gnomonlearn
Docs/RFC-0038 graph client contract proposal

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.md retains the original 14-pass/three-failure package attempt.
  • gnomon/tools/roma/evidence/pg-commit-outcome-db-20261018/README.md retains the 17-case package pass.
  • gnomon/tools/roma/evidence/pg-commit-outcome-20261018/README.md retains 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 contractCurrent framework sourceRelease 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

  1. Make client.query() and transaction-scoped client.batch executable or explicitly revise the normative surface. Verify cursor continuation, HMAC validation, safety limits, and builder traversal semantics end to end.
  2. 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; continueOnError must be the only partial-success path on the transactional client. Verify chunked savepoints and concurrent writes.
  3. Verify authenticated, anonymous, and cross-tenant reads/writes, creator attribution, audit emission, and client lifetime after a transaction ends.
  4. 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.