@openparachute/vault 0.4.8 → 0.4.9-rc.10

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

@@ -19,7 +19,7 @@
 
 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";
 
@@ -33,6 +33,7 @@ import {
   parseFrontmatter,
   portableExportFilePath,
   probeCaseSensitive,
+  pruneOrphans,
   SIDECAR_DIR,
   NOTES_META_DIR,
   supportsInlineFrontmatter,
@@ -1799,3 +1800,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);
+  });
+});

package/core/src/portable-md.ts

@@ -72,7 +72,7 @@
  * See vault#308.
  */
 
-import { readdirSync, readFileSync, statSync, mkdirSync, writeFileSync, copyFileSync, existsSync, rmSync } from "fs";
+import { readdirSync, readFileSync, realpathSync, statSync, mkdirSync, writeFileSync, copyFileSync, existsSync, rmSync } from "fs";
 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";
@@ -1001,7 +1001,375 @@ export async function exportVaultToDir(
   };
 }
 
-function hasSchemaContent(tag: TagRecord): boolean {
+// ---------------------------------------------------------------------------
+// Orphan sweep — for git-mirror's delete propagation
+// ---------------------------------------------------------------------------
+
+/**
+ * Result of a `pruneOrphans` pass.
+ */
+export interface PruneOrphansStats {
+  /** Note content files removed (frontmatter id not in `validNoteIds`). */
+  notes_removed: number;
+  /** Sidecar metadata files removed (under `.parachute/notes-meta/`). */
+  sidecars_removed: number;
+  /** Schema sidecars removed (under `.parachute/schemas/`). */
+  schemas_removed: number;
+  /** Attachment directories removed (under `.parachute/attachments/`). */
+  attachment_dirs_removed: number;
+  /**
+   * Files we couldn't parse / classify. Surfaced for operator audit;
+   * the sweep doesn't touch them. Empty when everything classified
+   * cleanly.
+   */
+  unparseable_files: Array<{ path: string; reason: string }>;
+}
+
+/**
+ * Options for the orphan-sweep pass. Run periodically (the mirror manager
+ * arms a safety-net poll, default 1h) and after operator-visible deletions
+ * (the mirror manager's targeted-deletion fast path also calls this for the
+ * touched-set).
+ *
+ * The sweep is the bookkeeping cousin of the event-driven fast path: events
+ * cover the common case (a single note deletion fires "deleted" → mirror
+ * removes that file); the sweep covers anything the fast path missed
+ * (direct SQL writes, app crashes between dispatch and handler, restart
+ * gaps).
+ */
+export interface PruneOrphansOptions {
+  /** Directory to sweep — same shape as an `exportVaultToDir` outDir. */
+  outDir: string;
+  /** Note IDs that should be kept (everything else under the export gets removed). */
+  validNoteIds: Set<string>;
+  /** Tag names that should be kept (other schema sidecars under `.parachute/schemas/` get removed). */
+  validTagNames: Set<string>;
+  /** Attachment IDs that should be kept (other dirs under `.parachute/attachments/` get removed). */
+  validAttachmentIds: Set<string>;
+  /**
+   * Override `extension`-based content-file extension recognition. The
+   * default treats `.md` and `.mdx` as having inline frontmatter (with
+   * `id:` reachable via the file head); everything else needs a sidecar
+   * lookup to know what id owns it.
+   */
+  supportsInlineFrontmatter?: (ext: string) => boolean;
+}
+
+/**
+ * Sweep the export directory for files belonging to notes / tags /
+ * attachments that no longer exist in the vault. Removes them so the
+ * mirror's `git diff` reflects what vault actually has.
+ *
+ * Strategy:
+ *   1. Walk content files. For each `.md` / `.mdx`, parse the frontmatter
+ *      `id` and compare against `validNoteIds`. Mismatch → remove the
+ *      file. Files we can't parse are recorded in `unparseable_files`
+ *      and left alone (best-effort, no destructive guesses).
+ *   2. For non-inline-frontmatter extensions (`.csv`, `.yaml`, etc.),
+ *      check the matching `.parachute/notes-meta/<id>.yaml` sidecar — the
+ *      sidecar carries the canonical `id` + `path` + `extension` triple.
+ *      An orphaned sidecar (no matching content file) is also removed,
+ *      and an orphaned content file (no matching sidecar) without a
+ *      parseable frontmatter is left as unparseable.
+ *   3. Walk `.parachute/schemas/`. Each file is `<tag>.yaml` (after
+ *      filename sanitization). Parse the `name:` field; compare against
+ *      `validTagNames`. Mismatch → remove.
+ *   4. Walk `.parachute/attachments/`. Each subdir name IS the
+ *      attachment id (per `exportVaultToDir`'s layout). Compare against
+ *      `validAttachmentIds`. Mismatch → recursive remove.
+ *
+ * Returns counts so callers can log + decide whether to commit.
+ *
+ * Safe to call on a directory that's never been exported to (returns
+ * zero counts; doesn't create anything).
+ */
+export function pruneOrphans(opts: PruneOrphansOptions): PruneOrphansStats {
+  const stats: PruneOrphansStats = {
+    notes_removed: 0,
+    sidecars_removed: 0,
+    schemas_removed: 0,
+    attachment_dirs_removed: 0,
+    unparseable_files: [],
+  };
+
+  const outDir = opts.outDir;
+  if (!existsSync(outDir)) return stats;
+
+  const supportsInline = opts.supportsInlineFrontmatter ?? supportsInlineFrontmatter;
+  const sidecarRoot = join(outDir, SIDECAR_DIR);
+  const notesMetaRoot = join(sidecarRoot, NOTES_META_DIR);
+  const schemasRoot = join(sidecarRoot, "schemas");
+  const attachmentsRoot = join(sidecarRoot, "attachments");
+
+  // Path-traversal guard. `walkContentFiles` uses `statSync` which
+  // follows symlinks — a symlink inside the mirror pointing OUTSIDE
+  // `outDir` would resurface its target's files in the prune sweep,
+  // and a bare `rmSync(filepath)` would delete them off-tree. Every
+  // deletion in this function routes through `safeRm`, which calls
+  // `realpathSync` (resolves through symlinks, unlike syntactic-only
+  // `path.resolve`) and refuses to delete anything that isn't `outDir`
+  // or beneath it after symlink resolution. Refusals get recorded in
+  // `unparseable_files` so an operator can see what was skipped.
+  // Reviewer-flagged on vault#382 (Critical #2).
+  const outDirReal = realpathSync(outDir);
+  const safeRm = (
+    candidate: string,
+    onSuccess: () => void,
+    options: { recursive?: boolean } = {},
+  ): void => {
+    let real: string;
+    try {
+      real = realpathSync(candidate);
+    } catch (err) {
+      // realpathSync throws if the path doesn't exist or is unreadable.
+      // Don't delete what we can't fully resolve.
+      stats.unparseable_files.push({
+        path: candidate,
+        reason: `realpath failed: ${(err as Error).message ?? err}`,
+      });
+      return;
+    }
+    if (!isWithinDir(real, outDirReal)) {
+      stats.unparseable_files.push({
+        path: candidate,
+        reason: "real path resolved outside mirror outDir — refusing to delete (symlink?)",
+      });
+      return;
+    }
+    try {
+      // Delete via the resolved real path; never via the unresolved
+      // candidate (which could route through a symlink we already
+      // determined would escape).
+      rmSync(real, { force: true, recursive: options.recursive ?? false });
+      onSuccess();
+    } catch (err) {
+      stats.unparseable_files.push({
+        path: candidate,
+        reason: `unlink failed: ${(err as Error).message ?? err}`,
+      });
+    }
+  };
+
+  // ---- 1 + 2. Notes + sidecars ----
+  //
+  // First pass: build the sidecar id → { path, extension } map so we can
+  // resolve non-inline-frontmatter content files via their sidecar.
+  // Sidecars whose claimed (path, extension) doesn't map to an existing
+  // content file are tracked as "orphaned sidecar" candidates.
+  const sidecarById = new Map<string, { path: string | null; extension: string | null }>();
+  const sidecarFilesById = new Map<string, string>(); // id → absolute filepath
+  if (existsSync(notesMetaRoot)) {
+    try {
+      for (const entry of readdirSync(notesMetaRoot)) {
+        if (!entry.endsWith(".yaml")) continue;
+        const id = entry.slice(0, -5);
+        const full = join(notesMetaRoot, entry);
+        sidecarFilesById.set(id, full);
+        try {
+          const text = readFileSync(full, "utf-8");
+          const { frontmatter } = parseFrontmatter(`---\n${text}---\n`);
+          sidecarById.set(id, {
+            path: typeof frontmatter.path === "string" ? (frontmatter.path as string) : null,
+            extension: typeof frontmatter.extension === "string" ? (frontmatter.extension as string) : null,
+          });
+        } catch (err) {
+          stats.unparseable_files.push({
+            path: full,
+            reason: `failed to parse sidecar: ${(err as Error).message ?? err}`,
+          });
+        }
+      }
+    } catch (err) {
+      // Notes-meta dir read-error is non-fatal — record + carry on.
+      stats.unparseable_files.push({
+        path: notesMetaRoot,
+        reason: `notes-meta walk failed: ${(err as Error).message ?? err}`,
+      });
+    }
+  }
+
+  // Now walk content files (everything outside the .parachute sidecar).
+  const contentFiles = walkContentFiles(outDir);
+  // Track which sidecars matched a content file so we can also remove
+  // orphaned sidecars (sidecar present but content file gone).
+  const pairedSidecarIds = new Set<string>();
+  for (const filepath of contentFiles) {
+    const ext = extname(filepath).slice(1).toLowerCase();
+    if (supportsInline(ext)) {
+      // Parse frontmatter, read id.
+      try {
+        const raw = readFileSync(filepath, "utf-8");
+        const { frontmatter } = parseFrontmatter(raw);
+        const id = typeof frontmatter.id === "string" ? (frontmatter.id as string) : null;
+        if (!id) {
+          stats.unparseable_files.push({
+            path: filepath,
+            reason: "no `id` in frontmatter",
+          });
+          continue;
+        }
+        if (!opts.validNoteIds.has(id)) {
+          safeRm(filepath, () => {
+            stats.notes_removed++;
+          });
+        }
+      } catch (err) {
+        stats.unparseable_files.push({
+          path: filepath,
+          reason: `read failed: ${(err as Error).message ?? err}`,
+        });
+      }
+    } else {
+      // Sidecar-required extension. Find the matching sidecar by
+      // (path, extension) — sidecars are keyed by id, so we sweep the
+      // sidecarById map.
+      const relPath = relative(outDir, filepath).replace(/\\/g, "/");
+      // Strip extension to get the canonical path stored in the sidecar
+      // (vault paths don't carry extensions).
+      const pathNoExt = relPath.slice(0, -(ext.length + 1));
+      let foundId: string | null = null;
+      for (const [id, info] of sidecarById.entries()) {
+        if (
+          info.path === pathNoExt &&
+          (info.extension ?? "md").toLowerCase() === ext
+        ) {
+          foundId = id;
+          break;
+        }
+      }
+      if (!foundId) {
+        // Content file with no sidecar — can't tell which note owns it.
+        // Conservative: leave alone, record as unparseable.
+        stats.unparseable_files.push({
+          path: filepath,
+          reason: "no sidecar metadata could be matched by (path, extension)",
+        });
+        continue;
+      }
+      pairedSidecarIds.add(foundId);
+      if (!opts.validNoteIds.has(foundId)) {
+        // Note is orphaned — remove both content and sidecar.
+        safeRm(filepath, () => {
+          stats.notes_removed++;
+        });
+        const sidecarPath = sidecarFilesById.get(foundId);
+        if (sidecarPath) {
+          safeRm(sidecarPath, () => {
+            stats.sidecars_removed++;
+          });
+        }
+      }
+    }
+  }
+
+  // Sweep up orphaned sidecars (sidecar exists but no content file
+  // matched OR sidecar's id isn't in validNoteIds).
+  for (const [id, sidecarPath] of sidecarFilesById.entries()) {
+    if (opts.validNoteIds.has(id) && pairedSidecarIds.has(id)) continue;
+    if (opts.validNoteIds.has(id) && !pairedSidecarIds.has(id)) {
+      // Sidecar refers to a valid note but the content file is gone —
+      // that's an inconsistency, not an orphan. Leave the sidecar so
+      // the next export can rewrite the content file alongside it.
+      continue;
+    }
+    safeRm(sidecarPath, () => {
+      stats.sidecars_removed++;
+    });
+  }
+
+  // ---- 3. Schema sidecars ----
+  if (existsSync(schemasRoot)) {
+    try {
+      for (const entry of readdirSync(schemasRoot)) {
+        if (!entry.endsWith(".yaml")) continue;
+        const full = join(schemasRoot, entry);
+        try {
+          const text = readFileSync(full, "utf-8");
+          const { frontmatter } = parseFrontmatter(`---\n${text}---\n`);
+          const name = typeof frontmatter.name === "string" ? (frontmatter.name as string) : null;
+          if (!name) {
+            // Fall back to filename — sanitizeTagFilename replaces `/`
+            // with `__`, so reverse for the lookup.
+            const fromFilename = entry.slice(0, -5).replace(/__/g, "/");
+            if (!opts.validTagNames.has(fromFilename)) {
+              safeRm(full, () => {
+                stats.schemas_removed++;
+              });
+            }
+            continue;
+          }
+          if (!opts.validTagNames.has(name)) {
+            safeRm(full, () => {
+              stats.schemas_removed++;
+            });
+          }
+        } catch (err) {
+          stats.unparseable_files.push({
+            path: full,
+            reason: `schema sweep failed: ${(err as Error).message ?? err}`,
+          });
+        }
+      }
+    } catch (err) {
+      stats.unparseable_files.push({
+        path: schemasRoot,
+        reason: `schemas walk failed: ${(err as Error).message ?? err}`,
+      });
+    }
+  }
+
+  // ---- 4. Attachment directories ----
+  if (existsSync(attachmentsRoot)) {
+    try {
+      for (const entry of readdirSync(attachmentsRoot)) {
+        const full = join(attachmentsRoot, entry);
+        let stat;
+        try {
+          stat = statSync(full);
+        } catch (err) {
+          stats.unparseable_files.push({
+            path: full,
+            reason: `stat failed: ${(err as Error).message ?? err}`,
+          });
+          continue;
+        }
+        if (!stat.isDirectory()) continue;
+        // The directory name IS the attachment id (per the export layout).
+        if (!opts.validAttachmentIds.has(entry)) {
+          safeRm(
+            full,
+            () => {
+              stats.attachment_dirs_removed++;
+            },
+            { recursive: true },
+          );
+        }
+      }
+    } catch (err) {
+      stats.unparseable_files.push({
+        path: attachmentsRoot,
+        reason: `attachments walk failed: ${(err as Error).message ?? err}`,
+      });
+    }
+  }
+
+  return stats;
+}
+
+/**
+ * True iff the tag carries content the export writer will emit as a
+ * schema sidecar (`.parachute/schemas/<tag>.yaml`). Bare-name tags
+ * (the `tags` table has a row but description/fields/relationships/
+ * parents are all empty) get no sidecar — and crucially, after
+ * `deleteTagSchema` clears those fields the row persists with the
+ * bare name. Callers building the `validTagNames` set for
+ * `pruneOrphans` MUST filter through this predicate, otherwise the
+ * stale sidecar lingers indefinitely.
+ *
+ * Reviewer-flagged on vault#382: without this filter, a cleared
+ * schema's sidecar never gets pruned.
+ */
+export function hasSchemaContent(tag: TagRecord): boolean {
   if (tag.description !== undefined && tag.description.length > 0) return true;
   if (tag.fields && Object.keys(tag.fields).length > 0) return true;
   if (tag.relationships && Object.keys(tag.relationships).length > 0) return true;