alkhttp/docs/reviews/006-alkcall-0.3.0-consequence-review.md

Review 006 — alkcall 0.3.0 consequence review (WS-24/WS-25 upstream, alkhttp residual)

Status

Verified, open for Unit 2. One new finding (UP-01); the 0.3 bump committed and verified (3dee46a).

Scope

Consequence review of alkcall 0.3.0 (published 2026-09-04 — the remediation of alkcall reviews 004–005, which is the upstream resolution of this repo's review-003 findings WS-24/WS-25) against this crate. The pass answers three questions:

1. What does the 0.3 bump itself cost here (source breaks, behavior changes)?
2. Which review-003 findings are now resolved upstream, and which remain alkhttp-side work?
3. Did the upstream remediation introduce anything this crate must absorb (new protocol codes, new wiring contracts, new decisions)?

Sources read: alkcall review 004 (docs/reviews/004-…md, remediated) and review 005 (docs/reviews/005-…md, resolved G-01..G-05), the 0.3.0 changelog, the ADR amendments (alkcall ADR-047 §4 amendment #2, ADR-022 amendments 2026-09-03 + 2026-09-04), and the published 0.3.0 crate source. Every claim below verified in source at this tree (df86f89, consuming alkcall 0.3.0) or the published crate.

Findings use the new prefix UP (upstream-consequence); review 003's WS numbering is referenced for continuity.

Baseline verification (this pass)

cargo test                                → 453 passed, 0 failed
cargo test --all-features                 → 575 passed, 0 failed
cargo clippy --all-targets -- -D warnings → clean
cargo clippy --all-features --all-targets -- -D warnings → clean
cargo fmt --check                         → clean
cargo doc --no-deps                       → clean

Verified after the 0.2 → 0.3 bump (3dee46a). The bump cost was two source-break classes, both mechanical:

• ChannelClient::take_call_connection now returns Option<Arc<CallConnection>> (was a bare CallConnection) — WssSession::connect dropped its Arc::new re-wrap (src/adapters/from_wss.rs:268-274).
• OperationRegistry::register, ChannelOperations::register_on, and ChannelCore::register_openable now take &OperationRegistry (was &mut) — 51 stale mut bindings dropped via clippy --fix across src/adapters/{from_wss,to_mcp, to_openapi}.rs, src/gateway/routes.rs, src/server/adapter.rs, and tests/.

The &self-registration change is the interior-mutability change that makes the per-session fork surface possible; for every existing alkhttp call site it is source-compatible (reborrow). The registration() → owned and list_operations() → owned return-type changes required no edits here (call sites already cloned through the borrow or consumed by value-compatible iteration — verified by the clean build).

Verdict

• WS-24 and WS-25 are resolved upstream. The two design gaps review 003 Part B identified are now mechanized in alkcall 0.3.0 and decided in its ADRs: the per-session fork is the dispatch-registry mechanism (alkcall ADR-047 §4 amendment #2 — review-003 option (a), the wire-proven shape), and op/register is the client-side registration mechanism (alkcall ADR-022 amendment 2026-09-03 — review-003's bootstrap-op candidate). The alkhttp-side consequences of review-003 Unit 1's candidates are exactly what landed.
• One upstream remediation result lands here for free: review 005 Unit 1 mechanized the accept-side pending-resolution arms into run_loop_single_stream (the loop our WS channel-0 dispatch runs). Pre-0.3, an accept-side nested-composing handler (a from_call imported-op stub riding the WS connection) could deadlock against the inline dispatch; post-0.3 the loop spawns Once invocations and Sub pumps, so the G-01 hazard class is shut for WS sessions by the bump alone — no alkhttp code involved.
• The remaining review-003 findings are all still open and now unblocked (WS-20/21/22/26 mechanical, WS-27 cleanup, WS-23 tests): the hook still discards the ChannelManager (src/websocket/upgrade.rs:255), no channel ops / openables / bootstrap discovery are registered, no deployment surface declares openable ALPNs, and no live connection handle is retained. All grep-verified at this tree.
• One new finding (UP-01): alkcall 0.3 introduced the ALREADY_EXISTS protocol code; this crate's gateway error table has no arm for it and would map it to 500. Unreachable today (only op_register_handler emits it), load-bearing the moment Unit 2 wires op/register.
• One wiring contract Unit 2 must honor (UP-02, recorded as a decision point, not a defect): the op/register collision policy binds the WS session's handler to the session fork.

Severity legend

Same scale as review 003: [major] — a decided behavior is missing/wrong or a real hazard; [minor] — drift, convention violation, or doc/spec inconsistency with no correctness impact.

---

Part A — What 0.3.0 resolves for this crate

WS-24 [was major, cross-crate] — dispatch-resolution mechanism → RESOLVED upstream

alkcall ADR-047 §4 amendment #2 (2026-09-03) decides option (a): the install_channel_zero hook forks the deployment's base registry, registers the per-session ops on the fork (ChannelOperations:: register_on, ChannelCore::register_openable, install_bootstrap_discovery — the last closed over the fork so services/list sees per-session openables, review-004 F-06), and dispatches channel 0 over the fork. The connection overlay remains the peer-announced-op landing zone and nested-invocation target, not the dispatch-resolution path. The reference shape is alkcall's fork_registry_open_op_resolves_and_is_discoverable gate (alkcall/src/channels/client.rs:1994 — fork → register_openable → install_bootstrap_discovery → Dispatcher::new(fork, …)), which is the shape Unit 2 must reproduce in install_channel_zero.

Upstream also resolved the fork's discovery half (review-004 F-06): install_bootstrap_discovery registers services/list, services/list-peers, and services/schema closed over the fork itself, so per-session openables are discoverable without a re-registration walk. The bootstrap set is closed at four with op/register (alkcall ADR-022 amendment, services/list-peers added 2026-09-04 per review-005 G-05).

alkhttp consequence: none to code yet; Unit 2 consumes it.

WS-25 [was major, cross-crate] — client-side op registration → RESOLVED upstream

alkcall ADR-022 amendment (2026-09-03) decides the bootstrap-op mechanism: op/register (registry::op_register module) — a peer announces an op spec over channel 0; the hub's per-session handler rebuilds the spec, wraps it as a forwarding stub that nested-calls back over channel 0, and lands it in the connection overlay via register_imported (forced Visibility::Internal, provenance FromCall). The wire stays the six call.* envelope kinds. Collision policy (2026-09-04 sub-amendment, review-005 G-03): an announced op may replace other announced ops (replace governs) but never the serving side's own registrations — ALREADY_EXISTS regardless of replace; the handler gates on the serving registry first, then the overlay.

The serving half it composes on (Dispatcher::serve_single_stream, opt-in via ChannelClient::from_connection_with_serving) landed with review-005 Unit 1's concurrency rework: Once invocations, Sub pumps, and sink response writers are spawned in both single-stream loops, so same-connection nested composition (the flagship hub-composes-peer-op flow) resolves concurrently instead of deadlocking to the 30 s sweeper (review-005 G-01, empirically verified upstream with a since-removed probe, productized as two 5s-bounded gates).

alkhttp consequences: Unit 2 wires op/register on WS sessions by registering op_register_spec(acl) + op_register_handler(connection, fork) on the per-session fork (the collision set is the fork — exactly what the session dispatches over, mirroring the upstream gates' production shape). Two additional facts from review 005 apply:

• The channel-0 Connection must carry the peer identity for compose_root_env to attach the connection's overlay (keyed by identity.id). alkhttp's hook already does this (src/websocket/upgrade.rs:264 — identity propagated from the upgrade's AuthContext); verified correct as-is.
• The serving loop's concurrency means a hub handler that composes an announced op resolves live (no sweeper); no alkhttp-side scheduling work is needed.

ADR-048's browser bidirectionality promise is now mechanized on the hub half; the browser half (announcing via WS framing) is a client-side concern with no alkhttp code beyond serving the op. The re-point edits in ADR-048/OQ-05 (committed df86f89) record this.

Fixed-upstream items this crate inherits

• Accept-side nested-composition hazard (review-005 G-01's second consequence): mechanized shut by the pending-resolution arms now in run_loop_single_stream — inherited by the bump, no alkhttp code.
• resource_id_path wire round-trip (review-005 G-04): a from_call-imported or announced op declaring ownership-scoped resource extraction previously rebuilt with resource_id: None (ACL checks ran without the resource id). Both round-trip halves now carry the field. from_wss's import path inherits the fix.
• Head-of-line blocking / interleaved directions: a serving side's outbound calls resolve while it serves a Sub (the interleaved-directions gate upstream) — relevant to any future serving-enabled from_wss (see Part C).

---

Part B — Findings at this tree

UP-01 [minor] — The ALREADY_EXISTS protocol code is unmapped in the gateway error table

Verified: YES. alkcall 0.3 added CallError::already_exists ("ALREADY_EXISTS", non-retryable — alkcall-0.3.0/src/protocol/wire.rs:124) for the op/register collision policy; its own ADR-022 amendment records the code. alkhttp's status map (src/gateway/error.rs:57-80) has no arm for it: NOT_FOUND, FORBIDDEN, INVALID_INPUT, INVALID_OPERATION_TYPE, TIMEOUT, INTERNAL, and HTTP_* prefixed codes are mapped; anything else falls to STATUS_INTERNAL (500). alkcall's ADR-016 code list (six codes) was not amended for the seventh — upstream doc drift, noted for that repo.

Reachability today: none — the only emitter is op_register_handler, which no alkhttp path invokes yet (grep verified; the gateway dispatches base-registry ops directly). It becomes reachable exactly when Unit 2 wires op/register on WS sessions, at which point a collision rejection would surface to wire callers as 500 with an ALREADY_EXISTS body instead of a conflict status. Because the collision path is also how a peer experiences the reconnect-reannounce contract (replace refused for serving-registry names), fidelity matters there.

Fix (Unit 2, ride-along): map ALREADY_EXISTS → 409 Conflict in call_error_to_http_status_with_identity (plus the test arm), matching ADR-023's HTTP_<status> discipline for the new code. One-line change + test; no consumer breaks (the code is new).

UP-02 [minor, decision point] — op/register's AccessControl on the WS surface needs a decided default

Not a defect — a decision Unit 2 cannot avoid. alkcall's op_register_spec(access_control) takes the ACL as a parameter; its doc notes the default (AccessControl::default()) lets any peer register, and the op is Mutation/External-typed. This crate's convention (AGENTS.md §13, ADR-015): adapter-registered ops are Visibility::Internal by default — but op/register cannot be Internal on the wire surface (the peer must call it; Internal ops resolve spec-404 to wire callers). The analogous precedent here is the built-in gateway's NoCap posture for channel opens (review-001 SRV-10: crate default is permissive, deployments gate via the ChannelsPolicy extension). The consistent shape: register op/register on the per-session fork with AccessControl::default() on the built-in surface and let an assembly-layer override pass a stricter ACL the same way ChannelsPolicy/OpenableAlpn flow — record the posture in the Unit-2 task and in ADR-048's amendment note when the wiring lands.

WS-20/WS-21/WS-22/WS-26 [major] — unchanged, now unblocked

Re-verified at this tree; all four stand as review 003 found them:

• install_channel_zero still discards the manager (src/websocket/upgrade.rs:255 — _manager unused); no ChannelCore, no ChannelOperations::register_on (grep: zero callers in this crate), no openables.
• No OpenableAlpn surface exists (src/server/adapter.rs builders unchanged: with_decoy / with_extra_routes / with_ws_max_sessions / with_ws_idle_timeout).
• No live Arc<CallConnection> handle is retained by the session (the hook moves channel 0's connection into the spawned task); WsSessions still tracks pump handles only.

The fix shape from review 003 Unit 2 stands, now with the upstream mechanism named concretely: per-session fork() in the hook → ChannelOperations::register_on(&fork) → openables via register_openable(spec, handler, &fork, auth) → install_bootstrap_discovery(&fork) → op_register_spec + op_register_handler(Arc<CallConnection>, fork) → dispatch over the fork (Dispatcher::run_loop_single_stream unchanged as the loop). The OpenableAlpn list + with_ws_openable_alpns threading (RouterState → SessionState → hook, request-extension fallback mirroring ChannelsPolicy) is unchanged, as is the WS-26 handle-retention design (eviction hooks into WsSessions).

WS-27 [minor] — unchanged; folds into the Unit-2 hook rework

adapter_install_channel_zero (src/websocket/upgrade.rs:290-295) is still #[allow(dead_code)] with its only caller test-gated (src/adapters/from_wss.rs test server). The rework gives both callers a real hook; fold the cfg cleanup there.

WS-23 [minor] — unchanged; Unit 3's e2e gates gain two upstream-mirroring gates

The browser-opened-channel e2e test is still absent (no test opens a data channel through a live WS session). Unit 3's five scenarios stand as written. Two gates to add, mirroring what review 005 taught: services/list on a live WS session lists the per-session openable (the F-06 shape), and the op/register announce → hub nested-composition → routes-back-to-consumer flow (the stub path — the one review-005's original gate missed and G-02 called out).

---

Part C — Noted, not findings

• Connect-side serving for from_wss: alkcall 0.3's from_connection_with_serving makes the WSS consumer half capable of serving inbound calls (the from_wss session could answer hub→consumer calls). from_wss keeps the pure-consumer default (from_connection, resolution-only pump — verified unchanged); opt-in serving is a deliberate later decision (it changes from_wss's security posture: a dial would then execute inbound requests against a caller-chosen registry). Recorded here so the opportunity is visible; no finding, no unit.
• op/register forced-Internal semantics vs AGENTS.md §13: the announced op lands Internal/FromCall on the hub — consistent with the adapter-registered-ops-are-Internal convention (it is composition material, not wire-callable from the hub side). No conflict; noted to preempt an apparent tension.
• list_operations returns External only — the to_openapi/to_mcp projections and the gateway /search continue to see exactly the External set; unchanged from 0.2.
• Upstream doc drift (alkcall-side, not ours): ADR-016's protocol-code list ("six codes", last amended by ADR-021) does not name ALREADY_EXISTS. The 2026-09-04 ADR-022 collision sub-amendment records the code's use; ADR-016's list is stale. Flagged for the next alkcall doc pass; UP-01 is the alkhttp-side half of the same gap.

---

Remediation plan (alkhttp side; supersedes review 003's plan where noted)

Review 003's Units 1 and 4 are partially closed by upstream; the remaining work re-sequences as:

Unit 2 — alkhttp wiring (WS-20/21/22/26/27 + UP-01) — next

1. OpenableAlpn { spec, open_handler } + HttpAdapter::with_ws_openable_alpns(...), threaded RouterState → SessionState → run_channels_session → hook, with a request-extension fallback (mirror ChannelsPolicy).
2. Hook rework per the upstream reference shape: fork → channel ops → openables → bootstrap discovery → op/register (ACL per UP-02's decided posture) → dispatch over the fork; retain the Arc<CallConnection> in a WsSessions-evicted registry (WS-26); adapter_install_channel_zero cfg cleanup (WS-27).
3. UP-01: ALREADY_EXISTS → 409 in the gateway error map + test.

Gate: a live WS session lists its openable in services/list; an open op on channel 0 returns a channel_id; op/register collides loudly against fork-registered names (409 over the WS path).

Unit 3 — e2e tests (WS-23) — after Unit 2

Review 003's five scenarios stand, plus the two upstream-mirroring gates named in Part B (openable discoverable on the live session; announce → nested composition → routes back).

Unit 4 — spec reconciliation (docs) — after Unit 2

Review 003's list stands (OQ-05 resolution, ADR-067/ADR-048 notes, websocket.md status block, idle-knob deployment note), with the op/register ACL posture recorded per UP-02.

---

Verification log (this pass)

• Bump verified empirically: cargo check (default + all-features) surfaced exactly the two break classes; post-fix gates all green (453 / 575 / clippy both / fmt / doc).
• WS-24/WS-25 resolutions read in the published 0.3.0 crate source (registry::op_register handler + collision gate; Dispatcher::serve_single_stream; install_bootstrap_discovery; OperationRegistry::fork) and in the upstream ADR amendment texts; the reference fork shape read at alkcall/src/channels/client.rs:1988-2130.
• Review-003 residual claims re-verified at this tree: hook discards manager (upgrade.rs:255), zero register_on callers, no openable surface, no retained connection handle, WS-27 caller census unchanged.
• UP-01 verified: no ALREADY_EXISTS arm in src/gateway/error.rs:57-80; emitter census in 0.3.0 = op_register.rs only; fall-through confirmed to STATUS_INTERNAL.
• UP-02 verified: op_register_spec signature and its default-ACL doc note; AGENTS.md §13 vs wire-callable tension resolved against the SRV-10 precedent (permissive crate default + extension override).
• Cross-repo state verified: alkcall review 005 resolved (G-01..G-05 remediation log), 0.3.0 published with cargo semver-checks 196 checks against 0.2.0 (changelog's Changed section matches the two source-break classes this crate experienced).