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

package/src/auto-transcribe.ts

@@ -1,247 +1,75 @@
-/**
- * Auto-transcribe trigger decision (vault#353, design 2026-05-21 Part 2).
- *
- * One pure function: given an attachment's mime-type + the operator's
- * settings + whether scribe is reachable, decide whether to enqueue the
- * attachment for the transcription worker. Lives in its own module so the
- * attachment-write code path (`routes.ts`) and the retry endpoint share the
- * same gate without duplicating logic.
- */
-
+/** Automatic uploads follow the selected, wired transcription worker (#751). */
 import { readGlobalConfig } from "./config.ts";
-import { getCachedScribeUrl } from "./scribe-discovery.ts";
 import { buildTranscriptionSnapshot } from "./transcription-routes.ts";
+import { getTranscriptionWorkerProvider } from "./transcription-registry.ts";
 
-/**
- * The name of a local provider that is INSTALLED on this box, or null.
- *
- * Delegates to the same snapshot `transcription status` and the admin SPA
- * answer from, so these surfaces share one implementation and cannot drift.
- *
- * Keyed on `binary.path`, deliberately, NOT on `snap.ready`. Readiness also
- * demands ffmpeg, so it varies box to box in a way this message shouldn't: a
- * machine with the provider installed but ffmpeg missing is still a machine
- * where "no transcription provider configured — set TRANSCRIPTION_PROVIDER to
- * a local provider" is false. `installed` answers the question the sentence
- * actually asks, and answers it the same way everywhere.
- * (Caught by running the real probe rather than the injected one — the unit
- * tests inject `localProviderImpl` and would never have shown the difference.)
- *
- * Errors swallow to null: a broken probe must degrade to the old, flat message,
- * never take down an attachment upload.
- */
-function installedLocalProvider(): string | null {
+type ProviderState = { ready: boolean; localProvider: string | null };
+function providerState(): ProviderState {
   try {
-    const snap = buildTranscriptionSnapshot();
-    if (snap.provider === "scribe-http") return null;
-    return snap.binary.path ? snap.provider : null;
+    const snapshot = buildTranscriptionSnapshot();
+    return {
+      ready: snapshot.active && snapshot.ready &&
+        getTranscriptionWorkerProvider() === snapshot.provider,
+      // The snapshot's binary field describes whisper.cpp tools, not every
+      // provider. Do not use it to claim a Python/transcribe-cpp install exists.
+      localProvider: snapshot.provider === "whisper-cpp" && snapshot.binary.path
+        ? snapshot.provider : null,
+    };
   } catch {
-    return null;
+    // A failed readiness probe must not break attachment upload.
+    return { ready: false, localProvider: null };
   }
 }
-
-/**
- * Pre-vault#353 callers passed `transcribe: true` explicitly on the
- * attachment POST. The auto-transcribe path inlines the decision: if the
- * upload is an audio mime-type AND the toggle is on AND scribe is reachable,
- * the worker is enqueued. This function is the single decision site.
- *
- * Returns `true` only when ALL three conditions hold:
- *   1. mime-type starts with `audio/` (case-insensitive).
- *   2. The resolved auto-transcribe toggle is not `false`. Resolution is
- *      **per-vault → global → true**:
- *        - `perVaultEnabled` (the owning vault's own `auto_transcribe.enabled`)
- *          wins when set — this is what makes scribe's "link to vault X" affect
- *          only X, not the whole server.
- *        - else the server-wide `globalConfig.auto_transcribe?.enabled`.
- *        - else `true` (default ON — once scribe is reachable, audio
- *          transcribes without a separate config step). Operators who want it
- *          OFF set `auto_transcribe.enabled: false` explicitly (per-vault or
- *          globally).
- *      `enabledOverride`, when present, hard-overrides the whole chain (used
- *      by the explicit caller-opt-in path).
- *   3. Scribe is discoverable (services.json entry OR SCRIBE_URL env).
- *
- * The three conditions are independent guards: a single `false` is sufficient
- * to skip enqueuing. The audio stays as a regular attachment in that case.
- */
-export function shouldAutoTranscribe(
-  mimeType: string,
-  opts: {
-    /** Injection seam for tests — defaults to live globals. */
-    readGlobalConfigImpl?: typeof readGlobalConfig;
-    getCachedScribeUrlImpl?: () => string | undefined;
-    /**
-     * The owning vault's per-vault `auto_transcribe.enabled` (vault.yaml).
-     * Takes precedence over the global toggle when set, so enabling/disabling
-     * one vault doesn't move the rest. `undefined` (the vault left it unset)
-     * falls through to the global toggle.
-     */
-    perVaultEnabled?: boolean;
-    /**
-     * Hard override of the entire per-vault→global→true chain. Used by the
-     * explicit caller-opt-in path; not part of the normal precedence ladder.
-     */
-    enabledOverride?: boolean;
-  } = {},
-): boolean {
-  if (typeof mimeType !== "string" || !mimeType.toLowerCase().startsWith("audio/")) {
-    return false;
-  }
-  return classifyAutoTranscribe(mimeType, opts).kind === "transcribe";
-}
-
-/**
- * Why an audio attachment is (or isn't) being transcribed. The three outcomes
- * are NOT interchangeable, which is the whole point of this type:
- *
- *   - `transcribe`  — enqueue it.
- *   - `disabled`    — the operator turned auto-transcribe off. Silence is
- *                     correct: they asked for nothing to happen.
- *   - `unavailable` — auto-transcribe is ON, but no provider is reachable.
- *                     This is a MISCONFIGURATION, and silence is wrong.
- *
- * vault#643: `shouldAutoTranscribe` collapsed the last two into `false`, so a
- * box with transcription enabled and no reachable provider accepted audio,
- * transcribed nothing, wrote no marker, logged nothing, and left an attachment
- * indistinguishable from a plain upload. Observed on a fresh install: the
- * provider resolves to `scribe-http` by default, nothing sets `SCRIBE_URL`, and
- * voice memos silently never transcribe.
- *
- * The hosted door already gets this right — `workers/vault/src/vault-do.ts`
- * marks a terminal state ("voice not enabled for this plan", "monthly voice
- * limit reached") rather than skipping quietly, precisely so the operator never
- * faces an eternal spinner. This brings self-host to the same posture.
- */
+type AutoTranscribeOptions = {
+  readGlobalConfigImpl?: typeof readGlobalConfig;
+  /** Test seam; production uses the registered worker and shared status probe. */
+  providerStateImpl?: () => ProviderState;
+  /** Per-vault → global → true; explicit caller overrides still win. */
+  perVaultEnabled?: boolean;
+  enabledOverride?: boolean;
+};
 export type AutoTranscribeDecision =
   | { kind: "transcribe" }
   | { kind: "not-audio" }
   | { kind: "disabled" }
-  /**
-   * `localProvider` names a local provider INSTALLED on this box (its binary
-   * resolves), or null when there is nothing local here.
-   *
-   * Installation, deliberately, and not the configured provider NAME. The name
-   * is a trap: `resolveTranscriptionProviderName` returns `whisper-cpp` on a
-   * box where nothing at all is set up, because that is the default when no
-   * scribe URL resolves. Keying the message off the name would tell a
-   * fresh-install operator their whisper-cpp install is present when they have
-   * never installed one — trading one false sentence for another.
-   *
-   * It does NOT change the decision: `unavailable` is `unavailable` either way,
-   * because this path resolves a scribe URL and nothing else. It exists purely
-   * so the error can be true. See `noProviderErrorFor`.
-   */
   | { kind: "unavailable"; localProvider: string | null };
 
-/** The full decision behind `shouldAutoTranscribe`. Same inputs, more answer. */
 export function classifyAutoTranscribe(
   mimeType: string,
-  opts: {
-    readGlobalConfigImpl?: typeof readGlobalConfig;
-    getCachedScribeUrlImpl?: () => string | undefined;
-    perVaultEnabled?: boolean;
-    enabledOverride?: boolean;
-    /**
-     * Injectable, same shape as the two impls above. Returns the name of a
-     * local provider installed here, or null. Defaults to the shared
-     * transcription snapshot.
-     */
-    localProviderImpl?: () => string | null;
-  } = {},
+  opts: AutoTranscribeOptions = {},
 ): AutoTranscribeDecision {
   if (typeof mimeType !== "string" || !mimeType.toLowerCase().startsWith("audio/")) {
     return { kind: "not-audio" };
   }
-  const enabled = opts.enabledOverride
-    ?? opts.perVaultEnabled
-    ?? (opts.readGlobalConfigImpl ?? readGlobalConfig)().auto_transcribe?.enabled
-    ?? true;
+  const enabled = opts.enabledOverride ?? opts.perVaultEnabled ??
+    (opts.readGlobalConfigImpl ?? readGlobalConfig)().auto_transcribe?.enabled ?? true;
   if (!enabled) return { kind: "disabled" };
-  const url = (opts.getCachedScribeUrlImpl ?? getCachedScribeUrl)();
-  if (!url || !url.trim()) {
-    // Still unavailable — this path reads a scribe URL and nothing else, and
-    // that is deliberately unchanged here. We only ask whether something local
-    // would run, so the message can name the real situation instead of telling
-    // an operator to do what they have already done.
-    return {
-      kind: "unavailable",
-      localProvider: (opts.localProviderImpl ?? installedLocalProvider)(),
-    };
-  }
-  return { kind: "transcribe" };
+  const state = (opts.providerStateImpl ?? providerState)();
+  return state.ready
+    ? { kind: "transcribe" }
+    : { kind: "unavailable", localProvider: state.localProvider };
+}
+export function shouldAutoTranscribe(mimeType: string, opts: AutoTranscribeOptions = {}): boolean {
+  return classifyAutoTranscribe(mimeType, opts).kind === "transcribe";
 }
-
-/**
- * The `transcribe_error` written when auto-transcribe is on but no provider is
- * reachable AND nothing local is configured. Deliberately actionable — the
- * operator needs to know which of the two things to do, not just that something
- * went wrong.
- *
- * Correct only when the resolved provider is `scribe-http`. On a box that HAS a
- * local provider this sentence is false in the most expensive way — see
- * `noProviderErrorFor`.
- */
 export const NO_PROVIDER_ERROR =
-  "no transcription provider configured — set TRANSCRIPTION_PROVIDER to a local " +
-  "provider (see `parachute-vault transcription install`), or point SCRIBE_URL at " +
-  "a transcription service";
-
-/**
- * The `transcribe_error` for an `unavailable` decision, told truthfully.
- *
- * Found live: a box with `TRANSCRIPTION_PROVIDER=whisper-cpp`, `parakeet-cli` on
- * PATH, the model downloaded, and `[transcribe] worker started → whisper-cpp` in
- * the same boot was writing `NO_PROVIDER_ERROR` onto its attachments — telling
- * the operator to set the variable they had set and install the provider that
- * was already running. Same failure mode as the `transcription status` bug
- * (#643): a diagnostic that lies during the exact task it exists for, and this
- * one sends someone to re-download a 400 MB model to fix nothing.
- *
- * The asymmetry is real and worth naming in the message rather than hiding:
- * `server.ts` starts a local worker with no scribe URL anywhere in the branch,
- * but this path resolves ONLY a scribe URL. So a local provider genuinely does
- * serve explicit `transcribe: true` requests while genuinely being invisible
- * here. An operator who is not told that will reasonably conclude their install
- * is broken.
- *
- * Deliberately NOT a fix for the asymmetry itself — teaching this path to see
- * local providers changes what gets transcribed, which is a behaviour question
- * and not this diff's to answer.
- */
+  "no transcription provider configured or ready — check `parachute-vault transcription status` " +
+  "and TRANSCRIPTION_PROVIDER. For local transcription use `parachute-vault transcription install`. " +
+  "For an explicitly selected legacy remote provider, check its SCRIBE_URL and worker status. " +
+  "The standalone Scribe service is retired.";
 export function noProviderErrorFor(localProvider: string | null): string {
   if (!localProvider) return NO_PROVIDER_ERROR;
-  return (
-    `auto-transcribe found no reachable provider: it resolves only a scribe URL ` +
-    `(SCRIBE_URL, or a \`parachute-scribe\` entry in services.json), and neither is set. ` +
-    `A local ${localProvider} install IS present here and explicit transcription requests ` +
-    `are routed to it — this path does not consult it. Reinstalling ${localProvider} will ` +
-    `not change this. To auto-transcribe uploads, point SCRIBE_URL at a transcription ` +
-    `service; otherwise request transcription explicitly on the attachment. ` +
-    `\`parachute-vault transcription status\` reports the local install's own state.`
-  );
+  return `auto-transcribe is unavailable: a local ${localProvider} binary is installed, ` +
+    "but the selected worker is not active and ready. Check `parachute-vault transcription status` " +
+    "for missing model/runtime dependencies or a required server restart. " +
+    "A binary alone does not establish readiness; reinstalling it is not necessarily the fix.";
 }
-
-/** Throttle for {@link warnNoTranscriptionProvider}. */
 const NO_PROVIDER_WARN_INTERVAL_MS = 60_000;
 let lastNoProviderWarnAt = 0;
-
-/**
- * Warn (at most once a minute) that audio is arriving with nowhere to send it.
- *
- * Throttled because it fires per-upload: a bulk import of a hundred voice
- * memos should produce one actionable line, not a hundred. Silence was the old
- * behaviour and it is what made this invisible — a box can accept audio for
- * months and never say that transcription isn't wired up.
- */
 export function warnNoTranscriptionProvider(now: () => number = Date.now): void {
   const t = now();
   if (t - lastNoProviderWarnAt < NO_PROVIDER_WARN_INTERVAL_MS) return;
   lastNoProviderWarnAt = t;
-  console.warn(`[transcribe] audio attachment accepted but ${NO_PROVIDER_ERROR}.`);
-}
-
-/** Test seam: forget the throttle window. */
-export function _resetNoProviderWarnForTest(): void {
-  lastNoProviderWarnAt = 0;
+  console.warn(`[transcribe] audio attachment accepted but ${NO_PROVIDER_ERROR}`);
 }
+export function _resetNoProviderWarnForTest(): void { lastNoProviderWarnAt = 0; }

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 });
+  }
+});

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);
+});