@mindot/will 0.1.0

package/src/cognition/senses/audition.engine/salience.ts

@@ -0,0 +1,59 @@
+// ─────────────────────────────────────────────────────────────
+// src/cognition/senses/audition.engine/salience.ts
+// ─────────────────────────────────────────────────────────────
+//
+// Language salience — how much a given inbound message *matters*, before the
+// per-entity novelty model (GenerativeModel.observe) modulates it.
+//
+// Pure + deterministic: a function of the message content, the speaker's
+// attachment strength, and the Will's active-goal topics. No wall-clock — the
+// score feeds attention allocation + GWT workspace gating, which are
+// replay-sensitive, so it must not depend on non-deterministic time.
+// "Recency/novelty" is handled separately by the per-entity GenerativeModel
+// baseline (a normally-quiet entity suddenly speaking spikes), not here.
+// ─────────────────────────────────────────────────────────────
+
+export interface LanguageSalienceInput {
+  /** Raw message text. */
+  content:         string
+  /** Speaker's attachment strength, 0–1 (0 = stranger / no bond). */
+  attachmentScore: number
+  /** Active-goal descriptions + tags, for topic-overlap detection. */
+  activeGoalText:  string[]
+}
+
+const URGENCY = /urgent|critical|help|asap|emergency|now\b/i
+
+const clamp01 = ( n: number ): number => Math.max( 0, Math.min( 1, n ) )
+
+/** True when the message shares a meaningful token with any active goal. */
+function overlapsActiveGoal( content: string, activeGoalText: string[] ): boolean {
+  if( activeGoalText.length === 0 ) return false
+  const lc = content.toLowerCase()
+  for( const text of activeGoalText )
+    for( const word of text.toLowerCase().split( /\W+/ ) )
+      if( word.length > 3 && lc.includes( word ) ) return true
+  return false
+}
+
+/**
+ * Compute language salience (0–1) for an inbound message.
+ *
+ * Weighting (sums, then clamps):
+ *   - base       0.15  — a floor so a first/neutral message is non-trivial
+ *   - urgency    0.30  — explicit urgency keywords
+ *   - attachment 0.35  — closer relationship ⇒ more salient (the big lever)
+ *   - goal       0.15  — topic overlaps an active goal
+ *   - length     0.05  — longer ⇒ slightly more substantive (normalised to 200 chars)
+ */
+export function computeLanguageSalience( opts: LanguageSalienceInput ): number {
+  const { content, attachmentScore, activeGoalText } = opts
+
+  const base    = 0.15
+  const urgency = URGENCY.test( content )                       ? 0.30 : 0
+  const attach  = clamp01( attachmentScore ) * 0.35
+  const goal    = overlapsActiveGoal( content, activeGoalText ) ? 0.15 : 0
+  const length  = Math.min( 1, content.length / 200 )           * 0.05
+
+  return clamp01( base + urgency + attach + goal + length )
+}

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

@@ -0,0 +1,117 @@
+// ─────────────────────────────────────────────────────────────
+// src/cognition/senses/base.sense.engine.ts
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * BaseSenseEngine — the shared perceptual pipeline (§6).
+ *
+ * Every sense engine repeats the same skeleton: CognitiveEngine boilerplate,
+ * an effector gate, a kind filter, and a percept publish on `senses.<domain>.percept`.
+ * This base captures all of it as a template method so each concrete engine only
+ * declares WHAT it senses (`domain`, `acceptedKinds`, optional `gateEffector`) and
+ * implements the domain-specific `_perceive()`.
+ *
+ * Flow (template method `ingest`):
+ *   effector gate (optional) → kind filter → `_perceive(input)`
+ *
+ * `_perceive()` does the domain work and calls `publishPercept()` — the single
+ * chokepoint for emitting on the bus. That chokepoint is also where a future
+ * cross-modal binder would observe percepts of the same `sourceEntityId` across
+ * domains (see §6 cross-modal note).
+ *
+ * - `AuditionEngine` extends this and overrides `publishes()`/`snapshot()` for its
+ *   extra `audition.task.signal` schema and session snapshot.
+ * - The four shell engines extend `ShellSenseEngine` (below) and are ~6 lines each.
+ */
+
+import { logger } from '#core/logger'
+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'
+
+export abstract class BaseSenseEngine implements SenseEngine {
+  abstract readonly name:   string
+  abstract readonly domain: SenseDomain
+
+  /**
+   * 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.
+   */
+  protected abstract readonly acceptedKinds: ReadonlySet<SensoryInput['kind']>
+
+  /**
+   * Effector that gates ingestion (e.g. audition → 'listen'). When set and
+   * AccessGrants denies it, `ingest()` is a silent no-op — the engine stays
+   * wired but functionally inactive. `null` = always active.
+   */
+  protected readonly gateEffector: string | null = null
+
+  protected _bus:    CognitiveBus | null = null
+  protected _grants: AccessGrants | null = null
+
+  // ── 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 }
+
+  // ── CognitiveEngine defaults ─────────────────────────────
+  publishes(): CognitiveEventSchema[] {
+    return [ { type: `senses.${this.domain}.percept`, version: 1, validate: () => null } ]
+  }
+  subscribes(): string[] { return [] }
+  onCognitiveEvent( _e: CognitiveEvent ): StateCommands | void { /* sense engines are ingest-driven */ }
+  snapshot(): Record<string, unknown> { return { domain: this.domain } }
+
+  // ── SenseEngine: the shared template ─────────────────────
+  /**
+   * Apply the effector gate + kind filter common to every sense, then delegate
+   * the domain-specific work to `_perceive()`. Subclasses never re-handle gating
+   * or filtering — they only implement `_perceive()`.
+   */
+  async ingest( 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
+    await this._perceive( input )
+  }
+
+  /** Domain-specific perception. Invoked only for accepted kinds, past the gate. */
+  protected abstract _perceive( input: SensoryInput ): Promise<void>
+
+  // ── Shared helpers ───────────────────────────────────────
+  /**
+   * 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.
+   */
+  protected publishPercept( percept: Percept ): void {
+    this._bus?.publish({
+      type:         `senses.${this.domain}.percept`,
+      version:      1,
+      sourceEngine: this.name,
+      salience:     percept.salience,
+      payload:      percept,
+    })
+  }
+}
+
+/**
+ * ShellSenseEngine — base for the not-yet-implemented senses
+ * (vision, somatosensation, olfaction, gustation).
+ *
+ * `_perceive()` logs a warning (only ever reached for an accepted kind, since the
+ * base filters first) and `snapshot()` advertises shell status. A concrete shell
+ * is just: `name`, `domain`, and `acceptedKinds`.
+ */
+export abstract class ShellSenseEngine extends BaseSenseEngine {
+  snapshot(): Record<string, unknown> {
+    return { domain: this.domain, status: 'shell' }
+  }
+
+  protected async _perceive( _input: SensoryInput ): Promise<void> {
+    logger.warn( `[${this.name}] ingest() called — engine is a shell, not yet implemented.` )
+  }
+}

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

@@ -0,0 +1,24 @@
+// ─────────────────────────────────────────────────────────────
+// src/cognition/senses/gustation.engine.ts
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * GustationEngine [SHELL] — taste / internal self-evaluation.
+ *
+ * Handles internal self-evaluation triggers and identity alignment checks —
+ * Will's "taste", introspective quality assessment of its own outputs and
+ * identity coherence after significant events. Future: post-action quality
+ * assessment into ConfidenceCalibrator / BiasDetector and SelfModelUpdater.
+ *
+ * Currently a structural stub — `_perceive()` (inherited from ShellSenseEngine)
+ * logs a warning and returns. The base handles gate / filter / publish / boilerplate.
+ */
+
+import type { SensoryInput } from '#senses/index'
+import { ShellSenseEngine } from '#senses/base.sense.engine'
+
+export class GustationEngine extends ShellSenseEngine {
+  readonly name   = 'gustation-engine'
+  readonly domain = 'gustation' as const
+  protected readonly acceptedKinds = new Set<SensoryInput['kind']>( [ 'self-eval', 'assessment' ] )
+}

package/src/cognition/senses/index.ts

@@ -0,0 +1,172 @@
+// ─────────────────────────────────────────────────────────────
+// src/cognition/senses/index.ts
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Perceptual Tier — 5 Senses Architecture
+ *
+ * Shared types and the SenseEngine interface for all sense engines.
+ * Sense engines are CognitiveEngines that also expose an `ingest()` method
+ * for external stimuli to enter Will's cognitive pipeline.
+ *
+ * Events flow on the existing CognitiveBus under the `senses.*` topic prefix:
+ *   senses.audition.percept   — LanguagePercept from AuditionEngine
+ *   senses.vision.percept     — (shell, future)
+ *   senses.somatosensation.percept — (shell, future)
+ *   senses.olfaction.percept  — (shell, future)
+ *   senses.gustation.percept  — (shell, future)
+ *
+ * AttentionAllocator subscribes to 'senses.*' to receive all percepts.
+ */
+
+import type { CognitiveEngine } from '#cognition/types'
+import type { CognitiveBus }    from '#cognition/bus'
+
+// ── Domain ────────────────────────────────────────────────────
+
+export type SenseDomain =
+  | 'audition'        // language, voice — AuditionEngine
+  | 'vision'          // images, video   — VisionEngine (shell)
+  | 'somatosensation' // webhooks, events — SomatosensationEngine (shell)
+  | 'olfaction'       // ambient signals  — OlfactionEngine (shell)
+  | 'gustation'       // self-evaluation  — GustationEngine (shell)
+
+// ── Percept types ─────────────────────────────────────────────
+
+/** Base percept published on the CognitiveBus. */
+export interface Percept {
+  domain:         SenseDomain
+  sourceEntityId: string
+  timestamp:      number
+  salience:       number   // 0–1, computed by the sense engine
+  raw:            unknown  // original input object
+}
+
+/** Audition-specific percept — carries language content and thread context. */
+export interface LanguagePercept extends Percept {
+  domain:          'audition'
+  channel:         'text' | 'voice'
+  content:         string
+  speakerEntityId: string
+  threadId:        string
+  /** Rolling context: last N user + will turns in the thread. */
+  digest:          string
+}
+
+// ── Sensory input types (discriminated union) ─────────────────
+
+// Audition
+export interface TextMessage {
+  kind:     'text'
+  entityId: string
+  threadId: string
+  content:  string
+  /** Display name — used in the facet focus content. */
+  speakerName?: string
+}
+
+export interface VoiceChunk {
+  kind:           'voice'
+  entityId:       string
+  threadId:       string
+  audioBuffer?:   Buffer
+  transcription?: string
+}
+
+// Vision (stub)
+export interface ImageFrame {
+  kind:     'image'
+  entityId: string
+  data:     Buffer
+  mimeType: string
+}
+
+export interface VideoSegment {
+  kind:      'video'
+  entityId:  string
+  frames:    ImageFrame[]
+  durationMs: number
+}
+
+// Somatosensation (stub)
+export interface WebhookEvent {
+  kind:    'webhook'
+  source:  string
+  payload: unknown
+  headers: Record<string, string>
+}
+
+export interface SystemSignal {
+  kind:   'system'
+  signal: string
+  data:   unknown
+}
+
+// Olfaction (stub)
+export interface AmbientMetric {
+  kind:      'ambient'
+  metricKey: string
+  value:     number
+  trend:     'rising' | 'falling' | 'stable'
+}
+
+export interface BackgroundSignal {
+  kind:     'background'
+  category: string
+  data:     unknown
+}
+
+// Gustation (stub)
+export interface InternalEvaluation {
+  kind:    'self-eval'
+  context: string
+  trigger: string
+}
+
+export interface SelfAssessmentTrigger {
+  kind:      'assessment'
+  goalId?:   string
+  checkType: string
+}
+
+/** Discriminated union of all sensory input kinds. */
+export type SensoryInput =
+  | TextMessage
+  | VoiceChunk
+  | ImageFrame
+  | VideoSegment
+  | WebhookEvent
+  | SystemSignal
+  | AmbientMetric
+  | BackgroundSignal
+  | InternalEvaluation
+  | SelfAssessmentTrigger
+
+// ── SenseEngine interface ─────────────────────────────────────
+
+/**
+ * SenseEngine — a CognitiveEngine that also accepts external stimuli.
+ *
+ * Sense engines implement the full CognitiveEngine contract
+ * (publishes, subscribes, onCognitiveEvent, snapshot) plus:
+ *   - `domain`: declares which sensory domain this engine handles
+ *   - `ingest()`: entry point for external stimuli (called by WillManager)
+ *   - `attachBus()`: called automatically by CognitiveOrchestrator.addEngine()
+ *
+ * Shell engines have no-op `ingest()` bodies — they log a warning and return.
+ * Full engines (AuditionEngine) process percepts and publish to the bus.
+ */
+export interface SenseEngine extends CognitiveEngine {
+  readonly domain: SenseDomain
+  attachBus( bus: CognitiveBus ): void
+  ingest( input: SensoryInput ): Promise<void>
+}
+
+// ── Re-exports ────────────────────────────────────────────────
+
+export { BaseSenseEngine, ShellSenseEngine } from './base.sense.engine'
+export { AuditionEngine }    from './audition.engine/engine'
+export { VisionEngine }      from './vision.engine'
+export { SomatosensationEngine } from './somatosensation.engine'
+export { OlfactionEngine }   from './olfaction.engine'
+export { GustationEngine }   from './gustation.engine'

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

@@ -0,0 +1,24 @@
+// ─────────────────────────────────────────────────────────────
+// src/cognition/senses/olfaction.engine.ts
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * OlfactionEngine [SHELL] — smell / ambient background monitoring.
+ *
+ * Handles ambient metrics and background signals — slow drifts and low-priority
+ * environmental monitoring. Will's "smell", detecting the ambient atmosphere
+ * before explicit events occur. Future: feed low-salience signals into
+ * AffectiveBlender for slow-burn mood modulation.
+ *
+ * Currently a structural stub — `_perceive()` (inherited from ShellSenseEngine)
+ * logs a warning and returns. The base handles gate / filter / publish / boilerplate.
+ */
+
+import type { SensoryInput } from '#senses/index'
+import { ShellSenseEngine } from '#senses/base.sense.engine'
+
+export class OlfactionEngine extends ShellSenseEngine {
+  readonly name   = 'olfaction-engine'
+  readonly domain = 'olfaction' as const
+  protected readonly acceptedKinds = new Set<SensoryInput['kind']>( [ 'ambient', 'background' ] )
+}

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

@@ -0,0 +1,23 @@
+// ─────────────────────────────────────────────────────────────
+// src/cognition/senses/somatosensation.engine.ts
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * SomatosensationEngine [SHELL] — touch / physical-world interaction.
+ *
+ * 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.
+ *
+ * Currently a structural stub — `_perceive()` (inherited from ShellSenseEngine)
+ * logs a warning and returns. The base handles gate / filter / publish / boilerplate.
+ */
+
+import type { SensoryInput } from '#senses/index'
+import { ShellSenseEngine } from '#senses/base.sense.engine'
+
+export class SomatosensationEngine extends ShellSenseEngine {
+  readonly name   = 'somatosensation-engine'
+  readonly domain = 'somatosensation' as const
+  protected readonly acceptedKinds = new Set<SensoryInput['kind']>( [ 'webhook', 'system' ] )
+}

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

@@ -0,0 +1,23 @@
+// ─────────────────────────────────────────────────────────────
+// src/cognition/senses/vision.engine.ts
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * VisionEngine [SHELL] — sight / visual perception.
+ *
+ * Future: multimodal LLM calls to interpret image frames and video segments;
+ * publishes `senses.vision.percept` events via the shared BaseSenseEngine flow.
+ *
+ * Currently a structural stub — `_perceive()` (inherited from ShellSenseEngine)
+ * logs a warning and returns. The base handles the effector gate, kind filter,
+ * percept publish, and CognitiveEngine boilerplate.
+ */
+
+import type { SensoryInput } from '#senses/index'
+import { ShellSenseEngine } from '#senses/base.sense.engine'
+
+export class VisionEngine extends ShellSenseEngine {
+  readonly name   = 'vision-engine'
+  readonly domain = 'vision' as const
+  protected readonly acceptedKinds = new Set<SensoryInput['kind']>( [ 'image', 'video' ] )
+}

package/src/cognition/types.ts

@@ -0,0 +1,63 @@
+// ─────────────────────────────────────────────────────────────
+// src/cognition/cognitive.engine.ts
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * CognitiveEngine — additive interface for engines that participate in the
+ * event-driven cognitive bus architecture.
+ *
+ * Any SimulationEngine can opt in by implementing these four methods.
+ * Engines that don't implement it continue to work normally via react().
+ * Migration can happen engine-by-engine with no orchestrator changes.
+ */
+
+import type { StateCommands } from '#core/types'
+import type { CognitiveEvent } from '#cognition/bus'
+import type { SimulationEngine } from '#core/orchestrator'
+import type { CognitiveEventSchema } from '#cognition/schema.registry'
+
+// Re-export core engine types so cognition-layer files have one import point
+export type { SimulationEngine, EngineResult, TickMiddleware } from '#core/orchestrator'
+
+export interface CognitiveEngine extends SimulationEngine {
+  /** Event schemas this engine may publish — declared at registration time. */
+  publishes(): CognitiveEventSchema[]
+
+  /** Topic patterns this engine subscribes to — used for bus wiring and cycle detection. */
+  subscribes(): string[]
+
+  /**
+   * Declare which schema versions this engine accepts for a given event type.
+   * If not implemented (or returns empty), any version is accepted.
+   * The bus will attempt migration before delivery when version is not in the list.
+   * Phase A: per-subscriber version filtering.
+   */
+  acceptsVersions?( eventType: string ): number[]
+
+  /** Called by the bus on event delivery — never called concurrently. */
+  onCognitiveEvent( event: CognitiveEvent ): StateCommands | void
+
+  /** Full local state snapshot for cold-start bootstrap and debugging. */
+  snapshot(): Record<string, unknown>
+
+  /**
+   * Rehydrate engine-internal mutable state from a prior snapshot() payload (FN9).
+   *
+   * snapshot() captures private accumulating state (activity multipliers, salience
+   * baselines, generative-model predictions) that the event-sourced SimulationState
+   * never sees; restore() is the matching seam that lets a snapshot/replay reproduce
+   * it instead of resuming with freshly-zeroed internals. Optional and additive:
+   * engines that don't implement it keep their old behaviour, and a restore caller
+   * must treat it as best-effort (feature-detect before calling).
+   */
+  restore?( snapshot: Record<string, unknown> ): void
+}
+
+export function isCognitiveEngine( engine: SimulationEngine ): engine is CognitiveEngine {
+  return (
+    typeof ( engine as CognitiveEngine ).publishes         === 'function' &&
+    typeof ( engine as CognitiveEngine ).subscribes        === 'function' &&
+    typeof ( engine as CognitiveEngine ).onCognitiveEvent  === 'function' &&
+    typeof ( engine as CognitiveEngine ).snapshot          === 'function'
+  )
+}