1 rollouts.candidate_support.contracts
rollouts.candidate_support.contracts
Immutable candidate-support scientific contracts and geometry reducers.
1.1 Classes
| Name | Description |
|---|---|
| CandidateBenchmark | Frozen benchmark facts for one immutable candidate-generation state. |
| CandidateFamilyCounts | One factual state/family cell without fabricating missing provenance. |
| CandidateFamilyPhaseAEvidence | Immutable Phase-A proposal-support audit and canonical gate result. |
| CandidateFamilyPhaseAExpectation | Externally owned identities required to admit one Phase-A artifact. |
| CandidateFamilyPreflight | Canonical presentation-free Phase-A family-support decision. |
| CandidateFamilyPreflightConfig | Versioned family-support and label-variation policy. |
| CandidateFamilySelection | One factual state/family shell selection shared by UI and plots. |
| CandidatePoint | One persisted candidate row in the target-aligned proposal-support frame. |
| CandidatePopulationCoverage | Population counts used by the canonical family preflight decision. |
| CandidatePreflightBlocker | One deterministic go/no-go blocker, optionally scoped to scene/state/family. |
| CandidateSupportFailure | Machine-readable failure reasons kept distinct by the preflight gate. |
| EvidenceTransformationKind | Whether evidence came directly from generation or an authenticated reseal. |
| FlatGainOutcome | State-conditional label variation with exact label/state denominators. |
1.1.1 CandidateBenchmark
rollouts.candidate_support.contracts.CandidateBenchmark(
state_key,
scene_key,
families,
geometry=dict(),
diversity=dict(),
timings_ms=dict(),
resources=dict(),
provenance=dict(),
candidate_ids=(),
coordinates=(),
lineage=dict(),
points=(),
oracle_target_root_gains=(),
)Frozen benchmark facts for one immutable candidate-generation state.
1.1.1.1 Methods
| Name | Description |
|---|---|
| to_record | Flatten facts into one deterministic row for Parquet. |
| to_phase_a_record | Project the historical label-free Phase-A row without v2 gain columns. |
1.1.1.1.1 to_record
rollouts.candidate_support.contracts.CandidateBenchmark.to_record()Flatten facts into one deterministic row for Parquet.
1.1.1.1.2 to_phase_a_record
rollouts.candidate_support.contracts.CandidateBenchmark.to_phase_a_record()Project the historical label-free Phase-A row without v2 gain columns.
The authenticated Phase-A artifact predates benchmark bundle schema v2 and is explicitly forbidden from containing oracle reward labels. This projection keeps that artifact byte-stable while to_record owns the current complete benchmark-bundle schema.
1.1.2 CandidateFamilyCounts
rollouts.candidate_support.contracts.CandidateFamilyCounts(
family,
applicable,
attempted=0,
valid=0,
selected=0,
denominator=0,
reason=None,
invalid_reason_bitsets=(),
first_failure=None,
margins=dict(),
refill_rounds=None,
fallback_used=None,
support_failure=None,
)One factual state/family cell without fabricating missing provenance.
applicable=None denotes an unknown legacy state, not false. Diagnostic fields summarize only values persisted for the cell; absent margins, refill state, fallback state, or support failure remain None.
1.1.2.1 Methods
| Name | Description |
|---|---|
| to_payload | Return a compact serializable projection without copying the proxy. |
1.1.2.1.1 to_payload
rollouts.candidate_support.contracts.CandidateFamilyCounts.to_payload()Return a compact serializable projection without copying the proxy.
1.1.3 CandidateFamilyPhaseAEvidence
rollouts.candidate_support.contracts.CandidateFamilyPhaseAEvidence(
source_manifest_sha256,
source_store_manifest_hash,
source_cache_version,
split_manifest_hash,
source_store_dir,
writer_config_sha256,
writer_config_identity_revision,
provenance_correction_revision,
evidence_assembly_revision,
predecessor_artifact_sha256,
transformation_kind,
implementation_revision,
generation_revision,
runtime_identity,
source_row_count,
scene_count,
target_state_count,
excluded_source_rows,
records,
preflight,
)Immutable Phase-A proposal-support audit and canonical gate result.
This is a no-render, no-reward-label Phase-A proposal-support audit with privileged GT target instruction and mesh validity. It therefore uses oracle-owned target geometry for instruction and physical validity without claiming to be oracle-free.
source_manifest_sha256 binds the reviewed manifest file bytes, while source_store_manifest_hash preserves the VIN store’s native canonical manifest identity. Current stores use the repository’s 16-hex stable msgspec hash; older compatible evidence may carry a 64-hex identity. These two provenance domains are intentionally not re-hashed into one another.
1.1.3.1 Methods
| Name | Description |
|---|---|
| to_payload | Serialize records and the one reducer result with a content hash. |
1.1.3.1.1 to_payload
rollouts.candidate_support.contracts.CandidateFamilyPhaseAEvidence.to_payload()Serialize records and the one reducer result with a content hash.
1.1.4 CandidateFamilyPhaseAExpectation
rollouts.candidate_support.contracts.CandidateFamilyPhaseAExpectation(
source_manifest_sha256,
source_store_manifest_hash,
source_cache_version,
split_manifest_hash,
source_store_dir,
writer_config_sha256,
generation_revision_hash,
)Externally owned identities required to admit one Phase-A artifact.
1.1.5 CandidateFamilyPreflight
rollouts.candidate_support.contracts.CandidateFamilyPreflight(
go,
schema_id,
config_sha256,
config,
query_width,
resolved_min_valid,
cells,
blockers,
flat_gain,
coverage,
audit_strata,
)Canonical presentation-free Phase-A family-support decision.
1.1.5.1 Methods
| Name | Description |
|---|---|
| to_payload | Serialize the single canonical decision for CLI, campaign, and UI. |
1.1.5.1.1 to_payload
rollouts.candidate_support.contracts.CandidateFamilyPreflight.to_payload()Serialize the single canonical decision for CLI, campaign, and UI.
1.1.6 CandidateFamilyPreflightConfig
rollouts.candidate_support.contracts.CandidateFamilyPreflightConfig(
query_width,
configured_families,
target_aware_families=('target_bearing_local', 'lateral_target_bypass'),
forward_family='forward_local',
min_selected_per_applicable_family=1,
min_selected_target_aware_total=3,
flat_gain_tolerance=0.0001,
flat_gain_aggregation=FLAT_GAIN_AGGREGATION,
require_known_applicability=True,
expected_population_size=None,
audit_strata_count=10,
family_floor_revision=FAMILY_SUPPORT_FLOOR_REVISION,
flat_gain_revision=FLAT_GAIN_REVISION,
)Versioned family-support and label-variation policy.
The resolved root threshold is max(12, ceil(0.25 * query_width)). Family floors are independent: every applicable family must contribute at least one selected row in each factual state, while applicable non-forward target-aware families must contribute at least three selected rows in total. flat_gain_tolerance is applied to the exact finite, oracle-labelled target-root-gain range; it never infers reward from geometry.
1.1.6.1 Attributes
| Name | Description |
|---|---|
| resolved_min_valid | Return the persisted root-support threshold for this query width. |
| config_sha256 | Bind every gate decision to the exact versioned policy. |
1.1.6.2 Methods
| Name | Description |
|---|---|
| to_payload | Serialize the complete reader-resolvable family policy. |
| from_payload | Decode one complete persisted family policy without defaults. |
1.1.6.2.1 to_payload
rollouts.candidate_support.contracts.CandidateFamilyPreflightConfig.to_payload()Serialize the complete reader-resolvable family policy.
1.1.6.2.2 from_payload
rollouts.candidate_support.contracts.CandidateFamilyPreflightConfig.from_payload(
payload,
)Decode one complete persisted family policy without defaults.
1.1.7 CandidateFamilySelection
rollouts.candidate_support.contracts.CandidateFamilySelection(
scene_key,
state_key,
family,
)One factual state/family shell selection shared by UI and plots.
1.1.8 CandidatePoint
rollouts.candidate_support.contracts.CandidatePoint(
candidate_id,
xyz,
family,
position,
actor_valid,
selected,
state_key,
candidate_config=None,
rollout_config=None,
branch_schedule=None,
unavailable_reason=None,
target_relative_xyz=None,
view_direction_xyz=None,
view_jitter_yaw_deg=None,
view_jitter_pitch_deg=None,
view_jitter_is_bounded=None,
view_jitter_azimuth_limit_deg=None,
view_jitter_elevation_limit_deg=None,
oracle_label=False,
target_root_gain=None,
)One persisted candidate row in the target-aligned proposal-support frame.
1.1.8.1 Attributes
| Name | Description |
|---|---|
| candidate_id | Stable candidate-row identity in the rollout store. |
| xyz | Candidate centre in the normalized proposal-support frame. |
| family | Configured proposal-family identifier. |
| position | Persisted position strategy used to generate the candidate. |
| actor_valid | Whether the candidate passes the authoritative physical action mask. |
| selected | Whether the rollout policy selected this candidate at the factual state. |
| state_key | Stable rollout:<id>/step:<id> factual-state identity. |
| candidate_config | Persisted candidate-generation configuration lineage, when available. |
| rollout_config | Persisted rollout configuration lineage, when available. |
| branch_schedule | Persisted branch schedule lineage, when available. |
| unavailable_reason | Explicit reason when a legacy store cannot supply a requested diagnostic. |
| target_relative_xyz | Target-to-candidate displacement in the same normalized support frame as xyz. |
| view_direction_xyz | Unit camera-forward direction expressed in the same proposal-support axes. |
| view_jitter_yaw_deg | Persisted local yaw residual in degrees. |
| view_jitter_pitch_deg | Persisted local pitch residual in degrees. |
| view_jitter_is_bounded | Per-candidate declaration distinguishing bounded box from uncapped spherical support. |
| view_jitter_azimuth_limit_deg | Configured non-negative yaw cap in degrees for a bounded row. |
| view_jitter_elevation_limit_deg | Configured non-negative pitch cap in degrees for a bounded row. |
| oracle_label | Whether direct continuous target-root gain is a valid oracle label. |
| target_root_gain | Direct continuous target-root gain when oracle_label is true. |
1.1.9 CandidatePopulationCoverage
rollouts.candidate_support.contracts.CandidatePopulationCoverage(
expected,
selected_source_rows,
represented_rows,
target_states,
unique_scenes,
)Population counts used by the canonical family preflight decision.
1.1.9.1 Attributes
| Name | Description |
|---|---|
| complete | Return whether evidence contains a non-empty complete population. |
1.1.10 CandidatePreflightBlocker
rollouts.candidate_support.contracts.CandidatePreflightBlocker(
code,
detail,
scene_key=None,
state_key=None,
family=None,
)One deterministic go/no-go blocker, optionally scoped to scene/state/family.
1.1.11 CandidateSupportFailure
rollouts.candidate_support.contracts.CandidateSupportFailure()Machine-readable failure reasons kept distinct by the preflight gate.
1.1.12 EvidenceTransformationKind
rollouts.candidate_support.contracts.EvidenceTransformationKind()Whether evidence came directly from generation or an authenticated reseal.
1.1.13 FlatGainOutcome
rollouts.candidate_support.contracts.FlatGainOutcome(
available,
passed,
denominator,
eligible_state_denominator,
tolerance,
observed_range,
revision,
aggregation,
reason=None,
)State-conditional label variation with exact label/state denominators.
1.2 Functions
| Name | Description |
|---|---|
| aggregate_store_content_sha256 | Bind an ordered set of promoted store identities and content seals. |
| benchmark_from_sampling_result | Reduce one generated full shell without scoring or rendering it. |
| candidate_support_metrics | Compute frame-safe candidate-support facts for one factual state. |
| canonical_generation_revision_hash | Recompute the generation identity from its immutable constituent fields. |
| canonical_json_bytes | Return stable UTF-8 JSON bytes for hashing and export. |
| circular_minimum_covering_span_deg | Return the shortest circular arc covering angles in degrees. |
| reduce_candidate_records | Normalize reducer input into immutable benchmark DTOs. |
| reframe_candidate_benchmark_target_aligned | Rotate an authenticated reference-frame shell into canonical target axes. |
| scientific_writer_config_sha256 | Hash scientific writer policy without checkout/acquisition paths. |
| select_candidate_family_shell | Project one selected cell into the existing 2-D/3-D shell interface. |
| sha256_bytes | Return a SHA-256 hex digest. |
| target_relative_orbit_span_deg | Return the minimum circular azimuth span around the target, in degrees. |
| target_side_count_balance | Return attempted target-family side-count balance for one factual state. |
1.2.1 aggregate_store_content_sha256
rollouts.candidate_support.contracts.aggregate_store_content_sha256(store_seals)Bind an ordered set of promoted store identities and content seals.
1.2.2 benchmark_from_sampling_result
rollouts.candidate_support.contracts.benchmark_from_sampling_result(
result,
*,
scene_key,
state_key,
family_positions,
target_center_world,
provenance=None,
)Reduce one generated full shell without scoring or rendering it.
The sampling result is the authoritative attempted-row table. Its compact valid mask defines final-shell selected counts for the family gate; there is no policy-selected transition in this Phase-A path. Rule reason bitsets and continuous margins are copied only when the generator produced them, so missing diagnostics remain unavailable rather than inferred.
1.2.2.1 Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| result | 'CandidateSamplingResult' | Full-shell candidate-generation result with component lineage. | required |
| scene_key | str | Stable source-scene identity. | required |
| state_key | str | Stable source-sample and target identity. | required |
| family_positions | Mapping[str, str] | Config-owned component-to-position-mode mapping. | required |
| target_center_world | Iterable[float] | Target centre used by the candidate generator. | required |
| provenance | Mapping[str, str] | None | Optional immutable source/config identities. | None |
1.2.2.2 Returns
| Name | Type | Description |
|---|---|---|
| CandidateBenchmark | Presentation-free benchmark record consumable by the canonical family | |
| CandidateBenchmark | preflight reducer, serializer, plots, campaign gate, and Streamlit. |
1.2.2.3 Raises
| Name | Type | Description |
|---|---|---|
| ValueError | If full-shell family lineage or tensor alignment is absent. |
1.2.3 candidate_support_metrics
rollouts.candidate_support.contracts.candidate_support_metrics(
points,
*,
configured_families=None,
projected_target_centers=None,
total_target_centers=None,
)Compute frame-safe candidate-support facts for one factual state.
1.2.3.1 Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| points | Iterable[CandidatePoint] | Attempted rows expressed in one target-aligned support frame. | required |
| configured_families | Collection[str] | None | Complete configured family identifiers, including families with no emitted or valid row. | None |
| projected_target_centers | int | None | Evaluated rows whose target centre projects inside the calibrated image domain. | None |
| total_target_centers | int | None | Rows on which target-centre projection was evaluated. | None |
1.2.3.2 Returns
| Name | Type | Description |
|---|---|---|
| dict[str, float | int | None] | State-level support counts and fractions. None denotes unavailable |
|
| dict[str, float | int | None] | evidence; projection is calibrated framing rather than visibility. |
1.2.3.3 Notes
Geometry from unrelated root and decision frames is intentionally not combined. Normal callers obtain coordinates from aria_nbv.rollouts.inspection.proposal_support_geometry.
1.2.4 canonical_generation_revision_hash
rollouts.candidate_support.contracts.canonical_generation_revision_hash(payload)Recompute the generation identity from its immutable constituent fields.
1.2.5 canonical_json_bytes
rollouts.candidate_support.contracts.canonical_json_bytes(value)Return stable UTF-8 JSON bytes for hashing and export.
1.2.6 circular_minimum_covering_span_deg
rollouts.candidate_support.contracts.circular_minimum_covering_span_deg(
angles_deg,
)Return the shortest circular arc covering angles in degrees.
The branch cut is handled on the circle, so -179 and 179 span two degrees rather than 358 degrees.
1.2.7 reduce_candidate_records
rollouts.candidate_support.contracts.reduce_candidate_records(records)Normalize reducer input into immutable benchmark DTOs.
1.2.8 reframe_candidate_benchmark_target_aligned
rollouts.candidate_support.contracts.reframe_candidate_benchmark_target_aligned(
record,
*,
reference_rotation_world_from_ref,
)Rotate an authenticated reference-frame shell into canonical target axes.
This metadata-only correction uses the target displacement already bound into every point and the source sample’s factual reference rotation. It never regenerates candidates, changes validity, or changes family counts.
1.2.9 scientific_writer_config_sha256
rollouts.candidate_support.contracts.scientific_writer_config_sha256(
payload,
*,
source_store_manifest_hash,
)Hash scientific writer policy without checkout/acquisition paths.
Source-store content is bound separately by its verified native manifest identity. Repository roots, cache directories, the local source-manifest path, and output-store locations are acquisition or execution concerns and therefore cannot distinguish otherwise identical experiments.
1.2.10 select_candidate_family_shell
rollouts.candidate_support.contracts.select_candidate_family_shell(
records,
selection,
)Project one selected cell into the existing 2-D/3-D shell interface.
1.2.11 sha256_bytes
rollouts.candidate_support.contracts.sha256_bytes(value)Return a SHA-256 hex digest.
1.2.12 target_relative_orbit_span_deg
rollouts.candidate_support.contracts.target_relative_orbit_span_deg(
points,
*,
target_conditioned_positions=('target_bearing_local', 'target_orbit'),
)Return the minimum circular azimuth span around the target, in degrees.
1.2.13 target_side_count_balance
rollouts.candidate_support.contracts.target_side_count_balance(
points,
*,
target_conditioned_positions=('target_bearing_local', 'target_orbit'),
)Return attempted target-family side-count balance for one factual state.
The lateral coordinate is read from target_relative_xyz. Rows without a common-frame target displacement are excluded rather than reconstructed from incompatible audit coordinates.