@openparachute/vault 0.7.2 → 0.7.3-rc.10

package/core/src/display-title.test.ts

@@ -0,0 +1,190 @@
+/**
+ * Title axis (ratified 2026-07-17): a note's title IS its first line —
+ * derived from content, never stored. This file covers:
+ *   - `computeDisplayTitle` derivation (first non-empty line, heading
+ *     markers stripped, truncation, null-on-empty);
+ *   - `displayTitle` presence on the lean `NoteIndex` shape, both via the
+ *     MCP `query-notes` list path and the REST `GET /notes` list path.
+ *
+ * The search title-BOOST (ranking notes whose first line matches query
+ * terms above the rest) lives in `search-title-boost.test.ts` — a
+ * different concern (ranking) from derivation (this file).
+ */
+import { describe, it, expect, beforeEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { SqliteStore } from "./store.js";
+import { generateMcpTools } from "./mcp.js";
+import { computeDisplayTitle, toNoteIndex, DISPLAY_TITLE_MAX_LEN } from "./notes.js";
+import type { Note } from "./types.js";
+
+describe("computeDisplayTitle", () => {
+  it("returns the first line when content is a single line", () => {
+    expect(computeDisplayTitle("Grocery List")).toBe("Grocery List");
+  });
+
+  it("returns the first NON-EMPTY line, skipping leading blank lines", () => {
+    expect(computeDisplayTitle("\n\n  \nReal Title\nbody text")).toBe("Real Title");
+  });
+
+  it("strips a leading markdown heading marker + its whitespace", () => {
+    expect(computeDisplayTitle("# Grocery List\nmilk, eggs")).toBe("Grocery List");
+    expect(computeDisplayTitle("## Section Two\nbody")).toBe("Section Two");
+    expect(computeDisplayTitle("###### h6\nbody")).toBe("h6");
+  });
+
+  it("strips a heading marker with no space after it", () => {
+    expect(computeDisplayTitle("###Title\nbody")).toBe("Title");
+  });
+
+  it("treats a heading-marker-only line as blank and moves to the next line", () => {
+    expect(computeDisplayTitle("##\nReal Title")).toBe("Real Title");
+  });
+
+  it("does not strip markers past the first six (never a valid heading)", () => {
+    // 7 leading `#`s: the regex only matches 1-6, so the 7th `#` survives
+    // as ordinary content.
+    expect(computeDisplayTitle("####### Title")).toBe("# Title");
+  });
+
+  it("returns null for empty content", () => {
+    expect(computeDisplayTitle("")).toBeNull();
+  });
+
+  it("returns null for null/undefined content", () => {
+    expect(computeDisplayTitle(null)).toBeNull();
+    expect(computeDisplayTitle(undefined)).toBeNull();
+  });
+
+  it("returns null when content is whitespace-only", () => {
+    expect(computeDisplayTitle("   \n\t\n   ")).toBeNull();
+  });
+
+  it("returns null when every line is a bare heading marker", () => {
+    expect(computeDisplayTitle("#\n##\n### ")).toBeNull();
+  });
+
+  it("truncates to DISPLAY_TITLE_MAX_LEN code points", () => {
+    const longTitle = "a".repeat(200);
+    const result = computeDisplayTitle(longTitle)!;
+    expect(result.length).toBe(DISPLAY_TITLE_MAX_LEN);
+    expect(result).toBe("a".repeat(DISPLAY_TITLE_MAX_LEN));
+  });
+
+  it("does not truncate a title at or under the limit", () => {
+    const exact = "a".repeat(DISPLAY_TITLE_MAX_LEN);
+    expect(computeDisplayTitle(exact)).toBe(exact);
+    const short = "short title";
+    expect(computeDisplayTitle(short)).toBe(short);
+  });
+
+  it("truncates by Unicode code point, not UTF-16 code unit (no split surrogate pairs)", () => {
+    // Astral-plane emoji are 2 UTF-16 code units each but 1 code point.
+    const emojiTitle = "😀".repeat(150);
+    const result = computeDisplayTitle(emojiTitle)!;
+    expect(Array.from(result).length).toBe(DISPLAY_TITLE_MAX_LEN);
+  });
+
+  describe("leading frontmatter block (misuse path — direct create with raw frontmatter)", () => {
+    it("skips a closed frontmatter block and derives the first line of the DOCUMENT", () => {
+      expect(computeDisplayTitle("---\ntitle: X\n---\n# Real Title")).toBe("Real Title");
+    });
+
+    it("skips a closed frontmatter block with multiple fields + blank lines after", () => {
+      expect(
+        computeDisplayTitle("---\ntitle: X\ntags: [a, b]\n---\n\n\nReal Title\nbody"),
+      ).toBe("Real Title");
+    });
+
+    it("falls back to treating an UNTERMINATED opening `---` as ordinary content", () => {
+      // No closing fence anywhere in the content — a note whose real first
+      // line is literally "---" (e.g. a markdown horizontal rule opener)
+      // must not be mangled.
+      expect(computeDisplayTitle("---\nnot frontmatter, just a rule\nmore text")).toBe("---");
+    });
+
+    it("returns null when content is EXACTLY a closed frontmatter block (nothing after)", () => {
+      expect(computeDisplayTitle("---\ntitle: X\n---\n")).toBeNull();
+      expect(computeDisplayTitle("---\ntitle: X\n---")).toBeNull();
+    });
+
+    it("returns null when only blank lines follow a closed frontmatter block", () => {
+      expect(computeDisplayTitle("---\ntitle: X\n---\n\n  \n")).toBeNull();
+    });
+
+    it("does not treat a closing fence found past the bounded scan window as a frontmatter close", () => {
+      // Opening `---` with the closing fence past FRONTMATTER_SCAN_LINES
+      // (100): the scan gives up and falls back to ordinary-content
+      // behavior, deriving from line 0.
+      const filler = Array.from({ length: 150 }, (_, i) => `line ${i}`).join("\n");
+      expect(computeDisplayTitle(`---\n${filler}\n---\nReal Title`)).toBe("---");
+    });
+
+    it("normal content with no leading `---` is byte-identical to prior behavior", () => {
+      expect(computeDisplayTitle("# Grocery List\nmilk, eggs")).toBe("Grocery List");
+      expect(computeDisplayTitle("Just a note\nbody text")).toBe("Just a note");
+    });
+  });
+});
+
+describe("toNoteIndex — displayTitle wiring", () => {
+  const baseNote: Note = {
+    id: "n1",
+    content: "# Real Title\nbody",
+    createdAt: new Date().toISOString(),
+    tags: [],
+    metadata: {},
+  };
+
+  it("carries the computed display title onto the lean shape", () => {
+    const index = toNoteIndex(baseNote);
+    expect(index.displayTitle).toBe("Real Title");
+  });
+
+  it("is null when content is empty", () => {
+    const index = toNoteIndex({ ...baseNote, content: "" });
+    expect(index.displayTitle).toBeNull();
+  });
+
+  it("is null when content is missing entirely (defensive — matches preview's ?? \"\" fallback)", () => {
+    const { content: _drop, ...rest } = baseNote;
+    const index = toNoteIndex(rest as Note);
+    expect(index.displayTitle).toBeNull();
+  });
+});
+
+let store: SqliteStore;
+let db: Database;
+
+beforeEach(() => {
+  db = new Database(":memory:");
+  store = new SqliteStore(db);
+});
+
+describe("displayTitle — list-shape presence (MCP)", () => {
+  it("query-notes list mode (include_content default false) carries displayTitle", async () => {
+    await store.createNote("# Meeting Notes\nagenda: budget", { path: "a" });
+    const tools = generateMcpTools(store);
+    const queryNotes = tools.find((t) => t.name === "query-notes")!;
+    const result = await queryNotes.execute({}) as any[];
+    expect(result).toHaveLength(1);
+    expect(result[0].displayTitle).toBe("Meeting Notes");
+    expect(result[0].content).toBeUndefined();
+  });
+
+  it("query-notes include_content=true does NOT carry displayTitle (full Note shape, unchanged)", async () => {
+    await store.createNote("# Meeting Notes\nagenda: budget", { path: "a" });
+    const tools = generateMcpTools(store);
+    const queryNotes = tools.find((t) => t.name === "query-notes")!;
+    const result = await queryNotes.execute({ include_content: true }) as any[];
+    expect(result[0].content).toBeTruthy();
+    expect(result[0].displayTitle).toBeUndefined();
+  });
+
+  it("displayTitle is null on the lean shape for an empty note", async () => {
+    await store.createNote("", { path: "empty" });
+    const tools = generateMcpTools(store);
+    const queryNotes = tools.find((t) => t.name === "query-notes")!;
+    const result = await queryNotes.execute({}) as any[];
+    expect(result[0].displayTitle).toBeNull();
+  });
+});

package/core/src/embedding/chunker.test.ts

@@ -0,0 +1,97 @@
+import { describe, it, expect } from "bun:test";
+import { chunkNoteContent, DEFAULT_TARGET_CHARS, DEFAULT_MIN_CHARS } from "./chunker.js";
+
+describe("chunkNoteContent", () => {
+  it("returns a single empty chunk for empty content", () => {
+    expect(chunkNoteContent("")).toEqual([{ ix: 0, text: "" }]);
+    expect(chunkNoteContent("   \n\n  ")).toEqual([{ ix: 0, text: "" }]);
+  });
+
+  it("degenerate case: a short note is a single whole-note chunk", () => {
+    const content = "A short morning-pages note about coffee and focus.";
+    const chunks = chunkNoteContent(content);
+    expect(chunks).toEqual([{ ix: 0, text: content }]);
+  });
+
+  it("a note exactly at the target size is still a single chunk", () => {
+    const content = "x".repeat(DEFAULT_TARGET_CHARS);
+    const chunks = chunkNoteContent(content);
+    expect(chunks.length).toBe(1);
+    expect(chunks[0].ix).toBe(0);
+  });
+
+  it("splits a long note on markdown headings, keeping the heading with its section", () => {
+    const section = (n: number) => "word ".repeat(Math.ceil(DEFAULT_TARGET_CHARS / 5)) + `end${n}`;
+    const content = [
+      `# Heading One`,
+      section(1),
+      `## Heading Two`,
+      section(2),
+      `### Heading Three`,
+      section(3),
+    ].join("\n\n");
+
+    const chunks = chunkNoteContent(content);
+    expect(chunks.length).toBe(3);
+    expect(chunks[0].text.startsWith("# Heading One")).toBe(true);
+    expect(chunks[1].text.startsWith("## Heading Two")).toBe(true);
+    expect(chunks[2].text.startsWith("### Heading Three")).toBe(true);
+    // Sequential 0-based ix.
+    expect(chunks.map((c) => c.ix)).toEqual([0, 1, 2]);
+  });
+
+  it("packs paragraphs within an over-long headingless section up to the target size", () => {
+    const para = "sentence ".repeat(30); // a few hundred chars
+    const paras = Array.from({ length: 20 }, (_, i) => `${para}${i}`);
+    const content = paras.join("\n\n");
+    expect(content.length).toBeGreaterThan(DEFAULT_TARGET_CHARS * 2);
+
+    const chunks = chunkNoteContent(content);
+    expect(chunks.length).toBeGreaterThan(1);
+    // No chunk should wildly exceed the target (a single paragraph can
+    // exceed it, but these paragraphs are all well under target size).
+    for (const c of chunks) {
+      expect(c.text.length).toBeLessThanOrEqual(DEFAULT_TARGET_CHARS + para.length);
+    }
+    // Every paragraph's marker text survives somewhere in the chunk set.
+    for (let i = 0; i < paras.length; i++) {
+      expect(chunks.some((c) => c.text.includes(`${para}${i}`))).toBe(true);
+    }
+  });
+
+  it("a single oversized paragraph becomes its own chunk rather than being hard-truncated", () => {
+    const hugeParagraph = "word ".repeat(Math.ceil((DEFAULT_TARGET_CHARS * 2) / 5));
+    const content = `intro paragraph here\n\n${hugeParagraph}\n\nclosing paragraph here`;
+    const chunks = chunkNoteContent(content);
+    const hugeChunk = chunks.find((c) => c.text.includes(hugeParagraph.slice(0, 20)));
+    expect(hugeChunk).toBeDefined();
+    // Not truncated: the full paragraph text is present verbatim.
+    expect(hugeChunk!.text).toContain(hugeParagraph.trim());
+  });
+
+  it("merges a tiny trailing fragment into the previous chunk instead of leaving it alone", () => {
+    const bigSection = (n: number) => "word ".repeat(Math.ceil(DEFAULT_TARGET_CHARS / 5)) + `end${n}`;
+    const tinyTail = "ok"; // far under DEFAULT_MIN_CHARS
+    const content = [`# One`, bigSection(1), `# Two`, bigSection(2), `# Three`, tinyTail].join("\n\n");
+
+    const chunks = chunkNoteContent(content);
+    // The tiny "# Three\n\nok" section merges into the preceding chunk —
+    // it must NOT appear as its own separate chunk.
+    expect(chunks.some((c) => c.text.trim() === "# Three\n\nok" || c.text.trim() === "ok")).toBe(false);
+    // But its content is still present, folded into the last chunk.
+    expect(chunks[chunks.length - 1].text).toContain("ok");
+  });
+
+  it("respects custom targetChars/minChars options", () => {
+    const content = Array.from({ length: 10 }, (_, i) => `paragraph number ${i} `.repeat(5)).join("\n\n");
+    const chunks = chunkNoteContent(content, { targetChars: 100, minChars: 20 });
+    expect(chunks.length).toBeGreaterThan(1);
+  });
+
+  it("chunk indices are always sequential starting at 0", () => {
+    const section = (n: number) => "word ".repeat(Math.ceil(DEFAULT_TARGET_CHARS / 5)) + `end${n}`;
+    const content = Array.from({ length: 5 }, (_, i) => `## Section ${i}\n\n${section(i)}`).join("\n\n");
+    const chunks = chunkNoteContent(content);
+    expect(chunks.map((c) => c.ix)).toEqual(chunks.map((_, i) => i));
+  });
+});

package/core/src/embedding/chunker.ts

@@ -0,0 +1,180 @@
+/**
+ * Per-section chunking for semantic search (V2, ratified in-scope by Aaron
+ * per P0's finding — see `SEMANTIC-MVP-PLAN.md`/`RESULTS.md` §6: whole-note
+ * embedding dilutes long, multi-topic journal entries, and that dilution —
+ * not truncation — was the dominant miss pattern on Aaron's real corpus).
+ *
+ * Pure function, no I/O, no model dependency. Splits note content into
+ * chunks targeting ~400–500 tokens, using a `chars/4` approximation
+ * (documented, not exact — an exact tokenizer count would require a
+ * model-specific tokenizer in core, which core's dependency-purity rule
+ * forbids; the approximation only shapes chunk BOUNDARIES, not what gets
+ * embedded, so being off by a few dozen tokens costs nothing but a
+ * slightly-off chunk size). Splits on markdown headings first, then
+ * paragraphs within an over-long section, then merges chunks that end up
+ * too small into a neighbor so recall isn't fragmented by tiny slivers.
+ *
+ * Degenerate case: a note whose whole content already fits under the
+ * target size is returned as a single chunk (`ix: 0`) — this is the same
+ * shape a v1 whole-note embedding would produce, so a short note costs
+ * nothing extra.
+ */
+
+/** One chunk of a note's content, ready to embed. */
+export interface Chunk {
+  /** 0-based chunk index within the note — the `note_vectors.chunk_ix` key. */
+  ix: number;
+  /** The chunk's text, ready to hand to `EmbeddingProvider.embed()`. */
+  text: string;
+}
+
+/** `chars/4` is the documented, approximate chars-per-token ratio used to size chunks — see module doc. */
+const CHARS_PER_TOKEN_APPROX = 4;
+
+/** Middle of the plan's ~400–500 token target band. */
+const TARGET_TOKENS = 450;
+
+/** Default target chunk size in characters (~450 tokens). */
+export const DEFAULT_TARGET_CHARS = TARGET_TOKENS * CHARS_PER_TOKEN_APPROX;
+
+/** Default minimum chunk size before it gets merged into a neighbor (~1/4 of target). */
+export const DEFAULT_MIN_CHARS = Math.floor(DEFAULT_TARGET_CHARS / 4);
+
+export interface ChunkOpts {
+  /** Target chunk size in characters. Default `DEFAULT_TARGET_CHARS` (~1800 chars ≈ 450 tokens). */
+  targetChars?: number;
+  /** Chunks below this size get merged into the previous chunk. Default `DEFAULT_MIN_CHARS`. */
+  minChars?: number;
+}
+
+/**
+ * Split note content into embedding-ready chunks.
+ *
+ * Empty/whitespace-only content returns a single degenerate chunk with
+ * empty text (`ix: 0`) — callers (the staleness gate, the embed-on-write
+ * hook) treat an empty chunk as "nothing to embed" rather than special-
+ * casing zero chunks.
+ */
+export function chunkNoteContent(content: string, opts: ChunkOpts = {}): Chunk[] {
+  const targetChars = opts.targetChars ?? DEFAULT_TARGET_CHARS;
+  const minChars = opts.minChars ?? DEFAULT_MIN_CHARS;
+
+  const trimmed = content.trim();
+  if (trimmed.length === 0) return [{ ix: 0, text: "" }];
+  // Degenerate case (the common one — most notes are short): whole note
+  // fits in one chunk, byte-identical in spirit to v1's whole-note embed.
+  if (trimmed.length <= targetChars) return [{ ix: 0, text: trimmed }];
+
+  const sections = splitOnHeadings(trimmed);
+  const rawChunks: string[] = [];
+  for (const section of sections) {
+    if (section.length <= targetChars) {
+      rawChunks.push(section);
+      continue;
+    }
+    rawChunks.push(...packParagraphs(section, targetChars));
+  }
+
+  const merged = mergeSmallChunks(rawChunks, minChars);
+  return merged.map((text, ix) => ({ ix, text }));
+}
+
+/**
+ * Split on markdown ATX headings (`#` through `######`), keeping each
+ * heading attached to the section that follows it (so a chunk boundary
+ * never separates a heading from its own content). Text before the first
+ * heading (or a note with no headings at all) is its own leading section.
+ */
+function splitOnHeadings(text: string): string[] {
+  const lines = text.split("\n");
+  const sections: string[] = [];
+  let buf: string[] = [];
+  for (const line of lines) {
+    if (/^#{1,6}\s/.test(line) && buf.length > 0) {
+      sections.push(buf.join("\n").trim());
+      buf = [line];
+    } else {
+      buf.push(line);
+    }
+  }
+  if (buf.length > 0) sections.push(buf.join("\n").trim());
+  return sections.filter((s) => s.length > 0);
+}
+
+/** Split a section on blank-line-delimited paragraphs. */
+function splitOnParagraphs(text: string): string[] {
+  return text
+    .split(/\n\s*\n+/)
+    .map((p) => p.trim())
+    .filter((p) => p.length > 0);
+}
+
+/**
+ * Greedily pack a section's paragraphs into chunks up to `targetChars`.
+ * A single paragraph that alone exceeds `targetChars` becomes its own
+ * oversized chunk — chunking never hard-truncates content; the provider's
+ * own model window does that truncation, same as v1's whole-note path.
+ *
+ * If the section opens with its own markdown heading (the common case —
+ * `splitOnHeadings` attaches a heading to the section that follows it),
+ * the heading is pulled out and glued onto ONLY the first resulting
+ * chunk, rather than treated as just another paragraph competing for the
+ * `targetChars` budget. Without this, a section whose heading-plus-first-
+ * paragraph landed just over budget could split the heading into its own
+ * paragraph-sized "chunk," and — worse — a global small-chunk merge pass
+ * has no way to tell that fragment apart from any other tiny chunk, so it
+ * could get glued onto the END of the PRECEDING section instead of the
+ * body it actually introduces.
+ */
+function packParagraphs(section: string, targetChars: number): string[] {
+  const lines = section.split("\n");
+  let heading = "";
+  let body = section;
+  if (/^#{1,6}\s/.test(lines[0] ?? "")) {
+    heading = lines[0]!;
+    body = lines.slice(1).join("\n").trim();
+  }
+
+  const paras = splitOnParagraphs(body);
+  const chunks: string[] = [];
+  let buf = "";
+  for (const p of paras) {
+    if (buf && buf.length + p.length + 2 > targetChars) {
+      chunks.push(buf);
+      buf = p;
+    } else {
+      buf = buf ? `${buf}\n\n${p}` : p;
+    }
+  }
+  if (buf) chunks.push(buf);
+  if (chunks.length === 0) chunks.push("");
+  if (heading) chunks[0] = `${heading}\n\n${chunks[0]}`.trim();
+  return chunks.filter((c) => c.length > 0);
+}
+
+/**
+ * Merge any chunk under `minChars` into the PRECEDING chunk (so a tiny
+ * trailing fragment — a one-line closing section, a short final
+ * paragraph — doesn't become its own low-signal vector that fragments
+ * recall). A small chunk that ends up FIRST (nothing precedes it — e.g. a
+ * lone heading line that `packParagraphs` split away from its own
+ * content) has no predecessor to fold backward into, so it's folded
+ * FORWARD into what's then the second chunk instead — a tiny fragment
+ * never survives as its own low-signal vector regardless of which end of
+ * the note it lands on.
+ */
+function mergeSmallChunks(chunks: string[], minChars: number): string[] {
+  const merged: string[] = [];
+  for (const c of chunks) {
+    if (merged.length > 0 && c.length < minChars) {
+      merged[merged.length - 1] = `${merged[merged.length - 1]!}\n\n${c}`;
+    } else {
+      merged.push(c);
+    }
+  }
+  if (merged.length > 1 && merged[0]!.length < minChars) {
+    merged[1] = `${merged[0]!}\n\n${merged[1]!}`;
+    merged.shift();
+  }
+  return merged;
+}

package/core/src/embedding/provider.ts

@@ -0,0 +1,108 @@
+/**
+ * Embedding provider seam (semantic-search MVP, V2).
+ *
+ * An `EmbeddingProvider` is the single, runtime-agnostic contract for
+ * turning text into a dense vector. It exists so the semantic-search scan
+ * doesn't hard-code a model or an HTTP call — the store resolves a
+ * provider and calls `embed()`, and the provider owns HOW text becomes a
+ * vector.
+ *
+ * ## Why this lives in core (not src)
+ *
+ * The interface must be importable from BOTH runtimes without dragging in
+ * Bun- or Node-only APIs, or any model library:
+ *
+ *   - the Bun vault (`src/embedding/onnx-transformers.ts` — the bundled
+ *     floor provider — and `src/embedding/external-api.ts` — the
+ *     OpenAI-compatible config upgrade);
+ *   - the cloud vault (a future Cloudflare Workers-AI provider implemented
+ *     against THIS interface, mirroring `transcription/workers-ai.ts`).
+ *
+ * So it is pure types + one dependency-free error class — no `fetch`, no
+ * ONNX/transformers import, no Node-only builtin. Core has no package
+ * `exports` map, so consumers import the subpath directly
+ * (`../core/src/embedding/provider.ts`), the same convention as
+ * `core/src/transcription/provider.ts`, which this file mirrors verbatim.
+ *
+ * ## The fold (context)
+ *
+ * Ratified 2026-07-16 (Aaron: GO on the semantic-search MVP, per
+ * `SEMANTIC-MVP-PLAN.md` — P0's real-corpus eval cleared the "keep
+ * building" bar). This seam is the shared contract both doors implement;
+ * see `core/src/embedding/chunker.ts` for the per-note chunking this feeds,
+ * and `core/src/notes.ts:semanticSearchNotes` for the consumer.
+ */
+
+/** Batch-first input — a provider embeds many texts in one call (backfill). */
+export interface EmbedInput {
+  texts: string[];
+}
+
+/** What a provider returns for a batch: one vector per input text, same order. */
+export interface EmbedResult {
+  /** One vector per `EmbedInput.texts` entry, same order/length. */
+  vectors: Float32Array[];
+  /** The model identifier that produced these vectors (recorded per-row in `note_vectors`). */
+  model: string;
+  /** Vector dimensionality — every vector in `vectors` has this length. */
+  dims: number;
+}
+
+/** Provider readiness probe result. */
+export interface ProviderAvailability {
+  /** True when the provider can service `embed()` calls right now. */
+  ok: boolean;
+  /** Human-readable cause when `ok` is false (e.g. "no embedding provider configured"). */
+  reason?: string;
+}
+
+/**
+ * The embedding contract. Implementations own the text→vector step; the
+ * store owns resolving which provider is active, chunking, freshness
+ * gating, and the cosine scan — none of which belong here.
+ */
+export interface EmbeddingProvider {
+  /** Stable provider identifier, surfaced on the capability flag (e.g. "onnx-transformers", "external-api", "workers-ai"). */
+  readonly name: string;
+  /** Model identifier this provider produces vectors with (e.g. "bge-small-en-v1.5"). Recorded on every `note_vectors` row so a model change is detectable. */
+  readonly model: string;
+  /** Vector dimensionality this provider's model produces. */
+  readonly dims: number;
+  /** Turn a batch of texts into vectors (or throw — see `EmbeddingError` for the retry contract). */
+  embed(input: EmbedInput): Promise<EmbedResult>;
+  /**
+   * Cheap, side-effect-free readiness check. MUST NOT perform an actual
+   * embedding or a network round-trip unless that is genuinely cheap — it
+   * gates the `embeddings` capability flag on the vault landing.
+   */
+  available(): Promise<ProviderAvailability>;
+}
+
+/**
+ * Structured, provider-agnostic embedding failure.
+ *
+ * Mirrors `TranscriptionError` exactly (see
+ * `core/src/transcription/provider.ts`): `retriable` decides whether the
+ * caller retries with backoff (a transient upstream failure) or gives up
+ * immediately (a config problem the operator must fix). `code` is a
+ * stable machine string (e.g. `missing_provider`) so callers branch on it
+ * instead of regex-matching message text.
+ */
+export class EmbeddingError extends Error {
+  /** Stable machine code (e.g. "missing_provider"), when the provider supplied one. */
+  readonly code?: string;
+  /** Upstream HTTP status, when the failure came from an HTTP provider. */
+  readonly httpStatus?: number;
+  /** Whether retrying the same input could plausibly succeed. */
+  readonly retriable: boolean;
+  constructor(
+    message: string,
+    opts: { code?: string; httpStatus?: number; retriable: boolean },
+  ) {
+    super(message);
+    this.name = "EmbeddingError";
+    this.code = opts.code;
+    this.httpStatus = opts.httpStatus;
+    this.retriable = opts.retriable;
+  }
+}

package/core/src/embedding/staleness.test.ts

@@ -0,0 +1,87 @@
+import { describe, it, expect } from "bun:test";
+import { planStaleness, contentHash, type ExistingVectorRow } from "./staleness.js";
+import type { Chunk } from "./chunker.js";
+
+const MODEL = "bge-small-en-v1.5";
+
+function chunk(ix: number, text: string): Chunk {
+  return { ix, text };
+}
+
+function row(ix: number, text: string, model = MODEL): ExistingVectorRow {
+  return { chunk_ix: ix, model, content_hash: contentHash(text) };
+}
+
+describe("contentHash", () => {
+  it("is deterministic", () => {
+    expect(contentHash("hello")).toBe(contentHash("hello"));
+  });
+
+  it("differs for different content", () => {
+    expect(contentHash("hello")).not.toBe(contentHash("hello!"));
+  });
+});
+
+describe("planStaleness", () => {
+  it("a brand-new note (no existing rows) is entirely stale", () => {
+    const chunks = [chunk(0, "some content")];
+    const plan = planStaleness([], chunks, MODEL);
+    expect(plan.stale).toEqual(chunks);
+    expect(plan.obsoleteIxs).toEqual([]);
+  });
+
+  it("no-op edit: identical content + same model produces zero stale chunks", () => {
+    const text = "unchanged content";
+    const chunks = [chunk(0, text)];
+    const existing = [row(0, text)];
+    const plan = planStaleness(existing, chunks, MODEL);
+    expect(plan.stale).toEqual([]);
+    expect(plan.obsoleteIxs).toEqual([]);
+  });
+
+  it("content change on one chunk marks only that chunk stale", () => {
+    const chunks = [chunk(0, "old text"), chunk(1, "second chunk unchanged")];
+    const existing = [row(0, "old text"), row(1, "second chunk unchanged")];
+    // Mutate chunk 0's text after the existing row was hashed — simulates
+    // an edit to that section only.
+    chunks[0] = chunk(0, "NEW text");
+    const plan = planStaleness(existing, chunks, MODEL);
+    expect(plan.stale).toEqual([chunk(0, "NEW text")]);
+    expect(plan.obsoleteIxs).toEqual([]);
+  });
+
+  it("a note that shrank (fewer chunks) marks the dropped chunk_ix as obsolete", () => {
+    const existing = [row(0, "a"), row(1, "b"), row(2, "c")];
+    const chunks = [chunk(0, "a"), chunk(1, "b")]; // chunk 2 no longer exists
+    const plan = planStaleness(existing, chunks, MODEL);
+    expect(plan.stale).toEqual([]);
+    expect(plan.obsoleteIxs).toEqual([2]);
+  });
+
+  it("a note that grew (more chunks) marks the new chunk_ix as stale, not obsolete", () => {
+    const existing = [row(0, "a")];
+    const chunks = [chunk(0, "a"), chunk(1, "new second chunk")];
+    const plan = planStaleness(existing, chunks, MODEL);
+    expect(plan.stale).toEqual([chunk(1, "new second chunk")]);
+    expect(plan.obsoleteIxs).toEqual([]);
+  });
+
+  it("a model change marks every existing row obsolete and every current chunk stale (full sweep)", () => {
+    const existing = [row(0, "a", "old-model"), row(1, "b", "old-model")];
+    const chunks = [chunk(0, "a"), chunk(1, "b")];
+    const plan = planStaleness(existing, chunks, "new-model");
+    expect(plan.stale).toEqual(chunks);
+    expect(plan.obsoleteIxs).toEqual([0, 1]);
+  });
+
+  it("composes shrink + edit + grow in one plan", () => {
+    const existing = [row(0, "a"), row(1, "b-old"), row(2, "c")]; // 3 will drop, 1 will change
+    const chunks = [chunk(0, "a"), chunk(1, "b-new"), chunk(3, "d")]; // note: ix 3, not 2 — a full re-chunk
+    const plan = planStaleness(existing, chunks, MODEL);
+    expect(plan.stale.map((c) => c.ix)).toEqual([1, 3]);
+    // ix 1 still exists in the current chunk set (its content just
+    // changed), so it's STALE, not obsolete — only ix 2 (dropped entirely)
+    // is obsolete.
+    expect(plan.obsoleteIxs).toEqual([2]);
+  });
+});