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

package/src/routes.ts

@@ -42,10 +42,13 @@ import {
   filterNotesByTagScope,
   noteWithinTagScope,
   scrubIndexedFieldConflictError,
+  scrubParentCycleError,
+  scrubReferencingTagsByScope,
   scrubTagFieldViolationsByScope,
   tagScopeForbidden,
   tagsWithinScope,
 } from "./tag-scope.ts";
+import { ParentCycleError } from "../core/src/tag-schemas.ts";
 import { findTokensReferencingTag } from "./token-store.ts";
 
 /**
@@ -2665,6 +2668,29 @@ export async function handleTags(
           400,
         );
       }
+      if (err instanceof ParentCycleError) {
+        // vault#552: parent_names would close a cycle. Nothing was
+        // persisted. Scope-scrub the cycle path for a tag-scoped caller —
+        // the write stays rejected either way. `error` is a SHORT code and
+        // `message` the human sentence — the same split every sibling 409 in
+        // this file uses (target_exists, tag_in_use_by_tokens,
+        // tag_referenced_as_parent). parachute-surface's shared VaultClient
+        // 409 handler reads `body.message` (falling back to a hardcoded
+        // "Note was edited elsewhere"), so the message key is load-bearing:
+        // without it the Tags parent_names editor would show the wrong
+        // conflict text.
+        const scrubbed = scrubParentCycleError(err, tagScope.allowed);
+        return json(
+          {
+            error: "ParentCycle",
+            error_type: "parent_cycle",
+            tag: scrubbed.tag,
+            cycle: scrubbed.cycle,
+            message: scrubbed.message,
+          },
+          409,
+        );
+      }
       throw err;
     }
     return json(result);
@@ -2692,7 +2718,33 @@ export async function handleTags(
         409,
       );
     }
-    return json(await store.deleteTag(tagName));
+    // `?cascade=true` / `?detach=true` (synonyms — see DeleteTagOpts):
+    // required to delete a tag another tag's parent_names still references
+    // (vault#552). Query params, not a DELETE body, so the flag is visible
+    // in access logs and works with any HTTP client without body support.
+    const cascade = parseBool(parseQuery(url, "cascade"), false);
+    const detach = parseBool(parseQuery(url, "detach"), false);
+    const result = await store.deleteTag(tagName, { cascade, detach });
+    if ("error" in result) {
+      // Referential-integrity refusal (vault#552). Scope-scrub the
+      // referencing tag names for a tag-scoped caller — the delete is
+      // still refused (integrity is scope-independent), but an
+      // out-of-scope referrer's name must not leak. Same posture as
+      // `tag_field_conflict`'s scrub.
+      const referencing_tags = scrubReferencingTagsByScope(result.referencing_tags, tagScope.allowed);
+      return json(
+        {
+          error: "TagReferencedAsParent",
+          error_type: "tag_referenced_as_parent",
+          tag: tagName,
+          referencing_tags,
+          message: `Tag "${tagName}" is referenced by ${referencing_tags.length} other tag(s)' parent_names; pass ?cascade=true or ?detach=true to also remove the reference, or update the referencing tag(s) first.`,
+          hint: "pass ?cascade=true or ?detach=true, or fix the referencing tag(s)' parent_names first",
+        },
+        409,
+      );
+    }
+    return json(result);
   }
 
   return json({ error: "Method not allowed", error_type: "method_not_allowed" }, 405);
@@ -2924,6 +2976,27 @@ export function handleUnresolvedWikilinks(
   return Response.json({ unresolved: filtered, count: filtered.length });
 }
 
+// ---------------------------------------------------------------------------
+// Doctor — GET /api/doctor (vault#552, admin-gated in routing.ts)
+// ---------------------------------------------------------------------------
+
+/**
+ * `GET /vault/{name}/api/doctor` — read-only taxonomy/metadata integrity
+ * scan. Method + `vault:admin` scope are already enforced by the caller
+ * (`src/routing.ts`, dispatched before the generic read/write gate — same
+ * shape as `/api/triggers`); this handler just runs the scan with the
+ * caller's tag-scope allowlist. See `core/src/doctor.ts` for the finding
+ * catalog.
+ */
+export async function handleDoctor(
+  _req: Request,
+  store: Store,
+  tagScope: TagScopeCtx = NO_TAG_SCOPE,
+): Promise<Response> {
+  const report = await store.doctor({ allowedTags: tagScope.allowed });
+  return json(report);
+}
+
 // ---------------------------------------------------------------------------
 // Published notes — public, no-auth HTML rendering
 // ---------------------------------------------------------------------------

package/src/routing.ts

@@ -70,6 +70,7 @@ import {
   handleUnresolvedWikilinks,
   handleStorage,
   handleViewNote,
+  handleDoctor,
   type TagScopeCtx,
   type WriteCtx,
 } from "./routes.ts";
@@ -825,6 +826,34 @@ export async function route(
     }
   }
 
+  // /api/doctor — read-only taxonomy/metadata integrity scan (vault#552).
+  // Same "dispatch before the generic read/write gate" shape as /triggers
+  // above, because this is ADMIN-tier regardless of method (GET-only, but
+  // admin — not read — since it's a whole-vault diagnostic, same tier as
+  // the MCP `doctor` tool and `prune-schema`).
+  if (apiMatch[1] === "/doctor") {
+    if (req.method !== "GET") {
+      return Response.json({ error: "Method not allowed", error_type: "method_not_allowed" }, { status: 405 });
+    }
+    if (!hasScopeForVault(auth.scopes, vaultName, "admin")) {
+      return Response.json(
+        {
+          error: "Forbidden",
+          error_type: "insufficient_scope",
+          message: `This endpoint requires the '${SCOPE_ADMIN}' scope (or '${SCOPE_ADMIN.replace("vault:", `vault:${vaultName}:`)}').`,
+          required_scope: SCOPE_ADMIN,
+          granted_scopes: auth.scopes,
+        },
+        { status: 403 },
+      );
+    }
+    const doctorTagScope: TagScopeCtx = {
+      allowed: await expandTokenTagScope(store, auth.scoped_tags),
+      raw: auth.scoped_tags,
+    };
+    return handleDoctor(req, store, doctorTagScope);
+  }
+
   // REST API — scope gate. GET/HEAD/OPTIONS → vault:read,
   // POST/PATCH/PUT/DELETE → vault:write. Inheritance (admin ⊇ write ⊇ read)
   // and the broad-vs-narrowed shape (`vault:<verb>` from pvt_*, or

package/src/tag-integrity-mcp.test.ts

@@ -0,0 +1,288 @@
+/**
+ * End-to-end coverage for the vault#552 MCP + REST surface: rename-tag and
+ * merge-tags tool wiring (verb + tag-scope gating), delete-tag's
+ * cascade/detach flags flowing through the MCP wrapper, and the `doctor`
+ * tool/endpoint's admin-gate + tag-scope filtering. Fixture pattern mirrors
+ * tag-field-conflict-scope.test.ts (PARACHUTE_HOME temp home + hand-built
+ * AuthResult).
+ */
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { mkdirSync, rmSync, existsSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { writeVaultConfig } from "./config.ts";
+import { getVaultStore, clearVaultStoreCache } from "./vault-store.ts";
+import { generateScopedMcpTools } from "./mcp-tools.ts";
+import { handleTags, handleDoctor, type TagScopeCtx } from "./routes.ts";
+import type { AuthResult } from "./auth.ts";
+
+let tmpHome: string;
+let prevHome: string | undefined;
+
+beforeEach(() => {
+  tmpHome = join(tmpdir(), `vault-tag-integrity-mcp-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+  mkdirSync(join(tmpHome, "vault", "data"), { recursive: true });
+  prevHome = process.env.PARACHUTE_HOME;
+  process.env.PARACHUTE_HOME = tmpHome;
+  clearVaultStoreCache();
+});
+
+afterEach(() => {
+  clearVaultStoreCache();
+  if (prevHome === undefined) delete process.env.PARACHUTE_HOME;
+  else process.env.PARACHUTE_HOME = prevHome;
+  if (existsSync(tmpHome)) rmSync(tmpHome, { recursive: true, force: true });
+});
+
+function seedVault(name: string): void {
+  writeVaultConfig({ name, api_keys: [], created_at: new Date().toISOString() });
+  getVaultStore(name);
+}
+
+function authFor(vaultName: string, scopedTags: string[] | null, verb: "read" | "write" | "admin" = "write"): AuthResult {
+  const verbs = verb === "admin" ? ["read", "write", "admin"] : verb === "write" ? ["read", "write"] : ["read"];
+  return {
+    permission: "full",
+    scopes: verbs.map((v) => `vault:${vaultName}:${v}`),
+    legacyDerived: false,
+    scoped_tags: scopedTags,
+    vault_name: null,
+    caller_jti: null,
+    actor: "test-user",
+    via: "api",
+  };
+}
+
+async function toolsFor(vaultName: string, scopedTags: string[] | null, verb: "read" | "write" | "admin" = "write") {
+  return generateScopedMcpTools(vaultName, authFor(vaultName, scopedTags, verb));
+}
+
+describe("rename-tag / merge-tags — tag-scope gating (vault#552)", () => {
+  test("rename-tag: old_name or new_name outside the allowlist is refused before reaching core", async () => {
+    seedVault("journal");
+    const store = getVaultStore("journal");
+    await store.upsertTagRecord("mine", {});
+    await store.upsertTagRecord("theirs", {});
+
+    const tools = await toolsFor("journal", ["mine"]);
+    const renameTag = tools.find((t) => t.name === "rename-tag")!;
+
+    const result = await renameTag.execute({ old_name: "theirs", new_name: "mine2" }) as any;
+    expect(result.error_type).toBe("tag_scope_violation");
+
+    // Untouched.
+    expect(await store.getTagRecord("theirs")).not.toBeNull();
+  });
+
+  test("rename-tag: both names in-scope reaches core (wrapper doesn't spuriously block), which reports target_exists for an already-live target", async () => {
+    seedVault("journal");
+    const store = getVaultStore("journal");
+    await store.upsertTagRecord("mine", {});
+    await store.upsertTagRecord("mine-other", {});
+
+    // Both names are directly scoped (each tag is trivially a member of its
+    // own descendant set), so the wrapper's scope check passes and the call
+    // reaches core — which correctly refuses because "mine-other" already
+    // exists (rename never silently overwrites; that's what merge-tags is
+    // for). Proves the wrapper isn't the thing blocking this, core is.
+    const tools = await toolsFor("journal", ["mine", "mine-other"]);
+    const renameTag = tools.find((t) => t.name === "rename-tag")!;
+    let caught: any;
+    try {
+      await renameTag.execute({ old_name: "mine", new_name: "mine-other" });
+    } catch (e) { caught = e; }
+    expect(caught?.error_type).toBe("target_exists");
+  });
+
+  test("merge-tags: a source outside the allowlist is refused before reaching core", async () => {
+    seedVault("journal");
+    const store = getVaultStore("journal");
+    await store.upsertTagRecord("mine", {});
+    await store.upsertTagRecord("theirs", {});
+
+    const tools = await toolsFor("journal", ["mine"]);
+    const mergeTags = tools.find((t) => t.name === "merge-tags")!;
+    const result = await mergeTags.execute({ sources: ["theirs"], target: "mine" }) as any;
+    expect(result.error_type).toBe("tag_scope_violation");
+    expect(await store.getTagRecord("theirs")).not.toBeNull();
+  });
+
+  test("merge-tags: a source referenced by a tag-scoped token is refused (409-equivalent), independent of the CALLER's own scope", async () => {
+    seedVault("journal");
+    const store = getVaultStore("journal");
+    await store.upsertTagRecord("mine", {});
+    await store.upsertTagRecord("locked", {});
+    // A DIFFERENT (vestigial) tag-scoped token row references "locked" —
+    // merging it away would orphan that token's allowlist. Raw INSERT, same
+    // fixture pattern as vault.test.ts's "MCP delete-tag returns
+    // tag_in_use_by_tokens..." — vault no longer mints these post-0.5.0, but
+    // findTokensReferencingTag still guards against leftover rows.
+    store.db
+      .prepare(
+        "INSERT INTO tokens (token_hash, label, permission, scoped_tags, created_at) VALUES (?, ?, ?, ?, ?)",
+      )
+      .run(
+        `sha256:locked-claw-${Math.random().toString(36).slice(2)}`,
+        "locked-claw",
+        "read",
+        JSON.stringify(["locked"]),
+        new Date().toISOString(),
+      );
+
+    const tools = await toolsFor("journal", null); // unscoped caller — still blocked by the token-reference guard
+    const mergeTags = tools.find((t) => t.name === "merge-tags")!;
+    const result = await mergeTags.execute({ sources: ["locked"], target: "mine" }) as any;
+    expect(result.error_type).toBe("tag_in_use_by_tokens");
+    expect(await store.getTagRecord("locked")).not.toBeNull();
+  });
+});
+
+describe("delete-tag cascade/detach — MCP wrapper pass-through (vault#552)", () => {
+  test("cascade:true flows through the tag-scope wrapper to the underlying store call", async () => {
+    seedVault("journal");
+    const store = getVaultStore("journal");
+    await store.upsertTagRecord("mine", { description: "root" });
+    await store.upsertTagRecord("mine-child", { parent_names: ["mine"] });
+
+    const tools = await toolsFor("journal", ["mine"]); // "mine-child" is a descendant, also in-scope
+    const deleteTag = tools.find((t) => t.name === "delete-tag")!;
+
+    const refused = await deleteTag.execute({ tag: "mine" }) as any;
+    expect(refused.error).toBe("tag_referenced_as_parent");
+
+    const cascaded = await deleteTag.execute({ tag: "mine", cascade: true }) as any;
+    expect(cascaded.deleted).toBe(true);
+    expect(await store.getTagRecord("mine")).toBeNull();
+  });
+});
+
+describe("doctor — admin gate + tag-scope filtering (vault#552)", () => {
+  test("MCP: doctor is invisible in tools/list to a write-only (non-admin) session, and excluded-tool-called-explicitly still refuses it", async () => {
+    // `generateScopedMcpTools` (the `toolsFor` helper) always returns the
+    // FULL tool set — the `requiredVerb` visibility filter lives one layer
+    // up, in `handleScopedMcp`'s tools/list dispatch (mcp-http.ts). Drive
+    // through that layer, same pattern as vault.test.ts's `listToolNames`.
+    seedVault("journal");
+    const { handleScopedMcp } = await import("./mcp-http.ts");
+    const listReq = new Request("http://localhost:1940/vault/journal/mcp", {
+      method: "POST",
+      headers: { "content-type": "application/json", accept: "application/json, text/event-stream" },
+      body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/list", params: {} }),
+    });
+    const listRes = await handleScopedMcp(listReq, "journal", authFor("journal", null, "write"));
+    const listBody = await listRes.json() as any;
+    const names: string[] = listBody.result.tools.map((t: any) => t.name);
+    expect(names).not.toContain("doctor");
+
+    // Explicitly calling it anyway is refused, not silently executed.
+    const callReq = new Request("http://localhost:1940/vault/journal/mcp", {
+      method: "POST",
+      headers: { "content-type": "application/json", accept: "application/json, text/event-stream" },
+      body: JSON.stringify({ jsonrpc: "2.0", id: 2, method: "tools/call", params: { name: "doctor", arguments: {} } }),
+    });
+    const callRes = await handleScopedMcp(callReq, "journal", authFor("journal", null, "write"));
+    const callBody = await callRes.json() as any;
+    expect(callBody.result?.isError).toBe(true);
+  });
+
+  test("MCP: doctor is visible + callable for an admin session, and a scoped admin session only reports in-scope findings", async () => {
+    seedVault("journal");
+    const store = getVaultStore("journal");
+    // In-scope dangling parent_names.
+    await store.upsertTagRecord("mine-broken", { parent_names: ["mine-ghost-parent"] });
+    // Out-of-scope dangling parent_names — must not appear in a scoped report.
+    await store.upsertTagRecord("theirs-broken", { parent_names: ["theirs-ghost-parent"] });
+
+    const unscopedTools = await toolsFor("journal", null, "admin");
+    const unscopedDoctor = unscopedTools.find((t) => t.name === "doctor")!;
+    const unscopedReport = await unscopedDoctor.execute({}) as any;
+    const unscopedSubjects = unscopedReport.findings.map((f: any) => f.subject);
+    expect(unscopedSubjects).toContain("mine-broken");
+    expect(unscopedSubjects).toContain("theirs-broken");
+
+    const scopedTools = await toolsFor("journal", ["mine-broken"], "admin");
+    const scopedDoctor = scopedTools.find((t) => t.name === "doctor")!;
+    const scopedReport = await scopedDoctor.execute({}) as any;
+    const scopedSubjects = scopedReport.findings.map((f: any) => f.subject);
+    expect(scopedSubjects).toContain("mine-broken");
+    expect(scopedSubjects).not.toContain("theirs-broken");
+  });
+
+  test("REST: GET /api/doctor reports findings filtered to the tag-scoped caller's allowlist", async () => {
+    seedVault("journal");
+    const store = getVaultStore("journal");
+    await store.upsertTagRecord("mine-broken", { parent_names: ["mine-ghost-parent"] });
+    await store.upsertTagRecord("theirs-broken", { parent_names: ["theirs-ghost-parent"] });
+
+    const tagScope: TagScopeCtx = { allowed: new Set(["mine-broken"]), raw: ["mine-broken"] };
+    const res = await handleDoctor(new Request("http://localhost/api/doctor"), store, tagScope);
+    expect(res.status).toBe(200);
+    const body: any = await res.json();
+    const subjects = body.findings.map((f: any) => f.subject);
+    expect(subjects).toContain("mine-broken");
+    expect(subjects).not.toContain("theirs-broken");
+  });
+});
+
+describe("parent_cycle — REST PUT /api/tags/:name surfaces the 409 (vault#552)", () => {
+  test("A→B then B→A is rejected with error_type parent_cycle, naming the cycle", async () => {
+    seedVault("journal");
+    const store = getVaultStore("journal");
+    await store.upsertTagRecord("b", {});
+    await store.upsertTagRecord("a", { parent_names: ["b"] });
+
+    const req = new Request("http://localhost/api/tags/b", {
+      method: "PUT",
+      body: JSON.stringify({ parent_names: ["a"] }),
+    });
+    const res = await handleTags(req, store, "/b");
+    expect(res.status).toBe(409);
+    const body: any = await res.json();
+    expect(body.error_type).toBe("parent_cycle");
+    expect(body.tag).toBe("b");
+    expect(body.cycle).toContain("a");
+    expect(body.cycle).toContain("b");
+    // MUST-FIX 5 (wire review): a `message` key is load-bearing — the shared
+    // parachute-surface VaultClient 409 handler reads `body.message` (else it
+    // shows a hardcoded "Note was edited elsewhere"). `error` is the short
+    // code, `message` the human sentence — same split every sibling 409 uses.
+    expect(typeof body.message).toBe("string");
+    expect(body.message.length).toBeGreaterThan(0);
+    expect(body.message).toMatch(/cycle/i);
+    expect(body.error).toBe("ParentCycle");
+    expect(body.error).not.toContain(" "); // short code, not the full sentence
+
+    // Nothing persisted.
+    expect((await store.getTagRecord("b"))?.parent_names ?? null).toBeFalsy();
+  });
+});
+
+describe("tag_referenced_as_parent — REST DELETE /api/tags/:name surfaces the 409 + flags (vault#552)", () => {
+  test("refused by default, cascade query param proceeds", async () => {
+    seedVault("journal");
+    const store = getVaultStore("journal");
+    await store.upsertTagRecord("root", {});
+    await store.upsertTagRecord("child", { parent_names: ["root"] });
+
+    const refusedRes = await handleTags(new Request("http://localhost/api/tags/root", { method: "DELETE" }), store, "/root");
+    expect(refusedRes.status).toBe(409);
+    const refusedBody: any = await refusedRes.json();
+    expect(refusedBody.error_type).toBe("tag_referenced_as_parent");
+    expect(refusedBody.referencing_tags).toEqual(["child"]);
+    // Same short-code-`error` + human-`message` split as every sibling 409
+    // (wire consistency — parachute-surface reads `body.message`).
+    expect(refusedBody.error).toBe("TagReferencedAsParent");
+    expect(typeof refusedBody.message).toBe("string");
+    expect(refusedBody.message.length).toBeGreaterThan(0);
+
+    const cascadedRes = await handleTags(
+      new Request("http://localhost/api/tags/root?cascade=true", { method: "DELETE" }),
+      store,
+      "/root",
+    );
+    expect(cascadedRes.status).toBe(200);
+    const cascadedBody: any = await cascadedRes.json();
+    expect(cascadedBody.deleted).toBe(true);
+    expect(cascadedBody.parent_refs_detached).toBe(1);
+  });
+});

package/src/tag-integrity-scope.test.ts

@@ -0,0 +1,97 @@
+/**
+ * Tag-scope scrub on the two vault#552 taxonomy-integrity guards:
+ * `tag_referenced_as_parent` (delete-tag's referential-integrity refusal)
+ * and `parent_cycle` (upsertTagRecord's write-time cycle guard). Same "in
+ * doubt, scrub" posture as `tag_field_conflict` (see
+ * tag-field-conflict-scope.test.ts) — the write stays rejected regardless
+ * of scope, but an out-of-scope tag name must never appear in the response.
+ *
+ * Reachability note: for BOTH guards, the offending tag(s) the scrub would
+ * redact are, by construction, always descendants of the tag the caller is
+ * already scoped to (deleteTag's `referencing_tags` are children of the
+ * doomed tag; `findParentCycle`'s conflicting parent + path are members of
+ * `getTagDescendants(hierarchy, tag)`, the SAME computation
+ * `expandTokenTagScope` uses to build the caller's allowlist for that same
+ * `tag`). So under the CURRENT hierarchy-based tag-scope model, a live
+ * end-to-end request can't actually construct an out-of-scope referrer —
+ * the scrub is defense-in-depth for a future change to either guard (e.g. if
+ * `deleteTag`'s search ever widens past direct parent_names children). These
+ * tests exercise the scrub functions directly against a synthetic
+ * out-of-scope input to pin the CONTRACT ("an out-of-scope name never
+ * survives"), independent of today's reachability.
+ */
+import { describe, test, expect } from "bun:test";
+import { scrubReferencingTagsByScope, scrubParentCycleError } from "./tag-scope.ts";
+import { ParentCycleError } from "../core/src/tag-schemas.ts";
+
+describe("scrubReferencingTagsByScope (vault#552)", () => {
+  test("unscoped caller (allowed === null): passthrough, no redaction", () => {
+    const result = scrubReferencingTagsByScope(["child-a", "secret-child"], null);
+    expect(result).toEqual(["child-a", "secret-child"]);
+  });
+
+  test("scoped caller: in-scope names kept, out-of-scope names redacted to a generic label — never the real name", () => {
+    const allowed = new Set(["child-a"]);
+    const result = scrubReferencingTagsByScope(["child-a", "secret-child"], allowed);
+    expect(result[0]).toBe("child-a");
+    expect(result[1]).not.toBe("secret-child");
+    expect(result.join(" ")).not.toContain("secret-child");
+    expect(result[1]).toContain("outside your token's tag scope");
+  });
+
+  test("every referencing tag out of scope: every entry redacted, count preserved", () => {
+    const allowed = new Set<string>(["unrelated"]);
+    const result = scrubReferencingTagsByScope(["secret-1", "secret-2"], allowed);
+    expect(result).toHaveLength(2);
+    for (const r of result) {
+      expect(r).not.toBe("secret-1");
+      expect(r).not.toBe("secret-2");
+    }
+  });
+
+  test("empty referencing list stays empty", () => {
+    expect(scrubReferencingTagsByScope([], new Set())).toEqual([]);
+  });
+});
+
+describe("scrubParentCycleError (vault#552)", () => {
+  test("unscoped caller (allowed === null): passthrough, same instance semantics (message/tag/cycle unchanged)", () => {
+    const err = new ParentCycleError("mine", ["mine", "secret-hop", "mine"]);
+    const scrubbed = scrubParentCycleError(err, null);
+    expect(scrubbed).toBe(err);
+  });
+
+  test("every hop in scope: passthrough, original error returned untouched", () => {
+    const err = new ParentCycleError("mine", ["mine", "child", "mine"]);
+    const allowed = new Set(["mine", "child"]);
+    const scrubbed = scrubParentCycleError(err, allowed);
+    expect(scrubbed).toBe(err);
+    expect(scrubbed.cycle).toEqual(["mine", "child", "mine"]);
+  });
+
+  test("an out-of-scope hop is generalized: the caller's own tag stays named, the out-of-scope hop does not, and the write is still reported rejected", () => {
+    const err = new ParentCycleError("mine", ["mine", "secret-hop", "mine"]);
+    const allowed = new Set(["mine"]); // "secret-hop" deliberately excluded
+    const scrubbed = scrubParentCycleError(err, allowed);
+
+    expect(scrubbed).not.toBe(err); // a REPLACEMENT error, not the original
+    expect(scrubbed.error_type).toBe("parent_cycle");
+    expect(scrubbed.tag).toBe("mine"); // the caller's own tag — always in-scope, never redacted
+    expect(scrubbed.cycle[0]).toBe("mine");
+    expect(scrubbed.cycle[2]).toBe("mine");
+    expect(scrubbed.cycle[1]).not.toBe("secret-hop");
+    expect(scrubbed.cycle.join(" ")).not.toContain("secret-hop");
+    expect(scrubbed.message).not.toContain("secret-hop");
+    expect(scrubbed.message).toContain("cycle");
+  });
+
+  test("multiple out-of-scope hops in a longer chain are each redacted independently", () => {
+    const err = new ParentCycleError("mine", ["mine", "secret-1", "secret-2", "mine"]);
+    const allowed = new Set(["mine"]);
+    const scrubbed = scrubParentCycleError(err, allowed);
+    expect(scrubbed.cycle[1]).not.toBe("secret-1");
+    expect(scrubbed.cycle[2]).not.toBe("secret-2");
+    expect(scrubbed.cycle.join(" ")).not.toContain("secret-1");
+    expect(scrubbed.cycle.join(" ")).not.toContain("secret-2");
+  });
+});

package/src/tag-scope.ts

@@ -21,8 +21,12 @@
 
 import type { Store, Note, HydratedLink, NoteSummary } from "../core/src/types.ts";
 import type { TagFieldViolation } from "../core/src/tag-schemas.ts";
+import { ParentCycleError } from "../core/src/tag-schemas.ts";
 import { IndexedFieldError } from "../core/src/indexed-fields.ts";
 
+/** Generic replacement for a redacted out-of-scope tag name — never the real name. */
+const OUT_OF_SCOPE_LABEL = "(outside your token's tag scope)";
+
 /**
  * Build the effective tag-allowlist for a token: union of `{root} ∪
  * descendants(root)` for each root in `scoped_tags`. Returns null when the
@@ -233,6 +237,45 @@ export function scrubIndexedFieldConflictError(
   );
 }
 
+/**
+ * Scrub the `referencing_tags` list on a `tag_referenced_as_parent` refusal
+ * (vault#552 — deleteTag's referential-integrity guard) for a tag-scoped
+ * caller. The delete is refused regardless of scope (referential integrity
+ * is scope-independent, same posture as `tag_field_conflict`), but a
+ * referencing tag OUTSIDE the caller's allowlist must not be named — same
+ * "in doubt, scrub" convention `scrubTagFieldViolationsByScope` uses.
+ * No-op for unscoped callers (`allowed === null`).
+ */
+export function scrubReferencingTagsByScope(
+  referencing: string[],
+  allowed: Set<string> | null,
+): string[] {
+  if (allowed === null) return referencing;
+  return referencing.map((t) => (allowed.has(t) ? t : OUT_OF_SCOPE_LABEL));
+}
+
+/**
+ * Scrub a `ParentCycleError`'s `cycle` path (vault#552 — the `parent_names`
+ * cycle guard) for a tag-scoped caller. The write is still rejected — a
+ * cycle is a structural problem independent of who's asking — but the
+ * cycle path can walk through tags OUTSIDE the caller's allowlist (the
+ * hierarchy `upsertTagRecord` validates against is vault-wide, scope-unaware
+ * by architecture, same as the cross-tag field checks). Returns a
+ * REPLACEMENT error with out-of-scope hops in `cycle` generalized; the
+ * caller's own tag (`err.tag`) is always in-scope by the time this runs (the
+ * update-tag wrapper already gates on it) so it's never redacted. No-op for
+ * unscoped callers or a cycle with no out-of-scope hop.
+ */
+export function scrubParentCycleError(
+  err: ParentCycleError,
+  allowed: Set<string> | null,
+): ParentCycleError {
+  if (allowed === null) return err;
+  if (err.cycle.every((t) => allowed.has(t))) return err;
+  const scrubbedCycle = err.cycle.map((t) => (allowed.has(t) ? t : OUT_OF_SCOPE_LABEL));
+  return new ParentCycleError(err.tag, scrubbedCycle);
+}
+
 /**
  * Standard 403 response shape for tag-scope rejections. Mirrors the
  * `insufficient_scope` 403 shape used elsewhere in the API so clients