@openparachute/vault 0.7.0-rc.1 → 0.7.0-rc.2

package/core/src/cursor.ts

@@ -94,41 +94,59 @@ export function encodeCursor(payload: CursorPayload): string {
   return Buffer.from(json, "utf8").toString("base64url");
 }
 
-/** Decode a cursor string. Throws `CursorError` on any structural problem. */
+/**
+ * Trailing hint appended to every `cursor_invalid` message (vault#550) so a
+ * caller who passed a garbage cursor — or never understood the bootstrap
+ * shape in the first place — gets the actual recovery flow, not just "this
+ * string is broken." The bootstrap flow: an EMPTY string (`cursor: ""` /
+ * `?cursor=`) opts into cursor mode without a watermark yet; the response's
+ * `next_cursor` is what you pass on every call after that.
+ */
+const CURSOR_BOOTSTRAP_HINT =
+  'first call: pass cursor:"" (or omit `cursor` entirely for a plain, non-paginated list); the response carries `next_cursor` — pass that back on each subsequent call to resume from the watermark.';
+
+/**
+ * Decode a cursor string. Throws `CursorError` on any structural problem.
+ * An EMPTY string is deliberately NOT accepted here — callers (queryNotes /
+ * queryNotesPaged) must special-case `opts.cursor === ""` as "cursor mode,
+ * no watermark yet" and skip calling this at all (vault#550 bootstrap fix).
+ * Any caller that reaches this function with an empty string gets the same
+ * loud `cursor_invalid` as any other malformed cursor.
+ */
 export function decodeCursor(cursor: string): CursorPayload {
   if (typeof cursor !== "string" || cursor.length === 0) {
-    throw new CursorError("cursor must be a non-empty string", "cursor_invalid");
+    throw new CursorError(`cursor must be a non-empty string — ${CURSOR_BOOTSTRAP_HINT}`, "cursor_invalid");
   }
   let json: string;
   try {
     json = Buffer.from(cursor, "base64url").toString("utf8");
   } catch {
-    throw new CursorError("cursor is not valid base64url", "cursor_invalid");
+    throw new CursorError(`cursor is not valid base64url — ${CURSOR_BOOTSTRAP_HINT}`, "cursor_invalid");
   }
   let parsed: unknown;
   try {
     parsed = JSON.parse(json);
   } catch {
-    throw new CursorError("cursor payload is not valid JSON", "cursor_invalid");
+    throw new CursorError(`cursor payload is not valid JSON — ${CURSOR_BOOTSTRAP_HINT}`, "cursor_invalid");
   }
   if (!parsed || typeof parsed !== "object") {
-    throw new CursorError("cursor payload must be an object", "cursor_invalid");
+    throw new CursorError(`cursor payload must be an object — ${CURSOR_BOOTSTRAP_HINT}`, "cursor_invalid");
   }
   const p = parsed as Record<string, unknown>;
   if (typeof p.v !== "number" || p.v !== CURSOR_VERSION) {
     throw new CursorError(
-      `cursor schema version mismatch (expected ${CURSOR_VERSION}, got ${String(p.v)})`,
+      `cursor schema version mismatch (expected ${CURSOR_VERSION}, got ${String(p.v)}) — ${CURSOR_BOOTSTRAP_HINT}`,
       "cursor_invalid",
     );
   }
   if (typeof p.last_updated_at !== "number" || !Number.isFinite(p.last_updated_at)) {
-    throw new CursorError("cursor.last_updated_at must be a finite number", "cursor_invalid");
+    throw new CursorError(`cursor.last_updated_at must be a finite number — ${CURSOR_BOOTSTRAP_HINT}`, "cursor_invalid");
   }
   if (typeof p.last_id !== "string") {
-    throw new CursorError("cursor.last_id must be a string", "cursor_invalid");
+    throw new CursorError(`cursor.last_id must be a string — ${CURSOR_BOOTSTRAP_HINT}`, "cursor_invalid");
   }
   if (typeof p.query_hash !== "string" || p.query_hash.length === 0) {
-    throw new CursorError("cursor.query_hash must be a non-empty string", "cursor_invalid");
+    throw new CursorError(`cursor.query_hash must be a non-empty string — ${CURSOR_BOOTSTRAP_HINT}`, "cursor_invalid");
   }
   return {
     v: p.v,

package/core/src/links.ts

@@ -404,6 +404,66 @@ export function traverseLinks(
   return results;
 }
 
+/** Hydrated find-path result — see `hydratePathResult` for field semantics. */
+export interface FindPathResult {
+  /** Note IDs, source → target (unchanged shape — back-compat). */
+  path: string[];
+  /** relationships[i] is the edge connecting path[i] to path[i+1] (unchanged shape). */
+  relationships: string[];
+  /**
+   * Hydrated companion to `path[]` (vault#550, additive): one entry per
+   * node, in the same order, carrying the note's `path` field alongside
+   * its `id` — so a caller doesn't have to round-trip each id through a
+   * separate note fetch just to render a human-legible chain.
+   */
+  nodes: { id: string; path: string | null }[];
+  /**
+   * Hydrated companion to `relationships[]` (vault#550, additive): each
+   * hop as a self-contained `{source, target, relationship}` edge plus
+   * both endpoints' note `path`, so a graph-rendering client can draw the
+   * chain without cross-referencing `nodes`.
+   */
+  edges: {
+    source: string;
+    target: string;
+    relationship: string;
+    sourcePath: string | null;
+    targetPath: string | null;
+  }[];
+}
+
+/**
+ * Hydrate a raw BFS result (`path` ids + `relationships`) with each node's
+ * note `path` field, in ONE batched query (not one fetch per hop). `path`
+ * and `relationships` pass through byte-identical to before this existed —
+ * `nodes`/`edges` are pure additions.
+ */
+function hydratePathResult(db: Database, path: string[], relationships: string[]): FindPathResult {
+  const pathById = new Map<string, string | null>();
+  for (const chunk of chunkForInClause(path)) {
+    const placeholders = chunk.map(() => "?").join(", ");
+    const rows = db.prepare(`SELECT id, path FROM notes WHERE id IN (${placeholders})`).all(...chunk) as
+      { id: string; path: string | null }[];
+    for (const row of rows) pathById.set(row.id, row.path);
+  }
+
+  const nodes = path.map((id) => ({ id, path: pathById.get(id) ?? null }));
+  const edges: FindPathResult["edges"] = [];
+  for (let i = 0; i < path.length - 1; i++) {
+    const source = path[i]!;
+    const target = path[i + 1]!;
+    edges.push({
+      source,
+      target,
+      relationship: relationships[i] ?? "",
+      sourcePath: pathById.get(source) ?? null,
+      targetPath: pathById.get(target) ?? null,
+    });
+  }
+
+  return { path, relationships, nodes, edges };
+}
+
 /**
  * Find a path between two notes in the link graph.
  * Returns the sequence of note IDs from source to target, or null if no path exists.
@@ -413,11 +473,11 @@ export function findPath(
   sourceId: string,
   targetId: string,
   opts?: { max_depth?: number },
-): { path: string[]; relationships: string[] } | null {
+): FindPathResult | null {
   const maxDepth = opts?.max_depth ?? 5;
 
   if (sourceId === targetId) {
-    return { path: [sourceId], relationships: [] };
+    return hydratePathResult(db, [sourceId], []);
   }
 
   // BFS from source
@@ -460,7 +520,7 @@ export function findPath(
             current = entry.parent;
           }
           path.unshift(sourceId);
-          return { path, relationships };
+          return hydratePathResult(db, path, relationships);
         }
       }
     }

package/core/src/mcp.ts

@@ -4,7 +4,8 @@ import { transactionAsync } from "./txn.js";
 import * as noteOps from "./notes.js";
 import { filterMetadata, MAX_BATCH_SIZE, validateExtension, ExtensionValidationError } from "./notes.js";
 import { QueryError } from "./query-operators.js";
-import { TAG_EXPAND_MODES, stripTagHash, type TagExpandMode } from "./tag-hierarchy.js";
+import { TAG_EXPAND_MODES, stripTagHash, suggestSimilarTag, type TagExpandMode } from "./tag-hierarchy.js";
+import { collectUnknownTagWarnings, type QueryWarning } from "./query-warnings.js";
 import * as linkOps from "./links.js";
 import * as tagSchemaOps from "./tag-schemas.js";
 import type { TagFieldSchema } from "./tag-schemas.js";
@@ -237,7 +238,12 @@ Defaults: include_content=true for single note, false for lists. include_links=f
 
 Large notes: pass \`content_offset\` / \`content_length\` (UTF-8 bytes) for a bounded read of note content — the response carries the slice plus \`content_total_length\` and \`content_next_offset\` (null when complete). Loop, feeding \`content_next_offset\` back as \`content_offset\`, to read a note too large for one response.
 
-Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returned content. Tune with \`expand_depth\` (1–3, default 1) and \`expand_mode\` ("full" inlines full content, "summary" inlines only metadata.summary). Expansions are deduplicated across the query and cycle-guarded.`,
+Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returned content. Tune with \`expand_depth\` (1–3, default 1) and \`expand_mode\` ("full" inlines full content, "summary" inlines only metadata.summary). Expansions are deduplicated across the query and cycle-guarded.
+
+Response shape (vault#550 — three variants, pick by what you passed):
+- Default (no \`cursor\`, no warnings): a bare array of notes.
+- Cursor mode (\`cursor\` param present — including \`cursor: ""\` to bootstrap): \`{notes: [...], next_cursor}\`. See \`cursor\` below for the bootstrap flow.
+- Warnings present (e.g. an unrecognized \`tag\`) and NOT in cursor mode: \`{notes: [...], warnings: [...]}\`. Cursor mode + warnings compose: \`{notes, next_cursor, warnings}\`. Absent \`warnings\` key means nothing to flag — don't assume its presence either way.`,
       inputSchema: {
         type: "object",
         properties: {
@@ -328,7 +334,7 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
           cursor: {
             type: "string",
             description:
-              "Opaque cursor for 'since last checked' agent loops (vault#313). First call: omit. The response will include `next_cursor` — pass it on the subsequent call to receive only notes created or updated since the prior page. The cursor binds to the query's filters (tag, path, metadata, etc.); changing them between calls returns a structured `cursor_query_mismatch` error. Pagination via cursor orders results by `updated_at ASC` and is mutually exclusive with `order_by` and `sort: \"desc\"`. The response shape switches to `{notes, next_cursor}` when this parameter is present.",
+              "Opaque cursor for 'since last checked' agent loops (vault#313). Bootstrap flow (vault#550): FIRST call passes `cursor: \"\"` (empty string) — this opts into cursor mode with no watermark yet and the response comes back as `{notes, next_cursor}`. Persist `next_cursor` and pass it back verbatim as `cursor` on every SUBSEQUENT call to receive only notes created or updated since the prior page. Omitting `cursor` entirely (not passing the key at all) is a DIFFERENT thing — a plain one-shot list with no cursor envelope and no way to resume; use that when you don't want pagination at all. The cursor binds to the query's filters (tag, path, metadata, etc.); changing them between calls returns a structured `cursor_query_mismatch` error, and a malformed/expired cursor returns `cursor_invalid` naming the bootstrap flow again. Pagination via cursor orders results by `updated_at ASC` and is mutually exclusive with `order_by` and `sort: \"desc\"`.",
           },
           include_content: { type: "boolean", description: "Include note content (default: true for single, false for list)" },
           content_offset: {
@@ -466,7 +472,11 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
         // neighborhood every call to be cursor-stable; we punt for now).
         // Both surface as INVALID_QUERY rather than silently returning
         // wrong rows.
-        const cursorMode = typeof params.cursor === "string" && params.cursor.length > 0;
+        // Presence, not truthiness (vault#550 bootstrap fix) — `cursor: ""`
+        // is the bootstrap call ("I want to paginate, no watermark yet") and
+        // must still engage cursor mode. Before this fix `"".length > 0` was
+        // false, so the very first call could never obtain a `next_cursor`.
+        const cursorMode = typeof params.cursor === "string";
         if (cursorMode && params.search) {
           throw new QueryError(
             `cursor is incompatible with full-text search — FTS has its own ordering. Use date_filter on updated_at for since-last-checked search.`,
@@ -495,6 +505,14 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
         // --- Full-text search ---
         let results: Note[];
         let nextCursor: string | null = null;
+        // Warnings channel (vault#550) — structured-query only for this
+        // wave; `search=` is out of scope (see #551). Scope-unaware by
+        // design (see `core/src/query-warnings.ts` doc comment) — a
+        // tag-scoped MCP session gets these stripped by the
+        // `applyTagScopeWrappers` query-notes wrapper in `src/mcp-tools.ts`
+        // before the result reaches the caller, so an out-of-scope tag name
+        // never leaks via `did_you_mean`.
+        let queryWarnings: QueryWarning[] = [];
         if (params.search) {
           // Normalize tag param
           const tags = normalizeTags(params.tag);
@@ -556,6 +574,7 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
             offset: params.offset as number | undefined,
             cursor: cursorMode ? (params.cursor as string) : undefined,
           };
+          queryWarnings = collectUnknownTagWarnings(db, queryOpts.tags, queryOpts.expand, store.getTagHierarchy());
           if (cursorMode) {
             const page = await store.queryNotesPaged(queryOpts);
             results = page.notes;
@@ -637,13 +656,29 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
           }
           // Cursor mode wraps the list in `{notes, next_cursor}` so callers can
           // chain calls without tracking a watermark client-side. Legacy
-          // callers (no `cursor` param) still get the flat array.
-          if (cursorMode) return { notes: enrichedOut, next_cursor: nextCursor };
-          return enrichedOut;
+          // callers (no `cursor` param, no warnings) still get the flat
+          // array (vault#550 — warnings channel is additive, never forces
+          // the envelope on its own outside cursor mode... except when
+          // there ARE warnings, in which case the envelope is the only way
+          // to attach them).
+          if (cursorMode) {
+            return {
+              notes: enrichedOut,
+              next_cursor: nextCursor,
+              ...(queryWarnings.length > 0 ? { warnings: queryWarnings } : {}),
+            };
+          }
+          return queryWarnings.length > 0 ? { notes: enrichedOut, warnings: queryWarnings } : enrichedOut;
         }
 
-        if (cursorMode) return { notes: output, next_cursor: nextCursor };
-        return output;
+        if (cursorMode) {
+          return {
+            notes: output,
+            next_cursor: nextCursor,
+            ...(queryWarnings.length > 0 ? { warnings: queryWarnings } : {}),
+          };
+        }
+        return queryWarnings.length > 0 ? { notes: output, warnings: queryWarnings } : output;
       },
     },
 
@@ -1353,7 +1388,7 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
     {
       name: "list-tags",
       requiredVerb: "read",
-      description: `List tags with usage counts. Pass \`tag\` to get a single tag's full record (description, fields, relationships, parent_names, timestamps). Pass \`include_schema: true\` to include the full record for every tag.`,
+      description: `List tags with usage counts. Each row carries \`count\` (notes carrying the EXACT tag) and \`expanded_count\` (vault#550 — distinct notes matching the tag OR any transitive descendant under the default subtypes expansion; use this to see a parent tag's true rollup when its notes are actually tagged with a more specific child). Pass \`tag\` to get a single tag's full record (description, fields, relationships, parent_names, timestamps) — errors with \`error_type: "tag_not_found"\` (plus a \`did_you_mean\` hint when a close match exists) if the tag has no identity row and no notes. Pass \`include_schema: true\` to include the full record for every tag.`,
       inputSchema: {
         type: "object",
         properties: {
@@ -1368,9 +1403,30 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
           const allTags = noteOps.listTags(db);
           const found = allTags.find((t) => t.name === singleTag);
           const record = tagSchemaOps.getTagRecord(db, singleTag);
+          // vault#550 — a tag with no identity row AND no note carrying it
+          // isn't a legitimate (if empty) tag, it's a typo or a tag from a
+          // different vault. Return a structured miss instead of a
+          // synthesized all-null 200. `did_you_mean` searches the full
+          // vault-wide tag catalog — core is scope-unaware by architecture.
+          // Tag-scope enforcement lives in the server layer's list-tags
+          // wrapper (src/mcp-tools.ts:applyTagScopeWrappers): a scoped
+          // session's out-of-scope `tag` param short-circuits to
+          // tag_not_found BEFORE this executes, and an in-scope miss gets
+          // its `did_you_mean` dropped unless the suggestion is also
+          // in-scope.
+          if (!found && !record) {
+            const suggestion = suggestSimilarTag(allTags.map((t) => t.name), singleTag);
+            return {
+              error: "Tag not found",
+              error_type: "tag_not_found",
+              tag: singleTag,
+              ...(suggestion ? { did_you_mean: suggestion } : {}),
+            };
+          }
           return {
             name: singleTag,
             count: found?.count ?? 0,
+            expanded_count: found?.expanded_count ?? 0,
             description: record?.description ?? null,
             fields: record?.fields ?? null,
             relationships: record?.relationships ?? null,
@@ -1589,7 +1645,7 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
     {
       name: "find-path",
       requiredVerb: "read",
-      description: "Find the shortest path between two notes in the link graph. Accepts IDs or paths. Returns the chain of note IDs and relationships, or null if no path exists.",
+      description: "Find the shortest path between two notes in the link graph. Accepts IDs or paths. Returns null if no path exists, else `{path, relationships, nodes, edges}`: `path` (note IDs, source→target) and `relationships` (relationships[i] connects path[i] to path[i+1]) are the original id-only shape; `nodes` (vault#550, additive) hydrates each id in `path` with the note's own `path` field — `[{id, path}]` in the same order; `edges` (additive) is the self-contained hop list — `[{source, target, relationship, sourcePath, targetPath}]` — for rendering the chain without cross-referencing `nodes`.",
       inputSchema: {
         type: "object",
         properties: {

package/core/src/notes.ts

@@ -20,7 +20,7 @@ import {
   type QueryHashInputs,
 } from "./cursor.js";
 import { getIndexedField, releaseField } from "./indexed-fields.js";
-import { stripTagHash } from "./tag-hierarchy.js";
+import { computeExpandedTagCounts, loadTagHierarchy, stripTagHash } from "./tag-hierarchy.js";
 import { chunkForInClause, IN_VIA_JSON_EACH, jsonEachParam } from "./sql-in.js";
 
 let idCounter = 0;
@@ -684,7 +684,78 @@ export function deleteNote(db: Database, id: string): void {
   db.prepare("DELETE FROM notes WHERE id = ?").run(id);
 }
 
+/**
+ * Validate `limit`/`offset` before any query work (vault#550). A negative
+ * `limit` used to leak SQLite's "negative LIMIT means unlimited" semantics
+ * straight through to the caller — silently returning EVERYTHING when the
+ * caller almost certainly meant "no limit I typed by mistake." A
+ * non-numeric value (a bad MCP param type, or a REST caller that slipped
+ * past `parseNotesQueryOpts`'s own stricter check) used to silently fall
+ * back to the default via `typeof opts.limit === "number" ? opts.limit :
+ * 100` below — also silent-wrong. This is the single choke point BOTH
+ * transports funnel through (`store.queryNotes` / `store.queryNotesPaged`
+ * call this via `queryNotes`), so REST and MCP get identical validation
+ * for free.
+ */
+function validateLimitOffset(opts: QueryOpts): void {
+  if (opts.limit !== undefined) {
+    if (typeof opts.limit !== "number" || !Number.isFinite(opts.limit) || !Number.isInteger(opts.limit) || opts.limit < 0) {
+      throw new QueryError(
+        `invalid limit: ${JSON.stringify(opts.limit)} — must be a non-negative integer (a negative LIMIT silently means "unlimited" in SQLite semantics, which is almost never what was intended). Omit for the default of 50.`,
+        "INVALID_QUERY",
+        {
+          error_type: "invalid_query",
+          field: "limit",
+          got: opts.limit,
+          hint: "pass a non-negative integer, or omit for the default",
+        },
+      );
+    }
+  }
+  if (opts.offset !== undefined) {
+    if (typeof opts.offset !== "number" || !Number.isFinite(opts.offset) || !Number.isInteger(opts.offset) || opts.offset < 0) {
+      throw new QueryError(
+        `invalid offset: ${JSON.stringify(opts.offset)} — must be a non-negative integer.`,
+        "INVALID_QUERY",
+        {
+          error_type: "invalid_query",
+          field: "offset",
+          got: opts.offset,
+          hint: "pass a non-negative integer, or omit for the default of 0",
+        },
+      );
+    }
+  }
+}
+
+/**
+ * Validate an ISO-8601 date-filter value before it's bound into a SQL
+ * comparison (vault#550). `n.created_at` / `n.updated_at` are TEXT columns
+ * compared lexicographically; an unparseable value used to bind straight
+ * through and silently match "nothing" or "everything" depending on how it
+ * happened to sort against real ISO strings, rather than erroring. Applies
+ * uniformly to BOTH `dateFilter` (bracket-style REST / MCP `date_filter`)
+ * and the legacy `dateFrom`/`dateTo` shorthand (MCP `date_from`/`date_to`,
+ * still supported) — both flow through this same function, so both get the
+ * same loud validation from one place.
+ */
+function validateIsoDateValue(field: string, value: string): void {
+  if (Number.isNaN(Date.parse(value))) {
+    throw new QueryError(
+      `invalid date value for "${field}": ${JSON.stringify(value)} — must be an ISO-8601 date/timestamp (e.g. "2026-07-09" or "2026-07-09T00:00:00.000Z").`,
+      "INVALID_QUERY",
+      {
+        error_type: "invalid_query",
+        field,
+        got: value,
+        hint: "pass an ISO-8601 date or timestamp",
+      },
+    );
+  }
+}
+
 export function queryNotes(db: Database, opts: QueryOpts): Note[] {
+  validateLimitOffset(opts);
   const conditions: string[] = [];
   const params: SQLQueryBindings[] = [];
 
@@ -920,19 +991,23 @@ export function queryNotes(db: Database, opts: QueryOpts): Note[] {
       column = `"meta_${field}"`;
     }
     if (filter.from !== undefined) {
+      validateIsoDateValue(field === "created_at" ? "date_filter.from" : `date_filter.from (${field})`, filter.from);
       conditions.push(`${column} >= ?`);
       params.push(filter.from);
     }
     if (filter.to !== undefined) {
+      validateIsoDateValue(field === "created_at" ? "date_filter.to" : `date_filter.to (${field})`, filter.to);
       conditions.push(`${column} < ?`);
       params.push(filter.to);
     }
   } else if (hasLegacyDate) {
     if (opts.dateFrom) {
+      validateIsoDateValue("date_from", opts.dateFrom);
       conditions.push("n.created_at >= ?");
       params.push(opts.dateFrom);
     }
     if (opts.dateTo) {
+      validateIsoDateValue("date_to", opts.dateTo);
       conditions.push("n.created_at < ?");
       params.push(opts.dateTo);
     }
@@ -940,8 +1015,22 @@ 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:
+  // Cursor mode is keyed on PRESENCE of `opts.cursor`, not truthiness
+  // (vault#550 bootstrap fix). `cursor: ""` is the bootstrap call — "I want
+  // to paginate, I don't have a watermark yet" — and must still force the
+  // keyset ORDER BY below so the FIRST page is taken in the same order
+  // subsequent pages will be. `opts.cursor === undefined` is the only way
+  // to opt OUT of cursor mode entirely (the legacy flat-array shape).
+  // 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,
+  // so naive "did I see this note already" comparisons could skip or
+  // duplicate rows across the boundary.
+  //
+  // 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)
@@ -953,8 +1042,9 @@ export function queryNotes(db: Database, opts: QueryOpts): Note[] {
   // 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.
+  const cursorMode = opts.cursor !== undefined;
   let cursorPayload: CursorPayload | null = null;
-  if (opts.cursor) {
+  if (cursorMode) {
     if (opts.orderBy) {
       throw new QueryError(
         `cursor and order_by are mutually exclusive — cursor pagination forces order by updated_at`,
@@ -967,33 +1057,39 @@ export function queryNotes(db: Database, opts: QueryOpts): Note[] {
         "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",
+    if (opts.cursor !== "") {
+      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);
     }
-    // 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);
+    // else: bootstrap call (`cursor === ""`) — no watermark yet, no
+    // predicate to add, but the ORDER BY below still switches to the
+    // keyset order so this first page is consistent with every page after
+    // it.
   }
 
   const direction = opts.sort === "desc" ? "DESC" : "ASC";
   let orderBy: string;
-  if (opts.cursor) {
+  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
@@ -1177,7 +1273,11 @@ export function queryNotesPaged(db: Database, opts: QueryOpts): QueryNotesPage {
   // cursor's watermark — see the JSDoc rationale above.
   let lastUpdatedAt = 0;
   let lastId = "";
-  if (opts.cursor) {
+  // `opts.cursor === ""` is the bootstrap call (vault#550) — there's no
+  // prior watermark to decode, so it takes the same 0/"" sentinel path as
+  // `opts.cursor === undefined`. Only a REAL (non-empty) cursor gets
+  // re-decoded here.
+  if (opts.cursor !== undefined && opts.cursor !== "") {
     // Re-decode (we already validated in queryNotes); this is cheap.
     const prior = decodeCursor(opts.cursor);
     lastUpdatedAt = prior.last_updated_at;
@@ -1303,7 +1403,18 @@ export function getNoteTags(db: Database, noteId: string): string[] {
   return rows.map((r) => r.tag_name);
 }
 
-export function listTags(db: Database): { name: string; count: number }[] {
+/**
+ * List every declared tag with its literal `count` (notes carrying that
+ * EXACT tag name) and its `expanded_count` (vault#550) — distinct notes
+ * matching the tag OR any transitive descendant under the DEFAULT
+ * (subtypes) expansion axis. `expanded_count` is what surfaces a parent
+ * tag as non-empty even when every one of its notes is actually tagged
+ * with a more specific child tag — `count` alone reports 0 for that
+ * parent, which reads as "this tag is dead" when it's really just a
+ * rollup label. See `computeExpandedTagCounts` for the single-pass
+ * (no N+1) computation.
+ */
+export function listTags(db: Database): { name: string; count: number; expanded_count: number }[] {
   const rows = db.prepare(`
     SELECT t.name, COUNT(nt.note_id) as count
     FROM tags t
@@ -1311,7 +1422,10 @@ export function listTags(db: Database): { name: string; count: number }[] {
     GROUP BY t.name
     ORDER BY t.name
   `).all() as { name: string; count: number }[];
-  return rows;
+
+  const h = loadTagHierarchy(db);
+  const expandedCounts = computeExpandedTagCounts(db, h);
+  return rows.map((r) => ({ ...r, expanded_count: expandedCounts.get(r.name) ?? 0 }));
 }
 
 export function deleteTag(db: Database, name: string): { deleted: boolean; notes_untagged: number } {

package/core/src/query-operators.ts

@@ -37,9 +37,26 @@ const OPS_SET: ReadonlySet<string> = new Set<string>(SUPPORTED_OPS);
 export class QueryError extends Error {
   override name = "QueryError";
   code: string;
-  constructor(message: string, code = "INVALID_QUERY") {
+  /**
+   * Structured `error_type` for the honest-queries validation errors
+   * (vault#550 — `limit`/`offset`/date-value validation). Optional: the
+   * long-standing QueryError call sites (FIELD_NOT_INDEXED,
+   * UNKNOWN_OPERATOR, generic INVALID_QUERY combos) leave this unset and
+   * keep their existing `{error, code}` response shape — only the new #550
+   * call sites opt into the richer `{error_type, field, got, hint}` shape.
+   */
+  error_type?: string;
+  field?: string;
+  got?: unknown;
+  hint?: string;
+  constructor(
+    message: string,
+    code = "INVALID_QUERY",
+    extra?: { error_type?: string; field?: string; got?: unknown; hint?: string },
+  ) {
     super(message);
     this.code = code;
+    if (extra) Object.assign(this, extra);
   }
 }