@arnilo/prism 0.0.1

package/docs/index.md

@@ -0,0 +1,56 @@
+# Prism Docs
+
+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.
+
+## Agent/session runtime
+- [Agent/session runtime](agent-session-runtime.md): create agents and sessions, run prompts, and subscribe to normalized session events.
+
+## Compaction/session memory
+- [Compaction and retry policies](compaction-and-retry.md): summarize branch history and retry transient provider failures with host-replaceable policies.
+- [LLM compaction package](compaction-llm.md): optional provider-backed compaction strategy package.
+- [Observational memory compaction package](compaction-observational-memory.md): optional source-backed memory, fast compaction, recall tool, and status/view command package.
+- [Session stores and branching](session-stores-and-branching.md): store session entries, rebuild branch context, and navigate branch leaves.
+- [Node JSONL session store](node-jsonl-session-store.md): persist session entries to caller-named JSONL files in Node hosts.
+
+## Provider and model connection
+- [Provider layer](provider-layer.md): register and resolve host-owned providers/models, create provider events, use generic provider request options, and test with the mock provider.
+- [Provider packages](provider-packages.md): define explicit provider packages, model metadata, auth descriptors, and request/cache policies without package discovery or provider-specific core behavior.
+  - Phase 12 package workspaces: [`@arnilo/prism-provider-openai`](providers/openai.md), [`@arnilo/prism-provider-opencode-go`](providers/opencode-go.md), [`@arnilo/prism-provider-openrouter`](providers/openrouter.md), [`@arnilo/prism-provider-zai`](providers/zai.md), and [`@arnilo/prism-provider-kimi`](providers/kimi.md).
+- [OpenAI-compatible provider](providers/openai-compatible.md): optional provider subpath using native or injected `fetch` for Chat Completions streaming.
+
+## Input, prompt, and context assembly
+- [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 and provider-input assembly.
+- [System prompts](system-prompts.md): compose explicit package/app/user/run system prompt layers without filesystem discovery or hidden globals.
+- [Context and skills](context-and-skills.md): resolve ordered context providers and keep context/skill selection host-owned.
+
+## Tools
+- [Tools](tools.md): register host-owned active tools, apply exact allow/deny filtering, and dispatch tool calls.
+
+## Extensions/plugins
+- [Contribution registries](contribution-registries.md): explicit host-owned registries for extension/package contributions without hidden globals.
+- [Extension kernel and event bus](extensions.md): load host-provided extensions in order, register contributions, emit lifecycle events, and isolate extension errors.
+- [Middleware hooks](middleware-hooks.md): ordered hook registry for provider, input, context, tool, retry, compaction, and session lifecycle boundaries.
+
+## Configuration/manifests
+- [Configuration and manifests](configuration-and-manifests.md): merge in-memory JSON config layers and validate data-only package manifests.
+- [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.
+
+## CLI/RPC
+- [CLI/RPC](cli-rpc.md): Run print/json modes and LF-delimited RPC over the public AgentSession runtime.
+
+## Security and credentials
+- [Security/auth/trust](settings-auth-trust-security.md): settings providers, credential helpers, trust/permission policies, and redaction controls.
+- [Credentials and redaction](credentials-and-redaction.md): compose explicit credential resolver order, use caller-supplied env objects/OAuth refresh helpers, and redact known secret values.
+
+## Testing and examples
+- [Provider layer](provider-layer.md): use `createMockProvider()` and provider event helpers for deterministic tests without timers, credentials, or network.
+- [Provider conformance](provider-conformance.md): run network-free provider adapter assertions from `@arnilo/prism/testing/provider-conformance`.
+- `examples/`: compile-checked typed examples and runnable mock demos (SDK basics, provider registration, auth, tools, stores/branching, compaction, observational-memory recall, CLI, RPC).
+
+## 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.
+

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

@@ -0,0 +1,168 @@
+# Input and prompt assembly
+
+## What it does
+
+`createDefaultInputBuilder()` turns common host input into Prism `Message[]` without starting an agent loop or calling a provider. It accepts strings, `Message`, or `Message[]`, and can add host-supplied instructions, history, summaries, attachments, explicit text resources, tool results, metadata, and optional `input_assembly` middleware.
+
+`createDefaultPromptBuilder()` composes messages, context blocks, selected skills, and host-supplied active tools into provider-ready messages. `assembleProviderInput()` wires input assembly, ordered context resolution, prompt middleware, and prompt composition into a `ProviderRequest` without calling a provider. Layered system prompts are composed before this helper and passed as `systemInstructions`. `renderPromptTemplate()` expands tiny `{{name}}` variables for CLI/RPC prompt strings before input assembly.
+
+## When to use it
+
+Use it when a host wants the boring default shape before a later prompt builder or provider request step. Use `renderPromptTemplate()` when CLI/RPC callers need simple variable replacement before sending a string to the input builder. Use a custom `InputBuilder` or `PromptBuilder` when an app has its own message or prompt policy.
+
+Do not use it for tool execution, provider calls, file discovery, credential lookup, package activation, template logic, or an agent/session runtime.
+
+## Inputs / request
+
+```ts
+import { createDefaultInputBuilder } from "@arnilo/prism";
+
+const messages = await createDefaultInputBuilder().build("Summarize", {
+  systemInstructions: "Be accurate.",
+  developerInstructions: "Cite supplied context only.",
+  history,
+  attachments: [{ name: "notes.md", text: "# Notes" }],
+  toolResults: [{ toolCallId: "call_1", name: "lookup", value: { ok: true } }],
+  metadata: { requestId: "r1" },
+});
+```
+
+Prompt templates:
+
+```ts
+import { renderPromptTemplate } from "@arnilo/prism";
+
+const prompt = renderPromptTemplate("Review {{file}} for {{focus}}", {
+  file: "src/index.ts",
+  focus: "public exports",
+});
+```
+
+Prompt/provider assembly:
+
+```ts
+import { assembleProviderInput, createDefaultPromptBuilder } from "@arnilo/prism";
+
+const request = await assembleProviderInput({
+  model: { provider: "mock", model: "demo" },
+  input: "Explain this file",
+  contextProviders: [projectContext],
+  promptBuilder: createDefaultPromptBuilder(),
+  tools: activeTools,
+});
+```
+
+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.
+- `InputAttachment`: already-loaded text/content 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.
+- `PromptTemplateOptions`: missing-variable behavior for `renderPromptTemplate()`.
+
+## Outputs / response / events
+
+The builder returns `readonly Message[]`.
+
+- String input becomes one user text message.
+- `Message` and `Message[]` input are preserved.
+- 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.
+- 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" }`.
+
+## Request/response example
+
+```json
+{
+  "template": "Review {{file}} for {{focus}}",
+  "variables": { "file": "src/index.ts", "focus": "public exports" },
+  "rendered": "Review src/index.ts for public exports"
+}
+```
+
+```json
+{
+  "input": "Hello",
+  "context": {
+    "systemInstructions": "Answer briefly.",
+    "attachments": [{ "name": "notes.md", "text": "Remember the release date." }]
+  }
+}
+```
+
+```json
+[
+  { "role": "system", "content": [{ "type": "text", "text": "System instruction:\nAnswer briefly." }] },
+  { "role": "user", "content": [{ "type": "text", "text": "Hello" }] },
+  { "role": "user", "content": [{ "type": "text", "text": "Attachment notes.md:\nRemember the release date." }] }
+]
+```
+
+## Implementation example
+
+```ts
+import { createDefaultInputBuilder, createMiddlewareRegistry, renderPromptTemplate } from "@arnilo/prism";
+
+const middleware = createMiddlewareRegistry();
+middleware.use("input_assembly", (messages) => messages);
+
+const prompt = renderPromptTemplate("Review {{resource}}", { resource: "package://demo/prompt.md" });
+const messages = await createDefaultInputBuilder().build(prompt, {
+  resourceUris: ["package://demo/prompt.md"],
+  resourceLoader: {
+    async load(uri) {
+      return { uri, text: "Host-loaded resource text." };
+    },
+  },
+  middleware,
+});
+```
+
+## 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.
+
+```ts
+const kernel = createExtensionKernel();
+await kernel.load([extension]);
+
+const request = await assembleProviderInput({
+  model: { provider: "mock", model: "demo" },
+  input: "Hello",
+  inputBuilder: kernel.registries.inputBuilders.resolve("custom-input"),
+  promptBuilder: kernel.registries.promptBuilders.resolve("custom-prompt"),
+  contextProviders: [kernel.registries.contextProviders.resolve("project")],
+  middleware: kernel.middleware,
+});
+```
+
+`input_assembly`, `context`, and `prompt_build` middleware are not global. They run only for helper calls that receive a `MiddlewareRegistry`, in that assembly order. `assembleProviderInput()` keeps provider `tools` equal to the host-supplied active tool list after prompt middleware.
+
+## Security and performance notes
+
+- The builder is linear in supplied messages, attachments, resources, and tool results.
+- 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`.
+- 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.
+
+## Related APIs
+
+- [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.
+- [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.
+- [Agent/session runtime](agent-session-runtime.md): calls assembly each turn and supplies runtime tool results to the next provider request.
+- [Tools](tools.md): host-owned tool registry and tool result boundary.
+- [Compaction and retry policies](compaction-and-retry.md): default compaction strategy that feeds summaries into input assembly.

package/docs/middleware-hooks.md

@@ -0,0 +1,123 @@
+# Middleware hooks
+
+## What it does
+
+Middleware hooks are ordered, host-owned functions that transform a payload only when a host/runtime explicitly calls `run()`. They are a primitive for provider, input, tool, compaction, retry, and session runtime phases.
+
+APIs:
+
+- `createMiddlewareRegistry()` / `MiddlewareRegistry`
+- `MiddlewareHookName`, `Middleware<T>`, and `MiddlewareNext<T>`
+- `ExtensionAPI.use()` for extension registration
+
+## When to use it
+
+Use middleware hooks when a host wants extension/package code to observe or transform a value at a named runtime boundary.
+
+Do not use middleware hooks as a provider adapter, prompt builder, retry policy, compaction strategy, tool dispatcher, permission system, or agent/session runtime.
+
+## Inputs / request
+
+```ts
+createMiddlewareRegistry(options?: MiddlewareRegistryOptions): MiddlewareRegistry
+```
+
+Built-in hook names:
+
+- `provider_request`
+- `input_assembly`
+- `prompt_build`
+- `context`
+- `tool_call`
+- `tool_result`
+- `retry`
+- `compaction`
+- `session_start`
+- `session_shutdown`
+
+`MiddlewareRegistry` methods:
+
+| Method | Input | Result |
+| --- | --- | --- |
+| `use(hook, middleware)` | hook name and middleware | Registers middleware in order and returns an unsubscribe function. |
+| `run(hook, value)` | hook name and payload | Runs registered middleware and returns the final payload. |
+| `list(hook)` | hook name | Returns registered middleware for inspection. |
+
+`Middleware<T>` receives `(value, next)` and returns a value or promise. Calling `next(updatedValue)` passes an updated value to later middleware.
+
+## Outputs / response / events
+
+`run()` returns the transformed value. If no middleware is registered for a hook, `run()` returns the original value. `assembleProviderInput()` calls Phase 5 hooks in this order when middleware is supplied: `input_assembly`, then `context`, then `prompt_build`. The agent/session runtime applies configured provider request policies, then invokes `provider_request` once with the `ProviderRequest` before `AIProvider.generate()`, invokes `tool_call` and `tool_result` through `dispatchToolCall()` for complete provider tool calls, invokes `compaction` with `{ context, result }` after a compaction strategy returns and before the runtime appends its standard compaction entry, and invokes `retry` with `{ context, decision }` before scheduling a provider-turn retry. There is no `provider_response` hook; observing provider output belongs to the provider adapter or subscriber events.
+
+With default `errorPolicy: "event"`, middleware errors become `extension_error` events when `onError` is provided, and later middleware still runs with the current value. With `errorPolicy: "throw"`, `run()` rejects on the first middleware error.
+
+## Request/response example
+
+```json
+{
+  "hook": "provider_request",
+  "before": { "metadata": {} },
+  "after": { "metadata": { "source": "demo" } }
+}
+```
+
+## Implementation example
+
+```ts
+import { createMiddlewareRegistry } from "@arnilo/prism";
+
+const middleware = createMiddlewareRegistry();
+
+middleware.use("provider_request", async (request, next) => {
+  return next({
+    ...request,
+    metadata: { ...request.metadata, source: "demo" },
+  });
+});
+
+const request = await middleware.run("provider_request", { metadata: {} });
+console.log(request.metadata.source);
+```
+
+Extensions can register middleware through the runtime API:
+
+```ts
+import type { Extension } from "@arnilo/prism";
+
+export const extension: Extension = {
+  name: "demo-middleware",
+  setup(api) {
+    api.use("session_start", (event) => event);
+  },
+};
+```
+
+## Extension and configuration notes
+
+- Middleware registration is explicit through `createMiddlewareRegistry()` or `ExtensionAPI.use()`.
+- `provider_request` middleware sees generic `ProviderRequest.options` after request policies have run; do not add secrets unless a redactor/policy secret list covers that boundary.
+- Middleware runs only when the host/runtime calls `run()` or passes the registry to a helper that documents a call site.
+- `compaction` middleware may adjust the compaction result summary/data, but runtime still owns session store append ordering and branch parent ids.
+- `retry` middleware may stop retrying or adjust delay, but runtime still owns retry event emission, abort-aware waiting, and provider-turn boundaries.
+- The registry does not discover packages, read manifests, load config, call providers, execute tools, read resources, or start sessions.
+- Hosts may pass a middleware registry into `createExtensionKernel({ middleware })` to share it with direct host code.
+
+## Security and performance notes
+
+- Middleware is in-memory, ordered, dependency-free, and synchronous-or-async.
+- Default error handling can emit redacted `extension_error` events through the extension kernel.
+- Do not put resolved credential values, tokens, headers, secret settings, or permission grants into middleware payloads unless the host boundary explicitly allows it.
+- Tool dispatch re-checks registry lookup, active allow/deny filters, and object arguments after `tool_call` middleware, so middleware cannot bypass host tool permissions by changing a tool name. `assembleProviderInput()` also keeps provider `tools` equal to the host-supplied active tool list after `prompt_build` middleware.
+
+## Related APIs
+
+- [Extension kernel and event bus](extensions.md): `ExtensionAPI.use()` and shared error policy.
+- [Contribution registries](contribution-registries.md): direct contribution registration separate from middleware.
+- [Agent/session runtime](agent-session-runtime.md): provider request policy/middleware timing, bounded tool loop call site for `tool_call`/`tool_result` hooks, and runtime call sites for `compaction` and `retry`.
+- [Tools](tools.md): tool dispatch behavior that runs `tool_call` and `tool_result` hooks.
+- [Input and prompt assembly](input-and-prompt-assembly.md): `input_assembly` and `prompt_build` helper call sites.
+- [Compaction and retry policies](compaction-and-retry.md): compaction/retry middleware payloads and runtime timing.
+- [Context and skills](context-and-skills.md): `context` helper call site.
+- [Public contracts](public-contracts.md): provider, tool, context, session, and extension contracts that runtimes can pass through hooks.
+
+Permission checks for tools, extensions, and resources are hard guards; middleware can transform payloads but cannot bypass a denied `PermissionPolicy`.

package/docs/node-filesystem-config.md

@@ -0,0 +1,85 @@
+# Node filesystem config loader
+
+## What it does
+
+The optional `@arnilo/prism/node/config` subpath reads JSON config files that a Node host explicitly names. It also computes the conventional user config path, such as `~/.config/prism/config.json`.
+
+APIs:
+
+- `defaultUserConfigPath()`
+- `readConfigFile()`
+- `loadConfigFiles()`
+- `NodeConfigFile`
+
+## When to use it
+
+Use this subpath in Node CLI/host code that wants filesystem config layers for `mergeConfigLayers()`.
+
+Do not use it from core root imports, browsers, package manifests, agent/session runtime startup, extension setup by default, or any path where filesystem access must stay unavailable.
+
+## Inputs / request
+
+```ts
+import { defaultUserConfigPath, loadConfigFiles, readConfigFile } from "@arnilo/prism/node/config";
+```
+
+`NodeConfigFile`:
+
+| Field | Type | Purpose |
+| --- | --- | --- |
+| `name` | `string` | Config layer name. |
+| `path` | `string` | Explicit JSON file path to read. |
+| `optional` | `boolean` | Skip missing files when true. |
+
+## Outputs / response / events
+
+- `defaultUserConfigPath(appName = "prism")` returns a path ending in `.config/<appName>/config.json` under the current user's home directory.
+- `readConfigFile(path)` returns a JSON object or rejects for read errors, invalid JSON, or non-object JSON.
+- `loadConfigFiles(files)` returns `ConfigLayer[]` in caller-provided order.
+- No events are emitted and no config is merged automatically.
+
+## Request/response example
+
+```json
+{
+  "files": [
+    { "name": "user", "path": "/home/demo/.config/prism/config.json", "optional": true }
+  ]
+}
+```
+
+## Implementation example
+
+```ts
+import { mergeConfigLayers } from "@arnilo/prism";
+import { defaultUserConfigPath, loadConfigFiles } from "@arnilo/prism/node/config";
+
+const layers = await loadConfigFiles([
+  { name: "user", path: defaultUserConfigPath(), optional: true },
+  { name: "runtime", path: "./prism.config.json" },
+]);
+
+const config = mergeConfigLayers(layers);
+console.log(config);
+```
+
+## Extension and configuration notes
+
+- This loader is an explicit Node subpath. Importing `@arnilo/prism` does not read files or compute config layers.
+- Hosts choose which paths to read and which missing files are optional.
+- The loader returns `ConfigLayer[]`; use `mergeConfigLayers()` from the root package to combine layers.
+- It does not discover packages, scan directories, watch files, import extension modules, load manifests, or start agent/session runtime behavior.
+
+## Security and performance notes
+
+- Only caller-provided files are read.
+- Invalid JSON and non-object JSON fail closed.
+- Errors include the path and reason, not file contents.
+- Config files must not contain resolved credential values, tokens, headers, or executable code.
+- The loader uses Node built-ins and has no polling, watchers, network calls, or dependencies.
+
+## Related APIs
+
+- [Configuration and manifests](configuration-and-manifests.md): in-memory config layers and merge behavior.
+- [Credentials and redaction](credentials-and-redaction.md): keep credentials out of config files.
+- [Extension kernel and event bus](extensions.md): extension loading remains separate from filesystem config loading.

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

@@ -0,0 +1,81 @@
+# Node JSONL session store
+
+## What it does
+
+The optional `@arnilo/prism/node/session-store-jsonl` subpath stores `SessionEntry` records in a caller-named JSONL file: one JSON object per line.
+
+APIs:
+
+- `createJsonlSessionStore(pathOrOptions)`
+- `JsonlSessionStoreOptions`
+
+## When to use it
+
+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.
+
+## Inputs / request
+
+```ts
+import { createJsonlSessionStore } from "@arnilo/prism/node/session-store-jsonl";
+```
+
+`pathOrOptions` can be a string path or:
+
+| Field | Type | Purpose |
+| --- | --- | --- |
+| `path` | `string` | Explicit JSONL file path to read/write. |
+| `createDirectory` | `boolean` | Create parent directories before append. Defaults to `true`. |
+
+## Outputs / response / events
+
+`createJsonlSessionStore()` returns a `SessionStore`:
+
+- `append(entry)` appends one JSON line and rejects duplicate entry ids.
+- `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`.
+
+## Request/response example
+
+```json
+{
+  "path": "./sessions.jsonl",
+  "createDirectory": true
+}
+```
+
+## Implementation example
+
+```ts
+import { createJsonlSessionStore, readJsonlSessionEntries } from "@arnilo/prism/node/session-store-jsonl";
+
+const store = createJsonlSessionStore("./sessions.jsonl");
+const { entries, errors } = await readJsonlSessionEntries("./sessions.jsonl");
+if (errors.length) console.warn("quarantined lines", errors);
+```
+
+Use `createMemorySessionStore()` for tests or throwaway sessions; use the JSONL store when entries should survive a process restart.
+
+## Extension and configuration notes
+
+- 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()`.
+
+## Security and performance notes
+
+- Reads and writes use only the caller-provided path.
+- 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.
+
+## Related APIs
+
+- [Session stores and branching](session-stores-and-branching.md): `SessionStore`, entries, branch helpers, and runtime branch semantics.
+- [Agent/session runtime](agent-session-runtime.md): sessions that append user, assistant, tool-result, and model-change entries.
+- [Node filesystem config loader](node-filesystem-config.md): similar explicit Node subpath pattern.

package/docs/provider-conformance.md

@@ -0,0 +1,109 @@
+# Provider conformance
+
+## What it does
+
+Provider conformance helpers are dependency-free assertions for provider package tests. They exercise normalized Prism `AIProvider` streams without live network or credentials.
+
+Exported from `@arnilo/prism/testing/provider-conformance`:
+
+- `collectProviderEvents(provider, request)`
+- `assertProviderStreamConforms(options)`
+- `assertAbortIsObserved(options)`
+- `assertToolCallDeltasReconstruct(events, expected)`
+- `assertUsageAccounting(events, expected)`
+- `assertSerializedRequestCoversContent(request, body, options?)`
+- `assertNoSecretLeak(events, secrets)`
+
+## When to use it
+
+Use these helpers in provider package tests to check event order, terminal events, abort propagation, streamed tool-call deltas, usage/cache accounting, request body content preservation, and secret redaction.
+
+Do not use them as a live integration runner, provider simulator, retry framework, credential loader, or test framework replacement.
+
+## Inputs / request
+
+```ts
+import { assertProviderStreamConforms } from "@arnilo/prism/testing/provider-conformance";
+
+await assertProviderStreamConforms({
+  provider,
+  request: {
+    model: { provider: "demo", model: "demo-model" },
+    messages: [{ role: "user", content: [{ type: "text", text: "Hi" }] }],
+  },
+  expect: { text: "Hello", usage: { cacheReadTokens: 10 } },
+});
+```
+
+Helpers accept normal `AIProvider`, `ProviderRequest`, `ProviderEvent`, `Usage`, and request body objects. They throw `Error` on failed assertions so any runner can use them.
+
+## Outputs / response / events
+
+- `collectProviderEvents()` returns provider events in stream order.
+- `assertProviderStreamConforms()` returns collected events after verifying the stream ends with `done` or `error`, terminal events are last, and optional text/usage expectations match.
+- `assertAbortIsObserved()` passes an already-aborted signal and expects provider generation to reject.
+- `assertToolCallDeltasReconstruct()` rebuilds streamed `tool_call_delta` fragments into tool calls and validates expected id/name/arguments.
+- `assertUsageAccounting()` finds `usage` or `done.usage` and checks selected token fields including `cacheReadTokens` and `cacheWriteTokens`.
+- `assertSerializedRequestCoversContent()` scans a serialized provider request body for primitive canaries from each Prism content block and fails if any supported block type is silently dropped.
+- `assertNoSecretLeak()` stringifies all collected events and fails if any known secret string is present.
+
+## Request/response example
+
+```json
+{
+  "events": ["content_delta", "usage", "done"],
+  "usage": { "inputTokens": 10, "cacheReadTokens": 4, "cacheWriteTokens": 2 }
+}
+```
+
+Content-preservation example:
+
+```ts
+import { assertSerializedRequestCoversContent } from "@arnilo/prism/testing/provider-conformance";
+
+const request = {
+  model: { provider: "demo", model: "demo-model" },
+  messages: [{
+    role: "user",
+    content: [
+      { type: "text", text: "Hello" },
+      { type: "image", url: "https://example.invalid/img.png" },
+      { type: "tool_result", toolCallId: "call_1", name: "lookup", result: { id: "42" } },
+    ],
+  }],
+};
+
+const body = JSON.parse(String(fetchInit.body));
+assertSerializedRequestCoversContent(request, body, { unsupported: ["image"] });
+```
+
+## Implementation example
+
+```ts
+import { createMockProvider, providerDone, providerTextDelta } from "@arnilo/prism";
+import { assertProviderStreamConforms } from "@arnilo/prism/testing/provider-conformance";
+
+await assertProviderStreamConforms({
+  provider: createMockProvider([providerTextDelta("Hello"), providerDone()]),
+  request: { model: { provider: "mock", model: "demo" }, messages: [] },
+  expect: { text: "Hello" },
+});
+```
+
+## Extension and configuration notes
+
+The helpers are a testing subpath only. Provider packages can use them with their own mocked fetch/transport or `createMockProvider()`. Live provider tests should stay opt-in and env-gated outside Prism's default test suite.
+
+## Security and performance notes
+
+- No credentials, env vars, OAuth tokens, filesystem discovery, provider SDKs, or network calls are required.
+- Use fake credentials only in fixtures.
+- The helpers collect one stream into memory; keep conformance fixtures small.
+- Redaction remains the provider/runtime boundary's job. Use `assertNoSecretLeak()` with known fake secrets to catch regressions, not as a general secret scanner.
+
+## Related APIs
+
+- [Provider layer](provider-layer.md): `AIProvider`, provider events, and mock provider.
+- [Provider packages](provider-packages.md): package authors can use conformance helpers for adapters.
+- [OpenAI-compatible provider](providers/openai-compatible.md): optional provider adapter tested with mocked streams.
+- [Public contracts](public-contracts.md): provider request/event/usage contracts.