Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Evidence delivery (`return_unit`) — page text, chunk location, units, allocation, spans,
* errors, snippet precedence and final-consumer wiring.
*
* Authoring gate: protects the delivered-evidence contract in
* docs/evidence-delivery.md (the bytes gbrain-evals measures). Regressions it
* catches: page text that differs from the body (lost paragraph breaks, duplicated overlap), budget overrun, spans that
* point at the wrong text, a config flip overriding the subagent snippet cap,
* mutated shared hit rows, recall/think consumers dropping the evidence, and
* the auto default touching anything but conversation pages. No seams:
* the property half drives `deliverEvidence` through a stub engine that only
* answers `getChunkWindows`; the op half runs the real ops on PGLite.
*/
import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import type { BrainEngine } from '../src/core/engine.ts';
import type { SearchResult } from '../src/core/types.ts';
import type { ChunkWindowOpts, ChunkWindowPage, ChunkWindowRequest } from '../src/core/search/chunk-windows.ts';
import { operations, type OperationContext } from '../src/core/operations.ts';
import { chunkText } from '../src/core/chunkers/recursive.ts';
import { prepareMarkdownChunks } from '../src/core/markdown-chunks.ts';
import { installFixtureChunks } from './helpers/page-projection.ts';
import { renderPagesBlock } from '../src/core/think/gather.ts';
import { runThink } from '../src/core/think/index.ts';
import { formatDeliverySummary, formatResultsExplain } from '../src/core/search/explain-formatter.ts';
import {
AUTO_PACKINGS,
conversationSignal,
assembleEvidenceForHits,
capDeliveredSnippets,
capEngaged,
countEvidenceTokens,
deliverEvidence,
deliveryVersionSkewWarning,
EVIDENCE_BLOCK_CHAR_CAP,
EVIDENCE_CUT_MARKER,
EVIDENCE_OMISSION,
evidenceFingerprint,
isConversationLabels,
locateChunks,
MIN_EXPLICIT_AUTO_BUDGET,
pageEvidenceText,
resolveEvidencePlan,
splitPieces,
TIMELINE_SEPARATOR,
type AutoPacking,
type EvidencePlan,
} from '../src/core/search/evidence-delivery.ts';
import { searchConfigValueRefusal } from '../src/core/search/config-values.ts';
function rng(seed: number): () => number {
let a = seed >>> 0;
return () => {
a = (a + 0x6d2b79f5) >>> 0;
let t = a;
t = Math.imul(t ^ (t >>> 15), t | 1);
t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
};
}
const WORDS = ['alpha', 'river', 'launch', 'march', 'budget', 'widget', 'acme', 'notes', 'said', 'the', 'moved', 'plan', 'review', 'quarter', 'team', 'draft'];
function prose(r: () => number, paragraphs: number): string {
const out: string[] = [];
for (let p = 0; p < paragraphs; p++) {
const sentences: string[] = [];
const n = 2 + Math.floor(r() * 8);
for (let s = 0; s < n; s++) {
const len = 4 + Math.floor(r() * 16);
const words = Array.from({ length: len }, () => WORDS[Math.floor(r() * WORDS.length)]);
words[0] = words[0][0].toUpperCase() + words[0].slice(1);
sentences.push(words.join(' ') + '.');
}
out.push(sentences.join(' '));
}
return out.join('\n\n');
}
const norm = (s: string) => s.replace(/\s+/g, ' ').trim();
describe('page text and chunk location', () => {
test('every chunk the chunker cut is located in the body, even where it folded whitespace', () => {
const r = rng(7);
for (let doc = 0; doc < 25; doc++) {
const body = prose(r, 10 + Math.floor(r() * 40));
const chunks = chunkText(body).map((c, i) => ({ id: i + 1, chunk_index: i, chunk_text: c.text }));
const spans = locateChunks(body, chunks);
expect(spans.map(x => x.id)).toEqual(chunks.map(c => c.id));
for (const sp of spans) expect(norm(body.slice(sp.start, sp.end))).toBe(norm(chunks[sp.id - 1].chunk_text));
for (let i = 1; i < spans.length; i++) expect(spans[i].start).toBeGreaterThan(spans[i - 1].start);
}
});
test('long turns whose paragraph breaks the chunker folds are delivered byte-identical to the body', async () => {
const turn = (i: number) => `**${i % 2 ? 'assistant' : 'user'}:** ${Array.from({ length: 40 }, (_, k) => `Sentence ${i}-${k} has several plain words in it.`).join(' ')}`;
const body = Array.from({ length: 8 }, (_, i) => turn(i)).join('\n\n') + '\n';
const chunks = chunkText(body).map(c => c.text);
expect(chunks.some(c => !body.includes(c))).toBe(true);
const page: FakePage = { page_id: 1, slug: 'chat/long', title: 'Long', body, chunks };
const { results } = await deliverEvidence(fakeEngine([page]), [hitFor(page, 2)], planOf('page', 32000), {});
expect(results[0].chunk_text).toBe(body.trimEnd());
expect(results[0].delivered.truncated).toBe(false);
});
test('page text is the whole body sanitized before slicing, timeline joined like the serializer', () => {
const facts = `<!--- gbrain:facts:begin -->\n\n| # | claim | kind | confidence | visibility | notability | valid_from | valid_until | source | context |\n|---|-------|------|------------|------------|------------|------------|-------------|--------|---------|\n| 1 | PUBLICROW | fact | 1.0 | world | high | | | | |\n| 2 | PRIVATEROW | fact | 1.0 | private | high | | | | |\n<!--- gbrain:facts:end -->`;
const out = pageEvidenceText({ compiled_truth: `intro\n\n${facts}\n\n<!--- gbrain:takes:begin -->\nTAKEROW\n<!--- gbrain:takes:end -->\nend`, timeline: '- 2026 TIMELINEROW' }, true);
expect(out.text).toContain('PUBLICROW');
expect(out.text).not.toContain('PRIVATEROW');
expect(out.text).not.toContain('TAKEROW');
expect(out.text).toContain(`end${TIMELINE_SEPARATOR}- 2026 TIMELINEROW`);
expect(pageEvidenceText({ compiled_truth: 'x', timeline: 'TL' }, false).text).toBe('x');
});
test('CJK chunks (char-cut overlap) are located', () => {
const r = rng(11);
const cjk = Array.from({ length: 1500 }, () => '天地玄黄宇宙洪荒日月盈昃辰宿列张'[Math.floor(r() * 16)]).join('')
.replace(/(.{40})/g, '$1。');
const chunks = chunkText(cjk).map((c, i) => ({ id: i + 1, chunk_index: i, chunk_text: c.text }));
expect(chunks.length).toBeGreaterThan(2);
expect(locateChunks(cjk, chunks)).toHaveLength(chunks.length);
});
test('splitPieces is lossless and bounded', () => {
const text = `short line\n${'long '.repeat(300)}\n\nlast`;
const pieces = splitPieces(text);
expect(pieces.map(p => text.slice(p.start, p.end)).join('')).toBe(text);
for (const p of pieces) expect(p.end - p.start).toBeLessThanOrEqual(400);
});
test('token counts are CJK-aware (cl100k, not char/4)', () => {
const cjk = '天地玄黄宇宙洪荒'.repeat(40);
expect(countEvidenceTokens(cjk)).toBeGreaterThan(cjk.length / 4 * 2);
});
test('conversation detection is structural', () => {
expect(isConversationLabels(['user', 'assistant', 'user', 'assistant'])).toBe(true);
expect(isConversationLabels(['note', 'note', 'note', 'summary'])).toBe(false);
expect(isConversationLabels(['user', 'assistant'])).toBe(false);
});
});
// ---------------------------------------------------------------------------
// Property tests over the assembler (stub engine answering getChunkWindows)
// ---------------------------------------------------------------------------
interface FakePage { page_id: number; slug: string; title: string; chunks: string[]; body?: string; sealed?: boolean }
function fakeEngine(pages: FakePage[], opts: { fail?: boolean } = {}): BrainEngine & { calls: number } {
const engine = {
calls: 0,
async getChunkWindows(requests: ChunkWindowRequest[], o: ChunkWindowOpts): Promise<ChunkWindowPage[]> {
engine.calls++;
if (opts.fail) throw new Error('synthetic fetch failure');
const out: ChunkWindowPage[] = [];
for (const p of pages) {
const mine = requests.filter(r => r.page_id === p.page_id);
if (mine.length === 0) continue;
out.push({
page_id: p.page_id, slug: p.slug, source_id: 'default', type: 'note', revision: `rev-${p.page_id}`,
sealed: p.sealed !== false, max_chunk_index: p.chunks.length - 1, row_limited: false,
compiled_truth: p.body ?? p.chunks.join('\n\n'), timeline: '',
chunks: p.sealed === false ? [] : p.chunks.map((t, i) => ({ id: p.page_id * 1000 + i, chunk_index: i, chunk_text: t, chunk_source: 'compiled_truth' }))
.filter(c => mine.some(r => c.chunk_index >= r.from_index && c.chunk_index <= r.to_index))
.filter(() => o.chunkSources.includes('compiled_truth')),
});
}
return out;
},
};
return engine as unknown as BrainEngine & { calls: number };
}
function hitFor(p: FakePage, index: number): SearchResult {
return {
slug: p.slug, page_id: p.page_id, title: p.title, type: 'note', chunk_text: p.chunks[index], chunk_source: 'compiled_truth',
chunk_id: p.page_id * 1000 + index, chunk_index: index, score: 1, stale: false, source_id: 'default',
};
}
/**
* A plan as resolveEvidencePlan builds it. `budgetExplicit` defaults to false:
* the existing property and spill tests pin today's implied-budget path,
* which every packing must leave byte-identical; the explicit-budget cap has
* its own tests below (`capPlan`).
*/
function planOf(unit: EvidencePlan['unit'], budget: number, window = 1, extra: Partial<EvidencePlan> = {}): EvidencePlan {
return { requestedUnit: unit, unit, window, budgetTokens: budget, explicitUnit: true, budgetExplicit: false, packing: 'cap_only', ...extra };
}
function randomCorpus(r: () => number, pageCount: number): FakePage[] {
return Array.from({ length: pageCount }, (_, i) => {
const conversational = r() < 0.4;
const body = conversational
? Array.from({ length: 6 + Math.floor(r() * 30) }, (_, t) => `**${t % 2 ? 'assistant' : 'user'}:** ${prose(r, 1)}`).join('\n\n')
: Array.from({ length: 1 + Math.floor(r() * 4) }, (_, s) => `## Section ${s}\n\n${prose(r, 2 + Math.floor(r() * 8))}`).join('\n\n');
return { page_id: i + 1, slug: `${conversational ? 'chat' : 'pages'}/p${i + 1}`, title: `Page ${i + 1}`, body, chunks: chunkText(body).map(c => c.text) };
});
}
describe('allocation and boundary properties', () => {
test('budget, rank order, span, cap and non-mutation invariants hold across random corpora', async () => {
const r = rng(20260930);
for (let trial = 0; trial < 60; trial++) {
const pages = randomCorpus(r, 1 + Math.floor(r() * 8));
const hits: SearchResult[] = [];
for (let k = 0; k < 1 + Math.floor(r() * 10); k++) {
const p = pages[Math.floor(r() * pages.length)];
hits.push(hitFor(p, Math.floor(r() * p.chunks.length)));
}
const unit = (['window', 'section', 'page'] as const)[Math.floor(r() * 3)];
const budget = [40, 200, 800, 3000, 12000][Math.floor(r() * 5)];
const snapshot = JSON.stringify(hits);
const engine = fakeEngine(pages);
const { results, delivery } = await deliverEvidence(engine, hits, planOf(unit, budget, 1 + Math.floor(r() * 3)), {});
expect(JSON.stringify(hits)).toBe(snapshot);
expect(engine.calls).toBe(1);
expect(delivery.budget_used).toBeLessThanOrEqual(budget);
const order = [...new Set(hits.map(h => h.page_id))];
expect(results.map(x => x.page_id)).toEqual(order.filter(id => results.some(x => x.page_id === id)));
expect(new Set(results.map(x => x.page_id)).size).toBe(results.length);
expect(results.length + delivery.dropped).toBe(order.length);
for (const res of results) {
expect(res.chunk_text.length).toBeLessThanOrEqual(EVIDENCE_BLOCK_CHAR_CAP);
expect(res.delivered.tokens).toBeLessThanOrEqual(budget);
for (const id of res.delivered.chunk_ids) expect(hits.some(h => h.chunk_id === id && h.page_id === res.page_id)).toBe(true);
for (const s of res.delivered.match_spans) {
expect(s.start).toBeGreaterThanOrEqual(0);
expect(s.end).toBeLessThanOrEqual(res.chunk_text.length);
const anchor = hits.find(h => h.chunk_id === s.chunk_id)!;
expect(norm(anchor.chunk_text)).toContain(norm(res.chunk_text.slice(s.start, s.end)));
}
}
const again = await deliverEvidence(fakeEngine(pages), hits, planOf(unit, budget, delivery.return_window), {});
expect(evidenceFingerprint(again.results)).toBe(evidenceFingerprint(results));
}
});
// Pins the implied-budget path (planOf: budgetExplicit false), which the cap
// never touches: every chunk is kept and a session that cannot fit spills.
// "Explicit budget: ..." below is its twin under the cap.
test('auto: conversation pages whole, every other hit its unchanged chunk, nothing lost, expansion within budget', async () => {
const r = rng(20261001);
let sawPage = 0;
let sawChunk = 0;
for (let trial = 0; trial < 60; trial++) {
const pages = randomCorpus(r, 1 + Math.floor(r() * 8));
const hits: SearchResult[] = [];
for (let k = 0; k < 1 + Math.floor(r() * 10); k++) {
const p = pages[Math.floor(r() * pages.length)];
const h = hitFor(p, Math.floor(r() * p.chunks.length));
if (!hits.some(x => x.chunk_id === h.chunk_id)) hits.push(h);
}
const budget = [40, 200, 800, 3000, 24000][Math.floor(r() * 5)];
const snapshot = JSON.stringify(hits);
const engine = fakeEngine(pages);
const { results, delivery } = await deliverEvidence(engine, hits, planOf('auto', budget), {});
expect(JSON.stringify(hits)).toBe(snapshot);
expect(engine.calls).toBe(hits.some(h => h.slug.startsWith('chat/')) ? 1 : 0);
expect(delivery.dropped).toBe(0);
const cost = (x: SearchResult) => countEvidenceTokens(x.chunk_text) + countEvidenceTokens(x.title);
for (const h of hits) expect(results.some(x => x.delivered.chunk_ids.includes(h.chunk_id)), `hit ${h.chunk_id} lost`).toBe(true);
const firstRank = (x: SearchResult) => Math.min(...x.delivered!.chunk_ids.map(id => hits.findIndex(h => h.chunk_id === id)));
expect(results.map(firstRank)).toEqual(results.map(firstRank).sort((a, b) => a - b));
for (const res of results) {
if (res.delivered.reason === 'not_conversation' || res.delivered.reason === 'conversation_over_budget') {
sawChunk++;
const { delivered, ...row } = res;
expect(row).toEqual(hits.find(h => h.chunk_id === delivered.chunk_ids[0])!);
expect(delivered).toMatchObject({ unit: 'chunk', truncated: false, match_spans: [{ chunk_id: delivered.chunk_ids[0], start: 0, end: row.chunk_text.length }] });
expect(delivered.reason === 'not_conversation').toBe(!row.slug.startsWith('chat/'));
} else {
sawPage++;
expect(res.slug.startsWith('chat/')).toBe(true);
expect(res.delivered).toMatchObject({ unit: 'page', reason: 'conversation_slug' });
expect(res.delivered.match_spans.length).toBeGreaterThan(0);
}
}
const unchanged = results.filter(x => x.delivered.reason === 'not_conversation');
const expanded = results.filter(x => x.delivered.unit === 'page');
expect(new Set(expanded.map(x => x.page_id)).size).toBe(expanded.length);
expect(expanded.reduce((n, x) => n + cost(x), 0)).toBeLessThanOrEqual(Math.max(0, budget - unchanged.reduce((n, x) => n + cost(x), 0)));
}
expect(sawPage).toBeGreaterThan(10);
expect(sawChunk).toBeGreaterThan(10);
});
// Implied budget only: under an explicit budget nothing spills (twin below).
test('auto gives lower-ranked sessions their matching span, and spills a session that cannot fit to its chunks', async () => {
const pages = randomCorpus(rng(5), 12).filter(p => p.slug.startsWith('chat/')).slice(0, 3);
expect(pages).toHaveLength(3);
const hits = pages.map(p => hitFor(p, Math.floor(p.chunks.length / 2)));
const floors = hits.reduce((n, h) => n + countEvidenceTokens(h.chunk_text) + countEvidenceTokens(h.title), 0);
const roomy = await deliverEvidence(fakeEngine(pages), hits, planOf('auto', Math.ceil(floors * 1.5)), {});
expect(roomy.results.map(x => x.delivered.unit)).toEqual(['page', 'page', 'page']);
for (const res of roomy.results) expect(res.delivered.match_spans.length).toBeGreaterThan(0);
// The smallest budget that still gives rank one its page leaves no room for the others' spans.
let budget = countEvidenceTokens(hits[0].chunk_text);
let tight = await deliverEvidence(fakeEngine(pages), hits, planOf('auto', budget), {});
while (tight.results[0].delivered.unit !== 'page') tight = await deliverEvidence(fakeEngine(pages), hits, planOf('auto', ++budget), {});
expect(tight.results.map(x => x.delivered.reason)).toEqual(['conversation_slug', 'conversation_over_budget', 'conversation_over_budget']);
expect(tight.results.slice(1).map(x => x.chunk_text)).toEqual(hits.slice(1).map(h => h.chunk_text));
expect(tight.delivery.dropped).toBe(0);
});
test('a budget below every floor cuts rank one to fit and drops the rest', async () => {
const [a, b] = randomCorpus(rng(3), 2);
const { results, delivery } = await deliverEvidence(fakeEngine([a, b]), [hitFor(a, 0), hitFor(b, 0)], planOf('page', 12), {});
expect(results).toHaveLength(1);
expect(results[0].delivered.truncated).toBe(true);
expect(delivery.budget_used).toBeLessThanOrEqual(12);
expect(delivery.dropped_reasons).toEqual({ budget_floor: 1 });
});
test('distinct pages keep their matching span before rank one is enriched', async () => {
const pages = randomCorpus(rng(5), 5).map(p => ({ ...p, body: undefined, chunks: [...p.chunks, ...p.chunks, ...p.chunks] }));
const hits = pages.map(p => hitFor(p, Math.floor(p.chunks.length / 2)));
const floors = hits.reduce((n, h) => n + countEvidenceTokens(h.chunk_text) + countEvidenceTokens(h.title), 0);
const { results } = await deliverEvidence(fakeEngine(pages), hits, planOf('page', Math.ceil(floors * 1.5)), {});
expect(results).toHaveLength(5);
expect(results[0].delivered.truncated).toBe(true);
for (const res of results) expect(res.delivered.match_spans.length).toBeGreaterThan(0);
});
test('many sessions, repeated text and missing anchors stay deterministic and explicit', async () => {
const repeated = 'the same sentence repeats verbatim across every chunk here.';
const page: FakePage = { page_id: 9, slug: 'chat/repeat', title: 'Repeat', chunks: Array.from({ length: 6 }, () => repeated) };
const ghost: SearchResult = { ...hitFor(page, 2), chunk_id: 999_999, chunk_text: 'text that is no longer in the page at all' };
const { results } = await deliverEvidence(fakeEngine([page]), [hitFor(page, 1), ghost], planOf('window', 5000), {});
expect(results).toHaveLength(1);
expect(results[0].delivered.chunk_ids).toEqual([9001, 999_999]);
expect(results[0].delivered.unmapped_chunk_ids).toEqual([999_999]);
expect(results[0].delivered.match_spans.every(s => s.chunk_id === 9001)).toBe(true);
});
test('redaction runs before accounting and unmaps shifted spans', async () => {
const secret = ['AKIA', 'ABCDEFGHIJKLMNOP'].join('');
const page: FakePage = { page_id: 4, slug: 'notes/keys', title: 'Keys', chunks: [`The deploy key is ${secret} for staging and nothing else here.`] };
const { results, delivery } = await deliverEvidence(fakeEngine([page]), [hitFor(page, 0)], planOf('page', 5000), {});
expect(results[0].chunk_text).not.toContain(secret);
expect(results[0].chunk_text).toContain('<REDACTED:');
expect(results[0].delivered.match_spans).toEqual([]);
expect(results[0].delivered.unmapped_chunk_ids).toEqual([4000]);
expect(delivery.fallbacks).toContain('redaction_unmapped');
});
test('oversized pages are cut at the 60,000-character cap, never redacted wholesale', async () => {
const big = Array.from({ length: 40 }, (_, i) => `Paragraph ${i}. ${'lorem ipsum dolor sit amet '.repeat(90)}`);
const page: FakePage = { page_id: 2, slug: 'notes/big', title: 'Big', chunks: big };
const { results } = await deliverEvidence(fakeEngine([page]), [hitFor(page, 20)], planOf('page', 32000), {});
expect(results[0].chunk_text.length).toBeLessThanOrEqual(EVIDENCE_BLOCK_CHAR_CAP);
expect(results[0].chunk_text).not.toContain('<REDACTED:output_limit>');
expect(results[0].delivered.truncated).toBe(true);
expect(results[0].chunk_text).toContain('Paragraph 20.');
});
test('fetch failure falls back to fresh hit chunks, and never to cached ones', async () => {
const [a] = randomCorpus(rng(8), 1);
const live = await deliverEvidence(fakeEngine([a], { fail: true }), [hitFor(a, 0)], planOf('page', 5000), {});
expect(live.results[0].chunk_text).toBe(a.chunks[0]);
expect(live.results[0].delivered).toMatchObject({ unit: 'chunk', fallback_reason: 'fetch_failed' });
expect(live.delivery.applied_unit).toBe('chunk');
const cached = await deliverEvidence(fakeEngine([a], { fail: true }), [hitFor(a, 0)], planOf('page', 5000), {}, { liveHits: false });
expect(cached.results).toEqual([]);
expect(cached.delivery.dropped_reasons).toEqual({ not_readable: 1 });
});
test('a fetch that exceeds the timeout degrades to fresh hit chunks with a receipt', async () => {
const [a] = randomCorpus(rng(14), 1);
const hanging = { getChunkWindows: () => new Promise<never>(() => {}) } as unknown as BrainEngine;
const { results, delivery } = await deliverEvidence(hanging, [hitFor(a, 0)], planOf('page', 5000), {}, { timeoutMs: 20 });
expect(results[0].delivered.fallback_reason).toBe('fetch_timeout');
expect(delivery.fallbacks).toContain('fetch_timeout');
expect(formatDeliverySummary(delivery)).toContain('fallbacks: fetch_timeout');
});
test('a page absent from the re-authorized fetch is dropped, not served from the hit', async () => {
const [a, b] = randomCorpus(rng(9), 2);
const { results, delivery } = await deliverEvidence(fakeEngine([a]), [hitFor(b, 0), hitFor(a, 0)], planOf('window', 5000), {});
expect(results.map(x => x.slug)).toEqual([a.slug]);
expect(delivery.dropped_reasons).toEqual({ not_readable: 1 });
expect(JSON.stringify(results)).not.toContain(b.chunks[0].slice(0, 60));
});
test('unsealed pages fall back to the hit chunk with a named reason', async () => {
const [a] = randomCorpus(rng(10), 1);
const { results } = await deliverEvidence(fakeEngine([{ ...a, sealed: false }]), [hitFor(a, 0)], planOf('page', 5000), {});
expect(results[0].delivered.fallback_reason).toBe('unsealed_page');
});
test('section falls back to window when a page has no structure', async () => {
const flat = prose(rng(12), 40);
const page: FakePage = { page_id: 3, slug: 'notes/flat', title: 'Flat', body: flat, chunks: chunkText(flat).map(c => c.text) };
const { results, delivery } = await deliverEvidence(fakeEngine([page]), [hitFor(page, 2)], planOf('section', 20000), {});
expect(results[0].delivered.unit).toBe('window');
expect(delivery.fallbacks).toContain('no_section_structure');
});
test('non-contiguous hits on one page join with the fixed omission line', async () => {
const longBody = prose(rng(13), 80);
const page: FakePage = { page_id: 5, slug: 'notes/long', title: 'Long', body: longBody, chunks: chunkText(longBody).map(c => c.text) };
expect(page.chunks.length).toBeGreaterThan(8);
const { results } = await deliverEvidence(fakeEngine([page]), [hitFor(page, 1), hitFor(page, page.chunks.length - 2)], planOf('window', 20000), {});
expect(results).toHaveLength(1);
expect(results[0].chunk_text).toContain(EVIDENCE_OMISSION);
expect(results[0].delivered.match_spans.map(s => s.chunk_id)).toEqual([5001, 5000 + page.chunks.length - 2]);
});
});
// ---------------------------------------------------------------------------
// Explicit budgets under auto: the cap (search.auto_packing)
// ---------------------------------------------------------------------------
const CAP_PACKINGS = AUTO_PACKINGS.filter((x): x is Exclude<AutoPacking, 'off'> => x !== 'off');
function capPlan(budget: number, packing: AutoPacking = 'cap_only', window = 1): EvidencePlan {
return planOf('auto', budget, window, { budgetExplicit: true, packing });
}
const recount = (rows: Array<{ title?: string; chunk_text: string }>) => rows.reduce((n, x) => n + countEvidenceTokens(x.title ?? '') + countEvidenceTokens(x.chunk_text), 0);
/** A chat page of three one-line turns: return_window 1 around turn 1 covers the whole page. */
function chatPage(id: number, words: number, title = `Chat ${id}`): FakePage {
const r = rng(1000 + id);
const turn = (who: string, k: number) => `**${who}:** ${Array.from({ length: words }, () => WORDS[Math.floor(r() * WORDS.length)]).join(' ')} turn ${id}-${k}.`;
const chunks = [turn('user', 0), turn('assistant', 1), turn('user', 2)];
return { page_id: id, slug: `chat/c${id}`, title, chunks };
}
function notePage(id: number, words: number, title = `Note ${id}`): FakePage {
const r = rng(2000 + id);
return { page_id: id, slug: `notes/n${id}`, title, chunks: [`${Array.from({ length: words }, () => WORDS[Math.floor(r() * WORDS.length)]).join(' ')} note ${id}.`] };
}
const whole = (p: FakePage) => countEvidenceTokens(p.title) + countEvidenceTokens(p.chunks.join('\n\n'));
const floorOf = (p: FakePage, i = 1) => countEvidenceTokens(p.title) + countEvidenceTokens(p.chunks[i] + (i < p.chunks.length - 1 ? '\n' : ''));
describe('explicit budget: the cap', () => {
test('without an explicit budget every packing is today\'s path, byte for byte (guard 1, structural)', async () => {
const r = rng(20261009);
let compared = 0;
for (let trial = 0; trial < 60; trial++) {
const pages = randomCorpus(r, 1 + Math.floor(r() * 8));
const hits: SearchResult[] = [];
for (let k = 0; k < 1 + Math.floor(r() * 25); k++) {
const p = pages[Math.floor(r() * pages.length)];
const h = hitFor(p, Math.floor(r() * p.chunks.length));
if (!hits.some(x => x.chunk_id === h.chunk_id)) hits.push(h);
}
const budget = [40, 200, 800, 3000, 24000][Math.floor(r() * 5)];
const today = JSON.stringify(await deliverEvidence(fakeEngine(pages), hits, planOf('auto', budget, 1, { packing: 'off' }), {}));
for (const packing of AUTO_PACKINGS) {
expect(capEngaged(planOf('auto', budget, 1, { packing }))).toBe(false);
expect(JSON.stringify(await deliverEvidence(fakeEngine(pages), hits, planOf('auto', budget, 1, { packing }), {}))).toBe(today);
compared++;
}
// An explicit budget with packing off is today's path too.
expect(JSON.stringify(await deliverEvidence(fakeEngine(pages), hits, capPlan(budget, 'off'), {}))).toBe(today);
}
expect(compared).toBe(240);
});
// Twin of the implied-budget property above: under the cap the recount of
// the final evidence fields never exceeds the budget, nothing spills, rank
// one is always delivered and every hit is delivered or counted as dropped.
test('explicit budget: the recount never exceeds the budget, nothing spills, rank one survives, every hit is accounted for', async () => {
const r = rng(20261010);
let cut = 0;
let droppedAny = 0;
for (let trial = 0; trial < 50; trial++) {
const pages = randomCorpus(r, 1 + Math.floor(r() * 10));
const hits: SearchResult[] = [];
for (let k = 0; k < 1 + Math.floor(r() * 25); k++) {
const p = pages[Math.floor(r() * pages.length)];
const h = hitFor(p, Math.floor(r() * p.chunks.length));
if (!hits.some(x => x.chunk_id === h.chunk_id)) hits.push(h);
}
const items = new Set(hits.map(h => h.slug.startsWith('chat/') ? `p${h.page_id}` : `c${h.chunk_id}`)).size;
for (const packing of CAP_PACKINGS) {
const budget = [MIN_EXPLICIT_AUTO_BUDGET, 40, 200, 800, 3000, 8000, 24000][Math.floor(r() * 7)];
const snapshot = JSON.stringify(hits);
const { results, delivery } = await deliverEvidence(fakeEngine(pages), hits, capPlan(budget, packing, 1 + Math.floor(r() * 3)), {});
const label = `trial ${trial} ${packing} @${budget}`;
expect(JSON.stringify(hits)).toBe(snapshot);
expect(recount(results), label).toBeLessThanOrEqual(budget);
expect(delivery.budget_used, label).toBe(recount(results));
expect(delivery.auto_packing).toBe(packing);
expect(results.length, label).toBeGreaterThan(0);
expect(results[0].delivered.chunk_ids, label).toContain(hits[0].chunk_id);
expect(results.length + delivery.dropped, label).toBe(items);
expect(results.some(x => x.delivered.reason === 'conversation_over_budget'), label).toBe(false);
const firstRank = (x: SearchResult) => Math.min(...x.delivered!.chunk_ids.map(id => hits.findIndex(h => h.chunk_id === id)));
expect(results.map(firstRank)).toEqual(results.map(firstRank).sort((a, b) => a - b));
for (const res of results) {
expect(res.chunk_text.length).toBeLessThanOrEqual(EVIDENCE_BLOCK_CHAR_CAP + EVIDENCE_CUT_MARKER.length);
for (const sp of res.delivered.match_spans) {
expect(sp.end).toBeLessThanOrEqual(res.chunk_text.length);
const anchor = hits.find(h => h.chunk_id === sp.chunk_id)!;
expect(norm(anchor.chunk_text)).toContain(norm(res.chunk_text.slice(sp.start, sp.end)));
}
if (res.chunk_text.endsWith(EVIDENCE_CUT_MARKER)) { cut++; expect(res.delivered.truncated).toBe(true); }
}
if (delivery.dropped > 0) droppedAny++;
}
}
expect(cut).toBeGreaterThan(5);
expect(droppedAny).toBeGreaterThan(20);
});
test('explicit budget: a session that cannot fit is dropped, never spilled outside the budget (twin of the spill test)', async () => {
const pages = randomCorpus(rng(5), 12).filter(p => p.slug.startsWith('chat/')).slice(0, 3);
const hits = pages.map(p => hitFor(p, Math.floor(p.chunks.length / 2)));
let budget = countEvidenceTokens(hits[0].chunk_text);
let tight = await deliverEvidence(fakeEngine(pages), hits, capPlan(budget), {});
while (tight.results[0].delivered.truncated) tight = await deliverEvidence(fakeEngine(pages), hits, capPlan(++budget), {});
expect(tight.results.map(x => x.slug)).toEqual([pages[0].slug]);
expect(tight.delivery.dropped_reasons).toEqual({ budget_floor: 2 });
expect(tight.delivery.budget_used).toBeLessThanOrEqual(budget);
const today = await deliverEvidence(fakeEngine(pages), hits, planOf('auto', budget), {});
expect(today.delivery.budget_used).toBeGreaterThan(budget);
});
test('mixed notes and chats: global rank one comes first, note or chat', async () => {
const [c1, c2] = [chatPage(1, 60), chatPage(2, 60)];
const n3 = notePage(3, 30);
const budget = floorOf(c1) + whole(n3) + 4;
for (const packing of CAP_PACKINGS) {
const noteFirst = await deliverEvidence(fakeEngine([c1, c2, n3]), [hitFor(n3, 0), hitFor(c1, 1), hitFor(c2, 1)], capPlan(budget, packing), {});
expect(noteFirst.results.map(x => x.slug), packing).toEqual(packing === 'breadth_capped' ? ['notes/n3'] : ['notes/n3', 'chat/c1']);
expect(noteFirst.results[0].delivered).toMatchObject({ unit: 'chunk', reason: 'not_conversation', truncated: false });
const chatFirst = await deliverEvidence(fakeEngine([c1, c2, n3]), [hitFor(c1, 1), hitFor(n3, 0), hitFor(c2, 1)], capPlan(budget, packing), {});
expect(chatFirst.results.map(x => x.slug), packing).toEqual(['chat/c1', 'notes/n3']);
expect(recount(chatFirst.results)).toBeLessThanOrEqual(budget);
}
});
test('a leading chat is never crowded out by a lower-ranked note that does not fit', async () => {
const c1 = chatPage(1, 40);
const big = notePage(2, 900);
const budget = whole(c1) + 10;
for (const packing of CAP_PACKINGS) {
const { results, delivery } = await deliverEvidence(fakeEngine([c1, big]), [hitFor(c1, 1), hitFor(big, 0)], capPlan(budget, packing), {});
expect(results.map(x => x.slug), packing).toEqual(['chat/c1']);
expect(results[0].delivered).toMatchObject({ unit: 'page', truncated: false });
expect(delivery.dropped_reasons).toEqual({ budget_note: 1 });
}
// Today's implied path pays the note first and spills the chat to its chunk.
const today = await deliverEvidence(fakeEngine([c1, big]), [hitFor(c1, 1), hitFor(big, 0)], planOf('auto', budget), {});
expect(today.results.map(x => x.delivered.reason)).toEqual(['conversation_over_budget', 'not_conversation']);
});
test('notes only, over budget: the rank-order prefix that fits is kept and the rest is listed', async () => {
const [a, b, c] = [notePage(1, 20), notePage(2, 400), notePage(3, 20)];
const budget = whole(a) + 40;
const { results, delivery } = await deliverEvidence(fakeEngine([a, b, c]), [hitFor(a, 0), hitFor(b, 0), hitFor(c, 0)], capPlan(budget), {});
expect(results.map(x => x.slug)).toEqual(['notes/n1']);
expect(results[0].chunk_text).toBe(a.chunks[0]);
expect(delivery.dropped_reasons).toEqual({ budget_note: 2 });
// Rank one longer than the budget is cut at a piece boundary with the counted marker, never empty.
const cut = await deliverEvidence(fakeEngine([b, a]), [hitFor(b, 0), hitFor(a, 0)], capPlan(60), {});
expect(cut.results).toHaveLength(1);
expect(cut.results[0].chunk_text.endsWith(EVIDENCE_CUT_MARKER)).toBe(true);
expect(cut.results[0].chunk_text.length).toBeGreaterThan(EVIDENCE_CUT_MARKER.length + 10);
expect(b.chunks[0].startsWith(cut.results[0].chunk_text.slice(0, -EVIDENCE_CUT_MARKER.length))).toBe(true);
expect(cut.results[0].delivered).toMatchObject({ truncated: true, match_spans: [{ start: 0, end: cut.results[0].chunk_text.length - EVIDENCE_CUT_MARKER.length }] });
expect(recount(cut.results)).toBeLessThanOrEqual(60);
expect(cut.delivery.dropped_reasons).toEqual({ budget_note: 1 });
});
test('rank one longer than the budget is cut to fit with a marker, never dropped, in every packing', async () => {
const big = chatPage(1, 400);
const other = chatPage(2, 40);
for (const packing of CAP_PACKINGS) {
for (const budget of [MIN_EXPLICIT_AUTO_BUDGET, 40, 100]) {
const { results, delivery } = await deliverEvidence(fakeEngine([big, other]), [hitFor(big, 1), hitFor(other, 1)], capPlan(budget, packing), {});
expect(results.map(x => x.slug)).toEqual(['chat/c1']);
expect(results[0].delivered.truncated).toBe(true);
expect(results[0].chunk_text.endsWith(EVIDENCE_CUT_MARKER)).toBe(true);
expect(results[0].chunk_text.length - EVIDENCE_CUT_MARKER.length).toBeGreaterThan(0);
expect(recount(results), `${packing} @${budget}`).toBeLessThanOrEqual(budget);
expect(delivery.dropped).toBe(1);
}
}
});
test('breadth_capped keeps the longest rank-order prefix whose title, floor and target window fit, then drops the rest as breadth_cap', async () => {
const pages = [chatPage(1, 50), chatPage(2, 50), chatPage(3, 50), chatPage(4, 50)];
const hits = pages.map(p => hitFor(p, 1));
// return_window 1 around turn 1 is the whole three-turn page, so each group's price is the whole page.
const budget = whole(pages[0]) + whole(pages[1]) + Math.floor(whole(pages[2]) / 2);
const { results, delivery } = await deliverEvidence(fakeEngine(pages), hits, capPlan(budget, 'breadth_capped'), {});
expect(results.map(x => x.slug)).toEqual(['chat/c1', 'chat/c2']);
for (const res of results) expect(res.delivered).toMatchObject({ unit: 'page', truncated: false });
expect(delivery.dropped_reasons).toEqual({ breadth_cap: 2 });
// cap_only on the same budget reserves every floor first, so the third session keeps its span.
const capOnly = await deliverEvidence(fakeEngine(pages), hits, capPlan(budget, 'cap_only'), {});
expect(capOnly.results.length).toBeGreaterThan(2);
// An oversized first group is cut, never skipped.
const tiny = await deliverEvidence(fakeEngine(pages), hits, capPlan(floorOf(pages[0]) - 5, 'breadth_capped'), {});
expect(tiny.results.map(x => x.slug)).toEqual(['chat/c1']);
expect(tiny.results[0].delivered.truncated).toBe(true);
expect(tiny.delivery.dropped_reasons).toEqual({ breadth_cap: 3 });
// A first group whose window does not fit keeps its floor (rank one), and the rest are breadth-capped.
const lead = await deliverEvidence(fakeEngine(pages), hits, capPlan(floorOf(pages[0]) + 6, 'breadth_capped'), {});
expect(lead.results.map(x => x.slug)).toEqual(['chat/c1']);
expect(lead.delivery.dropped_reasons).toEqual({ breadth_cap: 3 });
});
test('depth_first takes each session whole when it fits, else the largest window, else skips it', async () => {
const pages = [chatPage(1, 60), chatPage(2, 60), chatPage(3, 60)];
const hits = pages.map(p => hitFor(p, 1));
const budget = whole(pages[0]) + floorOf(pages[1]) + 2;
const depth = await deliverEvidence(fakeEngine(pages), hits, capPlan(budget, 'depth_first'), {});
expect(depth.results.map(x => x.slug)).toEqual(['chat/c1', 'chat/c2']);
expect(depth.results[0].delivered).toMatchObject({ unit: 'page', truncated: false });
expect(depth.results[1].delivered.truncated).toBe(true);
expect(depth.delivery.dropped_reasons).toEqual({ budget_floor: 1 });
// cap_only reserves all three floors before growing any session.
const capOnly = await deliverEvidence(fakeEngine(pages), hits, capPlan(budget, 'cap_only'), {});
expect(capOnly.results.map(x => x.slug)).toEqual(['chat/c1', 'chat/c2', 'chat/c3']);
expect(capOnly.results[0].delivered.truncated).toBe(true);
// Depth first: the leading session grows into what is left before the next one is considered.
const greedy = await deliverEvidence(fakeEngine([pages[0], pages[1]]), [hitFor(pages[0], 1), hitFor(pages[1], 1)], capPlan(floorOf(pages[0]) + floorOf(pages[1]) + 1, 'depth_first'), {});
expect(greedy.results.map(x => x.slug)).toEqual(['chat/c1']);
expect(greedy.delivery.dropped_reasons).toEqual({ budget_floor: 1 });
// A session whose matching chunk does not fit is skipped; a later one that fits is still taken.
const [big, small] = [chatPage(5, 400), chatPage(6, 10)];
const skip = await deliverEvidence(fakeEngine([pages[0], big, small]), [hitFor(pages[0], 1), hitFor(big, 1), hitFor(small, 1)], capPlan(whole(pages[0]) + whole(small) + 2, 'depth_first'), {});
expect(skip.results.map(x => x.slug)).toEqual(['chat/c1', 'chat/c6']);
expect(skip.results.map(x => x.delivered.truncated)).toEqual([false, false]);
expect(skip.delivery.dropped_reasons).toEqual({ budget_floor: 1 });
});
test('source swamp: a curated note survives chat dumps that repeat its phrase under a tight budget, in every packing', async () => {
const phrase = 'renewal window closes friday';
const dumps = [1, 2, 3, 4].map(id => {
const p = chatPage(id, 120);
return { ...p, chunks: p.chunks.map(c => `${c} ${phrase}.`) };
});
const note: FakePage = { page_id: 9, slug: 'notes/renewal-policy', title: 'Renewal policy', chunks: [`The ${phrase}; the owner signs it.`] };
const budget = floorOf(dumps[0]) + whole(note) + 20;
for (const packing of CAP_PACKINGS) {
for (let at = 0; at <= 4; at++) {
const hits = dumps.map(d => hitFor(d, 1));
hits.splice(at, 0, hitFor(note, 0));
const { results } = await deliverEvidence(fakeEngine([...dumps, note]), hits, capPlan(budget, packing), {});
expect(results.some(x => x.slug === 'notes/renewal-policy'), `${packing}, note at rank ${at}`).toBe(true);
expect(recount(results)).toBeLessThanOrEqual(budget);
}
}
});
test('zero conversation hits: within the budget the rows are the ranked chunks, unchanged', async () => {
const notes = [notePage(1, 20), notePage(2, 20)];
const hits = notes.map(n => hitFor(n, 0));
const engine = fakeEngine(notes);
const { results, delivery } = await deliverEvidence(engine, hits, capPlan(4000), {});
expect(engine.calls).toBe(0);
expect(results.map(({ delivered, ...row }) => row)).toEqual(hits);
expect(delivery).toMatchObject({ auto_packing: 'cap_only', dropped: 0, budget_used: recount(results) });
});
test('redaction that grows a row is recounted inside the budget', async () => {
const secret = ['AKIA', 'ABCDEFGHIJKLMNOP'].join('');
const note: FakePage = { page_id: 4, slug: 'notes/keys', title: 'Keys', chunks: [`The deploy key is ${secret} ${secret} ${secret} for staging and nothing else here at all.`] };
const budget = Math.max(MIN_EXPLICIT_AUTO_BUDGET, whole(note));
const { results, delivery } = await deliverEvidence(fakeEngine([note]), [hitFor(note, 0)], capPlan(budget), {});
expect(results[0].chunk_text).not.toContain(secret);
expect(results[0].chunk_text).toContain('<REDACTED:');
expect(delivery.fallbacks).toContain('redaction_unmapped');
expect(recount(results)).toBeLessThanOrEqual(budget);
expect(delivery.budget_used).toBe(recount(results));
});
test('the 60,000-character cap is reached before a large budget, and CJK spans stay UTF-16 exact', async () => {
const big = Array.from({ length: 40 }, (_, i) => `**${i % 2 ? 'assistant' : 'user'}:** Paragraph ${i}. ${'lorem ipsum dolor sit amet '.repeat(90)}`);
const page: FakePage = { page_id: 2, slug: 'chat/big', title: 'Big', chunks: big };
const { results } = await deliverEvidence(fakeEngine([page]), [hitFor(page, 20)], capPlan(32000), {});
expect(results[0].chunk_text.length).toBeLessThanOrEqual(EVIDENCE_BLOCK_CHAR_CAP);
expect(results[0].chunk_text).toContain('Paragraph 20.');
const r = rng(31);
const cjkTurn = (who: string) => `**${who}:** ${Array.from({ length: 120 }, () => '天地玄黄宇宙洪荒日月盈昃'[Math.floor(r() * 12)]).join('')}`;
const cjk: FakePage = { page_id: 3, slug: 'chat/cjk', title: '会话', chunks: [cjkTurn('user'), cjkTurn('assistant'), cjkTurn('user'), cjkTurn('assistant')] };
for (const packing of CAP_PACKINGS) {
const out = await deliverEvidence(fakeEngine([cjk]), [hitFor(cjk, 2)], capPlan(120, packing), {});
expect(recount(out.results)).toBeLessThanOrEqual(120);
for (const sp of out.results[0].delivered.match_spans) expect(cjk.chunks[2]).toContain(out.results[0].chunk_text.slice(sp.start, sp.end));
}
});
test('fetch failure, timeout and cached hits under the cap: fresh chunks within the budget, cached ones dropped', async () => {
const pages = [chatPage(1, 200), chatPage(2, 200)];
const hits = pages.map(p => hitFor(p, 1));
const live = await deliverEvidence(fakeEngine(pages, { fail: true }), hits, capPlan(120), {});
expect(live.results[0].delivered.fallback_reason).toBe('fetch_failed');
expect(recount(live.results)).toBeLessThanOrEqual(120);
const hanging = { getChunkWindows: () => new Promise<never>(() => {}) } as unknown as BrainEngine;
const slow = await deliverEvidence(hanging, hits, capPlan(120), {}, { timeoutMs: 20 });
expect(slow.delivery.fallbacks).toContain('fetch_timeout');
expect(recount(slow.results)).toBeLessThanOrEqual(120);
const cached = await deliverEvidence(fakeEngine(pages, { fail: true }), hits, capPlan(120), {}, { liveHits: false });
expect(cached.results).toEqual([]);
expect(cached.delivery.dropped_reasons).toEqual({ not_readable: 2 });
});
test('budgets below the documented minimum, zero, negative and non-finite are refused by name; the minimum is served', async () => {
const stub = { getConfig: async () => null } as unknown as BrainEngine;
const plan = (budget: unknown, extra: Record<string, unknown> = {}) => resolveEvidencePlan(stub, {
remote: false, returnUnit: 'auto', returnWindow: undefined, budget, snippetChars: undefined, snippetCap: 0, op: 'query', ...extra,
});
for (const budget of [...Array.from({ length: MIN_EXPLICIT_AUTO_BUDGET - 1 }, (_, i) => i + 1), 0, -5, 31.9, Number.NaN, Number.POSITIVE_INFINITY, Number.NEGATIVE_INFINITY]) {
await expect(plan(budget), String(budget)).rejects.toMatchObject({
code: 'invalid_params', message: expect.stringContaining(`token_budget must be at least ${MIN_EXPLICIT_AUTO_BUDGET} tokens`),
});
}
await expect(plan(3, { op: 'recall' })).rejects.toMatchObject({ message: expect.stringContaining('budget_tokens must be at least') });
expect(await plan(MIN_EXPLICIT_AUTO_BUDGET)).toMatchObject({ budgetTokens: MIN_EXPLICIT_AUTO_BUDGET, budgetExplicit: true, packing: 'cap_only' });
// Off the cap the old meanings stand: packing off, another unit, or no budget.
expect(await plan(5, { autoPacking: 'off' })).toMatchObject({ budgetTokens: 5, budgetExplicit: true, packing: 'off' });
expect(await plan(5, { returnUnit: 'page' })).toMatchObject({ unit: 'page', budgetTokens: 5 });
expect(await plan(undefined)).toMatchObject({ budgetTokens: 24000, budgetExplicit: false });
// With the unit implied, a budget that is not a positive number still means no budget, as before.
for (const budget of [0, -1, Number.NaN, Number.POSITIVE_INFINITY]) {
expect(await plan(budget, { returnUnit: undefined, op: 'recall' })).toMatchObject({ unit: 'auto', budgetTokens: 24000, budgetExplicit: false });
}
await expect(plan(4000, { autoPacking: 'widest' })).rejects.toMatchObject({ code: 'invalid_params', message: expect.stringContaining('auto_packing must be one of off, cap_only, breadth_capped, depth_first') });
// At the minimum a non-empty hit list yields non-empty evidence within it.
const r = rng(77);
for (let trial = 0; trial < 20; trial++) {
const pages = randomCorpus(r, 1 + Math.floor(r() * 5));
const hits = pages.map(p => hitFor(p, Math.floor(r() * p.chunks.length)));
for (const packing of CAP_PACKINGS) {
const { results } = await deliverEvidence(fakeEngine(pages), hits, capPlan(MIN_EXPLICIT_AUTO_BUDGET, packing), {});
expect(results.length).toBeGreaterThan(0);
expect(results[0].chunk_text.replace(EVIDENCE_CUT_MARKER, '').trim().length).toBeGreaterThan(0);
expect(recount(results)).toBeLessThanOrEqual(MIN_EXPLICIT_AUTO_BUDGET);
}
}
});
test('under the cap a snippet marker is paid from the row\'s own allocation, or left out when it cannot fit', async () => {
const page = chatPage(1, 30);
const { results, delivery } = await deliverEvidence(fakeEngine([page]), [hitFor(page, 1)], capPlan(4000), {});
const before = countEvidenceTokens(results[0].chunk_text);
const cap = results[0].chunk_text.length - 3;
const capped = capDeliveredSnippets(results, cap, { ...delivery, fallbacks: [...delivery.fallbacks] });
expect(capped[0].chunk_text).toContain('[truncated');
expect(countEvidenceTokens(capped[0].chunk_text)).toBeLessThanOrEqual(before);
// Without the cap the same snippet cap grows the row (the old behavior, kept for implied budgets).
const legacy = capDeliveredSnippets(results, cap, { ...delivery, auto_packing: undefined, fallbacks: [...delivery.fallbacks] });
expect(countEvidenceTokens(legacy[0].chunk_text)).toBeGreaterThan(before);
// A row too small to hold the marker keeps a shorter body and says so.
const tiny = [{ ...results[0], chunk_text: 'Short row of ten words that the cap trims here.' }];
const meta = { ...delivery, fallbacks: [...delivery.fallbacks] };
const out = capDeliveredSnippets(tiny, 20, meta);
expect(out[0].chunk_text).not.toContain('[truncated');
expect(countEvidenceTokens(out[0].chunk_text)).toBeLessThanOrEqual(countEvidenceTokens(tiny[0].chunk_text));
expect(meta.fallbacks).toEqual(expect.arrayContaining(['snippet_cap', 'snippet_marker_omitted']));
expect(meta.budget_used).toBe(recount(out));
});
test('search.auto_packing refuses unknown values at config set', () => {
for (const v of AUTO_PACKINGS) expect(searchConfigValueRefusal('search.auto_packing', v)).toBeNull();
expect(searchConfigValueRefusal('search.auto_packing', 'breadth')).toMatchObject({ message: expect.stringContaining('must be one of off, cap_only, breadth_capped, depth_first'), example: 'cap_only' });
});
});
// ---------------------------------------------------------------------------
// Real ops on PGLite
// ---------------------------------------------------------------------------
let engine: PGLiteEngine;
const op = (name: string) => operations.find(o => o.name === name)!;
let lastMeta: Record<string, any> | null = null;
function ctxOf(overrides: Partial<OperationContext> = {}): OperationContext {
return {
engine: engine as never, config: {} as never, logger: console as never, dryRun: false, remote: false, sourceId: 'default',
emitResponseMeta: (key: string, value: unknown) => { if (key === 'retrieval') lastMeta = value as Record<string, any>; },
...overrides,
} as OperationContext;
}
const SESSION = Array.from({ length: 24 }, (_, i) =>
`**user:** question ${i} ${'about the renewal and the widget roadmap '.repeat(6)}\n\n**assistant:** reply ${i} ${'we discussed timelines and owners '.repeat(6)}${i === 13 ? ' the launch moved to march narwhal' : ''}`,
).join('\n\n');
const HANDBOOK = `## Overview\n\n${prose(rng(21), 6)}\n\n## Pricing\n\n${prose(rng(22), 6)} narwhal pricing note.\n\n## Support\n\n${prose(rng(23), 6)}`;
const codeFn = (name: string) => `export function ${name}(input: number): number {\n${Array.from({ length: 12 }, (_, i) => ` const step${i} = input * ${i + 2} + ${name.length};`).join('\n')}\n return input;\n}`;
// One prose chunk (index 0) holding the whole fence, then one fenced_code
// chunk per function (indices 1-3): a hit on index 2 or 3 has no prose chunk
// within return_window, and every code chunk carries a synthesized header.
const CODE_PAGE = `## Setup\n\nThe quokka service boots from this module.\n\n\`\`\`ts\n${codeFn('alpha')}\n\n${codeFn('beta')}\n\n${codeFn('gamma')}\n\`\`\`\n\nClosing prose about the quokka service.`;
const CHUNK_HEADER_LINE = /^\[[^\]]+\] fence\.\w+:\d+-\d+ /m;
beforeAll(async () => {
engine = new PGLiteEngine();
await engine.connect({});
await engine.initSchema();
for (const [slug, body] of [['chat/session-1', SESSION], ['notes/handbook', HANDBOOK], ['notes/quokka-code', CODE_PAGE]] as const) {
await engine.putPage(slug, { type: 'note', title: slug, compiled_truth: body, timeline: slug === 'notes/handbook' ? '- 2026-01-02 narwhal timeline entry' : '', frontmatter: {} });
await installFixtureChunks(engine, slug, await prepareMarkdownChunks({ compiled_truth: body, timeline: slug === 'notes/handbook' ? '- 2026-01-02 narwhal timeline entry' : '' }));
}
await engine.setConfig('search.mcp_keyword_only', 'true');
}, 240_000);
afterAll(async () => {
await engine.disconnect();
}, 240_000);
/** The retrieval meta with its per-call stage timings removed (they differ on every call; present on every one). */
function sansTimings(meta: Record<string, any> | null): Record<string, any> {
const { timings, ...rest } = meta ?? {};
expect(timings?.total_ms).toBeGreaterThanOrEqual(0);
return rest;
}
describe('ops', () => {
test('omitted return_unit with no conversation hit is exactly the chunk response', async () => {
lastMeta = null;
const rows = await op('search').handler(ctxOf(), { query: 'pricing' }) as SearchResult[];
expect(rows.length).toBeGreaterThan(0);
expect(rows.every(r => !r.slug.startsWith('chat/'))).toBe(true);
expect(rows.every(r => r.delivered === undefined)).toBe(true);
expect((lastMeta as Record<string, unknown> | null)?.delivery).toBeUndefined();
const offMeta = lastMeta;
const chunk = await op('search').handler(ctxOf(), { query: 'pricing', return_unit: 'chunk' }) as SearchResult[];
expect(JSON.stringify(rows)).toBe(JSON.stringify(chunk));
expect(JSON.stringify(sansTimings(offMeta))).toBe(JSON.stringify(sansTimings(lastMeta)));
});
test('omitted return_unit delivers conversation pages whole and keeps other hits as their chunks', async () => {
lastMeta = null;
const chunk = await op('search').handler(ctxOf(), { query: 'narwhal', return_unit: 'chunk' }) as SearchResult[];
const rows = await op('search').handler(ctxOf(), { query: 'narwhal' }) as SearchResult[];
expect(lastMeta!.delivery).toMatchObject({ requested_unit: 'auto', applied_unit: 'auto', budget_tokens: 24000 });
const chat = rows.find(r => r.slug === 'chat/session-1')!;
expect(chat.delivered).toMatchObject({ unit: 'page', reason: 'conversation_slug', truncated: false });
const [page] = await engine.executeRaw<{ compiled_truth: string; timeline: string }>('SELECT compiled_truth, timeline FROM pages WHERE id = $1', [chat.page_id]);
expect(chat.chunk_text).toBe(pageEvidenceText(page, true).text.trimEnd());
expect(rows.filter(r => r.slug === 'chat/session-1')).toHaveLength(1);
const others = rows.filter(r => r.slug !== 'chat/session-1');
expect(others.length).toBeGreaterThan(0);
expect(others.map(({ delivered, ...r }) => { expect(delivered).toMatchObject({ unit: 'chunk', reason: 'not_conversation' }); return r; }))
.toEqual(chunk.filter(r => r.slug !== 'chat/session-1'));
const typed = await op('search').handler(ctxOf(), { query: 'quokka' }) as SearchResult[];
expect(typed.every(r => r.delivered === undefined)).toBe(true);
});
test('auto detects conversations by type or slug, deterministically', () => {
const at = (type: string, slug: string) => conversationSignal({ type, slug });
for (const t of ['conversation', 'transcript', 'chat', 'meeting', 'slack', 'slack-thread', 'imessage', 'Conversation']) expect(at(t, 'notes/x')).toBe('conversation_type');
expect(at('note', 'chat/s-1')).toBe('conversation_slug');
expect(at('note', 'conversations/sessions/2026-01-01-codex-abc')).toBe('conversation_slug');
for (const [t, slug] of [['note', 'notes/chat'], ['email', 'emails/a'], ['code', 'src/chat.ts'], ['person', 'people/meeting-maker']]) expect(at(t, slug)).toBeNull();
});
test('query token_budget, recall budget_tokens/budget_policy and an explicit chunk keep the legacy chunk path under the auto default', async () => {
lastMeta = null;
await op('query').handler(ctxOf(), { query: 'narwhal', expand: false, token_budget: 900 });
expect(lastMeta!.delivery).toBeUndefined();
await op('search').handler(ctxOf(), { query: 'narwhal', return_unit: 'chunk' });
expect(lastMeta!.delivery).toBeUndefined();
const legacy = await op('recall').handler(ctxOf(), { query: 'narwhal', budget_tokens: 5000, budget_policy: 'query_first' }) as Record<string, any>;
expect(legacy.delivery).toBeUndefined();
const packed = await op('recall').handler(ctxOf(), { query: 'narwhal', budget_tokens: 5000 }) as Record<string, any>;
expect(packed.delivery).toBeUndefined();
const auto = await op('recall').handler(ctxOf(), { query: 'narwhal' }) as Record<string, any>;
expect(auto.delivery.requested_unit).toBe('auto');
expect(auto.results.find((r: Record<string, any>) => r.slug === 'chat/session-1').delivered).toMatchObject({ unit: 'page', reason: 'conversation_slug' });
await engine.setConfig('search.return_unit', 'chunk');
try {
await op('search').handler(ctxOf(), { query: 'narwhal' });
expect(lastMeta!.delivery).toBeUndefined();
} finally {
await engine.executeRaw(`DELETE FROM config WHERE key = 'search.return_unit'`);
}
});
test('auto keeps the subagent snippet economy, the remote cap and its own budget key', async () => {
const sub = await op('search').handler(ctxOf({ viaSubagent: true } as Partial<OperationContext>), { query: 'narwhal' }) as SearchResult[];
expect(sub.every(r => r.delivered === undefined && r.chunk_text.length <= 300 + 80)).toBe(true);
await op('search').handler(ctxOf({ remote: true }), { query: 'narwhal', token_budget: 90000 });
expect(lastMeta!.delivery).toMatchObject({ applied_unit: 'auto', budget_tokens: 32000, budget_clamped: { requested: 90000, max: 32000 } });
await engine.setConfig('search.return_budget_conversation', '40000');
try {
await op('search').handler(ctxOf({ remote: true }), { query: 'narwhal' });
expect(lastMeta!.delivery.budget_tokens).toBe(32000);
await op('search').handler(ctxOf(), { query: 'narwhal' });
expect(lastMeta!.delivery.budget_tokens).toBe(40000);
} finally {
await engine.executeRaw(`DELETE FROM config WHERE key = 'search.return_budget_conversation'`);
}
const capped = await op('search').handler(ctxOf(), { query: 'narwhal', snippet_chars: 120 }) as SearchResult[];
expect(capped.every(r => r.chunk_text.length <= 120 + 200)).toBe(true);
});
test('explain names each result\'s unit and the auto reason', async () => {
const rows = await op('search').handler(ctxOf(), { query: 'narwhal' }) as SearchResult[];
const text = formatResultsExplain(rows, { delivery: lastMeta!.delivery } as never);
expect(text).toContain('evidence: auto — ');
expect(text).toContain('evidence: page (conversation_slug)');
expect(text).toContain('evidence: chunk (not_conversation)');
});
test('every unit delivers through search with delivered + delivery meta', async () => {
for (const unit of ['window', 'section', 'page', 'auto']) {
lastMeta = null;
const rows = await op('search').handler(ctxOf(), { query: 'narwhal', return_unit: unit, token_budget: 4000 }) as SearchResult[];
expect(rows.length).toBeGreaterThan(0);
expect(lastMeta!.delivery.requested_unit).toBe(unit);
expect(lastMeta!.delivery.budget_used).toBeLessThanOrEqual(4000);
for (const r of rows) {
expect(r.delivered).toBeDefined();
for (const s of r.delivered!.match_spans) expect(s.end).toBeLessThanOrEqual(r.chunk_text.length);
}
}
});
test('page evidence is byte-identical to the stored body (sanitized), on the real import path', async () => {
const rows = await op('search').handler(ctxOf(), { query: 'narwhal', return_unit: 'page', token_budget: 32000 }) as SearchResult[];
expect(rows.length).toBeGreaterThan(0);
for (const r of rows) {
const [page] = await engine.executeRaw<{ compiled_truth: string; timeline: string }>('SELECT compiled_truth, timeline FROM pages WHERE id = $1', [r.page_id]);
expect(r.chunk_text).toBe(pageEvidenceText(page, true).text.trimEnd());
}
});
test('auto takes the page branch for a conversation stored as type note', async () => {
const rows = await op('search').handler(ctxOf(), { query: 'narwhal launch march', return_unit: 'auto', token_budget: 20000 }) as SearchResult[];
const chat = rows.find(r => r.slug === 'chat/session-1')!;
expect(chat.delivered!.unit).toBe('page');
expect(chat.chunk_text).toContain('question 0 ');
expect(chat.chunk_text).toContain('reply 23 ');
});
test('bad return_unit and return_window fail with invalid_params naming the fix', async () => {
await expect(op('search').handler(ctxOf(), { query: 'x', return_unit: 'paragraph' })).rejects.toMatchObject({
code: 'invalid_params', message: expect.stringContaining('chunk, window, section, page, auto'), suggestion: expect.stringContaining('"return_unit"'),
});
await expect(op('query').handler(ctxOf(), { query: 'x', return_unit: 'window', return_window: 7 })).rejects.toMatchObject({
code: 'invalid_params', message: 'return_window must be an integer from 1 to 3 (got 7).', suggestion: expect.stringContaining('"return_window": 2'),
});
});
test('detail low never adds timeline text', async () => {
const low = await op('query').handler(ctxOf(), { query: 'narwhal pricing', return_unit: 'page', detail: 'low', expand: false }) as SearchResult[];
const book = low.find(r => r.slug === 'notes/handbook')!;
expect(book.chunk_text).not.toContain('narwhal timeline entry');
const medium = await op('query').handler(ctxOf(), { query: 'narwhal pricing', return_unit: 'page', expand: false }) as SearchResult[];
expect(medium.find(r => r.slug === 'notes/handbook')!.chunk_text).toContain('narwhal timeline entry');
});
test('snippet precedence: explicit snippet_chars > explicit unit > subagent default > config unit', async () => {
const sub = ctxOf({ viaSubagent: true } as Partial<OperationContext>);
const capped = await op('search').handler(sub, { query: 'narwhal', return_unit: 'page', snippet_chars: 120 }) as SearchResult[];
expect(capped[0].chunk_text).toContain('[truncated');
expect(capped[0].delivered!.truncated).toBe(true);
expect(lastMeta!.delivery.fallbacks).toContain('snippet_cap');
const explicit = await op('search').handler(sub, { query: 'narwhal', return_unit: 'page' }) as SearchResult[];
expect(explicit[0].chunk_text).not.toContain('[truncated');
expect(explicit[0].chunk_text.length).toBeGreaterThan(300);
await engine.setConfig('search.return_unit', 'page');
try {
const subDefault = await op('search').handler(sub, { query: 'narwhal' }) as SearchResult[];
expect(subDefault[0].delivered).toBeUndefined();
expect(subDefault[0].chunk_text.length).toBeLessThanOrEqual(300 + 80);
const human = await op('search').handler(ctxOf(), { query: 'narwhal' }) as SearchResult[];
expect(human[0].delivered).toBeDefined();
} finally {
await engine.executeRaw(`DELETE FROM config WHERE key = 'search.return_unit'`);
}
});
test('remote budgets clamp to search.return_budget_max_remote and say so', async () => {
await op('search').handler(ctxOf({ remote: true }), { query: 'narwhal', return_unit: 'window', token_budget: 90000 });
expect(lastMeta!.delivery.budget_tokens).toBe(32000);
expect(lastMeta!.delivery.budget_clamped).toEqual({ requested: 90000, max: 32000 });
expect(lastMeta!.delivery.fallbacks).toContain('budget_clamped');
});
test('recall keeps legacy fields and packing, adding delivered/delivery only when on', async () => {
const off = await op('recall').handler(ctxOf(), { query: 'narwhal', budget_tokens: 5000, return_unit: 'chunk' }) as Record<string, any>;
expect(off.delivery).toBeUndefined();
// #4830: `source_id` joined the pinned key list (additive; every hit names the source it came from).
expect(off.results.every((r: Record<string, unknown>) => Object.keys(r).join(',') === 'slug,title,chunk,evidence,create_safety,provenance,source_id,trust_tier,origin')).toBe(true);
const on = await op('recall').handler(ctxOf(), { query: 'narwhal', budget_tokens: 5000, return_unit: 'page' }) as Record<string, any>;
expect(on.delivery.requested_unit).toBe('page');
expect(on.results[0].delivered.unit).toBe('page');
expect(on.results[0].chunk.length).toBeGreaterThan(off.results[0].chunk.length);
expect(on.budget_used).toBeLessThanOrEqual(5000);
});
test('query token_budget budgets the delivered evidence', async () => {
const rows = await op('query').handler(ctxOf(), { query: 'narwhal', return_unit: 'page', token_budget: 900, expand: false }) as SearchResult[];
expect(lastMeta!.delivery.budget_tokens).toBe(900);
expect(lastMeta!.delivery.budget_used).toBeLessThanOrEqual(900);
expect(rows.length).toBeGreaterThan(0);
});
test('assemble_evidence returns the same evidence as search for the same hits', async () => {
const hits = await op('search').handler(ctxOf(), { query: 'narwhal' }) as SearchResult[];
const viaSearch = await op('search').handler(ctxOf(), { query: 'narwhal', return_unit: 'section', token_budget: 3000 }) as SearchResult[];
const out = await op('assemble_evidence').handler(ctxOf(), {
hits: hits.map(h => ({ source_id: h.source_id, slug: h.slug, chunk_id: h.chunk_id })), return_unit: 'section', token_budget: 3000,
}) as { results: SearchResult[]; unresolved: number[] };
expect(out.unresolved).toEqual([]);
expect(evidenceFingerprint(out.results)).toBe(evidenceFingerprint(viaSearch));
const bad = await op('assemble_evidence').handler(ctxOf(), { hits: [{ source_id: 'nope', slug: 'chat/session-1', chunk_id: 1 }], return_unit: 'page' }) as { unresolved: number[] };
expect(bad.unresolved).toEqual([0]);
});
test('malformed assemble_evidence hits name the parameter in the caller\'s own syntax', async () => {
await expect(op('assemble_evidence').handler(ctxOf(), { hits: 'chat/session-1' })).rejects.toMatchObject({
code: 'invalid_params', suggestion: expect.stringContaining('Pass --hits as a array'),
});
await expect(op('assemble_evidence').handler(ctxOf({ remote: true, transport: 'stdio' }), { hits: [{ slug: 'chat/session-1' }] })).rejects.toMatchObject({
code: 'invalid_params', suggestion: expect.stringContaining('assemble_evidence {"hits": [{"source_id":"default","slug":"chat/session-0412","chunk_id":8812}]}'),
});
await expect(assembleEvidenceForHits(engine, { hits: 'x' as never, return_unit: 'page' })).rejects.toMatchObject({ code: 'invalid_params', suggestion: expect.stringContaining('"chunk_id": 12') });
});
test('a fenced-code best hit delivers the page text for return_unit page, not the code chunk', async () => {
const [page] = await engine.executeRaw<{ compiled_truth: string; timeline: string }>(`SELECT compiled_truth, timeline FROM pages WHERE slug = 'notes/quokka-code'`);
const code = await engine.executeRaw<{ id: number; chunk_index: number; chunk_text: string }>(
`SELECT cc.id, cc.chunk_index, cc.chunk_text FROM content_chunks cc JOIN pages p ON p.id = cc.page_id WHERE p.slug = 'notes/quokka-code' AND cc.chunk_source = 'fenced_code' ORDER BY cc.chunk_index`);
expect(code.map(c => c.chunk_index)).toEqual([1, 2, 3]);
const text = pageEvidenceText(page, true).text;
for (const c of code) {
const out = await op('assemble_evidence').handler(ctxOf(), {
hits: [{ source_id: 'default', slug: 'notes/quokka-code', chunk_id: c.id }], return_unit: 'page', token_budget: 32000,
}) as { results: SearchResult[]; delivery: { fallbacks: string[] } };
const [r] = out.results;
expect(r.delivered!.unit, `chunk_index ${c.chunk_index}`).toBe('page');
expect(r.delivered!.fallback_reason).toBeUndefined();
expect(r.delivered!.unmapped_chunk_ids).toBeUndefined();
expect(r.chunk_text).toBe(text.trimEnd());
const [span] = r.delivered!.match_spans;
expect(span.chunk_id).toBe(c.id);
expect(norm(r.chunk_text.slice(span.start, span.end))).toBe(norm(c.chunk_text.replace(/^[^\n]*\n\n/, '')));
}
});
test('fenced-code evidence never carries the chunker header, in any expanding unit or fallback', async () => {
const [page] = await engine.executeRaw<{ compiled_truth: string; timeline: string }>(`SELECT compiled_truth, timeline FROM pages WHERE slug = 'notes/quokka-code'`);
const text = pageEvidenceText(page, true).text;
const code = await engine.executeRaw<{ id: number }>(
`SELECT cc.id FROM content_chunks cc JOIN pages p ON p.id = cc.page_id WHERE p.slug = 'notes/quokka-code' AND cc.chunk_source = 'fenced_code'`);
for (const unit of ['window', 'section', 'page']) {
for (const budget of [32000, 60]) {
const out = await op('assemble_evidence').handler(ctxOf(), {
hits: code.map(c => ({ source_id: 'default', slug: 'notes/quokka-code', chunk_id: c.id })), return_unit: unit, token_budget: budget,
}) as { results: SearchResult[] };
for (const r of out.results) {
expect(r.chunk_text, `${unit}/${budget}`).not.toMatch(CHUNK_HEADER_LINE);
for (const seg of r.chunk_text.split(EVIDENCE_OMISSION)) expect(text.includes(seg), `${unit}/${budget}: ${seg.slice(0, 60)}`).toBe(true);
}
}
}
// auto leaves a non-conversation page on the chunk path: the ranked rows, unchanged.
const auto = await op('assemble_evidence').handler(ctxOf(), {
hits: code.map(c => ({ source_id: 'default', slug: 'notes/quokka-code', chunk_id: c.id })), return_unit: 'auto',
}) as { results: SearchResult[] };
expect(auto.results.map(r => r.delivered!.reason)).toEqual(['not_conversation', 'not_conversation', 'not_conversation']);
const plain = await op('assemble_evidence').handler(ctxOf(), {
hits: code.map(c => ({ source_id: 'default', slug: 'notes/quokka-code', chunk_id: c.id })), return_unit: 'chunk',
}) as { results: SearchResult[] };
expect(auto.results.map(r => r.chunk_text)).toEqual(plain.results.map(r => r.chunk_text));
const hits = await op('search').handler(ctxOf(), { query: 'quokka' }) as SearchResult[];
const codeHit = { ...hits.find(h => h.slug === 'notes/quokka-code')!, chunk_id: code[1].id, chunk_index: 2, chunk_source: 'fenced_code' as const,
chunk_text: (await engine.executeRaw<{ chunk_text: string }>('SELECT chunk_text FROM content_chunks WHERE id = $1', [code[1].id]))[0].chunk_text };
expect(codeHit.chunk_text).toMatch(CHUNK_HEADER_LINE);
const failing = { getChunkWindows: async () => { throw new Error('synthetic fetch failure'); } } as unknown as BrainEngine;
const fallback = await deliverEvidence(failing, [codeHit], planOf('page', 5000), {});
expect(fallback.results[0].delivered).toMatchObject({ unit: 'chunk', fallback_reason: 'fetch_failed' });
expect(fallback.results[0].chunk_text).not.toMatch(CHUNK_HEADER_LINE);
expect(text.includes(fallback.results[0].chunk_text)).toBe(true);
});
test('think renders delivered blocks whole under think.return_unit, and only then', async () => {
const prompts: string[] = [];
const client = { create: async (params: { messages: Array<{ content: unknown }> }) => {
prompts.push(JSON.stringify(params.messages));
return { content: [{ type: 'text', text: '{"answer":"ok","citations":[],"gaps":[]}' }], usage: { input_tokens: 1, output_tokens: 1 } };
} };
const auto = await runThink(engine, { question: 'narwhal launch march', client: client as never, remote: false });
expect(prompts[0]).toContain('reply 23 ');
expect(auto.evidence_delivery?.requested_unit).toBe('auto');
await engine.setConfig('think.return_unit', 'chunk');
try {
await runThink(engine, { question: 'narwhal launch march', client: client as never, remote: false });
expect(prompts[1]).not.toContain('reply 23 ');
await engine.setConfig('search.return_unit', 'chunk');
await engine.setConfig('think.return_unit', 'page');
const r = await runThink(engine, { question: 'narwhal launch march', client: client as never, remote: false });
expect(prompts[2]).toContain('reply 23 ');
expect(r.evidence_delivery?.requested_unit).toBe('page');
} finally {
await engine.executeRaw(`DELETE FROM config WHERE key IN ('search.return_unit', 'think.return_unit')`);
}
});
test('renderPagesBlock verbatim mode passes delivered text through', () => {
const text = 'x'.repeat(5000);
const block = renderPagesBlock([{ slug: 'a/b', chunk_text: text } as SearchResult], 60000, 'q', { verbatim: true });
expect(block).toContain(text);
});
test('explicit budgets below the minimum are refused through query, search, recall and assemble_evidence; a bare query budget stays legacy chunk (G7)', async () => {
const msg = (name: string) => expect.stringContaining(`${name} must be at least ${MIN_EXPLICIT_AUTO_BUDGET} tokens under return_unit auto`);
await expect(op('query').handler(ctxOf(), { query: 'narwhal', return_unit: 'auto', token_budget: 10, expand: false })).rejects.toMatchObject({ code: 'invalid_params', message: msg('token_budget') });
await expect(op('search').handler(ctxOf(), { query: 'narwhal', token_budget: 5 })).rejects.toMatchObject({ code: 'invalid_params', message: msg('token_budget') });
await expect(op('recall').handler(ctxOf(), { query: 'narwhal', return_unit: 'auto', budget_tokens: 3 })).rejects.toMatchObject({ code: 'invalid_params', message: msg('budget_tokens') });
await expect(op('assemble_evidence').handler(ctxOf(), { hits: [{ source_id: 'default', slug: 'chat/session-1', chunk_id: 0 }], return_unit: 'auto', token_budget: 0 }))
.rejects.toMatchObject({ code: 'invalid_params', message: msg('token_budget') });
lastMeta = null;
const bare = await op('query').handler(ctxOf(), { query: 'narwhal', token_budget: 10, expand: false }) as SearchResult[];
expect(lastMeta!.delivery).toBeUndefined();
expect(bare.every(r => r.delivered === undefined)).toBe(true);
});
test('an explicit budget caps query, search, recall and assemble_evidence at the final boundary, snippet markers included', async () => {
const rowsCost = (rows: Array<{ title?: string; chunk_text: string }>) => recount(rows);
for (const budget of [MIN_EXPLICIT_AUTO_BUDGET, 60, 400, 3000]) {
const viaQuery = await op('query').handler(ctxOf(), { query: 'narwhal', return_unit: 'auto', token_budget: budget, expand: false }) as SearchResult[];
expect(lastMeta!.delivery).toMatchObject({ auto_packing: 'cap_only', budget_tokens: budget });
expect(rowsCost(viaQuery), `query @${budget}`).toBeLessThanOrEqual(budget);
expect(lastMeta!.delivery.budget_used).toBe(rowsCost(viaQuery));
const viaSearch = await op('search').handler(ctxOf(), { query: 'narwhal', token_budget: budget }) as SearchResult[];
expect(rowsCost(viaSearch), `search @${budget}`).toBeLessThanOrEqual(budget);
for (const snippet of [10, 40, 120]) {
const capped = await op('query').handler(ctxOf(), { query: 'narwhal', return_unit: 'auto', token_budget: budget, snippet_chars: snippet, expand: false }) as SearchResult[];
expect(rowsCost(capped), `query @${budget} snippet ${snippet}`).toBeLessThanOrEqual(budget);
expect(lastMeta!.delivery.budget_used).toBe(rowsCost(capped));
expect(lastMeta!.delivery.tokens_delivered).toBe(capped.reduce((n, r) => n + countEvidenceTokens(r.chunk_text), 0));
}
const recall = await op('recall').handler(ctxOf(), { query: 'narwhal', return_unit: 'auto', budget_tokens: budget }) as Record<string, any>;
expect(recall.delivery.auto_packing).toBe('cap_only');
expect(recall.delivery.budget_used).toBeLessThanOrEqual(budget);
const hits = await op('query').handler(ctxOf(), { query: 'narwhal', return_unit: 'chunk', expand: false }) as SearchResult[];
const assembled = await op('assemble_evidence').handler(ctxOf(), {
hits: hits.map(h => ({ source_id: h.source_id, slug: h.slug, chunk_id: h.chunk_id })), return_unit: 'auto', token_budget: budget,
}) as { results: SearchResult[]; delivery: { budget_used: number } };
expect(rowsCost(assembled.results), `assemble @${budget}`).toBeLessThanOrEqual(budget);
expect(assembled.delivery.budget_used).toBe(rowsCost(assembled.results));
}
// The remote clamp: the cap applies to the clamped value.
const remote = await op('search').handler(ctxOf({ remote: true }), { query: 'narwhal', token_budget: 90000, fields: 'full' }) as SearchResult[];
expect(lastMeta!.delivery).toMatchObject({ budget_tokens: 32000, budget_clamped: { requested: 90000, max: 32000 }, auto_packing: 'cap_only' });
expect(rowsCost(remote)).toBeLessThanOrEqual(32000);
});
test('search.auto_packing selects the packing; the library override wins per call; neither touches a call without a budget', async () => {
const baseline = async () => {
const out: string[] = [];
out.push(JSON.stringify(await op('search').handler(ctxOf(), { query: 'narwhal' })), JSON.stringify(sansTimings(lastMeta)));
out.push(JSON.stringify(await op('query').handler(ctxOf(), { query: 'narwhal', expand: false })), JSON.stringify(sansTimings(lastMeta)));
out.push(JSON.stringify(await op('query').handler(ctxOf(), { query: 'narwhal', return_unit: 'auto', expand: false })), JSON.stringify(sansTimings(lastMeta)));
out.push(JSON.stringify(await op('recall').handler(ctxOf(), { query: 'narwhal' })));
const hits = await op('search').handler(ctxOf(), { query: 'narwhal', return_unit: 'chunk' }) as SearchResult[];
out.push(JSON.stringify(await op('assemble_evidence').handler(ctxOf(), { hits: hits.map(h => ({ source_id: h.source_id, slug: h.slug, chunk_id: h.chunk_id })), return_unit: 'auto' })));
return out;
};
const today = await baseline();
try {
for (const packing of AUTO_PACKINGS) {
await engine.setConfig('search.auto_packing', packing);
expect(await baseline(), packing).toEqual(today);
await op('query').handler(ctxOf(), { query: 'narwhal', return_unit: 'auto', token_budget: 3000, expand: false });
if (packing === 'off') expect(lastMeta!.delivery.auto_packing).toBeUndefined();
else expect(lastMeta!.delivery.auto_packing).toBe(packing);
}
await engine.setConfig('search.auto_packing', 'depth_first');
const hits = await op('search').handler(ctxOf(), { query: 'narwhal', return_unit: 'chunk' }) as SearchResult[];
const frozen = hits.map(h => ({ source_id: h.source_id!, slug: h.slug, chunk_id: h.chunk_id }));
for (const packing of AUTO_PACKINGS) {
const out = await assembleEvidenceForHits(engine, { hits: frozen, return_unit: 'auto', budget_tokens: 3000, auto_packing: packing });
expect(out.delivery!.auto_packing).toBe(packing === 'off' ? undefined : packing);
}
await expect(assembleEvidenceForHits(engine, { hits: frozen, return_unit: 'auto', budget_tokens: 3000, auto_packing: 'widest' as never }))
.rejects.toMatchObject({ code: 'invalid_params' });
} finally {
await engine.executeRaw(`DELETE FROM config WHERE key = 'search.auto_packing'`);
}
// An explicit 24,000 and the implied 24,000 resolve to plans that differ only in the flag.
const resolve = (budget: unknown) => resolveEvidencePlan(engine, { remote: false, returnUnit: 'auto', returnWindow: undefined, budget, snippetChars: undefined, snippetCap: 0, op: 'search' });
const [explicit, implied] = [await resolve(24000), await resolve(undefined)];
expect({ ...explicit!, budgetExplicit: false }).toEqual(implied!);
expect(explicit!.budgetExplicit).toBe(true);
});
test('think passes no budget, so its prompt is the same under every packing', async () => {
const prompts: string[] = [];
const client = { create: async (params: { messages: Array<{ content: unknown }> }) => {
prompts.push(JSON.stringify(params.messages));
return { content: [{ type: 'text', text: '{"answer":"ok","citations":[],"gaps":[]}' }], usage: { input_tokens: 1, output_tokens: 1 } };
} };
try {
for (const packing of AUTO_PACKINGS) {
await engine.setConfig('search.auto_packing', packing);
await runThink(engine, { question: 'narwhal launch march', client: client as never, remote: false, reference_date: '2026-10-09' } as never);
}
} finally {
await engine.executeRaw(`DELETE FROM config WHERE key = 'search.auto_packing'`);
}
expect(new Set(prompts).size).toBe(1);
});
test('frozen-hit delivery carries effective_date, and every field a reader consumes equals live query (both packings and today\'s auto)', async () => {
await engine.executeRaw(`UPDATE pages SET effective_date = '2026-03-04', effective_date_source = 'frontmatter' WHERE slug = 'chat/session-1'`);
try {
const hits = await op('query').handler(ctxOf(), { query: 'narwhal', return_unit: 'chunk', expand: false }) as SearchResult[];
expect(lastMeta!.delivery).toBeUndefined();
const frozen = hits.map(h => ({ source_id: h.source_id!, slug: h.slug, chunk_id: h.chunk_id }));
const consumed = (rows: SearchResult[]) => rows.map(r => ({
slug: r.slug, title: r.title, chunk_text: r.chunk_text, effective_date: r.effective_date, effective_date_source: r.effective_date_source,
unit: r.delivered?.unit, spans: r.delivered?.match_spans, tokens: r.delivered?.tokens, truncated: r.delivered?.truncated, reason: r.delivered?.reason,
fallback: r.delivered?.fallback_reason, unmapped: r.delivered?.unmapped_chunk_ids,
}));
const totals = (d: Record<string, any>) => ({ budget_used: d.budget_used, tokens_delivered: d.tokens_delivered, fallbacks: d.fallbacks, dropped_reasons: d.dropped_reasons, auto_packing: d.auto_packing });
let dated = 0;
for (const packing of AUTO_PACKINGS) {
await engine.setConfig('search.auto_packing', packing);
for (const budget of [400, 3000, undefined]) {
const live = await op('query').handler(ctxOf(), { query: 'narwhal', return_unit: 'auto', expand: false, ...(budget ? { token_budget: budget } : {}) }) as SearchResult[];
const liveDelivery = lastMeta!.delivery;
const assembled = await assembleEvidenceForHits(engine, { hits: frozen, return_unit: 'auto', ...(budget ? { budget_tokens: budget } : {}) });
expect(consumed(assembled.results as SearchResult[]), `${packing} @${budget}`).toEqual(consumed(live));
expect(totals(assembled.delivery!)).toEqual(totals(liveDelivery));
expect(evidenceFingerprint(assembled.results)).toBe(evidenceFingerprint(live));
for (const r of assembled.results.filter(x => x.slug === 'chat/session-1')) { expect(r.effective_date).toBe('2026-03-04'); dated++; }
// A page with no date reads null on both paths, never an invented date.
for (const r of assembled.results.filter(x => x.slug !== 'chat/session-1')) expect(r.effective_date).toBeNull();
}
}
expect(dated).toBeGreaterThan(0);
} finally {
await engine.executeRaw(`UPDATE pages SET effective_date = NULL, effective_date_source = NULL WHERE slug = 'chat/session-1'`);
await engine.executeRaw(`DELETE FROM config WHERE key = 'search.auto_packing'`);
}
});
test('thin-client skew warning fires only when the server dropped delivery', () => {
expect(deliveryVersionSkewWarning('query', { return_unit: 'page' }, { returned_count: 1 }, [])).toContain('v0.60.13.0');
expect(deliveryVersionSkewWarning('query', { return_unit: 'page' }, { delivery: {} }, [])).toBeNull();
expect(deliveryVersionSkewWarning('query', { return_unit: 'chunk' }, {}, [])).toBeNull();
expect(deliveryVersionSkewWarning('recall', { return_unit: 'page' }, null, { facts: [] })).toContain('ignored return_unit');
});
});