@openparachute/vault 0.4.8 → 0.4.9-rc.11

package/core/src/hooks.ts

@@ -47,7 +47,34 @@
 
 import type { Note, Store, Attachment } from "./types.js";
 
-export type HookEvent = "created" | "updated";
+/**
+ * Note-mutation events. `"created"` and `"updated"` carry the full post-write
+ * `Note`; `"deleted"` carries only `{ id, path }` — the row is gone by
+ * dispatch time, so handlers can't re-read it. Down-stream consumers (e.g.
+ * the git-mirror) match by id/path and react (remove file, etc.). Predicate
+ * authors writing a `when(note)` for `"deleted"` should rely on `note.id` /
+ * `note.path` only; everything else is undefined for the deleted shape.
+ */
+export type HookEvent = "created" | "updated" | "deleted";
+
+/**
+ * Minimal identity payload for a deleted note. The row is gone by dispatch
+ * time, so handlers can't go back to the store for the rest. Path is
+ * optional because notes without a path are legal (e.g. fragments captured
+ * via API without a target slot).
+ */
+export interface DeletedNoteRef {
+  id: string;
+  path?: string;
+}
+
+/**
+ * What a hook handler receives. For `"created"` / `"updated"` it's the full
+ * `Note` row; for `"deleted"` only the id/path remain. This union keeps the
+ * common predicates (path-prefix gates, tag checks for non-deleted shapes)
+ * working unchanged while making the "deleted has less" reality type-safe.
+ */
+export type NoteHookPayload = Note | DeletedNoteRef;
 
 export interface NoteHook {
   /** Events this hook listens for. Defaults to ["created", "updated"]. */
@@ -57,10 +84,26 @@ export interface NoteHook {
    * Should be cheap and synchronous. Idempotency lives here: check
    * whether a marker (e.g. `metadata.audio_rendered_at`) is already set
    * and return false if so.
+   *
+   * For `"deleted"` events the payload is a `DeletedNoteRef` — only
+   * `id` / `path` are populated; tag/metadata/content fields are
+   * undefined. Predicates that read those fields effectively skip
+   * the deleted shape unless they handle the narrower payload.
+   */
+  when?: (note: NoteHookPayload) => boolean;
+  /**
+   * Handler — runs async, off the request path. Third arg is the event
+   * type. For `"deleted"` the payload is a `DeletedNoteRef`, not a full
+   * `Note` — the row is gone by dispatch time, so the store can't be
+   * queried for it. Handlers needing more context should stash it ahead
+   * of time on the note's `metadata` and read off the predicate / the
+   * tracking shape rather than re-querying.
    */
-  when?: (note: Note) => boolean;
-  /** Handler — runs async, off the request path. Third arg is the event type. */
-  handler: (note: Note, store: Store, event?: HookEvent) => Promise<void> | void;
+  handler: (
+    note: NoteHookPayload,
+    store: Store,
+    event?: HookEvent,
+  ) => Promise<void> | void;
   /** Optional label for logs. */
   name?: string;
 }
@@ -70,22 +113,46 @@ interface RegisteredHook extends NoteHook {
 }
 
 /**
- * Attachment-mutation events. Today only `"created"` is dispatched — the
- * transcription worker (and any future attachment-aware feature) registers
- * here to move off its poll-driven steady state and onto the same event bus
- * that note hooks use. Keeping attachments separate from notes means a
- * `NoteHook` predicate doesn't have to learn a second argument shape.
+ * Attachment-mutation events. `"created"` carries the full attachment;
+ * `"deleted"` carries only `{ id, note_id, path }` (the row is gone by
+ * dispatch time, same shape rule as deleted notes).
+ *
+ * Consumers (transcription worker, git-mirror) subscribe here to react to
+ * lifecycle changes without polling. Keeping attachments separate from
+ * notes means a `NoteHook` predicate doesn't have to learn a second
+ * argument shape.
+ */
+export type AttachmentHookEvent = "created" | "deleted";
+
+/**
+ * Identity payload for a deleted attachment. The DB row is gone by
+ * dispatch time, so handlers can only react to id/note_id/path; metadata
+ * and timestamps are not preserved.
  */
-export type AttachmentHookEvent = "created";
+export interface DeletedAttachmentRef {
+  id: string;
+  noteId: string;
+  path: string;
+}
+
+/** Union over what an attachment hook handler may receive. */
+export type AttachmentHookPayload = Attachment | DeletedAttachmentRef;
 
 export interface AttachmentHook {
   /** Events this hook listens for. Defaults to ["created"]. */
   event?: AttachmentHookEvent | AttachmentHookEvent[];
-  /** Sync predicate. Same idempotency contract as `NoteHook.when`. */
-  when?: (attachment: Attachment) => boolean;
-  /** Handler — runs async, off the request path. */
+  /**
+   * Sync predicate. Same idempotency contract as `NoteHook.when`. For
+   * `"deleted"` the payload is a `DeletedAttachmentRef` — predicates
+   * relying on `metadata` / `createdAt` will see `undefined`.
+   */
+  when?: (attachment: AttachmentHookPayload) => boolean;
+  /**
+   * Handler — runs async, off the request path. For `"deleted"` the
+   * payload is a `DeletedAttachmentRef`, not a full `Attachment`.
+   */
   handler: (
-    attachment: Attachment,
+    attachment: AttachmentHookPayload,
     store: Store,
     event?: AttachmentHookEvent,
   ) => Promise<void> | void;
@@ -97,6 +164,37 @@ interface RegisteredAttachmentHook extends AttachmentHook {
   events: Set<AttachmentHookEvent>;
 }
 
+/**
+ * Tag-mutation events. `"upserted"` fires on tag-record create/update
+ * (description, fields, relationships, parent_names — any mutation that
+ * could change the schema sidecar that the git-mirror writes). `"deleted"`
+ * fires when the tag row is removed.
+ *
+ * Why this exists: the export sidecars at `.parachute/schemas/<tag>.yaml`
+ * are part of the mirror's output. Without a tag-mutation event the mirror
+ * has no signal that those files might need to change.
+ */
+export type TagHookEvent = "upserted" | "deleted";
+
+export interface TagHook {
+  /** Events this hook listens for. Defaults to ["upserted", "deleted"]. */
+  event?: TagHookEvent | TagHookEvent[];
+  /** Sync predicate keyed on the tag name. */
+  when?: (tag: string) => boolean;
+  /** Handler — runs async, off the request path. */
+  handler: (
+    tag: string,
+    store: Store,
+    event?: TagHookEvent,
+  ) => Promise<void> | void;
+  /** Optional label for logs. */
+  name?: string;
+}
+
+interface RegisteredTagHook extends TagHook {
+  events: Set<TagHookEvent>;
+}
+
 /**
  * Tiny async semaphore — FIFO waiters, no dependencies.
  * Used to cap concurrent handler execution across all hooks.
@@ -139,6 +237,7 @@ export interface HookRegistryOptions {
 export class HookRegistry {
   private hooks: RegisteredHook[] = [];
   private attachmentHooks: RegisteredAttachmentHook[] = [];
+  private tagHooks: RegisteredTagHook[] = [];
   private semaphore: Semaphore;
   private inFlight = new Set<Promise<void>>();
   private logger: { error: (...args: unknown[]) => void };
@@ -150,7 +249,15 @@ export class HookRegistry {
     this.logger = opts.logger ?? console;
   }
 
-  /** Register a hook. Returns an unregister function. */
+  /**
+   * Register a note-mutation hook. Returns an unregister function.
+   *
+   * The default event set is `["created", "updated"]` — explicit
+   * `event: "deleted"` (or include it in the array) is required to
+   * subscribe to deletions. This keeps existing hooks that pre-date the
+   * `"deleted"` event from suddenly receiving a payload shape
+   * (`DeletedNoteRef`) they weren't typed for.
+   */
   onNote(hook: NoteHook): () => void {
     const events = new Set<HookEvent>(
       Array.isArray(hook.event)
@@ -167,7 +274,13 @@ export class HookRegistry {
     };
   }
 
-  /** Register an attachment-mutation hook. Returns an unregister function. */
+  /**
+   * Register an attachment-mutation hook. Returns an unregister function.
+   *
+   * The default event set is `["created"]` only (matches the historical
+   * shape pre-deletion-events). Subscribe to `"deleted"` explicitly when
+   * the handler needs to react to attachment removal.
+   */
   onAttachment(hook: AttachmentHook): () => void {
     const events = new Set<AttachmentHookEvent>(
       Array.isArray(hook.event)
@@ -184,15 +297,38 @@ export class HookRegistry {
     };
   }
 
+  /**
+   * Register a tag-mutation hook. Returns an unregister function. Default
+   * event set is both `"upserted"` and `"deleted"` — symmetric with the
+   * sole consumer's needs (the git-mirror reacts to either to refresh its
+   * schema sidecars).
+   */
+  onTag(hook: TagHook): () => void {
+    const events = new Set<TagHookEvent>(
+      Array.isArray(hook.event)
+        ? hook.event
+        : hook.event
+          ? [hook.event]
+          : (["upserted", "deleted"] as TagHookEvent[]),
+    );
+    const entry: RegisteredTagHook = { ...hook, events };
+    this.tagHooks.push(entry);
+    return () => {
+      const idx = this.tagHooks.indexOf(entry);
+      if (idx >= 0) this.tagHooks.splice(idx, 1);
+    };
+  }
+
   /** Remove all registered hooks. Mostly for tests. */
   clear(): void {
     this.hooks = [];
     this.attachmentHooks = [];
+    this.tagHooks = [];
   }
 
-  /** Count of currently registered hooks (notes + attachments). */
+  /** Count of currently registered hooks (notes + attachments + tags). */
   get size(): number {
-    return this.hooks.length + this.attachmentHooks.length;
+    return this.hooks.length + this.attachmentHooks.length + this.tagHooks.length;
   }
 
   /** Count of currently in-flight handler executions. */
@@ -201,13 +337,19 @@ export class HookRegistry {
   }
 
   /**
-   * Dispatch a mutation event. Matches hooks, schedules their handlers
-   * onto a microtask, and returns immediately. The caller is never
-   * blocked on handler execution.
+   * Dispatch a note-mutation event. Matches hooks, schedules their
+   * handlers onto a microtask, and returns immediately. The caller is
+   * never blocked on handler execution.
    *
    * Must only be called after the triggering SQLite write has committed.
+   *
+   * For `"deleted"` the `note` argument is a `DeletedNoteRef` ({ id,
+   * path }) — the row is gone, so the runtime can't re-read it before
+   * dispatching to handlers. For `"created"` / `"updated"` the full
+   * `Note` is expected; `runHandler` will re-read from the store for
+   * non-deleted events to pick up the latest committed state.
    */
-  dispatch(event: HookEvent, note: Note, store: Store): void {
+  dispatch(event: HookEvent, note: NoteHookPayload, store: Store): void {
     if (this.hooks.length === 0) return;
 
     // Snapshot matches synchronously so subsequent hook registration
@@ -241,13 +383,12 @@ export class HookRegistry {
 
   /**
    * Dispatch an attachment-mutation event. Same post-commit/microtask
-   * contract as `dispatch()` for notes — callers are never blocked on
-   * handler execution, and the triggering SQLite write must already be
-   * committed.
+   * contract as `dispatch()` for notes. For `"deleted"` the payload is
+   * a `DeletedAttachmentRef`; for `"created"` it's the full `Attachment`.
    */
   dispatchAttachment(
     event: AttachmentHookEvent,
-    attachment: Attachment,
+    attachment: AttachmentHookPayload,
     store: Store,
   ): void {
     if (this.attachmentHooks.length === 0) return;
@@ -277,19 +418,61 @@ export class HookRegistry {
     });
   }
 
+  /**
+   * Dispatch a tag-mutation event. Same post-commit / microtask contract
+   * as the note + attachment dispatchers. `tag` is the bare tag name; the
+   * git-mirror handler matches on it to identify which `.parachute/schemas/<tag>.yaml`
+   * sidecar to rewrite or remove.
+   */
+  dispatchTag(event: TagHookEvent, tag: string, store: Store): void {
+    if (this.tagHooks.length === 0) return;
+
+    const matches: RegisteredTagHook[] = [];
+    for (const hook of this.tagHooks) {
+      if (!hook.events.has(event)) continue;
+      try {
+        if (hook.when && !hook.when(tag)) continue;
+      } catch (err) {
+        this.logger.error(
+          `[hooks] predicate threw for ${hook.name ?? "anonymous"} on tag ${tag}:`,
+          err,
+        );
+        continue;
+      }
+      matches.push(hook);
+    }
+    if (matches.length === 0) return;
+
+    queueMicrotask(() => {
+      for (const hook of matches) {
+        const task = this.runTagHandler(hook, event, tag, store);
+        this.inFlight.add(task);
+        task.finally(() => this.inFlight.delete(task));
+      }
+    });
+  }
+
   private async runHandler(
     hook: RegisteredHook,
     event: HookEvent,
-    note: Note,
+    note: NoteHookPayload,
     store: Store,
   ): Promise<void> {
     const release = await this.semaphore.acquire();
     try {
-      // Re-read the note so the handler sees the latest state (another
-      // handler may have written back in between). If the note was
-      // deleted, silently drop.
-      const fresh = (await store.getNote(note.id)) ?? note;
-      await hook.handler(fresh, store, event);
+      // For non-deleted events, re-read the note so the handler sees the
+      // latest committed state (another handler may have written back
+      // between dispatch and this acquisition). For "deleted" events the
+      // row is gone — pass the DeletedNoteRef payload straight through.
+      let payload: NoteHookPayload = note;
+      if (event !== "deleted") {
+        const fresh = await store.getNote(note.id);
+        if (fresh) payload = fresh;
+        // If the note was deleted between dispatch and re-read, fall
+        // back to the dispatch-time payload — same shape as before; the
+        // handler can sense the disappearance via its own predicate.
+      }
+      await hook.handler(payload, store, event);
     } catch (err) {
       this.logger.error(
         `[hooks] handler ${hook.name ?? "anonymous"} threw on ${event} ${note.id}:`,
@@ -303,16 +486,19 @@ export class HookRegistry {
   private async runAttachmentHandler(
     hook: RegisteredAttachmentHook,
     event: AttachmentHookEvent,
-    attachment: Attachment,
+    attachment: AttachmentHookPayload,
     store: Store,
   ): Promise<void> {
     const release = await this.semaphore.acquire();
     try {
-      // Re-read the attachment so the handler sees the latest metadata
-      // (another handler may have written back in between). If the
-      // attachment was deleted, silently drop.
-      const fresh = (await store.getAttachment(attachment.id)) ?? attachment;
-      await hook.handler(fresh, store, event);
+      // Symmetric with runHandler: re-read for non-deleted events,
+      // pass straight through on delete.
+      let payload: AttachmentHookPayload = attachment;
+      if (event !== "deleted") {
+        const fresh = await store.getAttachment(attachment.id);
+        if (fresh) payload = fresh;
+      }
+      await hook.handler(payload, store, event);
     } catch (err) {
       this.logger.error(
         `[hooks] attachment handler ${hook.name ?? "anonymous"} threw on ${event} ${attachment.id}:`,
@@ -323,6 +509,25 @@ export class HookRegistry {
     }
   }
 
+  private async runTagHandler(
+    hook: RegisteredTagHook,
+    event: TagHookEvent,
+    tag: string,
+    store: Store,
+  ): Promise<void> {
+    const release = await this.semaphore.acquire();
+    try {
+      await hook.handler(tag, store, event);
+    } catch (err) {
+      this.logger.error(
+        `[hooks] tag handler ${hook.name ?? "anonymous"} threw on ${event} ${tag}:`,
+        err,
+      );
+    } finally {
+      release();
+    }
+  }
+
   /**
    * Wait for all currently in-flight handlers to settle. Best-effort
    * drain for graceful shutdown. New hooks dispatched during the drain

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