@arnilo/prism 0.0.1 → 0.0.3

package/docs/runs-and-usage.md

@@ -0,0 +1,236 @@
+# Runs and usage ledger
+
+## 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.).
+
+APIs:
+
+- `RunLedger`
+- `RunLedgerRecord`
+- `RunRecord` / `RunStatus`
+- `AgentEventRecord`
+- `ToolCallRecord` / `ToolCallStatus`
+- `UsageRecord`
+- `redactRunLedgerRecord()`
+
+## When to use it
+
+Configure `AgentConfig.runLedger` when you want every run of an agent to be persisted. Override it per run with `RunOptions.runLedger` if a single run needs a different adapter or no adapter at all. Use `runLedger` whenever you need durable observability, billing, audit replay, or run-scoped analytics.
+
+Do not use `RunLedger` as a replacement for `SessionStore` — messages, branches, and session entries continue to go through `SessionStore.append()`. Do not use it for live streaming; subscribers still receive `AgentEvent` through `session.subscribe()`.
+
+## Inputs / request
+
+Set the ledger and optional ownership scope/idempotency key on the agent or the run:
+
+| Field | Where | Purpose |
+| --- | --- | --- |
+| `runLedger` | `AgentConfig` / `RunOptions` | `RunLedger` adapter. `RunOptions.runLedger` wins. |
+| `ownership` | `AgentConfig` / `RunOptions` | `{ tenantId?, accountId?, userId? }` copied into every record. `RunOptions.ownership` wins. |
+| `idempotencyKey` | `AgentConfig` / `RunOptions` | Optional key for run deduplication. `RunOptions.idempotencyKey` wins. |
+
+`RunLedger` methods:
+
+| Method | Record | When called |
+| --- | --- | --- |
+| `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. |
+
+All methods may be sync or async (`void | Promise<void>`). The runtime awaits them at safe boundaries, so a slow adapter blocks the run.
+
+## Outputs / response / events
+
+The adapter receives these record shapes:
+
+`RunRecord`:
+
+| Field | Purpose |
+| --- | --- |
+| `id` | Same as `runId`. |
+| `sessionId` | Session id. |
+| `branchId` | Current branch leaf at run start. |
+| `model` | Resolved model config for the run. |
+| `provider` | Resolved provider id for the run. |
+| `idempotencyKey` | Optional host key. |
+| `status` | `queued` \| `running` \| `succeeded` \| `failed` \| `aborted`. |
+| `startedAt` / `finishedAt` | ISO timestamps. |
+| `abortReason` | Set when status is `aborted`. |
+| `error` | `ErrorInfo` when status is `failed`. |
+| `tenantId` / `accountId` / `userId` | From active ownership scope. |
+
+`AgentEventRecord`:
+
+| Field | Purpose |
+| --- | --- |
+| `id` | Unique ledger row id. |
+| `runId` / `sessionId` / `entryId` | Correlation ids. |
+| `type` | `AgentEvent["type"]` discriminator. |
+| `timestamp` | Event emission time. |
+| `event` | The emitted `AgentEvent`. |
+| `redacted` | `true` when a `SecretRedactor` is active. |
+
+`ToolCallRecord`:
+
+| Field | Purpose |
+| --- | --- |
+| `id` | Unique ledger row id. |
+| `toolCallId` / `name` | From the provider tool call. |
+| `arguments` | JSON object passed to the tool. |
+| `result` | `ToolResult` for `finished`/`error`/`blocked` rows. |
+| `status` | `started` \| `finished` \| `error` \| `blocked`. Progress snapshots reuse `started` with `progress` fields. |
+| `reason` | Block reason for `blocked` rows (`unknown_tool`, `tool_denied`, `invalid_arguments`, `permission_denied`, `validation_failed`). |
+| `progress` / `progressMetadata` / `progressAt` | Populated on progress snapshots. |
+| `startedAt` / `finishedAt` | Tool-call timing. |
+| `redacted` | `true` when a `SecretRedactor` is active. |
+
+`UsageRecord`:
+
+| Field | Purpose |
+| --- | --- |
+| `id` | Unique ledger row id. |
+| `runId` / `sessionId` / `entryId` | Correlation ids. |
+| `usage` | `Usage` shape: input/output/total/cache tokens, cost, currency. |
+| `recordedAt` | ISO timestamp. |
+
+## Status transitions
+
+```
+queued ──> running ──> succeeded
+              │
+              ├──────> failed
+              │
+              └──────> aborted
+```
+
+- `queued` is reserved for host scheduling and is not emitted by the runtime.
+- `running` is written immediately after provider/model resolution and `agent_started`.
+- `succeeded` / `failed` / `aborted` are written once in `finally`.
+- Only the final `RunRecord` contains `finishedAt`, `abortReason`, or `error`.
+
+## Request/response example
+
+```json
+{
+  "id": "run_abc",
+  "sessionId": "session_1",
+  "branchId": "branch_1",
+  "provider": "openai",
+  "model": { "provider": "openai", "model": "gpt-4o" },
+  "status": "succeeded",
+  "startedAt": "2024-01-01T00:00:00Z",
+  "finishedAt": "2024-01-01T00:00:05Z",
+  "tenantId": "tenant_a",
+  "idempotencyKey": "run-key-123"
+}
+```
+
+```json
+{
+  "id": "toolcall_def",
+  "sessionId": "session_1",
+  "runId": "run_abc",
+  "toolCallId": "call_1",
+  "name": "echo",
+  "arguments": { "text": "hi" },
+  "status": "finished",
+  "result": { "toolCallId": "call_1", "name": "echo", "value": { "text": "hi" } },
+  "startedAt": "2024-01-01T00:00:01Z",
+  "finishedAt": "2024-01-01T00:00:02Z",
+  "redacted": false
+}
+```
+
+## Implementation example
+
+```ts
+import {
+  cacheUsageReport,
+  createAgent,
+  createMockProvider,
+  createSecretRedactor,
+  providerDone,
+  providerTextDelta,
+  type RunLedger,
+  type RunRecord,
+  type AgentEventRecord,
+  type ToolCallRecord,
+  type UsageRecord,
+} from "@arnilo/prism";
+
+const runs: RunRecord[] = [];
+const events: AgentEventRecord[] = [];
+const toolCalls: ToolCallRecord[] = [];
+const usageRows: UsageRecord[] = [];
+
+const ledger: RunLedger = {
+  appendRun: async (record) => { runs.push(record); },
+  appendEvent: async (record) => { events.push(record); },
+  appendToolCall: async (record) => { toolCalls.push(record); },
+  appendUsage: async (record) => { usageRows.push(record); },
+};
+
+const agent = createAgent({
+  model: { provider: "mock", model: "demo" },
+  provider: createMockProvider([providerTextDelta("Hello"), providerDone()]),
+  runLedger: ledger,
+  ownership: { tenantId: "tenant_a", accountId: "account_a" },
+  idempotencyKey: "agent-key",
+  redactor: createSecretRedactor([process.env.APP_KEY!]),
+});
+
+const session = agent.createSession({ id: "session_1" });
+
+// per-run override
+await session.run("Hello", {
+  idempotencyKey: "run-key-123",
+});
+
+console.log(runs.at(-1)?.status); // succeeded
+console.log(cacheUsageReport(usageRows.at(-1)?.usage));
+// { cacheReadTokens: 0, cacheWriteTokens: 0, ... } when provider usage is present
+```
+
+## Extension and configuration notes
+
+### Production ledger adapter checklist
+
+- Treat `RunLedger` as write-only from Prism's point of view; expose replay/query APIs through `ProductionPersistenceStore` or host-owned reads.
+- Preserve ordering within each `runId`; allocate a monotonic event `sequence` before acknowledging durable writes.
+- Store `RunRecord.idempotencyKey` for host-level run deduplication, but never put credentials or provider clients in idempotency rows.
+- Redact before durable writes if the adapter transforms records after Prism redaction. Persist `redacted: true` when a redactor was active.
+- Test the full persistence path with the network-free [`examples/external-app-db-backed.ts`](../examples/external-app-db-backed.ts) pattern: run, event, tool-call, usage, branch checkout/fork, and resume queries.
+
+- `AgentConfig.runLedger` applies to every run of the agent. `RunOptions.runLedger` overrides it for a single run.
+- `AgentConfig.ownership` is the default ownership scope; `RunOptions.ownership` overrides it per run.
+- `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`.
+- 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.
+
+## Security and performance notes
+
+- **No credentials.** `RunLedger` records never contain `AIProvider`, `CredentialResolver`, `ProviderResolver`, provider API keys, or credential values. They store only ids, status, timestamps, and the public event/result/usage shapes.
+- **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.
+- **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.
+
+## Related APIs
+
+- [Performance limits](performance.md): batching, cursor keys, and production sizing assumptions.
+- [Agent/session runtime](agent-session-runtime.md): `session.run()` and runtime event emission.
+- [Agent events](agent-events.md): `AgentEvent` union and `session.subscribe()`.
+- [Tools](tools.md): `ToolResult`, `ToolCallContent`, and `dispatchToolCall()`.
+- [Database persistence](database-persistence.md): reference relational schema for runs, events, tool calls, and usage.
+- [Session store conformance](session-store-conformance.md): pair ledger tests with the session-store adapter baseline.
+- [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.
+- [Public contracts](public-contracts.md): full contract inventory.

package/docs/session-store-conformance.md

@@ -0,0 +1,78 @@
+# Session store conformance
+
+## What it does
+
+Session store conformance helpers are dependency-free assertions for `SessionStore` adapter tests. They exercise the append/idempotency/conflict/branch invariants of any `SessionStore` implementation without network or credentials.
+
+Exported from `@arnilo/prism/testing/session-store-conformance`:
+
+- `assertSessionStoreConforms(store, options?)`
+- `SessionStoreConformanceOptions`
+
+## When to use it
+
+Use this helper when implementing a DB-backed `SessionStore` (for example, the reference pattern in `examples/external-app-db-backed.ts`). It asserts the contract that the core memory and JSONL stores already satisfy, so an adapter author does not re-derive it:
+
+- append + `list` round-trip
+- duplicate entry id rejection
+- `expectedParentId` mismatch throws `SessionAppendConflictError` and writes nothing (atomic append)
+- `idempotencyKey` deduplication of an exact retry at the same position
+- 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`)
+
+## Inputs / request
+
+```ts
+import { assertSessionStoreConforms } from "@arnilo/prism/testing/session-store-conformance";
+import type { SessionStore } from "@arnilo/prism";
+
+await assertSessionStoreConforms(myDbBackedStore, { exerciseReadBranchPath: true });
+```
+
+`SessionStoreConformanceOptions`:
+- `sessionId?: string` — stable session id for the run (default `"conformance"`)
+- `exerciseReadBranchPath?: boolean` — also probe `readBranchPath` when implemented
+
+## Outputs / response / events
+
+Returns `Promise<void>`; throws a plain `Error` on the first contract violation. No events, no runner.
+
+## Request/response example
+
+```ts
+import { assertSessionStoreConforms } from "@arnilo/prism/testing/session-store-conformance";
+
+await assertSessionStoreConforms(postgresBackedStore);
+// throws if the adapter accepts a duplicate id, ignores a missing parent, or
+// collapses distinct linear appends sharing an idempotency key.
+```
+
+## Implementation example
+
+```ts
+import { assertSessionStoreConforms } from "@arnilo/prism/testing/session-store-conformance";
+import { createMemorySessionStore } from "@arnilo/prism";
+
+// The core memory store conforms:
+await assertSessionStoreConforms(createMemorySessionStore());
+```
+
+## Extension and configuration notes
+
+- The helper writes real entries into the supplied store; use a throwaway session id or a test schema.
+- `readBranchPath` is optional; stores that omit it skip that probe.
+- Adapter authors should also exercise `rebuildSessionContext`/`getSessionBranchEntries` with their own fixtures for branch-rebuild behavior beyond the conformance baseline.
+
+## Security and performance notes
+
+- No credentials, no network, no real secrets required.
+- The helper performs a small fixed number of appends; it is bounded and fast.
+- It does not assert secret redaction in stored entries — pair with `createSecretRedactor` checks in your own tests when entries may carry secret text.
+
+## Related APIs
+
+- [Session stores and branching](session-stores-and-branching.md)
+- [Session stores](session-stores.md)
+- [Database persistence](database-persistence.md)
+- [Provider conformance](provider-conformance.md)

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

@@ -1,16 +1,18 @@
 # Session stores and branching
 
+> Compatibility page: the canonical session-store overview now lives at [Session stores](session-stores.md). This page retains the detailed branch-helper reference and is kept to avoid breaking existing links.
+
 ## What it does
 
-Session store helpers define branch-aware session entries and pure utilities for creating entries, listing branch leaves, reading a leaf path, and rebuilding provider context from a selected leaf.
+Session store helpers define branch-aware session entries and pure utilities for creating entries, listing branch leaves, reading a leaf path, and rebuilding provider context from a selected leaf. For atomic append options, `SessionAppendConflictError`, branch handles, and production `readBranchPath` guidance, start with [Session stores](session-stores.md#atomic-append-and-branch-handles).
 
 Public helpers:
 
 - `createSessionEntry(options)`
 - `createMemorySessionStore(initialEntries?)`
-- `getSessionBranchEntries(entries, options)`
+- `getSessionBranchEntries(entries, options)` and `getSessionBranchEntries(reader, query)`
 - `listSessionBranches(entries)`
-- `rebuildSessionContext(entries, options)`
+- `rebuildSessionContext(entries, options)` and `rebuildSessionContext(reader, query)`
 
 ## When to use it
 
@@ -32,7 +34,7 @@ Do not use them as a database layer, migration system, lock service, compaction
 | `runId` | Optional run id. |
 | `message`, `event`, `model`, `previousModel`, `label`, `summary`, `data`, `metadata` | Optional payload fields for the entry kind. |
 
-`rebuildSessionContext()` and `getSessionBranchEntries()` accept an optional `leafId`. If omitted, the last entry is used as the leaf. `createMemorySessionStore()` accepts optional initial entries.
+`rebuildSessionContext()` and `getSessionBranchEntries()` accept an optional `leafId`. If omitted, the last entry is used as the leaf. The async reader overloads accept `SessionBranchRead { sessionId, leafId?, cursor?, limit? }` and call a `BranchReader` / `readBranchPath` implementation so database adapters can return one ancestor chain without `list(sessionId)`. `createMemorySessionStore()` accepts optional initial entries.
 
 ## Outputs / response / events
 
@@ -84,7 +86,7 @@ const context = rebuildSessionContext(await store.list("s1"), { leafId: label.id
 
 ## Extension and configuration notes
 
-Stores and extensions can use these data helpers directly. Store adapters only need append/list/get behavior; branch queries are derived in memory from listed entries.
+Stores and extensions can use these data helpers directly. Store adapters only need append/list/get behavior; branch queries are derived in memory from listed entries unless the store implements `readBranchPath`. See [Session stores](session-stores.md) for `SessionAppendOptions`, `SessionAppendConflictError`, and `(sessionId, leafId)` branch-handle guidance.
 
 `createMemorySessionStore()` is the built-in in-memory implementation. It preserves append order per session, isolates session ids, returns entries by id in O(1), rejects duplicate entry ids, and returns deep copies from `list()` and `get()`. It is process memory only; hosts that need durability should pass another `SessionStore`.
 
@@ -102,13 +104,15 @@ Use `createDefaultCompactionStrategy()` to create compaction entries that `rebui
 
 - Helpers are pure data functions: no provider calls, tool calls, settings reads, credential resolution, filesystem access, network access, timers, or dependencies.
 - Store only host-approved session entries. Do not put provider credentials, credential resolvers, provider objects, full provider requests, or secrets in entries.
-- Branch rebuild is linear over listed entries and uses `Map`, `Set`, and arrays only.
+- Branch rebuild is linear over listed entries for development stores. Production stores should implement `readBranchPath` and return one branch ancestor chain so large sessions are not fully loaded.
 - Compaction-aware rebuild keeps raw branch entries in `entries`; only provider-context `messages`/`summaries` are reduced.
 - Memory store lookup by id is O(1); list is O(n) for that session.
 - Duplicate ids and missing parents fail clearly instead of guessing a branch.
 
 ## Related APIs
 
+- [Migration guide](migration.md): moving branch-handle reads from the dev `list(sessionId)` path to a database-backed `readBranchPath`.
+- [Session stores](session-stores.md): canonical overview for `SessionAppendOptions`, `SessionAppendConflictError`, branch handles, and dev-vs-production branch reads.
 - [Public contracts](public-contracts.md): `SessionEntry`, `SessionStore`, `StoreFactory`, and session contracts.
 - [Agent/session runtime](agent-session-runtime.md): runtime sessions use these branch helpers for store-backed history, checkout, fork, and clone.
 - [Node JSONL session store](node-jsonl-session-store.md): optional Node filesystem store for caller-named JSONL files.

package/docs/session-stores.md

@@ -0,0 +1,126 @@
+# Session stores
+
+## What it does
+
+Session stores persist `SessionEntry` records for agent sessions. The `SessionStore` contract is the runtime seam: `append(entry)`, `list(sessionId)`, and an optional `get(id)`. Everything else — branch reconstruction, compaction boundaries, redaction, pagination, retention, and multi-tenant ownership — is layered on top by the runtime or by host adapters.
+
+This page describes the store contract, built-in helpers, and where to find the production schema reference.
+
+## When to use it
+
+Use `SessionStore` when you write a host adapter that keeps session entries durable across restarts. Use the built-in `createMemorySessionStore()` for tests and throwaway sessions. Use `createJsonlSessionStore()` from `@arnilo/prism/node/session-store-jsonl` only for single-process development. For production multi-tenant or multi-writer storage, implement a database-backed `SessionStore` or `ProductionPersistenceStore` using the reference schema in [Database persistence](database-persistence.md), then run [Session store conformance](session-store-conformance.md) against the adapter.
+
+## Inputs / request
+
+```ts
+import type { SessionStore, SessionEntry } from "@arnilo/prism";
+```
+
+`SessionStore` methods:
+
+| Method | Purpose |
+| --- | --- |
+| `append(entry, options?)` | Persist one `SessionEntry`. `SessionAppendOptions` can carry `expectedParentId` and an opaque `idempotencyKey`. Rejects duplicate ids within the store. |
+| `list(sessionId)` | Return all entries for one session in stored order. Development fallback for branch reads. |
+| `get?(id)` | Return one entry by id, if present. Optional. |
+| `readBranchPath?(query)` | Optional DB-friendly branch read. Return one branch's ancestor chain as a `PersistencePage<SessionEntry>` so the runtime can avoid `list(sessionId)`. |
+
+Public helpers:
+
+| Helper | Purpose |
+| --- | --- |
+| `createSessionEntry(options)` | Build a `SessionEntry` with generated `id`/`timestamp` when omitted. |
+| `createMemorySessionStore(initialEntries?)` | Built-in in-memory `SessionStore`. |
+| `getSessionBranchEntries(entries, options)` | Return root-to-leaf entries for a leaf id (sync array path). |
+| `getSessionBranchEntries(reader, query)` | Async overload for a `BranchReader` / `readBranchPath` implementation. |
+| `listSessionBranches(entries)` | List every branch handle as `{ leafId, entries }`. Pair with `sessionId` for a durable `(sessionId, leafId)` branch handle. |
+| `rebuildSessionContext(entries, options)` | Rebuild provider-context `messages` and `summaries` from a branch, honoring compaction entries (sync array path). |
+| `rebuildSessionContext(reader, query)` | Async overload that reads one branch path without a full-session load. |
+
+## Outputs / response / events
+
+A `SessionStore` returns `SessionEntry` arrays. Branch helpers return deep copies. `rebuildSessionContext()` returns `{ leafId, entries, messages, summaries }` where `entries` is the raw branch, `messages` is the provider context, and `summaries` includes compaction summaries.
+
+## Request/response example
+
+```json
+{
+  "id": "entry_1",
+  "sessionId": "s1",
+  "timestamp": "2024-06-15T10:00:00Z",
+  "kind": "message",
+  "message": {
+    "role": "user",
+    "content": [{ "type": "text", "text": "Hello" }]
+  }
+}
+```
+
+## Implementation example
+
+```ts
+import { createMemorySessionStore, createSessionEntry } from "@arnilo/prism";
+
+const store = createMemorySessionStore();
+const entry = createSessionEntry({
+  sessionId: "s1",
+  kind: "message",
+  message: { role: "user", content: [{ type: "text", text: "Hello" }] },
+});
+await store.append(entry);
+const entries = await store.list("s1");
+```
+
+For a database-backed store, see the reference schema and query shapes in [Database persistence](database-persistence.md). A runnable external-app reference that implements `SessionStore` + `RunLedger` + `ProductionPersistenceStore` and self-checks with `assertSessionStoreConforms(..., { exerciseReadBranchPath: true })` lives in [`examples/external-app-db-backed.ts`](../examples/external-app-db-backed.ts).
+
+### Atomic append and branch handles
+
+```ts
+import type { SessionAppendOptions, SessionBranchHandle } from "@arnilo/prism";
+
+const handle: SessionBranchHandle = { sessionId: "s1", leafId: "entry_1" };
+const options: SessionAppendOptions = {
+  expectedParentId: handle.leafId,
+  idempotencyKey: "request-42", // opaque host value; never a credential
+};
+await store.append(entry, options);
+```
+
+`SessionAppendConflictError` carries this stable shape:
+
+```ts
+{
+  code: "session_append_conflict";
+  expectedParentId?: string;
+  currentLeafId?: string;
+  idempotencyDuplicate?: boolean;
+}
+```
+
+Recognize it with `isSessionAppendConflict(error)`, not message text. Built-in stores reject duplicate entry ids, dangling `expectedParentId` values, and exact idempotency retries. They allow two distinct children of the same existing parent because that is a branch/fork, not parent-order corruption. Production stores may add a stricter branch-tip compare-and-swap when a host wants one-writer linear branches.
+
+## Extension and configuration notes
+
+- The runtime only requires `SessionStore`. Hosts opt into `ProductionPersistenceStore` for paginated reads and audit tables.
+- Store adapters own id generation policy, ordering, duplicate detection, idempotency storage, and error handling.
+- `AgentSession` uses `AgentSessionConfig.store` before `AgentConfig.store`; otherwise it falls back to a private memory store.
+- Branch semantics are parent links plus a leaf id. External UIs should keep branch handles as `(sessionId, leafId)`; RPC exposes an additional `handleId` for active handles.
+- Development stores can omit `readBranchPath`; the runtime falls back to `list(sessionId)` and the pure in-memory branch walk. Database-backed stores should implement `readBranchPath` so `entries()`, `clone()`, and context rebuild read only the selected ancestor chain.
+
+## Security and performance notes
+
+- Do not store provider credentials, credential resolvers, provider instances, or unredacted secrets in session entries, append options, idempotency keys, or branch records.
+- Use `AgentConfig.redactor` or `RunOptions.redactor` to redact secrets before entries reach durable stores. Stores receive already-redacted `SessionEntry` values.
+- `createMemorySessionStore()` keeps O(1) duplicate/idempotency/parent checks in process-local maps; it is not durable.
+- The JSONL adapter serializes appends per store instance, has no cross-process lock, and is not suitable for production multi-writer storage.
+- Database-backed stores should follow the indexes and retention guidance in [Database persistence](database-persistence.md). Implement `readBranchPath` as a single branch-path query (for example a recursive CTE) and avoid loading entire large sessions into memory when only one branch is needed.
+
+## Related APIs
+
+- [Session store conformance](session-store-conformance.md): dependency-free adapter assertions for append/idempotency/conflict/branch invariants.
+- [Migration guide](migration.md): moving from this memory/JSONL store to a database-backed adapter.
+- [Session stores and branching](session-stores-and-branching.md): detailed branch helpers, compaction boundaries, and runtime branch semantics.
+- [Database persistence](database-persistence.md): reference relational schema, indexes, retention, migrations, and NoSQL mapping notes.
+- [Node JSONL session store](node-jsonl-session-store.md): development-only file adapter.
+- [Agent/session runtime](agent-session-runtime.md): runtime sessions use stores for history, checkout, fork, and clone.
+- [Public contracts](public-contracts.md): `SessionEntry`, `SessionStore`, `StoreFactory`, and production persistence contracts.

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. 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, and stored `SessionEntry` values.
+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.
 
 ## Request/response example
 ```ts
@@ -47,6 +47,7 @@ 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,
   redactor: apiKey ? createSecretRedactor([apiKey]) : undefined,
@@ -56,14 +57,26 @@ 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.
+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.
 
 ## 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, 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.
+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.
 
-`@arnilo/prism/node/trust` resolves symlinks on both the trusted root and the target path. A path that is lexically inside a trusted root but escapes it through a symlink is rejected, and realpath failures (missing root, permission error) fail closed.
+Boundary hardening summary:
+
+| Boundary | Fail-closed rule |
+| --- | --- |
+| Contribution files | `SKILL.md` and `manifest.json` are realpath-checked inside the contribution directory before read. |
+| Instruction resources | Markdown resources are realpath-contained unless host passes explicit `resourceTrust`; `permission` still gates reads. |
+| Injector context | `InstructionContext.input` and `history` are redacted before injector `apply`; injectors grant no tools, skills, permissions, or validators. |
+| System prompt sources | Unknown custom sources rank below app/run layers, so caller `run` policy cannot be overridden by sorting after it. |
+| Config/manifest JSON | `__proto__`, `prototype`, and `constructor` keys are rejected at every depth before merge/clone. |
+| Provider headers | Adapters merge caller headers first, then provider-owned auth/content/session/cache/security/attribution headers last. |
+
+`@arnilo/prism/node/trust` resolves symlinks on both the trusted root and the target path. A path that is lexically inside a trusted root but escapes it through a symlink is rejected, and realpath failures (missing root, permission error) fail closed. Contribution discovery and discovered instruction resources reuse this check before reading entry/resource files.
 
 ## Related APIs
+- [Host security guide](host-security.md): fail-closed checklist for wiring credentials, redaction, trust, permissions, persistence, extension loading, and tool validation in an embedding app.
 - `createStaticSettingsProvider`, `createChainedSettingsProvider`
 - `createMemoryCredentialStore`, `createChainedCredentialResolver`, `createExplicitCredentialResolver`, `createEnvCredentialResolver`, `refreshOAuthCredential`, `resolveCredentialValue`
 - `createStaticTrustPolicy`, `assertTrusted`, `isTrusted`, `TrustDeniedError`
@@ -71,3 +84,4 @@ Prism does not sandbox host tools or extensions. Prism does not read environment
 - `createSecretRedactor`, `redactMessage`, `redactAgentEvent`, `redactSessionEntry`, `redactProviderRequest`
 - `@arnilo/prism/node/settings`: `defaultUserSettingsPath`, `readSettingsFile`, `loadSettingsFiles`
 - `@arnilo/prism/node/trust`: `createPathTrustPolicy`, `isPathInside`, `isPathInsideReal`
+- [Contribution discovery (workspace)](contribution-discovery.md): `createPathTrustPolicy` + `isPathInsideReal` gate workspace contribution roots fail-closed.