alktty/docs/architecture/decisions/010-channels-establisher-migration.md

ADR-010: Channels-Path Establishment Failures Move into an Establisher

Status

Accepted (2026-09-06). Migrates the channels-path semantic-failure surface per alkcall 0.5.0 / ADR-049 (review 006 E-01 + N-1) — the sequencing ADR-049 §5 names ("alktty migration — channels-path semantic failures move into an establisher; the direct-ALPN in-band error frame is retained — two transports, two contracts"). Prerequisites: alkcall 0.5.0 (ChannelCore::register_openable_with_establisher, channel:open_failed, typed ChannelOpenError).

Amended (2026-09-07, alkcall 0.6.0 / ADR-049 amendment 2 — review 007 R-01): Establishment gained its plan payload (ChannelPlan = Arc<dyn Any + Send + Sync>), removing §2's payloadless-Establishment blocker. Backend allocate moves into the establisher; the allocated TtyHandle crosses to the pump handler via the plan; allocate_failed joins the call-error surface as details.reason == "dial_failed" (the target refused or the backend lacked capacity). No failure class arrives in-band on the channels path from a registered producer; the in-band error-frame fallback stays for no-establisher registrations (defense-in-depth) and the direct-ALPN path. See §2A below; §2 is retained as historical record.

Amends ADR-009's R4 amendment: the in-band error-frame path on the channels path shrinks to one failure class (allocate_failed).

Context

ADR-009 made the open op's input the negotiation and moved semantic validation into the producer-side handler. Because alkcall 0.4.x's open wrapper could not fail after allocation (review 006 E-01), the semantic-failure classes had nowhere to go but the channel stream: the handler wrote a 0x00-prefixed negotiation error frame (malformed_negotiation, unknown_backend, allocate_failed, ownership-denial forbidden) on a channel the open op had already reported as succeeding. The consumer observed success-then-frame — a per-crate workaround ADR-049 explicitly retires:

alktty's per-crate in-band error vocabulary is retired on the channels path; every future ALPN crate gets the establishment reply for free.

alkcall 0.5.0 implements the resolution: the wrapper awaits a bounded establisher (OpenEstablisher — Fn(Value, AuthContext) -> BoxFuture< Result<Establishment, EstablishmentError>>) between channel allocation and the open reply; on rejection it tears the channel down and replies channel:open_failed with details: { reason, message } (reason ∈ dial_failed / unknown_resource / resource_shortage / handler_error / timeout). The SSH contract holds consumer-visibly: a failed open never returns a channel_id. ChannelClient::open_channel carries the CallError verbatim in a typed ChannelOpenError (review 006 N-1), so the reason is branchable end-to-end.

Decision

1. The channels path registers an establisher

register_openable (alktty's helper, signature unchanged) now calls ChannelCore::register_openable_with_establisher with make_tty_establisher — the establishment phase runs the semantic validation that used to be post-open error frames:

• Full NegotiateRequest parse of the registry-schema-validated input (the schema stays deliberately partial — the opaque ADR-053 backend params pass through; the establisher is the typed gate).
• carriage == "raw", non-empty cmd.
• Backend lookup against the adapter's backend map.
• The ADR-050 ownership check (moved from the pump handler's validate_and_allocate; the scope gate stays the registry's — pre-allocation, unchanged).

Rejections map into ADR-049's fixed reason vocabulary (no new codes — the vocabulary is alkcall's one-way wire surface):

TTY failure class	EstablishmentError variant	details.reason
NegotiateRequest parse failure	HandlerError	handler_error
carriage != "raw", empty cmd	HandlerError	handler_error
unknown backend	UnknownResource	unknown_resource
ownership denial	HandlerError	handler_error
allocation failure (amended — §2A)	DialFailed	dial_failed
establishment deadline	(wrapper)	timeout

resource_shortage has no TTY producer path (allocation-capacity failures map to dial_failed — the target refused or the backend lacked capacity; §2A). HandlerError covers both the malformed-negotiation semantics (the request shape is wrong) and the ACL-outcome ownership denial (an authorization failure, not a dial failure).

2. Backend allocation stays in the pump handler — allocate_failed stays in-band

Amended away (2026-09-07) — see §2A. This section is the historical record of the pre-0.3.0 shape; its blocker 1 (payloadless Establishment) was resolved by alkcall 0.6.0 (ADR-049 amendment 2, review 007 R-01). Blocker 2 (double-allocate unsoundness) is avoided by construction in the amended shape: the establisher's handle is the handle the handler pumps — there is no second allocate to be unsound about.

The one failure class that cannot migrate: backend.allocate. Two reasons, both structural:

1. Establishment is payloadless ("reserved for a channel plan"). There is no sound way to hand the allocated TtyHandle from the establisher to the pump handler: the establisher and handler are separate closures registered once per connection (no per-open key is shared between them), and an Arc<Mutex<Option<TtyHandle>>> stash would need exactly that key to be race-free.
2. Double-allocate is unsound under ADR-005's kill-on-Drop contract: re-allocating in the handler after an establisher-side allocate would spawn the session target twice (the first handle's kill-guard would fire on its drop — a session killed before it started), and leaking the establisher-side handle would leak the live target.

So backend.allocate runs where it always did — inside drive_session_pre_negotiated's validate_and_allocate — and allocate_failed remains a post-open 0x00-prefixed negotiation error frame, surfaced consumer-side as [TtySessionError::NegotiationRejected] via the same peek the direct path uses. A pinned test (allocate_failure_still_arrives_in_band_on_ channels_path) guards this boundary. Revisit when alkcall gives Establishment a payload (a channel plan carrying the handle would let allocate_failed join the call-error surface).

The pump handler's parse arm (malformed_negotiation frame) and validate_and_allocate's other error frames are now defense-in-depth: the establisher rejects those classes first, so on the registered path only allocate_failed is reachable. The arms stay (a no-establisher registration still compiles against alkcall's API and must not silently EOF), and the R4 seam test pins the handler-side frame.

2A. Amendment (alkcall 0.6.0): allocation moves into the establisher

alkcall 0.6.0 (ADR-049 amendment 2, review 007 R-01) filled the reserved field: Establishment { plan: Option<ChannelPlan> } with ChannelPlan = Arc<dyn Any + Send + Sync> — typed-opaque, wrapper threaded to the OpenHandler's new second parameter. §2's blocker 1 is gone; the double-allocate hazard (blocker 2) is structurally absent — one allocate per open, whose result the handler consumes.

The amended shape:

1. The establisher allocates. After the validation sequence (§1), it runs backend.allocate(&params). Failure maps to EstablishmentError::DialFailed (details.reason == "dial_failed" — the target refused or the backend lacked capacity; one string message, no nuance — the same granularity the direct path's allocate_failed frame always had). The channel:open_failed ErrorDefinition on tty_open_spec() therefore declares four reachable reasons (dial_failed, unknown_resource, handler_error, timeout).
2. The handle crosses via the plan. TtyHandle is not Sync (boxed dyn streams), so it cannot be the ChannelPlan directly. The establisher wraps it in a private AllocatedHandle one-shot slot (Mutex<Option<TtyHandle>>), created per establisher invocation — per open. The wrapper moves this open's plan to this open's handler (alkcall's concurrent-same-resource test pins that plans are never shared), the handler take()s it exactly once, and establisher-before-handler ordering is alkcall's wrapper guarantee (ADR-049 §1). The shared-slot race §2 described is unreachable by construction: there is no shared slot.
3. The handler pumps the pre-allocated handle. With a plan it calls drive_session_pre_allocated (new pub(crate) driver: the pumps directly, no validation pass). With plan: None — a no-establisher registration — it falls back to drive_session_pre_negotiated, whose inline validate-and-allocate keeps the full in-band error-frame vocabulary. That fallback is defense-in-depth for the assembly-layer freedom to register without an establisher, not a registered-producer path.
4. Consumer surface. TtySession::open_via_channels sees allocation failure as ChannelsOpen(CallFailed{ channel:open_failed, reason: dial_failed }) — a typed call error, branchable and retryable like every other establishment class. The 0x00 peek on the channel stream becomes a formality that no registered producer ever exercises; the pinned test flipped with the contract (allocate_failure_fails_open_as_dial_failed in testing.rs, plus the establisher unit gate establisher_allocates_and_maps_ failure_to_dial_failed in channels.rs).

The R-02 lifetime contract (the handler's JoinHandle tracks the data-plane lifetime) was already alktty's shape — the open handler awaits the driver inline in its spawned task — so the amendment adds no lifetime changes.

3. The direct-ALPN path is unchanged

TtyAdapter::handle / drive_session keep the wire-frame negotiation (ADR-001) and the full in-band error-frame vocabulary (unknown_backend, malformed_negotiation, allocate_failed, forbidden). Two transports, two contracts — the direct path has no open op to fail, and its 0x00-peek disambiguation is the ADR-001 wire-stable contract. The enforce_scope split from ADR-009 is unchanged (true direct, false channels — the registry's AccessControl is the channels scope gate).

4. Spec enrichment (review 006 E-02 + ADR-016)

tty_open_spec() gains:

• description — disclosed by services/list (the open op describes itself; the produced resource set stays OQ-40's deferred channel/resources/subscribe shape).
• An ErrorDefinition for channel:open_failed with the details.reason enum — so services/schema discloses the establishment-failure contract per ADR-016 (ADR-049 §3: "ALPN crates' open-op specs gain matching ErrorDefinition entries so services/schema discloses the failure contract").

5. Consumer surface

TtySession::open_via_channels failures after this ADR:

Failure	Where	Consumer-visible as
schema-invalid params	registry gate	ChannelsOpen(CallFailed{ INVALID_INPUT })
unparseable params (local fail-fast)	pre-open local parse	InvalidParams
malformed negotiation (schema-valid)	establisher	ChannelsOpen(CallFailed{ channel:open_failed, reason: handler_error })
unknown backend	establisher	ChannelsOpen(CallFailed{ channel:open_failed, reason: unknown_resource })
ownership denial	establisher	ChannelsOpen(CallFailed{ channel:open_failed, reason: handler_error })
allocation failure (amended — §2A)	establisher	ChannelsOpen(CallFailed{ channel:open_failed, reason: dial_failed })
establishment timeout	wrapper bound	ChannelsOpen(CallFailed{ channel:open_failed, reason: timeout })
ACL denial (scope)	registry gate	ChannelsOpen(CallFailed{ FORBIDDEN })
channel cap	wrapper check_open	ChannelsOpen(CallFailed{ channel:too_many_channels })

TtySessionError::ChannelsOpen now carries alkcall's typed ChannelOpenError verbatim (#[from]) instead of a flattened String — the N-1 fix applied at alktty's layer, so consumers branch on establishment_reason() without unwrapping strings.

Consequences

Positive:

• The phantom-channel workaround is retired: a semantically invalid open no longer allocates → succeeds → in-band-fails. Ledger, policy count, and manager state balance on every rejection.
• Retry policy / UX can branch: unknown_resource (bad config — don't retry), timeout (maybe retry), dial_failed (capacity/target refused — maybe retry; amended §2A, was the in-band allocate_failed).
• The consumer's open_via_channels failure is a typed call error — no peeking at the data stream for anything but the (now unreachable-from-registered-producers) error-frame formality.

Negative:

• Breaking (0.2.0): channels-path semantic failures change shape (NegotiationRejected{unknown_backend} → ChannelsOpen(CallFailed{ channel:open_failed})), and ChannelsOpen's payload changed. The direct path's failure surface is unchanged.
• The channel:open_failed reason codes the establisher emits join the wire-stable error set (ADR-049's one-way door).
• Amendment (0.3.0): allocation failure changed shape again — NegotiationRejected{ "allocate_failed" } (in-band) → ChannelsOpen(CallFailed{ channel:open_failed, reason: dial_failed }). The direct path's allocate_failed frame is unchanged (two transports, two contracts).

Door type

One-way (wire-visible). The establisher mapping fixes details.reason values for TTY's channels path — consumers branch on unknown_resource / handler_error / timeout, so re-mapping a failure class between reasons is a peer-breaking change. The establisher's internal validation order is a two-way door (implementation detail behind the fixed surface). ADR-009's "two-way for now" negotiation-location decision is unaffected — this ADR moves failure reporting, not the negotiation location.

References

• alkcall ADR-049 (the establisher, channel:open_failed, the typed client error — the upstream capability this ADR adopts)
• alkcall review 006 (E-01 the establishment gap; N-1 the typed client error; E-02 the discovery enrichment this ADR's spec enrichment adopts)
• ADR-009 (the open op's input is the negotiation; the R4 amendment's in-band error frames — shrunk to allocate_failed by this ADR)
• ADR-005 (kill-on-Drop — why a second establisher-side allocate would be unsound; avoided by construction in the §2A amendment — one allocate per open, consumed by the handler)
• ADR-001 (the §5 0x00 disambiguation — retained for the direct path; the channels-path peek is now a formality)
• ADR-002 (backend selection/allocation ownership)
• alkcall ADR-049 amendment 2 / review 007 R-01 (the Establishment plan payload — the upstream capability this ADR's §2A adopts)
• src/channels.rs — make_tty_establisher, AllocatedHandle, make_tty_open_handler, tty_open_spec
• src/session.rs — TtySessionError::ChannelsOpen, open_via_channels
• src/testing.rs — the pinned allocate_failure_fails_open_as_dial_failed test (superseded allocate_failure_still_arrives_in_band_on_channels_path)