SCE-002: implement deterministic trial-set compilation and admission

[Brad-Edwards]

Requirements

• SCE-002 — Scenario Composition, Parameterization, and Randomization

Outcome

Implement the pure compiler that turns an expanded scenario family plus admitted experiment-authoring input into the published trial plan.

Scope

• Stable trial-id derivation from semantic inputs.
• Versioned semantic random-stream derivation independent of process-global state.
• Deterministic enumeration, balancing, sampling, and constraint handling.
• Explicit creation of each trial's SDL instantiation bindings.
• Admission against scenario-family domains, cross-point constraints, apparatus intent, and backend realization envelopes where required.
• Bounded diagnostics for unsatisfiable, unsupported, or exhausted selection policies.
• Determinism, property, mutation, concurrency-independence, and cross-process tests.
• CLI/MCP or library entrypoint selected by Design: scenario variation and deterministic trial realization (SCE-002) #652 without creating a second semantic authority.

Acceptance criteria

• Identical governed inputs produce byte-identical canonical trial plans.
• Serial, parallel, shuffled, resumed, and partitioned compilation produce the same entries.
• Adding an unrelated trial or changing worker count cannot perturb an existing trial's semantic stream.
• Every selected value belongs to its admitted domain and is recorded once with origin.
• Constraint rejection/resampling behavior is bounded and reproducible.
• No backend side effect occurs during compilation.
• Failures identify semantic paths and policy ids without disclosing secret values.

Non-goals

• Runtime scheduling.
• Participant decision randomness.
• Backend-private realization.
• Statistical analysis of completed runs.

[Brad-Edwards]

🛠️ Picked up by /implement - driver codex, branch 789-deterministic-trial-compilation, 2026-07-29T00:42:14.109Z.

[Brad-Edwards]

gc workflow phase recorded: preflight (issue #789). 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 #789). 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

Outcome and boundaries

Implement SCE-002 as one pure in-process raes_processor library boundary that compiles an already admitted ExpandedScenario family and ExperimentSpecModel into exactly one sealed AdmittedTrialPlanModel, or a bounded canonically ordered diagnostic set with no partial plan. It will not parse/compose SDL, fetch artifacts, resolve ambient secrets, call a backend, schedule, persist, execute, or add CLI/MCP/HTTP surfaces. Durable selected-snapshot/run linkage remains #790.

The architecture-preflight prerequisites are implementation obligations, not assumed behavior: publish exact v1 coordinate/identity/compiler semantics and vectors; add the SDL-owned selected-scenario admission seam; represent an expanded-family reference precisely; admit the absent binding-set case; and require typed execution/cleanup authority instead of backend defaults.

Contract and profile work

1. Publish the exact trial-coordinate-v1, trial-entry-identity-v1, archival-run-identity-v1, and trial-compiler-v1 projections in the formal SCE-002 authority. Fix canonical coordinate order, replicate encoding, canonical domain order, supported policy-root/cardinality behavior, diagnostics ordering/bounds, and JCS/SHA-256 domain-separated plan/entry/run/cleanup identities. Add fixed conformance fixtures so the algorithms do not exist only as Python traversal behavior.
2. Correct AdmittedTrialPlanInputRefsModel so scenario_family_ref is a digest-pinned expanded-family reference rather than an instantiated snapshot, and binding_descriptor_set_ref is absent when the admitted experiment has no descriptor set. Regenerate the admitted-plan schema and fixtures and update schema-publication parity/ledger material required by repository policy.
3. Add closed typed compilation limits plus schedule-independent execution-control and cleanup templates. Templates contain the full authored timeout, cancellation, clean-state, resource-boundary, cleanup-obligation, and retry intent but omit identities that the compiler deterministically binds. No default timeout, retry, cleanup, isolation, or parallelism policy will be synthesized.

SDL-owned selection and admission

4. Add a public pure raes operation that accepts one complete selection per family point, validates each outcome against its domain, validates requires/excludes/cardinality/precedence constraints, resolves the canonical typed target, constructs a transient selected family, removes the resolved registry, and reruns ordinary instantiation plus whole-scenario semantic admission. It will be the production ScenarioBindingTargetResolver for scenario-plane descriptors and will return the admitted concrete scenario used by envelope membership checks. Processor code will not mutate SDL payloads or import private validator helpers.
5. Test every supported target kind (parameter, governed reference, alternative, subset, order, logical timing), complete-selection enforcement, cross-point constraints, canonical alias/target resolution, secret-safe failures, and post-selection whole-scenario rejection.

Deterministic compiler

6. Generate canonical logical coordinates from the structured run allocation only: canonical condition id followed by fixed-width one-based replicate id, or replicate-only coordinates for simple allocations. Unsupported block/cohort/arbitrary dimensions and ambiguous free-text semantics fail closed.
7. Resolve the policy graph deterministically. Fixed leaves broadcast. A single non-fixed root (or one explicit product root) must exactly cover the governed coordinate set; nested products are acyclic dimensions; enumerate/product cardinality mismatches, orphaned nodes, overlapping point writers, uncovered points, ambiguous roots, and implicit zip/cycle/padding/truncation fail with bounded diagnostics. Equal strata join exact condition/replicate coordinates. Enumeration uses canonical finite-domain order.
8. Implement sample-with-replacement only through blake3-xof-v1, sampling-selection, exact StreamAddressModel coordinates, and draw_bounded_integer_batch(). Decode only public seeds in this issue; governed entropy fails closed until an authorized resolver boundary exists. Preserve exact draw provenance and make any collision/exhaustion an atomic compilation failure.
9. Equality-check selection-linked binding descriptors, validate all descriptor targets through the SDL resolver and supplied concrete participant/apparatus manifests, and record each admitted binding once with its origin. Do not fabricate descriptors/defaults or expose selected values in diagnostics.
10. Admit every selected scenario against the supplied digest-valid realization-envelope carrier and require its identity to equal the plan apparatus binding. Require digest-pinned manifest refs. Bind explicit execution/cleanup templates to deterministic identities for each entry. Validate plan-wide coordinate, id, address, resource, and byte/diagnostic budgets before sealing.
11. Derive identities acyclically with domain-separated JCS projections: plan id from admitted plan-wide input intent; entry/run ids from that plan intent plus the semantic coordinate; cleanup id after entry/run ids; then existing entry/plan seal helpers compute content digests. IDs will not depend on entry position, worker/partition count, retry, process, time, UUIDs, Python hashes, or backend availability.

TDD and verification

12. Write failing tests first for all issue acceptance clauses and preflight gates, observe the expected failures, then implement the minimum production behavior. Coverage will include:

• byte-identical canonical plans from identical inputs;
• serial, reversed, shuffled, partitioned, resumed-subset/reassembled, threaded, and fixed-argv cross-process compilation equivalence;
• stability of existing per-trial selections/streams when an unrelated coordinate is added;
• every selected value is in-domain and recorded exactly once with leaf origin;
• deterministic fixed/enumerate/product/stratified/sample behavior;
• bounded/reproducible constraint rejection and random-draw exhaustion;
• ambiguous/underfilled/overlapping policy failures;
• binding, manifest, envelope, cleanup, limits, atomicity, and secret-redaction failures;
• mutation/tamper rejection, property tests, and no backend/persistence side effects.

13. Update the SCE-002 assurance-fulfillment record to cite delivered compiler unit/property/determinism evidence and remove SCE-002: implement deterministic trial-set compilation and admission #789 from the applicable waivers while retaining unrelated issue waivers.
14. Run targeted tests throughout, then the repository-mandated policy trio, canonical nox -s verify, make policy, and full pre-commit commands with RAES_REQUIREMENT_UID=SCE-002. Inspect the whole diff, keep files under the repository line cap, and preserve schema bundle/publication parity, concept-authority placement, and Ground Control IMPLEMENTS/TESTS traceability. Do not edit changelog or version files.

[Brad-Edwards]

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

Core review

Verdict: don't-ship

The top-level shape is sound: a pure processor boundary orchestrates contract-owned DTOs and canonical sealing helpers, while selected-scenario construction stays in the SDL-owning package. However, the new semantic seam permits last-write-wins selection materialization, and the apparatus boundary seals references without the promised concrete manifest proof. Together with resource ceilings applied only after large collections are built, these are structural contract failures rather than polish; the compiler can emit a plan that misrepresents admitted intent or fail outside its bounded diagnostic contract.

Blocking findings (3):

1. [class] Competing variation targets are resolved by silent last-write-wins — implementations/python/packages/raes/selected_scenario.py:229
   Each outcome directly mutates the selected-family payload, but there is no canonical-target collision check before mutation. The added all-kinds fixture already has target-ref and host-choice addressing the same content.payload.target; its agreeing outcomes conceal that conflicting outcomes would be applied in point-id order, with the later value winning while both selections are sealed into the plan. Parameter, reference, collection, and timing assignments have the same shape. Resolve every point to its canonical target first and reject conflicting writers—or explicitly prove equivalent values—before applying any outcome.
2. [class] Apparatus admission never verifies referenced manifest content — implementations/python/packages/raes_processor/trial_compiler/compiler.py:122
_validate_apparatus_intent compares reference metadata with the authoring intent, but never joins each admitted manifest reference to a supplied concrete processor/backend manifest or recomputes and compares its digest. TrialCompilationRequest permits an empty manifest map, and the success fixture uses an arbitrary digest without a concrete manifest. A plan can therefore reach admitted-sealed with nonexistent or mismatched apparatus evidence. Require and validate the exact concrete manifest for every selected reference—including kind, id, version, subject, and digest—before capability, allowlist, envelope, or plan admission.
3. [class] Resource ceilings are enforced only after full materialization — implementations/python/packages/raes_processor/trial_compiler/domains.py:55
   An integer interval is converted to a complete list before max_domain_values_per_point is checked. Coordinate generation similarly builds the full simple or per-condition list before checking max_coordinates. Large but valid declared counts can therefore exhaust memory or runtime instead of returning the bounded deterministic diagnostic promised by the compiler profile. Compute each cardinality with overflow-safe arithmetic and enforce its ceiling before constructing either collection.

Security review

Verdict: don't-ship

The pure compiler and SDL-owned selected-scenario seam are shaped coherently, and this change adds no new parsing, network, process, or persistence surface. The security-critical seam is apparatus admission: sealing a plan elevates manifest identities and capability claims into trusted execution authority, but the implementation validates partial caller-provided projections instead of exact, digest-bound concrete manifests. That boundary must fail closed before this compiler can safely produce admitted-sealed plans.

Blocking findings (1):

1. [class] Partial apparatus identity checks allow unapproved or substituted manifests — implementations/python/packages/raes_processor/trial_compiler/compiler.py:142
   Attacker model: a caller who can influence apparatus selection while supplying an otherwise admitted experiment. Capability references are trusted directly from the request; the processor/backend allowlist passes when any selected subject intersects the combined allowlist; and required manifests are compared without their digest. The caller can therefore include one allowed subject, add an unapproved processor or backend, substitute a required manifest with the same ID/version but different digest, and self-assert the required capabilities. Because no exact join to validated concrete manifests is required, the compiler can emit an admitted-sealed plan authorizing tampered or disallowed apparatus, which a downstream executor may trust. Resolve every selected reference to a supplied concrete manifest, verify the complete digest-pinned identity, derive capability/profile support from that validated manifest, enforce each processor and backend against its corresponding allowlist, and reject missing or unmatched payloads before sealing.

[Brad-Edwards]

gc_codex_review pre-push cycle 1 of 1 complete for issue #789 on branch '789-deterministic-trial-compilation'. Posted by the MCP server to enforce the pre-push hard-cap-1 contract (issues #796, #804, #906). Do not edit or delete — used by the next gc_codex_review (uncommitted) invocation to count cycles.