@ax-llm/ax 23.0.0 → 23.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ax-llm/ax",
-  "version": "23.0.0",
+  "version": "23.0.2",
   "type": "module",
   "description": "The best library to work with LLMs",
   "repository": {
@@ -24,9 +24,6 @@
       "optional": true
     }
   },
-  "tsd": {
-    "directory": "./"
-  },
   "files": [
     "**/*"
   ],

package/skills/ax-agent-context.md

@@ -1,7 +1,7 @@
 ---
 name: ax-agent-context
 description: This skill helps an LLM pick the right AxAgent context tool for a job - contextMap for recurring corpora, contextPolicy presets for within-run trajectory compaction, agent.optimize for offline GEPA instruction/demo tuning, agent.playbook for an evolving context playbook (offline evolve + online update), and recall/memories + skills for per-turn retrieval. Use when the user asks "which context feature should I use", confuses contextMap with contextPolicy or memory, or wants a decision guide for long-context agents. For contextPolicy/contextMap codegen use ax-agent-rlm; for recall/skills use ax-agent-memory-skills; for agent.optimize or agent.playbook use ax-agent-optimize.
-version: "23.0.0"
+version: "23.0.2"
 ---
 
 # AxAgent Context Selection (@ax-llm/ax)

package/skills/ax-agent-memory-skills.md

@@ -1,7 +1,7 @@
 ---
 name: ax-agent-memory-skills
 description: This skill helps an LLM generate correct AxAgent memory retrieval, context-map, and dynamic skill-loading code using @ax-llm/ax. Use when the user asks about contextMap, AxAgentContextMap, onMemoriesSearch, memoriesCatalog, recall(...), inputs.memories, onLoadedMemories, onUsedMemories, onSkillsSearch, skillsCatalog, AxAgentCatalogSkill, discover({ skills }), onLoadedSkills, onUsedSkills, preloaded skills, preloading memories at forward time, relevanceRanking hints, loaded memory/skill IDs, or carrying memories across forward() calls.
-version: "23.0.0"
+version: "23.0.2"
 ---
 
 # AxAgent Memory And Skills Rules (@ax-llm/ax)

package/skills/ax-agent-observability.md

@@ -1,7 +1,7 @@
 ---
 name: ax-agent-observability
 description: This skill helps an LLM generate correct AxAgent observability code using @ax-llm/ax. Use when the user asks about actorTurnCallback, onContextEvent, agentStatusCallback, onFunctionCall, reportSuccess, reportFailure, getChatLog(), getUsage(), resetUsage(), debug traces, progress updates, or telemetry for AxAgent runs.
-version: "23.0.0"
+version: "23.0.2"
 ---
 
 # AxAgent Observability Rules (@ax-llm/ax)

package/skills/ax-agent-optimize.md

@@ -1,7 +1,7 @@
 ---
 name: ax-agent-optimize
 description: This skill helps an LLM generate correct AxAgent tuning and evaluation code using @ax-llm/ax. Use when the user asks about agent.optimize(...), judgeOptions, eval datasets, optimization targets, saved optimizedProgram artifacts, or agent optimization guidance.
-version: "23.0.0"
+version: "23.0.2"
 ---
 
 # AxAgent Optimize Codegen Rules (@ax-llm/ax)
@@ -45,6 +45,7 @@ Pick the optimization shape from the user's need:
 - "Make the whole agent better" -> use the default actor target first; only broaden target selection when the user clearly wants that extra scope.
 - "Tune child-agent delegation" -> use tasks that exercise when to call the child agent, when to call normal tools, and when to answer directly.
 - "Compare before and after" -> include a held-out task plus artifact save/load and replay.
+- "Repair the tasks it keeps failing, without eroding what works" -> this is playbook territory, not GEPA: use the agent-bound playbook evolve method (in TypeScript, `agent.playbook().evolve(dataset)`) to mine failures into verified playbook bullets under a held-out gate. Python, Java, C++, Go, and Rust expose the same loop with native method casing; see `ax-playbook`. `optimize(...)` maximizes a metric by tuning instructions and demos; playbook evolution grows durable rules.
 
 Choose task design carefully:
 
@@ -320,6 +321,13 @@ Decision rules:
 
 ## Eval Semantics
 
+- MCP/UCP evaluation defaults to replay or sandbox mode. A live client is rejected unless `mcpEvaluation: 'live'` is explicit.
+- Use `ax-mcp` for recording/replay transport setup and MCP side-effect policy.
+- Use `AxMCPRecordingTransport` to capture a real session once and `AxMCPReplayTransport` for deterministic optimization/evaluation.
+- Replay normalized MCP notifications and task transitions through
+  `AxEventRuntime`; do not leave a live subscription active in a default
+  optimization run.
+- Action traces include qualified MCP/UCP operations, approvals, task transitions, raw protocol errors, and business outcomes for judges and deterministic metrics.
 - `agent.optimize(...)` runs each evaluation rollout from a clean continuation state.
 - Saved runtime state from `getState()` and `setState(...)` is not used during eval rollouts.
 - During optimize/eval, `askClarification(...)` is treated as a scored evaluation outcome instead of going through the responder.

package/skills/ax-agent-rlm.md

@@ -1,7 +1,7 @@
 ---
 name: ax-agent-rlm
 description: This skill helps an LLM generate correct AxAgent RLM/runtime code using @ax-llm/ax. Use when the user asks about RLM code execution, AxJSRuntime, contextFields, contextPolicy, liveRuntimeState, promptLevel, stage prompt controls, executorModelPolicy, maxRuntimeChars, agent.test(...), llmQuery(...), recursionOptions, or long-running agent runtime behavior.
-version: "23.0.0"
+version: "23.0.2"
 ---
 
 # AxAgent RLM Runtime Rules (@ax-llm/ax)

package/skills/ax-agent.md

@@ -1,7 +1,7 @@
 ---
 name: ax-agent
-description: This skill helps an LLM generate correct core AxAgent code using @ax-llm/ax. Use when the user asks about agent(), child agents, namespaced functions, discovery mode, clarification, bubbleErrors, host-side final/clarification protocol, or ordinary agent runtime behavior. For RLM/code-runtime work use ax-agent-rlm; for callbacks and telemetry use ax-agent-observability; for recall/memory/skill loading use ax-agent-memory-skills; for agent.optimize(...) use ax-agent-optimize.
-version: "23.0.0"
+description: This skill helps an LLM generate correct core AxAgent code using @ax-llm/ax. Use when the user asks about agent(), child agents, namespaced functions, discovery mode, clarification, bubbleErrors, host-side final/clarification protocol, or ordinary agent runtime behavior. For MCP clients, native runtime modules, subscriptions, tasks, or authentication use ax-mcp alongside this skill. For RLM/code-runtime work use ax-agent-rlm; for callbacks and telemetry use ax-agent-observability; for recall/memory/skill loading use ax-agent-memory-skills; for agent.optimize(...) use ax-agent-optimize.
+version: "23.0.2"
 ---
 
 # AxAgent Codegen Rules (@ax-llm/ax)
@@ -15,6 +15,8 @@ Your job is to choose the smallest correct `AxAgent` shape for the user's needs:
 - If the user wants callbacks, logs, tracing, or usage data, use the `ax-agent-observability` skill.
 - If the user wants dynamic memory retrieval or skill-guide loading, use the `ax-agent-memory-skills` skill.
 - If the user wants tuning or eval with `agent.optimize(...)`, use the `ax-agent-optimize` skill.
+- If the user wants MCP transports, authentication, catalogs, subscriptions,
+  tasks, Apps, or event-driven wake/resume, use the `ax-mcp` skill.
 
 ## Use These Defaults
 
@@ -237,24 +239,22 @@ const parent = agent('query:string -> answer:string', {
 });
 ```
 
-MCP clients and other `toFunction()` providers can be placed directly inside a group after initialization:
+Attach MCP/UCP clients through the native execution context. Ax initializes them once, exposes `mcp.<namespace>` / `ucp.<namespace>` runtime modules, and propagates them through actor stages, `llmQuery`, RLM, and child agents:
 
-```typescript
-await mcpClient.init();
+Use `ax-mcp` for constructing those clients, transport/authentication policy,
+server-initiated handlers, resource subscriptions, task continuations, and
+recording/replay. Keep this section focused on Agent attachment and discovery.
 
+```typescript
 const parent = agent('query:string -> answer:string', {
-  functions: [
-    {
-      namespace: 'memory',
-      title: 'Memory MCP',
-      description: 'Memory server tools',
-      selectionCriteria: 'Use for persistent memory lookup and updates.',
-      functions: [mcpClient],
-    },
-  ],
+  mcp: [memoryClient, searchClient],
+  mcpInheritance: 'all',
   functionDiscovery: true,
   contextFields: [],
 });
+
+// A child can restrict inheritance to selected namespaces or `none`.
+await parent.forward(llm, { query }, { mcpInheritance: ['memory'] });
 ```
 
 Rules:
@@ -265,8 +265,23 @@ Rules:
 - `relevanceRanking` (default ON — set `false` to opt out): a deterministic local ranker that injects an advisory `### Likely Relevant` shortlist into the executor turn (dynamic, non-cached field — the cached prompt stays byte-stable). Enabled by default after its A/B gate passed on both small and frontier models and implemented in the generated language ports through AxIR Core. Details in `ax-agent-memory-skills`; outcomes observable via the `relevance_ranking` context event (`ax-agent-observability`).
 - Add `alwaysInclude: true` to a group when discovery mode is on but the actor should always see that group's full callable definitions inline in the prompt.
 - Keep `functions: [...]` either flat or grouped. Runtime validation rejects mixed plain function entries and group objects.
-- In flat mode, pass `fn(...)` tools, child agents, and `toFunction()` providers directly.
-- In grouped mode, put callable entries and `toFunction()` providers inside groups. To expose a child agent inside a group, use `childAgent.getFunction()`.
+- In flat mode, pass `fn(...)` tools and child agents directly.
+- In grouped mode, put callable entries inside groups. To expose a child agent inside a group, use `childAgent.getFunction()`.
+- Do not place MCP clients in `functions`; use `mcp` so tasks, resources, subscriptions, elicitation, sampling, authorization, cancellation, and protocol metadata remain available.
+- To wake an Agent from a resource subscription, use `AxMCPEventSource` and an
+  explicit authenticated `wake` route. MCP sessions are not tenant identity;
+  supply identity from the application's authenticated token mapping.
+- An endpoint does not imply a resource URI. Inspect `client.inspectCatalog()`
+  and choose an explicit `resourceSubscriptions` policy. Omission means none;
+  `'all'` selects all discovered concrete resources; selectors can use names,
+  descriptions, MIME types, URIs, and annotations. Templates are not expanded.
+- Map the event with a signature-aware `.wakeInput(...)` plan, or reuse an
+  `eventInput()` plan. Callback `mapInput` is still signature-validated and
+  cannot inject undeclared Agent fields. Use multiple matching routes to wake
+  multiple Agents with independent state, authorization, retries, and runs.
+- To wake from a UCP lifecycle webhook, use `AxUCPWebhookEventSource` and map
+  verified profile/account state to Ax tenant identity after request
+  verification. Never derive tenant identity from the order payload.
 
 ## Host-Side Completion From Functions
 
@@ -529,6 +544,8 @@ agent(signature, {
   functions,
   functionDiscovery,
   autoUpgrade,
+  playbook,
+  citations,
   ...agentOptions,
 });
 ```
@@ -576,6 +593,34 @@ Rules:
 - Values in required non-string fields (arrays, objects, numbers, media) are never auto-promoted — declare those in `contextFields` explicitly when they can be large.
 - Each promotion emits a `field_auto_promoted` context event (`onContextEvent`) with the field name, original size, and preview size; use it to observe what was kept out of the prompt.
 
+### Learning And Citations
+
+These construction-time options are portable across TypeScript and the generated
+Python, Java, C++, Go, and Rust packages (both default off):
+
+- `playbook`: attach an ACE playbook at construction. `learn` is on by default — after each run that produced failure signals (error turns, dead-ends, failing tool calls) one bounded update curates durable avoidance rules that ride the next run's actor prompt; zero LLM cost on clean runs. TypeScript seeds a prior session with `playbook: { playbook: snapshot }`; generated packages accept their full `{ playbook, artifact }` snapshot under `seed`. Persist via `onUpdate`, read the live handle with `getPlaybook()` (or the language-shaped equivalent), gate with `learn: { minSignals, dedupe }`, or disable with `learn: false`. To grow the same playbook from a task set with a held-out verify gate, use the agent-bound playbook evolve method — see `ax-playbook`.
+- `citations`: add an optional `evidenceCitations: string[]` responder output listing which evidence entries (top-level keys of the curated evidence, plus memory ids) the answer relied on. Validated in-pipeline — the model cannot cite evidence it never collected (existence, not entailment). Pass `true`, or `{ field?, surface?: 'output' | 'hidden', includeMemoryIds?, onCitations? }`.
+
+Stage guidance is portable too. `setInstruction` replaces the stage-owned actor
+instruction and `addActorInstruction` appends an additive rule. Both are real
+optimization components; rebuilding the split programs no longer discards them.
+Generated packages use their normal casing conventions (`set_instruction` in
+Python/C++/Rust and `SetInstruction` in Go).
+
+The generated-language observer and evolve spellings are:
+
+| Language | Citations observer | Verified agent playbook evolve |
+|---|---|---|
+| Python | `citations.onCitations` | `agent.playbook().evolve(dataset, options)` |
+| Java | `citations.onCitations` (`Consumer`) | `agent.playbook(null).evolve(dataset, options)` |
+| C++ | `set_citations_observer(...)` | `agent.get_playbook()->evolve(dataset, options)` |
+| Go | `citations.onCitations` (`func([]Value)`) | `agent.GetPlaybook().EvolveAgent(ctx, dataset, options)` |
+| Rust | `set_citations_observer(...)` | `playbook.evolve_agent(&mut agent, client, dataset, options)` |
+
+C++ and Rust use `set_playbook_observer(...)` for construction-time learning
+updates; Python, Java, and Go accept the `playbook.onUpdate` callback in their
+native configuration map.
+
 ## Public Surface
 
 Use these method groups as the compact AxAgent surface map:
@@ -585,6 +630,7 @@ Use these method groups as the compact AxAgent surface map:
 - State and control: `getState()`, `setState(state?)`, `getContextMap()`, `setContextMap(map?)`, `stop()`, `getSignature()`, `setSignature(signature)`, `getFunction()`, `getId()`, and `setId(id)`. Context-map evolve policy lives on `AxAgentContextMap` (`infiniteEvolve`, `evolveSteps`, `maxChars`), not on the agent config. See [`src/examples/rlm-context-map-live.ts`](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/rlm-context-map-live.ts) for provider-backed persistence and finite-evolve usage.
 - Observability: `getChatLog()`, `getUsage()`, `getStagedUsage()`, `resetUsage()`, and `getTraces()`; use `ax-agent-observability` for details.
 - Demos and tuning: `setDemos(...)`, `namedPrograms()`, `namedProgramInstances()`, `optimize(...)`, `applyOptimization(...)`, `getOptimizableComponents()`, and `applyOptimizedComponents(...)`; use `ax-agent-optimize` for tuning details.
+- Learning: `playbook()` returns an agent-aware playbook handle (`update(...)`, `render()`, state/load methods, and verified dataset evolution); `getPlaybook()` reads the current handle. Generated packages expose the same behavior with language-shaped method names. Use `ax-playbook` for details.
 
 Rules:
 
@@ -615,9 +661,24 @@ Fetch these for full working code:
 - [Customer Support](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/customer-support.ts) - classification agent
 - [Abort Patterns](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/abort-patterns.ts) - abort handling
 - [Smart Defaults Agent](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/typescript/long-agents/smart-defaults-agent.ts) - auto-upgrade context promotion, relevance hints, and runtime tools
+- [Portable Playbook Evolve](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/python/optimization/agent-playbook-evolve.py) - Python construction-time learning, validated citations, stage guidance, and verified task-set evolution (parallel Java/C++/Go/Rust examples live beside it)
 
 RLM examples are listed in `ax-agent-rlm`. Memory/skills examples are listed in `ax-agent-memory-skills`.
 
+## Event-Driven Agents
+
+`AxEventRuntime` can wake or resume an Agent while preserving its logical
+state. Use `createProgram(instance)` for multi-tenant Agents; one mutable Agent
+object must not serve multiple instance keys concurrently. Clarification and
+remote task completion are represented as owned continuations, not synthetic
+user turns.
+
+Declare the Agent signature on
+`eventTarget('id').createProgram(signature, factory)` and map event values with
+`eventPath`. The runtime verifies every created Agent against that signature
+before invoking it. Fan-out uses multiple matching routes so each Agent keeps
+its own authorization, instance serialization, retry policy, and run record.
+
 ## Do Not Generate
 
 - Do not use `new AxAgent(...)` for new code unless explicitly required.

package/skills/ax-ai.md

@@ -1,7 +1,7 @@
 ---
 name: ax-ai
 description: This skill helps an LLM generate correct AI provider setup and configuration code using @ax-llm/ax. Use when the user asks about ai(), providers, models, presets, embeddings, batch audio with ai.transcribe() or ai.speak(), extended thinking, context caching, or mentions OpenAI/Anthropic/Google/Azure/DeepSeek/Mistral/Cohere/Reka/Grok with @ax-llm/ax.
-version: "23.0.0"
+version: "23.0.2"
 ---
 
 # AI Provider Codegen Rules (@ax-llm/ax)
@@ -213,9 +213,10 @@ console.log(res.results[0]?.content);
 
 ### Anthropic Model-Specific Behavior
 
-- Opus 4.8 and 4.7: adaptive thinking, effort levels including `'xhigh'`,
-  no manual `budget_tokens`, and no `temperature` / `topP` / `topK`.
-- Opus 4.6: adaptive thinking, effort levels
+- Opus 4.8, 4.7, and 4.6 plus Sonnet 5: adaptive thinking, no manual
+  `budget_tokens`, and no `temperature` / `topP` / `topK`. When thoughts are
+  requested, Ax asks Anthropic for summarized display; when they are hidden,
+  Ax explicitly requests `display: 'omitted'`.
 - Opus 4.5: budget_tokens + effort levels (capped at `'high'`)
 - Other thinking models: budget tokens only
 
@@ -342,12 +343,22 @@ const transport = axCreateMCPStdioTransport({
 const client = new AxMCPClient(transport);
 ```
 
+For server notifications, call `client.startListening({ signal, onError })` or
+attach the client through `AxMCPEventSource`. The event adapter is preferred
+for autonomous work because protocol callbacks only enqueue; explicit routes
+decide whether to observe, invalidate, resume, or wake.
+
+For signed UCP lifecycle requests, mount
+`AxUCPWebhookEventSource.ingest(request)` in application-owned HTTP hosting.
+Signature, profile, digest, freshness, and replay verification completes before
+the event runtime sees the request.
+
 ## Critical Rules
 
 - Use `ai()` factory for all providers.
 - Provider names: `'openai'`, `'openai-responses'`, `'anthropic'`, `'google-gemini'`, `'azure-openai'`, `'mistral'`, `'cohere'`, `'deepseek'`, `'reka'`, `'grok'`
-- Thinking constraints on Anthropic: Opus 4.8/4.7 omit `temperature`, `topP`,
-  and `topK`; older thinking models ignore `temperature` and `topK`, with
+- Thinking constraints on Anthropic: every adaptive-thinking model omits
+  `temperature`, `topP`, and `topK`; older thinking models ignore `temperature` and `topK`, with
   `topP` only sent if >= 0.95.
 - Bedrock uses `new AxAIBedrock()`, not `ai()`.
 - Vercel AI SDK uses `AxAIProvider` wrapper.

package/skills/ax-audio.md

@@ -1,7 +1,7 @@
 ---
 name: ax-audio
 description: This skill helps an LLM generate correct audio code with @ax-llm/ax. Use when the user asks about ai.transcribe(), ai.speak(), signature audio inputs or outputs, agent audio behavior, .chat() conversational audio, OpenAI audio or realtime models, Gemini Live native audio, Grok Voice Agent models, voices, formats, transcripts, or how audio fits with structured outputs.
-version: "23.0.0"
+version: "23.0.2"
 ---
 
 # Audio I/O Codegen Rules (@ax-llm/ax)

package/skills/ax-event-runtime.md

@@ -0,0 +1,145 @@
+---
+name: ax-event-runtime
+description: Use AxEventRuntime to ingest events, explicitly wake or resume AxGen, AxAgent, and AxFlow, persist state and results, and route outputs safely.
+---
+
+# Ax Event Runtime
+
+Use this skill when an Ax program should react to notifications, webhooks,
+timers, queues, task completion, or application events.
+
+## Mental Model
+
+```text
+source -> inbox -> route -> target -> stored run -> sink
+```
+
+Sources never call an Ax program directly. A route must explicitly choose
+`observe`, `invalidate`, `wake`, or `resume`. Only the last two invoke a model.
+
+## Minimal Pattern
+
+```ts
+const source = new AxPushEventSource('application');
+const target = eventTarget('triage')
+  .program(triageAgent)
+  .ai(llm)
+  .input((input) => input.field('incident', eventPath.data()))
+  .sink({ id: 'result', write: saveResult })
+  .build();
+
+const events = eventRuntime({
+  sources: [source],
+  routes: [
+    eventRoute('incident-created')
+      .types('incident.created')
+      .wake(target)
+      .build(),
+  ],
+});
+
+await events.start();
+await source.publish({ event, identity, trust: 'authenticated' });
+```
+
+## Rules
+
+- Supply identity from authenticated adapter state, never from event data.
+- Treat events without verified identity as anonymous and untrusted.
+- Map event data into signature inputs; do not synthesize a user message.
+- Use `eventPath.data('field')` and other segment-safe selectors. Do not use
+  dotted JSONPath strings or repurpose `s()` as a mapping language.
+- Use `.project(path)` only for same-name signature projection. Explicit
+  `.field()` mappings override projection; missing or invalid signature inputs
+  dead-letter before model invocation.
+- Use `eventInput().project(...).field(...)` when a declarative mapping should
+  be callback-free and reusable, then pass that plan to `.input()`,
+  `.wakeInput()`, or `.resumeInput()`.
+- Callback `mapInput` is an escape hatch, not a validation bypass: its result is
+  normalized to the program signature and mapper failures dead-letter before
+  invocation.
+- Use `.wakeInput()` and `.resumeInput()` when the two actions need different
+  contracts. Neither action silently uses the other action's mapping.
+- Use `observe` for progress/logs and `invalidate` for catalog changes.
+- Use `resume` only with an owned continuation correlation key.
+- Use `createProgram(instance)` for stateful multi-tenant Agents.
+- Declare `retrySafety: 'idempotent'` only when stable delivery keys protect
+  every possible side effect.
+- Persist outputs before final sink delivery; redrive sink failures separately.
+- Use `debounceMs` and `coalesce: 'latest'` only when replacing intermediate
+  events is part of the route's declared policy.
+- Observe source failures with `onSourceError`.
+- The in-memory store is volatile and single-process.
+- For cooperating Node processes on one local disk, use
+  `AxSQLiteEventStore` from `@ax-llm/ax-tools/event/sqlite` with explicit
+  retention and `coordination: 'multi-worker'`. Never recommend SQLite on a
+  network filesystem.
+- Close the runtime and caller-owned protocol clients explicitly.
+- Fan out to several Agents with several matching routes, not a multi-target
+  route. This preserves independent authorization, ordering, retries, and runs.
+
+## Continuation Pattern
+
+```ts
+eventContext.registerContinuation({
+  correlation: [{ kind: 'task', value: taskId }],
+  expiresAt,
+});
+```
+
+Route progress to `observe`. Route `input_required`, completed, failed, or
+cancelled task events to `resume` when the owning program must run again.
+
+## MCP Adapter
+
+Use `ax-mcp` for client construction, transports, authentication, catalogs,
+subscriptions, tasks, and MCP-specific security policy. This skill owns the
+generic inbox, routing, continuation, store, and sink behavior.
+
+Use `client.inspectCatalog()` to discover server-owned tools, prompts, concrete
+resources, and URI templates from only the endpoint. Then use
+`AxMCPEventSource({ client, resourceSubscriptions, identity, trust })` with an
+explicit none/all/URI/selector policy. Omitted policy subscribes to no
+resources. Templates are never expanded automatically. Managed sources diff
+catalog changes, restore current logical ownership on reconnect, and release
+only their own subscriptions on close. Identity must come from the
+application's authenticated client or token mapping; a bare MCP session is
+anonymous. Add `...axMCPEventRoutes({ client })` for catalog invalidation,
+progress/log observation, and task resume. Resource notifications never get an
+implicit wake route. See `docs/MCP_SUBSCRIPTIONS.md`.
+
+## UCP Adapter
+
+Use `AxUCPWebhookEventSource({ client, identity })` inside an application-owned
+HTTP handler, then call `source.ingest(request)`. Verification of the signer
+profile, RFC 9421 signature, digest, freshness window, key rotation, and replay
+key completes before enqueue. Resolve tenant/account identity from application
+state after verification; do not copy identity from the business payload.
+
+Generated Python, Java, C++, Go, and Rust packages expose the same Core-owned
+single-worker event state machine plus functioning inline lifecycle dispatch,
+continuations, state restoration, cancellation, persisted outputs, isolated
+sink redrive, signature-aware path/input/target/route builders, and host-owned
+source, sink, clock, and store boundaries. Generated targets use the host
+signature plus a typed invocation callback when no common object-safe program
+interface exists. Do not claim persistent multi-worker support from
+`axevent.single-worker` alone.
+
+Generated runtimes do not create worker threads. `publish()` drains work due at
+`clock.now()`. Hosts use `nextDueAt()` to schedule `runDue()` for debounce,
+retry, and continuation expiry; `redrive()` is due immediately. Manual clocks
+make these transitions deterministic. Generated in-memory stores enforce
+10,000 pending deliveries, 64 MiB queued data, 1 MiB per envelope, and a
+five-second publication wait.
+
+## Testing
+
+Use `AxManualEventClock`, `AxInMemoryEventStore`, deterministic event IDs, and
+an output-capturing sink. Assert that unmatched or observe-only events never
+invoke the program, tenant scopes do not collide, outputs exist before sinks,
+and uncertain side effects become `outcome_unknown`.
+
+Persistent store implementations must pass
+`runAxEventStoreConformance(createStore, { clock })`. A store must not advertise
+multi-worker capability without the conformance marker checked by runtime
+startup.