alkhttp/docs/reviews/001-initial-implementation-review.md

# Review 001 — Initial Implementation Review (the 17-task build)

## Status

Verified, open for remediation.

## Scope

Consolidated code review of the full initial implementation of alkhttp —
the 17-task build that landed the server foundation, the WebSocket
byte-adapter and channels session, the gateway (dispatch + 6 routes +
publish), the reqwest client host, and the five adapters
(`from_openapi`, `from_jsonschema`, `from_wss`, `from_mcp`, `to_openapi`,
`to_mcp`) — produced against the tree at `4a825d3` ("full-surface
integration suite + docs sync + publish prep").

The review consolidates eight passes (one per subsystem: server core,
WebSocket, gateway, client host + forwarding core, from_openapi/from_jsonschema,
to_openapi/to_mcp, from_wss/from_mcp, and a cross-cutting hygiene pass)
plus a `cargo-llvm-cov` coverage analysis. The most consequential
findings (auth layering, `/schema` visibility, forwarding URL
construction, SSE parsing, `Notify` semantics) were re-verified directly
in source and, where noted, empirically with scratch harnesses outside
the repo. Findings that are cross-crate (alkcall-side) are flagged as
such.

## Baseline verification (this pass)

```
cargo test --all-features            → 256 passed, 0 failed (227 unit + 29 integration)
cargo clippy --all-features --all-targets -- -D warnings → clean
cargo fmt --check                    → clean
cargo doc --no-deps                  → 0 warnings
cargo check --no-default-features    → clean
cargo llvm-cov --all-features        → 93.86% lines, 91.75% functions, 94.23% regions
```

The suite is green and the coverage number is high, but the integration
tests all exercise happy paths over real I/O; the gaps are at the edges
(auth layering on merged routers, malformed/hostile upstreams, error
paths, projection-vs-runtime fidelity). That is exactly where the
findings below live.

## Verdict

- **The architecture held.** The gateway pattern (fixed endpoints, no
  per-op surface), the no-env-vars credential invariant, the
  Internal-by-default privilege model, the HTTP_<status> error-code
  discipline, the WS byte-adapter framing, and the feature matrix are all
  implemented as specified and largely well tested. There is no
  "cannot function end-to-end" defect of the kind alkcall Review 001
  found (P-01/C-01); the happy paths are genuinely exercised by
  integration tests over real sockets.
- **The defects cluster in four places:** (1) *auth/visibility at the
  seams* — `extra_routes` mounts without the bearer middleware, `/schema`
  leaks Internal ops, and the MCP `schema` tool skips the per-op ACL
  check; (2) *the outbound forwarding core* — URL construction
  (unencoded path params, `Url::join` semantics, no host validation),
  cross-host redirect credential leakage, retries on non-idempotent
  methods, missing timeouts, and an SSE parser that silently drops events
  at TCP chunk boundaries; (3) *projection fidelity* — the `to_openapi`
  document describes responses the gateway does not emit; (4)
  *WS/adapter robustness edges* — a lossy EOF notification that can hang
  `from_wss` calls forever, head-of-line stalls, and uncapped inbound
  buffering multipliers.
- **One borderline-critical defect:** `from_openapi` stack-overflows the
  process (abort, not a catchable panic) on valid, common,
  self-referential OpenAPI specs.

## Severity legend

- **[critical]** — the protocol cannot function end-to-end as committed;
  or a decided spec invariant is violated in a way that corrupts data or
  causes silent permanent state damage.
- **[major]** — a decided behavior is missing, wrong, or a real
  reliability hazard; works in the happy path but fails a spec-required
  edge case, or is a realistic security weakness.
- **[minor]** — drift, convention violation, dead code, or a doc/spec
  inconsistency with no correctness impact.

---

# Part A — Server core (adapter, auth, decoy, state)

## SRV-01 [major] — `extra_routes` are mounted without the bearer-auth middleware

**ADR drift:** ADR-046 §4 ("Custom routes carry the same auth middleware
by default; per-route opt-out is the deployment's choice").
**Verified:** YES (empirically). `src/server/adapter.rs:170-183` — the
`bearer_auth_middleware` is applied via `route_layer` *before* extra
routes are merged. axum's `route_layer` wraps only routes registered
*before* the call (verified against axum 0.8.9 `path_router.rs` and with
a scratch harness replicating `build_router`'s shape: the middleware ran
only for default-surface routes; an extra-route handler saw no stashed
identity).

Amplifier: `ResolvedIdentity` extraction never fails
(`src/server/auth.rs` — `Rejection = Infallible`), so a custom-route
handler using `ResolvedIdentity` compiles and silently receives `None`
on every request — indistinguishable from "caller sent no token". If a
custom handler treats `None` as anonymous-allowed, that is an
unauthenticated access path; at minimum the documented default (auth
applied) is not the implemented default. **Fix:** merge extras *first*
(or apply the layer after the merge), so the documented default holds and
opt-out remains the deployment's explicit choice.

## SRV-02 [major] — `/schema` discloses the full spec of `Visibility::Internal` operations

**ADR drift:** ADR-015 §2 / http-server.md ("Internal operations return
404 … an HTTP client cannot stub its toe on a path for an operation it
can't call").
**Verified:** YES. `src/gateway/routes.rs:120-137` — `schema_handler`
runs only `access_check_for_op`; it never applies the `is_internal_op`
pre-check that `/call` (:99), `/batch` (:147), `/subscribe` (:164), and
`/publish` (:240) all apply. Internal ops carry `AccessControl::default()`
(no restrictions), so the pre-check passes even for an unauthenticated
caller, and the `services/schema` handler returns the full spec
(visibility, input/output/error schemas, `access_control`) for any
registered name. `POST /call` on the same op correctly 404s (asserted in
`tests/full_surface.rs`). One unauthenticated `GET /schema?name=…`
returns the internal op's contract, defeating the invisibility invariant
on the discovery axis and bypassing the per-caller `/search` surface.
There is no test covering `/schema` on an internal op.

## SRV-03 [major] — `/mcp` reads the request body with no size limit (unbounded memory)

**Verified:** YES (mcp feature only). `src/server/adapter.rs:141-150`
nests rmcp's `StreamableHttpService`; the bearer middleware only stashes
identity. axum's 2 MiB `DefaultBodyLimit` applies to axum *extractors*;
the nested rmcp service consumes the raw body via `body.collect().await`
with no cap (verified against rmcp 1.8.0 `server_side_http.rs`), and
hyper imposes no body limit. A single `POST /mcp` with a multi-GB
chunked body is buffered entirely in memory; a handful of concurrent
requests OOMs the process. The gateway routes themselves are correctly
capped at 2 MiB (axum extractors). **Fix:** wrap the nest with an
explicit `DefaultBodyLimit` (or a body-limit layer) sized for MCP.

## SRV-04 [major] — No read/idle timeouts on the hyper connection driver (slow-loris surface)

**Verified:** YES. `src/server/adapter.rs:217-224` —
`HyperBuilder::new(TokioExecutor::new())` sets no timer, no
`header_read_timeout`, no keep-alive/h2 keep-alive knobs. hyper's h1
`header_read_timeout` (30 s default) is **silently ignored without a
Timer** (verified against hyper 1.11 `common/time.rs`: `Time::Empty` →
`warn!` + `None`). A client that opens a connection and dribbles partial
headers parks a task + buffers indefinitely; each `HttpAdapter::handle`
admits one such connection and there is no concurrency cap in this crate
(the accept loop is the consumer's). Mitigation is partly the transport
layer's job, but this crate configures none of the knobs hyper provides.

## SRV-05 [minor] — `with_decoy` consumes `extra_routes` via `.take()`

**Verified:** YES. `src/server/adapter.rs:104` —
`build_router(state, self.extra_routes.take())` leaves
`self.extra_routes == None`; a subsequent `.with_decoy(d2)` rebuilds the
router *without* the custom routes, silently. The builder state and the
live router diverge. Should be a clone (or build-once semantics with an
explicit error).

## SRV-06 [minor] — `RESERVED_PATHS` is exported but never enforced; per-method merges leak through

**Verified:** YES. `src/server/adapter.rs:38-49` — the constant has no
reader outside its re-export. Actual collision behavior: same-method
overlap **panics** in axum's `merge` (sanctioned by ADR-046 §3's
"construction panics/warns"), but a *different* method on a reserved path
(e.g. custom `POST /search`) silently merges in — served on a reserved
path, and (per SRV-01) without auth middleware. The "default wins" claim
of ADR-046 §3 is false for the per-method case, and the exported
constant doesn't deliver the contract its export implies.

## SRV-07 [minor] — Stealth-mode fidelity gap: 405 responses bypass the decoy

**Verified:** YES (empirically). The decoy is only the router
`fallback` (`src/server/decoy.rs:24-43`); a request that matches a route
but not a method (e.g. `OPTIONS /search`, `DELETE /healthz`) returns
axum's bare 405 — no body, **no `Server: nginx` header** — so a single
probe distinguishes alkhttp from nginx in decoy deployments. Real nginx
sends its `Server` header on 405s.

## SRV-08 [minor] — Decoy static-server path decoding bugs

**Verified:** YES. `src/server/decoy.rs:106-127` — in a URI path `+` is
a literal plus (only query strings form-decode it), but `percent_decode`
maps it to space (a file named `a+b.html` becomes unreachable); and
percent-decoding maps each decoded byte to `char`, so `%C3%A9` yields
mojibake (`é`) instead of `é` — any non-ASCII filename is unreachable.
No traversal impact (the `Component` walk at :83-94 rejects `..`; also
verified `%00` fails the read). Related, same file: `resolve_static_path`
uses blocking `is_dir()`/`is_file()` syscalls on the async path
(:97-101) — a convention violation; the read itself correctly uses
`tokio::fs::read`.

## SRV-09 [minor] — `/openapi.json` error path echoes internals and rebuilds the doc per request

**Verified:** YES. `src/server/adapter.rs:250-254` — 500 body is
`format!("failed to serialize gateway spec: {e}")` (raw serde error
echoed to unauthenticated callers), and the handler rebuilds + serializes
the whole projection on every request (no caching) — cheap DoS
amplification. Companion finding: `src/adapters/to_openapi.rs:67` uses
`.expect("to_openapi always emits a valid OpenAPI document")` on this
request-triggered path — the only unguarded `expect` reachable from a
route handler (convention violation; also T-11).

## SRV-10 [minor] — WS upgrade hardcodes `NoCap`; doc claims deployers can pass a stricter policy but there is no injection point

**Verified:** YES. `src/websocket/upgrade.rs:28-29` says the assembly
layer can pass a stricter channel policy, but `:120` hardcodes
`Arc::new(NoCap)` and `HttpAdapter` offers no parameter. alkcall
documents `NoCap` as the explicit *opt-out* (the default is 256/identity).
One authenticated WS client can open unbounded data channels on one
connection. Minor (post-auth), but the comment misleads and the lever is
missing. Fold-in: the WS upgrade route resolves the bearer token twice
(router-wide `bearer_auth_middleware` + `ws_bearer_auth`) — harmless
today, but a provider with token-use side effects double-counts.

---

# Part B — WebSocket subsystem (byte adapter, upgrade, session)

## WS-01 [major] — Single demux loop: one dribbled chunk stalls all channels indefinitely

**Verified:** YES. The WS read task hands whole messages to `AsyncRead`
(`src/websocket/byte_adapter.rs:110-126`); alkcall's demux then does
`read_exact` on header + payload with **no read timeout**, and
`route_payload` awaits the per-channel bounded sender. A peer sends
header `[ch=0][len=16 MiB]` then dribbles one byte per minute: the server
holds the 16 MiB allocation forever and every outstanding channel-0
call/subscription on that connection hangs — Once-calls only at the 30 s
sweeper, `Sub`/`Pub` pendings (registered `timeout: None` on the client
side) hang until the socket dies. Memory is bounded; availability is not.
There is no read-idle timeout anywhere on the WS path. **Fix:** an idle
timeout on the WS read (close with 1001 on staleness) bounds the stall;
consider it a deployment knob.

## WS-02 [major] — `Notify::notify_waiters` is lossy — `read_eof` can be missed, in-flight calls hang forever

**Verified:** YES. `src/websocket/byte_adapter.rs:138-139` (and :319 for
the tungstenite twin) fires `read_eof.notify_waiters()`, which wakes only
*already-registered* waiters and stores no permit. The consumer
(`src/adapters/from_wss.rs:156-166`) spawns its drop-monitor *after*
session setup; if the read task hits EOF before the monitor first polls
`Notified`, the signal is lost. Because `import()` does
`std::mem::forget(session)` (`from_wss.rs:193`), the `close_rx` fallback
never fires either → the monitor never runs `fail_all` → imported-op
calls in flight hang (Once-calls recover only at the 30 s sweeper, if a
sweeper runs at all on this path — see CON-02; `Sub`/`Pub` pendings hang
forever). The module doc at `from_wss.rs:111-113` promises the opposite.
**Fix:** a `watch` channel / `CancellationToken` / permit-storing
`notify_one`, or a checked `AtomicBool`.

## WS-03 [major] — No data-channel wiring: ADR-067's browser data channels are not implemented

**ADR drift:** ADR-067 (websocket.md §"Data channels for browsers"),
ADR-048's connection-local overlay contract.
**Verified:** YES. `src/websocket/upgrade.rs:40,62-98` hands the **base**
registry to `install_channel_zero` and runs
`Dispatcher::run_loop_single_stream` over it; there is no
`ChannelCore`/`register_openable`/`ChannelOperations` wiring anywhere in
src/ (grep-verified). A browser can never open a data channel — the exact
capability ADR-067 says the channels design exists to provide; and
ADR-048's bidirectionality (hub calls browser-registered ops via the
connection-local overlay) is unused. This may be a deliberate v1 cut
(the WS tasks scoped channel-0 dispatch only), but the spec promise and
the implementation have not been reconciled in writing — either wire it
or file the OQ / amend the ADR. (Related: the overlay tests in
`tests/ws_overlay_ops.rs` cover the dispatcher's overlay mechanics over
duplex, not browser-opened data channels.)

## WS-04 [minor] — Write-side chunk parser does no length validation

**Verified:** YES. `src/websocket/byte_adapter.rs:161-163` (twin at
:343-345) parses the outbound length field with no `MAX_CHUNK_LEN` check
and no error path. Today the only producer is alkcall's mux (capped at 16
MiB per payload), so the parse always re-syncs; but if any future
producer writes non-chunk-framed bytes, the parser silently waits to
accumulate `8 + len` (up to ~4 GiB) from misaligned offsets — permanent
silent corruption plus a huge `pending` allocation. A one-line validation
that fails the stream would make the invariant loud.

## WS-05 [minor] — Write-task `pending` buffer is unbounded in bytes (~1 GiB worst case per connection)

**Verified:** YES. `byte_adapter.rs:143,155` — slot count is bounded (64
`WriteMsg`s) but bytes are not; each message is up to 16 MiB, so a slow
WS sink plus a large streaming publish buffers up to ≈64 × 16 MiB plus a
partial chunk before backpressure engages. Steady state is small; the
bound is worth a byte cap since `pending` is the only unbounded
accumulator on the write path.

## WS-06 [minor] — Inbound per-connection memory bound is 64 slots × 64 MiB ≈ 4 GiB

**Verified:** YES. `READ_SLOTS = 64` bounds messages, not bytes
(`byte_adapter.rs:56`); the plan's "~1 MiB" cap applies only to the write
side (`WS_MESSAGE_CAP`). Inbound WS messages are capped only by
axum/tungstenite's default `max_message_size` (64 MiB); neither
`WebSocketUpgrade::max_message_size` nor `max_frame_size` is configured.
A peer flooding 64 MiB binary messages pins up to ~4 GiB whenever the
demux drains slower than the socket delivers (e.g. during the WS-01
stall). Set an explicit message-size cap consistent with the plan.

## WS-07 [minor] — `poll_shutdown` does not close the WS sink; the documented close mapping is not the behavior

**Verified:** YES. `byte_adapter.rs:269-276` vs the module doc at :25-28
— `poll_shutdown` drops a **fresh clone** of `write_tx` while the
original stays in the struct, so the channel never closes and the
trailing `ws_sink.close()` doesn't run at shutdown time. In the server
path the teardown cascade still completes (traced end-to-end), so REQ-CH-01
sentinels do flush, but (a) the Close frame is deferred to an unrelated
cascade step, and (b) any consumer that calls `shutdown()` and keeps the
stream alive (the `from_wss` path does — it forgets its session) never
emits a WS Close frame at all. The comment describes intent, not
behavior.

## WS-08 [minor] — `_pumps` detached in the server session; no forced-teardown lever

**Verified:** YES. `upgrade.rs:36` drops `WsPumps` immediately — fine in
the normal path (cascade traced), but `WsPumps::abort()` (the documented
"forced teardown" lever) is never callable on the server path, so a
stuck session (WS-01's dribble) can only be evicted at the TLS/socket
layer outside this crate.

## WS-09 [minor] — No per-connection or global cap on WS sessions

**Verified:** YES. The upgrade route has bearer auth (good) but no
concurrency limit, no idle timeout, and each session holds ≥ 4 spawned
tasks plus buffers until the socket dies. Post-auth DoS only, but the
assembly layer cannot add a cap because the built-in route is built
inside `HttpAdapter` (extra routes only add routes; middleware can't wrap
this route from outside). A semaphore in `ws_upgrade_handler` is the
cheap lever.

## WS-10 [minor] — Dispatcher/mux tasks outlive a failed session task

**Verified:** YES. `upgrade.rs:65-97` spawns the dispatcher loop
detached; if the session future is dropped/aborted, the spawned tasks
keep the `ChannelManager`/`MuxHandle` alive, which keeps the writer (and
the WS sink) alive — the socket then closes only when the *peer* goes
away. Self-healing in practice; a leak window tied to peer behavior.

## WS-11 [minor] — ~60 lines of pump logic duplicated between the axum and tungstenite paths

**Verified:** YES. `byte_adapter.rs:119-180` vs `:299-364` — read task,
write task, and close handling are copy-pasted with only the message
enums differing, while the module doc claims "one implementation, both
directions" (:30-31, :279-284). Any fix (WS-04, WS-06) must be applied
twice; factor the pump bodies over a generic sink/stream of messages.

## WS-12 [major, cross-crate] — alkcall demux `TooLarge` skip allocates up to 4 GiB from an 8-byte peer header

**Location:** alkcall `src/channels/adapter.rs:144-148` (`let mut discard
= vec![0u8; length as usize];`). **Verified:** YES. Any header with
`length > 16 MiB` reaches this arm; the skip buffer is allocated *before*
reading. Via the WS path this is trivially reachable by any authenticated
browser (8 bytes of header); K connections × `[len = 0xFFFFFFFF]` +
dribble → OOM. Correct sync recovery (verified by alkcall's own resync
test), wrong memory shape — stream-skip with a bounded buffer. Not an
alkhttp defect, but it detonates through `byte_adapter.rs`'s read path;
fix on the alkcall side.

---

# Part C — Gateway (routes, dispatch, error)

## GW-01 [major] — `/publish` skips `publish_schema` validation that the wire path enforces

**Verified:** YES. `src/gateway/routes.rs:257-276` parses each NDJSON
line and feeds the stream straight to `invoke_sink`;
`OperationRegistry::invoke_sink` performs only not-found/visibility/ACL/
handler-kind checks — `publish_schema` validation lives in alkcall's wire
`Dispatcher` only. A Pub op that registers `publish_schema` receives
attacker-controlled arbitrary JSON over HTTP while the same op over the
call protocol aborts invalid chunks. Handlers written against the
validated-wire guarantee get a transport-dependent invariant. **Fix:**
validate in the route (or move validation into the shared
`invoke_sink` spine so both transports enforce it).

## GW-02 [major] — Per-identity `GET /search` / `GET /schema` responses carry no cache headers

**Verified:** YES (grep: no `Cache-Control`/`Vary` anywhere in src/).
`/search` and `/schema` are GETs whose bodies are per-caller
(AccessControl-filtered, 200 vs 403 depending on the bearer). With no
`Cache-Control: no-store` (or at least `Vary: Authorization`), shared
caches/CDNs are permitted to serve caller A's authenticated response to
caller B — leaking the op inventory and, compounded with SRV-02, full
schemas. Standard mitigation; matters for any deployment behind a cache.

## GW-03 [minor] — `INVALID_OPERATION_TYPE` maps to 500 on `/call`//`/batch` but 400 on `/publish`

**Verified:** YES. `src/gateway/error.rs:17-21` lists only five protocol
codes; `INVALID_OPERATION_TYPE` falls through to `_ => 500` (a
client-fault class reported as server-fault), while `routes.rs:288-297`
maps the identical condition to 400 on `/publish`. Pollutes error-rate
alerting and retry logic; undocumented drift in http-server.md's mapping
table.

## GW-04 [minor] — SSE error events are not terminal; the stream continues after an `Err`

**Verified:** YES. `routes.rs:299-313` maps each envelope independently
and keeps going; the documented contract (http-server.md:219-223) and the
wire dispatcher both treat an `Err` as terminal ("the stream ends after
it"). A streaming handler that yields `Err` and then yields again makes
HTTP serve `event:error` followed by more `data:` events, while the same
op over WS emits `call.error` and stops — two transports disagree about
stream semantics. **Fix:** `take_while` on `Ok` (emit the error, end the
stream).

## GW-05 [minor] — The 30 s `DEFAULT_TIMEOUT` deadline is set but never enforced

**Verified:** YES. `src/gateway/dispatch.rs:34,165` records a deadline;
nothing on the gateway path ever enforces it (`registry.invoke` does not
wrap the handler in a timeout; the only real timeout lives client-side in
alkcall's pending map). A hung handler holds the HTTP request open
indefinitely. Either enforce (`tokio::time::timeout` around the invoke
for Once ops) or remove the dead metadata.

## GW-06 [minor] — `/publish` buffers the entire NDJSON body before dispatch

**Verified:** YES. `routes.rs:187-191` takes `axum::body::Bytes` and
materializes all chunks before `invoke_sink` (:257-266), contradicting
ADR-068 step 4 ("stream each NDJSON line") and the module doc's
disconnect claim (:182-183). Mitigated by the 2 MiB body cap, so memory
is bounded — but there is no true streaming, no backpressure, and a
silent 2 MiB-max publish semantic difference vs the wire Pub path. The
vacuous test at `routes.rs:1572-1583` (see HY-13) implicitly concedes
the buffering.

## GW-07 [minor] — `Retry-After` is never emitted on any live gateway error path

**Verified:** YES. The header machinery lives in
`call_error_to_http_response` (`error.rs:61-75`), but the main gateway
error path builds responses by hand (`routes.rs:319-333`) without it;
the only production call site is `not_found_response`, where `retryable`
can never be true. A retryable `HTTP_429`/`HTTP_503` from a handler
reaches callers with **no** `Retry-After`, while http-server.md promises
the mapping.

## GW-08 [minor] — `/batch` has no cap on the number of operations

**Verified:** YES. `routes.rs:139-157` dispatches each entry
sequentially; the only bound is the 2 MiB body. A maximal batch of cheap
ops occupies a worker for the sum of all handler latencies (30 s
"deadline" unenforced per GW-05). Also note results are purely
positional — `CallRequest` has no caller-supplied id field.

## GW-09 [minor] — `/batch` internal-op entries emit `request_id: null` while dispatched entries carry a UUID

**Verified:** YES. `routes.rs:358-365` vs :335-340 — mixed envelope
shape within one response body; clients correlating on `request_id` see
two shapes.

## GW-10 [minor] — `/publish` first line without a `chunk` key silently publishes `Value::Null`

**Verified:** YES. `routes.rs:213` — `unwrap_or(Value::Null)`. A first
line carrying only `{"operation": "…"}` publishes a null chunk 1 instead
of failing with `INVALID_INPUT` (the class of error the route does
reject for a missing `operation` at :216-226). Since null is also a
legitimate payload, client error is indistinguishable from intent.

## GW-11 [minor] — `/publish` runs four registry lookups + ACL check that `invoke_sink` then repeats

**Verified:** YES. `routes.rs:240-255` vs alkcall
`registration.rs:289-344` — duplicated enforcement (harmless because
dispatch re-checks and wins, but pure duplication, and inconsistent with
`/call`//`/batch`, which deliberately skip the pre-check and rely on the
registry).

## GW-12 [minor] — ACL denial on `/subscribe` surfaces as HTTP 200 + SSE `event:error`; on `/call` the same denial is 401/403

**Verified:** YES. `subscribe_handler` returns `Sse` (always 200);
pre-dispatch failures (unknown op, internal op, ACL) stream as
`event:error` frames (tests at `routes.rs:1066-1132` assert the 200s).
Defensible per ADR-049 (errors-on-the-stream) but a status-fidelity
asymmetry across the "sole invoke path" that the docs don't call out —
and standard HTTP monitoring never sees auth failures on `/subscribe`.
(See also PRJ-05 — the OpenAPI doc doesn't document this either.)

## GW-13 [minor] — SSE stream has no keep-alive/heartbeat

**Verified:** YES. `routes.rs:172` — `Sse::new(stream)` with no
`.keep_alive(...)` and no `retry:` field. Subscriptions are specced as
unbounded, so quiet-but-alive streams are normal state; typical LB/proxy
idle timeouts (30-60 s) will silently terminate them.

## GW-14 [minor] — Stale module doc: `/publish` claimed to be "a separate module"

**Verified:** YES. `routes.rs:1-9` says `/publish` (ADR-068) "is a
separate module"; `publish_handler` and all its helpers live in this
same file (:184-297). (Same staleness echoed in AGENTS.md §7's
"5 gateway endpoints" framing — ADR-068 made it 6.)

---

# Part D — Outbound forwarding core + client host

## FWD-01 [major] — Path-parameter values substituted without percent-encoding; `Url::join` normalizes dot-segments

**Verified:** YES (empirically). `src/adapters/forward.rs:56-71,
133-141` — `value_to_path_segment` returns the raw string; `Url::join`
then normalizes `..`. Verified: template `/repos/{owner}/{repo}/issues`
with `{owner} = "../../admin"` → `https://api.example.com/admin/...`
(traversal); `{owner} = "a?admin=true"` → the `?` splits the URL and
discards the template tail into query semantics; `#` fragments inject
likewise. A value containing a *later* placeholder also gets expanded by
that later key (iterative substitution over a BTreeMap-ordered input).
Attack: peer-controlled input into a path param escapes a path-scoped
prefix on the upstream (cross-tenant IDOR), **with the operation's
injected credentials attached**. Contrast: the query path *is* correctly
encoded via `query_pairs_mut`. **Fix:** percent-encode each segment
(`utf8_percent_encode` with a path-segment set) before substitution, and
reject/encode `?`/`#`.

## FWD-02 [major] — `base_url` path prefix silently dropped; no scheme/host validation of the effective URL (SSRF)

**Verified:** YES (empirically). `forward.rs:74-78` — `Url::join`
resolves against the base *directory*: `base_url = "https://api.openai.com/v1"`
+ template `/chat/completions` → `https://api.openai.com/chat/…` (the
`/v1` is lost). Every test in both adapters uses an origin-only
`base_url`, so the suite can't see it. Worse: a path key that is an
absolute URL (`https://169.254.169.254/…`, `http://localhost:9090/…`)
replaces scheme+host entirely — verified — and reqwest only rejects
non-http(s) *schemes* at send time, so any http/https host is allowed.
Credential injection happens after URL construction, so a
spec-controlled absolute path sends the namespace's credentials to an
arbitrary host. Today specs are assembly-layer-supplied (trusted per
ADR-066), which keeps this out of critical territory — but nothing
enforces that trust boundary (no allowlist, no post-join host-equality
check). **Fix:** require the joined URL to keep the base host (fail
loudly otherwise), require https (or explicit opt-out), and handle the
base-path-prefix case (append to the base path, not the origin).

## FWD-03 [major] — Custom credential headers follow cross-host redirects (reqwest default policy)

**Verified:** YES. `src/client/http_client.rs:119-172` never sets
`.redirect(...)`, so reqwest's default (`limited(10)`) applies; its
cross-host scrub removes only `Authorization`/`Cookie`/`cookie2`/
`Proxy-Authorization`/`WWW-Authenticate` (verified in reqwest 0.13
source). `HttpAuthScheme::ApiKey { header_name }` credentials
(`forward.rs:110-117`) and all `default_headers` are not in that list.
Attack: an upstream open redirect (or DNS hijack) 302s to an attacker
host → the API key is delivered intact. **Fix:** an explicit redirect
policy — `none`, or a limited same-host policy — for the shared client.

## FWD-04 [major] — Non-idempotent requests (POST) are retried; retry budget has no total-duration cap

**Verified:** YES. `http_client.rs:165-167` installs
`RetryTransientMiddleware` with the default strategy, which classifies
5xx/408/429/timeout/connect-error as retryable **regardless of method**
(verified in reqwest-retry 0.9.1; `is_incomplete_message` is explicitly
retried). A POST whose backend committed the write then returned 500 (or
dropped mid-response) is re-sent up to 3 times → duplicate side effects.
Backoff sleeps (default `max_retry_interval` 30 min each) occur outside
reqwest's per-attempt timeout, and `ExponentialBackoff::build_with_max_retries(3)`
has no total-duration cap → total wall time unbounded from the caller's
perspective. **Fix:** skip retries for non-idempotent methods (or make
it a per-adapter policy), and cap total retry duration.

## FWD-05 [major] — No request/connect timeout by default; `Retry-After` deadlines uncapped → unbounded hangs

**Verified:** YES. `HttpClientConfig::default()` sets
`request_timeout: None` and no connect timeout exists anywhere
(`http_client.rs`); reqwest applies no timeout unless configured.
`retry_after.rs:27-37` accepts any u64 seconds with no maximum, and
`maybe_sleep_for` sleeps before *every* request to that URL. A hostile
backend answering once with `429` + `Retry-After: 315360000` (~10 years)
stalls every subsequent call to that URL indefinitely. Overflow is safe
(`checked_add` → `None`), and zero/past deadlines are filtered — the gap
is the missing cap and the missing default timeout. **Fix:** default
request timeout (the gateway's 30 s deadline is the natural anchor), a
connect timeout, and a `Retry-After` ceiling.

## FWD-06 [major] — SSE parser drops events at TCP chunk boundaries and corrupts split multi-byte UTF-8

**Verified:** YES (empirically with the verbatim parser). `forward.rs:
409-417` retains only the *last* line of each chunk as `remaining`,
discarding any pending multi-line `data_buffer`; a chunk ending exactly
at `data: …\n` (blank line not yet arrived) silently loses the event
(verified: chunks `"data: {\"n\":1}\n"` + `"\ndata: {\"n\":2}\n\n"`
yield only event 2). Single-chunk delivery (as in the tests) works,
which is why the suite passes. Also `String::from_utf8_lossy` per chunk
(:357) corrupts multi-byte characters split at chunk boundaries → JSON
parse failure → event degraded to a raw string. Plus the trailing
partial line has no length cap (unbounded buffering) and EOF with a
pending event drops it (SSE says dispatch at EOF). For a subscription
forwarder this is silent data loss with no error signal. **Fix:** an
incremental byte-level parser carrying state across chunks.

## FWD-07 [major] — Vendor JSON content types (`application/*+json`) decoded as per-byte arrays; no response size cap

**Verified:** YES. `forward.rs:236` — `content_type.contains("application/json")`
misses `application/vnd.api+json`, `application/hal+json`,
`application/problem+json`, which fall to the binary branch and return
`Value::Array` of one `Number` per byte. There is **no response size
limit** on any read path (`response.json()/.text()/.bytes()`), so a
hostile upstream controls caller-side memory. `forward_stream` never
checks content-type at all (a 200 HTML response parses to an empty
stream with no error). **Fix:** match on the mime essence type
(`application/.*+json` suffix semantics), cap response sizes, and treat
non-SSE content on a Sub op as an error.

## FWD-08 [minor] — Invalid credential values silently produce unauthenticated requests

**Verified:** YES. `forward.rs:104-126` (and :87-94 for
`default_headers`) — all auth arms drop the header on
`HeaderValue::try_from` failure with no error, no log. A credential with
a control character (or a typo'd `header_name`) means the request goes
out unauthenticated and the caller only sees the upstream's eventual
401. (No leak risk — nothing is logged; verified no tracing calls in the
forwarding path.) A loud error would surface misconfiguration at call
time instead.

## FWD-09 [minor] — Blocking `std::fs::read` in `build_client` (reachable via public `reload`)

**Verified:** YES. `http_client.rs:129,144,150` — small-file reads on
the construction path; `SharedHttpClient::reload` (:111-116) is public
and documented as hot-reload, so an async-context caller does blocking
I/O on the async path (convention violation; one-shot small reads, so
impact is a stalled worker). `tokio::fs::read` (or spawn_blocking) is
the cheap fix.

## FWD-10 [minor] — Upstream error bodies discarded

**Verified:** YES. `forward.rs:215-227` (and :333-346 for the stream
twin) — on non-2xx the body is dropped; the surfaced message is only
`"HTTP {status}: {reason}"`. Upstream diagnostics (validation details,
rate-limit info) never reach the caller, and unconsumed bodies hinder
connection reuse. The `HTTP_<status>` mapping itself is correct.

## FWD-11 [minor] — `Retry-After` bookkeeping keyed on pre-redirect URL; eviction order inverted; thundering herd on wake

**Verified:** YES. `retry_after.rs:127-130` records under `req.url()`
(pre-redirect), so a redirector's rate limit pollutes the origin's entry;
eviction drops the *earliest* deadline (preferentially discarding
soonest-actionable entries while retaining year-long ones, compounding
FWD-05); on expiry all concurrent waiters wake simultaneously (no
jitter).

## FWD-12 [minor] — Duplicated helpers, dead-ish parameter, non-atomic reload stores

**Verified:** YES. `value_to_path_segment` and `value_to_query`
(`forward.rs:133-151`) are byte-identical; `forward`'s `op_type`
parameter only toggles `ACCEPT` (if a Sub were ever routed here, the
`text/` branch would buffer the whole SSE stream — currently
unreachable but inviting misuse); `reload` performs two separate
`ArcSwap::store` calls (a reader can observe new config with the old
client); `forward.rs:197` `unwrap_or_else(|_| "null")` masks an
(unreachable) serialization failure by sending a null body.

---

# Part E — from_openapi / from_jsonschema / openapi_spec

## OAI-01 [major → borderline critical] — Unbounded `$ref` recursion → stack overflow (process abort) on valid, common specs

**Verified:** YES (empirically). `src/adapters/openapi_spec.rs:199-221`
— `resolve_refs_recursive` recurses with no cycle detection and no depth
budget; a self-referential component (`{"$ref":"#/components/schemas/Node"}`
inside Node — trees, linked lists, cursor pagination: common, *valid*
OpenAPI) recurses until the stack is exhausted. The 128-level parse
limits of serde_json/yaml_serde don't help (each `$ref` hop re-enters
from a fresh clone). Verified empirically: the exact algorithm against a
recursive schema → `thread has overflowed its stack; fatal runtime
error` → abort. Not a catchable panic; `import()` kills the whole
process (startup crash-loop, or remote DoS if specs are ever
runtime-refreshed/peer-supplied). **Fix:** a depth budget + visited set,
erroring cleanly on cycles.

## OAI-02 [major] — No input-schema enforcement: extra keys become upstream query params; `body` sent verbatim

**Verified:** YES. `forward.rs:60-72` — every input key that isn't a
path placeholder (and isn't literally `"body"`) is appended as a query
parameter regardless of the registered `input_schema`; neither the
registry nor the adapter validates input against the schema at call
time (ADR-066's "input schema validation before send" is not
implemented anywhere). A composed facade forwards peer input; a peer
adds `"debug": "true"` or `"impersonate_id": "…"` and it reaches the
upstream. Violates the schema-scoped contract `/schema` advertises.

## OAI-03 [major] — OpenAPI `in: header` / `in: cookie` parameters are silently sent as query parameters

**Verified:** YES. `openapi_spec.rs:35-40` records `in_` (dead field —
never read); `build_request` has no header-parameter branch. Upstream
auth/trace headers never arrive (confusing failures), and values that
were specified as headers — which don't normally land in upstream
access logs — end up in query strings, which typically do.

## OAI-04 [major] — Parameter-level and requestBody-level `$ref`s are silently dropped, producing broken operations

**Verified:** YES. `openapi_spec.rs:236-262` — a parameter entry of the
form `{"$ref": "#/components/parameters/Id"}` (extremely common in real
specs) has no `name`, is silently skipped, and never reaches
`resolve_refs_recursive`; same for `requestBody: {"$ref": …}`. Only
`components/schemas` is indexed (:162-174). Result: the op registers
with `{id}` in the template but `id` absent from the schema; at call
time the placeholder is substituted with the *literal* `{owner}` text
and percent-encoded (`%7Bowner%7D`) — a well-formed request to a
nonsense path, with credentials attached. Silent misbehavior, no error
at import or call time.

## OAI-05 [minor] — Operation-ID collisions silently overwrite registrations

**Verified:** YES. `from_openapi.rs:51-65,160` — generated IDs collide
by construction (`/x/{id}/y` and `/x/y` both → `get_x_y`); alkcall's
registry `insert` silently replaces; `import()` doesn't detect
duplicates within its own batch. One op silently shadows another;
`/search` shows fewer ops than the spec declares.

## OAI-06 [minor] — Unsupported OpenAPI features degrade silently

**Verified:** YES. `"default"`/wildcard response keys become
`ErrorDefinition { code: "HTTP_0", http_status: None }` — entries that
never match a real status (`from_openapi.rs:142-145`); `trace` ops are
silently skipped (`openapi_spec.rs:12-13`); `servers` overrides,
parameter `style`/`explode`, and array/object query serialization are
unsupported and silent (arrays become `"[1,2]"`); a `default`-declared
SSE stream is missed by `detect_op_type` and would return one giant
text string. None fail loudly at import; each produces an op that
misbehaves only at call time.

## OAI-07 [minor] — Magic `"body"` input key collides with spec parameters named `body`

**Verified:** YES. `from_openapi.rs:96-102` + `forward.rs:66-67` — a
declared parameter named `body` is overwritten by the requestBody schema
and diverted to the request body at call time, unreachable as the
query/path/header parameter the schema advertised.

## OAI-08 [minor] — Guarded `expect`s in `openapi_spec` lib code

**Verified:** YES. `openapi_spec.rs:144,170` — `expect("paths is object")`
etc., each immediately preceded by an `is_object()` check (unreachable
today, but AGENTS.md §2 says no `expect` outside tests; `if let` costs
nothing).

## OAI-09 [minor] — `from_jsonschema` defers all config validation to call time

**Verified:** YES. `from_jsonschema.rs:36-51` — malformed `method`/
`path_template`/`base_url` surface as `CallError::internal` on first
invoke rather than at construction. Also doc drift: the module doc says
"`Internal` by default" (:8) but the adapter passes the caller's
`OperationSpec` through verbatim — `from_openapi` hardcodes
`Visibility::Internal` (:169, tested); `from_jsonschema` does not.

---

# Part F — Projections (to_openapi, to_mcp)

## PRJ-01 [major] — `/search` 200 response schema is wrong twice (missing envelope wrapper, wrong item fields)

**Verified:** YES. `to_openapi.rs:100,335-351` documents
`{operations: [{name, description}]}`; the actual body is the envelope
wrapper (`{request_id, result, output}` — proven by the routes tests
reading `body.output`) and items carry `name`/`namespace`/`op_type` with
**no** `description`. The summary "Returns names + descriptions" is
false. Clients generated from this doc are broken on day one.

## PRJ-02 [major] — `/schema` 200 response schema is wrong (missing wrapper; omits `op_type`/`visibility`/`access_control`/`channel_open`/`publish_schema`)

**Verified:** YES. `to_openapi.rs:124,353-364` documents the bare spec;
the runtime body is the envelope with `spec_to_json`'s fuller inner
object. Same wrapper-miss as PRJ-01.

## PRJ-03 [major] — Documented 400 `INVALID_INPUT` doesn't match the runtime mapping (422) or axum's rejection bodies

**Verified:** YES. The doc maps 400 for `/call`//`/batch`//`/schema`;
the runtime mapper is `INVALID_INPUT → 422` (`error.rs:51`), and axum's
extractors reject malformed bodies with plain-text 400/415/422 bodies
that have none of the documented `{code, message, retryable}` shape.
The doc has no 422 response at all. `/publish` *is* correct here — the
inconsistency between two pages of the same doc underlines the drift.

## PRJ-04 [major] — Operation-level error statuses projected under statuses the runtime never produces

**Verified:** YES. `to_openapi.rs:544-563` projects an op error
declared at 429 under a `429` response; the runtime mapper is purely
code-driven and `ErrorDefinition.http_status` is never consulted at
runtime — a `RATE_LIMITED` error surfaces as **500** unless the code is
literally `HTTP_429`. A consumer building backoff logic around the
documented 429 gets 500s. The test `operation_errors_projected_onto_call`
enshrines the wrong behavior. Either project non-`HTTP_*` codes under
500, or honor `http_status` at runtime.

## PRJ-05 [major] — `/subscribe` documented HTTP error statuses are structurally unreachable; in-band SSE errors undocumented

**Verified:** YES. `subscribe_handler` always returns 200 + SSE
(GW-12); unknown op, internal op, ACL denial, and handler errors are all
`event:error` frames (asserted by tests). The doc claims full
protocol-status responses and never mentions `event: error` frames; a
client built from it waits for a 404 that will never come and hangs
reading the stream.

## PRJ-06 [major, security] — MCP `schema` tool skips the per-operation AccessControl check that HTTP `/schema` performs

**Verified:** YES. `to_mcp.rs:148-174` dispatches straight to
`services/schema` with no pre-check (compare `routes.rs:125-127`); the
handler returns the full spec — including `access_control.required_scopes`
— for any registered op the caller is forbidden to call, including
unauthenticated callers. An unprivileged MCP client reads the exact
scopes needed for escalation. Per-caller filtering is asymmetric between
the two projections of the same dispatch spine; the test
`schema_returns_full_operation_spec` enshrines the leak (fetches with
`identity: None` and asserts `access_control` is present).

## PRJ-07 [major] — MCP `search` tool advertises a `query` filter it silently ignores

**Verified:** YES. The input schema advertises "Optional substring
filter" (`to_mcp.rs:56-59`) but `call_tool` drops `arguments` entirely
for search (`:382`) — an LLM passing `{"query": "fs"}` receives the full
unfiltered listing (wasted context; in large registries, context
overflow).

## PRJ-08 [major] — MCP `search` does not exclude `Pub` operations, contradicting ADR-068

**Verified:** YES. The filter is `!matches!(op_type, "sub" |
"subscription" | "Sub")` (`to_mcp.rs:268-274`); ADR-068 says to_mcp
"excludes both `Sub` and `Pub`". A discovered Pub op can never be
invoked via the `call` tool (`invoke` on a Sink returns
`INVALID_OPERATION_TYPE`) — the advertised discovery surface is a lie
for the entire Pub class. (The `"subscription"`/`"Sub"` match arms are
dead — `op_type_str` only emits lowercase.)

## PRJ-09 [minor] — MCP `batch` item shape contradicts its own tool description

**Verified:** YES. `call` returns the raw output as `structuredContent`;
batch items are `{"isError": …, "output"|"error": …}` — the description
claims "each shaped like a `call` result". False on both success and
error shapes.

## PRJ-10 [minor] — `structuredContent` emitted as non-object values (MCP spec says object)

**Verified:** YES. `to_mcp.rs:293-298` passes the operation output
through verbatim — a string/array/null output produces a non-object
`structuredContent`, and batch returns a top-level array. rmcp accepts
it; strict MCP clients may not (client impact unverified).

## PRJ-11 [minor] — `expect`/`unwrap` in `to_openapi` library code

**Verified:** YES. `to_openapi.rs:67` (see SRV-09 — the reachable one),
`:440` (guarded by `is_object`), `:505,512` (guarded by `len() == 1`).
All currently unreachable-in-practice; convention violation.

## PRJ-12 [minor] — Generated doc is nondeterministic when the same error code is declared with different statuses

**Verified:** YES. `collect_operation_errors` dedupes by code while
iterating a `HashMap` — two regenerations of `/openapi.json` from
identical registry state can differ in which status wins (SipHash
randomized per process). Spec-diffing consumers see phantom changes.
Dedupe by `(code, status)` or sort.

## PRJ-13 [minor] — Hand-rolled MCP argument errors omit `retryable`, diverging from the `CallError` wire shape

**Verified:** YES. `to_mcp.rs:159-163,200-204,230-234` — the structured
errors lack `retryable` (required by the OpenAPI error schemas and
always present on `CallError`); a non-string `operation` reports the
misleading "missing required field: operation".

## PRJ-14 [minor] — `components.schemas` defined but never referenced; inline duplication guarantees drift

**Verified:** YES. `to_openapi.rs:88-91,534-542` — `schema_call_request()`
is inlined verbatim 4× and also emitted into components; nothing uses
`$ref`. Shape changes must be edited in lockstep or the doc
self-contradicts.

## PRJ-15 [minor] — `/search` documents 401/403 that cannot occur, omits the 404 that can; no `securitySchemes` anywhere

**Verified:** YES. `services/list` has default ACL, so `/search` returns
200 even unauthenticated (per-op filtering happens inside the listing —
tested); the doc's 401/403 for `/search` can't occur. And the doc
declares no `securitySchemes` despite Bearer being the contract
(ADR-004) — generated clients won't know to authenticate.

---

# Part G — Consumer adapters (from_wss, from_mcp)

## CON-01 [major] — `from_mcp` imports only the first `tools/list` page

**Verified:** YES. `from_mcp/mod.rs:86` — a single `list_tools` call;
`next_cursor` is never followed. rmcp 1.8 provides
`list_all_tools()` for exactly this. Any server with enough tools to
paginate silently truncates; no error, no log. One-line fix.

## CON-02 [major] — `from_wss` drop monitor is one-shot and racy; calls racing the drop hang forever

**Verified:** YES. Two code-verified gaps beyond WS-02's lost
notification: (1) the monitor runs `fail_all` exactly once and exits —
a call whose pending entry is registered *after* `fail_all` ran is
never resolved, and no pending-entry sweeper exists on the client path
(alkcall's sweeper runs only inside `Dispatcher::run_loop`, which
`from_wss` never takes; the module doc's "no hang until the 30s sweeper
deadline" promise is false on this path); (2) the race window above.
The test `connection_drop_fails_in_flight_calls_retryable_no_hang`
covers only calls registered *before* the drop. **Fix:** a `watch`
channel (WS-02) plus a periodic sweep of the pending map while the
session lives.

## CON-03 [major] — `from_wss` accepts plaintext `ws://` and sends the Bearer token over it

**Verified:** YES. `from_wss.rs:114-128` — `IntoClientRequest` accepts
any scheme; nothing enforces `wss://` and the Authorization header is
attached unconditionally. The crate's own tests dial `ws://`. A config
typo (`ws://prod-node/alk/channels`) silently ships a long-lived bearer
credential over plaintext. (TLS validation itself is fine —
rustls-tls-webpki-roots, no danger options anywhere.) **Fix:** refuse
`ws://` when a token is present (or unconditionally unless explicitly
allowed).

## CON-04 [minor] — `content_block_union_schema` audio variant requires a non-existent `"audio"` property

**Verified:** YES. `from_mcp/mod.rs:240-248` — the property is `data`
but `required` lists `audio`; valid audio blocks never satisfy the
schema. Published as `output_schema` and inside `error_schemas`; the
variant test checks only the enum tags. Consumers validating handler
output against the declared schema reject valid audio results.

## CON-05 [minor] — `from_mcp` per-call capability read is dead code; module doc claims per-call credential use

**Verified:** YES. `mod.rs:139-143` computes the token's length and
discards it; the credential actually used is the transport-pinned
import-time token (rmcp's config is immutable post-construction). An
integrator injecting per-call/per-user tokens into
`OperationContext.capabilities` gets silence. Doc + dead read should be
corrected to "import-time credential".

## CON-06 [minor] — 401 classification by substring match on `Debug` output

**Verified:** YES. `mod.rs:103-116` — `format!("{error:?}").contains("401")`
misclassifies transport errors whose URL contains `:4010/` (port 4010)
as `Unauthorized`, and misses differently-worded auth failures.
Fragile in both directions; affects only the surfaced error variant.

## CON-07 [minor] — `from_wss` doc claims imported handlers read per-call credentials; they carry no capabilities at all

**Verified:** YES. `from_wss.rs:7-9` vs alkcall `from_call.rs:141-148`
— bundles register with `Capabilities::new()`; only the dial-time token
ever authenticates. Same class of doc-vs-reality drift as CON-05
(ADR-014's chain is respected, but the doc describes an implementation
that doesn't exist).

## CON-08 [minor] — `std::mem::forget(running)` leaks the rmcp session — no teardown, no DELETE, SSE stream left open

**Verified:** YES. `mod.rs:98` — the fire-and-forget pattern skips
rmcp's session teardown; each `import()` leaves an open server-side
session + long-lived GET SSE stream until the remote times it out.
Repeated imports accumulate. No close path exists on `FromMCP`.

## CON-09 [minor] — `from_wss` import leaks the whole session by design; no shutdown handle for reconnect scenarios

**Verified:** YES. `from_wss.rs:189-193` — deliberate (ADR-070 v1),
but a reconnecting assembly layer calling `import()` again stacks a
second full session with duplicate op names and no way to tear the
first down. Worth an ADR-070 note or a `close()`/handle API in v1.1.

## CON-10 [minor] — `[[test]] full_surface` missing `test-support` in `required-features` → `cargo test --features mcp` fails to compile

**Verified:** YES (empirically). `Cargo.toml:73-75` vs
`tests/full_surface.rs:26` importing test-support-gated items
(`websocket/mod.rs:23-24`). `cargo test --features mcp` fails with
unresolved imports; masked because CI uses `--all-features`.

## CON-11 [minor] — Transport-level `tools/call` failures map to undeclared `INTERNAL`

**Verified:** YES. `mod.rs:149-152` — remote down/timeout/JSON-RPC
error → `CallError::internal`, which is not in the declared
`error_schemas` (only `MCP_TOOL_ERROR` is); MCP JSON-RPC error codes are
flattened, losing fidelity the rest of the crate maintains via
`HTTP_<status>`.

## CON-12 [minor] — Remote tool names interpolated into op names without sanitization

**Verified:** YES. `mod.rs:169-171` — a remote-controlled `tool_name`
containing `/` yields a three-plus-segment op name, breaking the
two-segment `ns/op` convention the gateway and namespace reasoning
assume. (Registry acceptance of such names unverified — if it rejects,
downgrades to cosmetic.)

## CON-13 [minor] — Auth tokens held as plain `String` in adapter builders

**Verified:** YES. `from_wss.rs:48`, `from_mcp/mod.rs:37` —
`auth_token: Option<String>` with a public accessor; alkcall's
`Secret<String>` zeroizing wrapper is used correctly at the
registration boundary but the builder-held copy is unguarded plaintext.
No `Debug` derives exist, so accidental logging is unlikely — but
holding `Secret<String>` would match the crate's own posture.

---

# Part H — Hygiene / cross-cutting

## HY-01 [major] — `openapiv3` is a production dependency used only by a test

**Verified:** YES. `Cargo.toml:44` vs sole usage `to_openapi.rs:1103`
(inside `#[cfg(test)]`). Every consumer compiles `openapiv3` (and its
tree) for nothing. Move to `[dev-dependencies]`.

## HY-02 [major] — 110 missing-docs warnings under `-W missing_docs`

**Verified:** YES (ran with `RUSTDOCFLAGS=-W missing_docs`). Default
`cargo doc` is 0-warning only because `missing_docs` is off. Worst:
`openapi_spec.rs` (28), `http_client.rs` (28), `forward.rs` (10),
`server/adapter.rs` (10), `dispatch.rs` (7), `routes.rs` (6);
`gateway/mod.rs` and `server/mod.rs` lack module docs. For a crate
prepping crates.io, this is the largest single hygiene gap.

## HY-03 [minor] — Guarded `expect`/`unwrap` spots that would panic silently if their guard is edited

**Verified:** YES. `to_openapi.rs:440` (guarded by `is_object`),
`:505,512` (guarded by `len() == 1`), `openapi_spec.rs:144,170`
(guarded by `is_object`). Safe today; the pattern is one edit away from
a panic. (The unguarded ones are SRV-09/PRJ-11.)

## HY-04 [minor] — `unwrap` in shipped `test_support`

**Verified:** YES. `upgrade.rs:161` — `serde_json::to_vec(envelope).unwrap()`
inside `pub mod test_support`, which ships behind the opt-in
`test-support` feature. Documented as intentional; note it is published
API surface with a panic inside.

## HY-05 [minor] — Unused dependencies and feature slack

**Verified:** YES (grep + build). `bytes` declared, zero direct use in
src/ (the only `Bytes` is axum's re-export); `parking_lot` declared,
zero direct use (obtained transitively via alkcall); `tokio` features =
`["full"]` drags in `process`/`signal` extras. All cheap to prune.

## HY-06 [minor] — `HttpClientConfig.retry_policy` exposes `reqwest_retry::ExponentialBackoff` in the public API

**Verified:** YES. `http_client.rs:34` — a semver anchor to an upstream
concrete type and an awkward construction surface; consider an owned
config struct.

## HY-07 [minor] — `READ_SLOTS` is `pub` in a public module (implementation constant leak)

**Verified:** YES. `byte_adapter.rs:56` — reachable as
`alkhttp::websocket::byte_adapter::READ_SLOTS` but deliberately not
re-exported; either privatize or document it as API.

## HY-08 [minor] — `tokio-tungstenite` declared three times with different feature sets

**Verified:** YES. `wss` (:19), `test-support` (:20), and the
dev-dependency (:59) each pull it; feature unification currently lands
on the superset, but `test-support` extending `wss` would remove the
fragility.

## HY-09 [minor] — `8 + len` can overflow on 32-bit targets

**Verified:** YES. `byte_adapter.rs:163,345` — `len` is a parsed
`u32 as usize`; `8 + u32::MAX` overflows in debug on 32-bit. Saturating
add (or the WS-04 validation) removes it.

## HY-10 [minor] — Stale/contradictory docs

**Verified:** YES. `from_wss.rs:86-88` says dropping the session tears
the WS down "(via `WssSession::drop` **or `std::mem::forget`**)" —
`mem::forget` prevents `Drop` and does the opposite (the comment at
:189-192 says so); `routes.rs:1-9` (GW-14); `[ADR-051]:
https://docs.rs/alkhttp` placeholder link definitions and a relative
filesystem link in `websocket/mod.rs:2` break on docs.rs.

## HY-11 [minor] — The whole `docs/` tree (672K) ships in the package

**Verified:** YES. The `exclude` list omits `docs/reviews/` but keeps
`docs/architecture/`; fine if intentional (ADR links), worth a decision
before publish.

## HY-12 [minor] — Duplicate dependency roots

**Verified:** YES (`cargo tree -d`). `getrandom 0.3/0.4` +
`cpufeatures 0.2/0.3`, driven by `tokio-tungstenite 0.28` here vs
`tungstenite 0.29` via axum's ws. Aligning tokio-tungstenite with axum's
tungstenite collapses the duplicates.

## HY-13 [minor] — Vacuous test: `publish_body_is_fully_consumed_before_dispatch_not_required`

**Verified:** YES. `routes.rs:1572-1583` — an empty test body (comment
only) that passes vacuously; its own comment cites an
"infra-integration-suite" socket-level test that does not exist in
`tests/`. Wire the socket-level early-disconnect test or delete the
stub.

---

# Part I — Coverage (cargo-llvm-cov, all features)

Overall: **93.86% lines / 91.75% functions / 94.23% regions** — high,
but the uncovered residue concentrates exactly where the findings live.

## COV-01 — `adapters/forward.rs` 82.3% lines / 67.9% functions (lowest in the crate)

Uncovered regions (JSON export): the binary-response branch (247-264),
the Basic-auth arm (122-125), the ApiKey arm (116-119), the
`value_to_*` helpers (137-151), non-2xx error mapping branches
(205-213), the SSE stream error path (374-383), and the `+json`/
content-type branches (239-244). These are precisely FWD-01/03/07/08/10
— the highest-risk code in the crate is also its least-tested.

## COV-02 — `client/http_client.rs` 81.4% lines

Uncovered: the mTLS/CA-bundle build paths (133-164) and the `Debug`
impl (87-95). No test constructs a client with a CA bundle or client
cert; FWD-03 (redirect policy) has no test because no redirect test
exists.

## COV-03 — `websocket/byte_adapter.rs` 82.2% lines

Uncovered: `WsPumps::abort`/`read_eof` (91-108 — the WS-02 mechanism is
untested), the tungstenite pump twins (309-337 — the duplicated code is
untested by the axum-path tests), and the write-side split/drain edge
paths. A tungstenite-path test suite (or dedup, WS-11) is needed.

## COV-04 — `server/decoy.rs` 87.1% lines

Uncovered: `percent_decode` (112-122 — SRV-08's bugs are untested),
`hex_digit`/`mime_for_path` (129-154), and static-site serving
(129-154). The traversal guards *are* tested; the decoding is not.

## COV-05 — `gateway/dispatch.rs` 91.0% lines

Uncovered: the capability-inheritance path (52-64) and error branches
(202-211, 270-273).

## COV-06 — `server/adapter.rs` 91.9% lines

Uncovered: the mcp router arm (127-132 — never exercised without the
feature in unit tests), `ProtocolHandler::handle`/ALPN entry (192-196,
228-230), the h2 enable-connect branch (235-243), and the
`/openapi.json` error path (250-256 — SRV-09 untested).

## COV-07 — `server/state.rs` 62.5% lines

Uncovered: `FromRef<RouterState> for Arc<dyn IdentityProvider>` (49-52)
— only the decoy FromRef is tested.

## COV-08 — Semantic test gaps (decided behaviors with no test)

The high line-coverage hides the gaps that let the findings land:

1. `/schema` on an `Visibility::Internal` op (SRV-02) — the four other
   routes are tested; schema is not.
2. `extra_routes` auth layering (SRV-01) — no test mounts an extra
   route and asserts identity resolution.
3. `/mcp` body limit (SRV-03).
4. SSE across real TCP chunk boundaries (FWD-06) — the parser is only
   tested with single-chunk delivery.
5. Cross-host redirect behavior with custom credential headers
   (FWD-03).
6. Retry policy on a non-idempotent op (FWD-04).
7. Recursive `$ref` specs (OAI-01 — a test importing a self-referential
   spec would have caught the abort immediately).
8. Absolute-URL path templates / base-path-preserved base URLs
   (FWD-02).
9. `/publish` with `publish_schema`-registered ops (GW-01).
10. `from_wss` drop *while a call is being registered* (CON-02's race).
11. `from_mcp` paginated `tools/list` (CON-01).
12. The tungstenite pump path end-to-end (COV-03).
13. MCP `search` with a `query` argument (PRJ-07); MCP `search`
    containing Pub ops (PRJ-08); MCP `schema` ACL denial (PRJ-06).

---

# Cross-cutting: what is solid (verified)

Listed so the remediation plan can focus on what's actually broken:

- **Auth enforcement on the default surface.** Every gateway route +
  `/openapi.json` + `/healthz` sits under `bearer_auth_middleware`
  (adapter.rs:154-173, applied before merges of the *default* router);
  the WS route carries the fail-closed `ws_bearer_auth` (401 before
  upgrade, tested). Dispatch re-runs visibility + ACL with
  `internal: false` and `forwarded_for: None` hardwired — wire callers
  cannot spoof forwarding or escalate to internal (verified in alkcall's
  registry code, defense in depth regardless of entry point).
- **No-env-vars invariant (ADR-014).** Zero `std::env::var` reads in
  src/; the only occurrences are negative tests asserting env is
  ignored. Credentials flow exclusively
  `context.capabilities.get(namespace)` → `expose_secret()` → header.
- **Credential hygiene.** No tracing calls anywhere in the forwarding
  path (nothing logs headers/tokens); `Secret<String>` zeroizing used at
  the registration boundary; header names/values pass through
  `HeaderName/HeaderValue::try_from` (CRLF injection structurally
  prevented — the failure mode is silent drop, not injection); no
  `danger_accept_invalid_certs` anywhere; stdio transport unreachable
  for MCP (rmcp feature set excludes child-process).
- **Internal-op invisibility on /call, /batch, /subscribe, /publish**
  (pre-checks + registry re-checks; `/call` on Internal → 404, tested) —
  the gap is `/schema` (SRV-02) only.
- **Body limits on axum-extracted routes.** `/call` `/batch`
  `/subscribe` `/publish` are capped at 2 MiB by axum's default (crate
  never disables it); JSON depth bombs rejected by serde_json's
  recursion limit; YAML bombs bounded by yaml_serde's alias/depth
  limits (verified against yaml_serde 0.10.7 source).
- **`/publish` terminal-error shape matches ADR-068** (plain HTTP
  status + JSON body, never an NDJSON line — tested for 200/400/401/
  403/404/500); OQ-02 framing implemented as decided.
- **Batch semantics:** per-entry envelopes, one bad op doesn't fail the
  batch, order preserved (tested).
- **WS framing core is correct.** Byte-stream treatment both
  directions; split headers/payloads reassemble (read_exact-based
  demux); oversized chunks split legally across messages (16 MiB
  round-trip test); WS Close *and* abnormal termination → EOF → all
  channels cleared (traced end-to-end; `disconnect_mid_call` test); no
  busy-wait (the POC spin was replaced with `poll_ready`); text message
  → 1002 close. Identity cannot be escalated via client-supplied
  `auth_token` on channel 0 (NoopProvider fallback verified in alkcall).
- **WS upgrade auth is header-only, fail-closed, and non-WS requests
  cannot reach the session.** No per-request token in URLs anywhere.
- **Error mapping basics (ADR-023).** Protocol codes → statuses per the
  documented table (incl. FORBIDDEN → 401-without-identity/403-with);
  `HTTP_<status>` parsing with malformed-code → 500 fallback (tested);
  unknown codes → 500, never panic.
- **Producer/consumer naming, module structure, feature matrix.** No
  server/client framing in API names; one module per file, all
  re-exported; `--no-default-features`, `mcp`-only, `wss`, and
  `--all-features` all compile; clippy clean in both modes; all 19
  cited ADR numbers resolve to real files.
- **No panics/locks-across-await/blocking-I/O on the hot paths.** The
  exceptions are individually filed (SRV-09, HY-03/04, FWD-09,
  SRV-08's `is_dir`); locks that exist are parking_lot or
  poison-safe std locks per convention.

---

# Remediation plan

Ordered by dependency and severity; each unit is independently
shippable with its own acceptance gate. The overarching gate mirrors the
alkcall review lesson: **each unit's acceptance gate is the test that
would have caught its worst finding.**

## Unit 1 — Auth/visibility at the seams (SRV-01, SRV-02, SRV-03, PRJ-06)

The highest-value unit; all four are small, mechanical, and
security-bearing.
- SRV-01: apply the auth layer after merging extra routes (keep
  per-route opt-out possible by documenting that extras may carry their
  own layers); add a test mounting an extra route asserting identity is
  resolved (and one for the explicit opt-out shape).
- SRV-02: add the `is_internal_op` → 404 guard to `schema_handler`
  (mirror `/call`); test `/schema?name=<internal>` → 404
  unauthenticated and for unauthorized identities.
- SRV-03: body-limit the `/mcp` nest (explicit `DefaultBodyLimit`);
  test a large body → 413.
- PRJ-06: run the same `access_check_for_op` pre-check in the MCP
  `schema` tool (or filter the returned spec per identity); fix the
  enshrining test.

**Gate:** the four new tests above; full suite green.

## Unit 2 — Outbound request construction + retry/timeout policy (FWD-01..05, OAI-01..04, FWD-11)

The largest unit; mostly inside `forward.rs`/`http_client.rs`/
`openapi_spec.rs`.
- FWD-01: percent-encode path segments; reject/encode `?`/`#`; iterate
  substitution safely (single-pass template rendering, not iterative
  replace).
- FWD-02: post-join host-equality validation (fail loudly on host
  change), scheme allowlist (https default), and correct base-path
  appending (fix `Url::join` directory semantics).
- OAI-01: depth budget + visited set in `resolve_refs_recursive`;
  clean error on cycles. **Acceptance gate: an import test with a
  self-referential schema returns an error instead of aborting.**
- OAI-02: enforce `input_schema` at call time (reject undeclared keys,
  or document the pass-through as explicit), implement ADR-066's
  validate-before-send for `from_jsonschema`.
- OAI-03/OAI-04: honor `in: header`; resolve parameter/requestBody
  `$ref`s (index `components/parameters` + `requestBodies`); error
  loudly on unresolved path placeholders instead of sending literal
  `%7Bowner%7D`.
- FWD-03: explicit redirect policy (none or limited same-host).
- FWD-04: no retries for non-idempotent methods (or per-op idempotency
  config); cap total retry duration.
- FWD-05: default request + connect timeouts (anchor to the gateway's
  30 s), cap `Retry-After` (e.g. 300 s ceiling, configurable).
- FWD-11: key `Retry-After` on the effective URL; evict
  longest-deadline-first (or soonest); add jitter.

**Gate:** tests for each bullet — traversal value, absolute-URL
template, redirect-with-API-key, POST-retry, recursive-$ref import,
header-param, `$ref` parameter, timeout default.

## Unit 3 — Gateway correctness (GW-01, GW-03..GW-13)

- GW-01: `publish_schema` validation in the shared spine or the route.
- GW-03: map `INVALID_OPERATION_TYPE` → 400 (or 422) consistently;
  document in http-server.md.
- GW-04: SSE error events terminal (`take_while` Ok / emit-and-end).
- GW-05: enforce or remove the 30 s deadline.
- GW-06: either stream the NDJSON body (axum `Body` → framed stream) or
  document the 2 MiB buffered semantic in ADR-068.
- GW-07: route error responses through `call_error_to_http_response`
  so `Retry-After` fires.
- GW-08: cap batch size (constant, e.g. 100).
- GW-09: generate request ids for internal-op batch entries.
- GW-10: reject a first line missing `chunk` with `INVALID_INPUT`.
- GW-11: drop the redundant `/publish` pre-checks (mirror `/call`).
- GW-12/GW-13: keep 200-on-stream (ADR-049) but document it in the
  projection (PRJ-05) and add SSE keep-alive.
- GW-14: fix the stale module doc.

**Gate:** a `/publish` test with a `publish_schema`-registered Pub op
rejects an invalid chunk; SSE error-terminal test; batch-cap test.

## Unit 4 — WS/adapter robustness (WS-01..WS-11, HY-09)

- WS-02 (do first): replace `notify_waiters` with a `watch` channel or
  permit-storing signal; CON-02 falls out of this + a pending-map
  sweep.
- WS-01: idle timeout on the WS read path (configurable; default
  bounds the dribble stall).
- WS-04/HY-09: validate `len > MAX_CHUNK_LEN` on the write side
  (saturating add).
- WS-05/WS-06: byte-based caps — cap `pending` growth and set an
  explicit inbound `max_message_size` consistent with the plan's ~1 MiB
  intent.
- WS-07: make `poll_shutdown` actually drop the held sender so the
  documented close mapping holds.
- WS-08/WS-09/WS-10: keep `_pumps` handle for forced teardown; add a
  session semaphore; document the detached-task semantics.
- WS-11: dedup the pump bodies (single generic implementation; also
  fixes COV-03).
- Cross-crate: file/land the alkcall demux fix for WS-12 (stream-skip
  instead of `vec![0u8; length]`).

**Gate:** a from_wss test that drops the connection mid-registration
(CON-02); a dribble-stall test bounded by the idle timeout; the
tungstenite path covered by shared tests.

## Unit 5 — Consumer adapter fixes (CON-01..CON-13)

- CON-01: `list_all_tools()`.
- CON-03: refuse `ws://` with a token (or unconditionally with an
  explicit escape hatch).
- CON-04: fix the audio variant `required` list.
- CON-05/CON-07: correct the doc claims (import-time credential) and
  remove the dead capability read.
- CON-06: classify on typed error variants where rmcp exposes them;
  fall back to substring only as a last resort.
- CON-08/CON-09: add explicit close/teardown handles (or document the
  leak + ADR-070 note).
- CON-10: add `test-support` to `full_surface`'s `required-features`.
- CON-11/CON-12/CON-13: declared error codes for transport failures;
  sanitize/validate remote tool names; `Secret<String>` for held
  tokens.

**Gate:** `cargo test --features mcp` compiles and passes (CON-10);
pagination test against a paginating MCP server.

## Unit 6 — Projection fidelity (PRJ-01..PRJ-05, PRJ-07..PRJ-15)

The `to_openapi` document needs a systematic diff against the runtime
(routes tests are the oracle): envelope wrappers (PRJ-01/02), the
422-vs-400 mapping (PRJ-03), error-status honesty (PRJ-04), the
`/subscribe` 200+in-band-error contract (PRJ-05), `securitySchemes`
(PRJ-15). MCP: honor/drop the `query` filter (PRJ-07 — honoring is
trivial), exclude Pub (PRJ-08), fix the batch doc (PRJ-09), wrap
non-object outputs or document (PRJ-10), add `retryable` (PRJ-13),
deterministic error merge (PRJ-12).

**Gate:** a test that generates the doc and asserts it against a
hand-written golden file matching the routes tests' actual bodies;
MCP search respects `query` and excludes Pub.

## Unit 7 — Hygiene + coverage (HY-01..HY-13, COV-01..07, SRV-04..SRV-10, OAI-05..OAI-09, FWD-08..FWD-10, FWD-12)

Mechanical, parallelizable cleanup:
- HY-01 (`openapiv3` → dev-deps), HY-05 (unused deps), HY-08 (feature
  triplication), HY-11/HY-12.
- HY-02: `missing_docs` sweep (110 warnings) before crates.io.
- SRV-05..SRV-10, OAI-05..OAI-09, FWD-08..FWD-10, FWD-12: per-finding
  small fixes.
- COV-01..07: backfill the uncovered regions identified in Part I,
  prioritizing the forwarding-core error/binary/auth paths and the
  tungstenite pump path.
- HY-13: wire or delete the vacuous `/publish` test.

**Gate:** `cargo doc -W missing_docs` clean; `cargo tree -d` reduced;
coverage of `forward.rs` ≥ 95% lines.

## Suggested sequencing

```
Unit 1 (auth seams)        → no deps; do first (smallest, highest value)
Unit 3 (gateway)           → no deps; independent
Unit 2 (outbound requests) → no deps; largest; can start in parallel
Unit 5 (consumer adapters) → no deps; small
Unit 4 (WS robustness)     → depends on nothing in-tree; coordinate WS-12 with alkcall
Unit 6 (projections)       → after Unit 3 (shares routes.rs/error mapping docs)
Unit 7 (hygiene/coverage)  → continuous; land the dep/doc items any time
```

Units 1, 3, 5 touch disjoint files and can proceed in parallel. Unit 2
and Unit 4 both touch `byte_adapter.rs` only via HY-09 (trivial).
Unit 6's doc-golden work should follow Unit 3 so the runtime contract
is settled before it is documented.

## On the baseline objective

The extraction is structurally sound: the architecture held, the wire
formats are right, the no-env-vars and Internal-by-default invariants
are real and tested, and the end-to-end integration suites (the thing
alkcall's review found missing) exist and are substantive. What needs
attention is the *edge* behavior: the seams where the default surface
meets extension points (extra routes, `/schema`, MCP), the outbound
forwarding path (URL construction, redirects, retries, timeouts, SSE
parsing), and the projections' fidelity to the runtime they describe.
None of these block the crate's core function; all of them are the kind
of thing that surfaces as a production incident rather than a failed
test. **Treat Unit 1 and Unit 2 as the gate for any deployment-facing
milestone.**

---

## Verification log (this pass)

- All findings carry `file:line` references verified against tree
  `4a825d3` by the subsystem passes; the consolidating pass
  re-verified: SRV-01/SRV-02 (adapter.rs:170-183, routes.rs:95-137,
  240, 380-399), SRV-09 (adapter.rs:243-256, to_openapi.rs:64-68),
  GW-01/GW-03 (routes.rs:213, 257-266; error.rs:17-59), WS-02/WS-04
  (byte_adapter.rs:91-103, 135-180, 343-345; from_wss.rs:154-166,
  189-195), WS-10 (upgrade.rs:114-143), FWD-02/FWD-03/FWD-05
  (forward.rs:56-151; http_client.rs:105-173), SRV-08/COV-04
  (decoy.rs:100-136), and the vacuous test (routes.rs:1572-1583).
- Subsystem passes verified dependency-level claims against vendored
  sources: axum 0.8.9 (route_layer/merge semantics, SSE, extractor body
  limits), hyper 1.11 (timer gating), reqwest 0.13.4 (redirect scrub,
  scheme rejection), reqwest-retry 0.9.1 (retryable strategy),
  reqwest-middleware 0.5.2 (stack order), rmcp 1.8.0 (body collect,
  list_all_tools, streamable-http transport, bearer application),
  tokio-tungstenite/tungstenite 0.28 (max_message_size), yaml_serde
  0.10.7 (alias/depth limits), retry-policies 0.5.2 (backoff bounds),
  and alkcall 0.1.1 (registry/discovery/dispatch/wire).
- Three findings were confirmed empirically with scratch harnesses
  outside the repo (no repo changes): the extra-routes auth bypass
  (SRV-01), the `$ref` recursion abort (OAI-01), and the SSE
  chunk-boundary event loss (FWD-06).
- Coverage figures: `cargo llvm-cov --all-features` (summary + JSON
  export), 2026-08-28.
- Cross-crate finding WS-12 is filed against alkcall, not this crate;
  it is included because the WS path makes it trivially reachable.