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

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
@@ -43,6 +44,25 @@ export interface TagFieldSchema {
   // "one" (scalar, default) or "many" (array). Advisory unless `strict:true`.
   // Distinct from relationship cardinality. vault#299.
   cardinality?: "one" | "many";
+  /**
+   * Explicit backfill value (vault#553 Decision B). When a note gains this
+   * tag and doesn't set the field, `applySchemaDefaults` (core/src/mcp.ts)
+   * writes THIS value onto the note. Undeclared (the default) means the
+   * field stays ABSENT on notes that don't set it — no more implicit
+   * first-enum-value / type-zero-value backfill. This is what makes
+   * `exists:false` trustworthy: "never set" and "explicitly set to the
+   * default" are now distinguishable states.
+   *
+   * Must conform to this field's own `type` (and `enum`, when declared) —
+   * `upsertTagRecord` (core/src/store.ts, the single chokepoint both REST
+   * and MCP funnel through) validates the default BEFORE persisting via
+   * {@link validateFieldDefault}; a non-conforming default is a tag-schema
+   * error (`invalid_field_default` / `TagFieldViolation` reason
+   * `"invalid_default"`), not a silent typo. `undefined` is JSON-serialized
+   * away by `JSON.stringify` — an omitted `default` key round-trips as "not
+   * declared", never as a stored `null`.
+   */
+  default?: unknown;
 }
 
 /**
@@ -132,10 +152,128 @@ 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`.
+ */
+/**
+ * Thrown by `upsertTagRecord` (core/src/store.ts's chokepoint — REST
+ * `PUT /api/tags/:name` and MCP `update-tag` both funnel through it) when a
+ * field's declared `default` (vault#553 Decision B) doesn't conform to that
+ * SAME field's own `type` (or `enum`, when declared). A bad default is a
+ * tag-schema authoring error, not silently-accepted junk that would poison
+ * every note gaining the tag — fail closed, same posture as
+ * `IndexedFieldError` and `ParentCycleError`. `error_type` is stamped
+ * directly (own-field validation leaf, one caller-facing shape) so the
+ * generic MCP domain-error mapping (`src/mcp-http.ts`) and REST's dedicated
+ * catch branch both surface it without a bespoke class-specific mapping.
+ */
+export class InvalidFieldDefaultError extends Error {
+  code = "INVALID_FIELD_DEFAULT" as const;
+  error_type = "invalid_field_default" as const;
+  field: string;
+
+  constructor(field: string, message: string) {
+    super(message);
+    this.name = "InvalidFieldDefaultError";
+    this.field = field;
+  }
+}
+
+/**
+ * Validate that a field's declared `default` (vault#553 Decision B) conforms
+ * to its own `type` and (when declared) `enum`. Returns `null` when the
+ * field has no `default` (the common case) or the default is valid;
+ * otherwise a {@link TagFieldViolation} with `reason: "invalid_default"`.
+ * Pure — never throws; the two callers (the store chokepoint's fail-fast
+ * pre-validate, and {@link collectTagFieldViolations}'s bundled MCP report)
+ * each decide how to surface it.
+ *
+ * Deliberately independent of `schema-defaults.ts`'s `valueMatchesType` (this
+ * module doesn't import that one, and vice versa — no cycle either way) so
+ * the two modules' type vocabularies can drift without cross-coupling; the
+ * rules are kept in lockstep by hand (string/number/integer/boolean/array/
+ * object, the SAME six as `TagFieldSchema.type`'s documented vocabulary).
+ */
+export function validateFieldDefault(field: string, spec: TagFieldSchema): TagFieldViolation | null {
+  if (spec.default === undefined) return null;
+  const value = spec.default;
+  const typeOk = defaultMatchesType(value, spec.type);
+  if (!typeOk) {
+    return {
+      field,
+      reason: "invalid_default",
+      message: `field "${field}" declares default ${JSON.stringify(value)}, which does not match its own type "${spec.type}"`,
+    };
+  }
+  if (spec.enum && spec.enum.length > 0 && typeof value === "string" && !spec.enum.includes(value)) {
+    return {
+      field,
+      reason: "invalid_default",
+      message: `field "${field}" declares default "${value}", which is not one of its own enum values [${spec.enum.join(", ")}]`,
+    };
+  }
+  return null;
+}
+
+/** Same six-type vocabulary as `TagFieldSchema.type`'s doc comment. Unknown/unset types pass (nothing to check against). */
+function defaultMatchesType(value: unknown, type: string): boolean {
+  switch (type) {
+    case "string":
+      return typeof value === "string";
+    case "number":
+      return typeof value === "number" && Number.isFinite(value);
+    case "integer":
+      return typeof value === "number" && Number.isInteger(value);
+    case "boolean":
+      return typeof value === "boolean";
+    case "array":
+      return Array.isArray(value);
+    case "object":
+      return !!value && typeof value === "object" && !Array.isArray(value);
+    default:
+      return true;
+  }
+}
+
+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 +285,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 (?, ?, ?)",
@@ -358,7 +502,12 @@ function jsonOrNull(value: unknown): string | null {
  */
 export interface TagFieldViolation {
   field: string;
-  reason: "type_conflict" | "indexed_flag_conflict" | "unsupported_indexed_type" | "invalid_field_name";
+  reason:
+    | "type_conflict"
+    | "indexed_flag_conflict"
+    | "unsupported_indexed_type"
+    | "invalid_field_name"
+    | "invalid_default";
   message: string;
   /**
    * The conflicting declarer tag — present on the cross-tag reasons
@@ -477,12 +626,17 @@ export function collectCrossTagFieldViolations(
 /**
  * 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
+ * identifier, and — vault#553 Decision B — a non-conforming `default`).
+ * Used by the MCP `update-tag` tool, which — unlike REST — had no prior
+ * single-violation status-code contract to preserve for those 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.
+ * why REST calls that narrower function directly instead of this one — REST
+ * gets the SAME `invalid_default` coverage via `store.upsertTagRecord`'s
+ * fail-fast pre-validate (mirrors its indexed-type/name checks), just as a
+ * single-violation `InvalidFieldDefaultError` → 400 rather than a bundled
+ * `TagFieldConflictError` → 422.
  */
 export function collectTagFieldViolations(
   db: Database,
@@ -492,6 +646,12 @@ export function collectTagFieldViolations(
   const violations = collectCrossTagFieldViolations(db, tag, incomingFields);
 
   for (const [fieldName, spec] of Object.entries(incomingFields)) {
+    // Own-field default-conformance check (vault#553 Decision B) — applies
+    // to EVERY field (not just indexed ones); a bad default is a tag-schema
+    // error regardless of whether the field is queryable.
+    const defaultViolation = validateFieldDefault(fieldName, spec);
+    if (defaultViolation) violations.push(defaultViolation);
+
     if (spec.indexed === true) {
       const mapped = mapFieldType(spec.type);
       if (!mapped) {

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.6",
   "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,

package/src/onboarding-seed.test.ts

@@ -166,8 +166,11 @@ describe("seedOnboardingNotes — default packs (welcome + getting-started)", ()
     expect(gs!.content).toContain("## Write gotchas");
     expect(gs!.content).toContain("if_updated_at"); // optimistic concurrency
     expect(gs!.content).toContain("force: true");
-    // schema-default back-fill: enum→first value, integer→0.
-    expect(gs!.content).toContain("first listed value");
+    // schema-default back-fill is explicit-`default`-only (vault#553 Decision B).
+    expect(gs!.content).toContain("explicit `default`");
+    expect(gs!.content).toContain("exists: false");
+    // indexed⇒strict type enforcement (vault#553 Decision A).
+    expect(gs!.content).toContain("field's TYPE is always enforced");
   });
 
   test("A3 (reshaped): the welcome ring resolves to real link edges; Getting Started has no dangling Surface Starter link", async () => {

package/src/routes.ts

@@ -24,7 +24,7 @@ import {
   contentRangeRequiresContent,
   type ContentRange,
 } from "../core/src/content-range.ts";
-import { attachValidationStatus, enforceStrictWrite } from "../core/src/mcp.ts";
+import { attachValidationStatus, enforceStrictWrite, applySchemaDefaults } from "../core/src/mcp.ts";
 import type { ValidationWarning } from "../core/src/schema-defaults.ts";
 import { logStrictBypass } from "./scopes.ts";
 import * as linkOps from "../core/src/links.ts";
@@ -42,10 +42,13 @@ import {
   filterNotesByTagScope,
   noteWithinTagScope,
   scrubIndexedFieldConflictError,
+  scrubParentCycleError,
+  scrubReferencingTagsByScope,
   scrubTagFieldViolationsByScope,
   tagScopeForbidden,
   tagsWithinScope,
 } from "./tag-scope.ts";
+import { ParentCycleError, InvalidFieldDefaultError } from "../core/src/tag-schemas.ts";
 import { findTokensReferencingTag } from "./token-store.ts";
 
 /**
@@ -2665,6 +2668,41 @@ export async function handleTags(
           400,
         );
       }
+      if (err instanceof InvalidFieldDefaultError) {
+        // vault#553 Decision B — a declared `default` doesn't conform to its
+        // own field's type/enum. Own-field error (no cross-tag data), so no
+        // scrub needed. Mirrors IndexedFieldError's 400 shape/posture — see
+        // store.upsertTagRecord's pre-validate comment for why REST hits
+        // this (fail-fast, single violation) while MCP's update-tag usually
+        // reports it bundled via `TagFieldConflictError` instead.
+        return json(
+          { error: err.message, error_type: "invalid_field_default", field: err.field },
+          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 +2730,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 +2988,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
 // ---------------------------------------------------------------------------
@@ -3662,56 +3747,10 @@ export async function handleStorage(
   return json({ error: "Not found", error_type: "not_found" }, 404);
 }
 
-// ---------------------------------------------------------------------------
-// Tag schema defaults — same logic as core/src/mcp.ts applySchemaDefaults
-// ---------------------------------------------------------------------------
-
-// Returns the IDs of notes whose metadata was actually default-filled, so
-// the caller can re-read ONLY the mutated notes (and skip the re-read when
-// nothing changed). Mirrors the core/src/mcp.ts contract.
-async function applySchemaDefaults(store: Store, db: any, noteIds: string[], tags: string[]): Promise<string[]> {
-  const schemas = tagSchemaOps.getTagSchemaMap(db);
-  if (Object.keys(schemas).length === 0) return [];
-
-  const defaults: Record<string, unknown> = {};
-  for (const tag of tags) {
-    const schema = schemas[tag];
-    if (!schema?.fields) continue;
-    for (const [field, fieldSchema] of Object.entries(schema.fields)) {
-      if (!(field in defaults)) {
-        defaults[field] = defaultForField(fieldSchema);
-      }
-    }
-  }
-  if (Object.keys(defaults).length === 0) return [];
-
-  const mutated: string[] = [];
-  for (const noteId of noteIds) {
-    const note = await store.getNote(noteId);
-    if (!note) continue;
-    const existing = (note.metadata as Record<string, unknown>) ?? {};
-    const missing: Record<string, unknown> = {};
-    for (const [field, value] of Object.entries(defaults)) {
-      if (!(field in existing)) missing[field] = value;
-    }
-    if (Object.keys(missing).length === 0) continue;
-    await store.updateNote(noteId, {
-      metadata: { ...existing, ...missing },
-      skipUpdatedAt: true,
-    });
-    mutated.push(noteId);
-  }
-  return mutated;
-}
-
-function defaultForField(field: { type: string; enum?: string[] }): unknown {
-  if (field.enum && field.enum.length > 0) return field.enum[0];
-  switch (field.type) {
-    case "boolean": return false;
-    case "integer": return 0;
-    default: return "";
-  }
-}
+// applySchemaDefaults lives in core/src/mcp.ts (vault#553) — REST used to
+// carry a byte-identical duplicate; importing it means REST and MCP can
+// never drift on this behavior again, and the cloud runtime (which imports
+// core directly) inherits it without any handler-side code.
 
 function removeWikilinkBrackets(content: string, targetPath: string): string {
   const escaped = targetPath.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");