alkcall/docs/architecture/decisions/048-dispatch-spine-gateway-module.md

ADR-048: Dispatch Spine (feature-gated gateway module)

Status

Accepted

Context

The first real downstream consumer of this crate — alkhttp — built its HTTP gateway (POST /call, /subscribe, /publish, the MCP call tool, the to_openapi projections) on a small internal component it calls the dispatch spine: a thin struct over Arc<OperationRegistry> that owns the non-HTTP half of gateway dispatch. The HTTP layer resolves bearer tokens to an Identity, frames NDJSON/SSE, maps CallError to HTTP statuses, and wraps axum handlers; the spine does everything that happens after that:

• constructs the root OperationContext identically for every transport (internal: false — ACL runs against the caller's identity, not a handler's composition authority; forwarded_for: None — wire-ingress only; identity supplied per-call),
• resolves the registration's composition_authority / capabilities / scoped_env into that context,
• bounds Once-ops and sink dispatch with a deadline while leaving streaming subscriptions unbounded (ADR-021: subscriptions are long-lived),
• and applies the services/schema disclosure guard when the dispatched operation's input names another operation.

This is transport-neutral work. It contains no HTTP concepts: no statuses, no headers, no body framing. And it is not HTTP-shaped by accident — the same shape is exactly what a hub needs when it terminates channel 0 on both legs and relays calls to spokes (ADR-042's "translate, not forward" rule): the hub must re-root the context at itself (its own identity, internal: false, no forwarded_for), re-resolve its capabilities for the outbound leg, and bound the relay so a hung spoke does not wedge the browser-facing connection. alkhttp needed it; the hub relay needs the same thing; any protocol crate that exposes a call surface to a less-trusted in-transport caller (a WS-native relay, a CLI bridge, a test harness) will need it again.

Duplicating it per consumer is the failure mode this crate already paid for once: the spine's services/schema guard existed because the registry handler and the HTTP route were written against different disclosure rules (CF-004, filed from alkhttp's consumer review). One shared implementation is the fix; a second copy in a second crate would re-open the drift.

alkhttp is not yet published. This is the cheapest moment to move the component into alkcall (behind a feature, so the base crate stays lean and the surface is opt-in) and have alkhttp consume it rather than carry its own copy.

Decision

Promote the dispatch spine into alkcall as a new gateway module, feature-gated:

• alkcall/gateway behind the gateway cargo feature (default off — the base crate stays lean; the module adds no dependencies, the gate exists to keep the audit surface explicit and opt-in).
• GatewayDispatch — the spine struct: invoke(), invoke_streaming(), invoke_sink(), registry access, and root context construction. The 30 s deadline alkhttp hardcodes becomes a constructor knob (with_deadline) so consumers keep their own policy; the default remains 30 s for drop-in equivalence.
• schema_disclosure_denial() — the shared check that a spec the caller could not invoke is not disclosed: NOT_FOUND for Internal-visibility ops, FORBIDDEN for ACL-denied ops.
• CallRequest stays in alkhttp (payload framing is transport business); MAX_BATCH_OPERATIONS stays in alkhttp (batch is a projection concern).

ACL denial returns FORBIDDEN, not spec-404

The wire-path services/schema handler (CF-004, discovery.rs) returns spec-404 for both Internal visibility and ACL denial — the right answer for an unauthenticated wire caller, where even acknowledging the op's existence is a leak vector. The spine's guard is invoked by a transport that has already resolved the caller's identity and often already admitted the op elsewhere (the alkhttp GET /schema route answers 403 for ACL-denied ops, deliberately). The spine therefore keeps alkhttp's split:

• Internal visibility → NOT_FOUND (never acknowledged, at any authority).
• ACL denial → FORBIDDEN (informative for a caller whose identity the transport resolved; alkcall's own registry invoke() produces the same code for the same caller state, so the guard's answer is never more restrictive or less restrictive than the invoke that would follow it).

The two layers are consistent by construction: the wire handler's spec-404 is the conservative outer bound, the spine's FORBIDDEN is the identity-aware refinement. When an unauthenticated caller hits both, FORBIDDEN and NOT_FOUND differ only in which exists — and AccessControl::check with no identity returns "authentication required", which HTTP-side mappers translate to 401. alkhttp consumes this module in a later session and drops its local copy; until then the two implementations coexist (byte-identical in behavior, one in each crate).

What the spine deliberately does NOT include

• No HTTP mapping. CallError → status/body is the consumer's (alkhttp gateway::error). The neutral wire error is the module's lowest-level vocabulary.
• No body framing, limits, or timeouts beyond the deadline knob. NDJSON/SSE framing, body caps, keep-alive intervals are transport concerns (GW-15/GW-16 in alkhttp's ledger).
• No batch semantics. MAX_BATCH_OPERATIONS and the batch envelope are projections of the registry onto HTTP/MCP payloads.
• No CallRequest type. The spine takes (op, input) — parsing { operation, input } is transport framing.

Consequences

• The deadline policy moves from "alkhttp's 30 s HTTP convention" to "spine policy, configured per-consumer" (default 30 s). Sink dispatch is bounded by the same deadline as Once-ops — the wire path's Pub dispatch is unbounded (deadline: None); consumers who want the wire behavior pass Duration::ZERO-style no-deadline configuration via with_deadline(None). Documented divergence, a choice the consumer now owns.
• alkhttp migrates to alkcall::gateway in a follow-up session; its local spine is deleted then, not deprecated in place (unpublished crate — no compat window needed).
• The feature adds no dependencies; cargo test --no-default-features and --all-features both pass (the wasm-clean baseline is untouched).
• Future transports (WS-native relays, protocol crates) reuse the spine instead of re-deriving the context/guard discipline.

Alternatives considered

• Fold into registry as a method set on OperationRegistry. Rejected: the spine is a policy wrapper (deadline, root-context shape, disclosure guard) a consumer opts into, not the registry's dispatch core. GatewayDispatch::invoke ≠ OperationRegistry::invoke — conflating them invites wire paths to pick up transport-shaped policy accidentally.
• Wait for alkhttp to publish first. Rejected: promotes a duplicate into the wild that immediately has to be deprecated; the cheapest moment to move the type is before either crate's first release.
• Promote the whole gateway module. Rejected: routes (SSE/NDJSON framing, body limits) and error mapping (IntoResponse, status mapping) are HTTP by definition; moving them would drag axum/hyper as optional dependencies into a protocol crate for no reuse — alkhttp is their only consumer.