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

package/README.md

@@ -67,6 +67,9 @@ A mental model for "where is my data?" and "what can I poke at?" after the one-c
       default/
         vault.db            # the SQLite database — notes, tags, links, attachments,
                             # per-vault tokens, OAuth clients + codes, tag schemas
+        vault.db-wal        # WAL journal (write-ahead log) — transient, recreated
+                            # on demand. Carries pending writes between checkpoints.
+        vault.db-shm        # WAL shared-memory index — transient, recreated on demand.
         vault.yaml          # per-vault config — description (sent as MCP session
                             # instruction), published_tag override, legacy api_keys
         assets/             # per-vault uploaded attachments (audio, images)
@@ -76,6 +79,8 @@ A mental model for "where is my data?" and "what can I poke at?" after the one-c
 
 `config.yaml` is the one file written at 0600 because it holds the bcrypt owner-password hash and the plaintext TOTP secret. `.env` is written with your umask default (typically 0644); if you add webhook API keys there, tighten the mode yourself. SQLite DBs follow your umask.
 
+The vault SQLite database runs in **WAL** (write-ahead logging) journal mode for multi-process concurrent access — the daemon, CLI tools, and out-of-process consumers (e.g. `parachute-runner` polling `tag:job`) can read concurrently while the daemon writes, without lock contention. WAL adds two sidecar files alongside `vault.db`: `vault.db-wal` (the journal) and `vault.db-shm` (shared-memory index). Both are recreated on demand; **don't back them up separately** — `parachute-vault backup` snapshots only `vault.db` via `VACUUM INTO`, which produces a consistent full-DB copy without needing the sidecars. If you copy a vault by hand, `vault.db` alone is sufficient on a checkpointed database; if you must capture an in-flight write, copy all three files. If WAL can't be enabled (NFS, some FUSE / Docker volume drivers don't support the `-shm` region), vault logs `[vault] WAL mode could not be enabled` on startup and falls back to the legacy single-writer mode.
+
 ### Registered externally
 
 - **macOS**: a launchd user agent labelled `computer.parachute.vault` (plus `computer.parachute.vault.backup` if you ran `vault backup --schedule`).
@@ -339,16 +344,45 @@ Webhook servers (scribe, narrate) are stateless — they don't need vault's API
 
 ### On-upload transcription
 
-The trigger system above handles the "tag a note and let a webhook fill in content later" shape. Clients that already know at upload time that an audio file should be transcribed can take a shorter path: `POST /api/notes/{id}/attachments` with `{transcribe: true}` in the body. The vault stamps the attachment with `transcribe_status: "pending"` and the note with `transcribe_stub: true`, then a background worker drains the queue FIFO.
-
-Enable the worker by pointing the server at a Whisper-compatible endpoint:
-
-```
-SCRIBE_URL=http://localhost:3200
-SCRIBE_TOKEN=optional-bearer-token
-```
-
-The worker POSTs audio as multipart to `${SCRIBE_URL}/v1/audio/transcriptions` and expects `{ text: string }` back. On success it replaces the `_Transcript pending._` placeholder in the note body (or the whole body if the placeholder is absent), clears `transcribe_stub`, and records `transcript` + `transcribe_done_at` on the attachment. If the user edited the note and cleared `transcribe_stub` before the transcript landed, the note is left alone — but the transcript is still stored on the attachment. Failures retry with exponential backoff up to three attempts before flipping `transcribe_status` to `"failed"`.
+Two paths feed the same transcription worker; they differ in how the
+result surfaces.
+
+**Auto-transcribe (vault#353).** When the operator flips
+`auto_transcribe.enabled: true` in vault's config AND scribe is
+reachable (registered in `~/.parachute/services.json`, or pointed at
+via `SCRIBE_URL`), any audio attachment uploaded to the vault is
+automatically queued for transcription. The worker writes a sibling
+`<attachment-path>.transcript.md` note with the transcript text +
+frontmatter linking back to the audio (`transcript_of`,
+`transcript_status`, `transcript_duration_ms`, etc.). Failures land as
+the same note with `transcript_status: failed` and the cause in
+`transcript_error`; the original audio is preserved. Operators can
+retry a failed transcript via `POST /vault/<name>/api/notes/<note-id>/retry-transcription`.
+
+**Explicit `transcribe: true` (legacy, Lens flow).** Callers that already
+know at upload time that an audio file should be transcribed pass
+`transcribe: true` to `POST /api/notes/{id}/attachments`. The vault
+stamps the attachment with `transcribe_status: "pending"` and the note
+with `transcribe_stub: true`. The worker replaces the literal
+`_Transcript pending._` placeholder in the note body with the transcript
+on success (or the whole body if no placeholder is present).
+
+Service discovery is automatic — when scribe lands in
+`~/.parachute/services.json` (the canonical hub-maintained registry),
+vault picks up its URL on next restart. The `SCRIBE_URL` env var still
+wins when set. The shared bearer for vault→scribe auth is generated
+once at first boot and persisted to `~/.parachute/vault/.env` as
+`SCRIBE_AUTH_TOKEN`; mirror that value into scribe's
+`SCRIBE_AUTH_TOKEN` env so scribe accepts the Authorization header.
+
+The worker POSTs audio as multipart to
+`${SCRIBE_URL}/v1/audio/transcriptions` and expects `{ text: string }`
+back. On success it records `transcript` + `transcribe_done_at` +
+`transcribe_duration_ms` on the attachment row regardless of the
+result-surface path. Failures retry with exponential backoff up to three
+attempts before flipping `transcribe_status` to `"failed"`; 4xx
+responses carrying `error_code` (e.g. `missing_provider`) are treated as
+terminal on the first failure.
 
 Per-vault `audio_retention` controls what happens to the audio file on disk once the worker reaches a terminal state. It's readable and mutable at runtime via `GET` / `PATCH /api/vault` (under `config.audio_retention`), or by hand-editing `vault.yaml`.
 

package/core/src/connection-pragmas.test.ts

@@ -0,0 +1,232 @@
+/**
+ * Tests for connection-level pragmas — WAL mode + synchronous=NORMAL +
+ * foreign_keys=ON. See applyConnectionPragmas in schema.ts and vault#326.
+ *
+ * `:memory:` databases land in journal_mode=memory and DO NOT support WAL
+ * (the WAL/shm sidecars need a real file). On-disk DBs are the realistic
+ * path; we exercise both so the readonly + filesystem-unsupported branches
+ * are covered.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { mkdtempSync, rmSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { applyConnectionPragmas, initSchema } from "./schema.ts";
+
+let dir: string;
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), "vault-pragma-"));
+});
+
+afterEach(() => {
+  rmSync(dir, { recursive: true, force: true });
+});
+
+function pragma(db: Database, name: string): string | number {
+  const row = db.prepare(`PRAGMA ${name}`).get() as Record<string, string | number> | null;
+  if (!row) return "";
+  // PRAGMA xxx returns a one-key object whose key matches the pragma name.
+  const v = Object.values(row)[0];
+  return typeof v === "string" ? v.toLowerCase() : (v as number);
+}
+
+describe("applyConnectionPragmas — on-disk DB", () => {
+  it("enables WAL mode on a fresh on-disk database", () => {
+    const db = new Database(join(dir, "fresh.db"));
+    const result = applyConnectionPragmas(db);
+    expect(result.wal).toBe(true);
+    expect(result.journalMode).toBe("wal");
+    expect(pragma(db, "journal_mode")).toBe("wal");
+    db.close();
+  });
+
+  it("sets synchronous=NORMAL when WAL succeeds", () => {
+    const db = new Database(join(dir, "sync.db"));
+    applyConnectionPragmas(db);
+    // synchronous values: 0=off, 1=normal, 2=full, 3=extra. NORMAL is 1.
+    expect(pragma(db, "synchronous")).toBe(1);
+    db.close();
+  });
+
+  it("sets wal_autocheckpoint=1000 when WAL succeeds", () => {
+    const db = new Database(join(dir, "checkpoint.db"));
+    applyConnectionPragmas(db);
+    expect(pragma(db, "wal_autocheckpoint")).toBe(1000);
+    db.close();
+  });
+
+  it("enables foreign_keys", () => {
+    const db = new Database(join(dir, "fk.db"));
+    applyConnectionPragmas(db);
+    expect(pragma(db, "foreign_keys")).toBe(1);
+    db.close();
+  });
+
+  it("is idempotent — applying twice yields the same result", () => {
+    const dbPath = join(dir, "idem.db");
+    const db = new Database(dbPath);
+    const a = applyConnectionPragmas(db);
+    const b = applyConnectionPragmas(db);
+    expect(a).toEqual(b);
+    expect(b.wal).toBe(true);
+    db.close();
+  });
+
+  it("a DB created in DELETE mode is migrated to WAL on next open", () => {
+    const dbPath = join(dir, "migrate.db");
+
+    // First connection — manually force DELETE journal mode (the legacy
+    // shape that pre-WAL vaults shipped with). Write some data so we can
+    // verify it survives the WAL flip.
+    {
+      const db = new Database(dbPath);
+      db.exec("PRAGMA journal_mode = DELETE");
+      db.exec("CREATE TABLE legacy (k TEXT PRIMARY KEY, v TEXT)");
+      db.prepare("INSERT INTO legacy (k, v) VALUES (?, ?)").run("hello", "world");
+      expect(pragma(db, "journal_mode")).toBe("delete");
+      db.close();
+    }
+
+    // Second connection — apply pragmas. WAL takes effect, existing data
+    // intact.
+    {
+      const db = new Database(dbPath);
+      const result = applyConnectionPragmas(db);
+      expect(result.wal).toBe(true);
+      const row = db.prepare("SELECT v FROM legacy WHERE k = ?").get("hello") as { v: string };
+      expect(row.v).toBe("world");
+      db.close();
+    }
+  });
+});
+
+describe("applyConnectionPragmas — :memory: DB", () => {
+  it("returns wal:false, journalMode='memory' WITHOUT warning", () => {
+    // :memory: is bun:sqlite's ephemeral mode — journal_mode comes back as
+    // "memory" and WAL can't be enabled. This is an explicit caller choice
+    // (test fixtures, throwaway probes), not an operator-visible filesystem
+    // limitation, so applyConnectionPragmas suppresses the warning for it
+    // to keep test output clean.
+    const db = new Database(":memory:");
+
+    const warnings: string[] = [];
+    const origWarn = console.warn;
+    console.warn = (msg: string) => warnings.push(msg);
+
+    try {
+      const result = applyConnectionPragmas(db);
+      expect(result.wal).toBe(false);
+      expect(result.journalMode).toBe("memory");
+      expect(warnings.length).toBe(0);
+    } finally {
+      console.warn = origWarn;
+      db.close();
+    }
+  });
+
+  it("still enables foreign_keys on the :memory: branch", () => {
+    const db = new Database(":memory:");
+    applyConnectionPragmas(db);
+    expect(pragma(db, "foreign_keys")).toBe(1);
+    db.close();
+  });
+});
+
+describe("applyConnectionPragmas — WAL-unsupported on-disk filesystem (simulated)", () => {
+  it("warns once when an on-disk DB lands in a non-WAL, non-memory mode", () => {
+    // We can't easily mount an NFS volume in CI, so simulate the
+    // unsupported-FS branch: open an on-disk DB and immediately force
+    // journal_mode to a non-WAL mode that sticks. PRAGMA journal_mode=WAL
+    // will then return that mode (because WAL silently fell back), which
+    // is the exact shape the unsupported-FS detection triggers on.
+    //
+    // We do this by stubbing prepare("PRAGMA journal_mode = WAL") to
+    // return { journal_mode: "delete" } — what bun:sqlite returns when
+    // SQLite refuses the WAL flip.
+    const db = new Database(join(dir, "stub.db"));
+
+    const origPrepare = db.prepare.bind(db);
+    // @ts-expect-error — narrow override for the one PRAGMA we care about
+    db.prepare = (sql: string) => {
+      if (sql === "PRAGMA journal_mode = WAL") {
+        return {
+          get: () => ({ journal_mode: "delete" }),
+          all: () => [{ journal_mode: "delete" }],
+          run: () => ({ changes: 0, lastInsertRowid: 0 }),
+        };
+      }
+      return origPrepare(sql);
+    };
+
+    const warnings: string[] = [];
+    const origWarn = console.warn;
+    console.warn = (msg: string) => warnings.push(msg);
+
+    try {
+      const result = applyConnectionPragmas(db);
+      expect(result.wal).toBe(false);
+      expect(result.journalMode).toBe("delete");
+      expect(warnings.length).toBe(1);
+      expect(warnings[0]).toContain("WAL mode could not be enabled");
+      expect(warnings[0]).toContain("journal_mode=delete");
+
+      // Second call on the same handle: dedupe by WeakSet, no second warn.
+      applyConnectionPragmas(db);
+      expect(warnings.length).toBe(1);
+    } finally {
+      console.warn = origWarn;
+      db.close();
+    }
+  });
+});
+
+describe("initSchema integration", () => {
+  it("leaves a fresh vault DB in WAL mode after full initialization", () => {
+    const db = new Database(join(dir, "vault.db"));
+    initSchema(db);
+    expect(pragma(db, "journal_mode")).toBe("wal");
+    expect(pragma(db, "foreign_keys")).toBe(1);
+    expect(pragma(db, "synchronous")).toBe(1);
+    db.close();
+  });
+});
+
+describe("multi-connection concurrency under WAL", () => {
+  it("allows a second connection to read while a first holds an open write txn", () => {
+    // The whole point of WAL: a reader running concurrently with a writer
+    // does NOT block. Under the legacy DELETE journal mode an open write
+    // txn locks out readers and a `BEGIN IMMEDIATE` from a sibling
+    // connection on the same file errors with SQLITE_BUSY.
+    //
+    // Setup: writer opens, applies pragmas (flips DB to WAL), inserts a
+    // row, BEGINS another txn (uncommitted). Reader opens a second
+    // connection to the same file and SELECTs — should succeed instantly
+    // with the pre-txn committed state.
+    const dbPath = join(dir, "concurrent.db");
+    const writer = new Database(dbPath);
+    initSchema(writer);
+
+    writer.exec(`CREATE TABLE k (id INTEGER PRIMARY KEY, v TEXT)`);
+    writer.prepare(`INSERT INTO k (id, v) VALUES (?, ?)`).run(1, "committed");
+
+    // Open a long-running write txn that doesn't commit.
+    writer.exec("BEGIN IMMEDIATE");
+    writer.prepare(`INSERT INTO k (id, v) VALUES (?, ?)`).run(2, "uncommitted");
+
+    // Reader: a separate connection (simulating a separate process).
+    // Under WAL this read should succeed and see only the committed row.
+    const reader = new Database(dbPath, { readonly: true });
+    try {
+      const rows = reader.prepare("SELECT id, v FROM k ORDER BY id").all() as { id: number; v: string }[];
+      expect(rows).toEqual([{ id: 1, v: "committed" }]);
+    } finally {
+      reader.close();
+    }
+
+    writer.exec("ROLLBACK");
+    writer.close();
+  });
+});

package/core/src/core.test.ts

@@ -3,6 +3,7 @@ import { Database } from "bun:sqlite";
 import { SqliteStore } from "./store.js";
 import { generateMcpTools } from "./mcp.js";
 import { initSchema } from "./schema.js";
+import { decodeCursor } from "./cursor.js";
 
 let store: SqliteStore;
 let db: Database;
@@ -1312,6 +1313,262 @@ describe("queryNotes", async () => {
     expect(desc[0].content).toBe("Second");
   });
 
+  // ---- Cursor pagination (vault#313) ----
+  //
+  // Opaque cursors for "since last checked" agent loops. The cursor binds
+  // to the query's filters via sha256 of the result-set-affecting params;
+  // a mismatched cursor raises CursorError. Pagination is keyset on
+  // (updated_at, id) so two notes sharing a millisecond don't get skipped
+  // or doubled across the page boundary.
+  describe("cursor pagination", () => {
+    // Helper: pin a note's updated_at to a known value so cursor math
+    // doesn't race wall-clock writes from the test harness.
+    function pinUpdatedAt(id: string, iso: string) {
+      db.prepare("UPDATE notes SET updated_at = ? WHERE id = ?").run(iso, id);
+    }
+
+    it("first call returns notes + a next_cursor string", async () => {
+      await store.createNote("A", { id: "na" });
+      await store.createNote("B", { id: "nb" });
+      const page = await store.queryNotesPaged({ tags: [], limit: 50 });
+      expect(page.notes.length).toBe(2);
+      expect(typeof page.next_cursor).toBe("string");
+      expect(page.next_cursor.length).toBeGreaterThan(0);
+    });
+
+    it("subsequent call with cursor returns only newer notes", async () => {
+      const a = await store.createNote("first", { id: "p1" });
+      pinUpdatedAt(a.id, "2026-04-01T00:00:00.000Z");
+      const b = await store.createNote("second", { id: "p2" });
+      pinUpdatedAt(b.id, "2026-04-02T00:00:00.000Z");
+
+      const page1 = await store.queryNotesPaged({});
+      // Both notes returned, cursor advances to "second"'s watermark.
+      expect(page1.notes.map((n) => n.id).sort()).toEqual(["p1", "p2"]);
+
+      // No new writes yet — second call should be empty.
+      const page2 = await store.queryNotesPaged({ cursor: page1.next_cursor });
+      expect(page2.notes).toHaveLength(0);
+
+      // Now write a new note; third call should return only it.
+      const c = await store.createNote("third", { id: "p3" });
+      pinUpdatedAt(c.id, "2026-04-03T00:00:00.000Z");
+      const page3 = await store.queryNotesPaged({ cursor: page2.next_cursor });
+      expect(page3.notes.map((n) => n.id)).toEqual(["p3"]);
+    });
+
+    it("next_cursor is always returned, even on an empty result page", async () => {
+      // No notes at all — first call returns empty array but still a cursor.
+      const page = await store.queryNotesPaged({});
+      expect(page.notes).toHaveLength(0);
+      expect(typeof page.next_cursor).toBe("string");
+      expect(page.next_cursor.length).toBeGreaterThan(0);
+
+      // Decode it: empty-page sentinel watermark is millis 0 + empty id.
+      const decoded = decodeCursor(page.next_cursor);
+      expect(decoded.last_updated_at).toBe(0);
+      expect(decoded.last_id).toBe("");
+    });
+
+    it("cursor with stale query_hash raises CursorError (cursor_query_mismatch)", async () => {
+      await store.createNote("a", { tags: ["x"], id: "qm1" });
+      await store.createNote("b", { tags: ["y"], id: "qm2" });
+
+      const page1 = await store.queryNotesPaged({ tags: ["x"] });
+      expect(page1.notes.map((n) => n.id)).toEqual(["qm1"]);
+
+      // Reuse the cursor with a different query — must reject loudly.
+      try {
+        await store.queryNotesPaged({ tags: ["y"], cursor: page1.next_cursor });
+        throw new Error("expected CursorError");
+      } catch (err: any) {
+        expect(err.name).toBe("CursorError");
+        expect(err.code).toBe("cursor_query_mismatch");
+      }
+    });
+
+    it("cursor with malformed payload raises CursorError (cursor_invalid)", async () => {
+      try {
+        await store.queryNotesPaged({ cursor: "not-a-real-cursor-!!!" });
+        throw new Error("expected CursorError");
+      } catch (err: any) {
+        expect(err.name).toBe("CursorError");
+        expect(err.code).toBe("cursor_invalid");
+      }
+    });
+
+    it("tiebreaker: two notes at the same updated_at use id as the secondary sort key", async () => {
+      const ts = "2026-04-15T00:00:00.000Z";
+      const a = await store.createNote("alpha", { id: "tb-a" });
+      const b = await store.createNote("beta", { id: "tb-b" });
+      const c = await store.createNote("gamma", { id: "tb-c" });
+      pinUpdatedAt(a.id, ts);
+      pinUpdatedAt(b.id, ts);
+      pinUpdatedAt(c.id, ts);
+
+      // Page 1 with limit=2: should return a + b (id-ascending tiebreaker).
+      const page1 = await store.queryNotesPaged({ limit: 2 });
+      expect(page1.notes.map((n) => n.id)).toEqual(["tb-a", "tb-b"]);
+
+      // Page 2 with the cursor: should return c (id > "tb-b" at same ms).
+      // Note: c is queried with the same query_hash since limit is
+      // excluded from the hash inputs by design.
+      const page2 = await store.queryNotesPaged({ limit: 2, cursor: page1.next_cursor });
+      expect(page2.notes.map((n) => n.id)).toEqual(["tb-c"]);
+    });
+
+    it("cursor advances correctly when notes share a millisecond on the page boundary", async () => {
+      // Two notes share the exact updated_at the cursor was minted at.
+      // The keyset predicate must include the larger-id one but NOT
+      // duplicate the cursor's own note.
+      const ts = "2026-04-15T12:34:56.789Z";
+      const a = await store.createNote("first-at-ts", { id: "ms-a" });
+      pinUpdatedAt(a.id, ts);
+
+      const page1 = await store.queryNotesPaged({ limit: 50 });
+      expect(page1.notes.map((n) => n.id)).toEqual(["ms-a"]);
+
+      // Now write a note that lands at the EXACT same updated_at (race
+      // window between pages). Its id sorts AFTER "ms-a".
+      const b = await store.createNote("second-at-same-ts", { id: "ms-b" });
+      pinUpdatedAt(b.id, ts);
+
+      const page2 = await store.queryNotesPaged({ cursor: page1.next_cursor });
+      // Must NOT include "ms-a" (we already saw it), MUST include "ms-b"
+      // (its id sorts after the cursor's last_id at the same timestamp).
+      expect(page2.notes.map((n) => n.id)).toEqual(["ms-b"]);
+    });
+
+    it("cursor invariance across reboots: a serialized cursor still resumes correctly", async () => {
+      // Cursors are self-contained — they don't reference any server-side
+      // state. Simulate a reboot by tearing down the DB+store and replaying
+      // the same data; the cursor minted on instance #1 must work against
+      // instance #2 with the same query.
+      const a1 = await store.createNote("note-1", { id: "reboot-1", path: "n1" });
+      pinUpdatedAt(a1.id, "2026-04-01T00:00:00.000Z");
+      const a2 = await store.createNote("note-2", { id: "reboot-2", path: "n2" });
+      pinUpdatedAt(a2.id, "2026-04-02T00:00:00.000Z");
+
+      const page1 = await store.queryNotesPaged({ limit: 1 });
+      expect(page1.notes.map((n) => n.id)).toEqual(["reboot-1"]);
+      const cursor = page1.next_cursor;
+
+      // Simulate a process restart with a fresh DB seeded the same way.
+      db.close();
+      db = new Database(":memory:");
+      store = new SqliteStore(db);
+      const a1b = await store.createNote("note-1", { id: "reboot-1", path: "n1" });
+      pinUpdatedAt(a1b.id, "2026-04-01T00:00:00.000Z");
+      const a2b = await store.createNote("note-2", { id: "reboot-2", path: "n2" });
+      pinUpdatedAt(a2b.id, "2026-04-02T00:00:00.000Z");
+
+      // The cursor is opaque-but-portable: encodes only millis + id + hash,
+      // none of which depend on server-side session state.
+      const page2 = await store.queryNotesPaged({ limit: 1, cursor });
+      expect(page2.notes.map((n) => n.id)).toEqual(["reboot-2"]);
+    });
+
+    it("cursor mode rejects sort: desc (descending iteration would skip new writes)", async () => {
+      await store.createNote("a");
+      const page = await store.queryNotesPaged({});
+      try {
+        await store.queryNotesPaged({ cursor: page.next_cursor, sort: "desc" });
+        throw new Error("expected QueryError");
+      } catch (err: any) {
+        expect(err.name).toBe("QueryError");
+        expect(err.code).toBe("INVALID_QUERY");
+        expect(err.message.toLowerCase()).toContain("ascending");
+      }
+    });
+
+    it("cursor mode rejects orderBy (mutually exclusive with updated_at keyset)", async () => {
+      const { declareField } = await import("./indexed-fields.js");
+      declareField(db, "priority", "INTEGER", "task");
+      await store.createNote("a", { metadata: { priority: 1 } });
+      const page = await store.queryNotesPaged({});
+      try {
+        await store.queryNotesPaged({ cursor: page.next_cursor, orderBy: "priority" });
+        throw new Error("expected QueryError");
+      } catch (err: any) {
+        expect(err.name).toBe("QueryError");
+        expect(err.code).toBe("INVALID_QUERY");
+        expect(err.message.toLowerCase()).toContain("order_by");
+      }
+    });
+
+    it("cursor + tag filter: only notes matching the filter advance the watermark", async () => {
+      // Cursor pagination composes with the rest of the query — the
+      // watermark tracks the last note that matched the filter, not the
+      // last note in the vault.
+      const a = await store.createNote("task-1", { tags: ["task"], id: "ct-1" });
+      pinUpdatedAt(a.id, "2026-04-01T00:00:00.000Z");
+      const b = await store.createNote("not-a-task", { tags: ["other"], id: "ct-2" });
+      pinUpdatedAt(b.id, "2026-04-02T00:00:00.000Z");
+      const c = await store.createNote("task-2", { tags: ["task"], id: "ct-3" });
+      pinUpdatedAt(c.id, "2026-04-03T00:00:00.000Z");
+
+      const page1 = await store.queryNotesPaged({ tags: ["task"] });
+      expect(page1.notes.map((n) => n.id).sort()).toEqual(["ct-1", "ct-3"]);
+
+      const page2 = await store.queryNotesPaged({
+        tags: ["task"],
+        cursor: page1.next_cursor,
+      });
+      expect(page2.notes).toHaveLength(0);
+    });
+
+    it("query_hash is stable across key-order permutations of the same query", async () => {
+      // Two semantically-equivalent queries differing only in JS object key
+      // order must produce the same cursor binding — otherwise an SDK that
+      // reshuffles parameters between calls would silently invalidate the
+      // cursor.
+      const { computeQueryHash } = await import("./cursor.js");
+      const h1 = computeQueryHash({
+        tags: ["a", "b"],
+        path: "Projects",
+        metadata: { status: "open" },
+      });
+      const h2 = computeQueryHash({
+        metadata: { status: "open" },
+        path: "Projects",
+        tags: ["a", "b"],
+      });
+      expect(h1).toBe(h2);
+
+      // ...and tag-array order is irrelevant (different SDKs may sort).
+      const h3 = computeQueryHash({
+        tags: ["b", "a"],
+        path: "Projects",
+        metadata: { status: "open" },
+      });
+      expect(h3).toBe(h1);
+    });
+
+    it("MCP query-notes: cursor mode returns {notes, next_cursor} envelope", async () => {
+      await store.createNote("a", { id: "mcp-a" });
+      await store.createNote("b", { id: "mcp-b" });
+
+      const tools = generateMcpTools(store);
+      const query = tools.find((t) => t.name === "query-notes")!;
+
+      // First call without cursor returns flat array (legacy shape).
+      const firstResult = await query.execute({}) as unknown;
+      expect(Array.isArray(firstResult)).toBe(true);
+
+      // Get a cursor by minting one ourselves via the store.
+      const seed = await store.queryNotesPaged({});
+
+      // Second call with cursor returns the wrapped envelope.
+      const envelope = await query.execute({ cursor: seed.next_cursor }) as any;
+      expect(envelope).toHaveProperty("notes");
+      expect(envelope).toHaveProperty("next_cursor");
+      expect(Array.isArray(envelope.notes)).toBe(true);
+      // No new writes since seed → empty page, cursor still advances.
+      expect(envelope.notes).toHaveLength(0);
+      expect(typeof envelope.next_cursor).toBe("string");
+    });
+  });
+
   it("limits results", async () => {
     for (let i = 0; i < 5; i++) await store.createNote(`Note ${i}`);
     const results = await store.queryNotes({ limit: 3 });