1 rollouts.storage.writer

rollouts.storage.writer

Standalone Zarr replay store for finite-candidate rollout traces.

This module owns normalized store materialization and finalization. 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
RolloutZarrStoreConfig	Filesystem, replay, and oracle-retention settings for one rollout store.
RolloutZarrWriteResult	Summary of one rollout Zarr write.

1.1.1 RolloutZarrStoreConfig

rollouts.storage.writer.RolloutZarrStoreConfig()

Filesystem, replay, and oracle-retention settings for one rollout store.

The destination is independent of the immutable VIN offline cache. Direct writes own and replace store_dir; validated completed stores should be treated as immutable inputs. Cluster jobs obtain crash-safe lifecycle semantics through temporary shard writes and atomic final promotion.

1.1.1.1 Attributes

Name	Description
paths	Repository path defaults used to resolve cache artifact destinations.
store_dir	Standalone destination replaced by a direct write; never the VIN source store.
return_semantics	Versioned return family recorded for the derived finite-candidate view.
discount_gamma	Discount applied only to non-terminal selected TD transitions.
target_protocol_version	Contract version separating target task inputs from oracle labels.
reason_code_version	Version of persisted candidate-invalidity bit positions.
field_retention_policy	Named policy describing which heavy oracle/audit payloads are retained.
source_offline_store_version	Immutable VIN source-cache version copied into rollout provenance.
split_manifest_hash	Hash binding the source split and ordered row ownership records.
q_h_chunk_states	Number of state rows per chunk in the persisted derived q_h/ view.
target_eval_crop_max_points	Fixed row width for oracle/eval target crop point payloads.
target_eval_crops_enabled	Persist oracle/eval target crop point payloads for sampled audit shards.
oracle_query_mode	Persisted hard-oracle candidate-query profile for Q_H supervision.
label_support_semantics	Persisted relation between actor-valid rows and finite Q labels.

1.1.2 RolloutZarrWriteResult

rollouts.storage.writer.RolloutZarrWriteResult(
    store_dir,
    num_rollouts,
    num_steps,
    num_candidates,
    manifest_path,
    manifest_sha256,
)

Summary of one rollout Zarr write.

Counts refer to materialized row tables, not source VIN samples. One source sample can contribute multiple targets, rollout recipes, beam chains, steps, and full-shell candidate rows.

1.1.2.1 Attributes

Name	Description
store_dir	Resolved standalone rollout-store directory written by the session.
num_rollouts	Number of retained trajectory-chain rows in rollouts/.
num_steps	Number of materialized state/transition rows in steps/.
num_candidates	Number of full-shell action rows in candidates/.
manifest_path	Human-readable provenance sidecar beside the Zarr payload.
manifest_sha256	SHA-256 binding canonical manifest JSON to the store root attrs.

1.2 Functions

Name	Description
write_rollout_zarr_store	Replace a standalone destination with normalized rollout replay tables.

1.2.1 write_rollout_zarr_store

rollouts.storage.writer.write_rollout_zarr_store(
    store_dir,
    records,
    *,
    return_semantics=DEFAULT_RETURN_SEMANTICS,
    discount_gamma=1.0,
    target_protocol_version=TargetInputProtocol.V0_GT_INPUT,
    reason_code_version=INVALID_REASON_VERSION,
    field_retention_policy='compact',
    source_offline_store_version='unknown-source-version',
    split_manifest_hash='unknown-split-manifest',
    manifest_context=None,
    selected_depth_enabled=True,
    selected_depth_width_px=240,
    selected_depth_height_px=240,
    selected_depth_chunk_steps=16,
    selected_depth_renderer='Pytorch3DDepthRenderer',
    selected_depth_znear_m=0.001,
    selected_depth_zfar_m=20.0,
    selected_depth_source_resolution='exact_output_size',
    q_h_chunk_states=64,
    target_eval_crop_max_points=DEFAULT_TARGET_EVAL_CROP_MAX_POINTS,
    target_eval_crops_enabled=False,
    oracle_query_mode='legacy_unspecified',
    label_support_semantics='subset_of_action_v1',
)

Replace a standalone destination with normalized rollout replay tables.

Candidate shells remain complete in the factual tables; valid-only oracle vectors are expanded through masks, and q_h/ is derived from the normalized step/candidate rows. Selected mesh depth and optional target evaluation crops remain rollout-owned oracle/audit artifacts.

1.2.1.1 Parameters

Name	Type	Description	Default
store_dir	Path | str	Destination directory opened in Zarr write mode. A direct call replaces existing content at this path.	required
records	Sequence[_RolloutWriteRecord]	Root-target-recipe rollout results with source/target lineage.	required
return_semantics	str	Versioned return family recorded on the derived view.	DEFAULT_RETURN_SEMANTICS
discount_gamma	float	Discount for non-terminal selected TD transitions.	1.0
target_protocol_version	TargetInputProtocol | str	Target input/label boundary contract.	TargetInputProtocol.V0_GT_INPUT
reason_code_version	str	Candidate-invalidity code-table version.	INVALID_REASON_VERSION
field_retention_policy	str	Named heavy-field retention policy.	'compact'
source_offline_store_version	str	Immutable VIN source-cache version.	'unknown-source-version'
split_manifest_hash	str	Hash of split and ordered source-row ownership.	'unknown-split-manifest'
manifest_context	RolloutStoreManifestContext | None	Optional resolved config, invocation, runtime, and shard provenance for the sidecar.	None
selected_depth_enabled	bool	Whether selected-only oracle depth is retained.	True
selected_depth_width_px	int	Selected-depth raster width in pixels.	240
selected_depth_height_px	int	Selected-depth raster height in pixels.	240
selected_depth_chunk_steps	int	Selected-depth rows per Zarr chunk.	16
selected_depth_renderer	str	Renderer identity stored as provenance.	'Pytorch3DDepthRenderer'
selected_depth_znear_m	float | None	Near clipping distance in metres.	0.001
selected_depth_zfar_m	float | None	Far clipping distance in metres.	20.0
selected_depth_source_resolution	str	Resolution-policy provenance label.	'exact_output_size'
q_h_chunk_states	int	State rows per derived-view chunk.	64
target_eval_crop_max_points	int	Fixed point width P_max for audit crops.	DEFAULT_TARGET_EVAL_CROP_MAX_POINTS
target_eval_crops_enabled	bool	Whether optional oracle target crops persist.	False
oracle_query_mode	str	Closed oracle-query support identity for Q_H labels.	'legacy_unspecified'
label_support_semantics	str	Closed relationship between labels and actor-valid rows.	'subset_of_action_v1'

1.2.1.2 Returns

Name	Type	Description
	RolloutZarrWriteResult	Row counts, resolved destination, and sidecar manifest digest.

1.2.1.3 Notes

This low-level direct writer is not a temp-to-final transaction. Use the rollout shard runner for validated atomic promotion. In either path the VIN source cache is opened only as an input and is never modified.