@openparachute/vault 0.7.1 → 0.7.2-rc.4

package/core/src/mcp.ts

@@ -2,7 +2,7 @@ import { Database } from "bun:sqlite";
 import type { Store, Note, QueryOpts } from "./types.js";
 import { transactionAsync } from "./txn.js";
 import * as noteOps from "./notes.js";
-import { filterMetadata, MAX_BATCH_SIZE, validateExtension, ExtensionValidationError } from "./notes.js";
+import { filterMetadata, MAX_BATCH_SIZE, validateExtension, ExtensionValidationError, validatePath } from "./notes.js";
 import { normalizePath } from "./paths.js";
 import { QueryError } from "./query-operators.js";
 import { TAG_EXPAND_MODES, stripTagHash, suggestSimilarTag, type TagExpandMode } from "./tag-hierarchy.js";
@@ -1269,6 +1269,10 @@ A note's response carries \`existed\` (true/false) whenever ITS \`if_exists\` wa
             const extension = item.extension !== undefined
               ? validateExtension(item.extension)
               : undefined;
+            // Reject NUL / `..` paths at the write surface (vault#589 / FIX 2).
+            // Throws inside the batch transaction — rolls it back, same as a
+            // path conflict; mcp-http's generic error_type mapping → clean 400.
+            validatePath(item.path);
             const effectiveExtension = extension ?? "md";
             const ifExists = (item.if_exists as string | undefined) ?? "error";
             const upsertMode = ifExists === "ignore" || ifExists === "update" || ifExists === "replace";
@@ -1719,6 +1723,8 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
                 const createExt = item.extension !== undefined
                   ? validateExtension(item.extension)
                   : undefined;
+                // Reject NUL / `..` paths at the write surface (vault#589 / FIX 2).
+                validatePath(explicitPath ?? (idLooksLikePath ? idOrPath : undefined));
                 const createOpts: Parameters<Store["createNote"]>[1] = {
                   ...(idLooksLikePath ? { path: explicitPath ?? idOrPath } : { id: idOrPath, ...(explicitPath !== undefined ? { path: explicitPath } : {}) }),
                   ...(item.tags && Array.isArray((item.tags as any).add)
@@ -1895,7 +1901,11 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
               if (item.append !== undefined) updates.append = item.append;
               if (item.prepend !== undefined) updates.prepend = item.prepend;
             }
-            if (item.path !== undefined) updates.path = item.path;
+            if (item.path !== undefined) {
+              // Reject NUL / `..` paths at the write surface (vault#589 / FIX 2).
+              validatePath(item.path);
+              updates.path = item.path;
+            }
             if (item.extension !== undefined) {
               updates.extension = validateExtension(item.extension);
             }

package/core/src/notes.ts

@@ -14,8 +14,7 @@ import {
   computeQueryHash,
   decodeCursor,
   encodeCursor,
-  isoToMillis,
-  millisToIso,
+  timestampToMs,
   type CursorPayload,
   type QueryHashInputs,
 } from "./cursor.js";
@@ -115,10 +114,18 @@ export function createNote(
   // value. Hook-style writes with `skipUpdatedAt` preserve this; real user
   // edits bump it strictly upward, so `updated_at > created_at` still means
   // "user-touched since creation."
+  //
+  // `updated_at_ms` (vault#586) is the integer keyset-ordering mirror of
+  // `updated_at`. Derived from the SAME `createdAt` value with the UTC-correct
+  // `timestampToMs`; a `null` (unparseable caller-supplied `created_at`, e.g.
+  // via `createNoteRaw` during import) falls back to wall-clock now so a fresh
+  // row never lands with a NULL keyset key. Import's `restoreNoteTimestamps`
+  // overwrites both columns from the exported bytes immediately after.
+  const updatedAtMs = timestampToMs(createdAt) ?? Date.now();
   try {
     db.prepare(
-      `INSERT INTO notes (id, content, path, metadata, created_at, updated_at, extension, created_by, created_via, last_updated_by, last_updated_via) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
-    ).run(id, content, path, metadata, createdAt, createdAt, extension, actor, via, actor, via);
+      `INSERT INTO notes (id, content, path, metadata, created_at, updated_at, updated_at_ms, extension, created_by, created_via, last_updated_by, last_updated_via) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    ).run(id, content, path, metadata, createdAt, createdAt, updatedAtMs, extension, actor, via, actor, via);
   } catch (err) {
     if (path !== null && isPathUniqueError(err)) {
       throw new PathConflictError(path);
@@ -466,6 +473,63 @@ export function validateExtension(extension: unknown): string {
   return extension;
 }
 
+/**
+ * Thrown by {@link validatePath} when a caller-supplied note `path` can never
+ * round-trip safely (vault#589 / FIX 2). Carries a stable `error_type`
+ * (`invalid_path`) so REST's catch and the generic MCP domain-error mapping
+ * (`src/mcp-http.ts`) both surface a clean 400 — same shape rule as
+ * `ExtensionValidationError`.
+ */
+export class PathValidationError extends Error {
+  code = "INVALID_PATH" as const;
+  error_type = "invalid_path" as const;
+  path: string;
+  reason: string;
+
+  constructor(path: string, reason: string) {
+    super(`invalid_path: "${path}" ${reason}`);
+    this.name = "PathValidationError";
+    this.path = path;
+    this.reason = reason;
+  }
+}
+
+/**
+ * Reject a caller-supplied note path that can never round-trip safely
+ * (vault#589 / FIX 2). Two rules, both enforced at the WRITE surface only
+ * (REST + MCP create/update, exactly where `validateExtension` sits):
+ *
+ *   1. **No NUL byte** — never valid in a filename. A NUL-in-path note keeps
+ *      its resolved target inside the export root (so it slips the traversal
+ *      guard), then uncaught-throws `writeFileSync`, aborting the ENTIRE vault
+ *      export for everyone. Rejecting NUL at write is the primary fix; the
+ *      export sink's per-file try/catch (portable-md.ts) is the belt for rows
+ *      that predate this guard.
+ *   2. **No `..` path segment** — traversal-shaped. Export guard-skips such a
+ *      note (silently un-round-trippable) and it has no legitimate use as a
+ *      vault note path.
+ *
+ * A `null`/empty-after-normalize path is fine — notes need no path. Reads /
+ * queries never call this, so a lookup by a `..`/NUL path degrades to
+ * not-found rather than throwing. The Store itself still trusts internal /
+ * importer writes (mirrors the `validateExtension` split). Throws
+ * `PathValidationError`.
+ */
+export function validatePath(path: unknown): void {
+  if (path === null || path === undefined) return;
+  if (typeof path !== "string") return; // non-string: not a path; caller's shape check owns it
+  // NUL check on the RAW value — `normalizePath` strips NUL, so this must run
+  // before normalization to actually reject rather than silently clean.
+  if (path.includes("\0")) {
+    throw new PathValidationError(path, "contains a NUL byte");
+  }
+  const normalized = normalizePath(path);
+  if (normalized === null) return;
+  if (normalized.split("/").some((seg) => seg === "..")) {
+    throw new PathValidationError(path, "contains a '..' path segment (path traversal)");
+  }
+}
+
 /**
  * Match bun:sqlite's UNIQUE-constraint error on the notes path index.
  * Post-vault#328 the unique index is composite `(path, extension)`, so
@@ -542,7 +606,9 @@ export function updateNote(
   // and path has been removed.
 
   const sets: string[] = [];
-  const values: (string | null)[] = [];
+  // `updated_at_ms` binds as a number (INTEGER column), so the value list
+  // carries numbers alongside strings/nulls (vault#586).
+  const values: (string | number | null)[] = [];
 
   // Hooks and other machine-level writers pass `skipUpdatedAt: true` so
   // their metadata markers don't look like user activity. See issue #44.
@@ -560,6 +626,12 @@ export function updateNote(
     }
     sets.push("updated_at = ?");
     values.push(now);
+    // `updated_at_ms` (vault#586) rides the SAME gate as `updated_at` — the
+    // integer keyset-ordering mirror must move in lockstep with the string.
+    // `now` is canonical `.toISOString()`, so `timestampToMs` never returns
+    // null here; the fallback is belt-and-suspenders.
+    sets.push("updated_at_ms = ?");
+    values.push(timestampToMs(now) ?? Date.now());
 
     // Write-attribution (vault#298): the most-recent-write columns ride the
     // SAME gate as `updated_at`. A `skipUpdatedAt` machine write doesn't bump
@@ -1100,6 +1172,11 @@ function buildFilterConditions(db: Database, opts: QueryOpts): { conditions: str
     if (field === "created_at") {
       column = "n.created_at";
     } else if (field === "updated_at") {
+      // NOTE (vault#586 follow-up): this range filter compares the TEXT
+      // `updated_at`, which is inconsistent on non-canonical rows the same way
+      // the cursor keyset was pre-v26. Cursor pagination moved to the integer
+      // `updated_at_ms` column; `date_filter`/`order_by`/export `--since` still
+      // read the string and are tracked separately. Behavior unchanged here.
       column = "n.updated_at";
     } else {
       // Re-uses the same indexed-field gate as `metadata` operator queries
@@ -1133,11 +1210,19 @@ function buildFilterConditions(db: Database, opts: QueryOpts): { conditions: str
   return { conditions, params };
 }
 
-export function queryNotes(db: Database, opts: QueryOpts): Note[] {
+/**
+ * `_outUpdatedAtMs` (internal, vault#586) — when supplied, the phase-1 page
+ * query writes each returned id's integer `updated_at_ms` keyset key into it.
+ * Only `queryNotesPaged` passes it, to derive the cursor watermark from the
+ * SAME statement that determined page membership + order (one consistent
+ * snapshot — see the call site). Ordinary callers omit it and are unaffected;
+ * it never touches the returned `Note` shape.
+ */
+export function queryNotes(db: Database, opts: QueryOpts, _outUpdatedAtMs?: Map<string, number>): Note[] {
   validateLimitOffset(opts);
   const { conditions, params } = buildFilterConditions(db, opts);
 
-  // ---- Cursor predicate (vault#313) ----
+  // ---- Cursor predicate (vault#313; keyset column vault#586) ----
   //
   // Cursor mode is keyed on PRESENCE of `opts.cursor`, not truthiness
   // (vault#550 bootstrap fix). `cursor: ""` is the bootstrap call — "I want
@@ -1148,24 +1233,38 @@ export function queryNotes(db: Database, opts: QueryOpts): Note[] {
   // Before this fix, `if (opts.cursor)` treated an empty string exactly
   // like "no cursor" — the caller's bootstrap intent silently vanished and
   // the first page came back in `created_at` order instead of the
-  // `updated_at` keyset order the SECOND page (a real cursor) would use,
+  // keyset order the SECOND page (a real cursor) would use,
   // so naive "did I see this note already" comparisons could skip or
   // duplicate rows across the boundary.
   //
+  // The keyset orders on the integer `n.updated_at_ms` column (vault#586),
+  // NOT the TEXT `n.updated_at`. That column is the single source of truth
+  // for cursor ordering: walk-order, the boundary predicate below, and the
+  // watermark in `queryNotesPaged` all read the SAME integer, so they can't
+  // diverge the way three separate readings of `updated_at` did on
+  // aged/imported vaults whose timestamps aren't canonical `.toISOString()`
+  // (space-form / offset / no-`Z`) — under which TEXT-lex order, an ISO
+  // boundary string, and a `Date.parse` watermark disagreed and silently
+  // skipped or re-delivered rows.
+  //
   // When a REAL (non-empty) cursor is present, decode it, verify its
   // query_hash matches the current query, and add a keyset predicate of
   // the form:
   //
-  //   (updated_at > last_updated_at)
-  //     OR (updated_at = last_updated_at AND id > last_id)
+  //   (updated_at_ms > last_updated_at)
+  //     OR (updated_at_ms = last_updated_at AND id > last_id)
   //
-  // The cursor also forces ORDER BY n.updated_at ASC, n.id ASC so the
-  // watermark math is sound — paginating by updated_at while ordering
-  // by created_at would skip rows whose update timestamp differs from
-  // their creation timestamp. `orderBy` and `sort: "desc"` are mutually
-  // exclusive with cursor mode (a "since last checked" loop wants
-  // ascending updated_at, full stop); we reject with INVALID_QUERY so
-  // callers don't silently get a broken iteration.
+  // The cursor payload's `last_updated_at` is ALREADY a millisecond epoch
+  // (see cursor.ts) — the same units as the column — so it binds directly
+  // with no ISO round-trip. This is also why existing client cursors keep
+  // working unchanged across the upgrade: the encoded watermark was always
+  // ms. The cursor forces ORDER BY n.updated_at_ms ASC, n.id ASC so the
+  // watermark math is sound — paginating by update time while ordering by
+  // created_at would skip rows whose update differs from their creation.
+  // `orderBy` and `sort: "desc"` are mutually exclusive with cursor mode (a
+  // "since last checked" loop wants ascending update order, full stop); we
+  // reject with INVALID_QUERY so callers don't silently get a broken
+  // iteration.
   const cursorMode = opts.cursor !== undefined;
   let cursorPayload: CursorPayload | null = null;
   if (cursorMode) {
@@ -1190,20 +1289,17 @@ export function queryNotes(db: Database, opts: QueryOpts): Note[] {
           "cursor_query_mismatch",
         );
       }
-      // Translate the millis watermark back to an ISO string for the SQL
-      // comparison. SQLite's `n.updated_at` is TEXT in canonical ISO form
-      // (the store's `toISOString()` output), and ISO timestamps sort
-      // lexicographically in the same order as their millisecond epochs
-      // when they all use the same canonical form — which every timestamp
-      // vault mints does. Cursors minted on heterogeneous timestamps
-      // (e.g. an import that preserved unusual formatting) are still
-      // safe: we round-trip the cursor's millis through `new Date()`'s
-      // canonical ISO so the comparison is apples-to-apples.
-      const cursorIso = millisToIso(cursorPayload.last_updated_at);
+      // The cursor's `last_updated_at` is a millisecond epoch (cursor.ts) —
+      // the SAME units as the integer `n.updated_at_ms` column — so it binds
+      // straight into the keyset predicate with no ISO round-trip. Ordering
+      // and boundary now read one numeric column, so heterogeneous /
+      // non-canonical `updated_at` TEXT (space-form, offset, no-`Z`) can no
+      // longer make the walk and the watermark disagree.
+      const cursorMs = cursorPayload.last_updated_at;
       conditions.push(
-        "(n.updated_at > ? OR (n.updated_at = ? AND n.id > ?))",
+        "(n.updated_at_ms > ? OR (n.updated_at_ms = ? AND n.id > ?))",
       );
-      params.push(cursorIso, cursorIso, cursorPayload.last_id);
+      params.push(cursorMs, cursorMs, cursorPayload.last_id);
     }
     // else: bootstrap call (`cursor === ""`) — no watermark yet, no
     // predicate to add, but the ORDER BY below still switches to the
@@ -1214,11 +1310,12 @@ export function queryNotes(db: Database, opts: QueryOpts): Note[] {
   const direction = opts.sort === "desc" ? "DESC" : "ASC";
   let orderBy: string;
   if (cursorMode) {
-    // Cursor mode forces a deterministic keyset order. `id` is the
-    // tiebreaker — without it, two notes sharing an `updated_at` would
-    // be at the mercy of SQLite's row order and the next page could
-    // miss or duplicate one.
-    orderBy = "n.updated_at ASC, n.id ASC";
+    // Cursor mode forces a deterministic keyset order on the integer
+    // `updated_at_ms` column (vault#586), matching the boundary predicate
+    // above and the `idx_notes_updated_ms` index. `id` is the tiebreaker —
+    // without it, two notes sharing an `updated_at_ms` would be at the mercy
+    // of SQLite's row order and the next page could miss or duplicate one.
+    orderBy = "n.updated_at_ms ASC, n.id ASC";
   } else if (opts.orderBy === "link_count") {
     // `link_count` is a pseudo-field — like `created_at`/`updated_at` in the
     // dateFilter block above, it bypasses `requireIndexedField` (it's not a
@@ -1273,15 +1370,26 @@ export function queryNotes(db: Database, opts: QueryOpts): Note[] {
   // Phase 2 fetches full rows for just the page (≤ limit ids) and re-orders
   // to the phase-1 order; tags are hydrated in ONE batched query instead of
   // one query per returned note.
+  // Phase 1 also selects `n.updated_at_ms` (vault#586) so a paging caller can
+  // read the keyset key from the SAME statement that applied the keyset order
+  // — the watermark then comes from one consistent snapshot, immune to a
+  // cross-process writer bumping a page row's ms between two separate reads.
   const idSql = `
-    SELECT n.id FROM notes n
+    SELECT n.id, n.updated_at_ms FROM notes n
     ${whereClause}
     ORDER BY ${orderBy}
     LIMIT ? OFFSET ?
   `;
   params.push(limit, offset);
 
-  const idRows = db.prepare(idSql).all(...params) as { id: string }[];
+  const idRows = db.prepare(idSql).all(...params) as { id: string; updated_at_ms: number | null }[];
+  if (_outUpdatedAtMs) {
+    for (const r of idRows) {
+      if (r.updated_at_ms !== null && r.updated_at_ms !== undefined) {
+        _outUpdatedAtMs.set(r.id, r.updated_at_ms);
+      }
+    }
+  }
   return fetchNotesByIdsOrdered(db, idRows.map((r) => r.id));
 }
 
@@ -1517,7 +1625,12 @@ function toQueryHashInputs(opts: QueryOpts): QueryHashInputs {
  * with a non-null `updated_at` greater than the unix epoch).
  */
 export function queryNotesPaged(db: Database, opts: QueryOpts): QueryNotesPage {
-  const notes = queryNotes(db, opts);
+  // Capture each page row's integer keyset key (vault#586) from the SAME
+  // phase-1 statement that ordered + sliced the page — one consistent
+  // snapshot, so the watermark can't leapfrog rows a cross-process writer
+  // bumps between reads. This replaces a separate post-query round-trip.
+  const updatedAtMsById = new Map<string, number>();
+  const notes = queryNotes(db, opts, updatedAtMsById);
   const queryHash = computeQueryHash(toQueryHashInputs(opts));
 
   // Watermark math: pick the larger of (last returned row, prior cursor
@@ -1536,14 +1649,20 @@ export function queryNotesPaged(db: Database, opts: QueryOpts): QueryNotesPage {
     lastId = prior.last_id;
   }
   if (notes.length > 0) {
-    // queryNotes with a cursor orders by (updated_at ASC, id ASC), so
-    // the last note in the array is the new watermark. When no cursor
-    // was passed, the SQL is ordered by created_at; we still want the
-    // cursor to advance to the MAX (updated_at, id) of this page so
-    // the next call resumes correctly. Compute the max explicitly.
+    // Advance the watermark to the page's MAX (updated_at_ms, id) using the
+    // keyset keys captured in the phase-1 snapshot above (vault#586) — the
+    // SAME integer `updated_at_ms` the walk-order used, from the SAME read.
+    // Using the snapshot, rather than re-deriving ms from each note's
+    // `updatedAt` string or re-reading the column, is what keeps walk-order
+    // and watermark from diverging: a row whose backfilled column and
+    // non-canonical `updated_at` TEXT disagree would otherwise re-parse to a
+    // different ms here and skip or re-deliver at the boundary. No throw — a
+    // NULL key (shouldn't occur post-migrateToV26) reads as 0. When a cursor
+    // is in effect the SQL already returns rows in (updated_at_ms, id) order
+    // so the last row IS the max; the explicit max also covers the
+    // created_at-ordered no-cursor path.
     for (const note of notes) {
-      const updatedIso = note.updatedAt ?? note.createdAt;
-      const ms = isoToMillis(updatedIso);
+      const ms = updatedAtMsById.get(note.id) ?? 0;
       if (ms > lastUpdatedAt || (ms === lastUpdatedAt && note.id > lastId)) {
         lastUpdatedAt = ms;
         lastId = note.id;
@@ -2041,6 +2160,10 @@ export function renameTag(db: Database, oldName: string, newName: string): Renam
     // note_tags FK on `tag_name` has no ON DELETE, so the delete must
     // come AFTER the repoint.
     const now = new Date().toISOString();
+    // Integer keyset mirror of `now` for the note `updated_at_ms` bumps in the
+    // content/path rewrite passes below (vault#586). `now` is canonical, so
+    // `timestampToMs` never returns null here.
+    const nowMs = timestampToMs(now) ?? Date.now();
     const readStmt = db.prepare(
       "SELECT description, fields, relationships, parent_names, created_at FROM tags WHERE name = ?",
     );
@@ -2168,12 +2291,13 @@ export function renameTag(db: Database, oldName: string, newName: string): Renam
       // `#newtag`) and must bump `updated_at` like any other content
       // write, or a cursor/sync-poll loop never sees it. Shares the one
       // `now` timestamp for the whole cascade (same convention as the
-      // tag-row rename pass above).
-      const updateStmt = db.prepare("UPDATE notes SET content = ?, updated_at = ? WHERE id = ?");
+      // tag-row rename pass above). `updated_at_ms` moves with it (vault#586)
+      // so the cursor keyset actually surfaces the rewrite.
+      const updateStmt = db.prepare("UPDATE notes SET content = ?, updated_at = ?, updated_at_ms = ? WHERE id = ?");
       for (const row of candidates) {
         const next = rewriteNoteBody(row.content, renames);
         if (next === row.content) continue;
-        updateStmt.run(next, now, row.id);
+        updateStmt.run(next, now, nowMs, row.id);
         notesRewritten++;
       }
     }
@@ -2189,12 +2313,13 @@ export function renameTag(db: Database, oldName: string, newName: string): Renam
         .prepare(`SELECT id, path FROM notes WHERE path IS NOT NULL AND (${orClauses})`)
         .all(...params) as { id: string; path: string }[];
       // vault#555 fix 2 — same reasoning as the content rewrite above: a
-      // path rewrite is a real persisted-state change.
-      const updateStmt = db.prepare("UPDATE notes SET path = ?, updated_at = ? WHERE id = ?");
+      // path rewrite is a real persisted-state change. `updated_at_ms` moves
+      // with `updated_at` (vault#586).
+      const updateStmt = db.prepare("UPDATE notes SET path = ?, updated_at = ?, updated_at_ms = ? WHERE id = ?");
       for (const row of candidates) {
         const next = rewriteTagConfigPath(row.path, renames);
         if (next === row.path) continue;
-        updateStmt.run(next, now, row.id);
+        updateStmt.run(next, now, nowMs, row.id);
         pathsRenamed++;
       }
     }

package/core/src/paths.ts

@@ -19,6 +19,10 @@ export function normalizePath(path: string | null | undefined): string | null {
   if (path === null || path === undefined) return null;
 
   let p = path
+    .replace(/\0/g, "")           // strip NUL bytes — never valid in a path;
+                                   // belt for legacy/imported rows so a stored
+                                   // NUL can't reach the filesystem (writes
+                                   // reject NUL up front via validatePath)
     .trim()
     .replace(/\\/g, "/")          // backslash → forward slash
     .replace(/\.md$/i, "")         // strip .md extension

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

@@ -29,6 +29,7 @@ import { buildVaultProjection } from "./vault-projection.js";
 import {
   CaseCollisionError,
   emitYamlDoc,
+  exportVault,
   exportVaultToDir,
   importPortableVault,
   noteToPortable,
@@ -41,7 +42,9 @@ import {
   supportsInlineFrontmatter,
   toPortableMarkdown,
   toSidecarYaml,
+  type ExportSink,
   type PortableNote,
+  type SinkWriteResult,
 } from "./portable-md.js";
 
 // ---------------------------------------------------------------------------
@@ -416,6 +419,86 @@ describe("exportVaultToDir", async () => {
     expect(vault).toContain("name: test");
   });
 
+  // FIX 2(b) (vault#589) — a NUL-in-path note (a pre-fix poisoned row a
+  // write-capable token could have planted) must be SKIPPED with a warning +
+  // stat, never abort the whole export. Before the sink hardening the
+  // uncaught `writeFileSync` throw aborted the entire vault export, so one bad
+  // note broke backup/export for everyone.
+  //
+  // RED-without-fix: drop the try/catch from `FsExportSink.writeText` and this
+  // test's `exportVaultToDir` call throws (whole export aborts) instead of
+  // returning a partial-with-skip result. Verified manually during development.
+  it("hardened export sink: a NUL-in-path note is skipped, not fatal (vault#589)", async () => {
+    await store.createNote("clean one", { id: "c1", path: "clean/one" });
+    await store.createNote("clean two", { id: "c2", path: "clean/two" });
+    await store.createNote("poison", { id: "p1", path: "temp" });
+    // Simulate a pre-fix vault: inject a real NUL directly into the stored
+    // path, bypassing normalizePath (which now strips NUL). `char(0)` yields a
+    // NUL byte in the TEXT column that survives read-back into note.path.
+    store.db.prepare("UPDATE notes SET path = 'bad' || char(0) || 'path' WHERE id = ?").run("p1");
+
+    const outDir = join(tmpBase, "poisoned-out");
+    const stats = await exportVaultToDir(store, { outDir, exportedAt: "2026-05-13T00:00:00.000Z" });
+
+    // The export completes and every OTHER note is written ...
+    expect(existsSync(join(outDir, "clean/one.md"))).toBe(true);
+    expect(existsSync(join(outDir, "clean/two.md"))).toBe(true);
+    expect(stats.notes).toBe(2); // only the two clean notes counted as written
+
+    // ... while the poisoned note is skipped-with-reason (fs write failure),
+    // surfaced as a stat rather than a thrown, aborted export.
+    expect(stats.skipped_traversal).toBeGreaterThanOrEqual(1);
+    const poisonSkip = stats.skipped_notes.find((s) => s.reason.includes("fs write failed"));
+    expect(poisonSkip).toBeTruthy();
+  });
+
+  // BLOCKER (vault#589 review) — the skip-with-warn export belt (FIX 2b) is
+  // correct ONLY for per-NOTE writes. The STRUCTURAL writes (the vault.yaml
+  // manifest + per-tag schema sidecars) are global: a dir missing
+  // `.parachute/vault.yaml` is hard-rejected at restore/import, so a discarded
+  // `{ok:false}` there would produce a manifest-less "success" — a silently
+  // broken backup. Those must FAIL LOUDLY.
+  //
+  // RED-without-fix: with the structural writes discarding the sink result,
+  // both `exportVault` calls RESOLVE (no throw) and the manifest/schema is
+  // silently absent. Verified manually during development.
+  it("aborts loudly when the manifest write fails (structural, not skip-with-warn)", async () => {
+    await store.createNote("n", { id: "n1", path: "p" });
+    // Stub sink that fails ONLY the manifest write; everything else succeeds.
+    const sink: ExportSink = {
+      caseSensitive: true,
+      attachmentsEnabled: false,
+      writeText(relPath: string): SinkWriteResult {
+        if (relPath === join(SIDECAR_DIR, "vault.yaml")) {
+          return { ok: false, reason: "simulated EACCES on .parachute/" };
+        }
+        return { ok: true };
+      },
+      copyAttachment(): SinkWriteResult { return { ok: true }; },
+    };
+    await expect(exportVault(store, sink, { exportedAt: "2026-05-13T00:00:00.000Z" }))
+      .rejects.toThrow(/manifest/i);
+  });
+
+  it("aborts loudly when a schema sidecar write fails (structural, not skip-with-warn)", async () => {
+    await store.upsertTagSchema("task", { description: "A unit of work" });
+    await store.createNote("x", { id: "x1", tags: ["task"] });
+    // Fail ONLY the schema write; the manifest (and everything else) succeeds.
+    const sink: ExportSink = {
+      caseSensitive: true,
+      attachmentsEnabled: false,
+      writeText(relPath: string): SinkWriteResult {
+        if (relPath.startsWith(join(SIDECAR_DIR, "schemas"))) {
+          return { ok: false, reason: "simulated disk full" };
+        }
+        return { ok: true };
+      },
+      copyAttachment(): SinkWriteResult { return { ok: true }; },
+    };
+    await expect(exportVault(store, sink, { exportedAt: "2026-05-13T00:00:00.000Z" }))
+      .rejects.toThrow(/schema sidecar/i);
+  });
+
   it("writes per-tag schemas to .parachute/schemas/", async () => {
     await store.upsertTagSchema("task", {
       description: "A unit of work",
@@ -710,6 +793,84 @@ describe("importPortableVault", async () => {
     expect(await targetStore.getNote("k1")).toBeTruthy();
   });
 
+  // FIX 1 (vault#589) — blow-away must be all-or-nothing. Before the fix, the
+  // wipe + replay ran with NO enclosing transaction: a mid-replay throw (here a
+  // PathConflictError from two source files declaring the same `path`) left the
+  // vault WIPED + partially replayed, originals gone for good. The wrap rolls
+  // the whole thing back to the exact pre-import vault.
+  //
+  // RED-without-fix: temporarily change `importVault` to always call
+  // `importVaultReplay` unwrapped (drop the `transactionAsync`) and this test
+  // ends with 1 note (`n-first`), all three originals gone — the assertions
+  // below fail. Verified manually during development.
+  it("--blow-away is atomic — a mid-replay throw rolls back to the original vault (vault#589)", async () => {
+    // Target vault holds originals that MUST survive a failed restore.
+    const target = new SqliteStore(new Database(":memory:"));
+    await target.createNote("original one", { id: "orig1", path: "keep/one" });
+    await target.createNote("original two", { id: "orig2", path: "keep/two" });
+    await target.createNote("original three", { id: "orig3", path: "keep/three" });
+
+    // Hand-build a poisoned export: two notes declaring the SAME frontmatter
+    // `path` → the 2nd createNote throws PathConflictError mid-replay. Files
+    // walk in sorted order (first.md before second.md), so first.md lands, then
+    // second.md collides.
+    const inDir = join(tmpBase, "poison-collide");
+    mkdirSync(join(inDir, ".parachute"), { recursive: true });
+    writeFileSync(join(inDir, ".parachute", "vault.yaml"), "name: poison\nexport_format_version: 1\n");
+    writeFileSync(join(inDir, "first.md"), "---\nid: nfirst\npath: collide\n---\nfirst body\n");
+    writeFileSync(join(inDir, "second.md"), "---\nid: nsecond\npath: collide\n---\nsecond body\n");
+
+    // The blow-away import propagates the collision (rejects) ...
+    await expect(importPortableVault(target, { inDir, blowAway: true })).rejects.toThrow();
+
+    // ... and rolls back: all three ORIGINALS survive, and NONE of the
+    // poisoned import's notes landed. The vault is exactly as it was.
+    expect(await target.getNote("orig1")).toBeTruthy();
+    expect(await target.getNote("orig2")).toBeTruthy();
+    expect(await target.getNote("orig3")).toBeTruthy();
+    expect(await target.getNote("nfirst")).toBeNull();
+    expect(await target.getNote("nsecond")).toBeNull();
+    const all = await target.queryNotes({ limit: 100 });
+    expect(all.length).toBe(3);
+  });
+
+  // FIX 3 (vault#589) — duplicate-id and blank-id content files must be
+  // reported + skipped, not silently clobber (last-wins) or seed a bogus key.
+  it("reports duplicate + blank note ids instead of silently clobbering (vault#589)", async () => {
+    // Hand-build a tree: two files share id "dup" (distinct content); a third
+    // carries a whitespace-only id. Files walk sorted: aaa < bbb < ccc.
+    const inDir = join(tmpBase, "dup-ids");
+    mkdirSync(join(inDir, ".parachute"), { recursive: true });
+    writeFileSync(join(inDir, ".parachute", "vault.yaml"), "name: dup\nexport_format_version: 1\n");
+    writeFileSync(join(inDir, "aaa.md"), "---\nid: dup\npath: pa\n---\nfrom aaa\n");
+    writeFileSync(join(inDir, "bbb.md"), "---\nid: dup\npath: pb\n---\nfrom bbb\n");
+    writeFileSync(join(inDir, "ccc.md"), "---\nid: '   '\npath: pc\n---\nfrom ccc\n");
+
+    const target = new SqliteStore(new Database(":memory:"));
+    const stats = await importPortableVault(target, { inDir });
+
+    // Exactly ONE note created — the FIRST of the id collision (aaa) — and the
+    // collision is NOT folded into "updated".
+    expect(stats.notes_created).toBe(1);
+    expect(stats.notes_updated).toBe(0);
+    const kept = await target.getNote("dup");
+    expect(kept).toBeTruthy();
+    expect(kept!.content.trimEnd()).toBe("from aaa"); // first-wins, deterministic
+
+    // Both the duplicate (bbb) and the blank-id (ccc) file are reported as
+    // skipped — surfaced in stats, not absorbed into the created/updated count.
+    expect(stats.skipped_duplicate_ids.length).toBe(2);
+    const dupEntry = stats.skipped_duplicate_ids.find((s) => s.reason.includes("duplicate id"));
+    expect(dupEntry).toBeTruthy();
+    expect(dupEntry!.path).toBe("pb");
+    const blankEntry = stats.skipped_duplicate_ids.find((s) => s.reason.includes("blank"));
+    expect(blankEntry).toBeTruthy();
+
+    // The whitespace-id file clobbered nothing — no bogus key, only "dup" exists.
+    const allNotes = await target.queryNotes({ limit: 100 });
+    expect(allNotes.length).toBe(1);
+  });
+
   it("restores tag schemas (description + fields)", async () => {
     await store.upsertTagSchema("task", {
       description: "A unit of work",