dsh-vision-router 2.2.1 → 2.2.2

package/docs/releases/v2.2.2.md

@@ -0,0 +1,21 @@
+# v2.2.2
+
+DSH Vision Router 2.2.2 is an urgent browser compatibility hotfix for DSH 0.1.7-rc.1.
+
+## Highlights
+
+- Fixes Vision Router being left pending at Web startup on DSH 0.1.7-rc.1 with `waiting for service: settingsScope`.
+- Adapts the legacy `ctx.settingsScope.bind({ namespace })` consumer face to DSH 0.1.7's official `configForms.get(namespace)` service without hard-requiring either service generation.
+- Keeps the real legacy `settingsScope` path preferred on older supported Hosts, so the fix does not raise the existing Host floor.
+- Preserves the existing local settings permission and remote-risk wrappers over both settings backends.
+- Adds loader-level regression coverage for both DSH 0.1.7 `configForms` and legacy `settingsScope` Hosts.
+
+## Validation
+
+- Node 22 and Node 24 CI passed on the compatibility fix.
+- Architecture Closure, P1 Routing Parity, P3 Compatibility Convergence, DSH Contract, exact-source, browser smoke, adversarial compatibility, fuzz, dependency review, fetch composition, and native multimodal cold-resume gates passed on PR #538.
+- The public minimum DSH Host remains `0.1.0-rc.8`.
+
+## Upgrade
+
+Users affected by the DSH 0.1.7 startup failure should upgrade Vision Router to 2.2.2. No settings migration is required.

package/lib/client.js

@@ -865,6 +865,57 @@ window.__ModuleLoader__.load({
           : stored && settingsValueEqual(item.key, user[item.key], item.run.value)
         return { ok, stored }
       }
+      const finalize = () => {
+        const landed = failures.length === 0
+        const nextDrafts = landedFields.length === 0 ? drafts : { ...drafts }
+        for (const field of landedFields) delete nextDrafts[field]
+        return {
+          landed,
+          failed: !landed,
+          landedFields,
+          nextDrafts,
+          failures,
+        }
+      }
+      const mismatchFailure = (item, check) => ({
+        field: item.key,
+        operation: item.run.clear ? 'unset' : 'set',
+        reason: 'readback-mismatch',
+        detail: item.run.clear
+          ? 'field remained present in the user layer'
+          : check.stored
+            ? 'stored user-layer value differs from the requested value'
+            : 'field is absent from the user layer',
+      })
+      const batchWrite = scope && typeof scope.__visionRouterWritePlan === 'function'
+        ? scope.__visionRouterWritePlan.bind(scope)
+        : undefined
+      // DSH 0.1.7's local compatibility transport is ConfigEditor-backed.
+      // ConfigEditor reloads the plugin after a successful edit, so serial POSTs
+      // from one Save can cross generations and strand the second mutation.
+      // Its private scope seam commits the entire UI plan in one atomic edit.
+      if (plan.length > 1 && batchWrite) {
+        try {
+          await batchWrite(plan)
+        } catch (error) {
+          for (const item of plan) {
+            failures.push({
+              field: item.key,
+              operation: item.run.clear ? 'unset' : 'set',
+              reason: error && error.code === 'settings-conflict' ? 'settings-conflict' : 'write-error',
+              detail: settingsSaveErrorMessage(error),
+            })
+          }
+          return finalize()
+        }
+        for (const item of plan) {
+          const check = inspectReadback(item)
+          if (check.error) failures.push(check.error)
+          else if (check.ok) landedFields.push(item.key)
+          else failures.push(mismatchFailure(item, check))
+        }
+        return finalize()
+      }
       const writeItem = async (item) => {
         if (item.run.clear) await scope.unset(item.key)
         else await scope.set(item.key, item.run.value)
@@ -913,16 +964,7 @@ window.__ModuleLoader__.load({
             }
           }
 
-          terminalFailure = {
-            field: item.key,
-            operation,
-            reason: 'readback-mismatch',
-            detail: item.run.clear
-              ? 'field remained present in the user layer'
-              : check.stored
-                ? 'stored user-layer value differs from the requested value'
-                : 'field is absent from the user layer',
-          }
+          terminalFailure = mismatchFailure(item, check)
         }
         if (success) landedFields.push(item.key)
         else failures.push(terminalFailure ?? {
@@ -932,16 +974,7 @@ window.__ModuleLoader__.load({
           detail: 'write did not become visible in the user layer',
         })
       }
-      const landed = failures.length === 0
-      const nextDrafts = landedFields.length === 0 ? drafts : { ...drafts }
-      for (const field of landedFields) delete nextDrafts[field]
-      return {
-        landed,
-        failed: !landed,
-        landedFields,
-        nextDrafts,
-        failures,
-      }
+      return finalize()
     }
 
     const REMOTE_SETTINGS_CHANNEL = '/vision-router-settings'
@@ -1124,16 +1157,23 @@ window.__ModuleLoader__.load({
     }
 
     function shouldUseRemoteSettings(getConnection, locationLike) {
+      // Browser page authority is the security boundary. DSH 0.1.7 can report
+      // Connection.isLoopback=false even for a real 127.0.0.1 page, so letting
+      // that hint win would incorrectly force the local Settings page onto the
+      // trusted-host RPC path. Conversely, a non-loopback browser URL must not
+      // become local merely because a stale Connection says true.
+      const location = locationLike ?? (typeof window !== 'undefined' ? window.location : undefined)
+      const hostname = typeof location?.hostname === 'string' ? location.hostname.toLowerCase().replace(/^\[|\]$/g, '') : ''
+      if (hostname !== '') {
+        if (hostname === 'localhost' || hostname.endsWith('.localhost') || hostname === '::1') return false
+        if (/^127(?:\.\d{1,3}){3}$/.test(hostname)) return false
+        return true
+      }
       try {
         const connection = typeof getConnection === 'function' ? getConnection() : undefined
         if (connection && typeof connection.isLoopback === 'boolean') return connection.isLoopback === false
-      } catch { /* fall through to page authority */ }
-      const location = locationLike ?? (typeof window !== 'undefined' ? window.location : undefined)
-      const hostname = typeof location?.hostname === 'string' ? location.hostname.toLowerCase().replace(/^\[|\]$/g, '') : ''
-      if (hostname === '') return false
-      if (hostname === 'localhost' || hostname.endsWith('.localhost') || hostname === '::1') return false
-      if (/^127(?:\.\d{1,3}){3}$/.test(hostname)) return false
-      return true
+      } catch { /* no page authority and no usable Connection: stay local-safe */ }
+      return false
     }
 
     function reportSettingsSaveFailures(failures) {

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

@@ -0,0 +1,416 @@
+const SETTINGS_NS = 'vision-router'
+export const LOCAL_SETTINGS_PATH = '/_dsh/vision-router/local-settings'
+export const DSH_017_SETTINGS_COMPAT_MARK = '__visionRouterDsh017ConfigEditorCompat'
+const BODY_LIMIT_BYTES = 256 * 1024
+const REVISION_REGISTRY_KEY = Symbol.for('dsh-vision-router.settings-017-revisions')
+
+function revisionRegistry() {
+  let registry = globalThis[REVISION_REGISTRY_KEY]
+  if (!(registry instanceof Map)) {
+    registry = new Map()
+    Object.defineProperty(globalThis, REVISION_REGISTRY_KEY, {
+      value: registry,
+      configurable: true,
+    })
+  }
+  return registry
+}
+
+function objectLike(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function plainObject(value) {
+  if (!objectLike(value)) return false
+  const proto = Object.getPrototypeOf(value)
+  return proto === Object.prototype || proto === null
+}
+
+function clone(value) {
+  return value === undefined ? undefined : structuredClone(value)
+}
+
+function mergeResolved(base, overlay) {
+  if (!plainObject(base) || !plainObject(overlay)) return clone(overlay)
+  const next = clone(base)
+  for (const [key, value] of Object.entries(overlay)) {
+    next[key] = plainObject(value) && plainObject(next[key])
+      ? mergeResolved(next[key], value)
+      : clone(value)
+  }
+  return next
+}
+
+function jsonEqual(left, right) {
+  if (left === right) return true
+  if (Array.isArray(left) || Array.isArray(right)) {
+    return Array.isArray(left) && Array.isArray(right)
+      && left.length === right.length
+      && left.every((value, index) => jsonEqual(value, right[index]))
+  }
+  if (!plainObject(left) || !plainObject(right)) return false
+  const leftKeys = Object.keys(left)
+  const rightKeys = Object.keys(right)
+  return leftKeys.length === rightKeys.length
+    && leftKeys.every((key) => Object.hasOwn(right, key) && jsonEqual(left[key], right[key]))
+}
+
+function logicalUserLayer(current, inherited) {
+  const user = Object.create(null)
+  const keys = new Set([
+    ...Object.keys(objectLike(current) ? current : {}),
+    ...Object.keys(objectLike(inherited) ? inherited : {}),
+  ])
+  for (const key of keys) {
+    const currentHas = objectLike(current) && Object.hasOwn(current, key)
+    const inheritedHas = objectLike(inherited) && Object.hasOwn(inherited, key)
+    if (currentHas === inheritedHas && (!currentHas || jsonEqual(current[key], inherited[key]))) continue
+    if (currentHas) user[key] = clone(current[key])
+  }
+  return user
+}
+
+function stableValue(value) {
+  if (Array.isArray(value)) return value.map(stableValue)
+  if (!plainObject(value)) return value
+  return Object.fromEntries(Object.keys(value).sort().map((key) => [key, stableValue(value[key])]))
+}
+
+function fingerprint(value) {
+  return JSON.stringify(stableValue(value))
+}
+
+function revisionKey(editor, namespace) {
+  let documentPath
+  try { documentPath = editor?.documentPath } catch {}
+  return `${String(documentPath ?? 'process-local-profile')}\u0000${namespace}`
+}
+
+/**
+ * Ordinary Config writes reload DVR, so a plugin-instance counter is unsafe.
+ * Keep one process-level monotonic counter per profile document + namespace.
+ * The registry survives DVR HMR and advances whenever the effective persisted
+ * layers observed at the compatibility boundary change. A process restart also
+ * resets every browser connection, which forces a fresh descriptor read.
+ */
+function revisionFor(editor, namespace, current, inherited) {
+  const key = revisionKey(editor, namespace)
+  const valueFingerprint = fingerprint({ current, inherited })
+  const registry = revisionRegistry()
+  const previous = registry.get(key)
+  if (!previous) {
+    const state = { fingerprint: valueFingerprint, revision: 0 }
+    registry.set(key, state)
+    return state.revision
+  }
+  if (previous.fingerprint !== valueFingerprint) {
+    previous.fingerprint = valueFingerprint
+    previous.revision += 1
+  }
+  return previous.revision
+}
+
+function serviceOf(ctx, name) {
+  try {
+    const value = typeof ctx?.get === 'function' ? ctx.get(name) : undefined
+    if (value !== undefined && value !== null) return value
+  } catch {}
+  try {
+    const value = ctx?.[name]
+    return value === undefined || value === null ? undefined : value
+  } catch {
+    return undefined
+  }
+}
+
+function configEditorRow(editor, namespace) {
+  const rows = typeof editor?.configuration === 'function' ? editor.configuration() : []
+  if (!Array.isArray(rows)) return undefined
+  return rows.find((row) => row?.entry?.options?.id === namespace)
+}
+
+function settingsConflict(expected, actual) {
+  const error = new Error(`Vision Router settings changed before this write landed (expected ${expected}, actual ${actual})`)
+  error.code = 'SETTINGS_CONFLICT'
+  error.expected = expected
+  error.actual = actual
+  return error
+}
+
+function admissionError(message) {
+  const error = new Error(message)
+  error.code = 'SETTINGS_INVALID_MUTATION'
+  return error
+}
+
+function validateOperations(ops) {
+  if (!Array.isArray(ops) || ops.length === 0) throw admissionError('settings operations must be a non-empty array')
+  return ops.map((op) => {
+    if (!objectLike(op) || (op.op !== 'set' && op.op !== 'unset')) {
+      throw admissionError('settings operation must be set or unset')
+    }
+    if (!Array.isArray(op.path) || op.path.length !== 1 || typeof op.path[0] !== 'string' || op.path[0] === '') {
+      throw admissionError('Vision Router settings compatibility accepts one top-level field per operation')
+    }
+    const key = op.path[0]
+    if (key === '__proto__' || key === 'prototype' || key === 'constructor') {
+      throw admissionError('unsafe settings field name')
+    }
+    return op.op === 'set'
+      ? { op: 'set', path: [key], value: clone(op.value) }
+      : { op: 'unset', path: [key] }
+  })
+}
+
+function applyOperations(current, inherited, ops) {
+  const next = clone(objectLike(current) ? current : {})
+  for (const op of ops) {
+    const key = op.path[0]
+    if (op.op === 'set') {
+      next[key] = clone(op.value)
+      continue
+    }
+    if (objectLike(inherited) && Object.hasOwn(inherited, key)) next[key] = clone(inherited[key])
+    else delete next[key]
+  }
+  return next
+}
+
+function createConfigEditorSettingsFacade(editor, entryConfig, namespace) {
+  const listeners = new Set()
+
+  function state() {
+    const row = configEditorRow(editor, namespace)
+    if (!row) return undefined
+    const current = objectLike(row.entry?.options?.config) ? row.entry.options.config : {}
+    const inherited = objectLike(row.inherited) ? row.inherited : {}
+    const base = mergeResolved(entryConfig, inherited)
+    const value = mergeResolved(entryConfig, current)
+    return {
+      row,
+      descriptor: {
+        ns: namespace,
+        value,
+        base,
+        user: logicalUserLayer(current, inherited),
+        revision: revisionFor(editor, namespace, current, inherited),
+        applies: true,
+      },
+    }
+  }
+
+  function notify(value) {
+    for (const listener of [...listeners]) {
+      try { listener(value, undefined) } catch {}
+    }
+  }
+
+  const scope = {
+    get() {
+      return state()?.descriptor.value ?? entryConfig
+    },
+    watch(listener) {
+      if (typeof listener !== 'function') return () => {}
+      listeners.add(listener)
+      return () => listeners.delete(listener)
+    },
+  }
+
+  return {
+    [DSH_017_SETTINGS_COMPAT_MARK]: true,
+    get writable() {
+      return state() !== undefined
+    },
+    get(namespaceName) {
+      return namespaceName === namespace ? scope.get() : undefined
+    },
+    register(namespaceName) {
+      if (namespaceName !== namespace) {
+        throw new Error(`vision-router: unexpected settings namespace ${String(namespaceName)}`)
+      }
+      return scope
+    },
+    describe() {
+      const current = state()
+      return current ? [clone(current.descriptor)] : []
+    },
+    async mutate(namespaceName, operations, expectedRevision) {
+      if (namespaceName !== namespace) throw new Error(`No configurable plugin entry ${JSON.stringify(namespaceName)}`)
+      const before = state()
+      if (!before) throw new Error(`No configurable plugin entry ${JSON.stringify(namespace)}`)
+      if (!Number.isSafeInteger(expectedRevision) || expectedRevision < 0) {
+        throw admissionError('expectedRevision must be a non-negative safe integer')
+      }
+      if (expectedRevision !== before.descriptor.revision) {
+        throw settingsConflict(expectedRevision, before.descriptor.revision)
+      }
+      const ops = validateOperations(operations)
+      const entry = before.row.entry
+      await editor.edit(entry, (current, inherited) => applyOperations(current, inherited, ops))
+      const after = state()
+      if (!after) throw new Error('Vision Router configuration entry disappeared after the write')
+      notify(after.descriptor.value)
+      return clone(after.descriptor)
+    },
+  }
+}
+
+/**
+ * DSH 0.1.7 services may mount after DVR's apply() starts. Capture ConfigEditor
+ * through its own lifecycle injection and resolve the settings generation when
+ * each consumer actually accesses it. This avoids both startup-order races and
+ * undeclared child-context service reads.
+ */
+function contextWithLazySettingsCompatibility(ctx, entryConfig, namespace) {
+  const wrappers = new WeakMap()
+  const facades = new WeakMap()
+  let injectedEditor
+
+  try {
+    if (typeof ctx?.inject === 'function') {
+      ctx.inject(['configEditor'], (editorCtx) => {
+        injectedEditor = serviceOf(editorCtx, 'configEditor')
+      })
+    }
+  } catch {
+    // Older Hosts may not expose ConfigEditor; their native SettingsProvider stays authoritative.
+  }
+
+  function compatibleSettings(target) {
+    const settings = serviceOf(target, 'settings') ?? serviceOf(ctx, 'settings')
+    if (!settings || typeof settings.register === 'function') return settings
+    const editor = serviceOf(target, 'configEditor') ?? injectedEditor ?? serviceOf(ctx, 'configEditor')
+    if (typeof settings.describe !== 'function'
+        || !editor || typeof editor.edit !== 'function' || typeof editor.configuration !== 'function') {
+      return settings
+    }
+    let facade = facades.get(editor)
+    if (!facade) {
+      facade = createConfigEditorSettingsFacade(editor, entryConfig, namespace)
+      facades.set(editor, facade)
+    }
+    return facade
+  }
+
+  function wrap(target) {
+    if (!target || typeof target !== 'object') return target
+    const held = wrappers.get(target)
+    if (held) return held
+    const wrapped = new Proxy(target, {
+      get(object, property) {
+        if (property === 'settings') return compatibleSettings(object)
+        if (property === 'get') {
+          const get = Reflect.get(object, property, object)
+          if (typeof get !== 'function') return get
+          return (name, ...rest) => name === 'settings'
+            ? compatibleSettings(object)
+            : get.call(object, name, ...rest)
+        }
+        if (property === 'inject') {
+          const inject = Reflect.get(object, property, object)
+          if (typeof inject !== 'function') return inject
+          return (dependencies, callback, ...rest) => inject.call(
+            object,
+            dependencies,
+            typeof callback === 'function' && Array.isArray(dependencies) && dependencies.includes('settings')
+              ? (child) => callback(wrap(child))
+              : callback,
+            ...rest,
+          )
+        }
+        const value = Reflect.get(object, property, object)
+        return typeof value === 'function' ? value.bind(object) : value
+      },
+    })
+    wrappers.set(target, wrapped)
+    return wrapped
+  }
+
+  return wrap(ctx)
+}
+
+/**
+ * DSH 0.1.7 removes the legacy SettingsProvider.register() namespace API and
+ * makes ordinary plugin configuration profile-owned through ConfigEditor.
+ * Preserve DVR's mature settings consumers behind the old semantic face while
+ * leaving older Hosts on their native SettingsProvider whenever it is present.
+ */
+export function installDsh017SettingsCompatibility(ctx, entryConfig = {}, options = {}) {
+  const namespace = typeof options.namespace === 'string' && options.namespace !== '' ? options.namespace : SETTINGS_NS
+  return contextWithLazySettingsCompatibility(ctx, entryConfig, namespace)
+}
+
+function sendJson(res, status, body) {
+  res.writeHead(status, {
+    'content-type': 'application/json; charset=utf-8',
+    'cache-control': 'no-store',
+  })
+  res.end(JSON.stringify(body))
+}
+
+async function readJson(req) {
+  let size = 0
+  const chunks = []
+  for await (const chunk of req) {
+    const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)
+    size += bytes.length
+    if (size > BODY_LIMIT_BYTES) throw Object.assign(new Error('request body too large'), { statusCode: 413 })
+    chunks.push(bytes)
+  }
+  if (chunks.length === 0) return {}
+  return JSON.parse(Buffer.concat(chunks).toString('utf8'))
+}
+
+function namespaceDescriptor(settings) {
+  const descriptors = settings.describe({ redactSecrets: true })
+  return Array.isArray(descriptors) ? descriptors.find((entry) => entry?.ns === SETTINGS_NS) : undefined
+}
+
+/** Local-only transport for the 0.1.7 browser, which no longer exposes settingsScope. */
+export function installDsh017LocalSettingsTransport(ctx) {
+  if (!ctx || typeof ctx.inject !== 'function') return
+  ctx.inject(['settings', 'webServer'], (webCtx) => {
+    if (webCtx.settings?.[DSH_017_SETTINGS_COMPAT_MARK] !== true) return
+    if (typeof webCtx.settings.describe !== 'function' || typeof webCtx.settings.mutate !== 'function') return
+    webCtx.effect(
+      () => webCtx.webServer.register({
+        kind: 'exact',
+        path: LOCAL_SETTINGS_PATH,
+        async handler(req, res) {
+          if (req.method === 'GET') {
+            const descriptor = namespaceDescriptor(webCtx.settings)
+            if (!descriptor) {
+              sendJson(res, 404, { ok: false, error: { code: 'settings-unavailable', message: 'Vision Router settings are unavailable' } })
+              return
+            }
+            sendJson(res, 200, { ok: true, value: { ...descriptor, writable: webCtx.settings.writable === true } })
+            return
+          }
+          if (req.method !== 'POST') {
+            res.setHeader('Allow', 'GET, POST')
+            sendJson(res, 405, { ok: false, error: { code: 'method-not-allowed', message: 'method not allowed' } })
+            return
+          }
+          try {
+            const payload = await readJson(req)
+            await webCtx.settings.mutate(SETTINGS_NS, payload?.ops, payload?.expectedRevision)
+            const descriptor = namespaceDescriptor(webCtx.settings)
+            if (!descriptor) throw new Error('Vision Router settings disappeared after the write')
+            sendJson(res, 200, { ok: true, value: { ...descriptor, writable: webCtx.settings.writable === true } })
+          } catch (error) {
+            const conflict = error?.code === 'SETTINGS_CONFLICT'
+            sendJson(res, error?.statusCode ?? (conflict ? 409 : 400), {
+              ok: false,
+              error: {
+                code: conflict ? 'settings-conflict' : 'settings-rejected',
+                message: error?.message ?? String(error),
+                ...(conflict ? { details: { expected: error.expected, actual: error.actual } } : {}),
+              },
+            })
+          }
+        },
+      }),
+      'vision-router: DSH 0.1.7 local settings transport',
+    )
+  })
+}

package/lib/public-entry.js

@@ -7,6 +7,10 @@ import {
   installVisionProviderTransport,
 } from './vision-provider-transport.js'
 import { installLegacyGlobalProxyBoundary } from './legacy-global-proxy-boundary.js'
+import { installDsh017SettingsCompatibility } from './dsh-settings-017-compat.js'
+import { installDsh017RootLocalSettingsTransport } from './web/dsh-settings-017-root-transport.js'
+import { installSettings017ClientCompatibility } from './settings-client-017-compat.js'
+import { installVisionRouterMessageSourceBoundary } from './session-message-source-compat.js'
 
 export * from '../entry.js'
 
@@ -33,7 +37,23 @@ function liveVisionConfig(ctx, fallback) {
  * settings therefore leave DSH/Host as the sole network authority.
  */
 export function apply(ctx, config = {}) {
-  const hardening = createVisionToggleRootHardening(ctx, config)
+  // DSH 0.1.7 replaces SettingsProvider.register() with profile-owned
+  // ConfigEditor writes for ordinary fields. Feature-detect that exact contract
+  // and present DVR's mature settings face without changing older Hosts.
+  const settingsCtx = installDsh017SettingsCompatibility(ctx, config, {
+    namespace: 'vision-router',
+    Config: base.Config,
+  })
+  // The 0.1.7 browser no longer exposes settingsScope. Keep the server route on
+  // the application root so ConfigEditor reconciliation cannot dispose an
+  // in-flight Settings POST, while each DVR generation supplies the live facade.
+  installDsh017RootLocalSettingsTransport(settingsCtx)
+  installSettings017ClientCompatibility(settingsCtx)
+  // Session V3 and V4 disagree on plugin message attribution. Normalize only
+  // DVR-authored contexts at the final hook-publication seam using the Session's
+  // own durable header version, never a DSH package-version guess.
+  const sessionSourceCtx = installVisionRouterMessageSourceBoundary(settingsCtx)
+  const hardening = createVisionToggleRootHardening(sessionSourceCtx, config)
   const runtimeCtx = contextWithVisionRoutingTopologyRefresh(hardening.ctx)
   const transport = createVisionProviderTransport({
     ctx: hardening.ctx,

package/lib/session-message-source-compat.js

@@ -0,0 +1,92 @@
+const LEGACY_SOURCE = Object.freeze({ kind: 'plugin', plugin: 'dsh-vision-router' })
+const PRODUCER_SOURCE = Object.freeze({ kind: 'plugin:dsh-vision-router' })
+
+function sourceKindForSession(session) {
+  const version = Number(session?.header?.version)
+  return Number.isInteger(version) && version >= 4 ? PRODUCER_SOURCE : LEGACY_SOURCE
+}
+
+function isVisionRouterSource(source) {
+  return !!source && typeof source === 'object' && !Array.isArray(source) && (
+    (source.kind === 'plugin' && source.plugin === 'dsh-vision-router') ||
+    source.kind === 'plugin:dsh-vision-router'
+  )
+}
+
+/** Return the canonical DVR message source for one live Session format. */
+export function visionRouterMessageSource(session) {
+  return { ...sourceKindForSession(session) }
+}
+
+/** Normalize one DVR-authored message without touching user/model/tool sources. */
+export function normalizeVisionRouterMessageSource(message, session) {
+  if (!message || typeof message !== 'object' || Array.isArray(message)) return message
+  if (!isVisionRouterSource(message.source)) return message
+  const source = sourceKindForSession(session)
+  if (message.source.kind === source.kind
+      && (source.kind !== 'plugin' || message.source.plugin === source.plugin)
+      && Object.keys(message.source).length === Object.keys(source).length) {
+    return message
+  }
+  return { ...message, source: { ...source } }
+}
+
+function normalizeMessageList(list, session) {
+  if (!Array.isArray(list)) return list
+  let changed = false
+  const next = list.map((message) => {
+    const normalized = normalizeVisionRouterMessageSource(message, session)
+    if (normalized !== message) changed = true
+    return normalized
+  })
+  return changed ? next : list
+}
+
+function normalizePreStepResult(result, payload) {
+  if (!result || typeof result !== 'object' || Array.isArray(result)) return result
+  const messages = normalizeMessageList(result.messages, payload?.agent?.session)
+  return messages === result.messages ? result : { ...result, messages }
+}
+
+function normalizePostExecuteResult(result, exec) {
+  if (!result || typeof result !== 'object' || Array.isArray(result)) return result
+  const additionalContexts = normalizeMessageList(result.additionalContexts, exec?.agent?.session)
+  return additionalContexts === result.additionalContexts ? result : { ...result, additionalContexts }
+}
+
+function normalizeHookResult(event, args, result) {
+  if (event === 'agent/pre-step') return normalizePreStepResult(result, args[0])
+  if (event === 'tools/post-execute') return normalizePostExecuteResult(result, args[0])
+  return result
+}
+
+/**
+ * DSH Session V3 requires the historical {kind:'plugin', plugin:...} source,
+ * while V4 rejects that wrapper in favor of producer-owned source kinds. Keep
+ * every existing DVR message producer unchanged and normalize at the final
+ * hook publication boundary using the Session's own durable header version.
+ */
+export function installVisionRouterMessageSourceBoundary(ctx) {
+  if (!ctx || typeof ctx !== 'object') return ctx
+  return new Proxy(ctx, {
+    get(target, property) {
+      if (property !== 'on') {
+        const value = Reflect.get(target, property, target)
+        return typeof value === 'function' ? value.bind(target) : value
+      }
+      const on = Reflect.get(target, property, target)
+      if (typeof on !== 'function') return on
+      return (event, handler, ...rest) => {
+        if ((event !== 'agent/pre-step' && event !== 'tools/post-execute') || typeof handler !== 'function') {
+          return on.call(target, event, handler, ...rest)
+        }
+        return on.call(target, event, function sourceCompatibleHook(...args) {
+          const output = handler.apply(this, args)
+          return output && typeof output.then === 'function'
+            ? output.then((value) => normalizeHookResult(event, args, value))
+            : normalizeHookResult(event, args, output)
+        }, ...rest)
+      }
+    },
+  })
+}