RFC-0038 · Design Q&A
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.
Q: Which RFC defines tenant management for workspace queries?
A: RFC-0014 is module versioning. RFC-0038 §4.5 now cites RFC-0045 tenant-mode configuration and RFC-0051 PostgreSQL RLS binding, and marks the complete tenancy model deferred.
Source: RFC-0038 §4.5; RFC-0045; RFC-0051 Issue: The earlier workspace paragraph cited RFC-0014 for tenant management.
Q: Can a graph query silently ignore an unknown filter?
Status: Open
Source: RFC-0038 §5.3; RFC-0037 §4.1 Issue: The client MUST tolerate unknown filter keys silently, while the backend may ignore them. A caller that thinks it applied a tenant, permission, or identity restriction can receive a broader result set without an error. Recommendation: Reject unsupported restriction-bearing filters with a stable diagnostic or negotiate a versioned filter schema; align RFC-0037 and RFC-0038.
Q: How does a batch caller learn which items failed in partial-success mode?
Status: Open
Source: RFC-0038 §7
Issue: continueOnError: true says errors are collected in a BatchResult, but the public helper still returns only bigint[] and explicitly hides failures. Partial loss can look like success to the caller.
Recommendation: Return an explicit BatchResult variant for partial-success mode, including every failed index and diagnostic; keep the simple ID array only for atomic success.
Q: How is an escaped transactional client prevented from writing after commit?
Status: Open
Source: RFC-0038 §§3.1–3.4, 9 invariant 2
Issue: The RFC prohibits use of TransactionalGraphClient outside its callback but exposes an object reference that application code can retain. It does not define a runtime state check or error when a retained client is called after commit or rollback.
Recommendation: Bind each transactional client to a transaction token and reject all operations after closure with a stable diagnostic; test escaped and concurrent callback cases.
Q: When is tenant context cleared after a readonly query?
Status: Open
Source: RFC-0038 §§3.2, 8.1; RFC-0037 §5.4 Issue: The client sets backend tenant context on every query but clears it only at transaction end. A readonly client query may have no transaction, leaving session context on a pooled connection for the next caller. Recommendation: Scope tenant/principal context to each request or explicit transaction with guaranteed cleanup, including errors and cancellation.
Q: What context is bound into a continuation token?
Status: Open
Source: RFC-0038 §5.2; RFC-0037 §6 Issue: HMAC protects token integrity, but the RFC does not require a token to bind the tenant, principal, filter, order, page size, and query version. A valid token may be replayed under a different session or query. Recommendation: Bind those fields and an expiry to the signed token; reject reuse under a different context, and specify rotation and clock-skew behavior.
Q: How does a caller request an independent rollback boundary without changing transaction joining?
A: Use the approved isolatedTransaction(callback) method. Standalone calls own a transaction and do not require savepoints. Nested calls use a savepoint or reject before callback execution when savepoint support is incomplete. Nested completion does not commit the caller’s transaction. Fatal lifecycle failures propagate with causes; custom structural GraphClient implementations must forward the new method.
Source: RFC-0038 §§3.1, 3.4; approved Gnomon implementation fed0662ece0d3ecd6774469085cef261d303ad9e
Issue: The existing transaction(callback) deliberately joins the caller. Swallowing a callback error after such a join could commit partial failed work. Source adoption is recorded; runtime and full consumer compilation remain unproved.