@mindot/will 0.1.0

package/src/cognition/faculties/moral.evaluator.ts

@@ -0,0 +1,437 @@
+// ─────────────────────────────────────────────────────────────
+// src/cognition/faculties/moral.evaluator.ts
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * MoralEvaluator — compares actions against internalized values and norms.
+ *
+ * Evaluates:
+ *   - Own actions against personal standards
+ *   - Others' actions against social norms
+ *   - Value alignment and violation
+ *   - Social comparison (am I better/worse than my standards?)
+ *
+ * Produces: guilt, shame, pride, indignation, disgust
+ *
+ * Guilt = "I did something bad" (action-focused, private)
+ * Shame = "I am bad" (self-focused, social exposure)
+ * Pride = "I did something good" (achievement against standards)
+ * Indignation = "They did something wrong" (moral anger at others)
+ * Disgust = "That violates a sacred value" (visceral moral rejection)
+ *
+ * Requires a value system — initialized with basic moral foundations
+ * and extensible through learning.
+ *
+ * Part of Shard 1 (Affective Layer) — runs every tick, synchronous.
+ */
+
+import type {
+  Duration,
+  Tick,
+  SimulationContext,
+  ReadonlySimulationState,
+  StateCommands,
+  SimulationEvent,
+} from '#core/types'
+import type { SimulationEngine, EngineResult, CognitiveEngine } from '#cognition/types'
+import type { CognitiveEventSchema } from '#cognition/schema.registry'
+import type { CognitiveEvent, CognitiveBus } from '#cognition/bus'
+import { GenerativeModel } from '#cognition/generative.model'
+import { readEffectiveParams } from '#cognition/persona.prior'
+
+export interface MoralEvaluatorConfig {
+  /** Moral foundations and their weights */
+  foundations?: Record<string, number>
+  /** Threshold for moral emotions to trigger events */
+  eventThreshold?: number
+  /** Rate at which moral emotions decay without re-trigger */
+  decayRate?: number
+  bus?: CognitiveBus
+}
+
+/**
+ * Moral Foundations Theory — six core dimensions.
+ * Each foundation has a care/harm and fairness/cheating polarity.
+ */
+interface MoralFoundation {
+  name: string
+  weight: number       // How much this foundation matters to the agent
+  threshold: number    // Sensitivity — how easily triggered
+}
+
+interface ValueViolation {
+  foundation: string
+  severity: number     // 0-1: how severe the violation
+  agent: 'self' | 'other'
+  keid: string
+}
+
+export class MoralEvaluator implements SimulationEngine, CognitiveEngine {
+  readonly name     = 'moral-evaluator'
+  
+  private _foundations: MoralFoundation[]
+  private _eventThreshold: number
+  private _decayRate: number
+
+  // Track own action history for guilt/pride evaluation
+  private _recentOwnActions: Array<{
+    action: string
+    outcome: string
+    tick: number
+    valueAlignment: Record<string, number>
+  }> = []
+
+  private _bus: CognitiveBus | null = null
+
+  private readonly _model    = new GenerativeModel()
+
+
+  constructor( config: MoralEvaluatorConfig = {} ){
+    this._bus = config.bus ?? null
+    const foundationWeights = config.foundations ?? {
+      care:      0.25,  // Harm/care — protection of vulnerable
+      fairness:  0.25,  // Cheating/fairness — proportional outcomes
+      loyalty:   0.15,  // Betrayal/loyalty — group commitment
+      authority: 0.10,  // Subversion/authority — respect for tradition/order
+      sanctity:  0.10,  // Degradation/sanctity — purity/disgust
+      liberty:   0.15,  // Oppression/liberty — freedom from domination
+    }
+
+    this._foundations = Object.entries( foundationWeights ).map( ([ name, weight ]) => ({
+      name,
+      weight: weight / Object.values( foundationWeights ).reduce( ( s, w ) => s + w, 0 ),
+      threshold: 0.3,
+    }))
+
+    this._eventThreshold = config.eventThreshold ?? 0.3
+    this._decayRate      = config.decayRate      ?? 0.02
+  }
+  attachBus( bus: CognitiveBus ): void { this._bus = bus }
+
+  // ── Engine interface ─────────────────────────────────────
+
+  private _readConfigFromState( state: ReadonlySimulationState ): void {
+    // Effective config = base engine-config-moral ⊕ persona-prior. Channel A: a
+    // conscientious Will develops a lower eventThreshold and so registers moral
+    // self-evaluations (guilt/shame/pride) more readily — the dutifulness facet.
+    const p = readEffectiveParams( state, 'engine-config-moral' )
+
+    if( p.eventThreshold != null ) this._eventThreshold = p.eventThreshold
+    if( p.decayRate != null ) this._decayRate = p.decayRate
+
+    // Update moral foundations from flat params. Keys map 1:1 to the six MFT
+    // foundations the engine tracks: the foundation is `sanctity` (carried by
+    // `foundationSanctity`, NOT `foundationPurity`), and `liberty` must be
+    // carried too — otherwise a state override silently drops both.
+    const foundationUpdates: Record<string, number | undefined> = {
+      care:      p.foundationCare,
+      fairness:  p.foundationFairness,
+      loyalty:   p.foundationLoyalty,
+      authority: p.foundationAuthority,
+      sanctity:  p.foundationSanctity,
+      liberty:   p.foundationLiberty,
+    }
+    let updated = false
+    for( const f of this._foundations )
+      if( foundationUpdates[ f.name ] != null ){ f.weight = foundationUpdates[ f.name ]!; updated = true }
+
+    // Re-normalize to the constructor's invariant (weights sum to 1.0). The
+    // override path previously assigned raw weights directly, de-normalizing
+    // the set and skewing the relative weights guilt & indignation depend on.
+    if( updated ){
+      const total = this._foundations.reduce( ( s, f ) => s + f.weight, 0 )
+      if( total > 0 ) for( const f of this._foundations ) f.weight = f.weight / total
+    }
+  }
+
+
+  subscribes(): string[] { return ['executive.prediction.formed'] }
+  publishes(): CognitiveEventSchema[] { return [] }
+
+  onCognitiveEvent( e: CognitiveEvent ): StateCommands | void {
+    this._model.observe( e.type, e.salience )
+    if( e.type === 'executive.prediction.formed' ){
+      const p = e.payload as { predictedDomains: string[]; confidence: number }
+      if( p.predictedDomains.includes('moral') )
+        this._model.setPrecision( 'emotion.guilt', 1.0 + p.confidence * 0.5 )
+    }
+  }
+
+  snapshot(): Record<string, unknown> { return {} }
+
+  async react(
+    delta: Duration,
+    _tick: Tick,
+    state: ReadonlySimulationState,
+    context: SimulationContext
+  ): Promise<EngineResult> {
+    this._readConfigFromState( state )
+    
+    const
+    events:   Array<Omit<SimulationEvent, 'id' | 'timestamp' | 'tick'>> = [],
+    commands: StateCommands = { metrics: [] }
+
+    // Detect value violations from percepts and own actions
+    const violations = this._detectViolations( state )
+
+    // Categorize violations by target (self vs. other)
+    const
+    selfViolations   = violations.filter( v => v.agent === 'self'),
+    otherViolations  = violations.filter( v => v.agent === 'other')
+
+    // Compute moral emotions
+    const previousGuilt = state.metrics.get('emotion.guilt') ?? 0
+    const previousShame = state.metrics.get('emotion.shame') ?? 0
+    const previousPride = state.metrics.get('emotion.pride') ?? 0
+
+    // Guilt: self-caused harm or fairness violation
+    const guiltRaw = this._computeGuilt( selfViolations )
+    const guilt = guiltRaw > 0.01
+      ? Math.min( 1, guiltRaw )
+      : Math.max( 0, previousGuilt - this._decayRate * ( delta / 1000 ) )
+
+    // Shame: self-violation with social exposure
+    const shameRaw = this._computeShame( selfViolations, state )
+    const shame = shameRaw > 0.01
+      ? Math.min( 1, shameRaw )
+      : Math.max( 0, previousShame - this._decayRate * ( delta / 1000 ) )
+
+    // Pride: self-exceeding moral standards
+    const prideRaw = this._computePride( state )
+    const pride = prideRaw > 0.01
+      ? Math.min( 1, prideRaw )
+      : Math.max( 0, previousPride - this._decayRate * ( delta / 1000 ) )
+
+    // Indignation: others' violations (moral anger)
+    const indignation = this._computeIndignation( otherViolations )
+
+    // Disgust: sanctity/degradation violations
+    const disgust = this._computeDisgust( violations )
+
+    commands.metrics!.push(
+      [ 'emotion.guilt', guilt ],
+      [ 'emotion.shame', shame ],
+      [ 'emotion.pride', pride ],
+      [ 'emotion.indignation', indignation ],
+      [ 'emotion.disgust', disgust ],
+      [ 'moral.self_violations', selfViolations.length ],
+      [ 'moral.other_violations', otherViolations.length ],
+    )
+
+    // Significant moral emotion events
+    if( guilt > this._eventThreshold )
+      events.push({
+        type: 'emotion.guilt.significant',
+        source: this.name,
+        payload: { guilt, selfViolations: selfViolations.map( v => v.foundation ) },
+      })
+
+    if( shame > this._eventThreshold )
+      events.push({
+        type: 'emotion.shame.significant',
+        source: this.name,
+        payload: { shame },
+      })
+
+    if( pride > this._eventThreshold )
+      events.push({
+        type: 'emotion.pride.significant',
+        source: this.name,
+        payload: { pride },
+      })
+
+    if( indignation > 0.6 )
+      events.push({
+        type: 'emotion.indignation.elevated',
+        source: this.name,
+        payload: { indignation },
+      })
+
+
+    // Phase C + F: publish cognitive event — gated by prediction error
+    const _bus = this._bus
+    if( _bus && ( guilt > 0.4 || shame > 0.4 ) ){
+      const predErr = this._model.observe( 'emotion.guilt', guilt )
+      if( !predErr.gated )
+        _bus.publish({ type: 'emotion.guilt.elevated', version: 1, sourceEngine: this.name, salience: Math.min(1, guilt * 1.5), payload: { guilt, shame, pride } })
+    }
+    return { events: events.length > 0 ? events : undefined, commands }
+  }
+
+  // ── Violation detection ──────────────────────────────────
+
+  private _detectViolations( state: ReadonlySimulationState ): ValueViolation[] {
+    const violations: ValueViolation[] = []
+
+    for( const entity of state.entities.values() ){
+      // Social percepts can encode moral violations
+      if( entity.type === 'percept.social'){
+        const
+        action     = ( entity.metadata?.action as string ) ?? '',
+        keid    = ( entity.metadata?.keid as string ) ?? '',
+        directedAtSelf = entity.metadata?.directedAtSelf === true,
+        harmful    = entity.metadata?.harmful === true,
+        unfair     = entity.metadata?.unfair === true,
+        deceptive  = entity.metadata?.deceptive === true,
+        disrespectful = entity.metadata?.disrespectful === true
+
+        if( harmful )
+          violations.push({
+            foundation: 'care',
+            severity: 0.7,
+            agent: directedAtSelf ? 'other' : 'other',
+            keid,
+          })
+
+        if( unfair )
+          violations.push({
+            foundation: 'fairness',
+            severity: 0.6,
+            agent: 'other',
+            keid,
+          })
+
+        if( deceptive )
+          violations.push({
+            foundation: 'fairness',
+            severity: 0.5,
+            agent: 'other',
+            keid,
+          })
+
+        if( disrespectful )
+          violations.push({
+            foundation: 'authority',
+            severity: 0.4,
+            agent: 'other',
+            keid,
+          })
+      }
+
+      // Own actions that could be violations
+      if( entity.type === 'action.own' || entity.type === 'decision.record'){
+        const
+        outcome    = entity.metadata?.outcome as string ?? '',
+        harmful    = entity.metadata?.harmful === true,
+        unfair     = entity.metadata?.unfair === true,
+        dishonest  = entity.metadata?.dishonest === true
+
+        if( harmful )
+          violations.push({
+            foundation: 'care',
+            severity: 0.65,
+            agent: 'self',
+            keid: 'agent-self',
+          })
+
+        if( unfair )
+          violations.push({
+            foundation: 'fairness',
+            severity: 0.55,
+            agent: 'self',
+            keid: 'agent-self',
+          })
+
+        if( dishonest )
+          violations.push({
+            foundation: 'fairness',
+            severity: 0.5,
+            agent: 'self',
+            keid: 'agent-self',
+          })
+      }
+    }
+
+    return violations
+  }
+
+  // ── Emotion computation ──────────────────────────────────
+
+  private _computeGuilt( selfViolations: ValueViolation[] ): number {
+    if( selfViolations.length === 0 ) return 0
+
+    // Guilt is weighted by foundation importance
+    let weightedSeverity = 0
+    let totalWeight = 0
+
+    for( const violation of selfViolations ){
+      const foundation = this._foundations.find( f => f.name === violation.foundation )
+      const weight = foundation?.weight ?? 0.1
+      weightedSeverity += violation.severity * weight
+      totalWeight += weight
+    }
+
+    return totalWeight > 0 ? weightedSeverity / totalWeight : 0
+  }
+
+  private _computeShame(
+    selfViolations: ValueViolation[],
+    state: ReadonlySimulationState
+  ): number {
+    if( selfViolations.length === 0 ) return 0
+
+    // Shame = guilt + social exposure
+    const guiltLevel = this._computeGuilt( selfViolations )
+    const
+    socialPresence    = state.metrics.get('social.active_agents') ?? 0,
+    evaluationThreat  = state.metrics.get('social.evaluation_threat') ?? 0,
+    exposureLevel     = Math.min( 1, ( socialPresence / 5 ) * 0.5 + evaluationThreat * 0.5 )
+
+    return guiltLevel * ( 0.4 + exposureLevel * 0.6 )
+  }
+
+  private _computePride( state: ReadonlySimulationState ): number {
+    // Pride = own actions exceeded moral standards
+    let prideScore = 0
+    let actionCount = 0
+
+    for( const entity of state.entities.values() ){
+      if( entity.type !== 'action.own' && entity.type !== 'decision.record') continue
+
+      const
+      virtuous = entity.metadata?.virtuous === true,
+      helpful  = entity.metadata?.helpful === true,
+      generous = entity.metadata?.generous === true,
+      honest   = entity.metadata?.honest === true
+
+      if( virtuous ) prideScore += 0.4
+      if( helpful )  prideScore += 0.3
+      if( generous ) prideScore += 0.2
+      if( honest )   prideScore += 0.1
+
+      actionCount++
+    }
+
+    return actionCount > 0
+      ? Math.min( 1, prideScore / Math.max( actionCount, 1 ) )
+      : 0
+  }
+
+  private _computeIndignation( otherViolations: ValueViolation[] ): number {
+    if( otherViolations.length === 0 ) return 0
+
+    // Indignation is moral anger at others' violations
+    let weightedSeverity = 0
+    let totalWeight = 0
+
+    for( const violation of otherViolations ){
+      const foundation = this._foundations.find( f => f.name === violation.foundation )
+      const weight = foundation?.weight ?? 0.1
+      weightedSeverity += violation.severity * weight
+      totalWeight += weight
+    }
+
+    return totalWeight > 0
+      ? Math.min( 1, ( weightedSeverity / totalWeight ) * 1.2 )
+      : 0
+  }
+
+  private _computeDisgust( violations: ValueViolation[] ): number {
+    // Disgust is specifically for sanctity/degradation violations
+    const sanctityViolations = violations.filter( v => v.foundation === 'sanctity')
+    if( sanctityViolations.length === 0 ) return 0
+
+    const maxSeverity = Math.max( ...sanctityViolations.map( v => v.severity ) )
+    return maxSeverity
+  }
+}

package/src/cognition/faculties/novelty.detector.ts

@@ -0,0 +1,254 @@
+// ─────────────────────────────────────────────────────────────
+// src/cognition/faculties/novelty.detector.ts
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * NoveltyDetector — compares current percepts against expectations.
+ *
+ * Computes prediction error by comparing incoming percept patterns
+ * against a running model of expected patterns. High novelty signals:
+ *   - Something unexpected happened
+ *   - The world has changed in a meaningful way
+ *   - The current mental model needs updating
+ *
+ * Novelty drives:
+ *   - Curiosity (positive valence + novelty → exploration)
+ *   - Anxiety (negative valence + novelty → caution)
+ *   - Learning (high novelty events are consolidated more strongly)
+ *
+ * Uses a simple exponential moving average of recent percept counts
+ * per category as the expectation baseline.
+ *
+ * Part of Shard 0 (Perceptual Layer) — runs every tick, synchronous.
+ */
+
+import type {
+  Duration,
+  Tick,
+  SimulationContext,
+  ReadonlySimulationState,
+  StateCommands,
+  SimulationEvent,
+} from '#core/types'
+import type { SimulationEngine, EngineResult, CognitiveEngine } from '#cognition/types'
+import type { CognitiveEventSchema } from '#cognition/schema.registry'
+import type { CognitiveEvent, CognitiveBus } from '#cognition/bus'
+import { GenerativeModel } from '#cognition/generative.model'
+import { readEffectiveParams } from '#cognition/persona.prior'
+
+export interface NoveltyDetectorConfig {
+  /** Learning rate for expectation updates (0-1) */
+  learningRate?: number
+  /** How many ticks to look back for pattern comparison */
+  windowSize?: number
+  /** Threshold above which novelty is considered significant */
+  significanceThreshold?: number
+  bus?: CognitiveBus
+}
+
+interface CategoryStats {
+  count: number
+  averageSalience: number
+}
+
+export class NoveltyDetector implements SimulationEngine, CognitiveEngine {
+  readonly name     = 'novelty-detector'
+  
+  private _learningRate: number
+  private _windowSize: number
+  private _significanceThreshold: number
+
+  // Expected patterns — EMA of percept counts per category
+  private _expectedCounts = new Map<string, number>()
+  private _expectedSalience = new Map<string, number>()
+  private _recentHistory: Array<Map<string, CategoryStats>> = []
+
+  private _bus: CognitiveBus | null = null
+
+  private readonly _model    = new GenerativeModel()
+
+
+  constructor( config: NoveltyDetectorConfig = {} ){
+    this._bus = config.bus ?? null
+    this._learningRate          = config.learningRate          ?? 0.1
+    this._windowSize            = config.windowSize            ?? 10
+    this._significanceThreshold = config.significanceThreshold ?? 0.4
+  }
+  attachBus( bus: CognitiveBus ): void { this._bus = bus }
+
+  // ── Engine interface ─────────────────────────────────────
+
+  private _readConfigFromState( state: ReadonlySimulationState ): void {
+    // Effective config = base engine-config-novelty ⊕ persona-prior. Channel A: an open
+    // Will develops a lower significanceThreshold and so registers novelty more readily.
+    const p = readEffectiveParams( state, 'engine-config-novelty' )
+    if( p.learningRate != null ) this._learningRate = p.learningRate
+    if( p.windowSize != null ) this._windowSize = p.windowSize
+    if( p.significanceThreshold != null ) this._significanceThreshold = p.significanceThreshold
+  }
+
+
+  subscribes(): string[] { return ['executive.prediction.formed'] }
+  publishes(): CognitiveEventSchema[] { return [] }
+
+  onCognitiveEvent( e: CognitiveEvent ): StateCommands | void {
+    this._model.observe( e.type, e.salience )
+    if( e.type === 'executive.prediction.formed' ){
+      const p = e.payload as { predictedDomains: string[]; confidence: number }
+      if( p.predictedDomains.includes('perception') )
+        this._model.setPrecision( 'novelty.score', 1.0 + p.confidence * 0.5 )
+    }
+  }
+
+  snapshot(): Record<string, unknown> { return {} }
+
+  async react(
+    _delta: Duration,
+    tick: Tick,
+    state: ReadonlySimulationState,
+    context: SimulationContext
+  ): Promise<EngineResult> {
+    this._readConfigFromState( state )
+    
+    const
+    events:   Array<Omit<SimulationEvent, 'id' | 'timestamp' | 'tick'>> = [],
+    commands: StateCommands = { metrics: [] }
+
+    // Aggregate current percepts by category
+    const currentStats = this._aggregatePercepts( state )
+
+    // Compute novelty per category
+    let totalNovelty = 0
+    let categoriesWithNovelty = 0
+
+    for( const [ category, stats ] of currentStats ){
+      const
+      expectedCount   = this._expectedCounts.get( category ) ?? 0,
+      expectedSalience = this._expectedSalience.get( category ) ?? 0.3,
+      countNovelty    = this._computeNovelty( stats.count, expectedCount ),
+      salienceNovelty = this._computeNovelty( stats.averageSalience, expectedSalience ),
+      categoryNovelty = ( countNovelty + salienceNovelty ) / 2
+
+      // Update running metric per category
+      commands.metrics!.push([ `novelty.${category}`, categoryNovelty ])
+
+      if( categoryNovelty > this._significanceThreshold )
+        categoriesWithNovelty++
+
+      totalNovelty += categoryNovelty
+    }
+
+    // Overall novelty
+    const overallNovelty = currentStats.size > 0
+      ? totalNovelty / currentStats.size
+      : 0
+
+    commands.metrics!.push(
+      [ 'perception.novelty', overallNovelty ],
+      [ 'novelty.significant_categories', categoriesWithNovelty ],
+    )
+
+    // Significant novelty event
+    if( overallNovelty > this._significanceThreshold )
+      events.push({
+        type: 'novelty.significant',
+        source: this.name,
+        payload: {
+          overallNovelty,
+          categoriesWithNovelty,
+          tick,
+        },
+      })
+
+    // Update expectations for next tick
+    this._updateExpectations( currentStats )
+    this._updateHistory( currentStats )
+
+
+    // Phase C: publish cognitive event
+    const _bus = this._bus
+    if( _bus && overallNovelty > 0.3 )
+      _bus.publish({ type: 'perception.novelty.spike', version: 1, sourceEngine: this.name, salience: Math.min(1, overallNovelty * 2), payload: { novelty: overallNovelty } })
+    // Phase D + F: rich state-change event — gated by prediction error
+    if( _bus ){
+      const predErr = this._model.observe( 'novelty.score', overallNovelty )
+      if( !predErr.gated )
+        _bus.publish({ type: 'novelty.state.changed', version: 1, sourceEngine: this.name, salience: predErr.salience, payload: { novelty: overallNovelty, socialEvaluationThreat: state.metrics.get('social.evaluation_threat') ?? 0, activeAgents: state.metrics.get('social.active_agents') ?? 0, fearLevel: state.metrics.get('emotion.fear') ?? 0 } })
+    }
+    return { events: events.length > 0 ? events : undefined, commands }
+  }
+
+  // ── Internal ─────────────────────────────────────────────
+
+  /**
+   * Aggregate current percept entities by category.
+   */
+  private _aggregatePercepts( state: ReadonlySimulationState ): Map<string, CategoryStats> {
+    const stats = new Map<string, CategoryStats>()
+
+    for( const entity of state.entities.values() ){
+      if( entity.type !== 'percept' && entity.type !== 'percept.social')
+        continue
+
+      const category = ( entity.metadata?.category as string ) ?? 'unknown'
+      const salience = ( entity.metadata?.salience as number ) ?? 0.3
+
+      const existing = stats.get( category )
+      if( existing ){
+        existing.count++
+        existing.averageSalience = ( existing.averageSalience * ( existing.count - 1 ) + salience ) / existing.count
+      }
+      else {
+        stats.set( category, { count: 1, averageSalience: salience } )
+      }
+    }
+
+    return stats
+  }
+
+  /**
+   * Compute novelty as normalized deviation from expected value.
+   */
+  private _computeNovelty( current: number, expected: number ): number {
+    if( expected === 0 )
+      return current > 0 ? 1.0 : 0.0
+
+    const deviation = Math.abs( current - expected )
+    const normalized = deviation / Math.max( expected, 1 )
+
+    return Math.min( 1, normalized )
+  }
+
+  /**
+   * Update exponential moving averages for each category.
+   */
+  private _updateExpectations( stats: Map<string, CategoryStats> ): void {
+    // Update for observed categories
+    for( const [ category, s ] of stats ){
+      const prevCount   = this._expectedCounts.get( category ) ?? 0,
+            prevSalience = this._expectedSalience.get( category ) ?? 0.3
+
+      this._expectedCounts.set(
+        category,
+        prevCount + this._learningRate * ( s.count - prevCount )
+      )
+
+      this._expectedSalience.set(
+        category,
+        prevSalience + this._learningRate * ( s.averageSalience - prevSalience )
+      )
+    }
+
+    // Decay expectations for unobserved categories
+    for( const [ category, count ] of this._expectedCounts ){
+      if( !stats.has( category ) )
+        this._expectedCounts.set( category, count * ( 1 - this._learningRate * 0.5 ) )
+    }
+  }
+
+  private _updateHistory( stats: Map<string, CategoryStats> ): void {
+    this._recentHistory.push( new Map( stats ) )
+    if( this._recentHistory.length > this._windowSize )
+      this._recentHistory.shift()
+  }
+}