An immutable, deterministically ordered component compilation result.
Bundles contain bounded component provenance (id, direct dependencies,
origin, source hash, and namespaces), ordered component IDs, an aggregate
graph hash, and one composed compiled PTC-Lisp prelude. Per-component
callable preludes are transient compiler inputs and are not retained. The
graph hash is bare lowercase SHA-256 over the canonical
ptc.frozen-bundle.v2 framing of every component ID, source hash, and sorted
unique direct dependency list.
It therefore changes when code or dependency edges change and does not
depend on Erlang external-term encoding.
All integer fields in the framing are unsigned big-endian:
"ptc.frozen-bundle.v2\0" ||
u32(component_count) ||
for each component sorted by UTF-8 component-ID bytes:
0x01 ||
u32(component_id_bytes) || component_id ||
u64(payload_bytes) || payloadThe sole record kind is 0x01. Its payload is RFC 8785 canonical JSON of
exactly {"dependencies":[...],"source_hash":"..."}. Dependencies are
sorted unique direct component IDs and source_hash is the existing bare
lowercase SHA-256 hex digest. Component IDs and dependencies are UTF-8
strings; neither field is nullable or omitted.
An in-VM attestation prevents callers from mutating a bundle struct and presenting it as compiler output during environment assembly.
Hosts obtain bundles through PtcRunner.Kernel.compile_bundle/1; seal/1
and valid?/1 support the Kernel's construction boundary.
Summary
Functions
Computes the graph hash of a component identity set.
Attests a newly compiled bundle for later environment validation.
Derives the compact canonical dependency projection for run-started.
Checks that a bundle still matches its in-VM attestation.
Types
@type t() :: %PtcRunner.Kernel.FrozenBundle{ attestation: binary() | nil, component_ids: [binary()], components: [map()], hash: binary(), prelude: PtcRunner.Lisp.Prelude.t() }
Functions
@spec identity([%{id: binary(), dependencies: [binary()], source_hash: binary()}]) :: {:ok, binary()} | {:error, :invalid_bundle}
Computes the graph hash of a component identity set.
The sole owner of the ptc.frozen-bundle.v2 framing documented above. The
compiler derives a bundle's hash through it, and validators recompute the
same identity from a canonical projection plus independently supplied source
hashes, so a proven identity cannot drift from the one the compiler sealed.
Each entry needs only id, direct dependencies, and source_hash;
ordering and dependency deduplication are imposed here rather than trusted
from the caller.
Attests a newly compiled bundle for later environment validation.
@spec trace_metadata(t() | nil) :: {:ok, %{ component_ids: [binary()], dependency_indices: [[non_neg_integer()]], hash: binary() | nil }} | {:error, :invalid_bundle}
Derives the compact canonical dependency projection for run-started.
dependency_indices is positionally aligned with component_ids: the
list at position i holds the unique, ascending indices of that
component's direct dependencies, and every index is strictly less than
i (the frozen order places dependencies before dependants, so forward
references and cycles are unrepresentable). A missing bundle projects to
empty lists and a nil hash. Component source, origins, namespaces, and
other compilation data never enter the projection.
Checks that a bundle still matches its in-VM attestation.