@vaur94/agz-memory 0.4.0-beta.1

package/dist/admin.js

@@ -0,0 +1,1494 @@
+#!/usr/bin/env bun
+// @bun
+
+// src/admin/index.ts
+import { createHash as createHash5 } from "crypto";
+import { Database as Database3 } from "bun:sqlite";
+import {
+  existsSync as existsSync4,
+  lstatSync as lstatSync2,
+  readdirSync,
+  readFileSync as readFileSync3,
+  rmSync as rmSync3
+} from "fs";
+import { basename as basename2, dirname as dirname2, resolve as resolve2 } from "path";
+
+// src/config.ts
+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 };
+}
+
+// src/db.ts
+import { randomUUID as randomUUID4 } from "crypto";
+import { Database as Database2 } from "bun:sqlite";
+import { chmodSync as chmodSync2, copyFileSync as copyFileSync2, existsSync as existsSync3 } from "fs";
+
+// src/identity.ts
+import { createHash } from "crypto";
+function hashRoot(directory) {
+  return createHash("sha256").update(directory).digest("hex");
+}
+
+// src/project.ts
+function cleanProjectName(value) {
+  return value.trim().replace(/\s+/g, " ");
+}
+function normalizeProjectName(value) {
+  return cleanProjectName(value).normalize("NFKC").toLowerCase();
+}
+
+// src/types.ts
+var SCHEMA_VERSION = 9;
+var PREDICATES = ["SUPPORTS", "DERIVED_FROM", "PART_OF", "ABOUT", "PRECEDES", "SUPERSEDES"];
+
+// src/db/backup.ts
+import { createHash as createHash2, randomUUID } from "crypto";
+import { Database } from "bun:sqlite";
+import {
+  chmodSync,
+  closeSync,
+  copyFileSync,
+  existsSync,
+  fsyncSync,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync
+} from "fs";
+import { basename, dirname, join as join2, resolve } from "path";
+
+// src/db/health.ts
+function inspectDatabase(db) {
+  const integrity = db.query("PRAGMA integrity_check").get().integrity_check;
+  const foreignKeyViolations = db.query("PRAGMA foreign_key_check").all();
+  const schemaVersion = hasTable(db, "schema_state") ? db.query("SELECT MAX(version) AS version FROM schema_state").get().version ?? undefined : undefined;
+  const counts = {};
+  for (const table of [
+    "projects",
+    "notes",
+    "note_edges",
+    "notes_fts",
+    "project_bindings",
+    "capture_events",
+    "capture_checkpoints",
+    "note_provenance",
+    "note_revisions",
+    "index_outbox"
+  ]) {
+    if (!hasTable(db, table))
+      continue;
+    counts[table] = db.query(`SELECT COUNT(*) AS count FROM ${table}`).get().count;
+  }
+  return { integrity, foreignKeyViolations, schemaVersion, counts };
+}
+function assertHealthyDatabase(db) {
+  const health = inspectDatabase(db);
+  if (health.integrity !== "ok") {
+    throw new Error(`database integrity check failed: ${health.integrity}`);
+  }
+  if (health.foreignKeyViolations.length > 0) {
+    throw new Error(`database foreign key check failed: ${health.foreignKeyViolations.length} violation(s)`);
+  }
+  return health;
+}
+function hasTable(db, table) {
+  const row = db.query("SELECT COUNT(*) AS count FROM sqlite_master WHERE type IN ('table','view') AND name = ?").get(table);
+  return row.count > 0;
+}
+
+// src/db/backup.ts
+var BACKUP_FORMAT = "opencode2-memory-backup/1";
+function createVerifiedBackup(db, databasePath, sourceSchema, targetSchema, productVersion) {
+  const sourceHealth = assertHealthyDatabase(db);
+  const checkpoint = db.query("PRAGMA wal_checkpoint(TRUNCATE)").get();
+  if (checkpoint.busy !== 0)
+    throw new Error("database WAL checkpoint is busy");
+  const backupDirectory = `${databasePath}.backup`;
+  mkdirSync(backupDirectory, { recursive: true, mode: 448 });
+  chmodSync(backupDirectory, 448);
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+  const stem = `schema-v${sourceSchema}-${stamp}-${randomUUID()}`;
+  const finalDatabasePath = join2(backupDirectory, `${stem}.sqlite`);
+  const finalManifestPath = join2(backupDirectory, `${stem}.manifest.json`);
+  const temporaryDatabasePath = `${finalDatabasePath}.tmp`;
+  const temporaryManifestPath = `${finalManifestPath}.tmp`;
+  try {
+    db.exec(`VACUUM INTO '${escapeSql(temporaryDatabasePath)}'`);
+    chmodSync(temporaryDatabasePath, 384);
+    const verification = new Database(temporaryDatabasePath, { readonly: true });
+    let backupHealth;
+    let sqliteVersion;
+    try {
+      backupHealth = assertHealthyDatabase(verification);
+      sqliteVersion = verification.query("SELECT sqlite_version() AS version").get().version;
+    } finally {
+      verification.close();
+    }
+    if (JSON.stringify(backupHealth.counts) !== JSON.stringify(sourceHealth.counts)) {
+      throw new Error("backup row counts differ from source database");
+    }
+    const bytes = readFileSync(temporaryDatabasePath);
+    const manifest = {
+      format: BACKUP_FORMAT,
+      productVersion,
+      sourceSchema,
+      targetSchema,
+      createdAt: new Date().toISOString(),
+      sqliteVersion,
+      databaseFile: basename(finalDatabasePath),
+      sha256: createHash2("sha256").update(bytes).digest("hex"),
+      size: bytes.byteLength,
+      counts: backupHealth.counts,
+      integrity: "ok",
+      foreignKeyViolations: 0
+    };
+    writeFileSync(temporaryManifestPath, `${JSON.stringify(manifest, null, 2)}
+`, {
+      mode: 384
+    });
+    fsyncPath(temporaryDatabasePath);
+    fsyncPath(temporaryManifestPath);
+    renameSync(temporaryDatabasePath, finalDatabasePath);
+    renameSync(temporaryManifestPath, finalManifestPath);
+    fsyncPath(backupDirectory);
+    return { databasePath: finalDatabasePath, manifestPath: finalManifestPath, manifest };
+  } catch (error) {
+    rmSync(temporaryDatabasePath, { force: true });
+    rmSync(temporaryManifestPath, { force: true });
+    throw error;
+  }
+}
+function verifyBackupManifest(manifestPath) {
+  const resolvedManifestPath = resolve(manifestPath);
+  const manifestStat = lstatSync(resolvedManifestPath);
+  if (!manifestStat.isFile() || manifestStat.isSymbolicLink()) {
+    throw new Error("backup manifest must be a regular file");
+  }
+  const manifest = JSON.parse(readFileSync(resolvedManifestPath, "utf8"));
+  if (manifest.format !== BACKUP_FORMAT) {
+    throw new Error("unsupported backup manifest format");
+  }
+  if (typeof manifest.databaseFile !== "string" || !manifest.databaseFile || basename(manifest.databaseFile) !== manifest.databaseFile) {
+    throw new Error("backup databaseFile must be a basename");
+  }
+  if (typeof manifest.sha256 !== "string" || !/^[0-9a-f]{64}$/.test(manifest.sha256)) {
+    throw new Error("backup manifest sha256 is invalid");
+  }
+  if (!Number.isSafeInteger(manifest.size) || manifest.size < 0) {
+    throw new Error("backup manifest size is invalid");
+  }
+  const manifestDirectory = dirname(resolvedManifestPath);
+  const databasePath = resolve(manifestDirectory, manifest.databaseFile);
+  if (dirname(databasePath) !== manifestDirectory) {
+    throw new Error("backup database file must stay inside the manifest directory");
+  }
+  if (!existsSync(databasePath))
+    throw new Error("backup database file is missing");
+  const databaseStat = lstatSync(databasePath);
+  if (!databaseStat.isFile() || databaseStat.isSymbolicLink()) {
+    throw new Error("backup database must be a regular file");
+  }
+  const bytes = readFileSync(databasePath);
+  const hash = createHash2("sha256").update(bytes).digest("hex");
+  if (hash !== manifest.sha256 || databaseStat.size !== manifest.size) {
+    throw new Error("backup hash or size mismatch");
+  }
+  const db = new Database(databasePath, { readonly: true });
+  try {
+    const health = assertHealthyDatabase(db);
+    if (JSON.stringify(health.counts) !== JSON.stringify(manifest.counts)) {
+      throw new Error("backup manifest row counts do not match");
+    }
+  } finally {
+    db.close();
+  }
+  return { databasePath, manifestPath: resolvedManifestPath, manifest };
+}
+function restoreVerifiedBackup(manifestPath, targetPath, confirmation) {
+  if (confirmation !== "RESTORE_DATABASE_FROM_VERIFIED_BACKUP") {
+    throw new Error("invalid restore confirmation");
+  }
+  const verified = verifyBackupManifest(manifestPath);
+  mkdirSync(dirname(targetPath), { recursive: true, mode: 448 });
+  const temporary = `${targetPath}.restore-${randomUUID()}.tmp`;
+  const preserved = `${targetPath}.failed-restore-source-${Date.now()}-${randomUUID()}`;
+  const movedSidecars = [];
+  let hasPreservedSource = false;
+  let preservedSourceHealthy = false;
+  let targetInstalled = false;
+  try {
+    copyFileSync(verified.databasePath, temporary);
+    chmodSync(temporary, 384);
+    fsyncPath(temporary);
+    if (existsSync(targetPath)) {
+      preservedSourceHealthy = checkpointSource(targetPath);
+      copyFileSync(targetPath, preserved);
+      chmodSync(preserved, 384);
+      fsyncPath(preserved);
+      if (preservedSourceHealthy)
+        verifyDatabaseFile(preserved);
+      for (const suffix of ["-wal", "-shm"]) {
+        const source = `${targetPath}${suffix}`;
+        if (!existsSync(source))
+          continue;
+        const preservedSidecar = `${preserved}${suffix}`;
+        copyFileSync(source, preservedSidecar);
+        chmodSync(preservedSidecar, 384);
+        fsyncPath(preservedSidecar);
+      }
+      fsyncPath(dirname(targetPath));
+      hasPreservedSource = true;
+    }
+    for (const suffix of ["-wal", "-shm"]) {
+      const source = `${targetPath}${suffix}`;
+      if (!existsSync(source))
+        continue;
+      const quarantine = `${source}.quarantine-${randomUUID()}`;
+      renameSync(source, quarantine);
+      movedSidecars.push({ source, quarantine });
+    }
+    renameSync(temporary, targetPath);
+    targetInstalled = true;
+    fsyncPath(dirname(targetPath));
+    verifyDatabaseFile(targetPath);
+    for (const { quarantine } of movedSidecars) {
+      rmSync(quarantine, { recursive: true, force: true });
+    }
+  } catch (error) {
+    const rollbackErrors = [];
+    rmSync(temporary, { force: true });
+    if (targetInstalled) {
+      try {
+        for (const suffix of ["-wal", "-shm"]) {
+          rmSync(`${targetPath}${suffix}`, { recursive: true, force: true });
+        }
+        if (hasPreservedSource) {
+          const rollback = `${targetPath}.rollback-${randomUUID()}.tmp`;
+          copyFileSync(preserved, rollback);
+          chmodSync(rollback, 384);
+          fsyncPath(rollback);
+          rmSync(targetPath, { force: true });
+          renameSync(rollback, targetPath);
+        } else {
+          rmSync(targetPath, { force: true });
+        }
+      } catch (rollbackError) {
+        rollbackErrors.push(rollbackError);
+      }
+    }
+    for (const { source, quarantine } of movedSidecars.reverse()) {
+      if (!existsSync(quarantine))
+        continue;
+      try {
+        rmSync(source, { recursive: true, force: true });
+        renameSync(quarantine, source);
+      } catch (rollbackError) {
+        rollbackErrors.push(rollbackError);
+      }
+    }
+    if (targetInstalled && hasPreservedSource && preservedSourceHealthy && rollbackErrors.length === 0) {
+      try {
+        fsyncPath(dirname(targetPath));
+        verifyDatabaseFile(targetPath);
+      } catch (rollbackError) {
+        rollbackErrors.push(rollbackError);
+      }
+    }
+    if (rollbackErrors.length > 0) {
+      throw new AggregateError([error, ...rollbackErrors], "restore failed and rollback was incomplete");
+    }
+    throw error;
+  }
+  return preserved;
+}
+function escapeSql(value) {
+  return value.replaceAll("'", "''");
+}
+function fsyncPath(path) {
+  const descriptor = openSync(path, "r");
+  try {
+    fsyncSync(descriptor);
+  } finally {
+    closeSync(descriptor);
+  }
+}
+function checkpointSource(path) {
+  let db;
+  try {
+    db = new Database(path);
+    const checkpoint = db.query("PRAGMA wal_checkpoint(TRUNCATE)").get();
+    if (checkpoint.busy !== 0)
+      throw new Error("source database WAL checkpoint is busy");
+    try {
+      assertHealthyDatabase(db);
+      return true;
+    } catch {
+      return false;
+    }
+  } catch (error) {
+    if (isBusyError(error))
+      throw error;
+    return false;
+  } finally {
+    db?.close();
+  }
+}
+function verifyDatabaseFile(path) {
+  const db = new Database(path, { readonly: true });
+  try {
+    assertHealthyDatabase(db);
+  } finally {
+    db.close();
+  }
+}
+function isBusyError(error) {
+  if (error && typeof error === "object" && "code" in error) {
+    const code = String(error.code);
+    if (code === "SQLITE_BUSY" || code === "SQLITE_LOCKED")
+      return true;
+  }
+  return error instanceof Error && /\b(?:busy|locked)\b/i.test(error.message);
+}
+
+// src/db/migration-lock.ts
+import { randomUUID as randomUUID2 } from "crypto";
+import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync2, renameSync as renameSync2, rmSync as rmSync2, writeFileSync as writeFileSync2 } from "fs";
+import { hostname } from "os";
+function migrationLockPath(databasePath) {
+  return `${databasePath}.migration.lock`;
+}
+function acquireMigrationLock(databasePath, targetSchema, timeoutMs = 30000) {
+  const path = migrationLockPath(databasePath);
+  const owner = {
+    ownerID: randomUUID2(),
+    pid: process.pid,
+    processStartMarker: processStartMarker(process.pid) ?? "unavailable",
+    hostname: hostname(),
+    startedAt: Date.now(),
+    targetSchema
+  };
+  const deadline = Date.now() + timeoutMs;
+  const stagedOwner = `${path}.owner-${owner.ownerID}.tmp`;
+  writeFileSync2(stagedOwner, `${JSON.stringify(owner, null, 2)}
+`, { mode: 384 });
+  try {
+    while (true) {
+      let created = false;
+      try {
+        mkdirSync2(path, { mode: 448 });
+        created = true;
+        renameSync2(stagedOwner, `${path}/owner.json`);
+        break;
+      } catch (error) {
+        if (created) {
+          rmSync2(path, { recursive: true, force: true });
+          throw error;
+        }
+        if (!existsSync2(path))
+          throw error;
+        if (Date.now() >= deadline) {
+          const current = readMigrationLockOwner(path);
+          throw new Error(`migration lock is held${current ? ` by ${current.ownerID} (pid ${current.pid})` : ""}`);
+        }
+        Bun.sleepSync(Math.min(250, Math.max(25, deadline - Date.now())));
+      }
+    }
+  } finally {
+    rmSync2(stagedOwner, { force: true });
+  }
+  let released = false;
+  return {
+    path,
+    owner,
+    release() {
+      if (released)
+        return;
+      const current = readMigrationLockOwner(path);
+      if (current?.ownerID !== owner.ownerID) {
+        throw new Error("migration lock ownership changed before release");
+      }
+      rmSync2(path, { recursive: true, force: true });
+      released = true;
+    }
+  };
+}
+function readMigrationLockOwner(path) {
+  try {
+    return JSON.parse(readFileSync2(`${path}/owner.json`, "utf8"));
+  } catch {
+    return;
+  }
+}
+function breakMigrationLock(databasePath, ownerID, confirmation) {
+  if (confirmation !== "BREAK_STALE_MIGRATION_LOCK") {
+    throw new Error("invalid migration lock confirmation");
+  }
+  const path = migrationLockPath(databasePath);
+  const owner = readMigrationLockOwner(path);
+  if (!owner) {
+    if (ownerID !== "ORPHANED" || !existsSync2(path))
+      throw new Error("migration lock owner mismatch");
+    rmSync2(path, { recursive: true, force: true });
+    return;
+  }
+  if (owner.ownerID !== ownerID)
+    throw new Error("migration lock owner mismatch");
+  if (owner.hostname === hostname() && processIsAlive(owner.pid)) {
+    const currentMarker = processStartMarker(owner.pid);
+    if (!currentMarker || currentMarker === owner.processStartMarker) {
+      throw new Error(`migration lock process ${owner.pid} is still alive`);
+    }
+  }
+  rmSync2(path, { recursive: true, force: true });
+}
+function processStartMarker(pid) {
+  try {
+    const fields = readFileSync2(`/proc/${pid}/stat`, "utf8").trim().split(/\s+/);
+    return fields[21];
+  } catch {
+    return;
+  }
+}
+function processIsAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// src/db/migrations/v009.ts
+import { createHash as createHash3, randomUUID as randomUUID3 } from "crypto";
+
+// src/db/schema.ts
+var SCHEMA_V9_TABLES = `
+CREATE TABLE IF NOT EXISTS projects (
+  id TEXT PRIMARY KEY,
+  name TEXT NOT NULL,
+  normalized_name TEXT NOT NULL UNIQUE,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL
+);
+CREATE TABLE IF NOT EXISTS notes (
+  id TEXT PRIMARY KEY,
+  project_id TEXT NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
+  kind TEXT NOT NULL CHECK (kind IN ('decision','fact','procedure','context','research','preference','task')),
+  title TEXT NOT NULL,
+  summary TEXT NOT NULL,
+  content TEXT NOT NULL,
+  size_class TEXT NOT NULL CHECK (size_class IN ('inline','indexed')),
+  pinned INTEGER NOT NULL DEFAULT 0 CHECK (pinned IN (0,1)),
+  status TEXT NOT NULL DEFAULT 'active' CHECK (status IN ('active','superseded','archived')),
+  supersedes_id TEXT,
+  current_revision INTEGER NOT NULL DEFAULT 1 CHECK (current_revision >= 1),
+  subject_key TEXT,
+  content_hash TEXT NOT NULL CHECK (length(content_hash) = 64),
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL,
+  UNIQUE(project_id, id)
+);
+CREATE INDEX IF NOT EXISTS notes_project_idx ON notes(project_id, status);
+CREATE UNIQUE INDEX IF NOT EXISTS notes_active_subject_idx
+  ON notes(project_id, kind, subject_key)
+  WHERE status = 'active' AND subject_key IS NOT NULL;
+CREATE TABLE IF NOT EXISTS note_edges (
+  id TEXT PRIMARY KEY,
+  project_id TEXT NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
+  source_id TEXT NOT NULL,
+  target_id TEXT NOT NULL,
+  predicate TEXT NOT NULL CHECK (predicate IN ('SUPPORTS','DERIVED_FROM','PART_OF','ABOUT','PRECEDES','SUPERSEDES')),
+  created_at INTEGER NOT NULL,
+  UNIQUE(project_id, source_id, target_id, predicate),
+  FOREIGN KEY (project_id, source_id) REFERENCES notes(project_id, id) ON DELETE CASCADE,
+  FOREIGN KEY (project_id, target_id) REFERENCES notes(project_id, id) ON DELETE CASCADE
+);
+CREATE INDEX IF NOT EXISTS note_edges_source_idx ON note_edges(project_id, source_id);
+CREATE INDEX IF NOT EXISTS note_edges_target_idx ON note_edges(project_id, target_id);
+CREATE TABLE IF NOT EXISTS project_bindings (
+  binding_key TEXT PRIMARY KEY,
+  project_id TEXT NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
+  source TEXT NOT NULL CHECK (source = 'opencode-v2'),
+  source_project_id TEXT NOT NULL,
+  workspace_id TEXT NOT NULL,
+  canonical_path_hash TEXT NOT NULL CHECK (length(canonical_path_hash) = 64),
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL,
+  UNIQUE(source, source_project_id, workspace_id)
+);
+CREATE TABLE IF NOT EXISTS capture_checkpoints (
+  session_id TEXT PRIMARY KEY,
+  binding_key TEXT NOT NULL REFERENCES project_bindings(binding_key) ON DELETE CASCADE,
+  project_id TEXT NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
+  state TEXT NOT NULL CHECK (state IN ('active','idle','unavailable','closed')),
+  last_message_id TEXT,
+  last_reconciled_at INTEGER,
+  next_reconcile_at INTEGER NOT NULL,
+  failure_count INTEGER NOT NULL DEFAULT 0 CHECK (failure_count >= 0),
+  lease_owner TEXT,
+  lease_expires_at INTEGER,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL
+);
+CREATE INDEX IF NOT EXISTS capture_checkpoints_due_idx
+  ON capture_checkpoints(state, next_reconcile_at);
+CREATE TABLE IF NOT EXISTS capture_events (
+  idempotency_key TEXT PRIMARY KEY,
+  contract TEXT NOT NULL CHECK (contract = 'opencode2-memory.capture/1'),
+  project_id TEXT NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
+  binding_key TEXT NOT NULL REFERENCES project_bindings(binding_key) ON DELETE CASCADE,
+  event_kind TEXT NOT NULL CHECK (event_kind IN ('user-candidate','assistant-candidate','session-summary','tool-signal')),
+  source_session_id TEXT NOT NULL,
+  source_message_id TEXT,
+  source_ordinal INTEGER CHECK (source_ordinal IS NULL OR source_ordinal >= 0),
+  source_tool_call_id TEXT,
+  payload_json TEXT CHECK (payload_json IS NULL OR json_valid(payload_json)),
+  payload_hash TEXT,
+  redaction_version TEXT NOT NULL,
+  state TEXT NOT NULL CHECK (state IN ('pending','shadowed','review','materialized','duplicate','ignored','rejected','quarantined','failed','dead')),
+  attempt_count INTEGER NOT NULL DEFAULT 0 CHECK (attempt_count >= 0),
+  note_id TEXT,
+  last_error_code TEXT,
+  generation INTEGER NOT NULL DEFAULT 0 CHECK (generation >= 0),
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL,
+  processed_at INTEGER
+);
+CREATE INDEX IF NOT EXISTS capture_events_state_idx ON capture_events(state, updated_at);
+CREATE INDEX IF NOT EXISTS capture_events_session_idx ON capture_events(project_id, source_session_id);
+CREATE INDEX IF NOT EXISTS capture_events_note_idx ON capture_events(project_id, note_id);
+CREATE TABLE IF NOT EXISTS note_provenance (
+  id TEXT PRIMARY KEY,
+  project_id TEXT NOT NULL,
+  note_id TEXT NOT NULL,
+  source_type TEXT NOT NULL CHECK (source_type IN ('mcp-manual','opencode-capture','migration','legacy-import','admin')),
+  capture_event_id TEXT,
+  source_session_id TEXT,
+  source_message_id TEXT,
+  source_ordinal INTEGER,
+  source_tool_call_id TEXT,
+  redaction_version TEXT,
+  extractor_version TEXT,
+  confidence REAL CHECK (confidence IS NULL OR (confidence >= 0 AND confidence <= 1)),
+  created_at INTEGER NOT NULL,
+  UNIQUE(project_id, id),
+  FOREIGN KEY (project_id, note_id) REFERENCES notes(project_id, id) ON DELETE CASCADE
+);
+CREATE TABLE IF NOT EXISTS note_revisions (
+  project_id TEXT NOT NULL,
+  note_id TEXT NOT NULL,
+  revision INTEGER NOT NULL CHECK (revision >= 1),
+  kind TEXT NOT NULL,
+  title TEXT NOT NULL,
+  summary TEXT NOT NULL,
+  content TEXT NOT NULL,
+  size_class TEXT NOT NULL,
+  pinned INTEGER NOT NULL CHECK (pinned IN (0,1)),
+  status TEXT NOT NULL CHECK (status IN ('active','superseded','archived')),
+  supersedes_id TEXT,
+  subject_key TEXT,
+  content_hash TEXT NOT NULL,
+  provenance_id TEXT NOT NULL,
+  created_at INTEGER NOT NULL,
+  PRIMARY KEY(project_id, note_id, revision),
+  FOREIGN KEY (project_id, note_id) REFERENCES notes(project_id, id) ON DELETE CASCADE,
+  FOREIGN KEY (project_id, provenance_id) REFERENCES note_provenance(project_id, id)
+);
+CREATE TABLE IF NOT EXISTS index_outbox (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  backend TEXT NOT NULL,
+  operation TEXT NOT NULL CHECK (operation IN ('upsert-note','delete-note','purge-project')),
+  project_id TEXT NOT NULL,
+  note_id TEXT,
+  revision INTEGER,
+  content_hash TEXT,
+  state TEXT NOT NULL DEFAULT 'pending' CHECK (state IN ('pending','leased','succeeded','dead')),
+  attempt_count INTEGER NOT NULL DEFAULT 0 CHECK (attempt_count >= 0),
+  available_at INTEGER NOT NULL,
+  lease_owner TEXT,
+  lease_expires_at INTEGER,
+  last_error_code TEXT,
+  created_at INTEGER NOT NULL,
+  completed_at INTEGER,
+  UNIQUE(backend, operation, project_id, note_id, revision)
+);
+CREATE INDEX IF NOT EXISTS index_outbox_due_idx
+  ON index_outbox(backend, project_id, state, available_at, id);
+CREATE TABLE IF NOT EXISTS schema_state (version INTEGER PRIMARY KEY);
+`;
+var FTS_V9 = `
+CREATE VIRTUAL TABLE IF NOT EXISTS notes_fts USING fts5(
+  title, summary, content,
+  content='notes', content_rowid='rowid',
+  tokenize='unicode61'
+);
+CREATE TRIGGER IF NOT EXISTS notes_fts_ai AFTER INSERT ON notes BEGIN
+  INSERT INTO notes_fts(rowid, title, summary, content)
+  VALUES (new.rowid, new.title, new.summary, new.content);
+END;
+CREATE TRIGGER IF NOT EXISTS notes_fts_ad AFTER DELETE ON notes BEGIN
+  INSERT INTO notes_fts(notes_fts, rowid, title, summary, content)
+  VALUES ('delete', old.rowid, old.title, old.summary, old.content);
+END;
+CREATE TRIGGER IF NOT EXISTS notes_fts_au AFTER UPDATE OF title, summary, content ON notes BEGIN
+  INSERT INTO notes_fts(notes_fts, rowid, title, summary, content)
+  VALUES ('delete', old.rowid, old.title, old.summary, old.content);
+  INSERT INTO notes_fts(rowid, title, summary, content)
+  VALUES (new.rowid, new.title, new.summary, new.content);
+END;
+`;
+function createSchemaV9(db) {
+  db.exec(SCHEMA_V9_TABLES);
+  db.exec(FTS_V9);
+  db.query("DELETE FROM schema_state").run();
+  db.query("INSERT INTO schema_state(version) VALUES (9)").run();
+}
+function rebuildFts(db) {
+  db.query("INSERT INTO notes_fts(notes_fts) VALUES ('rebuild')").run();
+}
+
+// src/db/migrations/v009.ts
+function migrateV8ToV9(db) {
+  const notes = db.query("SELECT * FROM notes ORDER BY rowid").all();
+  db.exec(`
+    DROP TABLE IF EXISTS capture_checkpoints;
+    DROP TABLE IF EXISTS capture_events;
+    DROP TABLE IF EXISTS project_bindings;
+    DROP TABLE IF EXISTS note_revisions;
+    DROP TABLE IF EXISTS note_provenance;
+    DROP TABLE IF EXISTS index_outbox;
+    DROP TABLE IF EXISTS note_edges_v9;
+    DROP TABLE IF EXISTS notes_v9;
+  `);
+  db.exec(`
+    CREATE TABLE notes_v9 (
+      id TEXT PRIMARY KEY,
+      project_id TEXT NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
+      kind TEXT NOT NULL CHECK (kind IN ('decision','fact','procedure','context','research','preference','task')),
+      title TEXT NOT NULL,
+      summary TEXT NOT NULL,
+      content TEXT NOT NULL,
+      size_class TEXT NOT NULL CHECK (size_class IN ('inline','indexed')),
+      pinned INTEGER NOT NULL DEFAULT 0 CHECK (pinned IN (0,1)),
+      status TEXT NOT NULL DEFAULT 'active' CHECK (status IN ('active','superseded','archived')),
+      supersedes_id TEXT,
+      current_revision INTEGER NOT NULL DEFAULT 1 CHECK (current_revision >= 1),
+      subject_key TEXT,
+      content_hash TEXT NOT NULL CHECK (length(content_hash) = 64),
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL,
+      UNIQUE(project_id, id)
+    );
+    CREATE TABLE note_edges_v9 (
+      id TEXT PRIMARY KEY,
+      project_id TEXT NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
+      source_id TEXT NOT NULL,
+      target_id TEXT NOT NULL,
+      predicate TEXT NOT NULL CHECK (predicate IN ('SUPPORTS','DERIVED_FROM','PART_OF','ABOUT','PRECEDES','SUPERSEDES')),
+      created_at INTEGER NOT NULL,
+      UNIQUE(project_id, source_id, target_id, predicate),
+      FOREIGN KEY (project_id, source_id) REFERENCES notes_v9(project_id, id) ON DELETE CASCADE,
+      FOREIGN KEY (project_id, target_id) REFERENCES notes_v9(project_id, id) ON DELETE CASCADE
+    );
+    INSERT INTO note_edges_v9 SELECT * FROM note_edges;
+  `);
+  const insert = db.query(`
+    INSERT INTO notes_v9
+      (id, project_id, kind, title, summary, content, size_class, pinned, status,
+       supersedes_id, current_revision, subject_key, content_hash, created_at, updated_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 1, NULL, ?, ?, ?)
+  `);
+  const hashes = new Map;
+  for (const note of notes) {
+    const hash = noteContentHash(note.kind, note.title, note.summary, note.content);
+    hashes.set(note.id, hash);
+    insert.run(note.id, note.project_id, note.kind, note.title, note.summary, note.content, note.size_class, note.pinned, note.status, note.supersedes_id, hash, note.created_at, note.updated_at);
+  }
+  db.exec(`
+    DROP TRIGGER IF EXISTS notes_fts_ai;
+    DROP TRIGGER IF EXISTS notes_fts_ad;
+    DROP TRIGGER IF EXISTS notes_fts_au;
+    DROP TABLE IF EXISTS notes_fts;
+    DROP TABLE note_edges;
+    DROP TABLE notes;
+    ALTER TABLE notes_v9 RENAME TO notes;
+    ALTER TABLE note_edges_v9 RENAME TO note_edges;
+  `);
+  db.exec(SCHEMA_V9_TABLES);
+  for (const note of notes) {
+    const provenanceID = randomUUID3();
+    db.query(`
+      INSERT INTO note_provenance
+        (id, project_id, note_id, source_type, created_at)
+      VALUES (?, ?, ?, 'migration', ?)
+    `).run(provenanceID, note.project_id, note.id, note.updated_at);
+    db.query(`
+      INSERT INTO note_revisions
+        (project_id, note_id, revision, kind, title, summary, content, size_class,
+         pinned, status, supersedes_id, subject_key, content_hash, provenance_id, created_at)
+      VALUES (?, ?, 1, ?, ?, ?, ?, ?, ?, ?, ?, NULL, ?, ?, ?)
+    `).run(note.project_id, note.id, note.kind, note.title, note.summary, note.content, note.size_class, note.pinned, note.status, note.supersedes_id, hashes.get(note.id), provenanceID, note.updated_at);
+  }
+  db.exec(FTS_V9);
+  rebuildFts(db);
+  db.query("DELETE FROM schema_state").run();
+  db.query("INSERT INTO schema_state(version) VALUES (9)").run();
+}
+function noteContentHash(kind, title, summary, content) {
+  return createHash3("sha256").update(`${kind}\x00${title}\x00${summary}\x00${content}`, "utf8").digest("hex");
+}
+
+// src/db.ts
+var DDL = `
+CREATE TABLE IF NOT EXISTS projects (
+  id TEXT PRIMARY KEY,
+  name TEXT NOT NULL,
+  normalized_name TEXT NOT NULL UNIQUE,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL
+);
+CREATE TABLE IF NOT EXISTS notes (
+  id TEXT PRIMARY KEY,
+  project_id TEXT NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
+  kind TEXT NOT NULL CHECK (kind IN ('decision','fact','procedure','context','research','preference','task')),
+  title TEXT NOT NULL,
+  summary TEXT NOT NULL,
+  content TEXT NOT NULL,
+  size_class TEXT NOT NULL CHECK (size_class IN ('inline','indexed')),
+  pinned INTEGER NOT NULL DEFAULT 0 CHECK (pinned IN (0,1)),
+  status TEXT NOT NULL DEFAULT 'active' CHECK (status IN ('active','superseded','archived')),
+  supersedes_id TEXT,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL,
+  UNIQUE(project_id, id)
+);
+CREATE INDEX IF NOT EXISTS notes_project_idx ON notes(project_id, status);
+CREATE TABLE IF NOT EXISTS note_edges (
+  id TEXT PRIMARY KEY,
+  project_id TEXT NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
+  source_id TEXT NOT NULL,
+  target_id TEXT NOT NULL,
+  predicate TEXT NOT NULL CHECK (predicate IN ('SUPPORTS','DERIVED_FROM','PART_OF','ABOUT','PRECEDES','SUPERSEDES')),
+  created_at INTEGER NOT NULL,
+  UNIQUE(project_id, source_id, target_id, predicate),
+  FOREIGN KEY (project_id, source_id) REFERENCES notes(project_id, id) ON DELETE CASCADE,
+  FOREIGN KEY (project_id, target_id) REFERENCES notes(project_id, id) ON DELETE CASCADE
+);
+CREATE INDEX IF NOT EXISTS note_edges_source_idx ON note_edges(project_id, source_id);
+CREATE INDEX IF NOT EXISTS note_edges_target_idx ON note_edges(project_id, target_id);
+CREATE TABLE IF NOT EXISTS schema_state (version INTEGER PRIMARY KEY);
+`;
+function openMemoryDatabase(path) {
+  const db = new Database2(path, { create: true });
+  chmodSync2(path, 384);
+  let lock;
+  let backup;
+  try {
+    db.exec("PRAGMA busy_timeout=5000");
+    db.exec("PRAGMA journal_mode=WAL");
+    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}`);
+    }
+    const hasExistingData = hasLegacyV2(db) || hasTable2(db, "notes") || Boolean(existingVersion);
+    if (!hasExistingData) {
+      db.exec("PRAGMA foreign_keys=ON");
+      db.transaction(() => createSchemaV9(db))();
+      assertHealthyDatabase(db);
+      return { db, close: () => db.close() };
+    }
+    if ((existingVersion?.version ?? 0) < SCHEMA_VERSION) {
+      lock = acquireMigrationLock(path, SCHEMA_VERSION);
+      backup = createVerifiedBackup(db, path, existingVersion?.version ?? 2, SCHEMA_VERSION, "0.4.0-beta.1");
+      db.exec("PRAGMA foreign_keys=OFF");
+      if (!existingVersion && 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);
+      } else if (!existingVersion) {
+        db.exec(DDL);
+        db.exec("CREATE VIRTUAL TABLE IF NOT EXISTS notes_fts USING fts5(id UNINDEXED, title, summary, content, tokenize='unicode61')");
+        db.transaction(() => {
+          adoptLegacyProjectIDs(db);
+          db.query("DELETE FROM schema_state").run();
+          db.query("INSERT INTO schema_state (version) VALUES (8)").run();
+        })();
+      } else if (existingVersion.version < 8) {
+        db.exec(DDL);
+        db.exec("CREATE VIRTUAL TABLE IF NOT EXISTS notes_fts USING fts5(id UNINDEXED, title, summary, content, tokenize='unicode61')");
+        migrateToV8(db);
+      }
+      const version = getSchemaVersion(db)?.version ?? 8;
+      if (version < 9)
+        db.transaction(() => migrateV8ToV9(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);
+      console.warn(`[agz-memory] migrated to v${SCHEMA_VERSION} (backup: ${backup.manifestPath})`);
+      lock.release();
+      lock = undefined;
+      return { db, close: () => db.close() };
+    }
+    db.exec("PRAGMA foreign_keys=ON");
+    db.exec(SCHEMA_V9_TABLES);
+    db.exec(FTS_V9);
+    assertHealthyDatabase(db);
+    db.exec("PRAGMA foreign_keys=ON");
+    return { db, close: () => db.close() };
+  } catch (error) {
+    db.close();
+    if (backup) {
+      try {
+        restoreVerifiedBackup(backup.manifestPath, path, "RESTORE_DATABASE_FROM_VERIFIED_BACKUP");
+      } catch (restoreError) {
+        throw new AggregateError([error, restoreError], "migration and automatic restore failed");
+      }
+    }
+    throw error;
+  } finally {
+    lock?.release();
+  }
+}
+function getSchemaVersion(db) {
+  if (!hasTable2(db, "schema_state"))
+    return;
+  return db.query("SELECT version FROM schema_state ORDER BY version DESC LIMIT 1").get();
+}
+function migrateToV8(db) {
+  db.transaction(() => {
+    adoptLegacyProjectIDs(db);
+    const pinned = hasColumn(db, "notes", "pinned") ? "pinned" : "0";
+    db.exec(`
+      CREATE TABLE notes_v7 (
+        id TEXT PRIMARY KEY,
+        project_id TEXT NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
+        kind TEXT NOT NULL CHECK (kind IN ('decision','fact','procedure','context','research','preference','task')),
+        title TEXT NOT NULL,
+        summary TEXT NOT NULL,
+        content TEXT NOT NULL,
+        size_class TEXT NOT NULL CHECK (size_class IN ('inline','indexed')),
+        pinned INTEGER NOT NULL DEFAULT 0 CHECK (pinned IN (0,1)),
+        status TEXT NOT NULL DEFAULT 'active' CHECK (status IN ('active','superseded','archived')),
+        supersedes_id TEXT,
+        created_at INTEGER NOT NULL,
+        updated_at INTEGER NOT NULL,
+        UNIQUE(project_id, id)
+      );
+      INSERT INTO notes_v7
+        (id, project_id, kind, title, summary, content, size_class, pinned, status, supersedes_id, created_at, updated_at)
+      SELECT id, project_id, kind, title, summary, content, size_class, ${pinned}, status, supersedes_id, created_at, updated_at
+        FROM notes;
+      CREATE TABLE note_edges_v7 (
+        id TEXT PRIMARY KEY,
+        project_id TEXT NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
+        source_id TEXT NOT NULL,
+        target_id TEXT NOT NULL,
+        predicate TEXT NOT NULL CHECK (predicate IN ('SUPPORTS','DERIVED_FROM','PART_OF','ABOUT','PRECEDES','SUPERSEDES')),
+        created_at INTEGER NOT NULL,
+        UNIQUE(project_id, source_id, target_id, predicate),
+        FOREIGN KEY (project_id, source_id) REFERENCES notes_v7(project_id, id) ON DELETE CASCADE,
+        FOREIGN KEY (project_id, target_id) REFERENCES notes_v7(project_id, id) ON DELETE CASCADE
+      );
+      INSERT OR IGNORE INTO note_edges_v7
+        (id, project_id, source_id, target_id, predicate, created_at)
+      SELECT e.id, source.project_id, e.source_id, e.target_id, e.predicate, e.created_at
+        FROM note_edges e
+        JOIN notes source ON source.id = e.source_id
+        JOIN notes target ON target.id = e.target_id
+       WHERE source.project_id = target.project_id;
+      DROP TABLE note_edges;
+      DROP TABLE notes;
+      ALTER TABLE notes_v7 RENAME TO notes;
+      ALTER TABLE note_edges_v7 RENAME TO note_edges;
+    `);
+    importLegacyAssociations(db);
+    db.query("DELETE FROM schema_state").run();
+    db.query("INSERT INTO schema_state (version) VALUES (8)").run();
+  })();
+}
+function adoptLegacyProjectIDs(db) {
+  const existingProjects = db.query("SELECT id FROM projects").all();
+  for (const { id: legacyID } of existingProjects) {
+    if (isUUID(legacyID))
+      continue;
+    const id = randomUUID4();
+    db.query("UPDATE projects SET id = ? WHERE id = ?").run(id, legacyID);
+    db.query("UPDATE notes SET project_id = ? WHERE project_id = ?").run(id, legacyID);
+    db.query("UPDATE note_edges SET project_id = ? WHERE project_id = ?").run(id, legacyID);
+  }
+  const rows = db.query("SELECT DISTINCT project_id FROM notes").all();
+  for (const { project_id: legacyID } of rows) {
+    if (db.query("SELECT id FROM projects WHERE id = ?").get(legacyID))
+      continue;
+    const id = randomUUID4();
+    const name = uniqueLegacyProjectName(db, legacyID);
+    const now = Date.now();
+    db.query("INSERT INTO projects (id, name, normalized_name, created_at, updated_at) VALUES (?, ?, ?, ?, ?)").run(id, name, normalizeProjectName(name), now, now);
+    db.query("UPDATE notes SET project_id = ? WHERE project_id = ?").run(id, legacyID);
+    db.query("UPDATE note_edges SET project_id = ? WHERE project_id = ?").run(id, legacyID);
+  }
+}
+function isUUID(value) {
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value);
+}
+function uniqueLegacyProjectName(db, legacyID) {
+  const base = legacyID === "global" ? "Legacy Global" : legacyID === "legacy" ? "Legacy" : `Legacy ${legacyID.slice(0, 12)}`;
+  let name = base;
+  let suffix = 2;
+  while (db.query("SELECT id FROM projects WHERE normalized_name = ?").get(normalizeProjectName(name))) {
+    name = `${base} ${suffix++}`;
+  }
+  return name;
+}
+function hasColumn(db, table, column) {
+  const rows = db.query(`PRAGMA table_info(${table})`).all();
+  return rows.some((row) => row.name === column);
+}
+function hasLegacyV2(db) {
+  return hasTable2(db, "memory_items");
+}
+function hasTable2(db, table) {
+  const row = db.query("SELECT COUNT(*) AS n FROM sqlite_master WHERE type='table' AND name = ?").get(table);
+  return (row?.n ?? 0) > 0;
+}
+var KIND_MAP = {
+  decision: "decision",
+  fact: "fact",
+  observation: "fact",
+  experiment: "fact",
+  hypothesis: "fact",
+  open_question: "fact",
+  rule: "fact",
+  direction: "fact",
+  constraint: "fact",
+  procedure: "procedure",
+  failure_remedy: "procedure",
+  agent_behavior: "procedure",
+  context: "context",
+  preference: "preference"
+};
+function migrateFromV2(db, path) {
+  const requiredTables = ["memory_items", "memory_versions", "memory_identities"];
+  const missingTables = requiredTables.filter((table) => !hasTable2(db, table));
+  if (missingTables.length > 0) {
+    throw new Error(`unsupported legacy schema; missing tables: ${missingTables.join(", ")}`);
+  }
+  const backup = `${path}.v2-backup`;
+  if (!existsSync3(backup)) {
+    db.exec("PRAGMA wal_checkpoint(TRUNCATE)");
+    copyFileSync2(path, backup);
+  }
+  db.transaction(() => {
+    migrateFromV2Data(db, backup, {
+      documents: ["document_sources", "document_chunks", "memories"].every((table) => hasTable2(db, table)),
+      links: hasTable2(db, "memory_links"),
+      edges: hasTable2(db, "memory_edges")
+    });
+    adoptLegacyProjectIDs(db);
+    db.query("DELETE FROM schema_state").run();
+    db.query("INSERT INTO schema_state (version) VALUES (8)").run();
+  })();
+}
+function migrateFromV2Data(db, backup, options) {
+  const now = Date.now();
+  db.query("DELETE FROM notes_fts").run();
+  db.query("DELETE FROM note_edges").run();
+  db.query("DELETE FROM notes").run();
+  db.query("DELETE FROM projects").run();
+  const items = db.query(`SELECT i.id AS item_id, i.subject_key, i.kind, i.created_at, i.updated_at,
+              i.identity_id, v.summary, v.content
+         FROM memory_items i
+         LEFT JOIN memory_versions v ON v.id = i.current_version_id
+        WHERE i.lifecycle_state = 'active'`).all();
+  const identities = new Map;
+  for (const row of db.query("SELECT id, project_id FROM memory_identities").all()) {
+    if (row.project_id)
+      identities.set(row.id, row.project_id);
+  }
+  let migratedNotes = 0;
+  for (const item of items) {
+    const projectID = identities.get(item.identity_id) ?? "legacy";
+    const content = item.content ?? item.summary ?? "";
+    const summary = item.summary ?? content.slice(0, 200);
+    const title = item.subject_key;
+    const kind = KIND_MAP[item.kind] ?? "fact";
+    const sizeClass = content.length <= 1200 ? "inline" : "indexed";
+    db.query(`INSERT INTO notes (id, project_id, kind, title, summary, content, size_class, status, supersedes_id, created_at, updated_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, 'active', NULL, ?, ?)`).run(item.item_id, projectID, kind, title, summary, content, sizeClass, item.created_at, item.updated_at);
+    db.query("INSERT INTO notes_fts (id, title, summary, content) VALUES (?, ?, ?, ?)").run(item.item_id, title, summary, content);
+    migratedNotes++;
+  }
+  const sources = options.documents ? db.query(`SELECT s.id, s.project_root, s.title, s.created_at, s.updated_at,
+               GROUP_CONCAT(m.content, '
+
+') AS body
+          FROM document_sources s
+          JOIN document_chunks c ON c.source_id = s.id
+          JOIN memories m ON m.id = c.memory_id
+         WHERE s.status = 'active'
+         GROUP BY s.id
+         ORDER BY s.created_at`).all() : [];
+  for (const source of sources) {
+    const content = source.body ?? "";
+    if (!content.trim())
+      continue;
+    const id = randomUUID4();
+    db.query(`INSERT INTO notes (id, project_id, kind, title, summary, content, size_class, status, supersedes_id, created_at, updated_at)
+       VALUES (?, ?, 'research', ?, ?, ?, 'indexed', 'active', NULL, ?, ?)`).run(id, source.project_root ? hashRoot(source.project_root) : "legacy", source.title, content.slice(0, 200), content, source.created_at, source.updated_at);
+    db.query("INSERT INTO notes_fts (id, title, summary, content) VALUES (?, ?, ?, ?)").run(id, source.title, content.slice(0, 200), content);
+    migratedNotes++;
+  }
+  const noteIDs = new Set(db.query("SELECT id FROM notes").all().map((r) => r.id));
+  let migratedEdges = 0;
+  const edges = options.edges ? db.query(`SELECT id, source_item_id, target_item_id, predicate, recorded_at
+             FROM memory_edges
+            WHERE lifecycle_state = 'active'`).all() : [];
+  for (const edge of edges) {
+    if (!noteIDs.has(edge.source_item_id) || !noteIDs.has(edge.target_item_id))
+      continue;
+    if (edge.source_item_id === edge.target_item_id)
+      continue;
+    const sourceProject = noteProjectID(db, edge.source_item_id);
+    if (sourceProject !== noteProjectID(db, edge.target_item_id))
+      continue;
+    const predicate = PREDICATES.includes(edge.predicate) ? edge.predicate : "ABOUT";
+    const result = db.query("INSERT OR IGNORE INTO note_edges (id, project_id, source_id, target_id, predicate, created_at) VALUES (?, ?, ?, ?, ?, ?)").run(`edge-${edge.id}`, sourceProject, edge.source_item_id, edge.target_item_id, predicate, edge.recorded_at);
+    migratedEdges += result.changes;
+  }
+  const links = options.links ? db.query("SELECT source_memory_id, target_memory_id FROM memory_links WHERE status = 'active'").all() : [];
+  for (const link of links) {
+    if (!noteIDs.has(link.source_memory_id) || !noteIDs.has(link.target_memory_id))
+      continue;
+    if (link.source_memory_id === link.target_memory_id)
+      continue;
+    const sourceProject = noteProjectID(db, link.source_memory_id);
+    if (sourceProject !== noteProjectID(db, link.target_memory_id))
+      continue;
+    const result = db.query("INSERT OR IGNORE INTO note_edges (id, project_id, source_id, target_id, predicate, created_at) VALUES (?, ?, ?, ?, 'ABOUT', ?)").run(`edge-${link.source_memory_id}-${link.target_memory_id}`, sourceProject, link.source_memory_id, link.target_memory_id, now);
+    migratedEdges += result.changes;
+  }
+  migratedEdges += importLegacyAssociations(db);
+  console.warn(`[agz-memory] v2\u2192v3 migration complete: ${migratedNotes} notes, ${migratedEdges} edges (backup: ${backup})`);
+}
+function importLegacyAssociations(db) {
+  if (!hasTable2(db, "memory_associations"))
+    return 0;
+  const associations = db.query(`SELECT id, left_item_id, right_item_id, kind, created_at
+         FROM memory_associations
+        WHERE lifecycle_state = 'active'`).all();
+  let imported = 0;
+  for (const association of associations) {
+    const source = db.query("SELECT project_id FROM notes WHERE id = ?").get(association.left_item_id);
+    const target = db.query("SELECT project_id FROM notes WHERE id = ?").get(association.right_item_id);
+    if (!source || !target || source.project_id !== target.project_id)
+      continue;
+    if (association.left_item_id === association.right_item_id)
+      continue;
+    const candidate = association.kind.toUpperCase();
+    const predicate = PREDICATES.includes(candidate) ? candidate : "ABOUT";
+    const result = db.query("INSERT OR IGNORE INTO note_edges (id, project_id, source_id, target_id, predicate, created_at) VALUES (?, ?, ?, ?, ?, ?)").run(`association-${association.id}`, source.project_id, association.left_item_id, association.right_item_id, predicate, association.created_at);
+    imported += result.changes;
+  }
+  return imported;
+}
+function noteProjectID(db, noteID) {
+  return db.query("SELECT project_id FROM notes WHERE id = ?").get(noteID).project_id;
+}
+
+// src/admin/doctor.ts
+function doctorDatabase(db) {
+  const health = inspectDatabase(db);
+  const warnings = [];
+  const failures = [];
+  const invariants = {};
+  if (health.integrity !== "ok")
+    failures.push("integrity_check_failed");
+  if (health.foreignKeyViolations.length > 0)
+    failures.push("foreign_key_violation");
+  if (health.schemaVersion === undefined)
+    failures.push("schema_state_missing");
+  else if (health.schemaVersion > SCHEMA_VERSION)
+    failures.push("schema_newer_than_runtime");
+  else if (health.schemaVersion < SCHEMA_VERSION)
+    warnings.push("schema_upgrade_required");
+  if (hasTable(db, "notes_fts") && hasTable(db, "notes")) {
+    invariants.notes = count(db, "SELECT COUNT(*) AS count FROM notes");
+    invariants.fts = count(db, "SELECT COUNT(*) AS count FROM notes_fts");
+    if (invariants.notes !== invariants.fts)
+      failures.push("fts_count_mismatch");
+  }
+  if (health.schemaVersion === SCHEMA_VERSION) {
+    invariants.missingCurrentRevisions = count(db, `SELECT COUNT(*) AS count
+         FROM notes n
+         LEFT JOIN note_revisions r
+           ON r.project_id = n.project_id
+          AND r.note_id = n.id
+          AND r.revision = n.current_revision
+        WHERE r.note_id IS NULL`);
+    invariants.missingProvenance = count(db, `SELECT COUNT(*) AS count
+         FROM note_revisions r
+         LEFT JOIN note_provenance p
+           ON p.project_id = r.project_id AND p.id = r.provenance_id
+        WHERE p.id IS NULL`);
+    invariants.bindingConflicts = count(db, `SELECT COUNT(*) AS count FROM (
+         SELECT source, source_project_id, workspace_id
+           FROM project_bindings
+          GROUP BY source, source_project_id, workspace_id
+         HAVING COUNT(DISTINCT project_id) > 1
+       )`);
+    invariants.deadOutbox = count(db, "SELECT COUNT(*) AS count FROM index_outbox WHERE state = 'dead'");
+    invariants.dueCheckpoints = count(db, "SELECT COUNT(*) AS count FROM capture_checkpoints WHERE next_reconcile_at <= ? AND state = 'active'", Date.now());
+    for (const [name, value] of Object.entries(invariants)) {
+      if (["missingCurrentRevisions", "missingProvenance", "bindingConflicts"].includes(name) && value > 0) {
+        failures.push(name);
+      }
+    }
+  }
+  return { ok: failures.length === 0, health, warnings, failures, invariants };
+}
+function count(db, sql, ...bindings) {
+  return db.query(sql).get(...bindings).count;
+}
+
+// src/retrieval/derived.ts
+import { createHash as createHash4 } from "crypto";
+
+// src/capture/redact.ts
+var RULES = [
+  {
+    name: "private-key",
+    pattern: /-----BEGIN (?:RSA |EC |OPENSSH |DSA )?PRIVATE KEY-----[\s\S]*?-----END (?:RSA |EC |OPENSSH |DSA )?PRIVATE KEY-----/gi,
+    highRisk: true
+  },
+  {
+    name: "credential-uri",
+    pattern: /\b[a-z][a-z0-9+.-]*:\/\/[^\s/:@]+:[^\s/@]+@[^\s]+/gi,
+    highRisk: true
+  },
+  { name: "bearer", pattern: /\bBearer\s+[A-Za-z0-9._~+/=-]{12,}/gi },
+  { name: "basic-auth", pattern: /\bBasic\s+[A-Za-z0-9+/=]{12,}/gi },
+  { name: "github-token", pattern: /\b(?:gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,})\b/g },
+  { name: "gitlab-token", pattern: /\bglpat-[A-Za-z0-9_-]{16,}\b/g },
+  { name: "aws-access-key", pattern: /\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/g },
+  { name: "jwt", pattern: /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/g },
+  {
+    name: "secret-assignment",
+    pattern: /\b(?:PASSWORD|PASSWD|SECRET|TOKEN|API_KEY|PRIVATE_KEY)\s*[:=]\s*["']?[^\s,"']{8,}["']?/gi
+  }
+];
+function redactText(value, options = {}) {
+  const maxCharacters = options.maxCharacters ?? Number.MAX_SAFE_INTEGER;
+  let text = value;
+  let replacements = 0;
+  let highRisk = 0;
+  const classes = {};
+  for (const literal of options.denylist ?? []) {
+    if (!literal)
+      continue;
+    const count2 = text.split(literal).length - 1;
+    if (count2 === 0)
+      continue;
+    replacements += count2;
+    classes.denylist = (classes.denylist ?? 0) + count2;
+    text = text.replaceAll(literal, "[REDACTED:denylist]");
+  }
+  for (const rule of RULES) {
+    text = text.replace(rule.pattern, () => {
+      replacements++;
+      classes[rule.name] = (classes[rule.name] ?? 0) + 1;
+      if (rule.highRisk)
+        highRisk++;
+      return `[REDACTED:${rule.name}]`;
+    });
+  }
+  text = text.replace(/\b[A-Za-z0-9+/=_-]{32,}\b/g, (candidate) => {
+    if (!looksHighEntropy(candidate))
+      return candidate;
+    replacements++;
+    classes.entropy = (classes.entropy ?? 0) + 1;
+    return "[REDACTED:entropy]";
+  });
+  const truncated = text.length > maxCharacters;
+  if (truncated)
+    text = text.slice(0, maxCharacters);
+  return {
+    text,
+    replacements,
+    classes,
+    truncated,
+    quarantined: highRisk > 0 || replacements >= 3
+  };
+}
+function looksHighEntropy(value) {
+  if (!/[A-Za-z]/.test(value) || !/\d/.test(value))
+    return false;
+  const counts = new Map;
+  for (const character of value)
+    counts.set(character, (counts.get(character) ?? 0) + 1);
+  let entropy = 0;
+  for (const count2 of counts.values()) {
+    const probability = count2 / value.length;
+    entropy -= probability * Math.log2(probability);
+  }
+  return entropy >= 4.1;
+}
+
+// src/retrieval/derived.ts
+function deriveDocument(source) {
+  const title = redactText(source.title);
+  const summary = redactText(source.summary);
+  const content = redactText(source.content);
+  if (title.quarantined || summary.quarantined || content.quarantined)
+    return;
+  const contentHash = createHash4("sha256").update(`${source.kind}\x00${title.text}\x00${summary.text}\x00${content.text}`, "utf8").digest("hex");
+  return {
+    projectID: source.projectID,
+    noteID: source.noteID,
+    revision: source.revision,
+    kind: source.kind,
+    title: title.text,
+    summary: summary.text,
+    content: content.text,
+    contentHash
+  };
+}
+
+// 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");
+  if (command === "doctor") {
+    requireExistingDatabase(databasePath);
+    const db = new Database3(databasePath, { readonly: true });
+    try {
+      return doctorDatabase(db);
+    } finally {
+      db.close();
+    }
+  }
+  if (command === "backup" && subcommand !== "prune") {
+    requireExistingDatabase(databasePath);
+    const lock = acquireMigrationLock(databasePath, readSchemaVersion(databasePath));
+    const db = new Database3(databasePath);
+    try {
+      const version = schemaVersion(db);
+      return createVerifiedBackup(db, databasePath, version, version, "0.4.0-beta.1");
+    } finally {
+      db.close();
+      lock.release();
+    }
+  }
+  if (command === "upgrade") {
+    if (option(argv, "--to") !== String(SCHEMA_VERSION)) {
+      throw new Error(`only --to ${SCHEMA_VERSION} is supported`);
+    }
+    const opened = openMemoryDatabase(databasePath);
+    try {
+      return doctorDatabase(opened.db);
+    } finally {
+      opened.close();
+    }
+  }
+  if (command === "restore") {
+    const manifestPath = subcommand;
+    if (!manifestPath)
+      throw new Error("restore manifest path is required");
+    assertInsideBackupRoot(databasePath, manifestPath);
+    const verified = verifyBackupManifest(manifestPath);
+    const confirmation = option(argv, "--confirm");
+    const expectedHash = option(argv, "--sha256");
+    if (!confirmation || !expectedHash) {
+      return { dryRun: true, manifest: verified.manifest, targetPath: databasePath };
+    }
+    if (expectedHash !== verified.manifest.sha256)
+      throw new Error("restore manifest hash mismatch");
+    const lock = acquireMigrationLock(databasePath, verified.manifest.sourceSchema);
+    try {
+      const preservedPath = restoreVerifiedBackup(manifestPath, databasePath, confirmation);
+      return { restored: true, preservedPath, manifest: verified.manifest };
+    } finally {
+      lock.release();
+    }
+  }
+  if (command === "unlock") {
+    const ownerID = option(argv, "--owner");
+    const confirmation = option(argv, "--confirm");
+    if (!ownerID || !confirmation)
+      throw new Error("unlock requires --owner and --confirm");
+    breakMigrationLock(databasePath, ownerID, confirmation);
+    return { unlocked: true, ownerID };
+  }
+  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;
+      const notes = opened.db.query("SELECT * FROM notes WHERE status = 'active' ORDER BY project_id, id").all();
+      const insert = opened.db.query(`
+        INSERT OR IGNORE INTO index_outbox
+          (backend, operation, project_id, note_id, revision, content_hash,
+           state, attempt_count, available_at, created_at)
+        VALUES (?, 'upsert-note', ?, ?, ?, ?, 'pending', 0, ?, ?)
+      `);
+      opened.db.transaction(() => {
+        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
+          });
+          queued += insert.run(backend, note.project_id, note.id, note.current_revision, document?.contentHash ?? null, now, now).changes;
+        }
+      })();
+      return { backend, queued };
+    } finally {
+      opened.close();
+    }
+  }
+  if (command === "outbox" && subcommand === "status") {
+    return withDatabase(databasePath, (db) => ({
+      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
+    }));
+  }
+  if (command === "outbox" && subcommand === "retry") {
+    const id = Number(argv[2]);
+    if (!Number.isSafeInteger(id) || id <= 0)
+      throw new Error("outbox retry requires a positive id");
+    return withDatabase(databasePath, (db) => {
+      const result = db.query(`UPDATE index_outbox
+              SET state = 'pending', available_at = ?, lease_owner = NULL,
+                  lease_expires_at = NULL, last_error_code = NULL
+            WHERE id = ? AND state = 'dead'`).run(Date.now(), id);
+      return { id, retried: result.changes === 1 };
+    });
+  }
+  if (command === "capture" && subcommand === "status") {
+    return withDatabase(databasePath, (db) => ({
+      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()
+    }));
+  }
+  if (command === "backup" && subcommand === "prune") {
+    const entries = backupEntries(databasePath);
+    const root = resolve2(`${databasePath}.backup`);
+    const digest = createHash5("sha256").update(`${resolve2(databasePath)}\x00${root}
+${entries.map((entry) => `${basename2(entry.manifest)}\x00${basename2(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 };
+    }
+    if (option(argv, "--digest") !== digest)
+      throw new Error("backup prune digest mismatch");
+    const currentEntries = entries.map((entry) => {
+      const current = verifiedBackupEntry(root, entry.manifest);
+      if (current.database !== entry.database || current.sha256 !== entry.sha256 || current.size !== entry.size || current.manifestHash !== entry.manifestHash) {
+        throw new Error(`backup changed after confirmation: ${basename2(entry.manifest)}`);
+      }
+      return current;
+    });
+    for (const current of currentEntries) {
+      rmSync3(current.database, { force: true });
+      rmSync3(current.manifest, { force: true });
+    }
+    return { deleted: entries.length, digest };
+  }
+  throw new Error(`unknown admin command: ${argv.join(" ")}`);
+}
+function withDatabase(databasePath, action) {
+  const opened = openMemoryDatabase(databasePath);
+  try {
+    return action(opened.db);
+  } finally {
+    opened.close();
+  }
+}
+function option(argv, name) {
+  const index = argv.indexOf(name);
+  return index >= 0 ? argv[index + 1] : undefined;
+}
+function requireExistingDatabase(databasePath) {
+  if (!existsSync4(databasePath))
+    throw new Error(`database does not exist: ${databasePath}`);
+}
+function readSchemaVersion(databasePath) {
+  const db = new Database3(databasePath, { readonly: true });
+  try {
+    return schemaVersion(db);
+  } finally {
+    db.close();
+  }
+}
+function schemaVersion(db) {
+  const row = db.query("SELECT MAX(version) AS version FROM schema_state").get();
+  if (row.version === null)
+    throw new Error("schema version is missing");
+  return row.version;
+}
+function assertInsideBackupRoot(databasePath, manifestPath) {
+  const root = resolve2(`${databasePath}.backup`);
+  const candidate = resolve2(manifestPath);
+  if (dirname2(candidate) !== root)
+    throw new Error("manifest must be inside the database backup directory");
+}
+function backupEntries(databasePath) {
+  const root = resolve2(`${databasePath}.backup`);
+  if (!existsSync4(root))
+    return [];
+  return readdirSync(root).filter((name) => name.endsWith(".manifest.json")).sort().map((name) => verifiedBackupEntry(root, resolve2(root, name)));
+}
+function verifiedBackupEntry(root, manifest) {
+  const candidate = resolve2(manifest);
+  if (dirname2(candidate) !== root)
+    throw new Error("backup manifest escaped the backup directory");
+  const stat = lstatSync2(candidate);
+  if (!stat.isFile() || stat.isSymbolicLink())
+    throw new Error("backup manifest must be a regular file");
+  const bytes = readFileSync3(candidate);
+  const verified = verifyBackupManifest(candidate);
+  if (dirname2(verified.databasePath) !== root) {
+    throw new Error("backup database escaped the backup directory");
+  }
+  return {
+    manifest: candidate,
+    database: verified.databasePath,
+    sha256: verified.manifest.sha256,
+    size: verified.manifest.size,
+    manifestHash: createHash5("sha256").update(bytes).digest("hex")
+  };
+}
+if (import.meta.main) {
+  try {
+    const result = await runAdmin();
+    process.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+    if (typeof result === "object" && result && "ok" in result && result.ok === false) {
+      process.exitCode = 2;
+    }
+  } catch (error) {
+    process.stderr.write(`[agz-memory-admin] ${error instanceof Error ? error.message : String(error)}
+`);
+    process.exitCode = 1;
+  }
+}
+export {
+  runAdmin
+};