@openparachute/vault 0.4.7-rc.2 → 0.4.8-rc.10

package/core/src/cursor.ts

@@ -0,0 +1,272 @@
+/**
+ * Opaque cursors for `query-notes` (vault#313).
+ *
+ * Agent loops want "give me notes I haven't seen since last call." Today's
+ * pattern — pass `dateFilter: { field: "updated_at", from: <iso> }` and
+ * track the timestamp client-side — is brittle: the client has to remember
+ * the watermark, two notes at the same millisecond may collide, and a
+ * second call landed mid-millisecond can miss or double-count rows.
+ *
+ * The opaque-cursor pattern (Stripe, GitHub, et al.) fixes this. The server
+ * returns a `next_cursor: string` on each query response; the client passes
+ * it back on the next call and the server resumes from exactly where it
+ * left off. The cursor is base64url-encoded JSON the client must not
+ * inspect — internal layout can evolve without breaking callers.
+ *
+ * # Cursor payload
+ *
+ * ```ts
+ * {
+ *   v: 1,                      // schema version
+ *   last_updated_at: number,   // millisecond epoch of the last seen note
+ *   last_id: string,           // ID of the last seen note — tiebreaker
+ *   query_hash: string,        // sha256 of normalized query params (hex)
+ * }
+ * ```
+ *
+ * - `last_updated_at` is millisecond epoch (not ISO) so cursor bytes stay
+ *   compact and the tiebreaker math is integer.
+ * - `last_id` is the tiebreaker — when two notes share `updated_at`, the
+ *   keyset query advances `id > last_id` at that timestamp so neither is
+ *   skipped nor returned twice.
+ * - `query_hash` binds the cursor to the exact query it was minted for.
+ *   Passing a cursor minted on `tag: "foo"` into a call for `tag: "bar"`
+ *   would silently return the wrong page; mismatch raises a structured
+ *   400 (`cursor_query_mismatch`) instead.
+ *
+ * # Why JSON inside base64url
+ *
+ * A flat-string format (`<ts>:<id>:<hash>`) is two characters shorter but
+ * forecloses on optional fields. JSON gives us a schema-versioned envelope
+ * — if v2 needs additional state (e.g. a search-relevance secondary key),
+ * old clients keep working and new clients can read both.
+ *
+ * # Race safety
+ *
+ * The cursor stores the maximum-`updated_at`+`id` of the LAST returned
+ * page. The next call's keyset predicate is:
+ *
+ *   (updated_at > last_updated_at)
+ *   OR (updated_at = last_updated_at AND id > last_id)
+ *
+ * A note written between calls A and B at a brand-new `updated_at` is
+ * picked up by the first half of the predicate. A note written at the
+ * exact same `updated_at` as the cursor's watermark (uncommon — wall-clock
+ * collisions are rare at millisecond resolution but not impossible) is
+ * picked up by the tiebreaker because the SQL `ORDER BY updated_at ASC,
+ * id ASC` ensures stable interleaving with the prior page. Without the
+ * tiebreaker, two notes sharing an `updated_at` would be at the mercy of
+ * SQLite's row order, which is "stable in practice" but not contract.
+ */
+
+import { createHash } from "node:crypto";
+
+export const CURSOR_VERSION = 1;
+
+export interface CursorPayload {
+  /** Schema version. Bumped if the cursor layout changes incompatibly. */
+  v: number;
+  /** Millisecond epoch of the last note returned. */
+  last_updated_at: number;
+  /** ID of the last note returned — tiebreaker for same-ms collisions. */
+  last_id: string;
+  /** sha256(hex) of normalized query params. Mismatch → cursor_query_mismatch. */
+  query_hash: string;
+}
+
+/**
+ * Thrown when a caller passes a malformed or stale cursor. The wrapping
+ * layer (MCP / REST) catches and surfaces a 400 with the structured code
+ * — callers should drop the cursor and restart the iteration.
+ */
+export class CursorError extends Error {
+  override name = "CursorError";
+  code: "cursor_invalid" | "cursor_query_mismatch";
+  constructor(message: string, code: "cursor_invalid" | "cursor_query_mismatch") {
+    super(message);
+    this.code = code;
+  }
+}
+
+/** Encode a cursor payload to a base64url-safe opaque string. */
+export function encodeCursor(payload: CursorPayload): string {
+  const json = JSON.stringify(payload);
+  return Buffer.from(json, "utf8").toString("base64url");
+}
+
+/** Decode a cursor string. Throws `CursorError` on any structural problem. */
+export function decodeCursor(cursor: string): CursorPayload {
+  if (typeof cursor !== "string" || cursor.length === 0) {
+    throw new CursorError("cursor must be a non-empty string", "cursor_invalid");
+  }
+  let json: string;
+  try {
+    json = Buffer.from(cursor, "base64url").toString("utf8");
+  } catch {
+    throw new CursorError("cursor is not valid base64url", "cursor_invalid");
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(json);
+  } catch {
+    throw new CursorError("cursor payload is not valid JSON", "cursor_invalid");
+  }
+  if (!parsed || typeof parsed !== "object") {
+    throw new CursorError("cursor payload must be an object", "cursor_invalid");
+  }
+  const p = parsed as Record<string, unknown>;
+  if (typeof p.v !== "number" || p.v !== CURSOR_VERSION) {
+    throw new CursorError(
+      `cursor schema version mismatch (expected ${CURSOR_VERSION}, got ${String(p.v)})`,
+      "cursor_invalid",
+    );
+  }
+  if (typeof p.last_updated_at !== "number" || !Number.isFinite(p.last_updated_at)) {
+    throw new CursorError("cursor.last_updated_at must be a finite number", "cursor_invalid");
+  }
+  if (typeof p.last_id !== "string") {
+    throw new CursorError("cursor.last_id must be a string", "cursor_invalid");
+  }
+  if (typeof p.query_hash !== "string" || p.query_hash.length === 0) {
+    throw new CursorError("cursor.query_hash must be a non-empty string", "cursor_invalid");
+  }
+  return {
+    v: p.v,
+    last_updated_at: p.last_updated_at,
+    last_id: p.last_id,
+    query_hash: p.query_hash,
+  };
+}
+
+/**
+ * Shape of query parameters that participate in the query-hash.
+ *
+ * Pagination / cursor parameters themselves are excluded — bumping `limit`
+ * or advancing the cursor must NOT invalidate the cursor. Output-shape
+ * parameters (`include_content`, etc.) are also excluded — they don't
+ * affect *which* rows are returned, just how each row is rendered.
+ *
+ * The fields here are the *result-set-affecting* inputs. Any future filter
+ * added to `QueryOpts` should also be added here.
+ */
+export interface QueryHashInputs {
+  tags?: string[];
+  tagMatch?: "all" | "any";
+  excludeTags?: string[];
+  hasTags?: boolean;
+  hasLinks?: boolean;
+  path?: string;
+  pathPrefix?: string;
+  extension?: string | string[];
+  ids?: string[];
+  metadata?: Record<string, unknown>;
+  dateFrom?: string;
+  dateTo?: string;
+  dateFilter?: { field?: string; from?: string; to?: string };
+  sort?: "asc" | "desc";
+  orderBy?: string;
+}
+
+/**
+ * Compute a stable hash of the query parameters.
+ *
+ * Stability matters: a caller that passes `{tag: "x", path_prefix: "p"}`
+ * on call 1 and `{path_prefix: "p", tag: "x"}` on call 2 (same query,
+ * different object-key order) must get the same hash. We achieve this
+ * by canonicalizing — sorting array fields (where order is irrelevant),
+ * recursively sorting object keys, and stringifying with a deterministic
+ * key order.
+ *
+ * `undefined` fields are dropped before hashing. An empty `tags: []` and
+ * an unset `tags` produce the same hash (both mean "no tag filter"), so
+ * a caller that conditionally sets it doesn't accidentally invalidate
+ * their cursor.
+ *
+ * Returned as a hex sha256 digest — 64 chars, fits comfortably in the
+ * base64url cursor envelope.
+ */
+export function computeQueryHash(inputs: QueryHashInputs): string {
+  const canonical = canonicalize(inputs);
+  const json = JSON.stringify(canonical);
+  return createHash("sha256").update(json, "utf8").digest("hex");
+}
+
+/**
+ * Canonicalize a value for stable hashing.
+ *
+ * - Drops `undefined` properties (object keys with `undefined` values).
+ * - Drops empty arrays at the top level (treated equivalent to unset).
+ * - Sorts string-array fields where order doesn't affect query semantics
+ *   (`tags`, `excludeTags`, `ids`, `extension` when array-shaped).
+ * - Recursively sorts plain-object keys so JSON.stringify is order-stable.
+ * - Primitives and arrays of primitives pass through unchanged (after the
+ *   array-sort rule above).
+ *
+ * Inside `metadata`, sub-object keys (operator-clause shapes like
+ * `{eq, gte, lt}`) are sorted too — the engine treats `{gte: 5, lt: 10}`
+ * and `{lt: 10, gte: 5}` identically, so the cursor binding should as well.
+ */
+function canonicalize(value: unknown): unknown {
+  if (value === null || value === undefined) return null;
+  if (typeof value !== "object") return value;
+  if (Array.isArray(value)) {
+    // Don't sort arbitrary arrays — order may be semantic (e.g. an `in`
+    // operator's array value is order-irrelevant to SQLite, but cursor
+    // semantics defer to the caller). For the known order-irrelevant
+    // string-array fields we sort at the top-level canonicalization;
+    // deep arrays pass through unchanged so a caller's intent is preserved.
+    return (value as unknown[]).map((v) => canonicalize(v));
+  }
+  // Plain object. Sort keys, drop undefineds, sort known order-irrelevant
+  // string-array fields.
+  const ORDER_IRRELEVANT_STRING_ARRAYS = new Set([
+    "tags",
+    "excludeTags",
+    "ids",
+    "extension",
+  ]);
+  const out: Record<string, unknown> = {};
+  const keys = Object.keys(value as object).sort();
+  for (const k of keys) {
+    const v = (value as Record<string, unknown>)[k];
+    if (v === undefined) continue;
+    if (Array.isArray(v) && v.length === 0) continue;
+    if (ORDER_IRRELEVANT_STRING_ARRAYS.has(k) && Array.isArray(v) && v.every((x) => typeof x === "string")) {
+      out[k] = [...(v as string[])].sort();
+      continue;
+    }
+    out[k] = canonicalize(v);
+  }
+  return out;
+}
+
+/**
+ * Parse an ISO-8601 timestamp to millisecond epoch.
+ *
+ * SQLite stores `updated_at` as a string ISO timestamp (set on insert /
+ * update by the store layer). The cursor pipes that string out as a
+ * millisecond integer for compact serialization. This helper exists so
+ * the call sites (mint-cursor + decode-cursor-into-SQL-predicate) share
+ * exactly one conversion, with NaN guarded.
+ */
+export function isoToMillis(iso: string): number {
+  const ms = Date.parse(iso);
+  if (!Number.isFinite(ms)) {
+    throw new CursorError(`invalid ISO timestamp for cursor: ${iso}`, "cursor_invalid");
+  }
+  return ms;
+}
+
+/**
+ * Convert millisecond epoch back to an ISO-8601 timestamp string.
+ *
+ * Used to translate the cursor's `last_updated_at` into the form SQLite
+ * compares (`n.updated_at` is a TEXT column carrying ISO strings). ISO
+ * timestamps sort correctly lexicographically when they're all in the same
+ * canonical form (Z-suffixed, fixed millisecond precision) — every
+ * timestamp vault mints goes through `new Date(...).toISOString()` so the
+ * lex-order matches the millis-order.
+ */
+export function millisToIso(ms: number): string {
+  return new Date(ms).toISOString();
+}

package/core/src/mcp.ts

@@ -2,6 +2,7 @@ import { Database } from "bun:sqlite";
 import type { Store, Note } from "./types.js";
 import * as noteOps from "./notes.js";
 import { filterMetadata, MAX_BATCH_SIZE, validateExtension, ExtensionValidationError } from "./notes.js";
+import { QueryError } from "./query-operators.js";
 import * as linkOps from "./links.js";
 import * as tagSchemaOps from "./tag-schemas.js";
 import type { TagFieldSchema } from "./tag-schemas.js";
@@ -189,6 +190,11 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
           sort: { type: "string", enum: ["asc", "desc"], description: "Sort by created_at" },
           limit: { type: "number", description: "Max results (default 50)" },
           offset: { type: "number", description: "Pagination offset (default 0)" },
+          cursor: {
+            type: "string",
+            description:
+              "Opaque cursor for 'since last checked' agent loops (vault#313). First call: omit. The response will include `next_cursor` — pass it on the subsequent call to receive only notes created or updated since the prior page. The cursor binds to the query's filters (tag, path, metadata, etc.); changing them between calls returns a structured `cursor_query_mismatch` error. Pagination via cursor orders results by `updated_at ASC` and is mutually exclusive with `order_by` and `sort: \"desc\"`. The response shape switches to `{notes, next_cursor}` when this parameter is present.",
+          },
           include_content: { type: "boolean", description: "Include note content (default: true for single, false for list)" },
           include_metadata: {
             oneOf: [
@@ -254,8 +260,32 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
           nearScope = new Set([anchor.id, ...traversed.map((t) => t.noteId)]);
         }
 
+        // --- Cursor mode (vault#313) ---
+        // When the caller passes `cursor`, the response shape switches to
+        // `{notes, next_cursor}` and `queryNotesPaged` handles the keyset
+        // pagination. Cursor mode is incompatible with full-text search
+        // (FTS owns its own ordering — relevance, not updated_at) and
+        // graph-neighborhood scoping (`near` would have to rebuild the
+        // neighborhood every call to be cursor-stable; we punt for now).
+        // Both surface as INVALID_QUERY rather than silently returning
+        // wrong rows.
+        const cursorMode = typeof params.cursor === "string" && params.cursor.length > 0;
+        if (cursorMode && params.search) {
+          throw new QueryError(
+            `cursor is incompatible with full-text search — FTS has its own ordering. Use date_filter on updated_at for since-last-checked search.`,
+            "INVALID_QUERY",
+          );
+        }
+        if (cursorMode && params.near) {
+          throw new QueryError(
+            `cursor is incompatible with near (graph neighborhood). Resolve the neighborhood first, then iterate with cursor + ids.`,
+            "INVALID_QUERY",
+          );
+        }
+
         // --- Full-text search ---
         let results: Note[];
+        let nextCursor: string | null = null;
         if (params.search) {
           // Normalize tag param
           const tags = normalizeTags(params.tag);
@@ -277,12 +307,13 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
           // unknown keys silently; aliasing here closes the silent-no-op gap.
           const excludeTagsRaw = params.exclude_tags ?? params.excludeTags ?? params.exclude_tag;
           const excludeTags = normalizeTags(excludeTagsRaw);
-          // Route through `store.queryNotes` (not `noteOps.queryNotes`) so
-          // tag-hierarchy expansion fires for MCP callers the same as for
-          // HTTP REST callers — `tag: "manual"` matches descendants declared
-          // via `_tags/*` config notes. The previous direct-noteOps call
-          // bypassed the wrapper and silently dropped hierarchy expansion.
-          results = await store.queryNotes({
+          // Route through `store.queryNotes`/`queryNotesPaged` (not the raw
+          // `noteOps` exports) so tag-hierarchy expansion fires for MCP
+          // callers the same as for HTTP REST callers — `tag: "manual"`
+          // matches descendants declared via `_tags/*` config notes. The
+          // previous direct-noteOps call bypassed the wrapper and silently
+          // dropped hierarchy expansion.
+          const queryOpts = {
             tags,
             tagMatch: (params.tag_match as "all" | "any") ?? (tags && tags.length > 1 ? "any" : undefined),
             excludeTags,
@@ -307,7 +338,15 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
             orderBy: params.order_by as string | undefined,
             limit: (params.limit as number) ?? 50,
             offset: params.offset as number | undefined,
-          });
+            cursor: cursorMode ? (params.cursor as string) : undefined,
+          };
+          if (cursorMode) {
+            const page = await store.queryNotesPaged(queryOpts);
+            results = page.notes;
+            nextCursor = page.next_cursor;
+          } else {
+            results = await store.queryNotes(queryOpts);
+          }
         }
 
         // For full-text search the post-filter is still the right shape — FTS
@@ -347,9 +386,14 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
             if (params.include_attachments) enriched.attachments = await store.getAttachments(n.id);
             enrichedOut.push(enriched);
           }
+          // Cursor mode wraps the list in `{notes, next_cursor}` so callers can
+          // chain calls without tracking a watermark client-side. Legacy
+          // callers (no `cursor` param) still get the flat array.
+          if (cursorMode) return { notes: enrichedOut, next_cursor: nextCursor };
           return enrichedOut;
         }
 
+        if (cursorMode) return { notes: output, next_cursor: nextCursor };
         return output;
       },
     },

package/core/src/notes.ts

@@ -1,5 +1,5 @@
 import { Database, type SQLQueryBindings } from "bun:sqlite";
-import type { Note, NoteIndex, QueryOpts, VaultStats } from "./types.js";
+import type { Note, NoteIndex, QueryOpts, QueryNotesPage, VaultStats } from "./types.js";
 import { normalizePath } from "./paths.js";
 import {
   buildOperatorClause,
@@ -7,6 +7,17 @@ import {
   QueryError,
   requireIndexedField,
 } from "./query-operators.js";
+import {
+  CURSOR_VERSION,
+  CursorError,
+  computeQueryHash,
+  decodeCursor,
+  encodeCursor,
+  isoToMillis,
+  millisToIso,
+  type CursorPayload,
+  type QueryHashInputs,
+} from "./cursor.js";
 
 let idCounter = 0;
 
@@ -663,9 +674,68 @@ export function queryNotes(db: Database, opts: QueryOpts): Note[] {
     }
   }
 
+  // ---- Cursor predicate (vault#313) ----
+  //
+  // When a cursor is present, decode it, verify its query_hash matches the
+  // current query, and add a keyset predicate of the form:
+  //
+  //   (updated_at > last_updated_at)
+  //     OR (updated_at = last_updated_at AND id > last_id)
+  //
+  // The cursor also forces ORDER BY n.updated_at ASC, n.id ASC so the
+  // watermark math is sound — paginating by updated_at while ordering
+  // by created_at would skip rows whose update timestamp differs from
+  // their creation timestamp. `orderBy` and `sort: "desc"` are mutually
+  // exclusive with cursor mode (a "since last checked" loop wants
+  // ascending updated_at, full stop); we reject with INVALID_QUERY so
+  // callers don't silently get a broken iteration.
+  let cursorPayload: CursorPayload | null = null;
+  if (opts.cursor) {
+    if (opts.orderBy) {
+      throw new QueryError(
+        `cursor and order_by are mutually exclusive — cursor pagination forces order by updated_at`,
+        "INVALID_QUERY",
+      );
+    }
+    if (opts.sort === "desc") {
+      throw new QueryError(
+        `cursor pagination requires ascending sort by updated_at — descending sort with a cursor would skip newly-written rows`,
+        "INVALID_QUERY",
+      );
+    }
+    cursorPayload = decodeCursor(opts.cursor);
+    const expectedHash = computeQueryHash(toQueryHashInputs(opts));
+    if (cursorPayload.query_hash !== expectedHash) {
+      throw new CursorError(
+        `cursor was minted for a different query — drop the cursor and restart iteration`,
+        "cursor_query_mismatch",
+      );
+    }
+    // Translate the millis watermark back to an ISO string for the SQL
+    // comparison. SQLite's `n.updated_at` is TEXT in canonical ISO form
+    // (the store's `toISOString()` output), and ISO timestamps sort
+    // lexicographically in the same order as their millisecond epochs
+    // when they all use the same canonical form — which every timestamp
+    // vault mints does. Cursors minted on heterogeneous timestamps
+    // (e.g. an import that preserved unusual formatting) are still
+    // safe: we round-trip the cursor's millis through `new Date()`'s
+    // canonical ISO so the comparison is apples-to-apples.
+    const cursorIso = millisToIso(cursorPayload.last_updated_at);
+    conditions.push(
+      "(n.updated_at > ? OR (n.updated_at = ? AND n.id > ?))",
+    );
+    params.push(cursorIso, cursorIso, cursorPayload.last_id);
+  }
+
   const direction = opts.sort === "desc" ? "DESC" : "ASC";
   let orderBy: string;
-  if (opts.orderBy) {
+  if (opts.cursor) {
+    // Cursor mode forces a deterministic keyset order. `id` is the
+    // tiebreaker — without it, two notes sharing an `updated_at` would
+    // be at the mercy of SQLite's row order and the next page could
+    // miss or duplicate one.
+    orderBy = "n.updated_at ASC, n.id ASC";
+  } else if (opts.orderBy) {
     requireIndexedField(db, opts.orderBy);
     // `orderBy` came from indexed_fields (validated on declaration), so
     // the column name is safe to interpolate. Append created_at as a
@@ -697,6 +767,98 @@ export function queryNotes(db: Database, opts: QueryOpts): Note[] {
   });
 }
 
+/**
+ * Extract the result-set-affecting subset of `QueryOpts` for cursor hashing.
+ *
+ * `cursor`, `limit`, `offset`, `_tagsExpanded` (internal cache key) are
+ * excluded — they don't change which rows match, just how many or how
+ * the iteration advances. See `core/src/cursor.ts` for the rationale.
+ */
+function toQueryHashInputs(opts: QueryOpts): QueryHashInputs {
+  return {
+    tags: opts.tags,
+    tagMatch: opts.tagMatch,
+    excludeTags: opts.excludeTags,
+    hasTags: opts.hasTags,
+    hasLinks: opts.hasLinks,
+    path: opts.path,
+    pathPrefix: opts.pathPrefix,
+    extension: opts.extension,
+    ids: opts.ids,
+    metadata: opts.metadata,
+    dateFrom: opts.dateFrom,
+    dateTo: opts.dateTo,
+    dateFilter: opts.dateFilter,
+    sort: opts.sort,
+    orderBy: opts.orderBy,
+  };
+}
+
+/**
+ * Cursor-paginated wrapper around `queryNotes` (vault#313).
+ *
+ * Always returns `{ notes, next_cursor }`. `next_cursor` advances even on
+ * an empty result page — the caller can persist a single watermark and
+ * keep polling without special-casing the empty-page condition. The
+ * empty-page cursor's `last_updated_at` is the larger of:
+ *   - the prior cursor's `last_updated_at` (when `opts.cursor` was set), or
+ *   - the prior cursor's `last_updated_at` (defaults to 0 when not).
+ *
+ * Holding the watermark at the prior value on an empty page is the
+ * conservative choice: if a note is written between this call and the
+ * next at a timestamp BEFORE wall-clock-now (clock skew, batch import
+ * with explicit `created_at`), advancing the watermark to `now()` would
+ * skip it. The watermark advances only when actual rows are returned.
+ *
+ * First-call semantics (`opts.cursor` absent): query_hash is computed
+ * from the result-set-affecting opts and bound into the minted cursor.
+ * If zero rows match, the returned cursor encodes
+ * `last_updated_at = 0, last_id = ""` so the next call returns
+ * everything written since (the keyset predicate
+ * `updated_at > 0 OR (updated_at = 0 AND id > "")` matches every row
+ * with a non-null `updated_at` greater than the unix epoch).
+ */
+export function queryNotesPaged(db: Database, opts: QueryOpts): QueryNotesPage {
+  const notes = queryNotes(db, opts);
+  const queryHash = computeQueryHash(toQueryHashInputs(opts));
+
+  // Watermark math: pick the larger of (last returned row, prior cursor
+  // watermark, sentinel). When the page is empty, fall back to the prior
+  // cursor's watermark — see the JSDoc rationale above.
+  let lastUpdatedAt = 0;
+  let lastId = "";
+  if (opts.cursor) {
+    // Re-decode (we already validated in queryNotes); this is cheap.
+    const prior = decodeCursor(opts.cursor);
+    lastUpdatedAt = prior.last_updated_at;
+    lastId = prior.last_id;
+  }
+  if (notes.length > 0) {
+    // queryNotes with a cursor orders by (updated_at ASC, id ASC), so
+    // the last note in the array is the new watermark. When no cursor
+    // was passed, the SQL is ordered by created_at; we still want the
+    // cursor to advance to the MAX (updated_at, id) of this page so
+    // the next call resumes correctly. Compute the max explicitly.
+    for (const note of notes) {
+      const updatedIso = note.updatedAt ?? note.createdAt;
+      const ms = isoToMillis(updatedIso);
+      if (ms > lastUpdatedAt || (ms === lastUpdatedAt && note.id > lastId)) {
+        lastUpdatedAt = ms;
+        lastId = note.id;
+      }
+    }
+  }
+
+  const next_cursor = encodeCursor({
+    v: CURSOR_VERSION,
+    last_updated_at: lastUpdatedAt,
+    last_id: lastId,
+    query_hash: queryHash,
+  });
+
+  return { notes, next_cursor };
+}
+
 export function searchNotes(
   db: Database,
   query: string,