@arnilo/prism 0.6.0 → 0.8.0

package/docs/execution-timeline.md

@@ -0,0 +1,186 @@
+# Execution Timeline
+
+## What it does
+
+`ExecutionTimeline` is a frozen, JSON-serializable view-model that reconstructs what an agent or workflow run did: initial input, each step with optional input/output, and the terminal result. One type powers both host cockpit waterfalls and trajectory evaluation scorers.
+
+APIs in `@arnilo/prism-core/governance/observability`:
+
+- `projectAgentTimeline(events, options)` — fold live `AgentEvent[]` into a timeline
+- `projectTraceTimeline(trace, options)` — fold an `EvaluationTrace` (from persistence) into a timeline
+- `projectWorkflowTimeline(events, options)` — fold `WorkflowEvent[]` + optional checkpoint into a timeline
+- `createTimelineFolder(options)` — incremental folder for SSE/cockpit live updates
+- `createWorkflowTimelineFolder(options)` — incremental folder for workflow events
+- `summarizeTimeline(timeline)` — fast cockpit summary (duration, tool counts capped at 64, tokens, cost)
+- `summarizeSession(timelines)` — multi-run conversation/session rollups without double counting
+
+## When to use it
+
+Use `projectAgentTimeline` when you have a completed run's events in memory and need to render a waterfall, score a trajectory, or serialize for audit.
+
+Use `createTimelineFolder` when you are streaming events from `session.subscribe()` and need live updates — push events one at a time and call `snapshot()` to get the current timeline.
+
+Use `projectTraceTimeline` when you have an `EvaluationTrace` from `createPersistenceTraceResolver` and want the same timeline shape as a live fold.
+
+Use `projectWorkflowTimeline` when you have workflow events and optionally a checkpoint — node outputs from the checkpoint are joined into workflow node steps when the content policy allows I/O.
+
+Do not use the dev inspector folding logic (`packages/prism-coding-tools/src/dev/ui/inspector.ts`) for production — it is a composition-only browser asset, not an exported projector.
+
+## Inputs / request
+
+### Content-capture policy
+
+| Mode | Timeline contains | Default |
+| --- | --- | --- |
+| `"metadata"` | kinds, names, status, timings, usage, error codes | ✅ |
+| `"redacted_io"` | input/output after `SecretRedactor`, byte-capped per step | |
+| `"full_io"` | redactor still runs (secrets never pass); host accepts residual content | |
+
+### Projection options
+
+```ts
+interface TimelineProjectionOptions {
+  readonly content?: TimelineContentPolicy;    // default "metadata"
+  readonly redactor?: SecretRedactor;          // required when content ≠ "metadata"
+  readonly maxSteps?: number;                  // default 1,000; hard 10,000
+  readonly maxStepIoBytes?: number;            // default 16,384; hard 262,144
+  readonly traceId?: string;                   // explicit OTel trace ID to attach
+  readonly instrumentation?: { traceId(runId: string): string | undefined }; // auto-resolve traceId from OTel handle
+}
+```
+
+### Workflow projection options
+
+```ts
+interface WorkflowTimelineProjectionOptions extends TimelineProjectionOptions {
+  readonly checkpoint?: WorkflowCheckpointValue;
+}
+```
+
+## Outputs / result
+
+### `ExecutionTimeline`
+
+```ts
+interface ExecutionTimeline {
+  readonly schemaVersion: 1;
+  readonly runId: string;
+  readonly sessionId?: string;
+  readonly workflowId?: string;
+  readonly workflowRevision?: string;
+  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 steps: readonly ExecutionStep[];
+  readonly redacted: boolean;
+  readonly content: TimelineContentPolicy;
+}
+```
+
+### `ExecutionStep`
+
+```ts
+interface ExecutionStep {
+  readonly id: string;
+  readonly parentId?: string;
+  readonly kind: ExecutionStepKind;
+  readonly name: string;
+  readonly order: number;
+  readonly status: ExecutionStepStatus;
+  readonly startedAt: string;
+  readonly finishedAt?: string;
+  readonly durationMs?: number;
+  readonly input?: unknown;
+  readonly output?: unknown;
+  readonly error?: ErrorInfo;
+  readonly usage?: Usage;
+  readonly metadata?: Readonly<Record<string, unknown>>;
+}
+```
+
+Step kinds: `"run"`, `"turn"`, `"provider"`, `"tool"`, `"guardrail"`, `"delegation"`, `"compaction"`, `"attention"`, `"retry"`, `"hitl"`, `"artifact"`, `"workflow_node"`, `"loop_iteration"`, `"nested_workflow"`.
+
+`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.
+
+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`.
+
+## Examples
+
+### Live cockpit fold
+
+```ts
+import { createTimelineFolder, summarizeTimeline } from "@arnilo/prism-core/governance/observability";
+
+const folder = createTimelineFolder({ content: "metadata" });
+for await (const event of session.subscribe()) {
+  folder.push(event);
+  const timeline = folder.snapshot();
+  renderWaterfall(timeline.steps); // host UI
+}
+```
+
+### Offline trace fold
+
+```ts
+import { projectTraceTimeline } from "@arnilo/prism-core/governance/observability";
+
+const trace = await traceResolver({ ownership, sessionId, runId });
+const timeline = projectTraceTimeline(trace, {
+  content: "redacted_io",
+  redactor: createSecretRedactor(secrets),
+});
+// timeline.steps.map(s => [s.order, s.kind, s.name, s.status])
+```
+
+### Workflow fold with checkpoint outputs
+
+```ts
+import { projectWorkflowTimeline } from "@arnilo/prism-core/governance/observability";
+
+const timeline = projectWorkflowTimeline(workflowEvents, {
+  content: "redacted_io",
+  checkpoint: await checkpoints.load({ workflowId, runId, ownership }),
+});
+// Node outputs appear on workflow_node steps when checkpoint is provided.
+```
+
+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).
+
+## Bounds
+
+| Dimension | Default | Hard cap |
+| --- | --- | --- |
+| Max steps | 1,000 | 10,000 |
+| Per-step I/O bytes | 16 KiB | 256 KiB |
+| Total timeline bytes | 4 MiB | 32 MiB (eval trace envelope) |
+
+Exceeding `maxSteps` throws `TimelineError` with code `ERR_PRISM_TIMELINE_BOUNDS`. Oversize I/O per step is truncated with a marker string, not thrown.
+
+## Security and performance notes
+
+- Default `"metadata"` content policy emits zero prompts, tool arguments, tool results, or node payloads.
+- `"redacted_io"` and `"full_io"` always run `SecretRedactor` — secrets never survive into the timeline.
+- Oversize I/O is truncated; unredactable steps omit I/O and set `redacted: true`.
+- Ownership is not checked in the projector — callers must supply already-authorized events. `projectTraceTimeline` consumes traces from `createPersistenceTraceResolver`, which already enforces ownership.
+- Low-cardinality metadata only; `metadata` on steps must not contain free-text, session IDs, or credentials.
+- Incremental `push` is O(1) per event aside from I/O redaction. No O(n²) rebuilds.
+
+## Related APIs
+
+- [Observability](observability.md): OTel span hierarchy and provider capture policy.
+- [Agent events](agent-events.md): full `AgentEvent` union and subscriber semantics.
+- [Evaluations](evaluations.md): trajectory scorers consume `ScorerInput.timeline`.
+- [Workflows](workflows.md): `WorkflowEvent` stream, `WorkflowCheckpointValue` for node outputs, and `WorkflowGraphRunView` for DAG topology/status overlay (graph overlays carry status/timing only; full I/O payloads remain on `ExecutionTimeline`).
+- [Runs and usage ledger](runs-and-usage.md): `EvaluationTrace` persistence path.

package/docs/guardrails.md

@@ -70,6 +70,39 @@ const agent = createAgent({ model, provider, guardrails: { input: [pii], output:
 await agent.createSession().run("Draft reply", { guardrails: { toolInput: [commandGuard] } });
 ```
 
+## 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.

package/docs/history/0.7.0-primitive-review.md

@@ -0,0 +1,254 @@
+# Release 0.7.0 — Primitive, Compatibility, and Integration-Boundary Review
+
+Plan: [073-Release-0-7-0-Host-Completeness.md](../../plans/073-Release-0-7-0-Host-Completeness.md) Task 1  
+Baseline: Released `0.6.0`  
+Target: Release `0.7.0` (Host Completeness, Evidence, and Capability Boundaries)  
+Date: 2026-09-13  
+
+---
+
+## 1. Executive Summary & Review Scope
+
+This review freezes the architectural primitives, compatibility contracts, performance budgets, and security boundaries for Release **0.7.0**.
+
+The release addresses the **three integration traps** identified in 0.6.0 (Traps A, B, C) and delivers the **fourteen P0–P2 host completeness recommendations** (R01–R06, R08–R14), integrating:
+- **R07 / R15** from [Plan 072 — Host Eval and Observability Cockpit](../../plans/072-Host-Eval-And-Observability-Cockpit.md) (frozen in [`docs/_evidence/phase72-primitive-review.md`](../_evidence/phase72-primitive-review.md)),
+- **R16** from [Plan 077 — Work-Scope Memory Index](../../plans/077-Work-Scope-Memory-Index.md) (`WorkScope` / `projectWorkMemory`),
+- **R17** from [Plan 074 — Attention Compiler](../../plans/074-Attention-Compiler.md) (`assembleTurn`, cache-stable attention ratio gate, sticky stubs).
+
+### Universal Invariants Upheld
+
+1. **Fail closed at trust boundaries**: Identity validation, tenant scoping, document authorization, and sandbox isolation fail closed. Never weaken fail-closed assertions.
+2. **No new dependencies without explicit plan authorization**: Root remains zero runtime dependencies. Optional SDKs live strictly as optional peer dependencies within owning integration packages, never loaded at import or module evaluation time.
+3. **No second agent loops or duplicated control planes**: Reuse existing core primitives (`Agent`, `AIProvider`, `ModelRouter`, `CheckpointStore`, `LeaseStore`, `ToolEffectStore`, `RunLedger`, `ProcessSessions`, `DeviceAdapter`).
+4. **Byte hard caps preserved**: All process-safety limits (`maxRequestBytes`, `maxResponseBytes`, `maxEventBytes`, `maxResultBytes`) remain immutable ceilings.
+5. **Truth in capability and state**: No simulated or mock-only claims for production infrastructure. Unobserved or ambiguous external mutations remain explicitly `unknown`, never fabricated as succeeded or zero-cost.
+
+---
+
+## 2. Coverage Ledger & Primitive Mapping
+
+Every review row is mapped below to its reusable baseline primitives, implementation owner, generic capability gap, dependencies, and required release evidence.
+
+| ID | Title | Reusable Baseline Primitives | Implementation Owner | Generic Capability Gap | Dependencies | Release Evidence |
+|---|---|---|---|---|---|---|
+| **Trap A** | Parsed ACP MCP destination allow-list | `packages/acp-agent/src/index.ts`, `selectMcpServers` | `packages/acp-agent/src/` | URL-parsed origin and strict path-segment subtree matching | None (Node `URL`) | Origin lookalike rejection, traversal/separator refusal, port/scheme validation |
+| **Trap B** | Router sync facade fail-loud governance | `createModelRouter`, `providerSource` | `packages/prism-core/src/governance/model-router/` | Fast synchronous check throwing `ERR_PRISM_MODEL_ROUTER_ASYNC_REQUIRED` when budget/circuit/rateLimit configured | None | Sync bypass rejection on budget/circuit, async `resolve` passes |
+| **Trap C** | ACP real model/provider configuration | `PrismAcpAgentConfig`, `createSpawnableAgent` | `packages/acp-agent/src/` | Validated `model` + `credentialRef` config parsing, explicit mock opt-in | `@arnilo/prism-providers` | Direct provider invocation via ACP, unknown provider refusal, credential canary check |
+| **R01** | Governed provider invocation & aggregate accounting | `ModelRouter.resolve`, `recordUsage`, `AIProvider` | `packages/prism-core/src/governance/model-router/` | `GovernedAIProvider` adapter wrapping select, reserve, request policy, invoke, settle | None | Zero-budget denial, stream settlement, duplicate settlement idempotency |
+| **R01** | Aggregate task/tenant accounting | `PostgresModelRouterStateStore`, `stateKey` | `packages/prism-core/src/enterprise/postgres/model-router/` | Cross-call aggregate task/tenant dimensions; reservation renewal & fencing | PostgreSQL driver | Concurrent 32-attempt allocation under cap, non-session tool/embedding charging |
+| **R02** | Durable business-action drafts & review | `WorkIdempotencyStore`, `ArtifactBodyStore` | `packages/prism-core/src/integrations/work/` | Revision-bound draft state machine, payload digest verification, expiry | Persistence backends | Draft edit invalidates prior approval, resume executes exact revision, unknown outcome logged |
+| **R02** | Editable durable approvals (AG-UI/server) | `RunDecision`, `approveWithEdits`, AG-UI handler | `packages/ag-ui/src/`, `packages/prism-core/src/runtime/server/` | `approveWithEdits` protocol capability, CAS expectedVersion validation | `@arnilo/prism-ag-ui` | Edited approval round-trip, invalid schema denial, quorum invalidation |
+| **R03** | Docker process sessions & workspace coherence | `DockerSandboxSession`, `createProcessSessions` | `packages/prism-coding-tools/src/security/`, `agent/process/` | `startProcess` on `DockerSandboxSession`, attested container reattach | Docker CLI | Watcher I/O, kill/signal, registry restart recovery without duplicate spawn |
+| **R03** | Hosted sandbox (E2B) | `DisposableSandbox`, `ProcessSandboxBackend` | `packages/prism-coding-tools/src/security/e2b-sandbox.ts` | E2B adapter implementing `DisposableSandbox` + `startProcess` + snapshot resume | `@e2b/code-interpreter` (optional peer) | E2B execution, pause/resume, snapshot integrity, cleanup on abort |
+| **R04** | Document authorization in RAG | `retrieveContext`, `VectorStore`, `lexicalQuery` | `packages/memory/src/rag/`, `packages/memory/src/postgres.ts` | Principal/group ACL constraint injected into vector/lexical query legs | None / pgvector | Pre-ranking candidate exclusion, post-topK non-starvation, ACL update revocation |
+| **R04** | Incremental enterprise-source sync (Drive) | `RagStore`, `Chunker`, `VectorMemory` | `packages/memory/src/rag/sync.ts`, `connectors/google-drive.ts` | Change-token pagination (`newStartPageToken`), tombstone deletion, ACL sync | Google Drive API / `@googleapis/drive` | Incremental change ingestion, tombstone deletion, stale-token recovery |
+| **R05** | Validated host compositions | `createSecureAgent`, `createAgent` | `templates/personal-assistant/`, `templates/business-worker/` | Validated production wiring templates & static composition inspection | Internal packages | Packed npm install smoke, unredacted secret check, memory-persistence refusal |
+| **R06** | Fair background admission & drain | `createWorkflowCoordinator`, `PrismDrainController` | `packages/prism-core/src/runtime/server/drain.ts`, `workflows/coordinator.ts` | Multi-tenant fair queuing, graceful drain deadline, active run tracking | None | 503 on drain admit, queue fairness across tenants, clean in-flight completion |
+| **R07** | Behavioral & trajectory evaluation | `EvaluationTrace`, `runExperiment` (Plan 072) | `packages/prism-coding-tools/src/dev/` (inspector wiring) | Wiring 072 trajectory & scenario eval into inspector UI and release gates | Plan 072 artifacts | Scenario gate pass, trajectory deviation scoring, inspector run visualization |
+| **R15** | Execution timeline & workflow graph | `ExecutionTimeline`, `serializeWorkflowGraph` (Plan 072) | Plan 072 implementation | Consumed by 0.7.0 release journeys and Dev Inspector | Plan 072 artifacts | Timeline step rendering, node overlay, trace aggregation |
+| **R16** | Work-scope session memory index | `WorkScope`, `projectWorkMemory` (Plan 077) | Plan 077 implementation | Parallel session memory index; task isolation until explicit promote | Plan 077 artifacts | Task isolation test, promotion round-trip, scope boundary enforcement |
+| **R17** | Attention compiler & compaction trigger | `assembleTurn`, ratio gate (Plan 074) | Plan 074 implementation | Cache-stable prompt assembly, sticky stub compaction | Plan 074 artifacts | Ratio gate no-op under ceiling, sticky stubs above ceiling |
+| **R08** | Cross-layer memory correction & provenance | `ObservationalMemory`, `VectorMemory` | `packages/memory/src/memory.ts`, `compaction/observational-memory/` | Point correction, tombstoning, cross-layer provenance lineage, sharing grant | None / Postgres | Correct memory update, tombstone tombstoning in search, lineage query |
+| **R09** | External coding runtime delegation | `Supervisor`, `SubagentTool` | `packages/prism-coding-tools/src/agent/delegated/` | Typed adapters for Codex, Claude, Copilot, Gemini CLI, Cursor | Optional vendor SDKs | Approval interception, tool call containment, session resume |
+| **R10** | Semantic artifact diffs & evidence citations | `ArtifactBodyStore`, `patchDocument` | `packages/office/src/documents/diff.ts`, `packages/web-tools/src/evidence.ts` | Structural document diffs, evidence citation attestation and OCR grounding | None | Semantic diff visualization, citation verification, tampering rejection |
+| **R10** | Scanned document layout & OCR (Mistral) | `DocumentReader`, `parseDocument` | `packages/prism-coding-tools/src/document-reader/mistral-ocr.ts` | External layout analysis and OCR extraction adapter | Mistral AI API | PDF table extraction, layout preservation, fallback handling |
+| **R11** | Per-run tool narrowing & capability invalidation | `createToolRegistry`, `RunOptions` | `src/contracts-protocol.ts`, `src/tools.ts`, `packages/mcp/` | `RunOptions.toolAllowList`, dynamic tool filtering, remote capability cache refresh | None | Hidden tool schema, rejection of unauthorized tool call, MCP change invalidation |
+| **R12** | Native Bedrock Converse & ConverseStream | `bedrockProvider` (0.6.0 wraps `/openai/v1`) | `packages/prism-providers/src/bedrock/` | Native AWS Bedrock Converse & ConverseStream protocol adapter with SigV4 | `@aws-sdk/client-bedrock-runtime` | Native Converse tool round, ConverseStream event decode, token counting |
+| **R13** | Native Vertex Gemini with workload identity | `vertexProvider` (0.6.0 wraps OpenAI-compat) | `packages/prism-providers/src/vertex/` | Native Google Vertex Gemini `generateContent` & `streamGenerateContent` | `@google-cloud/vertexai` | Native content parts, tool round, Google ADC credential rotation |
+| **R13** | Thin Python & .NET remote clients | `PrismServer` HTTP / SSE routes | `clients/python/`, `clients/dotnet/` | Remote typed clients for run execution, SSE stream consumption, and approval | Python stdlib, .NET HttpClient | Stream framing, reconnection with Last-Event-ID, edited approval payload |
+| **R13** | Authenticated Slack & Teams recipes | `PrismServer` webhooks & decision routes | `examples/channels/slack/`, `examples/channels/teams/` | Webhook verification (Slack HMAC, Teams JWT), interactive review cards | Optional Bot SDKs | Forged signature denial, interactive card approval, draft re-review |
+| **R14** | Governed realtime voice orchestration | `RealtimeSession`, `DeviceAdapter` | `packages/prism-core/src/runtime/realtime/`, `packages/prism-providers/src/openai/realtime.ts` | Realtime tool calling bridge, microphone admission, barge-in cancellation | None (WebSocket) | Mic admission check, interruption cancellation, audio privacy retention |
+| **Release** | Integrated journeys, truth & publish | Release tooling, packaging, gates | `scripts/`, `docs/`, `packages/*/` | Lockstep 0.7.0 cut, generated package truth, live matrix evidence | Node 22/24 | Clean build, packaging gate pass, live matrix green, dry-run publish |
+
+---
+
+## 3. Reference Integration Matrix & Version-Selection Rules
+
+Prism adheres strictly to a zero-eager-dependency policy: optional third-party integrations must never bloat package install size or trigger unreviewed imports.
+
+| Domain | Selected Reference Implementation | Vendor / Package Identifier | Pinning & Version Selection Rule | Operational Role & Boundary |
+|---|---|---|---|---|
+| **Hosted Sandbox** | E2B | `@e2b/code-interpreter` | Pinned to `^1.0.0` as optional peer in `@arnilo/prism-coding-tools`. Evaluated only when host passes `createE2bSandbox`. | Untrusted ephemeral execution environment with filesystem snapshotting. Network strictly egress-controlled. |
+| **Enterprise Source** | Google Drive | `@googleapis/drive` (or native fetch REST v3) | Google Drive API v3. Optional peer or direct REST fetch in `@arnilo/prism-memory`. | Document knowledge source. Sync uses `changes.list` with `startPageToken` and ACL sync. |
+| **Layout / OCR** | Mistral OCR | `@mistralai/mistralai` (or native fetch) | Mistral Document AI API (`mistral-ocr-latest`). Optional peer in `@arnilo/prism-coding-tools`. | Scanned PDF / complex image layout parser. Output ingested as structured Markdown blocks. |
+| **Delegation: OpenAI** | OpenAI Codex | `@openai/codex` (or direct app-server) | Official OpenAI Codex thread SDK. Pinned peer in `@arnilo/prism-coding-tools`. | Cloud coding agent delegation via `startThread` / `resumeThread`. Tool execution approvals intercepted. |
+| **Delegation: Anthropic** | Claude Code / Agent SDK | `@anthropic-ai/claude-code` | Stable Agent SDK V1 (`query`, `canUseTool`, `options.resume`). No unstable V2. | Local/cloud coding agent delegation with explicit tool permission callbacks. |
+| **Delegation: GitHub** | GitHub Copilot | `@github/copilot-sdk` | Official Copilot Workspace/CLI SDK. Optional peer in `@arnilo/prism-coding-tools`. | Repo-scoped coding delegation. Enforces GitHub enterprise auth & token boundary. |
+| **Delegation: Google** | Google Gemini CLI | `@google-gemini/gemini-cli` | Official Gemini CLI SDK. Pinned peer in `@arnilo/prism-coding-tools`. | Local workspace CLI agent delegation. |
+| **Delegation: Cursor** | Cursor SDK | `@cursor/sdk` (or local CLI engine) | Cursor TypeScript SDK / local engine. Pinned peer in `@arnilo/prism-coding-tools`. | Editor-bound workspace task delegation. |
+| **Cloud Provider: AWS** | AWS Bedrock | `@aws-sdk/client-bedrock-runtime` | Pinned `^3.700.0` optional peer in `@arnilo/prism-providers`. | Native Converse & ConverseStream endpoints. Uses SigV4 request signing and AWS event streams. |
+| **Cloud Provider: GCP** | Google Vertex AI | `@google-cloud/vertexai` | Pinned `^1.9.0` optional peer in `@arnilo/prism-providers` (or direct REST). | Native Gemini `generateContent` & `streamGenerateContent` with Google ADC credentials. |
+| **Remote Client: Python** | `prism-agent-client` | `clients/python` | Target Python `>= 3.10`. Zero runtime dependencies outside Python standard library (`urllib.request`, `json`). | Remote client for starting runs, streaming SSE events, and submitting edited approvals. |
+| **Remote Client: .NET** | `Prism.Client` | `clients/dotnet` | Target `.NET 8.0+` LTS. Pure `System.Net.Http` and `System.Text.Json`. | Remote C# client for Prism Server communication. |
+| **Channel: Slack** | Slack Webhook Recipe | `examples/channels/slack` | Uses raw Node HTTP HMAC verification or optional `@slack/bolt`. | Webhook receiver verifying `X-Slack-Signature` and rendering Block Kit editable approval cards. |
+| **Channel: Teams** | Teams Bot Recipe | `examples/channels/teams` | Uses Bot Framework JWT verification or `@microsoft/teamsfx`. | Bot Framework webhook receiver validating Microsoft tenant and rendering Adaptive Cards. |
+| **Realtime Voice** | OpenAI Realtime | Native WebSocket | Pinned to OpenAI Realtime API (`gpt-4o-realtime-preview`). Pure WebSocket transport in `@arnilo/prism-providers`. | Governed bidirectional audio streaming with microphone device admission and barge-in cancellation. |
+
+---
+
+## 4. Performance, Startup, and Package Budgets
+
+All implementations in 0.7.0 must adhere to established performance ceilings recorded in `scripts/budgets.json`.
+
+### 4.1 Package Size & File Count Budgets
+
+| Package | Packed Bytes Baseline (±5%) | Unpacked Bytes Baseline (±5%) | File Count Baseline (±5%) | Public Export Count Ceiling |
+|---|---|---|---|---|
+| `@arnilo/prism` (root) | 1,098,881 | 3,690,682 | 441 | 1,287 |
+| `@arnilo/prism-acp-agent` | — | — | — | 11 |
+| `@arnilo/prism-ag-ui` | — | — | — | 312 |
+| `@arnilo/prism-mcp` | — | — | — | 134 |
+| `@arnilo/prism-memory` | — | — | — | 638 |
+| `@arnilo/prism-office` | — | — | — | 230 |
+| `@arnilo/prism-coding-tools` | — | — | — | 955 |
+| `@arnilo/prism-core` | — | — | — | 1,333 |
+| `@arnilo/prism-providers` | — | — | — | 506 |
+| `@arnilo/prism-web-tools` | — | — | — | 303 |
+
+*Rule:* Any increase in root packed bytes or file count must be justified in `scripts/budgets.json`. Export ceilings fail closed under `scripts/budget-gate.test.mjs`.
+
+### 4.2 Startup Time Budgets
+
+- **Cold-Process `import('@arnilo/prism')` Wall Time**:
+  - Baseline: `38 ms`
+  - Hard Ceiling: `250 ms`
+- **Machine-Relative Startup Ratio (`importMs / processStartMs`)**:
+  - Baseline Ratio: `3.3`
+  - Idle Ceiling Ratio: `8.0`
+  - Under-Load Ceiling Ratio (`loadavg >= 1.5` per CPU): `20.0`
+
+*Enforcement:* No optional provider, tool, database, or SDK dependency may evaluate at package import time. All heavy imports are deferred to dynamic `await import()` upon explicit host activation.
+
+### 4.3 Workload Bounds & Hard Caps
+
+- **Request / Response Safety Caps**:
+  - `DEFAULT_MAX_REQUEST_BYTES`: `4 MiB` (hard ceiling `32 MiB`)
+  - `DEFAULT_MAX_RESPONSE_BYTES`: `4 MiB` (hard ceiling `32 MiB`)
+  - `HARD_CHUNK_SIZE_CAP` (RAG): `64 KiB`
+- **Event Streaming Caps**:
+  - Ring buffer size: `100` items default, `10,000` hard max
+  - SSE message size: `64 KiB` max per frame
+- **Concurrency & Conformance Bounds**:
+  - Max concurrent distributed coordinator claims: `4` default, `16` max
+  - Router concurrent reservation stress: `32` concurrent workers across `>= 2` models
+
+---
+
+## 5. Architectural Invariants & Shared Contracts
+
+To maintain code quality and prevent divergence across packages:
+
+### 5.1 No Duplicated Primitives
+- **Agent Loop**: Single execution loop in `src/agent-session/session.ts`. No secondary loop in ACP, supervisor, or delegated wrappers.
+- **Approval Store**: Approvals managed strictly through `RunDecision` and `CheckpointStore`. No standalone approval database.
+- **Scheduler**: Workflow execution managed by `createWorkflowCoordinator` with `LeaseStore`. No secondary cron or background queue daemon.
+- **Tool Registry**: Single `ToolRegistry` implementation in `src/tools.ts`. Per-run narrowing filters the registry dynamically; it does not instantiate a separate registry.
+
+### 5.2 Genuinely Shared Contracts
+1. **Governed Provider Invocation**:
+   ```ts
+   export interface GovernedInvocationOptions {
+     readonly router: ModelRouter;
+     readonly model: ModelConfig;
+     readonly identity: AgentIdentity;
+     readonly maxCostUsd?: number;
+   }
+   ```
+   Wraps `AIProvider.generate()` / `generateStream()` with atomic reservation, request policy injection, response metering, and commit/release.
+2. **Durable Action Draft & Revision Reference**:
+   ```ts
+   export interface ActionDraftRevision {
+     readonly draftId: string;
+     readonly revision: number;
+     readonly payloadDigest: string; // sha256 of canonical payload
+     readonly policyRevision: string;
+     readonly createdAt: string;
+   }
+   ```
+   Ensures that any edit to a draft changes its digest and invalidates prior approvals.
+3. **RAG Access Constraint**:
+   ```ts
+   export interface RagAccessConstraint {
+     readonly principalId: string;
+     readonly groupIds: readonly string[];
+     readonly tenantId: string;
+   }
+   ```
+   Passed down to both vector search and lexical query legs to enforce pre-ranking exclusion.
+
+---
+
+## 6. Threat Model & Security Enforcement
+
+| Threat Domain | Threat Vector | Mitigation & Fail-Closed Enforcement | Visibility & Audit |
+|---|---|---|---|
+| **Identity & Tenant Scope** | Cross-tenant access, spoofed userId in distributed calls | Identity active and ownership matching verified via `assertIdentityMatchesOwnership`. Cross-tenant budget or session access throws `ERR_PRISM_SECURITY_TENANT_MISMATCH`. | OTel trace tenant tag; `AgentEvent.agent_denied` emitted on mismatch. |
+| **Source ACLs (RAG)** | Unauthorized document exposure via vector similarity or lexical search | Predicate pushdown into SQL / vector queries. Unauthorized candidates never enter candidate list or top-K ranking. Revocation invalidates cached candidates. | Audit log records query principal and accessed document IDs. Text is never logged. |
+| **Durable Approvals** | Approval replay, editing payload after approval, unauthorized approver | `expectedVersion` CAS on resume. Approved digest must match current draft digest. Edits invalidate approval and increment revision. Separation-of-duties requires distinct approver. | `RunDecision` records approver identity, timestamp, and payload digest. |
+| **Credentials & Secrets** | Leaked provider tokens in logs, event streams, or process argv | Credential references (`credentialRef`) used in configs. Secrets resolved only at provider edge. `SecretRedactor` scrubs all ledgers and event streams. | Canary strings tested across all event streams, logs, and artifacts. |
+| **Execution Containment** | Malicious shell execution, sandbox breakout, directory traversal | Docker sandbox with `network: "none"` or audited proxy; non-root user; workspace root confinement via realpath traversal checks. E2B uses isolated cloud VMs. | Container ID, image digest, and execution policy audited per session. |
+| **Durable Resume & Fencing** | Split-brain execution, duplicate side-effect replay upon network failure | Distributed lease acquisition with fencing tokens. External mutations record `ToolEffectStore` idempotent keys. Ambiguous outcomes stay `unknown`. | Lease records in PostgreSQL with TTL; unknown effects surfaced in run status. |
+| **Budget & Cost Exhaustion** | Runaway LLM loops, unmetered tool/compaction calls | Atomic budget reservation before model call. Strict budget mode rejects calls without known pricing. Background compaction and embeddings charged against task budget. | Aggregated usage records linked to `taskId` and `tenantId`. |
+| **Remote Runtime Delegation** | Prompt injection via delegated agents (Codex/Claude/Cursor) | All external agent tool requests route through Prism's `ExecutionPolicy`. Approval interception preserves host control. External session state kept isolated. | Delegated agent steps logged as `delegated_agent_step` events with token usage. |
+
+---
+
+## 7. Plan 072, 074, 077 Boundary Freeze
+
+To maintain strict modularity across concurrent plans:
+- **Plan 072 Freeze (Eval & Observability)**:
+  - `ExecutionTimeline`, `projectAgentTimeline`, `projectTraceTimeline`, `projectWorkflowTimeline` are owned by Plan 072.
+  - `WorkflowGraphView` and `serializeWorkflowGraph` are owned by Plan 072.
+  - Trajectory scorers (`createToolCallMatchScorer`) and scenario runners are owned by Plan 072.
+  - Task 15 of Plan 073 strictly wires these surfaces into Dev Inspector and Release Gates; it **does not** create duplicate timeline projectors.
+- **Plan 077 Freeze (Work-Scope Memory Index)**:
+  - `WorkScope`, `projectWorkMemory`, session memory isolation are owned by Plan 077.
+  - Plan 073 assumes work-scope isolation in its coding journeys without reimplementing the index.
+- **Plan 074 Freeze (Attention Compiler)**:
+  - `assembleTurn`, ratio gates, and sticky stub compaction triggers are owned by Plan 074.
+  - Plan 073 does not introduce a competing prompt assembly or compaction trigger.
+
+---
+
+## 8. Resolution of File Lists & Barrels (Tasks 2–29)
+
+Below are the exact resolved file paths and implementation splits for all tasks where tentative or proposed filenames appeared in the plan:
+
+| Task | Capability | Resolved Implementation & Test Files | Export / Barrel Location |
+|---|---|---|---|
+| **Task 4** | Real-provider ACP launcher | `packages/acp-agent/src/config.ts`, `packages/acp-agent/src/index.ts`, `packages/acp-agent/bin/prism-acp-agent.ts`, `packages/acp-agent/src/__tests__/agent.test.ts` | `packages/acp-agent/src/index.ts` |
+| **Task 5** | Host composition templates | `templates/personal-assistant/src/index.ts`, `templates/personal-assistant/package.json`, `templates/business-worker/src/index.ts`, `templates/business-worker/package.json`, `packages/prism-coding-tools/src/dev/inspector.ts` | `templates/README.md`, `packages/prism-coding-tools/src/dev/index.ts` |
+| **Task 6** | Governed provider invocation | `packages/prism-core/src/governance/model-router/invocation.ts`, `packages/prism-core/src/governance/model-router/__tests__/invocation.test.ts` | `packages/prism-core/src/governance/model-router/index.ts` |
+| **Task 7** | Aggregate task accounting | `packages/prism-core/src/enterprise/postgres/model-router/reservations.ts`, `packages/prism-core/src/enterprise/postgres/model-router/state-store.ts`, `packages/prism-core/src/enterprise/postgres/migrations.ts` | `packages/prism-core/src/enterprise/postgres/index.ts` |
+| **Task 8** | Durable draft review | `packages/prism-core/src/integrations/work/drafts.ts`, `packages/prism-core/src/integrations/work/tools.ts`, `packages/prism-core/src/integrations/work/google-workspace.ts`, `packages/prism-core/src/integrations/work/microsoft365.ts`, `packages/prism-core/src/integrations/work/__tests__/drafts.test.ts` | `packages/prism-core/src/integrations/work/index.ts` |
+| **Task 9** | AG-UI editable approvals | `packages/ag-ui/src/handler.ts`, `packages/ag-ui/src/types.ts`, `packages/ag-ui/src/projection.ts`, `packages/prism-core/src/runtime/server/handler/core.ts`, `packages/prism-core/src/runtime/server/handler/readers.ts` | `packages/ag-ui/src/index.ts` |
+| **Task 10** | Docker process sessions | `packages/prism-coding-tools/src/security/docker-sandbox.ts`, `packages/prism-coding-tools/src/security/docker-cli.ts`, `packages/prism-coding-tools/src/agent/process/sessions-spawn.ts`, `packages/prism-coding-tools/src/agent/process/sessions-recovery.ts` | `packages/prism-coding-tools/src/security/index.ts` |
+| **Task 11** | Document authorization in RAG | `packages/memory/src/rag/retrieve.ts`, `packages/memory/src/rag/types.ts`, `packages/memory/src/postgres.ts`, `packages/memory/src/__tests__/rag-acl.test.ts` | `packages/memory/src/rag/index.ts` |
+| **Task 12** | Google Drive incremental sync | `packages/memory/src/rag/sync.ts`, `packages/memory/src/connectors/google-drive.ts`, `packages/memory/src/__tests__/sync.test.ts` | `packages/memory/src/index.ts` |
+| **Task 13** | Hosted sandbox (E2B) | `packages/prism-coding-tools/src/security/e2b-sandbox.ts`, `packages/prism-coding-tools/src/security/__tests__/e2b-sandbox.test.ts` | `packages/prism-coding-tools/src/security/index.ts` |
+| **Task 14** | Fair background admission & drain | `packages/prism-core/src/runtime/server/drain.ts`, `packages/prism-core/src/runtime/workflows/coordinator.ts`, `packages/prism-core/src/runtime/server/__tests__/drain.test.ts` | `packages/prism-core/src/runtime/server/index.ts` |
+| **Task 15** | Inspector eval/journey wiring | `packages/prism-coding-tools/src/dev/ui/inspector.ts`, `packages/prism-coding-tools/src/dev/server.ts`, `packages/prism-coding-tools/src/dev/__tests__/inspector.test.ts` | `packages/prism-coding-tools/src/dev/index.ts` |
+| **Task 16** | Cross-layer memory correction | `packages/memory/src/memory.ts`, `packages/memory/src/lineage.ts`, `packages/memory/src/compaction/observational-memory/runtime.ts`, `packages/memory/src/compaction/observational-memory/ledger.ts` | `packages/memory/src/index.ts` |
+| **Task 17** | Delegated runtimes (Codex/Claude) | `packages/prism-coding-tools/src/agent/delegated/codex.ts`, `packages/prism-coding-tools/src/agent/delegated/claude.ts`, `packages/prism-coding-tools/src/agent/delegated/types.ts`, `packages/prism-coding-tools/src/agent/delegated/index.ts` | `packages/prism-coding-tools/src/index.ts` |
+| **Task 18** | Delegated runtimes (Copilot/Gemini/Cursor) | `packages/prism-coding-tools/src/agent/delegated/copilot.ts`, `packages/prism-coding-tools/src/agent/delegated/gemini-cli.ts`, `packages/prism-coding-tools/src/agent/delegated/cursor.ts` | `packages/prism-coding-tools/src/agent/delegated/index.ts` |
+| **Task 19** | Semantic artifact diffs & evidence | `packages/office/src/documents/diff.ts`, `packages/prism-core/src/runtime/server/artifacts-service.ts`, `packages/web-tools/src/evidence.ts` | `packages/office/src/index.ts`, `packages/web-tools/src/index.ts` |
+| **Task 20** | Scanned document OCR (Mistral) | `packages/office/src/documents/parse.ts`, `packages/prism-coding-tools/src/document-reader/mistral-ocr.ts` | `packages/prism-coding-tools/src/document-reader/index.ts` |
+| **Task 21** | Per-run tool narrowing | `src/contracts-protocol.ts` (`RunOptions.toolAllowList`), `src/tools.ts`, `src/agent-session/session/provider-round.ts`, `packages/mcp/src/bridge.ts`, `packages/mcp/src/capabilities.ts` | `src/index.ts`, `packages/mcp/src/index.ts` |
+| **Task 22** | Native Bedrock Converse | `packages/prism-providers/src/bedrock/converse.ts`, `packages/prism-providers/src/bedrock/converse-stream.ts`, `packages/prism-providers/src/bedrock/provider.ts` | `packages/prism-providers/src/bedrock/index.ts` |
+| **Task 23** | Native Vertex Gemini | `packages/prism-providers/src/vertex/native.ts`, `packages/prism-providers/src/vertex/provider.ts` | `packages/prism-providers/src/vertex/index.ts` |
+| **Task 24** | Python & .NET remote clients | `clients/python/prism_client/{__init__.py,client.py}`, `clients/dotnet/Prism.Client/{PrismClient.cs,Prism.Client.csproj}` | Standalone client directories (excluded from npm root) |
+| **Task 25** | Slack & Teams channel recipes | `examples/channels/slack/{index.ts,package.json}`, `examples/channels/teams/{index.ts,package.json}` | `examples/channels/` |
+| **Task 26** | Governed realtime voice | `packages/prism-core/src/runtime/realtime/index.ts`, `packages/prism-core/src/runtime/realtime/session.ts`, `packages/prism-providers/src/openai/realtime.ts` | `packages/prism-core/src/runtime/index.ts`, `packages/prism-providers/src/index.ts` |
+
+---
+
+## 8. Evidence Checklist
+
+Every capability delivered under 0.7.0 must satisfy this verification matrix:
+
+- [ ] **Positive Verification**: Proves expected behavior on compliant inputs.
+- [ ] **Refusal & Fail-Closed**: Proves rejected state on lookalike, malformed, unauthenticated, or cross-tenant inputs.
+- [ ] **Restart & Recovery**: Proves state durability across process restarts without duplicate execution or state corruption.
+- [ ] **Bounds & Limits**: Proves strict adherence to byte caps, timeout limits, and concurrency ceilings.
+- [ ] **Documentation & Migration**: Proves accurate contract documentation in `/docs` and migration guidance in `docs/migrate-to-0.7.md`.