1 oracle.pipelines.recipe_experiment
oracle.pipelines.recipe_experiment
Run a frozen diagnostic recipe matrix through canonical rollout shards.
This owner schedules work and records outcomes; it does not select targets, score poses, or grant broad-corpus admission. Each arm supplies an ordinary writer TOML. The immutable plan binds one source row per shard across arms, source revision, configuration bytes and an absolute acquisition deadline.
1.1 Classes
| Name | Description |
|---|---|
| RecipeContrast | Predeclared paired profiles and whether candidate budget is the treatment. |
| RecipeExperimentArm | One immutable writer configuration in a paired allocation block. |
| RecipeExperimentConfig | Resource bounds and arm order for a diagnostic, never a corpus gate. |
1.1.1 RecipeContrast
oracle.pipelines.recipe_experiment.RecipeContrast()Predeclared paired profiles and whether candidate budget is the treatment.
1.1.2 RecipeExperimentArm
oracle.pipelines.recipe_experiment.RecipeExperimentArm()One immutable writer configuration in a paired allocation block.
1.1.2.1 Attributes
| Name | Description |
|---|---|
| name | Unique filesystem-safe arm identity, including replica/direction. |
| profile | Scientific profile shared across replicas; empty uses the arm name. |
| replica | Matched proposal/selection replica identity, independent of scene count. |
| writer_config_path | Existing canonical writer TOML; frozen by its byte hash. |
1.1.3 RecipeExperimentConfig
oracle.pipelines.recipe_experiment.RecipeExperimentConfig()Resource bounds and arm order for a diagnostic, never a corpus gate.
1.1.3.1 Attributes
| Name | Description |
|---|---|
| arms | Arms evaluated on identical ordered source rows. |
| contrasts | Only these scientific comparisons may appear in the post-hoc report. |
| output_root | Exclusive experiment directory containing plan, receipts and shards. |
| deadline | Optional ISO timestamp with explicit UTC offset; absent for quota-only queues. |
| max_blocks | Maximum number of distinct source rows, each compared across all arms. |
| estimated_block_seconds | Conservative measured block cost including finalization and contingency. |
| estimated_block_bytes | Conservative retained bytes per complete block, including contingency. |
| free_disk_floor_gib | Space kept free on the output filesystem. |
| max_output_gib | Per-worker admission cap on retained data, including quarantine evidence. |
| unit_timeout_seconds | Per-worker watchdog; the absolute deadline can shorten it. |
| allow_partial_final_block | Allow a deadline-censored final block; incomplete cells remain unreached. |
| engineering_pilot | True until the separately recorded measurement and integration gates pass. |
| rendering_contrast | Opt in to matched rendering; only candidate_render_crop may differ scientifically. |
| worker_lifecycle_timing | Record guarded parent launch-to-exit durations for ordinary source contrasts. |
| parameter_contrast_receipt_path | Typed R1 preparation receipt; seals baseline, root grids and permitted deltas. |
| target_roster_receipt_path | Optional admitted Oracle root/target parity receipt required before freezing. |
1.2 Functions
| Name | Description |
|---|---|
| admission_reason | Return the first resource gate preventing another complete block. |
| build_rendering_contrast_receipt | Seal complete writers and verify render-only differences within replicas. |
| execute_unit | Materialize exactly one frozen shard and write its terminal receipt. |
| freeze_experiment | Bind clean source and matched source-row shards before any generation. |
| main | Expose explicit freeze, run and one-unit worker operations. |
| rendering_measurement_contract | Remove only the crop field; retain candidate caps and all scorer semantics. |
| run_experiment | Run matched blocks with exclusive ownership and a watchdog. |
| validate_rendering_contrast_receipt | Recompute original arm seals, projection and exact delta without local paths. |
| validate_single_chain_policy | Reject branch controls that can retain multiple diagnostic trajectories. |
1.2.1 admission_reason
oracle.pipelines.recipe_experiment.admission_reason(
config,
*,
now,
free_bytes,
retained_bytes,
)Return the first resource gate preventing another complete block.
The estimate already includes pilot-derived contingency. These gates do not imply that any candidate will be valid or any scientific effect exists.
1.2.2 build_rendering_contrast_receipt
oracle.pipelines.recipe_experiment.build_rendering_contrast_receipt(
writers,
config,
)Seal complete writers and verify render-only differences within replicas.
Only renderer_validation_output and store.store_dir are operational paths. Their exact original values remain sealed. All source, generation, selection, support and measurement fields must agree within each paired replica.
1.2.3 execute_unit
oracle.pipelines.recipe_experiment.execute_unit(plan_path, unit_id)Materialize exactly one frozen shard and write its terminal receipt.
1.2.4 freeze_experiment
oracle.pipelines.recipe_experiment.freeze_experiment(config)Bind clean source and matched source-row shards before any generation.
1.2.5 main
oracle.pipelines.recipe_experiment.main()Expose explicit freeze, run and one-unit worker operations.
1.2.6 rendering_measurement_contract
oracle.pipelines.recipe_experiment.rendering_measurement_contract(writer)Remove only the crop field; retain candidate caps and all scorer semantics.
This projection permits a comparison, but proves no numerical equivalence.
1.2.7 run_experiment
oracle.pipelines.recipe_experiment.run_experiment(
plan_path,
*,
stop_after_blocks=None,
)Run matched blocks with exclusive ownership and a watchdog.
Terminal failures are retained rather than retried selectively. An absent receipt after interruption may be retried: staging is quarantined and a previously promoted shard is validated by the canonical leaf before reuse. An opt-in final block may be right-censored at the absolute deadline: its completed cells remain terminal while the interrupted cell has no outcome. stop_after_blocks pauses before an absolute zero-based block index reaches that positive bound. The complete frozen plan remains unchanged; a later call without the bound resumes remaining cells without rerunning outcomes.
1.2.8 validate_rendering_contrast_receipt
oracle.pipelines.recipe_experiment.validate_rendering_contrast_receipt(plan)Recompute original arm seals, projection and exact delta without local paths.
Historical ordinary plans retain their original readback contract. A renderer receipt cannot be omitted from an opt-in plan or inserted into an ordinary one.
1.2.9 validate_single_chain_policy
oracle.pipelines.recipe_experiment.validate_single_chain_policy(policy)Reject branch controls that can retain multiple diagnostic trajectories.
Deterministic schedules repeat their final value, while stochastic controls can select any branch count with positive probability. The diagnostic report assigns one task identity per arm and source row, so every reachable branch count must remain one throughout the acquisition horizon.