@mindot/will 0.9.0 → 0.10.0

package/src/cognition/faculties/executive.engine/escalation.buffer.ts

@@ -31,6 +31,7 @@
 // ─────────────────────────────────────────────────────────────
 
 import type { EntityInput } from '#core/types'
+import { perceptEntity } from '#cognition/percept.entity'
 
 /**
  * Work the master should plan or re-goal. The facet has already said whatever
@@ -42,14 +43,33 @@ export interface EscalationHandoff {
 }
 
 /**
- * An intention toward a THIRD party — "I'll reach out to FKEM now" — formed
- * while attending to something else. The facet never opens that channel itself,
- * so this is the only thing standing between having decided to make contact and
- * having made it.
+ * SOMETHING I SAID I WOULD DO, declared by the part of me that said it.
+ *
+ * It was `{ target, gist }` — a contact and nothing else — because the defect it
+ * was built for was capability-shaped rather than promise-shaped: a conversation
+ * facet can speak in its own thread but cannot open a channel to a third party,
+ * so the handoff carried the one act it structurally could not perform. Named
+ * "undertaking" and dressed in promise language, it read as a general commitment
+ * system with a strange restriction, and it was not one.
+ *
+ * `what` is the commitment in the mind's own words — "reach FKEM about the demo",
+ * "have the scoping doc by Friday", "look into the pricing". `target` is set only
+ * when it is toward someone the mind would have to REACH, which is still the case
+ * the tract exists for; a promise about work has no target and needs none.
+ *
+ * Note what this deliberately does NOT become: a task list. It is filed beside
+ * what the facet concluded and read once by the master, which may make a goal of
+ * it — the conversation format already says to raise [GOALS_NEW] for anything to
+ * follow through on, and goals are the thing that persists. This only ensures the
+ * seat that decides never learns of it too late to decide.
  */
 export interface UndertakingHandoff {
   kind:      'undertaking'
-  target:    string
+  /** What I said I would do, in my own words. */
+  what:      string
+  /** Who it is toward — only when keeping it means reaching someone. */
+  target?:   string
+  /** The words I had in mind for them, when I had any. */
   gist?:     string
   reasoning: string
 }
@@ -68,11 +88,18 @@ export function validateFacetHandoff( payload: unknown ): string | null {
   if( !body || typeof body !== 'object') return 'payload.body is required'
   const kind = ( body as { kind?: unknown } ).kind
   if( kind === 'escalation') return null
-  if( kind === 'undertaking')
-    return typeof ( body as { target?: unknown } ).target === 'string'
-        && ( body as { target: string } ).target.trim().length > 0
+  if( kind === 'undertaking'){
+    // `what` is the requirement now, not `target`. A promise about work has no
+    // one to reach and is still a promise; a promise with a target but nothing
+    // said is not one.
+    const what = ( body as { what?: unknown } ).what
+    if( typeof what !== 'string' || what.trim().length === 0 )
+      return 'undertaking handoff requires a non-empty what'
+    const target = ( body as { target?: unknown } ).target
+    return target === undefined || ( typeof target === 'string' && target.trim().length > 0 )
       ? null
-      : 'undertaking handoff requires a non-empty target'
+      : 'undertaking handoff target, when present, must be a non-empty string'
+  }
   return `unknown handoff kind: ${String( kind )}`
 }
 
@@ -126,6 +153,26 @@ export class EscalationBuffer {
    * Convert every buffered handoff into a high-salience percept entity and clear
    * the buffer. Returns the percepts plus the first handoff's requester context
    * (used to tag goals the master creates in response).
+   *
+   * WHY THESE DO NOT GO THROUGH A SENSE DOOR (SIGNAL_BOUNDARY P4).
+   *
+   * P4's rule is that only a sense or exteroception writes a percept, and these
+   * two are the standing exception. A sense door carries AFFERENCE: a signal
+   * crossing into the mind, either from the world (exafferent) or from the
+   * mind's own act returning THROUGH the world (reafferent). A facet handing off
+   * to the master crosses neither boundary — it never left the mind. Routing it
+   * through a sense would dress one part of a mind up as news from outside,
+   * which is precisely the laundering P1 removed from `inspect`, and §6 of the
+   * epoch names that class of over-unification as the thing not to do.
+   *
+   * They still had to stop being hand-rolled literals, and they have: everything
+   * goes through `perceptEntity()`, so the shape is the one shape.
+   *
+   * What is left open, and worth deciding rather than inheriting: a handoff is
+   * using the percept entity as a DELIVERY MECHANISM, because the percept block
+   * is what the executive prompt renders. A `self.handoff` type with its own
+   * section would say what this actually is. That is a prompt change and a
+   * `_reconcileUndertakings` change, so it is a decision, not a cleanup.
    */
   drainToPercepts(): DrainedEscalations {
     const percepts: EntityInput[] = []
@@ -136,63 +183,83 @@ export class EscalationBuffer {
       // silently collapse them into whichever came last.
       const id = `escalation-percept-${h.subjectEntityId ?? h.facetId ?? 'self'}-${h.tick}-${seq++}`
 
-      const common = {
+      // FACTS the builder owns, and the writer's OWN fields beside them. Split
+      // this way because `perceptEntity()` spreads `extra` first: a writer can
+      // add whatever it likes and still cannot clobber `tick` or `provenance`.
+      const core = {
+        id,
+        tick:     h.tick,
         salience: 0.85,
-        source:   'executive-facet',
+        // REAFFERENT. Nothing outside the mind produced this: a facet of it
+        // raised the handoff, and the master is now noticing its own part's
+        // doing. Tagging it costs no behaviour — the rupture gate excludes
+        // reafferent and untagged alike — but it stops the exclusion being an
+        // accident, and it is the honest answer rather than the convenient one.
+        provenance: 'reafferent' as const,
         ...( h.subjectEntityId ? { entityId: h.subjectEntityId } : {} ),
-        ...( h.threadId        ? { threadId: h.threadId }        : {} ),
-        ...( h.facetId         ? { facetId:  h.facetId  }        : {} ),
+      }
+      const mine = {
+        source: 'executive-facet',
+        ...( h.threadId ? { threadId: h.threadId } : {} ),
+        ...( h.facetId  ? { facetId:  h.facetId  } : {} ),
       }
 
+      // Built through `perceptEntity()` like every other percept in the package
+      // (SIGNAL_BOUNDARY P4). These were the last hand-rolled `type: 'percept'`
+      // literals, and a hand-rolled one is exactly how `tick` went missing on
+      // the wake and delivery percepts and made them immortal.
+      //
+      // They do NOT go through a sense door, and should not — see the note on
+      // `drainToPercepts` above for why.
       percepts.push( h.body.kind === 'undertaking'
-        ? {
-          id,
-          type: 'percept',
-          metadata: {
-            ...common,
-            category: 'undertaking',
-            // First person: this is the mind noticing what IT said it would do, not
-            // a report handed to it. What makes it act is that the words are still
-            // unsent — an undertaking it has already honoured reads the same until
-            // it checks, which is exactly the check we want it making.
-            // Everything actionable goes in `summary`: that is the only field the
-            // executive context actually renders (context.ts extractPercepts reads
-            // summary/content and nothing else).
-            //
-            // The closing clause is the whole point. A mind that has SAID it will make
-            // contact remembers deciding, and cannot tell from the inside whether the
-            // words went out — so it follows up on a message it never sent. Naming the
-            // gap is what lets it check. It stays a decision either way: it may have
-            // changed its mind, or judge this the wrong moment, and a reach-out
-            // competes with everything else like any other action.
-            summary: `${whereItHappened( h )} I said I would reach ${h.body.target}`
-              + ( h.body.gist ? ` — what I meant to say: "${h.body.gist.slice( 0, 220 )}"` : '')
-              + `. Nothing has gone to them yet; saying it in that conversation did not send it.`
-              + ` If I still mean it, I reach out with target '${h.body.target}'.`
-              + ` If I no longer do, I let it go — but I do not leave it half-done while telling them it is handled.`,
-            // Who was promised, and when the promise was made. The executive
-            // reconciles against these (see _reconcileUndertakings): once the mind
-            // has actually reached this target since `tick`, the percept is retired
-            // rather than left standing as a claim the words are still unsent.
-            undertakingTarget: h.body.target,
-            tick:              h.tick,
-          },
-        }
-        : {
-          id,
-          type: 'percept',
-          metadata: {
-            ...common,
-            category: 'task-escalation',
-            // The steer lives IN the summary because that is the only field the
-            // executive context renders (context.ts extractPercepts reads
-            // summary/content and nothing else). It sat in a sibling `directive`
-            // field for its whole life and never once reached the master.
-            summary: `[Task from ${h.subjectName ?? h.subjectEntityId ?? 'my own focused work'}] ${h.body.reasoning}`
-              + ' — this is mine to plan or re-goal; the part of me that raised it handles the talking.',
-            tick: h.tick,
+        ? perceptEntity( {
+          ...core,
+          category: 'undertaking',
+          // THE GAP, AND ONLY THE GAP. First person because the mind is noticing
+          // what IT said it would do, not because it is being told what to do
+          // about it. A mind that has said it will make contact remembers
+          // deciding and cannot tell from the inside whether the words went out
+          // — so it follows up on a message it never sent. Naming the gap is
+          // what lets it check; naming the remedy was never this line's job.
+          //
+          // What used to follow this sentence: "If I still mean it, I reach out
+          // with target 'X'. If I no longer do, I let it go — but I do not leave
+          // it half-done while telling them it is handled." An instruction
+          // naming an effector and its argument, and a value judgement, both
+          // written in the mind's own voice so it could not disagree with
+          // either. The pull now lives in the affordance field where it can be
+          // out-competed, and the judgement belongs to a persona, not a buffer.
+          summary: `${whereItHappened( h )} I said I would reach ${h.body.target}`
+            + `. Nothing has gone to them since; saying it in that conversation did not send it.`,
+        }, {
+          ...mine,
+          // Who was promised, and when the promise was made. The executive
+          // reconciles against these (see _reconcileUndertakings): once the mind
+          // has actually reached this target since `tick`, the percept is retired
+          // rather than left standing as a claim the words are still unsent.
+          undertakingTarget: h.body.target,
+          // The EVIDENCE, rendered beneath the label since P2 — which is what
+          // makes the prose above unnecessary. `gist` is what the mind meant to
+          // say; it is a fact about the promise, not a script for keeping it,
+          // and it is carried whole rather than clipped into a sentence.
+          data: {
+            target:     h.body.target,
+            promisedAt: h.tick,
+            ...( h.subjectName ?? h.subjectEntityId ? { promisedTo: h.subjectName ?? h.subjectEntityId } : {} ),
+            ...( h.body.gist ? { gist: h.body.gist } : {} ),
+            contactedSince: false,
           },
         } )
+        : perceptEntity( {
+          ...core,
+          category: 'task-escalation',
+          // What was raised, and by which part of me. It used to close with
+          // "this is mine to plan or re-goal; the part of me that raised it
+          // handles the talking" — a role instruction. Whether to plan it,
+          // re-goal it or drop it is the master's call, and it has a whole
+          // faculty for making it.
+          summary: `[Raised by ${h.subjectName ?? h.subjectEntityId ?? 'my own focused work'}] ${h.body.reasoning}`,
+        }, mine ) )
     }
 
     // Capture requester context before clearing — used to tag new goals. Only a

package/src/cognition/faculties/executive.engine/facet.supervisor.ts

@@ -333,6 +333,11 @@ export class FacetSupervisor {
       type:        'executive.facet.destroy',
       tick:        this._lastStateRef?.tick as unknown as number ?? 0,
       facetId,
+      // The key a reader needs to tell the two populations apart. A KEYED facet
+      // dying is a conversation ending; a keyless one dying is a deliberation
+      // finishing, which is what the executive does every time it thinks. Without
+      // it a churn metric counts both and reads engagement as damage.
+      ...( key ? { key } : {} ),
       reason,
       totalFacets: this._facets.size,
     } as any)
@@ -519,6 +524,11 @@ export class FacetSupervisor {
           type:      'executive.facet.destroy',
           tick:      this._lastStateRef?.tick as unknown as number ?? 0,
           facetId,
+          ...( key ? { key } : {} ),
+          // Named so the three ways a facet can end are distinguishable in a
+          // trace: its owner closed it, the TTL took a quiet one, or pressure
+          // evicted it. Only the last two are ever a symptom.
+          reason:    'explicit',
           totalFacets: this._facets.size,
         } as any)
       }

package/src/cognition/faculties/executive.engine/parser.ts

@@ -3,7 +3,7 @@
 // ─────────────────────────────────────────────────────────────
 
 import { logger } from '#core/logger'
-import { REPLY_TEXT_TAG, NO_MESSAGE_TAG, NO_MESSAGE_OPEN } from '#llm/wire.contracts'
+import { REPLY_TEXT_TAG, NO_MESSAGE_TAG, NO_MESSAGE_OPEN, stripProtocolMarkers } from '#llm/wire.contracts'
 import type { ReadonlySimulationState } from '#core/types'
 import type { ExecutiveOutputFull, ExecutiveOutputMinimal, IdeationCandidate, IdeationOutput } from '#faculties/executive.engine/types'
 
@@ -27,7 +27,9 @@ export function parseResponse(
 
   let
   actions: Array<{ type: string; reasoning: string; expectedOutcome: string }>,
-  confidence = 0.5
+  confidence = 0.5,
+  /** The mind's own sentence, when the response parsed as JSON and carried one. */
+  stated: string | undefined
 
   // Strategy 1: direct JSON.parse
   try {
@@ -41,6 +43,7 @@ export function parseResponse(
 
     actions = parsed.actions
     confidence = parsed.confidence ?? 0.5
+    stated = typeof parsed.reasoning === 'string' ? parsed.reasoning : undefined
   }
   catch {
     // Strategy 2: balanced-bracket extractor
@@ -60,9 +63,28 @@ export function parseResponse(
     confidence = confidenceMatch ? parseFloat( confidenceMatch[1]! ) : 0.5
   }
 
-  // Parse tagged blocks from the extracted JSON text
+  // Tagged blocks are scanned over the FULL text — they are documented as embedded
+  // in the reasoning field, but a model puts them wherever it likes and the scan
+  // has always been forgiving about that. Keep that surface.
   const full = parseTaggedBlocks({ actions, reasoning: fullText, confidence }, state )
 
+  // …but `reasoning` itself is the mind's SENTENCE, not its serialization.
+  //
+  // It was `fullText` — the whole JSON blob — for every consumer downstream, and
+  // that was invisible for as long as nothing read it as prose. Three things do:
+  // the session log records it, a facet is handed the master's as "What I've Been
+  // Turning Over" (clipped to 400 chars, so facets have been reading the master's
+  // JSON truncated mid-object), and the master now reads a facet's back as what it
+  // worked out. Seen live in a prompt: `What I worked out there: { "actions": [...
+  //
+  // The scan surface and the sentence were the same string only because nothing
+  // had ever needed them to be different.
+  // Stripped of the tagged blocks, because the format tells the mind to embed them
+  // IN this field — so the sentence and the structured payload arrive in one
+  // string, and handing the whole thing back as "what I worked out" would just
+  // move the serialization problem one level in.
+  if( stated ) full.reasoning = stripTaggedBlocks( stated )
+
   // [REPLY_TEXT] is a plain-text block that lives OUTSIDE the JSON code block.
   // Search the full response text so we find it even when the LLM used a code fence.
   const replyText = extractTextBlock( responseText, REPLY_TEXT_TAG )
@@ -176,6 +198,29 @@ function extractBalancedArray( text: string, key: string ): string | null {
   return null
 }
 
+/** Every block name the reasoning field may carry, for stripping it back to prose. */
+const TAGGED_BLOCK_NAMES = [
+  'PLANS', 'BELIEFS', 'INTROSPECTION', 'NARRATIVE', 'IDENTITY', 'KNOWN_ENTITIES',
+  'GOALS_NEW', 'GOALS_ABANDON', 'GOALS_REPRIORITIZE', 'EFFECTORS', 'SELF_OBS',
+  'SKILLS', 'REPLY_TEXT', 'ACK',
+] as const
+
+/**
+ * The sentence, with the structured payload taken back out of it.
+ *
+ * Unclosed blocks are cut to the end of the string on purpose: a truncated
+ * `[PLANS]{…` is not prose either, and leaving it in puts half a JSON object in
+ * front of whoever reads this as the mind's thinking.
+ */
+export function stripTaggedBlocks( reasoning: string ): string {
+  let out = reasoning
+  for( const tag of TAGGED_BLOCK_NAMES )
+    out = out
+      .replace( new RegExp( `\\[${ tag }\\][\\s\\S]*?\\[/${ tag }\\]`, 'g'), '')
+      .replace( new RegExp( `\\[${ tag }\\][\\s\\S]*$`, 'g'), '')
+  return out.replace( /\n{3,}/g, '\n\n').trim()
+}
+
 /**
  * Parse tagged JSON blocks from the reasoning text.
  * The LLM embeds optional outputs as [TAG]...[/TAG] blocks.
@@ -339,7 +384,15 @@ function extractBlock( text: string, tag: string ): string | null {
  * Used for [REPLY_TEXT] — content is streamed directly to the client,
  * so it must be clean prose, not a JSON payload.
  */
-function extractTextBlock( text: string, tag: string ): string | null {
+/**
+ * Pull one plain-text block out of a response.
+ *
+ * Exported for the guard: this slice is where a stray marker survives into
+ * content, and the seam is the thing worth testing. `parseResponse` needs a full
+ * well-formed response around it, which is exactly the setup that hides a defect
+ * living in one line of string handling.
+ */
+export function extractTextBlock( text: string, tag: string ): string | null {
   const open  = `[${tag}]`
   const close = `[/${tag}]`
   const openIdx  = text.indexOf( open )
@@ -350,51 +403,60 @@ function extractTextBlock( text: string, tag: string ): string | null {
     ? text.slice( contentStart, closeIdx )
     : text.slice( contentStart )   // unclosed block — take everything after the open marker
 
-  return content.trim() || null
+  // A stray marker INSIDE the body survives this slice — the block runs from the
+  // first open to the first close after it, and anything between is content by
+  // construction. Live, a reply went out as four substantive bubbles and a fifth
+  // reading exactly `[REPLY_TEXT]`: the person received a message whose whole
+  // content was the name of the slot it should have filled.
+  return stripProtocolMarkers( content ) || null
 }
 
 /**
- * Build a heuristic fallback output when LLM response parsing fails.
- * Chooses actions based on current physiological state.
+ * What the executive intends when its own reasoning did not come back.
+ *
+ * Two things had to change here. Every action this produced was PROSE, not a
+ * schema: `observe`, `replenish energy`, `enter deep rest to reduce fatigue`,
+ * `calm my mind and reduce tension`, `explore`, `learn`, `express_emotion`.
+ * Only `rest` names anything the body can enact. The rest reach the agency, fail
+ * to resolve, and become an ideomotor push toward an act that does not exist —
+ * observed live as `master decided [observe] conf=0.4` four times across two
+ * boots, each one a decision that could go nowhere.
+ *
+ * And the "no urgent need" branch was INVENTION. The executive could not read
+ * its own thought, so it made one up and pushed it into the field as intention.
+ * That is the mind being told what it wants. The substrate does not need the
+ * help: the affordance field is always there, System 1 selects from it every
+ * tick without an executive, and it now carries real satiation — the monotony
+ * this used to break by cycling a hardcoded list is handled where monotony
+ * actually lives.
+ *
+ * So: reflexes stay, invention goes. Critically low energy, high sleep pressure
+ * or high stress still push a real regulatory stance, because a body in trouble
+ * should not depend on an LLM parsing correctly. Anything else yields NO action
+ * and lets the substrate decide, which is what it is for.
  */
 export function buildFallbackOutput(
   state: ReadonlySimulationState,
-  recentActionTypes: string[]
+  _recentActionTypes: string[]
 ): ExecutiveOutputFull {
-  const energy = state.metrics.get('energy.level') ?? 100
+  const energy        = state.metrics.get('energy.level')  ?? 100
   const sleepPressure = state.metrics.get('sleep.pressure') ?? 0
-  const stressLoad = state.metrics.get('stress.load') ?? 0
-
-  let actionType = 'observe'
-  let actionReason = 'No urgent needs — observing surroundings.'
+  const stressLoad    = state.metrics.get('stress.load')    ?? 0
 
-  if( energy < 20 ){
-    actionType = 'replenish energy'
-    actionReason = 'Energy critically low — attempting to rest.'
-  }
-  else if( sleepPressure > 60 ){
-    actionType = 'enter deep rest to reduce fatigue'
-    actionReason = 'Sleep pressure high — attempting to sleep.'
-  }
-  else if( stressLoad > 70 ){
-    actionType = 'calm my mind and reduce tension'
-    actionReason = 'Stress elevated — attempting to meditate.'
-  }
-  else {
-    // Vary the fallback when low-effort actions have dominated recently
-    const monotonous = recentActionTypes.filter( t => t === 'reflect' || t === 'observe').length >= 3
-    if( monotonous) {
-      const alternatives = ['explore', 'learn', 'express_emotion', 'rest']
-      const tick = state.tick as number
-
-      actionType = alternatives[ tick % alternatives.length ]!
-      actionReason = 'Breaking monotony — choosing a varied action during LLM fallback.'
-    }
-  }
+  // Innate stances only — what the body can actually enact.
+  const reflex: { type: string; reasoning: string } | null =
+      energy < 20        ? { type: 'rest',     reasoning: 'Energy critically low — I let myself recover.' }
+    : sleepPressure > 60 ? { type: 'rest',     reasoning: 'Sleep pressure high — I let myself recover.' }
+    : stressLoad > 70    ? { type: 'withdraw', reasoning: 'Stress elevated — I pull back from the press of things.' }
+    : null
 
   return {
-    actions: [{ type: actionType, reasoning: actionReason, expectedOutcome: 'State improves' }],
-    reasoning: `Heuristic fallback — LLM unavailable. ${actionReason}`,
+    actions: reflex
+      ? [ { type: reflex.type, reasoning: reflex.reasoning, expectedOutcome: 'The body settles' } ]
+      : [],
+    reasoning: reflex
+      ? `Heuristic fallback — my reasoning did not come back. ${ reflex.reasoning }`
+      : 'Heuristic fallback — my reasoning did not come back, and nothing about my state is pressing. I intend nothing in particular; my body goes on choosing.',
     confidence: 0.4
   }
 }