@mindot/will 0.8.0 → 0.10.0

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@mindot/will",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "author": "Fabrice <fabrice8@github.com>",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/mindot-ai/will.git"
   },
   "bin": {
-    "will": "dist/cli.js"
+    "will": "dist/surface/cli.js"
   },
   "main": "./dist/index.js",
   "devDependencies": {
@@ -32,16 +32,16 @@
       "types": "./dist/index.d.ts"
     },
     "./mcp": {
-      "import": "./dist/mcp/effectors.js",
-      "types": "./dist/mcp/effectors.d.ts"
+      "import": "./dist/surface/mcp/effectors.js",
+      "types": "./dist/surface/mcp/effectors.d.ts"
     },
     "./discord": {
-      "import": "./dist/channels/discord.js",
-      "types": "./dist/channels/discord.d.ts"
+      "import": "./dist/surface/channels/discord.js",
+      "types": "./dist/surface/channels/discord.d.ts"
     },
     "./whatsapp": {
-      "import": "./dist/channels/whatsapp.js",
-      "types": "./dist/channels/whatsapp.d.ts"
+      "import": "./dist/surface/channels/whatsapp.js",
+      "types": "./dist/surface/channels/whatsapp.d.ts"
     }
   },
   "bugs": {
@@ -78,11 +78,10 @@
   "scripts": {
     "build": "tsup",
     "build:types": "tsc --project tsconfig.build.json",
-    "dev": "bun --env-file=.env run src/runners/thin-shim.runner.ts",
+    "dev": "bun --env-file=.env run examples/thin-shim.ts",
     "dev:build": "tsup --watch",
-    "run:social": "bun --env-file=.env run src/runners/social.runner.ts",
-    "run:outreach": "bun --env-file=.env run src/runners/outreach.runner.ts",
-    "start": "bun --env-file=.env run src/runners/thin-shim.runner.ts",
+    "run:social": "bun --env-file=.env run examples/social.ts",
+    "run:outreach": "bun --env-file=.env run examples/outreach.ts",
     "typecheck": "tsc --noEmit",
     "lint": "tsc --noEmit",
     "prepublishOnly": "bun run typecheck && bun test && bun run build",

package/src/cognition/agency/consequence.ts

@@ -52,6 +52,26 @@ export interface ConsequenceDescriptor {
   text?:           string
   /** FNV-1a over the canonicalized parameters (async dispatch). */
   paramsHash?:     number
+  /**
+   * Dispatched but NOT YET PERFORMED — a communicate held awaiting words that do
+   * not exist yet.
+   *
+   * The footprint is written when an intent goes to the async hold, which for an
+   * EXTERNAL effector is the act itself (the host is doing it now, and asking
+   * twice while waiting is the thing satiation should prevent). For a communicate
+   * it is not: the facet has not authored anything, and the mind has said nothing.
+   *
+   * Counting it as satiation meant ATTEMPTING to speak silenced the mind exactly
+   * as hard as speaking. Dormant until `justEnacted` first reached the
+   * competition, then immediately visible: a live COO willed `reach-out` 63 times
+   * in four minutes, delivered NOTHING, and 18 of those lost to `justEnacted`
+   * readings of 0.93–0.98 against a mind that had not spoken once that run. Each
+   * attempt wrote a fresh footprint, so the damping never decayed.
+   *
+   * P2's echo matching is unaffected — a pending descriptor carries no text to
+   * match on, which is the same fact from the other side.
+   */
+  pending?:        boolean
   expiresAt:       Tick
   tick:            Tick
 }
@@ -90,6 +110,80 @@ export function consequenceEntity( d: ConsequenceDescriptor ): EntityInput {
   }
 }
 
+// ── The durable enaction record — satiation's third source ───────────────────
+//
+// Descriptors are swept at the ECHO window (`CONSEQUENCE_TTL_TICKS`, 30) because
+// that answers "could the world still be replying to me". Satiation asks a
+// different and longer question (`repeatWindowTicks`, 60 by default), so the
+// second half of the satiation window had no carrier at all and silently damped
+// nothing.
+//
+// The codebase already hit this exact wall twice and closed it twice:
+//   • speaking  → `conversation.sent`, durable, read as `spokenAt`
+//   • objectless → `LearnedSkill.lastEnactedTick`, durable, read as `selfEnactedAt`
+//
+// The gap left was an act WITH an object that is NOT speech — `inspect`, and
+// every entity-bound host effector. `lastEnactedTick` cannot serve it: it is
+// per-schema, so "I just looked up Alice" would damp looking up Bob, which is
+// why the objectless branch is the only place it is consulted. So this is the
+// missing peer: per (schema, target), durable, on the satiation window.
+//
+// Measured on a live COO before this existed: entity-bound acts carried
+// satiation in 40–46% of competitions against 100% for objectless ones, and she
+// re-enacted `discord_lookup_member` toward the same person 33 times in seven
+// minutes.
+export const ENACTED_TYPE = 'agency.enacted'
+
+/** Stable id — one record per (schema, target), refreshed in place, so the set is
+ *  bounded by the pairs actually enacted rather than growing per enaction. */
+export function enactedId( schema: string, targetEntityId: string ): string {
+  return `agency-enacted-${ schema }-${ targetEntityId }`
+}
+
+/** Build/refresh the durable "I did this to them, then" record. */
+export function enactedEntity( schema: string, targetEntityId: string, tick: Tick ): EntityInput {
+  return {
+    id:   enactedId( schema, targetEntityId ),
+    type: ENACTED_TYPE,
+    metadata: { schema, targetEntityId, tick },
+  }
+}
+
+/**
+ * When this mind last enacted each (schema, target) pair. Keyed
+ * `schema\u0000target` — NUL, because neither half can contain it, so a pair
+ * cannot be forged by a schema id that happens to contain the separator.
+ */
+export function enactedAtBySchemaTarget(
+  entities: ReadonlyMap<string, { type: string; metadata?: ReadonlyMap<string, unknown> | Record<string, unknown> }>,
+  /**
+   * alias id → anchor id, when the caller has an alias table.
+   *
+   * A FUNCTION rather than the table itself because `social.identity` already
+   * imports `fnv1a` from this file, so importing `canonicalOf` back would close a
+   * cycle. The caller owns the id space and hands down the resolution; absent, ids
+   * are used as they were written, which is exactly the previous behaviour.
+   */
+  canon?: ( id: string ) => string,
+): Map<string, number> {
+  const out = new Map<string, number>()
+  for( const [ , e ] of entities ){
+    if( e.type !== ENACTED_TYPE ) continue
+    const meta   = ( e.metadata ?? {} ) as Record<string, unknown>
+    const schema = typeof meta['schema'] === 'string' ? meta['schema'] as string : undefined
+    const target = typeof meta['targetEntityId'] === 'string' ? meta['targetEntityId'] as string : undefined
+    const tick   = typeof meta['tick'] === 'number' ? meta['tick'] as number : undefined
+    if( !schema || !target || tick === undefined ) continue
+    out.set( enactedKey( schema, canon ? canon( target ) : target ), tick )
+  }
+  return out
+}
+
+/** The map key for a (schema, target) pair. */
+export function enactedKey( schema: string, targetEntityId: string ): string {
+  return `${ schema }\u0000${ targetEntityId }`
+}
+
 /** Read a descriptor back off entity metadata (P2 matcher + tests). */
 export function readConsequence(
   m: ReadonlyMap<string, unknown> | Record<string, unknown> | undefined,
@@ -106,6 +200,9 @@ export function readConsequence(
     textHash:       typeof meta['textHash']       === 'number' ? meta['textHash']       as number : undefined,
     text:           typeof meta['text']           === 'string' ? meta['text']           as string : undefined,
     paramsHash:     typeof meta['paramsHash']     === 'number' ? meta['paramsHash']     as number : undefined,
+    // Decoded, not just written — a field only one side knows about is the shape
+    // of defect this codebase has hit five times now.
+    pending:        meta['pending'] === true ? true : undefined,
     expiresAt:      typeof meta['expiresAt']      === 'number' ? meta['expiresAt']      as number : 0,
     tick:           typeof meta['tick']           === 'number' ? meta['tick']           as number : 0,
   }
@@ -117,12 +214,36 @@ export function readConsequence(
 export function liveConsequences(
   entities: ReadonlyMap<string, { type: string; metadata?: ReadonlyMap<string, unknown> | Record<string, unknown> }>,
   tick:     Tick,
+  /**
+   * alias id → anchor id, when the caller has an alias table.
+   *
+   * A FUNCTION rather than the table itself because `social.identity` already
+   * imports `fnv1a` from this file, so importing `canonicalOf` back would close a
+   * cycle. The caller owns the id space and hands down the resolution; absent, ids
+   * are used as they were written, which is exactly the previous behaviour.
+   */
+  canon?: ( id: string ) => string,
 ): ConsequenceDescriptor[] {
   const out: ConsequenceDescriptor[] = []
   for( const [ , e ] of entities ){
     if( e.type !== CONSEQUENCE_TYPE ) continue
     const d = readConsequence( e.metadata )
-    if( d && tick < d.expiresAt ) out.push( d )
+    if( !d ) continue
+    // A descriptor stamped LATER than now came from a previous session: descriptors
+    // snapshot with the state, and the tick counter restarts at 1 on wake. Without
+    // this the expiry test (`tick < expiresAt`) reads every restored descriptor as
+    // freshly live — measured: a Will woke at tick 1 holding three reach-out
+    // descriptors stamped 575–596 with expiry 605–626, so for the WHOLE session it
+    // believed it had just messaged that person moments ago. It damped every
+    // reach-out to them and delivered nothing, and the P2 matcher would equally
+    // have attenuated their genuine replies as its own echo.
+    if( d.tick > tick ) continue
+    if( tick < d.expiresAt )
+      // Canonical, so a descriptor written against a transport id and a candidate
+      // aimed at the anchor are recognised as the same act toward the same person.
+      out.push( canon && d.targetEntityId
+        ? { ...d, targetEntityId: canon( d.targetEntityId ) }
+        : d )
   }
   return out.sort( ( a, b ) => ( a.intentId < b.intentId ? -1 : a.intentId > b.intentId ? 1 : 0 ) )
 }
@@ -148,6 +269,240 @@ export function matchConsequenceText(
   return null
 }
 
+// ── P5: the act's own footprint, felt as satiation ───────────────────────────
+
+/**
+ * How much of an act's own footprint is still live for this (schema, target),
+ * 1 → 0 as the descriptor ages out. 0 when nothing matching is in flight.
+ *
+ * This is the consumer #112 always described and the descriptors never had. A
+ * delivered message wrote its footprint here and nothing ever read it back, so
+ * the standing `ideomotor.intent` that produced it kept re-winning the
+ * competition and the same words went out again — observed three times, ~21
+ * ticks apart, to the same person, while the mind believed each was the first.
+ *
+ * Deliberately a decaying quantity, not a lock. Right after acting it is ~1 and
+ * the pull to repeat is strongly damped; as the window in which the world could
+ * still answer runs out it returns to 0 and the appetite comes back on its own.
+ * That is a refractory period, not a rule: the mind may still repeat itself if
+ * something has become pressing enough to out-compete the damping, which is
+ * exactly what a person does when the silence starts to matter.
+ *
+ * Matches on (schema, target) rather than on the words, because at the moment
+ * the competition runs the words do not exist yet — a facet authors them later.
+ * "I have just reached out to this person and do not yet know how it landed" is
+ * the honest predicate, and it is the one that governs whether to speak again.
+ */
+export function enactionFootprint(
+  descriptors:    readonly ConsequenceDescriptor[],
+  schema:         string,
+  targetEntityId: string | undefined,
+  tick:           Tick,
+  windowTicks:    number = CONSEQUENCE_TTL_TICKS,
+  /**
+   * Tick of the last thing SAID to each entity, from `conversation.sent`.
+   *
+   * Descriptors cannot carry satiation on their own: the executor deletes them at
+   * `tick >= expiresAt` (motor.schema.executor's TTL sweep), so nothing survives
+   * past the echo window and a satiation window longer than it was silently a
+   * no-op. Observed live: the same relay delivered twice with `justEnacted` never
+   * once reaching the competition.
+   *
+   * `conversation.sent` is the durable record of having spoken — written by
+   * ProactiveCommunicator at push time, snapshotted with the state, and already
+   * what discharges an undertaking. Keyed by person rather than by schema on
+   * purpose: having just spoken to someone damps speaking to them again, however
+   * that speaking happens to be schematised.
+   */
+  spokenAt?:      ReadonlyMap<string, number>,
+  /**
+   * Tick this schema was last enacted — `LearnedSkill.lastEnactedTick`, used for
+   * an act with NO OBJECT, where "I have just done this" is the whole of the fact
+   * and there is no target to key on.
+   *
+   * Without it the innate floor could not satiate at all. Every objectless stance
+   * returned here at the first line, so `repeat` — the largest damping weight in
+   * the competition at 0.30 — was structurally zero for `orient · attend · rest ·
+   * withdraw · reflect · wait · express`, while `habit` (+0.20) outweighed the
+   * novelty it spends (−0.10). A stance that won once therefore won harder next
+   * tick, forever. Measured: `express` at habit 1.0 taking 144 of 145 decisions
+   * across 300 quiet ticks, with nothing in the mind able to represent that it had
+   * just done it.
+   *
+   * The skill record is the right source for the same reason `conversation.sent`
+   * is for speaking: descriptors are swept at the echo TTL, and `agency.outcome`
+   * is consumed and deleted the tick after it is written, so neither survives a
+   * satiation window. `lastEnactedTick` is durable and snapshotted.
+   */
+  selfEnactedAt?: number,
+  /**
+   * Tick this mind last SPOKE — to anyone. Supplied only for a speaking act, and
+   * satiating over the shorter echo window rather than the full repeat window.
+   *
+   * Satiation was keyed entirely by listener, so "I have already said this" had
+   * no bearing once the listener changed. Live, a COO drafted one scoping
+   * outline and put substantially the same thing into three destinations inside
+   * three minutes — general, a DM, a second channel — with nothing damping it,
+   * because each was a different key. She could SEE it: `## What I've Said
+   * Lately` listed her own turns across all targets and she posted again 31
+   * seconds later. The record was there; the pull had no opposing force.
+   *
+   * Deliberately WEAKER than the per-person arm, via the shorter window: telling
+   * a second person something is legitimate and must stay cheap, while saying it
+   * again to someone who already heard it should not be. And deliberately from
+   * `conversation.sent` — what was actually SAID — not from the schema's
+   * `lastEnactedTick`, which also counts attempts that authored no words and
+   * would let a run of declined outreach satiate the mind into silence.
+   *
+   * Replies are unaffected: an answer to an inbound message is delivered by the
+   * audition facet through the outbox and never enters this competition. This
+   * damps only self-initiated outreach — which is exactly what broadcasting is.
+   */
+  spokeAnywhereAt?: number,
+  /**
+   * Tick this (schema, target) pair was last enacted, from the durable
+   * `agency.enacted` records — the peer of `spokenAt` for an act that has an
+   * object but is not speech (`inspect`, every entity-bound host effector).
+   *
+   * Without it those acts carried satiation only while a consequence descriptor
+   * survived, i.e. the echo window, so the back half of the satiation window
+   * damped nothing — measured at 40–46% coverage against 100% for objectless
+   * acts, with a live COO re-looking-up the same person 33 times in 7 minutes.
+   * Keyed by PAIR, not by schema, so damping "look up Alice" leaves "look up
+   * Bob" untouched — which is precisely why `selfEnactedAt` cannot serve here.
+   */
+  enactedAt?:     ReadonlyMap<string, number>,
+): number {
+  if( windowTicks <= 0 ) return 0
+
+  if( !targetEntityId ){
+    // BOTH arms, for the same reason an act with an object has both.
+    //
+    // `selfEnactedAt` is a skill record, and a skill record is written when the
+    // outcome is RECONCILED — for a host effector that is an async ack landing
+    // some ticks after the act. In the window between dispatching and learning,
+    // satiation read the PREVIOUS enaction and damped almost nothing, while the
+    // descriptor saying "I did this on the tick just gone" sat one branch away,
+    // written at dispatch and never read: the objectless case returned before
+    // the loop that reads it.
+    //
+    // Measured live on a COO: `discord_server_snapshot` — objectless, cheap,
+    // always succeeds — repeated at a gap of THREE ticks in 26 of 47 intervals,
+    // while every entity-bound effector in the same run sat at 30–60 under the
+    // same weights. Those were not damped harder, they were damped SOONER,
+    // because a descriptor exists from the enacting tick and a skill record does
+    // not. Half the repeats were slipping through the reconciliation window.
+    let strongest = selfEnactedAt === undefined
+      ? 0
+      : ( windowTicks - ( tick - selfEnactedAt ) ) / windowTicks
+
+    for( const d of descriptors ){
+      // Objectless descriptors only. A `look up Alice` must never satiate the
+      // objectless form of the same schema — that is the asymmetry `enactedAt`
+      // is keyed by PAIR to avoid, and it would read as the mind refusing to do
+      // a thing in general because it once did it to someone.
+      if( d.schema !== schema || d.targetEntityId !== undefined ) continue
+      if( d.pending ) continue
+      const remaining = ( windowTicks - ( tick - d.tick ) ) / windowTicks
+      if( remaining > strongest ) strongest = remaining
+    }
+
+    return strongest < 0 ? 0 : strongest > 1 ? 1 : strongest
+  }
+
+  let strongest = 0
+
+  const enacted = enactedAt?.get( enactedKey( schema, targetEntityId ) )
+  if( enacted !== undefined ){
+    const remaining = ( windowTicks - ( tick - enacted ) ) / windowTicks
+    if( remaining > strongest ) strongest = remaining
+  }
+
+  const spoken = spokenAt?.get( targetEntityId )
+  if( spoken !== undefined ){
+    const remaining = ( windowTicks - ( tick - spoken ) ) / windowTicks
+    if( remaining > strongest ) strongest = remaining
+  }
+
+  // Having just spoken AT ALL — the arm that is not about the listener. Over the
+  // echo window, so it is real but short: a second person is cheap to tell, a
+  // third destination in ninety seconds is not. See `spokeAnywhereAt`.
+  if( spokeAnywhereAt !== undefined ){
+    const remaining = ( CONSEQUENCE_TTL_TICKS - ( tick - spokeAnywhereAt ) ) / CONSEQUENCE_TTL_TICKS
+    if( remaining > strongest ) strongest = remaining
+  }
+
+  for( const d of descriptors ){
+    if( d.schema !== schema || d.targetEntityId !== targetEntityId ) continue
+    // You cannot be satiated by something you have not done. See `pending`.
+    if( d.pending ) continue
+    // Measured from when the act happened, against the SATIATION window — not from
+    // the descriptor's own expiry, which is the echo window and a different
+    // question. Conflating them meant "how long before I say this again" was
+    // pinned to "how long until the world's reply could still arrive", and the
+    // second is necessarily short. Observed: re-deliveries landing ~25 ticks
+    // apart against a 30-tick echo TTL, so the damping had decayed to almost
+    // nothing exactly when the next impulse arrived.
+    const elapsed   = tick - d.tick
+    const remaining = ( windowTicks - elapsed ) / windowTicks
+    if( remaining > strongest ) strongest = remaining
+  }
+
+  return strongest < 0 ? 0 : strongest > 1 ? 1 : strongest
+}
+
+/**
+ * When the mind last SAID something to each person, from the durable
+ * `conversation.sent` records. Feeds `enactionFootprint`'s satiation.
+ *
+ * Unlike consequence descriptors these are never swept, so satiation can run on
+ * whatever window the persona wants rather than being capped by the echo TTL.
+ */
+export function spokenAtByEntity(
+  entities: ReadonlyMap<string, { type: string; updatedAtTick?: number; tick?: number; metadata?: ReadonlyMap<string, unknown> | Record<string, unknown> }>,
+  /**
+   * alias id → anchor id, when the caller has an alias table.
+   *
+   * A FUNCTION rather than the table itself because `social.identity` already
+   * imports `fnv1a` from this file, so importing `canonicalOf` back would close a
+   * cycle. The caller owns the id space and hands down the resolution; absent, ids
+   * are used as they were written, which is exactly the previous behaviour.
+   */
+  canon?: ( id: string ) => string,
+): Map<string, number> {
+  const out = new Map<string, number>()
+
+  for( const [ , e ] of entities ){
+    if( e.type !== 'conversation.sent') continue
+    const m      = ( e.metadata ?? {} ) as Record<string, unknown>
+    const target = typeof m['targetEntityId'] === 'string' ? m['targetEntityId'] as string : undefined
+    if( !target ) continue
+    // `metadata.tick` where the writer set one, else the entity's own tick, which
+    // StateManager.setEntity stamps from the sim clock on every write. The fallback
+    // matters: not every path that records having spoken fills the metadata field,
+    // and defaulting to 0 made every record look infinitely old.
+    // `updatedAtTick` is the field `StateManager.setEntity` actually stamps.
+    // This read `e.tick`, which does not exist on SimulationEntity — so the
+    // fallback the comment above describes has never once fired, and any writer
+    // that omitted `metadata.tick` was treated as having spoken at tick 0, i.e.
+    // infinitely long ago, i.e. not satiating at all.
+    const at = typeof m['tick']          === 'number' ? m['tick'] as number
+             : typeof e.updatedAtTick    === 'number' ? e.updatedAtTick
+             : typeof e.tick             === 'number' ? e.tick
+             : 0
+    // Through the alias table, for the reason `readSpokenTurns` states plainly:
+    // a REPLY is addressed to the transport id the percept arrived with
+    // (`discord:1019…`) while a PROACTIVE message is addressed to the anchor the
+    // executive resolved (`ke:…`), and they are the same someone. The PROMPT half
+    // resolved that from the start; this half, the one that damps, never did — so
+    // having just answered a person did not damp reaching out to them.
+    const key = canon ? canon( target ) : target
+    if( at > ( out.get( key ) ?? -Infinity ) ) out.set( key, at )
+  }
+
+  return out
+}
+
 // ── ACP-P1: entity correspondence (ACTION_CONDITIONED_PREDICTION §2) ─────────
 
 /** Salience multiplier for an entity-correspondence match — gentler than a