1 rollouts.inspection.support

rollouts.inspection.support

Fail-closed proposal and continuation diagnostics over rollout support.

The module reduces already materialized diagnostic evidence. It does not generate candidates, select targets, persist another rollout schema, or admit a production curriculum. Source and target identity come from the existing aria_nbv.rollouts.storage.trace DTOs, while intended root poses can be captured from aria_nbv.rollouts.replay.state.CounterfactualTrajectory.

The intended population is independent of successful records. Every root must produce exactly one success or explicit failure, and scene means are conditional on roots with defined finite maxima. Attempted and defined denominators remain visible so missing evidence is never interpreted as zero opportunity.

1.1 Classes

Name	Description
ActorChoice	Actor-only selection bound to table, history, order, and hard mask.
ContinuationDiagnostic	Privileged evaluation of one actor choice with separate support predicates.
DiagnosticAction	One physical action and its actor, Oracle, and supervision facts.
DiagnosticProtocol	Shared provenance and numerical contract for one diagnostic ledger.
DiagnosticResources	Optional measured work; None means unknown rather than measured zero.
DiagnosticRootKey	One independently declared scene, root, and observed-target task.
DiagnosticRootRecord	Exactly one successful shell pair or explicit failure for an intended root.
DiagnosticShell	Candidate table at one causally identified decision state.
DiagnosticStatus	Defined reductions and explicit reasons a finite maximum is unavailable.
IntendedDiagnosticRoot	Population entry declared before diagnostic acquisition succeeds or fails.
OpportunityGaps	Finite-support one-step proposal and selection regret decomposition.
ProposalDiagnostic	Checked nested-shell comparison; the reference is not a continuous optimum.
RootDiagnosticResult	Root result retaining failures, resources, proposal, and continuation evidence.
SceneDiagnostic	Conditional within-scene means with attempted and defined denominators.
SupportCounts	Attempted, feasible, and dense-labelled action denominators.
SupportDiagnosticLedger	Independent population plus one success/failure record for every root.
SupportDiagnosticReport	Descriptive scene-first report; never policy or continuous-optimum evidence.
SupportStratum	Selected actor support by scene, proposal family, and geometry bin.

1.1.1 ActorChoice

rollouts.inspection.support.ActorChoice(
    table_id,
    actor_history_id,
    action_ids,
    action_mask,
    selected_index,
    status,
)

Actor-only selection bound to table, history, order, and hard mask.

1.1.1.1 Attributes

Name	Description
table_id	Immutable candidate-table identity supplied to the actor.
actor_history_id	Acquired actor-visible history identity used to compute scores.
action_ids	Exact candidate identities in actor table order.
action_mask	Exact hard-feasibility mask supplied to the actor.
selected_index	Stable first argmax index, absent when actor selection is undefined.
status	Defined, terminal, empty-support, or incomplete-score outcome.

1.1.2 ContinuationDiagnostic

rollouts.inspection.support.ContinuationDiagnostic(
    status,
    support,
    oracle_reward=None,
    actor_reward=None,
    gap_to_actor=None,
    selected_action_id=None,
    selected_factual_successor=None,
    selected_dense_one_step_label=None,
    selected_horizon_label=None,
    selected_family=None,
    selected_geometry_stratum=None,
)

Privileged evaluation of one actor choice with separate support predicates.

1.1.2.1 Attributes

Name	Description
status	Whether the exact comparison is defined or why it is unavailable.
support	Attempted, feasible, and dense-labelled shell denominators.
oracle_reward	Exact feasible maximum, or zero for terminal and empty continuation.
actor_reward	Oracle evaluation of the fixed actor choice, when available.
gap_to_actor	Oracle minus actor reward; not an irreducible information-gap estimate.
selected_action_id	Actor-selected physical action identity.
selected_factual_successor	Whether the selected row has a persisted factual transition.
selected_dense_one_step_label	Whether the selected row has a finite dense immediate label.
selected_horizon_label	Whether the selected row has trustworthy requested-horizon support.
selected_family	Selected action’s proposal family.
selected_geometry_stratum	Selected action’s target-relative geometry bin.

1.1.3 DiagnosticAction

rollouts.inspection.support.DiagnosticAction(
    action_id,
    pose_world_camera,
    feasible,
    measurement_context,
    oracle_reward,
    factual_successor=False,
    horizon_label=False,
    family='unknown',
    geometry_stratum='unknown',
)

One physical action and its actor, Oracle, and supervision facts.

1.1.3.1 Attributes

Name	Description
action_id	Stable physical action identity, never a shell-local row index.
pose_world_camera	Flattened world-from-camera PoseTW describing the intervention.
feasible	Authoritative hard mask independent of actor scores and label availability.
measurement_context	Action-level renderer, assets, crop, cap, and reward context identity.
oracle_reward	Dense one-step root-gain label, or None when the label is unavailable.
factual_successor	Whether this row has a persisted factual successor transition.
horizon_label	Whether the requested-horizon label is defined; distinct from one-step density.
family	Proposal-family provenance used only for support accounting.
geometry_stratum	Producer-defined target-relative geometry bin.

1.1.4 DiagnosticProtocol

rollouts.inspection.support.DiagnosticProtocol(
    source_manifest_id,
    source_split='train',
    collection_split='train',
    shell_role='successor',
    horizon=1,
    measurement_protocol='root-gain-v1',
    target_protocol=TargetInputProtocol.V1_OBSERVED,
    action_support='actor_observed_action_mask_v1',
    pose_atol=1e-07,
    reward_atol=1e-07,
)

Shared provenance and numerical contract for one diagnostic ledger.

1.1.4.1 Attributes

Name	Description
source_manifest_id	Hash of the immutable VIN source manifest named by each source lineage.
source_split	Source-store split; challenger diagnostics are training-only.
collection_split	Campaign collection split, independently checked against source split.
shell_role	Decision stage shared by every shell in the ledger.
horizon	Requested label horizon; values above one require factual transitions.
measurement_protocol	Shared render, fusion, normalization, and reward measurement contract.
target_protocol	Actor-visible target admission and Oracle-binding protocol.
action_support	Common physical feasibility semantics used by both generators.
pose_atol	Absolute component tolerance for physical action and root poses.
reward_atol	Absolute tolerance for duplicate measurements of shared action rewards.

1.1.5 DiagnosticResources

rollouts.inspection.support.DiagnosticResources(
    oracle_calls=None,
    rendered_pixels=None,
    elapsed_seconds=None,
    peak_memory_bytes=None,
)

Optional measured work; None means unknown rather than measured zero.

1.1.5.1 Attributes

Name	Description
oracle_calls	Oracle invocations under the producer’s declared batching convention.
rendered_pixels	Measured rendered pixel work.
elapsed_seconds	Measured elapsed duration including retained failure work.
peak_memory_bytes	Measured peak memory under the producer’s declared device convention.

1.1.6 DiagnosticRootKey

rollouts.inspection.support.DiagnosticRootKey(scene_id, root_id, target_id)

One independently declared scene, root, and observed-target task.

1.1.6.1 Attributes

Name	Description
scene_id	Independent scene unit used for macro reduction.
root_id	Stable rollout-root identity, including any replica identity.
target_id	Actor-visible observed-target identity fixed before Oracle evaluation.

1.1.7 DiagnosticRootRecord

rollouts.inspection.support.DiagnosticRootRecord(
    key,
    source,
    target,
    baseline=None,
    reference=None,
    selected_action_id=None,
    actor_choice=None,
    failure=None,
    resources=DiagnosticResources(),
)

Exactly one successful shell pair or explicit failure for an intended root.

1.1.7.1 Attributes

Name	Description
key	Identity matching one independently declared population entry.
source	Existing persisted-source provenance DTO; no parallel source receipt is defined.
target	Existing actor/Oracle target-lineage DTO.
baseline	Baseline candidate support, absent only for explicit root failure.
reference	Broader diagnostic support containing all feasible baseline actions.
selected_action_id	Baseline policy choice fixed before diagnostic Oracle comparison.
actor_choice	Actor-only receipt formed before the reference shell’s Oracle labels are consumed.
failure	Explicit acquisition, admission, or measurement failure reason.
resources	Measured work for this attempt, with unknown fields retained as None.

1.1.8 DiagnosticShell

rollouts.inspection.support.DiagnosticShell(
    table_id,
    actor_history_id,
    generator_id,
    role,
    root_pose_world,
    measurement_protocol,
    action_support,
    actions,
    terminal=False,
)

Candidate table at one causally identified decision state.

1.1.8.1 Attributes

Name	Description
table_id	Immutable identity binding candidate identities, order, poses, and mask.
actor_history_id	Acquired actor-visible history identity at decision time.
generator_id	Frozen candidate-generator profile; baseline and reference may differ.
role	Initial-action or continuation decision stage.
root_pose_world	Flattened world-from-root pose used to materialize this table.
measurement_protocol	Shell-level measurement contract shared with the ledger protocol.
action_support	Hard-feasibility semantics shared by baseline and reference shells.
actions	All attempted rows in stable table order, including invalid and unlabelled rows.
terminal	Whether the state has no continuation by construction.

1.1.9 DiagnosticStatus

rollouts.inspection.support.DiagnosticStatus()

Defined reductions and explicit reasons a finite maximum is unavailable.

1.1.10 IntendedDiagnosticRoot

rollouts.inspection.support.IntendedDiagnosticRoot(
    key,
    root_pose_world,
    source_sample_key,
    split_manifest_hash,
    source_sample_index,
    descriptor_hash,
)

Population entry declared before diagnostic acquisition succeeds or fails.

1.1.10.1 Attributes

Name	Description
key	Stable task identity whose record must appear exactly once.
root_pose_world	Flattened world-from-root PoseTW independently binding the decision state.
source_sample_key	Canonical VIN sample identity expected for this intended root.
split_manifest_hash	Hash binding the split and ordered source ownership.
source_sample_index	Stable source-dataset row index.
descriptor_hash	Actor-visible descriptor identity frozen before Oracle evaluation.

1.1.10.2 Methods

Name	Description
from_trajectory	Capture replay root pose and current source-lineage identity.

1.1.10.2.1 from_trajectory

rollouts.inspection.support.IntendedDiagnosticRoot.from_trajectory(
    key,
    trajectory,
    *,
    source,
    descriptor_hash,
)

Capture replay root pose and current source-lineage identity.

1.1.11 OpportunityGaps

rollouts.inspection.support.OpportunityGaps(proposal, selection, total)

Finite-support one-step proposal and selection regret decomposition.

1.1.11.1 Attributes

Name	Description
proposal	Best finite-reference reward minus best baseline reward.
selection	Best baseline reward minus selected baseline reward.
total	Best finite-reference reward minus selected baseline reward.

1.1.12 ProposalDiagnostic

rollouts.inspection.support.ProposalDiagnostic(
    status,
    baseline_generator,
    reference_generator,
    baseline_support,
    reference_support,
    gaps,
)

Checked nested-shell comparison; the reference is not a continuous optimum.

1.1.12.1 Attributes

Name	Description
status	Whether exact gaps are defined or why they are unavailable.
baseline_generator	Frozen baseline generator identity.
reference_generator	Frozen broader diagnostic generator identity.
baseline_support	Attempted, feasible, and labelled baseline denominators.
reference_support	Attempted, feasible, and labelled reference denominators.
gaps	Finite-support decomposition, absent when an exact maximum is undefined.

1.1.13 RootDiagnosticResult

rollouts.inspection.support.RootDiagnosticResult(
    key,
    failure,
    resources,
    proposal,
    continuation,
)

Root result retaining failures, resources, proposal, and continuation evidence.

1.1.13.1 Attributes

Name	Description
key	Independently declared root-task identity.
failure	Explicit root acquisition/admission failure, if any.
resources	Measured resource facts with unknown values retained as None.
proposal	Nested-support result, absent on root failure.
continuation	Actor/Oracle continuation result, absent on root failure.

1.1.14 SceneDiagnostic

rollouts.inspection.support.SceneDiagnostic(
    scene_id,
    attempted_roots,
    defined_proposal_roots,
    defined_continuation_roots,
    proposal_status_counts,
    continuation_status_counts,
    root_failure_counts,
    mean_proposal_gap,
    mean_selection_gap,
    mean_total_gap,
    mean_gap_to_actor,
)

Conditional within-scene means with attempted and defined denominators.

1.1.14.1 Attributes

Name	Description
scene_id	Independent scene identity.
attempted_roots	All intended roots in the scene, including explicit failures.
defined_proposal_roots	Roots contributing to conditional proposal means.
defined_continuation_roots	Roots contributing to conditional actor-gap means.
proposal_status_counts	Proposal outcome counts including root failures.
continuation_status_counts	Continuation outcome counts including root failures.
root_failure_counts	Explicit producer failures grouped by reason.
mean_proposal_gap	Mean proposal gap over defined roots only.
mean_selection_gap	Mean selection gap over the same defined roots.
mean_total_gap	Mean total gap over the same defined roots.
mean_gap_to_actor	Mean actor gap over defined continuation roots only.

1.1.15 SupportCounts

rollouts.inspection.support.SupportCounts(attempted, feasible, labelled)

Attempted, feasible, and dense-labelled action denominators.

1.1.15.1 Attributes

Name	Description
attempted	All materialized actions, including hard-invalid rows.
feasible	Actions surviving the shared hard-feasibility mask.
labelled	Feasible actions with a finite dense one-step Oracle label.
missing_labels	Return feasible actions without a dense one-step Oracle label.

1.1.16 SupportDiagnosticLedger

rollouts.inspection.support.SupportDiagnosticLedger(
    protocol,
    population,
    records,
)

Independent population plus one success/failure record for every root.

1.1.16.1 Attributes

Name	Description
protocol	Single comparison contract shared by all records.
population	Intended roots declared independently of successful generation.
records	Exactly one retained success or failure per intended root.

1.1.16.2 Methods

Name	Description
validate	Revalidate the ledger, including mutable current-lineage DTO inputs.

1.1.16.2.1 validate

rollouts.inspection.support.SupportDiagnosticLedger.validate()

Revalidate the ledger, including mutable current-lineage DTO inputs.

1.1.17 SupportDiagnosticReport

rollouts.inspection.support.SupportDiagnosticReport(
    attempted_roots,
    attempted_scenes,
    defined_proposal_scenes,
    defined_continuation_scenes,
    scene_macro_proposal_gap,
    scene_macro_selection_gap,
    scene_macro_total_gap,
    scene_macro_gap_to_actor,
    records,
    scenes,
    selected_support,
    policy_evidence=False,
)

Descriptive scene-first report; never policy or continuous-optimum evidence.

1.1.17.1 Attributes

Name	Description
attempted_roots	Full independently declared root population size.
attempted_scenes	Scene population size, including wholly failed scenes.
defined_proposal_scenes	Scenes with at least one exact proposal decomposition.
defined_continuation_scenes	Scenes with at least one exact actor/Oracle comparison.
scene_macro_proposal_gap	Equal-scene mean conditional on defined proposal scenes.
scene_macro_selection_gap	Equal-scene selection mean on the defined proposal scenes.
scene_macro_total_gap	Equal-scene total mean on the defined proposal scenes.
scene_macro_gap_to_actor	Equal-scene actor-gap mean conditional on defined scenes.
records	All retained root successes and failures.
scenes	Per-scene attempted and defined denominators with conditional means.
selected_support	Factual, dense, and requested-horizon support of actor choices.
policy_evidence	Constant guard: diagnostics cannot authorize a production policy.

1.1.18 SupportStratum

rollouts.inspection.support.SupportStratum(
    scene_id,
    family,
    geometry_stratum,
    selected_actions,
    factual_successors,
    dense_one_step_labels,
    horizon_labels,
    comparable_actions,
    mean_gap_to_actor,
)

Selected actor support by scene, proposal family, and geometry bin.

1.1.18.1 Attributes

Name	Description
scene_id	Independent scene identity.
family	Selected proposal-family identity.
geometry_stratum	Selected target-relative geometry bin.
selected_actions	Actor selections in this support stratum.
factual_successors	Selections with a persisted factual transition.
dense_one_step_labels	Selections with a finite dense immediate label.
horizon_labels	Selections with trustworthy requested-horizon support.
comparable_actions	Selections contributing an exact actor-gap value.
mean_gap_to_actor	Conditional mean actor gap over comparable selections.

1.2 Functions

Name	Description
analyze_support	Reduce roots within scenes, then equally weight scenes with defined means.
continuation_diagnostic	Evaluate a previously chosen actor action against a complete Oracle shell.
proposal_diagnostic	Decompose regret on nested, fully labelled physical action supports.
select_actor_action	Choose from actor-only fields; no Oracle-label argument is accepted.
shell_support	Count support without conflating hard invalidity and missing labels.

1.2.1 analyze_support

rollouts.inspection.support.analyze_support(ledger)

Reduce roots within scenes, then equally weight scenes with defined means.

Numeric scene means are conditional on defined roots and cohort means are conditional on defined scenes. Attempted and defined denominators expose that conditioning; failed or incomplete roots are never assigned zero.

1.2.2 continuation_diagnostic

rollouts.inspection.support.continuation_diagnostic(shell, choice)

Evaluate a previously chosen actor action against a complete Oracle shell.

The gap is max_a reward(a) - reward(actor_choice) on this successor shell. It is a continuation-reward difference, not a full Q2 return unless the first reward and discount are also shared. A gap to this actor does not identify an irreducible information gap. Missing labels leave the maximum undefined; terminal or empty support has zero continuation but no measured information gap. Receipt validation precedes privileged evaluation.

1.2.3 proposal_diagnostic

rollouts.inspection.support.proposal_diagnostic(
    baseline,
    reference,
    *,
    selected_action_id,
    pose_atol,
    reward_atol,
)

Decompose regret on nested, fully labelled physical action supports.

For baseline B, finite reference R and selected action a in B, max(R) - reward(a) = (max(R) - max(B)) + (max(B) - reward(a)). The first term measures proposal opportunity; the second measures selection regret within the baseline. Both maxima require labels on every hard-valid row. Shared actions use the baseline measurement after tolerance checks, so measurement roundoff cannot break the identity. The reference is a finite diagnostic pool, never a continuous optimum.

1.2.4 select_actor_action

rollouts.inspection.support.select_actor_action(
    table_id,
    actor_history_id,
    action_ids,
    action_mask,
    actor_scores,
    terminal=False,
)

Choose from actor-only fields; no Oracle-label argument is accepted.

Ties preserve the supplied table order. A missing score on any hard-valid row leaves the choice undefined rather than selecting from a biased subset.

1.2.5 shell_support

rollouts.inspection.support.shell_support(shell)

Count support without conflating hard invalidity and missing labels.