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
@type generation() :: %{ rows: [row()], catalog_digest: binary(), excluded_files: non_neg_integer() }
Functions
@spec catalog_version() :: binary()
@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.
@spec max_row_bytes() :: pos_integer()
@spec reason_order() :: [atom()]