Struct Program 

pub struct Program { /* private fields */ }

A linked, ready-to-execute program.

Created from StoryData via link(). Immutable after creation — mutable per-instance state lives in Story.

Implementations

impl Program

pub fn resolve_address(&self, id: DefinitionId) -> Option<(u32, usize)>

Resolve a definition ID to (container_idx, byte_offset).

pub fn container_bytecode(&self, idx: u32) -> &[u8]

Get a container’s bytecode by index.

pub fn container_count(&self) -> u32

Number of containers.

pub fn source_checksum(&self) -> u32

CRC-32 checksum from the source .inkb, used for transcript validation.

pub fn name_checked(&self, id: NameId) -> Option<&str>

Look up a name by id, returning None if the id is out of range. Used by function-value rehydration (T1c, #700): a closure loaded from a save produced against a different compile can carry a NameId that no longer indexes this program’s table — treated as a mismatch (fault), never a panic.

Public (T1d, docs/t1d-spec.md §6): the same “index by id, None if out of range” contract a host needs to resolve a brink_format::Value::Handle’s kind to its manifest-declared name — e.g. for dev-tooling display or a host-side capability check. bevy-brink re-exports Program (decision 2026-07-10), so this is reachable from engine code without a direct brink-runtime dependency.

pub fn name_id(&self, name: &str) -> Option<NameId>

Reverse of name_checked: look up the NameId a string interns to in this program’s name table, if any.

Public (T1d-3, docs/t1d-spec.md §4): a host minting a brink_format::Value::Handle from a binding (e.g. spawn_timer() returning a fresh Handle<Timer>) needs the compiled program’s NameId for the manifest-declared kind name ("Timer") to build the token — the wire form carries only the interned id, never the string. None means this compile never interned that name (e.g. no Handle<Timer>-typed signature or annotation anywhere in the source graph), so no token of that kind can be minted against this program. Linear scan, same cost class as global_index.

pub fn find_address(&self, path: &str) -> Option<(u32, usize)>

Resolve a qualified ink path to its (container_idx, byte_offset).

Supports knot names (intro), qualified stitches (knot.stitch), and, for programs compiled by brink-compiler, author labels (knot.label, knot.stitch.label). Programs without the compiler’s address_paths table (legacy .inkb or converter output) resolve knot/stitch scope paths only. Use this to spawn flows at named entry points:

use brink_runtime::FlowInstance;

if let Some((idx, _)) = program.find_address("intro_scene") {
    let (flow, ctx) = FlowInstance::new_at(program, idx);
}

pub fn definition_id_for_path(&self, path: &str) -> Option<DefinitionId>

Public wrapper on find_path_target: resolve a qualified ink path (same grammar as find_address) to the DefinitionId of its target. Used by hosts that need the id itself — e.g. bevy-brink’s wake-condition purity check (issue #995), which looks the id up in the story’s EffectRows table to inspect a FlowSleep condition’s effect row before admitting it into the wake contract.

pub fn global_defaults(&self) -> Vec<Value>

Build the initial globals vector from slot defaults.

pub fn global_index(&self, name: &str) -> Option<u32>

Find the global variable slot index for a variable name, if declared. Used by host-facing variable get/set (Story::variable/set_variable).

pub fn global_slot(&self, id: DefinitionId) -> Option<u32>

Resolve a global cell’s DefinitionId to its slot index — the numbering ContextAccess::set_global and Self::global_index use.

Public because effect rows (brink_format::DirectEffects::reads / writes) name global cells by DefinitionId while the runtime’s world writes are keyed by slot: a host consuming rows for scheduling (bevy-brink’s row-directed wake dirtying, issue #1146) needs exactly this bridge. None for an id this program declares no global for (a stale row, a VAR removed by a story patch).

pub fn global_name(&self, idx: u32) -> Option<&str>

Resolve a global slot index to its variable name.

pub fn has_local_defaults(&self) -> bool

Whether the compiler marked anything flow-private. When false (all existing unannotated ink), policy resolution keeps its all-World fast path.

Public so the bevy host (bevy-brink’s batch driver) can guard against batching a #@local-annotated story: batch mode routes only the shared World, never a flow’s private FlowLocal, so a story carrying compiled flow-private defaults must stay on the serial API (docs/effects-spec.md §12; bevy-brink #925).

pub fn global_count(&self) -> u32

Number of global variable slots.

pub fn global_var_name(&self, id: DefinitionId) -> Option<&str>

Variable name for a global’s defining DefinitionId (e.g. a VariablePointer target, or a T1e projection’s root cell). pub (not pub(crate)) since brink-web’s program-model/speculation disassembly needs it to render a projection’s root name at the wasm boundary, the same way divert_target_path already resolves a divert’s DefinitionId for that consumer.

pub fn list_members(&self, list: &ListValue) -> Vec<ListMember>

Resolve the active members of a list value for host-facing display: each member’s origin list name, unqualified item name, and ordinal. Sorted the same way in-story list stringification orders them (ordinal, then origin name) so the two presentations agree.

pub fn divert_target_path(&self, id: DefinitionId) -> Option<String>

The qualified knot/stitch path a DefinitionId names, if it resolves to a named scope entry (offset-0 in address_by_path) — the destination of a Value::DivertTarget for host-facing display. Deterministic on collision: shortest path, then lexicographically smallest, independent of the map’s iteration order (mirrors debug::NameResolver’s reverse lookup).