RFC-0038 traversal and pagination contract proposal
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.
This is a trace and gap record from the pinned draft specification. It does not establish proof or implementation conformance.
Status: first-release contract proposal, 2026-10-03. Owners: Graph Platform, Storage, DX, Security, and spec. No Gnomon graph is deployed; there are no live cursor tokens or graph records to migrate.
Owner decision, 2026-10-03: use edge-rich traversal paths for the first
release. The initial PostgreSQL schema now carries ordered resource, statement,
and predicate identities, and its backend adapter returns explicit edges.
The SQL now handles direction: both at every hop and records each edge’s
physical source and target even when a path reverses direction. Four focused
adapter tests and temporary PostgreSQL assertions cover parallel statements,
incoming direction, mixed direction, filters, invalid statements, and deleted
resources; a checked-in PGlite regression suite awaits its destination CI run. RFC-0037
§4.5 and the TraversalPath RDF source now state the selected path shape, and
the generated domain Turtle matches. All 90 RFC-0037 source-bound RDF reviews
were rebound after checking that their class verdicts remain unchanged: the
one changed node is still a DataType classification mismatch. The
generated graph binding target built against the updated SQL and includes the
both traversal enum. Graph and tRPC normalize snake_case result rows into
the edge-rich path; nine focused source-level tests passed. The tRPC
GetOutgoing and GetIncoming procedures and their web consumers now use the
same physical edge shape, including predicate and statement IDs. Seven shared
normalizer/web tests and two procedure hydration smoke tests passed; the
checked-in MemoryGraph hydration suite later passed as part of the full
graph API package test target.
On 2026-10-04, framework Bazel invocation
ca3b13a4-df20-4f9f-97f7-a93fa8566425 passed
//db/tests/db-lifecycle:test_node locally. The test log reports seven Vitest
files and 70 tests passed, including five traversal-identity.test.ts checks
with PGlite against the shipped 000_initial_schema/050_graph.sql function
source. Those checks cover mixed direction, parallel statement and predicate
identity, validity and deletion filters, cycle bounds, stable statement
ordering, and immediate edge identities. The Bazel test filter did not narrow
Vitest; the complete target ran. This is local SQL evidence, while destination
CI and other backends remain unverified.
RFC-0037 also specifies ltree query patterns such as org.* and *.member.
The initial SQL traversal functions had accepted LTREE values and used an
ancestor comparison, which rejected wildcard queries. The three functions now
accept text patterns and cast them to LQUERY for ltree query matching. A
checked-in PGlite case verifies prefix and suffix wildcards for immediate and
multi-hop reads; //db/tests/db-lifecycle:test_node passed locally with the
new case. //graph/tests/graph-backend-postgres:test_node also passed after
regenerating its schema bindings from the changed signatures. Both runs used
local cache only. These checks establish PostgreSQL behavior; portable
object-store pattern matching remains open.
The framework then passed //graph/tests/graph-backend-postgres:test_node
locally (successful Bazel invocation
02b53fcf-264a-4f74-b93e-b9cdfb00ec0e). The build generated DB schema
bindings from a 633-type, 278-function semantic model and ran nine Vitest
files with 28 passing tests, including five traversal adapter checks. Bazel
retried an initial transient remote-cache missing-input error before the
successful build. This verifies the local generated-binding and PostgreSQL
adapter target; it does not establish gRPC or object-store traversal support.
After removing regenerable Roma CAS data to recover disk space, the local
framework also passed //graph/tests/graph-backend-memory:test_node
(12 tests; invocation 104d19b4-e408-4514-bbc5-2ca1f2999a5e) and
//trpc/packages/api-domain-graph:test_node (53 tests in six files,
including seven traversal.hydration.test.ts tests with a real MemoryGraph
and stubbed SQL rows;
invocation 3ba02840-3216-437b-96fd-bb58507edb53). The graph API target’s
first attempt failed during remote-cache fetch with missing blobs; the
successful run disabled remote-cache reads and compiled the local dependency
closure. This verifies local tRPC hydration behavior and generated bindings,
while destination CI and portable backend behavior remain open.
RFC-0037’s Lean catalog emits a TypeScript path-shape fact. The full 55-module
Lean corpus compiled and its Turtle and reference drift checks passed; this
records the contract and does not prove traversal behavior. The full Bazel
test run did not complete because the configured local remote cache failed and
a cache-free retry exhausted temporary disk space. Cursor/CursorPage and
continuation-token decisions remain open; generated-binding integration tests
and cross-backend conformance are still required before release.
Conflicting authored and implemented surfaces
RFC-0038 §1 and §10 now describe graph-client as a migration baseline. The
current class exports createGraphClient and a fluent builder, but no
client.query() method; queries/builder.ts throws from execute() and
fetchAll(). The earlier statements that the complete RFC contract was
already implemented and that client.query() was a preserved legacy method
were removed from the authored narrative, Lean evidence, and RDF claim
source. This maturity correction does not implement the builder or settle the
open Cursor/CursorPage choice.
| Surface | Authored contract at discovery | Baseline implementation divergence |
|---|---|---|
| Traversal results | RFC-0037 §4.5 and its RDF projection define TraversalEdge {from, to, predicate, predicateId, statementId} and TraversalPath {edges, length}. | graph-backend-model/model/traversal.ts declares an edge with targetId and a path with resourceId, depth, and resource-ID path. PostgreSQL graph.get_outgoing and graph.traverse return those smaller shapes. The SQL path omits statement identity, so parallel edges cannot be distinguished after traversal. |
| Cursor versus page | RFC-0037 §6 calls {items, nextCursor, hasMore} a Cursor<T>. RFC-0038 §5 calls the iterable object with toArray() and toToken() a Cursor<T> and separately defines CursorPage<T> with nextToken. | core/packages/pagination has an iterable Cursor<T> with next(), pages(), count(), map(), and stream(); each CursorPage<T> carries items, nextToken, and hasMore. The two RFC descriptions cannot both type the same value. |
| Continuation security | RFC-0038 §5.2 requires HMAC-secured, short-lived stateless tokens and M38030 for tampering or expiry. | graph-backend-object-store/helpers.ts base64url-encodes JSON without authentication or expiry. The core memory cursor uses server-side opaque tokens. Neither proves the cross-request HMAC contract. |
| Query builder reach | RFC-0038 §6 promises executable from/where/traverse/limit/offset. | graph-client/queries/builder.ts throws on execute and fetchAll; the client has no query() member. The gRPC and object-store backend maps do not supply TraversalService, so they would return M37020 until implemented. |
The separate savvifi.graph.v1 gRPC contract uses bounded ordered TraverseHop
steps. It is a wire API, not a substitute for the in-process backend return
type. Keep that wire identity stable while adapters are built and tested.
The RFC-0038 source-bound claim review also found that its toArray() RDF
claim describes 10,000 entries as a fixed safety limit, while §5.1 and Lean
make the limit implementation-defined with 10,000 as the default. Align the
claim with the selected Cursor/CursorPage contract and retain the stated
default unless the owner chooses a different public limit.
Recommended first-release contract
- Make
TraversalPathedge-rich. Include the terminal resource ID, ordered resource IDs, ordered statement IDs and predicate IDs, and depth. Keep the edge sequence explicit so parallel statements and provenance remain distinguishable. MakeGetOutgoingandGetIncominguse one directional edge shape with source, target, statement, and predicate identity. Project the present SQL node-only results into this richer shape only after the query or wire response supplies the missing edge IDs; do not invent them. - Use
Cursor<T>for the iterable object andCursorPage<T>for each page. The page ownsnextToken; the cursor ownsnext(),pages(), and streaming iteration. Define a bounded eager collection method with M38020 and a 10,000-item default, whether it is namedtoArray()or exposed through a bounded stream helper. Update RFC-0037 §6 and its Lean/RDF facts to the same vocabulary before generating reference catalogs. - Sign cross-request continuation tokens with a versioned envelope containing position, query/filter digest, tenant and principal scope, issue time, and expiry. Verify the HMAC before honoring any token, compare signatures in constant time, reject altered/expired/wrong-scope tokens with M38030, and document signing-key rotation. In-process memory cursors may use opaque server-state tokens when no cross-request promise is made. Replace the object-store’s unauthenticated JSON codec before public API exposure.
- Implement the builder over these normalized service results. Backends without traversal support must surface M37020; do not silently return an incomplete result. The Postgres, gRPC, and object-store adapters need their own conformance tests before the builder is advertised as portable.
Acceptance
- Decide the Cursor/CursorPage identity, then update RFC-0037/0038 prose, Lean, RDF protobuf source, generated Turtle, TS types, Postgres SQL/generated bindings, gRPC adapters where applicable, and all source-bound reviews. Record old-to-new RDF IRIs before first publication.
- Test direction, predicates, cycles, parallel edges, deleted resources, bitemporal statement validity, stable ordering, pagination, and tenant boundaries through the client and every supported backend.
- Test token tampering, expiry, scope mismatch, key rotation, and HMAC verification at the actual HTTP continuation entry points; assert M38030.
- Run the generated-schema and published-artifact build graph. Until those tests pass, keep the fluent builder and HMAC claims labeled as draft.