@openparachute/vault 0.7.1 → 0.7.2-rc.3

package/core/src/cursor.ts

@@ -287,13 +287,83 @@ export function isoToMillis(iso: string): number {
 /**
  * Convert millisecond epoch back to an ISO-8601 timestamp string.
  *
- * Used to translate the cursor's `last_updated_at` into the form SQLite
- * compares (`n.updated_at` is a TEXT column carrying ISO strings). ISO
- * timestamps sort correctly lexicographically when they're all in the same
- * canonical form (Z-suffixed, fixed millisecond precision) — every
- * timestamp vault mints goes through `new Date(...).toISOString()` so the
- * lex-order matches the millis-order.
+ * Historically used to translate the cursor's `last_updated_at` into the form
+ * SQLite compared (`n.updated_at` TEXT). Post-vault#586 the keyset compares
+ * against the integer `notes.updated_at_ms` column directly, so this is no
+ * longer on the cursor hot path — kept as a tested utility.
  */
 export function millisToIso(ms: number): string {
   return new Date(ms).toISOString();
 }
+
+/**
+ * Matches an ISO-8601-ish timestamp. The time portion (and each finer field)
+ * is optional so a bare `YYYY-MM-DD` or `YYYY-MM-DD HH:MM` still parses. The
+ * separator is `T` or a space (aged/imported vaults carry both). Zone is an
+ * optional trailing `Z`/`z` or `±HH:MM` / `±HHMM`.
+ */
+const TIMESTAMP_RE =
+  /^(\d{4})-(\d{2})-(\d{2})(?:[T ](\d{2}):(\d{2})(?::(\d{2}))?(?:\.(\d+))?\s*(Z|z|[+-]\d{2}:?\d{2})?)?$/;
+
+/**
+ * UTC-correct millisecond-epoch parse of a stored timestamp string, or `null`
+ * when the value is genuinely unparseable (vault#586).
+ *
+ * The cursor keyset orders by an integer `notes.updated_at_ms` column; this is
+ * the ONE parser that derives that integer from a timestamp string — used by
+ * the schema backfill (`migrateToV26`), the write sites that maintain the
+ * column, and any watermark fallback. It exists because `Date.parse` is WRONG
+ * for the two zone-less shapes aged/imported vaults carry (import stores
+ * frontmatter timestamps verbatim, so non-canonical forms are common):
+ *
+ *   - space-separated `YYYY-MM-DD HH:MM:SS` — implementation-defined per spec;
+ *     V8/Bun parse it as LOCAL time, shifting the epoch by the host's UTC
+ *     offset. This was the live bug — a watermark computed in local time
+ *     skipped or re-delivered rows by whole hours.
+ *   - zone-less ISO `YYYY-MM-DDTHH:MM:SS` — ES2015+ parse date-TIME forms with
+ *     no offset as LOCAL time too.
+ *
+ * Both are interpreted here as UTC. An explicit `Z` or `±HH:MM` offset is
+ * honored. Fractional seconds are truncated (floored) to millisecond
+ * precision. NEVER throws — the caller supplies its own deterministic fallback
+ * for a `null` result (e.g. the row's `created_at` ms, else a stable
+ * sentinel), so a single pathological timestamp can't 400 an entire walk.
+ */
+export function timestampToMs(value: string | null | undefined): number | null {
+  if (typeof value !== "string") return null;
+  const s = value.trim();
+  if (s.length === 0) return null;
+  const m = TIMESTAMP_RE.exec(s);
+  if (m) {
+    const year = Number(m[1]);
+    const month = Number(m[2]) - 1;
+    const day = Number(m[3]);
+    const hour = m[4] !== undefined ? Number(m[4]) : 0;
+    const min = m[5] !== undefined ? Number(m[5]) : 0;
+    const sec = m[6] !== undefined ? Number(m[6]) : 0;
+    // Fractional seconds → ms: right-pad to 3 digits, take the first 3
+    // (millisecond precision; finer digits are floored, not rounded).
+    const ms = m[7] !== undefined ? Number((m[7] + "000").slice(0, 3)) : 0;
+    let epoch = Date.UTC(year, month, day, hour, min, sec, ms);
+    if (!Number.isFinite(epoch)) return null;
+    const zone = m[8];
+    if (zone && zone !== "Z" && zone !== "z") {
+      // `±HH:MM` or `±HHMM` — the wall-clock is stated IN this offset; subtract
+      // it to reach UTC. (`14:30+02:00` is `12:30Z`.)
+      const sign = zone[0] === "-" ? -1 : 1;
+      const digits = zone.slice(1).replace(":", "");
+      const offMin = Number(digits.slice(0, 2)) * 60 + Number(digits.slice(2, 4));
+      epoch -= sign * offMin * 60_000;
+    }
+    return epoch;
+  }
+  // Anything the regex didn't match but that carries an explicit zone marker
+  // (exotic offset spellings, RFC-2822) — trust Date.parse ONLY then, since a
+  // zone-bearing string doesn't hit the local-time trap. Zone-less non-matches
+  // fall through to `null` rather than risk a local-time misread.
+  if (/(?:[Zz]|[+-]\d{2}:?\d{2})$/.test(s)) {
+    const p = Date.parse(s);
+    return Number.isFinite(p) ? p : null;
+  }
+  return null;
+}

package/core/src/hooks.ts

@@ -372,6 +372,15 @@ export class HookRegistry {
 
     // Defer to a microtask so we unwind the caller's stack (and its
     // SQLite transaction, if any) before handlers run.
+    //
+    // Caveat (vault#589): under an ASYNC transaction that spans awaits (the
+    // atomic blow-away import wrapped in `transactionAsync`), the connection
+    // stays open across the microtask boundary. A handler that writes to the
+    // store BEFORE its first real `await` would `SAVEPOINT`-join that open
+    // transaction (rolled back with it). Every handler here is audited safe —
+    // it defers real work behind an `await` (semaphore acquire) and does no
+    // synchronous store write — but the invariant lives in txn.ts's header
+    // ("shared-connection invariant"), not just this comment; keep it true.
     queueMicrotask(() => {
       for (const hook of matches) {
         const task = this.runHandler(hook, event, note, store);

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