SCE-002: publish the admitted experiment trial-plan contract

[Brad-Edwards]

Requirements

• SCE-002 — Scenario Composition, Parameterization, and Randomization
• SCE-006 — Isolated Batch Trial Scheduling

Outcome

Publish the schedule-independent admitted trial-plan contract selected by #652. It is the immutable handoff between experiment design/admission and orchestration.

Scope

Each trial entry must represent, as selected by the design:

• stable trial, condition, and replicate identity;
• scenario-family reference and digest;
• explicit variation selections and origins;
• an explicit SDL instantiation request or equivalent governed binding artifact;
• stochastic-control suite and semantic stream references;
• execution controls and apparatus/isolation constraints;
• reset, timeout, cancellation, cleanup, and retry obligations;
• input, compiler, policy, and contract versions;
• integrity binding for the entry and complete plan.

Define plan lifecycle, validation, canonicalization, compatibility, fixtures, and publication.

Acceptance criteria

• The plan is complete before scheduling and contains no unresolved sampling operation.
• Reordering entries or changing worker count cannot change entry identity or contents.
• A scheduler can consume one entry without interpreting the experiment-authoring document.
• Trial identity is distinct from execution-attempt identity.
• Secret values are absent; secret references remain governed.
• Invalid, incomplete, duplicate, contradictory, and tampered plans fail closed.
• The contract integrates with existing task/run/study/apparatus references without duplicating their meaning.

Non-goals

• Compiling the plan.
• Executing or scheduling entries.
• Recording observed run results.

[Brad-Edwards]

🛠️ Picked up by /implement - driver claude-code, branch 788-trial-plan-contract, 2026-07-28T17:54:57.418Z.

[Brad-Edwards]

gc workflow phase recorded: preflight (issue #788). Posted by the MCP server to enforce ordering between workflow steps (issue #794 MVP-2). Do not edit or delete — used by downstream tools to gate phase prerequisites.

[Brad-Edwards]

gc workflow phase recorded: preflight (issue #788). Posted by the MCP server to enforce ordering between workflow steps (issue #794 MVP-2). Do not edit or delete — used by downstream tools to gate phase prerequisites.

[Brad-Edwards]

gc workflow phase recorded: plan (issue #788). Posted by the MCP server to enforce ordering between workflow steps (issue #794 MVP-2). Do not edit or delete — used by downstream tools to gate phase prerequisites.

Implementation plan — publish admitted-trial-plan-v1

Publish the immutable, schedule-independent admitted trial-plan contract: the sealed handoff from experiment design/admission to orchestration selected by #652, governed by ADR-084, and specified by invariants SVR-018…SVR-030 in specs/formal/scenario-variation-trial-realization/README.md. Reconciled with the Codex architecture preflight note docs/decisions/issue-788-sce-002-admitted-trial-plan-contract-preflight.md (binding).

Requirement coverage

• SCE-002 (composition/parameterization/randomization): each entry commits the resolved variation selections + policy origin, non-secret typed bindings, and stochastic draw provenance — no unresolved sampling.
• SCE-006 (isolated batch trial scheduling): the plan is the schedule-independent artifact a scheduler consumes per entry (preallocated run_id, canonical coordinate identity, plan-scope isolation proof, apparatus/manifest/envelope pins, timeout + cleanup/retry by reference) without interpreting authoring/SDL or owning a second lifecycle.

Design (one closed *-v1 contract; reuse owners, never duplicate meaning)

New implementations/python/packages/raes_contracts/contracts/admitted_trial_plan.py.

AdmittedTrialPlanModel(ContractModel, extra="forbid"):

• schema_version const "admitted-trial-plan/v1" (new versions.py constant)
• plan_id
• profiles — exact versioned profile set (coordinate / entry-identity / run-identity / canonicalization / integrity / compiler / selection / random-stream / execution-control / cleanup / isolation): the ADR-084 extensibility seam
• input_refs — pinned typed refs + digests reusing experiment_references (authoring-input, ExperimentTaskReferenceModel, scenario-snapshot family+digest, study, binding-descriptor-set, associated-artifact-set)
• stochastic_controls: dict[control_id, ExperimentStochasticControlModel] (shared block)
• cleanup_plans: dict[cleanup_plan_id, TrialCleanupPlanModel] (shared block; reuse)
• isolation_proof: SchedulerIsolationProofModel | None (plan scope; None ⇒ serial)
• entries: dict[plan_entry_id, AdmittedTrialEntryModel] (≥1)
• admission — bounded success stage/count/limitations + DiagnosticModel list (no partial entries, no raw payloads)
• plan_digest — plan's own canonical content identity (SVR-022)

AdmittedTrialEntryModel: plan_entry_id(==map key), coordinate: TrialCoordinateModel, preallocated run_id, selections (reuse ExperimentSelectionOutcomeModel + qualified point + origin policy id/kind as provenance), bindings (admitted ExperimentBindingDescriptorModel + selection|default origin — admitted intent, not relabeled realized), stochastic_draws: list[RandomStreamDrawRecordModel] (explicit resolved outcomes), apparatus (pre-run intent: ExperimentApparatusConstraintModel + digest-bound ExperimentManifestReferenceModel + RealizationEnvelopeIdentityModel; not a fabricated ExperimentApparatusContextModel), execution_controls (minimal attempt-timeout + cancellation/timeout disposition + cleanup_plan_ref + reused ExecutionRetryPolicyModel), instantiation_provenance (plan/run/family linkage → snapshot identity, SVR-025), entry_digest.

Acyclic integrity chain (preflight-mandated)

logical coordinate + pinned inputs + identity profiles → plan_entry_id & run_id → cleanup-plan identity → entry_digest → plan_digest. Digest fields excluded from their own canonical projection; no child references the enclosing plan digest; cleanup plan_id ≠ plan digest. Canonicalization reuses RFC 8785/JCS + SHA-256; I will extract the existing canonical_contract_digest() core into a dependency-neutral helper (raes_contracts/_canonical.py) and route both satisfiability.canonical_contract_digest and this contract through it — no new serializer/canonicalizer.

Validation layers

• Structural: closed models + generated JSON Schema (required fields, strict unions, map-key equality, forbidden extras).
• Plan-local semantic (_validate_plan + x-raes-invariants): plan_entry_id/run_id/coordinate uniqueness; run_id ≠ plan_id; resolved selections/bindings and non-exhausted draws only; stochastic-control and cleanup-identity joins within the plan; instantiation-provenance equality; isolation-proof entry resolution; admission cardinality; entry/plan digest recomputation (tamper ⇒ fail closed; reorder/worker-count irrelevant).
• Cross-artifact admission against external authorities (task/spec/family/manifests/envelope/cleanup capability) is SCE-002: implement deterministic trial-set compilation and admission #789's compilation scope; SCE-002: publish the admitted experiment trial-plan contract #788 publishes the contract + validators SCE-002: implement deterministic trial-set compilation and admission #789 must call. Non-goals per preflight: no compile/sample/allocate/instantiate/schedule/persist/secret-resolve/API.

Acceptance criteria → mechanism

complete-before-scheduling & no unresolved sampling → resolved-only unions + non-exhausted draws + _validate_plan; reorder/worker-count identity-stable → coordinate-keyed map + JCS digest + isolation proof is the only parallelism knob; scheduler consumes one entry standalone → self-contained entry + shared blocks; trial ≠ attempt identity → run_id preallocated, execution_attempt_id absent; secrets absent/governed → reuse BindingValue literal|secret-reference, no raw secrets in ids/digests/fixtures; invalid/incomplete/duplicate/contradictory/tampered fail closed → structural + plan-local invariants; integrates without duplicating meaning → typed refs/digests + embedded owner models.

Publication wiring & gates

versions.py constant → register in bundle.py::_core_schema_bundle → export in contracts/__init__.py → generate contracts/schemas/plans/admitted-trial-plan-v1.json (-plan-v1 auto-routes) → contracts/schema-publication/entries/admitted-trial-plan-v1.json (stability:"draft", canonical-JSON content_hash + matching last_change) → valid/invalid fixtures under contracts/fixtures/plans/admitted-trial-plan-v1/ → implementations/python/tests/test_sce_002_admitted_trial_plan.py (mirrors test_sce_006_cleanup_contracts.py). Must pass check_generated_schemas.py, check_schema_publication.py, check_json_artifacts.py, check_repo_policy.py, check_requirement_governance.py, verify_all.py. RAES_REQUIREMENT_UID set (branch carries no UID). No CHANGELOG.md/version edits; PR title feat:.

TDD

Model + bundle-publish + fixture-corpus + digest/secret/uniqueness/resolution invariant tests first (red = missing module), then model + registration + generation + entry + fixtures to green. Optional reference-doc note that the sketch is now published (ADR-054 coverage: outcome_required=false).

Traceability (Phase E): IMPLEMENTS SCE-002 & SCE-006 → schema + model module; TESTS → the new test module.

[Brad-Edwards]

gc_codex_review — cycle 1 of 1 (pre-push) on issue #788 (branch 788-trial-plan-contract)
Diff mode: inline — the complete diff was supplied in one prompt

Core review

Verdict: ship-with-fixes

The change is shaped around the correct seam: one closed admitted-plan contract composes the existing coordinate, selection, binding, apparatus, cleanup, isolation, diagnostic, and random-stream vocabulary, while the extracted canonicalizer avoids creating a plan-specific serialization path. The layering and acyclic digest design fit the repository well and leave profile-versioned extension points. However, three admission-boundary invariants are not actually enforced, so the sealed artifact can contradict its declared profiles, apparatus pinning, and stochastic provenance.

Blocking findings (3):

1. [one-off] Declared profiles are not tied to the semantics used to seal the plan — implementations/python/packages/raes_contracts/contracts/admitted_trial_plan.py:105
   Every profile field accepts any syntactically valid SemanticProfileId, while sealing and verification unconditionally use JCS plus SHA-256 and the remaining validators implement only the incumbent semantics. A plan can therefore declare a different canonicalization or integrity profile and still validate under JCS/SHA-256, making its compatibility surface false. Validate the supported profile set or supported combinations before sealing and validation; unknown versions must fail closed.
2. [one-off] A sealed apparatus selection does not require digest-pinned manifests — implementations/python/packages/raes_contracts/contracts/admitted_trial_plan.py:173
   AdmittedApparatusBindingModel reuses the permissive ExperimentManifestReferenceModel without narrowing manifest_refs to digest-qualified processor/backend references. The new valid fixtures consequently seal apparatus selections with no manifest digest or subject identity. That violates the contract's immutable, exact-input boundary and allows the same admitted plan bytes to depend on manifest content not bound by the selected reference. Require each admitted manifest reference to carry the governed digest and subject/version qualifiers, then correct the fixtures.
3. [one-off] Stochastic draw addresses are not joined to their enclosing trial coordinate — implementations/python/packages/raes_contracts/contracts/admitted_trial_plan.py:353
   The plan-local stochastic join checks control existence, executable binding, and namespace, but never requires draw.address.trial_coordinate to equal the enclosing entry.coordinate. The new parallel-isolated fixture exposes the defect: its second entry uses the treatment coordinate while its draw remains addressed to baseline, yet the fixture is accepted as valid. This corrupts deterministic draw provenance and permits distinct entries to reuse an address belonging to another logical coordinate. Enforce coordinate equality and replace this oracle with a matching valid fixture plus a negative mismatch test.

Security review

Verdict: ship-with-fixes

The change is shaped around the correct seam: one closed, versioned admitted-plan contract reusing existing binding, cleanup, randomness, apparatus, and isolation models, with a single canonical integrity mechanism and published fixtures. It also touches two security-critical authorities—pinning executable apparatus and authorizing parallel resource use—and those joins are incomplete: contract validation currently accepts mutable apparatus dependencies and an isolation proof that contradicts the plan’s own resource ownership.

Blocking findings (2):

1. [one-off] Sealed plans accept mutable, digest-free apparatus manifests — implementations/python/packages/raes_contracts/contracts/admitted_trial_plan.py:173
   The admitted apparatus accepts ExperimentManifestReferenceModel values without requiring ref_digest; the new valid fixtures and test builder exercise exactly that state. Attacker model: an actor who can modify a manifest registry but cannot modify an already sealed plan. They can replace the processor/backend manifest under the admitted ref_id and ref_version, and the plan still validates because its digest commits only to a null manifest digest. Dispatch therefore cannot detect that capabilities or executable backend selection changed after admission. Require every admitted manifest reference to carry a content digest and validate that digest against the concrete supplied manifest during admission and execution; ID/version-only manifest references must not be sealable.
2. [one-off] Isolation proof is not bound to the resources it claims are independent — implementations/python/packages/raes_contracts/contracts/admitted_trial_plan.py:362
   The proof-to-plan join checks only that plan_entry_ids exist. It does not resolve evidence_refs or compare the entries’ declared resource boundaries. The published valid parallel fixture consequently requests parallelism 2 while both entries claim the same node.vm-a resource. A malicious authorized plan producer can submit the same shape with arbitrary evidence labels; any scheduler relying on this validated proof can run two trials against one resource, allowing one trial or its cleanup to read, mutate, or destroy the other trial’s state. Reject plan-local resource overlap among entries covered by an independence proof, and require isolation evidence to resolve to trusted, typed evidence bound to the exact plan, entries, and resource identities before it can authorize parallel dispatch.