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

package/README.md

@@ -992,3 +992,7 @@ wizard, `parachute init --vault-name <name>`, or `parachute-vault create
 ## License
 
 AGPL-3.0
+
+### Importing legacy git history
+
+`parachute-vault history-import plan` reports a local mirror archive's recoverable history and retention effects. The offline `prepare`, `apply`, and `retire` commands import it without rewriting live notes, preserve the static archive, and prevent retired mirrors from restarting. See [the cutover and recovery procedure](UPGRADING.md#git-history-import-schema-v30--v31). Audited duplicate trees can use explicit `--selections` on plan/prepare; apply uses the embedded manifest, and unresolved notes stay quarantined. Nothing imports or retires automatically on upgrade.

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

@@ -0,0 +1,82 @@
+import { test, expect } from "bun:test";
+import { Database } from "bun:sqlite";
+import { SqliteStore } from "./store.js";
+import { resolveHistoryPolicy, eraseHistory, getVersion } from "./history.js";
+import { applyImportedNote, beginImportRun, importTargetDigest, getImportedVersion, importStorageIndex, type ImportedObservation } from "./history-import.js";
+
+const run = { run_id: "manifest", source_fingerprint: "source", tip: "tip", options_digest: "options" };
+const rows: ImportedObservation[] = ["older", "newer"].map(content => ({ content, path: "history", metadata: {}, extension: "md", created_at: null, observed_at: "2026-01-01T00:00:00Z", commit: content, blob: content }));
+async function fixture() {
+  const db = new Database(":memory:");
+  const store = new SqliteStore(db);
+  const note = await store.createNote("live", { path: "history" });
+  beginImportRun(db, run);
+  const opts = { run, noteId: note.id, observations: rows, policy: resolveHistoryPolicy({ min_versions: 20 }), now: Date.parse("2026-01-02T00:00:00Z"), targetDigest: importTargetDigest(db, note.id) };
+  return { db, store, note, opts };
+}
+test("import preserves live state and native allocation; refs survive erase without resurrection", async () => {
+  const { db, store, note, opts } = await fixture();
+  try {
+    const result = applyImportedNote(db, opts);
+    expect(result.receipt.retained_count).toBe(2);
+    expect(getImportedVersion(db, note.id, 0)?.content).toBe("newer");
+    expect(getImportedVersion(db, note.id, 1)?.content).toBe("older");
+    expect((await store.getNote(note.id))?.content).toBe("live");
+    await store.updateNote(note.id, { content: "native" });
+    expect(getVersion(db, note.id, 0)?.content).toBe("live");
+    eraseHistory(db, note.id);
+    expect(applyImportedNote(db, opts).skipped).toBe(true);
+    expect(getImportedVersion(db, note.id, 0)).toBeNull();
+    expect(db.query("SELECT count(*) n FROM note_versions").get()).toEqual({ n: 0 });
+    expect(() => applyImportedNote(db, { ...opts, run: { ...run, run_id: "different" } })).toThrow("already owned");
+  } finally { db.close(); }
+});
+test("failed native-drop projection rolls back blobs, references and receipt", async () => {
+  const { db, opts } = await fixture();
+  try {
+    expect(() => applyImportedNote(db, { ...opts, expectedNativeDrops: [123] })).toThrow("deletion set");
+    for (const table of ["history_import_receipts", "history_import_refs", "note_versions", "note_blobs"]) expect(db.query(`SELECT count(*) n FROM ${table}`).get()).toEqual({ n: 0 });
+  } finally { db.close(); }
+});
+test("stale target and oversized note cannot leave a partial import", async () => {
+  const { db, store, note, opts } = await fixture();
+  try {
+    await store.updateNote(note.id, { content: "changed" });
+    expect(() => applyImportedNote(db, opts)).toThrow("Stale");
+    expect(() => applyImportedNote(db, { ...opts, targetDigest: importTargetDigest(db, note.id), observations: [...rows, { ...rows[0]!, content: "x".repeat(2_000_001) }] })).toThrow("Oversized");
+    expect(db.query("SELECT count(*) n FROM history_import_receipts").get()).toEqual({ n: 0 });
+    expect(db.query("SELECT count(*) n FROM note_versions WHERE version_ix<0").get()).toEqual({ n: 0 });
+  } finally { db.close(); }
+});
+test("import allocation rejects unsafe and negative public indices", () => {
+  expect(importStorageIndex(0)).toBe(-1);
+  for (const n of [-1, 0.5, Number.MAX_SAFE_INTEGER, Infinity, NaN]) expect(() => importStorageIndex(n)).toThrow();
+});
+
+test("native allocation starts at zero even when the newest import was removed", async () => {
+  const { db, store, note, opts } = await fixture();
+  try {
+    applyImportedNote(db, opts);
+    db.prepare("DELETE FROM note_versions WHERE note_id=? AND version_ix=-1").run(note.id);
+    await store.updateNote(note.id, { content: "native edit" });
+    expect(getVersion(db, note.id, 0)?.content).toBe("live");
+    expect(getImportedVersion(db, note.id, 1)?.content).toBe("older");
+  } finally { db.close(); }
+});
+
+test("import policy discloses native removals separately and honors disabled retention", async () => {
+  const { db, store, note, opts } = await fixture();
+  try {
+    await store.updateNote(note.id, { content: "first native" });
+    await store.updateNote(note.id, { content: "second native" });
+    const result = applyImportedNote(db, { ...opts, targetDigest: importTargetDigest(db, note.id), policy: resolveHistoryPolicy({ min_versions: 1, max_versions: 1 }), expectedNativeDrops: [0] });
+    expect(result.nativeDrops).toEqual([0]);
+    expect(result.receipt.pruned_native).toBe(1);
+    expect(result.receipt.pruned_imported).toBe(2);
+    expect(getVersion(db, note.id, 1)?.content).toBe("first native");
+    expect((await store.getNote(note.id))?.content).toBe("second native");
+    const other = await store.createNote("other");
+    const disabled = applyImportedNote(db, { ...opts, noteId: other.id, targetDigest: importTargetDigest(db, other.id), policy: resolveHistoryPolicy({ enabled: false, min_versions: 0, max_versions: 1 }) });
+    expect(disabled.receipt.retained_count).toBe(2);
+  } finally { db.close(); }
+});

package/core/src/history-import.ts

@@ -0,0 +1,157 @@
+/** Git-independent import primitives. Callers own source parsing and offline access. */
+import type { Database } from "bun:sqlite";
+import { transaction } from "./txn.js";
+import { HistoryUnrecoverableError, hashContent, byteLength, VERSION_MAX_BYTES, pruneVersions, compactNote, getVersion, type HistoryPolicy, type VersionRow } from "./history.js";
+
+export interface ImportedObservation {
+  content: string;
+  path: string | null;
+  metadata: Record<string, unknown>;
+  extension: string;
+  created_at: string | null;
+  observed_at: string;
+  commit: string;
+  blob: string;
+}
+export interface ImportRun {
+  run_id: string;
+  source_fingerprint: string;
+  tip: string;
+  options_digest: string;
+}
+export interface ImportReceipt {
+  note_id: string;
+  run_id: string;
+  state_digest: string;
+  imported_count: number;
+  retained_count: number;
+  pruned_imported: number;
+  pruned_native: number;
+  completed_at: string;
+}
+export function canonicalJson(value: unknown): string {
+  function ordered(v: unknown): unknown {
+    if (Array.isArray(v)) return v.map(ordered);
+    if (v !== null && typeof v === "object") return Object.fromEntries(Object.entries(v).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([k, x]) => [k, ordered(x)]));
+    return v;
+  }
+  return JSON.stringify(ordered(value));
+}
+export function importStorageIndex(index: number): number {
+  const storage = -index - 1;
+  if (!Number.isSafeInteger(index) || index < 0 || !Number.isSafeInteger(storage)) throw new Error("Invalid import_ix");
+  return storage;
+}
+export function projectHistoryRow<T extends VersionRow>(row: T): T | (Omit<T, "version_ix"> & { origin: "git-import"; import_ix: number }) {
+  if (row.version_ix >= 0) return row;
+  const { version_ix, ...rest } = row;
+  return { ...rest, origin: "git-import", import_ix: -version_ix - 1 };
+}
+export function getImportedVersion(db: Database, id: string, index: number) {
+  const ix = importStorageIndex(index);
+  if (!db.prepare("SELECT 1 FROM history_import_refs WHERE note_id=? AND import_ix=?").get(id, index)) return null;
+  try {
+    const row = getVersion(db, id, ix);
+    return row?.op === "import" ? row : null;
+  } catch (error) {
+    if (error instanceof HistoryUnrecoverableError) throw new ImportedHistoryUnrecoverableError(id, index, error.reason);
+    throw error;
+  }
+}
+export function beginImportRun(db: Database, run: ImportRun): void {
+  transaction(db, () => {
+    const existing = db.prepare("SELECT run_id,source_fingerprint,tip,options_digest FROM history_import_runs WHERE run_id=?").get(run.run_id);
+    if (existing) {
+      if (canonicalJson(existing) !== canonicalJson(run)) throw new Error("Import run conflicts with its manifest");
+      return;
+    }
+    db.prepare("INSERT INTO history_import_runs VALUES(?,?,?,?, 'applying', ?)").run(run.run_id, run.source_fingerprint, run.tip, run.options_digest, new Date().toISOString());
+  });
+}
+export function readImportReceipt(db: Database, id: string): ImportReceipt | null {
+  return db.prepare("SELECT * FROM history_import_receipts WHERE note_id=?").get(id) as ImportReceipt | null;
+}
+/** Content-addressed global blob changes are excluded from the per-note state fingerprint. */
+export function importTargetDigest(db: Database, id: string): string {
+  return hashContent(canonicalJson({
+    note: db.prepare("SELECT id,content,path,metadata,extension,created_at,updated_at FROM notes WHERE id=?").get(id),
+    versions: db.prepare("SELECT * FROM note_versions WHERE note_id=? ORDER BY version_ix").all(id),
+  }));
+}
+export function importObservationDigest(rows: ImportedObservation[]): string {
+  return hashContent(canonicalJson(rows));
+}
+export function applyImportedNote(db: Database, opts: {
+  run: ImportRun; noteId: string; observations: ImportedObservation[];
+  policy: HistoryPolicy; now: number; targetDigest: string;
+  expectedNativeDrops?: number[];
+}): { receipt: ImportReceipt; nativeDrops: number[]; skipped: boolean } {
+  return transaction(db, () => {
+    const prior = readImportReceipt(db, opts.noteId);
+    const digest = importObservationDigest(opts.observations);
+    if (prior) {
+      if (prior.run_id !== opts.run.run_id || prior.state_digest !== digest) throw new Error("Note already owned by another import; resume its original manifest");
+      return { receipt: prior, nativeDrops: [], skipped: true };
+    }
+    if (!db.prepare("SELECT 1 FROM notes WHERE id=?").get(opts.noteId)) throw new Error("Import requires a live note");
+    if (importTargetDigest(db, opts.noteId) !== opts.targetDigest) throw new Error("Stale import manifest: target note changed");
+    if (!opts.observations.length) throw new Error("Cannot receipt an empty import");
+    if (db.prepare("SELECT 1 FROM note_versions WHERE note_id=? AND version_ix<0").get(opts.noteId)) throw new Error("Unreceipted imported history exists");
+    const nativeBefore = db.prepare("SELECT version_ix FROM note_versions WHERE note_id=? AND version_ix>=0 ORDER BY version_ix").all(opts.noteId) as { version_ix: number }[];
+    const receipt: ImportReceipt = { note_id: opts.noteId, run_id: opts.run.run_id, state_digest: digest, imported_count: opts.observations.length, retained_count: 0, pruned_imported: 0, pruned_native: 0, completed_at: new Date(opts.now).toISOString() };
+    db.prepare("INSERT INTO history_import_receipts VALUES(?,?,?,?,?,?,?,?)").run(receipt.note_id, receipt.run_id, receipt.state_digest, receipt.imported_count, 0, 0, 0, receipt.completed_at);
+    for (let i = 0; i < opts.observations.length; i++) {
+      const row = opts.observations[i]!;
+      const size = byteLength(row.content);
+      if (size > VERSION_MAX_BYTES) throw new Error("Oversized imported observation: quarantine the whole note");
+      const index = opts.observations.length - i - 1;
+      const storage = importStorageIndex(index);
+      const hash = hashContent(row.content);
+      db.prepare("INSERT OR IGNORE INTO note_blobs(hash,content,byte_size) VALUES(?,?,?)").run(hash, row.content, size);
+      db.prepare(`INSERT INTO note_versions(note_id,version_ix,content_hash,path,metadata,extension,superseded_at,actor,via,op,content_len,encoding,created_at)
+        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);
+    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++) {
+      const index = opts.observations.length - i - 1;
+      if (after.has(importStorageIndex(index)) && getImportedVersion(db, opts.noteId, index)?.content !== opts.observations[i]!.content) throw new Error("Imported content failed verification");
+    }
+    const nativeDrops = nativeBefore.map(r => r.version_ix).filter(ix => !after.has(ix));
+    if (opts.expectedNativeDrops && canonicalJson(nativeDrops) !== canonicalJson(opts.expectedNativeDrops)) throw new Error("Native deletion set differs from final manifest");
+    receipt.retained_count = [...after].filter(ix => ix < 0).length;
+    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);
+    return { receipt, nativeDrops, skipped: false };
+  });
+}
+
+/** Public import errors must not expose the negative storage key, even in prose. */
+export class ImportedHistoryUnrecoverableError extends Error {
+  readonly code = "HISTORY_UNRECOVERABLE";
+  readonly error_type = "history_unrecoverable";
+  readonly origin = "git-import";
+  constructor(readonly note_id: string, readonly import_ix: number, readonly reason: "overflow" | "delta_orphan") {
+    super(`Imported version content is unrecoverable: "${note_id}" import ${import_ix}`);
+    this.name = "ImportedHistoryUnrecoverableError";
+  }
+}
+export function parseHistorySelector(value: { version_ix?: unknown; origin?: unknown; import_ix?: unknown }):
+  { version_ix: number } | { origin: "git-import"; import_ix: number } | null {
+  const imported = value.origin !== undefined || value.import_ix !== undefined;
+  if (imported) {
+    if (value.version_ix !== undefined || value.origin !== "git-import" || typeof value.import_ix !== "number"
+      || !Number.isSafeInteger(value.import_ix) || value.import_ix < 0) throw invalidHistorySelector();
+    importStorageIndex(value.import_ix);
+    return { origin: "git-import", import_ix: value.import_ix };
+  }
+  if (value.version_ix === undefined) return null;
+  if (typeof value.version_ix !== "number" || !Number.isSafeInteger(value.version_ix) || value.version_ix < 0) throw invalidHistorySelector();
+  return { version_ix: value.version_ix };
+}
+function invalidHistorySelector() {
+  return Object.assign(new Error("Specify either a nonnegative version_ix or origin git-import with a nonnegative import_ix"), { error_type: "invalid_request", field: "versions" });
+}

package/core/src/history.ts

@@ -16,6 +16,7 @@ import { encodeDelta, decodeDelta } from "./delta.js";
 import { transaction } from "./txn.js";
 
 export type HistoryOp =
+  | "import"
   | "update"
   | "append"
   | "prepend"
@@ -162,7 +163,7 @@ function nextIndex(db: Database, noteId: string): number {
   return (
     db
       .prepare(
-        "SELECT COALESCE(MAX(version_ix), -1) + 1 AS ix FROM note_versions WHERE note_id = ?",
+        "SELECT COALESCE(MAX(version_ix), -1) + 1 AS ix FROM note_versions WHERE note_id = ? AND version_ix >= 0",
       )
       .get(noteId) as { ix: number }
   ).ix;
@@ -258,6 +259,7 @@ export function pruneVersions(
   db: Database,
   noteId: string,
   policy: HistoryPolicy,
+  now = Date.now(),
 ): { versionsDeleted: number; blobsDeleted: number } {
   const rows = db
     .prepare(
@@ -268,7 +270,7 @@ export function pruneVersions(
     "version_ix" | "superseded_at" | "op" | "content_hash"
   >[];
   const cutoff = new Date(
-    Date.now() - policy.max_age_days * 86_400_000,
+    now - policy.max_age_days * 86_400_000,
   ).toISOString();
   const doomed = rows.filter(
     (r, i) =>

package/core/src/mcp-manifest.ts

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

package/core/src/mcp.ts

@@ -1,3 +1,4 @@
+import { getImportedVersion, parseHistorySelector, projectHistoryRow } from "./history-import.js";
 import { Database } from "bun:sqlite";
 import type { Store, Note, QueryOpts, Attachment } from "./types.js";
 import { transactionAsync } from "./txn.js";
@@ -698,16 +699,22 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
               error_type: "invalid_query", field: "versions", hint: `drop ${key} when using versions`,
             });
           }
-          const v = params.versions as { note_id: string; version_ix?: number; limit?: number; offset?: number };
+          const v = params.versions as { note_id: string; version_ix?: number; origin?: unknown; import_ix?: unknown; limit?: number; offset?: number };
+          const selector = parseHistorySelector(v);
           const note = requireNote(db, requireNoteReference(v.note_id));
-          if (typeof v.version_ix === "number") {
-            const version = await store.getNoteVersion(note.id, v.version_ix);
+          if (selector && "import_ix" in selector) {
+            const version = getImportedVersion(db, note.id, selector.import_ix);
+            if (!version) return { error: "Imported version not found", error_type: "not_found", id: v.note_id, ...selector };
+            return projectHistoryRow(version);
+          }
+          if (selector && "version_ix" in selector) {
+            const version = await store.getNoteVersion(note.id, selector.version_ix);
             if (!version) return { error: `Version not found: "${v.note_id}"@${v.version_ix}`, error_type: "not_found", id: v.note_id, version_ix: v.version_ix };
             return version;
           }
           const versions = await store.listNoteVersions(note.id, { limit: Math.max(0, Math.min(v.limit ?? 50, 200)), offset: v.offset ?? 0 });
           const total = await store.countNoteVersions(note.id);
-          return { versions, total };
+          return { versions: versions.map(projectHistoryRow), total };
         }
 
         // --- Single note by ID/path ---

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: 30 });
+  ).toEqual({ version: 31 });
   const tables = db
     .prepare(
       "SELECT name FROM sqlite_master WHERE type='table' AND name IN ('note_versions','note_blobs') ORDER BY name",

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(30);
+    expect(SCHEMA_VERSION).toBe(31);
     expect(snap()).toEqual(before);
     expect(db.prepare("SELECT hash FROM note_blobs WHERE delta_of IS NOT NULL OR encoding IS NOT NULL").all()).toEqual([]);
     expect(db.prepare("SELECT note_id FROM note_versions WHERE created_at IS NOT NULL").all()).toEqual([]);

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

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

package/core/src/schema.ts

@@ -6,7 +6,7 @@ import { transaction } from "./txn.js";
 import { timestampToMs } from "./cursor.js";
 import { ensureRelationshipColumn } from "./wikilinks.js";
 
-export const SCHEMA_VERSION = 30;
+export const SCHEMA_VERSION = 31;
 
 /**
  * Deterministic last-resort epoch for a note whose `updated_at` AND
@@ -741,6 +741,7 @@ export function initSchema(db: Database): void {
   migrateToV29(db);
   // v30: depth-one history deltas and captured creation time, no backfill.
   migrateToV30(db);
+  migrateToV31(db);
 
   // Rebuild any generated columns + indexes declared in indexed_fields.
   // No-op for a fresh vault; idempotent on existing vaults.
@@ -2032,3 +2033,34 @@ function migrateFromV2(db: Database): void {
   // Re-enable FK checks
   db.exec("PRAGMA foreign_keys = ON");
 }
+
+/** Import receipts deliberately survive version retention and erasure. */
+function migrateToV31(db: Database): void {
+  transaction(db, () => db.exec(`
+    CREATE TABLE IF NOT EXISTS history_import_runs (
+      run_id TEXT PRIMARY KEY,
+      source_fingerprint TEXT NOT NULL,
+      tip TEXT NOT NULL,
+      options_digest TEXT NOT NULL,
+      status TEXT NOT NULL CHECK(status IN ('applying', 'complete')),
+      created_at TEXT NOT NULL
+    );
+    CREATE TABLE IF NOT EXISTS history_import_receipts (
+      note_id TEXT PRIMARY KEY,
+      run_id TEXT NOT NULL REFERENCES history_import_runs(run_id),
+      state_digest TEXT NOT NULL,
+      imported_count INTEGER NOT NULL,
+      retained_count INTEGER NOT NULL,
+      pruned_imported INTEGER NOT NULL,
+      pruned_native INTEGER NOT NULL,
+      completed_at TEXT NOT NULL
+    );
+    CREATE TABLE IF NOT EXISTS history_import_refs (
+      note_id TEXT NOT NULL REFERENCES history_import_receipts(note_id),
+      import_ix INTEGER NOT NULL CHECK(import_ix >= 0),
+      source_commit TEXT NOT NULL,
+      source_blob TEXT NOT NULL,
+      PRIMARY KEY(note_id, import_ix)
+    );
+  `));
+}

package/package.json

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

package/src/cli.ts

@@ -296,6 +296,11 @@ switch (command) {
   case "backup":
     await cmdBackup(cmdArgs);
     break;
+  case "history-import": {
+    const { runHistoryImport } = await import("./history-import.ts");
+    console.log(JSON.stringify(await runHistoryImport(cmdArgs), null, 2));
+    break;
+  }
   case "import":
     await cmdImport(cmdArgs);
     break;
@@ -4815,7 +4820,7 @@ async function createVault(
   // git-less box leaves the config written but inactive + logs an actionable
   // hint — it must NEVER fail the vault create. Create-time ONLY: existing
   // vaults are never retroactively migrated.
-  if (shouldEnableCreateTimeMirror(opts)) {
+  if (shouldEnableCreateTimeMirror(opts) && (await import("./mirror-config.ts")).readHistoryMirrorPhase(name) === "active") {
     const mirrorConfig = historyPresetMirrorConfig();
     writeMirrorConfigForVault(name, mirrorConfig);
     const mirrorPath = resolveMirrorPath(vaultDir(name), mirrorConfig);
@@ -5213,6 +5218,10 @@ Import/Export:
                                                        --git-push to push after commit)
 
 History:
+  parachute-vault history-import plan|prepare|apply|retire|cancel --vault <name>
+                                                       Import a local git archive into note history;
+                                                       plan/prepare: --selections <file> for audited duplicates;
+                                                       see UPGRADING.md for offline cutover and recovery.
   parachute-vault history [--vault <name>]             Show the vault's git write history (the
                                                        mirror is git-backed — one file per note,
                                                        so git log IS a tamper-evident history)

package/src/history-import-mcp.test.ts

@@ -0,0 +1,94 @@
+import { test, expect } from "bun:test";
+import { handleMcp } from "./mcp-http.ts";
+import type { McpToolDef } from "../core/src/mcp.ts";
+
+async function errorEnvelope(fields: Record<string, unknown>) {
+  const tool: McpToolDef = {
+    name: "query-notes", description: "serializer boundary fixture", requiredVerb: "read",
+    inputSchema: { type: "object" },
+    execute() { throw Object.assign(new Error("Unrecoverable history"), fields); },
+  };
+  const request = new Request("http://localhost/vault/import-test/mcp", {
+    method: "POST", headers: { "content-type": "application/json", accept: "application/json, text/event-stream" },
+    body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: tool.name, arguments: {} } }),
+  });
+  const response = await handleMcp(request, () => [tool], "import-test", "import-test", {
+    permission: "full", scopes: ["vault:import-test:read"], legacyDerived: false,
+    scoped_tags: null, vault_name: null, caller_jti: null, actor: "test", via: "api",
+  }, "");
+  return await response.json() as any;
+}
+test("HTTP MCP forwards valid imported history references only on the dedicated error branch", async () => {
+  const fields = { code: "HISTORY_UNRECOVERABLE", error_type: "history_unrecoverable", origin: "git-import", import_ix: 0, version_ix: -1 };
+  const rpc = await errorEnvelope(fields);
+  expect(rpc.result).toBeUndefined();
+  expect(rpc.error.code).toBe(-32602);
+  expect(rpc.error.data).toEqual({ error_type: "history_unrecoverable", origin: "git-import", import_ix: 0 });
+  for (const invalid of [-1, 1.5, Number.MAX_SAFE_INTEGER + 1, "0", null]) {
+    const bad = await errorEnvelope({ ...fields, import_ix: invalid });
+    expect(bad.result).toBeUndefined();
+    expect(bad.error.data).toEqual({ error_type: "history_unrecoverable" });
+  }
+  const generic = await errorEnvelope({ ...fields, code: "OTHER" });
+  expect(generic.error.data).toEqual({ error_type: "history_unrecoverable" });
+  const native = await errorEnvelope({ code: "HISTORY_UNRECOVERABLE", error_type: "history_unrecoverable", version_ix: 0, note_id: "note" });
+  expect(native.error.data).toEqual({ error_type: "history_unrecoverable" });
+});
+
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { writeVaultConfig } from "./config.ts";
+import { getVaultStore, clearVaultStoreCache } from "./vault-store.ts";
+import { generateScopedMcpTools } from "./mcp-tools.ts";
+import { applyImportedNote, beginImportRun, importTargetDigest } from "../core/src/history-import.ts";
+import { resolveHistoryPolicy } from "../core/src/history.ts";
+
+test("HTTP MCP imported get/list/error keeps discriminator and rejects mixed selectors", async () => {
+  const saved = process.env.PARACHUTE_HOME;
+  const dir = mkdtempSync(join(tmpdir(), "history-import-mcp-"));
+  process.env.PARACHUTE_HOME = dir;
+  try {
+    writeVaultConfig({ name: "import-test", api_keys: [], created_at: new Date().toISOString() });
+    const store = getVaultStore("import-test");
+    const note = await store.createNote("live");
+    const run = { run_id: "test", source_fingerprint: "source", tip: "tip", options_digest: "options" };
+    beginImportRun(store.db, run);
+    applyImportedNote(store.db, {
+      run, noteId: note.id, policy: resolveHistoryPolicy({ min_versions: 20 }), now: Date.now(),
+      targetDigest: importTargetDigest(store.db, note.id),
+      observations: [{ content: "archive", path: null, metadata: {}, extension: "md", created_at: null, observed_at: new Date().toISOString(), commit: "commit", blob: "blob" }],
+    });
+    const auth = { permission: "full" as const, scopes: ["vault:import-test:read"], legacyDerived: false, scoped_tags: null, vault_name: null, caller_jti: null, actor: "test", via: "api" };
+    async function call(selector: Record<string, unknown>) {
+      const req = new Request("http://localhost/vault/import-test/mcp", { method: "POST", headers: { "content-type": "application/json", accept: "application/json, text/event-stream" }, body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: "query-notes", arguments: { versions: { note_id: note.id, ...selector } } } }) });
+      return await (await handleMcp(req, () => generateScopedMcpTools("import-test", auth), "test", "import-test", auth, "")).json() as any;
+    }
+    const got = await call({ origin: "git-import", import_ix: 0 });
+    const row = JSON.parse(got.result.content[0].text);
+    expect(row.content).toBe("archive");
+    expect(row.origin).toBe("git-import");
+    expect(row.import_ix).toBe(0);
+    expect(row.version_ix).toBeUndefined();
+    const listed = JSON.parse((await call({})).result.content[0].text);
+    expect(listed.versions[0].origin).toBe("git-import");
+    for (const selector of [{ origin: "git-import" }, { import_ix: 0 }, { version_ix: 0, origin: "git-import", import_ix: 0 }, { version_ix: -1 }]) {
+      const invalid = await call(selector);
+      expect(invalid.error).toBeDefined();
+      expect(invalid.result).toBeUndefined();
+    }
+    store.db.exec("UPDATE note_blobs SET encoding='unknown'");
+    const broken = await call({ origin: "git-import", import_ix: 0 });
+    expect(broken.result).toBeUndefined();
+    expect(broken.error.data).toEqual({ error_type: "history_unrecoverable", origin: "git-import", import_ix: 0 });
+    expect(broken.error.message).not.toContain("@-1");
+    const scoped = generateScopedMcpTools("import-test", { ...auth, scoped_tags: ["journal"] }).find(t => t.name === "query-notes")!;
+    const denied = await scoped.execute({ versions: { note_id: note.id, origin: "git-import", import_ix: 0 } });
+    expect(denied).toEqual({ error: "Note not found", error_type: "not_found", id: note.id });
+
+  } finally {
+    clearVaultStoreCache();
+    if (saved === undefined) delete process.env.PARACHUTE_HOME; else process.env.PARACHUTE_HOME = saved;
+    rmSync(dir, { recursive: true, force: true });
+  }
+});