@arnilo/prism 0.0.1 → 0.0.3

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
 

package/docs/performance.md

@@ -0,0 +1,127 @@
+# Performance limits
+
+## What it does
+
+This page states Prism runtime limits that keep slow consumers and long sessions from becoming unbounded memory or latency problems.
+
+Current surfaces:
+
+- `SubscribeOptions` for bounded live `AgentEvent` subscriber queues.
+- `SessionStore.readBranchPath(query)` for branch reads that avoid full-session scans.
+- `ProductionPersistenceStore` cursor queries for entries, events, runs, tool calls, and usage.
+- JSONL and memory stores documented as development/local adapters, not production multi-writer stores.
+
+## When to use it
+
+Use these limits when embedding Prism in a UI, API server, job worker, or multi-tenant app that may have slow event consumers or long-lived sessions.
+
+Do not treat Prism's live event subscribers as a durable queue. Use `RunLedger` / database persistence for replay, audit, billing, and timelines.
+
+## Inputs / request
+
+```ts
+import { createAgent, type SubscribeOptions } from "@arnilo/prism";
+
+const options: SubscribeOptions = {
+  maxQueuedEvents: 256,
+  overflow: "close",
+};
+
+const events = session.subscribe(options);
+```
+
+`SubscribeOptions` fields:
+
+| Field | Default | Purpose |
+| --- | --- | --- |
+| `maxQueuedEvents` | `1024` | Maximum events queued for one subscriber while it is not awaiting `next()`. Values below `1` are clamped to `1`. |
+| `overflow` | `"close"` | Overflow policy: `"close"`, `"drop_oldest"`, or `"drop_newest"`. |
+
+## Outputs / response / events
+
+On default overflow, the affected subscriber receives one `event_subscriber_overflow` event and then finishes:
+
+```json
+{
+  "type": "event_subscriber_overflow",
+  "sessionId": "session_1",
+  "droppedEvents": 257,
+  "maxQueuedEvents": 256,
+  "overflow": "close"
+}
+```
+
+`drop_oldest` keeps the newest queued events. `drop_newest` ignores incoming events while the queue is full. These policies are live-view policies only; they do not affect `RunLedger` writes or stored session entries.
+
+## Request/response example
+
+```json
+{
+  "subscribe": { "maxQueuedEvents": 256, "overflow": "close" },
+  "store": "database-backed SessionStore with readBranchPath",
+  "eventLedger": "cursor-paginated by runId and sequence"
+}
+```
+
+## Implementation example
+
+```ts
+import { createAgent, createMockProvider, providerDone, providerTextDelta } from "@arnilo/prism";
+
+const agent = createAgent({
+  model: { provider: "mock", model: "demo" },
+  provider: createMockProvider([providerTextDelta("Hello"), providerDone()]),
+});
+
+const session = agent.createSession();
+const reader = (async () => {
+  for await (const event of session.subscribe({ maxQueuedEvents: 256, overflow: "close" })) {
+    if (event.type === "event_subscriber_overflow") break;
+    render(event);
+  }
+})();
+
+await session.run("Hi");
+await reader;
+
+function render(_event: unknown) {}
+```
+
+For production branch reads, implement `SessionStore.readBranchPath` instead of loading every entry:
+
+```ts
+const store = {
+  async append(entry, options) { /* transaction + parent/idempotency checks */ },
+  async list(sessionId) { /* development fallback only */ return []; },
+  async readBranchPath(query) {
+    // Use one ancestor query / recursive CTE and return a cursor page.
+    return { items: [], nextCursor: undefined };
+  },
+};
+```
+
+## Extension and configuration notes
+
+- `SubscribeOptions` is per subscriber. One slow UI can be closed or dropped without affecting other subscribers, the active run, ledger writes, or session storage.
+- `RunLedger` remains the durable event/timeline surface. Hosts may batch inside their ledger adapter, but Prism awaits ledger writes at safe boundaries; preserve per-run event order before acknowledging a batch.
+- Database-backed stores should implement `readBranchPath` and cursor-paginated `ProductionPersistenceStore` queries. Memory and JSONL stores intentionally use full-session/file reads.
+- Cursor pagination should use indexed keys, not offsets: `(run_id, sequence)` for events, `(session_id, started_at, id)` for runs, `(run_id, recorded_at, id)` for usage, and `(session_id, timestamp, id)` for entries.
+- Hosts own queue sizes, page-size caps, database indexes, connection pools, transaction timeouts, retention jobs, partitioning, and multi-process coordination.
+
+## Security and performance notes
+
+- Overflow events contain only counts and policy, never message text, tool arguments, prompts, provider payloads, or credentials.
+- Runtime event payloads can be large (`Message`, content deltas, tool results, summaries, artifact metadata). Size queues by events and keep payload size in mind.
+- Live subscriber queues are bounded by default. Durable replay belongs to host storage.
+- `SessionStore.list(sessionId)` is a full-session read. It is fine for memory/JSONL development stores, but production adapters should use `readBranchPath` for provider context and branch views.
+- The JSONL store rereads/parses the file for validation/list/get and serializes appends only within one process. It has no cross-process lock, pagination, migrations, tenant isolation, or retention.
+- Recommended database indexes: session id, run id, parent id, branch leaf id, timestamps, tenant/account/user, event type, entry kind, `(run_id, sequence)` for event timelines, and `(run_id, recorded_at, id)` for usage. Allocate event `sequence` per run for stable timeline pagination.
+
+## Related APIs
+
+- [Agent events](agent-events.md): `SubscribeOptions` and `event_subscriber_overflow` event details.
+- [Agent/session runtime](agent-session-runtime.md): `session.subscribe()` and runtime event flow.
+- [Session stores](session-stores.md): `SessionStore.readBranchPath` and dev-vs-production branch reads.
+- [Database persistence](database-persistence.md): cursor queries, reference schema, indexes, and event sequence guidance.
+- [Runs and usage ledger](runs-and-usage.md): durable event, tool-call, and usage persistence.
+- [Node JSONL session store](node-jsonl-session-store.md): development-only JSONL limits.