@openparachute/vault 0.4.8 → 0.4.9-rc.11

package/core/src/portable-md.ts

@@ -72,7 +72,7 @@
  * See vault#308.
  */
 
-import { readdirSync, readFileSync, statSync, mkdirSync, writeFileSync, copyFileSync, existsSync, rmSync } from "fs";
+import { readdirSync, readFileSync, realpathSync, statSync, mkdirSync, writeFileSync, copyFileSync, existsSync, rmSync } from "fs";
 import { basename, join, relative, extname, dirname, resolve as resolvePath, sep as pathSep } from "path";
 import type { Store, Note, Link, Attachment } from "./types.js";
 import type { TagRecord } from "./tag-schemas.js";
@@ -1001,7 +1001,375 @@ export async function exportVaultToDir(
   };
 }
 
-function hasSchemaContent(tag: TagRecord): boolean {
+// ---------------------------------------------------------------------------
+// Orphan sweep — for git-mirror's delete propagation
+// ---------------------------------------------------------------------------
+
+/**
+ * Result of a `pruneOrphans` pass.
+ */
+export interface PruneOrphansStats {
+  /** Note content files removed (frontmatter id not in `validNoteIds`). */
+  notes_removed: number;
+  /** Sidecar metadata files removed (under `.parachute/notes-meta/`). */
+  sidecars_removed: number;
+  /** Schema sidecars removed (under `.parachute/schemas/`). */
+  schemas_removed: number;
+  /** Attachment directories removed (under `.parachute/attachments/`). */
+  attachment_dirs_removed: number;
+  /**
+   * Files we couldn't parse / classify. Surfaced for operator audit;
+   * the sweep doesn't touch them. Empty when everything classified
+   * cleanly.
+   */
+  unparseable_files: Array<{ path: string; reason: string }>;
+}
+
+/**
+ * Options for the orphan-sweep pass. Run periodically (the mirror manager
+ * arms a safety-net poll, default 1h) and after operator-visible deletions
+ * (the mirror manager's targeted-deletion fast path also calls this for the
+ * touched-set).
+ *
+ * The sweep is the bookkeeping cousin of the event-driven fast path: events
+ * cover the common case (a single note deletion fires "deleted" → mirror
+ * removes that file); the sweep covers anything the fast path missed
+ * (direct SQL writes, app crashes between dispatch and handler, restart
+ * gaps).
+ */
+export interface PruneOrphansOptions {
+  /** Directory to sweep — same shape as an `exportVaultToDir` outDir. */
+  outDir: string;
+  /** Note IDs that should be kept (everything else under the export gets removed). */
+  validNoteIds: Set<string>;
+  /** Tag names that should be kept (other schema sidecars under `.parachute/schemas/` get removed). */
+  validTagNames: Set<string>;
+  /** Attachment IDs that should be kept (other dirs under `.parachute/attachments/` get removed). */
+  validAttachmentIds: Set<string>;
+  /**
+   * Override `extension`-based content-file extension recognition. The
+   * default treats `.md` and `.mdx` as having inline frontmatter (with
+   * `id:` reachable via the file head); everything else needs a sidecar
+   * lookup to know what id owns it.
+   */
+  supportsInlineFrontmatter?: (ext: string) => boolean;
+}
+
+/**
+ * Sweep the export directory for files belonging to notes / tags /
+ * attachments that no longer exist in the vault. Removes them so the
+ * mirror's `git diff` reflects what vault actually has.
+ *
+ * Strategy:
+ *   1. Walk content files. For each `.md` / `.mdx`, parse the frontmatter
+ *      `id` and compare against `validNoteIds`. Mismatch → remove the
+ *      file. Files we can't parse are recorded in `unparseable_files`
+ *      and left alone (best-effort, no destructive guesses).
+ *   2. For non-inline-frontmatter extensions (`.csv`, `.yaml`, etc.),
+ *      check the matching `.parachute/notes-meta/<id>.yaml` sidecar — the
+ *      sidecar carries the canonical `id` + `path` + `extension` triple.
+ *      An orphaned sidecar (no matching content file) is also removed,
+ *      and an orphaned content file (no matching sidecar) without a
+ *      parseable frontmatter is left as unparseable.
+ *   3. Walk `.parachute/schemas/`. Each file is `<tag>.yaml` (after
+ *      filename sanitization). Parse the `name:` field; compare against
+ *      `validTagNames`. Mismatch → remove.
+ *   4. Walk `.parachute/attachments/`. Each subdir name IS the
+ *      attachment id (per `exportVaultToDir`'s layout). Compare against
+ *      `validAttachmentIds`. Mismatch → recursive remove.
+ *
+ * Returns counts so callers can log + decide whether to commit.
+ *
+ * Safe to call on a directory that's never been exported to (returns
+ * zero counts; doesn't create anything).
+ */
+export function pruneOrphans(opts: PruneOrphansOptions): PruneOrphansStats {
+  const stats: PruneOrphansStats = {
+    notes_removed: 0,
+    sidecars_removed: 0,
+    schemas_removed: 0,
+    attachment_dirs_removed: 0,
+    unparseable_files: [],
+  };
+
+  const outDir = opts.outDir;
+  if (!existsSync(outDir)) return stats;
+
+  const supportsInline = opts.supportsInlineFrontmatter ?? supportsInlineFrontmatter;
+  const sidecarRoot = join(outDir, SIDECAR_DIR);
+  const notesMetaRoot = join(sidecarRoot, NOTES_META_DIR);
+  const schemasRoot = join(sidecarRoot, "schemas");
+  const attachmentsRoot = join(sidecarRoot, "attachments");
+
+  // Path-traversal guard. `walkContentFiles` uses `statSync` which
+  // follows symlinks — a symlink inside the mirror pointing OUTSIDE
+  // `outDir` would resurface its target's files in the prune sweep,
+  // and a bare `rmSync(filepath)` would delete them off-tree. Every
+  // deletion in this function routes through `safeRm`, which calls
+  // `realpathSync` (resolves through symlinks, unlike syntactic-only
+  // `path.resolve`) and refuses to delete anything that isn't `outDir`
+  // or beneath it after symlink resolution. Refusals get recorded in
+  // `unparseable_files` so an operator can see what was skipped.
+  // Reviewer-flagged on vault#382 (Critical #2).
+  const outDirReal = realpathSync(outDir);
+  const safeRm = (
+    candidate: string,
+    onSuccess: () => void,
+    options: { recursive?: boolean } = {},
+  ): void => {
+    let real: string;
+    try {
+      real = realpathSync(candidate);
+    } catch (err) {
+      // realpathSync throws if the path doesn't exist or is unreadable.
+      // Don't delete what we can't fully resolve.
+      stats.unparseable_files.push({
+        path: candidate,
+        reason: `realpath failed: ${(err as Error).message ?? err}`,
+      });
+      return;
+    }
+    if (!isWithinDir(real, outDirReal)) {
+      stats.unparseable_files.push({
+        path: candidate,
+        reason: "real path resolved outside mirror outDir — refusing to delete (symlink?)",
+      });
+      return;
+    }
+    try {
+      // Delete via the resolved real path; never via the unresolved
+      // candidate (which could route through a symlink we already
+      // determined would escape).
+      rmSync(real, { force: true, recursive: options.recursive ?? false });
+      onSuccess();
+    } catch (err) {
+      stats.unparseable_files.push({
+        path: candidate,
+        reason: `unlink failed: ${(err as Error).message ?? err}`,
+      });
+    }
+  };
+
+  // ---- 1 + 2. Notes + sidecars ----
+  //
+  // First pass: build the sidecar id → { path, extension } map so we can
+  // resolve non-inline-frontmatter content files via their sidecar.
+  // Sidecars whose claimed (path, extension) doesn't map to an existing
+  // content file are tracked as "orphaned sidecar" candidates.
+  const sidecarById = new Map<string, { path: string | null; extension: string | null }>();
+  const sidecarFilesById = new Map<string, string>(); // id → absolute filepath
+  if (existsSync(notesMetaRoot)) {
+    try {
+      for (const entry of readdirSync(notesMetaRoot)) {
+        if (!entry.endsWith(".yaml")) continue;
+        const id = entry.slice(0, -5);
+        const full = join(notesMetaRoot, entry);
+        sidecarFilesById.set(id, full);
+        try {
+          const text = readFileSync(full, "utf-8");
+          const { frontmatter } = parseFrontmatter(`---\n${text}---\n`);
+          sidecarById.set(id, {
+            path: typeof frontmatter.path === "string" ? (frontmatter.path as string) : null,
+            extension: typeof frontmatter.extension === "string" ? (frontmatter.extension as string) : null,
+          });
+        } catch (err) {
+          stats.unparseable_files.push({
+            path: full,
+            reason: `failed to parse sidecar: ${(err as Error).message ?? err}`,
+          });
+        }
+      }
+    } catch (err) {
+      // Notes-meta dir read-error is non-fatal — record + carry on.
+      stats.unparseable_files.push({
+        path: notesMetaRoot,
+        reason: `notes-meta walk failed: ${(err as Error).message ?? err}`,
+      });
+    }
+  }
+
+  // Now walk content files (everything outside the .parachute sidecar).
+  const contentFiles = walkContentFiles(outDir);
+  // Track which sidecars matched a content file so we can also remove
+  // orphaned sidecars (sidecar present but content file gone).
+  const pairedSidecarIds = new Set<string>();
+  for (const filepath of contentFiles) {
+    const ext = extname(filepath).slice(1).toLowerCase();
+    if (supportsInline(ext)) {
+      // Parse frontmatter, read id.
+      try {
+        const raw = readFileSync(filepath, "utf-8");
+        const { frontmatter } = parseFrontmatter(raw);
+        const id = typeof frontmatter.id === "string" ? (frontmatter.id as string) : null;
+        if (!id) {
+          stats.unparseable_files.push({
+            path: filepath,
+            reason: "no `id` in frontmatter",
+          });
+          continue;
+        }
+        if (!opts.validNoteIds.has(id)) {
+          safeRm(filepath, () => {
+            stats.notes_removed++;
+          });
+        }
+      } catch (err) {
+        stats.unparseable_files.push({
+          path: filepath,
+          reason: `read failed: ${(err as Error).message ?? err}`,
+        });
+      }
+    } else {
+      // Sidecar-required extension. Find the matching sidecar by
+      // (path, extension) — sidecars are keyed by id, so we sweep the
+      // sidecarById map.
+      const relPath = relative(outDir, filepath).replace(/\\/g, "/");
+      // Strip extension to get the canonical path stored in the sidecar
+      // (vault paths don't carry extensions).
+      const pathNoExt = relPath.slice(0, -(ext.length + 1));
+      let foundId: string | null = null;
+      for (const [id, info] of sidecarById.entries()) {
+        if (
+          info.path === pathNoExt &&
+          (info.extension ?? "md").toLowerCase() === ext
+        ) {
+          foundId = id;
+          break;
+        }
+      }
+      if (!foundId) {
+        // Content file with no sidecar — can't tell which note owns it.
+        // Conservative: leave alone, record as unparseable.
+        stats.unparseable_files.push({
+          path: filepath,
+          reason: "no sidecar metadata could be matched by (path, extension)",
+        });
+        continue;
+      }
+      pairedSidecarIds.add(foundId);
+      if (!opts.validNoteIds.has(foundId)) {
+        // Note is orphaned — remove both content and sidecar.
+        safeRm(filepath, () => {
+          stats.notes_removed++;
+        });
+        const sidecarPath = sidecarFilesById.get(foundId);
+        if (sidecarPath) {
+          safeRm(sidecarPath, () => {
+            stats.sidecars_removed++;
+          });
+        }
+      }
+    }
+  }
+
+  // Sweep up orphaned sidecars (sidecar exists but no content file
+  // matched OR sidecar's id isn't in validNoteIds).
+  for (const [id, sidecarPath] of sidecarFilesById.entries()) {
+    if (opts.validNoteIds.has(id) && pairedSidecarIds.has(id)) continue;
+    if (opts.validNoteIds.has(id) && !pairedSidecarIds.has(id)) {
+      // Sidecar refers to a valid note but the content file is gone —
+      // that's an inconsistency, not an orphan. Leave the sidecar so
+      // the next export can rewrite the content file alongside it.
+      continue;
+    }
+    safeRm(sidecarPath, () => {
+      stats.sidecars_removed++;
+    });
+  }
+
+  // ---- 3. Schema sidecars ----
+  if (existsSync(schemasRoot)) {
+    try {
+      for (const entry of readdirSync(schemasRoot)) {
+        if (!entry.endsWith(".yaml")) continue;
+        const full = join(schemasRoot, entry);
+        try {
+          const text = readFileSync(full, "utf-8");
+          const { frontmatter } = parseFrontmatter(`---\n${text}---\n`);
+          const name = typeof frontmatter.name === "string" ? (frontmatter.name as string) : null;
+          if (!name) {
+            // Fall back to filename — sanitizeTagFilename replaces `/`
+            // with `__`, so reverse for the lookup.
+            const fromFilename = entry.slice(0, -5).replace(/__/g, "/");
+            if (!opts.validTagNames.has(fromFilename)) {
+              safeRm(full, () => {
+                stats.schemas_removed++;
+              });
+            }
+            continue;
+          }
+          if (!opts.validTagNames.has(name)) {
+            safeRm(full, () => {
+              stats.schemas_removed++;
+            });
+          }
+        } catch (err) {
+          stats.unparseable_files.push({
+            path: full,
+            reason: `schema sweep failed: ${(err as Error).message ?? err}`,
+          });
+        }
+      }
+    } catch (err) {
+      stats.unparseable_files.push({
+        path: schemasRoot,
+        reason: `schemas walk failed: ${(err as Error).message ?? err}`,
+      });
+    }
+  }
+
+  // ---- 4. Attachment directories ----
+  if (existsSync(attachmentsRoot)) {
+    try {
+      for (const entry of readdirSync(attachmentsRoot)) {
+        const full = join(attachmentsRoot, entry);
+        let stat;
+        try {
+          stat = statSync(full);
+        } catch (err) {
+          stats.unparseable_files.push({
+            path: full,
+            reason: `stat failed: ${(err as Error).message ?? err}`,
+          });
+          continue;
+        }
+        if (!stat.isDirectory()) continue;
+        // The directory name IS the attachment id (per the export layout).
+        if (!opts.validAttachmentIds.has(entry)) {
+          safeRm(
+            full,
+            () => {
+              stats.attachment_dirs_removed++;
+            },
+            { recursive: true },
+          );
+        }
+      }
+    } catch (err) {
+      stats.unparseable_files.push({
+        path: attachmentsRoot,
+        reason: `attachments walk failed: ${(err as Error).message ?? err}`,
+      });
+    }
+  }
+
+  return stats;
+}
+
+/**
+ * True iff the tag carries content the export writer will emit as a
+ * schema sidecar (`.parachute/schemas/<tag>.yaml`). Bare-name tags
+ * (the `tags` table has a row but description/fields/relationships/
+ * parents are all empty) get no sidecar — and crucially, after
+ * `deleteTagSchema` clears those fields the row persists with the
+ * bare name. Callers building the `validTagNames` set for
+ * `pruneOrphans` MUST filter through this predicate, otherwise the
+ * stale sidecar lingers indefinitely.
+ *
+ * Reviewer-flagged on vault#382: without this filter, a cleared
+ * schema's sidecar never gets pruned.
+ */
+export function hasSchemaContent(tag: TagRecord): boolean {
   if (tag.description !== undefined && tag.description.length > 0) return true;
   if (tag.fields && Object.keys(tag.fields).length > 0) return true;
   if (tag.relationships && Object.keys(tag.relationships).length > 0) return true;
@@ -1167,6 +1535,14 @@ export interface ImportStats {
   skipped_sidecars: Array<{ sidecar_id: string; expected_path: string | null; expected_extension: string | null; reason: string }>;
   /** Set when the caller passed `blowAway: true`; counts notes removed. */
   notes_wiped: number;
+  /**
+   * (tag, field) indexed-field declarations replayed after restoring tag
+   * schemas — materializes the generated columns + indexes a live vault
+   * would have. Without this an imported vault's schemas say `indexed: true`
+   * but the backing columns don't exist until each tag is next `update-tag`'d
+   * (queries fall back to full scans). See the import re-declare fix.
+   */
+  indexes_declared: number;
 }
 
 /**
@@ -1214,6 +1590,7 @@ export async function importPortableVault(
     skipped_attachments: [],
     skipped_sidecars: [],
     notes_wiped: 0,
+    indexes_declared: 0,
   };
 
   // 1. Optional wipe. Notes are deleted via the public Store API so
@@ -1651,6 +2028,45 @@ export async function importPortableVault(
     await store.syncAllWikilinks();
   }
 
+  // 7. Re-declare indexed fields (belt-and-suspenders + authoritative count).
+  // Step 2 restored tag schemas via `store.upsertTagRecord`, which — now that
+  // the indexed-field lifecycle is centralized in the store — already
+  // materializes the backing generated columns + indexes as it persists each
+  // schema. This explicit reconcile is therefore idempotent on the happy path;
+  // it stays as a safety net (covers any schema written through a path that
+  // skipped the lifecycle) and gives the authoritative `indexes_declared`
+  // count. Without it, a regression in step 2 would silently leave the
+  // imported schemas advertising `indexed: true` while queries full-scan.
+  if (!opts.dryRun) {
+    stats.indexes_declared = await store.reconcileDeclaredIndexes();
+  } else {
+    // Dry-run: count what WOULD be declared without touching the DB. Both
+    // paths count per (tag, field) declaration (a co-declared field counts
+    // once per declaring tag). The one asymmetry: this dry-run counts every
+    // `indexed: true` field including unsupported types, whereas the applied
+    // `reconcileDeclaredIndexes` skips fields whose type can't be indexed —
+    // so the dry-run can over-count by the number of mis-typed indexed
+    // fields. It's a "how much indexing work" signal, not a row-exact promise.
+    const schemasDir2 = join(sidecar, "schemas");
+    if (existsSync(schemasDir2)) {
+      for (const entry of readdirSync(schemasDir2)) {
+        if (!entry.endsWith(".yaml")) continue;
+        const fullPath = join(schemasDir2, entry);
+        const resolved = resolvePath(fullPath);
+        if (!isWithinDir(resolved, resolvePath(schemasDir2))) continue;
+        const text = readFileSync(fullPath, "utf-8");
+        const wrapped = `---\n${text}${text.endsWith("\n") ? "" : "\n"}---\n`;
+        const { frontmatter } = parseFrontmatter(wrapped);
+        const fields = frontmatter.fields;
+        if (fields && typeof fields === "object" && !Array.isArray(fields)) {
+          for (const spec of Object.values(fields as Record<string, { indexed?: boolean }>)) {
+            if (spec?.indexed === true) stats.indexes_declared++;
+          }
+        }
+      }
+    }
+  }
+
   return stats;
 }
 

package/core/src/schema.ts

@@ -2,7 +2,7 @@ import { Database } from "bun:sqlite";
 import { normalizePath } from "./paths.js";
 import { rebuildIndexes } from "./indexed-fields.js";
 
-export const SCHEMA_VERSION = 18;
+export const SCHEMA_VERSION = 20;
 
 export const SCHEMA_SQL = `
 -- Notes: the universal record.
@@ -118,6 +118,20 @@ CREATE TABLE IF NOT EXISTS indexed_fields (
 --
 -- scope_tag / scope_path_prefix are deprecated Phase-0 columns — never
 -- enforced at runtime, kept only for schema stability.
+-- created_via (v19) records the provenance of a token. NULL means the
+-- legacy/unspecified path (CLI, REST mint, YAML import); 'mcp_mint' means
+-- the token was minted by the manage-token MCP tool, which lets the
+-- list/revoke surface of that tool restrict itself to its own session's
+-- mints (no cross-session token management from inside MCP).
+--
+-- parent_jti (v19) is the display id (t_hashprefix) of the token that
+-- minted this one, or the hub-JWT jti claim when minted from a hub
+-- session. Session-pinned list+revoke in manage-token filters on this.
+--
+-- revoked_at (v19) marks soft-revocation. Revoke from manage-token sets
+-- this rather than deleting the row, so the audit trail stays intact and
+-- the second revoke of the same jti is idempotent (returns ok=true).
+-- resolveToken treats a revoked_at-set row as not-found.
 CREATE TABLE IF NOT EXISTS tokens (
   token_hash TEXT PRIMARY KEY,
   label TEXT NOT NULL,
@@ -129,7 +143,34 @@ CREATE TABLE IF NOT EXISTS tokens (
   expires_at TEXT,
   created_at TEXT NOT NULL,
   last_used_at TEXT,
-  vault_name TEXT
+  vault_name TEXT,
+  created_via TEXT,
+  parent_jti TEXT,
+  revoked_at TEXT
+);
+
+-- mcp_mint_ledger (v20) — session-pinned record of HUB JWTs minted by the
+-- manage-token MCP tool (vault#403, MGT). After the auth-unification arc,
+-- manage-token mints hub JWTs (via hub mint-token attenuation proxy), not
+-- pvt_* vault-DB tokens — so the mints no longer live in the tokens table.
+-- This ledger is a lightweight local index of (parent_jti to minted hub jti)
+-- so the tool list/revoke surface can stay session-scoped: a session sees
+-- and revokes only the hub JWTs it minted. Rows are NOT credentials — the
+-- signed JWT is never stored, only its jti (the revocation handle) plus
+-- display metadata. revoked_at mirrors the tokens-table soft-revoke marker
+-- so a second revoke is idempotent even if the hub round-trip is skipped.
+-- The authoritative revocation state lives in hub token registry; this is
+-- the attribution index only.
+CREATE TABLE IF NOT EXISTS mcp_mint_ledger (
+  jti TEXT PRIMARY KEY,
+  parent_jti TEXT NOT NULL,
+  vault_name TEXT NOT NULL,
+  label TEXT NOT NULL,
+  scopes TEXT,
+  scoped_tags TEXT,
+  created_at TEXT NOT NULL,
+  expires_at TEXT,
+  revoked_at TEXT
 );
 
 -- OAuth: registered clients (Dynamic Client Registration)
@@ -197,6 +238,10 @@ CREATE INDEX IF NOT EXISTS idx_note_tags_tag ON note_tags(tag_name, note_id);
 CREATE INDEX IF NOT EXISTS idx_attachments_note ON attachments(note_id);
 CREATE INDEX IF NOT EXISTS idx_links_source ON links(source_id);
 CREATE INDEX IF NOT EXISTS idx_links_target ON links(target_id);
+-- Session-pinned manage-token ledger lookup (v20): list/revoke scope on
+-- (parent_jti, vault_name). The mcp_mint_ledger table is created
+-- unconditionally above, so this index is safe in SCHEMA_SQL.
+CREATE INDEX IF NOT EXISTS idx_mcp_mint_ledger_session ON mcp_mint_ledger(parent_jti, vault_name);
 -- idx_tokens_vault_name is created in migrateToV16, not here. SCHEMA_SQL
 -- runs BEFORE migrations; an upgrading v15 vault doesn't yet have the
 -- vault_name column when this section evaluates, so the index has to
@@ -380,6 +425,19 @@ export function initSchema(db: Database): void {
   // (markdown), unchanged in meaning. See vault#328.
   migrateToV18(db);
 
+  // Migrate v18 → v19: add MCP-mint provenance columns to `tokens`
+  // (created_via, parent_jti, revoked_at) for vault#376's manage-token tool.
+  // All three are nullable; existing rows backfill to NULL which means
+  // "non-MCP-minted, not revoked" — identical pre-v19 semantics.
+  migrateToV19(db);
+
+  // Migrate v19 → v20: the `mcp_mint_ledger` table (session-pinned record of
+  // hub JWTs minted by the manage-token MCP tool). Created by SCHEMA_SQL's
+  // `CREATE TABLE IF NOT EXISTS` above, so this is a no-op confirmation hook
+  // — present for symmetry with the other migration steps and to anchor the
+  // version bump. See vault#403 (MGT — manage-token mints hub JWTs).
+  migrateToV20(db);
+
   // Rebuild any generated columns + indexes declared in indexed_fields.
   // No-op for a fresh vault; idempotent on existing vaults.
   rebuildIndexes(db);
@@ -952,6 +1010,60 @@ function migrateToV18(db: Database): void {
   }
 }
 
+/**
+ * Migrate v18 → v19: add `created_via`, `parent_jti`, `revoked_at` columns
+ * to `tokens` so manage-token can attribute mints to the MCP session that
+ * minted them, scope its list+revoke to those tokens, and soft-revoke
+ * (preserving the audit trail).
+ *
+ * All three columns are nullable; existing rows backfill to NULL with
+ * back-compat semantics — `created_via IS NULL` matches the CLI/REST-mint
+ * provenance, `revoked_at IS NULL` matches "still active". Idempotent —
+ * the column-existence guard means the migration is safe to re-run on a
+ * post-v19 vault. See vault#376.
+ */
+function migrateToV19(db: Database): void {
+  if (!hasTable(db, "tokens")) return;
+  const cols: [string, string][] = [
+    ["created_via", "TEXT"],
+    ["parent_jti", "TEXT"],
+    ["revoked_at", "TEXT"],
+  ];
+  for (const [col, type] of cols) {
+    if (!hasColumn(db, "tokens", col)) {
+      db.exec(`ALTER TABLE tokens ADD COLUMN ${col} ${type}`);
+    }
+  }
+}
+
+/**
+ * Migrate v19 → v20: ensure the `mcp_mint_ledger` table exists. SCHEMA_SQL's
+ * `CREATE TABLE IF NOT EXISTS` already covers fresh vaults AND upgrading
+ * vaults (SCHEMA_SQL runs unconditionally on every open before the migration
+ * steps), so this is a defensive no-op confirmation — there is no ALTER to
+ * perform. Kept as a named step so the version-bump arc reads cleanly and a
+ * future column addition has an obvious home. See vault#403 (MGT).
+ */
+function migrateToV20(db: Database): void {
+  if (hasTable(db, "mcp_mint_ledger")) return;
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS mcp_mint_ledger (
+      jti TEXT PRIMARY KEY,
+      parent_jti TEXT NOT NULL,
+      vault_name TEXT NOT NULL,
+      label TEXT NOT NULL,
+      scopes TEXT,
+      scoped_tags TEXT,
+      created_at TEXT NOT NULL,
+      expires_at TEXT,
+      revoked_at TEXT
+    )
+  `);
+  db.exec(
+    "CREATE INDEX IF NOT EXISTS idx_mcp_mint_ledger_session ON mcp_mint_ledger(parent_jti, vault_name)",
+  );
+}
+
 function hasTable(db: Database, name: string): boolean {
   const row = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name=?").get(name);
   return !!row;