@arnilo/prism 0.0.3 → 0.0.4

package/docs/coding-security.md

@@ -0,0 +1,84 @@
+# Coding execution approval and sandboxing
+
+## What it does
+
+`@arnilo/prism-coding-security` is an optional package that supplies structured execution policy for `@arnilo/prism-coding-agent` tools. It complements name-based `PermissionPolicy` at dispatch time with path/command context checked **inside** each tool before side effects.
+
+| Export | Purpose |
+| --- | --- |
+| `createCodingApprovalPolicy(options)` | Returns an `ExecutionPolicy` with trusted roots, read-only mode, command allow/deny rules, approval caching, and timeout/abort-aware approval waits. |
+| `createSandboxBashOperations(adapter)` | Maps a host-owned `SandboxAdapter` to coding-agent `BashOperations` for delegated shell execution. |
+| `assertPathInsideRoots`, `isPathInsideReal` | Symlink-aware path containment helpers. |
+| `evaluateCommandRules`, `hasShellMetacharacters` | Command classification helpers. |
+
+Core contracts live in `@arnilo/prism`:
+
+```ts
+import type { ExecutionAction, ExecutionPolicy, ExecutionDecision } from "@arnilo/prism";
+```
+
+## When to use it
+
+Use this package when coding tools need path scoping, human approval, command rules, or a pluggable sandbox backend. Wire the returned policy through `createCodingTools(cwd, { executionPolicy })` or per-tool `executionPolicy` options.
+
+Prism does **not** claim OS-level isolation unless the host provides a sandbox adapter. Default policy denies shell/write/edit without an `approve` callback and rejects paths outside configured roots. Coding shell definitions are marked `exclusive: true`, matching the approval policy's shell decision, so a single-shot turn containing shell work runs sequentially even when `toolConcurrency > 1`. Non-shell turns retain configured parallelism.
+
+## Inputs / request
+
+| Option | Default | Purpose |
+| --- | --- | --- |
+| `roots` | required | Realpath-contained filesystem roots. |
+| `readOnly` | `false` | Deny shell/write/edit actions. |
+| `commandRules` | `[]` | Ordered allow/deny/approval command classification. |
+| `approve` | none | Host callback for actions not statically allowed; omission fails closed. |
+| `approvalCacheScope` | `"none"` | Optional `run` or `session` decision cache scope. |
+| `approvalTimeoutMs` | `30000` | Bound approval wait; caller abort also cancels it. |
+
+## Outputs / response / events
+
+`createCodingApprovalPolicy()` returns an `ExecutionPolicy`. Allowed checks return `ExecutionDecision { allowed: true }`; denied checks include a stable reason; shell decisions set `exclusive: true`. Sandbox adapters return coding-agent-compatible `BashOperations` and never grant policy approval themselves.
+
+## Request/response example
+
+```json
+{
+  "action": { "kind": "shell", "operation": "execute", "command": "npm test", "paths": [] },
+  "decision": { "allowed": true, "exclusive": true }
+}
+```
+
+## Implementation example
+
+```ts
+import { createCodingTools } from "@arnilo/prism-coding-agent";
+import { createCodingApprovalPolicy, createSandboxBashOperations } from "@arnilo/prism-coding-security";
+
+const policy = createCodingApprovalPolicy({
+  roots: [workspaceRoot],
+  approve: async ({ action, signal }) => ui.confirm(action, { signal }),
+  approvalCacheScope: "run",
+  approvalTimeoutMs: 60_000,
+});
+
+const tools = createCodingTools(workspaceRoot, {
+  executionPolicy: policy,
+  shell: {
+    operations: createSandboxBashOperations(mySandboxAdapter),
+  },
+});
+```
+
+## Extension and configuration notes
+
+Policies are ordinary host values: attach one globally through `createCodingTools()` or per tool. `SandboxAdapter` is replaceable and host-owned; approval policy and sandboxing are separate layers. Use run-scoped approval caching unless a wider host identity/lifecycle is explicit.
+
+## Security and performance notes
+
+Containment resolves symlinks and rejects paths outside roots. Command rules are not a shell parser; shell metacharacters require approval. Approval waits and subprocess execution honor abort/timeouts. Path checks and cache lookup are local; sandbox latency belongs to the supplied adapter.
+
+## Related APIs
+
+- [Coding agent tools](coding-agent-tools.md)
+- [Host security guide](host-security.md)
+- [Tool execution primitives](tool-execution-primitives.md)
+- [Security/auth/trust](settings-auth-trust-security.md)

package/docs/credential-storage.md

@@ -0,0 +1,177 @@
+# Credential storage
+
+## What it does
+
+The optional `@arnilo/prism-credentials-node` package ships host-owned credential persistence for Node.js CLI and desktop apps:
+
+- **Encrypted file store** — AES-256-GCM envelope with scrypt KDF, atomic rename writes, versioned on-disk format
+- **System keychain store** — cross-platform secret service via `@napi-rs/keyring@^1.3.0`
+- **Stored credential resolver** — `createStoredCredentialResolver(store)` for explicit resolver chains
+- **OAuth adapter** — extends the core `OAuthCredentialStore` seam with `get`/`delete` for refresh flows
+
+Factories:
+
+- `openEncryptedCredentialStore(options)` / `createEncryptedCredentialStore(options)`
+- `createKeychainCredentialStore(options)`
+- `createStoredCredentialResolver(store)`
+- `createOAuthCredentialStoreAdapter(store)`
+- `rotateEncryptedCredentialStorePassphrase(options)`
+
+Core `@arnilo/prism` remains storage-free. Hosts choose a backend explicitly at startup; there is no global credential singleton and no silent fallback from keychain to plaintext file storage.
+
+## When to use it
+
+Use this package when a host needs durable credentials beyond `createMemoryCredentialStore()`:
+
+- local CLI tools storing API keys or OAuth tokens between runs
+- desktop hosts integrating with macOS Keychain, Windows Credential Manager, or Linux Secret Service
+- integration tests that need encrypted reopen semantics without a live keychain
+
+Do **not** use it when credentials should live in a remote vault, HSM, or cloud secret manager — implement `CredentialResolver` against that service instead.
+
+## Inputs / request
+
+```ts
+import {
+  openEncryptedCredentialStore,
+  createKeychainCredentialStore,
+} from "@arnilo/prism-credentials-node";
+```
+
+### Encrypted file
+
+| Field | Type | Purpose |
+| --- | --- | --- |
+| `path` | `string` | Vault file path. Parent directories are created as needed. |
+| `getPassphrase` | `() => string \| Promise<string>` | Host-owned passphrase retrieval. Never logged by the adapter. |
+| `scrypt` | `{ N?, r?, p?, keyLength? }` | Optional KDF tuning. Defaults: `N=32768`, `r=8`, `p=1`, `keyLength=32`. Minimum `N=16384`. |
+| `fileMode` | `number` | Unix mode for newly written files. Defaults to `0o600`. |
+
+### System keychain
+
+| Field | Type | Purpose |
+| --- | --- | --- |
+| `service` | `string` | Keychain service name (application identifier). |
+| `namespace` | `string` | Optional prefix separating environments or tenants within one service. |
+| `timeoutMs` | `number` | Operation timeout. Defaults to `5000`. |
+
+## Outputs / response / events
+
+Both backends implement `StoredCredentialStore`:
+
+| Method | Behavior |
+| --- | --- |
+| `set(record)` / `get(request)` / `delete(request)` | Namespaced by `(provider, name)` for API keys and bearer tokens. |
+| `setOAuth(provider, credentials, accountId?)` | Stores OAuth tokens per provider/account. |
+| `getOAuth(provider, accountId?)` / `deleteOAuth(...)` | Reads or removes OAuth rows. |
+| `resolve(request)` | `CredentialResolver` compatibility via `createStoredCredentialResolver`. |
+
+Encrypted file stores also expose:
+
+- `reload()` — re-read and decrypt from disk
+- `flush()` — force rewrite of the encrypted envelope
+
+Errors are explicit and fail closed:
+
+| Error | Code | When |
+| --- | --- | --- |
+| `CredentialDecryptError` | `credential_decrypt_failed` | Wrong passphrase or tampered ciphertext |
+| `CredentialStoreLockedError` | `credential_store_locked` | Keychain denied or locked |
+| `CredentialStoreUnavailableError` | `credential_store_unavailable` | No OS secret service |
+| `CredentialStoreTimeoutError` | `credential_store_timeout` | Keychain call exceeded `timeoutMs` |
+| `WeakKdfParametersError` | `weak_kdf_parameters` | scrypt work factor below minimum |
+
+## Request/response example
+
+```json
+{
+  "path": "./credentials.vault",
+  "fileMode": 384,
+  "keychain": {
+    "service": "my-app",
+    "namespace": "production",
+    "timeoutMs": 5000
+  }
+}
+```
+
+On-disk envelope (illustrative — ciphertext is base64, secrets are not plaintext):
+
+```json
+{
+  "version": 1,
+  "kdf": { "algorithm": "scrypt", "N": 32768, "r": 8, "p": 1, "salt": "...", "keyLength": 32 },
+  "cipher": { "algorithm": "aes-256-gcm", "iv": "..." },
+  "ciphertext": "..."
+}
+```
+
+## Implementation example
+
+```ts
+import {
+  createExplicitCredentialResolver,
+  refreshOAuthCredential,
+  resolveCredentialValue,
+} from "@arnilo/prism";
+import {
+  createOAuthCredentialStoreAdapter,
+  createStoredCredentialResolver,
+  openEncryptedCredentialStore,
+} from "@arnilo/prism-credentials-node";
+
+const store = await openEncryptedCredentialStore({
+  path: "./credentials.vault",
+  getPassphrase: () => process.env.MY_APP_CREDENTIAL_PASSPHRASE!,
+});
+
+const resolver = createExplicitCredentialResolver([
+  { name: "stored", resolver: createStoredCredentialResolver(store) },
+]);
+
+const apiKey = await resolveCredentialValue(resolver, { name: "apiKey", provider: "demo" });
+
+const oauthStore = createOAuthCredentialStoreAdapter(store);
+await refreshOAuthCredential({
+  provider: myOAuthProvider,
+  credentials: existing,
+  store: oauthStore,
+});
+```
+
+Passphrase rotation:
+
+```ts
+import { rotateEncryptedCredentialStorePassphrase } from "@arnilo/prism-credentials-node";
+
+await rotateEncryptedCredentialStorePassphrase({
+  path: "./credentials.vault",
+  getCurrentPassphrase: () => oldPassphrase,
+  getNewPassphrase: () => newPassphrase,
+});
+```
+
+## Extension and configuration notes
+
+- Passphrase retrieval, TLS, and OS permission prompts remain host-owned.
+- Use distinct `namespace` or vault paths per tenant/environment.
+- Keychain `list()` / `listOAuth()` are intentionally unsupported — enumerate credentials through host configuration instead of scanning the OS store.
+- Combine with `createExplicitCredentialResolver()` so runtime overrides still win over stored values.
+- Wire `createOAuthCredentialStoreAdapter(store)` into `refreshOAuthCredential()` so refreshed tokens persist durably.
+
+## Security and performance notes
+
+- Authenticated encryption uses Node built-in `aes-256-gcm` and `scrypt`; no extra crypto dependencies for the file backend.
+- Atomic writes use temp file + rename; partial writes cannot replace a valid vault.
+- Derived keys are zeroed after encrypt/decrypt operations where practical.
+- Default scrypt `N=32768` targets interactive CLI unlock; raise `N` for higher security at the cost of unlock latency.
+- Keychain operations honor `timeoutMs` and surface `CredentialStoreTimeoutError` instead of blocking indefinitely.
+- Never log passphrases, derived keys, or decrypted credential payloads. Error messages do not echo secret values.
+- Live keychain tests are opt-in (`PRISM_TEST_KEYCHAIN=1`); default `npm test` stays offline.
+
+## Related APIs
+
+- [Credentials and redaction](credentials-and-redaction.md): core resolver helpers and `refreshOAuthCredential()`
+- [Security/auth/trust](settings-auth-trust-security.md): host-owned settings/credentials boundaries
+- [Persistence, credentials, and multimodality primitives](persistence-credentials-multimodality-primitives.md): Plan 056 threat model and conformance matrix rows 7–10
+- `@arnilo/prism`: `CredentialResolver`, `OAuthCredentialStore`, `createMemoryCredentialStore()`

package/docs/credentials-and-redaction.md

@@ -113,6 +113,7 @@ console.log(error.message);
 - `AgentConfig.credentials` is not eagerly resolved, serialized into provider requests/events/stores, or passed to loops/compaction by the core runtime.
 - `resolveCredentialValue()` and `createExplicitCredentialResolver()` do not cache values. Add host-side caching only if a real credential source needs it.
 - `refreshOAuthCredential()` only calls the supplied OAuth provider and optional store; it has no built-in persistence or retry loop.
+- OpenAI Codex device-code OAuth polls inside `createOpenAICodexOAuthProvider().login()` with bounded delays and abort support via `OAuthLoginCallbacks.signal`. Token-endpoint failures redact authorization codes, PKCE verifiers, device/user codes, and access/refresh tokens when those values are known.
 
 ## Related APIs
 
@@ -121,4 +122,4 @@ console.log(error.message);
 - [LLM compaction package](compaction-llm.md): resolves optional summary-provider credentials per compaction call and redacts exact known values.
 - [OpenAI-compatible provider](providers/openai-compatible.md): resolves API keys per request and redacts known values from adapter errors.
 
-Phase 10 added `createMemoryCredentialStore()`, `createChainedCredentialResolver()`, and `createSecretRedactor()` for opt-in in-memory auth and runtime redaction. Phase 11 adds OAuth/API-key contracts plus explicit resolver order helpers. Core still has no persistent secret store and does not read environment variables or files for credentials. See [Security/auth/trust](settings-auth-trust-security.md).
+Phase 10 added `createMemoryCredentialStore()`, `createChainedCredentialResolver()`, and `createSecretRedactor()` for opt-in in-memory auth and runtime redaction. Phase 11 adds OAuth/API-key contracts plus explicit resolver order helpers. Core still has no persistent secret store and does not read environment variables or files for credentials. For durable storage, use [`@arnilo/prism-credentials-node`](credential-storage.md) encrypted-file or keychain backends. See [Security/auth/trust](settings-auth-trust-security.md).

package/docs/database-persistence.md

@@ -4,7 +4,9 @@
 
 The production persistence contracts describe database-neutral types for durable, multi-tenant storage of Prism sessions, branch handles, session entries, runs, agent-event ledger rows, tool-call rows, usage rows, agent-definition versions, retention policies, and migration records. They also define cursor-paginated query shapes so hosts can implement SQL, NoSQL, or object-store adapters without changing Prism runtime internals.
 
-Prism itself does not ship a production database adapter. The built-in `SessionStore` contract (`append` / `list` / optional `get`) remains the runtime seam; `ProductionPersistenceStore` is the optional adapter-facing contract for hosts that need paginated reads, tenant isolation, audit tables, and retention.
+Prism itself does not ship a production database adapter. The built-in `SessionStore` contract (`append` / `list` / optional `get`) remains the runtime seam; `ProductionPersistenceStore` is the optional adapter-facing contract for hosts that need paginated reads, tenant isolation, audit tables, retention, and optional generic `CheckpointStore` / `LeaseStore` capabilities.
+
+Plan 056 Task 1 adds dialect-neutral shared primitives under `@arnilo/prism/testing/persistence-schema`, `@arnilo/prism/testing/session-store-conformance`, and `@arnilo/prism/testing/run-ledger-conformance`. Task 2 ships `@arnilo/prism-session-store-sqlite` (see [SQLite persistence](sqlite-persistence.md)); Task 3 ships `@arnilo/prism-session-store-postgres` (see [PostgreSQL persistence](postgres-persistence.md)). Both implement dialect-local SQL against the shared model; Prism core still ships no ORM, driver, or migration runner.
 
 ## When to use it
 
@@ -184,6 +186,42 @@ The `usage` JSONB stores the `Usage` shape: input/output/total/cache tokens, cos
 
 Prism does not run migrations; hosts own migration tooling and use this table to record applied changes.
 
+## Shared schema model and migration contract
+
+Adapter packages import the shared model instead of copying table names piecemeal:
+
+```ts
+import {
+  createPersistenceSchemaModel,
+  createPersistenceMigrationContract,
+  assertPersistenceSchemaModel,
+  assertAdapterSchemaMatchesModel,
+  assertPersistenceQueryPaginationConforms,
+  assertTenantScopedQueryIsolation,
+  getPersistencePaginationCursors,
+  PARAMETERIZED_QUERY_GUIDANCE,
+} from "@arnilo/prism/testing/persistence-schema";
+import { assertSessionStoreConforms, runSessionStoreConformance } from "@arnilo/prism/testing/session-store-conformance";
+import { assertRunLedgerConforms, runRunLedgerConformance } from "@arnilo/prism/testing/run-ledger-conformance";
+
+const model = createPersistenceSchemaModel();
+assertPersistenceSchemaModel(model);
+
+await runSessionStoreConformance(() => createStore(testDatabase), { exerciseReopen: true });
+await runRunLedgerConformance(() => createLedger(testDatabase), { exerciseReopen: true });
+```
+
+| Primitive | Purpose |
+| --- | --- |
+| `PersistenceSchemaModel` | Versioned table/column/index model covering sessions, entries, parent chain, idempotency side table, runs, events, tool calls, usage, tenant columns, and `prism_migrations` |
+| `createPersistenceMigrationContract()` | Strictly increasing migration steps, `prism_migrations` recording, advisory-lock guidance, and least-privilege migration/runtime role guidance |
+| `getPersistencePaginationCursors()` | Indexed `(session_id, timestamp, id)`, `(run_id, sequence)`, `(run_id, recorded_at, id)` cursor shapes that avoid offset scans |
+| `assertPersistenceQueryPaginationConforms()` | Generic cursor pagination fixture for `queryEntries` |
+| `assertTenantScopedQueryIsolation()` | Tenant-filtered reads must not leak rows or primary-id collisions across tenants |
+| `PARAMETERIZED_QUERY_GUIDANCE` | Values are always bound parameters; only validated identifiers may be quoted |
+
+Dialect-local SQL remains in optional adapter packages. The shared model is the contract both adapters must satisfy before release.
+
 ## Adapter readiness checklist
 
 Before using a host database adapter in production:
@@ -382,9 +420,12 @@ const dbStore: ProductionPersistenceStore = {
 ## Extension and configuration notes
 
 - `ProductionPersistenceStore` is an optional extension point. The runtime does not require it.
-- Hosts choose the database, schema, transaction, and indexing strategy. The contract only specifies query shapes.
+- `ProductionPersistenceStore.checkpoints?: CheckpointStore` exposes generic versioned save/load/bounded-list/delete with compare-and-swap and fencing tokens, without workflow vocabulary.
+- `ProductionPersistenceStore.leases?: LeaseStore` exposes atomic acquire/renew/release/get with opaque claim tokens, expiries, ownership scope, and monotonic fencing tokens.
+- Hosts choose the database, schema, transaction, and indexing strategy. The contracts specify query and checkpoint capability shapes.
 - `SessionStore` (`append`/`list`/`get`/optional `readBranchPath`) can be implemented on top of `ProductionPersistenceStore` or kept separate.
 - Cursor values and idempotency keys are host-defined and opaque to Prism.
+- First-party SQLite/PostgreSQL adapters expose `persistence.checkpoints` and `persistence.leases`, backed by package-owned `prism_checkpoints` / `prism_leases` tables. `@arnilo/prism-workflows` consumes them for durable resume and multi-process coordination; workflow code owns no SQL table.
 
 ## Security and performance notes
 
@@ -405,3 +446,4 @@ const dbStore: ProductionPersistenceStore = {
 - [Agent events](agent-events.md): `AgentEvent` variants and redaction.
 - [Tools](tools.md): `ToolResult`, `ToolCallContent`, and tool execution events.
 - [Public contracts](public-contracts.md): full public contract inventory.
+- [Workflows](workflows.md): package-local durable checkpoint adapters on shared SQLite/Postgres handles.

package/docs/host-security.md

@@ -25,6 +25,7 @@ Start from explicit host inputs. Do not let runtime code discover security state
 | Permission decisions | allow/deny rules or approval UI result | `createStaticPermissionPolicy`, `assertPermission()` |
 | Tool allow-list | active tools for this agent/session/run | `createToolRegistry`, `filterTools()`, `dispatchToolCall()` |
 | Tool argument rules | host validator | `AgentConfig.validator`, `RunOptions.validate`, `ToolValidator` |
+| Coding execution policy | path/command approval adapter | `ExecutionPolicy`, `@arnilo/prism-coding-security` |
 | Durable history | host database adapter | `SessionStore`, `assertSessionStoreConforms()` |
 | Durable audit | host ledger adapter | `RunLedger`, `redactRunLedgerRecord()` |
 | Extensions | explicit package imports only | `createExtensionKernel`, `ExtensionAPI` |
@@ -120,12 +121,25 @@ Wire those values where they matter: provider adapters receive the resolved cred
 - Prism does not sandbox host tools, extensions, provider adapters, credential resolvers, or custom middleware. Use OS/container/process isolation when code is untrusted.
 - Redaction is exact known-secret replacement only. It is not arbitrary secret detection, entropy scanning, or DLP.
 - Known secrets must be passed into redactors before data is emitted or persisted. Redact again in host adapters if they transform records after Prism redaction.
-- Tool `parameters` metadata is not validation. Add a `ToolValidator` or validate inside the tool before side effects.
+- Tool `parameters` metadata is not validated by default. Add a `ToolValidator`, use `createToolParameterValidator()` with a schema adapter, or install `@arnilo/prism-tool-validator-json-schema` before side effects.
+- MCP tools from `@arnilo/prism-mcp` are untrusted remote servers. Configure stdio commands and HTTP URLs explicitly; bound output with `maxResultBytes`; register prefixed tools only after trust review. See [MCP client bridge](mcp-tools.md).
+- Coding tools from `@arnilo/prism-coding-agent` accept an optional `ExecutionPolicy` checked inside each tool before side effects. Use `@arnilo/prism-coding-security` for path roots, command rules, and approval caching. Prism does not provide OS sandboxing unless the host supplies a sandbox adapter.
 - Permission checks happen before tool validation and before `tool.execute()`. Middleware cannot grant permission by renaming a tool.
 - Session stores and ledgers receive redacted values when a redactor is active, but durable storage remains host-owned. Enforce tenant/account/user ownership and retention in the database layer.
 - Provider-owned auth/content/session/cache/security headers win over caller headers in adapters that merge headers.
 - Security checks are bounded explicit calls on the active path. Prism adds no hidden global middleware, background workers, watchers, network calls, or filesystem scans.
 
+### 0.0.4 release security audit (2026-07-14)
+
+- `npm audit --audit-level=high`: 0 vulnerabilities at every severity.
+- Lockfile: 162 registry dependency records, all with `resolved` provenance URL and integrity hash; `npm ls --all` reports a clean graph.
+- License inventory: 160 locked third-party packages; all declare permissive MIT, ISC, BSD, Apache-2.0, or compatible dual licenses. No GPL, AGPL, SSPL, or missing lockfile license metadata.
+- Install scripts: only `better-sqlite3@12.11.1` runs an install script (`prebuild-install || node-gyp rebuild --release`), required by the explicitly installed SQLite adapter. Core and other optional packages add no install hook.
+- Secret scan: source, tests, docs, workflow files, package metadata, built tests, packed-install canary, and tarball deny-list checks found no private-key block or common live-token prefix. Runtime redaction fixtures cover requests, events, ledgers, stores, checkpoints, provider/OAuth errors, and credential ciphertext.
+- Threat suites pass for parameterized SQL/tenant isolation, HTTP URL/SSRF rejection, realpath/symlink containment, shell-metacharacter approval, schema prototype-pollution/remote-reference bounds, OAuth polling/abort/redaction, credential tamper/wrong-key/KDF floors, MCP result bounds/timeouts, and coding approval/path policy.
+
+PostgreSQL TLS/network policy, MCP endpoint allow-listing, provider base URLs, OS keychain availability, process sandboxing, workflow tenant identity, and ANSI/control-sequence sanitization in any host terminal renderer remain host boundaries. Prism 0.0.4 ships JSON-line RPC, not an interactive TUI; hosts must render untrusted model/tool text safely. Credential-gated PostgreSQL/provider/keychain tests are separate operator/CI gates, not silently replaced by mocks.
+
 ## Related APIs
 
 - [Settings, auth, trust, and security controls](settings-auth-trust-security.md): low-level helpers and boundary hardening table.

package/docs/index.md

@@ -3,16 +3,17 @@
 Prism is a TypeScript/Node.js agent harness. Host apps and extension packages own providers, tools, resources, credentials, storage, UI, and business behavior. Prism supplies contracts, registries, streaming events, and replaceable runtime primitives.
 
 ## Public contracts
-- [Public contracts](public-contracts.md): type shapes for messages, content, agents, sessions, providers, tools, context, skills, extensions, stores, resources, settings, credentials, and events.
+- [Public contracts](public-contracts.md): type shapes for messages, agents, tools, stores, generic `CheckpointStore`, atomic `LeaseStore`, bounded `EventMultiplexer`, resources, credentials, and events.
 
 ## Agent/session runtime
 - [Agent/session runtime](agent-session-runtime.md): create agents and sessions, run prompts, subscribe to normalized events, and see which `AgentConfig` fields are runtime-consumed vs host-owned metadata. Covers tool-call loop transcript shape and prior-reasoning preservation across turns.
 - [Agent definitions](agent-definitions.md): resolve declarative `AgentDefinition` values via `resolveAgentDefinition`, and turn app-config `<configRoot>/agents/<name>/AGENT.md` bundles into runnable agents via `discoverAgentBundles` / `resolveAgentBundle` (explicit tool/skill activation by name, fail-closed omitted capabilities, migration-only `activateAllCapabilities`, strict duplicate scope checks, configurable prompt layers, no auto-discovery).
 - [Agent loops](agent-loops.md): replaceable per-run control loops — `singleShotLoop` default and `generate-validate-revise` with host-supplied `validator`/`parser`/`repairer` callbacks.
-- [Agent events](agent-events.md): the `AgentEvent` stream — agent/turn/message (including live `tool_call_delta` fragments), tool execution, queue/subscriber overflow, compaction/retry, artifact validation/refinement, and error variants, redacted via `redactAgentEvent`.
+- [Agent events](agent-events.md): the `AgentEvent` stream — agent/turn/message (including live `tool_call_delta` fragments), provider turn timing, tool execution, queue/subscriber overflow, compaction/retry, artifact validation/refinement, and error variants, redacted via `redactAgentEvent`.
+- [Observability](observability.md): metadata-only `provider_turn_*` events, `ToolExecutionMetadata`, core helpers, and optional `@arnilo/prism-observability-opentelemetry` adapter.
 - [Runs and usage ledger](runs-and-usage.md): `RunLedger` adapter for durable run, event, tool-call, usage persistence, cache diagnostics, ownership/idempotency, and redaction guidance.
 - [Performance limits](performance.md): bounded live subscriber queues, branch-read pagination expectations, JSONL/dev-store limits, and production sizing assumptions.
-- [Structured output](structured-output.md): the `Artifact*` seam (parser/validator/repairer, host-defined `T`) — the only typed-output path from a loop, with a Synapta-style schema→`ArtifactValidation` mapping example and an end-to-end third-party integration walkthrough.
+- [Structured output](structured-output.md): the `Artifact*` seam plus provider-native `StructuredOutputOptions` / `structuredOutputMode` for capable models.
 
 ## Compaction/session memory
 - [Compaction and retry policies](compaction-and-retry.md): summarize branch history and retry transient provider failures with host-replaceable policies.
@@ -20,11 +21,15 @@ Prism is a TypeScript/Node.js agent harness. Host apps and extension packages ow
 - [Observational memory compaction package](compaction-observational-memory.md): optional source-backed memory, owned runtime append callback, provider-valid worker transcripts, fast compaction, recall tool, and status/view command package.
 - [Session stores](session-stores.md): `SessionStore` contract, `SessionAppendOptions`, `SessionAppendConflictError`, branch handles, `readBranchPath`, and dev-vs-production branch reads — start here for session persistence.
 - [Session stores and branching](session-stores-and-branching.md): detailed branch semantics and helper reference (kept for compatibility; links back to the canonical atomic append / branch-handle sections).
-- [Database persistence](database-persistence.md): production persistence contracts, conditional append transaction pattern, idempotency indexes, `readBranchPath`, reference relational schema, retention, migrations, and NoSQL mapping.
-- [Migration guide](migration.md): the two cross-cutting app migrations in one place — in-memory/JSONL → database-backed `ProductionPersistenceStore` persistence (+ `RunLedger`) and permissive capability defaults → Phase 38 explicit `tools`/`skills` activation, with before/after shapes and links to the detailed pages.
+- [Database persistence](database-persistence.md): production persistence contracts, shared schema/migration primitives (`@arnilo/prism/testing/persistence-schema`), conditional append transaction pattern, idempotency indexes, `readBranchPath`, reference relational schema, retention, migrations, and NoSQL mapping.
+- [SQLite persistence](sqlite-persistence.md): optional `@arnilo/prism-session-store-sqlite` adapter — `SessionStore`, `RunLedger`, `ProductionPersistenceStore`, and generic durable checkpoints and atomic leases over `better-sqlite3`.
+- [PostgreSQL persistence](postgres-persistence.md): optional pooled adapter — session/run/query persistence plus generic durable checkpoints and atomic leases over `pg`, with advisory-lock migrations and opt-in live conformance.
+- [Migration guide](migration.md): 0.0.3 compatibility and optional 0.0.4 adoption — first-party/custom database persistence plus explicit fail-closed tool/skill activation.
 - [Node JSONL session store](node-jsonl-session-store.md): development-only JSONL file adapter for single-process Node hosts; no cross-process safety.
+- [Persistence, credentials, and multimodality primitives](persistence-credentials-multimodality-primitives.md): Plan 056 inventory — session/run-ledger/persistence contracts, credential/OAuth seams, content/resource/model capabilities, package dependency matrix, conformance matrix, and threat model for production adapters.
 
 ## Provider and model connection
+- [Provider primitives](provider-primitives.md): shared bounded transport and OpenAI serialization helpers — migrated across first-party providers; native structured-output and observability contracts.
 - [Provider layer](provider-layer.md): register and resolve host-owned providers/models, choose replace-or-error duplicate policy, create provider events, stream/reconstruct tool-call deltas, use generic provider request options, and test with the mock provider; deprecated provider-level timeout/retry hints point to runtime abort/retry.
 - [Model registry](model-registry.md): register and resolve `ModelConfig` records with capabilities, limits, cost, cache support metadata, compat data, and duplicate policy.
 - [Provider caching](provider-caching.md): use `PromptCacheHints`, `PromptCacheBreakpoint`, `ModelCacheCapabilities`, cache-aware stable-prefix guidance, and shared cache diagnostics helpers; includes a per-provider explicit/implicit cache matrix for OpenAI, OpenRouter, OpenCode Go, Z.AI, Kimi, and NeuralWatt; cache hints are best-effort and cache keys are never secrets.
@@ -35,17 +40,22 @@ Prism is a TypeScript/Node.js agent harness. Host apps and extension packages ow
 
 ## Input, prompt, and context assembly
 - [SDK customization guide](customization.md): map provider resolution, middleware, context, builders, injectors, loops, compaction, retry, stores, and skills to explicit host-wired APIs.
-- [Input and prompt assembly](input-and-prompt-assembly.md): render tiny prompt templates and turn common host input, history, attachments, explicit resources, summaries, and tool results into messages with replaceable builders, provider-input assembly, legacy default order, and opt-in cache-aware ordering.
+- [Input and prompt assembly](input-and-prompt-assembly.md): render tiny prompt templates and turn common host input, history, attachments, explicit resources, summaries, and tool results into messages with replaceable builders, provider-input assembly, legacy default order, and opt-in cache-aware ordering. Audio/file/document `ContentBlock` types and capability checks are documented there.
+- [Multimodal content](multimodal-content.md): bounded `audio`, `file`, and `document` content blocks, media resolution helpers, SSRF/MIME policy, and `ModelCapabilities.input` tags.
 - [System prompts](system-prompts.md): compose explicit user/package/app/run system prompt layers, auto-load the standard `AGENTS.md` (workspace) / `SYSTEM.md` prompt files via the Node `loadSystemPromptFiles` loader (trust-gated for `AGENTS.md`), and append `SYSTEM.md` → per-agent `AGENT.md` body → repo `AGENTS.md` layers from a discovered agent bundle via `resolveAgentBundle`.
 - [Instruction injection](instruction-injection.md): register package injectors that layer redacted instructions/context blocks without granting tools, permissions, or resource escapes.
 - [Context and skills](context-and-skills.md): resolve ordered context providers and keep context/skill selection host-owned; omitted declarative skills stay inactive by default, `toolNames` fail closed before provider turns, and strict skill registries prevent silent shadowing.
 
 ## Tools
 - [Tools](tools.md): register host-owned active tools with replace-or-error duplicate policy, apply exact allow/deny filtering, and dispatch tool calls.
-- [Coding agent tools](coding-agent-tools.md): optional first-party package `@arnilo/prism-coding-agent` providing `shell`, `read`, `write`, and `edit` tools (ported from pi) as `ToolDefinition`s a host registers; pluggable operation backends, per-path mutation serialization, and read-only/coding aggregators. Host shell/filesystem access — gate with permission/trust policies.
+- [Tool execution primitives](tool-execution-primitives.md): JSON Schema validation, exclusive-aware bounded parallel dispatch, MCP bridge mapping, coding execution policy, and image-read bounds.
+- [Tool validator JSON Schema package](../packages/tool-validator-json-schema/README.md): optional `@arnilo/prism-tool-validator-json-schema` adapter for `tool.parameters`.
+- [MCP client bridge](mcp-tools.md): optional `@arnilo/prism-mcp` package mapping remote MCP tools to `ToolDefinition`s.
+- [Coding agent tools](coding-agent-tools.md): optional first-party package `@arnilo/prism-coding-agent` providing `shell`, `read`, `write`, and `edit` tools (ported from pi) as `ToolDefinition`s a host registers; pluggable operation backends, per-path mutation serialization, optional `ExecutionPolicy`, bounded image reads (`maxImageBytes`, `transformImage`), and read-only/coding aggregators. Host shell/filesystem access — gate with permission/trust policies and `@arnilo/prism-coding-security` approval.
+- [Coding execution approval and sandboxing](coding-security.md): optional `@arnilo/prism-coding-security` package for path roots, command rules, approval caching, shell-turn exclusivity, and pluggable sandbox adapters for coding tools.
 
 ## Extensions/plugins
-- [Contribution discovery (workspace)](contribution-discovery.md): opt-in, realpath-contained directory scanner turning `SKILL.md`/`manifest.json` into inert `DiscoveredContribution` envelopes the host registers — no `import()`, no auto-activate, no provider scanning. (Per-agent `AGENT.md` bundles live under an app-controlled `configRoot`; see [Agent definitions](agent-definitions.md).)
+- [Contribution discovery (workspace)](contribution-discovery.md): opt-in, realpath-contained directory scanner turning `SKILL.md`/`manifest.json` into inert `DiscoveredContribution` envelopes the host registers — no `import()`, no auto-activate, no provider scanning. Per-agent bundles remain app-controlled and are documented under Agent/session runtime.
 - [Contribution registries](contribution-registries.md): explicit host-owned registries for extension/package contributions without hidden globals, with `duplicate: "error"` strict mode for provider/model/tool/skill shadowing prevention.
 - [Extension kernel and event bus](extensions.md): load host-provided extensions in order, register contributions, emit lifecycle events, and isolate extension errors.
 - [Extension authoring guide](extension-authoring.md): publish third-party extension packages that register inert contributions and show host-owned activation, trust, permissions, redaction, and no-sandbox boundaries.
@@ -54,25 +64,31 @@ Prism is a TypeScript/Node.js agent harness. Host apps and extension packages ow
 ## Configuration/manifests
 - [Configuration and manifests](configuration-and-manifests.md): merge in-memory JSON config layers and validate data-only package manifests with prototype-pollution key rejection.
 - [Node filesystem config loader](node-filesystem-config.md): explicitly read caller-named JSON config files in Node hosts.
-- [Resource loading](resource-loading.md): decode text, JSON, and manifest resources through caller-provided loaders.
+- [Resource loading](resource-loading.md): decode text, JSON, binary, and manifest resources through caller-provided loaders with bounded byte limits.
 
 ## CLI/RPC
 - [CLI/RPC](cli-rpc.md): Run print/json modes and LF-delimited RPC over the public AgentSession runtime, including branch-handle results, fixed `forkSession`, and `checkout`.
+- [Workflows](workflows.md): optional `@arnilo/prism-workflows` typed bounded DAG orchestration — local execution plus SQLite/PostgreSQL multi-process coordination with enqueue, leases, heartbeats, fencing, durable cancel/resume, events, and optional RPC bindings. Interactive TUI (C-012) deferred.
+- [Workflow orchestration primitives](workflow-orchestration-primitives.md): architecture inventory — workflow adapters consume core `CheckpointStore`, `LeaseStore`, and bounded `EventMultiplexer`; run control and optional RPC commands stay package-local.
+- [Workflow/TUI scope](workflow-tui-primitives.md): records why 0.0.4 ships workflow APIs/RPC control but no interactive terminal UI.
 
 ## Security and credentials
 - [Host security guide](host-security.md): fail-closed checklist for credentials, settings, redaction, trust roots, permission policies, persistence, extension loading, and tool validation.
 - [Security/auth/trust](settings-auth-trust-security.md): settings providers, credential helpers, trust/permission policies, redaction controls, host-owned `AgentConfig.settings`/`credentials`, and security-boundary hardening summary.
 - [Credentials and redaction](credentials-and-redaction.md): compose explicit credential resolver order, use caller-supplied env objects/OAuth refresh helpers, avoid eager `AgentConfig.credentials` resolution, and redact known secret values.
+- [Credential storage](credential-storage.md): optional `@arnilo/prism-credentials-node` encrypted-file and system-keychain adapters for durable host-owned credentials.
 
 ## Testing and examples
-- [Provider layer](provider-layer.md): use `createMockProvider()` and provider event helpers for deterministic tests without timers, credentials, or network.
+- Provider test doubles: `createMockProvider()` and provider event helpers are documented on the canonical Provider layer page above.
 - [Provider conformance](provider-conformance.md): run network-free provider adapter assertions (stream order, abort, tool-call reconstruction, cache usage, content coverage, protected header ownership, secret leak) from `@arnilo/prism/testing/provider-conformance`.
 - [Session store conformance](session-store-conformance.md): assert any `SessionStore` adapter satisfies append/idempotency/conflict/branch invariants from `@arnilo/prism/testing/session-store-conformance`.
+- [Run ledger conformance](run-ledger-conformance.md): assert any `RunLedger` adapter satisfies durable run/event/tool/usage writes and reopen survival from `@arnilo/prism/testing/run-ledger-conformance`.
 - [Compaction conformance](compaction-conformance.md): assert any `CompactionStrategy` returns a non-empty redacted summary and observes abort from `@arnilo/prism/testing/compaction-conformance`.
 - [Tool conformance](tool-conformance.md): assert the tool-dispatch blocked-reason matrix (unknown/denied/invalid/permission/validator) and success path from `@arnilo/prism/testing/tool-conformance`.
 - [Extension conformance](extension-conformance.md): assert an `Extension` setup runs, contributions stay inert, and setup errors are redacted or rethrown from `@arnilo/prism/testing/extension-conformance`.
-- `examples/`: compile-checked typed examples and runnable mock demos (SDK basics, provider registration, auth, tools, cache-aware prompt assembly, NeuralWatt agent run, stores/branching, compaction, observational-memory recall, structured-output/artifact-loop, CLI, RPC).
+- `examples/`: compile-checked typed examples and runnable mock demos (SDK basics, provider registration, auth, tools, cache-aware prompt assembly, NeuralWatt agent run, stores/branching, compaction, observational-memory recall, structured-output/artifact-loop, CLI, RPC, workflow orchestration).
 
 ## Release and install
-- [Release and install](release-and-install.md): package layout, install specifiers, required `@arnilo/prism` peer, tarball contents and exclusions, the map-retention knob, the release workflow, and the offline test budget.
+- [Release and install](release-and-install.md): 24-package graph and profiles, install/tarball rules, deterministic resumable provenance publication, and offline test budget.
+- [Review coverage (2026-07-14)](review-coverage-2026-07-14.md): traceability matrix linking review findings and bug-report fixes to plan tasks, tests, and documentation for release 0.0.4.
 

package/docs/input-and-prompt-assembly.md

@@ -60,7 +60,7 @@ Useful exported types:
 - `DefaultInputBuilder`: the default `InputBuilder` with typed default context.
 - `InputAssemblyLayout`: `"legacy" | "cache_aware"`; legacy is default.
 - `DefaultInputBuildContext`: optional input layout, instructions, history, summaries, attachments, resource loader/URIs, tool results, middleware, ids, metadata, and abort signal.
-- `InputAttachment`: already-loaded text/content or an explicit URI loaded through a caller-provided `ResourceLoader`.
+- `InputAttachment`: already-loaded text/content blocks (including `audio`, `file`, and `document`) or an explicit URI loaded through a caller-provided `ResourceLoader`.
 - `PromptInstruction`: labeled system instruction text.
 - `DefaultPromptBuilder`: the default `PromptBuilder`.
 - `AssembleProviderInputOptions`: model, input, optional builders, context providers, selected skills, active tools, generic provider options, metadata, and signal.
@@ -82,10 +82,10 @@ The builder returns `readonly Message[]`.
 The default prompt builder still prepends context, selected skills, and tool declarations before those input messages. Cache-aware ordering gives cache-capable providers a stable prefix only while those stable inputs stay byte-stable; changing tools, context, resources, summaries, history, or attachments changes the prefix too.
 - History is prepended before current input.
 - Instructions and summaries are system messages; compacted branch summaries from `rebuildSessionContext()` use the same path.
-- Text attachments and explicit text resources are user messages.
+- Text attachments and explicit text resources are user messages; inline `audio`/`file`/`document` blocks pass through unchanged on attachments with `content`.
 - Tool results are tool messages containing `tool_result` content; the agent/session runtime uses this to feed dispatched tool results into the next provider turn, placing the assistant `tool_call` and the matching role `tool` `tool_result` before any final assistant content. Cache-aware layout keeps tool results before the current user suffix so it does not split tool transcripts.
 - Middleware runs only when `middleware` is supplied in the context.
-- `assembleProviderInput()` returns a `ProviderRequest` with the caller's model/tools/provider options/metadata/signal and composed messages/context.
+- `assembleProviderInput()` returns a `ProviderRequest` with the caller's model/tools/provider options/metadata/signal and composed messages/context. It also calls `assertMessagesSupportModelCapabilities()` so unsupported `audio`/`file`/`document`/`image` blocks fail with `UnsupportedModalityError` when the model declares `capabilities.input`.
 - `renderPromptTemplate()` replaces top-level `{{name}}` variables with caller-supplied JSON-compatible values. Strings are inserted directly; numbers, booleans, `null`, arrays, and objects are stringified deterministically with sorted object keys. Missing variables throw by default or stay unchanged with `{ missing: "preserve" }`.
 
 ## Request/response example
@@ -165,7 +165,7 @@ const request = await assembleProviderInput({
 - The builder is linear in supplied messages, attachments, resources, and tool results. Layout selection is one flattening branch over already-built groups.
 - Template expansion is dependency-free string replacement over `{{name}}` variables. It does not evaluate expressions, filters, loops, partials, JavaScript, globals, or prototype properties.
 - It performs no provider calls, tool execution, credential resolution, package discovery, filesystem scan, network access, timers, or watchers.
-- URI attachments/resources load only through the caller-provided `ResourceLoader`.
+- URI attachments/resources load only through the caller-provided `ResourceLoader`. Binary media uses `resolveMediaContentBlock()` / `loadBinaryResource()` with bounded bytes, SSRF checks for URLs, and MIME magic validation — see [Multimodal content](multimodal-content.md).
 - Do not place secrets in templates, variables, instructions, messages, attachments, tool results, metadata, middleware payloads, or docs examples.
 - Active tools are passed through from the host; prompt middleware cannot grant additional provider tools.
 - Skill selection is handled by the host/skill registry path; this builder only includes selected skills passed by the caller.
@@ -175,7 +175,8 @@ const request = await assembleProviderInput({
 - [SDK customization guide](customization.md): high-level map of replaceable provider resolution, middleware, context, builder, injector, loop, compaction, retry, store, and skill seams.
 - [Public contracts](public-contracts.md): `Message`, `ContentBlock`, `InputBuilder`, `InputBuildContext`, `ToolResult`, and `ResourceLoader` shapes.
 - [Context and skills](context-and-skills.md): ordered context resolution feeding prompt composition.
-- [Resource loading](resource-loading.md): `loadTextResource()` behavior used for explicit URI resources.
+- [Multimodal content](multimodal-content.md): `audio`/`file`/`document` blocks, bounded media resolution, and capability checks.
+- [Resource loading](resource-loading.md): `loadTextResource()` and `loadBinaryResource()` behavior used for explicit URI resources.
 - [Middleware hooks](middleware-hooks.md): ordered middleware registry and `input_assembly`, `context`, and `prompt_build` hooks.
 - [System prompts](system-prompts.md): compose layered package/app/user/run prompts before input assembly.
 - [Contribution registries](contribution-registries.md): inert input, prompt, context, and skill contributions.