@mindot/will 0.1.0

package/src/stem/tracts/sensory.controller.ts

@@ -0,0 +1,168 @@
+// ─────────────────────────────────────────────────────────────
+// src/stem/tracts/sensory.controller.ts  —  per-Will senses I/O subsystem
+// ─────────────────────────────────────────────────────────────
+//
+// SensoryController owns the senses input + LLM chunk-streaming output
+// boundary extracted from WillStem (R5-e):
+//   - input ingestion: ingestText / ingestSensory / injectEvent
+//   - real-time chunk streaming: addChunkListener / addSensoryChunkListener
+//     and their sync helpers (syncChunkBroadcaster + the addChunkCallback fan-out)
+//
+// WillStem delegates the matching public methods here, so the god-object no
+// longer owns this concern. The ops touch only WillInstance fields (no Will
+// id needed), so these methods take the resolved instance directly; WillStem
+// still validates existence via _get(id) before delegating.
+//
+// Behaviour is preserved verbatim from the original WillStem methods;
+// this is a pure extract-collaborator refactor.
+// ─────────────────────────────────────────────────────────────
+
+import type { TextMessage, SensoryInput } from '#senses/index'
+import type { WillInstance } from '#stem/index'
+
+export class SensoryController {
+  /** Instances whose SSE chunk fan-out has already been registered on the engine. */
+  private readonly _chunkWired = new WeakSet<WillInstance>()
+  /** Per-Will monotonic counter for deterministic injected-event ids (replay). */
+  private readonly _eventSeq   = new WeakMap<WillInstance, number>()
+
+  // ── Input ingestion ──────────────────────────────────────────
+
+  /**
+   * Route an external text message through the Will's AuditionEngine.
+   * The senses-aware AuditionEngine handles salience, thread digests,
+   * LanguagePercept publication, conversation-facet spawn/reuse, and LLM
+   * reply generation. Reply delivery is async via the outbox / SSE channel.
+   */
+  async ingestText( instance: WillInstance, input: TextMessage ): Promise<void> {
+    await instance.cognition.auditionEngine.ingest( input )
+  }
+
+  /**
+   * Route a raw SensoryInput to the appropriate sense engine by domain.
+   * Used by the debug `POST /senses/:domain/ingest` route.
+   */
+  async ingestSensory( instance: WillInstance, domain: string, input: SensoryInput ): Promise<void> {
+    const cog = instance.cognition
+    const engineMap: Record<string, { ingest: (i: SensoryInput) => Promise<void> }> = {
+      audition:        cog.auditionEngine,
+      vision:          cog.visionEngine,
+      somatosensation: cog.somatosensationEngine,
+      olfaction:       cog.olfactionEngine,
+      gustation:       cog.gustationEngine,
+    }
+    const engine = engineMap[ domain ]
+    if( !engine ) throw Object.assign( new Error( `Unknown sense domain: ${domain}` ), { code: 400 } )
+    await engine.ingest( input )
+  }
+
+  /**
+   * Inject a percept or external event into the Will's world.
+   * The event is picked up by perceptual engines on the next tick.
+   */
+  injectEvent( instance: WillInstance, event: { type: string; payload: Record<string, unknown> } ): void {
+    // Deterministic id (tick + per-Will monotonic counter) so injected-event
+    // entities reproduce on replay — they're compared in ReplayComparison, and
+    // Date.now()+random made them diverge every run. createdAt/updatedAt are left
+    // to StateManager.setEntity, which stamps the (deterministic) sim clock time.
+    const seq = ( this._eventSeq.get( instance ) ?? 0 ) + 1
+    this._eventSeq.set( instance, seq )
+
+    instance.simulation.stateManager.setEntity({
+      id:       `external-event-${instance.tickCount}-${seq}`,
+      type:     event.type,
+      metadata: event.payload,
+    })
+  }
+
+  // ── Real-time LLM chunk streaming (F3) ───────────────────────
+
+  /**
+   * Subscribe to real-time LLM token chunks for this Will (Will-wide).
+   * The callback fires for each text token during executive LLM generation.
+   * Returns an unsubscribe function — call it when the SSE connection closes.
+   */
+  addChunkListener( instance: WillInstance, fn: ( chunk: string ) => void ): () => void {
+    instance.chunkListeners.add( fn )
+    this.syncChunkBroadcaster( instance )
+
+    return () => {
+      instance.chunkListeners.delete( fn )
+      this.syncChunkBroadcaster( instance )
+    }
+  }
+
+  /**
+   * Subscribe to real-time LLM token chunks for a specific conversation entity.
+   *
+   * Unlike addChunkListener() (Will-wide), this fires only when the AuditionEngine
+   * conversation facet for `entityId` is actively streaming — isolating chunks to the
+   * relevant SSE/WS client connection.
+   *
+   * On the first listener for any entity, wires addChunkCallback() on the
+   * AuditionEngine to fan out chunks by entityId. Subsequent listeners reuse the same
+   * callback — no duplicate registration occurs.
+   *
+   * Returns an unsubscribe function — call it when the SSE/WS connection closes.
+   */
+  addSensoryChunkListener(
+    instance: WillInstance,
+    entityId: string,
+    fn: ( chunk: string ) => void,
+  ): () => void {
+    let listeners = instance.sensoryChunkListeners.get( entityId )
+    if( !listeners ){
+      listeners = new Set()
+      instance.sensoryChunkListeners.set( entityId, listeners )
+    }
+
+    listeners.add( fn )
+
+    // Register the SSE fan-out on the engine once per instance. It reads the live
+    // sensoryChunkListeners map, so it stays correct as listeners come and go, and
+    // coexists with other chunk subscribers (e.g. the transport emit) — the engine
+    // chunk callback is multi-subscriber.
+    this._ensureChunkFanout( instance )
+
+    return () => {
+      listeners!.delete( fn )
+      if( listeners!.size === 0 )
+        instance.sensoryChunkListeners.delete( entityId )
+    }
+  }
+
+  /** Register the per-instance SSE chunk fan-out on the AuditionEngine (idempotent). */
+  private _ensureChunkFanout( instance: WillInstance ): void {
+    if( this._chunkWired.has( instance ) ) return
+    const audition = instance.cognition.auditionEngine
+    if( typeof ( audition as { addChunkCallback?: unknown } ).addChunkCallback !== 'function' ) return
+
+    this._chunkWired.add( instance )
+    audition.addChunkCallback( ( entityId: string, _threadId: string, chunk: string ) => {
+      const fns = instance.sensoryChunkListeners.get( entityId )
+      if( !fns ) return
+      for( const fn of fns ){
+        try { fn( chunk ) } catch {}
+      }
+    })
+  }
+
+  syncChunkBroadcaster( instance: WillInstance ): void {
+    // Get the executive engine (typed loosely to avoid circular imports)
+    const exec = ( instance.cognition as unknown as Record<string, unknown> )?.executiveEngine as
+      { setChunkBroadcaster?: ( fn: (( c: string ) => void) | null ) => void } | undefined
+    if( !exec?.setChunkBroadcaster ) return
+
+    if( instance.chunkListeners.size === 0 ){
+      exec.setChunkBroadcaster( null )
+    }
+    else {
+      // Single broadcaster that fans out to all listeners
+      exec.setChunkBroadcaster(( chunk: string ) => {
+        for( const fn of instance.chunkListeners ){
+          try { fn( chunk ) } catch {}
+        }
+      })
+    }
+  }
+}

package/src/stem/tracts/session.logger.ts

@@ -0,0 +1,157 @@
+// ─────────────────────────────────────────────────────────────
+// src/stem/session.logger.ts
+// ─────────────────────────────────────────────────────────────
+//
+// Captures every significant event in a Will's cognitive cycle:
+//
+//   tick             — per-tick metrics snapshot + entity counts
+//   event            — every semantic event from the EventBus
+//   executive.call     — LLM call metadata (model, prompt size, path)
+//   executive.response — LLM response (tokens, latency, raw excerpt)
+//   executive.output   — parsed structured output (actions, beliefs, ...)
+//   action.execute   — effector execution result and feedback
+//   belief.integrate — belief written to store (pre/post confidence cap)
+//   conversation.in  — inbound message from an external entity
+//   conversation.out — outbound message composed by the Will
+//   session.start    — written once on logger creation
+//   session.end      — written on close()
+//
+// Transport: every entry is forwarded (via `emit`/`attachEmit`) to the stem,
+// which emits it as a `session_log` envelope on the Will's ExternalTransport —
+// so the product wrapper / consumer owns persistence (Postgres, S3, Kafka,
+// SSE …). The Will itself no longer uploads to S3.
+//
+// Files: in DEVELOPMENT only (see `fileLoggingEnabled()`), the same NDJSON is
+// also written to data/wills/{willId}/sessions/{sessionId}.jsonl. One JSON
+// object per line; parse with `jq`, Python, or any NDJSON reader.
+// ─────────────────────────────────────────────────────────────
+
+import { createWriteStream, mkdirSync } from 'node:fs'
+import { join } from 'node:path'
+import type { WriteStream } from 'node:fs'
+
+/** Forwards each entry to the consumer (the stem bridges it onto the transport). */
+export type SessionLogEmit = ( record: Record<string, unknown> ) => void
+
+// ── Entry type union ──────────────────────────────────────────
+
+export type LogEntryType =
+  | 'session.start'
+  | 'session.end'
+  | 'tick'
+  | 'event'
+  | 'executive.call'
+  | 'executive.response'
+  | 'executive.output'
+  | 'executive.facet.spawn'
+  | 'executive.facet.call'
+  | 'executive.facet.response'
+  | 'executive.facet.output'
+  | 'executive.facet.destroy'
+  | 'action.execute'
+  | 'action.error'
+  | 'action.outcome'
+  | 'belief.integrate'
+  | 'conversation.in'
+  | 'conversation.out'
+  | 'plan.step.activated'
+  | 'plan.step.outcome'
+  | 'goal.progress'
+  | 'goal.achieved'
+  | 'goal.blocked'
+  | 'goal.abandoned'
+  | 'outbox.push'
+  | 'outbox.expire'
+
+interface BaseEntry {
+  type:     LogEntryType
+  wallTime: number
+  tick?:    number
+}
+
+export type LogEntry = BaseEntry & Record<string, unknown>
+
+export interface SessionLoggerOptions {
+  /**
+   * Forward every entry to the consumer (typically the stem, which emits it as a
+   * `session_log` envelope on the transport). May also be set later via
+   * {@link SessionLogger.attachEmit} once the Will instance exists.
+   */
+  emit?:        SessionLogEmit | null
+  /** Also write a local NDJSON file. Dev convenience only; off in production. */
+  fileLogging?: boolean
+  /** Override the data directory for the dev file (default `./data`). */
+  dataDir?:     string
+}
+
+// ── SessionLogger ─────────────────────────────────────────────
+
+export class SessionLogger {
+  readonly sessionId: string
+  /** Local file path — empty string when file logging is disabled. */
+  readonly filePath:  string
+
+  private readonly _stream:     WriteStream | null
+  private          _emit:       SessionLogEmit | null
+  private          _closed   = false
+  private          _count    = 0
+
+  constructor( willId: string, dataDir: string = './data', opts: SessionLoggerOptions = {} ) {
+    const ts  = new Date().toISOString().replace( /[:.]/g, '-' ).slice( 0, 19 )
+    const rnd = Math.random().toString( 36 ).slice( 2, 8 )
+    this.sessionId = `${ts}-${rnd}`
+
+    this._emit = opts.emit ?? null
+
+    const fileLogging = opts.fileLogging ?? false
+    if( fileLogging ){
+      const dir = join( opts.dataDir ?? dataDir, 'wills', willId, 'sessions' )
+      mkdirSync( dir, { recursive: true } )
+      this.filePath = join( dir, `${this.sessionId}.jsonl` )
+      this._stream  = createWriteStream( this.filePath, { flags: 'a' } )
+    } else {
+      this.filePath = ''
+      this._stream  = null
+    }
+  }
+
+  /**
+   * Late-bind the consumer forwarder (the stem sets this once the Will instance
+   * exists, so it can emit a `session_log` envelope on the instance's transport).
+   */
+  attachEmit( emit: SessionLogEmit ): void {
+    this._emit = emit
+  }
+
+  write( entry: Omit<LogEntry, 'wallTime'> ): void {
+    if( this._closed ) return
+    const record = { wallTime: Date.now(), ...entry }
+
+    // Forward first — this is the production transport; the consumer persists it.
+    try { this._emit?.( record ) }
+    catch { /* a listener fault must never block the tick loop */ }
+
+    // File is a dev-only mirror.
+    if( this._stream ){
+      try { this._stream.write( JSON.stringify( record ) + '\n' ) }
+      catch { /* never block the tick loop on a log failure */ }
+    }
+
+    this._count++
+  }
+
+  /**
+   * Emits `session.end` and closes the local file stream (if any). Persistence
+   * of the streamed entries is the consumer's responsibility — the Will no longer
+   * uploads anywhere itself.
+   */
+  close(): void {
+    if( this._closed ) return
+    this.write({ type: 'session.end', totalEntries: this._count + 1 })
+    this._closed = true
+    this._stream?.end()
+  }
+
+  get entryCount(): number { return this._count }
+  get isClosed():   boolean { return this._closed }
+}

package/src/stem/tracts/transport/index.ts

@@ -0,0 +1,38 @@
+// ─────────────────────────────────────────────────────────────
+// src/stem/tracts/transport/index.ts — ExternalTransport barrel
+// ─────────────────────────────────────────────────────────────
+
+export type {
+  ExternalTransport,
+  Envelope,
+  OutboundEnvelope,
+  InboundEnvelope,
+  ReplyEnvelope,
+  ChunkEnvelope,
+  MessageEnvelope,
+  effectorInvocationEnvelope,
+  PerceptEnvelope,
+  ActivityEnvelope,
+  SessionLogEnvelope,
+  TokenReportEnvelope,
+  InboundMessageEnvelope,
+  InboundPerceptEnvelope,
+  AckEnvelope,
+  AckResult,
+  TransportStatus,
+} from '#stem/tracts/transport/types'
+
+export { LoopbackTransport, type AckPolicy } from '#stem/tracts/transport/loopback.transport'
+export {
+  SocketIoTransport,
+  type SocketIoTransportOptions,
+  type SocketLike,
+} from '#stem/tracts/transport/socketio.transport'
+
+
+export {
+  type StreamChannel,
+  StreamTransport,
+  type OutboundListener,
+  fileLoggingEnabled,
+} from '#stem/tracts/transport/stream.transport'

package/src/stem/tracts/transport/loopback.transport.ts

@@ -0,0 +1,86 @@
+// ─────────────────────────────────────────────────────────────
+// src/stem/tracts/transport/loopback.transport.ts
+// ─────────────────────────────────────────────────────────────
+//
+// LoopbackTransport — in-memory, deterministic ExternalTransport for tests,
+// replay, and any configuration without a real peer.
+//
+// No sockets, no timers: emit() resolves its ack synchronously per a scripted
+// policy, and inbound is driven by injectInbound(). Mirrors the role of
+// InProcessCognitiveTransport for the cognitive bus.
+// ─────────────────────────────────────────────────────────────
+
+import type {
+  ExternalTransport,
+  OutboundEnvelope,
+  InboundEnvelope,
+  AckResult,
+  TransportStatus,
+} from './types'
+
+/** Decides how emit() resolves an ack for a given envelope. Default: acked via callback. */
+export type AckPolicy = ( env: OutboundEnvelope ) => AckResult
+
+const DEFAULT_ACK: AckPolicy = () => ({ acked: true, via: 'callback' })
+
+export class LoopbackTransport implements ExternalTransport {
+  /** Every envelope passed to emit(), in order — inspect in tests. */
+  readonly sent: OutboundEnvelope[] = []
+
+  private _connected = true
+  private _ackPolicy: AckPolicy
+  private readonly _inboundHandlers = new Set<( env: InboundEnvelope ) => void>()
+  private readonly _statusHandlers  = new Set<( s: TransportStatus ) => void>()
+
+  constructor( ackPolicy: AckPolicy = DEFAULT_ACK ){
+    this._ackPolicy = ackPolicy
+  }
+
+  get connected(): boolean { return this._connected }
+
+  async emit( env: OutboundEnvelope ): Promise<AckResult> {
+    this.sent.push( env )
+    return this._ackPolicy( env )
+  }
+
+  onInbound( handler: ( env: InboundEnvelope ) => void ): () => void {
+    this._inboundHandlers.add( handler )
+    return () => { this._inboundHandlers.delete( handler ) }
+  }
+
+  onStatus( handler: ( s: TransportStatus ) => void ): () => void {
+    this._statusHandlers.add( handler )
+    return () => { this._statusHandlers.delete( handler ) }
+  }
+
+  close(): void {
+    this._connected = false
+    this._inboundHandlers.clear()
+    this._statusHandlers.clear()
+    this.sent.length = 0
+  }
+
+  // ── Test / harness controls ──────────────────────────────────
+
+  /** Simulate the peer sending an inbound envelope to the Will. */
+  injectInbound( env: InboundEnvelope ): void {
+    for( const h of this._inboundHandlers ) h( env )
+  }
+
+  /** Flip connection state and notify status handlers. */
+  setConnected( connected: boolean ): void {
+    this._connected = connected
+    const status: TransportStatus = connected ? 'connected' : 'disconnected'
+    for( const h of this._statusHandlers ) h( status )
+  }
+
+  /** Swap the ack policy mid-test (e.g. to simulate timeouts then recovery). */
+  setAckPolicy( policy: AckPolicy ): void {
+    this._ackPolicy = policy
+  }
+
+  /** Convenience: only the envelopes on a given channel. */
+  sentOn<T extends OutboundEnvelope['channel']>( channel: T ): Extract<OutboundEnvelope, { channel: T }>[] {
+    return this.sent.filter( e => e.channel === channel ) as Extract<OutboundEnvelope, { channel: T }>[]
+  }
+}

package/src/stem/tracts/transport/socketio.transport.ts

@@ -0,0 +1,200 @@
+// ─────────────────────────────────────────────────────────────
+// src/stem/tracts/transport/socketio.transport.ts
+// ─────────────────────────────────────────────────────────────
+//
+// SocketIoTransport — production ExternalTransport over socket.io-client.
+//
+// The peer (backend) hosts the socket.io server; this is Will's client side.
+// It is constructed by the CALLER and injected via WillConfig.transport, so the
+// `will` package never imports socket.io-client at module load — the dependency
+// is OPTIONAL and loaded lazily via a dynamic import only when a transport is
+// actually instantiated. The import specifier is indirected through a variable
+// so the type checker does not require the module to be installed.
+//
+// Outbound:  emit('envelope', env, ack)  — socket.io ack callback gives the fast
+//            best-effort delivery/result ack (Section 3 reconciles with the
+//            durable discrete-event path).
+// Inbound:   'envelope' events plus discrete 'message.delivered' /
+//            'effector.invoked.ack' events (synthesized into ack envelopes), in
+//            case the peer emits them independently. All inbound is handed to
+//            onInbound() handlers — the stem enqueues them onto the tick queue.
+// ─────────────────────────────────────────────────────────────
+
+import { logger } from '#core/logger'
+import { wallClock } from '#core/wall.clock'
+import type {
+  ExternalTransport,
+  OutboundEnvelope,
+  InboundEnvelope,
+  AckEnvelope,
+  AckResult,
+  TransportStatus,
+} from './types'
+
+/** Minimal surface of a socket.io client we depend on — keeps us decoupled from the dep's types. */
+export interface SocketLike {
+  connected: boolean
+  on( event: string, handler: ( ...args: any[] ) => void ): void
+  emit( event: string, payload: unknown, ack?: ( response: unknown ) => void ): void
+  disconnect(): void
+}
+
+export interface SocketIoTransportOptions {
+  /** socket.io server URL (e.g. wss://host or http://host:port). */
+  url:           string
+  /** This Will's id — sent as auth + routing key. */
+  willId:        string
+  /** Optional auth token sent in the socket.io handshake. */
+  token?:        string
+  /** Default ack timeout for emit() in ms. Default 5000. */
+  ackTimeoutMs?: number
+  /**
+   * Override the socket factory — inject a fake in tests, or customize the
+   * socket.io connection. When omitted, `socket.io-client` is dynamically
+   * imported and `io(url, { auth })` is called.
+   */
+  socketFactory?: ( url: string, opts: { auth: { willId: string; token?: string } } ) => SocketLike | Promise<SocketLike>
+}
+
+const DEFAULT_ACK_TIMEOUT_MS = 5_000
+
+export class SocketIoTransport implements ExternalTransport {
+  private _socket:     SocketLike | null = null
+  private _connecting: Promise<SocketLike | null> | null = null
+  private _seq        = 0
+
+  private readonly _inboundHandlers = new Set<( env: InboundEnvelope ) => void>()
+  private readonly _statusHandlers  = new Set<( s: TransportStatus ) => void>()
+
+  constructor( private readonly _opts: SocketIoTransportOptions ){
+    // Begin connecting eagerly; emit()/inbound wiring await the same promise.
+    void this._ensureSocket()
+  }
+
+  get connected(): boolean { return this._socket?.connected ?? false }
+
+  // ── Outbound ─────────────────────────────────────────────────
+
+  async emit( env: OutboundEnvelope, opts?: { ackTimeoutMs?: number } ): Promise<AckResult> {
+    const socket = await this._ensureSocket()
+    if( !socket || !socket.connected )
+      // No connection — caller keeps the message buffered (outbox) and retries.
+      return { acked: false, via: 'timeout' }
+
+    const timeoutMs = opts?.ackTimeoutMs ?? this._opts.ackTimeoutMs ?? DEFAULT_ACK_TIMEOUT_MS
+    const stamped: OutboundEnvelope = { ...env, seq: env.seq || ++this._seq }
+
+    return new Promise<AckResult>( resolve => {
+      let settled = false
+      const done = ( r: AckResult ) => { if( !settled ){ settled = true; clearTimeout( timer ); resolve( r ) } }
+
+      const timer = setTimeout( () => done({ acked: false, via: 'timeout' }), timeoutMs )
+
+      try {
+        socket.emit( 'envelope', stamped, ( response: unknown ) => done({ acked: true, via: 'callback', payload: response }) )
+      }
+      catch( err ){
+        logger.warn(`[socketio-transport] emit failed: ${( err as Error ).message}`)
+        done({ acked: false, via: 'timeout' })
+      }
+    } )
+  }
+
+  // ── Inbound + status subscriptions ───────────────────────────
+
+  onInbound( handler: ( env: InboundEnvelope ) => void ): () => void {
+    this._inboundHandlers.add( handler )
+    return () => { this._inboundHandlers.delete( handler ) }
+  }
+
+  onStatus( handler: ( s: TransportStatus ) => void ): () => void {
+    this._statusHandlers.add( handler )
+    return () => { this._statusHandlers.delete( handler ) }
+  }
+
+  close(): void {
+    try { this._socket?.disconnect() } catch { /* ignore */ }
+    this._socket = null
+    this._connecting = null
+    this._inboundHandlers.clear()
+    this._statusHandlers.clear()
+  }
+
+  // ── Internal ─────────────────────────────────────────────────
+
+  private async _ensureSocket(): Promise<SocketLike | null> {
+    if( this._socket ) return this._socket
+    if( !this._connecting ) this._connecting = this._connect()
+    return this._connecting
+  }
+
+  private async _connect(): Promise<SocketLike | null> {
+    try {
+      const socket = this._opts.socketFactory
+        ? await this._opts.socketFactory( this._opts.url, { auth: { willId: this._opts.willId, token: this._opts.token } } )
+        : await this._defaultFactory()
+
+      this._wire( socket )
+      this._socket = socket
+      return socket
+    }
+    catch( err ){
+      logger.error(`[socketio-transport] connect failed: ${( err as Error ).message}`)
+      this._connecting = null   // allow a later retry
+      return null
+    }
+  }
+
+  private async _defaultFactory(): Promise<SocketLike> {
+    // Indirect the specifier so the type checker does not require the optional
+    // dependency to be installed for the core package to build.
+    const spec = 'socket.io-client'
+    const mod  = await import( /* @vite-ignore */ spec ) as any
+    const io   = mod.io ?? mod.default ?? mod
+    return io( this._opts.url, {
+      auth:       { willId: this._opts.willId, token: this._opts.token },
+      transports: ['websocket'],
+    } ) as SocketLike
+  }
+
+  /** Attach socket.io event handlers that feed the inbound + status streams. */
+  private _wire( socket: SocketLike ): void {
+    socket.on( 'connect',    () => this._notifyStatus( 'connected' ) )
+    socket.on( 'disconnect', () => this._notifyStatus( 'disconnected' ) )
+    socket.on( 'reconnect_attempt', () => this._notifyStatus( 'reconnecting' ) )
+
+    // Primary inbound channel — already-typed envelopes from the peer.
+    socket.on( 'envelope', ( env: InboundEnvelope ) => this._emitInbound( env ) )
+
+    // Discrete ack events (Section 2): in case the peer emits acks independently
+    // rather than via the emit() callback. Synthesized into ack envelopes; the
+    // AckReconciler (Section 3) dedups against the callback path by correlationId.
+    socket.on( 'message.delivered', ( m: { correlationId: string; delivered?: boolean } ) =>
+      this._emitInbound( this._deliveryAck( m.correlationId, m.delivered ?? true ) ) )
+
+    socket.on( 'effector.invoked.ack', ( m: { correlationId: string; result: AckEnvelope['result'] } ) =>
+      this._emitInbound( this._resultAck( m.correlationId, m.result ) ) )
+  }
+
+  private _emitInbound( env: InboundEnvelope ): void {
+    for( const h of this._inboundHandlers ){
+      try { h( env ) }
+      catch( err ){ logger.error(`[socketio-transport] inbound handler error: ${( err as Error ).message}`) }
+    }
+  }
+
+  private _notifyStatus( status: TransportStatus ): void {
+    for( const h of this._statusHandlers ){
+      try { h( status ) }
+      catch { /* ignore */ }
+    }
+  }
+
+  private _deliveryAck( correlationId: string, delivered: boolean ): AckEnvelope {
+    return { channel: 'ack', ackKind: 'delivery', delivered, willId: this._opts.willId, correlationId, seq: 0, wallTime: wallClock() }
+  }
+
+  private _resultAck( correlationId: string, result: AckEnvelope['result'] ): AckEnvelope {
+    return { channel: 'ack', ackKind: 'result', result, willId: this._opts.willId, correlationId, seq: 0, wallTime: wallClock() }
+  }
+}