@arnilo/prism 0.7.0 → 0.9.0

package/docs/migration.md

@@ -1,5 +1,48 @@
 # Migration guide
 
+## 0.8.0 → 0.9.0 (attention budget axes, turn traces, tool narrowing, guardrail packs, background agents, session search, deterministic turns, shared scopes)
+
+**Prism 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. The full guide — the four deltas inside existing surfaces, every new option with its sizing line, upgrade steps, and rollback — is [migrate-to-0.9.md](migrate-to-0.9.md).
+
+What a 0.8.0 host must check before upgrading:
+
+- **A limit death no longer ends a stream early.** `run_limit_exceeded` and `budget_exhausted` are not terminal; keep reading until `error` (or `isTerminalAgentEventType(type)` is true) to see the breach, its attribution, and the run's outcome in order.
+- **`provider_turn_finished` metadata grew** (`stopReason`, `budgets`, `tools`, `cache`), and `agent_finished` now carries `finishReason` / `stopDetail`; consumers that deep-equal `metadata` must allow the new fields.
+- **`AgentConfig.usageEstimation` defaults to `"fallback"`**: a provider that reports no usage is charged one labeled estimate (`estimated: true` + `confidence`) instead of zero. Set `"off"` for the old behavior; billing code must read the label.
+- **Progressive disclosure is cache-stable**: skill bodies and deferred schemas append at the tail instead of rewriting the prefix. Defaults keep 0.8 bytes for hosts that never load late context.
+- **One type-level change**: the `recordUsage` callback of `generateProviderTurn` / `generateWithRetry` returns `Promise<Usage | undefined>` instead of `Promise<void>`.
+- **Additive, inert by default**: attention `trigger` axes and `durable` folding, per-turn `toolNarrowing`, `guardrailPacks`, session-lifetime child agents with child-event passthrough, `checkpointMetadata` / `restoreHooks`, `searchSessions`, `beforeProviderTurn` deterministic turns, observability shared work scopes, deletion propagation, and the local reranker. One additive migration (004) adds the session-search index; no existing table or column changes.
+
+## 0.7.0 → 0.8.0 (messaging channels, connected apps, work family, durable runs)
+
+**Prism 0.8.0 is a lockstep minor for all eleven publishable packages.** Node `>=22` stays the floor. The only import-map break is `@arnilo/prism-office` → `@arnilo/prism-work` (plus the work/document-reader subpath moves). A host that never imported those paths upgrades by moving every `@arnilo/*` dependency and peer to `^0.8.0`. The full guide — per-item actions, opt-in activation, and rollback — is [migrate-to-0.8.md](migrate-to-0.8.md).
+
+What a 0.7.0 host must check before upgrading:
+
+- **One import-map break.** Replace `@arnilo/prism-office/*`, `@arnilo/prism-core/integrations/work*`, and `@arnilo/prism-coding-tools/document-reader` with `@arnilo/prism-work` subpaths. Catch work-idempotency by `error.code`, not class. No pre-1.0 shim.
+- **Eleventh package.** `@arnilo/prism-channels` is new and optional; omit it if the host has no messaging ingress.
+- **Additive, inert by default:** connected-app MCP sessions, work HTTP adapters, turn-boundary checkpoints / `decision: "continue"`, turn-stop policy, run-bundle snapshots, claim-grounding guardrail, work sandbox/skills.
+- **Behavioral pins inside existing surfaces:** observational-memory workers stay tool-only (text-only turns are successful no-ops); channel lease release clears in-memory state only after the store acknowledges; AG-UI `inputPolicy.clientState: "ignore"` is opt-in (default honor matches 0.7.0); a foreign checkpoint/run-status load is a miss, not an existence leak.
+
+## Next lockstep cut — work family package move
+
+`@arnilo/prism-office` and the work/document-reader subpaths are removed with no pre-1.0 compatibility shim. Install `@arnilo/prism-work` with `@arnilo/prism` and update 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` |
+
+The coding `createReadTool({ documentReader })` injection seam is unchanged; pass the reader created by the new subpath. Core keeps its durable adapter behind `createPostgresEnterpriseState({ pool }).workIdempotency` at `@arnilo/prism-core/enterprise/postgres` with type-only structural coupling.
+
+**Match work-idempotency conflicts by `code`, not by error class.** The portable codes are unchanged across the move — `ERR_PRISM_WORK_IDEMPOTENCY` for a rejected claim/transition and `ERR_PRISM_WORK_IDEMPOTENCY_CONFLICT` for a lost race or stale claim token — and a host that catches them by `error.code` (the pattern `docs/work-tools.md` documents) needs no change. The *class* is adapter-specific: `createMemoryIdempotencyStore()` throws `WorkToolError` (an upstream `Error` subclass) while the PostgreSQL adapter throws `EnterprisePostgresError`, since `@arnilo/prism-core` cannot depend on `@arnilo/prism-work` at runtime. A pre-existing adapter that caught the old import path's error by `instanceof` must switch to `code` matching; `packages/prism-core/src/enterprise/postgres/__tests__/work-idempotency.integration.test.ts` runs both adapters through the same conflict scenarios and asserts the two agree.
+
 ## 0.6.0 → 0.7.0 (host completeness, evidence, and capability boundaries)
 
 **Prism 0.7.0 is a lockstep minor for all ten publishable packages.** Node `>=22` stays the floor; no import path was removed and no store schema changed, so a host that does not touch the ACP agent or the model-router facade upgrades by moving every `@arnilo/*` dependency and peer to `^0.7.0`. The full guide — per-item migration actions, opt-in activation, and rollback — is [migrate-to-0.7.md](migrate-to-0.7.md).

package/docs/model-registry.md

@@ -36,7 +36,7 @@ import { createModelRegistry, type ModelConfig } from "@arnilo/prism";
 | --- | --- |
 | `provider` / `model` | Required registry key. |
 | `displayName` | Human-readable label. |
-| `capabilities` | Input/output modes (`text`, `image`, `audio`, `file`, `document`) plus reasoning/tools/streaming booleans and optional `structuredOutput` (`true` or `"json_schema"`) for native JSON-schema requests. |
+| `capabilities` | Input/output modes (`text`, `image`, `audio`, `file`, `document`) plus reasoning/tools/streaming booleans, optional `structuredOutput` (`true` or `"json_schema"`) for native JSON-schema requests, and advisory `toolCallStrictness`. |
 | `limits` | Context and output-token limits (`ModelLimits`). |
 | `cost` | Input/output/cache read/cache write pricing. |
 | `cache` | Generic `ModelCacheCapabilities`. |
@@ -101,9 +101,19 @@ const registry = createModelRegistry([model], { duplicate: "error" });
 const resolved = registry.resolve("demo", "demo-large");
 ```
 
+## Tool-call reliability metadata
+
+`ModelCapabilities.toolCallStrictness?: "strict" | "lenient" | "legacy"` is advisory evidence metadata for hosts pinning models. Omission means **unknown** and must never be inferred as `"strict"`; it changes neither tool disclosure, argument validation, parallel dispatch, retries, nor provider requests.
+
+- `"strict"`: the provider catalog has a network-free conformance fixture covering parallel-call reconstruction, a schema-shaped argument object, and an empty `{}` argument object.
+- `"lenient"`: a catalog has tested tool support but a known relaxed behavior; hosts should retain extra guardrails.
+- `"legacy"`: a catalog has tested compatibility-only tool behavior; hosts should avoid relying on strict multi-call/schema semantics.
+
+Current first-party evidence is generated at [tool-call coverage matrix](_evidence/toolcall-coverage-2026-09-17.md). Only NeuralWatt's curated catalog is stamped `"strict"`: its fixture checks all three behaviors. Every other first-party static catalog with `tools: true` is explicitly unstamped-unknown until it has that fixture coverage. Dynamic discovery records remain unknown because provider responses are untrusted catalog metadata. Hosts must still validate every tool argument against its schema.
+
 ## Extension and configuration notes
 
-Provider packages register models through `ProviderPackageAPI.registerModel(model)`. The extension kernel stores those records in the host-owned registries. Static package metadata is allowed; dynamic model discovery remains provider/host code outside Prism core.
+Provider packages register models through `ProviderPackageAPI.registerModel(model). The extension kernel stores those records in the host-owned registries. Static package metadata is allowed; dynamic model discovery remains provider/host code outside Prism core.
 
 `ModelConfig.compat` remains for provider-owned inert JSON. Prefer typed fields (`capabilities`, `limits`, `cost`, `cache`) for generic behavior shared across providers.
 

package/docs/multi-agent-patterns.md

@@ -17,7 +17,7 @@ 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 |
 | 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 | Same supervisor `delegation_*` events |
+| 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.
@@ -151,6 +151,29 @@ Live demo: [`examples/crew-hierarchy.ts`](../examples/crew-hierarchy.ts) — man
 
 Live demo: [`examples/spawn-agent-tool.ts`](../examples/spawn-agent-tool.ts) — a narrowed read-only explore child spawned twice in parallel, an uncatalogued child refused, and both handles joined.
 
+### Background agents (session lifetime)
+
+A host can start a background child at session open that reports without occupying the conversation:
+
+```ts
+const supervisor = createSupervisor({
+  ownership,
+  signal: sessionAbort.signal, // host session end stops every child and closes the stream
+  children: {
+    researcher: {
+      policy: { lifetime: "session", report: "milestones", milestone: { everyTurns: 5 }, budgetShare: 0.2 },
+      createAgent: ({ resourceId, threadId, permission, signal, delegate }) => createResearchAgent(/* ... */),
+    },
+  },
+});
+
+// Host code or the parent model (spawn_agent routes session lifetime to the async path):
+const handle = await supervisor.delegateAsync({ childId: "researcher", input: "watch the build", lifetime: "session" });
+await supervisor.wait(handle.delegationId); // join later; cancel(handle.delegationId) ends it explicitly
+```
+
+Session-lifetime children detach from the caller and ancestor-child abort signals, hold one `activeChildren` slot until they end, and stop on `cancel_agent` / `cancel(delegationId)` or the supervisor `signal`. `budgetShare` scales the inherited steps/tool-calls/tokens/timeout limits — never above the parent or host ceiling. Reporting stays host-opt-in and redacted: `milestones` emits `child_milestone` every N turns or on a host predicate, `stream` forwards every per-turn provider/tool/turn event (never token deltas), and both are rate-coalesced at `limits.maxChildEventsPerSecond` (10/s per child default) with a `delegation_child_events_coalesced` marker. To surface them on a parent session stream, pass `childEventSink` — it receives the same redacted payload tagged `child: { childId, delegationId, depth }`, so the parent subscriber only reads `event.child`.
+
 ## Where Prism is stronger
 
 - **Durable Human-in-the-Loop (HITL)**: Prism workflows support durable pause and resume via [`suspend()`](workflows.md#durable-suspension-and-resumption) and [`resumeWorkflow()`](workflows.md) across worker restarts or approval gates ([Agent durable approval](agent-session-runtime.md)).
@@ -166,7 +189,7 @@ Live demo: [`examples/spawn-agent-tool.ts`](../examples/spawn-agent-tool.ts) —
 - **Narrowing on transfer, never widening.** If the specialist needs the caller's verified identity, project it through `narrowIdentity` / `assertIdentityPropagation` ([Agent identity](agent-identity.md)) so scopes and tenant cannot widen across the swap. For delegation the same discipline is built in (`narrowIdentity`, AND-composed policies); for A2A the exact-origin client plus per-operation authorization is the boundary.
 - **Manager-generated task plans are untrusted model output.** Manager plan outputs are validated against the typed schema via `ArtifactValidator` before being persisted to workflow state or dispatched to `fan_out`. Malformed or invalid plans trigger the artifact repair loop or fail closed before any specialist is invoked.
 - **Redaction of carried context.** Handoff carries the raw transcript by design — same rows a human replay would read. Apply the session egress seams on the way out: `redactSessionEntry` / `redactMessage` with a host field policy (see [Data classification](data-classification.md)) and `AgentConfig.redactor`; for durable replay across tenants reuse the redacted transcript seam discipline used by ACP `sessions.transcript` ([ACP interop](acp.md)).
-- **Telemetry attribution.** Which agent produced which turn is not stored on message entries; the host knows (it performed the swap or aggregated fan-out results) and should pin it per run via `RunOptions.identity` (principal kind `agent`) so `identityTelemetryAttributes` (`prism.identity.*`) carries redacted attribution on telemetry, or via observability metadata. Supervisor runs emit dedicated `delegation_*` events; an in-process definition swap has no session seam to emit one, so the host records attribution.
+- **Telemetry attribution.** Which agent produced which turn is not stored on message entries; the host knows (it performed the swap or aggregated fan-out results) and should pin it per run via `RunOptions.identity` (principal kind `agent`) so `identityTelemetryAttributes` (`prism.identity.*`) carries redacted attribution on telemetry, or via observability metadata. Supervisor runs emit dedicated `delegation_*` events plus `child_failed` attribution (terminal `status`/`stopReason`, plan-086/087 `RunLimitBreach` when a ceiling fired), and `supervisor.summary()` reports per-child `attempts`/`retries`/`failures`/`failureRadius`/`outcome` — the recovery and cascade-radius counters a host cannot reconstruct from totals alone. An in-process definition swap has no session seam to emit one, so the host records attribution.
 - **Performance.** The swap performs zero provider calls; it costs one registry resolution plus one session open (~sub-millisecond in the example fixture). The transferred turn costs what any tool round costs.
 
 ## Extension and configuration notes

package/docs/node-jsonl-session-store.md

@@ -2,7 +2,7 @@
 
 ## What it does
 
-The optional `@arnilo/prism/node/session-store-jsonl` subpath stores `SessionEntry` records in a caller-named JSONL file: one JSON object per line. `searchSessions` is unsupported and throws `SessionSearchUnsupportedError` (use memory linear mode or a DB adapter for search).
+The optional `@arnilo/prism/node/session-store-jsonl` subpath stores `SessionEntry` records in a caller-named JSONL file: one JSON object per line. `searchSessions` is supported as an unindexed linear scan of the file: the memory-store matcher (workspace/label/summary/`kind` filters, text `query`, cursor pagination, hit pointers) with the contract linear scan caps. Every query reads and parses the whole file (O(corpus) time and memory), so indexed SQLite/Postgres adapters remain the recommended path for search over large corpora.
 
 APIs:
 
@@ -35,6 +35,7 @@ import { createJsonlSessionStore } from "@arnilo/prism/node/session-store-jsonl"
 - `append(entry, options?)` appends one JSON line, rejects duplicate entry ids, honors `expectedParentId` existence checks, and deduplicates exact idempotency retries within this store instance. Append **fails closed** when the file already contains any corrupt or shape-invalid line (`Invalid JSONL at line N: …`) so writers cannot extend a damaged log.
 - `list(sessionId)` reads the file and returns valid entries for that session id. Corrupt or shape-invalid lines are skipped; they do not poison the whole file.
 - `get(id)` reads the file and returns the matching valid entry, if any.
+- `searchSessions(query)` reads the file and runs the shared linear session matcher. Corrupt or shape-invalid lines are quarantined exactly as in `list()`/`get()`, the contract linear caps bound sessions/entries/bytes scanned, and hits carry the same shape as the indexed adapters (`sessionId`, `leafId`, `entryId`, `runId`, `turn`, `snippet`) — without `score`, since a linear scan has no index relevance.
 - `readJsonlSessionEntries(path)` returns `{ entries: SessionEntry[]; errors: SessionEntryParseError[] }` so hosts/tests can inspect per-line parse errors.
 
 Missing files read as empty stores (typed Node `ENOENT`). Invalid JSON, missing required fields, unsupported `schemaVersion`, unknown `kind`, or wrong per-kind shapes (`message`, `summary`, `model_change`, `custom`, `compaction`, `label`, `event`, `metadata`, or non-string `parentId`) are quarantined per line with line number and reason; the raw line is included in `SessionEntryParseError.raw`. Unknown entry kinds and future schema versions fail closed for reads: the line is skipped and never returned by `list()` or `get()`. For writes, any parse error blocks `append()` until the host repairs or replaces the file.
@@ -56,6 +57,10 @@ import { createJsonlSessionStore, readJsonlSessionEntries } from "@arnilo/prism/
 const store = createJsonlSessionStore("./sessions.jsonl");
 const { entries, errors } = await readJsonlSessionEntries("./sessions.jsonl");
 if (errors.length) console.warn("quarantined lines", errors);
+
+// Linear search (unindexed): the same query API as the SQLite/Postgres adapters.
+const page = await store.searchSessions!({ workspaceRoot: "/repo", query: "flake", kind: "any", limit: 20 });
+// [{ sessionId, leafId, entryId, runId, turn, snippet, ... }]
 ```
 
 Use `createMemorySessionStore()` for tests or throwaway sessions; use the JSONL store when entries should survive a process restart.
@@ -73,6 +78,7 @@ Use `createMemorySessionStore()` for tests or throwaway sessions; use the JSONL
 - Errors include path/reason or line number, not file contents.
 - Do not put secrets in messages, metadata, summaries, labels, or custom entries.
 - Reads are linear in file size. Appends also re-read and re-parse the whole file for duplicate/parent/corruption checks before writing one line, and are serialized per store instance. A rejected append does not poison later appends; the rejected line is not written.
+- `searchSessions` is linear in file size too (there is no index): every query reads and parses the whole file before the capped scan, so latency and peak memory grow with the corpus. Use a SQLite/Postgres `SessionStore` when search latency matters, and treat search here as resume/filter tooling on small stores.
 - There is no cross-process lock or durable idempotency table; two processes writing the same file can race. Add a database or external lock if multiple processes write the same file.
 - Treat this adapter as development/single-process storage. Production multi-writer hosts should use an indexed database `SessionStore` adapter.
 

package/docs/observability.md

@@ -41,7 +41,7 @@ New agent event variants (metadata only):
 | Variant | When | Key fields |
 | --- | --- | --- |
 | `provider_turn_started` | Before each provider `generate()` attempt | `turn`, `metadata: ProviderTurnMetadata` |
-| `provider_turn_finished` | After success or failure of that attempt | `metadata` (includes `latencyMs`, optional `httpStatus`), `usage?`, `error?` |
+| `provider_turn_finished` | After success or failure of that attempt | `metadata` (includes `latencyMs`, optional `httpStatus`, `stopReason`, `budgets`, `cache`), `usage?`, `error?` |
 
 `ToolExecutionMetadata` on terminal tool events:
 
@@ -91,6 +91,7 @@ Provider turn metadata fields:
 | `latencyMs` | Set on `provider_turn_finished` |
 | `httpStatus` | Numeric `ErrorInfo.code` when present |
 | `rateLimitRemaining` / `rateLimitResetMs` | Reserved for provider adapters (optional) |
+| `cache` | Provider-reported `{ cacheReadTokens?, cacheWriteTokens?, hitRate? }`; absent when cache usage is unknown. |
 
 OpenTelemetry mapping (when enabled):
 
@@ -190,8 +191,8 @@ const found = await retrieveContext("policy", { embedder, store, scope, telemetr
 
 Host cockpits and dashboard cards need fast aggregate summaries of an execution without re-walking every raw event or risking prompt/secret leaks:
 
-- `summarizeTimeline(timeline)`: rolls up an `ExecutionTimeline` into a `TimelineSummary` containing duration, turn count, tool call counts, provider attempts, total tokens, cost, error counts, and suspension state.
-- `summarizeSession(timelines)`: rolls up an array of `ExecutionTimeline`s for a session/conversation into a `SessionSummary` with aggregated tokens, costs, run counts, and duration.
+- `summarizeTimeline(timeline)`: rolls up an `ExecutionTimeline` into a `TimelineSummary` containing duration, turn count (split into model vs deterministic turns), tool call counts, provider attempts, total tokens, cost, error counts, suspension state, and — for a run that died on a run limit — an `exhaustion` line (`"maxTurns exhausted (13/12); closest: maxToolCalls 0.625"`).
+- `summarizeSession(timelines)`: rolls up an array of `ExecutionTimeline`s for a session/conversation into a `SessionSummary` with aggregated tokens, costs, run counts, duration, and the same model/deterministic turn split.
 
 ```ts
 import { summarizeTimeline, summarizeSession } from "@arnilo/prism-core/governance/observability";
@@ -201,6 +202,7 @@ const summary = summarizeTimeline(timeline);
 // {
 //   durationMs: 1250,
 //   turnCount: 2,
+//   turns: { model: 1, deterministic: 1 },
 //   toolCallCount: 3,
 //   toolCounts: { search: 2, lookup: 1 },
 //   providerAttempts: 2,
@@ -210,6 +212,7 @@ const summary = summarizeTimeline(timeline);
 //   blockedToolCount: 0,
 //   suspended: false,
 //   status: "succeeded",
+//   exhaustion: "maxTurns exhausted (13/12); closest: maxToolCalls 0.625", // only when a limit fired
 // }
 
 const sessionSummary = summarizeSession([run1Timeline, run2Timeline]);
@@ -218,6 +221,7 @@ const sessionSummary = summarizeSession([run1Timeline, run2Timeline]);
 
 Cardinality and correctness guarantees:
 - **Bounded cardinality**: `toolCounts` is capped to `MAX_SUMMARY_DISTINCT_TOOLS = 64` distinct tool names. If more tools are invoked, lowest-frequency tool names overflow into an `"other"` bucket.
+- **Honest turn attribution**: `turns.model` counts turns with a provider step; `turns.deterministic` counts turns answered by host middleware (plan 096, `deterministic` step kind). A no-model turn is never rolled into model counts, and its usage stays absent rather than zero.
 - **No double counting**: Token usage is derived from the root run's `run_total` (or aggregated across `turn` / `provider` steps if no run-level total exists), avoiding double counting between provider turn steps and run totals. Costs are rounded to 6 decimal places to prevent floating-point drift.
 - **Payload-free**: Summaries contain counts, durations, status codes, and usage metrics only — zero prompt text, tool arguments, or credentials.
 

package/docs/openapi-tools.md

@@ -4,7 +4,7 @@ Optional `createOpenApiTools` compiles host-selected OpenAPI 3.1 operations into
 
 ## When to use it
 
-Hosts that already expose a JSON API with an OpenAPI 3.1 document and want the agent to call a **fixed, host-chosen subset** of it — never model-driven discovery, never a raw method/path passthrough. For vendor web search/extraction use `@arnilo/prism-web-tools`; for M365/GWS use `@arnilo/prism-core/integrations/work`; this adapter is for arbitrary host APIs.
+Hosts that already expose a JSON API with an OpenAPI 3.1 document and want the agent to call a **fixed, host-chosen subset** of it — never model-driven discovery, never a raw method/path passthrough. For vendor web search/extraction use `@arnilo/prism-web-tools`; for M365/GWS use `@arnilo/prism-work/connectors`; this adapter is for arbitrary host APIs.
 
 ## Usage
 

package/docs/operations.md

@@ -82,9 +82,7 @@ tenant's reads, writes, and lease takeover all fail closed.
   fencing token), and a stale token's renewal returns `null`. There is
   intentionally no "force unlock" operation — deleting a lease row manually
   bypasses fencing and can cause split-brain writes; never do it.
-- Tenant ownership is checked on every durable read/write; cross-tenant
-  reads, saves, and lease acquisitions fail closed with ownership-mismatch
-  errors.
+- Tenant ownership is checked on every durable read/write: a foreign checkpoint read or delete is a miss (never an existence oracle), a foreign checkpoint write fails as `ERR_PRISM_CHECKPOINT_CONFLICT`, and lease acquisition still fails closed with an ownership-mismatch error.
 - An uncertain commit (side effect landed, cursor not advanced) is resolved
   by replaying the effect with its stable id — never by guessing. Reload
   durable state before any retry; retries that skip the reload risk

package/docs/options-index.md

@@ -18,7 +18,7 @@ Field-level detail (defaults, bounds, failure modes) lives on the owning page
 | --- | --- | --- |
 | `AgentConfig` | The reusable agent: provider, model, tools, skills, stores, retry, compaction, prompts, limits | [Agent/session runtime](agent-session-runtime.md) |
 | `RunOptions` | One run's overrides: model, limits, thinking level, skills, middleware, metadata, signal | [Agent/session runtime](agent-session-runtime.md) |
-| `AgentSessionConfig` | Session creation: id, agent, store, branch leaf, snapshot cache TTL | [Agent/session runtime](agent-session-runtime.md) |
+| `AgentSessionConfig` | Session creation: id, agent, store, branch leaf, snapshot cache TTL, guardrail packs | [Agent/session runtime](agent-session-runtime.md) |
 | `ModelConfig` | A registered model record: capabilities, limits, cost, cache and thinking metadata | [Model registry](model-registry.md) |
 | `ProviderRequestOptions` | Per-request provider hints: session/cache/header/compat/extra, applied after host policies | [Provider layer](provider-layer.md) |
 
@@ -29,6 +29,25 @@ Field-level detail (defaults, bounds, failure modes) lives on the owning page
 - **Request-time overrides narrow, never widen.** `RunOptions.limits` can only tighten `AgentConfig.limits`; a configured finite ceiling wins over `null`.
 - **Byte caps are not estimator-dependent.** Token-budget options that accept a host estimator (`tokenEstimator`) affect eviction accounting only; byte caps and redaction stay authoritative.
 
+## Durable runs
+
+**Agent run state** — [`durable-runs.md`](durable-runs.md)
+`AgentRunStateOptions`
+
+`AgentRunStateOptions.checkpointPolicy` (`"decision"` | `"every-turn"`) writes turn-boundary checkpoints so a crashed worker resumes with `decision: "continue"`; that action stays host-only and is never reachable from AG-UI or the server boundary.
+
+## Host stop, snapshot, and honesty surfaces
+
+| Surface | What it controls | Owning page |
+| --- | --- | --- |
+| `RunOptions.turnPolicy` (`TurnPolicyOptions`) | Synchronous host stop at a turn boundary; a stop lands as `stopReason: "host_policy"` and stays resumable | [Agent loops](agent-loops.md) |
+| `CreateAgUiHandlerOptions.inputPolicy` (`AgUiInputPolicyOptions`) | `clientState: "honor"` \| `"ignore"` — whether the server honors client-supplied AG-UI state and tools | [Frontend interoperability](ag-ui.md) |
+| `snapshotRunBundle(...)` → `RunBundleSnapshot` | Inspectable digest projection of the effective run bundle (prompt/skill/tool/guardrail digests, limits, storage kinds) | [Run bundle](run-bundle.md) |
+| `createClaimGroundingGuardrail` (`ClaimGroundingGuardrailOptions`) | `"output"`-stage guardrail that blocks or flags numeric claims no tool result or host evidence supports | [Guardrails](guardrails.md) |
+| `ErrorInfo.failureClass` (`ProviderFailureClass`) | Typed provider failure on run outcomes, ledger rows, and tool results (`quota`, `rate_limited`, `auth`, `transient`, `permanent`) | [Runs and usage](runs-and-usage.md) |
+| `AgentConfig.usageEstimation` | `"fallback"` (default) records a labeled estimate when a provider reports no usage; `"off"` leaves usage absent; estimates are never priced | [Runs and usage](runs-and-usage.md#automatic-fallback-agentconfigusageestimation) |
+| `ModelConfig.capabilities.toolCallStrictness` | Advisory tool-call reliability (`"strict"` \| `"lenient"` \| `"legacy"`); catalog conformance, not a promise | [Model registry](model-registry.md) |
+
 ## Agent/session runtime
 
 **Agent definitions** — [`agent-definitions.md`](agent-definitions.md)  
@@ -38,7 +57,10 @@ Field-level detail (defaults, bounds, failure modes) lives on the owning page
 `SubscribeOptions`
 
 **Agent loops** — [`agent-loops.md`](agent-loops.md)  
-`AgentLoopOptions`
+`AgentLoopOptions`, `TurnPolicyOptions`
+
+**Guardrails** — [`guardrails.md`](guardrails.md)
+`ClaimGroundingGuardrailOptions`
 
 **Agent/session runtime** — [`agent-session-runtime.md`](agent-session-runtime.md)  
 `AgentConfig`, `AgentRunResumeOptions`, `AgentRunResumeStreamOptions`, `AgentSessionCloneOptions`, `AgentSessionConfig`, `AgentSessionForkOptions`, `RunOptions`, `SteerOptions`
@@ -230,7 +252,7 @@ Field-level detail (defaults, bounds, failure modes) lives on the owning page
 `AcpCapabilitiesOptions`, `CreatePrismAcpAgentOptions`
 
 **Frontend interoperability (AG-UI and ACP)** — [`ag-ui.md`](ag-ui.md)  
-`AgUiLimitOptions`
+`AgUiInputPolicyOptions`, `AgUiLimitOptions`
 
 **Supervisors and subagents** — [`supervisors.md`](supervisors.md)  
 `CreateSupervisorOptions`, `SupervisorLimits`, `ResolvedSupervisorLimits`, `DelegationWaitOptions`, `CreateSpawnAgentToolOptions`, `CreateDelegationControlToolOptions`, `WorktreeChildFactoryOptions`, `ObserveSupervisorLifecycleOptions`
@@ -240,6 +262,17 @@ Field-level detail (defaults, bounds, failure modes) lives on the owning page
 **Workflows** — [`workflows.md`](workflows.md)  
 `RunWorkflowOptions`
 
+## Third-party integrations
+
+**Messaging channels** — [`messaging-channels.md`](messaging-channels.md)
+`MessagingRuntimeOptions`, `ChannelLimits`, `ChannelDeliveryJournalOptions`, `ChannelPairingStoreOptions`, `ChannelStateStoreOptions`
+
+**Telegram channel** — [`telegram-channel.md`](telegram-channel.md)
+`TelegramAdapterOptions`, `TelegramWebhookHandlerOptions`
+
+**Signal channel (experimental)** — [`signal-channel.md`](signal-channel.md)
+`SignalAdapterOptions`
+
 ## Conformance harnesses
 
 These option objects configure the shipped test doubles a host runs against its own adapters (provider, store, run ledger, compaction, tool, extension). They are host-facing, but only in test code.

package/docs/peer-dependencies.md

@@ -22,8 +22,8 @@ One row per declaration. `Unlocks` names the subpath whose import reaches the pe
 | `zod` | `^3.25.0 \|\| ^4.0.0` | no | `@arnilo/prism-ag-ui` | `./acp` | `npm i zod` | no |
 | `@nanonets/graft` | `^0.16.0 \|\| ^0.18.0` | yes | `@arnilo/prism-memory` | `./graft` | `npm i @nanonets/graft` | no |
 | `@dietrichgebert/ponytail` | `^4.9.0` | yes | `@arnilo/prism-coding-tools` | `./ponytail` | `npm i @dietrichgebert/ponytail` | no |
-| `mammoth` | `^1.8.0` | yes | `@arnilo/prism-coding-tools` | `./document-reader` | `npm i mammoth` | no |
-| `pdf-parse` | `^2.4.5` | yes | `@arnilo/prism-coding-tools` | `./document-reader` | `npm i pdf-parse` | 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 |
@@ -51,7 +51,7 @@ Two peers are pinned to an exact version instead of a range, because the pin is
 - **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.
 
-Test-only dependencies are *not* peers. `playwright-core` appears in `@arnilo/prism-office` as a devDependency only, because the office diagrams embed takes a host-supplied iframe and the sole consumer is the gated live draw.io conformance test.
+Test-only dependencies are *not* peers. `playwright-core` appears in `@arnilo/prism-work` as a devDependency only, because the office diagrams embed takes a host-supplied iframe and the sole consumer is the gated live draw.io conformance test.
 
 ## Implementation example
 
@@ -66,7 +66,7 @@ npm i @arnilo/prism-core pg
 npm i @arnilo/prism-core @nats-io/transport-node @nats-io/jetstream
 
 # Document reader: pick the parser you need (both are independent)
-npm i @arnilo/prism-coding-tools pdf-parse mammoth
+npm i @arnilo/prism-work pdf-parse mammoth
 ```
 
 ```ts
@@ -80,7 +80,7 @@ const tools = await createBrowserTools({ browser });
 ## Extension and configuration notes
 
 - A peer is an *implementation the host owns*. When a peer's default wiring is not what you want, pass your own implementation instead of installing theirs: the document reader accepts host parsers (`createReadTool({ documentReader })`), the memory `/graft` resolver accepts an explicit package root, and the browser surfaces accept a host `Browser`.
-- Subpaths that need a peer isolate that import, so importing another subpath of the same package never evaluates it. The office family is the extreme case: zero peers, because it takes structural inputs.
+- Subpaths that need a peer isolate that import, so importing another subpath of the same package never evaluates it. The office family is the extreme case: zero peers, because it takes structural inputs. `@arnilo/prism-channels` also has no third-party peers: Telegram uses native `fetch`, and signal-cli is a host-operated binary rather than an npm peer.
 - Adding a peer to a Prism package is a release-gated change: the declaration must be optional unless a hard dependency's own peer forces it (the `zod` case), and exact pins must come with a version-gate or compatibility rationale.
 
 ## Security and performance notes
@@ -93,4 +93,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), [Graft](graft.md), [Ponytail](ponytail.md), [Provider packages](provider-packages.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), [Graft](graft.md), [Ponytail](ponytail.md), [Provider packages](provider-packages.md), [Messaging channels](messaging-channels.md).

package/docs/policy-and-audit.md

@@ -107,7 +107,19 @@ for await (const page of exportPolicyDecisions({
 
 ## Extension and configuration notes
 
-Policy is optional. Hosts wire `record*` helpers or `evaluateAndAppend` at permission/guardrail/tool-approval/router/connector boundaries. Model-router and work-connector packages (later Phase 8 tasks) may call the same store when configured. Replace file/memory adapters with host WORM/KMS without changing record shape.
+Policy is optional. Hosts wire `record*` helpers or `evaluateAndAppend` at permission/guardrail/tool-approval/router/connector boundaries. Model-router and work-connector packages (later Phase 8 tasks) may call the same store when configured. Replace file/memory adapters with host WORM/KMS without changing record shape. Guardrail-pack denials record through `recordGuardrailDecision` like any other guardrail: the target id is the rule identity `pack:<pack>/<rule>`, `block`/`tripwire` map to outcome `deny`, and the evidence ref is `guardrail:pack:<pack>/<rule>:<stage>`. Pack config appears in run bundles as identity rows (`pack:<pack>/<rule>`, stage, `pack@version`) — never inline predicate code or tool arguments.
+
+## Memory retrieval ACL denials and re-pointing (plan 089)
+
+Memory retrieval keeps its own audit events next to policy decisions; hosts forward them to the same append-only sink:
+
+| Event | Shape | When |
+| --- | --- | --- |
+| `rag.acl_denied` | `{ sourceId, scope: { tenantId, resourceId, threadId }, reason: "no_grant" \| "check_failed", hits, error? }` via `retrieveContext({ onAccessDenied })` | A source was withheld at the retrieval boundary: revoked/absent/version-mismatched grant, or the grant lookup threw (`error` is redacted, capped at 256 chars) |
+| `Repointed` log line + result | `repointSource()` → `{ from, to, movedChunks, rewrittenEdges, layers, batched }` | A source's grant identity moved and derived artifacts followed |
+| Invalidation rows | `store.invalidate()` rows (`{ id, reason: "corrected" \| "revoked" \| "forgotten" \| "legal_hold", at }`) read back by `listInvalidatedIds()` | A source was revoked/forgotten/held; tombstones stay for explainability |
+
+Events are per *source*, not per hit, and are emitted once per query. They never contain document text, grant contents, or credentials; `check_failed` messages pass through the same redactor as retrieved content. Denials are fail-closed: a source is excluded whether the grant is absent, revoked, or the lookup failed, and the query returns the remaining hits. Aborts are not denials and are never recorded as such.
 
 ## Security and performance notes
 

package/docs/postgres-persistence.md

@@ -60,7 +60,7 @@ Hosts own TLS (`ssl` in `poolConfig`), credentials, connection limits, and backu
 | `RunLedger.append*` | Inserts run/event/tool/usage rows; events receive monotonic per-run `sequence` values. |
 | `events` | Durable `AgentEventSource`; `LISTEN`/`NOTIFY` only wakes exact owned indexed reads, while polling remains recovery fallback. |
 | `ProductionPersistenceStore.query*` | Parameterized cursor pagination on indexed columns with tenant/account/user filters. |
-| `checkpoints` | Generic versioned `CheckpointStore` backed by `prism_checkpoints`; ownership, CAS/fencing checks, bounded pagination, and workflow suspended/denied/schedule/state/replay values without a schema migration. |
+| `checkpoints` | Generic versioned `CheckpointStore` backed by `prism_checkpoints`; ownership, CAS/fencing checks, bounded pagination, and workflow suspended/denied/schedule/state/replay values without a schema migration. A load or delete under a non-matching ownership scope reads as absent and a cross-scope write fails as a generic `ERR_PRISM_CHECKPOINT_CONFLICT` (plan 080 Task 3) — no ownership-shaped existence oracle. |
 | `leases` | Atomic `LeaseStore` backed by `prism_leases`; database-clock expiry, opaque renew/release token, monotonic takeover fence. |
 | `close()` | Ends the pool when the adapter created it from `connectionString`. |
 

package/docs/prefix-stability-conformance.md

@@ -0,0 +1,93 @@
+# Prefix stability conformance
+
+## What it does
+
+Prefix stability conformance drives a real agent session through two staggered skill loads and asserts that each provider request keeps a byte-identical leading prefix with its predecessor — messages **and** tool schemas. It is the host-runnable form of the golden check behind [provider caching](provider-caching.md) and progressive skill disclosure: a late `load_skill` must append a body after the stable prefix instead of rewriting it.
+
+Exported from `@arnilo/prism/testing/prefix-stability-conformance`:
+
+- `runPrefixStabilityConformance(options)`
+- `PrefixStabilityConformanceOptions`
+- `PrefixStabilityConformanceResult`
+
+## When to use it
+
+Use it when a host owns any part of prompt assembly — custom `inputBuilder`, `promptBuilder`, context providers, instruction injectors, input/prompt middleware, or an explicit `inputLayout` — and wants to prove that progressive disclosure still holds the cache prefix. The runner:
+
+- installs a fixture provider (no network) that loads `skills[0]` on the first turn and `skills[1]` on the second, two provider requests per turn;
+- keeps everything else in `host` exactly as production: system prompt, context providers, builders, middleware, disclosure settings;
+- measures, for each consecutive captured request, the byte-shared prefix as a fraction of the previous request and fails below `minContinuity` (default `0.95`);
+- fails when a loaded body never reaches a provider request, so a builder that drops the tail cannot pass vacuously.
+
+## Inputs / request
+
+```ts
+import { runPrefixStabilityConformance } from "@arnilo/prism/testing/prefix-stability-conformance";
+
+const result = await runPrefixStabilityConformance({
+  host: {
+    model: { provider: "anthropic", model: "claude-sonnet-4-6" },
+    systemPrompt: { text: "..." },
+    context: [projectContextProvider],
+  },
+  skills: [skillA, skillB],
+});
+```
+
+`PrefixStabilityConformanceOptions`:
+- `host` — the host's `AgentConfig` minus `provider`, `providerSource`, and `skills`; the runner supplies the fixture provider and fixture skill registry
+- `skills` — exactly two distinct `Skill` values with non-empty `instructions`, loaded in turn order
+- `minContinuity?` — minimum shared-prefix fraction between consecutive requests (default `0.95`)
+- `inputs?` — the two turn inputs (default fixed strings, so runs stay comparable across hosts)
+
+## Outputs / response / events
+
+Returns `Promise<{ requests: number; minContinuity: number }>`: the captured request count (four) and the lowest shared-prefix fraction observed. Throws a plain `Error` naming the offending request pair and the measured percentage on the first violation. No events, no test runner, no network.
+
+## Request/response example
+
+```ts
+import { runPrefixStabilityConformance } from "@arnilo/prism/testing/prefix-stability-conformance";
+
+const { minContinuity } = await runPrefixStabilityConformance({
+  host: myAgentAssembly,
+  skills: [alphaSkill, betaSkill],
+});
+// throws: "request 2 → 3 kept 41.2% of the previous provider prefix (minimum 95.0%)"
+// when a context block or the skill catalog is recomposed in place.
+```
+
+## Implementation example
+
+```ts
+import { runPrefixStabilityConformance } from "@arnilo/prism/testing/prefix-stability-conformance";
+
+// The runner owns the provider and skills, so the same helper is the negative control too:
+// add a deliberately volatile context provider to prove the assertion can fail.
+await runPrefixStabilityConformance({
+  host: {
+    model: myModel,
+    context: [{ name: "volatile", resolve: () => [{ title: "Now", content: `${Date.now()}` }] }],
+  },
+  skills: [alphaSkill, betaSkill],
+});
+```
+
+## Extension and configuration notes
+
+- Loaded skill bodies and URI resources are re-sent after new transcript content by design (the tail is append-only, not immutable); a body larger than `1 - minContinuity` of the whole prompt lowers the fraction without indicating a prefix regression. Raise the fixture's stable prefix or lower `minContinuity` for body-heavy hosts.
+- Prompt builders that render skill bodies outside the tail are welcome — the check measures the provider-visible prefix, not where the body sits.
+- Attention/tool-result folding and context-budget eviction are explicit invalidation boundaries: run this check on an assembly path that neither folds nor evicts, or expect the fold to reset the measured prefix at that turn.
+
+## Security and performance notes
+
+- No credentials, no network, no real skills required; the fixture provider is a local generator.
+- Four small provider requests per run, in-memory session store (unless `host.store` says otherwise); cheap enough for a conformance suite.
+
+## Related APIs
+
+- [Provider caching](provider-caching.md)
+- [Input and prompt assembly](input-and-prompt-assembly.md)
+- [Context and skills](context-and-skills.md)
+- [Provider conformance](provider-conformance.md)
+- [Compaction conformance](compaction-conformance.md)

package/docs/provider-caching.md

@@ -66,11 +66,11 @@ Cache helpers return plain data:
 | `canonicalizeJsonSchema(value)` | Clone with sorted object keys and `required` names; semantic arrays stay ordered. Used by first-party tool serializers. |
 | `cacheHitRate(usage)` | Cached input ratio or `undefined`. |
 | `cacheSavings(usage, model)` | Estimated read-token savings or `undefined` without pricing. |
-| `cacheUsageReport(usage, model?)` | Normalized read/write tokens, hit rate, estimated savings, and currency when available; `undefined` when no usage is supplied. |
+| `cacheUsageReport(usage, model?)` | Normalized reported read/write tokens, hit rate, estimated savings, and currency when available; `undefined` when no cache token field is reported. Missing fields stay absent, never become `0`. |
 
-Provider events do not change. Cache accounting stays in normalized `Usage.cacheReadTokens` and `Usage.cacheWriteTokens`.
+Cache accounting stays in normalized `Usage.cacheReadTokens` and `Usage.cacheWriteTokens`. Terminal `provider_turn_finished.metadata.cache` carries the same numeric report for a reporting provider; unavailable cache usage stays absent.
 
-For stable-prefix payloads, `inputLayout: "cache_aware"` is the default on the default input builder, `assembleProviderInput()`, `AgentConfig`, and `RunOptions`; set `inputLayout: "legacy"` to restore the prior order. The default prompt builder's cache-aware order is leading system instructions → resolved context blocks → selected/progressively disclosed skills → fallback text tool declarations → attachments/resources → summaries → prior history → pending tool results → current input. Declared tool schemas remain in `ProviderRequest.tools` and are never granted by prompt middleware. First-party tool serializers run `canonicalizeJsonSchema` so property insertion order cannot break that prefix. Changing only current input preserves the serialized message prefix before the final user suffix; changing dynamic context or loaded skills changes only from its own boundary onward, while tool schemas remain independently stable. The prefix is byte-stable only when those stable inputs are unchanged; Prism still does not guarantee provider cache hits.
+For stable-prefix payloads, `inputLayout: "cache_aware"` is the default on the default input builder, `assembleProviderInput()`, `AgentConfig`, and `RunOptions`; set `inputLayout: "legacy"` to restore the prior order. The default prompt builder's cache-aware order is leading system instructions → resolved context blocks → selected/progressively disclosed skill catalogs → fallback text tool declarations → attachments/resources → summaries → prior history → pending tool results → current input → optional session tail. `RuntimeAgentSession` uses that tail for URI resources and loaded skill bodies: first insertion fixes `resource:<uri>` / `skill:<name>` order, so a later skill load appends instead of rewriting its catalog slot. Re-deriving the same id keeps its position; changed bytes explicitly invalidate from that tail segment. Declared tool schemas remain in `ProviderRequest.tools` and are never granted by prompt middleware. First-party tool serializers run `canonicalizeJsonSchema` so property insertion order cannot break that prefix. Context-budget eviction, custom builders/middleware, `toolResultFold`, and attention compilation are explicit invalidation boundaries; folding cannot move to an append-only tail without retaining the raw payload it exists to remove. The prefix is byte-stable only when those stable inputs are unchanged; Prism still does not guarantee provider cache hits.
 
 ## Request/response example
 
@@ -128,7 +128,7 @@ const retention = mapCacheRetention(hints.retention, model);
 const stamped = applyCacheControl(messages, hints.breakpoints ?? [], { maxBreakpoints: model.cache?.maxBreakpoints });
 const hitRate = cacheHitRate({ inputTokens: 1000, cacheReadTokens: 800 });
 const report = cacheUsageReport({ inputTokens: 1000, cacheReadTokens: 800 }, model);
-// { cacheReadTokens: 800, cacheWriteTokens: 0, hitRate: 0.8, ... }
+// { cacheReadTokens: 800, hitRate: 0.8, ... }
 
 await session.run("Explain this", { inputLayout: "cache_aware" });
 ```

package/docs/provider-conformance.md

@@ -223,6 +223,22 @@ Canonical contract: [Thinking and reasoning](thinking-and-reasoning.md).
 
 Canonical contract: [AI SDK provider adapter](providers/ai-sdk.md).
 
+## Stop-reason checklist
+
+Every adapter that parses a native completion reason must map it through the shared
+`mapProviderStopReason` table and emit it on the normalized `done` event
+(`providerDone(usage, mapped)`); `provider_turn_finished.metadata.stopReason` then carries it to
+hosts (see [Agent events](agent-events.md#outputs--response--events)). Cover:
+
+1. **One mapped native reason per protocol** — a fake stream whose wire reason means truncation
+   (`finish_reason: "length"`, `stop_reason: "max_tokens"`, `finishReason: "MAX_TOKENS"`,
+   Converse `stopReason: "max_tokens"`) reaches `done.stopReason === "max_output_tokens"`.
+2. **Tool-call turns** — a native tool reason (`tool_calls` / `tool_use` / `tool-calls`) maps to
+   `tool_calls`; a generic completion reason on a turn that produced tool calls is normalized to
+   `tool_calls` by the session, not the adapter.
+3. **Unknown degrades** — a new or unmapped wire value yields `unknown` and never fails the stream.
+4. **No extra fields** — the adapter adds nothing else to `done`; redaction and bounds are unchanged.
+
 ## Extension and configuration notes
 
 The helpers are a testing subpath only. Provider packages can use them with their own mocked fetch/transport or `createMockProvider()`. Live provider tests should stay opt-in and env-gated outside Prism's default test suite.

package/docs/provider-layer.md

@@ -127,7 +127,7 @@ const agent = createAgent({ model: { provider: own.id, model: "demo" }, provider
 
 - Registry `resolve()` returns the matching provider/model or throws before any provider `generate()` call.
 - Provider event helpers return plain `ProviderEvent` objects.
-- `providerError()` converts unknown errors to redacted `ErrorInfo` through `errorToErrorInfo()` and preserves safe string/number `code` fields for retry classification.
+- `providerError()` converts unknown errors to redacted `ErrorInfo`, preserves safe string/number `code` fields for retry classification, and stamps advisory `failureClass` (`quota`, `auth`, `rate_limited`, `transient`, `permanent`, or `unknown`) from already-captured status/body evidence. It never changes retry behavior or exposes response bodies/headers; see [Runs and usage ledger](runs-and-usage.md#provider-failure-classes).
 - `createMockProvider()` returns an `AIProvider` whose `generate()` yields the scripted events in order and checks `request.signal?.aborted` before each event.
 - The agent/session runtime passes its per-run abort signal as `ProviderRequest.signal`. `ProviderRequestOptions.structuredOutput` requests provider-native JSON-schema output when the model declares `capabilities.structuredOutput`; unsupported models fail before fetch. Timeouts are host-owned: pass `RunOptions.signal`/host abort controllers; retries are runtime-owned via `AgentConfig.retry`/`RunOptions.retry`. Provider-level timeout/retry hints were removed in 0.1.5.
 
@@ -200,7 +200,7 @@ for await (const event of resolvedProvider.generate({
 - `createMockProvider()` uses scripted events only: no timers, credentials, SDKs, or network.
 - Do not hide real secrets in mock event fixtures. If an error event must include secret-like text, use fake placeholders and redaction helpers.
 - `providerError(error, secrets)` only redacts the provided secret values. It is not a general secret scanner.
-- Providers may set safe `ErrorInfo.code` values such as `429`, `503`, or `ETIMEDOUT`; retry policy code treats them as classification hints, not trusted provider metadata.
+- Providers may set safe `ErrorInfo.code` values such as `429`, `503`, or `ETIMEDOUT`; retry policy code treats them as classification hints, not trusted provider metadata. The shared `classifyProviderFailure()` transport helper maps those already-captured values to advisory run outcome metadata; `unknown` is always the fallback.
 
 ## Related APIs