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

package/core/src/doctor.ts

@@ -0,0 +1,330 @@
+/**
+ * `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"]),
+};
+
+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 expected = EXPECTED_JSON_TYPES[f.sqliteType];
+    if (!expected) continue; // unknown sqlite_type — nothing to compare against
+
+    // `json_type(metadata, ?)` returns NULL when the key is absent — those
+    // notes simply don't declare the field and aren't a mismatch. Only rows
+    // where the key IS present get compared.
+    const path = `$."${f.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 }[];
+    // 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) => r.jt !== null && !expected.has(r.jt) && 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;
+}

package/core/src/mcp.ts

@@ -190,9 +190,11 @@ export interface GenerateMcpToolsOpts {
 }
 
 /**
- * Generate the consolidated MCP tools for a vault. Surface (10):
+ * Generate the consolidated MCP tools for a vault. Surface (13):
  * query-notes, create-note, update-note, delete-note, list-tags, update-tag,
- * delete-tag, find-path, vault-info, prune-schema (admin).
+ * delete-tag, rename-tag, merge-tags, find-path, vault-info, prune-schema
+ * (admin), doctor (admin). `manage-token` (admin) is appended by the SERVER
+ * layer (src/mcp-tools.ts), not here — see that file's doc comment.
  */
 export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): McpToolDef[] {
   const db: Database = store.db;
@@ -1716,11 +1718,13 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
       // mgmt + future config writes; deletes are write-tier mutations.
       // See delete-note rationale.
       requiredVerb: "write",
-      description: "Delete a tag, remove it from all notes, and delete its schema. Notes themselves are NOT deleted — just untagged.",
+      description: "Delete a tag, remove it from all notes, and delete its schema. Notes themselves are NOT deleted — just untagged. Refused with error_type \"tag_referenced_as_parent\" (vault#552) when another tag's parent_names still names this one — pass cascade OR detach (either — both mean the same thing: strip the stale reference from the referencing tag(s)' parent_names, never delete them) to proceed anyway.",
       inputSchema: {
         type: "object",
         properties: {
           tag: { type: "string", description: "Tag name to delete" },
+          cascade: { type: "boolean", description: "Proceed even though another tag's parent_names references this one, stripping the reference. Synonym of detach." },
+          detach: { type: "boolean", description: "Same as cascade — proceed and strip the stale parent_names reference from referencing tag(s)." },
         },
         required: ["tag"],
       },
@@ -1731,8 +1735,107 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
         // 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);
+        // gitcoin orphaned-fields bug report. The referential-integrity
+        // guard (vault#552) is ALSO inside store.deleteTag, so it returns
+        // (not throws) `{error: "tag_referenced_as_parent", ...}` when
+        // refused — same in-band shape delete-tag has always used for its
+        // token-reference guard (applyTagDependencyGuards, src/mcp-tools.ts).
+        return await store.deleteTag(tag, {
+          cascade: params.cascade === true,
+          detach: params.detach === true,
+        });
+      },
+    },
+
+    // =====================================================================
+    // 7a. rename-tag — atomic cascading rename (vault#552 MCP parity)
+    // =====================================================================
+    {
+      name: "rename-tag",
+      requiredVerb: "write",
+      description:
+        "Atomically rename a tag across EVERY surface that references it: note memberships, OTHER tags' parent_names, tag-scoped tokens' allowlists, indexed-field declarer lists, inline #tag mentions in note bodies, and _tags/<name> config-note paths — all in one transaction. THIS is the fix for the manual retag→delete dance (create the new tag, retag notes, delete the old one): that dance silently orphans parent_names references (the renamed-away tag stays a live query surface via subtype expansion while list-tags reports it at count 0, and the new tag misses every child-tagged note) and leaves stale #tag mentions behind. Sub-tags rename recursively — renaming \"task\" to \"todo\" also renames \"task/work\" to \"todo/work\". Does NOT rewrite metadata values that happen to equal the old tag name (e.g. metadata.epic: \"task\") — that's a distinct drift class the doctor tool's dead_tag_metadata_reference finding flags heuristically; rename-tag's job is structural (tags/note_tags/parent_names/tokens/content), not a blind string search-and-replace over arbitrary metadata.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          old_name: { type: "string", description: "The tag to rename. Aliases: from, tag." },
+          new_name: { type: "string", description: "The new name. Alias: to." },
+          from: { type: "string", description: "Alias for old_name." },
+          to: { type: "string", description: "Alias for new_name." },
+          tag: { type: "string", description: "Alias for old_name." },
+        },
+      },
+      execute: async (params) => {
+        const oldName = (params.old_name ?? params.from ?? params.tag) as string | undefined;
+        const newName = (params.new_name ?? params.to) as string | undefined;
+        if (typeof oldName !== "string" || oldName.length === 0) {
+          throw structuredError("rename-tag: old_name (or from/tag) is required", {
+            error_type: "invalid_request",
+            field: "old_name",
+          });
+        }
+        if (typeof newName !== "string" || newName.length === 0) {
+          throw structuredError("rename-tag: new_name (or to) is required", {
+            error_type: "invalid_request",
+            field: "new_name",
+          });
+        }
+        const result = await store.renameTag(oldName, newName);
+        if ("error" in result) {
+          if (result.error === "not_found") {
+            throw structuredError(`rename-tag: tag "${oldName}" not found`, {
+              error_type: "tag_not_found",
+              field: "old_name",
+            });
+          }
+          throw Object.assign(
+            new Error(
+              `rename-tag: target "${newName}" (or one of its sub-tags) already exists — use merge-tags to combine them instead`,
+            ),
+            {
+              error_type: "target_exists" as const,
+              target: newName,
+              conflicting: result.conflicting,
+              hint: "use merge-tags to combine the tags instead",
+            },
+          );
+        }
+        return result;
+      },
+    },
+
+    // =====================================================================
+    // 7b. merge-tags — same machinery, N sources → one target
+    // =====================================================================
+    {
+      name: "merge-tags",
+      requiredVerb: "write",
+      description:
+        "Atomically merge one or more source tags into a target tag: every note carrying any source is retagged with the target, then the source tags (and their identity rows — description/fields/relationships/parent_names) are dropped. target is created if it doesn't exist yet; target's own schema is preserved (sources' schemas are consumed, not merged field-by-field). Sources that don't exist are reported at count 0. Refused with error_type \"tag_in_use_by_tokens\" if a source is referenced by a tag-scoped token — revoke or re-mint it first.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          sources: { type: "array", items: { type: "string" }, description: "Tag names to merge away into target." },
+          target: { type: "string", description: "The tag that survives; sources are retagged onto it and dropped." },
+        },
+        required: ["sources", "target"],
+      },
+      execute: async (params) => {
+        const sources = params.sources;
+        const target = params.target;
+        if (!Array.isArray(sources) || sources.length === 0 || !sources.every((s) => typeof s === "string" && s.length > 0)) {
+          throw structuredError("merge-tags: sources must be a non-empty array of strings", {
+            error_type: "invalid_request",
+            field: "sources",
+          });
+        }
+        if (typeof target !== "string" || target.length === 0) {
+          throw structuredError("merge-tags: target must be a non-empty string", {
+            error_type: "invalid_request",
+            field: "target",
+          });
+        }
+        return await store.mergeTags(sources as string[], target);
       },
     },
 
@@ -1822,6 +1925,22 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
       },
     },
 
+    // =====================================================================
+    // 11. doctor — read-only taxonomy/metadata integrity scan (vault#552)
+    // =====================================================================
+    {
+      name: "doctor",
+      // `admin` — same tier as prune-schema: a diagnostic over the WHOLE
+      // vault's taxonomy, not scoped to any one tag's write authority.
+      requiredVerb: "admin",
+      description:
+        "Read-only integrity scan across the tag/metadata taxonomy — run this after any bulk tag reorg (rename/merge/delete/subtree move) to confirm nothing leaked. Reports, per finding, {type, severity, subject, detail, remedy} — NEVER auto-fixes; apply the suggested remedy (usually rename-tag/merge-tags/update-tag/prune-schema) yourself. Finding types: dangling_parent_name (a parent_names entry naming a tag with no identity row), parent_names_cycle (a tag reaching itself through its ancestor chain — traversal tolerates this, but it's dishonest hierarchy state), mixed_type_indexed_field (a note's metadata value for an indexed field has a JSON type disagreeing with the field's declared storage type — the ordering/filtering-goes-silently-wrong precursor), orphaned_indexed_field_declarer (an indexed field naming a dead declarer tag — see prune-schema), and dead_tag_metadata_reference (HEURISTIC, always carries heuristic:true — a metadata value that looks like a stale reference to a renamed/merged/deleted tag, inferred from sibling notes using the same metadata key with values that ARE live tags; can never be certain since vault keeps no tag-rename history).",
+      inputSchema: { type: "object", properties: {} },
+      execute: async () => {
+        return await store.doctor();
+      },
+    },
+
   ];
 }
 

package/core/src/notes.ts

@@ -1512,40 +1512,114 @@ export function listTags(db: Database): { name: string; count: number; expanded_
   return rows.map((r) => ({ ...r, expanded_count: expandedCounts.get(r.name) ?? 0 }));
 }
 
-export function deleteTag(db: Database, name: string): { deleted: boolean; notes_untagged: number } {
+/** Options accepted by {@link deleteTag} (vault#552). */
+export interface DeleteTagOpts {
+  /**
+   * Proceed with the delete even though another tag's `parent_names`
+   * references this one — strip the reference from every referencing tag's
+   * `parent_names` array as part of the same transaction. Accepted as a
+   * synonym of `detach` (both name the identical repair: remove the stale
+   * reference, never delete the referencing tag itself); offered as two
+   * flags because operators reach for either word depending on whether
+   * they're thinking "cascade the delete" or "detach the children."
+   */
+  cascade?: boolean;
+  /** Synonym of `cascade` — see above. */
+  detach?: boolean;
+}
+
+export type DeleteTagResult =
+  | { deleted: boolean; notes_untagged: number; parent_refs_detached?: number }
+  | { error: "tag_referenced_as_parent"; referencing_tags: string[] };
+
+/**
+ * Delete a tag: drop its identity row, untag every note carrying it, and
+ * release any indexed fields it exclusively declared. Notes themselves are
+ * NEVER deleted — only untagged.
+ *
+ * Referential integrity (vault#552): if another tag's `parent_names` array
+ * names `name`, deleting it would silently orphan that reference — the
+ * child tag's hierarchy edge would point at a name with no identity row
+ * (the exact "renamed-away tag remains a live query surface" class of bug
+ * the gardener found, one hop over from rename). Refuse by default with
+ * `{ error: "tag_referenced_as_parent", referencing_tags }`; pass
+ * `opts.cascade` or `opts.detach` (either — see {@link DeleteTagOpts}) to
+ * proceed, stripping `name` from every referencing tag's `parent_names` in
+ * the same transaction as the delete.
+ */
+export function deleteTag(db: Database, name: string, opts?: DeleteTagOpts): DeleteTagResult {
   const row = db.prepare("SELECT fields FROM tags WHERE name = ?").get(name) as
     | { fields: string | null }
     | null;
   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);
+  // Referential-integrity guard: who names `name` as a parent? Reuses the
+  // SAME parent_names parsing loadTagHierarchy uses everywhere else in the
+  // hierarchy (rather than a bespoke LIKE scan) so "who references this
+  // tag" answers identically here as it does for query expansion.
+  const hierarchy = loadTagHierarchy(db);
+  const referencing = Array.from(hierarchy.childrenOf.get(name) ?? []);
+  if (referencing.length > 0 && !opts?.cascade && !opts?.detach) {
+    return { error: "tag_referenced_as_parent", referencing_tags: referencing.sort() };
+  }
+
+  return transaction(db, (): DeleteTagResult => {
+    // Strip the stale reference from every referencing tag's parent_names
+    // BEFORE dropping this tag's own row — order doesn't matter for
+    // correctness (different rows), but doing the repair first means a
+    // mid-transaction failure never leaves the identity row gone with
+    // dangling references still pointing at it.
+    let parentRefsDetached = 0;
+    if (referencing.length > 0) {
+      const readStmt = db.prepare("SELECT parent_names FROM tags WHERE name = ?");
+      const updateStmt = db.prepare("UPDATE tags SET parent_names = ?, updated_at = ? WHERE name = ?");
+      const now = new Date().toISOString();
+      for (const refTag of referencing) {
+        const r = readStmt.get(refTag) as { parent_names: string | null } | null;
+        if (!r?.parent_names) continue;
+        let parsed: unknown;
+        try { parsed = JSON.parse(r.parent_names); } catch { continue; }
+        if (!Array.isArray(parsed)) continue;
+        const next = (parsed as unknown[]).filter((p) => p !== name);
+        if (next.length === parsed.length) continue;
+        updateStmt.run(next.length > 0 ? JSON.stringify(next) : null, now, refTag);
+        parentRefsDetached++;
+      }
+    }
+
+    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.
       }
-    } 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);
+    db.prepare("DELETE FROM note_tags WHERE tag_name = ?").run(name);
+    db.prepare("DELETE FROM tags WHERE name = ?").run(name);
 
-  return { deleted: true, notes_untagged: notesUntagged };
+    return {
+      deleted: true,
+      notes_untagged: notesUntagged,
+      ...(parentRefsDetached > 0 ? { parent_refs_detached: parentRefsDetached } : {}),
+    };
+  });
 }
 
 // The UNIQUE PRIMARY KEY on tags.name means rename-to-existing is ambiguous: