1 rollouts.inspection

rollouts.inspection

Question-oriented rollout evidence.

The package keeps two historical imports used by the published target-orbit evidence recipe. New code should import every other reducer from its owning leaf module; see aria_nbv.rollouts.inspection.inventory, aria_nbv.rollouts.inspection.candidates, aria_nbv.rollouts.inspection.policies, aria_nbv.rollouts.inspection.invariants, and aria_nbv.rollouts.inspection.geometry.

1.1 Package guide

This package owns presentation-free evidence queries over immutable rollout stores. It is split by the scientific question a caller asks, so each leaf hides storage traversal and exposes complete evidence rather than a collection of table helpers.

inventory.py discovers stores and establishes manifest, schema, promotion, and compact-statistics trust.
candidates.py reduces candidate populations, composition, calibration, collision, direction, and support evidence while preserving generation-cohort boundaries.
policies.py compares selection sequences, returns, temporal behavior, reconstruction endpoints, and oracle headroom without pooling incompatible cohorts.
invariants.py audits masks, QH availability, selected depth, target state, and suspicious rows.
geometry.py builds typed proposal, trajectory, frustum, and target-frame S² projections.
audits.py contains tensor-level policy, ordering, provenance, and path diagnostics; s2.py binds a configured store acquisition to its canonical evidence digest.
recipe_experiment.py compares jointly available acquisition-prefix endpoints, averaging target/replica effects within physical scenes before averaging scenes equally.
retained_selection.py checks recorded selector evidence and owns exploratory_scene_bootstrap_95, the shared percentile interval over finite pre-aggregated physical-scene scalar summaries. Its keyword-only seed and resamples default to 7 and 4096; diagnostic accuracy summaries retain their own meaning rather than becoming paired treatment effects. Recipe prefix results retain that explicitly exploratory interval with scene effects and support counts; fewer than two paired scenes remains unavailable. The conditional observed population and a degenerate empirical interval do not establish population coverage, generalization, zero uncertainty or promotion.
support.py owns fail-closed proposal and continuation opportunity diagnostics over an independently declared root population.

Import from the leaf that answers the question. The package initializer retains only the two historical imports used by the published target-orbit evidence recipe; it is not the general API catalog. Reducers preserve factual row order, masks, missingness, generation_cohort_id, and persisted reason codes. Presentation code belongs in rollouts.presentation.

1.2 Retained selector and heading inspection

selector_screen.inspect_selector_store validates a factual store before checking its exact clean producer revision, resolved writer configuration, calibrated camera roots, candidate eligibility, recorded logits, probabilities and selected lineage. Import it from the leaf, or run python -m aria_nbv.rollouts.inspection.selector_screen --help for the read-only JSON CLI. The expected writer configuration is a resolved JSON mapping, not a TOML generation configuration. Source/configuration identity checks do not replace canonical shard content seals or independent endpoint receipts.

The private archived heading decoder reads historical single-draw robust softmax experiments; it does not extend the current acquisition policy. selector_math computes world-Z-up horizontal displacement cost and its availability flag. Missing or vertical displacements have neutral cost with false availability; they are not measured straight motion. Normalization reuses the canonical replay calculation through retained_selection.producer_robust_temperature_logits. Zero heading weight preserves the exact producer operation order, dtype and device; the existing NumPy retained-producer check retains its explicit float32 conversion.

Temperature/heading shadows describe immediate distributions on retained factual shells. They do not predict changed successor states, cumulative trajectory returns or corpus admission. Factual prefixes retain missing gains and indicate that no independent prefix audit was performed. Summaries first average defined states within physical scenes, then weight scenes equally, with full state/scene availability counts. No candidate-row or trajectory-step IID uncertainty is reported. See tests/rollouts/test_selector_screen.py and test_selection_motion.py for mask, source, geometry, missingness and canonical math regressions.

1.3 Exact-path metadata observation

inventory.inspect_rollout_store_metadata(path) reads one exact store’s root, manifest and promotion metadata. Its immutable observation and inventory projection expose declared counts as unverified_metadata; payload validation and the recorded content seal are not verified. Reinvoke after replacement. This query performs no directory discovery, array reads or recursive statistics. The existing inventory’s optional payload statistics and deep validation remain separate operations. Missing, inconsistent, symlinked or partial promotion metadata is reported explicitly.

1.4 Source-bound primary sampler explanations

candidates.candidate_audit_rows retains the stored primary reason/ID/bitset, materialized order and every scientific mask. Its separate primary_outcome display column refines only primary SAMPLER_RULE_REJECTED rows into step-distance, height-change, both, or unresolved/other. Independent-trigger heatmaps keep the original overlapping bitsets; parent and child categories are never additive.

sampler_rejections reconstructs the producer’s strict FP32 > motion checks from persisted diagnostics and the authenticated original acquisition config, including after packing/repacking. Explicit null limits disable a guard; absent keys or metrics do not. Equal step/height limits are allowed. Every explanation carries method version, original producer/config/acquisition hashes and limits. SAMPLER_CLASSIFICATION_VERSION is the cache/provenance version for this derived explanation, not a store or generation schema revision.

The supported producer revisions are deliberately an explicit audited set. Unknown or dirty producers remain unresolved until their rule semantics are reviewed. Active yaw guards also remain unresolved because persisted degrees cannot establish the original radian comparison at a rounding boundary. These restrictions preserve an honest partial explanation without changing generation or relaxing admissibility. See tests/rollouts/test_sampler_rejections.py for source isolation, packed-source lookup, missingness and strict-boundary proof.

1.5 Functions

Name	Description
candidate_audit_rows	Project full source-qualified candidate rows without mutating the store.
proposal_support_geometry	Project complete candidate shells around their factual expansion poses.

1.5.1 candidate_audit_rows

rollouts.inspection.candidate_audit_rows(
    reader,
    *,
    rollout_row_id=None,
    step_row_id=None,
    limit=None,
    row_callback=None,
)

Project full source-qualified candidate rows without mutating the store.

Original primary names/IDs/bitsets and masks remain intact. primary_outcome is a separate display partition, whose sampler subcategories reconstruct the original acquisition’s audited motion bounds. Missing or unsupported source evidence yields an explicitly unresolved sampler explanation. Callback mode streams every admitted row without retaining a display-sized subset.

1.5.2 proposal_support_geometry

rollouts.inspection.proposal_support_geometry(
    reader,
    *,
    alignment=ProposalAlignment.TARGET_ALIGNED_Z_UP,
    rollout_row_ids=None,
    step_row_ids=None,
    max_candidates=50000,
)

Project complete candidate shells around their factual expansion poses.

Step zero uses the persisted rollout root; later steps use the preceding factual selected pose. Coordinates are divided by that expansion pose’s current 3D target distance, then yaw-aligned while preserving world Z-up.

A step filter still walks preceding factual steps so a requested later shell retains its persisted previous-selected expansion pose. Candidate limits count only shells admitted by both rollout and step filters.

# rollouts.inspection { #aria_nbv.rollouts.inspection } `rollouts.inspection` Question-oriented rollout evidence. The package keeps two historical imports used by the published target-orbit evidence recipe. New code should import every other reducer from its owning leaf module; see :mod:`aria_nbv.rollouts.inspection.inventory`, :mod:`aria_nbv.rollouts.inspection.candidates`, :mod:`aria_nbv.rollouts.inspection.policies`, :mod:`aria_nbv.rollouts.inspection.invariants`, and :mod:`aria_nbv.rollouts.inspection.geometry`.  ## Package guide This package owns presentation-free evidence queries over immutable rollout stores. It is split by the scientific question a caller asks, so each leaf hides storage traversal and exposes complete evidence rather than a collection of table helpers. - `inventory.py` discovers stores and establishes manifest, schema, promotion, and compact-statistics trust. - `candidates.py` reduces candidate populations, composition, calibration, collision, direction, and support evidence while preserving generation-cohort boundaries. - `policies.py` compares selection sequences, returns, temporal behavior, reconstruction endpoints, and oracle headroom without pooling incompatible cohorts. - `invariants.py` audits masks, QH availability, selected depth, target state, and suspicious rows. - `geometry.py` builds typed proposal, trajectory, frustum, and target-frame S² projections. - `audits.py` contains tensor-level policy, ordering, provenance, and path diagnostics; `s2.py` binds a configured store acquisition to its canonical evidence digest. - `recipe_experiment.py` compares jointly available acquisition-prefix endpoints, averaging target/replica effects within physical scenes before averaging scenes equally. - `retained_selection.py` checks recorded selector evidence and owns `exploratory_scene_bootstrap_95`, the shared percentile interval over finite pre-aggregated physical-scene scalar summaries. Its keyword-only `seed` and `resamples` default to 7 and 4096; diagnostic accuracy summaries retain their own meaning rather than becoming paired treatment effects. Recipe prefix results retain that explicitly exploratory interval with scene effects and support counts; fewer than two paired scenes remains unavailable. The conditional observed population and a degenerate empirical interval do not establish population coverage, generalization, zero uncertainty or promotion. - `support.py` owns fail-closed proposal and continuation opportunity diagnostics over an independently declared root population. Import from the leaf that answers the question. The package initializer retains only the two historical imports used by the published target-orbit evidence recipe; it is not the general API catalog. Reducers preserve factual row order, masks, missingness, `generation_cohort_id`, and persisted reason codes. Presentation code belongs in `rollouts.presentation`. ## Retained selector and heading inspection `selector_screen.inspect_selector_store` validates a factual store before checking its exact clean producer revision, resolved writer configuration, calibrated camera roots, candidate eligibility, recorded logits, probabilities and selected lineage. Import it from the leaf, or run `python -m aria_nbv.rollouts.inspection.selector_screen --help` for the read-only JSON CLI. The expected writer configuration is a resolved JSON mapping, not a TOML generation configuration. Source/configuration identity checks do not replace canonical shard content seals or independent endpoint receipts. The private archived heading decoder reads historical single-draw robust softmax experiments; it does not extend the current acquisition policy. `selector_math` computes world-Z-up horizontal displacement cost and its availability flag. Missing or vertical displacements have neutral cost with false availability; they are not measured straight motion. Normalization reuses the canonical replay calculation through `retained_selection.producer_robust_temperature_logits`. Zero heading weight preserves the exact producer operation order, dtype and device; the existing NumPy retained-producer check retains its explicit float32 conversion. Temperature/heading shadows describe immediate distributions on retained factual shells. They do not predict changed successor states, cumulative trajectory returns or corpus admission. Factual prefixes retain missing gains and indicate that no independent prefix audit was performed. Summaries first average defined states within physical scenes, then weight scenes equally, with full state/scene availability counts. No candidate-row or trajectory-step IID uncertainty is reported. See `tests/rollouts/test_selector_screen.py` and `test_selection_motion.py` for mask, source, geometry, missingness and canonical math regressions. ## Exact-path metadata observation `inventory.inspect_rollout_store_metadata(path)` reads one exact store's root, manifest and promotion metadata. Its immutable observation and inventory projection expose declared counts as `unverified_metadata`; payload validation and the recorded content seal are not verified. Reinvoke after replacement. This query performs no directory discovery, array reads or recursive statistics. The existing inventory's optional payload statistics and deep validation remain separate operations. Missing, inconsistent, symlinked or partial promotion metadata is reported explicitly. ## Source-bound primary sampler explanations `candidates.candidate_audit_rows` retains the stored primary reason/ID/bitset, materialized order and every scientific mask. Its separate `primary_outcome` display column refines only primary `SAMPLER_RULE_REJECTED` rows into step-distance, height-change, both, or unresolved/other. Independent-trigger heatmaps keep the original overlapping bitsets; parent and child categories are never additive. `sampler_rejections` reconstructs the producer's strict FP32 `>` motion checks from persisted diagnostics and the authenticated original acquisition config, including after packing/repacking. Explicit null limits disable a guard; absent keys or metrics do not. Equal step/height limits are allowed. Every explanation carries method version, original producer/config/acquisition hashes and limits. `SAMPLER_CLASSIFICATION_VERSION` is the cache/provenance version for this derived explanation, not a store or generation schema revision. The supported producer revisions are deliberately an explicit audited set. Unknown or dirty producers remain unresolved until their rule semantics are reviewed. Active yaw guards also remain unresolved because persisted degrees cannot establish the original radian comparison at a rounding boundary. These restrictions preserve an honest partial explanation without changing generation or relaxing admissibility. See `tests/rollouts/test_sampler_rejections.py` for source isolation, packed-source lookup, missingness and strict-boundary proof.  ## Functions | Name | Description | | --- | --- | | [candidate_audit_rows](#aria_nbv.rollouts.inspection.candidate_audit_rows) | Project full source-qualified candidate rows without mutating the store. | | [proposal_support_geometry](#aria_nbv.rollouts.inspection.proposal_support_geometry) | Project complete candidate shells around their factual expansion poses. | ### candidate_audit_rows { #aria_nbv.rollouts.inspection.candidate_audit_rows } ```python rollouts.inspection.candidate_audit_rows( reader, *, rollout_row_id=None, step_row_id=None, limit=None, row_callback=None, ) ``` Project full source-qualified candidate rows without mutating the store. Original primary names/IDs/bitsets and masks remain intact. ``primary_outcome`` is a separate display partition, whose sampler subcategories reconstruct the original acquisition's audited motion bounds. Missing or unsupported source evidence yields an explicitly unresolved sampler explanation. Callback mode streams every admitted row without retaining a display-sized subset. ### proposal_support_geometry { #aria_nbv.rollouts.inspection.proposal_support_geometry } ```python rollouts.inspection.proposal_support_geometry( reader, *, alignment=ProposalAlignment.TARGET_ALIGNED_Z_UP, rollout_row_ids=None, step_row_ids=None, max_candidates=50000, ) ``` Project complete candidate shells around their factual expansion poses. Step zero uses the persisted rollout root; later steps use the preceding factual selected pose. Coordinates are divided by that expansion pose's current 3D target distance, then yaw-aligned while preserving world Z-up. A step filter still walks preceding factual steps so a requested later shell retains its persisted previous-selected expansion pose. Candidate limits count only shells admitted by both rollout and step filters.