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

package/core/src/contract-taxonomy.test.ts

@@ -9,9 +9,12 @@
  * flipped to real assertions in a later wave. See #552 for the full write-up.
  */
 
-import { describe, it, test, expect, beforeEach } from "bun:test";
+import { describe, it, expect, beforeEach } from "bun:test";
 import { Database } from "bun:sqlite";
 import { SqliteStore } from "./store.js";
+import { generateMcpTools } from "./mcp.js";
+import { ParentCycleError } from "./tag-schemas.js";
+import { declareField } from "./indexed-fields.js";
 
 let store: SqliteStore;
 let db: Database;
@@ -100,20 +103,193 @@ describe("contract: taxonomy — passing (lock in current behavior)", () => {
   });
 });
 
-describe("contract: taxonomy — todo (#552)", () => {
-  test.todo(
-    "#552: deleting a tag still referenced in another tag's parent_names errors unless cascade/detach is passed (today: store.deleteTag succeeds unconditionally and leaves the referencing tag's parent_names pointing at a now-nonexistent tag name — verified with a fresh parent/child fixture)",
-  );
-  test.todo(
-    "#552: a parent_names cycle (A declares parent B, then B declares parent A) is rejected at write time (today: store.upsertTagRecord accepts both writes with no cycle check — traversal elsewhere is cycle-safe, but the write itself is not honest about creating one)",
-  );
-  test.todo(
-    "#552: rename-tag is exposed as an MCP tool, not just a REST endpoint (today: POST /api/tags/:name/rename exists and store.renameTag is wired, but generateMcpTools has no rename-tag tool — an MCP-only agent cannot rename a tag)",
-  );
-  test.todo(
-    "#552: merge-tags is exposed as an MCP tool, not just a REST endpoint (today: POST /api/tags/merge exists and store.mergeTags is wired, but generateMcpTools has no merge-tags tool)",
-  );
-  test.todo(
-    "#552: a `vault doctor` integrity scan reports dangling parent_names references (today: no doctor/scan surface inspects parent_names for referential integrity — the delete-tag gap above goes undetected)",
-  );
+describe("contract: taxonomy — #552 (flipped from test.todo)", () => {
+  it("rename-tag is exposed as an MCP tool and cascades parent_names — the gardener's exact bug no longer happens", async () => {
+    // Root tag, a child that declares it as a parent (the parent_names
+    // surface the gardener's rename left orphaned), and a note tagged with
+    // the CHILD only (proves subtype expansion still finds it post-rename).
+    await store.upsertTagRecord("proj", { description: "root project tag" });
+    await store.upsertTagRecord("special", { parent_names: ["proj"] });
+    const childTagged = await store.createNote("filed under the child tag", { tags: ["special"] });
+
+    const tools = generateMcpTools(store);
+    const renameTag = tools.find((t) => t.name === "rename-tag");
+    expect(renameTag).toBeDefined();
+    expect(renameTag!.requiredVerb).toBe("write");
+
+    const result = await renameTag!.execute({ old_name: "proj", new_name: "initiative" }) as any;
+    expect("error" in result).toBe(false);
+    expect(result.parent_refs_updated).toBeGreaterThanOrEqual(1);
+
+    // The exact gardener's bug: "special"'s parent_names must follow the
+    // rename, not keep pointing at the now-dead "proj".
+    const special = await store.getTagRecord("special");
+    expect(special?.parent_names).toEqual(["initiative"]);
+
+    // The renamed-away tag is NOT a live query surface anymore.
+    const projRecord = await store.getTagRecord("proj");
+    expect(projRecord).toBeNull();
+
+    // The NEW tag doesn't silently miss child-tagged notes (the gardener's
+    // second symptom): subtype expansion of "initiative" still reaches the
+    // note tagged only with the child "special".
+    const viaExpansion = await store.queryNotes({ tags: ["initiative"] });
+    expect(viaExpansion.map((n) => n.id)).toContain(childTagged.id);
+  });
+
+  it("rename-tag MCP tool reports target_exists (not a silent overwrite) and tag_not_found for a missing source", async () => {
+    await store.upsertTagRecord("a", {});
+    await store.upsertTagRecord("b", {});
+    const tools = generateMcpTools(store);
+    const renameTag = tools.find((t) => t.name === "rename-tag")!;
+
+    let caught: any;
+    try {
+      await renameTag.execute({ old_name: "a", new_name: "b" });
+    } catch (e) { caught = e; }
+    expect(caught?.error_type).toBe("target_exists");
+    expect(caught?.conflicting).toContain("b");
+
+    caught = undefined;
+    try {
+      await renameTag.execute({ old_name: "nonexistent", new_name: "whatever" });
+    } catch (e) { caught = e; }
+    expect(caught?.error_type).toBe("tag_not_found");
+  });
+
+  it("merge-tags is exposed as an MCP tool and merges N sources into one target", async () => {
+    await store.upsertTagRecord("draft", {});
+    await store.upsertTagRecord("wip", {});
+    const draftNote = await store.createNote("draft note", { tags: ["draft"] });
+    const wipNote = await store.createNote("wip note", { tags: ["wip"] });
+
+    const tools = generateMcpTools(store);
+    const mergeTags = tools.find((t) => t.name === "merge-tags");
+    expect(mergeTags).toBeDefined();
+    expect(mergeTags!.requiredVerb).toBe("write");
+
+    const result = await mergeTags!.execute({ sources: ["draft", "wip"], target: "active" }) as any;
+    expect(result.target).toBe("active");
+    expect(result.merged.draft).toBe(1);
+    expect(result.merged.wip).toBe(1);
+
+    const draftAfter = await store.getNote(draftNote.id);
+    const wipAfter = await store.getNote(wipNote.id);
+    expect(draftAfter!.tags).toEqual(["active"]);
+    expect(wipAfter!.tags).toEqual(["active"]);
+    expect(await store.getTagRecord("draft")).toBeNull();
+    expect(await store.getTagRecord("wip")).toBeNull();
+  });
+
+  it("delete-tag refuses a tag still referenced in another tag's parent_names, then cascade/detach both proceed and strip the reference", async () => {
+    await store.upsertTagRecord("proj", { description: "root" });
+    await store.upsertTagRecord("child", { parent_names: ["proj"] });
+
+    const tools = generateMcpTools(store);
+    const deleteTag = tools.find((t) => t.name === "delete-tag")!;
+
+    // Default (no flag): refused, nothing mutated.
+    const refused = await deleteTag.execute({ tag: "proj" }) as any;
+    expect(refused.error).toBe("tag_referenced_as_parent");
+    expect(refused.referencing_tags).toEqual(["child"]);
+    expect(await store.getTagRecord("proj")).not.toBeNull();
+    expect((await store.getTagRecord("child"))?.parent_names).toEqual(["proj"]);
+
+    // cascade: true proceeds and strips the stale reference.
+    const cascaded = await deleteTag.execute({ tag: "proj", cascade: true }) as any;
+    expect(cascaded.deleted).toBe(true);
+    expect(cascaded.parent_refs_detached).toBe(1);
+    expect(await store.getTagRecord("proj")).toBeNull();
+    expect((await store.getTagRecord("child"))?.parent_names ?? null).toBeFalsy();
+
+    // detach is a synonym — same repair, exercised on a second fixture.
+    await store.upsertTagRecord("proj2", { description: "root2" });
+    await store.upsertTagRecord("child2", { parent_names: ["proj2"] });
+    const detached = await deleteTag.execute({ tag: "proj2", detach: true }) as any;
+    expect(detached.deleted).toBe(true);
+    expect(detached.parent_refs_detached).toBe(1);
+    expect((await store.getTagRecord("child2"))?.parent_names ?? null).toBeFalsy();
+  });
+
+  it("a parent_names cycle (direct A→B→A, and bare self-parent) is rejected at write time with error_type parent_cycle", async () => {
+    await store.upsertTagRecord("B", {});
+    await store.upsertTagRecord("A", { parent_names: ["B"] });
+
+    let caught: unknown;
+    try {
+      await store.upsertTagRecord("B", { parent_names: ["A"] });
+    } catch (e) { caught = e; }
+    expect(caught).toBeInstanceOf(ParentCycleError);
+    const cycleErr = caught as ParentCycleError;
+    expect(cycleErr.error_type).toBe("parent_cycle");
+    expect(cycleErr.tag).toBe("B");
+    expect(cycleErr.cycle).toContain("A");
+    expect(cycleErr.cycle).toContain("B");
+    // Nothing persisted — B's parent_names is untouched by the rejected write.
+    expect((await store.getTagRecord("B"))?.parent_names ?? null).toBeFalsy();
+
+    // Bare self-parent: also caught (getTagDescendants always includes the
+    // tag itself).
+    let selfCaught: unknown;
+    try {
+      await store.upsertTagRecord("C", { parent_names: ["C"] });
+    } catch (e) { selfCaught = e; }
+    expect(selfCaught).toBeInstanceOf(ParentCycleError);
+    expect((selfCaught as ParentCycleError).cycle).toEqual(["C", "C"]);
+  });
+
+  it("doctor reports each finding type on a seeded-broken fixture, and stays clean on a healthy one", async () => {
+    // 1. dangling_parent_name — "ghost-parent" is never created as a tag row.
+    await store.upsertTagRecord("orphan-child", { parent_names: ["ghost-parent"] });
+
+    // 2. parent_names_cycle — the write-time guard blocks NEW cycles, so
+    // simulate pre-existing/pre-guard cyclic data with a direct DB write
+    // (same technique core.test.ts's cycle-tolerance tests use).
+    await store.upsertTagRecord("cyc-a", {});
+    await store.upsertTagRecord("cyc-b", { parent_names: ["cyc-a"] });
+    db.prepare("UPDATE tags SET parent_names = ? WHERE name = ?").run(JSON.stringify(["cyc-b"]), "cyc-a");
+
+    // 3. mixed_type_indexed_field — "n" is indexed INTEGER, but this note's
+    // metadata.n is a JSON string. Not `strict`, so the write succeeds with
+    // just an advisory warning — landing exactly the mismatched value.
+    await store.upsertTagRecord("metric", { fields: { n: { type: "integer", indexed: true } } });
+    await store.createNote("bad metric", { tags: ["metric"], metadata: { n: "not-a-number" } });
+
+    // 4. orphaned_indexed_field_declarer — declare directly via the
+    // indexed-fields API, then drop the tag row WITHOUT releasing (the
+    // pre-fix gitcoin state prune-schema's own tests seed identically).
+    declareField(db, "legacy_status", "TEXT", "ghost-declarer");
+
+    // 5. dead_tag_metadata_reference (heuristic) — "epic" holds tag-shaped
+    // values elsewhere (a live tag), so a value that ISN'T a live tag is
+    // the drift signal.
+    await store.upsertTagRecord("launch-v2", {});
+    await store.createNote("current epic", { tags: ["launch-v2"], metadata: { epic: "launch-v2" } });
+    await store.createNote("stale epic reference", { tags: ["launch-v2"], metadata: { epic: "launch-v1" } });
+
+    const report = await store.doctor();
+    const byType = new Map(report.findings.map((f) => [f.type, f]));
+
+    expect(byType.get("dangling_parent_name")?.subject).toBe("orphan-child");
+    expect(byType.get("parent_names_cycle")).toBeDefined();
+    expect(byType.get("mixed_type_indexed_field")?.subject).toBe("n");
+    expect(byType.get("mixed_type_indexed_field")?.severity).toBe("error");
+    expect(byType.get("orphaned_indexed_field_declarer")?.subject).toBe("legacy_status");
+    const driftFinding = byType.get("dead_tag_metadata_reference");
+    expect(driftFinding?.subject).toBe("metadata.epic");
+    expect(driftFinding?.heuristic).toBe(true);
+    expect(driftFinding?.detail).toContain("launch-v1");
+
+    // Every finding type from the fixture is present — five distinct types.
+    expect(byType.size).toBe(5);
+
+    // A fresh, healthy vault reports clean.
+    const cleanDb = new Database(":memory:");
+    const cleanStore = new SqliteStore(cleanDb);
+    await cleanStore.upsertTagRecord("healthy", { description: "nothing wrong here" });
+    await cleanStore.createNote("fine", { tags: ["healthy"] });
+    const cleanReport = await cleanStore.doctor();
+    expect(cleanReport.findings).toEqual([]);
+    expect(cleanReport.summary).toContain("clean");
+  });
 });

package/core/src/contract-typed-index.test.ts

@@ -22,6 +22,7 @@ import { Database } from "bun:sqlite";
 import { SqliteStore } from "./store.js";
 import { generateMcpTools } from "./mcp.js";
 import { TransitionConflictError } from "./notes.js";
+import { TagFieldConflictError } from "./tag-schemas.js";
 
 let store: SqliteStore;
 let db: Database;
@@ -97,10 +98,98 @@ describe("contract: typed indexes — todo (#553)", () => {
   test.todo(
     `#553: an unset enum field stays ABSENT — no first-value backfill — so exists:false correctly matches a note that never set the field (today: applySchemaDefaults in core/src/mcp.ts backfills the schema's first enum value onto every note that gains the tag, so "never set" is indistinguishable from "explicitly set to the default" and exists:false never matches)`,
   );
-  test.todo(
-    `#553: update-tag reports ALL invalid fields in one call AND states explicitly that no changes were applied (today: the cross-tag type/indexed-flag validation loop in core/src/mcp.ts throws on the FIRST offending field and never reports the rest, and the thrown Error's message doesn't say whether the tag's other, valid fields were partially applied — reproduced live: declaring two invalid fields in one update-tag call surfaces only the first field's error)`,
-  );
   test.todo(
     `#553: the indexed-field type list is honest about what's actually indexable (core/src/mcp.ts's update-tag field-type description advertises "string, boolean, integer, number, array, object" but indexed-fields.ts's TYPE_MAP only supports string/integer/boolean — "number" and the container types are accepted as declared but silently un-indexable)`,
   );
 });
+
+describe("contract: update-tag messaging — #553/#554 (flipped from todo)", () => {
+  it("update-tag reports ALL invalid fields in one call (not just the first) and states explicitly that no changes were applied", async () => {
+    // Tag "a" declares two fields. Tag "b" then redeclares BOTH with
+    // conflicting specs — a NON-indexed type conflict on "x" AND an
+    // indexed-flag conflict on "y" — in the SAME update-tag call. Pre-#553
+    // the cross-tag validation loop threw on the first offending field
+    // ("x") and never even evaluated "y"; two testers independently assumed
+    // the whole call (including "y") had partially landed. (The
+    // BOTH-indexed type-conflict case is deliberately absent here — it
+    // keeps its pre-existing declareField → IndexedFieldError path; see
+    // `collectCrossTagFieldViolations`'s doc-comment exclusion 2 and the
+    // both-indexed test below.)
+    await store.upsertTagRecord("a", {
+      fields: {
+        x: { type: "string" },
+        y: { type: "boolean", indexed: true },
+      },
+    });
+
+    const tools = generateMcpTools(store);
+    const updateTag = tools.find((t) => t.name === "update-tag")!;
+
+    let caught: unknown;
+    try {
+      await updateTag.execute({
+        tag: "b",
+        fields: {
+          x: { type: "integer" }, // non-indexed type_conflict vs tag "a"
+          y: { type: "boolean", indexed: false }, // indexed_flag_conflict vs tag "a"
+        },
+      });
+    } catch (e) {
+      caught = e;
+    }
+
+    expect(caught).toBeInstanceOf(TagFieldConflictError);
+    const err = caught as TagFieldConflictError;
+    expect(err.violations).toHaveLength(2);
+    const byField = new Map(err.violations.map((v) => [v.field, v.reason]));
+    expect(byField.get("x")).toBe("type_conflict");
+    expect(byField.get("y")).toBe("indexed_flag_conflict");
+    // States explicitly that no changes were applied.
+    expect(err.message).toContain("no changes were applied");
+    // Structured conflicting-declarer field (scrubbed by the server layer
+    // for tag-scoped sessions; full detail here — core is scope-unaware).
+    expect(err.violations[0]!.other_tag).toBe("a");
+
+    // Nothing partially landed — tag "b" has no field declarations at all.
+    const bRecord = await store.getTagRecord("b");
+    expect(bRecord?.fields ?? null).toBeFalsy();
+  });
+
+  it("a BOTH-indexed cross-tag type conflict keeps its pre-existing IndexedFieldError path (not TagFieldConflictError)", async () => {
+    // Wire-contract floor (vault#554): this exact case already errored on
+    // main via store.upsertTagRecord → declareField's cross-declarer
+    // sqlite-type check → IndexedFieldError (REST maps it to 400
+    // invalid_indexed_field). The new pre-check must not intercept it.
+    await store.upsertTagRecord("a", {
+      fields: { x: { type: "string", indexed: true } },
+    });
+
+    const tools = generateMcpTools(store);
+    const updateTag = tools.find((t) => t.name === "update-tag")!;
+
+    let caught: any;
+    try {
+      await updateTag.execute({
+        tag: "b",
+        fields: { x: { type: "integer", indexed: true } },
+      });
+    } catch (e) {
+      caught = e;
+    }
+
+    expect(caught).toBeDefined();
+    expect(caught).not.toBeInstanceOf(TagFieldConflictError);
+    expect(caught.name).toBe("IndexedFieldError");
+    expect(caught.error_type).toBe("invalid_indexed_field");
+    // The structured declarer context the server's tag-scope scrub keys on.
+    expect(caught.field).toBe("x");
+    expect(caught.declarer_tags).toEqual(["a"]);
+
+    // The store's transaction rolled back — nothing persisted for "b".
+    const bRecord = await store.getTagRecord("b");
+    expect(bRecord?.fields ?? null).toBeFalsy();
+  });
+  // REST `PUT /api/tags/:name` coverage for the same behavior lives in
+  // src/contract-errors.test.ts (core/ shouldn't import from src/ — that
+  // boundary runs one direction only).
+});

package/core/src/core.test.ts

@@ -2030,6 +2030,12 @@ describe("MCP tools", async () => {
     // prune-schema (admin) — drops orphaned indexed-field columns whose
     // declaring tags are gone. The gitcoin orphaned-fields fix.
     expect(names).toContain("prune-schema");
+    // rename-tag / merge-tags (vault#552) — MCP parity with the
+    // pre-existing REST rename/merge engine. doctor (admin, vault#552) —
+    // read-only taxonomy/metadata integrity scan.
+    expect(names).toContain("rename-tag");
+    expect(names).toContain("merge-tags");
+    expect(names).toContain("doctor");
     // Six note-schema tools (list/update/delete-note-schema +
     // list/set/delete-schema-mapping) retired in v17 — the standalone
     // note_schemas + schema_mappings subsystem was a parallel path to
@@ -2043,7 +2049,7 @@ describe("MCP tools", async () => {
     // synthesize-notes retired in v17 — replicable with query-notes(near=) +
     // find-path + agent-side aggregation. See vault#268.
     expect(names).not.toContain("synthesize-notes");
-    expect(tools).toHaveLength(10);
+    expect(tools).toHaveLength(13);
   });
 
   it("create-note tool works", async () => {
@@ -4170,7 +4176,17 @@ describe("tag hierarchy (tags.parent_names)", async () => {
 
   it("tolerates a cycle without infinite-looping", async () => {
     await store.upsertTagRecord("a", { parent_names: ["b"] });
-    await store.upsertTagRecord("b", { parent_names: ["a"] });
+    await store.upsertTagRecord("b", {}); // bare row, no parent yet
+    // vault#552: upsertTagRecord now REJECTS a parent_names write that would
+    // close a cycle, so the second leg of the cycle can no longer be built
+    // via the public API — simulate pre-existing cyclic data (written
+    // before the guard shipped, or via any path that bypasses it) with a
+    // direct DB write, same technique as "malformed parent_names JSON is
+    // ignored silently" below. Traversal must stay cycle-safe regardless of
+    // how the cycle got there.
+    (store as any).db.prepare("UPDATE tags SET parent_names = ? WHERE name = ?")
+      .run(JSON.stringify(["a"]), "b");
+    (store as any)._tagHierarchy = null;
     await store.createNote("note-a", { tags: ["a"] });
 
     // Both a and b should resolve without hanging; both reach the same set {a, b}.
@@ -4803,14 +4819,21 @@ describe("schema inheritance via parent_names (vault#270)", async () => {
   });
 
   it("cycle: A→B, B→A — no infinite loop, both fields visible", async () => {
+    await store.upsertTagRecord("B", {
+      fields: { b_field: { type: "string" } },
+    });
     await store.upsertTagRecord("A", {
       parent_names: ["B"],
       fields: { a_field: { type: "string" } },
     });
-    await store.upsertTagRecord("B", {
-      parent_names: ["A"],
-      fields: { b_field: { type: "string" } },
-    });
+    // vault#552: upsertTagRecord now REJECTS the write that would close this
+    // cycle (B declaring A as parent, when A already declares B) — simulate
+    // pre-existing cyclic data with a direct DB write, same technique as the
+    // "tolerates a cycle without infinite-looping" test above.
+    (store as any).db.prepare("UPDATE tags SET parent_names = ? WHERE name = ?")
+      .run(JSON.stringify(["A"]), "B");
+    (store as any)._tagHierarchy = null;
+    (store as any)._schemaConfig = null;
 
     const tools = generateMcpTools(store);
     const create = tools.find((t) => t.name === "create-note")!;

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

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