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

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

@@ -0,0 +1,91 @@
+import { test, expect, beforeEach, afterEach, spyOn } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { generateKeyPair, exportJWK, SignJWT } from "jose";
+import { handleMcp } from "./mcp-http.ts";
+import { route } from "./routing.ts";
+import { resetJwksCache, resetRevocationCache } from "./hub-jwt.ts";
+import { writeVaultConfig, readVaultConfig, vaultConfigPath } from "./config.ts";
+import { getVaultStore, clearVaultStoreCache } from "./vault-store.ts";
+import { generateScopedMcpTools } from "./mcp-tools.ts";
+import { BunSqliteStore } from "../core/src/store.ts";
+import * as history from "../core/src/history.ts";
+
+let taskDir: string, savedHome: string | undefined, savedOrigin: string | undefined, savedJwks: string | undefined, origin: string;
+let store: ReturnType<typeof getVaultStore>, server: ReturnType<typeof Bun.serve>, privateKey: CryptoKey;
+beforeEach(async () => {
+  savedHome = process.env.PARACHUTE_HOME;
+  savedOrigin = process.env.PARACHUTE_HUB_ORIGIN;
+  savedJwks = process.env.PARACHUTE_HUB_JWKS_ORIGIN;
+  taskDir = mkdtempSync(join(tmpdir(), "vault-compact-"));
+  process.env.PARACHUTE_HOME = taskDir;
+  writeVaultConfig({ name: "compact", api_keys: [], created_at: new Date().toISOString() });
+  store = getVaultStore("compact");
+  const keys = await generateKeyPair("RS256", { extractable: true });
+  privateKey = keys.privateKey;
+  const jwk = await exportJWK(keys.publicKey);
+  server = Bun.serve({ port: 0, fetch(req) { return new URL(req.url).pathname === "/.well-known/jwks.json" ? Response.json({ keys: [{ ...jwk, kid: "compact-test", alg: "RS256", use: "sig" }] }) : Response.json({ generated_at: new Date().toISOString(), jtis: [] }); } });
+  origin = `http://127.0.0.1:${server.port}`;
+  process.env.PARACHUTE_HUB_ORIGIN = origin;
+  process.env.PARACHUTE_HUB_JWKS_ORIGIN = origin;
+  resetJwksCache();
+  resetRevocationCache();
+});
+afterEach(() => { server.stop(true); clearVaultStoreCache(); rmSync(taskDir, { recursive: true, force: true }); for (const [key, value] of [["PARACHUTE_HOME", savedHome], ["PARACHUTE_HUB_ORIGIN", savedOrigin], ["PARACHUTE_HUB_JWKS_ORIGIN", savedJwks]] as const) {
+  if (value === undefined)
+    delete process.env[key];
+  else
+    process.env[key] = value;
+} resetJwksCache(); resetRevocationCache(); });
+async function call(path: string, method = "GET", body?: unknown, verb = "admin", scoped = false) {
+  const token = await new SignJWT({ scope: `vault:compact:${verb}`, client_id: "compact-test", ...(scoped ? { permissions: { scoped_tags: ["journal"] } } : {}) }).setProtectedHeader({ alg: "RS256", kid: "compact-test" }).setIssuer(origin).setSubject("tester").setAudience("vault.compact").setIssuedAt().setExpirationTime("5m").setJti(crypto.randomUUID()).sign(privateKey);
+  const full = `/vault/compact/api${path}`, response = await route(new Request(`http://localhost${full}`, { method, headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" }, ...(body === undefined ? {} : { body: JSON.stringify(body) }) }), new URL(`http://localhost${full}`).pathname);
+  return { status: response.status, body: await response.json() as any };
+}
+
+import { applyImportedNote, beginImportRun, importTargetDigest } from "../core/src/history-import.ts";
+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" });
+  const run = { run_id: "rest", source_fingerprint: "source", tip: "tip", options_digest: "options" };
+  beginImportRun(store.db, run);
+  applyImportedNote(store.db, { run, noteId: note.id, targetDigest: importTargetDigest(store.db, note.id), policy: history.resolveHistoryPolicy({ min_versions: 20 }), now: Date.now(), observations: [{ content: "archive", path: "old/path", metadata: { old: true }, extension: "md", created_at: null, observed_at: new Date().toISOString(), commit: "commit", blob: "blob" }] });
+  for (const ref of [note.id, encodeURIComponent("folder/imported")]) {
+    const got = await call(`/notes/${ref}/imports/0`);
+    expect(got.status).toBe(200);
+    expect(got.body.content).toBe("archive");
+    expect(got.body.origin).toBe("git-import");
+    expect(got.body.import_ix).toBe(0);
+    expect(got.body.version_ix).toBeUndefined();
+  }
+  const native = await call(`/notes/${note.id}/versions/0`);
+  expect(native.body.version_ix).toBe(0);
+  expect(native.body.origin).toBeUndefined();
+  const list = await call(`/notes/${note.id}/versions`);
+  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 });
+  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");
+  expect((await store.getNote(note.id))!.path).toBe("folder/imported");
+  const missing = await call(`/notes/${note.id}/imports/99`);
+  expect(missing.status).toBe(404);
+  expect(missing.body).toMatchObject({ origin: "git-import", import_ix: 99 });
+  await store.deleteNote(note.id);
+  const recreated = await call(`/notes/${note.id}/restore`, "POST", { origin: "git-import", import_ix: 0 });
+  expect(recreated.status).toBe(200);
+  expect(recreated.body.recreated).toBe(true);
+  expect((await store.getNote(note.id))!.content).toBe("archive");
+  const hash = store.db.query("SELECT content_hash FROM note_versions WHERE note_id=? AND version_ix=-1").get(note.id) as { content_hash: string };
+  store.db.query("UPDATE note_blobs SET encoding='unknown' WHERE hash=?").run(hash.content_hash);
+  const broken = await call(`/notes/${note.id}/imports/0`);
+  expect(broken.status).toBe(409);
+  expect(broken.body).toMatchObject({ origin: "git-import", import_ix: 0, error_type: "history_unrecoverable" });
+  expect(JSON.stringify(broken.body)).not.toContain("version_ix");
+  expect(JSON.stringify(broken.body)).not.toContain("@-1");
+  const privateNote = await store.createNote("private", { tags: ["secret"] });
+  expect((await call(`/notes/${privateNote.id}/imports/0`, "GET", undefined, "read", true)).status).toBe(404);
+});

package/src/history-import.test.ts

@@ -0,0 +1,318 @@
+import { test, expect } from "bun:test";
+import { createHash } from "node:crypto";
+import { Database } from "bun:sqlite";
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { spawnSync } from "node:child_process";
+import { stageArchive, runHistoryImport, type ImportManifest, normalizeHistorySelections, type HistorySelections } from "./history-import.ts";
+import { writeVaultConfig, writeGlobalConfig, vaultDbPath } from "./config.ts";
+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";
+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();
+}
+function repoAt(dir: string) { mkdirSync(dir); git(dir, "init", "-b", "main"); return dir; }
+function commit(dir: string, content: string, id = noteId, path = "entry.md") {
+  writeFileSync(join(dir, path), `---\nid: ${id}\npath: entry\ncreated_at: 2026-01-01T00:00:00Z\n---\n${content}`);
+  git(dir, "add", "."); git(dir, "commit", "-m", "observation"); return git(dir, "rev-parse", "HEAD");
+}
+test("git staging preserves exported CRLF bodies and A-B-A while quarantining duplicate IDs", () => {
+  const dir = mkdtempSync(join(tmpdir(), "import-stage-"));
+  const db = new Database(":memory:");
+  try {
+    const repo = repoAt(join(dir, "repo"));
+    commit(repo, "A\r\n"); commit(repo, "B\r\n"); const tip = commit(repo, "A\r\n");
+    const result = stageArchive(repo, tip, db);
+    expect(result.commits).toBe(3);
+    const rows = db.query("SELECT row_json FROM observations ORDER BY seq").all() as { row_json: string }[];
+    expect(rows.map(r => JSON.parse(r.row_json).content)).toEqual(["A\r\n", "B\r\n", "A\r\n"]);
+    const duplicate = commit(repo, "different", noteId, "duplicate.md");
+    const second = new Database(":memory:");
+    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("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");
+  try {
+    // Reserve then release a random loopback port so the guard cannot hit production.
+    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 store = getVaultStore("test"); const note = await store.createNote("native"); clearVaultStoreCache();
+    const repo = repoAt(join(dir, "repo")); commit(repo, "old", note.id); const tip = commit(repo, "recent", note.id);
+    const diagnostic = join(dir, "plan.json"), manifest = join(dir, "final.json"), archive = join(dir, "archive.bundle");
+    const oldSchema = new Database(vaultDbPath("test"));
+    oldSchema.exec("DROP TABLE history_import_refs; DROP TABLE history_import_receipts; DROP TABLE history_import_runs; UPDATE schema_version SET version=30");
+    oldSchema.close();
+    const before = readFileSync(vaultDbPath("test"));
+    await runHistoryImport(["plan", "--vault", "test", "--source", repo, "--through", tip, "--output", diagnostic]);
+    expect(readFileSync(vaultDbPath("test"))).toEqual(before);
+    await runHistoryImport(["prepare", "--vault", "test", "--source", repo, "--through", tip, "--archive", archive, "--output", manifest]);
+    expect(readHistoryMirrorPhase("test")).toBe("paused");
+    expect(() => getVaultStore("test")).toThrow("paused");
+    expect(readFileSync(mirrorConfigPath("test"), "utf8")).toContain("enabled: false");
+    const m = JSON.parse(readFileSync(manifest, "utf8")) as ImportManifest;
+    expect(m.notes).toHaveLength(1);
+    commit(repo, "changed after bundle", note.id);
+    const savedGitDir = process.env.GIT_DIR;
+    process.env.GIT_DIR = join(dir, "not-the-archive");
+    try { await runHistoryImport(["apply", "--vault", "test", "--manifest", manifest, "--archive", archive]); }
+    finally { if (savedGitDir === undefined) delete process.env.GIT_DIR; else process.env.GIT_DIR = savedGitDir; }
+    const db = new Database(vaultDbPath("test"));
+    try {
+      expect(getImportedVersion(db, note.id, 0)?.content).toBe("recent");
+      expect(db.query("SELECT content FROM notes WHERE id=?").get(note.id)).toEqual({ content: "native" });
+      db.exec("DELETE FROM note_versions");
+    } finally { db.close(); }
+    await runHistoryImport(["apply", "--vault", "test", "--manifest", manifest, "--archive", archive]);
+    const check = new Database(vaultDbPath("test"), { readonly: true });
+    try { expect(check.query("SELECT count(*) n FROM note_versions").get()).toEqual({ n: 0 }); } finally { check.close(); }
+    await expect(runHistoryImport(["cancel", "--vault", "test"])).rejects.toThrow("Receipts exist");
+    await runHistoryImport(["retire", "--vault", "test", "--manifest", manifest]);
+    expect(readHistoryMirrorPhase("test")).toBe("retired");
+    expect(await runHistoryImport(["retire", "--vault", "test", "--manifest", manifest])).toMatchObject({ retired: true });
+    expect(getVaultStore("test")).toBeDefined();
+  } finally { clearVaultStoreCache(); if (saved === undefined) delete process.env.PARACHUTE_HOME; else process.env.PARACHUTE_HOME = saved; rmSync(dir, { recursive: true, force: true }); }
+}, 30_000);
+
+for (const priorConfig of [null, "mirror:\n  enabled: true\n  location: internal\n"]) test(`prepare cancellation restores ${priorConfig === null ? "absent" : "present"} config and explicit active marker`, async () => {
+  const dir = mkdtempSync(join(tmpdir(), "import-cancel-")), 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 store = getVaultStore("test"), note = await store.createNote("native"); clearVaultStoreCache();
+    if (priorConfig !== null) writeFileSync(mirrorConfigPath("test"), priorConfig);
+    const repo = repoAt(join(dir, "repo")), tip = commit(repo, "old", note.id);
+    await runHistoryImport(["prepare", "--vault", "test", "--source", repo, "--through", tip, "--archive", join(dir, "archive.bundle"), "--output", join(dir, "final.json")]);
+    if (priorConfig === null) {
+      // Interrupted cancellation after restoring config/marker but before archiving its journal.
+      rmSync(mirrorConfigPath("test"));
+      writeFileSync(historyMirrorStatePath("test"), JSON.stringify({ phase: "active" }));
+    }
+    await runHistoryImport(["cancel", "--vault", "test"]);
+    if (priorConfig === null) expect(() => readFileSync(mirrorConfigPath("test"))).toThrow();
+    else expect(readFileSync(mirrorConfigPath("test"), "utf8")).toBe(priorConfig);
+    expect(JSON.parse(readFileSync(historyMirrorStatePath("test"), "utf8"))).toEqual({ phase: "active" });
+  } finally { clearVaultStoreCache(); if (saved === undefined) delete process.env.PARACHUTE_HOME; else process.env.PARACHUTE_HOME = saved; rmSync(dir, { recursive: true, force: true }); }
+});
+
+test("ambiguous sidecars quarantine both identities; malformed YAML diagnostics contain no source text", () => {
+  const dir = mkdtempSync(join(tmpdir(), "import-sidecar-")), stage = new Database(":memory:");
+  try {
+    const repo = repoAt(join(dir, "repo"));
+    mkdirSync(join(repo, ".parachute/notes-meta"), { recursive: true });
+    const other = "01M2KT4GXMQDNB8ZFXY05MHT6B";
+    for (const id of [noteId, other]) writeFileSync(join(repo, `.parachute/notes-meta/${id}.yaml`), `id: ${id}\npath: shared\nextension: json\n`);
+    writeFileSync(join(repo, "shared.json"), '{"value":1}');
+    writeFileSync(join(repo, "bad.md"), '---\nid: [PRIVATE_SENTINEL\n---\nbody');
+    git(repo, "add", "."); git(repo, "commit", "-m", "ambiguous");
+    stageArchive(repo, git(repo, "rev-parse", "HEAD"), stage);
+    expect(stage.query("SELECT note_id FROM quarantine ORDER BY note_id").all()).toEqual([noteId, other].sort().map(note_id => ({ note_id })));
+    expect(stage.query("SELECT * FROM observations").all()).toEqual([]);
+    expect(JSON.stringify(stage.query("SELECT * FROM issues").all())).not.toContain("PRIVATE_SENTINEL");
+  } finally { 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;
+  const server = Bun.serve({ port: 0, fetch: () => Response.json({ status: "ok" }) });
+  try {
+    writeGlobalConfig({ port: server.port! });
+    writeVaultConfig({ name: "test", api_keys: [], created_at: new Date().toISOString() });
+    await expect(runHistoryImport(["prepare", "--vault", "test"])).rejects.toThrow("Stop the vault daemon");
+    expect(() => readFileSync(historyMirrorStatePath("test"))).toThrow();
+  } finally { server.stop(true); if (saved === undefined) delete process.env.PARACHUTE_HOME; else process.env.PARACHUTE_HOME = saved; rmSync(dir, { recursive: true, force: true }); }
+});
+
+test("oversized revision quarantines its whole note while other identities remain staged", () => {
+  const dir = mkdtempSync(join(tmpdir(), "import-overflow-")), db = new Database(":memory:");
+  try {
+    const repo = repoAt(join(dir, "repo")); commit(repo, "small");
+    commit(repo, "x".repeat(2_000_001));
+    const other = "01M2KT4GXMQDNB8ZFXY05MHT6B", tip = commit(repo, "healthy", other, "healthy.md");
+    stageArchive(repo, tip, db);
+    expect(db.query("SELECT * FROM quarantine").all()).toEqual([{ note_id: noteId, reason: "oversized_body" }]);
+    expect(db.query("SELECT DISTINCT note_id FROM observations").all()).toEqual([{ note_id: other }]);
+  } finally { db.close(); rmSync(dir, { recursive: true, force: true }); }
+});
+
+test("first-parent import sees side-branch notes only in the merge tree", () => {
+  const dir = mkdtempSync(join(tmpdir(), "import-merge-")), db = new Database(":memory:");
+  try {
+    const repo = repoAt(join(dir, "repo")); commit(repo, "base");
+    git(repo, "checkout", "-b", "side");
+    const other = "01M2KT4GXMQDNB8ZFXY05MHT6B"; commit(repo, "side", other, "side.md");
+    git(repo, "checkout", "main"); commit(repo, "main");
+    git(repo, "merge", "--no-ff", "side", "-m", "merge result"); const tip = git(repo, "rev-parse", "HEAD");
+    expect(stageArchive(repo, tip, db).commits).toBe(3);
+    const side = db.query("SELECT row_json FROM observations WHERE note_id=?").get(other) as { row_json: string };
+    expect(JSON.parse(side.row_json).commit).toBe(tip);
+  } finally { db.close(); rmSync(dir, { recursive: true, force: true }); }
+});
+
+function selectionFile(repo: string, tip: string, entries: HistorySelections["selections"]): HistorySelections {
+  const walk = git(repo, "log", "--first-parent", "--reverse", "--format=%H %T", tip) + "\n";
+  return { format: 1, tip, source_fingerprint: createHash("sha256").update(walk).digest("hex"), selections: entries };
+}
+function pin(repo: string, commitId: string, path: string) { return { git_path: path, blob: git(repo, "rev-parse", `${commitId}:${path}`) }; }
+function selection(repo: string, commitId: string, selected: string, rejected: string, id = noteId): HistorySelections["selections"][number] {
+  return { note_id: id, commit: commitId, selected: pin(repo, commitId, selected), rejected: [{ ...pin(repo, commitId, rejected), reason: "Retained stale export" }], reason: "Reviewed explicit fixture path" };
+}
+function selectedStage(repo: string, tip: string, selectors?: HistorySelections) {
+  const db = new Database(":memory:");
+  try {
+    stageArchive(repo, tip, db, selectors);
+    return {
+      rows: (db.query("SELECT row_json FROM observations ORDER BY note_id,seq").all() as { row_json: string }[]).map(r => JSON.parse(r.row_json)),
+      quarantine: db.query("SELECT * FROM quarantine ORDER BY note_id").all(),
+      failures: db.query("SELECT * FROM selection_failures ORDER BY note_id,commit_id").all(),
+    };
+  } finally { db.close(); }
+}
+
+test("exact selections resolve duplicate trees regardless of Git path order; same bodies still require a selection", () => {
+  const dir = mkdtempSync(join(tmpdir(), "selection-order-"));
+  try {
+    for (const selectedFirst of [true, false]) {
+      const repo = repoAt(join(dir, String(selectedFirst))), oldPath = selectedFirst ? "z-old.md" : "a-old.md", newPath = selectedFirst ? "a-new.md" : "z-new.md";
+      commit(repo, "old", noteId, oldPath); const tip = commit(repo, "selected", noteId, newPath);
+      const selectors = selectionFile(repo, tip, [selection(repo, tip, newPath, oldPath)]);
+      expect(selectedStage(repo, tip).quarantine).toEqual([{ note_id: noteId, reason: "duplicate_id" }]);
+      const result = selectedStage(repo, tip, selectors);
+      expect(result.quarantine).toEqual([]); expect(result.rows.map(r => r.content)).toEqual(["old", "selected"]);
+      expect(result.rows[1].path).toBe("entry"); // Comes from frontmatter, not the Git path.
+    }
+    const repo = repoAt(join(dir, "same"));
+    commit(repo, "same", noteId, "old.md");
+    writeFileSync(join(repo, "new.md"), `---\nid: ${noteId}\npath: renamed\n---\nsame`);
+    git(repo, "add", "."); git(repo, "commit", "-m", "same body, new path"); const tip = git(repo, "rev-parse", "HEAD");
+    expect(selectedStage(repo, tip).quarantine).toHaveLength(1);
+    const result = selectedStage(repo, tip, selectionFile(repo, tip, [selection(repo, tip, "new.md", "old.md")]));
+    expect(result.rows.map(r => r.path)).toEqual(["entry", "renamed"]); expect(result.quarantine).toEqual([]);
+  } finally { rmSync(dir, { recursive: true, force: true }); }
+}, 30_000);
+
+test("stale selectors, candidate mismatches, rejected divergence and unlisted duplicate trees quarantine the whole note", () => {
+  const dir = mkdtempSync(join(tmpdir(), "selection-refusal-"));
+  try {
+    const repo = repoAt(join(dir, "repo")); const first = commit(repo, "old", noteId, "old.md"), tip = commit(repo, "new", noteId, "new.md");
+    const good = selectionFile(repo, tip, [selection(repo, tip, "new.md", "old.md")]);
+    const bad: HistorySelections[] = [];
+    for (const field of ["blob", "git_path"] as const) {
+      const copy = structuredClone(good); copy.selections[0]!.selected[field] = field === "blob" ? "0".repeat(40) : "absent.md"; bad.push(copy);
+      const rejected = structuredClone(good); rejected.selections[0]!.rejected[0]![field] = field === "blob" ? "0".repeat(40) : "absent.md"; bad.push(rejected);
+    }
+    const extra = structuredClone(good); extra.selections[0]!.rejected.push({ git_path: "third.md", blob: good.selections[0]!.selected.blob, reason: "Not present" }); bad.push(extra);
+    const singleton = structuredClone(good); singleton.selections.push({ ...selection(repo, tip, "old.md", "new.md"), commit: first }); bad.push(singleton);
+    const missing = structuredClone(good); missing.selections = []; bad.push(missing);
+    const absent = structuredClone(good); absent.selections[0]!.note_id = "01M2KT4GXMQDNB8ZFXY05MHT6B"; bad.push(absent);
+    for (const selectors of bad) {
+      const result = selectedStage(repo, tip, selectors);
+      expect(result.rows).toEqual([]); expect(result.quarantine).toContainEqual({ note_id: noteId, reason: "duplicate_id" }); expect(result.failures.length).toBeGreaterThan(0);
+    }
+    const changed = commit(repo, "rejected diverged", noteId, "old.md");
+    const divergent = selectionFile(repo, changed, [...good.selections, { ...good.selections[0]!, commit: changed }]);
+    expect(selectedStage(repo, changed, divergent).failures).toContainEqual({ note_id: noteId, commit_id: changed, reason: "candidate_set_mismatch" });
+    const third = commit(repo, "third candidate", noteId, "third.md");
+    const unlisted = selectionFile(repo, third, [...good.selections, selection(repo, changed, "new.md", "old.md")]);
+    expect(selectedStage(repo, third, unlisted).rows).toEqual([]);
+    expect(selectedStage(repo, third, { ...unlisted, selections: [...unlisted.selections, selection(repo, third, "new.md", "old.md")] }).failures).toContainEqual({ note_id: noteId, commit_id: third, reason: "candidate_set_mismatch" });
+    expect(() => selectedStage(repo, tip, { ...good, source_fingerprint: "0".repeat(64) })).toThrow("fingerprint");
+    expect(() => selectedStage(repo, tip, { ...good, tip: first })).toThrow("tip");
+    const foreign = structuredClone(good); foreign.selections[0]!.commit = "0".repeat(40);
+    expect(() => selectedStage(repo, tip, foreign)).toThrow("first-parent");
+  } finally { rmSync(dir, { recursive: true, force: true }); }
+}, 30_000);
+
+test("selections cannot clear ambiguous sidecars or oversized observations", () => {
+  const dir = mkdtempSync(join(tmpdir(), "selection-causes-"));
+  try {
+    const repo = repoAt(join(dir, "sidecars")), other = "01M2KT4GXMQDNB8ZFXY05MHT6B";
+    mkdirSync(join(repo, ".parachute/notes-meta"), { recursive: true });
+    for (const id of [noteId, other]) writeFileSync(join(repo, `.parachute/notes-meta/${id}.yaml`), `id: ${id}\npath: shared\nextension: json\n`);
+    writeFileSync(join(repo, "shared.json"), "{}"); const tip = commit(repo, "inline selected", noteId, "inline.md");
+    const item = selection(repo, tip, "inline.md", "shared.json");
+    item.rejected[0]!.sidecar = pin(repo, tip, `.parachute/notes-meta/${noteId}.yaml`);
+    const result = selectedStage(repo, tip, selectionFile(repo, tip, [item]));
+    expect(result.failures).toEqual([]); // The exact successful set matches; another cause remains authoritative.
+    expect(result.quarantine).toContainEqual({ note_id: noteId, reason: "ambiguous_sidecar" }); expect(result.rows).toEqual([]);
+    const large = repoAt(join(dir, "large")); commit(large, "x".repeat(2_000_001), noteId, "bad.md");
+    commit(large, "old", noteId, "old.md"); const end = commit(large, "new", noteId, "new.md");
+    const kept = selectedStage(large, end, selectionFile(large, end, [selection(large, end, "new.md", "old.md")]));
+    expect(kept.failures).toEqual([]); expect(kept.quarantine).toEqual([{ note_id: noteId, reason: "oversized_body" }]); expect(kept.rows).toEqual([]);
+  } finally { rmSync(dir, { recursive: true, force: true }); }
+}, 30_000);
+
+test("selection normalization rejects malformed pins and canonicalizes array order", () => {
+  const ref = { git_path: "a.md", blob: "a".repeat(40) }, other = { git_path: "b.md", blob: "b".repeat(40), reason: "kept" };
+  const input: HistorySelections = { format: 1, tip: "c".repeat(40), source_fingerprint: "d".repeat(64), selections: [{ note_id: noteId, commit: "c".repeat(40), selected: ref, rejected: [other, { ...other, git_path: "c.md" }], reason: "audit" }, { note_id: noteId, commit: "e".repeat(40), selected: ref, rejected: [other], reason: "audit" }] };
+  const reversed = structuredClone(input); reversed.selections.reverse(); for (const s of reversed.selections) s.rejected.reverse();
+  expect(normalizeHistorySelections(input)).toEqual(normalizeHistorySelections(reversed));
+  expect(() => normalizeHistorySelections({ ...input, body: "not permitted" })).toThrow();
+  expect(() => normalizeHistorySelections({ ...input, selections: [input.selections[0], input.selections[0]] })).toThrow("Duplicate selection");
+  expect(() => normalizeHistorySelections({ ...input, selections: [{ ...input.selections[0], reason: "" }] })).toThrow("reasons");
+  expect(() => normalizeHistorySelections({ ...input, selections: [{ ...input.selections[0], selected: { ...ref, git_path: "../a.md" } }] })).toThrow("reference");
+});
+
+test("partial selections block apply; complete selections are embedded and restage to the projected digest", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "selection-cutover-")), 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 store = getVaultStore("test"), a = await store.createNote("native A"), b = await store.createNote("native B"); clearVaultStoreCache();
+    const repo = repoAt(join(dir, "repo")); commit(repo, "a old", a.id, "a-old.md"); const t1 = commit(repo, "a new", a.id, "a-new.md");
+    const t2 = commit(repo, "b old", b.id, "b-old.md"), tip = commit(repo, "b new", b.id, "b-new.md");
+    const partial = selectionFile(repo, tip, [t1,t2,tip].map(c => selection(repo, c, "a-new.md", "a-old.md", a.id)));
+    const complete = selectionFile(repo, tip, [...partial.selections, selection(repo, tip, "b-new.md", "b-old.md", b.id)]);
+    const file = join(dir, "selections.json"); writeFileSync(file, JSON.stringify(partial));
+    for (const command of ["apply", "retire", "cancel"]) await expect(runHistoryImport([command, "--selections", file])).rejects.toThrow("only valid for plan/prepare");
+    const prepared = join(dir, "partial.json"), archive = join(dir, "partial.bundle");
+    const p = await runHistoryImport(["prepare", "--vault", "test", "--source", repo, "--through", tip, "--selections", file, "--archive", archive, "--output", prepared]) as ImportManifest;
+    expect(p.quarantined).toEqual([{ note_id: b.id, reason: "duplicate_id" }]);
+    await expect(runHistoryImport(["apply", "--vault", "test", "--manifest", prepared, "--archive", archive])).rejects.toThrow("Quarantined");
+    await runHistoryImport(["cancel", "--vault", "test"]);
+    writeFileSync(file, JSON.stringify(complete));
+    const finalPath = join(dir, "final.json"), bundle = join(dir, "final.bundle");
+    const final = await runHistoryImport(["prepare", "--vault", "test", "--source", repo, "--through", tip, "--selections", file, "--archive", bundle, "--output", finalPath]) as ImportManifest;
+    expect(final.quarantined).toEqual([]); expect(final.options_digest).not.toBe(p.options_digest); expect(final.selections_digest).not.toBe(p.selections_digest);
+    expect(final.selections).toEqual(normalizeHistorySelections(complete)); expect(final.notes).toHaveLength(2);
+    expect(final.notes.every(n => n.native_drops.length === 0)).toBe(true);
+    rmSync(file); // Apply cannot consult the original selectors file.
+    await runHistoryImport(["apply", "--vault", "test", "--manifest", finalPath, "--archive", bundle]);
+    const db = new Database(vaultDbPath("test"), { readonly: true });
+    try {
+      expect(getImportedVersion(db, a.id, 0)?.content).toBe("a new"); expect(getImportedVersion(db, b.id, 0)?.content).toBe("b new");
+      for (const note of final.notes) expect(db.query("SELECT state_digest FROM history_import_receipts WHERE note_id=?").get(note.id)).toEqual({ state_digest: note.state_digest });
+      expect(db.query("SELECT content FROM notes ORDER BY content").all()).toEqual([{ content: "native A" }, { content: "native B" }]);
+    } 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("valid sidecar candidate selection binds both content and metadata blobs", () => {
+  const dir = mkdtempSync(join(tmpdir(), "selection-sidecar-valid-"));
+  try {
+    const repo = repoAt(join(dir, "repo")); mkdirSync(join(repo, ".parachute/notes-meta"), { recursive: true });
+    for (const path of ["old", "new"]) {
+      writeFileSync(join(repo, `${path}.json`), JSON.stringify({ value: path }));
+      writeFileSync(join(repo, `.parachute/notes-meta/${path}.yaml`), `id: ${noteId}\npath: ${path}\nextension: json\n`);
+    }
+    git(repo, "add", "."); git(repo, "commit", "-m", "sidecar duplicates"); const tip = git(repo, "rev-parse", "HEAD");
+    const item = selection(repo, tip, "new.json", "old.json");
+    item.selected.sidecar = pin(repo, tip, ".parachute/notes-meta/new.yaml");
+    item.rejected[0]!.sidecar = pin(repo, tip, ".parachute/notes-meta/old.yaml");
+    const selectors = selectionFile(repo, tip, [item]), result = selectedStage(repo, tip, selectors);
+    expect(result.quarantine).toEqual([]); expect(result.rows).toHaveLength(1);
+    expect(result.rows[0]).toMatchObject({ path: "new", extension: "json", content: '{"value":"new"}' });
+    const stale = structuredClone(selectors); stale.selections[0]!.selected.sidecar!.blob = "0".repeat(40);
+    expect(selectedStage(repo, tip, stale).quarantine).toEqual([{ note_id: noteId, reason: "duplicate_id" }]);
+  } finally { rmSync(dir, { recursive: true, force: true }); }
+}, 30_000);