@openparachute/vault 0.4.9-rc.10 → 0.4.9-rc.12

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

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