@openparachute/vault 0.7.9-rc.4 → 0.7.9-rc.6

package/core/src/mcp-manifest.ts

@@ -208,6 +208,23 @@ Response shape (vault#550 — three variants, pick by what you passed):
             required: ["note_id"],
             description: "Scope results to notes within N hops of an anchor note",
           },
+          versions: {
+            type: "object",
+            properties: {
+              note_id: { type: "string", description: "Note ID or path" },
+              version_ix: { type: "integer", minimum: 0 },
+              origin: { type: "string", enum: ["git-import"] },
+              import_ix: { type: "integer", minimum: 0 },
+              limit: { type: "integer", minimum: 0, maximum: 200 },
+              offset: { type: "integer", minimum: 0 },
+            },
+            required: ["note_id"],
+            oneOf: [
+              { required: ["origin", "import_ix"], not: { required: ["version_ix"] } },
+              { not: { anyOf: [{ required: ["origin"] }, { required: ["import_ix"] }] } },
+            ],
+            description: "Read note history; mutually exclusive with id, search, near, cursor, aggregate, and semantic. Tag-scoped sessions see the SAME visibility enforcement as every other read — a note outside the token's tag scope answers `not_found`, and a deleted note's history is not readable by a scoped session at all. Deleted-note history is also unavailable to unscoped MCP sessions; restore is REST-only.",
+          },
           sort: {
             type: "string",
             enum: ["asc", "desc"],

package/core/src/mcp.ts

@@ -1,3 +1,4 @@
+import { getImportedVersion, parseHistorySelector, projectHistoryRow } from "./history-import.js";
 import { Database } from "bun:sqlite";
 import type { Store, Note, QueryOpts, Attachment } from "./types.js";
 import { transactionAsync } from "./txn.js";
@@ -184,7 +185,7 @@ function requireNoteReference(value: unknown): string {
  * match required. Same [[wikilink]] semantics as `resolveWikilink`; exact
  * id/path always wins first.
  */
-function resolveNote(db: Database, idOrPath: string): Note | null {
+export function resolveNote(db: Database, idOrPath: string): Note | null {
   // Try ID match first (fast, indexed)
   const byId = noteOps.getNote(db, idOrPath);
   if (byId) return byId;
@@ -692,6 +693,30 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
         // stays byte-identical to the no-pagination behavior.
         const contentRange = parseContentRange(params.content_offset, params.content_length);
 
+        if (params.versions) {
+          for (const key of ["search", "near", "cursor", "aggregate", "semantic", "id"] as const) {
+            if (params[key] !== undefined) throw new QueryError(`versions is incompatible with ${key}`, "INVALID_QUERY", {
+              error_type: "invalid_query", field: "versions", hint: `drop ${key} when using versions`,
+            });
+          }
+          const v = params.versions as { note_id: string; version_ix?: number; origin?: unknown; import_ix?: unknown; limit?: number; offset?: number };
+          const selector = parseHistorySelector(v);
+          const note = requireNote(db, requireNoteReference(v.note_id));
+          if (selector && "import_ix" in selector) {
+            const version = getImportedVersion(db, note.id, selector.import_ix);
+            if (!version) return { error: "Imported version not found", error_type: "not_found", id: v.note_id, ...selector };
+            return projectHistoryRow(version);
+          }
+          if (selector && "version_ix" in selector) {
+            const version = await store.getNoteVersion(note.id, selector.version_ix);
+            if (!version) return { error: `Version not found: "${v.note_id}"@${v.version_ix}`, error_type: "not_found", id: v.note_id, version_ix: v.version_ix };
+            return version;
+          }
+          const versions = await store.listNoteVersions(note.id, { limit: Math.max(0, Math.min(v.limit ?? 50, 200)), offset: v.offset ?? 0 });
+          const total = await store.countNoteVersions(note.id);
+          return { versions: versions.map(projectHistoryRow), total };
+        }
+
         // --- Single note by ID/path ---
         if (params.id) {
           const note = resolveNote(db, params.id as string);
@@ -2280,7 +2305,7 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
       name: "delete-note",
       execute: async (params) => {
         const note = requireNote(db, requireNoteReference(params.id));
-        await store.deleteNote(note.id);
+        await store.deleteNote(note.id, { actor: writeActor, via: writeVia });
         return { deleted: true, id: note.id };
       },
     },
@@ -2494,7 +2519,7 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
             field: "new_name",
           });
         }
-        const result = await store.renameTag(oldName, newName);
+        const result = await store.renameTag(oldName, newName, { actor: writeActor ?? undefined, via: writeVia ?? undefined });
         if ("error" in result) {
           if (result.error === "not_found") {
             throw structuredError(`rename-tag: tag "${oldName}" not found`, {

package/core/src/notes.ts

@@ -31,6 +31,7 @@ import {
   type SearchMode,
 } from "./search-query.js";
 import { generateUlid } from "./ulid.js";
+import { captureVersion, readPriorNoteRow, DEFAULT_HISTORY_POLICY, type HistoryPolicy } from "./history.js";
 
 /**
  * Write-attribution context (vault#298) — the two axes of provenance threaded
@@ -2390,7 +2391,7 @@ export type RenameTagResult =
  * (the store wrapper) bust both `_tagHierarchy` and `_schemaConfig`
  * after the cascade returns.
  */
-export function renameTag(db: Database, oldName: string, newName: string): RenameTagResult {
+export function renameTag(db: Database, oldName: string, newName: string, attr?: { actor?: string | null; via?: string | null }, policy: HistoryPolicy = DEFAULT_HISTORY_POLICY): RenameTagResult {
   // Normalize the TARGET so a rename can never create a `#`-prefixed tag. The
   // SOURCE (`oldName`) is left LITERAL on purpose — it's the transitional escape
   // hatch that lets the `#legacy/*` → `legacy/*` data migration find the
@@ -2590,6 +2591,8 @@ export function renameTag(db: Database, oldName: string, newName: string): Renam
       for (const row of candidates) {
         const next = rewriteNoteBody(row.content, renames);
         if (next === row.content) continue;
+        const prior = readPriorNoteRow(db, row.id);
+        if (prior) captureVersion(db, prior, { actor: attr?.actor ?? null, via: attr?.via ?? null, op: "tag-rename", policy });
         updateStmt.run(next, now, nowMs, row.id);
         notesRewritten++;
       }
@@ -2612,6 +2615,8 @@ export function renameTag(db: Database, oldName: string, newName: string): Renam
       for (const row of candidates) {
         const next = rewriteTagConfigPath(row.path, renames);
         if (next === row.path) continue;
+        const prior = readPriorNoteRow(db, row.id);
+        if (prior) captureVersion(db, prior, { actor: attr?.actor ?? null, via: attr?.via ?? null, op: "tag-rename", policy });
         updateStmt.run(next, now, nowMs, row.id);
         pathsRenamed++;
       }

package/core/src/portable-md.ts

@@ -1961,7 +1961,7 @@ async function importVaultReplay(
       const batch = await store.queryNotes({ sort: "asc", limit: EXPORT_BATCH_SIZE });
       if (batch.length === 0) break;
       for (const note of batch) {
-        await store.deleteNote(note.id);
+        await store.deleteNote(note.id, { captureHistory: false });
         stats.notes_wiped++;
       }
     }

package/core/src/schema-v29-note-versions.test.ts

@@ -0,0 +1,63 @@
+import { it, expect, beforeEach, afterEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { initSchema } from "./schema.js";
+import { BunSqliteStore } from "./store.js";
+let db: Database;
+beforeEach(() => {
+  db = new Database(":memory:");
+  initSchema(db);
+});
+afterEach(() => db.close());
+function dropHistory() {
+  db.exec(
+    "DROP TABLE IF EXISTS note_versions; DROP TABLE IF EXISTS note_blobs;",
+  );
+}
+it("P14a v28 upgrade creates both tables and three indexes without backfill", () => {
+  dropHistory();
+  db.prepare("UPDATE schema_version SET version=28").run();
+  initSchema(db);
+  expect(
+    db.prepare("SELECT MAX(version) AS version FROM schema_version").get(),
+  ).toEqual({ version: 31 });
+  const tables = db
+    .prepare(
+      "SELECT name FROM sqlite_master WHERE type='table' AND name IN ('note_versions','note_blobs') ORDER BY name",
+    )
+    .all();
+  expect(tables).toEqual([{ name: "note_blobs" }, { name: "note_versions" }]);
+  expect(
+    db
+      .prepare(
+        "SELECT name FROM sqlite_master WHERE type='index' AND name IN ('idx_note_versions_note','idx_note_versions_hash','idx_note_versions_superseded')",
+      )
+      .all(),
+  ).toHaveLength(3);
+  expect(db.prepare("SELECT COUNT(*) AS n FROM note_versions").get()).toEqual({
+    n: 0,
+  });
+});
+it("P14b repeated init is idempotent", () => {
+  initSchema(db);
+  initSchema(db);
+  expect(db.prepare("SELECT COUNT(*) AS n FROM note_versions").get()).toEqual({
+    n: 0,
+  });
+});
+it("P14c rerunning the v29 migration preserves captured rows", async () => {
+  const store = new BunSqliteStore(db);
+  const n = await store.createNote("a");
+  await store.updateNote(n.id, { content: "b" });
+  db.prepare("UPDATE schema_version SET version=28").run();
+  initSchema(db);
+  expect((await store.getNoteVersion(n.id, 0))!.content).toBe("a");
+});
+it("P14d missing tables before the first capture degrade to no history", async () => {
+  const store = new BunSqliteStore(db);
+  const n = await store.createNote("a");
+  // Drop before this handle has probed true. A drop after capture is an
+  // accepted throw because historyTablesPresent memoises true per handle.
+  dropHistory();
+  await store.updateNote(n.id, { content: "b" });
+  expect((await store.getNote(n.id))!.content).toBe("b");
+});

package/core/src/schema-v30-note-deltas.test.ts

@@ -0,0 +1,51 @@
+import { test, expect } from "bun:test";
+import { Database } from "bun:sqlite";
+import { BunSqliteStore } from "./store.js";
+import { initSchema, SCHEMA_VERSION } from "./schema.js";
+test("P12 v29 opens losslessly, fresh and upgraded columns/indexes agree", async () => {
+  const db = new Database(":memory:"), fresh = new Database(":memory:");
+  try {
+    const store = new BunSqliteStore(db);
+    const a = await store.createNote("one"), b = await store.createNote("other");
+    await store.updateNote(a.id, { content: "two" });
+    await store.updateNote(a.id, { content: "three" });
+    await store.deleteNote(a.id);
+    await store.updateNote(b.id, { content: "changed" });
+    // Remove only v30 additions to recreate the actual v29 table shape.
+    db.exec("DROP INDEX IF EXISTS idx_note_blobs_delta_of");
+    const cols = (table: string) => db.prepare(`PRAGMA table_info(${table})`).all() as {
+      name: string;
+    }[];
+    if (cols("note_blobs").some(c => c.name === "delta_of"))
+      db.exec("ALTER TABLE note_blobs DROP COLUMN delta_of");
+    if (cols("note_blobs").some(c => c.name === "encoding"))
+      db.exec("ALTER TABLE note_blobs DROP COLUMN encoding");
+    if (cols("note_versions").some(c => c.name === "created_at"))
+      db.exec("ALTER TABLE note_versions DROP COLUMN created_at");
+    db.exec("UPDATE schema_version SET version=29");
+    const snap = () => ({ blobs: db.prepare("SELECT hash,content,byte_size FROM note_blobs ORDER BY hash").all(), versions: db.prepare("SELECT note_id,version_ix,content_hash,path,metadata,extension,superseded_at,actor,via,op,content_len,encoding FROM note_versions ORDER BY note_id,version_ix").all() });
+    const before = snap();
+    expect(() => initSchema(db)).not.toThrow();
+    expect(SCHEMA_VERSION).toBe(31);
+    expect(snap()).toEqual(before);
+    expect(db.prepare("SELECT hash FROM note_blobs WHERE delta_of IS NOT NULL OR encoding IS NOT NULL").all()).toEqual([]);
+    expect(db.prepare("SELECT note_id FROM note_versions WHERE created_at IS NOT NULL").all()).toEqual([]);
+    initSchema(fresh);
+    for (const table of ["note_blobs", "note_versions"]) {
+      expect(cols(table).map(c => c.name).sort()).toEqual((fresh.prepare(`PRAGMA table_info(${table})`).all() as {
+        name: string;
+      }[]).map(c => c.name).sort());
+    }
+    for (const handle of [db, fresh])
+      expect(handle.prepare("SELECT name FROM sqlite_master WHERE name='idx_note_blobs_delta_of'").get()).not.toBeNull();
+    expect(db.prepare("PRAGMA integrity_check").get()).toEqual({ integrity_check: "ok" });
+    expect(db.prepare("PRAGMA foreign_key_check").all()).toEqual([]);
+    initSchema(db);
+    expect(snap()).toEqual(before);
+    expect(() => db.exec("UPDATE note_blobs SET delta_of='nosuchhash'")).toThrow("FOREIGN KEY");
+  }
+  finally {
+    db.close();
+    fresh.close();
+  }
+});

package/core/src/schema-v31-history-import.test.ts

@@ -0,0 +1,25 @@
+import { test, expect } from "bun:test";
+import { Database } from "bun:sqlite";
+import { SqliteStore } from "./store.js";
+import { initSchema } from "./schema.js";
+
+test("v30 to v31 retains native history and matches fresh import tables; reopening is idempotent", async () => {
+  const db = new Database(":memory:"), fresh = new Database(":memory:");
+  try {
+    const store = new SqliteStore(db), note = await store.createNote("before");
+    await store.updateNote(note.id, { content: "after" });
+    const tables = ["history_import_refs", "history_import_receipts", "history_import_runs"];
+    for (const table of tables) db.exec(`DROP TABLE ${table}`);
+    db.exec("UPDATE schema_version SET version=30");
+    const before = db.query("SELECT * FROM note_versions").all();
+    initSchema(db); initSchema(fresh); initSchema(db);
+    expect(db.query("SELECT MAX(version) AS version FROM schema_version").get()).toEqual({ version: 31 });
+    expect(db.query("SELECT * FROM note_versions").all()).toEqual(before);
+    for (const table of tables) {
+      expect(db.query(`PRAGMA table_info(${table})`).all()).toEqual(fresh.query(`PRAGMA table_info(${table})`).all());
+      expect(db.query(`SELECT * FROM ${table}`).all()).toEqual([]);
+    }
+    expect(db.query("PRAGMA foreign_key_check").all()).toEqual([]);
+    expect(db.query("PRAGMA integrity_check").get()).toEqual({ integrity_check: "ok" });
+  } finally { db.close(); fresh.close(); }
+});

package/core/src/schema.ts

@@ -6,7 +6,7 @@ import { transaction } from "./txn.js";
 import { timestampToMs } from "./cursor.js";
 import { ensureRelationshipColumn } from "./wikilinks.js";
 
-export const SCHEMA_VERSION = 28;
+export const SCHEMA_VERSION = 31;
 
 /**
  * Deterministic last-resort epoch for a note whose `updated_at` AND
@@ -142,6 +142,114 @@ CREATE TABLE IF NOT EXISTS note_vectors (
 -- sweep (a model <> ? scan) the backfill/drain use to find pending work.
 CREATE INDEX IF NOT EXISTS idx_note_vectors_stale ON note_vectors(model, content_hash);
 
+-- note_blobs + note_versions (v29, vault#524): note-level version history.
+--
+-- STORAGE. A version row is skinny; the BODY lives once per distinct content,
+-- keyed by its sha256, in note_blobs. A metadata-only edit on a 116 KB note
+-- costs one ~300-byte version row and a no-op \`INSERT OR IGNORE\` on the blob —
+-- the whole answer to "does every little update store an entirely new copy?"
+-- Live \`notes.content\` stays on \`notes\`: no join on the hot read path.
+--
+-- encoding IS NULL FOR EVERY ORDINARY ROW IN v29. NULL means "content_hash
+-- names a WHOLE blob". It exists so the PR-2 compactor can rewrite an old row
+-- to reference a delta (setting a format marker) with no second migration and
+-- no version-id change. The ONE non-NULL value v29 ever writes is the literal
+-- 'overflow', on a delete tombstone for a note whose body exceeded
+-- VERSION_MAX_BYTES: the row records that the note WAS deleted and how big it
+-- was, with content_hash NULL because the bytes were never blobbed. A delete
+-- must never be blocked by history (see history.ts captureVersion step 5).
+-- A restore marker copied from that tombstone also retains overflow encoding
+-- and a NULL hash, including after the note has been recreated.
+--
+-- content_hash IS NULLABLE, and it is nullable ONLY for that overflow
+-- tombstone or its copied restore marker. Every consumer must filter NULL —
+-- in particular gcBlobs's \`NOT IN (SELECT content_hash ...)\` MUST carry
+-- \`WHERE content_hash IS NOT NULL\`, or one NULL in the subquery makes the
+-- whole NOT IN evaluate to NULL and the sweep silently deletes nothing.
+--
+-- NO \`REFERENCES notes(id) ON DELETE CASCADE\` — the one deviation from
+-- note_vectors above, deliberate. deleteNote writes a final op='delete' row and
+-- the \`notes\` row then goes away; a cascade would delete the only surviving
+-- copy at the instant it became the only copy. Deleted-note history is reaped
+-- by the configurable sweep (history.deleted_retention_days) or an explicit
+-- erase, never by the FK.
+--
+-- content_hash DOES have a real FK to note_blobs with the default NO ACTION,
+-- so SQLite itself enforces the one invariant refcount GC protects: deleting a
+-- still-referenced blob raises instead of silently orphaning a version.
+-- foreign_keys is turned ON per connection in applyConnectionPragmas
+-- (schema.ts:486) — but inside a SWALLOWING try/catch, so on a handle where
+-- the pragma throws there is no FK enforcement at all and no signal. The
+-- NOT EXISTS guard on every blob delete is therefore the PRIMARY defence and
+-- the FK is the backstop, not the other way round (§4.6).
+-- note_blobs.encoding IS NULL  -> \`content\` is the literal body, \`byte_size\`
+--   is its UTF-8 byte length, and \`hash\` = sha256(content). This is every row
+--   v29 ever wrote.
+-- note_blobs.encoding = 'fossil-delta' -> \`content\` is the BASE64 of a Fossil
+--   delta that reconstructs this row's logical body from the body of the blob
+--   named by \`delta_of\`; \`byte_size\` is the length of that base64 payload, i.e.
+--   the bytes actually stored. \`hash\` is STILL sha256 of the LOGICAL body, so
+--   every note_versions.content_hash reference and its FK stay valid and
+--   content-addressed identity is never a delta hash (ClaudeJi R3).
+--   The LOGICAL byte length is note_versions.content_len, which PR 1
+--   denormalised for exactly this moment (PR 1 §2.1: "it must stay readable
+--   after PR 2 deltifies the blob").
+-- ANY OTHER \`encoding\` VALUE IS CORRUPTION. It is not a future format marker to
+--   be tolerated: a read of such a row answers 409 (materialise's
+--   "unknown_encoding" branch) and the doctor counts it (historyStorageStats's
+--   unknown_encoding_blobs). A later format adds its value here AND to both.
+--
+-- DEPTH IS EXACTLY ONE, AND THAT IS AN INVARIANT, NOT A TUNING CHOICE.
+--   delta_of MUST name a row whose \`encoding IS NULL\`. A delta is never the
+--   base of another delta. Rebuilding any version is therefore ONE applyDelta,
+--   measured p95 3.73 ms / p99 4.68 ms on a 116 KB note, against 38.98 ms /
+--   49.99 ms for a 24-link chain on the same note -- the chain sits ON the
+--   50 ms budget with no headroom. Star also confines corruption: a damaged
+--   delta loses one version, not every older one. See §11.1 D1.
+--
+-- delta_of carries a REAL self-referential FK with the default NO ACTION, and
+-- it IS enforced on a bun handle (probe E: deleting a referenced base raises
+-- FOREIGN KEY constraint failed). It is the backstop; the NOT EXISTS guards in
+-- pruneVersions and gcBlobs are the primary defence, exactly as for
+-- content_hash in v29 (PR 1 §4.6).
+--
+-- note_versions.created_at (#735) is the captured note's OWN creation time,
+-- copied from notes.created_at at capture. NULL on every pre-v30 row; a
+-- deleted-note restore falls back to the tombstone's superseded_at when it is
+-- NULL, which is precisely v29's behaviour.
+CREATE TABLE IF NOT EXISTS note_blobs (
+  hash       TEXT PRIMARY KEY,
+  content    TEXT NOT NULL,
+  byte_size  INTEGER NOT NULL,
+  encoding TEXT,
+  delta_of TEXT REFERENCES note_blobs(hash)
+);
+
+CREATE TABLE IF NOT EXISTS note_versions (
+  note_id       TEXT NOT NULL,
+  version_ix    INTEGER NOT NULL,
+  content_hash  TEXT REFERENCES note_blobs(hash),
+  path          TEXT,
+  metadata      TEXT,
+  extension     TEXT,
+  superseded_at TEXT NOT NULL,
+  actor         TEXT,
+  via           TEXT,
+  op            TEXT NOT NULL,
+  content_len   INTEGER NOT NULL,
+  encoding      TEXT,
+  created_at    TEXT,
+  PRIMARY KEY (note_id, version_ix)
+);
+-- list/get (newest first) + the prune walk.
+CREATE INDEX IF NOT EXISTS idx_note_versions_note ON note_versions(note_id, version_ix DESC);
+-- the age half of retention + the deleted-note sweep.
+CREATE INDEX IF NOT EXISTS idx_note_versions_superseded ON note_versions(superseded_at);
+-- refcount GC: "is any version still pointing at this blob?" This index is
+-- what keeps gcBlobs's per-vault-open anti-join off a full table scan; the
+-- boot sweep runs it on an opted-in vault's open path (§4.6).
+CREATE INDEX IF NOT EXISTS idx_note_versions_hash ON note_versions(content_hash);
+
 -- tag_schemas (v6) was retired in v14; description + fields lifted onto the
 -- tags row directly. The CREATE TABLE was removed from SCHEMA_SQL after the
 -- v14 data migration drops the table; existing v6+ vaults pick up the
@@ -629,6 +737,12 @@ export function initSchema(db: Database): void {
   // queued an unresolved link, and does not rewrite notes.
   migrateToV28(db);
 
+  // v29: note-level history, no backfill.
+  migrateToV29(db);
+  // v30: depth-one history deltas and captured creation time, no backfill.
+  migrateToV30(db);
+  migrateToV31(db);
+
   // Rebuild any generated columns + indexes declared in indexed_fields.
   // No-op for a fresh vault; idempotent on existing vaults.
   rebuildIndexes(db);
@@ -1756,6 +1870,94 @@ function migrateToV28(db: Database): void {
   ensureRelationshipColumn(db);
 }
 
+/** Add history tables and indexes without moving existing note data. */
+function migrateToV29(db: Database): void {
+  transaction(db, () => {
+    db.exec(`
+-- note_blobs + note_versions (v29, vault#524): note-level version history.
+--
+-- STORAGE. A version row is skinny; the BODY lives once per distinct content,
+-- keyed by its sha256, in note_blobs. A metadata-only edit on a 116 KB note
+-- costs one ~300-byte version row and a no-op \`INSERT OR IGNORE\` on the blob —
+-- the whole answer to "does every little update store an entirely new copy?"
+-- Live \`notes.content\` stays on \`notes\`: no join on the hot read path.
+--
+-- encoding IS NULL FOR EVERY ORDINARY ROW IN v29. NULL means "content_hash
+-- names a WHOLE blob". It exists so the PR-2 compactor can rewrite an old row
+-- to reference a delta (setting a format marker) with no second migration and
+-- no version-id change. The ONE non-NULL value v29 ever writes is the literal
+-- 'overflow', on a delete tombstone for a note whose body exceeded
+-- VERSION_MAX_BYTES: the row records that the note WAS deleted and how big it
+-- was, with content_hash NULL because the bytes were never blobbed. A delete
+-- must never be blocked by history (see history.ts captureVersion step 5).
+-- A restore marker copied from that tombstone also retains overflow encoding
+-- and a NULL hash, including after the note has been recreated.
+--
+-- content_hash IS NULLABLE, and it is nullable ONLY for that overflow
+-- tombstone or its copied restore marker. Every consumer must filter NULL —
+-- in particular gcBlobs's \`NOT IN (SELECT content_hash ...)\` MUST carry
+-- \`WHERE content_hash IS NOT NULL\`, or one NULL in the subquery makes the
+-- whole NOT IN evaluate to NULL and the sweep silently deletes nothing.
+--
+-- NO \`REFERENCES notes(id) ON DELETE CASCADE\` — the one deviation from
+-- note_vectors above, deliberate. deleteNote writes a final op='delete' row and
+-- the \`notes\` row then goes away; a cascade would delete the only surviving
+-- copy at the instant it became the only copy. Deleted-note history is reaped
+-- by the configurable sweep (history.deleted_retention_days) or an explicit
+-- erase, never by the FK.
+--
+-- content_hash DOES have a real FK to note_blobs with the default NO ACTION,
+-- so SQLite itself enforces the one invariant refcount GC protects: deleting a
+-- still-referenced blob raises instead of silently orphaning a version.
+-- foreign_keys is turned ON per connection in applyConnectionPragmas
+-- (schema.ts:486) — but inside a SWALLOWING try/catch, so on a handle where
+-- the pragma throws there is no FK enforcement at all and no signal. The
+-- NOT EXISTS guard on every blob delete is therefore the PRIMARY defence and
+-- the FK is the backstop, not the other way round (§4.6).
+CREATE TABLE IF NOT EXISTS note_blobs (
+  hash       TEXT PRIMARY KEY,
+  content    TEXT NOT NULL,
+  byte_size  INTEGER NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS note_versions (
+  note_id       TEXT NOT NULL,
+  version_ix    INTEGER NOT NULL,
+  content_hash  TEXT REFERENCES note_blobs(hash),
+  path          TEXT,
+  metadata      TEXT,
+  extension     TEXT,
+  superseded_at TEXT NOT NULL,
+  actor         TEXT,
+  via           TEXT,
+  op            TEXT NOT NULL,
+  content_len   INTEGER NOT NULL,
+  encoding      TEXT,
+  PRIMARY KEY (note_id, version_ix)
+);
+-- list/get (newest first) + the prune walk.
+CREATE INDEX IF NOT EXISTS idx_note_versions_note ON note_versions(note_id, version_ix DESC);
+-- the age half of retention + the deleted-note sweep.
+CREATE INDEX IF NOT EXISTS idx_note_versions_superseded ON note_versions(superseded_at);
+-- refcount GC: "is any version still pointing at this blob?" This index is
+-- what keeps gcBlobs's per-vault-open anti-join off a full table scan; the
+-- boot sweep runs it on an opted-in vault's open path (§4.6).
+CREATE INDEX IF NOT EXISTS idx_note_versions_hash ON note_versions(content_hash);
+    `);
+  });
+}
+
+/** Add delta representation and creation time without moving prior rows. */
+function migrateToV30(db: Database): void {
+  transaction(db, () => {
+    if (hasTable(db, "note_blobs") && !hasColumn(db, "note_blobs", "encoding")) db.exec("ALTER TABLE note_blobs ADD COLUMN encoding TEXT");
+    if (hasTable(db, "note_blobs") && !hasColumn(db, "note_blobs", "delta_of")) db.exec("ALTER TABLE note_blobs ADD COLUMN delta_of TEXT REFERENCES note_blobs(hash)");
+    if (hasTable(db, "note_versions") && !hasColumn(db, "note_versions", "created_at")) db.exec("ALTER TABLE note_versions ADD COLUMN created_at TEXT");
+    // SCHEMA_SQL runs before migrations: the index must be created here.
+    db.exec("CREATE INDEX IF NOT EXISTS idx_note_blobs_delta_of ON note_blobs(delta_of)");
+  });
+}
+
 function hasTable(db: Database, name: string): boolean {
   const row = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name=?").get(name);
   return !!row;
@@ -1831,3 +2033,34 @@ function migrateFromV2(db: Database): void {
   // Re-enable FK checks
   db.exec("PRAGMA foreign_keys = ON");
 }
+
+/** Import receipts deliberately survive version retention and erasure. */
+function migrateToV31(db: Database): void {
+  transaction(db, () => db.exec(`
+    CREATE TABLE IF NOT EXISTS history_import_runs (
+      run_id TEXT PRIMARY KEY,
+      source_fingerprint TEXT NOT NULL,
+      tip TEXT NOT NULL,
+      options_digest TEXT NOT NULL,
+      status TEXT NOT NULL CHECK(status IN ('applying', 'complete')),
+      created_at TEXT NOT NULL
+    );
+    CREATE TABLE IF NOT EXISTS history_import_receipts (
+      note_id TEXT PRIMARY KEY,
+      run_id TEXT NOT NULL REFERENCES history_import_runs(run_id),
+      state_digest TEXT NOT NULL,
+      imported_count INTEGER NOT NULL,
+      retained_count INTEGER NOT NULL,
+      pruned_imported INTEGER NOT NULL,
+      pruned_native INTEGER NOT NULL,
+      completed_at TEXT NOT NULL
+    );
+    CREATE TABLE IF NOT EXISTS history_import_refs (
+      note_id TEXT NOT NULL REFERENCES history_import_receipts(note_id),
+      import_ix INTEGER NOT NULL CHECK(import_ix >= 0),
+      source_commit TEXT NOT NULL,
+      source_blob TEXT NOT NULL,
+      PRIMARY KEY(note_id, import_ix)
+    );
+  `));
+}