@mindot/will 0.7.0 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mindot/will",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "author": "Fabrice <fabrice8@github.com>",
   "repository": {
     "type": "git",

package/src/channels/discord.ts

@@ -24,10 +24,23 @@
 
 import type { Will, WillMessage } from '#sdk/will'
 import { ChannelRoster } from '#channels/roster'
-import { chunkText, type ChannelBridge } from '#channels/types'
+import { chunkText, renderAttachments, isTextual, type ChannelBridge, type ChannelAttachment } from '#channels/types'
 
 const DISCORD_MESSAGE_LIMIT = 2000
 
+/**
+ * The only hosts the bridge will fetch attachment bodies from.
+ *
+ * Deliberately an allowlist of Discord's own CDN. An inbound message is
+ * untrusted input; following URLs it names would turn perception into an open
+ * redirect, and a `url` field is no more trustworthy than the message text.
+ */
+const DISCORD_CDN_HOSTS = new Set( [ 'cdn.discordapp.com', 'media.discordapp.net' ] )
+
+/** Refuse to pull a large file into a percept — the cap in renderAttachments
+ *  bounds what is *kept*, this bounds what is fetched at all. */
+const MAX_FETCH_BYTES = 256 * 1024
+
 // ── The slice of discord.js the bridge actually uses (structural) ───────────
 
 export interface DiscordLikeChannel {
@@ -35,6 +48,13 @@ export interface DiscordLikeChannel {
   sendTyping?(): Promise<unknown>
 }
 
+export interface DiscordLikeAttachment {
+  name?:        string | null
+  contentType?: string | null
+  size?:        number
+  url?:         string
+}
+
 export interface DiscordLikeMessage {
   content: string
   cleanContent?: string
@@ -44,6 +64,16 @@ export interface DiscordLikeMessage {
   member?: { displayName?: string } | null
   mentions?: { has( userId: string ): boolean }
   channel: DiscordLikeChannel
+  /**
+   * Files riding with the message.
+   *
+   * discord.js hands us a `Collection`, which extends `Map` — so iterating it
+   * directly yields `[id, attachment]` PAIRS, not attachments. Typing this as a
+   * bare `Iterable` was wrong and silently produced `name: undefined` against
+   * the real client while passing every test, because the test fake injects an
+   * array. Both shapes are accepted now and normalised in `collectAttachments`.
+   */
+  attachments?: ReadonlyMap<string, DiscordLikeAttachment> | Iterable<DiscordLikeAttachment>
 }
 
 export interface DiscordLikeClient {
@@ -63,14 +93,38 @@ export interface DiscordLikeClient {
 export interface DiscordBridgeOptions {
   /** Bot token (Discord developer portal). Unused when `client` is injected pre-logged-in. */
   token?: string
-  /** Channel ids the Will inhabits. Unset = every channel it can see. */
-  channels?: string[]
-  /** Perceive guild messages only when the Will is @mentioned (DMs always perceived). */
-  mentionOnly?: boolean
+  /**
+   * Channel ids the Will inhabits. Unset — or the single wildcard `'*'` — means
+   * every channel it can see, so adding it to a new channel in Discord is enough.
+   * A list restrains it to exactly those, and a message anywhere else is dropped
+   * at the bridge: the Will never perceives it and its silence there is not a choice.
+   */
+  channels?: readonly string[]
+  /**
+   * Where the Will only perceives guild messages that @mention it. DMs are always
+   * perceived either way.
+   *
+   *   `true`            — everywhere
+   *   `[ 'id', … ]`     — only in those channels; it listens openly elsewhere
+   *   omitted / `false` — nowhere
+   *
+   * The list form is what makes a wide-open roster usable: present in every channel,
+   * but a quiet participant in the busy ones.
+   */
+  mentionOnly?: boolean | readonly string[]
   /** Fallback channel for utterances with no reachable addressee. */
   homeChannelId?: string
   /** Roster path (default: ./.will/<willId>.discord.json). */
   rosterPath?: string
+  /**
+   * Read the contents of text-like attachments (.md, .txt, .json, …) into the
+   * percept, rather than only naming them. Default true.
+   *
+   * Only Discord's own CDN is ever fetched, and only up to a size cap. Set false
+   * for a bridge that should never pull remote bytes — the Will still perceives
+   * that a file arrived and can ask about it.
+   */
+  readAttachments?: boolean
   /** Test / power-user seam: bring your own client; discord.js is never imported. */
   client?: DiscordLikeClient
   log?: ( msg: string ) => void
@@ -86,7 +140,17 @@ export interface DiscordBridgeOptions {
 export async function connectDiscord( will: Will, opts: DiscordBridgeOptions ): Promise<ChannelBridge> {
   const log     = opts.log ?? ( ( m: string ) => console.error(`[will:discord] ${ m }`) )
   const roster  = new ChannelRoster( opts.rosterPath ?? `.will/${ will.id }.discord.json`)
-  const allowed = opts.channels?.length ? new Set( opts.channels ) : null
+  // `null` = everywhere. An explicit '*' reads the same as omitting the list, so a
+  // host can say "all channels" out loud instead of by leaving a variable blank.
+  const allowed = opts.channels?.length && !opts.channels.includes('*')
+    ? new Set( opts.channels )
+    : null
+
+  // Mention-gating is either global (true) or scoped to named channels.
+  const mentionEverywhere = opts.mentionOnly === true
+  const mentionIn         = Array.isArray( opts.mentionOnly ) && opts.mentionOnly.length
+    ? new Set( opts.mentionOnly )
+    : null
 
   const client = opts.client ?? await createDiscordClient()
 
@@ -104,7 +168,8 @@ export async function connectDiscord( will: Will, opts: DiscordBridgeOptions ):
     if( !isDM && allowed && !allowed.has( message.channelId ) ) return
 
     const addressed = isDM || ( message.mentions?.has( self.id ) ?? false )
-    if( opts.mentionOnly && !addressed ) return
+    // DMs are addressed by definition, so this never gates them.
+    if( !addressed && ( mentionEverywhere || mentionIn?.has( message.channelId ) ) ) return
 
     const entityId = `discord:${ message.author.id }`
     const speaker  = message.member?.displayName ?? message.author.displayName ?? message.author.username
@@ -121,17 +186,82 @@ export async function connectDiscord( will: Will, opts: DiscordBridgeOptions ):
     // may still choose silence, and typing expires on its own.
     if( addressed ) await message.channel.sendTyping?.().catch( () => {} )
 
-    const text = message.cleanContent || message.content
-    if( !text.trim() ) return
+    const said  = ( message.cleanContent || message.content ).trim()
+    const files = collectAttachments( message )
+
+    // An attachment-only message used to die here on the empty body: no percept,
+    // no log line, nothing. From the mind's side the person had simply gone
+    // quiet — and Discord *makes* these, turning a long pasted markdown block
+    // into a .md upload. Only a message with neither words nor files is nothing.
+    if( !said && files.length === 0 ) return
+
+    const shared = await renderAttachments(
+      files, speaker,
+      opts.readAttachments === false ? undefined : fetchAttachmentText,
+    )
+    const text = [ said, shared ].filter( Boolean ).join('\n')
 
     await will.perceive( {
       text,
       from:   entityId,
       thread: `discord:${ message.channelId }`,
+      // `isDM` has been computed on every inbound since this bridge shipped and
+      // used only to pick a roster field. It is the one fact that makes a room
+      // the right or wrong place to say something, and the mind never saw it —
+      // which is how a follow-up promised in a DM went out to #general.
+      direct: isDM,
       ...( speaker ? { speaker } : {} ),
     } )
   }
 
+  /**
+   * Normalise whatever the client gave us into attachments.
+   *
+   * `.values()` first: a discord.js Collection is a Map, so `for..of` over it
+   * yields `[id, attachment]` pairs and every field reads `undefined`. Arrays
+   * expose `.values()` too and yield their elements, so one branch covers the
+   * real client, a plain array, and a Map alike.
+   */
+  function collectAttachments( message: DiscordLikeMessage ): ChannelAttachment[] {
+    if( !message.attachments ) return []
+    const source = message.attachments as { values?: () => Iterable<DiscordLikeAttachment> }
+    const items: Iterable<DiscordLikeAttachment> = typeof source.values === 'function'
+      ? source.values()
+      : message.attachments as Iterable<DiscordLikeAttachment>
+
+    const out: ChannelAttachment[] = []
+    for( const a of items )
+      out.push( {
+        name: a.name ?? 'unnamed',
+        ...( a.contentType ? { contentType: a.contentType } : {} ),
+        ...( a.size != null ? { size: a.size } : {} ),
+        ...( a.url ? { url: a.url } : {} ),
+      } )
+    return out
+  }
+
+  /** Fetch one text attachment — Discord CDN only, size-capped. */
+  async function fetchAttachmentText( a: ChannelAttachment ): Promise<string | null> {
+    if( !a.url || !isTextual( a ) ) return null
+    let host: string
+    try { host = new URL( a.url ).hostname }
+    catch { return null }
+    if( !DISCORD_CDN_HOSTS.has( host ) ){
+      log(`refusing to fetch attachment '${ a.name }' from non-CDN host ${ host }`)
+      return null
+    }
+    if( a.size != null && a.size > MAX_FETCH_BYTES ){
+      log(`attachment '${ a.name }' is ${ a.size } bytes — naming it without reading`)
+      return null
+    }
+    const res = await fetch( a.url, { signal: AbortSignal.timeout( 10_000 ) } )
+    if( !res.ok ){
+      log(`attachment '${ a.name }' fetch failed: ${ res.status }`)
+      return null
+    }
+    return ( await res.text() ).slice( 0, MAX_FETCH_BYTES )
+  }
+
   // ── outbound: projected utterance → the addressee ─────────────────────────
   // The facade has no off(); the bridge gates its handler on `closed` instead.
   let closed = false
@@ -141,8 +271,22 @@ export async function connectDiscord( will: Will, opts: DiscordBridgeOptions ):
     const peer = m.to ? roster.resolve( m.to ) : undefined
     const chunks = chunkText( m.content, DISCORD_MESSAGE_LIMIT )
 
-    // Preference order: where we last shared a room → their DM → home channel.
-    const channelIds = [ peer?.lastChannelId, peer?.dmChannelId, opts.homeChannelId ?? undefined, lastActiveChannelId ?? undefined ]
+    // A reply goes back to the room it was said in. `m.thread` is the thread from
+    // the `perceive()` that prompted this — `discord:<channelId>` — so it is not a
+    // guess about where this person usually is, it is where they just spoke.
+    //
+    // Everything below it IS a guess, and the guesses were wrong in the way that
+    // matters most: a DM arrived, she answered it in seconds, and the answer went
+    // to the shared server channel because `lastChannelId` still held the last
+    // room they had been in together. She looked like she was ignoring him.
+    //
+    // Unprompted utterances carry no thread — nothing was said to them — so those
+    // still fall through to the roster, which is the right behaviour there.
+    const replyTo = m.thread?.startsWith('discord:') ? m.thread.slice('discord:'.length ) : undefined
+
+    // Preference order: the room they spoke in → where we last shared a room →
+    // their DM → home channel.
+    const channelIds = [ replyTo, peer?.lastChannelId, peer?.dmChannelId, opts.homeChannelId ?? undefined, lastActiveChannelId ?? undefined ]
     for( const id of channelIds ){
       if( !id ) continue
       try {
@@ -212,3 +356,37 @@ async function createDiscordClient(): Promise<DiscordLikeClient> {
     partials: [ Partials.Channel ],   // DMs arrive on uncached channels
   } ) as unknown as DiscordLikeClient
 }
+
+/**
+ * Parse `WILL_DISCORD_MENTION_ONLY` into the `mentionOnly` option.
+ *
+ * Accepts a boolean OR a channel list, because "only speak when spoken to" is
+ * rarely a whole-server property — it is how you stay present in a busy channel
+ * without narrating in it.
+ *
+ *   `1` / `true` / `yes`   → true (everywhere)
+ *   `0` / `false` / unset  → false (nowhere)
+ *   `123,456`              → only those channels
+ *
+ * Exported so every host parses it identically; the CLI and any SDK host share
+ * this rather than each re-deriving the syntax.
+ */
+export function parseMentionOnly( raw?: string ): boolean | string[] {
+  const v = raw?.trim()
+  if( !v ) return false
+  if( /^(1|true|yes)$/i.test( v ) ) return true
+  if( /^(0|false|no)$/i.test( v ) ) return false
+
+  const ids = v.split(',').map( s => s.trim() ).filter( Boolean )
+  return ids.length ? ids : false
+}
+
+/**
+ * Parse `WILL_DISCORD_CHANNELS`. `*` (or unset/empty) means every channel the Will
+ * can see — being added to a channel in Discord is then all it takes. Anything else
+ * restrains it to exactly the ids listed.
+ */
+export function parseChannels( raw?: string ): string[] | undefined {
+  const ids = raw?.split(',').map( s => s.trim() ).filter( Boolean )
+  return ids?.length ? ids : undefined
+}

package/src/channels/types.ts

@@ -28,6 +28,96 @@ export interface ChannelBridge {
   close(): Promise<void>
 }
 
+// ── Attachments ──────────────────────────────────────────────────────────────
+//
+// People hand over documents as well as speech, and some platforms *manufacture*
+// them: Discord silently turns a long pasted markdown block into a `.md` upload.
+// A bridge that reads only the text body sees such a message as empty and — worse
+// — as nothing at all, so the person appears to have gone silent.
+//
+// What a bridge does with these is deliberately modest. A named-but-unread file
+// is already a percept the Will can act on ("what's in it?"), which is the
+// paradigm-correct outcome and strictly better than silence. Inlining text is an
+// upgrade on top, never a precondition.
+
+/** One file riding along with a platform message. */
+export interface ChannelAttachment {
+  name:         string
+  contentType?: string
+  size?:        number
+  url?:         string
+}
+
+/** Per-attachment inline budget. A 2 MB doc must not enter working memory whole. */
+const INLINE_CHAR_CAP = 24_000
+/** How many text attachments to inline from one message. */
+const INLINE_COUNT_CAP = 4
+
+const TEXTUAL_EXT = /\.(md|markdown|txt|text|json|jsonl|csv|tsv|ya?ml|log|ini|toml)$/i
+
+/** Is this something we can meaningfully read as text? */
+export function isTextual( a: ChannelAttachment ): boolean {
+  const ct = a.contentType?.split(';')[0]?.trim().toLowerCase() ?? ''
+  if( ct.startsWith('text/') ) return true
+  if( ct === 'application/json' || ct === 'application/x-yaml' ) return true
+  // Discord's own markdown uploads arrive as text/plain, but trust the extension
+  // too — content types from platforms are advisory at best.
+  return TEXTUAL_EXT.test( a.name )
+}
+
+function humanSize( bytes?: number ): string {
+  if( bytes == null ) return ''
+  return bytes < 1024 ? `${ bytes } B`
+       : bytes < 1024 * 1024 ? `${ ( bytes / 1024 ).toFixed( 1 ) } KB`
+       : `${ ( bytes / 1024 / 1024 ).toFixed( 1 ) } MB`
+}
+
+/**
+ * Render attachments into perceivable text.
+ *
+ * `fetchText` is supplied by the bridge, not by this module — the decision about
+ * which hosts are safe to fetch from is platform knowledge, and a helper that
+ * fetched arbitrary URLs found in inbound messages would be an open redirect
+ * into the Will's perception. Omit it and attachments are named, never read.
+ *
+ * Inlined content is untrusted, exactly like message text — more so, since a
+ * document is long, structured, and looks authoritative, which is the shape of
+ * an effective injection. It is fenced and labelled as shared content so the
+ * mind reads it as something it was handed, not as something it was told.
+ */
+export async function renderAttachments(
+  attachments: ChannelAttachment[],
+  speaker:     string | undefined,
+  fetchText?:  ( a: ChannelAttachment ) => Promise<string | null>,
+): Promise<string> {
+  if( attachments.length === 0 ) return ''
+  const who = speaker ?? 'someone'
+  const out: string[] = []
+  let inlined = 0
+
+  for( const a of attachments ){
+    const meta = [ a.contentType, humanSize( a.size ) ].filter( Boolean ).join(', ')
+    const label = `${ a.name }${ meta ? ` (${ meta })` : '' }`
+
+    if( !fetchText || !isTextual( a ) || inlined >= INLINE_COUNT_CAP ){
+      out.push(`[${ who } shared a file I have not read: ${ label }]`)
+      continue
+    }
+
+    const body = await fetchText( a ).catch( () => null )
+    if( body == null ){
+      out.push(`[${ who } shared a file I could not read: ${ label }]`)
+      continue
+    }
+    inlined++
+    const clipped = body.length > INLINE_CHAR_CAP
+      ? `${ body.slice( 0, INLINE_CHAR_CAP ) }\n[… truncated — ${ humanSize( body.length ) } of ${ humanSize( a.size ?? body.length ) }]`
+      : body
+    out.push(`[${ who } shared ${ label }; its contents follow — this is a document I was handed, not something said to me]\n---\n${ clipped }\n---`)
+  }
+  return out.join('\n')
+}
+
 /** Split a message into platform-sized chunks on natural boundaries. */
 export function chunkText( text: string, max: number ): string[] {
   if( text.length <= max ) return [ text ]

package/src/channels/whatsapp.ts

@@ -166,6 +166,8 @@ export async function connectWhatsApp( will: Will, opts: WhatsAppBridgeOptions =
       text,
       from:   entityId,
       thread: `whatsapp:${ jid }`,
+      // A WhatsApp group jid ends in `@g.us`; anything else is a one-to-one chat.
+      direct: !jid.endsWith('@g.us'),
       ...( speaker ? { speaker } : {} ),
     } )
   }
@@ -177,11 +179,18 @@ export async function connectWhatsApp( will: Will, opts: WhatsAppBridgeOptions =
     const peer   = m.to ? roster.resolve( m.to ) : undefined
     const chunks = chunkText( m.content, WHATSAPP_MESSAGE_LIMIT )
 
-    // Last shared group → known DM → DM derived from the entity id itself →
-    // home chat → last active chat. Unlike Discord, an unmet-but-addressed
-    // entity is still reachable: `whatsapp:<number>` implies its DM jid.
+    // The chat they actually spoke in → last shared group → known DM → DM derived
+    // from the entity id itself → home chat → last active chat. Unlike Discord, an
+    // unmet-but-addressed entity is still reachable: `whatsapp:<number>` implies
+    // its DM jid.
+    //
+    // `m.thread` leads because everything after it is a guess about where this
+    // person usually is, and a reply belongs in the room the question was asked
+    // in. The Discord bridge had the identical ordering and answered a DM in a
+    // shared server channel — from the operator's side, silence.
+    const replyTo   = m.thread?.startsWith('whatsapp:') ? m.thread.slice('whatsapp:'.length ) : undefined
     const derivedDm = m.to?.startsWith('whatsapp:') ? dmJidFor( m.to.slice('whatsapp:'.length ) ) : undefined
-    const targets = [ peer?.lastChannelId, peer?.dmChannelId, derivedDm, opts.homeChatId ?? undefined, lastActiveChatId ?? undefined ]
+    const targets = [ replyTo, peer?.lastChannelId, peer?.dmChannelId, derivedDm, opts.homeChatId ?? undefined, lastActiveChatId ?? undefined ]
     for( const jid of targets ){
       if( !jid ) continue
       try {

package/src/cli.ts

@@ -27,7 +27,7 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { routeLogsToStderr, bootWillFromEnv } from '#root/host/boot'
 import { buildWillMcpServer } from '#root/mcp/server'
 import { buildWillHttpServer } from '#root/serve/server'
-import { connectDiscord } from '#channels/discord'
+import { connectDiscord, parseChannels, parseMentionOnly } from '#channels/discord'
 import { connectWhatsApp } from '#channels/whatsapp'
 
 // stdout is the MCP protocol channel under `will mcp` — route logs FIRST.
@@ -38,7 +38,12 @@ const USAGE = `usage: will <mcp | serve | discord | whatsapp>
   mcp       host a persistent mind over MCP stdio (Claude Desktop / Claude Code)
   serve     host a persistent mind over HTTP (any language; WILL_PORT, default 7777)
   discord   put a persistent mind in a Discord server (DISCORD_BOT_TOKEN; optional
-            WILL_DISCORD_CHANNELS, WILL_DISCORD_MENTION_ONLY, WILL_DISCORD_HOME_CHANNEL)
+            WILL_DISCORD_CHANNELS      "*" or unset = every channel it can see,
+                                       else a comma-separated allowlist
+            WILL_DISCORD_MENTION_ONLY  1/true = only when @mentioned, anywhere;
+                                       or a comma-separated channel list to gate
+                                       just those; DMs are always perceived
+            WILL_DISCORD_HOME_CHANNEL  where it speaks when it has no other route)
   whatsapp  put a persistent mind on WhatsApp — QR-pairs as a linked device; no token.
             UNOFFICIAL protocol (ban risk; use a spare number — docs/channels/whatsapp.md).
             Optional WILL_WHATSAPP_CHATS, WILL_WHATSAPP_MENTION_ONLY, WILL_WHATSAPP_HOME_CHAT
@@ -76,8 +81,8 @@ async function main(): Promise<void> {
     const csv = ( v?: string ) => v?.split(',').map( s => s.trim() ).filter( Boolean )
     const bridge = await connectDiscord( will, {
       token:         process.env.DISCORD_BOT_TOKEN!,
-      channels:      csv( process.env.WILL_DISCORD_CHANNELS ),
-      mentionOnly:   /^(1|true|yes)$/i.test( process.env.WILL_DISCORD_MENTION_ONLY ?? ''),
+      channels:      parseChannels( process.env.WILL_DISCORD_CHANNELS ),
+      mentionOnly:   parseMentionOnly( process.env.WILL_DISCORD_MENTION_ONLY ),
       homeChannelId: process.env.WILL_DISCORD_HOME_CHANNEL,
       rosterPath:    pmaPath.replace( /(\.pma)?\.json$/, '') + '.discord.json',
     } )

package/src/cognition/agency/consequence.ts

@@ -122,7 +122,17 @@ export function liveConsequences(
   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 ) out.push( d )
   }
   return out.sort( ( a, b ) => ( a.intentId < b.intentId ? -1 : a.intentId > b.intentId ? 1 : 0 ) )
 }
@@ -148,6 +158,117 @@ 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>,
+): number {
+  if( !targetEntityId ) return 0
+  if( windowTicks <= 0 ) return 0
+
+  let strongest = 0
+
+  const spoken = spokenAt?.get( targetEntityId )
+  if( spoken !== undefined ){
+    const remaining = ( windowTicks - ( tick - spoken ) ) / windowTicks
+    if( remaining > strongest ) strongest = remaining
+  }
+
+  for( const d of descriptors ){
+    if( d.schema !== schema || d.targetEntityId !== targetEntityId ) 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> }>,
+): 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
+    if( at > ( out.get( target ) ?? -Infinity ) ) out.set( target, at )
+  }
+
+  return out
+}
+
 // ── ACP-P1: entity correspondence (ACTION_CONDITIONED_PREDICTION §2) ─────────
 
 /** Salience multiplier for an entity-correspondence match — gentler than a