1 rollouts.inspection.inventory

rollouts.inspection.inventory

Store discovery, manifest trust, schema state, and compact inventory evidence.

1.1 Classes

Name	Description
CompactStatistics	Compact statistics demanded by CLI stats and report consumers.
EffectiveTrust	Streamlit trust composition, preserving schema then promotion errors.
ManifestFacts	The single manifest snapshot shared by one inspection demand.
PairwiseCorrelationResult	Pair-local finite Pearson evidence for one set of named components.
PromotionEvidence	Optional promotion error for a validated rollout store.
RolloutStoreMetadata	Observation of one exact store path, without checking array content.
SchemaValidation	Immutable schema-validation result with ordered errors.

1.1.1 CompactStatistics

rollouts.inspection.inventory.CompactStatistics(payload)

Compact statistics demanded by CLI stats and report consumers.

1.1.2 EffectiveTrust

rollouts.inspection.inventory.EffectiveTrust(
    ok,
    num_rollouts,
    num_steps,
    num_candidates,
    errors,
)

Streamlit trust composition, preserving schema then promotion errors.

1.1.3 ManifestFacts

rollouts.inspection.inventory.ManifestFacts(payload)

The single manifest snapshot shared by one inspection demand.

1.1.4 PairwiseCorrelationResult

rollouts.inspection.inventory.PairwiseCorrelationResult(
    columns,
    correlation,
    counts,
    reasons,
    has_finite_off_diagonal,
)

Pair-local finite Pearson evidence for one set of named components.

1.1.5 PromotionEvidence

rollouts.inspection.inventory.PromotionEvidence(error)

Optional promotion error for a validated rollout store.

1.1.6 RolloutStoreMetadata

rollouts.inspection.inventory.RolloutStoreMetadata(
    path,
    name,
    availability,
    verification_status,
    reason,
    schema_version,
    schema_status,
    manifest_status,
    campaign_id,
    campaign_split,
    generation_revision,
    rollout_recipes,
    candidate_families,
    horizon_min,
    horizon_max,
    scene_ids,
    source_splits,
    source_manifest_hash,
    source_store_dir,
    oracle_query_mode,
    label_support_semantics,
    q_h_state_count,
    rollout_count,
    step_count,
    candidate_count,
    recorded_content_sha256,
    recorded_manifest_sha256,
)

Observation of one exact store path, without checking array content.

1.1.6.1 Attributes

Name	Type	Description
path	Path	Examined path; the caller must supply an exact store directory.
name	str	Final path component for display.
availability	Literal['available', 'unavailable', 'invalid']	Whether the directory and required metadata are readable. invalid means the path exists but its metadata is inconsistent.
verification_status	Literal['unverified_metadata', 'unavailable', 'invalid']	unverified_metadata never certifies Zarr payloads or the recorded content hash; deep validation is a separate operation.
reason	str | None	Human-readable explanation when metadata is unavailable or invalid.
schema_version	str | None	Version declared by the Zarr root when readable.
schema_status	Literal['current', 'stale', 'unavailable']	Whether the declared schema matches the current writer.
manifest_status	Literal['present', 'unavailable', 'invalid']	Whether the top-level manifest is readable and bound.
campaign_id	str | None	Persisted campaign binding, if any; never inferred.
campaign_split	str | None	Persisted split, if present.
generation_revision	str | None	Persisted generator revision, if present.
rollout_recipes	tuple[str, …]	Recipe names declared by the writer configuration.
candidate_families	tuple[str, …]	Candidate family names declared by the writer.
oracle_query_mode	str | None	Recorded query mode, if present.
label_support_semantics	str | None	Recorded label support, if present.
q_h_state_count	int | None	Recorded Q_H state count, if present.
rollout_count	int | None	Manifest-declared count, if present.
step_count	int | None	Manifest-declared count, if present.
candidate_count	int | None	Manifest-declared count, if present.
recorded_content_sha256	str | None	Seal stated by both promotion markers, if any.
recorded_manifest_sha256	str | None	Hash recorded by the Zarr root, if present.

1.1.6.2 Methods

Name	Description
to_inventory_row	Project metadata into established inventory columns for selectors.

1.1.6.2.1 to_inventory_row

rollouts.inspection.inventory.RolloutStoreMetadata.to_inventory_row()

Project metadata into established inventory columns for selectors.

observed_* columns contain manifest-declared values here. The explicit verification status prevents treating them as array counts.

Additional attribute identifiers: horizon_max, horizon_min, horizon_summary, horizon_summary_kind, scene_ids, source_manifest_hash, source_splits, source_store_dir

1.1.7 SchemaValidation

rollouts.inspection.inventory.SchemaValidation(
    ok,
    num_rollouts,
    num_steps,
    num_candidates,
    errors,
)

Immutable schema-validation result with ordered errors.

1.2 Functions

Name	Description
build_compact_statistics	Compute compact statistics, reusing a supplied manifest snapshot.
build_effective_streamlit_trust	Compose independent trust facets without mutating either input.
build_manifest_facts	Read or reuse exactly one manifest snapshot.
build_promotion_evidence	Evaluate promotion evidence only for consumers that demand it.
build_schema_validation	Validate one store without exposing the reader’s mutable result.
decode_strategy_id	Return the stable orientation/strategy name for one numeric id.
decode_target_invalid_reason	Return the stable target-invalidity reason name for one numeric code.
discover_rollout_store_paths	Return rollout Zarr store candidates under a cache directory.
inspect_rollout_store_metadata	Inspect one registered store path using only top-level metadata files.
pairwise_finite_pearson	Compute finite paired Pearson correlations without pooling missing rows.
promoted_store_validation_error	Return an error when campaign completion evidence is not current.
rollout_header_summary	Return selected-store counts, reference coverage, and whole-store byte costs.
rollout_statistics	Compute the compact statistics shared by CLI and report consumers.
rollout_store_inventory_rows	Return schema, validation, count, lineage, and storage rows for stores.
runtime_storage_statistics	Return compact file-count and byte-cost statistics for one store.
selected_competition_rank	Rank one selected value over finite mask-supported alternatives.

1.2.1 build_compact_statistics

rollouts.inspection.inventory.build_compact_statistics(
    reader,
    *,
    manifest_payload=None,
)

Compute compact statistics, reusing a supplied manifest snapshot.

1.2.2 build_effective_streamlit_trust

rollouts.inspection.inventory.build_effective_streamlit_trust(schema, promotion)

Compose independent trust facets without mutating either input.

1.2.3 build_manifest_facts

rollouts.inspection.inventory.build_manifest_facts(
    reader,
    *,
    manifest_payload=None,
)

Read or reuse exactly one manifest snapshot.

1.2.4 build_promotion_evidence

rollouts.inspection.inventory.build_promotion_evidence(
    reader,
    *,
    manifest_payload=None,
    evaluator=None,
)

Evaluate promotion evidence only for consumers that demand it.

1.2.5 build_schema_validation

rollouts.inspection.inventory.build_schema_validation(reader)

Validate one store without exposing the reader’s mutable result.

1.2.6 decode_strategy_id

rollouts.inspection.inventory.decode_strategy_id(strategy_id)

Return the stable orientation/strategy name for one numeric id.

1.2.7 decode_target_invalid_reason

rollouts.inspection.inventory.decode_target_invalid_reason(reason)

Return the stable target-invalidity reason name for one numeric code.

1.2.8 discover_rollout_store_paths

rollouts.inspection.inventory.discover_rollout_store_paths(
    base_dir,
    *,
    pattern='**/*.zarr',
)

Return rollout Zarr store candidates under a cache directory.

1.2.8.1 Parameters

Name	Type	Description	Default
base_dir	Path	Directory to scan recursively.	required
pattern	str	Glob pattern used to find Zarr directories.	'**/*.zarr'

1.2.8.2 Returns

Name	Type	Description
	list[Path]	Absolute store paths sorted with the newest candidates first.

1.2.9 inspect_rollout_store_metadata

rollouts.inspection.inventory.inspect_rollout_store_metadata(store_path)

Inspect one registered store path using only top-level metadata files.

Reads zarr.json, manifest.json and, when present, the two promotion markers. No directory discovery, array reads, file-size walk, or content-seal recomputation occurs. Reinvoke after a path is replaced; this observation is not a durable validation of the payload.

1.2.10 pairwise_finite_pearson

rollouts.inspection.inventory.pairwise_finite_pearson(values, columns)

Compute finite paired Pearson correlations without pooling missing rows.

Columns must describe the same ordered observations and therefore have equal lengths. Each pair then has its own finite-row denominator. Fewer than two paired rows, constant values, and non-finite results remain unavailable with an explicit reason; in particular, n=2 is retained as degenerate evidence rather than silently presented as a substantive correlation.

1.2.11 promoted_store_validation_error

rollouts.inspection.inventory.promoted_store_validation_error(
    reader,
    *,
    manifest_payload=None,
)

Return an error when campaign completion evidence is not current.

1.2.12 rollout_header_summary

rollouts.inspection.inventory.rollout_header_summary(
    reader,
    *,
    manifest_payload=None,
)

Return selected-store counts, reference coverage, and whole-store byte costs.

Reference coverage is available only when manifest provenance supplies an explicit denominator. Observed source rows never define that denominator.

1.2.13 rollout_statistics

rollouts.inspection.inventory.rollout_statistics(
    reader,
    *,
    manifest_payload=None,
)

Compute the compact statistics shared by CLI and report consumers.

1.2.13.1 Parameters

Name	Type	Description	Default
reader	RolloutZarrStoreReader	Read-only rollout-store adapter.	required
manifest_payload	dict[str, Any] | None	Optional result of RolloutZarrStoreReader.manifest. The reader is queried when omitted.	None

1.2.13.2 Returns

Name	Type	Description
	dict[str, Any]	Nested candidate-validity, selected-action, policy, and source-coverage
	dict[str, Any]	statistics. Missing numeric samples remain explicit None values.

1.2.14 rollout_store_inventory_rows

rollouts.inspection.inventory.rollout_store_inventory_rows(
    store_paths,
    *,
    validate=True,
    include_payload_statistics=True,
)

Return schema, validation, count, lineage, and storage rows for stores.

1.2.14.1 Parameters

Name	Type	Description	Default
store_paths	Iterable[Path]	Candidate rollout-store directories.	required
validate	bool	Run the full cross-array validator for every discovered store. Interactive selectors may disable this and validate only the selected immutable store.	True
include_payload_statistics	bool	Read mask, policy and horizon payloads for detailed summaries, including a recursive filesystem size/count. Disable together with validate for metadata-only discovery; horizons then summarize manifest-declared configuration with horizon_summary_kind="configured" rather than observed payloads. horizon_min and horizon_max always describe configuration. Other omitted statistics remain None, while row counts use array-shape metadata. Existing detailed callers retain the default. Disk bytes and file counts remain None until requested; omission must not be presented as a measured zero.	True

1.2.15 runtime_storage_statistics

rollouts.inspection.inventory.runtime_storage_statistics(
    store_dir,
    *,
    candidate_count,
)

Return compact file-count and byte-cost statistics for one store.

1.2.15.1 Parameters

Name	Type	Description	Default
store_dir	Path	Rollout Zarr directory whose regular files are measured.	required
candidate_count	int	Persisted candidate rows used to normalize byte cost.	required

1.2.15.2 Returns

Name	Type	Description
	dict[str, float | int | str | None]	Storage totals and the existing rollout-preflight limits. The function
	dict[str, float | int | str | None]	reads file metadata only and does not open or mutate Zarr arrays.

1.2.16 selected_competition_rank

rollouts.inspection.inventory.selected_competition_rank(
    values,
    *,
    valid_mask,
    selected_index,
)

Rank one selected value over finite mask-supported alternatives.

Equal values share the same one-based competition rank. The returned denominator contains only finite rows admitted by valid_mask; an invalid, absent, or non-finite selection has no rank.