RFC-0043 execution contract proposal
Versioned draft snapshot
RFCs, reference catalogs, and evidence reflect Spec 3b2e3e7a114fb826b1445d39a48756b8fff629cd. Counts and pending/status notes belong to that snapshot. Read the dated project update for later progress.
Source repositories are private during staging. Links marked “repository access required” need access to the linked repository.
This is a trace and gap record from the pinned draft specification. It does not establish proof or implementation conformance.
Status: proposal; RFC prose, Lean catalog, and RDF remain unchanged pending owner choice on the public operation contract.
Evidence
- RFC-0043 §4.1 says failure of any authorization mechanism returns
core.errors.Unauthorized. Section 9.2 instead assigns authentication failureUnauthorizedand authorization failureForbidden. Both cannot be the response for a denied predicate-policy check. - Section 7.1 says guards run before a transaction opens. Section 9.2 opens the transaction before guards and says steps 7–8 can abort before opening it. Section 8.3 requires workflow transition locks inside the transaction.
- Sections 1 and 5.3 promise all effect steps execute in one transaction and
roll back together. Section 5 includes
event.emitandadapter.call. Emitting to an external subscriber or invoking an external adapter cannot be rolled back by a graph transaction. Theadapter.calltable calls it non-mutating “per-adapter,” while §3.2’s query prohibition lists seven mutating kinds and omitsadapter.callregardless of its actual behavior. - Section 9.2 persists a successful idempotency result after commit. A crash between steps 11 and 12 can repeat committed effects on replay; a concurrent replay can also pass the cache check before either result is recorded. This violates §6.2’s replay promise.
- Section 11.1 calls the schema a faithful codification and says legacy
operations install unchanged; §11.3 adds mandatory
tenantBoundaryRef, forward-reference rejection, and payload enforcement. The compatibility claim needs qualification. Nothing is deployed, so no migration path is needed for a first release. - Invariant 10 says every invocation produces an audit entry. Section 9.2 emits the audit entry only after commit, and its pre-transaction aborts and rolled-back failures skip that step. The audit scope and durability rule need to be explicit.
Recommended first-release contract
- Return
Unauthorized(401-equivalent) for absent/invalid authentication; returnForbidden(403-equivalent) for an authenticated principal denied by roles, permissions, or a predicate policy. Both abort before effects. - Resolve tenant context and authenticate before opening the transaction. Run authorization checks that read graph state inside a read/write transaction or a consistent snapshot. Evaluate input-only preflight guards before opening it; evaluate guards that read mutable graph state inside the same transaction as effects. Workflow state lookup, transition guard, row lock, state update, and graph effects all share that transaction.
- Limit the atomic rollback guarantee to graph writes plus an outbox record
for
event.emit. Dispatch outbox events after commit with retry and a stable event ID. Permitadapter.callin a transaction only for explicitly read-only adapters whose result is consumed before commit. Model external writes as post-commit delivery or a separately specified saga with compensation; reject an effect pipeline that implies impossible rollback. Query operations may call only declared read-only adapters. - Claim an idempotency key atomically with operation execution using a
database uniqueness constraint on
(operation FQN, tenantId, principalId, key). Commit the successful result and graph effects in the same transaction. A concurrent invocation waits for the first outcome; a failed transaction releases the claim for retry. If the response is larger than the durable result limit, persist a stable reference to it. - Remove the unchanged-install assertion. Document the first-release contract directly and test compile-time validation against it.
- Record both successful and rejected invocations with a stable attempt ID. Include the outcome and failure category. Persist success audit data in the operation transaction; persist pre-transaction and rollback failure records through a separate bounded audit path so the failed graph transaction does not erase them. Define which failures can be omitted if the audit sink is unavailable, and surface that operational fault.
Acceptance fixtures
- Authentication failure returns
Unauthorized; authenticated policy denial returnsForbidden, each before an effect runs. - A workflow guard sees the locked current state and concurrent transitions serialize; a failing guard leaves state and graph writes untouched.
- Event dispatch occurs only after commit; a rolled-back operation produces no delivered event. Dispatcher retry preserves the event ID.
- An adapter declared external-write is rejected from an atomic pipeline; query transport rejects any mutating adapter.
- A crash or injected interruption between graph effect and response cannot re-execute a successful mutation for the same idempotency key. Concurrent same-key invocations return one committed result.
- Compile fixtures reject missing tenant boundary, forward references, mutating query steps, and oversize effect pipelines.
- Authentication denial, guard failure, effect rollback, and success each produce exactly one durable invocation audit record with the right outcome.
If accepted, update RFC-0043 narrative, Lean definitions and rules, claim projection, reference output, and implementation fixtures together.