gnomonlearn
Docs/RFC-0037/Reference catalog

RFC-0037 · Reference catalog

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.

← Read the authored RFC

Generated reference catalog. This page renders structured Lean data for RFC-0037: defined terms, diagnostics, dependencies, and invariants. It does not establish proof coverage or runtime conformance. The authored narrative lives in RFC-0037.

This page is generated from the lean/Gnomon/Spec/ module for RFC-0037. Edit that source and regenerate this catalog.


Title: Graph Backend Services
Status: draft
Owners: Graph Platform, Storage
Diagnostic range: M37000-M37099

Depends on: RFC-0006, RFC-0007, RFC-0036
Extended by: RFC-0038

Proof citations in source: 8 / 8. Standalone proof verification is pending.


Definitions

TermMeaning
Backend serviceOne of the eight typed services that together comprise a GraphBackend; each handles a coherent slice of the RFC-0036 data model.
Composition contractRule that every GraphBackend is constructed from a Partial 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, opaque here.
GraphBackendThe composed eight-service interface that the graph client (RFC-0038) consumes.
Query definition (QueryDef)A type-level triple { type, params, result } enumerating the typed shape of one query.
Query-as-dataPattern where queries are plain data values ({ type, …params }) executed via uniform read()/write() rather than per-query method calls.

Diagnostics

CodeSeverityDescription
M37010ErrorQuery type discriminant is not recognized by the target service
M37011ErrorQuery parameters do not match the declared shape for the resolved query type
M37020ErrorService operation is unsupported by this backend (default stub from createGraphBackend)
M37021ErrorRead-only service received a write() call
M37030ErrorPredicateService.GetId failed to resolve the predicate URI - predicate not registered
M37040ErrorTransaction is required for this write but no transaction is active (per-backend policy)
M37041ErrorTransaction commit failed; backend rolled back automatically
M37050WarningPagination limit exceeds backend maximum; clamped silently
M37060ErrorRLS / tenant context required but not set; cross-tenant access blocked
M37061ErrorRLS / tenant context set but principal lacks privilege to read this tenant’s data

Dependency neighborhood

graph LR
  nRFC_0037["RFC-0037"]
  nRFC_0006["RFC-0006"]
  nRFC_0037 --> nRFC_0006
  nRFC_0007["RFC-0007"]
  nRFC_0037 --> nRFC_0007
  nRFC_0036["RFC-0036"]
  nRFC_0037 --> nRFC_0036
  nRFC_0038["RFC-0038"]
  nRFC_0038 --> nRFC_0037

Invariants

  1. Every query service except TransactionService exposes exactly two methods, read() and write(); read-only services MUST throw M37020 from write(). (enforced by: runtime)
  2. Implementations MUST emit the same diagnostic codes for the same conditions; backends MUST NOT introduce private error semantics. (enforced by: runtime)
  3. In tenanted mode a session-bound tenant context MUST gate all reads and writes; cross-tenant access without escalation is impossible. (enforced by: RLS)
  4. Missing services are replaced by unsupported stubs; clients MUST tolerate M37020 rather than crash. (enforced by: runtime)
  5. PermissionService is read-only; permission grants are derived from policy declarations, not written directly. (enforced by: runtime)
  6. PredicateService is read-only at runtime; predicate creation belongs to the install engine (RFC-0041). (enforced by: install-time)
  7. Query-type discriminant values are stable across versions; renumbering is a breaking change. (enforced by: compile-time)
  8. StatementService.CreateMany MUST be transactional (all-or-none) and result order MUST match input order. (enforced by: runtime)
  9. Writes within a transaction MUST commit atomically across all services in the GraphBackend. (enforced by: runtime)

Normative Statements

Statements are structured source data. Proof citations, where present, have not passed a standalone Gnomon proof gate.

Compatibility and Migration

  1. MAY — Implementations MAY accept either ltree path or CURIE form for predicateUri; the canonical form is the ltree path. (proof citation: rfc0037_b20_grounded; verification pending)

Composition Contract

  1. MUST — Clients MUST surface the M37020 diagnostic to callers without retrying. (proof citation: rfc0037_b7_grounded; verification pending)
  2. MUST_NOT — Implementations MUST NOT create a GraphBackend directly; they construct services and pass them through createGraphBackend. (proof citation: rfc0037_b9_grounded; verification pending)
  3. MUST_NOT — Services MUST NOT communicate via side channels other than the shared transaction context. (proof citation: rfc0037_b15_grounded; verification pending)
  4. MUST — Services within a backend MUST share state coherently across resources, traversal, and other services within a transaction.
  5. MUST — When tenanted, a session-bound tenant context MUST gate all reads and writes; cross-tenant reads MUST be impossible without explicit privilege escalation. (proof citation: rfc0037_b24_grounded; verification pending)

Invariants

  1. MUST — Clients MUST tolerate M37020 from unsupported stub services rather than crash.
  2. MUST — Every query service except TransactionService exposes exactly read() and write(); read-only query services MUST throw M37020 from write().
  3. MUST — Implementations MUST emit the same diagnostic codes for the same conditions and MUST NOT introduce private error semantics. (proof citation: rfc0037_b2_grounded; verification pending)
  4. MUST — Writes within a transaction MUST commit atomically across all services.

Pagination

  1. MUST — Backends MUST advertise their default and maximum limit; clients MUST NOT assume a specific value.

Query-as-Data Pattern

  1. MUST — Discriminant values MUST be stable across versions of a backend implementation; renumbering is a breaking change. (proof citation: rfc0037_b26_grounded; verification pending)
  2. MUST — Read-only services MUST throw M37020 if write() is called. (proof citation: rfc0037_b11_grounded; verification pending)

The Eight Services

  1. MUST — CreateMany MUST be transactional (all-or-none) and the result array MUST be in the same order as the input array.
  2. MAY — Implementations MAY accept additional ResourceQueryFilters fields; clients MUST tolerate unknown filters being ignored.
  3. MUST_NOT — Most backends MUST NOT expose execute(); it is reserved for the Postgres adapter and similar.
  4. MUST — PermissionCheckParams MUST supply either resourceKind or resourceType.
  5. MUST — Service calls within the same async context MUST observe the open transaction begun by begin().
  6. MUST — When merge:true, the implementation MUST deep-merge data into the existing record; otherwise data replaces it entirely.
  7. MUST — transaction(callback) implementations MUST ensure rollback on any thrown error from read()/write() methods.

Linked References

DirectionTarget
Depends onRFC-0006
Depends onRFC-0007
Depends onRFC-0036
Extended byRFC-0038