brink_format/
story.rs

1use alloc::string::String;
2use alloc::vec::Vec;
3
4use crate::definition::{
5    AddressDef, AddressPath, AliasEntry, ContainerDef, EffectRowEntry, ExternalFnDef,
6    FrameShapeDef, GlobalVarDef, ListDef, ListItemDef, ScopeLineTable, StructShapeDef,
7};
8use crate::id::DefinitionId;
9use crate::value::ListValue;
10
11/// The top-level compiled story: everything the runtime needs to execute.
12#[derive(Debug, Clone, PartialEq)]
13pub struct StoryData {
14    pub containers: Vec<ContainerDef>,
15    /// Per-scope line tables. Each scope (root, knot, stitch) gets one table
16    /// shared by all containers within that scope.
17    pub line_tables: Vec<ScopeLineTable>,
18    pub variables: Vec<GlobalVarDef>,
19    pub list_defs: Vec<ListDef>,
20    pub list_items: Vec<ListItemDef>,
21    pub externals: Vec<ExternalFnDef>,
22    /// Address definitions mapping IDs to byte offsets within containers.
23    pub addresses: Vec<AddressDef>,
24    /// Qualified-path → address-target table. The single source of truth for
25    /// [`Program::find_address`](../../brink_runtime/struct.Program.html#method.find_address);
26    /// empty for legacy/converter output (the linker then falls back to
27    /// deriving scope paths from container names).
28    pub address_paths: Vec<AddressPath>,
29    /// Interned name strings, indexed by [`NameId`](crate::id::NameId).
30    pub name_table: Vec<String>,
31    /// List literal values referenced by `PushList(idx)` opcodes.
32    pub list_literals: Vec<ListValue>,
33    /// The T1b `LiteralPool` (`docs/format-v4-rfc.md` §2): content-hash
34    /// deduplicated constant values referenced by `PushLiteral(idx)` opcodes.
35    /// Distinct from `list_literals`/`PushList` — this is additive new
36    /// surface for T1b collection literals, not a replacement (the RFC's
37    /// `ListLiterals` absorption is a separate, larger migration; see the
38    /// T1b-2 PR description).
39    pub literal_pool: Vec<crate::value::Value>,
40    /// The TM-4 `StructShapes` table (`docs/format-spec.md` section tag
41    /// `0x0C`): one entry per declared `STRUCT`, indexed by
42    /// [`crate::value::ShapeId`]. Referenced by `RecordNew`/static
43    /// `RecordGet`/`RecordSet` opcodes and by `Value::Record` values in the
44    /// literal pool, globals, and the transcript.
45    pub struct_shapes: Vec<StructShapeDef>,
46    /// `DefinitionId`s of every `#@private` definition (M-2b,
47    /// `docs/modules-spec.md` §4 boundary rule 2). Sorted ascending by raw id
48    /// for determinism. Empty for the entire pre-modules / all-public world,
49    /// in which case the `.inkb` `Visibility` section (tag `0x0E`) is omitted
50    /// entirely — so public-only stories stay byte-identical.
51    ///
52    /// This is the complement encoding: public is the default, private names
53    /// are enumerated (mirroring how `#@local` scope defaults are carried).
54    /// The runtime builds a lookup set from it and refuses host **semantic**
55    /// access (variable get/set, entry lookup, function eval) to these defs;
56    /// host **persistence** (save/load/journal/replay) ignores it and sees
57    /// everything (§4 boundary rule 2).
58    pub private_defs: Vec<DefinitionId>,
59    /// The M-3 `AliasTable` (`docs/modules-spec.md` §5, format section tag
60    /// `0x0F`): old→new `DefinitionId` rename records emitted from
61    /// `#@was(old_name)` directives on modules and definitions. Sorted by
62    /// `old` for the runtime's binary-search miss-path lookup. Empty for
63    /// every story that uses no `#@was` — including the entire pre-M-3
64    /// corpus and converter output.
65    pub alias_table: Vec<AliasEntry>,
66    /// The T2-3 `EffectRows` table (`docs/effects-spec.md` §11, format section
67    /// tag `0x0D`): one factored effect row per knot/stitch — the host's
68    /// resume-scheduling estimate (§12.1). **Additive metadata**: the runtime
69    /// does not consume rows yet (`sleep`/narrowing are the future clients), so
70    /// a story that carries rows runs byte-identically to one that does not.
71    /// Empty for converter output and any story compiled before this slice.
72    /// Sorted by `def` (ascending raw id) for determinism.
73    pub effect_rows: Vec<EffectRowEntry>,
74    /// The FS-3 `FrameShapes` table (`docs/flow-suspension-spec.md` §4/§11,
75    /// `.inkb` section tag `0x10`): one [`FrameShapeDef`] per `await` site —
76    /// the name-keyed static description of which locals cross the park, so
77    /// the runtime knows what to spill/restore around a suspension. Sorted by
78    /// `site` (ascending raw id) for determinism.
79    ///
80    /// **Reserved-through-fence**: additive metadata the runtime does not
81    /// consume yet, and — because the E052 `await` lowering fence stands
82    /// (FS-3c) — never populated by compilation today. Empty for every story
83    /// compiled today and all converter output, so a story carrying frame
84    /// shapes runs byte-identically to one without. First emission rides the
85    /// continuation-splitting codegen when the fence drops (FS-3r). The
86    /// section is **omitted entirely** from `.inkb` when empty (self-framed in
87    /// the offset table, like `Visibility`), so existing stories stay
88    /// byte-identical.
89    pub frame_shapes: Vec<FrameShapeDef>,
90    /// CRC-32 checksum from the `.inkb` header, used for locale validation.
91    /// Zero for stories not loaded from `.inkb`.
92    pub source_checksum: u32,
93}
brink_format/story.rs

brink_format/
story.rs
