@arnilo/prism 0.11.0 → 0.12.0

package/docs/index.md

@@ -1,15 +1,16 @@
 # Prism Docs
 
-Prism is a TypeScript/Node.js agent harness. Hosts own providers, tools, credentials, storage, and behavior; Prism supplies contracts, registries, events, and replaceable runtime primitives.
+Prism is a TypeScript agent harness for the Bun runtime. Hosts own providers, tools, credentials, storage, and behavior; Prism supplies contracts, registries, events, and replaceable runtime primitives.
 
-## Current line (0.11.0)
+## Current line (0.12.0)
 
 - **Memory-store branch reads**: the built-in memory session store implements `readBranchPath`. A snapshot walks the branch once and clones each kept entry once.
 - **JSONL parse cache**: a read after an in-process append reuses the parsed file when size and mtime match. A same-size write inside one filesystem timestamp tick can still look unchanged.
 - **Idempotency window**: memory and JSONL stores remember the latest 4,096 dedup keys. Replaying an older key appends a new entry instead of rejecting the write.
 - **In-memory lease sweep**: expired lease rows are deleted once the map reaches 1,024. A swept key starts its next fence at 1. A released key still in the map keeps `fencingToken + 1`. SQLite and Postgres adapters still keep the counter on the row.
 - **Shared text token estimate**: plain-text estimates use one `ceil(length/4)` helper. Message and entry estimates are unchanged.
-- **12 publishable packages** at current **0.11.0** lockstep, with the migration guide reachable from the release section below — inventory below.
+- **System One decision models**: `@arnilo/prism-providers/typesafe` (hosted Jev) and `@arnilo/prism-providers/laya` (self-hosted `laya-serve`) answer only `options.structuredOutput` requests, one `POST /v1/systemone` round trip, no tools or streaming; `@arnilo/prism-providers/decisions` adds a typed host call that preserves raw probabilities, confidence, the responding checkpoint, usage, and timing.
+- **12 publishable packages** at current **0.12.0** lockstep, with the migration guide reachable from the release section below — inventory below.
 
 ### Carried from the 0.10.0 line
 
@@ -47,7 +48,7 @@ Prism is a TypeScript/Node.js agent harness. Hosts own providers, tools, credent
 
 ### Carried from the 0.6.0 line
 
-- **Node 22 floor**: `engines.node` is `>=22` in all eleven publishable packages, the `node20-compat` CI leg becomes `node22-compat`, and `@types/node` moves to `^22.20.0` (plan 071; Node 20 is upstream EOL since 2026-04-30).
+- **Node 22 floor (retired in 0.12.0)**: the 0.6.0 line set `engines.node` to `>=22` in all eleven then-publishable packages, turned the `node20-compat` CI leg into `node22-compat`, and moved `@types/node` to `^22.20.0` (plan 071; Node 20 is upstream EOL since 2026-04-30). The 0.12.0 line declares `engines.bun >=1.4.2` instead — see the [Node retirement record](history/retire-node-runtime.md).
 - **Folded 0.5.7 content**: the 0.5.7 cut was never published — its durable-tool-round and strict-tool-result fixes, host knobs, peer/options truth, and dependency floors ship in 0.6.0 (migration guide below).
 - **Release-truth gates**: one forward-claim version-literal gate (manifests, internal ranges, lockfile, version constant, index banner, workflow tags), a workflow-liveness gate (every script target and action reference resolves, actions SHA-pinned), and a load-tolerant startup budget ratio (plan 071).
 - **Self-describing coverage failures**: a failing coverage child prints its redacted output tail and records `status`/`exitCode`/`tail` on its artifact row (plan 071).
@@ -83,7 +84,7 @@ Prism is a TypeScript/Node.js agent harness. Hosts own providers, tools, credent
 - [Agent definitions](agent-definitions.md): declarative `AgentDefinition` resolution and `AGENT.md` bundle discovery, fail-closed activation.
 - [Agent loops](agent-loops.md): replaceable loops with `limits.maxToolRounds` budgets and durable revision/restore hooks.
 - [Hooks](hooks.md): the hook model — stop hooks with bounded continuation, session/compaction boundary seams, and the Claude Code / Codex event map plus the `hooks.json` adapter.
-- [Guardrails](guardrails.md): typed fail-closed input/output/tool checks with redacted decision records.
+- [Guardrails](guardrails.md): typed fail-closed input/output/tool checks with redacted decision records, plus an opt-in tool-input field-evidence verifier for proposal-shaped calls.
 - [Agent events](agent-events.md): `turn_started`/`tool_call_delta` stream plus durable page/resume sources for reconnect.
 - [Observability](observability.md): OTel GenAI span hierarchy, workflow spans, cockpit aggregations, RAG span tree, bounded trace linkage, exporter isolation.
 - [Execution timeline](execution-timeline.md): execution timeline projection and cockpit summaries for host dashboards and trajectory evals.
@@ -99,7 +100,7 @@ Prism is a TypeScript/Node.js agent harness. Hosts own providers, tools, credent
 
 - [Compaction and retry policies](compaction-and-retry.md): host-replaceable summarize/retry policies with deprecated-option removals fail closed.
 - [LLM compaction subpath](compaction-llm.md): provider-backed summarization with finite `model.parameters.maxTokens` and coding handoff strategy.
-- [Observational memory compaction subpath](compaction-observational-memory.md): source-backed observations/reflections, an optional work-scope index for the current working set, and exact-id recall; `invalidatedIds` withhold derived injection.
+- [Observational memory compaction subpath](compaction-observational-memory.md): source-backed observations/reflections, coverage-safe admission that retains or defers on unobserved prefixes, an optional work-scope index for the current working set, and exact-id recall; `invalidatedIds` withhold derived injection.
 - [Working and semantic memory](working-and-semantic-memory.md): working-memory store, semantic recall, pgvector path, consent lifecycle, lineage invalidation, parent-child share grants.
 - [Memory fabric](memory-fabric.md): opt-in typed notes (fact/procedure/file/working/episode) with validity windows over the existing vector and working stores.
 - [Scoped memory](scoped-memory.md): workspace-scope guard, gated writes, promotion ladder, decay reads, audit mirror (`@arnilo/prism-memory/scoped`).
@@ -109,7 +110,7 @@ Prism is a TypeScript/Node.js agent harness. Hosts own providers, tools, credent
 - [Work artifacts and review](work-artifacts-and-review.md): artifact attach, revision compare, evidence-bound citations, approve/reject, expiring delivery links.
 - [Session stores and branching](session-stores-and-branching.md): branch-semantics helper reference (compatibility stub for session-stores.md).
 - [Database persistence](database-persistence.md): production persistence contracts, migrations, retention, and adapter conformance harnesses.
-- [SQLite persistence](sqlite-persistence.md): optional `better-sqlite3` adapter with FTS search and verified migrations.
+- [SQLite persistence](sqlite-persistence.md): built-in `bun:sqlite` adapter with FTS search and verified migrations.
 - [PostgreSQL persistence](postgres-persistence.md): optional pooled `pg` adapter with advisory-locked migrations and live conformance.
 - [Enterprise PostgreSQL state](enterprise-postgres-state.md): durable governance/router/ERP state, outbox/inbox messaging, approval records.
 - [Migration guide](migration.md): the era index of migration cuts with replacement tables and rollback notes.
@@ -131,7 +132,8 @@ Prism is a TypeScript/Node.js agent harness. Hosts own providers, tools, credent
 - [Use-case model selection](use-case-model-selection.md): bind models for compaction, memory, and other non-session LLM jobs.
 - [Provider request policies](provider-request-policies.md): kernel request-option defaults with host `ProviderRequestPolicy` overlays.
 - [Provider packages](provider-packages.md): all adapters as `@arnilo/prism-providers/<adapter>` subpaths; tool_result and event wire shapes stay provider-neutral.
-  - First-party adapters: [`openai`](providers/openai.md), [`anthropic`](providers/anthropic.md), [`google`](providers/google.md), [`opencode-go`](providers/opencode-go.md), [`openrouter`](providers/openrouter.md), [`zai`](providers/zai.md), [`deepseek`](providers/deepseek.md), [`xai`](providers/xai.md), [`clinepass`](providers/clinepass.md), [`hyper`](providers/hyper.md), [`commandcode`](providers/commandcode.md), [`kimi`](providers/kimi.md), [`alibaba`](providers/alibaba.md), [`ollama`](providers/ollama.md), [`neuralwatt`](providers/neuralwatt.md), plus the cross-vendor `model-discovery` listing adapters on the same page.
+  - First-party adapters: [`openai`](providers/openai.md), [`anthropic`](providers/anthropic.md), [`google`](providers/google.md), [`opencode-go`](providers/opencode-go.md), [`openrouter`](providers/openrouter.md), [`zai`](providers/zai.md), [`deepseek`](providers/deepseek.md), [`xai`](providers/xai.md), [`clinepass`](providers/clinepass.md), [`hyper`](providers/hyper.md), [`commandcode`](providers/commandcode.md), [`kimi`](providers/kimi.md), [`alibaba`](providers/alibaba.md), [`ollama`](providers/ollama.md), [`neuralwatt`](providers/neuralwatt.md), [`typesafe`](providers/typesafe.md), [`laya`](providers/laya.md), plus the cross-vendor `model-discovery` listing adapters on the same page.
+  - [System One decisions](providers/decisions.md): typed host decision call over the shared `POST /v1/systemone` client, preserving raw probabilities/confidence/legend, the responding checkpoint, usage, and timing with pre-fetch bounds and deadline/abort composition.
   - Enterprise cloud (workload identity): [`azure`](providers/azure.md) (Entra/Foundry), [`bedrock`](providers/bedrock.md) (IAM/SigV4; OpenAI-compatible or native Converse route), [`vertex`](providers/vertex.md) (ADC/Vertex).
   - Optional AI SDK adapter: [`ai-sdk`](providers/ai-sdk.md) maps host-owned pinned `LanguageModelV4` models onto Prism streams.
 - [OpenAI-compatible provider](providers/openai-compatible.md): base Chat Completions subpath with strict-completion default and vendor hooks.
@@ -146,8 +148,8 @@ Prism is a TypeScript/Node.js agent harness. Hosts own providers, tools, credent
 - [Versioned prompt registry](prompt-registry.md): immutable content-hashed prompt assets with durable stores and bounded diff.
 - [Instruction injection](instruction-injection.md): package injectors layer redacted instructions without granting capabilities.
 - [Context and skills](context-and-skills.md): ordered context providers, progressive skill disclosure, fail-closed activation. `@arnilo/prism-work` ships `docx`, `xlsx`, `powerpoint`, `pdf`.
-- [LLM Wiki](wiki.md): optional knowledge compiler emitting OKF bundles, with `/wiki-ingest` raw staging (text, file, image, or URL via a host `fetchUrl` hook) and on-device hybrid search.
-- [Retrieval-augmented generation](rag.md): bounded source lifecycle, hybrid retrieval, permission-trimmed query legs, reranking, evidence-backed citations, inert injection.
+- [LLM Wiki](wiki.md): optional knowledge compiler emitting OKF bundles, with `/wiki-ingest` raw staging (text, file, image, or URL via a host `fetchUrl` hook). A set `extractDocument` hook owns PDF and CSV; image OCR is opt-in.
+- [Retrieval-augmented generation](rag.md): bounded source lifecycle, hybrid retrieval, permission-trimmed query legs, reranking, evidence-backed citations, inert injection. Host parsers may convert documents; failed OCR is not indexed.
 - [Knowledge synchronization](knowledge-sync.md): paged enterprise-source import with a Drive connector, checkpointed change cursors, and host-owned ACL mapping.
 
 ## Tools
@@ -181,6 +183,7 @@ Prism is a TypeScript/Node.js agent harness. Hosts own providers, tools, credent
 ## Documents, sheets, and diagrams
 
 - [Documents, spreadsheets, and presentations](documents.md): OOXML generation, parsing, import fidelity reports, patching, structural diffs, and bounded preview for Office formats.
+- [Document extraction](document-extraction.md): optional local Markdown conversion for Office, OpenDocument, CSV, and text PDFs. Scanned PDFs fail closed unless the host runs the packaged Docling worker; never hosted OCR.
 - [Spreadsheets and CSV data](sheets.md): fail-closed XLSX/CSV ingestion with decimal-safety guarantees.
 - [Diagrams and mxGraph embed](diagrams.md): origin-enforced draw.io embed client with XXE-safe XML validation.
 
@@ -250,10 +253,12 @@ Prism is a TypeScript/Node.js agent harness. Hosts own providers, tools, credent
 - [Telegram channel](telegram-channel.md): official `@arnilo/prism-channels/telegram` long polling and mountable webhook ingress with durable offset/lease handling, approval callbacks, opt-in granted group/topic text, bounded media with optional voice transcription/synthesis, and opt-in streaming drafts.
 - [Signal channel (experimental)](signal-channel.md): `@arnilo/prism-channels/signal` pinned signal-cli v0.14.8 private-socket manual receive, explicit policy gate, UUID DM filtering and bounded ambiguous delivery.
 - [Messaging channel operations](messaging-channel-operations.md): durable journal, restart and reconciliation contract, lease fencing, retention and the operator runbook.
+- [Synapta → Prism integration review](synapta-integration-review.md): host-integration findings, the F1–F4 fixes, the remediation tasks that shipped them, and the authorities that stay with the host.
 
 ## Release and install
 
-- [Release and install](release-and-install.md): install rules, package graph, and deterministic resumable publication.
+- [Release and install](release-and-install.md): Bun install rules and the runtime matrix, the package graph, and deterministic resumable publication.
+- [Migrate 0.11 → 0.12](history/migrate-to-0.12.0.md): Bun `>=1.4.2`, `bun:sqlite`, and optional local document extraction.
 - [Migrate 0.10 → 0.11](migrate-to-0.11.md): idempotency window, in-memory lease fence reset, and the persona/graft subpath removals.
 - [Migrate 0.8 → 0.9](migrate-to-0.9.md): the four behavior deltas inside existing surfaces (limit-death stream order, turn-trace metadata, cache-stable disclosure, labeled usage estimates), every new option with its sizing line, and 0.9.0 host migration steps.
 - [Migrate 0.7 → 0.8](migrate-to-0.8.md): work-family import map, messaging channels, connected apps, durable runs, and 0.8.0 host migration steps.
@@ -265,23 +270,23 @@ Prism is a TypeScript/Node.js agent harness. Hosts own providers, tools, credent
 
 ## Package inventory
 
-The generated inventory below derives from [`scripts/package-truth.json`](../scripts/package-truth.json) — regenerate with `node scripts/package-truth.mjs --emit-docs`, never hand-edit.
+The generated inventory below derives from [`scripts/package-truth.json`](../scripts/package-truth.json) — regenerate with `bun scripts/package-truth.mjs --emit-docs`, never hand-edit.
 
 <!-- generated:package-truth:inventory begin -->
-**12 publishable manifests** — root `@arnilo/prism` plus 11 workspace packages (4 `prism-*` family packages, 7 capability packages). Generated by `node scripts/package-truth.mjs --emit-docs` — do not hand-edit.
+**12 publishable manifests** — root `@arnilo/prism` plus 11 workspace packages (4 `prism-*` family packages, 7 capability packages). Generated by `bun scripts/package-truth.mjs --emit-docs` — do not hand-edit.
 
 | package | version | notes |
 | --- | --- | --- |
-| `@arnilo/prism` | 0.11.0 | core — runtime, CLI/RPC, templates, docs |
-| `@arnilo/prism-channels` | 0.11.0 | family — transport-neutral messaging runtime, durable journal, pairing and one-use approvals; official /telegram (private DMs, opt-in granted groups/topics) and experimental pinned signal-cli /signal |
-| `@arnilo/prism-coding-tools` | 0.11.0 | family — /agent, /security, /openapi, /computer-use-linux, /dev, /impeccable subpaths |
-| `@arnilo/prism-core` | 0.11.0 | family — /runtime, /sessions, /governance, /credentials, /enterprise, /validation subpaths |
-| `@arnilo/prism-providers` | 0.11.0 | family — all provider adapters as `/<adapter>` subpaths |
-| `@arnilo/prism-acp-agent` | 0.11.0 | capability — ACP adapter |
-| `@arnilo/prism-ag-ui` | 0.11.0 | capability — AG-UI/A2A/A2UI adapter |
-| `@arnilo/prism-hooks` | 0.11.0 | capability — Claude/Codex-compatible hooks.json adapter compiled onto middleware, guardrail, injector, and stop-hook seams |
-| `@arnilo/prism-mcp` | 0.11.0 | capability — MCP client/server/OAuth interop |
-| `@arnilo/prism-memory` | 0.11.0 | capability — memory plus /rag, /compaction/*, /fabric, /wiki subpaths |
-| `@arnilo/prism-web-tools` | 0.11.0 | capability — Brave/Exa/Firecrawl plus peer-gated /browser and /obscura subpaths |
-| `@arnilo/prism-work` | 0.11.0 | capability — /connectors, /documents, /sheets, /diagrams, /document-reader, /sandbox, /skills, /tools subpaths |
+| `@arnilo/prism` | 0.12.0 | core — runtime, CLI/RPC, templates, docs |
+| `@arnilo/prism-channels` | 0.12.0 | family — transport-neutral messaging runtime, durable journal, pairing and one-use approvals; official /telegram (private DMs, opt-in granted groups/topics) and experimental pinned signal-cli /signal |
+| `@arnilo/prism-coding-tools` | 0.12.0 | family — /agent, /security, /openapi, /computer-use-linux, /dev, /impeccable subpaths |
+| `@arnilo/prism-core` | 0.12.0 | family — /runtime, /sessions, /governance, /credentials, /enterprise, /validation subpaths |
+| `@arnilo/prism-providers` | 0.12.0 | family — all provider adapters as `/<adapter>` subpaths |
+| `@arnilo/prism-acp-agent` | 0.12.0 | capability — ACP adapter |
+| `@arnilo/prism-ag-ui` | 0.12.0 | capability — AG-UI/A2A/A2UI adapter |
+| `@arnilo/prism-hooks` | 0.12.0 | capability — Claude/Codex-compatible hooks.json adapter compiled onto middleware, guardrail, injector, and stop-hook seams |
+| `@arnilo/prism-mcp` | 0.12.0 | capability — MCP client/server/OAuth interop |
+| `@arnilo/prism-memory` | 0.12.0 | capability — memory plus /rag, /compaction/*, /fabric, /wiki subpaths |
+| `@arnilo/prism-web-tools` | 0.12.0 | capability — Brave/Exa/Firecrawl plus peer-gated /browser and /obscura subpaths |
+| `@arnilo/prism-work` | 0.12.0 | capability — /connectors, /documents, /sheets, /diagrams, /document-extraction, /document-reader, /sandbox, /skills, /tools subpaths |
 <!-- generated:package-truth:inventory end -->

package/docs/live-testing.md

@@ -2,7 +2,7 @@
 
 ## What it does
 
-Prism ships three network-free test tiers by default (`npm test`, per-package `node --test` suites, and packed-consumer journeys) plus an opt-in **live matrix** that runs the same public surface against real credentials. This page documents how to run the live matrix, which credentials each suite needs, and the guarantees the harness gives you: a missing credential skips its suite (never fails), and secrets never enter the repo, logs, or reports.
+Prism ships three network-free test tiers by default (`bun run test`, per-package `bun test` suites, and packed-consumer journeys) plus an opt-in **live matrix** that runs the same public surface against real credentials. This page documents how to run the live matrix, which credentials each suite needs, and the guarantees the harness gives you: a missing credential skips its suite (never fails), and secrets never enter the repo, logs, or reports.
 
 ## When to use it
 

package/docs/mcp-tools.md

@@ -32,7 +32,7 @@ const app = await bridge.apps!.readResource("ui://weather/card");
 
 `bridge.apps` exposes reviewed UI metadata, linked bounded `ui://` HTML, and same-server app tools for a host renderer/proxy; it never creates an iframe or executes HTML.
 
-**Conformance and verification record (plan 063 task 7):** the official `@modelcontextprotocol/conformance` suite runs against the dual-era serving stack via `node scripts/mcp-conformance-2026.mjs` — the 20 expressible scenarios pass and the 14 scenarios requiring surface Prism does not expose (server-initiated sampling/elicitation/logging/progress from tool callbacks, `resources/subscribe`, completion capability, session-based SSE polling, non-text tool content blocks) are recorded as documented boundaries in `scripts/mcp-conformance-2026-baseline.yaml`. The CLI publishes scenarios only up to spec version 2025-11-25; the run is repeated when 2026-07-28 scenarios ship upstream. Measured on the loopback fixture (single process): legacy connect ~60ms, auto connect (with the one discovery probe) ~40ms, pinned modern connect ~20ms, steady-state bridge tool call ~4ms, uncached list walk ~5ms, cached list refresh ~2ms — the only added connect cost versus 1.x is the single negotiation probe plus SDK codec work. Security regression coverage lives in the package suites: malformed envelopes/headers, auth mix-up (`ERR_PRISM_MCP_OAUTH_ORIGIN`), SSRF/DNS-rebinding, oversized JSON/schema/results, MRTR round/replay, subscription exhaustion caps, cross-principal cache/session isolation, timeouts, cancellation, and redaction.
+**Conformance and verification record (plan 063 task 7):** the official `@modelcontextprotocol/conformance` suite runs against the dual-era serving stack via `bun scripts/mcp-conformance-2026.mjs` — the 20 expressible scenarios pass and the 14 scenarios requiring surface Prism does not expose (server-initiated sampling/elicitation/logging/progress from tool callbacks, `resources/subscribe`, completion capability, session-based SSE polling, non-text tool content blocks) are recorded as documented boundaries in `scripts/mcp-conformance-2026-baseline.yaml`. The CLI publishes scenarios only up to spec version 2025-11-25; the run is repeated when 2026-07-28 scenarios ship upstream. Measured on the loopback fixture (single process): legacy connect ~60ms, auto connect (with the one discovery probe) ~40ms, pinned modern connect ~20ms, steady-state bridge tool call ~4ms, uncached list walk ~5ms, cached list refresh ~2ms — the only added connect cost versus 1.x is the single negotiation probe plus SDK codec work. Security regression coverage lives in the package suites: malformed envelopes/headers, auth mix-up (`ERR_PRISM_MCP_OAUTH_ORIGIN`), SSRF/DNS-rebinding, oversized JSON/schema/results, MRTR round/replay, subscription exhaustion caps, cross-principal cache/session isolation, timeouts, cancellation, and redaction.
 
 **Extension status (revalidated 2026-09-05 against the modular SDK v2, plan 063 task 6):** MCP Apps (`io.modelcontextprotocol/ui`) is the only extension Prism negotiates — on both the 2025 legacy handshake and 2026-07-28 (modern capabilities ride per request in `params._meta`); resource reads/pagination now go through SDK v2 `listResources`/`readResource` with the same per-descriptor byte bounds, item caps, cursor-loop detection, and linked-HTML validation as before. **Tasks (`io.modelcontextprotocol/tasks`) is intentionally not advertised and not supported in this release**: neither the bridge client nor `createPrismMcpServer` declares it, draft-era `task` members on tool results fail closed (`McpBridgeError` surfaced as a `ToolResult.error`, never read as tool output; modern `resultType: "task"` fails SDK decode), and task handles are not accepted without a supported extension codec plus a durable ownership model. Re-evaluate Tasks when the official TypeScript client/server extension codec supports task result dispatch, polling/update/cancel, and subscription notifications with green conformance.
 
@@ -298,7 +298,7 @@ Official Exa/Firecrawl MCP servers may be tested only as explicit hardened proto
 An operator-gated smoke drives `createPrismMcpServer` through the real `@modelcontextprotocol/client` SDK over a real stdio subprocess — the same shape a production MCP host uses:
 
 ```bash
-PRISM_TEST_MCP_CLIENT=1 node scripts/mcp-client-smoke.mjs
+PRISM_TEST_MCP_CLIENT=1 bun scripts/mcp-client-smoke.mjs
 ```
 
 The scenario stays sandboxed (read-only echo tool, authorize-gated denial, no policy bypass) and covers: modern auto + legacy handshakes, `tools/list` of registered capabilities, `tools/call` round-trip, the authorize gate enforced over the wire, and malformed-frame fail-closed (the transport tears the connection down instead of answering garbage). Server-initiated `elicitation/create` is a documented Prism boundary (`scripts/mcp-conformance-2026-baseline.yaml`); the bridge-side MRTR elicitation round-trip is covered over real HTTP by the package's modern-bridge tests. Registered in `scripts/live-matrix.json` as `mcp/client-smoke`.

package/docs/messaging-channels.md

@@ -17,7 +17,7 @@ Use when a host already operates a chat bot (or plans to) and wants selected Pri
 Install the required `@arnilo/prism` peer plus this package. `createMessagingRuntime` takes `MessagingRuntimeOptions`: `authorize`, `resolveAgent`, `deliver`, optional `limits` (`ChannelLimits`), `redactor`, `checkpoints`, `leases`, and `resolveBinding`. Durable writers are also constructed with `ChannelStateStoreOptions`, `ChannelDeliveryJournalOptions`, and `ChannelPairingStoreOptions`.
 
 ```bash
-npm install @arnilo/prism @arnilo/prism-channels
+bun add @arnilo/prism @arnilo/prism-channels
 ```
 
 ## Request/response example

package/docs/migrate-to-0.7.md

@@ -329,7 +329,7 @@ Additive. `@arnilo/prism-providers/bedrock` now ships a native route next to the
 3. Re-check each §4–§17 item your host touches: they are behavioral tightenings inside existing surfaces (accounting, drafts, authorization, narrowing, fidelity), not new opt-ins.
 4. Adopt the opt-in additions only where they matter: §18 attention compiler, §19 memory fabric, §20 work scopes, §21 spawn tools.
 5. Build and run your suite. No persisted-data migration exists or is needed: the 0.7.0 additions write through existing stores (working/vector records, checkpoints, observational-memory entries) under the same schema, and stores still fail closed on unknown or newer schema versions rather than rewriting data.
-6. Optional: re-run `npm run release:gate` locally to reproduce the release evidence matrix.
+6. Optional: re-run `bun run release:gate` locally to reproduce the release evidence matrix.
 
 ## Rollback
 

package/docs/migrate-to-0.8.md

@@ -98,7 +98,7 @@ Identity-bound MCP connected-app sessions admit host-selected transports and reg
 
 ## Operator / release honesty (not a host API break)
 
-- `npm run test:postgres` writes gitignored `scripts/postgres-evidence.json` bound to `git rev-parse HEAD`. `release:gate` reports the Postgres surface as pass only when that evidence matches this tree. A stale phase baseline is **blocked**.
+- `bun run test:postgres` writes gitignored `scripts/postgres-evidence.json` bound to `git rev-parse HEAD`. `release:gate` reports the Postgres surface as pass only when that evidence matches this tree. A stale phase baseline is **blocked**.
 - Coverage artifact keys must equal live workspace package names (`@arnilo/prism-work`, not `@arnilo/prism-office`).
 
 ## Upgrade steps
@@ -108,7 +108,7 @@ Identity-bound MCP connected-app sessions admit host-selected transports and reg
 3. Adopt §6–§9 only where the host wants channels, connected apps, durable-run checkpoints, or the work sandbox. Omitted, request bytes and tool lists stay 0.7.0.
 4. Re-read §2–§5 if the host runs observational-memory workers, messaging channels, AG-UI, or inspects checkpoint ownership errors.
 5. Build and run the host suite. No new session-store schema version ships in 0.8.0; channel journals and work HTTP state are new stores a 0.7.0 host never opened.
-6. Optional: `PRISM_TEST_POSTGRES_URL=… npm run test:postgres` then `npm run release:gate` to reproduce this-tree Postgres evidence.
+6. Optional: `PRISM_TEST_POSTGRES_URL=… bun run test:postgres` then `bun run release:gate` to reproduce this-tree Postgres evidence.
 
 ## Rollback
 

package/docs/migrate-to-0.9.md

@@ -196,7 +196,7 @@ Sizing: the local reranker declares no inference dependency — the built-in loa
 3. Re-read §1–§4 if the host tails durable agent events, parses provider-turn metadata, uses progressive disclosure or prompt caching, or bills usage for vendors that report no usage.
 4. Adopt §5–§13 only where the host wants the new surfaces. Omitted, request bytes, stores, and tool lists stay 0.8.
 5. Run the new migration 004 on SQLite/Postgres stores if the host wants indexed session search; existing tables and columns are untouched, and 0.8 stores open unchanged.
-6. Optional: `PRISM_TEST_POSTGRES_URL=… npm run test:postgres` then `npm run release:gate` to reproduce this-tree Postgres evidence.
+6. Optional: `PRISM_TEST_POSTGRES_URL=… bun run test:postgres` then `bun run release:gate` to reproduce this-tree Postgres evidence.
 
 ## Rollback
 

package/docs/migration.md

@@ -85,7 +85,7 @@ What a 0.6.0 host must check before upgrading:
 
 What a 0.5.x host must check before upgrading:
 
-- **Runtime.** Move the host process and any container image to Node 22.6+ (the docs/test harness strips TypeScript natively from 22.6; Node 22 LTS or later is the supported answer). `engines.node` is now `>=22`, so `npm install` fails closed on older runtimes with `engine-strict` enabled.
+- **Runtime.** Move the host process and any container image to Node 22.6+ (the docs/test harness strips TypeScript natively from 22.6; Node 22 LTS or later is the supported answer). `engines.node` is now `>=22`, so `npm install` fails closed on older runtimes with `engine-strict` enabled. (The Node floor retired in 0.12.0 — the manifests declare `engines.bun >=1.4.2`; see [history/retire-node-runtime.md](history/retire-node-runtime.md).)
 - **CI legs.** The release workflow's compatibility leg is renamed `node20-compat` → `node22-compat` and runs on `node-version: "22"`; branch-protection required-check lists that name the old job id must be updated.
 - **Development types.** `@types/node` (dev) moves `^20.19.0` → `^22.20.0` in the root and `@arnilo/prism-coding-tools`, tracking the declared floor. Hosts building Prism from source should not pin their own `@types/node` below 22 while the floor is `>=22`.
 - **No migration step for Prism itself.** No import path, store schema, event shape, or public signature changed for the floor; it is one of the two host-visible deltas in this cut (`scripts/phase12-freeze-manifest.json` deviation `dev-006`), the other being the third-party peer floors and the removed `@arnilo/prism-office` `playwright-core` peer listed in [migrate-to-0.6.md](migrate-to-0.6.md#3-arniloprim-office-is-peer-free).
@@ -106,7 +106,7 @@ The 0.5.7 cut was never published, so its content ships in 0.6.0. Third-party ra
 Dev-tooling and release-gate changes in the same cut (no host action required):
 
 - **`@types/node` dev `^26.1.1` → `^20.19.0` at the 0.5.7 cut, then `^22.20.0` here.** Development types track the declared runtime floor, so a Node-22+-only API fails the build instead of compiling clean against a newer type surface. `docs/release-and-install.md` records the policy: the types package tracks the floor, and raising the floor is a support-matrix change (freeze manifest + CI legs), not a dependency bump. The `^20.19.0` pin immediately caught four runnable examples using `import.meta.main` (Node ≥22.18/≥24.2) on a Node-20 floor — they now use the house `import.meta.url === \`file://${process.argv[1]}\`` guard, so they no longer silently no-op below Node 22.18.
-- **Node 20 floor removed in 0.6.0.** The never-published 0.5.7 deliberately kept `engines.node >=20` because dropping a supported line is a host-breaking support-matrix change that does not belong in a patch release; the 0.6.0 minor is the right vehicle (Node 22 is maintenance LTS to 2027-04-30, Node 24 active LTS to 2028-04-30).
+- **Node 20 floor removed in 0.6.0.** The never-published 0.5.7 deliberately kept `engines.node >=20` (both Node floors retired in 0.12.0) because dropping a supported line is a host-breaking support-matrix change that does not belong in a patch release; the 0.6.0 minor is the right vehicle (Node 22 is maintenance LTS to 2027-04-30, Node 24 active LTS to 2028-04-30).
 - **Internal first-party ranges are gated at the cut version exactly.** `release.mjs validateRelease` (lockstep mode, which `release.mjs gate --lockstep --version` and the publish path both use) requires every `@arnilo/*` range to be the cut version (exact `0.6.0` or caret `^0.6.0`). A range that merely *satisfies* it — `^0.5.5` alongside `^0.5.6`, which is what the pre-cut tree carried — now fails the gate closed, because it lets two installs of the same release line resolve different first-party minors.
 
 ## 0.5.3 → 0.5.4 (export-shape break in `@arnilo/prism`)

package/docs/model-registry.md

@@ -157,7 +157,7 @@ The `@arnilo/prism-providers/model-discovery` adapters have an opt-in live leg t
 
 ```bash
 PRISM_LIVE_PROVIDER_TESTS=1 OPENAI_API_KEY=...   # or GEMINI_API_KEY for the Google route
-node --test packages/prism-providers/dist/model-discovery/__tests__/live.test.js
+bun test packages/prism-providers/dist/model-discovery/__tests__/live.test.js
 ```
 
 Chooses the OpenAI-compatible or Google route based on which key is present; neither → skip.

package/docs/model-routing.md

@@ -192,6 +192,27 @@ The adapter executes an explicit six-stage lifecycle for every call:
    - Usage recording errors: Propagate out on success so persistence failures are not concealed.
    - Invokes `onSettlement` callback with `GovernedInvocationSettlement` telemetry.
 
+### Aggregate budgets across host step loops
+
+A host that runs one business step per `session.run()` can keep one aggregate liability pool by
+supplying the **same `taskId`** to every call: reservations and usage aggregate at the task/owner
+level, so a per-run token cap is never a per-run reset. The model stays pinned (configure one fixed
+`model` and no fallbacks) — this is policy-preserving accounting, not model routing. Run three
+sequential calls plus auxiliary paid work (for example a compaction attempt admitted through
+`router.resolve`) and read `router.readBudget({ identity, taskId })` for the remaining aggregate;
+never represent that number by faking a context-window or attention threshold.
+
+- **Hold renewal fencing**: renew a long hold with `router.renewBudget()` or
+  `governedProvider.renewBudget()`. The fencing token advances and the pre-renewal handle fails
+  closed with `ERR_PRISM_MODEL_ROUTER_STATE` instead of committing twice.
+- **Unknown liability**: a provider that reports no usage settles the *reserved* amount as
+  `unknownUsage: true` (never zero), visible on `GovernedInvocationSettlement` and in diagnostics.
+- **Durability boundary**: without a `stateStore` the pool is process-local; surviving worker
+  restarts needs a durable store (for example [enterprise PostgreSQL state](enterprise-postgres-state.md)).
+
+Runnable composition: [`examples/model-router-aggregate-budgets.ts`](../examples/model-router-aggregate-budgets.ts)
+(offline, three `session.run()` calls plus one auxiliary call on a fixed pin).
+
 ### Synchronous facade (`providerSource`) governance matrix
 
 The synchronous `router.providerSource(model)` facade is strictly intended for simple synchronous resolution where allow-lists and residency checks are sufficient. Any configuration requiring asynchronous state or multi-candidate evaluations fails closed at call time:

package/docs/multi-agent-patterns.md

@@ -1,11 +1,12 @@
-# Multi-agent patterns: handoff, crew, supervisor, spawn tool, A2A
+# Multi-agent patterns: handoff, crew, supervisor, spawn tool, A2A, event-driven swarm
 
 ## What it does
 
-Maps five Prism answers for "more than one agent" onto one decision table. All five compose existing seams — none introduces a new runtime:
+Maps six Prism answers for "more than one agent" onto one decision table. All six compose existing seams — none introduces a new runtime:
 
 - **In-session handoff (swarm)** — agent A transfers control of the ongoing conversation to agent B by calling a host-built `handoff` tool; the host resolves the target `AgentDefinition` with `resolveAgentDefinition` and opens the specialist against the same session (same store + session id, previous run's `leafId`). One transcript, no new session. No helper primitive ships; the tool factory lives in [`examples/handoff-swarm.ts`](../examples/handoff-swarm.ts).
 - **Hierarchical crew** — a manager agent decomposes a goal into typed tasks (`{ tasks: [{ role, instruction }] }`) via structured output ([`Artifact*`](structured-output.md)), fans out to parallel role specialists with bounded `maxFanOut` ([`fanOutNode`](workflows.md)), aggregates deliverables with host reduce ([`joinNode`](workflows.md)), and validates outputs with conditional routing to completion or revision ([`conditionalNode`](workflows.md)). The entire process is a deterministic DAG workflow with zero new runtime primitives. Live demo in [`examples/crew-hierarchy.ts`](../examples/crew-hierarchy.ts).
+- **Event-driven swarm topology** — autonomous specialist agents communicate dynamically over a shared event router node using topic subscriptions ([`defineSwarmWorkflow`](workflows.md#declarative-event-driven-swarm-topology), [`swarmRouterNode`](workflows.md#declarative-event-driven-swarm-topology), [`publishSwarmEvent`](workflows.md#declarative-event-driven-swarm-topology)), per-node scoped working memory ([`withNodeScope`](workflows.md#scoped-per-node-state-and-subgraph-isolation)), and wave-based cyclic supersteps. Runnable proof: [`examples/cyclic-swarm-topology.ts`](../examples/cyclic-swarm-topology.ts).
 - **Supervisor delegation** — `@arnilo/prism-core/runtime/supervisor` `delegate()` invokes allow-listed child agents as bounded runs and returns their result to the parent. Separate child transcripts, hooks, budgets, narrowing.
 - **In-process spawn tool** — `createSpawnAgentTool({ supervisor })` gives a parent model non-exclusive sync or bounded async `spawn_agent` calls over that same host-owned supervisor catalog; `wait_agent` / `cancel_agent` join or abort local handles. It is an API adapter, not a runtime.
 - **A2A 1.0** — cross-service interop over the JSON-RPC/HTTPS binding; the remote peer's lifecycle is host-owned behind `A2ATaskLifecycle`.
@@ -16,11 +17,12 @@ Maps five Prism answers for "more than one agent" onto one decision table. All f
 | --- | --- | --- | --- | --- |
 | In-session handoff | One host, one ongoing conversation; the model decides **when** to transfer; specialists are alternate definitions of the same app | One continuous transcript chain (same store, session id, `leafId`) | Same session scope; give the specialist its own identity via its definition (`AgentConfig.identity` / `RunOptions.identity`) | Attribution is per-run: each `session.run()`'s events/result belong to the active definition — record the swap in host bookkeeping; no `delegated_agent_step` event exists for in-process swaps |
 | Hierarchical crew | A goal requires dynamic decomposition by a manager LLM, parallel execution by role specialists, host aggregation, and conditional validation/revision loop | Workflow DAG execution — each specialist executes a bounded child task session; final deliverable returns to host | Workflow tenant/ownership scopes propagate; specialists activate only their own narrowed `tools` | Workflow node events (`node_started`/`node_finished`/`agent_event`); task attribution per role in the aggregated deliverable |
+| Event-driven swarm | Multiple specialist agents collaborate asynchronously by publishing and subscribing to topic events; decentralized cyclic workflow | Workflow cyclic supersteps — agents run in waves triggered by matching event topics; state isolated per agent scope | Workflow tenant/ownership scopes propagate; each agent updates only its scoped slice of state and emits topic events | Wave-level checkpoints with `node_started`/`node_finished`/`agent_event` pairs per iteration; published swarm events recorded in state |
 | Supervisor delegation | Host code dynamically selects a bounded child run | Separate runs; child result returns to the host | Parent identity/effectStore propagate; child factories receive derived resource/thread ids and AND-composed permission | Dedicated `delegation_started/finished/rejected/error` events, projectable through observability `handleDelegation()`; opt-in `delegation_child_event` passthrough |
 | In-process spawn tool | Parent model needs an allow-listed child as a non-exclusive tool call | Separate runs; sync result returns through `spawn_agent`, async handle joins through `wait_agent` | Host owns catalog, tools, scopes, limits, and local handles; schema accepts only child ID/input/thread ID/mode plus policy args the host ceiling allows | Same supervisor `delegation_*` events; with host opt-in, `child_milestone` / `delegation_child_event` (redacted, capped, rate-coalesced) |
 | A2A 1.0 | The other agent is owned by a **different service/deployment**; cross-org or cross-cluster; needs durable task lifecycle, push configs, streaming | Protocol boundary (JSON-RPC/HTTPS agent card); replay/reconnect via host-owned task adapter | Exact-origin verified client, `A2AAuthorization` per operation, principal-scoped push configs | Host-owned task adapter records the remote lifecycle; Prism creates no worker/store |
 
-Rule of thumb: same conversation → handoff; dynamic task decomposition + parallel execution → hierarchical crew; host-selected same-process subtask → supervisor delegation; model-requested allow-listed subtask → in-process spawn tool; different deployment/trust boundary → A2A.
+Rule of thumb: same conversation → handoff; dynamic task decomposition + parallel execution → hierarchical crew; decentralized asynchronous event routing → event-driven swarm; host-selected same-process subtask → supervisor delegation; model-requested allow-listed subtask → in-process spawn tool; different deployment/trust boundary → A2A.
 
 ## How in-session handoff works
 
@@ -138,7 +140,78 @@ Live demo: [`examples/crew-hierarchy.ts`](../examples/crew-hierarchy.ts) — man
 | **Process (Sequential / Hierarchical)** | Workflow DAG ([`defineWorkflow`](workflows.md) / Edges) | Edges define data and execution dependencies; no unconstrained agent-to-agent loops. |
 | **Task Output Aggregation** | Join Node ([`joinNode`](workflows.md) + `reduce`) | Host-controlled reduction aggregating specialist outputs and computing per-role attribution. |
 | **Validation & Quality Review** | Conditional Node ([`conditionalNode`](workflows.md)) | Deterministic branch routing to `complete` or `revise` based on validation criteria. |
-| **Process Revision Loop** | Node Retries / DAG Branching / Loop Node ([`loopNode`](workflows.md)) | Bounded retry/revision path or bounded in-graph loop iteration. |
+| **Process Revision Loop** | Node Retries / DAG Branching / Loop Node ([`loopNode`](workflows.md)) | Bounded retry/revision path, in-graph loop iteration, or cyclic workflow reflection loops with back-edges under `limits.maxSupersteps`. |
+
+## How event-driven swarm topology works
+
+In an event-driven swarm topology, autonomous specialist agents collaborate asynchronously by publishing typed topic events to a central router node (`swarmRouterNode`). The router matches published topics against declared subscriptions and activates matching subscriber agents in wave-based cyclic supersteps:
+
+```mermaid
+flowchart TD
+  Event["Swarm Event Stream (__swarmEvents)"] --> Router["Swarm Router Node (routeNode)"]
+  Router -- "incident:new" --> Triage["Triage Specialist (withNodeScope)"]
+  Router -- "research:security" --> Researcher["Security Researcher (withNodeScope)"]
+  Router -- "verify:patch" --> Verifier["Patch Verifier (withNodeScope)"]
+  Triage -. "publishSwarmEvent(research:security)" .-> Router
+  Researcher -. "publishSwarmEvent(verify:patch)" .-> Router
+  Verifier -. "No further events (Idle Drain)" .-> Success["Workflow Succeeded"]
+```
+
+```ts
+import {
+  defineSwarmWorkflow,
+  functionNode,
+  getSwarmEvents,
+  publishSwarmEvent,
+  runWorkflow,
+  withNodeScope,
+} from "@arnilo/prism-core/runtime/workflows";
+
+// 1. Specialist agents wrapped with withNodeScope maintain isolated working memory
+const triage = withNodeScope("triage", functionNode({
+  execute: async (ctx) => {
+    const events = getSwarmEvents(ctx);
+    const incident = events.find((e) => e.topic === "incident:new");
+    await ctx.updateState({ incidentId: (incident?.payload as { id?: string })?.id });
+
+    // Publish event for downstream specialists
+    await publishSwarmEvent(ctx, {
+      topic: "research:security",
+      sender: "triage",
+      payload: { query: "Analyze CVE impact" },
+    });
+    return "triaged";
+  },
+}));
+
+// 2. Define the swarm with cyclic topic subscriptions and a wave limit
+const swarm = defineSwarmWorkflow({
+  id: "security-swarm",
+  revision: "1",
+  maxSupersteps: 12,
+  agents: { triage, researcher, verifier },
+  subscriptions: {
+    "incident:new": ["triage"],
+    "research:*": ["researcher"],
+    "verify:*": ["verifier"],
+  },
+  initialState: {
+    __swarmEvents: [
+      { topic: "incident:new", sender: "gateway", payload: { id: "INC-8802" } },
+    ],
+  },
+});
+
+const result = await runWorkflow(swarm, null);
+```
+
+Live demo: [`examples/cyclic-swarm-topology.ts`](../examples/cyclic-swarm-topology.ts) — complete triage → security research → patch verification cycle with per-agent state scoping and clean idle-drain termination.
+
+### Core swarm properties
+- **Topic Subscriptions**: Match exact strings (`"ticket:billing"`) or wildcard prefix patterns (`"ticket:*"` or `"*"`).
+- **Two-Phase Queueing**: Pending events are promoted to `__swarmActiveEvents` during the active superstep wave, while newly published events accumulate in `__swarmEvents` for the next wave.
+- **Scoped Working Memory**: `withNodeScope` guarantees agents only read/write their dedicated state slice without risking key collisions across concurrent or cyclic steps.
+- **Deterministic Termination**: The cycle drains cleanly to `status: "succeeded"` as soon as no more events are emitted, protected by `limits.maxSupersteps`.
 
 ## How the in-process spawn tool works
 

package/docs/obscura.md

@@ -13,7 +13,7 @@ the package at it.
 ## Install
 
 ```bash
-npm install @arnilo/prism-web-tools @arnilo/prism-mcp
+bun add @arnilo/prism-web-tools @arnilo/prism-mcp
 ```
 
 ## Process lifecycle (`spawnObscuraProcess`)

package/docs/openapi-tools.md

@@ -53,7 +53,7 @@ Defaults and hard caps (frozen in `scripts/phase11-freeze-manifest.json`): `maxD
 A live wire probe compiles the real public Warnely OpenAPI 3.1 spec (petstore serves 3.0 — the compiler requires 3.1) and drives real GET operations against it:
 
 ```bash
-PRISM_LIVE_OPENAPI_TOOLS=1 node --test packages/prism-coding-tools/dist/openapi/__tests__/live.test.js
+PRISM_LIVE_OPENAPI_TOOLS=1 bun test packages/prism-coding-tools/dist/openapi/__tests__/live.test.js
 ```
 
 3 requests total against the allow-listed public host: spec compile, a real 200 tool call, and a real 404 mapped to a status-carrying untrusted result; a missing-argument case proves validation fails closed locally (zero wire calls). Skips (never fails) when `PRISM_LIVE_OPENAPI_TOOLS` is unset. Registered in `scripts/live-matrix.json` as `coding-tools/openapi-live`.

package/docs/operations.md

@@ -47,7 +47,7 @@ await stores.leases.releaseLease({ namespace: "erp.ops", key: "invoice-42", owne
 # Protected two-replica drill (requires PRISM_TEST_POSTGRES_URL; Docker image
 # postgres:16-alpine is the local stand-in). Recorded evidence lands in
 # docs/_evidence/phase27-ha-evidence.json.
-`PRISM_TEST_POSTGRES_URL` set to the protected connection string (locally a disposable `postgres:16-alpine` container): `node --test scripts/phase27-ha.test.mjs`
+`PRISM_TEST_POSTGRES_URL` set to the protected connection string (locally a disposable `postgres:16-alpine` container): `bun test scripts/phase27-ha.test.mjs`
 ```
 
 The drill: worker A acquires, heartbeats, commits the charge effect into the
@@ -109,7 +109,7 @@ The outbound webhook notifier has an operator-gated live probe against a receive
 
 ```bash
 PRISM_TEST_WEBHOOK_URL=https://ops.example.com/hooks/prism \
-PRISM_TEST_WEBHOOK_SECRET=<at-least-32-byte-shared-key> npm test -w @arnilo/prism-core -- webhooks-live
+PRISM_TEST_WEBHOOK_SECRET=<at-least-32-byte-shared-key> bun run --filter @arnilo/prism-core test
 ```
 
 Probes: one signed delivery to your receiver (verify `x-prism-signature: sha256=<hex>` over the raw body) and a retry-after-5xx leg over a local loopback receiver (500 then 200, signature verified, retries recorded). Bounded to 1 real request + ≤ 2 loopback requests. Registered in `scripts/live-matrix.json` as `core/webhooks-live`.

package/docs/peer-dependencies.md

@@ -11,7 +11,7 @@ Lists every third-party peer a Prism package declares, what importing that peer
 - Debugging a "peer not installed" error from a gated subpath.
 - Auditing which of your already-installed packages a Prism surface will reuse.
 
-Internal `@arnilo/*` peers are not listed here: every first-party package declares a required `@arnilo/prism` peer, and the release gate keeps all internal ranges locked to the cut version. This page covers the **12 third-party declarations across 6 packages**.
+Internal `@arnilo/*` peers are not listed here: every first-party package declares a required `@arnilo/prism` peer, and the release gate keeps all internal ranges locked to the cut version. This page covers the **10 third-party declarations across 6 packages**.
 
 ## Matrix
 
@@ -19,16 +19,16 @@ One row per declaration. `Unlocks` names the subpath whose import reaches the pe
 
 | Peer | Declared range | Optional | Declared by | Unlocks | Install | Network |
 | --- | --- | --- | --- | --- | --- | --- |
-| `zod` | `^3.25.0 \|\| ^4.0.0` | no | `@arnilo/prism-ag-ui` | `./acp` | `npm i zod` | no |
-| `mammoth` | `^1.8.0` | yes | `@arnilo/prism-work` | `./document-reader` | `npm i mammoth` | no |
-| `pdf-parse` | `^2.4.5` | yes | `@arnilo/prism-work` | `./document-reader` | `npm i pdf-parse` | no |
-| `e2b` | `2.49.1` | yes | `@arnilo/prism-coding-tools` | `./security` | `npm i e2b@2.49.1` | yes |
-| `better-sqlite3` | `^13.0.3` | yes | `@arnilo/prism-core` | `./sessions/sqlite`, `./governance/prompts` | `npm i better-sqlite3` | no |
-| `pg` | `^8.23.0` | yes | `@arnilo/prism-core` | `./sessions/postgres`, `./enterprise/postgres`, `./governance/prompts` | `npm i pg` | yes |
-| `@nats-io/jetstream` | `^3.4.0` | yes | `@arnilo/prism-core` | `./sessions/nats` | `npm i @nats-io/jetstream @nats-io/transport-node` | yes |
-| `@nats-io/transport-node` | `^3.4.0` | yes | `@arnilo/prism-core` | `./sessions/nats` | `npm i @nats-io/transport-node` | yes |
-| `@ai-sdk/provider` | `4.0.13` | yes | `@arnilo/prism-providers` | `./ai-sdk` | `npm i @ai-sdk/provider@4.0.13` | no |
-| `playwright-core` | `1.63.0` | yes | `@arnilo/prism-web-tools` | `./browser`, `./obscura` | `npm i playwright-core@1.63.0` | yes |
+| `zod` | `^3.25.0 \|\| ^4.0.0` | no | `@arnilo/prism-ag-ui` | `./acp` | `bun add zod` | no |
+| `@firecrawl/anydoc` | `0.2.4` | yes | `@arnilo/prism-work` | `./document-extraction` | `bun add @firecrawl/anydoc@0.2.4` | no |
+| `mammoth` | `^1.8.0` | yes | `@arnilo/prism-work` | `./document-reader` | `bun add mammoth` | no |
+| `pdf-parse` | `^2.4.5` | yes | `@arnilo/prism-work` | `./document-reader` | `bun add pdf-parse` | no |
+| `e2b` | `2.49.1` | yes | `@arnilo/prism-coding-tools` | `./security` | `bun add e2b@2.49.1` | yes |
+| `pg` | `^8.23.0` | yes | `@arnilo/prism-core` | `./sessions/postgres`, `./enterprise/postgres`, `./governance/prompts` | `bun add pg` | yes |
+| `@nats-io/jetstream` | `^3.4.0` | yes | `@arnilo/prism-core` | `./sessions/nats` | `bun add @nats-io/jetstream @nats-io/transport-node` | yes |
+| `@nats-io/transport-node` | `^3.4.0` | yes | `@arnilo/prism-core` | `./sessions/nats` | `bun add @nats-io/transport-node` | yes |
+| `@ai-sdk/provider` | `4.0.13` | yes | `@arnilo/prism-providers` | `./ai-sdk` | `bun add @ai-sdk/provider@4.0.13` | no |
+| `playwright-core` | `1.63.0` | yes | `@arnilo/prism-web-tools` | `./browser`, `./obscura` | `bun add playwright-core@1.63.0` | yes |
 
 ## Exact pins and why
 
@@ -37,6 +37,7 @@ Two peers are pinned to an exact version instead of a range, because the pin is
 - **`playwright-core@1.63.0`** (`@arnilo/prism-web-tools/browser`, `/obscura`). Browser automation rides Playwright's CDP transport and accessibility snapshot shapes, which move between minors. Prism never launches, downloads, or bundles a browser: the host supplies the binary, the image, and the cache, and must match the pinned client. See [Browser automation](browser-automation.md).
 - **`@ai-sdk/provider@4.0.13`** (`@arnilo/prism-providers/ai-sdk`). The adapter consumes deterministic specification-versioned types (`LanguageModelV4`) and gates on an exact supported-version matrix at construction, so an unlisted version fails closed instead of silently mis-mapping. See [AI SDK provider](providers/ai-sdk.md).
 - **`e2b@2.49.1`** (`@arnilo/prism-coding-tools/security`). Pause `keepMemory`, `Sandbox.connect` auto-resume, and `ServiceBusyError` 503 semantics are version-specific. Hosts may inject `{ client }` instead of installing the peer. See [Hosted sandboxes](hosted-sandboxes.md).
+- **`@firecrawl/anydoc@0.2.4`** (`@arnilo/prism-work/document-extraction`). Error codes and the wrapper's optional third argument were checked against this release. The wrapper can upload a PDF when `ocr` is `'hosted'`; the Prism subpath never passes that argument and does not read an API key.
 
 `zod` is the only **required** third-party peer. `@agentclientprotocol/sdk` — a hard dependency of `@arnilo/prism-ag-ui` — declares `zod: ^3.25.0 || ^4.0.0` as its own peer, so `@arnilo/prism-ag-ui` re-declares the same range to keep the install tree satisfiable; the range is deliberately identical to the SDK's. Nothing in Prism imports zod directly.
 
@@ -45,7 +46,7 @@ Two peers are pinned to an exact version instead of a range, because the pin is
 `pg`, `@nats-io/jetstream`, `@nats-io/transport-node`, `playwright-core`, and `e2b` open sockets. For a supply-chain review of those five:
 
 - **Connection targets are host-owned.** Every one of them is passed a host-supplied connection string, endpoint list, browser instance, API key, or service URL. Prism holds no default endpoint, and no peer is reachable from the root import.
-- **Bytes stay local otherwise.** `better-sqlite3`, `mammoth`, and `pdf-parse` are filesystem/process peers; the remaining two (`zod`, `@ai-sdk/provider`) are pure types/schemas.
+- **Bytes stay local otherwise.** `mammoth`, `pdf-parse`, and `@firecrawl/anydoc` (as called by Prism) are filesystem/process peers; the remaining two (`zod`, `@ai-sdk/provider`) are pure types/schemas. SQLite is the runtime's `bun:sqlite`, not a peer. The anydoc package also ships a hosted-OCR option; `@arnilo/prism-work/document-extraction` does not call it.
 - **No secrets are read by the peers.** Prism resolves credentials through host providers and redacts them at the boundary; peers only ever receive a resolved connection string or model object. See [Credentials and redaction](credentials-and-redaction.md) and [Host security guide](host-security.md).
 - **Nothing is installed implicitly.** Optional peers are never auto-installed by npm; a missing one fails closed at the call site with a typed error naming the peer and the subpath. Required peers (today only `zod`) are installed by npm with the package.
 
@@ -55,16 +56,16 @@ Test-only dependencies are *not* peers. `playwright-core` appears in `@arnilo/pr
 
 ```bash
 # Browser automation: pinned client, host-owned browser binary
-npm i @arnilo/prism-web-tools playwright-core@1.63.0
+bun add @arnilo/prism-web-tools playwright-core@1.63.0
 
 # PostgreSQL session store: pool driver only
-npm i @arnilo/prism-core pg
+bun add @arnilo/prism-core pg
 
 # NATS JetStream event source: transport + jetstream together
-npm i @arnilo/prism-core @nats-io/transport-node @nats-io/jetstream
+bun add @arnilo/prism-core @nats-io/transport-node @nats-io/jetstream
 
 # Document reader: pick the parser you need (both are independent)
-npm i @arnilo/prism-work pdf-parse mammoth
+bun add @arnilo/prism-work pdf-parse mammoth
 ```
 
 ```ts
@@ -91,4 +92,4 @@ const tools = await createBrowserTools({ browser });
 
 - [Release and install](release-and-install.md): install profiles that pair with each peer.
 - [Configuration options index](options-index.md): the option surfaces each peer unlocks.
-- Package-level detail: [Coding tools](coding-tools.md), [Core runtime](core.md), [Session stores](session-stores.md), [Browser automation](browser-automation.md), [Document reader](document-reader.md), [Provider packages](provider-packages.md), [Messaging channels](messaging-channels.md).
+- Package-level detail: [Coding tools](coding-tools.md), [Core runtime](core.md), [Session stores](session-stores.md), [Browser automation](browser-automation.md), [Document reader](document-reader.md), [Document extraction](document-extraction.md), [Provider packages](provider-packages.md), [Messaging channels](messaging-channels.md).