1 rollouts.storage.trace
rollouts.storage.trace
Minimal rollout replay inputs shared by the Zarr writer.
rollouts.zarr stores facts derived from existing counterfactual rollout results. This module owns frozen invalidity codecs and composed lineage facts; generation-pipeline aggregates remain outside replay and storage. It does not define a second serializable trace hierarchy.
1.1 Attributes
| Name | Description |
|---|---|
| INVALID_REASON_CODES | Version-1 invalidity reason bit positions for rollout replay tables. |
| INVALID_REASON_VERSION | Version label for INVALID_REASON_CODES. |
1.2 Classes
| Name | Description |
|---|---|
| PolicyLineage | Candidate, Oracle, and replay-policy configuration lineage. |
| RolloutLineage | Composed source, target, and policy lineage flattened only by the writer. |
| SourceLineage | Immutable VIN source identity for one generated rollout root. |
| TargetLineage | Actor descriptor and privileged Oracle target lineage. |
1.2.1 PolicyLineage
rollouts.storage.trace.PolicyLineage(
candidate_config_hash=None,
oracle_config_hash=None,
model_checkpoint_hash=None,
random_seed=None,
rollout_policy='unknown',
rollout_config_hash=None,
branch_schedule_id=None,
reason_code_version=INVALID_REASON_VERSION,
selection_rng_state_hash=None,
)Candidate, Oracle, and replay-policy configuration lineage.
1.2.1.1 Attributes
| Name | Description |
|---|---|
| candidate_config_hash | Stable hash of candidate-shell generation and hard-validity controls. |
| oracle_config_hash | Stable hash of Oracle rendering, crop, fusion, and RRI controls. |
| model_checkpoint_hash | Optional learned-policy checkpoint hash; absent for built-in policies. |
| random_seed | Recipe/root seed from which deterministic node seeds were derived. |
| rollout_policy | Action-selection policy used for this retained rollout chain. |
| rollout_config_hash | Stable hash of horizon, branching, policy, and diversity controls. |
| branch_schedule_id | Human-stable recipe or schedule identifier for branch provenance. |
| reason_code_version | Version of rollout candidate invalidity bit positions. |
| selection_rng_state_hash | Hash of target-selection RNG state for deterministic replay audits. |
1.2.2 RolloutLineage
rollouts.storage.trace.RolloutLineage(
source=SourceLineage(),
target=TargetLineage(),
policy=PolicyLineage(),
rollout_id='',
chain_id=0,
)Composed source, target, and policy lineage flattened only by the writer.
1.2.2.1 Attributes
| Name | Description |
|---|---|
| source | Immutable VIN source identity for the rollout root. |
| target | Actor descriptor and privileged Oracle target lineage. |
| policy | Candidate, Oracle, and replay-policy configuration lineage. |
| rollout_id | Stable identifier assigned to one retained rollout chain. |
| chain_id | Zero-based retained trajectory index within the rollout root. |
1.2.2.2 Methods
| Name | Description |
|---|---|
| for_chain | Return persisted lineage identifiers for one retained chain. |
1.2.2.2.1 for_chain
rollouts.storage.trace.RolloutLineage.for_chain(
chain_id,
*,
rollout_id,
rollout_policy,
)Return persisted lineage identifiers for one retained chain.
1.2.3 SourceLineage
rollouts.storage.trace.SourceLineage(
scene_id=None,
snippet_id=None,
mesh_version=None,
source_cache_version=None,
split=None,
campaign_split=None,
source_offline_store_manifest_hash=None,
source_row_id=None,
source_sample_index=None,
source_sample_key=None,
split_manifest_hash=None,
source_shard_id=None,
source_shard_row=None,
)Immutable VIN source identity for one generated rollout root.
1.2.3.1 Attributes
| Name | Description |
|---|---|
| scene_id | Source scene identifier copied from the immutable VIN index. |
| snippet_id | Source snippet identifier copied from the immutable VIN index. |
| mesh_version | Fingerprint/version of the oracle mesh used for rendering and labels. |
| source_cache_version | Schema/version label of the immutable VIN offline source cache. |
| split | VIN source split associated with this rollout root. |
| campaign_split | Authoritative campaign split; never overwrites VIN split. |
| source_offline_store_manifest_hash | Hash of the complete VIN source-store manifest. |
| source_row_id | Dense source-table row id assigned by the rollout store writer. |
| source_sample_index | Stable VIN dataset sample index used to reopen the source row. |
| source_sample_key | Canonical VIN sample key used to detect source-index drift. |
| split_manifest_hash | Hash binding the split name and ordered source-row ownership records. |
| source_shard_id | Identifier of the immutable VIN storage shard containing the source. |
| source_shard_row | Zero-based row within source_shard_id. |
1.2.4 TargetLineage
rollouts.storage.trace.TargetLineage(
target_row_id=None,
target_id=None,
target_protocol_version=None,
target_crop_policy=None,
target_selection_policy=None,
target_selection_rank=None,
target_selection_score=None,
target_selection_probability=None,
target_selection_temperature=None,
target_source=None,
target_source_index=None,
descriptor_source=None,
descriptor_provenance=None,
descriptor_hash=None,
explicit_target_hash=None,
target_sem_id=None,
target_inst_id=None,
target_class_name=None,
target_confidence=None,
target_projected_area_pixels=None,
target_projected_area_fraction=None,
target_semidense_support_count=None,
target_evl_support_count=None,
target_effective_support_count=None,
target_visibility_score=None,
target_support_score=None,
target_deficit_score=None,
target_center_world=None,
target_extents=None,
target_pose_world_object=None,
target_relative_pose_reference_object=None,
target_invalid_reason_bitset=None,
target_primary_invalid_reason=None,
target_reason_code_version=None,
matched_gt_target_row_id=None,
matched_gt_target_id=None,
gt_match_iou=None,
gt_match_score=None,
gt_match_status=None,
)Actor descriptor and privileged Oracle target lineage.
1.2.4.1 Attributes
| Name | Description |
|---|---|
| target_row_id | Dense target-table row id assigned by the rollout store writer. |
| target_id | Stable target-task identifier from selection or oracle task sampling. |
| target_protocol_version | Versioned contract governing target evidence and label boundaries. |
| target_crop_policy | Versioned oracle geometry-crop policy used for target RRI labels. |
| target_selection_policy | Policy that admitted this target task before rollout generation. |
| target_selection_rank | Zero-based target rank within the source sample’s selected set. |
| target_selection_score | Target-interest score under the recorded selection protocol. |
| target_selection_probability | Sampling probability assigned to the selected target task. |
| target_selection_temperature | Temperature used by stochastic target selection, when applicable. |
| target_source | Target source protocol, distinguishing observed and oracle task inputs. |
| target_source_index | Row index in the source OBB/task table before target filtering. |
| descriptor_source | Source block that constructed the actor-facing descriptor. |
| descriptor_provenance | Typed construction provenance for the actor-facing descriptor. |
| descriptor_hash | Canonical hash of the actor-facing descriptor identity. |
| explicit_target_hash | Canonical hash binding an explicit observed target to its GT proof. |
| target_sem_id | Semantic class id carried by the chosen target task. |
| target_inst_id | Instance id carried by the chosen target task. |
| target_class_name | Human-readable semantic class label for audit and inspection. |
| target_confidence | Source OBB confidence; actor-visible only for observed-target protocols. |
| target_projected_area_pixels | Largest clipped target projection area, in square pixels. |
| target_projected_area_fraction | Projected area divided by the target selector’s image normalizer. |
| target_semidense_support_count | Semidense world points inside the selected target volume. |
| target_evl_support_count | Positive EVL evidence points inside the selected target volume. |
| target_effective_support_count | Weighted support count used by the target-selection protocol. |
| target_visibility_score | Projected-visibility factor used when selecting observed targets. |
| target_support_score | Support-sufficiency factor used by target ranking. |
| target_deficit_score | Unsaturated-support factor favoring targets with improvement headroom. |
| target_center_world | Target OBB center (x, y, z) in world metres. |
| target_extents | Full target OBB side lengths in object axes, in metres. |
| target_pose_world_object | Flattened 12-value physical transform from target object to world. |
| target_relative_pose_reference_object | Flattened 12-value transform from target object to snippet reference. |
| target_invalid_reason_bitset | Versioned bitset of target-level invalidity facts; never encoded as score. |
| target_primary_invalid_reason | Prioritized target invalidity code for compact inspection. |
| target_reason_code_version | Version of target-selection invalidity bit positions. |
| matched_gt_target_row_id | Oracle-only GT target row matched after target selection. |
| matched_gt_target_id | Oracle-only stable identifier of the matched GT target. |
| gt_match_iou | Oracle-only oriented-box IoU used for target-label auditing. |
| gt_match_score | Oracle-only composite score used to choose the GT match. |
| gt_match_status | Oracle-only match outcome controlling target-label admissibility. |
1.3 Functions
| Name | Description |
|---|---|
| candidate_invalid_reasons | Return full-shell invalid-reason bitsets and one primary reason per candidate. |
| policy_name | Return the stable persisted policy label for enum or string inputs. |
| termination_reason | Classify why a replay chain stopped without inventing a partial label. |
1.3.1 candidate_invalid_reasons
rollouts.storage.trace.candidate_invalid_reasons(candidates)Return full-shell invalid-reason bitsets and one primary reason per candidate.
The result preserves the persisted invalidity codec: valid candidates carry the VALID bit, cumulative rule-mask transitions identify the first rejected shell rows, hard diagnostics add their reason bits, and unresolved invalid rows fall back to SAMPLER_RULE_REJECTED.
1.3.2 policy_name
rollouts.storage.trace.policy_name(policy)Return the stable persisted policy label for enum or string inputs.
1.3.3 termination_reason
rollouts.storage.trace.termination_reason(result, trajectory)Classify why a replay chain stopped without inventing a partial label.
Early termination takes precedence over horizon completion. A trajectory shorter than result.horizon without the explicit early-stop marker is reported as incomplete_rollout so persisted stores can distinguish a valid terminal transition from missing generation output.