1 oracle.pipelines.target_roster_preflight
oracle.pipelines.target_roster_preflight
Freeze a paired Oracle target roster before recipe rendering.
The recipe experiment already binds source rows across arms. This module adds the missing no-render check: both writer configurations must resolve every admitted row to the same physical root and the same single Oracle target. It also owns the predeclared confirmation reserve and balanced standoff roster. Use the non-admitting proposal phase with full-population writers to create typed subset configs, then run a fresh preflight against those exact files.
1.1 Classes
| Name | Description |
|---|---|
| TargetRosterArmConfig | One writer configuration participating in the parity preflight. |
| TargetRosterPreflightBlockedError | Raised after a blocked receipt has been durably written. |
| TargetRosterPreflightConfig | Inputs for a two-arm, scene-disjoint target-roster preflight. |
| TargetRosterSourceIneligibleError | The shared Oracle task population cannot provide one valid target. |
1.1.1 TargetRosterArmConfig
oracle.pipelines.target_roster_preflight.TargetRosterArmConfig()One writer configuration participating in the parity preflight.
1.1.1.1 Attributes
| Name | Description |
|---|---|
| name | Stable arm label used only in the receipt. |
| writer_config_path | Existing canonical rollout-writer TOML evaluated without rendering. |
1.1.2 TargetRosterPreflightBlockedError
oracle.pipelines.target_roster_preflight.TargetRosterPreflightBlockedError(
receipt_path,
blockers,
)Raised after a blocked receipt has been durably written.
1.1.3 TargetRosterPreflightConfig
oracle.pipelines.target_roster_preflight.TargetRosterPreflightConfig()Inputs for a two-arm, scene-disjoint target-roster preflight.
1.1.3.1 Attributes
| Name | Description |
|---|---|
| arms | Exactly two paired writer configurations. |
| output_path | New JSON receipt or proposal path; existing evidence is never replaced. |
| excluded_scene_ids | Scenes already used by the prior policy pilot or another frozen holdout. |
| confirmation_reserve_count | Number of hash-ranked scenes held untouched for later confirmation. |
| confirmation_scene_ids | Optional exact historical confirmation membership; count must match the reserve and source rows retain their physical split. |
| selected_per_stratum | Selected scenes from each lower/upper root-to-target standoff half. |
| population_mode | Explicit same-arm commissioning mode for one source row; it supplies no balanced-scene comparison evidence. |
| confirmation_salt | Predeclared salt for the untouched confirmation reserve. |
| selection_salt | Predeclared salt for selection within each standoff half. |
1.1.4 TargetRosterSourceIneligibleError
oracle.pipelines.target_roster_preflight.TargetRosterSourceIneligibleError()The shared Oracle task population cannot provide one valid target.
1.2 Functions
| Name | Description |
|---|---|
| assert_target_roster_matches_experiment | Require an admitted receipt to bind source bytes, writers and plan rows. |
| freeze_target_roster | Admit exact writer files after a fresh physical-root and target audit. |
| main | Run proposal or admission from one typed target-roster TOML config. |
| propose_target_roster | Select a balanced roster from full-population writers and create subset TOMLs. |
| validate_target_roster_receipt | Validate receipt integrity and, for admission, the complete roster. |
| validate_target_roster_source_binding | Validate an admitted receipt and the source bytes and revision it names. |
1.2.1 assert_target_roster_matches_experiment
oracle.pipelines.target_roster_preflight.assert_target_roster_matches_experiment(
path,
*,
writer_config_paths,
planned_entries_by_arm,
generation_revision,
)Require an admitted receipt to bind source bytes, writers and plan rows.
1.2.2 freeze_target_roster
oracle.pipelines.target_roster_preflight.freeze_target_roster(config)Admit exact writer files after a fresh physical-root and target audit.
Balanced mode freezes a comparison roster; singleton engineering mode provides only same-arm commissioning evidence. Blocked receipts remain diagnostic evidence and cannot authorize generation. Existing different output is never replaced, and no rendering or source mutation is performed.
1.2.3 main
oracle.pipelines.target_roster_preflight.main()Run proposal or admission from one typed target-roster TOML config.
1.2.4 propose_target_roster
oracle.pipelines.target_roster_preflight.propose_target_roster(
config,
*,
writer_config_paths,
)Select a balanced roster from full-population writers and create subset TOMLs.
This first phase applies the same source, reserve, target and root-parity checks as admission. Its distinct proposal contract never admits writers. The full source manifest stays authoritative; only ordered sample_keys, max_samples and the rollout store’s ordered split hash change. Typed writer validation and serialization own these new configurations. Run freeze_target_roster against these exact files with a new receipt path for the second phase; a proposal or blocked receipt cannot substitute for that fresh audit.
All output paths must be new. No existing receipt is read or rewritten. Failed scientific checks produce no subset writer configurations.
1.2.5 validate_target_roster_receipt
oracle.pipelines.target_roster_preflight.validate_target_roster_receipt(
path,
*,
require_admitted=True,
)Validate receipt integrity and, for admission, the complete roster.
Blocked receipts may contain a partial selection because they are durable diagnostic evidence. Their selected rows and identities remain subject to structural validation; only admitted receipts must be complete and balanced. Balanced evidence requires the current v2 contract; the separately versioned singleton engineering contract admits only one same-arm commissioning row. Proposals never authorize comparison admission. Validation checks arm parity and selection-to-audit equality independently of the outer seal. Raw root poses must reproduce their declared hashes; standoff is recomputed from the target center and camera translation before admitting stratum evidence.
1.2.6 validate_target_roster_source_binding
oracle.pipelines.target_roster_preflight.validate_target_roster_source_binding(
path,
*,
generation_revision,
)Validate an admitted receipt and the source bytes and revision it names.
This read-only boundary is shared by experiment and queue schedulers. It prevents a still-valid receipt from authorizing a replaced source manifest or generation checkout.