Crate brink_format

Expand description

Binary interface between the brink compiler and runtime.

This crate defines the types shared across the compiler/runtime boundary: DefinitionId, opcodes, value types, line templates, and the top-level StoryData container.

brink-runtime depends ONLY on this crate — nothing else from brink.

no_std + alloc: this crate builds without the standard library when the default std feature is disabled (see docs/no-std-portability.md). inkt/inkt-write (the .inkt text format, used by the intl pipeline) are not part of the no_std surface — pest is std-oriented.

Modules§

manifest_field_names: Shared JSON field-name constants for the host manifest file (docs/host-capability-manifest.md) — the single on-disk manifest that two independent Rust types deserialize, each reading only the subset of keys it needs (issue #911, BH follow-up deliverable 1):

Structs§

AddressDef: An address pointing to a specific byte offset within a container.
AddressPath: Maps a qualified author path (e.g. knot, knot.stitch, knot.label, knot.stitch.label) to the DefinitionId it addresses.
AliasEntry: One old→new DefinitionId rename record (M-3, docs/modules-spec.md §5): the compiler emits one of these per #@was(old_name) directive — on a module, one entry per definition the renamed module currently owns; on a single definition, one entry for it. Rehydration (brink-runtime’s load_state) consults the table only on the miss path: a saved fn token, divert value, or visit-count key that the current program doesn’t recognize is looked up here before being treated as genuinely gone.
CallAtom: A single call atom in an effect row’s direct part (docs/effects-spec.md §2/§11): the name of an EXTERNAL binding (a call-kind), plus its capability-parameter slot and a reserved handle-parameter slot.
ChoiceFlags: Flags packed into a BeginChoice instruction.
ClosureEnvEntry: One bound-arg entry in a ClosureValue’s env.
ClosureValue: The payload of a Value::Closure — the fn token plus its bound-arg prefix (docs/t1c-spec.md §1/§6).
ContainerDef: A compiled container (knot, stitch, gather, or anonymous flow block).
ConventionAttachFieldDef: Wire mirror of brink_ir::ConventionAttachField.
ConventionEntryDef: One @[convention] handler’s projected shape on the wire. Mirrors brink_ir::ConventionProjectionEntry, with one deliberate exception: there is no disposition field here, because every wire entry is, today, the single existing ElementDisposition::Call case — this format has no other disposition to distinguish yet, unlike the in-process type, which carries the field explicitly (ConventionProjectionEntry::disposition’s own “read what happened, don’t infer it from absence” reasoning) so a future second disposition doesn’t need a wire bump to become visible in-process. Adding a second disposition to this wire shape is exactly the kind of section-local-version bump CONVENTIONS_PROJECTION_WIRE_VERSION exists for — until then, this one field’s omission is a considered simplification of a currently-single-variant enum, not evidence of a lossy conversion elsewhere.
ConventionsProjectionDef: The conventions projection, as it would ride the wire: every @[convention] handler declared in the project’s one configured conventions module, ascending by order — the same shape brink_ir::ConventionsProjection carries in-process, with source spans stripped (a .inkb-loaded host has no source text to point a range at) and disposition intentionally not carried — see ConventionEntryDef’s own doc for why.
CountingFlags: Container-level structural flags: what the runtime counts for a container, plus the FS-3 “invisible” marker.
DebugContainerTable: One container’s DebugInfo table (docs/debugger-spec.md §2.2): the DebugInfo section’s Nth DebugContainerTable describes the container at StoryData::containers[N] — addressed by the same container_idx the runtime’s ContainerPosition uses, lockstep with the Containers section, no DefinitionId lookup needed on the read path.
DebugEntry: One row in a container’s DebugInfo entry table (docs/debugger-spec.md §2.2): maps a bytecode offset (within that container’s own bytecode) to the source range it was lowered from. Entries for one container are sorted ascending by bytecode_offset so a reader can floor-lookup via binary search.
DebugFileEntry: One entry in the DebugInfo section’s section-local file table (docs/debugger-spec.md §2.3). Index 0 is always the reserved synthetic sentinel (§2.5) — surface = Synthetic, path = "" — real files start at index 1. Paths are project-root-relative (root_relative_key), not process-cwd-relative or absolute.
DebugInfoSection: The DebugInfo section (docs/debugger-spec.md §2, .inkb tag 0x11): bytecode-offset → source-range map, plus the section-local file table it’s keyed against. Carried on crate::StoryData::debug_info as Option — None when not requested (dev/studio compiles and an explicit CLI debug flag opt in; release export never does, §1.2 ship policy) — distinct from the other “always present, possibly empty” section types, because presence here tracks whether debug info was requested, not merely whether any entry was produced.
DebugLocalEntry: One row in a container’s DebugInfo locals table (docs/debugger-spec.md §3): a VM temp slot’s declared name, and optionally the source range it was declared at (for slot-reuse disambiguation). D7’s payload (docs/debugger-spec.md §3, issue #3185) — D6 emits the structural framing (an empty locals per container) but does not populate real entries; the wire shape ships now so D7 adds data without a layout change.
DefinitionId: A tagged 64-bit identifier for any definition in a compiled story.
DirectEffects: The direct part of a factored effect row (docs/effects-spec.md §7/§11): the atoms a definition (and everything it statically calls) may perform, independent of any dispatch-cell narrowing. Mirrors the analyzer’s flat EffectRow, lowered to wire vocabulary (cells as DefinitionIds, call kinds as CallAtoms).
DispatchEntry: A per-dispatch entry in a factored effect row (docs/effects-spec.md §7): the row a call through a dispatch cell contributes, whether that dispatch is runtime-narrowable (its cell is not in the entry’s own write set), and the static fallback row used when narrowing does not apply.
EffectRowEntry: One entry in the EffectRows DefinitionId → row table (T2-3, docs/effects-spec.md §11, docs/format-v4-rfc.md §2 EffectRows reservation): a factored effect row for one definition.
ExternalFnDef: An externally-bound function definition.
FrameShapeDef: The name-keyed frame shape for one await site (docs/flow-suspension-spec.md §4/§11): the static description of which locals cross the park at that site, so the runtime knows what to spill on park and restore on wake.
GlobalVarDef: A global variable definition.
InkbIndex: Parsed header + offset table from an .inkb file.
InktParseError: Error returned when parsing .inkt text fails.
LineEntry: One entry in a container’s line table.
LineFlags: Whitespace characteristics of a line, precomputed at compile time.
LineId: A reference to a specific line within a container.
LineVariantGroup: One line-variant group (stage 1 of the shared-alternatives track, issue #3273): the record that ties dims.iter().product() consecutive LineEntrys in a scope’s line table back to ONE authored source line whose inline alternatives were enumerated at recognition time.
ListDef: A list (enum-like set) definition.
ListItemDef: A single list item definition.
ListValue: An ink list value: a set of list items plus their origin list definitions.
LoadReport: What Story::load_state couldn’t apply, so a host can surface it rather than have data silently vanish. Globals whose name no longer exists are dropped (no slot to hold them) and reported here. Visit/turn counts are never dropped — counts for scopes the current program lacks are retained harmlessly (unused until/unless the scope returns), so they aren’t reported except when the miss-path alias lookup (M-3, docs/modules-spec.md §5) still can’t place them — see unresolved_renames for a named scope, or anonymous_states_dropped for an anonymous one.
LocaleData: Complete locale overlay data from a .inkl file.
LocaleLineEntry: A locale line entry — content + optional audio, no source metadata.
LocaleScopeTable: A per-scope locale line table.
NameId: An index into the story name table.
OrderedMap: remove shifts later entries down. Lookups are linear; that is the intended trade for small maps and stable ordering.
ParamMeta: Name + mode of one declared parameter of a container (T1c, docs/t1c-spec.md §6). See ContainerDef::params.
ProjectionValue: The payload of a Value::Projection — the root cell plus its ordered segment chain (docs/t1e-spec.md §1/§3).
SaveState: A persistent, name-keyed snapshot of a story’s game state.
ScopeLineTable: Per-scope line table, stored separately from ContainerDef for locale overlay swapping (.inkl).
SectionEntry: An entry in the .inkb offset table.
ShapeId: Identifies a struct shape (TM-4, docs/typed-mode-spec.md §6) within the compiled story’s StructShapes section (docs/format-spec.md, section tag 0x0C).
SlotInfo: Metadata for a single interpolation slot in a template line.
SourceLocation: Source location of a line in the original .ink file.
StaticSite: Where a static-operand instruction’s operand sits: buf[operand..end] holds the DefinitionId (or the linked layer’s replacement for it), and end is the offset of the next instruction.
StoryData: The top-level compiled story: everything the runtime needs to execute.
StructShapeDef: A STRUCT shape definition (TM-4, docs/typed-mode-spec.md §6; StructShapes section, docs/format-spec.md tag 0x0C).
SuspendedFlow: The FlowFrame — a parked flow’s durable, recompile-stable representation (docs/flow-suspension-spec.md §2, RULED). No instruction offsets ever serialize; recompile-stability rides container/DefinitionId identity, the same contract as the rest of SaveState, #@was, and fn tokens.
TargetSite: Where a static-target instruction’s operand sits: buf[operand..end] holds the DefinitionId (or the linked layer’s replacement for it), and end is the offset of the next instruction.
VisitEntry: One visit/turn-count entry: a scope id and its count, plus (when the scope is a named knot/stitch) an advisory author path for human inspection. The id is the load key; path is cosmetic.
WakePolicy: A parked flow’s wake policy (docs/flow-suspension-spec.md §2 point 4): await-site id + condition fn token + host-source discriminant, all name-stable. See docs/effects-spec.md §13.1 for the wake contract this plugs into (persistent-by-default policies, wake_once, host cancellation) — that contract’s runtime enforcement is FS-3/FS-4 scope; this type only carries the wire shape.
WeightedValue: The payload of Value::Map: an insertion-ordered map with scalar keys.

Enums§

BinaryKind: The binary operator a fused superinstruction applies (docs/optimizer-peephole.md §1). One byte on the wire; the mnemonic is what .inkt prints. Exactly the operators that have a plain two-operand opcode of their own — a fused form is always spelled out as that opcode preceded by PushInt and/or followed by JumpIfFalse.
CapabilityParam: The capability-parameter slot carried by every call atom in a factored effect row (T2-3, docs/effects-spec.md §11; ruled 2026-07-14, docs/t1d-spec.md §7).
CollectOp: The collections+ operation selected by an Opcode::Collect instruction’s kind byte (NS-A7, docs/stdlib-spec.md §8, issue #1113).
ConventionAttachDef: Wire mirror of brink_ir::ConventionAttachSchema — issue #2111 finding 1’s resolved field list, carried all the way to the wire shape rather than collapsing back to a bare name.
ConventionModeDef: Wire mirror of brink_ir::ConventionMode.
DecodeError: Errors that can occur when decoding from bytes.
DefinitionTag: Tag discriminant stored in the high byte of a DefinitionId.
FileSurface: Which frontend parsed a DebugInfo file-table entry’s file (docs/debugger-spec.md §2.3) — KindToken::raw is frontend-private (two independent ProvenanceResolver numberings), so a reader must know which resolver applies before interpreting an entry’s kind_token. Recorded once per file (not per entry) since surface is a property of where the code came from, constant for every entry pointing at that file.
GlobalKind: The static-global instructions: each carries exactly one DefinitionId operand naming the global variable it reads or writes. PushVarPointer is deliberately not one — its operand becomes a Value::VariablePointer the story can hold and pass around, so it must stay an id.
LineContent: The content of a single output line — either a plain string or a template with interpolation slots and plural selects.
LinePart: One segment of a LineTemplate.
MapKey: A scalar key for a Value::Map.
Opcode: A single VM instruction with its operands.
PluralCategory: CLDR plural category.
ProjSegment: One path-projection segment (docs/format-v4-rfc.md §1: segments: 0 = index i32, 1 = key value). Segment kind 2 = range is RESERVED and never constructed in T1e (icebox #829 — sequence slices/ranges).
SchemaTypeDef: Wire mirror of brink_ir::SchemaTypeShape.
SectionKind: Identifies a section within an .inkb file.
SelectKey: The key for matching a branch in a LinePart::Select.
SeqVerbOp: The fn-value verb selected by an Opcode::SeqVerb instruction’s kind byte (docs/stdlib-spec.md §4, issue #1679).
SequenceKind: The kind of sequence/shuffle container.
StaticKind: Every instruction whose sole DefinitionId operand is static — a jump or call address, or a global variable — as Opcode::peek_static classifies it.
TargetKind: The static-target instructions: each carries exactly one DefinitionId operand, and that operand names the address the instruction jumps to or calls. See Opcode::peek_target.
TowerOp: The tower operation selected by an Opcode::Tower instruction’s kind byte (NS-A8, docs/tower-mini-spec.md; docs/stdlib-spec.md §2b).
Value: A runtime value in the ink VM.
ValueType: The runtime type of a Value.
WakeSource: The wake policy’s host-source discriminant (docs/flow-suspension-spec.md §2 point 4; docs/effects-spec.md §13.1). FS-1 records the discriminant only — the host-side wake plumbing (wake_when, dormant spawn, cancellation-to-false) is FS-4 scope; today only Self::Condition is ever compiler-produced, but the format reserves Self::Host for the host-driven wake sources §3 names as a future (PROPOSED-only) ink spelling, so the wire shape doesn’t need a breaking change to add it later.

Constants§

CONVENTIONS_PROJECTION_WIRE_VERSION: Section-local encoding version — independent of the whole-.inkb VERSION, matching every other section-local-versioned table (EffectRows, AliasTable, FrameShapes) so this section’s own encoding can grow without a format-wide bump once it is wired in.
DEBUG_FLAG_IS_STMT: flags bit 0: this entry marks a recommended stop location / the start of a statement (docs/debugger-spec.md §2.1’s DWARF-is_stmt design). v1 sets this on every entry (statement-level rows only); a later expression-level entry arrives with this bit unset, additively — no version bump, no reader change.
DEBUG_FLAG_PROLOGUE_END: flags bit 1: this entry’s own bytecode_offset is the prologue-end landing point for a breakpoint set on the enclosing container (docs/debugger-spec.md §2.4) — past any leading parameter-binding DeclareTemps / choice-output prologue bytes. At most one entry per container carries this bit.
DEBUG_FLAG_RESERVED_MASK: Bits 2–7 of flags are reserved. Per docs/debugger-spec.md §2.2’s explicit, ruled departure from this format’s default strict-rejection posture, a DebugInfo reader must ignore any reserved bit it does not recognize rather than reject the entry — this constant exists so callers can mask deliberately (e.g. a round-trip test asserting v1 never sets a reserved bit) without hand-writing the mask twice.
MAX_DECODE_DEPTH: Maximum nesting depth permitted when decoding VAL_ARRAY/VAL_MAP values. Generous for legitimate data but bounds worst-case recursion so a crafted file of nested single-element arrays (~5 bytes/level) cannot stack-overflow the reader (CLAUDE.md “guard against unbounded growth”; issue #553).
SAVE_FORMAT_VERSION: Current SaveState format version. Bump when the format changes (independent of the story’s own content); version lets a loader migrate.
SUSPENDED_FLOW_SECTION_VERSION: Current suspended-flow section version, versioned independently of SAVE_FORMAT_VERSION (docs/flow-suspension-spec.md §9 FS-1: “one new suspended-flow section, section-locally versioned”). Bump when the SuspendedFlow shape itself changes; the rest of SaveState is unaffected.

Traits§

PluralResolver: Trait for resolving plural categories at runtime.

Functions§

assemble_inkb: Assemble a complete .inkb file from pre-encoded section buffers.
content_hash: Compute a stable hash of source text — FNV-1a, 64-bit, over the UTF-8 bytes.
read_conventions_projection: Read a conventions-projection section written by write_conventions_projection. buf/offset are a raw cursor, not an .inkb-indexed section range — this codec is not wired into crate::inkb::InkbIndex yet (see this module’s own doc).
read_inkb: Decode a StoryData from .inkb binary format.
read_inkb_index: Parse the .inkb header and offset table without touching section data.
read_inkl: Decode a LocaleData from .inkl binary format.
read_inkt: Parse .inkt text into a StoryData.
read_section_address_paths: Read the address-paths section using a pre-parsed index.
read_section_addresses: Read the addresses from a complete .inkb file using its index.
read_section_alias_table: Read the M-3 AliasTable section (docs/modules-spec.md §5) from a complete .inkb file using its index. Absent section (a pre-M-3 file, or a story with no #@was directives) decodes as empty, mirroring read_section_literal_pool. The section-local version byte is checked independently of the whole-file VERSION — see [ALIAS_TABLE_SECTION_VERSION].
read_section_containers: Read the containers from a complete .inkb file using its index.
read_section_debug_info: see crate::StoryData::debug_info’s doc for why presence itself is meaningful here.
read_section_effect_rows: Read the T2-3 EffectRows section (docs/effects-spec.md §11) from a complete .inkb file using its index. Absent section (converter output, or a story compiled before this slice) decodes as empty, mirroring read_section_alias_table. The section-local version byte is checked independently of the whole-file VERSION — see [EFFECT_ROWS_SECTION_VERSION].
read_section_externals: Read the externals from a complete .inkb file using its index.
read_section_frame_shapes: Read the FS-3 FrameShapes section (docs/flow-suspension-spec.md §4/§11) from a complete .inkb file using its index. Absent section (every story compiled behind the E052 fence, and all converter output) decodes as empty, mirroring read_section_visibility. The section-local version byte is checked independently of the whole-file VERSION — see [FRAME_SHAPES_SECTION_VERSION].
read_section_line_tables: Read the line tables from a complete .inkb file using its index.
read_section_list_defs: Read the list definitions from a complete .inkb file using its index.
read_section_list_items: Read the list items from a complete .inkb file using its index.
read_section_list_literals: Read the list literals from a complete .inkb file using its index.
read_section_literal_pool: Read the T1b literal pool from a complete .inkb file using its index. Absent section (older-shaped buffer within the same version) decodes as empty, mirroring read_section_list_literals.
read_section_name_table: Read the name table from a complete .inkb file using its index.
read_section_struct_shapes: Read the TM-4 StructShapes section from a complete .inkb file using its index. Absent section decodes as empty, mirroring read_section_literal_pool.
read_section_variables: Read the variables from a complete .inkb file using its index.
read_section_visibility: Read the M-2b Visibility section (tag 0x0E) from a complete .inkb file using its index — the DefinitionIds of every #@private definition. Absent section decodes as empty (the all-public common case), mirroring read_section_struct_shapes.
write_conventions_projection: Write the conventions-projection section (no header framing beyond its own section-local version byte, matching CONVENTIONS_PROJECTION_WIRE_VERSION): entry count, then each entry in the order given. Callers sort/dedupe before calling — this function trusts its input’s order, the same posture every writer in this crate takes toward its own table.
write_inkb: Encode a StoryData into the .inkb binary format with sectioned header.
write_inkl: Encode a LocaleData into the .inkl binary format.
write_inkt: Write the textual (.inkt) representation of a compiled story.
write_section_address_paths: Write the address-paths section (no header framing).
write_section_addresses: Write the addresses section (no header framing).
write_section_alias_table: Write the M-3 AliasTable section (no header framing): a one-byte section-local version, then a flat list of old→new DefinitionId pairs (docs/modules-spec.md §5). Entries are written in the order given — callers sort by old for the runtime’s binary-search lookup.
write_section_containers: Write the containers section (no header framing).
write_section_debug_info
write_section_effect_rows: Write the T2-3 EffectRows section (no header framing): a one-byte section-local version, then the DefinitionId → row table of factored effect rows (docs/effects-spec.md §11). One entry per knot/stitch — the host’s resume-scheduling estimate (§12.1). Entries are written in the order given; callers sort by def for determinism.
write_section_externals: Write the externals section (no header framing).
write_section_frame_shapes: Write the FS-3 FrameShapes section (no header framing): a one-byte section-local version, then one entry per await site (docs/flow-suspension-spec.md §4/§11) — the site’s stable DefinitionId (the synthesized continuation container id) followed by its name-keyed crossing-local slots. Entries are written in the order given; callers sort by site for determinism. Callers emit this section only when non-empty.
write_section_line_tables: Write the line tables section (no header framing).
write_section_list_defs: Write the list definitions section (no header framing).
write_section_list_items: Write the list items section (no header framing).
write_section_list_literals: Write the list literals section (no header framing).
write_section_literal_pool: Write the T1b literal pool section (no header framing) — a flat list of content-hash-deduplicated constant Values referenced by PushLiteral(idx) (docs/format-v4-rfc.md §2). Each entry uses the existing generic encode_value (the same recursive VAL_ARRAY/VAL_MAP tree encoding as a GlobalVarDef default).
write_section_name_table: Write the name table section (no header framing).
write_section_struct_shapes: Write the TM-4 StructShapes section (no header framing): one entry per declared STRUCT — shape id, name, then its ordered field NameIds (docs/format-v4-rfc.md §2). Empty (count 0) until a compiler milestone emits struct declarations — see the PR description’s scope note.
write_section_variables: Write the variables section (no header framing).
write_section_visibility: Write the visibility section (no header framing): a count followed by the DefinitionId of every #@private definition (M-2b). Callers only emit this section when private_defs is non-empty.

Type Aliases§

LineTemplate: A sequence of literal and dynamic parts that compose an output line.