1 rollouts.storage.reader

rollouts.storage.reader

Standalone Zarr replay store for finite-candidate rollout traces.

This module owns strict read-only access to the persisted contract. A store contains compact row tables for rollout chains, steps, full-shell candidates, shared VIN source rows, lineage, target records, masks, and reason codes. The padded Q_H tensors used by finite-candidate value learning are persisted in a derived q_h/ group for high-throughput training and are validated against the canonical factual steps/ and candidates/ tables. The store deliberately does not mutate or migrate the strict VIN offline store; rollout replay is a separate artifact with source manifest, split, target, candidate-mixture, policy, and oracle config hashes.

q_train_mask is true only when a candidate row is actor-selectable, target-valid, GT-label-valid, and has a finite target-root-gain reward. Invalid candidates keep their full-shell row but carry false masks and NaN labels. Q_H padding exists only in the derived dense q_h/ view. Target RRI and scene RRI are state-relative diagnostics; target labels must not be silently filled from scene scores or low-quality invalid rows.

1.1 Classes

Name Description
RolloutZarrStoreReader Open a completed standalone rollout replay store in read-only mode.

1.1.1 RolloutZarrStoreReader

rollouts.storage.reader.RolloutZarrStoreReader(store_dir)

Open a completed standalone rollout replay store in read-only mode.

The reader never repairs, migrates, or backfills arrays. Canonical factual tables remain the source of truth; q_h/ is a validated derived cache.

1.1.1.1 Methods

Name Description
candidate_shell_index Return the immutable shell-ordered candidate-row lookup for this reader.
array Read an array, returning -1 for supported unavailable provenance.
array_rows Read only selected first-axis rows from one canonical Zarr array.
validate Validate persisted contracts, optionally skipping unconsumed depth payloads.
manifest Read root attrs and the top-level sidecar manifest without payload arrays.
acquisition_row_context Resolve a chain or step to its authenticated, original generation context.
q_h_view Return the padded finite-candidate Q_H training view.
1.1.1.1.1 candidate_shell_index
rollouts.storage.reader.RolloutZarrStoreReader.candidate_shell_index()

Return the immutable shell-ordered candidate-row lookup for this reader.

The index is reader-local and derived only from canonical candidate columns. Reusing it prevents repeated whole-table scans in consumers that project several rollout steps from the same completed store.

1.1.1.1.2 array
rollouts.storage.reader.RolloutZarrStoreReader.array(path)

Read an array, returning -1 for supported unavailable provenance.

1.1.1.1.3 array_rows
rollouts.storage.reader.RolloutZarrStoreReader.array_rows(path, positions)

Read only selected first-axis rows from one canonical Zarr array.

1.1.1.1.4 validate
rollouts.storage.reader.RolloutZarrStoreReader.validate(
    validate_selected_depth_payload=True,
)

Validate persisted contracts, optionally skipping unconsumed depth payloads.

1.1.1.1.5 manifest
rollouts.storage.reader.RolloutZarrStoreReader.manifest()

Read root attrs and the top-level sidecar manifest without payload arrays.

1.1.1.1.6 acquisition_row_context
rollouts.storage.reader.RolloutZarrStoreReader.acquisition_row_context(
    table,
    row_id,
)

Resolve a chain or step to its authenticated, original generation context.

Physical packing renumbers rows but archives the source manifest and a hashed row mapping. Follow those bindings through repeated packing; return the acquisition manifest digest, original row ID and generation context. Missing, ambiguous or altered bindings fail rather than borrowing another chain’s configuration. Metadata is cached for this immutable reader.

1.1.1.1.7 q_h_view
rollouts.storage.reader.RolloutZarrStoreReader.q_h_view(discount_gamma=None)

Return the padded finite-candidate Q_H training view.

Let S be the number of materialized step/state rows and A the maximum step-local full-shell width. Candidate ids, masks, positions, one-step labels, and reason bitsets are ndarray["S A", ...]; source/target ids, selected-action indices, and TD linkage are ndarray["S", ...]. Shorter shells are padded with id -1, false masks, and NaN labels.

valid_action_mask is the hard actor-selectable mask. q_train_mask is stricter: it also requires a label-valid target/GT state and a finite explicit target-root-gain label. Finite target RRI remains an independent diagnostic-availability predicate. Invalidity is represented by masks and versioned reason bitsets, never by a low score. TD reward/linkage describes the factual selected action only; unselected action labels remain one-step oracle supervision.

1.1.1.1.7.1 Parameters
Name Type Description Default
discount_gamma float | None When None, read the persisted q_h/ cache. Otherwise rebuild the view from canonical factual tables using this discount for non-terminal selected transitions. None
1.1.1.1.7.2 Returns
Name Type Description
dict[str, np.ndarray] Mapping containing all Q_H_ARRAY_NAMES, preserving the
dict[str, np.ndarray] S state axis and padded A full-shell action axis.
Back to top