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

package/core/src/notes.ts

@@ -20,8 +20,9 @@ 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";
+import { buildLiteralSearchQuery, type SearchMode } from "./search-query.js";
 
 let idCounter = 0;
 
@@ -684,7 +685,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 +992,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 +1016,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 +1043,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 +1058,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 +1274,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;
@@ -1209,12 +1310,78 @@ export function queryNotesPaged(db: Database, opts: QueryOpts): QueryNotesPage {
   return { notes, next_cursor };
 }
 
+/**
+ * Turn a thrown FTS5 MATCH error into the structured `invalid_search_syntax`
+ * shape (vault#551, WS2A item 2). ALWAYS structured, never a raw rethrow —
+ * a raw `SQLiteError` escaping to the transport is an unstructured 500
+ * (REST) / generic `isError` text (MCP), which is exactly the swallowed-
+ * failure class this wave is closing.
+ *
+ * The two modes carry different hints:
+ *   - advanced: the caller passed raw FTS5 syntax that FTS5 rejected — tell
+ *     them to fix it or drop back to literal.
+ *   - literal: escaping + control-char sanitization
+ *     (`buildLiteralSearchQuery`) make every input syntactically valid
+ *     FTS5, so this is unreachable by construction — the belt-and-suspenders
+ *     structured error (rather than a raw rethrow) means that IF the
+ *     invariant is ever broken it still surfaces as an honest error, not a
+ *     500. Signals a vault bug worth reporting.
+ */
+function searchSyntaxError(rawQuery: string, err: unknown, mode: SearchMode): QueryError {
+  const causeMessage = err instanceof Error ? err.message : String(err);
+  const hint =
+    mode === "advanced"
+      ? `FTS5 rejected this as advanced query syntax (${causeMessage}). Fix the syntax, or omit search_mode:"advanced" for literal (punctuation-safe) search.`
+      : `FTS5 rejected the escaped literal query (${causeMessage}) — this should be impossible after literal-mode escaping + control-char sanitization; please report it as a vault bug.`;
+  return new QueryError(`invalid search syntax: ${causeMessage}`, "INVALID_QUERY", {
+    error_type: "invalid_search_syntax",
+    field: "search",
+    got: rawQuery,
+    hint,
+  });
+}
+
 export function searchNotes(
   db: Database,
   query: string,
-  opts?: { tags?: string[]; limit?: number },
+  opts?: { tags?: string[]; limit?: number; mode?: SearchMode; sort?: "asc" | "desc" },
 ): Note[] {
   const limit = typeof opts?.limit === "number" ? opts.limit : 50;
+  // Literal-by-default (vault#551): escape the caller's text so FTS5's own
+  // query syntax (hyphen = NOT, apostrophe/period = tokenizer breakage,
+  // etc.) is treated as ordinary content, not syntax. `search_mode:
+  // "advanced"` opts back into raw FTS5 query syntax — today's pre-#551
+  // behavior, unchanged — for callers who want boolean/phrase/prefix
+  // operators.
+  const mode: SearchMode = opts?.mode ?? "literal";
+  let ftsQuery: string;
+  if (mode === "literal") {
+    const built = buildLiteralSearchQuery(query);
+    // "Only whitespace/quotes" (vault#551 edge case): the caller (store.ts /
+    // the REST + MCP entry points) is expected to short-circuit this case
+    // itself (with an `empty_search` warning) before ever reaching here —
+    // this is a defensive fallback for any direct-core caller that skips
+    // that check.
+    if (built.isEmpty) return [];
+    ftsQuery = built.query;
+  } else {
+    ftsQuery = query;
+  }
+
+  // `sort` honored under search (vault#551 WS2A item 3): default stays FTS5
+  // relevance (`rank`, unchanged); an EXPLICIT `sort: "asc"|"desc"` switches
+  // to `created_at` ordering. Checked against the literal string values (not
+  // truthiness) so an absent `sort` can never accidentally match a branch.
+  // `n.id ${direction}` is appended as a deterministic tiebreaker — same
+  // rationale as `queryNotes` (two notes at the same created_at millisecond
+  // would otherwise return in arbitrary/unstable order). `rank` needs no
+  // tiebreaker (bm25 score is effectively unique per row).
+  const orderBy =
+    opts?.sort === "asc"
+      ? "n.created_at ASC, n.id ASC"
+      : opts?.sort === "desc"
+        ? "n.created_at DESC, n.id DESC"
+        : "rank";
 
   if (opts?.tags && opts.tags.length > 0) {
     // Canonical-bare-tag guard backstop (vault#XXX) for direct-core callers.
@@ -1234,12 +1401,19 @@ export function searchNotes(
         JOIN notes_fts fts ON fts.rowid = n.rowid
         WHERE notes_fts MATCH ?
           AND n.id IN (SELECT note_id FROM note_tags WHERE tag_name IN (${tagPlaceholders}))
-        ORDER BY rank
+        ORDER BY ${orderBy}
         LIMIT ?
-      `).all(query, ...searchTags, limit) as NoteRow[];
+      `).all(ftsQuery, ...searchTags, limit) as NoteRow[];
       return notesWithTags(db, rows);
-    } catch {
-      return [];
+    } catch (err) {
+      // Surface EVERY FTS5 error structured, never a raw rethrow (vault#551):
+      // advanced mode expects it (the caller passed raw syntax); literal
+      // mode should never reach it (escaping + control-char sanitization
+      // make the query valid) but if the invariant breaks we still want an
+      // honest error, not an unstructured 500. A QueryError we threw
+      // ourselves (empty-limit validation, etc.) is re-raised untouched.
+      if (err instanceof QueryError) throw err;
+      throw searchSyntaxError(query, err, mode);
     }
     }
   }
@@ -1249,12 +1423,13 @@ export function searchNotes(
       SELECT n.* FROM notes n
       JOIN notes_fts fts ON fts.rowid = n.rowid
       WHERE notes_fts MATCH ?
-      ORDER BY rank
+      ORDER BY ${orderBy}
       LIMIT ?
-    `).all(query, limit) as NoteRow[];
+    `).all(ftsQuery, limit) as NoteRow[];
     return notesWithTags(db, rows);
-  } catch {
-    return [];
+  } catch (err) {
+    if (err instanceof QueryError) throw err;
+    throw searchSyntaxError(query, err, mode);
   }
 }
 
@@ -1303,7 +1478,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 +1497,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);
   }
 }
 

package/core/src/query-warnings.ts

@@ -0,0 +1,219 @@
+/**
+ * The `warnings: []` channel (vault#550 — Reliability & Usability Program
+ * WS1, "honest queries"). Ratified principle: if the vault can still answer
+ * the question asked, answer it and attach a warning; if it would answer a
+ * DIFFERENT question, return a structured named error. Silence is never the
+ * third option.
+ *
+ * This module owns the ONE validated choke point for `unknown_tag`
+ * warnings — both the REST structured-query path (`src/routes.ts`) and the
+ * MCP `query-notes` tool call into `collectUnknownTagWarnings` so the two
+ * surfaces can't drift. REST-only warnings (`removed_param` — a REST query
+ * string concept with no MCP analog) stay in `src/routes.ts`.
+ *
+ * Tag-scope note (security review): this module is deliberately
+ * SCOPE-UNAWARE — `collectUnknownTagWarnings` always resolves against the
+ * full vault-wide tag catalog, exactly like `core/src/notes.ts:queryNotes`
+ * itself. Callers on a tag-scoped session MUST NOT surface these warnings
+ * (or must first narrow the candidate pool) — `did_you_mean` naming an
+ * out-of-scope tag would leak its existence across the scope boundary,
+ * which this codebase treats as a hard "no leak" invariant elsewhere (see
+ * `docs/contracts/tag-scoped-tokens.md`). `src/routes.ts` skips this call
+ * entirely for scoped sessions; `src/mcp-tools.ts`'s `query-notes` wrapper
+ * strips any `warnings` core computed before returning to a scoped caller.
+ */
+
+import { Database } from "bun:sqlite";
+import {
+  DEFAULT_TAG_EXPAND_MODE,
+  getTagExpansion,
+  loadTagHierarchy,
+  stripTagHash,
+  suggestSimilarTag,
+  type TagExpandMode,
+  type TagHierarchy,
+} from "./tag-hierarchy.js";
+import { chunkForInClause } from "./sql-in.js";
+
+export interface QueryWarning {
+  code: string;
+  message: string;
+  [key: string]: unknown;
+}
+
+/**
+ * Cap on `unknown_tag` warnings per query (vault#550 fold). A caller
+ * passing a garbage `tags` array (hundreds of junk names) would otherwise
+ * inflate the response — and the REST `X-Parachute-Warnings` header —
+ * unboundedly. Past the cap, a single `warnings_truncated` entry reports
+ * how many were suppressed.
+ */
+export const MAX_UNKNOWN_TAG_WARNINGS = 8;
+
+/**
+ * Membership counts for a specific set of candidate tag names — NOT a
+ * full `listTags()` vault-wide scan. `listTags` additionally computes
+ * `expanded_count` (a full `note_tags` pass over EVERY tag, vault#550),
+ * which this function deliberately avoids: `collectUnknownTagWarnings` runs
+ * on every tag-filtered structured query (a hot path), so paying for a
+ * vault-wide rollup just to answer "does tag X have ANY notes" would be a
+ * real perf regression. This scopes the `note_tags` scan to only the
+ * (typically small) set of names actually reachable from the query's own
+ * tag filter and its expansion.
+ */
+function countMembership(db: Database, names: ReadonlySet<string>): Map<string, number> {
+  const counts = new Map<string, number>();
+  if (names.size === 0) return counts;
+  for (const chunk of chunkForInClause([...names])) {
+    const placeholders = chunk.map(() => "?").join(", ");
+    const rows = db.prepare(
+      `SELECT tag_name, COUNT(*) as c FROM note_tags WHERE tag_name IN (${placeholders}) GROUP BY tag_name`,
+    ).all(...chunk) as { tag_name: string; c: number }[];
+    for (const row of rows) counts.set(row.tag_name, row.c);
+  }
+  return counts;
+}
+
+/**
+ * Warn on each literal tag name in a `tags` filter that can contribute
+ * NOTHING to the result set no matter what — the caller almost certainly
+ * mistyped it, or is thinking of a different vault. A tag survives (no
+ * warning) if ANY of the following holds:
+ *
+ *   - it has its own identity row (a `tags` table entry — created via
+ *     `update-tag` or implicitly by tagging a note), OR
+ *   - at least one note literally carries that tag, OR
+ *   - its mode-aware expansion (subtypes/namespace/both/exact — whatever
+ *     the query's `expand` axis resolves to) contains at least one tag
+ *     name that itself has notes.
+ *
+ * `did_you_mean` names the closest existing tag (case variant, prefix
+ * relationship, or small edit distance) when one exists — see
+ * `suggestSimilarTag`.
+ *
+ * Scoped to the POSITIVE `tags` filter only — `excludeTags` is not
+ * checked (excluding a nonexistent tag is a harmless no-op, not a sign of
+ * a mistaken query) and this does not run under `search=` (out of scope
+ * for this wave — see #551).
+ *
+ * Perf shape (vault#550 fold): this runs on EVERY tag-filtered structured
+ * query, so the common all-tags-known case must cost ~nothing. Pass the
+ * store's cached `hierarchy` (`Store.getTagHierarchy()` — invalidated on
+ * tag writes) so no fresh `tags`-table scan happens per request; the
+ * `note_tags` membership query below only runs for input tags MISSING
+ * from the identity set (`h.allTags`), which for a well-formed query is
+ * none — a tag with an identity row can never warn (`hasIdentity`
+ * short-circuits), so there's nothing to look up. The `hierarchy` param
+ * stays optional for direct-core callers/tests (falls back to a fresh
+ * load).
+ */
+export function collectUnknownTagWarnings(
+  db: Database,
+  tags: string[] | undefined,
+  expandMode: TagExpandMode | undefined,
+  hierarchy?: TagHierarchy,
+): QueryWarning[] {
+  if (!tags || tags.length === 0) return [];
+
+  const h = hierarchy ?? loadTagHierarchy(db);
+  const mode = expandMode ?? DEFAULT_TAG_EXPAND_MODE;
+
+  // Fast path: dedupe inputs and drop every tag with an identity row —
+  // those can never warn. For a well-formed query this empties the list
+  // and we return without touching the DB at all.
+  const suspects: string[] = [];
+  const seen = new Set<string>();
+  for (const raw of tags) {
+    const tag = stripTagHash(raw);
+    if (tag === "" || seen.has(tag)) continue;
+    seen.add(tag);
+    if (h.allTags.has(tag)) continue; // identity row → never unknown
+    suspects.push(tag);
+  }
+  if (suspects.length === 0) return [];
+
+  // Slow path (only for identity-less names): pre-compute each suspect's
+  // expansion set (memoized on `h.descendantsCache` — safe to share with
+  // the store's cache, entries are pure derived state) so the membership
+  // check is ONE batched IN-list query over the union, not one per tag.
+  // An identity-less tag can still be "known" two ways: a `note_tags` row
+  // exists without a `tags` row (not produced by current writers, but
+  // contract-tolerated), or children declared it a parent (`childrenOf`
+  // edges exist for undeclared parents) and a descendant has notes.
+  const expansions = new Map<string, Set<string>>();
+  for (const tag of suspects) expansions.set(tag, getTagExpansion(h, tag, mode));
+  const candidateNames = new Set<string>();
+  for (const set of expansions.values()) for (const name of set) candidateNames.add(name);
+  const counts = countMembership(db, candidateNames);
+
+  const warnings: QueryWarning[] = [];
+  let suppressed = 0;
+  for (const tag of suspects) {
+    const hasOwnMembership = (counts.get(tag) ?? 0) > 0;
+    let hasExpansionMembers = false;
+    for (const t of expansions.get(tag)!) {
+      if ((counts.get(t) ?? 0) > 0) {
+        hasExpansionMembers = true;
+        break;
+      }
+    }
+
+    if (!hasOwnMembership && !hasExpansionMembers) {
+      if (warnings.length >= MAX_UNKNOWN_TAG_WARNINGS) {
+        suppressed++;
+        continue;
+      }
+      const suggestion = suggestSimilarTag(h.allTags, tag);
+      warnings.push({
+        code: "unknown_tag",
+        message: `tag "${tag}" has no identity row and no notes match it (directly or via expansion) — check spelling, or create it first with update-tag`,
+        tag,
+        ...(suggestion ? { did_you_mean: suggestion } : {}),
+      });
+    }
+  }
+  if (suppressed > 0) {
+    warnings.push({
+      code: "warnings_truncated",
+      message: `${suppressed} additional unknown_tag warning(s) suppressed — at most ${MAX_UNKNOWN_TAG_WARNINGS} are reported per query.`,
+      suppressed,
+      limit: MAX_UNKNOWN_TAG_WARNINGS,
+    });
+  }
+  return warnings;
+}
+
+/**
+ * `empty_search` warning (vault#551) — the `search` string carried no
+ * literal content: blank/whitespace-only, or (in literal mode, where a
+ * manually-typed `"` is ordinary content rather than syntax) nothing but
+ * quote characters. Rather than let this degenerate into an FTS5 syntax
+ * error or a confusing always-empty-but-syntactically-valid query, the
+ * search path short-circuits BEFORE ever calling FTS5 and reports this
+ * warning alongside an honest `[]`. See `core/src/search-query.ts`
+ * `buildLiteralSearchQuery`, which is the choke point that detects this.
+ */
+export function emptySearchWarning(): QueryWarning {
+  return {
+    code: "empty_search",
+    message:
+      "the search query has no literal content (blank, or only whitespace/quote characters) — returning no results without querying FTS5.",
+  };
+}
+
+/**
+ * `ignored_param` warning (vault#551) — a query-shaping param was passed
+ * but has no effect given the rest of the request. First (and so far only)
+ * case: `search_mode` without `search` — the mode only shapes how `search`
+ * text is turned into an FTS5 query, so passing it alone almost always
+ * means the caller meant to pass `search` too. Generic over `param` /
+ * `reason` so a future ignored-param case can reuse the same shape instead
+ * of inventing a new warning code.
+ */
+export function ignoredParamWarning(param: string, reason: string): QueryWarning {
+  return {
+    code: "ignored_param",
+    message: `\`${param}\` has no effect: ${reason}`,
+    param,
+  };
+}