@arnilo/prism 0.0.5 → 0.0.6

package/docs/review-coverage-2026-07-17-provider-validation.md

@@ -0,0 +1,192 @@
+# Review coverage — 2026-07-17 provider validation
+
+Working evidence page for Plan 067. Freezes the 2026-07-14 P0–P2 re-verification map, first-party provider validation owners, official-doc priority URLs, Pi secondary references, cache/thinking/discovery surfaces, credential notes, and use-case model-binding inventory.
+
+**Evidence frozen:** 2026-07-17 (offline inventory; no live provider calls).
+**Priority rule:** official provider documentation wins; Pi (`badlogic/pi-mono`) is secondary when official docs are silent or ambiguous.
+
+Related: [2026-07-14 coverage](review-coverage-2026-07-14.md) (0.0.4), [2026-07-15 coverage](review-coverage-2026-07-15.md) (0.0.5), [provider caching](provider-caching.md), [provider packages](provider-packages.md).
+
+## Status legend
+
+| Status | Meaning |
+| --- | --- |
+| `verify` | Prior plan marked fixed; Plan 067 must re-verify with regression tests. |
+| `gap` | Known missing or incorrect behavior/docs relative to official sources. |
+| `fixed` | Closed in this plan (updated as tasks complete). |
+| `by-design` | Intentional absence (document; do not “fix” into a catalog). |
+
+## P0–P2 finding → Plan 067 owner matrix
+
+Source: `code-reviews/2026-07-14.md`. Prior Plans 053 / 054 / 058 marked these implemented for 0.0.4; this plan re-verifies rather than skipping.
+
+| Review ID | Priority | Finding | 0.0.4 owner | Plan 067 task | Current status | Credential / redaction notes |
+| --- | --- | --- | --- | --- | --- | --- |
+| R-001 | P0 | Revision request duplicated + corrupted by redaction | 053-1 | 1 | fixed | Secret canaries must not appear in repair requests, events, or redacted graphs. Re-verified 2026-07-17: `pendingHistory` + active-path redaction; revision+redactor suite asserts one repair and no `[Circular]`. |
+| R-002 | P1 | Multi-round tool transcript chronologically invalid | 053-2 | 1 | fixed | N/A. Re-verified 2026-07-17: two rounds × two calls keep `user → assistant → tool → tool → …` order in history and assembled request. |
+| R-003 | P1 | Redactor leaks secrets in object/Map keys | 053-1 | 1 | fixed | Object/Map string keys redact; collisions use deterministic `__N` suffixes. |
+| R-004 | P1 | Event-ledger writes lack backpressure | 053-3 | 1 | fixed | Ledger appends serialized (concurrency 1), order preserved, append failures reject run completion. |
+| R-008 | P1 | Unbounded SSE / error bodies; multiline `data:` | 054-1/2 | 2 | fixed | Bounded readers; error text redacted. |
+| R-009 | P1 | OpenAI device-code OAuth does not poll | 054-3 | 2 | fixed | Redact device/user/access/refresh codes from OAuth errors. |
+| R-010 | P2 | Duplicated provider protocol utilities | 054-1/2 | 2 | fixed | Shared transport/primitives remain authoritative. |
+| R-005 | P2 | JSONL append silent on corrupt lines | 053-4 | 2 | fixed | Dev-only store; fail closed on corrupt lines. |
+| R-011 | P2 | Coding-agent image read unbounded / resize no-op | 055-5 | 2 | fixed | Enforce `maxImageBytes`; deprecate `autoResizeImages` honestly. |
+| R-006 | P2 | Optional config ENOENT detected by message text | 053-5 | 2 | fixed | Typed `code === "ENOENT"`. |
+| R-012 | P2 | Release tag/version mismatch; no provenance | 058-7/9 | 2 | fixed | Tag/version gate + `--provenance`; no secrets in artifacts. |
+
+Bug-report fixes A–D remain covered by R-001 / R-003 / R-007 (malformed message shape was Plan 053; re-check under Task 1 if touched).
+
+## Provider package validation matrix
+
+| Package | Plan 067 task | Official cache | Prism `cache.kind` | Thinking / reasoning (official → Prism) | Discovery endpoint | Static catalog (bootstrap only) | Pi secondary ref | Credential surface | Status |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| `@arnilo/prism-provider-openai` | 6 | `prompt_cache_key`; older models `prompt_cache_retention` (`24h` / `in_memory`); GPT-5.6+ `prompt_cache_options` / breakpoints tracked (host may pass via compat/extra; discovery sets `longRetention: false`) | `openai_key` (+ `longRetention`, `maxKeyLength`) | Official: Responses top-level `reasoning.effort` (+ `summary`). Prism: merges `model.compat.reasoning` + `options.compat.reasoning` (request wins); `applyThinkingLevel(..., "openai_reasoning")` | Official: `GET /models` | Featured `openAIModels` / `openAICodexModels` + **`listOpenAIModels`**; factory accepts `models?` / `codexModels?` | `packages/ai/src/api/openai-responses.ts`, `openai-responses-shared.ts` | API key; Codex OAuth device-code (`oauth.ts`) — poll + redact codes | **fixed** 2026-07-17: Responses P0s + discovery + reasoning + models override |
+| `@arnilo/prism-provider-kimi` | 7 | Anthropic-style `cache_control` on `/messages` when supported; OpenAI Moonshot route none | default implicit; opt-in `cache_control` | Official K2.x: `thinking.type` (`enabled`/`disabled`/`keep`); K2.7-code always enabled; K3: top-level `reasoning_effort`. Prism: `kimiThinking`/`kimiReasoningEffort`/`kimiPreserveThinking` (request wins); Coding Anthropic + Moonshot Chat Completions both callable | Official: `GET https://api.moonshot.ai/v1/models` (also `.cn`); Coding has no public list API | Featured Coding (`kimi-for-coding`, `kimi-for-coding-highspeed`, `k3`) + Moonshot (`kimi-k2.7-code`, `kimi-k3`) + **`listKimiModels`** | `kimi-coding*.ts`, `moonshotai*.ts`, `api/anthropic-messages.ts` | API key (`KIMI` / Moonshot, not interchangeable); redacted from errors | **fixed** 2026-07-17: discovery + Moonshot provider + thinking + official Coding ids |
+| `@arnilo/prism-provider-zai` | 8 | Implicit (no client `cache_control` / `prompt_cache_key`); official `usage.prompt_tokens_details.cached_tokens` | `implicit` | Official: `thinking` (`{type, clear_thinking?}`), `reasoning_effort` (GLM-5.2+), `tool_stream` (GLM-4.6+). Prism: `zaiThinking`/`zaiReasoningEffort`/`zaiToolStream`/`zaiClearThinking`/`zaiPreserveThinking` (request wins); Preserved Thinking replays `reasoning_content`. Obsolete `thinkingFormat`/`developerRoleFallback` docs removed | No first-class docs.z.ai list page; OpenAI-compatible `GET {baseUrl}/models` best-effort + curated featured set from Chat Completions enum / overview | Featured `zaiModels` (`glm-5.2`…`glm-4.5`) + **`listZaiModels`**; default base `https://api.z.ai/api/paas/v4` | `zai.ts`, `zai.models.ts` (Pi secondary ids only) | API key; redacted from errors / discovery | **fixed** 2026-07-17: docs drift closed; catalog + discovery + clear_thinking/preserve |
+| `@arnilo/prism-provider-openrouter` | 9 | Official prompt caching via `cache_control` + sticky `session_id` routing; top-level automatic when no breakpoints | `cache_control` (legacy `compat.openRouterCache`) | Official: `reasoning: { effort | max_tokens }`. Prism: `resolveOpenRouterReasoning` merge + `preserveThinking` replay as body `reasoning` | Official: `GET https://openrouter.ai/api/v1/models` | **App-controlled** `models:` + optional **`listOpenRouterModels`** (no bundled mega-catalog) | `openrouter.models.ts` (do not vendor), `api/openai-completions.ts` | API key; sanitize session/cache ids | **fixed** 2026-07-17: discovery + reasoning merge/preserve + automatic top-level cache_control |
+| `@arnilo/prism-provider-opencode-go` | 10 | Anthropic route: selected `cache_control`; OpenAI route: none; `x-opencode-session` from cache/session key | route-specific (`cache_control` on Anthropic; `implicit` on OpenAI) | Dual-route: Anthropic thinking blocks + OpenAI `reasoning_content`; upstream `thinking`/`reasoning_effort`/`reasoning` passthrough (request wins); `preserveThinking` default for reasoning models | Official `GET https://opencode.ai/zen/go/v1/models` (sparse) | Featured official Go ids (Grok/GLM/Kimi/MiMo/MiniMax/Qwen/DeepSeek) + **`listOpenCodeGoModels`**; default base `https://opencode.ai/zen/go/v1` | `opencode-go.ts`, `opencode-go.models.ts` (Pi secondary ids/limits only) | API key; redacted from errors / discovery | **fixed** 2026-07-18: catalog + discovery + base URL + thinking preserve |
+| `@arnilo/prism-provider-neuralwatt` | 11 | Implicit vLLM prefix caching; `prompt_tokens_details.cached_tokens` | `implicit` | Official: `reasoning_effort` when `capabilities.reasoning_effort` (GLM-5.2 default `max`); `thinking_token_budget`; `chat_template_kwargs` (`preserve_thinking`/`clear_thinking`/`enable_thinking`). Prism: `thinking.ts` resolves owned fields + `stripNeuralWattOwnedCompat`; `applyThinkingLevel(..., "reasoning_effort")`; Preserved Thinking replays `reasoning_content` | Official: `GET https://api.neuralwatt.com/v1/models` (auth optional for public models) | Featured `neuralWattModels` (official aliases incl. `gemma-4-31b`; no guessed pricing) + **`listNeuralWattModels()`** | **No Pi NeuralWatt provider** — official docs only | Optional API key on discovery; quota helper; redact secrets in error bodies | **fixed** 2026-07-18: catalog refresh + kwargs routing + owned-compat strip |
+| `@arnilo/prism-provider-ai-sdk` | 12 | Host model owns request caching; adapter maps usage only | host-owned / N/A | Host `LanguageModelV4` owns reasoning; Prism maps stream `reasoning` parts | **None by design** (host supplies model) | None | N/A (AI SDK official spec > Pi) | No package credentials; host model may hold secrets | **fixed** 2026-07-18: host-owned catalog/cache/reasoning validated; usage mapping + docs |
+
+## Frozen official evidence sources (priority)
+
+| Provider | Frozen URLs (official) | Notes frozen 2026-07-17 |
+| --- | --- | --- |
+| OpenAI | [List models](https://developers.openai.com/api/reference/resources/models/methods/list); [Prompt caching](https://developers.openai.com/api/docs/guides/prompt-caching); [Reasoning](https://developers.openai.com/api/docs/guides/reasoning); [Responses create](https://developers.openai.com/api/reference/resources/responses/methods/create/); [Models guide](https://developers.openai.com/api/docs/models) | `GET /models`. Caching: `prompt_cache_key`; pre-5.6 `prompt_cache_retention`; 5.6+ `prompt_cache_options` / breakpoints. Reasoning: `reasoning.effort`. |
+| Kimi / Moonshot | [List models](https://platform.kimi.ai/docs/api/list-models); [API overview](https://platform.kimi.ai/docs/api/overview); [Model parameter reference](https://platform.kimi.ai/docs/api/models-overview); [Thinking mode](https://platform.kimi.ai/docs/guide/use-kimi-k2-thinking-model); [Thinking effort](https://platform.kimi.ai/docs/guide/use-thinking-effort) | `GET /v1/models` on `api.moonshot.ai` / `.cn`. K2.x `thinking`; K3 `reasoning_effort: "max"`. Anthropic `/messages` compat remains under-documented — record empirical gaps in Task 7. |
+| Z.AI | [Deep thinking](https://docs.z.ai/guides/capabilities/thinking); [Thinking mode](https://docs.z.ai/guides/capabilities/thinking-mode); [Tool streaming](https://docs.z.ai/guides/capabilities/stream-tool); [Context caching](https://docs.z.ai/guides/capabilities/cache); [Chat completion](https://docs.z.ai/api-reference/llm/chat-completion); [Migrate to GLM-5.2](https://docs.z.ai/guides/overview/migrate-to-glm-new); [Overview](https://docs.z.ai/guides/overview/overview) | Code + `docs/providers/zai.md` match official `thinking` / `reasoning_effort` / `tool_stream` / `clear_thinking`. Historical mismatch (`thinkingFormat`) closed in Task 8. |
+| OpenRouter | [Get models](https://openrouter.ai/docs/api/api-reference/models/get-models); [Prompt caching](https://openrouter.ai/docs/guides/best-practices/prompt-caching); [Reasoning tokens](https://openrouter.ai/docs/guides/best-practices/reasoning-tokens) | `GET /api/v1/models`. Cache via `cache_control` + sticky routing. Reasoning via `reasoning` object. |
+| OpenCode Go | [Go](https://opencode.ai/docs/go/); [Providers](https://opencode.ai/docs/providers/) | Dual OpenAI + Anthropic compatible APIs. Official `GET /zen/go/v1/models`. Featured: Grok 4.5, GLM-5.2/5.1, Kimi K3/K2.7 Code/K2.6, MiMo, MiniMax, Qwen3.7/3.6, DeepSeek V4. Default base `https://opencode.ai/zen/go/v1`. |
+| NeuralWatt | [Models](https://portal.neuralwatt.com/docs/api/models); [Chat completions](https://portal.neuralwatt.com/docs/api/chat-completions); [API overview](https://portal.neuralwatt.com/docs/api/overview); [Quickstart](https://portal.neuralwatt.com/docs/quickstart) | `GET /v1/models` returns pricing/capabilities/limits metadata. Prefix caching automatic; `reasoning_effort` when capability flagged. |
+| AI SDK | [Custom provider / LanguageModelV4](https://ai-sdk.dev/providers/community-providers/custom-providers); AI SDK usage types (`inputTokens` / cache details) | Adapter validates `specificationVersion`; maps cache read/write from usage. No Prism catalog. |
+
+## Frozen Pi secondary references
+
+Repo: `https://github.com/badlogic/pi-mono` (`packages/ai`).
+
+| Area | Path / note |
+| --- | --- |
+| OpenAI Responses | `packages/ai/src/providers/openai-responses.ts` (also Codex / Azure variants) |
+| OpenAI Completions | `packages/ai/src/providers/openai-completions.ts` / `api/openai-completions.ts` |
+| Anthropic Messages | `packages/ai/src/providers/anthropic-messages.ts` / `api/anthropic-messages.ts` |
+| Generated catalogs | `packages/ai/src/providers/*.models.ts` via `scripts/generate-models.ts` — **not** copied as Prism’s sole strategy |
+| Provider registry docs | Pi mintlify “LLM Providers” / README provider list |
+
+Use Pi only to fill gaps or cross-check wire shapes after official docs.
+
+## Shared discovery pattern (Task 3 decision — frozen)
+
+**Status (2026-07-17 Task 3):** pattern documented; no new core list-models primitive. Shared reuse is limited to existing transport/credential helpers.
+
+### Inventory
+
+| Primitive | Location | Role |
+| --- | --- | --- |
+| `listNeuralWattModels({ apiKey?, fetch?, baseUrl?, signal?, headers? })` | `packages/provider-neuralwatt/src/models.ts` | **Template** — only shipped `list*Models` today |
+| `mapNeuralWattModel(entry)` | same | Provider-specific entry → `ModelConfig` |
+| `neuralWattModels` featured aliases | same | Offline bootstrap; no guessed pricing |
+| `readBoundedResponseText` | `@arnilo/prism/providers/transport` | Bounded error-body read + optional secret redaction |
+| `resolveCredentialValue` / `redactSecrets` | `@arnilo/prism` | Auth resolution + error redaction |
+| Package `models?: readonly ModelConfig[]` | Kimi/Z.AI/OpenRouter/OpenCode Go/NeuralWatt/**OpenAI** factories | Host override of registered catalog |
+| OpenAI factory `models?` / `listOpenAIModels` | **done** Task 6 | Fixed |
+| OpenRouter / OpenCode Go `list*Models` | OpenRouter **`listOpenRouterModels` done** Task 9; OpenCode Go **`listOpenCodeGoModels` done** Task 10; Z.AI **`listZaiModels` done** Task 8; Kimi **`listKimiModels` done** Task 7 | Per-package work |
+| AI SDK catalog | N/A | Host-owned `LanguageModelV4` — no discovery export |
+
+### Decisions
+
+- Template options + return: NeuralWatt `listNeuralWattModels(...) → ModelConfig[]`.
+- **Never** call discovery from `create*ProviderPackage()` / extension setup.
+- Static catalogs = offline bootstrap / featured aliases only.
+- OpenRouter stays app-registration-first; **`listOpenRouterModels`** (done Task 9) feeds `models:` only.
+- AI SDK: no discovery export.
+- Prefer **package-local** helpers. Do **not** add a core model-discovery registry or OpenAI-compatible mega-mapper in Task 3. Extract a shared HTTP/list helper later only if ≥2 packages share identical parsing (unlikely: OpenRouter/NeuralWatt/OpenAI response shapes and cache/cost mapping diverge).
+- Discovery may populate `ModelConfig.cache` / `ModelConfig.cost` from live metadata when officially documented; static catalogs must not invent those fields.
+- Docs: [Provider packages — Caller-gated model discovery](provider-packages.md#caller-gated-model-discovery), [Provider caching — Discovery and live cache/cost metadata](provider-caching.md#discovery-and-live-cache-cost-metadata), [Provider conformance — Model discovery checklist](provider-conformance.md#model-discovery-checklist).
+
+## Shared thinking / per-turn override (Task 4 decision — frozen)
+
+| Layer | Contract |
+| --- | --- |
+| Model default | `ModelConfig.compat` (+ `capabilities.reasoning` where declared) |
+| Per-turn override | `ProviderRequestOptions.compat` via existing `mergeProviderRequestOptions` (request wins) |
+| Shared helpers | Core `applyThinkingLevel` / `thinkingCompatFor` / `thinkingFamilyForModel` → official compat fields; **not** a second options tree |
+| Families | `openai_reasoning` (`reasoning.effort`), `reasoning_effort`, `thinking_type` (`thinking.type`), `noop` (host-owned) — only shapes shared by ≥2 packages (or explicit no-op) |
+| Use-case wiring | LLM compaction + OM workers map `thinkingLevel` into `compat` via helpers (no longer inert `extra.thinkingLevel`) |
+| Docs | [Thinking and reasoning](thinking-and-reasoning.md) |
+
+**Decision (2026-07-17):** Implement thin core helpers; keep unique knobs (NeuralWatt budgets/kwargs, Kimi keep/all, Z.AI `tool_stream`) package-local. Core must not name forbidden provider literals (`openrouter`/`zai`/`kimi`/…). Hosts pick a family explicitly when inference is ambiguous. Per-provider first-class field hardening remains Tasks 6–12.
+
+## Use-case model binding inventory (Task 5 — done 2026-07-17)
+
+| Site | Current binding | Session fallback today? | Thinking path today |
+| --- | --- | --- | --- |
+| `AgentSession.run` / `RunOptions.model` | Per-run override; writes `model_change` | Explicit override of session model | Host `providerOptions` / `applyThinkingLevel` |
+| Observational memory workers | `resolveUseCaseModel({ configured: workerModel, sessionModel })` | **Yes** — host passes `sessionModel`; `requireExplicitModel` restores skip | `thinkingLevel` → `compat` via `applyThinkingLevel` |
+| LLM compaction | `resolveUseCaseModel({ configured: summaryModel, sessionModel: model })` | **Yes** — `model` is the fallback slot | `thinkingLevel` → `compat` via `applyThinkingLevel` |
+| Supervisor children | Child `Agent` owns its own `model` | Independent | Child config |
+| Declarative agents | `resolveAgentDefinition` model string / `ModelConfig` | Definition-scoped | Definition / run options |
+| Evaluations | `runOptions` including model | Eval-owned | Via run options |
+| Workflows / RPC / CLI | Pass-through `runOptions.model` | Caller-owned | Via run options |
+| Structured output | Reuses session/run model | Yes | Same as run |
+| Memory / RAG embedders | Host `Embedder` — separate from chat LLM | N/A (not chat) | N/A |
+
+**Decision (2026-07-17):** Core exports `UseCaseModelBinding`, `resolveUseCaseModel`, `resolveUseCaseModelBinding`, `useCaseCredentialProviderId`. Docs: [use-case-model-selection.md](use-case-model-selection.md). OM behavior change: session fallback when `sessionModel` supplied and worker model omitted; `requireExplicitModel` preserves historical `missing_model` skip.
+
+Desired Plan 067 outcome: every use-case accepts `{ provider, model, thinking }` with **explicit session-model fallback** when no use-case default is set — **done** for OM + LLM compaction; other sites documented as already-separate.
+
+## Known doc / code mismatches (frozen)
+
+| Item | Docs claim | Code / official | Owner task |
+| --- | --- | --- | --- |
+| Z.AI thinking | Was: `thinkingFormat: "zai"`, `developerRoleFallback` in `docs/providers/zai.md` | **fixed** Task 8 — docs+code match official `thinking` / `reasoning_effort` / `tool_stream` / `clear_thinking` | 8 (done) |
+| OpenAI reasoning | Was capabilities-only + opaque compat spread | Task 6 merges `model`/`options` `compat.reasoning` into body `reasoning`; Task 4 helper writes `compat.reasoning.effort` | 4 (done) / 6 (done) |
+| Kimi Moonshot | Was metadata-only (`provider: "moonshot"` without provider) | **fixed** Task 7: `createMoonshotProvider` registered when `includeMoonshotModels`; official Coding ids + `listKimiModels` | 7 (done) |
+| OpenCode Go catalog | Featured official Go open models + `listOpenCodeGoModels` | **done** Task 10 (removed stale `gpt-5.1-go` / `claude-sonnet-4.5-go`) | 10 (done) |
+| Z.AI catalog | Was: `glm-4.7` / `glm-4.5` only | **fixed** Task 8 — featured GLM-5.2…4.5 + `listZaiModels` | 8 (done) |
+| OM/LLM `thinkingLevel` + session fallback | Was inert `extra.thinkingLevel`; OM skipped without workerModel | Task 4 maps into `compat`; Task 5 session fallback + `requireExplicitModel` | 4 (done) / 5 (done) |
+
+## Credential and redaction canaries (per package)
+
+| Package | Secrets in flight | Redaction canary expectation |
+| --- | --- | --- |
+| openai | API key; OAuth device/user/access/refresh | Absent from errors, events, requests, discovery failures |
+| kimi | API key | Absent from errors / cache keys |
+| zai | API key | Absent from errors / model metadata |
+| openrouter | API key; session/cache ids | Sanitize length; never treat cache key as secret storage |
+| opencode-go | API key | Absent from errors |
+| neuralwatt | Optional API key; quota responses | Discovery/quota error bodies redacted |
+| ai-sdk | Host-owned | Adapter must not echo host secrets in Prism errors |
+
+No secrets are committed in this matrix.
+
+## Plan 067 task map (evidence owners)
+
+| Task | Owns |
+| --- | --- |
+| 0 | This page + evidence freeze — **done** |
+| 1 | R-001–R-004 re-verify — **fixed** 2026-07-17 |
+| 2 | R-005–R-006, R-008–R-012 re-verify — **fixed** 2026-07-17 |
+| 3 | Shared discovery pattern — **done** 2026-07-17 (package-local NeuralWatt template; no core list helper) |
+| 4 | Shared thinking / per-turn surface — **done** 2026-07-17 (core helpers + OM/LLM compat wiring; see thinking-and-reasoning.md) |
+| 5 | Use-case model selection + session fallback — **done** 2026-07-17 (`resolveUseCaseModel`, OM session fallback, use-case-model-selection.md) |
+| 6 | OpenAI validate/harden — **done** 2026-07-17 (Responses P0s, `listOpenAIModels`, `models?`, reasoning merge) |
+| 7 | Kimi validate/harden — **done** 2026-07-17 (`listKimiModels`, Moonshot provider, thinking, official Coding ids) |
+| 8 | Z.AI validate/harden — **done** 2026-07-17 (`listZaiModels`, GLM-5.x catalog, docs drift closed, clear_thinking/preserve) |
+| 9 | OpenRouter validate/harden — **done** 2026-07-17 (`listOpenRouterModels`, reasoning merge/preserve, automatic top-level `cache_control`) |
+| 10 | OpenCode Go validate/harden — **done** 2026-07-18 (`listOpenCodeGoModels`, official Go catalog, `zen/go/v1` base, thinking preserve) |
+| 11 | NeuralWatt validate/harden — **done** 2026-07-18 (featured catalog refresh, kwargs routing, owned-compat strip, applyThinkingLevel) |
+| 12 | AI SDK validate — **done** 2026-07-18 (host-owned catalog/cache/reasoning; usage mapping + docs) |
+| 13 | Cross-provider conformance + final verification — **done** 2026-07-18 (`sdk:ready`; 1,089 core tests + workspace suites + pack dry-runs) |
+
+Exact task titles live in `plans/067-provider-doc-validation-caching-discovery-and-review-hardening.md`.
+
+## Verification for this page
+
+- Final verification completed 2026-07-18 without live provider HTTP.
+- Lists all seven first-party provider packages; every provider row is `fixed` or intentional by-design behavior.
+- Lists every 2026-07-14 P0–P2 id (R-001–R-006, R-008–R-012); all are `fixed`.
+- Distinguishes official-doc priority vs Pi secondary.
+- `phase12-boundaries.test.ts` verifies all six HTTP package discovery exports and setup zero-fetch; AI SDK no-catalog behavior has its own adapter contract test.
+- `provider_validation_final_contract_covers_all_adapters_and_binding_sites` verifies provider docs, cache kinds, thinking rows, use-case sites, matrix statuses, and index navigation.
+- `npm run sdk:ready` passes: typecheck/build, 1,089 core tests, all workspace suites, packaging/provenance guards, and publish-graph pack dry-runs.
+- Linked from `docs/index.md` under Release and install.

package/docs/runs-and-usage.md

@@ -241,7 +241,7 @@ console.log(cacheUsageReport(aggregate?.usage));
 - `AgentConfig.ownership` is the default ownership scope; `RunOptions.ownership` overrides it per run.
 - `AgentConfig.idempotencyKey` is the default idempotency key; `RunOptions.idempotencyKey` overrides it per run.
 - The runtime resolves `model` and `provider` from `AgentConfig`/`RunOptions`/`AgentDefinition` before writing the start `RunRecord`.
-- Adapters should treat appends as ordered within a `runId`: event and tool-call rows preserve emission order because the runtime drains pending appends before writing the final `RunRecord`.
+- Adapters should treat appends as ordered within a `runId`: event and tool-call rows preserve emission order because the runtime serializes event ledger appends through one promise chain (concurrency 1), drains pending appends before writing the final `RunRecord`, and propagates append failures by rejecting run completion.
 - Billing queries must filter `scope = "provider_turn"`; presentation queries normally read the single `run_total`. `UsageQuery.scope`, `turn`, and `attempt` are explicit filters.
 - Adapters that need upsert semantics can use `RunRecord.id` (== `runId`) as the stable key.
 - Use `cacheUsageReport(record.usage, model)` for cache diagnostics from normalized usage. It works when a provider reports `cacheReadTokens` without `cacheWriteTokens`; missing write tokens are reported as `0`, and unavailable hit rate/savings stay `undefined`.

package/docs/sqlite-persistence.md

@@ -56,7 +56,7 @@ import { createSqlitePersistence } from "@arnilo/prism-session-store-sqlite";
 | `leases` | Atomic `LeaseStore` backed by `prism_leases`; database-clock expiry, opaque renew/release token, monotonic takeover fence. |
 | `close()` | Closes the underlying database when the adapter opened it. |
 
-Migrations run automatically on open and are idempotent across reopen.
+Migrations run automatically on open and are idempotent across reopen. Under the SQLite migration transaction, startup checks ordered contract name/version/SHA-256 rows plus full schema-v3 PRAGMA/catalog shape (all required tables, columns/types/nullability/defaults, PK/unique/FK keys, and named indexes) before any runtime write. A complete legacy 0.0.5 history with all `checksum` values `NULL` is shape-verified then backfilled transactionally once. Unknown, duplicate, out-of-order, partial-legacy, checksum, or shape drift rejects open; restore or apply reviewed DDL rather than editing migration rows.
 
 ## Request/response example
 
@@ -109,7 +109,7 @@ For resume/timeline flows, use `queryRuns`, `queryEvents`, `queryToolCalls`, and
 - **No path interpolation.** The adapter opens exactly the caller-supplied `filename`; it does not expand environment variables or discover paths.
 - **Redaction upstream.** Event and tool-call payloads may contain secrets; redact before ledger writes. The adapter does not scan or rewrite row contents.
 - **WAL + busy timeout.** WAL is enabled by default; busy timeout defaults to 5 seconds. This meets the Plan 056 local workload target but SQLite still serializes writers — prefer PostgreSQL for high write concurrency.
-- **Indexed operations.** Append, parent validation, idempotency dedup, branch reads, and pagination use the indexes documented in [Database persistence](database-persistence.md); normal paths avoid whole-database scans.
+- **Indexed operations.** Append, parent validation, idempotency dedup, branch reads, and pagination use the indexes documented in [Database persistence](database-persistence.md); normal paths avoid whole-database scans. Startup validation reads SQLite catalog/PRAGMA metadata only, never application rows.
 - **Tenant isolation.** `tenant_id` / `account_id` / `user_id` columns on run and ownership tables participate in query filters; hosts must still scope writes correctly.
 
 ## Related APIs

package/docs/structured-output.md

@@ -234,7 +234,7 @@ Key cross-seam points:
 - The default parser treats assistant text as the value (`{ ok: true, value: text }`); supply a host parser whenever `T` is not `string`.
 - The default repairer builds a user message from `validation.errors[].message`; supply a host repairer for schema-specific guidance.
 - `maxRevisions` (default 3) bounds revision turns; budget exhaustion ends the loop and emits `artifact_failed` (it does not throw).
-- Tools are not dispatched in revision turns. Hosts needing tools in artifact turns use `singleShotLoop` or a custom loop.
+- Tools are inert in artifact turns unless `loop.toolCalls: "bounded"` is explicit. Bounded mode uses run-global `maxToolRounds`, dispatches calls sequentially through normal runtime guards, skips parser/validator for tool-calling responses, and permits at most `1 + maxRevisions + maxToolRounds` provider turns. An extra tool response yields terminal `artifact_failed` with `result.metadata.reason === "tool_round_limit"` and executes nothing.
 
 ## Security and performance notes
 

package/docs/thinking-and-reasoning.md

@@ -0,0 +1,98 @@
+# Thinking and reasoning
+
+## What it does
+
+Prism keeps thinking/reasoning **provider-owned on the wire** while giving hosts one portable way to set effort per turn. Model defaults live on `ModelConfig.compat` (and `capabilities.reasoning` where declared). Per-turn overrides live on `ProviderRequestOptions.compat` and win through existing `mergeProviderRequestOptions`. Shared helpers map a portable `ThinkingLevel` into the official compat fields each family already reads — they do **not** invent a second options tree.
+
+## When to use it
+
+- Session runs: pass `providerOptions.compat` (or `applyThinkingLevel`) on `RunOptions`.
+- Use-case workers (LLM compaction, observational memory): pass `thinkingLevel`; packages map it into `compat` via the shared helpers.
+- Provider authors: keep reading official fields from `options.compat` / `model.compat`; add package-local escape hatches only when the official API has unique knobs.
+
+## Contract
+
+| Layer | Surface |
+| --- | --- |
+| Model default | `ModelConfig.compat` (+ `capabilities.reasoning` when the model can reason) |
+| Per-turn override | `ProviderRequestOptions.compat` (request wins over model via merge) |
+| Portable level | `ThinkingLevel`: `none` \| `minimal` \| `low` \| `medium` \| `high` \| `xhigh` \| `max` |
+| Helpers | `thinkingCompatFor`, `applyThinkingLevel`, `thinkingFamilyForModel`, `isThinkingLevel`, `normalizeThinkingLevel`, `THINKING_LEVELS` |
+| Not used | Inert `options.extra.thinkingLevel` — providers do not read `extra` for effort |
+
+```ts
+import { applyThinkingLevel, thinkingCompatFor, thinkingFamilyForModel } from "@arnilo/prism";
+
+// Per-turn override on a session run (OpenAI / OpenRouter family)
+await session.run(input, {
+  providerOptions: applyThinkingLevel(undefined, "low", "openai_reasoning"),
+});
+
+// Equivalent explicit compat
+await session.run(input, {
+  providerOptions: { compat: thinkingCompatFor("openai_reasoning", "low") },
+  // → { reasoning: { effort: "low" } }
+});
+
+// Use-case worker: family from model metadata (or pass an explicit family)
+const family = thinkingFamilyForModel(model);
+await runObserver({
+  ...,
+  providerOptions: applyThinkingLevel(base, "low", family === "noop" ? "reasoning_effort" : family),
+});
+```
+
+## Compat families
+
+Core maps only shapes shared by ≥2 packages (or an explicit no-op). Unique knobs stay package-local.
+
+| Family | Compat patch | Used by (official fields) |
+| --- | --- | --- |
+| `openai_reasoning` | `{ reasoning: { effort } }` | OpenAI Responses `reasoning.effort`; OpenRouter `reasoning.effort` |
+| `reasoning_effort` | `{ reasoning_effort }` | Z.AI `reasoning_effort`; NeuralWatt `reasoning_effort`; Kimi K3 `reasoning_effort` |
+| `thinking_type` | `{ thinking: { type: "enabled" \| "disabled" } }` | Z.AI `thinking.type`; Kimi K2.x `thinking.type` (`none` → `disabled`) |
+| `noop` | `{}` | AI SDK / host-owned adapters — effort is host-model settings |
+
+`applyThinkingLevel` defaults `family` to `reasoning_effort` when omitted. For `openai_reasoning`, an existing `compat.reasoning.summary` (or other reasoning keys) is preserved when merging `effort`.
+
+### Recommended family by first-party package
+
+| Package | Recommended family | Notes |
+| --- | --- | --- |
+| `@arnilo/prism-provider-openai` | `openai_reasoning` | First-class body `reasoning` from model + per-turn compat merge; `summary`/`mode`/`context` via compat |
+| `@arnilo/prism-provider-openrouter` | `openai_reasoning` | First-class `resolveOpenRouterReasoning` merge; prefer `reasoning` object over legacy `reasoning_effort` shorthand; `preserveThinking` replays as body `reasoning` |
+| `@arnilo/prism-provider-zai` | `reasoning_effort` (+ optional `thinking_type`) | Official `thinking` / `reasoning_effort` / `tool_stream` / `clear_thinking`; Preserved Thinking via `reasoning_content` |
+| `@arnilo/prism-provider-neuralwatt` | `reasoning_effort` | Budgets / `preserve_thinking` / `clear_thinking` / `chat_template_kwargs` stay package-local on `compat` |
+| `@arnilo/prism-provider-kimi` | K3: `reasoning_effort`; K2.x: `thinking_type` | K2.7-code thinking is always on; do not send conflicting `thinking` + `reasoning_effort` |
+| `@arnilo/prism-provider-opencode-go` | Anthropic route: thinking blocks (`thinking_type` family); OpenAI route: `reasoning_content` preserve + optional `thinking`/`reasoning_effort`/`reasoning` passthrough | Official dual endpoints; MiniMax/Qwen → Anthropic, others → OpenAI |
+| `@arnilo/prism-provider-ai-sdk` | `noop` | Host `LanguageModelV4` owns reasoning settings |
+
+`thinkingFamilyForModel` infers family from existing `compat` shape, then safe provider heuristics (`openai*` → `openai_reasoning`, `neuralwatt` → `reasoning_effort`), then `capabilities.reasoning` → `reasoning_effort`, else `noop`. Docs and packages may map other provider ids explicitly; core avoids provider-specific literals beyond those heuristics.
+
+## Merge order
+
+1. `ModelConfig.compat` / model defaults inside the provider
+2. `ProviderRequestOptions.compat` from agent / session policies
+3. Per-turn `RunOptions.providerOptions` or use-case `applyThinkingLevel` patch (wins)
+
+Providers already prefer `request.options.compat.*` over `request.model.compat.*`.
+
+## Use-case workers
+
+LLM compaction and observational memory accept `thinkingLevel?: string`. They call `applyThinkingLevel` into `compat` (not `extra.thinkingLevel`). When model inference returns `noop`, an explicit `thinkingLevel` still falls back to `reasoning_effort` so the host setting is never inert. Model selection for those workers (including session-model fallback) is documented in [Use-case model selection](use-case-model-selection.md).
+
+## Non-reasoning models
+
+- Helper with `noop`: returns options unchanged — no invented body fields.
+- Helper with a real family on a model that rejects the field: provider/API error — hosts should gate on `capabilities.reasoning` or package docs.
+- `thinking_type` + `none` sets `{ type: "disabled" }`; other levels set `{ type: "enabled" }` without encoding effort (compose with `reasoning_effort` when the API supports both).
+
+## Related pages
+
+- [Use-case model selection](use-case-model-selection.md) — session vs worker/summary model binding
+- [Provider packages](provider-packages.md) — package boundaries and discovery
+- [Provider caching](provider-caching.md) — cache retention can disable thinking on some providers (e.g. Z.AI when `cacheRetention: "none"`)
+- [Provider request policies](provider-request-policies.md) — `mergeProviderRequestOptions`
+- [Agent/session runtime](agent-session-runtime.md) — prior-reasoning preservation across turns
+- Per-provider pages under [docs/providers](providers/)
+- Evidence matrix: [Review coverage (2026-07-17 provider validation)](review-coverage-2026-07-17-provider-validation.md)

package/docs/tool-execution-primitives.md

@@ -123,8 +123,8 @@ Package performs **no** `PermissionPolicy`, `ToolValidator`, or trust checks of
 | --- | --- |
 | `ToolDefinition.parameters` | Stored and forwarded to providers; **not validated** by core |
 | `ToolValidator` | Host function hook; Phase 25 threads through agent runtime |
-| Standards-based schema validation | **Not shipped** — capability gap C-001 |
-| Schema compile cache | **None** — every dispatch would re-validate if host validator is naive |
+| Standards-based schema validation | Optional `@arnilo/prism-tool-validator-json-schema`; host wires it through `ToolValidator` |
+| Schema compile cache | Adapter-owned finite LRU; core never compiles schemas |
 
 ### MCP mapping (shipped — Task 3)
 
@@ -186,7 +186,7 @@ import { createJsonSchemaToolArgumentValidator } from "@arnilo/prism-tool-valida
 createAgent({ model, validator: createJsonSchemaToolArgumentValidator() });
 ```
 
-**Cache key:** stable `JSON.stringify(schema)` in adapter-owned `Map`. **Bounds:** configurable depth/properties/string/array limits before Ajv validation. **Security:** remote `$ref` rejected; prototype-pollution keys rejected in schemas and instances.
+**Cache key:** stable `JSON.stringify(schema)` in an adapter-owned 256-entry LRU (hard cap 1,024); eviction removes the matching Ajv schema. **Bounds:** schemas default to 256 KiB, depth 64, 10,000 properties/keywords, and 128 refs (hard 1 MiB/128/100,000/1,024); instance depth/properties/string/array limits remain configurable. Every limit rejects non-finite, unsafe, zero/negative, and above-hard values. **Security:** only fragment-local `$ref` is accepted; prototype-pollution keys, cycles, and non-finite schema numbers reject before Ajv compilation.
 
 ### Task 2 — Parallel tool execution — **shipped**
 

package/docs/tools.md

@@ -154,6 +154,10 @@ const agent = createAgent({ model, provider, tools: activeTools, permission, val
 
 Need different tools for one request? Build a short-lived agent/session with a narrower registry, or block extra calls with `PermissionPolicy` / `RunOptions.validate`. No extra per-run tool API exists yet; add one only when host apps need it.
 
+### Artifact-loop tools
+
+`generate-validate-revise` treats provider tools as inert by default. Set `loop.toolCalls: "bounded"` and `RunOptions.maxToolRounds` only when an artifact needs a host-owned lookup before its next candidate. Each response with one-or-more calls consumes one shared round, dispatches calls sequentially through this exact `dispatchToolCall()` path, persists assistant-call then result transcript rows, and skips artifact parsing/validation for that response. A post-limit call executes nothing; the loop emits `artifact_failed` with `metadata.reason: "tool_round_limit"`. Tools do not consume `maxRevisions`, and tool schemas/context never grant authority.
+
 ### Runtime-supplied validators
 
 `AgentConfig.validator?` and `RunOptions.validate?` expose the same `ToolValidator` seam that `DispatchToolCallOptions.validate` already uses. The runtime threads `validate: RunOptions.validate ?? AgentConfig.validator` into every `dispatchToolCall` it issues during the tool loop, so an app can supply argument validation without taking ownership of dispatch itself. `RunOptions.validate` overrides `AgentConfig.validator` on a per-run basis (RunOptions wins). When neither is set, dispatch runs unmodified.
@@ -229,6 +233,17 @@ await session.run(input, {
 - Contribution registration and registry/filter calls do not perform provider calls, credential resolution, resource loading, network, filesystem discovery, or tool execution.
 - Dispatch performs explicit in-memory checks and executes only the selected host-active tool; it adds no retries, queues, timers, or new dependencies.
 
+## JSON Schema validator limits
+
+Core stores `ToolDefinition.parameters` but does not compile schemas. Hosts that install `@arnilo/prism-tool-validator-json-schema` receive pre-Ajv schema limits: 256 KiB bytes, depth 64, 10,000 properties/keywords, 128 refs, and a 256-entry LRU compiled cache by default. All reject invalid values and have finite hard ceilings. Only fragment-local `$ref` values are accepted; non-local refs, cycles, forbidden keys, and non-finite schema numbers fail before tool execution.
+
+```ts
+createJsonSchemaToolArgumentValidator({
+  maxSchemaBytes: 256 * 1024,
+  maxCompiledSchemas: 256,
+});
+```
+
 ## Related APIs
 
 - [Agent/session runtime](agent-session-runtime.md): dispatches complete provider tool calls through the host-active tool harness and returns tool results on the next provider turn.

package/docs/use-case-model-selection.md

@@ -0,0 +1,109 @@
+# Use-case model selection
+
+## What it does
+
+Prism separates the **session chat model** (`AgentConfig.model` / `RunOptions.model`) from **use-case models** used by background or adjacent LLM jobs (observational memory workers, LLM compaction summarizers, declarative agents, supervisor children, evals). Hosts bind `{ model?, provider?, providerOptions?, thinkingLevel? }` per use case. When the use-case omits `model`, resolution falls back to the active session model. Workers never write `model_change` session entries for their own jobs.
+
+## When to use it
+
+- Observational memory should run a cheaper/faster model than the chat session (or inherit the session model when unset).
+- LLM compaction should summarize with an explicit `summaryModel`, falling back to a host-supplied session `model`.
+- Declarative agents, supervisor children, evals, and RPC/CLI runs already own their models — document them as use-case sites that stay separate from a parent session.
+- Memory/RAG `Embedder` selection is related but **not** a chat `ModelConfig` binding.
+
+## Contract
+
+| Layer | Surface |
+| --- | --- |
+| Binding | `UseCaseModelBinding`: `{ model?, provider?, providerOptions?, thinkingLevel?, requireExplicitModel? }` |
+| Resolver | `resolveUseCaseModel({ configured, sessionModel, requireExplicitModel?, … })` → `{ model, source }` or `undefined` |
+| Binding helper | `resolveUseCaseModelBinding(binding, sessionModel)` |
+| Credential id | `useCaseCredentialProviderId(resolved, binding?)` — always the **resolved** `model.provider` |
+| Escape hatch | `requireExplicitModel: true` skips session fallback (OM historical `missing_model`) |
+
+```ts
+import { resolveUseCaseModel, applyThinkingLevel, thinkingFamilyForModel } from "@arnilo/prism";
+
+// Prefer an explicit worker; otherwise inherit the session/agent model.
+const resolved = resolveUseCaseModel({
+  configured: settings.workerModel,       // optional use-case ModelConfig
+  sessionModel: agent.config.model,       // host-supplied; AgentSession does not expose agent
+  thinkingLevel: settings.thinkingLevel,
+});
+if (!resolved) {
+  // skip — neither configured nor session model (or requireExplicitModel)
+}
+
+const family = thinkingFamilyForModel(resolved.model);
+const providerOptions = resolved.thinkingLevel
+  ? applyThinkingLevel(resolved.providerOptions, resolved.thinkingLevel, family === "noop" ? "reasoning_effort" : family)
+  : resolved.providerOptions;
+```
+
+### Precedence
+
+1. `configured` / `binding.model` → `source: "configured"`
+2. Else `sessionModel` when `requireExplicitModel` is not set → `source: "session"`
+3. Else `undefined` (package skips or throws)
+
+Resolution is O(1) and network-free. It does not mutate session history.
+
+## Binding sites
+
+| Site | How hosts bind | Session fallback |
+| --- | --- | --- |
+| Observational memory | `workerModel` / settings `workerModel` + runtime `sessionModel` | Yes — pass `sessionModel: agent.config.model`; `requireExplicitModel` restores skip |
+| LLM compaction | `summaryModel` with `model` as fallback slot | Yes — `resolveUseCaseModel({ configured: summaryModel, sessionModel: model })` |
+| `RunOptions.model` | Per-run override on the **session** | N/A — this *is* the session/run model (writes `model_change`) |
+| Declarative `AgentDefinition` | Definition `model` / registry resolve | Definition-scoped (independent agent) |
+| Supervisor children | Child `createSession` / child `AgentConfig.model` | Independent child session |
+| Evals / workflows / RPC / CLI | Caller `runOptions.model` | Caller-owned |
+| Structured output | Reuses session/run model | Same as run |
+| Memory / RAG | Host `Embedder` | Not a chat model — see [Working and semantic memory](working-and-semantic-memory.md) |
+
+## Observational memory
+
+```ts
+createObservationalMemoryRuntime({
+  session,
+  appendEntry: (entry) => store.append(entry),
+  workerProvider,
+  sessionModel: agent.config.model, // enables fallback when workerModel unset
+  // workerModel: { provider: "neuralwatt", model: "glm-5.2-fast" }, // optional override
+  overrides: { thinkingLevel: "low", observeAfterTokens: 1 },
+});
+```
+
+- Default: no `workerModel` + `sessionModel` set → workers use the session model.
+- Explicit `workerModel` (or settings `workerModel`) always wins.
+- `requireExplicitModel: true` (runtime or settings) → `skipped: "missing_model"` when no worker model, even if `sessionModel` is set.
+- Neither worker nor session model → `skipped: "missing_model"`.
+- Default credential request uses the **resolved** model's `provider` id.
+
+## LLM compaction
+
+```ts
+createLlmCompactionStrategy({
+  provider: summaryProvider,
+  summaryModel: { provider: "example", model: "cheap-summary" }, // optional
+  model: agent.config.model, // session fallback when summaryModel omitted
+  thinkingLevel: "low",
+});
+```
+
+`summaryModel` wins; otherwise `model` is required. Thinking maps into `compat` via `applyThinkingLevel` ([Thinking and reasoning](thinking-and-reasoning.md)).
+
+## Security
+
+- Credential requests for worker calls must target the **resolved** model’s provider — not ambient session credentials for a different provider unless the host wires that explicitly.
+- Pass known secrets into worker/compaction options so prompts, ledger custom entries, and errors stay redacted.
+- Background workers must not append `model_change` entries or otherwise rewrite the chat session’s model timeline.
+
+## Related pages
+
+- [Thinking and reasoning](thinking-and-reasoning.md) — per-turn `thinkingLevel` → `compat`
+- [Observational memory compaction package](compaction-observational-memory.md)
+- [LLM compaction package](compaction-llm.md)
+- [Agent/session runtime](agent-session-runtime.md) — `RunOptions.model` / `model_change`
+- [Working and semantic memory](working-and-semantic-memory.md) — `Embedder` (non-chat)
+- Evidence matrix: [Review coverage (2026-07-17 provider validation)](review-coverage-2026-07-17-provider-validation.md)

package/docs/workflow-orchestration-primitives.md

@@ -387,6 +387,7 @@ const review = functionNode({ execute: async (ctx) => lint(ctx.upstream.draft) }
 
 const workflow = defineWorkflow({
   id: "research-draft-review",
+  revision: "2026-07-19.1",
   nodes: { research, draft, review },
   edges: [
     ["research", "draft"],

package/docs/workflows.md

@@ -29,29 +29,32 @@ Use `createWorkflowCoordinator()` when multiple processes share SQLite/PostgreSQ
 
 ## Inputs / request
 
-`defineWorkflow({ id, nodes, edges, limits? })`:
+`defineWorkflow({ id, revision, nodes, edges, limits? })`:
 
 | Field | Notes |
 | --- | --- |
 | `id` | Stable workflow id (required) |
+| `revision` | Non-empty host-authored definition revision (required); parent and nested revisions enter `definitionHash` |
 | `nodes` | Record of node definitions (`kind` + typed fields) |
 | `edges` | `[from, to]` pairs; must be acyclic; unknown ids rejected |
-| `limits.maxNodes` | Default 1000 |
-| `limits.maxFanOut` | Default 64 |
-| `limits.maxConcurrency` | Default 8 |
-| `limits.maxNodeOutputBytes` | Default 4 MiB |
-| `limits.maxCheckpointBytes` | Default 1 MiB |
+| `limits.maxNodes` | Default 1,000 / hard cap 10,000 |
+| `limits.maxFanOut` | Default 64 / hard cap 1,024 |
+| `limits.maxConcurrency` | Default 8 / hard cap 256 |
+| `limits.maxNodeOutputBytes` | Default 4 MiB / hard cap 16 MiB |
+| `limits.maxCheckpointBytes` | Default 1 MiB / hard cap 8 MiB |
 | `limits.maxNestedDepth` / hard cap | 8 / 32; inherited by child workflows |
 | `limits.maxStateBytes` / hard cap | 64 KiB / 512 KiB |
 | `limits.maxStateHistory` / hard cap | 32 / 128 state snapshots; updates stop before evidence would be discarded |
 | `limits.maxReplayDepth` / hard cap | 8 / 32 lineage generations |
 | `state.initial` / `state.schema` | Initial shared JSON object and optional host-validated schema |
 
+All workflow limits and runtime `concurrency` reject non-safe integers, zero, negatives, NaN, `Infinity`, and values above the named hard cap. Node retries allow 0–100; an explicit node timeout allows 1–86,400,000 ms. Omitting `timeoutMs` remains an explicit host choice.
+
 `runWorkflow(workflow, input, options?)`:
 
 | Option | Notes |
 | --- | --- |
-| `concurrency` | Worker pool size (capped by workflow/global limits) |
+| `concurrency` | Worker pool size; positive safe integer, hard cap 256, and capped by the workflow limit |
 | `checkpoints` | `WorkflowCheckpointAdapter` for save/load/list |
 | `agentFactory` | `(agentName) => AgentSession` for agent nodes |
 | `tools` | Tool registry/lookup for tool nodes |
@@ -100,6 +103,7 @@ Package-local `WorkflowEvent` types: `workflow_started`, `workflow_suspended`, `
 ```json
 {
   "id": "research-draft",
+  "revision": "2026-07-19.1",
   "nodes": ["research", "draft"],
   "edges": [["research", "draft"]],
   "limits": { "maxNodes": 256, "maxFanOut": 32, "maxConcurrency": 4 }
@@ -159,6 +163,7 @@ const publish = functionNode({
 
 const workflow = defineWorkflow({
   id: "research-draft",
+  revision: "2026-07-19.1",
   nodes: { research, draft, publish },
   edges: [["research", "draft"], ["draft", "publish"]],
   limits: { maxNodes: 256, maxFanOut: 32, maxConcurrency: 4 },
@@ -209,6 +214,7 @@ if (result.status === "suspended") {
 await cancelWorkflowRun({
   workflowId: workflow.id,
   runId: result.runId,
+  workflow,
   checkpoints,
   ownership: { tenantId: "t1" },
 });
@@ -258,15 +264,16 @@ runRpcServer({
 
 ## Security and performance notes
 
-- Definitions fail closed on cycles, unknown edges, self-edges, and `maxNodes` overflow.
-- Fan-out length is bounded by `maxFanOut`; concurrency by `maxConcurrency`.
+- Definitions require a non-empty host-authored `revision` and fail closed on cycles, unknown edges, self-edges, invalid limits, and `maxNodes` overflow. Revision and every nested revision enter the deterministic definition hash; hosts must bump revision when function/tool behavior changes.
+- Fan-out length is bounded by `maxFanOut`; concurrency by `maxConcurrency`; every count/byte/runtime option has a finite hard cap.
 - Node outputs, shared state/history, schedule input/records, and checkpoints are byte/count/depth bounded. Checkpoint size remains the final aggregate ceiling.
 - Event buses use a bounded buffer (default 2048) with `close` / `drop_oldest` / `drop_newest` overflow.
 - Checkpoints redact suspension/resume payloads via `SecretRedactor` / `secrets` before save; resume rejects tenant, schema, definition-hash, and expected-version mismatch.
 - Suspension requires a checkpoint adapter, consumes no worker/polling slot, and is ignored by distributed coordinators until explicit resume.
 - Concurrent resumes race on checkpoint CAS before node execution; one wins and stale/duplicate reviewers fail closed. Approved tool nodes then re-run current `ExecutionPolicy`, so durable approval cannot grant stale permissions.
 - `toolNode({ approval: { reason, data?, resumeSchema? } })` suspends before tool execution. Denial is terminal `denied`; no tool side effect occurs.
-- `cancelWorkflowRun` aborts local runs immediately and writes a durable cancellation request for a remotely leased run; workers check it during lease renewal.
+- `cancelWorkflowRun` requires the current workflow definition and exact tenant/account/user ownership. It verifies recursive definition hash before abort/mutation, then aborts local runs or writes a durable cancellation request for remotely leased work. Tenant-only or missing ownership cannot cancel a more-specific owned run.
+- Active registry identity includes workflow ID, run ID, and exact ownership. Exact duplicates fail instead of overwriting; distinct owners remain isolated in lookup/list/cancel/unregister.
 - Tool nodes attach `workflowId` / `nodeId` on `ExecutionAction.metadata` for approval/audit context.
 - Nested workflows inherit host registries/policies and cannot inject broader tools, agents, ownership, or credentials. Nested depth is inherited; child suspension bubbles to the parent review cursor.
 - Replay source ownership/hash/status/node eligibility are checked before a new checkpoint is created. Source records are immutable, lineage is bounded, and copied approval-bearing paths are rejected.

package/docs/working-and-semantic-memory.md

@@ -152,6 +152,7 @@ await runMemoryConformance(() => ({
 - Configure `secrets` / `redactor` so memory text and metadata cannot persist or inject raw canaries.
 - Injected context is inert text — it cannot grant tools or permissions.
 - Hard caps: top-K ≤ 32, messageRange ≤ 4, embed batch ≤ 128, injected tokens ≤ 8000, payload/working-memory byte limits enforced.
+- Every embedding is a non-empty finite number vector. `embedBatched()`, in-memory `VectorStore` upserts/queries, and PostgreSQL/pgvector parameters reject NaN, ±Infinity, non-numbers, and wrong configured dimensions before similarity scoring or SQL. Custom adapters can call `assertFiniteVector(vector, label, expectedLength?)` at their trust boundary.
 - Default `remember()` does not block agent completion; pass `{ wait: true }` when indexing must finish first.
 - PostgreSQL live suite is gated by `PRISM_TEST_POSTGRES_URL` and requires the `vector` extension.