@mindot/will 0.1.0

package/src/cognition/faculties/executive.engine/deferred.effects.ts

@@ -0,0 +1,104 @@
+// ─────────────────────────────────────────────────────────────
+// src/cognition/faculties/executive.engine/deferred.effects.ts
+// ─────────────────────────────────────────────────────────────
+//
+// DeferredEffectQueue — commit-gated manager-write queue (FN11).
+//
+// buildStateCommands is pure: it returns entity/metric commands plus the
+// mirroring manager writes (summarizer / goals / beliefs / effectors + the
+// action-diversity ring buffer) as deferred thunks. Those thunks must run
+// ONLY after the orchestrator confirms the tick committed — a pre-commit
+// validator (e.g. the inhibition veto) can abort a tick and discard the
+// commands, and we must not let the manager writes land for a tick whose
+// entities were dropped.
+//
+// Commit is detected on the next react() via the committed
+// `executive.last_tick` metric (set by buildStateCommands) matching the
+// entry's observed tick.
+//
+// Extracted verbatim from ExecutiveEngine (R5-g-1) as a pure collaborator.
+// ─────────────────────────────────────────────────────────────
+
+import { logger } from '#core/logger'
+import type { ReadonlySimulationState } from '#core/types'
+import type { DeferredEffect } from '#faculties/executive.engine/commands'
+
+interface DeferredEntry {
+  /** footprint.tickObserved — equals the committed `executive.last_tick`. */
+  observedTick: number
+  /** react() tick when the commands were returned (decision is made after this). */
+  queuedAtTick: number
+  effects: DeferredEffect[]
+}
+
+export class DeferredEffectQueue {
+  private _entries: DeferredEntry[] = []
+
+  /** The tick of the most recent react() call — the commit tick for queued effects. */
+  private _lastReactTick = -1
+
+  /**
+   * Record the current react() tick. Effects queued after this call are
+   * stamped with it as their `queuedAtTick`, so flush() knows to wait one
+   * more tick before deciding whether the tick committed.
+   */
+  markReactTick( tick: number ): void {
+    this._lastReactTick = tick
+  }
+
+  /**
+   * Queue commit-gated manager writes for `observedTick`. No-op when there
+   * are no effects to run.
+   */
+  enqueue( observedTick: number, effects: DeferredEffect[] ): void {
+    if( effects.length === 0 ) return
+    this._entries.push({
+      observedTick,
+      queuedAtTick: this._lastReactTick,
+      effects,
+    })
+  }
+
+  /**
+   * Run deferred manager writes for committed ticks; drop them for aborted ticks.
+   *
+   * An entry queued during react() at tick C is resolved on the *next* react:
+   *   • committed `executive.last_tick === observedTick` → the commands landed,
+   *     so run the mirroring manager writes.
+   *   • the queuing tick has passed without that match → the tick was aborted
+   *     (e.g. inhibition veto), so drop the writes — no compensation needed
+   *     because the entity commands were discarded too.
+   */
+  flush( state: ReadonlySimulationState, currentTick: number ): void {
+    if( this._entries.length === 0 ) return
+
+    const committedTick = state.metrics.get( 'executive.last_tick' )
+    const keep: DeferredEntry[] = []
+
+    for( const entry of this._entries ){
+      // Not yet resolved — commands were returned this same tick; wait one tick
+      // for the orchestrator to commit (or abort) before deciding.
+      if( currentTick <= entry.queuedAtTick ){
+        keep.push( entry )
+        continue
+      }
+
+      if( committedTick === entry.observedTick ){
+        for( const effect of entry.effects ){
+          try { effect() }
+          catch( err ){
+            logger.error( `[executive] deferred effect failed (tick ${entry.observedTick}):`, err )
+          }
+        }
+      }
+      else {
+        logger.warn(
+          `[executive] dropping deferred manager writes for aborted tick ${entry.observedTick} ` +
+          `(committed executive tick: ${committedTick ?? 'none'})`
+        )
+      }
+    }
+
+    this._entries = keep
+  }
+}

package/src/cognition/faculties/executive.engine/deliberate.reasoning.ts

@@ -0,0 +1,60 @@
+// ─────────────────────────────────────────────────────────────
+// src/cognition/faculties/executive.engine/deliberate.reasoning.ts
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Shared System 2 machinery for the master AND its facets.
+ *
+ * Facets are "the master over their focus" — they reason with the same PromptFactory +
+ * parser and make their own deliberate decision (e.g. a planning facet: replan / continue
+ * / abandon). So they deliberate the same way: an a-priori effort gate (`selectProcess`)
+ * picks fast vs deliberate, and on the deliberate path a *propose* pass generates a
+ * divergent candidate set that the *decision* pass weighs before committing.
+ *
+ * This module owns the one genuinely shared, new piece — the propose (ideation) pass —
+ * so master and facet share it rather than duplicating. Each caller keeps its own
+ * prompt-building, decision call (with its own streaming/logging), and parsing.
+ */
+
+import type { LLMDirector, LLMCallMeta } from '#llm/index'
+import type { IdeationCandidate } from '#faculties/executive.engine/types'
+import { parseIdeation } from '#faculties/executive.engine/parser'
+
+export interface ProposeParams {
+  director: LLMDirector
+  /** Same system prompt the decision pass uses — shares the prompt cache. */
+  systemPrompt: string
+  /** User message carrying the ideation output-format override (full context, asks for options). */
+  ideationUserMessage: string
+  tick: number
+  /** Elevated sampling temperature (creativity-driven) — diverge when proposing. */
+  proposeTemperature: number
+  /**
+   * Cost-attribution for the propose (ideation) pass. The caller passes its own
+   * attribution (master vs facet, with its scope) so the System-2 overhead is
+   * billed to the right bucket under `function: 'ideation'`. Defaults to the
+   * master executive when unset.
+   */
+  meta?: LLMCallMeta
+}
+
+/**
+ * Run the propose (ideation) pass: one non-streaming LLM call at elevated temperature,
+ * returning the parsed candidate set. The call is internal scratch (nothing streams to a
+ * user). A failure or empty parse degrades gracefully to `undefined`, so the caller then
+ * proceeds exactly as System 1 (no candidates injected). R2-safe: the distinct ideation
+ * prompt gets its own replay entry at this tick.
+ */
+export async function proposeCandidates( params: ProposeParams ): Promise<IdeationCandidate[] | undefined> {
+  try {
+    const result = await params.director.call(
+      params.systemPrompt, params.ideationUserMessage, params.tick, params.proposeTemperature,
+      params.meta ?? { category: 'executive', attribute: 'master', function: 'ideation' }
+    )
+    const candidates = parseIdeation( result.text ).candidates
+    return candidates.length > 0 ? candidates : undefined
+  }
+  catch {
+    return undefined  // degrade to System 1 — never let a flaky propose pass break a tick
+  }
+}

package/src/cognition/faculties/executive.engine/effort.gate.ts

@@ -0,0 +1,114 @@
+// ─────────────────────────────────────────────────────────────
+// src/cognition/faculties/executive.engine/effort.gate.ts
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Dual-process control for the master executive.
+ *
+ * The master reasons in one of two processes per tick:
+ *   - **System 1 (`fast`)** — the single-shot call. Quick, habitual, low-effort; the
+ *     default for routine ticks.
+ *   - **System 2 (`deliberate`)** — an effortful propose→evaluate pass, engaged only
+ *     when the situation demands the effort.
+ *
+ * `selectProcess` is the *a-priori* gate: it chooses BEFORE any LLM call, from signals
+ * already computed this tick, so there is no wasted work and (unlike post-hoc
+ * escalation) no risk of streaming an intuition we then override. It is a pure,
+ * deterministic function of those signals (R2): no wall-clock, no RNG.
+ *
+ * This is deliberately the one seat where effort allocation lives. Two things grow
+ * here later, on this same seam:
+ *   - the `DELIBERATE_THRESHOLD` becomes a persona-prior-developable disposition (an
+ *     analytical / conscientious Will lowers it ⇒ deliberates more readily; an impulsive
+ *     one raises it), unifying dual-process with the trait system; and
+ *   - a System-1→System-2 *escalation* hook (System 1 runs, then raises its hand when
+ *     unsure) — which is why the deliberate path reports its own confidence.
+ */
+
+/** Which cognitive process the master runs this tick. */
+export type CognitiveProcess = 'fast' | 'deliberate'
+
+/** A-priori signals (all available before the master's LLM call) driving the choice. */
+export interface EffortSignals {
+  /** Epistemic uncertainty for this tick (0..1). Higher ⇒ deliberate. */
+  epistemicUncertainty: number
+  /** Confidence on the master's *previous* decision (0..1). Lower ⇒ deliberate. */
+  priorConfidence: number
+  /** Perceptual novelty (0..1). Higher ⇒ deliberate. */
+  novelty: number
+  /** Stress load (0..100). High load flags a situation that matters ⇒ deliberate. */
+  stressLoad: number
+  /** A human message is awaiting a reply this tick. A social, stakes-bearing moment. */
+  hasPendingMessage: boolean
+}
+
+export interface ProcessSelection {
+  process: CognitiveProcess
+  /** Aggregate effort demand (0..1) that drove the choice — telemetry + future tuning. */
+  effortScore: number
+  /** The dominant contributor (auditability), e.g. `deliberate:uncertainty`. */
+  reason: string
+}
+
+// Contribution weights sum to 1, so effortScore ∈ [0,1]. Tunable; see the module note
+// on making the threshold persona-prior-developable.
+const W_UNCERTAINTY    = 0.30
+const W_LOW_CONFIDENCE = 0.25
+const W_NOVELTY        = 0.20
+const W_PENDING        = 0.15
+const W_STRESS         = 0.10
+
+/** Effort demand at/above which the master engages System 2 (deliberate). */
+export const DELIBERATE_THRESHOLD = 0.5
+
+const clamp01 = ( x: number ): number => Math.max( 0, Math.min( 1, x ) )
+
+/**
+ * Choose the master's cognitive process for this tick. Pure + deterministic.
+ * System 1 (`fast`) is the default; System 2 (`deliberate`) is engaged when the
+ * weighted effort demand crosses `threshold`.
+ *
+ * `threshold` defaults to `DELIBERATE_THRESHOLD` but is passed in by the engine as the
+ * *effective* threshold (base ⊕ persona-prior): an analytical Will develops a lower
+ * threshold and so deliberates more readily — effort allocation as a developing trait.
+ */
+export function selectProcess(
+  signals: EffortSignals,
+  threshold: number = DELIBERATE_THRESHOLD,
+): ProcessSelection {
+  const contributions: Array<[ string, number ]> = [
+    [ 'uncertainty',    W_UNCERTAINTY    * clamp01( signals.epistemicUncertainty ) ],
+    [ 'low_confidence', W_LOW_CONFIDENCE * ( 1 - clamp01( signals.priorConfidence ) ) ],
+    [ 'novelty',        W_NOVELTY        * clamp01( signals.novelty ) ],
+    [ 'pending_reply',  W_PENDING        * ( signals.hasPendingMessage ? 1 : 0 ) ],
+    [ 'load',           W_STRESS         * clamp01( signals.stressLoad / 100 ) ],
+  ]
+
+  const effortScore = contributions.reduce( ( sum, [ , v ] ) => sum + v, 0 )
+  const dominant    = contributions.reduce( ( a, b ) => ( b[ 1 ] > a[ 1 ] ? b : a ) )[ 0 ]
+  const deliberate  = effortScore >= threshold
+
+  return {
+    process:     deliberate ? 'deliberate' : 'fast',
+    effortScore,
+    reason:      deliberate ? `deliberate:${dominant}` : 'fast',
+  }
+}
+
+// ── Ideation temperature (closes TODO edge #4) ────────────────
+
+/** Safe sampling-temperature band for the ideation (propose) pass. */
+export const IDEATION_TEMP_MIN = 0.6
+export const IDEATION_TEMP_MAX = 1.0
+
+/**
+ * Map the `creativity` self-model trait (0..1) to the ideation pass's sampling
+ * temperature. A more creative Will diverges harder when proposing options. Bounded to
+ * [IDEATION_TEMP_MIN, IDEATION_TEMP_MAX] so the *decision* pass (provider default) is
+ * never destabilised. This closes TODO edge #4 — and cleanly, because temperature now
+ * lives only on the isolated ideation call, not the fused decision call. As the
+ * creativity trait develops in the self-model, this rises with it for free.
+ */
+export function ideationTemperature( creativity: number ): number {
+  return IDEATION_TEMP_MIN + clamp01( creativity ) * ( IDEATION_TEMP_MAX - IDEATION_TEMP_MIN )
+}