@arnilo/prism 0.7.0 → 0.9.0

package/docs/messaging-channels.md

@@ -0,0 +1,150 @@
+# Messaging channels
+
+## What it does
+
+`@arnilo/prism-channels` provides transport-neutral contracts and the Prism execution adapter for chat transports. A host authorizes an observed sender, binds them to an owned Prism session, and the runtime runs ordinary turns through the existing `AgentSession` API and projects only the current run's final text back to the bound destination.
+
+The root export ships the runtime, contracts, limits and durable journal. The official Telegram adapter ships as `@arnilo/prism-channels/telegram`; experimental Signal support ships as the isolated Node-only `@arnilo/prism-channels/signal` subpath. Durable single-decision approval controls ship now.
+
+Pass `checkpoints` (and optionally `leases`) to make bindings, admission dedup, the claim before provider work and outgoing replies durable; that is the restart-safe deployment. Without a store the runtime keeps bounded in-process state only — still the correct execution/authorization seam, but restart-unsafe. Recovery mechanics, record layout and the operator runbook: [Messaging channel operations](messaging-channel-operations.md).
+
+## When to use it
+
+Use when a host already operates a chat bot (or plans to) and wants selected Prism agents reachable by chat message without building another agent runtime or conversation database. Telegram admits private DMs by default and group/topic text only when the adapter opts in with `allowGroups` and the host grants the exact chat/thread/sender; Signal (experimental) stays direct-message only. Not for media, voice or proactive broadcasting in the current scope.
+
+## Inputs / request
+
+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
+```
+
+## Request/response example
+
+```ts
+import { createMessagingRuntime } from "@arnilo/prism-channels";
+
+const runtime = createMessagingRuntime({
+  // Observed sender + action -> host-verified grant, or `false`.
+  authorize: ({ connectionId, externalActorId, action }) => hostGrants.lookup(connectionId, externalActorId, action),
+  // Authorized alias -> the host-configured agent for the current identity/ownership.
+  resolveAgent: ({ agentAlias, identity, ownership }) => hostAgents.resolve(agentAlias, identity, ownership),
+  // Delivery seam: normally the transport adapter's `send`, or a durable outbox.
+  deliver: (reply) => transport.send(reply),
+  // Optional preview seam: cumulative redacted assistant text while a turn runs (Telegram drafts).
+  onAssistantDelta: (delta) => transport.sendDraft?.(delta),
+  // Optional media seam: normally the adapter's own bounded `fetchAttachment`.
+  // An image becomes model input only when the resolved model declares image input.
+  fetchAttachment: (ref) => transport.fetchAttachment(ref),
+  limits: { maxPendingPerBinding: 4 },
+  redactor: hostRedactor,
+  // Durable journal (optional but required for restart safety): any CheckpointStore/LeaseStore,
+  // for example createMemoryCheckpointStore(), SQLite or PostgreSQL persistence.
+  checkpoints: hostCheckpoints,
+  leases: hostLeases,
+});
+
+// The adapter calls this before acknowledging transport receipt (Telegram offset / webhook 2xx).
+const admission = await runtime.admit(event);
+await runtime.drain({ deadlineMs: 5_000 }); // host shutdown / test settle
+runtime.diagnostics(); // bounded counters, no text or external ids
+await runtime.stop();
+
+// Durable recovery, host-driven and never automatic:
+await runtime.listUnresolved({ identity }); // bounded page: operations still needing attention
+await runtime.reconcile({ identity, connectionId, operationId, expectedVersion, acknowledgeDuplicateRisk: true });
+await runtime.prune({ identity }); // retention sweep; unresolved work is never deleted
+
+// Opt-in host notice to one already-bound pair (no agent run, no tools, no queue):
+// the grant must carry `notifications: true`, `notifyId` is the idempotency key.
+await runtime.notify({
+  identity,
+  connectionId: "telegram-main",
+  externalConversationId: "8241",
+  notifyId: "job-123-done",
+  text: "The nightly job finished.",
+});
+```
+
+## Outputs / response / events
+
+`admit` authorizes first and returns `{ status: "accepted" | "denied" | "unsupported", reason?, operationId?, duplicate? }`. It resolves before any provider call and before the transport acknowledgment; accepted turns then run in the background.
+
+`ChannelInboundEvent` carries only transport-observed fields: `connectionId`, `externalConversationId`, `externalActorId` (stable platform id, never a display name), `eventId` (the transport acknowledgment unit), `text`, optional `threadId`, `attachments`, `claims`, and an adapter-parsed opaque `approval` control. `claims` and transport ids are untrusted context for the host callback only — never authority.
+
+`attachments` are bounded `ChannelAttachmentRef` values (`kind: "image" | "document" | "voice"`, transport file id, optional mime/size/name) — identifiers, never bytes and never model-selected. Voice and document become turn text in the adapter through host hooks (`transcribe`, `extractDocumentText`); only an `image` can become model input, and only when the resolved agent's model declares `image` input *and* the host wired `MessagingRuntimeOptions.fetchAttachment` (normally the adapter's `fetchAttachment`). Then the runtime fetches the current event's refs once, bounded by the channel cap, builds one image content block per ref next to the text, and stores nothing: an undeclared modality, a missing seam or a failed fetch produces `unsupported_media` with a bounded notice and no provider call. Declared attachment bytes above `maxAttachmentBytes` are denied (`reason: "oversized"`) before any fetch.
+
+`MessagingRuntimeOptions.onAssistantDelta` is the optional outbound preview seam: while a turn runs, the runtime forwards the cumulative assistant text of the current message, already redacted with the reply `redactor`, as `ChannelAssistantDelta` (`connectionId`, `externalConversationId`, optional `threadId`, `text`). It fires once per streamed text chunk, only for turns that actually reach the provider, stops at cancel or `stop()`, and resets per assistant message so a tool-call preamble never leaks into the following answer. It is not a reply: nothing is journaled, delivery is not tracked, a throwing callback is ignored, and the terminal `ChannelReply` is unchanged. An adapter that has no preview capability simply ignores it.
+
+`MessagingRuntime.notify` is the opt-in reverse direction: the host sends a `notice` (never a `final`) to one already-bound conversation/thread pair, without a model run, a tool call or a queue slot. It takes `identity`, the bound destination and a caller `notifyId`; the grant must be re-checked with `action: "notify"` and carry `notifications: true`, and `notifyId` is the idempotency key (`duplicate: true` on repeat). The notice is redacted, bounded by the reply cap, journaled as an operation of kind `notify` and staged through the same reply journal as an answer — so a crash between the answer and the send never turns into a silent notice and never re-runs anything. There is no broadcast or fan-out input: an unbound pair, another actor's binding, a foreign ownership scope, an ungranted or revoked identity and an unresolvable binding all fail closed with a bounded `reason`.
+
+## Implementation example
+
+Network-free host composition: [`examples/messaging-agent.ts`](../examples/messaging-agent.ts). Telegram: [`examples/telegram-agent.ts`](../examples/telegram-agent.ts). Experimental Signal: [`examples/signal-agent.ts`](../examples/signal-agent.ts).
+
+## Security and performance notes
+
+### Authorization
+
+- `authorize` receives the bounded text and action (`"message"`, `"command"`, or `"approval"`) and must return a host-verified `AgentIdentity` (`verified: true`, non-empty scopes, unexpired, unrevoked) plus permitted `agentAliases` and a `grantRevision`. Anything else fails closed with a bounded `reason` and no provider call.
+- Ownership is always derived with `ownershipFromIdentity`; the event, message text and `claims` cannot set or widen it. The run receives the verified `identity` and the runtime never passes a `per-run ownership` override, so `createSecureAgent` defaults cannot be replaced by a channel adapter.
+- Every turn re-checks the grant and `assertIdentityActive` before provider work and before delivery: a revoked identity neither runs nor sends, and no reply is sent after revocation.
+- Unknown aliases, malformed ids, oversized text, ungranted senders and capacity pressure are denied without provider or tool calls. Cross-tenant errors stay bounded and never reveal whether a foreign session exists.
+- **Media boundary.** Attachment refs are validated (count, ids, metadata, safe-integer sizes) and malformed refs are denied `malformed`; sizes above `maxAttachmentBytes` are denied `oversized` before a fetch. The runtime fetches only refs of the event it is running and passes bytes straight into one run call — the same address the model cannot influence. Nothing media-shaped is written to the journal or the delivery seam: operation and reply records stay text-only, and an attachment the host did not opt into produces a bounded notice rather than a prompt-injection surface.
+
+### Execution semantics
+
+- **Binding.** Connection + conversation + thread + actor + alias maps to a deterministic owned session id (`chan-<sha256 prefix>`); the host may supply `resolveBinding` to persist its own mapping. Same display name on another connection or tenant is a different session; `/new` starts a fresh session for the current binding. With `checkpoints`, the binding — including the `/new` generation, the branch leaf and a suspended marker — is journaled and reused after a restart.
+- **Serialization.** Turns are serialized per logical session id and bounded per binding, per process and by active-session concurrency. Core sessions do not serialize two runtime objects that share an id, so a channel-only mutex is not shared-session arbitration: if another API can drive the same session, use a shared host admission/lease mechanism instead.
+- **Host notices.** `notify` never allocates a binding or a route and never touches the turn queue; it requires an existing binding and re-checks identity, ownership, the `notifications: true` grant flag and the bound alias on every call. When the host has more than one binding for the same pair (the conversation moved alias), the current selection is addressed and anything ambiguous fails closed. Notices count against `maxPendingPerProcess` and reuse the staged-reply path, so a delivery failure is recorded rather than retried.
+- **Output.** Only the current run's terminal `succeeded` text is delivered. Failed, aborted or suspended runs send a bounded notice (redacted), never a previous turn's text and never partial deltas. Responses are truncated to the channel response cap.
+- **Cancellation.** `/cancel` aborts an active run via its `AbortSignal` and marks queued turns cancelled. For a suspended durable run it submits core's CAS-checked terminal denial; an already dispatched tool is never rolled back. Transport disconnection is not user cancellation; `stop()` marks queued turns cancelled and aborts active runs on host shutdown.
+- **Suspension and approval.** A suspended tool decision blocks ordinary turns (`reason: "awaiting_decision"`) and `/new` cannot bypass it. The runtime persists two short-lived opaque controls for the first pending tool decision: `allow_once` and `reject_once`. Each is bound to exact principal, connection, conversation/thread, agent alias/revision, session, run, approval id and checkpoint version. It is consumed atomically before resume; stale, expired, forwarded, replayed or revoked controls fail closed. Resume reauthorizes the sender and resolves current agent policy before core dispatches the decision. Subsequent pending decisions re-suspend and issue fresh controls. Unsupported elicitation stays blocked for authenticated host handling.
+- **Controls.** `/help`, `/status`, `/new`, `/agent <alias>` and `/cancel` are the only ordinary commands. `/status` reports only the bound operation state; controls bypass the prompt queue. The experimental Signal adapter maps `/approve <token>` and `/deny <token>` to the same opaque records. Any other slash input (including registry/config mutation) never reaches a model.
+- **Durable intake.** With `checkpoints`, every authorized event is recorded before it is acknowledged, deduplicated by connection + event id across processes, and moved `accepted` → `executing` by a compare-and-swap claim *before* the provider is called. A duplicate event is acknowledged with `duplicate: true` and never runs twice; a denial leaves no record behind, so a legitimate retry still works.
+- **Durable replies.** A reply is persisted before `deliver` runs, so a crash between the answer and the send never loses it and never reruns the model. An ambiguous send (`deliver` threw) is recorded as `delivery_unknown` and is never resent automatically; only an authorized `reconcile` call with an explicit `acknowledgeDuplicateRisk` resends the persisted text.
+- **Crash truth.** A claimed operation whose process died stays unresolved and is never replayed; `reconcile` files it as `execution_unknown`, which is a dead-letter for host review, not a retry. There is no exactly-once claim: side effects already accepted by the platform (or already dispatched tools) are not retractable.
+
+## Extension and configuration notes
+
+`resolveChannelLimits` rejects `ChannelLimits` values outside `[1, hard cap]`.
+
+| Limit | Default | Hard cap |
+| --- | --- | --- |
+| `maxInputBytes` | 32 KiB | 64 KiB |
+| `maxResponseBytes` | 64 KiB | 128 KiB |
+| `maxPendingPerBinding` | 8 | 32 |
+| `maxPendingPerProcess` | 100 | 500 |
+| `maxActiveSessions` | 4 | 16 |
+| `maxRoutes` | 1000 | 10000 |
+| `maxSeenEventsPerConnection` | 1000 | 10000 |
+| `stopDeadlineMs` | 30 s | 5 min |
+| `retentionDays` | 7 | 90 |
+| `maxJournalPage` | 100 | 500 |
+| `maxJournalRecordBytes` | 128 KiB | 512 KiB |
+| `leaseTtlMs` | 30 s | 5 min |
+| `approvalTtlMs` | 5 min | 5 min |
+| `maxAttachmentBytes` | 1 MiB | 4 MiB |
+
+Capacity pressure fails admission (`reason: "capacity"`) instead of evicting accepted work, and an unusable journal fails admission with `reason: "unavailable"` rather than running unclaimed work. Without `checkpoints` the in-process seen-event set is bounded and is not a durable deduplication guarantee.
+
+## Telegram
+
+Use [`@arnilo/prism-channels/telegram`](telegram-channel.md) for explicit long polling or a separately mounted webhook handler. Both require a service-owned receiver lease; polling also persists its offset after `admit` settles. The adapter uses only native `fetch`, resolves the bot token at each transport request, never follows redirects, sends plain text in Unicode-safe chunks, and records timeout/network sends as ambiguous so the durable reply journal never blindly resends them. Private DMs are the default; `allowGroups: true` adds `group`/`supergroup` text (forum topics keep their topic id as `threadId`) and only ever hands observed `(chat, thread?, sender)` tuples to the host `authorize` — membership is never an identity.
+
+## Signal (experimental)
+
+Use [`@arnilo/prism-channels/signal`](signal-channel.md) only with an externally supervised, pinned signal-cli v0.14.8 private Unix socket and an explicit operator acceptable-use/GPL policy attestation. It admits only direct UUID text envelopes after durable writer readiness, pauses on account/storage/lease trouble, sends only to the authorized bound UUID, and does not claim lossless receive or end-to-end encryption through Prism/model providers. Group envelopes are always dropped (no Signal group or topic support).
+
+A network-free host composition is `examples/messaging-agent.ts` (sqlite journal, mock agent, `drain`/`stop`). Telegram polling/webhook helpers live in `examples/telegram-agent.ts`; the experimental Signal helper is `examples/signal-agent.ts`. Opt-in live probes skip without credentials — see [Live and end-to-end testing](live-testing.md).
+
+## Related APIs
+
+- [Telegram channel](telegram-channel.md) — polling, webhook mounting, credentials, limits and failure behavior.
+- [Signal channel (experimental)](signal-channel.md) — daemon prerequisites, policy gate, manual subscription and reliability limits.
+- [Messaging channel operations](messaging-channel-operations.md) — durable records, recovery, reconciliation and the operator runbook.
+- [Agent session runtime](agent-session-runtime.md) — `AgentSession.run`, results, interruption and resume.
+- [Agent identity](agent-identity.md) — `AgentIdentity`, `IdentityVerifier`, ownership projection.
+- [Host security](host-security.md) — host-owned authority and side-effect policy.
+- [Package README](../packages/prism-channels/README.md) — package boundary and peer-only install.

package/docs/middleware-hooks.md

@@ -14,7 +14,7 @@ APIs:
 
 Use middleware hooks when a host wants extension/package code to observe or transform a value at a named runtime boundary.
 
-Do not use middleware hooks as a provider adapter, prompt builder, retry policy, compaction strategy, tool dispatcher, permission system, or agent/session runtime.
+Do not use middleware hooks as a provider adapter, prompt builder, retry policy, compaction strategy, tool dispatcher, permission system, or agent/session runtime. Per-turn tool menus use `AgentConfig.toolNarrowing` / `RunOptions.toolNarrowing`, not a middleware hook — see [Tools](tools.md).
 
 ## Inputs / request
 
@@ -24,6 +24,7 @@ createMiddlewareRegistry(options?: MiddlewareRegistryOptions): MiddlewareRegistr
 
 Built-in hook names:
 
+- `beforeProviderTurn`
 - `provider_request`
 - `input_assembly`
 - `prompt_build`
@@ -47,7 +48,7 @@ Built-in hook names:
 
 ## Outputs / response / events
 
-`run()` returns the transformed value. If no middleware is registered for a hook, `run()` returns the original value. `assembleProviderInput()` calls Phase 5 hooks in this order when middleware is supplied: `input_assembly`, then `context`, then `prompt_build`. The `input_assembly` call is unconditional — it runs after whatever `InputBuilder` produced the messages, so host middleware at that hook cannot be skipped by a custom builder. The agent/session runtime applies configured provider request policies, then invokes `provider_request` once with the `ProviderRequest` before `AIProvider.generate()`, invokes `tool_call` and `tool_result` through `dispatchToolCall()` for complete provider tool calls, invokes `compaction` with `{ context, result }` after a compaction strategy returns and before the runtime appends its standard compaction entry, and invokes `retry` with `{ context, decision }` before scheduling a provider-turn retry. There is no `provider_response` hook; observing provider output belongs to the provider adapter or subscriber events.
+`run()` returns the transformed value. If no middleware is registered for a hook, `run()` returns the original value. `assembleProviderInput()` calls Phase 5 hooks in this order when middleware is supplied: `input_assembly`, then `context`, then `prompt_build`. The `input_assembly` call is unconditional — it runs after whatever `InputBuilder` produced the messages, so host middleware at that hook cannot be skipped by a custom builder. The agent/session runtime runs `beforeProviderTurn` once per turn after the request is assembled and before any provider-round work, then applies configured provider request policies, then invokes `provider_request` once with the `ProviderRequest` before `AIProvider.generate()`, invokes `tool_call` and `tool_result` through `dispatchToolCall()` for complete provider tool calls, invokes `compaction` with `{ context, result }` after a compaction strategy returns and before the runtime appends its standard compaction entry, and invokes `retry` with `{ context, decision }` before scheduling a provider-turn retry. There is no `provider_response` hook; observing provider output belongs to the provider adapter or subscriber events.
 
 With default `errorPolicy: "event"`, middleware errors become `extension_error` events when `onError` is provided, and later middleware still runs with the current value. With `errorPolicy: "throw"`, `run()` rejects on the first middleware error.
 
@@ -92,11 +93,45 @@ export const extension: Extension = {
 };
 ```
 
+## No-model turns (`beforeProviderTurn`)
+
+`beforeProviderTurn` lets the host answer a turn from data it already has — teaching empty states, canned flows, deterministic lookups — without any provider request. The payload is `BeforeProviderTurnPayload` (`sessionId`, `runId`, `turn`, `userText`) and middleware returns it unchanged or with `answer: DeterministicTurnAnswer` set:
+
+```ts
+export interface DeterministicTurnAnswer {
+  readonly content: readonly ContentBlock[];
+  readonly provenance: { readonly middleware: string };
+}
+```
+
+```ts
+import { createAgent, createMiddlewareRegistry, type BeforeProviderTurnPayload } from "@arnilo/prism";
+
+const DESK_ANSWERS = new Map([["what can you do?", "I answer from local records; ask about an order id."]]);
+const middleware = createMiddlewareRegistry();
+middleware.use<BeforeProviderTurnPayload>("beforeProviderTurn", (payload, next) => {
+  const text = DESK_ANSWERS.get(payload.userText);
+  return text ? { ...payload, answer: { content: [{ type: "text", text }], provenance: { middleware: "desk" } } } : next(payload);
+});
+
+const session = createAgent({ model, provider, middleware }).createSession();
+await session.run("what can you do?"); // no provider call; assistant message recorded
+```
+
+Contract:
+
+- Returning the payload without `answer` (or returning `undefined`) sends the turn to the provider exactly as if the hook were absent.
+- `answer.provenance.middleware` is mandatory and validated as a bounded id (1–64 chars: letters, digits, `.` `_` `:` `-`); a deterministic turn can never masquerade as model output.
+- `answer.content` accepts assistant-visible content blocks (`text`, `image`, `audio`, `file`, `document`, `video`, `thinking`). Tool-call blocks are rejected — no provider ran to authorize a call — and an empty block array throws `DeterministicTurnError` (`ERR_PRISM_DETERMINISTIC_TURN`), failing the run closed instead of falling through to the provider.
+- Content passes the same output guardrails as provider output and is charged against `maxResponseBytes`, but the turn records no usage: usage is absent, never zero, and the run timeline shows a `deterministic` step named after the answering middleware.
+- Provenance persists: the assistant message carries `metadata.deterministic = { middleware }`, so a transcript loaded back from any session store still proves the turn had no model behind it. `summarizeTimeline()`/`summarizeSession()` report `turns: { model, deterministic }`, and `createDeterministicTurnScorer()` (from `@arnilo/prism-core/governance/evals`) grades a trajectory for no-model coverage — failing a turn that both answered deterministically and still issued a provider request.
+
 ## Extension and configuration notes
 
 - Middleware registration is explicit through `createMiddlewareRegistry()` or `ExtensionAPI.use()`.
 - `provider_request` middleware sees generic `ProviderRequest.options` after request policies have run; do not add secrets unless a redactor/policy secret list covers that boundary.
 - Middleware runs only when the host/runtime calls `run()` or passes the registry to a helper that documents a call site.
+- `beforeProviderTurn` runs only for turns that reach the provider boundary; a turn already ended by a run limit, host turn policy, or durable suspension never reaches it, and host middleware is trusted code — it must not use the hook to bypass `RunLimits` or guardrails.
 - `compaction` middleware may adjust the compaction result summary/data, but runtime still owns session store append ordering and branch parent ids.
 - `retry` middleware may stop retrying or adjust delay, but runtime still owns retry event emission, abort-aware waiting, and provider-turn boundaries.
 - The registry does not discover packages, read manifests, load config, call providers, execute tools, read resources, or start sessions.
@@ -112,6 +147,7 @@ export const extension: Extension = {
 
 ## Related APIs
 
+- [Middlewares vs restore hooks](durable-runs.md#restore-hooks-all-or-nothing): middleware transforms payloads at named boundaries; `restoreHooks` restore external state before a durable resume and are not middleware.
 - [Extension kernel and event bus](extensions.md): `ExtensionAPI.use()` and shared error policy.
 - [Contribution registries](contribution-registries.md): direct contribution registration separate from middleware.
 - [Agent/session runtime](agent-session-runtime.md): provider request policy/middleware timing, bounded tool loop call site for `tool_call`/`tool_result` hooks, and runtime call sites for `compaction` and `retry`.

package/docs/migrate-to-0.8.md

@@ -0,0 +1,124 @@
+# Migrate Prism 0.7 to 0.8
+
+> **Status: 0.8.0** (messaging channels, connected apps, work family, durable runs).
+
+This document details migration steps, breaking import-map changes, and compatibility notes for upgrading from Prism 0.7.0 to 0.8.0.
+
+---
+
+## Security Tightenings and Breaking Behavioral Changes
+
+### 1. Work family package move (the only import-map break)
+
+`@arnilo/prism-office` is removed with no pre-1.0 shim. Install `@arnilo/prism-work` next to `@arnilo/prism` and rewrite imports:
+
+| Old import | Replacement |
+| --- | --- |
+| `@arnilo/prism-office/documents` | `@arnilo/prism-work/documents` |
+| `@arnilo/prism-office/sheets` | `@arnilo/prism-work/sheets` |
+| `@arnilo/prism-office/diagrams` | `@arnilo/prism-work/diagrams` |
+| `@arnilo/prism-core/integrations/work` | `@arnilo/prism-work/connectors` |
+| `@arnilo/prism-core/integrations/work/microsoft365` | `@arnilo/prism-work/connectors/microsoft365` |
+| `@arnilo/prism-core/integrations/work/google-workspace` | `@arnilo/prism-work/connectors/google-workspace` |
+| `@arnilo/prism-core/integrations/work/drafts` | `@arnilo/prism-work/connectors/drafts` |
+| `@arnilo/prism-coding-tools/document-reader` | `@arnilo/prism-work/document-reader` |
+
+`createReadTool({ documentReader })` is unchanged: pass a reader from the new subpath. Core keeps the durable adapter at `@arnilo/prism-core/enterprise/postgres` (`createPostgresEnterpriseState({ pool }).workIdempotency`) with type-only structural coupling.
+
+**Match work-idempotency conflicts by `code`, not by error class.** Portable codes stay `ERR_PRISM_WORK_IDEMPOTENCY` and `ERR_PRISM_WORK_IDEMPOTENCY_CONFLICT`. `createMemoryIdempotencyStore()` throws `WorkToolError`; the PostgreSQL adapter throws `EnterprisePostgresError` because `@arnilo/prism-core` cannot depend on `@arnilo/prism-work` at runtime.
+
+#### Migration Actions
+- Replace every `@arnilo/prism-office` and `integrations/work` / coding-tools `document-reader` import with the table above.
+- Catch work-idempotency by `error.code`.
+- Install `@arnilo/prism-work@^0.8.0` (it is one of the eleven lockstep packages).
+
+### 2. Observational-memory workers stay tool-only
+
+Workers (`observer` / `dropper` / `reflector`) keep only `tool_call` provider events. A text-only, thinking-only, or done-only turn is a **successful no-op**: no ledger write from that turn. Mixed text+tools keep the tools. Limit and unknown-tool failures throw `MemoryError` / `MemoryLimitError` (`code`), not an English-prefix match.
+
+#### Migration Actions
+- Do not expect assistant prose from a worker turn to become an observation.
+- Catch worker-limit failures with `instanceof MemoryError` (or `MemoryLimitError`) / `error.code`, not message prefix.
+
+### 3. Channel lease release is fail-closed
+
+`createMessagingRuntime` clears an in-memory route lease only after the lease store acknowledges `releaseLease`. A store throw increments `storageFailures`, leaves the token on the route, and retries on the next idle/`stop` path. TTL remains the cross-process backstop. An already-delivered reply is not rolled back.
+
+#### Migration Actions
+- Treat a failed release as “this process still holds the binding,” not as free.
+- Do not log lease tokens.
+
+### 4. AG-UI input authority is opt-in server-side
+
+`CreateAgUiHandlerOptions.inputPolicy.clientState: "ignore"` validates then discards client-supplied AG-UI state and tools before projection, and stops advertising client-provided tools. Default `"honor"` is byte-identical to 0.7.0.
+
+#### Migration Actions
+- Hosts that must not trust the browser for tools/state set `inputPolicy: { clientState: "ignore" }`.
+- Leave the default if the 0.7.0 honor path is intended.
+
+### 5. Checkpoint foreign-scope reads no longer leak existence
+
+A checkpoint or agent-run status load under a foreign ownership scope is a miss (or a generic CAS conflict), not a distinct “exists but not yours” error. `ERR_PRISM_AGENT_RUN_STATE` covers a missing run and a foreign-scope read.
+
+#### Migration Actions
+- Stop catching `Checkpoint ownership mismatch` (or equivalent) as an existence signal.
+
+---
+
+## Additive surfaces (inert unless wired)
+
+### 6. Messaging channels (`@arnilo/prism-channels`)
+
+New eleventh publishable package. Transport-neutral runtime: deny-by-default sender authorization, owned session binding, serialized turns, current-run replies, one-use durable approvals, bounded attachment refs. Official Telegram adapter (private DMs; opt-in granted groups/topics; opt-in streaming drafts in private chats; bounded media; optional voice transcription/synthesis; opt-in notices to one already-bound pair). Experimental Signal adapter (pinned signal-cli, explicit policy gate, UUID DM filtering). See [messaging channels](messaging-channels.md), [Telegram](telegram-channel.md), [Signal](signal-channel.md), [operations](messaging-channel-operations.md).
+
+#### Migration Actions
+- Install `@arnilo/prism-channels@^0.8.0` only if the host wants a messaging ingress. Omitted, 0.7.0 hosts are unchanged.
+- Host `authorize` stays deny-by-default. Group/topic traffic requires an explicit grant.
+
+### 7. Connected apps and work HTTP
+
+Identity-bound MCP connected-app sessions admit host-selected transports and register prefixed tools. Google Workspace and Microsoft 365 HTTP adapters live under `@arnilo/prism-work/connectors`. Slack MCP wrap and Open Connector sidecar remain examples, not core. See [connected apps](connected-apps.md) and [work connectors](work-connectors.md).
+
+#### Migration Actions
+- Wire `connected-apps` only with a host allow-list. Do not add Open Connector / Klavis / Nango as Prism dependencies.
+
+### 8. Durable long runs
+
+`AgentRunStateOptions.checkpointPolicy: "every-turn"` checkpoints at the provider-turn boundary. Host-only `decision: "continue"` resumes a crashed worker (never from AG-UI or the server boundary; rejected while an approval or ready tool call is pending). `RunOptions.turnPolicy` stops at a turn boundary with `stopReason: "host_policy"`. `snapshotRunBundle` returns a frozen redacted digest with zero store or network reads. `createClaimGroundingGuardrail` (stage `"output"`) blocks or flags numeric claims that no tool result or host evidence supports. `ErrorInfo.failureClass` types provider failures; `ModelCapabilities.toolCallStrictness` is advisory. See [durable runs](durable-runs.md), [run bundle](run-bundle.md), [guardrails](guardrails.md).
+
+#### Migration Actions
+- Omit `checkpointPolicy` / `turnPolicy` / the claim-grounding guardrail to keep 0.7.0 run behavior.
+- `"continue"` is a host decision, not a client action.
+
+### 9. Work sandbox and vendored skills
+
+`@arnilo/prism-work/sandbox` plus `createWorkComposition` run office/exec in an injected Docker sandbox; connectors stay on the host. The package ships `docx`, `xlsx`, `powerpoint`, `pdf` skills. See [work sandbox](work-sandbox.md) and [context and skills](context-and-skills.md).
+
+---
+
+## 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**.
+- Coverage artifact keys must equal live workspace package names (`@arnilo/prism-work`, not `@arnilo/prism-office`).
+
+## Upgrade steps
+
+1. Bump every `@arnilo/*` dependency and peer to `^0.8.0` (all **eleven** manifests cut together; a range that only *satisfies* 0.8.0 is refused by the release gate). The published predecessor is 0.7.0.
+2. If the host imported `@arnilo/prism-office` or `integrations/work` / coding-tools `document-reader`, apply §1 before building.
+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.
+
+## Rollback
+
+Pin the previous published line: `@arnilo/prism@0.7.0` and its siblings, exact pins per package. A 0.7.0 host does not load `@arnilo/prism-channels` or `@arnilo/prism-work`. Channel journal rows and work-package files written under 0.8.0 are invisible to 0.7.0, not rewritten. Session/checkpoint schema is unchanged across 0.7.0 → 0.8.0, so a pin rollback is store-safe for those adapters. Restore `@arnilo/prism-office` only from a 0.7.0 install — that package name is gone on 0.8.0.
+
+Back up channel journals and work-sandbox volumes before a rollback if those 0.8.0 stores hold data you intend to keep.
+
+## Related APIs
+
+- [Migration guide](migration.md): the era index of migration cuts with replacement tables and rollback notes.
+- [Migrate Prism 0.6 to 0.7](migrate-to-0.7.md): ACP MCP allow-list, model-router facade refusals, host-completeness additions.
+- [Release and install](release-and-install.md): packed surfaces, install rules, support matrix, and the offline test budget.
+- [Messaging channels](messaging-channels.md), [Connected apps](connected-apps.md), [Work tools](work-tools.md), [Durable runs](durable-runs.md): owning pages for the 0.8.0 additions.

package/docs/migrate-to-0.9.md

@@ -0,0 +1,210 @@
+# Migrate Prism 0.8 to 0.9
+
+> **Status: 0.9.0** (attention budget axes, turn traces, cache-stable disclosure, per-turn tool narrowing, guardrail packs, background agents, checkpoint metadata, session search, deterministic turns, shared work scopes).
+
+This document details migration steps, behavioral changes, and compatibility notes for upgrading from Prism 0.8.0 to 0.9.0.
+
+0.9.0 is a lockstep minor for all **eleven** publishable packages. Node `>=22` stays the floor. **Nothing was removed**: no import path moved, no export was dropped, and every new surface defaults to 0.8 behavior — a host that only moves its dependency ranges keeps 0.8 request bytes, stores, and tool lists. The four deltas below sit inside existing surfaces, so they are readable without opting into anything.
+
+---
+
+## Behavior changes inside existing surfaces
+
+### 1. A limit death delivers three records, and only the last one is terminal
+
+`run_limit_exceeded` was treated as terminal by the in-memory, NATS, and Postgres event sources and by AG-UI replay, so a consumer that stopped at the first breach record ended one record early — before the `budget_exhausted` attribution and before the run's terminal `error`. The terminal set is now exactly `agent_finished`, `agent_denied`, and `error`, decided by one exported predicate that every stream-ending site shares.
+
+```ts
+// before — the stream could end on the breach record
+for await (const item of source.subscribe({ ... })) {
+  if (item.record.type === "run_limit_exceeded") break; // missed budget_exhausted and the error
+}
+
+// after — the breach and its attribution are not terminal; the error is
+for await (const item of source.subscribe({ ... })) {
+  if (isTerminalAgentEventType(item.record.type)) break; // ends on the run's error
+}
+```
+
+**Migration actions**
+- Keep reading past `run_limit_exceeded` and `budget_exhausted`; the stream ends on `error`. A consumer that wants the attribution reads until `isTerminalAgentEventType(type)` is `true` (or the iterator ends).
+- No configuration, no flag: this is the shipped delivery contract for pages, subscriptions, and replays. See [Agent events § Durable AgentEventSource](agent-events.md#durable-agenteventsource).
+
+### 2. `provider_turn_finished` carries stop reason, budgets, tools, and cache metrics
+
+The turn event gains attributed metadata: `stopReason` from one closed taxonomy (`end_turn`, `tool_calls`, `max_output_tokens`, `content_filter`, `abort`, `provider_error`, `unknown`), a `budgets` snapshot (`inputTokens?`, `inputCap?`, `runInputBudget?`, `runInputUsed`, `turns`, `maxTurns`), the effective tool menu as counts plus `tools.idsHash`, and provider-reported `cache` counts (`cacheReadTokens?`, `cacheWriteTokens?`, `hitRate?`). `agent_finished` carries the run-level `finishReason`/`stopDetail`, `AgentRunResult.stopReason` names host-policy and loop-ceiling stops, and the execution timeline adds `turns[i].stopReason` plus `timeline.exhaustion`.
+
+```ts
+source.subscribe({ ... }); // each provider_turn_finished.metadata:
+// { latencyMs, stopReason: "tool_calls", budgets: { runInputUsed: 43_000, turns: 3, maxTurns: 16 }, tools: { count: 7, idsHash: "sha256:…" } }
+```
+
+**Migration actions**
+- Consumers that deep-equal `metadata` (or reject unknown keys) must allow the new fields; consumers that read specific keys are unaffected.
+- Read `metadata.cache` only when present — unknown cache usage stays absent rather than zero-filled.
+
+### 3. Progressive disclosure is cache-stable
+
+Late-expanding context (skill bodies, deferred tool schemas, loaded references) now lands at cache-stable positions: the request tail, or an explicit documented invalidation of the segment that changed. The default group order and the catalogs' slot are unchanged, so a host that never loads late context sends the same bytes as 0.8; hosts that do get append-only growth instead of a rewritten prefix.
+
+```ts
+// assert it against your own assembly (fixture provider, network-free, no keys)
+await runPrefixStabilityConformance({ agent, minContinuity: 0.95 }); // ≥95% shared serialized prefix per turn
+```
+
+Sizing: measured 100% / 95.7% / 95.8% shared prefix on the padded fixture for three consecutive requests; `minContinuity` defaults to `0.95` and is checked over messages **and** tool schemas. Cache reads/writes and per-turn hit rate are now recorded on usage records and `provider_turn_finished.metadata.cache`. See [Prefix stability conformance](prefix-stability-conformance.md) and [Provider caching](provider-caching.md).
+
+### 4. A provider that reports no usage is charged a labeled estimate
+
+A usage-less provider used to contribute zero tokens. `AgentConfig.usageEstimation` now defaults to `"fallback"`: one labeled `TokenEstimate` is recorded at the existing usage seam, and the label survives everywhere the number goes.
+
+```ts
+const meter = session.contextMeter();
+// { inputTokens: 43_000, source: "estimated", inputCap: 200_000, runInputBudget: 500_000, usedRatio: 0.215 }
+const estimate = estimateMessageTokens(messages, "claude-sonnet-4.5"); // { tokens, confidence: "medium" | "low", … }
+```
+
+**Migration actions**
+- Billing or reporting code must read the `estimated` flag (and `confidence`) rather than treating every usage row as provider truth; reported usage always wins and is never overwritten.
+- Set `usageEstimation: "off"` to keep the 0.8 zero-for-no-usage behavior. Estimates charge the token counters for usage-less vendors but never a price, so a configured `maxCost` stays fail-closed.
+
+---
+
+## Additive surfaces (inert unless wired)
+
+### 5. Attention budget axes and durable folding
+
+`attentionCompiler.trigger` replaces the single `triggerRatio` gate with one axis, a predicate, or an any-of array: `{ kind: "input_ratio", ratio }` (the legacy axis), `{ kind: "run_input_ratio", ratio }` (fires against `RunLimits.maxInputTokens` — the case that used to be inert when the run cap sat below the model window), `{ kind: "token_floor", tokens }`, and a predicate function. Omitted, `triggerRatio` (default `0.75`) is the only axis and behavior is byte-identical to 0.8.
+
+```ts
+const attention = createAttentionCompiler(
+  { trigger: [{ kind: "run_input_ratio", ratio: 0.75 }, { kind: "token_floor", tokens: 120_000 }], durable: true },
+  { model, runInputBudget: limits.maxInputTokens },
+);
+```
+
+Sizing: one session-store write per fold (not per turn); folding stays default-off, and `durable: true` requires a checkpoint store (`runState`) or the run throws `AgentRunStateError` before its first provider turn. See [Attention compiler](attention-compiler.md).
+
+### 6. Per-turn tool narrowing
+
+`AgentConfig.toolNarrowing` / `RunOptions.toolNarrowing` (run wins) is a host callback invoked before each provider turn: it receives `{ turn, lastAssistantText?, toolIds }` and must return a subset of the run grant. Extra or unknown names are dropped — the runtime emits `tool_narrowing_clamped` with the dropped names — and a throw fails the turn instead of sending a partial schema.
+
+```ts
+await session.run("fix the failing test", {
+  toolNarrowing: async ({ turn, toolIds }) => (turn > 2 ? toolIds.filter((id) => id === "read" || id === "edit") : toolIds),
+});
+```
+
+Sizing and cache cost: changing the toolset rewrites provider schemas, so pair narrowing with tool search or deferred disclosure (where the tail contract above applies), and read menu identity from `provider_turn_finished.metadata.tools.idsHash` — identical consecutive subsets keep the same hash. Absent callback: 0.8 menu, byte-identical. See [Tools](tools.md).
+
+### 7. Guardrail packs
+
+`AgentSessionConfig.guardrailPacks` (or `compileGuardrailPacks(refs)` for hosts that dispatch tools directly) compiles declarative, restrictive-only rule sets onto the tool stages once per session. Four built-ins ship: `coding-standard` (`no-unrelated-file-edits`, `no-test-rewrites`), `destructive-commands`, `validation-respect`, and `secrets-hygiene`. Every pack ships a trajectory scorer (`createGuardrailPackScorer`) so enforcement can be graded, and pack denials are attributed as `pack:<pack>/<rule>`.
+
+```ts
+const agent = createAgent({ /* … */, session: { guardrailPacks: ["secrets-hygiene", "destructive-commands"] } });
+// compiled from existing seams: interruptBeforeTool, the extension kernel, enforceExecutionPolicy
+```
+
+Sizing: `guardrailPacks` accepts at most 8 packs and 64 rules per pack; containment in `coding-standard` is lexical (`options.roots` defaults to `[process.cwd()]`, symlinks are not resolved), so an `ExecutionPolicy` stays the hard boundary. See [Guardrails](guardrails.md#guardrail-packs).
+
+### 8. Background (session-lifetime) child agents and child-event passthrough
+
+`delegate` / `delegateAsync` / `spawn_agent` accept `lifetime: "session"`, `report: "on-complete" | "milestones" | "stream"`, `milestone`, and `budgetShare`; a host `SupervisorChild.policy` sets the ceiling and a model request can only narrow it (report is clamped, `everyTurns` can only be raised, share takes the lower value, session lifetime must be host-enabled). Session-lifetime children survive caller turns until `cancel_agent` / `cancel(delegationId)`. New events: `child_milestone`, `child_failed` (with the plan-087 `RunLimitBreach` attribution), `delegation_child_events_capped`, `delegation_child_events_coalesced`.
+
+```ts
+const { delegationId } = await supervisor.delegateAsync({ childId: "researcher", input: "survey the repo", lifetime: "session", report: "milestones", milestone: { everyTurns: 3 }, budgetShare: 0.25 });
+supervisor.subscribe(); // … child_milestone … child_failed (on a limit or error)
+```
+
+Sizing: child events per delegation 256/4096, child-event bytes 32 KiB/256 KiB, child events per second 10/1000 (default/hard, per child) — 10/s is trivial for a UI, raise it only for a child whose tool events are the UI. Exceeding rate coalesces into one `delegation_child_events_coalesced` marker with the dropped count (never throws). Defaults are exactly 0.8: `lifetime: "task"`, `report: "on-complete"`, no milestone, no share, no subscription. See [Supervisors](supervisors.md) and [Multi-agent patterns](multi-agent-patterns.md).
+
+### 9. Checkpoint sidecar metadata and cross-layer restore hooks
+
+Hosts attach an opaque, redacted metadata map (≤4 KiB) to every checkpoint record — git commit, document version, workspace fingerprint — without charging `maxStateBytes`, and register restore hooks that put each recorded layer back before a resume claims the run.
+
+```ts
+createAgentRunLifecycle({ runState: { checkpointMetadata: () => ({ gitCommit: head, docVersion: "v12" }) },
+  restoreHooks: [async ({ metadata, signal }) => { await checkout(metadata.gitCommit, { signal }); }] });
+```
+
+Sizing: `MAX_AGENT_RUN_METADATA_BYTES` is 4 KiB (fixed, no override), the whole map is redacted unconditionally (no public-key exemption), and each hook has a 10-second default timeout (`DEFAULT_CHECKPOINT_RESTORE_TIMEOUT_MS`) with sequential execution; any hook failure aborts the restore with `{ hook, error }`. Legacy records without metadata read as `undefined`, and an oversize or non-string map reads as absent rather than failing a resume — unused, behavior is unchanged. See [Durable runs](durable-runs.md).
+
+### 10. Bounded workspace session search
+
+`SessionStore.searchSessions?(query)` is part of the store contract: filters by workspace root (`metadata.workspaceRoot`), time, provider/model, label/summary, entry kind, ownership, and an optional full-text `query`; hits carry `sessionId`, optional `leafId`, and the matched entry pointer (`entryId`, `runId`, 1-based `turn`, store `score`, bounded `snippet`) — never credentials or whole transcripts. SQLite FTS5 and the Postgres `tsvector` column are maintained additively at append time (migration 004, no background job); memory and JSONL stores scan linearly through the shared `searchLinearSessions` matcher.
+
+```ts
+const page = await store.searchSessions!({ workspaceRoot: "/repo", query: "flake", kind: "any", limit: 20 });
+const { page } = await searchSessions({ bySession, leafBySession, query: "flake" }); // linear caps apply
+```
+
+Sizing: on the 100k-turn fixture the index is 18.8% of transcript page bytes (stored tool output is never indexed) and query p95 is 38 ms against the 100 ms ceiling; unindexed stores are O(corpus) per query and accept `maxLinearSessions` / `maxLinearEntries` / `maxLinearBytes` overrides bounded by their hard caps. See [Session stores](session-stores.md) and `examples/session-search.ts`.
+
+### 11. Deterministic no-model turns
+
+The `beforeProviderTurn` middleware hook receives `BeforeProviderTurnPayload` (`sessionId`, `runId`, `turn`, `userText`) and may answer the turn from host data by returning a `DeterministicTurnAnswer` — no provider request, zero model cost, no hallucination surface. Answers are validated (`validateDeterministicTurnAnswer` / `resolveDeterministicTurn`), the turn is recorded as `deterministic` on the timeline and in usage, and `DeterministicTurnProvenance` names the middleware that produced it. `createDeterministicTurnScorer` grades the behavior in evals.
+
+```ts
+middleware.use<BeforeProviderTurnPayload>("beforeProviderTurn", async (payload, next) =>
+  payload.userText.startsWith("status:")
+    ? { ...payload, answer: { text: await hostStatus(payload.userText), provenance: { middleware: "status" } } }
+    : next(payload));
+```
+
+Sizing: no provider turn, no usage beyond a zero-cost record; the hook runs only for turns that reach the provider boundary (a turn already ended by a run limit, host turn policy, or suspension never reaches it), and host middleware is trusted code — it must not use the hook to bypass `RunLimits` or guardrails. See [Middleware hooks](middleware-hooks.md#no-model-turns-beforeproviderturn).
+
+### 12. Shared work scopes for observational memory
+
+`om.attach(session, { sharedScopes })` lets several sessions contribute to and read one observational-memory scope under explicit owner grants (`controller.grant(scopeId, principalIds)` / `revoke`). Only ids bound to that exact scope are shared; the owner branch is the only grant authority; every resolve re-reads it, so revocation lands on the next read, and `onScopeAccess` audits each grant/denial.
+
+```ts
+om.attach(session, {
+  appendEntry: (entry, options) => store.append(entry, options),
+  sharedScopes: { "build-42": { ownerSessionId, entries: (id) => store.list(id) } },
+  onScopeAccess: (event) => audit.info("om.scope.access", event),
+});
+```
+
+Sizing: one local write per append (flush stays local — no second writer on a branch); one branch read plus fold per participating branch per context resolve and per shared-scope recall, not per observation; 1,024 principals per scope and 256-character principal ids, on top of the existing scope caps (256 scopes, depth 8, 4,096 binds, 512-character labels). Session-private scopes stay the default: with no `sharedScopes` configured, behavior is byte-identical to 0.8. See [Compaction and observational memory](compaction-observational-memory.md#shared-work-scopes-opt-in) and `examples/shared-work-scope.ts`.
+
+### 13. Retrieval revocation and a zero-service reranker
+
+Deletion and revocation propagate through derived artifacts: `createDeletionPropagator` deletes vector rows and then hands the invalidation set (`collectInvalidationIds` / `listInvalidatedIds`) to host handlers, and `repointSource` / `retireWikiSources` (plus the `createWikiDeletionHandler` / `createWikiRepointHandler` helpers) keep wiki pages and summaries consistent. `createAccessRecheck` rechecks governed sources per query and reports denials through an audit sink. Reranking no longer needs a research project: `resolveReranker({ kind: "local" })` / `createLocalReranker()` runs an in-process cross-encoder behind the `LocalRerankRuntime` seam, with the same `runRerankerConformance` contract as every other reranker; TEI and hosted adapters are unchanged.
+
+```ts
+const reranker = resolveReranker({ kind: "local" });            // Xenova/bge-reranker-base via a host-owned runtime
+const access = createAccessRecheck({ store, onDenied: audit.warn });
+const propagator = createDeletionPropagator({ store, handlers: [createRagDeletionHandler(vectors), createWikiDeletionHandler(wiki)] });
+```
+
+Sizing: the local reranker declares no inference dependency — the built-in loader resolves `@huggingface/transformers` at first use (pass `runtime` to inject your own, or `allowRemoteModels: false` for a no-network posture after the model is cached); propagation and repoint walks are bounded by `HARD_PROPAGATION_EDGES` / `HARD_REPOINT_RECORDS` and fail closed past them. See [RAG](rag.md#local-reranker), [Embeddings](embeddings.md), and [Knowledge sync](knowledge-sync.md).
+
+---
+
+## Operator / release honesty (not a host API break)
+
+- **Compatibility baseline regenerated**: `+119` public names across `@arnilo/prism` (+49), `@arnilo/prism-memory` (+60), and `@arnilo/prism-core` (+10); **zero removals** and zero renames. One declaration change is consumer-visible at the type level: the `recordUsage` callback accepted by `generateProviderTurn` / `generateWithRetry` now returns `Promise<Usage | undefined>` instead of `Promise<void>`, so a hand-written callback that returned nothing must return the usage (or `undefined`).
+- **Budgets rebaselined with recorded reasons**: root packed/unpacked/file count, per-package export ceilings, and the non-null assertion ratchet carry the measured 0.9.0 values and the plans that moved them.
+- **This-tree Postgres evidence**: `release:gate` reports the durable Postgres surface as pass only when `scripts/postgres-evidence.json` matches the current `git rev-parse HEAD`; a stale phase baseline is blocked rather than inherited.
+- **Version literals agree** across all eleven manifests, the lockfile, `src/index.ts`, the docs banner, the release workflow tag lists, and the generated package-truth artifact (`scripts/version-literal-gate.test.mjs`).
+
+## Upgrade steps
+
+1. Bump every `@arnilo/*` dependency and peer to `^0.9.0` (all **eleven** manifests cut together; a range that only *satisfies* 0.9.0 is refused by the release gate). The published predecessor is 0.8.0.
+2. Build and run the host suite. No import path moved, so compile errors should be limited to the `recordUsage` callback return type above and to code that deep-equals `provider_turn_finished.metadata`.
+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.
+
+## Rollback
+
+Pin the previous published line: `@arnilo/prism@0.8.0` and its siblings, exact pins per package. Session, checkpoint, and ledger schema are unchanged across 0.8.0 → 0.9.0 apart from the additive session-search index (migration 004), which a 0.8.0 process never reads; observability rows written under 0.9.0 carry extra metadata fields that 0.8.0 ignores. Revert host config to 0.8.0 semantics by dropping `attentionCompiler.trigger` / `durable`, `toolNarrowing`, `guardrailPacks`, `usageEstimation`, `checkpointMetadata` / `restoreHooks`, `sharedScopes`, and the session-lifetime child options — every default already matches 0.8.0.
+
+## Related APIs
+
+- [Migration guide](migration.md): the era index of migration cuts with replacement tables and rollback notes.
+- [Migrate Prism 0.7 to 0.8](migrate-to-0.8.md): work-family import map, messaging channels, connected apps, durable runs.
+- [Release and install](release-and-install.md): packed surfaces, install rules, support matrix, and the offline test budget.
+- [Agent events](agent-events.md), [Runs and usage](runs-and-usage.md), [Observability](observability.md), [Tools](tools.md), [Guardrails](guardrails.md), [Supervisors](supervisors.md), [Session stores](session-stores.md): owning pages for the 0.9.0 additions.