@mindot/will 0.8.0 → 0.10.0

package/src/cognition/index.ts

@@ -13,6 +13,7 @@ import {
   type ModelPrice,
 } from '#cognition/utilities/token.tracker'
 
+import type { VectorMemoryAdapter } from '#memory/vector.adapter'
 import { EnergyRegulator, type EnergyRegulatorConfig } from '#faculties/energy.regulator'
 import { SleepPressureRegulator, type SleepPressureConfig } from '#faculties/sleep.pressure.regulator'
 import { AttentionAllocator, type AttentionAllocatorConfig } from '#faculties/attention.allocator'
@@ -256,6 +257,12 @@ export type EngineRegistry = {
   affectiveBlender: AffectiveBlender
   workingMemory: WorkingMemory
   episodicConsolidator: EpisodicConsolidator
+  /**
+   * The vector index, when semantic recall is configured. Exposed so shutdown can
+   * FLUSH it: it lives outside the state snapshot and previously persisted only from
+   * a debounce timer no shutdown path awaited, so it died with the process.
+   */
+  vectorMemory: VectorMemoryAdapter | null
   semanticIntegrator: SemanticIntegrator
   spacedRepetition: SpacedRepetition
   forgettingCurve: ForgettingCurve

package/src/cognition/instruction.handler.ts

@@ -18,7 +18,7 @@ export interface Instruction {
   deadline?: number
   /** Constraints on how to execute */
   constraints?: string[]
-  /** Context/provenance — why this instruction was given */
+  /** Context — why this instruction was given */
   context: string
   /** Whether the Will can refuse */
   isOverridable: boolean

package/src/cognition/memory/vector.adapter.ts

@@ -302,15 +302,24 @@ export class DefaultVectorMemoryAdapter implements VectorMemoryAdapter {
     if( victims.length > 0 ) this._dirty = true
   }
 
+  /**
+   * Throttle, NOT a debounce. The previous version cleared and re-armed the timer on
+   * every index(), so it only ever fired after 5s of complete inactivity — and a mind
+   * consolidating steadily indexes far more often than that, so the write was pushed
+   * back indefinitely and the index never reached disk while it was awake.
+   *
+   * A pending timer is now left alone: the first write after a quiet period sets the
+   * deadline, and everything indexed within the window rides along on it. Persist is
+   * bounded at 5s from the FIRST pending change rather than the last.
+   */
   private _schedulePersist(): void {
-    if( this._persistDebounceTimer )
-      clearTimeout( this._persistDebounceTimer )
+    if( this._persistDebounceTimer ) return
 
     this._persistDebounceTimer = setTimeout( () => {
+      this._persistDebounceTimer = null
       this.persist().catch( err => {
         logger.error(`[VectorMemoryAdapter] Persist failed:`, err )
       } )
-      this._persistDebounceTimer = null
     }, 5000 )
   }
 }

package/src/cognition/memory/vector.embedder.ts

@@ -13,6 +13,7 @@
 
 import type { TokenTracker } from '#cognition/utilities/token.tracker'
 import type { LLMCallFunction } from '#cognition/utilities/token.tracker'
+import { LLMSemaphore, withGate } from '#llm/gate'
 
 /** Embedding is only ever a read or a write. */
 export type EmbedFunction = Extract<LLMCallFunction, 'recall' | 'index'>
@@ -44,16 +45,28 @@ export class OpenAICompatibleEmbedder implements EmbeddingProvider {
   private _maxConcurrency: number
   private _timeoutMs: number
   private _tokenTracker: TokenTracker | null
+  /**
+   * Own gate — the same LLMSemaphore the LLM calls use, on a separate instance so
+   * embeddings and reasoning do not compete for one another's slots. It bounds the
+   * fan-out that produced the 10.7s tail, and `withGate` additionally retries a 429
+   * with backoff, which a bare `embed()` previously surfaced as a hard failure.
+   */
+  private _gate: LLMSemaphore
 
   constructor( config: {
     modelName: string
     dimensions: number
     apiUrl: string
     apiKey?: string | null
-    /** Max embedding requests in flight at once for embedBatch(). Default 8. */
+    /**
+     * Max embedding requests in flight at once — across ALL callers, not just one
+     * embedBatch(). Default 4, chosen from measured provider behaviour rather than
+     * taste: gemini-embedding-001 answers a lone request in ~1.1s, but queues hard
+     * under fan-out — at 8 in flight the slowest three took 10.7s (all HTTP 200, no
+     * 429, simply serialized). That tail is what made recall exceed its 5s budget
+     * and return "no recall" while a mind with six live facets was asking.
+     */
     maxConcurrency?: number
-    /** @deprecated use maxConcurrency — kept as its fallback for back-compat. */
-    batchSize?: number
     /** Per-request timeout in ms before the connection is aborted. Default 30s. */
     timeoutMs?: number
     /**
@@ -67,12 +80,24 @@ export class OpenAICompatibleEmbedder implements EmbeddingProvider {
     this.dimensions = config.dimensions
     this._apiUrl = config.apiUrl
     this._apiKey = config.apiKey ?? null
-    this._maxConcurrency = Math.max( 1, config.maxConcurrency ?? config.batchSize ?? 8 )
+    this._maxConcurrency = Math.max( 1, config.maxConcurrency ?? 4 )
+    this._gate = new LLMSemaphore( this._maxConcurrency )
     this._timeoutMs = config.timeoutMs ?? 30_000
     this._tokenTracker = config.tokenTracker ?? null
   }
 
+  /**
+   * Embed one item, gated. Every caller funnels through here — a facet building a
+   * prompt, the master recalling, the consolidator indexing — so the gate is the
+   * only place total in-flight fan-out is bounded. Waiting for a slot is strictly
+   * better than the alternative it replaces: an ungated request that returns after
+   * the recall budget has already expired is a request whose answer is thrown away.
+   */
   async embed( content: unknown, fn: EmbedFunction = 'recall'): Promise<number[]> {
+    return withGate( () => this._embedOnce( content, fn ), `embed:${ this.modelName }`, this._gate )
+  }
+
+  private async _embedOnce( content: unknown, fn: EmbedFunction ): Promise<number[]> {
     let response: Response
     try {
       response = await fetch(`${this._apiUrl}/embeddings`, {
@@ -110,6 +135,21 @@ export class OpenAICompatibleEmbedder implements EmbeddingProvider {
     if( !Array.isArray( embedding ) || embedding.length === 0 )
       throw new Error(`Embedding response was empty or malformed for model ${this.modelName}`)
 
+    // The configured width must match what the provider actually returns. This class
+    // sends no `dimensions` param, so the index is sized from config alone — and a
+    // wrong number does not fail, it silently builds an index that can never match.
+    // Providers differ per model family and change defaults between versions, so the
+    // number is checked against reality once rather than trusted. Failing here is safe:
+    // indexing degrades to "deferred" and recall to "no recall", both already
+    // best-effort, and the message carries the value to set.
+    if( embedding.length !== this.dimensions )
+      throw new Error(
+        `Embedding width mismatch for ${ this.modelName }: provider returned ${ embedding.length } ` +
+        `dimensions, index is configured for ${ this.dimensions }. ` +
+        `Set WILL_EMBEDDING_DIMENSIONS=${ embedding.length } (and delete any existing ` +
+        `vector_index built at the old width).`
+      )
+
     // Meter embedding token usage (input-only — embeddings have no completion).
     // Recorded under the 'embedding' category so per-Will dashboards can split
     // memory-vector spend from LLM reasoning spend.
@@ -122,6 +162,7 @@ export class OpenAICompatibleEmbedder implements EmbeddingProvider {
         totalTokens:      usedTok,
         category:         'embedding',
         attribute:        'memory',
+        process:          'cog',        // background: no deliberation happens here
         function:         fn,           // 'recall' (query) | 'index' (write)
         scope:            this.modelName,
         tick:             0,

package/src/cognition/percept.entity.ts

@@ -0,0 +1,122 @@
+// ─────────────────────────────────────────────────────────────
+// src/cognition/percept.entity.ts  —  one shape for "something reached me"
+// ─────────────────────────────────────────────────────────────
+//
+// A `percept` entity is the staging area every downstream consumer of afference
+// reads. Five places write one and none of them agreed on what one is:
+//
+//   exteroception       tick ✓  provenance ✓   the complete one
+//   outbox.controller   tick ✗  provenance ✓
+//   escalation.buffer   tick ✓  provenance ✗   (x2)
+//   stem/index.ts       tick ✗  provenance ✗   the wake percept
+//
+// Both omissions are silent and both cost something real:
+//
+//   • NO `tick` — `exteroception._collectStalePerceptIds` is the ONLY sweeper of
+//     this type, and it collects only entities whose `metadata.tick` is a
+//     number. Everything else is immortal. `msg-delivered-<id>` therefore leaks
+//     one entity per message the mind ever successfully sends, and the wake
+//     percept tells the executive "I was offline for 3 hours" for the rest of
+//     the mind's life.
+//   • NO `provenance` — `action.selector`'s rupture gate counts only percepts
+//     tagged `'exafferent'`, so an untagged percept can never rupture a
+//     commitment, exactly as the mind's own echo cannot. A mind waking after
+//     hours offline cannot be ruptured by noticing that.
+//
+// Neither is a bug in the writers. They are a bug in there being no shape to
+// write: every one of them hand-rolled a metadata literal, and a literal cannot
+// forget a field it was never asked for. This is the shape. It makes `tick` and
+// `provenance` REQUIRED, so the sweeper's precondition and the rupture gate's
+// precondition are both structural rather than remembered.
+//
+// SIGNAL_BOUNDARY P0. Own the contract before widening it — the sense door is
+// about to become a sixth writer, and it must not invent a sixth variant.
+
+import type { SignalProvenance } from '#senses/provenance'
+
+export const PERCEPT_TYPE = 'percept'
+
+/**
+ * How long a `percept` survives before `Exteroception` sweeps it. Not a
+ * durability window — a *staging* window. Persistence happens downstream
+ * (WorkingMemory → EpisodicConsolidator → vector); a percept's job is to be
+ * seen once by the faculties that run each tick, then get out of the way.
+ */
+export const PERCEPT_STALE_AFTER_TICKS = 2
+
+/**
+ * How much of a percept's `summary` survives.
+ *
+ * 100 because that is what `exteroception._summarizeEntity` has always used —
+ * adopted rather than chosen, so naming it changes no behaviour. It is now one
+ * constant instead of a literal per writer, which is the point: the sizing
+ * question is real and open (SIGNAL_BOUNDARY §4 asks it of 120/300/700 too, and
+ * notes that none of those was ever a budget decision), and answering it should
+ * be a one-line change in one place rather than an archaeology exercise.
+ */
+export const PERCEPT_SUMMARY_CAP = 100
+
+/** What every percept must say, whatever wrote it. */
+export interface PerceptFacts {
+  /** Deterministic and unique. Never `wallClock()` — this lives in state (R2). */
+  id:         string
+  /** The tick it arrived on. REQUIRED: without it the entity is never swept. */
+  tick:       number
+  /** 0–1. The rupture gate reads this. */
+  salience:   number
+  /** Coarse kind, for grouping — 'message-delivery', 'system', 'undertaking'… */
+  category:   string
+  /** The one field the executive prompt renders. If it is not here, it is unread. */
+  summary:    string
+  /** REQUIRED: untagged means unrupturable. See `SignalProvenance`. */
+  provenance: SignalProvenance
+  /** The intent this is the consequence of, when `provenance` is `'reafferent'`. */
+  sourceIntentId?: string
+  /** The world entity this is about, where there is one. */
+  entityId?:      string
+  /** What happened to it — 'delivered', 'removed', 'changed'… */
+  changeType?:    string
+  /** What it FELT like, and how much that says about it (registry #5). */
+  valence?:       number
+  valenceSource?: string
+  /**
+   * What a host sent, whole. Carried into state so it survives to working
+   * memory, recall and the prompt — `summary` is a label the engine wrote, and
+   * a mind reasoning only from labels is reasoning from somebody else's
+   * conclusions.
+   */
+  data?:          unknown
+}
+
+/** The write-side entity shape `stateManager.setEntity` accepts. */
+export interface PerceptEntity {
+  id:       string
+  type:     typeof PERCEPT_TYPE
+  metadata: Record<string, unknown>
+}
+
+/**
+ * Build a `percept` entity. `extra` carries a writer's own fields (`messageId`,
+ * `facetId`, `offlineMs`…) and cannot overwrite the core: a writer that could
+ * clobber its own `tick` or `provenance` is back where it started.
+ */
+export function perceptEntity( facts: PerceptFacts, extra: Record<string, unknown> = {} ): PerceptEntity {
+  return {
+    id:   facts.id,
+    type: PERCEPT_TYPE,
+    metadata: {
+      ...extra,
+      tick:       facts.tick,
+      salience:   facts.salience,
+      category:   facts.category,
+      summary:    facts.summary,
+      provenance: facts.provenance,
+      ...( facts.sourceIntentId !== undefined ? { sourceIntentId: facts.sourceIntentId } : {} ),
+      ...( facts.entityId       !== undefined ? { entityId:       facts.entityId       } : {} ),
+      ...( facts.changeType     !== undefined ? { changeType:     facts.changeType     } : {} ),
+      ...( facts.valence        !== undefined ? { valence:        facts.valence        } : {} ),
+      ...( facts.valenceSource  !== undefined ? { valenceSource:  facts.valenceSource  } : {} ),
+      ...( facts.data           !== undefined ? { data:           facts.data           } : {} ),
+    },
+  }
+}

package/src/cognition/persona.prior.ts

@@ -118,6 +118,7 @@ const PRIOR_DESCRIPTIONS: Record<string, { lower: string; raise: string }> = {
   'engine-config-inhibition.baseInhibitionStrength':  { lower: 'acting on impulse more freely',              raise: 'holding myself in check more firmly before acting' },
   'engine-config-self-model.minNewExperiences':       { lower: 're-evaluating who I am on less new experience', raise: 'requiring more new experience before re-evaluating who I am' },
   'engine-config-attention.shiftInertia':             { lower: 'shifting my attention more readily',         raise: 'holding my attention more fixedly' },
+  'engine-config-attention.maxFoci':                  { lower: 'attending to one thing at a time, narrowly',  raise: 'keeping several things in view at once' },
   'engine-config-goal-manager.gritPriority':          { lower: 'refusing to give up on more of what matters to me', raise: 'letting go of goals more readily' },
   'engine-config-goal-manager.gritPatienceScale':     { lower: 'losing patience with stuck goals sooner',    raise: 'staying the course on hard goals far longer' },
   'engine-config-goal-manager.frustrationTolerance':  { lower: 'giving up faster when frustrated',            raise: 'holding steady through frustration' },
@@ -129,6 +130,7 @@ const PRIOR_DESCRIPTIONS: Record<string, { lower: string; raise: string }> = {
   'engine-config-executive.riskTolerance':            { lower: 'playing it safer',                            raise: 'taking bigger risks' },
   'engine-config-frustration.irritabilityRate':       { lower: 'letting frustration snowball into a bad mood more slowly', raise: 'getting wound up into a bad mood faster' },
   'engine-config-executive.deliberateThreshold':      { lower: 'stopping to think things through more readily',  raise: 'going with my gut more, deliberating less' },
+  'engine-config-executive.maxFacets':                { lower: 'keeping fewer things going at once, one at a time', raise: 'holding more conversations and threads at once' },
   'engine-config-reward.socialWeight':                { lower: 'caring less about social warmth',               raise: 'finding warmth and connection more rewarding' },
   'engine-config-frustration.angerReactivity':        { lower: 'letting slights go, yielding rather than bristling', raise: 'bristling harder when I feel wronged' },
   'engine-config-novelty.significanceThreshold':      { lower: 'noticing what is new and unusual more readily',  raise: 'needing more for something to strike me as new' },
@@ -143,6 +145,10 @@ const PRIOR_DESCRIPTIONS: Record<string, { lower: string; raise: string }> = {
   'engine-config-action-selector.switchCost':         { lower: 'dropping what I am doing for a new pull more easily', raise: 'seeing an action through, harder to knock off course once underway' },
   'engine-config-action-selector.riskWeight':         { lower: 'weighing the downside of what I do less — acting bolder', raise: 'weighing what could go wrong more heavily before I act' },
   'engine-config-action-selector.noveltyWeight':      { lower: 'feeling less pull toward the untried',               raise: 'drawn more strongly to do the untried and unpracticed' },
+  'engine-config-action-selector.repeatDamping':      { lower: 'following up sooner when I have had no answer',      raise: 'giving people room after I have said my piece' },
+  'engine-config-action-selector.repeatWindowTicks':  { lower: 'coming back to something sooner after I have said it', raise: 'letting what I have said stand for longer before returning to it' },
+  'engine-config-action-selector.replyWindowTicks':   { lower: 'reading a silence as an answer sooner',               raise: 'giving someone longer before I take their quiet as telling me anything' },
+  'engine-config-action-selector.socialWeight':       { lower: 'reaching for people regardless of whether they answer me', raise: 'drawn toward the people who actually answer me' },
   'engine-config-moral.eventThreshold':               { lower: 'holding myself to my principles more sharply',  raise: 'letting moral lapses weigh on me less' },
   'engine-config-frustration.decayRate':              { lower: 'staying frustrated for longer after a setback',  raise: 'shaking off frustration and bouncing back faster' },
   'engine-config-reward.socialWarmthBoost':           { lower: 'being warmed less by a kind exchange',          raise: 'being warmed more by every kind exchange' },

package/src/cognition/sense.boundary.ts

@@ -0,0 +1,176 @@
+// ─────────────────────────────────────────────────────────────
+// src/cognition/sense.boundary.ts  —  where I end and the world begins
+// ─────────────────────────────────────────────────────────────
+//
+// A body needs no rule saying "do not see your own premotor cortex." You do not
+// see it because the retina sits ON the boundary and motor planning is inside
+// it. Efference reaches you as a different signal, in a different modality,
+// already marked as yours — which this engine knows: that is what EXAFFERENCE
+// P1/P2 built.
+//
+// Will has no such boundary. Cognition and world share one `state.entities` map,
+// so the mind's own bookkeeping sits in the same place as the things it is
+// bookkeeping ABOUT, and Exteroception — the outward sense — walks the lot.
+//
+// THE COST, MEASURED. A mind booted offline for 300 quiet ticks — no host, no
+// channel, nothing outside it at all — produced 36,721 percepts, every one about
+// itself:
+//
+//     17802  removed            its own affordances being torn down each tick
+//     16950  affordance         its own affordances being rebuilt each tick
+//       546  calibration.state
+//       496  agency.intent
+//       287  agency.outcome
+//       286  agency.skill
+//       135  action.unresolved
+//       120  engine.config      its own configuration
+//        96  attention.demand
+//         3  will.identity      its own identity entity
+//
+// `maxPerceptsPerTick` is 50. The affordance field alone churns ~116 entities a
+// tick, so the sensory cap was consumed by self-noise before the world said
+// anything — and nothing downstream filters by category, so working memory, the
+// novelty detector, the attention allocator and episodic consolidation all ate
+// it. The visible symptom was elsewhere: a fresh Will proceduralized `inspect`
+// to habit 0.64 within fifteen ticks and spent five of its first eight decisions
+// examining its own affordance entities, because a percept-bound act offered
+// against phantom percepts is a real act aimed at nothing.
+//
+// WHY IT DRIFTED. The boundary was a denylist living inside the sense
+// (`internalTypes`), correct for the faculties it shipped beside in v0.1.0 and
+// silently wrong for every entity type invented after. `git log -L` on that
+// block shows two edits in five weeks — EXAFFERENCE P2 and P4 — each adding the
+// one agency type in front of its author at that moment. A hand-kept list is
+// correct for whatever you were last thinking about.
+//
+// THE ASYMMETRY THAT MAKES THIS TRACTABLE. The mind's own types are a CLOSED
+// set: it knows its own anatomy. The world's types are OPEN and unknowable —
+// that is the whole point of a container anything can rent. So enumerate the
+// self, and let everything else be world by default. Openness is preserved
+// exactly where it must be: a host introduces any entity type, any shape, and
+// the mind perceives it, with no act narrowed and no schema gated.
+//
+// Two sources, unioned:
+//   • MIND_OWN_ENTITY_TYPES — the anatomy this package ships.
+//   • each registered engine's `writes` — so a tenant that brings its OWN
+//     cognitive engine declares its own machinery beside the code that writes
+//     it, and gets this right without editing the container.
+//
+// The guard that keeps it true is behavioural, not a source scanner:
+// `sense.boundary.test.ts` boots a mind into an empty world and asserts it
+// perceives nothing. A new engine writing a new undeclared type fails it.
+// ─────────────────────────────────────────────────────────────
+
+import { CONSEQUENCE_TYPE, ENACTED_TYPE } from '#agency/consequence'
+import { AVAILABILITY_ENTITY_TYPE } from '#agency/schemas/repertoire'
+import { REVOCATION_TYPE }  from '#agency/revocation'
+import { SETTLEMENT_TYPE }  from '#agency/settlement'
+import { ACTION_RECORD_TYPE } from '#faculties/executive.engine/action.record'
+
+/**
+ * Entity types that ARE the mind — written by its own engines about its own
+ * operation. Not perceptible: a mind does not encounter its own machinery as an
+ * event in the world.
+ *
+ * Grouped by the faculty that writes them so a reader can check the list
+ * against the anatomy. Everything absent here is world.
+ */
+export const MIND_OWN_ENTITY_TYPES: ReadonlySet<string> = new Set([
+  // ── perception ────────────────────────────────────────────────
+  // Percepts about percepts are the original feedback loop this guarded.
+  'percept', 'percept.social',
+
+  // ── attention, interoception, control ─────────────────────────
+  'interoception', 'attention.focus', 'attention.demand',
+  'task.focus', 'decision.record', 'self_observation',
+  // What became of what it did. Undeclared, a mind perceives its own history as
+  // events in the world — which is how #127 was caught, recursively.
+  ACTION_RECORD_TYPE,
+
+  // ── memory ────────────────────────────────────────────────────
+  'working_memory.item', 'episodic_memory', 'spaced_repetition_record',
+  'belief', 'belief.integrate',
+
+  // ── deliberative structure ────────────────────────────────────
+  'goal', 'plan', 'plan.prior',
+
+  // ── narrative + metacognition ─────────────────────────────────
+  'narrative_chapter', 'introspection', 'self_narrative', 'cognitive_bias',
+  'calibration.state', 'executive.summary', 'executive.cache',
+
+  // ── affect + social models ────────────────────────────────────
+  // A dossier is the mind's record OF someone, not the someone. The person
+  // arrives through audition and social perception; the dossier is what the
+  // mind then holds about them, and re-perceiving it double-counts.
+  'affect.blends', 'empathic_state', 'attachment.bond',
+  'theory_of_mind', 'reputation',
+  'known-entity', 'known-entity-alias',
+
+  // ── conversation records ──────────────────────────────────────
+  // SocialPerception is the sense that owns these (it reads
+  // `conversation.received` and emits `percept.social` from it, then sweeps it).
+  // Exteroception perceiving them too was the same turn counted twice.
+  'conversation.received', 'conversation.sent',
+
+  // ── agency ────────────────────────────────────────────────────
+  // The whole pipeline: the field it synthesizes, what it committed to, what
+  // came back, what it learned, and what it merely imagined.
+  'affordance', 'agency.intent', 'agency.outcome', 'agency.skill',
+  'agency.schema', 'ideomotor.intent',
+  // What it HAS DONE — the enaction footprint satiation reads to know it has
+  // already tried this. Undeclared, it was the loudest thing in the mind's
+  // perceptual field: measured on a live Will, `New agency.enacted: agency-
+  // enacted-discord_lookup_…` sat at salience 0.5, ABOVE every real percept,
+  // and each enaction produced two of them — one when the record appeared, one
+  // when the retention sweep removed it. A mind watching its own footprints
+  // being laid down and swept away, and calling that the world.
+  ENACTED_TYPE,
+  // What it may currently do, and why not. The availability ledger is empty
+  // until a refusal lands (POLICY_REAFFERENCE P2), which is exactly why nothing
+  // caught it: a mind that has never been told no writes none of these, so the
+  // quiet path and every test that stays on it are blind to the omission. Give
+  // a Will a PolicyArbiter that refuses, and it starts perceiving its own
+  // permissions changing as events in the world.
+  AVAILABILITY_ENTITY_TYPE,
+  'action.unresolved', 'action.unaddressed',
+  CONSEQUENCE_TYPE,   // forward-model records  (EXAFFERENCE P1/P2)
+  REVOCATION_TYPE,    // commitment tombstones  (EXAFFERENCE P4)
+  SETTLEMENT_TYPE,    // verdicts System 2 reached — having thought about it
+
+  // ── substrate ─────────────────────────────────────────────────
+  // Its configuration and its identity are constitutive of it, not events in
+  // its world. It had been perceiving both.
+  'engine.config', 'will.identity', 'effector.created',
+  'dream.activity',
+])
+
+/** An engine that declares the entity types it writes about the mind itself. */
+export interface DeclaresWrites {
+  /**
+   * Entity types this engine writes as part of the mind's own operation.
+   *
+   * Declare here anything the mind should NOT re-encounter through its outward
+   * senses. Omit it for engines that write about the WORLD — a host engine
+   * maintaining rooms, documents, or sensor readings wants those perceived, and
+   * silence is the right default for them.
+   */
+  readonly writes?: readonly string[]
+}
+
+/**
+ * The full endogenous set for a given assembly: the shipped anatomy plus
+ * whatever the registered engines declare.
+ *
+ * Cheap enough to call per tick, but Exteroception memoizes on the engine list
+ * so a 50-engine union isn't rebuilt in the perceptual hot path.
+ */
+export function endogenousTypes( engines: readonly DeclaresWrites[] ): ReadonlySet<string> {
+  let extra: Set<string> | null = null
+  for( const e of engines )
+    for( const t of e.writes ?? [] )
+      if( !MIND_OWN_ENTITY_TYPES.has( t ) )
+        ( extra ??= new Set() ).add( t )
+
+  if( !extra ) return MIND_OWN_ENTITY_TYPES
+  return new Set([ ...MIND_OWN_ENTITY_TYPES, ...extra ])
+}