dsh-context-compression-improved 0.4.0-beta.1 → 0.5.0

package/packages/selector/tests/runtime/sidechannel.spec.ts

@@ -0,0 +1,241 @@
+import { describe, expect, it } from 'vitest'
+import { codePointLength } from '../../src/runtime/config.ts'
+import {
+  documentSectionSummaries,
+  reduceFreshToolResult,
+  searchNodeSummaries,
+  type ReducerInput,
+} from '../../src/runtime/reducers.ts'
+import {
+  buildRankUserPrompt,
+  mergeRanking,
+  parseRanking,
+  rankNodes,
+  sideChannelGate,
+  type RankedNode,
+} from '../../src/runtime/tokenpilot/sidechannel.ts'
+
+const SOURCE_REF = 'session://s1/event/9'
+
+function input(text: string, budgetChars = 4_000): ReducerInput {
+  return {
+    toolName: 'grep_search',
+    argumentsText: '{"pattern":"config"}',
+    text,
+    budgetChars,
+    sourceRef: SOURCE_REF,
+    isError: false,
+  }
+}
+
+function stubChannel(answer: string | undefined, calls: { count: number }): Pick<{ ask: unknown }, never> & {
+  ask: (request: { system: string, user: string, signal: AbortSignal }) => Promise<string | undefined>
+  askAudited: (request: { system: string, user: string, signal: AbortSignal }) => Promise<{ text?: string, audit: { ok: boolean, latencyMs: number } }>
+  identity: () => string | undefined
+} {
+  return {
+    async ask(request) {
+      calls.count += 1
+      void request
+      return answer
+    },
+    async askAudited(request) {
+      const text = await this.ask(request)
+      return { ...(text === undefined ? {} : { text }), audit: { ok: text !== undefined, latencyMs: 1 } }
+    },
+    identity: () => 'stub',
+  }
+}
+
+describe('rank parsing and merging (TS4)', () => {
+  it('keeps only valid identifiers in returned order', () => {
+    const ranked = parseRanking('b.ts, junk, a.ts, b.ts', new Set(['a.ts', 'b.ts']))
+    expect(ranked).toEqual(['b.ts', 'a.ts'])
+  })
+  it('resolves undefined for empty or garbage answers (fail-open)', () => {
+    expect(parseRanking(undefined, new Set(['a.ts']))).toBeUndefined()
+    expect(parseRanking('   ', new Set(['a.ts']))).toBeUndefined()
+    expect(parseRanking('I cannot rank these files', new Set(['a.ts']))).toBeUndefined()
+  })
+  it('appends unmentioned nodes in their original order (existence intact)', () => {
+    const nodes = [{ id: 'a' }, { id: 'b' }, { id: 'c' }]
+    expect(mergeRanking(nodes, ['c'])).toEqual([{ id: 'c' }, { id: 'a' }, { id: 'b' }])
+    expect(mergeRanking(nodes, undefined)).toEqual(nodes)
+  })
+})
+
+describe('cost gate (R-10)', () => {
+  it('does not call when everything fits or there is a single node', () => {
+    expect(sideChannelGate(true, 500)).toBe(false)
+    expect(sideChannelGate(false, 1)).toBe(false)
+    expect(sideChannelGate(false, 2)).toBe(true)
+  })
+})
+
+describe('node summaries (SC8: samples ride with identifiers)', () => {
+  it('search summaries carry path, count, and one content line', () => {
+    const text = ['a.ts:1: alpha config', 'a.ts:2: beta', 'b.ts:7: gamma'].join('\n')
+    const nodes = searchNodeSummaries(text)
+    expect(nodes).toHaveLength(2)
+    const a = nodes.find(node => node.id === 'a.ts')!
+    expect(a.count).toBe(2)
+    expect(a.sample).toContain('alpha config')
+  })
+  it('document summaries carry heading, mass, and the first content line (not only titles)', () => {
+    const text = [
+      '# Guide',
+      'Intro sentence everyone should read.',
+      '## Configuration',
+      ...Array.from({ length: 20 }, (_, i) => `config line ${String(i)}`),
+    ].join('\n')
+    const sections = documentSectionSummaries(text)
+    expect(sections).toHaveLength(2)
+    const config = sections.find(section => section.id === 'Configuration')!
+    expect(config.level).toBe(2)
+    expect(config.chars).toBeGreaterThan(100)
+    expect(config.sample).toContain('config line 0')
+  })
+  it('the rank prompt embeds query, reasoning, and samples (AD11 intent carrier)', () => {
+    const nodes: RankedNode[] = [{ id: 'a.ts', detail: '2 hits', sample: 'alpha config line' }]
+    const prompt = buildRankUserPrompt(nodes, 'find loading config', 'the user wants the config loader')
+    expect(prompt).toContain('query: find loading config')
+    expect(prompt).toContain('reasoning: the user wants the config loader')
+    expect(prompt).toContain('a.ts | 2 hits | alpha config line')
+  })
+})
+
+describe('S1a ranked search fold', () => {
+  const rows = [
+    ...Array.from({ length: 40 }, (_, i) => `fat.ts:${String(i + 1)}: fat row ${String(i)}`),
+    ...Array.from({ length: 40 }, (_, i) => `star.ts:${String(i + 1)}: star row ${String(i)}`),
+  ]
+
+  it('ranked file fills L2 first while L1 stays complete (existence lossless)', () => {
+    const tight = input(rows.join('\n'), 1_500)
+    const mechanical = reduceFreshToolResult(tight)!
+    const ranked = reduceFreshToolResult(tight, { files: ['star.ts'] })!
+    expect(ranked.reducer).toBe('search-by-file')
+    // L1 locator sets survive untouched for both files.
+    const locatorOf = (text: string, path: string): string | undefined =>
+      text.split('\n').find(line => line.startsWith(`## ${path}`))
+    for (const text of [mechanical.text, ranked.text]) {
+      expect(locatorOf(text, 'fat.ts')!.match(/L\d+/gu)).toHaveLength(40)
+      expect(locatorOf(text, 'star.ts')!.match(/L\d+/gu)).toHaveLength(40)
+    }
+    // Ranking only changes which rows the quota shows first.
+    const countRows = (text: string, path: string): number =>
+      text.split('\n').filter(line => line.startsWith(`${path}:`)).length
+    expect(countRows(ranked.text, 'star.ts')).toBeGreaterThanOrEqual(countRows(mechanical.text, 'star.ts'))
+  })
+
+  it('counter-proof: no ranking reproduces the mechanical output byte-for-byte', () => {
+    const tight = input(rows.join('\n'), 1_500)
+    const mechanical = reduceFreshToolResult(tight)!.text
+    expect(reduceFreshToolResult(tight, {})!.text).toBe(mechanical)
+    expect(reduceFreshToolResult(tight, { files: [] })!.text).toBe(mechanical)
+  })
+
+  it('an LM ranking with unknown paths changes nothing', () => {
+    const tight = input(rows.join('\n'), 1_500)
+    const mechanical = reduceFreshToolResult(tight)!.text
+    expect(reduceFreshToolResult(tight, { files: ['nope.ts'] })!.text).toBe(mechanical)
+  })
+})
+
+describe('S1b ranked document fold', () => {
+  function doc(): string {
+    const parts: string[] = ['# Guide', 'Intro line.']
+    for (const [name, size] of [['Small', 6] as const, ['Target Section', 40] as const, ['Appendix', 30] as const]) {
+      parts.push(`## ${name}`)
+      parts.push(...Array.from({ length: size }, (_, i) => `${name} body line ${String(i)} with ordinary prose.`))
+    }
+    return parts.join('\n')
+  }
+
+  function docInput(budget: number): ReducerInput {
+    return { ...input(doc(), budget), toolName: 'mcp_fetch' }
+  }
+
+  it('selected section keeps full content; unselected keep heading plus first line', () => {
+    const budget = 4_000
+    const ranked = reduceFreshToolResult(docInput(budget), { sections: ['Target Section'] })
+    expect(ranked).not.toBeNull()
+    expect(ranked!.reducer).toBe('doc-skeleton')
+    const text = ranked!.text
+    // All headings survive (existence is never the channel's to remove).
+    for (const heading of ['Guide', 'Small', 'Target Section', 'Appendix']) {
+      expect(text).toContain(heading)
+    }
+    // Selected: full content fits. Unselected: first line only.
+    expect(text).toContain('Target Section body line 39')
+    expect(text).not.toContain('Appendix body line 29')
+    expect(text).toContain('Appendix body line 0')
+    expect(codePointLength(text)).toBeLessThanOrEqual(budget)
+  })
+
+  it('fills the ranked section partially when the budget cannot hold it whole', () => {
+    const tight = reduceFreshToolResult(docInput(1_600), { sections: ['Target Section'] })!
+    expect(codePointLength(tight.text)).toBeLessThanOrEqual(1_600)
+    // More than the first-line floor of the ranked section survives.
+    expect(tight.text.split('\n').filter(line => line.startsWith('Target Section body line')).length).toBeGreaterThan(1)
+    // Unselected sections still show their first line (mechanical floor).
+    expect(tight.text).toContain('Appendix body line 0')
+  })
+
+  it('counter-proof: no ranking reproduces the mechanical skeleton byte-for-byte', () => {
+    const budget = 1_600
+    const mechanical = reduceFreshToolResult(docInput(budget))!.text
+    expect(reduceFreshToolResult(docInput(budget), { sections: [] })!.text).toBe(mechanical)
+  })
+})
+
+describe('S1 orchestrator', () => {
+  it('makes exactly ONE call and applies the ranking', async () => {
+    const calls = { count: 0 }
+    const channel = stubChannel('b.ts, a.ts', calls)
+    const outcome = await rankNodes(
+      [
+        { id: 'a.ts', detail: '3 hits', sample: 'alpha' },
+        { id: 'b.ts', detail: '9 hits', sample: 'beta' },
+      ],
+      new Set(['a.ts', 'b.ts']),
+      'find the loader',
+      'wants config loading',
+      channel,
+      AbortSignal.timeout(1_000),
+    )
+    expect(calls.count).toBe(1)
+    expect(outcome.ranking).toEqual(['b.ts', 'a.ts'])
+    expect(outcome.audit.ok).toBe(true)
+  })
+  it('falls back with an audit record when the channel returns nothing', async () => {
+    const calls = { count: 0 }
+    const outcome = await rankNodes(
+      [
+        { id: 'a.ts', detail: '3 hits', sample: 'alpha' },
+        { id: 'b.ts', detail: '9 hits', sample: 'beta' },
+      ],
+      new Set(['a.ts', 'b.ts']),
+      'find the loader',
+      undefined,
+      stubChannel(undefined, calls),
+      AbortSignal.timeout(1_000),
+    )
+    expect(outcome.ranking).toBeUndefined()
+    expect(outcome.audit.ok).toBe(false)
+    expect(outcome.audit.reason).toContain('falling back')
+  })
+  it('gate stays closed for a single node or an empty query (zero calls)', async () => {
+    const calls = { count: 0 }
+    const outcome = await rankNodes(
+      [{ id: 'a.ts', detail: '3 hits', sample: 'alpha' }],
+      new Set(['a.ts']),
+      'find the loader',
+      undefined,
+      stubChannel('a.ts', calls),
+      AbortSignal.timeout(1_000),
+    )
+    expect(calls.count).toBe(0)
+    expect(outcome.ranking).toBeUndefined()
+  })
+})

package/packages/selector/tests/runtime/toc-and-bundled.spec.ts

@@ -0,0 +1,159 @@
+import { describe, expect, it } from 'vitest'
+import {
+  historicalPlaceholder,
+  looksLikeMinified,
+  looksLikeDocument,
+  reduceFreshToolResult,
+  type ReducerInput,
+} from '../../src/runtime/reducers.ts'
+
+const input = (overrides: Partial<ReducerInput> & Pick<ReducerInput, 'text'>): ReducerInput => ({
+  toolName: overrides.toolName ?? 'read',
+  argumentsText: overrides.argumentsText ?? '{}',
+  text: overrides.text,
+  budgetChars: overrides.budgetChars ?? 4_000,
+  sourceRef: overrides.sourceRef ?? 'session://probe/event/1',
+  isError: overrides.isError ?? false,
+  ...(overrides.codeSkeleton === undefined ? {} : { codeSkeleton: overrides.codeSkeleton }),
+})
+
+/** task_4b (G6): a large read-class result must present its skeleton (the
+ *  natural table of contents) instead of head-only truncation, WITHOUT the
+ *  orthogonal `codeSkeleton` user gate. Acceptance: the first step carries
+ *  structure lines/headings and NO head boilerplate, and every elision marker
+ *  is line-addressable via start_line. */
+describe('TOC-first for large read results (task_4b)', () => {
+  const sourceLines = [
+    'import { a } from "./a.ts"',
+    'import { b } from "./b.ts"',
+    'import { c } from "./c.ts"',
+    ...Array.from({ length: 60 }, (_, index) => [
+      `export function handler${String(index)}(value: number): number {`,
+      // Body lines must be UNIQUE across handlers — exact repeats fold in the
+      // normalizer (R11), which would shrink the content view below the
+      // TOC threshold and change the dispatch this suite pins.
+      ...Array.from({ length: 40 }, (_, line) => `  value += ${String(line)}; // handler ${String(index)} padded body line`),
+      '  return value',
+      '}',
+    ]).flat(),
+  ]
+  const guttered = sourceLines.map((line, index) => `${String(index + 1)}: ${line}`).join('\n')
+
+  it('skeletons a large guttered read without the codeSkeleton gate', () => {
+    const output = reduceFreshToolResult(input({ text: guttered, budgetChars: 8_000 }))
+    expect(output).not.toBeNull()
+    expect(output!.reducer).toBe('hypa-code-skeleton')
+    // task_4c/G7: the elided-line count rides the structured telemetry for the
+    // audit record — never printed into the replacement text.
+    expect(output!.elidedLines).toBeGreaterThan(0)
+    expect(output!.text).not.toContain('elided_lines')
+    // Structure lines survive (the directory)…
+    expect(output!.text).toContain('export function handler0(')
+    // …while the head-of-file boilerplate does NOT dominate the first step.
+    expect(output!.text).not.toContain('value += 0; // handler 0 padded body line')
+  })
+
+  it('keeps every elision marker line-addressable (start_line present)', () => {
+    const output = reduceFreshToolResult(input({ text: guttered, budgetChars: 8_000 }))
+    expect(output!.text).toMatch(/\[... lines \d+-\d+ elided \(\d+ lines\) ...\]/)
+    expect(output!.text).toContain('start_line')
+    // The host continuation footer is never dropped by the envelope.
+    expect(output!.text).not.toBe('')
+  })
+
+  it('reports the whole original span as elided for aged placeholders (task_4c)', () => {
+    const text = ['line one', 'line two', 'line three', 'line four', 'line five'].join('\n')
+    const placeholder = historicalPlaceholder({
+      toolName: 'read',
+      sourceRef: 'session://probe/aged',
+      charsBefore: text.length,
+      isError: false,
+      text,
+    })
+    expect(placeholder.reducer).toBe('historical-tool-result-aging')
+    expect(placeholder.elidedLines).toBe(5)
+  })
+
+  it('degrades to head/tail when the skeleton is mostly elision markers', () => {
+    // Code-shaped (structure + import evidence) but structurally POOR: 20
+    // tiny `fn` signatures each followed by 100 unique filler lines → the
+    // skeleton output is dominated by elision markers, so the TOC guard must
+    // fail open and the result must land on the prose/head pair.
+    const flat = [
+      'use crate::a;',
+      'use crate::b;',
+      'use crate::c;',
+      ...Array.from({ length: 20 }, (_, index) => [
+        `fn fx${String(index)}(v: u32) {`,
+        ...Array.from({ length: 100 }, (_, line) => `  v = tick(${String(index)}, ${String(line)});`),
+        '}',
+      ]).flat(),
+    ]
+    const flatText = flat.join('\n')
+    expect(flatText.length).toBeGreaterThan(8_000)
+    const output = reduceFreshToolResult(input({ text: flatText, budgetChars: 4_000 }))
+    expect(output).not.toBeNull()
+    expect(output!.reducer).toBe('pi-head')
+  })
+})
+
+/** task_15 (R10-B): bundled/minified JS — line-anchored reducers cannot see
+ *  inside a 135k-character line; the useful first answer is a declaration
+ *  directory, never half a statement. */
+describe('bundled/minified JS directory (task_15)', () => {
+  const bundleLines = [
+    '/*! license header */',
+    `(()=>{var __webpack_exports__={};${Array.from({ length: 30 }, (_, index) =>
+      `function handleWidget${String(index)}(a,b){return a+b};`).join('')}export{handleWidget0};const CONFIG_VALUE=42;})();`,
+    '//# sourceMappingURL=index.js.map',
+  ]
+  const bundle = bundleLines.join('\n')
+
+  it('detects the minified form (R10a)', () => {
+    expect(looksLikeMinified(bundle)).toBe(true)
+  })
+
+  it('still detects a 53-line webui bundle with one 135k line', () => {
+    const giant = `var x=1;${'y'.repeat(135_000)};`
+    expect(looksLikeMinified([giant, giant].join('\n'))).toBe(true)
+  })
+
+  it('emits a declaration directory with symbols and the source-map note (R10b/R10c)', () => {
+    const output = reduceFreshToolResult(input({
+      toolName: 'read',
+      text: bundle,
+      budgetChars: 3_000,
+    }))
+    expect(output).not.toBeNull()
+    expect(output!.reducer).toBe('bundled-js-directory')
+    expect(output!.text).toContain('handleWidget0')
+    expect(output!.text).toContain('CONFIG_VALUE')
+    expect(output!.text).toContain('source map present')
+    // Never hands back half a statement of bundle body.
+    expect(output!.text).not.toContain('return a+b')
+  })
+
+  it('fails open when the bundle declares nothing extractable', () => {
+    const opaque = `${'q'.repeat(30_000)};`
+    const output = reduceFreshToolResult(input({ text: opaque, budgetChars: 2_000 }))
+    if (output !== null) expect(output.reducer).not.toBe('bundled-js-directory')
+  })
+})
+
+/** R4/RK-4: looksLikeDocument keeps its `^#{1,6}\s+\S` anchoring but scans
+ *  beyond line 400 (C26), and pure logs still fail (C27). */
+describe('looksLikeDocument window (C26/C27)', () => {
+  it('accepts a document whose ≥3 headings sit at lines 401–600', () => {
+    const lines = Array.from({ length: 595 }, () => 'plain prose line with words only')
+    lines[400] = '# Chapter Four'
+    lines[499] = '# Chapter Five'
+    lines[588] = '# Chapter Six'
+    expect(looksLikeDocument(lines.join('\n'))).toBe(true)
+  })
+
+  it('still rejects pure logs without heading lines (C27)', () => {
+    const log = Array.from({ length: 500 }, (_, index) =>
+      `2026-09-19T10:${String(index % 60).padStart(2, '0')} INFO request ${String(index)} handled in ${String(index)}ms`).join('\n')
+    expect(looksLikeDocument(log)).toBe(false)
+  })
+})

package/packages/selector/tests/runtime/tokenpilot/profile-baseline.spec.ts

@@ -66,6 +66,18 @@ describe('tokenpilot-inspired preset', () => {
       reviewTimeoutTurns: 6,
       cacheHitDiscountAlpha: 0.1,
       reviewHighImpactTokens: 4000,
+      // Advisory advisor ships off with its documented defaults. The
+      // resolved matrix intentionally gains this group so it follows the
+      // estimator's resolved-consumption pattern; see
+      // .agents/plans/ctx-relevance-advisor/spec.md decision record.
+      advisor: {
+        mode: '',
+        timeoutMs: 8000,
+        refreshTurns: 8,
+        scoreThreshold: 0.35,
+        sampleLimit: 16,
+        minTokens: 250,
+      },
     })
     // Other profiles never carry the capability matrix.
     expect(resolvePolicy(config, 'balanced').presetOptions).toBeUndefined()

package/packages/selector/tests/runtime/tokenpilot/proposal.spec.ts

@@ -82,6 +82,28 @@ describe('computeBenefit', () => {
     )
     expect(result.expectedSaving).toBeCloseTo(0)
   })
+
+  it('waives the refill penalty for a refill-exempt batch: payback 0, saving α·R·Ŝ', () => {
+    // Fresh-stage shaping: the content never entered the KV cache, so no
+    // refill penalty applies — the whole discounted recovery is pure gain.
+    const result = computeBenefit(
+      [{ sourceSeq: 7, tokensBefore: 4000, tokensAfter: 400 }],
+      { alpha: 0.1, tailTokens: 4000, remainingTurns: 12, refillPenaltyExempt: true },
+    )
+    expect(result.recoveredTokens).toBe(3600)
+    expect(result.penaltyTokens).toBe(0)
+    expect(result.paybackTurns).toBe(0)
+    // α·R·max(0, Ŝ − 0) = 360·12
+    expect(result.expectedSaving).toBeCloseTo(4320)
+  })
+
+  it('keeps the refill penalty when the exemption flag is absent', () => {
+    const result = computeBenefit(
+      [{ sourceSeq: 7, tokensBefore: 4000, tokensAfter: 400 }],
+      { alpha: 0.1, tailTokens: 4000 },
+    )
+    expect(result.penaltyTokens).toBeCloseTo(3600)
+  })
 })
 
 describe('proposalId', () => {
@@ -196,4 +218,176 @@ describe('classifyCandidates', () => {
     )
     expect(result.review[0]!.kind).toBe('estimator')
   })
+
+  it('degenerates to the per-candidate behavior for a single-candidate batch', () => {
+    // payback = 1000/400 = 2.5: Ŝ = 8 → 2.5 > 2 and ≤ 3 → review, one item.
+    const result = classifyCandidates(
+      [candidate({ tokensBefore: 1400, tokensAfter: 1000 })],
+      { ...TRIAGE, remainingTurns: 8 },
+    )
+    expect(result.auto).toEqual([])
+    expect(result.review).toHaveLength(1)
+    expect(result.review[0]!.items).toHaveLength(1)
+  })
+})
+
+/** Fresh-stage batches are exempt from the tail-refill penalty: their content
+ *  never entered the KV cache, so shaping it before the first request causes
+ *  no cache break. The same batch that history pricing would drop must land
+ *  auto. Fixture: α=0.1, tail=64,000 → history penalty = 57,600; batch
+ *  R = 2×450 = 900 → history payback = 57,600/90 = 640 > 3, Ŝ unknown →
+ *  drop. Fresh pricing: penalty = 0 → payback = 0 → auto. */
+describe('classifyCandidates (fresh-stage refill exemption)', () => {
+  const FRESH = {
+    alpha: 0.1,
+    tailTokens: 64_000,
+    reviewHighImpactTokens: 4_000,
+  }
+
+  it('lands a fresh batch auto that history pricing would drop', () => {
+    const batch = [
+      candidate({ sourceSeq: 1, tokensBefore: 2000, tokensAfter: 1550 }),
+      candidate({ sourceSeq: 2, tokensBefore: 2000, tokensAfter: 1550 }),
+    ]
+    const history = classifyCandidates(batch, FRESH)
+    expect(history.drop.map(entry => entry.sourceSeq)).toEqual([1, 2])
+    const fresh = classifyCandidates(batch, { ...FRESH, stage: 'fresh' })
+    expect(fresh.auto.map(entry => entry.sourceSeq)).toEqual([1, 2])
+    expect(fresh.review).toEqual([])
+    expect(fresh.drop).toEqual([])
+  })
+
+  it('still routes a high-impact fresh candidate to review', () => {
+    const result = classifyCandidates(
+      [candidate({ tokensBefore: 5000, tokensAfter: 4000 })],
+      { ...FRESH, stage: 'fresh' },
+    )
+    expect(result.auto).toEqual([])
+    expect(result.review).toHaveLength(1)
+  })
+
+  it('defaults to history pricing when stage is omitted', () => {
+    const result = classifyCandidates(
+      [candidate({ sourceSeq: 1, tokensBefore: 2000, tokensAfter: 1550 })],
+      FRESH,
+    )
+    expect(result.drop.map(entry => entry.sourceSeq)).toEqual([1])
+  })
+})
+
+/** R1 batch-level benefit: one merged mutation pays the tail refill ONCE.
+ *  Fixture: α=0.02, tail=64,000, Ŝ=60. Per candidate R = 50,000 − 500 = 49,500.
+ *  Batch: R = 247,500 → payback = 62,720 / 4,950 ≈ 12.67 ≤ 0.25·60 = 15 → auto.
+ *  Per candidate: payback = 62,720 / 990 ≈ 63.35 > 3 → every one drops. */
+describe('classifyCandidates (batch-level benefit, R1)', () => {
+  const BATCH = {
+    alpha: 0.02,
+    tailTokens: 64_000,
+    reviewHighImpactTokens: 200_000,
+    remainingTurns: 60,
+  }
+
+  function batchCandidate(seq: number, overrides: { tokensBefore?: number, tokensAfter?: number, reducer?: string } = {}) {
+    return candidate({
+      sourceSeq: seq,
+      tokensBefore: overrides.tokensBefore ?? 50_000,
+      tokensAfter: overrides.tokensAfter ?? 500,
+      ...overrides.reducer !== undefined ? { reducer: overrides.reducer } : {},
+    })
+  }
+
+  it('pays the refill penalty once per batch: 5×50k lands auto', () => {
+    const result = classifyCandidates(
+      [1, 2, 3, 4, 5].map(seq => batchCandidate(seq)),
+      BATCH,
+    )
+    expect(result.auto.map(entry => entry.sourceSeq)).toEqual([1, 2, 3, 4, 5])
+    expect(result.review).toEqual([])
+    expect(result.drop).toEqual([])
+  })
+
+  it('counter-proof: priced per candidate the same five would all drop', () => {
+    // Under per-candidate pricing each candidate pays the full refill alone:
+    // payback = 62,720 / (0.02·49,500) ≈ 63.35 > 3 → drop. The batch-level
+    // classifier above lands the identical five in auto.
+    const perCandidate = computeBenefit(
+      [{ sourceSeq: 1, tokensBefore: 50_000, tokensAfter: 500 }],
+      BATCH,
+    )
+    expect(perCandidate.paybackTurns).toBeGreaterThan(3)
+  })
+
+  it('a zero-recovery candidate is priced out before the batch verdict', () => {
+    // Batch of five real candidates + one growing one: the five land auto
+    // (payback ≈ 12.67) and the zero-recovery one never joins the pricing.
+    const result = classifyCandidates(
+      [
+        ...[1, 2, 3, 4, 5].map(seq => batchCandidate(seq)),
+        batchCandidate(6, { tokensBefore: 500, tokensAfter: 500 }),
+      ],
+      BATCH,
+    )
+    expect(result.auto.map(entry => entry.sourceSeq)).toEqual([1, 2, 3, 4, 5])
+    expect(result.drop.map(entry => entry.sourceSeq)).toEqual([6])
+  })
+
+  it('high impact covers the whole batch: one ≥H candidate sends everything to review', () => {
+    const result = classifyCandidates(
+      [batchCandidate(1), batchCandidate(2, { tokensBefore: 250_000 })],
+      BATCH,
+    )
+    expect(result.auto).toEqual([])
+    expect(result.drop).toEqual([])
+    expect(result.review).toHaveLength(1)
+    expect(result.review[0]!.items.map(item => item.seq)).toEqual([1, 2])
+  })
+
+  /** Edge-band review fixture: batch R = 3×430,000 = 1,290,000 →
+   *  perTurn = 0.02·R = 25,800 → payback = 62,720/25,800 ≈ 2.43.
+   *  Ŝ = 8 → 0.25·Ŝ = 2: payback ∈ (2, 3] → review. No candidate is
+   *  high-impact (600,000 < reviewHighImpactTokens 1,000,000). */
+  const EDGE_REVIEW = {
+    alpha: 0.02,
+    tailTokens: 64_000,
+    reviewHighImpactTokens: 1_000_000,
+    remainingTurns: 8,
+  }
+
+  function edgeCandidate(seq: number, overrides: { tokensBefore?: number, tokensAfter?: number, reducer?: string } = {}) {
+    return candidate({
+      sourceSeq: seq,
+      tokensBefore: overrides.tokensBefore ?? 600_000,
+      tokensAfter: overrides.tokensAfter ?? 170_000,
+      ...overrides.reducer !== undefined ? { reducer: overrides.reducer } : {},
+    })
+  }
+
+  it('groups one proposal per kind and the id covers every item digest', () => {
+    const result = classifyCandidates(
+      [1, 2, 3].map(seq => edgeCandidate(seq, { reducer: 'dedupe-pointer' })),
+      EDGE_REVIEW,
+    )
+    expect(result.review).toHaveLength(1)
+    const skeleton = result.review[0]!
+    expect(skeleton.kind).toBe('dedup')
+    expect(skeleton.items).toHaveLength(3)
+    expect(skeleton.id).toBe(proposalId(skeleton.items.map(item => item.digest)))
+  })
+
+  it('splits review proposals by kind when the batch mixes reducers', () => {
+    const result = classifyCandidates(
+      [
+        edgeCandidate(1, { reducer: 'dedupe-pointer' }),
+        edgeCandidate(2, { reducer: 'dedupe-pointer' }),
+        edgeCandidate(3, { reducer: 'native-whole-result' }),
+      ],
+      EDGE_REVIEW,
+    )
+    expect(result.review).toHaveLength(2)
+    const digests = result.review.flatMap(skeleton => skeleton.items.map(item => item.digest))
+    expect(digests).toHaveLength(3)
+    for (const skeleton of result.review) {
+      expect(skeleton.id).toBe(proposalId(skeleton.items.map(item => item.digest)))
+    }
+  })
 })