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
| Term | Meaning |
|---|---|
| Backend service | One 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-data | The 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. |
| GraphBackend | The composed eight-service interface that the graph client (RFC-0038) consumes. |
| Composition contract | The rule that every GraphBackend is constructed from a Partial<GraphServices> map, with missing services replaced by explicit unsupported stubs. |
| Cursor | A 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:
| Builder | Params | Result |
|---|---|---|
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:
| Type | Params | Result |
|---|---|---|
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:
| Type | Params | Result |
|---|---|---|
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:
| Type | Params | Result |
|---|---|---|
Get | { id: bigint } | Statement | null |
Query | { filters?: StatementQueryFilters } | Cursor<Statement> |
StatementQueryFilters extends pagination with { subjectId?, objectId?, predicateId?, predicate? }.
Write queries:
| Type | Params | Result |
|---|---|---|
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:
| Type | Params | Result |
|---|---|---|
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:
| Type | Params | Result |
|---|---|---|
GetSize | { collectionId, collectionType } | number |
GetMembers | { collectionId, collectionType } | bigint[] |
GetItem | { listId, position } | bigint | null |
Contains | { setId, memberId } | boolean |
Write queries:
| Type | Params | Result |
|---|---|---|
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:
| Type | Params | Result |
|---|---|---|
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:
| Type | Params | Result |
|---|---|---|
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:
| Type | Params | Result |
|---|---|---|
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
- Every query service except
TransactionServiceexposes exactly two methods:read()andwrite(). Read-only query services MUST throw M37020 fromwrite().TransactionServiceexposes the lifecycle methods in §4.8 instead. - Discriminant values for query types are stable; renumbering is a breaking change (§3.4).
- Writes within a transaction MUST commit atomically across all services (§5.3).
- Missing services are replaced by unsupported stubs; clients MUST tolerate M37020 rather than crash (§5.1).
- Implementations MUST emit the same diagnostic codes (§9) for the same conditions; backends MUST NOT introduce private error semantics for the operations defined here.
CreateMany(StatementService) MUST be transactional and order-preserving (§4.2).- The PermissionService is read-only; permission grants are derived from policy declarations, not written directly (§4.3).
- 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 file | This 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.