PtcRunner.Kernel.ComponentCatalog (PtcRunner v0.15.0)

Copy Markdown View Source

Immutable attested source-bearing projection of one compiled environment.

In frozen dependency order each entry binds a component ID to its direct dependencies, declared namespaces, qualified sha256:<64-hex> source hash, and exact effective source bytes. The catalog is built from the same %PtcRunner.Kernel.Component{} values passed to the bundle compiler and is validated against the resulting %PtcRunner.Kernel.FrozenBundle{} before attestation, so source cannot be paired with a different compiled graph.

This projection is setup memory for the selected workflow or mission environment. It is not prelude metadata, is not copied into result stamps, canonical traces, telemetry, or host logs, and is absent from direct PtcRunner.Lisp.run/2 unless a Kernel evaluation threads the selected environment's catalog into the evaluation context.

Summary

Types

entry()
t()

Functions

bind(catalog, bundle)

Accepts a catalog for environment assembly against bundle.

build(components, bundle, intern \\ SourceIntern.new())

Builds an attested catalog from compiled components and their bundle.

empty()

Returns the attested empty catalog.

empty?(component_catalog)

Returns true when catalog has no entries.

fetch(component_catalog, id)

Looks up one catalog entry by exact component ID.

ids(component_catalog)

Component IDs in frozen dependency order.

Types

entry()

@type entry() :: %{
  id: binary(),
  dependencies: [binary()],
  namespaces: [binary()],
  source_hash: binary(),
  source: binary()
}

t()

@type t() :: %PtcRunner.Kernel.ComponentCatalog{
  attestation: binary() | nil,
  entries: [entry()]
}

Functions

bind(catalog, bundle)

@spec bind(t() | nil, PtcRunner.Kernel.FrozenBundle.t() | nil) ::
  {:ok, t()} | {:error, atom()}

Accepts a catalog for environment assembly against bundle.

An omitted or empty catalog is allowed even when a bundle is present, so inspection remains opt-in at construction. A non-empty catalog must be attested and match the bundle's frozen graph and source hashes.

build(components, bundle, intern \\ SourceIntern.new())

@spec build(
  [PtcRunner.Kernel.Component.t()],
  PtcRunner.Kernel.FrozenBundle.t() | nil,
  PtcRunner.Kernel.SourceIntern.t()
) :: {:ok, PtcRunner.Kernel.SourceIntern.t(), t()} | {:error, atom()}

Builds an attested catalog from compiled components and their bundle.

Source binaries are interned through intern so identical bytes stay one BEAM binary across catalogs. A nil bundle is valid only for an empty component list.

empty()

@spec empty() :: t()

Returns the attested empty catalog.

empty?(component_catalog)

@spec empty?(t()) :: boolean()

Returns true when catalog has no entries.

fetch(component_catalog, id)

@spec fetch(t(), binary()) :: {:ok, entry()} | :error

Looks up one catalog entry by exact component ID.

ids(component_catalog)

@spec ids(t()) :: [binary()]

Component IDs in frozen dependency order.