dsh-vision-router 2.1.7 → 2.2.1

package/lib/session-vision-mode-boundary.js

@@ -9,6 +9,7 @@ import {
 } from './session-vision-mode-authority.js'
 
 const MODE_SYNC_VARIABLE = 'vision_router_mode_sync'
+const VISION_ROUTER_TOOL_OWNER = Symbol.for('dsh-vision-router.tool-owner')
 
 function isObject(value) {
   return value !== null && typeof value === 'object'
@@ -59,6 +60,58 @@ function ownedVisionToolNames(owned) {
   return [...owned.keys()].sort()
 }
 
+function restrictableOwnedVisionToolNames(tools, owned) {
+  const names = ownedVisionToolNames(owned)
+  const get = tools?.get
+  if (typeof get !== 'function') return names
+
+  const active = []
+  for (const name of names) {
+    try {
+      // DSH restrict() accepts only names that exist in the current global
+      // registry. Logical DVR ownership is broader: an intermediate boundary
+      // may capture a conditional definition without mounting it yet
+      // (vision_screenshot is the canonical example).
+      const definition = get.call(tools, name)
+      if (definition?.[VISION_ROUTER_TOOL_OWNER] === true) active.push(name)
+    } catch {
+      // Older/partial Hosts may not offer a safely readable registry view.
+      // Preserve the historical fail-closed path there; per-name fallback
+      // below still prevents one bad entry from exposing every other tool.
+      return names
+    }
+  }
+  return active
+}
+
+function assemblyOwnedVisionToolNames(registryTools, scopedTools, owned) {
+  const active = restrictableOwnedVisionToolNames(registryTools, owned)
+  const scopedGet = scopedTools?.get
+  if (typeof scopedGet !== 'function') return new Set(active)
+
+  const projected = new Set()
+  for (const name of active) {
+    try {
+      const visible = scopedGet.call(scopedTools, name)
+      // A foreign Agent-scoped definition is allowed to shadow DVR's global
+      // name. DSH restrictions deliberately leave scoped registrations visible,
+      // so the final assembly projection must preserve the same boundary.
+      if (
+        visible === undefined
+        || visible?.[VISION_ROUTER_TOOL_OWNER] === true
+      ) {
+        projected.add(name)
+      }
+    } catch {
+      // If the scoped view cannot be read, keep the conservative global DVR
+      // projection. This support-window fallback hides only a name whose global
+      // registration is proven DVR-owned.
+      projected.add(name)
+    }
+  }
+  return projected
+}
+
 function rememberOwnedTool(owned, name) {
   owned.set(name, (owned.get(name) ?? 0) + 1)
 }
@@ -89,18 +142,30 @@ function releaseAgentToolRestriction(agent, restrictions) {
   restrictions.delete(agent)
 }
 
+function restrictionFailureLabel(error) {
+  const name =
+    typeof error?.name === 'string' && error.name !== ''
+      ? error.name
+      : 'Error'
+  const code =
+    typeof error?.code === 'string' && error.code !== ''
+      ? `/${error.code}`
+      : ''
+  return `${name}${code}`
+}
+
 function warnRestrictionFailure(agent, error, deny, failed = deny) {
   try {
     agent?.ctx?.logger?.warn?.(
-      'vision-router: failed to restrict Session vision tools while Vision mode is off: %s (deny=%s failed=%s)',
-      error?.message ?? String(error),
-      deny.join(','),
+      'vision-router: failed to restrict Session vision tools while Vision mode is off: %s (attempted=%s failed=%s)',
+      restrictionFailureLabel(error),
+      String(deny.length),
       failed.join(','),
     )
   } catch {}
 }
 
-function syncAgentToolRestriction(agent, enabled, restrictions, owned) {
+function syncAgentToolRestriction(agent, enabled, restrictions, owned, registryTools) {
   if (!isObject(agent)) return
   if (enabled) {
     releaseAgentToolRestriction(agent, restrictions)
@@ -109,7 +174,11 @@ function syncAgentToolRestriction(agent, enabled, restrictions, owned) {
 
   const tools = agent?.ctx?.tools
   const restrict = tools?.restrict
-  const deny = ownedVisionToolNames(owned)
+  // Registration truth must come from the unscoped/global registry view.
+  // agent.ctx.tools.get() is restriction-aware: after this boundary denies a
+  // DVR tool it reads as absent for that Agent, so using it here would make a
+  // later sync tear down its own restriction and re-expose the capability.
+  const deny = restrictableOwnedVisionToolNames(registryTools, owned)
   if (typeof restrict !== 'function') return
   if (deny.length === 0) {
     releaseAgentToolRestriction(agent, restrictions)
@@ -185,6 +254,7 @@ function wrapTools(tools, ctx, config, owned) {
         const execute = definition.execute
         const registered = register.call(target, {
           ...definition,
+          [VISION_ROUTER_TOOL_OWNER]: true,
           async execute(args, exec) {
             if (
               exec?.agent &&
@@ -264,6 +334,7 @@ export function installSessionVisionModeBoundary(ctx, config = {}) {
       visionToolSurfaceEnabled(ctx, config, authority),
       restrictions,
       ownedVisionTools,
+      ctx?.tools,
     )
   }
 
@@ -282,6 +353,7 @@ export function installSessionVisionModeBoundary(ctx, config = {}) {
         visionToolSurfaceEnabled(ctx, config, authority),
         restrictions,
         ownedVisionTools,
+        ctx?.tools,
       )
     }
     return authority
@@ -314,10 +386,14 @@ export function installSessionVisionModeBoundary(ctx, config = {}) {
       if (!authority && isObject(context)) authority = captureForAssembly(context)
       if (!authority && isObject(agent)) authority = resolveForAgent(agent)
       const transformed = typeof next === 'function' ? await next() : assembly
+      const projectedOwned =
+        ctx?.tools
+          ? assemblyOwnedVisionToolNames(ctx.tools, agent?.ctx?.tools, ownedVisionTools)
+          : ownedVisionTools
       return projectAssemblyTools(
         transformed,
         visionToolSurfaceEnabled(ctx, config, authority),
-        ownedVisionTools,
+        projectedOwned,
       )
     })
   } catch {
@@ -390,6 +466,7 @@ export function installSessionVisionModeBoundary(ctx, config = {}) {
               visionToolSurfaceEnabled(target, config, authority),
               restrictions,
               ownedVisionTools,
+              target?.tools,
             )
             return runWithSessionVisionModeAuthority(
               authority,

package/lib/session-vision-runtime.js

@@ -16,13 +16,17 @@ export const DEFAULT_SESSION_VISION_STATE_OPTIONS = Object.freeze({
  * It is not a general runtime service locator. Production composition creates
  * one instance and gives the same owner to the Session boundary and Core.
  *
- * Durable recovery is requested through index.lookupAttachment(); the index
- * never monkey-patches stateStore.lookupAttachment().
+ * Cache lookup stays synchronous through index.lookupAttachment(); cold durable
+ * recovery is explicit through index.resolveAttachment(). The index never
+ * monkey-patches stateStore.lookupAttachment(), and receives only narrow Host
+ * Session readers rather than the full Context.
  */
 export function createSessionVisionRuntime({
   core,
   config = {},
   logger,
+  readSessionEvent,
+  readSessionLog,
   stateStore,
   stateOptions = {},
 } = {}) {
@@ -39,6 +43,8 @@ export function createSessionVisionRuntime({
     core,
     config,
     logger,
+    readSessionEvent,
+    readSessionLog,
   })
 
   return Object.freeze({

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-breaker-shadow-health.js

@@ -1,8 +1,19 @@
 import { createHash } from 'node:crypto'
+import { createSessionTurnResolver } from './session-turn-resolver.js'
 
-function turnNumberOf(session) {
+function legacyTurnNumberOf(session) {
   try {
-    const events = session?.events
+    // dsh 0.1.2-alpha.4 removed the bare `session.events` array in favor of
+    // `session.snapshotEvents()`; mirror legacySessionEvents
+    // (session-vision-index.js), which prefers the snapshot when both surfaces
+    // exist — transitional Hosts keep the bare array but leave it stale, so a
+    // bare-array-first read would resolve a stale turn on them.
+    let events
+    if (typeof session?.snapshotEvents === 'function') {
+      events = session.snapshotEvents()
+    } else {
+      events = session?.events
+    }
     if (!Array.isArray(events)) return 0
     const last = events.findLast((event) => event && event.type === 'turn/start')
     return last && Number.isInteger(last.data?.turn) ? last.data.turn : 0
@@ -19,8 +30,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 +94,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 +108,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-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-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 }
     },