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

package/core/src/search-query.test.ts

@@ -0,0 +1,149 @@
+import { describe, it, expect } from "bun:test";
+import {
+  SEARCH_MODES,
+  escapeFtsToken,
+  buildLiteralSearchQuery,
+  isValidSearchMode,
+} from "./search-query.js";
+
+describe("escapeFtsToken", () => {
+  it("wraps a plain token in quotes", () => {
+    expect(escapeFtsToken("widgets")).toBe(`"widgets"`);
+  });
+
+  it("doubles an embedded quote", () => {
+    expect(escapeFtsToken(`say"hi`)).toBe(`"say""hi"`);
+  });
+
+  it("doubles multiple embedded quotes", () => {
+    expect(escapeFtsToken(`"eleven-day`)).toBe(`"""eleven-day"`);
+    expect(escapeFtsToken(`delay"`)).toBe(`"delay"""`);
+  });
+
+  it("preserves punctuation that isn't a quote (hyphen, period, apostrophe)", () => {
+    expect(escapeFtsToken("eleven-day")).toBe(`"eleven-day"`);
+    expect(escapeFtsToken("18.6")).toBe(`"18.6"`);
+    expect(escapeFtsToken("didn't")).toBe(`"didn't"`);
+  });
+});
+
+describe("buildLiteralSearchQuery", () => {
+  it("wraps a single token", () => {
+    const r = buildLiteralSearchQuery("widgets");
+    expect(r.isEmpty).toBe(false);
+    expect(r.query).toBe(`"widgets"`);
+  });
+
+  it("phrase-quotes each whitespace-delimited token and ANDs them (vault#551 root fix)", () => {
+    const r = buildLiteralSearchQuery("eleven-day capping delay");
+    expect(r.isEmpty).toBe(false);
+    expect(r.query).toBe(`"eleven-day" "capping" "delay"`);
+  });
+
+  it("escapes an apostrophe as literal content, not syntax", () => {
+    const r = buildLiteralSearchQuery("didn't");
+    expect(r.isEmpty).toBe(false);
+    expect(r.query).toBe(`"didn't"`);
+  });
+
+  it("escapes a decimal point as literal content, not syntax", () => {
+    const r = buildLiteralSearchQuery("18.6");
+    expect(r.isEmpty).toBe(false);
+    expect(r.query).toBe(`"18.6"`);
+  });
+
+  it("collapses runs of whitespace between tokens", () => {
+    const r = buildLiteralSearchQuery("widgets    gadgets");
+    expect(r.query).toBe(`"widgets" "gadgets"`);
+  });
+
+  it("trims leading/trailing whitespace", () => {
+    const r = buildLiteralSearchQuery("  widgets  ");
+    expect(r.query).toBe(`"widgets"`);
+  });
+
+  it("escapes a manually-quoted phrase's embedded quote characters as content", () => {
+    // The user typed literal quote marks expecting phrase syntax; in
+    // literal mode those quote characters are just more content that gets
+    // escaped like anything else (vault#551 — this is CORRECT, not a bug:
+    // raw phrase/boolean/prefix syntax now requires search_mode:"advanced").
+    const r = buildLiteralSearchQuery(`"eleven-day capping delay"`);
+    expect(r.isEmpty).toBe(false);
+    expect(r.query).toBe(`"""eleven-day" "capping" "delay"""`);
+  });
+
+  it("treats a blank string as empty", () => {
+    expect(buildLiteralSearchQuery("").isEmpty).toBe(true);
+  });
+
+  it("treats a whitespace-only string as empty", () => {
+    expect(buildLiteralSearchQuery("   ").isEmpty).toBe(true);
+  });
+
+  it("treats a lone quote character as empty", () => {
+    expect(buildLiteralSearchQuery(`"`).isEmpty).toBe(true);
+  });
+
+  it("treats a quotes-and-whitespace-only string as empty", () => {
+    expect(buildLiteralSearchQuery(`"  "  "`).isEmpty).toBe(true);
+  });
+
+  it("an empty-flagged result never carries a query string callers should use", () => {
+    const r = buildLiteralSearchQuery("   ");
+    expect(r.isEmpty).toBe(true);
+    expect(r.query).toBe("");
+  });
+
+  // Control-character sanitization (vault#551 review fold) — a NUL byte
+  // (or any C0/DEL control) inside a token would otherwise crash FTS5's
+  // C-string parser with a raw `unterminated string` error, breaking the
+  // "literal mode cannot throw" guarantee.
+  it("splits a token on an embedded NUL byte — both halves stay searchable", () => {
+    const r = buildLiteralSearchQuery("hello\x00world");
+    expect(r.isEmpty).toBe(false);
+    expect(r.query).toBe(`"hello" "world"`);
+  });
+
+  it("treats a NUL-only string as empty (short-circuits, never reaches FTS5)", () => {
+    const r = buildLiteralSearchQuery("\x00");
+    expect(r.isEmpty).toBe(true);
+    expect(r.query).toBe("");
+  });
+
+  it("collapses a run of NUL/control bytes between tokens like whitespace", () => {
+    const r = buildLiteralSearchQuery("hello\x00\x00world");
+    expect(r.query).toBe(`"hello" "world"`);
+  });
+
+  it("sanitizes the other C0 controls and DEL (0x01-0x1F, 0x7F) as separators too", () => {
+    expect(buildLiteralSearchQuery("a\x01\x02b").query).toBe(`"a" "b"`);
+    expect(buildLiteralSearchQuery("a\x1fb").query).toBe(`"a" "b"`);
+    expect(buildLiteralSearchQuery("a\x7fb").query).toBe(`"a" "b"`);
+  });
+
+  it("a control byte adjacent to a real token still yields the clean token", () => {
+    expect(buildLiteralSearchQuery("\x00hello\x00").query).toBe(`"hello"`);
+  });
+});
+
+describe("isValidSearchMode / SEARCH_MODES", () => {
+  it("SEARCH_MODES is exactly literal + advanced", () => {
+    expect(SEARCH_MODES).toEqual(["literal", "advanced"]);
+  });
+
+  it("accepts literal and advanced", () => {
+    expect(isValidSearchMode("literal")).toBe(true);
+    expect(isValidSearchMode("advanced")).toBe(true);
+  });
+
+  it("rejects an unknown string", () => {
+    expect(isValidSearchMode("bogus")).toBe(false);
+  });
+
+  it("rejects non-string values", () => {
+    expect(isValidSearchMode(123)).toBe(false);
+    expect(isValidSearchMode(null)).toBe(false);
+    expect(isValidSearchMode(undefined)).toBe(false);
+    expect(isValidSearchMode(["literal"])).toBe(false);
+  });
+});

package/core/src/store.ts

@@ -34,6 +34,7 @@ import {
   countConformanceViolations,
   type ConformanceReport,
 } from "./conformance.js";
+import type { SearchMode } from "./search-query.js";
 
 /**
  * bun:sqlite-backed Store implementation. Internally everything is
@@ -70,8 +71,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;
   }
@@ -368,7 +376,7 @@ export class BunSqliteStore implements Store {
     return { ...opts, _tagsExpanded: expanded } as QueryOpts;
   }
 
-  async searchNotes(query: string, opts?: { tags?: string[]; limit?: number; expand?: TagExpandMode }): Promise<Note[]> {
+  async searchNotes(query: string, opts?: { tags?: string[]; limit?: number; expand?: TagExpandMode; mode?: SearchMode; sort?: "asc" | "desc" }): Promise<Note[]> {
     // Canonical-bare-tag guard (vault#XXX): strip leading `#` from search tag
     // filters before expansion, so `#manual` and `manual` resolve identically.
     if (opts?.tags && opts.tags.length > 0) {
@@ -445,7 +453,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,19 @@
 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 { SearchMode } from "./search-query.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 ----
 
@@ -312,7 +315,18 @@ export interface Store {
    * agent loop can persist a single watermark and keep polling.
    */
   queryNotesPaged(opts: QueryOpts): Promise<QueryNotesPage>;
-  searchNotes(query: string, opts?: { tags?: string[]; limit?: number; expand?: TagExpandMode }): Promise<Note[]>;
+  /**
+   * `mode` (vault#551 — literal-by-default): "literal" (default) escapes +
+   * phrase-quotes the query so FTS5 punctuation syntax (hyphen = NOT, an
+   * apostrophe/period breaking the parse, ...) is treated as ordinary
+   * content. "advanced" passes `query` through to FTS5 raw (pre-#551
+   * behavior) for callers who want boolean/phrase/prefix operators — a
+   * syntax error in that mode throws (`error_type: "invalid_search_syntax"`)
+   * rather than silently returning `[]`. `sort` (vault#551): omitted stays
+   * FTS5 relevance ranking (default); an explicit "asc"/"desc" switches to
+   * `created_at` ordering. See `core/src/search-query.ts`.
+   */
+  searchNotes(query: string, opts?: { tags?: string[]; limit?: number; expand?: TagExpandMode; mode?: SearchMode; sort?: "asc" | "desc" }): Promise<Note[]>;
 
   // Tags
   tagNote(noteId: string, tags: string[]): Promise<void>;
@@ -336,7 +350,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 +402,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.3",
   "description": "Agent-native knowledge graph. Notes, tags, links over MCP.",
   "module": "src/cli.ts",
   "type": "module",