Executor & Content-Addressed Execution

hologram-exec runs a compiled .holo archive. Execution is synchronous — there is no async API and no streaming. The runtime is no_std + alloc by default so inference runs in wasm and on embedded targets; the std feature adds host-only amenities.

Execution Model

Execution rides on one content-addressed buffer pool (BufferArena). A value lives in exactly one 64-byte-aligned buffer; a slot binds to that buffer rather than copying it — so the runtime is zero-movement. Buffers fall into two classes:

pinned — model constants/weights, deduped by content κ-label, resident for the session
transient — boundary inputs, intermediates, and outputs, held in a byte-bounded two-generation pool

Every value carries a UOR-ADDR κ-label (71 bytes). A computed value’s label is derived by ordered composition of its operands’ labels — cost O(operands), independent of tensor size. Because the kernels are deterministic, an identical derivation always yields identical content, so:

A whole-graph re-execution whose input ports content-address to a key already in the graph memo returns the cached output addresses without walking the graph — O(1) in graph size.
A shared sub-graph (common prefix / CSE within one run) is recognized and its kernel dispatch is elided.

Warm-start (WarmStore) pins the constant-only cone’s materialized results so the runtime cache is never cold.

Types

InferenceSession<B> — the loaded model; B: SessionBackend
BufferArena — the content-addressed buffer pool (implements the backend’s Workspace)
InputBuffer<'a> — { bytes: &'a [u8] }, a borrowed input tensor
OutputBuffer — { bytes: Vec<u8> }, an owned output tensor
RefinementPlan — pass budget, validators, and repair policy
RefinementStateContract — explicit state port contract for planner-generated plans
RefinementRunner<'a, B> — a borrowed runner over an existing session
CompiledRefinement<B> — owning convenience wrapper for a session and plan
ValidatorKind — built-in pass-boundary validators such as StableLabels and StableBytes
RepairPolicy — bounded repair behavior
RefinementReport — final status, pass counts, labels, counters, and resident-memory data
WarmStore / MemWarmStore / FileWarmStore (the last requires std)
ExecError — the runtime’s error type

Loading & executing

use hologram_exec::{InferenceSession, BufferArena, InputBuffer};
use hologram_backend::CpuBackend;

let backend: CpuBackend<BufferArena> = CpuBackend::new();
let mut session = InferenceSession::load(&archive, backend)?;

let outputs = session.execute(&[InputBuffer { bytes: &input_bytes }])?;
let result: &[u8] = &outputs[0].bytes;

Refinement is a bounded execution strategy around execute_addressed, not a graph op or backend kernel. The session’s input and output state ports must match in arity, dtype, shape, element count, and byte length so each pass output can become the next pass input.

Planner-generated plans can attach a RefinementStateContract; otherwise the runtime derives the contract from the session ports.

use hologram_exec::{
    InputBuffer, RefinementPlan, RepairPolicy, ValidatorKind,
};

let plan = RefinementPlan::builder(2)
    .validator(ValidatorKind::StableBytes)
    .repair_policy(RepairPolicy::RetryPass { extra_passes: 1 })
    .build()?;

let report = plan.execute(
    &mut session,
    &[InputBuffer { bytes: &state_bytes }],
)?;

StableLabels is O(number of state ports). StableBytes compares resolved arena slices without copying tensors, but it scans logical state bytes.

Accessors

Method	Returns
`input_count()`	declared input ports
`output_count()`	declared output ports
`kernel_count()`	kernel calls in the loaded archive
`resident_bytes()`	bytes currently resident in the pool
`resident_count()`	resident buffers in the pool
`content_store_len()`	distinct content-addressed entries

Feature Gates

Feature	Effect
`std`	Host-only amenities, including `FileWarmStore`
`parallel`	Forwards to the backend’s intra-kernel parallelism (one dispatch uses every core)
`tiered-exec`	PM_7 memory-tier coherence types