@openparachute/vault 0.7.6 → 0.7.7

package/core/src/lede.test.ts

@@ -72,6 +72,66 @@ describe("computeLede", () => {
     });
   });
 
+  describe("markdown blocks that are not prose (vault#616)", () => {
+    it("skips a fenced code block and returns the first prose paragraph after it", () => {
+      expect(
+        computeLede("# Title\n\n```js\nconst x = 1;\n```\n\nThe real lede."),
+      ).toBe("The real lede.");
+    });
+
+    it("skips a fenced block that is not blank-line separated from the title", () => {
+      expect(computeLede("# Title\n```\nraw\n```\n\nThe real lede.")).toBe("The real lede.");
+    });
+
+    it("skips a tilde-fenced code block", () => {
+      expect(computeLede("# Title\n\n~~~\nraw\n~~~\n\nThe real lede.")).toBe("The real lede.");
+    });
+
+    it("skips a fence whose body contains blank lines", () => {
+      expect(
+        computeLede("# Title\n\n```\nline one\n\nline two\n```\n\nThe real lede."),
+      ).toBe("The real lede.");
+    });
+
+    it("returns null when an unterminated fence runs to end of content", () => {
+      expect(computeLede("# Title\n\n```js\nconst x = 1;")).toBeNull();
+    });
+
+    it("returns null when a code fence is all the content after the title", () => {
+      expect(computeLede("# Title\n\n```js\nconst x = 1;\n```")).toBeNull();
+    });
+
+    it("skips a heading-only block rather than returning its raw marker", () => {
+      expect(computeLede("# Title\n\n## Section\n\nThe real lede.")).toBe("The real lede.");
+    });
+
+    it("skips consecutive headings and fences until it finds prose", () => {
+      expect(
+        computeLede("# Title\n\n## Section\n\n### Sub\n\n```\ncode\n```\n\nThe real lede."),
+      ).toBe("The real lede.");
+    });
+
+    it("returns null when only headings follow the title", () => {
+      expect(computeLede("# Title\n\n## Section\n\n### Sub")).toBeNull();
+    });
+
+    it("keeps a paragraph whose FIRST line is a heading-marked line but has prose under it", () => {
+      // A heading immediately followed by prose with no blank line: markdown
+      // ends the heading at the newline, so the prose is the lede.
+      expect(computeLede("# Title\n\n## Section\nThe real lede.")).toBe("The real lede.");
+    });
+
+    it("skips a setext underline / thematic break block under the title", () => {
+      expect(computeLede("Title\n---\n\nThe real lede.")).toBe("The real lede.");
+      expect(computeLede("# Title\n\n***\n\nThe real lede.")).toBe("The real lede.");
+      expect(computeLede("Title\n===\n\nThe real lede.")).toBe("The real lede.");
+    });
+
+    it("does not mistake a prose line for a thematic break", () => {
+      expect(computeLede("# Title\n\n--- and then some prose.")).toBe("--- and then some prose.");
+    });
+  });
+
   describe("length cap", () => {
     it("truncates to LEDE_MAX_LEN code points", () => {
       const longParagraph = "a".repeat(1000);

package/core/src/mcp-manifest.ts

@@ -51,7 +51,7 @@ export const MCP_TOOL_MANIFEST: readonly McpToolManifestEntry[] = [
       description: `Query notes. Returns notes matching the given filters.
 
 - **Single note**: pass \`id\` (accepts note ID, path, e.g., "Projects/README", or — as a last-resort fallback when id/path both miss cleanly and exactly one note matches — its H1 title, e.g. "Weekly Review")
-- **Filter**: pass \`tag\`, \`path\`, \`path_prefix\`, \`search\`, \`metadata\`, date range
+- **Filter**: pass \`tag\`, \`path\`, \`path_prefix\`, \`exclude_path_prefix\`, \`search\`, \`metadata\`, date range
 - **Graph neighborhood**: pass \`near\` to scope results to notes within N hops of an anchor note
 - **No filters**: returns all notes (paginated)
 
@@ -123,6 +123,20 @@ Response shape (vault#550 — three variants, pick by what you passed):
           has_broken_links: { type: "boolean", description: "Presence filter (vault#555): true = only notes with at least one dangling outbound link — a [[wikilink]] or structured `links` target that never resolved to a note; false = only notes with none. Backed by the unresolved_wikilinks table (same data `doctor`/list-unresolved surfaces); safe on a vault where no link has ever gone unresolved (true matches nothing, false is a no-op)." },
           path: { type: "string", description: "Exact path match (case-insensitive)" },
           path_prefix: { type: "string", description: "Path prefix match (e.g., 'Projects/')" },
+          exclude_path_prefix: {
+            oneOf: [
+              { type: "string" },
+              { type: "array", items: { type: "string" } },
+            ],
+            description: "Exclude notes whose path matches any of these prefixes (vault#628). Same matching as `path_prefix`. Repeatable. A note with no path is not excluded. First client: `.parachute/` system-space. Alias `excludePathPrefix` is also accepted.",
+          },
+          excludePathPrefix: {
+            oneOf: [
+              { type: "string" },
+              { type: "array", items: { type: "string" } },
+            ],
+            description: "Alias for `exclude_path_prefix` (camelCase).",
+          },
           extension: {
             oneOf: [
               { type: "string" },

package/core/src/mcp.ts

@@ -52,6 +52,7 @@ import {
   ATTACHMENT_MIME_TYPES,
   sanitizeAttachmentExtension,
   mimeForAttachmentExtension,
+  contentTypeForAttachmentPath,
 } from "./attachment/policy.js";
 import {
   computeTicketTtlMs,
@@ -818,6 +819,7 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
             hasBrokenLinks: params.has_broken_links as boolean | undefined,
             path: params.path as string | undefined,
             pathPrefix: params.path_prefix as string | undefined,
+            excludePathPrefix: normalizeTags(params.exclude_path_prefix ?? params.excludePathPrefix),
             extension: params.extension as string | string[] | undefined,
             metadata: params.metadata as Record<string, unknown> | undefined,
             createdBy: params.created_by as string | undefined,
@@ -939,6 +941,7 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
             hasBrokenLinks: params.has_broken_links as boolean | undefined,
             path: params.path as string | undefined,
             pathPrefix: params.path_prefix as string | undefined,
+            excludePathPrefix: normalizeTags(params.exclude_path_prefix ?? params.excludePathPrefix),
             extension: params.extension as string | string[] | undefined,
             // Same `near[]` neighborhood push-down `search`/structured-query
             // use — a semantic query can be scoped to a graph neighborhood too.
@@ -985,6 +988,8 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
           }
           // Normalize tag param
           const tags = normalizeTags(params.tag);
+          const excludeTagsRaw = params.exclude_tags ?? params.excludeTags ?? params.exclude_tag;
+          const excludeTags = normalizeTags(excludeTagsRaw);
           const mode: SearchMode = searchMode ?? "literal";
           // "Only whitespace/quotes" (vault#551 edge case): short-circuit
           // BEFORE ever calling FTS5 — an empty/all-punctuation phrase can
@@ -1004,10 +1009,35 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
             // `invalid_search_syntax`, vault#551) — uncaught on purpose, it
             // propagates to `src/mcp-http.ts`, which maps it to a JSON-RPC
             // error the same way it maps `invalid_query`.
+            // vault#647: forward the same QueryOpts the structured /
+            // semantic branches already pass. Pre-fix only tags/limit/
+            // expand/mode/sort reached searchNotes, so exclude_tags and
+            // date_from were silently dropped (a well-formed result set
+            // answering a different question).
             results = await store.searchNotes(params.search as string, {
               tags,
-              limit: (params.limit as number) ?? 50,
+              tagMatch: (params.tag_match as "all" | "any") ?? (tags && tags.length > 1 ? "any" : undefined),
               expand,
+              excludeTags,
+              hasTags: params.has_tags as boolean | undefined,
+              hasLinks: params.has_links as boolean | undefined,
+              hasBrokenLinks: params.has_broken_links as boolean | undefined,
+              path: params.path as string | undefined,
+              pathPrefix: params.path_prefix as string | undefined,
+              excludePathPrefix: normalizeTags(params.exclude_path_prefix ?? params.excludePathPrefix),
+              extension: params.extension as string | string[] | undefined,
+              ids: nearScope ? [...nearScope] : undefined,
+              metadata: params.metadata as Record<string, unknown> | undefined,
+              createdBy: params.created_by as string | undefined,
+              lastUpdatedBy: params.last_updated_by as string | undefined,
+              createdVia: params.created_via as string | undefined,
+              lastUpdatedVia: params.last_updated_via as string | undefined,
+              dateFrom: params.date_from as string | undefined,
+              dateTo: params.date_to as string | undefined,
+              dateFilter: params.date_filter as
+                | { field?: string; from?: string; to?: string }
+                | undefined,
+              limit: (params.limit as number) ?? 50,
               mode,
               sort: params.sort as "asc" | "desc" | undefined,
             });
@@ -1063,6 +1093,7 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
             hasBrokenLinks: params.has_broken_links as boolean | undefined,
             path: params.path as string | undefined,
             pathPrefix: params.path_prefix as string | undefined,
+            excludePathPrefix: normalizeTags(params.exclude_path_prefix ?? params.excludePathPrefix),
             extension: params.extension as string | string[] | undefined,
             // Push the near-scope into the SQL WHERE so that LIMIT and ORDER
             // BY apply to the neighborhood. Without this, queryNotes would
@@ -1103,8 +1134,8 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
             // requested, so `next_cursor` never surfaces as an honest
             // "more may follow" signal — this is that signal. Mirrors the
             // REST structured-query path in src/routes.ts.
-            if (results.length === queryOpts.limit) {
-              queryWarnings.push(truncatedResultsWarning(queryOpts.limit));
+            if (queryOpts.offset === undefined && results.length === queryOpts.limit) {
+              queryWarnings.push(truncatedResultsWarning(queryOpts.limit, "mcp"));
             }
           }
         }
@@ -2632,6 +2663,7 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
           const now = Date.now();
           const expiresAt = now + computeTicketTtlMs(declaredSize);
           const id = generateTicketId();
+          const downloadMime = contentTypeForAttachmentPath(attachment.path);
           const ticket: AttachmentTicket = {
             id,
             kind: "download",
@@ -2639,7 +2671,7 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
             createdAt: now,
             expiresAt,
             attachmentId: attachment.id,
-            mimeType: attachment.mimeType,
+            mimeType: downloadMime,
             sizeBytes: declaredSize,
           };
           await ticketSeam.provider.put(ticket);
@@ -2648,7 +2680,7 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
           return {
             method: "GET",
             url,
-            mime_type: attachment.mimeType,
+            mime_type: downloadMime,
             ...(declaredSize !== undefined ? { size_bytes: declaredSize } : {}),
             expires_at: new Date(expiresAt).toISOString(),
             curl_example: `curl -o downloaded${sanitizeAttachmentExtension(attachment.path) || ""} '${url}'`,

package/core/src/notes.ts

@@ -1102,6 +1102,18 @@ export function buildFilterConditions(db: Database, opts: QueryOpts): { conditio
     params.push(opts.pathPrefix + "%");
   }
 
+  // Path-prefix exclusion (vault#628). Mirrors `pathPrefix` matching
+  // (`LIKE prefix || '%'`, SQLite LIKE is ASCII-case-insensitive). NULL
+  // paths are kept — they are not under the prefix. Repeatable: a note
+  // matching ANY listed prefix is dropped.
+  if (opts.excludePathPrefix && opts.excludePathPrefix.length > 0) {
+    for (const prefix of opts.excludePathPrefix) {
+      if (typeof prefix !== "string" || prefix.length === 0) continue;
+      conditions.push("(n.path IS NULL OR n.path NOT LIKE ?)");
+      params.push(prefix + "%");
+    }
+  }
+
   // Extension filter (vault#328). Single string → exact match; array → IN
   // clause. Compared lower-case so a caller passing "CSV" still hits rows
   // stored as "csv". An empty array is a no-op (no filter applied) rather
@@ -1165,10 +1177,11 @@ export function buildFilterConditions(db: Database, opts: QueryOpts): { conditio
   if (opts.metadata) {
     for (const [key, value] of Object.entries(opts.metadata)) {
       if (isOperatorObject(value)) {
-        requireIndexedField(db, key);
+        const indexedField = requireIndexedField(db, key);
         const { sql, params: opParams } = buildOperatorClause(
           key,
           value as Record<string, unknown>,
+          indexedField.sqliteType,
         );
         conditions.push(sql);
         params.push(...opParams);
@@ -1656,6 +1669,7 @@ function toQueryHashInputs(opts: QueryOpts): QueryHashInputs {
     hasBrokenLinks: opts.hasBrokenLinks,
     path: opts.path,
     pathPrefix: opts.pathPrefix,
+    excludePathPrefix: opts.excludePathPrefix,
     extension: opts.extension,
     ids: opts.ids,
     metadata: opts.metadata,
@@ -1869,7 +1883,7 @@ function applySearchTitleBoost(
 export function searchNotes(
   db: Database,
   query: string,
-  opts?: { tags?: string[]; limit?: number; mode?: SearchMode; sort?: "asc" | "desc" },
+  opts?: QueryOpts & { mode?: SearchMode },
 ): Note[] {
   const limit = typeof opts?.limit === "number" ? opts.limit : 50;
   // Literal-by-default (vault#551): escape the caller's text so FTS5's own
@@ -1929,51 +1943,37 @@ export function searchNotes(
         ? "n.created_at DESC, n.id DESC"
         : "score DESC, n.id ASC";
 
-  if (opts?.tags && opts.tags.length > 0) {
-    // Canonical-bare-tag guard backstop (vault#XXX) for direct-core callers.
-    const searchTags = opts.tags.map(stripTagHash).filter((t) => t !== "");
-    if (searchTags.length === 0) {
-      // All tag filters collapsed to empty — fall through to the untagged
-      // search path below (no tag constraint).
-      opts = { ...opts, tags: undefined };
-    } else {
-    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 = searchTags.map(() => "?").join(", ");
-      const rows = db.prepare(`
-        SELECT n.*, ${scoreExpr} AS score FROM notes n
-        JOIN notes_fts fts ON fts.rowid = n.rowid
-        WHERE notes_fts MATCH ?
-          AND n.id IN (SELECT note_id FROM note_tags WHERE tag_name IN (${tagPlaceholders}))
-        ORDER BY ${orderBy}
-        LIMIT ?
-      `).all(ftsQuery, ...searchTags, limit) as (NoteRow & { score: number })[];
-      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
-      // mode should never reach it (escaping + control-char sanitization
-      // make the query valid) but if the invariant breaks we still want an
-      // honest error, not an unstructured 500. A QueryError we threw
-      // ourselves (empty-limit validation, etc.) is re-raised untouched.
-      if (err instanceof QueryError) throw err;
-      throw searchSyntaxError(query, err, mode);
-    }
-    }
-  }
+  // vault#647: compose FTS with the SAME filter builder queryNotes /
+  // semanticSearch use (excludeTags, dateFrom/dateFilter, path, metadata,
+  // …). Pre-fix only `tags` reached the WHERE clause; every other filter
+  // was silently dropped. Historical FTS tag semantics are "any tag
+  // matches" (a single IN (...)); preserve that when the caller didn't
+  // set `tagMatch`. LIMIT still applies AFTER the filters, not to an
+  // unfiltered FTS page.
+  const filterOpts: QueryOpts = {
+    ...(opts ?? {}),
+    tagMatch: opts?.tagMatch ?? (opts?.tags && opts.tags.length > 0 ? "any" : undefined),
+  };
+  const { conditions, params } = buildFilterConditions(db, filterOpts);
+  const extraWhere = conditions.length > 0 ? `AND ${conditions.join(" AND ")}` : "";
 
   try {
     const rows = db.prepare(`
       SELECT n.*, ${scoreExpr} AS score FROM notes n
       JOIN notes_fts fts ON fts.rowid = n.rowid
       WHERE notes_fts MATCH ?
+        ${extraWhere}
       ORDER BY ${orderBy}
       LIMIT ?
-    `).all(ftsQuery, limit) as (NoteRow & { score: number })[];
+    `).all(ftsQuery, ...params, limit) as (NoteRow & { score: number })[];
     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
+    // mode should never reach it (escaping + control-char sanitization
+    // make the query valid) but if the invariant breaks we still want an
+    // honest error, not an unstructured 500. A QueryError we threw
+    // ourselves (empty-limit validation, etc.) is re-raised untouched.
     if (err instanceof QueryError) throw err;
     throw searchSyntaxError(query, err, mode);
   }
@@ -2840,9 +2840,26 @@ export function computeDisplayTitle(content: string | null | undefined): string
 export const LEDE_MAX_LEN = 400;
 
 /**
- * Derive a note's "lede": the first non-empty PARAGRAPH after the title
+ * Opens (or closes) a fenced code block: three or more backticks or tildes.
+ * Capture 1 is the run itself so the scanner can require the CLOSING fence to
+ * use the same character and be at least as long, per CommonMark.
+ */
+const FENCE_OPEN_RE = /^(`{3,}|~{3,})/;
+/** A closing fence carries nothing but the run (an info string opens, never closes). */
+const FENCE_CLOSE_RE = /^(`{3,}|~{3,})\s*$/;
+/** An ATX heading line: 1-6 `#` followed by whitespace or end-of-line. */
+const HEADING_LINE_RE = /^#{1,6}(?:\s|$)/;
+/**
+ * A thematic break (`---`, `***`, `___`) or a setext heading underline
+ * (`---`, `===`). Both are pure markup with no text of their own — the
+ * setext case is why `Title\n---\n\nreal text` used to yield a `---` lede.
+ */
+const BREAK_LINE_RE = /^(?:-{3,}|\*{3,}|_{3,}|={3,})$/;
+
+/**
+ * Derive a note's "lede": the first non-empty PROSE PARAGRAPH after the title
  * line (a run of consecutive non-blank lines, whitespace-collapsed to one
- * line, truncated to `LEDE_MAX_LEN` code points). `null` when there's no
+ * line, truncated to `LEDE_MAX_LEN` code points). `null` when there's no such
  * paragraph after the title — a title-only note has no lede to report, and
  * callers must not fall back to repeating the title itself.
  *
@@ -2854,6 +2871,22 @@ export const LEDE_MAX_LEN = 400;
  * what it finds, honestly, using the SAME title-line rule as
  * `computeDisplayTitle` (including its frontmatter skip) so a caller that
  * shows both title and lede sees them agree on where the title ends.
+ *
+ * Non-prose blocks are SKIPPED (vault#616). A note that opens with a code
+ * fence, a section heading, or a horizontal rule used to have that raw markup
+ * returned as its lede — backticks, `## ` markers and all — which contradicted
+ * this function's own "first paragraph" contract and read as garbage in
+ * `expand_mode: "summary"`. The scan now walks past fenced blocks (to the
+ * matching closing fence, or to end-of-content when the fence is never
+ * closed), heading lines, and break/underline lines until it reaches real
+ * text, and returns `null` if it never does. Those same three shapes also
+ * TERMINATE a paragraph already in progress, matching how markdown lets a
+ * fence or heading interrupt a paragraph.
+ *
+ * Deliberately NOT normalized: list blocks. A `- milk` list is genuine prose
+ * content, and how to flatten it into one line (drop the markers? join with
+ * what?) is a rendering decision this function shouldn't make silently — it
+ * reports the list as written.
  */
 export function computeLede(content: string | null | undefined): string | null {
   if (!content) return null;
@@ -2870,14 +2903,51 @@ export function computeLede(content: string | null | undefined): string | null {
   if (titleLine === -1) return null; // no title at all — nothing to find a lede after
 
   let i = titleLine + 1;
-  while (i < lines.length && lines[i]!.trim() === "") i++; // skip blank lines after the title
-
   const paragraphLines: string[] = [];
-  while (i < lines.length && lines[i]!.trim() !== "") {
-    paragraphLines.push(lines[i]!);
-    i++;
+
+  // Walk blocks until one of them is prose. Each iteration consumes exactly
+  // one block (blank run, fence, heading, break, or paragraph), so `i` always
+  // advances and the loop terminates.
+  scan: while (i < lines.length) {
+    const trimmed = lines[i]!.trim();
+
+    if (trimmed === "") {
+      i++;
+      continue;
+    }
+
+    const opening = FENCE_OPEN_RE.exec(trimmed);
+    if (opening) {
+      const marker = opening[1]!;
+      i++;
+      while (i < lines.length) {
+        const closing = FENCE_CLOSE_RE.exec(lines[i]!.trim());
+        i++;
+        if (closing && closing[1]![0] === marker[0] && closing[1]!.length >= marker.length) break;
+      }
+      continue; // an unclosed fence runs off the end and leaves i past the last line
+    }
+
+    if (HEADING_LINE_RE.test(trimmed) || BREAK_LINE_RE.test(trimmed)) {
+      i++;
+      continue;
+    }
+
+    // Real text — gather the paragraph, stopping at a blank line or at any
+    // block-level marker that interrupts it.
+    while (i < lines.length) {
+      const line = lines[i]!;
+      const t = line.trim();
+      if (t === "" || FENCE_OPEN_RE.test(t) || HEADING_LINE_RE.test(t) || BREAK_LINE_RE.test(t)) {
+        break scan;
+      }
+      paragraphLines.push(line);
+      i++;
+    }
+    break;
   }
-  if (paragraphLines.length === 0) return null; // title-only note
+
+  if (paragraphLines.length === 0) return null; // title-only note, or nothing but markup
 
   const paragraph = paragraphLines.join(" ").replace(/\s+/g, " ").trim();
   if (paragraph === "") return null;
@@ -2938,8 +3008,10 @@ export function toNoteIndex(note: Note): NoteIndex {
 /**
  * Filter metadata on a note/index result based on an include_metadata param.
  * - true / undefined → return as-is (all metadata)
- * - false → strip metadata entirely
- * - string[] → return only those keys (empty array = no filtering)
+ * - false → strip metadata entirely (key omitted — caller asked for none)
+ * - string[] → return only those keys. Empty array = no filtering (all keys).
+ *   A non-empty array whose keys miss still keeps `metadata: {}` (vault#600
+ *   V1.1 invariant — the key must not vanish from the wire).
  */
 export function filterMetadata(obj: any, includeMetadata: boolean | string[] | undefined): any {
   if (includeMetadata === undefined || includeMetadata === true) return obj;
@@ -2953,7 +3025,7 @@ export function filterMetadata(obj: any, includeMetadata: boolean | string[] | u
   const filtered = Object.fromEntries(
     Object.entries(obj.metadata).filter(([k]) => fields.includes(k)),
   );
-  return { ...obj, metadata: Object.keys(filtered).length > 0 ? filtered : undefined };
+  return { ...obj, metadata: filtered };
 }
 
 /**

package/core/src/query-operators.ts

@@ -16,7 +16,8 @@
  */
 
 import { Database, type SQLQueryBindings } from "bun:sqlite";
-import { getIndexedField, type IndexedField } from "./indexed-fields.js";
+import { getIndexedField, type IndexedField, type SqliteType } from "./indexed-fields.js";
+import { inViaJsonEachCast, jsonEachParam } from "./sql-in.js";
 
 export const SUPPORTED_OPS = [
   "eq",
@@ -101,6 +102,52 @@ function toBinding(field: string, op: string, value: unknown): SQLQueryBindings
   );
 }
 
+/**
+ * Narrow one `in`/`not_in` element to something `JSON.stringify` can carry
+ * into {@link jsonEachParam} (vault#536).
+ *
+ * Runs `toBinding` first so the primitive-only validation and its error
+ * message are unchanged from the one-param-per-value era. Then two shapes
+ * need explicit handling, because JSON has no equivalent of what bun:sqlite
+ * did implicitly when the value was bound directly:
+ *
+ * - `boolean` → `1`/`0`, matching the INTEGER a boolean is stored as, so
+ *   `{ in: [true] }` still matches rows written with `true`. A raw JSON
+ *   `true` would come out of `json_each` as `1` anyway on current SQLite,
+ *   but converting here makes the intent explicit rather than dependent on
+ *   that.
+ * - `bigint` → `JSON.stringify` THROWS on it ("Do not know how to serialize
+ *   a BigInt"). Converted when it fits exactly in a double; otherwise
+ *   rejected with a real error instead of a crash or a silently wrong
+ *   comparison. (Unreachable from MCP/REST — `JSON.parse` never yields a
+ *   bigint — so this only guards a direct in-process caller.)
+ */
+function toJsonEachMember(
+  field: string,
+  op: string,
+  value: unknown,
+): string | number | boolean | null {
+  const bound = toBinding(field, op, value);
+  if (typeof bound === "boolean") return bound ? 1 : 0;
+  if (typeof bound === "bigint") {
+    if (bound >= BigInt(Number.MIN_SAFE_INTEGER) && bound <= BigInt(Number.MAX_SAFE_INTEGER)) {
+      return Number(bound);
+    }
+    throw new QueryError(
+      `operator "${op}" on metadata field "${field}" got a bigint outside the safe integer range (${bound}); it cannot be compared exactly`,
+      "INVALID_OPERATOR_VALUE",
+    );
+  }
+  // `toBinding` is declared as the full `SQLQueryBindings` union (which
+  // includes TypedArray/Record shapes it never actually returns), so narrow
+  // to what JSON can carry rather than asserting.
+  if (bound === null || typeof bound === "string" || typeof bound === "number") return bound;
+  throw new QueryError(
+    `operator "${op}" on metadata field "${field}" expects a primitive value (string, number, boolean, bigint, or null)`,
+    "INVALID_OPERATOR_VALUE",
+  );
+}
+
 /**
  * Best-effort lookup of a metadata field's declared `type` across every tag
  * schema — used ONLY to sharpen the {@link requireIndexedField} error hint
@@ -176,10 +223,19 @@ export function requireIndexedField(db: Database, field: string): IndexedField {
  * Build a SQL fragment + bound params for an operator object on an indexed
  * metadata field. Each operator maps to a single AND clause; an object like
  * `{ gt: 5, lt: 10 }` composes as `meta_<field> > 5 AND meta_<field> < 10`.
+ *
+ * `sqliteType` is the field's declared column storage type (from
+ * `requireIndexedField(...).sqliteType`, which every caller already
+ * resolves). It's needed for `in`/`not_in`: those bind the value-set through
+ * a `json_each` subquery, which — unlike a placeholder `IN (?, …)` list —
+ * does NOT apply the left column's type affinity to each candidate value, so
+ * the set must be CAST to the column's type to keep cross-type matches like
+ * numeric `5` against a TEXT-affinity `'5'` (vault#676).
  */
 export function buildOperatorClause(
   field: string,
   opObj: Record<string, unknown>,
+  sqliteType: SqliteType,
 ): { sql: string; params: SQLQueryBindings[] } {
   validateOperatorObject(field, opObj);
   // `field` came from indexed_fields (which validated it via FIELD_NAME_RE
@@ -235,13 +291,39 @@ export function buildOperatorClause(
           parts.push(op === "in" ? "0" : "1");
           break;
         }
-        const placeholders = value.map(() => "?").join(", ");
+        // ONE bound param for the whole set, regardless of its size
+        // (vault#536). This used to emit `IN (?, ?, …)` — one param per
+        // value — which on Cloudflare Durable Object SQLite (100 bound
+        // params per statement, vs bun:sqlite's 999+) turned any `in` array
+        // over ~100 elements into a `too many SQL variables` 500 on cloud
+        // vaults, while self-host never noticed.
+        //
+        // This is an EMBEDDED filter inside a paginated statement, so the
+        // chunk-and-union approach used for standalone id-lists isn't
+        // available — chunking would break the shared LIMIT/OFFSET window.
+        // The json_each shape #535 introduced for the `near` neighborhood is
+        // the one that works here: bind the array as a single JSON param and
+        // let SQLite expand it into a one-column table. See sql-in.ts.
+        //
+        // Every element still goes through `toBinding`, so the same
+        // primitive-only validation (and the same error message) applies as
+        // before — the values are just serialized into JSON instead of bound
+        // one by one.
+        //
+        // The set is CAST to the column's declared storage type inside the
+        // subquery (`inViaJsonEachCast`). A placeholder `IN (?, …)` list got
+        // the left column's affinity applied to each value for free; a
+        // `json_each` subquery does not, so without the CAST a numeric `5`
+        // silently stopped matching a TEXT-affinity `'5'` (vault#676). The
+        // CAST restores that in both directions and covers `in` and `not_in`.
+        const members = value.map((v) => toJsonEachMember(field, op, v));
+        const inClause = inViaJsonEachCast(sqliteType);
         if (op === "in") {
-          parts.push(`${col} IN (${placeholders})`);
+          parts.push(`${col} IN ${inClause}`);
         } else {
-          parts.push(`(${col} IS NULL OR ${col} NOT IN (${placeholders}))`);
+          parts.push(`(${col} IS NULL OR ${col} NOT IN ${inClause})`);
         }
-        for (const v of value) params.push(toBinding(field, op, v));
+        params.push(jsonEachParam(members));
         break;
       }
       case "exists":

package/core/src/query-warnings.ts

@@ -229,12 +229,20 @@ export function ignoredParamWarning(param: string, reason: string): QueryWarning
  * /api/notes` on a >limit-note vault returns the OLDEST rows with zero
  * signal that the NEWEST ones didn't make it. `?cursor=` (bootstrap or
  * watermark) sidesteps this entirely — the warning only fires in its
- * absence.
+ * absence. Explicit `offset` is also exempt (vault#601): offset-paging is
+ * deliberate pagination, not an accidental full default page.
  */
-export function truncatedResultsWarning(limit: number): QueryWarning {
+export function truncatedResultsWarning(
+  limit: number,
+  channel: "rest" | "mcp" = "rest",
+): QueryWarning {
+  const pageHint =
+    channel === "mcp"
+      ? `Pass cursor: "" to page, or sort: "desc" for newest-first.`
+      : "Pass ?cursor= to page, or sort=desc for newest-first.";
   return {
     code: "truncated",
-    message: `${limit} = limit rows returned; there may be more. Pass ?cursor= to page, or sort=desc for newest-first.`,
+    message: `${limit} = limit rows returned; there may be more. ${pageHint}`,
     limit,
   };
 }