@arnilo/prism 0.0.4 → 0.0.6

package/docs/compaction-llm.md

@@ -25,15 +25,16 @@ Key exports:
 | Field | Purpose |
 | --- | --- |
 | `provider` / `summaryProvider` | Explicit `AIProvider`, or factory receiving a resolved credential. |
-| `model` / `summaryModel` | Explicit summary `ModelConfig`. |
+| `model` / `summaryModel` | Summary `ModelConfig`. `summaryModel` wins; `model` is the session/host fallback via `resolveUseCaseModel`. See [Use-case model selection](use-case-model-selection.md). |
 | `credential`, `credentialRequest` | Optional per-call credential resolution for provider factories. |
 | `providerOptions` | Generic `ProviderRequest.options`, including cache fields. |
 | `providerRequestPolicies` | Optional Prism provider request policies applied before the summary call. |
 | `customInstructions` | Additional summary focus appended to prompts. |
-| `thinkingLevel` | Passed as `ProviderRequest.options.extra.thinkingLevel`. |
-| `reserveTokens` | Output budget basis; defaults to `16384`. |
+| `thinkingLevel` | Mapped into `ProviderRequest.options.compat` via `applyThinkingLevel` / `thinkingFamilyForModel` (not inert `extra.thinkingLevel`). See [Thinking and reasoning](thinking-and-reasoning.md). |
+| `reserveTokens` | Output budget basis; defaults to `16384`, hard cap `131072`. |
 | `keepRecentTokens` | Approximate recent-token budget; defaults to `20000`. |
-| `maxSummaryTokens` / `maxOutputTokens` | Computes the summary output budget, writes it to `summaryModel/model.parameters.maxTokens`, and truncates oversized collected summaries. First-party providers serialize that generic field to their real request field (`max_output_tokens` for OpenAI Responses, `max_tokens` for OpenAI-compatible/Anthropic-style providers). |
+| `maxSummaryTokens` / `maxOutputTokens` | Summary retention/request ceiling; default `16384`, hard cap `131072`. `maxSummaryTokens` wins over the compatibility alias. The finite value is written to `model.parameters.maxTokens`; first-party providers map it to their wire field. |
+| `maxErrorBytes` | Retained provider/factory/policy error detail; default `1024`, hard cap `8192`, UTF-8-safe and known-secret redacted. |
 | `maxToolResultChars` | Tool-result JSON truncation limit; defaults to `2000`. |
 | `trackFileOperations`, `includeFileOperations` | Control file path extraction and final summary blocks. |
 | `secrets` | Exact strings to redact from serialized prompts and final summaries. |
@@ -64,7 +65,8 @@ const strategy = createLlmCompactionStrategy({
   model: { provider: "openai", model: "gpt-4.1-mini" },
   keepRecentTokens: 20_000,
   reserveTokens: 16_384,
-  maxOutputTokens: 800,
+  maxSummaryTokens: 800,
+  maxErrorBytes: 1_024,
   providerOptions: { cacheRetention: "short" },
   customInstructions: "Focus on current files and failing tests.",
 });
@@ -102,10 +104,18 @@ const agent = createAgent({ model, provider, compaction: { strategy, thresholdEn
 Registration only contributes an inert strategy. The host must resolve and pass it to runtime config.
 
 ## Security and performance notes
-Preparation is O(n) over branch entries and uses only arrays, strings, and JSON serialization. Output-budget calculation is O(1) and does not add an extra summarization call. The strategy makes only the needed provider call(s): one history summary plus one split-turn prefix summary when needed. It does not discover credentials, read files, start background jobs, or add provider SDK dependencies. Redaction is exact-string only; pass every known secret that may appear in history or provider output.
+Preparation is O(n) over branch entries and uses only arrays, strings, and JSON serialization. Limit options must be positive safe integers at or below their hard caps and reject during strategy creation. Missing output options use a 16,384-token summary ceiling; reserve ratio/model metadata may narrow the provider request, never remove its finite `maxTokens`. A request policy that replaces `maxTokens` with NaN, Infinity, zero, an unsafe integer, or above-hard-cap input fails before provider generation.
+
+Provider deltas are redacted while retained and stop at `maxSummaryTokens * 4` UTF-16 code units without splitting a surrogate pair. Provider iteration is closed/aborted on overflow. A derived finite event ceiling also stops endless empty/non-text deltas. Final history/turn/file composition receives the same cap. Provider error events, generator throws, provider-factory failures, and policy failures expose only bounded redacted detail; host abort remains authoritative.
+
+The strategy makes only the needed provider call(s): one history summary plus one split-turn prefix summary when needed. It does not discover credentials, read files, start background jobs, or add provider SDK dependencies. Redaction is exact-string only; pass every known secret that may appear in history or provider output.
 
 ## Related APIs
-- [Compaction and retry policies](compaction-and-retry.md): core compaction strategy surface.
+
+- [Use-case model selection](use-case-model-selection.md): `summaryModel` vs session `model` fallback.
+- [Thinking and reasoning](thinking-and-reasoning.md): `thinkingLevel` → `compat`.
+- [Compaction and retry policies](compaction-and-retry.md): replaceable compaction strategy boundary and core compaction strategy surface.
+- [Observational memory compaction package](compaction-observational-memory.md): source-backed memory workers with the same use-case binding pattern.
 - [Agent/session runtime](agent-session-runtime.md): `AgentSession.compact()` and opt-in auto-compaction.
 - [Provider layer](provider-layer.md): mock providers and provider request contracts.
 - [Credentials and redaction](credentials-and-redaction.md): exact known-secret redaction behavior.

package/docs/compaction-observational-memory.md

@@ -6,6 +6,8 @@
 
 Current status: ledger/projection/render/recall utilities, explicit worker runtime, fast compaction strategy, inert extension helper, recall tool, and status/view command factories are available.
 
+This package is distinct from `@arnilo/prism-memory` working/semantic memory: observational memory compresses and recalls source-backed observations/reflections; semantic memory retrieves embeddings; working memory stores the current structured profile/state. Hosts may compose both.
+
 ## When to use it
 
 Use it when a host wants to opt in to long-session memory that records observations/reflections as session custom entries, renders prepared memory during compaction, and supports exact-id recall.
@@ -25,6 +27,20 @@ Memory records use `SessionEntry.kind: "custom"` with `entry.data.type` markers:
 
 Ids are known, source-backed 12-character lowercase hex strings matching `^[a-f0-9]{12}$`.
 
+Worker limits are finite positive safe integers:
+
+| Runtime option | Default | Hard cap | Scope |
+| --- | ---: | ---: | --- |
+| `maxWorkerTurns` | 16 | 64 | Provider turns per observer/reflector/dropper run; overrides settings `agentMaxTurns` |
+| `maxWorkerToolCallsPerTurn` | 32 | 256 | Calls retained from one provider response |
+| `maxWorkerToolCalls` | 128 | 1,024 | Calls across all turns in one worker run |
+| `maxWorkerArgumentBytes` | 64 KiB | 1 MiB | Each raw and redacted JSON argument object |
+| `maxWorkerResultBytes` | 64 KiB | 1 MiB | Full tool result and replayed value/error payload |
+| `maxWorkerMessageBytes` | 1 MiB | 8 MiB | System/prompt plus assistant-call/tool-result transcript |
+| `maxWorkerErrorBytes` | 1 KiB | 8 KiB | Provider/tool/runtime error text after exact known-secret redaction |
+
+Direct `runObserver()` / `runReflector()` / `runDropper()` calls retain required `maxTurns` and accept the corresponding shorter worker fields (`maxToolCalls`, `maxResultBytes`, etc.). Named default/hard constants and `resolveMemoryWorkerLimits()` are exported.
+
 ## Outputs / response / events
 
 Key exports:
@@ -76,7 +92,12 @@ const memory = createObservationalMemoryRuntime({
   session,
   appendEntry: (entry) => store.append(entry),
   workerProvider,
-  workerModel: { provider: "mock", model: "memory" },
+  sessionModel: agent.config.model, // fallback when workerModel unset
+  // workerModel: { provider: "mock", model: "memory" }, // optional override
+  maxWorkerTurns: 8,
+  maxWorkerToolCalls: 64,
+  maxWorkerResultBytes: 64 * 1024,
+  overrides: { thinkingLevel: "low" },
 });
 await memory.flush();
 await session.compact({ strategy: createObservationalMemoryCompactionStrategy({ keepRecentEntries: 8 }) });
@@ -90,9 +111,9 @@ await kernel.load([createObservationalMemoryExtension({ recallTool: { getEntries
 
 ## Extension and configuration notes
 
-Settings are read from the `observational-memory` key only when a host calls `resolveObservationalMemorySettings()` or `runtime.flush()`. Defaults are `observeAfterTokens: 10000`, `reflectAfterTokens: 20000`, `compactAfterTokens: 81000`, `observationsPoolMaxTokens: 20000`, `observationsPoolTargetTokens: 10000`, `agentMaxTurns: 16`, `passive: false`, and `debugLog: false`.
+Settings are read from the `observational-memory` key only when a host calls `resolveObservationalMemorySettings()` or `runtime.flush()`. Defaults are `observeAfterTokens: 10000`, `reflectAfterTokens: 20000`, `compactAfterTokens: 81000`, `observationsPoolMaxTokens: 20000`, `observationsPoolTargetTokens: 10000`, `agentMaxTurns: 16`, `passive: false`, and `debugLog: false`. `agentMaxTurns` now rejects non-integer/non-finite/out-of-range input (hard 64) instead of flooring/falling back. Runtime `maxWorkerTurns` takes precedence.
 
-The runtime requires host-supplied `session`, an `appendEntry` callback bound to that session's owning store/branch, `workerProvider`, and `workerModel`. It no longer accepts a separate `store` option because mismatched session/store pairs can append memory entries outside the active branch. After each memory append, the runtime checks the appended entry is visible at the session leaf and fails closed/restores the previous checkout if the callback points elsewhere. Optional credential resolution is explicit; missing requested credentials skip worker execution.
+The runtime requires host-supplied `session`, an `appendEntry` callback bound to that session's owning store/branch, and `workerProvider`. Model selection uses [use-case model selection](use-case-model-selection.md): pass optional `workerModel` (or settings `workerModel`) to override, and `sessionModel: agent.config.model` so workers fall back to the session model when no worker model is configured. `requireExplicitModel: true` restores the historical `missing_model` skip when no explicit worker model is set. It no longer accepts a separate `store` option because mismatched session/store pairs can append memory entries outside the active branch. After each memory append, the runtime checks the appended entry is visible at the session leaf and fails closed/restores the previous checkout if the callback points elsewhere. Optional credential resolution is explicit; missing requested credentials skip worker execution. Default credential requests use the **resolved** model's provider id.
 
 `createObservationalMemoryCompactionStrategy()` keeps recent message entries like the default compaction strategy, renders existing observations/reflections as the summary, and returns a standard Prism compaction entry. Its `data` includes `throughEntryId`, `keepEntryIds`, `strategy`, `trigger`, and `memory: { type: "om.folded", version: 1, fullFold, observations, reflections, droppedObservationIds }`. When active observations exceed `observationsPoolMaxTokens`, it performs a full fold into `data.memory`.
 
@@ -108,13 +129,18 @@ The runtime requires host-supplied `session`, an `appendEntry` callback bound to
 - Recall tool and commands only see current-branch entries supplied by the host callback.
 - Invalid or missing ids fail closed; invalid recall tool ids skip entry lookup.
 - Utilities and fast compaction are O(n) over supplied entries and use no provider, network, filesystem, timer, worker, credential, or settings access.
-- Workers serialize only supplied branch entries, enforce `agentMaxTurns`, and run one consolidation pipeline at a time per runtime. Worker transcripts replay assistant `tool_call` messages before matching role `tool` `tool_result` messages so provider requests stay valid for call/result-pairing providers.
+- Workers serialize only supplied branch entries within `maxWorkerMessageBytes`, enforce finite turns/calls/arguments/results/messages/errors, and run one consolidation pipeline at a time per runtime. Source serialization and reflection/drop prompts fail before joining beyond the transcript cap.
+- Every provider call must name a registered worker tool. Unknown calls, call overflow, oversized/deep/cyclic/non-JSON arguments/results, and transcript overflow fail deterministically; no excess call enters the assistant transcript or executes.
+- Raw arguments are measured before tool execution. Full results are measured before redaction/replay; the bounded redacted value/error is then measured again because replacement text can grow. Replayed call arguments, tool values/errors, runtime `lastError`, and debug error data contain exact known-secret redaction. Host tools may already have caused side effects before returning an invalid oversized result; keep worker tools small/idempotent.
+- Worker transcripts replay assistant `tool_call` messages before matching role `tool` `tool_result` messages so provider requests stay valid for call/result-pairing providers. Calls produced on the final allowed turn execute and persist, but no additional provider turn starts.
 - Compaction preserves raw history; Prism appends one standard compaction entry and rebuilds provider context from its summary plus kept recent messages.
 - Pass known secrets to render/recall/runtime/tool/command helpers to redact exact values from prompts, records, structured results, and text output.
 - Live tests are opt-in with `PRISM_LIVE_OBSERVATIONAL_MEMORY_TESTS=1`.
 
 ## Related APIs
 
+- [Use-case model selection](use-case-model-selection.md): session vs worker model binding and `resolveUseCaseModel`.
+- [Thinking and reasoning](thinking-and-reasoning.md): `thinkingLevel` → provider `compat`.
 - [Compaction and retry policies](compaction-and-retry.md): replaceable compaction strategy boundary.
 - [LLM compaction package](compaction-llm.md): existing optional compaction-package pattern.
 - [Session stores and branching](session-stores-and-branching.md): branch entries that observational memory reads and appends to.

package/docs/context-and-skills.md

@@ -179,6 +179,7 @@ Use `activateAllCapabilities: true` only as a temporary all-skills/all-tools com
 - [Agent/session runtime](agent-session-runtime.md): consumes host-selected context providers and skills from explicit agent config.
 - [Input and prompt assembly](input-and-prompt-assembly.md): default prompt builder and provider-input assembly helper.
 - [Instruction injection](instruction-injection.md): package injectors contribute `contextBlocks` that merge after host+skill provider blocks.
+- [Retrieval-augmented generation](rag.md): optional retrieved citations contribute through the same explicit inert context seam.
 - [Public contracts](public-contracts.md): `ContextProvider`, `ContextResolutionContext`, `ContextBlock`, `Skill`, `SkillRegistry`, `PromptBuilder`, and `PromptBuildRequest`.
 - [Middleware hooks](middleware-hooks.md): `context` and `prompt_build` hooks.
 - [Contribution registries](contribution-registries.md): inert context provider and skill contributions.

package/docs/credential-storage.md

@@ -44,8 +44,11 @@ import {
 | --- | --- | --- |
 | `path` | `string` | Vault file path. Parent directories are created as needed. |
 | `getPassphrase` | `() => string \| Promise<string>` | Host-owned passphrase retrieval. Never logged by the adapter. |
-| `scrypt` | `{ N?, r?, p?, keyLength? }` | Optional KDF tuning. Defaults: `N=32768`, `r=8`, `p=1`, `keyLength=32`. Minimum `N=16384`. |
-| `fileMode` | `number` | Unix mode for newly written files. Defaults to `0o600`. |
+| `scrypt` | `{ N?, r?, p?, keyLength? }` | Optional KDF tuning. Defaults: `N=32768`, `r=8`, `p=1`, `keyLength=32`; limits are listed below. |
+| `fileMode` | `number` | Unix mode for files. Defaults to `0o600`; group/other permissions are rejected. |
+| `limits.maxFileBytes` | `number` | Encrypted envelope file: 4 MiB default, 16 MiB hard cap. |
+| `limits.maxVaultBytes` | `number` | Decrypted vault/plaintext: 3 MiB default, 12 MiB hard cap. |
+| `limits.maxScryptMemoryBytes` | `number` | `128*N*r` memory estimate: 256 MiB default and hard cap. |
 
 ### System keychain
 
@@ -53,7 +56,8 @@ import {
 | --- | --- | --- |
 | `service` | `string` | Keychain service name (application identifier). |
 | `namespace` | `string` | Optional prefix separating environments or tenants within one service. |
-| `timeoutMs` | `number` | Operation timeout. Defaults to `5000`. |
+| `timeoutMs` | `number` | Operation timeout. Defaults to 5,000 ms; hard cap 60,000 ms. |
+| `maxPayloadBytes` | `number` | Decrypted keychain payload: 3 MiB default, 12 MiB hard cap. |
 
 ## Outputs / response / events
 
@@ -71,6 +75,8 @@ Encrypted file stores also expose:
 - `reload()` — re-read and decrypt from disk
 - `flush()` — force rewrite of the encrypted envelope
 
+`encryptBytes()` and `decryptBytes()` are Promise-based because they use asynchronous `node:crypto.scrypt`.
+
 Errors are explicit and fail closed:
 
 | Error | Code | When |
@@ -123,6 +129,7 @@ import {
 const store = await openEncryptedCredentialStore({
   path: "./credentials.vault",
   getPassphrase: () => process.env.MY_APP_CREDENTIAL_PASSPHRASE!,
+  limits: { maxFileBytes: 4 * 1024 * 1024, maxVaultBytes: 3 * 1024 * 1024 },
 });
 
 const resolver = createExplicitCredentialResolver([
@@ -151,6 +158,47 @@ await rotateEncryptedCredentialStorePassphrase({
 });
 ```
 
+### Desktop keychain and explicit overrides
+
+```ts
+import {
+  createEnvCredentialResolver,
+  createExplicitCredentialResolver,
+  createMemoryCredentialStore,
+} from "@arnilo/prism";
+import {
+  createKeychainCredentialStore,
+  createStoredCredentialResolver,
+} from "@arnilo/prism-credentials-node";
+import { createOpenAIProviderPackage } from "@arnilo/prism-provider-openai";
+
+const keychain = createKeychainCredentialStore({
+  service: "com.example.my-app",
+  namespace: "production",
+});
+await keychain.set({
+  name: "apiKey",
+  provider: "openai",
+  credential: { type: "api_key", value: userSuppliedKey },
+});
+
+const runtimeOverrides = createMemoryCredentialStore();
+// Set only for this user/agent instance; it wins over stored and env values.
+runtimeOverrides.set({
+  name: "apiKey",
+  provider: "openai",
+  credential: { type: "api_key", value: temporaryOverride },
+});
+
+const apiKey = createExplicitCredentialResolver([
+  { name: "runtime", resolver: runtimeOverrides },
+  { name: "keychain", resolver: createStoredCredentialResolver(keychain) },
+  { name: "env", resolver: createEnvCredentialResolver(process.env, { openai: "OPENAI_API_KEY" }) },
+]);
+
+const providers = createOpenAIProviderPackage({ apiKey });
+```
+
 ## Extension and configuration notes
 
 - Passphrase retrieval, TLS, and OS permission prompts remain host-owned.
@@ -161,12 +209,13 @@ await rotateEncryptedCredentialStorePassphrase({
 
 ## Security and performance notes
 
-- Authenticated encryption uses Node built-in `aes-256-gcm` and `scrypt`; no extra crypto dependencies for the file backend.
-- Atomic writes use temp file + rename; partial writes cannot replace a valid vault.
-- Derived keys are zeroed after encrypt/decrypt operations where practical.
-- Default scrypt `N=32768` targets interactive CLI unlock; raise `N` for higher security at the cost of unlock latency.
-- Keychain operations honor `timeoutMs` and surface `CredentialStoreTimeoutError` instead of blocking indefinitely.
-- Never log passphrases, derived keys, or decrypted credential payloads. Error messages do not echo secret values.
+- Authenticated encryption uses Node built-in `aes-256-gcm` and asynchronous `scrypt`; no extra crypto dependency is added for the file backend.
+- Envelope parsing rejects unknown shape, non-canonical/oversized base64, wrong salt/IV/tag size, unsupported algorithms/version, and excessive KDF work before scrypt. `N` must be a power of two from 16,384–262,144; `r≤32`, `p≤16`, `keyLength=32`, `N*r*p≤2,097,152`, and `128*N*r` must fit `maxScryptMemoryBytes`.
+- Existing Unix vaults are checked before content read and must deny group/other access. Atomic writes create a random exclusive temp file at the requested restrictive mode, then rename; Windows skips Unix mode checks.
+- Derived keys and package-owned plaintext buffers are zeroed after use. JavaScript passphrase strings and returned credentials remain host-owned.
+- Keychain operations use `@napi-rs/keyring`'s abort-aware `AsyncEntry`, so native work runs outside the JavaScript event loop. A main-loop timer aborts and rejects at `timeoutMs`; native cancellation remains OS/backend-dependent and may briefly retain one libuv worker after rejection.
+- Keychain payloads are bytes rather than password strings and are zeroed after parse/write. Unknown native errors are mapped to sanitized typed errors; no native message or secret value is echoed.
+- Never log passphrases, derived keys, or decrypted credential payloads.
 - Live keychain tests are opt-in (`PRISM_TEST_KEYCHAIN=1`); default `npm test` stays offline.
 
 ## Related APIs

package/docs/credentials-and-redaction.md

@@ -95,7 +95,7 @@ console.log(error.message);
 ## Extension and configuration notes
 
 - Hosts and extension packages can implement `CredentialResolver` and pass it explicitly to code that needs credentials.
-- `AgentConfig.credentials` is host-owned metadata for compatibility; `createAgent()` / `session.run()` do not call `credentials.resolve()`. Provider adapters, compaction workers, or request policies should receive and resolve credentials at the provider edge.
+- Credentials stay host-owned outside `AgentConfig`. `createAgent()` / `session.run()` do not call `credentials.resolve()`. Provider adapters, compaction workers, or request policies should receive and resolve credentials at the provider edge.
 - Use `createExplicitCredentialResolver()` when documenting a fixed order such as runtime override, stored credential, caller-provided env object, then fallback resolver.
 - Use `createEnvCredentialResolver()` only with an object supplied by the host; Prism does not read `process.env` for you.
 - Provider adapters should resolve credentials as late as possible, per request.
@@ -107,10 +107,10 @@ console.log(error.message);
 - Redaction only removes exact known secret values passed to the helper. It is not a general-purpose secret detector.
 - Do not pass empty strings as secrets; they are ignored.
 - `redactSecrets()` recursively walks arrays and object entries, so avoid using it on huge objects unless needed.
-- Cycle and non-JSON value handling: `redactSecrets()` is cycle-safe via a `WeakSet` visited-set. Self-referential or mutually referenced objects render `"[Circular]"` at the back-reference instead of throwing. `Date` and `RegExp` values are passed through unchanged; `ArrayBuffer` and typed arrays are passed through unchanged; `Map` is normalized to a plain object and `Set` to an array so the output stays JSON-compatible. `errorToErrorInfo()` tolerates a cyclic `error.cause` (rendered via `String()`).
+- Cycle and non-JSON value handling: `redactSecrets()` is cycle-safe via an active-path `WeakSet`. Ancestor cycles render `"[Circular]"` at the back-reference instead of throwing; shared diamond references on separate branches stay structured (they are not collapsed to `"[Circular]"`). String object keys and `Map` keys are redacted like values, with deterministic `__2`/`__3`/… suffixes on collisions. `Date` and `RegExp` values are passed through unchanged; `ArrayBuffer` and typed arrays are passed through unchanged; `Map` is normalized to a plain object and `Set` to an array so the output stays JSON-compatible. `errorToErrorInfo()` tolerates a cyclic `error.cause` (rendered via `String()`). Symbols and non-enumerable properties remain outside JSON-shaped redaction.
 - Use placeholders in tests and docs. Never commit real tokens.
 - Live provider/worker tests are gated behind explicit environment variables and skipped by default: `PRISM_LIVE_PROVIDER_TESTS`, `PRISM_LIVE_COMPACTION_TESTS`, `PRISM_LIVE_OBSERVATIONAL_MEMORY_TESTS`. Default `npm test` is network-free; do not add ungated network calls to default tests.
-- `AgentConfig.credentials` is not eagerly resolved, serialized into provider requests/events/stores, or passed to loops/compaction by the core runtime.
+- Credentials are not eagerly resolved by the core runtime, serialized into provider requests/events/stores, or passed to loops/compaction.
 - `resolveCredentialValue()` and `createExplicitCredentialResolver()` do not cache values. Add host-side caching only if a real credential source needs it.
 - `refreshOAuthCredential()` only calls the supplied OAuth provider and optional store; it has no built-in persistence or retry loop.
 - OpenAI Codex device-code OAuth polls inside `createOpenAICodexOAuthProvider().login()` with bounded delays and abort support via `OAuthLoginCallbacks.signal`. Token-endpoint failures redact authorization codes, PKCE verifiers, device/user codes, and access/refresh tokens when those values are known.

package/docs/database-persistence.md

@@ -67,7 +67,7 @@ Important shapes:
 | `RunRecord` | Stored run with `sessionId`, `branchId`, status (`queued` \| `running` \| `succeeded` \| `failed` \| `aborted`), `model`, `provider`, `idempotencyKey`, `abortReason`, and `error`. |
 | `AgentEventRecord` | Event ledger row with `event: AgentEvent` and a `redacted` flag. Hosts redact before storage. |
 | `ToolCallRecord` | Tool-call row with `arguments`, optional `result: ToolResult`, `reason`, `progress` snapshots, status, and a `redacted` flag. |
-| `UsageRecord` | Usage row wrapping `Usage` with session/run/entry linkage. |
+| `UsageRecord` | Scoped provider-turn or aggregate run usage with session/run/entry and turn/attempt linkage. |
 | `AgentDefinitionRecord` | Versioned agent definition snapshot. Only stores `AgentDefinition` data; never provider credentials/resolvers/instances. |
 | `RetentionPolicy` | Policy with `maxAgeDays`, `maxEntriesPerSession`, `maxTotalBytes`, `archiveStore`, and `appliedKinds`. |
 | `MigrationRecord` | Applied migration with name, version, timestamp, checksum, and applied-by. |
@@ -128,7 +128,7 @@ A branch leaf (`leaf_entry_id`) is the current entry id for that branch. Rebuild
 | --- | --- |
 | `prism_session_entries` | `id` PK, `session_id` FK, `parent_id`, `run_id`, `timestamp`, `kind`, `schema_version`, `message` JSONB, `event` JSONB, `model` JSONB, `previous_model` JSONB, `label`, `summary`, `data` JSONB, `metadata` JSONB |
 
-Maps directly to `SessionEntry`. `kind` is one of the `SessionEntryKind` values. `schema_version` defaults to `1`. `parent_id` may be null for the root entry of a session.
+Maps directly to `SessionEntry`. `kind` is one of the `SessionEntryKind` values. `schema_version` is nullable in schema version 3 for existing entry compatibility; hosts writing new rows should persist the entry's current schema version. `parent_id` may be null for the root entry of a session.
 
 `SessionAppendOptions.idempotencyKey` is not part of `SessionEntry`; store it in an adapter-owned side table when you need durable retry detection:
 
@@ -166,7 +166,7 @@ The `event` JSONB stores a redacted `AgentEvent`. The `sequence` column is an im
 
 | Table | Key columns |
 | --- | --- |
-| `prism_usage` | `id` PK, `session_id` FK, `run_id`, `entry_id`, `usage` JSONB, `recorded_at`, `tenant_id`, `account_id`, `user_id`, `metadata` JSONB |
+| `prism_usage` | `id` PK, `session_id` FK, `run_id`, `entry_id`, `scope`, `turn`, `attempt`, `usage` JSONB, `recorded_at`, `tenant_id`, `account_id`, `user_id`, `metadata` JSONB |
 
 The `usage` JSONB stores the `Usage` shape: input/output/total/cache tokens, cost, and currency.
 
@@ -214,7 +214,8 @@ await runRunLedgerConformance(() => createLedger(testDatabase), { exerciseReopen
 | Primitive | Purpose |
 | --- | --- |
 | `PersistenceSchemaModel` | Versioned table/column/index model covering sessions, entries, parent chain, idempotency side table, runs, events, tool calls, usage, tenant columns, and `prism_migrations` |
-| `createPersistenceMigrationContract()` | Strictly increasing migration steps, `prism_migrations` recording, advisory-lock guidance, and least-privilege migration/runtime role guidance |
+| `createPersistenceMigrationContract()` | Strictly increasing checked-in migration steps with deterministic SHA-256 checksums, `prism_migrations` recording, advisory-lock guidance, and least-privilege migration/runtime role guidance |
+| `assertAppliedPersistenceMigrations()` / `assertPersistenceSchemaShape()` | Testable fail-closed history and normalized SQLite/PostgreSQL catalog checks for every required table, column/type/null/default, PK/unique/FK, and named index. |
 | `getPersistencePaginationCursors()` | Indexed `(session_id, timestamp, id)`, `(run_id, sequence)`, `(run_id, recorded_at, id)` cursor shapes that avoid offset scans |
 | `assertPersistenceQueryPaginationConforms()` | Generic cursor pagination fixture for `queryEntries` |
 | `assertTenantScopedQueryIsolation()` | Tenant-filtered reads must not leak rows or primary-id collisions across tenants |
@@ -274,7 +275,8 @@ Recommended indexes for the reference schema. Hosts should add DB-specific parti
 | `prism_tool_calls` | `(session_id, name, started_at)` | tool usage by name |
 | `prism_tool_calls` | `(run_id, started_at)` | run tool-call listing |
 | `prism_tool_calls` | `(tool_call_id)` | deduplication / replay |
-| `prism_usage` | `(session_id, recorded_at)` | usage aggregation |
+| `prism_usage` | `(session_id, recorded_at)` | usage pagination |
+| `prism_usage` | `(session_id, scope, recorded_at)` | scope-safe billing/aggregate queries |
 | `prism_usage` | `(run_id, recorded_at)` | run usage |
 | `prism_agent_definitions` | `(name, version)` | definition lookup |
 | `prism_retention_policies` | `(tenant_id, account_id, user_id)` | policy listing |
@@ -344,7 +346,11 @@ Retention jobs should not run inside the agent/session runtime. They are a host
 
 ## Migrations
 
-Hosts own schema migrations. Prism publishes only the TypeScript contracts; no DDL is generated or executed by the core library. Recommended migration practices:
+Hosts own schema migrations. Prism publishes only the TypeScript contracts; no DDL is generated or executed by the core library. First-party SQLite/PostgreSQL adapters automatically verify their checked-in schema-v3 history and catalog at open, before runtime writes. Their catalog reads are bounded metadata queries/PRAGMAs, not table-data scans.
+
+Each new adapter-owned migration row records the contract SHA-256 checksum. A complete known v0.0.5 history whose checksum values are all `NULL` is a one-time compatibility case: under the SQLite transaction or PostgreSQL advisory transaction lock, the adapter verifies the full current shape, backfills all checksums, and continues. Unknown/duplicate/out-of-order/name-version/checksum mismatch, mixed/partial legacy values, or any missing/renamed/wrong-type/null/default/key/index artifact fails closed. Restore or apply a reviewed host migration; never edit checksums to silence drift.
+
+Recommended migration practices:
 
 - Use a sequential or timestamped migration naming convention.
 - Store applied migrations in `prism_migrations` with `name`, `version`, `applied_at`, `applied_by`, and `checksum`.
@@ -422,18 +428,20 @@ const dbStore: ProductionPersistenceStore = {
 - `ProductionPersistenceStore` is an optional extension point. The runtime does not require it.
 - `ProductionPersistenceStore.checkpoints?: CheckpointStore` exposes generic versioned save/load/bounded-list/delete with compare-and-swap and fencing tokens, without workflow vocabulary.
 - `ProductionPersistenceStore.leases?: LeaseStore` exposes atomic acquire/renew/release/get with opaque claim tokens, expiries, ownership scope, and monotonic fencing tokens.
+- `ProductionPersistenceStore.feedback?: RunFeedbackStore` exposes immutable append, bounded owned query, and owned deletion. First-party adapters store migration-003 rows in `prism_run_feedback`, FK-link `run_id`, and index owner/run/trace creation cursors.
 - Hosts choose the database, schema, transaction, and indexing strategy. The contracts specify query and checkpoint capability shapes.
 - `SessionStore` (`append`/`list`/`get`/optional `readBranchPath`) can be implemented on top of `ProductionPersistenceStore` or kept separate.
 - Cursor values and idempotency keys are host-defined and opaque to Prism.
-- First-party SQLite/PostgreSQL adapters expose `persistence.checkpoints` and `persistence.leases`, backed by package-owned `prism_checkpoints` / `prism_leases` tables. `@arnilo/prism-workflows` consumes them for durable resume and multi-process coordination; workflow code owns no SQL table.
+- First-party SQLite/PostgreSQL adapters expose `persistence.checkpoints` and `persistence.leases`, backed by package-owned `prism_checkpoints` / `prism_leases` tables. `@arnilo/prism-workflows` consumes them for durable resume, human suspension, multi-process coordination, Phase 11 schedule records/fire leases, shared state, and replay lineage; workflow code owns no SQL table. `suspended`/`denied`, schedules, state history, and replay lineage remain namespaces/categories plus bounded checkpoint JSON values, so Phases 8 and 11 need no database migration.
 
 ## Security and performance notes
 
 - **No credentials in storage.** The contracts never include `CredentialResolver`, `AIProvider`, `ProviderResolver`, provider API keys, or credential values.
 - **Redact before storage.** Runtime session entries are redacted before `SessionStore.append`; `AgentEventRecord.event` and `ToolCallRecord.result` may contain secrets, so hosts must redact them (for example with `redactAgentEvent()` and a `SecretRedactor`) before writing to durable storage and set `redacted: true`.
-- **Tenant isolation.** `OwnershipScope` fields are available on records and queries, but enforcement is the host's responsibility.
+- **Tenant isolation.** `OwnershipScope` fields are available on records and queries, but enforcement is the host's responsibility. First-party feedback stores require tenant plus account/user and use exact run ownership on append, query, and delete.
+- **Feedback retention/deletion.** Comments, tags, and metadata are redacted and bounded before insert. `RunFeedbackStore.delete()` provides explicit erasure; deleting a run cascades its feedback in first-party SQL schemas. Apply host retention policy to `created_at`.
 - **Pagination and branch reads.** Every query supports `cursor`/`limit`/`order` so hosts can avoid full-table or full-session scans. Loading an entire large session into memory to serve a provider context is an anti-pattern; implement `readBranchPath` and use branch-relevant filters / recursive ancestor queries.
-- **Indexes.** Production schemas should index `sessionId`, `runId`, `parentId`, `leafId`, timestamps, tenant/account/user, event type, and entry kind. See the reference indexes above.
+- **Indexes.** Production schemas should index `sessionId`, `runId`, `parentId`, `leafId`, timestamps, tenant/account/user, event type, entry kind, and feedback owner/run/trace creation cursors. See the reference indexes above.
 
 ## Related APIs
 

package/docs/evaluations.md

@@ -0,0 +1,122 @@
+# Evaluations
+
+## What it does
+
+`@arnilo/prism-evals` adds optional deterministic scorers, immutable datasets, live post-run scoring, and bounded batch experiments over `AgentRunResult`. Scores are finite numbers in `[0, 1]` with optional reason/metadata and linkage to run/session/trace/experiment IDs.
+
+## When to use it
+
+Use this package when a host needs offline quality checks or sampled live scoring without coupling scorers into core agent execution. Install it directly or through `@arnilo/prism-all`; installation does not attach scorers to runs.
+
+## Inputs / request
+
+| API | Key inputs |
+| --- | --- |
+| `defineScorer` | `id`, `score({ result, item?, expected?, signal? })` |
+| `defineDataset` | `id`, `version?`, immutable `items[]` with unique ids |
+| `scoreRun` / `scoreRunLive` | `AgentRunResult`, scorers, optional `sampleRate`, store, ownership, redactor |
+| `runExperiment` | `agent`, dataset, scorers, bounded `concurrency`, optional store/ownership |
+| `createMemoryEvaluationStore` | optional seed records |
+| `appendEvaluationFeedback` | `RunFeedbackStore`, `EvaluationStore`, feedback fields, and 1–64 known evaluation IDs |
+
+## Outputs / response / events
+
+| API | Output |
+| --- | --- |
+| `scoreRun` | `EvaluationRecord[]` with `scored` / `skipped` / `failed` |
+| `scoreRunLive` | same records; never mutates the agent result; host may ignore the promise |
+| `runExperiment` | `ExperimentReport` with stable item order, evaluations, and aggregates |
+| `EvaluationStore.query` | cursor-paginated, ownership-filtered page |
+| `appendEvaluationFeedback` | immutable `RunFeedbackRecord` containing only evaluation/scorer IDs |
+
+## Request/response example
+
+```json
+{
+  "scorerId": "contains-citation",
+  "status": "scored",
+  "score": 1,
+  "runId": "run_1",
+  "sessionId": "session_1",
+  "experimentId": "exp_1",
+  "sampled": true
+}
+```
+
+## Implementation example
+
+```ts
+import { createAgent, createMemoryRunFeedbackStore, createMockProvider, providerDone, providerTextDelta } from "@arnilo/prism";
+import {
+  appendEvaluationFeedback,
+  createMemoryEvaluationStore,
+  defineDataset,
+  defineScorer,
+  runExperiment,
+  scoreRunLive,
+} from "@arnilo/prism-evals";
+
+const scorer = defineScorer({
+  id: "contains-citation",
+  score: ({ result }) => ({ score: result.text.includes("[") ? 1 : 0 }),
+});
+
+const dataset = defineDataset({
+  id: "citations",
+  version: "1",
+  items: [{ id: "1", input: "Summarize with a citation" }],
+});
+
+const agent = createAgent({
+  model: { provider: "mock", model: "demo" },
+  provider: createMockProvider([providerTextDelta("ok [1]"), providerDone()]),
+});
+
+const store = createMemoryEvaluationStore();
+const report = await runExperiment({
+  agent,
+  dataset,
+  scorers: [scorer],
+  concurrency: 2,
+  store,
+  ownership: { tenantId: "t1", userId: "u1" },
+});
+
+const result = await agent.createSession().run("Follow up");
+void scoreRunLive(result, { scorers: [scorer], store });
+const evaluation = report.evaluations[0]!;
+const feedbackStore = createMemoryRunFeedbackStore({
+  resolveRun: ({ runId }) => runId === evaluation.runId
+    ? { runId, sessionId: evaluation.sessionId!, tenantId: "t1", userId: "u1" }
+    : false,
+});
+const linked = await appendEvaluationFeedback({
+  feedbackStore,
+  evaluationStore: store,
+  evaluationIds: [evaluation.id],
+  feedback: { id: "fb_1", runId: evaluation.runId!, rating: 1, tenantId: "t1", userId: "u1" },
+});
+console.log(report.aggregate.meanScore, linked.evaluationIds);
+```
+
+## Extension and configuration notes
+
+- Function scorers are the base primitive. No mandatory LLM judge, dashboard, or schema library is included.
+- Evaluation-result persistence remains package-local (`EvaluationStore`) and in-memory by default. Linked feedback is separately durable through optional `ProductionPersistenceStore.feedback`; evaluation score/reason payloads are not copied there.
+- `sampleRate` is explicit (`0`–`1`). Inject `random` for deterministic tests.
+- Dataset snapshots are frozen; duplicate item ids fail closed.
+- `appendEvaluationFeedback()` resolves every supplied ID from `EvaluationStore`, rejects missing IDs, verifies each evaluation has the same run, optional trace, and exact ownership as feedback, then copies only deduplicated `evaluationIds`/`scorerIds`. Evaluation scores, reasons, errors, and metadata are not duplicated.
+
+## Security and performance notes
+
+- Scorers receive result/item data only. Credentials, tools, and workspace access are not provided unless the host deliberately closes over them.
+- Records pass through `SecretRedactor` / `secrets` before store append.
+- Queries filter by ownership scope. Feedback linkage additionally requires tenant plus account/user and the feedback store re-verifies the run.
+- Experiment concurrency defaults to `1` and is capped at `32`. Scoring can reference run IDs without duplicating unbounded event payloads.
+
+## Related APIs
+
+- [Agent/session runtime](agent-session-runtime.md): `AgentRunResult` and `session.run()`
+- [Runs and usage ledger](runs-and-usage.md): run/session identity for score linkage
+- [Observability](observability.md): trace/run metadata hosts may copy into `traceId`
+- [Release and install](release-and-install.md): optional package install

package/docs/extensions.md

@@ -101,7 +101,7 @@ await kernel.middleware.run("provider_request", { metadata: {} });
 ## Extension and configuration notes
 
 - Extension loading is explicit. Prism does not discover packages, read manifests, or load filesystem config in the kernel.
-- `AgentConfig.extensions` is host-owned metadata for compatibility; `createAgent()` and `session.run()` do not load it or call `Extension.setup()`. Load extensions with `createExtensionKernel().load(...)`, then pass selected contributions (`tools`, `context`, `skills`, middleware, etc.) into `createAgent()`.
+- Extensions stay host-owned outside `AgentConfig`. `createAgent()` and `session.run()` do not load extension lists or call `Extension.setup()`. Load extensions with `createExtensionKernel().load(...)`, then pass selected contributions (`tools`, `context`, `skills`, middleware, etc.) into `createAgent()`.
 - Setup order is the order provided by the host.
 - The kernel writes only to explicit registries returned by `createContributionRegistries()` or provided by the host.
 - `api.registerTool()` contributes an inert `ToolDefinition` to `registries.tools`; it does not add the tool to an active tool registry, allow list, or dispatch loop.
@@ -117,7 +117,7 @@ await kernel.middleware.run("provider_request", { metadata: {} });
 ## Security and performance notes
 
 - No hidden global extension kernel, provider registry, credential resolver, settings provider, store, or resource loader is created.
-- `AgentConfig.extensions` does not auto-execute, so constructing or running an agent cannot unexpectedly run extension code.
+- Extension packages do not auto-execute from `createAgent()`, so constructing or running an agent cannot unexpectedly run extension code.
 - Error events use `ErrorInfo` and redact only known secret values passed in `secrets`.
 - Do not put resolved credential values in extension events, registry metadata, docs, logs, prompts, or session stores.
 - Event and middleware dispatch are ordered and dependency-free. They use no timers, background workers, filesystem discovery, network calls, provider calls, or tool execution.

package/docs/host-security.md

@@ -26,9 +26,12 @@ Start from explicit host inputs. Do not let runtime code discover security state
 | Tool allow-list | active tools for this agent/session/run | `createToolRegistry`, `filterTools()`, `dispatchToolCall()` |
 | Tool argument rules | host validator | `AgentConfig.validator`, `RunOptions.validate`, `ToolValidator` |
 | Coding execution policy | path/command approval adapter | `ExecutionPolicy`, `@arnilo/prism-coding-security` |
+| Remote media policy | public/default pinned DNS or explicit trusted transport | `SsrfPolicy`, `resolveMediaContentBlock()` |
 | Durable history | host database adapter | `SessionStore`, `assertSessionStoreConforms()` |
 | Durable audit | host ledger adapter | `RunLedger`, `redactRunLedgerRecord()` |
 | Extensions | explicit package imports only | `createExtensionKernel`, `ExtensionAPI` |
+| Remote agent/workflow API | host authentication + ownership mapping | `@arnilo/prism-server`, `createPrismHandler()` |
+| MCP server exposure | host MCP auth + selected capability list | `createPrismMcpServer()`, `createPrismMcpWebHandler()` |
 
 ## Outputs / response / events
 
@@ -105,7 +108,7 @@ Wire those values where they matter: provider adapters receive the resolved cred
 
 ## Extension and configuration notes
 
-- Keep security state explicit. `AgentConfig.settings` and `AgentConfig.credentials` are host-owned metadata; `createAgent()` and `session.run()` do not automatically call `settings.get()` or `credentials.resolve()`.
+- Keep security state explicit. Settings and credentials are host-owned outside `AgentConfig`; `createAgent()` and `session.run()` do not automatically call `settings.get()` or `credentials.resolve()`.
 - Resolve credentials at the provider/request edge, as late as possible. Do not put resolved credentials in configs, manifests, registries, prompts, messages, events, session entries, run ledgers, idempotency keys, cache keys, or logs.
 - Use `createExplicitCredentialResolver()` to document source order such as runtime override → stored credential → caller-supplied env object → fallback.
 - Use `createEnvCredentialResolver()` only with an object the host passes in. Prism does not read `process.env` for credentials.
@@ -121,9 +124,15 @@ Wire those values where they matter: provider adapters receive the resolved cred
 - Prism does not sandbox host tools, extensions, provider adapters, credential resolvers, or custom middleware. Use OS/container/process isolation when code is untrusted.
 - Redaction is exact known-secret replacement only. It is not arbitrary secret detection, entropy scanning, or DLP.
 - Known secrets must be passed into redactors before data is emitted or persisted. Redact again in host adapters if they transform records after Prism redaction.
-- Tool `parameters` metadata is not validated by default. Add a `ToolValidator`, use `createToolParameterValidator()` with a schema adapter, or install `@arnilo/prism-tool-validator-json-schema` before side effects.
-- MCP tools from `@arnilo/prism-mcp` are untrusted remote servers. Configure stdio commands and HTTP URLs explicitly; bound output with `maxResultBytes`; register prefixed tools only after trust review. See [MCP client bridge](mcp-tools.md).
-- Coding tools from `@arnilo/prism-coding-agent` accept an optional `ExecutionPolicy` checked inside each tool before side effects. Use `@arnilo/prism-coding-security` for path roots, command rules, and approval caching. Prism does not provide OS sandboxing unless the host supplies a sandbox adapter.
+- Tool `parameters` metadata is not validated by default. Add a `ToolValidator`, use `createToolParameterValidator()` with a schema adapter, or install `@arnilo/prism-tool-validator-json-schema` before side effects. Its untrusted-schema adapter rejects non-local refs, forbidden keys/cycles/non-finite values and bounds bytes/depth/properties/keywords/refs plus its LRU cache before Ajv compilation; do not raise caps above documented hard limits.
+- Treat embeddings as untrusted numeric input. `@arnilo/prism-memory` rejects empty, non-number, NaN, and infinite vectors before in-memory similarity or pgvector parameters; custom `Embedder`/`VectorStore` implementations must retain the same boundary.
+- Prism-generated session/run/tool/workflow/evaluation IDs use Node cryptographic UUIDs. Keep host-provided IDs authorization-scoped and validate them as untrusted identifiers; do not substitute timestamps or `Math.random()` for durable/security-relevant IDs.
+- MCP client tools from `@arnilo/prism-mcp` are untrusted remote servers. Stdio remains an explicit host executable. Streamable HTTP requires exact HTTPS origins, rejects credentials/fragments/redirects/private or mixed DNS, pins a validated address on every SDK request/reconnect, and bounds each response; plaintext is explicit loopback-only development mode. Discovery has finite page/tool/cursor/metadata/schema totals and commits atomically. Every result branch shares byte/depth/property bounds before core dispatch; supply a known-secret `SecretRedactor`, `PermissionPolicy`, and `ToolValidator` there. MCP server direction exposes only passed tools/commands, requires per-call `authorize`, and retains core gates. Its web handler still needs host `resolveAuthInfo`, TLS, edge rate limiting, and exact host/origin policy. See [MCP client/server exposure](mcp-tools.md).
+- `@arnilo/prism-server` exposes no agent/workflow by default and requires `authorize()` for every matched operation. Derive complete tenant/account/user ownership from validated host identity, never request JSON. Workflow active identity and cancellation compare exact ownership; a tenant-only scope intentionally cannot cancel a checkpoint/run carrying account or user identity. Pass the current explicitly revised workflow definition so recursive hash mismatch fails before abort or durable mutation. Configure exact host/origin allow-lists where needed, wire redaction before execution, retain tool/workflow policy checks, and adapt the Web handler behind host TLS/rate limits. Disconnect abort is default; persistent reconnect/status belongs to durable workflow checkpoints, not an invented in-memory agent result cache.
+- Coding tools from `@arnilo/prism-coding-agent` accept an optional `ExecutionPolicy` checked inside each tool before side effects; shared policy propagation includes `createReadOnlyTools()`. They enforce finite text-scan/image/edit/write/shell limits, a 600-second default shell wall time, and a 64 MiB default total-output ceiling. Successful truncated shell output leaves a host-owned exclusive `0600` temp file; delete `metadata.fullOutputPath` after use. Error/abort/timeout/overflow removes unpublished spills. Custom read/edit/shell backends must honor supplied caps/signals. Use `@arnilo/prism-coding-security` for path roots, command rules, and identity-scoped approval caching. Limits are not containment: Prism provides no OS sandbox unless the host supplies one.
+- `@arnilo/prism-credentials-node` rejects oversized/malformed envelopes and excessive scrypt work before KDF allocation, uses async scrypt, and requires restrictive existing/new Unix vault modes. Keep vault ownership and parent-directory access host-controlled; review before `chmod 600`, never auto-weaken a file policy. Keychain calls use abort-aware native async work with finite timeout/payload caps and sanitized errors. OS prompts, service availability, and whether a native backend promptly honors cancellation remain host/platform boundaries; no plaintext fallback is attempted.
+- LLM compaction always sends finite summary `maxTokens`, retains bounded deltas/events, and bounds/redacts provider/factory/policy error detail. Observational-memory workers cap turns, calls, arguments, results, transcript, and surfaced errors; unknown tools fail before execution, while invalid results can only be rejected after a host tool returns and may therefore follow side effects. Pass all known provider/credential/tool secrets into compaction/runtime options; exact replacement is not secret discovery.
+- Default remote-media loading resolves every DNS answer, rejects the hostname if any address is non-public, and pins one validated address through the request. Explicit `allowedHostnames` can trust private destinations. A host-supplied `fetch` owns DNS/rebinding/proxy/redirect safety; a custom `requestUrl` must connect to its supplied validated address.
 - Permission checks happen before tool validation and before `tool.execute()`. Middleware cannot grant permission by renaming a tool.
 - Session stores and ledgers receive redacted values when a redactor is active, but durable storage remains host-owned. Enforce tenant/account/user ownership and retention in the database layer.
 - Provider-owned auth/content/session/cache/security headers win over caller headers in adapters that merge headers.
@@ -138,10 +147,22 @@ Wire those values where they matter: provider adapters receive the resolved cred
 - Secret scan: source, tests, docs, workflow files, package metadata, built tests, packed-install canary, and tarball deny-list checks found no private-key block or common live-token prefix. Runtime redaction fixtures cover requests, events, ledgers, stores, checkpoints, provider/OAuth errors, and credential ciphertext.
 - Threat suites pass for parameterized SQL/tenant isolation, HTTP URL/SSRF rejection, realpath/symlink containment, shell-metacharacter approval, schema prototype-pollution/remote-reference bounds, OAuth polling/abort/redaction, credential tamper/wrong-key/KDF floors, MCP result bounds/timeouts, and coding approval/path policy.
 
-PostgreSQL TLS/network policy, MCP endpoint allow-listing, provider base URLs, OS keychain availability, process sandboxing, workflow tenant identity, and ANSI/control-sequence sanitization in any host terminal renderer remain host boundaries. Prism 0.0.4 ships JSON-line RPC, not an interactive TUI; hosts must render untrusted model/tool text safely. Credential-gated PostgreSQL/provider/keychain tests are separate operator/CI gates, not silently replaced by mocks.
+PostgreSQL TLS/network policy, MCP endpoint trust/credentials and egress policy beyond package origin/DNS pinning, provider base URLs, OS keychain availability, process sandboxing, workflow tenant identity, and ANSI/control-sequence sanitization in any host terminal renderer remain host boundaries. Prism 0.0.4 ships JSON-line RPC, not an interactive TUI; hosts must render untrusted model/tool text safely. Credential-gated PostgreSQL/provider/keychain tests are separate operator/CI gates, not silently replaced by mocks.
+
+## Supervisor and A2A boundaries
+
+- Register children explicitly. AND-compose parent/child/hook permissions; never let a delegation hook replace broader parent policy.
+- Build each child's context/memory with supervisor-provided `resourceId`/`threadId`; resolve provider credentials inside that child factory.
+- Keep depth, active children, input, turn/tool/token, timeout, and queue ceilings finite; propagate abort through nested calls.
+- Expose A2A only behind per-request authentication/authorization, TLS, edge rate limits, and replay policy. Public card discovery grants no invoke access.
+- Remote A2A endpoints/card URLs require exact HTTPS origin allow-lists and redirect rejection. Pin ES256 card keys/expiry; never auto-fetch untrusted `jku`.
+- Treat cards, task status, errors, artifacts, and SSE frames as untrusted bounded input and redact before logs/hooks/events. Client streaming uses one fatal UTF-8 decoder, bounded incremental LF/CRLF/multiline SSE parsing, and rejects partial/post-terminal frames; malformed remote bytes never become replacement characters in JSON.
 
 ## Related APIs
 
+- [Web-standard server handler](server.md): remote agent/workflow route, ownership, limits, abort, and deployment boundary.
+- [Supervisor delegation](supervisors.md): local child permission/memory/budget boundary.
+- [A2A interoperability](a2a.md): remote card/auth/origin/signature boundary.
 - [Settings, auth, trust, and security controls](settings-auth-trust-security.md): low-level helpers and boundary hardening table.
 - [Credentials and redaction](credentials-and-redaction.md): credential resolver order, caller-supplied env objects, OAuth refresh, exact redaction, and no persistent secret store.
 - [Tools](tools.md): active tool registry, allow/deny filters, permission order, validator order, blocked events, and no sandbox.