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

package/core/src/mcp.ts

@@ -10,7 +10,6 @@ import { SEARCH_MODES, buildLiteralSearchQuery, isValidSearchMode, type SearchMo
 import * as linkOps from "./links.js";
 import * as tagSchemaOps from "./tag-schemas.js";
 import type { TagFieldSchema } from "./tag-schemas.js";
-import * as indexedFieldOps from "./indexed-fields.js";
 import {
   SchemaValidationError,
   strictViolations,
@@ -53,6 +52,22 @@ export interface McpToolDef {
 // Helpers
 // ---------------------------------------------------------------------------
 
+/**
+ * Build a plain `Error` carrying a stable `error_type` (+ optional `field`/
+ * `hint`) as duck-typed extra properties — the same pattern `QueryError`
+ * uses for its optional structured fields. For validation leaves that don't
+ * warrant a dedicated exported class (one caller-facing shape, not a reusable
+ * domain error), this is what lets the generic domain-error mapping in
+ * `src/mcp-http.ts` surface `data.error_type` instead of falling through to
+ * the unstructured `isError: true` text fallback (vault#554).
+ */
+function structuredError(
+  message: string,
+  fields: { error_type: string; field?: string; hint?: string },
+): Error {
+  return Object.assign(new Error(message), fields);
+}
+
 /**
  * Resolve a note identifier — tries ID first, then case-insensitive
  * path match. Works everywhere a note reference is accepted.
@@ -86,7 +101,9 @@ function resolveNote(db: Database, idOrPath: string): Note | null {
 
 function requireNote(db: Database, idOrPath: string): Note {
   const note = resolveNote(db, idOrPath);
-  if (!note) throw new Error(`Note not found: "${idOrPath}"`);
+  if (!note) {
+    throw structuredError(`Note not found: "${idOrPath}"`, { error_type: "not_found", field: "id" });
+  }
   return note;
 }
 
@@ -173,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;
@@ -423,7 +442,7 @@ Response shape (vault#550 — three variants, pick by what you passed):
         // --- Single note by ID/path ---
         if (params.id) {
           const note = resolveNote(db, params.id as string);
-          if (!note) return { error: "Note not found", id: params.id };
+          if (!note) return { error: "Note not found", error_type: "not_found", id: params.id };
           const includeContent = params.include_content !== false; // default true for single
           // Range params are meaningless on a content-less shape — error
           // rather than silently ignore (same loud-validation policy as
@@ -471,7 +490,7 @@ Response shape (vault#550 — three variants, pick by what you passed):
         if (params.near) {
           const near = params.near as { note_id: string; depth?: number; relationship?: string };
           const anchor = resolveNote(db, near.note_id);
-          if (!anchor) return { error: "Anchor note not found", note_id: near.note_id };
+          if (!anchor) return { error: "Anchor note not found", error_type: "not_found", note_id: near.note_id };
           const depth = Math.min(near.depth ?? 2, 5);
           const traversed = linkOps.traverseLinks(db, anchor.id, {
             max_depth: depth,
@@ -914,7 +933,7 @@ Response shape (vault#550 — three variants, pick by what you passed):
 - \`links: { add: [{ target, relationship }], remove: [{ target, relationship }] }\` — add/remove links
 - When removing a wikilink-type link, \`[[brackets]]\` are also removed from content.
 - For batch: pass a \`notes\` array, each with an \`id\` field.
-- **Optimistic concurrency is required by default.** Pass \`if_updated_at\` with the \`updated_at\` value you last read — the update is rejected with a conflict error if the note has changed since. Re-read, reconcile, and retry. To skip the safety check (e.g. bulk migration), pass \`force: true\` instead; the update then runs unconditionally. \`force\` only waives the *requirement to supply* \`if_updated_at\` — if you pass both, the precondition you supplied still applies and a mismatch returns a conflict error. \`append\` / \`prepend\` only updates are exempt from the precondition (no-conflict-by-design).
+- **Optimistic concurrency is required by default.** Pass \`if_updated_at\` with the \`updated_at\` value you last read — the update is rejected with a conflict error if the note has changed since. Re-read, reconcile, and retry. To skip the safety check (e.g. bulk migration), pass \`force: true\` instead; the update then runs unconditionally. \`force\` only waives the *requirement to supply* \`if_updated_at\` — if you pass both, the precondition you supplied still applies and a mismatch returns a conflict error. \`append\` / \`prepend\` only updates are exempt from the precondition (no-conflict-by-design). **Batch default (vault#554):** a top-level \`force\` and/or \`if_updated_at\` alongside a \`notes\` array applies as the DEFAULT for every item that doesn't set its own — e.g. \`{force: true, notes: [{id: "a", content: "..."}, {id: "b", content: "...", if_updated_at: "..."}]}\` forces item "a" but still enforces the precondition on item "b" (its own \`if_updated_at\` wins). Per-item values always take precedence over the top-level default.
 - **Idempotent upsert via \`if_missing: "create"\`** — when the note doesn't exist, create it from this same payload (content/path/tags/metadata become the create fields; OC precondition skipped — nothing to conflict with). Response carries \`created: true\`. Useful for nightly sync loops that don't know ahead of time whether the note exists. Default \`"fail"\` (current behavior — missing note errors). See vault#309.
 - \`include_content\` (default \`true\`) — set \`false\` to receive a lean index shape (\`id\`, \`path\`, \`createdAt\`, \`updatedAt\`, \`createdBy\`, \`createdVia\`, \`lastUpdatedBy\`, \`lastUpdatedVia\`, \`tags\`, \`metadata\`, \`byteSize\`, \`preview\`) instead of full content. Useful for agents making frequent small edits to large notes (e.g. via \`append\` or \`content_edit\`) where re-receiving the body is the dominant cost. \`validation_status\` is preserved on the lean shape when present.
 
@@ -1043,7 +1062,23 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
       },
       execute: async (params) => {
         const batch = params.notes as any[] | undefined;
-        const items = batch ?? [params];
+        // vault#554: top-level `force` / `if_updated_at` apply as per-item
+        // DEFAULTS in a batch call — item-level values win when both are
+        // present. Before this fix `items = batch ?? [params]` never merged
+        // the top-level fields into batch items at all, so a caller passing
+        // `{force: true, notes: [...]}` had it silently ignored: every item
+        // without its OWN `force`/`if_updated_at` still threw
+        // `PreconditionRequiredError` (a gardener-reported round-trip cost).
+        // The single-item form (`items = [params]`) already behaved this
+        // way implicitly (params IS the item), so only the batch branch
+        // needs the merge.
+        const items = batch
+          ? batch.map((item: any) => ({
+              ...(params.force !== undefined ? { force: params.force } : {}),
+              ...(params.if_updated_at !== undefined ? { if_updated_at: params.if_updated_at } : {}),
+              ...item,
+            }))
+          : [params];
 
         if (items.length > MAX_BATCH_SIZE) {
           throw new BatchTooLargeError(items.length);
@@ -1175,7 +1210,7 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
               // Fallthrough: not-found + no if_missing → existing error
               // contract. Match `requireNote`'s message shape so existing
               // callers see no behavior change.
-              throw new Error(`Note not found: "${item.id}"`);
+              throw structuredError(`Note not found: "${item.id}"`, { error_type: "not_found", field: "id" });
             }
             const note = resolved;
 
@@ -1185,8 +1220,9 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
             const hasContentEdit = item.content_edit !== undefined;
             const contentModes = (hasContent ? 1 : 0) + (hasAppendPrepend ? 1 : 0) + (hasContentEdit ? 1 : 0);
             if (contentModes > 1) {
-              throw new Error(
+              throw structuredError(
                 `update-note: \`content\`, \`append\`/\`prepend\`, and \`content_edit\` are mutually exclusive — pick one mode of content update for note "${note.id}".`,
+                { error_type: "mutually_exclusive", hint: "pass exactly one of `content`, `append`/`prepend`, or `content_edit`" },
               );
             }
 
@@ -1237,20 +1273,23 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
             if (hasContentEdit) {
               const ce = item.content_edit as { old_text: string; new_text: string };
               if (typeof ce?.old_text !== "string" || typeof ce?.new_text !== "string") {
-                throw new Error(
+                throw structuredError(
                   "update-note: `content_edit` requires { old_text: string, new_text: string }.",
+                  { error_type: "invalid_content_edit", field: "content_edit", hint: "pass { old_text: string, new_text: string }" },
                 );
               }
               const idx = note.content.indexOf(ce.old_text);
               if (idx < 0) {
-                throw new Error(
+                throw structuredError(
                   `update-note content_edit: \`old_text\` not found in note "${note.id}". The note may have been edited — re-read and retry.`,
+                  { error_type: "content_edit_not_found", field: "content_edit.old_text", hint: "re-read the note's current content and retry with an old_text that occurs exactly once" },
                 );
               }
               const second = note.content.indexOf(ce.old_text, idx + 1);
               if (second >= 0) {
-                throw new Error(
+                throw structuredError(
                   `update-note content_edit: \`old_text\` matches multiple times in note "${note.id}" — must match exactly once. Add surrounding context to disambiguate.`,
+                  { error_type: "content_edit_ambiguous", field: "content_edit.old_text", hint: "add surrounding context to old_text so it matches exactly once" },
                 );
               }
               contentOverride = note.content.slice(0, idx) + ce.new_text + note.content.slice(idx + ce.old_text.length);
@@ -1315,8 +1354,9 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
             const stItem = item.state_transition as { field?: unknown; from?: unknown; to?: unknown } | undefined;
             if (stItem !== undefined) {
               if (typeof stItem.field !== "string" || stItem.field.length === 0) {
-                throw new Error(
+                throw structuredError(
                   `update-note: \`state_transition.field\` must be a non-empty string (note "${note.id}").`,
+                  { error_type: "invalid_state_transition", field: "state_transition.field", hint: "pass a non-empty string naming the metadata field to transition" },
                 );
               }
               updates.state_transition = { field: stItem.field, from: stItem.from, to: stItem.to };
@@ -1605,34 +1645,13 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
 
         // Validate cross-tag consistency on fields being (re)declared in this
         // call. `type` and `indexed` are global — all declarers must agree.
-        const otherSchemas = tagSchemaOps
-          .listTagSchemas(db)
-          .filter((s) => s.tag !== tag);
-        for (const [fieldName, spec] of Object.entries(incomingFields)) {
-          const incomingIndexed = spec.indexed === true;
-          for (const other of otherSchemas) {
-            const otherSpec = other.fields?.[fieldName];
-            if (!otherSpec) continue;
-            if (otherSpec.type !== spec.type) {
-              throw new Error(
-                `field "${fieldName}" type conflict: tag "${tag}" declares "${spec.type}"; tag "${other.tag}" declares "${otherSpec.type}". Types must agree across all declarers.`,
-              );
-            }
-            if ((otherSpec.indexed === true) !== incomingIndexed) {
-              throw new Error(
-                `field "${fieldName}" indexed-flag conflict: tag "${tag}" sets indexed=${incomingIndexed}; tag "${other.tag}" sets indexed=${otherSpec.indexed === true}. Must match across all declarers — change them atomically or not at all.`,
-              );
-            }
-          }
-          if (incomingIndexed) {
-            const mapped = indexedFieldOps.mapFieldType(spec.type);
-            if (!mapped) {
-              throw new Error(
-                `field "${fieldName}" has unsupported type "${spec.type}" for indexing (supported: string, integer, boolean)`,
-              );
-            }
-            indexedFieldOps.validateFieldName(fieldName);
-          }
+        // vault#553/#554: collects EVERY violation instead of throwing on the
+        // first — a caller declaring two bad fields sees both in one
+        // response, and the thrown error states explicitly that no changes
+        // were applied (nothing is persisted before this check runs).
+        const fieldViolations = tagSchemaOps.collectTagFieldViolations(db, tag, incomingFields);
+        if (fieldViolations.length > 0) {
+          throw new tagSchemaOps.TagFieldConflictError(tag, fieldViolations);
         }
 
         // ---- relationships: replace wholesale when provided. `relationships`
@@ -1655,7 +1674,11 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
           parentNamesPatch = null;
         } else if (params.parent_names !== undefined) {
           if (!Array.isArray(params.parent_names)) {
-            throw new Error("parent_names must be an array of tag names");
+            throw structuredError("parent_names must be an array of tag names", {
+              error_type: "invalid_parent_names",
+              field: "parent_names",
+              hint: "pass an array of tag name strings, or null to clear",
+            });
           }
           const cleaned = (params.parent_names as unknown[])
             .filter((p): p is string => typeof p === "string" && p.length > 0);
@@ -1695,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"],
       },
@@ -1710,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);
       },
     },
 
@@ -1762,7 +1886,7 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
       execute: () => {
         // This is a placeholder — vault-info needs access to vault config,
         // which is only available in the server layer (mcp-tools.ts).
-        return { error: "vault-info must be configured by the server layer" };
+        return { error: "vault-info must be configured by the server layer", error_type: "not_configured" };
       },
     },
 
@@ -1801,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();
+      },
+    },
+
   ];
 }
 
@@ -1994,6 +2134,9 @@ export class PreconditionRequiredError extends Error {
  */
 export class BatchTooLargeError extends Error {
   code = "BATCH_TOO_LARGE" as const;
+  // Stable error_type (vault#554) — additive; matches the string REST has
+  // hardcoded in its json response since #213.
+  error_type = "batch_too_large" as const;
   limit: number;
   got: number;
 

package/core/src/notes.ts

@@ -284,6 +284,11 @@ export class TransitionConflictError extends Error {
  */
 export class PathConflictError extends Error {
   code = "PATH_CONFLICT" as const;
+  // Stable error_type (vault#554) — additive; mirrors the `error_type` REST
+  // has hardcoded in its json response since #126. Lets the generic MCP
+  // domain-error mapping (src/mcp-http.ts) pick this class up without a
+  // bespoke branch, the same way REST's catch already does explicitly.
+  error_type = "path_conflict" as const;
   path: string;
 
   constructor(path: string) {
@@ -306,6 +311,8 @@ export class PathConflictError extends Error {
  */
 export class AmbiguousPathError extends Error {
   code = "AMBIGUOUS_PATH" as const;
+  // Stable error_type (vault#554) — see PathConflictError's comment.
+  error_type = "ambiguous_path" as const;
   path: string;
   candidates: { id: string; extension: string }[];
 
@@ -346,6 +353,8 @@ export const EXTENSION_PATTERN = /^[a-z0-9]{1,16}$/;
 
 export class ExtensionValidationError extends Error {
   code = "INVALID_EXTENSION" as const;
+  // Stable error_type (vault#554) — see PathConflictError's comment.
+  error_type = "invalid_extension" as const;
   extension: string;
   reason: string;
 
@@ -1503,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: