@arnilo/prism 0.7.0 → 0.9.0

package/docs/documents.md

@@ -1,8 +1,8 @@
-# Documents, spreadsheets, and presentations (`@arnilo/prism-office/documents`)
+# Documents, spreadsheets, and presentations (`@arnilo/prism-work/documents`)
 
 ## What it does
 
-The `@arnilo/prism-office/documents` package provides specification-compliant, AI-native OpenXML document generation, parsing, patching, and bounded preview rendering for Microsoft Word (`.docx`), Microsoft Excel (`.xlsx`), and Microsoft PowerPoint (`.pptx`) artifacts.
+The `@arnilo/prism-work/documents` package provides specification-compliant, AI-native OpenXML document generation, parsing, patching, and bounded preview rendering for Microsoft Word (`.docx`), Microsoft Excel (`.xlsx`), and Microsoft PowerPoint (`.pptx`) artifacts.
 
 It operates on a canonical, typed abstract syntax tree (AST) called the **Prism Document Model** (`DocModel`, `SheetModel`, `DeckModel`):
 - **Pure in-memory doctrine**: Functions accept `Uint8Array` container buffers or typed model objects and emit `Uint8Array` buffers or JSON models. Zero filesystem reads, zero network I/O, zero `process.env` lookups, and zero child process spawns.
@@ -15,13 +15,13 @@ It operates on a canonical, typed abstract syntax tree (AST) called the **Prism
 
 ## When to use it
 
-Use `@arnilo/prism-office/documents` whenever autonomous agents, coding assistants, workflow orchestrators, or enterprise applications need to:
+Use `@arnilo/prism-work/documents` whenever autonomous agents, coding assistants, workflow orchestrators, or enterprise applications need to:
 1. Synthesize professional DOCX reports, financial XLSX spreadsheets, or PPTX presentation decks from structured LLM outputs.
 2. Ingest existing OOXML artifacts into a structured, validated document model for analysis or automated summarization.
 3. Perform atomic, validated updates or localized edits to documents using typed patch operations.
 4. Render safe, bounded HTML previews or framework-neutral outline and grid snapshots in web and desktop hosts.
 
-Do **not** use this package for collaborative real-time editing (OT/CRDT), macro execution, or in-memory spreadsheet formula evaluation (formulas are preserved verbatim as `{ formula, cachedValue? }` read-only pairs).
+Do **not** use this package for collaborative real-time editing (OT/CRDT), macro execution, in-memory spreadsheet formula evaluation (formulas are preserved verbatim as `{ formula, cachedValue? }` read-only pairs), or OLE binaries (`.doc` / `.xls` / `.ppt`). Recalculation, slide PNG QA, and legacy convert run out of process in the [work sandbox](work-sandbox.md) (`xlsx_recalc.py`, `soffice --convert-to pdf|docx|xlsx|pptx`, `pdftoppm`).
 
 ## Inputs / request
 
@@ -40,6 +40,24 @@ Do **not** use this package for collaborative real-time editing (OT/CRDT), macro
 | `documentModelSchema` | `(kind: DocumentKind, slice?: string \| readonly string[]) => JsonSchema` | Retrieves the Draft-07 JSON Schema for a document kind, or a self-contained sliced sub-schema with resolved `$defs` (`docModelSchema` / `sheetModelSchema` / `deckModelSchema` expose the unsliced schemas). |
 | `validateDocumentModel`| `(model: unknown) => asserts model is DocumentModel` | Validates arbitrary JSON objects against Draft-07 document schemas and structural invariants. |
 
+### Agent tool facade
+
+`@arnilo/prism-work/tools` exports `createOfficeTools({ caps?, redactor?, filesystem?, artifacts? })`: six thin wrappers over this package — `office_parse`, `office_import`, `office_generate`, `office_patch`, `office_diff`, and `office_preview`.
+
+- Parse/import accept a document `kind` plus exactly one bounded `bytesBase64` or sandbox-relative `path`; results are marked `untrusted_external`.
+- Generate returns only `{ contentHash, byteLength, format }`; set `outputPath` for a contained sandbox write or `artifact: true` for the host-provided `ArtifactBodyStore`. Raw OOXML never enters tool content.
+- Patch is pure unless it also writes generated bytes. Parse/import/diff/preview declare no effect; generate/patch declare an external mutation only when a sandbox/artifact target is requested.
+- Filesystem paths must be relative to the configured root and pass the host/sandbox realpath containment hook when supplied. OOXML is still PK-gated, cap-limited, redacted at parse, and never executes macros.
+
+```ts
+import { createOfficeTools } from "@arnilo/prism-work/tools";
+
+const tools = createOfficeTools({
+  filesystem: { root: "/workspace", readFile, writeFile },
+  artifacts: { bodies, createRef }, // host-owned ArtifactBodyStore and ownership-aware ref factory
+});
+```
+
 ### Capacity Limits and Defaults
 
 Caps are strictly enforced in memory before compute-intensive translation or parsing:
@@ -107,7 +125,7 @@ import {
   renderPreviewBlocks,
   renderPreviewHtml,
   type DocModel,
-} from "@arnilo/prism-office/documents";
+} from "@arnilo/prism-work/documents";
 
 // 1. Define typed document model
 const doc: DocModel = {
@@ -156,7 +174,7 @@ history.apply([{ op: "set", target: { title: true }, value: "Updated Review" }])
 console.log(history.canUndo()); // true
 const restored = history.undo(); // restored to "Executive Summary" state
 
-import { diffDocument } from "@arnilo/prism-office/documents";
+import { diffDocument } from "@arnilo/prism-work/documents";
 const diff = diffDocument(parsed, restored, { maxOps: 4096 });
 
 // 6. Generate structured preview blocks & safe HTML
@@ -167,7 +185,7 @@ const htmlSnippet = renderPreviewHtml(restored, { maxHtmlBytes: 256 * 1024 });
 ## Extension and configuration notes
 
 ### Sub-package Pinning
-To avoid pulling in CLI frameworks or extraneous dependencies, `@arnilo/prism-office/documents` directly pins the exact underlying modular packages:
+To avoid pulling in CLI frameworks or extraneous dependencies, `@arnilo/prism-work/documents` directly pins the exact underlying modular packages:
 - `@office-open/docx@0.12.3`
 - `@office-open/xlsx@0.12.3`
 - `@office-open/pptx@0.12.3`
@@ -203,20 +221,23 @@ const telemetry: DocumentsTelemetry = {
 ```
 
 ### Decimal Fidelity Ceiling
-Financial worksheets often require exact decimal representations that JavaScript 64-bit binary floating-point numbers cannot represent without precision loss. `@arnilo/prism-office/documents` supports canonical string decimals (`{ type: "decimal", value: "1500000.00" }`), preserving exact numerical formatting without IEEE 754 precision artifacts.
+Financial worksheets often require exact decimal representations that JavaScript 64-bit binary floating-point numbers cannot represent without precision loss. `@arnilo/prism-work/documents` supports canonical string decimals (`{ type: "decimal", value: "1500000.00" }`). Generate emits that string; it does not coerce through `Number()`. Parse round-trips `{ type: "decimal", value: "1500000.00" }`.
+
+`list` blocks generate as OOXML numbering (`w:numPr`), not a `• ` prefix in `w:t`. Charts, pivots, comments, and headers remain fidelity-reported drops.
 
 ## 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 PK zip container signatures (`0x50, 0x4B, 0x03, 0x04`). Extension-based type inference is strictly prohibited.
+- **ZIP Signature Gating**: Buffers must begin with PK zip container signatures (`0x50, 0x4B, 0x03, 0x04`). Extension-based type inference is strictly prohibited. OLE compound files (`.doc` / `.xls` / `.ppt`, magic `D0 CF 11 E0`) fail this gate. Convert them in the [work sandbox](work-sandbox.md) then `office_parse`. Encrypted OOXML is still dropped on import.
 - **Fail-Closed Caps**: Input size and element count caps are evaluated before entering XML translation passes, preventing zip-bomb and decompression amplification attacks.
 - **Sanitize-by-Construction HTML**: `renderPreviewHtml` strictly entity-encodes all text fields, neutralizes dangerous protocols (`javascript:`, `http://`, `https://`), strips raw script/image tags, and caps output size to prevent DOM-based XSS and memory exhaustion.
 - **Performance Budget**: Warm generation of 200-block documents completes in under 15 ms; parse and round-trip equality checks complete in under 100 ms.
 
 ## Related APIs
 
-- [`@arnilo/prism-coding-tools/document-reader`](./document-reader.md): Bounded literal text extraction from PDF and DOCX documents for coding agent tools; optional host-selected Mistral OCR parser.
-- [`@arnilo/prism-core/integrations/work`](./work-tools.md): Microsoft 365 and Google Workspace identity-scoped connectors.
+- [`@arnilo/prism-work/document-reader`](./document-reader.md): Bounded literal text extraction from PDF and DOCX documents for coding agent tools; optional host-selected Mistral OCR parser.
+- [`@arnilo/prism-work/connectors`](./work-tools.md): Microsoft 365 and Google Workspace identity-scoped connectors.
 - [`@arnilo/prism-coding-tools/agent`](./coding-agent-tools.md): Coding tools and file operations.
 - [`@arnilo/prism-core/governance/observability`](./observability.md): OpenTelemetry instrumentation and trace adapters.
 - [Work artifacts and review](work-artifacts-and-review.md): evidence-bound artifact citations and `evidenceDigest` approvals.
+- [Work sandbox](work-sandbox.md): LibreOffice formula recalc, slide rasterization, and OLE convert; this package still does not spawn `soffice`.

package/docs/durable-runs.md

@@ -0,0 +1,129 @@
+# Durable runs
+
+## What it does
+
+Long investigations survive a host process that dies mid-run. With `checkpointPolicy: "every-turn"`, the durable store holds a running-state checkpoint at each provider-turn boundary — after the previous turn's tool results are in the session store, before the next provider request. A restarted worker resumes the *same* run with `decision: "continue"`: no tool is re-dispatched, and the session history is rebuilt from the checkpoint's session/leaf reference instead of being re-run from turn zero.
+
+This is crash recovery for the in-run state, not an orchestrator. The host workflow engine (Temporal, a queue, a supervisor) still owns scheduling, retries, and completion; Prism owns only the run's turns, counters, loop-local state, and sticky attention frontier.
+
+## When to use it
+
+- A `Do`-style investigation can outlive its worker process (deploys, evictions, OOM kills, spot reclamation) and re-running the paid turns is unacceptable.
+- The host wants a bounded, explicit recovery point rather than "restart the whole run".
+- An external orchestrator needs to resume a single run without replaying its tools.
+
+For approval suspension and batch decisions, see [Agent/session runtime § Durable interruption](agent-session-runtime.md#durable-interruption); `every-turn` is additive to that machinery and uses the same store, redaction, bounds, fingerprint, and CAS.
+
+## Inputs / request
+
+`AgentRunStateOptions` (per-run `RunOptions.runState` or `AgentConfig.runState`):
+
+| Field | Meaning |
+| --- | --- |
+| `checkpointPolicy` | `"decision"` (default) persists only on suspension/terminal status. `"every-turn"` adds one running-state checkpoint per provider turn. |
+| `checkpoints` | The host's `CheckpointStore`; the same store serves suspension, crash recovery, and status. |
+| `definitionRevision` | Host-authored revision participating in the fingerprint; a change without a revision bump refuses resume. |
+| `persistSessionState` | Also carries loaded-skill names and the attention sticky frontier into each turn checkpoint. |
+| `includeSkillBodies` | Alongside `persistSessionState`, carries exact skill instructions. |
+| `maxStateBytes` | Save-side byte ceiling (default 256 KB, hard 1 MB). Applies to every turn checkpoint identically. |
+| `checkpointMetadata` | Sidecar map (`Record<string, string>`, ≤ 4 KB, redacted) written with every checkpoint record — never inside the state value, so it costs no `maxStateBytes` budget. A function is resolved at each write, so a host closure can pin state that moves mid-run (git commit, document version). |
+
+```ts
+let head = "commit-1";
+await session.run("investigate", {
+  runState: {
+    checkpoints,
+    definitionRevision: "2026-09-19.1",
+    checkpointMetadata: () => ({ gitCommit: head, docVersion: "v12" }),
+  },
+});
+head = "commit-2"; // the next checkpoint records the new commit
+```
+
+`AgentRunLifecycle.status()` and `loadAgentRunState()` return the record's `metadata`; `resume` accepts `checkpointMetadata` to annotate the claim write, and without it the recorded map is preserved byte-for-byte across the claim and every later write. Legacy records without metadata read as `undefined` — an oversize or non-string map reads as absent rather than failing the resume.
+
+### Restore hooks (all-or-nothing)
+
+`resume` also accepts `restoreHooks`: host code that puts each external layer recorded in `checkpointMetadata` back where the checkpoint says it was. Hooks run sequentially before the claim write, each receiving the checkpoint context (`runId`, `version`, `status`, the redacted `metadata` map, and the raw `checkpoint` record) plus an `AbortSignal` that fires on host abort or the per-hook timeout.
+
+```ts
+await lifecycle.resume(ref, { decision: "approve", expectedVersion }, {
+  restoreHooks: [
+    async function restoreGit(cp) {
+      await git.reset(cp.metadata?.gitCommit);
+    },
+    async function restoreDocs(cp) {
+      await docs.restoreVersion(cp.metadata?.docVersion);
+    },
+  ],
+  restoreHookTimeoutMs: 10_000, // default, per hook
+});
+```
+
+All-or-nothing:
+
+- The first hook that throws or overruns `restoreHookTimeoutMs` (default 10 s, `DEFAULT_CHECKPOINT_RESTORE_TIMEOUT_MS`) aborts the resume with `CheckpointRestoreError` — `code: "ERR_PRISM_CHECKPOINT_RESTORE"`, `hook` naming the layer, `cause` the original error. Later hooks do not run.
+- The claim write and the conversation replay happen only after every hook succeeds, so a failed restore leaves the checkpoint byte-for-byte as it was — still resumable — instead of claiming a half-restored world. The server maps the failure to `409`/`ERR_PRISM_CHECKPOINT_RESTORE`.
+- Hooks run on claiming resumes only; `deny` and resuspend paths never call them.
+- The claim's `agent_resumed` event carries the audit: `restore: { hooks: [{ hook, durationMs }], durationMs }`.
+- Register once on the lifecycle (`createAgentRunLifecycle({ restoreHooks })`) or per resume; lifecycle-registered hooks run first. No hooks ⇒ no call, no overhead, no `restore` field.
+
+Resume uses `resumeAgentRun` / `resumeAgentRunStream` with `{ expectedVersion, decision: "continue" }`. The checkpoint records its own cadence, so a continued run keeps writing turn checkpoints without the host repeating `checkpointPolicy`.
+
+## Outputs / response / events
+
+Each turn checkpoint is a normal durable state (schema v1) carrying status `running`, the current `leafId`, run counters and wall deadline, loop-local state when the loop declares `snapshot`/`restore`, the run's `toolNames` grant, and — with `persistSessionState` — the loaded-skill catalog plus sticky attention frontier. Hard gates are unchanged: CAS `expectedVersion`, ownership/fencing, redaction at the checkpoint boundary, `maxStateBytes`, and the agent fingerprint (`agentFingerprint`) over id, revision, model, instructions, system prompt, skills, tools, guardrails, and loop revision.
+
+A crash leaves the last checkpoint at status `running`. `decision: "continue"` accepts exactly that: a running checkpoint with no interruption and no unresolved pending decisions. Everything else fails closed with `AgentRunStateError` and zero checkpoint writes:
+
+- `expectedVersion` mismatch, ownership/fencing mismatch, revision or fingerprint mismatch (`Stale or non-running agent run resume`, `Agent revision or fingerprint mismatch on resume`).
+- Status `suspended` — approvals, elicitations, and input guardrails still require `approve`/`deny` or a `RunDecision` batch; `continue` never bypasses a gate.
+- Any interruption, pending decision, or ready-to-dispatch pending call recorded in the state.
+
+The resumed run emits `agent_resumed` with the claimed version, reuses the recorded run counter snapshot, restores loop-local state, and dispatches nothing that was already persisted. Terminal saves then drop the pending markers as before.
+
+**Ambiguity window.** A turn checkpoint is taken between turns, so a crash can lose at most the one provider turn that was in flight; that turn is re-requested on resume. A crash *inside* a tool's side effect is still the pre-existing ambiguous case — an already-marked `dispatched` call is never replayed automatically; resolve it manually or key host effects on `runId`/`toolCallId` idempotency. Counter caveat: the interrupted turn's `maxTurns` charge was already recorded at assembly, and the resumed turn charges once more, so a crash costs one extra turn against a finite `maxTurns` budget.
+
+## Request/response example
+
+```ts
+import { createAgent, createMemoryCheckpointStore, providerDone, providerTextDelta, resumeAgentRun } from "@arnilo/prism";
+
+const checkpoints = createMemoryCheckpointStore();
+const agent = createAgent({
+  id: "investigation",
+  model: { provider: "mock", model: "demo" },
+  provider: { id: "mock", async *generate() { yield providerTextDelta("done"); yield providerDone(); } },
+});
+
+// Worker 1: long run, crash-recoverable between turns.
+const session = agent.createSession({ id: "investigation-session" });
+const first = await session
+  .run("Investigate", { runState: { checkpoints, definitionRevision: "2026-09-20.1", checkpointPolicy: "every-turn" } })
+  .catch(() => undefined); // worker died
+
+// Worker 2: same stores, same run, continue from the last turn boundary.
+const resumed = await resumeAgentRun(
+  agent,
+  { runId, sessionId: session.id },
+  { decision: "continue", expectedVersion: checkpointVersion },
+  { checkpoints, definitionRevision: "2026-09-20.1" },
+);
+```
+
+The complete network-free demo — one tool execution across the crash, resumed from the turn checkpoint — is [`examples/durable-investigation.ts`](../examples/durable-investigation.ts).
+
+## Extension and configuration notes
+
+- `checkpointPolicy: "decision"` is byte-identical to the pre-0.8 behavior: no turn writes, no extra events, no state fields. Turn checkpoints appear only when the option is set.
+- The policy is recorded on the state (when non-default) and restored on resume, so hosts do not thread the option through `AgentRunResumeOptions`.
+- Custom loops declared durable via `snapshot`/`restore` hooks keep their loop-local state across a crash resume exactly as they do across a suspension.
+- Per-run `toolNames` grants, run counters, and wall deadlines all ride the turn checkpoint; the resumed run cannot widen any of them.
+
+## Security and performance notes
+
+- `"continue"` is a host-API action only. Prism's AG-UI interrupt resolution accepts `approve`/`deny` only, channel adapters resume with `deny`, and there is no server route that forwards an untrusted `continue`; adding one would create an approval-bypass path.
+- Restore hooks are trusted host code running outside the sandbox: they see the checkpoint's (already redacted) sidecar map and are bounded only by their timeout. Because they run before the claim write, a timeout cannot leave a claimed checkpoint pointing at un-restored external state.
+- Every gate that protects a suspension protects a continue resume: exact ownership, fencing token, fingerprint, revision, CAS version, and the absence of unresolved work. A running checkpoint is a recovery point, never an authorization.
+- Cost is one bounded checkpoint write per provider turn (same redaction and `maxStateBytes` ceiling as suspension writes). A 40-turn investigation under `"every-turn"` therefore writes 40 checkpoint rows plus the terminal save, while the default `"decision"` policy writes at most one row per approval or suspension. Each row carries the run frontier, counters, run limits, and loop snapshot — not the message history, which stays in the session store and is pointed at by `leafId` — so the store grows with turns, not with turns × transcript; a state that would exceed `maxStateBytes` (default 256 KiB, `DEFAULT_MAX_AGENT_RUN_STATE_BYTES`) fails closed rather than truncating. Pick `"every-turn"` when a worker restart must cost at most one turn of thinking, and leave the default for runs with many cheap turns.
+- Checkpoints never contain provider objects, callbacks, signals, credentials, or raw secrets; the payload is bounded and redacted like any other durable state.

package/docs/embeddings.md

@@ -87,6 +87,11 @@ await runEmbeddingsConformance({
   bridge structurally (`createAlibabaEmbedder` remains assignable to `Embedder`
   without importing it). The contract is a superset: it adds usage and per-item
   error mapping.
+- The same host-seam posture covers local inference in retrieval: the RAG local
+  reranker (`resolveReranker({ kind: "local" })` / `createLocalReranker`) runs a
+  cross-encoder in the host process through a `LocalRerankRuntime`, so no
+  inference dependency name enters any manifest — see
+  [RAG local reranker](rag.md#local-reranker).
 - Adapters never auto-chunk: a batch over the provider cap rejects with
   `batch_too_large`, so `embedBatched`-style callers own batching and preserve
   per-item error attribution.

package/docs/enterprise-postgres-state.md

@@ -200,6 +200,10 @@ export async function recordEnterpriseState(state: PostgresEnterpriseState) {
 // `state` comes from `await createPostgresEnterpriseState({ pool, schema: "prism" })`.
 ```
 
+## Composing with messaging channels
+
+An outbox row is a natural fit for the `deliver` seam of `createMessagingRuntime` when the host wants each reply recorded alongside its own business state: append in the host transaction, commit, then hand the reply to the transport adapter. The channel runtime never imports this package and `@arnilo/prism-channels` has no `pg` peer — the composition is host code, because only the host knows which local mutation the row belongs with and which transport it owns. The appended payload should carry correlation ids (`connectionId`, the answered event id, reply kind) rather than message text, and the tenant id should come from the resolved identity's ownership scope rather than from the inbound event. `examples/messaging-outbox.ts` runs this seam offline against a fake pool.
+
 ## Extension and configuration notes
 
 - `createModelRouter({ resolver, stateStore: state.modelRouter })` keeps allow-list, residency, fallback, and diagnostics behavior in `@arnilo/prism-core/governance/model-router`; this package only supplies durable state. Router admission reservations (`reserveBudget`/`commitBudget`/`releaseBudget` on `state.modelRouter`) live in the `reservations` JSONB column of `prism_model_router_budgets`: one atomic UPSERT per admission, fencing-token-guarded commit/release in a SERIALIZABLE transaction, and TTL reconciliation as unknown usage; see [Model routing](model-routing.md).

package/docs/evaluations.md

@@ -31,6 +31,7 @@ Use this package when a host needs offline quality checks or sampled live scorin
 | `createSchemaScorer` | Validates final result or named step output against JSON schema |
 | `createErrorClassScorer` | Fails closed if denied error codes or blocked executions appear on timeline |
 | `createApprovalBeforeEffectScorer` | Verifies explicit approval occurred on timeline prior to sensitive tool effect |
+| `createDeterministicTurnScorer` | Requires host-answered (no-model) turns with intact provenance: `minTurns` deterministic steps, optionally from one `middleware`, and no provider request inside those turns |
 | `createCitationIntegrityScorer` | Invariant 0 on missing source, hash/span mismatch, or revoked ACL. Reads `environment.citations[]`. Ignores semantic `support`. |
 | `runComparison` | immutable dataset, 2–8 named candidates by default, pairwise scorers |
 | `assertEvaluationThreshold` / `serializeEvaluationReport` | mean/failure/per-scorer gates, hard invariant enforcement, and bounded redacted JSON |
@@ -267,6 +268,10 @@ The spawn pack (`@arnilo/prism-core/governance/evals` `spawn-pack.test.ts`) grad
 
 Negative controls wire deliberately vulnerable host compositions — uncatalogued spawn, skipped reservation, model-supplied scope escalation, leaky child tool list, non-aborting cancel, ungated ship — and assert the matching grader reports `0` naming the violation.
 
+## Guardrail-pack trajectory scenarios (plan 092)
+
+`guardrail-pack-scenarios.test.ts` gives every built-in [guardrail pack](guardrails.md#guardrail-packs) a violating and a compliant trajectory, graded by `createGuardrailPackScorer()` on the projected timeline: a denying guardrail step scores `0` and names `metadata.guardrail` (`pack:<pack>/<rule>`), a compliant trajectory scores `1` with no pack denial, and a `forbidTools` call that executed fails as an enforcement escape instead of passing vacuously. Each scenario runs `runScenario({ agent, turns, sessionConfig: { guardrailPacks: [...] }, timeline: "metadata" })` against a scripted mock provider; a pack-absent control re-runs the destructive script with no packs to prove the blocked calls were blocked by the pack.
+
 ## PostgreSQL enterprise state (0.0.23)
 
 `createPostgresEnterpriseState({ pool, schema }).evaluations` implements this package's existing `EvaluationStore`. The host creates an `EvaluationRecord` from verified ownership before append; every PostgreSQL query requires tenant scope, uses exact normalized account/user matching, and returns owner-bound opaque cursor pages. It is durable across reopen and supports the existing id/scorer/session/run/trace/dataset/item/experiment/status filters.

package/docs/execution-timeline.md

@@ -68,14 +68,21 @@ interface ExecutionTimeline {
   readonly sessionId?: string;
   readonly workflowId?: string;
   readonly workflowRevision?: string;
+  /** Workflow checkpoint sidecar metadata (`WorkflowCheckpointValue.metadata`); present only when projected with a checkpoint. */
+  readonly workflowMetadata?: Readonly<Record<string, unknown>>;
   readonly traceId?: string;
   readonly status: string;
+  readonly stopReason?: AgentFinishReason;
+  readonly stopDetail?: string;
   readonly startedAt: string;
   readonly finishedAt?: string;
   readonly input?: unknown;
   readonly result?: unknown;
   readonly usage?: Usage;
+  readonly cacheHitRate?: number;
   readonly steps: readonly ExecutionStep[];
+  readonly turns?: readonly TimelineTurn[];
+  readonly exhaustion?: TimelineExhaustion;
   readonly redacted: boolean;
   readonly content: TimelineContentPolicy;
 }
@@ -102,10 +109,54 @@ interface ExecutionStep {
 }
 ```
 
-Step kinds: `"run"`, `"turn"`, `"provider"`, `"tool"`, `"guardrail"`, `"delegation"`, `"compaction"`, `"attention"`, `"retry"`, `"hitl"`, `"artifact"`, `"workflow_node"`, `"loop_iteration"`, `"nested_workflow"`.
+Step kinds: `"run"`, `"turn"`, `"deterministic"`, `"provider"`, `"tool"`, `"guardrail"`, `"delegation"`, `"compaction"`, `"attention"`, `"retry"`, `"hitl"`, `"artifact"`, `"workflow_node"`, `"loop_iteration"`, `"nested_workflow"`.
+
+### `TimelineTurn` and `TimelineExhaustion`
+
+```ts
+interface TimelineTurn {
+  readonly turn: number;
+  readonly status: ExecutionStepStatus;
+  readonly startedAt: string;
+  readonly finishedAt?: string;
+  readonly durationMs?: number;
+  readonly providerAttempts: number;
+  readonly cacheHitRate?: number;
+  readonly budgets?: TurnBudgets;
+  readonly stopReason?: ProviderStopReason;
+}
+
+interface TimelineExhaustion {
+  readonly limit: RunLimitName;
+  readonly maximum?: number;
+  readonly observed?: number;
+  readonly currency?: string;
+  readonly consumed?: BudgetConsumedCounters;
+  readonly closestOtherAxes: readonly BudgetAxisUsage[];
+  readonly recentToolCalls: readonly ToolCallSummary[];
+}
+```
+
+`turns` is the per-turn trace, derived in one pass over folded provider steps: turn number, status,
+timing, attempts (retries included), input-token-weighted `cacheHitRate`, the last provider
+attempt's recorded `budgets`, and its stop reason. Cache rate is absent when cache usage is unknown;
+`budgets` is copied verbatim from `provider_turn_finished.metadata.budgets` and is absent on legacy
+events. `ExecutionTimeline.cacheHitRate` is the same input-token-weighted calculation across all
+provider attempts. The stop reason also rides the `provider` step's metadata (`metadata.stopReason`),
+so a flat renderer can badge attempts without walking `turns`. `turns` is absent on timelines with
+no turn steps (workflow timelines).
+
+`exhaustion` is the terminal limit attribution, present only when the run died on a run limit. It
+joins `run_limit_exceeded` (`limit`, `maximum`, `observed`, `currency`) with `budget_exhausted`
+(`consumed`, `closestOtherAxes`, `recentToolCalls`); a trace that recorded only the breach carries the
+first group and empty axes. Argument hashes only — `recentToolCalls` never contains raw arguments.
 
 `attention_compiled` folds into a one-step `"attention"` entry (status `succeeded`) whose metadata carries the measured counts (`used`, `usedAfter`, `inputCap`, `triggerRatio`, `droppedThinkingTurns`, `stubbedToolResults`, `stubbedBytes`, `truncated`); under-ratio turns emit no event, so they add no step.
 
+`deterministic_turn` folds into a `"deterministic"` step whose `name` is the answering middleware id and whose metadata carries `{ turn, middleware }`. A deterministic turn has no provider step, no `usage`, and no `stopReason`, so a host-answered turn can never be read as model output; its `turns` entry carries `providerAttempts: 0`, and `summarizeTimeline()`/`summarizeSession()` split the turn count into `turns: { model, deterministic }`. The same provenance is copied onto the assistant message as `message.metadata.deterministic = { middleware }`, so the persisted transcript alone proves the turn had no model behind it.
+
+`guardrail_decision` folds into a `"guardrail"` step whose `name` is the stage (`input`/`output`/`tool_input`/`tool_output`) and whose metadata carries `action`, the rule identity `metadata.guardrail` (compiled packs name it `pack:<pack>/<rule>`, other guardrails their configured name), and `toolName`/`toolCallId` when the decision is tool-scoped. A denying action (`deny`, `block`, `tripwire`) sets status `denied`; the free-text guardrail reason stays on the event, not the step.
+
 Step statuses: `"running"`, `"succeeded"`, `"failed"`, `"blocked"`, `"skipped"`, `"suspended"`, `"denied"`, `"aborted"`.
 
 Tree structure: steps are a flat ordered array. Tree via `parentId` (run → turn → provider/tool). Scorers iterate the flat array; UIs that need nesting walk `parentId`.
@@ -136,6 +187,7 @@ const timeline = projectTraceTimeline(trace, {
   redactor: createSecretRedactor(secrets),
 });
 // timeline.steps.map(s => [s.order, s.kind, s.name, s.status])
+// timeline.turns.map(t => [t.turn, t.cacheHitRate, t.budgets, t.stopReason])
 ```
 
 ### Workflow fold with checkpoint outputs
@@ -152,6 +204,37 @@ const timeline = projectWorkflowTimeline(workflowEvents, {
 
 See runnable host demo in `examples/execution-timeline.ts` for offline workflow timeline projection, cockpit summary, and Mermaid diagram export.
 
+### Stop reasons
+
+Run-level `stopReason` mirrors `agent_finished.finishReason` when the loop stopped on a ceiling or a host turn policy (`"host_policy"`); `status` reads `finished:<stopReason>` for those runs and `succeeded` for a natural end. `stopDetail` carries the host's `turnPolicy.stop` reason, bounded to 256 bytes and redacted at the runtime boundary. See [Runs and usage ledger § Clean stops and stop reasons](runs-and-usage.md#clean-stops-and-stop-reasons).
+
+Per-turn stop reasons are a separate, closed taxonomy (`ProviderStopReason`: `end_turn`, `tool_calls`,
+`max_output_tokens`, `content_filter`, `abort`, `provider_error`, `unknown`) because they answer a
+different question — why the *provider* returned, not why the loop ended. Each `provider_turn_finished`
+badges its turn (`timeline.turns[i].stopReason`) and its provider step (`metadata.stopReason`). See
+[Agent events](agent-events.md) § Provider turn events.
+
+A run that died on a run limit packs its attribution into the timeline and the summary line:
+
+```ts
+import { projectTraceTimeline, summarizeTimeline } from "@arnilo/prism-core/governance/observability";
+
+const timeline = projectTraceTimeline(trace);
+// timeline.turns.map(t => [t.turn, t.stopReason]);
+//   [[1, "tool_calls"], [2, "end_turn"]]
+// timeline.exhaustion;
+//   { limit: "maxTurns", maximum: 12, observed: 13,
+//     consumed: { turns: 13, inputTokens: 41_200, providerAttempts: 13, requestBytes: 1_048_576 },
+//     closestOtherAxes: [{ axis: "maxToolCalls", usedRatio: 0.625 }],
+//     recentToolCalls: [{ id: "tc_91", name: "searchCodebase", argHash: "sha256:9f.." }] }
+
+summarizeTimeline(timeline).exhaustion;
+// "maxTurns exhausted (13/12); closest: maxToolCalls 0.625"
+```
+
+`summarizeTimeline().exhaustion` is one renderable dashboard line; runs that ended any other way omit
+it, and `summarizeSession()` keeps each run's line in its `runs` array.
+
 ## Bounds
 
 | Dimension | Default | Hard cap |

package/docs/guardrails.md

@@ -26,6 +26,8 @@ const guardrails: Guardrails = { input: [pii], maxConcurrency: 1 };
 
 Set `AgentConfig.guardrails` for every session run or `RunOptions.guardrails` to append checks for one run. `DispatchToolCallOptions.guardrails`, workflow `RunWorkflowOptions.guardrails`, and MCP server `CreatePrismMcpServerOptions.guardrails` apply tool stages to direct calls. A stage has `Guardrail<"input" | "output" | "tool_input" | "tool_output">`, a name, optional revision, and `evaluate(context)` result.
 
+`AgentSessionConfig.guardrailPacks` compiles declarative, restrictive-only rule sets onto the tool stages once per session (see [Guardrail packs](#guardrail-packs)). Session packs merge after `AgentConfig.guardrails` and before `RunOptions.guardrails`. Hosts that dispatch tools directly can compile the same config with `compileGuardrailPacks(refs)` and pass the result as `DispatchToolCallOptions.guardrails`.
+
 Decisions are `allow`, `block`, `tripwire`, or `interrupt`. Evaluation defaults to declaration-order sequential. `maxConcurrency` may be 1–16; records are emitted in declaration order. Thrown or malformed decisions become a fail-closed tripwire. A throwing guardrail produces a `guardrail_failed` record whose `metadata.error` carries the underlying error message — redacted and bounded to 4 KiB — so failures stay diagnosable without leaking internals. Decision reasons are capped at 4 KiB and metadata at 16 KiB after JSON normalization and optional redaction.
 
 ## Outputs / response / events
@@ -70,15 +72,82 @@ const agent = createAgent({ model, provider, guardrails: { input: [pii], output:
 await agent.createSession().run("Draft reply", { guardrails: { toolInput: [commandGuard] } });
 ```
 
+## Guardrail packs
+
+A pack is configuration, not code: rules compile once per session onto the existing `tool_input` / `tool_output` seams. Packs can only deny or tripwire — they never grant permissions, widen arguments, or add a stage. A rule that matches produces the standard refusal-shaped `ToolResult`; `tripwire` additionally rejects the enclosing run.
+
+```ts
+const session = agent.createSession({
+  guardrailPacks: ["secrets-hygiene"],
+  // or, with options / inline rules:
+  guardrailPacks: [
+    { id: "coding-standard", options: { cwd: "/repo", roots: ["/repo"] } },
+    {
+      id: "my-pack",
+      version: 1,
+      rules: [{ id: "no-etc", tool: "write", pattern: "^/etc/", reason: "system path" }],
+    },
+  ],
+});
+```
+
+Built-in pack ids are public surface and versioned:
+
+| Pack | Rules | Notes |
+| --- | --- | --- |
+| `coding-standard` | `no-unrelated-file-edits`, `no-test-rewrites` | Applies to `write`/`edit`/`delete`/`move`. `options.roots` defaults to `[process.cwd()]`; `options.cwd` is the resolution base. Containment is lexical — symlinks are not resolved, so an `ExecutionPolicy` remains the hard boundary. |
+| `destructive-commands` | `no-recursive-force-delete`, `no-long-flag-force-delete`, `no-force-push` (includes `--force-with-lease`), `no-destructive-sql`, `no-device-overwrite` | Matched against the `shell` tool's `command` argument. |
+| `validation-respect` | `no-mutation-after-failed-validation` | Observes `options.validationTools` (default `test`, `run_tests`, `validate`, `validation`, `lint`, `typecheck`, `check`). A result carrying an error or a non-zero `exitCode` marks validation failed; the next successful validation clears it. Opt `shell` in explicitly when validations run through the shell tool. |
+| `secrets-hygiene` | `no-secret-material-in-arguments` | Scans argument strings (bounded depth and count) for credential shapes: `sk-`, `gh[pousr]_`, `AKIA…`, PEM private-key headers, JWTs, `xox[baprs]-`. Prism redaction replaces exact known values only, so these patterns ship with the pack. |
+
+Inline rule shape: exactly one of `pattern` (string or `RegExp`, compiled once) or `deny(args, context)` (typed predicate, host-trusted like all host code); optional `tool` (name or names; omitted matches every tool), `argPath` (dot path or paths such as `command` or `["from", "to"]`; omitted scans every argument string), `action` (`deny` default, or `tripwire`), and `reason`. Predicates receive `{ toolName, toolCallId, sessionId, runId, metadata, state }`, where `state` is pack-local and read-only. `action: "ask"` is rejected: the tool stage has no deterministic approval seam.
+
+Every evaluated rule emits a `guardrail_decision` event; the denying record's `guardrail` is `pack:<pack>/<rule>` and its `metadata` is `{ pack, rule, version }` — never tool arguments. `describeGuardrailPacks(refs)` returns the same identity rows (`pack:<pack>/<rule>`, stage, `pack@version`) that `snapshotRunBundle()` reports for the session config. Malformed config (unknown id, duplicate pack or rule id, both `pattern` and `deny`, invalid regex, `ask`) throws `GuardrailPackError` at session creation instead of silently dropping a rule.
+
+On the observability timeline each guardrail step carries that identity in `metadata.guardrail` (with `status: "denied"` when it denied — the free-text reason stays off the step to keep metadata low-cardinality), so evals can grade enforcement without reading tool arguments: `createGuardrailPackScorer()` from `@arnilo/prism-core/governance/evals` scores a denied `pack:` rule as a failed trajectory and names it. The built-in packs are covered by violating/compliant scenario pairs in `packages/prism-core/src/governance/evals/__tests__/guardrail-pack-scenarios.test.ts` (see [Evaluations](evaluations.md#guardrail-pack-trajectory-scenarios-plan-092)).
+
+## Claim grounding
+
+`createClaimGroundingGuardrail(options: ClaimGroundingGuardrailOptions)` is a deterministic output guardrail for quantitative claims. It scans assistant text once, then attributes each number to a completed host tool result from **this run** or to a host-governed figure. It never calls a model, store, or network service.
+
+```ts
+import { createClaimGroundingGuardrail } from "@arnilo/prism";
+
+const grounding = createClaimGroundingGuardrail({
+  requireEvidenceForNumbers: true,
+  evidenceSources: "tool_results", // default
+  onViolation: "block", // default; "flag" records but permits output
+});
+
+const agent = createAgent({ model, provider, guardrails: { output: [grounding] } });
+```
+
+Numbers in an assistant text block pass when their exact numeric value occurs in a same-run successful tool result. The default is strict: `4,320.50` matches `4320.5`; `~4.3k` does not. Set `tolerance: "rounded"` to accept half the final printed unit, so `~4.3k` can match `4320.5`.
+
+A host can supply governed figures without giving this package a storage dependency:
+
+```ts
+const grounding = createClaimGroundingGuardrail({
+  requireEvidenceForNumbers: true,
+  evidenceSources: ({ metadata }) =>
+    metadata.metric === "revenue-q2" ? [{ value: 4320.5, ref: "metric:revenue-q2" }] : [],
+});
+// `Revenue is 999 [evidence:metric:revenue-q2]` cites that governed source.
+```
+
+An explicit citation is `[evidence:<ref>]`, immediately after its claim (within 96 characters). Tool-result refs are `tool:<toolCallId>`; extractor refs may contain only letters, digits, `.`, `_`, `:`, and `-` (1–128 chars). A citation must name an evidence ref the guardrail received; arbitrary labels do not pass.
+
+With `onViolation: "block"`, the standard `GuardrailError` has `reason: "claim_ungrounded"` and bounded metadata `{ claim, contentIndex, start, end }` — never a full response body. `"flag"` returns `action: "allow"` plus that same metadata and `violation: true`, so the response stays visible while the normal `guardrail_decision` event and run ledger preserve the flag. Strict mode treats every standalone number (including dates, percentages, and versions) as a claim; use the option only where that law is wanted.
+
 ## Extension and configuration notes
 
-Guardrails are callbacks supplied by the host. Prism does not discover, load, retry, or persist callback code. `createSecureAgent()` keeps configured guardrails and only appends run-level checks; it never lets a run remove secure defaults. Custom loops receive guarded `LoopContext.generate()` and `LoopContext.dispatchToolCall()`; host code that directly calls a provider or `ToolDefinition.execute()` is outside the runtime boundary.
+Guardrails are callbacks supplied by the host. Prism does not discover, load, retry, or persist callback code. `createSecureAgent()` keeps configured guardrails and only appends run-level checks; it never lets a run remove secure defaults. Custom loops receive guarded `LoopContext.generate()` and `LoopContext.dispatchToolCall()`; host code that directly calls a provider or `ToolDefinition.execute()` is outside the runtime boundary. Guardrail packs follow the same rule: they are host-supplied config, compiled in memory per session, never discovered from disk or persisted by Prism.
 
 ## Security and performance notes
 
 Optional `@arnilo/prism-core/governance/policy` can record guardrail outcomes via `recordGuardrailDecision` (evidence refs only; see [Policy and audit](policy-and-audit.md)).
 
-Output buffering prevents blocked provider content from reaching subscribers, session entries, ledgers, parsers, delegation, or tools. Tool-output checks receive raw results but Prism discards blocked raw output before event, ledger, transcript, or MCP exposure. Redaction replaces exact known values only; it is not general secret detection. Parallel checks receive an abort signal, but callback code must honor it to stop in-flight work. Browser snapshots and page text from the `browser` subpath are untrusted external content: never allow them to modify tools, permissions, credentials, or policy. Browser mutations still require host `ExecutionPolicy`/approval; prompt-injection text in a page cannot grant upload/download release.
+Output buffering prevents blocked provider content from reaching subscribers, session entries, ledgers, parsers, delegation, or tools. Tool-output checks receive raw results but Prism discards blocked raw output before event, ledger, transcript, or MCP exposure. Redaction replaces exact known values only; it is not general secret detection. Guardrail-pack patterns compile once at session creation and argument scans are bounded (depth 8, 64 strings, 16 KiB per string), so rule cost stays off the provider path. Parallel checks receive an abort signal, but callback code must honor it to stop in-flight work. Browser snapshots and page text from the `browser` subpath are untrusted external content: never allow them to modify tools, permissions, credentials, or policy. Browser mutations still require host `ExecutionPolicy`/approval; prompt-injection text in a page cannot grant upload/download release.
 
 ## Related APIs