@vaur94/agz-memory 0.5.0 → 0.5.2

package/dist/core.js

@@ -734,7 +734,7 @@ function inspectDatabase(db) {
   }
   return { integrity, foreignKeyViolations, schemaVersion, counts };
 }
-function assertHealthyDatabase(db) {
+function assertHealthyDatabase(db, options = {}) {
   const health = inspectDatabase(db);
   if (health.integrity !== "ok") {
     throw new Error(`database integrity check failed: ${health.integrity}`);
@@ -742,7 +742,7 @@ function assertHealthyDatabase(db) {
   if (health.foreignKeyViolations.length > 0) {
     throw new Error(`database foreign key check failed: ${health.foreignKeyViolations.length} violation(s)`);
   }
-  if (health.schemaVersion === 11)
+  if (options.verifySchema !== false && health.schemaVersion === 11)
     assertSchemaV11(db);
   return health;
 }
@@ -2169,7 +2169,7 @@ var V9_V10_COLUMNS = {
     "completed_at"
   ]
 };
-function assertLegacySchemaIdentity(db, version) {
+function assertLegacySchemaIdentity(db, version, options = {}) {
   if (version < 2 || version > 10)
     throw new Error("unrecognized_database");
   const applicationID = db.query("PRAGMA application_id").get().application_id;
@@ -2177,12 +2177,14 @@ function assertLegacySchemaIdentity(db, version) {
     throw new Error("unrecognized_database");
   if (version === 2 && tableExists(db, "memory_items")) {
     assertV2Identity(db);
-    assertHealthyDatabase(db);
+    if (options.verifyHealth)
+      assertHealthyDatabase(db);
     return;
   }
   if (version < 8) {
     assertPreV8Identity(db, version);
-    assertHealthyDatabase(db);
+    if (options.verifyHealth)
+      assertHealthyDatabase(db);
     return;
   }
   const states = db.query("SELECT version FROM schema_state").all();
@@ -2207,7 +2209,8 @@ function assertLegacySchemaIdentity(db, version) {
       throw new Error("unrecognized_database");
     }
   }
-  assertHealthyDatabase(db);
+  if (options.verifyHealth)
+    assertHealthyDatabase(db);
   if (version === 10)
     assertV10SourceDatabase(db);
 }
@@ -3375,7 +3378,7 @@ function migrateV9ToV10(db) {
 }
 
 // src/version.ts
-var PRODUCT_VERSION = "0.5.0";
+var PRODUCT_VERSION = "0.5.2";
 
 // src/db.ts
 var DDL = `
@@ -3418,15 +3421,25 @@ CREATE INDEX IF NOT EXISTS note_edges_target_idx ON note_edges(project_id, targe
 CREATE TABLE IF NOT EXISTS schema_state (version INTEGER PRIMARY KEY);
 `;
 var PRE_OPEN_PROBE_TIMEOUT_MS = 5000;
-function openMemoryDatabase(path) {
+function timeMigrationStage(timing, stage, work) {
+  if (!timing)
+    return work();
+  const started = performance.now();
+  try {
+    return work();
+  } finally {
+    timing.phases.push({ stage, elapsedMs: Math.round((performance.now() - started) * 1000) / 1000 });
+  }
+}
+function openMemoryDatabase(path, options = {}) {
   ensureDatabaseParent(path);
-  assertSupportedDatabaseBeforeOpen(path);
+  assertSupportedDatabaseBeforeOpen(path, false);
   recoverStaleMaintenanceGate(path, () => assertSupportedDatabaseBeforeOpen(path));
   let lock = acquireMigrationLock(path, SCHEMA_VERSION);
   let lease = acquireDatabaseLease(path);
   let db;
   try {
-    assertSupportedDatabaseBeforeOpen(path);
+    assertSupportedDatabaseBeforeOpen(path, false);
     db = openDatabase(path);
   } catch (error) {
     lease.release();
@@ -3448,7 +3461,7 @@ function openMemoryDatabase(path) {
       lease.release();
       lease = undefined;
       lease = acquireDatabaseLease(path);
-      assertSupportedDatabaseBeforeOpen(path);
+      assertSupportedDatabaseBeforeOpen(path, false);
       db = openDatabase(path);
       dbOpen = true;
       if (hasApplicationObjects(db)) {
@@ -3498,7 +3511,7 @@ function openMemoryDatabase(path) {
       lease.release();
       lease = undefined;
       lease = acquireDatabaseLease(path);
-      assertSupportedDatabaseBeforeOpen(path);
+      assertSupportedDatabaseBeforeOpen(path, false);
       db = openDatabase(path);
       dbOpen = true;
       let migrationVersion = getSchemaVersion(db);
@@ -3526,7 +3539,7 @@ function openMemoryDatabase(path) {
       lease.release();
       lease = undefined;
       maintenance = acquireMaintenanceGate(path);
-      assertSupportedDatabaseBeforeOpen(path);
+      timeMigrationStage(options.timing, "source-validation", () => assertSupportedDatabaseBeforeOpen(path, false));
       db = openDatabase(path);
       dbOpen = true;
       migrationVersion = getSchemaVersion(db);
@@ -3556,12 +3569,12 @@ function openMemoryDatabase(path) {
         lease = undefined;
         return opened3;
       }
-      backup = createVerifiedBackup(db, path, migrationVersion?.version ?? 2, SCHEMA_VERSION, PRODUCT_VERSION);
+      backup = timeMigrationStage(options.timing, "backup-checkpoint", () => createVerifiedBackup(db, path, migrationVersion?.version ?? 2, SCHEMA_VERSION, PRODUCT_VERSION));
       db.exec("PRAGMA foreign_keys=OFF");
       if (!migrationVersion && hasLegacyV2(db)) {
         db.exec(DDL);
         db.exec("CREATE VIRTUAL TABLE IF NOT EXISTS notes_fts USING fts5(id UNINDEXED, title, summary, content, tokenize='unicode61')");
-        migrateFromV2(db, path);
+        timeMigrationStage(options.timing, "v2-import", () => migrateFromV2(db, path));
       } else if (!migrationVersion) {
         db.exec(DDL);
         db.exec("CREATE VIRTUAL TABLE IF NOT EXISTS notes_fts USING fts5(id UNINDEXED, title, summary, content, tokenize='unicode61')");
@@ -3577,24 +3590,25 @@ function openMemoryDatabase(path) {
       }
       let version = getSchemaVersion(db)?.version ?? 8;
       if (version < 9) {
-        db.transaction(() => migrateV8ToV9(db))();
+        timeMigrationStage(options.timing, "v8-to-v9", () => db.transaction(() => migrateV8ToV9(db))());
         version = 9;
       }
       if (version < 10) {
-        db.transaction(() => migrateV9ToV10(db))();
+        timeMigrationStage(options.timing, "v9-to-v10", () => db.transaction(() => migrateV9ToV10(db))());
         version = 10;
       }
       if (version < SCHEMA_VERSION) {
-        db.transaction(() => {
+        timeMigrationStage(options.timing, "v10-to-v11", () => db.transaction(() => {
           db.exec(`PRAGMA application_id = ${APPLICATION_ID}`);
           migrateV10ToV11(db);
-        })();
+        })());
       }
       db.exec("PRAGMA foreign_keys=ON");
       if (db.query("PRAGMA foreign_keys").get().foreign_keys !== 1) {
         throw new Error("failed to enable database foreign keys");
       }
-      assertHealthyDatabase(db);
+      timeMigrationStage(options.timing, "fingerprint", () => assertSchemaV11(db));
+      timeMigrationStage(options.timing, "deep-health", () => assertHealthyDatabase(db, { verifySchema: false }));
       console.warn(`[agz-memory] migrated to v${SCHEMA_VERSION} (backup: ${backup.manifestPath})`);
       backup = undefined;
       db.close();
@@ -3680,11 +3694,11 @@ function openDatabase(path) {
     throw error;
   }
 }
-function assertSupportedDatabaseBeforeOpen(path) {
+function assertSupportedDatabaseBeforeOpen(path, verifyHealth = true) {
   const deadline = Date.now() + PRE_OPEN_PROBE_TIMEOUT_MS;
   while (true) {
     try {
-      assertSupportedDatabaseBeforeOpenOnce(path);
+      assertSupportedDatabaseBeforeOpenOnce(path, verifyHealth);
       return;
     } catch (error) {
       if (!isSQLiteBusyError(error) || Date.now() >= deadline)
@@ -3693,19 +3707,19 @@ function assertSupportedDatabaseBeforeOpen(path) {
     }
   }
 }
-function assertSupportedDatabaseBeforeOpenOnce(path) {
+function assertSupportedDatabaseBeforeOpenOnce(path, verifyHealth) {
   assertDatabasePath(path);
   if (!existsSync4(path))
     return;
   const db = new Database3(path, { readonly: true });
   try {
     assertDatabasePath(path);
-    assertSupportedDatabase(db);
+    assertSupportedDatabase(db, verifyHealth);
   } finally {
     db.close();
   }
 }
-function assertSupportedDatabase(db) {
+function assertSupportedDatabase(db, verifyHealth = true) {
   const existingVersion = getSchemaVersion(db);
   if (existingVersion && existingVersion.version > SCHEMA_VERSION) {
     throw new Error(`database schema v${existingVersion.version} is newer than supported v${SCHEMA_VERSION}`);
@@ -3716,7 +3730,7 @@ function assertSupportedDatabase(db) {
   if (!existingVersion) {
     if (!hasLegacyV2(db))
       throw new Error("unrecognized_database");
-    assertLegacySchemaIdentity(db, 2);
+    assertLegacySchemaIdentity(db, 2, { verifyHealth });
     return;
   }
   if (existingVersion.version === SCHEMA_VERSION || hasV11Marker) {
@@ -3726,7 +3740,7 @@ function assertSupportedDatabase(db) {
   if (existingVersion.version < 2 || existingVersion.version > 10) {
     throw new Error("unrecognized_database");
   }
-  assertLegacySchemaIdentity(db, existingVersion.version);
+  assertLegacySchemaIdentity(db, existingVersion.version, { verifyHealth });
 }
 function assertDatabasePath(path) {
   try {
@@ -4086,13 +4100,341 @@ function takeHead(value, maxCharacters) {
   return value.slice(0, offset);
 }
 
+// src/config.ts
+import { homedir } from "os";
+import { join as join3 } from "path";
+function resolveConfig(environment = process.env) {
+  const databasePath = environment.OPENCODE_MEMORY_DATABASE_PATH?.trim() || join3(environment.HOME ?? homedir(), ".local", "share", "opencode-memory", "memory.sqlite");
+  const quarantineKeyringPath = environment.OPENCODE_MEMORY_QUARANTINE_KEYRING_PATH?.trim() || `${databasePath}.quarantine-keys`;
+  return { databasePath, quarantineKeyringPath };
+}
+
+// src/security/quarantine-key.ts
+import { createHmac, randomBytes, timingSafeEqual } from "crypto";
+import {
+  closeSync as closeSync3,
+  constants as constants3,
+  existsSync as existsSync5,
+  fchmodSync,
+  fstatSync as fstatSync2,
+  fsyncSync as fsyncSync3,
+  lstatSync as lstatSync4,
+  mkdirSync as mkdirSync4,
+  openSync as openSync3,
+  readFileSync as readFileSync4,
+  renameSync as renameSync4,
+  rmSync as rmSync3,
+  writeSync as writeSync2
+} from "fs";
+import { dirname as dirname3 } from "path";
+var KEYRING_FORMAT = "agz-memory.quarantine-keyring/1";
+var KEY_BYTES = 32;
+var KEY_ID_BYTES = 12;
+var MAX_KEYRING_BYTES = 64 * 1024;
+var KEY_MODE = 384;
+var LOCK_TIMEOUT_MS = 1000;
+var RETRIES = 20;
+
+class QuarantineKeyring {
+  path;
+  constructor(path) {
+    this.path = path;
+  }
+  readActiveKey() {
+    return this.keyReference(this.readDocument());
+  }
+  ensureActiveKey() {
+    let lastError;
+    for (let attempt = 0;attempt < RETRIES; attempt++) {
+      try {
+        return this.readActiveKey();
+      } catch (error) {
+        lastError = error;
+        if (!isKeyringError(error, "quarantine_keyring_missing")) {
+          if (attempt + 1 < RETRIES) {
+            pause();
+            continue;
+          }
+          throw error;
+        }
+      }
+      try {
+        this.createInitialKeyring();
+      } catch (error) {
+        lastError = error;
+        if (!isKeyringError(error, "quarantine_keyring_exists"))
+          throw error;
+      }
+      pause();
+    }
+    throw lastError instanceof Error ? lastError : new Error("quarantine_keyring_unavailable");
+  }
+  rotate() {
+    this.assertSupportedPlatform();
+    const lockPath = `${this.path}.lock`;
+    const lock = this.acquireLock(lockPath);
+    try {
+      const document = this.readDocument();
+      const keyID = randomBytes(KEY_ID_BYTES).toString("hex");
+      document.keys[keyID] = randomBytes(KEY_BYTES).toString("base64");
+      document.activeKeyID = keyID;
+      this.writeAtomically(document);
+      return { keyID };
+    } finally {
+      closeSync3(lock);
+      rmSync3(lockPath, { force: true });
+    }
+  }
+  digestSource(source, payloadFingerprint) {
+    const active = this.activeKey(true);
+    return digestSourceWithKey(source, payloadFingerprint, active);
+  }
+  digestExistingSource(source, payloadFingerprint) {
+    const active = this.activeKey(false);
+    return digestSourceWithKey(source, payloadFingerprint, active);
+  }
+  verifySourceDigest(source, payloadFingerprint, keyID, digest) {
+    if (!isPayloadFingerprint(payloadFingerprint) || !/^[0-9a-f]{24}$/.test(keyID) || !/^[0-9a-f]{64}$/.test(digest)) {
+      return false;
+    }
+    const document = this.readDocument();
+    const encoded = document.keys[keyID];
+    if (!encoded)
+      return false;
+    const expected = createHmac("sha256", Buffer.from(encoded, "base64")).update(sourceDigestBytes(source, payloadFingerprint)).digest();
+    return timingSafeEqual(expected, Buffer.from(digest, "hex"));
+  }
+  activeKey(createIfMissing) {
+    if (createIfMissing)
+      this.ensureActiveKey();
+    const document = this.readDocument();
+    const keyID = document.activeKeyID;
+    const encoded = document.keys[keyID];
+    if (!encoded)
+      throw new Error("quarantine_keyring_invalid");
+    return { keyID, key: Buffer.from(encoded, "base64") };
+  }
+  keyReference(document) {
+    if (!document.keys[document.activeKeyID])
+      throw new Error("quarantine_keyring_invalid");
+    return { keyID: document.activeKeyID };
+  }
+  createInitialKeyring() {
+    this.assertSupportedPlatform();
+    this.assertSafeParent();
+    const keyID = randomBytes(KEY_ID_BYTES).toString("hex");
+    const document = {
+      format: KEYRING_FORMAT,
+      activeKeyID: keyID,
+      keys: { [keyID]: randomBytes(KEY_BYTES).toString("base64") }
+    };
+    let fd;
+    try {
+      fd = openSync3(this.path, constants3.O_WRONLY | constants3.O_CREAT | constants3.O_EXCL | constants3.O_NOFOLLOW, KEY_MODE);
+      fchmodSync(fd, KEY_MODE);
+      writeSync2(fd, JSON.stringify(document));
+      fsyncSync3(fd);
+    } catch (error) {
+      if (error.code === "EEXIST") {
+        throw new Error("quarantine_keyring_exists");
+      }
+      throw error;
+    } finally {
+      if (fd !== undefined)
+        closeSync3(fd);
+    }
+  }
+  readDocument() {
+    this.assertSupportedPlatform();
+    let before;
+    try {
+      before = lstatSync4(this.path);
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        throw new Error("quarantine_keyring_missing");
+      }
+      throw new Error("quarantine_keyring_unavailable");
+    }
+    if (before.isSymbolicLink())
+      throw new Error("quarantine_keyring_symlink");
+    if (!before.isFile())
+      throw new Error("quarantine_keyring_not_regular");
+    this.assertPermissions(before.mode);
+    if (before.size <= 0 || before.size > MAX_KEYRING_BYTES) {
+      throw new Error("quarantine_keyring_invalid");
+    }
+    let fd;
+    try {
+      fd = openSync3(this.path, constants3.O_RDONLY | constants3.O_NOFOLLOW);
+      const opened = fstatSync2(fd);
+      if (!opened.isFile() || opened.dev !== before.dev || opened.ino !== before.ino || opened.size <= 0 || opened.size > MAX_KEYRING_BYTES) {
+        throw new Error("quarantine_keyring_toctou");
+      }
+      this.assertPermissions(opened.mode);
+      const bytes = readFileSync4(fd);
+      const after = fstatSync2(fd);
+      if (after.dev !== opened.dev || after.ino !== opened.ino || after.size !== opened.size) {
+        throw new Error("quarantine_keyring_toctou");
+      }
+      return parseKeyring(bytes);
+    } catch (error) {
+      if (error.code === "ELOOP") {
+        throw new Error("quarantine_keyring_symlink");
+      }
+      throw error;
+    } finally {
+      if (fd !== undefined)
+        closeSync3(fd);
+    }
+  }
+  writeAtomically(document) {
+    this.assertSafeParent();
+    const temporary = `${this.path}.${process.pid}.${randomBytes(8).toString("hex")}.tmp`;
+    let fd;
+    try {
+      fd = openSync3(temporary, constants3.O_WRONLY | constants3.O_CREAT | constants3.O_EXCL | constants3.O_NOFOLLOW, KEY_MODE);
+      fchmodSync(fd, KEY_MODE);
+      writeSync2(fd, JSON.stringify(document));
+      fsyncSync3(fd);
+      closeSync3(fd);
+      fd = undefined;
+      renameSync4(temporary, this.path);
+      this.syncParent();
+    } finally {
+      if (fd !== undefined)
+        closeSync3(fd);
+      rmSync3(temporary, { force: true });
+    }
+  }
+  acquireLock(lockPath) {
+    this.assertSafeParent();
+    const deadline = Date.now() + LOCK_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+      try {
+        const fd = openSync3(lockPath, constants3.O_WRONLY | constants3.O_CREAT | constants3.O_EXCL | constants3.O_NOFOLLOW, KEY_MODE);
+        fchmodSync(fd, KEY_MODE);
+        return fd;
+      } catch (error) {
+        if (error.code !== "EEXIST")
+          throw error;
+        pause();
+      }
+    }
+    throw new Error("quarantine_keyring_busy");
+  }
+  assertSafeParent() {
+    const parent = dirname3(this.path);
+    if (!existsSync5(parent))
+      mkdirSync4(parent, { recursive: true, mode: 448 });
+    const stat = lstatSync4(parent);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) {
+      throw new Error("quarantine_keyring_parent_unsafe");
+    }
+  }
+  assertSupportedPlatform() {
+    if (process.platform === "win32") {
+      throw new Error("quarantine_keyring_platform_unsupported");
+    }
+  }
+  assertPermissions(mode) {
+    if ((mode & 511) !== KEY_MODE)
+      throw new Error("quarantine_keyring_permissions");
+  }
+  syncParent() {
+    let fd;
+    try {
+      fd = openSync3(dirname3(this.path), constants3.O_RDONLY);
+      fsyncSync3(fd);
+    } catch {} finally {
+      if (fd !== undefined)
+        closeSync3(fd);
+    }
+  }
+}
+function digestSourceWithKey(source, payloadFingerprint, active) {
+  if (!isPayloadFingerprint(payloadFingerprint)) {
+    throw new Error("quarantine_payload_fingerprint_invalid");
+  }
+  return {
+    keyID: active.keyID,
+    digest: createHmac("sha256", active.key).update(sourceDigestBytes(source, payloadFingerprint)).digest("hex")
+  };
+}
+function parseKeyring(bytes) {
+  let value;
+  try {
+    value = JSON.parse(bytes.toString("utf8"));
+  } catch {
+    throw new Error("quarantine_keyring_invalid");
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("quarantine_keyring_invalid");
+  }
+  const record = value;
+  if (record.format !== KEYRING_FORMAT || typeof record.activeKeyID !== "string" || !record.keys || typeof record.keys !== "object" || Array.isArray(record.keys) || Object.keys(record).length !== 3) {
+    throw new Error("quarantine_keyring_invalid");
+  }
+  const keys = record.keys;
+  if (!/^[0-9a-f]{24}$/.test(record.activeKeyID)) {
+    throw new Error("quarantine_keyring_invalid");
+  }
+  for (const [keyID, encoded] of Object.entries(keys)) {
+    if (!/^[0-9a-f]{24}$/.test(keyID) || typeof encoded !== "string" || !isCanonicalKey(encoded)) {
+      throw new Error("quarantine_keyring_invalid");
+    }
+  }
+  if (typeof keys[record.activeKeyID] !== "string") {
+    throw new Error("quarantine_keyring_invalid");
+  }
+  return {
+    format: KEYRING_FORMAT,
+    activeKeyID: record.activeKeyID,
+    keys
+  };
+}
+function isCanonicalKey(value) {
+  const key = Buffer.from(value, "base64");
+  return key.length === KEY_BYTES && key.toString("base64") === value;
+}
+function sourceDigestBytes(source, payloadFingerprint) {
+  return Buffer.from(JSON.stringify([
+    "quarantine-source-payload/2",
+    source.schema,
+    source.projectID,
+    source.bindingKey,
+    source.kind,
+    source.source.system,
+    source.source.opencodeVersion,
+    source.source.pluginVersion,
+    source.source.sessionID,
+    source.source.messageID ?? null,
+    source.source.ordinal ?? null,
+    source.source.toolCallID ?? null,
+    payloadFingerprint
+  ]), "utf8");
+}
+function isPayloadFingerprint(value) {
+  return /^[0-9a-f]{64}$/.test(value);
+}
+function isKeyringError(error, code) {
+  return error instanceof Error && error.message === code;
+}
+function pause() {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);
+}
+
 // src/store/capture.ts
 class CaptureStore {
   db;
   indexBackends;
-  constructor(db, indexBackends = []) {
+  quarantineKeyring;
+  constructor(db, indexBackends = [], options = {}) {
     this.db = db;
     this.indexBackends = indexBackends;
+    this.quarantineKeyring = options.quarantineKeyring ?? new QuarantineKeyring(resolveConfig().quarantineKeyringPath);
+    try {
+      this.quarantineKeyring.ensureActiveKey();
+    } catch {}
   }
   bindProject(input) {
     const workspaceID = input.workspaceID ?? "";
@@ -4273,7 +4615,7 @@ class CaptureStore {
     }
     if (!this.binding(parsed.bindingKey, parsed.projectID))
       throw new Error("binding_conflict");
-    const prepared = prepareForPersistence(parsed, options.denylist);
+    const prepared = prepareForPersistence(parsed, options.denylist, this.quarantineKeyring);
     const now = Date.now();
     let result = {
       outcome: prepared.quarantined ? "quarantined" : "shadowed",
@@ -4288,13 +4630,13 @@ class CaptureStore {
            generation, created_at, updated_at, processed_at)
         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 0, 0, ?, ?, ?)
         ON CONFLICT DO NOTHING
-      `).run(prepared.event.idempotencyKey, prepared.event.schema, prepared.event.projectID, prepared.event.bindingKey, prepared.event.kind, prepared.event.source.sessionID, prepared.event.source.messageID ?? null, prepared.event.source.ordinal ?? null, prepared.event.source.toolCallID ?? null, prepared.payload, prepared.payloadHash, REDACTION_POLICY_VERSION, prepared.quarantined ? "quarantined" : "pending", now, now, prepared.quarantined ? now : null);
+      `).run(prepared.event.idempotencyKey, prepared.event.schema, prepared.event.projectID, prepared.event.bindingKey, prepared.event.kind, prepared.event.source.sessionID, prepared.event.source.messageID ?? null, prepared.event.source.ordinal ?? null, prepared.event.source.toolCallID ?? null, prepared.payload, prepared.payloadHash, prepared.redactionVersion, prepared.quarantined ? "quarantined" : "pending", now, now, prepared.quarantined ? now : null);
       if (inserted.changes === 0) {
         const existing = this.db.query(`SELECT contract, project_id, binding_key, event_kind, source_session_id,
                     source_message_id, source_ordinal, source_tool_call_id,
                     payload_json, payload_hash, redaction_version, note_id
                FROM capture_events WHERE idempotency_key = ?`).get(parsed.idempotencyKey);
-        if (!existing || !samePersistedCapture(existing, prepared.event, prepared.payload, prepared.payloadHash)) {
+        if (!existing || !samePersistedCapture(existing, prepared.event, prepared.payload, prepared.payloadHash, prepared.redactionVersion, prepared.payloadFingerprint, this.quarantineKeyring)) {
           throw new Error("idempotency_conflict");
         }
         result = {
@@ -4459,6 +4801,9 @@ class CaptureStore {
          supersedes_id, current_revision, subject_key, content_hash, created_at, updated_at)
       VALUES (?, ?, ?, ?, ?, ?, ?, 0, 'active', ?, 1, ?, ?, ?, ?)
     `).run(id, event.projectID, candidate.kind, candidate.title, candidate.summary, candidate.content, sizeClass, supersedesID, subjectKey, contentHash, now, now);
+    this.db.query(`UPDATE projects
+          SET updated_at = CASE WHEN updated_at >= ? THEN updated_at + 1 ELSE ? END
+        WHERE id = ?`).run(now, now, event.projectID);
     this.recordRevision(event, id, now);
     return id;
   }
@@ -4535,7 +4880,7 @@ class CaptureStore {
     return rows[0];
   }
 }
-function prepareForPersistence(event, denylist) {
+function prepareForPersistence(event, denylist, quarantineKeyring) {
   const copy = structuredClone(event);
   let replacements = 0;
   let truncated = copy.redaction.truncated;
@@ -4576,11 +4921,28 @@ function prepareForPersistence(event, denylist) {
     truncated
   };
   const validated = parseCaptureEvent(copy);
+  const payloadFingerprint = capturePayloadHash2(validated);
+  let payloadHash = payloadFingerprint;
+  let redactionVersion = REDACTION_POLICY_VERSION;
+  if (quarantined) {
+    let keyID = "unavailable";
+    payloadHash = null;
+    try {
+      const keyed = quarantineKeyring?.digestExistingSource(validated, payloadFingerprint);
+      if (keyed) {
+        keyID = keyed.keyID;
+        payloadHash = keyed.digest;
+      }
+    } catch {}
+    redactionVersion = quarantineRedactionVersion(keyID);
+  }
   const payload = quarantined ? null : JSON.stringify(validated);
   return {
     event: validated,
     payload,
-    payloadHash: capturePayloadHash2(validated),
+    payloadHash,
+    redactionVersion,
+    payloadFingerprint,
     quarantined,
     additionalReplacements: replacements
   };
@@ -4654,9 +5016,34 @@ function captureKeyForEvent(event) {
     terminalStatus: event.signal.status
   });
 }
-function samePersistedCapture(existing, event, payload, payloadHash) {
-  const retainedLegacyPayload = existing.payload_json === null && existing.payload_hash === null;
-  return existing.contract === event.schema && existing.project_id === event.projectID && existing.binding_key === event.bindingKey && existing.event_kind === event.kind && existing.source_session_id === event.source.sessionID && existing.source_message_id === (event.source.messageID ?? null) && existing.source_ordinal === (event.source.ordinal ?? null) && existing.source_tool_call_id === (event.source.toolCallID ?? null) && (retainedLegacyPayload || sameCapturePayload(existing.payload_json, existing.payload_hash, payload, payloadHash) && existing.redaction_version === REDACTION_POLICY_VERSION);
+function samePersistedCapture(existing, event, payload, payloadHash, redactionVersion, payloadFingerprint, quarantineKeyring) {
+  const retainedLegacyPayload = existing.payload_json === null && existing.payload_hash === null && !isQuarantineRedactionVersion(existing.redaction_version);
+  return existing.contract === event.schema && existing.project_id === event.projectID && existing.binding_key === event.bindingKey && existing.event_kind === event.kind && existing.source_session_id === event.source.sessionID && existing.source_message_id === (event.source.messageID ?? null) && existing.source_ordinal === (event.source.ordinal ?? null) && existing.source_tool_call_id === (event.source.toolCallID ?? null) && (retainedLegacyPayload || sameCapturePayload(existing.payload_json, existing.payload_hash, payload, payloadHash) && existing.redaction_version === redactionVersion || sameKeyedQuarantinedCapture(existing, event, payload, payloadHash, redactionVersion, payloadFingerprint, quarantineKeyring));
+}
+function sameKeyedQuarantinedCapture(existing, event, payload, payloadHash, redactionVersion, payloadFingerprint, quarantineKeyring) {
+  if (payload !== null || existing.payload_json !== null || payloadHash === null || existing.payload_hash === null || !isCurrentKeyedQuarantineVersion(existing.redaction_version) || !isCurrentKeyedQuarantineVersion(redactionVersion)) {
+    return false;
+  }
+  const keyID = quarantineKeyID(existing.redaction_version);
+  if (!keyID)
+    return false;
+  try {
+    return quarantineKeyring.verifySourceDigest(event, payloadFingerprint, keyID, existing.payload_hash);
+  } catch {
+    return false;
+  }
+}
+function quarantineRedactionVersion(keyID) {
+  return `${REDACTION_POLICY_VERSION};quarantine-key=${keyID};quarantine-digest=2`;
+}
+function isQuarantineRedactionVersion(value) {
+  return /^redaction\/1;quarantine-key=(?:[0-9a-f]{24}|unavailable)(?:;quarantine-digest=2)?$/.test(value);
+}
+function isCurrentKeyedQuarantineVersion(value) {
+  return /^redaction\/1;quarantine-key=[0-9a-f]{24};quarantine-digest=2$/.test(value);
+}
+function quarantineKeyID(value) {
+  return /^redaction\/1;quarantine-key=([0-9a-f]{24});quarantine-digest=2$/.exec(value)?.[1];
 }
 function sameCapturePayload(existingPayload, existingHash, payload, payloadHash) {
   if (existingHash !== null && existingHash === payloadHash)
@@ -4694,6 +5081,172 @@ function derivedHash(note) {
 
 // src/store.ts
 import { randomUUID as randomUUID8 } from "crypto";
+
+// src/contracts/limits.ts
+import * as z2 from "zod/v4";
+var LIMITS = {
+  title: 240,
+  summary: 4096,
+  content: 65536,
+  query: 4096,
+  noteID: 256,
+  batch: 10,
+  requestBytes: 1048576,
+  responseBytes: 1048576,
+  pageSize: 100
+};
+function utf8Bytes(value) {
+  return Buffer.byteLength(value, "utf8");
+}
+function assertTextLimit(field, value) {
+  const maximum = LIMITS[field];
+  if (utf8Bytes(value) > maximum)
+    throw new RangeError(`${field} exceeds ${maximum} UTF-8 bytes`);
+}
+function boundedText(field, description) {
+  return z2.string().superRefine((value, context) => {
+    if (utf8Bytes(value) > LIMITS[field]) {
+      context.addIssue({ code: "custom", message: `${field} exceeds ${LIMITS[field]} UTF-8 bytes` });
+    }
+  }).describe(description);
+}
+function assertRequestLimit(value) {
+  if (utf8Bytes(JSON.stringify(value)) > LIMITS.requestBytes) {
+    throw new RangeError(`request exceeds ${LIMITS.requestBytes} UTF-8 bytes`);
+  }
+}
+
+// src/contracts/pagination.ts
+import { createHmac as createHmac2, randomBytes as randomBytes2, timingSafeEqual as timingSafeEqual2 } from "crypto";
+var CURSOR_VERSION = 1;
+var CURSOR_KEY = randomBytes2(32);
+var MAX_CURSOR_BYTES = 2048;
+function encodeCursor(payload) {
+  const body = Buffer.from(JSON.stringify({ v: CURSOR_VERSION, ...payload }));
+  const signature = createHmac2("sha256", CURSOR_KEY).update(body).digest();
+  return Buffer.concat([body, signature]).toString("base64url");
+}
+function decodeCursor(cursor, scope) {
+  let payload;
+  try {
+    if (Buffer.byteLength(cursor, "utf8") > MAX_CURSOR_BYTES)
+      throw new Error;
+    const encoded = Buffer.from(cursor, "base64url");
+    if (encoded.length <= 32)
+      throw new Error;
+    const body = encoded.subarray(0, -32);
+    const signature = encoded.subarray(-32);
+    const expected = createHmac2("sha256", CURSOR_KEY).update(body).digest();
+    if (!timingSafeEqual2(signature, expected))
+      throw new Error;
+    payload = JSON.parse(body.toString("utf8"));
+  } catch {
+    throw new TypeError("invalid_cursor");
+  }
+  if (payload.v !== CURSOR_VERSION || !Number.isSafeInteger(payload.offset) || payload.offset < 0)
+    throw new TypeError("invalid_cursor");
+  if (payload.projectID !== scope.projectID || payload.query !== scope.query) {
+    throw new TypeError("cursor_scope_mismatch");
+  }
+  if (payload.snapshot !== scope.snapshot)
+    throw new TypeError("stale_snapshot");
+  return { offset: payload.offset };
+}
+function paginate(items, options) {
+  if (!Number.isSafeInteger(options.limit) || options.limit < 1)
+    throw new RangeError("page limit must be positive");
+  if (options.requestedSnapshot !== undefined && options.requestedSnapshot !== options.snapshot) {
+    throw new TypeError("stale_snapshot");
+  }
+  const offset = options.cursor !== undefined ? decodeCursor(options.cursor, options).offset : 0;
+  const limit = Math.min(options.limit, LIMITS.pageSize);
+  const page = items.slice(offset, offset + limit);
+  const nextOffset = offset + page.length;
+  return {
+    items: page,
+    snapshot: options.snapshot,
+    etag: options.snapshot,
+    ...nextOffset < items.length ? { nextCursor: encodeCursor({ projectID: options.projectID, query: options.query, snapshot: options.snapshot, offset: nextOffset }) } : {}
+  };
+}
+
+// src/contracts/mutation.ts
+function normalizeLegacyMutation(input) {
+  const { id, delete: deleteFlag, confirmation, kind, title, summary, content } = input;
+  const hasEdits = kind !== undefined || title !== undefined || summary !== undefined || content !== undefined;
+  if (deleteFlag) {
+    if (!id)
+      throw new TypeError("id is required for delete");
+    if (hasEdits)
+      throw new TypeError("cannot combine delete with edits");
+    return { operation: "delete", id, confirmation };
+  }
+  if (id) {
+    if (!hasEdits)
+      throw new TypeError("patch requires changes");
+    return { operation: "patch", id, changes: { kind, title, summary, content } };
+  }
+  if (!kind || title === undefined || summary === undefined) {
+    throw new TypeError("create requires kind, title, and summary");
+  }
+  return { operation: "create", kind, title, summary, content };
+}
+function isMutationOperation(value) {
+  try {
+    assertStrictMutationOperation(value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function assertStrictMutationOperation(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new TypeError("invalid mutation");
+  const input = value;
+  if (input.operation !== "create" && input.operation !== "patch" && input.operation !== "delete") {
+    throw new TypeError("invalid mutation operation");
+  }
+  const operation = input.operation;
+  const allowed = {
+    create: ["operation", "kind", "title", "summary", "content"],
+    patch: ["operation", "id", "changes"],
+    delete: ["operation", "id", "confirmation"]
+  };
+  const invalid = Object.keys(input).some((key) => !allowed[operation].includes(key));
+  if (invalid)
+    throw new TypeError("invalid mutation keys");
+  if (input.operation === "create") {
+    if (!KINDS.includes(input.kind) || typeof input.title !== "string" || typeof input.summary !== "string") {
+      throw new TypeError("invalid create mutation");
+    }
+    if (input.content !== undefined && typeof input.content !== "string")
+      throw new TypeError("invalid create mutation");
+  }
+  if (input.operation === "patch") {
+    if (typeof input.id !== "string" || !input.id || !input.changes || typeof input.changes !== "object" || Array.isArray(input.changes)) {
+      throw new TypeError("patch requires changes");
+    }
+    const changes = input.changes;
+    if (Object.values(changes).every((value2) => value2 === undefined))
+      throw new TypeError("patch requires changes");
+    if (Object.keys(changes).some((key) => !["kind", "title", "summary", "content"].includes(key)))
+      throw new TypeError("invalid patch changes");
+    if (changes.kind !== undefined && !KINDS.includes(changes.kind))
+      throw new TypeError("invalid patch changes");
+    for (const key of ["title", "summary", "content"]) {
+      if (changes[key] !== undefined && typeof changes[key] !== "string")
+        throw new TypeError("invalid patch changes");
+    }
+  }
+  if (input.operation === "delete") {
+    if (typeof input.id !== "string" || !input.id)
+      throw new TypeError("id is required for delete");
+    if (input.confirmation !== undefined && typeof input.confirmation !== "string")
+      throw new TypeError("invalid delete confirmation");
+  }
+}
+
+// src/store.ts
 class MemoryStore {
   db;
   indexBackends;
@@ -4723,6 +5276,18 @@ class MemoryStore {
       pinnedCount: row.pinned_count
     }));
   }
+  listProjectsPage(limit, cursor, snapshot) {
+    const projects = this.listProjects();
+    const current = hashTuple("project-list-snapshot", 1, projects.flatMap((project) => [
+      project.projectID,
+      project.projectName,
+      project.createdAt,
+      project.updatedAt,
+      project.noteCount,
+      project.pinnedCount
+    ]));
+    return paginate(projects, { projectID: "__projects__", query: "", limit, cursor, snapshot: current, requestedSnapshot: snapshot });
+  }
   createProject(nameValue) {
     const reason = validateProjectName(nameValue);
     if (reason)
@@ -4767,7 +5332,12 @@ class MemoryStore {
     }
     const now = Date.now();
     try {
-      const updated = this.immediateTransaction(() => this.db.query("UPDATE projects SET name = ?, normalized_name = ?, updated_at = ? WHERE id = ? RETURNING *").get(name, normalizedName, now, projectID));
+      const updated = this.immediateTransaction(() => this.db.query(`UPDATE projects
+                  SET name = ?,
+                      normalized_name = ?,
+                      updated_at = CASE WHEN updated_at >= ? THEN updated_at + 1 ELSE ? END
+                WHERE id = ?
+                RETURNING *`).get(name, normalizedName, now, now, projectID));
       if (!updated)
         return { ok: false, reason: `project ${projectID} not found` };
       return { ok: true, project: rowToProject(updated) };
@@ -4825,14 +5395,14 @@ class MemoryStore {
       };
     });
   }
-  update(projectID, input) {
+  update(projectID, operation) {
     const project = this.getProjectRow(projectID);
     if (!project)
       return { ok: false, reason: `project ${projectID} not found` };
-    if (input.delete) {
-      if (!input.id)
-        return { ok: false, reason: "id is required for delete" };
-      const id2 = input.id;
+    assertStrictMutationOperation(operation);
+    if (operation.operation === "delete") {
+      const id2 = operation.id;
+      assertTextLimit("noteID", id2);
       const existing2 = this.getNoteRow(projectID, id2);
       if (!existing2)
         return {
@@ -4849,6 +5419,7 @@ class MemoryStore {
           };
         }
         const now2 = Date.now();
+        this.bumpProjectVersion(projectID, now2);
         for (const backend of this.indexBackends) {
           this.enqueueOutbox(backend, "delete-note", deleted.project_id, deleted.id, deleted.current_revision, null, now2);
         }
@@ -4861,31 +5432,35 @@ class MemoryStore {
         };
       });
     }
-    const existing = input.id ? this.getNoteRow(projectID, input.id) : undefined;
-    if (input.id && !existing) {
+    if (operation.operation === "patch")
+      assertTextLimit("noteID", operation.id);
+    const existing = operation.operation === "patch" ? this.getNoteRow(projectID, operation.id) : undefined;
+    if (operation.operation === "patch" && !existing) {
       return {
         ok: false,
-        reason: `note ${input.id} not found in project ${project.name}`
+        reason: `note ${operation.id} not found in project ${project.name}`
       };
     }
     if (existing && existing.status !== "active") {
       return { ok: false, reason: `note is ${existing.status}` };
     }
-    const kindValue = input.kind ?? existing?.kind;
+    const changes = operation.operation === "patch" ? operation.changes : undefined;
+    const kindValue = operation.operation === "create" ? operation.kind : changes?.kind ?? existing?.kind;
     const kind = KINDS.includes(kindValue ?? "") ? kindValue : null;
     if (!kind)
       return { ok: false, reason: `kind must be one of: ${KINDS.join(", ")}` };
-    const title = input.title === undefined ? existing?.title ?? "" : input.title.trim();
-    const summary = input.summary === undefined ? existing?.summary ?? "" : input.summary.trim();
-    const content = input.content === undefined ? existing?.content ?? summary : input.content.trim();
+    const title = operation.operation === "create" ? operation.title.trim() : changes?.title === undefined ? existing?.title ?? "" : changes.title.trim();
+    const summary = operation.operation === "create" ? operation.summary.trim() : changes?.summary === undefined ? existing?.summary ?? "" : changes.summary.trim();
+    const content = operation.operation === "create" ? (operation.content ?? summary).trim() : changes?.content === undefined ? existing?.content ?? summary : changes.content.trim();
     if (!title)
       return { ok: false, reason: "title is required" };
-    if (title.length > 240)
-      return { ok: false, reason: "title exceeds 240 characters" };
     if (!summary)
       return { ok: false, reason: "summary is required" };
     if (!content)
       return { ok: false, reason: "content is empty" };
+    assertTextLimit("title", title);
+    assertTextLimit("summary", summary);
+    assertTextLimit("content", content);
     const now = Date.now();
     const sizeClass = content.length <= INLINE_LIMIT ? "inline" : "indexed";
     const contentHash = noteContentHash(kind, title, summary, content);
@@ -4920,6 +5495,7 @@ class MemoryStore {
               RETURNING *`).get(kind, title, summary, content, sizeClass, subjectKey, contentHash, now, projectID, existing.id, existing.current_revision);
         if (!updated)
           return;
+        this.bumpProjectVersion(projectID, now);
         this.recordCurrentRevision(updated, "mcp-manual", now);
         const derived = deriveDocument({
           projectID: updated.project_id,
@@ -4965,6 +5541,7 @@ class MemoryStore {
     };
   }
   pin(projectID, id, pinned) {
+    assertTextLimit("noteID", id);
     const project = this.getProjectRow(projectID);
     if (!project)
       return { ok: false, reason: `project ${projectID} not found` };
@@ -4999,6 +5576,7 @@ class MemoryStore {
             RETURNING *`).get(pinned ? 1 : 0, now, projectID, id, note.current_revision);
       if (!updated)
         return;
+      this.bumpProjectVersion(projectID, now);
       this.recordCurrentRevision(updated, "mcp-manual", now);
       const derived = deriveDocument({
         projectID: updated.project_id,
@@ -5043,6 +5621,7 @@ class MemoryStore {
            RETURNING *`).get(id, projectID, kind, title, summary, content, sizeClass, supersedesID, subjectKey, contentHash, now, now);
       if (!note)
         throw new Error(`note ${id} insert returned no row`);
+      this.bumpProjectVersion(projectID, now);
       this.recordCurrentRevision(note, "mcp-manual", now);
       const derived = deriveDocument({
         projectID: note.project_id,
@@ -5062,19 +5641,43 @@ class MemoryStore {
     });
   }
   read(projectID, id) {
+    const page = this.readPage(projectID, id, LIMITS.pageSize);
+    if (!("note" in page))
+      return page;
+    return {
+      note: page.note,
+      edges: page.items,
+      snapshot: page.snapshot,
+      etag: page.etag,
+      nextCursor: page.nextCursor
+    };
+  }
+  readPage(projectID, id, limit, cursor, snapshot) {
+    assertTextLimit("noteID", id);
     const row = this.getNoteRow(projectID, id);
     if (!row)
       return { reason: `note ${id} not found in project ${projectID}` };
     const edges = this.db.query(`SELECT e.id, e.project_id, p.name AS project_name, e.source_id, e.target_id, e.predicate, e.created_at
-           FROM note_edges e
-           JOIN projects p ON p.id = e.project_id
-          WHERE e.project_id = ? AND (e.source_id = ? OR e.target_id = ?)`).all(projectID, id, id);
+            FROM note_edges e
+            JOIN projects p ON p.id = e.project_id
+           WHERE e.project_id = ? AND (e.source_id = ? OR e.target_id = ?)
+           ORDER BY e.created_at, e.id`).all(projectID, id, id);
+    const resultEdges = edges.map(rowToEdge);
+    const current = hashTuple("note-edge-snapshot", 1, [id, row.updated_at, ...resultEdges.flatMap((edge) => [edge.id, edge.projectID, edge.projectName, edge.sourceID, edge.targetID, edge.predicate, edge.createdAt])]);
     return {
       note: rowToNote(row),
-      edges: edges.map(rowToEdge)
+      ...paginate(resultEdges, { projectID, query: `edges:${id}`, limit, cursor, snapshot: current, requestedSnapshot: snapshot })
     };
   }
+  listRevisionsPage(projectID, noteID, limit, cursor, snapshot) {
+    assertTextLimit("noteID", noteID);
+    const rows = this.db.query("SELECT revision, created_at FROM note_revisions WHERE project_id = ? AND note_id = ? ORDER BY revision").all(projectID, noteID);
+    const current = hashTuple("note-revision-snapshot", 1, [noteID, ...rows.flatMap((row) => [row.revision, row.created_at])]);
+    return paginate(rows, { projectID, query: `revisions:${noteID}`, limit, cursor, snapshot: current, requestedSnapshot: snapshot });
+  }
   link(projectID, sourceID, targetID, predicate) {
+    assertTextLimit("noteID", sourceID);
+    assertTextLimit("noteID", targetID);
     const project = this.getProjectRow(projectID);
     if (!project)
       return { ok: false, reason: `project ${projectID} not found` };
@@ -5096,24 +5699,64 @@ class MemoryStore {
       if (row.status !== "active")
         return { ok: false, reason: `note ${id} is ${row.status}` };
     }
-    this.db.query("INSERT OR IGNORE INTO note_edges (id, project_id, source_id, target_id, predicate, created_at) VALUES (?, ?, ?, ?, ?, ?)").run(randomUUID8(), projectID, sourceID, targetID, predicate, Date.now());
+    this.immediateTransaction(() => {
+      const now = Date.now();
+      const inserted = this.db.query("INSERT OR IGNORE INTO note_edges (id, project_id, source_id, target_id, predicate, created_at) VALUES (?, ?, ?, ?, ?, ?)").run(randomUUID8(), projectID, sourceID, targetID, predicate, now);
+      if (inserted.changes > 0)
+        this.bumpProjectVersion(projectID, now);
+    });
     return { ok: true, projectID, projectName: project.name };
   }
   recall(projectID, query, limit = 10) {
+    return this.recallPage(projectID, query, limit).cards;
+  }
+  recallPage(projectID, query, limit = LIMITS.pageSize, cursor, snapshot) {
+    assertTextLimit("query", query);
+    if (!Number.isSafeInteger(limit) || limit < 1) {
+      return { cards: [], snapshot: hashTuple("recall-snapshot", 1, [projectID, query]), etag: hashTuple("recall-snapshot", 1, [projectID, query]) };
+    }
+    const pageLimit = Math.min(limit, LIMITS.pageSize);
     const tokens = query.split(/\s+/).map((token) => token.trim()).filter(Boolean).slice(0, 12).map((token) => `"${token.replace(/"/g, '""')}"`);
-    if (tokens.length === 0)
-      return [];
-    const matches = this.db.query(`SELECT n.*, p.name AS project_name, bm25(notes_fts) AS rank
+    if (tokens.length === 0) {
+      const current2 = hashTuple("recall-snapshot", 1, [projectID, query]);
+      return { cards: [], snapshot: current2, etag: current2 };
+    }
+    const project = this.getProjectRow(projectID);
+    const current = hashTuple("recall-snapshot", 2, [
+      projectID,
+      query,
+      project?.name ?? "",
+      project?.updated_at ?? 0
+    ]);
+    if (snapshot !== undefined && snapshot !== current)
+      throw new TypeError("stale_snapshot");
+    const offset = cursor !== undefined ? decodeCursor(cursor, { projectID, query, snapshot: current }).offset : 0;
+    const directCount = this.db.query(`SELECT COUNT(*) AS count
+         FROM notes_fts
+         JOIN notes n ON n.rowid = notes_fts.rowid
+        WHERE notes_fts MATCH ? AND n.project_id = ? AND n.status = 'active'`).get(tokens.join(" OR "), projectID).count;
+    const matches = offset < directCount ? this.db.query(`SELECT n.*, p.name AS project_name, bm25(notes_fts) AS rank
            FROM notes_fts
            JOIN notes n ON n.rowid = notes_fts.rowid
            JOIN projects p ON p.id = n.project_id
           WHERE notes_fts MATCH ? AND n.project_id = ? AND n.status = 'active'
-          ORDER BY n.pinned DESC, rank
-          LIMIT ?`).all(tokens.join(" OR "), projectID, limit);
+           ORDER BY n.pinned DESC, rank, n.id
+            LIMIT ? OFFSET ?`).all(tokens.join(" OR "), projectID, pageLimit, offset) : [];
     const cards = matches.map((row) => toCard(rowToNote(row), "match"));
-    const seen = new Set(cards.map((card) => card.id));
-    for (const match of matches.slice(0, 5)) {
-      const neighbors = this.db.query(`SELECT e.predicate, n.*, p.name AS project_name
+    const directRemaining = Math.max(0, directCount - offset);
+    const neighborOffset = Math.max(0, offset - directCount);
+    if (cards.length < pageLimit && directRemaining <= cards.length) {
+      const firstMatches = this.db.query(`SELECT n.*, p.name AS project_name, bm25(notes_fts) AS rank
+           FROM notes_fts
+           JOIN notes n ON n.rowid = notes_fts.rowid
+           JOIN projects p ON p.id = n.project_id
+          WHERE notes_fts MATCH ? AND n.project_id = ? AND n.status = 'active'
+          ORDER BY n.pinned DESC, rank, n.id
+          LIMIT 5`).all(tokens.join(" OR "), projectID);
+      const neighborsToAppend = [];
+      const seen = new Set;
+      for (const match of firstMatches) {
+        const neighbors = this.db.query(`SELECT e.predicate, n.*, p.name AS project_name
              FROM note_edges e
              JOIN notes n ON n.id = CASE WHEN e.source_id = ? THEN e.target_id ELSE e.source_id END
              JOIN projects p ON p.id = n.project_id
@@ -5121,22 +5764,49 @@ class MemoryStore {
               AND (e.source_id = ? OR e.target_id = ?)
               AND n.project_id = ?
               AND n.status = 'active'
-            ORDER BY n.pinned DESC
+             ORDER BY n.pinned DESC, n.updated_at DESC, n.id
             LIMIT 6`).all(match.id, projectID, match.id, match.id, projectID);
-      for (const neighbor of neighbors) {
-        if (seen.has(neighbor.id))
-          continue;
-        seen.add(neighbor.id);
-        const card = toCard(rowToNote(neighbor), "neighbor");
-        card.predicates = [neighbor.predicate];
-        cards.push(card);
+        for (const neighbor of neighbors) {
+          if (seen.has(neighbor.id))
+            continue;
+          const isDirectMatch = this.db.query(`SELECT 1
+             FROM notes_fts
+             JOIN notes n ON n.rowid = notes_fts.rowid
+            WHERE notes_fts MATCH ? AND n.project_id = ? AND n.id = ? AND n.status = 'active'`).get(tokens.join(" OR "), projectID, neighbor.id);
+          if (isDirectMatch)
+            continue;
+          seen.add(neighbor.id);
+          const card = toCard(rowToNote(neighbor), "neighbor");
+          card.predicates = [neighbor.predicate];
+          neighborsToAppend.push(card);
+        }
       }
+      cards.push(...neighborsToAppend.slice(neighborOffset, neighborOffset + (pageLimit - cards.length)));
+      const consumedNeighbors = neighborOffset + Math.max(0, cards.length - matches.length);
+      const hasMore2 = offset + matches.length < directCount || consumedNeighbors < neighborsToAppend.length;
+      return {
+        cards,
+        snapshot: current,
+        etag: current,
+        ...hasMore2 ? { nextCursor: encodeCursor({ projectID, query, snapshot: current, offset: offset + cards.length }) } : {}
+      };
     }
-    return cards.slice(0, limit + 5);
+    const hasMore = offset + cards.length < directCount;
+    return {
+      cards,
+      snapshot: current,
+      etag: current,
+      ...hasMore ? { nextCursor: encodeCursor({ projectID, query, snapshot: current, offset: offset + cards.length }) } : {}
+    };
   }
   getProjectRow(id) {
     return this.db.query("SELECT * FROM projects WHERE id = ?").get(id);
   }
+  bumpProjectVersion(projectID, now) {
+    this.db.query(`UPDATE projects
+          SET updated_at = CASE WHEN updated_at >= ? THEN updated_at + 1 ELSE ? END
+        WHERE id = ?`).run(now, now, projectID);
+  }
   getProjectByNormalizedName(normalizedName) {
     return this.db.query("SELECT * FROM projects WHERE normalized_name = ?").get(normalizedName);
   }
@@ -5261,6 +5931,8 @@ import { randomUUID as randomUUID9 } from "crypto";
 var LEASE_DURATION_MS = 30000;
 var BACKEND_TIMEOUT_MS = 5000;
 var HEARTBEAT_INTERVAL_MS = 1e4;
+var TERMINAL_OUTBOX_RETENTION = 1e4;
+var TERMINAL_OUTBOX_PRUNE_INTERVAL = 100;
 
 class OutboxWorker {
   db;
@@ -5268,11 +5940,21 @@ class OutboxWorker {
   now;
   random;
   workerID = randomUUID9();
-  constructor(db, backends, now = Date.now, random = Math.random) {
+  terminalRetention;
+  terminalPruneInterval;
+  terminalTransitions;
+  constructor(db, backends, now = Date.now, random = Math.random, retention = {}) {
     this.db = db;
     this.backends = backends;
     this.now = now;
     this.random = random;
+    this.terminalRetention = retention.terminalRetention ?? TERMINAL_OUTBOX_RETENTION;
+    this.terminalPruneInterval = retention.terminalPruneInterval ?? TERMINAL_OUTBOX_PRUNE_INTERVAL;
+    if (!Number.isSafeInteger(this.terminalRetention) || this.terminalRetention < 1)
+      throw new Error("outbox_terminal_retention_invalid");
+    if (!Number.isSafeInteger(this.terminalPruneInterval) || this.terminalPruneInterval < 1)
+      throw new Error("outbox_terminal_prune_interval_invalid");
+    this.terminalTransitions = this.terminalPruneInterval - 1;
     for (const backend of backends.values()) {
       if (backend.outboxProtocol !== "agz-memory-outbox/1") {
         throw new Error("outbox_backend_fencing_required");
@@ -5377,30 +6059,52 @@ class OutboxWorker {
     return transition === "succeeded" ? outcome : transition;
   }
   succeed(row) {
-    const result = this.db.query(`
-        UPDATE index_outbox
-           SET state = 'succeeded', completed_at = ?, lease_owner = NULL,
-               lease_expires_at = NULL, heartbeat_at = NULL, last_error_code = NULL
-         WHERE id = ? AND state = 'leased' AND lease_owner = ?
-           AND lease_generation = ? AND fence = ?
-      `).run(this.now(), row.id, this.workerID, row.lease_generation, row.fence);
-    return result.changes === 1 ? "succeeded" : "lost_lease";
+    let changed = false;
+    this.db.transaction(() => {
+      const result = this.db.query(`
+          UPDATE index_outbox
+             SET state = 'succeeded', completed_at = ?, lease_owner = NULL,
+                 lease_expires_at = NULL, heartbeat_at = NULL, last_error_code = NULL
+            WHERE id = ? AND state = 'leased' AND lease_owner = ?
+              AND lease_generation = ? AND fence = ?
+        `).run(this.now(), row.id, this.workerID, row.lease_generation, row.fence);
+      changed = result.changes === 1;
+      if (changed)
+        this.pruneTerminalOutbox();
+    })();
+    return changed ? "succeeded" : "lost_lease";
   }
   fail(row, errorCode) {
     const dead = row.attempt_count >= 10;
     const availableAt = this.now() + retryDelay(row.attempt_count, this.random());
-    const result = this.db.query(`
-        UPDATE index_outbox
-           SET state = ?, available_at = ?, lease_owner = NULL,
-               lease_expires_at = NULL, heartbeat_at = NULL,
-               last_error_code = ?, completed_at = ?
-         WHERE id = ? AND state = 'leased' AND lease_owner = ?
-           AND lease_generation = ? AND fence = ?
-      `).run(dead ? "dead" : "pending", availableAt, errorCode, dead ? this.now() : null, row.id, this.workerID, row.lease_generation, row.fence);
-    if (result.changes !== 1)
+    let changed = false;
+    this.db.transaction(() => {
+      const result = this.db.query(`
+          UPDATE index_outbox
+             SET state = ?, available_at = ?, lease_owner = NULL,
+                 lease_expires_at = NULL, heartbeat_at = NULL,
+                 last_error_code = ?, completed_at = ?
+            WHERE id = ? AND state = 'leased' AND lease_owner = ?
+              AND lease_generation = ? AND fence = ?
+        `).run(dead ? "dead" : "pending", availableAt, errorCode, dead ? this.now() : null, row.id, this.workerID, row.lease_generation, row.fence);
+      changed = result.changes === 1;
+      if (changed && dead)
+        this.pruneTerminalOutbox();
+    })();
+    if (!changed)
       return "lost_lease";
     return dead ? "dead" : "retry";
   }
+  pruneTerminalOutbox() {
+    this.terminalTransitions++;
+    if (this.terminalTransitions < this.terminalPruneInterval)
+      return;
+    this.terminalTransitions = 0;
+    this.db.query(`DELETE FROM index_outbox WHERE id IN (
+         SELECT id FROM index_outbox WHERE state IN ('succeeded', 'dead')
+         ORDER BY completed_at DESC, id DESC LIMIT -1 OFFSET ?
+       )`).run(this.terminalRetention);
+  }
 }
 function exportDocument(note) {
   return deriveDocument({
@@ -5544,6 +6248,7 @@ class RetrievalStore {
     this.backend = backend;
   }
   async retrieve(request) {
+    assertTextLimit("query", request.query);
     const query = request.query.trim();
     const limit = boundedCardLimit(request.limit);
     if (!query || limit === 0 || Date.now() >= request.deadlineAt) {
@@ -5912,6 +6617,46 @@ function escapeText(value) {
 function escapeAttribute(value) {
   return escapeText(value).replaceAll('"', "&quot;").replaceAll("'", "&#39;");
 }
+// src/contracts/error.ts
+class MemoryBusinessError extends Error {
+  code;
+  correlationID;
+  cause;
+  constructor(code, message, correlationID = newCorrelationID(), cause) {
+    super(message);
+    this.code = code;
+    this.correlationID = correlationID;
+    this.cause = cause;
+  }
+}
+function correlationID() {
+  return newCorrelationID();
+}
+function newCorrelationID() {
+  return crypto.randomUUID();
+}
+function businessError(code, message, id = correlationID(), cause) {
+  return new MemoryBusinessError(code, message, id, cause);
+}
+function toPublicError(error) {
+  return { code: error.code, correlationID: error.correlationID, retryable: error.code === "internal_error", message: error.message };
+}
+function asBusinessError(error, id = correlationID()) {
+  if (error instanceof MemoryBusinessError)
+    return error;
+  if (error instanceof RangeError)
+    return businessError("limit_exceeded", error.message, id, error);
+  if (error instanceof TypeError) {
+    if (error.message === "invalid_cursor")
+      return businessError("invalid_cursor", "cursor is invalid", id, error);
+    if (error.message === "cursor_scope_mismatch")
+      return businessError("cursor_scope_mismatch", "cursor does not match this request", id, error);
+    if (error.message === "stale_snapshot")
+      return businessError("stale_cursor", "cursor snapshot is stale", id, error);
+    return businessError("invalid_request", "request is invalid", id, error);
+  }
+  return businessError("internal_error", "memory operation failed", id, error);
+}
 
 // src/core.ts
 class MemoryCore {
@@ -5937,25 +6682,41 @@ function openMemoryCore(databasePath, options = {}) {
 }
 export {
   validateBackendHits,
+  utf8Bytes,
+  toPublicError,
   redactText,
   projectUserPrompt,
   projectToolSignal,
   projectSessionSummary,
   projectAssistantParts,
   parseCaptureEvent,
+  paginate,
   openMemoryCore,
   normalizeSubjectKey,
+  normalizeLegacyMutation,
+  isMutationOperation,
   formatUntrustedContext,
   extractExplicitUserCandidate,
+  encodeCursor,
+  decodeCursor,
+  correlationID,
   captureIdempotencyKey,
   captureEventSchema,
   canAutoWrite,
+  businessError,
+  boundedText,
+  assertTextLimit,
+  assertStrictMutationOperation,
+  assertRequestLimit,
+  asBusinessError,
   SUPPORTED_OPENCODE_VERSION,
   SCHEMA_VERSION,
   REDACTION_POLICY_VERSION,
   PRODUCT_VERSION,
   PREDICATES,
   MemoryCore,
+  MemoryBusinessError,
+  LIMITS,
   KINDS,
   INLINE_LIMIT,
   EXTRACTOR_VERSION,