@mindot/will 0.1.0

package/src/core/snapshot.manager.ts

@@ -0,0 +1,293 @@
+// ─────────────────────────────────────────────────────────────
+// src/core/snapshot.manager.ts
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * SnapshotManager — first-class state serialization for the simulation core.
+ * 
+ * Follows the same pattern as DefaultMetricCollector:
+ *   - Implements TickMiddleware via an onTick method
+ *   - Wired into DefaultSimulation via orchestratorConfig.onAfterTick
+ *   - Always active (configurable interval, not optional existence)
+ * 
+ * Responsibilities:
+ *   1. Serialize simulation state at configurable intervals
+ *   2. Compute deltas between snapshots
+ *   3. Feed the ReplayRecorder with structured tick data
+ *   4. Persist snapshots to disk
+ *   5. Provide restore points for StateManager.restore()
+ */
+
+import { logger } from '#core/logger'
+import type { Tick, ReadonlySimulationState, SimulationContext, SimulationState } from '#core/types'
+import type { Serializer, SerializedState, DeltaSnapshot } from '#core/serialization'
+import { BunStorageAdapter, type StorageAdapter } from '#core/abstracts'
+import { DefaultSerializer, DeltaEncoder } from '#core/serialization'
+import { wallClock } from '#core/wall.clock'
+
+export interface SnapshotManagerConfig {
+  /** How often to take full snapshots (ticks). 1 = every tick. */
+  snapshotInterval?: number
+  /** How often to persist to disk (ticks). 0 = never. */
+  persistInterval?: number
+  /** Base path for persisted snapshots */
+  persistPath?: string
+  /** Whether to compute deltas between snapshots */
+  computeDeltas?: boolean
+  /** Maximum in-memory snapshots to retain */
+  maxInMemorySnapshots?: number
+  /** Storage adapter */
+  storage?: StorageAdapter
+}
+
+export interface SnapshotEntry {
+  tick: Tick
+  state: SerializedState
+  delta?: DeltaSnapshot
+  timestamp: number
+}
+
+export class SnapshotManager {
+  private _serializer: Serializer
+  private _deltaEncoder: DeltaEncoder
+  private _config: Required<SnapshotManagerConfig>
+  private _storage: StorageAdapter
+
+  private _snapshots: SnapshotEntry[] = []
+  /**
+   * Deserialized form of the *immediately preceding* snapshot, kept as the
+   * baseline for the next delta. Caching the deserialized state (rather than a
+   * SerializedState) lets us encode the next delta without re-stringifying and
+   * re-deserializing the baseline every snapshot.
+   */
+  private _prevState?: SimulationState
+  private _ticksSinceSnapshot = 0
+  private _ticksSincePersist = 0
+  private _currentTick: Tick = 0
+
+  /** Callback for feeding replay recorder — set by DefaultSimulation */
+  onSnapshot?: ( tick: Tick, state: SerializedState, delta?: DeltaSnapshot ) => void
+
+  constructor( config: SnapshotManagerConfig = {} ){
+    this._serializer    = new DefaultSerializer({ includeChecksum: true, prettyPrint: false })
+    this._deltaEncoder  = new DeltaEncoder()
+    this._storage       = config.storage ?? new BunStorageAdapter()
+
+    this._config = {
+      snapshotInterval:     config.snapshotInterval     ?? 10,
+      persistInterval:      config.persistInterval      ?? 100,
+      persistPath:          config.persistPath          ?? './data/snapshots',
+      computeDeltas:        config.computeDeltas        ?? true,
+      maxInMemorySnapshots: config.maxInMemorySnapshots ?? 500,
+      storage:              this._storage,  // satisfies Required<>
+    }
+
+    this._config.persistInterval > 0
+    && this._storage.ensureDir?.( this._config.persistPath ).catch(() => {})
+  }
+
+  /**
+   * Implements the TickMiddleware signature.
+   * Wire this as orchestratorConfig.onAfterTick to enable state serialization.
+   * Follows the exact same pattern as DefaultMetricCollector.onTick.
+   */
+  onTick = ( tick: Tick, state: ReadonlySimulationState, _context: SimulationContext ): void => {
+    this._currentTick = tick
+    this._ticksSinceSnapshot++
+    this._ticksSincePersist++
+
+    // Take a snapshot at the configured interval
+    if( this._ticksSinceSnapshot < this._config.snapshotInterval ) return
+
+    this._ticksSinceSnapshot = 0
+
+    // Serialize current state
+    const serialized = this._serializer.serialize(
+      state as unknown as SimulationState,
+      'json'
+    ) as string
+
+    const parsed = JSON.parse( serialized ) as SerializedState
+
+    // Compute the delta against the *immediately preceding* snapshot (FN13).
+    // The previous code only advanced the baseline when `delta` was falsy
+    // (`if( !delta )`), which — after the very first snapshot — pinned the
+    // baseline to tick 0 forever: every later delta was computed against that
+    // one stale state, growing without bound and, once the tick-0 entry was
+    // evicted by the ring buffer, referencing a base that no longer existed.
+    // Now each delta describes a single interval of change against the prior
+    // snapshot, and the baseline advances every time.
+    let delta: DeltaSnapshot | undefined
+    let currState: SimulationState | undefined
+    if( this._config.computeDeltas ){
+      currState = this._serializer.deserialize( serialized )
+      if( this._prevState )
+        delta = this._deltaEncoder.encode( this._prevState, currState )
+    }
+
+    const entry: SnapshotEntry = {
+      tick,
+      state: parsed,
+      delta,
+      timestamp: wallClock(),
+    }
+
+    // Store in memory
+    this._snapshots.push( entry )
+    if( this._snapshots.length > this._config.maxInMemorySnapshots )
+      this._snapshots.shift()
+
+    // Advance the delta baseline on every snapshot so the next delta is
+    // computed against this one. Each stored entry also keeps the full
+    // serialized `state`, so it remains a self-contained keyframe for
+    // restore() even after its predecessor is evicted.
+    if( currState ) this._prevState = currState
+
+    // Feed external consumers (e.g., ReplayRecorder)
+    this.onSnapshot?.( tick, parsed, delta )
+
+    // Persist to disk
+    if( this._config.persistInterval > 0
+        && this._ticksSincePersist >= this._config.persistInterval ){
+      this._ticksSincePersist = 0
+      this._persistSnapshot( entry ).catch( err => {
+        logger.error(`[SnapshotManager] Persist failed at tick ${tick}:`, err )
+      })
+    }
+  }
+
+  // ── Query API ────────────────────────────────────────────
+
+  /**
+   * Retrieve a snapshot by tick.
+   */
+  getSnapshot( tick: Tick ): SerializedState | undefined {
+    return this._snapshots.find( s => s.tick === tick )?.state
+  }
+
+  /**
+   * Get all in-memory snapshots.
+   */
+  getAllSnapshots(): ReadonlyArray<SnapshotEntry> {
+    return this._snapshots
+  }
+
+  /**
+   * Get the most recent snapshot.
+   */
+  getLatestSnapshot(): SnapshotEntry | undefined {
+    return this._snapshots[ this._snapshots.length - 1 ]
+  }
+
+  /**
+   * Restore simulation state from a snapshot.
+   * Returns the deserialized state ready for StateManager.restore().
+   */
+  restoreState( tick: Tick ): SimulationState | undefined {
+    const snapshot = this.getSnapshot( tick )
+    if( !snapshot ) return undefined
+    return this._serializer.deserialize( JSON.stringify( snapshot ) )
+  }
+
+  /**
+   * Export all snapshots to a file.
+   */
+  async exportAll( path: string ): Promise<void> {
+    const output = {
+      snapshots: this._snapshots.map( s => ({
+        tick: s.tick,
+        state: s.state,
+        delta: s.delta,
+        timestamp: s.timestamp,
+      })),
+      exportedAt: wallClock(),
+    }
+    await this._storage.write( path, JSON.stringify( output ) )
+  }
+
+  /**
+   * Get the number of in-memory snapshots.
+   */
+  get snapshotCount(): number {
+    return this._snapshots.length
+  }
+
+  // ── Restore from storage ──────────────────────────────────
+
+  /**
+   * Load the most recently persisted snapshot from the storage adapter and
+   * deserialize it into a live SimulationState, ready for StateManager.restore().
+   *
+   * Returns undefined when no snapshot has been persisted yet (first boot).
+   *
+   * Works with any StorageAdapter — BunStorageAdapter (filesystem) or
+   * PostgresStorageAdapter (Postgres). The sentinel file `latest.json` is written
+   * alongside each snapshot so we can locate the most recent one without scanning.
+   */
+  async loadLatestFromStorage(): Promise<SimulationState | undefined> {
+    if( this._config.persistInterval === 0 ) return undefined
+
+    const sentinelPath = `${this._config.persistPath}/latest.json`
+    try {
+      const exists = await this._storage.exists( sentinelPath )
+      if( !exists ) return undefined
+
+      const raw     = await this._storage.read( sentinelPath )
+      const { path } = JSON.parse( raw ) as { path: string; tick: number }
+
+      const snapExists = await this._storage.exists( path )
+      if( !snapExists ) return undefined
+
+      const snapRaw = await this._storage.read( path )
+      const parsed  = JSON.parse( snapRaw ) as SerializedState
+      return this._serializer.deserialize( JSON.stringify( parsed ) )
+    }
+    catch( err ){
+      logger.warn( `[SnapshotManager] Could not load latest snapshot:`, err )
+      return undefined
+    }
+  }
+
+  /**
+   * Force an immediate snapshot of `state` and persist it to disk.
+   *
+   * Called at session end (pauseWill / archiveWill) to guarantee the latest
+   * simulation state — including freshly-flushed episodic memories — is
+   * written to disk even if the scheduled persist interval has not elapsed.
+   *
+   * Unlike the normal onTick path, this does NOT push an entry into the
+   * in-memory ring buffer (no replay entry needed for a shutdown snapshot)
+   * and does NOT advance the delta baseline (`_prevState`; no more ticks will follow).
+   *
+   * No-op when persistInterval === 0 (disk persistence disabled).
+   */
+  async persistNow( state: ReadonlySimulationState ): Promise<void> {
+    if( this._config.persistInterval === 0 ) return
+
+    const serialized = this._serializer.serialize(
+      state as unknown as SimulationState,
+      'json'
+    ) as string
+
+    const parsed = JSON.parse( serialized ) as SerializedState
+    const entry: SnapshotEntry = {
+      tick:      this._currentTick,
+      state:     parsed,
+      delta:     undefined,
+      timestamp: wallClock(),
+    }
+
+    await this._persistSnapshot( entry )
+  }
+
+  // ── Internal ─────────────────────────────────────────────
+
+  private async _persistSnapshot( entry: SnapshotEntry ): Promise<void> {
+    const path = `${this._config.persistPath}/snapshot-${String( entry.tick ).padStart( 8, '0')}.json`
+    await this._storage.write( path, JSON.stringify( entry.state ) )
+
+    // Write a sentinel so loadLatestFromStorage() can find this snapshot on restart.
+    const sentinelPath = `${this._config.persistPath}/latest.json`
+    await this._storage.write( sentinelPath, JSON.stringify({ path, tick: entry.tick }) )
+  }
+}

package/src/core/state.manager.ts

@@ -0,0 +1,283 @@
+// ─────────────────────────────────────────────────────────────
+// src/core/state.manager.ts
+// ─────────────────────────────────────────────────────────────
+
+import type { SimulationEntity, EntityInput, SimulationState, StateCommands, Tick, Timestamp, RestoreOptions } from '#core/types'
+import { deepFreeze } from '#core/utils'
+
+/**
+ * Whether entities are deep-frozen on write (R3). Enforcing the read-only
+ * contract at runtime costs a recursive freeze per write, so it is on
+ * everywhere *except* production — dev, test and CI catch any illegal mutation
+ * loudly, and production runs the exact code paths those caught. Override
+ * explicitly with `WILL_FREEZE_STATE` (`1`/`true` to force on, `0`/`false` off).
+ */
+function resolveFreezeState(): boolean {
+  const flag = process.env.WILL_FREEZE_STATE
+  if( flag !== undefined && flag !== '' )
+    return flag !== '0' && flag.toLowerCase() !== 'false'
+  return process.env.NODE_ENV !== 'production'
+}
+
+export interface StateManager {
+  readonly currentTick: Tick
+  readonly currentTime: Timestamp
+
+  updateClock( tick: Tick, time: Timestamp ): void
+
+  getEntity<T extends SimulationEntity>( id: string ): T | undefined
+  setEntity( entity: EntityInput ): void
+  deleteEntity( id: string ): boolean
+  getAllEntities(): IterableIterator<SimulationEntity>
+
+  /** O(1) — backed by an internal type index */
+  getEntitiesByType( type: string ): SimulationEntity[]
+
+  getMetric( key: string ): number | undefined
+  setMetric( key: string, value: number ): void
+  incrementMetric( key: string, delta?: number ): number
+
+  /**
+   * Apply a batch of commands atomically.
+   * Called by the Orchestrator after all engines have returned their
+   * EngineResult for a tick (double-buffer commit phase).
+   */
+  applyCommands( commands: StateCommands ): void
+
+  snapshot(): SimulationState
+  /**
+   * Accepts optional RestoreOptions for partial
+   * restore. Use { entities: true, metrics: false } to rewind entity
+   * state while preserving metric counters.
+   */
+  restore( snapshot: SimulationState, options?: RestoreOptions ): void
+  clear(): void
+}
+
+export class DefaultStateManager implements StateManager {
+  private _entities   = new Map<string, SimulationEntity>()
+  private _metrics    = new Map<string, number>()
+  private _typeIndex  = new Map<string, Set<string>>()  // type → entity ids
+  private _tick: Tick = 0
+  private _time: Timestamp = 0
+
+  /**
+   * Copy-on-write guard (R3-b / FIX F8). A handed-out snapshot shares the live
+   * `_entities` / `_metrics` map by reference instead of being eagerly copied;
+   * these flags mark a map as still observed by an outstanding snapshot. The
+   * NEXT mutation clones that map once (see _ownEntities / _ownMetrics) before
+   * writing, so the snapshot keeps its point-in-time values. This turns
+   * snapshot() into O(1) and collapses the per-tick double copy (pre- + post-
+   * commit) into a single clone on the first write — and zero clones on an
+   * idle tick or a read-only snapshot consumer. Entities are deep-frozen on
+   * write (R3-a), so sharing a reference can never leak a mutable value.
+   */
+  private _entitiesShared = false
+  private _metricsShared  = false
+
+  /**
+   * When true, every entity stored is deep-frozen so the read-only snapshot
+   * contract (R3) is enforced at runtime, not just in the type system.
+   * Resolved once per manager from the environment — see resolveFreezeState.
+   */
+  private readonly _freeze = resolveFreezeState()
+
+  get currentTick(): Tick      { return this._tick }
+  get currentTime(): Timestamp { return this._time }
+
+  updateClock( tick: Tick, time: Timestamp ): void {
+    this._tick = tick
+    this._time = time
+  }
+
+  // ── Entity CRUD ──────────────────────────────────────────
+
+  getEntity<T extends SimulationEntity>( id: string ): T | undefined {
+    return this._entities.get( id ) as T | undefined
+  }
+
+  setEntity( entity: EntityInput ): void {
+    const
+    existing = this._entities.get( entity.id ),
+    // Sim clock time (fed each tick by updateClock), NOT wall time — this is the
+    // single place every entity's createdAt/updatedAt is stamped, so sourcing it
+    // from the sim clock makes all entity timestamps deterministic on replay (R2).
+    now      = this._time
+
+    // Maintain type index — handle type changes
+    if( existing && existing.type !== entity.type )
+      this._typeIndex.get( existing.type )?.delete( entity.id )
+
+    if( !this._typeIndex.has( entity.type ) )
+      this._typeIndex.set( entity.type, new Set() )
+
+    this._typeIndex.get( entity.type )!.add( entity.id )
+
+    // A fresh object every write — setEntity never mutates an existing entity
+    // in place. Combined with the copy-on-write clone below, the live map only
+    // ever changes by slot replacement on a map no snapshot still observes.
+    const stored: SimulationEntity = {
+      ...entity,
+      createdAt:     existing?.createdAt ?? entity.createdAt ?? now,
+      updatedAt:     now,
+      updatedAtTick: this._tick,
+    }
+
+    // CoW: clone the map once if a snapshot still references it, so this write
+    // can't reach back and mutate that point-in-time view (R3-b / FIX F8).
+    this._ownEntities()
+
+    // Freeze so anything that later reads this entity (engine snapshots, stored
+    // rollback snapshots) cannot mutate it and silently corrupt determinism (R3).
+    this._entities.set( entity.id, this._freeze ? deepFreeze( stored ) : stored )
+  }
+
+  deleteEntity( id: string ): boolean {
+    const existing = this._entities.get( id )
+    if( !existing ) return false
+
+    this._typeIndex.get( existing.type )?.delete( id )
+    // CoW: clone before removing the slot so an outstanding snapshot still
+    // sees the entity (R3-b / FIX F8).
+    this._ownEntities()
+    return this._entities.delete( id )
+  }
+
+  getAllEntities(): IterableIterator<SimulationEntity> {
+    return this._entities.values()
+  }
+
+  getEntitiesByType( type: string ): SimulationEntity[] {
+    const ids = this._typeIndex.get( type )
+    if( !ids ) return []
+
+    const result: SimulationEntity[] = []
+    for( const id of ids ){
+      const entity = this._entities.get( id )
+      entity && result.push( entity )
+    }
+
+    return result
+  }
+
+  // ── Metrics ──────────────────────────────────────────────
+
+  getMetric( key: string ): number | undefined {
+    return this._metrics.get( key )
+  }
+
+  setMetric( key: string, value: number ): void {
+    this._ownMetrics()
+    this._metrics.set( key, value )
+  }
+
+  incrementMetric( key: string, delta: number = 1 ): number {
+    const next = ( this._metrics.get( key ) ?? 0 ) + delta
+    this._ownMetrics()
+    this._metrics.set( key, next )
+    return next
+  }
+
+  // ── Command application (double-buffer commit) ───────────
+
+  applyCommands( commands: StateCommands ): void {
+    if( commands.set )
+      for( const entity of commands.set )
+        this.setEntity( entity )
+
+    if( commands.delete )
+      for( const id of commands.delete )
+        this.deleteEntity( id )
+
+    if( commands.metrics )
+      for( const [ key, value ] of commands.metrics )
+        typeof value === 'number'
+          ? this.setMetric( key, value )
+          : this.incrementMetric( key, ( value as { delta: number } ).delta )
+  }
+
+  // ── Snapshot / restore ───────────────────────────────────
+
+  snapshot(): SimulationState {
+    // Copy-on-write (R3-b / FIX F8): hand out the live maps by reference and
+    // mark them shared instead of eagerly cloning. The next mutation clones
+    // before writing (_ownEntities / _ownMetrics), so this snapshot stays a
+    // genuine point-in-time view. Callers must treat it as read-only — the
+    // ReadonlySimulationState type enforces that for the per-tick consumers,
+    // and no code mutates a snapshot's maps directly.
+    this._entitiesShared = true
+    this._metricsShared  = true
+    return {
+      tick:     this._tick,
+      time:     this._time,
+      entities: this._entities,
+      metrics:  this._metrics,
+    }
+  }
+
+  /** CoW: clone `_entities` once if an outstanding snapshot still shares it. */
+  private _ownEntities(): void {
+    if( !this._entitiesShared ) return
+    this._entities = new Map( this._entities )
+    this._entitiesShared = false
+  }
+
+  /** CoW: clone `_metrics` once if an outstanding snapshot still shares it. */
+  private _ownMetrics(): void {
+    if( !this._metricsShared ) return
+    this._metrics = new Map( this._metrics )
+    this._metricsShared = false
+  }
+
+  /**
+   * Allows selective rollback of entities, metrics, or clock state.
+   * Default behavior (no options) is full restore — backward compatible.
+   */
+  restore( snapshot: SimulationState, options: RestoreOptions = {} ): void {
+    const restoreEntities = options.entities ?? true
+    const restoreMetrics  = options.metrics  ?? true
+    const restoreClock    = options.clock    ?? true
+
+    if( restoreClock ){
+      this._tick = snapshot.tick
+      this._time = snapshot.time
+    }
+
+    if( restoreEntities ){
+      // Fresh map the manager owns outright — clear any CoW share (R3-b).
+      this._entities = new Map( snapshot.entities )
+      this._entitiesShared = false
+
+      // Rebuild type index from restored entities
+      this._typeIndex.clear()
+      for( const entity of this._entities.values() ){
+        // Restored entities may be fresh (e.g. deserialized from disk) and thus
+        // unfrozen — re-establish the R3 immutability guarantee. Idempotent for
+        // entities that came from an already-frozen in-process snapshot.
+        if( this._freeze ) deepFreeze( entity )
+
+        if( !this._typeIndex.has( entity.type ) )
+          this._typeIndex.set( entity.type, new Set() )
+
+        this._typeIndex.get( entity.type )!.add( entity.id )
+      }
+    }
+
+    if( restoreMetrics ){
+      this._metrics = new Map( snapshot.metrics )
+      this._metricsShared = false
+    }
+  }
+
+  clear(): void {
+    // Replace (not .clear()) the maps: an outstanding snapshot may still share
+    // them under CoW, and emptying them in place would wipe that view (R3-b).
+    this._entities = new Map()
+    this._metrics  = new Map()
+    this._entitiesShared = false
+    this._metricsShared  = false
+    this._typeIndex.clear()
+    this._tick = 0
+    this._time = 0
+  }
+}