docs: align remaining alloc-failure references with ADR-010 §2A (prepublish review for v0.3.0)

- 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)
This commit is contained in:
2026-09-07 10:04:44 +00:00
parent af9dbaedea
commit bc4a9b6024
5 changed files with 20 additions and 7 deletions
+1 -1
View File
@@ -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) | | [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) | | [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) | | [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 ## Key Design Principles
@@ -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 tests that asserted the in-band frames for those classes now assert
the call-error shape. 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 ## Context
Before this ADR, the channels path carried the negotiation twice. The Before this ADR, the channels path carried the negotiation twice. The
@@ -242,8 +242,9 @@ on `establishment_reason()` without unwrapping strings.
open no longer allocates → succeeds → in-band-fails. Ledger, policy open no longer allocates → succeeds → in-band-fails. Ledger, policy
count, and manager state balance on every rejection. count, and manager state balance on every rejection.
- Retry policy / UX can branch: `unknown_resource` (bad config — don't - Retry policy / UX can branch: `unknown_resource` (bad config — don't
retry), `timeout` (maybe retry), `allocate_failed` (capacity retry), `timeout` (maybe retry), `dial_failed` (capacity/target
still distinguishable in-band). refused — maybe retry; amended §2A, was the in-band
`allocate_failed`).
- The consumer's `open_via_channels` failure is a typed call error — - The consumer's `open_via_channels` failure is a typed call error —
no peeking at the data stream for anything but the (now no peeking at the data stream for anything but the (now
unreachable-from-registered-producers) error-frame formality. unreachable-from-registered-producers) error-frame formality.
+4 -2
View File
@@ -125,8 +125,10 @@ pub enum TtyError {
- `AllocFailed` — the PTY couldn't be allocated, the docker exec failed - `AllocFailed` — the PTY couldn't be allocated, the docker exec failed
to start, the SSH channel request was rejected. Returned by to start, the SSH channel request was rejected. Returned by
`allocate()`; the adapter sends `{"error":"allocate_failed",...}` and `allocate()`; on the direct path the adapter sends
closes (tty-adapter.md §"Negotiation errors"). `{"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 - `WaitFailed` — the backend couldn't reap the child / determine the
exit code. Returned by the `exit_code` future; the adapter sends exit code. Returned by the `exit_code` future; the adapter sends
`{"type":"exit","code":-1}` (ADR-004 §4). `{"type":"exit","code":-1}` (ADR-004 §4).
+5 -2
View File
@@ -45,8 +45,11 @@ pub type BoxFuture<T> = futures::future::BoxFuture<'static, T>;
#[derive(Debug, thiserror::Error)] #[derive(Debug, thiserror::Error)]
pub enum TtyError { pub enum TtyError {
/// The PTY couldn't be allocated, the docker exec failed to start, the /// The PTY couldn't be allocated, the docker exec failed to start, the
/// SSH channel request was rejected. Returned by `allocate()`; the /// SSH channel request was rejected. Returned by `allocate()`; on the
/// adapter sends `{"error":"allocate_failed",...}` and closes. /// 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}")] #[error("allocate failed: {message}")]
AllocFailed { message: String }, AllocFailed { message: String },
/// The backend couldn't reap the child / determine the exit code. /// The backend couldn't reap the child / determine the exit code.