1 vin.diagnostics.qh_evidence

vin.diagnostics.qh_evidence

Bounded, rendering-neutral factual Q_H batches and optional scorer evidence.

The snapshot is deliberately made only of frozen records, tuples, and JSON scalars. It therefore owns its diagnostic values without retaining tensor storage, an autograd graph, the scorer, or the source batch. Acquisition and checkpoint admission remain with their existing owners; this module observes an already admitted scorer and QhBatch.

1.1 Classes

Name	Description
QhBatchEvidenceSnapshot	Owned scorer-free factual batch evidence shared by display adapters.
QhCoralEvidence	Bounded ordinal arithmetic for the displayed candidate rows.
QhEvidenceScope	Full scored shape and bounded copied extent.
QhEvidenceSelection	Display-copy limits applied after the full admitted batch is scored.
QhEvidenceSnapshot	Owned evidence product shared by Streamlit and static export.
QhFeatureBlock	One complete named readout vector copied from the bounded trace.
QhGeometryRow	Root-frame position for one factual or candidate pose.
QhHistoryRow	One entry of the factual strict-prefix history support matrix.
QhModuleRow	Construction metadata for one registered scorer module.
QhOutputRow	One candidate-aligned prediction with factual supports kept separate.
QhPopulationStats	Mask-aware accounting for one selected numeric population.
QhStateEvidenceRow	Factual selection compared with the complete finite labelled population.
QhSupportRow	Support counts for one source-aligned chain and state row.
QhTraceRow	Bounded hook record; complete means every source element was copied.
QhUtilityRow	Immediate supervision for one bounded candidate; absent labels stay absent.

1.1.1 QhBatchEvidenceSnapshot

vin.diagnostics.qh_evidence.QhBatchEvidenceSnapshot(
    scope,
    provenance,
    support,
    history,
    geometry,
    states,
    utilities,
)

Owned scorer-free factual batch evidence shared by display adapters.

Display quotas bound copies, never the population used for selection ranks. No tensors or source batch references survive acquisition. Geometry uses the actor’s root-relative poses; rewards remain supervision-only records.

1.1.1.1 Attributes

Name	Description
scope	Full batch axes and bounded display-copy extent.
provenance	Caller-supplied strict-JSON source identity.
support	Independent materialized, action-valid and label-supported counts per copied state.
history	Owned strict-prefix presence matrix for copied states.
geometry	Owned root-frame positions from actor poses, keyed by source row.
states	Full-population factual selection statistics for copied states.
utilities	Bounded candidate supervision records retaining the factual selected row.

1.1.2 QhCoralEvidence

vin.diagnostics.qh_evidence.QhCoralEvidence(
    bin_edges,
    bin_values,
    row_ids,
    threshold_logits,
    class_probabilities,
    monotonicity_violation_rate,
)

Bounded ordinal arithmetic for the displayed candidate rows.

1.1.2.1 Attributes

Name	Description
bin_edges	Continuous ordinal label boundaries.
bin_values	Continuous representatives used for scalar decoding.
row_ids	Stable (chain,state,candidate) identities aligned with every evidence row.
threshold_logits	Flattened displayed rows by cumulative threshold.
class_probabilities	Repaired class masses aligned with displayed rows.
monotonicity_violation_rate	Mean violation fraction over materialized rows, or None when none exist.

1.1.3 QhEvidenceScope

vin.diagnostics.qh_evidence.QhEvidenceScope(
    batch_shape,
    copied_chains,
    copied_states,
    copied_candidates,
    display_chain,
    display_state,
    partial,
)

Full scored shape and bounded copied extent.

1.1.3.1 Attributes

Name	Description
batch_shape	Complete scored (B,S,N) axes.
copied_chains	Leading chain rows copied into the snapshot.
copied_states	Leading state rows copied into the snapshot.
copied_candidates	Maximum candidate rows copied per state, retaining the factual selection.
display_chain	Copied chain selected for single-chain figures.
display_state	Copied state selected for detailed figures.
partial	Whether any copied axis is shorter than its complete scored axis.

1.1.4 QhEvidenceSelection

vin.diagnostics.qh_evidence.QhEvidenceSelection(
    max_chains=2,
    max_states=5,
    max_candidates=32,
    display_chain=0,
    display_state=0,
)

Display-copy limits applied after the full admitted batch is scored.

1.1.4.1 Attributes

Name	Description
max_chains	Maximum leading batch rows copied into per-row display records.
max_states	Maximum leading state rows copied; the scorer still receives every state.
max_candidates	Maximum candidate rows copied per state, retaining a factual selected row.
display_chain	Copied chain index used by single-chain figures.
display_state	Copied state index used by geometry, feature, and output figures.

1.1.5 QhEvidenceSnapshot

vin.diagnostics.qh_evidence.QhEvidenceSnapshot(
    scope,
    provenance,
    dto_rows,
    population_stats,
    support,
    history,
    geometry,
    feature_blocks,
    outputs,
    trace,
    model_type,
    total_parameters,
    trainable_parameters,
    modules,
    coral,
)

Owned evidence product shared by Streamlit and static export.

1.1.5.1 Attributes

Name	Description
scope	Complete scored axes and bounded copied extent.
provenance	Caller-supplied strict-JSON identity facts.
dto_rows	Shared Rich-summary atlas for actor, supervision, and output DTOs.
population_stats	Mask-aware finite and support accounting over the full selected batch.
support	Copied state-level materialization, validity, and label counts.
history	Copied query states with their complete causal-history axes.
geometry	Root-frame positions for the displayed state.
feature_blocks	Complete named feature vectors admitted by capture quotas.
outputs	Copied candidate-aligned model outputs and factual masks.
trace	Bounded registered-module tensor trace.
model_type	Fully qualified scorer type.
total_parameters	Total initialized scorer parameter elements.
trainable_parameters	Initialized scorer parameters with gradients enabled.
modules	Registered module metadata in traversal order.
coral	Ordinal diagnostics, or None for direct regression.

1.1.6 QhFeatureBlock

vin.diagnostics.qh_evidence.QhFeatureBlock(
    module_path,
    chain,
    state,
    candidate,
    names,
    units,
    values,
    available,
)

One complete named readout vector copied from the bounded trace.

1.1.6.1 Attributes

Name	Description
module_path	Registered producer path observed during the scorer forward.
chain	Batch-row index.
state	Query-state index.
candidate	Candidate index, or -1 for state-aligned directional history.
names	Producer-owned feature names in exact column order.
units	Physical units aligned with names.
values	Complete detached feature vector; unavailable entries are zero-filled.
available	Measurement availability aligned with values.

1.1.7 QhGeometryRow

vin.diagnostics.qh_evidence.QhGeometryRow(
    role,
    chain,
    state,
    candidate,
    x_m,
    y_m,
    z_m,
    selected,
)

Root-frame position for one factual or candidate pose.

1.1.7.1 Attributes

Name	Description
role	Pose role: target, current, factual history, or candidate.
chain	Batch-row index.
state	Displayed query-state index.
candidate	Candidate/history row identity, absent for shared target and current poses.
x_m	Root-frame x coordinate in metres.
y_m	Root-frame y coordinate in metres.
z_m	Root-frame z coordinate in metres.
selected	Whether this materialized candidate is the factual selected row.

1.1.8 QhHistoryRow

vin.diagnostics.qh_evidence.QhHistoryRow(chain, state, history_state, present)

One entry of the factual strict-prefix history support matrix.

1.1.8.1 Attributes

Name	Description
chain	Batch-row index.
state	Query-state index.
history_state	Factual selected-pose slot index.
present	Whether the slot belongs to the strict prefix for this query state.

1.1.9 QhModuleRow

vin.diagnostics.qh_evidence.QhModuleRow(
    path,
    module_type,
    direct_parameters,
    trainable_parameters,
    direct_buffers,
)

Construction metadata for one registered scorer module.

1.1.9.1 Attributes

Name	Description
path	Registered path, with <root> for the scorer.
module_type	Fully qualified concrete module type.
direct_parameters	Initialized parameters registered directly on this module.
trainable_parameters	Direct parameters whose gradients are enabled.
direct_buffers	Initialized buffers registered directly on this module.

1.1.10 QhOutputRow

vin.diagnostics.qh_evidence.QhOutputRow(
    chain,
    state,
    candidate,
    materialized,
    action_valid,
    label_supported,
    selected,
    conditional_q,
    feasibility_logit,
)

One candidate-aligned prediction with factual supports kept separate.

1.1.10.1 Attributes

Name	Description
chain	Batch-row index.
state	Query-state index.
candidate	Candidate-row index.
materialized	Whether this stored candidate row is present rather than padding.
action_valid	Caller-owned actor validity, separate from learned feasibility.
label_supported	Whether oracle supervision is available for this row.
selected	Whether this materialized row is the factual selected action.
conditional_q	Raw conditional-Q output; padding retains the scorer’s zero convention.
feasibility_logit	Raw learned feasibility logit; it is not a hard action mask.

1.1.11 QhPopulationStats

vin.diagnostics.qh_evidence.QhPopulationStats(
    name,
    total,
    included,
    finite,
    nonfinite,
    unavailable,
    excluded,
    minimum,
    maximum,
    mean,
)

Mask-aware accounting for one selected numeric population.

1.1.11.1 Attributes

Name	Description
name	Stable population identity including its support interpretation.
total	Number of aligned tensor entries before availability or selection masks.
included	Entries selected for the numerical reduction.
finite	Included entries with finite numeric values.
nonfinite	Included entries with non-finite numeric values.
unavailable	Entries outside the factual materialized population.
excluded	Available entries omitted by the named selection mask.
minimum	Finite selected minimum, or None for an empty finite population.
maximum	Finite selected maximum, or None for an empty finite population.
mean	Finite selected arithmetic mean, or None for an empty population.

1.1.12 QhStateEvidenceRow

vin.diagnostics.qh_evidence.QhStateEvidenceRow(
    chain,
    state,
    realized,
    horizon_remaining,
    selected_candidate,
    root_gain_rank,
    root_gain_support,
    root_gain_regret,
    root_gain_gap,
    target_rri_rank,
    target_rri_support,
    target_rri_regret,
    target_rri_gap,
)

Factual selection compared with the complete finite labelled population.

Ranks use one-based competition ordering (ties share rank). Regret is the supported maximum minus the selected value; gap is the top two supported values’ difference, absent with fewer than two labels. Neither is policy regret or a learned horizon value. Root-gain statistics describe the actual batch candidate_reward labels, potentially TRAIN-permuted rather than measured candidate gain; provenance records the label transformation.

1.1.12.1 Attributes

Name	Description
chain	Batch-row identity, not a physical-scene count.
state	Query-state row within the batch chain.
realized	Factual state mask; false for padded states.
horizon_remaining	Acquisition horizon from the actor; absent on padding.
selected_candidate	Materialized factual selection row, absent when not admitted.
root_gain_rank	One-based actual batch reward-label rank; may describe TRAIN-permuted labels, not measured gain.
root_gain_support	Full finite labelled root-gain denominator before display limits.
root_gain_regret	Supported maximum batch reward label minus selected label; absent without selected support.
root_gain_gap	Top-two supported batch reward-label difference; absent with fewer than two rows.
target_rri_rank	One-based target-RRI rank on its full finite labelled support.
target_rri_support	Full finite labelled target-RRI denominator before display limits.
target_rri_regret	Supported maximum target RRI minus factual selected target RRI.
target_rri_gap	Top-two supported target-RRI difference; absent with fewer than two rows.

1.1.13 QhSupportRow

vin.diagnostics.qh_evidence.QhSupportRow(
    chain,
    state,
    realized,
    materialized,
    action_valid,
    label_supported,
    selected_candidate,
)

Support counts for one source-aligned chain and state row.

1.1.13.1 Attributes

Name	Description
chain	Batch-row index in the scored selection.
state	State-row index in the scored selection.
realized	Whether this state is factual rather than padding.
materialized	Number of candidate rows present in this realized state.
action_valid	Number of materialized candidates admitted by the actor mask.
label_supported	Number of materialized candidates carrying oracle labels.
selected_candidate	Factual selected row when it is in range and materialized.

1.1.14 QhTraceRow

vin.diagnostics.qh_evidence.QhTraceRow(
    module_path,
    call_index,
    direction,
    tensor_path,
    shape,
    dtype,
    device,
    numel,
    sampled,
    sampled_bytes,
    complete,
    omission_reason,
)

Bounded hook record; complete means every source element was copied.

1.1.14.1 Attributes

Name	Description
module_path	Registered module path.
call_index	Zero-based invocation number for shared modules.
direction	Observed hook side, input or output.
tensor_path	Container path from module arguments or result.
shape	Complete source tensor shape at hook time.
dtype	Source dtype before bounded copying.
device	Source device before bounded copying.
numel	Complete source element count.
sampled	Number of detached CPU scalar values copied.
sampled_bytes	Source-dtype bytes represented by the copied prefix.
complete	Whether the copied tuple covers every source element.
omission_reason	Unsupported sampling reason, or None when numeric sampling applies.

1.1.15 QhUtilityRow

vin.diagnostics.qh_evidence.QhUtilityRow(
    chain,
    state,
    candidate,
    materialized,
    action_valid,
    label_supported,
    selected,
    root_gain,
    target_rri,
)

Immediate supervision for one bounded candidate; absent labels stay absent.

1.1.15.1 Attributes

Name	Description
chain	Batch-row identity, not a physical-scene count.
state	Query-state row within the batch chain.
candidate	Padded candidate-axis row, retained unchanged for geometry joins.
materialized	Realized candidate support; false for state or candidate padding.
action_valid	Hard actor mask on materialized support; not learned feasibility.
label_supported	Persisted label mask on materialized support, independent of finite-value checks.
selected	Whether this materialized row is the factual teacher-selected action.
root_gain	Actual batch candidate_reward label, possibly TRAIN-permuted; None without finite label support.
target_rri	Finite persisted target RRI, or None; never substituted for root gain.

1.2 Functions

Name	Description
build_qh_batch_evidence	Copy factual actor/support/label evidence without a scorer or inference.
build_qh_evidence	Observe one full, gradient-free Q_H forward and return bounded evidence.

1.2.1 build_qh_batch_evidence

vin.diagnostics.qh_evidence.build_qh_batch_evidence(
    batch,
    *,
    selection=_DEFAULT_SELECTION,
    provenance=(),
)

Copy factual actor/support/label evidence without a scorer or inference.

Both utility populations use realized, materialized, label-supported finite rows, before candidate display truncation. Root-normalized immediate gain and target RRI remain separate quantities; no RRI is recomputed. The reward is the actual batch candidate_reward, including any admitted TRAIN label transformation. Target RRI is not replaced by that transformed reward.

1.2.2 build_qh_evidence

vin.diagnostics.qh_evidence.build_qh_evidence(
    scorer,
    batch,
    *,
    requested_horizon=None,
    selection=_DEFAULT_SELECTION,
    capture_limits=None,
    provenance=(),
)

Observe one full, gradient-free Q_H forward and return bounded evidence.

Every registered module’s original training flag is restored individually, including mixed train/eval configurations and exceptional forwards. Hook cleanup is delegated to capture_model. Display limits bound only detached copies made after the ordinary forward; the scorer always receives the complete admitted actor, preserving its causal prefixes.