@arnilo/prism 0.0.4 → 0.0.5

package/docs/performance.md

@@ -156,6 +156,215 @@ Provider SSE remained at the frozen 380 MiB/s / +1.7 MiB heap snapshot. Media an
 
 The ledger percentage overhead is intentionally not a threshold: its no-ledger baseline is below 1 ms, making the percentage unstable while absolute added latency remains about 1 ms. JSONL's append path is intentionally O(n²) across repeated appends because it rereads for corruption/conflict checks; move production or high-volume workloads to SQLite/PostgreSQL rather than weakening validation.
 
+### 0.0.5 Phase 0 baseline (2026-07-15)
+
+Scope froze at commit `f5128a816ae204c52f3e2f089de71c99bd5de6d4`. Measurement host: Node v24.18.0, npm 11.16.0, Linux 7.1.3 x86_64, AMD Ryzen 9 PRO 7940HS (16 logical CPUs). Supported package runtime remains Node >=20. These are dated local comparison points, not portable CI wall-clock assertions.
+
+| Surface | Workload | Result |
+| --- | --- | --- |
+| Network-free tests | `npm test` | 25.750 s; 1,475 tests, 1,450 pass, 25 explicit live skips, 0 fail |
+| Release readiness | `npm run sdk:ready` | 54.341 s; typecheck, tests, examples, builds, and 24 dry-run packs pass |
+| Provider/agent stream | One mock run with 5,000 one-character text deltas and a concurrently drained 8,192-event subscriber | 3.78 ms median |
+| Tool dispatch | Six independent 20 ms tools, concurrency 1 | 121.05 ms median |
+| Tool dispatch | Same calls, concurrency 2 | 60.65 ms median (2.00x speedup) |
+| Workflow runner | Existing bounded 1,000-node chain, configured concurrency 8 | 9.66 ms median |
+| Package artifacts | All 24 dry-run tarballs | 542,993 packed bytes; 2,084,900 unpacked bytes aggregate |
+| Root artifact | `@arnilo/prism@0.0.4` dry-run tarball | 346.0 kB packed; 1.3 MB unpacked; 196 files |
+| Installed workspace | Current root `node_modules` | 72 MiB |
+
+Synthetic stream/tool/workflow values are medians of seven measured runs after one warm-up and contain no network, database, or exporter I/O. The temporary benchmark reused public `AgentSession`, `dispatchToolCallsInOrder`, and `@arnilo/prism-workflows` APIs; it was not added to CI because this phase records a baseline rather than creating hardware-sensitive tests.
+
+Repository size at the same commit, counted from `src/` and `packages/` while excluding `dist/`:
+
+| Area | Files | Lines |
+| --- | ---: | ---: |
+| Production TypeScript | 189 | 26,828 |
+| Test TypeScript | 144 | 23,535 |
+| Documentation Markdown | 70 | 12,662 |
+| Numbered plans | 58 | 24,270 |
+| TypeScript examples | 39 | 3,134 |
+
+Prism has no project generator before Phase 5, so a generated-Prism-project install/build size is **not applicable** at this baseline. The closest current install figure is the 72 MiB development workspace; it is not a scaffold target. The comparison Mastra default scaffold measured during the review used 439 MB `node_modules`, 300 MB build output, and 427 installed packages. Phase 5 must establish a real generated Prism project baseline and keep unselected storage, telemetry, eval, memory, server, and workflow dependencies absent.
+
+See [Review coverage — 2026-07-15](review-coverage-2026-07-15.md) for scope, primitive, package, and threat-boundary ownership.
+
+### 0.0.5 Phase 2 verification (2026-07-15)
+
+Same Phase 0 host and seven-run warm benchmark. Runtime correctness changes stayed inside frozen ceilings:
+
+| Surface | Result |
+| --- | --- |
+| Network-free tests | 27.992 s; 1,485 tests, 1,460 pass, 25 explicit live skips, 0 fail |
+| `npm run sdk:ready` | 55.598 s; typecheck, examples, tests, builds, and all 24 dry-run packs pass |
+| Provider/agent stream, 5,000 deltas | 3.54 ms median (Phase 0: 3.78 ms) |
+| Six 20 ms tools, concurrency 1 / 2 | 121.22 ms / 60.63 ms (2.00x speedup retained) |
+| Workflow 1,000-node chain | 10.31 ms median (well below 1 s ceiling) |
+| Root dry-run tarball | 361.2 kB packed, 1.3 MB unpacked, 197 files |
+
+Usage aggregation performs one constant-size accumulator update per terminal provider turn. Telemetry retains only active span metadata and removes every terminal/detached entry. Complete media resolution is sequential, rejects item count and inline estimates before I/O, and retains at most the request budget plus one per-item-bounded candidate before failing an aggregate overflow. Sandbox output still streams into the existing bounded `OutputAccumulator`; no adapter-side response buffer was added.
+
+### 0.0.5 Phase 4 verification (2026-07-15)
+
+Optional `@arnilo/prism-evals` adds package-local scoring without changing core run latency. Validation stayed within the frozen release gate:
+
+| Surface | Result |
+| --- | --- |
+| Network-free tests | 1,503 tests, 1,478 pass, 25 explicit live skips, 0 fail |
+| `npm run sdk:ready` | typecheck, examples, tests, builds, and all 25 dry-run packs pass |
+| Evals dry-run tarball | 35.4 kB unpacked package payload |
+| Profile bundles | unchanged; evals remains opt-in until size/use review |
+
+Experiment concurrency is capped at 32 workers and defaults to 1. Scorers operate on `AgentRunResult` references plus dataset item metadata rather than duplicating event ledgers.
+
+### 0.0.5 Phase 5 verification (2026-07-15)
+
+`prism init` lands as a stdlib-only CLI subcommand with checked-in templates under `templates/init/`.
+
+| Surface | Result |
+| --- | --- |
+| Default generated sources | 8 files / ~3.3 KB |
+| Default clean consumer install (`@arnilo/prism` + TypeScript tooling) | ~27.5 MB `node_modules` |
+| Mastra comparator | 439 MB install / 300 MB build / 427 packages |
+| Default dependencies | `@arnilo/prism` only; no storage, telemetry, eval, memory, server, or workflow packages unless `--with-*` / provider flags select them |
+| Offline proof | packed core tarball → `npm install` → `npm run typecheck` → `npm test` (mock provider) |
+
+### 0.0.5 Phase 6 verification (2026-07-15)
+
+Optional `@arnilo/prism-provider-ai-sdk` adapts AI SDK `LanguageModelV4` streams to Prism without adding an AI SDK dependency to core.
+
+| Surface | Result |
+| --- | --- |
+| Supported specification | `@ai-sdk/provider@^4` (`LanguageModelV4`) |
+| Adapter behavior | incremental stream translation; unsupported content fails before `doStream`; abort owned by Prism `request.signal` |
+| Network-free tests | 1,522 tests, 1,497 pass, 25 explicit live skips, 0 fail |
+| `npm run sdk:ready` | typecheck, examples, tests, builds, and all 26 dry-run packs pass |
+| AI SDK adapter dry-run tarball | 6.5 kB packed / 22.5 kB unpacked / 16 files |
+| Profile bundles | unchanged; AI SDK adapter remains opt-in until size/use review |
+| Publishable graph | 26 packages |
+
+### 0.0.5 Phase 7 verification (2026-07-15)
+
+Optional `@arnilo/prism-memory` adds working memory and semantic recall without changing core session stores.
+
+| Surface | Result |
+| --- | --- |
+| Contracts | package-owned `Embedder`, `VectorStore`, `WorkingMemoryStore`, `createMemory` |
+| Adapters | in-memory reference + PostgreSQL/pgvector production path |
+| Injection | existing `ContextProvider` seam; opt-in working-memory processor |
+| Profile bundles | unchanged; memory remains opt-in until size/use review |
+| Publishable graph | 27 packages |
+| Network-free tests | 1,538 tests, 1,513 pass, 25 explicit live skips, 0 fail |
+| `npm run sdk:ready` | pass |
+| Memory dry-run tarball | 17.9 kB packed / 76.6 kB unpacked / 32 files |
+
+### 0.0.5 Phase 8 verification (2026-07-15)
+
+Durable human suspension extends existing workflow checkpoint JSON/CAS; no worker polling loop, package, dependency, or database migration was added.
+
+| Surface | Result |
+| --- | --- |
+| Focused workflow suite | 43 tests pass, 0 fail |
+| Network-free tests | 1,547 tests, 1,522 pass, 25 explicit live skips, 0 fail |
+| `npm run sdk:ready` | typecheck, examples, tests, builds, and all 27 dry-run packs pass |
+| Workflow dry-run tarball | 25.7 kB packed / 121.6 kB unpacked / 34 files |
+| Coordinator behavior | `suspended` absent from queued/running poll; zero worker/lease retained |
+| Storage | existing bounded checkpoint JSON/category; no SQLite/PostgreSQL migration |
+
+### 0.0.5 Phase 9 verification (2026-07-16)
+
+Optional `@arnilo/prism-rag` reuses Phase 7 vector contracts and adds no core path, parser dependency, network loader, or profile activation.
+
+| Surface | Result |
+| --- | --- |
+| Focused RAG suite | 9 tests pass, 0 fail |
+| Network-free tests | 1,561 tests, 1,536 pass, 25 explicit live skips, 0 fail |
+| `npm run sdk:ready` | typecheck, examples, tests, builds, and all 28 dry-run packs pass |
+| RAG dry-run tarball | 9.0 kB packed / 34.6 kB unpacked / 22 files |
+| Index bounds | chunk/document/count/metadata caps; embed batches default 32, hard 128 |
+| Retrieval bounds | top-K default 5/hard 32; candidates default 20/hard 128; result 64/512 KiB; context 2,000/8,000 estimated tokens |
+| Profile bundles | unchanged; RAG and memory remain explicit opt-ins |
+
+### 0.0.5 Phase 10 verification (2026-07-16)
+
+Optional `@arnilo/prism-server` and MCP server-direction APIs compose existing agent/workflow/tool/SDK primitives; no core path, framework/listener, auth provider, database, or profile activation was added.
+
+| Surface | Result |
+| --- | --- |
+| Focused server suites | 6 Web handler tests + 4 MCP server tests pass; existing 12 MCP client tests remain green |
+| Network-free tests | 1,576 tests, 1,551 pass, 25 explicit live skips, 0 fail |
+| `npm run sdk:ready` | typecheck, examples, tests, builds, and all 29 dry-run packs pass |
+| Server dry-run tarball | 8.4 kB packed / 34.4 kB unpacked / 12 files |
+| MCP dry-run tarball | 11.6 kB packed / 45.0 kB unpacked / 20 files |
+| Web handler bounds | request 64 KiB, result 1 MiB, event 64 KiB, stream 10 MiB/10k events, queue 128, concurrency 16, timeout 120 s by default; all have hard caps |
+| MCP server bounds | call result 1 MiB, calls 16, timeout 60 s; HTTP request 1 MiB, response 2 MiB, requests 32 by default; all have hard caps |
+| Profile bundles | unchanged; server remains explicit opt-in |
+
+### 0.0.5 Phase 11 verification (2026-07-16)
+
+Workflow schedules, background runs, composition, state, and replay reuse the existing workflow package plus generic checkpoint/lease stores. No package, runtime dependency, SQL migration, listener, cron parser, or auto-started worker was added.
+
+| Surface | Result |
+| --- | --- |
+| Focused workflow/server suites | 54 workflow tests + 8 Web handler tests pass, 0 fail |
+| Network-free tests | 1,589 tests, 1,564 pass, 25 explicit live skips, 0 fail |
+| `npm run sdk:ready` | typecheck, examples, tests, builds, and all 29 dry-run packs pass |
+| Workflow dry-run tarball | 34.7 kB packed / 171.5 kB unpacked / 38 files |
+| Server dry-run tarball | 9.9 kB packed / 45.2 kB unpacked / 12 files |
+| Synthetic schedule bound | 100 in-memory creates: 1.28 ms; scan 100 / claim+enqueue 16 due fires: 6.64 ms |
+| Synthetic composition/replay | depth-8 nested run: 2.73 ms; 100-node source: 35.42 ms; replay 50 nodes: 21.17 ms |
+| State/replay ceilings | state 64/512 KiB; history 32/128; nested depth 8/32; replay depth 8/32 default/hard |
+| Schedule ceilings | page 100/500; claims 16/256; input 256 KiB/1 MiB; 1s idle timer; 30s fire lease defaults |
+
+Synthetic timings are one local Node v24.18.0 run over memory adapters with no network/database I/O; finite limits and behavior tests, not wall-clock numbers, are CI gates.
+
+### 0.0.5 Phase 12 verification (2026-07-16)
+
+Run feedback adds no package or runtime dependency. Memory/SQLite/PostgreSQL implementations share bounded append/query/delete semantics; OTel projection accepts only fixed scalar metadata.
+
+| Surface | Result |
+| --- | --- |
+| Focused feedback/eval/SQLite/OTel tests | 35 tests pass, 0 fail; PostgreSQL DDL suite passes and live feedback conformance is env-gated |
+| Synthetic memory feedback | 1,000 bounded appends: 3.82 ms; 100 filtered 100-row queries over 1,000 records: 11.53 ms |
+| Core dry-run tarball | 398.1 kB packed / 1.4 MB unpacked / 219 files |
+| Evals dry-run tarball | 9.8 kB packed / 38.4 kB unpacked / 26 files |
+| OTel dry-run tarball | 6.3 kB packed / 26.5 kB unpacked / 8 files |
+| SQLite/PostgreSQL tarballs | 17.7/18.1 kB packed; 89.8/89.8 kB unpacked |
+| Feedback limits | comment 4/16 KiB; tags 16/64; links 16/64; metadata 16/64 KiB; pages 100/500 default/hard |
+
+Metrics came from one local Node v24.18.0 memory-adapter run. SQL correctness/indexing/migration behavior and hard bounds are gates; local timings are not release thresholds.
+
+### 0.0.5 Phase 13 verification (2026-07-16)
+
+Supervisor/A2A stays in one optional zero-runtime-dependency package; core and profile bundles gained no import, listener, worker, protocol SDK, or network activation.
+
+| Surface | Result |
+| --- | --- |
+| Focused supervisor/A2A suite | 11 tests pass, 0 fail; local delegation, policy/budget/abort/redaction, card signatures, server/client/stream bounds |
+| Synthetic local delegation | 100 sequential mock child results: 11.83 ms |
+| Synthetic in-process A2A | 100 card discovery + JSON-RPC mock round trips: 34.17 ms |
+| Supervisor dry-run tarball | 15.3 kB packed / 69.4 kB unpacked / 22 files |
+| Local hard ceilings | depth 16; active 32; message 1 MiB; steps 64; tools 256; tokens 1m; timeout 30m; event queue 4096 |
+| A2A hard ceilings | request/card/event 1 MiB; response 8 MiB; stream 64 MiB/100k events; concurrency 256; timeout 30m |
+
+Timings are one local Node v24.18.0 run over mock agents and an in-process fetch adapter. Bounds, protocol validation, signature/auth/origin checks, and offline behavior tests are release gates; timings are not thresholds.
+
+### 0.0.5 Phase 14 release-candidate verification (2026-07-16)
+
+| Surface | Result |
+| --- | --- |
+| Default network-free test | 32.247 s, below 60 s budget |
+| Full SDK readiness | 70.560 s; build/typecheck/examples/tests/30 pack dry-runs |
+| Test matrix | 1,618 total; 1,593 pass; 25 explicit live skips; 0 fail |
+| Node compatibility | Node 20.20.2 imports 44 built root/package export targets; Node 24.18.0 runs full matrix |
+| PostgreSQL/pgvector | 29 live checks pass in fresh `pgvector/pgvector:pg16` container |
+| Packed artifact set | 30 tarballs / 699 files; post-bundle snapshot ~690.6 kB packed / 2.64 MB unpacked |
+| Core artifact | post-bundle snapshot ~403.7 kB packed / 1.46 MB unpacked / 221 files |
+| Generated default project | under 50 KiB source and under 50 MiB installed; packed-core typecheck/test pass |
+| Fresh packed journey | 30 packages install/import and Phase 1-13 optional composition pass in ~8.0 s |
+| Registry/publish preview | 30/30 versions available; 30/30 dependency-ordered provenance dry-runs pass |
+
+No performance ceiling was raised. Core grew from Phase 0's 346.0 kB packed baseline to ~403.7 kB after documented APIs/templates, while the full package set remains ~690.6 kB packed. Follow-up review includes all six Phase 4-13 capability packages through `prism-all` and AI SDK interoperability through `prism-providers`; focused base/code/SDK profiles remain unchanged and no capability auto-activates. Manifest tarballs remain tiny: providers 1.4 kB and all 1.6 kB packed.
+
 ## Related APIs
 
 - [Agent events](agent-events.md): `SubscribeOptions` and `event_subscriber_overflow` event details.

package/docs/postgres-persistence.md

@@ -39,6 +39,7 @@ import { createPostgresPersistence } from "@arnilo/prism-session-store-postgres"
 | `connectionString` | `string` | Create an adapter-owned bounded pool when `pool` is omitted. |
 | `schema` | `string` | PostgreSQL schema for Prism tables. Defaults to `"prism"`. Validated and double-quoted. |
 | `poolMax` | `number` | Maximum pool size for adapter-owned pools. Defaults to `10`. |
+| `feedbackRedactor` | `SecretRedactor` | Optional redaction for feedback comment/tags/metadata before insert. |
 | `poolConfig` | `PoolConfig` | Additional `pg` options (TLS, idle timeout, application name, etc.). |
 
 Hosts own TLS (`ssl` in `poolConfig`), credentials, connection limits, and backup/retention enforcement.
@@ -54,7 +55,7 @@ Hosts own TLS (`ssl` in `poolConfig`), credentials, connection limits, and backu
 | `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 with tenant/account/user filters. |
-| `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()` | Ends the pool when the adapter created it from `connectionString`. |
 
@@ -115,7 +116,7 @@ PRISM_TEST_POSTGRES_URL="$DATABASE_URL" npm run test:postgres --workspace @arnil
 - The package is optional and workspace-local; `@arnilo/prism` core has no PostgreSQL dependency.
 - Schema names must match `^[a-zA-Z_][a-zA-Z0-9_]*$`; the adapter quotes them and never interpolates user values into identifier positions.
 - `SessionAppendOptions` idempotency rows are durable in `prism_session_append_idempotency` and survive reopen.
-- Schema version **1** (`001_init`) matches `@arnilo/prism/testing/persistence-schema` — SQLite 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. SQLite shares the same model with dialect-local DDL.
 - Pass an existing `pg` `Pool` when your host already manages pooling, TLS, and credential rotation.
 
 ## Security and performance notes
@@ -126,7 +127,7 @@ PRISM_TEST_POSTGRES_URL="$DATABASE_URL" npm run test:postgres --workspace @arnil
 - **Redaction upstream.** Event and tool-call payloads may contain secrets; redact before ledger writes. The adapter does not scan or rewrite row contents.
 - **Bounded pool.** Adapter-owned pools default to `max: 10`. Hosts with heavy concurrency should supply their own pool sizing.
 - **Indexed operations.** Append, parent validation, idempotency dedup, branch reads, and pagination use the indexes documented in [Database persistence](database-persistence.md); normal paths avoid sequential scans.
-- **Migration locking.** `pg_advisory_xact_lock` prevents concurrent `001_init` races when multiple processes open the adapter at once.
+- **Migration locking.** `pg_advisory_xact_lock` prevents concurrent migration races when multiple processes open the adapter at once.
 - **Tenant isolation.** `tenant_id` / `account_id` / `user_id` columns participate in query filters; hosts must still scope writes correctly.
 - **Benchmark target.** Indexed append + paginated branch read on a warm pool should stay under **50 ms p95** for local/CI-sized datasets (≤100k entries per session); measure with your pool size and hardware before production sizing.
 
@@ -137,5 +138,6 @@ PRISM_TEST_POSTGRES_URL="$DATABASE_URL" npm run test:postgres --workspace @arnil
 - [Session store conformance](session-store-conformance.md): `assertSessionStoreConforms` / `runSessionStoreConformance`.
 - [Run ledger conformance](run-ledger-conformance.md): `assertRunLedgerConforms` / `runRunLedgerConformance`.
 - [Persistence, credentials, and multimodality primitives](persistence-credentials-multimodality-primitives.md): package matrix and threat model.
-- [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.
+- [Working and semantic memory](working-and-semantic-memory.md): optional `@arnilo/prism-memory` PostgreSQL/pgvector working + semantic stores (separate from session/run persistence).
 - [Migration guide](migration.md): moving from JSONL/in-memory to database-backed persistence.

package/docs/provider-conformance.md

@@ -149,5 +149,6 @@ The helpers are a testing subpath only. Provider packages can use them with thei
 
 - [Provider layer](provider-layer.md): `AIProvider`, provider events, and mock provider.
 - [Provider packages](provider-packages.md): package authors can use conformance helpers for adapters.
+- [AI SDK provider adapter](providers/ai-sdk.md): optional `LanguageModelV4` bridge tested with a fake AI SDK model.
 - [OpenAI-compatible provider](providers/openai-compatible.md): optional provider adapter tested with mocked streams.
 - [Public contracts](public-contracts.md): provider request/event/usage contracts.

package/docs/provider-packages.md

@@ -63,6 +63,8 @@ First-party providers map generic `ModelConfig.parameters.maxTokens` to real out
 
 Phase 12 adds explicit npm workspaces for [`@arnilo/prism-provider-openai`](providers/openai.md), [`@arnilo/prism-provider-opencode-go`](providers/opencode-go.md), [`@arnilo/prism-provider-openrouter`](providers/openrouter.md), [`@arnilo/prism-provider-zai`](providers/zai.md), [`@arnilo/prism-provider-kimi`](providers/kimi.md), and [`@arnilo/prism-provider-neuralwatt`](providers/neuralwatt.md). Each package starts with a side-effect-free `create*ProviderPackage()` export, README, TypeScript build, network-free default tests, and real opt-in live smoke tests.
 
+Phase 6 also adds optional [`@arnilo/prism-provider-ai-sdk`](providers/ai-sdk.md), which adapts a host-owned AI SDK `LanguageModelV4` to Prism's `AIProvider`. It joins `@arnilo/prism-providers` as the seventh adapter while remaining independent from the six HTTP implementations.
+
 Provider live tests are real smoke tests gated by `PRISM_LIVE_PROVIDER_TESTS=1` plus the provider-specific API key (`OPENAI_API_KEY`, `OPENROUTER_API_KEY`, `KIMI_API_KEY`, `ZAI_API_KEY`, `NEURALWATT_API_KEY`, or `OPENCODE_API_KEY`). They cover text generation, tool-call loop behavior, abort/error paths where supported, and no-secret-leak assertions; they skip by default and never run in release verification.
 
 These workspaces still follow the same rule as external packages: no provider SDK dependency, catalog fetch, env scan, keychain/file credential lookup, shell auth command, OAuth login, or live provider call runs by default. `@arnilo/prism-provider-openai` now registers OpenAI Responses and OpenAI Codex providers from caller-supplied credentials only. `@arnilo/prism-provider-opencode-go` now registers static OpenCode Go metadata and package-local OpenAI/Anthropic-compatible routes from caller-supplied credentials only. `@arnilo/prism-provider-openrouter` now registers an app-controlled OpenRouter catalog with routing/reasoning/cache passthrough and no setup catalog fetch. `@arnilo/prism-provider-zai` now registers static GLM metadata with Z.AI thinking/reasoning/tool-stream request mapping. `@arnilo/prism-provider-kimi` now registers Kimi Coding Anthropic-compatible behavior by default and optional Moonshot metadata only when requested. `@arnilo/prism-provider-neuralwatt` now registers static featured model metadata with NeuralWatt reasoning_effort/thinking_token_budget/chat_template_kwargs request mapping, SSE comment tolerance, an opt-in `listNeuralWattModels()` helper for explicit `/v1/models` discovery, `getNeuralWattQuota()` for on-demand account balance/usage/energy, `neuralWattEventsWithTelemetry()`/`mapNeuralWattTelemetry()` for `: energy`/`: cost` telemetry, and `classifyNeuralWattError()` for retry classification. None of these helpers run during package setup or generation.

package/docs/providers/ai-sdk.md

@@ -0,0 +1,113 @@
+# AI SDK provider adapter
+
+## What it does
+
+`@arnilo/prism-provider-ai-sdk` adapts a host-supplied AI SDK `LanguageModelV4` into a Prism `AIProvider`. It maps Prism messages, tools, and structured-output options into `doStream` call options, then translates stream parts into Prism provider events incrementally.
+
+Supported specification: `@ai-sdk/provider` **v4** (`specificationVersion: "v4"`). Core `@arnilo/prism` does not depend on the AI SDK.
+
+## When to use it
+
+Use this package when a host already creates AI SDK language models and wants them inside Prism agent/session loops without adding another first-party HTTP provider.
+
+Do not use it as a credential store, model catalog, or high-level `streamText`/`generateText` replacement. Hosts keep owning credentials inside the supplied model.
+
+## Inputs / request
+
+```ts
+import { createAiSdkProvider } from "@arnilo/prism-provider-ai-sdk";
+
+createAiSdkProvider(options: {
+  model: LanguageModelV4;
+  id?: string;
+}): AIProvider
+```
+
+| Field | Type | Purpose |
+| --- | --- | --- |
+| `model` | `LanguageModelV4` | Host-owned AI SDK language model. |
+| `id` | `string` | Prism provider id. Defaults to `ai-sdk:<model.provider>` or `ai-sdk`. |
+
+Mapped request surfaces:
+
+| Prism | AI SDK |
+| --- | --- |
+| `messages` | `LanguageModelV4Prompt` |
+| `tools` | `LanguageModelV4FunctionTool[]` with JSON Schema `inputSchema` |
+| `options.structuredOutput` | `responseFormat: { type: "json", name, schema }` |
+| `model.parameters` | `maxOutputTokens`, `temperature`, `topP`, `topK`, penalties, `seed`, `stopSequences` |
+| `request.signal` | `abortSignal` (always wins over adapter options) |
+| `options.headers` | extension headers only; model owns auth |
+
+Unsupported content fails before `doStream` (for example unresolved `resourceUri`, audio/file/document without declared capability, `tool_call_delta` in history, non-text system content).
+
+## Outputs / response / events
+
+| AI SDK stream part | Prism event |
+| --- | --- |
+| `text-delta` | `content_delta` text |
+| `reasoning-delta` | `content_delta` thinking |
+| `tool-input-start` / `tool-input-delta` | `tool_call_delta` |
+| `tool-call` (client-executed) | `tool_call` |
+| `finish` usage | `usage` then `done` |
+| `error` / thrown / abort | redacted `error` |
+
+Provider-executed tool calls, files/sources/custom parts, warnings, and raw chunks are ignored rather than silently converted into unsupported Prism content.
+
+## Request/response example
+
+```json
+{
+  "prompt": [{ "role": "user", "content": [{ "type": "text", "text": "hello" }] }],
+  "tools": [{ "type": "function", "name": "echo", "inputSchema": { "type": "object" } }],
+  "responseFormat": {
+    "type": "json",
+    "name": "Answer",
+    "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } }
+  }
+}
+```
+
+## Implementation example
+
+```ts
+import { createAgent } from "@arnilo/prism";
+import { createAiSdkProvider } from "@arnilo/prism-provider-ai-sdk";
+
+const provider = createAiSdkProvider({ model: hostCreatedLanguageModelV4 });
+
+const agent = createAgent({
+  provider,
+  model: {
+    provider: provider.id,
+    model: hostCreatedLanguageModelV4.modelId,
+    capabilities: { tools: true, streaming: true, structuredOutput: true, input: ["text"] },
+  },
+});
+
+const result = await agent.createSession().run("Summarize this");
+console.log(result.text);
+```
+
+## Extension and configuration notes
+
+- Peer dependency: `@ai-sdk/provider@^4.0.0`. Upgrade policy tracks one specification major at a time.
+- First-party HTTP providers remain independent; this adapter is available directly, through `@arnilo/prism-providers`, or through `@arnilo/prism-all`. Installation does not select a model or invoke AI SDK.
+- `options.compat` / `options.extra` pass through as AI SDK `providerOptions.prism`.
+- Export helpers `toAiSdkCallOptions`, `toAiSdkPrompt`, and `mapAiSdkStream` for tests and custom hosts.
+
+## Security and performance notes
+
+- Host credentials stay inside the supplied AI SDK model. The adapter never reads env keys or credential stores.
+- Abort and resource limits come from Prism `request.signal`; adapter options cannot replace that bound.
+- Stream parts are translated incrementally with no full-response buffering and no duplicate model call.
+- Unsupported content fails closed before model invocation. Errors use Prism `providerError` redaction.
+- Provider metadata/warnings are not emitted as prompt or tool content.
+
+## Related APIs
+
+- [Provider packages](../provider-packages.md)
+- [Provider conformance](../provider-conformance.md)
+- [Provider layer](../provider-layer.md)
+- [Structured output](../structured-output.md)
+- [Agent session runtime](../agent-session-runtime.md)

package/docs/public-contracts.md

@@ -15,7 +15,7 @@ Current contract groups:
 - Extensions/middleware: `ExtensionLifecycleEventName`, `ExtensionEvent`, `Extension`, `ExtensionAPI`, `MiddlewareHookName`, `Middleware`, `MiddlewareNext`, `MiddlewareRegistry`
 - Configuration/manifests: `ConfigProvider`, `ConfigLayer`, `ConfigLoadContext`, `PrismManifest`, `ManifestContributionDeclaration`, `ManifestResourceDeclaration`, `ManifestContributionKind`
 - Stores/resources/settings/credentials/compaction/retry/cache helpers: `SessionEntry`, `SessionStore`, `StoreFactory`, `Resource`, `ResourceLoader`, `ResourceLoadContext`, `SettingsProvider`, `CredentialRequest`, `Credential`, `CredentialResolver`, `CompactionStrategy`, `CompactionContext`, `CompactionResult`, `CompactionOptions`, `CompactionMiddlewarePayload`, `CompactionEntryData`, `DefaultCompactionStrategyOptions`, `RetryPolicy`, `RetryContext`, `RetryDecision`, `RetryOptions`, `RetryMiddlewarePayload`, `DefaultRetryPolicyOptions`, `CacheUsageReport`, `sanitizeCacheKey`, `mapCacheRetention`, `applyCacheControl`, `cacheHitRate`, `cacheSavings`, `cacheUsageReport`
-- Production persistence (adapter-facing): `ProductionPersistenceStore`, `CheckpointStore`, `CheckpointKey`, `CheckpointSaveInput`, `CheckpointRecord`, `CheckpointQuery`, `LeaseStore`, `LeaseKey`, `LeaseAcquireInput`, `LeaseClaimInput`, `LeaseRecord`, `PersistencePage`, `PersistenceQuery`, `OwnershipScope`, `SessionRecord`, `SessionQuery`, `BranchRecord`, `BranchQuery`, `SessionEntryQuery`, `RunRecord`, `RunQuery`, `AgentEventRecord`, `AgentEventQuery`, `ToolCallRecord`, `ToolCallQuery`, `UsageRecord`, `UsageQuery`, `AgentDefinitionRecord`, `AgentDefinitionQuery`, `RetentionPolicy`, `RetentionPolicyQuery`, `MigrationRecord`, `MigrationQuery`
+- Production persistence (adapter-facing): `ProductionPersistenceStore`, `CheckpointStore`, `CheckpointKey`, `CheckpointSaveInput`, `CheckpointRecord`, `CheckpointQuery`, `LeaseStore`, `LeaseKey`, `LeaseAcquireInput`, `LeaseClaimInput`, `LeaseRecord`, `PersistencePage`, `PersistenceQuery`, `OwnershipScope`, `SessionRecord`, `SessionQuery`, `BranchRecord`, `BranchQuery`, `SessionEntryQuery`, `RunRecord`, `RunQuery`, `RunFeedbackRecord`, `RunFeedbackStore`, `RunFeedbackQuery`, `AgentEventRecord`, `AgentEventQuery`, `ToolCallRecord`, `ToolCallQuery`, `UsageRecord`, `UsageQuery`, `AgentDefinitionRecord`, `AgentDefinitionQuery`, `RetentionPolicy`, `RetentionPolicyQuery`, `MigrationRecord`, `MigrationQuery`
 
 ## When to use it
 
@@ -142,9 +142,10 @@ Important request shapes:
 | `SystemPromptContribution` | Explicit caller-selected prompt layer with source, mode, text, and metadata. |
 | `ConfigLayer` | Named JSON config layer consumed by `mergeConfigLayers()`. |
 | `PrismManifest` | Data-only package manifest with config defaults, contribution declarations, and resource declarations. |
-| `ProductionPersistenceStore` | Adapter-facing interface for durable, paginated, multi-tenant storage plus optional `checkpoints?: CheckpointStore` and `leases?: LeaseStore`. No SQL/ORM/host file storage/network dependency. |
+| `ProductionPersistenceStore` | Adapter-facing interface for durable, paginated, multi-tenant storage plus optional `checkpoints?: CheckpointStore`, `leases?: LeaseStore`, and `feedback?: RunFeedbackStore`. No SQL/ORM/host file storage/network dependency. |
 | `CheckpointStore` | Generic versioned checkpoint capability: save/load/bounded-list/delete by namespace and key, with ownership, exact-version CAS, and lease fencing. `createMemoryCheckpointStore()` is the reference implementation. |
 | `LeaseStore` | Atomic acquire/renew/release/get by namespace and key, with opaque claim tokens, expiry, ownership scope, and monotonically increasing takeover fences. `createMemoryLeaseStore()` is the reference implementation. |
+| `RunFeedbackStore` | Immutable append, bounded owned query, and owned deletion for ratings/comments/tags linked to existing run/trace/evaluation IDs. `createMemoryRunFeedbackStore()` is the reference implementation. |
 | `EventMultiplexer<T>` | Generic bounded fan-in from async sources. `createEventMultiplexer()` owns queue limits, overflow policy, abort, source teardown, and close behavior. |
 | `PersistencePage<T>` | Cursor-paginated result page: `items`, optional `nextCursor`, optional `total`. |
 | `PersistenceQuery` | Common pagination controls: `cursor?`, `limit?`, `order?: "asc" \| "desc"`. |
@@ -155,7 +156,7 @@ Important request shapes:
 | `RunRecord` / `RunQuery` | Stored run and filters: session, branch, status, timestamps, ownership. |
 | `AgentEventRecord` / `AgentEventQuery` | Event ledger row with `redacted` flag and filters by type, session, run, entry, timestamp, ownership. |
 | `ToolCallRecord` / `ToolCallQuery` | Tool-call row with `redacted` flag and filters by name, status, session, run, entry, timestamps, ownership. |
-| `UsageRecord` / `UsageQuery` | Usage row and filters: session, run, entry, recorded-at range, ownership. |
+| `UsageRecord` / `UsageQuery` | Usage row and filters: `provider_turn`/`run_total` scope, turn/attempt, session, run, entry, recorded-at range, ownership. |
 | `CacheUsageReport` | Numeric cache diagnostics from normalized `Usage`: read/write tokens, hit rate, estimated savings, and optional currency. |
 | `AgentDefinitionRecord` / `AgentDefinitionQuery` | Versioned agent-definition snapshot and filters. Does not store credentials or provider instances. |
 | `RetentionPolicy` / `RetentionPolicyQuery` | Retention policy and filters: age, entry count, byte limits, archive store, applied kinds. |
@@ -412,8 +413,8 @@ void credentials;
 - Contracts are host-owned and package-friendly. External packages can implement `AIProvider`, `ToolDefinition`, `CommandDefinition`, `AgentDefinition`, `InputBuilder`, `PromptBuilder`, `Middleware`, `ContextProvider`, `Skill`, `Extension`, config providers, data-only manifests, compaction strategies, store factories, resource loaders, settings providers, and credential resolvers.
 - `ExtensionAPI` is implemented by the extension kernel. It exposes explicit registries, ordered middleware registration, ordered event subscription/emission, and registration methods for Phase 2 contribution categories.
 - `AgentConfig.provider` can hold a direct provider instance for simple host wiring. Hosts that need config-driven selection should use `ModelConfig.provider` with explicit `createProviderRegistry()` / `createModelRegistry()` objects; Prism does not create a hidden global provider registry.
-- `SettingsProvider` and `CredentialResolver` are explicit dependencies. Prism must not hide global settings or credentials behind these contracts, and `CredentialResolver` should be passed only to the edge that needs a credential. `AgentConfig.settings` and `AgentConfig.credentials` are host-owned metadata; the session runtime does not call `settings.get()` or `credentials.resolve()`.
-- `AgentConfig.extensions` is host-owned metadata; the session runtime does not load extensions or call `Extension.setup()`. Use `createExtensionKernel().load(...)` before creating an agent, then pass selected contributions into `AgentConfig`.
+- `SettingsProvider` and `CredentialResolver` are explicit dependencies. Prism must not hide global settings or credentials behind these contracts, and `CredentialResolver` should be passed only to the edge that needs a credential. These seams are host-owned outside `AgentConfig`; the session runtime does not call `settings.get()` or `credentials.resolve()`.
+- Extension loading is host-owned outside `AgentConfig`; the session runtime does not load extensions or call `Extension.setup()`. Use `createExtensionKernel().load(...)` before creating an agent, then pass selected contributions into `AgentConfig`.
 - `PrismManifest` is data-only. It can describe contribution modules/resources and config defaults, but parsing it does not import modules, execute package code, or mutate registries.
 - Resource helper functions decode resources from a caller-provided `ResourceLoader`; Prism does not include host file storage, network, package, or URI router loaders.
 - `createDefaultInputBuilder()` is a small default implementation of `InputBuilder`. It is replaceable and only loads explicit URI resources through a caller-provided `ResourceLoader`.

package/docs/rag.md

@@ -0,0 +1,113 @@
+# Retrieval-augmented generation (RAG)
+
+## What it does
+
+`@arnilo/prism-rag` is an optional package for deterministic plain-text/Markdown chunking, bounded embedding/vector indexing, filtered semantic retrieval, stable citations, and explicit `ContextProvider` injection. It reuses `Embedder` and `VectorStore` from `@arnilo/prism-memory`; Prism core input assembly is unchanged.
+
+## When to use it
+
+Use it when a host already owns trusted document text and needs small retrieval primitives without a document framework. Do not use it for PDF/HTML/LaTeX parsing, semantic chunking, metadata extraction agents, reranker pipelines, GraphRAG, crawling, URL fetching, or filesystem discovery.
+
+## Inputs / request
+
+Chunking:
+
+| API/field | Meaning |
+| --- | --- |
+| `chunkText(text, options)` | Character-bounded plain-text chunks |
+| `chunkMarkdown(markdown, options)` | Same engine, preferring heading/paragraph boundaries |
+| `sourceId` | Required stable, non-secret source identifier |
+| `size` / `overlap` | Character ceiling and repeated context |
+| `metadata` | JSON metadata copied to every chunk |
+
+Index/retrieve:
+
+| Field | Required | Meaning |
+| --- | --- | --- |
+| `embedder` / `store` | yes | Phase 7 `Embedder` and `VectorStore` |
+| `scope` | yes | `{ tenantId, resourceId, corpusId }`; corpus maps to vector thread isolation |
+| `chunks` | indexing | `RagChunk[]` from package chunkers or compatible host parser |
+| `topK` / `queryCandidates` | retrieval | Returned result count and bounded pre-filter candidates |
+| `filter` | no | Shallow JSON metadata equality filter |
+| `redactor` / `secrets` | no | Redact before embedding, persistence, and injection |
+| `signal` | no | Abort embedding, vector operations, and batch progression |
+
+## Outputs / response / events
+
+- `chunkText()` / `chunkMarkdown()` return frozen `RagChunk[]` with `sourceId`, zero-based index, offsets, and stable IDs such as `guide#0001`.
+- `indexChunks()` returns `{ indexed, sourceIds }` after bounded batch upserts.
+- `retrieveContext()` returns `{ query, text, hits, citations, truncated }`. Rendered text uses `[citation-id] text` blocks.
+- `createRagContextProvider()` returns one ordinary context provider. Empty queries/results contribute no block.
+- No events, tools, permissions, provider calls, loaders, or network requests are added.
+
+Default hard ceilings include 1,000/16,384 chunk characters, 100/4,096 overlap, 1,048,576/8,388,608 document characters, 2,048/8,192 chunks, 32/128 embed batch, top-K 5/32, candidates 20/128, result 64/512 KiB, and context 2,000/8,000 estimated tokens.
+
+## Request/response example
+
+```json
+{
+  "scope": { "tenantId": "t1", "resourceId": "docs", "corpusId": "handbook" },
+  "query": "How do approvals work?",
+  "topK": 1,
+  "result": {
+    "text": "[security-guide#0001] Recheck policy before side effects.",
+    "citations": [{ "id": "security-guide#0001", "sourceId": "security-guide" }]
+  }
+}
+```
+
+## Implementation example
+
+```ts
+import { createAgent, createMockProvider, providerDone, providerTextDelta } from "@arnilo/prism";
+import { createHashEmbedder, createMemoryVectorStore } from "@arnilo/prism-memory";
+import { chunkMarkdown, createRagContextProvider, indexChunks, retrieveContext } from "@arnilo/prism-rag";
+
+const embedder = createHashEmbedder(); // deterministic demo/test helper, not production semantic quality
+const store = createMemoryVectorStore();
+const scope = { tenantId: "t1", resourceId: "docs", corpusId: "handbook" };
+const chunks = chunkMarkdown("# Approval\n\nRecheck current policy before side effects.", {
+  sourceId: "security-guide",
+  metadata: { category: "security" },
+});
+await indexChunks({ chunks, embedder, store, scope });
+
+const found = await retrieveContext("approval policy", {
+  embedder,
+  store,
+  scope,
+  topK: 4,
+  filter: { category: "security" },
+});
+
+const agent = createAgent({
+  model: { provider: "mock", model: "demo" },
+  provider: createMockProvider([providerTextDelta("Policy checked."), providerDone()]),
+  context: [createRagContextProvider({ embedder, store, scope })],
+});
+console.log(found.text, await agent.createSession().run("How do approvals work?"));
+```
+
+## Extension and configuration notes
+
+- Supply any Phase 7-conforming embedder/vector store, including the in-memory reference or PostgreSQL/pgvector adapter.
+- Metadata filtering is package-local after a bounded candidate query so existing vector contracts/adapters remain unchanged. Increase `queryCandidates` only when selective filters measurably need it.
+- `createRagContextProvider()` derives its query from latest user text by default; pass a fixed string or callback for host-controlled query generation.
+- Load source text separately with a host-owned `ResourceLoader`. The RAG package intentionally accepts text, not URLs or filesystem paths.
+- Package is available directly or through `@arnilo/prism-all`; installation does not create an embedder, vector store, or context provider.
+
+## Security and performance notes
+
+- Every index/query includes exact tenant/resource/corpus scope; returned records are rechecked and malformed/foreign records fail closed.
+- Source IDs become citation/storage IDs and must be stable non-secret identifiers. Text and user metadata can be redacted before external embedding and persistence.
+- Retrieved documents are untrusted inert context. Prompt-injection text cannot activate tools, skills, credentials, permissions, or extensions.
+- Remote sources must pass existing resource/media trust, SSRF, MIME, and byte policies before their decoded text reaches this package.
+- Indexing is bounded per batch and checks abort between embed/upsert operations. A failure can leave completed batches persisted; retry is idempotent for the same stable source/chunk IDs.
+- Filtering scans at most `queryCandidates` hits; rendering stops at top-K, UTF-8 result bytes, or estimated context-token ceiling.
+
+## Related APIs
+
+- [Working and semantic memory](working-and-semantic-memory.md): shared `Embedder`/`VectorStore` contracts and adapters.
+- [Context and skills](context-and-skills.md): explicit `ContextProvider` injection and inert context semantics.
+- [Resource loading](resource-loading.md): host-owned trusted source loading.
+- [Multimodal content](multimodal-content.md): remote media SSRF/MIME/byte policies before text extraction.