Module wire 

The wire layer: the fixed envelope shape as a typed value, plus plural encodings exposed as descriptors (vtables of function pointers). Splits what was collapsed in core.rs — where byte-emitters implicitly defined the shape — so the shape is owned once (here) and the encodings vary independently. See docs/design/IO.md.

Two encodings, no JSON: text (the readable X = foo form — the default, human/shell-facing) and bson (binary, dense, typed — the machine-facing format). A host that wants JSON derives it from bson at the host boundary; the engine itself never serializes JSON. Term values inside bson are BinData(0x00) wrapping a copyterm::TermBuf — the same cell ABI the fact tables and copy_term/2 use, single-sourced in plg-shared::cell, lossless including cyclic terms. Because a binary format can’t coexist with streamed text bytes, bson forces capture mode; the encoding dictates the sink.

Why descriptors, not a trait. Codegen bakes a per-binary capability table — pointers to the descriptors the program declared via io_format/1 — and entry.rs dispatches through those pointers, never naming an encoder statically. Link-time --gc-sections then strips any encoder whose descriptor isn’t in the table.

Structs

EncoderDesc

An encoding as a vtable: a name plus the three operations the wire contract needs. #[repr(C)] so codegen can reference a descriptor by address and entry.rs can read its fields after dereferencing the pointer from the capability table. A #[no_mangle] static of this type per encoding (PLG_ENC_TEXT, PLG_ENC_BSON) is what codegen’s @plg_caps table points at; encoders not listed there are unreferenced and get dead-stripped.

Envelope

The fixed engine-output shape — the contract, made a type. Every encoding reads the same fields; only their byte encoding varies.

ParsedRequest

A parsed bson request document. limit is None when absent.

Enums

WireError

The two failure classes the engine distinguishes, carrying the message the wire contract puts on the wire. Callers construct the correct variant (Parse vs Runtime) so the distinction is honest on the wire even though today’s encoders collapse both to the same bytes — a future bson kind field will surface it. Callers map the class to their surface (exit codes 2/3 for the CLI); the message bytes come from core::run_query.

Statics

PLG_ENC_BSON

PLG_ENC_TEXT

The readable text wire encoding (default).

Functions

parse_bson_request

Parse a bson request document from buf. buf may be longer than the document (stdin may carry trailing bytes); only the leading document (delimited by its int32 length) is consumed. Returns the query and an optional limit.

write_atom_map_bson

Standalone --atoms bson output: {count: N, atoms: [...]} — just the atom map (program atoms only; no query has run, so no query-introduced atoms). For the case where a host wants the map once and its queries won’t introduce new atoms (docs/design/BSON_ATOMS.md).

write_atom_map_text

Standalone --atoms text output: id\tname per line (program atoms only).