RFC-0038 · 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-0038: defined terms, diagnostics, dependencies, and invariants. It does not establish proof coverage or runtime conformance. The authored narrative lives in
RFC-0038.This page is generated from the
lean/Gnomon/Spec/module for RFC-0038. Edit that source and regenerate this catalog.
Title: Graph Client
Status: draft
Owners: DX, Graph Platform
Diagnostic range: M38000-M38099
Depends on: RFC-0006, RFC-0007, RFC-0036, RFC-0037
Extended by: RFC-0039, RFC-0043
Proof citations in source: 13 / 13. Standalone proof verification is pending.
Definitions
| Term | Meaning |
|---|---|
| Batch operation | A bulk write that creates many entities through a single backend round-trip. |
| GraphClient | The composed readonly client. Carries no transaction; reads observe last-committed state. |
| GraphContext | The bundle of { backend, session } passed to every query implementation. |
| Query builder | The fluent API surface for composing multi-step traversal queries. |
| Query namespace | One of resources, statements, lists, sets, permissions, workspace. |
| TransactionalGraphClient | The composed write-capable client. Bound to a single open transaction; reads observe in-transaction state. |
Diagnostics
| Code | Severity | Description |
|---|---|---|
M38010 | Error | graphClientBuilder().build() called without a backend |
M38020 | Warning | Cursor.toArray() or GraphQueryBuilder.fetchAll() called on a result set exceeding the safety limit (default 10 000); consumer should use streaming iteration |
M38030 | Error | Continuation token failed HMAC validation — tampered or signed with a rotated key |
M38040 | Error | Anonymous read attempted on an API surface that requires authentication |
M38041 | Error | Anonymous write attempted; the transactional client requires a session |
M38050 | Error | Identity merge conflict on getByExternalId upsert (RFC-0007 §7.6) |
M38060 | Error | Transactional client used outside its transaction(callback) or isolatedTransaction(callback) scope |
M38061 | Error | transaction() callback completed with an in-flight error not propagated to the client; backend was rolled back |
M38070 | Warning | Backend service returned M37020 (unsupported) for a query the client surface advertises; client surface advertises features the backend does not implement |
M38080 | Error | Audit emission failed; the operation was committed but its audit record was not written — runtime MUST escalate per RFC-0047 |
Dependency neighborhood
graph LR
nRFC_0038["RFC-0038"]
nRFC_0006["RFC-0006"]
nRFC_0038 --> nRFC_0006
nRFC_0007["RFC-0007"]
nRFC_0038 --> nRFC_0007
nRFC_0036["RFC-0036"]
nRFC_0038 --> nRFC_0036
nRFC_0037["RFC-0037"]
nRFC_0038 --> nRFC_0037
nRFC_0039["RFC-0039"]
nRFC_0039 --> nRFC_0038
nRFC_0043["RFC-0043"]
nRFC_0043 --> nRFC_0038
Invariants
- Audit emission for every install is mandatory and may not be suppressed by the module being installed. (enforced by: runtime)
- Audit emission for transactional writes is mandatory and must not be suppressible. (enforced by: runtime)
- Batch operations are transactional by default; partial success requires explicit continueOnError opt-in. (enforced by: runtime)
- Continuation tokens must be HMAC-validated and rejected with M38030 when tampered. (enforced by: runtime)
- Every read must observe the active session’s tenant binding before executing. (enforced by: runtime)
- Every write must attach the active principal as creatorId on new entities. (enforced by: runtime)
- GraphSet.add must be idempotent; repeated adds of the same member must not duplicate membership. (enforced by: runtime)
- Implementations must silently tolerate unknown filter keys rather than throwing, for forward compatibility. (enforced by: runtime)
- PermissionQueries is read-only and post-evaluation; permission writes must go through predicate-policy declarations. (enforced by: compile-time)
- Re-entrant transaction calls participate in the existing transaction and must not begin a nested one. (enforced by: runtime)
- The GraphClient may only be constructed via graphClientBuilder or GraphClient.create; direct construction is forbidden. (enforced by: compile-time)
- The TransactionalGraphClient exists only inside its transaction callback; escaped references are invalid. (enforced by: runtime)
- The client surface defaults update() merge to true, inverting the backend default for safety. (enforced by: compile-time)
Normative Statements
Statements are structured source data. Proof citations, where present, have not passed a standalone Gnomon proof gate.
Batch Operations
- MUST — Callers needing failed batch items must use the lower-level batch primitive directly.
- MUST — When continueOnError is false (default), the entire batch is transactional — all inputs succeed or none do.
Client Composition
- MUST_NOT — A re-entrant transaction() call inside an existing transaction issues an additional begin()/commit(); the outer transaction owns the lifecycle.
- MUST — Backends reject all writes from an unauthenticated (sessionless) client. (proof citation:
rfc0038_b33_grounded; verification pending) - MUST — Implementations propagate the session into the backend’s tenant context before executing any read or write. (proof citation:
rfc0038_b9_grounded; verification pending) - MUST — The builder throws at build() time if backend is unset (M38010). (proof citation:
rfc0038_b1_grounded; verification pending) - MUST_NOT — TransactionalGraphClient is never directly constructible by application code; it exists only inside a transaction() or isolatedTransaction() callback.
Compatibility and Migration
- MUST — Backends without audit infrastructure install a logging stub before going live.
Invariants
- MUST — Every read observes the active session’s tenant binding. (proof citation:
rfc0038_b25_grounded; verification pending) - MUST — Every write attaches the active principal as creatorId. (proof citation:
rfc0038_b12_grounded; verification pending) - MUST_NOT — Re-entrant transaction() calls begin a nested transaction; they participate in the existing one.
- MUST — The client is constructed only via the builder or GraphClient.create(context); direct construction is not permitted.
- MUST — Writes go through policy declarations (RFC-0042), not directly through the PermissionQueries namespace. (proof citation:
rfc0038_b16_grounded; verification pending)
Pagination
- MUST — Continuation tokens are treated as short-lived (default 1 hour).
- MUST — Cursor.toArray() throws or warns (M38020) when the result set exceeds the implementation-defined safety limit (default 10 000).
- MUST — Implementations tolerate unknown filter keys silently for forward compatibility and do not throw.
- MUST — The client verifies the HMAC before honoring a continuation token; tampered or expired tokens are rejected with M38030.
Query Builder
- MUST — The builder is a thin wrapper over TraversalService and ResourceService and preserves observable semantics; implementations may optimize execution.
- MUST — fetchAll() emits M38020 (warning) for results larger than the safety limit. (proof citation:
rfc0038_b30_grounded; verification pending)
Query Surfaces
- MUST — Set.add() is idempotent: calling add(m) twice does not result in duplicate membership.
- MUST_NOT — The client caches permission results across calls; backend PermissionCache handles caching. (proof citation:
rfc0038_b3_grounded; verification pending)
Session and Tenant Context
- MUST — Anonymous queries throw M38040 unless both the API surface and backend tenant policy permit them. (proof citation:
rfc0038_b37_grounded; verification pending) - MUST — Every write through the transactional client produces an audit log entry capturing operation, principal, tenant, entity, action, hashes, and correlation id. (proof citation:
rfc0038_b21_grounded; verification pending) - MUST — On every query the client sets the backend tenant context, attaches principal id as creatorId on writes, and clears tenant context on transaction end. (proof citation:
rfc0038_b14_grounded; verification pending) - MUST_NOT — The client permits suppression of audit emission. (proof citation:
rfc0038_b27_grounded; verification pending) - MUST — The client surfaces merge-conflict errors as M38050 and does not silently overwrite a Resource merged from a different external system. (proof citation:
rfc0038_b5_grounded; verification pending)
Linked References
| Direction | Target |
|---|---|
| Depends on | RFC-0006 |
| Depends on | RFC-0007 |
| Depends on | RFC-0036 |
| Depends on | RFC-0037 |
| Extended by | RFC-0039 |
| Extended by | RFC-0043 |