gnomonlearn
Docs/RFC-0038 traversal and pagination contract proposal

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.

SurfaceAuthored contract at discoveryBaseline implementation divergence
Traversal resultsRFC-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 pageRFC-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 securityRFC-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 reachRFC-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.

  1. Make TraversalPath edge-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. Make GetOutgoing and GetIncoming use 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.
  2. Use Cursor<T> for the iterable object and CursorPage<T> for each page. The page owns nextToken; the cursor owns next(), pages(), and streaming iteration. Define a bounded eager collection method with M38020 and a 10,000-item default, whether it is named toArray() or exposed through a bounded stream helper. Update RFC-0037 §6 and its Lean/RDF facts to the same vocabulary before generating reference catalogs.
  3. 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.
  4. 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

  1. 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.
  2. Test direction, predicates, cycles, parallel edges, deleted resources, bitemporal statement validity, stable ordering, pagination, and tenant boundaries through the client and every supported backend.
  3. Test token tampering, expiry, scope mismatch, key rotation, and HMAC verification at the actual HTTP continuation entry points; assert M38030.
  4. Run the generated-schema and published-artifact build graph. Until those tests pass, keep the fluent builder and HMAC claims labeled as draft.