@mindot/will 0.8.0 → 0.10.0

package/src/cognition/senses/base.sense.engine.ts

@@ -20,7 +20,7 @@
  * domains (see §6 cross-modal note).
  *
  * - `AuditionEngine` extends this and overrides `publishes()`/`snapshot()` for its
- *   extra `audition.task.signal` schema and session snapshot.
+ *   extra `executive.facet.handoff` schema and session snapshot.
  * - The four shell engines extend `ShellSenseEngine` (below) and are ~6 lines each.
  */
 
@@ -29,7 +29,10 @@ import type { CognitiveEvent, CognitiveBus } from '#cognition/bus'
 import type { CognitiveEventSchema } from '#cognition/schema.registry'
 import type { StateCommands } from '#core/types'
 import type { AccessGrants } from '#agency/access.grants'
-import type { SenseEngine, SensoryInput, SenseDomain, Percept } from '#senses/index'
+import type { SensorySignal } from '#senses/provenance'
+import { perceptEntity, type PerceptEntity } from '#cognition/percept.entity'
+import { fnv1a } from '#agency/consequence'
+import type { SenseEngine, SensoryInput, SenseDomain, Percept, Transduced } from '#senses/index'
 
 export abstract class BaseSenseEngine implements SenseEngine {
   abstract readonly name:   string
@@ -38,7 +41,7 @@ export abstract class BaseSenseEngine implements SenseEngine {
   /**
    * The `SensoryInput.kind` values this engine consumes. Inputs of any other
    * kind are ignored silently by `ingest()` (no warning, no work) — this is how
-   * a single `ingestSensory(domain, input)` call can be routed leniently.
+   * a single `senseSignal(domain, input)` call can be routed leniently.
    */
   protected abstract readonly acceptedKinds: ReadonlySet<SensoryInput['kind']>
 
@@ -51,12 +54,45 @@ export abstract class BaseSenseEngine implements SenseEngine {
 
   protected _bus:    CognitiveBus | null = null
   protected _grants: AccessGrants | null = null
+  protected _trace:  (( e: PerceptEntity ) => void) | null = null
+  protected _now:    (() => number) | null = null
+
+  /**
+   * Whether this sense lays down a `percept` trace in state (SIGNAL_BOUNDARY P0).
+   *
+   * ON by default, because that is the contract a host is owed: implement a
+   * sense, and what it senses reaches the five things that read percepts — the
+   * rupture gate, reafference credit, working memory, the executive prompt, and
+   * novelty. Before this, `publishPercept()` emitted a bus event three
+   * subscribers glanced at for one tick and nothing else, so a robot host
+   * ingesting frames could never remember having SEEN anything.
+   *
+   * `AuditionEngine` overrides it to `false` — see the comment there. It is the
+   * documented exception, not the template.
+   */
+  protected readonly tracesPercepts: boolean = true
 
   // ── Wiring ───────────────────────────────────────────────
   attachBus( bus: CognitiveBus ): void { this._bus = bus }
   /** Inject the AccessGrants so `ingest()` honours `gateEffector` (the permission gate). */
   attachGrants( g: AccessGrants ): void { this._grants = g }
 
+  /**
+   * Wire the sense to state: where a percept goes, and what tick it is now.
+   *
+   * Both together, never one: a percept without a tick is uncollectable — the
+   * sweeper reads `metadata.tick` and nothing else — which is the leak P0 step 2
+   * closed in two other writers. And the tick has to be injected rather than
+   * remembered, because a sense is INGEST-DRIVEN and off-tick: it has no `react()`
+   * to be handed one in. Audition's own `_lastDecisionTick` is the cautionary
+   * case — it lags to whenever the executive last decided, so a message arriving
+   * forty ticks later would be stamped forty ticks stale and swept on arrival.
+   */
+  attachPerceptTrace( write: ( e: PerceptEntity ) => void, currentTick: () => number ): void {
+    this._trace = write
+    this._now   = currentTick
+  }
+
   // ── CognitiveEngine defaults ─────────────────────────────
   publishes(): CognitiveEventSchema[] {
     return [ { type: `senses.${this.domain}.percept`, version: 1, validate: () => null } ]
@@ -71,7 +107,7 @@ export abstract class BaseSenseEngine implements SenseEngine {
    * the domain-specific work to `_perceive()`. Subclasses never re-handle gating
    * or filtering — they only implement `_perceive()`.
    */
-  async ingest( input: SensoryInput ): Promise<void> {
+  async sense( input: SensoryInput ): Promise<void> {
     // Permission gate — AccessGrants decides whether this sense may ingest.
     if( this.gateEffector && this._grants && !this._grants.isAllowed( this.gateEffector ) ) return
     if( !this.acceptedKinds.has( input.kind ) ) return
@@ -86,15 +122,77 @@ export abstract class BaseSenseEngine implements SenseEngine {
    * Publish a percept on this engine's `senses.<domain>.percept` topic. The
    * single emit chokepoint — the AttentionAllocator (and, in future, a
    * cross-modal binder) observes percepts here.
+   *
+   * `from` is the signal this percept was transduced FROM, and it is required
+   * rather than optional on purpose: every percept has a cause, and the one
+   * fact transduction must not lose is whose doing that cause was. Taking it
+   * here — instead of stashing the in-flight input on a field — is what keeps
+   * the stamp correct while `_perceive()` is async and two ingests overlap.
+   *
+   * The percept arrives as `Transduced`, i.e. WITHOUT the two fields, so a
+   * sense engine cannot supply them at all. An earlier cut let one through: the
+   * stamp overwrote `provenance` unconditionally but `sourceIntentId` only when
+   * the host supplied one, so an engine could fabricate an intent id and it
+   * survived — provenance the mind would later trust, laundered by the very
+   * step that exists to establish it. The type now refuses it outright; the
+   * host's assertion is the only authority.
+   *
+   * Returns the stamped percept so a sense engine that needs it downstream (as
+   * audition does, to route the turn) uses the SAME object the bus saw, rather
+   * than a second one that could drift from it.
    */
-  protected publishPercept( percept: Percept ): void {
+  protected publishPercept<P extends Percept>( percept: Transduced<P>, from: SensorySignal ): P {
+    // Stripped, then re-applied — belt AND braces. `Transduced` makes forging a
+    // compile error, but a type is only as strong as the compiler that saw it:
+    // a JS host, or a consumer built against an older .d.ts, hands over whatever
+    // it likes. The strip is what holds at runtime.
+    const { provenance: _stale, sourceIntentId: _staleIntent, ...rest } =
+      percept as Transduced<P> & Partial<SensorySignal>
+
+    const stamped = {
+      ...rest,
+      provenance: from.provenance,
+      ...( from.sourceIntentId ? { sourceIntentId: from.sourceIntentId } : {} ),
+    } as P
+
     this._bus?.publish({
       type:         `senses.${this.domain}.percept`,
       version:      1,
       sourceEngine: this.name,
-      salience:     percept.salience,
-      payload:      percept,
+      salience:     stamped.salience,
+      payload:      stamped,
     })
+
+    this._writeTrace( stamped )
+    return stamped
+  }
+
+  /**
+   * Lay the percept down in state, so it reaches the faculties that read
+   * percepts rather than only the three that were listening on the bus this
+   * tick. Silent when the sense opts out or the host wired no sink.
+   *
+   * The id is content-derived and tick-stamped — never `wallClock()` — because
+   * this entity lives in state, and a wall-clock id makes a recorded and a
+   * replayed run diverge (R2). Two identical signals from one entity on one
+   * tick collapse to one percept, which is the same coalescing audition already
+   * applies to a burst of identical messages.
+   */
+  private _writeTrace( p: Percept ): void {
+    if( !this.tracesPercepts || !this._trace || !this._now ) return
+
+    const tick = this._now()
+    this._trace( perceptEntity( {
+      id:         `sense-${ this.domain }-${ tick }-${ fnv1a( `${ p.sourceEntityId }\u0000${ p.summary }` ) }`,
+      tick,
+      salience:   p.salience,
+      category:   this.domain,
+      summary:    p.summary,
+      provenance: p.provenance,
+      entityId:   p.sourceEntityId,
+      ...( p.sourceIntentId !== undefined ? { sourceIntentId: p.sourceIntentId } : {} ),
+      ...( p.data           !== undefined ? { data:           p.data           } : {} ),
+    } ) )
   }
 }
 

package/src/cognition/senses/index.ts

@@ -21,6 +21,7 @@
 
 import type { CognitiveEngine } from '#cognition/types'
 import type { CognitiveBus }    from '#cognition/bus'
+import type { SensorySignal }   from './provenance'
 
 // ── Domain ────────────────────────────────────────────────────
 
@@ -31,15 +32,57 @@ export type SenseDomain =
   | 'olfaction'       // ambient signals  — OlfactionEngine (shell)
   | 'gustation'       // self-evaluation  — GustationEngine (shell)
 
+// ── Provenance (re-exported from ./provenance) ────────────────
+
+export type { SignalProvenance, SensorySignal, Transduced } from './provenance'
+export { asProvenance } from './provenance'
+
 // ── Percept types ─────────────────────────────────────────────
 
-/** Base percept published on the CognitiveBus. */
-export interface Percept {
+/**
+ * Base percept published on the CognitiveBus.
+ *
+ * It extends `SensorySignal` because transduction does not change whose doing a
+ * signal was: what the host stamped on the input is what the percept carries.
+ * `BaseSenseEngine.publishPercept()` applies both from the input, so a percept
+ * ALWAYS carries provenance — no consumer downstream ever writes a fallback.
+ */
+export interface Percept extends SensorySignal {
   domain:         SenseDomain
   sourceEntityId: string
   timestamp:      number
   salience:       number   // 0–1, computed by the sense engine
   raw:            unknown  // original input object
+  /**
+   * A LABEL for what was sensed. Required, so a percept is never invisible —
+   * `extractPercepts` skips one without it.
+   *
+   * A label, not the payload, and not a meaning. The engine composes it from
+   * what it has (the signal's name, a compact rendering) — A HOST IS NEVER
+   * ASKED TO WRITE ONE. Demanding prose from an integration puts the mind's own
+   * work on the wrong side of the boundary: a robot's vision system reports
+   * `object_detected, confidence 0.9, bbox […]`, and making it also write
+   * "I see a red ball on the table" is asking the arm to do the thinking.
+   *
+   * Because the ENGINE composes this, `PERCEPT_SUMMARY_CAP` may bound it —
+   * bounding its own words destroys nobody's only copy. `data` beside it is the
+   * host's, and is never bounded.
+   */
+  summary:        string
+  /**
+   * What the host actually sent, in the shape it had it — whole, unreshaped,
+   * uncapped.
+   *
+   * The mind's job is to make meaning by connecting pieces of information, and
+   * it cannot do that from a sentence somebody else wrote about the pieces. A
+   * host reporting `memberCount: 47` under a summary saying "a few people"
+   * leaves a mind that can never recover 47.
+   *
+   * Distinct from `raw`, which is the whole `SensoryInput` envelope and is
+   * engine-internal — never persisted. This is, and it reaches state, working
+   * memory and the prompt.
+   */
+  data?:          unknown
 }
 
 /** Audition-specific percept — carries language content and thread context. */
@@ -56,16 +99,43 @@ export interface LanguagePercept extends Percept {
 // ── Sensory input types (discriminated union) ─────────────────
 
 // Audition
-export interface TextMessage {
+export interface TextMessage extends SensorySignal {
   kind:     'text'
   entityId: string
   threadId: string
   content:  string
   /** Display name — used in the facet focus content. */
   speakerName?: string
+  /**
+   * True when `threadId` is a PRIVATE thread — this someone and the mind, nobody
+   * else listening. The single fact that decides whether a room is the right
+   * place for a given utterance, and the Discord edge has always computed it
+   * (`isDM`) and discarded it before the mind could see it: a follow-up promised
+   * in a DM went out to a public channel, because the roster's "where did I last
+   * see them" is a different question from "where did I promise this".
+   *
+   * Undefined means the channel did not say, which is honestly different from
+   * false — an unknown room is not known to be public.
+   */
+  direct?: boolean
+  /**
+   * What this room is CALLED, where the channel knows.
+   *
+   * A room has had a dossier of its own since 0.9.0 and no way to be named, so
+   * every place the mind knew was the id it was reached at —
+   * `discord:1531261362838441996`. It rendered to the mind as "something", which
+   * is what the prompt says for a `thing` with no name, and left a mind deciding
+   * *where* to say something choosing between two opaque numbers.
+   *
+   * A display label, not an address: `#general` is what a person calls the room,
+   * `discord:1531…` is how a message gets there, and 0.9.0 established that those
+   * are different facts. The bridge composes it, because what a room is called is
+   * a platform's business and the mind should not learn Discord's spelling.
+   */
+  threadName?: string
 }
 
-export interface VoiceChunk {
+export interface VoiceChunk extends SensorySignal {
   kind:           'voice'
   entityId:       string
   threadId:       string
@@ -74,14 +144,14 @@ export interface VoiceChunk {
 }
 
 // Vision (stub)
-export interface ImageFrame {
+export interface ImageFrame extends SensorySignal {
   kind:     'image'
   entityId: string
   data:     Buffer
   mimeType: string
 }
 
-export interface VideoSegment {
+export interface VideoSegment extends SensorySignal {
   kind:      'video'
   entityId:  string
   frames:    ImageFrame[]
@@ -89,41 +159,41 @@ export interface VideoSegment {
 }
 
 // Somatosensation (stub)
-export interface WebhookEvent {
+export interface WebhookEvent extends SensorySignal {
   kind:    'webhook'
   source:  string
   payload: unknown
   headers: Record<string, string>
 }
 
-export interface SystemSignal {
+export interface SystemSignal extends SensorySignal {
   kind:   'system'
   signal: string
   data:   unknown
 }
 
 // Olfaction (stub)
-export interface AmbientMetric {
+export interface AmbientMetric extends SensorySignal {
   kind:      'ambient'
   metricKey: string
   value:     number
   trend:     'rising' | 'falling' | 'stable'
 }
 
-export interface BackgroundSignal {
+export interface BackgroundSignal extends SensorySignal {
   kind:     'background'
   category: string
   data:     unknown
 }
 
 // Gustation (stub)
-export interface InternalEvaluation {
+export interface InternalEvaluation extends SensorySignal {
   kind:    'self-eval'
   context: string
   trigger: string
 }
 
-export interface SelfAssessmentTrigger {
+export interface SelfAssessmentTrigger extends SensorySignal {
   kind:      'assessment'
   goalId?:   string
   checkType: string
@@ -159,7 +229,7 @@ export type SensoryInput =
 export interface SenseEngine extends CognitiveEngine {
   readonly domain: SenseDomain
   attachBus( bus: CognitiveBus ): void
-  ingest( input: SensoryInput ): Promise<void>
+  sense( input: SensoryInput ): Promise<void>
 }
 
 // ── Re-exports ────────────────────────────────────────────────

package/src/cognition/senses/provenance.ts

@@ -0,0 +1,128 @@
+// ─────────────────────────────────────────────────────────────
+// src/cognition/senses/provenance.ts
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Signal provenance — the boundary vocabulary for "whose doing was this?"
+ * (SIGNAL_BOUNDARY P0a).
+ *
+ * Its own module, not part of `senses/index`, for one concrete reason:
+ * `BaseSenseEngine` needs the VALUE `provenanceOf` at the emit chokepoint, and
+ * `senses/index` re-exports `BaseSenseEngine` — importing it from there would
+ * be a runtime import cycle rather than the erased type-only one that was there
+ * before. `senses/index` re-exports everything here, so the public path is
+ * unchanged.
+ */
+
+/**
+ * Whether a signal arriving at the senses was caused by this mind's own
+ * efference (SIGNAL_BOUNDARY P0a).
+ *
+ *   • 'exafferent' — the world did this. Nothing of mine preceded it.
+ *   • 'reafferent' — I did this, and I am now sensing the consequence.
+ *   • 'unknown'    — the source cannot say.
+ *
+ * There is no fourth, silent state — see `SensorySignal`.
+ *
+ * ONE CONCEPT, TWO WAYS OF ARRIVING AT IT. This type is shared with the percept
+ * entities `exteroception` and `outbox.controller` write, which used the same
+ * two spellings before it existed (EXAFFERENCE P2/P3), and it is deliberately
+ * not "asserted only":
+ *
+ *   • At the WORLD door, provenance is INFERRED and that is correct — the mind
+ *     holds both sides. `Exteroception` matches an observed change against its
+ *     own live consequence descriptors (`matchConsequenceText` /
+ *     `matchConsequenceEntity`) and tags the hit `'reafferent'`.
+ *   • At the SENSE door, provenance must be ASSERTED — there is nothing to
+ *     match against. A host's Discord message and the mind's own echo of it are
+ *     identical from the inside; only the host can tell them apart.
+ *
+ * What the two share is the consequence, and it is load-bearing:
+ * `action.selector`'s rupture gate counts only `'exafferent'` percepts, so
+ * anything tagged (or defaulted) as mine can never rupture a commitment.
+ */
+export type SignalProvenance = 'exafferent' | 'reafferent' | 'unknown'
+
+/**
+ * What EVERY sensory signal carries, whatever kind it is — the provenance stamp.
+ *
+ * It lives on the input rather than being derived downstream because only the
+ * host knows. A Discord bridge knows that the message it just received is the
+ * webhook echo of the message the mind sent; nothing inside the mind can tell
+ * that from a stranger saying the same words. So the boundary asserts it, and
+ * the mind trusts the assertion.
+ *
+ * WHY `provenance` IS REQUIRED AND HAS NO DEFAULT. It shipped optional first,
+ * defaulting to `'exafferent'`, and that was wrong for a reason worth keeping
+ * written down. This codebase makes a field optional when absence is the ONLY
+ * way to say a third thing: `speakerName?` (no string means "no name learned"),
+ * `direct?` (no boolean means "the channel did not say"). Provenance already
+ * HAS its third thing — `'unknown'`. So optionality bought a fourth state that
+ * was behaviourally identical to `'exafferent'` and epistemically its opposite:
+ * a claim that the world did this, made by nobody. Worse, it was lossy in the
+ * one direction that costs — a reader could never separate "the host asserts
+ * exafference" from "the host said nothing", which want different treatment
+ * downstream, and `'unknown'` exists precisely to keep them apart.
+ *
+ * The related-but-different precedent is `asFinality()`. That one DOES default,
+ * because it normalizes an `unknown` read back off entity metadata or a host
+ * ack, where the type system cannot help and something must be chosen. Here the
+ * type system can help, so it does. Should provenance ever need reading off a
+ * tape, that reader gets its own `asFinality`-shaped normalizer, and the
+ * direction of ITS fallback is `'exafferent'`: a percept wrongly marked as mine
+ * is attenuated and can never rupture a commitment, so a mind that mislabels
+ * the world as its own doing goes quiet about real events. Erring the other way
+ * costs only a little redundant salience.
+ *
+ * `sourceIntentId` stays optional by the same rule that made `provenance`
+ * required: there is no id meaning "no intent", so absence is the only way to
+ * say it, and it is meaningless unless `provenance` is `'reafferent'`.
+ */
+export interface SensorySignal {
+  /** Mine, the world's, or honestly unknown. Asserted by the host — never inferred. */
+  provenance:      SignalProvenance
+  /**
+   * The `agency.intent` id this is the consequence of. Only meaningful when
+   * `provenance` is `'reafferent'`; the correlation handle a later mechanism
+   * needs to ask *"is this the echo of that?"* (`ACT_EXPECTATIONS`).
+   */
+  sourceIntentId?: string
+}
+
+/**
+ * A percept as a sense engine BUILDS it — provenance omitted, because it is not
+ * the engine's to write. `publishPercept()` applies the host's assertion, so
+ * this type is what makes laundering a compile error rather than a runtime one.
+ */
+export type Transduced<P extends { provenance: SignalProvenance }> =
+  Omit<P, 'provenance' | 'sourceIntentId'>
+
+/**
+ * Normalize an UNTYPED provenance — one arriving over a protocol the type
+ * system cannot police: an MCP tool call, an HTTP body, a wire envelope, a
+ * value read back off a snapshot.
+ *
+ * This is the `asFinality()` situation, and the ONLY situation in which
+ * provenance has a default. Inside the package the field is required, because
+ * there the compiler can make a producer answer. At an untyped boundary it
+ * cannot, something must be chosen, and every such read goes through here
+ * rather than comparing string literals at the call site.
+ *
+ * THE DEFAULT IS 'exafferent', AND NEVER 'reafferent'. A percept wrongly marked
+ * as mine is attenuated on the exafference path and can never rupture a
+ * commitment — so a mind that mislabels the world as its own doing goes quiet
+ * about real events, which is the failure that matters. Erring the other way
+ * costs only a little redundant salience. 'reafferent' is a claim only a caller
+ * that actually knows can make.
+ *
+ * Note it does NOT fall back to 'unknown', which would be the tidy-looking
+ * choice. 'unknown' is an assertion too — "I looked and I cannot tell" — and a
+ * caller that simply did not send the field has not looked. Where the ABSENCE
+ * is structural rather than a caller's omission (a wire envelope with no such
+ * field), say 'unknown' at that site explicitly instead of routing through here.
+ */
+export function asProvenance( raw: unknown ): SignalProvenance {
+  return raw === 'reafferent' ? 'reafferent'
+       : raw === 'unknown'    ? 'unknown'
+       : 'exafferent'
+}

package/src/cognition/senses/somatosensation.engine.ts

@@ -3,21 +3,129 @@
 // ─────────────────────────────────────────────────────────────
 
 /**
- * SomatosensationEngine [SHELL] — touch / physical-world interaction.
+ * SomatosensationEngine — the sense that feels things happen TO the mind.
  *
- * Handles webhook events, system signals, and external API callbacks — Will's
- * "touch", its awareness of interaction with external systems. Future: route
- * incoming webhooks as percepts into ThreatEvaluator / RewardEvaluator.
+ * Webhooks, system signals, external callbacks: not something said, not
+ * something seen, but the world touching the mind directly. It was the first
+ * shell to be implemented because the wake event needed a door — SIGNAL_BOUNDARY
+ * P1 — and a hand-written percept in `stem/index.ts` was the bypass that proved
+ * the door was missing.
  *
- * Currently a structural stub — `_perceive()` (inherited from ShellSenseEngine)
- * logs a warning and returns. The base handles gate / filter / publish / boilerplate.
+ * WHAT MAKES THIS A SENSE RATHER THAN A HELPER. It does nothing the other senses
+ * do not: transduce an input into a `Percept` with a salience and a summary, and
+ * hand it to `publishPercept`, which stamps provenance from the host's assertion
+ * and lays down the trace. Everything downstream — the rupture gate, working
+ * memory, the executive prompt, novelty — receives it because it is a percept,
+ * not because anyone wired those five places to a wake event.
+ *
+ * That is the whole point of a door: the wake event stops being special.
  */
 
-import type { SensoryInput } from '#senses/index'
-import { ShellSenseEngine } from '#senses/base.sense.engine'
+import type { SensoryInput, SystemSignal, WebhookEvent, Percept, Transduced } from '#senses/index'
+import { BaseSenseEngine } from '#senses/base.sense.engine'
+import { PERCEPT_SUMMARY_CAP } from '#cognition/percept.entity'
+
+/**
+ * How loud a system signal is by default.
+ *
+ * A signal arrives because something HAPPENED to the mind — a host woke it, a
+ * webhook fired — so it outranks the ambient world-change percepts
+ * `exteroception` produces at 0.3, and clears `action.selector`'s rupture gate
+ * (0.4). A host that knows better says so with `salience` on the input.
+ */
+export const SYSTEM_SIGNAL_SALIENCE = 0.75
 
-export class SomatosensationEngine extends ShellSenseEngine {
+export class SomatosensationEngine extends BaseSenseEngine {
   readonly name   = 'somatosensation-engine'
   readonly domain = 'somatosensation' as const
   protected readonly acceptedKinds = new Set<SensoryInput['kind']>( [ 'webhook', 'system' ] )
+
+  protected async _perceive( input: SensoryInput ): Promise<void> {
+    const percept: Transduced<Percept> = input.kind === 'system'
+      ? this._fromSignal( input as SystemSignal )
+      : this._fromWebhook( input as WebhookEvent )
+
+    this.publishPercept( percept, input )
+  }
+
+  private _fromSignal( s: SystemSignal ): Transduced<Percept> {
+    return {
+      domain:         this.domain,
+      // The signal IS the source: nothing in the world sent it, the substrate did.
+      sourceEntityId: `system:${ s.signal }`,
+      timestamp:      0,
+      salience:       salienceOf( s.data, SYSTEM_SIGNAL_SALIENCE ),
+      summary:        labelFor( s.signal, s.data ),
+      ...( s.data !== undefined && s.data !== null ? { data: s.data } : {} ),
+      raw:            s,
+    }
+  }
+
+  private _fromWebhook( w: WebhookEvent ): Transduced<Percept> {
+    return {
+      domain:         this.domain,
+      sourceEntityId: `webhook:${ w.source }`,
+      timestamp:      0,
+      salience:       salienceOf( w.payload, SYSTEM_SIGNAL_SALIENCE ),
+      summary:        labelFor( w.source, w.payload ),
+      ...( w.payload !== undefined && w.payload !== null ? { data: w.payload } : {} ),
+      raw:            w,
+    }
+  }
+}
+
+/**
+ * A LABEL for a signal — what arrived, not what it means.
+ *
+ * The mind makes the meaning; this only has to make the percept legible enough
+ * to be noticed and connected to its data. A HOST IS NEVER ASKED FOR PROSE:
+ * demanding a sentence from a robot's control layer puts the mind's own work on
+ * the wrong side of the integration boundary, and a lidar driver has no business
+ * describing what a scan implies.
+ *
+ * The signal's own NAME is the hint, and it is free — `discord_server_snapshot`,
+ * `WAKE`, `lidar.scan` already say what kind of thing this is. A host that
+ * happens to have words may put a `summary` on its data and they are used
+ * instead; it is an option, never an obligation.
+ *
+ * Bounded by `PERCEPT_SUMMARY_CAP` because the ENGINE writes it. The data it
+ * labels is beside it, whole and uncapped.
+ */
+function labelFor( signal: string, data: unknown ): string {
+  const words = hostWords( data )
+  if( words ) return words.length > PERCEPT_SUMMARY_CAP
+    ? `${ words.slice( 0, PERCEPT_SUMMARY_CAP - 1 ) }\u2026` : words
+
+  const rendered = compact( data )
+  const label = rendered ? `${ signal }: ${ rendered }` : `Something happened: ${ signal }.`
+  return label.length > PERCEPT_SUMMARY_CAP
+    ? `${ label.slice( 0, PERCEPT_SUMMARY_CAP - 1 ) }\u2026` : label
+}
+
+/** A host's own words, if it chose to offer any. Optional, never required. */
+function hostWords( data: unknown ): string | undefined {
+  if( typeof data === 'string') return data.length > 0 ? data : undefined
+  if( typeof data === 'object' && data !== null && !Array.isArray( data ) ){
+    const s = ( data as Record<string, unknown> )['summary']
+    if( typeof s === 'string' && s.length > 0 ) return s
+  }
+  return undefined
+}
+
+/** A glance at the shape, for the label only. The whole thing rides in `data`. */
+function compact( data: unknown ): string | undefined {
+  if( data === undefined || data === null ) return undefined
+  if( typeof data !== 'object') return String( data )
+  try {
+    const json = JSON.stringify( data )
+    return json === '{}' || json === '[]' ? undefined : json
+  }
+  catch { return undefined }   // circular — the label falls back to the name
+}
+
+/** Same door for salience: the host may say, otherwise the default stands. */
+function salienceOf( data: unknown, fallback: number ): number {
+  if( typeof data !== 'object' || data === null || Array.isArray( data ) ) return fallback
+  const s = ( data as Record<string, unknown> )['salience']
+  return typeof s === 'number' && Number.isFinite( s ) ? Math.max( 0, Math.min( 1, s ) ) : fallback
 }