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

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"
@@ -119,6 +120,14 @@ export class HistoryUnrecoverableError extends Error {
     this.name = "HistoryUnrecoverableError";
   }
 }
+export class HistoryPreconditionRequiredError extends Error {
+  readonly code = "PRECONDITION_REQUIRED";
+  readonly error_type = "precondition_required";
+  constructor(readonly note_id: string) {
+    super("Restoring an existing note requires if_updated_at from the note you reviewed.");
+  }
+}
+
 export class HistoryNotFoundError extends Error {
   code = "HISTORY_NOT_FOUND" as const;
   note_id: string;
@@ -204,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);
@@ -229,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,
@@ -253,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(
@@ -293,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 } {
@@ -323,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) };
   });
 }
@@ -398,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) };
   });
 }
@@ -545,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;
@@ -561,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 {
@@ -606,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 {
@@ -642,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) {
@@ -678,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

@@ -1,7 +1,9 @@
 import { Database } from "bun:sqlite";
+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";
@@ -529,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);
@@ -691,6 +698,7 @@ export class BunSqliteStore implements Store {
         this.syncReferenceFieldLinks(note, priorMetadataForRefs);
       }
 
+      refreshCompactState(this.db, id);
       return note;
     });
 
@@ -817,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);
       }
     }
   }
@@ -834,6 +843,7 @@ export class BunSqliteStore implements Store {
       const v = getVersion(this.db, id, versionIx);
       if (!v) throw new HistoryNotFoundError(id, versionIx);
       if (v.encoding === "overflow") throw new HistoryUnrecoverableError(id, versionIx);
+      if (opts.if_updated_at === undefined) throw new HistoryPreconditionRequiredError(id);
       return await this.updateNote(id, {
         content: v.content!, metadata: v.metadata, extension: v.extension ?? undefined,
         actor: opts.actor ?? null, via: opts.via ?? null,
@@ -856,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;
     });
   }
@@ -908,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
@@ -1601,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.7",
+  "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-routes.test.ts

@@ -45,6 +45,24 @@ async function call(path: string, method = "GET", body?: unknown, verb = "admin"
 }
 
 import { applyImportedNote, beginImportRun, importTargetDigest } from "../core/src/history-import.ts";
+test("authenticated history REST redacts scoped provenance for read/write/admin tokens", async () => {
+  const note = await store.createNote("before", { tags: ["journal"] });
+  await store.updateNote(note.id, { content: "after", actor: "HISTORICAL_EDITOR", via: "HISTORICAL_INTERFACE" });
+  for (const verb of ["read", "write", "admin"]) {
+    for (const scoped of [false, true]) {
+      for (const suffix of ["/versions", "/versions/0"]) {
+        const got = await call(`/notes/${note.id}${suffix}`, "GET", undefined, verb, scoped);
+        expect(got.status).toBe(200);
+        const row = got.body.versions?.[0] ?? got.body;
+        expect(Object.hasOwn(row, "actor")).toBe(!scoped);
+        expect(Object.hasOwn(row, "via")).toBe(!scoped);
+        if (!scoped) expect(row.actor).toBe("HISTORICAL_EDITOR");
+        expect(row.version_ix).toBe(0);
+      }
+    }
+  }
+  expect((await store.getNoteVersion(note.id, 0))!.actor).toBe("HISTORICAL_EDITOR");
+});
 test("imported REST references restore by ID or encoded path and preserve native keys", async () => {
   const note = await store.createNote("native", { path: "folder/imported", tags: ["journal"] });
   await store.updateNote(note.id, { content: "current" });
@@ -66,7 +84,11 @@ test("imported REST references restore by ID or encoded path and preserve native
   expect(list.body.versions.map((v: any) => v.version_ix ?? v.origin)).toEqual([0, "git-import"]);
   for (const body of [{ origin: "git-import" }, { import_ix: 0 }, { origin: "git-import", import_ix: 0, version_ix: 0 }, { origin: "git-import", import_ix: -1 }]) expect((await call(`/notes/${note.id}/restore`, "POST", body)).status).toBe(400);
   expect((await call(`/notes/${note.id}/versions/-1`)).status).toBe(400);
-  const restored = await call(`/notes/${note.id}/restore`, "POST", { origin: "git-import", import_ix: 0 });
+  const beforeRestore = await store.getNote(note.id);
+  const missingStamp = await call(`/notes/${note.id}/restore`, "POST", { origin: "git-import", import_ix: 0 });
+  expect(missingStamp.status).toBe(428);
+  expect(await store.getNote(note.id)).toEqual(beforeRestore);
+  const restored = await call(`/notes/${note.id}/restore`, "POST", { origin: "git-import", import_ix: 0, if_updated_at: beforeRestore!.updatedAt });
   expect(restored.status).toBe(200);
   expect(restored.body.restored_from).toEqual({ origin: "git-import", import_ix: 0 });
   expect((await store.getNote(note.id))!.content).toBe("archive");

package/src/history-import.test.ts

@@ -1,6 +1,6 @@
-import { test, expect } from "bun:test";
+import { test, expect, spyOn } from "bun:test";
 import { createHash } from "node:crypto";
-import { Database } from "bun:sqlite";
+import { Database, SQLiteError } from "bun:sqlite";
 import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
@@ -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");
@@ -119,6 +206,38 @@ test("ambiguous sidecars quarantine both identities; malformed YAML diagnostics
   } finally { stage.close(); rmSync(dir, { recursive: true, force: true }); }
 });
 
+for (const format of ["inline", "sidecar"] as const) for (const cache of ["object_cache", "parsed_cache"] as const) {
+  test(`staging SQLite failure in ${format} ${cache} aborts without blaming source notes`, () => {
+    const dir = mkdtempSync(join(tmpdir(), "import-stage-failure-")), stage = new Database(":memory:");
+    const exec = stage.exec.bind(stage);
+    const setup = spyOn(stage, "exec").mockImplementation((sql) => {
+      const result = exec(sql);
+      if (sql.startsWith("CREATE TABLE selection_failures")) {
+        exec(`CREATE TRIGGER fail_cache BEFORE INSERT ON ${cache} BEGIN SELECT RAISE(ABORT, 'staging write failed'); END`);
+      }
+      return result;
+    });
+    try {
+      const repo = repoAt(join(dir, "repo"));
+      if (format === "inline") commit(repo, "valid body");
+      else {
+        mkdirSync(join(repo, ".parachute/notes-meta"), { recursive: true });
+        writeFileSync(join(repo, `.parachute/notes-meta/${noteId}.yaml`), `id: ${noteId}\npath: entry\nextension: json\n`);
+        writeFileSync(join(repo, "entry.json"), '{"valid":true}');
+        git(repo, "add", "."); git(repo, "commit", "-m", "valid sidecar");
+      }
+      let failure: unknown;
+      try { stageArchive(repo, git(repo, "rev-parse", "HEAD"), stage); }
+      catch (error) { failure = error; }
+      expect(failure).toBeInstanceOf(SQLiteError);
+      expect((failure as Error).message).toContain("staging write failed");
+      expect(stage.query("SELECT * FROM issues").all()).toEqual([]);
+      expect(stage.query("SELECT * FROM quarantine").all()).toEqual([]);
+      expect(stage.query("SELECT * FROM observations").all()).toEqual([]);
+    } finally { setup.mockRestore(); stage.close(); rmSync(dir, { recursive: true, force: true }); }
+  });
+}
+
 test("running daemon refuses prepare before creating a pause marker or backup", async () => {
   const dir = mkdtempSync(join(tmpdir(), "import-busy-")), saved = process.env.PARACHUTE_HOME;
   process.env.PARACHUTE_HOME = dir;