1 oracle.pipelines.recipe_queue
oracle.pipelines.recipe_queue
Run a resumable, quota-bounded stream of immutable single-rollout plans.
The queue is a scheduler over the canonical recipe-experiment runner. It owns the source population, deterministic seed progression, disk admission, and append-only receipts; each rollout remains an ordinary frozen recipe plan. Pausing takes effect between rollouts, and a paused queue can be resumed without changing its experiment identity or rewriting completed evidence. Persisting a pause request does not acknowledge that the worker is quiescent; the control result distinguishes those states.
1.1 Classes
| Name | Description |
|---|---|
| QueueControlResult | Result of persisting a queue control request. |
| RecipeQueueConfig | Frozen inputs and resource limits for a resumable recipe stream. |
| RecipeQueueSnapshot | One source-bound queue and ledger captured without mixed-read drift. |
| RecipeQueueStoreIdentity | Canonical identity of one validated successful queue store. |
1.1.1 QueueControlResult
oracle.pipelines.recipe_queue.QueueControlResult(
action,
request_persisted,
pause_acknowledged,
lifecycle_status,
)Result of persisting a queue control request.
A recorded pause request becomes acknowledged only after the scheduler has reached a rollout boundary and persisted lifecycle status paused.
1.1.1.1 Attributes
| Name | Description |
|---|---|
| action | Requested control transition. |
| request_persisted | Whether this call appended a new request to the control ledger. |
| pause_acknowledged | Whether an already-requested pause is confirmed by worker state. |
| lifecycle_status | Scheduler state observed before this control call. |
1.1.2 RecipeQueueConfig
oracle.pipelines.recipe_queue.RecipeQueueConfig()Frozen inputs and resource limits for a resumable recipe stream.
The roster is derived from a reviewed Oracle target-roster receipt. Only eligible development rows are streamed; reserved confirmation and excluded rows are never admitted. Rounds repeat the same scenes with new sampler/proposal seeds, keeping scene count separate from seed replication.
1.1.2.1 Attributes
| Name | Description |
|---|---|
| writer_config_path | Canonical one-recipe G60 writer TOML used as the stream profile. |
| roster_receipt_path | Reviewed full-roster receipt that separates eligible, reserved, and excluded rows. |
| output_root | New exclusive root for queue identity, control events, and rollout evidence. |
| seed_start | Seed assigned to the first complete scene pass; each pass increments by one. |
| max_output_gib | Hard retained-output quota for this queue; reaching it stops without deleting data. |
| free_disk_floor_gib | Independent free-space reserve protecting the shared system filesystem. |
| estimated_unit_bytes | Conservative whole-rollout estimate used before starting each GPU worker. |
| unit_timeout_seconds | Per-rollout watchdog; it is not a queue deadline. |
| fleet_hosts | Frozen ordered host identities; round-robin scene ownership never changes when an endpoint is offline. |
| owner_host | Host allowed to launch this queue’s disjoint population; absent retains the legacy single-host contract. |
| availability_index_roots | Explicit ancestor discovery scopes notified after sealed rollout publication. |
1.1.3 RecipeQueueSnapshot
oracle.pipelines.recipe_queue.RecipeQueueSnapshot(
queue,
ledger,
queue_sha256,
ledger_sha256,
successful_stores,
lifecycle_status,
completed_units,
terminal,
lifecycle_status_reason,
population_complete,
population_complete_reason,
)One source-bound queue and ledger captured without mixed-read drift.
1.1.3.1 Attributes
| Name | Description |
|---|---|
| queue | Validated frozen queue payload. |
| ledger | Validated terminal attempts in their exact scheduling order. |
| queue_sha256 | SHA-256 of the queue bytes captured for this snapshot. |
| ledger_sha256 | SHA-256 of the ledger bytes captured for this snapshot. |
| successful_stores | Validated immutable identities for successful stores in ledger order. |
| lifecycle_status | Validated queue lifecycle state captured with the ledger. |
| completed_units | Lifecycle count proven equal to the validated terminal ledger length. |
| terminal | Whether lifecycle state or a terminal failure ledger proves a scheduler stop. |
| lifecycle_status_reason | Why lifecycle status is unavailable despite a validated ledger prefix. |
| population_complete | Whether every unit in a finite frozen population is accounted for. |
| population_complete_reason | Machine-readable reason whole-population accounting is unavailable. |
1.1.4 RecipeQueueStoreIdentity
oracle.pipelines.recipe_queue.RecipeQueueStoreIdentity(
unit_id,
path,
shard_id,
manifest_sha256,
content_sha256,
owner_sha256,
)Canonical identity of one validated successful queue store.
1.1.4.1 Attributes
| Name | Description |
|---|---|
| unit_id | Deterministic queue unit that owns the store. |
| path | Canonical promoted shard path. |
| shard_id | Frozen child-plan shard identity. |
| manifest_sha256 | Digest of the rollout store manifest. |
| content_sha256 | Digest of the canonical logical Zarr content. |
| owner_sha256 | Digest of the promotion owner sidecar named by the success marker. |
1.2 Functions
| Name | Description |
|---|---|
| freeze_queue | Freeze queue inputs before generation; repeated calls must be identical. |
| main | Freeze, run, pause, or resume one disk-bounded queue. |
| read_validated_queue_snapshot | Capture one immutable queue ledger prefix for downstream readout. |
| request_control | Append a control request and report pause acknowledgement separately. |
| resume_queue | Record a resume request and immediately continue scheduling work. |
| run_queue | Run an immutable queue prefix until pause, resource stop, or tranche bound. |
1.2.1 freeze_queue
oracle.pipelines.recipe_queue.freeze_queue(config)Freeze queue inputs before generation; repeated calls must be identical.
1.2.2 main
oracle.pipelines.recipe_queue.main()Freeze, run, pause, or resume one disk-bounded queue.
1.2.3 read_validated_queue_snapshot
oracle.pipelines.recipe_queue.read_validated_queue_snapshot(queue_path)Capture one immutable queue ledger prefix for downstream readout.
Queue v1 has no finite target count. Even a terminal scheduler state is therefore not evidence that a scientific population is complete.
1.2.4 request_control
oracle.pipelines.recipe_queue.request_control(
queue_path,
action,
*,
origin='operator',
)Append a control request and report pause acknowledgement separately.
1.2.5 resume_queue
oracle.pipelines.recipe_queue.resume_queue(queue_path)Record a resume request and immediately continue scheduling work.
1.2.6 run_queue
oracle.pipelines.recipe_queue.run_queue(
queue_path,
*,
stop_after_units=None,
render_progress=False,
continuous=False,
host=None,
)Run an immutable queue prefix until pause, resource stop, or tranche bound.
stop_after_units is an absolute completed-attempt count, including excluded/failed attempts. It bounds this invocation without changing the frozen queue or appending operator controls. A later larger bound resumes the same deterministic assignments. Continuous supervisors use bounded tranches with continuous=True; progress then reports rates and backlog without presenting an unbounded population as a percentage.