gnomonlearn
Docs/RFC-0037 backend services and RDF identity proposal

RFC-0037 backend services and RDF identity 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: source-bound domain review and first-release model proposal, 2026-10-03. Owners: Graph Platform, Storage, and spec. No Gnomon system is deployed, so this is a prepublication contract correction rather than a live data migration.

Source boundary

RFC-0037 defines an in-process backend interface consumed by the graph client: eight required services, typed query definitions, service methods, transaction scope, and M37020 unsupported-service behavior. These are framework/backend API concepts. They are not declarations an application author can write in Gnomon source, Gnomon operation effects, or values in RFC-0006’s authoring type system. The current ontology uses NamedDeclaration, DeclarationKind, EffectKind, Operation, and DataType for those different authoring concepts, so the inherited RDF projection conflates the two layers.

All 90 domain nodes were compared with the authored RFC and Lean catalog. The nine invariant nodes reflect stated RFC-0037 rules. The other 81 nodes have accurate descriptions of backend concepts but incorrect authoring-class identities: 13 declarations, nine effects, 31 operations, and 28 types. The source-bound ledger records a finding for each node. No source RDF node or IRI changed during this review.

Proposed model and implementation reconciliation

Add explicit backend API classes under DomainEntity, such as GraphBackendService, GraphBackendQuery, GraphBackendMethod, GraphBackendQueryType, and GraphBackendEffect. Reserve existing authoring classes for compiler-visible Gnomon declarations, effects, operations, and Values. Give each backend concept its own typed IRI and retain a documented old-to-new IRI map before first publication. Align RFC-0036 storage-shape classes in the same change, since query input/result types depend on them.

The gnomon framework’s graph-backend-model currently contains an optional policies service and transaction savepoint hooks beyond the eight-service prose; its resource service also includes CreateMany. Decide whether each is an extension or part of the first-release normative surface, then align prose, Lean, RDF, types, and tests. The prose’s claim that the inherited Postgres and memory implementations need no behavior change requires fresh conformance evidence. The separate graph repository’s savvifi.graph.v1 gRPC contract is a cross-process wire boundary, not this in-process service interface.

RFC-0037 already requires M37020 for absent services. Framework commit a8896ce32 gives unsupported factory stubs a typed error with that code and the service name. Focused Node checks passed for read, write, and transaction stubs. On 2026-10-03, five focused graph suites passed 59 tests under a temporary Vitest source resolver with a minimal graph-model shim; this includes the backend factory tests. Generated DB schemas and the published build graph remain unverified by that run.

Framework 35b551605 added serial state rollback for object-store Statement CreateMany; f399f8420 added the corresponding Resource CreateMany path and transactional client batch surface. Six focused suites now pass 65 tests under the same temporary resolver and shim. This does not prove concurrent object-store atomicity or published-artifact compatibility.

RFC-0037’s edge-rich traversal result and page-shaped Cursor also conflict with the current backend types, SQL result, and RFC-0038 cursor object. The first-release reconciliation is proposed in RFC0038_QUERY_PAGINATION_PROPOSAL.md.

Acceptance

  1. Choose and document backend RDF classes together with RFC-0036, then align the ontology, RFC prose, Lean, protobuf projection sources, generated Turtle, and all RDF consumers. Rebind source-bound reviews after the correction.
  2. Decide and test the eight required services and optional extension surface, query discriminants, transaction/savepoint semantics, tenant context, and M37020/M37030 diagnostics against each backend and graph client.
  3. Keep runtime TypeScript shapes for purely in-process values; define a versioned .proto for any DTO that crosses a process, language, file, or stage boundary unless an established schema layer already owns it. Verify the separate savvifi.graph.v1 wire descriptor and archive pin.