@mindot/will 0.9.0 → 0.10.0

package/dist/mcp/effectors.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../../src/mcp/effectors.ts"],"names":[],"mappings":"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","file":"effectors.js","sourcesContent":["// ─────────────────────────────────────────────────────────────\n// src/mcp/effectors.ts — a Will EMPLOYING MCP tools (Seam 1)\n// ─────────────────────────────────────────────────────────────\n//\n// The other direction from server.ts: connect a Will to an external MCP server\n// and register that server's tools as the Will's own ABILITIES. Each tool\n// becomes a learnable affordance — its description (plus a compact hint of the\n// arguments it takes) is the ability's meaning, surfaced to the executive and\n// the deliberator; the WILL decides when to enact one (nothing here dispatches);\n// the tool's result feeds back through reafference, so the Will gets *skilled*\n// at the tools it uses.\n//\n// Arguments come from conscious intent: the executive supplies them via an\n// action's `args`, which ride the ideomotor leg into the invocation (see\n// executive commands.ts). A tool with required arguments enacted habitually\n// (without args) fails informatively — reafference then teaches the Will that\n// this ability wants deliberate articulation.\n//\n//   const { names, close } = await connectMcpEffectors( will, {\n//     command: 'npx', args: [ '-y', '@modelcontextprotocol/server-filesystem', '/tmp' ],\n//   } )\n//\n// Import from '@mindot/will/mcp' — kept off the main entry so non-MCP\n// consumers never load the MCP SDK.\n// ─────────────────────────────────────────────────────────────\n\nimport { Client } from '@modelcontextprotocol/sdk/client/index.js'\nimport { StdioClientTransport, getDefaultEnvironment } from '@modelcontextprotocol/sdk/client/stdio.js'\nimport { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'\nimport type { Will, EffectorHandler, EffectorResult } from '#sdk/will'\n\n/** Where the tools live: spawn a local server, reach a remote one, or bring a connected client. */\nexport type McpToolsSource =\n  | { command: string; args?: string[]; env?: Record<string, string> }\n  | { url: string }\n  | { client: Client }\n\nexport interface McpEffectorsOptions {\n  /** Intrinsic effort prior 0..1 seeded on every bridged ability (default 0.2). */\n  cost?: number\n  /** Prefix for the ability names (e.g. 'fs_') — avoids collisions across servers. */\n  prefix?: string\n}\n\n/** Minimal structural view of an MCP tool (the SDK's zod-inferred type, loosened). */\nexport interface McpToolInfo {\n  name:         string\n  description?: string\n  inputSchema?: {\n    type?:       string\n    properties?: Record<string, { type?: string; description?: string }>\n    required?:   string[]\n  }\n}\n\n/** Keep tool outcomes bounded — the description feeds reafference + episodic memory. */\nconst RESULT_DESCRIPTION_CAP = 700\n/** Keep ability meanings bounded — they render into the executive prompt. */\nconst MEANING_CAP = 300\n\n/**\n * The ability's *meaning*: the tool's description plus a compact hint of the\n * arguments it takes — so the executive knows what to supply in an action's\n * `args` when it enacts this ability.\n */\nexport function describeMcpTool( tool: McpToolInfo ): string {\n  const props    = tool.inputSchema?.properties ?? {}\n  const required = new Set( tool.inputSchema?.required ?? [] )\n  const argHints = Object.entries( props ).map( ( [ key, p ] ) =>\n    `${ key }${ required.has( key ) ? '' : '?' }${ p.description ? `: ${ p.description }` : '' }`)\n\n  const base = ( tool.description ?? `The ${ tool.name } tool.`).trim().replace( /\\s+/g, ' ')\n  const hint = argHints.length > 0 ? ` (args — ${ argHints.join('; ') })` : ''\n  const full = `${ base }${ hint }`\n  return full.length > MEANING_CAP ? `${ full.slice( 0, MEANING_CAP - 1 ) }…` : full\n}\n\n/**\n * The effector handler for one bridged tool: checks required args (an ability\n * enacted without its needed articulation fails informatively — reafference\n * learns from it), calls the tool, and maps the result onto EffectorResult.\n */\nexport function buildMcpHandler( client: Client, tool: McpToolInfo ): EffectorHandler {\n  return async ( args ): Promise<EffectorResult> => {\n    const props = tool.inputSchema?.properties\n    // Only pass keys the tool declares — invocation params can carry situation\n    // extras (targetEntityName, learned priors) the tool never asked for.\n    const filtered: Record<string, unknown> = {}\n    for( const [ k, v ] of Object.entries( args ?? {} ) )\n      if( !props || k in props ) filtered[ k ] = v\n\n    const missing = ( tool.inputSchema?.required ?? [] ).filter(\n      k => filtered[ k ] === undefined || filtered[ k ] === '')\n    if( missing.length > 0 )\n      return {\n        success: false,\n        description: `${ tool.name } needs ${ missing.join(', ') } — enact it deliberately, supplying them in the action's args.`,\n      }\n\n    try {\n      const res  = await client.callTool( { name: tool.name, arguments: filtered } ) as\n        { content?: Array<{ type: string; text?: string }>; isError?: boolean }\n      const text = ( res.content ?? [] )\n        .filter( c => c.type === 'text' && typeof c.text === 'string')\n        .map( c => c.text as string )\n        .join('\\n')\n        .trim() || ( res.isError ? 'The tool reported an error.' : 'Done (no output).')\n      const bounded = text.length > RESULT_DESCRIPTION_CAP ? `${ text.slice( 0, RESULT_DESCRIPTION_CAP - 1 ) }…` : text\n      return { success: !res.isError, description: bounded }\n    }\n    catch( err ){\n      return { success: false, description: `${ tool.name } failed: ${ err instanceof Error ? err.message : String( err ) }` }\n    }\n  }\n}\n\nasync function connect( source: McpToolsSource ): Promise<{ client: Client; owned: boolean }> {\n  if('client' in source ) return { client: source.client, owned: false }\n\n  const client = new Client( { name: 'mindot-will', version: '0' } )\n  if('url' in source )\n    await client.connect( new StreamableHTTPClientTransport( new URL( source.url ) ) )\n  else\n    await client.connect( new StdioClientTransport( {\n      command: source.command,\n      ...( source.args ? { args: source.args } : {} ),\n      // Merge over the SDK's safe default env so PATH etc. survive a custom env.\n      env: { ...getDefaultEnvironment(), ...( source.env ?? {} ) },\n    } ) )\n  return { client, owned: true }\n}\n\n/**\n * Register an MCP server's tools as the Will's abilities. Returns the ability\n * names registered and a `close()` for the connection (call it when the Will\n * stops; a client passed in via `source.client` is left open).\n */\nexport async function connectMcpEffectors(\n  will:   Will,\n  source: McpToolsSource,\n  opts:   McpEffectorsOptions = {},\n): Promise<{ names: string[]; close: () => Promise<void> }> {\n  const { client, owned } = await connect( source )\n  const { tools } = await client.listTools() as unknown as { tools: McpToolInfo[] }\n\n  const names: string[] = []\n  for( const tool of tools ){\n    const name = `${ opts.prefix ?? '' }${ tool.name }`\n    will.effector( name, {\n      description: describeMcpTool( tool ),\n      cost:        opts.cost ?? 0.2,\n      tags:        [ 'mcp' ],\n      handler:     buildMcpHandler( client, tool ),\n    } )\n    names.push( name )\n  }\n\n  return { names, close: async () => { if( owned ) await client.close() } }\n}\n"]}

package/src/extensions/livestream.ext.ts

@@ -1,570 +0,0 @@
-// ─────────────────────────────────────────────────────────────
-// src/extensions/live.ext.ts
-// ─────────────────────────────────────────────────────────────
-
-/**
- * Live streaming extension for dashboards, monitoring, and observability.
- * Layers on top of core — not part of the framework itself.
- * 
- * Provides WebSocket (full-duplex) and Server-Sent Events (unidirectional)
- * transports for real-time simulation state, metrics, and event streaming.
- */
-
-import { logger } from '#core/logger'
-import type { SimulationClock } from '#core/clock'
-import type { EventBus } from '#core/event.bus'
-import type { MetricCollector } from '#core/metrics'
-import type { Orchestrator } from '#core/orchestrator'
-import type { StateManager } from '#core/state.manager'
-import type {
-  SimulationContext,
-  SimulationEvent,
-  ReadonlySimulationState,
-  Tick,
-  Timestamp,
-} from '../core/types'
-
-// ── Transport-agnostic stream message ──────────────────────
-
-export interface StreamMessage {
-  type: 'snapshot' | 'tick-summary' | 'event' | 'metric-point' | 'log'
-  timestamp: Timestamp
-  tick: Tick
-  payload: unknown
-}
-
-export interface TickSummary {
-  tick: Tick
-  simTime: Timestamp
-  wallDuration: number       // ms this tick took
-  entityCount: number
-  metricCount: number
-  pendingEvents: number
-}
-
-// ── Stream transports ─────────────────────────────────────
-
-/**
- * Pluggable transport for live data.
- * Implementations: WebSocketStream, SSEStream, ConsoleStream, NoopStream
- */
-export interface LiveStreamTransport {
-  /** Push a single message to connected clients. */
-  send( message: StreamMessage ): void
-
-  /** Close all connections gracefully. */
-  close(): void
-
-  /** Called when the transport is registered with the extension. */
-  onRegister?(): void
-}
-
-// ── Configuration ─────────────────────────────────────────
-
-export interface LiveStreamConfig {
-  /** Emit full state snapshot every N ticks (0 = never) */
-  snapshotIntervalTicks?: number
-  /** Emit tick summary (entity count, latency) every N ticks (1 = every tick) */
-  tickSummaryIntervalTicks?: number
-  /** Forward all events from EventBus */
-  streamEvents?: boolean
-  /** Forward metric points */
-  streamMetrics?: boolean
-  /** Event types to exclude from streaming (e.g., verbose debug events) */
-  excludeEventTypes?: string[]
-  /** Maximum message queue depth before dropping (backpressure) */
-  maxQueueDepth?: number
-}
-
-// ── Extension implementation ──────────────────────────────
-
-/**
- * FIX 1: Instead of implementing TickMiddleware (which has a call-signature
- * constraint), we expose the handler as a property that matches the signature.
- * The class no longer `implements TickMiddleware` — it provides an `onTick`
- * arrow function that is structurally compatible and can be assigned to
- * orchestratorConfig.onAfterTick.
- */
-export class LiveStreamExtension {
-  private _transport: LiveStreamTransport
-  private _config: LiveStreamConfig
-  private _eventBus: EventBus
-  private _stateManager: StateManager
-  private _metricCollector?: MetricCollector
-  private _clock: SimulationClock
-  /** FIX 2: Use the concrete DefaultOrchestrator type which has tickLatencies. */
-  private _orchestrator: Orchestrator
-  private _getTickLatency: () => number
-
-  private _unsubscribeEventBus?: () => void
-  private _messageQueue: StreamMessage[] = []
-  private _maxQueueDepth: number
-  private _flushInterval: ReturnType<typeof setInterval> | null = null
-
-  constructor(
-    transport: LiveStreamTransport,
-    eventBus: EventBus,
-    stateManager: StateManager,
-    orchestrator: Orchestrator,
-    clock: SimulationClock,
-    config: LiveStreamConfig = {},
-    metricCollector?: MetricCollector
-  ){
-    this._transport = transport
-    this._eventBus = eventBus
-    this._stateManager = stateManager
-    this._orchestrator = orchestrator
-    this._clock = clock
-    this._metricCollector = metricCollector
-    this._config = {
-      snapshotIntervalTicks: config.snapshotIntervalTicks ?? 0,
-      tickSummaryIntervalTicks: config.tickSummaryIntervalTicks ?? 1,
-      streamEvents: config.streamEvents ?? true,
-      streamMetrics: config.streamMetrics ?? false,
-      excludeEventTypes: config.excludeEventTypes ?? [],
-      maxQueueDepth: config.maxQueueDepth ?? 1000,
-    }
-    this._maxQueueDepth = this._config.maxQueueDepth!
-
-    /**
-     * FIX 2: tickLatencies is only available on DefaultOrchestrator, not the
-     * Orchestrator interface. We probe for it and provide a fallback so the
-     * extension works with any orchestrator implementation.
-     */
-    const orchestratorAny = orchestrator as any
-    if( Array.isArray( orchestratorAny.tickLatencies ) ){
-      this._getTickLatency = () => {
-        const latencies = orchestratorAny.tickLatencies as number[]
-        return latencies.length > 0 ? ( latencies.at( -1 ) ?? 0 ) : 0
-      }
-    }
-    else {
-      this._getTickLatency = () => 0
-    }
-
-    // Wire transport lifecycle
-    transport.onRegister?.()
-  }
-
-  // ── Tick handler (assignable to OrchestratorConfig.onAfterTick) ──
-
-  /**
-   * Arrow function property — structurally matches the TickMiddleware
-   * call signature `(tick, time, state, context) => void | Promise<void>`.
-   * Assign this to orchestratorConfig.onAfterTick.
-   */
-  readonly onTick = (
-    tick: Tick,
-    _time: Timestamp,
-    state: ReadonlySimulationState,
-    _context: SimulationContext
-  ): void => {
-    // Tick summary
-    if(
-      this._config.tickSummaryIntervalTicks! > 0
-      && tick % this._config.tickSummaryIntervalTicks! === 0
-    ){
-      this._enqueue({
-        type: 'tick-summary',
-        timestamp: Date.now(),
-        tick,
-        payload: {
-          tick,
-          simTime: this._clock.now,
-          wallDuration: this._getTickLatency(),
-          entityCount: state.entities.size,
-          metricCount: state.metrics.size,
-          pendingEvents: this._eventBus.getPendingCount(),
-        } satisfies TickSummary,
-      })
-    }
-
-    // Full snapshot
-    if(
-      this._config.snapshotIntervalTicks! > 0
-      && tick % this._config.snapshotIntervalTicks! === 0
-    ){
-      this._enqueue({
-        type: 'snapshot',
-        timestamp: Date.now(),
-        tick,
-        payload: this._stateManager.snapshot(),
-      })
-    }
-  }
-
-  // ── Lifecycle ───────────────────────────────────────────
-
-  /** Start streaming. Must be called after construction. */
-  start(): void {
-    // Subscribe to event bus
-    if( this._config.streamEvents ){
-      this._unsubscribeEventBus = this._eventBus.subscribeAll( ( event, _ctx ) => {
-        if( this._config.excludeEventTypes?.includes( event.type ) ) return
-        this._enqueue({
-          type: 'event',
-          timestamp: Date.now(),
-          tick: event.tick,
-          payload: event,
-        })
-      })
-    }
-
-    // Periodic flush (handles metric streaming + drain)
-    this._flushInterval = setInterval( () => {
-      // Metric streaming can be wired here if MetricCollector exposes a
-      // per-point callback. Currently metrics flow through tick summaries.
-      this._drainQueue()
-    }, 50 ) // 20 fps flush rate
-  }
-
-  /** Stop streaming and close transport. */
-  stop(): void {
-    this._unsubscribeEventBus?.()
-    if( this._flushInterval ) clearInterval( this._flushInterval )
-    this._drainQueue()
-    this._transport.close()
-  }
-
-  // ── Backpressure handling ───────────────────────────────
-
-  private _enqueue( message: StreamMessage ): void {
-    if( this._messageQueue.length >= this._maxQueueDepth ){
-      // Drop oldest message (circular buffer semantics)
-      this._messageQueue.shift()
-      logger.warn(`[LiveStream] Queue full (${this._maxQueueDepth}), dropping oldest message`)
-    }
-
-    this._messageQueue.push( message )
-  }
-
-  private _drainQueue(): void {
-    while( this._messageQueue.length > 0 ){
-      const message = this._messageQueue.shift()!
-      try {
-        this._transport.send( message )
-      }
-      catch( error ){
-        logger.error('[LiveStream] Failed to send message, transport may be closed:', error )
-        // Stop trying — transport is dead
-        this._messageQueue.length = 0
-        break
-      }
-    }
-  }
-}
-
-// ── WebSocket transport (Bun-native) ──────────────────────
-
-export interface WebSocketConfig {
-  port: number
-  path?: string  // e.g., '/live'
-  maxConnections?: number
-}
-
-/**
- * FIX 3: Bun.serve().upgrade() requires an options object with `data`.
- * The third argument is not rest parameters — it's a single options bag.
- */
-export class WebSocketTransport implements LiveStreamTransport {
-  private _server: ReturnType<typeof Bun.serve> | null = null
-  private _clients: Set<{ send: ( data: string ) => void }> = new Set()
-  private _config: WebSocketConfig
-  private _maxConnections: number
-
-  constructor( config: WebSocketConfig ){
-    this._config = config
-    this._maxConnections = config.maxConnections ?? 100
-  }
-
-  send( message: StreamMessage ): void {
-    const data = JSON.stringify( message )
-
-    for( const client of this._clients )
-      client.send( data )
-  }
-
-  close(): void {
-    this._server?.stop()
-    this._clients.clear()
-  }
-
-  onRegister(): void {
-    this._server = Bun.serve({
-      port: this._config.port,
-      fetch: ( req, server ) => {
-        // Only upgrade on the configured path
-        const url = new URL( req.url )
-        if( this._config.path && url.pathname !== this._config.path )
-          return new Response('Not found', { status: 404 } )
-
-        // Connection limit
-        if( this._clients.size >= this._maxConnections )
-          return new Response('Too many connections', { status: 503 } )
-
-        // FIX 3: upgrade() requires { data } as second argument per Bun types
-        const upgraded = server.upgrade( req, { data: {} } )
-        if( !upgraded )
-          return new Response('WebSocket upgrade failed', { status: 400 } )
-
-        return undefined  // Bun handles the upgrade response
-      },
-      websocket: {
-        open: ( ws ) => {
-          this._clients.add( ws )
-          logger.info(`[WebSocket] Client connected (${this._clients.size} total)`)
-        },
-        close: ( ws ) => {
-          this._clients.delete( ws )
-          logger.info(`[WebSocket] Client disconnected (${this._clients.size} total)`)
-        },
-        message: ( _ws, _message ) => {
-          // Clients can send commands here (pause, resume, set speed, etc.)
-          // For now, read-only streaming
-        },
-      },
-    })
-
-    logger.info(`[WebSocket] Server listening on ws://localhost:${this._config.port}${this._config.path ?? '/'}`)
-  }
-}
-
-// ── Server-Sent Events transport ──────────────────────────
-
-export interface SSEConfig {
-  port: number
-  path?: string
-}
-
-/**
- * FIX 4 & 5: ReadableStreamDefaultController (from Bun.serve fetch) is not
- * a WritableStreamDefaultWriter. SSE uses a ReadableStream to push events
- * to the client. We need to store the controller and use controller.enqueue()
- * instead of writer.write().
- */
-export class SSETransport implements LiveStreamTransport {
-  private _server: ReturnType<typeof Bun.serve> | null = null
-  private _clients: Set<ReadableStreamDefaultController<Uint8Array>> = new Set()
-  private _config: SSEConfig
-  private _encoder = new TextEncoder()
-
-  constructor( config: SSEConfig ){
-    this._config = config
-  }
-
-  send( message: StreamMessage ): void {
-    const
-    eventLine = `event: ${message.type}\n`,
-    dataLine = `data: ${JSON.stringify( message )}\n\n`,
-    encoded = this._encoder.encode( eventLine + dataLine )
-
-    for( const controller of this._clients )
-      controller.enqueue( encoded )
-  }
-
-  close(): void {
-    this._server?.stop()
-    for( const controller of this._clients ){
-      try { controller.close() } catch {}
-    }
-    this._clients.clear()
-  }
-
-  onRegister(): void {
-    this._server = Bun.serve({
-      port: this._config.port,
-      fetch: async ( req ) => {
-        const url = new URL( req.url )
-        if( this._config.path && url.pathname !== this._config.path )
-          return new Response('Not found', { status: 404 } )
-
-        /**
-         * FIX 4 & 5: ReadableStream with start(controller) gives us a
-         * ReadableStreamDefaultController. We store the controller directly
-         * and use controller.enqueue() to push SSE data. The client's
-         * abort signal handles disconnection cleanup.
-         */
-        let streamController: ReadableStreamDefaultController<Uint8Array> | null = null
-
-        const stream = new ReadableStream<Uint8Array>({
-          start: ( controller ) => {
-            streamController = controller
-            this._clients.add( controller )
-
-            // Send initial comment to establish connection
-            controller.enqueue( this._encoder.encode(': connected\n\n') )
-
-            req.signal.addEventListener('abort', () => {
-              if( streamController ){
-                this._clients.delete( streamController )
-                logger.info(`[SSE] Client disconnected (${this._clients.size} total)`)
-                streamController = null
-              }
-            })
-          },
-          cancel: () => {
-            if( streamController ){
-              this._clients.delete( streamController )
-              streamController = null
-            }
-          },
-        })
-
-        return new Response( stream, {
-          headers: {
-            'Content-Type': 'text/event-stream',
-            'Cache-Control': 'no-cache',
-            'Connection': 'keep-alive',
-          },
-        })
-      },
-    })
-
-    logger.info(`[SSE] Server listening on http://localhost:${this._config.port}${this._config.path ?? '/'}`)
-  }
-}
-
-// ── Console transport (for development) ───────────────────
-
-export class ConsoleTransport implements LiveStreamTransport {
-  private _verbose: boolean
-
-  constructor( verbose: boolean = false ){
-    this._verbose = verbose
-  }
-
-  send( message: StreamMessage ): void {
-    if( !this._verbose && message.type === 'tick-summary'){
-      // Only log every 100 ticks for summary
-      const summary = message.payload as TickSummary
-      if( summary.tick % 100 === 0 ){
-        logger.info(
-          `[Live] Tick ${summary.tick}: ${summary.entityCount} entities, ${summary.wallDuration}ms`
-        )
-      }
-      return
-    }
-
-    logger.info(`[Live] ${message.type}:`, message.payload )
-  }
-
-  close(): void {
-    // No-op for console
-  }
-}
-
-// ── Factory helpers ───────────────────────────────────────
-
-export class LiveStreamFactory {
-  /**
-   * Create a WebSocket-backed live stream wired into a running simulation.
-   * Wire `stream.onTick` as `orchestratorConfig.onAfterTick`.
-   */
-  static createWebSocket(
-    sim: {
-      eventBus: EventBus
-      stateManager: StateManager
-      orchestrator: Orchestrator
-      clock: SimulationClock
-      metrics: MetricCollector
-    },
-    config: LiveStreamConfig & WebSocketConfig
-  ): LiveStreamExtension {
-    const transport = new WebSocketTransport({
-      port: config.port,
-      path: config.path,
-      maxConnections: config.maxConnections,
-    })
-
-    return new LiveStreamExtension(
-      transport,
-      sim.eventBus,
-      sim.stateManager,
-      sim.orchestrator,
-      sim.clock,
-      config,
-      sim.metrics
-    )
-  }
-
-  /**
-   * Create an SSE-backed live stream.
-   */
-  static createSSE(
-    sim: {
-      eventBus: EventBus
-      stateManager: StateManager
-      orchestrator: Orchestrator
-      clock: SimulationClock
-      metrics: MetricCollector
-    },
-    config: LiveStreamConfig & SSEConfig
-  ): LiveStreamExtension {
-    const transport = new SSETransport({
-      port: config.port,
-      path: config.path,
-    })
-
-    return new LiveStreamExtension(
-      transport,
-      sim.eventBus,
-      sim.stateManager,
-      sim.orchestrator,
-      sim.clock,
-      config,
-      sim.metrics
-    )
-  }
-
-  /**
-   * Quick console logger for development.
-   */
-  static createConsole(
-    sim: {
-      eventBus: EventBus
-      stateManager: StateManager
-      orchestrator: Orchestrator
-      clock: SimulationClock
-      metrics: MetricCollector
-    },
-    config: LiveStreamConfig = {}
-  ): LiveStreamExtension {
-    const transport = new ConsoleTransport()
-
-    return new LiveStreamExtension(
-      transport,
-      sim.eventBus,
-      sim.stateManager,
-      sim.orchestrator,
-      sim.clock,
-      config,
-      sim.metrics
-    )
-  }
-}
-
-// ── Usage example ─────────────────────────────────────────
-
-// import { DefaultSimulation } from '../core/simulation'
-// import { LiveStreamFactory } from './live.ext'
-//
-// const sim = new DefaultSimulation()
-// // ... load scenario, add engines ...
-//
-// const liveStream = LiveStreamFactory.createWebSocket( sim, {
-//   port: 8080,
-//   path: '/simulation-live',
-//   tickSummaryIntervalTicks: 1,
-//   streamEvents: true,
-//   snapshotIntervalTicks: 100,
-// })
-//
-// // Wire into orchestrator using updateConfig — works post-construction
-// const unsubLive = sim.orchestrator.onAfterTick( liveStream.onTick )
-//
-// // Later, remove one without affecting the other
-// unsubLive()
-//
-// liveStream.start()
-// await sim.run()
-// liveStream.stop()