@arnilo/prism 0.0.1 → 0.0.2

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

@@ -18,6 +18,7 @@ Do not use it for tool execution, provider calls, file discovery, credential loo
 import { createDefaultInputBuilder } from "@arnilo/prism";
 
 const messages = await createDefaultInputBuilder().build("Summarize", {
+  inputLayout: "legacy", // default; "cache_aware" passes the cache-aware layout preference
   systemInstructions: "Be accurate.",
   developerInstructions: "Cite supplied context only.",
   history,
@@ -46,6 +47,7 @@ import { assembleProviderInput, createDefaultPromptBuilder } from "@arnilo/prism
 const request = await assembleProviderInput({
   model: { provider: "mock", model: "demo" },
   input: "Explain this file",
+  inputLayout: "cache_aware",
   contextProviders: [projectContext],
   promptBuilder: createDefaultPromptBuilder(),
   tools: activeTools,
@@ -56,7 +58,8 @@ Useful exported types:
 
 - `AgentInput`: `string | Message | readonly Message[]`.
 - `DefaultInputBuilder`: the default `InputBuilder` with typed default context.
-- `DefaultInputBuildContext`: optional instructions, history, summaries, attachments, resource loader/URIs, tool results, middleware, ids, metadata, and abort signal.
+- `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`.
 - `PromptInstruction`: labeled system instruction text.
 - `DefaultPromptBuilder`: the default `PromptBuilder`.
@@ -69,10 +72,18 @@ The builder returns `readonly Message[]`.
 
 - String input becomes one user text message.
 - `Message` and `Message[]` input are preserved.
+- Legacy layout is the default. Set `inputLayout: "cache_aware"` on the default builder, `assembleProviderInput()`, `AgentConfig`, or `RunOptions` to pass the cache-aware layout preference without replacing the builder.
+
+| Layout | Input message order |
+| --- | --- |
+| `legacy` | instructions → summaries → history → current input → attachments/resources → tool results |
+| `cache_aware` | instructions → attachments/resources → summaries → history → tool results → current input |
+
+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.
-- 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.
+- 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.
 - `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" }`.
@@ -123,8 +134,12 @@ const messages = await createDefaultInputBuilder().build(prompt, {
   },
   middleware,
 });
+
+await session.run("Explain this", { inputLayout: "cache_aware" });
 ```
 
+Cache-aware mode is opt-in; hosts that do nothing keep legacy order.
+
 ## Extension and configuration notes
 
 Extensions can contribute `InputBuilder`, `PromptBuilder`, and `ContextProvider` objects through the extension API, but contributions stay inert until the host resolves and calls or passes them. The agent/session runtime uses configured builders/providers only when the host puts them on `AgentConfig`; it does not load extensions or registries itself. Defaults are built-ins; hosts can replace them with compatible builders. Prompt templates are caller-side string expansion only; they do not load resources or contributions.
@@ -147,7 +162,7 @@ const request = await assembleProviderInput({
 
 ## Security and performance notes
 
-- The builder is linear in supplied messages, attachments, resources, and tool results.
+- 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`.
@@ -157,6 +172,7 @@ const request = await assembleProviderInput({
 
 ## Related APIs
 
+- [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.

package/docs/instruction-injection.md

@@ -0,0 +1,183 @@
+# Instruction injection
+
+## What it does
+
+Instruction injectors let a package modify how context is formulated and inject its own instructions to modify agent behavior — on the first turn, every turn, or in response to user input — without forking the input/prompt pipeline and without hidden globals. Each injector contributes only `instructions` (text) and `contextBlocks`; it cannot register tools, skills, or permissions, and cannot bypass the validator or the permission gate.
+
+Injectors are the package-side complement to the host-owned `systemInstructions` base path: the host sets base instructions, then selected package injectors layer additional instructions and context blocks per turn.
+
+## When to use it
+
+- A package wants to bias the model toward a response format (e.g. "answer in JSON") every turn.
+- A package wants to inject project context (e.g. a repo summary) on the first turn only.
+- A package wants to react to user input (via a `predicate`) without re-authoring the assembler.
+- A package wants to ship a discoverable `.agents/instructions/<name>/` bundle that hosts opt into by name.
+
+Injectors are **not** a way to grant tool access, change credentials, or mutate provider request options.
+
+## Inputs / request
+
+Injectors implement `InstructionInjector`:
+
+```ts
+type InstructionTiming = "first_turn" | "every_turn" | "on_input";
+
+interface InstructionContext {
+  readonly sessionId: string;
+  readonly runId: string;
+  readonly turn: number;          // 1-based; undefined is treated as turn 1
+  readonly input: readonly Message[];  // already redacted by the runtime
+  readonly history: readonly Message[]; // redacted messages from prior turns
+  readonly metadata: Readonly<Record<string, unknown>>;
+  readonly signal: AbortSignal;
+}
+
+interface InstructionContribution {
+  readonly instructions?: string;
+  readonly contextBlocks?: readonly ContextBlock[];
+  readonly when: InstructionTiming;
+  readonly predicate?: (ctx: InstructionContext) => boolean;
+}
+
+interface InstructionInjector {
+  readonly name: string;
+  readonly description?: string;
+  apply(ctx: InstructionContext): InstructionContribution;
+}
+```
+
+`InstructionContext` fields are already redacted by the runtime before `apply` runs: current input is run through the active `AgentConfig.redactor` / `RunOptions.redactor` during assembly, and history holds previously-redacted messages. Direct `assembleProviderInput()` callers that use injectors should pass the same `redactor` option to keep this boundary.
+
+### Lifecycle
+
+| `when` | `predicate` | Applied when |
+|---|---|---|
+| `first_turn` | ignored | `ctx.turn === 1` |
+| `every_turn` | ignored | every turn |
+| `on_input` | absent | every turn (default) |
+| `on_input` | present | turns where `predicate(ctx)` returns `true` |
+
+Only `instructions` and `contextBlocks` are honored from a contribution; other fields grant nothing (see [Security and performance notes](#security-and-performance-notes)).
+
+## Outputs / response / events
+
+Injectors do not emit events. Their output is folded into the assembled `ProviderRequest`:
+
+- **Instructions** layer via `composeSystemPrompt(injectorContributions, { base: systemInstructions })` as `source: "package"`, `mode: "append"`. Host base instructions come first, then injector package instructions appended. This keeps a single prompt-composition code path (no parallel prompt code in the assembler).
+- **Context blocks** merge via `resolveContextProviders`, appended after host+skill provider blocks, before the context middleware hook runs. `ponytail:` the assembler threads `injectedBlocks` into `resolveContextProviders` so the existing context middleware flow is untouched and the diff stays minimal.
+
+`runInstructionInjectors(injectors, ctx)` runs each selected injector against a turn-local `InstructionContext`, returning `{ instructions: SystemPromptContribution[]; contextBlocks: ContextBlock[] }`. It aborts on `ctx.signal`.
+
+## Request/response example
+
+```ts
+const jsonInjector: InstructionInjector = {
+  name: "json-always",
+  apply: () => ({ instructions: "Always answer in JSON.", when: "every_turn" }),
+};
+
+const projectContext: InstructionInjector = {
+  name: "project-context",
+  apply: () => ({
+    contextBlocks: [{ title: "Repo", content: "Prism monorepo — see docs/." }],
+    when: "first_turn",
+  }),
+};
+
+const onInputJson: InstructionInjector = {
+  name: "json-on-json-input",
+  apply: (ctx) => ({
+    instructions: "Reply with JSON because the user asked for JSON.",
+    when: "on_input",
+    predicate: (c) => c.input.some((m) => /json/i.test(JSON.stringify(m.content))),
+  }),
+};
+```
+
+## Implementation example
+
+```ts
+import { createAgent, createMockProvider, providerDone, createSecretRedactor } from "@arnilo/prism";
+
+const jsonInjector = { name: "json-always", apply: () => ({ instructions: "Answer in JSON.", when: "every_turn" as const }) };
+
+const session = createAgent({
+  model: { provider: "mock", model: "demo" },
+  provider: createMockProvider([providerDone()]),
+  instructions: "You are helpful.",
+  instructionInjectors: [jsonInjector],
+}).createSession();
+
+await session.run("List primes under 10.");
+```
+
+### Selection and override semantics
+
+`AgentConfig.instructionInjectors` configures a base injector list; `RunOptions.instructionInjectors` overrides it (last wins), mirroring `activeSkills`. `resolveInstructionInjectors` resolves names against a registry fail-closed:
+
+```ts
+import { resolveInstructionInjectors } from "@arnilo/prism";
+
+const injectors = resolveInstructionInjectors({ registry, names: ["json-always", "project-context"] });
+// Unknown name throws: Error: Unknown instruction injector: <name>
+```
+
+### Phase 29 discovery loading
+
+A discovered `.agents/instructions/<name>/manifest.json` (see [Contribution discovery](contribution-discovery.md)) becomes a live injector via the host-owned Node adapter — core performs no `import()`:
+
+```ts
+import { registerDiscoveredInstructionInjectors } from "@arnilo/prism/node/instruction-injectors";
+
+// markdown-only (no `module` field) → static every_turn injector reading resource text;
+// module-referenced → host-supplied moduleLoader (skipped when absent).
+// resourceTrust is only needed for absolute/outside resource files.
+await registerDiscoveredInstructionInjectors(registries, discovered, { moduleLoader, resourceTrust });
+```
+
+The CLI wires this under `--discover` (see below). Hosts embedding the SDK keep the registry empty and supply injectors directly on `AgentConfig`/`RunOptions`.
+
+### CLI and RPC
+
+CLI:
+
+```
+# select a discovered injector by name (repeatable)
+prism --discover --discover-kinds instructions --instruction json-always -p "Hi" --provider mock
+
+# load a markdown file as a static every_turn injector (repeatable)
+prism --injector-file ./rules/json.md -p "Hi" --provider mock
+
+# disable all injectors for a run (including AgentConfig injectors)
+prism --instruction false -p "Hi" --provider mock
+```
+
+`--instruction false` disables; `--instruction <name>` fails closed (exit 1) on an unknown name. Names resolve against discovered injectors only when `--discover` ran; without discovery, `--instruction` requires a name present in the session's `instructionInjectors` (host-supplied).
+
+RPC: `prompt`/`followUp` params accept an optional `instructionInjectors: readonly string[]` field. Names resolve against the `instructionInjectors` registry passed to `runRpcServer({ instructionInjectors })`; an unknown name fails closed with a correlated error response and no provider call.
+
+## Extension and configuration notes
+
+- Register via `ExtensionAPI.registerInstructionInjector(injector)` (Phase 30). Each injector is stored by `injector.name` (last-write-wins).
+- Select on `AgentConfig.instructionInjectors` or `RunOptions.instructionInjectors` (`RunOptions` wins). `RunOptions.instructionInjectors` is a list of `InstructionInjector` instances; hosts embed names by passing instances resolved through `resolveInstructionInjectors`.
+- Manifest `kind: "instructionInjector"` (Phase 30) declares contributions data-only; discovery of `kind: "instructions"` is the filesystem vehicle (see [Configuration and manifests](configuration-and-manifests.md)).
+- `turn` is plumbed through `LoopContext.assemble(nextInput, toolResults?, turn?)` (Phase 30) so injectors see the loop-local turn, not a stale value.
+
+## Security and performance notes
+
+- **No privilege grant:** `InstructionContribution` exposes only `instructions`/`contextBlocks`/`when`/`predicate`. There is no `tools`, `skills`, `permissions`, or `execute` field; a malformed contribution smuggling those fields contributes only `instructions`. Registering an injector adds entries only to `instructionInjectors`; `tools`/`skills`/`contextProviders`/`systemPromptContributions` stay empty.
+- **Cannot bypass validator or permissions:** injectors are layered into prompt assembly; tool dispatch still re-checks the active registry (`unknown_tool`), filters, arguments, the permission assertion, and `validate` (Phase 4/25/26).
+- **Secrets never enter history/events:** secrets in injector-produced `instructions`/`contextBlocks` are redacted in the outgoing `ProviderRequest` (via `redactProviderRequest`) and in emitted events (via `redactAgentEvent`). Do not put secrets in injector text at authoring time; the redactor is a backstop, not an invitation.
+- **Resource containment:** markdown-only discovered injectors resolve `resource` relative to their contribution directory and realpath-check it before read. Relative `..`, absolute paths, or symlinks that escape the contribution directory are rejected unless the host passes an explicit `resourceTrust` policy; `permission` is still checked before reading.
+- No hidden globals: injectors are resolved explicitly per run; nothing is auto-activated or auto-imported by core.
+
+## Related APIs
+
+- [Input and prompt assembly](input-and-prompt-assembly.md): default prompt builder and `assembleProviderInput`, where injector instructions/blocks are merged.
+- [System prompts](system-prompts.md): `composeSystemPrompt` and the `package`/`app`/`user`/`run` layering injectors layer into.
+- [Context and skills](context-and-skills.md): `resolveContextProviders` merge order and skill `context`.
+- [Contribution registries](contribution-registries.md): `instructionInjectors` registry.
+- [Contribution discovery](contribution-discovery.md): `.agents/instructions/<name>/` discovery and the host-owned `loadInstructionInjector` adapter.
+- [Extensions](extensions.md): `registerInstructionInjector` in the contribution-kinds list.
+- [CLI and RPC](cli-rpc.md): `--instruction`/`--injector-file` flags and the RPC `instructionInjectors` field.
+- [Credentials and redaction](credentials-and-redaction.md): `createSecretRedactor`, `redactProviderRequest`, `redactAgentEvent`.

package/docs/migration.md

@@ -0,0 +1,201 @@
+# Migration guide
+
+## What it does
+
+This page is the single navigation entry for the two cross-cutting migrations external apps hit when moving from Prism's development defaults to its production persistence and explicit-capability surfaces:
+
+1. **In-memory / JSONL → database-backed persistence** — swap the single-process development `SessionStore` for a host-implemented `ProductionPersistenceStore` / `SessionStore` adapter, and optionally attach a durable `RunLedger`.
+2. **Permissive capability defaults → explicit capability activation** — move from "omitted tool/skill lists activate everything in scope" (pre-Phase 38 behavior) to named, fail-closed tool/skill activation.
+
+It is a thin, link-first guide: it states before/after shapes and points at the detailed pages for schema, indexes, redaction, branch handles, capability semantics, and security.
+
+## When to use it
+
+Read this page when:
+
+- you are taking an app from the `createMemorySessionStore()` / `createJsonlSessionStore()` path to a multi-process, multi-tenant, or durable database backend;
+- you are hardening an agent that previously relied on "every scoped tool/skill is active" and need to name capabilities explicitly;
+- you are adopting the Phase 34–40 production surfaces (atomic append, branch handles, run/event/tool/usage ledger, security boundary hardening) for the first time.
+
+If you are new to Prism, start at [Session stores](session-stores.md) and [Agent/session runtime](agent-session-runtime.md) instead.
+
+## Inputs / request
+
+There is no runtime import for this page. The migrations below use these surfaces:
+
+| Surface | Where | Migration role |
+| --- | --- | --- |
+| `SessionStore` | `@arnilo/prism` | Runtime seam swapped from memory/JSONL to DB. |
+| `ProductionPersistenceStore` | `@arnilo/prism` | Adapter-facing contract for paginated, multi-tenant reads (`query*`, optional `readBranchPath`). |
+| `RunLedger` / `RunLedgerRecord` | `@arnilo/prism` | Durable run/event/tool-call/usage ledger attached via `AgentConfig.runLedger` / `RunOptions.runLedger`. |
+| `SessionAppendOptions` / `SessionAppendConflictError` / `SessionBranchHandle` | `@arnilo/prism` | Atomic append, retry dedup, durable branch handles. |
+| `AgentDefinition.tools` / `skills` | `@arnilo/prism` | Named, fail-closed capability activation (Phase 38). |
+| `activateAllCapabilities` | `@arnilo/prism` | Temporary all-tools/all-skills compatibility opt-in while migrating. |
+
+## Outputs / response / events
+
+These migrations are configuration swaps: they do not add `AgentEvent` variants or change runtime event order. The observable differences are:
+
+- reads come from a database instead of an in-memory map / JSONL file;
+- branches are addressable by a storable `(sessionId, leafId)` handle;
+- a run leaves durable `RunRecord` / `AgentEventRecord` / `ToolCallRecord` / `UsageRecord` rows;
+- an agent with omitted `tools`/`skills` activates **no** capabilities instead of every in-scope one.
+
+## Request/response example
+
+Persistence migration (before/after):
+
+```json
+// Before — development SessionStore, single process, no ledger.
+{
+  "store": "createMemorySessionStore() | createJsonlSessionStore(path)",
+  "runLedger": null,
+  "ownership": null
+}
+```
+
+```json
+// After — host-implemented database-backed adapter + durable ledger.
+{
+  "store": "createDbSessionStore({ pool })",
+  "runLedger": "createDbRunLedger({ pool })",
+  "ownership": { "tenantId": "t1", "accountId": "a1", "userId": "u1" }
+}
+```
+
+Capability migration (before/after):
+
+```json
+// Before (pre-Phase 38) — omitted tools/skills could receive every scoped capability.
+{ "name": "doc", "model": "openai/gpt-4o" }
+
+// After — explicit names; omitted means none.
+{ "name": "doc", "model": "openai/gpt-4o", "tools": ["read"], "skills": ["brief"] }
+```
+
+## Implementation example
+
+### Migration 1 — in-memory / JSONL → database-backed persistence
+
+A complete, network-free reference adapter that implements these contracts against in-memory tables (and wires a `RunLedger`, branch-handle checkout, fork, and prior-run timeline resume) lives at [`examples/external-app-db-backed.ts`](../examples/external-app-db-backed.ts). The steps below mirror its structure.
+
+Step 1: implement a `SessionStore` (or the richer `ProductionPersistenceStore`) against your database. The runtime only requires `append(entry, options?)`, `list(sessionId)`, and optional `get(id)` / `readBranchPath(query)`.
+
+```ts
+// Before: development store, single process.
+import { createJsonlSessionStore } from "@arnilo/prism/node/session-store-jsonl";
+const store = createJsonlSessionStore("./sessions.jsonl");
+
+// After: host-implemented database adapter implementing the documented contract, no real DB needed to satisfy the contract.
+import type { SessionStore, SessionEntry, SessionAppendOptions, PersistencePage, SessionBranchRead } from "@arnilo/prism";
+
+const store: SessionStore = {
+  async append(entry: SessionEntry, options?: SessionAppendOptions) {
+    // 1. idempotency dedup: insert (session_id, expected_parent_id, idempotency_key, entry_id)
+    //    into prism_session_append_idempotency; unique hit => SessionAppendConflictError { idempotencyDuplicate: true }
+    // 2. expectedParentId existence check => SessionAppendConflictError { expectedParentId } if missing
+    // 3. insert prism_session_entries row; duplicate id fails the transaction
+    // 4. optionally compare-and-swap prism_branches.leaf_entry_id
+  },
+  async list(sessionId: string) { /* O(n) development fallback only */ return []; },
+  async readBranchPath(query: SessionBranchRead): Promise<PersistencePage<SessionEntry>> {
+    // one recursive CTE / ancestor query — do NOT list(sessionId)+in-memory walk for long sessions
+    return { items: [] };
+  },
+};
+```
+
+Step 2: optionally attach a durable run/event/tool/usage ledger and ownership scope so a process exit leaves enough to resume and bill:
+
+```ts
+import { createAgent, type RunLedger } from "@arnilo/prism";
+
+const runLedger: RunLedger = {
+  // appendRun / appendEvent / appendToolCall / appendUsage — redact before storage, preserve per-run order
+  async appendRun(record) { /* insert prism_runs */ },
+  async appendEvent(record) { /* insert prism_agent_events with monotonic sequence per run_id */ },
+  async appendToolCall(record) { /* insert prism_tool_calls */ },
+  async appendUsage(record) { /* insert prism_usage */ },
+};
+
+const agent = createAgent({
+  model,
+  provider,
+  store,
+  runLedger,
+  ownership: { tenantId: "t1", accountId: "a1", userId: "u1" },
+});
+```
+
+Step 3: store branch handles `(sessionId, leafId)` in your app state and use checkout to move an existing session to a previous or sibling leaf. The runtime's branch helpers (`getSessionBranchEntries`, `rebuildSessionContext`) consume `readBranchPath` so large sessions never require a full `list(sessionId)` load.
+
+What you leave behind and why:
+
+- `createMemorySessionStore()` — process-local maps; lost on restart, no cross-process locking. Keep for tests.
+- `createJsonlSessionStore()` — single-process file adapter; reads are linear in file size, no cross-process lock, no durable idempotency table, two writers to the same file can race. Keep for local/dev only.
+
+See [Database persistence](database-persistence.md) for the full reference schema, indexes, conditional-append transaction pattern, retention, and NoSQL mapping; [Session stores](session-stores.md) for the `SessionStore` contract and branch helpers; [Session stores and branching](session-stores-and-branching.md) for branch semantics; [Runs and usage ledger](runs-and-usage.md) for the `RunLedger` record shapes and ordering rules.
+
+### Migration 2 — permissive capability defaults → explicit capability activation
+
+Pre-Phase 38 behavior could treat an omitted `tools` list as "every scoped tool"; some hosts also expected all scoped skills to be available. Phase 38 changes the safe default: omitted `tools` and omitted `skills` mean no active capabilities.
+
+```ts
+import { resolveAgentDefinition } from "@arnilo/prism";
+
+// Before: omitted tools could receive every scoped tool.
+resolveAgentDefinition({ name: "doc", model: "openai/gpt-4o" }, context);
+
+// After: list the capabilities this agent may use.
+resolveAgentDefinition(
+  { name: "doc", model: "openai/gpt-4o", tools: ["read"], skills: ["brief"] },
+  context,
+);
+```
+
+Temporary compatibility shim (use only while migrating old configs):
+
+```ts
+resolveAgentDefinition(
+  { name: "legacy", model: "openai/gpt-4o" },
+  { ...context, activateAllCapabilities: true },
+);
+```
+
+`activateAllCapabilities: true` intentionally scans/list-activates every in-scope tool/skill. New configs should list names and use strict contribution registries so a third-party package cannot silently shadow a capability name:
+
+```ts
+import { createContributionRegistries } from "@arnilo/prism";
+
+const registries = createContributionRegistries({ duplicate: "error" });
+```
+
+Runtime skill activation remains explicit: `RunOptions.activeSkills` narrows per run after an agent has a skill registry configured, and `Skill.toolNames` is enforced fail-closed before the first provider turn. See [Agent definitions](agent-definitions.md), [Context and skills](context-and-skills.md), and [Contribution registries](contribution-registries.md) for the full capability semantics.
+
+## Extension and configuration notes
+
+- **Persistence is host-owned.** Prism ships no database adapter, no DDL, no migration runner. Hosts own connection pools, transactions, cursor encoding, retention jobs, and tenant isolation. The runtime only talks to `SessionStore` (+ optional `readBranchPath`) and `RunLedger`.
+- **`RunLedger` is not a `SessionStore` replacement.** Messages, branches, and session entries still flow through `SessionStore.append()`; the ledger records run/event/tool/usage facts. See [Runs and usage ledger](runs-and-usage.md).
+- **Capability activation is config over code.** Every seam lives on `AgentDefinition` / `AgentDefinitionResolutionContext` / `RunOptions`; no auto-activation, no privilege grant. A declaration cannot grant permissions or bypass `toolNames`.
+- **Migration order is decoupled.** You can adopt database persistence without changing capability activation, and vice versa. Both migrations are independent config swaps.
+- **Strict duplicate mode for new registries.** `createContributionRegistries({ duplicate: "error" })` makes a third-party package fail loud instead of silently shadowing a capability name during migration.
+
+## Security and performance notes
+
+- **Never store provider credentials or secrets in the persistence contract.** `ProductionPersistenceStore`, `RunLedger`, `AgentEventRecord`, `ToolCallRecord`, `UsageRecord`, and `AgentDefinitionRecord` never require API keys, resolvers, or provider instances. Redact `SessionEntry` / event / tool-call / usage payloads before storage; the runtime redacts `AgentEvent`s via `redactAgentEvent` and ledger records via `redactRunLedgerRecord` before calling the adapter.
+- **JSONL is a development-only adapter.** No cross-process lock, no durable idempotency table, no tenant isolation, no retention enforcement, no migrations. Do not use it as a production multi-writer store.
+- **Avoid full-session scans in production.** Implement `readBranchPath(query)` with a recursive CTE / ancestor query and cursor-paginate `query*` from indexed columns. `list(sessionId)` + in-memory parent walk is the development fallback only.
+- **`activateAllCapabilities` widens blast radius.** It activates every in-scope tool/skill, so prefer named lists. Strict duplicate mode catches capability-name collisions early.
+- **`toolNames` enforcement is fail-closed.** A skill demanding an inactive tool throws at activation, before any provider turn — for both the old and new migration paths.
+
+## Related APIs
+
+- [Database persistence](database-persistence.md): production persistence contracts, reference schema, indexes, conditional append, retention, migrations, NoSQL mapping.
+- [Session stores](session-stores.md): `SessionStore` contract, `SessionAppendOptions`, `SessionAppendConflictError`, branch handles, `readBranchPath`.
+- [Session stores and branching](session-stores-and-branching.md): detailed branch semantics and helper reference.
+- [Runs and usage ledger](runs-and-usage.md): `RunLedger` record shapes, redaction, and event/usage ordering.
+- [Node JSONL session store](node-jsonl-session-store.md): development-only JSONL adapter and its limits.
+- [Agent definitions](agent-definitions.md): declarative `AgentDefinition`, `resolveAgentDefinition`, and the explicit-capability-activation migration.
+- [Context and skills](context-and-skills.md): `RunOptions.activeSkills`, `Skill.context`, `toolNames` enforcement.
+- [Contribution registries](contribution-registries.md): strict `duplicate: "error"` mode for capability shadowing prevention.
+- [Release and install](release-and-install.md): packaged surfaces and the offline test budget that gate these migrations.

package/docs/model-registry.md

@@ -0,0 +1,122 @@
+# Model registry
+
+## What it does
+
+The model registry stores explicit `ModelConfig` records by provider/model key. It keeps model metadata inert and host-owned: capabilities, limits, cost, cache support, provider compat data, parameters, and metadata are registered and resolved, not executed.
+
+Public API:
+
+- `createModelRegistry(models?, options?)`
+- `ModelRegistry.register(model)`
+- `ModelRegistry.get(provider, model)`
+- `ModelRegistry.resolve(provider, model)`
+- `ModelRegistry.list()`
+- `ModelConfig.cache?: ModelCacheCapabilities`
+
+## When to use it
+
+Use the model registry when a host or provider package needs to:
+
+- Fail closed when a provider/model is unknown.
+- Publish model metadata from a provider package.
+- Pick provider request behavior from generic metadata such as `ModelConfig.cache`.
+- Keep pricing, limits, and capabilities near the model id without global state.
+
+Do not use the registry for credential lookup, network model discovery, provider package discovery, or automatic SDK configuration.
+
+## Inputs / request
+
+```ts
+import { createModelRegistry, type ModelConfig } from "@arnilo/prism";
+```
+
+`ModelConfig` metadata fields:
+
+| Field | Purpose |
+| --- | --- |
+| `provider` / `model` | Required registry key. |
+| `displayName` | Human-readable label. |
+| `capabilities` | Input/output modes plus reasoning/tools/streaming booleans. |
+| `limits` | Context and output-token limits. |
+| `cost` | Input/output/cache read/cache write pricing. |
+| `cache` | Generic `ModelCacheCapabilities`. |
+| `compat` | Provider-owned inert JSON escape hatch. |
+| `parameters` | Host/provider default parameters. |
+| `metadata` | Host-owned inert metadata. |
+
+`ModelCacheCapabilities` fields:
+
+| Field | Purpose |
+| --- | --- |
+| `kind` | `implicit`, `openai_key`, `cache_control`, `provider_specific`, or `none`. |
+| `maxKeyLength` | Provider-safe cache key length. |
+| `maxBreakpoints` | Maximum cache-control anchors. |
+| `minCacheableTokens` | Minimum prompt size worth marking cacheable. |
+| `longRetention` | Whether long retention is supported. |
+
+## Outputs / response / events
+
+`createModelRegistry()` returns a `ModelRegistry`:
+
+| Method | Result |
+| --- | --- |
+| `register(model)` | Stores or replaces model. With `duplicate: "error"`, throws on duplicate key. |
+| `get(provider, model)` | Returns `ModelConfig | undefined`. |
+| `resolve(provider, model)` | Returns `ModelConfig` or throws `Unknown model: <provider>/<model>`. |
+| `list()` | Returns registered models in insertion order. |
+
+The registry emits no events and performs no I/O.
+
+## Request/response example
+
+```json
+{
+  "model": {
+    "provider": "demo",
+    "model": "demo-large",
+    "capabilities": { "input": ["text"], "tools": true, "streaming": true },
+    "limits": { "contextWindow": 128000, "maxOutputTokens": 8192 },
+    "cost": { "input": 10, "output": 30, "cacheRead": 2, "currency": "USD", "unit": "1M tokens" },
+    "cache": { "kind": "cache_control", "maxBreakpoints": 4, "longRetention": true }
+  }
+}
+```
+
+## Implementation example
+
+```ts
+import { createModelRegistry, type ModelConfig } from "@arnilo/prism";
+
+const model: ModelConfig = {
+  provider: "demo",
+  model: "demo-large",
+  displayName: "Demo Large",
+  capabilities: { input: ["text"], output: ["text"], tools: true, streaming: true },
+  limits: { contextWindow: 128_000, maxOutputTokens: 8_192 },
+  cost: { input: 10, output: 30, cacheRead: 2, cacheWrite: 12, currency: "USD", unit: "1M tokens" },
+  cache: { kind: "cache_control", maxBreakpoints: 4, minCacheableTokens: 1024, longRetention: true },
+};
+
+const registry = createModelRegistry([model], { duplicate: "error" });
+const resolved = registry.resolve("demo", "demo-large");
+```
+
+## Extension and configuration notes
+
+Provider packages register models through `ProviderPackageAPI.registerModel(model)`. The extension kernel stores those records in the host-owned registries. Static package metadata is allowed; dynamic model discovery remains provider/host code outside Prism core.
+
+`ModelConfig.compat` remains for provider-owned inert JSON. Prefer typed fields (`capabilities`, `limits`, `cost`, `cache`) for generic behavior shared across providers.
+
+## Security and performance notes
+
+- Model metadata must not contain credentials or secrets.
+- Registration is in-memory and O(1) by provider/model key.
+- `ModelConfig.cache` is declarative capability info only; it does not grant permissions, select tools, or bypass auth.
+- Provider-specific behavior belongs in provider packages, not Prism core.
+
+## Related APIs
+
+- [Provider layer](provider-layer.md): provider/model registry overview.
+- [Provider caching](provider-caching.md): `ModelCacheCapabilities` and cache helpers.
+- [Provider packages](provider-packages.md): package registration of model metadata.
+- [Public contracts](public-contracts.md): `ModelConfig`, `ModelCost`, and cache type contracts.

package/docs/node-jsonl-session-store.md

@@ -13,7 +13,7 @@ APIs:
 
 Use it in Node hosts that want a small durable `SessionStore` without adding a database.
 
-Do not use it for browser code, automatic discovery, shared multi-process locking, migrations, compaction, credentials, or app-specific tools.
+Do not use it for browser code, automatic discovery, shared multi-process locking, migrations, compaction, credentials, app-specific tools, or production multi-writer storage. Use a database-backed `SessionStore` adapter for multi-process or multi-writer durability.
 
 ## Inputs / request
 
@@ -32,12 +32,12 @@ import { createJsonlSessionStore } from "@arnilo/prism/node/session-store-jsonl"
 
 `createJsonlSessionStore()` returns a `SessionStore`:
 
-- `append(entry)` appends one JSON line and rejects duplicate entry ids.
+- `append(entry, options?)` appends one JSON line, rejects duplicate entry ids, honors `expectedParentId` existence checks, and deduplicates exact idempotency retries within this store instance.
 - `list(sessionId)` reads the file and returns valid entries for that session id. Corrupt or shape-invalid lines are skipped; they do not poison the whole file.
 - `get(id)` reads the file and returns the matching valid entry, if any.
 - `readJsonlSessionEntries(path)` returns `{ entries: SessionEntry[]; errors: SessionEntryParseError[] }` so hosts/tests can inspect per-line parse errors.
 
-Missing files read as empty stores. Invalid JSON, missing required fields, or wrong per-kind shapes (`message`, `summary`, `model_change`, `custom`, `compaction`, `label`, or non-string `parentId`) are quarantined per line with line number and reason; the raw line is included in `SessionEntryParseError.raw`.
+Missing files read as empty stores. Invalid JSON, missing required fields, unsupported `schemaVersion`, unknown `kind`, or wrong per-kind shapes (`message`, `summary`, `model_change`, `custom`, `compaction`, `label`, `event`, `metadata`, or non-string `parentId`) are quarantined per line with line number and reason; the raw line is included in `SessionEntryParseError.raw`. Unknown entry kinds and future schema versions fail closed: the line is skipped and never returned by `list()` or `get()`.
 
 ## Request/response example
 
@@ -65,6 +65,7 @@ Use `createMemorySessionStore()` for tests or throwaway sessions; use the JSONL
 - This adapter is an explicit Node subpath. Importing `@arnilo/prism` does not touch the filesystem.
 - Hosts choose the file path. Prism does not discover, watch, rotate, compact, or migrate files.
 - The adapter stores only `SessionEntry` data passed to `append()`.
+- `SessionAppendOptions` idempotency tracking is in memory for the store instance. It is a development guard, not a durable cross-process coordination mechanism.
 
 ## Security and performance notes
 
@@ -72,7 +73,7 @@ Use `createMemorySessionStore()` for tests or throwaway sessions; use the JSONL
 - Errors include path/reason or line number, not file contents.
 - Do not put secrets in messages, metadata, summaries, labels, or custom entries.
 - Reads are linear in file size. Appends are serialized per store instance.
-- There is no cross-process lock; add a database or external lock if multiple processes write the same file.
+- There is no cross-process lock or durable idempotency table; two processes writing the same file can race. Add a database or external lock if multiple processes write the same file.
 
 ## Related APIs