dsh-vision-router 2.1.7 → 2.2.1

package/lib/session-vision-index.js

@@ -1,11 +1,14 @@
 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'
 }
 
-function sessionEvents(session) {
+function legacySessionEvents(session) {
   try {
     // dsh 0.1.2-alpha.4 removed the bare `session.events` array in favor of
     // `session.snapshotEvents()`; both are handled so one build runs on both
@@ -38,23 +41,35 @@ 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
- * incremental durable-log scan, target-only recovery after bounded-cache
- * eviction, 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(). Durable recovery is
- * requested explicitly through index.lookupAttachment(), so storage and
- * recovery ownership remain visible at the call site.
+ * The index never replaces stateStore.lookupAttachment(). Cache lookup stays
+ * synchronous through lookupAttachment(); cold durable recovery is requested
+ * explicitly through async resolveAttachment(), so I/O ownership remains visible.
  */
 export function createSessionVisionIndex({
   stateStore,
   core,
   config = {},
   logger,
+  readSessionEvent,
+  readSessionLog,
 } = {}) {
   if (!core || typeof core !== 'object') throw new TypeError('session vision index requires core helpers')
 
@@ -70,59 +85,103 @@ 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)
   }
 
-  const scanEventLog = (session) => {
-    if (!session) return
-    const events = sessionEvents(session)
-    if (!events || events.length === 0) return
-    const last = store.getScannedEventSeq(session)
-    if (last >= events.length) return
-    const refs = typeof core.collectEventAttachmentRefs === 'function'
-      ? core.collectEventAttachmentRefs(events.slice(last))
-      : []
-    // Advance even when no refs are present so irrelevant durable history is
-    // never rescanned indefinitely.
-    store.setScannedEventSeq(session, events.length)
-    if (Array.isArray(refs) && refs.length > 0) 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) => {
     if (!primitiveLookup) return undefined
-    let hit = primitiveLookup(session, id)
-    if (hit !== undefined) return hit
-    if (session === undefined) return undefined
-
-    scanEventLog(session)
-    hit = primitiveLookup(session, id)
-    if (hit !== undefined) return hit
-
-    // Bounded cache eviction is a performance event, never a correctness
-    // event. Recover only the requested durable ref instead of rebuilding an
-    // unbounded attachment index.
-    const events = sessionEvents(session)
-    if (!events || events.length === 0 || typeof core.collectEventAttachmentRefs !== 'function') {
-      return undefined
+    return primitiveLookup(session, id)
+  }
+
+  const recoverAttachmentsFromEvents = (session, ids, events) => {
+    const found = new Map()
+    if (!Array.isArray(events) || events.length === 0 || typeof core.collectEventAttachmentRefs !== 'function') {
+      return found
     }
-    const wanted = String(id)
-    const recovered = core.collectEventAttachmentRefs(events).find(
-      (ref) => ref && String(ref.attachmentId ?? ref.id) === wanted,
+    const wanted = new Set(ids.map((id) => String(id)))
+    for (const ref of core.collectEventAttachmentRefs(events)) {
+      if (!ref) continue
+      const id = String(ref.attachmentId ?? ref.id)
+      if (wanted.has(id) && !found.has(id)) found.set(id, ref)
+    }
+    if (found.size > 0) store.recordAttachments(session, [...found.values()])
+    return found
+  }
+
+  const warnAttachmentRecoveryFailure = (session, id, error) => {
+    const message = boundedMessage(error)
+    const key = `${String(id)}:${message}`
+    if (attachmentRecoveryWarnings.get(session) === key) return
+    attachmentRecoveryWarnings.set(session, key)
+    logger?.warn?.(
+      'vision-router: session attachment recovery failed id=%s error=%s',
+      String(id),
+      message,
     )
-    if (recovered !== undefined) {
-      store.recordAttachments(session, [recovered])
-      return recovered
+  }
+
+  const resolveAttachments = async (session, ids) => {
+    const requested = [...new Set((Array.isArray(ids) ? ids : []).map((id) => String(id)))]
+    const resolved = new Map()
+    const missing = []
+    for (const id of requested) {
+      const cached = lookupAttachment(session, id)
+      if (cached !== undefined) resolved.set(id, cached)
+      else missing.push(id)
     }
-    return undefined
+    if (missing.length === 0 || session === undefined) return resolved
+
+    let events
+    if (typeof readSessionLog === 'function') {
+      let result
+      try {
+        result = await readSessionLog(session)
+      } catch (error) {
+        warnAttachmentRecoveryFailure(session, missing[0], error)
+        return resolved
+      }
+      if (result?.supported === true) {
+        attachmentRecoveryWarnings.delete(session)
+        events = result.events
+      } else if (result?.supported !== false) {
+        warnAttachmentRecoveryFailure(
+          session,
+          missing[0],
+          new Error('Session log reader returned an invalid capability result'),
+        )
+        return resolved
+      }
+    }
+
+    // Historical/partial Hosts without SessionQuery keep the released fallback.
+    // Public rc8+ Hosts use readSessionLog above and never touch sync history.
+    if (events === undefined) events = legacySessionEvents(session)
+    const recovered = recoverAttachmentsFromEvents(session, missing, events)
+    for (const [id, ref] of recovered) resolved.set(id, ref)
+    return resolved
   }
 
-  const nextSurfaceSeqs = (scans, session) => {
-    if (!session) return []
+  const resolveAttachment = async (session, id) => {
+    return (await resolveAttachments(session, [id])).get(String(id))
+  }
+
+  const pendingSurfaceScan = (scans, session) => {
+    if (!session) return undefined
     const nodes = surfaceNodes(session)
-    if (!nodes || nodes.length === 0) return []
+    if (!nodes || nodes.length === 0) return undefined
     let scan = scans.get(session)
     if (!scan) {
       scan = { count: 0 }
@@ -131,9 +190,88 @@ export function createSessionVisionIndex({
     // Compaction/resume may shrink/rebuild the surface. Reset the incremental
     // cursor rather than assuming old indices still refer to the new surface.
     if (scan.count > nodes.length) scan.count = 0
-    const fresh = nodes.slice(scan.count)
-    scan.count = nodes.length
-    return fresh
+    const count = nodes.length
+    const seqs = nodes.slice(scan.count)
+    if (seqs.length === 0) return undefined
+    return {
+      seqs,
+      advance() {
+        if (scan.count < count) scan.count += 1
+      },
+    }
+  }
+
+  const warnRepairReadFailure = (session, seq, error) => {
+    const message = boundedMessage(error)
+    const previous = repairReadWarnings.get(session)
+    if (previous?.seq === seq && previous.message === message) return
+    repairReadWarnings.set(session, { seq, message })
+    logger?.warn?.(
+      'vision-router: session surface event read failed seq=%s error=%s',
+      seq,
+      message,
+    )
+  }
+
+  const eventForSurfaceRepair = async (session, seq) => {
+    if (typeof readSessionEvent === 'function') {
+      let result
+      try {
+        result = await readSessionEvent(session, seq)
+      } catch (error) {
+        warnRepairReadFailure(session, seq, error)
+        return { readable: false }
+      }
+      if (result?.supported === true) {
+        repairReadWarnings.delete(session)
+        return { readable: true, event: result.event }
+      }
+      if (result?.supported !== false) {
+        warnRepairReadFailure(session, seq, new Error('Session event reader returned an invalid capability result'))
+        return { readable: false }
+      }
+    }
+
+    // Isolated/partial Hosts that do not expose SessionQuery retain the released
+    // 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 = () => {
@@ -143,60 +281,241 @@ export function createSessionVisionIndex({
     return policy.ownership === 'native-image' || policy.ownership === 'vision-router-owned'
   }
 
+  const replacementIntent = (session, seq) => {
+    const intent = sessionSurfaceReplacementIntent(session, seq)
+    if (intent !== undefined) return intent
+    if (!unsupportedSurfaceContracts.has(session)) {
+      unsupportedSurfaceContracts.add(session)
+      logger?.warn?.(
+        'vision-router: skipping durable session surface repair for unsupported Session format version=%s',
+        session?.header?.version ?? 'unknown',
+      )
+    }
+    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) => {
-    const events = sessionEvents(session)
-    if (!events || typeof session?.append !== 'function') return 0
-    const seqs = nextSurfaceSeqs(toolSurfaceScans, session)
-    if (seqs.length === 0 || typeof core.planToolResultImageShadows !== 'function') return 0
+    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 plans = core.planToolResultImageShadows(events, seqs, () => !preserve)
+    const snapshot = await surfaceRepairSnapshot(session, scan.seqs[0])
+    if (snapshot?.readable === false) return 0
     let repaired = 0
-    for (const plan of plans) {
-      try {
-        await session.append(
-          'tool/result',
-          { ...plan.event.data, message: plan.message },
-          {
-            surfaceOp: { op: 'replace', start: plan.seq, end: plan.seq },
-            sourceEventSeqs: [plan.seq],
-          },
-        )
-        repaired += 1
-      } catch (error) {
-        logger?.warn?.(
-          'vision-router: session tool-result surface repair failed seq=%s error=%s',
-          plan.seq,
-          boundedMessage(error),
-        )
+    for (const seq of scan.seqs) {
+      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.
+      scan.advance()
+      const events = []
+      events[seq] = read.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 repairGuardStopSurface = async (session) => {
-    const events = sessionEvents(session)
-    if (!events || typeof session?.append !== 'function') return 0
-    const seqs = nextSurfaceSeqs(guardSurfaceScans, session)
-    if (seqs.length === 0 || typeof core.planGuardStopShadows !== 'function') return 0
-    const plans = core.planGuardStopShadows(events, seqs)
+    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 plan of plans) {
-      try {
-        await session.append(
-          'user/message',
-          plan.data,
-          {
-            surfaceOp: { op: 'replace', start: plan.seq, end: plan.seq },
-            sourceEventSeqs: [plan.seq],
-          },
-        )
-        repaired += 1
-      } catch (error) {
-        logger?.warn?.(
-          'vision-router: session guard-stop surface repair failed seq=%s error=%s',
-          plan.seq,
-          boundedMessage(error),
-        )
+    for (const seq of scan.seqs) {
+      const read = snapshot?.readable === true
+        ? eventFromRepairSnapshot(session, snapshot.events, seq)
+        : await eventForSurfaceRepair(session, seq)
+      if (!read.readable) break
+      scan.advance()
+      const events = []
+      events[seq] = read.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
@@ -213,7 +532,6 @@ export function createSessionVisionIndex({
         store.recordAttachments(session, found.attachments)
       }
     }
-    scanEventLog(session)
     await repairToolResultSurface(session)
     await repairGuardStopSurface(session)
     return decision
@@ -221,8 +539,11 @@ export function createSessionVisionIndex({
 
   return Object.freeze({
     recordAttachments,
-    scanEventLog,
+    recordSessionEvent,
+    activateSurfaceEventFeed,
     lookupAttachment,
+    resolveAttachment,
+    resolveAttachments,
     repairToolResultSurface,
     repairGuardStopSurface,
     prepareDecision,
@@ -231,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
@@ -250,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') {