dsh-vision-router 2.1.6 → 2.2.0

package/lib/session-vision-state.js

@@ -123,7 +123,6 @@ function createState(key, stable, options, now) {
     attachments: new WeightedLruMap({
       maxEntries: options.attachmentMaxEntries,
     }),
-    scannedEventSeq: 0,
   }
 }
 
@@ -356,17 +355,6 @@ export function createSessionVisionStateStore(config = {}) {
       return stateFor(session, false)?.attachments.get(id)
     },
 
-    getScannedEventSeq(session) {
-      return stateFor(session, false)?.scannedEventSeq ?? 0
-    },
-
-    setScannedEventSeq(session, seq) {
-      const state = stateFor(session, true)
-      if (state === undefined) return
-      const next = Number.isFinite(Number(seq)) && Number(seq) >= 0 ? Math.floor(Number(seq)) : 0
-      state.scannedEventSeq = next
-      touchState(state)
-    },
 
     forgetSession(sessionOrId) {
       const id =
@@ -389,7 +377,6 @@ export function createSessionVisionStateStore(config = {}) {
         descriptions: state.descriptions.size,
         descriptionChars: state.descriptions.weight,
         attachments: state.attachments.size,
-        scannedEventSeq: state.scannedEventSeq,
       }
     },
 

package/lib/tesseract-exec-compat.js

@@ -1,4 +1,4 @@
-import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { mkdtemp, realpath, rm, writeFile } from 'node:fs/promises'
 import path from 'node:path'
 import { tmpdir } from 'node:os'
 import { createRequire, syncBuiltinESMExports } from 'node:module'
@@ -80,9 +80,23 @@ export function createTesseractPromisifyCompat(execFileImpl, originalCustom, opt
   const makeTempDir = options.mkdtemp ?? mkdtemp
   const writeTempFile = options.writeFile ?? writeFile
   const removeTempDir = options.rm ?? rm
+  const resolveRealPath = options.realpath ?? realpath
   const tempDir = options.tempDir ?? tmpdir()
+  let resolvedTempDir
   let active = true
 
+  const stagingRoot = async () => {
+    if (resolvedTempDir !== undefined) return resolvedTempDir
+    try {
+      resolvedTempDir = await resolveRealPath(tempDir)
+    } catch {
+      // Some tests/embedders provide a virtual temp root. Preserve the old
+      // path when canonicalization is unavailable instead of disabling OCR.
+      resolvedTempDir = tempDir
+    }
+    return resolvedTempDir
+  }
+
   async function tesseractPromisifyCompat(file, args, execOptions) {
     if (!active || !isTesseractCompatCall(file, args, execOptions)) {
       return delegate(file, args, execOptions)
@@ -91,7 +105,7 @@ export function createTesseractPromisifyCompat(execFileImpl, originalCustom, opt
     const bytes = bytesView(execOptions.input)
     let dir
     try {
-      dir = await makeTempDir(path.join(tempDir, 'dsh-vision-router-ocr-'))
+      dir = await makeTempDir(path.join(await stagingRoot(), 'dsh-vision-router-ocr-'))
       const inputPath = path.join(dir, `input${extensionForBytes(bytes)}`)
       await writeTempFile(inputPath, bytes)
 

package/lib/twin-image-capability-fallback.js

@@ -1,4 +1,5 @@
 import { AsyncLocalStorage } from 'node:async_hooks'
+import { blocksHaveRetainedImage } from './image-offload-compat.js'
 
 const TWIN_SUFFIX = '-vision'
 const DEFAULT_MAIN_WRAPPER_ROUTE = 'deepseek-vision'
@@ -16,19 +17,9 @@ function nonEmptyString(value) {
   return typeof value === 'string' && value.length > 0
 }
 
-function blocksHaveImage(content) {
-  if (!Array.isArray(content)) return false
-  for (const block of content) {
-    if (!block) continue
-    if (block.type === 'image') return true
-    if (Array.isArray(block.content) && blocksHaveImage(block.content)) return true
-  }
-  return false
-}
-
 export function twinRequestHasImage(messages) {
   return (messages ?? []).some(
-    (message) => message && Array.isArray(message.content) && blocksHaveImage(message.content),
+    (message) => message && Array.isArray(message.content) && blocksHaveRetainedImage(message.content),
   )
 }
 

package/lib/vision-artifact-store.js

@@ -1,6 +1,7 @@
 import {
   resolveArtifactTarget,
   writeArtifactFile,
+  writePersistentArtifactFile,
 } from './artifact-io.js'
 import {
   retainArtifactRun,
@@ -46,6 +47,17 @@ export function createVisionArtifactStore({ workspace, artifactsDir, deps = {} }
     )
   }
 
+  const publishPersistent = (relativePath, data, options = {}) => {
+    const current = location()
+    return writePersistentArtifactFile(
+      current.workspace,
+      current.artifactsDir,
+      relativePath,
+      data,
+      callDeps(deps, options),
+    )
+  }
+
   return Object.freeze({
     resolve(relativePath, options = {}) {
       const current = location()
@@ -58,10 +70,11 @@ export function createVisionArtifactStore({ workspace, artifactsDir, deps = {} }
     },
 
     publish,
+    publishPersistent,
 
-    // Temporary-vs-persistent placement is authority/lifetime driven: the
-    // ambient managed artifactRunId decides whether hardened IO uses `.runs`.
-    // Keeping this method as an alias avoids inventing a second placement path.
+    // Temporary placement remains authority/lifetime driven by the ambient
+    // random managed artifactRunId. publishPersistent is the narrow handoff
+    // exception and uses one stable reserved run that retention still owns.
     publishTemporary(relativePath, data, options = {}) {
       return publish(relativePath, data, options)
     },

package/lib/vision-attachment-handle-runtime.js

@@ -29,13 +29,11 @@ function attachmentIdOf(ref) {
   return id === '' ? undefined : id
 }
 
-function sessionEvents(session) {
+function sessionMessages(session) {
   try {
-    if (session && typeof session.snapshotEvents === 'function') {
-      const events = session.snapshotEvents()
-      return Array.isArray(events) ? events : []
-    }
-    return Array.isArray(session?.events) ? session.events : []
+    if (!session || typeof session.deriveMessages !== 'function') return []
+    const messages = session.deriveMessages()
+    return Array.isArray(messages) ? messages : []
   } catch {
     return []
   }
@@ -55,18 +53,9 @@ function collectImageRefsFromMessages(messages, out) {
   for (const message of messages) collectImageRefsFromBlocks(message?.content, out)
 }
 
-function authorizedRefs(core, agent) {
+function authorizedRefs(agent) {
   const refs = []
-  const session = agent?.session
-  const events = sessionEvents(session)
-  if (typeof core?.collectEventAttachmentRefs === 'function') {
-    try {
-      const durable = core.collectEventAttachmentRefs(events)
-      if (Array.isArray(durable)) refs.push(...durable)
-    } catch {
-      // The resolver remains fail-closed; pending refs below may still suffice.
-    }
-  }
+  collectImageRefsFromMessages(sessionMessages(agent?.session), refs)
   collectImageRefsFromMessages(agent?.inbox?.nextTurn, refs)
   collectImageRefsFromMessages(agent?.inbox?.nextStep, refs)
 
@@ -99,12 +88,12 @@ function isCanonicalSha256Id(value) {
  * only when exactly one image authorized by the current Session has that
  * prefix. Zero or multiple matches fail closed.
  */
-export function resolveProjectedAttachmentHandle(handle, { core, sessionVisionIndex, agent } = {}) {
+export function resolveProjectedAttachmentHandle(handle, { sessionVisionIndex, agent } = {}) {
   const token = typeof handle === 'string' ? handle.trim() : ''
   if (!isProjectedAttachmentHandle(token)) return { kind: 'not-projected', value: handle }
 
   const session = agent?.session
-  const refs = authorizedRefs(core, agent)
+  const refs = authorizedRefs(agent)
   const wanted = token.toLowerCase()
   const matches = refs.filter((ref) => {
     const id = attachmentIdOf(ref)
@@ -124,7 +113,7 @@ export function resolveProjectedAttachmentHandle(handle, { core, sessionVisionIn
   try {
     sessionVisionIndex?.recordAttachments?.(session, [candidate])
   } catch {
-    // A durable event can still be recovered by lookupAttachment below.
+    // Authorization is still fail-closed if the bounded cache cannot be warmed.
   }
   if (!sessionVisionIndex || typeof sessionVisionIndex.lookupAttachment !== 'function') {
     return { kind: 'unknown', handle: token }
@@ -201,7 +190,6 @@ export function wrapVisionAttachmentHandleDefinition(def, options = {}) {
     ...def,
     execute(args, exec) {
       const nextArgs = canonicalizeArgs(args, {
-        core: options.core,
         sessionVisionIndex: options.sessionVisionIndex,
         agent: exec?.agent,
         toolName: def.name,

package/lib/vision-backend-runtime-policy.js

@@ -1,4 +1,5 @@
 import { AsyncLocalStorage } from 'node:async_hooks'
+import { blocksHaveRetainedImage, isOffloadedImageBlock, offloadedImagePlaceholder } from './image-offload-compat.js'
 
 const visionBackendScope = new AsyncLocalStorage()
 const wrappedContexts = new WeakMap()
@@ -127,12 +128,8 @@ async function resolveCredential(ctx, plan) {
   return undefined
 }
 
-function contentHasImage(core, messages) {
-  return (messages ?? []).some((message) => {
-    if (!Array.isArray(message?.content)) return false
-    if (typeof core?.blocksHaveImage === 'function') return core.blocksHaveImage(message.content)
-    return message.content.some((block) => block?.type === 'image')
-  })
+function contentHasImage(_core, messages) {
+  return (messages ?? []).some((message) => blocksHaveRetainedImage(message?.content))
 }
 
 async function toOpenAIMessages(ctx, messages) {
@@ -151,6 +148,10 @@ async function toOpenAIMessages(ctx, messages) {
         continue
       }
       if (block?.type === 'image' && block.attachment) {
+        if (isOffloadedImageBlock(block)) {
+          converted.push({ type: 'text', text: offloadedImagePlaceholder(block) })
+          continue
+        }
         const stored = await attachments.readImage(block.attachment)
         const mediaType = block.attachment.mediaType || stored?.mediaType || 'image/png'
         const data = Buffer.from(stored.data).toString('base64')

package/lib/vision-background-stop-store.js

@@ -50,6 +50,25 @@ function recordKey(value) {
   return `${value.fingerprint}\u0000${value.axis}`
 }
 
+function selectRetainedStops(values, at, maxEntries = MAX_ENTRIES) {
+  const seen = new Set()
+  return [...values]
+    .map(cleanStop)
+    .filter((item) => item && item.expiresAt > at)
+    .sort((a, b) => b.recordedAt - a.recordedAt || recordKey(a).localeCompare(recordKey(b)))
+    .filter((item) => {
+      const key = recordKey(item)
+      if (seen.has(key)) return false
+      seen.add(key)
+      return true
+    })
+    .slice(0, maxEntries)
+}
+
+function retainedStopMap(values, at, maxEntries = MAX_ENTRIES) {
+  return new Map(selectRetainedStops(values, at, maxEntries).map((item) => [recordKey(item), item]))
+}
+
 export function backgroundBenchmarkStopCachePath(dshHome = resolveDshHome()) {
   return path.join(dshHome, 'cache', 'vision-router', 'background-benchmark-stops.json')
 }
@@ -59,10 +78,7 @@ async function load(file, fsOps, at) {
     const raw = await fsOps.readFile(file, 'utf8')
     const body = JSON.parse(raw)
     if (!body || !Array.isArray(body.stops) || ![2, CACHE_VERSION].includes(body.version)) return new Map()
-    const records = new Map(body.stops
-      .map(cleanStop)
-      .filter((item) => item && item.expiresAt > at)
-      .map((item) => [recordKey(item), item]))
+    const records = retainedStopMap(body.stops, at)
     if (body.version === 2) await save(file, records, fsOps, at)
     return records
   } catch (error) {
@@ -73,11 +89,7 @@ async function load(file, fsOps, at) {
 
 async function save(file, records, fsOps, at) {
   const temporary = `${file}.${process.pid}.${Date.now()}.tmp`
-  const stops = [...records.values()]
-    .map(cleanStop)
-    .filter((item) => item && item.expiresAt > at)
-    .sort((a, b) => b.recordedAt - a.recordedAt)
-    .slice(0, MAX_ENTRIES)
+  const stops = selectRetainedStops(records.values(), at)
   await fsOps.mkdir(path.dirname(file), { recursive: true })
   await fsOps.writeFile(temporary, JSON.stringify({ version: CACHE_VERSION, stops }), { encoding: 'utf8', mode: 0o600 })
   await fsOps.rename(temporary, file)
@@ -105,22 +117,19 @@ export function createBackgroundBenchmarkStopStore(options = {}) {
     return saveTail
   }
 
-  const pruneExpired = () => {
+  const reconcile = () => {
     const at = Number(now())
-    let removed = false
-    for (const [key, record] of records.entries()) {
-      if (record.expiresAt > at) continue
-      records.delete(key)
-      removed = true
-    }
-    return removed
+    const retained = retainedStopMap(records.values(), at)
+    const changed = retained.size !== records.size || [...retained.keys()].some((key) => !records.has(key))
+    records = retained
+    return changed
   }
 
   return {
     file,
     async list() {
       await ready
-      if (pruneExpired()) await persist()
+      if (reconcile()) await persist()
       return [...records.values()].sort((a, b) => b.recordedAt - a.recordedAt)
     },
     async mark({
@@ -135,7 +144,7 @@ export function createBackgroundBenchmarkStopStore(options = {}) {
       expiresAt,
     } = {}) {
       await ready
-      pruneExpired()
+      reconcile()
       const clean = cleanStop({
         fingerprint,
         key,
@@ -150,8 +159,9 @@ export function createBackgroundBenchmarkStopStore(options = {}) {
       })
       if (!clean) return undefined
       records.set(recordKey(clean), clean)
+      reconcile()
       await persist()
-      return clean
+      return records.get(recordKey(clean))
     },
     async clearStop(fingerprint, axis) {
       await ready

package/lib/vision-breaker-shadow-health.js

@@ -1,6 +1,7 @@
 import { createHash } from 'node:crypto'
+import { createSessionTurnResolver } from './session-turn-resolver.js'
 
-function turnNumberOf(session) {
+function legacyTurnNumberOf(session) {
   try {
     const events = session?.events
     if (!Array.isArray(events)) return 0
@@ -19,8 +20,15 @@ function sessionIdOf(session) {
   }
 }
 
-export function visionBreakerScopeOf(session) {
-  return `${sessionIdOf(session)}:${turnNumberOf(session)}`
+export function visionBreakerScopeOf(session, turnOf) {
+  let turn
+  try {
+    if (typeof turnOf === 'function') turn = turnOf(session)
+  } catch {
+    turn = undefined
+  }
+  if (!Number.isInteger(turn) || turn < 0) turn = legacyTurnNumberOf(session)
+  return `${sessionIdOf(session)}:${turn}`
 }
 
 function credentialFingerprintOf(value) {
@@ -76,7 +84,9 @@ function healthFromGate(gate) {
  * giving shadow code mutation authority. `capture()` is called only while
  * core.apply() constructs the breaker; `healthForCandidate()` uses peek().
  */
-export function createVisionBreakerShadowHealth(ctx) {
+export function createVisionBreakerShadowHealth(ctx, options = {}) {
+  const sessionTurnResolver = options.sessionTurnResolver ?? createSessionTurnResolver(ctx)
+  const turnOf = sessionTurnResolver.turnOf
   let breaker
   return {
     capture(value) {
@@ -88,7 +98,7 @@ export function createVisionBreakerShadowHealth(ctx) {
       const key = typeof candidate?.key === 'string' ? candidate.key : undefined
       if (!key) return undefined
       const fingerprint = await visionBreakerFingerprintForCandidate(ctx, candidate)
-      const scope = visionBreakerScopeOf(context.session)
+      const scope = visionBreakerScopeOf(context.session, turnOf)
       return healthFromGate(breaker.peek(key, fingerprint, scope))
     },
 

package/lib/vision-capability-probe.js

@@ -338,21 +338,34 @@ export async function runExactCapabilityBenchmark({
   return { record, results }
 }
 
+function selectRetainedCapabilityProfiles(values, maxEntries) {
+  const seen = new Set()
+  return [...values]
+    .map(sanitizeCapabilityProfileRecord)
+    .filter(Boolean)
+    .sort((a, b) => b.measuredAt - a.measuredAt || a.fingerprint.localeCompare(b.fingerprint))
+    .filter((record) => {
+      if (seen.has(record.fingerprint)) return false
+      seen.add(record.fingerprint)
+      return true
+    })
+    .slice(0, maxEntries)
+}
+
+function retainedCapabilityProfileMap(values, maxEntries) {
+  return new Map(selectRetainedCapabilityProfiles(values, maxEntries).map((record) => [record.fingerprint, record]))
+}
+
 function cacheEnvelope(records) {
   return { version: CAPABILITY_PROFILE_CACHE_VERSION, profiles: records }
 }
 
-async function loadCache(file, fsOps) {
+async function loadCache(file, fsOps, maxEntries) {
   try {
     const raw = await fsOps.readFile(file, 'utf8')
     const body = JSON.parse(raw)
     if (!body || body.version !== CAPABILITY_PROFILE_CACHE_VERSION || !Array.isArray(body.profiles)) return new Map()
-    return new Map(
-      body.profiles
-        .map(sanitizeCapabilityProfileRecord)
-        .filter(Boolean)
-        .map((record) => [record.fingerprint, record]),
-    )
+    return retainedCapabilityProfileMap(body.profiles, maxEntries)
   } catch (error) {
     if (error?.code === 'ENOENT') return new Map()
     return new Map()
@@ -362,11 +375,7 @@ async function loadCache(file, fsOps) {
 async function saveCache(file, records, fsOps, maxEntries) {
   const directory = path.dirname(file)
   const temporary = `${file}.${process.pid}.${Date.now()}.tmp`
-  const profiles = [...records.values()]
-    .map(sanitizeCapabilityProfileRecord)
-    .filter(Boolean)
-    .sort((a, b) => b.measuredAt - a.measuredAt || a.fingerprint.localeCompare(b.fingerprint))
-    .slice(0, maxEntries)
+  const profiles = selectRetainedCapabilityProfiles(records.values(), maxEntries)
   await fsOps.mkdir(directory, { recursive: true })
   await fsOps.writeFile(temporary, JSON.stringify(cacheEnvelope(profiles)), { encoding: 'utf8', mode: 0o600 })
   await fsOps.rename(temporary, file)
@@ -384,7 +393,7 @@ export function createCapabilityProfileStore(options = {}) {
   const logger = options.logger
   let records = new Map()
   let saveTail = Promise.resolve()
-  const ready = loadCache(file, fsOps).then((loaded) => { records = loaded })
+  const ready = loadCache(file, fsOps, maxEntries).then((loaded) => { records = loaded })
 
   const persist = () => {
     saveTail = saveTail
@@ -412,8 +421,9 @@ export function createCapabilityProfileStore(options = {}) {
       if (merged === undefined) throw new TypeError('invalid merged capability profile record')
       if (existing && JSON.stringify(existing) === JSON.stringify(merged)) return existing
       records.set(clean.fingerprint, merged)
+      records = retainedCapabilityProfileMap(records.values(), maxEntries)
       await persist()
-      return merged
+      return records.get(clean.fingerprint)
     },
     async remove(fingerprint) {
       await ready

package/lib/vision-evidence-guidance.js

@@ -0,0 +1,39 @@
+export const VISION_SUCCESS_GUIDANCE =
+  'Vision Router trusted execution metadata: the preceding vision_describe call SUCCEEDED. ' +
+  'This metadata is not image content. If that successful evidence resolves the visual fact needed for the current task, stop making additional vision calls for that fact and continue the remaining user task from this evidence. ' +
+  'If no non-visual work remains, answer now in exactly the format the user requested; when the user asks for only one value or short phrase, do not add Markdown, explanation, or a restatement. ' +
+  'Call another vision tool only for a specific unresolved visual fact. For verbatim or exact-text tasks such as identifiers, amounts, times, version strings, or code, preserve every visible symbol, prefix, suffix, and punctuation from the most faithful evidence already collected; a later semantic summary must not overwrite a more exact transcription. Focused OCR or localization is still appropriate when character identity remains uncertain.'
+
+function isVisionFailureEnvelope(value) {
+  const text = value.trim()
+  if (!text.startsWith('{')) return false
+  try {
+    const parsed = JSON.parse(text)
+    return (
+      parsed !== null &&
+      typeof parsed === 'object' &&
+      parsed.ok === false &&
+      typeof parsed.code === 'string' &&
+      /^VISION_[A-Z0-9_]+$/u.test(parsed.code)
+    )
+  } catch {
+    return false
+  }
+}
+
+export function visionDescribeSuccessContext(exec, result) {
+  if (
+    exec?.name !== 'vision_describe' ||
+    !exec?.agent ||
+    result?.isError !== false ||
+    typeof result.value !== 'string' ||
+    result.value.trim().length === 0 ||
+    isVisionFailureEnvelope(result.value)
+  ) return undefined
+  return {
+    role: 'user',
+    id: `vision-router-evidence-success-${String(exec.callId)}`,
+    content: [{ type: 'text', text: VISION_SUCCESS_GUIDANCE }],
+    source: { kind: 'plugin', plugin: 'dsh-vision-router' },
+  }
+}

package/lib/vision-image-input-verdict.js

@@ -38,12 +38,30 @@ export function imageInputVerdictCachePath(dshHome = resolveDshHome()) {
   return path.join(dshHome, 'cache', 'vision-router', 'image-input-verdicts.json')
 }
 
+function selectRetainedVerdicts(values, maxEntries = MAX_ENTRIES) {
+  const seen = new Set()
+  return [...values]
+    .map(cleanVerdict)
+    .filter(Boolean)
+    .sort((a, b) => b.measuredAt - a.measuredAt || a.fingerprint.localeCompare(b.fingerprint))
+    .filter((item) => {
+      if (seen.has(item.fingerprint)) return false
+      seen.add(item.fingerprint)
+      return true
+    })
+    .slice(0, maxEntries)
+}
+
+function retainedVerdictMap(values, maxEntries = MAX_ENTRIES) {
+  return new Map(selectRetainedVerdicts(values, maxEntries).map((item) => [item.fingerprint, item]))
+}
+
 async function load(file, fsOps) {
   try {
     const raw = await fsOps.readFile(file, 'utf8')
     const body = JSON.parse(raw)
     if (!body || body.version !== CACHE_VERSION || !Array.isArray(body.verdicts)) return new Map()
-    return new Map(body.verdicts.map(cleanVerdict).filter(Boolean).map((item) => [item.fingerprint, item]))
+    return retainedVerdictMap(body.verdicts)
   } catch (error) {
     if (error?.code === 'ENOENT') return new Map()
     return new Map()
@@ -52,11 +70,7 @@ async function load(file, fsOps) {
 
 async function save(file, records, fsOps) {
   const temporary = `${file}.${process.pid}.${Date.now()}.tmp`
-  const verdicts = [...records.values()]
-    .map(cleanVerdict)
-    .filter(Boolean)
-    .sort((a, b) => b.measuredAt - a.measuredAt)
-    .slice(0, MAX_ENTRIES)
+  const verdicts = selectRetainedVerdicts(records.values())
   await fsOps.mkdir(path.dirname(file), { recursive: true })
   await fsOps.writeFile(temporary, JSON.stringify({ version: CACHE_VERSION, verdicts }), { encoding: 'utf8', mode: 0o600 })
   await fsOps.rename(temporary, file)
@@ -101,8 +115,9 @@ export function createImageInputVerdictStore(options = {}) {
       })
       if (!clean) return undefined
       records.set(clean.fingerprint, clean)
+      records = retainedVerdictMap(records.values())
       await persist()
-      return clean
+      return records.get(clean.fingerprint)
     },
     async clear(fingerprint) {
       await ready

package/lib/vision-resilience.js

@@ -376,12 +376,14 @@ export function createVisionTurnMemory({
   maxScopes = 64,
   maxSessions = maxScopes,
   maxAttemptsPerScope = 64,
+  maxEvidencePerScope = 32,
 } = {}) {
   const scopes = new Map() // scope -> { failedKinds:Set, attempted: [], allFailed:false }
   const lastScopeBySession = new Map() // bounded LRU sessionId -> scope
   const scopeLimit = Math.max(1, Math.floor(Number(maxScopes) || 64))
   const sessionLimit = Math.max(1, Math.floor(Number(maxSessions) || scopeLimit))
   const attemptLimit = Math.max(1, Math.floor(Number(maxAttemptsPerScope) || 64))
+  const evidenceLimit = Math.max(1, Math.floor(Number(maxEvidencePerScope) || 32))
 
   const dropScope = (scope) => {
     scopes.delete(scope)
@@ -410,7 +412,14 @@ export function createVisionTurnMemory({
   const entry = (scope) => {
     let hit = scopes.get(scope)
     if (hit === undefined) {
-      hit = { failedKinds: new Set(), attempted: [], allFailed: false }
+      hit = {
+        failedKinds: new Set(),
+        attempted: [],
+        allFailed: false,
+        localOcr: new Map(),
+        derivedArtifacts: new Map(),
+        degradedRefinements: new Map(),
+      }
       scopes.set(scope, hit)
       pruneScopes()
     } else {
@@ -453,6 +462,69 @@ export function createVisionTurnMemory({
       return hit === undefined ? [] : [...hit.attempted]
     },
 
+    resolveSource(scope, sourceKey) {
+      const key = typeof sourceKey === 'string' ? sourceKey : ''
+      const hit = scopes.get(scope)
+      if (hit === undefined || key === '') return key
+      for (const [artifactToken, rootSource] of hit.derivedArtifacts) {
+        if (key === artifactToken || key.includes(artifactToken)) return rootSource
+      }
+      return key
+    },
+
+    recordLocalOcr(scope, sourceKey, evidence = {}) {
+      const hit = entry(scope)
+      const key = this.resolveSource(scope, sourceKey)
+      if (key === '') return
+      hit.localOcr.delete(key)
+      hit.localOcr.set(key, Object.freeze({ uncertain: evidence.uncertain === true }))
+      while (hit.localOcr.size > evidenceLimit) hit.localOcr.delete(hit.localOcr.keys().next().value)
+    },
+
+    hasLocalOcr(scope, sourceKey) {
+      const hit = scopes.get(scope)
+      if (hit === undefined) return false
+      return hit.localOcr.has(this.resolveSource(scope, sourceKey))
+    },
+
+    degradedEvidenceTokens(scope) {
+      const hit = scopes.get(scope)
+      if (hit === undefined || !hit.allFailed || hit.localOcr.size === 0) return []
+      const tokens = [...hit.localOcr.keys()]
+      for (const [artifactToken, rootSource] of hit.derivedArtifacts) {
+        if (hit.localOcr.has(rootSource)) tokens.push(artifactToken)
+      }
+      return tokens
+    },
+
+    recordDerivedArtifact(scope, sourceKey, artifactToken) {
+      const token = typeof artifactToken === 'string' ? artifactToken : ''
+      if (token === '') return
+      const hit = entry(scope)
+      const rootSource = this.resolveSource(scope, sourceKey)
+      if (rootSource === '') return
+      hit.derivedArtifacts.delete(token)
+      hit.derivedArtifacts.set(token, rootSource)
+      while (hit.derivedArtifacts.size > evidenceLimit) hit.derivedArtifacts.delete(hit.derivedArtifacts.keys().next().value)
+    },
+
+    degradedRefinementCount(scope, sourceKey) {
+      const hit = scopes.get(scope)
+      if (hit === undefined) return 0
+      return hit.degradedRefinements.get(this.resolveSource(scope, sourceKey)) ?? 0
+    },
+
+    recordDegradedRefinement(scope, sourceKey) {
+      const hit = entry(scope)
+      const key = this.resolveSource(scope, sourceKey)
+      if (key === '') return 0
+      const count = (hit.degradedRefinements.get(key) ?? 0) + 1
+      hit.degradedRefinements.delete(key)
+      hit.degradedRefinements.set(key, count)
+      while (hit.degradedRefinements.size > evidenceLimit) hit.degradedRefinements.delete(hit.degradedRefinements.keys().next().value)
+      return count
+    },
+
     stats() {
       return { scopes: scopes.size, sessions: lastScopeBySession.size }
     },