@openparachute/vault 0.4.9-rc.8 → 0.5.0-rc.1

package/README.md

@@ -93,13 +93,13 @@ The daemon binds `0.0.0.0:1940` (or whatever you set in `PORT`) and serves REST,
 
 ### `~/.claude.json`
 
-`vault init` adds one entry — `mcpServers["parachute-vault"]` — pointing at `http://127.0.0.1:<port>/vault/<default-vault>/mcp` with a baked-in `Authorization: Bearer pvt_...` header. Next Claude Code session picks it up; there's no further wiring. See [Connecting a client](#connecting-a-client) for rotating that token or pointing it elsewhere.
+`vault init` adds one entry — `mcpServers["parachute-vault"]` — pointing at `http://127.0.0.1:<port>/vault/<default-vault>/mcp` with a baked-in `Authorization: Bearer <hub-jwt>` header (a hub-minted JWT — vault#282 Stage 2). Next Claude Code session picks it up; there's no further wiring. See [Connecting a client](#connecting-a-client) for rotating that token or pointing it elsewhere.
 
 ### Your API token
 
-`vault init` asks two explicit questions: (1) install vault as an MCP server in `~/.claude.json`? (2) also surface the API token so you can paste it into other MCP clients (Codex, Goose, OpenCode, Cursor, Zed, Cline), scripts, or `curl`? Both default yes. Pass `--mcp` / `--no-mcp` and `--token` / `--no-token` for non-interactive installs.
+`vault init` asks two explicit questions: (1) install vault as an MCP server in `~/.claude.json`? (2) also surface the access token so you can paste it into other MCP clients (Codex, Goose, OpenCode, Cursor, Zed, Cline), scripts, or `curl`? Both default yes. Pass `--mcp` / `--no-mcp` and `--token` / `--no-token` for non-interactive installs.
 
-If you said yes to (2), the `pvt_...` token is printed prominently at the end — it's the same token baked into `~/.claude.json` (if you also said yes to (1)). It's not stored anywhere retrievable — save it if you need it for `curl`, cron, or any other script. Lost it? Just mint a new one: `parachute-vault tokens create`. Tokens are SHA-256 hashed at rest in each vault's `vault.db`.
+If you said yes to (2), the hub-issued JWT is printed prominently at the end — it's the same token baked into `~/.claude.json` (if you also said yes to (1)). It's not stored anywhere retrievable — save it if you need it for `curl`, cron, or any other script. Lost it? Mint a fresh one with `parachute auth mint-token --scope vault:<name>:<verb>` (or rewire an MCP client with `parachute-vault mcp-install`, or use the admin SPA Tokens page). As of vault 0.5.0 (vault#282 Stage 2) vault no longer mints its own `pvt_*` tokens — minting is the hub's job.
 
 ### OAuth lives on the hub
 
@@ -120,13 +120,13 @@ Two ways to authenticate — pick based on the client, not the deployment:
 | Path | When to use | User action |
 |---|---|---|
 | **OAuth 2.1 + PKCE (browser flow, via hub)** | Claude Desktop, Parachute Daily, any third-party MCP client set up interactively | Click "Add integration", enter the vault MCP URL, a browser opens to the **hub's** consent page, sign in with hub credentials, done — no token ever touches your clipboard |
-| **Bearer token** | Claude Code (auto-wired by `vault init`), CLI scripts, cron jobs, any non-interactive caller | `curl -H "Authorization: Bearer pvt_..."` — the token is printed once at `vault init` (save it) or minted on demand with `parachute-vault tokens create` |
+| **Bearer token (hub JWT)** | Claude Code (auto-wired by `vault init`), CLI scripts, cron jobs, any non-interactive caller | `curl -H "Authorization: Bearer <hub-jwt>"` — mint one with `parachute-vault mcp-install` (MCP clients) or `parachute auth mint-token --scope vault:<name>:<verb>` (scripts) |
 
-The OAuth path mints a hub-signed JWT that vault validates against the hub's JWKS. The bearer-token path mints a `pvt_` opaque token straight from vault's local DB. Either works for any client; pick based on whether you want a human-driven consent step.
+As of 0.5.0 (vault#282 Stage 2) vault is a **pure hub resource-server**: both paths use a hub-signed JWT that vault validates against the hub's JWKS. (The OAuth path is the interactive browser handshake; the bearer path mints the same kind of JWT non-interactively.) The old vault-local `pvt_*` opaque token was dropped — vault no longer mints or accepts it. The server-wide `VAULT_AUTH_TOKEN` operator bearer remains for the no-granular-auth / cross-container path.
 
 ### Claude Code
 
-`vault init` fully auto-configures `~/.claude.json` — there's nothing else to do. The entry it writes uses a baked-in `pvt_` token rather than OAuth:
+`vault init` fully auto-configures `~/.claude.json` — there's nothing else to do. The entry it writes bakes in a hub-minted JWT rather than running the interactive OAuth browser flow:
 
 ```json
 {
@@ -134,13 +134,13 @@ The OAuth path mints a hub-signed JWT that vault validates against the hub's JWK
     "parachute-vault": {
       "type": "http",
       "url": "http://127.0.0.1:1940/vault/{name}/mcp",
-      "headers": { "Authorization": "Bearer pvt_..." }
+      "headers": { "Authorization": "Bearer <hub-jwt>" }
     }
   }
 }
 ```
 
-Where `{name}` is `default` on a fresh install, or whatever vault you pointed `vault init` at. **First MCP call after `vault init` requires no browser handoff — Claude Code uses the baked-in token and the vault's tools show up in your next session.** This is intentional: for an owner connecting their own machine's vault to their own Claude Code, the token is already there and OAuth would add friction.
+Where `{name}` is `default` on a fresh install, or whatever vault you pointed `vault init` at. **First MCP call after `vault init` requires no browser handoff — Claude Code uses the baked-in token and the vault's tools show up in your next session.** This is intentional: for an owner connecting their own machine's vault to their own Claude Code, the token is already there and the OAuth browser handshake would add friction.
 
 To re-point Claude Code at a different vault, change `default_vault` in `~/.parachute/vault/config.yaml` and re-run `parachute-vault init` — which re-mints an API token and re-writes the `~/.claude.json` entry end-to-end. To rotate the token only, run `parachute-vault mcp-install` (defaults to `--mint`, which mints a fresh scope-narrow hub JWT via `~/.parachute/operator.token` and writes it into `~/.claude.json` with an `Authorization: Bearer …` header). See the [cookbook](#install-vault-mcp-into-a-client-config) section below for the full flag surface — token paste, scope narrowing, project-level install, multi-vault.
 
@@ -154,7 +154,7 @@ For Claude Desktop — or any install where the server is on a different machine
 4. Sign in to the hub with your hub credentials, pick a scope (`full` or `read`), click Authorize.
 5. Browser redirects back. The connection is live. The client now holds a hub-signed JWT scoped to this vault.
 
-If you'd rather skip OAuth — e.g. you're scripting the setup — Claude Desktop also accepts a bearer token via the integration's auth header field. Use a token from `parachute-vault tokens create` (or the one from `vault init` if you still have it). This is the "manual bearer" fallback; OAuth is the recommended path.
+If you'd rather skip the browser flow — e.g. you're scripting the setup — Claude Desktop also accepts a bearer token via the integration's auth header field. Mint a hub JWT with `parachute auth mint-token --scope vault:<name>:<verb>` (or the admin SPA Tokens page), or reuse the one from `vault init` if you still have it. This is the "manual bearer" fallback; the OAuth browser flow is the recommended path.
 
 ### Parachute Daily (mobile)
 
@@ -194,8 +194,7 @@ parachute-vault create work                # create a new vault
 parachute-vault list                       # list all vaults (alias: `ls`)
 parachute-vault remove work --yes          # delete a vault (alias: `rm`)
 parachute-vault mcp-install                # (re)write the MCP client entry; defaults to --mint (hub-issued JWT) at local scope
-parachute-vault mcp-install --token <t>    # paste an existing bearer instead of minting
-parachute-vault mcp-install --legacy-pat   # mint a vault-DB pvt_* (self-hosted-without-hub)
+parachute-vault mcp-install --token <t>    # paste an existing bearer (hub JWT or VAULT_AUTH_TOKEN) instead of minting
 parachute-vault mcp-install --install-scope user      # write ~/.claude.json top-level (every project)
 parachute-vault mcp-install --install-scope local     # write ~/.claude.json projects[<cwd>] (this directory only — default)
 parachute-vault mcp-install --install-scope project   # write ./.mcp.json (checked into the repo)
@@ -217,14 +216,11 @@ parachute-vault 2fa enroll                 # enroll TOTP (shows QR + prints one-
 parachute-vault 2fa disable                # disable 2FA
 parachute-vault 2fa backup-codes           # regenerate backup codes
 
-# Tokens
-parachute-vault tokens                     # list all tokens across all vaults
-parachute-vault tokens create                                 # full-access token in the default vault
-parachute-vault tokens create --vault work                    # ...in a specific vault
-parachute-vault tokens create --read                          # read-only token
-parachute-vault tokens create --expires 30d                   # expiring token (N{h|d|w|m|y})
-parachute-vault tokens create --label mobile                  # labeled token
-parachute-vault tokens revoke <token-id>                      # revoke (default vault; add --vault to target)
+# Tokens — vault#282 Stage 2: vault no longer mints its own tokens. Mint a
+# hub JWT with `parachute-vault mcp-install` (MCP clients) or
+# `parachute auth mint-token --scope vault:<name>:<verb>` (scripts).
+parachute-vault tokens                     # list any vestigial pre-0.5.0 token rows (all vaults)
+parachute-vault tokens revoke <token-id>   # revoke a vestigial row (default vault; add --vault to target)
 
 # Obsidian
 parachute-vault import ~/Obsidian/MyVault              # import into default vault
@@ -445,7 +441,7 @@ On Linux, scheduled runs via systemd timers are a follow-up; for now `parachute-
 Serve notes as clean HTML pages at `/view/:noteId`:
 
 - **Without auth**: only serves notes tagged `published` (or with `metadata.published: true`). Returns 404 for unpublished notes.
-- **With auth**: serves any note. Pass your token via `Authorization: Bearer pvt_...` header or `?key=pvt_...` query param.
+- **With auth**: serves any note. Pass your token via `Authorization: Bearer <hub-jwt>` header or `?key=<hub-jwt>` query param.
 - **Custom tag**: set `published_tag` in vault.yaml to use a different tag name (default: `publish`).
 
 ```yaml
@@ -535,7 +531,7 @@ The SSG / sync pattern. Two equivalent forms — bracket-style is canonical goin
 curl -H "Authorization: Bearer $VAULT_TOKEN" \
   "http://localhost:1940/vault/default/api/notes?meta[updated_at][gte]=2026-04-01T00:00:00Z"
 
-# Flat form (DEPRECATED in 0.4.3; planned removal 0.6.0 per vault#288)
+# Flat form (DEPRECATED in 0.4.3; planned removal in a later 0.x per vault#288)
 curl -H "Authorization: Bearer $VAULT_TOKEN" \
   "http://localhost:1940/vault/default/api/notes?date_field=updated_at&date_from=2026-04-01T00:00:00Z"
 ```
@@ -613,7 +609,7 @@ The shortest path to a public HTTPS URL for a vault you control — useful for S
 
 ### Install vault MCP into a client config
 
-Bare `parachute-vault mcp-install` from a terminal **walks you through a short contextual conversation** — picks defaults informed by your environment (how many vaults you have, whether the hub is reachable, whether you're in a project directory, whether vault is already installed somewhere), shows the JSON shape it will write before doing anything, and asks before each non-obvious choice. The patterns below are the non-interactive shapes — pass any flag (`--mint`, `--token`, `--scope`, `--install-scope`, `--vault`, `--legacy-pat`) and the walkthrough is skipped.
+Bare `parachute-vault mcp-install` from a terminal **walks you through a short contextual conversation** — picks defaults informed by your environment (how many vaults you have, whether the hub is reachable, whether you're in a project directory, whether vault is already installed somewhere), shows the JSON shape it will write before doing anything, and asks before each non-obvious choice. The patterns below are the non-interactive shapes — pass any flag (`--mint`, `--token`, `--scope`, `--install-scope`, `--vault`) and the walkthrough is skipped.
 
 #### Install scopes
 
@@ -646,15 +642,12 @@ parachute-vault mcp-install --install-scope user
 #    project actually mutates the vault.
 parachute-vault mcp-install --install-scope project --scope vault:write
 
-# 4. Paste an existing token — useful when you already have a pvt_* in hand
-#    or want to re-use a long-lived bearer from another machine. Skips the
-#    mint step entirely.
-parachute-vault mcp-install --token pvt_abc123...
-
-# 5. Self-hosted-without-hub — mint a vault-DB pvt_* token (the legacy
-#    path; preserved so deployments without a hub keep working). Prints a
-#    deprecation notice.
-parachute-vault mcp-install --legacy-pat
+# 4. Paste an existing bearer — useful when you already have a hub JWT in
+#    hand, or want to re-use the VAULT_AUTH_TOKEN operator bearer / a
+#    long-lived JWT from another machine. Skips the mint step entirely.
+#    (vault#282 Stage 2 removed the --legacy-pat pvt_* path — without a hub,
+#    paste a bearer here or set VAULT_AUTH_TOKEN.)
+parachute-vault mcp-install --token <hub-jwt-or-operator-bearer>
 ```
 
 **Multi-vault.** `--vault <name>` targets a specific vault and writes the entry under `parachute-vault-<name>` so multiple vaults coexist. Without `--vault`, the singular `parachute-vault` slot is used and one install clobbers another — that's intentional for the common single-vault case.
@@ -671,8 +664,9 @@ parachute-vault mcp-install --legacy-pat
 2. **`--mcp-config` JSON is per-runner boilerplate.** Some runners prefer to inline the MCP config rather than mutate the user's Claude Code state. `parachute-vault mcp-config <vault-name>` emits exactly the JSON shape `--mcp-config` consumes:
 
 ```bash
-# Mint or fetch a vault-scoped token first, then:
-export PARACHUTE_VAULT_TOKEN=pvt_...
+# Mint a vault-scoped hub JWT first (parachute auth mint-token --scope
+# vault:gitcoin:read), then:
+export PARACHUTE_VAULT_TOKEN=<hub-jwt>
 claude -p --mcp-config "$(parachute-vault mcp-config gitcoin)" \
           --strict-mcp-config \
           "Summarize the latest notes under projects/gitcoin"
@@ -681,7 +675,7 @@ claude -p --mcp-config "$(parachute-vault mcp-config gitcoin)" \
 parachute-vault mcp-config gitcoin --env-vars > .claude/mcp-gitcoin.json
 # ...then later, when invoking claude:
 export PARACHUTE_HUB_URL=http://127.0.0.1:1940
-export PARACHUTE_VAULT_TOKEN=pvt_...
+export PARACHUTE_VAULT_TOKEN=<hub-jwt>
 claude -p --mcp-config "$(envsubst < .claude/mcp-gitcoin.json)" \
           --strict-mcp-config ...
 ```
@@ -710,43 +704,46 @@ For wiring up an AI client (Claude Code, Claude Desktop, Parachute Daily), see [
 
 ### Passing the key
 
-Tokens come in two shapes. Both work interchangeably at every authenticated endpoint:
+As of 0.5.0 (vault#282 Stage 2) vault accepts these bearers at every authenticated endpoint:
+
+- **Hub-issued JWT** (`eyJ...`) — the user-credential path; what OAuth issues and what `parachute-vault mcp-install` / `parachute auth mint-token` produce. Audience-bound to `vault.<name>`, scope-narrowed (`vault:<name>:<verb>`).
+- **`VAULT_AUTH_TOKEN`** — the server-wide operator bearer (env var; full-admin against any vault on the server).
+- **`pvk_...`** — legacy global API keys from `config.yaml` / per-vault `vault.yaml` (still honored for existing deployments).
 
-- `pvt_...` — per-vault scoped tokens (the modern format; what `vault init` mints, what OAuth issues, what `parachute-vault tokens create` produces)
-- `pvk_...` — legacy global API keys from `config.yaml` (still honored for existing deployments)
+The old vault-local `pvt_*` opaque token was **dropped at 0.5.0** — vault no longer mints or accepts it.
 
 ```bash
 # Header (preferred)
-curl -H "Authorization: Bearer pvt_..." http://localhost:1940/vault/default/api/notes
+curl -H "Authorization: Bearer <hub-jwt>" http://localhost:1940/vault/default/api/notes
 
 # Alternative header
-curl -H "X-API-Key: pvt_..." http://localhost:1940/vault/default/api/notes
+curl -H "X-API-Key: <hub-jwt>" http://localhost:1940/vault/default/api/notes
 
 # Query param (for /view endpoint only — convenient for browsers)
-curl http://localhost:1940/vault/default/view/noteId?key=pvt_...
+curl http://localhost:1940/vault/default/view/noteId?key=<hub-jwt>
 ```
 
 ### Token management
 
-Per-vault tokens with two permission levels:
-
-| Permission | Can do |
-|---|---|
-| `full` | Everything (CRUD + delete + token management) |
-| `read` | Query, list, find-path, vault-info only |
+Tokens are hub-issued JWTs (vault#282 Stage 2 — vault no longer mints its own).
+Mint and revoke happen on the hub:
 
 ```bash
-parachute-vault tokens                                        # list all tokens
-parachute-vault tokens create --vault work                    # full-access token
-parachute-vault tokens create --vault work --read             # read-only
-parachute-vault tokens create --vault work --expires 30d      # with expiry
-parachute-vault tokens create --vault work --label phone      # labeled token
-parachute-vault tokens revoke <token-id> --vault work         # revoke
+parachute-vault mcp-install --scope vault:write   # mint + wire a hub JWT into an MCP client
+parachute auth mint-token --scope vault:<name>:<verb>   # mint a scoped JWT for scripts
+parachute auth tokens                              # list / revoke hub JWTs (hub registry)
 ```
 
-Tokens are shown once at creation — save them immediately. SHA-256 hashed at rest.
+Two permission levels carry through the JWT scope verb:
+
+| Verb | Can do |
+|---|---|
+| `admin` / `write` → `full` | Everything (CRUD + delete + token management) |
+| `read` | Query, list, find-path, vault-info only |
 
-Legacy API keys (`pvk_...`) from config.yaml still work at runtime but the `vault keys` CLI commands have been removed. Use `vault tokens` for all new keys.
+`parachute-vault tokens list` / `tokens revoke` remain only to clean up any
+vestigial pre-0.5.0 rows. Legacy `pvk_...` keys from config.yaml still work at
+runtime; the `vault keys` CLI commands were removed long ago.
 
 ### Public endpoints
 

package/core/src/core.test.ts

@@ -1944,6 +1944,9 @@ describe("MCP tools", async () => {
     expect(names).toContain("delete-tag");
     expect(names).toContain("find-path");
     expect(names).toContain("vault-info");
+    // prune-schema (admin) — drops orphaned indexed-field columns whose
+    // declaring tags are gone. The gitcoin orphaned-fields fix.
+    expect(names).toContain("prune-schema");
     // Six note-schema tools (list/update/delete-note-schema +
     // list/set/delete-schema-mapping) retired in v17 — the standalone
     // note_schemas + schema_mappings subsystem was a parallel path to
@@ -1957,7 +1960,7 @@ describe("MCP tools", async () => {
     // synthesize-notes retired in v17 — replicable with query-notes(near=) +
     // find-path + agent-side aggregation. See vault#268.
     expect(names).not.toContain("synthesize-notes");
-    expect(tools).toHaveLength(9);
+    expect(tools).toHaveLength(10);
   });
 
   it("create-note tool works", async () => {

package/core/src/indexed-fields.test.ts

@@ -7,11 +7,13 @@ import {
   declareField,
   getIndexedField,
   listIndexedFields,
+  pruneOrphanedIndexedFields,
   rebuildIndexes,
   releaseField,
   TYPE_MAP,
   validateFieldName,
 } from "./indexed-fields.js";
+import { buildVaultProjection } from "./vault-projection.js";
 
 let db: Database;
 let store: SqliteStore;
@@ -282,4 +284,153 @@ describe("delete-tag: indexed fields", () => {
     expect(getIndexedField(db, "status")?.declarerTags).toEqual(["ticket"]);
     expect(notesColumns()).toContain("meta_status");
   });
+
+  // Bug 1b — the release lives in store.deleteTag now (not the MCP layer), so
+  // every delete entry point releases. Co-declaration sequencing: deleting the
+  // FIRST co-declarer keeps the column; deleting the SECOND drops it.
+  it("co-declaration: delete A keeps column (B holds), then delete B drops it", async () => {
+    const update = findTool("update-tag");
+    const del = findTool("delete-tag");
+    await update.execute({ tag: "asset", fields: { aspect_ratio: { type: "string", indexed: true } } });
+    await update.execute({ tag: "storyboard", fields: { aspect_ratio: { type: "string", indexed: true } } });
+
+    await del.execute({ tag: "asset" });
+    expect(getIndexedField(db, "aspect_ratio")?.declarerTags).toEqual(["storyboard"]);
+    expect(notesColumns()).toContain("meta_aspect_ratio");
+
+    await del.execute({ tag: "storyboard" });
+    expect(getIndexedField(db, "aspect_ratio")).toBeNull();
+    expect(notesColumns()).not.toContain("meta_aspect_ratio");
+    expect(notesIndexes()).not.toContain("idx_meta_aspect_ratio");
+  });
+});
+
+// ===========================================================================
+// Bug 1a — update-tag {fields: null} clears all of this tag's field schemas,
+// dropping the exclusively-declared columns + indexes. `null` (clear-all) must
+// be distinguished from `undefined` (no change). The gitcoin orphaned-fields
+// bug was that `?? {}` collapsed null to a no-op.
+// ===========================================================================
+describe("update-tag: fields null vs undefined", () => {
+  it("fields:null drops the tag's exclusively-declared columns + indexed_fields rows", async () => {
+    const update = findTool("update-tag");
+    await update.execute({
+      tag: "project",
+      fields: { status: { type: "string", indexed: true }, priority: { type: "integer", indexed: true } },
+    });
+    expect(notesColumns()).toContain("meta_status");
+    expect(notesColumns()).toContain("meta_priority");
+
+    await update.execute({ tag: "project", fields: null });
+
+    expect(getIndexedField(db, "status")).toBeNull();
+    expect(getIndexedField(db, "priority")).toBeNull();
+    expect(notesColumns()).not.toContain("meta_status");
+    expect(notesColumns()).not.toContain("meta_priority");
+    expect(notesIndexes()).not.toContain("idx_meta_status");
+    // The tag's fields column is cleared too.
+    const rec = await store.getTagRecord("project");
+    expect(rec?.fields ?? null).toBeNull();
+  });
+
+  it("fields:null no longer lists the fields in the vault-info indexed_fields catalog", async () => {
+    const update = findTool("update-tag");
+    await update.execute({ tag: "project", fields: { status: { type: "string", indexed: true } } });
+    expect(buildVaultProjection(db).indexed_fields.map((f) => f.name)).toContain("status");
+
+    await update.execute({ tag: "project", fields: null });
+    expect(buildVaultProjection(db).indexed_fields.map((f) => f.name)).not.toContain("status");
+  });
+
+  it("fields:undefined is a no-op — preserves existing field schemas + columns", async () => {
+    const update = findTool("update-tag");
+    await update.execute({ tag: "project", fields: { status: { type: "string", indexed: true } } });
+    // Update only the description; omit fields entirely.
+    await update.execute({ tag: "project", description: "a project" });
+    expect(getIndexedField(db, "status")?.declarerTags).toEqual(["project"]);
+    expect(notesColumns()).toContain("meta_status");
+  });
+
+  it("fields:null respects co-declaration — keeps a field another live tag still declares", async () => {
+    const update = findTool("update-tag");
+    await update.execute({ tag: "asset", fields: { aspect_ratio: { type: "string", indexed: true } } });
+    await update.execute({ tag: "storyboard", fields: { aspect_ratio: { type: "string", indexed: true } } });
+
+    await update.execute({ tag: "asset", fields: null });
+    expect(getIndexedField(db, "aspect_ratio")?.declarerTags).toEqual(["storyboard"]);
+    expect(notesColumns()).toContain("meta_aspect_ratio");
+  });
+});
+
+// ===========================================================================
+// Bug 1c — prune for ALREADY-orphaned fields. The gitcoin case: an
+// indexed_fields row whose every declarer tag has no `tags` row (orphaned by a
+// pre-fix delete/clear that never released). prune finds + drops them; it must
+// NOT touch fields with a live declarer.
+// ===========================================================================
+describe("pruneOrphanedIndexedFields", () => {
+  // Seed an orphaned field directly: declare via the API (creates the tag
+  // row + column), then delete the tag row out from under it WITHOUT going
+  // through the release path — exactly the pre-fix orphaned state.
+  function orphanField(field: string, type: "TEXT" | "INTEGER", tag: string) {
+    declareField(db, field, type, tag);
+    // Drop the tags row directly — simulating the pre-fix delete-tag that
+    // never released. The indexed_fields row + column survive (orphaned).
+    db.prepare("DELETE FROM tags WHERE name = ?").run(tag);
+  }
+
+  it("dry-run reports the orphan without mutating", async () => {
+    orphanField("legacy_status", "TEXT", "ghost");
+    expect(notesColumns()).toContain("meta_legacy_status");
+
+    const plan = pruneOrphanedIndexedFields(db, { dryRun: true });
+    expect(plan).toEqual([{ field: "legacy_status", deadDeclarers: ["ghost"], dropped: true }]);
+    // Nothing changed.
+    expect(getIndexedField(db, "legacy_status")).not.toBeNull();
+    expect(notesColumns()).toContain("meta_legacy_status");
+  });
+
+  it("apply drops the orphaned column + index + row", async () => {
+    orphanField("legacy_status", "TEXT", "ghost");
+    const plan = pruneOrphanedIndexedFields(db, { dryRun: false });
+    expect(plan).toEqual([{ field: "legacy_status", deadDeclarers: ["ghost"], dropped: true }]);
+    expect(getIndexedField(db, "legacy_status")).toBeNull();
+    expect(notesColumns()).not.toContain("meta_legacy_status");
+    expect(notesIndexes()).not.toContain("idx_meta_legacy_status");
+    // No longer advertised by vault-info.
+    expect(buildVaultProjection(db).indexed_fields.map((f) => f.name)).not.toContain("legacy_status");
+  });
+
+  it("does NOT touch a field with a live declarer", async () => {
+    const update = findTool("update-tag");
+    await update.execute({ tag: "project", fields: { status: { type: "string", indexed: true } } });
+    const plan = pruneOrphanedIndexedFields(db, { dryRun: false });
+    expect(plan).toEqual([]);
+    expect(getIndexedField(db, "status")?.declarerTags).toEqual(["project"]);
+    expect(notesColumns()).toContain("meta_status");
+  });
+
+  it("trims dead declarers but keeps the column when a live co-declarer remains", async () => {
+    const update = findTool("update-tag");
+    // Two declarers, then orphan only one by deleting its tag row directly.
+    await update.execute({ tag: "asset", fields: { aspect_ratio: { type: "string", indexed: true } } });
+    await update.execute({ tag: "storyboard", fields: { aspect_ratio: { type: "string", indexed: true } } });
+    db.prepare("DELETE FROM tags WHERE name = ?").run("asset"); // orphan one declarer
+
+    const plan = pruneOrphanedIndexedFields(db, { dryRun: false });
+    expect(plan).toEqual([{ field: "aspect_ratio", deadDeclarers: ["asset"], dropped: false }]);
+    // Column kept; storyboard still declares it; asset trimmed from the set.
+    expect(getIndexedField(db, "aspect_ratio")?.declarerTags).toEqual(["storyboard"]);
+    expect(notesColumns()).toContain("meta_aspect_ratio");
+  });
+
+  it("store.pruneIndexedFields surfaces the same plan", async () => {
+    orphanField("legacy_status", "TEXT", "ghost");
+    const dry = await store.pruneIndexedFields({ dryRun: true });
+    expect(dry).toEqual([{ field: "legacy_status", deadDeclarers: ["ghost"], dropped: true }]);
+    expect(getIndexedField(db, "legacy_status")).not.toBeNull(); // dry-run didn't mutate
+    const applied = await store.pruneIndexedFields({ dryRun: false });
+    expect(applied).toEqual([{ field: "legacy_status", deadDeclarers: ["ghost"], dropped: true }]);
+    expect(getIndexedField(db, "legacy_status")).toBeNull();
+  });
 });

package/core/src/indexed-fields.ts

@@ -236,3 +236,101 @@ export function rebuildIndexes(db: Database): void {
     }
   }
 }
+
+export interface PrunedField {
+  /** The field whose `indexed_fields` row was affected. */
+  field: string;
+  /** Declarer tags that no longer have a `tags` row (removed from the set). */
+  deadDeclarers: string[];
+  /**
+   * True when the field had NO surviving live declarer and was fully dropped
+   * (row + generated column + index). False when at least one live declarer
+   * remained and only the dead declarers were pruned from the set.
+   */
+  dropped: boolean;
+}
+
+/**
+ * Prune orphaned `indexed_fields` declarers — the gitcoin defect.
+ *
+ * A declarer tag is "dead" when no `tags` row carries that name (the tag was
+ * deleted, or its schema was cleared, without releasing the field). For every
+ * `indexed_fields` row:
+ *
+ *   - Drop dead declarers from the set.
+ *   - If NO live declarer remains, drop the whole field — row + generated
+ *     column + index. This is the only data-loss-free drop: the generated
+ *     column is `json_extract(metadata, …)` so the source values stay in
+ *     `notes.metadata`; only the (now-dead) index is lost.
+ *   - If at least one live declarer remains (co-declaration), keep the column
+ *     and just trim the dead names from the declarer set.
+ *
+ * `dryRun` (default) computes the plan without mutating; pass `dryRun: false`
+ * to apply. Returns the per-field plan either way so the CLI / MCP surface can
+ * print what it would (or did) drop.
+ */
+export function pruneOrphanedIndexedFields(
+  db: Database,
+  opts: { dryRun?: boolean } = {},
+): PrunedField[] {
+  const dryRun = opts.dryRun ?? true;
+  const liveTags = new Set(
+    (db.prepare("SELECT name FROM tags").all() as { name: string }[]).map((r) => r.name),
+  );
+  const plan: PrunedField[] = [];
+  for (const f of listIndexedFields(db)) {
+    const deadDeclarers = f.declarerTags.filter((t) => !liveTags.has(t));
+    if (deadDeclarers.length === 0) continue; // every declarer is live — leave it
+    const liveDeclarers = f.declarerTags.filter((t) => liveTags.has(t));
+    const dropped = liveDeclarers.length === 0;
+    plan.push({ field: f.field, deadDeclarers, dropped });
+    if (dryRun) continue;
+    if (dropped) {
+      db.prepare("DELETE FROM indexed_fields WHERE field = ?").run(f.field);
+      dropColumnAndIndex(db, f.field);
+    } else {
+      db.prepare("UPDATE indexed_fields SET declarer_tags = ? WHERE field = ?").run(
+        JSON.stringify(liveDeclarers),
+        f.field,
+      );
+    }
+  }
+  return plan;
+}
+
+/**
+ * Replay `declareField` for every field a tag schema marks `indexed: true`.
+ * Idempotent — used by the portable-md import path so a fresh import ends with
+ * the same generated columns a live vault would have (the import writes
+ * `tags.fields` via `upsertTagRecord` but never materializes the backing
+ * columns). Without this, an imported vault's schemas say `indexed: true` but
+ * queries fall back to full scans until each tag is next `update-tag`'d.
+ *
+ * `tagSchemas` is the post-import set of (tag, fields) pairs. Returns the
+ * number of (tag, field) declarations replayed.
+ */
+export function reconcileDeclaredIndexes(
+  db: Database,
+  tagSchemas: { tag: string; fields?: Record<string, { type: string; indexed?: boolean }> }[],
+): number {
+  let declared = 0;
+  for (const schema of tagSchemas) {
+    if (!schema.fields) continue;
+    for (const [fieldName, spec] of Object.entries(schema.fields)) {
+      if (spec.indexed !== true) continue;
+      const mapped = mapFieldType(spec.type);
+      if (!mapped) continue; // unsupported type for indexing — skip, don't throw
+      try {
+        validateFieldName(fieldName);
+        declareField(db, fieldName, mapped, schema.tag);
+        declared++;
+      } catch (err) {
+        console.error(
+          `[indexed-fields] could not re-declare "${fieldName}" for tag "${schema.tag}" on import:`,
+          err,
+        );
+      }
+    }
+  }
+  return declared;
+}