@openparachute/vault 0.7.0-rc.9 → 0.7.2-rc.3

package/core/src/notes.ts

@@ -1,5 +1,5 @@
 import { Database, type SQLQueryBindings } from "bun:sqlite";
-import type { Note, NoteIndex, QueryOpts, QueryNotesPage, VaultStats } from "./types.js";
+import type { Note, NoteIndex, QueryOpts, QueryNotesPage, VaultStats, VaultMap, AggregateSpec, AggregateRow } from "./types.js";
 import { normalizePath } from "./paths.js";
 import { transaction } from "./txn.js";
 import {
@@ -14,8 +14,7 @@ import {
   computeQueryHash,
   decodeCursor,
   encodeCursor,
-  isoToMillis,
-  millisToIso,
+  timestampToMs,
   type CursorPayload,
   type QueryHashInputs,
 } from "./cursor.js";
@@ -28,8 +27,7 @@ import {
   SEARCH_WEIGHT_CONTENT,
   type SearchMode,
 } from "./search-query.js";
-
-let idCounter = 0;
+import { generateUlid } from "./ulid.js";
 
 /**
  * Write-attribution context (vault#298) — the two axes of provenance threaded
@@ -61,20 +59,25 @@ function attrValue(v: string | null | undefined): string | null {
   return t.length === 0 ? null : t;
 }
 
-/** Generate a timestamp-based ID: YYYY-MM-DD-HH-MM-SS-ffffff */
+/**
+ * Generate a new note/attachment ID.
+ *
+ * As of vault#ulid-ids this returns a ULID (see `ulid.ts`) — monotonic,
+ * lexicographically time-sortable, Crockford base32, opaque, and
+ * collision-resistant. Previously this returned a timestamp-format ID
+ * (`YYYY-MM-DD-HH-MM-SS-ffffff`).
+ *
+ * IMPORTANT: existing notes are NOT migrated. Old timestamp-format IDs
+ * stay exactly as they are — only newly-generated IDs use the ULID
+ * format, so a vault's `id` column is (and must remain) a mix of both
+ * shapes indefinitely. Nothing may assume a uniform id format, and
+ * nothing may parse a note's ID to recover its creation time — that's
+ * what the `created_at` column is for. The cursor-pagination tiebreaker
+ * (`cursor.ts`) treats `id` as an opaque, stable string for ordering
+ * ties only, which holds for any id format.
+ */
 export function generateId(): string {
-  const now = new Date();
-  const pad = (n: number, len = 2) => String(n).padStart(len, "0");
-  const micro = now.getMilliseconds() * 1000 + (idCounter++ % 1000);
-  return [
-    now.getFullYear(),
-    pad(now.getMonth() + 1),
-    pad(now.getDate()),
-    pad(now.getHours()),
-    pad(now.getMinutes()),
-    pad(now.getSeconds()),
-    pad(micro, 6),
-  ].join("-");
+  return generateUlid();
 }
 
 export function createNote(
@@ -111,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);
@@ -183,6 +194,66 @@ export function getNoteByPath(db: Database, path: string, extension?: string): N
   );
 }
 
+/**
+ * Extract a note's "H1 title" — the first line in `content` that starts
+ * with a literal `"# "` (a level-1 Markdown heading; `"## "`+ don't match
+ * because `^#[ \t]` fails at that line's start once a second `#` follows
+ * the first). Returns null when no such line exists, or the text after
+ * the marker is blank once trimmed.
+ */
+export function extractH1Title(content: string): string | null {
+  const match = content.match(/^#[ \t]+(.+)$/m);
+  if (!match) return null;
+  const title = match[1]!.trim();
+  return title.length > 0 ? title : null;
+}
+
+/**
+ * Find every note whose H1 title (see {@link extractH1Title}) equals
+ * `title`, case-insensitively (matches the COLLATE NOCASE policy every
+ * other path/basename lookup in this file uses). Used as the title-fallback
+ * step for wikilink/id/path resolution — a target that misses on
+ * id/path/basename gets one more chance against notes whose displayed
+ * title differs from their path.
+ *
+ * This is a full-content scan: no index exists on "first heading line," so
+ * every note's content is read once and matched in JS. Acceptable because
+ * every call site reaches this ONLY after the cheap indexed lookups (id,
+ * path, basename) have already missed — a rare fallback path, not the hot
+ * resolution route.
+ */
+export function findNotesByTitle(db: Database, title: string): { id: string; path: string | null }[] {
+  const needle = title.trim().toLowerCase();
+  if (!needle) return [];
+  const rows = db.prepare("SELECT id, path, content FROM notes").all() as {
+    id: string;
+    path: string | null;
+    content: string;
+  }[];
+  const matches: { id: string; path: string | null }[] = [];
+  for (const row of rows) {
+    const h1 = extractH1Title(row.content);
+    if (h1 && h1.toLowerCase() === needle) {
+      matches.push({ id: row.id, path: row.path });
+    }
+  }
+  return matches;
+}
+
+/**
+ * Title-fallback lookup: resolve `title` to a note ONLY when exactly one
+ * note in the vault carries that H1 title (see {@link findNotesByTitle}).
+ * Zero matches or 2+ matches (ambiguous) both return null — "don't guess"
+ * mirrors the existing basename-ambiguity policy (vault#328). Callers use
+ * this as the LAST resort after id and path/basename resolution have
+ * already missed; exact id/path matches always win first.
+ */
+export function getNoteByTitle(db: Database, title: string): Note | null {
+  const matches = findNotesByTitle(db, title);
+  if (matches.length !== 1) return null;
+  return getNote(db, matches[0]!.id);
+}
+
 export function getNotes(db: Database, ids: string[]): Note[] {
   if (ids.length === 0) return [];
   // Dedupe before chunking: a duplicate id straddling two chunk boundaries
@@ -402,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
@@ -478,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.
@@ -496,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
@@ -769,8 +905,20 @@ function validateIsoDateValue(field: string, value: string): void {
   }
 }
 
-export function queryNotes(db: Database, opts: QueryOpts): Note[] {
-  validateLimitOffset(opts);
+/**
+ * Build the shared WHERE-clause conditions + bound params for the filter
+ * surface both `queryNotes` and `aggregateNotes` apply: tag membership
+ * (include/exclude/presence), link/broken-link presence, id-set scoping,
+ * exact path / path-prefix / extension, write-attribution, metadata
+ * (operator + plain-equality), and date range. Does NOT include the
+ * cursor-keyset predicate, ORDER BY, or LIMIT/OFFSET — those are
+ * query-shape concerns specific to `queryNotes`'s paginated-list contract
+ * and don't apply to an aggregate rollup (which spans every matching row,
+ * not a page of them). Extracted so aggregation reuses the EXACT filter
+ * semantics a normal query applies, rather than risking the two drifting
+ * apart.
+ */
+function buildFilterConditions(db: Database, opts: QueryOpts): { conditions: string[]; params: SQLQueryBindings[] } {
   const conditions: string[] = [];
   const params: SQLQueryBindings[] = [];
 
@@ -1024,6 +1172,11 @@ export function queryNotes(db: Database, opts: QueryOpts): Note[] {
     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
@@ -1054,7 +1207,22 @@ export function queryNotes(db: Database, opts: QueryOpts): Note[] {
     }
   }
 
-  // ---- Cursor predicate (vault#313) ----
+  return { conditions, params };
+}
+
+/**
+ * `_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; 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
@@ -1065,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) {
@@ -1107,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
@@ -1131,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
@@ -1190,18 +1370,156 @@ 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));
 }
 
+/**
+ * Aggregation / rollup query (top new-feature ask from a UX round — see
+ * `QueryOpts.aggregate` / `AggregateSpec` in types.ts). Applies the SAME
+ * filter surface `queryNotes` does — via the shared `buildFilterConditions`:
+ * tags, exclude-tags, presence filters, `ids`, path/extension, write-
+ * attribution, metadata, date range — BEFORE grouping, so aggregating over a
+ * filtered query rolls up exactly the notes that query would have listed.
+ *
+ * Tag-scope is NOT enforced here — core stays scope-unaware, same division
+ * every other core query surface keeps. A tag-scoped caller narrows via
+ * `opts.ids` to a pre-computed visible-note-id set (see `src/mcp-tools.ts`'s
+ * `aggregateVisibility` wiring for MCP and `src/routes.ts`'s REST aggregate
+ * branch — both filter to visible notes FIRST, then pass the resulting ids
+ * in here, exactly like a normal query's `near` neighborhood scoping does).
+ *
+ * `group_by: "tag"` groups by tag MEMBERSHIP, not partition: implemented as
+ * a JOIN against `note_tags`, so a note carrying N of the tags present in
+ * the filtered result set contributes to N separate group rows (the
+ * existing filter conditions, which reference `n.*`, compose unchanged
+ * against the join). Any other `group_by` value must be a declared
+ * `indexed: true` metadata field — reuses `requireIndexedField`, the same
+ * FIELD_NOT_INDEXED contract `metadata` operator queries and `order_by`
+ * use — and groups by its generated `meta_<field>` column.
+ *
+ * `op: "sum"` requires `field` — another indexed field whose declared
+ * storage type is `INTEGER` (the only indexable numeric shape; a bare
+ * `type: "number"` schema field is never indexed — see
+ * `indexed-fields.ts`'s `TYPE_MAP` — and a `TEXT`-backed field can't be
+ * summed). `op: "count"` ignores `field`.
+ *
+ * A note whose group_by value is absent/null collects into one
+ * `{group: null, ...}` row — standard SQL `GROUP BY` behavior, not silently
+ * dropped.
+ */
+export function aggregateNotes(db: Database, opts: QueryOpts): AggregateRow[] {
+  const spec = opts.aggregate;
+  if (!spec) {
+    throw new QueryError(
+      `aggregateNotes requires opts.aggregate`,
+      "INVALID_QUERY",
+      {
+        error_type: "invalid_query",
+        field: "aggregate",
+        hint: `pass { group_by, op } — group_by is an indexed metadata field or "tag"; op is "count" or "sum"`,
+      },
+    );
+  }
+  if (typeof spec.group_by !== "string" || spec.group_by.length === 0) {
+    throw new QueryError(
+      `aggregate.group_by is required — an indexed metadata field name, or "tag"`,
+      "INVALID_QUERY",
+      {
+        error_type: "invalid_query",
+        field: "aggregate.group_by",
+        got: spec.group_by,
+        hint: `pass an indexed metadata field name, or "tag"`,
+      },
+    );
+  }
+  if (spec.op !== "count" && spec.op !== "sum") {
+    throw new QueryError(
+      `invalid aggregate.op: ${JSON.stringify(spec.op)} — must be "count" or "sum"`,
+      "INVALID_QUERY",
+      { error_type: "invalid_query", field: "aggregate.op", got: spec.op, hint: `pass "count" or "sum"` },
+    );
+  }
+  if (spec.op === "sum" && (typeof spec.field !== "string" || spec.field.length === 0)) {
+    throw new QueryError(
+      `aggregate.field is required when aggregate.op is "sum"`,
+      "INVALID_QUERY",
+      {
+        error_type: "invalid_query",
+        field: "aggregate.field",
+        hint: "pass the indexed numeric metadata field to sum",
+      },
+    );
+  }
+
+  const { conditions, params } = buildFilterConditions(db, opts);
+
+  const groupByTag = spec.group_by === "tag";
+  let groupExpr: string;
+  let fromClause: string;
+  if (groupByTag) {
+    groupExpr = "nt.tag_name";
+    fromClause = "FROM notes n JOIN note_tags nt ON nt.note_id = n.id";
+  } else {
+    // `group_by` came from indexed_fields (validated via FIELD_NAME_RE at
+    // declaration time), so interpolating the column name is safe — same
+    // justification `orderBy`/`buildOperatorClause` use.
+    requireIndexedField(db, spec.group_by);
+    groupExpr = `"meta_${spec.group_by}"`;
+    fromClause = "FROM notes n";
+  }
+
+  let valueExpr: string;
+  if (spec.op === "count") {
+    valueExpr = "COUNT(*)";
+  } else {
+    const fieldInfo = requireIndexedField(db, spec.field!);
+    if (fieldInfo.sqliteType !== "INTEGER") {
+      throw new QueryError(
+        `aggregate.field "${spec.field}" is not numeric (declared sqlite type ${fieldInfo.sqliteType}) — "sum" requires a field declared type: "integer" or "boolean" in its tag schema`,
+        "INVALID_QUERY",
+        {
+          error_type: "invalid_query",
+          field: "aggregate.field",
+          got: spec.field,
+          hint: `sum requires a numeric indexed field (type: "integer"/"boolean"); "${spec.field}" is declared a non-numeric type`,
+        },
+      );
+    }
+    valueExpr = `SUM("meta_${spec.field}")`;
+  }
+
+  const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+  const sql = `
+    SELECT ${groupExpr} AS group_key, ${valueExpr} AS value
+    ${fromClause}
+    ${whereClause}
+    GROUP BY ${groupExpr}
+    ORDER BY ${groupExpr}
+  `;
+  const rows = db.prepare(sql).all(...params) as { group_key: string | number | null; value: number | null }[];
+  return rows.map((r) => ({ group: r.group_key, value: r.value ?? 0 }));
+}
+
 /**
  * Fetch full note rows for `ids`, preserving the input order, with tags
  * hydrated via ONE batched query per chunk (not one per note). Ids not
@@ -1307,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
@@ -1326,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;
@@ -1831,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 = ?",
     );
@@ -1958,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++;
       }
     }
@@ -1979,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++;
       }
     }
@@ -2359,6 +2694,122 @@ export function getVaultStats(
   };
 }
 
+// ---- Vault map (front-door structural orientation) ----
+
+/** Shared bucket-expression for the top-level path segment: the text before
+ *  the first `/`, or the whole path when it has none. Applied to whichever
+ *  `path` column reference the caller substitutes in (`path` or `n.path`). */
+function pathBucketExpr(pathCol: string): string {
+  return `CASE WHEN instr(${pathCol}, '/') > 0 THEN substr(${pathCol}, 1, instr(${pathCol}, '/') - 1) ELSE ${pathCol} END`;
+}
+
+/**
+ * Compute the compact structural map `vault-info` surfaces for one-call
+ * orientation: total note count, every tag currently carried by at least one
+ * note with its membership count, and every top-level path "bucket" (the
+ * first `/`-delimited segment of `path`) with its note count — plus a count
+ * of notes with no path at all (excluded from `path_buckets`, nothing to
+ * bucket). Counts only, no content; three grouped-COUNT queries, safe on
+ * large vaults.
+ *
+ * `opts.tagFilter`, when the KEY IS PRESENT, restricts every count to notes
+ * reachable through that exact tag-name set (an `IN`-clause join through
+ * `note_tags`) — the scope-aware path a tag-scoped caller's already-expanded
+ * allowlist takes (server layer; core stays scope-unaware, it just filters
+ * by the plain tag-name list it's given). An empty array is a valid,
+ * meaningful filter — "nothing is in scope" — and short-circuits to an
+ * all-zero map WITHOUT falling through to the unfiltered/full-vault query;
+ * only OMITTING `tagFilter` entirely computes the vault-wide map.
+ */
+export function getVaultMap(
+  db: Database,
+  opts?: { tagFilter?: string[] },
+): VaultMap {
+  const hasFilter = opts !== undefined && opts.tagFilter !== undefined;
+  const tagFilter = opts?.tagFilter ?? [];
+
+  if (hasFilter && tagFilter.length === 0) {
+    return { total_notes: 0, tags: [], path_buckets: [], unfiled_notes: 0 };
+  }
+
+  if (hasFilter) {
+    const placeholders = tagFilter.map(() => "?").join(",");
+
+    const totalRow = db
+      .prepare(`SELECT COUNT(DISTINCT note_id) as c FROM note_tags WHERE tag_name IN (${placeholders})`)
+      .get(...tagFilter) as { c: number };
+
+    const tagRows = db
+      .prepare(
+        `SELECT tag_name AS name, COUNT(*) AS count
+         FROM note_tags
+         WHERE tag_name IN (${placeholders})
+         GROUP BY tag_name
+         ORDER BY count DESC, name ASC`,
+      )
+      .all(...tagFilter) as { name: string; count: number }[];
+
+    const bucketRows = db
+      .prepare(
+        `SELECT ${pathBucketExpr("n.path")} AS name, COUNT(DISTINCT n.id) AS count
+         FROM notes n
+         JOIN note_tags nt ON nt.note_id = n.id
+         WHERE nt.tag_name IN (${placeholders}) AND n.path IS NOT NULL
+         GROUP BY name
+         ORDER BY count DESC, name ASC`,
+      )
+      .all(...tagFilter) as { name: string; count: number }[];
+
+    const unfiledRow = db
+      .prepare(
+        `SELECT COUNT(DISTINCT n.id) as c
+         FROM notes n
+         JOIN note_tags nt ON nt.note_id = n.id
+         WHERE nt.tag_name IN (${placeholders}) AND n.path IS NULL`,
+      )
+      .get(...tagFilter) as { c: number };
+
+    return {
+      total_notes: totalRow.c,
+      tags: tagRows,
+      path_buckets: bucketRows,
+      unfiled_notes: unfiledRow.c,
+    };
+  }
+
+  const totalRow = db.prepare("SELECT COUNT(*) as c FROM notes").get() as { c: number };
+
+  const tagRows = db
+    .prepare(
+      `SELECT tag_name AS name, COUNT(*) AS count
+       FROM note_tags
+       GROUP BY tag_name
+       ORDER BY count DESC, name ASC`,
+    )
+    .all() as { name: string; count: number }[];
+
+  const bucketRows = db
+    .prepare(
+      `SELECT ${pathBucketExpr("path")} AS name, COUNT(*) AS count
+       FROM notes
+       WHERE path IS NOT NULL
+       GROUP BY name
+       ORDER BY count DESC, name ASC`,
+    )
+    .all() as { name: string; count: number }[];
+
+  const unfiledRow = db
+    .prepare("SELECT COUNT(*) as c FROM notes WHERE path IS NULL")
+    .get() as { c: number };
+
+  return {
+    total_notes: totalRow.c,
+    tags: tagRows,
+    path_buckets: bucketRows,
+    unfiled_notes: unfiledRow.c,
+  };
+}
+
 // ---- Bulk Operations ----
 
 export interface BulkNoteInput {