alktunnels/docs/architecture/bast.md

status, last_updated

status	last_updated
draft	2026-09-07

alktunnels — BAST Document for the alk/tunnel Wire Format

This document is the BAST (Binary Abstract Syntax Tree) specification for the binary portions of the alk/tunnel wire format — per AGENTS.md convention 12, the mandatory UDP length-framing codec (ADR-003) is binary framing beyond pass-through, so the BAST document exists even though the format is trivial. It is a normative JSON document conforming to the BAST meta-schema at https://alk.dev/bast/v1/schema (JSON Schema Draft 2020-12); any Draft 2020-12 validator can check well-formedness.

alktunnels does not depend on alktype. The hand-rolled frame_datagram / DatagramReader (the src/wire.rs shape the POCs ran) is the runtime codec; this BAST document is the human-readable contract describing what those functions round-trip. If runtime validation against the BAST becomes desirable later, alktype becomes an optional dep and this document is there to feed it.

Scope

The alk/tunnel wire format is: a JSON open op on the channels call plane (a UTF-8 JSON object inside the channels envelope — not a binary layout; specified in wire.md §The Open Op and implemented by TunnelParams/tunnel_open_spec in the Rust source), and a binary data plane inside the channel BiStream.

Per the BAST format spec, a BAST document describes binary data layouts — not JSON payloads (validate_bytes vs validate_json). This document therefore covers only the data plane's binary framing:

1. The datagram frame ([len: u16 BE][datagram bytes]) — the UDP-substrate codec (ADR-003; mandatory, F-2). Stream substrates ride raw pass-through — zero tunnel-level framing, so there is nothing for BAST to describe there.

What this BAST deliberately does not cover:

• The open-op params JSON shape ({resource, substrate}) — UTF-8 JSON on the call plane; specified in ADR-001 and wire.md, implemented by TunnelParams.
• The channels 8-byte chunk header — the channels layer's own framing (alknet ADR-071/093); stripped transparently before the tunnel data plane sees bytes. Specified upstream, not here.
• The EOF sentinel — the channels-level zero-length chunk (upstream); the tunnel codec never emits it (that is the F-2 invariant).

The BAST document

{
  "$schema": "https://alk.dev/bast/v1/schema",
  "$defs": {
    "DatagramFrame": {
      "kind": "struct",
      "endian": "big",
      "fields": [
        { "name": "len",    "kind": "uint16" },
        { "name": "datagram", "kind": "bytes", "encoding": "length-prefixed", "maxLength": 65535 }
      ]
    }
  }
}

Annotations

DatagramFrame — binary, exact

Maps 1:1 to the on-wire bytes. len as uint16 big-endian (2 bytes) followed by exactly len bytes of datagram payload. The zero-byte payload (len == 0) is a legal empty datagram — a real datagram, NOT EOF (the F-2 invariant; EOF is the channels-level sentinel, outside this codec). The maxLength: 65535 encodes the u16 bound; the codec rejects framing a larger datagram at frame time (Oversize) rather than wrapping the length field.

One frame per datagram, in both directions of the channel BiStream. Frames are self-delimiting on the byte stream; a decoder is an incremental state machine across chunk boundaries (chunk splitting/batching is transparent — forward POC, 7-byte chunk splits verified).

Layering note

The codec sits at the substrate/pump boundary (the establisher wraps the dialed UDP half in the framed adapter — ADR-003's placement, so the pump handler stays substrate-agnostic). The BAST describes the wire inside the BiStream only; the pump/pump_bidi contract (ADR-050) is upstream's, not re-specified here.

References

• ADR-003 (the codec decision + F-2 mandate), ADR-001 (the JSON open-op shape — outside BAST scope)
• wire.md (the normative prose; §Normative byte diagrams)
• alktty tty-bast.md (the BAST precedent — same meta-schema, same "binary framing only" scope rule)
• Forward POC docs/research/poc-summary.md §3 (the codec's validation matrix); reverse POC docs/research/reverse-poc-summary.md §F-2 (the mandate)