@cerefox/memory 1.14.1 → 1.14.3

package/dist/server-assets/_shared/mcp-tools/search.ts

@@ -18,12 +18,162 @@
 import type { MCPSupabaseClient } from "./types.ts";
 
 import { getEmbedding, resolveEmbedderKind } from "../embeddings/index.ts";
-import { applyByteBudget, getConfiguredMinSearchScore, getConfiguredSearchAlpha,
+import { getConfiguredMinSearchScore, getConfiguredSearchAlpha,
   getMaxResponseBytes, getMinTermCoverage, logUsage } from "./_utils.ts";
 import { lookupProjectId } from "./_projects.ts";
 import { McpInvalidParams, type ToolContext, type ToolDefinition } from "./types.ts";
 import { AUTHOR_PARAM_READ, callerIdentity } from "./identity.ts";
 
+interface SearchRow {
+  document_id?: string;
+  doc_title?: string;
+  /** Document-level modes (`docs`) return this… */
+  full_content?: string;
+  /** …while `hybrid` and `fts` return the chunk text under this name. */
+  content?: string;
+  /** Chunk-mode identity: the RPCs return several chunks OF THE SAME document. */
+  chunk_id?: string;
+  chunk_index?: number;
+  /** The chunk's own heading, and its full path from the document root. */
+  title?: string;
+  heading_path?: string[];
+  best_score?: number;
+  score?: number;
+  is_partial?: boolean;
+  chunk_count?: number;
+  total_chars?: number;
+  content_hash?: string;
+  below_confidence?: boolean;
+}
+
+/** The row's text, under whichever column name this search mode returns. */
+export function rowContent(row: SearchRow): string {
+  return row.full_content ?? row.content ?? "";
+}
+
+/**
+ * `Document Title › Section` for a chunk row, `Document Title` for a document
+ * row, plus the ids that identify it.
+ *
+ * The chunk RPCs return several chunks OF THE SAME document, so without the
+ * section and the index those results are indistinguishable (#261). Shared by
+ * the rendered path and the degraded one, where identical headings would be
+ * the entire answer.
+ */
+function rowHeading(row: SearchRow): string {
+  const doc = row.doc_title ?? "Untitled";
+  // `heading_path` normally opens with the document's own H1, so the FIRST
+  // element is dropped when it repeats the title. Only the first: a section
+  // legitimately named after the document must still appear (#261).
+  const path = [...(row.heading_path ?? [])];
+  if (path.length > 0 && path[0] === doc) path.shift();
+  const section = path.length
+    ? path.filter(Boolean).join(" › ")
+    : row.title && row.title !== doc
+      ? row.title
+      : "";
+  const docId = row.document_id ? ` [id: ${row.document_id}]` : "";
+  const chunk = row.chunk_index != null ? ` (chunk ${row.chunk_index})` : "";
+  return `${doc}${section ? ` › ${section}` : ""}${docId}${chunk}`;
+}
+
+/**
+ * A short label for a row in the truncation footer: the leaf section, the
+ * chunk index, and the document id.
+ *
+ * Shorter than the rendered heading, which carries the whole breadcrumb — the
+ * footer names up to five rows, and full headings pushed the reply over the
+ * budget it was reporting on (#263). The id stays, because chunk modes span
+ * documents too and two documents sharing a title and a section name are
+ * otherwise indistinguishable, with no way to fetch either (#265). The footer
+ * is inside the budget and drops names it cannot afford, so it is accounted
+ * for either way.
+ */
+function shortLabel(row: SearchRow): string {
+  const doc = row.doc_title ?? "Untitled";
+  const path = [...(row.heading_path ?? [])];
+  if (path.length > 0 && path[0] === doc) path.shift();
+  const leaf = path.filter(Boolean).at(-1) ?? (row.title && row.title !== doc ? row.title : "");
+  const chunk = row.chunk_index != null ? ` (chunk ${row.chunk_index})` : "";
+  // Always the id. Chunk modes are not single-document either, so two
+  // documents sharing a title and a section name would otherwise produce
+  // byte-identical entries with no way to fetch either (#265). The footer is
+  // inside the budget now and drops names it cannot afford, so carrying the
+  // id costs nothing that is not accounted for.
+  const id = row.document_id ? ` [id: ${row.document_id}]` : "";
+  return `${leaf ? `${doc} › ${leaf}` : doc}${chunk}${id}`;
+}
+
+/** One rendered result: heading, score, then the row's text. */
+function renderRow(row: SearchRow): string {
+  const raw = row.best_score ?? row.score;
+  const score = raw != null ? ` (score: ${raw.toFixed(3)})` : "";
+  const partial = row.is_partial
+    ? ` -- partial (${row.chunk_count} of ${(row.total_chars ?? 0).toLocaleString()} chars)`
+    : "";
+  // content_hash = the concurrency token for cerefox_ingest updates (iter-32).
+  const hash = row.content_hash ? `\nhash: ${row.content_hash}` : "";
+  // Whichever column this mode returns (#259): `cerefox_search_docs` gives
+  // `full_content`, the chunk RPCs give `content`, and reading only the first
+  // rendered every hybrid/fts result as a title with an empty body.
+  return `## ${rowHeading(row)}${score}${partial}${hash}\n\n${rowContent(row)}`;
+}
+
+/** `## Title [id: …] (score: …) -- 20,297 chars` — everything but the content. */
+function headerLine(row: SearchRow): string {
+  const raw = row.best_score ?? row.score;
+  const score = raw != null ? ` (score: ${raw.toFixed(3)})` : "";
+  const size = row.total_chars != null ? ` -- ${row.total_chars.toLocaleString()} chars` : "";
+  const hash = row.content_hash ? `\nhash: ${row.content_hash}` : "";
+  return `## ${rowHeading(row)}${score}${size}${hash}`;
+}
+
+/**
+ * What to say when results matched but none fit `max_bytes` (#254).
+ *
+ * Never "no results": that is the one answer an agent acts on irreversibly.
+ * The headers are listed while they fit the same budget, so the response
+ * still honours the limit the caller asked for; if even one header does not
+ * fit, the count and the remedy alone still beat silence.
+ */
+function degradedToHeaders(
+  matched: SearchRow[],
+  rendered: string[],
+  maxBytes: number,
+  belowConfidence: boolean,
+): string {
+  // Rendered bytes, not JSON: the fit decision that reaches here is made in
+  // rendered bytes, and quoting a JSON size produced messages saying the
+  // largest result was 490 bytes and did not fit a 600-byte budget (#265).
+  // Sizes come from the render the caller already paid for — re-rendering
+  // whole documents here just to measure them tripled peak memory.
+  const biggest = Math.max(...rendered.map((t) => new TextEncoder().encode(t).length));
+  // A degraded response must not silently promote 28I's weak-signal
+  // candidates into real matches: an agent told "N result(s) matched" about
+  // rows that cleared no threshold would trust them.
+  const confidence = belowConfidence
+    ? "None of these cleared the confidence threshold — they are the closest " +
+      "candidates, so judge relevance from the scores. "
+    : "";
+  const lead =
+    `⚠ ${matched.length} result(s) matched, but none fit max_bytes=${maxBytes} ` +
+    `(the largest is ${biggest.toLocaleString()} bytes). ${confidence}This is NOT an ` +
+    `empty knowledge base. Listing what matched, without content — raise max_bytes ` +
+    `to read it, or read one document with cerefox_get_document (outline: true for ` +
+    `structure, or section: "## Heading" for one part).`;
+
+  const lines: string[] = [];
+  let used = new TextEncoder().encode(lead).length;
+  for (const row of matched) {
+    const line = headerLine(row);
+    const size = new TextEncoder().encode(line).length + 2;
+    if (used + size > maxBytes) break;
+    lines.push(line);
+    used += size;
+  }
+  return lines.length > 0 ? `${lead}\n\n${lines.join("\n\n")}` : lead;
+}
+
 async function handler(
   supabase: MCPSupabaseClient,
   args: Record<string, unknown>,
@@ -31,7 +181,12 @@ async function handler(
 ): Promise<string> {
   const query = args.query as string;
   const project_name = args.project_name as string | undefined;
-  const match_count = (args.match_count as number | undefined) ?? 5;
+  // Sanitised, then clamped, exactly as the Edge Function does it. Clamping
+  // alone left `NaN` for a non-numeric value, which serialises to JSON null,
+  // and `LIMIT NULL` in Postgres means NO limit — the unbounded work the
+  // clamp exists to prevent, reachable because the local MCP server passes
+  // tool arguments through unvalidated (#265).
+  const match_count = Math.min(Math.max(1, Math.floor(Number(args.match_count)) || 5), 200);
   const mode = (args.mode as string | undefined) ?? "docs";
   // #133: omit unconfigured tunables so the server resolves them from
   // cerefox_config (one setting governs every access path).
@@ -52,7 +207,18 @@ async function handler(
   const requested_max_bytes = args.max_bytes as number | undefined;
 
   const ceiling = getMaxResponseBytes();
-  const max_bytes = Math.min(requested_max_bytes ?? ceiling, ceiling);
+  // Sanitised before clamping, for the reason `match_count` is: `NaN` makes
+  // every `> max_bytes` comparison below false, so a non-numeric value emitted
+  // every row unbounded — the ceiling bypassed by passing it a word (#266).
+  // A NUMBER of 0 or less still means "almost no budget", as it always did:
+  // falling back to the ceiling there would hand a caller whose remaining
+  // allowance ran out the largest possible reply (#267). Only a missing or
+  // non-numeric value defaults to the ceiling.
+  const requestedBytes = Math.floor(Number(requested_max_bytes));
+  const max_bytes = Math.min(
+    Number.isFinite(requestedBytes) ? Math.max(requestedBytes, 1) : ceiling,
+    ceiling,
+  );
 
   if (
     metadata_filter !== null &&
@@ -131,7 +297,138 @@ async function handler(
 
   if (error) throw new Error(`RPC error: ${error.message}`);
 
-  const { accepted, truncated, usedBytes } = applyByteBudget(data ?? [], max_bytes);
+  const matched = (data ?? []) as SearchRow[];
+
+  // 28I: nothing cleared the relevance threshold, so the server returned its
+  // best-effort candidates flagged below_confidence rather than an empty set
+  // (which agents misread as "this knowledge does not exist"). The flag is
+  // all-or-nothing per response, so it is read from what MATCHED.
+  const belowConfidence = matched.length > 0 && matched.every((r) => r.below_confidence === true);
+
+  if (matched.length === 0) {
+    logUsage(supabase, {
+      operation: "search",
+      accessPath: ctx.accessPath,
+      requestor: callerIdentity(args),
+      query_text: query,
+      project_id: projectId,
+      result_count: 0,
+    });
+    return "No results found.";
+  }
+
+  // ── Fit the reply to max_bytes, in the units the caller receives ──────────
+  //
+  // The budget is spent on RENDERED text, not on the JSON the RPC returned:
+  // `applyByteBudget` measures `JSON.stringify(row)`, which is the right unit
+  // for the Edge Function (it ships JSON) and the wrong one here (this returns
+  // markdown). Reserving rendered bytes out of a JSON-measured budget
+  // guaranteed nothing, and neither the below-confidence preamble (~185 bytes)
+  // nor the footer was counted by anything (#265).
+  //
+  // So: render, then take as many rows as the whole assembled reply can carry.
+  // Assembling and measuring is the only way to be sure, because the preamble
+  // and the footer both depend on how many rows were kept.
+  const rendered = matched.map(renderRow);
+  const size = (t: string) => new TextEncoder().encode(t).length;
+  const SEP = "\n\n---\n\n";
+
+  // The 28I advisory, long and short. It is charged to the budget like
+  // everything else, but it must never displace the answer it is advising
+  // about: a ~190-byte banner that pushes the only result out of a small reply
+  // leaves the caller with a warning and no content (#265). The short form is
+  // the floor — the contract is that weak candidates are never presented as
+  // confident ones, and that survives in six words.
+  const banner = (take: number, short: boolean) =>
+    !belowConfidence
+      ? ""
+      : short
+        ? `⚠ Below the confidence threshold — judge relevance from the scores.\n\n`
+        : `⚠ No results cleared the confidence threshold. Showing the closest ${take} ` +
+          `candidate(s) with scores — judge relevance yourself; a low score means weak ` +
+          `signal, not necessarily absent knowledge.\n\n`;
+
+  /**
+   * The whole reply for a set of kept rows.
+   *
+   * Everything but the results is optional, in this order: the long advisory
+   * gives way first, then the named list of what was dropped, then the bare
+   * footer. What is NOT optional is saying that results were dropped — a
+   * reply that quietly returns 1 of 5 hits leaves the caller believing they
+   * saw everything, which is the failure this whole file is about (#266).
+   */
+  const assemble = (keptCount: number, short: boolean): string => {
+    const kept = keptIdx.slice(0, keptCount);
+    const body = banner(keptCount, short) + kept.map((i) => rendered[i]!).join(SEP);
+    if (kept.length === matched.length) return body;
+
+    const droppedRows = matched.filter((_, i) => !kept.includes(i));
+    const room = max_bytes - size(body);
+    const footer = (named: number) => {
+      const labels = droppedRows.slice(0, named).map(shortLabel);
+      const rest = droppedRows.length - labels.length;
+      const naming = labels.length
+        ? `: ${labels.join(", ")}${rest > 0 ? ` and ${rest} more` : ""}`
+        : "";
+      return (
+        `\n\n[${kept.length} of ${matched.length} result(s) shown; ${droppedRows.length} did ` +
+        `not fit max_bytes=${max_bytes}${naming}. Raise max_bytes, narrow the query, or ` +
+        `lower match_count.]`
+      );
+    };
+    for (let named = Math.min(5, droppedRows.length); named >= 1; named--) {
+      const candidate = footer(named);
+      if (size(candidate) <= room) return body + candidate;
+    }
+    const bare = footer(0);
+    if (size(bare) <= room) return body + bare;
+    // The floor, ~25 bytes, never dropped: the caller must know there is more.
+    return body + `\n\n[${kept.length} of ${matched.length} shown; raise max_bytes]`;
+  };
+
+  // Which rows the budget can carry, in rank order. Rows that do not fit are
+  // SKIPPED rather than ending the scan: one oversized top hit used to suppress
+  // every smaller result behind it, and the reply then claimed nothing fit when
+  // rows two and three would have fitted comfortably (#266).
+  const sepBytes = size(SEP);
+  const keptIdx: number[] = [];
+  let acc = 0;
+  for (let i = 0; i < rendered.length; i++) {
+    const add = size(rendered[i]!) + (keptIdx.length > 0 ? sepBytes : 0);
+    if (acc + add > max_bytes) continue;
+    acc += add;
+    keptIdx.push(i);
+  }
+
+  // Not one result fits (#254) — the only case that answers with no content,
+  // and now the only case that can truthfully say so.
+  if (keptIdx.length === 0) {
+    logUsage(supabase, {
+      operation: "search",
+      accessPath: ctx.accessPath,
+      requestor: callerIdentity(args),
+      query_text: query,
+      project_id: projectId,
+      result_count: matched.length,
+      extra: { returned: 0, truncated: true, degraded: true },
+    });
+    return degradedToHeaders(matched, rendered, max_bytes, belowConfidence);
+  }
+
+  // Give up the framing before the content, but never the fact of truncation:
+  // long advisory, then a result, and the "N of M shown" notice always stays.
+  let keptCount = keptIdx.length;
+  let short = false;
+  let output = assemble(keptCount, short);
+  while (size(output) > max_bytes) {
+    if (belowConfidence && !short) short = true;
+    else if (keptCount > 1) {
+      keptCount -= 1;
+      short = belowConfidence;
+    } else break; // one result plus the shortest possible framing: the floor
+    output = assemble(keptCount, short);
+  }
+  const take = keptCount;
 
   logUsage(supabase, {
     operation: "search",
@@ -139,53 +436,12 @@ async function handler(
     requestor: callerIdentity(args),
     query_text: query,
     project_id: projectId,
-    result_count: accepted.length,
-  });
-
-  if (accepted.length === 0) return "No results found.";
-
-  const rows = accepted as Array<{
-    document_id?: string;
-    doc_title?: string;
-    full_content?: string;
-    best_score?: number;
-    score?: number;
-    is_partial?: boolean;
-    chunk_count?: number;
-    total_chars?: number;
-    content_hash?: string;
-    below_confidence?: boolean;
-  }>;
-
-  // 28I: nothing cleared the relevance threshold, so the server returned its
-  // best-effort top candidates flagged below_confidence instead of an empty
-  // set (which agents misread as "this knowledge does not exist").
-  const belowConfidence = rows.length > 0 && rows.every((r) => r.below_confidence === true);
-
-  const parts: string[] = rows.map((row) => {
-    const title = row.doc_title ?? "Untitled";
-    const docId = row.document_id ? ` [id: ${row.document_id}]` : "";
-    const rawScore = row.best_score ?? row.score;
-    const score = rawScore != null ? ` (score: ${rawScore.toFixed(3)})` : "";
-    const partial = row.is_partial
-      ? ` -- partial (${row.chunk_count} of ${(row.total_chars ?? 0).toLocaleString()} chars)`
-      : "";
-    // content_hash = the concurrency token for cerefox_ingest updates (iter-32).
-    const hash = row.content_hash ? `\nhash: ${row.content_hash}` : "";
-    return `## ${title}${docId}${score}${partial}${hash}\n\n${row.full_content ?? ""}`;
+    // What the QUERY matched, not what survived the budget: recording the
+    // latter made a budget-wiped search look like an empty store in analytics.
+    result_count: matched.length,
+    ...(take < matched.length ? { extra: { returned: take, truncated: true } } : {}),
   });
 
-  let output = parts.join("\n\n---\n\n");
-  if (belowConfidence) {
-    output =
-      `⚠ No results cleared the confidence threshold. Showing the closest ${rows.length} ` +
-      `candidate(s) with scores — judge relevance yourself; a low score means weak signal, ` +
-      `not necessarily absent knowledge.\n\n` + output;
-  }
-  if (truncated) {
-    output +=
-      `\n\n[Results truncated at ${usedBytes} bytes. Use a more specific query or a smaller match_count to see more.]`;
-  }
   return output;
 }
 
@@ -207,7 +463,7 @@ export const searchTool: ToolDefinition = {
       query: { type: "string", description: "Natural-language search query" },
       match_count: {
         type: "integer",
-        description: "Maximum number of documents to return (default: 5)",
+        description: "Maximum number of documents to return (default: 5, maximum: 200)",
       },
       project_name: {
         type: "string",

package/dist/server-assets/supabase/functions/cerefox-search/index.ts

@@ -4,6 +4,8 @@ import { isVersionRequest, versionResponse } from "../../../_shared/ef-meta/inde
 import { efAuthGate } from "../../../_shared/ef-auth/index.ts";
 import { callerIdentity } from "../../../_shared/mcp-tools/identity.ts";
 import { capEmbeddingInput } from "../../../_shared/embeddings/index.ts";
+// One implementation of the byte budget, shared with the MCP tools (#254).
+import { applyByteBudget } from "../../../_shared/mcp-tools/_utils.ts";
 
 /**
  * cerefox-search — Supabase Edge Function
@@ -34,7 +36,16 @@ import { capEmbeddingInput } from "../../../_shared/embeddings/index.ts";
  *                                      `truncated` flag when results were dropped.
  *
  * Response: { results: [...], query, mode, match_count, project_name?,
- *             truncated: boolean, response_bytes: number }
+ *             truncated: boolean, response_bytes: number,
+ *             matched: number, degraded: boolean, note?: string }
+ *
+ * `matched` is how many results the query found, before the byte budget.
+ * `degraded` is true when everything that matched was larger than max_bytes:
+ * the items then carry NO content, they name what exists so the caller can
+ * re-ask with a larger budget. That header list is capped to max_bytes and so
+ * may be a SUBSET of `matched`, except that one item is always returned even
+ * if it exceeds the budget — an empty `results` would read as "nothing was
+ * found", which is `matched: 0` and nothing else (#254, #257, #261).
  *
  * Example agent prompt:
  *   "Invoke the cerefox-search edge function with query='knowledge management'
@@ -148,35 +159,6 @@ async function lookupProjectId(
   return data[0].id;
 }
 
-/**
- * Apply a byte budget to an array of result rows.
- *
- * Each row is serialised to JSON to measure its size. Rows are included in
- * order until the next row would push the running total over `maxBytes`.
- * Rows are always kept or dropped whole — content is never truncated
- * mid-document. Returns the accepted rows and a `truncated` flag.
- */
-function applyByteBudget(
-  rows: unknown[],
-  maxBytes: number,
-): { accepted: unknown[]; truncated: boolean; usedBytes: number } {
-  const accepted: unknown[] = [];
-  let usedBytes = 0;
-  let truncated = false;
-
-  for (const row of rows) {
-    const rowBytes = new TextEncoder().encode(JSON.stringify(row)).length;
-    if (usedBytes + rowBytes > maxBytes) {
-      truncated = true;
-      break;
-    }
-    accepted.push(row);
-    usedBytes += rowBytes;
-  }
-
-  return { accepted, truncated, usedBytes };
-}
-
 const headers = {
   "Content-Type": "application/json",
   "Access-Control-Allow-Origin": "*",
@@ -233,7 +215,15 @@ Deno.serve(async (req: Request) => {
   } = body;
 
   // Enforce ceiling: agents may request less but never more than MAX_BYTES.
-  const max_bytes = Math.min(requested_max_bytes ?? MAX_BYTES, MAX_BYTES);
+  // Sanitised before clamping: `NaN` compares false against every budget
+  // check, so a non-numeric value bypassed the ceiling entirely (#266).
+  // A number of 0 or less still means "almost no budget"; only a missing or
+  // non-numeric value falls back to the ceiling (#267).
+  const requestedBytes = Math.floor(Number(requested_max_bytes));
+  const max_bytes = Math.min(
+    Number.isFinite(requestedBytes) ? Math.max(requestedBytes, 1) : MAX_BYTES,
+    MAX_BYTES,
+  );
   // Clamp match_count to [1, MAX_MATCH_COUNT] (bounds query work; see MAX_MATCH_COUNT).
   const match_count = Math.min(Math.max(1, Math.floor(Number(raw_match_count)) || 5), MAX_MATCH_COUNT);
 
@@ -374,7 +364,40 @@ Deno.serve(async (req: Request) => {
 
   // Apply byte budget — drop whole results (never truncate mid-doc) to stay
   // under the limit. This mirrors the local MCP server's truncation behaviour.
-  const { accepted, truncated, usedBytes } = applyByteBudget(data ?? [], max_bytes);
+  const matched = (data ?? []) as Array<Record<string, unknown>>;
+  const { accepted, truncated, usedBytes } = applyByteBudget(matched, max_bytes);
+
+  // Nothing fit the budget (#254). Returning an empty `results` reads as "this
+  // knowledge does not exist" to whatever is on the other end, so send the
+  // rows WITHOUT their content instead: the caller learns what matched, how
+  // big it is, and can re-ask with a larger budget or fetch one document.
+  //
+  // Both content columns have to go: `cerefox_search_docs` (mode "docs")
+  // returns `full_content`, while `cerefox_hybrid_search` and the FTS RPC
+  // return `content`. Stripping one of them shipped in v1.14.2 and returned
+  // 83 KB of chunk text against a 3 KB budget while the response claimed the
+  // content had been omitted (#257).
+  const degraded = accepted.length === 0 && matched.length > 0;
+  // And the headers themselves are held to the budget the caller asked for:
+  // a `match_count` of 200 makes even a content-free list large. At least one
+  // survives regardless: an empty `results` is the "nothing was found" shape
+  // #254 exists to prevent, and a header row can exceed a very small budget
+  // on its own (#259).
+  const listed = degraded
+    ? (() => {
+        const headerRows = matched.map(
+          ({ full_content: _full, content: _chunk, ...header }) => header,
+        );
+        const fitted = applyByteBudget(headerRows, max_bytes).accepted;
+        return fitted.length > 0 ? fitted : headerRows.slice(0, 1);
+      })()
+    : [];
+  const results = degraded ? listed : accepted;
+  // What is actually being returned, which on a degraded response is the
+  // header list rather than the (empty) content-bearing set.
+  const responseBytes = degraded
+    ? new TextEncoder().encode(JSON.stringify(results)).length
+    : usedBytes;
 
   // Fire-and-forget usage logging (never blocks the response)
   Promise.resolve(supabase.rpc("cerefox_log_usage", {
@@ -382,20 +405,37 @@ Deno.serve(async (req: Request) => {
     p_access_path: "edge-function",
     p_requestor: identityValue ?? null,
     p_query_text: query,
-    p_result_count: accepted.length,
+    // What the query matched, not what survived the budget: recording 0 for a
+    // budget-wiped search made it look like an empty knowledge base here too.
+    p_result_count: matched.length,
     p_project_id: projectId,
   })).catch(() => {});
 
   return new Response(
     JSON.stringify({
-      results: accepted,
+      results,
       query,
       mode,
       match_count,
       project_name: project_name ?? null,
       metadata_filter: metadata_filter ?? null,
       truncated,
-      response_bytes: usedBytes,
+      response_bytes: responseBytes,
+      matched: matched.length,
+      degraded,
+      ...(degraded
+        ? {
+            note:
+              `${matched.length} result(s) matched but none fit max_bytes=${max_bytes}; ` +
+              `content omitted${
+                listed.length < matched.length
+                  ? `, and only ${listed.length} of them are listed here` +
+                    " (the rest did not fit either)"
+                  : ""
+              }. This is NOT an empty result. Raise max_bytes, or fetch one ` +
+              `document with cerefox-get-document.`,
+          }
+        : {}),
     }),
     { headers },
   );

package/docs/guides/connect-agents.md

@@ -638,7 +638,7 @@ In the action editor, paste this schema (replace `<your-project-ref>`):
 openapi: 3.1.0
 info:
   title: Cerefox Knowledge Base
-  version: 4.0.0
+  version: 4.2.0
 servers:
   - url: https://<your-project-ref>.supabase.co/functions/v1
 paths:
@@ -697,7 +697,10 @@ paths:
                     Response size budget in bytes (server hard ceiling 200000).
                     Whole results are dropped (never truncated mid-document) until
                     the budget is met; the response sets `truncated: true` when this
-                    happens. Advanced; leave unset for the default.
+                    happens. One exception: when nothing fits at all, a single
+                    content-free header is returned even if it exceeds the budget,
+                    because an empty results array would read as "nothing was found"
+                    (see degraded). Advanced; leave unset for the default.
                 author:
                   type: string
                   description: >
@@ -707,9 +710,17 @@ paths:
       responses:
         '200':
           description: >
-            { results, query, mode, match_count, project_name, metadata_filter, truncated, response_bytes }.
+            { results, query, mode, match_count, project_name, metadata_filter, truncated,
+            response_bytes, matched, degraded }.
             Each item in results (docs mode) contains: document_id, doc_title, full_content,
             chunk_count, total_chars, best_score, is_partial.
+            matched is how many results the query found, before the byte budget.
+            When degraded is true, everything that matched was larger than max_bytes, so the
+            items carry NO content of any kind — they name what exists so you can re-ask with
+            a larger max_bytes or fetch one document. That header list is itself capped to
+            max_bytes, so it may be a SUBSET of matched (at least one item is always
+            returned). Read matched, never results.length, to know how much the query found:
+            "nothing was found" is matched == 0.
             is_partial is true when the document exceeded the small-to-big threshold — in that
             case full_content contains matched chunks plus their neighbours rather than the
             complete document, and total_chars still reflects the full document size.
@@ -1124,7 +1135,7 @@ If the same content was already ingested (SHA-256 hash match), returns `"skipped
 | `mode` | string | `"docs"` | `"docs"` = full document results (recommended) |
 | `alpha` | number | 0.7 | Semantic weight (0 = FTS only, 1 = semantic only) |
 | `min_score` | number | 0.5 | Minimum cosine similarity threshold |
-| `max_bytes` | number | 200000 | Response size budget in bytes. Results are dropped whole (never truncated mid-document) once the budget is reached. The response includes `truncated: true` and `response_bytes` when the limit was hit. See "Response size limit" below. |
+| `max_bytes` | number | 200000 | Response size budget in bytes. Results are dropped whole (never truncated mid-document) once the budget is reached. The response includes `truncated: true` and `response_bytes` when the limit was hit. When nothing fits, `degraded: true` and a content-free header list come back instead of an empty `results` — always at least one item, even if it exceeds the budget. See "Response size limit" below. |
 
 **Response envelope fields:**
 

package/docs/guides/response-limits.md

@@ -30,13 +30,35 @@ agent's context window matters. Callers always choose whether to apply a limit.
 
 ## How limits are applied
 
-Truncation is always **whole-document**: results are dropped in full once adding the next
-document would exceed the budget. Cerefox never cuts a document mid-content.
+Truncation is always **whole-document**: a result is returned in full or not at all.
+Cerefox never cuts a document mid-content.
+
+A result that does not fit is **skipped**, not treated as the end of the list, so the
+returned set is not necessarily the top N by rank: one oversized document ranked first
+does not hide the smaller results behind it (v1.14.3). Anything skipped is named in the
+footer, so what is missing is always visible.
 
 When truncation occurs:
-- The local MCP server appends `[Results truncated at N bytes — ...]` to the response text.
+- The MCP tool appends a footer naming what was held back:
+  `[3 of 12 result(s) shown; 9 did not fit max_bytes=8000: Plan › Rollout (chunk 4) [id: …] and 8 more. Raise max_bytes, narrow the query, or lower match_count.]`
 - The Edge Function includes `"truncated": true` and `"response_bytes": N` in the JSON response.
 
+**The reply as a whole stays inside the budget**, footer and warnings included:
+they are measured in the same rendered bytes the caller receives (v1.14.3).
+When the budget is tight the framing gives way before the results do.
+
+**When nothing fits at all** — the smallest matching document is larger than
+the whole budget — the reply is NOT "no results found", which an agent acts on
+as "this knowledge does not exist". It is a header list naming what matched,
+its size and its id, prefixed with a warning and the remedy. The same case on
+the Edge Function sets `"degraded": true`, returns items with no content, and
+reports `"matched"`: read that, not `results.length`, to know what the query
+found. A reply may exceed `max_bytes` only by the framing that cannot be dropped
+without misleading you: the notice that results were held back, or the
+below-confidence advisory. Both are a few dozen bytes, and neither is ever
+traded for content. Returning 1 of 5 results without saying so, or presenting
+weak candidates as confident ones, would be worse than a small overrun.
+
 ---
 
 ## The server ceiling — agents can request less, never more