docs(net): record net-ws resilience refinements (ADR-0033/0034)

[NotAProfDev]

Closes #79.

Append-only ADR amendments from a design-review pass over the landed WebSocket stack (ADR-0032 contract #65, ADR-0033 resilience). Decision text is untouched; each entry pins a construction-surface detail the ADR named but left open, or corrects a claim the shipped contract crate contradicts. Docs-only — no code, no dependency change; the code lands with each implementation slice.

ADR-0033 — new ## Amendments (2026-07-04), seven entries

1. Spawn seam — return-free, no trait 'static (mirrors Timer); cooperative shutdown (graceful WsSink::close(self), not abort mid-poll), awaitable-confirmed and bounded so a dead socket can't wedge it.
2. WsControl split — single-owner shutdown(self) + cloneable ReconnectTrigger for background force_reconnect (§8 makes it timer/staleness-driven; Arc+shutdown(self) is a hard conflict).
3. WsConfig validation — NonZero/Option tier-1 (illegal states unrepresentable, "off" = absence), WsConfigError on builder().build(); stack() stays config-infallible (fullest form of §9's reduction).
4. Classify seam over &WsError — and corrects §7's parenthetical: only Auth → Permanent is default-catchable; protocol-version-reject is Connection-kinded → Transient, so its permanence is hook-only.
5. Voluntary max_attempts exhaustion — orthogonal sticky exhausted field + #[non_exhaustive] LifecycleSnapshot, not a ConnState variant (health axis vs. policy axis).
6. §5 edge feed = tracing events, not a channel — with a recorded non-blocking-subscriber constraint (else the flap-storm burst reintroduces the actor stall §5 rejected).
7. MockSpawn home — net-ws-mock (Spawn is WS-only); MockTimer stays single-homed in net-mock, un-re-exported.

ADR-0034 — amendment 5

AuthSource is two per-transport traits (Request<Bytes>/HttpError vs Request<()>/WsError), not one "identical", Parts-based trait: HTTP body-signing (e.g. Binance HMAC) needs the whole request; the WS handshake is a bodyless GET. The shipped HTTP trait already abandoned Parts; this records why and rejects both the Parts unification and a generic AuthSource<B>.

The domain glossary is deliberately untouched — every term is implementation vocabulary, per both ADRs' Relationships sections.

Local just ci green (fmt, taplo, typos, clippy -D warnings, nextest, shellcheck pre-push).

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Updated architecture decision records with append-only amendments detailing websocket resilience refinements, including cooperative shutdown behavior, reconnect triggering, lifecycle reporting, stricter configuration validation, and revised error/exhaustion semantics.
  • Clarified transport-specific authentication guidance: HTTP authorization uses a modifiable request with a body (some schemes sign it), while websocket authorization uses a bodyless request shape, with corresponding per-transport error handling.

[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: 7e6ab88d-168b-4608-9827-1d9cbb7d6d2a

📥 Commits

Reviewing files that changed from the base of the PR and between fff6b8b and 5b656d5.

📒 Files selected for processing (2)

• docs/adr/0033-websocket-resilience-reconnect-actor-watch-lifecycle.md
• docs/adr/0034-http-construction-surface-auth-guarded-boot-coverage.md

✅ Files skipped from review due to trivial changes (1)

• docs/adr/0034-http-construction-surface-auth-guarded-boot-coverage.md

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

• docs/adr/0033-websocket-resilience-reconnect-actor-watch-lifecycle.md

---

📝 Walkthrough

Walkthrough

Two ADRs add append-only amendments dated 2026-07-04. ADR-0033 records seven WebSocket resilience refinements, and ADR-0034 records the per-transport AuthSource trait split.

Changes

ADR amendments

Layer / File(s)	Summary
Spawn and control-plane seam clarifications docs/adr/0033-websocket-resilience-reconnect-actor-watch-lifecycle.md	Clarifies the Spawn trait shape, cooperative shutdown, and the split between WsControl shutdown and ReconnectTrigger reconnect requests.
Config validation and failure classification docs/adr/0033-websocket-resilience-reconnect-actor-watch-lifecycle.md	Defines WsConfig construction validation and the Classify seam over &WsError, including the default permanent-failure rule.
Lifecycle exhaustion and tracing-based edge feed docs/adr/0033-websocket-resilience-reconnect-actor-watch-lifecycle.md	Defines max_attempts exhaustion as LifecycleSnapshot.exhausted and replaces the edge feed with non-blocking tracing events.
Mock crate layout and AuthSource trait split docs/adr/0033-websocket-resilience-reconnect-actor-watch-lifecycle.md, docs/adr/0034-http-construction-surface-auth-guarded-boot-coverage.md	Documents MockSpawn/MockTimer crate placement and clarifies AuthSource as separate HTTP and WS traits with different request and error types.

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

Possibly related PRs

• NotAProfDev/oath#56: Defines the HTTP transport contract and resilience-layer stack that these auth and error-shape decisions build on.
• NotAProfDev/oath#62: Introduces the initial ADR-0032/0033 WebSocket contract and resilience stack that this amendment set refines.
• NotAProfDev/oath#66: Implements the HTTP auth-layer details that ADR-0034 amends.

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 docs-only ADR refinements.
Linked Issues check	✅ Passed	The PR records the listed ADR-0033 and ADR-0034 append-only amendments and keeps decision text and code unchanged.
Out of Scope Changes check	✅ Passed	The change stays within the docs-only ADR amendment scope with no unrelated code or dependency edits.
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 docs/net-ws-resilience-refinements

---

_{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 `@docs/adr/0033-websocket-resilience-reconnect-actor-watch-lifecycle.md`:
- Around line 416-433: Resolve the inconsistency in the `WsConfig` construction
section by making it explicit whether `build()` is fallible or not. The current
wording conflicts between “stack()/build() stay config-infallible” and `build()
-> Result<WsConfig, WsConfigError>`; update the prose around `WsConfig`,
`build()`, and `WsConfigError` so validation flow is unambiguous and
implementers know exactly where construction-time checks happen. Keep `stack()`
described separately as infallible if that is intended, and align every sentence
in this subsection to the same lifecycle.

🪄 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: b2441e1e-4834-4173-a8a5-cda7057bbcff

📥 Commits

Reviewing files that changed from the base of the PR and between ca6b3eb and e62dc85.

📒 Files selected for processing (2)

• docs/adr/0033-websocket-resilience-reconnect-actor-watch-lifecycle.md
• docs/adr/0034-http-construction-surface-auth-guarded-boot-coverage.md