dsh-vision-router 2.3.0 → 3.0.1

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

@@ -415,5 +415,21 @@ export function contextWithVisionBackendRuntimePolicy(ctx, options = {}) {
     ? finalContextDecorator(wrapped)
     : wrapped
   wrappedContexts.set(ctx, result)
+  let lifecycleOwned = false
+  try {
+    if (typeof ctx.effect === 'function') {
+      ctx.effect(
+        () => () => {
+          if (wrappedContexts.get(ctx) === result) wrappedContexts.delete(ctx)
+        },
+        'vision-router: backend runtime policy context lifecycle',
+      )
+      lifecycleOwned = true
+    }
+  } catch {
+    // The current caller can still use this one-shot policy view.
+  }
+  // options contains generation-owned config/transport/evidence closures.
+  if (!lifecycleOwned && wrappedContexts.get(ctx) === result) wrappedContexts.delete(ctx)
   return result
 }

package/lib/vision-background-benchmark.js

@@ -552,6 +552,7 @@ export function createBackgroundCapabilityProfiler({
   let lastForegroundAt = Number(now())
   let runningController
   let runningWork
+  let tickTask
   let topologyDirty = false
   let lastAuthority = resolveVisionRoutingAuthority(activeSettings(ctx, config))
   const backoff = new Map()
@@ -689,7 +690,7 @@ export function createBackgroundCapabilityProfiler({
     }
   }
 
-  const tick = async () => {
+  const runTick = async () => {
     if (stopped || runningController) return
     const currentNow = Number(now())
     const current = activeSettings(ctx, config)
@@ -757,7 +758,7 @@ export function createBackgroundCapabilityProfiler({
       }, interval)
       try { policyTimer?.unref?.() } catch {}
 
-      const runner = runAxisBenchmark ?? ((args) => runAxis({ ...args, options: invokerOptions }))
+      const runner = runAxisBenchmark ?? runAxis
       await runner({
         ctx,
         config: current,
@@ -767,6 +768,7 @@ export function createBackgroundCapabilityProfiler({
         axis: work.axis,
         signal: controller.signal,
         logger,
+        options: invokerOptions,
         onProgress(progress = {}) {
           if (!runningWork || runningWork.candidate.key !== work.candidate.key || runningWork.axis !== work.axis) return
           const completed = Math.max(0, Number(progress.completed) || 0)
@@ -864,6 +866,32 @@ export function createBackgroundCapabilityProfiler({
     }
   }
 
+  const tick = () => {
+    if (tickTask) return tickTask
+    let tracked
+    // `tracked` is assigned before any rejection can be observed: the timer
+    // callback and the lifecycle disposer both call tick(), and a background
+    // scan that throws must degrade to a logged failure instead of an
+    // unhandled process-level rejection.
+    tracked = Promise.resolve()
+      .then(runTick)
+      .catch((error) => {
+        try {
+          logger?.warn?.(
+            'vision-router: background benchmark tick failed: %s',
+            bounded(error?.message ?? error),
+          )
+        } catch {
+          /* diagnostics only */
+        }
+      })
+      .finally(() => {
+        if (tickTask === tracked) tickTask = undefined
+      })
+    tickTask = tracked
+    return tracked
+  }
+
   const foregroundStart = () => {
     activeForeground += 1
     lastForegroundAt = Number(now())
@@ -893,6 +921,7 @@ export function createBackgroundCapabilityProfiler({
     if (timer !== undefined) clearTimer(timer)
     timer = undefined
     yieldBackground('background profiler stopped')
+    return tickTask ?? Promise.resolve()
   }
 
   schedule(idleMs)
@@ -971,6 +1000,16 @@ export function installBackgroundCapabilityProfiling(ctx, config, core, store, o
   const logger = options.logger ?? ctx?.logger
   const imageVerdictStore = options.imageVerdictStore ?? createImageInputVerdictStore({ logger })
   const backgroundStopStore = options.backgroundStopStore ?? createBackgroundBenchmarkStopStore({ logger })
+  // Provider transport is one explicit runtime capability shared by automatic
+  // profiling and the user-triggered exact check. Top-level ownership wins so
+  // a stale nested test/customization bag cannot silently bypass live proxy
+  // policy after composition or HMR changes.
+  const invokerOptions = {
+    ...(options.invokerOptions ?? {}),
+    ...(options.providerTransport === undefined
+      ? {}
+      : { providerTransport: options.providerTransport }),
+  }
   const profiler = createBackgroundCapabilityProfiler({
     ctx,
     config,
@@ -978,6 +1017,7 @@ export function installBackgroundCapabilityProfiling(ctx, config, core, store, o
     store,
     logger,
     ...options,
+    invokerOptions,
     imageVerdictStore,
     backgroundStopStore,
   })
@@ -1022,17 +1062,26 @@ export function installBackgroundCapabilityProfiling(ctx, config, core, store, o
     // Event-driven wakeups are an optimization; the short authority scan remains.
   }
 
+  let lifecycleOwned = true
   try {
-    ctx?.effect?.(() => () => {
+    ctx?.effect?.(() => async () => {
       for (const dispose of eventDisposers.splice(0)) {
         try { dispose() } catch {}
       }
-      profiler.stop()
+      await profiler.stop()
     }, 'vision-router: background capability profiler')
   } catch {
-    // Cleanup registration is best-effort; the profiler remains process-scoped.
+    lifecycleOwned = false
+    for (const dispose of eventDisposers.splice(0)) {
+      try { dispose() } catch {}
+    }
+    void profiler.stop().catch(() => {})
   }
 
+  // An inactive/unowned generation must not continue admitting client scripts,
+  // routes, or tool wrappers after its profiler ownership was rejected.
+  if (!lifecycleOwned) return { ctx, profiler }
+
   installVisionExactCheckClient(ctx)
 
   try {
@@ -1083,7 +1132,7 @@ export function installBackgroundCapabilityProfiling(ctx, config, core, store, o
               provider: body.provider,
               model: body.model,
               signal: AbortSignal.timeout(VISION_CHECK_TIMEOUT_MS),
-              invokerOptions: options.invokerOptions ?? {},
+              invokerOptions,
             })
             await profiler.recordImageSupported(body.provider, body.model)
             sendJson(res, 200, result)

package/lib/vision-background-failure-policy.js

@@ -1,47 +1,47 @@
-export const BACKGROUND_AUTH_STOP_TTL_MS = 10 * 60 * 1000
-export const BACKGROUND_ENDPOINT_STOP_TTL_MS = 6 * 60 * 60 * 1000
-export const BACKGROUND_TRANSIENT_RETRY_MS = 30 * 60 * 1000
-
+export const BACKGROUND_AUTH_STOP_TTL_MS = 10 * 60 * 1000;
+export const BACKGROUND_ENDPOINT_STOP_TTL_MS = 6 * 60 * 60 * 1000;
+export const BACKGROUND_TRANSIENT_RETRY_MS = 30 * 60 * 1000;
 const DEFAULT_POLICY = Object.freeze({
-  retryable: true,
-  persist: false,
-  retryAfterMs: undefined,
-  ttlMs: undefined,
-})
-
-const POLICIES = Object.freeze({
-  auth: Object.freeze({
-    retryable: false,
-    persist: false,
-    ttlMs: BACKGROUND_AUTH_STOP_TTL_MS,
-  }),
-  protocol: Object.freeze({
-    retryable: false,
-    persist: true,
-    ttlMs: BACKGROUND_ENDPOINT_STOP_TTL_MS,
-  }),
-  unavailable: Object.freeze({
-    retryable: false,
-    persist: true,
-    ttlMs: BACKGROUND_ENDPOINT_STOP_TTL_MS,
-  }),
-  'unsupported-image': Object.freeze({
-    retryable: false,
-    persist: false,
-  }),
-  'visual-proof': Object.freeze({
     retryable: true,
     persist: false,
-    retryAfterMs: BACKGROUND_TRANSIENT_RETRY_MS,
-  }),
-  infrastructure: Object.freeze({
-    retryable: true,
-    persist: false,
-    retryAfterMs: BACKGROUND_TRANSIENT_RETRY_MS,
-  }),
-})
-
+    retryAfterMs: undefined,
+    ttlMs: undefined,
+});
+const POLICIES = Object.freeze({
+    auth: Object.freeze({
+        retryable: false,
+        persist: false,
+        ttlMs: BACKGROUND_AUTH_STOP_TTL_MS,
+    }),
+    protocol: Object.freeze({
+        retryable: false,
+        persist: true,
+        ttlMs: BACKGROUND_ENDPOINT_STOP_TTL_MS,
+    }),
+    unavailable: Object.freeze({
+        retryable: false,
+        persist: true,
+        ttlMs: BACKGROUND_ENDPOINT_STOP_TTL_MS,
+    }),
+    'unsupported-image': Object.freeze({
+        retryable: false,
+        persist: false,
+    }),
+    'visual-proof': Object.freeze({
+        retryable: true,
+        persist: false,
+        retryAfterMs: BACKGROUND_TRANSIENT_RETRY_MS,
+    }),
+    infrastructure: Object.freeze({
+        retryable: true,
+        persist: false,
+        retryAfterMs: BACKGROUND_TRANSIENT_RETRY_MS,
+    }),
+});
 /** Failure lifetime is separate from failure classification. */
 export function backgroundFailurePolicy(errorClass) {
-  return POLICIES[String(errorClass ?? '')] ?? DEFAULT_POLICY
+    const key = String(errorClass ?? '');
+    return Object.prototype.hasOwnProperty.call(POLICIES, key)
+        ? POLICIES[key]
+        : DEFAULT_POLICY;
 }

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

@@ -0,0 +1,217 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+import { BENCHMARK_AXES, } from './vision-capability-evidence.js';
+import { CAPABILITY_BENCHMARK_SUITE_REVISION } from './vision-capability-fingerprint.js';
+const CACHE_VERSION = 3;
+const MAX_ENTRIES = 256;
+function propertyBag(value) {
+    return value !== null && typeof value === 'object'
+        ? value
+        : undefined;
+}
+function cleanText(value, max = 256) {
+    return typeof value === 'string' && value.trim() !== ''
+        ? value.trim().slice(0, max)
+        : '';
+}
+function benchmarkAxis(value) {
+    return BENCHMARK_AXES.includes(value)
+        ? value
+        : undefined;
+}
+function persistentFailureClass(value) {
+    return value === 'unavailable' || value === 'protocol'
+        ? value
+        : undefined;
+}
+function cleanStop(value) {
+    const record = propertyBag(value);
+    if (record === undefined)
+        return undefined;
+    if (Number(record.suiteRevision) !== CAPABILITY_BENCHMARK_SUITE_REVISION) {
+        return undefined;
+    }
+    const fingerprint = cleanText(record.fingerprint, 64);
+    if (!/^ep2_[0-9a-f]{32}$/.test(fingerprint))
+        return undefined;
+    const key = cleanText(record.key);
+    const provider = cleanText(record.provider);
+    const model = cleanText(record.model);
+    const axis = benchmarkAxis(cleanText(record.axis, 32));
+    const errorClass = persistentFailureClass(cleanText(record.errorClass, 48));
+    const errorCode = cleanText(record.errorCode, 96);
+    const recordedAt = Number(record.recordedAt);
+    const expiresAt = Number(record.expiresAt);
+    if (!key || !provider || !model || axis === undefined || errorClass === undefined) {
+        return undefined;
+    }
+    if (!Number.isFinite(recordedAt) || recordedAt <= 0)
+        return undefined;
+    if (!Number.isFinite(expiresAt) || expiresAt <= recordedAt)
+        return undefined;
+    return {
+        fingerprint,
+        key,
+        provider,
+        model,
+        axis,
+        errorClass,
+        ...(errorCode ? { errorCode } : {}),
+        recordedAt,
+        expiresAt,
+        suiteRevision: CAPABILITY_BENCHMARK_SUITE_REVISION,
+    };
+}
+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 !== undefined && 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]));
+}
+async function save(file, records, fsOps, at) {
+    const temporary = `${file}.${process.pid}.${Date.now()}.${randomUUID()}.tmp`;
+    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);
+}
+async function load(file, fsOps, at) {
+    try {
+        const raw = await fsOps.readFile(file, 'utf8');
+        const body = propertyBag(JSON.parse(raw));
+        const stops = body?.stops;
+        const version = Number(body?.version);
+        if (!Array.isArray(stops)
+            || (version !== 2 && version !== CACHE_VERSION)) {
+            return new Map();
+        }
+        const records = retainedStopMap(stops, at);
+        if (version === 2)
+            await save(file, records, fsOps, at);
+        return records;
+    }
+    catch (error) {
+        if (propertyBag(error)?.code === 'ENOENT')
+            return new Map();
+        return new Map();
+    }
+}
+/**
+ * Durable stop owner for unattended capability measurement.
+ *
+ * Only endpoint/model evidence that is benchmark-axis-scoped and safe to
+ * persist (protocol or unavailable) can enter this store. AUTH remains a
+ * process-local access condition and is rejected by runtime validation even
+ * when legacy v2 cache data contains it.
+ */
+export function createBackgroundBenchmarkStopStoreCore(options) {
+    const file = options.file;
+    const fsOps = {
+        readFile: options.fsOps?.readFile ?? readFile,
+        mkdir: options.fsOps?.mkdir ?? mkdir,
+        writeFile: options.fsOps?.writeFile ?? writeFile,
+        rename: options.fsOps?.rename ?? rename,
+    };
+    const logger = options.logger;
+    const now = typeof options.now === 'function' ? options.now : Date.now;
+    let records = new Map();
+    let saveTail = Promise.resolve();
+    const ready = load(file, fsOps, Number(now()))
+        .then((loaded) => {
+        records = loaded;
+    });
+    const persist = () => {
+        const at = Number(now());
+        saveTail = saveTail
+            .then(() => save(file, records, fsOps, at))
+            .catch((error) => {
+            logger?.warn?.('vision-router: background stop cache write failed: %s', cleanText(propertyBag(error)?.message ?? error, 240));
+        });
+        return saveTail;
+    };
+    const reconcile = () => {
+        const at = Number(now());
+        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 (reconcile())
+                await persist();
+            return [...records.values()]
+                .sort((a, b) => b.recordedAt - a.recordedAt);
+        },
+        async mark({ fingerprint, key, provider, model, axis, errorClass, errorCode, recordedAt = Number(now()), expiresAt, } = {}) {
+            await ready;
+            reconcile();
+            const clean = cleanStop({
+                fingerprint,
+                key,
+                provider,
+                model,
+                axis,
+                errorClass,
+                errorCode,
+                recordedAt,
+                expiresAt,
+                suiteRevision: CAPABILITY_BENCHMARK_SUITE_REVISION,
+            });
+            if (clean === undefined)
+                return undefined;
+            const keyOfStop = recordKey(clean);
+            records.set(keyOfStop, clean);
+            reconcile();
+            await persist();
+            return records.get(keyOfStop);
+        },
+        async clearStop(fingerprint, axis) {
+            await ready;
+            const removed = records.delete(`${String(fingerprint ?? '')}\u0000${String(axis ?? '')}`);
+            if (removed)
+                await persist();
+            return removed;
+        },
+        async clearFingerprint(fingerprint) {
+            await ready;
+            const wanted = String(fingerprint ?? '');
+            let removed = false;
+            for (const [key, record] of records.entries()) {
+                if (record.fingerprint !== wanted)
+                    continue;
+                records.delete(key);
+                removed = true;
+            }
+            if (removed)
+                await persist();
+            return removed;
+        },
+        async flush() {
+            await ready;
+            await saveTail;
+        },
+    };
+}

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

@@ -1,190 +1,19 @@
-import { randomUUID } from 'node:crypto'
-import { mkdir, readFile, rename, writeFile } from 'node:fs/promises'
 import path from 'node:path'
-import process from 'node:process'
 import { resolveDshHome } from './doctor.js'
-import { CAPABILITY_BENCHMARK_SUITE_REVISION } from './vision-capability-benchmark.js'
-
-// v1 stops had no expiry; v2 AUTH stops also persisted a secret-derived
-// credential fingerprint. Do not migrate either format: v3 persists only
-// non-secret endpoint/model stop evidence.
-const CACHE_VERSION = 3
-const MAX_ENTRIES = 256
-const AXES = new Set(['ocr', 'general', 'document', 'structured', 'grounding'])
-const CLASSES = new Set(['unavailable', 'protocol'])
-
-function cleanText(value, max = 256) {
-  return typeof value === 'string' && value.trim() !== '' ? value.trim().slice(0, max) : ''
-}
-
-function cleanStop(value) {
-  if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined
-  if (Number(value.suiteRevision) !== CAPABILITY_BENCHMARK_SUITE_REVISION) return undefined
-  const fingerprint = cleanText(value.fingerprint, 64)
-  if (!/^ep2_[0-9a-f]{32}$/.test(fingerprint)) return undefined
-  const key = cleanText(value.key)
-  const provider = cleanText(value.provider)
-  const model = cleanText(value.model)
-  const axis = cleanText(value.axis, 32)
-  const errorClass = cleanText(value.errorClass, 48)
-  const errorCode = cleanText(value.errorCode, 96)
-  const recordedAt = Number(value.recordedAt)
-  const expiresAt = Number(value.expiresAt)
-  if (!key || !provider || !model || !AXES.has(axis) || !CLASSES.has(errorClass)) return undefined
-  if (!Number.isFinite(recordedAt) || recordedAt <= 0) return undefined
-  if (!Number.isFinite(expiresAt) || expiresAt <= recordedAt) return undefined
-  return {
-    fingerprint,
-    key,
-    provider,
-    model,
-    axis,
-    errorClass,
-    ...(errorCode ? { errorCode } : {}),
-    recordedAt,
-    expiresAt,
-    suiteRevision: CAPABILITY_BENCHMARK_SUITE_REVISION,
-  }
-}
-
-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]))
-}
+import { createBackgroundBenchmarkStopStoreCore } from './vision-background-stop-store-core.js'
 
 export function backgroundBenchmarkStopCachePath(dshHome = resolveDshHome()) {
   return path.join(dshHome, 'cache', 'vision-router', 'background-benchmark-stops.json')
 }
 
-async function load(file, fsOps, at) {
-  try {
-    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 = retainedStopMap(body.stops, at)
-    if (body.version === 2) await save(file, records, fsOps, at)
-    return records
-  } catch (error) {
-    if (error?.code === 'ENOENT') return new Map()
-    return new Map()
-  }
-}
-
-async function save(file, records, fsOps, at) {
-  const temporary = `${file}.${process.pid}.${Date.now()}.${randomUUID()}.tmp`
-  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)
-}
-
+/**
+ * Keep DSH-home discovery at the dynamic Host/path boundary. The typed core
+ * owns durable stop validation, migration, retention and persistence.
+ */
 export function createBackgroundBenchmarkStopStore(options = {}) {
   const file = options.cacheFile ?? backgroundBenchmarkStopCachePath(options.dshHome)
-  const fsOps = {
-    readFile: options.fsOps?.readFile ?? readFile,
-    mkdir: options.fsOps?.mkdir ?? mkdir,
-    writeFile: options.fsOps?.writeFile ?? writeFile,
-    rename: options.fsOps?.rename ?? rename,
-  }
-  const logger = options.logger
-  const now = typeof options.now === 'function' ? options.now : Date.now
-  let records = new Map()
-  let saveTail = Promise.resolve()
-  const ready = load(file, fsOps, Number(now())).then((loaded) => { records = loaded })
-
-  const persist = () => {
-    const at = Number(now())
-    saveTail = saveTail
-      .then(() => save(file, records, fsOps, at))
-      .catch((error) => logger?.warn?.('vision-router: background stop cache write failed: %s', cleanText(error?.message ?? error, 240)))
-    return saveTail
-  }
-
-  const reconcile = () => {
-    const at = Number(now())
-    const retained = retainedStopMap(records.values(), at)
-    const changed = retained.size !== records.size || [...retained.keys()].some((key) => !records.has(key))
-    records = retained
-    return changed
-  }
-
-  return {
+  return createBackgroundBenchmarkStopStoreCore({
+    ...options,
     file,
-    async list() {
-      await ready
-      if (reconcile()) await persist()
-      return [...records.values()].sort((a, b) => b.recordedAt - a.recordedAt)
-    },
-    async mark({
-      fingerprint,
-      key,
-      provider,
-      model,
-      axis,
-      errorClass,
-      errorCode,
-      recordedAt = Number(now()),
-      expiresAt,
-    } = {}) {
-      await ready
-      reconcile()
-      const clean = cleanStop({
-        fingerprint,
-        key,
-        provider,
-        model,
-        axis,
-        errorClass,
-        errorCode,
-        recordedAt,
-        expiresAt,
-        suiteRevision: CAPABILITY_BENCHMARK_SUITE_REVISION,
-      })
-      if (!clean) return undefined
-      records.set(recordKey(clean), clean)
-      reconcile()
-      await persist()
-      return records.get(recordKey(clean))
-    },
-    async clearStop(fingerprint, axis) {
-      await ready
-      const removed = records.delete(`${String(fingerprint ?? '')}\u0000${String(axis ?? '')}`)
-      if (removed) await persist()
-      return removed
-    },
-    async clearFingerprint(fingerprint) {
-      await ready
-      const wanted = String(fingerprint ?? '')
-      let removed = false
-      for (const [key, record] of records.entries()) {
-        if (record.fingerprint !== wanted) continue
-        records.delete(key)
-        removed = true
-      }
-      if (removed) await persist()
-      return removed
-    },
-    async flush() {
-      await ready
-      await saveTail
-    },
-  }
+  })
 }