@arnilo/prism 0.0.96 → 0.1.1

package/docs/resource-loading.md

@@ -87,6 +87,8 @@ console.log(bytes.byteLength, manifest.name, prompt);
 - Helpers do not choose a loader by URI scheme. Hosts can use contribution registries or their own routing when they need that.
 - Helpers do not execute loaded text or imported modules. Package activation remains a host decision.
 - `loadManifestResource()` only validates manifest data; it does not register manifest contributions.
+- `@arnilo/prism-rag` `createResourceDocumentLoader({ loader, context? })` is the RAG bridge for an already-authorized artifact. It calls the supplied `ResourceLoader` once for a caller-selected URI, preserves text/binary media type, and adds no URI routing, local-file discovery, or network fallback. Pair it with a bounded RAG `Parser`; `replaceDocument()` then chunks and atomically replaces one exact RAG source.
+- For public web documents, use `createWebFetchDocumentLoader({ fetcher })` with a host-configured `@arnilo/prism-web-tools` fetch adapter instead of adding web I/O to a `ResourceLoader`. It reuses normalized citation/trust data; the web adapter retains DNS/SSRF policy ownership.
 
 ## Security and performance notes
 
@@ -96,6 +98,7 @@ console.log(bytes.byteLength, manifest.name, prompt);
 - Helpers call `loader.load()` once per helper call and do not cache, scan, list, watch, poll, or discover packages.
 - JSON parsing fails closed for invalid JSON or non-object JSON.
 - Do not put resolved credential values, tokens, headers, or executable code in loaded config, manifests, prompts, skills, or metadata.
+- A RAG resource loader is not permission escalation: pass the same host-owned trust/permission context used for any resource load. HTML/PDF parser output and web content are untrusted inert text; compressed/scanned PDFs require a host parser rather than partial fallback.
 
 ## MCP resources
 

package/docs/runs-and-usage.md

@@ -286,6 +286,7 @@ console.log(cacheUsageReport(aggregate?.usage));
 - **Idempotency is host-owned.** The runtime writes the key into `RunRecord.idempotencyKey`; enforcing unique keys and deduplicating retries is the host adapter's responsibility.
 - **Tenant isolation.** `OwnershipScope` fields are copied from the active ownership scope, but the runtime does not enforce tenant isolation for ledger rows. Feedback is stricter: append/query/delete require tenant plus account/user, and first-party stores compare the exact scope to the linked run.
 - **Feedback privacy.** Comments/tags/metadata can contain PII. Configure a feedback redactor, apply retention, and call owned `delete()` for erasure. Never copy comments or tag values into metric labels.
+- **Policy audit is separate.** Enterprise allow/deny/modify/approval rows with evidence refs live in optional `@arnilo/prism-policy`, not `RunLedger`. See [Policy and audit](policy-and-audit.md).
 
 ## Optional batching and durability
 
@@ -304,6 +305,7 @@ Runtime session snapshots cache one leaf/generation for at most one second. Succ
 
 ## Related APIs
 
+- [Policy and audit](policy-and-audit.md): optional enterprise decision ledger (separate from run usage rows).
 - [Performance limits](performance.md): batching, cursor keys, and production sizing assumptions.
 - [Agent/session runtime](agent-session-runtime.md): `session.run()` and runtime event emission.
 - [Agent events](agent-events.md): `AgentEvent` union and `session.subscribe()`.
@@ -315,3 +317,4 @@ Runtime session snapshots cache one leaf/generation for at most one second. Succ
 - [Provider caching](provider-caching.md): cache hints and `cacheUsageReport()` diagnostics.
 - [Observability](observability.md): `provider_turn_*` events, tool duration metadata, OpenTelemetry adapter.
 - [Public contracts](public-contracts.md): full contract inventory.
+- [Frontend interoperability (AG-UI and ACP)](ag-ui.md): `AgentEventRecord` pages become redacted, ownership-scoped, at-least-once replay only through an explicit host adapter.

package/docs/server.md

@@ -2,9 +2,9 @@
 
 ## What it does
 
-`@arnilo/prism-server` exposes explicitly selected agents and workflows through one framework-free `(Request) => Promise<Response>` handler. It supports direct agent results, bounded agent/workflow SSE, opt-in durable agent status/resume, durable workflow start/enqueue/status/cancel/resume/replay, ownership-scoped schedules, host authorization, ownership propagation, redaction, and resource ceilings.
+`@arnilo/prism-server` exposes explicitly selected agents and workflows through one framework-free `(Request) => Promise<Response>` handler. It supports direct agent results, bounded agent/workflow SSE, cross-replica durable agent-event reconnect, opt-in durable agent status/resume, durable workflow start/enqueue/status/cancel/resume/replay, ownership-scoped schedules, host authorization, ownership propagation, redaction, resource ceilings, and optional deployment seams (health/readiness, drain, host rate-limit adapter, ownership-scoped event replay, worker/coordinator lease election).
 
-No listener starts on import. Empty `agents`/`workflows` maps expose nothing. Authentication, authorization, route selection, durable stores, TLS, rate limiting, and framework/serverless adaptation remain host-owned.
+No listener starts on import. Empty `agents`/`workflows` maps expose nothing. Authentication, authorization, route selection, durable stores, TLS, distributed rate limiting, queues, and framework/serverless adaptation remain host-owned.
 
 ## When to use it
 
@@ -15,15 +15,19 @@ Use `AgentSession` or workflow APIs directly for in-process applications. Do not
 ## Inputs / request
 
 ```ts
+const drain = createPrismDrainController({ deadlineMs: 30_000 });
 const handler = createPrismHandler({
-  agents?: Record<string, Agent | PrismAgentExposure>,
+  agents?: Record<string, Agent | PrismAgentExposure>, // exposure may include events + resolveRun
   agentRuns?: Record<string, PrismAgentRunExposure>, // explicit durable status/resume only
   workflows?: Record<string, PrismWorkflowExposure>,
   schedules?: WorkflowSchedules | ((authorization, signal) => WorkflowSchedules),
   authorize: async ({ request, operation, capabilityId }) => false | {
     ownership: { tenantId?: string; accountId?: string; userId?: string },
+    identity?: AgentIdentity, // optional host-verified; must match ownership
     metadata?: Record<string, unknown>,
   },
+  drain?, // blocks admit ops with 503 while draining
+  rateLimit?, // host adapter after authorize, before session/run create
   basePath?: "/prism",
   allowedHosts?: string[],
   allowedOrigins?: string[],
@@ -31,6 +35,7 @@ const handler = createPrismHandler({
   limits?: PrismServerLimits,
   disconnectAborts?: boolean,
 });
+const health = createPrismHealthHandler({ ready: () => store.ping(), drain });
 ```
 
 At least one non-empty ownership field must come from `authorize()`. Request JSON never chooses ownership.
@@ -41,6 +46,7 @@ At least one non-empty ownership field must come from `authorize()`. Request JSO
 | `POST /prism/agents/:id/stream` | `agent.stream` | same; SSE response |
 | `GET /prism/agents/:id/runs/:runId` | `agent.status` | none; redacted public state/version only |
 | `POST /prism/agents/:id/runs/:runId/resume` | `agent.resume` | `{ "decision": "approve" | "deny", "expectedVersion": number }` |
+| `GET /prism/agents/:id/runs/:runId/events?cursor=` | `agent.events` | none; durable SSE, also accepts `Last-Event-ID` |
 | `POST /prism/workflows/:id/runs` | `workflow.run` | `{ "input": unknown, "runId"?: string }` |
 | `POST /prism/workflows/:id/stream` | `workflow.stream` | same; SSE response |
 | `POST /prism/workflows/:id/enqueue` | `workflow.enqueue` | `{ "input": unknown, "runId"?: string }`; returns `202` queued handle |
@@ -59,7 +65,7 @@ POST routes require `Content-Type: application/json`. Capability/run IDs are bou
 
 ## Outputs / response / events
 
-Direct routes return bounded JSON. Stream routes return `text/event-stream`; every event is one `data: <AgentEvent|WorkflowEvent>` frame. Status returns the ownership-scoped durable checkpoint record. Resume uses Phase 8 expected-version CAS. Cancel aborts active work or marks eligible durable checkpoints aborted.
+Direct routes return bounded JSON. New-run stream routes return `text/event-stream`; every event is one `data: <AgentEvent|WorkflowEvent>` frame. Durable event reconnect frames add `id: <opaque source cursor>` before `data: <AgentEvent>` and resume strictly after either matching `?cursor=` or `Last-Event-ID`. Conflicting header/query cursors fail before source access. Status returns the ownership-scoped durable checkpoint record. Resume uses Phase 8 expected-version CAS. Cancel aborts active work or marks eligible durable checkpoints aborted.
 
 Errors use `{ "error": { "code", "message" } }`. Unknown routes/capabilities are `404`, authorization/policy denial `403`, malformed input `400`, unsupported content type `415`, body overflow `413`, concurrency overflow `429`, and result overflow `507`. Unexpected errors are generic and never include stacks.
 
@@ -103,6 +109,7 @@ const handler = createPrismHandler({
 - Workflow exposure requires its existing `WorkflowCheckpointAdapter`; no server-owned database exists.
 - Schedule exposure is optional and may be one service or an authorization-selected resolver. Returned service ownership must exactly match authorized tenant/account/user scope; otherwise request is forbidden.
 - `PrismWorkflowExposure.runOptions` can supply agent/tool/policy/resume-validator wiring. Server-owned ownership, signal, checkpoint, redactor, run ID, and event bus fields cannot be overridden.
+- The agent resume endpoint (`/prism/agents/{id}/runs/{runId}/resume`) accepts `{ decision: "approve" | "deny" }` or `{ decisions: [{ approvalId, outcome, reason?, modifiedArguments?, elicitation? }] }` next to `expectedVersion` — exactly one of `decision`/`decisions`. Entries are validated at the boundary (count ≤ 128, four outcomes, bounded reason/payloads) and core applies them atomically under the run's CAS; unknown ids, stale versions, and malformed batches fail closed without touching the run.
 - Host/origin checks and CORS headers activate only when their allow-lists are configured. Hosts still own reverse-proxy trust and canonical host handling.
 
 Default/hard ceilings:
@@ -117,14 +124,39 @@ Default/hard ceilings:
 | concurrent runs | 16 | 256 |
 | subscriber queue | 128 | 4,096 |
 | request/run timeout | 120 s | 30 min |
+| health response | 4 KiB | 64 KiB |
+| drain admit cutoff | 30 s | 5 min |
+| replay page / cursor | 100 / 4 KiB | 500 / 16 KiB |
+
+## Deployment seams (optional)
+
+Compose beside `createPrismHandler` — Prism starts no listener, container orchestrator, or queue worker.
+
+| Helper | Role |
+| --- | --- |
+| `createPrismHealthHandler` | `GET /health`, `/livez`, `/readyz`. Minimal JSON; `?detail=1` requires `authorizeDetail`. No secrets/tenant payloads by default. Ready fails while draining. |
+| `createPrismDrainController` | `beginDrain()` rejects admit ops (`agent.run`/`stream`/`resume`, workflow run/stream/enqueue/resume/replay, schedule create/trigger) with `503 ERR_PRISM_SERVER_DRAINING`. Status/cancel/list stay open. |
+| `rateLimit` on handler | Host adapter after authorize, before session create. Return denial `{ retryAfterMs, code, message }` → `429` + optional `Retry-After`. `createMemoryRateLimiter` is single-process only. |
+| `createPrismAgentEventReplay` | Shared `AgentEventSource` page/follow semantics for exact-owned runs. |
+| `createPrismEventReplay` / `createPrismReplayHandler` | Compatible ownership-scoped legacy `queryEvents` pages (`redacted: true`). Does not re-run work. Unauthorized replay denies. |
+| `createPrismDeploymentLease` | Lease election under `prism.server.deployment`. Coordinator replica holds `key: "coordinator"` before schedule ticks; workers run `@arnilo/prism-workflows` `createWorkflowCoordinator` for queued runs (fencing tokens). |
+| `createConversationService` / `createConversationHandler` | Durable user-scoped conversation threads (create/list/continue/branch/archive/export/delete) over session + event-ledger seams, with thread-bound reconnectable replay. Mounts beside the handler; see [Conversations](conversations.md). |
+| `createArtifactService` / `createArtifactHandler` | Durable artifact co-work review (attach/revise/compare/approve/reject/last-validated/delivery-link + authorized download) over the versioned checkpoint store; records persist metadata/revisions/approvals only, never file bodies. Mounts beside the handler; see [Work artifacts and review](work-artifacts-and-review.md). |
+
+**Queues:** Redis/SQS/other adapters are absent. Postgres checkpoint polling via `createWorkflowCoordinator` remains the default background path until a measured polling/load justification is recorded.
+
+Network-free demo: [`examples/server-deployment-seams.ts`](../examples/server-deployment-seams.ts).
 
 ## Security and performance notes
 
 - `authorize()` is required and runs for every matched operation before capability lookup or body execution. Return `false` on missing/invalid credentials. Do not trust caller ownership fields.
+- Optional `authorization.identity` must be host-verified (`AgentIdentity.verified`); the handler asserts activity and ownership match, then forwards identity into agent runs. Caller-asserted identity without a host verifier is rejected.
 - Use authorization metadata only for non-secret audit context. Never put credentials in metadata, input, route IDs, run IDs, checkpoints, events, or responses.
 - Configure `SecretRedactor` before runs. Redaction matches known secrets; it is not DLP.
 - Agent tools and workflow tool nodes still need their own `PermissionPolicy`, `ToolValidator`, and `ExecutionPolicy`. HTTP authorization does not replace side-effect policy.
-- Host and origin allow-lists are exact string matches. Configure reverse-proxy normalization, TLS, rate limiting, IP policy, CSRF/cookie policy, and authentication outside Prism.
+- Host and origin allow-lists are exact string matches. Configure reverse-proxy normalization, TLS, IP policy, CSRF/cookie policy, and authentication outside Prism. Optional `rateLimit` is an attributable short-circuit only — not a WAF.
+- Health endpoints reveal process/liveness only by default; detail flags require host authorize and must omit secrets/tenant dumps.
+- Drain and event replay require the same ownership/authorize boundary as other routes; replay never invokes providers or tools. Durable event routes exist only on object `PrismAgentExposure` entries with both `events` and `resolveRun`; every reconnect authorizes again, resolves public run ID to exact internal session/run IDs, and opens the shared source without `sessionFactory`.
 - SSE uses bounded upstream subscriber queues. Consumer cancellation aborts owned work by default and releases concurrency; set `disconnectAborts: false` only when the host deliberately owns background completion.
 - Source inputs/resource URLs remain host responsibilities and use existing resource/media SSRF policies. Server package does not fetch URLs.
 - Schedule routes never accept ownership from JSON. Services carry mandatory ownership and explicit workflow/calculator registries; route authorization cannot broaden either. Replay applies workflow ownership/hash/approval checks.
@@ -134,9 +166,15 @@ A2A routes are not added to `createPrismHandler()`. Install `@arnilo/prism-super
 
 ## Related APIs
 
+- [Agent identity](agent-identity.md): optional verified identity on authorize results.
+- [Performance](performance.md): capacity notes for concurrent runs and deployment probes.
 - [Agent/session runtime](agent-session-runtime.md): direct result and event stream semantics.
-- [Workflows](workflows.md): durable checkpoints, status, cancellation, and exact-once resume.
+- [Workflows](workflows.md): durable checkpoints, status, cancellation, exact-once resume, and `createWorkflowCoordinator` workers.
 - [MCP client and server exposure](mcp-tools.md): selected MCP capabilities and web-standard MCP transport.
 - [Host security guide](host-security.md): remote-boundary checklist.
 - [A2A interoperability](a2a.md): separately mounted A2A 1.0 handler/client.
+- [Conversations](conversations.md): durable user-scoped conversation service, replay, branches, export, deletion.
+- [Work artifacts and review](work-artifacts-and-review.md): durable artifact review service, revisions, approvals, authorized expiring delivery links.
+- [Frontend interoperability (AG-UI and ACP)](ag-ui.md): separately installed authorized AG-UI Web handler.
+- [AG-UI adoption evaluation](ag-ui-adoption.md): official 0.0.57 support matrix and MCP/A2A follow-up scope.
 - [Release and install](release-and-install.md): optional package installation and profiles.

package/docs/session-store-conformance.md

@@ -25,6 +25,8 @@ Use this helper when implementing a DB-backed `SessionStore` (for example, the r
 - session ids remain isolated (`assertSessionStoreConforms` always probes a secondary session)
 - optional concurrent fork children of the same parent succeed when `exerciseConcurrentParentAppend: true`
 - optional durable reopen/idempotency survival when `runSessionStoreConformance(..., { exerciseReopen: true })`
+- optional `searchSessions` bounds/ownership/empty-page checks when `exerciseSearchSessions: true` (`assertSessionStoreSearchSessions`)
+- optional `searchSessions` bounds/ownership/empty-page checks when `exerciseSearchSessions: true` (`assertSessionStoreSearchSessions`)
 
 ## Inputs / request
 

package/docs/session-stores.md

@@ -24,13 +24,16 @@ import type { SessionStore, SessionEntry } from "@arnilo/prism";
 | `list(sessionId)` | Return all entries for one session in stored order. Development fallback for branch reads. |
 | `get?(id)` | Return one entry by id, if present. Optional. |
 | `readBranchPath?(query)` | Optional DB-friendly branch read. Return one branch's ancestor chain as a `PersistencePage<SessionEntry>` so the runtime can avoid `list(sessionId)`. |
+| `searchSessions?(query)` | Optional bounded session search (`SessionSearchQuery` → `PersistencePage<SessionSearchHit>`). SQLite/Postgres implement FTS + metadata filters; memory default is linear; JSONL throws `SessionSearchUnsupportedError`. |
 
 Public helpers:
 
 | Helper | Purpose |
 | --- | --- |
 | `createSessionEntry(options)` | Build a `SessionEntry` with generated `id`/`timestamp` when omitted. |
-| `createMemorySessionStore(initialEntries?)` | Built-in in-memory `SessionStore`. |
+| `createMemorySessionStore(initialEntries?, options?)` | Built-in in-memory `SessionStore`. `options.sessionSearchMode`: `"linear"` (default) or `"unsupported"` (throws `SessionSearchUnsupportedError`). |
+| `resolveSessionSearchQuery(query)` | Validate/clamp search limits (page, query bytes, snippet, cursor, linear/FTS caps). |
+| `SessionIndex` | Narrow search seam (`search(query)`); adapters may expose this instead of `SessionStore.searchSessions`. |
 | `getSessionBranchEntries(entries, options)` | Return root-to-leaf entries for a leaf id (sync array path). |
 | `getSessionBranchEntries(reader, query)` | Async overload for a `BranchReader` / `readBranchPath` implementation. |
 | `listSessionBranches(entries)` | List every branch handle as `{ leafId, entries }`. Pair with `sessionId` for a durable `(sessionId, leafId)` branch handle. |
@@ -97,7 +100,7 @@ await store.append(entry, options);
 }
 ```
 
-Recognize it with `isSessionAppendConflict(error)`, not message text. Built-in stores reject duplicate entry ids, dangling `expectedParentId` values, and exact idempotency retries. They allow two distinct children of the same existing parent because that is a branch/fork, not parent-order corruption. Production stores may add a stricter branch-tip compare-and-swap when a host wants one-writer linear branches.
+Recognize it with `isSessionAppendConflict(error)`, not message text. Built-in stores reject duplicate entry ids, dangling `expectedParentId` values, and `expectedParentId` pointing at another session's entry (the parent must exist in the same session — a cross-session parent would be a write no per-session branch walk could read back), and exact idempotency retries. They allow two distinct children of the same existing parent because that is a branch/fork, not parent-order corruption. Production stores may add a stricter branch-tip compare-and-swap when a host wants one-writer linear branches.
 
 ## Extension and configuration notes
 
@@ -107,6 +110,42 @@ Recognize it with `isSessionAppendConflict(error)`, not message text. Built-in s
 - Branch semantics are parent links plus a leaf id. External UIs should keep branch handles as `(sessionId, leafId)`; RPC exposes an additional `handleId` for active handles.
 - Development stores can omit `readBranchPath`; the runtime falls back to `list(sessionId)` and the pure in-memory branch walk. Database-backed stores should implement `readBranchPath` so `entries()`, `clone()`, and context rebuild read only the selected ancestor chain.
 
+## Session search (0.0.11)
+
+Bounded `SessionIndex` / `searchSessions` lists sessions by optional `workspaceRoot` (`metadata.workspaceRoot`), provider/model, label/summary, time range, ownership, and optional text `query` (FTS on SQLite/Postgres; case-sensitive substring on memory linear). Hits require `sessionId` and may include `leafId` for `checkout`; never credentials or whole transcripts.
+
+```ts
+import { createMemorySessionStore, resolveSessionSearchQuery } from "@arnilo/prism";
+
+const store = createMemorySessionStore([], { sessionSearchMode: "linear" });
+const page = await store.searchSessions!({
+  workspaceRoot: "/repo",
+  query: "flake",
+  limit: 20,
+});
+// Opt out: createMemorySessionStore([], { sessionSearchMode: "unsupported" })
+```
+
+Finite caps (defaults / hard): page 20/100; query string 4 KiB/16 KiB; snippet 512 B/4 KiB; cursor 1 KiB/4 KiB; memory linear sessions 1000/5000, entries 10000/50000, bytes 8 MiB/64 MiB; DB FTS candidates 1000/5000. Overflow fails closed via `resolveSessionSearchQuery`. See [Phase 6 evidence](review-coverage-2026-07-22-phase-6.md).
+
+## Session search (0.0.11)
+
+Bounded `SessionIndex` / `searchSessions` lists sessions by optional `workspaceRoot` (`metadata.workspaceRoot`), provider/model, label/summary, time range, ownership, and optional text `query` (FTS on SQLite/Postgres; case-sensitive substring on memory linear). Hits require `sessionId` and may include `leafId` for `checkout`; never credentials or whole transcripts.
+
+```ts
+import { createMemorySessionStore, resolveSessionSearchQuery } from "@arnilo/prism";
+
+const store = createMemorySessionStore([], { sessionSearchMode: "linear" });
+const page = await store.searchSessions!({
+  workspaceRoot: "/repo",
+  query: "flake",
+  limit: 20,
+});
+// Opt out: createMemorySessionStore([], { sessionSearchMode: "unsupported" })
+```
+
+Finite caps (defaults / hard): page 20/100; query string 4 KiB/16 KiB; snippet 512 B/4 KiB; cursor 1 KiB/4 KiB; memory linear sessions 1000/5000, entries 10000/50000, bytes 8 MiB/64 MiB; DB FTS candidates 1000/5000. Overflow fails closed via `resolveSessionSearchQuery`. See [Phase 6 evidence](review-coverage-2026-07-22-phase-6.md).
+
 ## Security and performance notes
 
 - Do not store provider credentials, credential resolvers, provider instances, or unredacted secrets in session entries, append options, idempotency keys, or branch records.

package/docs/sqlite-persistence.md

@@ -4,7 +4,7 @@
 
 The optional `@arnilo/prism-session-store-sqlite` package ships a production-oriented SQLite adapter that implements:
 
-- `SessionStore` — atomic `append` / `list` / `get` / `readBranchPath`
+- `SessionStore` — atomic `append` / `list` / `get` / `readBranchPath` / bounded `searchSessions` / bounded `searchSessions`
 - `RunLedger` — durable run, event, tool-call, and usage rows
 - `ProductionPersistenceStore` — cursor-paginated `query*` reads plus generic `checkpoints` and atomic `leases` capabilities
 
@@ -56,7 +56,7 @@ import { createSqlitePersistence } from "@arnilo/prism-session-store-sqlite";
 | `leases` | Atomic `LeaseStore` backed by `prism_leases`; database-clock expiry, opaque renew/release token, monotonic takeover fence. |
 | `close()` | Closes the underlying database when the adapter opened it. |
 
-Migrations run automatically on open and are idempotent across reopen. Under the SQLite migration transaction, startup checks ordered contract name/version/SHA-256 rows plus full schema-v3 PRAGMA/catalog shape (all required tables, columns/types/nullability/defaults, PK/unique/FK keys, and named indexes) before any runtime write. A complete legacy 0.0.5 history with all `checksum` values `NULL` is shape-verified then backfilled transactionally once. Unknown, duplicate, out-of-order, partial-legacy, checksum, or shape drift rejects open; restore or apply reviewed DDL rather than editing migration rows.
+Migrations run automatically on open and are idempotent across reopen. Under the SQLite migration transaction, startup checks ordered contract name/version/SHA-256 rows plus full schema-v6 PRAGMA/catalog shape (all required tables, columns/types/nullability/defaults, PK/unique/FK keys, and named indexes) before any runtime write. A complete legacy 0.0.5 history with all `checksum` values `NULL` is shape-verified then backfilled transactionally once. Unknown, duplicate, out-of-order, partial-legacy, checksum, or shape drift rejects open; restore or apply reviewed DDL rather than editing migration rows.
 
 ## Request/response example
 
@@ -99,9 +99,17 @@ For resume/timeline flows, use `queryRuns`, `queryEvents`, `queryToolCalls`, and
 - The package is optional and workspace-local; `@arnilo/prism` core has no SQLite dependency.
 - Hosts choose the database path and own backup, retention enforcement, and filesystem permissions.
 - `SessionAppendOptions` idempotency rows are durable in `prism_session_append_idempotency` and survive reopen.
-- Schema version **3** applies `001_init`, additive `002_usage_scope`, and `003_run_feedback`. Migration 003 adds immutable `prism_run_feedback` rows with run FK/cascade deletion and owner/run/trace cursor indexes. `persistence.feedback` validates exact run ownership, bounds/redacts through optional `feedbackRedactor`, queries bounded pages, and deletes only exact-owned IDs. PostgreSQL shares the same model with dialect-local DDL.
+- Schema version **6** applies `001_init`, `002_usage_scope`, `003_run_feedback`, `004_session_search`, `005_lifecycle_hold_quota`, and `006_agent_event_source`. Migration 006 backfills `prism_agent_event_streams` and uses it to allocate unique per-run event sequences inside the SQLite append transaction. It is sequence-compatible with PostgreSQL but remains local/file-backed; it does not expose distributed subscriptions. Migration 003 adds immutable `prism_run_feedback` rows with run FK/cascade deletion and owner/run/trace cursor indexes. Migration 004 adds session search FTS (FTS5 virtual table `prism_session_search_fts` dual-written on append) plus `prism_sessions(updated_at, id)` cursor index; existing entries are backfilled once. `persistence.feedback` validates exact run ownership, bounds/redacts through optional `feedbackRedactor`, queries bounded pages, and deletes only exact-owned IDs. Search hits never include credentials; ownership filters apply when present. PostgreSQL shares the same model with dialect-local DDL.
 - Pass an existing `better-sqlite3` `Database` via `database` when your host already manages connections.
 
+## Durable events
+
+SQLite applies migrations **006**/**007** for per-run event sequence compatibility and the owner retention index. It does **not** provide cross-process subscribe/LISTEN; use PostgreSQL for distributed reconnect.
+
+## Durable events
+
+SQLite applies migrations **006**/**007** for per-run event sequence compatibility and the owner retention index. It does **not** provide cross-process subscribe/LISTEN; use PostgreSQL for distributed reconnect.
+
 ## Security and performance notes
 
 - **Parameterized SQL only.** Session ids, idempotency keys, tenant ids, and JSON payloads are bound parameters.

package/docs/structured-output.md

@@ -49,8 +49,11 @@ await session.run(input, {
     parser,            // optional; default treats assistant text as the value
     repairer,          // optional; default stringifies validation.errors[].message
     maxRevisions: 3,   // optional; default 3
+    toolCalls: "bounded", // optional; default "disabled"
     structuredOutput: { name: "answer", schema, strict: true }, // optional native mode
     structuredOutputMode: "native", // or "artifact-loop" to skip provider-native schema
+    // Opt-in: schema only on artifact/revision turns (tools free on earlier turns).
+    structuredOutputTiming: "final-turn-only", // default "every-turn"
   },
   providerOptions: {
     structuredOutput: { name: "answer", schema, strict: true }, // direct native request
@@ -58,6 +61,8 @@ await session.run(input, {
 });
 ```
 
+`structuredOutputTiming: "final-turn-only"` (with `toolCalls: "bounded"` and native schema) sends tool-eligible turns **without** `response_format` so models can call tools; once the model returns a call-free candidate (or tool rounds are exhausted), the next turn withdraws tools and attaches schema. Revision turns stay schema-on / tools-off. Default `"every-turn"` keeps legacy behavior (schema on every provider request).
+
 ## Outputs / response / events
 
 `generateValidateReviseLoop.run(ctx)` returns `Promise<Usage | undefined>`. Observable behavior is emitted through `AgentEvent` artifact variants (zero emitted by `singleShotLoop`):
@@ -230,11 +235,12 @@ Key cross-seam points:
 
 - `generate-validate-revise` is selected via `AgentConfig.loop` / `RunOptions.loop` (`RunOptions.loop` wins). See [Agent loops](agent-loops.md). `resolveLoop()` maps the options form to the factory; an unknown `strategy` throws before the first turn; a custom `AgentLoopStrategy` instance bypasses the options form.
 - Native structured output uses provider-neutral `StructuredOutputOptions` on `ProviderRequestOptions` / loop options. Capable OpenAI-family providers map to JSON-schema wire fields; unsupported models fail before fetch unless the host sets `structuredOutputMode: "artifact-loop"` and relies on parser/validator/repairer only.
+- `structuredOutputTiming: "final-turn-only"` (opt-in; default `"every-turn"`) with `toolCalls: "bounded"` omits native schema on tool-eligible turns and attaches schema only on artifact/revision turns (tools withdrawn). Call-free tool-phase output promotes to one schema turn before parse/validate.
 - `validateStructuredOutputOptions()` enforces JSON-safe schemas, forbidden prototype-pollution keys, and a 64 KiB schema size cap.
 - The default parser treats non-empty assistant text as the value (`{ ok: true, value: text }`); empty/whitespace-only call-free text is a `parse_error` before the parser. Supply a host parser whenever `T` is not `string`.
 - The default repairer builds a user message from `validation.errors[].message`; supply a host repairer for schema-specific guidance.
 - `maxRevisions` (default 3) bounds revision turns; budget exhaustion ends the loop and emits `artifact_failed`. Session runs then fail with `AgentRunError` unless `artifact_finished` occurred (direct `loop.run` still returns usage without throwing).
-- Tools are inert in artifact turns unless `loop.toolCalls: "bounded"` is explicit. Bounded mode uses run-global `maxToolRounds`, dispatches calls sequentially through normal runtime guards, skips parser/validator for tool-calling responses, and permits at most `1 + maxRevisions + maxToolRounds` provider turns. An extra tool response yields terminal `artifact_failed` with `result.metadata.reason === "tool_round_limit"` and executes nothing.
+- Tools are inert in artifact turns unless `loop.toolCalls: "bounded"` is explicit. Bounded mode uses run-global `maxToolRounds`, dispatches calls sequentially through normal runtime guards, skips parser/validator for tool-calling responses, and permits at most `1 + maxRevisions + maxToolRounds` provider turns (plus one extra schema turn under `final-turn-only` when a tool-phase call-free draft promotes). An extra tool response yields terminal `artifact_failed` with `result.metadata.reason === "tool_round_limit"` and executes nothing.
 
 ## Security and performance notes
 

package/docs/supervisors.md

@@ -50,10 +50,16 @@ const supervisor = createSupervisor({
 const result = await supervisor.delegate({ childId: "research", input: "Check sources" });
 ```
 
+## Durable child approvals
+
+With `checkpoints` + `definitionRevision`, every child run is durable with `interruptBeforeTool: true`. A child that suspends on pending decisions throws `AgentDelegationSuspendedError` out of `delegate()`; when the delegation runs inside a root agent's tool, core converts it into a root suspension whose `interruption.pendingDecisions` carry hashed root-visible approval ids (`sub_<sha256(runId:childApprovalId)>`) and `attribution.path` (redacted child ids, root first, at most 8 deep). Root decisions route back through the same CAS rules: pass `supervisor.resumeNestedRun` as `resumeNestedRun` in the root run's `runState` and in every `resumeAgentRun` options object. The supervisor rebuilds the child from a bounded delegation mapping stored in the same checkpoint store (child id, delegation/thread ids, redacted input, version), re-runs the `before` hook so its narrowing applies to the resumed run (hooks must be idempotent), and re-attributes re-suspensions recursively, so grandchild decisions surface with the full path. A delegating child's own `interruptBeforeTool` also gates its delegate tool, so hosts approve delegation and the child's own side effects as separate stages. Root `*_for_run` stickies record the attribution path and only match the same delegation path; child stickies live on the child run and expire with it. A root approval never widens the child: the child's narrowed permission re-runs at dispatch. Unknown or foreign nested run ids fail closed with one non-enumerating error. Child factories must return stable configs and a durable (or rebuild-stable) session store for resume to work.
+
 ## Extension and configuration notes
 
 Child factories resolve their own providers/credentials and construct context/memory using the supplied IDs. Parent, child, returned-agent, budget, and hook permission policies are AND-composed. Child/request/hook limits can only lower inherited limits. A nested factory can call the supplied `delegate()`; immutable path state rejects cycles and depth overflow.
 
+Supervisors propagate parent `identity` and `effectStore` to every child agent/run so delegated tool effects stay under the same ownership scope.
+
 ## Security and performance notes
 
 - Child IDs are explicit; no package/provider discovery occurs.
@@ -61,10 +67,12 @@ Child factories resolve their own providers/credentials and construct context/me
 - Tool budget is checked before side effects. Token usage is enforced on terminal aggregate usage and can exceed by at most one provider turn because providers report tokens after generation.
 - Abort and timeout cover hooks, child creation, nested delegation, and the run. Host child code must cooperate with `AbortSignal`.
 - Redaction applies before hook input, run metadata/results, completion hooks, and events. Child credentials are never supplied in delegation context.
+- When forwarding verified identity into children or A2A, use `narrowIdentity` / `assertIdentityPropagation` so scopes and tenant cannot widen across the boundary.
 - Static workflows remain smaller and more reproducible for known graphs.
 
 ## Related APIs
 
+- [Agent identity](agent-identity.md): host-verified identity and narrow delegation.
 - [A2A interoperability](a2a.md): separate remote protocol boundary. `A2ATaskLifecycle` adapts host durable agent/workflow state directly; it does not route A2A execution through local supervisor child planning.
 - [Workflows](workflows.md): preferred deterministic orchestration.
 - [Working and semantic memory](working-and-semantic-memory.md): child scope construction.

package/docs/tool-effects.md

@@ -0,0 +1,95 @@
+# Recoverable tool effects
+
+## What it does
+
+Optional tool-effect contracts record whether a tool call may mutate state and how Prism recovers after crash or duplicate delivery. When a host supplies `effectStore` and a tool declares `effect`, dispatch claims before side effects, marks dispatched before execute, and completes or marks unknown after. Ambiguous outcomes never auto-replay. This is at-least-once claim coordination, not exactly-once delivery.
+
+APIs:
+
+- `ToolEffectDeclaration` / `ToolEffectClassifier` on `ToolDefinition.effect`
+- `ToolEffectStore` (`get` / `begin` / `markDispatched` / `complete` / `fail` / `markUnknown` / `resolveUnknown` / `cleanup`)
+- `createMemoryToolEffectStore()` (in-process reference)
+- `deriveToolEffectKey()` / `toolEffectArgumentsHash()` / `canonicalToolEffectJson()`
+- Enterprise: `createPostgresEnterpriseState().toolEffects`
+
+## When to use it
+
+Use when tools perform local or external mutations and a host needs durable claim/CAS recovery across process restart. Skip for pure observation tools (`kind: "none"`). Keep `session.subscribe()` for live UI; pair durable events with [Agent events](agent-events.md) when reconnecting replicas.
+
+## Inputs / request
+
+| Field | Values | Meaning |
+| --- | --- | --- |
+| `kind` | `none` / `local_mutation` / `external_mutation` | Observation vs local vs external side effect |
+| `idempotency` | `none` / `optional` / `required` / `tool_managed` / `unsupported` | Whether core claims a key |
+| `effectStore` | on `AgentConfig` / `RunOptions` | Opt-in store; required when idempotency is `required` |
+| `context.idempotencyKey` | core-derived only | Model-supplied keys are ignored |
+
+Statuses: `pending` → `dispatched` → `completed` | `failed_retryable` | `failed_terminal` | `unknown`. Expired pending becomes retryable; expired dispatched becomes unknown. Unknown needs operator `resolveUnknown`.
+
+## Outputs / response / events
+
+| Outcome | Behavior |
+| --- | --- |
+| First claim | `begin` acquires; dispatch marks dispatched then executes |
+| Duplicate completed | returns bounded stored result; tool body does not rerun |
+| Ambiguous crash | `unknown` + `ERR_PRISM_TOOL_EFFECT_UNKNOWN`; never silent replay |
+| Unsupported | no store/identity required; host owns recovery |
+
+## Request/response example
+
+```json
+{
+  "kind": "external_mutation",
+  "idempotency": "required"
+}
+```
+
+## Implementation example
+
+```ts
+import { createAgent, createMemoryToolEffectStore, dispatchToolCall } from "@arnilo/prism";
+
+const effectStore = createMemoryToolEffectStore();
+const tool = {
+  name: "mail.send",
+  description: "Send mail",
+  parameters: { type: "object", properties: {} },
+  effect: { kind: "external_mutation", idempotency: "required" },
+  execute: async (_args, context) => ({ toolCallId: context.toolCallId, name: "mail.send", value: { sent: true } }),
+};
+
+const agent = createAgent({ model, provider, tools: [tool], effectStore });
+```
+
+Runnable demo: `examples/distributed-events-and-tool-effects.ts`.
+
+## Extension and configuration notes
+
+| Surface | Classification |
+| --- | --- |
+| Coding read/list/search/glob | `none` / `none` |
+| Coding write/edit/delete/move/git commit | `local_mutation` / `optional` |
+| Coding shell / check | `external_mutation` / `unsupported` |
+| Browser observation | `none` / `none` |
+| Browser mutation | `external_mutation` / `unsupported` |
+| Work connector reads | `none` / `none` |
+| Work connector mutations | `external_mutation` / `tool_managed` (core key + store) |
+| MCP remote tools | host `effect` policy; default unsupported |
+| Supervisor children | inherit parent `identity` + `effectStore` |
+
+## Security and performance notes
+
+- Ownership and verified identity bind every claim key; cursors/keys never select tenants.
+- Results/references are byte-bounded and redacted; oversized writes fail closed.
+- Claim TTL default 15 min (hard 60); attempts default 3 (hard 10); unknown has no auto-expiry.
+- PostgreSQL store uses parameterized CAS; request roles stay `SELECT`/`INSERT`/`UPDATE`/`DELETE` only.
+- Recorded p95 claim/transition ≈ 3.1 ms under Task 0 ceilings — see [performance](performance.md).
+
+## Related APIs
+
+- [Tools](tools.md): dispatch harness that hosts effect claim/recovery.
+- [Agent events](agent-events.md): durable `AgentEventSource` for replica reconnect (separate from effect claims).
+- [Work tools](work-tools.md): connector `tool_managed` reconciliation.
+- [Enterprise PostgreSQL state](enterprise-postgres-state.md): durable `toolEffects` store.
+- [Host security](host-security.md): unknown-outcome fail-closed guidance.

package/docs/tools.md

@@ -237,6 +237,8 @@ await session.run(input, {
 - Prism does not sandbox host tools and does not include built-in app tools.
 - Contribution registration and registry/filter calls do not perform provider calls, credential resolution, resource loading, network, filesystem discovery, or tool execution.
 - Dispatch performs explicit in-memory checks and executes only the selected host-active tool; it adds no retries, queues, timers, or new dependencies.
+- When `effectStore` is configured, dispatch claims before side effects and never auto-replays `unknown` outcomes (see [tool effects](tool-effects.md)).
+- When `effectStore` is configured, dispatch claims before side effects and never auto-replays `unknown` outcomes (see [tool effects](tool-effects.md)).
 
 ## JSON Schema validator limits
 
@@ -255,6 +257,7 @@ createJsonSchemaToolArgumentValidator({
 
 ## Related APIs
 
+- [OpenAPI tools adapter](openapi-tools.md): optional `@arnilo/prism-openapi-tools` `createOpenApiTools` — compile host-selected OpenAPI 3.1 operationIds into bounded `ToolDefinition`s (allow-list only, pinned origin, resolved/bounded schemas, approval + effect-store idempotency on mutations, bounded body/response/retries/pagination, host credential resolver, untrusted output).
 - [Agent/session runtime](agent-session-runtime.md): dispatches complete provider tool calls through the host-active tool harness and returns tool results on the next provider turn.
 - [Public contracts](public-contracts.md): `ToolDefinition`, `ToolRegistry`, `ToolExecutionContext`, `ToolResult`, and tool `AgentEvent` contracts.
 - [Contribution registries](contribution-registries.md): inert extension/package tool contribution storage.
@@ -265,6 +268,8 @@ createJsonSchemaToolArgumentValidator({
 - [Observational memory compaction package](compaction-observational-memory.md): optional exact-id recall tool factory.
 - [Tool execution primitives](tool-execution-primitives.md): JSON Schema adapter, parallelism, MCP bridge, and execution-policy designs.
 - [MCP client bridge](mcp-tools.md): optional remote tool mapping plus separate bounded resource/prompt facades; non-tool MCP capabilities never bypass tool dispatch by masquerading as `ToolDefinition`.
+- [Recoverable tool effects](tool-effects.md): optional `tool.effect` + `effectStore` claim/CAS recovery around dispatch.
+- [Recoverable tool effects](tool-effects.md): optional `tool.effect` + `effectStore` claim/CAS recovery around dispatch.
 - [Coding agent tools](coding-agent-tools.md): optional first-party `@arnilo/prism-coding-agent` `shell`/`read`/`write`/`edit` tools a host registers into this harness.
 
 `DispatchToolCallOptions.trust` and `.permission` run before validation or `execute()`; denial emits `tool_execution_blocked`. Middleware cannot bypass either guard. `AgentConfig.validator`/`RunOptions.validate` run after these guards; their output is redacted through the active `SecretRedactor`. `createSecureAgent()` requires all three seams plus non-empty schemas and durable pre-tool approval. Prism does not sandbox tools. See [Security/auth/trust](settings-auth-trust-security.md).

package/docs/work-artifacts-and-review.md

@@ -0,0 +1,102 @@
+# Work artifacts and review
+
+## What it does
+
+`@arnilo/prism-server` ships a durable artifact co-work review service (Phase 9 / 0.0.14): authorized attach of source/output references with MIME/hash/version, producer-run attribution, citations/data sources, and preview metadata; revision comparison; reviewer approve/reject (request-changes) with last-validated recovery; and authorized, expiring delivery links. Core (`@arnilo/prism`) exports artifact **types only** (`ArtifactRecord`, `ArtifactRevision`, `ArtifactApproval`, `ArtifactDeliveryToken`, approval state `pending | approved | rejected`). Prism persists bounded metadata, revisions, approvals, and delivery references over the existing versioned checkpoint store — **never file bodies**; hosts own blob storage and rendering.
+
+## When to use it
+
+- Durable human-in-the-loop review of agent-produced outputs (drafts, exports, generated files) where users compare revisions, request changes, and approve/reject.
+- Authorized, time-boxed delivery of a validated artifact revision to a downstream consumer.
+- Recovering the last approved ("validated") revision after a later revision is rejected.
+
+Not for: storing file content (use host blob storage), local Office preview/rendering (host-owned), or SaaS connector delivery (see work-connectors).
+
+## Inputs / request
+
+`createArtifactService(store: CheckpointStore, options)`:
+
+| Field | Required | Meaning |
+| --- | --- | --- |
+| `store` | yes | Any `CheckpointStore` (sqlite/postgres `persistence.checkpoints`, or `createMemoryCheckpointStore()` for tests) |
+| `options.redactor` | yes | `SecretRedactor`; records are redacted before persist and on every response |
+| `options.linkSecret` | yes | Host HMAC key material for signing/verifying delivery links |
+| `options.limits` | no | Frozen caps (below); each clamped to a hard maximum |
+| `options.onDecision` | no | Audit seam (redacted refs) for attach/revise/approve/reject; bridge to `@arnilo/prism-policy` |
+
+Every operation input carries `ownership` (from host `authorize`, never request JSON) plus optional verified `identity`. `attach` requires `threadId`, `uri`, `mime`, `hash`; `revise` requires `uri`, `hash` (mime defaults to the previous revision); `compare` requires two distinct revision numbers; `approve`/`reject` require a `version`; `deliveryLink` accepts optional `version` (defaults to last validated, else latest) and `ttlSeconds`.
+
+## Outputs / response / events
+
+| API | Result |
+| --- | --- |
+| `attach` | `ArtifactRecord` with revision 1, pending state (idempotent get-or-create with explicit `id`) |
+| `list` | Ownership/thread-scoped `PersistencePage<ArtifactRecord>` |
+| `get` | `ArtifactRecord` |
+| `revise` | `ArtifactRecord` with an appended revision (new revision resets state to pending) |
+| `compare` | `{ artifactId, from, to, changed: { hash, mime, uri, citations } }` — hash+metadata only |
+| `approve` / `reject` | `ArtifactRecord`; approve advances `lastValidatedVersion`, reject never clears it |
+| `lastValidated` | The last approved `ArtifactRevision` (fails closed before any approval) |
+| `deliveryLink` | `{ link, token }` — signed expiring `ArtifactDeliveryToken` |
+
+No package-owned agent events are emitted; `onDecision` is the audit seam (redacted actor refs only).
+
+## Request/response example
+
+```json
+{
+  "attach": { "threadId": "thread-1", "uri": "https://blob.example/doc-v1", "mime": "text/markdown", "hash": "sha256:aaa" },
+  "compare": { "from": 1, "to": 2, "changed": { "hash": true, "mime": false, "uri": true, "citations": false } },
+  "approve": { "version": 2, "lastValidatedVersion": 2, "approvals": [{ "version": 2, "state": "approved", "reviewer": "user:user-1" }] },
+  "deliveryLink": { "link": "<base64url payload>.<base64url hmac>", "token": { "artifactId": "art_1", "version": 2, "expiresAt": "2026-07-25T04:10:00.000Z" } }
+}
+```
+
+## Implementation example
+
+```ts
+import { createSecretRedactor } from "@arnilo/prism";
+import { createSqlitePersistence } from "@arnilo/prism-session-store-sqlite";
+import { createArtifactService, createArtifactHandler } from "@arnilo/prism-server";
+
+const persistence = createSqlitePersistence({ filename: "prism.db" });
+const artifacts = createArtifactService(persistence.checkpoints, {
+  redactor: createSecretRedactor([/* host secrets */]),
+  linkSecret: process.env.PRISM_ARTIFACT_LINK_SECRET!,
+});
+
+const record = await artifacts.attach({ ownership, identity, threadId: "thread-1", uri: "https://blob.example/doc", mime: "text/markdown", hash: "sha256:aaa" });
+await artifacts.revise({ ownership, threadId: "thread-1", artifactId: record.id, uri: "https://blob.example/doc-v2", hash: "sha256:bbb" });
+await artifacts.approve({ ownership, identity, threadId: "thread-1", artifactId: record.id, version: 2 });
+const { link } = await artifacts.deliveryLink({ ownership, threadId: "thread-1", artifactId: record.id });
+
+// Framework-free HTTP adapter (default base /prism/artifacts); ownership only from authorize.
+export const handler = createArtifactHandler({ service: artifacts, authorize: hostAuthorize, linkSecret: process.env.PRISM_ARTIFACT_LINK_SECRET! });
+```
+
+## Extension and configuration notes
+
+- Artifact records are versioned checkpoint values (namespace `prism.artifact`, key `threadId:artifactId`). The checkpoint `version` is the CAS counter for concurrent reviewers, distinct from revision numbers. Any `CheckpointStore` works; sqlite/postgres persistence already expose `.checkpoints`, so there is no separate artifact schema or migration.
+- `createArtifactHandler` mounts attach/list/get/revise/compare/approve/reject/last-validated/delivery-link plus `GET /prism/artifacts/download?link=…`. Download verifies the link signature + expiry, then **reauthorizes** against the token's ownership (mismatch fails closed), and returns the authorized revision reference only — the host fetches the body.
+- Delivery links are `base64url(payload).base64url(HMAC-SHA256)` over `{ artifactId, threadId, version, ownership, issuedAt, expiresAt }`; they are reauthorized per download and are not bearer secrets.
+- **Blob storage (0.0.28)**: `createArtifactService` accepts an optional `bodies: ArtifactBodyStore` (core contract in `src/artifacts.ts`: `put`/`get`/`delete`/`presign` by opaque, ownership-scoped `ArtifactBodyRef`). When wired, `deliveryLink` resolves through `bodies.presign` and returns an additional `url` (bounded-TTL, single-object presigned URL) beside the signed link/token; revisions must carry a recorded `size` (optional on attach/revise) or delivery fails closed. The reference adapter is `@arnilo/prism-server/artifact-bodies` `createS3ArtifactBodyStore` (hand-rolled SigV4 over native fetch + WebCrypto, path-style, single-chunk PUT with verified `x-amz-content-sha256`; works with AWS S3, MinIO, Cloudflare R2). Hosts may substitute any store; the contract is storage-free in core.
+- Body stores verify ownership on every operation, verify size/SHA-256/MIME on put and get (fail closed), refuse delete under legal hold (host `isHeld` callback), and are idempotent on delete (retention sweeps delete bodies with metadata). Credentials come only from the host resolver; bucket/path/key never appear in errors, telemetry, or artifact records (the object key is derived from the ref).
+- Review loops driven by an agent consume the shared `RunLimits` at the host's agent layer; the artifact service itself is a passive, bounded record store.
+
+## Security and performance notes
+
+- Every operation requires authenticated identity + thread ownership derived from host `authorize`; cross-ownership access fails closed as `not_found` (never leaks existence).
+- Concurrent reviewer conflicts resolve via checkpoint CAS (`expectedVersion`); the loser gets a retryable `conflict` and no approval is lost or duplicated. A throw before commit persists nothing, so failed updates roll back.
+- Local filesystem paths are rejected in `uri`/citations (`file:`, absolute, or drive paths); records are redacted before persist and on response, so paths/secrets/document-private data never enter records, events, or exports.
+- Frozen caps (default / hard): artifacts per thread 64/256; revisions per artifact 32/128; record 8/64 KiB; preview 16/64 KiB; citations 32/128 and 2/8 KiB each; MIME 128/512 B; hash 256/1 KiB; compare exactly 2 revisions; delivery TTL 5 min/24 h; delivery token 4/16 KiB. Raising the revision cap may require raising `recordBytes` (aggregate backstop).
+- Compare is hash+metadata-bounded (hosts render content); no file bodies are persisted or transferred. With a wired body store, bodies live in the host's object store and are streamed through the adapter (bounded by `maxBodyBytes` 64 MiB/512 MiB, concurrent transfers 4/16, presign TTL 10 min/24 h); object-store outages surface typed `ERR_PRISM_S3_*` / `ERR_PRISM_ARTIFACT_BODY_*` errors, never silent success.
+
+## Related APIs
+
+- [Server](server.md): `createArtifactService` / `createArtifactHandler` mount alongside the Prism handler; ownership only from `authorize`.
+- [Conversations](conversations.md): artifact threads reuse conversation thread ownership scoping.
+- [Database persistence](database-persistence.md): artifact records persist as versioned checkpoint values (sqlite/postgres `.checkpoints`).
+- [Workflows](workflows.md): durable suspend/approve seam; hosts may gate revisions behind `tool_approval`.
+- [Policy and audit](policy-and-audit.md): `onDecision` events bridge here for an auditable review ledger.
+- [Host security](host-security.md): identity/ownership, redaction, and expiring-link boundaries.
+- [Frontend interoperability (AG-UI and ACP)](ag-ui.md): projects artifact progress/approval/download-link as redacted co-work events over the durable-resume stream.