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

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.7.0-rc.1",
+  "version": "0.7.0-rc.2",
   "description": "Agent-native knowledge graph. Notes, tags, links over MCP.",
   "module": "src/cli.ts",
   "type": "module",