dsh-vision-router 2.3.0 → 3.0.1

package/lib/vision-routing-authority.js

@@ -1,46 +1,42 @@
-import { normalizeVisionRoutingMode } from './vision-routing-product.js'
-
-export const BACKGROUND_MEASUREMENT_MODES = Object.freeze(['off', 'local-free', 'all'])
-
-const BACKGROUND_MEASUREMENT_SET = new Set(BACKGROUND_MEASUREMENT_MODES)
-const MANUAL_MEASUREMENT_GRANT = Symbol('vision-router-manual-measurement-grant')
-
+import { normalizeVisionRoutingMode, } from './vision-routing-product.js';
+export const BACKGROUND_MEASUREMENT_MODES = Object.freeze(['off', 'local-free', 'all']);
+const BACKGROUND_MEASUREMENT_SET = new Set(BACKGROUND_MEASUREMENT_MODES);
+const MANUAL_MEASUREMENT_GRANT = Symbol('vision-router-manual-measurement-grant');
 function plainObject(value) {
-  return value !== null && typeof value === 'object' && !Array.isArray(value)
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
-
 export function normalizeBackgroundMeasurementAuthority(value, fallback = 'off') {
-  const normalizedFallback = BACKGROUND_MEASUREMENT_SET.has(fallback) ? fallback : 'off'
-  return typeof value === 'string' && BACKGROUND_MEASUREMENT_SET.has(value.trim())
-    ? value.trim()
-    : normalizedFallback
+    const normalizedFallback = typeof fallback === 'string' && BACKGROUND_MEASUREMENT_SET.has(fallback)
+        ? fallback
+        : 'off';
+    const candidate = typeof value === 'string' ? value.trim() : '';
+    return BACKGROUND_MEASUREMENT_SET.has(candidate)
+        ? candidate
+        : normalizedFallback;
 }
-
 /**
  * Resolve only user-delegated v2 authority. Evidence, preference, credentials,
  * capability gaps, or internal shadow switches must never widen this result.
  */
 export function resolveVisionRoutingAuthority(config = {}) {
-  const source = plainObject(config) ? config : {}
-  const execution = normalizeVisionRoutingMode(source.routingMode)
-  const backgroundMeasurement = normalizeBackgroundMeasurementAuthority(source.backgroundBenchmarking)
-  const autoSelectionAuthorized = execution === 'auto'
-  const backgroundMeasurementAuthorized = backgroundMeasurement !== 'off'
-
-  return Object.freeze({
-    execution,
-    autoSelectionAuthorized,
-    backgroundMeasurement,
-    backgroundMeasurementAuthorized,
-    // Current background profiler is useful only for Auto preparation, but the
-    // standing measurement grant remains independent from execution authority.
-    backgroundMeasurementActive: autoSelectionAuthorized && backgroundMeasurementAuthorized,
-    ephemeralRuntimeObservation: autoSelectionAuthorized,
-    // No v2 setting currently grants durable user-specific behavioral learning.
-    persistentLearning: false,
-  })
+    const source = plainObject(config) ? config : {};
+    const execution = normalizeVisionRoutingMode(source.routingMode);
+    const backgroundMeasurement = normalizeBackgroundMeasurementAuthority(source.backgroundBenchmarking);
+    const autoSelectionAuthorized = execution === 'auto';
+    const backgroundMeasurementAuthorized = backgroundMeasurement !== 'off';
+    return Object.freeze({
+        execution,
+        autoSelectionAuthorized,
+        backgroundMeasurement,
+        backgroundMeasurementAuthorized,
+        // Current background profiler is useful only for Auto preparation, but the
+        // standing measurement grant remains independent from execution authority.
+        backgroundMeasurementActive: autoSelectionAuthorized && backgroundMeasurementAuthorized,
+        ephemeralRuntimeObservation: autoSelectionAuthorized,
+        // No v2 setting currently grants durable user-specific behavioral learning.
+        persistentLearning: false,
+    });
 }
-
 /**
  * A manual measurement grant is intentionally opaque and process-local. The
  * local HTTP action creates one only after an explicit user POST. Requiring the
@@ -48,23 +44,26 @@ export function resolveVisionRoutingAuthority(config = {}) {
  * inheriting "manual" semantics by convention.
  */
 export function grantManualMeasurementFromUserAction(source = 'local-ui') {
-  if (source !== 'local-ui') {
-    throw new TypeError('manual measurement authority source must be local-ui')
-  }
-  return Object.freeze({
-    kind: 'manual-measurement',
-    source,
-    [MANUAL_MEASUREMENT_GRANT]: true,
-  })
+    if (source !== 'local-ui') {
+        throw new TypeError('manual measurement authority source must be local-ui');
+    }
+    const grant = {
+        kind: 'manual-measurement',
+        source,
+        [MANUAL_MEASUREMENT_GRANT]: true,
+    };
+    return Object.freeze(grant);
 }
-
 export function hasManualMeasurementAuthority(value) {
-  return !!value && value[MANUAL_MEASUREMENT_GRANT] === true && value.kind === 'manual-measurement'
+    if (!value || typeof value !== 'object')
+        return false;
+    const candidate = value;
+    return candidate[MANUAL_MEASUREMENT_GRANT] === true && candidate.kind === 'manual-measurement';
 }
-
 export function assertManualMeasurementAuthority(value) {
-  if (hasManualMeasurementAuthority(value)) return value
-  const error = new Error('explicit manual measurement authority is required')
-  error.code = 'CAPABILITY_BENCHMARK_AUTHORITY_REQUIRED'
-  throw error
+    if (hasManualMeasurementAuthority(value))
+        return value;
+    const error = new Error('explicit manual measurement authority is required');
+    error.code = 'CAPABILITY_BENCHMARK_AUTHORITY_REQUIRED';
+    throw error;
 }

package/lib/vision-routing-product.js

@@ -5,40 +5,37 @@
 // A user chooses whether routing is automatic or strictly ordered, then chooses
 // a plain-language preference. The actual execution-changing auto mode is
 // enabled only when the runtime is ready to honor this contract.
-
-export const VISION_ROUTING_MODES = Object.freeze(['ordered', 'auto'])
-export const VISION_ROUTING_PREFERENCES = Object.freeze(['balanced', 'quality', 'speed', 'local'])
-
-const MODE_SET = new Set(VISION_ROUTING_MODES)
-const PREFERENCE_SET = new Set(VISION_ROUTING_PREFERENCES)
-
+export const VISION_ROUTING_MODES = Object.freeze(['ordered', 'auto']);
+export const VISION_ROUTING_PREFERENCES = Object.freeze(['balanced', 'quality', 'speed', 'local']);
+const MODE_SET = new Set(VISION_ROUTING_MODES);
+const PREFERENCE_SET = new Set(VISION_ROUTING_PREFERENCES);
 export function normalizeVisionRoutingMode(value, fallback = 'ordered') {
-  const normalizedFallback = MODE_SET.has(fallback) ? fallback : 'ordered'
-  return typeof value === 'string' && MODE_SET.has(value.trim()) ? value.trim() : normalizedFallback
+    const normalizedFallback = typeof fallback === 'string' && MODE_SET.has(fallback) ? fallback : 'ordered';
+    const candidate = typeof value === 'string' ? value.trim() : '';
+    return MODE_SET.has(candidate) ? candidate : normalizedFallback;
 }
-
 export function normalizeVisionRoutingPreference(value) {
-  if (typeof value === 'string') {
-    const candidate = value.trim()
-    if (PREFERENCE_SET.has(candidate)) return candidate
-  }
-
-  return 'balanced'
+    if (typeof value === 'string') {
+        const candidate = value.trim();
+        if (PREFERENCE_SET.has(candidate))
+            return candidate;
+    }
+    return 'balanced';
 }
-
 export function routingPreferenceToCapabilityStrategy(preference) {
-  const normalized = normalizeVisionRoutingPreference(preference)
-  return normalized === 'local' ? 'privacy' : normalized
+    const normalized = normalizeVisionRoutingPreference(preference);
+    return normalized === 'local' ? 'privacy' : normalized;
 }
-
 export function resolveVisionRoutingProduct(config = {}) {
-  const source = config && typeof config === 'object' && !Array.isArray(config) ? config : {}
-  const mode = normalizeVisionRoutingMode(source.routingMode)
-  const preference = normalizeVisionRoutingPreference(source.routingPreference)
-  return {
-    mode,
-    preference,
-    strategy: routingPreferenceToCapabilityStrategy(preference),
-    automatic: mode === 'auto',
-  }
+    const source = config && typeof config === 'object' && !Array.isArray(config)
+        ? config
+        : {};
+    const mode = normalizeVisionRoutingMode(source.routingMode);
+    const preference = normalizeVisionRoutingPreference(source.routingPreference);
+    return {
+        mode,
+        preference,
+        strategy: routingPreferenceToCapabilityStrategy(preference),
+        automatic: mode === 'auto',
+    };
 }

package/lib/vision-routing-settings-prelude.js

@@ -446,7 +446,7 @@ export const VISION_ROUTING_SETTINGS_PRELUDE = String.raw`(function(){
     try { state.backgroundTimer && state.backgroundTimer.unref && state.backgroundTimer.unref(); } catch (_) {}
     schedule();
 
-    var dispose = function() {
+    var dispose = async function() {
       state.disposed = true;
       if (state.scanTimer !== undefined) clearTimeout(state.scanTimer);
       if (state.backgroundTimer !== undefined) clearInterval(state.backgroundTimer);
@@ -456,13 +456,18 @@ export const VISION_ROUTING_SETTINGS_PRELUDE = String.raw`(function(){
         try { disposeRemote(); } catch (_) {}
       });
       state.remoteDisposers.length = 0;
-      if (remote && scope && typeof scope.dispose === 'function') void scope.dispose();
       if (state.panel && state.panel.parentNode) state.panel.parentNode.removeChild(state.panel);
       if (states) states.delete(ctx);
+      if (remote && scope && typeof scope.dispose === 'function') await scope.dispose();
     };
+    var lifecycleOwned = false;
     try {
-      if (typeof ctx.effect === 'function') ctx.effect(function(){ return dispose; }, 'vision-router: routing settings product panel');
+      if (typeof ctx.effect === 'function') {
+        ctx.effect(function(){ return dispose; }, 'vision-router: routing settings product panel');
+        lifecycleOwned = true;
+      }
     } catch (_) {}
+    if (!lifecycleOwned) void dispose().catch(function(){});
   }
 
   function patchLoader(loader) {

package/lib/vision-runtime-performance-store.js

@@ -0,0 +1,166 @@
+import { BENCHMARK_AXES, } from './vision-capability-evidence.js';
+export const DEFAULT_RUNTIME_PERFORMANCE_MAX_AGE_MS = 60 * 60 * 1000;
+export const DEFAULT_RUNTIME_PERFORMANCE_MAX_SAMPLES = 8;
+export const DEFAULT_RUNTIME_PERFORMANCE_MIN_SAMPLES = 2;
+export const DEFAULT_RUNTIME_PERFORMANCE_MAX_BACKENDS = 128;
+function finiteLatency(value) {
+    const number = Number(value);
+    return Number.isFinite(number) && number >= 0 ? number : undefined;
+}
+function median(values) {
+    const sorted = values.filter(Number.isFinite).sort((a, b) => a - b);
+    if (sorted.length === 0)
+        return undefined;
+    const middle = Math.floor(sorted.length / 2);
+    const right = sorted[middle];
+    if (right === undefined)
+        return undefined;
+    if (sorted.length % 2 === 1)
+        return right;
+    const left = sorted[middle - 1];
+    return left === undefined ? right : (left + right) / 2;
+}
+function cleanBackendKey(value) {
+    const text = typeof value === 'string' ? value.trim() : '';
+    return text === '' ? undefined : text.slice(0, 512);
+}
+function isBenchmarkAxis(value) {
+    return typeof value === 'string'
+        && BENCHMARK_AXES.includes(value);
+}
+export function createVisionRuntimePerformanceSampleStore(options = {}) {
+    const now = typeof options.now === 'function' ? options.now : Date.now;
+    const maxAgeMs = Math.max(1_000, Number(options.maxAgeMs) || DEFAULT_RUNTIME_PERFORMANCE_MAX_AGE_MS);
+    const maxSamples = Math.max(1, Math.min(64, Math.floor(Number(options.maxSamples) || DEFAULT_RUNTIME_PERFORMANCE_MAX_SAMPLES)));
+    const minSamples = Math.max(1, Math.min(maxSamples, Math.floor(Number(options.minSamples) || DEFAULT_RUNTIME_PERFORMANCE_MIN_SAMPLES)));
+    const maxBackends = Math.max(1, Math.min(1024, Math.floor(Number(options.maxBackends) || DEFAULT_RUNTIME_PERFORMANCE_MAX_BACKENDS)));
+    const records = new Map();
+    let identityContext = options.context;
+    const identityResolver = options.identityResolver;
+    const resolvedStorageKey = (backendKey) => {
+        const key = cleanBackendKey(backendKey);
+        if (key === undefined)
+            return undefined;
+        let identity;
+        try {
+            identity = identityContext && identityResolver !== undefined
+                ? identityResolver(key, identityContext)
+                : undefined;
+        }
+        catch {
+            identity = undefined;
+        }
+        return identity ? `${key}\u0000${String(identity)}` : key;
+    };
+    const pruneAxis = (samples, at) => samples.filter((sample) => at - sample.at <= maxAgeMs);
+    const pruneBackend = (key, at) => {
+        const axes = records.get(key);
+        if (axes === undefined)
+            return undefined;
+        for (const [axis, samples] of axes) {
+            const current = pruneAxis(samples, at);
+            if (current.length === 0)
+                axes.delete(axis);
+            else if (current.length !== samples.length)
+                axes.set(axis, current);
+        }
+        if (axes.size === 0) {
+            records.delete(key);
+            return undefined;
+        }
+        records.delete(key);
+        records.set(key, axes);
+        return axes;
+    };
+    const bound = () => {
+        while (records.size > maxBackends) {
+            const oldest = records.keys().next().value;
+            if (oldest === undefined)
+                break;
+            records.delete(oldest);
+        }
+    };
+    return {
+        maxAgeMs,
+        maxSamples,
+        minSamples,
+        bindContext(context) {
+            identityContext = context;
+        },
+        record(backendKey, axisValue, latencyMsValue, atValue = now()) {
+            const key = resolvedStorageKey(backendKey);
+            const latencyMs = finiteLatency(latencyMsValue);
+            const at = Number(atValue);
+            if (key === undefined
+                || !isBenchmarkAxis(axisValue)
+                || latencyMs === undefined
+                || !Number.isFinite(at)) {
+                return false;
+            }
+            let axes = pruneBackend(key, at);
+            if (axes === undefined) {
+                axes = new Map();
+                records.set(key, axes);
+            }
+            const current = pruneAxis(axes.get(axisValue) ?? [], at);
+            current.push({ at, latencyMs });
+            if (current.length > maxSamples) {
+                current.splice(0, current.length - maxSamples);
+            }
+            axes.set(axisValue, current);
+            records.delete(key);
+            records.set(key, axes);
+            bound();
+            return true;
+        },
+        get(backendKey, atValue = now()) {
+            const key = resolvedStorageKey(backendKey);
+            const at = Number(atValue);
+            if (key === undefined || !Number.isFinite(at))
+                return undefined;
+            const axes = pruneBackend(key, at);
+            if (axes === undefined)
+                return undefined;
+            const observedLatencyMsByAxis = {};
+            const runtimeLatencyMsByAxis = {};
+            const sampleCountByAxis = {};
+            const observedAtByAxis = {};
+            for (const [axis, samples] of axes) {
+                const latencyMs = median(samples.map((sample) => sample.latencyMs));
+                if (latencyMs === undefined)
+                    continue;
+                observedLatencyMsByAxis[axis] = latencyMs;
+                sampleCountByAxis[axis] = samples.length;
+                observedAtByAxis[axis] = Math.max(...samples.map((sample) => sample.at));
+                if (samples.length >= minSamples)
+                    runtimeLatencyMsByAxis[axis] = latencyMs;
+            }
+            return {
+                runtimeLatencyMsByAxis,
+                observedLatencyMsByAxis,
+                sampleCountByAxis,
+                observedAtByAxis,
+                maxAgeMs,
+                minSamples,
+            };
+        },
+        clear(backendKey) {
+            if (backendKey === undefined) {
+                records.clear();
+                return;
+            }
+            const base = cleanBackendKey(backendKey);
+            if (base === undefined)
+                return;
+            records.delete(base);
+            const prefix = `${base}\u0000`;
+            for (const key of [...records.keys()]) {
+                if (key.startsWith(prefix))
+                    records.delete(key);
+            }
+        },
+        size() {
+            return records.size;
+        },
+    };
+}

package/lib/vision-runtime-performance.js

@@ -1,37 +1,19 @@
 import { AsyncLocalStorage } from 'node:async_hooks'
-import {
-  benchmarkAxisForVisionIntent,
-  inferToolVisionIntent,
-} from './vision-capability-router.js'
+import { benchmarkAxisForVisionIntent } from './vision-capability-evidence.js'
+import { inferToolVisionIntent } from './vision-capability-router.js'
 import { capabilityEvidenceFingerprint } from './vision-capability-identity.js'
 import { providerTransportFor } from './live-model-discovery.js'
+import { createVisionRuntimePerformanceSampleStore } from './vision-runtime-performance-store.js'
 
-export const DEFAULT_RUNTIME_PERFORMANCE_MAX_AGE_MS = 60 * 60 * 1000
-export const DEFAULT_RUNTIME_PERFORMANCE_MAX_SAMPLES = 8
-export const DEFAULT_RUNTIME_PERFORMANCE_MIN_SAMPLES = 2
-export const DEFAULT_RUNTIME_PERFORMANCE_MAX_BACKENDS = 128
+export {
+  DEFAULT_RUNTIME_PERFORMANCE_MAX_AGE_MS,
+  DEFAULT_RUNTIME_PERFORMANCE_MAX_SAMPLES,
+  DEFAULT_RUNTIME_PERFORMANCE_MIN_SAMPLES,
+  DEFAULT_RUNTIME_PERFORMANCE_MAX_BACKENDS,
+} from './vision-runtime-performance-store.js'
 
 const runtimeScope = new AsyncLocalStorage()
 
-function finiteLatency(value) {
-  const number = Number(value)
-  return Number.isFinite(number) && number >= 0 ? number : undefined
-}
-
-function median(values) {
-  const sorted = values.filter(Number.isFinite).sort((a, b) => a - b)
-  if (sorted.length === 0) return undefined
-  const middle = Math.floor(sorted.length / 2)
-  return sorted.length % 2 === 1
-    ? sorted[middle]
-    : (sorted[middle - 1] + sorted[middle]) / 2
-}
-
-function cleanBackendKey(value) {
-  const text = typeof value === 'string' ? value.trim() : ''
-  return text === '' ? undefined : text.slice(0, 512)
-}
-
 function backendParts(backendKey) {
   const key = cleanBackendKey(backendKey)
   if (!key) return undefined
@@ -91,124 +73,13 @@ function failureFinish(chunk) {
 }
 
 export function createVisionRuntimePerformanceStore(options = {}) {
-  const now = typeof options.now === 'function' ? options.now : Date.now
-  const maxAgeMs = Math.max(1_000, Number(options.maxAgeMs) || DEFAULT_RUNTIME_PERFORMANCE_MAX_AGE_MS)
-  const maxSamples = Math.max(1, Math.min(64, Math.floor(Number(options.maxSamples) || DEFAULT_RUNTIME_PERFORMANCE_MAX_SAMPLES)))
-  const minSamples = Math.max(1, Math.min(maxSamples, Math.floor(Number(options.minSamples) || DEFAULT_RUNTIME_PERFORMANCE_MIN_SAMPLES)))
-  const maxBackends = Math.max(1, Math.min(1024, Math.floor(Number(options.maxBackends) || DEFAULT_RUNTIME_PERFORMANCE_MAX_BACKENDS)))
-  const records = new Map()
-  let identityContext = options.context
   const identityResolver = typeof options.identityResolver === 'function'
     ? options.identityResolver
     : (backendKey, ctx) => runtimePerformanceIdentityFor(ctx, backendKey)
-
-  const resolvedStorageKey = (backendKey) => {
-    const key = cleanBackendKey(backendKey)
-    if (!key) return undefined
-    let identity
-    try { identity = identityContext ? identityResolver(key, identityContext) : undefined } catch { identity = undefined }
-    return identity ? `${key}\u0000${identity}` : key
-  }
-
-  const pruneAxis = (samples, at) => samples.filter((sample) => at - sample.at <= maxAgeMs)
-
-  const pruneBackend = (key, at) => {
-    const axes = records.get(key)
-    if (!axes) return undefined
-    for (const [axis, samples] of axes) {
-      const current = pruneAxis(samples, at)
-      if (current.length === 0) axes.delete(axis)
-      else if (current.length !== samples.length) axes.set(axis, current)
-    }
-    if (axes.size === 0) {
-      records.delete(key)
-      return undefined
-    }
-    // LRU touch only on runtime-observation reads/writes; routing diagnostics
-    // are allowed to read this performance store because it is not the v1
-    // breaker and has no execution side effects.
-    records.delete(key)
-    records.set(key, axes)
-    return axes
-  }
-
-  const bound = () => {
-    while (records.size > maxBackends) {
-      const oldest = records.keys().next().value
-      if (oldest === undefined) break
-      records.delete(oldest)
-    }
-  }
-
-  return {
-    maxAgeMs,
-    maxSamples,
-    minSamples,
-    bindContext(ctx) {
-      identityContext = ctx
-    },
-    record(backendKey, axis, latencyMs, at = now()) {
-      const key = resolvedStorageKey(backendKey)
-      const latency = finiteLatency(latencyMs)
-      const timestamp = Number(at)
-      if (!key || !benchmarkAxisForVisionIntent(axis) || latency === undefined || !Number.isFinite(timestamp)) return false
-      let axes = pruneBackend(key, timestamp)
-      if (!axes) {
-        axes = new Map()
-        records.set(key, axes)
-      }
-      const current = pruneAxis(axes.get(axis) ?? [], timestamp)
-      current.push({ at: timestamp, latencyMs: latency })
-      if (current.length > maxSamples) current.splice(0, current.length - maxSamples)
-      axes.set(axis, current)
-      records.delete(key)
-      records.set(key, axes)
-      bound()
-      return true
-    },
-    get(backendKey, at = now()) {
-      const key = resolvedStorageKey(backendKey)
-      const timestamp = Number(at)
-      if (!key || !Number.isFinite(timestamp)) return undefined
-      const axes = pruneBackend(key, timestamp)
-      if (!axes) return undefined
-      const observedLatencyMsByAxis = {}
-      const runtimeLatencyMsByAxis = {}
-      const sampleCountByAxis = {}
-      const observedAtByAxis = {}
-      for (const [axis, samples] of axes) {
-        const latencies = samples.map((sample) => sample.latencyMs)
-        const value = median(latencies)
-        if (value === undefined) continue
-        observedLatencyMsByAxis[axis] = value
-        sampleCountByAxis[axis] = samples.length
-        observedAtByAxis[axis] = Math.max(...samples.map((sample) => sample.at))
-        if (samples.length >= minSamples) runtimeLatencyMsByAxis[axis] = value
-      }
-      return {
-        runtimeLatencyMsByAxis,
-        observedLatencyMsByAxis,
-        sampleCountByAxis,
-        observedAtByAxis,
-        maxAgeMs,
-        minSamples,
-      }
-    },
-    clear(backendKey) {
-      if (backendKey === undefined) {
-        records.clear()
-        return
-      }
-      const base = cleanBackendKey(backendKey)
-      if (!base) return
-      records.delete(base)
-      const prefix = `${base}\u0000`
-      for (const key of [...records.keys()]) if (key.startsWith(prefix)) records.delete(key)
-    },
-    size() {
-      return records.size
-    },
-  }
+  return createVisionRuntimePerformanceSampleStore({
+    ...options,
+    identityResolver,
+  })
 }
 
 export function withVisionRuntimePerformanceScope(toolName, args, fn) {