@openparachute/vault 0.7.0-rc.4 → 0.7.0-rc.6

package/core/src/core.test.ts

@@ -2030,6 +2030,12 @@ describe("MCP tools", async () => {
     // prune-schema (admin) — drops orphaned indexed-field columns whose
     // declaring tags are gone. The gitcoin orphaned-fields fix.
     expect(names).toContain("prune-schema");
+    // rename-tag / merge-tags (vault#552) — MCP parity with the
+    // pre-existing REST rename/merge engine. doctor (admin, vault#552) —
+    // read-only taxonomy/metadata integrity scan.
+    expect(names).toContain("rename-tag");
+    expect(names).toContain("merge-tags");
+    expect(names).toContain("doctor");
     // 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
@@ -2043,7 +2049,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(10);
+    expect(tools).toHaveLength(13);
   });
 
   it("create-note tool works", async () => {
@@ -2075,8 +2081,11 @@ describe("MCP tools", async () => {
   // schema-default-filled field was missing from the returned note even
   // though it had just been written to disk.
   it("create-note response reflects post-applySchemaDefaults state (vault#316)", async () => {
+    // vault#553 Decision B: backfill is explicit-`default`-only now — declare
+    // one so this test still exercises the post-defaults re-read mechanism
+    // (the thing vault#316 is actually about).
     await store.upsertTagSchema("task", {
-      fields: { priority: { type: "string", enum: ["high", "low"] } },
+      fields: { priority: { type: "string", enum: ["high", "low"], default: "high" } },
     });
     const tools = generateMcpTools(store);
     const createNote = tools.find((t) => t.name === "create-note")!;
@@ -2087,7 +2096,7 @@ describe("MCP tools", async () => {
       path: "Inbox/task-1",
       tags: ["task"],
     }) as any;
-    expect(single.metadata?.priority).toBe("high"); // first enum value
+    expect(single.metadata?.priority).toBe("high"); // explicit schema default
     // Disk and response agree.
     const onDisk = await store.getNoteByPath("Inbox/task-1");
     expect((onDisk!.metadata as any)?.priority).toBe("high");
@@ -3450,7 +3459,7 @@ describe("MCP tools", async () => {
     expect(links.some((l) => l.relationship === "wikilink")).toBe(true);
   });
 
-  it("create-note with schema tag auto-populates defaults", async () => {
+  it("create-note with schema tag leaves undeclared fields ABSENT (vault#553 Decision B — no implicit enum[0]/zero-value backfill)", async () => {
     await store.upsertTagSchema("person", {
       description: "A person",
       fields: {
@@ -3466,10 +3475,36 @@ describe("MCP tools", async () => {
 
     const result = await createNote.execute({ content: "Alice", tags: ["person"] }) as any;
     const fresh = await query.execute({ id: result.id }) as any;
-    expect(fresh.metadata.first_appeared).toBe("");
-    expect(fresh.metadata.active).toBe(false);
-    expect(fresh.metadata.priority).toBe(0);
+    // None of these fields declares a `default` — the pre-0.7.0 behavior
+    // (enum[0] / type zero-value backfill) is retired. "Never set" now stays
+    // genuinely absent instead of masquerading as "explicitly set to X" — in
+    // fact NO field got backfilled, so `metadata` itself stays empty/absent.
+    expect(fresh.metadata?.first_appeared).toBeUndefined();
+    expect(fresh.metadata?.active).toBeUndefined();
+    expect(fresh.metadata?.priority).toBeUndefined();
+    expect(fresh.metadata?.status).toBeUndefined();
+  });
+
+  it("create-note with schema tag applies EXPLICIT `default:` values only (vault#553 Decision B)", async () => {
+    await store.upsertTagSchema("employee", {
+      description: "An employee",
+      fields: {
+        active: { type: "boolean", default: true },
+        priority: { type: "integer", default: 3 },
+        status: { type: "string", enum: ["active", "archived"], default: "active" },
+        nickname: { type: "string" }, // no default — stays absent
+      },
+    });
+    const tools = generateMcpTools(store);
+    const createNote = tools.find((t) => t.name === "create-note")!;
+    const query = tools.find((t) => t.name === "query-notes")!;
+
+    const result = await createNote.execute({ content: "Bob", tags: ["employee"] }) as any;
+    const fresh = await query.execute({ id: result.id }) as any;
+    expect(fresh.metadata.active).toBe(true);
+    expect(fresh.metadata.priority).toBe(3);
     expect(fresh.metadata.status).toBe("active");
+    expect(fresh.metadata.nickname).toBeUndefined();
   });
 
   // ---- query-notes input-shape tolerance (vault#214) ----
@@ -4170,7 +4205,17 @@ describe("tag hierarchy (tags.parent_names)", async () => {
 
   it("tolerates a cycle without infinite-looping", async () => {
     await store.upsertTagRecord("a", { parent_names: ["b"] });
-    await store.upsertTagRecord("b", { parent_names: ["a"] });
+    await store.upsertTagRecord("b", {}); // bare row, no parent yet
+    // vault#552: upsertTagRecord now REJECTS a parent_names write that would
+    // close a cycle, so the second leg of the cycle can no longer be built
+    // via the public API — simulate pre-existing cyclic data (written
+    // before the guard shipped, or via any path that bypasses it) with a
+    // direct DB write, same technique as "malformed parent_names JSON is
+    // ignored silently" below. Traversal must stay cycle-safe regardless of
+    // how the cycle got there.
+    (store as any).db.prepare("UPDATE tags SET parent_names = ? WHERE name = ?")
+      .run(JSON.stringify(["a"]), "b");
+    (store as any)._tagHierarchy = null;
     await store.createNote("note-a", { tags: ["a"] });
 
     // Both a and b should resolve without hanging; both reach the same set {a, b}.
@@ -4600,8 +4645,9 @@ describe("update-note if_missing=create (vault#309)", async () => {
   });
 
   it("create branch applies tag-schema defaults when the new tag declares fields", async () => {
+    // vault#553 Decision B: backfill is explicit-`default`-only.
     await store.upsertTagSchema("task", {
-      fields: { priority: { type: "string", enum: ["high", "low"] } },
+      fields: { priority: { type: "string", enum: ["high", "low"], default: "high" } },
     });
     const tools = generateMcpTools(store);
     const update = tools.find((t) => t.name === "update-note")!;
@@ -4613,7 +4659,7 @@ describe("update-note if_missing=create (vault#309)", async () => {
     }) as any;
     expect(result.created).toBe(true);
     // Schema defaults populated metadata.priority on insert.
-    expect(result.metadata?.priority).toBeDefined();
+    expect(result.metadata?.priority).toBe("high");
   });
 
   it("create branch surfaces validation warnings just like create-note", async () => {
@@ -4803,14 +4849,21 @@ describe("schema inheritance via parent_names (vault#270)", async () => {
   });
 
   it("cycle: A→B, B→A — no infinite loop, both fields visible", async () => {
+    await store.upsertTagRecord("B", {
+      fields: { b_field: { type: "string" } },
+    });
     await store.upsertTagRecord("A", {
       parent_names: ["B"],
       fields: { a_field: { type: "string" } },
     });
-    await store.upsertTagRecord("B", {
-      parent_names: ["A"],
-      fields: { b_field: { type: "string" } },
-    });
+    // vault#552: upsertTagRecord now REJECTS the write that would close this
+    // cycle (B declaring A as parent, when A already declares B) — simulate
+    // pre-existing cyclic data with a direct DB write, same technique as the
+    // "tolerates a cycle without infinite-looping" test above.
+    (store as any).db.prepare("UPDATE tags SET parent_names = ? WHERE name = ?")
+      .run(JSON.stringify(["A"]), "B");
+    (store as any)._tagHierarchy = null;
+    (store as any)._schemaConfig = null;
 
     const tools = generateMcpTools(store);
     const create = tools.find((t) => t.name === "create-note")!;

package/core/src/doctor-scope.test.ts

@@ -0,0 +1,117 @@
+/**
+ * Tag-scope confidentiality for the `vault doctor` integrity scan (vault#552
+ * auth fold). Two finding types query notes VAULT-WIDE and previously leaked
+ * out-of-scope data to a tag-scoped caller:
+ *
+ *   - `mixed_type_indexed_field`: the note query + mismatch count + exemplars
+ *     + the "Declared by: <tags>" detail were all unscoped — a caller scoped
+ *     to `mine` could see an out-of-scope declarer tag name AND an
+ *     out-of-scope note id.
+ *   - `dead_tag_metadata_reference`: the example live value (the `e.g.
+ *     "<value>"` in detail) was computed vault-wide — leaking an out-of-scope
+ *     tag NAME — and (unscoped) exemplars could include out-of-scope note ids.
+ *
+ * Each test asserts the out-of-scope tag name / note id appears NOWHERE in
+ * the serialized findings when scoped, and pairs with an UNSCOPED positive
+ * control proving the fixture genuinely carries that leak-able data (so the
+ * scoped assertion isn't vacuous — remove the scope filter and the control's
+ * leak reappears in the scoped run).
+ */
+import { describe, it, expect, beforeEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { SqliteStore } from "./store.js";
+import { runDoctorScan } from "./doctor.js";
+
+const OUT_OF_SCOPE_TAG = "theirs-secret";
+
+let store: SqliteStore;
+let db: Database;
+
+beforeEach(() => {
+  db = new Database(":memory:");
+  store = new SqliteStore(db);
+});
+
+describe("doctor mixed_type_indexed_field × tag scope (vault#552 MUST-FIX 3)", () => {
+  beforeEach(async () => {
+    // Field `n` is indexed INTEGER, co-declared by an in-scope tag (`mine`)
+    // and an out-of-scope one (`theirs-secret`). Both carry a note whose
+    // metadata.n is a JSON string (type mismatch), not strict so the write
+    // lands the poison value.
+    await store.upsertTagRecord("mine", { fields: { n: { type: "integer", indexed: true } } });
+    await store.upsertTagRecord(OUT_OF_SCOPE_TAG, { fields: { n: { type: "integer", indexed: true } } });
+    await store.createNote("in-scope mismatch", { id: "mine-mm", tags: ["mine"], metadata: { n: "bad-mine" } });
+    await store.createNote("out-of-scope mismatch", { id: "theirs-mm", tags: [OUT_OF_SCOPE_TAG], metadata: { n: "bad-theirs" } });
+  });
+
+  it("scoped caller: the out-of-scope declarer name and out-of-scope note id appear NOWHERE", async () => {
+    const report = await store.doctor({ allowedTags: new Set(["mine"]) });
+    const finding = report.findings.find((f) => f.type === "mixed_type_indexed_field");
+    expect(finding).toBeDefined(); // the in-scope mismatch still fires it
+    expect(finding!.subject).toBe("n");
+
+    const serialized = JSON.stringify(report.findings);
+    expect(serialized).not.toContain(OUT_OF_SCOPE_TAG);
+    expect(serialized).not.toContain("theirs-mm");
+    // The in-scope exemplar IS present (proves the finding is real, not empty).
+    expect(serialized).toContain("mine-mm");
+    // Count reflects the single in-scope mismatch, not both.
+    expect(finding!.detail).toContain("1 note(s)");
+    expect(finding!.detail).toContain("Declared by: mine.");
+  });
+
+  it("unscoped control: the same fixture DOES surface the out-of-scope declarer + note (mutation-check)", async () => {
+    const report = await runDoctorScan(db); // no allowedTags
+    const serialized = JSON.stringify(report.findings);
+    // Absent the scope filter, both the out-of-scope declarer name and the
+    // out-of-scope note id leak — this is exactly what the scoped run above
+    // must suppress. If the scope filter were removed, the scoped assertions
+    // would see these too and fail.
+    expect(serialized).toContain(OUT_OF_SCOPE_TAG);
+    expect(serialized).toContain("theirs-mm");
+  });
+});
+
+describe("doctor dead_tag_metadata_reference × tag scope (vault#552 MUST-FIX 4)", () => {
+  beforeEach(async () => {
+    await store.upsertTagRecord("mine", {});
+    await store.upsertTagRecord(OUT_OF_SCOPE_TAG, {});
+    // Insertion ORDER matters: the out-of-scope live-tag value is created
+    // FIRST so the vault-wide `liveValues[0]` example would be
+    // "theirs-secret" absent the scope fix.
+    await store.createNote("oos live", { id: "theirs-live", tags: [OUT_OF_SCOPE_TAG], metadata: { epic: OUT_OF_SCOPE_TAG } });
+    await store.createNote("in-scope live", { id: "mine-live", tags: ["mine"], metadata: { epic: "mine" } });
+    await store.createNote("in-scope dead", { id: "mine-dead", tags: ["mine"], metadata: { epic: "ghost-epic" } });
+    await store.createNote("oos dead", { id: "theirs-dead", tags: [OUT_OF_SCOPE_TAG], metadata: { epic: "ghost-epic" } });
+  });
+
+  it("scoped caller: the out-of-scope example tag name and out-of-scope note id appear NOWHERE", async () => {
+    const report = await store.doctor({ allowedTags: new Set(["mine"]) });
+    const finding = report.findings.find((f) => f.type === "dead_tag_metadata_reference");
+    expect(finding).toBeDefined();
+    expect(finding!.subject).toBe("metadata.epic");
+    expect(finding!.heuristic).toBe(true);
+
+    const serialized = JSON.stringify(report.findings);
+    // No out-of-scope tag NAME (as the `e.g. "<value>"` live example) and no
+    // out-of-scope note id (as an exemplar of the dead value).
+    expect(serialized).not.toContain(OUT_OF_SCOPE_TAG);
+    expect(serialized).not.toContain("theirs-dead");
+    expect(serialized).not.toContain("theirs-live");
+    // The in-scope live example + in-scope exemplar + dead value ARE present.
+    expect(finding!.detail).toContain('e.g. "mine"');
+    expect(serialized).toContain("mine-dead");
+    expect(serialized).toContain("ghost-epic");
+  });
+
+  it("unscoped control: the same fixture leaks the out-of-scope example name + note id (mutation-check)", async () => {
+    const report = await runDoctorScan(db); // no allowedTags
+    const finding = report.findings.find((f) => f.type === "dead_tag_metadata_reference")!;
+    const serialized = JSON.stringify(report.findings);
+    // Vault-wide, the example live value is the first-inserted live tag
+    // ("theirs-secret"), and the out-of-scope note id is an exemplar — both
+    // the leaks the scoped run suppresses.
+    expect(finding.detail).toContain(`e.g. "${OUT_OF_SCOPE_TAG}"`);
+    expect(serialized).toContain("theirs-dead");
+  });
+});

package/core/src/doctor.ts

@@ -0,0 +1,360 @@
+/**
+ * `vault doctor` — read-only taxonomy/metadata integrity scan (vault#552).
+ *
+ * NOT to be confused with `parachute-vault doctor` (the CLI's install/daemon
+ * diagnostic in `src/cli.ts` — port reachability, config sanity, launchd/
+ * systemd registration). This module answers a different question: "did my
+ * tag reorg (rename/merge/delete) leak?" It never auto-fixes — every finding
+ * carries a suggested `remedy` the caller applies deliberately (usually via
+ * `rename-tag`/`merge-tags`/`prune-schema`/another `update-tag` call).
+ *
+ * Scans:
+ *   - `dangling_parent_name`   — a `parent_names` entry naming a tag with no
+ *     identity row.
+ *   - `parent_names_cycle`     — a tag that reaches itself through its
+ *     declared ancestor chain (traversal is cycle-safe; this just SURFACES
+ *     data that predates the vault#552 write-time cycle guard, or was
+ *     written by a path that bypasses it).
+ *   - `mixed_type_indexed_field` — a note whose `metadata.<field>` JSON type
+ *     disagrees with the field's declared indexed sqlite type. This is the
+ *     WS4 typed-index "poison precursor": inconsistent column affinity
+ *     coercion silently breaks ordering/comparison across rows. The finding
+ *     shape here is intentionally reusable as WS4's migration pre-flight.
+ *   - `orphaned_indexed_field_declarer` — an `indexed_fields` row naming a
+ *     declarer tag with no `tags` row (overlaps `prune-schema`, which is the
+ *     suggested remedy).
+ *   - `dead_tag_metadata_reference` — HEURISTIC, always labeled `heuristic:
+ *     true`. A metadata key is used elsewhere in the vault with values that
+ *     ARE live tag names (establishing "this key holds tag-shaped values");
+ *     a value under the same key that does NOT match any live tag is
+ *     flagged as a possible stale reference to a renamed/merged/deleted tag
+ *     — the PM's `metadata.epic` drift class from the #552 write-up. Vault
+ *     has no history of past tag names, so this can never be certain —
+ *     hence heuristic.
+ *
+ * Tag-scope (vault#552): pass `allowedTags` (the caller's EXPANDED
+ * allowlist, e.g. from `expandTokenTagScope`) to restrict every finding to
+ * in-scope tags/fields/notes. `null` (or omitted) — the default — scans the
+ * whole vault. The scan is re-run with the allowlist rather than filtering
+ * an unscoped result afterward, so the `summary` counts never leak
+ * out-of-scope activity.
+ */
+
+import { Database } from "bun:sqlite";
+import { loadTagHierarchy, findHierarchyCycles } from "./tag-hierarchy.js";
+import { listIndexedFields } from "./indexed-fields.js";
+import { pruneOrphanedIndexedFields } from "./indexed-fields.js";
+
+export type DoctorFindingType =
+  | "dangling_parent_name"
+  | "parent_names_cycle"
+  | "mixed_type_indexed_field"
+  | "orphaned_indexed_field_declarer"
+  | "dead_tag_metadata_reference";
+
+export type DoctorSeverity = "error" | "warning" | "info";
+
+export interface DoctorFinding {
+  type: DoctorFindingType;
+  severity: DoctorSeverity;
+  /** The tag / field / metadata-key this finding is about. */
+  subject: string;
+  detail: string;
+  remedy: string;
+  /**
+   * True ONLY for `dead_tag_metadata_reference` — flags the finding as a
+   * best-effort inference (no tag-rename history exists to confirm it),
+   * never present (not even `false`) on the other, structurally-certain
+   * finding types.
+   */
+  heuristic?: true;
+}
+
+export interface DoctorReport {
+  findings: DoctorFinding[];
+  summary: string;
+  scanned_at: string;
+}
+
+export interface DoctorScanOpts {
+  /**
+   * The caller's expanded tag allowlist (root ∪ descendants). `null`
+   * (default) scans the whole vault. See the module doc comment for how
+   * each finding type is scoped.
+   */
+  allowedTags?: Set<string> | null;
+}
+
+/** Cap on exemplar note IDs embedded in a finding's `detail` (vault#552 — keep report bodies bounded). */
+const MAX_EXEMPLARS = 5;
+
+/**
+ * Build a per-note in-scope predicate for a tag-scoped doctor run (vault#552
+ * auth fold). A note is in-scope iff at least one of its tags is in
+ * `allowedTags`; an unscoped run (`allowedTags === null`) treats every note
+ * as in-scope. Caches each note's tag lookup so repeated checks across scans
+ * cost one query per note. Shared by the mixed-type-indexed-field and
+ * dead-tag-metadata scans, both of which query notes vault-wide and must NOT
+ * surface an out-of-scope note id (or count, or exemplar) to a scoped caller.
+ */
+function makeNoteInScope(db: Database, allowedTags: Set<string> | null): (id: string) => boolean {
+  if (!allowedTags) return () => true;
+  const cache = new Map<string, boolean>();
+  return (id: string): boolean => {
+    const cached = cache.get(id);
+    if (cached !== undefined) return cached;
+    const tags = (db.prepare("SELECT tag_name FROM note_tags WHERE note_id = ?").all(id) as { tag_name: string }[]).map((r) => r.tag_name);
+    const inScope = tags.some((t) => allowedTags.has(t));
+    cache.set(id, inScope);
+    return inScope;
+  };
+}
+
+export function runDoctorScan(db: Database, opts?: DoctorScanOpts): DoctorReport {
+  const allowedTags = opts?.allowedTags ?? null;
+  const findings: DoctorFinding[] = [
+    ...scanDanglingParentNames(db, allowedTags),
+    ...scanParentNamesCycles(db, allowedTags),
+    ...scanMixedTypeIndexedFields(db, allowedTags),
+    ...scanOrphanedIndexedFieldDeclarers(db, allowedTags),
+    ...scanDeadTagMetadataReferences(db, allowedTags),
+  ];
+
+  const errors = findings.filter((f) => f.severity === "error").length;
+  const warnings = findings.filter((f) => f.severity === "warning").length;
+  const infos = findings.filter((f) => f.severity === "info").length;
+  const summary =
+    findings.length === 0
+      ? "clean — no integrity findings"
+      : `${findings.length} finding(s): ${errors} error(s), ${warnings} warning(s), ${infos} info(s)`;
+
+  return { findings, summary, scanned_at: new Date().toISOString() };
+}
+
+// ---------------------------------------------------------------------------
+// A. dangling parent_names
+// ---------------------------------------------------------------------------
+
+function scanDanglingParentNames(db: Database, allowedTags: Set<string> | null): DoctorFinding[] {
+  const rows = db
+    .prepare("SELECT name, parent_names FROM tags WHERE parent_names IS NOT NULL")
+    .all() as { name: string; parent_names: string }[];
+  const allTags = new Set(
+    (db.prepare("SELECT name FROM tags").all() as { name: string }[]).map((r) => r.name),
+  );
+
+  const findings: DoctorFinding[] = [];
+  for (const row of rows) {
+    if (allowedTags && !allowedTags.has(row.name)) continue;
+    let parsed: unknown;
+    try { parsed = JSON.parse(row.parent_names); } catch { continue; }
+    if (!Array.isArray(parsed)) continue;
+    for (const parent of parsed) {
+      if (typeof parent !== "string" || parent.length === 0) continue;
+      if (allTags.has(parent)) continue;
+      findings.push({
+        type: "dangling_parent_name",
+        severity: "warning",
+        subject: row.name,
+        detail: `tag "${row.name}" declares parent "${parent}", which has no identity row — a typo, a tag that was never created, or a rename/delete that didn't update this reference.`,
+        remedy: `remove "${parent}" from "${row.name}"'s parent_names (update-tag), or create the missing "${parent}" tag if it's meant to exist`,
+      });
+    }
+  }
+  return findings;
+}
+
+// ---------------------------------------------------------------------------
+// B. parent_names cycles (pre-existing data — the write-time guard blocks
+//    NEW ones; this surfaces anything already on disk)
+// ---------------------------------------------------------------------------
+
+function scanParentNamesCycles(db: Database, allowedTags: Set<string> | null): DoctorFinding[] {
+  const hierarchy = loadTagHierarchy(db);
+  const cycles = findHierarchyCycles(hierarchy);
+  const findings: DoctorFinding[] = [];
+  for (const tag of cycles) {
+    if (allowedTags && !allowedTags.has(tag)) continue;
+    findings.push({
+      type: "parent_names_cycle",
+      severity: "error",
+      subject: tag,
+      detail: `tag "${tag}" reaches itself through its declared parent_names ancestor chain. Query expansion tolerates this (a visited-set stops it looping), but it's confusing hierarchy state.`,
+      remedy: `clear or correct parent_names on one of the tags in "${tag}"'s ancestor chain (update-tag) to break the cycle`,
+    });
+  }
+  return findings;
+}
+
+// ---------------------------------------------------------------------------
+// C. mixed-type values in an indexed column (WS4 poison precursor)
+// ---------------------------------------------------------------------------
+
+/** `json_type()` results consistent with each declared indexed sqlite storage class. */
+const EXPECTED_JSON_TYPES: Record<string, Set<string>> = {
+  INTEGER: new Set(["integer", "real", "true", "false"]),
+  TEXT: new Set(["text"]),
+};
+
+/** One vault-wide-scan result row from {@link findMixedTypeIndexedFieldNotes}. */
+export interface MixedTypeIndexedFieldRow {
+  id: string;
+  /** SQLite `json_type()` of the CURRENT `metadata.<field>` value — "text", "integer", "real", "true", "false", "array", "object" (never "null": absent/null keys are excluded upstream). */
+  jt: string;
+}
+
+/**
+ * Vault-wide detector: every note whose `metadata.<field>` JSON type
+ * disagrees with `sqliteType` (the field's declared indexed storage class —
+ * "INTEGER" or "TEXT"). Returns `[]` for an unknown `sqliteType` or when
+ * nothing mismatches. UNSCOPED — no tag-scope filtering (that's the caller's
+ * job; see `scanMixedTypeIndexedFields` below for the tag-scoped doctor
+ * finding, and `migrateToV24` in `core/src/schema.ts` for the unscoped
+ * migration consumer). `json_type(metadata, ?)` returns NULL when the key is
+ * absent — those notes simply don't declare the field and aren't a mismatch.
+ *
+ * Extracted (vault#553 Decision D) so the SAME detection query backs both
+ * the `mixed_type_indexed_field` doctor finding AND the `migrateToV24`
+ * startup migration's poison scan — one source of truth for "what counts as
+ * mismatched," so a fix to one can't silently diverge from the other.
+ */
+export function findMixedTypeIndexedFieldNotes(
+  db: Database,
+  field: string,
+  sqliteType: string,
+): MixedTypeIndexedFieldRow[] {
+  const expected = EXPECTED_JSON_TYPES[sqliteType];
+  if (!expected) return []; // unknown sqlite_type — nothing to compare against
+  const path = `$."${field}"`;
+  const rows = db
+    .prepare(
+      `SELECT id, json_type(metadata, ?) as jt FROM notes WHERE metadata IS NOT NULL AND metadata != '' AND json_valid(metadata)`,
+    )
+    .all(path) as { id: string; jt: string | null }[];
+  return rows.filter((r): r is MixedTypeIndexedFieldRow => r.jt !== null && !expected.has(r.jt));
+}
+
+function scanMixedTypeIndexedFields(db: Database, allowedTags: Set<string> | null): DoctorFinding[] {
+  const findings: DoctorFinding[] = [];
+  const noteInScope = makeNoteInScope(db, allowedTags);
+  for (const f of listIndexedFields(db)) {
+    if (allowedTags && !f.declarerTags.some((t) => allowedTags.has(t))) continue;
+
+    const rows = findMixedTypeIndexedFieldNotes(db, f.field, f.sqliteType);
+    if (rows.length === 0) continue;
+
+    // Tag-scope (vault#552 auth fold): the note query above is vault-wide —
+    // filter mismatches to IN-SCOPE notes so a scoped caller never sees an
+    // out-of-scope note id (nor a count/exemplar reflecting one). If every
+    // mismatch is on an out-of-scope note, the finding is dropped entirely.
+    const mismatches = rows.filter((r) => noteInScope(r.id));
+    if (mismatches.length === 0) continue;
+
+    // Also generalize the "Declared by" list to in-scope declarers only —
+    // the field can be co-declared by an out-of-scope tag whose name must
+    // not leak (the caller sees this field only via its in-scope declarer).
+    const visibleDeclarers = allowedTags
+      ? f.declarerTags.filter((t) => allowedTags.has(t))
+      : f.declarerTags;
+    const exemplars = mismatches.slice(0, MAX_EXEMPLARS).map((r) => `${r.id} (${r.jt})`);
+    findings.push({
+      type: "mixed_type_indexed_field",
+      severity: "error",
+      subject: f.field,
+      detail: `field "${f.field}" is indexed as ${f.sqliteType} but ${mismatches.length} note(s) carry a metadata."${f.field}" value of a disagreeing JSON type — the generated column's affinity coercion makes ordering/filtering across these rows inconsistent. Declared by: ${visibleDeclarers.join(", ") || "(no live declarer)"}. Example note(s): ${exemplars.join(", ")}${mismatches.length > exemplars.length ? ", …" : ""}`,
+      remedy: `backfill each listed note's metadata."${f.field}" to a value matching the declared type, or relax the field's declared type (update-tag) if the mixed values are intentional`,
+    });
+  }
+  return findings;
+}
+
+// ---------------------------------------------------------------------------
+// D. orphaned indexed_fields declarers (overlaps prune-schema)
+// ---------------------------------------------------------------------------
+
+function scanOrphanedIndexedFieldDeclarers(db: Database, allowedTags: Set<string> | null): DoctorFinding[] {
+  const plan = pruneOrphanedIndexedFields(db, { dryRun: true });
+  const findings: DoctorFinding[] = [];
+  for (const p of plan) {
+    if (allowedTags && !p.deadDeclarers.some((t) => allowedTags.has(t))) {
+      // Dead declarer names never survive `allowedTags` (it's derived from
+      // LIVE tags only) — this branch exists for completeness; in practice
+      // a scoped caller only sees this finding when the report is unscoped.
+      continue;
+    }
+    findings.push({
+      type: "orphaned_indexed_field_declarer",
+      severity: p.dropped ? "warning" : "info",
+      subject: p.field,
+      detail: p.dropped
+        ? `field "${p.field}" has NO surviving live declarer (dead: ${p.deadDeclarers.join(", ")}) — the generated column + index are stale and will be dropped on next prune (metadata values are never lost, only the index).`
+        : `field "${p.field}" has dead declarer tag(s) [${p.deadDeclarers.join(", ")}] still listed alongside live ones — cosmetic, no functional impact.`,
+      remedy: `run the prune-schema tool (apply: true) to drop the dead declarer(s)${p.dropped ? " and the now-unreferenced column/index" : ""}`,
+    });
+  }
+  return findings;
+}
+
+// ---------------------------------------------------------------------------
+// E. metadata values equal to a tag name that no longer exists (heuristic)
+// ---------------------------------------------------------------------------
+
+function scanDeadTagMetadataReferences(db: Database, allowedTags: Set<string> | null): DoctorFinding[] {
+  const liveTags = new Set(
+    (db.prepare("SELECT name FROM tags").all() as { name: string }[]).map((r) => r.name),
+  );
+
+  const rows = db
+    .prepare("SELECT id, metadata FROM notes WHERE metadata IS NOT NULL AND metadata != ''")
+    .all() as { id: string; metadata: string }[];
+
+  // key -> value -> note ids carrying that (key, value) pair.
+  const byKey = new Map<string, Map<string, string[]>>();
+  for (const row of rows) {
+    let parsed: unknown;
+    try { parsed = JSON.parse(row.metadata); } catch { continue; }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) continue;
+    for (const [key, value] of Object.entries(parsed as Record<string, unknown>)) {
+      if (typeof value !== "string" || value.length === 0) continue;
+      let valueMap = byKey.get(key);
+      if (!valueMap) { valueMap = new Map(); byKey.set(key, valueMap); }
+      let ids = valueMap.get(value);
+      if (!ids) { ids = []; valueMap.set(value, ids); }
+      ids.push(row.id);
+    }
+  }
+
+  // Tag-scope (vault#552 auth fold): a note is in-scope iff at least one of
+  // its tags is in `allowedTags` (unscoped → every note in-scope).
+  const noteInScope = makeNoteInScope(db, allowedTags);
+
+  const findings: DoctorFinding[] = [];
+  for (const [key, valueMap] of byKey) {
+    // Signal: does this metadata key hold tag-shaped values on IN-SCOPE
+    // notes? Computed over in-scope notes ONLY (not vault-wide) so the
+    // example live value quoted in `detail` can never leak an out-of-scope
+    // tag name — a scoped caller must not learn a tag exists just because a
+    // note it can't see uses it as a metadata value. Only flag mismatches
+    // under a key that demonstrably holds tag-shaped values in-scope.
+    const liveValuesInScope = [...valueMap.entries()]
+      .filter(([v, ids]) => liveTags.has(v) && ids.some(noteInScope))
+      .map(([v]) => v);
+    if (liveValuesInScope.length === 0) continue;
+
+    for (const [value, noteIds] of valueMap) {
+      if (liveTags.has(value)) continue;
+      const inScopeIds = noteIds.filter(noteInScope);
+      if (inScopeIds.length === 0) continue;
+      const exemplars = inScopeIds.slice(0, MAX_EXEMPLARS);
+      findings.push({
+        type: "dead_tag_metadata_reference",
+        severity: "info",
+        subject: `metadata.${key}`,
+        detail: `${inScopeIds.length} note(s) carry metadata.${key} = "${value}", which matches no current tag — other notes' metadata.${key} values ARE live tags (e.g. "${liveValuesInScope[0]}"), suggesting "${value}" may be a stale reference to a tag that was renamed, merged, or deleted. Example note(s): ${exemplars.join(", ")}${inScopeIds.length > exemplars.length ? ", …" : ""}`,
+        remedy: `if "${value}" was renamed/merged/deleted, update these notes' metadata.${key} to the current tag name; if "${value}" was never a tag, ignore this finding`,
+        heuristic: true,
+      });
+    }
+  }
+  return findings;
+}