@arnilo/prism 0.0.3 → 0.0.5

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,9 +242,11 @@ 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.
+- **Live timing metadata.** `provider_turn_*` events and `ToolExecutionMetadata` on terminal `tool_execution_*` events expose latency, retry `attempt`, and tool `durationMs` for subscribers and ledger replay — see [Observability](observability.md).
 
 ## Security and performance notes
 
@@ -218,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
 
@@ -233,4 +271,5 @@ console.log(cacheUsageReport(usageRows.at(-1)?.usage));
 - [Session stores](session-stores.md): `SessionStore` contract for session entries and branches.
 - [Credentials and redaction](credentials-and-redaction.md): `createSecretRedactor()` and redaction helpers.
 - [Provider caching](provider-caching.md): cache hints and `cacheUsageReport()` diagnostics.
+- [Observability](observability.md): `provider_turn_*` events, tool duration metadata, OpenTelemetry adapter.
 - [Public contracts](public-contracts.md): full contract inventory.

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/session-store-conformance.md

@@ -7,7 +7,9 @@ Session store conformance helpers are dependency-free assertions for `SessionSto
 Exported from `@arnilo/prism/testing/session-store-conformance`:
 
 - `assertSessionStoreConforms(store, options?)`
+- `runSessionStoreConformance(factory, options?)`
 - `SessionStoreConformanceOptions`
+- `SessionStoreConformanceFactory`
 
 ## When to use it
 
@@ -20,6 +22,9 @@ Use this helper when implementing a DB-backed `SessionStore` (for example, the r
 - branching from any existing entry (existence validation, not tip-CAS)
 - distinct linear appends sharing a run-level `idempotencyKey` are not collapsed
 - optional `readBranchPath` returns the ancestor chain in root-to-leaf order (when `exerciseReadBranchPath: true`)
+- session ids remain isolated (`assertSessionStoreConforms` always probes a secondary session)
+- optional concurrent fork children of the same parent succeed when `exerciseConcurrentParentAppend: true`
+- optional durable reopen/idempotency survival when `runSessionStoreConformance(..., { exerciseReopen: true })`
 
 ## Inputs / request
 
@@ -28,11 +33,21 @@ import { assertSessionStoreConforms } from "@arnilo/prism/testing/session-store-
 import type { SessionStore } from "@arnilo/prism";
 
 await assertSessionStoreConforms(myDbBackedStore, { exerciseReadBranchPath: true });
+
+// Durable adapters: factory reopens the same backing store
+await runSessionStoreConformance(() => createStore(testDatabase), {
+  exerciseReadBranchPath: true,
+  exerciseReopen: true,
+  exerciseConcurrentParentAppend: true,
+});
 ```
 
 `SessionStoreConformanceOptions`:
 - `sessionId?: string` — stable session id for the run (default `"conformance"`)
+- `otherSessionId?: string` — secondary session for isolation probes
 - `exerciseReadBranchPath?: boolean` — also probe `readBranchPath` when implemented
+- `exerciseConcurrentParentAppend?: boolean` — also probe concurrent fork appends
+- `exerciseReopen?: boolean` — only on `runSessionStoreConformance`; reopen via the same factory
 
 ## Outputs / response / events
 
@@ -75,4 +90,5 @@ await assertSessionStoreConforms(createMemorySessionStore());
 - [Session stores and branching](session-stores-and-branching.md)
 - [Session stores](session-stores.md)
 - [Database persistence](database-persistence.md)
+- [Run ledger conformance](run-ledger-conformance.md)
 - [Provider conformance](provider-conformance.md)

package/docs/session-stores-and-branching.md

@@ -119,5 +119,6 @@ Use `createDefaultCompactionStrategy()` to create compaction entries that `rebui
 - [Compaction and retry policies](compaction-and-retry.md): default strategy for creating compaction entries.
 - [Input and prompt assembly](input-and-prompt-assembly.md): provider input assembly consumes rebuilt `messages` and `summaries`.
 - [Credentials and redaction](credentials-and-redaction.md): security boundary for secrets that must not enter session entries.
+- [Workflows](workflows.md): optional orchestration that reuses session `leafId` on resume rather than reloading full transcripts into the scheduler.
 
 Session stores persist the entries they receive. Configure `AgentConfig.redactor` or `RunOptions.redactor` before a run when known secrets must be removed before entries reach durable stores.

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. 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.
@@ -81,6 +81,7 @@ Boundary hardening summary:
 - `createMemoryCredentialStore`, `createChainedCredentialResolver`, `createExplicitCredentialResolver`, `createEnvCredentialResolver`, `refreshOAuthCredential`, `resolveCredentialValue`
 - `createStaticTrustPolicy`, `assertTrusted`, `isTrusted`, `TrustDeniedError`
 - `createStaticPermissionPolicy`, `assertPermission`, `checkPermission`, `PermissionDeniedError`
+- `ExecutionPolicy`, `assertExecutionAllowed`, `checkExecution`, `ExecutionDeniedError` (core); `@arnilo/prism-coding-security` for coding-tool approval adapters — see [Coding execution approval and sandboxing](coding-security.md)
 - `createSecretRedactor`, `redactMessage`, `redactAgentEvent`, `redactSessionEntry`, `redactProviderRequest`
 - `@arnilo/prism/node/settings`: `defaultUserSettingsPath`, `readSettingsFile`, `loadSettingsFiles`
 - `@arnilo/prism/node/trust`: `createPathTrustPolicy`, `isPathInside`, `isPathInsideReal`

package/docs/sqlite-persistence.md

@@ -0,0 +1,123 @@
+# SQLite persistence
+
+## What it does
+
+The optional `@arnilo/prism-session-store-sqlite` package ships a production-oriented SQLite adapter that implements:
+
+- `SessionStore` — atomic `append` / `list` / `get` / `readBranchPath`
+- `RunLedger` — durable run, event, tool-call, and usage rows
+- `ProductionPersistenceStore` — cursor-paginated `query*` reads plus generic `checkpoints` and atomic `leases` capabilities
+
+Factory:
+
+- `createSqlitePersistence(options)`
+- `SqlitePersistenceOptions`
+- `SqlitePersistence.close()`
+
+The adapter uses `better-sqlite3@^12.11.1`, enables WAL and foreign keys, applies versioned migrations from the shared Plan 056 schema model, and passes the full session-store and run-ledger conformance suites including process reopen.
+
+## When to use it
+
+Use this package when you want a small, file-backed persistence layer on Node without operating a database server:
+
+- local CLI tools and desktop hosts
+- single-writer or low-concurrency deployments
+- integration tests that need durable reopen semantics
+
+Do **not** use it as a substitute for PostgreSQL when you need heavy multi-writer concurrency, server-side pooling, or managed TLS. See [`@arnilo/prism-session-store-postgres`](postgres-persistence.md) for that path.
+
+## Inputs / request
+
+```ts
+import { createSqlitePersistence } from "@arnilo/prism-session-store-sqlite";
+```
+
+| Field | Type | Purpose |
+| --- | --- | --- |
+| `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). |
+
+## Outputs / response / events
+
+`createSqlitePersistence()` returns one object implementing the three persistence contracts plus generic checkpoints and leases:
+
+| Method group | Behavior |
+| --- | --- |
+| `SessionStore.append` | One transaction per append: parent existence check, idempotency dedup, duplicate-id rejection, entry insert. |
+| `SessionStore.list` / `get` | Indexed reads by `session_id` and primary key. |
+| `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, 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. |
+
+Migrations run automatically on open and are idempotent across reopen.
+
+## Request/response example
+
+```json
+{
+  "filename": "./prism.db",
+  "wal": true,
+  "busyTimeoutMs": 5000,
+  "fileMode": 384
+}
+```
+
+## Implementation example
+
+```ts
+import { createAgentSession } from "@arnilo/prism";
+import { createSqlitePersistence } from "@arnilo/prism-session-store-sqlite";
+import { runSessionStoreConformance } from "@arnilo/prism/testing/session-store-conformance";
+
+const persistence = createSqlitePersistence({ filename: "./prism.db" });
+
+await runSessionStoreConformance(
+  () => createSqlitePersistence({ filename: "./prism.db" }),
+  { exerciseReadBranchPath: true, exerciseReopen: true },
+);
+
+const session = createAgentSession({
+  sessionStore: persistence,
+  runLedger: persistence,
+});
+
+await session.run("hello");
+persistence.close();
+```
+
+For resume/timeline flows, use `queryRuns`, `queryEvents`, `queryToolCalls`, and `queryUsage` the same way as the reference mock in [`examples/external-app-db-backed.ts`](../examples/external-app-db-backed.ts).
+
+## Extension and configuration notes
+
+- 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 **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
+
+- **Parameterized SQL only.** Session ids, idempotency keys, tenant ids, and JSON payloads are bound parameters.
+- **File ownership.** Create database files on a host-controlled path with restrictive permissions (`0600` default on Unix via `fileMode`).
+- **No path interpolation.** The adapter opens exactly the caller-supplied `filename`; it does not expand environment variables or discover paths.
+- **Redaction upstream.** Event and tool-call payloads may contain secrets; redact before ledger writes. The adapter does not scan or rewrite row contents.
+- **WAL + busy timeout.** WAL is enabled by default; busy timeout defaults to 5 seconds. This meets the Plan 056 local workload target but SQLite still serializes writers — prefer PostgreSQL for high write concurrency.
+- **Indexed operations.** Append, parent validation, idempotency dedup, branch reads, and pagination use the indexes documented in [Database persistence](database-persistence.md); normal paths avoid whole-database scans.
+- **Tenant isolation.** `tenant_id` / `account_id` / `user_id` columns on run and ownership tables participate in query filters; hosts must still scope writes correctly.
+
+## Related APIs
+
+- [Database persistence](database-persistence.md): shared schema model, conditional append pattern, indexes.
+- [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.
+- [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()` and `createWorkflowSchedules()` for durable background execution and schedules.
+- [Migration guide](migration.md): moving from JSONL/in-memory to database-backed persistence.

package/docs/structured-output.md

@@ -10,6 +10,8 @@ An artifact loop generates provider text, parses it to `T`, validates `T` agains
 
 Use `generateValidateReviseLoop` (with host `parser`/`validator`/`repairer`) when a run should produce an artifact that must satisfy a host-owned schema before it is considered complete: structured JSON output, a generated file passing lint, a typed response conforming to a Synapta-defined model. Wrap your existing schema/validation library behind the `Artifact*` callbacks.
 
+When the model declares `capabilities.structuredOutput` and the host opts into native mode, pass `structuredOutput` on `RunOptions.providerOptions` or on the `generate-validate-revise` loop options so capable providers map the schema to their wire format (`response_format` / Responses `text.format`) and valid output can finish in one turn without repair revisions.
+
 Do not use it to re-implement provider calls, retry, abort, store, or event emission — those stay runtime-owned and are exposed to the loop only through `LoopContext`. Do not use it for runs that need tool calls during revision turns — use `singleShotLoop` or a custom `AgentLoopStrategy` instead. Do not put Synapta domain types into Prism; map them to `ArtifactValidation` in your callbacks.
 
 ## Inputs / request
@@ -47,6 +49,11 @@ await session.run(input, {
     parser,            // optional; default treats assistant text as the value
     repairer,          // optional; default stringifies validation.errors[].message
     maxRevisions: 3,   // optional; default 3
+    structuredOutput: { name: "answer", schema, strict: true }, // optional native mode
+    structuredOutputMode: "native", // or "artifact-loop" to skip provider-native schema
+  },
+  providerOptions: {
+    structuredOutput: { name: "answer", schema, strict: true }, // direct native request
   },
 });
 ```
@@ -222,6 +229,8 @@ Key cross-seam points:
 ## Extension and configuration notes
 
 - `generate-validate-revise` is selected via `AgentConfig.loop` / `RunOptions.loop` (`RunOptions.loop` wins). See [Agent loops](agent-loops.md). `resolveLoop()` maps the options form to the factory; an unknown `strategy` throws before the first turn; a custom `AgentLoopStrategy` instance bypasses the options form.
+- Native structured output uses provider-neutral `StructuredOutputOptions` on `ProviderRequestOptions` / loop options. Capable OpenAI-family providers map to JSON-schema wire fields; unsupported models fail before fetch unless the host sets `structuredOutputMode: "artifact-loop"` and relies on parser/validator/repairer only.
+- `validateStructuredOutputOptions()` enforces JSON-safe schemas, forbidden prototype-pollution keys, and a 64 KiB schema size cap.
 - The default parser treats assistant text as the value (`{ ok: true, value: text }`); supply a host parser whenever `T` is not `string`.
 - The default repairer builds a user message from `validation.errors[].message`; supply a host repairer for schema-specific guidance.
 - `maxRevisions` (default 3) bounds revision turns; budget exhaustion ends the loop and emits `artifact_failed` (it does not throw).

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.

package/docs/tool-conformance.md

@@ -77,6 +77,7 @@ await assertToolDispatchConforms(createToolRegistry(), {
 ## Security and performance notes
 
 - No credentials, no network required.
+- Supply `validate` to exercise your policy; use `createJsonSchemaToolArgumentValidator()` from `@arnilo/prism-tool-validator-json-schema` for standards-based `parameters` validation.
 - The helper uses an allow-all permission policy by default; supply `permission` to validate your fail-closed policy.
 - Blocked calls are proven not to execute by the absence of `tool_execution_started`.