@arnilo/prism 0.3.2 → 0.5.0

package/docs/server.md

@@ -2,7 +2,7 @@
 
 ## What it does
 
-`@arnilo/prism-server` exposes explicitly selected agents and workflows through one framework-free `(Request) => Promise<Response>` handler. It supports direct agent results, bounded agent/workflow SSE, cross-replica durable agent-event reconnect, opt-in durable agent status/resume, durable workflow start/enqueue/status/cancel/resume/replay, ownership-scoped schedules, host authorization, ownership propagation, redaction, resource ceilings, and optional deployment seams (health/readiness, drain, host rate-limit adapter, ownership-scoped event replay, worker/coordinator lease election).
+`@arnilo/prism-core/runtime/server` exposes explicitly selected agents and workflows through one framework-free `(Request) => Promise<Response>` handler. It supports direct agent results, bounded agent/workflow SSE, cross-replica durable agent-event reconnect, opt-in durable agent status/resume, durable workflow start/enqueue/status/cancel/resume/replay, ownership-scoped schedules, host authorization, ownership propagation, redaction, resource ceilings, and optional deployment seams (health/readiness, drain, host rate-limit adapter, ownership-scoped event replay, worker/coordinator lease election).
 
 No listener starts on import. Empty `agents`/`workflows` maps expose nothing. Authentication, authorization, route selection, durable stores, TLS, distributed rate limiting, queues, and framework/serverless adaptation remain host-owned.
 
@@ -82,7 +82,7 @@ Errors use `{ "error": { "code", "message" } }`. Unknown routes/capabilities are
 
 ```ts
 import { createAgent, createMockProvider, providerDone, providerTextDelta } from "@arnilo/prism";
-import { createPrismHandler } from "@arnilo/prism-server";
+import { createPrismHandler } from "@arnilo/prism-core/runtime/server";
 
 const agent = createAgent({
   model: { provider: "mock", model: "offline" },
@@ -128,6 +128,95 @@ Default/hard ceilings:
 | drain admit cutoff | 30 s | 5 min |
 | replay page / cursor | 100 / 4 KiB | 500 / 16 KiB |
 
+## Outbound webhooks
+
+### What it does
+
+`createWebhookNotifier()` posts selected terminal agent/workflow events to host-registered HTTPS endpoints. Every JSON envelope is redacted before HMAC-SHA-256 signing; `X-Prism-Signature` is `sha256=<hex>` and `X-Prism-Timestamp` carries the signed envelope timestamp.
+
+### When to use it
+
+Use it for host-owned PagerDuty, Slack, or application hooks after a run completes, fails, or suspends. Omit targets when no outbound notification is wanted: no target means no queued delivery or network activity.
+
+### Inputs / request
+
+| Field | Meaning |
+| --- | --- |
+| `targets` | Host-configured `{ url, events }` entries. URLs must be public HTTPS, without credentials/fragments; private and metadata literals fail during registration. |
+| `allowLoopbackHttp` | Explicit opt-in permitting `http:` for loopback hostnames (development receivers only); never combined with private or metadata targets. Default false. |
+| `signer.key` | Host-held `Uint8Array` HMAC key, at least 32 bytes. |
+| `redactor` | Required `SecretRedactor`; its result is placed in `redactedPayload` before signing. |
+| `limits.maxQueuedEvents` | Global outbound queue cap; default 128, hard cap 4,096. Overflow drops newest and increments `diagnostics().dropped`. |
+| `limits.timeoutMs` / `maxEventBytes` | Per-attempt timeout (5 s default, 30 s hard) and JSON envelope byte cap (64 KiB default, 1 MiB hard). |
+| `limits.retries` / `retryBaseDelayMs` / `retryMaxDelayMs` / `retryJitter` | Retries after the first attempt (3 default, 10 hard); exponential 100 ms→5 s delays (30 s hard), with ±25% jitter by default. Set jitter to `0` only for deterministic tests. |
+| `limits.maxFailureRecords` | Redacted terminal failure-record ring buffer; 32 default, 256 hard. |
+
+`notify()` accepts `run.completed`, `run.failed`, `run.suspended`, `workflow.completed`, `workflow.failed`, or `workflow.suspended`. `onAgentEvent()` and `onWorkflowEvent()` translate Prism lifecycle events into those names.
+
+### Outputs / response / events
+
+`notify()` returns immediately after bounded enqueue. Pass `{ signal }` as its second argument to cancel queued or retrying delivery for that run. `diagnostics()` returns `{ queued, delivered, failed, dropped, retries, cancelled, failures, lastError? }`: `failed` is the `prism.webhook.failed` terminal-failure counter, `failures` is bounded and redacted, and `lastError` is its latest redacted error.
+
+A `2xx` delivery succeeds. `4xx` is terminal except `429`; `429`, `5xx`, and transport failures retry within the configured cap. `Retry-After` is honored within `retryMaxDelayMs`. Delivery is at-least-once: receiver timeouts after processing can yield duplicates.
+
+```json
+{
+  "id": "01d2...",
+  "event": "run.failed",
+  "runId": "run-42",
+  "status": "failed",
+  "redactedPayload": { "error": "[REDACTED]" },
+  "timestamp": "2026-01-01T00:00:00.000Z"
+}
+```
+
+### Request/response example
+
+Receivers verify the raw request body, not a parsed/re-serialized object:
+
+```ts
+const expected = createHmac("sha256", hostHmacKey).update(rawBody).digest("hex");
+const valid = request.headers.get("x-prism-signature") === `sha256=${expected}`;
+```
+
+### Implementation example
+
+```ts
+import { createSecretRedactor, type AgentSession } from "@arnilo/prism";
+import { createWebhookNotifier } from "@arnilo/prism-core/runtime/server";
+
+const notifier = createWebhookNotifier({
+  targets: [{ url: "https://ops.example.test/prism", events: ["run.failed", "workflow.suspended"] }],
+  signer: { key: Buffer.from(process.env.PRISM_WEBHOOK_HMAC!, "hex") },
+  redactor: createSecretRedactor([process.env.PRISM_WEBHOOK_HMAC]),
+});
+
+export function wireWebhookAgentSession(session: AgentSession): AgentSession {
+  void (async () => {
+    for await (const event of session.subscribe()) notifier.onAgentEvent(event);
+  })();
+  return session;
+}
+
+export const webhookWorkflowRunOptions = { onEvent: notifier.onWorkflowEvent };
+```
+
+The agent `sessionFactory` is the server-handler adapter. Workflow `onEvent` receives the same events emitted through its event bus, including `workflow_finished` and `workflow_suspended`.
+
+### Extension and configuration notes
+
+Targets are static host configuration, never request JSON, tool output, or extension discovery. Event filters are exact. The notifier is a server-package export; it neither starts a listener nor owns a durable queue, auth provider, or webhook receiver.
+
+### Security and performance notes
+
+Delivery uses core `pinnedFetch` only: every attempt DNS-pins a public address and rejects all redirects, including redirects toward private targets. The HMAC key, signature, and delivery errors are never logged by the notifier; bounded failure records redact error text before retention. HTTPS is mandatory; plaintext HTTP is allowed only with explicit `allowLoopbackHttp: true` and a loopback hostname, and still pins/validates DNS. Queue overflow deliberately drops newest deliveries so earlier accepted lifecycle events retain order; use `diagnostics()` to observe loss. The in-memory queue does not survive restart; a durable outbox is required when cross-restart delivery matters. The outbound-webhook threat leg lives in `npm run security:threat-suites` (`scripts/phase46-webhooks-security.test.mjs` plus the package and pinned-fetch fixtures).
+
+### Related APIs
+
+- [Multimodal content](multimodal-content.md): shared DNS-pinned outbound fetch primitive.
+- [Workflows](workflows.md): workflow event-bus and `onEvent` lifecycle seam.
+- [Host security guide](host-security.md): remote-boundary controls.
+
 ## Deployment seams (optional)
 
 Compose beside `createPrismHandler` — Prism starts no listener, container orchestrator, or queue worker.
@@ -139,7 +228,7 @@ Compose beside `createPrismHandler` — Prism starts no listener, container orch
 | `rateLimit` on handler | Host adapter after authorize, before session create. Return denial `{ retryAfterMs, code, message }` → `429` + optional `Retry-After`. `createMemoryRateLimiter` is single-process only. |
 | `createPrismAgentEventReplay` | Shared `AgentEventSource` page/follow semantics for exact-owned runs. |
 | `createPrismEventReplay` / `createPrismReplayHandler` | Compatible ownership-scoped legacy `queryEvents` pages (`redacted: true`). Does not re-run work. Unauthorized replay denies. |
-| `createPrismDeploymentLease` | Lease election under `prism.server.deployment`. Coordinator replica holds `key: "coordinator"` before schedule ticks; workers run `@arnilo/prism-workflows` `createWorkflowCoordinator` for queued runs (fencing tokens). |
+| `createPrismDeploymentLease` | Lease election under `prism.server.deployment`. Coordinator replica holds `key: "coordinator"` before schedule ticks; workers run `@arnilo/prism-core/runtime/workflows` `createWorkflowCoordinator` for queued runs (fencing tokens). |
 | `createConversationService` / `createConversationHandler` | Durable user-scoped conversation threads (create/list/continue/branch/archive/export/delete) over session + event-ledger seams, with thread-bound reconnectable replay. Mounts beside the handler; see [Conversations](conversations.md). |
 | `createArtifactService` / `createArtifactHandler` | Durable artifact co-work review (attach/revise/compare/approve/reject/last-validated/delivery-link + authorized download) over the versioned checkpoint store; records persist metadata/revisions/approvals only, never file bodies. Mounts beside the handler; see [Work artifacts and review](work-artifacts-and-review.md). |
 
@@ -158,11 +247,11 @@ Network-free demo: [`examples/server-deployment-seams.ts`](../examples/server-de
 - Health endpoints reveal process/liveness only by default; detail flags require host authorize and must omit secrets/tenant dumps.
 - Drain and event replay require the same ownership/authorize boundary as other routes; replay never invokes providers or tools. Durable event routes exist only on object `PrismAgentExposure` entries with both `events` and `resolveRun`; every reconnect authorizes again, resolves public run ID to exact internal session/run IDs, and opens the shared source without `sessionFactory`.
 - SSE uses bounded upstream subscriber queues. Consumer cancellation aborts owned work by default and releases concurrency; set `disconnectAborts: false` only when the host deliberately owns background completion.
-- Source inputs/resource URLs remain host responsibilities and use existing resource/media SSRF policies. Server package does not fetch URLs.
+- Source inputs/resource URLs remain host responsibilities and use existing resource/media SSRF policies. Apart from explicitly configured `WebhookNotifier` targets, server package features do not fetch URLs.
 - Schedule routes never accept ownership from JSON. Services carry mandatory ownership and explicit workflow/calculator registries; route authorization cannot broaden either. Replay applies workflow ownership/hash/approval checks.
 - Agent status/resume routes exist only for keys in `agentRuns`. Supply one core `createAgentRunLifecycle({ checkpoints, resolveAgent })` capability per selected agent; its resolver returns current `{ agent, definitionRevision }`. It reuses core checkpoint parsing/CAS/fingerprint checks, returns only public state/version, and needs a durable `SessionStore` as well as checkpoints for restart-safe resume. Empty/default configuration adds no agent lifecycle route, polling, or server cache.
 
-A2A routes are not added to `createPrismHandler()`. Install `@arnilo/prism-supervisor` and explicitly mount `createA2AHandler()` when protocol interoperability is required; this keeps cards and remote invoke absent from ordinary Prism servers.
+A2A routes are not added to `createPrismHandler()`. Install `@arnilo/prism-core/runtime/supervisor` and explicitly mount `createA2AHandler()` when protocol interoperability is required; this keeps cards and remote invoke absent from ordinary Prism servers.
 
 ## Related APIs
 

package/docs/settings-auth-trust-security.md

@@ -34,11 +34,13 @@ console.log(await settings.get("demo.enabled"));
 ## Implementation example
 ```ts
 import { createAgent, createMemoryCredentialStore, createSecretRedactor, resolveCredentialValue } from "@arnilo/prism";
-import { loadSettingsFiles, defaultUserSettingsPath } from "@arnilo/prism/node/settings";
+import { loadSettingsFiles } from "@arnilo/prism/node/settings";
 import { createPathTrustPolicy } from "@arnilo/prism/node/trust";
+import { homedir } from "node:os";
+import { join } from "node:path";
 
 const settings = await loadSettingsFiles([
-  { name: "user", path: defaultUserSettingsPath(), optional: true },
+  { name: "user", path: join(homedir(), ".config", "prism", "settings.json"), optional: true },
 ]);
 const credentials = createMemoryCredentialStore();
 credentials.set({ name: "api", provider: "demo", credential: { type: "api_key", value: "token-value" } });
@@ -57,7 +59,7 @@ void agent;
 ```
 
 ## Extension and configuration notes
-Root imports stay filesystem-free. Node settings files are caller-named and read once; optional missing files are skipped. Trust storage, prompts, approval UI, OAuth token storage, environment-variable selection, and persistent credentials belong in the host or an extension package. For Node.js hosts, [`@arnilo/prism-credentials-node`](credential-storage.md) provides encrypted-file and system-keychain backends. Pass concrete settings values or credential resolvers to the provider/request edge that needs them; do not place them on `AgentConfig`.
+Root imports stay filesystem-free. Node settings files are caller-named and read once; optional missing files are skipped. Trust storage, prompts, approval UI, OAuth token storage, environment-variable selection, and persistent credentials belong in the host or an extension package. For Node.js hosts, [`@arnilo/prism-core/credentials/node`](credential-storage.md) provides encrypted-file and system-keychain backends. Pass concrete settings values or credential resolvers to the provider/request edge that needs them; do not place them on `AgentConfig`.
 
 ## Security and performance notes
 Prism does not sandbox host tools or extensions. Prism does not read environment variables, keychains, user config files, package manifests, resources, settings providers, credential resolvers, or project-local extensions unless the host explicitly wires those operations. Redaction is exact known-secret replacement only; it is not secret detection. Permission and trust checks are one operation per guarded call and add no workers, watchers, retries, network, or filesystem scans.
@@ -81,8 +83,8 @@ Boundary hardening summary:
 - `createMemoryCredentialStore`, `createChainedCredentialResolver`, `createExplicitCredentialResolver`, `createEnvCredentialResolver`, `refreshOAuthCredential`, `resolveCredentialValue`
 - `createStaticTrustPolicy`, `assertTrusted`, `isTrusted`, `TrustDeniedError`
 - `createStaticPermissionPolicy`, `assertPermission`, `checkPermission`, `PermissionDeniedError`
-- `ExecutionPolicy`, `assertExecutionAllowed`, `checkExecution`, `ExecutionDeniedError` (core); `@arnilo/prism-coding-security` for coding-tool approval adapters — see [Coding execution approval and sandboxing](coding-security.md)
+- `ExecutionPolicy`, `assertExecutionAllowed`, `checkExecution`, `ExecutionDeniedError` (core); `@arnilo/prism-coding-tools/security` for coding-tool approval adapters — see [Coding execution approval and sandboxing](coding-security.md)
 - `createSecretRedactor`, `redactMessage`, `redactAgentEvent`, `redactSessionEntry`, `redactProviderRequest`
-- `@arnilo/prism/node/settings`: `defaultUserSettingsPath`, `readSettingsFile`, `loadSettingsFiles`
+- `@arnilo/prism/node/settings`: `readSettingsFile`, `loadSettingsFiles` (`defaultUserSettingsPath` was removed in 0.5.0 — build the path with `node:os`/`node:path`)
 - `@arnilo/prism/node/trust`: `createPathTrustPolicy`, `isPathInside`, `isPathInsideReal`
 - [Contribution discovery (workspace)](contribution-discovery.md): `createPathTrustPolicy` + `isPathInsideReal` gate workspace contribution roots fail-closed.

package/docs/sheets.md

@@ -0,0 +1,229 @@
+# Spreadsheets, CSV parsing, and typed schema inference (`@arnilo/prism-office/sheets`)
+
+## What it does
+
+The `@arnilo/prism-office/sheets` package provides fail-closed, high-fidelity spreadsheet (XLSX) and delimiter-separated (CSV/TSV/PSV) data ingestion with automatic dialect sniffing, typed column schema inference, and **strict financial decimal safety**.
+
+### Headline Guarantee: Strict Financial Decimal Safety
+
+> [!IMPORTANT]
+> **Zero Float Coercion on Decimal Paths**:
+> In financial and enterprise data processing, floating-point rounding errors (IEEE-754 `double`) silently distort monetary totals, balance ledgers, and transaction reconciliations.
+>
+> In `@arnilo/prism-office/sheets`:
+> - Money-like and decimal values are **never converted to JavaScript numbers (`Number()`, `parseFloat()`, or unary `+`)**.
+> - All decimal and currency values are parsed, normalized, and emitted as exact canonical decimal strings: `{ type: "decimal", value: "1234.56" }`.
+> - Currency markers (`$`, `€`, `£`, `¥`, `₹`, `CHF`, `USD`, `EUR`, etc.) and accounting parentheses `($1,234.56)` are normalized safely into canonical strings (`"-1234.56"`).
+> - Ambiguous numbers (e.g. scientific notation `1.23e5` or inconsistent locale separators) are preserved as raw strings with `flags: ["numeric-ambiguous"]` rather than guessed.
+> - An automated source-scan test in the regression suite enforces that no floating-point conversions exist on decimal paths across the codebase.
+
+### Core Capabilities
+
+- **Pure In-Memory Operation**: Accepts `Uint8Array` binary archives or `string | Uint8Array` CSV text. Zero filesystem access, zero network I/O, zero `process.env` lookups, and zero background worker threads.
+- **Fail-Closed Container Gating**: XLSX archives must begin with the standard ZIP container magic signature (`PK\x03\x04`). CSV inputs support UTF-8 (with automatic BOM stripping); UTF-16 encoded buffers are refused fail-closed with `ERR_PRISM_SHEETS_UNSUPPORTED_FORMAT`.
+- **Automatic CSV Dialect Sniffing**: Analyzes the first 4 KiB / 50 lines to detect candidate delimiters (`,`, `;`, `\t`, `|`) using variance-based scoring outside quoted regions, correctly distinguishing delimiters from commas within quoted addresses or company names.
+- **RFC 4180 State Machine**: Handles embedded newlines in quoted fields, doubled-quote escaping (`""`), and CRLF / LF line endings in a single, non-backtracking linear pass (<60 ms for 1 MB CSVs).
+- **Read-Only Formula Preservation**: OpenXML formula cells are extracted as `{ type: "formula", formula: "=SUM(A1:A10)", cachedValue: "100" }` and are **never evaluated or executed**.
+- **Bounded Sampling Window + Full Validation**: Infers column types across an initial window (default 500 rows) and validates all subsequent records against the inferred schema, reporting structured `type-mismatch` warnings without silent coercion.
+- **Privacy-Guaranteed Telemetry Seam**: Optional, dependency-free `SheetsTelemetry` hook emits `sheets.parse` spans carrying byte, row, column, and duration metrics with zero cell text or confidential payload leakage.
+
+## When to use it
+
+Use `@arnilo/prism-office/sheets` when autonomous agents, data pipelines, or enterprise workflows need to:
+1. Ingest untrusted customer XLSX or CSV files with strict, unbypassable byte, row, column, and sheet caps.
+2. Parse tabular financial records, invoices, ledgers, or pricing sheets with mathematical decimal precision guarantees.
+3. Automatically determine CSV delimiters, quotes, and headers without manual dialect configuration.
+4. Extract structural column schemas (`name`, `type`, `nullRate`, `sample`, `flags`) for automated data cataloging, SQL generation, or tool routing.
+
+Do **not** use this package for interactive spreadsheet calculation/formula engines, macro execution, chart generation, or real-time collaborative editing.
+
+## Inputs / request
+
+### Primary Parsing Functions
+
+| Function | Signature | Description |
+| --- | --- | --- |
+| `parseWorkbook` | `(bytes: Uint8Array, options?: ParseWorkbookOptions) => Promise<WorkbookParse>` | Parses an XLSX workbook binary buffer, enforces caps and ZIP signature gating, extracts raw cells, resolves shared strings and styles, and infers schemas per worksheet. |
+| `parseCsv` | `(input: string \| Uint8Array, options?: ParseCsvOptions) => Promise<CsvParse>` | Parses CSV/TSV/PSV input with automatic dialect sniffing, BOM stripping, RFC 4180 state machine processing, and schema inference. |
+| `inferAndTransformRows` | `(rows: readonly (readonly CellValue[])[], caps: ResolvedSheetsCaps) => InferAndTransformResult` | Pure function that infers column types over a sampling window and validates full rows against the inferred schema. |
+
+### Decimal & Normalization Utilities
+
+| Function | Signature | Description |
+| --- | --- | --- |
+| `normalizeDecimal` | `(input: string) => NormalizedDecimalResult \| null` | Normalizes currency strings, accounting negatives, and thousands separators into canonical decimal strings (`^-?\d+(\.\d+)?$`). Returns `null` if ambiguous or invalid. |
+| `isCanonicalDecimal` | `(str: string) => boolean` | Checks if a string is already in canonical decimal format (e.g. `"1234.56"`, `"-0.05"`, `"42"`). |
+| `isCurrencyString` | `(str: string) => boolean` | Checks if a string contains explicit currency symbols or currency codes (`$`, `€`, `USD`, etc.). |
+| `isScientificNotation` | `(str: string) => boolean` | Checks if a string represents scientific notation (e.g. `"1.23e5"`, `"4.56E-3"`). |
+
+### Cap Validation Utilities
+
+| Function | Signature | Description |
+| --- | --- | --- |
+| `resolveSheetsCaps` | `(caps?: SheetsCaps) => ResolvedSheetsCaps` | Resolves user-configured limits against safe defaults and hard ceilings. |
+| `validateByteCap` | `(byteLength: number, caps: ResolvedSheetsCaps) => void` | Validates input size against `caps.maxBytes`, throwing `SheetsCapError` if exceeded. |
+| `validateZipSignature` | `(bytes: Uint8Array) => void` | Validates standard PKZIP magic bytes (`0x50, 0x4b, 0x03, 0x04`), throwing `SheetsFormatError` if missing. |
+
+### Capacity Limits and Defaults
+
+Limits are verified upfront and enforced progressively to prevent memory exhaustion and denial-of-service from adversarial inputs:
+
+| Cap | Default | Hard Ceiling | Description |
+| --- | --- | --- | --- |
+| `maxBytes` | 32 MiB (`33,554,432`) | 512 MiB (`536,870,912`) | Maximum input buffer or string byte length. |
+| `maxSheets` | 100 | 1,000 | Maximum worksheets in a workbook archive. |
+| `maxRows` | 100,000 | 1,000,000 | Maximum rows per worksheet or CSV document. |
+| `maxColumns` | 1,000 | 16,384 | Maximum columns per worksheet or CSV document. |
+| `inferenceWindowRows` | 500 | 5,000 | Number of rows sampled for column schema inference. |
+| `maxWarnings` | 100 | 1,000 | Maximum validation and dialect warnings recorded. |
+
+## Outputs / response / events
+
+### Error Hierarchy
+
+All error classes inherit from `SheetsError` and carry structured error codes:
+
+| Error Class | Code | Cause / Trigger |
+| --- | --- | --- |
+| `SheetsCapError` | `ERR_PRISM_SHEETS_CAP` | Input size, sheet count, row count, or column count exceeds configured caps. |
+| `SheetsValidationError` | `ERR_PRISM_SHEETS_VALIDATION` | Invalid cap configuration (e.g. non-integer or exceeding hard ceiling). |
+| `SheetsFormatError` | `ERR_PRISM_SHEETS_UNSUPPORTED_FORMAT` | Missing ZIP container signature on XLSX input or unsupported encoding (UTF-16) on CSV input. |
+| `SheetsParseError` | `ERR_PRISM_SHEETS_PARSE_FAILED` | Corrupt archive structure or malformed XML parts. |
+
+### Schema & Warnings Output Shape
+
+```ts
+export interface ColumnSchema {
+  readonly name: string;
+  readonly type: "string" | "integer" | "number" | "decimal" | "date" | "datetime" | "boolean";
+  readonly nullRate: number;
+  readonly sample?: string;
+  readonly flags?: readonly ("numeric-ambiguous" | "mixed-types")[];
+}
+
+export interface InferenceWarning {
+  readonly row: number;
+  readonly column: number;
+  readonly columnName?: string;
+  readonly expectedType: string;
+  readonly actualValue: string;
+  readonly message: string;
+}
+```
+
+## Request/response example
+
+### Input CSV
+
+```csv
+transaction_id,item_description,total_amount,unit_price,refund_fee
+TXN-1001,"Software Consulting","$1,234.56",1234.56,"($ 50.00)"
+TXN-1002,"Cloud Server Hosting","€ 450.00",450.00,"-$ 10.00"
+TXN-1003,"Hardware Device","£ 2,500.00",2500.00,"$ 0.00"
+```
+
+### Parsed Output (`CsvParse`)
+
+```json
+{
+  "dialect": {
+    "delimiter": ",",
+    "quote": "\"",
+    "hasHeader": true
+  },
+  "schema": [
+    { "name": "transaction_id", "type": "string", "nullRate": 0, "sample": "TXN-1001", "flags": [] },
+    { "name": "item_description", "type": "string", "nullRate": 0, "sample": "Software Consulting", "flags": [] },
+    { "name": "total_amount", "type": "decimal", "nullRate": 0, "sample": "$1,234.56", "flags": [] },
+    { "name": "unit_price", "type": "decimal", "nullRate": 0, "sample": "1234.56", "flags": [] },
+    { "name": "refund_fee", "type": "decimal", "nullRate": 0, "sample": "($ 50.00)", "flags": [] }
+  ],
+  "rows": [
+    ["transaction_id", "item_description", "total_amount", "unit_price", "refund_fee"],
+    ["TXN-1001", "Software Consulting", { "type": "decimal", "value": "1234.56" }, { "type": "decimal", "value": "1234.56" }, { "type": "decimal", "value": "-50.00" }],
+    ["TXN-1002", "Cloud Server Hosting", { "type": "decimal", "value": "450.00" }, { "type": "decimal", "value": "450.00" }, { "type": "decimal", "value": "-10.00" }],
+    ["TXN-1003", "Hardware Device", { "type": "decimal", "value": "2500.00" }, { "type": "decimal", "value": "2500.00" }, { "type": "decimal", "value": "0.00" }]
+  ],
+  "warnings": []
+}
+```
+
+## Implementation example
+
+```ts
+import { parseWorkbook, parseCsv, type SheetsTelemetry } from "@arnilo/prism-office/sheets";
+
+// 1. Parse XLSX workbook with custom caps
+const xlsxBytes = new Uint8Array([...]); // Untrusted file bytes
+const workbook = await parseWorkbook(xlsxBytes, {
+  caps: {
+    maxRows: 50_000,
+    maxColumns: 500,
+    maxBytes: 16 * 1024 * 1024,
+  },
+});
+
+for (const sheet of workbook.sheets) {
+  console.log(`Sheet: ${sheet.name} (${sheet.rows.length} rows)`);
+  for (const col of sheet.schema) {
+    console.log(`  Column [${col.name}] inferred as ${col.type} (nullRate: ${col.nullRate})`);
+  }
+}
+
+// 2. Parse CSV with automatic dialect sniffing and telemetry
+const csvText = `id;name;revenue\n1;"Acme, Corp";1000000.00\n2;"Global, Inc";500000.50\n`;
+
+const telemetry: SheetsTelemetry = {
+  startSpan(name, attributes) {
+    console.log(`Span started: ${name}`, attributes);
+    return {
+      setAttribute() {},
+      addEvent() {},
+      recordError() {},
+      end() {},
+    };
+  },
+};
+
+const csvResult = await parseCsv(csvText, { telemetry });
+console.log(`Detected delimiter: "${csvResult.dialect.delimiter}"`);
+console.log(`Revenue value:`, csvResult.rows[1][2]);
+// Output: { type: "decimal", value: "1000000.00" }
+```
+
+## Extension and configuration notes
+
+### Sub-package Pinning
+To avoid pulling in CLI frameworks or extraneous dependencies, `@arnilo/prism-office/sheets` directly pins the exact underlying modular packages:
+- `@office-open/xlsx@0.12.3`
+- `@office-open/xml@0.12.3`
+
+### Custom Telemetry Hook
+The `SheetsTelemetry` seam allows optional OpenTelemetry instrumentation without adding runtime telemetry dependencies:
+```ts
+const telemetry: SheetsTelemetry = {
+  startSpan(name, attributes) {
+    // Maps to tracer.startSpan with allow-listed metadata (bytes, rows, columns, sheetCount)
+    // Cell contents and user data are NEVER passed to telemetry spans.
+    return activeSpan;
+  },
+};
+```
+
+### Self-Hosting & Operational Notes
+- **Zero Network & Storage Dependencies**: `@arnilo/prism-office/sheets` does not write files or contact network services. Host engines own persistence, storage buckets, and lake datasets.
+- **Fail-Closed Container Gating**: Malicious or non-standard files are rejected before allocation or XML decompression occurs.
+
+## Security and performance notes
+
+- **Pure In-Memory Operation**: No temporary files, no shell execution, no binary spawning, and zero network sockets.
+- **ZIP Signature Gating**: Buffers must begin with standard PKZIP container signatures (`0x50, 0x4B, 0x03, 0x04`). Extension-based type inference is strictly prohibited.
+- **Fail-Closed Caps**: Input size and element count caps are evaluated before entering XML translation passes, preventing zip-bomb and decompression amplification attacks.
+- **Strict Anti-Corruption Invariant**: Zero floating-point conversions on decimal paths guarantee exact financial calculations and ledger balances.
+- **Performance Budget**: Warm parsing of 1 MB CSV files completes in under 60 ms; workbook parsing completes in under 100 ms.
+
+## Related APIs
+
+- [`@arnilo/prism-office/documents`](./documents.md): Specification-compliant OpenXML document generation, parsing, patching, and preview rendering for DOCX, XLSX, and PPTX.
+- [`@arnilo/prism-coding-tools/document-reader`](./document-reader.md): Bounded literal text extraction from PDF and DOCX documents for coding agent tools.
+- [`@arnilo/prism-core/governance/observability`](./observability.md): OpenTelemetry instrumentation and trace adapters.

package/docs/speech.md

@@ -0,0 +1,126 @@
+# Speech synthesis and transcription
+
+## What it does
+
+`SpeechProvider` is the provider-neutral speech contract: text→audio via
+`synthesize` (full bytes) and `synthesizeStream` (first chunk as soon as the
+provider responds). `TranscriptionProvider` is audio→text via `transcribe`
+(one-shot) and `transcribeStream` (partial `TranscriptDelta` events, then one
+`done`), sharing the Realtime `transcript_delta` event naming. Adapters ship in
+[`@arnilo/prism-providers/openai`](providers/openai.md) (`/v1/audio/speech`,
+`/v1/audio/transcriptions`); offline conformance runs via `runSpeechConformance`
+and `runTranscriptionConformance` from `@arnilo/prism/testing/provider-conformance`.
+
+## When to use it
+
+Use it for one-shot voice output and batch/stream transcription where the host
+owns playback, capture, and audio storage. Do not use it for interactive
+bidirectional voice — that is the Realtime session contract
+([`RealtimeSession`](public-contracts.md)), which keeps its own
+`audio_delta`/`transcript_delta` events. Streaming here is one-directional:
+synthesis streams audio out, transcription streams text in.
+
+## Inputs / request
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `model` | `string` | Speech model (`tts-1`, `gpt-4o-mini-tts`) or transcription model (`whisper-1`, `gpt-4o-transcribe`). |
+| `input` | `string` (speech) | Text to speak; non-empty, within the provider input cap (OpenAI: 4,096 chars). |
+| `audio` | `Uint8Array` (transcription) | Audio bytes; non-empty, within the provider cap (OpenAI: 25 MiB). |
+| `voice` / `format` / `speed` | `string?` / `string?` / `number?` (speech) | Voice id, audio container (`mp3`, `wav`, `opus`), playback speed. Adapter defaults when omitted. |
+| `format` / `language` / `prompt` | `string?` | Audio container hint (maps to the upload filename), ISO-639-1 hint, spelling hint. |
+| `signal` | `AbortSignal?` | Cancellation; observed by the adapter transport. |
+
+Adapter options: `apiKey` (`CredentialValueSource` — the existing credential
+seam, resolved per call and redacted from errors), `baseUrl`, `fetch` (inject a
+fake transport for offline tests), `headers`, provider defaults
+(`voice`/`format`), and `maxAudioBytes` (response ceiling for synthesis,
+input ceiling for transcription).
+
+## Outputs / response / events
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `audio` | `Uint8Array` / `ReadableStream<Uint8Array>` | Full synthesized bytes, or chunks in order — the first chunk is available as soon as the provider responds. |
+| `format` | `string` | Actual audio container (request value or provider default). |
+| `text` | `string` | Transcript; `TranscriptDone.text` is the final full text. |
+| `usage` | `Usage?` | Transcription token usage (streaming `done` reports it; one-shot when the provider includes it). |
+
+Streaming transcription yields `TranscriptDelta` (`{ type: "transcript_delta",
+text }`, naming aligned with `RealtimeEvent.transcript_delta` — no `role`) then
+exactly one `TranscriptDone`.
+
+Failures throw `SpeechError` / `TranscriptionError` with a stable `code`:
+`empty_input` (no text / no audio), `input_too_large` (speech text over the
+provider cap), `audio_too_large` (transcription audio over the cap),
+`request_failed` (non-2xx or stream error, secret-redacted message),
+`response_malformed` (missing text, over-ceiling audio bytes),
+`unsupported_model` (via `assertSpeechSupported` / `assertTranscriptionSupported`
+when the host checks `ModelCapabilities.speech` / `transcription`).
+
+## Request/response example
+
+```json
+{ "model": "tts-1", "input": "hello", "voice": "alloy", "response_format": "mp3" }
+```
+
+## Implementation example
+
+```ts
+import { createOpenAISpeechProvider, createOpenAITranscriptionProvider } from "@arnilo/prism-providers/openai";
+import { runSpeechConformance, runTranscriptionConformance } from "@arnilo/prism/testing/provider-conformance";
+
+const speech = createOpenAISpeechProvider({ apiKey: process.env.OPENAI_API_KEY });
+const { audio } = await speech.synthesize({ model: "tts-1", input: "hi", voice: "alloy" });
+const streamed = await speech.synthesizeStream({ model: "tts-1", input: "hi" });
+// streamed.audio is a ReadableStream<Uint8Array>; first chunk resolves at first response bytes
+
+const transcription = createOpenAITranscriptionProvider({ apiKey: process.env.OPENAI_API_KEY });
+const { text } = await transcription.transcribe({ model: "whisper-1", audio, format: "mp3" });
+for await (const event of transcription.transcribeStream({ model: "whisper-1", audio })) {
+  if (event.type === "transcript_delta") process.stdout.write(event.text);
+}
+
+// Offline conformance (fake transport, no network):
+await runSpeechConformance({
+  provider: createOpenAISpeechProvider({ apiKey: "sk-test", fetch: fakeFetch }),
+  model: "tts-1",
+  maxInputChars: 4096,
+  sample: { input: "hi", voice: "alloy" },
+});
+```
+
+## Extension and configuration notes
+
+- Implement `SpeechProvider` / `TranscriptionProvider` for other vendors; the
+  contracts are structural — no base class, no registry.
+- Models declare support with `capabilities.speech` / `capabilities.transcription`;
+  hosts gate with the `modelSupports*` / `assert*Supported` guards, mirroring the
+  structured-output and embeddings guard pattern.
+- `synthesizeStream` returns a Web `ReadableStream` and `transcribeStream` an
+  `AsyncIterable` — the repo's streaming conventions; no Node-only stream types.
+- Adapters never truncate: over-cap inputs and responses reject with typed
+  errors, so callers own splitting long text or large audio.
+
+## Security and performance notes
+
+- API keys resolve through the existing `CredentialValueSource` seam and are
+  redacted from every thrown error (`redactSecrets`); no new secret paths.
+- Synthesized audio is consumed under a byte ceiling
+  (`DEFAULT_SPEECH_MAX_AUDIO_BYTES`, 25 MiB; `maxAudioBytes` override) — the
+  stream errors instead of buffering without bound; transcription input is
+  capped before any network I/O.
+- Audio content and transcript text are never logged; error messages carry
+  status and a redacted body only.
+- One HTTP request per call; streaming paths forward provider chunks as they
+  arrive (first byte at provider RTT, no full-response buffering).
+
+## Related APIs
+
+- [Realtime sessions](public-contracts.md): `RealtimeSession` for interactive
+  bidirectional voice; `RealtimeEvent.transcript_delta` is this contract's
+  naming anchor.
+- [Provider conformance](provider-conformance.md): `runSpeechConformance` /
+  `runTranscriptionConformance` and the offline conformance matrix.
+- [Provider packages](provider-packages.md): subpath import rules for
+  `@arnilo/prism-providers/openai`.

package/docs/sqlite-persistence.md

@@ -2,7 +2,7 @@
 
 ## What it does
 
-The optional `@arnilo/prism-session-store-sqlite` package ships a production-oriented SQLite adapter that implements:
+The optional `@arnilo/prism-core/sessions/sqlite` package ships a production-oriented SQLite adapter that implements:
 
 - `SessionStore` — atomic `append` / `list` / `get` / `readBranchPath` / bounded `searchSessions` / bounded `searchSessions`
 - `RunLedger` — durable run, event, tool-call, and usage rows
@@ -24,12 +24,12 @@ Use this package when you want a small, file-backed persistence layer on Node wi
 - single-writer or low-concurrency deployments
 - integration tests that need durable reopen semantics
 
-Do **not** use it as a substitute for PostgreSQL when you need heavy multi-writer concurrency, server-side pooling, or managed TLS. See [`@arnilo/prism-session-store-postgres`](postgres-persistence.md) for that path.
+Do **not** use it as a substitute for PostgreSQL when you need heavy multi-writer concurrency, server-side pooling, or managed TLS. See [`@arnilo/prism-core/sessions/postgres`](postgres-persistence.md) for that path.
 
 ## Inputs / request
 
 ```ts
-import { createSqlitePersistence } from "@arnilo/prism-session-store-sqlite";
+import { createSqlitePersistence } from "@arnilo/prism-core/sessions/sqlite";
 ```
 
 | Field | Type | Purpose |
@@ -73,7 +73,7 @@ Migrations run automatically on open and are idempotent across reopen. Under the
 
 ```ts
 import { createAgentSession } from "@arnilo/prism";
-import { createSqlitePersistence } from "@arnilo/prism-session-store-sqlite";
+import { createSqlitePersistence } from "@arnilo/prism-core/sessions/sqlite";
 import { runSessionStoreConformance } from "@arnilo/prism/testing/session-store-conformance";
 
 const persistence = createSqlitePersistence({ filename: "./prism.db" });

package/docs/supervisors.md

@@ -2,11 +2,11 @@
 
 ## What it does
 
-`@arnilo/prism-supervisor` adds optional runtime-selected delegation to an explicit local child allow-list. It returns normal `AgentRunResult` values and does not modify core `createAgent()` or deterministic workflows.
+`@arnilo/prism-core/runtime/supervisor` adds optional runtime-selected delegation to an explicit local child allow-list. It returns normal `AgentRunResult` values and does not modify core `createAgent()` or deterministic workflows.
 
 ## When to use it
 
-Use a supervisor when a host or agent must choose a child dynamically. Use `@arnilo/prism-workflows` for known DAGs, durable checkpoints, schedules, replay, or human suspension.
+Use a supervisor when a host or agent must choose a child dynamically. Use `@arnilo/prism-core/runtime/workflows` for known DAGs, durable checkpoints, schedules, replay, or human suspension.
 
 ## Inputs / request
 
@@ -36,7 +36,7 @@ Use a supervisor when a host or agent must choose a child dynamically. Use `@arn
 ## Implementation example
 
 ```ts
-import { createSupervisor } from "@arnilo/prism-supervisor";
+import { createSupervisor } from "@arnilo/prism-core/runtime/supervisor";
 
 const supervisor = createSupervisor({
   ownership: { tenantId: "tenant", userId: "user" },
@@ -78,6 +78,7 @@ Supervisors propagate parent `identity` and `effectStore` to every child agent/r
 
 ## Related APIs
 
+- [Multi-agent patterns](multi-agent-patterns.md): the decision table comparing this delegation pattern with in-session handoff (swarm) and A2A; handoff keeps one transcript, delegation keeps separate child runs — choose by boundary, budget, and telemetry needs.
 - [Agent identity](agent-identity.md): host-verified identity and narrow delegation.
 - [A2A interoperability](a2a.md): separate remote protocol boundary. `A2ATaskLifecycle` adapts host durable agent/workflow state directly; it does not route A2A execution through local supervisor child planning.
 - [Workflows](workflows.md): preferred deterministic orchestration.