@openparachute/vault 0.6.5 → 0.7.0-rc.2

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);
   }
 }
 

package/core/src/query-warnings.ts

@@ -0,0 +1,184 @@
+/**
+ * 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;
+}

package/core/src/store.ts

@@ -70,8 +70,15 @@ export class BunSqliteStore implements Store {
    * boot or after an invalidation does the scan; subsequent calls hit the
    * cache. Returns the same object until invalidated, so callers can rely
    * on identity for memoizing per-tag descendant sets.
+   *
+   * Public (vault#550 fold): the query-warnings collector
+   * (`core/src/query-warnings.ts:collectUnknownTagWarnings`) runs on every
+   * tag-filtered structured query — threading this cached hierarchy in
+   * (instead of a fresh `loadTagHierarchy` per request) keeps the
+   * common all-tags-known case at ~zero extra cost. Treat the returned
+   * object as READ-ONLY — it's the shared cache, invalidated by writers.
    */
-  private getTagHierarchy(): TagHierarchy {
+  getTagHierarchy(): TagHierarchy {
     if (!this._tagHierarchy) this._tagHierarchy = loadTagHierarchy(this.db);
     return this._tagHierarchy;
   }
@@ -445,7 +452,7 @@ export class BunSqliteStore implements Store {
     return expanded;
   }
 
-  async listTags(): Promise<{ name: string; count: number }[]> {
+  async listTags(): Promise<{ name: string; count: number; expanded_count: number }[]> {
     return noteOps.listTags(this.db);
   }
 

package/core/src/tag-hierarchy.ts

@@ -249,6 +249,119 @@ export function getTagExpansion(
   }
 }
 
+/**
+ * Suggest the closest EXISTING tag name to an unmatched input — the
+ * `did_you_mean` hint on `unknown_tag` warnings (vault#550) and
+ * `tag_not_found` errors. Candidates are scored, lower is better:
+ *
+ *   0. case-only difference (`Voice` vs `voice`)
+ *   1. a prefix relationship either direction (`voice` / `voice-memo` —
+ *      catches plural/singular drift and namespace-child typos)
+ *   2+dist. Levenshtein edit distance, when within a length-scaled budget
+ *
+ * Returns the single best match, or `undefined` when nothing is close
+ * enough to be worth suggesting — a genuinely novel tag name shouldn't get
+ * a noisy "did you mean" pointing at an unrelated tag.
+ */
+export function suggestSimilarTag(
+  candidates: Iterable<string>,
+  input: string,
+): string | undefined {
+  const lower = input.toLowerCase();
+  let best: string | undefined;
+  let bestScore = Infinity;
+  for (const candidate of candidates) {
+    if (candidate === input) continue;
+    const candLower = candidate.toLowerCase();
+    let score: number | null = null;
+    if (candLower === lower) {
+      score = 0;
+    } else if (lower.length >= 2 && candLower.length >= 2 && (candLower.startsWith(lower) || lower.startsWith(candLower))) {
+      score = 1;
+    } else {
+      const dist = levenshtein(lower, candLower);
+      const budget = Math.max(2, Math.ceil(Math.min(lower.length, candLower.length) * 0.34));
+      if (dist <= budget) score = 2 + dist;
+    }
+    if (score !== null && score < bestScore) {
+      bestScore = score;
+      best = candidate;
+    }
+  }
+  return best;
+}
+
+/** Classic Levenshtein edit distance, O(m·n) time / O(n) space. */
+function levenshtein(a: string, b: string): number {
+  const m = a.length;
+  const n = b.length;
+  if (m === 0) return n;
+  if (n === 0) return m;
+  let prev = new Array<number>(n + 1);
+  let curr = new Array<number>(n + 1);
+  for (let j = 0; j <= n; j++) prev[j] = j;
+  for (let i = 1; i <= m; i++) {
+    curr[0] = i;
+    for (let j = 1; j <= n; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      curr[j] = Math.min(prev[j]! + 1, curr[j - 1]! + 1, prev[j - 1]! + cost);
+    }
+    [prev, curr] = [curr, prev];
+  }
+  return prev[n]!;
+}
+
+/**
+ * Compute, for every declared tag, the number of DISTINCT notes matching
+ * that tag OR any transitive descendant under the subtypes axis (vault#550
+ * `expanded_count` — the rollup a parent tag whose notes are all tagged
+ * with a CHILD tag needs to report a non-zero count).
+ *
+ * One query fetches every `(tag_name, note_id)` pairing from `note_tags`;
+ * the fan-out to ancestors is pure in-memory set work over the (memoized)
+ * hierarchy — not one query per tag, so this stays cheap regardless of how
+ * many tags the vault declares. `getTagDescendants` is memoized per tag on
+ * `h`, so the ancestor-closure build below reuses that cache instead of
+ * re-walking the graph per candidate.
+ */
+export function computeExpandedTagCounts(
+  db: Database,
+  h: TagHierarchy,
+): Map<string, number> {
+  const rows = db.prepare(`SELECT tag_name, note_id FROM note_tags`).all() as
+    { tag_name: string; note_id: string }[];
+
+  const expandedNotes = new Map<string, Set<string>>();
+  const ancestorsCache = new Map<string, string[]>();
+
+  function ancestorsOrSelf(x: string): string[] {
+    const cached = ancestorsCache.get(x);
+    if (cached) return cached;
+    const result: string[] = [];
+    for (const t of h.allTags) {
+      if (getTagDescendants(h, t).has(x)) result.push(t);
+    }
+    if (!result.includes(x)) result.push(x);
+    ancestorsCache.set(x, result);
+    return result;
+  }
+
+  for (const row of rows) {
+    for (const ancestor of ancestorsOrSelf(row.tag_name)) {
+      let set = expandedNotes.get(ancestor);
+      if (!set) {
+        set = new Set();
+        expandedNotes.set(ancestor, set);
+      }
+      set.add(row.note_id);
+    }
+  }
+
+  const counts = new Map<string, number>();
+  for (const [tag, set] of expandedNotes) counts.set(tag, set.size);
+  return counts;
+}
+
 /**
  * Detect cycles in the declared hierarchy. Returns the list of tags
  * reachable from themselves via parent declarations. Used by

package/core/src/types.ts

@@ -1,16 +1,18 @@
 import type { Database } from "bun:sqlite";
 import type { TagFieldSchema, TagRelationship, TagRelationshipMap, TagRecord } from "./tag-schemas.js";
 import type { PrunedField } from "./indexed-fields.js";
-import type { TagExpandMode } from "./tag-hierarchy.js";
+import type { TagExpandMode, TagHierarchy } from "./tag-hierarchy.js";
 import type { ValidationStatus } from "./schema-defaults.js";
 import type { ConformanceReport } from "./conformance.js";
+import type { FindPathResult } from "./links.js";
 
 // ---- Re-exports ----
 
 export type { TagFieldSchema, TagRelationship, TagRelationshipMap, TagRecord } from "./tag-schemas.js";
 export type { PrunedField } from "./indexed-fields.js";
-export type { TagExpandMode } from "./tag-hierarchy.js";
+export type { TagExpandMode, TagHierarchy } from "./tag-hierarchy.js";
 export type { ConformanceReport } from "./conformance.js";
+export type { FindPathResult } from "./links.js";
 
 // ---- Note ----
 
@@ -336,7 +338,20 @@ export interface Store {
    * IDENTICAL expansion the snapshot query engine uses for the same `expand`.
    */
   expandTags(tags: string[], mode?: TagExpandMode): Promise<Set<string>>;
-  listTags(): Promise<{ name: string; count: number }[]>;
+  /**
+   * The store's cached tag hierarchy (invalidated on tag/parent_names
+   * writes). Sync, like `db` and `transaction`. Exposed (vault#550 fold)
+   * so per-query consumers — the `unknown_tag` warning collector — reuse
+   * the cache instead of re-scanning the `tags` table per request. Treat
+   * the returned object as READ-ONLY shared state.
+   */
+  getTagHierarchy(): TagHierarchy;
+  /**
+   * `expanded_count` (vault#550): distinct notes matching the tag OR any
+   * transitive descendant under the DEFAULT (subtypes) expansion axis,
+   * alongside the literal `count`. See `core/src/tag-hierarchy.ts:computeExpandedTagCounts`.
+   */
+  listTags(): Promise<{ name: string; count: number; expanded_count: number }[]>;
   deleteTag(name: string): Promise<{ deleted: boolean; notes_untagged: number }>;
   renameTag(
     oldName: string,
@@ -375,7 +390,7 @@ export interface Store {
 
   // Deeper link queries
   traverseLinks(noteId: string, opts?: { max_depth?: number; relationship?: string }): Promise<{ noteId: string; depth: number; relationship: string; direction: "outbound" | "inbound" }[]>;
-  findPath(sourceId: string, targetId: string, opts?: { max_depth?: number }): Promise<{ path: string[]; relationships: string[] } | null>;
+  findPath(sourceId: string, targetId: string, opts?: { max_depth?: number }): Promise<FindPathResult | null>;
 
   // Tag schemas — schema-only facade (description + fields). Back-compat
   // surface for v13-and-earlier callers; reads/writes route through the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/vault",
-  "version": "0.6.5",
+  "version": "0.7.0-rc.2",
   "description": "Agent-native knowledge graph. Notes, tags, links over MCP.",
   "module": "src/cli.ts",
   "type": "module",