@openparachute/vault 0.7.0-rc.3 → 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

@@ -16,6 +16,8 @@
  */
 
 import { Database } from "bun:sqlite";
+import { mapFieldType, validateFieldName } from "./indexed-fields.js";
+import { loadTagHierarchy, findParentCycle } from "./tag-hierarchy.js";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -131,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,
@@ -146,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 (?, ?, ?)",
@@ -280,17 +326,23 @@ export function deleteTagSchema(db: Database, tag: string): boolean {
  * time"); dropping the inner-shape gate is consistent with that intent.
  */
 export function validateRelationships(raw: unknown): Record<string, unknown> {
+  // `error_type` (vault#554) is attached directly on the thrown Error
+  // (duck-typed extra property, same pattern as QueryError's optional
+  // fields) rather than via a dedicated class — this is a validation
+  // leaf with one caller-facing shape, not a reusable domain error. Both
+  // REST (src/routes.ts, which already hardcodes this same string) and the
+  // generic MCP domain-error mapping (src/mcp-http.ts) key off it.
   if (raw === null || raw === undefined) {
-    throw new Error("relationships: expected an object, got null/undefined");
+    throw relationshipsError("relationships: expected an object, got null/undefined");
   }
   if (typeof raw !== "object" || Array.isArray(raw)) {
-    throw new Error(
+    throw relationshipsError(
       "relationships: expected an object mapping relationship name → value (got an array or primitive)",
     );
   }
   for (const rel of Object.keys(raw as Record<string, unknown>)) {
     if (!rel) {
-      throw new Error("relationships: keys must be non-empty strings");
+      throw relationshipsError("relationships: keys must be non-empty strings");
     }
   }
   // Round-trip through JSON to (a) confirm the payload is serializable —
@@ -300,11 +352,15 @@ export function validateRelationships(raw: unknown): Record<string, unknown> {
   try {
     serialized = JSON.stringify(raw);
   } catch (err) {
-    throw new Error(`relationships: value must be JSON-serializable (${(err as Error).message})`);
+    throw relationshipsError(`relationships: value must be JSON-serializable (${(err as Error).message})`);
   }
   return JSON.parse(serialized) as Record<string, unknown>;
 }
 
+function relationshipsError(message: string): Error {
+  return Object.assign(new Error(message), { error_type: "invalid_relationships" as const });
+}
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -334,3 +390,174 @@ function jsonOrNull(value: unknown): string | null {
   }
   return JSON.stringify(value);
 }
+
+// ---------------------------------------------------------------------------
+// Cross-tag field validation (vault#553 / #554) — update-tag messaging
+// ---------------------------------------------------------------------------
+
+/**
+ * A single field-declaration violation surfaced by {@link collectTagFieldViolations}.
+ * `reason` is a stable machine-checkable slug; `message` is the existing
+ * human-readable prose (unchanged wording, just no longer thrown on the
+ * first hit).
+ */
+export interface TagFieldViolation {
+  field: string;
+  reason: "type_conflict" | "indexed_flag_conflict" | "unsupported_indexed_type" | "invalid_field_name";
+  message: string;
+  /**
+   * The conflicting declarer tag — present on the cross-tag reasons
+   * (`type_conflict` / `indexed_flag_conflict`) only; the solo own-field
+   * reasons have no other party. Core populates it unconditionally
+   * (scope-unaware by architecture); the SERVER layers scrub it — and
+   * generalize `message` — when the declarer is outside a tag-scoped
+   * caller's allowlist (`scrubTagFieldViolationsByScope` in
+   * src/tag-scope.ts), so a scoped session learns THAT a conflict exists
+   * (the write is still rejected — integrity is scope-independent) but not
+   * WHICH out-of-scope tag it conflicts with or what that tag declares.
+   */
+  other_tag?: string;
+}
+
+/**
+ * Thrown by `update-tag` (MCP tool + REST `PUT /api/tags/:name`) when one or
+ * more fields in the incoming `fields` payload conflict with another tag's
+ * declaration, or declare an unindexable/invalid indexed field. Carries
+ * EVERY violation found in the call (vault#553 settled complaint: the prior
+ * behavior threw on the FIRST offending field and silently never reported
+ * the rest — two testers independently assumed the other fields had landed).
+ * The message states explicitly that no changes were applied — the whole
+ * `upsertTagRecord` call is validated BEFORE any write, so a rejection here
+ * always leaves the tag record untouched (atomicity unchanged from before;
+ * this only improves what the caller is told).
+ */
+export class TagFieldConflictError extends Error {
+  code = "TAG_FIELD_CONFLICT" as const;
+  error_type = "tag_field_conflict" as const;
+  tag: string;
+  violations: TagFieldViolation[];
+
+  constructor(tag: string, violations: TagFieldViolation[]) {
+    const summary = violations.map((v) => `${v.field} (${v.reason}): ${v.message}`).join("; ");
+    super(
+      `tag_field_conflict: ${violations.length} field violation(s) for tag "${tag}" — no changes were applied. ${summary}`,
+    );
+    this.name = "TagFieldConflictError";
+    this.tag = tag;
+    this.violations = violations;
+  }
+}
+
+/**
+ * Validate the fields a caller is declaring/redeclaring for `tag` against
+ * every OTHER tag's schema — `type` and `indexed` must agree across all
+ * declarers (both are global per field). Returns every violation found —
+ * never throws — so the caller can report the complete set in one
+ * structured error (or none, when the array is empty).
+ *
+ * `incomingFields` is the set of fields THIS call is declaring (MCP:
+ * `params.fields`; REST: `body.fields`) — not the full merged field map.
+ * Fields the call doesn't touch were already valid (or already accepted)
+ * and are not re-validated here, matching the pre-#553 scope of the check.
+ *
+ * Two deliberate exclusions preserve pre-existing wire contracts
+ * (vault#554 — statuses/error_types on previously-working calls must not
+ * change):
+ *
+ * 1. The SEPARATE own-field checks (unsupported type for indexing,
+ *    invalid identifier) are NOT included — REST's `PUT /api/tags/:name`
+ *    has an established, tested single-violation `IndexedFieldError` →
+ *    400 `invalid_indexed_field` contract for those (vault#478). Use
+ *    {@link collectTagFieldViolations} (own-field checks included) for a
+ *    caller — MCP's `update-tag` tool — with no such prior contract.
+ * 2. The type-conflict check is SKIPPED for any field whose INCOMING spec
+ *    is `indexed: true` (wire review, vault#554): a both-indexed cross-tag
+ *    type conflict already errors on main via `store.upsertTagRecord` →
+ *    `declareField`'s cross-declarer sqlite-type check (`IndexedFieldError`
+ *    → 400 `invalid_indexed_field`), and reporting it here would flip that
+ *    established 400 to a 422. Letting it fall through preserves the 400.
+ *    No case is silently re-accepted by the skip: an incoming-indexed type
+ *    conflict against an INDEXED declarer hits declareField's 400; against
+ *    a NON-indexed declarer the indexed-FLAG conflict below still fires
+ *    (the flags necessarily differ). What this function newly reports —
+ *    both silent 200s on main — is (a) type conflicts on NON-indexed
+ *    incoming fields and (b) indexed-flag conflicts.
+ */
+export function collectCrossTagFieldViolations(
+  db: Database,
+  tag: string,
+  incomingFields: Record<string, TagFieldSchema>,
+): TagFieldViolation[] {
+  const violations: TagFieldViolation[] = [];
+  const otherSchemas = 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;
+      // See doc comment exclusion 2: incoming-indexed type conflicts keep
+      // their pre-existing declareField → 400 invalid_indexed_field path.
+      if (!incomingIndexed && otherSpec.type !== spec.type) {
+        violations.push({
+          field: fieldName,
+          reason: "type_conflict",
+          message: `field "${fieldName}" type conflict: tag "${tag}" declares "${spec.type}"; tag "${other.tag}" declares "${otherSpec.type}". Types must agree across all declarers.`,
+          other_tag: other.tag,
+        });
+      }
+      if ((otherSpec.indexed === true) !== incomingIndexed) {
+        violations.push({
+          field: fieldName,
+          reason: "indexed_flag_conflict",
+          message: `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.`,
+          other_tag: other.tag,
+        });
+      }
+    }
+  }
+  return violations;
+}
+
+/**
+ * Full field-violation collection: {@link collectCrossTagFieldViolations}
+ * PLUS the own-field checks (unsupported type for indexing, invalid
+ * identifier). Used by the MCP `update-tag` tool, which — unlike REST — had
+ * no prior single-violation status-code contract to preserve for those two
+ * checks (its old inline loop threw an unstructured `Error` for them, same
+ * as everything else pre-#554); collecting everything here is a strict
+ * improvement. See {@link collectCrossTagFieldViolations}'s doc comment for
+ * why REST calls that narrower function directly instead of this one.
+ */
+export function collectTagFieldViolations(
+  db: Database,
+  tag: string,
+  incomingFields: Record<string, TagFieldSchema>,
+): TagFieldViolation[] {
+  const violations = collectCrossTagFieldViolations(db, tag, incomingFields);
+
+  for (const [fieldName, spec] of Object.entries(incomingFields)) {
+    if (spec.indexed === true) {
+      const mapped = mapFieldType(spec.type);
+      if (!mapped) {
+        violations.push({
+          field: fieldName,
+          reason: "unsupported_indexed_type",
+          message: `field "${fieldName}" has unsupported type "${spec.type}" for indexing (supported: string, integer, boolean)`,
+        });
+      } else {
+        try {
+          validateFieldName(fieldName);
+        } catch (err) {
+          violations.push({
+            field: fieldName,
+            reason: "invalid_field_name",
+            message: (err as Error).message,
+          });
+        }
+      }
+    }
+  }
+
+  return violations;
+}

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.3",
+  "version": "0.7.0-rc.5",
   "description": "Agent-native knowledge graph. Notes, tags, links over MCP.",
   "module": "src/cli.ts",
   "type": "module",