gnomonlearn
Docs/RFC-0038/Reference catalog

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.

← Read the authored RFC

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

TermMeaning
Batch operationA bulk write that creates many entities through a single backend round-trip.
GraphClientThe composed readonly client. Carries no transaction; reads observe last-committed state.
GraphContextThe bundle of { backend, session } passed to every query implementation.
Query builderThe fluent API surface for composing multi-step traversal queries.
Query namespaceOne of resources, statements, lists, sets, permissions, workspace.
TransactionalGraphClientThe composed write-capable client. Bound to a single open transaction; reads observe in-transaction state.

Diagnostics

CodeSeverityDescription
M38010ErrorgraphClientBuilder().build() called without a backend
M38020WarningCursor.toArray() or GraphQueryBuilder.fetchAll() called on a result set exceeding the safety limit (default 10 000); consumer should use streaming iteration
M38030ErrorContinuation token failed HMAC validation — tampered or signed with a rotated key
M38040ErrorAnonymous read attempted on an API surface that requires authentication
M38041ErrorAnonymous write attempted; the transactional client requires a session
M38050ErrorIdentity merge conflict on getByExternalId upsert (RFC-0007 §7.6)
M38060ErrorTransactional client used outside its transaction(callback) or isolatedTransaction(callback) scope
M38061Errortransaction() callback completed with an in-flight error not propagated to the client; backend was rolled back
M38070WarningBackend service returned M37020 (unsupported) for a query the client surface advertises; client surface advertises features the backend does not implement
M38080ErrorAudit 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

  1. Audit emission for every install is mandatory and may not be suppressed by the module being installed. (enforced by: runtime)
  2. Audit emission for transactional writes is mandatory and must not be suppressible. (enforced by: runtime)
  3. Batch operations are transactional by default; partial success requires explicit continueOnError opt-in. (enforced by: runtime)
  4. Continuation tokens must be HMAC-validated and rejected with M38030 when tampered. (enforced by: runtime)
  5. Every read must observe the active session’s tenant binding before executing. (enforced by: runtime)
  6. Every write must attach the active principal as creatorId on new entities. (enforced by: runtime)
  7. GraphSet.add must be idempotent; repeated adds of the same member must not duplicate membership. (enforced by: runtime)
  8. Implementations must silently tolerate unknown filter keys rather than throwing, for forward compatibility. (enforced by: runtime)
  9. PermissionQueries is read-only and post-evaluation; permission writes must go through predicate-policy declarations. (enforced by: compile-time)
  10. Re-entrant transaction calls participate in the existing transaction and must not begin a nested one. (enforced by: runtime)
  11. The GraphClient may only be constructed via graphClientBuilder or GraphClient.create; direct construction is forbidden. (enforced by: compile-time)
  12. The TransactionalGraphClient exists only inside its transaction callback; escaped references are invalid. (enforced by: runtime)
  13. 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

  1. MUST — Callers needing failed batch items must use the lower-level batch primitive directly.
  2. MUST — When continueOnError is false (default), the entire batch is transactional — all inputs succeed or none do.

Client Composition

  1. MUST_NOT — A re-entrant transaction() call inside an existing transaction issues an additional begin()/commit(); the outer transaction owns the lifecycle.
  2. MUST — Backends reject all writes from an unauthenticated (sessionless) client. (proof citation: rfc0038_b33_grounded; verification pending)
  3. MUST — Implementations propagate the session into the backend’s tenant context before executing any read or write. (proof citation: rfc0038_b9_grounded; verification pending)
  4. MUST — The builder throws at build() time if backend is unset (M38010). (proof citation: rfc0038_b1_grounded; verification pending)
  5. MUST_NOT — TransactionalGraphClient is never directly constructible by application code; it exists only inside a transaction() or isolatedTransaction() callback.

Compatibility and Migration

  1. MUST — Backends without audit infrastructure install a logging stub before going live.

Invariants

  1. MUST — Every read observes the active session’s tenant binding. (proof citation: rfc0038_b25_grounded; verification pending)
  2. MUST — Every write attaches the active principal as creatorId. (proof citation: rfc0038_b12_grounded; verification pending)
  3. MUST_NOT — Re-entrant transaction() calls begin a nested transaction; they participate in the existing one.
  4. MUST — The client is constructed only via the builder or GraphClient.create(context); direct construction is not permitted.
  5. MUST — Writes go through policy declarations (RFC-0042), not directly through the PermissionQueries namespace. (proof citation: rfc0038_b16_grounded; verification pending)

Pagination

  1. MUST — Continuation tokens are treated as short-lived (default 1 hour).
  2. MUST — Cursor.toArray() throws or warns (M38020) when the result set exceeds the implementation-defined safety limit (default 10 000).
  3. MUST — Implementations tolerate unknown filter keys silently for forward compatibility and do not throw.
  4. MUST — The client verifies the HMAC before honoring a continuation token; tampered or expired tokens are rejected with M38030.

Query Builder

  1. MUST — The builder is a thin wrapper over TraversalService and ResourceService and preserves observable semantics; implementations may optimize execution.
  2. MUST — fetchAll() emits M38020 (warning) for results larger than the safety limit. (proof citation: rfc0038_b30_grounded; verification pending)

Query Surfaces

  1. MUST — Set.add() is idempotent: calling add(m) twice does not result in duplicate membership.
  2. MUST_NOT — The client caches permission results across calls; backend PermissionCache handles caching. (proof citation: rfc0038_b3_grounded; verification pending)

Session and Tenant Context

  1. MUST — Anonymous queries throw M38040 unless both the API surface and backend tenant policy permit them. (proof citation: rfc0038_b37_grounded; verification pending)
  2. 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)
  3. 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)
  4. MUST_NOT — The client permits suppression of audit emission. (proof citation: rfc0038_b27_grounded; verification pending)
  5. 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

DirectionTarget
Depends onRFC-0006
Depends onRFC-0007
Depends onRFC-0036
Depends onRFC-0037
Extended byRFC-0039
Extended byRFC-0043