RFC-0043 template transaction repair 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: proposed, awaiting owner decision. Owners: Graph Runtime and Compiler. No implementation or normative contract changed.
Confirmed source discrepancy
RFC-0043 §5.5 requires template.compose inside the operation transaction, with exports available to subsequent steps by their declared key. §1 requires pipeline rollback on any failure. The extracted framework currently differs:
graph/packages/graph-module-model/model/manifest.tsroutes template.compose into effectPostCommit rather than the atomic write sequence.trpc/packages/api-procedure-core/write-dispatch.tsdispatchDeclaredOperation executes writes first, then dispatchPostCommitEffects. The latter catches template failures, records POST_COMMIT_FAILED, and returns ok:false without throwing. Subsequent post-commit effects continue.write-dispatch.test.tsexplicitly tests best-effort continuation. Those tests encode current behavior; they are not RFC transaction conformance.graph/packages/graph-module-engine/services/write-resolver-service.tsalready has an in-transaction template.instantiate path. It constructs a template context using the open graph transaction and throws on execution errors or a missing root resource ID.
This is executor and normalization source evidence. No database rollback test was run for this investigation, and nested transaction enlistment is unproved.
Recommended contract
Retain authored transactional template.compose for graph creation. Normalize it into the atomic ordered sequence and implement it through a transaction-bound template executor. Preserve the declared effect ordering, step keys, and full export map rather than substituting only a root-resource result.
The existing template.instantiate implementation is a reusable starting point, not a proven drop-in replacement: it currently returns resourceId, opens its own graphClient.transaction callback, and needs explicit verification that nested execution shares the enclosing transaction. A mechanical kind rename would not satisfy the exports or atomicity requirements.
Any separately requested deferred cascade must have a distinct operation kind and documented delivery semantics. It must not silently replace the normative transactional compose kind. External event delivery remains a separate contract question: committing an outbox record atomically can support later delivery, but requires a durable delivery contract rather than best-effort logging.
Exact implementation work after decision
- Manifest normalization: place compose steps in their original sequence positions, rather than grouping them after all graph writes.
- Atomic executor: accept an existing transaction-bound template context and return the template exports under the step’s declared key.
- Write grammar/result schemas: carry compose inputs and export results through the established schema layer; add schema definitions for any new boundary record rather than introducing an untyped cross-process payload.
- Remove compose from best-effort post-commit dispatch and make unsupported transactional execution fail before any writes, without a fallback.
- Update model comments, normalization tests, dispatcher tests, RDF/Lean implementation traces, and the framework acceptance audit.
- Inventory authored compose uses and verify their ordering and export bindings.
Required acceptance evidence
- A preceding write, compose write, and following write all commit together.
- A failing template rolls back all three, including partial template writes.
- A failing later step rolls back the earlier template effects.
- A later step can resolve all declared template exports by key.
- Nested templates share the enclosing transaction and cannot independently commit; include an integration test against the actual graph backend.
- Queries reject compose as a mutating effect before execution.
- Missing template runtime fails before mutation; no post-commit fallback.
- Replay and idempotency tests cover the complete atomic sequence.
Alternative: redefine template.compose as deferred and make another kind the transactional owner. This changes RFC-0043’s authored behavior and introduces another delivery/retry contract. The recommended approach preserves the existing normative transaction promise and uses the executor capability already present.
Authored source inventory
The framework tool tools/migration/inventory_template_compose.py parses all
213 tracked .graph.yaml files and recursively identifies effect records by
kind: template.compose. At framework commit containing the tool, it finds
zero such effect nodes. A tracked-text search independently finds no compose
occurrence in these files. Therefore the current checked-in YAML corpus does
not require rewriting compose declarations for this repair.
This scope excludes TypeScript-generated declarations, test fixture objects,
installed module data, downstream application repositories, and external
consumers. Existing normalization and dispatch fixtures explicitly use compose,
including a cascade referring to prior steps.7.ids; those tests must change
with the execution boundary. No universal absence or deployed-consumer claim
follows from this local inventory.