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.
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
| Term | Meaning |
|---|---|
| Backend service | One of the eight typed services that together comprise a GraphBackend; each handles a coherent slice of the RFC-0036 data model. |
| Composition contract | Rule that every GraphBackend is constructed from a Partial |
| Cursor | A pagination handle produced by query operations that may return multiple results; defined in @savvi-studio/pagination, opaque here. |
| GraphBackend | The 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-data | Pattern where queries are plain data values ({ type, …params }) executed via uniform read()/write() rather than per-query method calls. |
Diagnostics
| Code | Severity | Description |
|---|---|---|
M37010 | Error | Query type discriminant is not recognized by the target service |
M37011 | Error | Query parameters do not match the declared shape for the resolved query type |
M37020 | Error | Service operation is unsupported by this backend (default stub from createGraphBackend) |
M37021 | Error | Read-only service received a write() call |
M37030 | Error | PredicateService.GetId failed to resolve the predicate URI - predicate not registered |
M37040 | Error | Transaction is required for this write but no transaction is active (per-backend policy) |
M37041 | Error | Transaction commit failed; backend rolled back automatically |
M37050 | Warning | Pagination limit exceeds backend maximum; clamped silently |
M37060 | Error | RLS / tenant context required but not set; cross-tenant access blocked |
M37061 | Error | RLS / 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
- Every query service except TransactionService exposes exactly two methods, read() and write(); read-only services MUST throw M37020 from write(). (enforced by: runtime)
- Implementations MUST emit the same diagnostic codes for the same conditions; backends MUST NOT introduce private error semantics. (enforced by: runtime)
- In tenanted mode a session-bound tenant context MUST gate all reads and writes; cross-tenant access without escalation is impossible. (enforced by: RLS)
- Missing services are replaced by unsupported stubs; clients MUST tolerate M37020 rather than crash. (enforced by: runtime)
- PermissionService is read-only; permission grants are derived from policy declarations, not written directly. (enforced by: runtime)
- PredicateService is read-only at runtime; predicate creation belongs to the install engine (RFC-0041). (enforced by: install-time)
- Query-type discriminant values are stable across versions; renumbering is a breaking change. (enforced by: compile-time)
- StatementService.CreateMany MUST be transactional (all-or-none) and result order MUST match input order. (enforced by: runtime)
- 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
- 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
- MUST — Clients MUST surface the M37020 diagnostic to callers without retrying. (proof citation:
rfc0037_b7_grounded; verification pending) - MUST_NOT — Implementations MUST NOT create a GraphBackend directly; they construct services and pass them through createGraphBackend. (proof citation:
rfc0037_b9_grounded; verification pending) - MUST_NOT — Services MUST NOT communicate via side channels other than the shared transaction context. (proof citation:
rfc0037_b15_grounded; verification pending) - MUST — Services within a backend MUST share state coherently across resources, traversal, and other services within a transaction.
- 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
- MUST — Clients MUST tolerate M37020 from unsupported stub services rather than crash.
- MUST — Every query service except TransactionService exposes exactly read() and write(); read-only query services MUST throw M37020 from write().
- 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) - MUST — Writes within a transaction MUST commit atomically across all services.
Pagination
- MUST — Backends MUST advertise their default and maximum limit; clients MUST NOT assume a specific value.
Query-as-Data Pattern
- MUST — Discriminant values MUST be stable across versions of a backend implementation; renumbering is a breaking change. (proof citation:
rfc0037_b26_grounded; verification pending) - MUST — Read-only services MUST throw M37020 if write() is called. (proof citation:
rfc0037_b11_grounded; verification pending)
The Eight Services
- MUST — CreateMany MUST be transactional (all-or-none) and the result array MUST be in the same order as the input array.
- MAY — Implementations MAY accept additional ResourceQueryFilters fields; clients MUST tolerate unknown filters being ignored.
- MUST_NOT — Most backends MUST NOT expose execute(); it is reserved for the Postgres adapter and similar.
- MUST — PermissionCheckParams MUST supply either resourceKind or resourceType.
- MUST — Service calls within the same async context MUST observe the open transaction begun by begin().
- MUST — When merge:true, the implementation MUST deep-merge data into the existing record; otherwise data replaces it entirely.
- MUST — transaction(callback) implementations MUST ensure rollback on any thrown error from read()/write() methods.
Linked References
| Direction | Target |
|---|---|
| Depends on | RFC-0006 |
| Depends on | RFC-0007 |
| Depends on | RFC-0036 |
| Extended by | RFC-0038 |