@arnilo/prism 0.0.11 → 0.0.13

package/docs/policy-and-audit.md

@@ -0,0 +1,127 @@
+# Policy and audit
+
+## What it does
+
+`@arnilo/prism-policy` records redacted allow/deny/modify/approval decisions with policy version, actor refs from verified `AgentIdentity`, target, reason, expiry, and evidence references. Hosts export cursor-paginated pages to append-only/WORM sinks. The package does not embed a mandatory global policy engine, KMS, or cloud WORM SDK.
+
+## When to use it
+
+Use it when enterprise hosts need an attributable audit trail alongside existing guardrails, permission checks, and tool-approval interruptions. Skip it for single-tenant apps that only need `RunLedger` / guardrail events.
+
+Do not store unrestricted prompts, tool argument bodies, JWTs, or credential secrets on decision records. Do not treat the reference memory/file adapters as production WORM.
+
+## Inputs / request
+
+| API / field | Meaning |
+| --- | --- |
+| `createPolicyEvaluator({ policyId, policyVersion, evaluate })` | Host rule callback stamped with immutable id/version |
+| `PolicyEvaluateRequest` | Verified `identity`, `action`, `resource`, optional evaluator-only `context` (never persisted) |
+| `AppendPolicyDecisionInput` | Decision fields + verified identity; ownership from identity or explicit scope |
+| `createMemoryPolicyDecisionStore` / `createFilePolicyDecisionStore` | Append-only reference ledgers |
+| `exportPolicyDecisions({ store, ownership, cursor, limit, sink? })` | Cursor pages; optional host WORM sink |
+| `recordGuardrailDecision` / `recordPermissionDecision` / `recordToolApprovalDecision` | Optional bridges from existing decision points |
+
+Frozen caps (default / hard): decision `8 KiB / 64 KiB`, reason or evidence ref `1 KiB / 8 KiB`, export page `100 / 500`.
+
+## Outputs / response / events
+
+- `PolicyDecisionRecord` — frozen redacted row (`actor` refs, `evidenceRefs`, no payload blob).
+- `evaluateAndAppend` — evaluate then append in one call.
+- Policy version mismatch (`requirePolicyVersion`) and unrestricted payload keys fail closed (`ERR_PRISM_POLICY_VERSION` / `ERR_PRISM_POLICY_PAYLOAD`).
+- Missing/expired/unverified identity fails via core `assertIdentityActive` before append.
+
+## Request/response example
+
+```json
+{
+  "id": "dec-1",
+  "policyId": "mail",
+  "policyVersion": "2026-07-23",
+  "outcome": "approval",
+  "actor": {
+    "tenantId": "tenant-1",
+    "userId": "user-1",
+    "principalId": "agent-42",
+    "principalKind": "agent",
+    "sponsorId": "sponsor-7"
+  },
+  "target": { "kind": "draft", "id": "d1" },
+  "reason": "external send",
+  "evidenceRefs": ["rule:external"],
+  "createdAt": "2026-07-23T12:00:00.000Z",
+  "tenantId": "tenant-1",
+  "userId": "user-1"
+}
+```
+
+## Implementation example
+
+```ts
+import { type AgentIdentity } from "@arnilo/prism";
+import {
+  createFilePolicyDecisionStore,
+  createPolicyEvaluator,
+  evaluateAndAppend,
+  exportPolicyDecisions,
+  recordToolApprovalDecision,
+} from "@arnilo/prism-policy";
+
+const evaluator = createPolicyEvaluator({
+  policyId: "mail",
+  policyVersion: "2026-07-23",
+  evaluate: ({ action }) =>
+    action === "mail.send"
+      ? { outcome: "approval", reason: "external send", evidenceRefs: ["rule:external"] }
+      : { outcome: "allow" },
+});
+
+const store = createFilePolicyDecisionStore({
+  path: "/var/prism/policy-decisions.jsonl",
+  requirePolicyVersion: "2026-07-23",
+});
+
+await evaluateAndAppend(
+  { identity, action: "mail.send", resource: { kind: "draft", id: "d1" } },
+  { store, evaluator, id: crypto.randomUUID() },
+);
+
+await recordToolApprovalDecision({
+  store,
+  evaluator,
+  id: crypto.randomUUID(),
+  identity,
+  toolName: "mail.send",
+  toolCallId: "call-1",
+  evidenceRef: "run:abc/tool:call-1",
+});
+
+for await (const page of exportPolicyDecisions({
+  store,
+  tenantId: identity.tenantId,
+  userId: identity.userId,
+  sink: { async write(records) { await worm.append(records); } },
+})) {
+  void page;
+}
+```
+
+## Extension and configuration notes
+
+Policy is optional. Hosts wire `record*` helpers or `evaluateAndAppend` at permission/guardrail/tool-approval/router/connector boundaries. Model-router and work-connector packages (later Phase 8 tasks) may call the same store when configured. Replace file/memory adapters with host WORM/KMS without changing record shape.
+
+## Security and performance notes
+
+- Approvals require verified `AgentIdentity`; actor fields are refs only.
+- Policy version pin fails closed on mismatch.
+- Unrestricted payload field names (`prompt`, `body`, `toolArguments`, …) are rejected before append.
+- Evaluate/append are O(fields) and network-free in-package; remote WORM I/O stays in the host sink/adapter.
+- Export never full-scans: page size is capped; raise hard caps only with Phase 8 freeze + tests + docs updates.
+
+## Related APIs
+
+- [Model routing](model-routing.md)
+- [Agent identity](agent-identity.md)
+- [Guardrails](guardrails.md)
+- [Runs and usage ledger](runs-and-usage.md)
+- [Host security](host-security.md)
+- Package README: [`@arnilo/prism-policy`](../packages/policy/README.md)

package/docs/postgres-persistence.md

@@ -116,7 +116,7 @@ PRISM_TEST_POSTGRES_URL="$DATABASE_URL" npm run test:postgres --workspace @arnil
 - The package is optional and workspace-local; `@arnilo/prism` core has no PostgreSQL dependency.
 - Schema names must match `^[a-zA-Z_][a-zA-Z0-9_]*$`; the adapter quotes them and never interpolates user values into identifier positions.
 - `SessionAppendOptions` idempotency rows are durable in `prism_session_append_idempotency` and survive reopen.
-- Schema version **4** applies `001_init`, `002_usage_scope`, `003_run_feedback`, and `004_session_search`. 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 (Postgres `tsvector` FTS table 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. SQLite shares the same model with dialect-local DDL.
+- Schema version **5** applies `001_init`, `002_usage_scope`, `003_run_feedback`, `004_session_search`, and `005_lifecycle_hold_quota`. 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 (Postgres `tsvector` FTS table 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. SQLite shares the same model with dialect-local DDL.
 - Pass an existing `pg` `Pool` when your host already manages pooling, TLS, and credential rotation.
 
 ## Security and performance notes

package/docs/provider-packages.md

@@ -18,6 +18,19 @@ Use provider packages when a host wants to bundle model metadata, provider adapt
 
 Do not use provider packages as a package manager, credential store, env loader, provider-specific cache implementation, or live integration runner.
 
+### Subscription OAuth support matrix
+
+| Package | 0.0.12 auth registration | Subscription OAuth boundary |
+| --- | --- | --- |
+| `@arnilo/prism-provider-openai` | `api_key` for `openai`; `oauth` for `openai-codex` | Existing host-invoked OpenAI Codex PKCE/device-code flow only. |
+| `@arnilo/prism-provider-anthropic` | `api_key` only | No Claude Code/Claude.ai subscription OAuth, credential-file/setup-token import, or routing. [Anthropic requires product developers to use API keys or supported cloud providers](https://docs.anthropic.com/en/docs/claude-code/legal-and-compliance). |
+| `@arnilo/prism-provider-google` | `api_key` only | No Gemini CLI OAuth or credential/token import. [Gemini CLI prohibits third-party OAuth piggybacking](https://github.com/google-gemini/gemini-cli/blob/main/docs/resources/tos-privacy.md); use Google AI Studio API keys. Vertex/ADC uses separate [`@arnilo/prism-provider-vertex`](providers/vertex.md). |
+| `@arnilo/prism-provider-azure` | host Entra token or Azure resource key | Workload identity via `credential` callback; endpoint host preserved ([docs](providers/azure.md)). |
+| `@arnilo/prism-provider-bedrock` | host IAM/IRSA credentials | SigV4 over OpenAI-compatible Bedrock Runtime; region/PrivateLink preserved ([docs](providers/bedrock.md)). |
+| `@arnilo/prism-provider-vertex` | host ADC / workload token | OpenAPI-compatible Vertex endpoint; separate from consumer Google package ([docs](providers/vertex.md)). |
+
+A future provider-local OAuth package must first have explicit third-party permission and documented authorize/token/refresh flow. Before it registers an OAuth descriptor, it must add bounded request/response, abort, PKCE/state where required, expiry/refresh, secret-redaction, durable-store round-trip, and offline protocol tests. Do not add a generic OAuth framework, CLI credential scanner, automatic refresh timer, or success stub.
+
 ## Inputs / request
 
 ```ts
@@ -258,6 +271,8 @@ await kernel.load([pkg]);
 - Provider-specific behavior belongs in provider packages, not Prism core.
 - Adapter serializers should preserve Prism content blocks (text, thinking, tool_call, tool_result, and image when the model declares image input) in provider-native request shape, or fail explicitly when a block is unsupported.
 - Adapter header merging must put caller-supplied `ProviderRequest.options.headers` first and provider-owned headers last. Caller headers may add non-owned headers, but cannot replace resolved credentials, content type, session/cache/security headers, or provider attribution headers.
+- For allow-list/residency/budget/circuit selection before resolve, use optional `@arnilo/prism-model-router` over `createProviderResolver` — do not fork provider packages for governance.
+- Enterprise cloud adapters (`azure` / `bedrock` / `vertex`) stay separate from consumer Anthropic/Google packages and authenticate only through host credential callbacks.
 
 ## Manifest declarations
 
@@ -281,6 +296,8 @@ Manifest declarations are inert. The host must later resolve them through regist
 
 ## Related APIs
 
+- [Model routing](model-routing.md): optional governance router over `ProviderResolver`.
+- [Azure OpenAI / Foundry](providers/azure.md) / [Amazon Bedrock](providers/bedrock.md) / [Google Vertex AI](providers/vertex.md): enterprise workload-identity packages.
 - [Provider layer](provider-layer.md): provider/model registries and provider events.
 - [Provider conformance](provider-conformance.md): reusable network-free checks for provider adapters.
 - [Contribution registries](contribution-registries.md): registry bundle and extension contribution points.

package/docs/provider-request-policies.md

@@ -104,9 +104,11 @@ Policy output should stay generic: use `ProviderRequestOptions.cache`, `headers`
 - Cache keys must never be credentials.
 - Policy chains are O(number of policies) plus option merge cost.
 - Policies should be pure and synchronous unless the host explicitly accepts async work.
+- Optional `@arnilo/prism-model-router` returns a `ProviderRequestPolicy` that strips `openRouterRouting` unless governance allows it — chain it with other policies.
 
 ## Related APIs
 
+- [Model routing](model-routing.md): governance facade that emits a chainable OpenRouter routing gate policy.
 - [Provider caching](provider-caching.md): structured cache hints and helpers.
 - [Provider packages](provider-packages.md): registering policies from extension packages.
 - [Provider layer](provider-layer.md): provider request flow and `AIProvider.generate()`.

package/docs/providers/anthropic.md

@@ -8,7 +8,7 @@
 
 Use for native Claude Messages (tools, `cache_control`, thinking/reasoning, media, usage, abort). Prefer this over the AI SDK escape hatch when Anthropic is a primary coding host.
 
-Do **not** use for OpenCode Go Anthropic *route* hosting (`@arnilo/prism-provider-opencode-go`) or automatic credential discovery.
+Do **not** use for OpenCode Go Anthropic *route* hosting (`@arnilo/prism-provider-opencode-go`), automatic credential discovery, Claude Code credential-file/setup-token import, or Claude.ai subscription login/routing. This package is API-key-only.
 
 ## Inputs / request
 
@@ -43,7 +43,7 @@ Featured offline aliases: `claude-opus-4-8`, `claude-sonnet-5`, `claude-haiku-4-
 | Stream | Prism text, thinking deltas, tool-call delta/final, usage (incl. cache read/create when present), `done`, redacted `error`. |
 | Cache | Featured models use `cache.kind: "cache_control"`; markers on selected breakpoints (`long` → `ttl: "1h"`). |
 | Thinking | Model-family aware (`adaptive` vs `enabled`+`budget_tokens`); helpers `anthropicThinking` / `anthropicEffort` / `anthropicPreserveThinking`. |
-| Auth | `api_key` for provider id; provider-owned `content-type`, `x-api-key`, `anthropic-version` win over caller headers. |
+| Auth | `api_key` for provider id; provider-owned `content-type`, `x-api-key`, `anthropic-version` win over caller headers. No OAuth descriptor or subscription adapter is registered. |
 
 ## Request/response example
 
@@ -75,6 +75,7 @@ api.registerProviderPackage(createAnthropicProviderPackage({ apiKey: hostKey, mo
 - Register via `defineProviderPackage` / host registries; no package auto-discovery.
 - AI SDK (`@arnilo/prism-provider-ai-sdk`) remains an escape hatch, not the primary Anthropic path.
 - Live smoke: `PRISM_LIVE_PROVIDER_TESTS=1` + `ANTHROPIC_API_KEY`.
+- Anthropic says OAuth is for purchasers' ordinary Claude Code/native-app use; 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)). Prism therefore has no Anthropic subscription OAuth API or token-import shortcut.
 
 ## Security and performance notes
 

package/docs/providers/azure.md

@@ -0,0 +1,74 @@
+# Azure OpenAI / Foundry
+
+## What it does
+
+`@arnilo/prism-provider-azure` registers an Azure OpenAI / Foundry Chat Completions provider that uses host-supplied Entra workload identity (Bearer) or Azure resource keys (`api-key`). Deployment URLs keep the configured endpoint host (custom subdomain, private endpoint, or VNet FQDN).
+
+## When to use it
+
+Use it for enterprise Azure OpenAI / Foundry deployments with Managed Identity or host token providers. Do not fold this into consumer OpenAI packages. Do not embed static keys in fixtures.
+
+## Inputs / request
+
+```ts
+import { createAzureOpenAIProviderPackage } from "@arnilo/prism-provider-azure";
+
+createAzureOpenAIProviderPackage({
+  endpoint: "https://my-resource.openai.azure.com",
+  deployment: "gpt-4o",
+  apiVersion: "2024-10-21",
+  credential: hostEntraToken, // late-bound
+  authStyle: "bearer",
+  models: [{ provider: "azure", model: "gpt-4o" }],
+});
+```
+
+| Field | Meaning |
+| --- | --- |
+| `endpoint` | Absolute https resource URL; host preserved |
+| `deployment` | Deployment name (defaults to `model.model`) |
+| `apiVersion` | Query `api-version` (default `2024-10-21`) |
+| `credential` | `CredentialValueSource` — Entra token or resource key |
+| `authStyle` | `bearer` (default) or `api-key` |
+
+## Outputs / response / events
+
+Reuses `@arnilo/prism/providers/openai-compatible` streaming events (text, tool deltas, usage, done, redacted errors). Missing credentials fail closed before `fetch`.
+
+## Request/response example
+
+```http
+POST https://my-resource.privatelink.openai.azure.com/openai/deployments/gpt-4o/chat/completions?api-version=2024-10-21
+Authorization: Bearer <entra-token>
+```
+
+## Implementation example
+
+```ts
+const provider = createAzureOpenAIProvider({
+  endpoint: process.env.AZURE_OPENAI_ENDPOINT!,
+  deployment: "gpt-4o",
+  credential: () => entra.getToken("https://cognitiveservices.azure.com/.default").then((t) => t.token),
+});
+```
+
+Opt-in live canaries: inject real `fetch` + host credential behind host CI secrets — no secrets in repo.
+
+## Extension and configuration notes
+
+Register via `createExtensionKernel().load([createAzureOpenAIProviderPackage(...)])`. Pair with `@arnilo/prism-model-router` for residency allow-lists on Azure regions/endpoints.
+
+## Security and performance notes
+
+- No credential prefetch at import; resolve per request.
+- Endpoint host is never rewritten to public DNS.
+- Errors redact credential values via shared transport helpers.
+- No Azure SDK dependency.
+
+## Related APIs
+
+- [OpenAI-compatible provider](openai-compatible.md)
+- [Provider packages](../provider-packages.md)
+- [Model routing](../model-routing.md)
+- [Credential storage](../credential-storage.md)
+- Package README: [`@arnilo/prism-provider-azure`](../../packages/provider-azure/README.md)

package/docs/providers/bedrock.md

@@ -0,0 +1,72 @@
+# Amazon Bedrock
+
+## What it does
+
+`@arnilo/prism-provider-bedrock` registers an Amazon Bedrock Runtime OpenAI-compatible Chat Completions provider. Hosts supply IAM/IRSA/assumed-role credentials; the package signs requests with SigV4 (no AWS SDK). Region and optional PrivateLink endpoint URLs are preserved.
+
+## When to use it
+
+Use it for enterprise Bedrock access under workload identity. Do not embed long-lived keys in fixtures. Use model-router residency policy to deny disallowed regions.
+
+## Inputs / request
+
+```ts
+import { createBedrockProviderPackage } from "@arnilo/prism-provider-bedrock";
+
+createBedrockProviderPackage({
+  region: "eu-west-1",
+  // endpoint: "https://vpce-….bedrock-runtime.eu-west-1.vpce.amazonaws.com",
+  credential: () => hostAwsCredentials(),
+  models: [{ provider: "bedrock", model: "anthropic.claude-3-haiku-20240307-v1:0" }],
+});
+```
+
+| Field | Meaning |
+| --- | --- |
+| `region` | AWS region for signing + default endpoint |
+| `endpoint` | Optional https PrivateLink / VPC interface base URL |
+| `credential` | `{ accessKeyId, secretAccessKey, sessionToken? }` or async callback |
+| `signRequest` | Optional host SigV4 override |
+
+Default public base: `https://bedrock-runtime.{region}.amazonaws.com` → `/openai/v1/chat/completions`.
+
+## Outputs / response / events
+
+OpenAI-compatible SSE mapped to Prism provider events. Missing credentials fail closed before network I/O.
+
+## Request/response example
+
+```http
+POST https://bedrock-runtime.eu-west-1.amazonaws.com/openai/v1/chat/completions
+Authorization: AWS4-HMAC-SHA256 Credential=…/eu-west-1/bedrock/aws4_request, …
+X-Amz-Security-Token: …
+```
+
+## Implementation example
+
+```ts
+const provider = createBedrockProvider({
+  region: "us-east-1",
+  credential: async () => fromNodeProviderChain()(),
+});
+```
+
+Live canaries stay opt-in behind host credentials; default tests are network-free.
+
+## Extension and configuration notes
+
+Uses Bedrock’s OpenAI-compatible runtime route (not Converse eventstream). Hosts needing Converse-only models should supply a custom provider or AI SDK bridge.
+
+## Security and performance notes
+
+- No AWS SDK; package-local SigV4 only for `bedrock` service.
+- Private endpoint hosts are not rewritten to public DNS.
+- Credential secrets are redacted from provider errors.
+- No credential prefetch at import.
+
+## Related APIs
+
+- [OpenAI-compatible provider](openai-compatible.md)
+- [Model routing](../model-routing.md)
+- [Provider packages](../provider-packages.md)
+- Package README: [`@arnilo/prism-provider-bedrock`](../../packages/provider-bedrock/README.md)

package/docs/providers/google.md

@@ -8,7 +8,7 @@
 
 Use for first-party Gemini Developer API coding-host semantics (function calling, multimodal `inlineData`, thinking, usage, abort). Prefer this over the AI SDK escape hatch when Gemini is a primary host.
 
-Do **not** use for Vertex enterprise identity (deferred to 0.0.13+) or as a substitute for Anthropic Messages.
+Do **not** use for Vertex enterprise identity (deferred to 0.0.13+), as a substitute for Anthropic Messages, or Gemini CLI OAuth/credential-file/token import. This package is API-key-only.
 
 ## Inputs / request
 
@@ -43,7 +43,7 @@ Featured offline aliases include `gemini-2.5-pro`, `gemini-2.5-flash`, `gemini-2
 | Stream | Prism text, thinking when present, **complete** `tool_call` events (Gemini does not stream argument deltas), usage, `done`, redacted `error`. |
 | Cache | No Anthropic-style `cache_control`; Gemini implicit caching is not exposed as Prism breakpoints in 0.0.11. |
 | Multimodal | `inlineData` parts with MIME + base64; capability checks fail closed for unsupported modalities. |
-| Auth | `api_key`; provider-owned `content-type` + `x-goog-api-key` win over caller headers. |
+| Auth | `api_key`; provider-owned `content-type` + `x-goog-api-key` win over caller headers. No OAuth descriptor or Gemini CLI subscription adapter is registered. |
 
 ## Request/response example
 
@@ -71,6 +71,7 @@ api.registerProviderPackage(createGoogleProviderPackage({ apiKey: hostKey, model
 - AI SDK remains an escape hatch, not the primary Google path.
 - Live smoke: `PRISM_LIVE_PROVIDER_TESTS=1` + `GOOGLE_API_KEY` or `GEMINI_API_KEY`.
 - Vertex / enterprise identity stays out of 0.0.11.
+- Gemini CLI says third-party software accessing its backend through Gemini CLI OAuth violates applicable terms, and its FAQ directs third-party coding agents to Vertex AI or Google AI Studio API keys ([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)). Prism therefore has no Gemini CLI OAuth API or token-import shortcut.
 
 ## Security and performance notes
 
@@ -81,6 +82,7 @@ api.registerProviderPackage(createGoogleProviderPackage({ apiKey: hostKey, model
 
 ## Related APIs
 
+- [Google Vertex AI](vertex.md): enterprise ADC/workload-identity package (separate from this consumer API-key package).
 - [Provider packages](../provider-packages.md): package setup + discovery contract.
 - [Thinking and reasoning](../thinking-and-reasoning.md): portable thinking helpers.
 - [Provider conformance](../provider-conformance.md): network-free assertions.

package/docs/providers/openai-compatible.md

@@ -27,9 +27,11 @@ Options:
 | Field | Type | Purpose |
 | --- | --- | --- |
 | `id` | `string` | Optional provider id. Defaults to `openai-compatible`. |
-| `baseUrl` | `string` | Base API URL; `/chat/completions` is appended. |
+| `baseUrl` | `string` | Base API URL; `/chat/completions` is appended unless `chatCompletionsUrl` is set. |
 | `apiKey` | `CredentialValueSource` | Optional direct/callback/resolver credential source. |
 | `fetch` | `typeof fetch` | Optional fetch implementation for tests or custom hosts. |
+| `chatCompletionsUrl` | `string \| ((request) => string)` | Optional full chat-completions URL override (Azure deployment paths). |
+| `authStyle` | `"bearer" \| "api-key" \| "none"` | Auth header style. Default `bearer`. |
 
 Provider requests use the standard `ProviderRequest` shape: `model`, `messages`, optional `tools`, `metadata`, and `signal`.
 

package/docs/providers/openai.md

@@ -52,7 +52,7 @@ uses official Responses `reasoning: { effort, summary? }` via
 | --- | --- |
 | Provider stream | Prism text, thinking (downgraded to text), `tool_call` deltas/finals, `usage`, `done`, redacted `error` events. |
 | Block preservation | User/system text → `input_text`; assistant text → `output_text`; assistant `tool_call` → top-level `function_call` with `call_id`; `tool_result` → top-level `function_call_output`; images/files/audio when declared on the model. Bare thinking without an encrypted Responses reasoning item is omitted on replay. |
-| Auth methods | `api_key` for `openai`; `oauth` for `openai-codex`. |
+| Auth methods | `api_key` for `openai`; host-invoked subscription `oauth` for `openai-codex`. This is Prism's only first-party subscription OAuth flow in 0.0.12. |
 
 Unsupported block placements or unclaimed images fail before `fetch`.
 
@@ -120,7 +120,7 @@ const challenge = computeS256Challenge(verifier);
 - Hosts/apps control model selection, credential resolution, and cache policy per
   run/model through `RunOptions` and `ModelConfig.compat`.
 - OAuth browser/device-code flows run only when the caller explicitly invokes the
-  OAuth provider.
+  OAuth provider. Login UI and optional durable token storage remain host-owned; no ambient credential discovery or refresh timer is installed.
 - Device-code login polls the token endpoint with server-directed `interval` and
   `expires_in`, honors RFC 8628 `authorization_pending` / `slow_down`, and stops
   on terminal errors or expiry. Pass `signal` on `OAuthLoginCallbacks` to abort

package/docs/providers/openrouter.md

@@ -188,9 +188,11 @@ cache-read pricing exists), and seeds `compat.reasoning.effort` from
   hidden app identity.
 - Live tests stay opt-in behind `PRISM_LIVE_PROVIDER_TESTS=1` plus fake-safe
   provider-specific env names; default tests are network-free.
+- Enterprise hosts that must gate `compat.openRouterRouting` should wrap selection with `@arnilo/prism-model-router` (`allowOpenRouterRouting`); the OpenRouter adapter itself still passthroughs routing when present on the request.
 
 ## Related APIs
 
+- [Model routing](../model-routing.md): optional allow-list/residency/budget/circuit facade and OpenRouter routing gate.
 - [Provider packages](../provider-packages.md): `defineProviderPackage`,
   `ModelConfig`/`compat`, cache policy, caller-gated discovery.
 - [Thinking and reasoning](../thinking-and-reasoning.md): `applyThinkingLevel`

package/docs/providers/vertex.md

@@ -0,0 +1,71 @@
+# Google Vertex AI
+
+## What it does
+
+`@arnilo/prism-provider-vertex` registers a Vertex AI OpenAPI-compatible Chat Completions provider authenticated with host ADC / workload identity tokens. It is intentionally separate from `@arnilo/prism-provider-google` (consumer Gemini API keys).
+
+## When to use it
+
+Use it for GCP enterprise Vertex deployments with Application Default Credentials or workload identity federation. Do not use the consumer Google package for Vertex auth semantics.
+
+## Inputs / request
+
+```ts
+import { createVertexProviderPackage } from "@arnilo/prism-provider-vertex";
+
+createVertexProviderPackage({
+  projectId: "my-gcp-project",
+  location: "europe-west1",
+  credential: () => hostAdcAccessToken(),
+  models: [{ provider: "vertex", model: "google/gemini-2.0-flash-001" }],
+});
+```
+
+| Field | Meaning |
+| --- | --- |
+| `projectId` | GCP project |
+| `location` | Vertex location / region |
+| `endpoint` | Optional full https OpenAPI base (private/custom); otherwise location-scoped default |
+| `credential` | Bearer access token source (ADC / WIF) |
+
+Default base: `https://{location}-aiplatform.googleapis.com/v1/projects/{project}/locations/{location}/endpoints/openapi`.
+
+## Outputs / response / events
+
+OpenAI-compatible SSE → Prism provider events. Missing ADC token fails closed before `fetch`.
+
+## Request/response example
+
+```http
+POST https://europe-west1-aiplatform.googleapis.com/v1/projects/my-gcp-project/locations/europe-west1/endpoints/openapi/chat/completions
+Authorization: Bearer <adc-token>
+```
+
+## Implementation example
+
+```ts
+const provider = createVertexProvider({
+  projectId: "my-gcp-project",
+  location: "us-central1",
+  credential: async () => (await GoogleAuth.getAccessToken()),
+});
+```
+
+## Extension and configuration notes
+
+`@arnilo/prism-provider-google` remains API-key Gemini (`generativelanguage.googleapis.com`) and must not register Vertex OAuth/ADC. Load this package explicitly for Vertex.
+
+## Security and performance notes
+
+- No Google Cloud SDK dependency in the package.
+- Custom/private endpoint hosts are preserved.
+- Tokens redacted from errors; no import-time credential prefetch.
+- Pair with model-router residency allow-lists on `location`.
+
+## Related APIs
+
+- [Google Gemini (consumer)](google.md)
+- [OpenAI-compatible provider](openai-compatible.md)
+- [Provider packages](../provider-packages.md)
+- [Model routing](../model-routing.md)
+- Package README: [`@arnilo/prism-provider-vertex`](../../packages/provider-vertex/README.md)

package/docs/public-contracts.md

@@ -15,7 +15,8 @@ Current contract groups:
 - Extensions/middleware: `ExtensionLifecycleEventName`, `ExtensionEvent`, `Extension`, `ExtensionAPI`, `MiddlewareHookName`, `Middleware`, `MiddlewareNext`, `MiddlewareRegistry`
 - Configuration/manifests: `ConfigProvider`, `ConfigLayer`, `ConfigLoadContext`, `PrismManifest`, `ManifestContributionDeclaration`, `ManifestResourceDeclaration`, `ManifestContributionKind`
 - Stores/resources/settings/credentials/compaction/retry/cache helpers: `SessionEntry`, `SessionStore`, `StoreFactory`, `Resource`, `ResourceLoader`, `ResourceLoadContext`, `SettingsProvider`, `CredentialRequest`, `Credential`, `CredentialResolver`, `CompactionStrategy`, `CompactionContext`, `CompactionResult`, `CompactionOptions`, `CompactionMiddlewarePayload`, `CompactionEntryData`, `DefaultCompactionStrategyOptions`, `RetryPolicy`, `RetryContext`, `RetryDecision`, `RetryOptions`, `RetryMiddlewarePayload`, `DefaultRetryPolicyOptions`, `CacheUsageReport`, `sanitizeCacheKey`, `mapCacheRetention`, `applyCacheControl`, `cacheHitRate`, `cacheSavings`, `cacheUsageReport`
-- Production persistence (adapter-facing): `ProductionPersistenceStore`, `CheckpointStore`, `CheckpointKey`, `CheckpointSaveInput`, `CheckpointRecord`, `CheckpointQuery`, `LeaseStore`, `LeaseKey`, `LeaseAcquireInput`, `LeaseClaimInput`, `LeaseRecord`, `PersistencePage`, `PersistenceQuery`, `OwnershipScope`, `SessionRecord`, `SessionQuery`, `BranchRecord`, `BranchQuery`, `SessionEntryQuery`, `RunRecord`, `RunQuery`, `RunFeedbackRecord`, `RunFeedbackStore`, `RunFeedbackQuery`, `AgentEventRecord`, `AgentEventQuery`, `ToolCallRecord`, `ToolCallQuery`, `UsageRecord`, `UsageQuery`, `AgentDefinitionRecord`, `AgentDefinitionQuery`, `RetentionPolicy`, `RetentionPolicyQuery`, `MigrationRecord`, `MigrationQuery`
+- Production persistence (adapter-facing): `ProductionPersistenceStore` (optional `lifecycle`), `CheckpointStore`, `CheckpointKey`, `CheckpointSaveInput`, `CheckpointRecord`, `CheckpointQuery`, `LeaseStore`, `LeaseKey`, `LeaseAcquireInput`, `LeaseClaimInput`, `LeaseRecord`, `PersistencePage`, `PersistenceQuery`, `OwnershipScope`, `SessionRecord`, `SessionQuery`, `BranchRecord`, `BranchQuery`, `SessionEntryQuery`, `RunRecord`, `RunQuery`, `RunFeedbackRecord`, `RunFeedbackStore`, `RunFeedbackQuery`, `AgentEventRecord`, `AgentEventQuery`, `ToolCallRecord`, `ToolCallQuery`, `UsageRecord`, `UsageQuery`, `AgentDefinitionRecord`, `AgentDefinitionQuery`, `RetentionPolicy`, `RetentionPolicyQuery`, `MigrationRecord`, `MigrationQuery`, `PersistenceLifecycleStore`, `LegalHoldRecord`, `TenantQuota`
+- Identity: `Principal`, `AgentIdentity`, `IdentityVerifier`, `assertIdentityActive`, `narrowIdentity`, `ownershipFromIdentity`, `assertIdentityMatchesOwnership`, `assertIdentityPropagation`, `identityTelemetryAttributes`, `resolveRunIdentity`, `IdentityError`, identity limit constants
 
 ## When to use it
 
@@ -132,6 +133,7 @@ Important request shapes:
 | `AgentSessionConfig` | Session creation input: optional id, agent, store, leaf id, and metadata. |
 | `RunOptions` | Per-run overrides: optional abort signal, model, input layout, max tool rounds, provider options/request policies, system prompt layers, compaction, retry, metadata, skill selection, validate, redactor, and loop. |
 | `SubscribeOptions` / `SubscriberOverflowPolicy` | Live `AgentEvent` subscriber queue limit and overflow policy: `maxQueuedEvents`, `overflow: "close" \| "drop_oldest" \| "drop_newest"`. |
+| `resumeAgentRunStream` / `AgentRunResumeStreamOptions` | One durable-run event stream: existing checkpoint/resume options plus `signal` and bounded subscriber options. `AgentRunLifecycle.resumeStream()` adds host capability resolution; no protocol types enter core. |
 | `AgentConfig.loop` / `RunOptions.loop` | Replaceable per-run control loop: `singleShotLoop` default, `generate-validate-revise` options, or a custom `AgentLoopStrategy`. `RunOptions.loop` wins. See [Agent loops](agent-loops.md). |
 | `AgentLoopStrategy` | `{ name; run(ctx: LoopContext): Promise<Usage \| undefined> }` — orchestrates shared runtime primitives via `LoopContext`. |
 | `LoopContext` | Loop-facing surface: run ids, signal, live `history`, `input`/`inputMessages`/`maxToolRounds`, and bound `assemble`/`generate`/`dispatchToolCall`/`appendMessage`/`emit` primitives. |
@@ -164,6 +166,7 @@ Important request shapes:
 | `CacheUsageReport` | Numeric cache diagnostics from normalized `Usage`: read/write tokens, hit rate, estimated savings, and optional currency. |
 | `AgentDefinitionRecord` / `AgentDefinitionQuery` | Versioned agent-definition snapshot and filters. Does not store credentials or provider instances. |
 | `RetentionPolicy` / `RetentionPolicyQuery` | Retention policy and filters: age, entry count, byte limits, archive store, applied kinds. |
+| `PersistenceLifecycleStore` / `LegalHoldRecord` / `TenantQuota` | Optional hold/retention apply/export/quota capability on `ProductionPersistenceStore.lifecycle`. |
 | `MigrationRecord` / `MigrationQuery` | Applied migration record and filters. |
 
 ## Outputs / response / events
@@ -447,6 +450,7 @@ void credentials;
 - [Agent/session runtime](agent-session-runtime.md): `createAgent()` / `createAgentSession()` runtime, `AgentSession.compact()`, and auto-compaction config built on these contracts.
 - [Agent loops](agent-loops.md): `singleShotLoop` default, `generateValidateReviseLoop`, `resolveLoop`, and the `Artifact*`/`AgentLoop*`/`LoopContext` contracts.
 - [Agent events](agent-events.md): the `AgentEvent` union including `artifact_*` variants and event ordering.
+- [Frontend interoperability (AG-UI and ACP)](ag-ui.md): optional protocol package consuming `AgentEvent`, `AgentRunLifecycle`, `OwnershipScope`, and `AgentEventRecord`; AG-UI/ACP protocol types do not enter root contracts.
 - [Structured output](structured-output.md): the `ArtifactParser<T>`/`ArtifactValidator<T>`/`ArtifactRepairer<T>` seam — the only typed-output path from a loop.
 - [Session stores](session-stores.md): `SessionStore` contract, branch-aware `SessionEntry` helpers, context rebuild, and store responsibilities.
 - [Database persistence](database-persistence.md): production persistence contracts, paginated query shapes, reference schema, indexes, retention, migrations, and NoSQL mapping.