1 oracle.pipelines.campaign

oracle.pipelines.campaign

Typed planning and bounded execution for the reviewed CUDA campaign.

The module is deliberately an orchestration owner: shard validation and skip decisions remain owned by run_rollout_shard.

1.1 Classes

Name	Description
CampaignProcessRunner	Injectable subprocess boundary with process-group termination.
CampaignProfileConfig	One immutable, reviewed candidate-family schedule.
CampaignTimeoutError	Bounded child timeout carrying reproducible process evidence.
CudaRolloutCampaign	Plan and execute one campaign serially through the shard leaf.
CudaRolloutCampaignConfig	Config-as-factory for the fixed CUDA campaign contract.

1.1.1 CampaignProcessRunner

oracle.pipelines.campaign.CampaignProcessRunner()

Injectable subprocess boundary with process-group termination.

1.1.1.1 Methods

Name	Description
run	Run one opaque child while draining pipes and enforcing its watchdog.
run_stage	Run a bounded setup/render stage using the same process-group policy.

1.1.1.1.1 run

oracle.pipelines.campaign.CampaignProcessRunner.run(
    argv,
    *,
    timeout,
    stdout=None,
    stderr=None,
    on_started=None,
    clock=time.monotonic,
)

Run one opaque child while draining pipes and enforcing its watchdog.

1.1.1.1.2 run_stage

oracle.pipelines.campaign.CampaignProcessRunner.run_stage(
    argv,
    *,
    timeout=120,
    stdout=None,
    stderr=None,
)

Run a bounded setup/render stage using the same process-group policy.

1.1.2 CampaignProfileConfig

oracle.pipelines.campaign.CampaignProfileConfig()

One immutable, reviewed candidate-family schedule.

1.1.3 CampaignTimeoutError

oracle.pipelines.campaign.CampaignTimeoutError(
    message,
    *,
    pid,
    process_group,
    elapsed_seconds,
    stderr_tail='',
    disposition='term-grace-kill',
    tmux_session=None,
)

Bounded child timeout carrying reproducible process evidence.

1.1.4 CudaRolloutCampaign

oracle.pipelines.campaign.CudaRolloutCampaign(
    config,
    *,
    clock=time.monotonic,
    utc_now=lambda: datetime.now(UTC),
    process_runner=None,
)

Plan and execute one campaign serially through the shard leaf.

1.1.4.1 Methods

Name	Description
candidate_family_preflight	Evaluate campaign candidate support through the rollout-domain gate.
candidate_family_phase_a	Generate the unchanged single-root Phase-A proposal-support audit.
admit_broad_generation	Evaluate family support, then fail closed pending the WP18 reader.
require_execution_admission	Reject broad execution before claims, status, events, or outputs.
require_worker_admission	Permit only the exact canonical smoke unit before WP18 in broad mode.
audit_source_manifest	Enumerate every observed target and attach privileged admission evidence.
write_admission_audit	Persist the complete immutable target-admission audit before plan publication.
run_preflight_stage	Run the named 120-second setup stage through the process-group watchdog.
smoke	Run the canonical per-unit smoke guard, not a smoke population.
parse_worker_json	Parse worker JSON and preserve skipped as a distinct outcome.
parse_worker_result	Parse and strictly bind a subprocess worker result to its unit.
run_work_unit	Admit and delegate one immutable plan unit before any leaf side effect.
adapt_work_unit	Bind one immutable unit to a writer and shard entry.
profile_components	Return the exact reviewed component order/counts for a profile.
shard_entry_for_unit	Create the single-row manifest envelope used by the worker seam.
worker_argv	Build the only subprocess argv used for an opaque work unit.
run	Run a claimed campaign and always release its claim.
quarantine_staging	Atomically quarantine a timed-out unit’s known staging directory.
claim_disposition	Classify a claim without mutating its evidence.
claim_is_stale	Diagnose a vanished local owner without deleting its evidence.
acknowledge_stale_claim	Archive exactly the acknowledged stale claim before reacquisition.
load_plan	Load and hash-validate an immutable canonical plan.
progress_summary	Presentation-free status/events read model for CLI and UI adapters.

1.1.4.1.1 candidate_family_preflight

oracle.pipelines.campaign.CudaRolloutCampaign.candidate_family_preflight(reader)

Evaluate campaign candidate support through the rollout-domain gate.

1.1.4.1.2 candidate_family_phase_a

oracle.pipelines.campaign.CudaRolloutCampaign.candidate_family_phase_a(
    writer_config,
    source_manifest,
    *,
    source_manifest_sha256,
)

Generate the unchanged single-root Phase-A proposal-support audit.

This is a no-render, no-reward-label Phase-A proposal-support audit with privileged GT target instruction and mesh validity. The adapter applies the reviewed source manifest, uses the writer’s existing target task sampler and candidate mixture, and stops before any target scorer, renderer, replay policy, or reward label is constructed. The resulting full shells are reduced through the same rollout-domain preflight used by stores, CLI serialization, plots, and Streamlit.

1.1.4.1.2.1 Parameters

Name	Type	Description	Default
writer_config	Any	Canonical RolloutDatasetWriterConfig for the run.	required
source_manifest	Any	Reviewed ordered 100-scene source manifest.	required
source_manifest_sha256	str	SHA-256 of the exact manifest file bytes.	required

1.1.4.1.2.2 Returns

Name	Type	Description
	CandidateFamilyPhaseAEvidence	Hash-ready benchmark records and the canonical go/no-go decision.

1.1.4.1.3 admit_broad_generation

oracle.pipelines.campaign.CudaRolloutCampaign.admit_broad_generation(reader)

Evaluate family support, then fail closed pending the WP18 reader.

Phase-A generation may run to produce the candidate-only evidence. This method owns admission of the broader rollout campaign: a passing family result is necessary but deliberately insufficient until the hash-bound final #120 artifact is read by a canonical WP18 owner. No caller-supplied mapping is accepted as an admission receipt.

1.1.4.1.4 require_execution_admission

oracle.pipelines.campaign.CudaRolloutCampaign.require_execution_admission()

Reject broad execution before claims, status, events, or outputs.

1.1.4.1.5 require_worker_admission

oracle.pipelines.campaign.CudaRolloutCampaign.require_worker_admission(
    plan,
    unit,
    *,
    purpose,
)

Permit only the exact canonical smoke unit before WP18 in broad mode.

1.1.4.1.6 audit_source_manifest

oracle.pipelines.campaign.CudaRolloutCampaign.audit_source_manifest(
    writer_config,
    source_manifest,
)

Enumerate every observed target and attach privileged admission evidence.

1.1.4.1.7 write_admission_audit

oracle.pipelines.campaign.CudaRolloutCampaign.write_admission_audit(
    rows,
    *,
    source_manifest_hash,
    expected_hash,
    path=None,
)

Persist the complete immutable target-admission audit before plan publication.

1.1.4.1.8 run_preflight_stage

oracle.pipelines.campaign.CudaRolloutCampaign.run_preflight_stage(
    argv,
    *,
    plan=None,
    stage_name='preflight',
)

Run the named 120-second setup stage through the process-group watchdog.

1.1.4.1.9 smoke

oracle.pipelines.campaign.CudaRolloutCampaign.smoke(
    plan,
    *,
    config_path=None,
    plan_path=None,
)

Run the canonical per-unit smoke guard, not a smoke population.

1.1.4.1.10 parse_worker_json

oracle.pipelines.campaign.CudaRolloutCampaign.parse_worker_json(payload)

Parse worker JSON and preserve skipped as a distinct outcome.

1.1.4.1.11 parse_worker_result

oracle.pipelines.campaign.CudaRolloutCampaign.parse_worker_result(
    payload,
    plan,
    unit,
)

Parse and strictly bind a subprocess worker result to its unit.

1.1.4.1.12 run_work_unit

oracle.pipelines.campaign.CudaRolloutCampaign.run_work_unit(
    plan,
    unit,
    *,
    purpose,
    writer_config,
    shard_entry,
    output_tmp,
    output_final,
    invocation=None,
    shard_runner=None,
)

Admit and delegate one immutable plan unit before any leaf side effect.

1.1.4.1.13 adapt_work_unit

oracle.pipelines.campaign.CudaRolloutCampaign.adapt_work_unit(
    unit,
    *,
    writer_config,
    shard_entry,
    plan_hash='',
    profile_hash='',
)

Bind one immutable unit to a writer and shard entry.

The writer remains the owner of target validation; this adapter only narrows the source selection to one sample and carries campaign identity into the existing shard manifest contract.

1.1.4.1.14 profile_components

oracle.pipelines.campaign.CudaRolloutCampaign.profile_components(profile_name)

Return the exact reviewed component order/counts for a profile.

1.1.4.1.15 shard_entry_for_unit

oracle.pipelines.campaign.CudaRolloutCampaign.shard_entry_for_unit(plan, unit)

Create the single-row manifest envelope used by the worker seam.

1.1.4.1.16 worker_argv

oracle.pipelines.campaign.CudaRolloutCampaign.worker_argv(
    plan_path,
    unit,
    *,
    config_path=None,
    writer_config_path=None,
    purpose=CampaignWorkerPurpose.CAMPAIGN,
)

Build the only subprocess argv used for an opaque work unit.

1.1.4.1.17 run

oracle.pipelines.campaign.CudaRolloutCampaign.run(
    plan,
    *,
    plan_path=None,
    config_path=None,
    cuda_probe=None,
    nested_configs=(),
    current_writer_config_hash='',
    max_new_units=None,
    time_budget_seconds=None,
    free_disk_floor_gb=None,
)

Run a claimed campaign and always release its claim.

1.1.4.1.18 quarantine_staging

oracle.pipelines.campaign.CudaRolloutCampaign.quarantine_staging(unit)

Atomically quarantine a timed-out unit’s known staging directory.

1.1.4.1.19 claim_disposition

oracle.pipelines.campaign.CudaRolloutCampaign.claim_disposition(plan, path)

Classify a claim without mutating its evidence.

1.1.4.1.20 claim_is_stale

oracle.pipelines.campaign.CudaRolloutCampaign.claim_is_stale(
    path,
    *,
    tmux_probe=None,
    pid_probe=None,
    process_group_probe=None,
    owner_probe=None,
)

Diagnose a vanished local owner without deleting its evidence.

1.1.4.1.21 acknowledge_stale_claim

oracle.pipelines.campaign.CudaRolloutCampaign.acknowledge_stale_claim(
    path,
    claim_hash,
)

Archive exactly the acknowledged stale claim before reacquisition.

1.1.4.1.22 load_plan

oracle.pipelines.campaign.CudaRolloutCampaign.load_plan(path)

Load and hash-validate an immutable canonical plan.

1.1.4.1.23 progress_summary

oracle.pipelines.campaign.CudaRolloutCampaign.progress_summary(plan=None)

Presentation-free status/events read model for CLI and UI adapters.

1.1.5 CudaRolloutCampaignConfig

oracle.pipelines.campaign.CudaRolloutCampaignConfig()

Config-as-factory for the fixed CUDA campaign contract.

1.2 Functions

Name	Description
bounded_scene_stratified_plan	Return a deterministic train/validation/test evidence slice.

1.2.1 bounded_scene_stratified_plan

oracle.pipelines.campaign.bounded_scene_stratified_plan(
    plan,
    *,
    scenes_per_split=1,
    required_splits=('train', 'validation', 'test'),
)

Return a deterministic train/validation/test evidence slice.

The full :class:CampaignPlan remains the population owner: scene-level split assignment, work-unit identity, source lineage, generation revision, and configuration hashes are copied without reinterpretation. This helper selects complete existing work units only; it does not invent a second partition rule or mutate the parent plan. Selection is keyed by the parent seed and stable work-unit identities so input ordering cannot silently pick an easier target.

1.2.1.1 Parameters

Name	Type	Description	Default
plan	CampaignPlan	Fully validated broad campaign plan containing persisted train, validation, and test scene assignments.	required
scenes_per_split	int	Positive number of distinct scenes retained from each requested campaign split. One work unit is selected per scene.	1
required_splits	tuple[str, …]	Ordered, nonempty subset of train, validation, and test. The default constructs a complete three-stage smoke population. A stage-only plan supports deterministic replacement acquisition after input-side feasibility rejection without regenerating already admitted stages or inspecting Q labels.	('train', 'validation', 'test')

1.2.1.2 Returns

Name	Type	Description
	CampaignPlan	A new hash-valid plan ordered by train, validation, and test split. Its
	CampaignPlan	smaller work-unit list is the complete bounded execution population;
	CampaignPlan	all parent provenance and admission summaries remain bound.

1.2.1.3 Raises

Name	Type	Description
	ValueError	If the bound is non-positive, the requested splits are empty, duplicated, or unknown, a work unit lacks scene lineage, or a requested split has insufficient distinct scenes.

1.2.1.4 Notes

This is an infrastructure/smoke surface, not a statistically powered evaluation design. Scientific comparisons still require a separately justified population size and scene-level uncertainty analysis.