@openparachute/vault 0.7.2 → 0.7.3-rc.10

package/core/src/schema-defaults.ts

@@ -41,6 +41,7 @@
  */
 
 import { Database } from "bun:sqlite";
+import { timestampToMs } from "./cursor.js";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -57,7 +58,7 @@ export interface SchemaField {
    * `type_mismatch` warning that previously fired on every integer-shaped
    * field because the validator had no `"integer"` case. See vault#310.
    */
-  type?: "string" | "number" | "integer" | "boolean" | "array" | "object" | "reference";
+  type?: "string" | "number" | "integer" | "boolean" | "array" | "object" | "reference" | "date";
   enum?: string[];
   description?: string;
   /**
@@ -320,6 +321,82 @@ export function resolveNoteSchemas(
   return { effectiveTags, mergedFields, conflicts };
 }
 
+/**
+ * Normalize `date`-typed field VALUES in `metadata` to canonical UTC ISO
+ * form (`Z`-suffixed) BEFORE persisting (vault#date-field-type — mixed-
+ * offset corruption, caught in review).
+ *
+ * The bug: every consumer of an indexed `date` field — `buildOperatorClause`
+ * (query-operators.ts), `date_filter` and `order_by` (notes.ts) — compares
+ * the generated `meta_<field>` column as raw TEXT. ISO-8601 strings sort
+ * correctly under a TEXT compare ONLY when every value shares the same
+ * offset representation. `timestampToMs` (cursor.ts) — the validator both
+ * `defaultMatchesType` and `valueMatchesType` reuse — correctly ACCEPTS an
+ * explicit `±HH:MM` offset (validation was never the gap), but a value like
+ * `"2026-07-16T10:00:00+02:00"` (= `08:00Z`) persisted VERBATIM sorts AFTER
+ * `"2026-07-16T09:00:00Z"` (= `09:00Z`) under a raw string compare, even
+ * though the actual instant is earlier — a mixed-offset vault silently gets
+ * wrong range-query/order_by/date_filter results. This is the exact bug
+ * class `updated_at` got a dedicated ms-mirror column for (vault#585/#586,
+ * see `notes.ts`'s `dateFilter` block) that never extended to user-declared
+ * `date` fields.
+ *
+ * The fix is normalize-on-write, not reject-on-write (matching the
+ * "paths are normalized on write" precedent — instant preserved,
+ * representation canonicalized) — rejecting offsets would defeat the
+ * type's own motivation (calendar integrations and other emitters commonly
+ * produce offset timestamps, not always `Z`). Only a FULL timestamp (has a
+ * time component) is rewritten, to `new Date(ms).toISOString()` — always
+ * UTC, millisecond precision, `Z`-suffixed. A bare `YYYY-MM-DD` value is
+ * left untouched: it has no offset to normalize, is already canonical, and
+ * prefix-sorts correctly against full timestamps sharing the same calendar
+ * day. A value that fails `timestampToMs` is left untouched too — that's a
+ * `type_mismatch` for `valueMatchesType` to catch, not this function's job.
+ *
+ * COPY-ON-WRITE, never mutates the input `metadata` object (vault#date-
+ * field-type review round 2) — `core/` is a published library; a direct
+ * embedder holding a reference to the object THEY passed in must never see
+ * it change out from under them. Returns the SAME reference when nothing
+ * needs rewriting (the common case — no unnecessary allocation on the
+ * no-op path) or `metadata` is undefined; returns a freshly shallow-copied
+ * object, with only the rewritten field(s) replaced, the first time a
+ * rewrite is actually needed. Every call site must use the RETURNED value
+ * (not assume its input was mutated) — see `store.createNote`/`updateNote`/
+ * `createNotes`/`createNoteRaw`, all of which reassign their local
+ * `opts`/`updates`/`input` binding from the return rather than relying on a
+ * side effect.
+ *
+ * Called from `store.createNote`/`updateNote`/`createNotes`/`createNoteRaw`
+ * — the lowest chokepoint every write path (MCP, REST, import) funnels
+ * through — BEFORE the row is persisted, so the value that's validated by
+ * `validateNote`/`valueMatchesType` upstream (offset-tolerant, so
+ * normalization can't newly fail a write) and the value that's written +
+ * echoed back on the response are the SAME normalized string.
+ */
+export function normalizeDateFields(
+  resolved: ResolvedSchemas,
+  note: { tags?: string[]; metadata?: Record<string, unknown> },
+): Record<string, unknown> | undefined {
+  const metadata = note.metadata;
+  if (!metadata) return metadata;
+  const { mergedFields } = resolveNoteSchemas(resolved, note);
+  let copy: Record<string, unknown> | undefined;
+  for (const [fieldName, { spec }] of mergedFields) {
+    if (spec.type !== "date") continue;
+    const value = metadata[fieldName];
+    if (typeof value !== "string") continue;
+    // Bare `YYYY-MM-DD` (no time component) has no offset to normalize.
+    if (/^\d{4}-\d{2}-\d{2}$/.test(value)) continue;
+    const ms = timestampToMs(value);
+    if (ms === null) continue; // unparseable — valueMatchesType's job, not ours
+    const canonical = new Date(ms).toISOString();
+    if (canonical === value) continue;
+    if (!copy) copy = { ...metadata }; // lazy: only copy once a rewrite is due
+    copy[fieldName] = canonical;
+  }
+  return copy ?? metadata;
+}
+
 function fieldSpecsEqual(a: SchemaField, b: SchemaField): boolean {
   if (a.type !== b.type) return false;
   if (!stringArraysEqual(a.enum, b.enum)) return false;
@@ -390,6 +467,13 @@ function valueMatchesType(value: unknown, type: SchemaField["type"], cardinality
         return Array.isArray(value) && value.every((item) => typeof item === "string");
       }
       return typeof value === "string";
+    // `date` validates like `string` — an ISO-8601 date (`YYYY-MM-DD`) or
+    // full RFC3339 timestamp. Reuses `cursor.ts`'s `timestampToMs` (the SAME
+    // UTC-correct parser `date_filter`'s `updated_at` bound uses), not a
+    // second date parser — see tag-schemas.ts's `VALID_FIELD_TYPES` doc
+    // comment.
+    case "date":
+      return typeof value === "string" && timestampToMs(value) !== null;
   }
 }
 

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