gnomonlearn
Docs/Graph/RFC-0037

RFC-0037 · Graph Backend Services

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.

Status Draft corpus. Reference catalogs and RDF projections have generation drift checks; Gnomon proofs and projection semantics remain unverified for release.

View the generated reference catalog →

Read design questions and decisions →


Reference catalog: the diagnostics, linked-RFC graph, defined terms, and normative-rule index for this RFC are in the reference catalog, generated from the structured Lean module. This document carries the prose: design rationale, entity-shape definitions in context, and migration notes.


1. Purpose

A graph backend in Gnomon is not a single monolithic adapter. It is a composition of eight orthogonal service interfaces, each with a small, typed query surface. This RFC defines those service interfaces, the query-as-data pattern they share, the composition contract that builds a complete GraphBackend from a partial service map, and the obligations every implementation must satisfy.

This decomposition is the load-bearing substrate that makes the graph layer pluggable (Postgres, in-memory, custom KV) and selectively implementable (a backend that only needs resources + statements + transactions can stub the rest). Its service map and query-as-data convention derive from the legacy graph-backend-model; the legacy PostgreSQL and memory backends are migration baselines, not conformance evidence for every rule in this RFC.

This RFC defines the contract between the graph client (RFC-0038) and the storage substrate. It does not define the storage implementation itself.


2. Definitions

TermMeaning
Backend serviceOne of the eight typed services that together comprise a GraphBackend. Each service handles a coherent slice of the data model from RFC-0036.
Query-as-dataThe pattern where queries are plain data values ({ type: <enum>, ...params }) executed via a uniform read() / write() method, rather than method calls per query type.
Query definition (QueryDef)A type-level triple { type, params, result } enumerating the typed shape of one query.
GraphBackendThe composed eight-service interface that the graph client (RFC-0038) consumes.
Composition contractThe rule that every GraphBackend is constructed from a Partial<GraphServices> map, with missing services replaced by explicit unsupported stubs.
CursorA pagination handle produced by query operations that may return multiple results. Defined in @savvi-studio/pagination; exposed here as an opaque type.

3. Query-as-Data Pattern

3.1 The shape

Queries are plain data, not method calls. Every query has a numeric type discriminant and a typed parameter object. Every query has a typed result. The discriminant + parameters + result form a query definition:

BackendQueryDef<TType extends Integer, TParams, TResult> {
  type:    TType
  params:  TParams
  result:  TResult
}

A query value (what is passed to read() / write()) is the discriminant flattened with the parameters:

BackendQuery<TType, TParams> = { type: TType } & TParams

The result type is read off the query definition by the type system; at runtime the implementation is responsible for returning the correct shape.

3.2 The five common query definition shapes

The model defines five reusable QueryDef builders. Most service-specific queries fit one of these shapes:

BuilderParamsResult
GetQueryDef<TEnum, TEntity>{ id: bigint }TEntity | null
QueryQueryDef<TEnum, TEntity, TFilters>{ filters?: TFilters }Cursor<TEntity>
CreateQueryDef<TEnum, TInput>{ input: TInput }bigint (new entity id)
UpdateQueryDef<TEnum, TInput>{ id: bigint, input: TInput }boolean
DeleteQueryDef<TEnum>{ id: bigint }boolean

Service-specific queries that do not fit these shapes (e.g., GetByExternalId, Invalidate, Traverse) define their own params and result directly.

3.3 The two service methods

Every query service except TransactionService exposes exactly two methods:

BackendService<TReadQueryDefs, TWriteQueryDefs> {
  read(query: BackendQuery<...TReadQueryDefs>):  Promise<...TReadQueryDefs.result>
  write(query: BackendQuery<...TWriteQueryDefs>): Promise<...TWriteQueryDefs.result>
}

Read-only services declare TWriteQueryDefs = {} (an empty record) and MUST throw M37020 if write() is called.

3.4 Discriminant numbering convention

Each service’s read/write enums begin from CommonReadQueryType / CommonWriteQueryType (which reserve Get=0, Query=1, Create=0, Update=1, Delete=2) and extend from there. Custom queries take values 2+ (read) or 3+ (write).

Discriminant values MUST be stable across versions of a backend implementation. Renumbering is a breaking change.


4. The Eight Services

A complete GraphBackend is the composition:

GraphServices {
  resources:    ResourceService
  statements:   StatementService
  permissions:  PermissionService
  collections:  CollectionService
  traversal:    TraversalService
  predicates:   PredicateService
  workspace:    WorkspaceService
  transactions: TransactionService
}

GraphBackend = GraphServices

4.1 ResourceService

Read/write operations on Resources (RFC-0036 §4.1).

Read queries:

TypeParamsResult
Get{ id: bigint }Resource | null
GetByExternalId{ kind: string, externalId: string }Resource | null
Query{ filters?: ResourceQueryFilters }Cursor<Resource>

ResourceQueryFilters is paginationOptions extended with { kind?: string, externalId?: string }. Implementations MAY accept additional filter fields; clients MUST tolerate unknown filters being ignored.

Write queries:

TypeParamsResult
Create{ input: ResourceInput }bigint (new id)
Update{ id: bigint, input: ResourceUpdateInput }boolean
Delete{ id: bigint }boolean (soft delete)

ResourceUpdateInput is { data?: Map<String, Any>, merge?: boolean }. When merge: true, the implementation MUST deep-merge data into the existing record; when merge: false (default), data replaces the existing record’s data field entirely.

4.2 StatementService

Read/write operations on Statements (RFC-0036 §4.2).

Read queries:

TypeParamsResult
Get{ id: bigint }Statement | null
Query{ filters?: StatementQueryFilters }Cursor<Statement>

StatementQueryFilters extends pagination with { subjectId?, objectId?, predicateId?, predicate? }.

Write queries:

TypeParamsResult
Create{ input: StatementInput }bigint
CreateMany{ inputs: StatementInput[] }bigint[]
Update{ id: bigint, input: StatementUpdateInput }boolean
Invalidate{ id: bigint }boolean

Invalidate is distinct from Delete: it sets validTo = now() on the statement (closes the bitemporal interval) without soft-deleting the row. Use Delete (via the common pattern) only when the statement should be removed from the system-time axis as well.

CreateMany MUST be transactional: either all statements are created or none are. The result array MUST be in the same order as the input array.

4.3 PermissionService (read-only)

Permission evaluation queries. Authoritative — the cache (RFC-0036 §6.2) is consulted internally but the result reflects the post-cache effective permission.

Read queries:

TypeParamsResult
GetPermission{ params: PermissionCheckParams }PermissionResult
GetSubjectPermissions{ params: SubjectPermissionsParams }SubjectPermission[]

PermissionCheckParams:

PermissionCheckParams {
  subjectId:    bigint
  subjectType:  string
  resourceId:   bigint
  resourceKind: string?      // either resourceKind OR resourceType MUST be supplied
  resourceType: string?
}

SubjectPermissionsParams:

SubjectPermissionsParams {
  subjectId:           bigint
  subjectType:         string
  resourceKindFilter:  string?
  resourceTypeFilter:  string?
  minPermissionBits:   number?
}

PermissionResult is the bitmask value (number) representing the effective permission level of the subject on the resource. SubjectPermission is { resourceId, resourceKind?, resourceType, permissionBits, derivedFrom }.

This service has no write surface. Permissions are derived from policy declarations (RFC-0042); they are not directly written.

4.4 CollectionService

Operations on List and Set collections rooted at a Resource. Lists are ordered, Sets are unique.

Read queries:

TypeParamsResult
GetSize{ collectionId, collectionType }number
GetMembers{ collectionId, collectionType }bigint[]
GetItem{ listId, position }bigint | null
Contains{ setId, memberId }boolean

Write queries:

TypeParamsResult
Create{ collectionType, options? }bigint
Add{ collectionId, collectionType, memberId }boolean
Insert{ listId, memberId, position }boolean
Remove{ collectionId, collectionType, memberIdOrPosition }boolean
Clear{ collectionId, collectionType }boolean
Delete{ collectionId, collectionType }boolean

CollectionType is the enum 'list' | 'set'. Insert is List-only. Contains is Set-only.

4.5 TraversalService (read-only)

Graph walks from a starting Resource.

Read queries:

TypeParamsResult
GetOutgoing{ resourceId, predicatePattern? }TraversalEdge[]
GetIncoming{ resourceId, predicatePattern? }TraversalEdge[]
Traverse{ startId, options? }TraversalPath[]

predicatePattern is an ltree query (e.g., org.*, *.member). When omitted, all edges are returned.

TraverseOptions SHOULD include at least { maxDepth, predicatePattern, direction }. Implementations MAY accept additional options.

TraversalEdge is { from: bigint, to: bigint, predicate: string, predicateId: bigint, statementId: bigint }. from and to are the statement’s physical subject and object, even when the walk follows an incoming edge.

TraversalPath is { resourceId: bigint, resourceIds: bigint[], statementIds: bigint[], predicateIds: bigint[], edges: TraversalEdge[], length: number }. resourceId is the terminal resource. resourceIds starts with startId and lists resources in walk order. The other arrays and edges list hops in that same order: resourceIds.length = length + 1, and each edge array has length entries. Each statementIds[i] and predicateIds[i] equals the identity in edges[i]. Implementations MUST retain statement identity for parallel edges and MUST NOT infer edge identity from resource IDs alone.

direction is 'outgoing' | 'incoming' | 'both'. With both, each hop may follow either direction independently; each edge still reports its physical from and to endpoints. A path MUST NOT visit the same resource twice.

4.6 PredicateService (read-only)

Predicate id resolution.

Read queries:

TypeParamsResult
GetId{ predicateUri: string }bigint

predicateUri is the ltree path (e.g., org.member). The service throws M37030 if the predicate does not exist.

Predicate creation is the responsibility of the install engine (RFC-0041) and is not exposed as a runtime write.

4.7 WorkspaceService (read-only)

Read access to the resource membership of a workspace.

Read queries:

TypeParamsResult
GetResources{ filters?: WorkspaceQueryFilters }Cursor<WorkspaceEntity>
CountResources{ filters? }bigint
GetEntityById{ id: bigint }WorkspaceEntity | null
IsResourceInWorkspace{ resourceId: bigint }boolean

WorkspaceEntity is the projected view of a Resource within a Workspace, including workspace-derived permission bits. The shape is defined by RFC-0036 §6.1.

Workspace creation and tenant binding are out of scope for this service. RFC-0045 defines tenant-mode configuration and RFC-0051 defines PostgreSQL RLS binding; a complete cross-backend tenancy contract remains deferred.

4.8 TransactionService

Transaction lifecycle. Orthogonal to the other services — the same transaction scope MUST cover writes across all service instances.

TransactionService {
  begin():           Promise<TransactionId>
  commit(id?):       Promise<void>
  rollback(id?):     Promise<void>
  isInTransaction(): Promise<boolean>
  transaction<T>(callback: () => Promise<T>): Promise<T>
  execute?(sql, params?): Promise<unknown>   // optional escape hatch
  savepoint?(name: string): Promise<void>
  releaseSavepoint?(name: string): Promise<void>
  rollbackToSavepoint?(name: string): Promise<void>
}

begin() returns a TransactionId (string). Subsequent service calls within the same async context MUST observe the open transaction. commit(id?) / rollback(id?) close the transaction; the id arg disambiguates nested transactions if the backend supports savepoints.

transaction(callback) is the recommended high-level form: begin → run callback → commit on success, rollback on throw. Implementations MUST ensure rollback on any thrown error including those raised by service read() / write() methods.

The client composes these lifecycle operations through two distinct callback forms (RFC-0038 §3.4). GraphClient.transaction(callback) joins an active caller transaction. GraphClient.isolatedTransaction(callback) owns a transaction when none is active, or uses a savepoint within the caller’s transaction. The latter requires all three backend savepoint operations (savepoint, rollbackToSavepoint, and releaseSavepoint) when nested; it rejects before invoking the callback if any is unavailable. Backend lifecycle errors remain fatal and preserve their causes. The three optional savepoint operations already exist in the approved backend interface; their signatures above correct an omission in the earlier listing. Client composition does not add a backend operation or change the database isolation level.

execute() is an optional escape hatch for backends that expose a SQL or query-language surface. Most backends MUST NOT expose this; it is reserved for the Postgres adapter and similar.


5. Composition Contract

5.1 The factory

A GraphBackend is constructed from a Partial<GraphServices> map. Missing services are replaced with explicit unsupported stubs that throw M37020 on any call:

createGraphBackend(overrides: Partial<GraphServices>): GraphBackend

This is the canonical entry point. Implementations MUST NOT create a GraphBackend directly — they construct individual services and pass them through this factory, so unsupported operations always fail with the same diagnostic.

5.2 Selective implementation

A backend MAY implement only the services it can support. For example, a read-only mirror backend might implement only resources, statements, traversal, and predicates, leaving the rest as unsupported stubs. Clients (RFC-0038) MUST surface the M37020 diagnostic to callers without retrying.

5.3 Service independence

Services within a backend MUST share state coherently. A Resource created via resources.write({ type: Create, ... }) MUST be visible to a subsequent resources.read({ type: Get, id }) and to traversal.read({ type: GetOutgoing, resourceId: id }) once the enclosing transaction commits.

Services MUST NOT communicate via side channels other than the shared transaction context. A Postgres backend may share a connection pool; an in-memory backend may share a heap; the contract is the same: writes commit atomically across all services within a transaction.

5.4 Tenant scoping (RLS-style)

When the backend runs in tenanted mode, a session-bound tenant context MUST gate all reads and writes. The legacy Postgres backend implements this via PostgreSQL Row-Level Security:

setRlsSessionContext({ tenantId, principalId })
clearRlsSessionContext()

Backends that do not support RLS MUST simulate the behavior in application code: every query is filtered by the active tenant, every write is tagged with the tenant, and cross-tenant reads MUST be impossible without explicit privilege escalation. RFC-0045 defines the deployment tenant-mode setting and RFC-0051 defines PostgreSQL RLS binding; the complete cross-backend tenancy model remains deferred.


6. Pagination

Queries that return collections (QueryQueryDef, WorkspaceService.GetResources) return a Cursor<T> rather than a list. The cursor surface is:

Cursor<T> {
  items:     T[]
  nextCursor: string | null
  hasMore:    boolean
}

Subsequent pages are retrieved by passing the nextCursor value back in the filters.cursor field. paginationOptions (the base of every filter type) declares:

paginationOptions {
  cursor:  string?
  limit:   number?      // default and maximum are backend-defined
  orderBy: string?
}

Backends MUST advertise their default and maximum limit in implementation documentation; clients (RFC-0038) MUST NOT assume a specific value. The full cursor contract is defined in @savvi-studio/pagination and is opaque to this RFC.


7. Invariants

  1. Every query service except TransactionService exposes exactly two methods: read() and write(). Read-only query services MUST throw M37020 from write(). TransactionService exposes the lifecycle methods in §4.8 instead.
  2. Discriminant values for query types are stable; renumbering is a breaking change (§3.4).
  3. Writes within a transaction MUST commit atomically across all services (§5.3).
  4. Missing services are replaced by unsupported stubs; clients MUST tolerate M37020 rather than crash (§5.1).
  5. Implementations MUST emit the same diagnostic codes (§9) for the same conditions; backends MUST NOT introduce private error semantics for the operations defined here.
  6. CreateMany (StatementService) MUST be transactional and order-preserving (§4.2).
  7. The PermissionService is read-only; permission grants are derived from policy declarations, not written directly (§4.3).
  8. The PredicateService is read-only at runtime; predicate creation belongs to the install engine (§4.6).

8. Compatibility and Migration

8.1 From legacy graph-backend-model

This RFC maps the legacy service interfaces while specifying an expanded traversal result in §4.5:

Legacy fileThis RFC
services/resources.ts§4.1
services/statements.ts§4.2
services/permissions.ts§4.3
services/collections.ts§4.4
services/traversal.ts§4.5
services/predicates.ts§4.6
services/workspace.ts§4.7
types.ts (TransactionService)§4.8
factory.ts (createGraphBackend)§5.1

The legacy traversal path held only a terminal resource, depth, and resource-ID sequence. Section 4.5 requires ordered resource, Statement, Predicate, and edge identities. The Gnomon PostgreSQL adapter and shared graph model were changed to carry those identities. The memory backend remains a migration baseline; its conformance must be established against the service contract and is not inferred from the legacy implementation. Future backends (e.g., SQLite, DuckDB, distributed KV) implement the same eight interfaces.

8.2 Naming changes

The RFC retains the legacy service and query names. One terminological note: the legacy predicateUri parameter (PredicateService.GetId) is in fact an ltree path, not a URI. Implementations MAY accept either form (org.member or a CURIE like schema:memberOf); the canonical form is the ltree path.

8.3 Versioning

Backend services are versioned with the RFC. Breaking changes (renumbering discriminants, changing query result shapes, removing services) require a new RFC that supersedes this one. Additive changes (new query types within existing services, new optional filter fields) are non-breaking.


Diagnostics

The diagnostic catalog for this RFC is authored in the structured Lean module and rendered in reference catalog § Diagnostics. Inline mentions in the prose above (e.g., “rejected with MNNxxx”) cross-link to the catalog at render time.

Linked References

The cross-RFC dependency graph is rendered in reference catalog § Linked References. Out-of-KG pointers to legacy code or external resources, when present, remain in this document under “Source-tree references” below.