Skip to content

[Ontology] Continue neighborhoods beyond the bounded source window #363

Closed

Description

@seonghobae

Buyer problem

PR #349 now fails visibly when its authorization-safe SQL source window is exhausted: it marks the neighborhood truncated, withholds a fake cursor, and tells the user to narrow the property filter or traversal depth. That is truthful and safe, but it is not the final product experience for a buyer who needs to inspect every authorized relation in a large neighborhood.

The current in-memory after:<edge_id> cursor can continue only within the already-loaded fact window. Relations beyond the SQL hard window are intentionally unreachable so that the API never fabricates completeness. This issue adds a real database continuation contract without weakening bounds, ABAC, cutoff, or deterministic ordering.

Required contract

Add a versioned, opaque source cursor whose server-side meaning binds to:

  • tenant/authorization scope and focus node;
  • focus node type and canonical UUID;
  • knowledge_cutoff;
  • maximum depth, node and edge bounds;
  • allowed property codes;
  • deterministic source order and last source key;
  • query/schema/contract version;
  • expiration or immutable request digest.

The cursor must be integrity-protected and must not reveal hidden endpoint IDs, omitted counts, timestamps, SQL ordering keys, or tenant identifiers.

Traversal requirements

  1. Continue the recursive candidate source window with keyset pagination rather than OFFSET.
  2. Preserve focus-connected breadth-first proximity before property/tie-break ordering.
  3. Apply source eligibility, available_time <= knowledge_cutoff, and endpoint ABAC before a relation can enter a page.
  4. A hidden endpoint removes the relation and cannot change visible totals, cursor shape, or timing metadata.
  5. Page N must not repeat or skip a visible relation from page N-1 under a fixed request snapshot.
  6. A cursor used with changed focus, cutoff, filters, limits, tenant, or contract version fails closed.
  7. Concurrent graph changes use an explicit snapshot/revision contract; they never silently splice two graph versions.
  8. Page payloads keep the exact-value table, CSV, JSON-LD, provenance, truth status, and mobile/print equivalents.

RED → GREEN acceptance

  • More than the hard source window of synthetic relations can be exhausted across deterministic pages.
  • Same request and snapshot produce byte-stable page boundaries and cursor sequence.
  • Cutoff-late evidence never consumes a page slot.
  • Hidden endpoints create no count, cursor, or timing side channel.
  • Cursor tampering, replay under another scope, unknown version, and expiration fail closed.
  • A one-edge first page remains connected to the focus node.
  • PostgreSQL integration proves no duplicate/skip across pages.
  • Frontend can load and optionally accumulate subsequent pages without losing selected evidence.
  • Production statement/branch coverage and public docstrings remain 100%.

Dependency and delivery

Implement as a forward stacked child after PR #349 is accepted. Reuse its typed ontology, truth/provenance, cutoff, ABAC, exact-value, Figma, Storybook, and accessibility contracts. Do not change Event Lineage, expose arbitrary SQL/Cypher/SPARQL, remove hard limits, or treat inferred relations as authoritative.

Activity

  1. self-assigned this
    on Aug 21, 2026
  2. seonghobae commented on Aug 21, 2026

    @seonghobae
    ContributorAuthor

    Stacked implementation is in PR #369 onto #349 (feat/ontology-source-window-continuation-v2140 @ d58befb).

    ADR 0124 adds a versioned opaque src.v1. HMAC source cursor with keyset pagination of the recursive SQL window. A missing ONTOLOGY_SOURCE_CURSOR_SECRET keeps truncated-without-cursor. Tamper, scope, version, expiry, and snapshot drift fail closed. The explorer accumulates pages without losing selected evidence.

    This is not independent APPROVE and is not mixed into #349.

  3. changed the title [-][Buyer Gap] Continue ontology neighborhoods beyond the bounded source window[/-] [+][Ontology] Continue neighborhoods beyond the bounded source window[/+] on Aug 25, 2026
  4. seonghobae commented on Aug 25, 2026

    @seonghobae
    ContributorAuthor

    Protected delivery is now present on main: PR #369 merged into #349, and #349 reached main as merge commit 9b0b71a. The shipped source cursor is versioned, opaque, HMAC-protected, scope/cutoff/filter/snapshot-bound, keyset-paged, fail-closed on tamper or missing secret, and accumulated by the explorer without losing selected evidence. Closing this implementation issue; runtime acceptance remains separate.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions