@openparachute/vault 0.7.9-rc.8 → 0.7.9-rc.9

package/core/src/compact-state-rebuild.test.ts

@@ -0,0 +1,46 @@
+import { test, expect } from "bun:test";
+import { Database } from "bun:sqlite";
+import { BunSqliteStore } from "./store.js";
+import { initSchema } from "./schema.js";
+import { runDoctorScan } from "./doctor.js";
+
+test("no ledger rows are not evidence of a downgrade", async () => {
+  const db = new Database(":memory:");
+  try {
+    const store = new BunSqliteStore(db);
+    const note = await store.createNote("before");
+    await store.updateNote(note.id, { content: "after" });
+    db.exec("DELETE FROM schema_version; UPDATE history_compact_state SET refused=1");
+    initSchema(db);
+    expect(db.prepare("SELECT refused FROM history_compact_state").get()).toEqual({ refused: 1 });
+    db.exec("DROP TABLE history_compact_state; DELETE FROM schema_version");
+    initSchema(db);
+    expect(db.prepare("SELECT versions,refused FROM history_compact_state").get()).toEqual({ versions: 1, refused: 0 });
+  } finally { db.close(); }
+});
+
+for (const tied of [false, true]) test(`a downgrade ledger entry rebuilds existing stale hints (tied=${tied})`, async () => {
+  const db = new Database(":memory:");
+  try {
+    const store = new BunSqliteStore(db, { history: { compact_min_versions: 2, compact_ratio: 1 } });
+    const note = await store.createNote("old".repeat(1000));
+    await store.updateNote(note.id, { append: "first" });
+    const stale = db.prepare("SELECT * FROM history_compact_state WHERE note_id=?").get(note.id) as any;
+    await store.updateNote(note.id, { append: "second" });
+    await store.updateNote(note.id, { content: "x" });
+    // Reproduce the older writer: history/live rows advance but hints do not,
+    // and that binary records its own version on open.
+    db.prepare("UPDATE history_compact_state SET versions=?,stored=?,live=?,refused=1 WHERE note_id=?").run(stale.versions, stale.stored, stale.live, note.id);
+    db.prepare("UPDATE schema_version SET applied_at='2026-01-01T00:00:00.000Z'").run();
+    db.prepare("INSERT OR REPLACE INTO schema_version VALUES(31,?)").run(tied ? "2026-01-01T00:00:00.000Z" : "2026-01-02T00:00:00.000Z");
+    expect(runDoctorScan(db).findings.some(f=>f.type==="history_compact_state_drift")).toBe(true);
+    const rows = db.prepare("SELECT * FROM note_versions").all();
+    initSchema(db);
+    expect(runDoctorScan(db).findings.some(f=>f.type==="history_compact_state_drift")).toBe(false);
+    expect(db.prepare("SELECT * FROM note_versions").all()).toEqual(rows);
+    expect(store.compactHistory({ budgetMs: null, maxNotes: null }).notes_scanned).toBe(1);
+    db.prepare("UPDATE history_compact_state SET refused=1").run();
+    initSchema(db);
+    expect(db.prepare("SELECT refused FROM history_compact_state WHERE note_id=?").get(note.id)).toEqual({ refused: 1 });
+  } finally { db.close(); }
+});

package/core/src/compact-state.test.ts

@@ -0,0 +1,129 @@
+import { test, expect, beforeEach, afterEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { BunSqliteStore } from "./store.js";
+import { initSchema } from "./schema.js";
+import { runDoctorScan } from "./doctor.js";
+import { pruneVersions, resolveHistoryPolicy, sweepDeletedHistory } from "./history.js";
+import { readCompactState } from "./history-compact-state.js";
+import { applyImportedNote, beginImportRun, importTargetDigest } from "./history-import.js";
+let db: Database, store: BunSqliteStore;
+beforeEach(() => { db = new Database(":memory:"); store = new BunSqliteStore(db, { history: { compact_min_versions: 2, compact_ratio: 1 } }); });
+afterEach(() => db.close());
+const state = (id: string) => db.query("SELECT versions,stored,live,refused FROM history_compact_state WHERE note_id=?").get(id) as { versions: number; stored: number; live: number; refused: number } | null;
+test("live bytes refresh after mutation, empty histories are excluded and nonempty edits re-arm", async () => {
+  const n = await store.createNote("large".repeat(1000));
+  await store.updateNote(n.id, { append: "changed" });
+  await store.updateNote(n.id, { content: "" });
+  expect(state(n.id)?.live).toBe(0);
+  expect(store.compactHistory({ budgetMs: null, maxNotes: null }).notes_scanned).toBe(0);
+  await store.updateNote(n.id, { content: "x" });
+  expect(state(n.id)?.live).toBe(1);
+  expect(store.compactHistory({ budgetMs: null, maxNotes: null }).notes_scanned).toBe(1);
+});
+test("incompressible refusal disappears on pass two and any metadata capture re-arms", async () => {
+  const n = await store.createNote("a");
+  await store.updateNote(n.id, { content: "b" });
+  await store.updateNote(n.id, { content: "c" });
+  expect(store.compactHistory({ budgetMs: null, maxNotes: null }).notes_scanned).toBe(1);
+  expect(state(n.id)?.refused).toBe(1);
+  expect(store.compactHistory({ budgetMs: null, maxNotes: null }).notes_scanned).toBe(0);
+  await store.updateNote(n.id, { metadata: { status: 1 } });
+  expect(state(n.id)?.refused).toBe(0);
+  expect(store.compactHistory({ budgetMs: null, maxNotes: null }).notes_scanned).toBe(1);
+});
+test("shared blob rewrites refresh other notes without re-arming refusal", async () => {
+  const body = "shared history\n".repeat(1000);
+  const a = await store.createNote(body), b = await store.createNote(body);
+  await store.updateNote(a.id, { append: "a" });
+  await store.updateNote(a.id, { content: "small" });
+  await store.updateNote(b.id, { content: "small" });
+  db.query("UPDATE history_compact_state SET refused=1 WHERE note_id=?").run(b.id);
+  const before = state(b.id)!;
+  expect(store.compactNote(a.id).blobs_deltified).toBeGreaterThan(0);
+  expect(state(b.id)!.stored).toBeLessThan(before.stored);
+  expect(state(b.id)!.refused).toBe(1);
+});
+test("v31 migration backfills deleted and live history once and preserves bodies", async () => {
+  const n = await store.createNote("old");
+  await store.updateNote(n.id, { content: "new" });
+  await store.deleteNote(n.id);
+  const before = db.query("SELECT * FROM note_versions").all();
+  db.exec("DROP TABLE history_compact_state; UPDATE schema_version SET version=31");
+  initSchema(db);
+  expect(state(n.id)).toEqual({ versions: 2, stored: 6, live: 3, refused: 0 });
+  expect(db.query("PRAGMA foreign_key_list(history_compact_state)").all()).toEqual([]);
+  expect(db.query("SELECT * FROM note_versions").all()).toEqual(before);
+  expect((await store.getNoteVersion(n.id, 0))?.content).toBe("old");
+  db.query("UPDATE history_compact_state SET refused=1").run();
+  initSchema(db);
+  expect(state(n.id)?.refused).toBe(1);
+  await store.eraseNoteHistory(n.id);
+  expect(state(n.id)).toBeNull();
+  expect(db.query("PRAGMA foreign_key_check").all()).toEqual([]);
+});
+test("doctor reports bounded hint drift without repairing history", async () => {
+  const n = await store.createNote("before");
+  await store.updateNote(n.id, { content: "after" });
+  db.query("UPDATE history_compact_state SET stored=999 WHERE note_id=?").run(n.id);
+  const result = runDoctorScan(db);
+  expect(result.findings.some(f => f.type === ("history_compact_state_drift" as any) && f.severity === "warning")).toBe(true);
+  expect(state(n.id)?.stored).toBe(999);
+  expect(runDoctorScan(db, { allowedTags: ["restricted"] }).findings.some(f => f.type === "history_compact_state_drift")).toBe(false);
+});
+test("prune, imported observations, deleted compaction and sweep maintain exact counters", async () => {
+  const n = await store.createNote("body".repeat(1000));
+  const exact = () => {
+    const actual = readCompactState(db, n.id)!;
+    expect(state(n.id)).toMatchObject({ versions: actual.versions, stored: actual.stored, live: actual.live });
+  };
+  for (let i=0;i<4;i++) { await store.updateNote(n.id, { append: String(i) }); exact(); }
+  const policy = resolveHistoryPolicy({ min_versions: 1, max_versions: 2, compact_min_versions: 2, compact_ratio: 1 });
+  db.transaction(() => pruneVersions(db, n.id, policy))(); exact();
+  const run = { run_id: "state-test", source_fingerprint: "source", tip: "tip", options_digest: "options" };
+  beginImportRun(db, run);
+  applyImportedNote(db, { run, noteId: n.id, targetDigest: importTargetDigest(db, n.id), policy: resolveHistoryPolicy({ enabled: false }), now: Date.now(), observations: [{ content: "import", path: null, metadata: {}, extension: "md", created_at: null, observed_at: new Date().toISOString(), commit: "commit", blob: "blob" }] });
+  exact(); expect(state(n.id)?.refused).toBe(0);
+  await store.deleteNote(n.id); exact();
+  expect(store.compactNote(n.id).blobs_deltified).toBeGreaterThan(0); exact();
+  const remaining = await store.listNoteVersions(n.id);
+  for (const v of remaining) expect((await store.getNoteVersion(n.id, v.version_ix))?.content).not.toBeNull();
+  expect(db.query("SELECT 1 FROM note_blobs b JOIN note_blobs base ON base.hash=b.delta_of WHERE base.encoding IS NOT NULL").all()).toEqual([]);
+  expect(db.query("PRAGMA foreign_key_check").all()).toEqual([]);
+  sweepDeletedHistory(db, resolveHistoryPolicy({ deleted_retention_days: 1 }), new Date(Date.now()+3*86400000));
+  expect(state(n.id)).toBeNull();
+});
+test("explicit-ID recreation refreshes live bytes and bounded remaining is a total", async () => {
+  for(let i=0;i<10;i++) {
+    const n = await store.createNote("abc", { id: `candidate-${i}` });
+    await store.updateNote(n.id, { content: "def" });
+    await store.updateNote(n.id, { content: "x" });
+  }
+  const first = store.compactHistory({ maxNotes: 1, budgetMs: null });
+  expect(first.remaining_candidates).toBe(9);
+  await store.deleteNote("candidate-0");
+  await store.createNoteRaw("", { id: "candidate-0" });
+  expect(state("candidate-0")?.live).toBe(0);
+});
+test("failed enclosing write rolls back history and scheduling state together", async () => {
+  const n = await store.createNote("before");
+  await store.updateNote(n.id, { content: "after" });
+  const before = state(n.id);
+  db.exec("CREATE TRIGGER reject_hint BEFORE UPDATE ON history_compact_state BEGIN SELECT RAISE(ABORT,'injected refresh failure'); END");
+  await expect(store.updateNote(n.id, { content: "must roll back" })).rejects.toThrow("injected refresh failure");
+  expect((await store.getNote(n.id))?.content).toBe("after");
+  expect(state(n.id)).toEqual(before);
+  expect(await store.countNoteVersions(n.id)).toBe(1);
+});
+test("empty live content still obeys the history byte ceiling", async () => {
+  store = new BunSqliteStore(db, { history: { min_versions: 1, max_bytes_per_note: 65536, compact_min_versions: 2 } });
+  const body = () => Buffer.from(crypto.getRandomValues(new Uint8Array(15000))).toString("hex");
+  const n = await store.createNote(body());
+  for(let i=0;i<5;i++) await store.updateNote(n.id, { content: body() });
+  await store.updateNote(n.id, { content: "" });
+  expect(state(n.id)?.stored).toBe(180000);
+  const pass = store.compactHistory({ budgetMs: null, maxNotes: null });
+  expect(pass.notes_scanned).toBe(1);
+  expect(pass.versions_dropped).toBe(4);
+  expect(state(n.id)).toMatchObject({ stored: 60000, live: 0, refused: 0 });
+  expect(store.compactHistory({ budgetMs: null, maxNotes: null }).notes_scanned).toBe(0);
+});

package/core/src/compact.test.ts

@@ -74,7 +74,7 @@ test("P6 triggers and off switch leave blobs unchanged; writes never compact", a
     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);
+    expect(emptyStore.compactHistory({ budgetMs: null, maxNotes: null }).notes_scanned).toBe(0);
   } finally { emptyDb.close(); }
 });
 test("P7 third encode failure rolls back all changes", async () => {
@@ -115,7 +115,7 @@ test("P8 bounded passes resume and converge; unbounded visits all", async () =>
   expect(all.stopped_by).toBe("complete");
   expect(all.remaining_candidates).toBe(0);
 });
-test("P16/P8 incompressible candidates are refused on every pass", async () => {
+test("P16/P8 explicit retries remain safe; automatic passes skip refused candidates", async () => {
   const bodies = Array.from({ length: 5 }, () => randomHex(20480));
   expect(codec).not.toBeNull();
   expect(codec!.encodeDelta(bodies[1]!, bodies[0]!).length).toBeGreaterThanOrEqual(20480 * .9);
@@ -129,7 +129,7 @@ test("P16/P8 incompressible candidates are refused on every pass", async () => {
     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" });
+    expect(h.compactVault(db, p, { budgetMs: null, maxNotes: null })).toMatchObject({ notes_scanned: 0, stopped_by: "complete" });
   }
   const twin = await seed();
   expect(store.compactNote(twin.id)).toMatchObject({ blobs_skipped_too_large: 0 });

package/core/src/doctor.ts

@@ -48,11 +48,67 @@
  */
 
 import { historyTablesPresent, deletedHistoryStats, historyStorageStats, topNotesByHistoryBytes } from "./history.js";
+import { readCompactState, type CompactState } from "./history-compact-state.js";
 import { Database } from "bun:sqlite";
 import { loadTagHierarchy, findHierarchyCycles } from "./tag-hierarchy.js";
 import { listIndexedFields } from "./indexed-fields.js";
 import { pruneOrphanedIndexedFields } from "./indexed-fields.js";
 import { loadSchemaConfig } from "./schema-defaults.js";
+import { readBlobContent, hashContent, HistoryDeltaOrphanError } from "./history.js";
+
+function scanCompactStateDrift(db: Database): DoctorFinding[] {
+  if (!db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='history_compact_state'").get()) return [];
+  const sample = db.prepare("SELECT note_id,versions,stored,live FROM history_compact_state ORDER BY stored DESC LIMIT 200").all() as CompactState[];
+  const drift = sample.filter(row => {
+    const actual = readCompactState(db, row.note_id);
+    return !actual || actual.versions !== row.versions || actual.stored !== row.stored || actual.live !== row.live;
+  }).length;
+  return drift ? [{ type: "history_compact_state_drift", severity: "warning", subject: "history compaction scheduling hints",
+    detail: `${drift} of ${sample.length} sampled hint rows differ from history. Sample is bounded to the 200 largest hints; this is not a full audit.`,
+    remedy: "Investigate missed history-write refreshes. Self-hosted: history rebuild-state --vault <name>. Cloud: deploy a core-pin migration that rebuilds hints; no operator repair API. This scan does not repair them." }] : [];
+}
+
+export interface HistoryAuditPage {
+  checked: number;
+  corrupt: number;
+  examples: string[];
+  complete: boolean;
+  next_after: string | null;
+}
+
+/** Read-only keyset page. Budgets apply between blobs, not inside one decode.
+ * A sequence of pages is not a snapshot: use a consistent backup for a complete audit.
+ */
+export function auditHistoryBlobs(db: Database, after = "", maxBlobs = 100, budgetMs = 250): HistoryAuditPage {
+  if (after !== "" && !/^[a-f0-9]{64}$/.test(after)) throw new Error("history_after must be a SHA-256 hash");
+  if (!Number.isInteger(maxBlobs) || maxBlobs < 1 || maxBlobs > 500) throw new Error("history_max_blobs must be an integer from 1 to 500");
+  if (!Number.isInteger(budgetMs) || budgetMs < 1 || budgetMs > 1000) throw new Error("history_budget_ms must be an integer from 1 to 1000");
+  const page: HistoryAuditPage = { checked: 0, corrupt: 0, examples: [], complete: true, next_after: null };
+  if (!historyTablesPresent(db)) return page;
+  const start = performance.now();
+  const rows = db.prepare("SELECT hash FROM note_blobs WHERE hash > ? ORDER BY hash LIMIT ?").all(after, maxBlobs + 1) as { hash: string }[];
+  let cursor = after;
+  for (const row of rows) {
+    if (page.checked >= maxBlobs || (page.checked > 0 && performance.now() - start >= budgetMs)) {
+      page.complete = false;
+      page.next_after = cursor;
+      break;
+    }
+    let damaged = false;
+    try {
+      const body = readBlobContent(db, row.hash);
+      damaged = body === null || hashContent(body) !== row.hash;
+    } catch (error) {
+      // Operational database failures must abort, not masquerade as corruption.
+      if (!(error instanceof HistoryDeltaOrphanError)) throw error;
+      damaged = true;
+    }
+    page.checked++;
+    cursor = row.hash;
+    if (damaged) { page.corrupt++; if (page.examples.length < 5) page.examples.push(row.hash); }
+  }
+  return page;
+}
 
 export type DoctorFindingType =
   | "dangling_parent_name"
@@ -62,7 +118,9 @@ export type DoctorFindingType =
   | "dead_tag_metadata_reference"
   | "deleted_note_history"
   | "history_storage"
-  | "history_delta_orphan";
+  | "history_delta_orphan"
+  | "history_content_audit"
+  | "history_compact_state_drift";
 
 export type DoctorSeverity = "error" | "warning" | "info";
 
@@ -86,6 +144,7 @@ export interface DoctorReport {
   findings: DoctorFinding[];
   summary: string;
   scanned_at: string;
+  history_audit?: HistoryAuditPage;
 }
 
 export interface DoctorScanOpts {
@@ -95,6 +154,10 @@ export interface DoctorScanOpts {
    * each finding type is scoped.
    */
   allowedTags?: Set<string> | null;
+  deep?: boolean;
+  history_after?: string;
+  history_max_blobs?: number;
+  history_budget_ms?: number;
 }
 
 /** Cap on exemplar note IDs embedded in a finding's `detail` (vault#552 — keep report bodies bounded). */
@@ -124,6 +187,7 @@ function makeNoteInScope(db: Database, allowedTags: Set<string> | null): (id: st
 
 export function runDoctorScan(db: Database, opts?: DoctorScanOpts): DoctorReport {
   const allowedTags = opts?.allowedTags ?? null;
+  if (opts?.deep && allowedTags !== null) throw new Error("deep history audit requires an unrestricted session");
   const findings: DoctorFinding[] = [
     ...scanDanglingParentNames(db, allowedTags),
     ...scanParentNamesCycles(db, allowedTags),
@@ -133,8 +197,15 @@ export function runDoctorScan(db: Database, opts?: DoctorScanOpts): DoctorReport
     ...(allowedTags === null ? scanDeletedNoteHistory(db) : []),
     ...(allowedTags === null ? scanHistoryStorage(db) : []),
     ...(allowedTags === null ? scanDeltaOrphans(db) : []),
+    ...(allowedTags === null ? scanCompactStateDrift(db) : []),
   ];
 
+  const audit = opts?.deep ? auditHistoryBlobs(db, opts.history_after, opts.history_max_blobs, opts.history_budget_ms) : undefined;
+  if (audit) findings.push({ type: "history_content_audit", severity: audit.corrupt ? "error" : audit.complete ? "info" : "warning",
+    subject: "history content audit page",
+    detail: `Checked ${audit.checked} blob(s); ${audit.corrupt} corrupt. ${audit.complete ? "End of scan reached." : "Incomplete: continue with next_after."} Examples: ${audit.examples.join(", ") || "none"}.`,
+    remedy: "Continue incomplete scans with history_after=next_after. For snapshot-level assurance, audit a consistent backup. Preserve backups and investigate corruption; this audit never repairs or erases history." });
+
   const errors = findings.filter((f) => f.severity === "error").length;
   const warnings = findings.filter((f) => f.severity === "warning").length;
   const infos = findings.filter((f) => f.severity === "info").length;
@@ -143,7 +214,8 @@ export function runDoctorScan(db: Database, opts?: DoctorScanOpts): DoctorReport
       ? "clean — no integrity findings"
       : `${findings.length} finding(s): ${errors} error(s), ${warnings} warning(s), ${infos} info(s)`;
 
-  return { findings, summary, scanned_at: new Date().toISOString() };
+  return { findings, summary, scanned_at: new Date().toISOString(),
+    ...(audit ? { history_audit: audit } : {}) };
 }
 
 // ---------------------------------------------------------------------------

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

@@ -0,0 +1,51 @@
+import { test, expect } from "bun:test";
+import { Database } from "bun:sqlite";
+import { SqliteStore } from "./store.js";
+import { auditHistoryBlobs, runDoctorScan } from "./doctor.js";
+import { hashContent } from "./history.js";
+import { encodeDelta } from "./delta.js";
+
+test("deep audit pages whole/delta blobs, detects content damage without writes", () => {
+  const db = new Database(":memory:"); new SqliteStore(db);
+  try {
+    const insert = db.prepare("INSERT INTO note_blobs(hash,content,byte_size,encoding,delta_of) VALUES(?,?,?,?,?)");
+    const base = "base text ".repeat(100), changed = base + "new tail";
+    const a = hashContent(base), b = hashContent(changed), c = hashContent("original");
+    insert.run(a, base, base.length, null, null);
+    const delta = encodeDelta(base, changed);
+    insert.run(b, delta, delta.length, "fossil-delta", a);
+    insert.run(c, "tampered", 8, null, null);
+    const before = db.prepare("SELECT * FROM note_blobs ORDER BY hash").all();
+    let after = "", checked = 0, corrupt = 0;
+    do {
+      const p = auditHistoryBlobs(db, after, 1);
+      checked += p.checked; corrupt += p.corrupt;
+      if (p.complete) { expect(p.next_after).toBeNull(); break; }
+      expect(p.next_after! > after).toBe(true); after = p.next_after!;
+    } while (true);
+    expect(checked).toBe(3); expect(corrupt).toBe(1);
+    const report = runDoctorScan(db, { deep: true });
+    expect(report.history_audit?.examples).toEqual([c]);
+    expect(report.findings.find(f => f.type === "history_content_audit")?.severity).toBe("error");
+    expect(db.prepare("SELECT * FROM note_blobs ORDER BY hash").all()).toEqual(before);
+    db.prepare("UPDATE note_blobs SET content='invalid delta' WHERE hash=?").run(b);
+    expect(auditHistoryBlobs(db).corrupt).toBe(2);
+  } finally { db.close(); }
+});
+
+test("deep audit is explicit, bounded, scope-safe, and reports empty completion", () => {
+  const db = new Database(":memory:"); new SqliteStore(db);
+  try {
+    expect(runDoctorScan(db).history_audit).toBeUndefined();
+    expect(auditHistoryBlobs(db)).toEqual({ checked: 0, corrupt: 0, examples: [], complete: true, next_after: null });
+    expect(() => runDoctorScan(db, { deep: true, allowedTags: new Set() })).toThrow("unrestricted");
+    for (const n of [0, -1, 501, NaN, 1.5]) expect(() => auditHistoryBlobs(db, "", n)).toThrow();
+    expect(() => auditHistoryBlobs(db, "bad cursor")).toThrow();
+    expect(() => auditHistoryBlobs(db, "", 100, 1001)).toThrow();
+    for (let i=0;i<7;i++) db.prepare("INSERT INTO note_blobs(hash,content,byte_size) VALUES(?,?,?)").run(hashContent(String(i)), "broken", 6);
+    const p = auditHistoryBlobs(db, "", 2);
+    expect(p.checked).toBe(2); expect(p.complete).toBe(false); expect(p.next_after).not.toBeNull();
+    expect(auditHistoryBlobs(db).examples).toHaveLength(5);
+    expect(runDoctorScan(db, { deep: true, history_max_blobs: 2 }).summary).toContain("error");
+  } finally { db.close(); }
+});

package/core/src/history-compact-state.ts

@@ -0,0 +1,52 @@
+import type { Database } from "bun:sqlite";
+import { transaction } from "./txn.js";
+
+/** Rebuild derived hints only, atomically; authoritative history is untouched. */
+export function rebuildCompactState(db: Database): number {
+  return transaction(db, () => {
+    if (db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='history_compact_state'").get()) {
+      db.exec("DROP TABLE history_compact_state");
+    }
+    db.exec(`CREATE TABLE history_compact_state (
+      note_id TEXT PRIMARY KEY, versions INTEGER NOT NULL, stored INTEGER NOT NULL,
+      live INTEGER NOT NULL, refused INTEGER NOT NULL DEFAULT 0, refreshed_at INTEGER NOT NULL
+    );
+    CREATE INDEX idx_history_compact_candidates ON history_compact_state(refused, stored DESC);
+    CREATE INDEX IF NOT EXISTS idx_note_versions_note_hash ON note_versions(note_id, content_hash);`);
+    db.prepare(`INSERT INTO history_compact_state(note_id,versions,stored,live,refused,refreshed_at)
+      SELECT note_id,versions,stored,live,0,? FROM (${COMPACT_STATE_AGGREGATE.replace("__FILTER__", "")})`).run(Date.now());
+    return (db.prepare("SELECT COUNT(*) AS n FROM history_compact_state").get() as { n: number }).n;
+  });
+}
+
+// Scheduling hints only. History remains authoritative, including for deleted notes.
+export const COMPACT_STATE_AGGREGATE = `SELECT v.note_id,
+  (SELECT COUNT(*) FROM note_versions n WHERE n.note_id=v.note_id AND n.content_hash IS NOT NULL) AS versions,
+  SUM(b.byte_size) AS stored,
+  COALESCE(LENGTH(CAST(live_note.content AS BLOB)),
+    (SELECT content_len FROM note_versions newest WHERE newest.note_id=v.note_id ORDER BY version_ix DESC LIMIT 1),0) AS live
+  FROM (SELECT DISTINCT note_id,content_hash FROM note_versions WHERE content_hash IS NOT NULL __FILTER__) v
+  JOIN note_blobs b ON b.hash=v.content_hash LEFT JOIN notes live_note ON live_note.id=v.note_id
+  GROUP BY v.note_id`;
+
+export interface CompactState { note_id: string; versions: number; stored: number; live: number }
+export function readCompactState(db: Database, noteId: string): CompactState | null {
+  return db.prepare(COMPACT_STATE_AGGREGATE.replace("__FILTER__", "AND note_id=?")).get(noteId) as CompactState | null;
+}
+
+/** Caller owns the enclosing write transaction; run after the live-row mutation. */
+export function refreshCompactState(db: Database, noteId: string, opts?: { refused?: boolean }): void {
+  // Keep the existing graceful behavior of writes before history tables exist.
+  const tables = db.prepare("SELECT COUNT(*) AS n FROM sqlite_master WHERE type='table' AND name IN ('note_versions','note_blobs','history_compact_state')").get() as { n: number };
+  if (tables.n !== 3) return;
+  const state = readCompactState(db, noteId);
+  if (!state) {
+    db.prepare("DELETE FROM history_compact_state WHERE note_id=?").run(noteId);
+    return;
+  }
+  db.prepare(`INSERT INTO history_compact_state(note_id,versions,stored,live,refused,refreshed_at)
+    VALUES(?,?,?,?,?,?) ON CONFLICT(note_id) DO UPDATE SET
+    versions=excluded.versions,stored=excluded.stored,live=excluded.live,
+    refused=excluded.refused,refreshed_at=excluded.refreshed_at`)
+    .run(noteId, state.versions, state.stored, state.live, opts?.refused ? 1 : 0, Date.now());
+}

package/core/src/history-import.ts

@@ -1,6 +1,7 @@
 /** Git-independent import primitives. Callers own source parsing and offline access. */
 import type { Database } from "bun:sqlite";
 import { transaction } from "./txn.js";
+import { refreshCompactState } from "./history-compact-state.js";
 import { HistoryUnrecoverableError, hashContent, byteLength, VERSION_MAX_BYTES, pruneVersions, compactNote, getVersion, type HistoryPolicy, type VersionRow } from "./history.js";
 
 export interface ImportedObservation {
@@ -112,7 +113,7 @@ export function applyImportedNote(db: Database, opts: {
         VALUES(?,?,?,?,?,?,?,NULL,'git-import','import',?,NULL,?)`).run(opts.noteId, storage, hash, row.path, canonicalJson(row.metadata), row.extension, row.observed_at, size, row.created_at);
       db.prepare("INSERT INTO history_import_refs VALUES(?,?,?,?)").run(opts.noteId, index, row.commit, row.blob);
     }
-    if (opts.policy.enabled) pruneVersions(db, opts.noteId, opts.policy, opts.now);
+    if (opts.policy.enabled) pruneVersions(db, opts.noteId, opts.policy, opts.now, false);
     compactNote(db, opts.noteId, opts.policy);
     const after = new Set((db.prepare("SELECT version_ix FROM note_versions WHERE note_id=?").all(opts.noteId) as { version_ix: number }[]).map(r => r.version_ix));
     for (let i = 0; i < opts.observations.length; i++) {
@@ -125,6 +126,7 @@ export function applyImportedNote(db: Database, opts: {
     receipt.pruned_imported = receipt.imported_count - receipt.retained_count;
     receipt.pruned_native = nativeDrops.length;
     db.prepare("UPDATE history_import_receipts SET retained_count=?,pruned_imported=?,pruned_native=? WHERE note_id=?").run(receipt.retained_count, receipt.pruned_imported, receipt.pruned_native, opts.noteId);
+    refreshCompactState(db, opts.noteId);
     return { receipt, nativeDrops, skipped: false };
   });
 }

package/core/src/history.ts

@@ -14,6 +14,7 @@ import type { Database } from "bun:sqlite";
 import { createHash } from "node:crypto";
 import { encodeDelta, decodeDelta } from "./delta.js";
 import { transaction } from "./txn.js";
+import { refreshCompactState } from "./history-compact-state.js";
 
 export type HistoryOp =
   | "import"
@@ -212,7 +213,7 @@ export function captureVersion(
       size,
       prior.created_at,
     );
-    pruneVersions(db, prior.id, opts.policy);
+    pruneVersions(db, prior.id, opts.policy, Date.now(), false);
     return;
   }
   const hash = hashContent(text);
@@ -237,7 +238,7 @@ export function captureVersion(
     size,
     prior.created_at,
   );
-  pruneVersions(db, prior.id, opts.policy);
+  pruneVersions(db, prior.id, opts.policy, Date.now(), false);
 }
 export function appendRestoreMarker(
   db: Database,
@@ -261,13 +262,14 @@ export function appendRestoreMarker(
     noteId,
     tombstone.version_ix,
   );
-  pruneVersions(db, noteId, policy);
+  pruneVersions(db, noteId, policy, Date.now(), false);
 }
 export function pruneVersions(
   db: Database,
   noteId: string,
   policy: HistoryPolicy,
   now = Date.now(),
+  refresh = true,
 ): { versionsDeleted: number; blobsDeleted: number } {
   const rows = db
     .prepare(
@@ -301,6 +303,7 @@ export function pruneVersions(
       )
       .run(hash, hash, hash).changes;
   }
+  if (refresh) refreshCompactState(db, noteId);
   return { versionsDeleted, blobsDeleted };
 }
 export function gcBlobs(db: Database): { blobsDeleted: number } {
@@ -331,10 +334,12 @@ export function sweepDeletedHistory(
     .all(cutoff) as { note_id: string }[];
   return transaction(db, () => {
     let versionsDeleted = 0;
-    for (const v of victims)
+    for (const v of victims) {
       versionsDeleted += db
         .prepare("DELETE FROM note_versions WHERE note_id = ?")
         .run(v.note_id).changes;
+      db.prepare("DELETE FROM history_compact_state WHERE note_id=?").run(v.note_id);
+    }
     return { notesSwept: victims.length, versionsDeleted, ...gcBlobs(db) };
   });
 }
@@ -406,6 +411,7 @@ export function eraseHistory(
     const versionsDeleted = db
       .prepare("DELETE FROM note_versions WHERE note_id = ?")
       .run(noteId).changes;
+    db.prepare("DELETE FROM history_compact_state WHERE note_id=?").run(noteId);
     return { versionsDeleted, ...gcBlobs(db) };
   });
 }
@@ -553,6 +559,23 @@ export function compactNote(db: Database, noteId: string, policy: HistoryPolicy)
   const result: CompactResult = { blobs_deltified: 0, blobs_skipped_too_large: 0, versions_dropped: 0, bytes_before: 0, bytes_after: 0 };
   if (!policy.enabled || !policy.compact_enabled || !historyTablesPresent(db))
     return result;
+  return transaction(db, () => {
+  const changedHashes = new Set<string>();
+  const finish = () => {
+    // A blob can be referenced by several notes. Refresh each affected hint,
+    // without treating another note's compaction as a new history write.
+    const affected = new Set<string>();
+    for (const hash of changedHashes) {
+      for (const row of db.prepare("SELECT DISTINCT note_id FROM note_versions WHERE content_hash=?").all(hash) as { note_id: string }[]) affected.add(row.note_id);
+    }
+    for (const id of affected) {
+      if (id === noteId) continue;
+      const prior = db.prepare("SELECT refused FROM history_compact_state WHERE note_id=?").get(id) as { refused: number } | null;
+      refreshCompactState(db, id, { refused: prior?.refused === 1 });
+    }
+    refreshCompactState(db, noteId, { refused: result.blobs_deltified === 0 && result.versions_dropped === 0 });
+    return result;
+  };
   const rows = db.prepare("SELECT version_ix, content_hash, content_len FROM note_versions WHERE note_id = ? AND content_hash IS NOT NULL ORDER BY version_ix DESC").all(noteId) as {
     version_ix: number;
     content_hash: string;
@@ -569,10 +592,9 @@ export function compactNote(db: Database, noteId: string, policy: HistoryPolicy)
   const live = current?.content == null ? newest?.content_len ?? 0 : byteLength(current.content);
   const overBytes = policy.max_bytes_per_note !== null && stored > policy.max_bytes_per_note;
   if (!overBytes && rows.length < policy.compact_min_versions)
-    return result;
+    return finish();
   if (!overBytes && stored <= policy.compact_ratio * Math.max(live, 1))
-    return result;
-  return transaction(db, () => {
+    return finish();
     for (let start = 0; start < rows.length; start += policy.compact_run_length) {
       const run = rows.slice(start, start + policy.compact_run_length);
       const baseRow = db.prepare("SELECT hash, encoding, delta_of FROM note_blobs WHERE hash = ?").get(run[0]!.content_hash) as {
@@ -614,13 +636,15 @@ export function compactNote(db: Database, noteId: string, policy: HistoryPolicy)
           result.blobs_skipped_too_large++;
           continue;
         }
-        result.blobs_deltified += db.prepare("UPDATE note_blobs SET content = ?, byte_size = ?, encoding = 'fossil-delta', delta_of = ? WHERE hash = ? AND encoding IS NULL").run(payload, payload.length, baseHash, b.hash).changes;
+        const changed = db.prepare("UPDATE note_blobs SET content = ?, byte_size = ?, encoding = 'fossil-delta', delta_of = ? WHERE hash = ? AND encoding IS NULL").run(payload, payload.length, baseHash, b.hash).changes;
+        result.blobs_deltified += changed;
+        if (changed) changedHashes.add(b.hash);
       }
     }
     if (policy.max_bytes_per_note !== null)
       result.versions_dropped = enforceByteCeiling(db, noteId, policy);
     result.bytes_after = noteHistoryBytes(db, noteId);
-    return result;
+    return finish();
   });
 }
 function enforceByteCeiling(db: Database, noteId: string, policy: HistoryPolicy): number {
@@ -650,15 +674,10 @@ export function compactVault(db: Database, policy: HistoryPolicy, opts?: {
   if (budget !== null && budget <= 0)
     return { ...result, stopped_by: "budget" };
   const started = performance.now();
-  const candidates = opts?.noteId !== undefined ? [{ note_id: opts.noteId }] : db.prepare(`SELECT v.note_id, SUM(b.byte_size) AS stored,
-  (SELECT COUNT(*) FROM note_versions n WHERE n.note_id = v.note_id AND n.content_hash IS NOT NULL) AS versions,
-  COALESCE(LENGTH(CAST(live_note.content AS BLOB)),
-   (SELECT content_len FROM note_versions newest WHERE newest.note_id = v.note_id ORDER BY version_ix DESC LIMIT 1),0) AS live
-  FROM (SELECT DISTINCT note_id, content_hash FROM note_versions WHERE content_hash IS NOT NULL) v
-  JOIN note_blobs b ON b.hash = v.content_hash LEFT JOIN notes live_note ON live_note.id = v.note_id
-  GROUP BY v.note_id
-  HAVING (versions >= ? AND stored > ? * MAX(live,1)) OR (? IS NOT NULL AND stored > ?)
-  ORDER BY stored DESC`).all(policy.compact_min_versions, policy.compact_ratio, policy.max_bytes_per_note, policy.max_bytes_per_note) as {
+  const predicate = `refused=0 AND ((live>0 AND versions >= ? AND stored > ? * MAX(live,1)) OR (? IS NOT NULL AND stored > ?))`;
+  const args = [policy.compact_min_versions, policy.compact_ratio, policy.max_bytes_per_note, policy.max_bytes_per_note];
+  const total = opts?.noteId !== undefined ? 1 : (db.prepare(`SELECT COUNT(*) AS n FROM history_compact_state WHERE ${predicate}`).get(...args) as { n: number }).n;
+  const candidates = opts?.noteId !== undefined ? [{ note_id: opts.noteId }] : db.prepare(`SELECT note_id FROM history_compact_state WHERE ${predicate} ORDER BY stored DESC LIMIT ?`).all(...args, max === null ? -1 : max * 4) as {
     note_id: string;
   }[];
   for (const candidate of candidates) {
@@ -686,7 +705,7 @@ export function compactVault(db: Database, policy: HistoryPolicy, opts?: {
       console.warn("[history] compaction failed", candidate.note_id, err);
     }
   }
-  result.remaining_candidates = candidates.length - result.notes_scanned;
+  result.remaining_candidates = total - result.notes_scanned;
   result.duration_ms = performance.now() - started;
   return result;
 }

package/core/src/mcp-manifest.ts

@@ -705,7 +705,12 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
       requiredVerb: "read",
       description:
         "Read-only integrity scan across the tag/metadata taxonomy — run this after any bulk tag reorg (rename/merge/delete/subtree move) to confirm nothing leaked. Returns {findings, summary, scanned_at} — findings is an array, each entry {type, severity, subject, detail, remedy} — NEVER auto-fixes; apply the suggested remedy (usually rename-tag/merge-tags/update-tag/prune-schema) yourself. Finding types: dangling_parent_name (a parent_names entry naming a tag with no identity row), parent_names_cycle (a tag reaching itself through its ancestor chain — traversal tolerates this, but it's dishonest hierarchy state), mixed_type_indexed_field (a note's metadata value for an indexed field has a JSON type disagreeing with the field's declared storage type — the ordering/filtering-goes-silently-wrong precursor), orphaned_indexed_field_declarer (an indexed field naming a dead declarer tag — see prune-schema), and dead_tag_metadata_reference (HEURISTIC, always carries heuristic:true — a metadata value that looks like a stale reference to a renamed/merged/deleted tag, inferred from sibling notes using the same metadata key with values that ARE live tags; can never be certain since vault keeps no tag-rename history).",
-      inputSchema: { type: "object", properties: {} },
+      inputSchema: { type: "object", properties: {
+        deep: { type: "boolean", description: "Opt-in, unrestricted sessions only: materialize and hash-check a bounded history blob page. Check history_audit.complete; incomplete is not a clean audit." },
+        history_after: { type: "string", description: "Resume after history_audit.next_after. Pages are not a snapshot; audit a consistent backup for snapshot assurance." },
+        history_max_blobs: { type: "integer", minimum: 1, maximum: 500, description: "Maximum blobs in a deep page; default 100." },
+        history_budget_ms: { type: "integer", minimum: 1, maximum: 1000, description: "Between-blob budget; default 250ms. One blob may exceed it." },
+      } },
       condition: "core",
     },
     {

package/core/src/mcp.ts

@@ -2619,8 +2619,12 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
     // =====================================================================
     {
       name: "doctor",
-      execute: async () => {
-        return await store.doctor();
+      execute: async (params) => {
+        if (params.deep !== undefined && typeof params.deep !== "boolean") throw new Error("deep must be boolean");
+        if (params.history_after !== undefined && typeof params.history_after !== "string") throw new Error("history_after must be a string");
+        if (params.history_max_blobs !== undefined && typeof params.history_max_blobs !== "number") throw new Error("history_max_blobs must be a number");
+        if (params.history_budget_ms !== undefined && typeof params.history_budget_ms !== "number") throw new Error("history_budget_ms must be a number");
+        return await store.doctor({ deep: params.deep, history_after: params.history_after, history_max_blobs: params.history_max_blobs, history_budget_ms: params.history_budget_ms });
       },
     },
 

package/core/src/note-id-shape.test.ts

@@ -0,0 +1,9 @@
+import { test, expect } from "bun:test";
+import { isNoteIdShape } from "./ulid.js";
+
+test("note ID shape accepts exact legacy strings without coercion", () => {
+  for (const id of ["a", "A", "legacy:abc123", "2020-01-02-03-04-05", "shortid", "a_b", "a".repeat(64), "01M2KT1VQBHNZ99V5KSGXP6VSE"])
+    expect(isNoteIdShape(id)).toBe(true);
+  for (const id of ["", "a b", "a/b", "a.b", "a".repeat(65), "-leading", "_leading", ":leading", "a\n", "a\r", "a\0", "é", 123, null, undefined])
+    expect(isNoteIdShape(id)).toBe(false);
+});

package/core/src/notes.ts

@@ -32,6 +32,7 @@ import {
 } from "./search-query.js";
 import { generateUlid } from "./ulid.js";
 import { captureVersion, readPriorNoteRow, DEFAULT_HISTORY_POLICY, type HistoryPolicy } from "./history.js";
+import { refreshCompactState } from "./history-compact-state.js";
 
 /**
  * Write-attribution context (vault#298) — the two axes of provenance threaded
@@ -2594,6 +2595,7 @@ export function renameTag(db: Database, oldName: string, newName: string, attr?:
         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);
+        refreshCompactState(db, row.id);
         notesRewritten++;
       }
     }
@@ -2618,6 +2620,7 @@ export function renameTag(db: Database, oldName: string, newName: string, attr?:
         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);
+        refreshCompactState(db, row.id);
         pathsRenamed++;
       }
     }

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

@@ -19,7 +19,7 @@ it("P14a v28 upgrade creates both tables and three indexes without backfill", ()
   initSchema(db);
   expect(
     db.prepare("SELECT MAX(version) AS version FROM schema_version").get(),
-  ).toEqual({ version: 31 });
+  ).toEqual({ version: 32 });
   const tables = db
     .prepare(
       "SELECT name FROM sqlite_master WHERE type='table' AND name IN ('note_versions','note_blobs') ORDER BY name",

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

@@ -26,7 +26,7 @@ test("P12 v29 opens losslessly, fresh and upgraded columns/indexes agree", async
     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(SCHEMA_VERSION).toBe(32);
     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([]);

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

@@ -13,7 +13,7 @@ test("v30 to v31 retains native history and matches fresh import tables; reopeni
     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 MAX(version) AS version FROM schema_version").get()).toEqual({ version: 32 });
     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());

package/core/src/schema.ts

@@ -5,8 +5,18 @@ import { findMixedTypeIndexedFieldNotes } from "./doctor.js";
 import { transaction } from "./txn.js";
 import { timestampToMs } from "./cursor.js";
 import { ensureRelationshipColumn } from "./wikilinks.js";
+import { rebuildCompactState } from "./history-compact-state.js";
 
-export const SCHEMA_VERSION = 31;
+export const SCHEMA_VERSION = 32;
+
+function migrateToV32(db: Database): void {
+    const exists = db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='history_compact_state'").get();
+    // Read before initSchema records this open. On a timestamp tie, prefer
+    // a harmless rebuild over missing an older writer's stale hints.
+    const previous = db.prepare("SELECT version FROM schema_version ORDER BY applied_at DESC, version ASC LIMIT 1").get() as { version: number } | null;
+    if (exists && (!previous || previous.version >= 32)) return;
+    rebuildCompactState(db);
+}
 
 /**
  * Deterministic last-resort epoch for a note whose `updated_at` AND
@@ -742,6 +752,7 @@ export function initSchema(db: Database): void {
   // v30: depth-one history deltas and captured creation time, no backfill.
   migrateToV30(db);
   migrateToV31(db);
+  migrateToV32(db);
 
   // Rebuild any generated columns + indexes declared in indexed_fields.
   // No-op for a fresh vault; idempotent on existing vaults.

package/core/src/store.ts

@@ -3,6 +3,7 @@ import { HistoryPreconditionRequiredError } from "./history.js";
 import type { Store, Note, Link, Attachment, QueryOpts, QueryNotesPage, AggregateRow, SemanticSearchResult } from "./types.js";
 import { compactNote, compactVault, countNoteVersions, type CompactResult, type CompactSummary, captureVersion, readPriorNoteRow, resolveHistoryPolicy, appendRestoreMarker, listVersions, getVersion, latestTombstone, eraseHistory, sweepDeletedHistory, deletedHistoryStats, HistoryNotFoundError, HistoryOverflowError, HistoryUnrecoverableError, DEFAULT_HISTORY_POLICY, VERSION_MAX_BYTES, type VersionRow, type HistoryPolicy, type HistoryOp } from "./history.js";
 import { initSchema } from "./schema.js";
+import { refreshCompactState } from "./history-compact-state.js";
 import * as noteOps from "./notes.js";
 import * as linkOps from "./links.js";
 import * as tagSchemaOps from "./tag-schemas.js";
@@ -530,7 +531,12 @@ export class BunSqliteStore implements Store {
       if (normalized !== opts.metadata) opts = { ...opts, metadata: normalized };
     }
 
-    const note = noteOps.createNote(this.db, content, opts);
+    const note = this.transaction(() => {
+      const created = noteOps.createNote(this.db, content, opts);
+      // Explicit IDs may recreate a deleted note with retained history.
+      refreshCompactState(this.db, created.id);
+      return created;
+    });
 
     if (content) {
       syncWikilinks(this.db, note.id, content);
@@ -692,6 +698,7 @@ export class BunSqliteStore implements Store {
         this.syncReferenceFieldLinks(note, priorMetadataForRefs);
       }
 
+      refreshCompactState(this.db, id);
       return note;
     });
 
@@ -818,6 +825,7 @@ export class BunSqliteStore implements Store {
         if (prior) captureVersion(this.db, prior, { ...attr, op: "cascade-rename", policy: this.historyPolicy });
         noteOps.updateNote(this.db, sourceId, { content: updated });
         syncWikilinks(this.db, sourceId, updated);
+        refreshCompactState(this.db, sourceId);
       }
     }
   }
@@ -858,6 +866,7 @@ export class BunSqliteStore implements Store {
       appendRestoreMarker(this.db, id, tomb, { actor: opts.actor ?? null, via: opts.via ?? null }, this.historyPolicy);
       if (note.content) syncWikilinks(this.db, id, note.content);
       if (note.path) resolveUnresolvedWikilinks(this.db, note.path, id);
+      refreshCompactState(this.db, id);
       return note;
     });
   }
@@ -910,6 +919,7 @@ export class BunSqliteStore implements Store {
       }
       noteOps.deleteNote(this.db, id);
       refreshAmbiguousLinks(this.db, ambiguityKeys);
+      refreshCompactState(this.db, id);
     });
     if (existing?.path) this.invalidateConfigCachesForPath(existing.path);
     // Dispatch even when `existing` was null — the caller asked for a
@@ -1603,7 +1613,11 @@ export class BunSqliteStore implements Store {
       const normalized = normalizeDateFields(this.getSchemaConfig(), { tags: opts.tags, metadata: opts.metadata });
       if (normalized !== opts.metadata) opts = { ...opts, metadata: normalized };
     }
-    return noteOps.createNote(this.db, content, opts);
+    return this.transaction(() => {
+      const created = noteOps.createNote(this.db, content, opts);
+      refreshCompactState(this.db, created.id);
+      return created;
+    });
   }
 
   /**

package/core/src/ulid.ts

@@ -114,3 +114,10 @@ export function generateUlid(): string {
 
 /** 26-char Crockford base32 (`0-9A-HJKMNP-TV-Z`, case-insensitive by spec — we always emit uppercase). */
 export const ULID_REGEX = /^[0-9A-HJKMNP-TV-Z]{26}$/;
+
+const NOTE_ID_SHAPE = /^[A-Za-z0-9][A-Za-z0-9:_-]{0,63}$/;
+/** Accepted history identity shape, including legacy IDs; never normalizes an ID. */
+export function isNoteIdShape(value: unknown): value is string {
+  // Comparing the entire match also rejects a final newline (JS `$` permits one).
+  return typeof value === "string" && NOTE_ID_SHAPE.exec(value)?.[0] === value;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/vault",
-  "version": "0.7.9-rc.8",
+  "version": "0.7.9-rc.9",
   "description": "Agent-native knowledge graph. Notes, tags, links over MCP.",
   "module": "src/cli.ts",
   "type": "module",

package/src/cli.ts

@@ -3432,6 +3432,8 @@ async function cmdExport(args: string[]) {
  * a past revision (`git show <sha>:<path>.md`).
  */
 async function cmdHistory(args: string[]) {
+  const rebuild = args[0] === "rebuild-state";
+  if (rebuild) args = args.slice(1);
   let vaultName = "default";
   let notePath: string | undefined;
   let limit: number | undefined;
@@ -3485,6 +3487,10 @@ async function cmdHistory(args: string[]) {
     }
   }
 
+  if (rebuild && (showSha || notePath || limit !== undefined)) {
+    console.error("rebuild-state accepts only --vault and --json.");
+    process.exit(1);
+  }
   if (showSha && !notePath) {
     console.error("--show <sha> requires --note <path> (which file to read at that revision).");
     process.exit(1);
@@ -3496,6 +3502,25 @@ async function cmdHistory(args: string[]) {
     process.exit(1);
   }
 
+  if (rebuild) {
+    const path = vaultDbPath(vaultName);
+    if (!existsSync(path)) {
+      console.error(`Vault database not found: ${path}`);
+      process.exit(1);
+    }
+    const { Database } = await import("bun:sqlite");
+    const { initSchema } = await import("../core/src/schema.js");
+    const { rebuildCompactState } = await import("../core/src/history-compact-state.js");
+    const db = new Database(path, { readwrite: true, create: false });
+    try {
+      initSchema(db);
+      const rebuilt_notes = rebuildCompactState(db);
+      console.log(asJson ? JSON.stringify({ vault: vaultName, rebuilt_notes }) :
+        `Rebuilt compaction hints for ${rebuilt_notes} notes in vault "${vaultName}". History unchanged.`);
+    } finally { db.close(); }
+    return;
+  }
+
   // Resolve the mirror dir the same way the server does: per-vault mirror
   // config (or defaults) → resolveMirrorPath against the vault's data dir.
   const mirrorConfig = readMirrorConfigForVault(vaultName) ?? defaultMirrorConfig();
@@ -3558,6 +3583,10 @@ async function cmdHistory(args: string[]) {
 }
 
 function printHistoryUsage(): void {
+  console.error("Usage: parachute-vault history rebuild-state [--vault <name>] [--json]");
+  console.error("Rebuild compaction hints and reset refusals; does not compact or change history.");
+  console.error("The current server may stay running: writes serialize with the rebuild transaction.");
+  console.error("Stop the server optionally to avoid write contention; do not run older writers concurrently.\n");
   console.error(
     "Usage: parachute-vault history [--note <path>] [--limit N] [--vault <name>] [--json]\n" +
       "                              [--note <path> --show <sha>]",

package/src/history-import.test.ts

@@ -11,6 +11,42 @@ import { getVaultStore, clearVaultStoreCache } from "./vault-store.ts";
 import { getImportedVersion } from "../core/src/history-import.ts";
 import { historyMirrorStatePath, readHistoryMirrorPhase, mirrorConfigPath } from "./mirror-config.ts";
 const noteId = "01M2KT1VQBHNZ99V5KSGXP6VSE";
+for (const id of ["legacy:abc123", "2020-01-02-03-04-05", "shortid"]) {
+  for (const sidecar of [false, true]) test(`legacy ID staging: ${id}, sidecar=${sidecar}`, () => {
+    const dir = mkdtempSync(join(tmpdir(), "legacy-stage-")), db = new Database(":memory:");
+    try {
+      const repo = repoAt(join(dir, "repo"));
+      if (sidecar) {
+        mkdirSync(join(repo, ".parachute/notes-meta"), { recursive: true });
+        writeFileSync(join(repo, ".parachute/notes-meta/entry.yaml"), `id: ${id}\npath: entry\nextension: json\n`);
+        writeFileSync(join(repo, "entry.json"), '{}');
+        git(repo, "add", "."); git(repo, "commit", "-m", "sidecar");
+      } else commit(repo, "legacy body", id);
+      stageArchive(repo, git(repo, "rev-parse", "HEAD"), db);
+      expect(db.query("SELECT note_id FROM observations").all()).toEqual([{ note_id: id }]);
+      expect(db.query("SELECT * FROM issues").all()).toEqual([]);
+      expect(db.query("SELECT * FROM quarantine").all()).toEqual([]);
+    } finally { db.close(); rmSync(dir, { recursive: true, force: true }); }
+  });
+}
+for (const id of ["a b", "a/b", "a.b", "a".repeat(65), "", "-leading"]) {
+  for (const sidecar of [false, true]) test(`invalid ID staging: ${JSON.stringify(id)}, sidecar=${sidecar}`, () => {
+    const dir = mkdtempSync(join(tmpdir(), "invalid-stage-")), db = new Database(":memory:");
+    try {
+      const repo = repoAt(join(dir, "repo"));
+      const meta = `id: ${JSON.stringify(id)}\npath: entry\n`;
+      if (sidecar) {
+        mkdirSync(join(repo, ".parachute/notes-meta"), { recursive: true });
+        writeFileSync(join(repo, ".parachute/notes-meta/entry.yaml"), meta + "extension: json\n");
+        writeFileSync(join(repo, "entry.json"), '{}');
+      } else writeFileSync(join(repo, "entry.md"), `---\n${meta}---\nbody`);
+      git(repo, "add", "."); git(repo, "commit", "-m", "invalid");
+      stageArchive(repo, git(repo, "rev-parse", "HEAD"), db);
+      expect(db.query("SELECT * FROM observations").all()).toEqual([]);
+      expect(db.query("SELECT reason FROM issues").all()).toContainEqual({ reason: sidecar ? "invalid_sidecar" : "invalid_id" });
+    } finally { db.close(); rmSync(dir, { recursive: true, force: true }); }
+  });
+}
 function git(dir: string, ...args: string[]) {
   const p = spawnSync("git", ["-C", dir, ...args], { encoding: "utf8", env: { ...process.env, GIT_AUTHOR_NAME: "test", GIT_AUTHOR_EMAIL: "test@example.test", GIT_COMMITTER_NAME: "test", GIT_COMMITTER_EMAIL: "test@example.test" } });
   if (p.status !== 0) throw new Error(p.stderr); return p.stdout.trim();
@@ -35,6 +71,57 @@ test("git staging preserves exported CRLF bodies and A-B-A while quarantining du
     try { stageArchive(repo, duplicate, second); expect(second.query("SELECT reason FROM quarantine").all()).toEqual([{ reason: "duplicate_id" }]); expect(second.query("SELECT * FROM observations").all()).toEqual([]); } finally { second.close(); }
   } finally { db.close(); rmSync(dir, { recursive: true, force: true }); }
 });
+test("legacy duplicate IDs still quarantine and selection entries preserve exact identity", () => {
+  const dir = mkdtempSync(join(tmpdir(), "legacy-duplicate-")), db = new Database(":memory:");
+  try {
+    const repo = repoAt(join(dir, "repo")), id = "legacy:duplicate";
+    commit(repo, "first", id); const tip = commit(repo, "second", id, "duplicate.md");
+    stageArchive(repo, tip, db);
+    expect(db.query("SELECT * FROM quarantine").all()).toEqual([{ note_id: id, reason: "duplicate_id" }]);
+    expect(db.query("SELECT * FROM observations").all()).toEqual([]);
+    const selections = normalizeHistorySelections({ format: 1, tip, source_fingerprint: "a".repeat(64), selections: [{
+      note_id: id, commit: tip, selected: { git_path: "entry.md", blob: git(repo, "rev-parse", `${tip}:entry.md`) },
+      rejected: [{ git_path: "duplicate.md", blob: git(repo, "rev-parse", `${tip}:duplicate.md`), reason: "explicit choice" }], reason: "explicit choice",
+    }] });
+    expect(selections.selections[0]!.note_id).toBe(id);
+  } finally { db.close(); rmSync(dir, { recursive: true, force: true }); }
+});
+test("legacy imports preserve exact IDs, receipts and idempotency; case mismatch never merges", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "legacy-import-")), saved = process.env.PARACHUTE_HOME;
+  process.env.PARACHUTE_HOME = join(dir, "home");
+  try {
+    const probe = Bun.serve({ port: 0, fetch: () => new Response() }); const port = probe.port!; probe.stop(true);
+    writeGlobalConfig({ port });
+    writeVaultConfig({ name: "test", api_keys: [], created_at: new Date().toISOString() });
+    const ids = ["legacy:abc123", "2020-01-02-03-04-05", "shortid"];
+    const store = getVaultStore("test");
+    for (const id of [...ids, "CaseId"]) await store.createNote("native", { id });
+    clearVaultStoreCache();
+    const repo = repoAt(join(dir, "repo"));
+    for (const [i, id] of [...ids, "caseid"].entries()) commit(repo, "archive", id, `entry${i}.md`);
+    let tip = git(repo, "rev-parse", "HEAD");
+    const output = join(dir, "plan.json");
+    await runHistoryImport(["plan", "--vault", "test", "--source", repo, "--through", tip, "--output", output]);
+    const plan = JSON.parse(readFileSync(output, "utf8"));
+    expect(plan.skipped).toEqual(["caseid"]);
+    expect(plan.missing_at_tip).toEqual(["CaseId"]);
+    expect(plan.notes.map((n: any) => n.id).sort()).toEqual([...ids].sort());
+    // Resolve the fixture mismatch explicitly before prepare, never via coercion.
+    commit(repo, "archive", "CaseId", "entry3.md"); tip = git(repo, "rev-parse", "HEAD");
+    const manifest = join(dir, "final.json"), archive = join(dir, "archive.bundle");
+    await runHistoryImport(["prepare", "--vault", "test", "--source", repo, "--through", tip, "--archive", archive, "--output", manifest]);
+    await runHistoryImport(["apply", "--vault", "test", "--manifest", manifest, "--archive", archive]);
+    const db = new Database(vaultDbPath("test"));
+    try {
+      const before = db.query("SELECT * FROM history_import_receipts ORDER BY note_id").all();
+      expect(before).toHaveLength(4);
+      for (const id of ids) expect(getImportedVersion(db, id, 0)?.content).toBe("archive");
+      await runHistoryImport(["apply", "--vault", "test", "--manifest", manifest, "--archive", archive]);
+      expect(db.query("SELECT * FROM history_import_receipts ORDER BY note_id").all()).toEqual(before);
+      expect(db.query("SELECT id FROM notes ORDER BY id").all()).toEqual([...ids, "CaseId"].sort().map(id => ({ id })));
+    } finally { db.close(); }
+  } finally { clearVaultStoreCache(); if (saved === undefined) delete process.env.PARACHUTE_HOME; else process.env.PARACHUTE_HOME = saved; rmSync(dir, { recursive: true, force: true }); }
+}, 30_000);
 test("offline prepare applies verified bundle, retries without resurrection, then retires", async () => {
   const dir = mkdtempSync(join(tmpdir(), "import-cutover-")), saved = process.env.PARACHUTE_HOME;
   process.env.PARACHUTE_HOME = join(dir, "home");

package/src/history-import.ts

@@ -5,6 +5,7 @@ import { createHash } from "node:crypto";
 import { chmodSync, closeSync, copyFileSync, existsSync, fsyncSync, mkdirSync, mkdtempSync, openSync, readSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { tmpdir } from "node:os";
+import { isNoteIdShape } from "../core/src/ulid.ts";
 import { applyImportedNote, beginImportRun, canonicalJson, importObservationDigest, importTargetDigest, readImportReceipt, type ImportedObservation, type ImportRun } from "../core/src/history-import.ts";
 import { hashContent, resolveHistoryPolicy, VERSION_MAX_BYTES, type HistoryPolicy } from "../core/src/history.ts";
 import { applyConnectionPragmas, initSchema } from "../core/src/schema.ts";
@@ -16,7 +17,6 @@ const MAX_OUTPUT = 32 * 1024 * 1024;
 const MAX_COMMITS = 100_000;
 const MAX_OBJECTS = 10_000_000;
 const MAX_BYTES = 2 * 1024 * 1024 * 1024;
-const ID = /^[0-9A-HJKMNP-TV-Z]{26}$/;
 const decoder = new TextDecoder("utf-8", { fatal: true });
 class GitArchiveError extends Error {}
 function git(repo: string, args: string[]): Buffer {
@@ -47,7 +47,7 @@ function inline(raw: string): { meta: Record<string, unknown>; content: string }
   return { meta: yaml(match[1]!), content: raw.slice(match[0].length) };
 }
 function observation(meta: Record<string, unknown>, content: string, commit: string, blob: string, time: string): { id: string; row: ImportedObservation } {
-  if (typeof meta.id !== "string" || !ID.test(meta.id)) throw new Error("invalid_id");
+  if (!isNoteIdShape(meta.id)) throw new Error("invalid_id");
   if (Buffer.byteLength(content) > VERSION_MAX_BYTES) throw new Error("oversized_body");
   const path = meta.path ?? null, extension = meta.extension ?? "md", created = meta.created_at ?? null;
   if (path !== null && (typeof path !== "string" || path.includes("\0") || path.split("/").includes(".."))) throw new Error("invalid_path");
@@ -88,7 +88,7 @@ export function normalizeHistorySelections(input: unknown): HistorySelections {
   const seen = new Set<string>();
   const selections = value.selections.map(raw => {
     const entry = selectionObject(raw, ["note_id", "commit", "selected", "rejected", "reason"]);
-    if (typeof entry.note_id !== "string" || !ID.test(entry.note_id) || typeof entry.commit !== "string" || !OBJECT_ID.test(entry.commit) || !Array.isArray(entry.rejected) || !entry.rejected.length) throw new Error("Invalid selection entry");
+    if (!isNoteIdShape(entry.note_id) || typeof entry.commit !== "string" || !OBJECT_ID.test(entry.commit) || !Array.isArray(entry.rejected) || !entry.rejected.length) throw new Error("Invalid selection entry");
     const key = `${entry.note_id}:${entry.commit}`;
     if (seen.has(key)) throw new Error("Duplicate selection note/commit");
     seen.add(key);
@@ -188,7 +188,7 @@ export function stageArchive(repo: string, tip: string, stage: Database, inputSe
       const message = error instanceof Error ? error.message : "invalid_observation";
       const reason = /^[a-z_]+$/.test(message) ? message : "invalid_metadata_or_utf8";
       if (error instanceof GitArchiveError || message === "Archive byte limit exceeded" || message === "Archive note limit exceeded") throw error;
-      if (typeof id === "string" && ID.test(id)) stage.prepare("INSERT OR REPLACE INTO quarantine VALUES(?,?)").run(id, reason);
+      if (isNoteIdShape(id)) stage.prepare("INSERT OR REPLACE INTO quarantine VALUES(?,?)").run(id, reason);
       else stage.prepare("INSERT INTO issues VALUES(?,?,?)").run(commit, entry.path, reason);
     };
     const format = files.get(".parachute/vault.yaml");
@@ -198,7 +198,7 @@ export function stageArchive(repo: string, tip: string, stage: Database, inputSe
       try {
         meta = yaml(read(entry));
         const extension = meta.extension;
-        if (typeof meta.id !== "string" || !ID.test(meta.id) || typeof extension !== "string") throw new Error("invalid_sidecar");
+        if (!isNoteIdShape(meta.id) || typeof extension !== "string") throw new Error("invalid_sidecar");
         const contentPath = `${meta.path ?? `_unpathed/${meta.id}`}.${extension}`;
         const body = files.get(contentPath);
         if (!body) throw new Error("missing_sidecar_body");
@@ -321,7 +321,7 @@ function project(vault: string, repo: string, tip: string, dir: string, opts: {
     const selections = opts.selections ?? null;
     const source = stageArchive(repo, tip, stage, selections), policy = resolveHistoryPolicy(config.history);
     const waivers = opts.waivers ?? {};
-    for (const [id, reason] of Object.entries(waivers)) if (!ID.test(id) || typeof reason !== "string" || !reason.trim()) throw new Error("Waivers require note IDs and reasons");
+    for (const [id, reason] of Object.entries(waivers)) if (!isNoteIdShape(id) || typeof reason !== "string" || !reason.trim()) throw new Error("Waivers require note IDs and reasons");
     const options_digest = optionsDigest(policy, waivers, selections);
     const run = { run_id: "projection", source_fingerprint: source.source_fingerprint, tip, options_digest };
     beginImportRun(db, run);

package/src/history-rebuild-cli.test.ts

@@ -0,0 +1,38 @@
+import { test, expect } from "bun:test";
+import { Database } from "bun:sqlite";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { writeVaultConfig, vaultDbPath } from "./config.ts";
+import { BunSqliteStore } from "../core/src/store.ts";
+import { runDoctorScan } from "../core/src/doctor.ts";
+
+test("history rebuild-state repairs hints only, without requiring a Git mirror", async () => {
+  const taskDir = mkdtempSync(join(tmpdir(), "history-rebuild-"));
+  const saved = process.env.PARACHUTE_HOME;
+  process.env.PARACHUTE_HOME = taskDir;
+  let db: Database | undefined;
+  try {
+    writeVaultConfig({ name: "repair", api_keys: [], created_at: new Date().toISOString() });
+    db = new Database(vaultDbPath("repair"), { create: true });
+    const store = new BunSqliteStore(db);
+    const n = await store.createNote("before");
+    await store.updateNote(n.id, { content: "after" });
+    db.exec("UPDATE history_compact_state SET stored=999,refused=1");
+    expect(runDoctorScan(db).findings.some(f=>f.type==="history_compact_state_drift")).toBe(true);
+    const notes = db.query("SELECT * FROM notes").all(), versions = db.query("SELECT * FROM note_versions").all(), blobs = db.query("SELECT * FROM note_blobs").all();
+    db.close(); db=undefined;
+    const proc = Bun.spawnSync({ cmd: [process.execPath, join(import.meta.dir,"cli.ts"),"history","rebuild-state","--vault","repair","--json"], env: {...process.env, PARACHUTE_HOME: taskDir}, stdout:"pipe",stderr:"pipe" });
+    expect(proc.exitCode, new TextDecoder().decode(proc.stderr)).toBe(0);
+    expect(JSON.parse(new TextDecoder().decode(proc.stdout))).toEqual({ vault: "repair", rebuilt_notes: 1 });
+    db = new Database(vaultDbPath("repair"));
+    expect(runDoctorScan(db).findings.some(f=>f.type==="history_compact_state_drift")).toBe(false);
+    expect(db.query("SELECT * FROM notes").all()).toEqual(notes);
+    expect(db.query("SELECT * FROM note_versions").all()).toEqual(versions);
+    expect(db.query("SELECT * FROM note_blobs").all()).toEqual(blobs);
+  } finally {
+    db?.close();
+    if(saved===undefined)delete process.env.PARACHUTE_HOME;else process.env.PARACHUTE_HOME=saved;
+    rmSync(taskDir,{recursive:true,force:true});
+  }
+});

package/src/mcp-tools.ts

@@ -911,6 +911,7 @@ function applyTagScopeWrappers(
   wrapReadTool(tools, "doctor", async (orig, params) => {
     const allowed = await getAllowed();
     if (!allowed) return await orig(params);
+    if (params.deep) return forbidden("deep history audit requires an unrestricted session");
     return runDoctorScan(store.db, { allowedTags: allowed });
   });
 }

package/src/routes.ts

@@ -14,7 +14,7 @@ import { getImportedVersion, importStorageIndex, parseHistorySelector, projectHi
 
 import { HistoryNotFoundError, latestTombstone } from "../core/src/history.js";
 import { projectHistoryProvenance } from "../core/src/history-visibility.js";
-import { ULID_REGEX } from "../core/src/ulid.js";
+import { isNoteIdShape } from "../core/src/ulid.js";
 import type { Database } from "bun:sqlite";
 import type { Store, Note, QueryOpts, AggregateSpec } from "../core/src/types.ts";
 import { TAG_EXPAND_MODES, stripTagHash, suggestSimilarTag, type TagExpandMode } from "../core/src/tag-hierarchy.ts";
@@ -2932,7 +2932,7 @@ async function handleNotesInner(
     if (note && !noteWithinTagScope(note, tagScope.allowed, tagScope.raw)) {
       return json({ error: "Not found", error_type: "not_found" }, 404);
     }
-    if (!note && (tagScope.raw !== null || !ULID_REGEX.test(idOrPath) ||
+    if (!note && (tagScope.raw !== null || !isNoteIdShape(idOrPath) ||
       !(await store.listNoteVersions(idOrPath, { limit: 1 })).length)) {
       return json({ error: "Not found", error_type: "not_found" }, 404);
     }
@@ -4453,11 +4453,21 @@ export function handleUnresolvedWikilinks(
  * catalog.
  */
 export async function handleDoctor(
-  _req: Request,
+  req: Request,
   store: Store,
   tagScope: TagScopeCtx = NO_TAG_SCOPE,
 ): Promise<Response> {
-  const report = await store.doctor({ allowedTags: tagScope.allowed });
+  const q = new URL(req.url).searchParams;
+  if (q.has("deep") && !["true", "false"].includes(q.get("deep")!)) return json({ error: "deep must be true or false" }, 400);
+  const deep = q.get("deep") === "true";
+  if (deep && tagScope.allowed !== null) return json({ error: "deep history audit requires an unrestricted session" }, 403);
+  const after = q.get("history_after") ?? undefined;
+  const maxBlobs = q.has("history_max_blobs") ? Number(q.get("history_max_blobs")) : undefined;
+  const budgetMs = q.has("history_budget_ms") ? Number(q.get("history_budget_ms")) : undefined;
+  if ((after !== undefined && !/^[a-f0-9]{64}$/.test(after)) ||
+      (maxBlobs !== undefined && (!Number.isInteger(maxBlobs) || maxBlobs < 1 || maxBlobs > 500)) ||
+      (budgetMs !== undefined && (!Number.isInteger(budgetMs) || budgetMs < 1 || budgetMs > 1000))) return json({ error: "invalid history audit bounds or cursor" }, 400);
+  const report = await store.doctor({ allowedTags: tagScope.allowed, deep, history_after: after, history_max_blobs: maxBlobs, history_budget_ms: budgetMs });
   return json(report);
 }
 

package/src/tag-integrity-mcp.test.ts

@@ -65,6 +65,24 @@ async function toolsFor(vaultName: string, scopedTags: string[] | null, verb: "r
   return generateScopedMcpTools(vaultName, authFor(vaultName, scopedTags, verb));
 }
 
+test("deep doctor REST/MCP parity and scoped refusal", async () => {
+  seedVault("journal");
+  const store = getVaultStore("journal");
+  await store.upsertTagRecord("mine", {});
+  const doctor = (await toolsFor("journal", null, "read")).find(t => t.name === "doctor")!;
+  const mcp: any = await doctor.execute({ deep: true, history_max_blobs: 1 });
+  const rest = await handleDoctor(new Request("http://localhost/api/doctor?deep=true&history_max_blobs=1"), store);
+  expect(rest.status).toBe(200);
+  expect((await rest.json() as any).history_audit).toEqual(mcp.history_audit);
+  expect(mcp.history_audit.complete).toBe(true);
+  const scoped = (await toolsFor("journal", ["mine"], "admin")).find(t => t.name === "doctor")!;
+  expect((await scoped.execute({ deep: true }) as any).error_type).toBe("tag_scope_violation");
+  expect((await handleDoctor(new Request("http://localhost/api/doctor?deep=true"), store, { allowed: new Set(["mine"]), raw: ["mine"] })).status).toBe(403);
+  for (const q of ["deep=1", "deep=true&history_after=oops", "deep=true&history_max_blobs=501", "deep=true&history_budget_ms=0"]) {
+    expect((await handleDoctor(new Request("http://localhost/api/doctor?" + q), store)).status).toBe(400);
+  }
+});
+
 describe("rename-tag / merge-tags — tag-scope gating (vault#552)", () => {
   test("rename-tag: old_name or new_name outside the allowlist is refused before reaching core", async () => {
     seedVault("journal");

package/src/vault-history-routes.test.ts

@@ -369,6 +369,21 @@ test("P19 overflow deletion remains possible but its tombstone cannot restore",
   expect(r.status).toBe(409);
   expect(r.body.error_type).toBe("history_unrecoverable");
 });
+test("legacy deleted IDs resolve exact history and restore without exposing scoped tombstones", async () => {
+  for (const id of ["2020-01-02-03-04-05", "legacy:abc123", "shortid"]) {
+    await store.createNote("original", { id, path: `legacy/${id}` });
+    await store.updateNote(id, { content: "current" });
+    await store.deleteNote(id);
+    expect((await call(id, "/versions", "GET", undefined, true)).status).toBe(404);
+    expect((await call(id, "/restore", "POST", { version_ix: 0 }, true)).status).toBe(404);
+    expect((await call(id, "/versions")).status).toBe(200);
+    const restored = await call(id, "/restore", "POST", { version_ix: 0 });
+    expect(restored.status).toBe(200);
+    expect(restored.body).toMatchObject({ id, content: "original", recreated: true });
+  }
+  expect((await call("not-a-tombstone", "/versions")).status).toBe(404);
+  expect((await call("not-a-tombstone", "/restore", "POST", { version_ix: 0 })).status).toBe(404);
+});
 test("P20 REST recreates untagged at the tombstone path and guards conflicts", async () => {
   const n = await fixture();
   await store.deleteNote(n.id);