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

package/src/mirror-retirement.test.ts

@@ -0,0 +1,79 @@
+import { test, expect } from "bun:test";
+import { mkdirSync, writeFileSync, rmSync, existsSync } from "node:fs";
+import { dirname } from "node:path";
+import { historyMirrorStatePath, assertVaultNotPaused, assertMirrorActive, VaultImportPausedError, MirrorRetiredError } from "./mirror-config.ts";
+import { getVaultStore } from "./vault-store.ts";
+import { vaultDbPath } from "./config.ts";
+
+test("paused and malformed markers refuse before a DB is created; retired serves but cannot export", () => {
+  const name = `retirement-${crypto.randomUUID()}`;
+  const marker = historyMirrorStatePath(name);
+  mkdirSync(dirname(marker), { recursive: true });
+  try {
+    for (const raw of ['{"phase":"paused"}', '{', '{"phase":"other"}']) {
+      writeFileSync(marker, raw);
+      expect(() => getVaultStore(name)).toThrow(VaultImportPausedError);
+      expect(existsSync(vaultDbPath(name))).toBe(false);
+    }
+    writeFileSync(marker, '{"phase":"retired"}');
+    expect(() => assertVaultNotPaused(name)).not.toThrow();
+    expect(() => assertMirrorActive(name)).toThrow(MirrorRetiredError);
+    writeFileSync(marker, '{"phase":"active"}');
+    expect(() => assertMirrorActive(name)).not.toThrow();
+  } finally { rmSync(dirname(marker), { recursive: true, force: true }); }
+});
+
+import { mkdtempSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { tmpdir } from "node:os";
+import { writeVaultConfig, writeGlobalConfig } from "./config.ts";
+import { clearVaultStoreCache } from "./vault-store.ts";
+import { waitForHealthy } from "./health.ts";
+
+test("real four-vault boot isolates paused vault HTTP/MCP/subscribe before DB open", async () => {
+  const saved = process.env.PARACHUTE_HOME, home = mkdtempSync(join(tmpdir(), "import-paused-host-"));
+  process.env.PARACHUTE_HOME = home;
+  let child: ReturnType<typeof Bun.spawn> | undefined;
+  try {
+    const reserve = Bun.serve({ port: 0, fetch: () => new Response() }); const port = reserve.port!; reserve.stop(true);
+    writeGlobalConfig({ port, default_mirror: "off" });
+    for (const name of ["paused", "normal1", "normal2", "normal3"]) writeVaultConfig({ name, api_keys: [], created_at: new Date().toISOString() });
+    writeFileSync(historyMirrorStatePath("paused"), JSON.stringify({ phase: "paused" }));
+    child = Bun.spawn({ cmd: [process.execPath, resolve(import.meta.dir, "server.ts")], env: { ...process.env, PARACHUTE_HOME: home, PORT: String(port), PARACHUTE_VAULT_NAME: "", SCRIBE_URL: "" }, stdout: "ignore", stderr: "ignore" });
+    expect((await waitForHealthy(port, { totalMs: 15_000 })).status).toBe("healthy");
+    for (const path of ["api/notes", "mcp", "subscribe"]) {
+      const response = await fetch(`http://127.0.0.1:${port}/vault/paused/${path}`, { headers: path === "subscribe" ? { Upgrade: "websocket", Connection: "Upgrade" } : {} });
+      expect(response.status).toBe(503);
+      expect(await response.json()).toEqual({ error_type: "history_import_paused", message: "Vault history import is paused" });
+    }
+    expect(existsSync(vaultDbPath("paused"))).toBe(false);
+    for (const name of ["normal1", "normal2", "normal3"]) {
+      expect(existsSync(vaultDbPath(name))).toBe(true);
+      expect((await fetch(`http://127.0.0.1:${port}/vault/${name}/api/notes`)).status).not.toBe(503);
+    }
+  } finally {
+    if (child) { child.kill(); await child.exited; }
+    clearVaultStoreCache(); if (saved === undefined) delete process.env.PARACHUTE_HOME; else process.env.PARACHUTE_HOME = saved;
+    rmSync(home, { recursive: true, force: true });
+  }
+}, 25_000);
+
+import { MirrorManager } from "./mirror-manager.ts";
+import { defaultMirrorConfig } from "./mirror-config.ts";
+import { handleMirrorPut, enableSyncToImportedRepo } from "./mirror-routes.ts";
+test("retired manager refuses every export boundary and old-client enable without config writes", async () => {
+  const name = `retired-${crypto.randomUUID()}`, marker = historyMirrorStatePath(name);
+  mkdirSync(dirname(marker), { recursive: true }); writeFileSync(marker, '{"phase":"retired"}');
+  let writes = 0, exports = 0;
+  const config = { ...defaultMirrorConfig(), enabled: true };
+  const manager = new MirrorManager({ vaultName: name, runExport: async () => { exports++; return { notes: 0 }; }, firstChangedNoteTitle: async () => "", readMirrorConfig: () => config, writeMirrorConfig: () => { writes++; } });
+  try {
+    for (const call of [() => manager.start(), () => manager.reload(config), () => manager.runNow(), () => manager.pushNow()]) await expect(call()).rejects.toThrow(MirrorRetiredError);
+    const response = await handleMirrorPut(new Request("http://localhost/mirror", { method: "PUT", body: JSON.stringify(config) }), manager);
+    expect(response.status).toBe(409);
+    expect((await response.json() as any).error_type).toBe("mirror_retired");
+    expect(writes).toBe(0); expect(exports).toBe(0);
+    const sync = await enableSyncToImportedRepo({ vaultName: name, remoteUrl: "https://example.invalid/repo.git", auth: { kind: "none" }, manager });
+    expect(sync.sync_enabled).toBe(false);
+  } finally { manager.stop(); rmSync(dirname(marker), { recursive: true, force: true }); }
+});

package/src/mirror-routes.ts

@@ -1,3 +1,4 @@
+import { readHistoryMirrorPhase, assertMirrorActive, MirrorRetiredError, VaultImportPausedError } from "./mirror-config.ts";
 /**
  * HTTP surface for the mirror lifecycle.
  *
@@ -158,6 +159,10 @@ export async function handleMirrorPut(
   // to exercise the git_not_installed 503 path without uninstalling git.
   whichOverride?: (cmd: string) => string | null,
 ): Promise<Response> {
+  try { assertMirrorActive(manager.getVaultName()); } catch (error) {
+    if (error instanceof MirrorRetiredError || error instanceof VaultImportPausedError) return Response.json({ error_type: error.error_type, message: error.message }, { status: error.status });
+    throw error;
+  }
   let body: unknown;
   try {
     body = await req.json();
@@ -1067,7 +1072,7 @@ export async function handleAuthDelete(manager: MirrorManager): Promise<Response
   deleteCredentials(manager.getVaultName());
   // Strip origin from the mirror dir if one is set.
   const status = manager.getStatus();
-  if (status.mirror_path) {
+  if (status.mirror_path && readHistoryMirrorPhase(manager.getVaultName()) === "active") {
     try {
       await unsetGitRemote(status.mirror_path);
     } catch (err) {
@@ -1441,7 +1446,7 @@ export async function handleAuthGithubSelectRepo(
   // stored, and the URL will get applied next time the mirror starts.
   const status = manager.getStatus();
   let applied = false;
-  if (status.mirror_path) {
+  if (status.mirror_path && readHistoryMirrorPhase(manager.getVaultName()) === "active") {
     const res = await applyToGitRemote(status.mirror_path, authedUrl);
     if (!res.ok) {
       return Response.json(
@@ -1520,6 +1525,7 @@ async function maybeEnableHistoryOnLink(
   manager: MirrorManager,
 ): Promise<HistoryOnLink> {
   const vaultName = manager.getVaultName();
+  if (readHistoryMirrorPhase(vaultName) !== "active") return false;
   if (!existsSync(mirrorConfigPath(vaultName))) {
     try {
       const status = await manager.reload({
@@ -1567,6 +1573,7 @@ async function maybeEnableHistoryOnLink(
 async function maybeEnableAutoPush(
   manager: MirrorManager,
 ): Promise<{ was_already_enabled: boolean; auto_push_now_enabled: boolean }> {
+  if (readHistoryMirrorPhase(manager.getVaultName()) !== "active") return { was_already_enabled: false, auto_push_now_enabled: false };
   const config = manager.getConfig();
   // Don't muck with auto_push when the mirror is disabled — the operator
   // is configuring credentials before turning the mirror on, which is a
@@ -1607,6 +1614,7 @@ async function maybeFireInitialPush(
   | { fired: false; reason: "auto_push_disabled" | "no_mirror_path" | "manager_skipped" | "not_enabled" }
   | { fired: true; pushed: boolean; error?: string; sha?: string }
 > {
+  if (readHistoryMirrorPhase(manager.getVaultName()) !== "active") return { fired: false, reason: "not_enabled" };
   if (!autoPushEnabled) return { fired: false, reason: "auto_push_disabled" };
   const status = manager.getStatus();
   if (!status.mirror_path) return { fired: false, reason: "no_mirror_path" };
@@ -1638,6 +1646,7 @@ async function maybeFireInitialPush(
 export async function applyCredentialsToMirror(
   manager: MirrorManager,
 ): Promise<void> {
+  if (readHistoryMirrorPhase(manager.getVaultName()) !== "active") return;
   const status = manager.getStatus();
   if (!status.mirror_path) return;
   const creds = readCredentials(manager.getVaultName());
@@ -2211,6 +2220,7 @@ export async function enableSyncToImportedRepo(opts: {
   ) => Promise<{ ok: boolean; error?: string; heads?: string[] }>;
 }): Promise<{ sync_enabled: boolean; warning?: string }> {
   const { vaultName, remoteUrl, auth, manager, override = false, probeOverride } = opts;
+  if (readHistoryMirrorPhase(vaultName) !== "active") return { sync_enabled: false, warning: "History mirror is paused or retired; automatic sync cannot be enabled" };
   // Set when the unrelated-history probe couldn't reach the remote. Rides along
   // on a SUCCESSFUL arm — the operator gets Sync and the caveat, not neither.
   let historyUnverified = false;

package/src/routes.ts

@@ -1,3 +1,4 @@
+import { getImportedVersion, importStorageIndex, parseHistorySelector, projectHistoryRow, ImportedHistoryUnrecoverableError } from "../core/src/history-import.js";
 /**
  * REST API route handlers for the multi-vault server.
  *
@@ -11,6 +12,8 @@
  * and the Request, and returns a Response.
  */
 
+import { HistoryNotFoundError, latestTombstone } from "../core/src/history.js";
+import { ULID_REGEX } from "../core/src/ulid.js";
 import type { Database } from "bun:sqlite";
 import type { Store, Note, QueryOpts, AggregateSpec } from "../core/src/types.ts";
 import { TAG_EXPAND_MODES, stripTagHash, suggestSimilarTag, type TagExpandMode } from "../core/src/tag-hierarchy.ts";
@@ -180,6 +183,103 @@ export { assetsDir };
 // Helpers
 // ---------------------------------------------------------------------------
 
+function conflictResponse(e: any): Response | null {
+  if (e instanceof NotFoundError) return json({ error: e.message, error_type: "not_found" }, 404);
+  // Duck-type on `code` rather than `instanceof ConflictError`: this
+  // error originates in the core package and survives any future
+  // bundling / module-boundary split more robustly than a prototype check.
+  if (e && e.code === "CONFLICT") {
+    return json(
+      {
+        // New structured shape — what agents should key on.
+        error_type: "conflict",
+        current_updated_at: e.current_updated_at ?? null,
+        your_updated_at: e.expected_updated_at,
+        path: e.note_path ?? null,
+        note_id: e.note_id,
+        message: e.message,
+        hint: "re-read the note (GET) and re-apply your change against its current `updated_at`, or pass `force: true` to overwrite",
+        // Legacy fields — kept for the lens VaultConflictError shim and
+        // any other pre-launch callers. Safe to drop post-launch.
+        error: "conflict",
+        expected_updated_at: e.expected_updated_at,
+      },
+      409,
+    );
+  }
+  // State-transition compare-and-set conflict (vault#299 Part B). A
+  // DISTINCT error vocabulary from `conflict` (settled lead #3): the
+  // field VALUE didn't match `from`, not the updated_at token. 409.
+  if (e && e.code === "TRANSITION_CONFLICT") {
+    return json(
+      {
+        error_type: "transition_conflict",
+        error: "transition_conflict",
+        note_id: e.note_id,
+        path: e.note_path ?? null,
+        field: e.field,
+        expected_from: e.expected_from,
+        to: e.to,
+        current: e.current ?? null,
+        message: e.message,
+        hint: "re-read the note's current value for this field and retry the transition from its actual current state",
+      },
+      409,
+    );
+  }
+  // Strict-schema rejection (vault#299 Part A). One error carrying ALL
+  // per-field violations (settled lead #1). 422 Unprocessable Entity —
+  // the note exists / request is well-formed but violates the contract.
+  if (e && e.code === "SCHEMA_VALIDATION") {
+    return json(
+      {
+        error_type: "schema_validation",
+        error: "schema_validation",
+        violations: e.violations ?? [],
+        message: e.message,
+        hint: "fix every field listed in `violations` and retry — none of this write was applied",
+      },
+      422,
+    );
+  }
+  // Path-rename collision — schema's UNIQUE(path) tripped. Issue #126.
+  if (e && e.code === "PATH_CONFLICT") {
+    return json(
+      {
+        error_type: "path_conflict",
+        error: "path_conflict",
+        path: e.path,
+        message: e.message,
+        hint: "pass a different `path`, or omit it to leave the existing path unchanged",
+      },
+      409,
+    );
+  }
+  if (e && e.code === "INVALID_EXTENSION") {
+    return json(
+      { error_type: "invalid_extension", error: "invalid_extension", extension: e.extension, reason: e.reason, message: e.message },
+      400,
+    );
+  }
+  // Bad `path` value (vault#589 / FIX 2) — NUL byte or `..` segment.
+  if (e && e.code === "INVALID_PATH") {
+    return json(
+      { error_type: "invalid_path", error: "invalid_path", path: e.path, reason: e.reason, message: e.message },
+      400,
+    );
+  }
+  if (e && e.code === "HISTORY_NOT_FOUND") return json({ error: e.message, error_type: "not_found" }, 404);
+  if (e && e.code === "HISTORY_OVERFLOW") return json({
+    error_type: "history_overflow", note_id: e.note_id, byte_size: e.byte_size, limit: e.limit, message: e.message,
+    hint: "this note exceeds the 2 MB version-history ceiling, so it cannot be updated while history is enabled; delete it, or shrink it out-of-band, or disable history for this vault",
+  }, 413);
+  if (e && e.code === "HISTORY_UNRECOVERABLE") return json({
+    error_type: "history_unrecoverable", note_id: e.note_id, ...(e.origin === "git-import" ? { origin: e.origin, import_ix: e.import_ix } : { version_ix: e.version_ix }), message: e.message,
+    hint: e.reason === "delta_orphan" ? "this version's stored delta cannot be rebuilt — its base blob is missing or corrupt; run GET /api/doctor for the `history_delta_orphan` finding" : "this version is an overflow tombstone — the note's size and deletion were recorded but its content never was",
+  }, 409);
+  return null;
+}
+
 function json(data: unknown, status = 200): Response {
   return Response.json(data, { status });
 }
@@ -2823,6 +2923,93 @@ async function handleNotesInner(
     return handleRetryTranscription(store, note, vault);
   }
 
+  const verMatch = sub.match(/^\/versions\/([^/]+)$/);
+  const importMatch = sub.match(/^\/imports\/([^/]+)$/);
+  if (sub === "/versions" || verMatch || importMatch || sub === "/restore") {
+    const note = await resolveNote(store, idOrPath);
+    if (note && !noteWithinTagScope(note, tagScope.allowed, tagScope.raw)) {
+      return json({ error: "Not found", error_type: "not_found" }, 404);
+    }
+    if (!note && (tagScope.raw !== null || !ULID_REGEX.test(idOrPath) ||
+      !(await store.listNoteVersions(idOrPath, { limit: 1 })).length)) {
+      return json({ error: "Not found", error_type: "not_found" }, 404);
+    }
+    const id = note?.id ?? idOrPath;
+    if (sub === "/versions") {
+      if (method === "GET") {
+        const parsedLimit = Number.parseInt(url.searchParams.get("limit") ?? "50", 10);
+        const limit = Number.isNaN(parsedLimit) ? 50 : Math.min(200, Math.max(0, parsedLimit));
+        const offset = Math.max(0, Number.parseInt(url.searchParams.get("offset") ?? "0", 10) || 0);
+        const versions = await store.listNoteVersions(id, { limit, offset });
+        const total = await store.countNoteVersions(id);
+        return json({ versions: versions.map(projectHistoryRow), total });
+      }
+      if (method === "DELETE") {
+        const result = await store.eraseNoteHistory(id);
+        return json({ erased: true, id, versions_deleted: result.versionsDeleted, blobs_deleted: result.blobsDeleted });
+      }
+    } else if (importMatch && method === "GET") {
+      const index = Number(importMatch[1]);
+      if (!/^\d+$/.test(importMatch[1]!) || !Number.isSafeInteger(index) || index < 0) return json({ error: "Invalid import_ix", error_type: "invalid_request" }, 400);
+      try {
+        const version = getImportedVersion(db, id, index);
+        return version ? json(projectHistoryRow(version)) : json({ error: "Not found", error_type: "not_found", origin: "git-import", import_ix: index }, 404);
+      } catch (e) {
+        const response = conflictResponse(e);
+        if (response) return response;
+        throw e;
+      }
+    } else if (verMatch && method === "GET") {
+      const ix = Number(verMatch[1]);
+      if (!/^\d+$/.test(verMatch[1]!) || !Number.isInteger(ix) || ix < 0) return json({ error: "Invalid version_ix", error_type: "invalid_request" }, 400);
+      try {
+        const version = await store.getNoteVersion(id, ix);
+        return version ? json(version) : json({ error: "Not found", error_type: "not_found" }, 404);
+      } catch (e) {
+        const response = conflictResponse(e);
+        if (response) return response;
+        throw e;
+      }
+    } else if (sub === "/restore" && method === "POST") {
+      const parsed = await parseJsonBody(req);
+      if (!parsed.ok) return parsed.response;
+      const body = parsed.body;
+      let selector: ReturnType<typeof parseHistorySelector>;
+      try { selector = parseHistorySelector(body); } catch {
+        return json({ error: "Invalid history selector", error_type: "invalid_request" }, 400);
+      }
+      if (!selector) return json({ error: "History selector is required", error_type: "missing_required_field" }, 400);
+      const imported = "import_ix" in selector;
+      const storageIndex = "import_ix" in selector ? importStorageIndex(selector.import_ix) : selector.version_ix;
+      try {
+        const version = "import_ix" in selector ? getImportedVersion(db, id, selector.import_ix) : await store.getNoteVersion(id, storageIndex);
+        if (!version) return json({ error: "Not found", error_type: "not_found", ...(imported ? selector : {}) }, 404);
+        gateStrictWrite(store, writeCtx, {
+          path: note ? note.path : latestTombstone(db, id)?.path,
+          tags: note?.tags ?? [], metadata: version.metadata,
+        });
+        const restored = await store.restoreNoteVersion(id, storageIndex, {
+          actor: writeCtx.actor, via: writeCtx.via,
+          ...(body.if_updated_at !== undefined ? { if_updated_at: body.if_updated_at as string } : {}),
+        });
+        let validated: any = attachValidationStatus(store, db, restored);
+        validated = scrubNoteTagsByScope(validated, tagScope.allowed, tagScope.raw);
+        if (validated.validation_status) {
+          const vs = scrubValidationStatusByScope(validated.validation_status, tagScope.allowed, tagScope.raw);
+          if (vs === undefined) { const { validation_status: _d, ...rest } = validated; validated = rest; }
+          else validated = { ...validated, validation_status: vs };
+        }
+        return json({ ...validated, restored_from: "import_ix" in selector ? selector : selector.version_ix, recreated: !note });
+      } catch (e: any) {
+        if ("import_ix" in selector && e?.code === "HISTORY_UNRECOVERABLE" && e.origin !== "git-import") e = new ImportedHistoryUnrecoverableError(id, selector.import_ix, e.reason);
+        const r = conflictResponse(e);
+        if (r) return r;
+        throw e;
+      }
+    }
+    return json({ error: "Method not allowed", error_type: "method_not_allowed" }, 405);
+  }
+
   if (sub !== "") return json({ error: "Not found", error_type: "not_found" }, 404);
 
   // GET /notes/:idOrPath — single note
@@ -3357,90 +3544,8 @@ async function handleNotesInner(
       lean.created = false;
       return json(lean);
     } catch (e: any) {
-      if (e instanceof NotFoundError) return json({ error: e.message, error_type: "not_found" }, 404);
-      // Duck-type on `code` rather than `instanceof ConflictError`: this
-      // error originates in the core package and survives any future
-      // bundling / module-boundary split more robustly than a prototype check.
-      if (e && e.code === "CONFLICT") {
-        return json(
-          {
-            // New structured shape — what agents should key on.
-            error_type: "conflict",
-            current_updated_at: e.current_updated_at ?? null,
-            your_updated_at: e.expected_updated_at,
-            path: e.note_path ?? null,
-            note_id: e.note_id,
-            message: e.message,
-            hint: "re-read the note (GET) and re-apply your change against its current `updated_at`, or pass `force: true` to overwrite",
-            // Legacy fields — kept for the lens VaultConflictError shim and
-            // any other pre-launch callers. Safe to drop post-launch.
-            error: "conflict",
-            expected_updated_at: e.expected_updated_at,
-          },
-          409,
-        );
-      }
-      // State-transition compare-and-set conflict (vault#299 Part B). A
-      // DISTINCT error vocabulary from `conflict` (settled lead #3): the
-      // field VALUE didn't match `from`, not the updated_at token. 409.
-      if (e && e.code === "TRANSITION_CONFLICT") {
-        return json(
-          {
-            error_type: "transition_conflict",
-            error: "transition_conflict",
-            note_id: e.note_id,
-            path: e.note_path ?? null,
-            field: e.field,
-            expected_from: e.expected_from,
-            to: e.to,
-            current: e.current ?? null,
-            message: e.message,
-            hint: "re-read the note's current value for this field and retry the transition from its actual current state",
-          },
-          409,
-        );
-      }
-      // Strict-schema rejection (vault#299 Part A). One error carrying ALL
-      // per-field violations (settled lead #1). 422 Unprocessable Entity —
-      // the note exists / request is well-formed but violates the contract.
-      if (e && e.code === "SCHEMA_VALIDATION") {
-        return json(
-          {
-            error_type: "schema_validation",
-            error: "schema_validation",
-            violations: e.violations ?? [],
-            message: e.message,
-            hint: "fix every field listed in `violations` and retry — none of this write was applied",
-          },
-          422,
-        );
-      }
-      // Path-rename collision — schema's UNIQUE(path) tripped. Issue #126.
-      if (e && e.code === "PATH_CONFLICT") {
-        return json(
-          {
-            error_type: "path_conflict",
-            error: "path_conflict",
-            path: e.path,
-            message: e.message,
-            hint: "pass a different `path`, or omit it to leave the existing path unchanged",
-          },
-          409,
-        );
-      }
-      if (e && e.code === "INVALID_EXTENSION") {
-        return json(
-          { error_type: "invalid_extension", error: "invalid_extension", extension: e.extension, reason: e.reason, message: e.message },
-          400,
-        );
-      }
-      // Bad `path` value (vault#589 / FIX 2) — NUL byte or `..` segment.
-      if (e && e.code === "INVALID_PATH") {
-        return json(
-          { error_type: "invalid_path", error: "invalid_path", path: e.path, reason: e.reason, message: e.message },
-          400,
-        );
-      }
+      const r = conflictResponse(e);
+      if (r) return r;
       throw e;
     }
   }
@@ -3454,7 +3559,7 @@ async function handleNotesInner(
     if (!noteWithinTagScope(note, tagScope.allowed, tagScope.raw)) {
       return json({ error: "Not found", error_type: "not_found" }, 404);
     }
-    await store.deleteNote(note.id);
+    await store.deleteNote(note.id, { actor: writeCtx.actor, via: writeCtx.via });
     return json({ deleted: true, id: note.id });
   }
 
@@ -3471,6 +3576,7 @@ export async function handleTags(
   store: Store,
   subpath = "",
   tagScope: TagScopeCtx = NO_TAG_SCOPE,
+  writeCtx: WriteCtx = NO_WRITE_CTX,
 ): Promise<Response> {
   const url = new URL(req.url);
 
@@ -3619,7 +3725,7 @@ export async function handleTags(
     // other surface). The old fail-closed token-reference check has been
     // removed; the cascade rewrites the JSON allowlist atomically. See
     // notes.ts:renameTag for the surfaces touched.
-    const result = await store.renameTag(oldName, newName);
+    const result = await store.renameTag(oldName, newName, { actor: writeCtx.actor ?? undefined, via: writeCtx.via ?? undefined });
     if ("error" in result) {
       if (result.error === "not_found") {
         return json({ error: "not_found", error_type: "tag_not_found", tag: oldName }, 404);
@@ -5142,3 +5248,37 @@ function removeWikilinkBrackets(content: string, targetPath: string): string {
   content = content.replace(new RegExp(`\\[\\[${escaped}(#[^\\]]+)?\\]\\]`, "gi"), `${targetPath}$1`);
   return content;
 }
+
+/** POST /api/history/compact — unscoped administrators; absent bounds are unbounded. */
+export async function handleHistoryCompact(req: Request, store: Store, tagScope: TagScopeCtx = NO_TAG_SCOPE): Promise<Response> {
+  if (tagScope.raw !== null)
+    return json({ error: "Not found", error_type: "not_found" }, 404);
+  const declared = Number(req.headers.get("content-length"));
+  if (declared > MAX_JSON_BODY_BYTES)
+    return payloadTooLargeResponse(declared);
+  let body: Record<string, unknown>;
+  try {
+    const raw = await req.text();
+    if (new TextEncoder().encode(raw).length > MAX_JSON_BODY_BYTES)
+      return payloadTooLargeResponse(new TextEncoder().encode(raw).length);
+    const parsed = raw.trim() ? JSON.parse(raw) : {};
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+      throw new Error("object required");
+    body = parsed;
+  }
+  catch {
+    return json({ error: "Invalid compaction request", error_type: "invalid_request" }, 400);
+  }
+  if ((body.note_id !== undefined && (typeof body.note_id !== "string" || body.note_id.length === 0)) ||
+    [body.budget_ms, body.max_notes].some(v => v !== undefined && (typeof v !== "number" || !Number.isInteger(v) || v < 1)))
+    return json({ error: "Invalid compaction request", error_type: "invalid_request" }, 400);
+  try {
+    return json(store.compactHistory({ noteId: body.note_id as string | undefined, budgetMs: body.budget_ms as number | undefined ?? null, maxNotes: body.max_notes as number | undefined ?? null }));
+  }
+  catch (err) {
+    const conflict = conflictResponse(err);
+    if (conflict)
+      return conflict;
+    return json({ error: "Compaction failed", error_type: "compaction_failed", message: err instanceof Error ? err.message : String(err) }, 500);
+  }
+}

package/src/routing.ts

@@ -85,6 +85,7 @@ import {
   handleStorage,
   handleViewNote,
   handleDoctor,
+  handleHistoryCompact,
   type TagScopeCtx,
   type WriteCtx,
 } from "./routes.ts";
@@ -1101,11 +1102,14 @@ export async function route(
     ((req.method === "PUT" || req.method === "DELETE") && /^\/tags\/[^/]+$/.test(apiSubpath)) ||
     (req.method === "POST" &&
       (apiSubpath === "/tags/merge" || /^\/tags\/[^/]+\/rename$/.test(apiSubpath)));
-  const requiredVerb = isReadOnlyPost ? "read" : isTagSchemaMutation ? "admin" : verbForMethod(req.method);
+  // Erasing note history is irreversible and requires admin (vault#524).
+  const isNoteHistoryErase = req.method === "DELETE" && /^\/notes\/[^/]+\/versions$/.test(apiSubpath);
+  const isHistoryCompact = req.method === "POST" && apiSubpath === "/history/compact";
+  const requiredVerb = isReadOnlyPost ? "read" : (isTagSchemaMutation || isNoteHistoryErase || isHistoryCompact) ? "admin" : verbForMethod(req.method);
   if (!hasScopeForVault(auth.scopes, vaultName, requiredVerb)) {
     const requiredApiScope = isReadOnlyPost
       ? SCOPE_READ
-      : isTagSchemaMutation
+      : (isTagSchemaMutation || isNoteHistoryErase || isHistoryCompact)
         ? SCOPE_ADMIN
         : scopeForMethod(req.method);
     return Response.json(
@@ -1173,7 +1177,8 @@ export async function route(
       { status: 410 },
     );
   }
-  if (apiPath.startsWith("/tags")) return handleTags(req, store, apiPath.slice(5), tagScope);
+  if (apiPath.startsWith("/tags")) return handleTags(req, store, apiPath.slice(5), tagScope, writeCtx);
+  if (isHistoryCompact) return handleHistoryCompact(req, store, tagScope);
   if (apiPath === "/find-path") return handleFindPath(req, store, tagScope);
   if (apiPath === "/vault") {
     return handleVault(

package/src/server.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env bun
+import { assertVaultNotPaused, VaultImportPausedError, MirrorRetiredError } from "./mirror-config.ts";
 /**
  * Multi-vault HTTP server using Bun.serve().
  *
@@ -430,22 +431,27 @@ for (const warning of reservedNameSquatWarnings(listVaults())) {
 // Migrate tag schemas from vault.yaml → DB for each vault.
 // Only inserts schemas that don't already exist in the DB (safe across restarts).
 for (const vaultName of listVaults()) {
-  const vaultConfig = readVaultConfig(vaultName);
-  if (vaultConfig?.tag_schemas && Object.keys(vaultConfig.tag_schemas).length > 0) {
-    const store = getVaultStore(vaultName);
-    const existingTags = new Set((await store.listTagSchemas()).map((s) => s.tag));
-    let migrated = 0;
-    for (const [tag, schema] of Object.entries(vaultConfig.tag_schemas)) {
-      if (!existingTags.has(tag)) {
-        await store.upsertTagSchema(tag, schema);
-        migrated++;
+  try {
+    const vaultConfig = readVaultConfig(vaultName);
+    if (vaultConfig?.tag_schemas && Object.keys(vaultConfig.tag_schemas).length > 0) {
+      const store = getVaultStore(vaultName);
+      const existingTags = new Set((await store.listTagSchemas()).map((s) => s.tag));
+      let migrated = 0;
+      for (const [tag, schema] of Object.entries(vaultConfig.tag_schemas)) {
+        if (!existingTags.has(tag)) {
+          await store.upsertTagSchema(tag, schema);
+          migrated++;
+        }
+      }
+      if (migrated > 0) {
+        console.log(`[migration] migrated ${migrated} tag schema(s) from vault.yaml to DB for vault "${vaultName}"`);
+      } else {
+        console.log(`[migration] vault "${vaultName}" has tag_schemas in vault.yaml (already in DB — vault.yaml section can be removed)`);
       }
     }
-    if (migrated > 0) {
-      console.log(`[migration] migrated ${migrated} tag schema(s) from vault.yaml to DB for vault "${vaultName}"`);
-    } else {
-      console.log(`[migration] vault "${vaultName}" has tag_schemas in vault.yaml (already in DB — vault.yaml section can be removed)`);
-    }
+  } catch (err) {
+    if (!(err instanceof VaultImportPausedError)) throw err;
+    console.warn(`[history-import] vault "${vaultName}" is paused; skipping tag-schema migration`);
   }
 }
 
@@ -633,6 +639,16 @@ const server = Bun.serve({
       return new Response(null, { status: 204, headers: corsHeaders });
     }
 
+    // Refuse before WS upgrade and before any route can open/maintain a paused DB.
+    const vaultSegment = /^\/vault\/([^/]+)/.exec(path)?.[1];
+    if (vaultSegment && listVaults().includes(vaultSegment)) {
+      try { assertVaultNotPaused(vaultSegment); }
+      catch (err) {
+        if (!(err instanceof VaultImportPausedError)) throw err;
+        return Response.json({ error_type: err.error_type, message: err.message }, { status: 503, headers: corsHeaders });
+      }
+    }
+
     // Live-query WebSocket upgrade — detected BEFORE the fetch pipeline because
     // WS upgrades don't traverse `route()`. Non-upgrade requests (incl. a
     // straggler non-WS GET /subscribe, which now gets a 410 Gone in routing.ts —
@@ -659,6 +675,9 @@ const server = Bun.serve({
       }
       return response;
     } catch (err) {
+      if (err instanceof VaultImportPausedError || err instanceof MirrorRetiredError) {
+        return Response.json({ error_type: err.error_type, message: err.message }, { status: err.status, headers: corsHeaders });
+      }
       console.error(`[${req.method} ${path}]`, err);
       return Response.json(
         { error: "Internal server error" },