@openparachute/vault 0.4.7-rc.1 → 0.4.8-rc.4

package/core/src/notes.ts

@@ -1,5 +1,5 @@
 import { Database, type SQLQueryBindings } from "bun:sqlite";
-import type { Note, NoteIndex, QueryOpts, VaultStats } from "./types.js";
+import type { Note, NoteIndex, QueryOpts, QueryNotesPage, VaultStats } from "./types.js";
 import { normalizePath } from "./paths.js";
 import {
   buildOperatorClause,
@@ -7,6 +7,17 @@ import {
   QueryError,
   requireIndexedField,
 } from "./query-operators.js";
+import {
+  CURSOR_VERSION,
+  CursorError,
+  computeQueryHash,
+  decodeCursor,
+  encodeCursor,
+  isoToMillis,
+  millisToIso,
+  type CursorPayload,
+  type QueryHashInputs,
+} from "./cursor.js";
 
 let idCounter = 0;
 
@@ -663,9 +674,68 @@ export function queryNotes(db: Database, opts: QueryOpts): Note[] {
     }
   }
 
+  // ---- Cursor predicate (vault#313) ----
+  //
+  // When a 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)
+  //
+  // 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.
+  let cursorPayload: CursorPayload | null = null;
+  if (opts.cursor) {
+    if (opts.orderBy) {
+      throw new QueryError(
+        `cursor and order_by are mutually exclusive — cursor pagination forces order by updated_at`,
+        "INVALID_QUERY",
+      );
+    }
+    if (opts.sort === "desc") {
+      throw new QueryError(
+        `cursor pagination requires ascending sort by updated_at — descending sort with a cursor would skip newly-written rows`,
+        "INVALID_QUERY",
+      );
+    }
+    cursorPayload = decodeCursor(opts.cursor);
+    const expectedHash = computeQueryHash(toQueryHashInputs(opts));
+    if (cursorPayload.query_hash !== expectedHash) {
+      throw new CursorError(
+        `cursor was minted for a different query — drop the cursor and restart iteration`,
+        "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);
+    conditions.push(
+      "(n.updated_at > ? OR (n.updated_at = ? AND n.id > ?))",
+    );
+    params.push(cursorIso, cursorIso, cursorPayload.last_id);
+  }
+
   const direction = opts.sort === "desc" ? "DESC" : "ASC";
   let orderBy: string;
-  if (opts.orderBy) {
+  if (opts.cursor) {
+    // 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";
+  } else if (opts.orderBy) {
     requireIndexedField(db, opts.orderBy);
     // `orderBy` came from indexed_fields (validated on declaration), so
     // the column name is safe to interpolate. Append created_at as a
@@ -697,6 +767,98 @@ export function queryNotes(db: Database, opts: QueryOpts): Note[] {
   });
 }
 
+/**
+ * Extract the result-set-affecting subset of `QueryOpts` for cursor hashing.
+ *
+ * `cursor`, `limit`, `offset`, `_tagsExpanded` (internal cache key) are
+ * excluded — they don't change which rows match, just how many or how
+ * the iteration advances. See `core/src/cursor.ts` for the rationale.
+ */
+function toQueryHashInputs(opts: QueryOpts): QueryHashInputs {
+  return {
+    tags: opts.tags,
+    tagMatch: opts.tagMatch,
+    excludeTags: opts.excludeTags,
+    hasTags: opts.hasTags,
+    hasLinks: opts.hasLinks,
+    path: opts.path,
+    pathPrefix: opts.pathPrefix,
+    extension: opts.extension,
+    ids: opts.ids,
+    metadata: opts.metadata,
+    dateFrom: opts.dateFrom,
+    dateTo: opts.dateTo,
+    dateFilter: opts.dateFilter,
+    sort: opts.sort,
+    orderBy: opts.orderBy,
+  };
+}
+
+/**
+ * Cursor-paginated wrapper around `queryNotes` (vault#313).
+ *
+ * Always returns `{ notes, next_cursor }`. `next_cursor` advances even on
+ * an empty result page — the caller can persist a single watermark and
+ * keep polling without special-casing the empty-page condition. The
+ * empty-page cursor's `last_updated_at` is the larger of:
+ *   - the prior cursor's `last_updated_at` (when `opts.cursor` was set), or
+ *   - the prior cursor's `last_updated_at` (defaults to 0 when not).
+ *
+ * Holding the watermark at the prior value on an empty page is the
+ * conservative choice: if a note is written between this call and the
+ * next at a timestamp BEFORE wall-clock-now (clock skew, batch import
+ * with explicit `created_at`), advancing the watermark to `now()` would
+ * skip it. The watermark advances only when actual rows are returned.
+ *
+ * First-call semantics (`opts.cursor` absent): query_hash is computed
+ * from the result-set-affecting opts and bound into the minted cursor.
+ * If zero rows match, the returned cursor encodes
+ * `last_updated_at = 0, last_id = ""` so the next call returns
+ * everything written since (the keyset predicate
+ * `updated_at > 0 OR (updated_at = 0 AND id > "")` matches every row
+ * with a non-null `updated_at` greater than the unix epoch).
+ */
+export function queryNotesPaged(db: Database, opts: QueryOpts): QueryNotesPage {
+  const notes = queryNotes(db, opts);
+  const queryHash = computeQueryHash(toQueryHashInputs(opts));
+
+  // Watermark math: pick the larger of (last returned row, prior cursor
+  // watermark, sentinel). When the page is empty, fall back to the prior
+  // cursor's watermark — see the JSDoc rationale above.
+  let lastUpdatedAt = 0;
+  let lastId = "";
+  if (opts.cursor) {
+    // Re-decode (we already validated in queryNotes); this is cheap.
+    const prior = decodeCursor(opts.cursor);
+    lastUpdatedAt = prior.last_updated_at;
+    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.
+    for (const note of notes) {
+      const updatedIso = note.updatedAt ?? note.createdAt;
+      const ms = isoToMillis(updatedIso);
+      if (ms > lastUpdatedAt || (ms === lastUpdatedAt && note.id > lastId)) {
+        lastUpdatedAt = ms;
+        lastId = note.id;
+      }
+    }
+  }
+
+  const next_cursor = encodeCursor({
+    v: CURSOR_VERSION,
+    last_updated_at: lastUpdatedAt,
+    last_id: lastId,
+    query_hash: queryHash,
+  });
+
+  return { notes, next_cursor };
+}
+
 export function searchNotes(
   db: Database,
   query: string,

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

@@ -25,6 +25,7 @@ import { tmpdir } from "os";
 
 import { SqliteStore } from "./store.js";
 import {
+  CaseCollisionError,
   emitYamlDoc,
   exportVaultToDir,
   importPortableVault,
@@ -1551,4 +1552,250 @@ describe("case-collision detection (vault#327)", async () => {
     expect(lower!.path).toBe("Tabular/budget-2026");
     expect(lower!.content).toBe("month,total\n2026-01,1");
   });
+
+  // ---------------------------------------------------------------------------
+  // failOnCaseCollision — strict mode (vault#327 Phase 2)
+  // ---------------------------------------------------------------------------
+  //
+  // The default behavior (auto-disambiguate) is lossless but silent on the
+  // wire — the CLI didn't surface it before #vault-rc.2. Strict mode is the
+  // opt-in fail-fast path: throws `CaseCollisionError` with every colliding
+  // path enumerated, so the operator can rename one of each pair in the
+  // vault before re-exporting.
+
+  it("failOnCaseCollision throws CaseCollisionError on case-insensitive FS", async () => {
+    await store.createNote("# in Balance", {
+      id: "2025-05-26-09-15-42-aaaaaa",
+      path: "Journal/2025-05-26 Technology in Balance",
+    });
+    await store.createNote("# in balance", {
+      id: "2025-05-26-09-15-42-bbbbbb",
+      path: "Journal/2025-05-26 Technology in balance",
+    });
+
+    const outDir = join(tmpBase, "strict-throw");
+    let thrown: unknown;
+    try {
+      await exportVaultToDir(store, {
+        outDir,
+        vaultName: "test",
+        exportedAt: "2026-05-15T00:00:00.000Z",
+        caseSensitiveOverride: false,
+        failOnCaseCollision: true,
+      });
+    } catch (err) {
+      thrown = err;
+    }
+    expect(thrown).toBeInstanceOf(CaseCollisionError);
+    const err = thrown as CaseCollisionError;
+    expect(err.collisions).toHaveLength(1);
+    expect(err.collisions[0]).toHaveLength(2);
+    const ids = err.collisions[0]!.map((c) => c.note_id).sort();
+    expect(ids).toEqual(["2025-05-26-09-15-42-aaaaaa", "2025-05-26-09-15-42-bbbbbb"]);
+    // Error message names BOTH paths + the actionable instruction.
+    expect(err.message).toContain("Journal/2025-05-26 Technology in Balance");
+    expect(err.message).toContain("Journal/2025-05-26 Technology in balance");
+    expect(err.message).toContain("Rename one of them");
+    // Pre-scan throws BEFORE any per-note file write. The .parachute/
+    // sidecar dir is still created (cheap, idempotent), but no per-note
+    // .md file landed.
+    expect(existsSync(join(outDir, "Journal/2025-05-26 Technology in Balance.md"))).toBe(false);
+  });
+
+  it("failOnCaseCollision is a no-op when FS is case-sensitive", async () => {
+    // Same fixture as above, but force the case-sensitive code path. The
+    // strict flag becomes a no-op — both files land at their canonical
+    // paths, no error.
+    await store.createNote("# in Balance", {
+      id: "2025-05-26-09-15-42-aaaaaa",
+      path: "Journal/2025-05-26 Technology in Balance",
+    });
+    await store.createNote("# in balance", {
+      id: "2025-05-26-09-15-42-bbbbbb",
+      path: "Journal/2025-05-26 Technology in balance",
+    });
+
+    const outDir = join(tmpBase, "strict-cs");
+    const stats = await exportVaultToDir(store, {
+      outDir,
+      vaultName: "test",
+      exportedAt: "2026-05-15T00:00:00.000Z",
+      caseSensitiveOverride: true,
+      failOnCaseCollision: true,
+    });
+    expect(stats.notes).toBe(2);
+    expect(stats.disambiguated_paths).toHaveLength(0);
+  });
+
+  it("failOnCaseCollision is a no-op on case-insensitive FS when nothing collides", async () => {
+    // One note. Strict mode + case-insensitive FS — should not throw,
+    // should ship clean. Pre-scan walks the (single-note) list and
+    // finds no collision groups.
+    await store.createNote("# solo", {
+      id: "2025-05-26-09-15-42-aaaaaa",
+      path: "Journal/Solo Note",
+    });
+
+    const outDir = join(tmpBase, "strict-solo");
+    const stats = await exportVaultToDir(store, {
+      outDir,
+      vaultName: "test",
+      exportedAt: "2026-05-15T00:00:00.000Z",
+      caseSensitiveOverride: false,
+      failOnCaseCollision: true,
+    });
+    expect(stats.notes).toBe(1);
+    expect(stats.disambiguated_paths).toHaveLength(0);
+    expect(existsSync(join(outDir, "Journal/Solo Note.md"))).toBe(true);
+  });
+
+  it("three-way collision lists all three paths in the error", async () => {
+    // Foo.md + foo.md + FOO.md — all share the same lowercased
+    // `(path, ext)` slot. CaseCollisionError.collisions[0] should
+    // include every one of them so the operator sees the full set in
+    // a single error report, not a paint-by-numbers re-export cycle.
+    await store.createNote("# upper-camel", {
+      id: "2025-05-26-09-15-42-aaaaaa",
+      path: "Journal/Foo",
+    });
+    await store.createNote("# lower", {
+      id: "2025-05-26-09-15-42-bbbbbb",
+      path: "Journal/foo",
+    });
+    await store.createNote("# all-caps", {
+      id: "2025-05-26-09-15-42-cccccc",
+      path: "Journal/FOO",
+    });
+
+    const outDir = join(tmpBase, "strict-3way");
+    let thrown: unknown;
+    try {
+      await exportVaultToDir(store, {
+        outDir,
+        vaultName: "test",
+        exportedAt: "2026-05-15T00:00:00.000Z",
+        caseSensitiveOverride: false,
+        failOnCaseCollision: true,
+      });
+    } catch (err) {
+      thrown = err;
+    }
+    expect(thrown).toBeInstanceOf(CaseCollisionError);
+    const err = thrown as CaseCollisionError;
+    expect(err.collisions).toHaveLength(1);
+    expect(err.collisions[0]).toHaveLength(3);
+    const paths = err.collisions[0]!.map((c) => c.path).sort();
+    expect(paths).toEqual(["Journal/FOO", "Journal/Foo", "Journal/foo"]);
+    expect(err.message).toContain("Journal/FOO");
+    expect(err.message).toContain("Journal/Foo");
+    expect(err.message).toContain("Journal/foo");
+  });
+
+  it("multiple independent collision groups all surface", async () => {
+    // Two distinct collision groups: (Bar.md, bar.md) and (Baz.md,
+    // baz.md). Both groups should appear in the error so the operator
+    // doesn't have to fix-rebuild-fix in a loop. Pairs are independent —
+    // resolving one doesn't reveal the other.
+    await store.createNote("# bar-upper", {
+      id: "2025-05-26-09-15-42-aaaaaa",
+      path: "Bar",
+    });
+    await store.createNote("# bar-lower", {
+      id: "2025-05-26-09-15-42-bbbbbb",
+      path: "bar",
+    });
+    await store.createNote("# baz-upper", {
+      id: "2025-05-26-09-15-42-cccccc",
+      path: "Baz",
+    });
+    await store.createNote("# baz-lower", {
+      id: "2025-05-26-09-15-42-dddddd",
+      path: "baz",
+    });
+
+    const outDir = join(tmpBase, "strict-multi-group");
+    let thrown: unknown;
+    try {
+      await exportVaultToDir(store, {
+        outDir,
+        vaultName: "test",
+        exportedAt: "2026-05-15T00:00:00.000Z",
+        caseSensitiveOverride: false,
+        failOnCaseCollision: true,
+      });
+    } catch (err) {
+      thrown = err;
+    }
+    expect(thrown).toBeInstanceOf(CaseCollisionError);
+    const err = thrown as CaseCollisionError;
+    expect(err.collisions).toHaveLength(2);
+    const allIds = err.collisions.flat().map((c) => c.note_id).sort();
+    expect(allIds).toEqual([
+      "2025-05-26-09-15-42-aaaaaa",
+      "2025-05-26-09-15-42-bbbbbb",
+      "2025-05-26-09-15-42-cccccc",
+      "2025-05-26-09-15-42-dddddd",
+    ]);
+  });
+
+  it("directory-level case difference triggers collision detection", async () => {
+    // Two notes at `Notes/foo` and `notes/foo` — the basename matches
+    // but the parent dir differs only by case. On a case-insensitive
+    // FS, both files would land in the same directory because
+    // `Notes/` and `notes/` resolve to the same inode. Verify the
+    // lowercased-path key catches this: `notes/foo.md`.
+    await store.createNote("# notes-upper", {
+      id: "2025-05-26-09-15-42-aaaaaa",
+      path: "Notes/foo",
+    });
+    await store.createNote("# notes-lower", {
+      id: "2025-05-26-09-15-42-bbbbbb",
+      path: "notes/foo",
+    });
+
+    const outDir = join(tmpBase, "strict-dir-case");
+    let thrown: unknown;
+    try {
+      await exportVaultToDir(store, {
+        outDir,
+        vaultName: "test",
+        exportedAt: "2026-05-15T00:00:00.000Z",
+        caseSensitiveOverride: false,
+        failOnCaseCollision: true,
+      });
+    } catch (err) {
+      thrown = err;
+    }
+    expect(thrown).toBeInstanceOf(CaseCollisionError);
+    const err = thrown as CaseCollisionError;
+    expect(err.collisions).toHaveLength(1);
+    expect(err.collisions[0]).toHaveLength(2);
+  });
+
+  it("default (no failOnCaseCollision) still auto-disambiguates — back-compat", async () => {
+    // The new strict mode is opt-in. Leaving failOnCaseCollision unset
+    // (or false) keeps the existing lossless auto-disambiguation path
+    // unchanged. This pins the back-compat contract — watch/mirror
+    // loops that don't opt in to strict mode never see a thrown
+    // CaseCollisionError on a colliding vault.
+    await store.createNote("# upper", {
+      id: "2025-05-26-09-15-42-aaaaaa",
+      path: "Journal/Note",
+    });
+    await store.createNote("# lower", {
+      id: "2025-05-26-09-15-42-bbbbbb",
+      path: "Journal/note",
+    });
+
+    const outDir = join(tmpBase, "default-disambig");
+    const stats = await exportVaultToDir(store, {
+      outDir,
+      vaultName: "test",
+      exportedAt: "2026-05-15T00:00:00.000Z",
+      caseSensitiveOverride: false,
+      // failOnCaseCollision deliberately omitted — default behavior.
+    });
+    expect(stats.notes).toBe(2);
+    expect(stats.disambiguated_paths).toHaveLength(1);
+  });
 });

package/core/src/portable-md.ts

@@ -631,6 +631,78 @@ export interface ExportOptions {
    * run on. When unset (the production default), the probe runs.
    */
   caseSensitiveOverride?: boolean;
+  /**
+   * Strict mode for case-collision handling on case-insensitive
+   * filesystems (vault#327 Phase 2). When `true`, the first detected
+   * collision aborts the export by throwing a `CaseCollisionError`
+   * naming every colliding path. When `false` (the default), the
+   * existing lossless behavior is preserved — the colliding note is
+   * written to a disambiguated filename (`<base>__<id-short>.<ext>`)
+   * and recorded in `ExportStats.disambiguated_paths`.
+   *
+   * Use `true` for one-shot CLI flows where the operator wants to be
+   * forced to fix the source-of-truth (rename one of the colliding
+   * notes in the vault before re-exporting). Leave `false` for
+   * long-running watch / mirror loops where a hard failure mid-loop
+   * would block the operator's actual work.
+   */
+  failOnCaseCollision?: boolean;
+}
+
+/**
+ * Thrown by `exportVaultToDir` when `failOnCaseCollision: true` is set
+ * and the export detects two-or-more notes whose paths differ only by
+ * case on a case-insensitive filesystem (vault#327).
+ *
+ * The error names every colliding path (full N-way group, not just
+ * the first pair) so the operator can audit the whole set in one
+ * pass. Caller catches by type and surfaces `.collisions` for a
+ * clean error report:
+ *
+ * ```ts
+ * try {
+ *   await exportVaultToDir(store, { ..., failOnCaseCollision: true });
+ * } catch (err) {
+ *   if (err instanceof CaseCollisionError) {
+ *     for (const group of err.collisions) {
+ *       console.error(`collision: ${group.map((g) => g.path).join(", ")}`);
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export class CaseCollisionError extends Error {
+  /**
+   * Each entry is one collision group — every note that shares the same
+   * lowercased `(path, extension)` slot. Two notes per group is the
+   * common case; three-or-more (`Foo.md` + `foo.md` + `FOO.md`) is rare
+   * but supported. Notes are listed in the order they were encountered
+   * during the export walk (deterministic — `queryNotes` sorts ASC).
+   */
+  readonly collisions: Array<Array<{ note_id: string; path: string; extension: string }>>;
+  constructor(collisions: CaseCollisionError["collisions"]) {
+    const lines: string[] = [
+      "Export failed: case-collision detected on case-insensitive filesystem.",
+      "The following notes have paths that differ only by case:",
+    ];
+    // Separate distinct collision groups with `  ---` so operators
+    // reading the error in a terminal can tell where one (Foo.md /
+    // foo.md) pair ends and the next (Bar.md / bar.md) begins. Without
+    // a separator, multi-group output runs together as an unbroken
+    // bullet list. vault#350.
+    collisions.forEach((group, idx) => {
+      if (idx > 0) lines.push("  ---");
+      for (const entry of group) {
+        lines.push(`  - ${entry.path}.${entry.extension} (note id: ${entry.note_id})`);
+      }
+    });
+    lines.push(
+      "Rename one of them in the vault before re-exporting, or run from a case-sensitive filesystem.",
+    );
+    super(lines.join("\n"));
+    this.name = "CaseCollisionError";
+    this.collisions = collisions;
+  }
 }
 
 /**
@@ -733,9 +805,54 @@ export async function exportVaultToDir(
   // case-insensitive filesystems.
   const seenLowerKeys = new Map<string, string>();
 
+  // Strict-mode pre-scan (vault#327 Phase 2). When the caller passes
+  // `failOnCaseCollision: true`, surface every collision group in one
+  // typed error BEFORE any write lands on disk — partial-export-then-
+  // throw would leave the operator with a half-mirrored output dir to
+  // clean up. The pre-scan walks every note in the vault (NOT
+  // since-filtered: a since-filter belongs in the write loop —
+  // collisions can involve one old + one new path, and a since-only
+  // pre-scan would miss those entirely, silently degrading the strict
+  // guarantee on every poll cycle after the initial export). When no
+  // collisions exist on a case-insensitive FS, the pre-scan is a
+  // no-op (cheap); on a case-sensitive FS it's skipped entirely.
+  //
+  // Perf: the pre-scan calls `noteToPortable` (3 DB queries per note:
+  // links, attachments, content). The main loop below also calls
+  // `noteToPortable` — without caching, every note that ALSO passes
+  // the since-filter would be serialized twice (~2x the DB round-
+  // trips on a large strict-mode export). Stash every pre-scan result
+  // in `prescanPortables` and reuse it below; cache-miss falls back
+  // to a fresh `noteToPortable` for safety. vault#350.
+  const prescanPortables = new Map<string, PortableNote>();
+  if (opts.failOnCaseCollision && !caseSensitive) {
+    const groups = new Map<string, Array<{ note_id: string; path: string; extension: string }>>();
+    for (const note of allNotes) {
+      const portable = await noteToPortable(note, store);
+      prescanPortables.set(portable.id, portable);
+      if (!portable.path) continue; // _unpathed/<id>.<ext> is case-stable
+      const ext = portable.extension ?? "md";
+      const key = `${portable.path.toLowerCase()}|${ext.toLowerCase()}`;
+      const entry = { note_id: portable.id, path: portable.path, extension: ext };
+      const existing = groups.get(key);
+      if (existing) {
+        existing.push(entry);
+      } else {
+        groups.set(key, [entry]);
+      }
+    }
+    const collisions = Array.from(groups.values()).filter((g) => g.length > 1);
+    if (collisions.length > 0) {
+      throw new CaseCollisionError(collisions);
+    }
+  }
+
   for (const note of allNotes) {
     if (since && !shouldIncludeForSince(note, since)) continue;
-    const portable = await noteToPortable(note, store);
+    // Reuse a pre-scan result when strict-mode populated the cache;
+    // otherwise serialize fresh. Same PortableNote shape either way,
+    // so the rest of the loop is untouched. vault#350.
+    const portable = prescanPortables.get(note.id) ?? (await noteToPortable(note, store));
     let relPath = portableExportFilePath(portable);
 
     // Decide whether this note's filename needs disambiguation