@openparachute/vault 0.7.9-rc.3 → 0.7.9-rc.5

package/core/src/compact.test.ts

@@ -0,0 +1,248 @@
+import { test, expect, beforeEach, afterEach, spyOn } from "bun:test";
+import { Database } from "bun:sqlite";
+import { BunSqliteStore } from "./store.js";
+import * as h from "./history.js";
+const codec = await import("./delta.js").catch(() => null);
+let db: Database, store: BunSqliteStore;
+beforeEach(() => { db = new Database(":memory:"); store = new BunSqliteStore(db); });
+afterEach(() => db.close());
+const blobs = () => db.prepare("SELECT hash,content,byte_size,encoding,delta_of FROM note_blobs ORDER BY hash").all();
+const versions = () => db.prepare("SELECT note_id,version_ix,content_hash,path,metadata,extension,superseded_at,actor,via,op,content_len,encoding,created_at FROM note_versions ORDER BY note_id,version_ix").all();
+async function seed(count = 12, size = 20000, label = "note") {
+  const body = (label + " abcdefghijklmnop\n").repeat(Math.ceil(size / (label.length + 18))).slice(0, size);
+  const n = await store.createNote(body, { path: label, created_at: "2001-01-01T00:00:00.000Z" });
+  for (let i = 0; i < count; i++)
+    await store.updateNote(n.id, { append: `\nedit ${i}` });
+  return n;
+}
+function randomHex(size: number) { const bytes = new Uint8Array(size / 2); for (let i = 0; i < bytes.length; i += 65536)
+  crypto.getRandomValues(bytes.subarray(i, i + 65536)); return Buffer.from(bytes).toString("hex"); }
+async function map(id: string) { return Promise.all((await store.listNoteVersions(id, { limit: 1000 })).map(async (v) => [v.version_ix, (await store.getNoteVersion(id, v.version_ix))!.content])); }
+test("P3/P8 stars roll over, preserve all bodies and rerun idempotently", async () => {
+  const n = await seed(50);
+  const before = await map(n.id);
+  expect(store.compactNote(n.id).blobs_deltified).toBeGreaterThanOrEqual(45);
+  expect(h.historyStorageStats(db).whole_blobs).toBeLessThanOrEqual(3);
+  expect(h.historyStorageStats(db).whole_blobs).toBeGreaterThanOrEqual(1);
+  expect(h.historyStorageStats(db).orphan_deltas).toBe(0);
+  expect(await map(n.id)).toEqual(before);
+  const after = blobs();
+  expect(store.compactNote(n.id).blobs_deltified).toBe(0);
+  expect(blobs()).toEqual(after);
+});
+test("P4/P5 GC removes orphan deltas, protects bases, and drains two waves", async () => {
+  const n = await seed();
+  store.compactNote(n.id);
+  const first = db.prepare("SELECT v.version_ix,b.hash,b.delta_of FROM note_versions v JOIN note_blobs b ON b.hash=v.content_hash WHERE b.encoding='fossil-delta' ORDER BY v.version_ix LIMIT 1").get() as any;
+  expect(() => db.prepare("DELETE FROM note_blobs WHERE hash=?").run(first.delta_of)).toThrow("FOREIGN KEY");
+  db.prepare("DELETE FROM note_versions WHERE note_id=? AND version_ix=?").run(n.id, first.version_ix);
+  h.gcBlobs(db);
+  expect(db.prepare("SELECT hash FROM note_blobs WHERE hash=?").get(first.hash)).toBeNull();
+  expect(db.prepare("SELECT hash FROM note_blobs WHERE hash=?").get(first.delta_of)).not.toBeNull();
+  h.eraseHistory(db, n.id);
+  expect(blobs()).toEqual([]);
+});
+test("P4 shared base survives erasure of another note", async () => {
+  const n = await seed();
+  const base = (await store.listNoteVersions(n.id))[0]!;
+  const text = (await store.getNoteVersion(n.id, base.version_ix))!.content!;
+  const other = await store.createNote(text);
+  await store.updateNote(other.id, { append: "other" });
+  store.compactNote(n.id);
+  h.eraseHistory(db, n.id);
+  expect(h.readBlobContent(db, base.content_hash!)).toBe(text);
+  expect((await store.getNoteVersion(other.id, 0))!.content).toBe(text);
+});
+test("P6 triggers and off switch leave blobs unchanged; writes never compact", async () => {
+  const n = await seed(9);
+  let before = blobs();
+  expect(store.compactNote(n.id).blobs_deltified).toBe(0);
+  expect(blobs()).toEqual(before);
+  expect(h.compactNote(db, n.id, h.resolveHistoryPolicy({ compact_min_versions: 2, compact_ratio: 100 })).blobs_deltified).toBe(0);
+  expect(blobs()).toEqual(before);
+  const large = await seed(20, 20000, "off");
+  before = blobs();
+  expect(h.compactNote(db, large.id, h.resolveHistoryPolicy({ compact_enabled: false, max_bytes_per_note: 65536, min_versions: 1 })).versions_dropped).toBe(0);
+  expect(blobs()).toEqual(before);
+  for (let i = 0; i < 200; i++)
+    await store.updateNote(n.id, { append: `ordinary ${i}` });
+  expect(db.prepare("SELECT hash FROM note_blobs WHERE encoding IS NOT NULL").all()).toEqual([]);
+  // A live empty body has size zero, not the newest retained body's size.
+  const emptyDb = new Database(":memory:");
+  try {
+    const emptyStore = new BunSqliteStore(emptyDb, { history: { compact_min_versions: 2 } });
+    const empty = await emptyStore.createNote("empty fixture".repeat(2000));
+    await emptyStore.updateNote(empty.id, { append: "one" });
+    await emptyStore.updateNote(empty.id, { content: "" });
+    expect(emptyStore.compactHistory({ budgetMs: null, maxNotes: null }).notes_compacted).toBe(1);
+  } finally { emptyDb.close(); }
+});
+test("P7 third encode failure rolls back all changes", async () => {
+  const n = await seed();
+  const b = blobs(), v = versions();
+  expect(codec).not.toBeNull();
+  const original = codec!.encodeDelta;
+  let count = 0;
+  const mock = spyOn(codec!, "encodeDelta").mockImplementation((a, b) => { if (++count === 3)
+    throw Error("injected"); return original(a, b); });
+  try {
+    expect(() => store.compactNote(n.id)).toThrow("injected");
+    expect(blobs()).toEqual(b);
+    expect(versions()).toEqual(v);
+  }
+  finally {
+    mock.mockRestore();
+  }
+  expect(store.compactNote(n.id).blobs_deltified).toBeGreaterThan(0);
+});
+test("P8 bounded passes resume and converge; unbounded visits all", async () => {
+  for (let i = 0; i < 3; i++)
+    await seed(12, 20000, `note${i}`);
+  for (let left = 2; left >= 0; left--) {
+    const r = store.compactHistory({ maxNotes: 1, budgetMs: null });
+    expect(r.notes_compacted).toBe(1);
+    expect(r.remaining_candidates).toBe(left);
+    expect(r.stopped_by).toBe(left ? "max_notes" : "complete");
+  }
+  expect(store.compactHistory({ maxNotes: null, budgetMs: null }).notes_scanned).toBe(0);
+  for (let i = 0; i < 3; i++)
+    await seed(12, 20000, `more${i}`);
+  const budget = store.compactHistory({ budgetMs: 1, maxNotes: null });
+  expect(budget.stopped_by).toBe("budget");
+  expect(budget.notes_scanned).toBe(1);
+  expect(budget.notes_compacted).toBe(1);
+  const all = store.compactHistory({ budgetMs: null, maxNotes: null });
+  expect(all.stopped_by).toBe("complete");
+  expect(all.remaining_candidates).toBe(0);
+});
+test("P16/P8 incompressible candidates are refused on every pass", async () => {
+  const bodies = Array.from({ length: 5 }, () => randomHex(20480));
+  expect(codec).not.toBeNull();
+  expect(codec!.encodeDelta(bodies[1]!, bodies[0]!).length).toBeGreaterThanOrEqual(20480 * .9);
+  const n = await store.createNote(bodies[0]!);
+  for (let i = 1; i <= 5; i++)
+    await store.updateNote(n.id, { content: bodies[i % 5]! });
+  const p = h.resolveHistoryPolicy({ compact_min_versions: 2, compact_ratio: 1 });
+  const before = blobs();
+  for (let i = 0; i < 2; i++) {
+    const result = h.compactNote(db, n.id, p);
+    expect(result.blobs_deltified).toBe(0);
+    expect(result.blobs_skipped_too_large).toBeGreaterThanOrEqual(1);
+    expect(blobs()).toEqual(before);
+    expect(h.compactVault(db, p, { budgetMs: null, maxNotes: null })).toMatchObject({ notes_scanned: 1, stopped_by: "complete" });
+  }
+  const twin = await seed();
+  expect(store.compactNote(twin.id)).toMatchObject({ blobs_skipped_too_large: 0 });
+  expect(h.historyStorageStats(db).delta_blobs).toBeGreaterThan(0);
+});
+test("P14 overflow rows stay unchanged during compaction", async () => {
+  const n = await store.createNote("x".repeat(h.VERSION_MAX_BYTES + 1));
+  await store.deleteNote(n.id);
+  const before = await store.listNoteVersions(n.id);
+  expect(before[0]!.created_at).toBe(n.createdAt);
+  await seed();
+  store.compactHistory({ budgetMs: null, maxNotes: null });
+  expect(await store.listNoteVersions(n.id)).toEqual(before);
+  expect(await store.getNoteVersion(n.id, 0)).toMatchObject({ content: null, encoding: "overflow" });
+});
+test("P15 compaction precedes ceiling, floor includes protected tombstone", async () => {
+  const n = await seed(40, 50000);
+  expect(h.compactNote(db, n.id, h.resolveHistoryPolicy({ max_bytes_per_note: 300000 })).versions_dropped).toBe(0);
+  expect(h.noteHistoryBytes(db, n.id)).toBeLessThan(300000);
+  // A random corpus cannot shrink below the floor's 20 whole bodies.
+  const q = await store.createNote(randomHex(50000));
+  for (let i = 0; i < 40; i++)
+    await store.updateNote(q.id, { content: randomHex(50000) });
+  await store.deleteNote(q.id);
+  const r = h.compactNote(db, q.id, h.resolveHistoryPolicy({ max_bytes_per_note: 65536 }));
+  expect(r.versions_dropped).toBe(21);
+  const remaining = await store.listNoteVersions(q.id);
+  expect(remaining).toHaveLength(20);
+  expect(remaining.filter(v => v.op === "delete")).toHaveLength(1);
+  expect(Math.min(...remaining.map(v => v.version_ix))).toBe(21);
+  expect(h.noteHistoryBytes(db, q.id)).toBeGreaterThan(65536);
+  for (const v of remaining)
+    expect((await store.getNoteVersion(q.id, v.version_ix))!.content).not.toBeNull();
+});
+test("P15 over-byte trigger works below minimum count and null disables dropping", async () => {
+  const n = await seed(5, 1999000);
+  expect(store.compactNote(n.id).blobs_deltified).toBeGreaterThan(0);
+  expect(h.noteHistoryBytes(db, n.id)).toBeLessThan(8388608);
+  const before = await store.countNoteVersions(n.id);
+  h.compactNote(db, n.id, h.resolveHistoryPolicy({ max_bytes_per_note: null }));
+  expect(await store.countNoteVersions(n.id)).toBe(before);
+});
+test("P15 attribution drops while indirect base remains on disk", async () => {
+  const n = await seed();
+  store.compactNote(n.id);
+  const base = db.prepare("SELECT delta_of FROM note_blobs WHERE encoding='fossil-delta' LIMIT 1").get() as any;
+  const before = h.noteHistoryBytes(db, n.id), count = blobs().length;
+  db.prepare("DELETE FROM note_versions WHERE note_id=? AND content_hash=?").run(n.id, base.delta_of);
+  h.gcBlobs(db);
+  expect(h.noteHistoryBytes(db, n.id)).toBeLessThan(before);
+  expect(blobs()).toHaveLength(count);
+});
+test("P17 creation time capture, restore marker and pre-v30 fallback", async () => {
+  const n = await seed(2);
+  await store.deleteNote(n.id);
+  expect((await store.listNoteVersions(n.id)).every(v => v.created_at === n.createdAt)).toBe(true);
+  expect((await store.restoreNoteVersion(n.id, 0, {})).createdAt).toBe(n.createdAt);
+  expect((await store.listNoteVersions(n.id))[0]!.created_at).toBe(n.createdAt);
+  await store.deleteNote(n.id);
+  const tomb = (await store.listNoteVersions(n.id))[0]!;
+  db.prepare("UPDATE note_versions SET created_at=NULL WHERE note_id=?").run(n.id);
+  expect((await store.restoreNoteVersion(n.id, 0, {})).createdAt).toBe(tomb.superseded_at);
+});
+test("P18/P19 counts, clamps and defaults", async () => {
+  const n = await seed(7);
+  expect(await store.countNoteVersions(n.id)).toBe(7);
+  expect(await store.countNoteVersions("absent")).toBe(0);
+  expect(h.resolveHistoryPolicy({ compact_ratio: 0, compact_run_length: 500, max_bytes_per_note: 10 })).toMatchObject({ compact_ratio: 1, compact_run_length: 100, max_bytes_per_note: 65536, compact_budget_ms: 250, compact_max_notes: 50 });
+  expect(h.resolveHistoryPolicy({ max_bytes_per_note: null }).max_bytes_per_note).toBeNull();
+});
+test("P20 oldest 116KB version reads p95 under 50ms", async () => {
+  const n = await seed(24, 116000);
+  store.compactNote(n.id);
+  const times: number[] = [];
+  for (let i = 0; i < 40; i++) {
+    const t = performance.now();
+    expect((await store.getNoteVersion(n.id, 0))!.content).toBe(n.content);
+    times.push(performance.now() - t);
+  }
+  times.sort((a, b) => a - b);
+  console.log("P20 read latency", { p50: times[20], p95: times[38], max: times[39] });
+  expect(times[38]!).toBeLessThan(50);
+});
+test("P23 corrupt chain cannot rewrite a healthy whole; vault continues", async () => {
+  const n = await seed(12), good = await seed(12, 20000, "good");
+  const rows = await store.listNoteVersions(n.id);
+  expect(codec).not.toBeNull();
+  const [r, d, w] = rows;
+  const content = (hash: string) => (db.prepare("SELECT content FROM note_blobs WHERE hash=?").get(hash) as any).content as string;
+  const dt = content(d!.content_hash!), wt = content(w!.content_hash!), rt = content(r!.content_hash!);
+  db.prepare("UPDATE note_blobs SET content=?,encoding='fossil-delta',delta_of=? WHERE hash=?").run(codec!.encodeDelta(wt, dt), w!.content_hash, d!.content_hash);
+  db.prepare("UPDATE note_blobs SET content=?,encoding='fossil-delta',delta_of=? WHERE hash=?").run(codec!.encodeDelta(dt, rt), d!.content_hash, r!.content_hash);
+  const before = blobs();
+  expect(() => store.compactNote(n.id)).toThrow("base_not_whole");
+  expect(blobs()).toEqual(before);
+  expect(store.compactHistory({ maxNotes: null, budgetMs: null })).toMatchObject({ notes_failed: 1, notes_compacted: 1 });
+  expect((await store.getNoteVersion(good.id, 0))!.content).toBe(good.content);
+});
+
+test("P10(i)/P21(f) explicit IDs and guard precedence cannot widen or stall a pass", async () => {
+  for (let i = 0; i < 3; i++) await seed(12, 20000, `guard${i}`);
+  const before = blobs();
+  expect(store.compactHistory({ noteId: "", budgetMs: null, maxNotes: null })).toMatchObject({ notes_scanned: 1, notes_compacted: 0 });
+  expect(blobs()).toEqual(before);
+  expect(store.compactHistory({ budgetMs: 0, maxNotes: 0 }).stopped_by).toBe("max_notes");
+  const clock = spyOn(performance, "now");
+  let tick = 0;
+  clock.mockImplementation(() => (tick += 10));
+  try {
+    expect(store.compactHistory({ budgetMs: 1, maxNotes: 1 })).toMatchObject({ notes_scanned: 1, notes_compacted: 1, stopped_by: "max_notes" });
+    expect(store.compactHistory({ budgetMs: 1, maxNotes: null })).toMatchObject({ notes_scanned: 1, notes_compacted: 1, stopped_by: "budget" });
+  } finally { clock.mockRestore(); }
+  const empty = new Database(":memory:");
+  try { expect(h.compactVault(empty, h.resolveHistoryPolicy(), { budgetMs: 0, maxNotes: 0 }).stopped_by).toBe("disabled"); }
+  finally { empty.close(); }
+});

package/core/src/delta.test.ts

@@ -0,0 +1,49 @@
+import { test, expect } from "bun:test";
+import { readFileSync } from "node:fs";
+const codec = await import("./delta.js").catch(() => null);
+function randomHex(size: number) {
+  const bytes = new Uint8Array(size / 2);
+  for (let i = 0; i < bytes.length; i += 65536)
+    crypto.getRandomValues(bytes.subarray(i, i + 65536));
+  return Buffer.from(bytes).toString("hex");
+}
+for (const [name, seed] of [["ASCII", "hello world"], ["CJK", "日本語"], ["emoji", "🐢 café naïve"], ["combining", "école résumé"], ["high Latin", "ÿþý"]]) {
+  test(`P1 ${name} mid-body roundtrip`, () => {
+    expect(codec).not.toBeNull();
+    const lines = Array.from({ length: 500 }, (_, i) => `${i}: ${seed}`);
+    const base = lines.join("\n");
+    lines[200] = "new 🐙 line";
+    lines.splice(300, 0, "inserted");
+    const target = lines.join("\n"), payload = codec!.encodeDelta(base, target);
+    expect(payload).toMatch(/^[A-Za-z0-9+/=]*$/);
+    expect(codec!.decodeDelta(base, payload)).toBe(target);
+  });
+}
+test("P1 large independent bodies exercise a large delta without spread", () => {
+  expect(codec).not.toBeNull();
+  const base = randomHex(2000000), target = randomHex(2000000);
+  const payload = codec!.encodeDelta(base, target);
+  expect(atob(payload).length).toBeGreaterThanOrEqual(1000000);
+  expect(codec!.decodeDelta(base, payload)).toBe(target);
+});
+test("P1 identity is small and corrupted checksum / copied base throws", () => {
+  expect(codec).not.toBeNull();
+  const base = "unique numbered line\n".repeat(500);
+  expect(codec!.encodeDelta(base, base).length).toBeLessThan(32);
+  const payload = codec!.encodeDelta(base, base + "tail");
+  const bytes = Buffer.from(payload, "base64");
+  // Alter a checksum digit, not a framing byte.
+  bytes[bytes.length - 2] = bytes[bytes.length - 2] === 48 ? 49 : 48;
+  expect(() => codec!.decodeDelta(base, bytes.toString("base64"))).toThrow("bad checksum");
+  expect(() => codec!.decodeDelta(base.replaceAll("u", "X"), payload)).toThrow("bad checksum");
+});
+test("P2 vendor provenance and removed string surface", () => {
+  expect(codec).not.toBeNull();
+  for (const key of ["createStringDelta", "applyStringDelta", "getStringDeltaTargetSize"])
+    expect(key in codec!).toBe(false);
+  const source = readFileSync(new URL("./vendor/fossil-delta.ts", import.meta.url), "utf8");
+  expect(source.startsWith("// @" + "ts-nocheck\n")).toBe(true);
+  expect(source).toContain("BSD 2-Clause");
+  expect(source).toContain("29d795837d08ff9305e145d20611e721e52aa29969c10c39c8f9d3d51be67b6c");
+  expect(source).toContain("sha512-rcvnd0xjV7KNkEbXhTCsjHhONvdami+WWhTYGf4ORkPk9ixkQDmVeII96F6wBD/6qa9zBjH15bOzSARKsQ/rKg==");
+});

package/core/src/delta.ts

@@ -0,0 +1,21 @@
+import { createDelta, applyDelta } from "./vendor/fossil-delta.js";
+/** Encode UTF-8 text as a base64 byte delta, without an argument-sized spread. */
+export function encodeDelta(base: string, target: string): string {
+  const bytes = createDelta(new TextEncoder().encode(base), new TextEncoder().encode(target));
+  return toBase64(bytes);
+}
+function toBase64(bytes: Uint8Array | number[]): string {
+  const chunks: string[] = [];
+  for (let start = 0; start < bytes.length; start += 8192) {
+    let chunk = "";
+    for (let i = start; i < Math.min(start + 8192, bytes.length); i++)
+      chunk += String.fromCharCode(bytes[i]!);
+    chunks.push(chunk);
+  }
+  return btoa(chunks.join(""));
+}
+/** Reconstruct exactly one delta; checksum verification remains enabled. */
+export function decodeDelta(base: string, payload: string): string {
+  const bytes = Uint8Array.from(atob(payload), c => c.charCodeAt(0));
+  return new TextDecoder().decode(new Uint8Array(applyDelta(new TextEncoder().encode(base), bytes)));
+}

package/core/src/doctor.ts

@@ -47,6 +47,7 @@
  * out-of-scope activity.
  */
 
+import { historyTablesPresent, deletedHistoryStats, historyStorageStats, topNotesByHistoryBytes } from "./history.js";
 import { Database } from "bun:sqlite";
 import { loadTagHierarchy, findHierarchyCycles } from "./tag-hierarchy.js";
 import { listIndexedFields } from "./indexed-fields.js";
@@ -58,7 +59,10 @@ export type DoctorFindingType =
   | "parent_names_cycle"
   | "mixed_type_indexed_field"
   | "orphaned_indexed_field_declarer"
-  | "dead_tag_metadata_reference";
+  | "dead_tag_metadata_reference"
+  | "deleted_note_history"
+  | "history_storage"
+  | "history_delta_orphan";
 
 export type DoctorSeverity = "error" | "warning" | "info";
 
@@ -126,6 +130,9 @@ export function runDoctorScan(db: Database, opts?: DoctorScanOpts): DoctorReport
     ...scanMixedTypeIndexedFields(db, allowedTags),
     ...scanOrphanedIndexedFieldDeclarers(db, allowedTags),
     ...scanDeadTagMetadataReferences(db, allowedTags),
+    ...(allowedTags === null ? scanDeletedNoteHistory(db) : []),
+    ...(allowedTags === null ? scanHistoryStorage(db) : []),
+    ...(allowedTags === null ? scanDeltaOrphans(db) : []),
   ];
 
   const errors = findings.filter((f) => f.severity === "error").length;
@@ -380,3 +387,36 @@ function scanDeadTagMetadataReferences(db: Database, allowedTags: Set<string> |
   }
   return findings;
 }
+
+/** Deleted rows have no tags to authorize against; callers omit this for scoped sessions. */
+function scanDeletedNoteHistory(db: Database): DoctorFinding[] {
+  if (!historyTablesPresent(db)) return [];
+  const stats = deletedHistoryStats(db);
+  if (stats.versions === 0) return [];
+  return [{ type: "deleted_note_history", severity: "info",
+    subject: `${stats.notes} deleted note(s)`,
+    detail: `${stats.versions} version row(s) retained for notes that no longer exist, holding ~${stats.bytes} bytes of blob content. Blobs shared with a live note's history are counted here as well, so this is an upper bound, not an exact figure.`
+      + (stats.overflow_tombstones > 0 ? ` ${stats.overflow_tombstones} of these are overflow tombstone(s): the note exceeded the 2 MB version ceiling, so its deletion, size and metadata were recorded but its content was not and cannot be restored.` : ``),
+    remedy: "Set `history.deleted_retention_days` in the vault's vault.yaml to sweep these automatically (null — the default — keeps them until an explicit erase), or erase one note's history permanently with DELETE /api/notes/<id>/versions.",
+  }];
+}
+
+function scanHistoryStorage(db: Database): DoctorFinding[] {
+  if (!historyTablesPresent(db)) return [];
+  const s = historyStorageStats(db);
+  if (s.whole_blobs + s.delta_blobs === 0) return [];
+  const top = topNotesByHistoryBytes(db, 5);
+  return [{ type: "history_storage", severity: "info",
+    subject: `${s.whole_blobs + s.delta_blobs} history blob(s)`,
+    detail: `${s.whole_bytes} byte(s) stored whole across ${s.whole_blobs} blob(s) and ${s.delta_bytes} byte(s) stored as fossil deltas across ${s.delta_blobs} blob(s). Largest histories by stored bytes: ${top.map(t => `${t.note_id} (${t.bytes} bytes, ${t.versions} versions)`).join(", ")}.`,
+    remedy: "Run POST /api/history/compact (vault:admin) to compact now, or set history.max_bytes_per_note in the vault's vault.yaml to bound per-note history. Turning history.compact_enabled off also stops max_bytes_per_note being enforced." }];
+}
+function scanDeltaOrphans(db: Database): DoctorFinding[] {
+  if (!historyTablesPresent(db)) return [];
+  const s = historyStorageStats(db);
+  if (s.orphan_deltas + s.unknown_encoding_blobs === 0) return [];
+  return [{ type: "history_delta_orphan", severity: "error",
+    subject: `${s.orphan_deltas + s.unknown_encoding_blobs} unrecoverable history blob(s)`,
+    detail: `${s.orphan_deltas} blob(s) are stored as fossil deltas whose base blob is missing or is itself a delta, and ${s.unknown_encoding_blobs} carry an encoding this version does not know how to read, so the versions referencing them cannot be reconstructed. Reading one answers 409 history_unrecoverable; listing versions still works.`,
+    remedy: "Erase the affected note's history with DELETE /api/notes/<id>/versions, or restore the vault database from backup. This is a corruption finding, not a retention setting." }];
+}

package/core/src/history-capture.test.ts

@@ -0,0 +1,244 @@
+import { it, expect, beforeEach, afterEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { mkdtempSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { BunSqliteStore } from "./store.js";
+import {
+  exportVaultToDir,
+  FsImportSource,
+  importVault,
+} from "./portable-md.js";
+let db: Database, store: BunSqliteStore;
+beforeEach(() => {
+  db = new Database(":memory:");
+  store = new BunSqliteStore(db);
+});
+afterEach(() => db.close());
+const count = (table: "note_versions" | "note_blobs") =>
+  (db.prepare(`SELECT COUNT(*) AS n FROM ${table}`).get() as { n: number }).n;
+for (const leg of ["path", "transition"] as const)
+  it(`P1 rollback after ${leg} rejection leaves no phantom history`, async () => {
+    const n = await store.createNote("original", {
+      path: "a",
+      metadata: { status: "a" },
+    });
+    await store.createNote("occupied", { path: "b" });
+    const before = count("note_blobs");
+    if (leg === "path")
+      await expect(
+        store.updateNote(n.id, { content: "bad", path: "b" }),
+      ).rejects.toMatchObject({ code: "PATH_CONFLICT" });
+    else
+      await expect(
+        store.updateNote(n.id, {
+          content: "bad",
+          state_transition: { field: "status", from: "wrong", to: "b" },
+        }),
+      ).rejects.toMatchObject({ code: "TRANSITION_CONFLICT" });
+    expect(count("note_versions")).toBe(0);
+    expect(count("note_blobs")).toBe(before);
+    expect((await store.getNote(n.id))!.content).toBe("original");
+  });
+it("P4 sequential append/prepend preserve reconstructable prior bodies", async () => {
+  const content = "---\ntitle: T\n---\nbody\n";
+  const n = await store.createNote(content);
+  await store.updateNote(n.id, { append: "a\n" });
+  await store.updateNote(n.id, { prepend: "p\n" });
+  const rows = await store.listNoteVersions(n.id);
+  expect(rows).toHaveLength(2);
+  expect(rows.map((v) => v.version_ix)).toEqual([1, 0]);
+  expect(rows.map((v) => v.op)).toEqual(["prepend", "append"]);
+  expect(rows[0]!.content_hash).not.toBe(rows[1]!.content_hash);
+  expect((await store.getNoteVersion(n.id, 0))!.content + "a\n").toBe(
+    (await store.getNoteVersion(n.id, 1))!.content!,
+  );
+  expect((await store.getNote(n.id))!.content).toBe(
+    "---\ntitle: T\n---\np\nbody\na\n",
+  );
+  // This pin makes no concurrency claim: synchronous transactions serialize these calls.
+});
+it("P5 live restore captures the prior body and preserves the source version", async () => {
+  const n = await store.createNote("0", { path: "original" });
+  for (let i = 1; i <= 5; i++)
+    await store.updateNote(n.id, { content: String(i) });
+  const source = await store.getNoteVersion(n.id, 1),
+    before = await store.getNote(n.id);
+  const r = await store.restoreNoteVersion(n.id, 1, {
+    if_updated_at: before!.updatedAt!,
+    actor: "restorer",
+    via: "api",
+  });
+  expect(r.content).toBe(source!.content!);
+  expect(r.updatedAt! > before!.updatedAt!).toBe(true);
+  expect(r.lastUpdatedBy).toBe("restorer");
+  const rows = await store.listNoteVersions(n.id);
+  expect(rows).toHaveLength(6);
+  expect(rows[0]!.op).toBe("restore");
+  expect((await store.getNoteVersion(n.id, rows[0]!.version_ix))!.content).toBe(
+    "5",
+  );
+  expect(await store.getNoteVersion(n.id, 1)).toEqual(source);
+});
+it("P5 restore reads its source before a one-version prune", async () => {
+  store = new BunSqliteStore(db, {
+    history: { min_versions: 1, max_versions: 1 },
+  });
+  const n = await store.createNote("one");
+  await store.updateNote(n.id, { content: "two" });
+  expect((await store.restoreNoteVersion(n.id, 0, {})).content).toBe("one");
+  expect(await store.listNoteVersions(n.id)).toHaveLength(1);
+});
+it("P8a tag rename captures only rewritten notes", async () => {
+  await store.upsertTagRecord("old", {});
+  const a = await store.createNote("#old a"),
+    b = await store.createNote("#old b"),
+    c = await store.createNote("untouched");
+  await store.renameTag("old", "new");
+  for (const n of [a, b])
+    expect(await store.getNoteVersion(n.id, 0)).toMatchObject({
+      op: "tag-rename",
+      content: n.content,
+    });
+  expect(await store.listNoteVersions(c.id)).toHaveLength(0);
+});
+it("P8b path rename captures the source brackets and renamed note", async () => {
+  const b = await store.createNote("B", { path: "B" }),
+    a = await store.createNote("see [[B]]", { path: "A" });
+  await store.updateNote(b.id, { path: "C", actor: "renamer", via: "api" });
+  expect(await store.getNoteVersion(a.id, 0)).toMatchObject({
+    content: "see [[B]]",
+    op: "cascade-rename",
+    actor: "renamer",
+    via: "api",
+  });
+  expect(await store.getNoteVersion(b.id, 0)).toMatchObject({
+    path: "B",
+    op: "update",
+  });
+});
+it("P9 skipUpdatedAt metadata writes still capture with NULL attribution", async () => {
+  const n = await store.createNote("body");
+  const r = await store.updateNote(n.id, {
+    metadata: { x: 1 },
+    skipUpdatedAt: true,
+  });
+  expect(r.updatedAt).toBe(n.updatedAt);
+  expect(await store.listNoteVersions(n.id)).toHaveLength(1);
+  expect(await store.getNoteVersion(n.id, 0)).toMatchObject({
+    actor: null,
+    via: null,
+    op: "update",
+    metadata: {},
+  });
+});
+it("P10 deletion captures final state; blow-away opt-out does not", async () => {
+  const a = await store.createNote("final"),
+    b = await store.createNote("skip");
+  await store.deleteNote(a.id, { actor: "a", via: "v" });
+  await store.deleteNote(b.id, { captureHistory: false });
+  expect(await store.getNote(a.id)).toBeNull();
+  expect(await store.getNoteVersion(a.id, 0)).toMatchObject({
+    content: "final",
+    op: "delete",
+    actor: "a",
+    via: "v",
+  });
+  expect(await store.listNoteVersions(b.id)).toHaveLength(0);
+});
+it("P11b skipUpdatedAt transition reaches the mutating-key guard", async () => {
+  const n = await store.createNote("body", { metadata: { status: "a" } });
+  const r = await store.updateNote(n.id, {
+    state_transition: { field: "status", from: "a", to: "b" },
+    skipUpdatedAt: true,
+  });
+  expect(r.updatedAt).toBe(n.updatedAt);
+  expect(await store.listNoteVersions(n.id)).toHaveLength(1);
+  expect(await store.getNoteVersion(n.id, 0)).toMatchObject({
+    metadata: { status: "a" },
+  });
+});
+it("P12 blow-away round trip reattaches the existing version chains", async () => {
+  const outDir = mkdtempSync(join(tmpdir(), "history-import-"));
+  try {
+    const notes = [];
+    for (let i = 0; i < 3; i++) {
+      const n = await store.createNote("a", { path: `p${i}` });
+      await store.updateNote(n.id, { content: "b" });
+      await store.updateNote(n.id, { content: "c" });
+      notes.push(n);
+    }
+    const before = new Map(
+      await Promise.all(
+        notes.map(
+          async (n) => [n.id, await store.listNoteVersions(n.id)] as const,
+        ),
+      ),
+    );
+    await exportVaultToDir(store, { outDir, vaultName: "history" });
+    const stats = await importVault(
+      store,
+      new FsImportSource({ inDir: outDir }),
+      { blowAway: true },
+    );
+    expect(stats.notes_wiped).toBe(3);
+    expect(stats.notes_created).toBe(3);
+    expect(stats.notes_updated).toBe(0);
+    expect(
+      (
+        db
+          .prepare("SELECT COUNT(*) AS n FROM note_versions WHERE op='delete'")
+          .get() as { n: number }
+      ).n,
+    ).toBe(0);
+    // Replay recreates these IDs, with zero update-branch upserts, so MAX advances by zero.
+    for (const n of notes)
+      expect(await store.listNoteVersions(n.id)).toEqual(before.get(n.id)!);
+    for (const n of notes) await store.deleteNote(n.id);
+    expect(
+      (
+        db
+          .prepare("SELECT COUNT(*) AS n FROM note_versions WHERE op='delete'")
+          .get() as { n: number }
+      ).n,
+    ).toBe(3);
+  } finally {
+    rmSync(outDir, { recursive: true, force: true });
+  }
+});
+it("P20 re-create uses tombstone path/time, selected metadata, no tags", async () => {
+  const n = await store.createNote("one", {
+    path: "p",
+    tags: ["work"],
+    metadata: { k: 1 },
+  });
+  await store.updateNote(n.id, { content: "two", metadata: { k: 2 } });
+  await store.deleteNote(n.id, { actor: "a" });
+  const tomb = (await store.listNoteVersions(n.id))[0]!;
+  const r = await store.restoreNoteVersion(n.id, 0, {});
+  expect(r).toMatchObject({
+    id: n.id,
+    path: "p",
+    content: "one",
+    metadata: { k: 1 },
+    tags: [],
+    createdAt: n.createdAt,
+  });
+  const rows = await store.listNoteVersions(n.id);
+  expect(rows[0]).toMatchObject({
+    op: "restore",
+    content_hash: tomb.content_hash,
+  });
+  expect(rows.some((v) => v.op === "delete")).toBe(true);
+});
+it("P20d path collision rolls back re-creation and its marker", async () => {
+  const n = await store.createNote("one", { path: "p" });
+  await store.deleteNote(n.id);
+  await store.createNote("other", { path: "p" });
+  const before = await store.listNoteVersions(n.id);
+  await expect(store.restoreNoteVersion(n.id, 0, {})).rejects.toMatchObject({
+    code: "PATH_CONFLICT",
+  });
+  expect(await store.getNote(n.id)).toBeNull();
+  expect(await store.listNoteVersions(n.id)).toEqual(before);
+});