refactor(net): harden compose — lock-in tests, must_use, self-contained docs, neutral param

[NotAProfDev]

What

Follow-up hardening of oath-adapter-net-api after the #121 vocabulary rename — all in the kernel crate, no behaviour change:

• Lock-in tests for compose.rs: the ordering invariant (first .layer() is outermost), Identity pass-through, Default == new(), and the zero-cost / ZST property. The ordering invariant was previously only compile-checked by assert-nothing doctests; the new tests execute and assert it (verified test-first — reversing the slotting convention makes them fail, then restoring makes them pass).
• #[must_use] on LayerBuilder::wrap() — assembling a stack and discarding the composed value is a bug; matches layer() / new().
• Self-contained public docs — dropped the internal ADR-0029 §N citations from compose.rs, lib.rs, timer.rs; the rustdoc now stands on its own.
• Neutral value type parameter S → T in compose.rs. S was tower's "Service" vestige; the kernel is transport-neutral, so the parameter carries no Service connotation. The HTTP layer impls keep S — there it is genuinely bounded S: Service<…>.

Verification

• just ci green (fmt, clippy -D warnings, tests, doctests, cargo doc -D warnings, deny, machete, gitleaks, actionlint, shellcheck)
• New compose::tests (5) + doctests (2) pass; the ordering test was shown to fail under a reversed slotting convention before passing under the correct one (real red → green)

Closes #122

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Improved layer composition behavior and consistency, including clearer handling of identity and empty builders.
• Bug Fixes
  • Added safeguards so wrapping composition is treated as something that should be used, helping catch mistakes earlier.
  • Locked in expected composition order and zero-sized behavior with tests.
• Documentation
  • Refreshed API docs and examples for clearer, self-contained guidance.
  • Removed internal reference text from public documentation.

[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: dc360e3d-2566-4209-b9de-79fd985fe6e0

📥 Commits

Reviewing files that changed from the base of the PR and between 10e30ca and e0282ef.

📒 Files selected for processing (4)

• CHANGELOG.md
• crates/adapter/net/api/src/compose.rs
• crates/adapter/net/api/src/lib.rs
• crates/adapter/net/api/src/timer.rs

---

📝 Walkthrough

Walkthrough

Renames the generic parameter of the Layer trait and its implementations from S to T in the oath-adapter-net-api compose module, adds a #[cfg(test)] unit test module for ordering/Identity/ZST behavior, and removes internal ADR citations from compose, lib, and timer documentation, with a CHANGELOG entry.

Changes

net-api compose polish

Layer / File(s)	Summary
Layer trait and generic parameter rename crates/adapter/net/api/src/compose.rs	Layer<S> trait, LayerBuilder::wrap, Identity, and Stack impls renamed generic parameter to T; module docs and doctest examples updated to match.
Compose ordering and ZST lock-in tests crates/adapter/net/api/src/compose.rs	New #[cfg(test)] module asserts outermost-first execution order, empty-builder passthrough, Identity no-op behavior, Default/new() equivalence, and zero-sized composition for Identity/LayerBuilder<Identity>/Stack<Identity, Identity>.
Self-contained rustdoc without ADR citations crates/adapter/net/api/src/lib.rs, crates/adapter/net/api/src/timer.rs, CHANGELOG.md	Crate-level and Timer doc comments reworded to remove ADR-0029 references; CHANGELOG documents the #[must_use] addition, new tests, and doc cleanup.

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

Possibly related issues

• refactor(net): make compose vocabulary transport-neutral (LayerBuilder / Layer::Wrapped) #120: Same compose API refactor covering LayerBuilder::wrap/Layer generic cleanup in oath-adapter-net-api.

Possibly related PRs

• NotAProfDev/oath#82: Shares the same Layer<T>/LayerBuilder::wrap() composition API surface affected by the generic parameter rename.

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 uses a valid Conventional Commits prefix and accurately summarizes the compose hardening work.
Linked Issues check	✅ Passed	The PR implements the requested docs cleanup, lock-in tests, and must_use change with no behavior change in the kernel crate.
Out of Scope Changes check	✅ Passed	No unrelated code changes are evident; the parameter rename and changelog note stay within the requested net-api polish scope.
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 worktree-test+compose-invariants

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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