@mindot/will 0.1.0

package/src/core/clock.ts

@@ -0,0 +1,196 @@
+// ─────────────────────────────────────────────────────────────
+// src/core/clock.ts
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Core simulation clock — completely generic.
+ * No time-of-day, calendar, or domain-specific logic.
+ * Time is just milliseconds since epoch.
+ */
+
+import type { Duration, Tick, Timestamp } from '#core/types'
+import { wallClock } from '#core/wall.clock'
+
+export interface SimulationClock {
+  readonly now: Timestamp
+  readonly currentTick: Tick
+  readonly delta: Duration
+  readonly isRunning: boolean
+  readonly multiplier: number
+
+  // Driven externally by the Orchestrator
+  tick(): void
+
+  // Lifecycle
+  pause(): void
+  resume(): void
+  reset(): void
+
+  // Time manipulation
+  setTime( time: Timestamp ): void
+  setTick( tick: Tick ): void
+  setMultiplier( newMultiplier: number ): void
+
+  // Helpers
+  toSimMs( wallMs: number ): number
+  toWallMs( simMs: number ): number
+  simSleep( simMs: number ): Promise<void>
+}
+
+export interface ClockConfig {
+  startTime?: Timestamp
+  startTick?: Tick
+  timeScale?: number  // 1.0 = real-time, 2.0 = 2× real-time
+  /** When set, tick() uses this fixed duration (ms) instead of wall time. */
+  fixedDeltaMs?: number
+}
+
+export class DefaultSimulationClock implements SimulationClock {
+  private _now: Timestamp
+  private _tick: Tick
+  private _delta: Duration = 0
+  private _lastTick: Timestamp
+  private _isRunning = true
+  private _timeScale: number
+  private _pausedAt: Timestamp | null = null
+  private _fixedDeltaMs: number | null = null
+
+  // Anchors for accurate now() under dynamic multiplier
+  private _startWallMs: Timestamp
+  private _startSimMs: Timestamp
+
+  constructor( config: ClockConfig = {} ){
+    this._now = config.startTime ?? wallClock()
+    this._tick = config.startTick ?? 0
+    this._lastTick = this._now
+    this._timeScale = config.timeScale ?? 1.0
+    this._fixedDeltaMs = config.fixedDeltaMs ?? null
+
+    this._startWallMs = wallClock()
+    this._startSimMs = this._now
+  }
+
+  // ── Getters ─────────────────────────────────────────────
+
+  get now(): Timestamp {
+    // Deterministic mode: time only advances inside tick(); never read wall
+    // time, so SimulationState.time reproduces exactly on replay (R2).
+    if( this._fixedDeltaMs !== null ) return this._now
+
+    if( !this._isRunning ) return this._now
+
+    const wallElapsed = wallClock() - this._startWallMs
+    return this._startSimMs + wallElapsed * this._timeScale
+  }
+
+  get currentTick(): Tick { return this._tick }
+  get delta(): Duration   { return this._delta }
+  get isRunning(): boolean { return this._isRunning }
+  get multiplier(): number { return this._timeScale }
+
+  // ── Core tick ───────────────────────────────────────────
+
+  /**
+   * The Orchestrator calls this once per tick as the single 
+   * source of tick advancement.
+   */
+  tick(): void {
+    if( !this._isRunning ) return
+
+    // Deterministic mode: advance by a fixed sim delta, never reading wall
+    // time. This is what makes the tick→time mapping reproducible on replay (R2).
+    if( this._fixedDeltaMs !== null ){
+      this._delta = this._fixedDeltaMs * this._timeScale
+      this._now  += this._delta
+      this._tick += 1
+      return
+    }
+
+    const
+    realNow     = wallClock(),
+    realDelta   = realNow - this._lastTick,
+    scaledDelta = realDelta * this._timeScale
+
+    this._delta    = scaledDelta
+    this._now      = this.now
+    this._tick    += 1
+    this._lastTick = realNow
+  }
+
+  // ── Lifecycle ───────────────────────────────────────────
+
+  pause(): void {
+    if( !this._isRunning ) return
+
+    this._isRunning = false
+    this._pausedAt  = wallClock()
+  }
+
+  resume(): void {
+    if( this._isRunning ) return
+
+    this._isRunning = true
+
+    if( this._pausedAt !== null ){
+      const pauseDuration = wallClock() - this._pausedAt
+
+      // Shift anchors to compensate for pause — maintains continuous time
+      this._startWallMs += pauseDuration
+      this._lastTick     = wallClock() - ( this._pausedAt - this._lastTick )
+      this._pausedAt     = null
+    }
+  }
+
+  reset(): void {
+    const now = wallClock()
+
+    this._now         = now
+    this._tick        = 0
+    this._delta       = 0
+    this._lastTick    = now
+    this._isRunning   = true
+    this._pausedAt    = null
+    this._startWallMs = now
+    this._startSimMs  = now
+  }
+
+  // ── Time manipulation ───────────────────────────────────
+
+  setTime( time: Timestamp ): void {
+    this._now          = time
+    this._startSimMs   = time
+    this._startWallMs  = wallClock()
+    this._lastTick     = this._startWallMs
+  }
+
+  setTick( tick: Tick ): void {
+    this._tick = tick
+  }
+
+  setMultiplier( newMultiplier: number ): void {
+    if( newMultiplier <= 0 )
+      throw new Error('Multiplier must be positive')
+
+    // Re-anchor current sim time to prevent jumps
+    const simNow = this.now
+
+    this._startSimMs   = simNow
+    this._startWallMs  = wallClock()
+    this._timeScale    = newMultiplier
+  }
+
+  // ── Helpers ─────────────────────────────────────────────
+
+  toSimMs( wallMs: number ): number {
+    return wallMs * this._timeScale
+  }
+
+  toWallMs( simMs: number ): number {
+    return simMs / this._timeScale
+  }
+
+  async simSleep( simMs: number ): Promise<void> {
+    const wallMs = this.toWallMs( simMs )
+    return new Promise( resolve => setTimeout( resolve, wallMs ) )
+  }
+}

package/src/core/completion.recorder.ts

@@ -0,0 +1,122 @@
+// ─────────────────────────────────────────────────────────────
+// src/core/completion.recorder.ts
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * LLM completion record/replay seam.
+ *
+ * The LLM is an external, non-deterministic oracle: to re-run a session
+ * deterministically (REORIENT R2) the recorder captures each completion's full
+ * input (model, params, prompt) and output, and on replay a *source* re-feeds
+ * those recorded completions instead of re-calling the model. This module is
+ * both halves of that seam — the capture sink (R2-b) and the re-feed source
+ * (R2-c). Both registries are keyed by willId so each Will routes to its own
+ * recorder/source (unlike the process-global token tracker — see REORIENT R4).
+ */
+
+import type { Tick, Timestamp } from '#core/types'
+
+export interface LLMCompletionRecord {
+  tick: Tick
+  willId: string
+  provider: string
+  model: string
+  maxOutputTokens: number
+  systemPrompt: string
+  userMessage: string
+  text: string
+  inputTok: number
+  outputTok: number
+  /** True when produced by the deterministic mock path (no API call). */
+  mock: boolean
+  latencyMs: number
+  timestamp: Timestamp
+}
+
+export interface LLMCompletionSink {
+  recordCompletion( record: LLMCompletionRecord ): void
+}
+
+const _sinks = new Map<string, LLMCompletionSink>()
+
+export function setCompletionRecorder( willId: string, sink: LLMCompletionSink ): void {
+  _sinks.set( willId, sink )
+}
+
+export function clearCompletionRecorder( willId: string ): void {
+  _sinks.delete( willId )
+}
+
+export function getCompletionRecorder( willId: string ): LLMCompletionSink | undefined {
+  return _sinks.get( willId )
+}
+
+// ── Replay re-feed source (R2-c) ─────────────────────────────
+
+/**
+ * Supplies recorded completions back to the LLM director during replay. A
+ * registered source short-circuits the live API call: the director returns the
+ * recorded output instead of re-invoking the non-deterministic model. Returning
+ * `undefined` means "no recorded completion — fall through to a live call"; a
+ * strict source (see RecordedCompletionSource) instead throws on a miss so a
+ * replay can never silently diverge.
+ */
+export interface LLMCompletionSource {
+  nextCompletion(
+    tick: number,
+    systemPrompt: string,
+    userMessage: string,
+  ): LLMCompletionRecord | undefined
+}
+
+/**
+ * Strict re-feed source backed by an array of recorded completions. Matches by
+ * tick, then by BYTE-IDENTICAL PROMPT within the tick — order-independent.
+ *
+ * Why prompt-keyed, not FIFO: concurrent LLM chains (the master executive and
+ * a deliberation facet) can ISSUE their same-tick calls in either order — that
+ * interleaving is scheduler timing, not seed-pinned state, so it may flip
+ * between the recording run and the replay run. Positional matching mispairs
+ * at the first flip and reports a phantom "prompt diverged". Keying each call
+ * to its own record by exact prompt makes the pairing insensitive to issue
+ * order while remaining strict: the prompts themselves are pure functions of
+ * deterministic state, so a real divergence still has no matching record and
+ * throws. Identical duplicate prompts within a tick consume FIFO.
+ */
+export class RecordedCompletionSource implements LLMCompletionSource {
+  private _byTick = new Map<number, LLMCompletionRecord[]>()
+
+  constructor( completions: readonly LLMCompletionRecord[] ){
+    for( const c of completions ){
+      const queue = this._byTick.get( c.tick )
+      if( queue ) queue.push( c )
+      else this._byTick.set( c.tick, [ c ] )
+    }
+  }
+
+  nextCompletion( tick: number, systemPrompt: string, userMessage: string ): LLMCompletionRecord {
+    const queue = this._byTick.get( tick )
+    if( !queue || queue.length === 0 )
+      throw new Error( `replay: no recorded LLM completion for tick ${tick} (recording is incomplete or call timing diverged)` )
+
+    const idx = queue.findIndex( r => r.systemPrompt === systemPrompt && r.userMessage === userMessage )
+    if( idx === -1 )
+      throw new Error( `replay: LLM prompt diverged at tick ${tick} — no recorded completion matches this call (upstream non-determinism)` )
+
+    return queue.splice( idx, 1 )[ 0 ]!
+  }
+}
+
+const _sources = new Map<string, LLMCompletionSource>()
+
+export function setCompletionSource( willId: string, source: LLMCompletionSource ): void {
+  _sources.set( willId, source )
+}
+
+export function clearCompletionSource( willId: string ): void {
+  _sources.delete( willId )
+}
+
+export function getCompletionSource( willId: string ): LLMCompletionSource | undefined {
+  return _sources.get( willId )
+}

package/src/core/conflict.detector.ts

@@ -0,0 +1,140 @@
+// ─────────────────────────────────────────────────────────────
+// src/core/conflict.detector.ts
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Validates async engine reasoning footprints against current state.
+ * Detects read-after-write and write-after-write conflicts that occur
+ * when an engine reasons on a stale snapshot while the world advances.
+ */
+
+import type {
+  ReasoningFootprint,
+  ConflictReport,
+  ConflictResolution,
+  ConflictStrategy,
+  ReadonlySimulationState,
+  StateCommands,
+} from '#core/types'
+
+export class ConflictDetector {
+  /**
+   * Check a reasoning footprint against the current state snapshot.
+   * Returns a detailed conflict report.
+   */
+  detect(
+    footprint: ReasoningFootprint,
+    currentState: ReadonlySimulationState
+  ): ConflictReport {
+    const
+    readConflicts:  string[] = [],
+    writeConflicts: string[] = []
+
+    // Read conflicts: entities the engine observed have been modified
+    // since the footprint was taken. Compare the entity's last-write tick
+    // against `tickObserved` (both are sim ticks). Entities without a tick
+    // stamp (e.g. restored from a snapshot) cannot be proven stale → skip.
+    for( const id of footprint.entitiesRead ){
+      const entity = currentState.entities.get( id )
+      const modifiedAtTick = entity?.updatedAtTick
+      if( entity && modifiedAtTick !== undefined && modifiedAtTick > footprint.tickObserved )
+        readConflicts.push(`Entity '${id}' modified at tick ${modifiedAtTick} (observed at tick ${footprint.tickObserved})`)
+    }
+
+    // Write conflicts: entities the engine wants to modify were modified by others
+    for( const id of footprint.entitiesModified ){
+      const entity = currentState.entities.get( id )
+      const modifiedAtTick = entity?.updatedAtTick
+      if( entity && modifiedAtTick !== undefined && modifiedAtTick > footprint.tickObserved )
+        writeConflicts.push(`Write conflict on '${id}': modified at tick ${modifiedAtTick} (observed at tick ${footprint.tickObserved})`)
+    }
+
+    return {
+      hasConflicts: readConflicts.length > 0 || writeConflicts.length > 0,
+      readConflicts,
+      writeConflicts,
+      detectedAtTick: currentState.tick,
+      footprint,
+    }
+  }
+
+  /**
+   * Resolve conflicts using the specified strategy.
+   */
+  resolve(
+    report: ConflictReport,
+    strategy: ConflictStrategy = 'REJECT'
+  ): ConflictResolution {
+    switch( strategy ){
+      case 'FORCE':
+        return {
+          strategy: 'FORCE',
+          resolvedCommands: report.footprint.intendedCommands,
+          shouldRerun: false,
+          reason: 'FORCE: applied despite conflicts',
+        }
+
+      case 'MERGE':
+        return this._merge( report )
+
+      case 'REJECT':
+      default:
+        return {
+          strategy: 'REJECT',
+          resolvedCommands: null,
+          shouldRerun: true,
+          reason: `REJECT: ${report.readConflicts.length} read conflicts, ${report.writeConflicts.length} write conflicts`,
+        }
+    }
+  }
+
+  /**
+   * Attempt to apply a non-conflicting subset of commands.
+   * Only includes entity sets and metric sets that don't touch conflicted entities.
+   */
+  private _merge( report: ConflictReport ): ConflictResolution {
+    if( !report.hasConflicts )
+      return {
+        strategy: 'MERGE',
+        resolvedCommands: report.footprint.intendedCommands,
+        shouldRerun: false,
+        reason: 'MERGE: no conflicts detected, full commit',
+      }
+
+    const
+    footprint = report.footprint,
+    original   = footprint.intendedCommands,
+    conflictedIds = new Set<string>()
+
+    // Collect all conflicted entity IDs from write conflict messages
+    for( const msg of report.writeConflicts ){
+      const match = msg.match( /Write conflict on '([^']+)'/ )
+      match && conflictedIds.add( match[1]! )
+    }
+
+    const merged: StateCommands = {}
+
+    // Only include entity sets that don't touch conflicted entities
+    if( original.set )
+      merged.set = original.set.filter( e => !conflictedIds.has( e.id ) )
+
+    // Only include deletes that don't touch conflicted entities
+    if( original.delete )
+      merged.delete = original.delete.filter( id => !conflictedIds.has( id ) )
+
+    // Metrics are always safe to apply (no entity-level conflicts)
+    if( original.metrics )
+      merged.metrics = [ ...original.metrics ]
+
+    const
+    appliedCount   = ( merged.set?.length ?? 0 ) + ( merged.delete?.length ?? 0 ),
+    rejectedCount  = conflictedIds.size
+
+    return {
+      strategy: 'MERGE',
+      resolvedCommands: merged,
+      shouldRerun: rejectedCount > 0,
+      reason: `MERGE: applied ${appliedCount} operations, rejected ${rejectedCount} conflicts`,
+    }
+  }
+}