@mindot/will 0.7.0 → 0.9.0

package/src/llm/routing.ts

@@ -0,0 +1,204 @@
+// ─────────────────────────────────────────────────────────────
+// src/llm/routing.ts
+// ─────────────────────────────────────────────────────────────
+//
+// MODEL_ROUTING W2 — per-call model selection.
+//
+// A Will runs one LLMDirector, and every call site shares it: the master's
+// decision, each facet, the propose pass, the rolling summariser, the identity
+// guard. They are not the same cognitive act, and they need not be the same
+// inference. This module lets a host decide which model serves which call,
+// without the engine learning anything it should not know.
+//
+// WHAT THIS IS NOT. This is a mechanism, never a policy. The engine may know
+// that a call is routine or consequential — that is a cognitive fact it already
+// computes (`LLMCallMeta.demand`). It must never know who is paying, what plan
+// they are on, or what anything costs us. A router that needs commercial
+// information is the host's to write; the seam below carries none of it.
+//
+// DETERMINISM CONTRACT. A router is an external oracle, exactly like the LLM
+// itself and the policy arbiter. Its choice is already captured: the completion
+// tape records `provider` and `model` on every call, and replay re-feeds the
+// recorded completion rather than re-deciding. So replay never consults a
+// router, and a run replays byte-for-byte whether the router is absent,
+// present, or since reconfigured.
+//
+// SCOPE. A router may read the call meta and its own configuration, and nothing
+// else. It must not reach into simulation state — that is what keeps this
+// module below cognition (src/llm imports no cognition behaviour) and keeps
+// routing from becoming a hidden input to the mind.
+// ─────────────────────────────────────────────────────────────
+
+import { logger } from '#core/logger'
+import type { LLMProvider, LLMCallMeta } from '#llm/index'
+
+/**
+ * Where a single call should go. Every field except `model` falls back to the
+ * Will's default when omitted.
+ */
+export interface ModelRoute {
+  /**
+   * Omit to keep the Will's default provider and change only the model — the
+   * common "same vendor, different model for this kind of work" route, and what
+   * the per-role model map compiles to (a role has never had a provider of its
+   * own). Name a provider to cross vendors; it must appear in `llm.providers`
+   * or the route falls back to the default.
+   */
+  provider?: LLMProvider
+  model: string
+  /** Override the provider's API base (self-hosted / OpenAI-compatible servers). */
+  baseUrl?: string
+  /** Override the output-token ceiling for this call. */
+  maxOutputTokens?: number
+}
+
+/**
+ * Chooses a model for a call.
+ *
+ * Returning `null` means "no opinion" — the Will's default model is used. A
+ * router should return `null` rather than guess when it does not recognise a
+ * call: falling back is always safe, and a wrong route is not.
+ */
+export interface ModelRouter {
+  /** Stable identifier, recorded alongside routing telemetry. */
+  readonly name: string
+  route( meta: LLMCallMeta ): ModelRoute | null
+}
+
+/**
+ * The default. Has no opinion about anything, allocates nothing.
+ *
+ * A Will running this must be byte-identical to one built before the routing
+ * seam existed — that property is asserted by test, and it is what lets this
+ * ship dark.
+ */
+export const NULL_ROUTER: ModelRouter = {
+  name: 'null',
+  route(): ModelRoute | null { return null },
+}
+
+/** True when the router is the no-op default (used to skip the seam entirely). */
+export function isNullRouter( router: ModelRouter | null | undefined ): boolean {
+  return !router || router === NULL_ROUTER
+}
+
+// ── Reference implementation ──────────────────────────────────
+
+/**
+ * One entry in a {@link TableRouter}'s table. All present conditions must match
+ * (logical AND); an absent condition matches anything.
+ */
+export interface RoutingRule {
+  /**
+   * Match `LLMCallMeta.category` exactly (e.g. 'executive', 'summarizer').
+   *
+   * The axes are typed rather than free strings so a rule that names a bucket
+   * the engine never emits fails to compile instead of silently never matching
+   * — a routing table's worst failure is the rule that looks right and is dead.
+   */
+  category?: LLMCallMeta['category']
+  /** Match `LLMCallMeta.attribute` exactly (e.g. 'master', 'facet', 'guard'). */
+  attribute?: LLMCallMeta['attribute']
+  /** Match `LLMCallMeta.process` exactly (e.g. 'decision', 'ideation'). */
+  process?: LLMCallMeta['process']
+  /** Match `LLMCallMeta.function` exactly (e.g. 'decision', 'consolidation'). */
+  function?: LLMCallMeta['function']
+  /**
+   * Inclusive lower bound on `LLMCallMeta.demand`. A call with no demand
+   * reported never matches a rule that sets this — absent means unknown, and
+   * unknown must not be treated as zero.
+   */
+  minDemand?: number
+  /** Exclusive upper bound on `LLMCallMeta.demand`. Same absence rule. */
+  maxDemand?: number
+  /** Where a matching call goes. */
+  route: ModelRoute
+}
+
+/**
+ * A worked example of the seam: first matching rule wins, otherwise no opinion.
+ *
+ * This ships so that the interface has a reference implementation and so that
+ * hosts have something to copy — it is deliberately dumb. It is not a routing
+ * strategy, and the engine ships no table of its own: what belongs where is the
+ * host's decision, expressed as configuration.
+ *
+ * Rules are evaluated in order, so put specific rules before general ones.
+ */
+export class TableRouter implements ModelRouter {
+  readonly name: string
+  private readonly _rules: readonly RoutingRule[]
+
+  constructor( rules: readonly RoutingRule[], name = 'table' ){
+    this._rules = [ ...rules ]
+    this.name   = name
+  }
+
+  route( meta: LLMCallMeta ): ModelRoute | null {
+    for( const rule of this._rules ){
+      if( matches( rule, meta ) ) return rule.route
+    }
+    return null
+  }
+}
+
+/**
+ * Ask each router in turn; the first with an opinion wins.
+ *
+ * This exists because a Will can have two sources of routing at once: the
+ * host's own router, and the one compiled from its per-role model map. Order
+ * expresses precedence — an explicit router is consulted before the role map,
+ * which is the precedence those two mechanisms already had when roles were
+ * served by separate directors.
+ *
+ * A throwing link is skipped, not propagated. The links are independent
+ * decisions, and one broken router must not take a working one down with it —
+ * that would silently demote every role-mapped call to the default model.
+ */
+export function chainRouters( ...routers: ( ModelRouter | null | undefined )[] ): ModelRouter {
+  const chain = routers.filter( ( r ): r is ModelRouter => !isNullRouter( r ) )
+  if( chain.length === 0 ) return NULL_ROUTER
+  if( chain.length === 1 ) return chain[ 0 ]!
+
+  const warned = new Set<string>()
+  return {
+    name: chain.map( r => r.name ).join('>'),
+    route( meta: LLMCallMeta ): ModelRoute | null {
+      for( const router of chain ){
+        try {
+          const hit = router.route( meta )
+          if( hit ) return hit
+        }
+        catch( err ){
+          if( !warned.has( router.name ) ){
+            warned.add( router.name )
+            logger.warn(`[llm.routing] router "${router.name}" threw — skipping it: ${( err as Error ).message}`)
+          }
+        }
+      }
+      return null
+    },
+  }
+}
+
+function matches( rule: RoutingRule, meta: LLMCallMeta ): boolean {
+  if( rule.category  !== undefined && rule.category  !== meta.category  ) return false
+  if( rule.attribute !== undefined && rule.attribute !== meta.attribute ) return false
+  // `process` split out of `function` (ideation vs decision). It was declarable on a
+  // rule from the moment the axis existed but never tested here, so a rule that named
+  // it matched every process — the opposite of the AND semantics every other axis has.
+  if( rule.process   !== undefined && rule.process   !== meta.process   ) return false
+  if( rule.function  !== undefined && rule.function  !== meta.function  ) return false
+
+  // Absent demand is UNKNOWN, not zero: a demand-bounded rule cannot claim a
+  // call whose demand was never measured.
+  const bounded = rule.minDemand !== undefined || rule.maxDemand !== undefined
+  if( bounded ){
+    const d = meta.demand
+    if( typeof d !== 'number' || Number.isNaN( d ) ) return false
+    if( rule.minDemand !== undefined && d <  rule.minDemand ) return false
+    if( rule.maxDemand !== undefined && d >= rule.maxDemand ) return false
+  }
+
+  return true
+}

package/src/llm/summarizer.ts

@@ -17,6 +17,7 @@
 
 import { logger } from '#core/logger'
 import type { LLMDirector } from '#llm/index'
+import { BACKGROUND_DEMAND } from '#llm/index'
 
 export interface SummarizerConfig {
   /** How many executive calls between summarization runs. Default: 10 */
@@ -148,7 +149,10 @@ export class ExecutiveSummarizer {
         userMessage,
         this._callCount as any,
         undefined,
-        { category: 'summarizer', attribute: 'memory', function: 'consolidation' }
+        // MODEL_ROUTING W0 — compression is background work at a constant low
+        // demand: distilling excerpts is the same job whether the mind is calm
+        // or in crisis, so there is no honest per-tick measure to forward here.
+        { category: 'summarizer', attribute: 'memory', process: 'cog', function: 'consolidation', demand: BACKGROUND_DEMAND }
       )
 
       if( result.text ){

package/src/llm/wire.contracts.ts

@@ -34,6 +34,25 @@ export const REPLY_TEXT_TAG = 'REPLY_TEXT'
 export const REPLY_TEXT_OPEN  = `[${REPLY_TEXT_TAG}]`
 export const REPLY_TEXT_CLOSE = `[/${REPLY_TEXT_TAG}]`
 
+/**
+ * The block a facet uses to say it has decided NOT to speak, and why.
+ *
+ * "Omit [REPLY_TEXT] to stay silent" was stated in the prompt and nowhere else —
+ * a rule with no mechanism behind it. Live, an outreach facet read that it had
+ * three unanswered messages outstanding, correctly concluded there was nothing new
+ * to say, and — having no other block to put that sentence in — wrote it into
+ * REPLY_TEXT. "— nothing new to say to FKEM. Three messages unanswered is enough."
+ * was delivered to FKEM, in the third person, about him.
+ *
+ * The prompt already warned against exactly that. Warning was not enough, because
+ * the pressure is structural: a mind that decides not to speak still has something
+ * to say about the decision, and REPLY_TEXT was the only place to say it. This is
+ * the place. Content here is recorded and never sent.
+ */
+export const NO_MESSAGE_TAG   = 'NO_MESSAGE'
+export const NO_MESSAGE_OPEN  = `[${NO_MESSAGE_TAG}]`
+export const NO_MESSAGE_CLOSE = `[/${NO_MESSAGE_TAG}]`
+
 /** Wrap a reply body in the block markers (the mock's emission shape). */
 export function wrapReplyText( body: string ): string {
   return [ REPLY_TEXT_OPEN, body, REPLY_TEXT_CLOSE ].join('\n')

package/src/pma/index.ts

@@ -32,6 +32,7 @@ import { readFileSync, existsSync } from 'node:fs'
 import { join }                     from 'node:path'
 
 import type { SimulationState }    from '#core/types'
+import { mergeEngineConfig }        from '#cognition/config.mirror.entities'
 import type { DefaultSimulation }  from '#core/simulation'
 import type { Cognition }          from '#types'
 import type {
@@ -45,6 +46,7 @@ import {
   loadCompetence,
   type CompetenceSnapshot,
 } from '#agency/competence.codec'
+import { mergeIdentity, composeIdentityPrompt, readPersona, IDENTITY_ENTITY_ID } from '#cognition/identity.entity'
 
 // ── Schema version ─────────────────────────────────────────────
 // Bump this when any field is removed or semantically changed.
@@ -361,7 +363,12 @@ export class PMADistiller {
       if( entity.type === 'will.identity'){
         const m = entity.metadata ?? {}
         return {
-          prompt:  ( m['prompt']  as string )                     ?? '',
+          // The TENANT's text only. Capturing the composed `prompt` baked the
+          // container's WILL_CORE_PREAMBLE into the artifact, so a woken mind
+          // recited whichever build's preamble had distilled it — forever, and
+          // invisibly. `readPersona` falls back to stripping it out of a composed
+          // prompt, so artifacts written before the split load clean too.
+          prompt:  readPersona( m ),
           values:  ( m['values']  as string[] )                   ?? [],
           traits:  ( m['traits']  as Record<string, number> )     ?? {},
           traitStats: ( m['traitStats'] as PMAIdentity['traitStats'] ) ?? undefined,
@@ -792,22 +799,31 @@ export class PMALoader {
     const sm = simulation.stateManager
 
     // ── 1. Identity (with enhanced fields) ────────────────────
-    sm.setEntity({
-      id:        'identity-self',
-      type:      'will.identity',
-      createdAt: Date.now(),
-      updatedAt: Date.now(),
-      metadata: {
-        prompt:  pma.identity.prompt,
-        values:  pma.identity.values,
-        traits:  pma.identity.traits,
-        traitStats: pma.identity.traitStats,   // restore the Will's own norm (graded salience B/C)
-        version: pma.identity.version,
-        style:   pma.identity.style,
-        socialOrientation: pma.identity.socialOrientation,
-        trustPropensity:   pma.identity.trustPropensity,
-        memoryPersistence: pma.identity.memoryPersistence,
-      },
+    // MERGING (see cognition/identity.entity). An artifact carries what the mind
+    // LEARNED about itself; it does not carry the mind's name, because the name is
+    // supplied at boot by whoever is renting the container. This used to replace
+    // the entity outright, so `_seedIdentity`'s `name` — written moments earlier
+    // in the same wake — was erased before the first tick, every single wake.
+    // Recomposed, never restored verbatim: `pma.identity.prompt` is layer 2 (the
+    // persona), and layer 1 comes from the build that is running NOW. This is what
+    // makes a preamble fix reach minds that already exist.
+    const environment = sm.getEntity( IDENTITY_ENTITY_ID )?.metadata?.['environment']
+    // Through `readPersona`, NOT raw. An artifact written before the layers were
+    // split stores the COMPOSED prompt, so composing over it again gives the mind
+    // its own architecture twice. Putting this fallback only in the distiller was
+    // not enough — the loader is what every existing artifact goes through.
+    const persona = readPersona({ prompt: pma.identity.prompt })
+    mergeIdentity( sm, {
+      persona,
+      prompt:  composeIdentityPrompt( persona, typeof environment === 'string' ? environment : undefined ),
+      values:  pma.identity.values,
+      traits:  pma.identity.traits,
+      traitStats: pma.identity.traitStats,   // restore the Will's own norm (graded salience B/C)
+      version: pma.identity.version,
+      style:   pma.identity.style,
+      socialOrientation: pma.identity.socialOrientation,
+      trustPropensity:   pma.identity.trustPropensity,
+      memoryPersistence: pma.identity.memoryPersistence,
     })
 
     // ── 1b. Persona (learned self-tuning from the metacognition cycle) ──
@@ -889,55 +905,53 @@ export class PMALoader {
     const temperamentValence = pma.emotionalBaseline.temperamentValence
     const reactivity = pma.emotionalBaseline.reactivity
 
-    sm.setEntity({
-      id:        'engine-config-affective-blender',
-      type:      'engine.config',
-      createdAt: Date.now(),
-      updatedAt: Date.now(),
-      metadata: {
-        engine: 'affective-blender',
-        params: {
-          inertia: 1 - reactivity,
-          temperamentValence,
-        },
+    // MERGE, never replace — same trap as engine-config-executive. The mirror
+    // seeds `emitBlendEvents` here and the PMA carries only `inertia`, so a
+    // whole-entity write silently dropped it for every restored Will.
+    mergeEngineConfig( sm, {
+      id: 'engine-config-affective-blender', engine: 'affective-blender',
+      params: {
+        inertia: 1 - reactivity,
+        temperamentValence,
       },
-    })
+    }, 'incoming')
 
     // ── 6. Behavioral parameters ──────────────────────────────
     if( pma.behavioral.riskTolerance !== undefined ||
         pma.behavioral.explorationRate !== undefined ||
         pma.behavioral.impulsivity !== undefined ){
 
-      sm.setEntity({
-        id:        'engine-config-executive',
-        type:      'engine.config',
-        createdAt: Date.now(),
-        updatedAt: Date.now(),
-        metadata: {
-          engine: 'executive',
-          params: {
-            riskTolerance:   pma.behavioral.riskTolerance   ?? 0.5,
-            explorationRate: pma.behavioral.explorationRate ?? 0.3,
-            impulsivity:     pma.behavioral.impulsivity     ?? 0.3,
-          },
+      // MERGE onto the seeded mirror, never replace it.
+      //
+      // createWill() seeds engine-config-executive first (executiveInterval,
+      // cooldownTicks, deliberateThreshold, maxFacets); loadPMA() runs after. A
+      // whole-entity write here dropped every param the PMA does not carry — so
+      // for every Will restored from an artifact (i.e. every production Will), the
+      // executive's dual-process gate lost its base, `readBaseParams` returned
+      // nothing for `deliberateThreshold`, and consolidatePrior skipped its
+      // adjustments outright: the analytical/decisiveness edges that are supposed
+      // to develop how readily this mind stops to think had no base to move.
+      mergeEngineConfig( sm, {
+        id: 'engine-config-executive', engine: 'executive',
+        params: {
+          riskTolerance:   pma.behavioral.riskTolerance   ?? 0.5,
+          explorationRate: pma.behavioral.explorationRate ?? 0.3,
+          impulsivity:     pma.behavioral.impulsivity     ?? 0.3,
         },
-      })
+      }, 'incoming')
     }
 
     // Configure memory persistence for ForgettingCurve
     if( pma.identity.memoryPersistence !== undefined ){
-      sm.setEntity({
-        id:        'engine-config-forgetting',
-        type:      'engine.config',
-        createdAt: Date.now(),
-        updatedAt: Date.now(),
-        metadata: {
-          engine: 'forgetting-curve',
-          params: {
-            baseForgettingRate: 1 - ( pma.identity.memoryPersistence * 0.7 ),
-          },
+      // MERGE — the mirror seeds emotionProtection / pruningThreshold /
+      // maxPrunePerTick here and the PMA carries only baseForgettingRate, so a
+      // whole-entity write dropped three params on every restore.
+      mergeEngineConfig( sm, {
+        id: 'engine-config-forgetting', engine: 'forgetting-curve',
+        params: {
+          baseForgettingRate: 1 - ( pma.identity.memoryPersistence * 0.7 ),
         },
-      })
+      }, 'incoming')
     }
 
     // ── 7. Relationship stubs ─────────────────────────────────

package/src/runners/thin-shim.runner.ts

@@ -16,6 +16,14 @@
 
 import type { WillConfig } from '#stem/mind'
 import type { StateSnapshot } from '#stem/index'
+import type { TokenTracker } from '#cognition/utilities/token.tracker'
+
+/**
+ * The Will's token tracker, for cost display. Held here rather than passed in
+ * because printStatus is registered as a TickListener, whose third parameter is
+ * the outbox. Cost is no longer a state metric (W8c) — it lives on the tracker.
+ */
+let _tracker: TokenTracker | undefined
 import { WillStem } from '#stem/index'
 
 // ── Env config ────────────────────────────────────────────────
@@ -88,14 +96,15 @@ function printStatus( snapshot: StateSnapshot, tick: number ): void {
     `  entities=${entities}`
   )
 
-  // LLM stats every LOG_INTERVAL
-  const costTotal    = ( snapshot.metrics.get('llm.cost_total_usd') ?? 0 ).toFixed( 4 )
-  const costThisTick = ( snapshot.metrics.get('llm.cost_this_tick_usd') ?? 0 ).toFixed( 5 )
-  const totalCalls   = snapshot.metrics.get('llm.total_calls') ?? 0
+  // LLM stats every LOG_INTERVAL. Tokens come from state; cost comes from the
+  // tracker — dollars are host accounting and no longer live in state (W8c).
+  const totalCalls = snapshot.metrics.get('llm.total_calls') ?? 0
+  const cost = _tracker
+    ? `  total_cost=$${_tracker.totalCostUsd.toFixed( 4 )}`
+    : ''
 
   console.log(
-    `  [llm] total_cost=$${costTotal}` +
-    `  tick_cost=$${costThisTick}` +
+    `  [llm]${cost}` +
     `  calls=${totalCalls}` +
     `  prompt=${snapshot.metrics.get('llm.prompt_tokens_total') ?? 0}` +
     `  completion=${snapshot.metrics.get('llm.completion_tokens_total') ?? 0}`
@@ -141,6 +150,9 @@ async function main(): Promise<void> {
   console.log('[init] Assembling mind...')
   await manager.createWill( willConfig )
 
+  // Cost is no longer a state metric (W8c) — read it off the Will's tracker.
+  _tracker = manager.getWillCognition( WILL_ID ).tokenTracker
+
   manager.addTickListener( WILL_ID, printStatus )
 
   // Graceful shutdown