@mindot/will 0.1.0

package/src/core/event.bus.ts

@@ -0,0 +1,292 @@
+// ─────────────────────────────────────────────────────────────
+// src/core/event.bus.ts
+// ─────────────────────────────────────────────────────────────
+
+import type { SimulationEvent, SimulationEventBase, SimulationContext, Tick, Timestamp } from '#core/types'
+import { wallClock } from '#core/wall.clock'
+
+export type EventHandler<T = unknown> = ( event: SimulationEvent<T>, context: SimulationContext ) => void | Promise<void>
+export type EventFilter = ( event: SimulationEventBase ) => boolean
+
+export interface EventBus {
+  /**
+   * Enqueue an event for dispatch at end of the current tick.
+   * Prevents silent corruption from events stamped with tick 0. 
+   * Callers must explicitly pass the current tick from the orchestrator.
+   */
+  publish<T>(
+    event: Omit<SimulationEvent<T>, 'id' | 'timestamp' | 'tick'>,
+    context: SimulationContext,
+    tick: Tick
+  ): void
+
+  /**
+   * Enqueue and immediately flush if the queue is below the sync threshold.
+   * Useful outside of a managed tick loop.
+   */
+  publishAsync<T>(
+    event: Omit<SimulationEvent<T>, 'id' | 'timestamp' | 'tick'>,
+    context: SimulationContext,
+    tick: Tick
+  ): Promise<void>
+
+  /**
+   * Schedule an event to be injected into the pending queue at a future tick.
+   * The Orchestrator calls prepareTick() each tick to drain due events.
+   */
+  scheduleAt<T>(
+    scheduledTick: Tick,
+    event: Omit<SimulationEvent<T>, 'id' | 'timestamp' | 'tick'>,
+    context: SimulationContext
+  ): void
+
+  /**
+   * Move all scheduled events whose tick ≤ currentTick into the pending queue.
+   * Called by the Orchestrator at the start of each tick, before engines run.
+   */
+  prepareTick( currentTick: Tick ): void
+
+  /**
+   * Drain and dispatch all pending events synchronously (within the current
+   * async frame).  Called by the Orchestrator at end of each tick, after all
+   * commands have been applied.
+   */
+  flush(): Promise<void>
+
+  subscribe<T>( eventType: string, handler: EventHandler<T> ): () => void
+  subscribeFiltered( filter: EventFilter, handler: EventHandler ): () => void
+  subscribeAll( handler: EventHandler ): () => void
+
+  clear(): void
+  getPendingCount(): number
+}
+
+export interface EventBusConfig {
+  maxQueueSize?: number
+  syncThreshold?: number
+  /**
+   * Sim-time source for event timestamps. Events land in the event log, so the
+   * timestamp must come from the sim clock (not wall time) for replay fidelity
+   * (R2). Defaults to `wallClock` for standalone/non-orchestrated use; the
+   * Simulation wires this to `clock.now`.
+   */
+  now?: () => Timestamp
+}
+
+// ── Internal types ───────────────────────────────────────────
+
+interface PendingEntry {
+  event: SimulationEvent
+  context: SimulationContext
+}
+
+interface ScheduledEntry {
+  tick: Tick
+  event: SimulationEvent
+  context: SimulationContext
+}
+
+// ── Implementation ───────────────────────────────────────────
+
+export class DefaultEventBus implements EventBus {
+  private _handlers         = new Map<string, Set<EventHandler>>()
+  private _filteredHandlers = new Map<EventFilter, Set<EventHandler>>()
+  private _allHandlers      = new Set<EventHandler>()
+  private _pendingEvents:   PendingEntry[] = []
+  private _scheduledEvents: ScheduledEntry[] = []  // sorted ascending by tick
+  private _isProcessing   = false
+  private _maxQueueSize: number
+  private _syncThreshold: number
+  private _now: () => Timestamp
+  // Monotonic event-id counter. Event ids land in the replay stream, so they
+  // must be deterministic across identical runs for byte-identical replay (R2);
+  // a per-bus counter incremented in publish/schedule order replaces randomUUID().
+  private _eventSeq = 0
+
+  constructor( config: EventBusConfig = {} ){
+    this._maxQueueSize  = config.maxQueueSize ?? 10000
+    this._syncThreshold = config.syncThreshold ?? 100
+    this._now           = config.now ?? wallClock
+  }
+
+  // ── Publish ─────────────────────────────────────────────
+
+  /**
+   * Events are always stamped with the caller-provided tick 
+   * to prevent default-to-zero bugs.
+   */
+  publish<T>(
+    event: Omit<SimulationEvent<T>, 'id' | 'timestamp' | 'tick'>,
+    context: SimulationContext,
+    tick: Tick
+  ): void {
+    const fullEvent = this._stamp<T>( event, tick )
+    this._enqueue( fullEvent, context )
+  }
+
+  async publishAsync<T>(
+    event: Omit<SimulationEvent<T>, 'id' | 'timestamp' | 'tick'>,
+    context: SimulationContext,
+    tick: Tick
+  ): Promise<void> {
+    const fullEvent = this._stamp<T>( event, tick )
+    this._enqueue( fullEvent, context )
+
+    this._pendingEvents.length <= this._syncThreshold && await this.flush()
+  }
+
+  private _stamp<T>(
+    event: Omit<SimulationEvent<T>, 'id' | 'timestamp' | 'tick'>,
+    tick: Tick
+  ): SimulationEvent<T> {
+    return {
+      ...event,
+      id:        `evt-${this._eventSeq++}`,
+      timestamp: this._now(),
+      tick,
+    } as SimulationEvent<T>
+  }
+
+  private _enqueue( event: SimulationEvent, context: SimulationContext ): void {
+    if( this._pendingEvents.length >= this._maxQueueSize )
+      throw new Error(`Event bus queue full (${this._maxQueueSize}). Dropping event: ${event.type}`)
+
+    this._pendingEvents.push({ event, context })
+
+    // Trigger async processing for standalone (non-orchestrated) use.
+    // When the Orchestrator is driving ticks it calls flush() explicitly;
+    // the setImmediate fires after that and finds an empty queue — no-op.
+    !this._isProcessing && setImmediate( () => { this._processBackground() } )
+  }
+
+  // ── Future-event priority queue ─────────────────────────
+
+  scheduleAt<T>(
+    scheduledTick: Tick,
+    event: Omit<SimulationEvent<T>, 'id' | 'timestamp' | 'tick'>,
+    context: SimulationContext
+  ): void {
+    const fullEvent: SimulationEvent<T> = {
+      ...event,
+      id:        `evt-${this._eventSeq++}`,
+      timestamp: this._now(),
+      tick:      scheduledTick,
+    } as SimulationEvent<T>
+
+    // Binary-search insertion to maintain ascending tick order — O(log n)
+    const entry: ScheduledEntry = { tick: scheduledTick, event: fullEvent, context }
+    let lo = 0, hi = this._scheduledEvents.length
+
+    while( lo < hi ){
+      const mid = ( lo + hi ) >>> 1
+      this._scheduledEvents[mid]!.tick <= scheduledTick ? lo = mid + 1 : hi = mid
+    }
+
+    this._scheduledEvents.splice( lo, 0, entry )
+  }
+
+  prepareTick( currentTick: Tick ): void {
+    // Find the first entry beyond the current tick — O(log n) scan
+    let i = 0
+    while( i < this._scheduledEvents.length && this._scheduledEvents[i]!.tick <= currentTick )
+      i++
+
+    if( i === 0 ) return
+
+    // Move due events into the pending queue (preserving scheduled tick)
+    const due = this._scheduledEvents.splice( 0, i )
+    for( const entry of due )
+      this._pendingEvents.push({ event: entry.event, context: entry.context })
+  }
+
+  // ── Flush ───────────────────────────────────────────────
+
+  async flush(): Promise<void> {
+    await this._process()
+  }
+
+  /**
+   * Background processing — triggered via setImmediate for standalone use.
+   * Silently swallows errors to avoid unhandled-rejection noise in that path.
+   */
+  private _processBackground(): void {
+    this._process().catch( () => {} )
+  }
+
+  private async _process(): Promise<void> {
+    if( this._isProcessing ) return
+    if( this._pendingEvents.length === 0 ) return
+
+    this._isProcessing = true
+
+    try {
+      // Loop so that events published by handlers in the same flush are
+      // dispatched before we yield back to the caller.
+      while( this._pendingEvents.length > 0 ){
+        const batch = this._pendingEvents.splice( 0 )
+        for( const { event, context } of batch )
+          await this._dispatch( event, context )
+      }
+    }
+    finally {
+      this._isProcessing = false
+    }
+  }
+
+  private async _dispatch( event: SimulationEvent, context: SimulationContext ): Promise<void> {
+    // Type-specific handlers
+    const handlers = this._handlers.get( event.type )
+    if( handlers )
+      for( const handler of handlers )
+        await handler( event, context )
+
+    // Filtered handlers
+    for( const [ filter, handlersSet ] of this._filteredHandlers )
+      filter( event ) && await Promise.all( [ ...handlersSet ].map( h => h( event, context ) ) )
+
+    // All-catch handlers
+    for( const handler of this._allHandlers )
+      await handler( event, context )
+  }
+
+  // ── Subscriptions ────────────────────────────────────────
+
+  subscribe<T>( eventType: string, handler: EventHandler<T> ): () => void {
+    !this._handlers.has( eventType ) && this._handlers.set( eventType, new Set() )
+    this._handlers.get( eventType )!.add( handler as EventHandler )
+
+    return () => {
+      this._handlers.get( eventType )?.delete( handler as EventHandler )
+      this._handlers.get( eventType )?.size === 0 && this._handlers.delete( eventType )
+    }
+  }
+
+  subscribeFiltered( filter: EventFilter, handler: EventHandler ): () => void {
+    !this._filteredHandlers.has( filter ) && this._filteredHandlers.set( filter, new Set() )
+    this._filteredHandlers.get( filter )!.add( handler )
+
+    return () => {
+      this._filteredHandlers.get( filter )?.delete( handler )
+      this._filteredHandlers.get( filter )?.size === 0 && this._filteredHandlers.delete( filter )
+    }
+  }
+
+  subscribeAll( handler: EventHandler ): () => void {
+    this._allHandlers.add( handler )
+    return () => { this._allHandlers.delete( handler ) }
+  }
+
+  // ── Housekeeping ─────────────────────────────────────────
+
+  clear(): void {
+    this._handlers.clear()
+    this._filteredHandlers.clear()
+    this._allHandlers.clear()
+    this._pendingEvents    = []
+    this._scheduledEvents  = []
+  }
+
+  getPendingCount(): number {
+    return this._pendingEvents.length
+  }
+}

package/src/core/inbound.recorder.ts

@@ -0,0 +1,100 @@
+// ─────────────────────────────────────────────────────────────
+// src/core/inbound.recorder.ts
+// ─────────────────────────────────────────────────────────────
+//
+// External-inbound record/replay seam (REORIENT R2, transport edition).
+//
+// The ExternalTransport is a non-deterministic input, exactly like the LLM:
+// to re-run a session deterministically the recorder must capture every inbound
+// envelope (messages, percepts, acks) at the tick it was applied. On replay a
+// *source* re-feeds those recorded envelopes instead of waiting on a live socket.
+//
+// This mirrors completion.recorder.ts: a capture sink (recordInbound) and a
+// re-feed source, both keyed by willId. Deterministic re-execution itself is
+// still deferred — this completes the capture half so it lands ready.
+//
+// `envelope` is `unknown` on purpose: this is `#core` and must not depend on the
+// `#stem` transport types. It round-trips as JSON.
+// ─────────────────────────────────────────────────────────────
+
+import type { Tick, Timestamp } from '#core/types'
+
+export interface InboundRecord {
+  tick:      Tick
+  willId:    string
+  /** The InboundEnvelope as applied (opaque here to avoid a #stem dependency). */
+  envelope:  unknown
+  timestamp: Timestamp
+}
+
+export interface InboundSink {
+  recordInbound( record: InboundRecord ): void
+}
+
+// ── Capture sink ─────────────────────────────────────────────
+
+const _sinks = new Map<string, InboundSink>()
+
+export function setInboundRecorder( willId: string, sink: InboundSink ): void {
+  _sinks.set( willId, sink )
+}
+
+export function clearInboundRecorder( willId: string ): void {
+  _sinks.delete( willId )
+}
+
+export function getInboundRecorder( willId: string ): InboundSink | undefined {
+  return _sinks.get( willId )
+}
+
+// ── Replay re-feed source (deferred re-execution) ────────────
+
+/**
+ * Supplies recorded inbound envelopes back during a deterministic re-execution
+ * replay, keyed by willId. Returns the envelopes recorded at `tick` (empty if
+ * none). Registered only while replaying; absent during live runs.
+ */
+export interface InboundSource {
+  envelopesAt( tick: Tick ): unknown[]
+}
+
+/**
+ * Re-feed source backed by recorded inbound. Groups envelopes by their applied
+ * tick (FIFO within a tick, preserving record order) and hands them back once.
+ * Unlike the LLM source, a tick with no recorded inbound is normal (most ticks),
+ * so a miss returns `[]` rather than throwing — only an upstream LLM/clock/PRNG
+ * divergence (caught by their own sources) can invalidate the replay.
+ */
+export class RecordedInboundSource implements InboundSource {
+  private readonly _byTick = new Map<Tick, unknown[]>()
+
+  constructor( records: readonly InboundRecord[] ){
+    for( const r of records ){
+      const queue = this._byTick.get( r.tick )
+      if( queue ) queue.push( r.envelope )
+      else this._byTick.set( r.tick, [ r.envelope ] )
+    }
+  }
+
+  envelopesAt( tick: Tick ): unknown[] {
+    const queue = this._byTick.get( tick )
+    if( !queue || queue.length === 0 ) return []
+    // Consume so a tick is never re-fed twice within one replay.
+    this._byTick.set( tick, [] )
+    return queue
+  }
+}
+
+const _sources = new Map<string, InboundSource>()
+
+export function setInboundSource( willId: string, source: InboundSource ): void {
+  _sources.set( willId, source )
+}
+
+export function clearInboundSource( willId: string ): void {
+  _sources.delete( willId )
+}
+
+export function getInboundSource( willId: string ): InboundSource | undefined {
+  return _sources.get( willId )
+}

package/src/core/index.ts

@@ -0,0 +1,167 @@
+// ─────────────────────────────────────────────────────────────
+// src/index.ts
+// ─────────────────────────────────────────────────────────────
+
+import { type ClockConfig, DefaultSimulationClock, type SimulationClock } from '#core/clock'
+import type { Coordinates, Duration, SimulationContext, SimulationEntity, SimulationEvent, SimulationEventBase, EventPayload, SimulationState, Tick, Timestamp, MinimalContext, RestoreOptions } from '#core/types'
+import { DefaultOrchestrator, type Orchestrator, type OrchestratorConfig, type SimulationEngine, type EngineResult } from '#core/orchestrator'
+import { DefaultEventBus, type EventBus, type EventBusConfig, type EventFilter, type EventHandler } from '#core/event.bus'
+import { DefaultScenario, type Scenario, type ScenarioConfig, type ScenarioValidationResult } from '#core/scenario'
+import { DefaultMetricCollector, type MetricCollector, type MetricPoint } from '#core/metrics'
+import { DefaultSimulation, type Simulation, type SimulationConfig } from '#core/simulation'
+import { DefaultStateManager, type StateManager } from '#core/state.manager'
+import { createContext, createPRNG } from '#core/utils'
+
+// New exports
+export {
+  DefaultSerializer,
+  DeltaEncoder,
+  type Serializer,
+  type SerializationConfig,
+  type SerializationFormat,
+  type SerializedState,
+  type SerializedEntity,
+  type DeltaSnapshot
+} from '#core/serialization'
+
+export {
+  DefaultPartitionRouter,
+  ConsistentHashRouter,
+  DistributedStateManager,
+  DistributedOrchestrator,
+  LocalTransport,
+  type DistributedNode,
+  type DistributedNodeConfig,
+  type ShardConfig,
+  type ShardStrategy,
+  type PartitionRouter,
+  type CrossShardTransport,
+  type CrossShardQuery,
+  type CrossShardResult,
+  type DistributedEvent,
+  type DeliveryGuarantee
+} from '#core/distributed'
+
+export {
+  DefaultReplayRecorder,
+  DefaultReplaySession,
+  ReplayManager,
+  type ReplayRecord,
+  type ReplayMetadata,
+  type ReplaySession,
+  type ReplayRecorder,
+  type ReplayConfig,
+  type ReplayComparison,
+  type ReplayDifference
+} from '#core/replay'
+
+export {
+  setCompletionRecorder,
+  clearCompletionRecorder,
+  getCompletionRecorder,
+  type LLMCompletionRecord,
+  type LLMCompletionSink
+} from '#core/completion.recorder'
+
+// Injectable diagnostic logger
+export {
+  logger,
+  setLogger,
+  resetLogger,
+  getLogger,
+  ConsoleLogger,
+  SilentLogger,
+  type Logger
+} from '#core/logger'
+
+// Core exports
+export {
+  DefaultSimulation,
+  type Simulation,
+  type SimulationConfig,
+}
+
+export {
+  DefaultSimulationClock,
+  type SimulationClock,
+  type ClockConfig
+}
+
+export {
+  DefaultEventBus,
+  type EventBus,
+  type EventBusConfig,
+  type EventHandler,
+  type EventFilter
+}
+
+export {
+  DefaultStateManager,
+  type StateManager
+}
+
+export {
+  DefaultOrchestrator,
+  type Orchestrator,
+  type OrchestratorConfig,
+  type SimulationEngine,
+  type EngineResult,
+}
+
+export {
+  DefaultScenario,
+  type Scenario,
+  type ScenarioConfig,
+  type ScenarioValidationResult
+}
+
+export {
+  DefaultMetricCollector,
+  type MetricCollector,
+  type MetricPoint
+}
+
+// Storage abstractions
+export {
+  BunStorageAdapter,
+  type StorageAdapter
+} from '#core/abstracts'
+
+// Utility functions
+export {
+  createContext,
+  createPRNG
+}
+
+// Types
+export type {
+  Timestamp,
+  Duration,
+  Tick,
+  Coordinates,
+  SimulationContext,
+  SimulationEntity,
+  SimulationEvent,
+  SimulationEventBase,
+  EventPayload,
+  SimulationState,
+  MinimalContext,
+  RestoreOptions
+}
+
+export {
+  AsyncEngine,
+} from '#core/async.engine'
+
+export {
+  ConflictDetector,
+} from '#core/conflict.detector'
+
+// In the types section, add:
+export type {
+  ReasoningFootprint,
+  ConflictReport,
+  ConflictResolution,
+  ConflictStrategy,
+  AsyncEngineConfig,
+} from '#core/types'

package/src/core/logger.ts

@@ -0,0 +1,85 @@
+// ─────────────────────────────────────────────────────────────
+// src/core/logger.ts
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Injectable diagnostic logger for the Will library.
+ *
+ * Will is embedded inside a host process (the API server, the dev runner,
+ * tests). A library has no business deciding where diagnostic output goes,
+ * so every internal `console.*` call routes through this seam instead. The
+ * host installs its own sink once at startup via `setLogger()`; everything
+ * downstream calls `logger.info()/warn()/error()/debug()` and never touches
+ * `console` directly.
+ *
+ * This is deliberately NOT the same thing as `SessionLogger` (stem/tracts),
+ * which writes the structured NDJSON cognitive event stream. This logger is
+ * for unstructured operational diagnostics — "rate limited, retrying",
+ * "S3 upload failed", "engine X skipped" — the lines that used to be
+ * `console.warn`.
+ *
+ * Default behaviour is identical to the previous direct `console.*` usage:
+ * `ConsoleLogger` forwards each level to the matching console method, so
+ * installing nothing changes nothing.
+ *
+ * Usage:
+ *   import { logger } from '#core/logger'
+ *   logger.warn('[LLMGate] rate limited — retrying')
+ *
+ *   // host, once at startup:
+ *   import { setLogger } from 'will'
+ *   setLogger(myStructuredLogger)
+ */
+
+export interface Logger {
+  debug( message?: unknown, ...args: unknown[] ): void
+  info ( message?: unknown, ...args: unknown[] ): void
+  warn ( message?: unknown, ...args: unknown[] ): void
+  error( message?: unknown, ...args: unknown[] ): void
+}
+
+/**
+ * Default sink: forwards to the global console. `debug` → console.debug,
+ * `info` → console.info (stdout, same channel as the old console.log calls),
+ * `warn`/`error` → their console equivalents (stderr). Behaviour matches the
+ * pre-refactor direct console usage exactly.
+ */
+export class ConsoleLogger implements Logger {
+  debug( message?: unknown, ...args: unknown[] ): void { console.debug( message, ...args ) }
+  info ( message?: unknown, ...args: unknown[] ): void { console.info ( message, ...args ) }
+  warn ( message?: unknown, ...args: unknown[] ): void { console.warn ( message, ...args ) }
+  error( message?: unknown, ...args: unknown[] ): void { console.error( message, ...args ) }
+}
+
+/**
+ * No-op sink — useful for tests or hosts that want Will to stay silent.
+ */
+export class SilentLogger implements Logger {
+  debug(): void {}
+  info (): void {}
+  warn (): void {}
+  error(): void {}
+}
+
+// Module-level current logger. Mutable so a host can swap it once at startup.
+let _logger: Logger = new ConsoleLogger()
+
+/**
+ * Stable indirection object. Callers import this and call `logger.info(...)`;
+ * `setLogger()` re-points the underlying sink without callers re-importing.
+ */
+export const logger: Logger = {
+  debug: ( message?: unknown, ...args: unknown[] ) => _logger.debug( message, ...args ),
+  info : ( message?: unknown, ...args: unknown[] ) => _logger.info ( message, ...args ),
+  warn : ( message?: unknown, ...args: unknown[] ) => _logger.warn ( message, ...args ),
+  error: ( message?: unknown, ...args: unknown[] ) => _logger.error( message, ...args ),
+}
+
+/** Install a custom sink for all subsequent Will diagnostic logging. */
+export function setLogger( next: Logger ): void { _logger = next }
+
+/** Reset to the default console sink. Primarily for tests. */
+export function resetLogger(): void { _logger = new ConsoleLogger() }
+
+/** The currently-installed sink (the real object, not the indirection). */
+export function getLogger(): Logger { return _logger }