@openparachute/vault 0.6.0 → 0.6.2-rc.1

package/core/src/links.ts

@@ -1,6 +1,6 @@
 import { Database } from "bun:sqlite";
 import type { Link, NoteSummary, HydratedLink } from "./types.js";
-import { getNoteTags } from "./notes.js";
+import { getNoteTagsForNotes } from "./notes.js";
 
 export function createLink(
   db: Database,
@@ -103,28 +103,25 @@ function parseMetadata(raw: string | null): Record<string, unknown> | undefined
   try { return JSON.parse(raw); } catch { return undefined; }
 }
 
-function getNoteSummary(db: Database, noteId: string): NoteSummary | undefined {
-  const row = db.prepare(
-    "SELECT id, path, metadata, created_at, updated_at FROM notes WHERE id = ?",
-  ).get(noteId) as SummaryRow | null;
-  if (!row) return undefined;
-  return {
-    id: row.id,
-    path: row.path ?? undefined,
-    metadata: parseMetadata(row.metadata),
-    createdAt: row.created_at,
-    updatedAt: row.updated_at ?? undefined,
-    tags: getNoteTags(db, row.id),
-  };
-}
+/** IN-list chunk size — matches getLinkCounts' conservative bound-variable floor. */
+const IN_CHUNK = 900;
 
 function getNoteSummaries(db: Database, noteIds: string[]): Map<string, NoteSummary> {
   const map = new Map<string, NoteSummary>();
   if (noteIds.length === 0) return map;
-  const placeholders = noteIds.map(() => "?").join(", ");
-  const rows = db.prepare(
-    `SELECT id, path, metadata, created_at, updated_at FROM notes WHERE id IN (${placeholders})`,
-  ).all(...noteIds) as SummaryRow[];
+  const ids = [...new Set(noteIds)];
+  const rows: SummaryRow[] = [];
+  for (let i = 0; i < ids.length; i += IN_CHUNK) {
+    const chunk = ids.slice(i, i + IN_CHUNK);
+    const placeholders = chunk.map(() => "?").join(", ");
+    rows.push(...db.prepare(
+      `SELECT id, path, metadata, created_at, updated_at FROM notes WHERE id IN (${placeholders})`,
+    ).all(...chunk) as SummaryRow[]);
+  }
+  // ONE batched tag lookup for every summary on the page — this used to be
+  // a per-summary query, which made hydrating a well-linked note cost
+  // O(linked notes) round-trips (2026-06-10 perf measurements).
+  const tagsById = getNoteTagsForNotes(db, rows.map((r) => r.id));
   for (const row of rows) {
     map.set(row.id, {
       id: row.id,
@@ -132,7 +129,7 @@ function getNoteSummaries(db: Database, noteIds: string[]): Map<string, NoteSumm
       metadata: parseMetadata(row.metadata),
       createdAt: row.created_at,
       updatedAt: row.updated_at ?? undefined,
-      tags: getNoteTags(db, row.id),
+      tags: tagsById.get(row.id) ?? [],
     });
   }
   return map;
@@ -148,8 +145,11 @@ export function getLinksHydrated(
   opts?: { direction?: "outbound" | "inbound" | "both"; include_content?: boolean },
 ): HydratedLink[] {
   const links = getLinks(db, noteId, opts);
+  return hydrateLinks(db, links);
+}
 
-  // Collect all note IDs we need to hydrate
+/** Attach source/target note summaries to a set of links (batched). */
+function hydrateLinks(db: Database, links: Link[]): HydratedLink[] {
   const noteIds = new Set<string>();
   for (const link of links) {
     noteIds.add(link.sourceId);
@@ -165,6 +165,61 @@ export function getLinksHydrated(
   }));
 }
 
+/**
+ * Batch variant of `getLinksHydrated` for the `include_links` enrichment
+ * loops (MCP query-notes list path, REST GET /api/notes): hydrates links for
+ * a whole PAGE of notes in a constant number of queries — two indexed
+ * IN-list scans over `links` per chunk, one summary fetch, one batched tag
+ * lookup — instead of (1 link query + 1 summary query + N tag queries) per
+ * note. See the 2026-06-10 perf measurements (include_links scaled
+ * per-returned-note).
+ *
+ * Returns a map keyed by every requested note id (empty array when the note
+ * has no links). Each note's list contains links touching it in either
+ * direction, ordered created_at DESC — same contract as the single-note
+ * `getLinksHydrated`. A link between two notes that are BOTH on the page
+ * appears in both notes' lists, exactly as the per-note calls produced.
+ */
+export function getLinksHydratedForNotes(
+  db: Database,
+  noteIds: string[],
+): Map<string, HydratedLink[]> {
+  const result = new Map<string, HydratedLink[]>();
+  if (noteIds.length === 0) return result;
+  const ids = [...new Set(noteIds)];
+  for (const id of ids) result.set(id, []);
+
+  // Collect every link touching any requested note, deduped on the
+  // (source, target, relationship) primary key so a link whose endpoints
+  // are both on the page is fetched once.
+  const rowsByKey = new Map<string, LinkRow>();
+  for (let i = 0; i < ids.length; i += IN_CHUNK) {
+    const chunk = ids.slice(i, i + IN_CHUNK);
+    const placeholders = chunk.map(() => "?").join(", ");
+    for (const column of ["source_id", "target_id"] as const) {
+      const rows = db.prepare(
+        `SELECT * FROM links WHERE ${column} IN (${placeholders})`,
+      ).all(...chunk) as LinkRow[];
+      for (const row of rows) {
+        rowsByKey.set(`${row.source_id}|${row.target_id}|${row.relationship}`, row);
+      }
+    }
+  }
+
+  // Stable sort newest-first to mirror the single-note SQL's
+  // ORDER BY created_at DESC (ISO timestamps sort lexicographically).
+  const links = [...rowsByKey.values()]
+    .sort((a, b) => (a.created_at < b.created_at ? 1 : a.created_at > b.created_at ? -1 : 0))
+    .map(rowToLink);
+
+  const hydrated = hydrateLinks(db, links);
+  for (const link of hydrated) {
+    result.get(link.sourceId)?.push(link);
+    if (link.targetId !== link.sourceId) result.get(link.targetId)?.push(link);
+  }
+  return result;
+}
+
 /**
  * Batch link-degree counter (vault feedback #4).
  *

package/core/src/mcp.ts

@@ -15,6 +15,12 @@ import {
   type ExpandContext,
   type ExpandMode,
 } from "./expand.js";
+import {
+  parseContentRange,
+  applyContentRange,
+  contentRangeRequiresContent,
+  MIN_CONTENT_LENGTH,
+} from "./content-range.js";
 
 export interface McpToolDef {
   name: string;
@@ -153,6 +159,8 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
 
 Defaults: include_content=true for single note, false for lists. include_links=false. tag_match="any".
 
+Large notes: pass \`content_offset\` / \`content_length\` (UTF-8 bytes) for a bounded read of note content — the response carries the slice plus \`content_total_length\` and \`content_next_offset\` (null when complete). Loop, feeding \`content_next_offset\` back as \`content_offset\`, to read a note too large for one response.
+
 Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returned content. Tune with \`expand_depth\` (1–3, default 1) and \`expand_mode\` ("full" inlines full content, "summary" inlines only metadata.summary). Expansions are deduplicated across the query and cycle-guarded.`,
       inputSchema: {
         type: "object",
@@ -243,6 +251,16 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
               "Opaque cursor for 'since last checked' agent loops (vault#313). First call: omit. The response will include `next_cursor` — pass it on the subsequent call to receive only notes created or updated since the prior page. The cursor binds to the query's filters (tag, path, metadata, etc.); changing them between calls returns a structured `cursor_query_mismatch` error. Pagination via cursor orders results by `updated_at ASC` and is mutually exclusive with `order_by` and `sort: \"desc\"`. The response shape switches to `{notes, next_cursor}` when this parameter is present.",
           },
           include_content: { type: "boolean", description: "Include note content (default: true for single, false for list)" },
+          content_offset: {
+            type: "number",
+            description:
+              "Byte offset (UTF-8) into note content to start reading from (default 0). For reading a note too large for one response: pass the previous response's `content_next_offset` here to continue. An offset landing mid-codepoint is aligned DOWN to the codepoint's leading byte (chained `content_next_offset` values are always aligned); the effective start is echoed back as `content_offset` on the response. Requires content in the response — errors when combined with include_content=false (or a list query without include_content=true).",
+          },
+          content_length: {
+            type: "number",
+            description:
+              `Maximum bytes (UTF-8) of note content to return (minimum ${MIN_CONTENT_LENGTH}). When this or content_offset is set, the returned \`content\` is the byte slice and the response gains \`content_offset\` (effective start), \`content_total_length\` (full content size in bytes), and \`content_next_offset\` (pass back as content_offset to continue; null when the slice reaches the end). Slices end on a UTF-8 codepoint boundary, so a slice may be up to 3 bytes under the budget — never over. Concatenating the slices from offset 0 through content_next_offset=null reconstructs the content byte-for-byte. On list queries the same window applies to each note's content independently. When expand_links=true the range applies to the returned (expanded) content.`,
+          },
           include_metadata: {
             oneOf: [
               { type: "boolean" },
@@ -292,17 +310,31 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
             }
           : null;
 
+        // --- Content range (bounded reads for large notes) ---
+        // Validates loudly: bad values throw QueryError here, before any
+        // query work. Null when neither param is present — response shape
+        // stays byte-identical to the no-pagination behavior.
+        const contentRange = parseContentRange(params.content_offset, params.content_length);
+
         // --- Single note by ID/path ---
         if (params.id) {
           const note = resolveNote(db, params.id as string);
           if (!note) return { error: "Note not found", id: params.id };
           const includeContent = params.include_content !== false; // default true for single
+          // Range params are meaningless on a content-less shape — error
+          // rather than silently ignore (same loud-validation policy as
+          // `expand`).
+          if (contentRange && !includeContent) throw contentRangeRequiresContent();
           let result: any = includeContent ? { ...note } : noteOps.toNoteIndex(note);
           if (expandCtx && includeContent && typeof result.content === "string") {
             // Mark the top-level note as already expanded so it can't recursively inline itself.
             expandCtx.expanded.add(note.id);
             result.content = expandContent(result.content, expandCtx, expandDepth);
           }
+          // Range applies to the FINAL returned content — after wikilink
+          // expansion — so the window the client pages through is the same
+          // document it would have received unpaged.
+          if (contentRange && includeContent) applyContentRange(result, contentRange);
           result = filterMetadata(result, params.include_metadata as boolean | string[] | undefined);
           if (params.include_links) {
             result.links = linkOps.getLinksHydrated(db, note.id);
@@ -457,6 +489,10 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
 
         // --- Format output ---
         const includeContent = params.include_content === true; // default false for list
+        // Range params require content in the response — on lists that
+        // means an explicit include_content=true (the lean default carries
+        // no content to slice). Error rather than silently ignore.
+        if (contentRange && !includeContent) throw contentRangeRequiresContent();
         const includeMetadata = params.include_metadata as boolean | string[] | undefined;
         let output: any[] = includeContent ? results.map((n) => ({ ...n })) : results.map(noteOps.toNoteIndex);
 
@@ -471,6 +507,15 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
           }
         }
 
+        // --- Content range (per-note, post-expansion) ---
+        // The same byte window applies to EACH note's content independently
+        // — the primary use is a single large note, but list mode keeps the
+        // simple per-note semantic (every note reports its own
+        // content_total_length / content_next_offset).
+        if (contentRange && includeContent) {
+          for (const n of output) applyContentRange(n, contentRange);
+        }
+
         // --- Apply metadata filtering ---
         if (includeMetadata !== undefined && includeMetadata !== true) {
           output = output.map((n: any) => filterMetadata(n, includeMetadata));
@@ -491,10 +536,17 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
 
         // --- Hydrate links/attachments per note if requested ---
         if (params.include_links || params.include_attachments) {
+          // Links hydrate for the WHOLE page in a constant number of
+          // queries (see getLinksHydratedForNotes) — the per-note variant
+          // cost (1 link query + 1 summary query + N tag queries) × page
+          // size. 2026-06-10 perf measurements.
+          const linksByNote = params.include_links
+            ? linkOps.getLinksHydratedForNotes(db, (output as any[]).map((n: any) => n.id))
+            : null;
           const enrichedOut: any[] = [];
           for (const n of output as any[]) {
             const enriched: any = { ...n };
-            if (params.include_links) enriched.links = linkOps.getLinksHydrated(db, n.id);
+            if (linksByNote) enriched.links = linksByNote.get(n.id) ?? [];
             if (params.include_attachments) enriched.attachments = await store.getAttachments(n.id);
             enrichedOut.push(enriched);
           }

package/core/src/notes.ts

@@ -18,7 +18,7 @@ import {
   type CursorPayload,
   type QueryHashInputs,
 } from "./cursor.js";
-import { releaseField } from "./indexed-fields.js";
+import { getIndexedField, releaseField } from "./indexed-fields.js";
 
 let idCounter = 0;
 
@@ -142,11 +142,7 @@ export function getNotes(db: Database, ids: string[]): Note[] {
   const rows = db.prepare(
     `SELECT * FROM notes WHERE id IN (${placeholders}) ORDER BY created_at`,
   ).all(...ids) as NoteRow[];
-  return rows.map((row) => {
-    const note = rowToNote(row);
-    note.tags = getNoteTags(db, note.id);
-    return note;
-  });
+  return notesWithTags(db, rows);
 }
 
 /**
@@ -489,7 +485,6 @@ export function deleteNote(db: Database, id: string): void {
 export function queryNotes(db: Database, opts: QueryOpts): Note[] {
   const conditions: string[] = [];
   const params: SQLQueryBindings[] = [];
-  const joins: string[] = [];
 
   // Include tags — "all" (default): must have ALL tags; "any": must have ANY tag.
   // The `_tagsExpanded` internal field carries per-input-tag descendant sets
@@ -498,6 +493,15 @@ export function queryNotes(db: Database, opts: QueryOpts): Note[] {
   // `{manual, voice, text, ...}` per declared `_tags/*` config notes. Falls
   // back to `[opts.tags[i]]` (single-element set) when no expansion is set,
   // preserving the original semantics.
+  //
+  // Membership is expressed as a SEMIJOIN (`n.id IN (SELECT note_id ...)`),
+  // not a `JOIN note_tags`. A JOIN multiplies rows when a note carries
+  // several matching tags, which forced `SELECT DISTINCT n.*` — and that
+  // DISTINCT materialized every candidate's FULL row (content included)
+  // into a temp B-tree before LIMIT could apply, making large-tag queries
+  // cost O(candidates × row size) regardless of limit. The IN-subquery
+  // rides idx_note_tags_tag, produces each note id at most once, and lets
+  // the whole query drop DISTINCT. See the 2026-06-10 perf measurements.
   if (opts.tags && opts.tags.length > 0) {
     const tagSets: string[][] = (opts as QueryOpts & { _tagsExpanded?: string[][] })._tagsExpanded
       ?? opts.tags.map((t) => [t]);
@@ -508,17 +512,16 @@ export function queryNotes(db: Database, opts: QueryOpts): Note[] {
       const flat = Array.from(new Set(tagSets.flat()));
       if (flat.length > 0) {
         const placeholders = flat.map(() => "?").join(", ");
-        joins.push(`JOIN note_tags nt_or ON nt_or.note_id = n.id AND nt_or.tag_name IN (${placeholders})`);
+        conditions.push(`n.id IN (SELECT note_id FROM note_tags WHERE tag_name IN (${placeholders}))`);
         params.push(...flat);
       }
     } else {
-      // "all": one JOIN per input tag, each accepting the input or any descendant.
-      for (let i = 0; i < tagSets.length; i++) {
-        const set = tagSets[i] ?? [];
-        if (set.length === 0) continue;
-        const alias = `nt${i}`;
+      // "all": one membership clause per input tag, each accepting the
+      // input or any descendant.
+      for (const set of tagSets) {
+        if (!set || set.length === 0) continue;
         const placeholders = set.map(() => "?").join(", ");
-        joins.push(`JOIN note_tags ${alias} ON ${alias}.note_id = n.id AND ${alias}.tag_name IN (${placeholders})`);
+        conditions.push(`n.id IN (SELECT note_id FROM note_tags WHERE tag_name IN (${placeholders}))`);
         params.push(...set);
       }
     }
@@ -601,6 +604,20 @@ export function queryNotes(db: Database, opts: QueryOpts): Note[] {
   // Metadata filters — operator objects route through the indexed generated
   // column (fast, loud errors on non-indexed fields); primitives keep the
   // existing JSON-scan exact-match behavior for backcompat.
+  //
+  // Plain-equality fast path (2026-06-10 perf measurements): when the field
+  // happens to be indexed, a plain `{field: value}` equality used to pay the
+  // same full-table json_extract scan as a non-indexed field — 280× slower
+  // than the operator form `{field: {eq: value}}` ON THE SAME column. We now
+  // prepend an indexed-prefilter conjunct (`"meta_<field>" = ?`) so the
+  // B-tree narrows the candidates, while KEEPING the original json_extract
+  // clause as a residual predicate. The conjunction is result-identical to
+  // the scan by construction: any row the scan matches also satisfies the
+  // prefilter (the generated column is the same json_extract under the
+  // column's type affinity), and rows where the affinity-converted column
+  // matches but the raw extraction doesn't (e.g. JSON number 5 vs query
+  // string "5") are excluded by the residual — exactly as the scan excluded
+  // them. Pinned by query-plain-eq-routing.test.ts.
   if (opts.metadata) {
     for (const [key, value] of Object.entries(opts.metadata)) {
       if (isOperatorObject(value)) {
@@ -612,8 +629,17 @@ export function queryNotes(db: Database, opts: QueryOpts): Note[] {
         conditions.push(sql);
         params.push(...opParams);
       } else {
-        conditions.push(`json_extract(n.metadata, '$.' || ?) = ?`);
-        params.push(key, typeof value === "string" ? value : JSON.stringify(value));
+        const bound = typeof value === "string" ? value : JSON.stringify(value);
+        // `getIndexedField` returning a row proves `key` was validated by
+        // FIELD_NAME_RE at declaration time, so interpolating the column
+        // name is safe — same justification as buildOperatorClause.
+        if (getIndexedField(db, key)) {
+          conditions.push(`("meta_${key}" = ? AND json_extract(n.metadata, '$.' || ?) = ?)`);
+          params.push(bound, key, bound);
+        } else {
+          conditions.push(`json_extract(n.metadata, '$.' || ?) = ?`);
+          params.push(key, bound);
+        }
       }
     }
   }
@@ -768,30 +794,89 @@ export function queryNotes(db: Database, opts: QueryOpts): Note[] {
     // the column name is safe to interpolate. Append created_at as a
     // stable tiebreaker so two rows with the same indexed value have a
     // deterministic order.
-    orderBy = `"meta_${opts.orderBy}" ${direction}, n.created_at ${direction}`;
+    orderBy = `"meta_${opts.orderBy}" ${direction}, n.created_at ${direction}, n.id ${direction}`;
   } else {
-    orderBy = `n.created_at ${direction}`;
+    // id tiebreaker: same-millisecond inserts get deterministic relative
+    // order — load-bearing now that the two-phase page fetch makes
+    // pagination ordering the contract (#485 review nit).
+    orderBy = `n.created_at ${direction}, n.id ${direction}`;
   }
   const limit = typeof opts.limit === "number" ? opts.limit : 100;
   const offset = typeof opts.offset === "number" ? opts.offset : 0;
 
   const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
 
-  const sql = `
-    SELECT DISTINCT n.* FROM notes n
-    ${joins.join("\n")}
+  // Two-phase "deferred join" page fetch (2026-06-10 perf measurements).
+  //
+  // Phase 1 selects ONLY `n.id` — the ORDER BY temp B-tree (when one is
+  // needed) holds narrow id/sort-key entries instead of full note rows, so
+  // sort/materialization cost no longer scales with content size. With the
+  // tag semijoin above there is no row multiplication, so no DISTINCT.
+  //
+  // Phase 2 fetches full rows for just the page (≤ limit ids) and re-orders
+  // to the phase-1 order; tags are hydrated in ONE batched query instead of
+  // one query per returned note.
+  const idSql = `
+    SELECT n.id FROM notes n
     ${whereClause}
     ORDER BY ${orderBy}
     LIMIT ? OFFSET ?
   `;
   params.push(limit, offset);
 
-  const rows = db.prepare(sql).all(...params) as NoteRow[];
-  return rows.map((row) => {
-    const note = rowToNote(row);
-    note.tags = getNoteTags(db, note.id);
-    return note;
-  });
+  const idRows = db.prepare(idSql).all(...params) as { id: string }[];
+  return fetchNotesByIdsOrdered(db, idRows.map((r) => r.id));
+}
+
+/** Chunk size for IN-list queries — comfortably under SQLite's conservative
+ *  999 bound-variable floor (older builds), matching getLinkCounts. */
+const IN_CHUNK = 900;
+
+/**
+ * Fetch full note rows for `ids`, preserving the input order, with tags
+ * hydrated via ONE batched query per chunk (not one per note). Ids not
+ * found (deleted between phases) are silently dropped.
+ */
+function fetchNotesByIdsOrdered(db: Database, ids: string[]): Note[] {
+  if (ids.length === 0) return [];
+  const rowsById = new Map<string, NoteRow>();
+  for (let i = 0; i < ids.length; i += IN_CHUNK) {
+    const chunk = ids.slice(i, i + IN_CHUNK);
+    const placeholders = chunk.map(() => "?").join(", ");
+    const rows = db.prepare(
+      `SELECT * FROM notes WHERE id IN (${placeholders})`,
+    ).all(...chunk) as NoteRow[];
+    for (const row of rows) rowsById.set(row.id, row);
+  }
+  const notes: Note[] = [];
+  for (const id of ids) {
+    const row = rowsById.get(id);
+    if (row) notes.push(rowToNote(row));
+  }
+  const tagsById = getNoteTagsForNotes(db, notes.map((n) => n.id));
+  for (const note of notes) note.tags = tagsById.get(note.id) ?? [];
+  return notes;
+}
+
+/**
+ * Batched tag lookup: tags for many notes in one IN-list query per chunk.
+ * Per-note arrays are sorted by tag_name — identical to `getNoteTags`.
+ * Every requested id is present in the map (empty array when untagged).
+ */
+export function getNoteTagsForNotes(db: Database, noteIds: string[]): Map<string, string[]> {
+  const map = new Map<string, string[]>();
+  if (noteIds.length === 0) return map;
+  const ids = [...new Set(noteIds)];
+  for (const id of ids) map.set(id, []);
+  for (let i = 0; i < ids.length; i += IN_CHUNK) {
+    const chunk = ids.slice(i, i + IN_CHUNK);
+    const placeholders = chunk.map(() => "?").join(", ");
+    const rows = db.prepare(
+      `SELECT note_id, tag_name FROM note_tags WHERE note_id IN (${placeholders}) ORDER BY tag_name`,
+    ).all(...chunk) as { note_id: string; tag_name: string }[];
+    for (const row of rows) map.get(row.note_id)!.push(row.tag_name);
+  }
+  return map;
 }
 
 /**
@@ -895,20 +980,19 @@ export function searchNotes(
 
   if (opts?.tags && opts.tags.length > 0) {
     try {
+      // Tag membership as a semijoin — same rationale as queryNotes: a
+      // `JOIN note_tags` multiplies rows for multi-tagged notes and forced
+      // DISTINCT over full rows. The FTS join itself is 1:1 on rowid.
       const tagPlaceholders = opts.tags.map(() => "?").join(", ");
       const rows = db.prepare(`
-        SELECT DISTINCT n.* FROM notes n
+        SELECT n.* FROM notes n
         JOIN notes_fts fts ON fts.rowid = n.rowid
-        JOIN note_tags nt ON nt.note_id = n.id AND nt.tag_name IN (${tagPlaceholders})
         WHERE notes_fts MATCH ?
+          AND n.id IN (SELECT note_id FROM note_tags WHERE tag_name IN (${tagPlaceholders}))
         ORDER BY rank
         LIMIT ?
-      `).all(...opts.tags, query, limit) as NoteRow[];
-      return rows.map((row) => {
-        const note = rowToNote(row);
-        note.tags = getNoteTags(db, note.id);
-        return note;
-      });
+      `).all(query, ...opts.tags, limit) as NoteRow[];
+      return notesWithTags(db, rows);
     } catch {
       return [];
     }
@@ -922,16 +1006,20 @@ export function searchNotes(
       ORDER BY rank
       LIMIT ?
     `).all(query, limit) as NoteRow[];
-    return rows.map((row) => {
-      const note = rowToNote(row);
-      note.tags = getNoteTags(db, note.id);
-      return note;
-    });
+    return notesWithTags(db, rows);
   } catch {
     return [];
   }
 }
 
+/** Map rows → Notes with tags hydrated in one batched query. */
+function notesWithTags(db: Database, rows: NoteRow[]): Note[] {
+  const notes = rows.map(rowToNote);
+  const tagsById = getNoteTagsForNotes(db, notes.map((n) => n.id));
+  for (const note of notes) note.tags = tagsById.get(note.id) ?? [];
+  return notes;
+}
+
 // ---- Tag Operations ----
 
 export function tagNote(db: Database, noteId: string, tags: string[]): void {