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

package/core/src/portable-md.test.ts

@@ -1441,6 +1441,113 @@ describe("portable-md non-markdown round-trip (vault#328)", async () => {
     // No sidecar → no DB row.
     expect(stats.notes_created).toBe(0);
   });
+
+  // -------------------------------------------------------------------------
+  // vault#552 — the write-time parent_names cycle guard must NOT abort an
+  // import of an OLD export that carries a mutual-cycle fixture (accepted
+  // before the guard shipped). The offending parent_names is dropped +
+  // warned, the tags + notes still land. On a blow-away replace this is
+  // load-bearing: the vault was already wiped, so an uncaught throw here
+  // would leave it EMPTY with no rollback.
+  // -------------------------------------------------------------------------
+
+  /** Hand-build a portable-md export whose two tag schemas form an A↔B
+   *  parent_names cycle, plus one note tagged with `a`. */
+  function writeCyclicSchemaExport(dir: string): void {
+    mkdirSync(join(dir, SIDECAR_DIR, "schemas"), { recursive: true });
+    writeFileSync(
+      join(dir, SIDECAR_DIR, "vault.yaml"),
+      "export_format_version: 1\nexported_at: '2026-07-09T00:00:00.000Z'\n",
+    );
+    writeFileSync(
+      join(dir, SIDECAR_DIR, "schemas", "a.yaml"),
+      "name: a\ndescription: tag a\nparent_names:\n  - b\n",
+    );
+    writeFileSync(
+      join(dir, SIDECAR_DIR, "schemas", "b.yaml"),
+      "name: b\ndescription: tag b\nparent_names:\n  - a\n",
+    );
+    writeFileSync(
+      join(dir, "note1.md"),
+      "---\nid: note1\npath: note1\ntags:\n  - a\ncreated_at: '2026-07-09T00:00:00.000Z'\nupdated_at: '2026-07-09T00:00:00.000Z'\n---\nhello from note1\n",
+    );
+  }
+
+  it("imports an export carrying a parent_names cycle — the cycle is dropped + warned, not fatal (vault#552 MUST-FIX 1)", async () => {
+    const outDir = join(tmpBase, "cyclic-schemas");
+    writeCyclicSchemaExport(outDir);
+
+    const restored = new SqliteStore(new Database(":memory:"));
+    // MUST complete, not throw.
+    const stats = await importPortableVault(restored, { inDir: outDir });
+
+    // Both schemas + the note landed.
+    expect(stats.schemas_restored).toBe(2);
+    expect(stats.notes_created).toBe(1);
+    expect((await restored.getNote("note1"))!.content.trimEnd()).toBe("hello from note1");
+    expect(await restored.getTagRecord("a")).not.toBeNull();
+    expect(await restored.getTagRecord("b")).not.toBeNull();
+
+    // Exactly one of the two had its parent_names dropped (whichever the
+    // filesystem walk restored SECOND closes the cycle) and is recorded.
+    expect(stats.skipped_schema_parents).toHaveLength(1);
+    const skipped = stats.skipped_schema_parents[0]!;
+    expect(["a", "b"]).toContain(skipped.tag);
+    expect(skipped.reason).toMatch(/cycle/i);
+
+    // The surviving hierarchy is acyclic: at most one of a/b still carries
+    // parent_names (the other was dropped). Never both.
+    const aParents = (await restored.getTagRecord("a"))!.parent_names ?? null;
+    const bParents = (await restored.getTagRecord("b"))!.parent_names ?? null;
+    expect(Boolean(aParents) && Boolean(bParents)).toBe(false);
+  });
+
+  it("blow-away import of a cyclic-schema export leaves the vault populated, NOT empty (vault#552 MUST-FIX 1 — destructive path)", async () => {
+    const outDir = join(tmpBase, "cyclic-blowaway");
+    writeCyclicSchemaExport(outDir);
+
+    // Seed the target with a throwaway note so blow-away has something to
+    // wipe — proving the wipe ran AND that the uncaught-throw regression
+    // (wipe-then-abort → empty vault) is gone.
+    const restored = new SqliteStore(new Database(":memory:"));
+    await restored.createNote("doomed pre-existing note", { id: "old1", path: "old1" });
+
+    const stats = await importPortableVault(restored, { inDir: outDir, blowAway: true });
+
+    expect(stats.notes_wiped).toBe(1); // the pre-existing note was wiped
+    expect(await restored.getNote("old1")).toBeNull(); // gone
+    // Vault is NOT left empty — the fixture note landed despite the cycle.
+    expect((await restored.getNote("note1"))!.content.trimEnd()).toBe("hello from note1");
+    expect(stats.skipped_schema_parents).toHaveLength(1);
+  });
+
+  it("blow-away wipes a parent-before-child hierarchy with NO stale tag rows left (vault#552 MUST-FIX 2)", async () => {
+    // The bug: blow-away's tag sweep called store.deleteTag(tag) with no
+    // flag and ignored the return. listTagRecords is ORDER BY name, so the
+    // namespace parent "task" is visited BEFORE its child "task/work" —
+    // while the child's parent_names still references it — and deleteTag now
+    // RETURNS {error:"tag_referenced_as_parent"} instead of throwing, so the
+    // parent's row silently survived the "clean slate." Fixed by passing
+    // {cascade:true} in the sweep.
+    const target = new SqliteStore(new Database(":memory:"));
+    await target.upsertTagRecord("task", { description: "parent" });
+    await target.upsertTagRecord("task/work", { parent_names: ["task"], description: "child" });
+    await target.createNote("stale note", { id: "stale1", path: "stale1", tags: ["task/work"] });
+
+    // Build a minimal UNRELATED export from a fresh store to replay.
+    const sourceStore = new SqliteStore(new Database(":memory:"));
+    await sourceStore.createNote("fresh body", { id: "fresh1", path: "fresh1", tags: ["fresh"] });
+    const outDir = join(tmpBase, "blowaway-hierarchy-source");
+    await exportVaultToDir(sourceStore, { outDir, exportedAt: "2026-07-09T00:00:00.000Z" });
+
+    await importPortableVault(target, { inDir: outDir, blowAway: true });
+
+    // After a full wipe, NEITHER old hierarchy tag row survives.
+    const remaining = (await target.listTagRecords()).map((t) => t.tag);
+    expect(remaining).not.toContain("task");
+    expect(remaining).not.toContain("task/work");
+    expect(await target.getNote("stale1")).toBeNull();
+  });
 });
 
 // ---------------------------------------------------------------------------

package/core/src/portable-md.ts

@@ -76,6 +76,7 @@ import { readdirSync, readFileSync, realpathSync, statSync, mkdirSync, writeFile
 import { basename, join, relative, extname, dirname, resolve as resolvePath, sep as pathSep } from "path";
 import type { Store, Note, Link, Attachment } from "./types.js";
 import type { TagRecord } from "./tag-schemas.js";
+import { ParentCycleError } from "./tag-schemas.js";
 
 // ---------------------------------------------------------------------------
 // Format constants
@@ -1631,6 +1632,17 @@ export interface ImportStats {
    * content file during the walk.
    */
   skipped_sidecars: Array<{ sidecar_id: string; expected_path: string | null; expected_extension: string | null; reason: string }>;
+  /**
+   * Tag schemas whose `parent_names` was DROPPED on restore because it
+   * would have created a hierarchy cycle (vault#552 — the write-time cycle
+   * guard in `upsertTagRecord`). The tag itself is still restored (its
+   * description/fields/relationships land); only the offending
+   * `parent_names` is skipped, so the import completes instead of aborting
+   * mid-flight on an uncaught `ParentCycleError`. An OLD export that carried
+   * a mutual-cycle fixture (accepted before the guard shipped) still
+   * imports — the cycle is warned, not fatal. Empty in the common case.
+   */
+  skipped_schema_parents: Array<{ tag: string; parent_names: string[]; reason: string }>;
   /** Set when the caller passed `blowAway: true`; counts notes removed. */
   notes_wiped: number;
   /**
@@ -1802,6 +1814,7 @@ export async function importVault(
     skipped_links: [],
     skipped_attachments: [],
     skipped_sidecars: [],
+    skipped_schema_parents: [],
     notes_wiped: 0,
     indexes_declared: 0,
   };
@@ -1821,10 +1834,18 @@ export async function importVault(
       }
     }
     // Clear tag rows too — `deleteNote` clears note_tags via FK cascade but
-    // leaves the `tags` table rows in place (orphaned schemas).
+    // leaves the `tags` table rows in place (orphaned schemas). `cascade:
+    // true` is REQUIRED here (vault#552): a blow-away is a full wipe, and
+    // `listTagRecords` returns rows `ORDER BY name`, so a namespace parent
+    // (`task`) sorts before its child (`task/work`) and is visited while the
+    // child's `parent_names` still references it — without `cascade`,
+    // `deleteTag` would RETURN `{error: "tag_referenced_as_parent"}` (it no
+    // longer throws) and silently leave the parent's row behind, defeating
+    // the "clean slate." Since we're deleting every tag anyway, cascading the
+    // parent_names strip is exactly right.
     const tagRecords = await store.listTagRecords();
     for (const tag of tagRecords) {
-      await store.deleteTag(tag.tag);
+      await store.deleteTag(tag.tag, { cascade: true });
     }
   }
 
@@ -1842,12 +1863,37 @@ export async function importVault(
       stats.schemas_restored++;
       continue;
     }
-    await store.upsertTagRecord(tagName, {
+    const parentNames = (frontmatter.parent_names as string[] | null | undefined) ?? null;
+    const patch = {
       description: (frontmatter.description as string | null | undefined) ?? null,
       fields: (frontmatter.fields as Record<string, unknown> | null | undefined) as any ?? null,
       relationships: (frontmatter.relationships as Record<string, unknown> | null | undefined) as any ?? null,
-      parent_names: (frontmatter.parent_names as string[] | null | undefined) ?? null,
-    });
+      parent_names: parentNames,
+    };
+    try {
+      await store.upsertTagRecord(tagName, patch);
+    } catch (err) {
+      // vault#552: the write-time cycle guard rejects a `parent_names` that
+      // would close a hierarchy cycle. An OLD export carrying a mutual-cycle
+      // fixture (accepted before the guard shipped) must still import —
+      // dropping the offending `parent_names` and warning, not aborting the
+      // whole import mid-flight (import isn't atomic; on a blow-away replace
+      // the vault was already wiped in step 1, so an uncaught throw here
+      // would leave it EMPTY). Retry WITHOUT parent_names so the tag's
+      // description/fields/relationships still land; record a skip warning
+      // mirroring the skipped_links/skipped_attachments/skipped_sidecars
+      // precedent. Any OTHER error still propagates.
+      if (err instanceof ParentCycleError) {
+        stats.skipped_schema_parents.push({
+          tag: tagName,
+          parent_names: parentNames ?? [],
+          reason: `parent_names would create a hierarchy cycle (${err.cycle.join(" → ")}); dropped on import`,
+        });
+        await store.upsertTagRecord(tagName, { ...patch, parent_names: null });
+      } else {
+        throw err;
+      }
+    }
     stats.schemas_restored++;
   }
 

package/core/src/store.ts

@@ -35,6 +35,7 @@ import {
   type ConformanceReport,
 } from "./conformance.js";
 import type { SearchMode } from "./search-query.js";
+import { runDoctorScan, type DoctorReport, type DoctorScanOpts } from "./doctor.js";
 
 /**
  * bun:sqlite-backed Store implementation. Internally everything is
@@ -457,10 +458,15 @@ export class BunSqliteStore implements Store {
     return noteOps.listTags(this.db);
   }
 
-  async deleteTag(name: string): Promise<{ deleted: boolean; notes_untagged: number }> {
-    const result = noteOps.deleteTag(this.db, name);
+  async deleteTag(name: string, opts?: noteOps.DeleteTagOpts): Promise<noteOps.DeleteTagResult> {
+    const result = noteOps.deleteTag(this.db, name, opts);
+    // Referential-integrity refusal (vault#552) — nothing was written;
+    // caches and hooks are untouched.
+    if ("error" in result) return result;
     // The deleted tag may have been a parent or child in the hierarchy
-    // and may have declared `fields` powering schema validation.
+    // and may have declared `fields` powering schema validation. A
+    // cascade/detach repair also rewrites OTHER tags' parent_names, so
+    // busting the hierarchy cache covers both cases.
     this._tagHierarchy = null;
     this._schemaConfig = null;
     // Fire "deleted" only when SOMETHING happened (the underlying
@@ -644,6 +650,14 @@ export class BunSqliteStore implements Store {
     return count;
   }
 
+  /**
+   * Read-only taxonomy/metadata integrity scan (vault#552). Pure read — no
+   * cache invalidation needed since nothing is written.
+   */
+  async doctor(opts?: DoctorScanOpts): Promise<DoctorReport> {
+    return runDoctorScan(this.db, opts);
+  }
+
   // ---- Tag Records (post-v14: full identity row) ----
 
   async listTagRecords() {

package/core/src/tag-hierarchy.ts

@@ -388,3 +388,69 @@ export function findHierarchyCycles(h: TagHierarchy): string[] {
   }
   return cycles;
 }
+
+/**
+ * Cycle guard for a PROSPECTIVE `parent_names` write (vault#552). Setting
+ * `tag`'s parents to include `p` adds the edge `childrenOf[p] += tag` (tag
+ * becomes a child of `p`). That closes a cycle iff `tag` can ALREADY reach
+ * `p` via the existing hierarchy — i.e. `p` is already in `tag`'s descendant
+ * set — because the new edge would then let `p` reach back to itself through
+ * `tag`. Self-parent (`parentNames` containing `tag` itself) is caught by the
+ * same check: `getTagDescendants` always includes `tag` in its own result.
+ *
+ * Returns the offending cycle path (`[tag, ...existing chain down to p, p,
+ * tag]`, closing the loop) for the FIRST conflicting parent found, or `null`
+ * when no cycle would result. `h` must reflect the hierarchy BEFORE this
+ * write — the check only depends on OTHER tags' parent_names (edges pointing
+ * away from `tag`), never `tag`'s own current parent_names, so passing the
+ * pre-write hierarchy is always correct regardless of write ordering.
+ */
+export function findParentCycle(
+  h: TagHierarchy,
+  tag: string,
+  parentNames: string[],
+): string[] | null {
+  const descendants = getTagDescendants(h, tag);
+  for (const p of parentNames) {
+    if (descendants.has(p)) {
+      return [...findChildPath(h, tag, p), tag];
+    }
+  }
+  return null;
+}
+
+/**
+ * BFS shortest path from `from` to `to` following `childrenOf` edges
+ * (parent → child). Used only to render a human-legible cycle path for
+ * {@link findParentCycle}'s error — the existence of a path is already
+ * established by the caller (`to` is a known member of `from`'s descendant
+ * set) before this runs, so the fallback return is unreachable in practice
+ * and exists only to keep the function total.
+ */
+function findChildPath(h: TagHierarchy, from: string, to: string): string[] {
+  if (from === to) return [from];
+  const queue: string[] = [from];
+  const cameFrom = new Map<string, string>();
+  const visited = new Set<string>([from]);
+  while (queue.length > 0) {
+    const current = queue.shift()!;
+    const children = h.childrenOf.get(current);
+    if (!children) continue;
+    for (const child of children) {
+      if (visited.has(child)) continue;
+      visited.add(child);
+      cameFrom.set(child, current);
+      if (child === to) {
+        const path = [to];
+        let node = to;
+        while (cameFrom.has(node)) {
+          node = cameFrom.get(node)!;
+          path.unshift(node);
+        }
+        return path;
+      }
+      queue.push(child);
+    }
+  }
+  return [from, to];
+}

package/core/src/tag-schemas.ts

@@ -17,6 +17,7 @@
 
 import { Database } from "bun:sqlite";
 import { mapFieldType, validateFieldName } from "./indexed-fields.js";
+import { loadTagHierarchy, findParentCycle } from "./tag-hierarchy.js";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -132,10 +133,48 @@ export function getTagRecord(db: Database, tag: string): TagRecord | null {
   return row ? rowToRecord(row) : null;
 }
 
+/**
+ * Thrown by `upsertTagRecord` (and therefore by both `PUT /api/tags/:name`
+ * and the MCP `update-tag` tool — this is the single chokepoint both share,
+ * see `core/src/store.ts:upsertTagRecord`) when the incoming `parent_names`
+ * would create a cycle in the hierarchy (vault#552). Traversal elsewhere
+ * (`getTagDescendants`) is already cycle-safe — a visited-set stops it from
+ * looping forever — but the WRITE itself was dishonest about creating one:
+ * an adversarial or accidental `A→B` then `B→A` (or a bare self-parent)
+ * silently succeeded pre-#552. `cycle` is the offending path, e.g.
+ * `["A", "B", "A"]` for a direct A↔B cycle, or the longer chain for a
+ * transitive one; the SERVER layer scope-scrubs out-of-scope names in it
+ * for a tag-scoped caller (`scrubParentCycleError` in src/tag-scope.ts),
+ * same posture as `TagFieldConflictError`.
+ */
+export class ParentCycleError extends Error {
+  code = "PARENT_CYCLE" as const;
+  error_type = "parent_cycle" as const;
+  tag: string;
+  cycle: string[];
+
+  constructor(tag: string, cycle: string[]) {
+    super(
+      `parent_cycle: setting "${tag}"'s parent_names would create a cycle: ${cycle.join(" → ")}`,
+    );
+    this.name = "ParentCycleError";
+    this.tag = tag;
+    this.cycle = cycle;
+  }
+}
+
 /**
  * Upsert a tag record — partial update. Any field left `undefined` is
  * preserved. Pass `null` explicitly to clear a column. Always touches
  * `updated_at`; sets `created_at` on first insert.
+ *
+ * Cycle guard (vault#552): when `patch.parent_names` is a non-empty array,
+ * validate it against the CURRENT hierarchy (loaded fresh — this function is
+ * the shared chokepoint for both REST and MCP, so it can't rely on a
+ * possibly-stale caller cache) before touching any row. A conflicting parent
+ * throws {@link ParentCycleError} and nothing is persisted — same
+ * fail-closed-before-any-write posture as the cross-tag field-conflict
+ * checks in this module.
  */
 export function upsertTagRecord(
   db: Database,
@@ -147,6 +186,12 @@ export function upsertTagRecord(
     parent_names?: string[] | null;
   },
 ): TagRecord {
+  if (patch.parent_names != null && patch.parent_names.length > 0) {
+    const hierarchy = loadTagHierarchy(db);
+    const cycle = findParentCycle(hierarchy, tag, patch.parent_names);
+    if (cycle) throw new ParentCycleError(tag, cycle);
+  }
+
   const now = new Date().toISOString();
   db.prepare(
     "INSERT OR IGNORE INTO tags (name, created_at, updated_at) VALUES (?, ?, ?)",

package/core/src/types.ts

@@ -6,6 +6,7 @@ import type { SearchMode } from "./search-query.js";
 import type { ValidationStatus } from "./schema-defaults.js";
 import type { ConformanceReport } from "./conformance.js";
 import type { FindPathResult } from "./links.js";
+import type { DoctorReport, DoctorScanOpts } from "./doctor.js";
 
 // ---- Re-exports ----
 
@@ -14,6 +15,7 @@ export type { PrunedField } from "./indexed-fields.js";
 export type { TagExpandMode, TagHierarchy } from "./tag-hierarchy.js";
 export type { ConformanceReport } from "./conformance.js";
 export type { FindPathResult } from "./links.js";
+export type { DoctorReport, DoctorFinding, DoctorFindingType, DoctorSeverity, DoctorScanOpts } from "./doctor.js";
 
 // ---- Note ----
 
@@ -364,7 +366,20 @@ export interface Store {
    * alongside the literal `count`. See `core/src/tag-hierarchy.ts:computeExpandedTagCounts`.
    */
   listTags(): Promise<{ name: string; count: number; expanded_count: number }[]>;
-  deleteTag(name: string): Promise<{ deleted: boolean; notes_untagged: number }>;
+  /**
+   * Delete a tag. Refused (vault#552) when another tag's `parent_names`
+   * still references it — pass `cascade` or `detach` (synonyms; either
+   * strips the stale reference from the referencing tags' `parent_names`
+   * in the same transaction) to proceed anyway. Notes are never deleted,
+   * only untagged.
+   */
+  deleteTag(
+    name: string,
+    opts?: { cascade?: boolean; detach?: boolean },
+  ): Promise<
+    | { deleted: boolean; notes_untagged: number; parent_refs_detached?: number }
+    | { error: "tag_referenced_as_parent"; referencing_tags: string[] }
+  >;
   renameTag(
     oldName: string,
     newName: string,
@@ -431,6 +446,13 @@ export interface Store {
    */
   reconcileDeclaredIndexes(): Promise<number>;
 
+  /**
+   * Read-only taxonomy/metadata integrity scan (vault#552). Never mutates —
+   * every finding carries a suggested `remedy` the caller applies
+   * deliberately. See `core/src/doctor.ts` for the finding-type catalog.
+   */
+  doctor(opts?: DoctorScanOpts): Promise<DoctorReport>;
+
   // Tag records — full v14 identity row (description + fields + typed
   // relationships + parent_names + timestamps). See
   // docs/contracts/tag-data-model.md.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/vault",
-  "version": "0.7.0-rc.4",
+  "version": "0.7.0-rc.5",
   "description": "Agent-native knowledge graph. Notes, tags, links over MCP.",
   "module": "src/cli.ts",
   "type": "module",

package/src/mcp-http.ts

@@ -170,6 +170,8 @@ async function handleMcp(
         reason?: string;
         limit?: number;
         tag?: string;
+        cycle?: unknown;
+        referencing_tags?: unknown;
       };
       // Honest-queries validation errors (vault#550) — `limit`/`offset`/date
       // values that are structurally invalid rather than merely "no
@@ -313,6 +315,17 @@ async function handleMcp(
           violations: e.violations ?? [],
         });
       }
+      // parent_names cycle guard (vault#552) — `update-tag`'s write would
+      // close a cycle. Mirrors REST's 409 `parent_cycle` shape; the tool
+      // wrapper (src/mcp-tools.ts) scope-scrubs `cycle` before this throw
+      // for a tag-scoped caller, same as TAG_FIELD_CONFLICT above.
+      if (e?.code === "PARENT_CYCLE") {
+        throw new McpError(ErrorCode.InvalidRequest, message, {
+          error_type: "parent_cycle",
+          tag: e.tag,
+          cycle: e.cycle ?? [],
+        });
+      }
       // Generic catch-all (vault#554): any remaining error that carries a
       // stable `error_type` — either a domain error class that stamps it as
       // an instance property (IndexedFieldError, and the classes handled by

package/src/mcp-tools.ts

@@ -23,11 +23,14 @@ import {
   filterHydratedLinksByTagScope,
   noteWithinTagScope,
   scrubIndexedFieldConflictError,
+  scrubParentCycleError,
+  scrubReferencingTagsByScope,
   scrubTagFieldViolationsByScope,
   tagsWithinScope,
 } from "./tag-scope.ts";
-import { TagFieldConflictError } from "../core/src/tag-schemas.ts";
+import { TagFieldConflictError, ParentCycleError } from "../core/src/tag-schemas.ts";
 import { IndexedFieldError } from "../core/src/indexed-fields.ts";
+import { runDoctorScan } from "../core/src/doctor.ts";
 import {
   findTokensReferencingTag,
   recordMcpMintLedger,
@@ -219,11 +222,12 @@ export function generateScopedMcpTools(
 }
 
 /**
- * Tag-delete and (future) tag-merge always check for tag-scoped tokens
- * referencing the doomed tag — regardless of whether the *deleter* is
- * itself tag-scoped. A successful delete that orphans an allowlist would
+ * Tag-delete and tag-merge always check for tag-scoped tokens referencing
+ * the doomed tag(s) — regardless of whether the CALLER is itself
+ * tag-scoped. A successful delete/merge that orphans an allowlist would
  * silently widen surface area downstream. Mirrors the REST 409
- * `tag_in_use_by_tokens` envelope.
+ * `tag_in_use_by_tokens` envelope (routes.ts's DELETE /tags/:name and
+ * POST /tags/merge run the identical check).
  */
 function applyTagDependencyGuards(tools: McpToolDef[], vaultName: string): void {
   const store = getVaultStore(vaultName);
@@ -243,6 +247,29 @@ function applyTagDependencyGuards(tools: McpToolDef[], vaultName: string): void
     }
     return await orig(params);
   });
+  // vault#552: merging consumes every source tag (same identity-drop as
+  // delete), so a source referenced by a tag-scoped token would orphan that
+  // token's allowlist exactly like a bare delete would. Aggregate matches
+  // across all sources into one 409-equivalent envelope, same shape REST's
+  // POST /tags/merge returns.
+  wrapReadTool(tools, "merge-tags", async (orig, params) => {
+    const sources = Array.isArray((params as any).sources) ? ((params as any).sources as unknown[]) : [];
+    const referenced: { source: string; tokens: { id: string; label: string }[] }[] = [];
+    for (const src of sources) {
+      if (typeof src !== "string") continue;
+      const tokens = findTokensReferencingTag(store.db, src);
+      if (tokens.length > 0) referenced.push({ source: src, tokens });
+    }
+    if (referenced.length > 0) {
+      return {
+        error: "TagInUseByTokens",
+        error_type: "tag_in_use_by_tokens",
+        message: `Cannot merge: ${referenced.length} source tag(s) referenced by tag-scoped token(s); revoke or re-mint them first.`,
+        referenced_by: referenced,
+      };
+    }
+    return await orig(params);
+  });
 }
 
 /**
@@ -535,6 +562,14 @@ function applyTagScopeWrappers(
       if (err instanceof IndexedFieldError) {
         throw scrubIndexedFieldConflictError(err, allowed);
       }
+      // parent_names cycle guard (vault#552) — the hierarchy `upsertTagRecord`
+      // validates against is vault-wide (scope-unaware by architecture), so
+      // the cycle path can name an out-of-scope tag. Same "write stays
+      // rejected, path gets generalized" posture as the field-conflict scrub
+      // above.
+      if (err instanceof ParentCycleError) {
+        throw scrubParentCycleError(err, allowed);
+      }
       throw err;
     }
   });
@@ -546,9 +581,59 @@ function applyTagScopeWrappers(
     if (typeof tag === "string" && !allowed.has(tag)) {
       return forbidden(`delete-tag: tag "${tag}" is outside the token's allowlist`);
     }
+    const result = await orig(params);
+    // Referential-integrity refusal (vault#552) — scrub out-of-scope
+    // referencing tag names before returning. The delete stays refused
+    // either way; only the response's tag-name visibility changes.
+    if (result && typeof result === "object" && (result as any).error_type === "tag_referenced_as_parent") {
+      return {
+        ...(result as Record<string, unknown>),
+        referencing_tags: scrubReferencingTagsByScope((result as any).referencing_tags ?? [], allowed),
+      };
+    }
+    return result;
+  });
+
+  // rename-tag / merge-tags (vault#552 — MCP parity with the pre-existing
+  // REST engine). Same tag-scope posture as update-tag/delete-tag: every
+  // tag NAMED in the request (source(s) + target, or old/new name) must be
+  // inside the caller's allowlist — a rename/merge that pulls a tag out of
+  // scope (or in) is a privilege-boundary move, refuse the whole op before
+  // it reaches core.
+  wrapReadTool(tools, "rename-tag", async (orig, params) => {
+    const allowed = await getAllowed();
+    if (!allowed) return await orig(params);
+    const oldName = (params as any).old_name ?? (params as any).from ?? (params as any).tag;
+    const newName = (params as any).new_name ?? (params as any).to;
+    for (const t of [oldName, newName]) {
+      if (typeof t === "string" && !allowed.has(t)) {
+        return forbidden(`rename-tag: tag "${t}" is outside the token's allowlist`);
+      }
+    }
+    return await orig(params);
+  });
+
+  wrapReadTool(tools, "merge-tags", async (orig, params) => {
+    const allowed = await getAllowed();
+    if (!allowed) return await orig(params);
+    const sources = Array.isArray((params as any).sources) ? ((params as any).sources as unknown[]) : [];
+    const target = (params as any).target;
+    for (const t of [...sources, target]) {
+      if (typeof t === "string" && !allowed.has(t)) {
+        return forbidden(`merge-tags: tag "${t}" is outside the token's allowlist`);
+      }
+    }
     return await orig(params);
   });
 
+  // doctor (vault#552) — the scan itself is re-run with the caller's
+  // expanded allowlist rather than post-filtering the unscoped result, so
+  // aggregate counts (findings summary) never reflect out-of-scope data.
+  wrapReadTool(tools, "doctor", async (orig, params) => {
+    const allowed = await getAllowed();
+    if (!allowed) return await orig(params);
+    return runDoctorScan(store.db, { allowedTags: allowed });
+  });
 }
 
 function wrapReadTool(

package/src/mirror-import.ts

@@ -518,6 +518,11 @@ function importResultFromStats(
       `Orphaned sidecar ${ss.sidecar_id} (path=${ss.expected_path ?? "—"}): ${ss.reason}`,
     );
   }
+  for (const sp of stats.skipped_schema_parents) {
+    warnings.push(
+      `Dropped parent_names on tag "${sp.tag}": ${sp.reason}`,
+    );
+  }
   const result: ImportResult = {
     notes_imported: stats.notes_created + stats.notes_updated,
     tags_imported: stats.schemas_restored,