@mindot/will 0.9.0 → 0.10.0

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
 }

package/src/cognition/social.identity.ts

@@ -232,6 +232,29 @@ export function handlesOf( entities: ReadonlyMap<string, EntityLike>, referentId
   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.
  *

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

@@ -77,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
 
@@ -98,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
@@ -334,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 = {

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.

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'

package/src/llm/gate.ts

@@ -19,11 +19,14 @@
  *
  * Configured via env vars:
  *   WILL_LLM_CONCURRENCY    max simultaneous LLM calls (default 2)
+ *   WILL_LLM_RESPONSIVE_CONCURRENCY  slots reserved for calls someone outside
+ *                           the mind is waiting on (default 1)
  *   WILL_LLM_MAX_RETRIES    retries before giving up on a 429 (default 4)
  *   WILL_LLM_RETRY_BASE_MS  first retry wait, doubles each attempt (default 2000)
  */
 
 import { logger } from '#core/logger'
+import type { LLMCallFunction } from '#cognition/utilities/token.tracker'
 
 const MAX_CONCURRENT = parseInt( process.env.WILL_LLM_CONCURRENCY ?? '2')
 
@@ -76,6 +79,51 @@ export class LLMSemaphore {
 
 export const llmGate = new LLMSemaphore( MAX_CONCURRENT )
 
+// ── The responsive lane ───────────────────────────────────────
+
+/**
+ * A second gate, for calls someone OUTSIDE the mind is waiting on.
+ *
+ * `WILL_LLM_CONCURRENCY` ships with the comment "the minimum is 3: orbital,
+ * conversation, summary" — an intended allocation that one shared semaphore
+ * cannot enforce. Three slots means any three callers, and a mind deliberating
+ * at ~1,100 output tokens a call keeps all three warm indefinitely.
+ *
+ * Measured on a live COO over 7 hours: 29 of 45 replies began at or past the
+ * limit, and the worst spent 117 of its 131 seconds waiting for a slot rather
+ * than generating — 545 tokens at 4.2 tok/s against a provider that does ~39.
+ * From outside, that is a mind that read your message and said nothing.
+ *
+ * The distinction drawn here is NOT that conversation matters more. It is that
+ * something outside the mind is blocked on this call — a property of the call
+ * itself, which is why the predicate is named for the property and not for a
+ * list of blessed functions. Rumination can wait its turn. A person waiting for
+ * an answer cannot tell a mind that is thinking from one that is gone.
+ */
+const RESPONSIVE_CONCURRENCY = parseInt( process.env.WILL_LLM_RESPONSIVE_CONCURRENCY ?? '1')
+
+export const responsiveGate = new LLMSemaphore( RESPONSIVE_CONCURRENCY )
+
+/**
+ * The cognitive functions something outside the mind is blocked on.
+ *
+ * `outreach` is deliberately absent: the mind started that one, and nobody is
+ * sitting on the other end waiting. Only work that a waiting party is already
+ * owed belongs in the reserved lane — widen this and the reservation stops
+ * meaning anything.
+ */
+const AWAITED_OUTSIDE: ReadonlySet<LLMCallFunction> = new Set([ 'conversation' ])
+
+/** Whether someone outside the mind is blocked on a call of this function. */
+export function isAwaitedOutside( fn: LLMCallFunction | undefined ): boolean {
+  return fn !== undefined && AWAITED_OUTSIDE.has( fn )
+}
+
+/** The lane a call of this function belongs in. */
+export function gateFor( fn: LLMCallFunction | undefined ): LLMSemaphore {
+  return isAwaitedOutside( fn ) ? responsiveGate : llmGate
+}
+
 // ── Rate-limit detection ──────────────────────────────────────
 
 export function isRateLimitError( err: unknown ): boolean {