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

package/core/src/mcp.ts

@@ -190,9 +190,11 @@ export interface GenerateMcpToolsOpts {
 }
 
 /**
- * Generate the consolidated MCP tools for a vault. Surface (10):
+ * Generate the consolidated MCP tools for a vault. Surface (13):
  * query-notes, create-note, update-note, delete-note, list-tags, update-tag,
- * delete-tag, find-path, vault-info, prune-schema (admin).
+ * delete-tag, rename-tag, merge-tags, find-path, vault-info, prune-schema
+ * (admin), doctor (admin). `manage-token` (admin) is appended by the SERVER
+ * layer (src/mcp-tools.ts), not here — see that file's doc comment.
  */
 export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): McpToolDef[] {
   const db: Database = store.db;
@@ -1586,15 +1588,16 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
           description: { type: "string", description: "Human-readable description of what this tag means" },
           fields: {
             type: "object",
-            description: 'Metadata fields notes with this tag should have. E.g., { "status": { "type": "string", "enum": ["active", "archived"], "strict": true } }. Constraints are ADVISORY by default (violations surface as validation_status warnings; the write still succeeds). Mark a field `strict: true` to ENFORCE all its constraints — type + enum + required + cardinality flip to hard write rejections (vault#299).',
+            description: 'Metadata fields notes with this tag should have. E.g., { "status": { "type": "string", "enum": ["active", "archived"], "strict": true, "default": "active" } }. Constraints are ADVISORY by default (violations surface as validation_status warnings; the write still succeeds). Mark a field `strict: true` to ENFORCE all its constraints — type + enum + required + cardinality flip to hard write rejections (vault#299). Mark a field `indexed: true` to make it queryable — an indexed field\'s TYPE is ALWAYS enforced (a type-mismatched write is REJECTED, independent of `strict`) because a bad-typed value silently poisons range-query ordering (vault#553).',
             additionalProperties: {
               type: "object",
               properties: {
-                type: { type: "string", description: "Field type: string, boolean, integer, number, array, object" },
+                type: { type: "string", description: "Field type: string, boolean, integer, number, array, object — all six are accepted for storage + advisory validation. Only string/integer/boolean are INDEXABLE (see `indexed` below); declaring `indexed: true` with number/array/object is rejected (unsupported_indexed_type / invalid_indexed_field)." },
                 description: { type: "string" },
-                enum: { type: "array", items: { type: "string" }, description: "Allowed values (first is default)" },
-                indexed: { type: "boolean", description: "When true, a generated column + index are maintained on notes.metadata.<field>, making it queryable via metadata operator objects and order_by. Global: all tags declaring the field must agree on both type and indexed." },
-                strict: { type: "boolean", description: "vault#299. Default false (advisory). When true, ALL of this field's declared constraints (type + enum + required + cardinality) are ENFORCED — a violating write is rejected with a schema_validation error, not just warned. All-or-nothing per field; free-form fields on a strict tag simply leave strict off." },
+                enum: { type: "array", items: { type: "string" }, description: "Allowed values. Does NOT auto-backfill — a note that omits this field stays without it unless `default` is also set (vault#553; the pre-0.7.0 behavior of silently defaulting to the first enum value is retired). Set `default` explicitly if you want backfill." },
+                default: { description: "Explicit backfill value (vault#553) applied when a note gains this tag without setting the field. Must conform to this field's own `type` (and `enum`, if declared) — a non-conforming default is rejected (invalid_default / invalid_field_default) rather than silently stored. Omit entirely to leave the field ABSENT (not backfilled) on notes that don't set it — this is what makes `exists:false` a trustworthy \"never set\" query." },
+                indexed: { type: "boolean", description: "When true, a generated column + index are maintained on notes.metadata.<field>, making it queryable via metadata operator objects and order_by. Global: all tags declaring the field must agree on both type and indexed. Only string/integer/boolean are indexable. Indexed ⇒ a type-mismatched write is HARD-REJECTED (schema_validation), not just warned — vault#553." },
+                strict: { type: "boolean", description: "vault#299. Default false (advisory). When true, ALL of this field's declared constraints (type + enum + required + cardinality) are ENFORCED — a violating write is rejected with a schema_validation error, not just warned. All-or-nothing per field; free-form fields on a strict tag simply leave strict off. Note: `indexed: true` fields enforce their TYPE constraint regardless of this flag (vault#553)." },
                 required: { type: "boolean", description: "vault#299. The field must be present + non-null on a note with this tag. Advisory unless `strict: true`." },
                 cardinality: { type: "string", enum: ["one", "many"], description: "vault#299. 'one' (scalar, default) or 'many' (array). Advisory unless `strict: true`." },
               },
@@ -1716,11 +1719,13 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
       // mgmt + future config writes; deletes are write-tier mutations.
       // See delete-note rationale.
       requiredVerb: "write",
-      description: "Delete a tag, remove it from all notes, and delete its schema. Notes themselves are NOT deleted — just untagged.",
+      description: "Delete a tag, remove it from all notes, and delete its schema. Notes themselves are NOT deleted — just untagged. Refused with error_type \"tag_referenced_as_parent\" (vault#552) when another tag's parent_names still names this one — pass cascade OR detach (either — both mean the same thing: strip the stale reference from the referencing tag(s)' parent_names, never delete them) to proceed anyway.",
       inputSchema: {
         type: "object",
         properties: {
           tag: { type: "string", description: "Tag name to delete" },
+          cascade: { type: "boolean", description: "Proceed even though another tag's parent_names references this one, stripping the reference. Synonym of detach." },
+          detach: { type: "boolean", description: "Same as cascade — proceed and strip the stale parent_names reference from referencing tag(s)." },
         },
         required: ["tag"],
       },
@@ -1731,8 +1736,107 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
         // Indexed-field release is handled inside store.deleteTag →
         // noteOps.deleteTag so every entry point (MCP, REST, import sweep)
         // releases consistently with the co-declaration guard. See the
-        // gitcoin orphaned-fields bug report.
-        return await store.deleteTag(tag);
+        // gitcoin orphaned-fields bug report. The referential-integrity
+        // guard (vault#552) is ALSO inside store.deleteTag, so it returns
+        // (not throws) `{error: "tag_referenced_as_parent", ...}` when
+        // refused — same in-band shape delete-tag has always used for its
+        // token-reference guard (applyTagDependencyGuards, src/mcp-tools.ts).
+        return await store.deleteTag(tag, {
+          cascade: params.cascade === true,
+          detach: params.detach === true,
+        });
+      },
+    },
+
+    // =====================================================================
+    // 7a. rename-tag — atomic cascading rename (vault#552 MCP parity)
+    // =====================================================================
+    {
+      name: "rename-tag",
+      requiredVerb: "write",
+      description:
+        "Atomically rename a tag across EVERY surface that references it: note memberships, OTHER tags' parent_names, tag-scoped tokens' allowlists, indexed-field declarer lists, inline #tag mentions in note bodies, and _tags/<name> config-note paths — all in one transaction. THIS is the fix for the manual retag→delete dance (create the new tag, retag notes, delete the old one): that dance silently orphans parent_names references (the renamed-away tag stays a live query surface via subtype expansion while list-tags reports it at count 0, and the new tag misses every child-tagged note) and leaves stale #tag mentions behind. Sub-tags rename recursively — renaming \"task\" to \"todo\" also renames \"task/work\" to \"todo/work\". Does NOT rewrite metadata values that happen to equal the old tag name (e.g. metadata.epic: \"task\") — that's a distinct drift class the doctor tool's dead_tag_metadata_reference finding flags heuristically; rename-tag's job is structural (tags/note_tags/parent_names/tokens/content), not a blind string search-and-replace over arbitrary metadata.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          old_name: { type: "string", description: "The tag to rename. Aliases: from, tag." },
+          new_name: { type: "string", description: "The new name. Alias: to." },
+          from: { type: "string", description: "Alias for old_name." },
+          to: { type: "string", description: "Alias for new_name." },
+          tag: { type: "string", description: "Alias for old_name." },
+        },
+      },
+      execute: async (params) => {
+        const oldName = (params.old_name ?? params.from ?? params.tag) as string | undefined;
+        const newName = (params.new_name ?? params.to) as string | undefined;
+        if (typeof oldName !== "string" || oldName.length === 0) {
+          throw structuredError("rename-tag: old_name (or from/tag) is required", {
+            error_type: "invalid_request",
+            field: "old_name",
+          });
+        }
+        if (typeof newName !== "string" || newName.length === 0) {
+          throw structuredError("rename-tag: new_name (or to) is required", {
+            error_type: "invalid_request",
+            field: "new_name",
+          });
+        }
+        const result = await store.renameTag(oldName, newName);
+        if ("error" in result) {
+          if (result.error === "not_found") {
+            throw structuredError(`rename-tag: tag "${oldName}" not found`, {
+              error_type: "tag_not_found",
+              field: "old_name",
+            });
+          }
+          throw Object.assign(
+            new Error(
+              `rename-tag: target "${newName}" (or one of its sub-tags) already exists — use merge-tags to combine them instead`,
+            ),
+            {
+              error_type: "target_exists" as const,
+              target: newName,
+              conflicting: result.conflicting,
+              hint: "use merge-tags to combine the tags instead",
+            },
+          );
+        }
+        return result;
+      },
+    },
+
+    // =====================================================================
+    // 7b. merge-tags — same machinery, N sources → one target
+    // =====================================================================
+    {
+      name: "merge-tags",
+      requiredVerb: "write",
+      description:
+        "Atomically merge one or more source tags into a target tag: every note carrying any source is retagged with the target, then the source tags (and their identity rows — description/fields/relationships/parent_names) are dropped. target is created if it doesn't exist yet; target's own schema is preserved (sources' schemas are consumed, not merged field-by-field). Sources that don't exist are reported at count 0. Refused with error_type \"tag_in_use_by_tokens\" if a source is referenced by a tag-scoped token — revoke or re-mint it first.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          sources: { type: "array", items: { type: "string" }, description: "Tag names to merge away into target." },
+          target: { type: "string", description: "The tag that survives; sources are retagged onto it and dropped." },
+        },
+        required: ["sources", "target"],
+      },
+      execute: async (params) => {
+        const sources = params.sources;
+        const target = params.target;
+        if (!Array.isArray(sources) || sources.length === 0 || !sources.every((s) => typeof s === "string" && s.length > 0)) {
+          throw structuredError("merge-tags: sources must be a non-empty array of strings", {
+            error_type: "invalid_request",
+            field: "sources",
+          });
+        }
+        if (typeof target !== "string" || target.length === 0) {
+          throw structuredError("merge-tags: target must be a non-empty string", {
+            error_type: "invalid_request",
+            field: "target",
+          });
+        }
+        return await store.mergeTags(sources as string[], target);
       },
     },
 
@@ -1822,6 +1926,22 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
       },
     },
 
+    // =====================================================================
+    // 11. doctor — read-only taxonomy/metadata integrity scan (vault#552)
+    // =====================================================================
+    {
+      name: "doctor",
+      // `admin` — same tier as prune-schema: a diagnostic over the WHOLE
+      // vault's taxonomy, not scoped to any one tag's write authority.
+      requiredVerb: "admin",
+      description:
+        "Read-only integrity scan across the tag/metadata taxonomy — run this after any bulk tag reorg (rename/merge/delete/subtree move) to confirm nothing leaked. Reports, per finding, {type, severity, subject, detail, remedy} — NEVER auto-fixes; apply the suggested remedy (usually rename-tag/merge-tags/update-tag/prune-schema) yourself. Finding types: dangling_parent_name (a parent_names entry naming a tag with no identity row), parent_names_cycle (a tag reaching itself through its ancestor chain — traversal tolerates this, but it's dishonest hierarchy state), mixed_type_indexed_field (a note's metadata value for an indexed field has a JSON type disagreeing with the field's declared storage type — the ordering/filtering-goes-silently-wrong precursor), orphaned_indexed_field_declarer (an indexed field naming a dead declarer tag — see prune-schema), and dead_tag_metadata_reference (HEURISTIC, always carries heuristic:true — a metadata value that looks like a stale reference to a renamed/merged/deleted tag, inferred from sibling notes using the same metadata key with values that ARE live tags; can never be certain since vault keeps no tag-rename history).",
+      inputSchema: { type: "object", properties: {} },
+      execute: async () => {
+        return await store.doctor();
+      },
+    },
+
   ];
 }
 
@@ -1834,18 +1954,33 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
  * for any field they omitted. Returns the IDs of the notes whose metadata was
  * actually written — callers use this to re-read ONLY the mutated notes (and
  * to skip the re-read entirely when nothing changed). The common no-schema /
- * no-defaults path returns an empty array.
+ * no-declared-defaults path returns an empty array.
+ *
+ * vault#553 Decision B: backfill is EXPLICIT-`default`-only. A field with no
+ * declared `default` is skipped entirely here — it stays genuinely absent on
+ * the note, not silently filled with the first enum value or a type
+ * zero-value (the pre-0.7.0 behavior, which made "never set" and
+ * "explicitly set to the default" indistinguishable and broke `exists:false`).
+ * Exported so `src/routes.ts` (REST create/PATCH) shares this ONE
+ * implementation instead of carrying its own copy — the two had drifted into
+ * a byte-identical duplicate pre-#553; centralizing here means the cloud
+ * runtime (which imports core directly, not `src/routes.ts`) automatically
+ * inherits this behavior with zero handler-side work.
  *
  * vault#299: this runs AFTER the create write (so AFTER the strict gate) and
  * intentionally does NOT re-run `enforceStrict`. Defaults are always
- * conforming by construction — `defaultForField` returns the first enum value
- * / the type's zero-value, so a default can never violate type/enum. And a
- * `required` strict field is already caught at the pre-write gate, so a note
- * that would need a default to satisfy `required` never reaches this filler
- * (the create was rejected first). Don't add a defaults path that could
- * inject a violating value without re-gating.
+ * conforming by construction — `store.upsertTagRecord` validates a field's
+ * `default` against its own `type`/`enum` BEFORE the schema can be persisted
+ * (`InvalidFieldDefaultError` / `TagFieldConflictError` reason
+ * `invalid_default`), so a default can never violate type/enum at read time
+ * here. And a `required` strict field is already caught at the pre-write
+ * gate, so a note that would need a default to satisfy `required` never
+ * reaches this filler (the create was rejected first) — declaring a
+ * `default` does NOT satisfy `required`; the caller must still set the field
+ * explicitly. Don't add a defaults path that could inject a violating value
+ * without re-gating.
  */
-async function applySchemaDefaults(store: Store, db: Database, noteIds: string[], tags: string[]): Promise<string[]> {
+export async function applySchemaDefaults(store: Store, db: Database, noteIds: string[], tags: string[]): Promise<string[]> {
   const schemas = tagSchemaOps.getTagSchemaMap(db);
   if (Object.keys(schemas).length === 0) return [];
 
@@ -1854,9 +1989,10 @@ async function applySchemaDefaults(store: Store, db: Database, noteIds: string[]
     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 (field in defaults) continue; // first tag that declares a REAL default wins
+      const value = defaultForField(fieldSchema);
+      if (value === undefined) continue; // no `default` declared — leave the slot open for a later tag
+      defaults[field] = value;
     }
   }
   if (Object.keys(defaults).length === 0) return [];
@@ -1882,13 +2018,13 @@ async function applySchemaDefaults(store: Store, db: Database, noteIds: string[]
   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 "";
-  }
+/**
+ * Resolve a field's backfill value — its declared `default` (vault#553
+ * Decision B), or `undefined` when none was declared (the field stays
+ * absent). Exported alongside `applySchemaDefaults` for `src/routes.ts`.
+ */
+export function defaultForField(field: { default?: unknown }): unknown {
+  return field.default;
 }
 
 // ---------------------------------------------------------------------------

package/core/src/notes.ts

@@ -1512,40 +1512,114 @@ export function listTags(db: Database): { name: string; count: number; expanded_
   return rows.map((r) => ({ ...r, expanded_count: expandedCounts.get(r.name) ?? 0 }));
 }
 
-export function deleteTag(db: Database, name: string): { deleted: boolean; notes_untagged: number } {
+/** Options accepted by {@link deleteTag} (vault#552). */
+export interface DeleteTagOpts {
+  /**
+   * Proceed with the delete even though another tag's `parent_names`
+   * references this one — strip the reference from every referencing tag's
+   * `parent_names` array as part of the same transaction. Accepted as a
+   * synonym of `detach` (both name the identical repair: remove the stale
+   * reference, never delete the referencing tag itself); offered as two
+   * flags because operators reach for either word depending on whether
+   * they're thinking "cascade the delete" or "detach the children."
+   */
+  cascade?: boolean;
+  /** Synonym of `cascade` — see above. */
+  detach?: boolean;
+}
+
+export type DeleteTagResult =
+  | { deleted: boolean; notes_untagged: number; parent_refs_detached?: number }
+  | { error: "tag_referenced_as_parent"; referencing_tags: string[] };
+
+/**
+ * Delete a tag: drop its identity row, untag every note carrying it, and
+ * release any indexed fields it exclusively declared. Notes themselves are
+ * NEVER deleted — only untagged.
+ *
+ * Referential integrity (vault#552): if another tag's `parent_names` array
+ * names `name`, deleting it would silently orphan that reference — the
+ * child tag's hierarchy edge would point at a name with no identity row
+ * (the exact "renamed-away tag remains a live query surface" class of bug
+ * the gardener found, one hop over from rename). Refuse by default with
+ * `{ error: "tag_referenced_as_parent", referencing_tags }`; pass
+ * `opts.cascade` or `opts.detach` (either — see {@link DeleteTagOpts}) to
+ * proceed, stripping `name` from every referencing tag's `parent_names` in
+ * the same transaction as the delete.
+ */
+export function deleteTag(db: Database, name: string, opts?: DeleteTagOpts): DeleteTagResult {
   const row = db.prepare("SELECT fields FROM tags WHERE name = ?").get(name) as
     | { fields: string | null }
     | null;
   if (!row) return { deleted: false, notes_untagged: 0 };
 
-  const countRow = db.prepare("SELECT COUNT(*) as c FROM note_tags WHERE tag_name = ?").get(name) as { c: number };
-  const notesUntagged = countRow.c;
-
-  // Release any indexed fields this tag declared BEFORE the row drops.
-  // `releaseField` only drops the generated column + index when this tag is
-  // the last live declarer (co-declaration guard) — a field co-declared by
-  // another live tag keeps its column and just loses this tag from the set.
-  // This lives in the store-level delete (not the MCP layer) so every caller
-  // — MCP delete-tag, the REST DELETE /tags/:name route, the import
-  // blow-away sweep — releases consistently. See the gitcoin orphaned-fields
-  // bug report.
-  if (row.fields) {
-    try {
-      const fields = JSON.parse(row.fields) as Record<string, { indexed?: boolean }>;
-      for (const [fieldName, spec] of Object.entries(fields)) {
-        if (spec?.indexed === true) {
-          releaseField(db, fieldName, name);
+  // Referential-integrity guard: who names `name` as a parent? Reuses the
+  // SAME parent_names parsing loadTagHierarchy uses everywhere else in the
+  // hierarchy (rather than a bespoke LIKE scan) so "who references this
+  // tag" answers identically here as it does for query expansion.
+  const hierarchy = loadTagHierarchy(db);
+  const referencing = Array.from(hierarchy.childrenOf.get(name) ?? []);
+  if (referencing.length > 0 && !opts?.cascade && !opts?.detach) {
+    return { error: "tag_referenced_as_parent", referencing_tags: referencing.sort() };
+  }
+
+  return transaction(db, (): DeleteTagResult => {
+    // Strip the stale reference from every referencing tag's parent_names
+    // BEFORE dropping this tag's own row — order doesn't matter for
+    // correctness (different rows), but doing the repair first means a
+    // mid-transaction failure never leaves the identity row gone with
+    // dangling references still pointing at it.
+    let parentRefsDetached = 0;
+    if (referencing.length > 0) {
+      const readStmt = db.prepare("SELECT parent_names FROM tags WHERE name = ?");
+      const updateStmt = db.prepare("UPDATE tags SET parent_names = ?, updated_at = ? WHERE name = ?");
+      const now = new Date().toISOString();
+      for (const refTag of referencing) {
+        const r = readStmt.get(refTag) as { parent_names: string | null } | null;
+        if (!r?.parent_names) continue;
+        let parsed: unknown;
+        try { parsed = JSON.parse(r.parent_names); } catch { continue; }
+        if (!Array.isArray(parsed)) continue;
+        const next = (parsed as unknown[]).filter((p) => p !== name);
+        if (next.length === parsed.length) continue;
+        updateStmt.run(next.length > 0 ? JSON.stringify(next) : null, now, refTag);
+        parentRefsDetached++;
+      }
+    }
+
+    const countRow = db.prepare("SELECT COUNT(*) as c FROM note_tags WHERE tag_name = ?").get(name) as { c: number };
+    const notesUntagged = countRow.c;
+
+    // Release any indexed fields this tag declared BEFORE the row drops.
+    // `releaseField` only drops the generated column + index when this tag is
+    // the last live declarer (co-declaration guard) — a field co-declared by
+    // another live tag keeps its column and just loses this tag from the set.
+    // This lives in the store-level delete (not the MCP layer) so every caller
+    // — MCP delete-tag, the REST DELETE /tags/:name route, the import
+    // blow-away sweep — releases consistently. See the gitcoin orphaned-fields
+    // bug report.
+    if (row.fields) {
+      try {
+        const fields = JSON.parse(row.fields) as Record<string, { indexed?: boolean }>;
+        for (const [fieldName, spec] of Object.entries(fields)) {
+          if (spec?.indexed === true) {
+            releaseField(db, fieldName, name);
+          }
         }
+      } catch {
+        // Malformed fields JSON — nothing to release; proceed with the delete.
       }
-    } catch {
-      // Malformed fields JSON — nothing to release; proceed with the delete.
     }
-  }
 
-  db.prepare("DELETE FROM note_tags WHERE tag_name = ?").run(name);
-  db.prepare("DELETE FROM tags WHERE name = ?").run(name);
+    db.prepare("DELETE FROM note_tags WHERE tag_name = ?").run(name);
+    db.prepare("DELETE FROM tags WHERE name = ?").run(name);
 
-  return { deleted: true, notes_untagged: notesUntagged };
+    return {
+      deleted: true,
+      notes_untagged: notesUntagged,
+      ...(parentRefsDetached > 0 ? { parent_refs_detached: parentRefsDetached } : {}),
+    };
+  });
 }
 
 // The UNIQUE PRIMARY KEY on tags.name means rename-to-existing is ambiguous:

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++;
   }