@openparachute/vault 0.4.9-rc.9 → 0.5.0-rc.2

package/core/src/mcp.ts

@@ -23,8 +23,8 @@ export interface McpToolDef {
   /**
    * Minimum scope verb the caller must hold for THIS vault to see + invoke
    * the tool. `read` for pure queries, `write` for mutations, `admin` for
-   * token-management surfaces (only `manage-token` in the current set —
-   * core's nine tools cap at `write`). The MCP HTTP layer filters
+   * operator-only surfaces (`prune-schema` in core; `manage-token` in the
+   * server layer). The MCP HTTP layer filters
    * `tools/list` by this field and verb-gates `tools/call` against it; the
    * filter is the primary defense, the inner gate is defense-in-depth.
    *
@@ -100,9 +100,9 @@ function removeWikilinkBrackets(content: string, targetPath: string): string {
 // ---------------------------------------------------------------------------
 
 /**
- * Generate the consolidated MCP tools for a vault. Post-v17 surface (9):
+ * Generate the consolidated MCP tools for a vault. Surface (10):
  * query-notes, create-note, update-note, delete-note, list-tags, update-tag,
- * delete-tag, find-path, vault-info.
+ * delete-tag, find-path, vault-info, prune-schema (admin).
  */
 export function generateMcpTools(store: Store): McpToolDef[] {
   const db: Database = (store as any).db;
@@ -1074,12 +1074,23 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
         const tag = params.tag as string;
         const existing = tagSchemaOps.getTagRecord(db, tag);
 
-        // ---- fields: shallow-merge into existing (preserves prior keys).
-        const incomingFields = (params.fields as Record<string, TagFieldSchema> | undefined) ?? {};
-        const mergedFields: Record<string, TagFieldSchema> = {
-          ...(existing?.fields ?? {}),
-          ...incomingFields,
-        };
+        // ---- fields: three-way semantics, distinguishing `null` from
+        // `undefined` (do NOT collapse with `?? {}` — that silently turns an
+        // explicit clear-all into a no-op, the gitcoin orphaned-fields bug).
+        //   - undefined  → no change. Preserve every existing field; declare
+        //                  nothing new. mergedFields === existing.fields.
+        //   - null       → clear ALL of this tag's field schemas.
+        //                  mergedFields = {} so the diff below releases every
+        //                  indexed field this tag exclusively declares.
+        //   - object     → shallow-merge into existing (preserves prior keys).
+        const incomingFields =
+          params.fields === null || params.fields === undefined
+            ? {}
+            : (params.fields as Record<string, TagFieldSchema>);
+        const mergedFields: Record<string, TagFieldSchema> =
+          params.fields === null
+            ? {}
+            : { ...(existing?.fields ?? {}), ...incomingFields };
 
         // Validate cross-tag consistency on fields being (re)declared in this
         // call. `type` and `indexed` are global — all declarers must agree.
@@ -1146,6 +1157,12 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
           : (params.fields !== undefined ? null : undefined);
         const descriptionPatch =
           params.description === undefined ? undefined : (params.description as string);
+        // The indexed-field lifecycle (declareField for added indexed fields,
+        // releaseField for removed ones, with the co-declaration guard) is
+        // reconciled inside store.upsertTagRecord — the single chokepoint all
+        // callers (MCP, REST PUT /tags/:name, import) share — so it can't be
+        // bypassed. The cross-tag validation above stays here to surface a
+        // clean error before persisting. See the gitcoin orphaned-fields bug.
         const result = await store.upsertTagRecord(tag, {
           ...(descriptionPatch !== undefined ? { description: descriptionPatch } : {}),
           ...(fieldsPatch !== undefined ? { fields: fieldsPatch } : {}),
@@ -1153,28 +1170,6 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
           ...(parentNamesPatch !== undefined ? { parent_names: parentNamesPatch } : {}),
         });
 
-        // ---- Reconcile indexed-field lifecycle for this tag.
-        const priorIndexed = new Set(
-          Object.entries(existing?.fields ?? {})
-            .filter(([, v]) => v.indexed === true)
-            .map(([k]) => k),
-        );
-        const nextIndexed = new Set(
-          Object.entries(mergedFields)
-            .filter(([, v]) => v.indexed === true)
-            .map(([k]) => k),
-        );
-        for (const fieldName of nextIndexed) {
-          const spec = mergedFields[fieldName]!;
-          const mapped = indexedFieldOps.mapFieldType(spec.type)!;
-          indexedFieldOps.declareField(db, fieldName, mapped, tag);
-        }
-        for (const fieldName of priorIndexed) {
-          if (!nextIndexed.has(fieldName)) {
-            indexedFieldOps.releaseField(db, fieldName, tag);
-          }
-        }
-
         return result;
       },
     },
@@ -1198,19 +1193,12 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
       },
       execute: async (params) => {
         const tag = params.tag as string;
-        // Release any indexed fields this tag declared before the row
-        // drops. releaseField drops the generated column + index when the
-        // declarer set empties.
-        const schema = tagSchemaOps.getTagSchema(db, tag);
-        if (schema?.fields) {
-          for (const [fieldName, spec] of Object.entries(schema.fields)) {
-            if (spec.indexed === true) {
-              indexedFieldOps.releaseField(db, fieldName, tag);
-            }
-          }
-        }
         // Drop the row outright — description/fields/relationships/parents
         // travel with it. (No more sidecar table to clear separately.)
+        // Indexed-field release is handled inside store.deleteTag →
+        // noteOps.deleteTag so every entry point (MCP, REST, import sweep)
+        // releases consistently with the co-declaration guard. See the
+        // gitcoin orphaned-fields bug report.
         return await store.deleteTag(tag);
       },
     },
@@ -1266,6 +1254,41 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
       },
     },
 
+    // =====================================================================
+    // 10. prune-schema — drop orphaned indexed-field columns
+    // =====================================================================
+    {
+      name: "prune-schema",
+      // `admin` — a destructive schema-maintenance op, same tier as
+      // manage-token. Operator-only; hidden from read/write sessions.
+      requiredVerb: "admin",
+      description:
+        "Drop orphaned indexed-field columns + indexes whose declaring tags no longer exist (the result of a deleted tag never releasing its fields). Dry-run by default — returns the drop plan without mutating. Pass `apply: true` to execute. A field co-declared by a still-live tag is never dropped; only the dead declarers are trimmed from its set. Generated columns are derived from notes.metadata JSON, so a drop loses only the index, never source data — declare the field again to rebuild it.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          apply: {
+            type: "boolean",
+            description: "Execute the prune. Default false (dry-run — report what would be dropped without changing anything).",
+          },
+        },
+      },
+      execute: async (params) => {
+        const apply = params.apply === true;
+        const plan = await store.pruneIndexedFields({ dryRun: !apply });
+        const dropped = plan.filter((p) => p.dropped);
+        const trimmed = plan.filter((p) => !p.dropped);
+        return {
+          dry_run: !apply,
+          fields_dropped: dropped.map((p) => ({ field: p.field, dead_declarers: p.deadDeclarers })),
+          fields_trimmed: trimmed.map((p) => ({ field: p.field, dead_declarers: p.deadDeclarers })),
+          summary: apply
+            ? `pruned ${dropped.length} orphaned field(s); trimmed dead declarers on ${trimmed.length} co-declared field(s)`
+            : `would prune ${dropped.length} orphaned field(s); would trim dead declarers on ${trimmed.length} co-declared field(s) — pass apply:true to execute`,
+        };
+      },
+    },
+
   ];
 }
 

package/core/src/notes.ts

@@ -18,6 +18,7 @@ import {
   type CursorPayload,
   type QueryHashInputs,
 } from "./cursor.js";
+import { releaseField } from "./indexed-fields.js";
 
 let idCounter = 0;
 
@@ -943,12 +944,35 @@ export function listTags(db: Database): { name: string; count: number }[] {
 }
 
 export function deleteTag(db: Database, name: string): { deleted: boolean; notes_untagged: number } {
-  const exists = db.prepare("SELECT 1 FROM tags WHERE name = ?").get(name);
-  if (!exists) return { deleted: false, notes_untagged: 0 };
+  const row = db.prepare("SELECT fields FROM tags WHERE name = ?").get(name) as
+    | { fields: string | null }
+    | undefined;
+  if (!row) return { deleted: false, notes_untagged: 0 };
 
   const countRow = db.prepare("SELECT COUNT(*) as c FROM note_tags WHERE tag_name = ?").get(name) as { c: number };
   const notesUntagged = countRow.c;
 
+  // Release any indexed fields this tag declared BEFORE the row drops.
+  // `releaseField` only drops the generated column + index when this tag is
+  // the last live declarer (co-declaration guard) — a field co-declared by
+  // another live tag keeps its column and just loses this tag from the set.
+  // This lives in the store-level delete (not the MCP layer) so every caller
+  // — MCP delete-tag, the REST DELETE /tags/:name route, the import
+  // blow-away sweep — releases consistently. See the gitcoin orphaned-fields
+  // bug report.
+  if (row.fields) {
+    try {
+      const fields = JSON.parse(row.fields) as Record<string, { indexed?: boolean }>;
+      for (const [fieldName, spec] of Object.entries(fields)) {
+        if (spec?.indexed === true) {
+          releaseField(db, fieldName, name);
+        }
+      }
+    } catch {
+      // Malformed fields JSON — nothing to release; proceed with the delete.
+    }
+  }
+
   db.prepare("DELETE FROM note_tags WHERE tag_name = ?").run(name);
   db.prepare("DELETE FROM tags WHERE name = ?").run(name);
 

package/core/src/portable-md.test.ts

@@ -24,6 +24,8 @@ import { join } from "path";
 import { tmpdir } from "os";
 
 import { SqliteStore } from "./store.js";
+import { getIndexedField } from "./indexed-fields.js";
+import { buildVaultProjection } from "./vault-projection.js";
 import {
   CaseCollisionError,
   emitYamlDoc,
@@ -725,6 +727,56 @@ describe("importPortableVault", async () => {
     expect(schema!.description).toBe("A unit of work");
   });
 
+  // Fix 2 — import must re-declare indexed fields. The import writes
+  // tags.fields via upsertTagRecord but historically never materialized the
+  // backing generated columns + indexes, so a fresh import advertised
+  // `indexed: true` while queries silently full-scanned. Regression: export a
+  // vault with an indexed field → fresh import → the generated column + index
+  // exist and the field shows in the vault-info indexed_fields catalog.
+  it("re-declares indexed fields on import (column + index + vault-info catalog)", async () => {
+    await store.upsertTagRecord("project", {
+      fields: { status: { type: "string", indexed: true } },
+    });
+    await store.createNote("p", { id: "p", tags: ["project"], metadata: { status: "active" } });
+    const outDir = join(tmpBase, "out");
+    await exportVaultToDir(store, { outDir, exportedAt: "2026-05-13T00:00:00.000Z" });
+
+    const target = new SqliteStore(new Database(":memory:"));
+    const targetDb = target.db;
+    // Pre-condition: a fresh store has no backing column yet.
+    const colsBefore = (targetDb.prepare("PRAGMA table_xinfo(notes)").all() as { name: string }[]).map((r) => r.name);
+    expect(colsBefore).not.toContain("meta_status");
+
+    const stats = await importPortableVault(target, { inDir: outDir });
+    expect(stats.schemas_restored).toBe(1);
+    expect(stats.indexes_declared).toBe(1);
+
+    // The generated column + index now exist — same introspection vault-info
+    // uses to advertise the queryable-field catalog.
+    const colsAfter = (targetDb.prepare("PRAGMA table_xinfo(notes)").all() as { name: string }[]).map((r) => r.name);
+    expect(colsAfter).toContain("meta_status");
+    const idxs = (targetDb.prepare("SELECT name FROM sqlite_master WHERE type='index' AND tbl_name='notes'").all() as { name: string }[]).map((r) => r.name);
+    expect(idxs).toContain("idx_meta_status");
+    expect(getIndexedField(targetDb, "status")?.declarerTags).toEqual(["project"]);
+    // And vault-info lists it.
+    expect(buildVaultProjection(targetDb).indexed_fields.map((f) => f.name)).toContain("status");
+  });
+
+  it("dry-run import counts indexes_declared without materializing columns", async () => {
+    await store.upsertTagRecord("project", {
+      fields: { status: { type: "string", indexed: true } },
+    });
+    const outDir = join(tmpBase, "out");
+    await exportVaultToDir(store, { outDir, exportedAt: "2026-05-13T00:00:00.000Z" });
+
+    const target = new SqliteStore(new Database(":memory:"));
+    const stats = await importPortableVault(target, { inDir: outDir, dryRun: true });
+    expect(stats.indexes_declared).toBe(1);
+    // Dry-run touches nothing.
+    const cols = (target.db.prepare("PRAGMA table_xinfo(notes)").all() as { name: string }[]).map((r) => r.name);
+    expect(cols).not.toContain("meta_status");
+  });
+
   it("restores typed links (non-wikilink relationships)", async () => {
     await store.createNote("src body", { id: "src", path: "src" });
     await store.createNote("tgt body", { id: "tgt", path: "tgt" });

package/core/src/portable-md.ts

@@ -1535,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;
 }
 
 /**
@@ -1582,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
@@ -2019,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 = 19;
+export const SCHEMA_VERSION = 20;
 
 export const SCHEMA_SQL = `
 -- Notes: the universal record.
@@ -96,6 +96,17 @@ CREATE TABLE IF NOT EXISTS indexed_fields (
 
 -- Tokens: API authentication with OAuth-standard scopes.
 --
+-- VESTIGIAL as of 0.5.0 (vault#282 Stage 2). Vault is a pure hub
+-- resource-server: it no longer mints (pvt_*) or validates rows in this
+-- table — auth runs through hub-issued JWTs + VAULT_AUTH_TOKEN + legacy YAML
+-- api_keys only. The table is KEPT (not dropped) because migrateVaultKeys
+-- raw-INSERTs legacy YAML api_keys here as its import landing zone, and
+-- dropping it would trip an upgrade on a missing column for operators with
+-- leftover rows. A future cosmetic migration may drop it alongside
+-- oauth_clients/oauth_codes. 'tokens list' / 'tokens revoke' (CLI) still
+-- read/delete here for cleanup of leftover rows. See the field docs below for
+-- the historical (pre-0.5.0) semantics.
+--
 -- scopes is a whitespace-separated list of granted scopes (OAuth 2.0 §3.3)
 -- — e.g. "vault:read vault:write". Introduced in v12 alongside enforcement;
 -- NULL rows are pre-v12 tokens which fall back to deriving scopes from the
@@ -128,10 +139,9 @@ CREATE TABLE IF NOT EXISTS indexed_fields (
 -- 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.
+-- revoked_at (v19) marked soft-revocation of vault-DB tokens. Vestigial
+-- post-0.5.0 (vault#282 Stage 2) — the validation path that read it
+-- (resolveToken) was removed alongside the pvt_* mint.
 CREATE TABLE IF NOT EXISTS tokens (
   token_hash TEXT PRIMARY KEY,
   label TEXT NOT NULL,
@@ -149,6 +159,30 @@ CREATE TABLE IF NOT EXISTS tokens (
   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)
 -- VESTIGIAL after vault 0.4.x workstream E (2026-05-25). The standalone
 -- OAuth issuer that wrote these rows was retired (hub is the issuer now;
@@ -214,6 +248,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,9 +418,10 @@ export function initSchema(db: Database): void {
   migrateToV15(db);
 
   // Migrate v15 → v16: add `vault_name` column to tokens. Existing rows
-  // backfill to NULL ("server-wide / legacy" semantic) — auth accepts
-  // NULL for any vault, so today's pvt_* tokens keep working unchanged.
-  // New mints via per-vault routes write the column explicitly. See vault#257.
+  // backfilled to NULL ("server-wide / legacy" semantic) — at the time auth
+  // accepted NULL for any vault so pre-v16 pvt_* tokens kept working. (pvt_*
+  // validation was dropped at 0.5.0 / vault#282 Stage 2; the column is now
+  // vestigial.) See vault#257.
   migrateToV16(db);
 
   // Migrate v16 → v17: rip the standalone `note_schemas` + `schema_mappings`
@@ -403,6 +442,13 @@ export function initSchema(db: Database): void {
   // "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);
@@ -803,12 +849,11 @@ function migrateToV15(db: Database): void {
  * Migrate v15 → v16: per-vault token storage (vault#257).
  *
  * Adds `tokens.vault_name TEXT` (nullable). Existing rows stay NULL —
- * "server-wide / legacy" semantic — and `authenticateVaultRequest`
- * accepts NULL for any vault, so today's pvt_* tokens keep working
- * unchanged. New mints via `/vault/<name>/tokens` write the column
- * explicitly; cross-vault presentation rejects on the row's vault_name
- * mismatch. The complementary index speeds the per-vault listTokens
- * filter in the admin SPA.
+ * "server-wide / legacy" semantic. At the time, `authenticateVaultRequest`
+ * accepted NULL for any vault so pre-v16 pvt_* tokens kept working. (pvt_*
+ * validation + the `/vault/<name>/tokens` mint route were both removed at
+ * 0.5.0 / vault#282 Stage 2 — the column + index are now vestigial; the
+ * index still speeds the per-vault `listTokens` cleanup listing.)
  *
  * Wrapped in BEGIN IMMEDIATE / COMMIT (with try/catch ROLLBACK) per the
  * v14/v15 wrap pattern from vault#251 — the column add and index create
@@ -1001,6 +1046,34 @@ function migrateToV19(db: Database): void {
   }
 }
 
+/**
+ * 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;

package/core/src/store.ts

@@ -4,6 +4,12 @@ import { initSchema } from "./schema.js";
 import * as noteOps from "./notes.js";
 import * as linkOps from "./links.js";
 import * as tagSchemaOps from "./tag-schemas.js";
+import * as indexedFieldOps from "./indexed-fields.js";
+import {
+  pruneOrphanedIndexedFields,
+  reconcileDeclaredIndexes,
+  type PrunedField,
+} from "./indexed-fields.js";
 import { syncWikilinks, resolveUnresolvedWikilinks } from "./wikilinks.js";
 import { pathTitle } from "./paths.js";
 import { HookRegistry } from "./hooks.js";
@@ -503,6 +509,37 @@ export class BunSqliteStore implements Store {
     return tagSchemaOps.getTagSchemaMap(this.db);
   }
 
+  // ---- Indexed-field lifecycle (generated columns + indexes) ----
+
+  /**
+   * Prune orphaned `indexed_fields` declarers — declarer tags that no longer
+   * have a `tags` row. Fields with no surviving live declarer are dropped
+   * wholesale (row + generated column + index); co-declared fields keep their
+   * column and just lose the dead declarers. `dryRun` (default true) returns
+   * the plan without mutating. See the gitcoin orphaned-fields bug.
+   */
+  async pruneIndexedFields(opts?: { dryRun?: boolean }): Promise<PrunedField[]> {
+    const plan = pruneOrphanedIndexedFields(this.db, opts);
+    // A drop changes the queryable-field catalog vault-info advertises; bust
+    // the schema cache so the next read reflects it.
+    if (opts?.dryRun === false && plan.length > 0) this._schemaConfig = null;
+    return plan;
+  }
+
+  /**
+   * Replay `declareField` for every `indexed: true` field across all current
+   * tag records, materializing the generated columns + indexes. Idempotent —
+   * used by the portable-md import path so a fresh import ends with the same
+   * backing columns a live vault would have. Returns the count of (tag, field)
+   * declarations replayed.
+   */
+  async reconcileDeclaredIndexes(): Promise<number> {
+    const schemas = await this.listTagRecords();
+    const count = reconcileDeclaredIndexes(this.db, schemas);
+    if (count > 0) this._schemaConfig = null;
+    return count;
+  }
+
   // ---- Tag Records (post-v14: full identity row) ----
 
   async listTagRecords() {
@@ -517,6 +554,18 @@ export class BunSqliteStore implements Store {
    * Partial upsert of the full tag record. Any patch field left undefined
    * is preserved; pass null to clear. Invalidates the tag-hierarchy cache
    * when `parent_names` is touched.
+   *
+   * Indexed-field lifecycle is reconciled HERE — at the single store
+   * chokepoint every caller (MCP update-tag, REST PUT /tags/:name, import)
+   * funnels through — so no caller can persist a `fields` change without the
+   * matching declareField/releaseField. When `patch.fields` is touched
+   * (object or explicit `null`), the prior-vs-next indexed-field set is
+   * diffed: added indexed fields get `declareField`, removed ones get
+   * `releaseField` (which drops the generated column + index only when this
+   * tag is the last live declarer — the co-declaration guard). `patch.fields
+   * === undefined` (no-touch) skips reconciliation entirely. Centralizing
+   * here is the same discipline as moving delete-release into noteOps.deleteTag
+   * — it closes the REST PUT orphaned-column leak. See the gitcoin bug.
    */
   async upsertTagRecord(
     tag: string,
@@ -527,7 +576,43 @@ export class BunSqliteStore implements Store {
       parent_names?: string[] | null;
     },
   ) {
+    // Snapshot the prior indexed-field set BEFORE the write so the diff below
+    // sees what this tag declared going in. Only needed when `fields` changes.
+    const priorRecord =
+      patch.fields !== undefined ? tagSchemaOps.getTagRecord(this.db, tag) : null;
+
     const result = tagSchemaOps.upsertTagRecord(this.db, tag, patch);
+
+    if (patch.fields !== undefined) {
+      const indexedSet = (fields: Record<string, tagSchemaOps.TagFieldSchema> | null | undefined) =>
+        new Set(
+          Object.entries(fields ?? {})
+            .filter(([, v]) => v.indexed === true)
+            .map(([k]) => k),
+        );
+      const nextFields = patch.fields; // object | null
+      const priorIndexed = indexedSet(priorRecord?.fields);
+      const nextIndexed = indexedSet(nextFields);
+      for (const fieldName of nextIndexed) {
+        const spec = nextFields![fieldName]!;
+        const mapped = indexedFieldOps.mapFieldType(spec.type);
+        // Unmappable type for indexing is a caller error; surface it rather
+        // than silently skipping. MCP/REST validate up-front for a cleaner
+        // message, but this is the backstop at the chokepoint.
+        if (!mapped) {
+          throw new indexedFieldOps.IndexedFieldError(
+            `field "${fieldName}" has unsupported type "${spec.type}" for indexing (supported: string, integer, boolean)`,
+          );
+        }
+        indexedFieldOps.declareField(this.db, fieldName, mapped, tag);
+      }
+      for (const fieldName of priorIndexed) {
+        if (!nextIndexed.has(fieldName)) {
+          indexedFieldOps.releaseField(this.db, fieldName, tag);
+        }
+      }
+    }
+
     if (patch.parent_names !== undefined) {
       // parent_names drives both query expansion (tag hierarchy) AND, post
       // vault#270, schema inheritance — bust both caches.
@@ -687,6 +772,38 @@ export class BunSqliteStore implements Store {
     };
   }
 
+  /**
+   * Reverse-lookup: every attachment row whose `path` column equals the given
+   * vault-internal relative path (`<date>/<filename>`). A single on-disk asset
+   * can be referenced by more than one attachment row (the orphan check in
+   * `deleteAttachment` accounts for that), so this returns an array. Used by
+   * the raw `/api/storage/<date>/<file>` byte-serve path to map a requested
+   * file back to its owning note(s) for tag-scope enforcement — without this,
+   * a tag-scoped token could fetch an out-of-scope note's attachment bytes
+   * directly by path (the path-secrecy-only bypass; see the C0 adversarial
+   * audit finding).
+   */
+  async getAttachmentsByPath(path: string): Promise<Attachment[]> {
+    const rows = this.db.prepare(
+      "SELECT * FROM attachments WHERE path = ? ORDER BY created_at",
+    ).all(path) as { id: string; note_id: string; path: string; mime_type: string; metadata: string | null; created_at: string }[];
+
+    return rows.map((r) => {
+      let metadata: Record<string, unknown> | undefined;
+      if (r.metadata && r.metadata !== "{}") {
+        try { metadata = JSON.parse(r.metadata); } catch {}
+      }
+      return {
+        id: r.id,
+        noteId: r.note_id,
+        path: r.path,
+        mimeType: r.mime_type,
+        metadata,
+        createdAt: r.created_at,
+      };
+    });
+  }
+
   /**
    * Replace the attachment's metadata JSON blob. The caller passes the full
    * merged object — this is a set, not a patch, so partial-field updates