@openparachute/vault 0.7.3-rc.5 → 0.7.3-rc.7

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

@@ -0,0 +1,149 @@
+/**
+ * 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("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/mcp.ts

@@ -45,6 +45,18 @@ import {
   contentRangeRequiresContent,
   MIN_CONTENT_LENGTH,
 } from "./content-range.js";
+import {
+  BLOCKED_ATTACHMENT_EXTENSIONS,
+  sanitizeAttachmentExtension,
+  mimeForAttachmentExtension,
+} from "./attachment/policy.js";
+import {
+  computeTicketTtlMs,
+  generateTicketId,
+  MAX_TICKET_UPLOAD_BYTES,
+  type AttachmentTicket,
+  type AttachmentTicketProvider,
+} from "./attachment/tickets.js";
 
 export interface McpToolDef {
   name: string;
@@ -80,7 +92,7 @@ export interface McpToolDef {
  */
 function structuredError(
   message: string,
-  fields: { error_type: string; field?: string; hint?: string },
+  fields: { error_type: string; field?: string; hint?: string } & Record<string, unknown>,
 ): Error {
   return Object.assign(new Error(message), fields);
 }
@@ -246,6 +258,39 @@ export interface GenerateMcpToolsOpts {
    * path with no extra fetch.
    */
   aggregateVisibility?: (note: Note) => boolean;
+  /**
+   * `AttachmentTicketProvider` seam (vault attachment-tickets design,
+   * Wave 1 — D10 "tools omitted when unwired"). When provided,
+   * `generateMcpTools` appends `request-attachment-upload` /
+   * `request-attachment-download` to the returned tool list. Omitted (a
+   * door that hasn't wired its ticket seam yet) → the two tools are
+   * ABSENT from the list entirely — not merely erroring on call — so an
+   * agent is never shown an affordance the runtime can't back.
+   */
+  attachmentTickets?: {
+    provider: AttachmentTicketProvider;
+    /** This vault's own name — stamped onto every minted ticket so the spend route can cheaply reject a cross-vault replay. */
+    vaultName: string;
+    /**
+     * Absolute base URL for this vault's ticket spend path, no trailing
+     * slash — e.g. `https://host/vault/<name>`. A minted ticket's URL is
+     * `${urlBase}/tickets/<id>`. Resolved by the caller (server layer)
+     * from the incoming request's `X-Forwarded-Host`/proto — core stays
+     * request-unaware.
+     */
+    urlBase: string;
+    /**
+     * OPTIONAL per-note visibility predicate (tag-scope confidentiality —
+     * same intent as `expandVisibility`/`ifExistsVisible` above, kept
+     * separate because it needs to be awaitable). Both ticket tools run
+     * fully async execute() paths (unlike `expandVisibility`/
+     * `ifExistsVisible`, which feed core's SYNCHRONOUS wikilink/if_exists
+     * code and so need the shared pre-resolved-allowlist-holder
+     * machinery), so this can just be awaited inline. Omitted (unscoped /
+     * internal callers) → every note/attachment is visible.
+     */
+    noteVisible?: (note: Note) => boolean | Promise<boolean>;
+  };
 }
 
 /**
@@ -312,7 +357,7 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
     });
   };
 
-  return [
+  const tools: McpToolDef[] = [
 
     // =====================================================================
     // 1. query-notes — the universal read tool
@@ -1619,7 +1664,7 @@ A note's response carries \`existed\` (true/false) whenever ITS \`if_exists\` wa
 - For batch: pass a \`notes\` array, each with an \`id\` field.
 - **Optimistic concurrency is required by default.** Pass \`if_updated_at\` with the \`updated_at\` value you last read — the update is rejected with a conflict error if the note has changed since. Re-read, reconcile, and retry. To skip the safety check (e.g. bulk migration), pass \`force: true\` instead; the update then runs unconditionally. \`force\` only waives the *requirement to supply* \`if_updated_at\` — if you pass both, the precondition you supplied still applies and a mismatch returns a conflict error. \`append\` / \`prepend\` only updates are exempt from the precondition (no-conflict-by-design). **Batch default (vault#554):** a top-level \`force\` and/or \`if_updated_at\` alongside a \`notes\` array applies as the DEFAULT for every item that doesn't set its own — e.g. \`{force: true, notes: [{id: "a", content: "..."}, {id: "b", content: "...", if_updated_at: "..."}]}\` forces item "a" but still enforces the precondition on item "b" (its own \`if_updated_at\` wins). Per-item values always take precedence over the top-level default.
 - **Idempotent upsert via \`if_missing: "create"\`** — when the note doesn't exist, create it from this same payload (content/path/tags/metadata become the create fields; OC precondition skipped — nothing to conflict with). Response carries \`created: true\`. Useful for nightly sync loops that don't know ahead of time whether the note exists. Default \`"fail"\` (current behavior — missing note errors). See vault#309.
-- \`include_content\` (default \`true\`) — set \`false\` to receive a lean index shape (\`id\`, \`path\`, \`createdAt\`, \`updatedAt\`, \`createdBy\`, \`createdVia\`, \`lastUpdatedBy\`, \`lastUpdatedVia\`, \`tags\`, \`metadata\`, \`byteSize\`, \`preview\`) instead of full content. Useful for agents making frequent small edits to large notes (e.g. via \`append\` or \`content_edit\`) where re-receiving the body is the dominant cost. \`validation_status\` is preserved on the lean shape when present.
+- \`include_content\` (default \`true\`) — set \`false\` to receive a lean index shape (\`id\`, \`path\`, \`createdAt\`, \`updatedAt\`, \`createdBy\`, \`createdVia\`, \`lastUpdatedBy\`, \`lastUpdatedVia\`, \`tags\`, \`metadata\`, \`byteSize\`, \`preview\`, \`displayTitle\`) instead of full content. Useful for agents making frequent small edits to large notes (e.g. via \`append\` or \`content_edit\`) where re-receiving the body is the dominant cost. \`validation_status\` is preserved on the lean shape when present. \`displayTitle\` is the note's first non-empty content line (heading markers stripped, ~120 chars max), \`null\` when content is empty — never stored, computed fresh from content already in hand.
 
 Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\` (the principal + interface of the first write) and \`lastUpdatedBy\`/\`lastUpdatedVia\` (the most recent write). NULL on notes written before attribution existed. Filter on them with \`created_by\`/\`last_updated_by\`/\`created_via\`/\`last_updated_via\`.`,
       inputSchema: {
@@ -1693,7 +1738,7 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
           },
           include_content: {
             type: "boolean",
-            description: "Response shape opt-out. Default `true` (returns the full Note with content). Set `false` to receive the lean index shape (drops `content`, adds `byteSize` and a whitespace-collapsed `preview`). `validation_status` is preserved on the lean shape when present. Applies uniformly to single and batch responses.",
+            description: "Response shape opt-out. Default `true` (returns the full Note with content). Set `false` to receive the lean index shape (drops `content`, adds `byteSize`, a whitespace-collapsed `preview`, and a computed `displayTitle`). `validation_status` is preserved on the lean shape when present. Applies uniformly to single and batch responses.",
           },
           include_links: {
             type: "boolean",
@@ -2779,6 +2824,202 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
     },
 
   ];
+
+  // =====================================================================
+  // 12/13. request-attachment-upload / request-attachment-download —
+  // runtime-lane attachment tickets (Wave 1). Present ONLY when the
+  // server layer wires an AttachmentTicketProvider — see
+  // `GenerateMcpToolsOpts.attachmentTickets`'s doc comment (D10, "tools
+  // omitted when unwired"). Bytes never pass through either tool: the
+  // model gets back a URL + a literal curl_example; a runtime with a
+  // shell spends it directly, outside this MCP session entirely.
+  // =====================================================================
+  const ticketSeam = opts?.attachmentTickets;
+  if (ticketSeam) {
+    tools.push(
+      {
+        name: "request-attachment-upload",
+        requiredVerb: "write",
+        description:
+          "Mint a short-lived, single-use upload URL for a note attachment. Bytes never pass through this tool — you get back a URL (+ a ready-to-run `curl_example`) your runtime's shell spends directly; no MCP session credential is needed to spend it. Provide the target `note` (id or path), the `filename`, and its exact `size_bytes` — declared here and enforced at spend (a mismatch, or exceeding the 100 MiB REST upload cap, fails the mint or the upload). `mime_type` is inferred from the filename's extension when omitted. Pass `transcribe: true` for an audio file to enqueue it exactly like the REST attach flow does. The ticket's `expires_at` scales with declared size (10 minutes base + 10s per MiB, capped at 30 minutes) and can be spent exactly once — a failed curl means re-minting, not retrying the same URL.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            note: { type: "string", description: "Target note ID or path" },
+            filename: { type: "string", description: "Original filename — sanitized for a blocked extension (active-content types: .html/.svg/.xml/.js/.css/…) and used to infer the MIME type when `mime_type` is omitted." },
+            size_bytes: {
+              type: "number",
+              description: `Declared upload size in bytes. Must be > 0 and <= ${MAX_TICKET_UPLOAD_BYTES} (100 MiB — the same ceiling REST's own /storage/upload enforces). The spend endpoint rejects (413) any upload that exceeds this declared size.`,
+            },
+            mime_type: { type: "string", description: "MIME type to store on the attachment row. Inferred from `filename`'s extension when omitted (`application/octet-stream` for an uncurated extension)." },
+            transcribe: { type: "boolean", description: "Opt into transcription for an audio attachment — mirrors the REST `POST /notes/:id/attachments` `transcribe` flag." },
+          },
+          required: ["note", "filename", "size_bytes"],
+        },
+        execute: async (params) => {
+          const noteRef = params.note;
+          if (typeof noteRef !== "string" || noteRef.trim() === "") {
+            throw structuredError("`note` is required", {
+              error_type: "missing_required_field",
+              field: "note",
+              how_to: "pass the target note's id or path",
+            });
+          }
+          const filename = params.filename;
+          if (typeof filename !== "string" || filename.trim() === "") {
+            throw structuredError("`filename` is required", {
+              error_type: "missing_required_field",
+              field: "filename",
+              how_to: "pass the original filename you're about to upload",
+            });
+          }
+          const sizeBytes = params.size_bytes;
+          if (typeof sizeBytes !== "number" || !Number.isFinite(sizeBytes) || sizeBytes <= 0) {
+            throw structuredError("`size_bytes` must be a positive number", {
+              error_type: "invalid_query",
+              field: "size_bytes",
+              how_to: "pass the exact byte length of the file you're about to upload",
+            });
+          }
+          if (sizeBytes > MAX_TICKET_UPLOAD_BYTES) {
+            throw structuredError(
+              `size_bytes (${sizeBytes}) exceeds the ${MAX_TICKET_UPLOAD_BYTES} byte (100 MiB) upload cap`,
+              {
+                error_type: "file_too_large",
+                field: "size_bytes",
+                limit: MAX_TICKET_UPLOAD_BYTES,
+                got: sizeBytes,
+                how_to: "REST /storage/upload shares this same 100 MiB ceiling — split the file or upload it out-of-band",
+              },
+            );
+          }
+
+          const note = requireNote(db, noteRef);
+          if (ticketSeam.noteVisible && !(await ticketSeam.noteVisible(note))) {
+            // Uniform not_found — a tag-scoped caller learns nothing about
+            // an out-of-scope note's existence (same posture as every other
+            // scope-gated tool in this file).
+            throw structuredError(`Note not found: "${noteRef}"`, { error_type: "not_found", field: "note" });
+          }
+
+          const ext = sanitizeAttachmentExtension(filename);
+          if (BLOCKED_ATTACHMENT_EXTENSIONS.has(ext)) {
+            throw structuredError(`File type ${ext} not allowed (active/executable content)`, {
+              error_type: "blocked_upload_extension",
+              field: "filename",
+              extension: ext,
+              how_to: "rename with a non-executable extension, or store the content as note text instead",
+            });
+          }
+
+          const mimeType =
+            typeof params.mime_type === "string" && params.mime_type.trim() !== ""
+              ? params.mime_type
+              : mimeForAttachmentExtension(ext);
+
+          const now = Date.now();
+          const expiresAt = now + computeTicketTtlMs(sizeBytes);
+          const id = generateTicketId();
+          const ticket: AttachmentTicket = {
+            id,
+            kind: "upload",
+            vaultName: ticketSeam.vaultName,
+            createdAt: now,
+            expiresAt,
+            noteId: note.id,
+            filename,
+            mimeType,
+            sizeBytes,
+            transcribe: params.transcribe === true,
+          };
+          await ticketSeam.provider.put(ticket);
+
+          const url = `${ticketSeam.urlBase}/tickets/${id}`;
+          return {
+            method: "PUT",
+            url,
+            headers: { "content-type": mimeType },
+            expires_at: new Date(expiresAt).toISOString(),
+            max_bytes: sizeBytes,
+            curl_example: `curl -X PUT -H 'content-type: ${mimeType}' --data-binary @${filename} '${url}'`,
+          };
+        },
+      },
+      {
+        name: "request-attachment-download",
+        requiredVerb: "read",
+        description:
+          "Mint a short-lived, single-use download URL for an existing attachment's bytes. Bytes never pass through this tool — you get back a URL (+ a ready-to-run `curl_example`) your runtime's shell spends directly; no MCP session credential is needed to spend it. Pass the `attachment_id` from a note's `include_attachments: true` rows (query-notes) or `GET .../attachments`. The ticket's `expires_at` follows the same size-scaled window as upload tickets (10 minutes base, up to 30) and can be spent exactly once.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            attachment_id: { type: "string", description: "The attachment's id (from a note's attachment rows)" },
+          },
+          required: ["attachment_id"],
+        },
+        execute: async (params) => {
+          const attachmentId = params.attachment_id;
+          if (typeof attachmentId !== "string" || attachmentId.trim() === "") {
+            throw structuredError("`attachment_id` is required", {
+              error_type: "missing_required_field",
+              field: "attachment_id",
+              how_to: "pass the attachment id from a note's attachment rows",
+            });
+          }
+
+          const attachment = await store.getAttachment(attachmentId);
+          if (!attachment) {
+            throw structuredError(`Attachment not found: "${attachmentId}"`, {
+              error_type: "not_found",
+              field: "attachment_id",
+            });
+          }
+
+          if (ticketSeam.noteVisible) {
+            const owningNote = await store.getNote(attachment.noteId);
+            // A missing owning note (shouldn't happen — ON DELETE CASCADE —
+            // but never trust it) collapses to the same not_found as an
+            // out-of-scope note: no oracle either way.
+            if (!owningNote || !(await ticketSeam.noteVisible(owningNote))) {
+              throw structuredError(`Attachment not found: "${attachmentId}"`, {
+                error_type: "not_found",
+                field: "attachment_id",
+              });
+            }
+          }
+
+          const metaSize = attachment.metadata?.size;
+          const declaredSize = typeof metaSize === "number" ? metaSize : undefined;
+          const now = Date.now();
+          const expiresAt = now + computeTicketTtlMs(declaredSize);
+          const id = generateTicketId();
+          const ticket: AttachmentTicket = {
+            id,
+            kind: "download",
+            vaultName: ticketSeam.vaultName,
+            createdAt: now,
+            expiresAt,
+            attachmentId: attachment.id,
+            mimeType: attachment.mimeType,
+            sizeBytes: declaredSize,
+          };
+          await ticketSeam.provider.put(ticket);
+
+          const url = `${ticketSeam.urlBase}/tickets/${id}`;
+          return {
+            method: "GET",
+            url,
+            mime_type: attachment.mimeType,
+            ...(declaredSize !== undefined ? { size_bytes: declaredSize } : {}),
+            expires_at: new Date(expiresAt).toISOString(),
+            curl_example: `curl -o downloaded${sanitizeAttachmentExtension(attachment.path) || ""} '${url}'`,
+          };
+        },
+      },
+    );
+  }
+
+  return tools;
 }
 
 // ---------------------------------------------------------------------------

package/core/src/notes.ts

@@ -25,6 +25,7 @@ import { computeExpandedTagCounts, loadTagHierarchy, stripTagHash } from "./tag-
 import { chunkForInClause, IN_VIA_JSON_EACH, jsonEachParam } from "./sql-in.js";
 import {
   buildLiteralSearchQuery,
+  extractLiteralBoostTerms,
   SEARCH_WEIGHT_PATH,
   SEARCH_WEIGHT_CONTENT,
   type SearchMode,
@@ -1810,6 +1811,61 @@ function searchSyntaxError(rawQuery: string, err: unknown, mode: SearchMode): Qu
   });
 }
 
+/**
+ * Post-rank a search result page (title axis, ratified 2026-07-17) so
+ * notes whose display title (first line of content) contains EVERY boost
+ * term outrank the rest — a title-match tier ahead of a body-only-match
+ * tier. Stable partition: within a tier, the incoming order (FTS5
+ * relevance, or an explicit `sort`) is preserved untouched — two notes
+ * that both match, or both don't, keep their relative order.
+ *
+ * No-migration by design (see the search-seam note on `searchNotes`
+ * below): re-orders the already-fetched page in memory instead of adding
+ * a weighted title column to `notes_fts`, which would need a schema
+ * migration + backfill. `notes_fts`'s existing `SEARCH_WEIGHT_PATH` bm25
+ * weighting (above) already boosts by note PATH — a different axis from
+ * the ratified title model (title = first line of CONTENT, not path).
+ * This function is the one that boosts by the content-derived title.
+ */
+function boostTitleMatches(notes: Note[], terms: string[]): Note[] {
+  if (terms.length === 0) return notes;
+  return notes
+    .map((note, index) => ({ note, index, titleMatch: titleMatchesAllTerms(note.content, terms) }))
+    .sort((a, b) => {
+      if (a.titleMatch === b.titleMatch) return a.index - b.index; // stable
+      return a.titleMatch ? -1 : 1;
+    })
+    .map((x) => x.note);
+}
+
+function titleMatchesAllTerms(content: string | null | undefined, terms: string[]): boolean {
+  const title = computeDisplayTitle(content);
+  if (!title) return false;
+  const lower = title.toLowerCase();
+  return terms.every((t) => lower.includes(t));
+}
+
+/**
+ * Apply the title-boost post-rank to a fetched search page. Skipped
+ * whenever it would fight the caller's intent:
+ *   - an explicit `sort: "asc"|"desc"` means the caller wants chronological
+ *     order, not relevance re-ranking;
+ *   - `search_mode: "advanced"` text carries raw FTS5 syntax (boolean
+ *     operators, column filters, prefix `*`) — naively tokenizing it into
+ *     "terms" would misread operators as content (see
+ *     `extractLiteralBoostTerms`'s doc comment). Only literal-mode queries
+ *     (the default) get boosted today.
+ */
+function applySearchTitleBoost(
+  notes: Note[],
+  mode: SearchMode,
+  rawQuery: string,
+  sort: "asc" | "desc" | undefined,
+): Note[] {
+  if (sort !== undefined || mode !== "literal") return notes;
+  return boostTitleMatches(notes, extractLiteralBoostTerms(rawQuery));
+}
+
 export function searchNotes(
   db: Database,
   query: string,
@@ -1846,6 +1902,14 @@ export function searchNotes(
   // The weights are our own numeric constants (not user input) interpolated
   // directly — bm25()'s weight arguments are positional per-column
   // multipliers, not general SQL expressions callers can influence.
+  //
+  // NOTE: "title" here means the note's `path` — this predates the title
+  // axis (ratified 2026-07-17), under which a note's title is its first
+  // CONTENT line, not its path. `applySearchTitleBoost` (below) is the
+  // mechanism for THAT axis: a post-rank pass over the already-scored page,
+  // not a third FTS column. The two are complementary, not redundant — a
+  // note can have a matching path with a non-matching first line, or vice
+  // versa.
   const scoreExpr = `(-1.0 * bm25(notes_fts, ${SEARCH_WEIGHT_PATH}, ${SEARCH_WEIGHT_CONTENT}))`;
 
   // `sort` honored under search (vault#551 WS2A item 3): default stays FTS5
@@ -1886,7 +1950,7 @@ export function searchNotes(
         ORDER BY ${orderBy}
         LIMIT ?
       `).all(ftsQuery, ...searchTags, limit) as (NoteRow & { score: number })[];
-      return notesWithTags(db, rows, scoresById(rows));
+      return applySearchTitleBoost(notesWithTags(db, rows, scoresById(rows)), mode, query, opts?.sort);
     } catch (err) {
       // Surface EVERY FTS5 error structured, never a raw rethrow (vault#551):
       // advanced mode expects it (the caller passed raw syntax); literal
@@ -1908,7 +1972,7 @@ export function searchNotes(
       ORDER BY ${orderBy}
       LIMIT ?
     `).all(ftsQuery, limit) as (NoteRow & { score: number })[];
-    return notesWithTags(db, rows, scoresById(rows));
+    return applySearchTitleBoost(notesWithTags(db, rows, scoresById(rows)), mode, query, opts?.sort);
   } catch (err) {
     if (err instanceof QueryError) throw err;
     throw searchSyntaxError(query, err, mode);
@@ -2702,10 +2766,52 @@ export function mergeTags(
 /** Max code points in a NoteIndex preview. */
 export const NOTE_INDEX_PREVIEW_LEN = 120;
 
+/** Max code points in a computed `displayTitle` (title axis, ratified 2026-07-17). */
+export const DISPLAY_TITLE_MAX_LEN = 120;
+
+/**
+ * Derive a note's display title: the first non-empty line of `content`,
+ * with a leading markdown heading marker (`#` through `######`) and its
+ * following whitespace stripped, truncated to `DISPLAY_TITLE_MAX_LEN` code
+ * points. `null` when content has no non-empty line (empty or
+ * whitespace/heading-marker-only note).
+ *
+ * The ratified title model (2026-07-17): a note's title IS its first line
+ * — derived from content, NEVER stored as its own column. This function is
+ * the one place that derivation happens; callers (`toNoteIndex` below) call
+ * it fresh at read time. Timestamp-path formatting — what a surface shows
+ * in place of a `null` title — is deliberately NOT this function's job; it
+ * reports the honest content-derived value (or its absence) and leaves
+ * rendering to the caller.
+ */
+export function computeDisplayTitle(content: string | null | undefined): string | null {
+  if (!content) return null;
+  for (const rawLine of content.split("\n")) {
+    const stripped = rawLine.replace(/^#{1,6}\s*/, "").trim();
+    if (stripped === "") continue;
+    // Iterate by Unicode code points so we don't split surrogate pairs mid-character.
+    const codePoints = Array.from(stripped);
+    return codePoints.length > DISPLAY_TITLE_MAX_LEN
+      ? codePoints.slice(0, DISPLAY_TITLE_MAX_LEN).join("")
+      : stripped;
+  }
+  return null;
+}
+
 /**
  * Convert a full Note into its lean index shape:
- * drops `content`, adds `byteSize` and a whitespace-collapsed `preview`.
- * Shared between the `query-notes` MCP tool, HTTP /notes endpoints, and /graph.
+ * drops `content`, adds `byteSize`, a whitespace-collapsed `preview`, and a
+ * computed `displayTitle`. Shared between the `query-notes` MCP tool, HTTP
+ * /notes endpoints, and /graph.
+ *
+ * Perf note: `displayTitle` costs nothing extra here — every caller of this
+ * function already has the full `Note` (content included) in hand by the
+ * time it's called. `queryNotes`'s two-phase page fetch selects a narrow
+ * `id`-only column list for the ORDER BY/pagination phase, but the second
+ * phase (`fetchNotesByIdsOrdered`) always `SELECT *`s the page's full rows
+ * before `toNoteIndex` ever runs — same as `preview`/`byteSize` today. If a
+ * future lean-list path is added that genuinely avoids a content read, it
+ * must NOT call this function (or `toNoteIndex`) on a content-less row.
  */
 export function toNoteIndex(note: Note): NoteIndex {
   const content = note.content ?? "";
@@ -2732,6 +2838,7 @@ export function toNoteIndex(note: Note): NoteIndex {
     metadata: note.metadata,
     byteSize,
     preview,
+    displayTitle: computeDisplayTitle(note.content),
     ...(note.score !== undefined ? { score: note.score } : {}),
   };
 }

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",