# `PtcRunner.Kernel.FrozenBundle`
[🔗](https://github.com/andreasronge/ptc_runner/blob/main/lib/ptc_runner/kernel/frozen_bundle.ex#L1)

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:

```text
"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) || payload
```

The 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.

# `t`

```elixir
@type t() :: %PtcRunner.Kernel.FrozenBundle{
  attestation: binary() | nil,
  component_ids: [binary()],
  components: [map()],
  hash: binary(),
  prelude: PtcRunner.Lisp.Prelude.t()
}
```

# `identity`

```elixir
@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.

# `seal`

```elixir
@spec seal(t()) :: t()
```

Attests a newly compiled bundle for later environment validation.

# `trace_metadata`

```elixir
@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.

# `valid?`

```elixir
@spec valid?(t()) :: boolean()
```

Checks that a bundle still matches its in-VM attestation.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
