docs(arch): ADR-057 — alknet-tty does not depend on alknet-call (self-contained negotiation framing)
The earlier specs claimed alknet-tty reuses alknet-call's FrameFramedReader/FrameFramedWriter 'framing utility' (ADR-052 §6, ADR-003 Am. 1). A pre-implementation sanity check found this was unsound: FrameFramedReader::read_frame() is hardcoded to deserialize EventEnvelope — the length-prefix read and the type-specific deserialize are one entangled call, not a separable utility. alknet-tty's negotiation payload is a NegotiateRequest, not an EventEnvelope, so the claimed reuse did not exist in a usable form. ADR-057: alknet-tty implements its own ~30-line length-prefixed framing directly on tokio AsyncRead/AsyncWrite. The format coincides with alknet-call's framing by convention (both are length-prefixed JSON); the implementations are independent. alknet-tty depends on alknet-core only — no alknet-call dependency. The ~30 lines of framing is an idiom, not a domain abstraction worth a cross-crate dependency. Updates: - ADR-003 Amendment 2: clarifies alknet-tty does not depend on alknet-call; the Am. 1 protocol-foundation exception remains for alknet-http/agent/napi (actual type reuse), not alknet-tty. - ADR-052 §6: framing is self-contained in alknet-tty; format coincides by convention, not by code reuse. - overview.md: dependency block drops alknet-call; new 'Why no alknet-call dependency' subsection explains the unsound-reuse finding. - tty-wire.md, tty-backend.md, tty README, crates/tty/README.md, top-level README: ADR tables, Design Decisions tables, and dependency edges updated to reflect alknet-core-only dependency. - ADR-053, ADR-054: References updated to ADR-003 Am. 2 + ADR-057.
This commit is contained in:
1 parent
25f0f55592
commit
dbac972aaa
10 files changed
+297
-76
No files matched your search
@@ -16,17 +16,17 @@ The alknet-tty research (`docs/research/alknet-tty/phase-0-findings.md`)
|
||||
identified the `TtyBackend` trait as the inversion point. The guiding
|
||||
insight:
|
||||
|
||||
> A terminal session is not an SSH concern, or a Docker concern — it is a
|
||||
> terminal concern. SSH and Docker are just two backends that can allocate
|
||||
> a PTY.
|
||||
> A terminal session is not an SSH concern, or a Docker concern — it is
|
||||
> a terminal concern. SSH and Docker are just two backends that can
|
||||
> allocate a PTY.
|
||||
|
||||
The trait is what makes that insight load-bearing: alknet-tty defines the
|
||||
trait and the wire-format adapter; the backend crates (alknet-docker,
|
||||
The trait is what makes that insight load-bearing: alknet-tty defines
|
||||
the trait and the wire-format adapter; the backend crates (alknet-docker,
|
||||
alknet-ssh, alknet-tty-local) implement the trait. This preserves ADR-003's
|
||||
no-handler-depends-on-another-handler rule (amended by ADR-003 Amendment 1
|
||||
for protocol-foundation crates): alknet-tty depends on alknet-core;
|
||||
backend crates depend on alknet-tty for the trait; alknet-tty does not
|
||||
depend on any backend.
|
||||
no-handler-depends-on-another-handler rule: alknet-tty depends on
|
||||
alknet-core; backend crates depend on alknet-tty for the trait; alknet-tty
|
||||
does not depend on any backend (and, per ADR-057, does not depend on
|
||||
alknet-call either — the negotiation framing is self-contained).
|
||||
|
||||
### What the local-PTY POC discovered about the trait shape
|
||||
|
||||
@@ -403,9 +403,12 @@ impl doesn't break existing implementors); its return type
|
||||
- `/workspace/alknet-tty-poc/src/session.rs` — the adapter-side pump that
|
||||
consumes `TtyHandle`-shaped fields (the reference for how the adapter
|
||||
uses the trait)
|
||||
- [ADR-003](003-crate-decomposition.md) + Amendment 1 — no-handler-depends-
|
||||
on-another-handler; alknet-tty depends on alknet-core; backends depend
|
||||
on alknet-tty for the trait
|
||||
- [ADR-003](003-crate-decomposition.md) + Amendments 1 & 2 —
|
||||
no-handler-depends-on-another-handler; alknet-tty depends on
|
||||
alknet-core (no alknet-call per Am. 2 / ADR-057); backends depend on
|
||||
alknet-tty for the trait
|
||||
- [ADR-057](057-alknet-tty-no-alknet-call-dep.md) — alknet-tty does not
|
||||
depend on alknet-call (self-contained negotiation framing)
|
||||
- [ADR-007](007-bistream-type-definition.md) — `Connection`, `SendStream`,
|
||||
`RecvStream` (the adapter receives a `Connection`, accepts bidi streams,
|
||||
pumps per-session)
|
||||
|
||||
Reference in new issue
Block a user