Publish backend operation and supervision contracts

[Brad-Edwards]

Publish the portable interfaces required by the accepted operation lifecycle, so runtime and backend implementations share explicit execution and outcome meanings.

Acceptance criteria

• Define versioned requests, acknowledgements, progress, terminal/indeterminate outcomes, refusal, cancellation, reconciliation, and the identity/fencing information required by the accepted design.
• Bind capability and willingness checks to requested requirements and execution context. Represent partial effects and unknown outcomes without claiming rollback, prevention, or observation that was not established.
• Publish schemas, profiles, Python contracts, public backend protocols, and migration rules consistently. Update publication manifests, generated bundles, and requirement traceability.
• Provide contract examples for accepted work, contextual refusal, cancellation races, duplicate requests, and uncertain completion. Backend owners can implement the protocol without a second scenario runtime.

Prerequisites: #1348.

References: Diagnosis, Diagnosis.

Requirements

• API-402 — Plain-Data Execution, Result, And History Contracts

[Brad-Edwards]

🛠️ Picked up by /implement - driver codex, branch 1360-backend-operation-contracts, 2026-09-24T01:24:24.927Z.

[Brad-Edwards]

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

Publish the optional backend operation/supervision contract family under API-402, following #1348 and ADR-113. Preserve existing operation states, live-result/history owners and archival separation.

1. AC1 / API-402 (Path A): add closed, bounded, versioned request, capability, supervision-request and discriminated response carriers in raes_contracts/contracts/backend_operation*.py. Responses distinguish admission/refusal, acknowledgement, progress, control disposition, terminal evidence and reconciliation. Bind original admission context, backend, deployment, owner/execution generation, invocation/attempt/worker identity, conflicting-effect scope, baseline revision, admitted artifact and exact requirement commitment. Supervision carries independently authorized actor/request identity. Keep strict finite stage budgets and their origin.
2. AC2 (Path A): publish shared semantic validators for exact cross-message binding, capability/willingness, supported contract versions, ordering/duplicates and honest effect/outcome claims. Known partial effects require residual state/scope evidence; unknown effects or unproved cessation cannot become known success/failure/cancellation. Cancellation acceptance is not cessation. Validators check claims and relationships, not physical truth or runtime authorization.
3. AC3 (Path A): publish normative schemas, matching schema_bundle output, public facade exports, optional typed backend protocols, backend manifest contract allowlists and an additive backend profile. Update per-contract v2 publication records and routed corpus. Keep existing receipts/status/store codecs unchanged; explicitly document lossless opt-in and refusal of unsupported versions rather than inventing migration evidence.
4. AC4 (Path A): publish and execute examples for accepted work/progress, contextual refusal, completion winning a cancellation race, known-partial cancellation, duplicate requests, uncertain completion and bounded reconciliation. Add negative cross-context, stale-generation, duplicate-conflict, unsupported guarantee, unknown-outcome and closed-reader tests. Backend methods execute/observe/control one admitted invocation; RAE retains scenario scheduling, authorization, authored retry and terminal publication.
5. Documentation (Path D accompanying executable tests): add the normative contract specification and backend migration guide, update contracts/README.md, public backend guidance and runtime architecture. Reconcile API-402 IMPLEMENTS/TESTS/DOCUMENTS links, retaining ACTIVE and clearly labeling publication evidence. No runtime supervision or P3 conformance claim.
6. Repair the discovered requirement-governance defect with a failing regression through the real policy consumer: API-402 is absent from requirement_order.yaml. Map this already ACTIVE live control-plane contract to the existing runtime-control-plane phase alongside API-404; no new phase or gate.

Security: reuse OperationAdmissionContext, ContractModel, strict bounded primitives, canonical_json_digest and existing artifact/result authorities. Carrier references are non-authorizing; no secrets, executable locators, native exceptions or arbitrary metadata. Runtime identity/subject checks, one-use claim authorization and native result/release validation remain mandatory integration boundaries. Add cross-message rejection tests.
Maintainability: reuse schema bundle, semantic-invariant annotations, publication index entries, backend profile/corpus loader, manifest authority and current diagnostics; no parallel engine, store, lifecycle enum or exception hierarchy.
Extensibility: optional contract/version + operation kind + exact requested guarantees/context, with explicit refusal; avoid backend-specific branches and global cancellation flags. References preserve owning workflow/time/trial policy instead of defining a second policy language.
Whole-repository view: public package exports and packaged corpus, backend producer/consumer allowlists, strict legacy readers/store migration, JSON schema structural validation plus semantic validation, publication hashes/coverage, requirement governance, existing nox/hooks and hosted CI.

Verification: set RAES_REQUIREMENT_UID=API-402. Observe new behavioral tests fail before implementation, then run only the new contract/governance modules and relevant existing lifecycle, facade and backend profile tests. Run targeted file-local policy, schema publication/compatibility, corpus/schema checks and requirement governance. Full suites remain CI/CD only. Preserve the mandatory pre-publish hook, one configured review cycle, hosted CI/Sonar and readiness handoff. No changelog/version edits or new dependencies.

[Brad-Edwards]

gc_codex_review — sanitized deferred publication for issue #1360, cycle 1 of 1
Reviewed revision: 49c506679708f39cbadd645398ffcbdcdb00d80723a3d47abc0492dc249f49e2

Architectural read

The optional portable protocol reuses the existing operation identities and states, keeps backend reports as evidence and preserves runtime terminal authority. Review found one invalid transcript transition and no concrete exploitable security defect in the publication boundary.

Verdict: ship-with-fixes

Findings

core-F1 — Reject admission refusal after an accepted invocation

• Classification: one-off
• Decision: fix
• Location: implementations/python/packages/raes_contracts/contracts/backend_operation_validation.py:122
• Rationale: Require admission reports to precede accepted acknowledgement. Once effects are possible, subsequent refusal cannot classify the outcome; use correlated effect evidence. Add regression tests for late willing and refused admission reports.

[Brad-Edwards]

gc_codex_review pre-push cycle 1 of 1 complete for issue #1360 on branch '1360-backend-operation-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.