dsh-vision-router 2.2.0 → 2.2.2

package/lib/session-vision-index.js

@@ -2,6 +2,8 @@ import { currentSessionSurfacePolicy } from './session-surface-policy.js'
 import { sessionSurfaceReplacementIntent } from './session-surface-compat.js'
 import { createSessionVisionStateStore } from './session-vision-state.js'
 
+const MAX_PENDING_REPAIR_EVENTS = 256
+
 function isObject(value) {
   return value !== null && typeof value === 'object'
 }
@@ -39,13 +41,23 @@ function boundedMessage(error) {
   return String(text ?? '').slice(0, 400)
 }
 
+function isReplacementEvent(event) {
+  const op = event?.surfaceOp
+  return !!op && typeof op === 'object' && !Array.isArray(op) && op.op === 'replace'
+}
+
 /**
  * Session visual data-plane index.
  *
  * SessionVisionStateStore remains the bounded storage owner. This object owns
- * target-only durable attachment recovery after bounded-cache eviction,
- * bounded Host-backed tool-result image surface repair and expired structured
- * guard-stop surface repair.
+ * target-only durable attachment recovery, event-feed-backed tool-result image
+ * surface repair and expired structured guard-stop surface repair.
+ *
+ * Supported DSH Hosts expose the post-commit `session/event` feed. Production
+ * surface repair consumes only the exact frozen events observed on that feed;
+ * it never asks SessionQuery to materialize or clone the live Session history.
+ * The older reader path remains only for isolated/partial callers that do not
+ * install the event feed boundary.
  *
  * The index never replaces stateStore.lookupAttachment(). Cache lookup stays
  * synchronous through lookupAttachment(); cold durable recovery is requested
@@ -73,16 +85,20 @@ export function createSessionVisionIndex({
     : undefined
   const toolSurfaceScans = new WeakMap()
   const guardSurfaceScans = new WeakMap()
+  const pendingToolRepairEvents = new WeakMap()
+  const pendingGuardRepairEvents = new WeakMap()
   const unsupportedSurfaceContracts = new WeakSet()
   const repairReadWarnings = new WeakMap()
+  const repairFeedOverflowWarnings = new WeakSet()
+  const repairFeedObserverWarnings = new WeakMap()
   const attachmentRecoveryWarnings = new WeakMap()
+  let surfaceEventFeedActive = false
 
   const recordAttachments = (session, refs) => {
     if (!session || !Array.isArray(refs) || refs.length === 0) return
     store.recordAttachments(session, refs)
   }
 
-
   // Synchronous lookup is cache-only. Projected short handles first warm this
   // cache from current derived messages and must not trigger historical I/O.
   const lookupAttachment = (session, id) => {
@@ -217,13 +233,47 @@ export function createSessionVisionIndex({
     }
 
     // Isolated/partial Hosts that do not expose SessionQuery retain the released
-    // Session-local compatibility path. Supported production Hosts use the
-    // bounded async reader above and never silently fall back after a read error.
+    // Session-local compatibility path. Supported production Hosts install the
+    // event feed and never enter this compatibility reader.
     const events = legacySessionEvents(session)
     if (!events) return { readable: false }
     return { readable: true, event: events[seq] }
   }
 
+  const surfaceRepairSnapshot = async (session, seq) => {
+    if (typeof readSessionLog !== 'function') return undefined
+    let result
+    try {
+      result = await readSessionLog(session)
+    } catch (error) {
+      warnRepairReadFailure(session, seq, error)
+      return { readable: false }
+    }
+    if (result?.supported === true) {
+      if (!Array.isArray(result.events)) {
+        warnRepairReadFailure(session, seq, new Error('Session log reader returned no event log'))
+        return { readable: false }
+      }
+      repairReadWarnings.delete(session)
+      return { readable: true, events: result.events }
+    }
+    if (result?.supported !== false) {
+      warnRepairReadFailure(session, seq, new Error('Session log reader returned an invalid capability result'))
+      return { readable: false }
+    }
+    return undefined
+  }
+
+  const eventFromRepairSnapshot = (session, events, seq) => {
+    const event = events?.[seq]
+    if (!event || typeof event !== 'object' || (event.seq !== undefined && event.seq !== seq)) {
+      warnRepairReadFailure(session, seq, new Error(`Session repair snapshot has no event at seq ${seq}`))
+      return { readable: false }
+    }
+    repairReadWarnings.delete(session)
+    return { readable: true, event }
+  }
+
   const keepToolResultImages = () => {
     const policy = currentSessionSurfacePolicy(
       typeof config === 'function' ? config() : config,
@@ -244,14 +294,165 @@ export function createSessionVisionIndex({
     return undefined
   }
 
+  const cachePendingRepairEvent = (pendingBySession, session, event) => {
+    if (!session || !Number.isSafeInteger(event?.seq) || event.seq < 0 || Object.is(event.seq, -0)) return
+    let pending = pendingBySession.get(session)
+    if (!pending) {
+      pending = new Map()
+      pendingBySession.set(session, pending)
+    }
+    if (!pending.has(event.seq) && pending.size >= MAX_PENDING_REPAIR_EVENTS) {
+      const oldest = pending.keys().next().value
+      if (oldest !== undefined) pending.delete(oldest)
+      if (!repairFeedOverflowWarnings.has(session)) {
+        repairFeedOverflowWarnings.add(session)
+        logger?.warn?.(
+          'vision-router: session surface repair event feed exceeded %s pending events; dropping oldest entry',
+          MAX_PENDING_REPAIR_EVENTS,
+        )
+      }
+    }
+    pending.set(event.seq, event)
+  }
+
+  const planAgainstOneEvent = (event, planner) => {
+    if (!Number.isSafeInteger(event?.seq) || event.seq < 0 || Object.is(event.seq, -0)) return []
+    const events = { [event.seq]: event }
+    return planner(events, [event.seq])
+  }
+
+  const recordSessionEvent = (session, event) => {
+    if (!session || !event || typeof event !== 'object') return
+    try {
+      if (typeof core.collectEventAttachmentRefs === 'function') {
+        const refs = core.collectEventAttachmentRefs([event])
+        if (Array.isArray(refs) && refs.length > 0) recordAttachments(session, refs)
+      }
+
+      // Replacement events are consequences of this repair path and must never
+      // be re-enqueued, otherwise a guard-stop replacement would shadow itself
+      // forever because its stable plugin-owned id is intentionally preserved.
+      if (isReplacementEvent(event)) return
+
+      if (event.type === 'tool/result' && typeof core.planToolResultImageShadows === 'function') {
+        const plans = planAgainstOneEvent(
+          event,
+          (events, seqs) => core.planToolResultImageShadows(events, seqs, () => true),
+        )
+        if (plans.length > 0) cachePendingRepairEvent(pendingToolRepairEvents, session, event)
+      } else if (event.type === 'user/message' && typeof core.planGuardStopShadows === 'function') {
+        const plans = planAgainstOneEvent(event, (events, seqs) => core.planGuardStopShadows(events, seqs))
+        if (plans.length > 0) cachePendingRepairEvent(pendingGuardRepairEvents, session, event)
+      }
+      repairFeedObserverWarnings.delete(session)
+    } catch (error) {
+      const message = boundedMessage(error)
+      if (repairFeedObserverWarnings.get(session) === message) return
+      repairFeedObserverWarnings.set(session, message)
+      logger?.warn?.('vision-router: session event feed observation failed error=%s', message)
+    }
+  }
+
+  const activateSurfaceEventFeed = () => {
+    surfaceEventFeedActive = true
+  }
+
+  const consumePendingRepairEvents = (pendingBySession, session) => {
+    const pending = pendingBySession.get(session)
+    if (!pending || pending.size === 0) return []
+    const nodes = surfaceNodes(session)
+    if (!nodes || nodes.length === 0) {
+      pending.clear()
+      return []
+    }
+    const current = new Set(nodes)
+    for (const seq of pending.keys()) {
+      if (!current.has(seq)) pending.delete(seq)
+    }
+    const entries = []
+    for (const seq of nodes) {
+      const event = pending.get(seq)
+      if (event === undefined) continue
+      pending.delete(seq)
+      entries.push({ seq, event })
+    }
+    return entries
+  }
+
+  const repairToolResultSurfaceFromFeed = async (session) => {
+    if (typeof session?.append !== 'function' || typeof core.planToolResultImageShadows !== 'function') return 0
+    const pending = consumePendingRepairEvents(pendingToolRepairEvents, session)
+    if (pending.length === 0) return 0
+    const preserve = keepToolResultImages()
+    let repaired = 0
+    for (const { seq, event } of pending) {
+      const events = { [seq]: event }
+      const plans = core.planToolResultImageShadows(events, [seq], () => !preserve)
+      for (const plan of plans) {
+        try {
+          const intent = replacementIntent(session, plan.seq)
+          if (intent === undefined) continue
+          await session.append(
+            'tool/result',
+            { ...plan.event.data, message: plan.message },
+            intent,
+          )
+          repaired += 1
+        } catch (error) {
+          logger?.warn?.(
+            'vision-router: session tool-result surface repair failed seq=%s error=%s',
+            plan.seq,
+            boundedMessage(error),
+          )
+        }
+      }
+    }
+    return repaired
+  }
+
+  const repairGuardStopSurfaceFromFeed = async (session) => {
+    if (typeof session?.append !== 'function' || typeof core.planGuardStopShadows !== 'function') return 0
+    const pending = consumePendingRepairEvents(pendingGuardRepairEvents, session)
+    if (pending.length === 0) return 0
+    let repaired = 0
+    for (const { seq, event } of pending) {
+      const events = { [seq]: event }
+      const plans = core.planGuardStopShadows(events, [seq])
+      for (const plan of plans) {
+        try {
+          const intent = replacementIntent(session, plan.seq)
+          if (intent === undefined) continue
+          await session.append(
+            'user/message',
+            plan.data,
+            intent,
+          )
+          repaired += 1
+        } catch (error) {
+          logger?.warn?.(
+            'vision-router: session guard-stop surface repair failed seq=%s error=%s',
+            plan.seq,
+            boundedMessage(error),
+          )
+        }
+      }
+    }
+    return repaired
+  }
+
   const repairToolResultSurface = async (session) => {
+    if (surfaceEventFeedActive) return repairToolResultSurfaceFromFeed(session)
     if (typeof session?.append !== 'function') return 0
     const scan = pendingSurfaceScan(toolSurfaceScans, session)
     if (!scan || typeof core.planToolResultImageShadows !== 'function') return 0
     const preserve = keepToolResultImages()
+    const snapshot = await surfaceRepairSnapshot(session, scan.seqs[0])
+    if (snapshot?.readable === false) return 0
     let repaired = 0
     for (const seq of scan.seqs) {
-      const read = await eventForSurfaceRepair(session, seq)
+      const read = snapshot?.readable === true
+        ? eventFromRepairSnapshot(session, snapshot.events, seq)
+        : await eventForSurfaceRepair(session, seq)
       if (!read.readable) break
       // A readable node is settled for this repair pass even when it needs no
       // replacement or append later fails; only an unread node remains pending.
@@ -282,12 +483,17 @@ export function createSessionVisionIndex({
   }
 
   const repairGuardStopSurface = async (session) => {
+    if (surfaceEventFeedActive) return repairGuardStopSurfaceFromFeed(session)
     if (typeof session?.append !== 'function') return 0
     const scan = pendingSurfaceScan(guardSurfaceScans, session)
     if (!scan || typeof core.planGuardStopShadows !== 'function') return 0
+    const snapshot = await surfaceRepairSnapshot(session, scan.seqs[0])
+    if (snapshot?.readable === false) return 0
     let repaired = 0
     for (const seq of scan.seqs) {
-      const read = await eventForSurfaceRepair(session, seq)
+      const read = snapshot?.readable === true
+        ? eventFromRepairSnapshot(session, snapshot.events, seq)
+        : await eventForSurfaceRepair(session, seq)
       if (!read.readable) break
       scan.advance()
       const events = []
@@ -333,6 +539,8 @@ export function createSessionVisionIndex({
 
   return Object.freeze({
     recordAttachments,
+    recordSessionEvent,
+    activateSurfaceEventFeed,
     lookupAttachment,
     resolveAttachment,
     resolveAttachments,
@@ -344,8 +552,9 @@ export function createSessionVisionIndex({
 
 /**
  * Intercept core's pre-step registration and decorate only its downstream
- * `next()` result. Production passes `options.index`; direct/test callers get
- * an isolated index/store unless they explicitly provide `options.stateStore`.
+ * `next()` result. Production also subscribes the index to DSH's post-commit
+ * `session/event` feed before activating feed-backed surface repair. Direct/test
+ * callers without a usable event feed retain the compatibility reader path.
  */
 export function installSessionVisionIndexBoundary(ctx, config, core, options = {}) {
   if (!isObject(ctx)) return ctx
@@ -363,6 +572,25 @@ export function installSessionVisionIndexBoundary(ctx, config, core, options = {
     logger: options.logger,
   })
 
+  try {
+    const on = Reflect.get(ctx, 'on', ctx)
+    if (
+      typeof on === 'function'
+      && typeof index.recordSessionEvent === 'function'
+      && typeof index.activateSurfaceEventFeed === 'function'
+    ) {
+      on.call(ctx, 'session/event', (session, event) => {
+        index.recordSessionEvent(session, event)
+      })
+      index.activateSurfaceEventFeed()
+    }
+  } catch (error) {
+    options.logger?.warn?.(
+      'vision-router: session event feed unavailable; retaining compatibility surface reader error=%s',
+      boundedMessage(error),
+    )
+  }
+
   return new Proxy(ctx, {
     get(target, property) {
       if (property === 'on') {

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

@@ -0,0 +1,331 @@
+import { htmlHasScriptMarker } from './html-script-marker.js'
+import { LOCAL_SETTINGS_PATH } from './dsh-settings-017-compat.js'
+
+const SETTINGS_017_MARK = 'data-vision-router-settings-017-compat'
+
+export const SETTINGS_017_CLIENT_PRELUDE = String.raw`(function(){
+  'use strict';
+  var TARGET = 'dsh-vision-router';
+  var ENDPOINT = '${LOCAL_SETTINGS_PATH}';
+  var contextCache = typeof WeakMap === 'function' ? new WeakMap() : undefined;
+  var scopeCache = typeof WeakMap === 'function' ? new WeakMap() : undefined;
+  var binderCache = typeof WeakMap === 'function' ? new WeakMap() : undefined;
+  var connectionCache = typeof WeakMap === 'function' ? new WeakMap() : undefined;
+
+  function safeGet(ctx, name) {
+    if (!ctx) return undefined;
+    try {
+      if (typeof ctx.get === 'function') {
+        var value = ctx.get(name);
+        if (value !== undefined && value !== null) return value;
+      }
+    } catch (_) {}
+    try { return ctx[name]; } catch (_) { return undefined; }
+  }
+
+  function isLoopbackLocation(locationLike) {
+    var hostname = locationLike && typeof locationLike.hostname === 'string'
+      ? locationLike.hostname.toLowerCase().replace(/^\[|\]$/g, '')
+      : '';
+    if (hostname === 'localhost' || hostname.endsWith('.localhost') || hostname === '::1') return true;
+    return /^127(?:\.\d{1,3}){3}$/.test(hostname);
+  }
+
+  function normalizeConnection(connection) {
+    if (!connection || typeof connection !== 'object') return connection;
+    var locationLike;
+    try { locationLike = window && window.location; } catch (_) { locationLike = undefined; }
+    if (!isLoopbackLocation(locationLike) || connection.isLoopback !== false) return connection;
+    if (connectionCache && connectionCache.has(connection)) return connectionCache.get(connection);
+    var wrapped = new Proxy(connection, {
+      get: function(target, property) {
+        if (property === 'isLoopback') return true;
+        var value = Reflect.get(target, property, target);
+        return typeof value === 'function' ? value.bind(target) : value;
+      }
+    });
+    if (connectionCache) connectionCache.set(connection, wrapped);
+    return wrapped;
+  }
+
+  function errorOf(value, fallback) {
+    var detail = value && value.error;
+    var error = new Error(detail && detail.message ? detail.message : fallback);
+    if (detail && detail.code) error.code = detail.code;
+    if (detail && detail.details !== undefined) error.details = detail.details;
+    return error;
+  }
+
+  function createScope() {
+    var listeners = new Set();
+    var writeTail = Promise.resolve();
+    var inFlight;
+    var snapshot = Object.freeze({
+      status: 'loading', value: undefined, base: undefined, user: undefined,
+      revision: undefined, writable: false, mode: 'host'
+    });
+    function publish(next) {
+      snapshot = Object.freeze(next);
+      listeners.forEach(function(listener){ try { listener(); } catch (_) {} });
+    }
+    function accept(view) {
+      if (!view || !view.value || typeof view.value !== 'object' || Array.isArray(view.value)
+          || !Number.isInteger(view.revision) || view.revision < 0) {
+        throw new Error('Vision Router local settings returned an invalid view');
+      }
+      publish({
+        status: 'ready', value: view.value, base: view.base, user: view.user,
+        revision: view.revision, writable: view.writable === true, mode: 'host'
+      });
+    }
+    async function request(method, payload) {
+      if (typeof fetch !== 'function') throw new Error('Vision Router local settings transport is unavailable');
+      var response = await fetch(ENDPOINT, {
+        method: method,
+        headers: { accept: 'application/json', ...(method === 'POST' ? { 'content-type': 'application/json' } : {}) },
+        cache: 'no-store',
+        credentials: 'same-origin',
+        ...(method === 'POST' ? { body: JSON.stringify(payload) } : {})
+      });
+      var body;
+      try { body = await response.json(); } catch (_) { body = undefined; }
+      if (!response.ok || !body || body.ok !== true) throw errorOf(body, 'Vision Router local settings request failed');
+      return body.value;
+    }
+    function load(restart) {
+      if (!restart && inFlight) return inFlight;
+      var task = request('GET').then(accept, function(error){
+        publish({
+          status: 'unavailable', value: undefined, base: undefined, user: undefined,
+          revision: undefined, writable: false, mode: 'host', error: error && error.message ? error.message : String(error)
+        });
+        throw error;
+      });
+      var held = task.finally(function(){ if (inFlight === held) inFlight = undefined; });
+      inFlight = held;
+      return held;
+    }
+    function writeOps(ops) {
+      if (!Array.isArray(ops) || ops.length === 0) return Promise.reject(new TypeError('settings operations must be a non-empty array'));
+      var task = writeTail.then(async function(){
+        if (snapshot.status !== 'ready' || !Number.isInteger(snapshot.revision)) await load(true);
+        if (snapshot.status !== 'ready' || !Number.isInteger(snapshot.revision)) throw new Error('Vision Router local settings are not ready');
+        if (!snapshot.writable) throw new Error('Vision Router settings provider is read-only');
+        try {
+          // One ConfigEditor edit may reload DVR. Keep all fields from one UI
+          // Save inside that single Host transaction so a second request cannot
+          // get stranded between plugin generations.
+          var view = await request('POST', { ops: ops, expectedRevision: snapshot.revision });
+          accept(view);
+        } catch (error) {
+          try { await load(true); } catch (_) {}
+          throw error;
+        }
+      });
+      writeTail = task.catch(function(){});
+      return task;
+    }
+    function planOps(items) {
+      if (!Array.isArray(items) || items.length === 0) throw new TypeError('settings plan must be a non-empty array');
+      return items.map(function(item){
+        if (!item || typeof item.key !== 'string' || item.key.length === 0 || !item.run) {
+          throw new TypeError('settings plan item is invalid');
+        }
+        return item.run.clear
+          ? { op: 'unset', path: [item.key] }
+          : { op: 'set', path: [item.key], value: item.run.value };
+      });
+    }
+    var scope = {
+      getSnapshot: function(){ return snapshot; },
+      subscribe: function(listener){
+        if (typeof listener !== 'function') return function(){};
+        listeners.add(listener);
+        return function(){ listeners.delete(listener); };
+      },
+      load: function(){ return load(false); },
+      reload: function(){ return load(true); },
+      set: function(field, value){ return writeOps([{ op: 'set', path: [field], value: value }]); },
+      unset: function(field){ return writeOps([{ op: 'unset', path: [field] }]); },
+      __visionRouterWritePlan: function(items){ return writeOps(planOps(items)); },
+      dispose: async function(){ listeners.clear(); await Promise.allSettled([inFlight, writeTail].filter(Boolean)); }
+    };
+    void load(false).catch(function(){});
+    return scope;
+  }
+
+  function scopeFor(ctx) {
+    if (scopeCache && scopeCache.has(ctx)) return scopeCache.get(ctx);
+    var scope = createScope();
+    if (scopeCache) scopeCache.set(ctx, scope);
+    return scope;
+  }
+
+  function syntheticBinder(ctx, original) {
+    return {
+      bind: function(spec) {
+        if (spec && spec.namespace === 'vision-router') return scopeFor(ctx);
+        if (original && typeof original.bind === 'function') return original.bind(spec);
+        throw new Error('Settings scope ' + String(spec && spec.namespace) + ' is unavailable');
+      }
+    };
+  }
+
+  function configFormsBinder(ctx) {
+    var forms = safeGet(ctx, 'configForms');
+    if (!forms || typeof forms.get !== 'function') return undefined;
+    if (binderCache && binderCache.has(forms)) return binderCache.get(forms);
+    var binder = {
+      bind: function(spec) {
+        var namespace = spec && spec.namespace;
+        if (typeof namespace !== 'string' || namespace.length === 0) {
+          throw new TypeError('settings namespace must be a non-empty string');
+        }
+        return forms.get(namespace);
+      }
+    };
+    if (binderCache) binderCache.set(forms, binder);
+    return binder;
+  }
+
+  function wrapContext(ctx) {
+    if (!ctx || typeof ctx !== 'object') return ctx;
+    if (contextCache && contextCache.has(ctx)) return contextCache.get(ctx);
+    var wrapped = new Proxy(ctx, {
+      get: function(target, property) {
+        if (property === 'settingsScope') {
+          var original = safeGet(target, 'settingsScope');
+          if (original && typeof original.bind === 'function') return original;
+          // DSH 0.1.7 configForms only mirrors Config fields declared volatile.
+          // DVR must keep its public Config ordinary for the older supported Host
+          // window, so its namespace intentionally uses the local-only ConfigEditor
+          // bridge while other namespaces may still delegate to native configForms.
+          var official = configFormsBinder(target);
+          return syntheticBinder(ctx, official);
+        }
+        if (property === 'get') {
+          var getter = Reflect.get(target, property, target);
+          if (typeof getter !== 'function') return getter;
+          return function(name) {
+            var value = getter.call(target, name);
+            return name === 'connection' ? normalizeConnection(value) : value;
+          };
+        }
+        var value = Reflect.get(target, property, target);
+        return typeof value === 'function' ? value.bind(target) : value;
+      }
+    });
+    if (contextCache) contextCache.set(ctx, wrapped);
+    return wrapped;
+  }
+
+  function requireConfigForms(plugin) {
+    if (!plugin || !Array.isArray(plugin.inject)) return plugin;
+    var inject = [];
+    var inserted = false;
+    for (var index = 0; index < plugin.inject.length; index += 1) {
+      var service = plugin.inject[index];
+      if (service === 'settingsScope') {
+        if (!inserted) {
+          inject.push('configForms');
+          inserted = true;
+        }
+        continue;
+      }
+      if (service === 'configForms') inserted = true;
+      if (inject.indexOf(service) === -1) inject.push(service);
+    }
+    // Another loader compatibility layer may already have removed the legacy
+    // dependency before this factory runs. DSH 0.1.7 still requires the native
+    // configForms service to be activation-ready before Vision Router applies.
+    if (!inserted) inject.unshift('configForms');
+    try {
+      plugin.inject = inject;
+      return plugin;
+    } catch (_) {
+      return Object.assign({}, plugin, { inject: inject });
+    }
+  }
+
+  function patchLoader(loader) {
+    if (!loader || typeof loader.load !== 'function' || loader.load.__visionRouterSettings017Compat) return;
+    var original = loader.load;
+    function load(spec) {
+      if (spec && spec.id === TARGET && typeof spec.factory === 'function') {
+        var factory = spec.factory;
+        spec = Object.assign({}, spec, {
+          factory: function(require) {
+            var plugin = requireConfigForms(factory(require));
+            if (plugin && typeof plugin.apply === 'function' && !plugin.apply.__visionRouterSettings017Compat) {
+              var apply = plugin.apply;
+              var wrappedApply = function(ctx) {
+                var rest = Array.prototype.slice.call(arguments, 1);
+                return apply.apply(plugin, [wrapContext(ctx)].concat(rest));
+              };
+              Object.defineProperty(wrappedApply, '__visionRouterSettings017Compat', { value: true });
+              plugin.apply = wrappedApply;
+            }
+            return plugin;
+          }
+        });
+      }
+      return original.call(this, spec);
+    }
+    Object.defineProperty(load, '__visionRouterSettings017Compat', { value: true });
+    loader.load = load;
+  }
+
+  function patchCreate(loader) {
+    if (!loader || typeof loader.create !== 'function' || loader.create.__visionRouterSettings017Compat) return;
+    var original = loader.create;
+    function create() {
+      var result = original.apply(this, arguments);
+      patchLoader(loader);
+      if (result && result !== loader) patchLoader(result);
+      return result;
+    }
+    Object.defineProperty(create, '__visionRouterSettings017Compat', { value: true });
+    loader.create = create;
+    if (loader.mode === 'live') patchLoader(loader);
+  }
+
+  function install() {
+    var descriptor = Object.getOwnPropertyDescriptor(window, '__ModuleLoader__');
+    var stored = window.__ModuleLoader__;
+    if (stored) patchCreate(stored);
+    if (descriptor && descriptor.configurable === false) return;
+    var previousGet = descriptor && descriptor.get;
+    var previousSet = descriptor && descriptor.set;
+    Object.defineProperty(window, '__ModuleLoader__', {
+      configurable: true,
+      enumerable: !descriptor || descriptor.enumerable !== false,
+      get: function(){ return previousGet ? previousGet.call(window) : stored; },
+      set: function(value) {
+        if (previousSet) previousSet.call(window, value); else stored = value;
+        try { patchCreate(previousGet ? previousGet.call(window) : value); } catch (_) {}
+      }
+    });
+  }
+
+  try { install(); } catch (_) {}
+})();`
+
+export function injectSettings017ClientPrelude(html) {
+  if (typeof html !== 'string' || htmlHasScriptMarker(html, SETTINGS_017_MARK)) return html
+  const safe = SETTINGS_017_CLIENT_PRELUDE.replace(/<\/script/gi, '<\\/script')
+  const script = `<script ${SETTINGS_017_MARK}>${safe}</script>`
+  const closeHead = html.indexOf('</head>')
+  return closeHead === -1 ? `${html}${script}` : `${html.slice(0, closeHead)}${script}${html.slice(closeHead)}`
+}
+
+export function installSettings017ClientCompatibility(ctx) {
+  if (!ctx || typeof ctx.inject !== 'function') return
+  // ConfigEditor is the generation fence: old supported Hosts keep their native
+  // settingsScope activation contract and never see this client shim.
+  ctx.inject(['configEditor', 'webServer'], (webCtx) => {
+    webCtx.effect(
+      () => webCtx.webServer.tapIndex(injectSettings017ClientPrelude),
+      'vision-router: DSH 0.1.7 settings client compatibility',
+    )
+  })
+}