dsh-context-compression-improved 0.1.1 → 0.2.1

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

@@ -0,0 +1,254 @@
+/**
+ * Exact DeepSeek V4 Flash Vision image-token arithmetic.
+ *
+ * Every rule in this module is a line-by-line port of the official
+ * `inference/image_processor.py` published by
+ * `deepseek-ai/DeepSeek-V4-Flash-Vision-Exp` at the pinned immutable revision
+ * recorded below. The golden fixtures in `tests/fixtures/vision-golden.json`
+ * are generated by executing that official implementation, so any change here
+ * must keep the Node counts byte-identical to the reference output.
+ *
+ * These arithmetic results back intrinsic-grid estimates, never exact counts
+ * of the final request. The official expansion
+ * depends on the absolute serialized prompt position (system prompt,
+ * chat-template framing, adapter image handles) and on the adapter's final
+ * request-image projection — including per-route pixel-budget or image-detail
+ * overrides and byte-cap reprojection — none of which is published through a
+ * public API, and a projected image can count FEWER tokens than its intrinsic
+ * grid suggests. The measurement layer therefore labels image-bearing nodes
+ * as estimates and keeps them outside exact rewrite proofs; the 640,000-pixel
+ * budget below documents the adapter default rather than establishing
+ * exactness.
+ */
+
+/** Official projection parameters pinned from the model repository config. */
+export const DEEPSEEK_VISION_PROJECTION = Object.freeze({
+  sourceRepository: 'deepseek-ai/DeepSeek-V4-Flash-Vision-Exp',
+  sourceRevision: '6821d6ad3681a4b137b066b76094fa82ebd0a380',
+  /** `vision_patch_size` from the official config. */
+  visionPatchSize: 14,
+  /** `vision_downsample_ratio` from the official config. */
+  visionDownsampleRatio: 3,
+  /** `vision_max_n_token`: post-preprocessing cap per image, not a fixed value. */
+  visionMaxNTokens: 384,
+  /** `vision_min_pixels`: tiny images are upscaled before patching. */
+  visionMinPixels: 147_456,
+  /** `vision_max_wh_ratio`: wider-than-ratio images are width-clamped. */
+  visionMaxWhRatio: 8,
+  /**
+   * Default per-image pixel budget used by the DeepSeek adapter's normal
+   * attachment projection (`DEFAULT_REQUEST_IMAGE_PIXEL_BUDGET` in
+   * `@deepseek-ai/dsh-llm-deepseek`). Route overrides remain unobservable to
+   * this estimator.
+   */
+  requestImagePixelBudget: 640_000,
+})
+
+/**
+ * Fallback charged when durable image metadata cannot be evaluated. It sits
+ * near the middle of the official 384-token image budget so one malformed or
+ * provider-projected image never makes the surrounding surface unmeasurable.
+ */
+export const DEEPSEEK_VISION_DEFAULT_IMAGE_TOKENS = 256
+
+/** Stable identity for the deliberately approximate image-token counter. */
+export const DEEPSEEK_VISION_IMAGE_ESTIMATOR = Object.freeze({
+  id: `${DEEPSEEK_VISION_PROJECTION.sourceRepository}/image-token-estimate`,
+  revision: `${DEEPSEEK_VISION_PROJECTION.sourceRevision}:v1`,
+})
+
+/** Official `COMPRESS_PAD_TO` alignment constant from image_processor.py. */
+const COMPRESS_PAD_TO = 4
+
+/** Aligner-grid facts the official pipeline derives from one image. */
+export interface DeepSeekVisionImageGrid {
+  readonly nLlmH: number
+  readonly nLlmW: number
+  readonly bestHeight: number
+  readonly bestWidth: number
+}
+
+/** One bounded estimate over the four possible stream-alignment residues. */
+export interface DeepSeekVisionImageTokenEstimate {
+  readonly tokens: number
+  readonly upperBoundTokens: number
+  readonly source: 'intrinsic-grid' | 'default'
+  readonly paddingMinimumTokens?: number
+  readonly paddingMaximumTokens?: number
+}
+
+/**
+ * Whether one image's intrinsic metadata fits the adapter's documented
+ * default request pixel budget. This is informational only: estimation also
+ * accepts larger valid dimensions because the official processor enforces its
+ * own 384-token grid budget.
+ */
+export function isWithinDeepSeekRequestPixelBudget(width: number, height: number): boolean {
+  return width > 0 && height > 0 && width * height <= DEEPSEEK_VISION_PROJECTION.requestImagePixelBudget
+}
+
+/**
+ * Expand one image into its official token count at a given stream position.
+ *
+ * The count includes the position-dependent alignment padding from the
+ * official `build_image_block`: leading compress pads, the image start and end
+ * sentinels, one newline token per grid row, the odd-row pad, and the final
+ * two-token alignment pad. `startTokenPos` is the number of tokens already in
+ * the stream where this image's block begins, mirroring `len(tokens)` in the
+ * official `prepare_vl_inputs`.
+ */
+export function deepSeekVisionImageTokens(width: number, height: number, startTokenPos: number): number {
+  const grid = deepSeekVisionImageGrid(width, height)
+  return deepSeekVisionImageBlockTokens(grid.nLlmH, grid.nLlmW, startTokenPos)
+}
+
+/**
+ * Estimate one image without claiming an exact serialized position or final
+ * adapter projection. Valid intrinsic dimensions use the midpoint of the four
+ * possible alignment residues. Invalid or unsafe metadata uses the documented
+ * fixed fallback. In both cases the official per-image budget is retained as
+ * a conservative upper bound.
+ */
+export function estimateDeepSeekVisionImageTokens(
+  width: number,
+  height: number,
+): DeepSeekVisionImageTokenEstimate {
+  if (!Number.isSafeInteger(width) || !Number.isSafeInteger(height)
+    || width <= 0 || height <= 0 || !Number.isSafeInteger(width * height)) {
+    return Object.freeze({
+      tokens: DEEPSEEK_VISION_DEFAULT_IMAGE_TOKENS,
+      upperBoundTokens: DEEPSEEK_VISION_PROJECTION.visionMaxNTokens,
+      source: 'default',
+    })
+  }
+  try {
+    const grid = deepSeekVisionImageGrid(width, height)
+    const counts = [0, 1, 2, 3].map(position => (
+      deepSeekVisionImageBlockTokens(grid.nLlmH, grid.nLlmW, position)
+    ))
+    const paddingMinimumTokens = Math.min(...counts)
+    const paddingMaximumTokens = Math.max(...counts)
+    return Object.freeze({
+      tokens: Math.round((paddingMinimumTokens + paddingMaximumTokens) / 2),
+      upperBoundTokens: DEEPSEEK_VISION_PROJECTION.visionMaxNTokens,
+      source: 'intrinsic-grid',
+      paddingMinimumTokens,
+      paddingMaximumTokens,
+    })
+  } catch {
+    return Object.freeze({
+      tokens: DEEPSEEK_VISION_DEFAULT_IMAGE_TOKENS,
+      upperBoundTokens: DEEPSEEK_VISION_PROJECTION.visionMaxNTokens,
+      source: 'default',
+    })
+  }
+}
+
+/**
+ * Resolve the aligner grid for one image's intrinsic dimensions.
+ *
+ * Port of the arithmetic path of the official `load_image`: aspect-ratio
+ * clamp, minimum-pixel upscale, patch-grid ceiling, and the `safe_resize`
+ * budget loop.
+ */
+export function deepSeekVisionImageGrid(width: number, height: number): DeepSeekVisionImageGrid {
+  const { visionPatchSize: patch, visionMaxWhRatio, visionMinPixels } = DEEPSEEK_VISION_PROJECTION
+  let effectiveWidth: number = width
+  let effectiveHeight: number = height
+  if (visionMaxWhRatio !== undefined && effectiveWidth > effectiveHeight * visionMaxWhRatio) {
+    effectiveWidth = effectiveHeight * visionMaxWhRatio
+  }
+  if (effectiveWidth * effectiveHeight > 0 && effectiveWidth * effectiveHeight < visionMinPixels) {
+    const ratio = (visionMinPixels / (effectiveWidth * effectiveHeight)) ** 0.5
+    effectiveWidth = Math.trunc(effectiveWidth * ratio)
+    effectiveHeight = Math.trunc(effectiveHeight * ratio)
+  }
+  const bestWidth = Math.ceil(effectiveWidth / patch) * patch
+  const bestHeight = Math.ceil(effectiveHeight / patch) * patch
+  const resolved = safeResize(effectiveHeight, effectiveWidth, bestHeight, bestWidth)
+  return Object.freeze({ ...resolved })
+}
+
+/**
+ * Token count of one expanded image block, port of `build_image_block` length.
+ * @internal exported for direct golden-fixture comparison.
+ */
+export function deepSeekVisionImageBlockTokens(nLlmH: number, nLlmW: number, startTokenPos: number): number {
+  const compressPad = COMPRESS_PAD_TO - 1 - startTokenPos % COMPRESS_PAD_TO
+  const padH = nLlmH % 2
+  const rows = nLlmH + padH
+  const rowLen = nLlmW + 1
+  const padLast = (Math.floor(rows / 2) * rowLen % 2) * 2
+  return compressPad + 1 + rows * rowLen + padLast + 1
+}
+
+/** Port of the official `grid_tokens` N-layout occupancy check. */
+function gridTokens(bestHeight: number, bestWidth: number): { nLlmH: number, nLlmW: number, numTokens: number } {
+  const { visionPatchSize: patch, visionDownsampleRatio: downsample } = DEEPSEEK_VISION_PROJECTION
+  const nLlmH = Math.ceil(Math.floor(bestHeight / patch) / downsample)
+  const nLlmW = Math.ceil(Math.floor(bestWidth / patch) / downsample)
+  let numTokens = nLlmH * (nLlmW + 1) + 2
+  if (nLlmH % 2 === 1) {
+    numTokens += nLlmW + 1
+  }
+  numTokens += (Math.floor((nLlmH + 1) / 2) * (nLlmW + 1) % 2) * 2
+  return { nLlmH, nLlmW, numTokens }
+}
+
+/** Port of the official `solve_resize_ratio` budget solver. */
+function solveResizeRatio(
+  height: number,
+  width: number,
+  maxNTokens: number,
+): { nLlmH: number, nLlmW: number, bestHeight: number, bestWidth: number } {
+  const { visionPatchSize: patch, visionDownsampleRatio: downsample } = DEEPSEEK_VISION_PROJECTION
+  const ratio = height / width
+  const maxWFloat = Math.sqrt((maxNTokens - 2) / ratio + 0.25) - 0.5
+  const maxHFloat = maxWFloat * ratio
+  let bestWidth: number
+  let bestHeight: number
+  if (maxWFloat < 1.0) {
+    const maxW = 1
+    let maxH = Math.floor((maxNTokens - 2) / (maxW + 1))
+    if (maxH % 2 === 1) maxH -= 1
+    bestWidth = maxW * patch * downsample
+    bestHeight = maxH * patch * downsample
+  } else if (maxHFloat < 2.0) {
+    const maxH = 2
+    const maxW = Math.floor((maxNTokens - 2) / maxH) - 1
+    if (maxW <= 1) throw new Error('DeepSeek vision resize solver produced an invalid width')
+    bestWidth = maxW * patch * downsample
+    bestHeight = maxH * patch * downsample
+  } else {
+    const maxW = Math.floor(maxWFloat)
+    let maxH = Math.floor(maxHFloat)
+    if (maxH % 2 === 1) maxH -= 1
+    const beta = Math.min(maxW * patch * downsample / width, maxH * patch * downsample / height)
+    bestWidth = Math.floor(width * beta / patch) * patch
+    bestHeight = Math.floor(height * beta / patch) * patch
+  }
+  const grid = gridTokens(bestHeight, bestWidth)
+  return { nLlmH: grid.nLlmH, nLlmW: grid.nLlmW, bestHeight, bestWidth }
+}
+
+/** Port of the official `safe_resize` loop with the compress-pad budget. */
+function safeResize(
+  height: number,
+  width: number,
+  initialBestHeight: number,
+  initialBestWidth: number,
+): { nLlmH: number, nLlmW: number, bestHeight: number, bestWidth: number } {
+  const { visionMaxNTokens } = DEEPSEEK_VISION_PROJECTION
+  let budget = visionMaxNTokens - (COMPRESS_PAD_TO - 1)
+  let grid = gridTokens(initialBestHeight, initialBestWidth)
+  let bestHeight = initialBestHeight
+  let bestWidth = initialBestWidth
+  while (grid.numTokens > budget) {
+    const solved = solveResizeRatio(height, width, budget)
+    grid = gridTokens(solved.bestHeight, solved.bestWidth)
+    bestHeight = solved.bestHeight
+    bestWidth = solved.bestWidth
+    budget -= 1
+  }
+  return { nLlmH: grid.nLlmH, nLlmW: grid.nLlmW, bestHeight, bestWidth }
+}

package/packages/selector/src/runtime/measurement.ts

@@ -0,0 +1,403 @@
+/** Public-API-only measurement adapter for the standalone runtime. */
+
+import type { Context } from '@deepseek-ai/cordis'
+import type { ContentBlock, TokenUsage } from '@deepseek-ai/dsh-llm'
+import { deriveEventMessage } from '@deepseek-ai/dsh-session'
+import type { Session } from '@deepseek-ai/dsh-session'
+import type {} from '@deepseek-ai/dsh-token-meter'
+import type { TokenMeasurement } from '@deepseek-ai/dsh-token-meter'
+import {
+  DEEPSEEK_VISION_TOKENIZER_ARTIFACT,
+  deepSeekV4TokenizerForModel,
+} from '../deepseek-v4-tokenizer.ts'
+import {
+  DEEPSEEK_VISION_IMAGE_ESTIMATOR,
+  estimateDeepSeekVisionImageTokens,
+} from './deepseek-v4-vision-tokens.ts'
+import { unavailableTokenCount } from './token-count.ts'
+import { sessionEvents } from './session-events.ts'
+import type {
+  CanonicalTextTokenCounter,
+  ExactTokenizerTokenCount,
+  TokenCount,
+  TokenizerEstimateTokenCount,
+} from './token-count.ts'
+
+export type { TokenCount } from './token-count.ts'
+
+/** Request identity retained only when every dimension is publicly known. */
+export interface ProviderMeasurementKey {
+  readonly provider: string
+  readonly baseUrlClass: string
+  readonly apiRoute: string
+  readonly modelId: string
+  readonly requestTemplateRevision: string
+  readonly tokenizerRevision: string
+  readonly modality: string
+}
+
+/** Rich request observation used by Adaptive when a future public API supplies it. */
+export interface ObservedPromptUsage {
+  readonly attemptId: string
+  readonly providerRequestOrdinal: number
+  readonly startedAtMs: number
+  readonly completedAtMs: number
+  readonly measurement: TokenCount
+  readonly observedPromptTokens: number
+  readonly observedOutputTokens?: number
+  readonly responseModelId?: string
+  readonly cacheStatus?: 'complete' | 'unknown'
+  readonly cacheReadTokens?: number
+  readonly cacheMissTokens?: number
+  readonly key?: ProviderMeasurementKey
+}
+
+/** Metadata-only image dimensions; the pixel payload is never read or logged. */
+export interface CanonicalImageAttachment {
+  readonly width: number
+  readonly height: number
+}
+
+/**
+ * Intrinsic-grid diagnostic attached to nodes whose count estimates images.
+ * It reports ONLY the official block
+ * arithmetic evaluated on the attachment's intrinsic dimensions at the two
+ * alignment-padding extremes (compress-pad 0 and 3). It is NOT a request-token
+ * bound: the adapter may still re-project the image (per-route pixel-budget
+ * or image-detail overrides, byte-cap reprojection), which can move the real
+ * count below the diagnostic minimum. It never participates in exact gates,
+ * rewrite proofs, or any lossy decision.
+ */
+export interface IntrinsicImageBlockDiagnostic {
+  readonly paddingMinimumTokens: number
+  readonly paddingMaximumTokens: number
+}
+
+/** One same-revision surface node with exact, estimated, or unavailable count. */
+export interface MeasuredTokenSurfaceNode {
+  readonly seq: number
+  readonly count: TokenCount
+  /** Intrinsic-grid diagnostic when usable image dimensions were available. */
+  readonly intrinsicImageBlockEstimate?: IntrinsicImageBlockDiagnostic
+}
+
+/** Compression view derived only from published Session and TokenMeter methods. */
+export interface CompactionTokenView extends TokenMeasurement {
+  readonly providerRoute?: string
+  readonly modelId?: string
+  readonly measuredNodes: readonly MeasuredTokenSurfaceNode[]
+  readonly currentSurface: TokenCount
+  /** Sum of per-node intrinsic padding minima; a diagnostic, not a token bound. */
+  readonly intrinsicImageBlockEstimateTokens: number
+  readonly latestEnvelopeKey?: ProviderMeasurementKey
+  readonly lastCompletedUsage?: ObservedPromptUsage
+  countCanonicalText(text: string): TokenCount
+}
+
+/** Text plus image gating for one durable request target. */
+interface CanonicalCounter {
+  readonly countText: CanonicalTextTokenCounter
+  readonly countImage: (attachment: CanonicalImageAttachment) => TokenCount
+}
+
+const VISION_MODEL_ID = DEEPSEEK_VISION_TOKENIZER_ARTIFACT.modelIds[0] as string
+
+/**
+ * Capture one route-bound view without calling patched Harness methods.
+ * Official `measure()` remains authoritative for request pressure; the bundled
+ * tokenizer supplies exact canonical content counts used by safe rewrites.
+ */
+export function measureForCompaction(ctx: Context, session: Session): CompactionTokenView {
+  const header = session.requestHeader()
+  const measurement = ctx.tokenMeter.measure(session, header)
+  const target = header?.config
+  const counter = bindCounter(target?.provider, target?.model)
+  const events = sessionEvents(session)
+  const measuredNodes = measurement.nodes.map((node): MeasuredTokenSurfaceNode => {
+    const event = events[node.seq]
+    if (event === undefined) {
+      return { seq: node.seq, count: unavailableTokenCount(`surface node ${String(node.seq)} is missing`) }
+    }
+    const message = deriveEventMessage(event)
+    if (message === null) {
+      return { seq: node.seq, count: unavailableTokenCount(`surface node ${String(node.seq)} is not model-visible`) }
+    }
+    const count = countCanonicalContent(message.content, counter, `surface node ${String(node.seq)}`)
+    const intrinsicImageBlockEstimate = count.kind === 'tokenizer-estimate'
+      ? intrinsicImageDiagnostic(message.content, target)
+      : undefined
+    return {
+      seq: node.seq,
+      count,
+      ...intrinsicImageBlockEstimate === undefined ? {} : { intrinsicImageBlockEstimate },
+    }
+  })
+  const currentSurface = countSurfaceCounts(
+    measuredNodes.map(node => node.count),
+    'current surface',
+  )
+  const intrinsicImageBlockEstimateTokens = measuredNodes.reduce(
+    (sum, node) => sum + (node.intrinsicImageBlockEstimate?.paddingMinimumTokens ?? 0),
+    0,
+  )
+  return Object.freeze({
+    ...measurement,
+    ...(target === undefined ? {} : { providerRoute: target.provider, modelId: target.model }),
+    measuredNodes: Object.freeze(measuredNodes),
+    currentSurface,
+    intrinsicImageBlockEstimateTokens,
+    countCanonicalText: counter.countText,
+  })
+}
+
+/** Request-level usage exposed by official TokenMeter, without invented route attribution. */
+export function officialRequestUsage(view: CompactionTokenView): Readonly<TokenUsage> | undefined {
+  return view.baseline.kind === 'usage' ? view.baseline.usage : undefined
+}
+
+/**
+ * Count one canonical content walk in canonical field order.
+ *
+ * Text, reasoning, tool-call names/arguments, and nested text tool results are
+ * counted exactly with one tokenizer identity. Image blocks produce a bounded
+ * estimate because the absolute prompt position and the adapter's final
+ * projection are not publicly observable. A mixed text/image node is therefore
+ * an estimate and never qualifies for an exact rewrite proof.
+ */
+function countCanonicalContent(
+  blocks: readonly ContentBlock[],
+  counter: CanonicalCounter,
+  subject: string,
+): TokenCount {
+  let identity: ExactTokenizerTokenCount | undefined
+  let estimateIdentity: Pick<TokenizerEstimateTokenCount, 'estimatorId' | 'estimatorRevision'> | undefined
+  let tokens = 0
+  let upperBoundTokens = 0
+  let firstRefusal: TokenCount | undefined
+  const absorb = (count: TokenCount): boolean => {
+    if (count.kind === 'unavailable') {
+      firstRefusal ??= count
+      return false
+    }
+    if (count.kind === 'exact-tokenizer') {
+      if (identity !== undefined
+        && (identity.tokenizerId !== count.tokenizerId
+          || identity.tokenizerRevision !== count.tokenizerRevision)) {
+        firstRefusal ??= unavailableTokenCount(`${subject}: tokenizer identity changed within one measurement`)
+        return false
+      }
+      identity ??= count
+      tokens += count.tokens
+      upperBoundTokens += count.tokens
+    } else {
+      if (estimateIdentity !== undefined
+        && (estimateIdentity.estimatorId !== count.estimatorId
+          || estimateIdentity.estimatorRevision !== count.estimatorRevision)) {
+        firstRefusal ??= unavailableTokenCount(`${subject}: image estimator identity changed within one measurement`)
+        return false
+      }
+      estimateIdentity ??= {
+        estimatorId: count.estimatorId,
+        estimatorRevision: count.estimatorRevision,
+      }
+      tokens += count.tokens
+      upperBoundTokens += count.upperBoundTokens
+    }
+    return Number.isSafeInteger(tokens) && tokens >= 0
+      && Number.isSafeInteger(upperBoundTokens) && upperBoundTokens >= tokens
+  }
+  const walk = (content: readonly ContentBlock[]): boolean => {
+    for (const block of content) {
+      switch (block.type) {
+        case 'text':
+        case 'reasoning': {
+          if (!absorb(counter.countText(block.text))) return false
+          break
+        }
+        case 'tool-call': {
+          if (!absorb(counter.countText(block.name))) return false
+          if (!absorb(counter.countText(block.arguments))) return false
+          break
+        }
+        case 'tool-result': {
+          if (!walk(block.content)) return false
+          break
+        }
+        case 'image': {
+          if (!absorb(counter.countImage(block.attachment))) return false
+          break
+        }
+        default: {
+          firstRefusal ??= unavailableTokenCount(`${subject}: contains an unsupported content block`)
+          return false
+        }
+      }
+    }
+    return true
+  }
+  if (!walk(blocks)) {
+    if (firstRefusal?.kind === 'unavailable') {
+      return unavailableTokenCount(`${subject}: ${firstRefusal.reason}`)
+    }
+    return unavailableTokenCount(`${subject}: contains content the canonical counter cannot count exactly`)
+  }
+  if (identity === undefined && estimateIdentity === undefined) {
+    // Empty content is a legal durable shape; it keeps the exact-0 count with
+    // the bound tokenizer identity instead of fail-opening the whole surface.
+    const empty = counter.countText('')
+    if (empty.kind !== 'exact-tokenizer') return empty
+    return empty
+  }
+  if (!Number.isSafeInteger(tokens) || tokens < 0) {
+    return unavailableTokenCount(`${subject}: invalid token sum`)
+  }
+  if (estimateIdentity !== undefined) {
+    return Object.freeze({
+      kind: 'tokenizer-estimate',
+      ...estimateIdentity,
+      tokens,
+      upperBoundTokens,
+    })
+  }
+  if (identity === undefined) return unavailableTokenCount(`${subject}: no tokenizer identity`)
+  return Object.freeze({ ...identity, tokens })
+}
+
+function bindCounter(provider: string | undefined, model: string | undefined): CanonicalCounter {
+  if (provider === undefined || model === undefined) {
+    const unavailable = () => unavailableTokenCount('canonical text: no durable provider/model request header')
+    return { countText: unavailable, countImage: () => unavailableTokenCount('canonical image: no durable provider/model request header') }
+  }
+  if (provider !== 'deepseek' && provider !== 'deepseek-official') {
+    const reason = `canonical text: provider "${provider}" is not the supported DeepSeek route`
+    return { countText: () => unavailableTokenCount(reason), countImage: () => unavailableTokenCount(`canonical image: provider "${provider}" is not the supported DeepSeek route`) }
+  }
+  const tokenizer = deepSeekV4TokenizerForModel(model)
+  if (tokenizer === undefined) {
+    const reason = `canonical text: no verified bundled tokenizer for model "${model}"`
+    return {
+      countText: () => unavailableTokenCount(reason),
+      // Image arithmetic is independently pinned and does not need the text
+      // tokenizer asset. A pure-image node can therefore retain its estimate
+      // even when text measurement fails closed.
+      countImage: attachment => countCanonicalImage(model, attachment),
+    }
+  }
+  return {
+    countText: (text: string) => tokenizer.countText(text),
+    countImage: attachment => countCanonicalImage(model, attachment),
+  }
+}
+
+/**
+ * Images never claim an exact count. The official expansion depends on the
+ * absolute prompt position (system prompt, chat-template framing, adapter
+ * image handles) and on the adapter's final request-image projection, neither
+ * of which is exposed through a public API; a route may even override the
+ * pixel budget or re-project under the byte cap. Valid dimensions therefore
+ * use the midpoint of the four alignment residues as a bounded estimate;
+ * malformed dimensions use a fixed default. Estimate-bearing nodes remain
+ * ineligible for exact rewrite proofs.
+ */
+function countCanonicalImage(
+  model: string,
+  attachment: CanonicalImageAttachment,
+): TokenCount {
+  if (model !== VISION_MODEL_ID) {
+    return unavailableTokenCount(`canonical image: model "${model}" has no vision image counter`)
+  }
+  const estimate = estimateDeepSeekVisionImageTokens(attachment.width, attachment.height)
+  return Object.freeze({
+    kind: 'tokenizer-estimate',
+    tokens: estimate.tokens,
+    upperBoundTokens: estimate.upperBoundTokens,
+    estimatorId: DEEPSEEK_VISION_IMAGE_ESTIMATOR.id,
+    estimatorRevision: DEEPSEEK_VISION_IMAGE_ESTIMATOR.revision,
+  })
+}
+
+/**
+ * Intrinsic-grid diagnostic for one content walk: the official block
+ * arithmetic on intrinsic dimensions at both alignment extremes. Only images
+ * on the pinned DeepSeek vision route with usable metadata contribute.
+ */
+function intrinsicImageDiagnostic(
+  blocks: readonly ContentBlock[],
+  target: { readonly provider: string, readonly model: string } | undefined,
+): IntrinsicImageBlockDiagnostic | undefined {
+  // Mirror the gating route: only the DeepSeek vision route carries the
+  // official-arithmetic bounds.
+  if (target === undefined
+    || (target.provider !== 'deepseek' && target.provider !== 'deepseek-official')
+    || target.model !== VISION_MODEL_ID) return undefined
+  let paddingMinimumTokens = 0
+  let paddingMaximumTokens = 0
+  let seen = false
+  const walk = (content: readonly ContentBlock[]): void => {
+    for (const block of content) {
+      if (block.type === 'image') {
+        const { width, height } = block.attachment
+        const estimate = estimateDeepSeekVisionImageTokens(width, height)
+        if (estimate.source !== 'intrinsic-grid'
+          || estimate.paddingMinimumTokens === undefined
+          || estimate.paddingMaximumTokens === undefined) continue
+        paddingMinimumTokens += estimate.paddingMinimumTokens
+        paddingMaximumTokens += estimate.paddingMaximumTokens
+        seen = true
+      } else if (block.type === 'tool-result') {
+        walk(block.content)
+      }
+    }
+  }
+  walk(blocks)
+  return seen ? Object.freeze({ paddingMinimumTokens, paddingMaximumTokens }) : undefined
+}
+
+function countSurfaceCounts(counts: readonly TokenCount[], subject: string): TokenCount {
+  if (counts.length === 0) return unavailableTokenCount(`${subject}: no surface nodes`)
+  let identity: Extract<TokenCount, { kind: 'exact-tokenizer' }> | undefined
+  let estimateIdentity: Pick<TokenizerEstimateTokenCount, 'estimatorId' | 'estimatorRevision'> | undefined
+  let tokens = 0
+  let upperBoundTokens = 0
+  for (const count of counts) {
+    if (count.kind === 'unavailable') {
+      return unavailableTokenCount(`${subject}: ${count.reason}`)
+    }
+    if (count.kind === 'exact-tokenizer') {
+      if (identity !== undefined
+        && (identity.tokenizerId !== count.tokenizerId
+          || identity.tokenizerRevision !== count.tokenizerRevision)) {
+        return unavailableTokenCount(`${subject}: tokenizer identity changed within one measurement`)
+      }
+      identity ??= count
+      tokens += count.tokens
+      upperBoundTokens += count.tokens
+    } else {
+      if (estimateIdentity !== undefined
+        && (estimateIdentity.estimatorId !== count.estimatorId
+          || estimateIdentity.estimatorRevision !== count.estimatorRevision)) {
+        return unavailableTokenCount(`${subject}: image estimator identity changed within one measurement`)
+      }
+      estimateIdentity ??= {
+        estimatorId: count.estimatorId,
+        estimatorRevision: count.estimatorRevision,
+      }
+      tokens += count.tokens
+      upperBoundTokens += count.upperBoundTokens
+    }
+  }
+  if (!Number.isSafeInteger(tokens) || tokens < 0
+    || !Number.isSafeInteger(upperBoundTokens) || upperBoundTokens < tokens) {
+    return unavailableTokenCount(`${subject}: invalid token sum`)
+  }
+  if (estimateIdentity !== undefined) {
+    return Object.freeze({
+      kind: 'tokenizer-estimate',
+      ...estimateIdentity,
+      tokens,
+      upperBoundTokens,
+    })
+  }
+  if (identity === undefined) return unavailableTokenCount(`${subject}: no tokenizer identity`)
+  return Object.freeze({ ...identity, tokens })
+}