docs: fix tty-bast.md to cover only binary framing, not JSON payloads

The previous BAST document modeled the JSON payloads (NegotiateRequest,
ControlMessage and its resize/signal/eof/exit variants, TerminalParams)
as BAST struct/union definitions with uint16/int32 fields. That was a
category error: BAST describes binary data layouts, and per the BAST
format spec itself, "a BAST document cannot validate a JSON payload."
The control and negotiation payloads on the wire are UTF-8 JSON text
serialized via serde_json, not struct-encoded binary — the uint16/int32
field widths implied a binary encoding that does not exist on the wire
and would have misled any generated validator.

The rewrite keeps only the genuinely-binary framing layer:

- ChunkHeader (5-byte: stream_type u8 + length u32 BE)
- StreamType enum (name->index table; documented deviation: on-wire
  is uint8, not BAST's standard u32 enum index)
- Chunk (header + length-prefixed bytes payload)
- NegotiationFrame (4-byte BE length prefix + UTF-8 JSON body,
  modeled as bytes since the body's JSON interpretation is above the
  BAST layer)

The JSON shapes (NegotiateRequest, ControlMessage, TerminalParams)
remain specified in tty-wire.md and implemented by the Rust source
(src/negotiation.rs, src/control.rs), which are the source of truth
for those payloads. Cross-references in tty-wire.md, overview.md, and
README.md updated to reflect the simplified scope.

The drift-detection test (project plan "Risk: BAST schema drift")
still works unchanged — it asserts the StreamType enum values match
wire.rs's STREAM_* constants, and that enum is retained.

Docs-only change; no Rust source changes.

Verification:
- cargo test --all-features -> 122 tests pass (unchanged)
- cargo clippy --all-targets --all-features -- -D warnings -> clean
- cargo fmt --check -> clean
- cargo doc --no-deps -> no new warnings (9 pre-existing rustdoc link
  warnings in src/, unchanged)
- BAST JSON block parses as valid JSON (4 : ChunkHeader,
  StreamType, Chunk, NegotiationFrame)
This commit is contained in:
2026-08-17 11:20:23 +00:00
parent b84c67bd8a
commit da0d395ab3
4 changed files with 113 additions and 239 deletions
+8 -4
View File
@@ -246,10 +246,14 @@ PTY allocation code. See [ADR-003](decisions/003-local-backend-placement.md).
/ `STREAM_CTRL_OUT` halves, JSON control messages), sentinels, and
the fixed-channel-set rationale.
- **[tty-bast.md](tty-bast.md)** — the BAST (Binary Abstract Syntax
Tree) document for the `alk/tty` wire format; a normative JSON spec
conforming to the BAST meta-schema at
`https://alk.dev/bast/v1/schema`, validatable by any JSON Schema
Draft 2020-12 validator.
Tree) document for the binary framing layer of the `alk/tty` wire
format (the 5-byte chunk header and the negotiation frame's 4-byte
length prefix); a normative JSON spec conforming to the BAST
meta-schema at `https://alk.dev/bast/v1/schema`, validatable by any
JSON Schema Draft 2020-12 validator. The JSON payloads
(`NegotiateRequest`, `ControlMessage`, `TerminalParams`) are
specified in `tty-wire.md` and the Rust source, not in the BAST —
BAST describes binary layouts, not JSON shapes.
- **[tty-backend.md](tty-backend.md)** — the `TtyBackend` trait,
`TtyParams`, `TtyHandle`, `TtyControl`. The inversion point between
the wire-format adapter and the backends. Carries REQ-TTY-01