RFC-0038 graph client 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.
Current status — October 18, 2026
The M38060 callback-lifetime subcheck passed at Gnomon
355de169faa945592161ecf684082356872a2083. The ordinary Roma
//graph/tests/graph-client:test_node target passed eight files and 42 tests,
including fifteen lifetime cases. Independent acceptance d5d522/0 joins
6,374 unchanged product rows and true source/tool guards in the
actual client evidence (Gnomon source: gnomon/tools/roma/evidence/graph-client-callback-lifetime-20261017/README.md; public archive link pending).
Both transaction and isolatedTransaction permanently close each callback’s
client, retained query/batch/permission/SQL/savepoint capabilities, cursors,
streams and iterators when that callback settles. Escaped operations report
M38060 before backend dispatch; later callbacks cannot revive them, and closing
a child does not close its outer callback. Materialized data remains ordinary
data. Frozen custom receivers and frozen exposed capabilities are covered.
The ordinary engine consumer target also passed 29 files and 245 tests at
87b77a0d41341b03db322e06f7559940806e02c9, with independent acceptance
511d02/0, 6,374 unchanged product rows and true source/tool guards; see the
scoped consumer evidence (Gnomon source: gnomon/tools/roma/evidence/rfc0041-planning-diagnostics-20261017/README.md; public archive link pending).
The first client attempt (Gnomon source: gnomon/tools/roma/evidence/graph-client-callback-lifetime-first-failure-20261017/README.md; public archive link pending)
remains a compile failure before tests. This closes the tested lifetime
subcheck only. M38061 error-propagation semantics, concurrent transaction isolation,
authenticated tenant/creator/audit behavior, all custom-facade compilation,
portable backend behavior and full published integration remain open.
A later real-PostgreSQL sentinel run at Gnomon
3d83cc412d4a68e46db311ba21de300a54c584bc confirms an outcome-reporting
counterexample. The existing Roma
//runtime/tests/completeness:test_pg_transaction_boundary target finishes
with the original five cases passing and the new sixth case failing
(e34a71/session41329 → cf0be4/1, Roma child 22932). The callback catches
real SQLSTATE 22012 from division by zero and fulfills. Before line 235
fails on expected rejected, received fulfilled, the test confirms that an
independent observer and the same writer see the earlier SQL write rolled
back, then successfully commits a fresh transaction through the same
backend/writer. The later assertion for an M38061 error is not reached;
the raw pg COMMIT command tag is not exposed or directly observed by this test.
Independent e671ab/0 joins all 265 artifact bindings and 6,373 unchanged
product records; 52c372/0 confirms recorded process/group and endpoint
closure. The counterexample archive (Gnomon source: gnomon/tools/roma/evidence/pg-commit-outcome-first-failure-20261017/README.md; public archive link pending)
is committed at c103e3f0674350c96285e13083479ad5e785e303. The earlier
five-case acceptance retains its tested revision and sentinel-SQL scope;
it does not cover this caught-error/fulfilled-callback outcome.
The private five-file repair (local review proposal: .work/pg-commit-outcome-repair-proposal-v1-20261017/README.md; not published; availability pending)
proposes forwarding optional actual-driver QueryResult.command metadata and
detecting only an actual COMMIT-to-ROLLBACK result, with truthful transaction
depth and cleanup tied to that confirmed terminal outcome. The additive public metadata field remains unselected. A separate official
adapter-local M38061 repair is adopted and runtime-verified on October 18, 2026
at Gnomon 897cb3902f385fd1d0c4903cffaae6046b810f85. It inspects the actual
native COMMIT-to-ROLLBACK result before projection, without adding public
query-result metadata. The existing //db/tests/db-postgres:test_node target
passes all 17 cases (5f68b6/0, independent cf0ab6/0); its database/config
dependencies are mocked. The unchanged
//runtime/tests/completeness:test_pg_transaction_boundary target passes all
six cases against fresh PostgreSQL 16.15 (965187/0, independent 98c573/0).
The sixth now rejects with M38061 after the fulfilled callback catches SQLSTATE
22012; observer/writer rollback and same-writer clean reuse also pass. The
other cases retain commit visibility, callback rollback, caller savepoints,
caller rollback and deferred-constraint COMMIT failure/recovery. The test does
not expose the raw native COMMIT command tag. Each accepted run preserves all
6,384 product records and source/tool guards; the real-PG fixture’s observed
registered processes and endpoints close.
Tracked Gnomon evidence, with public archive availability pending:
gnomon/tools/roma/evidence/pg-commit-outcome-db-first-failure-20261017/README.mdretains the original 14-pass/three-failure package attempt.gnomon/tools/roma/evidence/pg-commit-outcome-db-20261018/README.mdretains the 17-case package pass.gnomon/tools/roma/evidence/pg-commit-outcome-20261018/README.mdretains the six-case sentinel-SQL pass.
These results establish the tested official-adapter/API SQL boundaries, not
full PostgreSQL Graph module/service behavior or arbitrary custom-query-client
conformance. No blanket rule for all caught errors or pending operations is
selected. Full PostgreSQL module-resource persistence,
registry/audit/activation, concurrency, proof/formal release and published
integration remain open. Separately tested Site
c029b86d6a77cbe94891a83991916fefa396ed9c consumes Spec
dd6620275d5f6e4a797535cc31732a27e9c2db2f: corrected build 6d87e0/0,
independent 064078/0, emits 395 HTML pages including 209 evidence pages and
passes the existing route checks. The initial a0dc86/1 five-link failure is
preserved before the finite source-link repair. This source-status refresh is
not another Site build, browser acceptance or publication.
Historical source review — October 3, 2026
Status: source-bound domain review and first-release conformance proposal, 2026-10-03. Owners: Graph Platform, DX, Storage, and spec. No Gnomon system is deployed, so no live client migration is required.
Source and projection boundary
RFC-0038 describes the in-process graph client API over RFC-0037 backend services. Its query namespaces, builder, cursor, options, batch helpers, methods, and input/result shapes are framework API constructs. They are not Gnomon source declarations, declaration fields, operations, or Values. The inherited RDF source assigns those authoring classes to 61 of 73 domain nodes: 17 declarations, 11 fields, 17 operations, and 16 types. Its 12 invariant nodes agree with authored statements. Every node has a source-bound verdict in the projection ledger. No RDF triple or subject IRI changed during this review.
Model RFC-0038 alongside RFC-0036/0037 with explicit client API classes under
DomainEntity, retaining the authoring classes only for compiler-visible
Gnomon constructs. Define old-to-new IRI mappings before publication and
update the ontology, prose, Lean, source protobuf projections, generated
Turtle, and consumers together.
Conformance gaps found in the framework checkout
| Authored contract | Current framework source | Release consequence |
|---|---|---|
§6: GraphQueryBuilder.execute returns a streaming cursor and fetchAll materializes it. | graph/packages/graph-client/queries/builder.ts throws “not yet implemented” in both methods. | Public builder examples cannot execute. |
§3/§6: client.query() exposes an executable fluent builder. | graph/packages/graph-client/index.ts still has no query() member, and the builder’s execute methods throw. | The documented query surface cannot be called as written. |
§7: transactional client.batch is atomic by default, with explicit continueOnError for partial success and chunkSize options. | Framework f399f8420 now exposes client.batch only inside a transaction. Default calls use one CreateMany, chunked calls require savepoints, and partial mode is explicit. The older lower-level helpers retain their separate batchSize/useTransaction API. | Verify each backend’s bulk atomicity and transaction scope, especially concurrent object-store writes and callback errors. |
§8: every query propagates the session’s tenant context; writes add creatorId, and every write emits audit evidence. | GraphClient stores session, while its shown query and transaction paths dispatch to backend methods without an explicit context-binding or audit layer. | Tenant, creator, and audit requirements need backend-specific proof or implementation before release. |
| §3.3: missing backend emits M38010. | Builder previously threw a plain error. | Framework commit 00c0a5fbc now exposes a typed M38010 error and adds client diagnostic tests. |
The inherited prose claims both client variants already satisfy the RFC. That claim requires correction or conformance evidence from the current tree; the listed gaps contradict it. The query builder and batch behavior should be implemented to the authored first-release contract, with tests that exercise all backend variants. If the owner chooses a smaller first-release surface, the normative RFC, Lean, RDF, site, and examples must change together and label deferred features plainly.
The traversal result, Cursor/CursorPage, and HMAC-token conflicts that block an honest query-builder implementation are detailed in RFC0038_QUERY_PAGINATION_PROPOSAL.md.
Framework commit c181d0e15 narrowed the bulk fallback: a failed
CreateMany now propagates unless the backend explicitly reports an unknown
query type. Focused tests assert no per-item retry after a real bulk failure.
The lower-level unsupported-query fallback can still return partial successes;
the new transactional client.batch no longer uses that fallback by default.
The object-store backend now supports Resource CreateMany with the same
serial state rollback approach as Statement CreateMany. On 2026-10-03, six
focused graph suites passed 65 tests using a temporary Vitest source resolver
and minimal graph-model shim. TypeScript checks of the graph-client and
object-store packages reported only absent generated DB schema/binding
modules. The published build graph and concurrent write behavior were not
covered by those checks.
Acceptance
- Make
client.query()and transaction-scopedclient.batchexecutable or explicitly revise the normative surface. Verify cursor continuation, HMAC validation, safety limits, and builder traversal semantics end to end. - Test batch success, unsupported bulk rejection, a bulk failure after
partial work, explicit per-item partial mode, callback progress, rollback,
and ordered results on each backend. A default batch failure must leave no
writes;
continueOnErrormust be the only partial-success path on the transactional client. Verify chunked savepoints and concurrent writes. - Verify authenticated, anonymous, and cross-tenant reads/writes, creator attribution, audit emission, and client lifetime after a transaction ends.
- Run client and backend tests in a reproducible dependency environment, then integrated cross-repository graph tests. Rebind the projection ledger after any normative source or RDF correction.