@arnilo/prism 0.0.4 → 0.0.5

package/docs/review-coverage-2026-07-15.md

@@ -0,0 +1,193 @@
+# Review coverage — 2026-07-15
+
+This page freezes Prism 0.0.5 scope at commit `f5128a816ae204c52f3e2f089de71c99bd5de6d4` after the Prism/Mastra review. It maps every confirmed finding and accepted capability to one owning roadmap phase, package/public surface, focused test owner, and documentation owner.
+
+Status: **scope frozen; Phases 1-14 implementation complete; publication handoff pending**. Phase 0 changes no public runtime behavior.
+
+## Release decision
+
+- Target release is **0.0.5**. Do not publish the currently versioned but unpublished 0.0.4 package graph.
+- npm currently reports `@arnilo/prism@0.0.3`; Phase 14 has retargeted every repository package and lock entry to 0.0.5. Publication remains pending the clean signed-tag workflow.
+- Core remains a Node.js 20-compatible, zero-runtime-dependency harness.
+- New capabilities are opt-in and package-owned. No server, database, credential store, telemetry exporter, memory worker, schedule, remote agent, or privileged tool activates on install.
+- Any row below that changes a trust boundary remains a release blocker until its owning phase and regression checks pass.
+
+## Frozen confirmed findings
+
+Each ID appears once. “Planned” means owned, not fixed.
+
+| ID | Confirmed finding | Disposition and single owner | Package / public surface | Focused test owner | Documentation owner | Status |
+| --- | --- | --- | --- | --- | --- | --- |
+| S-001 | Bracket-normalization lets IPv6 loopback, link-local, ULA, and IPv4-mapped private literals bypass media SSRF checks; DNS resolution/rebinding behavior is not sufficient for a private-network denial claim. | Phase 1 | Core `src/content.ts`; `SsrfPolicy` and media fetch path | `src/__tests__/content.test.ts` with injected resolver/requester matrix | `multimodal-content.md`, `host-security.md` | completed 2026-07-15 |
+| S-002 | `createReadOnlyTools()` does not apply the aggregate `executionPolicy`. | Phase 1 | `@arnilo/prism-coding-agent` read-only aggregator | coding-agent execution-policy tests | `coding-agent-tools.md` | completed 2026-07-15 |
+| S-003 | Approval caching defaults to a process-lifetime map instead of `none`; `run` and `session` scopes have no identity in the cache key. | Phase 1 | `@arnilo/prism-coding-security`; approval policy and execution identity metadata | coding-security approval tests | `coding-security.md`, `host-security.md` | completed 2026-07-15 |
+| C-001 | Sandbox adapter returns only an exit code and cannot forward stdout/stderr to coding-agent `onData`. | Phase 2 | coding-security sandbox adapter / coding-agent bash operations bridge | sandbox and shell integration tests | `coding-security.md`, `coding-agent-tools.md` | completed 2026-07-15 |
+| C-002 | OpenTelemetry agent spans end only on `agent_finished`; provider failure can leave `prism.agent.run` active. | Phase 2 | `@arnilo/prism-observability-opentelemetry` instrumentation lifecycle | in-memory telemetry failed/aborted-run tests | `observability.md` | completed 2026-07-15 |
+| C-003 | `prism.provider.tokens` is incremented for provider-turn and agent-total events, double-counting one usage source. | Phase 2 | OTel token metric names/scopes | in-memory metric assertions | `observability.md`, `runs-and-usage.md` | completed 2026-07-15 |
+| C-004 | Usage rows do not distinguish provider-turn values from run totals; the loop returns the latest turn rather than an explicit aggregate. | Phase 2 | core `Usage`, `UsageRecord`, runtime accumulator, persistence adapters | multi-turn run-ledger conformance and runtime tests | `runs-and-usage.md`, persistence docs | completed 2026-07-15 |
+| C-005 | Providers resolve media one block at a time, so request-wide 32-item/32-MiB bounds are not accumulated before provider/upload side effects. | Phase 2 | core media request resolver and provider media serializers | content/provider-media/provider package tests | `multimodal-content.md` | completed 2026-07-15 |
+| A-001 | Workflow coordinator concurrency test was timing-sensitive under load. | Phase 0 | test only; production workflow API unchanged | `packages/workflows/src/__tests__/coordinator.test.ts` repeated five times plus full suite | this page, `performance.md` | completed at frozen HEAD `f5128a8` |
+| A-002 | `AgentConfig.extensions`, `settings`, and `credentials` are accepted but explicitly ignored by agent/session runtime. | Phase 3 | core `AgentConfig` and host composition docs | compile fixtures and runtime behavior tests | `agent-session-runtime.md`, `customization.md`, `migration.md` | completed 2026-07-15 |
+| A-003 | `AgentSession.run()`/`prompt()` return `Promise<void>` and integrated streaming requires a separately started subscriber. | Phase 3 | core `AgentSession`, new run-result/stream contract | agent/session, CLI/RPC, workflow tests | agent/session, events, CLI/RPC, workflow docs | completed 2026-07-15 |
+| A-004 | Direct source/phase-text boundary tests make refactors fail without behavioral changes. | Phase 14 | test architecture; replace implementation assertions when touched, retain manifest/docs/absence boundary checks | docs/export/behavior/pack tests replacing implementation-text assertions | testing/release coverage docs | completed for touched tests; broad historical conversion deferred |
+| A-005 | `src/contracts.ts`, `src/agents.ts`, and `packages/workflows/src/run.ts` are conflict hotspots; docs/plans are larger than production source. | Phase 14 | maintainability gate; split only where completed work proves a cohesive domain | typecheck, public exports, behavior suites, docs links | review coverage and release docs | reviewed; no safe release-time cohesive split, deferred with measurements |
+| R-001 | 0.0.4 must not be published after the review; all package/version/tag/provenance checks must target 0.0.5. | Phase 14 | 30-package graph, lockfile, release workflow/script | release, packaging, install, Node 20/24, registry checks | `release-and-install.md`, changelogs, migration docs | completed 2026-07-16; publication handoff pending |
+
+## Accepted capability scope
+
+These are the twelve accepted Mastra-comparison recommendations. Each has one implementation owner; adjacent phases may consume the result but do not own a duplicate implementation.
+
+| ID | Capability | Single owner | Reused Prism primitives | Minimum missing surface | Test owner | Documentation owner |
+| --- | --- | --- | --- | --- | --- | --- |
+| F-001 | Direct run result and integrated stream | Phase 3 / core | `AgentSession`, loop, `AgentEvent`, bounded subscriber | `AgentRunResult`; race-free `session.stream()` wrapper over one execution | core agent/session suite | agent/session and events docs |
+| F-002 | Minimal scorers, sampling, datasets, batch experiments | Phase 4 / `@arnilo/prism-evals` (completed 2026-07-15) | F-001 result, run/trace IDs, package-local evaluation store | package-local scorer/dataset/experiment records and runner | eval package tests | `evaluations.md` |
+| F-003 | Minimal project scaffold | Phase 5 / existing root CLI (completed 2026-07-15) | CLI parser, examples, provider packages, pack smoke | deterministic `prism init`; tiny templates | CLI temp-project pack/install/typecheck/test | CLI, README, release/install docs |
+| F-004 | AI SDK model interoperability | Phase 6 / `@arnilo/prism-provider-ai-sdk` (completed 2026-07-15) | `AIProvider`, provider events, transport/content/structured-output conformance | one supported AI SDK language-model adapter | provider conformance with fake AI SDK model | provider package and AI SDK page |
+| F-005 | Working memory and semantic recall | Phase 7 / `@arnilo/prism-memory` (completed 2026-07-15) | context providers, middleware, ownership, Postgres package | package-local `Embedder`, `VectorStore`, working-memory store; one pgvector adapter | memory conformance and PostgreSQL opt-in suite | `working-and-semantic-memory.md` |
+| F-006 | Durable human approval and suspend/resume | Phase 8 / workflows plus coding-security bridge (completed 2026-07-15) | checkpoints, leases, fencing, workflow resume/cancel, execution policy | suspended state, validated payload, exact-once resume cursor | workflow restart/race/authorization tests | workflow and coding-security docs |
+| F-007 | Small text/Markdown RAG | Phase 9 / `@arnilo/prism-rag` (completed 2026-07-16) | Phase 7 embed/vector contracts, resource/content bounds, context provider | deterministic chunk/index/retrieve/citation helpers | RAG package tests | `rag.md` |
+| F-008 | Web-standard agent/workflow handler and MCP server | Phase 10 / `@arnilo/prism-server` plus existing MCP package (completed 2026-07-16) | F-001 result/stream, workflow commands, MCP SDK, abort/redaction | `Request -> Response` handler; explicit MCP server registration | server and MCP in-memory tests | `server.md`, `mcp-tools.md` |
+| F-009 | Durable schedules and reconnectable background runs | Phase 11 / workflows (completed 2026-07-16) | coordinator, checkpoints, leases, active-run registry | schedule records/claims and one-time/interval/host-calculated next run | workflow multi-coordinator tests | workflow/persistence/server docs |
+| F-010 | Workflow composition, state, and replay | Phase 11 / workflows (completed 2026-07-16) | DAG runner, node adapters, checkpoints, lineage/events | workflow node, bounded typed state, replay lineage/cursor | workflow nested/replay tests | workflow docs |
+| F-011 | Trace/run feedback linked to evaluations | Phase 12 / persistence plus OTel/evals (completed 2026-07-16) | run/trace IDs, cursor queries, redaction, OTel | bounded feedback record/query and safe OTel projection | persistence conformance and OTel tests | observability/evaluation docs |
+| F-012 | Supervisor delegation and A2A | Phase 13 / `@arnilo/prism-supervisor` (completed 2026-07-16) | F-001, memory scope, permission/abort/budget, web handler | bounded child delegation and current A2A protocol mapping/signing | supervisor isolation and A2A protocol tests | `supervisors.md`, `a2a.md` |
+
+## Existing primitive inventory
+
+| Domain | Existing reusable primitive | What it already covers | Frozen gap/decision |
+| --- | --- | --- | --- |
+| Agent execution | `Agent`, `AgentSession`, `AgentLoopStrategy`, `singleShotLoop`, generate/validate/revise loop | provider/tool turns, retry, compaction, abort, stores, middleware, ledger | Add only F-001 result/stream in Phase 3; do not add a second engine or central application object. |
+| Events and fan-in | `AgentEvent`, `createEventMultiplexer<T>()`, bounded `subscribe()` queues | normalized live events, ordered source fan-in, overflow policies | Reuse for server, workflow, and supervisor streams. Durable replay remains storage-owned. |
+| Provider boundary | `AIProvider.generate()`, `ProviderEvent`, request policies, bounded SSE/body/argument transport, provider/media/openai helpers | first-party model streams, tool fragments, structured output, abort, metadata | AI SDK is an optional adapter only; no new provider abstraction. |
+| Input/context | `InputBuilder`, `PromptBuilder`, `ContextProvider`, instruction injectors, resource loader, ten middleware hook names | explicit context/prompt assembly and host contributions | Memory and RAG inject through context/middleware; no memory-specific core hook. |
+| Tools | `ToolDefinition`, validator, registry/filter, permission policy, `ExecutionPolicy`, bounded parallel dispatch | schema validation, allow/deny, ownership metadata, ordered tool transcript | Fix policy propagation/identity; durable approval extends workflow checkpoints rather than tool loop internals. |
+| Redaction | `SecretRedactor`, message/event/request/session/ledger redactors | active-path cycle handling, object/Map key redaction, metadata-safe errors | Reuse at every new storage/remote boundary; no second redaction system. |
+| Session/run persistence | `SessionStore`, `RunLedger`, `ProductionPersistenceStore`, cursor pages, ownership scope | sessions, branches, entries, runs, events, tool calls, usage, definitions, retention, migrations | Add narrowly typed records only when package-local stores cannot preserve cross-package run linkage. Vector search stays outside `SessionStore`. |
+| Durable coordination | `CheckpointStore`, `LeaseStore`, fencing tokens; memory/SQLite/PostgreSQL implementations | versioned CAS state, atomic claims, expiry/takeover | Reuse for suspend, schedules, background runs, and replay. No new queue/lock engine. |
+| Workflows | bounded DAG with agent/function/tool/conditional/fan-out/join nodes; checkpoint/resume/cancel/coordinator/RPC | deterministic local and multi-process orchestration | Extended for suspension, schedules/background runs, composition/state/replay without a durable-agent engine. |
+| MCP | client bridge over SDK stdio and Streamable HTTP; list cache, timeout, abort, bounded results | consuming remote MCP tools | Add explicit server exposure in existing package; expose nothing by default. |
+| CLI/RPC | `prism` CLI, LF-delimited RPC, `CommandDefinition`, workflow commands | host-controlled run and durable workflow operations | Add stdlib-only `init`; server remains optional package-owned. |
+| Testing | mock provider plus provider/session/ledger/compaction/tool/extension/persistence conformance | network-free adapter and behavior checks | Add package-specific conformance only for genuinely reusable memory/eval/server seams. Avoid new source-text boundary tests. |
+| Packaging | root plus 29 workspaces; 23 capability packages and six profile bundles | independent installation, dependency-ordered release, pack/import smoke | `prism-all` reaches all 30 packages; provider umbrella reaches all seven adapters; focused profiles stay unchanged. Core keeps zero runtime dependencies. |
+
+## Current package and export inventory
+
+The publishable graph is root plus 28 workspaces (29 packages). Every package remains explicit; no package discovery exists.
+
+| Export group | Current public surface |
+| --- | --- |
+| Root runtime | `@arnilo/prism` |
+| Root provider helpers | `@arnilo/prism/providers/openai-compatible`, `/transport`, `/openai`, `/media` |
+| Root testing helpers | `/testing/provider-conformance`, `/session-store-conformance`, `/compaction-conformance`, `/tool-conformance`, `/extension-conformance`, `/persistence-schema`, `/run-ledger-conformance` |
+| Root Node helpers | `/node/config`, `/settings`, `/trust`, `/session-store-jsonl`, `/contribution-discovery`, `/instruction-injectors`, `/system-prompts`, `/agent-definitions` |
+| Provider packages | `prism-provider-openai`, `-opencode-go`, `-openrouter`, `-zai`, `-kimi`, `-neuralwatt` |
+| Compaction packages | `prism-compaction-llm`, `prism-compaction-observational-memory` |
+| Optional feature packages | `prism-observability-opentelemetry`, `prism-tool-validator-json-schema`, `prism-mcp`, `prism-coding-agent`, `prism-coding-security`, `prism-session-store-sqlite`, `prism-session-store-postgres`, `prism-credentials-node`, `prism-workflows`, `prism-evals`, `prism-provider-ai-sdk`, `prism-memory`, `prism-rag`, `prism-server`, `prism-supervisor` |
+| Profile bundles | `prism-all`, `prism-base`, `prism-code`, `prism-compaction`, `prism-providers`, `prism-sdk` |
+
+Core middleware exposes exactly ten built-in hook names: `provider_request`, `input_assembly`, `prompt_build`, `context`, `tool_call`, `tool_result`, `retry`, `compaction`, `session_start`, and `session_shutdown`. Custom string hooks remain extension-owned. New phases reuse these hooks or package APIs unless the owning phase documents a generic cross-package gap.
+
+## Package and primitive decisions by phase
+
+| Phase | Owner | Existing primitive consumed | Why it is insufficient | Minimum generic addition allowed |
+| --- | --- | --- | --- | --- |
+| 1 | core, coding-agent, coding-security | content policy, execution policy, approval policy | hostname normalization/DNS pinning and cache identity are incomplete | normalized/pinned network seam and execution run/session identity only |
+| 2 | core, coding-security, OTel, providers | bash callback, runtime events, usage rows, media resolver | callbacks/terminal states/accounting/request aggregation are incomplete | sandbox output callback; usage scope/aggregate; request-level media resolver |
+| 3 | core | session run, loop, events | no direct terminal result or integrated stream | `AgentRunResult` and one stream wrapper |
+| 4 | optional eval package | Phase 3 result, IDs, persistence | no scorer/dataset record or bounded runner | package-local contracts; generic persistence addition only for durable cross-package linkage |
+| 5 | root CLI | CLI and compile-checked examples | `prism init` + `templates/init` | templates and command only; no new library primitive |
+| 6 | optional AI SDK provider | `AIProvider` and provider conformance | AI SDK models do not implement Prism's interface | adapter only; no core change |
+| 7 | optional memory plus PostgreSQL adapter | context, ownership, middleware | no embedding/vector/working-memory contract | package-owned contracts and one production adapter |
+| 8 | workflows/coding-security | checkpoint/resume/lease/policy | completed: suspended/denied state, validated/redacted resume, expected-version CAS, tool policy recheck | workflow status/checkpoint extension; no generic scheduler |
+| 9 | optional RAG | Phase 7 and context/resource limits | completed: bounded text/Markdown chunk/index/filter/retrieve/citation/context helpers | package-only helpers |
+| 10 | optional server and MCP | Web APIs, result/stream, workflow commands, MCP SDK | completed: bounded authorized agent/workflow Web handler plus explicit MCP tool/command registration and SDK Web transport | package-owned handler/router and MCP registrations |
+| 11 | workflows/persistence | coordinator/checkpoint/lease/DAG | completed: ownership-scoped one-time/interval/calculated schedules, deterministic background enqueue, nested runner composition, bounded validated state/history, immutable replay lineage and fresh approval checks | package records over existing generic checkpoint/lease primitives; no migration or second worker engine |
+| 12 | persistence/evals/OTel | run/trace IDs and cursor queries | completed: immutable exact-owned feedback append/query/delete, ID-only evaluation linkage, migration-003 SQLite/PostgreSQL stores, safe span projection and fixed-label counters | one bounded typed record/store plus optional OTel handlers; no vendor exporter |
+| 13 | optional supervisor/A2A | session result, memory scope, policy, event multiplexer, Request/Response, WebCrypto | completed: explicit bounded child delegation, narrowing permissions/hooks, derived scopes, A2A 1.0 cards/ES256/JSON-RPC/SSE/exact-origin client | one zero-dependency optional package; text-only protocol subset |
+| 14 | release/docs/tests | deterministic release and pack checks | completed: graph/docs/changelogs retargeted to 0.0.5; packed cross-capability and release matrix evidence recorded | no release-time source split; all umbrella inclusion preserves independent direct installs and inert activation |
+
+## Threat-boundary matrix
+
+| Boundary | Untrusted input / asset | Primary risks | Required 0.0.5 controls | Owner |
+| --- | --- | --- | --- | --- |
+| Media network fetch | URL, hostname, DNS answer, response bytes/MIME | private-network access, rebinding, redirects, decompression/size abuse | normalize literals, classify all private ranges, resolve and pin public address or require allow-list/injected hardened loader, reject redirects, timeout/abort, per-item and whole-request bounds before provider side effects | Phases 1-2 |
+| Tool execution | model-produced name/arguments/path/command | shell execution, traversal/symlink escape, policy bypass, output exhaustion | schema/filter/permission/execution policy on every aggregator, realpath containment, approval, sandbox, abort, bounded/redacted output | Phases 1-2 |
+| Approval cache/resume | action and human decision | cross-run/session/tenant decision reuse, stale approval, duplicate side effect | default no cache, identity-bound keys, durable owner check, version/fencing/idempotency, policy recheck on resume | Phases 1 and 8 |
+| Remote HTTP/MCP | request body, identity headers, selected capability, stream consumer | unauthorized capability use, DoS, data leak, orphaned runs | expose nothing by default, host auth callback, owner checks, body/event/concurrency/time bounds, disconnect abort, redacted errors | Phase 10 |
+| Working/semantic memory and RAG | stored user text, embeddings, retrieved documents/metadata | cross-tenant recall, prompt injection, retention leak, unbounded context | mandatory tenant/resource/thread scope, bounded top-K/context, redaction, inert context, host retention/deletion | Phases 7 and 9 |
+| Workflow suspend/schedule/replay | resume payload, checkpoint, schedule, source run | forged resume, stale worker, duplicate fire/side effect, approval replay | schema validation, authorization, CAS/fencing, idempotency, immutable lineage, bounded state/history | Phases 8 and 11 |
+| Feedback/evaluation | comments, tags, scorer output, dataset items | PII/secret persistence, tenant leak, metric-cardinality explosion | ownership, redaction, limits, retention, no free text in metric labels, scorer isolation | Phases 4 and 12 |
+| Supervisor delegation | child prompt/result, selected child/tool, delegated memory | privilege amplification, recursive/cyclic delegation, budget exhaustion, memory/credential leak | implemented: explicit allow-list, AND-only permission narrowing, unique resources, depth/concurrency/token/time/tool limits, cancellation propagation | Phase 13 complete |
+| A2A | remote card, signature, task/message stream | impersonation, replay, malicious/oversized remote content, SSRF/credential forwarding | implemented: protocol-1.0 validation, host auth, ES256 signature/expiry verification, exact HTTPS origin allow-list/redirect rejection, bounds/timeouts/abort, untrusted output mapping | Phase 13 complete |
+
+## Capabilities already present — do not reimplement
+
+| Existing capability | Evidence | 0.0.5 rule |
+| --- | --- | --- |
+| Revision ownership/redaction fix and valid multi-round tool transcript | `src/agent-loops.ts`, `src/redaction.ts`, regression tests | Preserve; Phase 3 reuses loop output. |
+| Object and `Map` key redaction, active-path cycle handling | redaction suite | Use the same redactor everywhere. |
+| Bounded provider SSE, error body, argument parsing, retry, native structured output | provider primitives and conformance | Adapters reuse these helpers/limits. |
+| Polling OpenAI device OAuth | provider-openai OAuth tests | No new credential flow in core. |
+| JSON Schema tool validation, bounded parallel calls, exclusive tools | core/tool-validator and loop tests | Preserve shared dispatch. |
+| MCP client bridge | `@arnilo/prism-mcp` | Phase 10 adds server direction only. |
+| SQLite/PostgreSQL production persistence, checkpoints, leases | adapter conformance/live CI | Extend only required records/migrations. |
+| Encrypted file/keychain credentials | `@arnilo/prism-credentials-node` | Hosts keep explicit credential ownership. |
+| Audio/file/document blocks and MIME/size checks | core/provider media tests | Fix SSRF/request aggregation; do not add a second media model. |
+| OpenTelemetry agent/provider/tool instrumentation | optional OTel package | Correct lifecycle/accounting; no vendor matrix. |
+| Bounded DAG workflows and distributed coordinator | workflows package | Extend the same engine. |
+| Deterministic resumable package release | `scripts/release.mjs`, release workflow/tests | Retarget to 0.0.5 only after all gates. |
+
+## Explicit exclusions
+
+0.0.5 does not include Studio/editor/cloud services, browser automation, voice providers, chat-channel adapters, framework-specific HTTP adapters, auth-provider packages, deployment-provider packages, vendor observability exporters, a vector-store matrix, advanced document parsers/GraphRAG, an interactive TUI, automatic discovery/activation, or a mandatory central application object.
+
+A cron-expression parser is also excluded: Phase 11 provides one-time timestamps, fixed intervals, and a host-supplied next-run calculator. Add a cron adapter only from a concrete requirement.
+
+## Frozen baseline summary
+
+Detailed commands and measurements are in [Performance limits](performance.md#005-phase-0-baseline-2026-07-15).
+
+| Area | Frozen value |
+| --- | --- |
+| Runtime/toolchain | Node 24.18.0 measurement host; npm 11.16.0; supported runtime remains Node >=20 |
+| Full network-free tests | 1,475 total; 1,450 pass; 25 explicit live skips; 0 fail; 25.750 s |
+| `sdk:ready` | pass; 54.341 s |
+| Publishable graph | 24 packages at Phase 0 freeze; 25 after Phase 4 (evals); 26 after Phase 6 (AI SDK); 27 after Phase 7 (memory); 28 after Phase 9 (RAG); 29 after Phase 10 (server); 30 after Phase 13 (supervisor/A2A). Phase 14 follow-up puts all 30 behind `prism-all` and all seven adapters behind `prism-providers`. |
+| Tarballs | 542,993 packed bytes / 2,084,900 unpacked bytes aggregate; root 346.0 kB / 1.3 MB |
+| Installed workspace | 72 MiB `node_modules` |
+| Source/tests | 189 production TypeScript files / 26,828 lines; 144 test files / 23,535 lines |
+| Docs/plans/examples | 70 docs / 12,662 lines; 58 plans / 24,270 lines; 39 examples / 3,134 lines |
+| Current generator | `prism init`; default sources ~3.3 KB / 8 files; default clean install ~27.5 MB vs Mastra 439 MB |
+| Mastra comparator | default scaffold measured 439 MB `node_modules`, 300 MB build output, 427 installed packages |
+
+## Phase 0 verification
+
+Executed from repository root at frozen HEAD:
+
+```bash
+npm test
+npm run sdk:ready
+for i in 1 2 3 4 5; do node --test packages/workflows/dist/__tests__/coordinator.test.js; done
+node /tmp/prism-phase0-bench.mjs
+```
+
+Results:
+
+- Pre-change baseline and post-documentation full checks passed with zero failures. Final `sdk:ready` completed in 57.764 s with all 24 dry-run packs; the frozen pre-change value remains 54.341 s.
+- Coordinator suite passed five consecutive runs after the pre-freeze test correction.
+- Traceability validation found 14 unique confirmed-finding IDs, 12 unique capability IDs, all roadmap phases 0-14, and no missing or duplicate owner.
+- The benchmark script was temporary because these measurements are dated evidence, not CI wall-clock assertions.
+
+## Documentation reviewed
+
+- Local: `docs/index.md`, `public-contracts.md`, `agent-session-runtime.md`, `agent-loops.md`, `runs-and-usage.md`, `workflows.md`, `workflow-orchestration-primitives.md`, `host-security.md`, `release-and-install.md`, `performance.md`, and `review-coverage-2026-07-14.md`.
+- Source: core contracts/runtime/middleware/input/tools/content/redaction/persistence/checkpoint/lease/provider primitives, workflow package, optional package manifests/exports, and all seven testing conformance helpers.
+- Comparison: Mastra repository commit `2745031d1d4a4978f037092da371428c32e2842a` and current docs/source reviewed on 2026-07-15 for agents, memory, RAG, workflows, evals, observability, server, MCP, scheduling, supervisors, and A2A.
+
+## Related pages
+
+- [Roadmap](../roadmap.md): executable Phase 0-14 plan and release gate.
+- [Review coverage — 2026-07-14](review-coverage-2026-07-14.md): evidence for capabilities already shipped before this review.
+- [Performance limits](performance.md): dated baseline details and existing runtime limits.
+- [Host security](host-security.md): current host responsibilities pending the Phase 1-2 corrections.
+- [Release and install](release-and-install.md): current package graph and deterministic publication process.

package/docs/runs-and-usage.md

@@ -2,7 +2,7 @@
 
 ## What it does
 
-`RunLedger` is the host-implemented, write-only seam Prism uses to durably persist run metadata, agent events, tool calls, and usage during a `session.run()`. The runtime calls the adapter as each record becomes available; the adapter decides how to write it (SQL insert, NoSQL put, JSONL append, time-series batch, etc.).
+`RunLedger` is the host-implemented, write-only seam Prism uses to durably persist run metadata, agent events, tool calls, and usage during a `session.run()`. `RunFeedbackStore` is the separate post-run seam for immutable ratings, comments, tags, and evaluation links. The runtime calls the adapter as each record becomes available; the adapter decides how to write it (SQL insert, NoSQL put, JSONL append, time-series batch, etc.).
 
 APIs:
 
@@ -13,6 +13,7 @@ APIs:
 - `ToolCallRecord` / `ToolCallStatus`
 - `UsageRecord`
 - `redactRunLedgerRecord()`
+- `RunFeedbackRecord` / `RunFeedbackStore` / `createMemoryRunFeedbackStore()`
 
 ## When to use it
 
@@ -37,7 +38,7 @@ Set the ledger and optional ownership scope/idempotency key on the agent or the
 | `appendRun` | `RunRecord` | After run starts (`running`) and again at finish (`succeeded`/`failed`/`aborted`). |
 | `appendEvent` | `AgentEventRecord` | After every emitted `AgentEvent`, after redaction. |
 | `appendToolCall` | `ToolCallRecord` | For each tool-call `started`, `progress`, `finished`, `error`, and `blocked` transition. |
-| `appendUsage` | `UsageRecord` | For each provider `usage` event and for the final loop usage. |
+| `appendUsage` | `UsageRecord` | Once per terminal provider turn (`scope: "provider_turn"`) and once for the O(turns) aggregate (`scope: "run_total"`). |
 
 All methods may be sync or async (`void | Promise<void>`). The runtime awaits them at safe boundaries, so a slow adapter blocks the run.
 
@@ -92,9 +93,40 @@ The adapter receives these record shapes:
 | --- | --- |
 | `id` | Unique ledger row id. |
 | `runId` / `sessionId` / `entryId` | Correlation ids. |
+| `scope` | `provider_turn` for billable source rows; `run_total` for the aggregate. Never sum both scopes. |
+| `turn` / `attempt` | Provider-turn attribution; absent on `run_total`. |
 | `usage` | `Usage` shape: input/output/total/cache tokens, cost, currency. |
 | `recordedAt` | ISO timestamp. |
 
+## Run/trace feedback
+
+`RunFeedbackStore.append()` accepts an immutable record only when `resolveRun` finds the same `runId` under the exact `{ tenantId, accountId?, userId? }` scope. A tenant plus account or user is mandatory. Records contain `sessionId`, optional `traceId`, finite `rating` in `[-1, 1]`, comment, tags, scorer IDs, evaluation IDs, timestamp, creator, and metadata. Correction appends a new ID; records are never updated in place. `delete()` is the explicit privacy/retention operation.
+
+```ts
+import { createMemoryRunFeedbackStore } from "@arnilo/prism";
+
+const feedback = createMemoryRunFeedbackStore({
+  resolveRun: ({ runId }) => runId === result.runId
+    ? { runId, sessionId: result.sessionId, tenantId: "t1", userId: "u1" }
+    : false,
+  redactor,
+});
+await feedback.append({
+  id: "fb_1",
+  runId: result.runId,
+  rating: 1,
+  comment: "Useful and cited",
+  tags: ["reviewed"],
+  evaluationIds: ["eval_1"],
+  tenantId: "t1",
+  userId: "u1",
+});
+const page = await feedback.query({ runId: result.runId, tenantId: "t1", userId: "u1", limit: 50 });
+await feedback.delete({ id: "fb_1", tenantId: "t1", userId: "u1" });
+```
+
+Default/hard bounds: comment 4/16 KiB, tags 16/64, scorer/evaluation IDs 16/64 each, metadata 16/64 KiB, query page 100/500; tags are 64 characters and identifiers 128. The store redacts comment/tags/metadata after run ownership validation and before persistence. IDs are linked, not scorer payloads. `ProductionPersistenceStore.feedback?` exposes this capability; first-party SQLite/PostgreSQL adapters implement it in schema migration `003_run_feedback` and reject missing/cross-owned runs.
+
 ## Status transitions
 
 ```
@@ -189,7 +221,9 @@ await session.run("Hello", {
 });
 
 console.log(runs.at(-1)?.status); // succeeded
-console.log(cacheUsageReport(usageRows.at(-1)?.usage));
+const billable = usageRows.filter((row) => row.scope === "provider_turn");
+const aggregate = usageRows.find((row) => row.scope === "run_total");
+console.log(cacheUsageReport(aggregate?.usage));
 // { cacheReadTokens: 0, cacheWriteTokens: 0, ... } when provider usage is present
 ```
 
@@ -208,6 +242,7 @@ console.log(cacheUsageReport(usageRows.at(-1)?.usage));
 - `AgentConfig.idempotencyKey` is the default idempotency key; `RunOptions.idempotencyKey` overrides it per run.
 - The runtime resolves `model` and `provider` from `AgentConfig`/`RunOptions`/`AgentDefinition` before writing the start `RunRecord`.
 - Adapters should treat appends as ordered within a `runId`: event and tool-call rows preserve emission order because the runtime drains pending appends before writing the final `RunRecord`.
+- Billing queries must filter `scope = "provider_turn"`; presentation queries normally read the single `run_total`. `UsageQuery.scope`, `turn`, and `attempt` are explicit filters.
 - Adapters that need upsert semantics can use `RunRecord.id` (== `runId`) as the stable key.
 - Use `cacheUsageReport(record.usage, model)` for cache diagnostics from normalized usage. It works when a provider reports `cacheReadTokens` without `cacheWriteTokens`; missing write tokens are reported as `0`, and unavailable hit rate/savings stay `undefined`.
 - **Provider-specific telemetry is package-owned.** Core `Usage` carries token counts and `cost`/`currency`; it has no energy or detailed cost-breakdown fields. Providers that surface extra telemetry (e.g. `@arnilo/prism-provider-neuralwatt` exposes `neuralWattEventsWithTelemetry()`, `parseNeuralWattComment()`, and `mapNeuralWattTelemetry()` for `: energy`/`: cost` SSE comments and non-streaming top-level fields) keep that data in package-specific helpers/types. Telemetry never enters `RunLedger` usage rows unless the host explicitly copies it in; it carries usage/cost numbers only — never prompts, API keys, or headers. Account-level quota is likewise package-owned: `@arnilo/prism-provider-neuralwatt` exports an explicit `getNeuralWattQuota()` helper that the host calls on demand (never during generation); NeuralWatt rate-limits that endpoint to 1 request per second per customer, so the caller owns throttling.
@@ -219,9 +254,11 @@ console.log(cacheUsageReport(usageRows.at(-1)?.usage));
 - **Redaction.** The runtime calls `redactRunLedgerRecord()` and `redactAgentEvent()` with the active `SecretRedactor` before handing records to the adapter. `AgentEventRecord.redacted` and `ToolCallRecord.redacted` are set to `true` when a redactor is configured. Hosts should still redact before writing to durable storage if they perform additional transformations.
 - **Message content stays in `SessionStore`.** `AgentEventRecord.event` may contain `message_delta` / `message_finished` payloads; these are redacted but still belong conceptually to the session store. Do not use the ledger as the source of truth for messages.
 - **Cache diagnostics stay numeric.** `cacheUsageReport()` derives reports from `Usage` numbers and optional `ModelConfig.cost`; do not add prompt text, cache keys, headers, credentials, or provider payloads to usage rows.
+- **No double billing.** Sum `provider_turn` rows or read `run_total`; never sum both. Run totals add every turn/attempt in O(turns), derive missing per-turn totals from input/output tokens, and omit aggregate cost when reported currencies conflict.
 - **Synchronous adapters block the run.** An adapter that performs network or heavy DB writes inline will slow down the agent loop. For high-throughput hosts, buffer or batch inside the adapter and return quickly; the runtime awaits the returned promise. If batching, preserve per-run order before acknowledging a batch: `appendEvent` rows should be pageable by `(runId, sequence)`, run rows by `(sessionId, startedAt, id)`, and usage rows by `(runId, recordedAt, id)`.
 - **Idempotency is host-owned.** The runtime writes the key into `RunRecord.idempotencyKey`; enforcing unique keys and deduplicating retries is the host adapter's responsibility.
-- **Tenant isolation.** `OwnershipScope` fields are copied from the active ownership scope, but the runtime does not enforce tenant isolation. Host adapters must apply their own access controls when querying persisted ledger rows.
+- **Tenant isolation.** `OwnershipScope` fields are copied from the active ownership scope, but the runtime does not enforce tenant isolation for ledger rows. Feedback is stricter: append/query/delete require tenant plus account/user, and first-party stores compare the exact scope to the linked run.
+- **Feedback privacy.** Comments/tags/metadata can contain PII. Configure a feedback redactor, apply retention, and call owned `delete()` for erasure. Never copy comments or tag values into metric labels.
 
 ## Related APIs
 

package/docs/server.md

@@ -0,0 +1,139 @@
+# Web-standard server handler
+
+## What it does
+
+`@arnilo/prism-server` exposes explicitly selected agents and workflows through one framework-free `(Request) => Promise<Response>` handler. It supports direct agent results, bounded agent/workflow SSE, durable workflow start/enqueue/status/cancel/resume/replay, ownership-scoped schedules, host authorization, ownership propagation, redaction, and resource ceilings.
+
+No listener starts on import. Empty `agents`/`workflows` maps expose nothing. Authentication, authorization, route selection, durable stores, TLS, rate limiting, and framework/serverless adaptation remain host-owned.
+
+## When to use it
+
+Use it when a Node 20, serverless, worker, or framework host already speaks Web `Request`/`Response` and needs a small Prism API boundary. Wrap it in the platform's native adapter rather than adding Express, Fastify, Hono, Koa, Nest, or Next to Prism.
+
+Use `AgentSession` or workflow APIs directly for in-process applications. Do not treat this package as an auth provider, user database, firewall, durable agent-result store, or public listener.
+
+## Inputs / request
+
+```ts
+const handler = createPrismHandler({
+  agents?: Record<string, Agent | PrismAgentExposure>,
+  workflows?: Record<string, PrismWorkflowExposure>,
+  schedules?: WorkflowSchedules | ((authorization, signal) => WorkflowSchedules),
+  authorize: async ({ request, operation, capabilityId }) => false | {
+    ownership: { tenantId?: string; accountId?: string; userId?: string },
+    metadata?: Record<string, unknown>,
+  },
+  basePath?: "/prism",
+  allowedHosts?: string[],
+  allowedOrigins?: string[],
+  redactor?: SecretRedactor,
+  limits?: PrismServerLimits,
+  disconnectAborts?: boolean,
+});
+```
+
+At least one non-empty ownership field must come from `authorize()`. Request JSON never chooses ownership.
+
+| Method and route | Authorization operation | Body |
+| --- | --- | --- |
+| `POST /prism/agents/:id/runs` | `agent.run` | `{ "input": string | Message | Message[] }` |
+| `POST /prism/agents/:id/stream` | `agent.stream` | same; SSE response |
+| `POST /prism/workflows/:id/runs` | `workflow.run` | `{ "input": unknown, "runId"?: string }` |
+| `POST /prism/workflows/:id/stream` | `workflow.stream` | same; SSE response |
+| `POST /prism/workflows/:id/enqueue` | `workflow.enqueue` | `{ "input": unknown, "runId"?: string }`; returns `202` queued handle |
+| `GET /prism/workflows/:id/runs/:runId` | `workflow.status` | none |
+| `DELETE /prism/workflows/:id/runs/:runId` | `workflow.cancel` | none |
+| `POST /prism/workflows/:id/runs/:runId/resume` | `workflow.resume` | `{ "decision": "approve" | "deny", "input"?: unknown, "expectedVersion": number }` |
+| `POST /prism/workflows/:id/runs/:runId/replay` | `workflow.replay` | `{ "fromNodeId": string, "runId"?: string }` |
+| `POST /prism/schedules/:id` | `schedule.create` | `{ "workflowId", "nextRunAt", "input"?, "intervalMs"?, "calculatorId"?, "paused"?, "metadata"? }` |
+| `GET /prism/schedules?status=&cursor=&limit=` | `schedule.list` | none |
+| `POST /prism/schedules/:id/pause` | `schedule.pause` | `{}` |
+| `POST /prism/schedules/:id/resume` | `schedule.resume` | `{ "nextRunAt"?: string }` |
+| `POST /prism/schedules/:id/trigger` | `schedule.trigger` | `{ "idempotencyKey": string }` |
+| `DELETE /prism/schedules/:id` | `schedule.delete` | none |
+
+POST routes require `Content-Type: application/json`. Capability/run IDs are bounded URL-safe identifiers. A custom `PrismAgentExposure.sessionFactory` can build sessions from authorized host context; otherwise an `Agent` creates a fresh session.
+
+## Outputs / response / events
+
+Direct routes return bounded JSON. Stream routes return `text/event-stream`; every event is one `data: <AgentEvent|WorkflowEvent>` frame. Status returns the ownership-scoped durable checkpoint record. Resume uses Phase 8 expected-version CAS. Cancel aborts active work or marks eligible durable checkpoints aborted.
+
+Errors use `{ "error": { "code", "message" } }`. Unknown routes/capabilities are `404`, authorization/policy denial `403`, malformed input `400`, unsupported content type `415`, body overflow `413`, concurrency overflow `429`, and result overflow `507`. Unexpected errors are generic and never include stacks.
+
+## Request/response example
+
+```json
+{
+  "request": { "method": "POST", "path": "/prism/agents/support/runs", "body": { "input": "Summarize this" } },
+  "response": { "status": "succeeded", "sessionId": "...", "runId": "...", "text": "Summary" }
+}
+```
+
+## Implementation example
+
+```ts
+import { createAgent, createMockProvider, providerDone, providerTextDelta } from "@arnilo/prism";
+import { createPrismHandler } from "@arnilo/prism-server";
+
+const agent = createAgent({
+  model: { provider: "mock", model: "offline" },
+  provider: createMockProvider([providerTextDelta("ready"), providerDone()]),
+});
+
+const handler = createPrismHandler({
+  agents: { support: agent },
+  authorize: async ({ request }) => request.headers.get("authorization") === "Bearer host-validated"
+    ? { ownership: { tenantId: "tenant-1", userId: "user-1" } }
+    : false,
+  allowedHosts: ["api.example.test"],
+  allowedOrigins: ["https://app.example.test"],
+});
+
+// Cloudflare/Bun/Deno-style: export { handler as fetch }.
+// Node/framework hosts adapt their request to Web Request and return Web Response.
+```
+
+## Extension and configuration notes
+
+- `basePath` defaults to `/prism`; URL root exposure is rejected.
+- Agent maps and workflow maps are immutable host selections. No registry/package discovery runs.
+- Workflow exposure requires its existing `WorkflowCheckpointAdapter`; no server-owned database exists.
+- Schedule exposure is optional and may be one service or an authorization-selected resolver. Returned service ownership must exactly match authorized tenant/account/user scope; otherwise request is forbidden.
+- `PrismWorkflowExposure.runOptions` can supply agent/tool/policy/resume-validator wiring. Server-owned ownership, signal, checkpoint, redactor, run ID, and event bus fields cannot be overridden.
+- Host/origin checks and CORS headers activate only when their allow-lists are configured. Hosts still own reverse-proxy trust and canonical host handling.
+
+Default/hard ceilings:
+
+| Limit | Default | Hard cap |
+| --- | ---: | ---: |
+| JSON request | 64 KiB | 1 MiB |
+| direct response | 1 MiB | 8 MiB |
+| SSE event | 64 KiB | 1 MiB |
+| SSE total | 10 MiB | 64 MiB |
+| SSE event count | 10,000 | 100,000 |
+| concurrent runs | 16 | 256 |
+| subscriber queue | 128 | 4,096 |
+| request/run timeout | 120 s | 30 min |
+
+## Security and performance notes
+
+- `authorize()` is required and runs for every matched operation before capability lookup or body execution. Return `false` on missing/invalid credentials. Do not trust caller ownership fields.
+- Use authorization metadata only for non-secret audit context. Never put credentials in metadata, input, route IDs, run IDs, checkpoints, events, or responses.
+- Configure `SecretRedactor` before runs. Redaction matches known secrets; it is not DLP.
+- Agent tools and workflow tool nodes still need their own `PermissionPolicy`, `ToolValidator`, and `ExecutionPolicy`. HTTP authorization does not replace side-effect policy.
+- Host and origin allow-lists are exact string matches. Configure reverse-proxy normalization, TLS, rate limiting, IP policy, CSRF/cookie policy, and authentication outside Prism.
+- SSE uses bounded upstream subscriber queues. Consumer cancellation aborts owned work by default and releases concurrency; set `disconnectAborts: false` only when the host deliberately owns background completion.
+- Source inputs/resource URLs remain host responsibilities and use existing resource/media SSRF policies. Server package does not fetch URLs.
+- Schedule routes never accept ownership from JSON. Services carry mandatory ownership and explicit workflow/calculator registries; route authorization cannot broaden either. Replay applies workflow ownership/hash/approval checks.
+- No agent status/reconnect store is invented. Durable reconnect/status/resume is the workflow path; persistent agent run querying remains a host persistence API.
+
+A2A routes are not added to `createPrismHandler()`. Install `@arnilo/prism-supervisor` and explicitly mount `createA2AHandler()` when protocol interoperability is required; this keeps cards and remote invoke absent from ordinary Prism servers.
+
+## Related APIs
+
+- [Agent/session runtime](agent-session-runtime.md): direct result and event stream semantics.
+- [Workflows](workflows.md): durable checkpoints, status, cancellation, and exact-once resume.
+- [MCP client and server exposure](mcp-tools.md): selected MCP capabilities and web-standard MCP transport.
+- [Host security guide](host-security.md): remote-boundary checklist.
+- [A2A interoperability](a2a.md): separately mounted A2A 1.0 handler/client.
+- [Release and install](release-and-install.md): optional package installation and profiles.

package/docs/settings-auth-trust-security.md

@@ -18,7 +18,7 @@ Use these APIs when a host wants one explicit place to compose settings, resolve
 - Node-only subpaths: `@arnilo/prism/node/settings` for caller-named JSON settings files and `@arnilo/prism/node/trust` for explicit trusted path roots with symlink-aware realpath checks.
 
 ## Outputs / response / events
-Settings and credential helpers return existing `SettingsProvider` and `CredentialResolver` contracts. `AgentConfig.settings` and `AgentConfig.credentials` are host-owned metadata for compatibility; `createAgent()` / `session.run()` do not call `settings.get()` or `credentials.resolve()`. Permission denial blocks tool execution, extension setup, and resource loader calls before side effects. A configured `AgentConfig.redactor` or `RunOptions.redactor` redacts provider requests, emitted `AgentEvent` payloads, stored `SessionEntry` values, and runtime `InstructionContext` input/history seen by instruction injectors.
+Settings and credential helpers return existing `SettingsProvider` and `CredentialResolver` contracts. These seams are host-owned outside `AgentConfig`; `createAgent()` / `session.run()` do not call `settings.get()` or `credentials.resolve()`. Permission denial blocks tool execution, extension setup, and resource loader calls before side effects. A configured `AgentConfig.redactor` or `RunOptions.redactor` redacts provider requests, emitted `AgentEvent` payloads, stored `SessionEntry` values, and runtime `InstructionContext` input/history seen by instruction injectors.
 
 ## Request/response example
 ```ts
@@ -47,17 +47,17 @@ const apiKey = await resolveCredentialValue(credentials, { name: "api", provider
 
 const agent = createAgent({
   model: { provider: "demo", model: "model" },
-  // host-owned metadata; runtime does not read/resolve these fields
-  settings,
-  credentials,
+  // Resolve credentials at the provider edge; register known secrets for redaction.
   redactor: apiKey ? createSecretRedactor([apiKey]) : undefined,
 });
+void settings;
+void credentials;
 void trust;
 void agent;
 ```
 
 ## Extension and configuration notes
-Root imports stay filesystem-free. Node settings files are caller-named and read once; optional missing files are skipped. Trust storage, prompts, approval UI, OAuth token storage, environment-variable selection, and persistent credentials belong in the host or an extension package. For Node.js hosts, [`@arnilo/prism-credentials-node`](credential-storage.md) provides encrypted-file and system-keychain backends. Passing `settings` / `credentials` on `AgentConfig` does not wire hidden runtime reads; hosts pass concrete values or resolvers to the provider/request edge that needs them.
+Root imports stay filesystem-free. Node settings files are caller-named and read once; optional missing files are skipped. Trust storage, prompts, approval UI, OAuth token storage, environment-variable selection, and persistent credentials belong in the host or an extension package. For Node.js hosts, [`@arnilo/prism-credentials-node`](credential-storage.md) provides encrypted-file and system-keychain backends. Pass concrete settings values or credential resolvers to the provider/request edge that needs them; do not place them on `AgentConfig`.
 
 ## Security and performance notes
 Prism does not sandbox host tools or extensions. Prism does not read environment variables, keychains, user config files, package manifests, resources, settings providers, credential resolvers, or project-local extensions unless the host explicitly wires those operations. Redaction is exact known-secret replacement only; it is not secret detection. Permission and trust checks are one operation per guarded call and add no workers, watchers, retries, network, or filesystem scans.

package/docs/sqlite-persistence.md

@@ -37,6 +37,7 @@ import { createSqlitePersistence } from "@arnilo/prism-session-store-sqlite";
 | `filename` | `string` | SQLite database path. Use `:memory:` for ephemeral tests. |
 | `wal` | `boolean` | Enable WAL journal mode. Defaults to `true`. |
 | `busyTimeoutMs` | `number` | SQLite `busy_timeout` in milliseconds. Defaults to `5000`. |
+| `feedbackRedactor` | `SecretRedactor` | Optional redaction for feedback comment/tags/metadata before insert. |
 | `fileMode` | `number` | Unix file mode for newly created database files. Defaults to `0o600`. |
 | `database` | `Database` | Advanced: supply an existing `better-sqlite3` handle (caller owns lifecycle). |
 
@@ -51,7 +52,7 @@ import { createSqlitePersistence } from "@arnilo/prism-session-store-sqlite";
 | `SessionStore.readBranchPath` | Recursive ancestor query from `leafId` (or latest leaf) in root→leaf order. |
 | `RunLedger.append*` | Inserts run/event/tool/usage rows; events receive monotonic per-run `sequence` values. |
 | `ProductionPersistenceStore.query*` | Parameterized cursor pagination on indexed columns. |
-| `checkpoints` | Generic versioned `CheckpointStore` backed by `prism_checkpoints`; ownership, CAS/fencing checks, and bounded pagination. |
+| `checkpoints` | Generic versioned `CheckpointStore` backed by `prism_checkpoints`; ownership, CAS/fencing checks, bounded pagination, and workflow suspended/denied/schedule/state/replay values without a schema migration. |
 | `leases` | Atomic `LeaseStore` backed by `prism_leases`; database-clock expiry, opaque renew/release token, monotonic takeover fence. |
 | `close()` | Closes the underlying database when the adapter opened it. |
 
@@ -98,7 +99,7 @@ For resume/timeline flows, use `queryRuns`, `queryEvents`, `queryToolCalls`, and
 - The package is optional and workspace-local; `@arnilo/prism` core has no SQLite dependency.
 - Hosts choose the database path and own backup, retention enforcement, and filesystem permissions.
 - `SessionAppendOptions` idempotency rows are durable in `prism_session_append_idempotency` and survive reopen.
-- Schema version **1** (`001_init`) matches `@arnilo/prism/testing/persistence-schema` — PostgreSQL adapters share the same model with dialect-local DDL.
+- Schema version **3** applies `001_init`, additive `002_usage_scope`, and `003_run_feedback`. Migration 003 adds immutable `prism_run_feedback` rows with run FK/cascade deletion and owner/run/trace cursor indexes. `persistence.feedback` validates exact run ownership, bounds/redacts through optional `feedbackRedactor`, queries bounded pages, and deletes only exact-owned IDs. PostgreSQL shares the same model with dialect-local DDL.
 - Pass an existing `better-sqlite3` `Database` via `database` when your host already manages connections.
 
 ## Security and performance notes
@@ -118,5 +119,5 @@ For resume/timeline flows, use `queryRuns`, `queryEvents`, `queryToolCalls`, and
 - [Run ledger conformance](run-ledger-conformance.md): `assertRunLedgerConforms` / `runRunLedgerConformance`.
 - [Persistence, credentials, and multimodality primitives](persistence-credentials-multimodality-primitives.md): package matrix and threat model.
 - [Node JSONL session store](node-jsonl-session-store.md): dev-only single-process alternative.
-- [Workflows](workflows.md): adapt `persistence.checkpoints` and pass `persistence.leases` to `createWorkflowCoordinator()` for durable multi-process workflow execution.
+- [Workflows](workflows.md): adapt `persistence.checkpoints` and pass `persistence.leases` to `createWorkflowCoordinator()` and `createWorkflowSchedules()` for durable background execution and schedules.
 - [Migration guide](migration.md): moving from JSONL/in-memory to database-backed persistence.

package/docs/supervisors.md

@@ -0,0 +1,71 @@
+# Supervisor delegation
+
+## What it does
+
+`@arnilo/prism-supervisor` adds optional runtime-selected delegation to an explicit local child allow-list. It returns normal `AgentRunResult` values and does not modify core `createAgent()` or deterministic workflows.
+
+## When to use it
+
+Use a supervisor when a host or agent must choose a child dynamically. Use `@arnilo/prism-workflows` for known DAGs, durable checkpoints, schedules, replay, or human suspension.
+
+## Inputs / request
+
+| API/field | Meaning |
+| --- | --- |
+| `createSupervisor({ ownership, children })` | Creates one ownership-scoped supervisor. |
+| `SupervisorChild.createAgent(context)` | Child-owned factory; receives derived resource/thread IDs, narrowed permission, abort signal, and nested `delegate`. |
+| `delegate({ childId, input, threadId?, limits?, signal? })` | Invokes one allow-listed child. Input is text and byte-bounded. |
+| `hooks.before` | May reject, modify redacted input, or narrow limits/policy. |
+| `hooks.after` | Observes redacted terminal summary; failures cannot alter settled result. |
+| `limits` | Depth 4/16, active children 4/32, input 64 KiB/1 MiB, steps 8/64, tools 32/256, tokens 20k/1m, timeout 60s/30m, event queue 128/4096 default/hard. |
+
+## Outputs / response / events
+
+`delegate()` returns the child's `AgentRunResult` or throws its `AgentRunError`/a supervisor denial or limit error. `subscribe()` emits bounded `delegation_started`, `delegation_finished`, `delegation_rejected`, and `delegation_error` metadata events.
+
+## Request/response example
+
+```json
+{"childId":"research","input":"Check primary sources","limits":{"maxTokens":4000}}
+```
+
+## Implementation example
+
+```ts
+import { createSupervisor } from "@arnilo/prism-supervisor";
+
+const supervisor = createSupervisor({
+  ownership: { tenantId: "tenant", userId: "user" },
+  permission: parentPolicy,
+  children: {
+    research: {
+      permission: readOnlyPolicy,
+      createAgent: ({ resourceId, threadId, permission, delegate }) =>
+        createResearchAgent({ resourceId, threadId, permission, delegate }),
+    },
+  },
+  hooks: { before: ({ input }) => ({ input, limits: { maxTokens: 4000 } }) },
+});
+
+const result = await supervisor.delegate({ childId: "research", input: "Check sources" });
+```
+
+## Extension and configuration notes
+
+Child factories resolve their own providers/credentials and construct context/memory using the supplied IDs. Parent, child, returned-agent, budget, and hook permission policies are AND-composed. Child/request/hook limits can only lower inherited limits. A nested factory can call the supplied `delegate()`; immutable path state rejects cycles and depth overflow.
+
+## Security and performance notes
+
+- Child IDs are explicit; no package/provider discovery occurs.
+- `resourceId` and `threadId` include supervisor/delegation/child identity. Do not replace them with parent memory IDs.
+- Tool budget is checked before side effects. Token usage is enforced on terminal aggregate usage and can exceed by at most one provider turn because providers report tokens after generation.
+- Abort and timeout cover hooks, child creation, nested delegation, and the run. Host child code must cooperate with `AbortSignal`.
+- Redaction applies before hook input, run metadata/results, completion hooks, and events. Child credentials are never supplied in delegation context.
+- Static workflows remain smaller and more reproducible for known graphs.
+
+## Related APIs
+
+- [A2A interoperability](a2a.md): remote protocol boundary.
+- [Workflows](workflows.md): preferred deterministic orchestration.
+- [Working and semantic memory](working-and-semantic-memory.md): child scope construction.
+- [Host security](host-security.md): permission and credential boundaries.