dsh-llm-verifier 0.1.13 → 0.1.14

package/src/cache.ts

@@ -1,115 +1,115 @@
-import { createHash } from 'node:crypto'
-import { mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises'
-import { dirname, isAbsolute, join, resolve } from 'node:path'
-import type { UsageStats } from './caller.ts'
-
-export interface CachedPairScore {
-  scoreA: number
-  scoreB: number
-  usage: UsageStats
-  scoringMode: 'top-logprobs' | 'explicit-tag'
-  createdAt: number
-}
-
-interface CacheDocument {
-  version: 1
-  entries: Record<string, CachedPairScore>
-}
-
-export function stableHash(value: unknown): string {
-  return createHash('sha256').update(JSON.stringify(value)).digest('hex')
-}
-
-export function resolveCacheFile(cacheDir: string, cwd = process.cwd()): string {
-  const root = isAbsolute(cacheDir) ? cacheDir : resolve(cwd, cacheDir)
-  return join(root, 'scores-v1.json')
-}
-
-function validUsage(value: unknown): value is UsageStats {
-  if (typeof value !== 'object' || value === null) return false
-  const row = value as Record<string, unknown>
-  return ['calls', 'attempts', 'retries', 'inputTokens', 'cachedInputTokens', 'outputTokens', 'reasoningTokens'].every(key => typeof row[key] === 'number' && Number.isFinite(row[key]) && Number(row[key]) >= 0)
-}
-
-function validEntry(value: unknown): value is CachedPairScore {
-  if (typeof value !== 'object' || value === null) return false
-  const row = value as Record<string, unknown>
-  return typeof row.scoreA === 'number' && Number.isFinite(row.scoreA) && row.scoreA >= 0 && row.scoreA <= 1 && typeof row.scoreB === 'number' && Number.isFinite(row.scoreB) && row.scoreB >= 0 && row.scoreB <= 1 && validUsage(row.usage) && (row.scoringMode === undefined || row.scoringMode === 'top-logprobs' || row.scoringMode === 'explicit-tag') && typeof row.createdAt === 'number' && Number.isFinite(row.createdAt) && row.createdAt >= 0
-}
-
-/** Channel-independent single-flight: concurrent identical tasks share one promise; joiners are flagged so callers can avoid double-counting usage. */
-export class SingleFlight<T> {
-  private readonly flights = new Map<string, Promise<T>>()
-  async run(key: string, task: () => Promise<T>): Promise<{ value: T; joined: boolean }> {
-    const existing = this.flights.get(key)
-    if (existing !== undefined) return { value: await existing, joined: true }
-    // task() starts synchronously so the flight is registered before its first await.
-    const flight = task().finally(() => { if (this.flights.get(key) === flight) this.flights.delete(key) })
-    this.flights.set(key, flight)
-    return { value: await flight, joined: false }
-  }
-}
-
-export class ScoreCache {
-  private readonly file: string
-  private readonly maxEntries: number
-  private loaded = false
-  private entries = new Map<string, CachedPairScore>()
-  private readonly inflight = new Map<string, Promise<{ value: CachedPairScore; key: string }>>()
-  private writing: Promise<void> = Promise.resolve()
-
-  constructor(file: string, maxEntries: number) {
-    this.file = file
-    this.maxEntries = maxEntries
-  }
-
-  async load(): Promise<void> {
-    if (this.loaded) return
-    this.loaded = true
-    try {
-      const document = JSON.parse(await readFile(this.file, 'utf8')) as CacheDocument
-      if (document.version !== 1 || typeof document.entries !== 'object' || document.entries === null) return
-      this.entries = new Map(Object.entries(document.entries).filter((entry): entry is [string, CachedPairScore] => validEntry(entry[1])).map(([key, value]) => [key, { ...value, scoringMode: value.scoringMode ?? 'explicit-tag' }]))
-    } catch (error) {
-      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
-    }
-  }
-
-  async getOrCreate(key: string, create: () => Promise<CachedPairScore>, keyFor: (value: CachedPairScore) => string = () => key): Promise<{ value: CachedPairScore; hit: boolean }> {
-    await this.load()
-    const cached = this.entries.get(key)
-    if (cached !== undefined) return { value: cached, hit: true }
-    const existing = this.inflight.get(key)
-    if (existing !== undefined) return { value: (await existing).value, hit: true }
-    // The storage key may differ from the lookup key when the actual scoring mode
-    // differs from the predicted one (first-call logprobs downgrade).
-    const pending = create().then(value => ({ value, key: keyFor(value) }))
-    this.inflight.set(key, pending)
-    try {
-      const landed = await pending
-      this.entries.set(landed.key, landed.value)
-      this.trim()
-      await this.persist()
-      return { value: landed.value, hit: false }
-    } finally {
-      this.inflight.delete(key)
-    }
-  }
-
-  private trim(): void {
-    if (this.entries.size <= this.maxEntries) return
-    const sorted = [...this.entries].sort((a, b) => a[1].createdAt - b[1].createdAt)
-    for (let index = 0; index < sorted.length - this.maxEntries; index += 1) this.entries.delete(sorted[index]![0])
-  }
-
-  private async persist(): Promise<void> {
-    const snapshot: CacheDocument = { version: 1, entries: Object.fromEntries(this.entries) }
-    this.writing = this.writing.catch(() => {}).then(async () => {
-      await mkdir(dirname(this.file), { recursive: true })
-      const temporary = this.file + '.tmp-' + process.pid
-      await writeFile(temporary, JSON.stringify(snapshot), 'utf8')
-      try { await rename(temporary, this.file) } catch (error) { await unlink(temporary).catch(() => {}); throw error }
-    })
-    await this.writing
-  }
-}
+import { createHash } from 'node:crypto'
+import { mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises'
+import { dirname, isAbsolute, join, resolve } from 'node:path'
+import type { UsageStats } from './caller.ts'
+
+export interface CachedPairScore {
+  scoreA: number
+  scoreB: number
+  usage: UsageStats
+  scoringMode: 'top-logprobs' | 'explicit-tag'
+  createdAt: number
+}
+
+interface CacheDocument {
+  version: 1
+  entries: Record<string, CachedPairScore>
+}
+
+export function stableHash(value: unknown): string {
+  return createHash('sha256').update(JSON.stringify(value)).digest('hex')
+}
+
+export function resolveCacheFile(cacheDir: string, cwd = process.cwd()): string {
+  const root = isAbsolute(cacheDir) ? cacheDir : resolve(cwd, cacheDir)
+  return join(root, 'scores-v1.json')
+}
+
+function validUsage(value: unknown): value is UsageStats {
+  if (typeof value !== 'object' || value === null) return false
+  const row = value as Record<string, unknown>
+  return ['calls', 'attempts', 'retries', 'inputTokens', 'cachedInputTokens', 'outputTokens', 'reasoningTokens'].every(key => typeof row[key] === 'number' && Number.isFinite(row[key]) && Number(row[key]) >= 0)
+}
+
+function validEntry(value: unknown): value is CachedPairScore {
+  if (typeof value !== 'object' || value === null) return false
+  const row = value as Record<string, unknown>
+  return typeof row.scoreA === 'number' && Number.isFinite(row.scoreA) && row.scoreA >= 0 && row.scoreA <= 1 && typeof row.scoreB === 'number' && Number.isFinite(row.scoreB) && row.scoreB >= 0 && row.scoreB <= 1 && validUsage(row.usage) && (row.scoringMode === undefined || row.scoringMode === 'top-logprobs' || row.scoringMode === 'explicit-tag') && typeof row.createdAt === 'number' && Number.isFinite(row.createdAt) && row.createdAt >= 0
+}
+
+/** Channel-independent single-flight: concurrent identical tasks share one promise; joiners are flagged so callers can avoid double-counting usage. */
+export class SingleFlight<T> {
+  private readonly flights = new Map<string, Promise<T>>()
+  async run(key: string, task: () => Promise<T>): Promise<{ value: T; joined: boolean }> {
+    const existing = this.flights.get(key)
+    if (existing !== undefined) return { value: await existing, joined: true }
+    // task() starts synchronously so the flight is registered before its first await.
+    const flight = task().finally(() => { if (this.flights.get(key) === flight) this.flights.delete(key) })
+    this.flights.set(key, flight)
+    return { value: await flight, joined: false }
+  }
+}
+
+export class ScoreCache {
+  private readonly file: string
+  private readonly maxEntries: number
+  private loaded = false
+  private entries = new Map<string, CachedPairScore>()
+  private readonly inflight = new Map<string, Promise<{ value: CachedPairScore; key: string }>>()
+  private writing: Promise<void> = Promise.resolve()
+
+  constructor(file: string, maxEntries: number) {
+    this.file = file
+    this.maxEntries = maxEntries
+  }
+
+  async load(): Promise<void> {
+    if (this.loaded) return
+    this.loaded = true
+    try {
+      const document = JSON.parse(await readFile(this.file, 'utf8')) as CacheDocument
+      if (document.version !== 1 || typeof document.entries !== 'object' || document.entries === null) return
+      this.entries = new Map(Object.entries(document.entries).filter((entry): entry is [string, CachedPairScore] => validEntry(entry[1])).map(([key, value]) => [key, { ...value, scoringMode: value.scoringMode ?? 'explicit-tag' }]))
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
+    }
+  }
+
+  async getOrCreate(key: string, create: () => Promise<CachedPairScore>, keyFor: (value: CachedPairScore) => string = () => key): Promise<{ value: CachedPairScore; hit: boolean }> {
+    await this.load()
+    const cached = this.entries.get(key)
+    if (cached !== undefined) return { value: cached, hit: true }
+    const existing = this.inflight.get(key)
+    if (existing !== undefined) return { value: (await existing).value, hit: true }
+    // The storage key may differ from the lookup key when the actual scoring mode
+    // differs from the predicted one (first-call logprobs downgrade).
+    const pending = create().then(value => ({ value, key: keyFor(value) }))
+    this.inflight.set(key, pending)
+    try {
+      const landed = await pending
+      this.entries.set(landed.key, landed.value)
+      this.trim()
+      await this.persist()
+      return { value: landed.value, hit: false }
+    } finally {
+      this.inflight.delete(key)
+    }
+  }
+
+  private trim(): void {
+    if (this.entries.size <= this.maxEntries) return
+    const sorted = [...this.entries].sort((a, b) => a[1].createdAt - b[1].createdAt)
+    for (let index = 0; index < sorted.length - this.maxEntries; index += 1) this.entries.delete(sorted[index]![0])
+  }
+
+  private async persist(): Promise<void> {
+    const snapshot: CacheDocument = { version: 1, entries: Object.fromEntries(this.entries) }
+    this.writing = this.writing.catch(() => {}).then(async () => {
+      await mkdir(dirname(this.file), { recursive: true })
+      const temporary = this.file + '.tmp-' + process.pid
+      await writeFile(temporary, JSON.stringify(snapshot), 'utf8')
+      try { await rename(temporary, this.file) } catch (error) { await unlink(temporary).catch(() => {}); throw error }
+    })
+    await this.writing
+  }
+}

package/src/caller.test.ts

@@ -1,34 +1,34 @@
-import { afterEach, describe, expect, it, vi } from 'vitest'
-import { callVerifier } from './caller.ts'
-import { TopLogprobCapabilityCache } from './top-logprobs.ts'
-
-function chunks(text = '<score_A> A </score_A>') { return [{ type: 'block-start', index: 0, blockType: 'text' }, { type: 'text-delta', index: 0, text }, { type: 'block-end', index: 0, block: { type: 'text', text } }, { type: 'usage', usage: { inputTokens: 7, cacheReadTokens: 3, outputTokens: 4, reasoningTokens: 2 } }, { type: 'finish', reason: { kind: 'stop' } }] as any[] }
-function ctx(settingsValue?: unknown) { return { get(name: string) { if (name === 'settings' && settingsValue !== undefined) return { get: () => settingsValue }; if (name === 'credentials') return { resolve: async () => ({ value: 'secret' }) }; return undefined } } as any }
-function config(stream: (options: any) => AsyncIterable<any>, saveImage = vi.fn(), context = ctx()) { return { ctx: context, llm: { stream } as any, attachments: { saveImage } as any, topLogprobCapabilities: new TopLogprobCapabilityCache(), provider: 'openai', model: 'gpt-5', reasoningEffort: 'high', maxTokens: 100, timeoutMs: 1000, maxRetries: 2, retryBaseDelayMs: 1 } }
-async function* streamOf(items: any[]) { for (const item of items) yield item }
-afterEach(() => vi.unstubAllGlobals())
-
-describe('automatic verifier scoring', () => {
-  it('falls back to explicit A-T tags when the route has no safe logprob transport', async () => {
-    let seen: any
-    const result = await callVerifier(config(async function* (options) { seen = options; yield* streamOf(chunks()) }), 'prompt')
-    expect(seen.provider).toBe('openai'); expect(result.scoringMode).toBe('explicit-tag')
-  })
-  it('uses top-logprob distributions on an explicit OpenAI-compatible route', async () => {
-    const body = { choices: [{ message: { content: '<score_A> A </score_A>' }, logprobs: { content: [{ token: '<score_A>', logprob: 0, top_logprobs: [] }, { token: 'A', logprob: -0.1, top_logprobs: [{ token: 'A', logprob: Math.log(0.7) }, { token: 'T', logprob: Math.log(0.3) }] }] } }], usage: { prompt_tokens: 10, completion_tokens: 2 } }
-    vi.stubGlobal('fetch', vi.fn(async () => new Response(JSON.stringify(body), { status: 200 })))
-    let streamed = false
-    const context = ctx({ providers: { openai: { api: 'openai-completions', baseURL: 'https://example.test/v1', apiKeyEnv: 'OPENAI_API_KEY' } } })
-    const result = await callVerifier(config(async function* () { streamed = true; yield* streamOf(chunks()) }, vi.fn(), context), 'prompt')
-    expect(result.scoringMode).toBe('top-logprobs'); expect(result.positions[1]?.length).toBe(2); expect(streamed).toBe(false)
-  })
-  it('remembers a provider logprob rejection and falls back through DSH', async () => {
-    const fetcher = vi.fn(async () => new Response('{"error":{"message":"logprobs unsupported"}}', { status: 400 }))
-    vi.stubGlobal('fetch', fetcher)
-    const context = ctx({ providers: { openai: { api: 'openai-completions', baseURL: 'https://example.test/v1' } } })
-    const cfg = config(async function* () { yield* streamOf(chunks()) }, vi.fn(), context)
-    expect((await callVerifier(cfg, 'prompt')).scoringMode).toBe('explicit-tag')
-    expect((await callVerifier(cfg, 'prompt2')).scoringMode).toBe('explicit-tag')
-    expect(fetcher).toHaveBeenCalledTimes(1)
-  })
-})
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { callVerifier } from './caller.ts'
+import { TopLogprobCapabilityCache } from './top-logprobs.ts'
+
+function chunks(text = '<score_A> A </score_A>') { return [{ type: 'block-start', index: 0, blockType: 'text' }, { type: 'text-delta', index: 0, text }, { type: 'block-end', index: 0, block: { type: 'text', text } }, { type: 'usage', usage: { inputTokens: 7, cacheReadTokens: 3, outputTokens: 4, reasoningTokens: 2 } }, { type: 'finish', reason: { kind: 'stop' } }] as any[] }
+function ctx(settingsValue?: unknown) { return { get(name: string) { if (name === 'settings' && settingsValue !== undefined) return { get: () => settingsValue }; if (name === 'credentials') return { resolve: async () => ({ value: 'secret' }) }; return undefined } } as any }
+function config(stream: (options: any) => AsyncIterable<any>, saveImage = vi.fn(), context = ctx()) { return { ctx: context, llm: { stream } as any, attachments: { saveImage } as any, topLogprobCapabilities: new TopLogprobCapabilityCache(), provider: 'openai', model: 'gpt-5', reasoningEffort: 'high', maxTokens: 100, timeoutMs: 1000, maxRetries: 2, retryBaseDelayMs: 1 } }
+async function* streamOf(items: any[]) { for (const item of items) yield item }
+afterEach(() => vi.unstubAllGlobals())
+
+describe('automatic verifier scoring', () => {
+  it('falls back to explicit A-T tags when the route has no safe logprob transport', async () => {
+    let seen: any
+    const result = await callVerifier(config(async function* (options) { seen = options; yield* streamOf(chunks()) }), 'prompt')
+    expect(seen.provider).toBe('openai'); expect(result.scoringMode).toBe('explicit-tag')
+  })
+  it('uses top-logprob distributions on an explicit OpenAI-compatible route', async () => {
+    const body = { choices: [{ message: { content: '<score_A> A </score_A>' }, logprobs: { content: [{ token: '<score_A>', logprob: 0, top_logprobs: [] }, { token: 'A', logprob: -0.1, top_logprobs: [{ token: 'A', logprob: Math.log(0.7) }, { token: 'T', logprob: Math.log(0.3) }] }] } }], usage: { prompt_tokens: 10, completion_tokens: 2 } }
+    vi.stubGlobal('fetch', vi.fn(async () => new Response(JSON.stringify(body), { status: 200 })))
+    let streamed = false
+    const context = ctx({ providers: { openai: { api: 'openai-completions', baseURL: 'https://example.test/v1', apiKeyEnv: 'OPENAI_API_KEY' } } })
+    const result = await callVerifier(config(async function* () { streamed = true; yield* streamOf(chunks()) }, vi.fn(), context), 'prompt')
+    expect(result.scoringMode).toBe('top-logprobs'); expect(result.positions[1]?.length).toBe(2); expect(streamed).toBe(false)
+  })
+  it('remembers a provider logprob rejection and falls back through DSH', async () => {
+    const fetcher = vi.fn(async () => new Response('{"error":{"message":"logprobs unsupported"}}', { status: 400 }))
+    vi.stubGlobal('fetch', fetcher)
+    const context = ctx({ providers: { openai: { api: 'openai-completions', baseURL: 'https://example.test/v1' } } })
+    const cfg = config(async function* () { yield* streamOf(chunks()) }, vi.fn(), context)
+    expect((await callVerifier(cfg, 'prompt')).scoringMode).toBe('explicit-tag')
+    expect((await callVerifier(cfg, 'prompt2')).scoringMode).toBe('explicit-tag')
+    expect(fetcher).toHaveBeenCalledTimes(1)
+  })
+})

package/src/caller.ts

@@ -13,154 +13,154 @@ function deepFreeze<T>(value: T): T {
     }
   }
   return value
-}
-import type { AttachmentStore } from '@deepseek-ai/dsh-attachment'
-import type { CompletionLogprobs } from './core.ts'
-import { TopLogprobCapabilityCache, TopLogprobsUnsupportedError, callTopLogprobs, resolveTopLogprobRoute } from './top-logprobs.ts'
-import type { Context } from '@deepseek-ai/cordis'
-
-export interface VerifierClientConfig {
-  ctx: Context
-  llm: LlmRuntime
-  attachments: AttachmentStore
-  topLogprobCapabilities: TopLogprobCapabilityCache
-  provider: string
-  model: string
-  reasoningEffort?: string
-  maxTokens: number
-  timeoutMs: number
-  maxRetries: number
-  retryBaseDelayMs: number
-  limiter?: RequestLimiter
-}
-
-export interface VerifierImage {
-  data: Uint8Array
-  mediaType: 'image/png' | 'image/jpeg' | 'image/webp' | 'image/gif'
-}
-
-export interface UsageStats {
-  calls: number
-  attempts: number
-  retries: number
-  inputTokens: number
-  cachedInputTokens: number
-  outputTokens: number
-  reasoningTokens: number
-}
-
-export type ScoringMode = 'top-logprobs' | 'explicit-tag'
-export interface VerifierCompletion extends CompletionLogprobs { usage: UsageStats; scoringMode: ScoringMode }
-
-function failureMessage(finish: FinishReason): string | undefined {
-  if (finish.kind === 'error' || finish.kind === 'aborted') return finish.failure.message
-  if (finish.kind === 'max-tokens') return 'verifier response reached max tokens before completing its answer'
-  return undefined
-}
-
-async function delay(ms: number, signal?: AbortSignal): Promise<void> {
-  if (signal?.aborted) throw signal.reason
-  await new Promise<void>((resolve, reject) => {
-    const timer = setTimeout(resolve, ms)
-    const abort = () => { clearTimeout(timer); reject(signal?.reason) }
-    signal?.addEventListener('abort', abort, { once: true })
-  })
-}
-
-function usage(attempts: number, value = {} as { inputTokens?: number; outputTokens?: number; cacheReadTokens?: number; cacheWriteTokens?: number; reasoningTokens?: number }): UsageStats {
-  return { calls: 1, attempts, retries: attempts - 1, inputTokens: value.inputTokens ?? 0, cachedInputTokens: (value.cacheReadTokens ?? 0) + (value.cacheWriteTokens ?? 0), outputTokens: value.outputTokens ?? 0, reasoningTokens: value.reasoningTokens ?? 0 }
-}
-
-async function callExplicitTag(config: VerifierClientConfig, prompt: string, signal?: AbortSignal, images?: readonly VerifierImage[]): Promise<VerifierCompletion> {
-  let attempt = 0
-  while (true) {
-    attempt += 1
-    const controller = new AbortController()
-    const timeout = setTimeout(() => controller.abort(new Error('llm-verifier: request timed out')), config.timeoutMs)
-    const abort = () => controller.abort(signal?.reason)
-    signal?.addEventListener('abort', abort, { once: true })
-    try {
-      const content: ContentBlock[] = [{ type: 'text', text: prompt }]
-      for (const image of images ?? []) {
-        const ref = await config.attachments.saveImage({ data: image.data, mediaType: image.mediaType })
-        content.push({ type: 'image', attachment: ref })
-      }
-      const messages = [createUserMessage({ content, source: { kind: 'plugin', plugin: 'dsh-llm-verifier' } })]
-      const assembler = new BlockAssembler()
-      const options = deepFreeze({
-        provider: config.provider,
-        model: config.model,
-        ...(config.reasoningEffort ? { reasoningEffort: ReasoningEffortId(config.reasoningEffort) } : {}),
-        messages,
-        maxTokens: config.maxTokens,
-        temperature: 1,
-        signal: controller.signal,
-      })
-      for await (const chunk of config.llm.stream(options)) assembler.push(chunk)
-      const failed = failureMessage(assembler.finish)
-      if (failed !== undefined) throw new Error('llm-verifier: model call failed: ' + failed)
-      const text = assembler.blocks().filter((block): block is Extract<ContentBlock, { type: 'text' }> => block.type === 'text').map(block => block.text).join('')
-      if (!text.trim()) throw new Error('llm-verifier: selected DSH model produced no text')
-      // DSH adapters expose provider-neutral text/usage but not top-logprob candidates.
-      // extractScore() therefore uses the model's explicit final A–T tags.
-      return { text, tokens: [], positions: [], scoringMode: 'explicit-tag', usage: usage(attempt, assembler.usage) }
-    } catch (error) {
-      if (signal?.aborted) throw signal.reason
-      if (attempt > config.maxRetries || !(error instanceof Error) || !/rate|quota|timeout|timed out|temporar|network|fetch|socket|5\d\d/i.test(error.message)) throw error
-      await delay(Math.min(30000, config.retryBaseDelayMs * 2 ** (attempt - 1) * (0.8 + Math.random() * 0.4)), signal)
-    } finally {
-      clearTimeout(timeout)
-      signal?.removeEventListener('abort', abort)
-    }
-  }
-}
-
-export class RequestLimiter {
-  private active = 0
-  private readonly queue: Array<() => void> = []
-  constructor(readonly limit: number) { if (!Number.isSafeInteger(limit) || limit < 1) throw new Error('llm-verifier: request concurrency limit must be a positive integer') }
-  async run<T>(operation: () => Promise<T>, signal?: AbortSignal): Promise<T> {
-    if (this.active >= this.limit) await new Promise<void>((resolve, reject) => {
-      const enter = () => { signal?.removeEventListener('abort', abort); resolve() }
-      const abort = () => { const index = this.queue.indexOf(enter); if (index >= 0) this.queue.splice(index, 1); reject(signal?.reason) }
-      this.queue.push(enter); signal?.addEventListener('abort', abort, { once: true })
-    })
-    if (signal?.aborted) throw signal.reason
-    this.active += 1
-    try { return await operation() } finally { this.active -= 1; this.queue.shift()?.() }
-  }
-}
-
-/** Best-effort pre-call channel prediction for cache identity only; callAutomatic() stays the runtime source of truth. */
-export async function predictScoringChannel(config: VerifierClientConfig): Promise<ScoringMode> {
-  await config.topLogprobCapabilities.ensureLoaded()
-  return config.topLogprobCapabilities.isUnsupported(config.provider, config.model) ? 'explicit-tag' : 'top-logprobs'
-}
-
-async function callAutomatic(config: VerifierClientConfig, prompt: string, signal?: AbortSignal, images?: readonly VerifierImage[]): Promise<VerifierCompletion> {
-  await config.topLogprobCapabilities.ensureLoaded()
-  if (!config.topLogprobCapabilities.isUnsupported(config.provider, config.model)) {
-    const route = await resolveTopLogprobRoute(config.ctx, config.provider)
-    if (route !== undefined) {
-      try { return await callTopLogprobs(route, config.model, prompt, config.maxTokens, config.reasoningEffort, signal, images) }
-      catch (error) {
-        if (!(error instanceof TopLogprobsUnsupportedError)) throw error
-        config.topLogprobCapabilities.markUnsupported(config.provider, config.model)
-      }
-    } else config.topLogprobCapabilities.markUnsupported(config.provider, config.model)
-  }
-  return callExplicitTag(config, prompt, signal, images)
-}
-
-export async function callVerifier(config: VerifierClientConfig, prompt: string, signal?: AbortSignal, images?: readonly VerifierImage[]): Promise<VerifierCompletion> {
-  const invoke = () => callAutomatic(config, prompt, signal, images)
-  return config.limiter === undefined ? invoke() : config.limiter.run(invoke, signal)
-}
-
-/** Plain-text verifier call for conservative JSON routing; probability labels are intentionally bypassed. */
-export async function callVerifierText(config: VerifierClientConfig, prompt: string, signal?: AbortSignal): Promise<VerifierCompletion> {
-  const invoke = () => callExplicitTag(config, prompt, signal)
-  return config.limiter === undefined ? invoke() : config.limiter.run(invoke, signal)
-}
-export function addUsage(target: UsageStats, source: UsageStats): void { for (const key of ['calls', 'attempts', 'retries', 'inputTokens', 'cachedInputTokens', 'outputTokens', 'reasoningTokens'] as const) target[key] += source[key] }
-export function emptyUsage(): UsageStats { return { calls: 0, attempts: 0, retries: 0, inputTokens: 0, cachedInputTokens: 0, outputTokens: 0, reasoningTokens: 0 } }
+}
+import type { AttachmentStore } from '@deepseek-ai/dsh-attachment'
+import type { CompletionLogprobs } from './core.ts'
+import { TopLogprobCapabilityCache, TopLogprobsUnsupportedError, callTopLogprobs, resolveTopLogprobRoute } from './top-logprobs.ts'
+import type { Context } from '@deepseek-ai/cordis'
+
+export interface VerifierClientConfig {
+  ctx: Context
+  llm: LlmRuntime
+  attachments: AttachmentStore
+  topLogprobCapabilities: TopLogprobCapabilityCache
+  provider: string
+  model: string
+  reasoningEffort?: string
+  maxTokens: number
+  timeoutMs: number
+  maxRetries: number
+  retryBaseDelayMs: number
+  limiter?: RequestLimiter
+}
+
+export interface VerifierImage {
+  data: Uint8Array
+  mediaType: 'image/png' | 'image/jpeg' | 'image/webp' | 'image/gif'
+}
+
+export interface UsageStats {
+  calls: number
+  attempts: number
+  retries: number
+  inputTokens: number
+  cachedInputTokens: number
+  outputTokens: number
+  reasoningTokens: number
+}
+
+export type ScoringMode = 'top-logprobs' | 'explicit-tag'
+export interface VerifierCompletion extends CompletionLogprobs { usage: UsageStats; scoringMode: ScoringMode }
+
+function failureMessage(finish: FinishReason): string | undefined {
+  if (finish.kind === 'error' || finish.kind === 'aborted') return finish.failure.message
+  if (finish.kind === 'max-tokens') return 'verifier response reached max tokens before completing its answer'
+  return undefined
+}
+
+async function delay(ms: number, signal?: AbortSignal): Promise<void> {
+  if (signal?.aborted) throw signal.reason
+  await new Promise<void>((resolve, reject) => {
+    const timer = setTimeout(resolve, ms)
+    const abort = () => { clearTimeout(timer); reject(signal?.reason) }
+    signal?.addEventListener('abort', abort, { once: true })
+  })
+}
+
+function usage(attempts: number, value = {} as { inputTokens?: number; outputTokens?: number; cacheReadTokens?: number; cacheWriteTokens?: number; reasoningTokens?: number }): UsageStats {
+  return { calls: 1, attempts, retries: attempts - 1, inputTokens: value.inputTokens ?? 0, cachedInputTokens: (value.cacheReadTokens ?? 0) + (value.cacheWriteTokens ?? 0), outputTokens: value.outputTokens ?? 0, reasoningTokens: value.reasoningTokens ?? 0 }
+}
+
+async function callExplicitTag(config: VerifierClientConfig, prompt: string, signal?: AbortSignal, images?: readonly VerifierImage[]): Promise<VerifierCompletion> {
+  let attempt = 0
+  while (true) {
+    attempt += 1
+    const controller = new AbortController()
+    const timeout = setTimeout(() => controller.abort(new Error('llm-verifier: request timed out')), config.timeoutMs)
+    const abort = () => controller.abort(signal?.reason)
+    signal?.addEventListener('abort', abort, { once: true })
+    try {
+      const content: ContentBlock[] = [{ type: 'text', text: prompt }]
+      for (const image of images ?? []) {
+        const ref = await config.attachments.saveImage({ data: image.data, mediaType: image.mediaType })
+        content.push({ type: 'image', attachment: ref })
+      }
+      const messages = [createUserMessage({ content, source: { kind: 'plugin', plugin: 'dsh-llm-verifier' } })]
+      const assembler = new BlockAssembler()
+      const options = deepFreeze({
+        provider: config.provider,
+        model: config.model,
+        ...(config.reasoningEffort ? { reasoningEffort: ReasoningEffortId(config.reasoningEffort) } : {}),
+        messages,
+        maxTokens: config.maxTokens,
+        temperature: 1,
+        signal: controller.signal,
+      })
+      for await (const chunk of config.llm.stream(options)) assembler.push(chunk)
+      const failed = failureMessage(assembler.finish)
+      if (failed !== undefined) throw new Error('llm-verifier: model call failed: ' + failed)
+      const text = assembler.blocks().filter((block): block is Extract<ContentBlock, { type: 'text' }> => block.type === 'text').map(block => block.text).join('')
+      if (!text.trim()) throw new Error('llm-verifier: selected DSH model produced no text')
+      // DSH adapters expose provider-neutral text/usage but not top-logprob candidates.
+      // extractScore() therefore uses the model's explicit final A–T tags.
+      return { text, tokens: [], positions: [], scoringMode: 'explicit-tag', usage: usage(attempt, assembler.usage) }
+    } catch (error) {
+      if (signal?.aborted) throw signal.reason
+      if (attempt > config.maxRetries || !(error instanceof Error) || !/rate|quota|timeout|timed out|temporar|network|fetch|socket|5\d\d/i.test(error.message)) throw error
+      await delay(Math.min(30000, config.retryBaseDelayMs * 2 ** (attempt - 1) * (0.8 + Math.random() * 0.4)), signal)
+    } finally {
+      clearTimeout(timeout)
+      signal?.removeEventListener('abort', abort)
+    }
+  }
+}
+
+export class RequestLimiter {
+  private active = 0
+  private readonly queue: Array<() => void> = []
+  constructor(readonly limit: number) { if (!Number.isSafeInteger(limit) || limit < 1) throw new Error('llm-verifier: request concurrency limit must be a positive integer') }
+  async run<T>(operation: () => Promise<T>, signal?: AbortSignal): Promise<T> {
+    if (this.active >= this.limit) await new Promise<void>((resolve, reject) => {
+      const enter = () => { signal?.removeEventListener('abort', abort); resolve() }
+      const abort = () => { const index = this.queue.indexOf(enter); if (index >= 0) this.queue.splice(index, 1); reject(signal?.reason) }
+      this.queue.push(enter); signal?.addEventListener('abort', abort, { once: true })
+    })
+    if (signal?.aborted) throw signal.reason
+    this.active += 1
+    try { return await operation() } finally { this.active -= 1; this.queue.shift()?.() }
+  }
+}
+
+/** Best-effort pre-call channel prediction for cache identity only; callAutomatic() stays the runtime source of truth. */
+export async function predictScoringChannel(config: VerifierClientConfig): Promise<ScoringMode> {
+  await config.topLogprobCapabilities.ensureLoaded()
+  return config.topLogprobCapabilities.isUnsupported(config.provider, config.model) ? 'explicit-tag' : 'top-logprobs'
+}
+
+async function callAutomatic(config: VerifierClientConfig, prompt: string, signal?: AbortSignal, images?: readonly VerifierImage[]): Promise<VerifierCompletion> {
+  await config.topLogprobCapabilities.ensureLoaded()
+  if (!config.topLogprobCapabilities.isUnsupported(config.provider, config.model)) {
+    const route = await resolveTopLogprobRoute(config.ctx, config.provider)
+    if (route !== undefined) {
+      try { return await callTopLogprobs(route, config.model, prompt, config.maxTokens, config.reasoningEffort, signal, images) }
+      catch (error) {
+        if (!(error instanceof TopLogprobsUnsupportedError)) throw error
+        config.topLogprobCapabilities.markUnsupported(config.provider, config.model)
+      }
+    } else config.topLogprobCapabilities.markUnsupported(config.provider, config.model)
+  }
+  return callExplicitTag(config, prompt, signal, images)
+}
+
+export async function callVerifier(config: VerifierClientConfig, prompt: string, signal?: AbortSignal, images?: readonly VerifierImage[]): Promise<VerifierCompletion> {
+  const invoke = () => callAutomatic(config, prompt, signal, images)
+  return config.limiter === undefined ? invoke() : config.limiter.run(invoke, signal)
+}
+
+/** Plain-text verifier call for conservative JSON routing; probability labels are intentionally bypassed. */
+export async function callVerifierText(config: VerifierClientConfig, prompt: string, signal?: AbortSignal): Promise<VerifierCompletion> {
+  const invoke = () => callExplicitTag(config, prompt, signal)
+  return config.limiter === undefined ? invoke() : config.limiter.run(invoke, signal)
+}
+export function addUsage(target: UsageStats, source: UsageStats): void { for (const key of ['calls', 'attempts', 'retries', 'inputTokens', 'cachedInputTokens', 'outputTokens', 'reasoningTokens'] as const) target[key] += source[key] }
+export function emptyUsage(): UsageStats { return { calls: 0, attempts: 0, retries: 0, inputTokens: 0, cachedInputTokens: 0, outputTokens: 0, reasoningTokens: 0 } }