Owner process holding one immutable private run-catalog generation.
Capture runs once, inside a heap- and deadline-bounded worker, and freezes
its rows into owner state. Nothing re-lists or re-probes afterwards, so a
filesystem that grows, shrinks, or changes under an open generation cannot
alter what this owner answers; a caller that wants current state captures a
new generation, which carries a different catalog_digest.
The owner is bound to the process that started it and exits when that owner does. It holds no file descriptors: every probe closes its file before the capture returns, so a generation costs bounded memory and no handles.
This owner is the discovery half of the two-stage cohort contract. It never opens a private payload and never admits a source — selection admission re-verifies the files it names, on its own authority.
Summary
Functions
Returns a specification to start this module under a supervisor.
Returns the generation's identity and accounting, without any row.
Returns one bounded page from this generation's safe metadata rows.
Returns the generation's frozen rows, in run-reference order.
Captures one generation over a trace root and an inspection root.
Types
Functions
Returns a specification to start this module under a supervisor.
See Supervisor.
@spec default_retained_bytes() :: pos_integer()
Returns the generation's identity and accounting, without any row.
Returns one bounded page from this generation's safe metadata rows.
@spec rows(t()) :: {:ok, [PtcRunner.Kernel.RunCatalog.row()]} | {:error, atom()}
Returns the generation's frozen rows, in run-reference order.
The list is bounded by the capture's retained-byte and stem-count limits. Paging, filtering, and digest-bound cursors are the query surface's concern and read the same frozen list.
@spec start( {:private_authorized_catalog, binary(), binary()}, keyword() ) :: {:ok, t()} | {:error, atom()}
Captures one generation over a trace root and an inspection root.
Options lower, never raise, the capture bounds: :max_directory_entries,
:max_files, :max_retained_bytes, :capture_heap_words, and
:capture_deadline_ms. :owner names the process the generation belongs
to, and :listing_hook and :file_probe_hook exist for tests that need
deterministic synchronization around filesystem operations.
Whole-operation refusals are path-free: :source_unavailable for a root
that cannot be listed, and :catalog_limit_exceeded for a listing, stem
count, or retained projection beyond its bound.
@spec stop(term()) :: :ok