dsh-vision-router 2.3.0 → 3.0.0

package/lib/core-vision-surface-domain.js

@@ -0,0 +1,63 @@
+import { resolveSessionSurfacePolicy, } from './session-surface-policy-domain.js';
+export const CORE_VISION_SURFACE_KEYS = [
+    'tool',
+    'rewriteImages',
+    'instantDescribe',
+    'autoActivateOnImage',
+    'structuredVisionBootstrap',
+];
+function objectRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function own(object, key) {
+    return Object.prototype.hasOwnProperty.call(object, key);
+}
+function coreFlags(values) {
+    return {
+        toolAvailable: values.tool !== false,
+        rewriteEnabled: values.rewriteImages !== false,
+        instantDescribe: values.instantDescribe === true,
+        autoActivateOnImage: values.autoActivateOnImage !== false,
+        structuredBootstrap: values.structuredVisionBootstrap === true,
+    };
+}
+/**
+ * Explicit Core-facing projection of SessionSurfacePolicy.
+ *
+ * Only the five historical Core switches cross this boundary. Unrelated plugin
+ * Settings cannot masquerade as a Core config/Settings object.
+ */
+export function projectCoreVisionSurface(config = {}, sessionPolicy) {
+    const value = objectRecord(config) ?? {};
+    const policyRecord = objectRecord(sessionPolicy);
+    const policy = policyRecord !== undefined
+        ? policyRecord
+        : resolveSessionSurfacePolicy({ config: value });
+    const overrides = objectRecord(policy.legacyConfigOverrides) ?? {};
+    const projected = {};
+    for (const key of CORE_VISION_SURFACE_KEYS) {
+        projected[key] = own(overrides, key)
+            ? overrides[key]
+            : value[key];
+    }
+    const values = Object.freeze(projected);
+    return Object.freeze({
+        ownership: typeof policy.ownership === 'string'
+            ? policy.ownership
+            : undefined,
+        preserveRawImages: policy.preserveRawImages === true,
+        rewriteCurrentImages: policy.rewriteCurrentImages === true,
+        ...coreFlags(values),
+        values,
+    });
+}
+export function resolveCoreVisionSurface({ visionPolicy, config = {}, schemaBootstrapping = false, } = {}) {
+    const value = objectRecord(config) ?? {};
+    return projectCoreVisionSurface(value, resolveSessionSurfacePolicy({
+        visionPolicy,
+        config: value,
+        schemaBootstrapping,
+    }));
+}

package/lib/core-vision-surface.js

@@ -1,82 +1,20 @@
+import { currentSessionSurfacePolicy } from './session-surface-policy.js'
 import {
-  currentSessionSurfacePolicy,
-  resolveSessionSurfacePolicy,
-} from './session-surface-policy.js'
+  CORE_VISION_SURFACE_KEYS,
+  projectCoreVisionSurface,
+  resolveCoreVisionSurface,
+} from './core-vision-surface-domain.js'
 
-const CORE_SURFACE_KEYS = Object.freeze([
-  'tool',
-  'rewriteImages',
-  'instantDescribe',
-  'autoActivateOnImage',
-  'structuredVisionBootstrap',
-])
+export {
+  CORE_VISION_SURFACE_KEYS,
+  projectCoreVisionSurface,
+  resolveCoreVisionSurface,
+} from './core-vision-surface-domain.js'
 
 function isObject(value) {
   return value !== null && typeof value === 'object' && !Array.isArray(value)
 }
 
-function own(object, key) {
-  return Object.prototype.hasOwnProperty.call(object, key)
-}
-
-function coreFlags(values) {
-  return {
-    toolAvailable: values.tool !== false,
-    rewriteEnabled: values.rewriteImages !== false,
-    instantDescribe: values.instantDescribe === true,
-    autoActivateOnImage: values.autoActivateOnImage !== false,
-    structuredBootstrap: values.structuredVisionBootstrap === true,
-  }
-}
-
-/**
- * Explicit core-facing projection of the SessionSurfacePolicy.
- *
- * The returned object carries only the five config values that the historical
- * Settings/config projection could override plus explicit booleans consumed by
- * Core and the already-resolved image ownership facts. It deliberately cannot
- * masquerade as a Settings service or a full plugin config object.
- */
-export function projectCoreVisionSurface(config = {}, sessionPolicy) {
-  const value = isObject(config) ? config : {}
-  const policy = sessionPolicy && typeof sessionPolicy === 'object'
-    ? sessionPolicy
-    : resolveSessionSurfacePolicy({ config: value })
-  const overrides = isObject(policy.legacyConfigOverrides)
-    ? policy.legacyConfigOverrides
-    : {}
-  const projected = {}
-
-  for (const key of CORE_SURFACE_KEYS) {
-    projected[key] = own(overrides, key) ? overrides[key] : value[key]
-  }
-
-  return Object.freeze({
-    ownership: policy.ownership,
-    preserveRawImages: policy.preserveRawImages === true,
-    rewriteCurrentImages: policy.rewriteCurrentImages === true,
-    ...coreFlags(projected),
-    values: Object.freeze(projected),
-  })
-}
-
-/** Resolve an explicit core surface from an explicit ownership-policy input. */
-export function resolveCoreVisionSurface({
-  visionPolicy,
-  config = {},
-  schemaBootstrapping = false,
-} = {}) {
-  const value = isObject(config) ? config : {}
-  return projectCoreVisionSurface(
-    value,
-    resolveSessionSurfacePolicy({
-      visionPolicy,
-      config: value,
-      schemaBootstrapping,
-    }),
-  )
-}
-
 /** Resolve the current turn-local surface without exposing a Settings facade. */
 export function currentCoreVisionSurface(config = {}, options = {}) {
   const value = isObject(config) ? config : {}
@@ -92,9 +30,7 @@ export function currentCoreVisionSurface(config = {}, options = {}) {
  * One explicit production seam for Core's five policy-derived switches.
  *
  * The config source stays live, but schema bootstrap is an internal lifecycle
- * bit rather than a fake Settings/config value. Direct Core callers can keep
- * their two-argument compatibility path; composition passes this runtime as
- * the authoritative production surface.
+ * bit rather than a fake Settings/config value.
  */
 export function createCoreVisionSurfaceRuntime({ config = {} } = {}) {
   let schemaBootstrapping = true
@@ -120,5 +56,3 @@ export function createCoreVisionSurfaceRuntime({ config = {} } = {}) {
     },
   })
 }
-
-export const CORE_VISION_SURFACE_KEYS = CORE_SURFACE_KEYS

package/lib/delegated-call-config.js

@@ -1,27 +1,18 @@
 const ROUTE_OWNED_CALL_FIELDS = Object.freeze([
-  'reasoningEffort',
-  'temperature',
-  'maxTokens',
-  'stop',
-])
-
-/**
- * Project an internal Vision Router delegation onto a different provider/model.
- *
- * The delegated route owns its own call defaults and compatibility. Carry the
- * request payload and lifecycle through, but never leak source-route sampling,
- * reasoning or output-limit state into the target adapter. DSH will materialize
- * the target adapter's configured defaults when these fields are absent.
- *
- * Direct transports owned by Vision Router do not use this projection; their
- * wire compatibility remains the Router's responsibility.
- */
+    'reasoningEffort',
+    'temperature',
+    'maxTokens',
+    'stop',
+]);
 export function projectDelegatedCallConfig(options) {
-  if (!options || typeof options !== 'object' || Array.isArray(options)) return options
-  if (!ROUTE_OWNED_CALL_FIELDS.some((field) => Object.hasOwn(options, field))) return options
-  const next = { ...options }
-  for (const field of ROUTE_OWNED_CALL_FIELDS) delete next[field]
-  return next
+    if (!options || typeof options !== 'object' || Array.isArray(options))
+        return options;
+    const record = options;
+    if (!ROUTE_OWNED_CALL_FIELDS.some((field) => Object.hasOwn(record, field)))
+        return options;
+    const next = { ...record };
+    for (const field of ROUTE_OWNED_CALL_FIELDS)
+        delete next[field];
+    return next;
 }
-
-export const delegatedRouteOwnedCallFields = ROUTE_OWNED_CALL_FIELDS
+export const delegatedRouteOwnedCallFields = ROUTE_OWNED_CALL_FIELDS;

package/lib/doctor-runtime.js

@@ -52,6 +52,10 @@ export async function probeRuntime({
   dshHome,
   applicableProfiles = [],
   timeoutMs = 800,
+  // Doctor probes are a CLI surface: they never install a process fetch
+  // wrapper and must observe whatever transport the surrounding process
+  // currently provides.
+  // diagnostics-lint: sealed-process-global
   fetchImpl = globalThis.fetch,
 } = {}) {
   if (typeof fetchImpl !== 'function') throw new TypeError('runtime probe requires fetch')
@@ -220,7 +224,6 @@ function chromiumCandidates(env = process.env) {
 }
 
 const HOST_PACKAGES = [
-  '@deepseek-ai/dsh-client-runtime',
   '@deepseek-ai/dsh-client-ui-settings-plugins',
   '@deepseek-ai/dsh-attachment-local',
   '@deepseek-ai/dsh-llm-deepseek',

package/lib/dsh-contract-compat.js

@@ -31,232 +31,19 @@ const VISION_ROUTER_NORMALIZED_BYTES = LEGACY_VISION_ATTACHMENT_BYTES
 const HOST_CAPABILITIES_PATH = '/_dsh/vision-router/host-capabilities'
 const capabilityRouteInstalls = new WeakSet()
 
-function sessionQueryOf(ctx) {
-  if (!ctx || typeof ctx !== 'object') return undefined
-  try {
-    if (typeof ctx.get === 'function') {
-      const query = ctx.get('sessionQuery')
-      if (query && typeof query === 'object') return query
-    }
-  } catch {
-    // A partial/legacy Host may not expose SessionQuery through ctx.get().
-  }
-  try {
-    const query = ctx.sessionQuery
-    return query && typeof query === 'object' ? query : undefined
-  } catch {
-    return undefined
-  }
-}
-
-/**
- * Build the narrow bounded Session event reader used by durable surface repair.
- * DSH rc.8+ exposes `sessionQuery.readEvent({ sessionId, seq })`; resolve the
- * service at call time so Host service replacement/hot reload stays visible.
- * Missing capability is explicit and lets isolated/legacy callers use their
- * existing Session-local compatibility fallback. Once the Host advertises the
- * reader, operational failures propagate instead of silently falling back to
- * deprecated synchronous Session history.
- */
-export function createSessionEventReader(ctx) {
-  return async function readSessionEvent(session, seq) {
-    const sessionId = session?.id
-    if (sessionId === undefined || sessionId === null) return { supported: false }
-    if (!Number.isSafeInteger(seq) || seq < 0 || Object.is(seq, -0)) {
-      throw new TypeError(`session event seq must be a non-negative safe integer, got ${String(seq)}`)
-    }
-    const query = sessionQueryOf(ctx)
-    if (!query || typeof query.readEvent !== 'function') return { supported: false }
-    const window = await query.readEvent({ sessionId, seq })
-    const event = window?.target
-    if (!event || typeof event !== 'object') {
-      throw new Error(`sessionQuery.readEvent returned no target for seq ${seq}`)
-    }
-    if (event.seq !== undefined && event.seq !== seq) {
-      throw new Error(`sessionQuery.readEvent returned seq ${String(event.seq)} for requested seq ${seq}`)
-    }
-    return { supported: true, event }
-  }
-}
-
-
-const SESSION_EVENT_TAIL_INITIAL_AFTER = 50
-const SESSION_EVENT_TAIL_MAX_EVENTS = 4096
-const SESSION_EVENT_TAIL_MAX_READS = 128
-
-function sessionQueryCode(error) {
-  return typeof error?.code === 'string' ? error.code : undefined
-}
-
-/**
- * Read raw Session events strictly after one known committed seq through the
- * Host-owned bounded `sessionQuery.readEvent()` window contract.
- *
- * The reader adapts to deployments that lower SessionQuery's configurable
- * `readWindowMax`, never materializes the full Session log, and caps both
- * events and Host reads. Missing capability is explicit. Operational failures
- * from an advertised capability propagate to the caller; a cap is reported as
- * `truncated` so routing can fail safe without a synchronous-history fallback.
- */
-export function createSessionEventTailReader(ctx) {
-  let afterHint = SESSION_EVENT_TAIL_INITIAL_AFTER
-
-  const readWindow = async (query, sessionId, seq) => {
-    let after = afterHint
-    while (true) {
-      try {
-        const request = after > 0 ? { sessionId, seq, after } : { sessionId, seq }
-        const window = await query.readEvent(request)
-        afterHint = after
-        return { window, after }
-      } catch (error) {
-        if (sessionQueryCode(error) !== 'SESSION_QUERY_INVALID_WINDOW' || after <= 0) throw error
-        after = after <= 1 ? 0 : Math.floor(after / 2)
-      }
-    }
-  }
-
-  return async function readSessionEventTail(session, anchorSeq, options = {}) {
-    const sessionId = session?.id
-    if (sessionId === undefined || sessionId === null) return { supported: false }
-    if (!Number.isSafeInteger(anchorSeq) || anchorSeq < 0 || Object.is(anchorSeq, -0)) {
-      throw new TypeError(`session tail anchor seq must be a non-negative safe integer, got ${String(anchorSeq)}`)
-    }
-    const query = sessionQueryOf(ctx)
-    if (!query || typeof query.readEvent !== 'function') return { supported: false }
-
-    const collect = options?.collect !== false
-    const events = []
-    let capturedThroughSeq = anchorSeq
-    let cursor = anchorSeq
-    let inspected = 0
-    let reads = 0
-
-    while (reads < SESSION_EVENT_TAIL_MAX_READS) {
-      let result
-      try {
-        result = await readWindow(query, sessionId, cursor)
-      } catch (error) {
-        if (sessionQueryCode(error) === 'SESSION_QUERY_EVENT_NOT_FOUND' && cursor > anchorSeq) {
-          return { supported: true, events, capturedThroughSeq, truncated: false }
-        }
-        throw error
-      }
-      reads += 1
-
-      const window = result.window
-      const target = window?.target
-      if (!target || typeof target !== 'object' || target.seq !== cursor) {
-        throw new Error(`sessionQuery.readEvent returned an invalid target for seq ${cursor}`)
-      }
-      if (!Array.isArray(window.events) || window.events.length === 0) {
-        throw new Error(`sessionQuery.readEvent returned no event window for seq ${cursor}`)
-      }
-      const windowEvents = window.events
-      let expectedSeq = cursor
-      let endSeq = cursor
-      for (const event of windowEvents) {
-        const seq = event?.seq
-        if (!Number.isSafeInteger(seq) || seq !== expectedSeq) {
-          throw new Error(
-            `sessionQuery.readEvent returned non-contiguous seq ${String(seq)}; expected ${expectedSeq}`,
-          )
-        }
-        expectedSeq += 1
-        endSeq = seq
-        if (seq <= capturedThroughSeq) continue
-        capturedThroughSeq = seq
-        inspected += 1
-        if (collect) events.push(event)
-        if (inspected >= SESSION_EVENT_TAIL_MAX_EVENTS) {
-          return { supported: true, events, capturedThroughSeq, truncated: true }
-        }
-      }
-      if (Number.isSafeInteger(window?.endSeq) && window.endSeq !== endSeq) {
-        throw new Error(
-          `sessionQuery.readEvent returned endSeq ${String(window.endSeq)} for window ending at ${endSeq}`,
-        )
-      }
-
-      if (result.after > 0) {
-        if (endSeq <= cursor || windowEvents.length < result.after + 1) {
-          return { supported: true, events, capturedThroughSeq: Math.max(capturedThroughSeq, endSeq), truncated: false }
-        }
-        cursor = endSeq
-        continue
-      }
-
-      // `readWindowMax: 0` is a valid Host configuration. Walk exact seqs and
-      // use the typed EVENT_NOT_FOUND result as the logical tail sentinel.
-      cursor += 1
-    }
-
-    return { supported: true, events, capturedThroughSeq, truncated: true }
-  }
-}
-
-
-/**
- * Build the asynchronous Session-log reader used by cold attachment recovery
- * and batched surface repair. Prefer SessionQuery's observation lease when it
- * exists: one exact live cut materializes at most one immutable event snapshot,
- * rather than cloning the whole live corpus once per requested event (#524).
- * Hosts without that capability retain the released readSession() contract.
- */
-export function createSessionLogReader(ctx) {
-  return async function readSessionLog(session) {
-    const sessionId = session?.id
-    if (sessionId === undefined || sessionId === null) return { supported: false }
-    const query = sessionQueryOf(ctx)
-    if (!query) return { supported: false }
-
-    if (typeof query.observeSession === 'function') {
-      let observation
-      try {
-        observation = await query.observeSession(sessionId, { projectionMode: 'none' })
-        if (!observation || !Array.isArray(observation.events)) {
-          throw new Error('sessionQuery.observeSession returned no event log')
-        }
-        const observedId = observation.header?.id
-        if (observedId !== undefined && observedId !== sessionId) {
-          throw new Error(
-            `sessionQuery.observeSession returned session ${String(observedId)} for requested ${String(sessionId)}`,
-          )
-        }
-        return { supported: true, events: observation.events }
-      } finally {
-        const dispose = observation?.[Symbol.dispose]
-        if (typeof dispose === 'function') dispose.call(observation)
-      }
-    }
-
-    if (typeof query.readSession !== 'function') return { supported: false }
-    const snapshot = await query.readSession(sessionId)
-    if (!snapshot || !Array.isArray(snapshot.events)) {
-      throw new Error('sessionQuery.readSession returned no event log')
-    }
-    const observedId = snapshot.session?.id
-    if (observedId !== undefined && observedId !== sessionId) {
-      throw new Error(
-        `sessionQuery.readSession returned session ${String(observedId)} for requested ${String(sessionId)}`,
-      )
-    }
-    return { supported: true, events: snapshot.events }
-  }
-}
+export {
+  createSessionEventReader,
+  createSessionEventTailReader,
+  createSessionLogReader,
+} from './session-query-readers.js'
 
 function attachmentStoreOf(ctx) {
   if (!ctx || typeof ctx !== 'object') return undefined
+  // attachments is an optional capability at this boundary. Context#get keeps
+  // the probe non-owning; lifecycle ownership is handled separately by inject.
   try {
-    if (typeof ctx.get === 'function') {
-      const store = ctx.get('attachments')
-      if (store && typeof store === 'object') return store
-    }
-  } catch {
-    // A detached/partial test context may not expose the service yet.
-  }
-  try {
-    const store = ctx.attachments
+    if (typeof ctx.get !== 'function') return undefined
+    const store = ctx.get('attachments')
     return store && typeof store === 'object' ? store : undefined
   } catch {
     return undefined
@@ -564,14 +351,20 @@ export function installSettingsSectionCompat(ctx, namespace, Config, entryConfig
     hooks.setSource(() => scope.get())
     hooks.onChange()
     const disposeWatch = scope.watch(() => hooks.onChange())
-    sctx.effect(
-      () => () => {
-        if (typeof disposeWatch === 'function') disposeWatch()
-        hooks.setSource(() => entryConfig)
-        hooks.onChange()
-      },
-      'vision-router: host settings compatibility source',
-    )
+    const restore = () => {
+      if (typeof disposeWatch === 'function') disposeWatch()
+      hooks.setSource(() => entryConfig)
+      hooks.onChange()
+    }
+    try {
+      sctx.effect(
+        () => restore,
+        'vision-router: host settings compatibility source',
+      )
+    } catch (error) {
+      restore()
+      throw error
+    }
   })
 }
 
@@ -585,6 +378,9 @@ export function installHostSettingsCompatibility(ctx, entryConfig, options = {})
   const install = options.installSettingsSection ?? installSettingsSectionCompat
   const ns = options.namespace
   const Config = options.Config
+  if (typeof ns !== 'string' || ns.trim() === '') {
+    throw new TypeError('vision-router: host settings compatibility requires namespace')
+  }
   if (Config === undefined) {
     throw new TypeError('vision-router: host settings compatibility requires Config')
   }

package/lib/dsh-host-capabilities.js

@@ -2,18 +2,12 @@ const UNKNOWN = 'unknown'
 
 function serviceOf(ctx, name) {
   if (!ctx || (typeof ctx !== 'object' && typeof ctx !== 'function')) return undefined
+  if (typeof ctx.get !== 'function') return undefined
   try {
-    if (typeof ctx.get === 'function') {
-      const service = ctx.get(name)
-      if (service !== undefined && service !== null) return service
-    }
-  } catch {
-    // Capability diagnostics are advisory and must not break plugin startup.
-  }
-  try {
-    const service = ctx[name]
+    const service = ctx.get(name)
     return service === undefined || service === null ? undefined : service
   } catch {
+    // Capability diagnostics are advisory and must not break plugin startup.
     return undefined
   }
 }

package/lib/dsh-settings-017-compat.js

@@ -6,8 +6,10 @@ const REVISION_REGISTRY_KEY = Symbol.for('dsh-vision-router.settings-017-revisio
 
 function revisionRegistry() {
   let registry = globalThis[REVISION_REGISTRY_KEY]
-  if (!(registry instanceof Map)) {
-    registry = new Map()
+  if (!(registry instanceof WeakMap)) {
+    // The pre-R11 registry was a process-global Map keyed only by document
+    // paths. Replace it rather than retaining stale profile keys forever.
+    registry = new WeakMap()
     Object.defineProperty(globalThis, REVISION_REGISTRY_KEY, {
       value: registry,
       configurable: true,
@@ -94,13 +96,20 @@ function revisionKey(editor, namespace) {
  * resets every browser connection, which forces a fresh descriptor read.
  */
 function revisionFor(editor, namespace, current, inherited) {
+  const identity = serviceIdentity(editor)
+  if (!identity || (typeof identity !== 'object' && typeof identity !== 'function')) return 0
+  const registry = revisionRegistry()
+  let states = registry.get(identity)
+  if (!(states instanceof Map)) {
+    states = new Map()
+    registry.set(identity, states)
+  }
   const key = revisionKey(editor, namespace)
   const valueFingerprint = fingerprint({ current, inherited })
-  const registry = revisionRegistry()
-  const previous = registry.get(key)
+  const previous = states.get(key)
   if (!previous) {
     const state = { fingerprint: valueFingerprint, revision: 0 }
-    registry.set(key, state)
+    states.set(key, state)
     return state.revision
   }
   if (previous.fingerprint !== valueFingerprint) {
@@ -123,12 +132,10 @@ function serviceIdentity(value) {
 }
 
 function serviceOf(ctx, name) {
+  if (!ctx || (typeof ctx !== 'object' && typeof ctx !== 'function')) return undefined
+  if (typeof ctx.get !== 'function') return undefined
   try {
-    const value = typeof ctx?.get === 'function' ? ctx.get(name) : undefined
-    if (value !== undefined && value !== null) return value
-  } catch {}
-  try {
-    const value = ctx?.[name]
+    const value = ctx.get(name)
     return value === undefined || value === null ? undefined : value
   } catch {
     return undefined

package/lib/file-logger.js

@@ -504,13 +504,18 @@ export function installVisionRouterFileLogging(ctx, options = {}) {
     // next apply would reuse an object whose routes are no longer mounted.
     try {
       ctx.effect?.(
-        () => () => {
+        () => async () => {
           if (installs.get(ctx) === installed) installs.delete(ctx)
+          await sink.flush()
         },
         'vision-router: diagnostics file logger lifecycle',
       )
-    } catch {
-      // Cache expiry is a hardening aid; logging itself must stay non-fatal.
+    } catch (error) {
+      // Filesystem diagnostics may degrade, but lifecycle ownership may not.
+      // Continuing here would publish routes and a file-writing logger after
+      // Cordis already rejected this plugin generation.
+      if (installs.get(ctx) === installed) installs.delete(ctx)
+      throw error
     }
   }
 

package/lib/grounding-coordinate-runtime.js

@@ -34,11 +34,10 @@ function artifactsDirOf(config) {
 
 function contextService(ctx, name) {
   try {
-    if (typeof ctx?.get === 'function') return ctx.get(name)
+    return typeof ctx?.get === 'function' ? ctx.get(name) : undefined
   } catch {
     return undefined
   }
-  return ctx?.[name]
 }
 
 async function readSourceBytes(ctx, core, sessionVisionIndex, exec, image) {