@openparachute/vault 0.4.8 → 0.4.9-rc.11

package/core/src/mcp.ts

@@ -20,6 +20,18 @@ export interface McpToolDef {
   description: string;
   inputSchema: Record<string, unknown>;
   execute: (params: Record<string, unknown>) => unknown | Promise<unknown>;
+  /**
+   * Minimum scope verb the caller must hold for THIS vault to see + invoke
+   * the tool. `read` for pure queries, `write` for mutations, `admin` for
+   * operator-only surfaces (`prune-schema` in core; `manage-token` in the
+   * server layer). The MCP HTTP layer filters
+   * `tools/list` by this field and verb-gates `tools/call` against it; the
+   * filter is the primary defense, the inner gate is defense-in-depth.
+   *
+   * Pre-v19 unstamped tools default to `write` at the dispatch layer so a
+   * future addition that forgets to stamp this gets the safer treatment.
+   */
+  requiredVerb: "read" | "write" | "admin";
 }
 
 // ---------------------------------------------------------------------------
@@ -88,9 +100,9 @@ function removeWikilinkBrackets(content: string, targetPath: string): string {
 // ---------------------------------------------------------------------------
 
 /**
- * Generate the consolidated MCP tools for a vault. Post-v17 surface (9):
+ * Generate the consolidated MCP tools for a vault. Surface (10):
  * query-notes, create-note, update-note, delete-note, list-tags, update-tag,
- * delete-tag, find-path, vault-info.
+ * delete-tag, find-path, vault-info, prune-schema (admin).
  */
 export function generateMcpTools(store: Store): McpToolDef[] {
   const db: Database = (store as any).db;
@@ -102,6 +114,7 @@ export function generateMcpTools(store: Store): McpToolDef[] {
     // =====================================================================
     {
       name: "query-notes",
+      requiredVerb: "read",
       description: `Query notes. Returns notes matching the given filters.
 
 - **Single note**: pass \`id\` (accepts note ID or path, e.g., "Projects/README")
@@ -403,6 +416,7 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
     // =====================================================================
     {
       name: "create-note",
+      requiredVerb: "write",
       description: `Create one or more notes. Pass a single note's fields directly, or pass a \`notes\` array for batch creation. Each note accepts content, path, metadata, tags, links, and created_at.`,
       inputSchema: {
         type: "object",
@@ -518,6 +532,7 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
     // =====================================================================
     {
       name: "update-note",
+      requiredVerb: "write",
       description: `Update one or more notes. Accepts ID or path. Supports content, path, metadata updates plus tag and link mutations.
 
 - Three content-modification modes (mutually exclusive):
@@ -930,6 +945,14 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
     // =====================================================================
     {
       name: "delete-note",
+      // `write` — same destructive verb as update-note. Aaron's call
+      // 2026-05-27: "delete- in write; right now the only admin gated
+      // thing is tokens." Reserving `admin` for "operator-only
+      // capabilities" (token mgmt + future config writes). A future
+      // finer-grained model might split `vault:write:no-delete` for
+      // genuinely append-only callers — gating WITHIN write rather
+      // than promoting deletes out of it.
+      requiredVerb: "write",
       description: "Permanently delete a note and all its tags and links. Accepts ID or path.",
       inputSchema: {
         type: "object",
@@ -950,6 +973,7 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
     // =====================================================================
     {
       name: "list-tags",
+      requiredVerb: "read",
       description: `List tags with usage counts. Pass \`tag\` to get a single tag's full record (description, fields, relationships, parent_names, timestamps). Pass \`include_schema: true\` to include the full record for every tag.`,
       inputSchema: {
         type: "object",
@@ -1004,6 +1028,7 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
     // =====================================================================
     {
       name: "update-tag",
+      requiredVerb: "write",
       description: "Create or update a tag's identity row: description, indexed-field schemas, typed-link relationships, and hierarchy parents. If the tag doesn't exist, it's created. Fields are merged (new keys added, existing keys replaced); relationships and parent_names are replaced wholesale when provided. Pass null for fields/relationships/parent_names to clear that column. See parachute-patterns/patterns/tag-data-model.md.",
       inputSchema: {
         type: "object",
@@ -1049,12 +1074,23 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
         const tag = params.tag as string;
         const existing = tagSchemaOps.getTagRecord(db, tag);
 
-        // ---- fields: shallow-merge into existing (preserves prior keys).
-        const incomingFields = (params.fields as Record<string, TagFieldSchema> | undefined) ?? {};
-        const mergedFields: Record<string, TagFieldSchema> = {
-          ...(existing?.fields ?? {}),
-          ...incomingFields,
-        };
+        // ---- fields: three-way semantics, distinguishing `null` from
+        // `undefined` (do NOT collapse with `?? {}` — that silently turns an
+        // explicit clear-all into a no-op, the gitcoin orphaned-fields bug).
+        //   - undefined  → no change. Preserve every existing field; declare
+        //                  nothing new. mergedFields === existing.fields.
+        //   - null       → clear ALL of this tag's field schemas.
+        //                  mergedFields = {} so the diff below releases every
+        //                  indexed field this tag exclusively declares.
+        //   - object     → shallow-merge into existing (preserves prior keys).
+        const incomingFields =
+          params.fields === null || params.fields === undefined
+            ? {}
+            : (params.fields as Record<string, TagFieldSchema>);
+        const mergedFields: Record<string, TagFieldSchema> =
+          params.fields === null
+            ? {}
+            : { ...(existing?.fields ?? {}), ...incomingFields };
 
         // Validate cross-tag consistency on fields being (re)declared in this
         // call. `type` and `indexed` are global — all declarers must agree.
@@ -1121,6 +1157,12 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
           : (params.fields !== undefined ? null : undefined);
         const descriptionPatch =
           params.description === undefined ? undefined : (params.description as string);
+        // The indexed-field lifecycle (declareField for added indexed fields,
+        // releaseField for removed ones, with the co-declaration guard) is
+        // reconciled inside store.upsertTagRecord — the single chokepoint all
+        // callers (MCP, REST PUT /tags/:name, import) share — so it can't be
+        // bypassed. The cross-tag validation above stays here to surface a
+        // clean error before persisting. See the gitcoin orphaned-fields bug.
         const result = await store.upsertTagRecord(tag, {
           ...(descriptionPatch !== undefined ? { description: descriptionPatch } : {}),
           ...(fieldsPatch !== undefined ? { fields: fieldsPatch } : {}),
@@ -1128,28 +1170,6 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
           ...(parentNamesPatch !== undefined ? { parent_names: parentNamesPatch } : {}),
         });
 
-        // ---- Reconcile indexed-field lifecycle for this tag.
-        const priorIndexed = new Set(
-          Object.entries(existing?.fields ?? {})
-            .filter(([, v]) => v.indexed === true)
-            .map(([k]) => k),
-        );
-        const nextIndexed = new Set(
-          Object.entries(mergedFields)
-            .filter(([, v]) => v.indexed === true)
-            .map(([k]) => k),
-        );
-        for (const fieldName of nextIndexed) {
-          const spec = mergedFields[fieldName]!;
-          const mapped = indexedFieldOps.mapFieldType(spec.type)!;
-          indexedFieldOps.declareField(db, fieldName, mapped, tag);
-        }
-        for (const fieldName of priorIndexed) {
-          if (!nextIndexed.has(fieldName)) {
-            indexedFieldOps.releaseField(db, fieldName, tag);
-          }
-        }
-
         return result;
       },
     },
@@ -1159,6 +1179,10 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
     // =====================================================================
     {
       name: "delete-tag",
+      // `write` — Aaron's call 2026-05-27: admin reserved for token
+      // 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.",
       inputSchema: {
         type: "object",
@@ -1169,19 +1193,12 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
       },
       execute: async (params) => {
         const tag = params.tag as string;
-        // Release any indexed fields this tag declared before the row
-        // drops. releaseField drops the generated column + index when the
-        // declarer set empties.
-        const schema = tagSchemaOps.getTagSchema(db, tag);
-        if (schema?.fields) {
-          for (const [fieldName, spec] of Object.entries(schema.fields)) {
-            if (spec.indexed === true) {
-              indexedFieldOps.releaseField(db, fieldName, tag);
-            }
-          }
-        }
         // Drop the row outright — description/fields/relationships/parents
         // travel with it. (No more sidecar table to clear separately.)
+        // 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);
       },
     },
@@ -1191,6 +1208,7 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
     // =====================================================================
     {
       name: "find-path",
+      requiredVerb: "read",
       description: "Find the shortest path between two notes in the link graph. Accepts IDs or paths. Returns the chain of note IDs and relationships, or null if no path exists.",
       inputSchema: {
         type: "object",
@@ -1215,6 +1233,11 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
     // =====================================================================
     {
       name: "vault-info",
+      // `read` so vault:read callers can fetch stats. The
+      // description-update branch performs an inner write-check (see
+      // overrideVaultInfo in src/mcp-tools.ts) — do not promote this to
+      // `write` or read-only callers lose the stats projection.
+      requiredVerb: "read",
       description: "Get a comprehensive vault projection: name, description, tags-with-schemas (own + effective parents/fields per #270 inheritance), indexed metadata fields catalog, and query hints. Pass `include_stats: true` to add note/tag/link counts and the monthly distribution. Pass `description` to update the vault description (changes how AI agents behave in future sessions). Call this anytime mid-session to refresh schema context.",
       inputSchema: {
         type: "object",
@@ -1231,6 +1254,41 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
       },
     },
 
+    // =====================================================================
+    // 10. prune-schema — drop orphaned indexed-field columns
+    // =====================================================================
+    {
+      name: "prune-schema",
+      // `admin` — a destructive schema-maintenance op, same tier as
+      // manage-token. Operator-only; hidden from read/write sessions.
+      requiredVerb: "admin",
+      description:
+        "Drop orphaned indexed-field columns + indexes whose declaring tags no longer exist (the result of a deleted tag never releasing its fields). Dry-run by default — returns the drop plan without mutating. Pass `apply: true` to execute. A field co-declared by a still-live tag is never dropped; only the dead declarers are trimmed from its set. Generated columns are derived from notes.metadata JSON, so a drop loses only the index, never source data — declare the field again to rebuild it.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          apply: {
+            type: "boolean",
+            description: "Execute the prune. Default false (dry-run — report what would be dropped without changing anything).",
+          },
+        },
+      },
+      execute: async (params) => {
+        const apply = params.apply === true;
+        const plan = await store.pruneIndexedFields({ dryRun: !apply });
+        const dropped = plan.filter((p) => p.dropped);
+        const trimmed = plan.filter((p) => !p.dropped);
+        return {
+          dry_run: !apply,
+          fields_dropped: dropped.map((p) => ({ field: p.field, dead_declarers: p.deadDeclarers })),
+          fields_trimmed: trimmed.map((p) => ({ field: p.field, dead_declarers: p.deadDeclarers })),
+          summary: apply
+            ? `pruned ${dropped.length} orphaned field(s); trimmed dead declarers on ${trimmed.length} co-declared field(s)`
+            : `would prune ${dropped.length} orphaned field(s); would trim dead declarers on ${trimmed.length} co-declared field(s) — pass apply:true to execute`,
+        };
+      },
+    },
+
   ];
 }
 

package/core/src/notes.ts

@@ -18,6 +18,7 @@ import {
   type CursorPayload,
   type QueryHashInputs,
 } from "./cursor.js";
+import { releaseField } from "./indexed-fields.js";
 
 let idCounter = 0;
 
@@ -943,12 +944,35 @@ export function listTags(db: Database): { name: string; count: number }[] {
 }
 
 export function deleteTag(db: Database, name: string): { deleted: boolean; notes_untagged: number } {
-  const exists = db.prepare("SELECT 1 FROM tags WHERE name = ?").get(name);
-  if (!exists) return { deleted: false, notes_untagged: 0 };
+  const row = db.prepare("SELECT fields FROM tags WHERE name = ?").get(name) as
+    | { fields: string | null }
+    | undefined;
+  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);
+        }
+      }
+    } 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);
 

package/core/src/portable-md.test.ts

@@ -19,11 +19,13 @@
 
 import { describe, it, expect, beforeEach } from "bun:test";
 import { Database } from "bun:sqlite";
-import { mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync, existsSync, statSync } from "fs";
+import { mkdirSync, readFileSync, readdirSync, rmSync, symlinkSync, writeFileSync, existsSync, statSync } from "fs";
 import { join } from "path";
 import { tmpdir } from "os";
 
 import { SqliteStore } from "./store.js";
+import { getIndexedField } from "./indexed-fields.js";
+import { buildVaultProjection } from "./vault-projection.js";
 import {
   CaseCollisionError,
   emitYamlDoc,
@@ -33,6 +35,7 @@ import {
   parseFrontmatter,
   portableExportFilePath,
   probeCaseSensitive,
+  pruneOrphans,
   SIDECAR_DIR,
   NOTES_META_DIR,
   supportsInlineFrontmatter,
@@ -724,6 +727,56 @@ describe("importPortableVault", async () => {
     expect(schema!.description).toBe("A unit of work");
   });
 
+  // Fix 2 — import must re-declare indexed fields. The import writes
+  // tags.fields via upsertTagRecord but historically never materialized the
+  // backing generated columns + indexes, so a fresh import advertised
+  // `indexed: true` while queries silently full-scanned. Regression: export a
+  // vault with an indexed field → fresh import → the generated column + index
+  // exist and the field shows in the vault-info indexed_fields catalog.
+  it("re-declares indexed fields on import (column + index + vault-info catalog)", async () => {
+    await store.upsertTagRecord("project", {
+      fields: { status: { type: "string", indexed: true } },
+    });
+    await store.createNote("p", { id: "p", tags: ["project"], metadata: { status: "active" } });
+    const outDir = join(tmpBase, "out");
+    await exportVaultToDir(store, { outDir, exportedAt: "2026-05-13T00:00:00.000Z" });
+
+    const target = new SqliteStore(new Database(":memory:"));
+    const targetDb = target.db;
+    // Pre-condition: a fresh store has no backing column yet.
+    const colsBefore = (targetDb.prepare("PRAGMA table_xinfo(notes)").all() as { name: string }[]).map((r) => r.name);
+    expect(colsBefore).not.toContain("meta_status");
+
+    const stats = await importPortableVault(target, { inDir: outDir });
+    expect(stats.schemas_restored).toBe(1);
+    expect(stats.indexes_declared).toBe(1);
+
+    // The generated column + index now exist — same introspection vault-info
+    // uses to advertise the queryable-field catalog.
+    const colsAfter = (targetDb.prepare("PRAGMA table_xinfo(notes)").all() as { name: string }[]).map((r) => r.name);
+    expect(colsAfter).toContain("meta_status");
+    const idxs = (targetDb.prepare("SELECT name FROM sqlite_master WHERE type='index' AND tbl_name='notes'").all() as { name: string }[]).map((r) => r.name);
+    expect(idxs).toContain("idx_meta_status");
+    expect(getIndexedField(targetDb, "status")?.declarerTags).toEqual(["project"]);
+    // And vault-info lists it.
+    expect(buildVaultProjection(targetDb).indexed_fields.map((f) => f.name)).toContain("status");
+  });
+
+  it("dry-run import counts indexes_declared without materializing columns", async () => {
+    await store.upsertTagRecord("project", {
+      fields: { status: { type: "string", indexed: true } },
+    });
+    const outDir = join(tmpBase, "out");
+    await exportVaultToDir(store, { outDir, exportedAt: "2026-05-13T00:00:00.000Z" });
+
+    const target = new SqliteStore(new Database(":memory:"));
+    const stats = await importPortableVault(target, { inDir: outDir, dryRun: true });
+    expect(stats.indexes_declared).toBe(1);
+    // Dry-run touches nothing.
+    const cols = (target.db.prepare("PRAGMA table_xinfo(notes)").all() as { name: string }[]).map((r) => r.name);
+    expect(cols).not.toContain("meta_status");
+  });
+
   it("restores typed links (non-wikilink relationships)", async () => {
     await store.createNote("src body", { id: "src", path: "src" });
     await store.createNote("tgt body", { id: "tgt", path: "tgt" });
@@ -1799,3 +1852,253 @@ describe("case-collision detection (vault#327)", async () => {
     expect(stats.disambiguated_paths).toHaveLength(1);
   });
 });
+
+// ---------------------------------------------------------------------------
+// pruneOrphans (vault#382 — event-driven mirror delete propagation)
+// ---------------------------------------------------------------------------
+
+describe("pruneOrphans", async () => {
+  let tmpBase: string;
+  beforeEach(() => {
+    tmpBase = join(tmpdir(), `parachute-prune-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
+    mkdirSync(tmpBase, { recursive: true });
+  });
+
+  it("no-op on non-existent directory", () => {
+    const stats = pruneOrphans({
+      outDir: join(tmpBase, "doesnt-exist"),
+      validNoteIds: new Set(),
+      validTagNames: new Set(),
+      validAttachmentIds: new Set(),
+    });
+    expect(stats.notes_removed).toBe(0);
+    expect(stats.unparseable_files).toHaveLength(0);
+  });
+
+  it("removes orphaned note .md file", async () => {
+    const outDir = join(tmpBase, "orphan-note");
+    // First do a real export so the structure is realistic.
+    const db = new Database(":memory:");
+    const store = new SqliteStore(db);
+    await store.createNote("alive", { id: "01HFAA", path: "alive" });
+    await store.createNote("doomed", { id: "01HFBB", path: "doomed" });
+    await exportVaultToDir(store, { outDir, vaultName: "t", exportedAt: "2026-01-01T00:00:00.000Z" });
+    expect(existsSync(join(outDir, "alive.md"))).toBe(true);
+    expect(existsSync(join(outDir, "doomed.md"))).toBe(true);
+
+    // Now prune with only "alive" in the valid set.
+    const stats = pruneOrphans({
+      outDir,
+      validNoteIds: new Set(["01HFAA"]),
+      validTagNames: new Set(),
+      validAttachmentIds: new Set(),
+    });
+    expect(stats.notes_removed).toBe(1);
+    expect(existsSync(join(outDir, "alive.md"))).toBe(true);
+    expect(existsSync(join(outDir, "doomed.md"))).toBe(false);
+  });
+
+  it("removes orphaned schema sidecar", async () => {
+    const outDir = join(tmpBase, "orphan-schema");
+    const db = new Database(":memory:");
+    const store = new SqliteStore(db);
+    await store.upsertTagRecord("alive-tag", { description: "stays" });
+    await store.upsertTagRecord("doomed-tag", { description: "goes" });
+    await exportVaultToDir(store, { outDir, vaultName: "t", exportedAt: "2026-01-01T00:00:00.000Z" });
+    const schemasDir = join(outDir, SIDECAR_DIR, "schemas");
+    expect(existsSync(join(schemasDir, "alive-tag.yaml"))).toBe(true);
+    expect(existsSync(join(schemasDir, "doomed-tag.yaml"))).toBe(true);
+
+    const stats = pruneOrphans({
+      outDir,
+      validNoteIds: new Set(),
+      validTagNames: new Set(["alive-tag"]),
+      validAttachmentIds: new Set(),
+    });
+    expect(stats.schemas_removed).toBe(1);
+    expect(existsSync(join(schemasDir, "alive-tag.yaml"))).toBe(true);
+    expect(existsSync(join(schemasDir, "doomed-tag.yaml"))).toBe(false);
+  });
+
+  it("removes orphaned attachment directories", async () => {
+    const outDir = join(tmpBase, "orphan-att");
+    // Build the export structure by hand (attachment binaries need
+    // assetsDir wiring; cheaper to just create the dirs).
+    const attachmentsDir = join(outDir, SIDECAR_DIR, "attachments");
+    mkdirSync(attachmentsDir, { recursive: true });
+    mkdirSync(join(attachmentsDir, "att-alive"), { recursive: true });
+    writeFileSync(join(attachmentsDir, "att-alive", "voice.m4a"), "");
+    mkdirSync(join(attachmentsDir, "att-doomed"), { recursive: true });
+    writeFileSync(join(attachmentsDir, "att-doomed", "voice.m4a"), "");
+    // Need .parachute/vault.yaml so the structure is recognized (cheap to fake)
+    writeFileSync(join(outDir, SIDECAR_DIR, "vault.yaml"), "name: t\n");
+
+    const stats = pruneOrphans({
+      outDir,
+      validNoteIds: new Set(),
+      validTagNames: new Set(),
+      validAttachmentIds: new Set(["att-alive"]),
+    });
+    expect(stats.attachment_dirs_removed).toBe(1);
+    expect(existsSync(join(attachmentsDir, "att-alive"))).toBe(true);
+    expect(existsSync(join(attachmentsDir, "att-doomed"))).toBe(false);
+  });
+
+  it("skips unparseable .md files without crashing", async () => {
+    const outDir = join(tmpBase, "unparseable");
+    mkdirSync(outDir, { recursive: true });
+    writeFileSync(join(outDir, "no-frontmatter.md"), "just content, no frontmatter\n");
+    writeFileSync(join(outDir, "garbage.md"), "---\nnot-real-yaml\n");
+    const stats = pruneOrphans({
+      outDir,
+      validNoteIds: new Set(),
+      validTagNames: new Set(),
+      validAttachmentIds: new Set(),
+    });
+    // Both files lacked an `id`, so we record them but don't remove.
+    expect(stats.notes_removed).toBe(0);
+    expect(stats.unparseable_files.length).toBeGreaterThanOrEqual(2);
+    expect(existsSync(join(outDir, "no-frontmatter.md"))).toBe(true);
+    expect(existsSync(join(outDir, "garbage.md"))).toBe(true);
+  });
+
+  it("preserves all files when everything is in the valid sets", async () => {
+    const outDir = join(tmpBase, "happy-path");
+    const db = new Database(":memory:");
+    const store = new SqliteStore(db);
+    const a = await store.createNote("a", { path: "a" });
+    const b = await store.createNote("b", { path: "b" });
+    await store.upsertTagRecord("tag1", { description: "x" });
+    await exportVaultToDir(store, { outDir, vaultName: "t", exportedAt: "2026-01-01T00:00:00.000Z" });
+    const stats = pruneOrphans({
+      outDir,
+      validNoteIds: new Set([a.id, b.id]),
+      validTagNames: new Set(["tag1"]),
+      validAttachmentIds: new Set(),
+    });
+    expect(stats.notes_removed).toBe(0);
+    expect(stats.schemas_removed).toBe(0);
+    expect(stats.attachment_dirs_removed).toBe(0);
+    expect(existsSync(join(outDir, "a.md"))).toBe(true);
+    expect(existsSync(join(outDir, "b.md"))).toBe(true);
+  });
+
+  it("removes orphan note + corresponding notes-meta sidecar for csv/yaml notes", async () => {
+    // For non-frontmatter extensions, the sidecar lives at
+    // .parachute/notes-meta/<id>.yaml. Pruning the note should remove
+    // both files.
+    const outDir = join(tmpBase, "orphan-csv");
+    const db = new Database(":memory:");
+    const store = new SqliteStore(db);
+    await store.createNote("col1,col2\n1,2\n", {
+      id: "01CSV-DEL",
+      path: "data/table",
+      extension: "csv",
+    });
+    await exportVaultToDir(store, { outDir, vaultName: "t", exportedAt: "2026-01-01T00:00:00.000Z" });
+    const contentFile = join(outDir, "data", "table.csv");
+    const sidecarFile = join(outDir, SIDECAR_DIR, "notes-meta", "01CSV-DEL.yaml");
+    expect(existsSync(contentFile)).toBe(true);
+    expect(existsSync(sidecarFile)).toBe(true);
+
+    const stats = pruneOrphans({
+      outDir,
+      validNoteIds: new Set(), // doom it
+      validTagNames: new Set(),
+      validAttachmentIds: new Set(),
+    });
+    expect(stats.notes_removed).toBe(1);
+    expect(stats.sidecars_removed).toBeGreaterThanOrEqual(1);
+    expect(existsSync(contentFile)).toBe(false);
+    expect(existsSync(sidecarFile)).toBe(false);
+  });
+
+  // Reviewer-flagged regression on vault#382 Critical #2 — pruneOrphans
+  // walks via statSync (follows symlinks); without the safeRm guard a
+  // symlink inside the mirror pointing OUTSIDE outDir would resurface
+  // its target's files as orphans and rmSync would happily delete them
+  // off-tree. The guard resolves each candidate and refuses anything
+  // not under outDir; refusals get recorded in `unparseable_files` so
+  // an operator can see what was skipped.
+  it("refuses to delete files reached via a symlink pointing outside outDir", async () => {
+    const outDir = join(tmpBase, "symlink-attack");
+    const outside = join(tmpBase, "outside");
+    mkdirSync(outside, { recursive: true });
+    mkdirSync(outDir, { recursive: true });
+    // A real, sensitive file in `outside/` we don't want pruneOrphans
+    // to touch under any circumstance.
+    const externalFile = join(outside, "do-not-touch.md");
+    writeFileSync(externalFile, "---\nid: 01EXTERNAL\n---\nimportant\n");
+    // A symlink inside outDir pointing at outside/ — walkContentFiles
+    // would normally surface outside/do-not-touch.md as a candidate.
+    try {
+      symlinkSync(outside, join(outDir, "via-link"));
+    } catch {
+      // Some CI sandboxes refuse symlink creation. Skip the test in
+      // that case rather than fail spuriously.
+      return;
+    }
+
+    const stats = pruneOrphans({
+      outDir,
+      validNoteIds: new Set(), // doom every id we see
+      validTagNames: new Set(),
+      validAttachmentIds: new Set(),
+    });
+
+    // Critical assertion: the external file MUST survive.
+    expect(existsSync(externalFile)).toBe(true);
+    // And the refusal MUST be recorded so the operator sees it.
+    expect(
+      stats.unparseable_files.some(
+        (u) => u.path.includes("via-link") || u.reason.includes("outside"),
+      ),
+    ).toBe(true);
+  });
+
+  // Reviewer-flagged regression on vault#382 Critical #1 — pruneOrphans
+  // builds `validTagNames` from ALL tag-table rows in mirror-deps.ts.
+  // After `deleteTagSchema(t)` the schema fields are cleared but the
+  // tag row persists with the bare name, so the sidecar lingers
+  // forever. The fix routes validTagNames through `hasSchemaContent`
+  // before passing into pruneOrphans, and exports the predicate so
+  // mirror-deps can reuse the single source of truth.
+  it("considers a schema-content-free tag the same as a deleted tag for sidecar pruning", async () => {
+    const outDir = join(tmpBase, "stale-schema");
+    const db = new Database(":memory:");
+    const store = new SqliteStore(db);
+    await store.upsertTagRecord("bare", {}); // bare-name only
+    await store.upsertTagRecord("with-schema", { description: "real" });
+    await exportVaultToDir(store, {
+      outDir,
+      vaultName: "t",
+      exportedAt: "2026-01-01T00:00:00.000Z",
+    });
+    const schemasDir = join(outDir, SIDECAR_DIR, "schemas");
+    // The bare tag SHOULDN'T have a sidecar; the schema-bearing one
+    // SHOULD. This confirms the export-writer's contract before the
+    // prune step.
+    expect(existsSync(join(schemasDir, "bare.yaml"))).toBe(false);
+    expect(existsSync(join(schemasDir, "with-schema.yaml"))).toBe(true);
+
+    // Now seed a stale sidecar for `bare` (simulating "the operator
+    // previously had a schema for `bare`, then cleared it via
+    // `deleteTagSchema`"). pruneOrphans should remove this iff the
+    // caller correctly filtered validTagNames by hasSchemaContent.
+    writeFileSync(join(schemasDir, "bare.yaml"), 'name: "bare"\ndescription: "stale"\n');
+    expect(existsSync(join(schemasDir, "bare.yaml"))).toBe(true);
+
+    // Filtered set — only `with-schema` has hasSchemaContent === true.
+    const validTagNames = new Set(["with-schema"]);
+    const stats = pruneOrphans({
+      outDir,
+      validNoteIds: new Set(),
+      validTagNames,
+      validAttachmentIds: new Set(),
+    });
+
+    expect(stats.schemas_removed).toBe(1);
+    expect(existsSync(join(schemasDir, "bare.yaml"))).toBe(false);
+    expect(existsSync(join(schemasDir, "with-schema.yaml"))).toBe(true);
+  });
+});