dsh-vision-router 2.2.8 → 3.0.0

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
-    },
-  }
+  })
 }

package/lib/vision-capability-benchmark-service.js

@@ -307,6 +307,7 @@ export function createExactCapabilityInvoker(ctx, core, candidate, config, optio
             maxTokens: benchmarkMaxTokensForProvider(exactHttpProvider),
             signal: callSignal,
             affinityId: benchmarkAffinityId,
+            providerTransport: options.providerTransport,
             resolveCredential: (ref) => resolvedCredentialValue(ctx, ref),
           }),
           fixtureTimeoutMs,

package/lib/vision-capability-benchmark.js

@@ -1,15 +1,19 @@
-import { createHash } from 'node:crypto'
-import process from 'node:process'
 import { VISION_INTENTS } from './vision-capability-router.js'
+import {
+  CAPABILITY_BENCHMARK_RENDERER_SCOPE,
+  CAPABILITY_BENCHMARK_SUITE_REVISION,
+  capabilityBenchmarkFingerprint,
+} from './vision-capability-fingerprint.js'
+
+export {
+  CAPABILITY_BENCHMARK_RENDERER_SCOPE,
+  CAPABILITY_BENCHMARK_SUITE_REVISION,
+  capabilityBenchmarkFingerprint,
+} from './vision-capability-fingerprint.js'
 
 const WIDTH = 768
 const HEIGHT = 512
 
-export const CAPABILITY_BENCHMARK_SUITE_REVISION = 5
-// Renderer-only fixes must invalidate prior evidence even when the scoring and
-// prompt contract (the suite revision) is unchanged.
-export const CAPABILITY_BENCHMARK_RENDERER_SCOPE = `${process.platform}/${process.arch}-proof-badge-v2`
-
 function esc(value) {
   return String(value).replace(/[&<>"']/g, (ch) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&apos;' })[ch])
 }
@@ -160,60 +164,6 @@ export function listCapabilityBenchmarkFixtures(intents = CORE_BENCHMARK_INTENTS
   return fixtures
 }
 
-function isSensitiveKey(key) {
-  return /(^|[_-])(api[_-]?key|key|token|secret|password|authorization|auth|signature|sig)([_-]|$)/i.test(String(key ?? ''))
-}
-
-function normalizeEndpoint(value) {
-  const raw = String(value ?? '').trim()
-  if (raw === '') return ''
-  try {
-    const url = new URL(raw)
-    url.username = ''
-    url.password = ''
-    url.hash = ''
-    for (const key of [...url.searchParams.keys()]) {
-      if (isSensitiveKey(key)) url.searchParams.delete(key)
-    }
-    url.searchParams.sort()
-    const pathname = url.pathname === '/' ? '' : url.pathname.replace(/\/+$/, '')
-    return `${url.protocol.toLowerCase()}//${url.host.toLowerCase()}${pathname}${url.search}`
-  } catch {
-    return raw.replace(/\/+$/, '')
-  }
-}
-
-function sanitizeFingerprintValue(value, keyHint = '') {
-  if (value === null || value === undefined) return value ?? null
-  if (Array.isArray(value)) return value.map((item) => sanitizeFingerprintValue(item))
-  if (typeof value === 'object') {
-    return Object.fromEntries(
-      Object.entries(value)
-        .filter(([key]) => !isSensitiveKey(key))
-        .sort(([a], [b]) => a.localeCompare(b))
-        .map(([key, child]) => [key, sanitizeFingerprintValue(child, key)]),
-    )
-  }
-  if (typeof value === 'string' && /(endpoint|base[_-]?url|url)$/i.test(keyHint)) return normalizeEndpoint(value)
-  if (typeof value === 'bigint') return value.toString()
-  if (typeof value === 'number' || typeof value === 'boolean' || typeof value === 'string') return value
-  return String(value)
-}
-
-export function capabilityBenchmarkFingerprint({ provider, model, endpoint, config, credentialFingerprint } = {}) {
-  const payload = JSON.stringify({
-    schema: 'vision-capability-endpoint-v2',
-    suiteRevision: CAPABILITY_BENCHMARK_SUITE_REVISION,
-    rendererScope: CAPABILITY_BENCHMARK_RENDERER_SCOPE,
-    provider: String(provider ?? '').trim(),
-    model: String(model ?? '').trim(),
-    endpoint: normalizeEndpoint(endpoint),
-    config: sanitizeFingerprintValue(config && typeof config === 'object' ? config : null),
-    credentialFingerprint: String(credentialFingerprint ?? 'none'),
-  })
-  return `ep2_${createHash('sha256').update(payload).digest('hex').slice(0, 32)}`
-}
-
 function clamp01(value) {
   return Math.max(0, Math.min(1, Number.isFinite(value) ? value : 0))
 }

package/lib/vision-capability-evidence.js

@@ -0,0 +1,35 @@
+export const VISION_INTENTS = [
+    'structured',
+    'ocr',
+    'document',
+    'ui',
+    'grounding',
+    'detection',
+    'general',
+    'chart_diagram',
+    'code_screenshot',
+    'visual_compare',
+];
+export const BENCHMARK_AXES = [
+    'structured',
+    'ocr',
+    'document',
+    'grounding',
+    'general',
+];
+const DIRECT_TASK_AXIS = Object.freeze({
+    structured: 'structured',
+    ocr: 'ocr',
+    document: 'document',
+    grounding: 'grounding',
+    general: 'general',
+});
+export function normalizeVisionIntent(intent) {
+    return typeof intent === 'string'
+        && VISION_INTENTS.includes(intent)
+        ? intent
+        : 'general';
+}
+export function benchmarkAxisForVisionIntent(intent) {
+    return DIRECT_TASK_AXIS[normalizeVisionIntent(intent)];
+}

package/lib/vision-capability-fingerprint.js

@@ -0,0 +1,72 @@
+import { createHash } from 'node:crypto';
+import process from 'node:process';
+export const CAPABILITY_BENCHMARK_SUITE_REVISION = 5;
+// Renderer-only fixes must invalidate prior evidence even when the scoring and
+// prompt contract (the suite revision) is unchanged.
+export const CAPABILITY_BENCHMARK_RENDERER_SCOPE = `${process.platform}/${process.arch}-proof-badge-v2`;
+function isSensitiveKey(key) {
+    return /(^|[_-])(api[_-]?key|key|token|secret|password|authorization|auth|signature|sig)([_-]|$)/i
+        .test(String(key ?? ''));
+}
+function normalizeEndpoint(value) {
+    const raw = String(value ?? '').trim();
+    if (raw === '')
+        return '';
+    try {
+        const url = new URL(raw);
+        url.username = '';
+        url.password = '';
+        url.hash = '';
+        for (const key of [...url.searchParams.keys()]) {
+            if (isSensitiveKey(key))
+                url.searchParams.delete(key);
+        }
+        url.searchParams.sort();
+        const pathname = url.pathname === '/' ? '' : url.pathname.replace(/\/+$/, '');
+        return `${url.protocol.toLowerCase()}//${url.host.toLowerCase()}${pathname}${url.search}`;
+    }
+    catch {
+        return raw.replace(/\/+$/, '');
+    }
+}
+function sanitizeFingerprintValue(value, keyHint = '') {
+    if (value === null || value === undefined)
+        return value ?? null;
+    if (Array.isArray(value)) {
+        return value.map((item) => sanitizeFingerprintValue(item));
+    }
+    if (typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value)
+            .filter(([key]) => !isSensitiveKey(key))
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([key, child]) => [
+            key,
+            sanitizeFingerprintValue(child, key),
+        ]));
+    }
+    if (typeof value === 'string'
+        && /(endpoint|base[_-]?url|url)$/i.test(keyHint)) {
+        return normalizeEndpoint(value);
+    }
+    if (typeof value === 'bigint')
+        return value.toString();
+    if (typeof value === 'number'
+        || typeof value === 'boolean'
+        || typeof value === 'string') {
+        return value;
+    }
+    return String(value);
+}
+export function capabilityBenchmarkFingerprint({ provider, model, endpoint, config, credentialFingerprint, } = {}) {
+    const payload = JSON.stringify({
+        schema: 'vision-capability-endpoint-v2',
+        suiteRevision: CAPABILITY_BENCHMARK_SUITE_REVISION,
+        rendererScope: CAPABILITY_BENCHMARK_RENDERER_SCOPE,
+        provider: String(provider ?? '').trim(),
+        model: String(model ?? '').trim(),
+        endpoint: normalizeEndpoint(endpoint),
+        config: sanitizeFingerprintValue(config && typeof config === 'object' ? config : null),
+        credentialFingerprint: String(credentialFingerprint ?? 'none'),
+    });
+    return `ep2_${createHash('sha256').update(payload).digest('hex').slice(0, 32)}`;
+}