docs(net): net-http construction-surface refinements (ADR-0034 amendments)

[NotAProfDev]

Closes #70. Follow-up to #66 (ADR-0034, Slice 0 PR 3).

A design-review/grilling session produced four refinements to the net-http construction surface. This PR records them — ADR-0034 gets a dated, append-only Amendments (2026-07-04) section (the landed decision text is untouched, per the repo's append-only ADR norm) and the construction-surface spec is updated. Docs only; the implied code changes land with their respective slices.

The four refinements

1. Absent RateLimit<K> directive fails closed (tightens ADR-0031 §3). Config-side totality already made "no local limit" an explicit classification; this closes the matching call-site hole — a request with no RateLimit<K> extension is now rejected fail-closed instead of silently defaulting to Scope::Global. "Global only" becomes an explicit Scope::Global; opt-out an explicit Scope::None. Removes the last silent path into IBKR's 429 → 15-min penalty box. (Lands with the RateLimit slice.)

2. Guarded releases the permit on a mid-stream error too. Rule is now the earliest of terminal frame, mid-stream error, or drop (was terminal-frame/drop). A /history transfer that dies mid-stream is as over as a clean end; a consumer holding the errored body for context must not pin one of the 5 concurrency permits. (Touches the Guarded body shipped in feat(net): AuthSource + Auth/SetHeaders layers + Guarded body (Slice 0 PR 3) #66 — code change lands as a small follow-up.)

3. async-lock re-grounded on the stated multi-backend goal. smol/async-std backends are a stated project goal, so async-lock (R) over tokio features=["sync"] (P) has a concrete payoff — a future non-tokio stack stays genuinely tokio-free — not a "thin margin". Option Q (a Timer-style semaphore trait) is unnecessary, not merely YAGNI: async_lock::Semaphore is already cross-runtime. (Doc-only.)

4. MockTimer relocates into a shared dev-only oath-adapter-net-mock crate, beside the Timer contract in net-api. MockTimer already ships in net-http-mock (feat(net): AuthSource + Auth/SetHeaders layers + Guarded body (Slice 0 PR 3) #66); this is a relocation, and it's time-critical — net-ws-mock already exists and its header says "MockTimer/MockSpawn arrive with the resilience slice (ADR-0033 §9)", which is imminent. Without the move that slice duplicates the clock or dev-depends a WS mock on an HTTP mock. (Crate lands when the resilience slice does.)

Verification

just ci green via the pre-commit and pre-push hooks (fmt, typos, clippy -D warnings, build, nextest). Docs-only diff: ADR-0034, the construction-surface spec, CHANGELOG [Unreleased].

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Updated design and ADR notes to reflect stricter request handling, earlier release of shared request resources on errors, and clarified authentication refresh behavior.
  • Clarified test setup guidance so HTTP and WebSocket mock tests share the same clock and dev-only mock support.

[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: 91a52cc8-5c91-4175-af25-77f7f41d8fd9

📥 Commits

Reviewing files that changed from the base of the PR and between 4adeac1 and 4fcee42.

📒 Files selected for processing (3)

• CHANGELOG.md
• docs/adr/0034-http-construction-surface-auth-guarded-boot-coverage.md
• docs/superpowers/specs/2026-06-30-net-http-construction-surface-design.md

---

📝 Walkthrough

Walkthrough

This PR updates CHANGELOG.md, ADR-0034, and the net-http construction-surface design spec with append-only amendments dated 2026-07-04: RateLimit fail-closed rejection, Guarded mid-stream permit release, async-lock multi-backend rationale, and MockTimer relocation into a shared oath-adapter-net-mock crate. No exported/public code entities are altered.

Changes

ADR-0034 amendments and spec documentation

Layer / File(s)	Summary
Changelog entry CHANGELOG.md	Adds an Added entry summarizing the four amendments.
RateLimit fail-closed behavior docs/adr/0034-...md, docs/superpowers/specs/2026-06-30-...md	Absent RateLimit<K> directive now rejected fail-closed instead of defaulting to Global; adds Scope stamping and RateKey::all() exhaustiveness enforcement guidance.
Guarded permit-release timing docs/adr/0034-...md, docs/superpowers/specs/2026-06-30-...md	Permit release now occurs at the earliest of terminal frame, mid-stream error, or drop; adds poll_frame/is_end_stream/size_hint forwarding guidance.
async-lock rationale and AuthSource coalescing docs/adr/0034-...md, docs/superpowers/specs/2026-06-30-...md	Re-bases async-lock selection on the multi-backend, non-tokio goal; adds AuthSource refresh-coalescing requirement.
MockTimer relocation docs/adr/0034-...md, docs/superpowers/specs/2026-06-30-...md	Documents moving MockTimer into a new dev-only oath-adapter-net-mock crate beside the Timer contract, shared by HTTP and WS mock setups.
ADR reconciliation, testing, and DoD updates docs/superpowers/specs/2026-06-30-...md	Updates reconciliation, testing assertions, and definition-of-done/open-questions to reflect the above amendments.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related issues

• feat(net): AuthSource + Auth/SetHeaders layers + Guarded body (Slice 0, PR 3) #64: Extends the same Guarded<B> permit-release semantics and ADR/spec documentation work.
• feat(net): RateKey + RateLimitConfig + boot-time coverage (Slice 0, PR 4) #69: Addresses the same fail-closed boot/build validation behavior for missing RateLimit<K> directives.

Possibly related PRs

• NotAProfDev/oath#56: Establishes the RateLimit/permit-lifetime semantics and layer-order rules (ADRs 0029–0031) that this PR's amendments refine.
• NotAProfDev/oath#58: Introduced the kernel Timer contract and transport split that this PR's MockTimer relocation builds on.
• NotAProfDev/oath#60: Introduced MockTimer in oath-adapter-net-http-mock, which this PR relocates into the shared oath-adapter-net-mock crate.

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 accurately summarizes the net-http docs refinements.
Linked Issues check	✅ Passed	The ADR and spec updates record the four refinements, and the Guarded code change is explicitly deferred to its later slice.
Out of Scope Changes check	✅ Passed	The diff stays within the documented ADR/spec/changelog follow-up and adds no unrelated changes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/net-http-construction-surface-refinements

---

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