@arnilo/prism 0.3.0 → 0.3.1

package/docs/migration.md

@@ -1,5 +1,15 @@
 # Migration guide
 
+## 0.3.0 → 0.3.1 production RAG engine (independent patch)
+
+Only `@arnilo/prism-rag`, `@arnilo/prism-memory`, and `@arnilo/prism-observability-opentelemetry` move to `0.3.1`. Keep every other first-party package on `^0.3.0` — those ranges already satisfy `0.3.1`.
+
+**Required for Embedder implementers.** `Embedder.id` is now a required `readonly id: string` (stable model/deploy identity, ≤256 chars). Hosts that construct their own embedder must set it; `createHashEmbedder` defaults to `"prism-hash-embedder"` and the Alibaba embedder uses `options.model`. `retrieveContext` fails closed with `ERR_PRISM_RAG_EMBEDDER_MISMATCH` when a stored `embedderId` is missing or differs (or dimensions differ). Re-index the source after an embedder/model change. Existing 0.3.0 rows without `embedderId` also fail closed until re-indexed.
+
+Everything else is additive and opt-in: `createPostgresVectorStore`, hybrid `lexical` retrieve, `contentHash` skip, heading metadata, generation pointers, `createRagTelemetry`, `createTeiReranker`, multi-scope retrieve (`scopes` — pass `scope` for one corpus or `scopes` for one-or-many exact corpora; `scope` stays valid, both or neither throws). Default `retrieveContext` / `replaceSource` paths without those options stay 0.3.0-compatible (vector-only, single-scope, no skip, no telemetry).
+
+Postgres DDL is additive (`IF NOT EXISTS` columns/indexes/tables). 0.3.0 rows remain readable. Rollback = restore the 0.3.0 package versions; no down migration.
+
 ## 0.2.9 → 0.3.0 lockstep cut and independent package versions (additive)
 
 Release **0.3.0** is the final lockstep cut on the 0.3.x line: all 57 publishable manifests move from `0.2.9` to `0.3.0`, then internal first-party `dependencies`, `optionalDependencies`, and `peerDependencies` use `^0.3.0`. The package graph is now **Decision B**: changed packages may patch/minor independently inside `>=0.3.0 <0.4.0`; unchanged packages keep their version.

package/docs/node-jsonl-session-store.md

@@ -72,7 +72,7 @@ Use `createMemorySessionStore()` for tests or throwaway sessions; use the JSONL
 - Reads and writes use only the caller-provided path.
 - Errors include path/reason or line number, not file contents.
 - Do not put secrets in messages, metadata, summaries, labels, or custom entries.
-- Reads are linear in file size. Appends also re-read and re-parse the whole file for duplicate/parent/corruption checks before writing one line, and are serialized per store instance.
+- Reads are linear in file size. Appends also re-read and re-parse the whole file for duplicate/parent/corruption checks before writing one line, and are serialized per store instance. A rejected append does not poison later appends; the rejected line is not written.
 - There is no cross-process lock or durable idempotency table; two processes writing the same file can race. Add a database or external lock if multiple processes write the same file.
 - Treat this adapter as development/single-process storage. Production multi-writer hosts should use an indexed database `SessionStore` adapter.
 

package/docs/obscura.md

@@ -0,0 +1,175 @@
+# Obscura browser engine
+
+Optional `@arnilo/prism-obscura` support for a host-installed
+[Obscura](https://github.com/h4ckf0r0day/obscura) headless browser. Obscura is never
+bundled — install the binary (or use the `h4ckf0r0day/obscura` Docker image) and point
+the package at it.
+
+- Capability evidence: `docs/_evidence/phase39-obscura-capability-matrix.md`
+  (pinned to Obscura `0.1.0` @ `f449e6f`).
+
+## Install
+
+```bash
+npm install @arnilo/prism-obscura
+```
+
+## Process lifecycle (`spawnObscuraProcess`)
+
+Runs a shell-free, bounded, ownership-tracked Obscura process. Configuration is
+validated fail-closed: absolute NUL-free command, bounded argv/env, minimal default
+environment (`PATH`, `HOME`), and insecure flags (`--allow-private-network`,
+`--allow-file-access`, non-loopback `--host`) rejected unless `allowInsecureFlags`
+is set explicitly.
+
+```ts
+import { spawnObscuraProcess } from "@arnilo/prism-obscura";
+
+const obscura = spawnObscuraProcess({
+  command: "/usr/local/bin/obscura",
+  args: ["serve", "--host", "127.0.0.1", "--port", "9222"],
+});
+await obscura.waitReady(() => canConnect("ws://127.0.0.1:9222"));
+await obscura.close(); // SIGTERM → SIGKILL after grace; process-group kill on POSIX
+```
+
+Docker works through the same argv seam — no Docker SDK:
+
+```ts
+const mcp = spawnObscuraProcess({
+  command: "/usr/bin/docker",
+  args: ["run", "--rm", "-i", "h4ckf0r0day/obscura", "mcp"],
+});
+```
+
+Guarantees: argv byte-for-byte; capped stderr capture; errors never echo argv/env;
+`close()` idempotent and kills only owned resources; abort signals kill owned
+processes immediately.
+
+## MCP tools (`createObscuraMcpTools`)
+
+Connects to `obscura mcp` (stdio or Streamable HTTP) through
+[`@arnilo/prism-mcp`](mcp-tools.md) and exposes **every advertised tool** — no static
+allow-list, so future Obscura tools keep flowing through.
+
+```ts
+import { createObscuraMcpTools } from "@arnilo/prism-obscura";
+
+const obscura = await createObscuraMcpTools({
+  transport: { type: "stdio", command: "/usr/local/bin/obscura", args: ["mcp"] },
+});
+agent.tools = [...agent.tools, ...obscura.tools];
+await obscura.close();
+```
+
+- Tool inventory at the pinned revision: 37 `browser_*` tools; render-enabled builds
+  add `browser_screenshot` and `browser_pdf`.
+- **`browser_search` is in-page text search**, not public-web search.
+- Effects: read/diagnostic/waiter/capture tools are effect-free; navigation,
+  interaction, evaluation, cookie/storage writes, tabs, and any unknown future tool
+  are exclusive, serialized external mutations (Obscura keeps one live page).
+- Naming: default `obscura_` prefix coexists with `@arnilo/prism-browser`;
+  `namePrefix: ""` preserves native Obscura names.
+- Transports: stdio configs are validated with the same fail-closed command policy;
+  Streamable HTTP endpoints outside loopback require explicit `allowRemoteHttp` and
+  remain subject to `@arnilo/prism-mcp` origin/transport security.
+
+## CDP and Playwright (`connectObscuraCdp`)
+
+Attach to a running Obscura CDP endpoint — or spawn `obscura serve` and attach once
+it is ready (bounded, abortable readiness; no fixed post-start sleep) — through the
+host's Playwright via `chromium.connectOverCDP`. `connect()` and browser launch are
+never used; Prism never launches browsers.
+
+```ts
+import { connectObscuraCdp } from "@arnilo/prism-obscura";
+import { createBrowserTools } from "@arnilo/prism-browser";
+
+const session = await connectObscuraCdp({
+  command: "/usr/local/bin/obscura",
+  args: ["serve", "--host", "127.0.0.1", "--port", "9222"],
+});
+const tools = createBrowserTools({ browser: session.browser, networkPolicy });
+// ... run ...
+await session.close(); // browser first, then the owned process
+```
+
+- External mode: pass `endpoint` (`ws://`/`http://`) with no `command` — the server
+  stays alive after `close()`; only resources this call created are terminated.
+- Endpoints are loopback-only unless `allowRemoteEndpoint` is set; credentials in the
+  URL are always rejected; remote plain `ws:`/`http:` is refused (no authentication —
+  require an authenticated `wss:`/`https:` tunnel).
+- The Playwright import is an optional exact `playwright-core@1.61.0` peer; supply
+  `connectObscuraCdp({ playwright })` to inject a host-selected build.
+- The returned browser composes with `createBrowserManager`/`createBrowserTools`:
+  snapshots, actions, policy, checkpoints, and artifacts are Prism-owned. Raw CDP
+  (screenshots, PDF, screencast) stays available through Playwright's CDP session
+  APIs (`browser.newBrowserCDPSession()`, `context.newCDPSession(page)`); the package
+  adds no CDP command allow-list.
+- Concurrency limit: pages served by one Obscura worker share one V8 isolate —
+  CPU-bound page JavaScript can delay sibling pages. Keep `@arnilo/prism-browser`
+  limits authoritative; size Obscura's `--workers` for the host.
+- Screenshots/PDF require a render-enabled Obscura build and still obey the browser
+  package's artifact/byte policy.
+
+## Web search, fetch, and scrape (`createObscuraWebTools`)
+
+Bounded CLI-backed web tools built on short-lived `obscura fetch`/`obscura scrape`
+child processes. Returns standard Prism `web_search`/`web_fetch` tools plus explicit
+`obscura_fetch`/`obscura_scrape` (disable with `nativeTools: false`).
+
+```ts
+import { createObscuraWebTools } from "@arnilo/prism-obscura";
+
+const web = createObscuraWebTools({ command: "/usr/local/bin/obscura" });
+agent.tools = [...agent.tools, ...web.tools];
+```
+
+- **Search truth**: `web_search` runs public-web search through one replaceable HTML
+  search profile (default: DuckDuckGo HTML endpoint). The extraction JavaScript is a
+  constant — the query travels only URL-encoded inside the search URL, never inside
+  evaluated source. Supply `searchProfile` to swap engines. Obscura's native
+  `browser_search` is in-page text search and is **not** exposed by this package.
+- **web_search / web_fetch** return the same normalized untrusted shapes as
+  [`@arnilo/prism-web-tools`](web-tools.md) (`provider: "obscura"`, citations,
+  `untrusted: true`); content is labeled untrusted external content.
+- **obscura_fetch**: one URL, bounded dump mode (`html|text|links|markdown|original`),
+  optional CSS selector (1-256 chars). No evaluation, screenshots, output paths, file
+  URLs, or private-network access.
+- **obscura_scrape**: batch of public URLs (deduplicated, capped) with a constant
+  default expression; Obscura enforces `--concurrency` itself. Custom expressions
+  require explicit `allowEval: true` and stay byte-capped. Input association is
+  preserved by index; missing rows surface as `{ url, error }` entries.
+- **Bounds**: query/result/batch/concurrency/output/eval byte caps, per-run timeout,
+  and child-process kill on timeout/abort (`DEFAULT_OBSCURA_WEB_LIMITS`,
+  `HARD_OBSCURA_WEB_LIMITS`). Malformed JSON, oversized output, and nonzero exits
+  fail closed with redacted diagnostics; nothing is retried.
+- **URL policy**: every URL is validated as a public HTTP(S) target (private/
+  loopback/metadata and credentialed URLs denied) before any child process starts.
+- Docker-style invocations work through `argsBefore` (e.g.
+  `["run", "--rm", "-i", "h4ckf0r0day/obscura"]`).
+- An opt-in live smoke test runs against a real installed binary with
+  `npm run test:live -w @arnilo/prism-obscura` plus `PRISM_LIVE_OBSCURA=1` and
+  `PRISM_OBSCURA_BIN=/path/to/obscura`.
+
+## Host conformance (one generic integration)
+
+`scripts/obscura-host-conformance.test.mjs` runs one shared fake-Obscura fixture —
+the same `ToolDefinition[]` with one read tool (`web_fetch`) and one mutating tool
+(`obscura_scrape`) — through every Prism host's public API: core agent/session
+execution, the Prism MCP server, the `createPrismHandler` server lifecycle, AG-UI
+MCP-tool injection, ACP fronting, workflow `toolNode`/`agentNode`s, supervisor
+children, and Antigravity delegated MCP exposure. It verifies host authorization
+and selection deny before execution, that no host needs an Obscura-specific branch,
+and that an aborted in-flight call settles and kills the owned child. Composition
+walkthrough: [`examples/obscura.ts`](../examples/obscura.ts).
+
+## Security
+
+Obscura's CDP and MCP HTTP endpoints have no built-in authentication. This package
+binds or connects to loopback by default. For remote deployments use an
+authenticating reverse proxy or network isolation
+(see [host security](host-security.md)).
+
+CLI-backed web tools land in a subsequent release
+(see `plans/039-Obscura-Full-Host-Support-And-Changed-Package-Release.md`).

package/docs/observability.md

@@ -4,13 +4,14 @@
 
 Prism exposes provider and tool timing through stable, metadata-only `AgentEvent` variants. Hosts subscribe via `session.subscribe()` or persist events through `RunLedger`. Core helpers build `ProviderTurnMetadata` and classify HTTP failures without echoing prompts, tool arguments, or credentials.
 
-Optional package `@arnilo/prism-observability-opentelemetry` maps those events to OpenTelemetry spans and low-cardinality metrics. OpenTelemetry is **not** a dependency of `@arnilo/prism`.
+Optional package `@arnilo/prism-observability-opentelemetry` maps those events to OpenTelemetry spans and low-cardinality metrics, and adapts `@arnilo/prism-rag`'s dependency-free telemetry seam (`createRagTelemetry()`) onto the same tracer. OpenTelemetry is **not** a dependency of `@arnilo/prism`.
 
 APIs:
 
 - `ProviderTurnMetadata`, `ToolExecutionMetadata` on `AgentEvent`
 - `createProviderTurnMetadata()`, `readProviderHttpStatus()` in `@arnilo/prism`
 - `createOpenTelemetryInstrumentation()`, `wrapOpenTelemetryApi()`, `createInMemoryTelemetry()` in `@arnilo/prism-observability-opentelemetry`
+- `createRagTelemetry()` in `@arnilo/prism-observability-opentelemetry` (RAG spans/events; see span tree below)
 - `handleRunFeedback()` / `handleEvaluation()` for explicit safe post-run projection
 
 ## When to use it
@@ -96,6 +97,21 @@ OpenTelemetry mapping (when enabled):
 | `handleRunFeedback` | active-run `prism.run.feedback` event or ended-run span | `prism.run.feedback` |
 | `handleEvaluation` | active-run `gen_ai.evaluation.result` event or ended-run span | `prism.run.evaluation` (`status`) |
 
+RAG span tree (`@arnilo/prism-rag` + `createRagTelemetry()`):
+
+| Span | Parent | Notes |
+| --- | --- | --- |
+| `rag_request` | host/chosen parent or root | One per `retrieveContext()`; carries `rag.top_k`, `rag.scope_count`, `rag.result_count`, `rag.index_generation` (single-scope only), scope/embedder id. `chunk_retrieved` events add `rag.chunk.tenant_id` + `rag.chunk.corpus_id`. |
+| `embedding.query` | `rag_request` | Embedder call for the query |
+| `retrieval.vector_search` / `retrieval.lexical` | `rag_request` | Present when the leg runs (lexical only when enabled and supported) |
+| `retrieval.fusion` | `rag_request` | RRF fusion of the legs; `rag.fused_candidates` count |
+| `retrieval.rerank` | `rag_request` | Only when a reranker is configured |
+| `prompt.assembly` | `rag_request` | Context/template rendering |
+| `rag_index` | host/chosen parent or root | One per `replaceSource()`/`indexChunks()`; `rag.chunk_count`, `rag.index_generation`, `rag.embedder_id`, `rag.source_id` |
+| `embedding.index` | `rag_index` | Embedder batch call; skipped when unchanged-content skip fires |
+
+`createRagTelemetry({ tracer, meter, attributeFilter? })` adapts the dependency-free `RagTelemetry` seam to a PrismTracer. Only the fixed span names and `rag.*`-shaped attribute keys pass through; anything else (including raw chunk text) is dropped before export. `attributeFilter` can further reduce or drop attributes.
+
 High-cardinality identifiers (`sessionId`, `runId`, `requestId`, `toolCallId`) are **span attributes only**, never metric labels.
 
 ## Request/response example
@@ -149,6 +165,10 @@ detach();
 telemetry.handleRunFeedback({ runId: result.runId, rating: 1, hasComment: true, tagCount: 1, scorerCount: 1, evaluationCount: 1 });
 telemetry.handleEvaluation({ runId: result.runId, name: "citation", status: "scored", score: 0.9, hasReason: true });
 console.log(traceId, memory.spans.map((span) => span.name));
+
+// RAG: attach the same tracer to retrieveContext via the dependency-free seam
+const ragTelemetry = createRagTelemetry({ tracer: memory.tracer, meter: memory.meter });
+const found = await retrieveContext("policy", { embedder, store, scope, telemetry: ragTelemetry }); // rag_request tree
 ```
 
 ## Extension and configuration notes

package/docs/performance.md

@@ -28,6 +28,47 @@ node scripts/benchmark-0.1.0.mjs --out scripts/benchmark-0.1.0.json
 PRISM_TEST_POSTGRES_URL="postgresql://…" node scripts/benchmark-0.1.0.mjs --out scripts/benchmark-0.1.0.json  # adds protected legs
 ```
 
+## Multi-agent runtime concurrency (phase 35)
+
+`node scripts/benchmark.mjs --scenario multi-agent-runtime` is network-free (mock providers, in-process memory stores, no credentials). It measures concurrent independent sessions (1/4/16/32), supervisor fan-out and saturation (32 attempted delegates vs `maxActiveChildren`), parallel workflow fan-out maps (8×20 ms items at concurrency 2, ≥1.75× vs sequential), parallel workflow agent nodes, in-run tool concurrency, and an abort storm. Each result row carries p50/p95, throughput, heap delta, queued/dropped events, peak active provider calls, completions, and abort settle. Ceilings live in `scripts/budgets.json#multiAgentRuntime` (sanity bounds, machine-dependent). Exhaustive 59-manifest classification and recorded numbers: [`docs/_evidence/phase35-ai-runtime-package-matrix.md`](./_evidence/phase35-ai-runtime-package-matrix.md). Schema/safety/invariants: `scripts/benchmark-multi-agent.test.mjs`. Fan-out row: 8×20 ms items at concurrency 2, ≥1.75× vs sequential, peak workers ≤ 2. Supervisor saturation: 32 attempted delegates vs `maxActiveChildren` 4, overflow rejected, `activeAfter` 0.
+
+```bash
+node scripts/benchmark.mjs --scenario multi-agent-runtime --out /tmp/prism-multi-agent.json
+```
+
+Recorded 2026-08-27, Node v24.19.0 / Linux x64, 5 warmups + 20 waves, 8 ms mock delay. 32 independent sessions p95 10.1 ms (vs 9.0 ms at n=1); supervisor cap-4 fan-out p95 9.4 ms; workflow 4 agent nodes at concurrency 2 p95 17.9 ms; 8 tools at concurrency 4 p95 17.4 ms; abort storm settled in 5.5 ms with zero leftover provider calls. Dropped events: 0 on every row. Task 6 three-run median p95 (2026-08-28, same fixture): sessions 9.9/9.9/10.6/12.0, supervisorFanOut 10.4, supervisorSaturation 10.3, workflowFanOut 84.5 (1.87×, peak workers 2), workflowAgentNodes 19.7, toolConcurrency 19.1, abortStorm 3.3 — all under `scripts/budgets.json#multiAgentRuntime` ceilings. Protected PostgreSQL (`PRISM_TEST_POSTGRES_URL`) skipped on this host; `release:gate` blocked until durable evidence exists. Memory-store router 16/32-worker reservations do not oversubscribe.
+
+## Large-history and streamed-delta hot paths (plan 036)
+
+The `multi-agent-runtime` scenario also covers 10,000 context-budget history rows and
+5,000 streamed provider deltas. `applyContextBudget` measures the keep-set once,
+advances a history head cursor during eviction, and slices the retained suffix once;
+it never front-mutates the history array. Runtime request/response limit accounting
+uses `Buffer.byteLength(JSON.stringify(value), "utf8")`, so UTF-8 byte limits do not
+allocate an encoded buffer per provider event.
+
+Run with the existing network-free fixture:
+
+```bash
+node scripts/benchmark.mjs --scenario multi-agent-runtime
+```
+
+Recorded 2026-08-28 on Node v24.19.0 / Linux x64, 5 warmups + 20 measured waves.
+`contextBudget-10k-history` completed with zero history remaining; its p50/p95 were
+2.481/3.708 ms and peak measured heap delta was 7,748,848 bytes. `provider-5k-deltas`
+processed 5,000 deltas (320,015 serialized response bytes) at 4.253/5.847 ms p50/p95
+with a 4,414,944-byte peak measured heap delta. These are local comparison evidence,
+not portable SLOs; ceilings are in `scripts/budgets.json#multiAgentRuntime`.
+
+`Buffer.byteLength` counts encoded bytes rather than JavaScript string length. A
+serialized provider event at the exact response-byte cap succeeds; one byte below it
+fails closed, including multibyte Unicode deltas. Context-budget omission order and
+newest-history preservation remain covered by the root context-budget tests.
+
+## Current-line root artifact diet
+
+`npm pack --dry-run --json` on `@arnilo/prism` is gated by `scripts/budget-gate.test.mjs` against `scripts/budgets.json#root` (±5%). Repository-only history stays out of the tarball: `docs/_evidence/**`, `docs/release-*-evidence.md`, `docs/api-page-template.md`, `dist/__tests__`, and `*.map`. Every page linked from shipped `docs/index.md` must be in the pack. Recorded 2026-08-27: **923,045 packed / 3,149,665 unpacked / 375 files** (226 `dist` js+d.ts, 124 index-linked docs, 25 other). 0.1.0 freeze 713,454 / 293 stays historical.
+
 ## 0.1.4 tree-shake measurement (static-reachability proxy)
 
 The 0.1.4 god-module split (agents/contracts → per-concern modules behind barrels) is
@@ -89,9 +130,10 @@ file count fail above baseline × 1.05. Labels: **network-free** = runs in
 | reconnectCatchup | 8.374 | 100 | distributed events (0.0.24) | protected |
 
 Install/startup rows (same helpers as the budget gate — no duplicate
-measurement): startup import 41.7 ms (ceiling 250 ms); root packed 711,755
-bytes vs baseline 678,541 (+5%, tolerance 5%); root file count 295 vs 293
-(+5%). Storage-growth rows and query plans from the protected legs are in the
+measurement): startup import 41.7 ms (ceiling 250 ms). The recorded 0.1.0.json
+pack rows (711,755 bytes / 295 files vs freeze 678,541 / 293) stay historical.
+Live root pack is the current-line diet in `scripts/budgets.json#root` (see below).
+Storage-growth rows and query plans from the protected legs are in the
 recorded JSON (`storageBeforeCleanup` / `storageAfterCleanup` per leg).
 
 Conformance companions: `scripts/phase8–11-conformance.test.mjs` plus the
@@ -375,7 +417,7 @@ On default overflow, the affected subscriber receives one `event_subscriber_over
 }
 ```
 
-`drop_oldest` keeps the newest queued events. `drop_newest` ignores incoming events while the queue is full. These policies are live-view policies only; they do not affect `RunLedger` writes or stored session entries.
+`drop_oldest` keeps the newest queued events. `drop_newest` ignores incoming events while the queue is full. These policies are live-view policies only; they do not affect `RunLedger` writes or stored session entries. Graceful `createEventMultiplexer().close()` (and abort) stop new publishes/sources and drain already-queued events within `maxQueuedEvents` before the subscriber completes. Overflow `close` still drops the backlog, emits one overflow notice, and terminates.
 
 ## Request/response example
 
@@ -707,6 +749,18 @@ Enterprise governance and connector caps (defaults / hard). Timings: `node scrip
 
 Offline behavior tests (identity propagation, policy export, router deny paths, fake CLI argv) are release gates; live tenant canaries remain operator-gated.
 
+### 0.3.x Phase 39 Obscura browser-engine envelopes (2026-08-29)
+
+`@arnilo/prism-obscura` binary-backed legs, network-free, driven by a deterministic fake CLI: `node scripts/benchmark-obscura.mjs` (3 runs, medians vs reviewed ceilings; artifact `scripts/benchmark-obscura.json`). Startup leg probes SIG-0 liveness after spawn — a real host waits on its readiness endpoint inside the same bound.
+
+| Leg | Median (3 runs) | Ceiling | Notes |
+| --- | --- | --- | --- |
+| Managed startup (`spawnObscuraProcess` + `waitReady`) | ~0.02 ms | 250 ms | fake child; machine-dependent sanity bound, catches catastrophic lifecycle regression |
+| Bounded CLI `web_search` call | ~20 ms | 100 ms | one `runObscuraCli` round trip through the public tool surface |
+| Group close (SIGTERM drain) | ~0.6 ms | 250 ms | idempotent group-wide close; real children exit on signal |
+
+No new release gate: the ceilings are evidence, not gates. Concurrent-resource evidence is behavioral, not timing: the MCP bridge serializes mutations (one live page), and abort tests prove an aborted in-flight call settles and kills the owned child with zero leaked processes (`scripts/obscura-host-conformance.test.mjs` abort leg; process/web suite timeout/abort-kill tests). Packed tarball 34.4 kB / 16 files; the package installs no binary, image, or browser.
+
 ## Related APIs
 
 - [Agent events](agent-events.md): `SubscribeOptions` and `event_subscriber_overflow` event details.

package/docs/ponytail.md

@@ -106,7 +106,7 @@ See `examples/caveman-ponytail.ts` for combined Caveman + Ponytail progressive d
 - Import alone registers nothing (`sideEffects: false`); no timers, watchers, network, or shell scripts.
 - Upstream hook modules load via `createRequire` from resolved root — instruction strings are not forked in Prism.
 - Mode restore scans `getEntries()` for latest `data.type === "ponytail-mode"` (OM attach pattern).
-- `ponytail-subagent` hook is not wired; nested-agent behavior is host responsibility.
+- `ponytail-subagent` hook is not wired; nested-agent behavior is host responsibility. When hosts wire the upstream hook, `PONYTAIL_SUBAGENT_MATCHER` accepts only the documented safe subset — `"explore|general"` (any literal substring) or `"^general$"` (exact), case-insensitive, max 256 chars. No `RegExp` is compiled from the environment, so arbitrary regex (including catastrophic nested quantifiers) is never evaluated; unset/invalid patterns inject into every subagent.
 - No TUI statusline scripts; use `ponytail status` command or extension events.
 - Not included in `@arnilo/prism-code` or `@arnilo/prism-sdk` profiles — opt-in install only.
 

package/docs/provider-caching.md

@@ -8,7 +8,7 @@ Provider caching documents Prism's cache intent surface:
 - Legacy aliases `cacheKey` and `cacheRetention`, still supported for backwards compatibility.
 - `PromptCacheBreakpoint` locations for reusable prompt regions.
 - `ModelCacheCapabilities` for model/provider cache support metadata.
-- Shared helpers: `sanitizeCacheKey`, `mapCacheRetention`, `applyCacheControl`, `cacheHitRate`, `cacheSavings`, and `cacheUsageReport`.
+- Shared helpers: `sanitizeCacheKey`, `mapCacheRetention`, `applyCacheControl`, `resolveBreakpoint`, `canonicalizeJsonSchema`, `cacheHitRate`, `cacheSavings`, and `cacheUsageReport`.
 
 Cache hints are best-effort. They describe intent; providers decide whether their native API can use them. Prism does not guarantee cache hits.
 
@@ -17,7 +17,7 @@ Cache hints are best-effort. They describe intent; providers decide whether thei
 Use this page when a host or provider package needs to:
 
 - Mark stable system prompts, tools, context, or messages as cacheable.
-- Opt into cache-aware default input ordering so stable attachments/resources, summaries, and prior history form a reusable prefix before the current user turn.
+- Use cache-aware default input ordering so stable instructions, attachments/resources, summaries, and prior history form a reusable prefix before the current user turn.
 - Carry a stable cache key across turns without putting provider-specific fields in core.
 - Read `ModelConfig.cache` to decide whether to map hints to implicit caching, key-based caching, cache-control breakpoints, provider-specific caching, or no caching.
 - Compute normalized cache diagnostics from `Usage.cacheReadTokens` / `Usage.cacheWriteTokens`, including providers that only report reads.
@@ -60,13 +60,15 @@ Cache helpers return plain data:
 | `sanitizeCacheKey(value, maxLength)` | Safe key string or `undefined`. |
 | `mapCacheRetention(retention, model)` | `"short"`, `"long"`, or `undefined`. |
 | `applyCacheControl(messages, breakpoints, options)` | New message array with `cache_control: { type: "ephemeral" }` on selected message anchors. |
+| `resolveBreakpoint(messages, breakpoint)` | Message index for a `PromptCacheBreakpoint` (`-1` when unresolved); shared anchor selection for `applyCacheControl` and OpenAI explicit breakpoints. |
+| `canonicalizeJsonSchema(value)` | Clone with sorted object keys and `required` names; semantic arrays stay ordered. Used by first-party tool serializers. |
 | `cacheHitRate(usage)` | Cached input ratio or `undefined`. |
 | `cacheSavings(usage, model)` | Estimated read-token savings or `undefined` without pricing. |
 | `cacheUsageReport(usage, model?)` | Normalized read/write tokens, hit rate, estimated savings, and currency when available; `undefined` when no usage is supplied. |
 
 Provider events do not change. Cache accounting stays in normalized `Usage.cacheReadTokens` and `Usage.cacheWriteTokens`.
 
-For stable-prefix payloads, `inputLayout: "cache_aware"` is the default on the default input builder, `assembleProviderInput()`, `AgentConfig`, and `RunOptions`; set `inputLayout: "legacy"` to restore the prior order. The default prompt builder already places context, selected skills, and tool declarations before input messages; cache-aware input ordering then places attachments/resources, summaries, prior history, and pending tool results before the current user suffix. The prefix is byte-stable only when those stable inputs are unchanged; Prism still does not guarantee provider cache hits.
+For stable-prefix payloads, `inputLayout: "cache_aware"` is the default on the default input builder, `assembleProviderInput()`, `AgentConfig`, and `RunOptions`; set `inputLayout: "legacy"` to restore the prior order. The default prompt builder's cache-aware order is leading system instructions → resolved context blocks → selected/progressively disclosed skills → fallback text tool declarations → attachments/resources → summaries → prior history → pending tool results → current input. Declared tool schemas remain in `ProviderRequest.tools` and are never granted by prompt middleware. First-party tool serializers run `canonicalizeJsonSchema` so property insertion order cannot break that prefix. Changing only current input preserves the serialized message prefix before the final user suffix; changing dynamic context or loaded skills changes only from its own boundary onward, while tool schemas remain independently stable. The prefix is byte-stable only when those stable inputs are unchanged; Prism still does not guarantee provider cache hits.
 
 ## Request/response example
 
@@ -135,7 +137,7 @@ Provider request policies can set `ProviderRequestOptions.cache` or the legacy `
 
 | `ModelCacheCapabilities.kind` | Typical mapping |
 | --- | --- |
-| `implicit` | No request mutation; provider caches automatically. |
+| `implicit` | No request mutation; provider caches automatically. Conformance (`assertNoForeignCacheFields`) proves the serialized body carries no cache wire fields. |
 | `openai_key` | Send sanitized cache key and mapped retention where supported. |
 | `cache_control` | Use `applyCacheControl()` on provider-native message anchors. |
 | `provider_specific` | Provider package uses `compat`/native options intentionally. |
@@ -145,8 +147,8 @@ Provider request policies can set `ProviderRequestOptions.cache` or the legacy `
 
 | Provider package | Cache kind | Explicit cache hints | Multi-turn reuse notes | Caveats |
 | --- | --- | --- | --- | --- |
-| `@arnilo/prism-provider-openai` | `openai_key` | Sends sanitized `prompt_cache_key`; `prompt_cache_retention: "24h"` only when the model declares `longRetention`. | Stable cache key + stable prefix can improve reuse. | Best-effort only; `"short"`/`"none"` omit retention. |
-| `@arnilo/prism-provider-anthropic` | `cache_control` | Marks only selected Anthropic message anchors; `"long"` maps to documented `ttl: "1h"`. | Keep selected anchors stable. | Best-effort; never stamp every block. |
+| `@arnilo/prism-provider-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-provider-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-provider-google` | none | Sends no Prism cache marker. | Host/model may have upstream behavior. | Gemini cache controls are not mapped in this package. |
 | `@arnilo/prism-provider-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-provider-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. |
@@ -156,7 +158,7 @@ Provider request policies can set `ProviderRequestOptions.cache` or the legacy `
 | `@arnilo/prism-provider-ai-sdk` | host-owned | No Prism cache payload; host `LanguageModelV4` owns upstream caching. | Host model/provider decides cache keys, breakpoints, and sticky routing. | Adapter maps `inputTokens.cacheRead`/`cacheWrite` from `finish.usage` only; does not invent cache fields. |
 | `@arnilo/prism-provider-alibaba` | implicit by default, optional `cache_control` | DashScope implicit prefix caching is automatic; opt-in `cache_control: {"type":"ephemeral"}` markers only on caller-selected `cache.breakpoints`, capped at 4. | Keep selected anchors and prior history stable; each cached prefix needs ≥1024 tokens and lives ~5 minutes upstream. | Best-effort and model-dependent; `cached_tokens`→read, `cache_creation_input_tokens`→write. |
 | `@arnilo/prism-provider-ollama` | `implicit` | No `cache_control`, `cacheKey`, `prompt_cache`, or `cacheRetention` payload; Ollama KV/prefix caching is automatic with no request knob. | Resend unchanged prior history for implicit KV reuse. | Best-effort only; Ollama reports no cached-token count, so `Usage.cacheReadTokens` stays `undefined`. |
-| `@arnilo/prism-provider-deepseek` | `implicit` | No `cache_control` / `prompt_cache_key`; tools schemas are key-sorted so the prefix stays byte-stable. | Resend unchanged history from token 0; append only the new turn. Thinking-on strips temperature/top_p/penalties so they cannot break the prefix. | Best-effort prefix units (~1024 practical min). `prompt_cache_hit_tokens` → `cacheReadTokens`. |
+| `@arnilo/prism-provider-deepseek` | `implicit` | No `cache_control` / `prompt_cache_key`; tool `parameters` go through shared `canonicalizeJsonSchema`. | Resend unchanged history from token 0; append only the new turn. Thinking-on strips temperature/top_p/penalties so they cannot break the prefix. | Best-effort prefix units (~1024 practical min). `prompt_cache_hit_tokens` → `cacheReadTokens`. |
 | `@arnilo/prism-provider-xai` | `implicit` | No `prompt_cache_key`. Package-local `x-grok-conv-id` is `sanitizeCacheKey(cache.key ?? cacheKey ?? sessionId, 128)`. | Same server + unchanged message prefix. Replay `reasoning_content` on reasoning models or the prefix breaks. | Conv-id is never a credential or SuperGrok token. Omitted when `cache.mode` is `off` or `cacheRetention` is `none`. `cached_tokens` → `cacheReadTokens` (inclusive or exclusive reports kept as-is). |
 | `@arnilo/prism-provider-clinepass` | `implicit` | No `cache_control` / `prompt_cache_key`. Gateway-owned prefix cache. | Resend unchanged prior history. Stream only. | Best-effort and backend-dependent (`cline-pass/*` slugs). `cached_tokens` / `prompt_cache_hit_tokens` map when present. |
 | `@arnilo/prism-provider-azure` | none | No Prism cache mapping. | Endpoint/model-specific. | Host owns Azure cache policy. |
@@ -165,11 +167,11 @@ Provider request policies can set `ProviderRequestOptions.cache` or the legacy `
 
 Detailed first-party provider notes:
 
-- OpenAI Responses (`@arnilo/prism-provider-openai`): `kind: "openai_key"`. Sanitizes/clamps `prompt_cache_key` to 64 chars; `"long"` retention maps to `prompt_cache_retention: "24h"` only when the model declares `cache.longRetention`; `"short"`/`"none"` omit the field. GPT-5.6+ official docs use `prompt_cache_options` / breakpoints instead of retention — `listOpenAIModels` sets `longRetention: false` for those ids. `input_tokens_details.cached_tokens` maps to `Usage.cacheReadTokens`.
+- OpenAI Responses (`@arnilo/prism-provider-openai`): `kind: "openai_key"`. Sanitizes/clamps `prompt_cache_key` to 64 chars; pre-GPT-5.6 models (`cache.longRetention: true`) map `"long"` retention to `prompt_cache_retention: "24h"`; GPT-5.6+ models (`cache.explicitBreakpoints: true`) map `cache.breakpoints`/`cache.mode: "on"` to `prompt_cache_options: { mode: "explicit" }` plus `prompt_cache_breakpoint: { mode: "explicit" }` markers on selected message anchors (≤4 writes; the only TTL `"30m"` is the default, so none is emitted). Resolved cache fields win over caller `extra`. `input_tokens_details.cached_tokens`/`cache_write_tokens` map to `Usage.cacheReadTokens`/`Usage.cacheWriteTokens`.
 - OpenAI-compatible Chat Completions adapter: minimal scope, sends no cache payload; see [OpenAI-compatible provider](providers/openai-compatible.md).
-- Anthropic (`@arnilo/prism-provider-anthropic`): `kind: "cache_control"`; selected Anthropic message anchors receive `cache_control` and eligible long retention maps to `ttl: "1h"`. Cache read/create usage maps to normalized cache read/write tokens.
+- Anthropic (`@arnilo/prism-provider-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-provider-google`): sends no Prism cache-control payload. Do not infer cache hits or cache token counts from absent Gemini fields.
-- OpenRouter (`@arnilo/prism-provider-openrouter`): `kind: "cache_control"`. Sanitizes/clamps `session_id`/`X-Session-Id` to 256 chars for sticky routing; 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-provider-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.
 - OpenCode Go (`@arnilo/prism-provider-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`.
 - Z.AI (`@arnilo/prism-provider-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-provider-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.
@@ -177,7 +179,7 @@ Detailed first-party provider notes:
 - AI SDK adapter (`@arnilo/prism-provider-ai-sdk`): **host-owned**. Sends no Prism cache payload; the supplied `LanguageModelV4` and its upstream provider own request caching. Maps AI SDK v4 `finish.usage.inputTokens.cacheRead`/`cacheWrite` to `Usage.cacheReadTokens`/`cacheWriteTokens`. No `list*Models()` export.
 - Alibaba Cloud (`@arnilo/prism-provider-alibaba`): implicit by default, optional `cache_control`. DashScope implicit prefix caching is automatic (no marker); explicit opt-in `cache_control: {"type":"ephemeral"}` markers apply only to selected breakpoints when `ModelConfig.cache.kind: "cache_control"` and the caller supplies breakpoints, capped at 4 (each prefix ≥1024 tokens, ~5 minute TTL). `prompt_tokens_details.cached_tokens`/`cache_creation_input_tokens` map to `Usage.cacheReadTokens`/`cacheWriteTokens`. Caller-gated `listAlibabaModels` against OpenAI-compatible `GET {base}/models`.
 - Ollama (`@arnilo/prism-provider-ollama`): `kind: "implicit"`. Ollama reuses its KV/prompt cache automatically; there is no request knob and no wire marker, so Prism never emits `cache_control`. Ollama reports no cached-token count, so `Usage.cacheReadTokens` is intentionally left `undefined` (not `0`). Caller-gated `listOllamaModels` against OpenAI-compatible `GET {base}/models`.
-- DeepSeek (`@arnilo/prism-provider-deepseek`): `kind: "implicit"`. Official disk prefix cache is automatic (byte-identical prefix from token 0). Adapter sends no cache payload; tool `parameters` are canonicalized for stable JSON key order. `prompt_cache_hit_tokens` maps to `Usage.cacheReadTokens`. Caller-gated `listDeepSeekModels`.
+- DeepSeek (`@arnilo/prism-provider-deepseek`): `kind: "implicit"`. Official disk prefix cache is automatic (byte-identical prefix from token 0). Adapter sends no cache payload; tool `parameters` use shared `canonicalizeJsonSchema` (object keys + unordered `required` only; `enum`/`prefixItems`/`examples` keep caller order). `prompt_cache_hit_tokens` maps to `Usage.cacheReadTokens`. Caller-gated `listDeepSeekModels`.
 - xAI (`@arnilo/prism-provider-xai`): `kind: "implicit"`. Automatic prefix cache. Sticky `x-grok-conv-id` is a sanitized session/cache key (128 chars), never an OAuth access token. Reasoning models must replay `reasoning_content`. `prompt_tokens_details.cached_tokens` maps to `Usage.cacheReadTokens`. Caller-gated `listXaiModels`.
 - ClinePass (`@arnilo/prism-provider-clinepass`): `kind: "implicit"`. No explicit cache payload; multi-backend gateway may report `cached_tokens` or `prompt_cache_hit_tokens`. Static `cline-pass/*` catalog only — no `listClinePassModels`.
 - Azure, Bedrock, and Vertex: their OpenAI-compatible packages intentionally emit no Prism cache fields. Endpoint/model-specific cache controls remain host-owned rather than guessed from another provider family.

package/docs/provider-conformance.md

@@ -12,6 +12,9 @@ Exported from `@arnilo/prism/testing/provider-conformance`:
 - `assertToolCallDeltasReconstruct(events, expected)`
 - `assertUsageAccounting(events, expected)`
 - `assertSerializedRequestCoversContent(request, body, options?)`
+- `assertCanonicalToolParameters(serialized, original)`
+- `assertNoForeignCacheFields(body, allowed?)`
+- `assertNoFetches(calls)`
 - `assertProviderOwnedHeadersWin(captured, options)`
 - `assertNoSecretLeak(events, secrets)`
 
@@ -68,6 +71,9 @@ Helpers accept normal `AIProvider`, `ProviderRequest`, `ProviderEvent`, `Usage`,
 - `assertAbortIsObserved()` passes an already-aborted signal and expects provider generation to reject. This is the supported timeout primitive; use a host abort controller or `RunOptions.signal`.
 - `assertToolCallDeltasReconstruct()` rebuilds streamed `tool_call_delta` fragments into tool calls and validates expected id/name/arguments. Malformed JSON with id+name present yields `argumentsError` (no throw); missing id/name throws typed `incomplete_delta`. The runtime uses the same reconstruction before tool execution when a provider streams deltas.
 - `assertUsageAccounting()` finds `usage` or `done.usage` and checks selected token fields including `cacheReadTokens` and `cacheWriteTokens`. This is the provider-neutral check for normalized cache read/write token extraction; every first-party provider package exercises it against server-specific fields (`cached_tokens`, `cache_read_input_tokens`, etc.).
+- `assertCanonicalToolParameters()` checks a serialized tool schema matches `canonicalizeJsonSchema(original)` so property insertion order and `required` name order cannot drift on the wire while `enum`/`prefixItems`/`examples` stay caller-ordered.
+- `assertNoForeignCacheFields()` fails when a request body carries a cache wire field the route does not document (`cache_control`, `prompt_cache_*`, `cachedContent`, `cachePoint`); pass documented fields in `allowed` for routes that opt in (Alibaba/OpenRouter markers, Gemini `extra.cachedContent`). Implicit-cache providers must serialize no foreign cache fields — implicit caching works by byte-stable prefix reuse, not request payloads.
+- `assertNoFetches()` fails when a provider performed network calls outside caller-gated discovery/stream; provider construction and `setup()` must be network-free.
 - `assertSerializedRequestCoversContent()` scans a serialized provider request body for primitive canaries from each Prism content block and fails if any supported block type is silently dropped. Provider-valid transcripts place assistant `tool_call` messages before matching role `tool` `tool_result` messages; runtime, cache-aware input layout, and observational-memory worker loops preserve that order before serialization.
 - `assertProviderOwnedHeadersWin()` compares captured request headers against the provider's authoritative owned header values and a caller-supplied header bag; it fails if any owned header (`authorization`, `content-type`, session/security headers) was overridden by caller headers, and also fails if a non-owned caller header was dropped. This is the provider-neutral check that caller `ProviderRequest.options.headers` cannot hijack provider credentials or sessions; every first-party provider package exercises it.
 - `assertNoSecretLeak()` stringifies all collected events and fails if any known secret string is present.

package/docs/provider-packages.md

@@ -115,7 +115,7 @@ Every package remains explicit, setup-zero-fetch, and late-credential-bound. `Mo
 
 Every first-party provider package hardens prompt-cache behavior so it cannot emit invalid cache retention values or over-broad cache-control markers, and so provider-owned `authorization`/session/security headers cannot be overridden by caller `ProviderRequest.options.headers`. Cache behavior is provider-specific and best-effort: OpenAI/OpenRouter use explicit hints, NeuralWatt/Z.AI/DeepSeek/ClinePass use implicit caching, xAI adds a sanitized `x-grok-conv-id`, and OpenCode Go/Kimi are route/model-dependent. See [Provider caching](provider-caching.md#per-provider-cache-behavior) for the canonical explicit/implicit matrix.
 
-- **OpenAI** (`kind: openai_key`): `prompt_cache_key` is sanitized and clamped to 64 chars; `prompt_cache_retention` is emitted as `24h` only when the model declares `cache.longRetention`, and omitted for `short`/`none` (the API only accepts absent or `24h`). `prompt_tokens_details.cached_tokens` maps to `Usage.cacheReadTokens`.
+- **OpenAI** (`kind: openai_key`): `prompt_cache_key` is sanitized and clamped to 64 chars. Pre-GPT-5.6 models emit `prompt_cache_retention: "24h"` when the model declares `cache.longRetention`; GPT-5.6+ models (`cache.explicitBreakpoints`) map `cache.breakpoints` / `cache.mode: "on"` to `prompt_cache_options: { mode: "explicit" }` with `prompt_cache_breakpoint` markers on selected anchors. `input_tokens_details.cached_tokens`/`cache_write_tokens` map to `Usage.cacheReadTokens`/`Usage.cacheWriteTokens`.
 - **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`.

package/docs/provider-primitives.md

@@ -8,7 +8,7 @@ Implementation is **shipped** for transport and OpenAI serialization primitives
 
 ## When to use it
 
-- **Provider package authors** implementing or migrating a first-party adapter should import shared primitives from `@arnilo/prism/providers/transport` and `@arnilo/prism/providers/openai` instead of copying `sse.ts`, `safeText`, `parseArgs`, or serializers.
+- **Provider package authors** implementing or migrating a first-party adapter should import shared primitives from `@arnilo/prism/providers/transport`, `@arnilo/prism/providers/openai`, and `@arnilo/prism/providers/schema` instead of copying `sse.ts`, `safeText`, `parseArgs`, serializers, or JSON Schema key-sorting.
 - **Host apps** choose native structured output via `ProviderRequestOptions.structuredOutput` when the model declares support; otherwise they keep the artifact generate→validate→revise loop ([Structured output](structured-output.md)).
 - **Operators** enable observability through extended agent events and the optional OpenTelemetry adapter package ([Observability](observability.md)).
 
@@ -190,6 +190,19 @@ export function assertOpenAIChatMessage(message: unknown, path: string): asserts
 
 `src/providers/openai-compatible.ts` becomes a thin adapter over these helpers in Task 2.
 
+### `@arnilo/prism/providers/schema` — **shipped**
+
+Deterministic JSON Schema clone for tool/function parameters. Sorts object keys and unordered `required` names. Leaves semantic arrays (`prefixItems`, `examples`, `enum`, tuple `items`) in caller order. Does not resolve `$ref`, mutate input, or enforce schema bounds.
+
+```ts
+import { canonicalizeJsonSchema } from "@arnilo/prism/providers/schema";
+
+canonicalizeJsonSchema({ required: ["b", "a"], properties: { b: {}, a: {} } });
+// keys and required names stable; ordered schema arrays remain ordered
+```
+
+`serializeOpenAITool` and first-party native `toTool` mappers reuse this helper so logically identical schemas stringify identically.
+
 ### Structured output capability (Task 4 — **shipped**)
 
 ```ts
@@ -286,7 +299,7 @@ Every migrated provider must pass this shared matrix (implemented in Task 1 test
 ## Related APIs
 
 - [Provider layer](provider-layer.md): registry, mock provider, event helpers
-- [Provider conformance](provider-conformance.md): stream order, abort, header ownership
+- [Provider conformance](provider-conformance.md): stream order, abort, header ownership, canonical tool schemas
 - [OpenAI-compatible provider](providers/openai-compatible.md): reference adapter subpath
 - [Structured output](structured-output.md): artifact loop fallback
 - [Provider request policies](provider-request-policies.md): cache and request hooks

package/docs/providers/ai-sdk.md

@@ -112,7 +112,7 @@ console.log(result.text);
 
 There is **no Prism-side model catalog** and **no `list*Models()` export** by design. Hosts supply a ready-made `LanguageModelV4` instance (typically from `@ai-sdk/openai`, `@ai-sdk/anthropic`, AI Gateway, or a custom provider) and register a matching `ModelConfig` for capabilities/limits.
 
-Prism setup remains network-free: `createAiSdkProvider` only wraps the supplied model and never fetches catalogs or credentials.
+Prism setup remains network-free: `createAiSdkProvider` only wraps the supplied model and never fetches catalogs or credentials. Stream and abort behavior are conformance-proven: an already-aborted signal fails fast as an `error` event, a host stream ending without a `finish` part fails loudly (typed `AiSdkProviderError { code: "model_error" }`) instead of synthesizing a `done`, and unmappable stream parts fail closed.
 
 ## Prompt caching
 

package/docs/providers/anthropic.md

@@ -41,7 +41,7 @@ Featured offline aliases: `claude-opus-4-8`, `claude-sonnet-5`, `claude-haiku-4-
 | Surface | Behavior |
 | --- | --- |
 | Stream | Prism text, thinking deltas, tool-call delta/final, usage (incl. cache read/create when present), `done`, redacted `error`. |
-| Cache | Featured models use `cache.kind: "cache_control"`; markers on selected breakpoints (`long` → `ttl: "1h"`). |
+| Cache | Featured models use `cache.kind: "cache_control"`; markers on selected breakpoints (`long` → `ttl: "1h"`). A `system_prompt` breakpoint serializes `system` as native text blocks with the marker (plain string otherwise). |
 | Thinking | Model-family aware (`adaptive` vs `enabled`+`budget_tokens`); helpers `anthropicThinking` / `anthropicEffort` / `anthropicPreserveThinking`. |
 | Auth | `api_key` for provider id; provider-owned `content-type`, `x-api-key`, `anthropic-version` win over caller headers. No OAuth descriptor or subscription adapter is registered. |
 

package/docs/providers/azure.md

@@ -64,6 +64,7 @@ Register via `createExtensionKernel().load([createAzureOpenAIProviderPackage(...
 - Endpoint host is never rewritten to public DNS.
 - Errors redact credential values via shared transport helpers.
 - 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`.
 
 ## Related APIs
 

package/docs/providers/bedrock.md

@@ -62,6 +62,7 @@ Uses Bedrock’s OpenAI-compatible runtime route (not Converse eventstream). Hos
 - No AWS SDK; package-local SigV4 only for `bedrock` service.
 - Input headers are normalized once before signing: names are lowercased and duplicate-case keys merge last-wins, so the canonical request always matches the signed header list (no duplicate-case mismatch); query parameters are canonicalized sorted by encoded key then value.
 - Private endpoint hosts are not rewritten to public DNS.
+- 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; native Bedrock caching (`Converse cachePoint`) is intentionally unsupported on the OpenAI-compatible route — no cache wire fields are emitted even when the request carries Prism cache hints.
 - Credential secrets are redacted from provider errors.
 - No credential prefetch at import.
 

package/docs/providers/kimi.md

@@ -179,7 +179,8 @@ await kernel.load([
 - When opted in, `cache_control: { type: "ephemeral" }` markers apply only to
   caller-selected `ProviderRequestOptions.cache.breakpoints` on the last content
   block of each selected message. `cacheRetention: "long"` adds `ttl: "1h"` when
-  the model allows long retention.
+  the model allows long retention. A `system_prompt` breakpoint serializes
+  `system` as native text blocks with the marker (plain string otherwise).
 - The Moonshot Open Platform route never receives Anthropic `cache_control` fields.
 - Coding usage: `cache_read_input_tokens` → `Usage.cacheReadTokens`,
   `cache_creation_input_tokens` → `Usage.cacheWriteTokens`.