Define authoritative cross-plane experiment binding descriptors and typed participant configuration targets

[Brad-Edwards]

Outcome

Publish the portable RAES contract surfaces required to bind experiment factors and conditions safely to scenario variation points, participant-implementation configuration, and apparatus configuration without encoded names, private backend schemas, or arbitrary configuration injection.

This issue is a prerequisite for #787, #788, #789, #790, and #345.

Problem

The current experiment condition parameter carries name, a scalar value, value_kind, and redaction, but it does not identify:

• the authoritative binding plane;
• a canonical target address and declared scalar type;
• the source factor and condition;
• sensitivity or a structurally distinct secret-reference form;
• the owning validator, defaults, normalized realized value, or provenance;
• a typed, addressable participant-implementation configuration target surface.

ParticipantImplementationSelectionModel.configuration_ref and configuration_digest preserve configuration identity, but the participant manifest and runtime contracts do not publish which configuration targets are supported or how their types, defaults, validation, realization provenance, and digests are governed.

Without these contracts, downstream apparatuses cannot distinguish scenario, participant, and apparatus intent. Inferring a plane from value_kind, parameter names, prefixes, free-text constraints, or matching field names is ambiguous and creates cross-plane injection and provenance failures.

Scope

• Define a versioned binding descriptor that identifies exactly one authoritative plane, canonical target, exact JSON scalar type, source factor and condition, value disposition, and owning contract/validator.
• Define canonical target-address and alias/collision semantics. Two inputs resolving to the same target must fail even when their values match.
• Bind scenario-plane targets to the governed scenario-family variation/SDL instantiation surface used by SCE-002: add experiment variation-selection policies and allocation bindings #787-SCE-002: integrate trial realization with SDL instantiation and run provenance #790.
• Extend participant implementation manifest/runtime contracts with a typed, addressable configuration-target declaration and validation/result surface, including defaults, normalized realized values, configuration identity, and provenance.
• Define a structurally distinct secret-reference binding form. Resolved secret values must remain outside authoring documents, trial plans, canonical digests, diagnostics, and run records.
• Define portable realized-binding provenance sufficient to preserve factor, condition, plane, target, type, default-or-override origin, non-secret realized value or reference identity, owning contract version, and authoritative configuration digest.
• Specify canonicalization, ordering, compatibility, schema publication, conformance validation, and positive/negative fixtures.
• Define fail-closed behavior for older or ambiguous parameter contracts when explicit binding semantics are required.

Acceptance criteria

• Every admitted parameter resolves to exactly one declared plane and one canonical target owned by that plane.
• Factor and condition provenance is explicit rather than reconstructed by name equality or collection ordering.
• Unknown planes or targets, cross-plane fallback, type coercion, duplicate canonical targets, alias collisions, non-finite numbers, and ambiguous legacy inputs fail before runtime mutation.
• Participant implementations can publish typed configuration targets and validate a complete realized configuration while preserving defaults, normalized values, provenance, and a canonical configuration digest.
• Secret references are distinct from scalar values; only non-sensitive reference identity is admitted or recorded, and no resolved secret participates in identity or canonicalization.
• Scenario bindings integrate with the scenario-family selection, trial-plan, compiler, and provenance contracts in SCE-002: add experiment variation-selection policies and allocation bindings #787-SCE-002: integrate trial realization with SDL instantiation and run provenance #790 without creating a second SDL or instantiation path.
• Participant binding identity integrates with the implementation/provenance contracts in Participant Implementation And Exposure Provenance (EXP-733) #345 without turning manifest free-text constraints into a configuration schema.
• Generated schemas, public models, compatibility rules, conformance registration, valid/invalid fixtures, canonicalization tests, and documentation move together.

Non-goals

• Selecting or constructing participant providers.
• Executing or scheduling trials.
• Defining an APTL-specific apparatus allowlist or exposing arbitrary backend configuration.
• Environment-variable binding, arbitrary file paths, command fragments, Python entry points, templates, generic overlays, or plugin dispatch selected by experiment input.
• Persisting or hashing resolved secret values.

[Brad-Edwards]

🛠️ Picked up by /implement - driver codex, branch 903-experiment-binding-contracts, 2026-07-26T02:24:46.933Z.

[Brad-Edwards]

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

1. Publish the contract family in raes_contracts: add closed, versioned models for strict JSON scalar types, literal-versus-secret-reference values, explicit factor/level/condition provenance, and plane-specific scenario, participant-implementation, and apparatus targets. Add reusable owner/validator identity, typed configuration-target registry, realized-binding provenance, and participant complete-configuration result models. Reuse ContractModel, strict Pydantic scalars, existing experiment reference/identity types, and canonical_contract_digest(); do not introduce generic paths, overlays, executable validator names, environment/file/command binding, or a second canonicalizer.
2. Integrate the surfaces with incumbent owners: add descriptors to experiment authoring input and validate their factor/level/condition joins; add optional realized-binding provenance to archival runs; add typed target registries to participant implementation, processor, and backend manifests; and require participant selection configuration refs/digests to remain coherent with the authoritative normalized result. Preserve legacy descriptive parameters only where no binding claim is made, with an explicit fail-closed validator for workflows that require binding semantics.
3. Implement atomic configuration realization: resolve aliases before validation, reject alias/canonical collisions and duplicate canonical targets even for equal values, apply defaults and overrides as one complete operation, enforce exact non-coercing scalar types and finite numbers, run a governed owner validator protocol, preserve default/override provenance, and calculate one RFC 8785/JCS digest over normalized non-secret values or non-sensitive secret-reference identities. No partial result is returned on failure, and resolved secret material has no model field or digest path.
4. Publish and register the new roots through schema_bundle(), schema output routing, conformance validators, supported-contract allowlists, hand-governed schemas, positive/negative fixtures, schema-publication entries, and per-schema change-ledger hashes. Update every modified draft schema entry and keep generated output byte-identical to contracts/schemas/.
5. Add an accepted ADR and reference documentation explaining authority planes, typed owner targets, compatibility, secret handling, atomic configuration validation, canonicalization, and downstream SDL/trial-plan/participant-provenance integration. Update the ADR index pin and retain the architecture preflight note as implementation guidance.
6. Test model and published-schema behavior for all issue criteria: unknown/cross-plane targets, factor/condition mismatches, strict type rejection (including bool/int and non-finite numbers), duplicate/alias collisions, unknown targets, missing required values, defaults/overrides/normalization, digest stability under ordering and aliases, structurally distinct secret references, absence of resolved-secret fields, legacy fail-closed behavior, conformance registration, and positive/negative fixtures. Extend existing manifest, experiment-authoring, runtime-contract, schema-publication, and generated-schema parity tests rather than creating parallel harnesses.
7. Repair the stale .ground-control.yaml routing key that prevented the repository policy workflow from loading. Run targeted tests during TDD, then the repository gates with ACES_REQUIREMENT_UID set because the branch has no requirement UID: tools/check_repo_policy.py, tools/check_requirement_governance.py, tools/verify_all.py, the configured Nox completion command, generated-schema parity, schema-publication, JSON-artifact, authority-boundary, semantic-coverage, and specification-coverage checks.

Design checks

• Security: closed discriminated unions and strict scalars protect authoring/config shape; whole-set alias resolution and owner registries prevent cross-plane injection; secret references carry only bounded non-sensitive identity; no endpoint, auth grant, environment/OS lookup, plugin dispatch, raw validation input, or resolved-secret carrier is added. Existing diagnostics and control-plane authorization remain the only later runtime surfaces.
• Maintainability: build on experiment factor/allocation validators, SDL variation authority, manifest models, ContractModel, canonical_contract_digest(), schema generation, conformance registration, and publication tooling. A single reusable target-registry/collision implementation serves participant and apparatus owners.
• Extensibility: new targets and validator versions extend owner-published registries without editing the cross-plane union; adding a new authority plane remains an explicit contract/ADR version change. The owner-validator protocol permits trusted implementations without experiment-selected code.
• Whole repository: source models, public exports, experiment/participant/apparatus carriers, supported-contract registries, schemas, fixtures, publication records, conformance, ADRs/docs, and mandatory policy/verification scripts move together. No changelog or version file is edited; the eventual PR title will use a release-please-compatible Conventional Commit type.

[Brad-Edwards]

gc_codex_review — cycle 1 of 1 (pre-push) on issue #903 (branch 903-experiment-binding-contracts)

Core review

Verdict: don't-ship

The overall shape is strong: a closed plane union, owner-published registries, strict scalar handling, canonical digests, explicit source joins, and behavioral tests form the right seam for cross-plane binding. However, the authority boundary is not yet closed: canonical target identities discard declared owner coordinates, and manifest resolution trusts caller-created index keys rather than the resolved manifests themselves. Because authoritative identity is the central purpose of ADR-094, these are structural defects rather than peripheral validation gaps; the otherwise broad tests also miss these mismatch cases.

Blocking findings (2):

1. [class] Canonical keys discard parts of the declared target identity — implementations/python/packages/raes_contracts/contracts/experiment_bindings.py:80
   The collision invariant is computed from lossy keys. Scenario keys omit variation_point_id; participant and apparatus keys omit manifest_version; and the latter two flatten structured owner fields into delimiter-based strings even though those fields accept arbitrary non-empty text. Consequently distinct authoritative targets can collapse into the same key and be rejected as duplicates. This directly contradicts ADR-094's plane-specific identity model and forecloses legitimate manifest-version and variation-point evolution. Preserve every identity coordinate as separate tuple elements and add collision tests for targets differing only in each currently omitted field.
2. [class] Target admission trusts caller-supplied manifest index keys — implementations/python/packages/raes_contracts/experiment_bindings.py:110
   After resolving a caller-provided tuple key, neither path verifies that the manifest's own identity and schema version match the descriptor target; the apparatus path also does not verify that component_kind matches the manifest type. A stale or incorrectly keyed selected-manifest map can therefore admit a target under an owner identity different from the manifest that supplied its registry, and that false identity is retained in admitted provenance. Verify the resolved manifest's intrinsic identity, version, and kind at this boundary, with negative tests for mis-keyed participant and apparatus manifests.

Security review

Verdict: ship

This change is shaped correctly as an offline, schema-first authority boundary: closed plane-specific binding targets delegate resolution to scenario or selected-manifest owners, participant configuration realization remains atomic and type-strict, secret material is represented only by bounded references, and canonical digests join normalized configuration to provenance. It touches contract publication, manifest capability declarations, conformance routing, and archival provenance without introducing an execution, authentication, filesystem, or network surface. The owner registry and resolver protocols preserve the obvious next variation—new targets or validator versions—without opening dynamic dispatch or cross-plane fallback. I found no concrete, exploitable security issue introduced by the diff.

No blocking findings.

[Brad-Edwards]

gc_codex_review pre-push cycle 1 of 1 complete for issue #903 on branch '903-experiment-binding-contracts'. 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.

[Brad-Edwards]

Review decision record — codex cycle 1 (issue #903)

Reviewer: codex
Cycle: 1

Architectural read:

Core reviewer: The overall shape is strong: a closed plane union, owner-published registries, strict scalar handling, canonical digests, explicit source joins, and behavioral tests form the right seam for cross-plane binding. However, the authority boundary is not yet closed: canonical target identities discard declared owner coordinates, and manifest resolution trusts caller-created index keys rather than the resolved manifests themselves. Because authoritative identity is the central purpose of ADR-094, these are structural defects rather than peripheral validation gaps; the otherwise broad tests also miss these mismatch cases.

Security reviewer: This change is shaped correctly as an offline, schema-first authority boundary: closed plane-specific binding targets delegate resolution to scenario or selected-manifest owners, participant configuration realization remains atomic and type-strict, secret material is represented only by bounded references, and canonical digests join normalized configuration to provenance. It touches contract publication, manifest capability declarations, conformance routing, and archival provenance without introducing an execution, authentication, filesystem, or network surface. The owner registry and resolver protocols preserve the obvious next variation—new targets or validator versions—without opening dynamic dispatch or cross-plane fallback. I found no concrete, exploitable security issue introduced by the diff.

Blocking findings: 2

Finding 1 — class (3 instances)

• ID: F1
• Title: [core] Canonical keys discard parts of the declared target identity
• Location: implementations/python/packages/raes_contracts/contracts/experiment_bindings.py:80
• Decision: fix
• Rationale: The collision invariant is computed from lossy keys. Scenario keys omit variation_point_id; participant and apparatus keys omit manifest_version; and the latter two flatten structured owner fields into delimiter-based strings even thou…
• Instances:
  • implementations/python/packages/raes_contracts/contracts/experiment_bindings.py:80
  • implementations/python/packages/raes_contracts/contracts/experiment_bindings.py:94
  • implementations/python/packages/raes_contracts/contracts/experiment_bindings.py:109

Finding 2 — class (2 instances)

• ID: F2
• Title: [core] Target admission trusts caller-supplied manifest index keys
• Location: implementations/python/packages/raes_contracts/experiment_bindings.py:110
• Decision: fix
• Rationale: After resolving a caller-provided tuple key, neither path verifies that the manifest's own identity and schema version match the descriptor target; the apparatus path also does not verify that component_kind matches the manifest type. A …
• Instances:
  • implementations/python/packages/raes_contracts/experiment_bindings.py:110
  • implementations/python/packages/raes_contracts/experiment_bindings.py:132

[Brad-Edwards]

gc_review_cap_disposition — issue #903 (codex, cycle 1 of 1)

Disposition: proceed
Auto-override grant #: n/a
Rationale: Findings are fully known/classified (0 one-offs, 2 classes, no security hits) and surfaces are low-risk (doc/unclassified, consistent with a schema+fixture-heavy contracts change); large diff size reflects JSON schema/fixture volume, not scope risk.

Posted by the MCP server to record the review-cap auto-disposition. Do not edit or delete — the cycle wrappers read this marker to verify an over-cap auto-grant before running a cycle.