@vaur94/agz-memory 0.5.0 → 0.5.1

package/dist/admin.js

@@ -2,14 +2,15 @@
 // @bun
 
 // src/admin/index.ts
-import { createHash as createHash7 } from "crypto";
+import { createHash as createHash8 } from "crypto";
 import { Database as Database4 } from "bun:sqlite";
 import {
   existsSync as existsSync5,
-  lstatSync as lstatSync4,
+  lstatSync as lstatSync5,
   readdirSync as readdirSync2,
-  readFileSync as readFileSync4,
-  rmSync as rmSync3
+  readFileSync as readFileSync5,
+  realpathSync,
+  rmSync as rmSync4
 } from "fs";
 import { basename as basename3, dirname as dirname3, resolve as resolve3 } from "path";
 
@@ -18,7 +19,8 @@ import { homedir } from "os";
 import { join } from "path";
 function resolveConfig(environment = process.env) {
   const databasePath = environment.OPENCODE_MEMORY_DATABASE_PATH?.trim() || join(environment.HOME ?? homedir(), ".local", "share", "opencode-memory", "memory.sqlite");
-  return { databasePath };
+  const quarantineKeyringPath = environment.OPENCODE_MEMORY_QUARANTINE_KEYRING_PATH?.trim() || `${databasePath}.quarantine-keys`;
+  return { databasePath, quarantineKeyringPath };
 }
 
 // src/db.ts
@@ -746,7 +748,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}`);
@@ -754,7 +756,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;
 }
@@ -2180,7 +2182,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;
@@ -2188,12 +2190,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();
@@ -2218,7 +2222,8 @@ function assertLegacySchemaIdentity(db, version) {
       throw new Error("unrecognized_database");
     }
   }
-  assertHealthyDatabase(db);
+  if (options.verifyHealth)
+    assertHealthyDatabase(db);
   if (version === 10)
     assertV10SourceDatabase(db);
 }
@@ -3416,7 +3421,7 @@ function migrateV9ToV10(db) {
 }
 
 // src/version.ts
-var PRODUCT_VERSION = "0.5.0";
+var PRODUCT_VERSION = "0.5.1";
 
 // src/db.ts
 var DDL = `
@@ -3459,15 +3464,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();
@@ -3489,7 +3504,7 @@ function openMemoryDatabase(path) {
       lease.release();
       lease = undefined;
       lease = acquireDatabaseLease(path);
-      assertSupportedDatabaseBeforeOpen(path);
+      assertSupportedDatabaseBeforeOpen(path, false);
       db = openDatabase(path);
       dbOpen = true;
       if (hasApplicationObjects(db)) {
@@ -3539,7 +3554,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);
@@ -3567,7 +3582,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);
@@ -3597,12 +3612,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')");
@@ -3618,24 +3633,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();
@@ -3743,11 +3759,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)
@@ -3756,19 +3772,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}`);
@@ -3779,7 +3795,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) {
@@ -3789,7 +3805,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 {
@@ -4274,17 +4290,550 @@ function derivedHashMismatches(db) {
   return mismatches;
 }
 
+// src/admin/quarantine.ts
+var KEYED_VERSION = /^redaction\/1;quarantine-key=([0-9a-f]{24});quarantine-digest=2$/;
+var UNAVAILABLE_VERSION = /^redaction\/1;quarantine-key=unavailable;quarantine-digest=2$/;
+function quarantinePrivacyReport(db) {
+  const rows = db.query(`SELECT redaction_version, COUNT(*) AS count
+         FROM capture_events
+        WHERE state = 'quarantined'
+        GROUP BY redaction_version`).all();
+  let quarantinedEvents = 0;
+  let keyedEvents = 0;
+  let unavailableKeyEvents = 0;
+  let legacyOrUnknownEvents = 0;
+  const keyIDs = new Set;
+  for (const row of rows) {
+    quarantinedEvents += row.count;
+    const keyed = KEYED_VERSION.exec(row.redaction_version);
+    if (keyed) {
+      keyedEvents += row.count;
+      keyIDs.add(keyed[1]);
+    } else if (UNAVAILABLE_VERSION.test(row.redaction_version)) {
+      unavailableKeyEvents += row.count;
+    } else {
+      legacyOrUnknownEvents += row.count;
+    }
+  }
+  return {
+    quarantinedEvents,
+    keyedEvents,
+    unavailableKeyEvents,
+    legacyOrUnknownEvents,
+    keyIDs: [...keyIDs].sort(),
+    digest: {
+      algorithm: "HMAC-SHA256",
+      input: "quarantine-source-identity-and-redacted-payload/2",
+      storage: "capture_events.payload_hash",
+      keyID: "capture_events.redaction_version quarantine-key suffix"
+    }
+  };
+}
+
+// src/admin/reindex.ts
+import { spawnSync } from "child_process";
+import { createHash as createHash7, randomUUID as randomUUID7 } from "crypto";
+import {
+  closeSync as closeSync3,
+  constants as constants3,
+  fsyncSync as fsyncSync3,
+  fstatSync as fstatSync2,
+  lstatSync as lstatSync4,
+  mkdirSync as mkdirSync4,
+  openSync as openSync3,
+  readFileSync as readFileSync4,
+  renameSync as renameSync4,
+  rmSync as rmSync3,
+  writeSync as writeSync2
+} from "fs";
+import { hostname as hostname3 } from "os";
+import { join as join4 } from "path";
+var MAX_BATCH_SIZE = 500;
+function classifyReindexOwner(owner, localHostname, processAlive, currentProcessStart) {
+  if (!isOwnerMetadata(owner) || owner.hostname !== localHostname)
+    return "unverifiable";
+  if (!processAlive)
+    return "stale";
+  if (!currentProcessStart)
+    return "unverifiable";
+  return currentProcessStart === owner.processStart ? "live" : "stale";
+}
+function runResumableReindex(path, databaseID, backend, batchSize, maxBatches, testOptions = {}) {
+  if (!Number.isSafeInteger(batchSize) || batchSize < 1 || batchSize > MAX_BATCH_SIZE) {
+    throw new Error(`reindex --batch-size must be 1..${MAX_BATCH_SIZE}`);
+  }
+  if (maxBatches !== undefined && (!Number.isSafeInteger(maxBatches) || maxBatches < 1 || maxBatches > 1e4)) {
+    throw new Error("reindex --max-batches must be 1..10000");
+  }
+  const databaseFile = captureDatabaseFile(path);
+  const directory = openSidecarDirectory(path);
+  const file = join4(directory.path, `${createHash7("sha256").update(backend).digest("hex")}.json`);
+  const release = acquireOwnerLock(file, directory, testOptions);
+  try {
+    testOptions.afterOwnerLockAcquired?.();
+    const existing = readState(file, directory, path, databaseID, backend);
+    let state = existing ?? createState(path, databaseID, backend, databaseFile);
+    if (!existing)
+      writeState(file, directory, state);
+    let batches = 0;
+    while (true) {
+      const result = runBatch(path, state, batchSize, testOptions);
+      state = result.state;
+      batches++;
+      if (result.done) {
+        removePrivateFile(file, directory, "reindex state file", true);
+        return {
+          backend,
+          generation: state.generation,
+          purges: state.purges,
+          queued: state.queued,
+          quarantined: state.quarantined,
+          resumed: existing !== undefined
+        };
+      }
+      testOptions.afterCommitBeforeStateWrite?.();
+      writeState(file, directory, state);
+      if (maxBatches !== undefined && batches >= maxBatches) {
+        return {
+          backend,
+          generation: state.generation,
+          purges: state.purges,
+          queued: state.queued,
+          quarantined: state.quarantined,
+          incomplete: true,
+          resumed: existing !== undefined
+        };
+      }
+    }
+  } finally {
+    try {
+      release();
+    } finally {
+      closeSync3(directory.fd);
+    }
+  }
+}
+function acquireOwnerLock(stateFile, directory, testOptions) {
+  const lock = `${stateFile}.lock`;
+  assertReindexOwnerLivenessSupported();
+  const processStart = readReindexProcessStartMarker(process.pid);
+  if (!processStart)
+    throw new Error(`reindex owner liveness is unavailable on ${process.platform}`);
+  const owner = {
+    ownerID: randomUUID7(),
+    pid: process.pid,
+    processStart,
+    hostname: hostname3(),
+    createdAt: Date.now()
+  };
+  for (let attempt = 0;attempt < 3; attempt++) {
+    let fd;
+    try {
+      assertSidecarDirectory(directory);
+      fd = openSync3(lock, constants3.O_WRONLY | constants3.O_CREAT | constants3.O_EXCL | constants3.O_NOFOLLOW, 384);
+      writeSync2(fd, `${JSON.stringify(owner)}
+`);
+      fsyncSync3(fd);
+      closeSync3(fd);
+      fd = undefined;
+      assertSidecarDirectory(directory);
+      return () => {
+        const current = readPrivateJsonFile(lock, directory, "reindex owner lock", false);
+        if (!current || !isOwnerMetadata(current.value) || current.value.ownerID !== owner.ownerID) {
+          throw new Error("reindex owner lock changed before release");
+        }
+        removeOwnedPrivateFile(lock, directory, "reindex owner lock", current.identity, owner.ownerID);
+      };
+    } catch (error) {
+      if (fd !== undefined)
+        closeSync3(fd);
+      if (!hasCode(error, "EEXIST") || attempt === 2)
+        throw new Error("reindex already owned");
+      const observed = readPrivateJsonFile(lock, directory, "reindex owner lock", false);
+      if (!observed || !isOwnerMetadata(observed.value))
+        throw new Error("reindex owner lock is unverifiable");
+      const current = observed.value;
+      const pid = current.pid;
+      let alive = false;
+      try {
+        process.kill(pid, 0);
+        alive = true;
+      } catch (probe) {
+        if (!hasCode(probe, "ESRCH"))
+          throw new Error("reindex owner lock is unverifiable");
+      }
+      const status = classifyReindexOwner(current, hostname3(), alive, alive ? readReindexProcessStartMarker(pid) : null);
+      if (status === "live")
+        throw new Error("reindex already owned");
+      if (status === "unverifiable")
+        throw new Error("reindex owner lock is unverifiable");
+      testOptions.beforeStaleLockTakeover?.();
+      quarantineStaleLock(lock, directory, observed.identity, current, owner);
+    }
+  }
+  throw new Error("reindex already owned");
+}
+function readReindexProcessStartMarker(pid, platform3 = process.platform, readers = {}) {
+  if (platform3 === "linux") {
+    try {
+      const value = "readLinuxStat" in readers ? readers.readLinuxStat?.(pid) : readFileSync4(`/proc/${pid}/stat`, "utf8");
+      if (!value)
+        return null;
+      const close = value.lastIndexOf(")");
+      if (close < 0)
+        return null;
+      const start = value.slice(close + 1).trim().split(/\s+/)[19];
+      return start ? `linux:${start}` : null;
+    } catch {
+      return null;
+    }
+  }
+  if (platform3 === "darwin") {
+    try {
+      const output = "readMacOSPs" in readers ? readers.readMacOSPs?.(pid) : readMacOSProcessStart(pid);
+      return output ? `macos:${output}` : null;
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+function assertReindexOwnerLivenessSupported(platform3 = process.platform) {
+  if (platform3 !== "linux" && platform3 !== "darwin") {
+    throw new Error(`reindex owner liveness is unsupported on ${platform3}`);
+  }
+}
+function readMacOSProcessStart(pid) {
+  const result = spawnSync("/bin/ps", ["-o", "lstart=", "-p", String(pid)], { encoding: "utf8" });
+  if (result.status !== 0 || typeof result.stdout !== "string")
+    return null;
+  const marker = result.stdout.trim();
+  return marker || null;
+}
+function createState(path, databaseID, backend, databaseFile) {
+  preflightDatabaseIdentity(path, databaseID, databaseFile);
+  const opened = openMemoryDatabase(path);
+  try {
+    assertDatabaseIdentity(path, opened.db, databaseID, databaseFile);
+    const generation = opened.db.query("SELECT COALESCE(MAX(generation), 0) + 1 AS value FROM index_outbox WHERE backend = ?").get(backend).value;
+    return {
+      databaseID,
+      databaseFile,
+      backend,
+      generation,
+      phase: "purges",
+      projectID: null,
+      noteID: null,
+      startedAt: Date.now(),
+      snapshot: randomUUID7(),
+      purges: 0,
+      queued: 0,
+      quarantined: 0
+    };
+  } finally {
+    opened.close();
+  }
+}
+function runBatch(path, state, limit, testOptions) {
+  preflightDatabaseIdentity(path, state.databaseID, state.databaseFile);
+  const opened = openMemoryDatabase(path);
+  try {
+    const next = { ...state };
+    testOptions.beforeBatchDatabaseIdentity?.();
+    assertDatabaseIdentity(path, opened.db, state.databaseID, state.databaseFile);
+    opened.db.exec("BEGIN IMMEDIATE");
+    try {
+      if (next.phase === "purges") {
+        const rows = opened.db.query("SELECT id FROM projects WHERE id > ? ORDER BY id LIMIT ?").all(next.projectID ?? "", limit + 1);
+        for (const row of rows.slice(0, limit)) {
+          insert(opened.db, next, "purge-project", row.id, null, null, null);
+          next.purges++;
+          next.projectID = row.id;
+        }
+        if (rows.length <= limit) {
+          next.phase = "notes";
+          next.projectID = null;
+          next.noteID = null;
+        }
+      } else {
+        const rows = opened.db.query("SELECT id, project_id, current_revision, kind, title, summary, content FROM notes WHERE status = 'active' AND (project_id > ? OR (project_id = ? AND id > ?)) ORDER BY project_id, id LIMIT ?").all(next.projectID ?? "", next.projectID ?? "", next.noteID ?? "", limit + 1);
+        for (const row of rows.slice(0, limit)) {
+          next.projectID = row.project_id;
+          next.noteID = row.id;
+          const document = deriveDocument({ projectID: row.project_id, noteID: row.id, revision: row.current_revision, kind: row.kind, title: row.title, summary: row.summary, content: row.content });
+          if (!document) {
+            next.quarantined++;
+            continue;
+          }
+          insert(opened.db, next, "upsert-note", row.project_id, row.id, row.current_revision, document.contentHash);
+          next.queued++;
+        }
+        if (rows.length <= limit) {
+          opened.db.exec("COMMIT");
+          return { state: next, done: true };
+        }
+      }
+      opened.db.exec("COMMIT");
+      return { state: next, done: false };
+    } catch (error) {
+      try {
+        opened.db.exec("ROLLBACK");
+      } catch {}
+      throw error;
+    }
+  } finally {
+    opened.close();
+  }
+}
+function captureDatabaseFile(path) {
+  const stat = regularFile(path, "database");
+  return { dev: stat.dev, ino: stat.ino };
+}
+function assertDatabaseIdentity(path, db, databaseID, expectedFile) {
+  const stat = regularFile(path, "database");
+  if (!sameFile(stat, expectedFile))
+    throw new Error("reindex database file changed");
+  const row = db.query("SELECT database_id FROM agz_meta WHERE id = 1").get();
+  if (row?.database_id !== databaseID)
+    throw new Error("reindex database identity changed");
+}
+function preflightDatabaseIdentity(path, databaseID, expectedFile) {
+  if (!sameFile(regularFile(path, "database"), expectedFile)) {
+    throw new Error("reindex database file changed; remove state and restart reindex");
+  }
+  const opened = openReadOnlyMemoryDatabase(path);
+  try {
+    assertDatabaseIdentity(path, opened.db, databaseID, expectedFile);
+  } finally {
+    opened.close();
+  }
+  if (!sameFile(regularFile(path, "database"), expectedFile)) {
+    throw new Error("reindex database file changed; remove state and restart reindex");
+  }
+}
+function insert(db, state, operation, projectID, noteID, revision, contentHash) {
+  const key = hashTuple("outbox-operation", 2, [state.backend, operation, projectID, noteID, revision, contentHash, state.generation]);
+  if (db.query("SELECT 1 FROM index_outbox WHERE operation_key = ?").get(key))
+    return;
+  db.query("INSERT INTO index_outbox (backend, operation_key, operation, project_id, note_id, revision, content_hash, generation, lease_generation, fence, state, attempt_count, available_at, heartbeat_at, created_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, 0, 0, 'pending', 0, ?, NULL, ?)").run(state.backend, key, operation, projectID, noteID, revision, contentHash, state.generation, Date.now(), Date.now());
+}
+function openSidecarDirectory(databasePath) {
+  if (process.platform === "win32" || !constants3.O_DIRECTORY || !constants3.O_NOFOLLOW) {
+    throw new Error("reindex sidecar directory security is unsupported on this platform");
+  }
+  const path = `${databasePath}.reindex`;
+  try {
+    mkdirSync4(path, { mode: 448 });
+  } catch (error) {
+    if (!hasCode(error, "EEXIST"))
+      throw error;
+  }
+  const before = lstatSync4(path);
+  if (!before.isDirectory() || before.isSymbolicLink() || (before.mode & 63) !== 0) {
+    throw new Error("reindex state directory is unsafe");
+  }
+  const fd = openSync3(path, constants3.O_RDONLY | constants3.O_DIRECTORY | constants3.O_NOFOLLOW);
+  try {
+    const opened = fstatSync2(fd);
+    if (!sameFile(before, opened))
+      throw new Error("reindex state directory changed while opening");
+    const directory = { path, fd, dev: opened.dev, ino: opened.ino };
+    assertSidecarDirectory(directory);
+    return directory;
+  } catch (error) {
+    closeSync3(fd);
+    throw error;
+  }
+}
+function assertSidecarDirectory(directory) {
+  const opened = fstatSync2(directory.fd);
+  const current = lstatSync4(directory.path);
+  if (!opened.isDirectory() || !current.isDirectory() || current.isSymbolicLink() || !sameFile(opened, directory) || !sameFile(current, directory) || (current.mode & 63) !== 0) {
+    throw new Error("reindex state directory changed");
+  }
+}
+function readState(path, directory, databasePath, databaseID, backend) {
+  const parsed = readPrivateJson(path, directory, "reindex state file", true);
+  if (parsed === undefined)
+    return;
+  if (!parsed || typeof parsed !== "object")
+    throw new Error("reindex state is invalid");
+  const state = parsed;
+  if (state.databaseID !== databaseID || state.backend !== backend || !isFileIdentity(state.databaseFile) || !Number.isSafeInteger(state.generation) || state.generation < 1 || state.phase !== "purges" && state.phase !== "notes" || !Number.isSafeInteger(state.startedAt) || typeof state.snapshot !== "string" || !/^[0-9a-f-]{36}$/i.test(state.snapshot) || !nullableString(state.projectID) || !nullableString(state.noteID) || ![state.purges, state.queued, state.quarantined].every((value) => Number.isSafeInteger(value) && value >= 0)) {
+    throw new Error("reindex state is invalid");
+  }
+  if (!sameFile(regularFile(databasePath, "database"), state.databaseFile)) {
+    throw new Error("reindex state is stale; remove state and restart reindex");
+  }
+  return state;
+}
+function readPrivateJson(path, directory, label, optional) {
+  return readPrivateJsonFile(path, directory, label, optional)?.value;
+}
+function readPrivateJsonFile(path, directory, label, optional) {
+  let fd;
+  try {
+    assertSidecarDirectory(directory);
+    const before = regularFile(path, label);
+    fd = openSync3(path, constants3.O_RDONLY | constants3.O_NOFOLLOW);
+    const opened = fstatSync2(fd);
+    if (!sameFile(before, opened))
+      throw new Error(`${label} changed while opening`);
+    const raw = readFileSync4(fd, "utf8");
+    const after = regularFile(path, label);
+    if (!sameFile(after, opened))
+      throw new Error(`${label} changed while reading`);
+    assertSidecarDirectory(directory);
+    return { value: JSON.parse(raw), identity: { dev: opened.dev, ino: opened.ino } };
+  } catch (error) {
+    if (optional && hasCode(error, "ENOENT")) {
+      assertSidecarDirectory(directory);
+      return;
+    }
+    throw error;
+  } finally {
+    if (fd !== undefined)
+      closeSync3(fd);
+  }
+}
+function quarantineStaleLock(lock, directory, observedIdentity, observedOwner, contender) {
+  const takeover = `${lock}.takeover`;
+  let takeoverFd;
+  let takeoverIdentity;
+  try {
+    assertSidecarDirectory(directory);
+    takeoverFd = openSync3(takeover, constants3.O_WRONLY | constants3.O_CREAT | constants3.O_EXCL | constants3.O_NOFOLLOW, 384);
+    const takeoverStat = fstatSync2(takeoverFd);
+    takeoverIdentity = { dev: takeoverStat.dev, ino: takeoverStat.ino };
+    writeSync2(takeoverFd, `${JSON.stringify(contender)}
+`);
+    fsyncSync3(takeoverFd);
+    closeSync3(takeoverFd);
+    takeoverFd = undefined;
+    const current = readPrivateJsonFile(lock, directory, "reindex owner lock", true);
+    if (!current || !sameFile(current.identity, observedIdentity) || !isOwnerMetadata(current.value) || current.value.ownerID !== observedOwner.ownerID) {
+      return;
+    }
+    const quarantine = `${lock}.${contender.ownerID}.stale`;
+    assertReplacementTargetSafe(quarantine, "reindex stale lock quarantine");
+    renameSync4(lock, quarantine);
+    const claimed = readPrivateJsonFile(quarantine, directory, "reindex stale lock quarantine", false);
+    if (!claimed || !sameFile(claimed.identity, observedIdentity) || !isOwnerMetadata(claimed.value) || claimed.value.ownerID !== observedOwner.ownerID) {
+      throw new Error("reindex owner lock changed during stale takeover");
+    }
+    removeOwnedPrivateFile(quarantine, directory, "reindex stale lock quarantine", observedIdentity, observedOwner.ownerID);
+  } catch (error) {
+    if (hasCode(error, "EEXIST"))
+      throw new Error("reindex already owned");
+    throw error;
+  } finally {
+    if (takeoverFd !== undefined)
+      closeSync3(takeoverFd);
+    if (takeoverIdentity) {
+      removeOwnedPrivateFile(takeover, directory, "reindex stale takeover lock", takeoverIdentity, contender.ownerID);
+    }
+  }
+}
+function removeOwnedPrivateFile(path, directory, label, expectedIdentity, expectedOwnerID) {
+  const current = readPrivateJsonFile(path, directory, label, false);
+  if (!current || !sameFile(current.identity, expectedIdentity) || !isOwnerMetadata(current.value) || current.value.ownerID !== expectedOwnerID) {
+    throw new Error(`${label} changed before removal`);
+  }
+  removePrivateFile(path, directory, label, false);
+}
+function writeState(path, directory, state) {
+  const temporary = `${path}.${randomUUID7()}.tmp`;
+  let fd;
+  let created = false;
+  try {
+    assertSidecarDirectory(directory);
+    fd = openSync3(temporary, constants3.O_WRONLY | constants3.O_CREAT | constants3.O_EXCL | constants3.O_NOFOLLOW, 384);
+    created = true;
+    writeSync2(fd, `${JSON.stringify(state)}
+`);
+    fsyncSync3(fd);
+    closeSync3(fd);
+    fd = undefined;
+    regularFile(temporary, "reindex temporary state file");
+    assertSidecarDirectory(directory);
+    assertReplacementTargetSafe(path, "reindex state file");
+    renameSync4(temporary, path);
+    created = false;
+    assertSidecarDirectory(directory);
+    fsyncSync3(directory.fd);
+  } finally {
+    if (fd !== undefined)
+      closeSync3(fd);
+    if (created)
+      removePrivateFile(temporary, directory, "reindex temporary state file", true);
+  }
+}
+function removePrivateFile(path, directory, label, optional) {
+  try {
+    assertSidecarDirectory(directory);
+    regularFile(path, label);
+    rmSync3(path);
+    assertSidecarDirectory(directory);
+    fsyncSync3(directory.fd);
+  } catch (error) {
+    if (optional && hasCode(error, "ENOENT")) {
+      assertSidecarDirectory(directory);
+      return;
+    }
+    throw error;
+  }
+}
+function regularFile(path, label) {
+  const stat = lstatSync4(path);
+  if (!stat.isFile() || stat.isSymbolicLink() || (stat.mode & 63) !== 0)
+    throw new Error(`${label} is unsafe`);
+  return stat;
+}
+function assertReplacementTargetSafe(path, label) {
+  try {
+    regularFile(path, label);
+  } catch (error) {
+    if (hasCode(error, "ENOENT"))
+      return;
+    throw error;
+  }
+}
+function sameFile(left, right) {
+  return left.dev === right.dev && left.ino === right.ino;
+}
+function isFileIdentity(value) {
+  return Boolean(value && typeof value === "object" && Number.isSafeInteger(value.dev) && Number.isSafeInteger(value.ino));
+}
+function nullableString(value) {
+  return value === null || typeof value === "string";
+}
+function hasCode(error, code) {
+  return Boolean(error && typeof error === "object" && "code" in error && error.code === code);
+}
+function isOwnerMetadata(value) {
+  return Boolean(value && typeof value === "object" && typeof value.ownerID === "string" && value.ownerID && Number.isSafeInteger(value.pid) && value.pid > 0 && typeof value.processStart === "string" && value.processStart && typeof value.hostname === "string" && value.hostname && Number.isSafeInteger(value.createdAt));
+}
+
 // src/admin/index.ts
 async function runAdmin(argv = process.argv.slice(2)) {
-  const databasePath = resolveConfig().databasePath;
-  const [command, subcommand] = argv;
-  if (!command)
-    throw new Error("admin command is required");
+  const parsed = parseAdminArguments(argv);
+  const configuredDatabasePath = resolveConfig().databasePath;
+  const database = parsed.command === "init" ? undefined : requireExistingDatabase(configuredDatabasePath, parsed.databaseID);
+  const databasePath = database?.path ?? configuredDatabasePath;
+  const [command, subcommand] = [parsed.command, parsed.subcommand];
+  if (command === "init") {
+    const opened = openMemoryDatabase(databasePath);
+    try {
+      return withDatabaseIdentity({ initialized: true }, databaseIdentity(opened.db, databasePath));
+    } finally {
+      opened.close();
+    }
+  }
   if (command === "doctor") {
     requireExistingDatabase(databasePath);
     const opened = openReadOnlyMemoryDatabase(databasePath);
     try {
-      return doctorDatabase(opened.db);
+      return withDatabaseIdentity(doctorDatabase(opened.db), database);
     } finally {
       opened.close();
     }
@@ -4295,7 +4844,7 @@ async function runAdmin(argv = process.argv.slice(2)) {
       const db = new Database4(databasePath);
       try {
         const version = schemaVersion(db);
-        return createVerifiedBackup(db, databasePath, version, version, PRODUCT_VERSION);
+        return withDatabaseIdentity(createVerifiedBackup(db, databasePath, version, version, PRODUCT_VERSION), database);
       } finally {
         db.close();
       }
@@ -4307,7 +4856,7 @@ async function runAdmin(argv = process.argv.slice(2)) {
     }
     const opened = openMemoryDatabase(databasePath);
     try {
-      return doctorDatabase(opened.db);
+      return withDatabaseIdentity(doctorDatabase(opened.db), database);
     } finally {
       opened.close();
     }
@@ -4321,7 +4870,7 @@ async function runAdmin(argv = process.argv.slice(2)) {
     const confirmation = option(argv, "--confirm");
     const expectedHash = option(argv, "--sha256");
     if (!confirmation || !expectedHash) {
-      return { dryRun: true, manifest: verified.manifest, targetPath: databasePath };
+      return withDatabaseIdentity({ dryRun: true, manifest: verified.manifest, targetPath: databasePath }, database);
     }
     if (expectedHash !== verified.manifest.sha256)
       throw new Error("restore manifest hash mismatch");
@@ -4339,7 +4888,7 @@ async function runAdmin(argv = process.argv.slice(2)) {
     }
     return withExclusiveMaintenance(databasePath, verified.manifest.sourceSchema, (maintenance) => {
       const preservedPath = restoreVerifiedBackup(manifestPath, databasePath, confirmation, maintenance, expectedHash);
-      return { restored: true, preservedPath, manifest: verified.manifest };
+      return withDatabaseIdentity({ restored: true, preservedPath, manifest: verified.manifest }, database);
     }, recovery);
   }
   if (command === "unlock") {
@@ -4348,72 +4897,20 @@ async function runAdmin(argv = process.argv.slice(2)) {
     if (!ownerID || !confirmation)
       throw new Error("unlock requires --owner and --confirm");
     breakMigrationLock(databasePath, ownerID, confirmation);
-    return { unlocked: true, ownerID };
+    return withDatabaseIdentity({ unlocked: true, ownerID }, database);
   }
   if (command === "reindex") {
     const backend = option(argv, "--backend");
     if (!backend || !/^[a-z0-9][a-z0-9._-]{0,79}$/i.test(backend)) {
       throw new Error("reindex requires a valid --backend");
     }
-    const opened = openMemoryDatabase(databasePath);
-    try {
-      const now = Date.now();
-      let queued = 0;
-      let purges = 0;
-      const quarantined = {};
-      let generation = 0;
-      const insert = opened.db.query(`
-        INSERT INTO index_outbox
-          (backend, operation_key, operation, project_id, note_id, revision, content_hash,
-           generation, lease_generation, fence, state, attempt_count, available_at,
-           heartbeat_at, created_at)
-        VALUES (?, ?, ?, ?, ?, ?, ?, ?, 0, 0, 'pending', 0, ?, NULL, ?)
-      `);
-      opened.db.exec("BEGIN IMMEDIATE");
-      try {
-        generation = opened.db.query("SELECT COALESCE(MAX(generation), 0) + 1 AS generation FROM index_outbox WHERE backend = ?").get(backend).generation;
-        const projects = opened.db.query("SELECT id FROM projects ORDER BY id").all();
-        const notes = opened.db.query("SELECT * FROM notes WHERE status = 'active' ORDER BY project_id, id").all();
-        for (const project of projects) {
-          const operation = "purge-project";
-          const operationKey = outboxOperationKey(backend, operation, project.id, null, null, null, generation);
-          purges += insert.run(backend, operationKey, operation, project.id, null, null, null, generation, now, now).changes;
-        }
-        for (const note of notes) {
-          const document = deriveDocument({
-            projectID: note.project_id,
-            noteID: note.id,
-            revision: note.current_revision,
-            kind: note.kind,
-            title: note.title,
-            summary: note.summary,
-            content: note.content
-          });
-          if (!document) {
-            quarantined.derived_document_unavailable = (quarantined.derived_document_unavailable ?? 0) + 1;
-            continue;
-          }
-          const operation = "upsert-note";
-          const operationKey = outboxOperationKey(backend, operation, note.project_id, note.id, note.current_revision, document.contentHash, generation);
-          queued += insert.run(backend, operationKey, operation, note.project_id, note.id, note.current_revision, document.contentHash, generation, now, now).changes;
-        }
-        opened.db.exec("COMMIT");
-      } catch (error) {
-        try {
-          opened.db.exec("ROLLBACK");
-        } catch {}
-        throw error;
-      }
-      return { backend, generation, purges, queued, quarantined };
-    } finally {
-      opened.close();
-    }
+    return withDatabaseIdentity(runResumableReindex(databasePath, database.databaseID, backend, Number(option(argv, "--batch-size") ?? 100), option(argv, "--max-batches") === undefined ? undefined : Number(option(argv, "--max-batches"))), database);
   }
   if (command === "outbox" && subcommand === "status") {
-    return withDatabase(databasePath, (db) => ({
+    return withDatabase(databasePath, (db) => withDatabaseIdentity({
       states: db.query("SELECT state, COUNT(*) AS count FROM index_outbox GROUP BY state ORDER BY state").all(),
       oldestPendingAt: db.query("SELECT MIN(created_at) AS value FROM index_outbox WHERE state IN ('pending','leased')").get().value
-    }));
+    }, database));
   }
   if (command === "outbox" && subcommand === "retry") {
     const id = Number(argv[2]);
@@ -4423,26 +4920,28 @@ async function runAdmin(argv = process.argv.slice(2)) {
       const result = db.query(`UPDATE index_outbox
               SET state = 'pending', available_at = ?, lease_owner = NULL,
                   lease_expires_at = NULL, heartbeat_at = NULL,
-                  completed_at = NULL, last_error_code = NULL
-            WHERE id = ? AND state = 'dead'`).run(Date.now(), id);
-      return { id, retried: result.changes === 1 };
+                  completed_at = NULL, last_error_code = NULL, attempt_count = 0
+             WHERE id = ? AND state = 'dead'`).run(Date.now(), id);
+      pruneTerminalOutbox(db);
+      return withDatabaseIdentity({ id, retried: result.changes === 1 }, database);
     });
   }
   if (command === "capture" && subcommand === "status") {
-    return withDatabase(databasePath, (db) => ({
+    return withDatabase(databasePath, (db) => withDatabaseIdentity({
       events: db.query("SELECT state, COUNT(*) AS count FROM capture_events GROUP BY state ORDER BY state").all(),
-      checkpoints: db.query("SELECT state, COUNT(*) AS count FROM capture_checkpoints GROUP BY state ORDER BY state").all()
-    }));
+      checkpoints: db.query("SELECT state, COUNT(*) AS count FROM capture_checkpoints GROUP BY state ORDER BY state").all(),
+      quarantinePrivacy: quarantinePrivacyReport(db)
+    }, database));
   }
   if (command === "backup" && subcommand === "prune") {
     return withExclusiveMaintenance(databasePath, SCHEMA_VERSION, () => {
       const entries = backupEntries(databasePath);
       const root = resolve3(`${databasePath}.backup`);
-      const digest = createHash7("sha256").update(`${resolve3(databasePath)}\x00${root}
+      const digest = createHash8("sha256").update(`${resolve3(databasePath)}\x00${root}
 ${entries.map((entry) => `${basename3(entry.manifest)}\x00${basename3(entry.database)}\x00${entry.sha256}\x00${entry.size}\x00${entry.manifestHash}`).join(`
 `)}`).digest("hex");
       if (option(argv, "--confirm") !== "DELETE_VERIFIED_BACKUPS") {
-        return { dryRun: true, digest, backups: entries };
+        return withDatabaseIdentity({ dryRun: true, digest, backups: entries }, database);
       }
       if (option(argv, "--digest") !== digest)
         throw new Error("backup prune digest mismatch");
@@ -4454,14 +4953,59 @@ ${entries.map((entry) => `${basename3(entry.manifest)}\x00${basename3(entry.data
         return current;
       });
       for (const current of currentEntries) {
-        rmSync3(current.database, { force: true });
-        rmSync3(current.manifest, { force: true });
+        rmSync4(current.database, { force: true });
+        rmSync4(current.manifest, { force: true });
       }
-      return { deleted: entries.length, digest };
+      return withDatabaseIdentity({ deleted: entries.length, digest }, database);
     });
   }
   throw new Error(`unknown admin command: ${argv.join(" ")}`);
 }
+var TERMINAL_OUTBOX_RETENTION = 1e4;
+function parseAdminArguments(argv) {
+  if (argv.length === 0)
+    throw new Error("admin command is required");
+  const [command, subcommand] = argv;
+  const forms = {
+    init: { positional: 0, flags: ["--database-id"] },
+    doctor: { positional: 0, flags: ["--database-id"] },
+    backup: { positional: subcommand === "prune" ? 1 : 0, flags: subcommand === "prune" ? ["--confirm", "--digest", "--database-id"] : ["--database-id"] },
+    upgrade: { positional: 0, flags: ["--to", "--database-id"] },
+    restore: { positional: 1, flags: ["--confirm", "--sha256", "--maintenance-owner", "--maintenance-confirm", "--database-id"] },
+    unlock: { positional: 0, flags: ["--owner", "--confirm", "--database-id"] },
+    reindex: { positional: 0, flags: ["--backend", "--batch-size", "--max-batches", "--database-id"] },
+    outbox: { positional: subcommand === "retry" ? 2 : subcommand === "status" ? 1 : -1, flags: ["--database-id"] },
+    capture: { positional: subcommand === "status" ? 1 : -1, flags: ["--database-id"] }
+  };
+  const form = forms[command];
+  if (!form || form.positional < 0)
+    throw new Error(`unknown admin command: ${argv.join(" ")}`);
+  let positional = command === "restore" ? 2 : subcommand ? 2 : 1;
+  if (command === "backup" && subcommand !== "prune")
+    positional = 1;
+  if (command === "init" || command === "doctor" || command === "upgrade" || command === "unlock" || command === "reindex")
+    positional = 1;
+  if (command === "outbox" && subcommand === "retry")
+    positional = 3;
+  const seen = new Set;
+  for (let index = positional;index < argv.length; index += 2) {
+    const flag = argv[index];
+    const value = argv[index + 1];
+    if (!flag?.startsWith("--") || value === undefined || value.startsWith("--")) {
+      throw new Error("admin arguments must use unique --flag value pairs");
+    }
+    if (!form.flags.includes(flag) || seen.has(flag))
+      throw new Error(`invalid or duplicate admin argument: ${flag}`);
+    seen.add(flag);
+  }
+  if (command === "restore" && (!subcommand || subcommand.startsWith("--"))) {
+    throw new Error("restore manifest path is required");
+  }
+  if ((command === "outbox" || command === "capture") && !subcommand) {
+    throw new Error(`unknown admin command: ${argv.join(" ")}`);
+  }
+  return { command, subcommand, databaseID: option(argv, "--database-id") };
+}
 function withDatabase(databasePath, action) {
   const opened = openMemoryDatabase(databasePath);
   try {
@@ -4487,9 +5031,39 @@ function option(argv, name) {
   const index = argv.indexOf(name);
   return index >= 0 ? argv[index + 1] : undefined;
 }
-function requireExistingDatabase(databasePath) {
+function requireExistingDatabase(databasePath, expectedID) {
   if (!existsSync5(databasePath))
-    throw new Error(`database does not exist: ${databasePath}`);
+    throw new Error("database does not exist");
+  const stat = lstatSync5(databasePath);
+  if (!stat.isFile() || stat.isSymbolicLink())
+    throw new Error("database must be a regular file");
+  const canonicalPath = realpathSync(databasePath);
+  if (canonicalPath !== resolve3(databasePath))
+    throw new Error("database path must be canonical");
+  const opened = openReadOnlyMemoryDatabase(canonicalPath);
+  try {
+    const identity = databaseIdentity(opened.db, canonicalPath);
+    if (expectedID !== undefined && expectedID !== identity.databaseID)
+      throw new Error("database id mismatch");
+    return identity;
+  } finally {
+    opened.close();
+  }
+}
+function databaseIdentity(db, databasePath) {
+  const row = db.query("SELECT database_id FROM agz_meta WHERE id = 1").get();
+  if (!row?.database_id)
+    throw new Error("database identity is missing");
+  return { path: realpathSync(databasePath), databaseID: row.database_id };
+}
+function withDatabaseIdentity(result, identity) {
+  return { ...result, databasePath: identity.path, databaseID: identity.databaseID };
+}
+function pruneTerminalOutbox(db) {
+  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(TERMINAL_OUTBOX_RETENTION);
 }
 function readSchemaVersion(databasePath) {
   const db = new Database4(databasePath, { readonly: true });
@@ -4521,10 +5095,10 @@ function verifiedBackupEntry(root, manifest) {
   const candidate = resolve3(manifest);
   if (dirname3(candidate) !== root)
     throw new Error("backup manifest escaped the backup directory");
-  const stat = lstatSync4(candidate);
+  const stat = lstatSync5(candidate);
   if (!stat.isFile() || stat.isSymbolicLink())
     throw new Error("backup manifest must be a regular file");
-  const bytes = readFileSync4(candidate);
+  const bytes = readFileSync5(candidate);
   const verified = verifyBackupManifest(candidate);
   if (dirname3(verified.databasePath) !== root) {
     throw new Error("backup database escaped the backup directory");
@@ -4534,20 +5108,9 @@ function verifiedBackupEntry(root, manifest) {
     database: verified.databasePath,
     sha256: verified.manifest.sha256,
     size: verified.manifest.size,
-    manifestHash: createHash7("sha256").update(bytes).digest("hex")
+    manifestHash: createHash8("sha256").update(bytes).digest("hex")
   };
 }
-function outboxOperationKey(backend, operation, projectID, noteID, revision, contentHash, generation) {
-  return hashTuple("outbox-operation", 2, [
-    backend,
-    operation,
-    projectID,
-    noteID,
-    revision,
-    contentHash,
-    generation
-  ]);
-}
 if (import.meta.main) {
   try {
     const result = await runAdmin();