@openparachute/vault 0.7.3-rc.1 → 0.7.3-rc.10

package/core/src/schema-v27-note-vectors.test.ts

@@ -0,0 +1,178 @@
+/**
+ * Migration v26 → v27: the `note_vectors` table (semantic search MVP —
+ * `SEMANTIC-MVP-PLAN.md`). Exercised against a REALISTIC pre-v27 fixture
+ * (a hand-built v26-shape DB, not a fresh vault — per the real-install-
+ * fixture discipline: fresh-DB-only testing misses the "existing vault
+ * upgrading" path, which is the one that matters in production).
+ */
+import { describe, it, expect } from "bun:test";
+import { Database } from "bun:sqlite";
+import { initSchema, SCHEMA_VERSION } from "./schema.js";
+import { encodeVector, normalize } from "./embedding/vector-codec.js";
+
+/** A v26-shape vault: everything through vault#586, no `note_vectors` at all. */
+function buildPreV27Vault(): Database {
+  const db = new Database(":memory:");
+  db.exec(`
+    CREATE TABLE notes (
+      id TEXT PRIMARY KEY,
+      content TEXT DEFAULT '',
+      path TEXT,
+      metadata TEXT DEFAULT '{}',
+      created_at TEXT NOT NULL,
+      updated_at TEXT,
+      extension TEXT NOT NULL DEFAULT 'md',
+      created_by TEXT,
+      created_via TEXT,
+      last_updated_by TEXT,
+      last_updated_via TEXT,
+      updated_at_ms INTEGER
+    );
+    CREATE TABLE tags (
+      name TEXT PRIMARY KEY,
+      description TEXT,
+      fields TEXT,
+      relationships TEXT,
+      parent_names TEXT,
+      created_at TEXT,
+      updated_at TEXT
+    );
+    CREATE TABLE note_tags (
+      note_id TEXT NOT NULL REFERENCES notes(id) ON DELETE CASCADE,
+      tag_name TEXT NOT NULL REFERENCES tags(name),
+      PRIMARY KEY (note_id, tag_name)
+    );
+    CREATE TABLE attachments (
+      id TEXT PRIMARY KEY,
+      note_id TEXT NOT NULL REFERENCES notes(id) ON DELETE CASCADE,
+      path TEXT NOT NULL,
+      mime_type TEXT NOT NULL,
+      metadata TEXT DEFAULT '{}',
+      created_at TEXT NOT NULL
+    );
+    CREATE TABLE links (
+      source_id TEXT NOT NULL REFERENCES notes(id) ON DELETE CASCADE,
+      target_id TEXT NOT NULL REFERENCES notes(id) ON DELETE CASCADE,
+      relationship TEXT NOT NULL,
+      metadata TEXT DEFAULT '{}',
+      created_at TEXT NOT NULL,
+      UNIQUE(source_id, target_id, relationship)
+    );
+    CREATE INDEX idx_notes_updated_ms ON notes(updated_at_ms, id);
+    -- A REAL v26 vault already went through migrateToV25's notes_fts
+    -- rebuild+repopulate long ago — this fixture must include that
+    -- already-populated state too, or a post-migration DELETE against
+    -- notes hits the notes_fts_delete trigger with an external-content FTS5
+    -- index that was never populated for these rows, which SQLite reports
+    -- as disk-image corruption (a fixture-fidelity issue, not a real one).
+    CREATE VIRTUAL TABLE notes_fts USING fts5(
+      path, content, content='notes', content_rowid='rowid', tokenize='porter unicode61'
+    );
+    CREATE TRIGGER notes_fts_insert AFTER INSERT ON notes BEGIN
+      INSERT INTO notes_fts(rowid, path, content) VALUES (new.rowid, COALESCE(new.path, ''), new.content);
+    END;
+    CREATE TRIGGER notes_fts_delete AFTER DELETE ON notes BEGIN
+      INSERT INTO notes_fts(notes_fts, rowid, path, content) VALUES('delete', old.rowid, COALESCE(old.path, ''), old.content);
+    END;
+    CREATE TRIGGER notes_fts_update AFTER UPDATE OF content, path ON notes BEGIN
+      INSERT INTO notes_fts(notes_fts, rowid, path, content) VALUES('delete', old.rowid, COALESCE(old.path, ''), old.content);
+      INSERT INTO notes_fts(rowid, path, content) VALUES (new.rowid, COALESCE(new.path, ''), new.content);
+    END;
+    CREATE TABLE schema_version (version INTEGER PRIMARY KEY, applied_at TEXT);
+    INSERT INTO schema_version (version, applied_at) VALUES (26, '2026-07-01T00:00:00.000Z');
+  `);
+  const insert = db.prepare(
+    "INSERT INTO notes (id, content, created_at, updated_at, updated_at_ms) VALUES (?, ?, ?, ?, ?)",
+  );
+  insert.run("note-1", "some real morning-pages content", "2026-06-01T00:00:00.000Z", "2026-06-01T00:00:00.000Z", Date.UTC(2026, 5, 1));
+  insert.run("note-2", "another pre-existing note", "2026-06-02T00:00:00.000Z", "2026-06-02T00:00:00.000Z", Date.UTC(2026, 5, 2));
+  return db;
+}
+
+function hasTable(db: Database, name: string): boolean {
+  return !!db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name=?").get(name);
+}
+
+function hasIndex(db: Database, name: string): boolean {
+  return !!db.prepare("SELECT name FROM sqlite_master WHERE type='index' AND name=?").get(name);
+}
+
+describe("migrateToV27 — creates note_vectors on a real pre-v27 fixture", () => {
+  it("has no note_vectors table before migration; has one (+ its index) after", () => {
+    const db = buildPreV27Vault();
+    expect(hasTable(db, "note_vectors")).toBe(false);
+    initSchema(db);
+    expect(hasTable(db, "note_vectors")).toBe(true);
+    expect(hasIndex(db, "idx_note_vectors_stale")).toBe(true);
+    expect(
+      (db.prepare("SELECT MAX(version) AS v FROM schema_version").get() as { v: number }).v,
+    ).toBe(SCHEMA_VERSION);
+  });
+
+  it("does NOT touch existing note rows — no data movement, unlike migrateToV26's backfill", () => {
+    const db = buildPreV27Vault();
+    const before = db.prepare("SELECT id, content, created_at, updated_at FROM notes ORDER BY id").all();
+    initSchema(db);
+    const after = db.prepare("SELECT id, content, created_at, updated_at FROM notes ORDER BY id").all();
+    expect(after).toEqual(before);
+  });
+
+  it("every pre-existing note starts with ZERO note_vectors rows — the implicit 'needs embedding' backfill signal", () => {
+    const db = buildPreV27Vault();
+    initSchema(db);
+    const count = (
+      db.prepare("SELECT COUNT(*) AS n FROM note_vectors").get() as { n: number }
+    ).n;
+    expect(count).toBe(0);
+  });
+
+  it("is idempotent — a second initSchema neither throws nor duplicates the table/index", () => {
+    const db = buildPreV27Vault();
+    initSchema(db);
+    expect(() => initSchema(db)).not.toThrow();
+    expect(hasTable(db, "note_vectors")).toBe(true);
+  });
+
+  it("note_vectors rows cascade-delete when their note is deleted (ON DELETE CASCADE)", () => {
+    const db = buildPreV27Vault();
+    initSchema(db);
+    const vec = encodeVector(normalize(new Float32Array([1, 2, 3, 4])));
+    db.prepare(
+      `INSERT INTO note_vectors (note_id, chunk_ix, vector, dims, model, content_hash, embedded_at)
+       VALUES (?, 0, ?, 4, 'test-model', 'deadbeef', ?)`,
+    ).run("note-1", vec, new Date().toISOString());
+    expect(
+      (db.prepare("SELECT COUNT(*) AS n FROM note_vectors WHERE note_id = ?").get("note-1") as { n: number }).n,
+    ).toBe(1);
+
+    db.prepare("DELETE FROM notes WHERE id = ?").run("note-1");
+
+    expect(
+      (db.prepare("SELECT COUNT(*) AS n FROM note_vectors WHERE note_id = ?").get("note-1") as { n: number }).n,
+    ).toBe(0);
+    // note-2 is unaffected.
+    expect(hasTable(db, "notes")).toBe(true);
+    expect(
+      (db.prepare("SELECT COUNT(*) AS n FROM notes WHERE id = ?").get("note-2") as { n: number }).n,
+    ).toBe(1);
+  });
+
+  it("PRIMARY KEY (note_id, chunk_ix) rejects a duplicate chunk row (upsert-by-replace is the caller's job)", () => {
+    const db = buildPreV27Vault();
+    initSchema(db);
+    const vec = encodeVector(normalize(new Float32Array([1, 0, 0, 0])));
+    const insert = db.prepare(
+      `INSERT INTO note_vectors (note_id, chunk_ix, vector, dims, model, content_hash, embedded_at)
+       VALUES (?, 0, ?, 4, 'test-model', 'hash-a', ?)`,
+    );
+    insert.run("note-1", vec, new Date().toISOString());
+    expect(() => insert.run("note-1", vec, new Date().toISOString())).toThrow();
+  });
+
+  it("a fresh vault (no prior schema_version row) gets note_vectors directly from SCHEMA_SQL", () => {
+    const db = new Database(":memory:");
+    initSchema(db);
+    expect(hasTable(db, "note_vectors")).toBe(true);
+    expect(hasIndex(db, "idx_note_vectors_stale")).toBe(true);
+  });
+});

package/core/src/schema.ts

@@ -5,7 +5,7 @@ import { findMixedTypeIndexedFieldNotes } from "./doctor.js";
 import { transaction } from "./txn.js";
 import { timestampToMs } from "./cursor.js";
 
-export const SCHEMA_VERSION = 26;
+export const SCHEMA_VERSION = 27;
 
 /**
  * Deterministic last-resort epoch for a note whose `updated_at` AND
@@ -112,6 +112,35 @@ CREATE TABLE IF NOT EXISTS links (
   UNIQUE(source_id, target_id, relationship)
 );
 
+-- note_vectors (v27, semantic search MVP — EXPERIMENTAL): one row per
+-- embedded CHUNK of a note (see core/src/embedding/chunker.ts). chunk_ix=0
+-- is either the whole note (short notes, the degenerate/v1-equivalent
+-- case) or the first section of a long, multi-section note.
+--
+-- vector is a Float32Array serialized to raw bytes (core/src/embedding/
+-- vector-codec.ts), stored L2-NORMALIZED so ranking is a plain dot
+-- product. model is recorded per-row so a provider/model change is
+-- detectable (see core/src/embedding/staleness.ts) — a chunk_ix's row is
+-- REPLACED wholesale on re-embed, never appended, so a vault only ever
+-- carries vectors from ONE model at a time. content_hash is the freshness
+-- gate: a create/update whose chunk text hashes the same as the stored
+-- row is a no-op (no wasted embed on a metadata-only save).
+-- ON DELETE CASCADE mirrors attachments/links above — a deleted note
+-- drops its vectors for free.
+CREATE TABLE IF NOT EXISTS note_vectors (
+  note_id      TEXT NOT NULL REFERENCES notes(id) ON DELETE CASCADE,
+  chunk_ix     INTEGER NOT NULL DEFAULT 0,
+  vector       BLOB NOT NULL,
+  dims         INTEGER NOT NULL,
+  model        TEXT NOT NULL,
+  content_hash TEXT NOT NULL,
+  embedded_at  TEXT NOT NULL,
+  PRIMARY KEY (note_id, chunk_ix)
+);
+-- Backs the staleness diff (per-note row fetch) and the model-mismatch
+-- sweep (a model <> ? scan) the backfill/drain use to find pending work.
+CREATE INDEX IF NOT EXISTS idx_note_vectors_stale ON note_vectors(model, content_hash);
+
 -- tag_schemas (v6) was retired in v14; description + fields lifted onto the
 -- tags row directly. The CREATE TABLE was removed from SCHEMA_SQL after the
 -- v14 data migration drops the table; existing v6+ vaults pick up the
@@ -554,6 +583,12 @@ export function initSchema(db: Database): void {
   // `updated_at` string with a UTC-correct parse. See vault#586.
   migrateToV26(db);
 
+  // Migrate v26 → v27: create the `note_vectors` table (semantic search
+  // MVP, EXPERIMENTAL) — one row per embedded note chunk. No backfill loop:
+  // every pre-existing note simply has zero rows, which the staleness gate
+  // already reads as "needs embedding." See vault semantic-search MVP plan.
+  migrateToV27(db);
+
   // Rebuild any generated columns + indexes declared in indexed_fields.
   // No-op for a fresh vault; idempotent on existing vaults.
   rebuildIndexes(db);
@@ -1617,6 +1652,51 @@ function migrateToV26(db: Database): void {
   db.exec("CREATE INDEX IF NOT EXISTS idx_notes_updated_ms ON notes(updated_at_ms, id)");
 }
 
+/**
+ * Migrate v26 → v27: the `note_vectors` table (semantic search MVP,
+ * EXPERIMENTAL — `SEMANTIC-MVP-PLAN.md`). Created by SCHEMA_SQL's
+ * `CREATE TABLE IF NOT EXISTS` above, so on a FRESH vault this is a no-op
+ * confirmation hook (same pattern as `migrateToV7`/`V20`/`V21` — the table
+ * is new, not a column added to existing rows). On an EXISTING vault
+ * upgrading through this version, the `CREATE TABLE IF NOT EXISTS` +
+ * `CREATE INDEX IF NOT EXISTS` calls create it for the first time.
+ *
+ * Deliberately NO backfill loop, and no embedding call of any kind — this
+ * function never resolves an `EmbeddingProvider` or does network/CPU work.
+ * "Backfill" for existing notes is implicit and free: every note that
+ * predates this migration simply has ZERO rows in the (now-created, empty)
+ * `note_vectors` table, which `core/src/embedding/staleness.ts:planStaleness`
+ * already treats as "stale — needs embedding" (no existing row at a given
+ * `chunk_ix` ⇒ stale). The async drain (self-host: the `onNote` hook +
+ * its sweep; cloud: the DO-alarm drain) discovers this pending work by
+ * scanning for notes lacking a fresh vector row — the exact same "queue is
+ * implicit in the diff, not a separate table" property the `updated_at_ms`
+ * self-heal above relies on. So this migration is intentionally ALL
+ * schema, zero data movement — the whole point of "enqueue, never embed
+ * inside the migration."
+ *
+ * Wrapped in a transaction for symmetry with `migrateToV25`/`V26` (a
+ * multi-statement DDL block should commit or roll back as one unit), even
+ * though there's no row data to lose here.
+ */
+function migrateToV27(db: Database): void {
+  transaction(db, () => {
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS note_vectors (
+        note_id      TEXT NOT NULL REFERENCES notes(id) ON DELETE CASCADE,
+        chunk_ix     INTEGER NOT NULL DEFAULT 0,
+        vector       BLOB NOT NULL,
+        dims         INTEGER NOT NULL,
+        model        TEXT NOT NULL,
+        content_hash TEXT NOT NULL,
+        embedded_at  TEXT NOT NULL,
+        PRIMARY KEY (note_id, chunk_ix)
+      )
+    `);
+    db.exec("CREATE INDEX IF NOT EXISTS idx_note_vectors_stale ON note_vectors(model, content_hash)");
+  });
+}
+
 function hasTable(db: Database, name: string): boolean {
   const row = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name=?").get(name);
   return !!row;

package/core/src/search-fts-v25.test.ts

@@ -132,7 +132,15 @@ describe("search — v24 → v25 migration (legacy vault upgrade)", () => {
     );
     insert.run(
       "legacy-1",
-      "a dedicated writeup mentioning propolis only once in passing text",
+      // Deliberately multi-line, with the "propolis" mention on a LATER
+      // line — this fixture isolates the PATH-weighted bm25 axis (below)
+      // from the separate content-title-boost axis (title axis, ratified
+      // 2026-07-17): that boost derives a note's "title" from its FIRST
+      // content line, and a single-line note IS its own title in full, so
+      // a one-line body mentioning "propolis" would (correctly, under the
+      // newer axis) count as a title match and confound this test's
+      // path-only signal. See `search-title-boost.test.ts` for that axis.
+      "Notes on foraging patterns\n\na dedicated writeup mentioning propolis only once in passing text",
       "beekeeping-notes",
       "2026-01-01T00:00:00.000Z",
       "2026-01-01T00:00:00.000Z",

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

@@ -4,6 +4,7 @@ import {
   escapeFtsToken,
   buildLiteralSearchQuery,
   isValidSearchMode,
+  extractLiteralBoostTerms,
 } from "./search-query.js";
 
 describe("escapeFtsToken", () => {
@@ -147,3 +148,44 @@ describe("isValidSearchMode / SEARCH_MODES", () => {
     expect(isValidSearchMode(["literal"])).toBe(false);
   });
 });
+
+describe("extractLiteralBoostTerms (search title-boost input, title axis)", () => {
+  it("lowercases and whitespace-splits", () => {
+    expect(extractLiteralBoostTerms("Budget Review")).toEqual(["budget", "review"]);
+  });
+
+  it("collapses whitespace runs", () => {
+    expect(extractLiteralBoostTerms("widgets    gadgets")).toEqual(["widgets", "gadgets"]);
+  });
+
+  it("trims leading/trailing whitespace", () => {
+    expect(extractLiteralBoostTerms("  widgets  ")).toEqual(["widgets"]);
+  });
+
+  it("strips literal quote characters a caller typed, unlike buildLiteralSearchQuery", () => {
+    // buildLiteralSearchQuery treats a manually-typed `"` as ordinary
+    // content (escaped into the FTS phrase); the boost-term extractor
+    // strips it instead, since a title-string comparison shouldn't
+    // require the title to contain a literal quote mark.
+    expect(extractLiteralBoostTerms(`"eleven-day capping delay"`)).toEqual([
+      "eleven-day",
+      "capping",
+      "delay",
+    ]);
+  });
+
+  it("preserves punctuation that isn't a quote (hyphen, period, apostrophe)", () => {
+    expect(extractLiteralBoostTerms("eleven-day")).toEqual(["eleven-day"]);
+    expect(extractLiteralBoostTerms("18.6")).toEqual(["18.6"]);
+    expect(extractLiteralBoostTerms("didn't")).toEqual(["didn't"]);
+  });
+
+  it("returns an empty array for blank/whitespace-only input", () => {
+    expect(extractLiteralBoostTerms("")).toEqual([]);
+    expect(extractLiteralBoostTerms("   ")).toEqual([]);
+  });
+
+  it("sanitizes control characters as separators, matching buildLiteralSearchQuery", () => {
+    expect(extractLiteralBoostTerms("hello\x00world")).toEqual(["hello", "world"]);
+  });
+});

package/core/src/search-query.ts

@@ -153,3 +153,30 @@ export function buildLiteralSearchQuery(raw: string): LiteralSearchQuery {
   const tokens = cleaned.trim().split(/\s+/).filter(Boolean);
   return { query: tokens.map(escapeFtsToken).join(" "), isEmpty: false };
 }
+
+/**
+ * Extract lowercase whitespace-delimited terms from raw literal-mode search
+ * text, for the search title-boost post-rank (title axis, ratified
+ * 2026-07-17) — NOT used to build the FTS5 MATCH query itself (that's
+ * `buildLiteralSearchQuery`, above). Sanitizes control characters the same
+ * way, plus strips any literal `"` a caller typed (kept as ordinary content
+ * by `buildLiteralSearchQuery`, but a display-title substring check
+ * shouldn't require the title to contain a literal quote mark).
+ *
+ * This is a heuristic re-rank signal, not a second index — it deliberately
+ * does not attempt FTS5-tokenizer parity (stemming, unicode normalization).
+ * It only needs to answer "does the note's first line plausibly contain the
+ * query," not reproduce FTS5's match semantics exactly. Restricted to
+ * literal-mode callers by convention (see `core/src/notes.ts` `searchNotes`)
+ * — `search_mode: "advanced"` text carries FTS5 boolean/column/prefix
+ * operators (`AND`, `path:`, `foo*`) that would leak into the term list as
+ * false "content" if tokenized the same naive way.
+ */
+export function extractLiteralBoostTerms(raw: string): string[] {
+  const cleaned = raw.replace(CONTROL_CHARS, " ").toLowerCase();
+  return cleaned
+    .trim()
+    .split(/\s+/)
+    .map((t) => t.replace(/^"+|"+$/g, ""))
+    .filter(Boolean);
+}

package/core/src/search-title-boost.test.ts

@@ -0,0 +1,125 @@
+/**
+ * Search title-boost (title axis, ratified 2026-07-17): literal-mode
+ * search results whose `displayTitle` (first non-empty content line, NOT
+ * `path`) contains every query term are post-ranked ahead of body-only
+ * matches. No-migration — an in-memory re-rank of the already-fetched
+ * page, not a `notes_fts` schema change (see `applySearchTitleBoost` /
+ * `boostTitleMatches` in `notes.ts`).
+ *
+ * This is a DIFFERENT axis from the existing `path`-weighted bm25 ranking
+ * covered in `search-fts-v25.test.ts` — a note's title here is its first
+ * CONTENT line, not its `path`.
+ */
+import { describe, it, expect, beforeEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { SqliteStore } from "./store.js";
+
+let store: SqliteStore;
+let db: Database;
+
+beforeEach(() => {
+  db = new Database(":memory:");
+  store = new SqliteStore(db);
+});
+
+describe("search title-boost", () => {
+  it("ranks a first-line (title) match above a body-only match", async () => {
+    // Body-only match: "budget" appears only deep in the body, first line
+    // is unrelated.
+    await store.createNote(
+      "Weekly Standup\nlots of unrelated notes here, but somewhere we discuss the budget in passing",
+      { path: "standup-notes" },
+    );
+    // First-line (title) match: "Budget" is the first line itself.
+    await store.createNote("Budget Review\nQ3 numbers", { path: "budget-review" });
+
+    const hits = await store.searchNotes("budget");
+    expect(hits.length).toBeGreaterThanOrEqual(2);
+    expect(hits[0].path).toBe("budget-review");
+  });
+
+  it("requires ALL query terms to be present in the first line to boost (a partial title match doesn't qualify)", async () => {
+    // "budget" is in the title but "review" is only in the body — a
+    // PARTIAL title match, which stays in the body-only tier.
+    await store.createNote("Budget notes\nsee the quarterly review for details", { path: "partial" });
+    // Both "budget" and "review" are in the title — a FULL title match.
+    await store.createNote("Budget Review\nQ3 numbers", { path: "full-match" });
+
+    const hits = await store.searchNotes("budget review");
+    expect(hits.map((n) => n.path)).toEqual(["full-match", "partial"]);
+  });
+
+  it("ties (both notes in the same tier) keep the existing relevance order", async () => {
+    // Two title-matching notes plus one body-only note. Comparing literal
+    // mode (boosted) against advanced mode with the same plain-word query
+    // (identical FTS5 syntax, so identical underlying bm25 order, but no
+    // boost pass) isolates the boost's effect: within the title-match
+    // tier, the boost must preserve whatever relative order the
+    // underlying relevance ranking already gave — a stable sort, not a
+    // fresh comparator that could reshuffle ties.
+    await store.createNote("Project Widget\nfirst, mentions widget again for relevance", { path: "w1" });
+    await store.createNote("Project Widget\nsecond", { path: "w2" });
+    await store.createNote("Unrelated\nbody-only mention of widget project", { path: "body-only" });
+
+    const boosted = await store.searchNotes("widget project");
+    const rawOrder = await store.searchNotes("widget project", { mode: "advanced" });
+
+    const titleTierBoosted = boosted.map((n) => n.path).filter((p) => p === "w1" || p === "w2");
+    const titleTierRaw = rawOrder.map((n) => n.path).filter((p) => p === "w1" || p === "w2");
+    expect(titleTierBoosted).toEqual(titleTierRaw);
+    // The title-match tier precedes the body-only note in the boosted result.
+    expect(boosted.map((n) => n.path).indexOf("body-only")).toBeGreaterThan(
+      Math.max(...["w1", "w2"].map((p) => boosted.map((n) => n.path).indexOf(p))),
+    );
+  });
+
+  it("does not disturb ordering when an explicit sort is requested", async () => {
+    await store.createNote("Zebra body-only mention of gadget", { path: "z" });
+    await store.createNote("Gadget Launch\nfirst line title match", { path: "a" });
+
+    const asc = await store.searchNotes("gadget", { sort: "asc" });
+    // created_at ASC means "z" (created first) comes before "a" — the
+    // title-boost must NOT override an explicit sort.
+    expect(asc.map((n) => n.path)).toEqual(["z", "a"]);
+  });
+
+  it("does not apply the boost under search_mode: advanced (raw FTS5 syntax, not naively tokenizable)", async () => {
+    await store.createNote("Body only mentions gadget in passing text here", { path: "body-only" });
+    await store.createNote("Gadget\nfirst line title match", { path: "title-match" });
+
+    const advanced = await store.searchNotes("gadget", { mode: "advanced" });
+    const literal = await store.searchNotes("gadget");
+
+    // Literal mode boosts the title match to the front.
+    expect(literal[0].path).toBe("title-match");
+    // Advanced mode is unaffected by the boost — order comes from bm25
+    // relevance alone (title-match still likely ranks first via the
+    // EXISTING path-weighted bm25, but that's a different mechanism; the
+    // test here just confirms advanced mode doesn't throw and returns
+    // both notes, not that ordering matches/mismatches literal mode).
+    expect(advanced.map((n) => n.path).sort()).toEqual(["body-only", "title-match"]);
+  });
+
+  it("a query with no results is unaffected (empty array in, empty array out)", async () => {
+    const hits = await store.searchNotes("nonexistent_term_xyz");
+    expect(hits).toEqual([]);
+  });
+
+  it("boosts on the post-frontmatter title line, not the `---` delimiter (shares computeDisplayTitle's frontmatter skip)", async () => {
+    // Direct-create misuse path: raw frontmatter-bearing content. Without
+    // the frontmatter skip, the derived "title" would be the literal
+    // string "---", which never matches any query term, so this note
+    // would wrongly land in the body-only tier.
+    await store.createNote(
+      "---\ntitle: irrelevant\n---\n# Budget Review\nQ3 numbers",
+      { path: "frontmatter-led" },
+    );
+    await store.createNote(
+      "Weekly Standup\nsomewhere we discuss the budget in passing",
+      { path: "body-only" },
+    );
+
+    const hits = await store.searchNotes("budget review");
+    expect(hits[0].path).toBe("frontmatter-led");
+  });
+});

package/core/src/seed-packs.test.ts

@@ -20,7 +20,10 @@
 
 import { describe, test, expect } from "bun:test";
 import {
+  ALL_NOTES_VIEW_PATH,
   applySeedPack,
+  ARCHIVE_VIEW_PATH,
+  ARCHIVED_TAG,
   CAPTURE_ANYTHING_PATH,
   CONNECT_AI_PATH,
   DEFAULT_VAULT_DESCRIPTION,
@@ -33,11 +36,17 @@ import {
   GUIDE_TAG,
   listSeedPacks,
   NOTES_REQUIRED_TAGS,
+  PINNED_TAG,
+  PINNED_VIEW_PATH,
+  RECENT_VIEW_PATH,
   SEED_PACK_NAMES,
+  STARTER_ONTOLOGY_PACK,
   SURFACE_STARTER_CONTENT,
   SURFACE_STARTER_PACK,
   SURFACE_STARTER_PATH,
   TAGS_GRAPH_PATH,
+  VIEW_TAG,
+  VIEWS_PATH_PREFIX,
   WELCOME_PATH,
   welcomePack,
   YOURS_TO_KEEP_PATH,
@@ -335,12 +344,119 @@ describe("surface-starter pack", () => {
   });
 });
 
+describe("starter-ontology pack", () => {
+  test("exactly four tags, in constitution order: view, archived, pinned, capture", () => {
+    expect(STARTER_ONTOLOGY_PACK.name).toBe("starter-ontology");
+    expect(STARTER_ONTOLOGY_PACK.tags.map((t) => t.name)).toEqual([
+      "view",
+      "archived",
+      "pinned",
+      "capture",
+    ]);
+  });
+
+  test("opt-in, not seeded by default", () => {
+    expect(STARTER_ONTOLOGY_PACK.description).toContain("Opt-in — not seeded by default.");
+  });
+
+  test("view is the one meta tag — carries the kind/query/lane_by/date_field schema", () => {
+    expect(VIEW_TAG.name).toBe("view");
+    expect(VIEW_TAG.description).toContain("meta tag");
+    expect(VIEW_TAG.fields).toBeDefined();
+    expect(Object.keys(VIEW_TAG.fields!)).toEqual([
+      "kind",
+      "query",
+      "lane_by",
+      "date_field",
+    ]);
+
+    const kind = VIEW_TAG.fields!.kind!;
+    expect(kind.type).toBe("string");
+    expect(kind.enum).toEqual(["list", "board", "calendar", "gallery"]);
+    expect(kind.default).toBe("list");
+
+    const query = VIEW_TAG.fields!.query!;
+    expect(query.type).toBe("string");
+
+    // lane_by / date_field are optional (no default — absent stays absent).
+    expect(VIEW_TAG.fields!.lane_by!.default).toBeUndefined();
+    expect(VIEW_TAG.fields!.date_field!.default).toBeUndefined();
+  });
+
+  test("archived + pinned are plain tags — no schema", () => {
+    expect(ARCHIVED_TAG.name).toBe("archived");
+    expect(ARCHIVED_TAG.fields).toBeUndefined();
+    expect(ARCHIVED_TAG.description).toContain("out of the flow of the present");
+
+    expect(PINNED_TAG.name).toBe("pinned");
+    expect(PINNED_TAG.fields).toBeUndefined();
+    expect(PINNED_TAG.description).toContain("partition");
+  });
+
+  test("capture is reused verbatim from NOTES_REQUIRED_TAGS — byte-equal, no drift risk", () => {
+    const capture = STARTER_ONTOLOGY_PACK.tags.find((t) => t.name === "capture");
+    expect(capture).toBe(NOTES_REQUIRED_TAGS[0]); // SAME object reference, not just equal content
+    expect(capture!.description).toBe(NOTES_REQUIRED_TAGS[0]!.description);
+  });
+
+  test("four seed #view notes mirroring the app's default pages", () => {
+    expect(STARTER_ONTOLOGY_PACK.notes.map((n) => n.path)).toEqual([
+      ALL_NOTES_VIEW_PATH,
+      RECENT_VIEW_PATH,
+      PINNED_VIEW_PATH,
+      ARCHIVE_VIEW_PATH,
+    ]);
+    for (const note of STARTER_ONTOLOGY_PACK.notes) {
+      expect(note.path.startsWith(VIEWS_PATH_PREFIX)).toBe(true);
+      expect(note.tags).toEqual(["view"]);
+      expect(note.metadata?.kind).toBe("list");
+      expect(typeof note.metadata?.query).toBe("string");
+      // Every seeded query must itself be valid JSON — a downstream reader
+      // parses it as query-notes params.
+      expect(() => JSON.parse(note.metadata!.query as string)).not.toThrow();
+    }
+  });
+
+  test("All notes / Recent exclude archived explicitly (authoring-time default, not magic)", () => {
+    for (const path of [ALL_NOTES_VIEW_PATH, RECENT_VIEW_PATH]) {
+      const note = noteAt(STARTER_ONTOLOGY_PACK, path);
+      const query = JSON.parse(note.metadata!.query as string);
+      expect(query.exclude_tags).toEqual(["archived"]);
+    }
+  });
+
+  test("Recent orders by updated_at desc", () => {
+    const query = JSON.parse(noteAt(STARTER_ONTOLOGY_PACK, RECENT_VIEW_PATH).metadata!.query as string);
+    expect(query.order_by).toBe("updated_at");
+    expect(query.sort).toBe("desc");
+  });
+
+  test("Pinned queries tag:pinned; Archive queries tag:archived (the deliberate exception to exclude_tags)", () => {
+    const pinnedQuery = JSON.parse(noteAt(STARTER_ONTOLOGY_PACK, PINNED_VIEW_PATH).metadata!.query as string);
+    expect(pinnedQuery.tag).toBe("pinned");
+
+    const archiveQuery = JSON.parse(noteAt(STARTER_ONTOLOGY_PACK, ARCHIVE_VIEW_PATH).metadata!.query as string);
+    expect(archiveQuery.tag).toBe("archived");
+    expect(archiveQuery.exclude_tags).toBeUndefined();
+  });
+
+  test("no dangling wikilinks within the pack", () => {
+    const seededPaths = new Set(STARTER_ONTOLOGY_PACK.notes.map((n) => n.path));
+    for (const note of STARTER_ONTOLOGY_PACK.notes) {
+      for (const target of wikilinkTargets(note.content)) {
+        expect(seededPaths.has(target)).toBe(true);
+      }
+    }
+  });
+});
+
 describe("pack registry", () => {
-  test("lists exactly the three packs, in order", () => {
+  test("lists exactly the four packs, in order", () => {
     expect([...SEED_PACK_NAMES]).toEqual([
       "welcome",
       "getting-started",
       "surface-starter",
+      "starter-ontology",
     ]);
     expect(listSeedPacks().map((p) => p.name)).toEqual([...SEED_PACK_NAMES]);
     for (const p of listSeedPacks()) {