Skip to content

Paging cursor for find and typed walks (#247 item 4) - #259

Merged
chouswei merged 4 commits into
masterfrom
feat/paging-cursor
Nov 4, 2026
Merged

chouswei merged 4 commits into
masterfrom
feat/paging-cursor

Conversation

@chouswei

@chouswei chouswei commented Nov 4, 2026

Copy link
Copy Markdown
Owner

Closes #247

Last piece of #247 (item 4): cursor paging for find and typed walks, across CLI, serve and the MCP tools (find, typed_walk).

Cursor design

  • Opaque token c_ + base32 of version | verb | position | store.change_count | query fingerprint plus a 12-byte HMAC-SHA256 keyed by the session id (memnet/paging.py). The position is a row count into this result, never an id or an id's order; no nickname or hid is in the token. Stateless on the server.
  • Refusals (existing error-code style), checked in this order: bad_cursor (not a token, forged, another session's, or the other verb's), cursor_mismatch (a query parameter changed; limit is not part of the fingerprint, so page size may change), stale_cursor (change_count differs: any write since the page; reads never bump it).
  • Resume re-runs the query and skips the rows already given (walk: typed_walk skip counted after WHERE/min-hops; find: bounded_match_find(offset=)). A walk page cut by the reply-byte cap returns a cursor at the first dropped row; a page cut by the 20,000 edge-read budget returns none (a re-run would hit the same budget).
  • Wire: walk walk_cursor stat (and stats.cursor in --json-handles); find ends with @STAT: find_cursor|<token>|-; MCP typed_walk adds next_cursor (null when no more) and takes limit/cursor; MCP find takes cursor/paged. Row numbers continue across walk pages.

Back-compat

Paging is opt-in: --cursor, --paged on find, an explicit --limit on typed-walk (CLI default is now "not asked", still 50), limit or cursor on MCP typed_walk (its default is now None, still 50). A request that asks for none of these gets the same bytes as before; pinned by test_backcompat_* and test_mcp_typed_walk_without_limit_or_cursor_is_unchanged (golden strings taken from master before the change).

Tests

tests/test_paging_cursor.py (written red first, commit 0495d87, then made green) and tests/test_sysml_paging_cursor.py. Full suite, ruff check and ruff format --check pass locally; a real memnet serve --ipc demo is in the proof notes.

Model

New MN-REQ-14.13 + MN-VER-14-S13, PagedRead action and PagingCursor part (requirements/verify/behaviour/implementation). MN-REQ-14.2 (general read past the 50-row cap) stays PARKED; see open decisions.

Open decisions for the owner

  1. 14.2 carries an Elon CTO note preferring a since-filter over an opaque cursor. I did not un-park it; 14.13 covers only find and typed walks as asked.
  2. Opt-in rule: find needs --paged (it always has a limit, so "limit asked" cannot be the switch), walk uses an explicit limit. Say if you would rather have a cursor on every limit-truncated reply.
  3. A write between pages gives stale_cursor (restart), not a best-effort resume. A serve restart that restores a session also invalidates cursors.
  4. Not paged: leftover query walk and pin_map (shaped by cue and depth, not a row list).

@chouswei
chouswei merged commit 927ecb9 into master Nov 4, 2026
2 checks passed
@chouswei chouswei mentioned this pull request Nov 4, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Feature request: typed walks (edge type + direction, far-node WHERE, bounded 1..k paths, paging)

1 participant