@mindot/will 0.8.0 → 0.10.0

package/src/cognition/agency/settlement.ts

@@ -0,0 +1,203 @@
+// ─────────────────────────────────────────────────────────────
+// src/agency/settlement.ts  —  having thought about it
+// ─────────────────────────────────────────────────────────────
+//
+// The agency has always been able to represent having ACTED. It could not
+// represent having DECIDED.
+//
+// System 2 is recruited when the field is ambiguous — `margin < marginGate` in
+// the ActionSelector, where margin is the activation gap between the top two
+// affordances. The DeliberationEngine then resolves the contest and writes back
+// exactly one thing: that intent flipped to 'selected', carrying `deliberated:
+// true`. Nothing reads `deliberated`. The synthesizer rebuilds the field from
+// scratch next tick, the same rivals score the same, the margin is again below
+// the gate, and the same question is deliberated again.
+//
+// Measured on a live COO over 7 hours: 149 deliberations, median gap between
+// them 17 seconds, 139 of 148 gaps under a minute — one LLM call every ~3 ticks
+// for the whole run, and the single largest line in her cost. She could see it
+// and had no mechanism to leave it:
+//
+//   "Nothing has changed since my last ten deliberation cycles. Goal-7 is
+//    externally blocked — this is a fact, not a diagnosis I need to reach again."
+//   "I have composed the same message to FKEM across twelve deliberation cycles
+//    and not sent it."
+//   "There is nothing left to deliberate. I am looking."
+//
+// So: a settlement is the trace a verdict leaves in the field it was called in
+// to resolve. It is the missing peer of a family the engine already has —
+// having acted damps re-acting (`justEnacted`), having spoken damps re-speaking
+// (`spokeAnywhereAt`), having committed can be withdrawn (revocation
+// tombstones) — and having thought damped nothing at all.
+//
+// The mechanism is deliberately ONE quantity doing both jobs. Raising the
+// settled option's activation means (a) the verdict has force, so System 1 does
+// not coin-flip its way to a different answer on the next tick of the same flat
+// field, and (b) the margin to the runner-up widens past the gate, so System 2
+// is not recruited for a question it has already answered. The flatness is what
+// summoned deliberation; the verdict is what gives the field the shape it
+// lacked.
+//
+// And it DECAYS, like everything else here. This is a refractory period, not a
+// lock — the user's objection to "a hard conditional gate that does not promise
+// any flexibility or dynamism of the mind" is the whole design constraint. As
+// the settlement ages the field flattens again and the question genuinely
+// re-opens; a rupture revokes it outright through the machinery that already
+// exists. A mind may always change its mind. It should not have to reach the
+// same conclusion every three seconds to keep holding it.
+// ─────────────────────────────────────────────────────────────
+
+import type { EntityInput, Tick } from '#core/types'
+
+export const SETTLEMENT_TYPE = 'agency.settlement'
+
+/**
+ * Ticks a verdict holds before the question is genuinely open again.
+ *
+ * Set to the satiation window rather than the echo window, and the symmetry is
+ * the argument: having thought about something should hold about as long as
+ * having done it. The echo window (`CONSEQUENCE_TTL_TICKS`, 30) answers "could
+ * the world still be replying to me" — a different and necessarily shorter
+ * question that has nothing to do with whether a choice is settled.
+ *
+ * At the COO's observed rate (~5s/tick) this is roughly five minutes of held
+ * verdict, against a mind that was re-deciding every three ticks.
+ */
+export const SETTLEMENT_TTL_TICKS = 60
+
+export interface SettlementDescriptor {
+  /** The act that won the contest. */
+  schema:          string
+  /** Its object, when it has one — keyed exactly as satiation is, on purpose. */
+  targetEntityId?: string
+  /**
+   * The rivals it was weighed against.
+   *
+   * Not used for matching — a settlement is keyed on what WON, so a slightly
+   * differently-framed contest still meets a verdict the mind has already
+   * reached. Carried because "I decided this over that" is the introspectable
+   * fact, and a settlement with no memory of what it beat is a preference with
+   * no reason attached.
+   */
+  over?:           readonly string[]
+  tick:            Tick
+  expiresAt:       Tick
+}
+
+/** Stable id — one settlement per (schema, target), so re-deciding refreshes it. */
+export function settlementId( schema: string, targetEntityId?: string ): string {
+  return `agency-settlement-${ schema }${ targetEntityId ? `-${ targetEntityId }` : '' }`
+}
+
+/** Build the settlement entity. Ordinary state, so it snapshots and replays (FN9). */
+export function settlementEntity( d: SettlementDescriptor ): EntityInput {
+  return {
+    id:   settlementId( d.schema, d.targetEntityId ),
+    type: SETTLEMENT_TYPE,
+    metadata: { ...d, ...( d.over ? { over: [ ...d.over ] } : {} ) },
+  }
+}
+
+/**
+ * Read a settlement back off entity metadata.
+ *
+ * Decoded field-for-field, including `over`. A value written by one side and
+ * never read by the other is the defect shape this codebase has now hit six
+ * times, and it is the exact defect this module exists to fix — `deliberated:
+ * true` was written on every deliberated intent and read by nobody.
+ */
+export function readSettlement(
+  m: ReadonlyMap<string, unknown> | Record<string, unknown> | undefined,
+): SettlementDescriptor | null {
+  const meta = ( m instanceof Map ? Object.fromEntries( m ) : m ?? {} ) as Record<string, unknown>
+  const schema = typeof meta['schema'] === 'string' ? meta['schema'] as string : undefined
+  if( !schema ) return null
+
+  const over = Array.isArray( meta['over'] )
+    ? ( meta['over'] as unknown[] ).filter( ( x ): x is string => typeof x === 'string' )
+    : undefined
+
+  return {
+    schema,
+    targetEntityId: typeof meta['targetEntityId'] === 'string' ? meta['targetEntityId'] as string : undefined,
+    ...( over && over.length > 0 ? { over } : {} ),
+    tick:      typeof meta['tick']      === 'number' ? meta['tick']      as number : 0,
+    expiresAt: typeof meta['expiresAt'] === 'number' ? meta['expiresAt'] as number : 0,
+  }
+}
+
+/** The live (unexpired) settlements in frozen state, in stable id order. */
+export function liveSettlements(
+  entities: ReadonlyMap<string, { type: string; metadata?: ReadonlyMap<string, unknown> | Record<string, unknown> }>,
+  tick:     Tick,
+  /**
+   * alias id → anchor id. Settlement is keyed exactly as satiation is — see the
+   * note on `settlementForce` — so it has to share satiation's id space too, or a
+   * verdict reached about a person under one id would not hold about them under
+   * the other. A function, not the table: see `liveConsequences`.
+   */
+  canon?: ( id: string ) => string,
+): SettlementDescriptor[] {
+  const out: Array<{ id: string; d: SettlementDescriptor }> = []
+
+  for( const [ id, e ] of entities ){
+    if( e.type !== SETTLEMENT_TYPE ) continue
+    const d = readSettlement( e.metadata )
+    if( !d ) continue
+    // Stamped LATER than now ⇒ restored from a previous session, where the tick
+    // counter restarts at 1 on wake. Without this a woken mind reads every
+    // settlement it ever made as freshly decided and cannot deliberate at all.
+    // The same trap `liveConsequences` documents, and the same fix.
+    if( d.tick > tick ) continue
+    if( tick < d.expiresAt )
+      out.push({ id, d: canon && d.targetEntityId
+        ? { ...d, targetEntityId: canon( d.targetEntityId ) }
+        : d })
+  }
+
+  return out.sort( ( a, b ) => ( a.id < b.id ? -1 : a.id > b.id ? 1 : 0 ) ).map( x => x.d )
+}
+
+/** Settlement ids that have aged out — swept by the DeliberationEngine. */
+export function expiredSettlementIds(
+  entities: ReadonlyMap<string, { type: string; metadata?: ReadonlyMap<string, unknown> | Record<string, unknown> }>,
+  tick:     Tick,
+): string[] {
+  const out: string[] = []
+  for( const [ id, e ] of entities ){
+    if( e.type !== SETTLEMENT_TYPE ) continue
+    const d = readSettlement( e.metadata )
+    if( d && tick >= d.expiresAt ) out.push( id )
+  }
+  return out
+}
+
+/**
+ * How much of a verdict on this (schema, target) is still standing, 1 → 0.
+ *
+ * Linear decay over the window, matching `enactionFootprint` — the two are
+ * mirror images and should feel the same from inside: one is the fading pull
+ * not to repeat an act, this is the fading weight of having already chosen.
+ *
+ * An objectless act matches an objectless settlement only. Deciding to `rest`
+ * says nothing about whether to `reach-out` to Ada, and a verdict that leaked
+ * across objects would be a mind that mistakes one question for another.
+ */
+export function settlementForce(
+  settlements:    readonly SettlementDescriptor[],
+  schema:         string,
+  targetEntityId: string | undefined,
+  tick:           Tick,
+  windowTicks:    number = SETTLEMENT_TTL_TICKS,
+): number {
+  if( windowTicks <= 0 ) return 0
+
+  let strongest = 0
+  for( const s of settlements ){
+    if( s.schema !== schema || s.targetEntityId !== targetEntityId ) continue
+    const remaining = ( windowTicks - ( tick - s.tick ) ) / windowTicks
+    if( remaining > strongest ) strongest = remaining
+  }
+
+  return strongest < 0 ? 0 : strongest > 1 ? 1 : strongest
+}

package/src/cognition/agency/types.ts

@@ -118,7 +118,7 @@ export interface Affordance {
   parameters:      Record<string, unknown>
   /** Bound target entity id, when the schema binds an entity. */
   targetEntityId?: string
-  /** Entity id of the percept / known-entity that evoked this (provenance). */
+  /** Entity id of the percept / known-entity that evoked this. */
   evokedBy?:       string
   /** Anticipated affective outcome −1..1 (learned, falling back to schema prior). */
   expectedValence: number
@@ -140,6 +140,29 @@ export interface Affordance {
    * competition WITHOUT bypassing it (the plan biases; the field still decides).
    */
   planBias?:       number
+  /**
+   * Top-down volitional bias 0..1 — set when the executive DELIBERATELY willed this
+   * affordance (source 'ideomotor'), carrying the confidence it decided with. Like
+   * planBias it lifts activation without bypassing the competition: a willed act must
+   * still out-compete the field, but it no longer arrives with the same standing as an
+   * ambient possibility. Without this term the ideomotor leg created candidates the
+   * arithmetic could not tell apart from idle ones, and a cheap unconditional reflex
+   * ('express', cost 0.02) beat a deliberate 'reach-out' 176 times out of 176.
+   */
+  willBias?:       number
+  /**
+   * Learned social standing of this affordance's addressee, −1..1 (0 = neutral or
+   * unknown). Set only for an act aimed at someone. Every input is LEARNED, none
+   * hardcoded: ReputationTracker's trustworthiness — which is fed by
+   * `interaction.occurred` and so only became live once inbound conversation reached
+   * social cognition (#113) — weighted by that model's own confidence, plus the mind's
+   * current affective tone as a gentle tilt on reaching out at all.
+   *
+   * This is what makes "they never answer me" reach the competition: it arrives as a
+   * fading opinion of a person the mind formed itself and can revise, not as a damping
+   * curve applied behind its back.
+   */
+  socialPrior?:    number
   /**
    * Policy availability 0..1 (POLICY_REAFFERENCE P2) — learned from refusals,
    * distinct from `available` (precondition satisfaction) and from competence.
@@ -149,6 +172,38 @@ export interface Affordance {
    * gets an occasional re-probe and can climb back as availability recovers.
    */
   availability?:   number
+  /**
+   * How much of this act's OWN footprint is still live, 1 → 0 (EXAFFERENCE P5).
+   * Set when a consequence descriptor for the same (schema, target) has not yet
+   * expired — the mind has just done this and does not yet know how it landed.
+   *
+   * Damps the pull to do it again, and decays back to 0 on its own, so a silence
+   * that starts to matter can still out-compete it. Without this the executive's
+   * standing `ideomotor.intent` outlived the act it produced: the same two
+   * messages were delivered to the same person three times, ~21 ticks apart,
+   * each time as though it were the first.
+   */
+  justEnacted?:    number
+  /**
+   * How much of a DELIBERATED verdict on this act is still standing, 1 → 0.
+   *
+   * The mirror of `justEnacted`: that one is the fading pull not to repeat
+   * something done, this is the fading weight of having already chosen. Set
+   * when System 2 resolved a contest in this act's favour and the settlement
+   * has not yet aged out.
+   *
+   * It does two things with one quantity, which is why it is a quantity and not
+   * a flag. The verdict gets force, so System 1 does not coin-flip its way to a
+   * different answer on the next tick of the same flat field; and the margin to
+   * the runner-up widens past the selector's gate, so System 2 is not recruited
+   * for a question it has already answered. Flatness is what summons
+   * deliberation — the verdict is what gives the field the shape it lacked.
+   *
+   * Without it, a live COO deliberated 149 times in 7 hours, median 17s apart,
+   * re-reaching the same conclusion about an externally-blocked goal until she
+   * wrote "this is a fact, not a diagnosis I need to reach again".
+   */
+  settled?:        number
   /** Provenance: the plan whose frontier step projected this affordance. */
   planId?:         string
   /** Provenance: the frontier step id — flows through to action.outcome so the plan advances. */
@@ -156,6 +211,23 @@ export interface Affordance {
   tick:            number
 }
 
+/**
+ * PlanLink — where an act sits in a plan: the frontier step it serves, if any.
+ * Rides on the `agency.outcome` so the PlanningEngine can advance the step the
+ * act was committed from.
+ *
+ * NAMED, AND NAMED THIS, BECAUSE IT USED TO BE CALLED `provenance`
+ * (SIGNAL_BOUNDARY P3). Two unrelated concepts shared that word in one codebase:
+ * this one, and `SignalProvenance` — whether a signal came from the world or
+ * from the mind's own act. The signal sense is the one the vocabulary needs, so
+ * this one gives the word up. An inline `{ planId?, stepId? }` in three
+ * signatures is also how the collision stayed invisible; a name can be grepped.
+ */
+export interface PlanLink {
+  planId?: string
+  stepId?: string
+}
+
 /**
  * EfferenceCopy — the forward model's prediction of an action's own consequences,
  * emitted *before* enaction so reafference has something to compare against.

package/src/cognition/cache/composition.ts

@@ -0,0 +1,232 @@
+// ─────────────────────────────────────────────────────────────
+// src/cognition/cache/composition.ts
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Compositional operators for cache interpolation.
+ *
+ * Design principle (from the research sketch): interpolate what is safe to
+ * interpolate, copy verbatim what is not. Executive actions carry free-text
+ * fields (`reasoning`, `expectedOutcome`) that would turn to gibberish under
+ * blending, so the ACTIONS block uses a weighted *vote* over action type and
+ * then copies the winning neighbor's action objects verbatim. Numeric scalars
+ * (goal priority, belief confidence) are the only fields we mean-blend.
+ *
+ * Every operator is deterministic: inputs arrive pre-sorted from the cache and
+ * ties are resolved by neighbor order (already deterministic), never by hashing.
+ */
+
+import type { ExecutiveOutputFull } from '#faculties/executive.engine/types'
+import type { ScoredNeighbor, CacheScope } from './types'
+
+/**
+ * Compose a valid ExecutiveOutputFull from scored neighbors. `neighbors` must be
+ * non-empty and ordered best-first (as the cache returns them). The three
+ * required fields (actions, reasoning, confidence) are always populated.
+ */
+export function composeOutput(
+  neighbors: ScoredNeighbor[],
+  tau: number,
+  scopes: CacheScope[],
+): ExecutiveOutputFull {
+  const weights = _softmaxWeights( neighbors, tau )
+
+  // The best neighbor anchors required fields when a scope leaves them empty.
+  const anchor = neighbors[ 0 ]!.pattern.output
+
+  const out: ExecutiveOutputFull = {
+    actions:    [],
+    reasoning:  anchor.reasoning ?? '',
+    confidence: anchor.confidence ?? 0.5,
+  }
+
+  if( scopes.includes('actions') ){
+    const composed = _composeActions( neighbors, weights )
+    out.actions    = composed.actions
+    out.reasoning  = composed.reasoning
+    out.confidence = composed.confidence
+  } else {
+    // Actions are required downstream — fall back to the anchor's verbatim actions.
+    out.actions = _clone( anchor.actions ?? [] )
+  }
+
+  if( scopes.includes('goals') )
+    out.newGoals = _composeGoals( neighbors, weights )
+
+  if( scopes.includes('beliefs') )
+    out.newBeliefs = _composeBeliefs( neighbors, weights )
+
+  return out
+}
+
+// ── Weight computation ─────────────────────────────────────
+
+function _softmaxWeights( neighbors: ScoredNeighbor[], tau: number ): number[] {
+  const t = tau > 0 ? tau : 1e-6
+  const sims = neighbors.map( n => n.similarity )
+  const maxSim = Math.max( ...sims )
+  const exps = sims.map( s => Math.exp( ( s - maxSim ) / t ) )  // shift for stability
+  const sum = exps.reduce( ( a, b ) => a + b, 0 )
+  return exps.map( e => ( sum === 0 ? 1 / exps.length : e / sum ) )
+}
+
+// ── ACTIONS: weighted type vote + verbatim copy ────────────
+
+function _composeActions(
+  neighbors: ScoredNeighbor[],
+  weights: number[],
+): { actions: ExecutiveOutputFull['actions']; reasoning: string; confidence: number } {
+  // Vote on each neighbor's primary (first) action type.
+  const typeWeight = new Map<string, number>()
+  for( let i = 0; i < neighbors.length; i++ ){
+    const acts = neighbors[ i ]!.pattern.output.actions ?? []
+    const primary = acts[ 0 ]?.type
+    if( primary === undefined ) continue
+    typeWeight.set( primary, ( typeWeight.get( primary ) ?? 0 ) + ( weights[ i ] ?? 0 ) )
+  }
+
+  // Winning type — deterministic: highest weight, ties broken by neighbor order
+  // (the first neighbor to reach the max keeps it, and neighbors are best-first).
+  let winningType: string | null = null
+  let bestWeight = -1
+  for( let i = 0; i < neighbors.length; i++ ){
+    const primary = neighbors[ i ]!.pattern.output.actions?.[ 0 ]?.type
+    if( primary === undefined ) continue
+    const w = typeWeight.get( primary ) ?? 0
+    if( w > bestWeight ){ bestWeight = w; winningType = primary }
+  }
+
+  // Copy the full action list from the highest-weight neighbor whose primary
+  // action type matches the winner — verbatim, so text fields stay coherent.
+  let source = neighbors[ 0 ]!
+  for( let i = 0; i < neighbors.length; i++ ){
+    if( neighbors[ i ]!.pattern.output.actions?.[ 0 ]?.type === winningType ){
+      source = neighbors[ i ]!
+      break
+    }
+  }
+
+  const src = source.pattern.output
+  return {
+    actions:    _clone( src.actions ?? [] ),
+    reasoning:  src.reasoning ?? '',
+    confidence: src.confidence ?? 0.5,
+  }
+}
+
+// ── GOALS: merge by description, mean priority (Phase 2) ────
+
+function _composeGoals(
+  neighbors: ScoredNeighbor[],
+  weights: number[],
+): ExecutiveOutputFull['newGoals'] {
+  type Agg = {
+    weight: number
+    priority: number
+    tags: string[]
+    completionType: string
+    completionCondition?: string
+    bestW: number
+  }
+  const byDesc = new Map<string, Agg>()
+
+  for( let i = 0; i < neighbors.length; i++ ){
+    const w = weights[ i ] ?? 0
+    for( const g of neighbors[ i ]!.pattern.output.newGoals ?? [] ){
+      const cur = byDesc.get( g.description )
+      if( cur ){
+        cur.weight += w
+        cur.priority += g.priority * w
+        if( w > cur.bestW ){
+          cur.bestW = w
+          cur.tags = g.tags
+          cur.completionType = g.completionType
+          cur.completionCondition = g.completionCondition
+        }
+      } else {
+        byDesc.set( g.description, {
+          weight: w,
+          priority: g.priority * w,
+          tags: g.tags,
+          completionType: g.completionType,
+          completionCondition: g.completionCondition,
+          bestW: w,
+        } )
+      }
+    }
+  }
+
+  const result: NonNullable<ExecutiveOutputFull['newGoals']> = []
+  for( const [ description, a ] of byDesc ){
+    result.push( {
+      description,
+      priority: a.weight === 0 ? 0 : a.priority / a.weight,
+      tags: [ ...a.tags ],
+      completionType: a.completionType,
+      ...( a.completionCondition !== undefined ? { completionCondition: a.completionCondition } : {} ),
+    } )
+  }
+  result.sort( ( x, y ) => y.priority - x.priority )
+  return result.slice( 0, 3 )
+}
+
+// ── BELIEFS: merge by statement, mean confidence (Phase 3) ─
+
+function _composeBeliefs(
+  neighbors: ScoredNeighbor[],
+  weights: number[],
+): ExecutiveOutputFull['newBeliefs'] {
+  type Agg = {
+    weight: number
+    confidence: number
+    category: string
+    evidence: 'single_observation' | 'recurring_pattern' | 'strong_pattern'
+    tags: string[]
+    bestW: number
+  }
+  const byStmt = new Map<string, Agg>()
+
+  for( let i = 0; i < neighbors.length; i++ ){
+    const w = weights[ i ] ?? 0
+    for( const b of neighbors[ i ]!.pattern.output.newBeliefs ?? [] ){
+      const cur = byStmt.get( b.statement )
+      if( cur ){
+        cur.weight += w
+        cur.confidence += b.confidence * w
+        if( w > cur.bestW ){
+          cur.bestW = w
+          cur.category = b.category
+          cur.evidence = b.evidence
+          cur.tags = b.tags
+        }
+      } else {
+        byStmt.set( b.statement, {
+          weight: w,
+          confidence: b.confidence * w,
+          category: b.category,
+          evidence: b.evidence,
+          tags: b.tags,
+          bestW: w,
+        } )
+      }
+    }
+  }
+
+  const result: NonNullable<ExecutiveOutputFull['newBeliefs']> = []
+  for( const [ statement, a ] of byStmt ){
+    result.push( {
+      statement,
+      category: a.category,
+      confidence: a.weight === 0 ? 0 : a.confidence / a.weight,
+      evidence: a.evidence,
+      tags: [ ...a.tags ],
+    } )
+  }
+  return result
+}
+
+// ── Deterministic deep clone for verbatim-copied blocks ────
+
+function _clone<T>( v: T ): T {
+  return JSON.parse( JSON.stringify( v ) ) as T
+}