feat(net): Timeout resilience layer (Slice 1, PR 2)

[NotAProfDev]

Closes #77

Slice 1 PR 2 of the net-http resilience layers (spec: docs/superpowers/specs/2026-07-04-net-http-timeout-layer-design.md; ADR-0031 §1). Builds on the RateLimit layer (#76).

• Timeout<S, T> + TimeoutLayer<T> (net-api::Layer) — bounds the send (inner call → response), not the pacing-permit wait (ADR-0031 §1): a response-future race against Timer::sleep, returning HttpError::Timeout when the deadline wins (inner future dropped). Body-transparent — http::Response<B> returned untouched (no B: Body bound).
• RequestTimeout(Duration) per-request override extension — absent → the layer default (not fail-closed: a missing override has no fail-open pacing hazard, unlike RateScope).
• A streaming-body TimeoutBody is deferred — inert on IBKR's all-buffered responses; a clean additive follow-up when a streaming venue lands.

Runtime-neutral: generic over net-api::Timer, race via futures-util — no tokio/hyper. No new dependency. MockTimer-driven tests with inline service doubles (no MockClient — dev-dep cycle). ADR-0034 gains append-only Amendment #6.

Next: Slice 1 PR 3 — the Retry layer.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added an HTTP Timeout resilience layer with a configurable default deadline.
  • Added per-request RequestTimeout(Duration) override for deadline customization.
  • When the deadline elapses first, requests fail with HttpError::Timeout; successful responses pass through unchanged.

• Documentation

  • Updated the changelog and ADR to describe timeout semantics and how behavior differs for buffered vs streaming responses.
  • Added design/spec and implementation guidance for the timeout layer.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: d8ca1fbf-6816-42bb-8428-03c9af106ed9

📥 Commits

Reviewing files that changed from the base of the PR and between 7b76094 and 981ad67.

📒 Files selected for processing (1)

• crates/adapter/net/http/api/src/timeout.rs

🚧 Files skipped from review as they are similar to previous changes (1)

• crates/adapter/net/http/api/src/timeout.rs

---

📝 Walkthrough

Walkthrough

This PR adds a Timeout/TimeoutLayer middleware to oath-adapter-net-http-api, races the inner response future against a timer, supports per-request overrides, and wires the new API into exports, tests, and documentation.

Changes

Timeout Resilience Layer

Layer / File(s)	Summary
Design spec and implementation plan documents docs/superpowers/specs/2026-07-04-net-http-timeout-layer-design.md, docs/superpowers/plans/2026-07-04-net-http-timeout-layer.md	Adds the timeout-layer design spec and implementation plan, including scope, behavior, testing, rollout steps, and open questions.
Timeout/TimeoutLayer implementation crates/adapter/net/http/api/src/timeout.rs	Adds RequestTimeout, TimeoutLayer<T>, and Timeout<S, T> with deadline racing against Timer::sleep and HttpError::Timeout on timeout.
Timeout unit tests crates/adapter/net/http/api/src/timeout.rs	Adds MockTimer-based tests for override behavior, timeout handling, error pass-through, and zero-deadline ordering.
Crate exports and module wiring crates/adapter/net/http/api/src/lib.rs	Exposes the new timeout module, re-exports its public types, and updates the crate docs list.
CHANGELOG and ADR-0034 updates CHANGELOG.md, docs/adr/0034-http-construction-surface-auth-guarded-boot-coverage.md	Adds the Unreleased changelog entry and ADR amendment covering timeout scope, override semantics, and body transparency.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Possibly related PRs

• NotAProfDev/oath#56: Defines the resilience-layer placement and timeout semantics that this PR implements.
• NotAProfDev/oath#58: Introduces the Timer contract used by the new timeout middleware.
• NotAProfDev/oath#60: Adds the Timer/MockTimer infrastructure that the timeout tests use.

Suggested labels: enhancement

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title follows Conventional Commits and clearly describes the timeout resilience layer change.
Linked Issues check	✅ Passed	The implementation matches #77: send-phase timeout racing, RequestTimeout override, body-transparent responses, and no new dependency.
Out of Scope Changes check	✅ Passed	The changes stay within the timeout layer scope, including the expected API, docs, ADR, changelog, and tests.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/net-http-timeout

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@crates/adapter/net/http/api/src/timeout.rs`:
- Around line 23-31: The public tuple field on RequestTimeout is undocumented,
which triggers missing_docs under the workspace warning policy and then fails
clippy with -D warnings. Update RequestTimeout in timeout.rs by either adding a
field-level doc comment for the Duration payload or applying an explicit
#[allow(missing_docs)] to this type, keeping the existing type docs intact.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: fba55cfe-3950-4a90-b0fd-41c7bd2ef3ff

📥 Commits

Reviewing files that changed from the base of the PR and between f32fa41 and 7b76094.

📒 Files selected for processing (6)

• CHANGELOG.md
• crates/adapter/net/http/api/src/lib.rs
• crates/adapter/net/http/api/src/timeout.rs
• docs/adr/0034-http-construction-surface-auth-guarded-boot-coverage.md
• docs/superpowers/plans/2026-07-04-net-http-timeout-layer.md
• docs/superpowers/specs/2026-07-04-net-http-timeout-layer-design.md