@arnilo/prism 0.4.0 → 0.5.1

package/docs/process-sessions.md

@@ -2,7 +2,7 @@
 
 ## What it does
 
-`createProcessSessions` is an optional host-activated registry in `@arnilo/prism-coding-agent` for **long-running** child processes: start, cursor-paged output, input, wait, signal/kill, and release (detach). Sessions have bounded lifetime (sweep on registry access — no import-time timers), ownership/identity attribution, durable metadata (command fingerprint without env/secrets), and typed `CodingProcessEvent`s via a host callback. Reuses `ExecutionPolicy`, `killProcessTree`, and `OutputAccumulator` (including spill + `readRaw` cursor paging). Optional duck-typed `sandbox` backend uses `startProcess` when present; one-shot adapters fail closed. Nothing spawns on import or construction.
+`createProcessSessions` is an optional host-activated registry in `@arnilo/prism-coding-tools/agent` for **long-running** child processes: start, cursor-paged output, input, wait, signal/kill, and release (detach). Sessions have bounded lifetime (sweep on registry access — no import-time timers), ownership/identity attribution, durable metadata (command fingerprint without env/secrets), and typed `CodingProcessEvent`s via a host callback. Reuses `ExecutionPolicy`, `killProcessTree`, and `OutputAccumulator` (including spill + `readRaw` cursor paging). Optional duck-typed `sandbox` backend uses `startProcess` when present; one-shot adapters fail closed. Nothing spawns on import or construction.
 
 | Export | Purpose |
 | --- | --- |
@@ -20,7 +20,7 @@
 Use when a host needs attachable long-running processes (watch modes, language servers, interactive CLIs) that one-shot `shell` cannot model. Do not use as a job-control language. `pty: true` (host-selected PTY) requires a `ptyBackend` passed to `createProcessSessions`; without one it fails closed before spawn with `ERR_PRISM_PROCESS_PTY_UNSUPPORTED`. Pass a sandbox with `startProcess` for contained long-running work; omit `sandbox` for native spawn.
 
 ```ts
-import { createProcessSessions } from "@arnilo/prism-coding-agent";
+import { createProcessSessions } from "@arnilo/prism-coding-tools/agent";
 
 const sessions = createProcessSessions({ cwd: workspaceRoot, policy, sandbox, onEvent });
 const p = await sessions.start({ command: "npm", args: ["test", "--", "--watch"] });

package/docs/prompt-registry.md

@@ -2,12 +2,12 @@
 
 ## What it does
 
-The optional `@arnilo/prism-prompts` package stores prompt assets as immutable, content-hashed versions. It provides a memory store plus SQLite and PostgreSQL adapters. The registry returns prompt data; it does not compose system-prompt layers, evaluate prompt quality, discover files, or activate text.
+The optional `@arnilo/prism-core/governance/prompts` package stores prompt assets as immutable, content-hashed versions. It provides a memory store plus SQLite and PostgreSQL adapters. The registry returns prompt data; it does not compose system-prompt layers, evaluate prompt quality, discover files, or activate text.
 
 ## Inputs / request
 
 ```ts
-import { createMemoryPromptStore } from "@arnilo/prism-prompts";
+import { createMemoryPromptStore } from "@arnilo/prism-core/governance/prompts";
 
 const store = createMemoryPromptStore();
 const version = await store.put({
@@ -57,10 +57,10 @@ The ref is opaque identity — name, version number, and the store's SHA-256 bod
 ## Durable adapters
 
 ```ts
-import { createSqlitePromptStore } from "@arnilo/prism-prompts";
+import { createSqlitePromptStore } from "@arnilo/prism-core/governance/prompts";
 const sqlite = createSqlitePromptStore({ filename: "./prompts.db" });
 
-import { createPostgresPromptStore } from "@arnilo/prism-prompts";
+import { createPostgresPromptStore } from "@arnilo/prism-core/governance/prompts";
 const postgres = await createPostgresPromptStore({
   connectionString: process.env.DATABASE_URL,
   schema: "prism",
@@ -74,7 +74,7 @@ SQLite uses `better-sqlite3`; PostgreSQL uses a caller-supplied or adapter-owned
 `assertPromptPromotion` composes [evaluations](evaluations.md) with the store to answer one question — should this candidate version replace the baseline? It resolves both versions (read-only), runs them head-to-head over a dataset through `runComparison`, and returns a typed verdict. It never promotes anything, writes nothing, and never touches a live agent:
 
 ```ts
-import { assertPromptPromotion } from "@arnilo/prism-prompts";
+import { assertPromptPromotion } from "@arnilo/prism-core/governance/prompts";
 
 const v = await assertPromptPromotion({
   store,
@@ -90,13 +90,13 @@ const v = await assertPromptPromotion({
 if (v.verdict === "promote") await store.put({ ...hostInput, body: v.candidate.body, labels: ["production"] });
 ```
 
-The verdict carries `promote`/`hold`, per-scorer `wins/losses/ties/failures`, `winRate`, the raw `ComparisonReport`, a redacted bounded `reportJson` (`serializeEvaluationReport`), and `reasons` on hold. The default gate holds unless the candidate wins strictly more scored comparisons than the baseline; `minimumWinRate` and `thresholds` add stricter gates, and threshold equality passes. Requires the optional peer `@arnilo/prism-evals` (install it or the helper fails closed with `ERR_PRISM_PROMPT_EVALS_PEER`). Promotion itself stays a host decision: applying the verdict means `put`-ing a new version with labels — the helper never does.
+The verdict carries `promote`/`hold`, per-scorer `wins/losses/ties/failures`, `winRate`, the raw `ComparisonReport`, a redacted bounded `reportJson` (`serializeEvaluationReport`), and `reasons` on hold. The default gate holds unless the candidate wins strictly more scored comparisons than the baseline; `minimumWinRate` and `thresholds` add stricter gates, and threshold equality passes. Requires the optional peer `@arnilo/prism-core/governance/evals` (install it or the helper fails closed with `ERR_PRISM_PROMPT_EVALS_PEER`). Promotion itself stays a host decision: applying the verdict means `put`-ing a new version with labels — the helper never does.
 
 ## Limits and security
 
 Names, bodies, labels, metadata, cursors, pages, and diffs have finite defaults and hard caps. Prompt bodies are data: no evaluation, template execution, file discovery, or implicit layer injection occurs. Store body hashes are integrity checks; a durable row whose hash no longer matches its body fails closed. Never put credentials or provider clients in prompt metadata.
 
-Threat model: the registry is **host-trusted data**. Anyone who can write versions into the store is inside the trust boundary — `put`, label management, and `assertPromptPromotion` verdicts are host operations, never agent-reachable surfaces. Untrusted prompt-injection defense stays at Prism's existing untrusted-content boundaries (tool results, attachments, and provider output), which the store neither bypasses nor weakens: a resolved body enters the system-prompt layer exactly like a host-authored constant. The optional `@arnilo/prism-evals` peer is only loaded by `assertPromptPromotion` and never makes the store itself depend on evaluation infrastructure.
+Threat model: the registry is **host-trusted data**. Anyone who can write versions into the store is inside the trust boundary — `put`, label management, and `assertPromptPromotion` verdicts are host operations, never agent-reachable surfaces. Untrusted prompt-injection defense stays at Prism's existing untrusted-content boundaries (tool results, attachments, and provider output), which the store neither bypasses nor weakens: a resolved body enters the system-prompt layer exactly like a host-authored constant. The optional `@arnilo/prism-core/governance/evals` peer is only loaded by `assertPromptPromotion` and never makes the store itself depend on evaluation infrastructure.
 
 ## Related APIs
 

package/docs/provider-caching.md

@@ -12,6 +12,8 @@ Provider caching documents Prism's cache intent surface:
 
 Cache hints are best-effort. They describe intent; providers decide whether their native API can use them. Prism does not guarantee cache hits.
 
+**Kernel defaults (0.5.1).** `applyDefaultProviderRequestOptions` fills `cache.breakpoints` with `{ location: "system_prompt" }` and `{ location: "last_stable_message" }` plus `cacheRetention: "short"` when `model.cache.kind === "cache_control"` or `model.cache.explicitBreakpoints === true`, unless the host set `cache.mode: "off"`, `cacheRetention: "none"`, or a non-empty breakpoint list. Implicit / `none` / host-owned (Azure, Bedrock, Vertex, AI SDK) models get no Prism markers. Session and cache keys are correlation ids — Cache keys must never be credentials.
+
 ## When to use it
 
 Use this page when a host or provider package needs to:
@@ -150,8 +152,10 @@ Provider request policies can set `ProviderRequestOptions.cache` or the legacy `
 | `@arnilo/prism-providers/openai` | `openai_key` | Sends sanitized `prompt_cache_key`; pre-5.6 models emit `prompt_cache_retention: "24h"` when `longRetention`; GPT-5.6+ models (`explicitBreakpoints`) map `cache.breakpoints`/`cache.mode: "on"` to `prompt_cache_options: { mode: "explicit" }` + `prompt_cache_breakpoint` markers (≤4 writes). | Stable cache key + stable prefix can improve reuse; keep selected anchors stable. | Best-effort only; `"short"`/`"none"` omit retention; `"30m"` TTL is the default and never emitted. |
 | `@arnilo/prism-providers/anthropic` | `cache_control` | Marks only selected Anthropic message anchors; `system_prompt` breakpoints emit native `system` text blocks with the marker; `"long"` maps to documented `ttl: "1h"`. | Keep selected anchors stable. | Best-effort; never stamp every block. |
 | `@arnilo/prism-providers/google` | none | Sends no Prism cache marker. | Host/model may have upstream behavior. | Gemini cache controls are not mapped in this package. |
-| `@arnilo/prism-providers/openrouter` | `cache_control` | Top-level automatic `cache_control` when enabled without breakpoints; otherwise markers only on caller-selected `cache.breakpoints`; `"long"` may add `ttl: "1h"`. Sticky `session_id` routing. | Breakpoint-stable / automatic prefixes can be reused by upstream providers. | Best-effort only; top-level automatic may exclude some backends from routing. |
+| `@arnilo/prism-providers/openrouter` | `cache_control` | Kernel defaults (agent session / helper) emit **per-message** `cache_control` on `system_prompt` + `last_stable_message`. Raw `generate` with empty breakpoints may still send top-level automatic `cache_control`. `"long"` may add `ttl: "1h"`. Sticky `session_id` routing. | Breakpoint-stable prefixes can be reused by upstream providers. | Best-effort only; top-level automatic may exclude some backends from routing. |
 | `@arnilo/prism-providers/opencode-go` | route-specific | Sends sanitized `x-opencode-session`; Anthropic route applies selected `cache_control` breakpoints; OpenAI route sends none. | Session id + unchanged selected anchors can help route-native caches. | Best-effort and route-dependent. |
+| `@arnilo/prism-providers/hyper` | route-specific implicit / `cache_control` | Chat route sends no markers (implicit prefix caching); `qwen3.6-*` messages route applies `cache_control` only to caller-selected `cache.breakpoints` (max 4); **no `ttl`** (undocumented). Opt-in responses route emits OpenAI-standard `prompt_cache_key` from hints only, never retention/options. | Keep selected Anthropic anchors and prior history stable. | Best-effort only; `402 billing_error` when Hypercredits run out. |
+| `@arnilo/prism-providers/commandcode` | route-specific implicit / `cache_control` | Chat route sends no markers (implicit prefix caching); `claude-*` messages route applies `cache_control` only to caller-selected `cache.breakpoints` (max 4); **no `ttl`** (undocumented). GPT-5.6 tiers keep docs `cacheWrite` prices in `cost` but stay implicit until the live probe verifies `prompt_cache_key`. | Keep selected Anthropic anchors and prior history stable. | Best-effort only; GPT-5.6 explicit `prompt_cache_key` upgrade pending probe (plan 055 Task 9); OSS models bill at mean per-provider price; DeepSeek off-peak 17h/day, peak 2×. |
 | `@arnilo/prism-providers/zai` | `implicit` | No explicit cache payload; GLM context caching is automatic. | Resend unchanged prior history for implicit context-cache reuse. | Best-effort only; cache options do not force hits. |
 | `@arnilo/prism-providers/kimi` | implicit by default, optional `cache_control` | Default catalog models send no `cache_control`; hosts may opt in on Anthropic `/messages` models with `ModelConfig.cache.kind: "cache_control"`. | Keep selected Anthropic anchors and prior history stable. | Best-effort and model/route-dependent. |
 | `@arnilo/prism-providers/neuralwatt` | `implicit` | No `cache_control`, `cacheKey`, `prompt_cache`, or `cacheRetention` payload; NeuralWatt vLLM prefix caching is automatic. | Full prior history must be resent unchanged with only the new turn appended; `inputLayout: "cache_aware"` keeps stable prefixes first. | Best-effort only; does not promise cache hits; `cacheRetention: "none"` disables Prism hints only, not the implicit backend prefix cache. |
@@ -171,8 +175,10 @@ Detailed first-party provider notes:
 - OpenAI-compatible Chat Completions adapter: minimal scope, sends no cache payload; see [OpenAI-compatible provider](providers/openai-compatible.md).
 - Anthropic (`@arnilo/prism-providers/anthropic`): `kind: "cache_control"`; selected Anthropic message anchors receive `cache_control` and eligible long retention maps to `ttl: "1h"`. A `system_prompt` breakpoint serializes `system` as native text blocks carrying the marker (shared `systemCacheControlField()` helper; plain joined string when unmarked). Cache read/create usage maps to normalized cache read/write tokens.
 - Google (`@arnilo/prism-providers/google`): sends no Prism cache-control payload. Do not infer cache hits or cache token counts from absent Gemini fields.
-- OpenRouter (`@arnilo/prism-providers/openrouter`): `kind: "cache_control"`. Sanitizes/clamps `session_id`/`X-Session-Id` to 256 chars for sticky routing (from `cache.key` ?? legacy `cacheKey` ?? `sessionId`); with no breakpoints emits top-level automatic `cache_control: { type: "ephemeral" }`; with breakpoints applies Anthropic-style markers only to caller-selected locations (last content block of each selected message); `"long"` retention adds `ttl: "1h"` when the model allows it. `prompt_tokens_details.cached_tokens`/`cache_write_tokens` map to `Usage.cacheReadTokens`/`cacheWriteTokens`. Optional `listOpenRouterModels()` may populate `ModelConfig.cache`/`cost` from live pricing.
+- OpenRouter (`@arnilo/prism-providers/openrouter`): `kind: "cache_control"`. Sanitizes/clamps `session_id`/`X-Session-Id` to 256 chars for sticky routing (from `cache.key` ?? legacy `cacheKey` ?? `sessionId`); kernel defaults supply `system_prompt` + `last_stable_message` breakpoints so agent-session requests use per-message markers (not top-level automatic). Raw `generate` with empty breakpoints still emits top-level automatic `cache_control: { type: "ephemeral" }`; `"long"` retention adds `ttl: "1h"` when the model allows it. `prompt_tokens_details.cached_tokens`/`cache_write_tokens` map to `Usage.cacheReadTokens`/`cacheWriteTokens`. Optional `listOpenRouterModels()` may populate `ModelConfig.cache`/`cost` from live pricing.
 - OpenCode Go (`@arnilo/prism-providers/opencode-go`): default base `https://opencode.ai/zen/go/v1`; `x-opencode-session` from `cacheKey ?? sessionId`, sanitized to 128 chars; the Anthropic route (MiniMax/Qwen) applies `cache_control` markers only to selected breakpoints (`"long"` → `ttl: "1h"`), the OpenAI route (Grok/GLM/Kimi/MiMo/DeepSeek) sends none and preserves `reasoning_content`. OpenAI route maps `prompt_tokens_details.cached_tokens`/`cache_write_tokens`; Anthropic route maps `cache_read_input_tokens`/`cache_creation_input_tokens`. Caller-gated `listOpenCodeGoModels` against official `GET /zen/go/v1/models`.
+- Hyper (`@arnilo/prism-providers/hyper`): `kind: "implicit"` on the chat route, `kind: "cache_control"` on the messages route. Model route selection follows the live catalog's pricing shape: models with explicit cache-write pricing (qwen3.6-*) default to the Anthropic route; the rest stay chat-route implicit with the write fee recorded in `cost.cacheWrite`. The messages route applies `cache_control: { type: "ephemeral" }` only to caller-selected `cache.breakpoints` (shared `applyCacheControl`, max 4) — never every block, and **never a `ttl`** (Hyper documents no TTL values). Chat route maps `prompt_tokens_details.cached_tokens`/`cache_write_tokens` (and `prompt_cache_hit_tokens`); messages route maps `cache_read_input_tokens`/`cache_creation_input_tokens`. `parseHyperUsageCost` surfaces USD/cost/remaining Hypercredits from the OpenAI usage chunk for cost telemetry; `402 billing_error` is the drained-balance signal. Caller-gated `listHyperModels`; operator-gated `getHyperCredits`.
+- Command Code (`@arnilo/prism-providers/commandcode`): `kind: "implicit"` on the chat route, `kind: "cache_control"` on the messages route. `claude-*` tiers (the only Anthropic-route models by server-enforced routing) default to `cache_control` with markers only on caller-selected `cache.breakpoints` max 4 — never every block, and **never a `ttl`** (the upstream TTL window is undocumented). GPT-5.6 sol/terra/luna keep the docs cache-write price in `cost.cacheWrite` but stay `implicit` until the live `prompt_cache_key` probe passes (plan 055 Task 9); all other chat-route models are implicit with `prompt_cache_hit_tokens`/`cached_tokens` mapped by the shared OpenAI usage mapping. Messages route maps `cache_read_input_tokens`/`cache_creation_input_tokens`. Billing caveats: OSS models bill at the mean per-provider price; DeepSeek off-peak rates (17h/day) with ~2× peak 01–04 & 06–10 UTC; deals (MiniMax M3, MiMo) auto-applied. Caller-gated `listCommandCodeModels`; optional ZDR (`zdr: true`) adds `x-cmd-zdr: 1` and may route to costlier upstreams or fail `422 cmd_zdr_no_providers`.
 - Z.AI (`@arnilo/prism-providers/zai`): `kind: "implicit"`. GLM context caching is automatic; sends no explicit cache payload regardless of cache options. `prompt_tokens_details.cached_tokens`/`cache_write_tokens` map to `Usage.cacheReadTokens`/`cacheWriteTokens`.
 - NeuralWatt (`@arnilo/prism-providers/neuralwatt`): `kind: "implicit"`. NeuralWatt prefix caching is automatic; sends no explicit cache payload regardless of cache options. `cacheRetention: "none"` disables Prism cache-control hints only (not the implicit backend prefix cache). `prompt_tokens_details.cached_tokens` maps to `Usage.cacheReadTokens`; NeuralWatt does not report a cache-write token, so `Usage.cacheWriteTokens` is never fabricated (stays `undefined`). NeuralWatt's `/v1/models` catalog advertises exact `cached_input_per_million` rates for cache reads and `cached_output_per_million: null`; static curated aliases do not guess those prices.
 - Kimi (`@arnilo/prism-providers/kimi`): default catalog models use implicit caching (no `cache_control`); hosts opt in via `ModelConfig.cache.kind: "cache_control"` on the Anthropic `/messages` route, then `cache_control` markers apply only to selected breakpoints (`"long"` → `ttl: "1h"`); the Moonshot OpenAI route sends none. `cache_read_input_tokens`/`cache_creation_input_tokens` map to `Usage.cacheReadTokens`/`cacheWriteTokens`.

package/docs/provider-conformance.md

@@ -31,13 +31,15 @@ Offline conformance is mandatory for every package; credentialed probes are not
 | Package | Required offline evidence | Restricted live evidence |
 | --- | --- | --- |
 | OpenAI | Responses serialization/stream ordering, provider-hosted authority, continuation cap/cursor, Realtime fake WebSocket caps | Standard API-key smoke; separate protected hosted-tool/Realtime entitlement probe |
-| AI SDK | Exact 4.0.4/V4 gate (`4.0.3` also listed); every mapped stream part; authority, cache usage, redaction, unsupported mapping | Host-created V4 model only; no Prism credential fixture |
+| AI SDK | Exact 4.0.10/V4 gate (`4.0.3` and `4.0.4` also listed); every mapped stream part; authority, cache usage, redaction, unsupported mapping | Host-created V4 model only; no Prism credential fixture |
 | Anthropic | Messages serialization, cache/thinking/tools, header/redaction/abort assertions | Protected `ANTHROPIC_API_KEY` smoke |
 | Google | `generateContent` serialization, complete tool calls, media/abort/redaction assertions | Protected `GOOGLE_API_KEY` or `GEMINI_API_KEY` smoke |
 | Kimi | Coding/Moonshot route fixtures, thinking/tool reconstruction, headers/redaction | Protected `KIMI_API_KEY` smoke |
 | Z.AI | GLM thinking/tool-stream fixtures, implicit-cache usage, headers/redaction | Protected `ZAI_API_KEY` smoke |
 | OpenRouter | routing/reasoning/cache-control fixture, stream/tool reconstruction, headers/redaction | Protected `OPENROUTER_API_KEY` smoke |
 | OpenCode Go | OpenAI/Anthropic route fixture, completion proof, PDF/media boundary, headers/redaction | Protected `OPENCODE_API_KEY` smoke |
+| Hyper | dual-route OpenAI/Anthropic fixtures, thinking/effort replay, message-delta usage at end, cache-breakpoint fixture, auth/redaction | Protected `HYPER_API_KEY` smoke |
+| Command Code | dual-route OpenAI/Anthropic fixtures, thinking replay, no-`ttl` cache-breakpoint fixture, ZDR header ownership, 403/422 classification, auth/redaction | Protected `COMMAND_CODE_API_KEY` smoke |
 | Alibaba | DashScope presets, Qwen thinking, image rejection/mapping, cache/usage fixture | Protected account/region host probe; no generic key fixture |
 | Ollama | cloud/local preset, reasoning/image mapping, implicit-cache fixture | Protected cloud or host-local authenticated daemon probe; no daemon starts in tests |
 | NeuralWatt | stream/retry/quota/telemetry fixtures, implicit-cache usage, headers/redaction | Protected `NEURALWATT_API_KEY` smoke |
@@ -47,6 +49,26 @@ Offline conformance is mandatory for every package; credentialed probes are not
 
 All rows must retain bounded request/response fixtures, abort propagation, provider-owned-header precedence, and fake-secret leak assertions where the package surfaces those values. A successful fake transport proves Prism mapping, not account entitlement or vendor availability.
 
+## Modality conformance matrix (plan 061)
+
+One provider-neutral contract per modality, each with a capability flag, a typed error family, and an offline conformance runner from `@arnilo/prism/testing/provider-conformance`. Fake transports prove Prism mapping and typed-cap behavior only — never account entitlement or vendor availability.
+
+| Contract / runner | Offline evidence (fake transport) | Live probe |
+| --- | --- | --- |
+| `EmbeddingsProvider` — `runEmbeddingsConformance` | batch-cap/empty-input typed errors, index-ordered vectors, dimensions truthfulness, usage | probe pending |
+| `SpeechProvider` — `runSpeechConformance` | input/byte caps typed, audio bytes + mime provenance, first-chunk streaming | probe pending |
+| `TranscriptionProvider` — `runTranscriptionConformance` | audio caps typed, SSE partials, terminal transcript | probe pending |
+| `ImageGenerationProvider` — `runImageGenerationConformance` | prompt/byte caps typed, b64 provenance, edit route | probe pending |
+| `VideoGenerationProvider` — `runVideoGenerationConformance` | submit/status lifecycle, terminal-only resolution, provenance | probe pending |
+| `ModerationProvider` — `runModerationConformance` | empty/oversized typed errors, neutral category mapping + raw passthrough, score range [0,1], no local thresholds | probe pending |
+| `BatchJobsProvider` — `runBatchJobsConformance` | empty/oversized submits typed, opaque ids, state union, `pollBatch` terminal resolution, paged results walk to exhaustion | probe pending |
+
+Failure/cancel terminal transitions for long-running contracts (video, batch) are covered by provider fakes in the adapter suites; `pollBatch` surfaces typed `job_failed`/`job_cancelled`/`job_expired` errors. Live probes stay operator-gated like the package matrix above; ledger rows live in `docs/_evidence/modality-contracts-2026-09-03.md` marked "probe pending" until run.
+
+## Nightly live-provider canary (plan 060)
+
+`.github/workflows/canary-providers.yml` runs nightly (`0 3 * * *`, plus `workflow_dispatch`) against the `live-canaries` environment. Each matrix leg runs one provider's existing live suite (text completion + tool-call/structured legs, `assertNoSecretLeak` inside); legs skip without their key. The provider set is the `PRISM_CANARY_PROVIDERS` repo variable (JSON array, default `["openai"]`). Evidence is per-leg and aggregate job summaries (statuses only — responses are never logged); any failure opens a tracking issue and blocks nothing.
+
 ## Inputs / request
 
 ```ts

package/docs/provider-packages.md

@@ -18,6 +18,36 @@ 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.
 
+### Provider inventory
+
+<!-- generated:package-truth:providers begin -->
+**20 provider adapters** — first-party adapters ship as `@arnilo/prism-providers/<adapter>` subpaths in one tarball (importing one never evaluates another):
+
+| adapter package | version |
+| --- | --- |
+| `@arnilo/prism-providers/ai-sdk` | 0.5.1 |
+| `@arnilo/prism-providers/alibaba` | 0.5.1 |
+| `@arnilo/prism-providers/anthropic` | 0.5.1 |
+| `@arnilo/prism-providers/azure` | 0.5.1 |
+| `@arnilo/prism-providers/bedrock` | 0.5.1 |
+| `@arnilo/prism-providers/clinepass` | 0.5.1 |
+| `@arnilo/prism-providers/commandcode` | 0.5.1 |
+| `@arnilo/prism-providers/deepseek` | 0.5.1 |
+| `@arnilo/prism-providers/google` | 0.5.1 |
+| `@arnilo/prism-providers/hyper` | 0.5.1 |
+| `@arnilo/prism-providers/kimi` | 0.5.1 |
+| `@arnilo/prism-providers/model-discovery` | 0.5.1 |
+| `@arnilo/prism-providers/neuralwatt` | 0.5.1 |
+| `@arnilo/prism-providers/ollama` | 0.5.1 |
+| `@arnilo/prism-providers/openai` | 0.5.1 |
+| `@arnilo/prism-providers/opencode-go` | 0.5.1 |
+| `@arnilo/prism-providers/openrouter` | 0.5.1 |
+| `@arnilo/prism-providers/vertex` | 0.5.1 |
+| `@arnilo/prism-providers/xai` | 0.5.1 |
+| `@arnilo/prism-providers/zai` | 0.5.1 |
+<!-- generated:package-truth:providers end -->
+
+
 ### Subscription OAuth support matrix
 
 | Package | 0.0.12 auth registration | Subscription OAuth boundary |
@@ -28,6 +58,8 @@ Do not use provider packages as a package manager, credential store, env loader,
 | `@arnilo/prism-providers/clinepass` | `api_key` only | No Cline WorkOS / Cline OAuth store share. Host supplies `CLINE_API_KEY`. |
 | `@arnilo/prism-providers/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-providers/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-providers/vertex`](providers/vertex.md). |
+| `@arnilo/prism-providers/hyper` | `api_key` only | No subscription OAuth — Charm Hyper is pay-per-use Hypercredits; host supplies `HYPER_API_KEY` (keys start `sk-hyper-`). |
+| `@arnilo/prism-providers/commandcode` | `api_key` only | No subscription OAuth — Command Code Go/GOAT/Pro/Max coding plans and the Provider plan all authenticate with the same Studio API key; host supplies `COMMAND_CODE_API_KEY`. |
 | `@arnilo/prism-providers/azure` | host Entra token or Azure resource key | Workload identity via `credential` callback; endpoint host preserved ([docs](providers/azure.md)). |
 | `@arnilo/prism-providers/bedrock` | host IAM/IRSA credentials | SigV4 over OpenAI-compatible Bedrock Runtime; region/PrivateLink preserved ([docs](providers/bedrock.md)). |
 | `@arnilo/prism-providers/vertex` | host ADC / workload token | OpenAPI-compatible Vertex endpoint; separate from consumer Google package ([docs](providers/vertex.md)). |
@@ -58,18 +90,15 @@ export default defineProviderPackage({
 
 `compat` is provider-owned inert JSON. Core does not branch on provider names or interpret vendor-specific fields.
 
-Provider packages can also contribute auth descriptors and request policies without resolving credentials:
+Provider packages can also contribute auth descriptors and prompt layers without resolving credentials:
 
 ```ts
-import { createSessionCachePolicy } from "@arnilo/prism";
-
 api.registerAuthMethod({ provider: "demo", kind: "api_key", credentialName: "apiKey" });
 api.registerAuthMethod({ provider: "demo", kind: "oauth", oauth: demoOAuthProvider });
-api.registerProviderRequestPolicy(createSessionCachePolicy({ retention: "short" }));
 api.registerSystemPromptContribution({ id: "demo-prompt", source: "package", mode: "append", text: "Use demo provider rules." });
 ```
 
-Hosts decide which credential resolvers, env objects, OAuth stores, request policies, and prompt contributions become active. Request policies can set generic `ProviderRequest.options` such as `sessionId`, `cacheRetention`, `headers`, `compat`, and opaque `extra`; provider adapters decide how to map those options to provider payloads. Caller headers are extension headers only: provider adapters must apply provider-owned headers (auth, content type, session/cache/security, attribution) after caller headers so requests cannot override credentials or provider policy.
+Host picks provider + model + intent (messages, tools, optional `thinkingLevel` / cache retention). Prism constructs a valid wire request for every generate site it owns. Host request policies are overlays — they are never required for success. Hosts still own credentials, env objects, OAuth stores, extra headers, custom `cacheKey`, `compat`/`extra` overlays, and which prompt contributions become active. Request policies can overlay generic `ProviderRequest.options` such as `sessionId`, `cacheRetention`, `headers`, `compat`, and opaque `extra`; provider adapters map those options to provider payloads. Caller headers are extension headers only: provider adapters must apply provider-owned headers (auth, content type, session/cache/security, attribution) after caller headers so requests cannot override credentials or provider policy.
 
 Provider request options: `ProviderRequestOptions` carries session/cache/header/compat/extra hints only. Timeouts are host-owned (`RunOptions.signal`/host abort controllers); retries are runtime-owned (`AgentConfig.retry`/`RunOptions.retry`). Provider-level timeout/retry hints were removed in 0.1.5. Provider packages should not add provider-specific retry loops unless the vendor protocol requires it and runtime retry cannot cover the failure mode.
 
@@ -83,7 +112,7 @@ Phase 12 adds explicit npm workspaces for [`@arnilo/prism-providers/openai`](pro
 
 Phase 6 also adds optional [`@arnilo/prism-providers/ai-sdk`](providers/ai-sdk.md), which adapts a host-owned AI SDK `LanguageModelV4` to Prism's `AIProvider`. It joins `@arnilo/prism-providers` as the seventh adapter while remaining independent from the six HTTP implementations.
 
-Provider live tests are real smoke tests gated by `PRISM_LIVE_PROVIDER_TESTS=1` plus the provider-specific API key (`OPENAI_API_KEY`, `OPENROUTER_API_KEY`, `KIMI_API_KEY`, `ZAI_API_KEY`, `NEURALWATT_API_KEY`, `OPENCODE_API_KEY`, `DEEPSEEK_API_KEY`, `XAI_API_KEY`, or `CLINE_API_KEY`). They cover text generation, tool-call loop behavior, abort/error paths where supported, and no-secret-leak assertions; they skip by default and never run in release verification. SuperGrok login is operator-only (`PRISM_LIVE_XAI_OAUTH=1`).
+Provider live tests are real smoke tests gated by `PRISM_LIVE_PROVIDER_TESTS=1` plus the provider-specific API key (`OPENAI_API_KEY`, `OPENROUTER_API_KEY`, `KIMI_API_KEY`, `ZAI_API_KEY`, `NEURALWATT_API_KEY`, `OPENCODE_API_KEY`, `DEEPSEEK_API_KEY`, `XAI_API_KEY`, `CLINE_API_KEY`, `HYPER_API_KEY`, or `COMMAND_CODE_API_KEY`). They cover text generation, tool-call loop behavior, abort/error paths where supported, and no-secret-leak assertions; they skip by default and never run in release verification. SuperGrok login is operator-only (`PRISM_LIVE_XAI_OAUTH=1`).
 
 These workspaces still follow the same rule as external packages: no provider SDK dependency, catalog fetch, env scan, keychain/file credential lookup, shell auth command, OAuth login, or live provider call runs by default. `@arnilo/prism-providers/openai` now registers OpenAI Responses and OpenAI Codex providers from caller-supplied credentials only, with optional `models`/`codexModels` overrides and an opt-in `listOpenAIModels()` helper for official `GET /models` discovery. `@arnilo/prism-providers/opencode-go` now registers docs-verified OpenCode Go open coding models with dual OpenAI/Anthropic routes (`compat.route`), official default base `https://opencode.ai/zen/go/v1`, `reasoning_content`/thinking preserve, and an opt-in `listOpenCodeGoModels()` helper for official `GET /zen/go/v1/models`. `@arnilo/prism-providers/openrouter` now registers an app-controlled OpenRouter catalog with routing/`reasoning`/cache passthrough, assistant `reasoning` replay, optional top-level automatic `cache_control`, and an opt-in `listOpenRouterModels()` helper for official `GET /api/v1/models` (setup still never fetches). `@arnilo/prism-providers/zai` now registers featured GLM-5.x/4.x metadata with official `thinking`/`reasoning_effort`/`tool_stream`/`clear_thinking` mapping, Preserved Thinking `reasoning_content` replay, implicit context caching, and an opt-in `listZaiModels()` helper for OpenAI-compatible `GET /models`. `@arnilo/prism-providers/kimi` now registers Kimi Coding Anthropic-compatible behavior by default, optional callable Moonshot Open Platform Chat Completions when `includeMoonshotModels` is requested, official Coding/Open Platform featured ids, thinking/`reasoning_effort` compat mapping, and an opt-in `listKimiModels()` helper for Moonshot `GET /v1/models`. `@arnilo/prism-providers/neuralwatt` now registers static featured model metadata with NeuralWatt reasoning_effort/thinking_token_budget/chat_template_kwargs request mapping, SSE comment tolerance, an opt-in `listNeuralWattModels()` helper for explicit `/v1/models` discovery, `getNeuralWattQuota()` for on-demand account balance/usage/energy, `neuralWattEventsWithTelemetry()`/`mapNeuralWattTelemetry()` for `: energy`/`: cost` telemetry, and `classifyNeuralWattError()` for retry classification. None of these helpers run during package setup or generation. `@arnilo/prism-providers/deepseek` registers featured `deepseek-v4-flash` / `deepseek-v4-pro` with official `thinking` / `reasoning_effort`, tool-turn `reasoning_content` replay, implicit prefix cache, and caller-gated `listDeepSeekModels`. `@arnilo/prism-providers/xai` registers featured Completions (`grok-4.6` / `grok-4.3` / `grok-build-0.1`), `x-grok-conv-id`, `reasoning_content` replay, caller-gated `listXaiModels`, and host-invoked SuperGrok device-code OAuth against `auth.x.ai`. `@arnilo/prism-providers/clinepass` registers a static `cline-pass/*` catalog, stream-only Chat Completions, per-model `reasoning_effort` maps, and `api_key` only (no WorkOS, no `listClinePassModels`). `@arnilo/prism-providers/anthropic` registers native Anthropic Messages (`createAnthropicProviderPackage` / `listAnthropicModels`). `@arnilo/prism-providers/google` registers native Gemini `generateContent` streaming (`createGoogleProviderPackage` / `listGoogleModels`; Vertex identity stays in the separate package). Both follow the same zero-setup-network / host-owned credential / provider-owned-header rules; see [`docs/providers/anthropic.md`](providers/anthropic.md) and [`docs/providers/google.md`](providers/google.md).
 
@@ -94,13 +123,15 @@ Every package remains explicit, setup-zero-fetch, and late-credential-bound. `Mo
 | Package | Protocol / model source | Content mapping | Stream, tools, and reasoning | Cache / canary |
 | --- | --- | --- | --- | --- |
 | OpenAI | Responses; featured or caller-gated `listOpenAIModels` | text, image, audio, file, document | Host and provider-hosted tools; 8-hop continuation; Realtime seam; Responses reasoning | `openai_key`; checked-in standard smoke + protected hosted/Realtime probe |
-| AI SDK | Host `LanguageModelV4`; no Prism catalog | declared text/image/audio/file/document prompt parts (role-limited) | v4 mapping; provider-executed tool authority; host-owned reasoning | host-owned; exact 4.0.4 matrix (`4.0.3` also listed); protected host integration |
+| AI SDK | Host `LanguageModelV4`; no Prism catalog | declared text/image/audio/file/document prompt parts (role-limited) | v4 mapping; provider-executed tool authority; host-owned reasoning | host-owned; exact 4.0.10 matrix (`4.0.3` and `4.0.4` also listed); protected host integration |
 | Anthropic | Messages; caller-gated list | text, image, PDF document/file | tool deltas, thinking | `cache_control`; protected API-key smoke |
 | Google | Gemini `generateContent`; caller-gated list | text, image, audio, document/file | complete tool calls, thinking | no Prism cache marker; protected API-key smoke |
 | Kimi | Coding Messages or opt-in Moonshot; caller-gated list | text, image, PDF document/file by route/model | tool deltas, route-native thinking replay | implicit / optional Anthropic markers; protected API-key smoke |
 | Z.AI | OpenAI-compatible; caller-gated list | text, image | tool deltas, `reasoning_content` | implicit; protected API-key smoke |
 | OpenRouter | OpenAI-compatible; host catalog + caller-gated list | text, image | tool deltas, reasoning replay/routing metadata | `cache_control`; protected API-key smoke |
 | OpenCode Go | OpenAI or Anthropic route; caller-gated list | text/image OpenAI route; PDF document/file Anthropic route | tool deltas, route-native thinking | route-specific; protected API-key smoke |
+| Hyper | OpenAI, Anthropic, or explicit-pass-through Responses route (`compat.route: "responses"` reuses the shared OpenAI Responses machinery); caller-gated list | text, image | tool deltas, route-native thinking, `reasoning_effort` | route-specific implicit / `cache_control`; protected API-key smoke |
+| Command Code | OpenAI or Anthropic route; caller-gated list | text, image | tool deltas, route-native thinking | route-specific implicit / `cache_control`; protected API-key smoke |
 | Alibaba | DashScope OpenAI-compatible; caller-gated list | text, image | tool deltas, Qwen thinking | implicit / optional markers; protected host probe |
 | Ollama | Cloud/local OpenAI-compatible; caller-gated list | text, image | tool deltas, reasoning effort | implicit only; protected host/daemon probe |
 | NeuralWatt | OpenAI-compatible; caller-gated list | text, image | tool deltas, reasoning and telemetry | implicit; protected API-key smoke |
@@ -119,6 +150,8 @@ Every first-party provider package hardens prompt-cache behavior so it cannot em
 - **OpenAI-compatible core adapter**: Chat Completions sends no `prompt_cache_key`/`prompt_cache_retention`/`cache_control` fields; endpoints cache implicitly. `prompt_tokens_details.cached_tokens` maps to `Usage.cacheReadTokens`.
 - **OpenRouter** (`kind: cache_control`): `session_id`/`x-session-id` sanitized and clamped to 256 chars; with no breakpoints, emits top-level automatic `cache_control: { type: ephemeral }`; with breakpoints, markers applied only to caller-selected locations (not every block); `cacheRetention: long` adds `ttl: 1h` when allowed. Preserves `cached_tokens`/`cache_write_tokens`.
 - **OpenCode Go**: default base `https://opencode.ai/zen/go/v1`; `x-opencode-session` from `cacheKey ?? sessionId` sanitized to 128 chars; Anthropic route (MiniMax/Qwen) applies `cache_control` only to selected breakpoints (`long` → `ttl: 1h`); OpenAI route (Grok/GLM/Kimi/MiMo/DeepSeek) sends none and preserves `reasoning_content`. Per-route usage mapping. Caller-gated `listOpenCodeGoModels`.
+- **Hyper** (`kind: implicit` chat route / `cache_control` messages route): `qwen3.6-*` models default to the Anthropic route with `cache_control` markers applied only to selected breakpoints (max 4; **no `ttl`** — undocumented). DeepSeek/Kimi/GLM/Gemma/etc. stay on the chat route with implicit prefix caching; `prompt_tokens_details.cached_tokens`/`cache_write_tokens` map to cache usage. Third route: `compat.route: "responses"` opts into the Codex-style `/v1/responses` OpenAI-standard pass-through, reusing the OpenAI package's Responses machinery wholesale (stream/usage/continuation/media; errors labeled `Hyper …`); cache hints surface as OpenAI-standard `prompt_cache_key` there, never retention/options. Hypercredits: `parseHyperUsageCost` surfaces USD/cost/remaining from the usage chunk. Caller-gated `listHyperModels`, operator-gated `getHyperCredits`. Billing caveat: `402 billing_error` when Hypercredits run out.
+- **Command Code** (`kind: implicit` chat route / `cache_control` messages route): `claude-*` tiers default to the Anthropic route with `cache_control` markers only on selected breakpoints (max 4; **no `ttl`** — undocumented); GPT-5.6/OSS models stay `implicit` with docs cache-write prices recorded in `cost.cacheWrite` (explicit `prompt_cache_key` upgrade pending live-probe verification). `prompt_cache_hit_tokens` chat-route and `cache_read_input_tokens`/`cache_creation_input_tokens` messages-route map to cache usage. ZDR opt-in (`zdr: true` → `x-cmd-zdr: 1`) may route to costlier upstreams or fail `422 cmd_zdr_no_providers`. Billing caveats: OSS models bill at the mean per-provider price; DeepSeek off-peak 17h/day, peak 2×; deals auto-applied. Caller-gated `listCommandCodeModels`.
 - **Z.AI** (`kind: implicit`): GLM context caching is automatic; no explicit cache payload sent regardless of cache options. `prompt_tokens_details.cached_tokens`/`cache_write_tokens` map to cache usage.
 - **NeuralWatt** (`kind: implicit`): NeuralWatt prefix caching is automatic; sends no explicit cache payload regardless of cache options. `cacheRetention: "none"` disables Prism cache-control hints only (not the implicit backend prefix cache). `prompt_tokens_details.cached_tokens` maps to `Usage.cacheReadTokens`; NeuralWatt does not report a cache-write token so `Usage.cacheWriteTokens` is never fabricated.
 - **Kimi**: default catalog models use implicit caching (no `cache_control`); hosts opt in via `ModelConfig.cache.kind: cache_control` on the Anthropic `/messages` route, then markers apply only to selected breakpoints (`long` → `ttl: 1h`); the Moonshot OpenAI route sends none. `cache_read_input_tokens`/`cache_creation_input_tokens` map to cache usage.
@@ -258,10 +291,10 @@ Provider package manifest contribution and the generic request options a provide
 
 ## Implementation example
 
-Wire a provider package with model metadata plus a session cache policy through the extension kernel:
+Wire a provider package with model metadata through the extension kernel. Session correlation and cache defaults are kernel-constructed — do not register `createSessionCachePolicy` for request success:
 
 ```ts
-import { createExtensionKernel, defineProviderPackage, createSessionCachePolicy } from "@arnilo/prism";
+import { createExtensionKernel, defineProviderPackage } from "@arnilo/prism";
 
 const pkg = defineProviderPackage({
   name: "demo-provider",
@@ -276,7 +309,6 @@ const pkg = defineProviderPackage({
       cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, currency: "USD" },
       compat: { vendorSpecific: true },
     });
-    api.registerProviderRequestPolicy(createSessionCachePolicy({ retention: "short" }));
   },
 });
 
@@ -286,13 +318,13 @@ await kernel.load([pkg]);
 
 ## Extension and configuration notes
 
-- Hosts decide which credential resolvers, env objects, OAuth stores, request
-  policies, and prompt contributions become active; the package only *declares*
-  them.
-- `createSessionCachePolicy()` acts as a concrete cache policy hook
-  (`provider_request`) that sets generic `ProviderRequest.options`
+- Hosts own credentials, env objects, OAuth stores, extra headers, custom `cacheKey`,
+  `compat`/`extra`, and which prompt contributions become active; the package only *declares*
+  them. Prism constructs session/cache/thinking options for owned generate sites.
+- `createSessionCachePolicy()` is an optional host overlay (`provider_request` cache policy hook)
+  that sets generic `ProviderRequest.options`
   (`sessionId`, `cacheKey`, `cacheRetention`, `headers`, opaque `extra`) before
-  `AIProvider.generate()`; provider adapters map those options to provider payloads.
+  `AIProvider.generate()`; provider adapters map those options to provider payloads. Not required for request success.
 - `ModelConfig.cache` is the generic cache capability metadata documented in [Model registry](model-registry.md); `ModelConfig.compat` remains provider-owned inert JSON for behavior that has no generic field yet.
 - `ModelConfig.compat` is provider-owned inert JSON: cache policy overrides,
   reasoning/thinking formats, and provider-specific usage mapping live there
@@ -310,7 +342,7 @@ 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.
+- For allow-list/residency/budget/circuit selection before resolve, use optional `@arnilo/prism-core/governance/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

package/docs/provider-primitives.md

@@ -251,7 +251,7 @@ export interface ProviderTurnMetadata {
 // - provider_turn_finished { sessionId, runId, turn, metadata, usage?, error? }
 ```
 
-Optional package `@arnilo/prism-observability-opentelemetry` subscribes via middleware + agent events. **Default:** content redacted/absent; high-cardinality IDs are span attributes, not metric labels. NeuralWatt `neuralwatt:telemetry` events remain package-local; the adapter may forward numeric energy/cost fields.
+Optional package `@arnilo/prism-core/governance/observability` subscribes via middleware + agent events. **Default:** content redacted/absent; high-cardinality IDs are span attributes, not metric labels. NeuralWatt `neuralwatt:telemetry` events remain package-local; the adapter may forward numeric energy/cost fields.
 
 ## Migration conformance fixtures
 

package/docs/provider-request-policies.md

@@ -6,15 +6,17 @@ Provider request policies are small host/package hooks that can adjust `Provider
 
 Public helpers:
 
+- `applyDefaultProviderRequestOptions(request, { sessionId, thinkingLevel })` is the kernel constructor. Fill-if-missing `sessionId` / `cacheKey`; default cache breakpoints + `cacheRetention: "short"` when `model.cache.kind` is `cache_control` or `explicitBreakpoints` is true; optional `thinkingLevel` patches via `applyThinkingLevelForModel` after those fills. Host values win. Agent sessions, observational-memory workers, and LLM compaction already call it.
+- `ProviderRequirementError` (`ERR_PRISM_PROVIDER_REQUIREMENT`) is the fail-fast typed error adapters throw when a mandatory option is still missing (OpenCode Go `sessionId` → `x-opencode-session`). Thrown before fetch; messages contain no request bodies or secrets.
 - `createProviderRequestPolicyChain(policies)` runs policies in order.
-- `createSessionCachePolicy(options)` sets legacy `cacheKey` / `cacheRetention` aliases from `sessionId`.
+- `createSessionCachePolicy(options)` is a host overlay that sets legacy `cacheKey` / `cacheRetention` aliases from `sessionId`. Not required for request success.
 - `mergeProviderRequestOptions(base, patch)` merges request options, including structured `cache` hints.
 
 ## When to use it
 
-Use provider request policies when an app or provider package needs to set generic per-request options such as cache hints, caller-owned headers, `compat`, or `extra` without changing every provider call site.
+Use `createAgent({ thinkingLevel })` / `session.run(input, { thinkingLevel })` for session intent. Use `applyDefaultProviderRequestOptions` on custom `provider.generate` sites. Use provider request policies only as overlays (custom `cacheKey`, extra headers, `compat`/`extra`) — never to make a request valid.
 
-Do not use request policies to resolve credentials, read env vars, perform OAuth refresh, fetch model lists, or override provider-owned auth/session/security headers.
+Do not use request policies to resolve credentials, read env vars, perform OAuth refresh, fetch model lists, or override provider-owned auth/session/security headers. Session and cache keys are correlation ids, never secrets.
 
 ## Inputs / request
 
@@ -24,9 +26,11 @@ import type { ProviderRequestPolicy, ProviderRequestPolicyContext, ProviderReque
 
 | API | Input | Purpose |
 | --- | --- | --- |
+| `applyDefaultProviderRequestOptions(request, ctx)` | `{ sessionId?, thinkingLevel? }` | Fill-if-missing `sessionId` / `cacheKey`; cache defaults from `model.cache`; thinking patch. |
+| `ProviderRequirementError` | `message`, `{ requirement, providerId? }` | Typed missing-requirement error. |
 | `ProviderRequestPolicy.apply(context)` | `{ sessionId?, request, options? }` | Returns a patched request or options. |
 | `createProviderRequestPolicyChain(policies)` | ordered policies | Applies patches in order. |
-| `createSessionCachePolicy({ retention?, cacheKey? })` | optional cache defaults | Sets legacy aliases. |
+| `createSessionCachePolicy({ retention?, cacheKey? })` | optional cache overlay | Sets legacy aliases after kernel defaults. |
 | `mergeProviderRequestOptions(base, patch)` | two option bags | Shallow merges scalars and structurally merges `cache`. |
 
 `mergeProviderRequestOptions()` behavior:
@@ -62,12 +66,21 @@ No agent events are emitted by the policy chain itself.
 
 ```ts
 import {
+  applyDefaultProviderRequestOptions,
   createProviderRequestPolicyChain,
   createSessionCachePolicy,
   mergeProviderRequestOptions,
+  ProviderRequirementError,
   type ProviderRequestPolicy,
 } from "@arnilo/prism";
 
+const stamped = applyDefaultProviderRequestOptions(request, {
+  sessionId: session.id,
+  thinkingLevel: "low",
+});
+// stamped.options.sessionId === request.options?.sessionId ?? session.id
+// cache_control models also get default cache.breakpoints unless the host set mode/off / retention/none / explicit breakpoints
+
 const structuredCache: ProviderRequestPolicy = {
   name: "demo.structured-cache",
   apply({ request }) {
@@ -93,7 +106,7 @@ const chain = createProviderRequestPolicyChain([
 
 ## Extension and configuration notes
 
-Provider packages can register request policies during `defineProviderPackage().setup(api)`. Hosts decide which packages/policies load and in which order. Prism has no hidden provider request policy registry and no automatic provider-specific cache behavior in core.
+Provider packages can register request policies during `defineProviderPackage().setup(api)`. Hosts decide which overlay policies load and in which order. Prism has no hidden provider request policy registry. Kernel construction (`applyDefaultProviderRequestOptions`) already fills session/cache/thinking from `model.cache` and run intent — package-registered policies are never auto-activated and never required for success.
 
 Policy output should stay generic: use `ProviderRequestOptions.cache`, `headers`, `compat`, and `extra` instead of provider-name branches in core.
 
@@ -104,7 +117,7 @@ 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.
+- Optional `@arnilo/prism-core/governance/model-router` returns a `ProviderRequestPolicy` that strips `openRouterRouting` unless governance allows it — chain it with other policies.
 
 ## Related APIs
 

package/docs/providers/ai-sdk.md

@@ -12,6 +12,7 @@ Core `@arnilo/prism` does not depend on the AI SDK.
 | --- | --- | --- |
 | `4.0.3` | `LanguageModelV4`, `specificationVersion: "v4"` | Supported and offline-tested |
 | `4.0.4` | `LanguageModelV4`, `specificationVersion: "v4"` | Supported and offline-tested |
+| `4.0.10` | `LanguageModelV4`, `specificationVersion: "v4"` | Current peer; supported and offline-tested |
 
 The peer dependency is intentionally exact. `createAiSdkProvider()` reads its resolved `@ai-sdk/provider/package.json` version during setup and throws typed `AiSdkProviderError { code: "unsupported_version" }` for an unlisted version; it does not infer compatibility from a matching `"v4"` string.
 
@@ -131,7 +132,7 @@ See [Provider caching](../provider-caching.md) for the cross-provider matrix.
 
 ## Thinking and reasoning
 
-Reasoning effort, budgets, and provider-specific thinking controls are **host-model-owned**. Prism does not map `ThinkingLevel` into AI SDK call options (`thinkingFamilyForModel` → `noop`). Hosts configure reasoning on the AI SDK model (for example OpenAI `reasoning.effort` via AI SDK `providerOptions`) and may pass per-turn overrides through `ProviderRequestOptions.compat` / `extra`, which the adapter forwards as `providerOptions.prism`.
+Reasoning effort, budgets, and provider-specific thinking controls are **host-model-owned**. Prism does not map `ThinkingLevel` into AI SDK call options: the deliberate `noop` compat family (stamped `compat.thinkingFamily: "noop"` on AI SDK models, and the `thinkingFamilyForModel` fallback) leaves the request options unchanged. Hosts configure reasoning on the AI SDK model (for example OpenAI `reasoning.effort` via AI SDK `providerOptions`) and may pass per-turn overrides through `ProviderRequestOptions.compat` / `extra`, which the adapter forwards as `providerOptions.prism`.
 
 Stream mapping:
 
@@ -144,11 +145,23 @@ Official evidence: [Custom providers / LanguageModelV4](https://ai-sdk.dev/provi
 
 ## Extension and configuration notes
 
-- Peer dependency: `@ai-sdk/provider@4.0.4` (matrix also lists `4.0.3`). Upgrade policy adds a matrix row and offline conformance fixture before accepting any new version.
-- First-party HTTP providers remain independent; this adapter is available directly, through `@arnilo/prism-providers`, or through `@arnilo/prism-all`. Installation does not select a model or invoke AI SDK.
+- Peer dependency: `@ai-sdk/provider@4.0.10` (matrix also lists `4.0.3` and `4.0.4`). Upgrade policy adds a matrix row and offline conformance fixture before accepting any new version.
+- First-party HTTP providers remain independent; this adapter is available directly or through `@arnilo/prism-providers`. Installation does not select a model or invoke AI SDK.
 - `options.compat` / `options.extra` pass through as AI SDK `providerOptions.prism`.
 - Export helpers `toAiSdkCallOptions`, `toAiSdkPrompt`, and `mapAiSdkStream` for tests and custom hosts.
 
+## Request construction (0.5.1)
+
+Agent sessions stamp `sessionId`/`cacheKey` without a host policy. Session/cache keys are correlation ids, never secrets.
+
+| | |
+| --- | --- |
+| P1 session wire | none |
+| Mandatory | no |
+| P2 default cache | host-owned, no Prism cache fields |
+
+See [Provider request policies](../provider-request-policies.md).
+
 ## Security and performance notes
 
 - Host credentials stay inside the supplied AI SDK model. The adapter never reads env keys or credential stores.
@@ -157,6 +170,17 @@ Official evidence: [Custom providers / LanguageModelV4](https://ai-sdk.dev/provi
 - Unsupported content and stream parts fail closed before/at mapping; `structuredOutput.strict` is rejected because V4 cannot carry it.
 - Pass `redactor` for direct use; agent runs apply their active redactor. Provider metadata/warnings never become prompt, tool, event, or telemetry content.
 
+## Live probe
+
+Runs the adapter over the real `@ai-sdk/openai` provider package (dev dependency) to prove the `LanguageModelV4` mapping on a genuine AI SDK wire:
+
+```bash
+PRISM_LIVE_PROVIDER_TESTS=1 OPENAI_API_KEY=... \
+  node --test packages/prism-providers/dist/ai-sdk/__tests__/live.test.js
+```
+
+`PRISM_LIVE_AISDK_MODEL` overrides the probed model (default `gpt-5.1`). Without a key the suite skips.
+
 ## Related APIs
 
 - [Provider packages](../provider-packages.md)

package/docs/providers/alibaba.md

@@ -157,7 +157,7 @@ reranker. The verified compatible route is workspace-dedicated only:
 (`qwen3-rerank`, ≤500 documents, 4,000 tokens/item; base path `compatible-api/v1`,
 not `compatible-mode/v1`). A future `createAlibabaReranker` over that route is
 demand-gated: implement when a caller supplies a workspace-dedicated `baseUrl` and
-needs rerank (structural `Reranker` shape from `@arnilo/prism-rag`, no new
+needs rerank (structural `Reranker` shape from `@arnilo/prism-memory/rag`, no new
 dependency). Multimodal rerank (`qwen3-vl-rerank`) is native-only and stays out.
 
 ## Outputs / response / events
@@ -245,6 +245,18 @@ await kernel.load([
 - Usage accounting: `cached_tokens` → `Usage.cacheReadTokens`,
   `cache_creation_input_tokens` → `Usage.cacheWriteTokens`.
 
+## Request construction (0.5.1)
+
+Agent sessions stamp `sessionId`/`cacheKey` without a host policy. Session/cache keys are correlation ids, never secrets.
+
+| | |
+| --- | --- |
+| P1 session wire | none |
+| Mandatory | no |
+| P2 default cache | only if `model.cache.kind === "cache_control"` |
+
+See [Provider request policies](../provider-request-policies.md).
+
 ## Security and performance notes
 
 - SSE streams and HTTP error bodies use bounded `@arnilo/prism/providers/transport`
@@ -264,6 +276,10 @@ await kernel.load([
 - Model discovery is caller-gated and never invoked in the provider hot path.
 - Live tests stay opt-in; default tests are network-free.
 
+## Thinking and reasoning
+
+Qwen hybrid models route through the `thinking_type` family: `none` maps to `enable_thinking: false`, any other declared level to `true` — there are no effort levels upstream, so declared `capabilities.thinkingLevels` for hybrid models are the on/off set (`none`–`max` used as a toggle vocabulary). Thinking-only models (`qwq*`, `*-thinking`) always think and never receive `enable_thinking: false`; `thinking_budget` stays a package-local passthrough. See [Thinking and reasoning](../thinking-and-reasoning.md).
+
 ## Related APIs
 
 - [Provider packages](../provider-packages.md): `defineProviderPackage`,

package/docs/providers/anthropic.md

@@ -77,6 +77,18 @@ api.registerProviderPackage(createAnthropicProviderPackage({ apiKey: hostKey, mo
 - 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.
 
+## Request construction (0.5.1)
+
+Agent sessions stamp `sessionId`/`cacheKey` without a host policy. Session/cache keys are correlation ids, never secrets.
+
+| | |
+| --- | --- |
+| P1 session wire | `x-client-request-id` from `sessionId` |
+| Mandatory | no |
+| P2 default cache | `cache_control` on `system_prompt` + `last_stable_message`; `cacheRetention: "short"` |
+
+See [Provider request policies](../provider-request-policies.md).
+
 ## Security and performance notes
 
 - No network during import/setup/default tests; credentials host-owned and late-bound.
@@ -84,6 +96,10 @@ api.registerProviderPackage(createAnthropicProviderPackage({ apiKey: hostKey, mo
 - Media/SSRF bounds reuse `@arnilo/prism/providers/media` / transport helpers.
 - Offline conformance: `@arnilo/prism/testing/provider-conformance`.
 
+## Thinking and reasoning
+
+Anthropic models route through the `output_config_effort` family: the adapter merges `compat.output_config.effort` (from `applyThinkingLevelForModel`) and the provider emits `output_config: { effort }` on Messages bodies. Declared levels per generation (from `capabilities.thinkingLevels`): Opus 4.8/4.7, Sonnet 5, Fable/Mythos 5, Opus 5 accept `low`–`max` incl. `xhigh`; Mythos Preview, Opus 4.6, Sonnet 4.6 accept `low/medium/high/max`; Opus 4.5 accepts `low/medium/high`; Haiku 4.5 declares `none`–`high` (upstream effort support undocumented — live-probe pending). Undeclared levels snap to the nearest declared level (ladder distance, ties up); values below the minimum snap up. Thinking type: `adaptive` on 4.6+/Sonnet 5/Fable/Mythos (bare `enabled` maps to `adaptive`); legacy 4.5 models get `enabled` plus a `budget_tokens` default of 10000 when absent. See [Thinking and reasoning](../thinking-and-reasoning.md).
+
 ## Related APIs
 
 - [Provider packages](../provider-packages.md): package setup + discovery contract.

package/docs/providers/azure.md

@@ -56,7 +56,19 @@ Opt-in live canaries: inject real `fetch` + host credential behind host CI secre
 
 ## Extension and configuration notes
 
-Register via `createExtensionKernel().load([createAzureOpenAIProviderPackage(...)])`. Pair with `@arnilo/prism-model-router` for residency allow-lists on Azure regions/endpoints.
+Register via `createExtensionKernel().load([createAzureOpenAIProviderPackage(...)])`. Pair with `@arnilo/prism-core/governance/model-router` for residency allow-lists on Azure regions/endpoints.
+
+## Request construction (0.5.1)
+
+Agent sessions stamp `sessionId`/`cacheKey` without a host policy. Session/cache keys are correlation ids, never secrets.
+
+| | |
+| --- | --- |
+| P1 session wire | none |
+| Mandatory | no |
+| P2 default cache | host-owned, no Prism cache fields |
+
+See [Provider request policies](../provider-request-policies.md).
 
 ## Security and performance notes
 
@@ -66,6 +78,22 @@ Register via `createExtensionKernel().load([createAzureOpenAIProviderPackage(...
 - No Azure SDK dependency.
 - Conformance-proven (Task 6): package `setup()` performs zero fetch and zero credential resolution; an already-aborted signal fails fast; a truncated SSE stream (no `data: [DONE]`) ends in an `error` event; Azure cache policy stays host-owned, so no cache wire fields (`cache_control`, `prompt_cache_*`) are emitted even when the request carries Prism cache hints — only upstream-reported `prompt_tokens_details.cached_tokens` maps to `Usage.cacheReadTokens`.
 
+## Live probe
+
+Opt-in smoke over your real Azure OpenAI resource:
+
+```bash
+PRISM_LIVE_PROVIDER_TESTS=1 AZURE_OPENAI_ENDPOINT=https://<resource>.openai.azure.com \
+  AZURE_OPENAI_API_KEY=... PRISM_LIVE_AZURE_MODEL=<deployment-name> \
+  node --test packages/prism-providers/dist/azure/__tests__/live.test.js
+```
+
+The deployment name is the model knob (`AZURE_OPENAI_DEPLOYMENT` also works). Without any of these variables the suite skips — it never fails.
+
+## Thinking and reasoning
+
+Azure OpenAI deployments use the OpenAI-compatible wire: the provider forwards sanitized thinking compat (`reasoning_effort` with `effort`/`reasoningEffort` aliases, or a `reasoning` object with `effort` + preserved `summary`) via its body builder, snapping effort to the model's declared levels (gpt-5.1 → `none/low/medium/high`, ties up). Unrecognized compat keys are dropped. See [Thinking and reasoning](../thinking-and-reasoning.md).
+
 ## Related APIs
 
 - [OpenAI-compatible provider](openai-compatible.md)