dsh-context-compression-improved 0.1.1 → 0.2.1

package/packages/selector/tests/runtime/code-skeleton.spec.ts

@@ -0,0 +1,141 @@
+import { describe, expect, it } from 'vitest'
+import { codePointLength } from '../../src/runtime/config.ts'
+import { reduceFreshToolResult, verifyReduction } from '../../src/runtime/reducers.ts'
+
+const SOURCE_REF = 'session://s1/event/12'
+
+function readInput(
+  text: string,
+  budgetChars = 700,
+  codeSkeleton?: boolean,
+): Parameters<typeof reduceFreshToolResult>[0] {
+  return {
+    toolName: 'read_file',
+    argumentsText: '{"path":"src/example.ts"}',
+    text,
+    budgetChars,
+    sourceRef: SOURCE_REF,
+    isError: false,
+    ...codeSkeleton === undefined ? {} : { codeSkeleton },
+  }
+}
+
+const TYPESCRIPT_FILE = [
+  '/** Module doc block. */',
+  "import { helper } from './helper'",
+  'import type { Options } from "./options"',
+  '',
+  'export interface Options {',
+  '  retries: number',
+  '  timeout: number',
+  '}',
+  '',
+  'export function runJob(job: string,',
+  '  retries: number,',
+  '  timeout: number) {',
+  '  const started = Date.now()',
+  "  throw new Error('fatal: job queue unreachable')",
+  '  return started',
+  '}',
+  '',
+  'class Runner {',
+  '  private stopped = false',
+  '  stop(): void {',
+  '    this.stopped = true',
+  '  }',
+  '}',
+  ...Array.from({ length: 40 }, (_, i) => `// filler line ${String(i)} to make the file worth compressing`),
+].join('\n')
+
+const PYTHON_FILE = [
+  '"""Docstring."""',
+  'import os',
+  'from pathlib import Path',
+  '',
+  'class Runner:',
+  '    def __init__(self, name,',
+  '        retries=3):',
+  '        self.name = name',
+  '        raise RuntimeError("fatal: bad config")',
+  '',
+  '    def run(self):',
+  '        return os.getcwd()',
+  ...Array.from({ length: 40 }, (_, i) => `# filler line ${String(i)} to make the file worth compressing`),
+].join('\n')
+
+describe('hypa-code-skeleton reducer', () => {
+  it('keeps imports and signatures while eliding brace-language bodies', () => {
+    const input = readInput(TYPESCRIPT_FILE, 700, true)
+    const output = reduceFreshToolResult(input)
+    expect(output).not.toBeNull()
+    expect(output?.reducer).toBe('hypa-code-skeleton')
+    expect(output?.text).toContain("import { helper } from './helper'")
+    expect(output?.text).toContain('export interface Options {')
+    expect(output?.text).toContain('export function runJob(job: string,')
+    expect(output?.text).toContain('class Runner {')
+    expect(output?.text).toContain('lines elided')
+    expect(output?.text).not.toContain('const started = Date.now()')
+    expect(output?.text).toContain(SOURCE_REF)
+    expect(verifyReduction(input, output!)).toBe(true)
+  })
+
+  it('preserves error lines from inside elided bodies', () => {
+    const input = readInput(TYPESCRIPT_FILE, 700, true)
+    const output = reduceFreshToolResult(input)
+    expect(output?.text).toContain("throw new Error('fatal: job queue unreachable')")
+  })
+
+  it('keeps multi-line signature continuations', () => {
+    const input = readInput(TYPESCRIPT_FILE, 700, true)
+    const output = reduceFreshToolResult(input)
+    expect(output?.text).toContain('  retries: number,')
+    expect(output?.text).toContain('  timeout: number) {')
+  })
+
+  it('elides indented Python bodies and keeps method signatures', () => {
+    const input = readInput(PYTHON_FILE, 700, true)
+    const output = reduceFreshToolResult(input)
+    expect(output).not.toBeNull()
+    expect(output?.reducer).toBe('hypa-code-skeleton')
+    expect(output?.text).toContain('class Runner:')
+    expect(output?.text).toContain('def __init__(self, name,')
+    expect(output?.text).toContain('def run(self):')
+    expect(output?.text).not.toContain('return os.getcwd()')
+    expect(output?.text).toContain('raise RuntimeError("fatal: bad config")')
+    expect(verifyReduction(input, output!)).toBe(true)
+  })
+
+  it('stays within the char budget', () => {
+    const input = readInput(TYPESCRIPT_FILE, 1_200, true)
+    const output = reduceFreshToolResult(input)
+    expect(output?.reducer).toBe('hypa-code-skeleton')
+    expect(codePointLength(output!.text)).toBeLessThanOrEqual(1_200)
+  })
+
+  it('leaves prose on the existing head reducer', () => {
+    const prose = Array.from({ length: 200 }, (_, i) =>
+      `Paragraph ${String(i)} explains a concept in plain sentences with no code structure at all.`).join('\n')
+    const input = readInput(prose)
+    const output = reduceFreshToolResult(input)
+    expect(output?.reducer).toBe('pi-head')
+  })
+
+  it('does not fire on small or sparse content', () => {
+    const sparse = ['function a() {}', 'function b() {}', 'plain text line'].join('\n')
+    expect(reduceFreshToolResult(readInput(sparse))?.reducer).not.toBe('hypa-code-skeleton')
+  })
+
+  it('stays off for code content when the orthogonal gate is unset or false', () => {
+    for (const codeSkeleton of [undefined, false]) {
+      const input = readInput(TYPESCRIPT_FILE, 700, codeSkeleton)
+      const output = reduceFreshToolResult(input)
+      expect(output?.reducer).not.toBe('hypa-code-skeleton')
+      expect(output?.reducer).toBe('pi-head')
+    }
+  })
+
+  it('fires for code content only when the orthogonal gate is enabled', () => {
+    const enabled = reduceFreshToolResult(readInput(TYPESCRIPT_FILE, 700, true))
+    expect(enabled?.reducer).toBe('hypa-code-skeleton')
+  })
+})

package/packages/selector/tests/runtime/deepseek-official-pricing.spec.ts

@@ -0,0 +1,186 @@
+import { describe, expect, it } from 'vitest'
+import {
+  DEEPSEEK_OFFICIAL_PRICE_CATALOG_VERSION,
+  priceBandAt,
+  priceOfficialDeepSeekUsage,
+  resolveOfficialDeepSeekPrice,
+} from '../../src/runtime/deepseek-official-pricing.ts'
+
+describe('DeepSeek checked-in official price catalog', () => {
+  it.each([
+    ['deepseek-v4-flash', 'USD', 'off-peak', '0.007', '0.22', '0.66'],
+    ['deepseek-v4-flash', 'USD', 'peak', '0.014', '0.44', '1.32'],
+    ['deepseek-v4-flash', 'CNY', 'off-peak', '0.05', '1.5', '4.5'],
+    ['deepseek-v4-flash', 'CNY', 'peak', '0.10', '3.0', '9.0'],
+    ['deepseek-v4-pro', 'USD', 'off-peak', '0.022', '0.66', '1.98'],
+    ['deepseek-v4-pro', 'USD', 'peak', '0.044', '1.32', '3.96'],
+    ['deepseek-v4-pro', 'CNY', 'off-peak', '0.15', '4.5', '13.5'],
+    ['deepseek-v4-pro', 'CNY', 'peak', '0.30', '9.0', '27.0'],
+    ['deepseek-v4-flash-vision-exp', 'USD', 'off-peak', '0.007', '0.22', '0.66'],
+    ['deepseek-v4-flash-vision-exp', 'USD', 'peak', '0.014', '0.44', '1.32'],
+    ['deepseek-v4-flash-vision-exp', 'CNY', 'off-peak', '0.05', '1.5', '4.5'],
+    ['deepseek-v4-flash-vision-exp', 'CNY', 'peak', '0.10', '3.0', '9.0'],
+  ] as const)(
+    'resolves %s %s %s from the versioned catalog',
+    (modelId, currency, band, hit, miss, output) => {
+      const resolved = resolveOfficialDeepSeekPrice({
+        provider: 'deepseek-official',
+        baseUrlClass: 'official-public',
+        apiRoute: 'chat-completions',
+        modelId,
+        currency,
+        at: band === 'peak'
+          ? new Date('2026-08-25T01:00:00.000Z')
+          : new Date('2026-08-23T01:00:00.000Z'),
+      })
+      expect(resolved).toMatchObject({
+        kind: 'priced',
+        record: {
+          catalogVersion: DEEPSEEK_OFFICIAL_PRICE_CATALOG_VERSION,
+          modelId, currency, band,
+          inputCacheHit: hit,
+          inputCacheMiss: miss,
+          output,
+        },
+      })
+    },
+  )
+
+  it.each(['chat-completions', 'responses'] as const)(
+    'prices the documented %s route without changing the catalog tuple',
+    (apiRoute) => {
+      expect(resolveOfficialDeepSeekPrice({
+        provider: 'deepseek-official',
+        baseUrlClass: 'official-public',
+        apiRoute,
+        modelId: 'deepseek-v4-pro',
+        currency: 'USD',
+        at: new Date('2026-08-25T01:00:00.000Z'),
+      })).toMatchObject({
+        kind: 'priced',
+        record: { apiRoute, modelId: 'deepseek-v4-pro', band: 'peak' },
+      })
+    },
+  )
+
+  it.each([
+    ['2026-08-24T00:59:59.000Z', 'off-peak'],
+    ['2026-08-24T01:00:00.000Z', 'peak'],
+    ['2026-08-24T03:59:59.000Z', 'peak'],
+    ['2026-08-24T04:00:00.000Z', 'off-peak'],
+    ['2026-08-24T05:59:59.000Z', 'off-peak'],
+    ['2026-08-24T06:00:00.000Z', 'peak'],
+    ['2026-08-24T09:59:59.000Z', 'peak'],
+    ['2026-08-24T10:00:00.000Z', 'off-peak'],
+    ['2026-08-29T01:00:00.000Z', 'off-peak'],
+    ['2026-08-30T06:00:00.000Z', 'off-peak'],
+  ] as const)('classifies exact UTC schedule boundary %s as %s', (iso, expected) => {
+    expect(priceBandAt(new Date(iso))).toBe(expected)
+  })
+
+  it.each([
+    [{ provider: 'gateway', baseUrlClass: 'official-public' }, 'provider'],
+    [{ provider: 'deepseek-official', baseUrlClass: 'compatible-hmac:v1:test' }, 'base-url'],
+    [{ provider: 'deepseek-official', baseUrlClass: 'official-public', modelId: 'deepseek-chat' }, 'model'],
+    [{ provider: 'deepseek-official', baseUrlClass: 'official-public', apiRoute: 'other' }, 'route'],
+  ] as const)('fails closed instead of aliasing an unknown applicability: %s', (patch, reason) => {
+    const resolved = resolveOfficialDeepSeekPrice({
+      apiRoute: 'chat-completions',
+      modelId: 'deepseek-v4-flash',
+      currency: 'USD',
+      at: new Date('2026-08-25T01:00:00.000Z'),
+      ...patch,
+    })
+    expect(resolved.kind).toBe('unpriced')
+    if (resolved.kind !== 'unpriced')
+      throw new Error(`Expected an unpriced result, received ${resolved.kind}`)
+    expect(resolved.reason).toContain(reason)
+  })
+
+  it('computes provider-usage cost with fixed-point arithmetic, never JS float money', () => {
+    const cost = priceOfficialDeepSeekUsage({
+      provider: 'deepseek-official',
+      baseUrlClass: 'official-public',
+      apiRoute: 'chat-completions',
+      modelId: 'deepseek-v4-flash',
+      currency: 'USD',
+      startedAt: new Date('2026-08-25T01:00:00.000Z'),
+      completedAt: new Date('2026-08-25T01:01:00.000Z'),
+      usage: { cacheReadTokens: 1, cacheMissTokens: 2, outputTokens: 3 },
+    })
+    expect(cost).toEqual({
+      kind: 'exact',
+      currency: 'USD',
+      band: 'peak',
+      femtoUnits: '4854000000',
+      decimal: '0.000004854',
+    })
+  })
+
+  it('returns a range when one request spans a published price-band boundary', () => {
+    const cost = priceOfficialDeepSeekUsage({
+      provider: 'deepseek-official',
+      baseUrlClass: 'official-public',
+      apiRoute: 'chat-completions',
+      modelId: 'deepseek-v4-pro',
+      currency: 'CNY',
+      startedAt: new Date('2026-08-25T03:59:59.000Z'),
+      completedAt: new Date('2026-08-25T04:00:01.000Z'),
+      usage: { cacheReadTokens: 10, cacheMissTokens: 20, outputTokens: 3 },
+    })
+    expect(cost).toMatchObject({
+      kind: 'range', currency: 'CNY', bands: ['peak', 'off-peak'],
+    })
+  })
+
+  it('returns a range when both endpoints share a band but the interval crosses peak', () => {
+    const cost = priceOfficialDeepSeekUsage({
+      provider: 'deepseek-official',
+      baseUrlClass: 'official-public',
+      apiRoute: 'chat-completions',
+      modelId: 'deepseek-v4-flash',
+      currency: 'USD',
+      startedAt: new Date('2026-08-25T00:59:59.000Z'),
+      completedAt: new Date('2026-08-25T04:00:01.000Z'),
+      usage: { cacheReadTokens: 10, cacheMissTokens: 20, outputTokens: 3 },
+    })
+    expect(cost).toMatchObject({
+      kind: 'range', currency: 'USD', bands: ['off-peak', 'peak'],
+    })
+  })
+
+  it.each([
+    ['Friday through Monday', '2026-08-28T10:00:01.000Z', '2026-08-31T01:00:01.000Z'],
+    ['seven full days', '2026-08-25T00:00:00.000Z', '2026-09-01T00:00:00.000Z'],
+  ])('returns a range across %s', (_label, startedAt, completedAt) => {
+    expect(priceOfficialDeepSeekUsage({
+      provider: 'deepseek-official',
+      baseUrlClass: 'official-public',
+      apiRoute: 'responses',
+      modelId: 'deepseek-v4-flash',
+      currency: 'USD',
+      startedAt: new Date(startedAt),
+      completedAt: new Date(completedAt),
+      usage: { cacheReadTokens: 10, cacheMissTokens: 20, outputTokens: 3 },
+    })).toMatchObject({ kind: 'range', currency: 'USD' })
+  })
+
+  it.each([
+    ['invalid start timestamp', new Date('invalid'), new Date('2026-08-25T01:00:00.000Z'), 'timestamp'],
+    ['completion before start', new Date('2026-08-25T01:00:01.000Z'), new Date('2026-08-25T01:00:00.000Z'), 'precedes'],
+  ] as const)('fails closed for %s', (_label, startedAt, completedAt, reason) => {
+    const cost = priceOfficialDeepSeekUsage({
+      provider: 'deepseek-official',
+      baseUrlClass: 'official-public',
+      apiRoute: 'chat-completions',
+      modelId: 'deepseek-v4-flash',
+      currency: 'USD',
+      startedAt,
+      completedAt,
+      usage: { cacheReadTokens: 1, cacheMissTokens: 2, outputTokens: 3 },
+    })
+    expect(cost.kind).toBe('unpriced')
+    if (cost.kind !== 'unpriced') throw new Error('expected unpriced interval')
+    expect(cost.reason).toContain(reason)
+  })
+})

package/packages/selector/tests/runtime/deepseek-v4-tokenizer.spec.ts

@@ -0,0 +1,122 @@
+/** Registry behavior for the bundled official DeepSeek tokenizer artifacts. */
+
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+import {
+  DEEPSEEK_V4_TOKENIZER_ARTIFACT,
+  DEEPSEEK_VISION_TOKENIZER_ARTIFACT,
+  createDeepSeekV4TokenizerFromAssets,
+  deepSeekV4TokenizerFailureReason,
+  deepSeekV4TokenizerForModel,
+} from '../../src/deepseek-v4-tokenizer.ts'
+
+const RUNTIME_ROOT = new URL('../../', import.meta.url)
+
+describe('bundled DeepSeek tokenizer artifact registry', () => {
+  it('resolves each exact API model id to its pinned artifact identity', () => {
+    for (const modelId of ['deepseek-v4-flash', 'deepseek-v4-pro']) {
+      expect(deepSeekV4TokenizerForModel(modelId)?.countText('identity probe')).toMatchObject({
+        kind: 'exact-tokenizer',
+        tokenizerId: 'deepseek-ai/DeepSeek-V4-Pro',
+        tokenizerRevision: DEEPSEEK_V4_TOKENIZER_ARTIFACT.revision,
+      })
+    }
+    expect(deepSeekV4TokenizerForModel('deepseek-v4-flash-vision-exp')?.countText('identity probe')).toMatchObject({
+      kind: 'exact-tokenizer',
+      tokenizerId: 'deepseek-ai/DeepSeek-V4-Flash-Vision-Exp',
+      tokenizerRevision: '6821d6ad3681a4b137b066b76094fa82ebd0a380',
+    })
+  })
+
+  it('ships a vision tokenizer that is not an alias of the V4 Pro tokenizer', () => {
+    expect(DEEPSEEK_VISION_TOKENIZER_ARTIFACT.modelIds).toEqual(['deepseek-v4-flash-vision-exp'])
+    expect(DEEPSEEK_VISION_TOKENIZER_ARTIFACT.license).toBe('MIT')
+    expect(DEEPSEEK_VISION_TOKENIZER_ARTIFACT.tokenizerSha256)
+      .not.toBe(DEEPSEEK_V4_TOKENIZER_ARTIFACT.tokenizerSha256)
+    // The official vision placeholder special token exists only in the vision
+    // vocabulary; the text tokenizer must not silently accept it as one token.
+    expect(deepSeekV4TokenizerForModel('deepseek-v4-flash-vision-exp')?.countText('<｜deepseek_image｜>').tokens).toBe(1)
+    expect(deepSeekV4TokenizerForModel('deepseek-v4-pro')?.countText('<｜deepseek_image｜>').tokens).toBeGreaterThan(1)
+  })
+
+  it.each([
+    'deepseek-v4-flash-vision',
+    'deepseek-v4-flash-vision-exp-2',
+    'DeepSeek-V4-Flash-Vision-Exp',
+    'deepseek-v4-vision-exp',
+    'deepseek-v4-pro-vision',
+    'deepseek-vision',
+    'gpt-4o',
+    '',
+  ])('refuses the non-exact model id %s', (modelId) => {
+    expect(deepSeekV4TokenizerForModel(modelId)).toBeUndefined()
+    expect(deepSeekV4TokenizerFailureReason(modelId)).toBeUndefined()
+  })
+
+  it('reports the cached failure reason for the artifact serving one model', () => {
+    // Both text models resolve successfully today, so no failure is recorded.
+    expect(deepSeekV4TokenizerFailureReason('deepseek-v4-pro')).toBeUndefined()
+    expect(deepSeekV4TokenizerFailureReason('deepseek-v4-flash-vision-exp')).toBeUndefined()
+  })
+
+  it('fails closed on byte-length, SHA-256, and JSON corruption for the vision artifact without touching the text artifact', () => {
+    const visionRoot = new URL('assets/deepseek-v4-vision-exp/', RUNTIME_ROOT)
+    const tokenizerBytes = readFileSync(fileURLToPath(new URL('tokenizer.json', visionRoot)))
+    const good = {
+      tokenizer: { bytes: tokenizerBytes.byteLength, sha256: DEEPSEEK_VISION_TOKENIZER_ARTIFACT.tokenizerSha256 },
+      config: { bytes: 801, sha256: DEEPSEEK_VISION_TOKENIZER_ARTIFACT.tokenizerConfigSha256 },
+    }
+    expect(() => createDeepSeekV4TokenizerFromAssets(visionRoot, {
+      tokenizer: { ...good.tokenizer, bytes: good.tokenizer.bytes + 1 },
+      config: good.config,
+    })).toThrow(/bytes/)
+    expect(() => createDeepSeekV4TokenizerFromAssets(visionRoot, {
+      tokenizer: { ...good.tokenizer, sha256: '0'.repeat(64) },
+      config: good.config,
+    })).toThrow(/SHA-256/)
+    expect(() => createDeepSeekV4TokenizerFromAssets(visionRoot, good)).not.toThrow()
+    // The shared registry still serves the independent text artifact.
+    expect(deepSeekV4TokenizerForModel('deepseek-v4-flash')?.countText('still exact').kind).toBe('exact-tokenizer')
+  })
+
+  it('fails closed when a byte-and-hash-valid asset is not JSON', async () => {
+    const { mkdtemp, writeFile } = await import('node:fs/promises')
+    const { tmpdir } = await import('node:os')
+    const { createHash } = await import('node:crypto')
+    const { join } = await import('node:path')
+    const root = await mkdtemp(join(tmpdir(), 'dsh-tokenizer-json-corrupt-'))
+    try {
+      const payload = 'this is definitely not json'
+      const bytes = Buffer.from(payload, 'utf8')
+      await writeFile(join(root, 'tokenizer.json'), bytes)
+      await writeFile(join(root, 'tokenizer_config.json'), bytes)
+      const sha256 = createHash('sha256').update(bytes).digest('hex')
+      const integrity = {
+        tokenizer: { bytes: bytes.byteLength, sha256 },
+        config: { bytes: bytes.byteLength, sha256 },
+      }
+      await expect(Promise.resolve().then(() =>
+        createDeepSeekV4TokenizerFromAssets(new URL(`file://${root}/`), integrity),
+      )).rejects.toThrow(/JSON|json/)
+    } finally {
+      await import('node:fs/promises').then(fs => fs.rm(root, { recursive: true, force: true }))
+    }
+  })
+
+  it('verifies the committed asset manifests against the shipped files', () => {
+    for (const [directory, artifact] of [
+      ['deepseek-v4', DEEPSEEK_V4_TOKENIZER_ARTIFACT],
+      ['deepseek-v4-vision-exp', DEEPSEEK_VISION_TOKENIZER_ARTIFACT],
+    ] as const) {
+      const manifest = JSON.parse(
+        readFileSync(fileURLToPath(new URL(`assets/${directory}/manifest.json`, RUNTIME_ROOT)), 'utf8'),
+      ) as { repository: string, revision: string, modelIds: string[], files: Record<string, { bytes: number, sha256: string }> }
+      expect(manifest.repository).toBe(artifact.repository)
+      expect(manifest.revision).toBe(artifact.revision)
+      expect(manifest.modelIds).toEqual([...artifact.modelIds])
+      expect(manifest.files['tokenizer.json']?.sha256).toBe(artifact.tokenizerSha256)
+      expect(manifest.files['tokenizer_config.json']?.sha256).toBe(artifact.tokenizerConfigSha256)
+    }
+  })
+})

package/packages/selector/tests/runtime/deepseek-v4-vision-tokens.spec.ts

@@ -0,0 +1,122 @@
+/** Node vision-token arithmetic against the official DeepSeek reference fixtures. */
+
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+import {
+  DEEPSEEK_VISION_DEFAULT_IMAGE_TOKENS,
+  DEEPSEEK_VISION_IMAGE_ESTIMATOR,
+  DEEPSEEK_VISION_PROJECTION,
+  deepSeekVisionImageGrid,
+  deepSeekVisionImageTokens,
+  estimateDeepSeekVisionImageTokens,
+  isWithinDeepSeekRequestPixelBudget,
+} from '../../src/runtime/deepseek-v4-vision-tokens.ts'
+
+interface GoldenEntry {
+  readonly width: number
+  readonly height: number
+  readonly startTokenPos: number
+  readonly nLlmH: number
+  readonly nLlmW: number
+  readonly tokens: number
+}
+
+interface GoldenFixture {
+  readonly source: { readonly repository: string, readonly revision: string }
+  readonly parameters: Readonly<Record<string, number>>
+  readonly singleImages: readonly { width: number, height: number, nLlmH: number, nLlmW: number, tokensAtStart0: number }[]
+  readonly startPositions: readonly GoldenEntry[]
+  readonly sequences: readonly { entries: readonly GoldenEntry[] }[]
+}
+
+const fixture = JSON.parse(readFileSync(
+  fileURLToPath(new URL('fixtures/vision-golden.json', import.meta.url)),
+  'utf8',
+)) as GoldenFixture
+
+describe('DeepSeek vision token arithmetic matches the official reference', () => {
+  it('pins the official projection parameters and revision', () => {
+    expect(DEEPSEEK_VISION_PROJECTION.sourceRepository).toBe(fixture.source.repository)
+    expect(DEEPSEEK_VISION_PROJECTION.sourceRevision).toBe(fixture.source.revision)
+    expect(DEEPSEEK_VISION_PROJECTION.visionPatchSize).toBe(fixture.parameters.visionPatchSize)
+    expect(DEEPSEEK_VISION_PROJECTION.visionDownsampleRatio).toBe(fixture.parameters.visionDownsampleRatio)
+    expect(DEEPSEEK_VISION_PROJECTION.visionMaxNTokens).toBe(fixture.parameters.visionMaxNTokens)
+    expect(DEEPSEEK_VISION_PROJECTION.visionMinPixels).toBe(fixture.parameters.visionMinPixels)
+    expect(DEEPSEEK_VISION_PROJECTION.visionMaxWhRatio).toBe(fixture.parameters.visionMaxWhRatio)
+  })
+
+  it.each(fixture.singleImages)('expands $width×$height to the official grid', (entry) => {
+    const grid = deepSeekVisionImageGrid(entry.width, entry.height)
+    expect(grid).toMatchObject({ nLlmH: entry.nLlmH, nLlmW: entry.nLlmW })
+    expect(deepSeekVisionImageTokens(entry.width, entry.height, 0)).toBe(entry.tokensAtStart0)
+  })
+
+  it.each(fixture.startPositions)('aligns 640×480 at start $startTokenPos to $tokens tokens', (entry) => {
+    const grid = deepSeekVisionImageGrid(entry.width, entry.height)
+    expect(grid.nLlmH).toBe(entry.nLlmH)
+    expect(grid.nLlmW).toBe(entry.nLlmW)
+    expect(deepSeekVisionImageTokens(entry.width, entry.height, entry.startTokenPos)).toBe(entry.tokens)
+  })
+
+  it('reproduces multi-image sequences with accumulated start positions', () => {
+    for (const sequence of fixture.sequences) {
+      let position = sequence.entries[0]?.startTokenPos ?? 0
+      for (const entry of sequence.entries) {
+        expect(position).toBe(entry.startTokenPos)
+        const grid = deepSeekVisionImageGrid(entry.width, entry.height)
+        expect(grid.nLlmH).toBe(entry.nLlmH)
+        expect(grid.nLlmW).toBe(entry.nLlmW)
+        const tokens = deepSeekVisionImageTokens(entry.width, entry.height, position)
+        expect(tokens).toBe(entry.tokens)
+        position += tokens
+      }
+    }
+  })
+
+  it('reports the adapter default request pixel-budget boundary', () => {
+    expect(isWithinDeepSeekRequestPixelBudget(640, 480)).toBe(true)
+    expect(isWithinDeepSeekRequestPixelBudget(800, 800)).toBe(true) // 640000 exactly
+    expect(isWithinDeepSeekRequestPixelBudget(801, 800)).toBe(false) // one pixel over
+    expect(isWithinDeepSeekRequestPixelBudget(4096, 4096)).toBe(false)
+  })
+
+  it('estimates valid images at the midpoint of all alignment residues', () => {
+    const estimate = estimateDeepSeekVisionImageTokens(512, 512)
+    const counts = [0, 1, 2, 3].map(position => deepSeekVisionImageTokens(512, 512, position))
+    expect(estimate).toEqual({
+      tokens: Math.round((Math.min(...counts) + Math.max(...counts)) / 2),
+      upperBoundTokens: DEEPSEEK_VISION_PROJECTION.visionMaxNTokens,
+      source: 'intrinsic-grid',
+      paddingMinimumTokens: Math.min(...counts),
+      paddingMaximumTokens: Math.max(...counts),
+    })
+    expect(Math.max(...counts) - Math.min(...counts)).toBeLessThanOrEqual(3)
+    expect(DEEPSEEK_VISION_IMAGE_ESTIMATOR.revision).toContain(fixture.source.revision)
+  })
+
+  it('keeps alignment-only estimation error below ten percent across the official fixture sizes', () => {
+    for (const entry of fixture.singleImages) {
+      const estimate = estimateDeepSeekVisionImageTokens(entry.width, entry.height)
+      expect(estimate.source).toBe('intrinsic-grid')
+      for (let position = 0; position < 4; position += 1) {
+        const actual = deepSeekVisionImageTokens(entry.width, entry.height, position)
+        expect(Math.abs(estimate.tokens - actual) / actual).toBeLessThan(0.1)
+      }
+    }
+  })
+
+  it.each([
+    [0, 480],
+    [640.5, 480],
+    [Number.NaN, 480],
+    [Number.POSITIVE_INFINITY, 480],
+    [Number.MAX_SAFE_INTEGER, Number.MAX_SAFE_INTEGER],
+  ])('uses the fixed fallback for unusable metadata %s×%s', (width, height) => {
+    expect(estimateDeepSeekVisionImageTokens(width, height)).toEqual({
+      tokens: DEEPSEEK_VISION_DEFAULT_IMAGE_TOKENS,
+      upperBoundTokens: DEEPSEEK_VISION_PROJECTION.visionMaxNTokens,
+      source: 'default',
+    })
+  })
+})