@arnilo/prism 0.0.96 → 0.1.0

package/docs/conversations.md

@@ -0,0 +1,135 @@
+# Conversations
+
+## What it does
+
+`@arnilo/prism-server` ships a durable, user-scoped conversation service: create/list/get/continue/branch/archive/export/delete conversation threads on top of the existing session and event-ledger seams. A thread **is** an ownership-scoped session branch plus a `prismConversation` marker in `SessionRecord.metadata`; content stays in session entries and the redacted event ledger. Reconnectable replay pages durable redacted events without ever rerunning a provider or tool.
+
+Core (`@arnilo/prism`) exports only conversation **types and pure helpers** (`ConversationThread`, `ConversationError`, `CONVERSATION_METADATA_KEY`, thread-bound replay cursor codec, `conversationThreadFromRecord`, `conversationMarkerMetadata`). The service and optional HTTP handler live in `@arnilo/prism-server`.
+
+## When to use it
+
+Use it when a host needs persistent personal/work-agent conversations with reconnect, branch, archive, export, and deletion semantics without building a second session/event system. Hosts own authentication, agent selection, UI, transport chrome, and blob storage.
+
+Do not use it as a chat UI, a push/always-on daemon, or a file store. Slack/Teams channels, realtime voice, and desktop-control vendors are deferred (0.1.x); device adapters are contract + deny-by-default conformance only in 0.0.14.
+
+## Inputs / request
+
+```ts
+import { createConversationService, createConversationHandler } from "@arnilo/prism-server";
+import { createSqlitePersistence } from "@arnilo/prism-session-store-sqlite";
+
+const persistence = createSqlitePersistence({ filename }); // implements ConversationServiceStore
+const service = createConversationService(persistence, {
+  redactor,                    // required: replay/export serve redacted rows only; continue runs with it
+  sessionFactory: ({ thread, leafId, ownership, signal }) =>
+    agent.createSession({ id: thread.id, ...(leafId ? { leafId } : {}) }), // host binds agent/store/leaf
+  runOptions?,                 // narrowable RunOptions minus ownership/identity/signal/redactor/idempotencyKey
+  limits?: ConversationLimits, // frozen defaults/caps below
+});
+
+await service.create({ ownership, title?, id?, requestId?, metadata? });
+await service.list({ ownership, cursor?, limit? });
+await service.get({ ownership, threadId });
+await service.continue({ ownership, threadId, message, requestId?, leafId? });
+await service.branch({ ownership, threadId, leafId });
+await service.archive({ ownership, threadId });
+await service.export({ ownership, threadId, cursor? });
+await service.delete({ ownership, threadId });
+await service.replay({ ownership, threadId, cursor?, limit? });
+
+const handler = createConversationHandler({ service, authorize, basePath?: "/prism/conversations", redactor?, limits? });
+```
+
+`ConversationServiceStore` is a narrow `Pick` of `ProductionPersistenceStore`: `querySessions`, `queryEvents`, optional `appendSession` (required at factory time; sqlite/postgres implement it), and optional `lifecycle.applyRetention` (required for delete). Stores without `appendSession` fail closed at construction.
+
+## Outputs / response / events
+
+- `create`/`get`/`branch`/`archive` → `ConversationThread` (`id`, `title?`, `state: "active" | "archived"`, `branches`, timestamps, ownership projection, host metadata).
+- `list` → ownership-scoped `PersistencePage<ConversationThread>` (newest first), marker-filtered; non-conversation sessions never appear.
+- `continue` → `AgentRunResult` from one agent turn on the thread session; history rebuilds from durable entries, so the agent sees prior turns.
+- `replay` → `{ records: AgentEventRecord[], nextCursor?, terminal }`; records are durable redacted ledger rows ordered by `(timestamp, id)`; `terminal` marks `agent_finished`/`agent_denied`/`error`.
+- `export` → `{ thread, events, nextCursor?, truncated }`; redacted, byte/page-capped, cursor-resumable.
+- `delete` → `{ deleted, held }` via persistence lifecycle; legal holds always win.
+- HTTP handler routes: `POST {base}` create · `GET {base}` list · `GET {base}/{id}` · `DELETE {base}/{id}` · `POST {base}/{id}/continue|branch|archive|export` · `GET {base}/{id}/events?cursor=&limit=` replay.
+
+## Request/response example
+
+```http
+POST /prism/conversations HTTP/1.1
+content-type: application/json
+
+{ "title": "Q3 planning" }
+```
+
+```json
+{ "id": "conv_9b0f…", "title": "Q3 planning", "state": "active", "branches": [], "createdAt": "…", "updatedAt": "…", "tenantId": "t1", "userId": "u1" }
+```
+
+Reconnect after a dropped connection: `GET {base}/{id}/events` (optionally with the last `nextCursor`) pages the same durable events; clients dedupe by stable record `id` (at-least-once across the page boundary). No provider or tool call is re-executed by replay/export.
+
+## Implementation example
+
+```ts
+const thread = await service.create({ ownership, title: "draft review" });
+await service.continue({ ownership, threadId: thread.id, message: "summarize the attached plan", requestId: "ui-req-1" });
+
+// Branch from a known leaf (e.g. last entry id), then fork a continue from it.
+const branched = await service.branch({ ownership, threadId: thread.id, leafId });
+await service.continue({ ownership, threadId: thread.id, message: "try a shorter version", leafId });
+
+// Reconnectable replay.
+let cursor: string | undefined;
+do {
+  const page = await service.replay({ ownership, threadId: thread.id, ...(cursor ? { cursor } : {}) });
+  render(page.records);
+  cursor = page.nextCursor;
+} while (cursor);
+
+await service.archive({ ownership, threadId: thread.id });
+const result = await service.delete({ ownership, threadId: thread.id }); // { deleted: true, held: false }
+```
+
+## Extension and configuration notes
+
+Frozen limits (default / hard cap; hosts may tighten, never raise past hard caps):
+
+| Resource | Default / hard cap |
+| --- | ---: |
+| Thread list page | 50 / 200 |
+| Replay/export page rows | 100 / 500 |
+| Replay/export cursor | 4 KiB / 16 KiB |
+| Thread title | 256 B / 2 KiB |
+| Client request id | 256 B / 2 KiB |
+| Active branches per thread | 16 / 64 |
+| Export payload per request | 8 MiB / 32 MiB |
+| Export pages per request | 100 / 500 |
+| Handler request body | 64 KiB / 1 MiB |
+
+Behavior notes:
+
+- `create` with an explicit `id` is idempotent get-or-create; generated ids are `conv_<uuid>`.
+- `continue` `requestId` flows into session-append idempotency (`RunRecord.idempotencyKey` + append dedup), so exact retries deduplicate.
+- `continue` on an archived thread fails closed (`thread_archived`); `leafId` must be a branch ref recorded by `branch()`.
+- Replay cursors are thread-bound: a cursor minted for one thread is rejected on another (`cursor_thread_mismatch`).
+- Ledger rows from runs that had no redactor are never served by replay/export (fail-closed skip).
+- Export truncates at page granularity when the next page would exceed `exportBytes`; a single page larger than `exportBytes` cannot be exported (raise the cap or page via `replay`).
+- Branch refs live in thread metadata (read-modify-write); concurrent `branch()` calls can lose a ref, so the cap is approximate and the entry tree remains the content source of truth.
+- Deletion purges the whole session ledger (entries, runs, events, tool calls, usage, branches, search rows) through `lifecycle.applyRetention`; legal holds block deletion and report `held: true`.
+
+## Security and performance notes
+
+- Every operation starts from host-verified ownership (and optional `AgentIdentity`, which must project onto ownership without widening); wrong-user access returns not-found, never leaked existence.
+- `appendSession` upserts set ownership columns only on create; metadata/`updatedAt` on update — ownership is immutable after create.
+- Replay/export serve `redacted: true` ledger rows only and pass through the service redactor; no local paths, raw tool payloads, or secrets are emitted.
+- All loops are bounded by the frozen caps above; review/agent turns consume shared `RunLimits` via the host's `runOptions`.
+- No new permission surface: conversations reuse session/event/identity/redaction/lifecycle seams (roadmap gate 8).
+
+## Related APIs
+
+- [Web-standard server handler](server.md): authorized agent/workflow routes; the conversation handler mounts beside it.
+- [Session stores](session-stores.md): branch/append/checkout semantics a thread builds on.
+- [Database persistence](database-persistence.md): `ProductionPersistenceStore`, `appendSession`, `SessionQuery` id/metadataKey filters, retention/legal-hold lifecycle.
+- [Agents and sessions](agent-identity.md): verified identity and ownership projection.
+- [Credentials and redaction](credentials-and-redaction.md): `SecretRedactor` used by replay/export/continue.
+- [Browser automation](browser-automation.md): verified-state checkpoints scope to the runs a thread owns; reload/verify before side effect.
+- [Device adapters](device-adapters.md): deny-by-default voice/desktop sessions bind to a thread's run and consume shared `RunLimits`.

package/docs/credential-storage.md

@@ -17,6 +17,8 @@ Factories:
 - `createOAuthCredentialStoreAdapter(store)`
 - `rotateEncryptedCredentialStorePassphrase(options)`
 
+The `@arnilo/prism-credentials-node/oidc` subpath adds the optional OIDC/JWKS identity verifier (`createOidcIdentityVerifier`) — pinned issuer/audience/JWKS verification over native `fetch` + WebCrypto (see [Agent identity](agent-identity.md)).
+
 Core `@arnilo/prism` remains storage-free. Hosts choose a backend explicitly at startup; there is no global credential singleton and no silent fallback from keychain to plaintext file storage.
 
 ## When to use it
@@ -146,6 +148,33 @@ await refreshOAuthCredential({
 });
 ```
 
+Workload OAuth providers (0.0.14) — Microsoft 365 / Google Workspace over the shared OAuth2 seam (PKCE + device code + refresh + revoke), least-privilege scopes per read/mutation bundle:
+
+```ts
+import { revokeOAuthCredential } from "@arnilo/prism";
+import {
+  createMicrosoft365OAuthProvider,
+  createGoogleWorkspaceOAuthProvider,
+  createOAuthWorkTokenProvider,
+  createOAuthCredentialStoreAdapter,
+} from "@arnilo/prism-credentials-node";
+
+// Read-only mail/calendar (no mutation scopes requested).
+const m365 = createMicrosoft365OAuthProvider({ clientId: "<app-id>", capabilities: ["mail", "calendar"], access: "read" });
+const creds = await m365.login({ onDeviceCode: ({ userCode, verificationUri }) => host.showCode(userCode, verificationUri) });
+await createOAuthCredentialStoreAdapter(store).set("microsoft365", creds);
+
+// Late-bound, per-identity token for a work-tools connector (env var, never argv/model context).
+const tokenProvider = createOAuthWorkTokenProvider({
+  provider: m365,
+  store: createOAuthCredentialStoreAdapter(store),
+  envVar: "M365_ACCESSTOKEN",
+});
+
+// Revocation: best-effort upstream (GWS supports RFC 7009; M365 does not) + mandatory local delete.
+await revokeOAuthCredential({ provider: m365, credentials: creds, store: createOAuthCredentialStoreAdapter(store) });
+```
+
 Passphrase rotation:
 
 ```ts
@@ -205,7 +234,8 @@ const providers = createOpenAIProviderPackage({ apiKey });
 - Use distinct `namespace` or vault paths per tenant/environment.
 - Keychain `list()` / `listOAuth()` are intentionally unsupported — enumerate credentials through host configuration instead of scanning the OS store.
 - Combine with `createExplicitCredentialResolver()` so runtime overrides still win over stored values.
-- Wire `createOAuthCredentialStoreAdapter(store)` into `refreshOAuthCredential()` so refreshed tokens persist durably.
+- Wire `createOAuthCredentialStoreAdapter(store)` into `refreshOAuthCredential()` only for an OAuth flow explicitly selected by the host and authorized by that provider. In 0.0.12 that means OpenAI Codex; in 0.0.14 the Microsoft 365 / Google Workspace workload providers (`createMicrosoft365OAuthProvider` / `createGoogleWorkspaceOAuthProvider`) are added over the same seam with least-privilege read/mutation scope bundles. Anthropic and Google *model* packages still accept API keys only. Never import or migrate Claude Code/Gemini CLI credential files, setup tokens, browser sessions, or CLI OAuth rows into this store.
+- Enterprise cloud providers (`azure` / `bedrock` / `vertex`) expect host workload-identity callbacks (Entra / IAM / ADC), not this local encrypted/keychain store as a cloud token minting service. Store may hold opaque refresh material only when the host already owns the cloud auth flow.
 
 ## Security and performance notes
 
@@ -216,6 +246,8 @@ const providers = createOpenAIProviderPackage({ apiKey });
 - Keychain operations use `@napi-rs/keyring`'s abort-aware `AsyncEntry`, so native work runs outside the JavaScript event loop. A main-loop timer aborts and rejects at `timeoutMs`; native cancellation remains OS/backend-dependent and may briefly retain one libuv worker after rejection.
 - Keychain payloads are bytes rather than password strings and are zeroed after parse/write. Unknown native errors are mapped to sanitized typed errors; no native message or secret value is echoed.
 - Never log passphrases, derived keys, or decrypted credential payloads.
+- Optional host KMS: `encryptWithHostKms` / `decryptWithHostKms` wrap a random AES-256-GCM DEK via host `HostKms.wrapKey`/`unwrapKey` (timeout ≤ 60 s). Envelope sizes reuse vault/file caps. Keys are never logged. `createMemoryHostKms` is for tests only.
+- Storage is not OAuth eligibility. A durable store may persist credentials for a provider only after the host selects a provider-authorized flow; it must not be used to piggyback on a vendor CLI or consumer subscription.
 - Live keychain tests are opt-in (`PRISM_TEST_KEYCHAIN=1`); default `npm test` stays offline.
 
 ## MCP authentication boundary
@@ -229,6 +261,7 @@ MCP credentials remain host inputs: resolve them before constructing client `req
 ## Related APIs
 
 - [Credentials and redaction](credentials-and-redaction.md): core resolver helpers and `refreshOAuthCredential()`
+- [Azure OpenAI / Foundry](providers/azure.md) / [Amazon Bedrock](providers/bedrock.md) / [Google Vertex AI](providers/vertex.md): enterprise workload-identity credential callbacks
 - [Web search, fetch, and extraction](web-tools.md): late-bound Brave/Exa/Firecrawl credentials
 - [Security/auth/trust](settings-auth-trust-security.md): host-owned settings/credentials boundaries
 - [Persistence, credentials, and multimodality primitives](persistence-credentials-multimodality-primitives.md): Plan 056 threat model and conformance matrix rows 7–10

package/docs/credentials-and-redaction.md

@@ -8,6 +8,7 @@ Prism provides small helpers for host-owned credentials and known-secret redacti
 - `createExplicitCredentialResolver()`: tries named resolver sources in caller-provided order, such as runtime override → stored → env object → fallback.
 - `createEnvCredentialResolver()`: reads only a caller-supplied env-like object and map.
 - `refreshOAuthCredential()`: calls a provider OAuth refresh function and writes the result to a caller-owned store when supplied.
+- `revokeOAuthCredential()`: best-effort upstream revocation (`OAuthProvider.revoke?`) followed by a mandatory caller-owned store delete, so a revoked token fails closed locally even if the provider has no revocation endpoint.
 - `CredentialValueSource`: the accepted source type for `resolveCredentialValue()`.
 - `redactSecrets()`: replaces known secret string values inside strings, arrays, and plain objects.
 - `errorToErrorInfo()`: converts unknown errors into `ErrorInfo` and redacts known secret values from error text.
@@ -41,6 +42,7 @@ resolveCredentialValue(
 createExplicitCredentialResolver(sources: readonly CredentialResolverSource[]): CredentialResolver
 createEnvCredentialResolver(env: Readonly<Record<string, string | undefined>>, map: Readonly<Record<string, string>>): CredentialResolver
 refreshOAuthCredential(options: { provider: OAuthProvider; credentials: OAuthCredentials; store?: OAuthCredentialStore }): Promise<OAuthCredentials>
+revokeOAuthCredential(options: { provider: OAuthProvider; credentials: OAuthCredentials; store?: RevocableOAuthCredentialStore }): Promise<void>
 redactSecrets<T>(value: T, secrets: readonly (string | undefined)[]): T
 errorToErrorInfo(error: unknown, secrets?: readonly (string | undefined)[]): ErrorInfo
 ```
@@ -102,6 +104,14 @@ console.log(error.message);
 - Keep resolved credential values local to the request path. Do not put them in registries, model configs, messages, provider events, agent events, session entries, compaction summaries, or logs.
 - Future settings/config loaders may provide credential resolver instances, but core helpers remain storage-free.
 
+### Subscription OAuth eligibility
+
+In 0.0.12, OpenAI Codex is Prism's only first-party subscription OAuth flow. It is explicit and host-invoked through `createOpenAICodexOAuthProvider()`; hosts own login UI and may use `createOAuthCredentialStoreAdapter()` for deliberately selected durable storage.
+
+Anthropic and Google provider packages are API-key-only. Do not scrape or import Claude Code/Gemini CLI credential files, setup tokens, environment values, or browser sessions, and do not route a user's Claude.ai/Gemini subscription through Prism. Anthropic states that developers building products must use Claude Console API keys or a supported cloud provider and may not offer Claude.ai login or route Free/Pro/Max credentials ([legal and compliance](https://docs.anthropic.com/en/docs/claude-code/legal-and-compliance)). Gemini CLI states that third-party software using its OAuth to access backend services violates applicable terms; its FAQ names Vertex AI or Google AI Studio API keys as the supported third-party path ([terms](https://github.com/google-gemini/gemini-cli/blob/main/docs/resources/tos-privacy.md), [FAQ](https://github.com/google-gemini/gemini-cli/blob/main/docs/resources/faq.md)).
+
+A future provider-local OAuth adapter needs published permission for third-party products, documented authorize/token/refresh endpoints and scopes, PKCE/state where required, abort/expiry/bounded-response/redaction/store-round-trip fixtures, and legal review before registration. Until then, absence is intentional.
+
 ## Security and performance notes
 
 - Redaction only removes exact known secret values passed to the helper. It is not a general-purpose secret detector.
@@ -122,4 +132,4 @@ console.log(error.message);
 - [LLM compaction package](compaction-llm.md): resolves optional summary-provider credentials per compaction call and redacts exact known values.
 - [OpenAI-compatible provider](providers/openai-compatible.md): resolves API keys per request and redacts known values from adapter errors.
 
-Phase 10 added `createMemoryCredentialStore()`, `createChainedCredentialResolver()`, and `createSecretRedactor()` for opt-in in-memory auth and runtime redaction. Phase 11 adds OAuth/API-key contracts plus explicit resolver order helpers. Core still has no persistent secret store and does not read environment variables or files for credentials. For durable storage, use [`@arnilo/prism-credentials-node`](credential-storage.md) encrypted-file or keychain backends. See [Security/auth/trust](settings-auth-trust-security.md).
+Phase 10 added `createMemoryCredentialStore()`, `createChainedCredentialResolver()`, and `createSecretRedactor()` for opt-in in-memory auth and runtime redaction. By default the memory store serves a providerless record for a provider-scoped request of the same name — that record is then shared across every provider; pass `{ allowProviderFallback: false }` for exact-match-only resolution (strict provider scoping). Phase 11 adds OAuth/API-key contracts plus explicit resolver order helpers. Core still has no persistent secret store and does not read environment variables or files for credentials. For durable storage, use [`@arnilo/prism-credentials-node`](credential-storage.md) encrypted-file or keychain backends. See [Security/auth/trust](settings-auth-trust-security.md).

package/docs/database-persistence.md

@@ -8,6 +8,8 @@ Prism itself does not ship a production database adapter. The built-in `SessionS
 
 Plan 056 Task 1 adds dialect-neutral shared primitives under `@arnilo/prism/testing/persistence-schema`, `@arnilo/prism/testing/session-store-conformance`, and `@arnilo/prism/testing/run-ledger-conformance`. Task 2 ships `@arnilo/prism-session-store-sqlite` (see [SQLite persistence](sqlite-persistence.md)); Task 3 ships `@arnilo/prism-session-store-postgres` (see [PostgreSQL persistence](postgres-persistence.md)). Both implement dialect-local SQL against the shared model; Prism core still ships no ORM, driver, or migration runner.
 
+Release 0.0.23 additionally ships [`@arnilo/prism-enterprise-postgres`](enterprise-postgres-state.md), a separate PostgreSQL composition for policy decisions, evaluations, work-mutation claims, and model-router state. It is not a `ProductionPersistenceStore` replacement and does not store sessions/runs. Its fixed `prism_enterprise_migrations` history is independent of `prism_migrations`; hosts may use both compositions against the same validated schema.
+
 ## When to use it
 
 Use these contracts when you write a database-backed `SessionStore` or a separate persistence adapter that needs:
@@ -72,6 +74,10 @@ Important shapes:
 | `RetentionPolicy` | Policy with `maxAgeDays`, `maxEntriesPerSession`, `maxTotalBytes`, `archiveStore`, and `appliedKinds`. |
 | `MigrationRecord` | Applied migration with name, version, timestamp, checksum, and applied-by. |
 
+Optional session-record write seam (0.0.14): `appendSession?(record: SessionRecord)` upserts a session row — ownership columns are set on create only, `metadata`/`updatedAt` on update — so hosts (e.g. the [conversation service](conversations.md)) can durably mark and title sessions without entry writes. `SessionQuery` gained two bounded filters for the same seam: `id` (exact session lookup) and `metadataKey` (sessions whose `metadata` object contains a top-level key, validated by `assertSessionMetadataKey`). SQLite implements it with `json_extract`, PostgreSQL with a `jsonb` existence check; both keep ownership filtering intact.
+
+Artifact co-work review (0.0.14) reuses the generic `CheckpointStore` rather than adding a dedicated table: the [artifact service](work-artifacts-and-review.md) stores each artifact as a versioned checkpoint value (namespace `prism.artifact`, key `threadId:artifactId`, category `artifact`). The checkpoint `version` is the compare-and-swap counter that resolves concurrent reviewers; revision numbers, approvals, and `lastValidatedVersion` live inside the JSON value. SQLite/Postgres already persist checkpoints durably, so there is no separate artifact schema or migration, and records carry metadata/hashes/refs only — never file bodies.
+
 ## Outputs / response / events
 
 Each `query*` method returns a `PersistencePage<T>`:
@@ -334,19 +340,30 @@ Use `cursor`/`limit` when an adapter pages very long branches. Do not implement
 
 ## Retention policies
 
-A retention policy is a host-managed rule attached to sessions via `retention_policy_id`. Enforcement is host-owned and typically runs as a background job:
+A retention policy is a host-managed rule attached to sessions via `retention_policy_id`. Phase 8 adds optional `ProductionPersistenceStore.lifecycle` (`createMemoryPersistenceLifecycle`, SQLite/Postgres `persistence.lifecycle`) for bounded apply/hold/export/quota:
+
+```ts
+await store.lifecycle.putLegalHold({ tenantId, userId, resourceKind: "session", resourceId, reason });
+await store.lifecycle.applyRetention({ tenantId, userId, policy, candidates }); // hold wins over delete; SQL adapters purge the whole session ledger (entries, runs, events, tool calls, usage, branches, search rows) in FK order
+await store.lifecycle.exportUnderHold({ tenantId, userId, cursor, limit }); // redacted
+await store.lifecycle.setTenantQuota({ tenantId, userId, resourceKind: "run", limit: 100 });
+await store.lifecycle.consumeTenantQuota({ tenantId, userId, resourceKind: "run" }); // fails closed when exhausted
+```
+
+Schema **v5** migration `005_lifecycle_hold_quota` adds `prism_legal_holds` and `prism_tenant_quotas`. Legal hold always blocks delete for the held resource id. Export pages are redacted refs only (no prompts/bodies/secrets).
+
+Host background jobs may still:
 
 1. Select policies whose `max_age_days`, `max_entries_per_session`, or `max_total_bytes` thresholds are exceeded.
-2. For each affected session, delete or archive entries older than the policy age, beyond the entry count, or over the byte budget.
-3. Respect `applied_kinds` — only delete kinds listed in the policy (null means all kinds).
-4. Compact or soft-delete sessions whose `expires_at` has passed.
-5. Write audit metadata to the migration or host audit log; do not delete the policy row unless explicitly requested.
+2. Pass candidate session ids into `applyRetention` (or let SQL adapters discover expired sessions).
+3. Respect `applied_kinds` when selecting candidates.
+4. Never silently purge under hold.
 
-Retention jobs should not run inside the agent/session runtime. They are a host concern.
+Retention jobs should not run inside the agent/session runtime.
 
 ## Migrations
 
-Hosts own schema migrations. Prism publishes only the TypeScript contracts; no DDL is generated or executed by the core library. First-party SQLite/PostgreSQL adapters automatically verify their checked-in schema-v3 history and catalog at open, before runtime writes. Their catalog reads are bounded metadata queries/PRAGMAs, not table-data scans.
+Hosts own schema migrations. Prism publishes only the TypeScript contracts; no DDL is generated or executed by the core library. First-party SQLite/PostgreSQL adapters automatically verify their checked-in schema-v5 history and catalog at open, before runtime writes. Their catalog reads are bounded metadata queries/PRAGMAs, not table-data scans.
 
 Each new adapter-owned migration row records the contract SHA-256 checksum. A complete known v0.0.5 history whose checksum values are all `NULL` is a one-time compatibility case: under the SQLite transaction or PostgreSQL advisory transaction lock, the adapter verifies the full current shape, backfills all checksums, and continues. Unknown/duplicate/out-of-order/name-version/checksum mismatch, mixed/partial legacy values, or any missing/renamed/wrong-type/null/default/key/index artifact fails closed. Restore or apply a reviewed host migration; never edit checksums to silence drift.
 
@@ -434,6 +451,8 @@ const dbStore: ProductionPersistenceStore = {
 - Cursor values and idempotency keys are host-defined and opaque to Prism.
 - First-party SQLite/PostgreSQL adapters expose `persistence.checkpoints` and `persistence.leases`, backed by package-owned `prism_checkpoints` / `prism_leases` tables. `@arnilo/prism-workflows` consumes them for durable resume, human suspension, multi-process coordination, Phase 11 schedule records/fire leases, shared state, and replay lineage; workflow code owns no SQL table. `suspended`/`denied`, schedules, state history, and replay lineage remain namespaces/categories plus bounded checkpoint JSON values, so Phases 8 and 11 need no database migration.
 
+Schema version **7** adds the exact-owner durable event retention index (`prism_agent_events_owner_timestamp_sequence_idx`). Distributed subscribe/LISTEN remains PostgreSQL-only via `persistence.events`.
+
 ## Security and performance notes
 
 - **No credentials in storage.** The contracts never include `CredentialResolver`, `AIProvider`, `ProviderResolver`, provider API keys, or credential values.
@@ -446,6 +465,7 @@ const dbStore: ProductionPersistenceStore = {
 ## Related APIs
 
 - [Session store conformance](session-store-conformance.md): executable adapter baseline for append/idempotency/conflict/branch invariants.
+- [Enterprise PostgreSQL state](enterprise-postgres-state.md): durable governance and connector/router state outside the session/run contract.
 - [Migration guide](migration.md): before/after shapes for moving from in-memory/JSONL to this contract.
 - [Performance limits](performance.md): production sizing, subscriber queues, branch-read limits, and database adapter guidance.
 - [Session stores and branching](session-stores-and-branching.md): `SessionStore`, `SessionEntry`, branch helpers, and runtime branch semantics.

package/docs/device-adapters.md

@@ -0,0 +1,97 @@
+# Device adapters
+
+## What it does
+
+Optional realtime voice and desktop OS / computer-control surface for Prism agents, shipped in 0.0.14 as a **contract + deny-by-default policy only** in `@arnilo/prism` (`src/devices.ts`). No vendor voice or desktop-control implementation ships in 0.0.14 — those are demand-gated to 0.1.x. The contract composes over the existing `PermissionPolicy`, `RunLimits`, approval (`tool_approval`), and redactor seams; it adds no second approval runtime and no device framework.
+
+## When to use it
+
+- A host wants to admit a realtime voice or desktop-control device for an agent run and needs a fail-closed policy boundary before writing the vendor adapter.
+- You need conformance fixtures (denial, approval, stream bounds, session budget, run accounting, redaction) to validate a future vendor adapter against the deny-by-default contract.
+- You must guarantee device side effects never run without explicit consent + sandbox + approval, and never replay after reconnect.
+
+Do **not** use it to broaden consent, memory, network, file, browser, connector, or tool permissions (roadmap gate 8 forbids this).
+
+## Inputs / request
+
+```ts
+import type { DeviceAdapter, DevicePolicyOptions, DeviceAdmitRequest } from "@arnilo/prism";
+
+const adapter: DeviceAdapter = {
+  kind: "voice",            // "voice" | "desktop-control"
+  enabled: false,           // deny-by-default: admit only on explicit true
+  requireApproval: true,    // every side effect requires approval
+  sandbox: "sandbox-a",     // host-owned sandbox id (required to admit)
+  network: "egress-strict", // host-owned network/egress policy id
+  limits: { maxChunkBytes: 1_048_576, maxConcurrentSessions: 1 },
+};
+
+const options: DevicePolicyOptions = { runLimits: { maxTurns: 8, maxToolCalls: 50 } };
+const admit: DeviceAdmitRequest = { approved: true, activeSessions: 0 };
+```
+
+## Outputs / response / events
+
+| Export | Purpose |
+| --- | --- |
+| `resolveDevicePolicy(adapter, options?)` | Resolve caps; reject unknown kinds and caps above the hard ceiling. |
+| `assertDeviceAdmit(policy, request)` | Fail-closed admission gate (disabled / unsandboxed / unapproved / over-budget / unaccounted all deny). |
+| `acceptDeviceChunk(policy, bytes)` | Stream bound: oversize chunks dropped with `marker: "dropped_oversize"`, never forwarded. |
+| `redactDeviceTelemetry(redactor, telemetry)` | Metadata-safe telemetry: apply the host redactor before any emit/persist. |
+| `runDevicePolicyConformance(adapter, options?)` | Conformance pair for future vendor adapters; returns `{ passed }`. |
+| `DevicePolicyError` | Stable error (`ERR_PRISM_DEVICE_DISABLED` / `_APPROVAL` / `_SESSIONS` / `_CHUNK` / `_RUN_LIMITS` / `_INPUT`). |
+
+## Request/response example
+
+```jsonc
+// assertDeviceAdmit on a disabled device throws (fail closed):
+// DevicePolicyError: voice device is disabled by default  (ERR_PRISM_DEVICE_DISABLED)
+
+// acceptDeviceChunk(policy, 9_000_000) with a 1 MiB cap:
+{ "accepted": false, "bytes": 9000000, "marker": "dropped_oversize" }
+```
+
+## Implementation example
+
+```ts
+import {
+  assertDeviceAdmit,
+  acceptDeviceChunk,
+  redactDeviceTelemetry,
+  resolveDevicePolicy,
+  createSecretRedactor,
+} from "@arnilo/prism";
+
+const policy = resolveDevicePolicy(
+  { kind: "desktop-control", enabled: true, requireApproval: true, sandbox: "sandbox-a" },
+  { runLimits: { maxTurns: 8, maxToolCalls: 50 } },
+);
+
+// Re-admit on every resume (side effects never replay after reconnect).
+assertDeviceAdmit(policy, { approved: hostApprovedSideEffect, activeSessions: currentSessions });
+
+// Stream bound + redaction on each audio/screenshot chunk.
+const chunk = acceptDeviceChunk(policy, frameBytes);
+if (chunk.accepted) emit(redactDeviceTelemetry(createSecretRedactor([token]), frame));
+```
+
+## Extension and configuration notes
+
+- Frozen caps: audio/screenshot/stream chunk **1 MiB / 8 MiB**; concurrent device sessions per identity **1 / 4**. Device wall time / turns / tool calls consume the shared `RunLimits` (admission fails closed without run accounting).
+- `enabled` resolves to `true` only on an explicit `true`; any other value is disabled. `requireApproval` stays `true` unless the host explicitly sets `false` (it should not).
+- Vendor voice / desktop-control packages are **deferred to 0.1.x** and ship only if Task 0 records measured demand. This page documents the contract they must satisfy via `runDevicePolicyConformance`.
+
+## Security and performance notes
+
+- Deny-by-default: admission requires explicit `enabled`, an explicit `sandbox`, approval (when required), an under-budget session count, and shared `RunLimits` — any missing condition fails closed.
+- Side effects never replay after reconnect: hosts must re-admit on every resume/interruption.
+- Secrets are isolated from audio/screenshot/stream paths: apply `redactDeviceTelemetry` before any emit/persist; telemetry must be metadata-safe.
+- No permission broadening: device adapters cannot widen consent, memory, network, file, browser, connector, or tool permissions (gate 8).
+
+## Related APIs
+
+- [Browser automation](browser-automation.md): verified-state checkpoints + reload/verify-before-side-effect for browser composition.
+- [Conversations](conversations.md): durable threads that own the runs device sessions bind to.
+- [Host security](host-security.md): approval, sandbox, and egress trust boundaries device adapters compose over.
+- [Performance and resource limits](performance.md): shared `RunLimits` accounting.
+- [Migration](migration.md): 0.0.14 additive seams and 0.1.x device vendor deferral.

package/docs/enterprise-postgres-state.md

@@ -0,0 +1,178 @@
+# Enterprise PostgreSQL state
+
+## What it does
+
+`@arnilo/prism-enterprise-postgres` is one optional PostgreSQL composition for the four existing enterprise state seams:
+
+| State | Composition property | Durable behavior |
+| --- | --- | --- |
+| Policy decisions | `policy` | Append-only `PolicyDecisionStore` with owner-bound cursor pages. |
+| Evaluations | `evaluations` | `EvaluationStore` append/query records with exact owner pages. |
+| Work mutations | `workIdempotency` | Atomic claim/CAS lifecycle for connector effects. |
+| Model routing | `modelRouter` | Shared rate, budget, and circuit state for router replicas. |
+| Tool effects | `toolEffects` | Durable `ToolEffectStore` claim/CAS for recoverable tool side effects (migration 002). |
+| Tool effects | `toolEffects` | Durable `ToolEffectStore` claim/CAS for recoverable tool side effects (migration 002). |
+
+`createPostgresEnterpriseState()` opens a host-supplied or adapter-owned `pg` pool, verifies/applies checksum-protected enterprise migrations (`001_enterprise_state`, `002_tool_effects`), and returns those stores plus explicit cleanup and close operations. Importing it performs no I/O. It is separate from session/run persistence in [`@arnilo/prism-session-store-postgres`](postgres-persistence.md).
+
+## When to use it
+
+Use it for a multi-process production host that needs policy/evaluation audit state, connector mutation reconciliation, or model-router limits to survive restart and coordinate across replicas.
+
+Use memory/file stores only for tests, demos, or a deliberately single-process host. They do not provide PostgreSQL cross-replica coordination. This package is optional; it adds no database driver to `@arnilo/prism` core.
+
+## Inputs / request
+
+```ts
+import { createPostgresEnterpriseState } from "@arnilo/prism-enterprise-postgres";
+import { Pool } from "pg";
+
+const pool = new Pool({
+  connectionString: process.env.DATABASE_URL,
+  max: 10,
+  ssl: { rejectUnauthorized: true },
+});
+
+const state = await createPostgresEnterpriseState({ pool, schema: "prism" });
+```
+
+| Input | Meaning |
+| --- | --- |
+| `pool` | Existing `pg` pool. Exactly one of `pool` and `connectionString` is required; caller retains pool lifecycle. |
+| `connectionString` | Creates an adapter-owned pool when `pool` is omitted. |
+| `schema` | Validated identifier; defaults to `"prism"`. It is never interpolated as an unchecked SQL identifier. |
+| `poolMax` / `poolConfig` | Adapter-owned pool settings; maximum defaults to 10 and is capped at 100. Put TLS in `poolConfig.ssl`. |
+| `skipMigrations` | Isolated-test escape hatch only. Production opens verify/apply the fixed migration before request traffic. |
+| `cleanup({ tenantId, accountId?, userId?, principalId, limit?, signal? })` | Explicit exact-owner cleanup; default 100 and hard maximum 500 rows. No worker starts automatically. |
+
+Every durable policy/work/router action starts from an active host-verified `AgentIdentity`. Evaluation records/queries must be projected by the host from that verified ownership. PostgreSQL rejects missing tenant scope; optional account/user values are normalized and matched exactly, including absence.
+
+## Outputs / response / events
+
+`PostgresEnterpriseState` has this public shape:
+
+```ts
+interface PostgresEnterpriseState {
+  readonly policy: PolicyDecisionStore;
+  readonly evaluations: EvaluationStore;
+  readonly workIdempotency: IdempotencyStore;
+  readonly modelRouter: ModelRouterStateStore;
+  readonly toolEffects: ToolEffectStore;
+  readonly toolEffects: ToolEffectStore;
+  cleanup(input: EnterpriseStateCleanupInput): Promise<EnterpriseStateCleanupResult>;
+  close(): Promise<void>;
+}
+```
+
+`close()` ends only a pool created from `connectionString`; it leaves a caller-owned pool open. `cleanup()` returns `{ removed, transitioned }`. It transitions expired work claims to `unknown` and abandoned circuit probes back to cooldown before deleting expired/idle retained state.
+
+Work mutations expose six observable states: **absent**, `in_progress`, `completed`, `failed_retryable`, `failed_terminal`, and `unknown`. `begin()` atomically returns `acquired` or the existing record; `complete`/`fail`/`markUnknown` use claim-token plus version compare-and-swap. `unknown` requires an operator/connector-specific `resolveUnknown` decision. It is not automatically replayed and it does **not** claim exactly-once external effects.
+
+Model-router state is asynchronous and owner/principal/provider/model scoped. Supplying it to `createModelRouter({ stateStore })` requires awaited `resolve`, `recordUsage`, and `recordOutcome` calls with verified identity. The legacy synchronous `providerSource` facade throws `ERR_PRISM_MODEL_ROUTER_ASYNC_STATE` when durable state is configured.
+
+## Request/response example
+
+```json
+{
+  "schema": "prism",
+  "cleanup": {
+    "tenantId": "tenant-1",
+    "userId": "user-7",
+    "principalId": "agent-9",
+    "limit": 100
+  },
+  "result": { "removed": 12, "transitioned": 1 }
+}
+```
+
+A migration creates `prism_policy_decisions`, `prism_evaluations`, `prism_work_idempotency`, three `prism_model_router_*` tables, and its separate `prism_enterprise_migrations` history. Startup serializes per-schema setup with an advisory transaction lock and rejects checksum or catalog drift rather than silently repairing it.
+
+## Implementation example
+
+```ts
+import type { AgentIdentity } from "@arnilo/prism";
+import { createPostgresEnterpriseState, type PostgresEnterpriseState } from "@arnilo/prism-enterprise-postgres";
+
+const identity: AgentIdentity = {
+  tenantId: "tenant-1",
+  userId: "user-7",
+  principal: { kind: "agent", id: "agent-9" },
+  scopes: ["enterprise:write"],
+  verified: true,
+  issuedAt: "2026-08-03T00:00:00.000Z",
+};
+
+export async function recordEnterpriseState(state: PostgresEnterpriseState) {
+  const now = new Date().toISOString();
+  await state.policy.append({
+    id: "policy-1",
+    policyId: "mail",
+    policyVersion: "2026-08-03",
+    outcome: "approval",
+    identity,
+    target: { kind: "draft", id: "draft-1" },
+    evidenceRefs: ["rule:external-recipient"],
+    createdAt: now,
+  });
+  await state.evaluations.append({
+    id: "eval-1",
+    scorerId: "quality",
+    status: "scored",
+    score: 1,
+    sampled: true,
+    tenantId: identity.tenantId,
+    userId: identity.userId,
+    createdAt: now,
+  });
+
+  const claim = await state.workIdempotency.begin({ identity, key: "mail-send-1", op: "mail.send" });
+  if (claim.outcome === "acquired") {
+    // Run approved connector effect outside PostgreSQL transaction.
+    await state.workIdempotency.complete({
+      identity,
+      key: "mail-send-1",
+      op: "mail.send",
+      claimToken: claim.record.claimToken!,
+      expectedVersion: claim.record.version,
+      result: { draftId: "draft-1", resourceId: "message-1" },
+    });
+  }
+
+  await state.modelRouter.addUsage({
+    key: { tenantId: "tenant-1", userId: "user-7", principalId: "agent-9", provider: "openai", model: "gpt-4.1-mini" },
+    tokens: 100,
+    windowMs: 86_400_000,
+    now: Date.now(),
+  });
+  return state.cleanup({ tenantId: "tenant-1", userId: "user-7", principalId: "agent-9" });
+}
+
+// `state` comes from `await createPostgresEnterpriseState({ pool, schema: "prism" })`.
+```
+
+## Extension and configuration notes
+
+- `createModelRouter({ resolver, stateStore: state.modelRouter })` keeps allow-list, residency, fallback, and diagnostics behavior in `@arnilo/prism-model-router`; this package only supplies durable state.
+- Policy/evaluation/query public contracts stay in their owning packages. This package exports only `createPostgresEnterpriseState`, its options/result types, and `EnterprisePostgresError`; it has no SQL, DDL, codec, queryable, or migration subpath.
+- The fixed schema has no generic key/value table and no background cleanup scheduler. Schedule `state.cleanup()` from an authorized host job, size its bounded batch for the deployment, and monitor unknown work rows for reconciliation. Run protected integration checks with `PRISM_TEST_POSTGRES_URL="$DATABASE_URL" npm run test:postgres`; the command rejects an absent URL instead of silently skipping database coverage.
+- The OPA adapter (`@arnilo/prism-policy/opa`, 0.0.28) records decisions into the same `state.policy` store unchanged via `evaluateAndAppend` — see [Policy and audit](policy-and-audit.md#opa-external-policy-adapter-arniloprism-policyopa-008).
+- Request-path state SQL uses `SELECT`, `INSERT`, `UPDATE`, and `DELETE` on the six state tables. The open/migration lifecycle additionally needs schema/catalog/advisory-lock and DDL permissions. Use a deployment migration principal for that lifecycle and a least-privilege request role for request traffic; this release intentionally does not ship a migration CLI or worker.
+
+## Security and performance notes
+
+- Configure TLS, database credentials, pool timeouts, backups, restore drills, retention schedule, and database role grants in the host. Never put connection strings, tokens, prompts, raw connector responses, unrestricted payloads, or provider credentials in records.
+- Every value is a bound parameter. Schema identifiers are validated; table/index names are fixed. Cursors embed and recheck ownership, so a foreign tenant cannot reuse a page cursor.
+- Policy records cap at 64 KiB; evaluations at 64 KiB; work rows at 8 KiB; router material at 512 bytes. JSON rejects prototype-pollution keys, non-finite values, excess depth/properties, and over-size material.
+- PostgreSQL transaction SQLSTATE `40001`/`40P01` retries whole safe transactions up to three times. Connector effects remain outside those transactions and ambiguous errors become `unknown` rather than being retried.
+- Recorded `postgres:16-alpine` evidence (Node 24.18.0/Linux x64, 10 tenants × 10 principals × 1,000 policy/evaluation rows, 10,000 router keys, 16 clients) stayed below 50 ms p95 for point operations and 100 ms for cursor/cleanup pages. The highest recorded p95 was router-circuit contention at 28.410 ms. Fourteen representative `EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON)` shapes used named indexes with no sequential scans. These are recorded comparison evidence, not hardware-independent guarantees.
+
+## Related APIs
+
+- [Policy and audit](policy-and-audit.md): policy record and WORM export semantics.
+- [Evaluations](evaluations.md): scorer/evaluation record lifecycle.
+- [Work tools](work-tools.md): draft approval, unknown outcomes, and connector boundaries.
+- [Model routing](model-routing.md): durable asynchronous router migration.
+- [PostgreSQL persistence](postgres-persistence.md): sessions/runs/checkpoints/leases adapter.
+- [Database persistence](database-persistence.md): host retention and persistence guidance.
+- [Host security](host-security.md): database ownership, TLS, secrets, and role boundaries.
+- [Migration guide](migration.md): 0.0.22 → 0.0.23 upgrade steps.

package/docs/evaluations.md

@@ -146,11 +146,24 @@ Release 0.0.9 ships curated network-free adversarial fixtures in package tests:
 
 Fixtures reuse `@arnilo/prism-evals` (`defineDataset` / `defineScorer` / `scoreRun` / `assertEvaluationThreshold` / `serializeEvaluationReport`). Optional SWE-bench-compatible or live-browser harnesses remain host adapters — they are not default dependencies or quality claims. Protected real Docker/Playwright gates stay env-gated (`PRISM_TEST_DOCKER_SANDBOX`, `PRISM_LIVE_PLAYWRIGHT`) and never enter `sdk:ready`.
 
+## PostgreSQL enterprise state (0.0.23)
+
+`createPostgresEnterpriseState({ pool, schema }).evaluations` implements this package's existing `EvaluationStore`. The host creates an `EvaluationRecord` from verified ownership before append; every PostgreSQL query requires tenant scope, uses exact normalized account/user matching, and returns owner-bound opaque cursor pages. It is durable across reopen and supports the existing id/scorer/session/run/trace/dataset/item/experiment/status filters.
+
+```ts
+const state = await createPostgresEnterpriseState({ pool });
+await state.evaluations.append(record); // record is already host-owned and redacted
+const page = await state.evaluations.query({ tenantId: "t1", userId: "u1", status: "scored", limit: 100 });
+```
+
+Memory evaluation storage remains suitable for development and deterministic tests; it is not cross-replica production storage. PostgreSQL bounds each evaluation row to 64 KiB (reason/error 8 KiB each and metadata 32 KiB).
+
 ## Related APIs
 
 - [Agent/session runtime](agent-session-runtime.md): `AgentRunResult` and `session.run()`
 - [Runs and usage ledger](runs-and-usage.md): run/session identity for score linkage
 - [Observability](observability.md): use `onTraceReference` or bounded `traceId(runId)` to supply `ScoreRunOptions.traceId`; evaluation telemetry emits no reason/explanation content
 - [Coding agent tools](coding-agent-tools.md) / [Browser automation](browser-automation.md) / [Workflows](workflows.md): network-free coding-task composition at `examples/durable-coding-workflow.ts`; adversarial coding/browser eval example at `examples/coding-browser-evaluation.ts`
-- [Performance limits](performance.md): `scripts/benchmark-0.0.9.mjs` coding/browser evidence fields
+- [Performance limits](performance.md): `scripts/benchmark-0.0.11.mjs` search/budget evidence, `scripts/benchmark-0.0.10.mjs` workspace-mode evidence, and `scripts/benchmark-0.0.9.mjs` coding/browser evidence fields
+- [Enterprise PostgreSQL state](enterprise-postgres-state.md): durable owner-scoped evaluation storage.
 - [Release and install](release-and-install.md): optional package install and protected sandbox-browser workflow