From bc4a9b6024ad364e47cf6a2cb40abe6fe57d6810 Mon Sep 17 00:00:00 2001 From: "glm-5.3-flash" Date: Mon, 7 Sep 2026 10:04:44 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20align=20remaining=20alloc-failure=20ref?= =?UTF-8?q?erences=20with=20ADR-010=20=C2=A72A=20(prepublish=20review=20fo?= =?UTF-8?q?r=20v0.3.0)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - README.md ADR index: ADR-010 status notes the §2A amendment - ADR-009: amendment note records the §2A supersession (in-band path shrinks to nothing from registered producers) - ADR-010 Consequences: dial_failed replaces the stale in-band allocate_failed retry-policy bullet - AllocFailed doc comment + tty-backend.md: describe both failure surfaces (direct-path frame / channels-path dial_failed) --- docs/architecture/README.md | 2 +- .../decisions/009-channels-open-op-is-the-negotiation.md | 7 +++++++ .../decisions/010-channels-establisher-migration.md | 5 +++-- docs/architecture/tty-backend.md | 6 ++++-- src/backend.rs | 7 +++++-- 5 files changed, 20 insertions(+), 7 deletions(-) diff --git a/docs/architecture/README.md b/docs/architecture/README.md index 269d255..4222dbf 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -37,7 +37,7 @@ tty-specific and therefore not ported into alktty's ADR range). | [007](decisions/007-tty-inside-channels.md) | TTY Inside Channels — Sub-Streams, Not Wire Format | alknet ADR-077 | Accepted (**reversed by ADR-008** — kept for historical context) | | [008](decisions/008-channels-pure-channel-multiplexing.md) | Channels Pure Channel Multiplexing (8-Byte Header, No `stream_type`) | alknet ADR-093 | Accepted (amends alknet ADR-071/074; reverses ADR-007) | | [009](decisions/009-channels-open-op-is-the-negotiation.md) | The Channels Open Op's `input` Is the Negotiation | alktty-native | Accepted (resolves review #001 L1; amended by review #002 R4 — parse failure is a client-visible error frame; amended by ADR-010 — semantic failures move into the establisher) | -| [010](decisions/010-channels-establisher-migration.md) | Channels-Path Establishment Failures Move into an Establisher | alktty-native | Accepted (adopts alkcall 0.5.0 ADR-049; amends ADR-009's R4 amendment — in-band frames shrink to `allocate_failed`) | +| [010](decisions/010-channels-establisher-migration.md) | Channels-Path Establishment Failures Move into an Establisher | alktty-native | Accepted (adopts alkcall 0.5.0 ADR-049; amends ADR-009's R4 amendment; amended 2026-09-07 §2A for alkcall 0.6's plan payload — allocation moves into the establisher, no in-band frame from a registered producer) | ## Key Design Principles diff --git a/docs/architecture/decisions/009-channels-open-op-is-the-negotiation.md b/docs/architecture/decisions/009-channels-open-op-is-the-negotiation.md index c2c9418..ca5cef8 100644 --- a/docs/architecture/decisions/009-channels-open-op-is-the-negotiation.md +++ b/docs/architecture/decisions/009-channels-open-op-is-the-negotiation.md @@ -21,6 +21,13 @@ cannot carry the allocated handle across — see ADR-010 §2). The R4 tests that asserted the in-band frames for those classes now assert the call-error shape. +Amended 2026-09-07 (ADR-010 §2A, alkcall 0.6.0 — review 007 R-01): +`Establishment` gained its plan payload, so `allocate` also moved +into the establisher — the in-band error-frame path on this channel +shrinks to nothing from a registered producer (the frames remain the +defense-in-depth fallback for no-establisher registrations and the +direct path). See ADR-010 §2A. + ## Context Before this ADR, the channels path carried the negotiation twice. The diff --git a/docs/architecture/decisions/010-channels-establisher-migration.md b/docs/architecture/decisions/010-channels-establisher-migration.md index 05c0ded..50cd605 100644 --- a/docs/architecture/decisions/010-channels-establisher-migration.md +++ b/docs/architecture/decisions/010-channels-establisher-migration.md @@ -242,8 +242,9 @@ on `establishment_reason()` without unwrapping strings. 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), `allocate_failed` (capacity — - still distinguishable in-band). + 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. diff --git a/docs/architecture/tty-backend.md b/docs/architecture/tty-backend.md index 8b256ae..9a30b00 100644 --- a/docs/architecture/tty-backend.md +++ b/docs/architecture/tty-backend.md @@ -125,8 +125,10 @@ pub enum TtyError { - `AllocFailed` — the PTY couldn't be allocated, the docker exec failed to start, the SSH channel request was rejected. Returned by - `allocate()`; the adapter sends `{"error":"allocate_failed",...}` and - closes (tty-adapter.md §"Negotiation errors"). + `allocate()`; on the direct path the adapter sends + `{"error":"allocate_failed",...}` and closes (tty-adapter.md + §"Negotiation errors"); on the channels path the establisher maps it + to `channel:open_failed` / `dial_failed` (ADR-010 §2A). - `WaitFailed` — the backend couldn't reap the child / determine the exit code. Returned by the `exit_code` future; the adapter sends `{"type":"exit","code":-1}` (ADR-004 §4). diff --git a/src/backend.rs b/src/backend.rs index 705286b..2407c58 100644 --- a/src/backend.rs +++ b/src/backend.rs @@ -45,8 +45,11 @@ pub type BoxFuture = futures::future::BoxFuture<'static, T>; #[derive(Debug, thiserror::Error)] pub enum TtyError { /// The PTY couldn't be allocated, the docker exec failed to start, the - /// SSH channel request was rejected. Returned by `allocate()`; the - /// adapter sends `{"error":"allocate_failed",...}` and closes. + /// SSH channel request was rejected. Returned by `allocate()`; on the + /// direct path the adapter sends `{"error":"allocate_failed",...}` and + /// closes; on the channels path (alkcall 0.6, ADR-010 §2A) the + /// establisher maps it to `channel:open_failed` / + /// `details.reason == "dial_failed"`. #[error("allocate failed: {message}")] AllocFailed { message: String }, /// The backend couldn't reap the child / determine the exit code.