@mindot/will 0.8.0 → 0.10.0

package/src/cognition/social.identity.ts

@@ -0,0 +1,296 @@
+// ─────────────────────────────────────────────────────────────
+// src/cognition/social.identity.ts  —  what something IS, vs where to find it
+// ─────────────────────────────────────────────────────────────
+//
+// A `keid` used to be minted by the transport: `discord:${author.id}`,
+// `whatsapp:${userId}`. Identity WAS the address, and whichever channel spoke
+// first won the right to name the person. Everything downstream inherited that:
+// twenty-two files key off a keid, so the same human met on two channels was two
+// people to the reputation tracker, the theory-of-mind model, the attachment
+// bond and the PMA — with no way to notice, and no way to say so.
+//
+// It also made "how should I reach them?" unaskable. There was exactly one id
+// and it WAS a route, so the question collapsed into a roster guess about where
+// the person was last seen. Live, that sent a follow-up promised in a DM into a
+// public channel, because the roster's last-seen answer is not the same question
+// as "where did I promise this".
+//
+// So identity and route are separated here:
+//
+//   ke:<opaque>       — a referent. Never a route. The anchor everything hangs on.
+//   handle            — a way that referent has been reachable, with the
+//                       circumstances under which it worked.
+//
+// Deliberately NOT social-only. `keid` has always stood for *known entity* id and
+// the dossier has carried `kind: 'sentient' | 'thing'` since it shipped; the
+// first cut of this minted `person:` ids, which was a narrower word than the
+// system already used. A document, a repo, a dashboard, a room each have a what
+// and a where, and the where can change while the what stays put.
+//
+// This is closer to how a person actually holds it. You know someone; you know
+// places; and separately you know where you usually find whom. Three things that
+// compose, not one contact record — which is why a handle carries evidence
+// (`lastAnsweredTick`) rather than a priority number somebody configured.
+//
+// Everything here is pure and deterministic. `mintReferentId` hashes the first
+// transport id ever seen for that referent, so a recorded run and its replay mint
+// the same id (R2) — no clock, no counter, no RNG.
+// ─────────────────────────────────────────────────────────────
+
+import type { Tick } from '#core/types'
+import { fnv1a } from '#agency/consequence'
+
+/**
+ * Marks an id as a referent rather than an address.
+ *
+ * `ke` for known-entity, which is what `keid` has always stood for — the
+ * vocabulary was never social. The first cut of this minted `person:` ids and
+ * that was a narrower word than the system uses: the dossier has carried
+ * `kind: 'sentient' | 'thing'` since it shipped, and the split here is not a
+ * social idea. It is referent vs. access path, which is how anything is held —
+ * you remember the book, and separately that it is on the shelf, on the Kindle,
+ * or at the library. A document, a repo, a dashboard, a room all have several
+ * routes that come and go while the thing itself stays put.
+ */
+export const REFERENT_PREFIX = 'ke:'
+
+export const ALIAS_TYPE  = 'known-entity-alias'
+export const DOSSIER_TYPE = 'known-entity'
+
+/** True for an anchor, false for a transport address (`discord:…`, `whatsapp:…`). */
+export function isReferentId( id: string ): boolean {
+  return id.startsWith( REFERENT_PREFIX )
+}
+
+/**
+ * Mint the anchor for a referent first met at `seedKeid`.
+ *
+ * Kind is deliberately NOT in the id. It lives on the dossier, because kind is
+ * LEARNED and correctable — a handle you took for a bot turns out to be a person.
+ * Baked into the id, correcting it would mean re-identifying, and every faculty
+ * keyed off that id would lose its history of them at the moment it finally
+ * understood what they were.
+ *
+ * Deterministic by construction: the same first-seen transport id always yields
+ * the same referent id, so a replay of a recorded run mints identically and the
+ * state hashes match (R2). A counter would drift the moment two runs met people
+ * in a different order; a clock or RNG would never match at all.
+ *
+ * Opaque on purpose. The moment an id is readable as `ke:discord:123`
+ * something downstream starts parsing it back into a route, and the separation
+ * this whole module exists for quietly stops holding.
+ */
+export function mintReferentId( seedKeid: string ): string {
+  return `${ REFERENT_PREFIX }${ fnv1a( seedKeid ).toString( 36 ) }`
+}
+
+/**
+ * A way this referent has been reachable, and what happened there.
+ *
+ * `kind` is the one fact that decides whether a room is the right place for a
+ * given utterance, and it was being computed at the Discord edge (`isDM`) and
+ * discarded before the mind could see it.
+ *
+ * `lastAnsweredTick` is evidence, not configuration — it arrives free from the
+ * `social.responsiveness` signal. It is what lets the mind prefer the DM because
+ * that is where this person actually answers, rather than because a constant in
+ * the code says DMs rank higher.
+ */
+export interface Handle {
+  /** The transport address — what a channel bridge can actually deliver to. */
+  keid:             string
+  /**
+   * 'dm' — a private thread. 'room' — somewhere others are listening. Left open
+   * for a non-social referent, where the meaningful distinction is a different one.
+   */
+  kind:             'dm' | 'room' | 'unknown'
+  /** The place this handle lives in, once places are dossiers of their own. */
+  place?:           string
+  /** When the mind last SAID something here. */
+  lastUsedTick?:    Tick
+  /** When someone last answered it here — the only evidence that this route works. */
+  lastAnsweredTick?: Tick
+  /** Free-form, so a host can mark what its own vocabulary cares about. */
+  tags?:            string[]
+}
+
+interface EntityLike {
+  type:      string
+  /** A frozen state entity may hand metadata over as either shape. */
+  metadata?: ReadonlyMap<string, unknown> | Record<string, unknown>
+}
+
+/** Normalize whichever shape metadata arrived in. */
+function meta( e: EntityLike ): Record<string, unknown> {
+  const m = e.metadata
+  if( !m ) return {}
+  return m instanceof Map ? Object.fromEntries( m ) : m as Record<string, unknown>
+}
+
+function str( v: unknown ): string | undefined {
+  return typeof v === 'string' && v.length > 0 ? v : undefined
+}
+
+/**
+ * alias keid → canonical referent id.
+ *
+ * Every transport address a referent has been met at is an alias of its anchor,
+ * which is what lets the twenty-two keid consumers keep working untouched: they
+ * still see one opaque string per referent, it is simply no longer a route.
+ */
+export function readAliases( entities: ReadonlyMap<string, EntityLike> ): Map<string, string> {
+  const out = new Map<string, string>()
+  for( const [ , e ] of entities ){
+    if( e.type !== ALIAS_TYPE ) continue
+    const m = meta( e )
+    const a = str( m['aliasKeid'] )
+    const c = str( m['canonicalKeid'] )
+    if( a && c ) out.set( a, c )
+  }
+  return out
+}
+
+/** Follow an alias chain to the anchor. Cycle-safe; returns the input when unaliased. */
+export function canonicalOf( aliases: ReadonlyMap<string, string>, keid: string ): string {
+  const seen = new Set<string>()
+  let id = keid
+  while( true ){
+    const next = aliases.get( id )
+    if( !next || next === id || seen.has( next ) ) return id
+    seen.add( id )
+    id = next
+  }
+}
+
+/**
+ * Resolve anything the mind might name — an anchor, a transport address, or a
+ * learned name — to the anchor.
+ *
+ * ONE resolver, because there were two and they disagreed:
+ * `extractKnownEntities` folded aliases (so the prompt showed one person) while
+ * `resolveKnownEntity` did not (so willing a reach-out to that same person could
+ * resolve to a keid that had been merged away, and the intention evaporated).
+ * Same question, two answers, in the same tick.
+ *
+ * Name matching stays last and exact. It is the weakest evidence here — two
+ * people genuinely can share a name — and the KnownEntityTracker's recognition
+ * pass already guards fusing them.
+ */
+export function resolveKeid(
+  entities: ReadonlyMap<string, EntityLike>,
+  ref:      string,
+): string | undefined {
+  const needle = ref.trim().toLowerCase()
+  if( !needle ) return undefined
+
+  const aliases = readAliases( entities )
+
+  // An anchor or an address named directly.
+  const direct = canonicalOf( aliases, ref.trim() )
+  for( const [ , e ] of entities )
+    if( e.type === DOSSIER_TYPE && str( meta( e )['keid'] ) === direct ) return direct
+
+  // Otherwise a keid or a name, case-insensitively, in stable entity order.
+  for( const [ , e ] of entities ){
+    if( e.type !== DOSSIER_TYPE ) continue
+    const m    = meta( e )
+    const keid = str( m['keid'] )
+    if( !keid ) continue
+    if( keid.toLowerCase() === needle ) return canonicalOf( aliases, keid )
+    if( str( m['name'] )?.toLowerCase() === needle ) return canonicalOf( aliases, keid )
+  }
+
+  // A known alias whose dossier was absorbed — still a real reference to someone.
+  for( const [ alias, canon ] of aliases )
+    if( alias.toLowerCase() === needle ) return canon
+
+  return undefined
+}
+
+/** The name the mind has learned for this referent, or undefined — never a placeholder. */
+export function nameOf( entities: ReadonlyMap<string, EntityLike>, referentId: string ): string | undefined {
+  for( const [ , e ] of entities ){
+    if( e.type !== DOSSIER_TYPE || str( meta( e )['keid'] ) !== referentId ) continue
+    return str( meta( e )['name'] )?.trim() || undefined
+  }
+  return undefined
+}
+
+/** Every route the mind holds for this referent, most recently answered first. */
+export function handlesOf( entities: ReadonlyMap<string, EntityLike>, referentId: string ): Handle[] {
+  for( const [ , e ] of entities ){
+    if( e.type !== DOSSIER_TYPE || str( meta( e )['keid'] ) !== referentId ) continue
+    const raw = meta( e )['handles']
+    if( !Array.isArray( raw ) ) return []
+    return ( raw as Handle[] )
+      .filter( h => h && typeof h.keid === 'string' )
+      .sort( ( a, b ) =>
+        ( b.lastAnsweredTick ?? -1 ) - ( a.lastAnsweredTick ?? -1 )
+        || ( b.lastUsedTick ?? -1 ) - ( a.lastUsedTick ?? -1 )
+        || ( a.keid < b.keid ? -1 : a.keid > b.keid ? 1 : 0 ) )
+  }
+  return []
+}
+
+/**
+ * Every address the world knows this referent by.
+ *
+ * The inverse of the alias table: an anchor in, the transport ids that resolve to
+ * it out. An anchor is deliberately opaque and deliberately not an address —
+ * `ke:1sqlkux` is who someone IS — so anything that must actually reach them in
+ * the world has to come back through here.
+ *
+ * Two callers now, which is why it is a function and not inline: the outbox, so a
+ * message addressed to a referent can be delivered, and the agency's dispatch, so
+ * a host asked to act on a referent knows which of its own ids that is. Both are
+ * the mind reaching OUT; nothing here lets a surface name someone to the mind.
+ *
+ * Sorted, so a recorded run and its replay produce the same list (R2).
+ */
+export function addressesOf( entities: ReadonlyMap<string, EntityLike>, referentId: string ): string[] {
+  const aliases = readAliases( entities )
+  return [ ...aliases.entries() ]
+    .filter( ( [ , canonical ] ) => canonical === referentId )
+    .map( ( [ alias ] ) => alias )
+    .sort()
+}
+
+/**
+ * The route to use when the mind has expressed no preference.
+ *
+ * A DEFAULT, not a decision. Which room to speak in is the mind's call, made
+ * from the circumstances it can now see; this only answers "nothing was chosen
+ * and the words must still go somewhere" — the case where the alternative is
+ * dropping the message.
+ *
+ * Ordering is evidence-first: somewhere this person has actually answered beats
+ * somewhere they have not, and a DM beats a room only as a tiebreak. A live Will
+ * lost a promised follow-up into a public channel precisely because its fallback
+ * ranked "where I last saw them" above "where they talk to me".
+ */
+export function defaultHandle( handles: readonly Handle[] ): Handle | undefined {
+  if( handles.length === 0 ) return undefined
+  const answered = handles.filter( h => h.lastAnsweredTick !== undefined )
+  const pool     = answered.length > 0 ? answered : handles
+  return pool.find( h => h.kind === 'dm') ?? pool[0]
+}
+
+/**
+ * Fold a newly-seen address into a person's handle list.
+ *
+ * Merges rather than appends: meeting someone again in a room already known is
+ * not a new way to reach them, it is news about an existing one. Pure — returns
+ * a fresh array, so a caller writing it back through `setEntity` cannot
+ * accidentally share a mutable reference with frozen state.
+ */
+export function withHandle( handles: readonly Handle[], next: Handle ): Handle[] {
+  const out = handles.filter( h => h.keid !== next.keid )
+  const old = handles.find( h => h.keid === next.keid )
+  out.push( old ? { ...old, ...next,
+    // Never let a fresh sighting erase evidence the old record already held.
+    lastUsedTick:     next.lastUsedTick     ?? old.lastUsedTick,
+    lastAnsweredTick: next.lastAnsweredTick ?? old.lastAnsweredTick,
+    tags: [ ...new Set([ ...( old.tags ?? [] ), ...( next.tags ?? [] ) ]) ],
+  } : next )
+  return out.sort( ( a, b ) => ( a.keid < b.keid ? -1 : a.keid > b.keid ? 1 : 0 ) )
+}

package/src/cognition/utilities/token.tracker.ts

@@ -54,10 +54,15 @@ export type LLMCallAttribute =
   | 'memory'   // consolidation / embedding
   | 'guard'    // a safety reviewer
 
-/** The specific cognitive function being paid for. */
-export type LLMCallFunction =
+/** The specific cognitive process being paid for. */
+export type LLMCallProcess =
+  | 'cog'                 // background cogs' call
   | 'decision'           // the master's fused decision call
   | 'ideation'           // the deliberate path's propose pass
+
+/** The specific cognitive function being paid for. */
+export type LLMCallFunction =
+  | '-'                  // no-specific function
   | 'deliberation'       // action choice under contest
   | 'conversation'       // a live reply
   | 'outreach'           // an unprompted message
@@ -72,9 +77,24 @@ export type LLMCallFunction =
 export type TokenLedgerRecord = Record<string, unknown>
 export type TokenRecordListener = ( record: TokenLedgerRecord ) => void
 
-// ── Prompt-cache pricing (Anthropic) ──────────────────────
+// ── Prompt-cache pricing ──────────────────────────────────
 // `input_tokens` in the API usage already EXCLUDES cached tokens, so the full
-// input cost is: fresh input ×1 + cache reads ×0.1 + cache writes ×1.25.
+// input cost is: fresh input ×1 + cache reads + cache writes.
+//
+// These two ratios are ANTHROPIC's, and they are the last prices this engine
+// ships. That is the inconsistency they encode: the module refuses to bake in
+// an input or output rate on the explicit grounds that "prices belong to the
+// host — they change on a vendor's schedule, differ per account, and are ~0 for
+// a self-hosted model", and then hardcodes two more prices because they happen
+// to be expressible as a ratio.
+//
+// They are wrong the moment a host is not on Anthropic. Z.ai charges $0.26/M
+// for cached input against $1.40/M fresh — a ratio of 0.186, not 0.10 — so a
+// COO's cache line came out 46% under. Its cache WRITES are free outright,
+// which 1.25 cannot express at all.
+//
+// So they are now a FALLBACK, used only when the host's `ModelPrice` does not
+// state the real rate. A host that says nothing gets exactly the old numbers.
 const CACHE_READ_MULT  = 0.1
 const CACHE_WRITE_MULT = 1.25
 
@@ -93,7 +113,21 @@ function normalizeModelKey( model: string ): string {
   return m.replace( /[-@]\d{6,8}$/, '')         // drop trailing -YYYYMMDD date stamp
 }
 /** USD per 1M tokens for one model. */
-export interface ModelPrice { input: number; output: number }
+export interface ModelPrice {
+  input:  number
+  output: number
+  /**
+   * USD per 1M cache-READ tokens. Absent ⇒ `input × 0.1` (Anthropic's ratio).
+   *
+   * State it whenever the host is not Anthropic. `0` is meaningful and honoured
+   * — some providers do not charge for cache reads at all — so this is read as
+   * "absent", not "falsy".
+   */
+  cachedInput?: number
+  /** USD per 1M cache-WRITE tokens. Absent ⇒ `input × 1.25`. `0` is honoured:
+   *  Z.ai's cache storage is free, which no multiple of input can express. */
+  cacheWrite?:  number
+}
 
 /**
  * Host-supplied prices, keyed by model id. Matching is exact first, then
@@ -176,9 +210,25 @@ export interface TokenUsage {
    */
   priced: boolean
 
+  /**
+   * How much this call demanded, 0..1 — the cognitive measure the router saw.
+   *
+   * Recorded so routing can be ANSWERED rather than argued. Every call computes
+   * this, routes on it, and until now threw it away — which left questions like
+   * "is deliberation being rated by the tick's mood rather than the stakes of
+   * its own choice?" with no dataset at all.
+   *
+   * Absent means UNMEASURED, never zero. It must stay nullable all the way to
+   * storage: a call that never reported demand and a call that reported 0.0 are
+   * different facts, and collapsing them would put a floor of invented
+   * confidence under exactly the analysis this exists to enable.
+   */
+  demand?: number
+
   // ── 5-axis cost attribution ──────────────────────────────
   category:  LLMCallCategory
   attribute: LLMCallAttribute
+  process:  LLMCallProcess
   function:  LLMCallFunction
   /** Optional specific id or namespace: facet id, entity id, model name. */
   scope?: string
@@ -197,9 +247,17 @@ export interface TokenUsage {
 /** What callers pass to {@link TokenTracker.recordUsage} — cost and label are derived. */
 export type RecordUsageInput = Omit<TokenUsage, 'estimatedCostUsd' | 'label' | 'priced'> & { label?: string }
 
-/** Compose a stable, readable label from the attribution axes. */
-function composeLabel( m: { category: LLMCallCategory; attribute: LLMCallAttribute; function: LLMCallFunction; scope?: string } ): string {
-  const base = `${m.category}/${m.attribute}/${m.function}`
+/**
+ * Compose a stable, readable label from the attribution axes.
+ *
+ * `function` carries '-' when the call has no specific one (the master's own
+ * decision/ideation passes), so it is dropped rather than rendered — a label of
+ * `executive/master/-` names nothing. Process always shows: it is what
+ * distinguishes the propose pass from the decision it feeds.
+ */
+function composeLabel( m: { category: LLMCallCategory; attribute: LLMCallAttribute; process: LLMCallProcess; function: LLMCallFunction; scope?: string } ): string {
+  const base = [ m.category, m.attribute, m.process, m.function === '-' ? '' : m.function ]
+    .filter( Boolean ).join('/')
   return m.scope ? `${base}#${m.scope}` : base
 }
 
@@ -245,6 +303,12 @@ export class TokenTracker implements SimulationEngine {
   private _categoryTokens = new Map<string, { prompt: number; completion: number }>()
   private _functionCosts  = new Map<string, number>()
   private _functionTokens = new Map<string, { prompt: number; completion: number }>()
+  // Split out of the function axis: `decision` vs `ideation` is which PROCESS ran,
+  // not which function it served. Without its own bucket the deliberate path's
+  // propose pass became invisible in cost reporting — every master call landing in
+  // the '-' function bucket regardless of whether it deliberated.
+  private _processCosts   = new Map<string, number>()
+  private _processTokens  = new Map<string, { prompt: number; completion: number }>()
   // Per-provider spend. The axis a host actually reconciles against invoices —
   // "which vendor did we pay?" is not answerable from the model id once routing
   // can reach one model through several of them.
@@ -299,8 +363,10 @@ export class TokenTracker implements SimulationEngine {
     const costUsd = pricing
       ? ( usage.promptTokens     / 1_000_000 ) * pricing.input  +
         ( usage.completionTokens / 1_000_000 ) * pricing.output +
-        ( cacheRead              / 1_000_000 ) * pricing.input * CACHE_READ_MULT  +
-        ( cacheWrite             / 1_000_000 ) * pricing.input * CACHE_WRITE_MULT
+        // `?? fallback` rather than `||`: a stated 0 is a real rate (free cache
+        // reads / free storage) and must not silently become the Anthropic ratio.
+        ( cacheRead              / 1_000_000 ) * ( pricing.cachedInput ?? pricing.input * CACHE_READ_MULT  ) +
+        ( cacheWrite             / 1_000_000 ) * ( pricing.cacheWrite  ?? pricing.input * CACHE_WRITE_MULT )
       : 0
 
     const full: TokenUsage = {
@@ -320,6 +386,7 @@ export class TokenTracker implements SimulationEngine {
     // Per-axis breakdowns — the repartition surface (category × function).
     this._accumulate( this._categoryCosts, this._categoryTokens, full.category, full )
     this._accumulate( this._functionCosts, this._functionTokens, full.function, full )
+    this._accumulate( this._processCosts,  this._processTokens,  full.process,  full )
     // Unattributed rather than guessed: a caller that did not say which
     // provider served the call must not be silently folded into the default.
     this._accumulate( this._providerCosts, this._providerTokens, full.provider ?? 'unattributed', full )
@@ -350,6 +417,7 @@ export class TokenTracker implements SimulationEngine {
       provider:      full.provider,
       category:      full.category,
       attribute:     full.attribute,
+      process:       full.process,
       function:      full.function,
       scope:         full.scope,
       label:         full.label,
@@ -363,6 +431,9 @@ export class TokenTracker implements SimulationEngine {
       // priced this model, NOT because the call was free — a consumer summing
       // spend must not fold unpriced calls in as zero.
       priced:        full.priced,
+      // Undefined stays undefined — see TokenUsage.demand. A consumer that
+      // coerces this to 0 has silently invented a measurement.
+      demand:        full.demand,
       latencyMs:     full.latencyMs,
     }
 
@@ -461,6 +532,7 @@ export class TokenTracker implements SimulationEngine {
           totalCost: this._totalCost,
           categoryBreakdown: Object.fromEntries( this._categoryCosts ),
           functionBreakdown: Object.fromEntries( this._functionCosts ),
+          processBreakdown:  Object.fromEntries( this._processCosts ),
         },
       })
     }
@@ -502,6 +574,16 @@ export class TokenTracker implements SimulationEngine {
     return this._functionTokens
   }
 
+  /** Cost broken down by process ('decision' | 'ideation' | 'cog'). */
+  get processBreakdown(): ReadonlyMap<string, number> {
+    return this._processCosts
+  }
+
+  /** Token counts (prompt + completion) broken down by process. */
+  get processTokenBreakdown(): ReadonlyMap<string, { prompt: number; completion: number }> {
+    return this._processTokens
+  }
+
   /**
    * Cost broken down by provider ('anthropic' | 'glm' | 'moonshot' | …), plus
    * an `unattributed` bucket for usage recorded without one.
@@ -554,6 +636,8 @@ export class TokenTracker implements SimulationEngine {
     this._categoryTokens.clear()
     this._functionCosts.clear()
     this._functionTokens.clear()
+    this._processCosts.clear()
+    this._processTokens.clear()
     this._providerCosts.clear()
     this._providerTokens.clear()
     this._tickCosts = []

package/src/core/orchestrator.ts

@@ -35,6 +35,19 @@ export interface EngineResult {
 export interface SimulationEngine {
   readonly name: string
 
+  /**
+   * Entity types this engine writes as part of the MIND'S OWN operation — its
+   * bookkeeping, not the world's furniture. Declared here, they fall inside the
+   * sense boundary and the outward senses stop re-perceiving them (see
+   * `#cognition/sense.boundary`).
+   *
+   * Optional and silent by default, because the default is the right one for a
+   * host engine: an engine that maintains rooms, documents or sensor readings
+   * wants those perceived. Declare only what the mind should not encounter as an
+   * event in its world.
+   */
+  readonly writes?: readonly string[]
+
   /**
    * Called once per tick with a frozen read-only snapshot.
    * Engines must NOT mutate state directly — return commands instead.
@@ -62,6 +75,13 @@ export interface SimulationEngine {
 }
 
 
+/**
+ * Fraction of one tick interval a single non-async engine may consume before the
+ * orchestrator says so. Half a tick is generous for work that is meant to be
+ * in-memory, and low enough to fire long before tick-denominated deadlines drift.
+ */
+const SLOW_ENGINE_FRACTION = 0.5
+
 // ── Middleware ───────────────────────────────────────────────
 
 export type TickMiddleware = (
@@ -384,6 +404,35 @@ export class DefaultOrchestrator implements Orchestrator {
    * calls _executeTick() which handles pause/stop checks internally.
    * The orchestrator is the sole driver of ticks.
    */
+  /**
+   * A plain SimulationEngine's `react()` is implicitly "finish inside the tick" —
+   * only an AsyncEngine is allowed to span ticks, and it does so by LAUNCHING work
+   * and landing it later (see async.engine.ts: "react() never awaits LLM calls").
+   * Nothing enforces that on everyone else, and the failure is silent and severe:
+   * every agency deadline is denominated in TICKS, so an engine that awaits network
+   * I/O does not merely run slowly, it rescales time for the whole mind.
+   *
+   * Measured: one rate-limited embedding call awaited inside EpisodicConsolidator
+   * made two consecutive ticks take 64.9s and 63.5s. `AWAIT_TIMEOUT` — 15 ticks,
+   * normally ~15s — silently became 15 minutes, so a communicate intent sat
+   * 'awaiting' forever and the serial selector never chose anything again. 45
+   * executive decisions produced one intent and zero delivered messages, with no
+   * error anywhere. This turns that into a line in the log the first time it happens.
+   */
+  private _warnIfSlow( engine: SimulationEngine, elapsedMs: number ): void {
+    // AsyncEngines are exempt by design — spanning ticks is their contract.
+    if( ( engine as { hasPendingWork?: unknown } ).hasPendingWork !== undefined ) return
+
+    const budget = ( this._config.tickIntervalMs ?? 1000 ) * SLOW_ENGINE_FRACTION
+    if( elapsedMs <= budget ) return
+
+    logger.warn(
+      `[Orchestrator] Engine "${ engine.name }" held the tick for ${ Math.round( elapsedMs ) }ms ` +
+      `at tick ${ this._currentTick } (budget ${ Math.round( budget ) }ms). A non-async engine must not ` +
+      `await network I/O — tick-denominated deadlines elsewhere are being stretched by this.`
+    )
+  }
+
   private _runLoop( context: SimulationContext ): void {
     if( this._tickTimer ) return
 
@@ -478,6 +527,7 @@ export class DefaultOrchestrator implements Orchestrator {
     const allResults: EngineResult[] = []
 
     const runEngine = async ( engine: SimulationEngine ): Promise<void> => {
+      const startedAt = wallClock()
       try {
         const result = await engine.react?.( this._clock.delta, this._currentTick, snapshot, engineContext )
         if( result ) allResults.push( result )
@@ -494,6 +544,7 @@ export class DefaultOrchestrator implements Orchestrator {
           )
         }
       }
+      finally { this._warnIfSlow( engine, wallClock() - startedAt ) }
     }
 
     for( const engine of this._enginesTick() )

package/src/index.ts

@@ -87,8 +87,8 @@ export {
 } from '#cognition/memory/index'
 
 // Profile registry — built-in profiles are auto-registered when this package is imported
-// (mind.ts imports '#profiles/built-in' as a side effect).
-export { resolveProfile, listProfiles, type WorldProfile } from '#profiles/index'
+// (mind.ts imports '#stem/profiles/built-in' as a side effect).
+export { resolveProfile, listProfiles, type WorldProfile } from '#stem/profiles/index'
 
 // PMA (Personal Mind Archive) snapshot types
 export type {
@@ -109,14 +109,20 @@ export type {
   PMAProbe,
 } from '#pma/eval'
 
-// Sensory input types — used by callers of WillManager.ingestText()
+// Sensory input types — used by callers of WillManager.senseText()
 export type { TextMessage, VoiceChunk, SensoryInput } from '#senses/index'
+// Provenance — whose doing a signal was. Required on every signal, because
+// nothing inside the mind can tell its own echo from a stranger saying the same
+// words: only the host knows, so the host says. `asProvenance` is for untyped
+// ingress only (a tool call, an HTTP body) — the one place a default exists.
+export type { SignalProvenance, SensorySignal, Transduced } from '#senses/provenance'
+export { asProvenance } from '#senses/provenance'
 
 // ── SDK facade — the ergonomic embedding API (recommended entry point) ──
 // `Will.create()` wraps WillStem in the shape a developer expects: on('message'),
 // effector(name, handler), say(), state(), hibernate()/wake(). Drop to `.stem`
 // for the full contract. See src/sdk/will.ts + examples/effectors.ts.
-export { Will } from '#sdk/will'
+export { Will } from '#surface/sdk/will'
 export type {
   CreateWillOptions,
   Stimulus,
@@ -128,5 +134,33 @@ export type {
   EffectorResult,
   EffectorSpec,
   EffectorEntry,
-} from '#sdk/will'
+} from '#surface/sdk/will'
 export type { SchemaPrecondition, EffectorDeclaration } from '#agency/types'
+
+// ── Policy — the PDP/PEP boundary (POLICY_REAFFERENCE) ──────────────────
+// A host installs a PolicyArbiter via `WillStem.setArbiter()` / `Will.setArbiter()`
+// to gate host-owned effector invocations before they reach the world: allow,
+// deny (with `finality` — class/parameter/context, see arbiter.ts), or escalate
+// (hold the intent, voice the ask, resolve via `resolveEscalation()`). No arbiter
+// installed ⇒ byte-identical to a Will with no policy layer. `RuleTableArbiter`
+// is the local reference PDP — pure and declarative, sufficient for static
+// schema/target/parameter rules; a host needing live world state (session/DB
+// lookups) implements `PolicyArbiter` directly instead.
+export {
+  NULL_ARBITER,
+  isNullArbiter,
+  finalityOf,
+  asFinality,
+  type PolicyArbiter,
+  type PolicyDecision,
+  type DenialFinality,
+  type PolicyCounterfactual,
+  type Verdict,
+  type PolicyInvocation,
+} from '#stem/policy/arbiter'
+export {
+  RuleTableArbiter,
+  type PolicyRule,
+  type ParamConstraint,
+  type RuleTableOptions,
+} from '#stem/policy/rule.table'