@arnilo/prism 0.5.6 → 0.7.0

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`.

package/docs/history/migration-0.0.md

@@ -513,7 +513,7 @@ OAuth client behavior is 2026-07-28 conformant: `finishAuth` now takes the full
 
 ### Monolithic SDK 1.x → modular SDK v2 migration table
 
-| v1 (`@modelcontextprotocol/sdk` 1.30.0) | v2 / current Synapta API | Notes |
+| v1 (`@modelcontextprotocol/sdk` 1.30.0) | v2 / current Prism MCP API | Notes |
 | --- | --- | --- |
 | `new Client(...)` from `sdk/client/index.js` | same name from `@modelcontextprotocol/client` | `ClientOptions` gains `versionNegotiation`, `listChanged`, `inputRequired`, `cachePartition`, `listMaxPages` |
 | `InMemoryTransport` / `StdioClientTransport` / `StreamableHTTPClientTransport` | `InMemoryTransport`/`StreamableHTTPClientTransport` from `@modelcontextprotocol/client`; `StdioClientTransport` from `@modelcontextprotocol/client/stdio` | subpath moves only |
@@ -529,7 +529,7 @@ OAuth client behavior is 2026-07-28 conformant: `finishAuth` now takes the full
 
 - **Now (default):** `createPrismMcpWebHandler(factory)` without `sessionIdGenerator` is stateless dual-era — modern 2026-07-28 serving plus the SDK stateless fallback for 2025 clients. No `Mcp-Session-Id`, no sticky routing, `Last-Event-ID` replay not enabled.
 - **Now (opt-in):** configuring `sessionIdGenerator` keeps identity-bound legacy sessions (POST/GET/DELETE/SSE beside the strict modern handler) for hosts that still need them; the pairing requires exact `allowedOrigins` and host `resolveIdentity`.
-- **Planned removal:** the legacy session leg is deprecated once Synapta's clients and documented hosts are modern-era; removal lands as a breaking 0.x cut with a migration note here (the `sessionIdGenerator` option disappears and legacy traffic gets the SDK stateless fallback, which 2025 clients already work against). No date is committed in this release.
+- **Planned removal:** the legacy session leg is deprecated once the package's clients and documented hosts are modern-era; removal lands as a breaking 0.x cut with a migration note here (the `sessionIdGenerator` option disappears and legacy traffic gets the SDK stateless fallback, which 2025 clients already work against). No date is committed in this release.
 
 ## 0.0.7 → 0.0.8 OpenTelemetry adapter
 

package/docs/history/release-handoffs.md

@@ -2,6 +2,75 @@
 
 Operator publish handoffs per release line, kept verbatim. Not read on the hot path.
 
+### 0.7.0 publish handoff (plan 073 Tasks 28–29)
+
+**Decision: GO when the operator prerequisites below are recorded.** Release **0.7.0** is the **six-plan cut** that closed the extended line: [072](../evaluations.md) (execution timeline, workflow graph, trajectory/outcome evals, cockpit aggregations, workflow OTel), [073](../index.md) (host completeness: traps A–C, R01–R06, R08, R10–R14, Tasks 15/30/31 and the cut itself), [074](../attention-compiler.md) (R17 attention compiler and the host-programmable compaction trigger), [075](../memory-fabric.md) (Memory Fabric subpath), [077](../compaction-observational-memory.md) (R16 work-scope memory index) and [078](../supervisors.md) (host-owned subagent spawn, bounded async spawn/wait/cancel, worktree isolation). **Plan 079 (Telegram/Signal channels) was moved to 0.8.0 on 2026-09-15** so the cut stopped waiting on unstarted work; no channel adapter ships in 0.7.0.
+
+The graph is **10 publishable manifests** at exact **0.7.0** with internal caret ranges `^0.7.0`: root `@arnilo/prism` plus 9 workspace packages (3 `prism-*` family packages, 6 capability packages, 19 provider adapter subpaths inside the providers family). The predecessor published release is **0.6.0**.
+
+Host-visible delta (full detail in [migrate-to-0.7.md](../migrate-to-0.7.md)): two **hard refusals** inside existing surfaces — `@arnilo/prism-acp-agent` matches `mcp.allow` by WHATWG origin plus path-segment subtree (lookalike hosts, sibling prefixes, credentials, and ambiguous encodings now fail closed) and no longer silently falls back to a mock provider; `router.providerSource(model)` throws `ERR_PRISM_MODEL_ROUTER_ASYNC_REQUIRED` / `_ASYNC_STATE` instead of bypassing budgets, rate limits, circuits, fallbacks, selection policies, or durable state. Everything else is additive: opt-in attention compiler, `@arnilo/prism-memory/fabric`, the observational-memory work-scope index, supervisor `spawn_agent`/`wait_agent`/`cancel_agent`, plus behavioral tightenings inside R01–R14 surfaces. **No export was removed**: the compat baselines were regenerated and reviewed as **+469 public declarations, zero removals**.
+
+Evidence recorded for the tree under publication. `scripts/release-evidence.json` — **42 surfaces, 11 pass, 31 protected with reasons, `blocked: false`** (`test:postgres durable conformance` is a real pass; the only unavailable leg is the real-phase26 coding journey). `npm test` 5/5 stages; `npm run typecheck` green for root, all workspaces, and `examples/`; coverage core 92.43 lines against the 60/70/75 gate with every non-protected workspace above its recorded lines threshold (acp-agent recovered to 94.72 by exporting and testing its provider resolver); `npm run pack:dry-run` green for all ten packages; `npm run release:check --lockstep --version 0.7.0` reports **10/10 packages available**; `npm run release:publish --dry-run` produces all ten packs deterministically; `npm run security:threat-suites` **83/83**; `npm audit --audit-level=moderate` **0**; tracked+untracked secret scan **2328 files, 0 findings**; SBOM regenerated (172 packages) and `scripts/verify-sbom.mjs` clean against `security/license-policy.json`.
+
+Protected legs actually run here (not just recorded): `PRISM_TEST_POSTGRES_URL=… npm run test:postgres` against `pgvector/pgvector:pg16` — core **72/72**, memory **457/457**, phase conformance **11/11**; `node scripts/drill-migration-rollback.mjs --url …` — Postgres apply → downgrade `009` → verify-compat → re-apply → checksum-fail-closed and the SQLite flow all pass, plus the `--self-test` URL-refusal check. That leg found and closed three real defects hermetic doubles could not see: a `42P08` parameter-type ambiguity on the first task-scoped budget insert, a swallowed serialization failure that issued SQL against an aborted transaction (`25P02`), and a retry policy too small for 16 concurrent serializable writers. The release workflow's `postgres-integration` job must be green on the release commit before publication.
+
+```bash
+# Operator prerequisites (each a named blocked gate — none may be skipped):
+#  1. protected live-canary matrix green (live-canaries.yml, canary-report.json retained)
+#  2. PostgreSQL protected suite green (test:postgres) and CodeQL SAST green on the release commit
+#  3. npm OIDC trusted publishing identity authenticated (NPM_TOKEN with id-token, provenance)
+#  4. branch protection: the compatibility leg is node22-compat
+
+git diff --check
+npm ci
+# sdk:ready phases, as .github/workflows/release.yml runs them (env scoped to release:gate only):
+npm run typecheck && npm run lint && npm run format:check
+npm test && npm run test:coverage && npm run pack:dry-run
+PRISM_TEST_POSTGRES_URL=... npm run release:gate
+npm run security:threat-suites
+
+# Sign the release on the clean tagged tree (operator GPG key):
+git tag -s v0.7.0 -m "0.7.0"
+node scripts/release.mjs publish --lockstep --version 0.7.0
+
+# First-party package tags: push in batches of <=3 per push (tag-push storms; VENT 26-08-29).
+```
+
+Rollback pins the previous published line — `@arnilo/prism@0.6.0` and its siblings, exact pins per package. Persisted shapes are additive across 0.6.0 → 0.7.0 (fabric notes, scope entries, and spawn handles write new records through existing stores; migrations `001`–`006` are forward-only), so a pin rollback is store-safe: a 0.6.0 host ignores entries it cannot read and regains the pre-0.7.0 ACP prefix matching and router facade bypass, which is why those two refusals should be re-checked before rolling back.
+
+### 0.6.0 publish handoff (plan 071 Task 16)
+
+
+**Decision: GO when the operator prerequisites below are recorded.** Release **0.6.0** is the first published cut after **0.5.6**: the 0.5.7 cut was never published and is **superseded** by this one (registry preflight `node scripts/release.mjs check --lockstep --version 0.6.0` reports all **10/10 packages available**, so there is no published 0.5.7 to replace or deprecate). The graph is **10 publishable manifests** at exact **0.6.0** with internal ranges `^0.6.0`: root `@arnilo/prism` plus 9 workspace packages (3 `prism-*` family packages, 6 capability packages, 19 provider adapter subpaths inside the providers family).
+
+Host-visible delta (full detail in [migrate-to-0.6.md](../../docs/migrate-to-0.6.md)): the runtime floor moves to **Node `>=22`** (Node 20 is upstream EOL since 2026-04-30) and the never-published 0.5.7 content ships here — third-party floors (`pg ^8.23`, `playwright-core 1.63.0`, `@ai-sdk/provider 4.0.13`, `@agentclientprotocol/sdk` exact `1.4.0`, `@office-open/* 0.14.5`, `zod ^4.6.2`), the removed `@arnilo/prism-office` `playwright-core` peer, five additive host knobs, and the durable-tool-round / strict-provider tool-result fixes. No import path, store schema, event shape, or public signature was removed: the compat baselines were regenerated and reviewed as **+70 public names, zero removals** (32 declaration-site moves from the module splits).
+
+Evidence recorded for the tree under publication: `scripts/release-evidence.json` — **42 surfaces, 11 pass, 31 protected with reasons, `blocked: false`** (`test:postgres durable conformance` is a real pass, count 91, env **name** only); `npm test` 5/5 stages (core count 3716, skip 33); combined coverage core 92.13% lines against the 60/70/75 gate with all nine workspace suites above their lines thresholds; `security:threat-suites` 83/83; `npm audit --audit-level=moderate` 0; SBOM regenerated (`npm sbom --sbom-format spdx > security-artifacts/sbom.spdx.json`, 172 packages, 10 licenses, `verify-sbom` clean); tracked-source secret scan 2166 files, 0 findings.
+
+```bash
+# Operator prerequisites (each a named blocked gate — none may be skipped):
+#  1. protected live-canary matrix green (live-canaries.yml, canary-report.json retained)
+#  2. PostgreSQL protected suite green (test:postgres) and CodeQL SAST green on the release commit
+#  3. npm OIDC trusted publishing identity authenticated (NPM_TOKEN with id-token, provenance)
+#  4. branch protection: the compatibility leg is named node22-compat (renamed from node20-compat)
+
+git diff --check
+npm ci
+# sdk:ready phases, as .github/workflows/release.yml runs them (env scoped to release:gate only):
+npm run typecheck && npm run lint && npm run format:check
+npm test && npm run test:coverage && npm run pack:dry-run
+PRISM_TEST_POSTGRES_URL=... npm run release:gate
+npm run security:threat-suites
+
+# Sign the release on the clean tagged tree (operator GPG key):
+git tag -s v0.6.0 -m "0.6.0"
+node scripts/release.mjs publish --lockstep --version 0.6.0
+
+# First-party package tags: push in batches of <=3 per push (tag-push storms; VENT 26-08-29).
+```
+
+Rollback pins the previous published line — `@arnilo/prism@0.5.6` and its siblings, exact pins per package. **Never pin 0.5.7: it does not exist on the registry.** Persisted shapes are unchanged across 0.5.6 → 0.6.0, so a pin rollback loses only the Node floor, the peer floors, and the new knobs.
+
 ### 0.3.2 independent workflow patch (plan 045)
 
 
@@ -238,7 +307,7 @@ node scripts/release.mjs publish --independent --baseline c600eaa18f65b56764ec2f
 ### 0.3.2 changed-package cut (plan 050 Task 12)
 
 
-**Decision: GO when the operator prerequisites below are recorded.** The plan 050 cut covers the clay-integration-findings remediation and the OKF wiki adoption: baseline `edb4fcf` (the parent of the plan 050 implementation work); five packages publish in dependency order — root `@arnilo/prism` (FEATURE-1 agent-definition model override fallback, FEATURE-3 command driver hooks, FEATURE-2/6 docs+example, DOCS-1 contracts), `@arnilo/prism-coding-agent` (BUG-1 `allowCustom` default + optional `toolCallId`), `@arnilo/prism-supervisor` (BUG-2 child-factory `Agent` guard, FEATURE-4 opt-in child event passthrough), `@arnilo/prism-wiki` (OKF v0.2 bundle emission, 0.0.2 → 0.0.3), and `@arnilo/prism-acp-agent` (sqlite `:memory:` pass-through fix, 0.0.x-style patch 0.3.1 → 0.3.2). Every unchanged package stays byte-identical; docs-only packages (`@arnilo/prism-workflows`, `@arnilo/prism-compaction-observational-memory`) do not bump. Republished packages carry `^0.3.2` root peers; unchanged packages keep their window peers. Docs-only change on the root: none of the deltas are breaking (additive fields and fail-closed guards), compat additive-only, no migration.
+**Decision: GO when the operator prerequisites below are recorded.** The plan 050 cut covers the integration-findings remediation and the OKF wiki adoption: baseline `edb4fcf` (the parent of the plan 050 implementation work); five packages publish in dependency order — root `@arnilo/prism` (FEATURE-1 agent-definition model override fallback, FEATURE-3 command driver hooks, FEATURE-2/6 docs+example, DOCS-1 contracts), `@arnilo/prism-coding-agent` (BUG-1 `allowCustom` default + optional `toolCallId`), `@arnilo/prism-supervisor` (BUG-2 child-factory `Agent` guard, FEATURE-4 opt-in child event passthrough), `@arnilo/prism-wiki` (OKF v0.2 bundle emission, 0.0.2 → 0.0.3), and `@arnilo/prism-acp-agent` (sqlite `:memory:` pass-through fix, 0.0.x-style patch 0.3.1 → 0.3.2). Every unchanged package stays byte-identical; docs-only packages (`@arnilo/prism-workflows`, `@arnilo/prism-compaction-observational-memory`) do not bump. Republished packages carry `^0.3.2` root peers; unchanged packages keep their window peers. Docs-only change on the root: none of the deltas are breaking (additive fields and fail-closed guards), compat additive-only, no migration.
 
 ```bash
 node scripts/release.mjs changed --baseline edb4fcf   # 5 packages

package/docs/host-compositions.md

@@ -0,0 +1,147 @@
+# Host compositions
+
+Prism agents are host-assembled: the host application owns credentials, providers, persistence, permissions, and tool definitions. Prism provides two canonical, maintained host compositions and a zero-network inspection and readiness API to ensure host setups conform to their operational contracts:
+
+- **`personal` (`personal-assistant`)**: Local-personal host composition for single-operator productivity, personal tools, local/memory persistence, and secret redaction.
+- **`business` (`business-worker`)**: Multi-tenant enterprise worker host composition with verified tenant identity, mandatory durable storage, sandbox workspace containment, and strict governance enforcement.
+
+## Profiles
+
+| Profile | Ownership | Identity | Persistence | Sandbox | Governance |
+| --- | --- | --- | --- | --- | --- |
+| `personal` | Single user (`userId`) | Optional unverified operator | Memory or durable storage | Local workspace | Optional |
+| `business` | Tenant + user (`tenantId`, `userId`) | Mandatory verified identity (`verified: true`) matching tenant | Mandatory durable store (`durable: true`); memory rejected | Contained sandbox roots within workspace | Required supported governance |
+
+## Host composition API
+
+Both helper functions and the error class are exported from `@arnilo/prism`:
+
+```ts
+import {
+  inspectHostComposition,
+  assertHostCompositionReadiness,
+  HostCompositionError,
+  type HostCompositionProfile,
+  type HostCompositionOptions,
+  type HostCompositionReport,
+} from "@arnilo/prism";
+```
+
+### `inspectHostComposition(options)`
+
+Inspects an agent configuration and returns a typed `HostCompositionReport`. Inspection is **completely inert and performs zero network calls**. Canary secrets in credentials are never leaked.
+
+```ts
+const report = inspectHostComposition({
+  profile: "personal",
+  agent: personalAgent,
+  store: memoryStore,
+  credentialRefs: ["OPENAI_API_KEY"],
+});
+```
+
+Report structure:
+
+- `profile`: `"personal"` or `"business"`.
+- `effectiveTools`: Readonly list of tool names registered on the agent.
+- `credentialRefs`: Host credential references (sanitized, values never included).
+- `ownership`: Tenant and user ownership identifiers.
+- `storage`: Storage summary with `kind` (`"memory"`, `"postgres"`, `"sqlite"`, etc.) and `durable` boolean. Memory stores are truthfully reported with `durable: false`.
+- `sandbox`: Isolation status and resolved root paths.
+- `governance`: Coverage flags (authorization, trust, and custom policies).
+- `readiness`: Object with `ok: boolean` and list of `reasons` if not ready.
+
+### `assertHostCompositionReadiness(options)`
+
+Validates that the host composition satisfies all profile constraints. Throws `HostCompositionError` on the first violated rule:
+
+| Error Code | Violation |
+| --- | --- |
+| `ERR_PRISM_HOST_COMPOSITION_PROFILE` | Unknown or missing profile. |
+| `ERR_PRISM_HOST_COMPOSITION_OWNERSHIP` | Missing `userId` (personal), missing `tenantId` (business), or identity/ownership mismatch. |
+| `ERR_PRISM_HOST_COMPOSITION_STORAGE` | Non-durable or in-memory persistence passed to a business composition. |
+| `ERR_PRISM_HOST_COMPOSITION_SECRETS` | Agent lacks a configured `SecretRedactor`. |
+| `ERR_PRISM_HOST_COMPOSITION_PROVIDER` | Agent lacks an active `AIProvider` or model selection. |
+| `ERR_PRISM_HOST_COMPOSITION_SANDBOX` | Sandbox roots escape the declared `workspaceRoot`. |
+| `ERR_PRISM_HOST_COMPOSITION_GOVERNANCE` | Governance policy disabled or unsupported. |
+
+### Integration with `createSecureAgent`
+
+`createSecureAgent` accepts an optional `composition` field. When provided, readiness is asserted immediately before the agent is returned:
+
+```ts
+import { createSecureAgent } from "@arnilo/prism";
+
+const agent = createSecureAgent({
+  id: "worker-1",
+  definitionRevision: "1",
+  ownership: { tenantId: "acme-corp", userId: "worker-prod" },
+  identity: {
+    tenantId: "acme-corp",
+    userId: "worker-prod",
+    principal: { kind: "user", id: "worker-prod" },
+    scopes: ["task:execute"],
+    verified: true,
+    issuedAt: new Date().toISOString(),
+  },
+  composition: {
+    profile: "business",
+    store: postgresStore,
+    workspaceRoot: "/data/acme",
+    sandboxRoots: ["/data/acme/scratch"],
+  },
+  // ... other required secure agent options
+});
+```
+
+## Package install vs. import subpaths
+
+Always install containing packages directly. **NPM install never accepts subpaths**:
+
+```bash
+# Correct — install containing published packages:
+npm install @arnilo/prism @arnilo/prism-core @arnilo/prism-providers
+
+# Never install subpaths:
+# npm install @arnilo/prism-core/integrations/work (WRONG: fails with 404 / E404)
+```
+
+In your application code, import from documented subpaths:
+
+```ts
+// Subpaths exported by @arnilo/prism-core:
+import { createWorkTools } from "@arnilo/prism-core/integrations/work";
+import { createJsonSchemaArgumentValidator } from "@arnilo/prism-core/validation/json-schema";
+
+// Subpaths exported by @arnilo/prism-providers:
+import { createOpenAIProvider } from "@arnilo/prism-providers/openai";
+```
+
+## Background workers
+
+Business workers that share a durable checkpoint queue should pass `admission: { perTenant, drain }` into `createWorkflowCoordinator` and mount `createPrismOperatorHandler` beside health/drain. See [Operations runbook](operations.md) and [Workflows](workflows.md). Do not introduce a second scheduler.
+
+## Starter templates
+
+Scaffold fresh host compositions using `prism init`:
+
+```bash
+# Personal assistant composition
+prism init my-assistant --template personal-assistant
+
+# Business worker composition
+prism init my-worker --template business-worker
+```
+
+Each template produces a runnable agent, mock test fixtures, environment templates, and strict typing.
+
+## Dev inspector endpoint
+
+When running `@arnilo/prism-coding-tools/dev`, host compositions can be inspected via HTTP:
+
+```bash
+GET /inspect
+# or GET {basePath}/inspect
+```
+
+Returns the JSON serialized `HostCompositionReport` corresponding to the inspected agent and options.

package/docs/host-security.md

@@ -152,13 +152,13 @@ Wire those values where they matter: provider adapters receive the resolved cred
 - `@arnilo/prism-core/runtime/server` exposes no agent/workflow by default and requires `authorize()` for every matched operation. Derive complete tenant/account/user ownership from validated host identity, never request JSON. Workflow active identity and cancellation compare exact ownership; a tenant-only scope intentionally cannot cancel a checkpoint/run carrying account or user identity. The artifact review service (`createArtifactService`) requires authenticated identity + thread ownership on every attach/revise/compare/approve/reject/download, resolves concurrent reviewers via checkpoint CAS (no lost approvals), rejects local filesystem paths in `uri`/citations, redacts records before persist and on response, and serves downloads only through signed expiring links that are reauthorized against the token's ownership per request. When a blob store is wired (`bodies: ArtifactBodyStore`, 0.0.28), delivery links additionally resolve through `bodies.presign`; the reference `createS3ArtifactBodyStore` verifies ownership on every operation, verifies size/SHA-256/MIME on put and get (fail closed), refuses delete under legal hold (host `isHeld` callback), keeps credentials host-resolved, and never discloses bucket/path/key in errors, telemetry, or artifact records. Pass the current explicitly revised workflow definition so recursive hash mismatch fails before abort or durable mutation. Configure exact host/origin allow-lists where needed, wire redaction before execution, retain tool/workflow policy checks, and adapt the Web handler behind host TLS/rate limits. Disconnect abort is default; persistent reconnect/status belongs to durable workflow checkpoints, not an invented in-memory agent result cache. Outbound lifecycle webhooks (`createWebhookNotifier`, 0.3.2) share the same boundary posture: host-registered public HTTPS (or explicitly opted-in loopback HTTP) targets only, private/metadata literals rejected at registration, every attempt DNS-pinned and redirect-free through core `pinnedFetch`, redaction before HMAC signing, and the key held by the host only. Pass a known-secret `SecretRedactor`.
 - Coding tools from `@arnilo/prism-coding-tools/agent` accept an optional `ExecutionPolicy` checked inside each tool before side effects; shared policy propagation includes `createReadOnlyTools()`. They enforce finite text-scan/image/edit/write/shell limits, repository list/search depth/entry/match/scan/time caps, structured Git path/ref/message/output/patch/worktree caps, named-check concurrency/output caps, a 600-second default shell wall time, and a 64 MiB default total-output ceiling. Opt-in `createGitTools()` uses argument arrays with hooks/credential prompts/external diff disabled, requires host `commitIdentity` for commits, and never pushes or opens PRs. Successful truncated shell output leaves a host-owned exclusive `0600` temp file; delete `metadata.fullOutputPath` after use. Error/abort/timeout/overflow removes unpublished spills. Custom read/edit/shell/repository backends must honor supplied caps/signals. Use `@arnilo/prism-coding-tools/security` for path roots, command rules, identity-scoped approval caching, required `workspaceMode` on `createSandboxCodingComposition()` / `createSandboxCodingTools()`, and the optional `createDockerSandbox()` reference adapter. **Host mode is never contained execution** (every isolation capability false). Sandbox mode reports isolation only from validated adapter capability metadata: `composition.capabilities` carries the frozen `SandboxCapabilities` object (`workspaceCoherent`, `filesystemIsolated`, `networkIsolated`, `processIsolated`, `privilegeIsolated`, `egressRestricted`); the deprecated `containmentClaim` is a conservative projection and must never be used alone. Authorize security-sensitive actions from the individual capabilities the policy actually needs — e.g. require `filesystemIsolated` before hosting untrusted coding tasks, and `egressRestricted` before any network-capable run. Mixed wiring requires `allowMixedWorkspaceWiring` and still reports no isolation. Limits alone are not containment: construct the Docker adapter (absolute CLI, digest-pinned image, network none by default) or an equivalent host sandbox before treating coding execution as production-safe. Docker daemon/image trust, egress firewall/proxy, and artifact retention remain host-owned.
 - Allow-list egress (0.0.26, `@arnilo/prism-coding-tools/security`): `createEgressPolicy()` is deny-all with exact host/port/protocol rules and frozen `npm-registry`/`github` presets; `createAllowListEgressProxy()` is an HTTP forward proxy + CONNECT tunnel that pins DNS answers and verifies the connected address (rebinding defense), denies private/link-local/metadata ranges unless a rule opts in, re-validates every redirect hop against policy, and cuts oversized/slow transfers at frozen byte/time caps. TLS passes through without interception. Every allow/deny writes an audit record with no secrets. The proxy is inert until `start()`; `reloadPolicy()` is the only rule change path. `composeEgressSandboxNetwork(proxy.attestation(), name)` records validated attestation as `prism.egress.*` container labels — evidence, not enforcement: the host must restrict the Docker network so the proxy is the only reachable path, and `denyDirectEgress: true` is a claim the host makes true by topology. The proxy is not a firewall and cannot stop a container whose network reaches the internet directly.
-- Optional `@arnilo/prism-web-tools/browser` requires a host-supplied Playwright Browser (`playwright-core@1.61.0` peer). Import is inert. One non-persistent context belongs to one run; actions serialize; refs are snapshot-scoped; CSS/evaluate/CDP/persistent profiles are denied. Context routing + `serviceWorkers: "block"` deny file/data/blob/devtools/private/loopback by default and require contained-proxy attestation for external egress (Playwright routing is defense in depth, not DNS containment). Uploads are realpath-rooted; downloads quarantine with hash/MIME until host `approveRelease`; screenshots return bounded `ImageContent`. Observation vs mutation/high-impact actions map to `ExecutionPolicy`. Treat snapshot/page text as untrusted external content. Close contexts with `browser_close` or `manager.closeRun(runId)` on abort/terminal. Browser control endpoint, binary/image pin, and real egress firewall/proxy remain host-owned. Shared sandbox: `createSharedSandboxBrowserOptions()` + `assertBrowserSandboxNetwork()`.
+- Optional `@arnilo/prism-web-tools/browser` requires a host-supplied Playwright Browser (`playwright-core@1.63.0` peer). Import is inert. One non-persistent context belongs to one run; actions serialize; refs are snapshot-scoped; CSS/evaluate/CDP/persistent profiles are denied. Context routing + `serviceWorkers: "block"` deny file/data/blob/devtools/private/loopback by default and require contained-proxy attestation for external egress (Playwright routing is defense in depth, not DNS containment). Uploads are realpath-rooted; downloads quarantine with hash/MIME until host `approveRelease`; screenshots return bounded `ImageContent`. Observation vs mutation/high-impact actions map to `ExecutionPolicy`. Treat snapshot/page text as untrusted external content. Close contexts with `browser_close` or `manager.closeRun(runId)` on abort/terminal. Browser control endpoint, binary/image pin, and real egress firewall/proxy remain host-owned. Shared sandbox: `createSharedSandboxBrowserOptions()` + `assertBrowserSandboxNetwork()`.
 - Browser verified-state checkpoints (0.0.14, `createBrowserCheckpointLedger()`) store URL + domain-state hash + host data refs only — never serialized browser internals (cookies/storage/contexts). After any resume/interruption the ledger fails closed (`assertVerifiedBeforeSideEffect`) until the host reloads + verifies, so side effects never replay on stale state.
 - Device adapters (0.0.14, `resolveDevicePolicy`/`assertDeviceAdmit`) are deny-by-default: admission fails closed without explicit `enabled`, an explicit sandbox, approval (when required), an under-budget session count, and shared `RunLimits`. Stream chunks over the frozen cap are dropped with a marker; telemetry is redacted before emit/persist. No vendor voice/desktop package ships in 0.0.14 (demand-gated 0.1.x); device adapters cannot broaden consent/memory/network/file/browser/connector/tool permissions (gate 8).
 - Optional `@arnilo/prism-memory/wiki` tools treat agent-supplied input as untrusted at the first-party `.wiki/` filesystem boundary. `wiki_read_page` enforces lexical containment (`path.relative` with separator-aware `..`/absolute checks) plus `fs.realpath` containment for the wiki root and every successfully read file, so sibling-prefix (`.wiki-evil`), `..`, absolute, alternate-separator, and symlink escapes are denied before content is returned; missing contained pages report `found: false` while denied paths throw an access-denied error (never mapped to not-found). `wiki_record_insight` rejects empty titles/content, caps titles at 200 characters and content at 65,536 bytes, and collapses control characters and newlines in titles to single-line display text before any page/frontmatter/index/log write, so titles cannot inject Markdown headings, index entries, or log entries; slugs are allow-listed to `[a-z0-9-_]` with a non-empty fallback. See [LLM Wiki](wiki.md).
 - `@arnilo/prism-core/credentials/node` rejects oversized/malformed envelopes and excessive scrypt work before KDF allocation, uses async scrypt, and requires restrictive existing/new Unix vault modes. Keep vault ownership and parent-directory access host-controlled; review before `chmod 600`, never auto-weaken a file policy. Keychain calls use abort-aware native async work with finite timeout/payload caps and sanitized errors. OS prompts, service availability, and whether a native backend promptly honors cancellation remain host/platform boundaries; no plaintext fallback is attempted.
 - LLM compaction always sends finite summary `maxTokens`, retains bounded deltas/events, and bounds/redacts provider/factory/policy error detail. Observational-memory workers cap turns, calls, arguments, results, transcript, and surfaced errors; unknown tools fail before execution, while invalid results can only be rejected after a host tool returns and may therefore follow side effects. Pass all known provider/credential/tool secrets into compaction/runtime options; exact replacement is not secret discovery.
-- Default remote-media loading resolves every DNS answer, rejects the hostname if any address is non-public, and pins one validated address through the request. Explicit `allowedHostnames` can trust private destinations. A host-supplied `fetch` owns DNS/rebinding/proxy/redirect safety; a custom `requestUrl` must connect to its supplied validated address.
+- Default remote-media loading resolves every DNS answer, rejects the hostname if any address is non-public, and pins one validated address through the request. Explicit `allowedHostnames` can trust private destinations; `allowedCidrs` trusts IP ranges instead (checked after the hostname/denied-name lists, applied to literals and resolved answers, and bypassing only the private-IP block — metadata-style names and malformed ranges fail closed). A host-supplied `fetch` owns DNS/rebinding/proxy/redirect safety; a custom `requestUrl` must connect to its supplied validated address.
 - Permission checks happen before tool validation and before `tool.execute()`. Middleware cannot grant permission by renaming a tool.
 - Session stores and ledgers receive redacted values when a redactor is active, but durable storage remains host-owned. Enforce tenant/account/user ownership, retention, legal hold, and quotas via `ProductionPersistenceStore.lifecycle` (or host-equivalent DB controls). Hold always blocks delete.
 - `@arnilo/prism-core/enterprise/postgres` request paths require exact tenant scope plus principal for work/router state, use bound SQL values, and retain no prompts, connector request bodies, raw provider results, tokens, or credentials. Configure TLS/credential rotation/connection limits with the host `pg` pool. Run checksum/catalog migration setup with a controlled migration principal; keep request-path SQL least-privilege (`USAGE`, `SELECT`, `INSERT`, `UPDATE`, `DELETE` on six state tables) and do not grant request workers `CREATE`, `ALTER`, `DROP`, `TRUNCATE`, `GRANT`, or `COPY PROGRAM`. Back up and restore-test the schema; run bounded owner-scoped `state.cleanup()` from an authorized host job. `unknown` connector outcomes require reconciliation and must never auto-replay.