PtcRunner.Kernel.RunCatalog (PtcRunner v0.15.0)

Copy Markdown View Source

Immutable safe-metadata rows for one private run-cohort generation.

A generation is a captured value, not a view of a directory. It turns the bounded probes of PtcRunner.Kernel.RunCatalogProbe into one frozen row per canonical run stem, commits to their identities with a domain-separated digest, and never re-lists anything afterwards. Filesystem change therefore cannot alter an open generation: a later capture is a different generation with a different digest.

What a row may say

A row carries only what a sealed artifact states about itself at O(1) cost: identities, artifact presence and source class, schema and format versions, byte and record counts, lifecycle timestamps and terminal status, the safe result_hash fingerprint, the same run-started labels the public analysis/runs surface already exposes, the sealed artifact digest, and the correlation and admissibility of the pair.

A row never carries prompts, responses, generated source, capability payloads, diagnostics, prints, result values, evidence-record content, or a filesystem path — and never a counter that would require scanning a whole trace (evaluations, llm_calls, error_count, truncated). Those stay where they already are, behind admission, on analysis/runs {"view" "full"} and analysis/counters.

"Non-copying" here means no payload copying: beyond a head line, a bounded tail line, and a sealed container's fixed edges, nothing is read, decoded, or retained. The bounded per-row metadata projection is the product.

Isolation

Classification is per row, and a row is the unit of failure. A malformed, ambiguous, duplicate, unstable, or version-incompatible entry becomes an isolated row carrying a path-free reason code — it never blocks the generation, because nothing beyond its own probe was ever opened. Whole- operation refusals belong to the probe and the owner, not here.

Summary

Functions

Freezes one generation from the probes of a single capture.

Types

generation()

@type generation() :: %{
  rows: [row()],
  catalog_digest: binary(),
  excluded_files: non_neg_integer()
}

row()

@type row() :: %{required(binary()) => term()}

Functions

catalog_version()

@spec catalog_version() :: binary()

generation(probes, excluded_files)

@spec generation([PtcRunner.Kernel.RunCatalogProbe.probe()], non_neg_integer()) ::
  {:ok, generation()} | {:error, :invalid_catalog}

Freezes one generation from the probes of a single capture.

Rows are ordered by run reference so a generation, its digest, and any cursor derived from it stay stable for the lifetime of the capture.

max_row_bytes()

@spec max_row_bytes() :: pos_integer()

reason_order()

@spec reason_order() :: [atom()]