@arnilo/prism 0.4.0 → 0.5.0

package/docs/documents.md

@@ -66,6 +66,7 @@ All package operations throw typed exceptions derived from `DocumentsError`:
 | `DocumentsCapExceededError` | `ERR_PRISM_DOCUMENTS_CAP_EXCEEDED` | Document exceeds byte size, block count, cell count, or slide count caps. |
 | `DocumentsParseError` | `ERR_PRISM_DOCUMENTS_PARSE_FAILED` | Input buffer lacks PK zip signature, is corrupted, or fails OOXML part parsing. |
 | `DocumentsFormatError` | `ERR_PRISM_DOCUMENTS_UNSUPPORTED_FORMAT` | Format mismatch (e.g. attempting to generate PPTX from a `DocModel`). |
+| `DocumentsPatchError` | `ERR_PRISM_DOCUMENTS_UNSAFE_PATH` | `__proto__`, `prototype`, or `constructor` appears as a `metadata` target or inside a block/slide/sheet `patch` segment (rejected before mutation to prevent `Object.prototype` pollution). |
 | `DocumentsPatchError` | `ERR_PRISM_DOCUMENTS_PATCH_FAILED` | Out-of-bounds index target, unknown patch operation, or invalid patch structure. |
 
 ## Request/response example
@@ -207,7 +208,7 @@ Financial worksheets often require exact decimal representations that JavaScript
 
 ## Related APIs
 
-- [`@arnilo/prism-document-reader`](./document-reader.md): Bounded literal text extraction from PDF and DOCX documents for coding agent tools.
-- [`@arnilo/prism-work-tools`](./work-tools.md): Microsoft 365 and Google Workspace identity-scoped connectors.
-- [`@arnilo/prism-coding-agent`](./coding-agent-tools.md): Coding tools and file operations.
-- [`@arnilo/prism-observability-opentelemetry`](./observability.md): OpenTelemetry instrumentation and trace adapters.
+- [`@arnilo/prism-coding-tools/document-reader`](./document-reader.md): Bounded literal text extraction from PDF and DOCX documents for coding agent tools.
+- [`@arnilo/prism-core/integrations/work`](./work-tools.md): Microsoft 365 and Google Workspace identity-scoped connectors.
+- [`@arnilo/prism-coding-tools/agent`](./coding-agent-tools.md): Coding tools and file operations.
+- [`@arnilo/prism-core/governance/observability`](./observability.md): OpenTelemetry instrumentation and trace adapters.

package/docs/embeddings.md

@@ -0,0 +1,112 @@
+# Embeddings
+
+## What it does
+
+`EmbeddingsProvider` is the provider-neutral embeddings contract: one-shot batch
+text→vector generation with usage accounting, per-item error mapping, and
+capability-gated models. First-party adapters ship in
+[`@arnilo/prism-providers/openai`](providers/openai.md) (OpenAI-compatible
+`POST {base}/embeddings`) and [`@arnilo/prism-providers/alibaba`](providers/alibaba.md)
+(DashScope `compatible-mode/v1/embeddings`); offline conformance runs via
+`runEmbeddingsConformance` from `@arnilo/prism/testing/provider-conformance`.
+
+## When to use it
+
+Use it when a host owns its embedding pipeline (RAG ingestion, memory indexing,
+semantic search) and wants a portable contract instead of per-provider HTTP code.
+Do not use it as a live integration runner: the contract is caller-gated, adapters
+perform no network on construction, and batch caps are enforced with typed errors
+rather than silent auto-chunking — chunk callers themselves (for example,
+`@arnilo/prism-memory`'s `embedBatched`).
+
+## Inputs / request
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `model` | `string` | Embedding model id, e.g. `text-embedding-3-small` or `text-embedding-v4`. |
+| `inputs` | `readonly string[]` | Texts to embed; order is preserved on `result.vectors`. Non-empty and within the provider batch cap. |
+| `dimensions` | `number?` | Output-dimensions override; only for models that support reduced dimensions (OpenAI `dimensions` param, DashScope 64–2048). |
+| `signal` | `AbortSignal?` | Cancellation; observed by the adapter transport. |
+
+Adapter options: `apiKey` (`CredentialValueSource` — the existing credential seam,
+resolved per call and redacted from errors), `baseUrl`/`preset` (Alibaba),
+`fetch` (inject a fake transport for offline tests), `headers`, and default
+`dimensions`/`encodingFormat` where the provider supports them.
+
+## Outputs / response / events
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `vectors` | `readonly (readonly number[])[]` | Vectors in input order; `vectors[i]` corresponds to `inputs[i]`. |
+| `usage` | `Usage` | Provider-reported token usage (`inputTokens`, `totalTokens`); empty object when the provider omits it. |
+| `dimensions` | `number` | Actual vector dimensionality reported by the response. |
+
+Failures throw `EmbeddingsError` with a stable `code`:
+`empty_input` (no inputs), `batch_too_large` (over the provider cap — OpenAI 2048,
+DashScope 10), `request_failed` (non-2xx, secret-redacted message),
+`response_malformed` (missing index, wrong dimensionality), `unsupported_model`
+(via `assertEmbeddingsSupported` when the host checks
+`ModelCapabilities.embeddings`).
+
+## Request/response example
+
+```json
+{ "model": "text-embedding-3-small", "input": ["hello", "world"], "dimensions": 256 }
+```
+
+## Implementation example
+
+```ts
+import { createOpenAIEmbeddingsProvider } from "@arnilo/prism-providers/openai";
+import { runEmbeddingsConformance } from "@arnilo/prism/testing/provider-conformance";
+
+const embeddings = createOpenAIEmbeddingsProvider({ apiKey: process.env.OPENAI_API_KEY });
+const result = await embeddings.embedMany({
+  model: "text-embedding-3-small",
+  inputs: ["hello", "world"],
+});
+// result.vectors.length === 2; result.usage.inputTokens reported
+
+// Offline conformance (fake transport, no network):
+await runEmbeddingsConformance({
+  provider: createOpenAIEmbeddingsProvider({ apiKey: "sk-test", fetch: fakeFetch }),
+  model: "text-embedding-3-small",
+  maxBatchSize: 2048,
+  sample: { inputs: ["a", "b"], dimensions: 2 },
+});
+```
+
+## Extension and configuration notes
+
+- Implement `EmbeddingsProvider` (`{ id, embedMany }`) for other vendors; the
+  contract is structural — no base class, no registry.
+- Models declare support with `capabilities.embeddings`; hosts gate with
+  `modelSupportsEmbeddings(capabilities)` / `assertEmbeddingsSupported(model)`,
+  mirroring the structured-output guard pattern.
+- `@arnilo/prism-memory` keeps its dependency-free `Embedder` host seam; adapters
+  bridge structurally (`createAlibabaEmbedder` remains assignable to `Embedder`
+  without importing it). The contract is a superset: it adds usage and per-item
+  error mapping.
+- Adapters never auto-chunk: a batch over the provider cap rejects with
+  `batch_too_large`, so `embedBatched`-style callers own batching and preserve
+  per-item error attribution.
+
+## Security and performance notes
+
+- API keys resolve through the existing `CredentialValueSource` seam and are
+  redacted from every thrown error (`redactSecrets`); no new secret paths.
+- Responses are read through the bounded transport (`readBoundedResponseJson` /
+  `readBoundedResponseText`) — response bodies cannot exhaust memory.
+- Input text is never logged; error messages carry status and redacted body only.
+- One HTTP request per `embedMany` call; response mapping allocates one vector
+  copy per input and nothing else. Per-item token caps are server-enforced;
+  the local cap is batch count.
+
+## Related APIs
+
+- [`@arnilo/prism-memory`](working-and-semantic-memory.md): `Embedder` host seam and `embedBatched` —
+  consumption side of the structural bridge.
+- [Provider conformance](provider-conformance.md): `runEmbeddingsConformance` and
+  the offline conformance matrix this contract joins.
+- [Provider packages](provider-packages.md): subpath import rules for
+  `@arnilo/prism-providers/openai` and `@arnilo/prism-providers/alibaba`.

package/docs/enterprise-postgres-state.md

@@ -2,7 +2,7 @@
 
 ## What it does
 
-`@arnilo/prism-enterprise-postgres` is one optional PostgreSQL composition for existing enterprise state seams:
+`@arnilo/prism-core/enterprise/postgres` is one optional PostgreSQL composition for existing enterprise state seams:
 
 | State | Composition property | Durable behavior |
 | --- | --- | --- |
@@ -14,7 +14,7 @@
 | ERP messaging | `erpMessaging` | Transactional outbox/inbox markers plus bounded, tenant-scoped at-least-once dispatch (migration 004). |
 | Multi-party approvals | `createPostgresApprovalStore({ pool, schema, authority })` | Immutable approval requests, role/quorum decisions, revocation, bounded delegation, and atomic grant consumption (migration 005). |
 
-`createPostgresEnterpriseState()` opens a host-supplied or adapter-owned `pg` pool, verifies/applies checksum-protected enterprise migrations (`001_enterprise_state`, `002_tool_effects`, `003_router_reservations`, `004_erp_messaging`, `005_erp_approvals`), and returns those stores plus explicit cleanup and close operations. Importing it performs no I/O. It is separate from session/run persistence in [`@arnilo/prism-session-store-postgres`](postgres-persistence.md).
+`createPostgresEnterpriseState()` opens a host-supplied or adapter-owned `pg` pool, verifies/applies checksum-protected enterprise migrations (`001_enterprise_state`, `002_tool_effects`, `003_router_reservations`, `004_erp_messaging`, `005_erp_approvals`), and returns those stores plus explicit cleanup and close operations. Importing it performs no I/O. It is separate from session/run persistence in [`@arnilo/prism-core/sessions/postgres`](postgres-persistence.md).
 
 ## When to use it
 
@@ -25,7 +25,7 @@ Use memory/file stores only for tests, demos, or a deliberately single-process h
 ## Inputs / request
 
 ```ts
-import { createPostgresEnterpriseState } from "@arnilo/prism-enterprise-postgres";
+import { createPostgresEnterpriseState } from "@arnilo/prism-core/enterprise/postgres";
 import { Pool } from "pg";
 
 const pool = new Pool({
@@ -95,7 +95,7 @@ A migration creates `prism_policy_decisions`, `prism_evaluations`, `prism_work_i
 ## Implementation example
 
 ```ts
-import { createPostgresErpMessaging } from "@arnilo/prism-enterprise-postgres";
+import { createPostgresErpMessaging } from "@arnilo/prism-core/enterprise/postgres";
 
 const messaging = createPostgresErpMessaging({ pool, schema: "prism" });
 const client = await pool.connect();
@@ -141,7 +141,7 @@ await messaging.dispatcher.replay({
 
 ```ts
 import type { AgentIdentity } from "@arnilo/prism";
-import { createPostgresEnterpriseState, type PostgresEnterpriseState } from "@arnilo/prism-enterprise-postgres";
+import { createPostgresEnterpriseState, type PostgresEnterpriseState } from "@arnilo/prism-core/enterprise/postgres";
 
 const identity: AgentIdentity = {
   tenantId: "tenant-1",
@@ -202,13 +202,13 @@ export async function recordEnterpriseState(state: PostgresEnterpriseState) {
 
 ## Extension and configuration notes
 
-- `createModelRouter({ resolver, stateStore: state.modelRouter })` keeps allow-list, residency, fallback, and diagnostics behavior in `@arnilo/prism-model-router`; this package only supplies durable state. Router admission reservations (`reserveBudget`/`commitBudget`/`releaseBudget` on `state.modelRouter`) live in the `reservations` JSONB column of `prism_model_router_budgets`: one atomic UPSERT per admission, fencing-token-guarded commit/release in a SERIALIZABLE transaction, and TTL reconciliation as unknown usage; see [Model routing](model-routing.md).
+- `createModelRouter({ resolver, stateStore: state.modelRouter })` keeps allow-list, residency, fallback, and diagnostics behavior in `@arnilo/prism-core/governance/model-router`; this package only supplies durable state. Router admission reservations (`reserveBudget`/`commitBudget`/`releaseBudget` on `state.modelRouter`) live in the `reservations` JSONB column of `prism_model_router_budgets`: one atomic UPSERT per admission, fencing-token-guarded commit/release in a SERIALIZABLE transaction, and TTL reconciliation as unknown usage; see [Model routing](model-routing.md).
 - `createPostgresErpMessaging({ pool, schema? })` is the direct messaging composition. `outbox.append` and `inbox.record` accept a caller-owned `PoolClient`; the host must put them in the same transaction as its local mutation. The dispatcher owns only short claim/transition transactions and never invokes business callbacks or stores executable handlers.
 - `createPostgresApprovalStore({ pool, schema?, authority })` is the direct approval composition (migration 005). `authority.resolveRoles(actor, request)` and `policyRevision` are host-owned; Prism persists only accepted role grants and delegation chains. `decide`/`revoke` lock the request row and revision-check the terminal transition in one transaction. `consume` accepts an optional caller-owned `client`; grant consumption and the protected action commit (or roll back) together.
 - Rate/budget/circuit tables are capped like the memory store: `consumeRate`/`readBudget`/`addUsage`/`reserveBudget` accept `maxRateKeys`/`maxBudgetKeys` (the router passes its resolved limits) and evict the least-recently-used row on new-key insert — never the row just inserted, never a budget row holding an active reservation — else fail closed with `ERR_PRISM_MODEL_ROUTER_STATE`. Cleanup prunes expired reservations within its bounded batch.
 - Policy/evaluation/query public contracts stay in their owning packages. This package exports `createPostgresEnterpriseState`, `createPostgresApprovalStore`, `createPostgresErpMessaging`, their options/result/types, and `EnterprisePostgresError`; it has no SQL, DDL, codec, queryable, or migration subpath.
 - The fixed schema has no generic key/value table and no background cleanup scheduler. Schedule `state.cleanup()` from an authorized host job, size its bounded batch for the deployment, and monitor unknown work rows for reconciliation. Run protected integration checks with `PRISM_TEST_POSTGRES_URL="$DATABASE_URL" npm run test:postgres`; the command rejects an absent URL instead of silently skipping database coverage.
-- The OPA adapter (`@arnilo/prism-policy/opa`, 0.0.28) records decisions into the same `state.policy` store unchanged via `evaluateAndAppend` — see [Policy and audit](policy-and-audit.md#opa-external-policy-adapter-arniloprism-policyopa-008).
+- The OPA adapter (`@arnilo/prism-core/governance/policy/opa`, 0.0.28) records decisions into the same `state.policy` store unchanged via `evaluateAndAppend` — see [Policy and audit](policy-and-audit.md#opa-external-policy-adapter-arniloprism-policyopa-008).
 - Request-path state SQL uses `SELECT`, `INSERT`, `UPDATE`, and `DELETE` on the eight state tables. The open/migration lifecycle additionally needs schema/catalog/advisory-lock and DDL permissions. Use a deployment migration principal for that lifecycle and a least-privilege request role for request traffic; this release intentionally does not ship a migration CLI or worker.
 
 ## Security and performance notes

package/docs/evaluations.md

@@ -2,11 +2,11 @@
 
 ## What it does
 
-`@arnilo/prism-evals` adds optional deterministic scorers, immutable datasets, bounded persistence-trace grading, explicit host model judges, pairwise comparisons, CI thresholds, live post-run scoring, and batch experiments over `AgentRunResult`. Scores are finite numbers in `[0, 1]` with optional reason/metadata and linkage to run/session/trace/experiment IDs.
+`@arnilo/prism-core/governance/evals` adds optional deterministic scorers, immutable datasets, bounded persistence-trace grading, explicit host model judges, pairwise comparisons, CI thresholds, live post-run scoring, and batch experiments over `AgentRunResult`. Scores are finite numbers in `[0, 1]` with optional reason/metadata and linkage to run/session/trace/experiment IDs.
 
 ## When to use it
 
-Use this package when a host needs offline quality checks or sampled live scoring without coupling scorers into core agent execution. Install it directly or through `@arnilo/prism-all`; installation does not attach scorers to runs.
+Use this package when a host needs offline quality checks or sampled live scoring without coupling scorers into core agent execution. Install it directly or through the `@arnilo/prism-core` family package; installation does not attach scorers to runs.
 
 ## Inputs / request
 
@@ -60,7 +60,7 @@ import {
   defineScorer,
   runExperiment,
   scoreRunLive,
-} from "@arnilo/prism-evals";
+} from "@arnilo/prism-core/governance/evals";
 
 const scorer = defineScorer({
   id: "contains-citation",
@@ -145,7 +145,7 @@ assertEvaluationThreshold(report, { minimumMean: 0.9, maximumFailures: 0 });
 Plan 043 adds `datasetFromRuns`: it turns recorded runs (production incident transcripts included) into dataset items in one call — resolve through `createPersistenceTraceResolver`, redact, map through an optional host `toItem`, and append as a **new immutable dataset version**. The prior version object is never mutated.
 
 ```ts
-import { datasetFromRuns, defineDataset } from "@arnilo/prism-evals";
+import { datasetFromRuns, defineDataset } from "@arnilo/prism-core/governance/evals";
 
 const result = await datasetFromRuns({
   runIds: ["run_9f2", "run_a71"],
@@ -169,16 +169,16 @@ Omit `toItem` and the default mapping is used: `input` = first user message, `ex
 - Feedback costs one bounded, owner-scoped query per curation batch (`store.feedback`); records are read id-only per the feedback linkage contract — scorer payloads are never copied. A feedback query failure (e.g. scope contract mismatch) omits `expected` instead of aborting the batch.
 - Every item field passes the host `redactor` after host mapping — fail closed: a redactor failure or an item over the frozen 4 MiB cap (`ERR_PRISM_EVAL_CURATE`) skips the run or aborts the append before anything is persisted. Cross-tenant runs are never readable (resolver ownership check → `ownership mismatch` skip).
 
-Prompt versions can ride the same primitives: [`assertPromptPromotion`](prompt-registry.md#eval-gated-promotion) in `@arnilo/prism-prompts` resolves two prompt versions, runs them through `runComparison`, and returns a `promote`/`hold` verdict with per-scorer aggregates and a bounded report — never applying the change itself.
+Prompt versions can ride the same primitives: [`assertPromptPromotion`](prompt-registry.md#eval-gated-promotion) in `@arnilo/prism-core/governance/prompts` resolves two prompt versions, runs them through `runComparison`, and returns a `promote`/`hold` verdict with per-scorer aggregates and a bounded report — never applying the change itself.
 
 ## Coding and browser adversarial evaluations (0.0.9)
 
 Release 0.0.9 ships curated network-free adversarial fixtures in package tests:
 
-- `@arnilo/prism-coding-agent` `eval-fixtures.test.ts`: safe native list vs shell, Git path/ref injection, dirty-tree rollback, unknown named-check failure, PR-handoff artifact completeness, and prompt-injection file content under read-only tools.
+- `@arnilo/prism-coding-tools/agent` `eval-fixtures.test.ts`: safe native list vs shell, Git path/ref injection, dirty-tree rollback, unknown named-check failure, PR-handoff artifact completeness, and prompt-injection file content under read-only tools.
 - `browser` `eval-fixtures.test.ts`: stale snapshot refs, side-effect approval, private/loopback/file deny, upload/download/screenshot policy, CSS/evaluate target rejection, and hostile accessible-name text.
 
-Fixtures reuse `@arnilo/prism-evals` (`defineDataset` / `defineScorer` / `scoreRun` / `assertEvaluationThreshold` / `serializeEvaluationReport`). Optional SWE-bench-compatible or live-browser harnesses remain host adapters — they are not default dependencies or quality claims. Protected real Docker/Playwright gates stay env-gated (`PRISM_TEST_DOCKER_SANDBOX`, `PRISM_LIVE_PLAYWRIGHT`) and never enter `sdk:ready`.
+Fixtures reuse `@arnilo/prism-core/governance/evals` (`defineDataset` / `defineScorer` / `scoreRun` / `assertEvaluationThreshold` / `serializeEvaluationReport`). Optional SWE-bench-compatible or live-browser harnesses remain host adapters — they are not default dependencies or quality claims. Protected real Docker/Playwright gates stay env-gated (`PRISM_TEST_DOCKER_SANDBOX`, `PRISM_LIVE_PLAYWRIGHT`) and never enter `sdk:ready`.
 
 ## PostgreSQL enterprise state (0.0.23)
 
@@ -214,7 +214,7 @@ The protected runner (`scripts/phase27-erp-journey.test.mjs`) carries the journe
 ### Hard-gate usage
 
 ```ts
-import { createErpInvariantScorers, erpInvariantDataset, scoreRun } from "@arnilo/prism-evals";
+import { createErpInvariantScorers, erpInvariantDataset, scoreRun } from "@arnilo/prism-core/governance/evals";
 
 const scorers = createErpInvariantScorers();
 const records = await scoreRun({

package/docs/extensions.md

@@ -140,9 +140,9 @@ await kernel.middleware.run("provider_request", { metadata: {} });
 - [Compaction and retry policies](compaction-and-retry.md): compaction strategy/retry policy contributions and `compaction`/`retry` middleware runtime behavior.
 - [LLM compaction package](compaction-llm.md): optional extension helper that registers a provider-backed compaction strategy.
 - [Observational memory compaction package](compaction-observational-memory.md): optional extension helper that registers an inert fast memory compaction strategy.
-- [Caveman behavior integration](caveman.md): optional `@arnilo/prism-caveman` upstream Caveman skills, commands, level injector, and session `caveman-level` persistence.
-- [Ponytail behavior integration](ponytail.md): optional `@arnilo/prism-ponytail` upstream Ponytail skills, commands, mode injector, and session `ponytail-mode` persistence.
-- [Impeccable behavior integration](impeccable.md): optional `@arnilo/prism-impeccable` upstream Impeccable skill and `load_skill` command.
+- [Caveman behavior integration](caveman.md): optional `@arnilo/prism-coding-tools/caveman` upstream Caveman skills, commands, level injector, and session `caveman-level` persistence.
+- [Ponytail behavior integration](ponytail.md): optional `@arnilo/prism-coding-tools/ponytail` upstream Ponytail skills, commands, mode injector, and session `ponytail-mode` persistence.
+- [Impeccable behavior integration](impeccable.md): optional `@arnilo/prism-coding-tools/impeccable` upstream Impeccable skill and `load_skill` command.
 - [Public contracts](public-contracts.md): `Extension`, `ExtensionAPI`, and contribution contract types.
 - [Credentials and redaction](credentials-and-redaction.md): secret-redaction behavior used for extension errors.
 

package/docs/forge-integration.md

@@ -2,7 +2,7 @@
 
 ## What it does
 
-`createGitHubForge` is an optional host-activated adapter in `@arnilo/prism-coding-agent` for the six **proven** GitHub operations: issue context read, authenticated push, pull-request create/update, review comments, and check/status retrieval, plus bounded handoff reconciliation. It is GitHub-first by freeze decision — there is no multi-forge generic abstraction, and no octokit dependency: HTTP uses Node's global `fetch` with a bounded streaming reader, timeout, and rate-limit backoff; push reuses the existing `BoundGitRunner` with the token injected via `GIT_CONFIG_*` environment variables (`http.extraHeader`) — never argv, never persisted, never in logs/events. Every mutation flows through Phase 8 approval (`ExecutionPolicy`) and Phase 7 `ToolEffectStore` idempotency keys; a retry after a completed call returns the existing record instead of duplicating the PR or comment.
+`createGitHubForge` is an optional host-activated adapter in `@arnilo/prism-coding-tools/agent` for the six **proven** GitHub operations: issue context read, authenticated push, pull-request create/update, review comments, and check/status retrieval, plus bounded handoff reconciliation. It is GitHub-first by freeze decision — there is no multi-forge generic abstraction, and no octokit dependency: HTTP uses Node's global `fetch` with a bounded streaming reader, timeout, and rate-limit backoff; push reuses the existing `BoundGitRunner` with the token injected via `GIT_CONFIG_*` environment variables (`http.extraHeader`) — never argv, never persisted, never in logs/events. Every mutation flows through Phase 8 approval (`ExecutionPolicy`) and Phase 7 `ToolEffectStore` idempotency keys; a retry after a completed call returns the existing record instead of duplicating the PR or comment.
 
 | Export | Purpose |
 | --- | --- |
@@ -18,7 +18,7 @@
 Use when a coding agent needs to open/update PRs, comment on reviews, push a branch with scoped credentials, or verify handoff state against GitHub before deciding the next step. Do not use as a general GitHub SDK, an auto-merge engine (`reconcileHandoff` never merges), or a replacement for host-owned App installation flows — the adapter resolves credentials through the host's `CredentialResolverSource`-compatible resolver and never stores them.
 
 ```ts
-import { createGitHubForge } from "@arnilo/prism-coding-agent";
+import { createGitHubForge } from "@arnilo/prism-coding-tools/agent";
 
 const forge = createGitHubForge({
   credentials: { name: "github", resolver: myCredentialResolver }, // App installation token preferred; PAT allowed
@@ -75,7 +75,7 @@ Every mutation result is recorded in the `effectStore` with a stable key derived
 ## Implementation example
 
 ```ts
-import { createGitHubForge } from "@arnilo/prism-coding-agent";
+import { createGitHubForge } from "@arnilo/prism-coding-tools/agent";
 
 const forge = createGitHubForge({
   credentials: { name: "github-app", resolver },

package/docs/graft.md

@@ -14,7 +14,7 @@ Use it when a host wants agents to locate code by architecture, callers, and cou
 - `"push"` — per-turn retrieval pack (pointers only) + first-turn orientation, injected automatically.
 - `"both"` — everything.
 
-Install optional peer `@nanonets/graft@^0.13.0` **or** pass `packageRoot`/`cliPath` explicitly. Pair with progressive disclosure: the `graft` skill body stays small; tool schemas carry the details. Graft complements indexed code search (`repository_search`): graph/semantic locators vs literal search — neither replaces the other.
+Install optional peer `@nanonets/graft@^0.16.0` **or** pass `packageRoot`/`cliPath` explicitly. Pair with progressive disclosure: the `graft` skill body stays small; tool schemas carry the details. Graft complements indexed code search (`repository_search`): graph/semantic locators vs literal search — neither replaces the other.
 
 Zero-code alternative (L0): hosts can skip this package entirely and let agents call `graft <command> --json` through their shell tool, optionally seeding context with graft's own generated instruction files. This package exists for native-tool ergonomics, budgeted subprocesses, session persistence, and push mode.
 
@@ -105,7 +105,7 @@ await kernel.load([
 - Import alone registers nothing (`sideEffects: false`); no timers, watchers, or network. The only child processes are budgeted graft CLI calls.
 - Retrieval happens in-process via Prism primitives (context provider, injector, tool_result middleware) — no external hook shims.
 - Ask result shape is parsed tolerantly (`nodes|results|matches|hits`) because graft is pre-1.0; formatters emit pointers (`title` + `file:line` + `[[wikilink]]`), never source bodies.
-- Not included in `@arnilo/prism-code`, `@arnilo/prism-sdk`, or the `prism-all` umbrella (deliberate opt-out, like Caveman/Ponytail) — opt-in install only.
+- Not included in `@arnilo/prism-coding-tools`, `@arnilo/prism-core`, or the `prism-all` umbrella (deliberate opt-out, like Caveman/Ponytail) — opt-in install only.
 - Multi-repo layouts work as upstream graft defines them (workspaces, submodules with `--follow-submodules`, sibling repos); point `projectDir` at the graft root that owns the target repo.
 
 ## Security and performance notes

package/docs/guardrails.md

@@ -76,7 +76,7 @@ Guardrails are callbacks supplied by the host. Prism does not discover, load, re
 
 ## Security and performance notes
 
-Optional `@arnilo/prism-policy` can record guardrail outcomes via `recordGuardrailDecision` (evidence refs only; see [Policy and audit](policy-and-audit.md)).
+Optional `@arnilo/prism-core/governance/policy` can record guardrail outcomes via `recordGuardrailDecision` (evidence refs only; see [Policy and audit](policy-and-audit.md)).
 
 Output buffering prevents blocked provider content from reaching subscribers, session entries, ledgers, parsers, delegation, or tools. Tool-output checks receive raw results but Prism discards blocked raw output before event, ledger, transcript, or MCP exposure. Redaction replaces exact known values only; it is not general secret detection. Parallel checks receive an abort signal, but callback code must honor it to stop in-flight work. Browser snapshots and page text from the `browser` subpath are untrusted external content: never allow them to modify tools, permissions, credentials, or policy. Browser mutations still require host `ExecutionPolicy`/approval; prompt-injection text in a page cannot grant upload/download release.
 

package/docs/host-security.md

@@ -26,17 +26,17 @@ Start from explicit host inputs. Do not let runtime code discover security state
 | Tool allow-list | active tools for this agent/session/run | `createToolRegistry`, `filterTools()`, `dispatchToolCall()` |
 | Tool argument rules | host validator | `AgentConfig.validator`, `RunOptions.validate`, `ToolValidator` |
 | Guardrail decisions | host callback allow/block/tripwire policy | `Guardrails`, `Guardrail`, `GuardrailError` |
-| Coding execution policy | path/command approval adapter | `ExecutionPolicy`, `@arnilo/prism-coding-security` |
+| Coding execution policy | path/command approval adapter | `ExecutionPolicy`, `@arnilo/prism-coding-tools/security` |
 | Remote media policy | public/default pinned DNS or explicit trusted transport | `SsrfPolicy`, `resolveMediaContentBlock()` |
 | Durable history | host database adapter | `SessionStore`, `assertSessionStoreConforms()` |
 | Durable audit | host ledger adapter | `RunLedger`, `redactRunLedgerRecord()` |
 | Telemetry | host OpenTelemetry SDK/exporter | metadata-only adapter, controlled metric labels, `onTraceReference` |
 | Durable interruption | host checkpoint + session stores, exact ownership | `RunOptions.runState`, `resumeAgentRun()`, `createAgentRunLifecycle()`, `createSecureAgent()` |
 | Extensions | explicit package imports only | `createExtensionKernel`, `ExtensionAPI` |
-| Remote agent/workflow API | host authentication + ownership mapping | `@arnilo/prism-server`, `createPrismHandler()` |
-| Authenticated identity | host `IdentityVerifier` → verified `AgentIdentity`; optional OIDC/JWKS reference adapter (`@arnilo/prism-credentials-node/oidc`, pinned issuer/audience/JWKS, fail closed) | [Agent identity](agent-identity.md), `assertIdentityActive`, `narrowIdentity` |
-| Policy decision audit | optional redacted ledger + host WORM sink | [Policy and audit](policy-and-audit.md), `@arnilo/prism-policy` |
-| Durable enterprise state | host PostgreSQL pool, TLS, exact owner/principal projection, migration/runtime database roles, backup and explicit cleanup schedule | [Enterprise PostgreSQL state](enterprise-postgres-state.md), `@arnilo/prism-enterprise-postgres` |
+| Remote agent/workflow API | host authentication + ownership mapping | `@arnilo/prism-core/runtime/server`, `createPrismHandler()` |
+| Authenticated identity | host `IdentityVerifier` → verified `AgentIdentity`; optional OIDC/JWKS reference adapter (`@arnilo/prism-core/credentials/node/oidc`, pinned issuer/audience/JWKS, fail closed) | [Agent identity](agent-identity.md), `assertIdentityActive`, `narrowIdentity` |
+| Policy decision audit | optional redacted ledger + host WORM sink | [Policy and audit](policy-and-audit.md), `@arnilo/prism-core/governance/policy` |
+| Durable enterprise state | host PostgreSQL pool, TLS, exact owner/principal projection, migration/runtime database roles, backup and explicit cleanup schedule | [Enterprise PostgreSQL state](enterprise-postgres-state.md), `@arnilo/prism-core/enterprise/postgres` |
 | MCP server exposure | host MCP auth + selected capability list | `createPrismMcpServer()`, `createPrismMcpWebHandler()` |
 
 ## Outputs / response / events
@@ -139,7 +139,7 @@ Wire those values where they matter: provider adapters receive the resolved cred
 - Redaction is exact known-secret replacement only. It is not arbitrary secret detection, entropy scanning, or DLP.
 - Known secrets must be passed into redactors before data is emitted or persisted. Redact again in host adapters if they transform records after Prism redaction.
 - OpenAI Realtime sessions require a stable host owner identifier, use header-only credentials, and bind to the server `session.created` id. Treat returned audio/transcripts as untrusted; use a `SecretRedactor`, retain finite event/byte/wall caps, and close on disconnect or an identity/budget breach.
-- Tool `parameters` metadata is not validated by default. Add a `ToolValidator`, use `createToolParameterValidator()` with a schema adapter, or install `@arnilo/prism-tool-validator-json-schema` before side effects. Its untrusted-schema adapter rejects non-local refs, forbidden keys/cycles/non-finite values and bounds bytes/depth/properties/keywords/refs plus its LRU cache before Ajv compilation; do not raise caps above documented hard limits.
+- Tool `parameters` metadata is not validated by default. Add a `ToolValidator`, use `createToolParameterValidator()` with a schema adapter, or install `@arnilo/prism-core/validation/json-schema` before side effects. Its untrusted-schema adapter rejects non-local refs, forbidden keys/cycles/non-finite values and bounds bytes/depth/properties/keywords/refs plus its LRU cache before Ajv compilation; do not raise caps above documented hard limits.
 - RAG `replaceSource()` only accepts a store with scoped `getBySource()` plus a real transaction; it stages bounded embeddings before mutation and otherwise fails closed. `deleteSource()` rechecks returned tenant/resource/corpus/source metadata. `createResourceDocumentLoader()` receives only a host-authorized `ResourceLoader`; `createWebFetchDocumentLoader()` never opens I/O and rejects local/private/IP-literal URLs before delegating to host-configured web-tools. HTML scripts/styles are stripped, PDF parsing has byte/page/time caps and rejects compressed PDFs.
 - RAG retrieval always emits `trust: { untrusted: true, inert: true, injectionCapable: true }` plus attributable citation provenance. Context blocks repeat this metadata and never gain tool authority. Host `Reranker`s see redacted finite candidates, are hard-capped by bytes/time/concurrency, must return only a permutation of candidate IDs, and cannot overwrite provenance/trust. Ingestion status errors are redacted; status storage/listing stays exact-scope and capped.
 - Treat embeddings as untrusted numeric input. `@arnilo/prism-memory` rejects empty, non-number, NaN, and infinite vectors before in-memory similarity, pgvector parameters, export, or rebuild; custom `Embedder`/`VectorStore` implementations must retain the same boundary. Memory entries carry consent/source/visibility; revoked/invisible entries never enter prompts, events, exports, or telemetry. `exportMemory()` additionally excludes consent-less legacy records regardless of recall mode and requires exact host identity equal to its tenant/resource/thread scope. Save rebuild cursors only in host-authorized storage; `rebuildIndex()` is one abortable capped page, never an implicit corpus job. `forget`/`applyRetention` are real bounded deletes.
@@ -149,19 +149,19 @@ Wire those values where they matter: provider adapters receive the resolved cred
 - AG-UI fields stay untrusted after schema validation. `input.project` returns host-selected messages/handoffs only; never merge state/tools/context/props into ownership, identity, permissions, provider options, or media policy. Apply Prism media SSRF/MIME bounds before resolution; output projectors are bounded allow-lists; interrupt edits deny rather than mutate persisted calls.
 - AG-UI MCP Apps requires negotiated `mcpApps`, exact proxy origin/auth, owned-run context, approval, one bridge, separate-origin sandbox (`allow-scripts allow-same-origin`), and no-wider CSP. Never execute HTML in host origin or retry a UI mutation; Task 4 adds recovery.
 - AG-UI A2A requires exact-origin verified client, host-owned task selection/correlation, explicit data/tool/A2UI projection, and reauthorized follow/cancel.
-- `@arnilo/prism-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-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-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-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.
+- `@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()`.
 - 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-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-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.
+- 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.
 - 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-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.
+- `@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.
 - Prefer `createExtensionKernel({ loadPolicy })` allow-list/signature checks before loading third-party extension packages.
 - Provider-owned auth/content/session/cache/security headers win over caller headers in adapters that merge headers.
 - Security checks are bounded explicit calls on the active path. Prism adds no hidden global middleware, background workers, watchers, network calls, or filesystem scans.
@@ -190,7 +190,7 @@ PostgreSQL TLS/network policy, MCP endpoint trust/credentials and egress policy
 ## Web research boundaries
 
 - Construct `@arnilo/prism-web-tools` with one host-selected Brave or Exa adapter; never expose adapter/provider/credential/schema selection to model arguments.
-- Construct `@arnilo/prism-work-tools` with host-pinned CLI binary + isolated `configDir` + verified `AgentIdentity` (M365 and/or GWS). Never pass model-built command strings, `login`/`setup`/`auth`/`schema`/`--debug`, or credentials in argv. Mutations require draft approval; external recipients and anonymous/`anyone` shares fail closed.
+- Construct `@arnilo/prism-core/integrations/work` with host-pinned CLI binary + isolated `configDir` + verified `AgentIdentity` (M365 and/or GWS). Never pass model-built command strings, `login`/`setup`/`auth`/`schema`/`--debug`, or credentials in argv. Mutations require draft approval; external recipients and anonymous/`anyone` shares fail closed.
 - Provider API origins are fixed exact HTTPS origins and redirects fail. Credentials resolve immediately before I/O; remote bodies and secrets are excluded from errors/results/telemetry.
 - Firecrawl targets reject userinfo, non-HTTP(S), private literals, and policy-denied hosts. Supply `validateUrl` for host DNS/rebinding/egress checks. Firecrawl performs remote retrieval, so Prism cannot pin target DNS after handoff.
 - Treat every snippet, highlight, Markdown byte, metadata field, and extracted JSON value as prompt-injection-capable untrusted data. Never elevate it into system instructions or let it modify tools, permissions, trust, credentials, routing, or extraction schema.
@@ -211,8 +211,8 @@ PostgreSQL TLS/network policy, MCP endpoint trust/credentials and egress policy
 ### 0.1.0 security evidence (plan 012 Task 6)
 
 - **Audit policy.** `npm audit --audit-level=moderate` is enforced in both `security.yml` and the `release.yml` supply-chain job (freeze-manifest `releasePolicy.auditLevelTarget`); recorded 0.1.0 tree: 0 vulnerabilities at every severity (317 locked dependencies, MCP SDK at the 1.30.0 fix baseline).
-- **Named threat-suites leg.** `npm run security:threat-suites` aggregates the Phase 8–11 conformance suites (durable-loop/HITL approval, coding sandbox/egress/forge, ACP protocol, OIDC/OPA/MCP-OAuth/OpenAPI/artifact) into one named 0.1.0 security evidence leg — same scripts as `npm test`, no rewrite; the Phase 7 tenant-isolation suite is its protected counterpart under `npm run test:postgres` (missing `PRISM_TEST_POSTGRES_URL` is a named blocked gate). The dev-inspector leg (`scripts/phase40-security.test.mjs`, plan 040 Task 5) exercises the `@arnilo/prism-dev` local playground through built public entrypoints: D1 non-loopback binds refuse before any listener exists (`ERR_PRISM_DEV_REMOTE_BIND`) and loopback is the only bindable surface; D2 the host redactor scrubs secret literals from server-rendered replay payloads; D3 replay selectors outside the `resolveRun` seam's ownership fail closed 404 and replay without a durable event_source is a documented 404, never a re-execution; D4 unknown decision outcome discriminants reject `400` without consuming a run version or executing the tool, and a valid `allow_once` applies exactly once.
-- **Dev-surface boundary (plan 040 Task 5).** The `@arnilo/prism-dev` inspector is a developer-time tool: loopback-only by default, non-loopback requires an explicit programmatic `remoteAuthorize` callback plus a real authorizer (the CLI/bin offers no remote-bind flag at all), and it must never be the production API boundary (that stays `@arnilo/prism-server` under host authorization). It carries no credential storage — the host agent config owns credentials and the inspector never reads environment secrets; rendered tool args/results pass the host redactor on both the live and replay paths, and HITL decision resume composes the core `createAgentRunLifecycle` validation (fail-closed on unknown discriminants/versions/runs).
+- **Named threat-suites leg.** `npm run security:threat-suites` aggregates the Phase 8–11 conformance suites (durable-loop/HITL approval, coding sandbox/egress/forge, ACP protocol, OIDC/OPA/MCP-OAuth/OpenAPI/artifact) into one named 0.1.0 security evidence leg — same scripts as `npm test`, no rewrite; the Phase 7 tenant-isolation suite is its protected counterpart under `npm run test:postgres` (missing `PRISM_TEST_POSTGRES_URL` is a named blocked gate). The dev-inspector leg (`scripts/phase40-security.test.mjs`, plan 040 Task 5) exercises the `@arnilo/prism-coding-tools/dev` local playground through built public entrypoints: D1 non-loopback binds refuse before any listener exists (`ERR_PRISM_DEV_REMOTE_BIND`) and loopback is the only bindable surface; D2 the host redactor scrubs secret literals from server-rendered replay payloads; D3 replay selectors outside the `resolveRun` seam's ownership fail closed 404 and replay without a durable event_source is a documented 404, never a re-execution; D4 unknown decision outcome discriminants reject `400` without consuming a run version or executing the tool, and a valid `allow_once` applies exactly once.
+- **Dev-surface boundary (plan 040 Task 5).** The `@arnilo/prism-coding-tools/dev` inspector is a developer-time tool: loopback-only by default, non-loopback requires an explicit programmatic `remoteAuthorize` callback plus a real authorizer (the CLI/bin offers no remote-bind flag at all), and it must never be the production API boundary (that stays `@arnilo/prism-core/runtime/server` under host authorization). It carries no credential storage — the host agent config owns credentials and the inspector never reads environment secrets; rendered tool args/results pass the host redactor on both the live and replay paths, and HITL decision resume composes the core `createAgentRunLifecycle` validation (fail-closed on unknown discriminants/versions/runs).
 - **Supply-chain negative fixtures.** `scripts/release-gate.test.mjs` verifies the tarball deny list rejects tampered content (plans/reviews/maps/tests), unexpected file types and credential material (native binaries, `.pem`/`.key`/`.p12`), and that a provenance flag suppressed in CI is detectable in the `release.mjs` publish dry-run arguments (`--provenance` mandatory under `GITHUB_ACTIONS`, never claimed on local OIDC-less publishes).
 - **Mandatory gate stack.** CodeQL/SAST, PR dependency review (fail on high), secret scan (source + unpacked tarballs), SPDX SBOM + license policy, tarball allow/deny content checks, and provenance (npm OIDC + GitHub build attestations on tarballs and SBOM) all run in `security.yml`/`release.yml`; evidence for the 0.1.0 tree is recorded in [0.1.0 readiness](0.1.0-readiness.md).
 - **CodeQL query suite.** `.github/codeql/codeql-config.yml` selects the `security-extended` suite for `javascript-typescript` (with the default suite) on push/PR/schedule in `security.yml` (10-minute job bound; measured runtime ~3m22s on the audited SHA, last successful main run `33059128198`). The ignore list covers only generated `dist`, `node_modules`, and release/security artifact directories — first-party packages, threat suites, and fixtures that ship or execute are always scanned, so new alerts enter the same plan-038 ledger/remediation loop (config + guardrails asserted in `scripts/phase38-codeql-regression.test.mjs`). Local Task 6 gates (typecheck/lint/format/threat suites/audit/secret scan/SBOM) pass on the remediations; GitHub `state=open` stays non-zero until those remediations are the analyzed head. Groups G (`js/insufficient-password-hash` on RFC 7636 S256) and H (`js/incomplete-url-substring-sanitization` on a negative docs assertion) are maintainer-reviewed false positives queued for narrow dismissal after that analyze, not code changes.

package/docs/image-generation.md

@@ -0,0 +1,129 @@
+# Image generation and editing
+
+## What it does
+
+`ImageGenerationProvider` is the provider-neutral image contract: `generate`
+(prompt→image[s] with size/format/quality/count options) and `edit`
+(image+mask+prompt, reusing the existing `ImageContent` binary content parts).
+Results are `Uint8Array` bytes plus provenance — hosts own persistence; no
+disk writes, no URL-only contract. Adapters ship in
+[`@arnilo/prism-providers/openai`](providers/openai.md) (`/v1/images/generations`,
+`/v1/images/edits`, always `b64_json`) and
+[`@arnilo/prism-providers/alibaba`](providers/alibaba.md) (DashScope wanx async
+task API); offline conformance runs via `runImageGenerationConformance` from
+`@arnilo/prism/testing/provider-conformance`.
+
+## When to use it
+
+Use it when the host owns image storage and lifecycle and wants portable
+generate/edit calls with typed errors. Do not use it for image *input* to a chat
+model — that is the existing `ImageContent` content part on
+[`ModelConfig`](public-contracts.md) — and do not use the Alibaba adapter for
+edits (DashScope has no first-party image-edit route; it rejects with
+`unsupported_operation`).
+
+## Inputs / request
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `model` | `string` | e.g. `gpt-image-1` (OpenAI), `wanx2.1-t2i-turbo` (DashScope). |
+| `prompt` | `string` | Non-empty, within the provider cap (OpenAI 32,000 chars, wanx 800). |
+| `images` / `mask` | `ImageContent[]` / `ImageContent?` (edit) | Base64 `data` parts decode inline; `url` parts resolve through `pinnedFetch` (SSRF-guarded, DNS-pinned, byte-bounded). |
+| `size` / `format` / `quality` / `count` | `string?` / `string?` / `string?` / `number?` | Provider-defined vocabulary (`1024x1024`, `png`, `standard`/`hd`, 1–10 OpenAI / 1–4 wanx). |
+| `signal` | `AbortSignal?` | Cancellation; observed by the adapter transport and the DashScope poll loop. |
+
+Adapter options: `apiKey` (`CredentialValueSource` — the existing credential
+seam, resolved per call and redacted from errors), `baseUrl`, `fetch` (inject a
+fake transport for offline tests), `fetchUrl` (inject a result/input-image
+downloader; defaults to `pinnedFetch`), `headers`, and `maxImageBytes`.
+
+## Outputs / response / events
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `images` | `GeneratedImage[]` | One entry per generated image, in provider order. |
+| `images[].bytes` | `Uint8Array` | Decoded image bytes (one allocation per image; no re-encode loops). |
+| `images[].mimeType` | `string` | e.g. `image/png` (from the provider's `output_format` or the request format). |
+| `images[].provider` / `.model` | `string` | Preserved provenance — hosts can attribute stored output. |
+| `images[].url` / `.revisedPrompt` | `string?` | Provider-native passthrough when returned. |
+| `usage` | `Usage?` | Provider-reported usage when available. |
+
+Failures throw `ImageGenerationError` with a stable `code`: `empty_input`
+(no prompt / edit without image parts), `input_too_large` (prompt or count over
+cap, over-ceiling input image), `unsupported_operation` (edit on providers
+without an edit route), `request_failed` (non-2xx, failed task, failed download,
+secret-redacted message), `response_malformed` (missing `b64_json`, invalid
+base64, no result URLs), `unsupported_model` (via `assertImageGenerationSupported`
+when the host checks `ModelCapabilities.imageGeneration`).
+
+## Request/response example
+
+```json
+{ "model": "gpt-image-1", "prompt": "a red cube", "size": "1024x1024", "n": 1, "response_format": "b64_json" }
+```
+
+## Implementation example
+
+```ts
+import { createOpenAIImageGenerationProvider } from "@arnilo/prism-providers/openai";
+import { createAlibabaImageGenerationProvider } from "@arnilo/prism-providers/alibaba";
+import { runImageGenerationConformance } from "@arnilo/prism/testing/provider-conformance";
+
+const images = createOpenAIImageGenerationProvider({ apiKey: process.env.OPENAI_API_KEY });
+const { images: generated } = await images.generate({ model: "gpt-image-1", prompt: "a red cube", size: "1024x1024" });
+// generated[0] = { bytes: Uint8Array, mimeType: "image/png", provider: "openai", model: "gpt-image-1" }
+
+const edited = await images.edit({
+  model: "gpt-image-1",
+  prompt: "make it blue",
+  images: [{ type: "image", data: base64Png, mimeType: "image/png" }],
+});
+
+// DashScope wanx: submit + poll + download, wrapped in one call:
+const alibaba = createAlibabaImageGenerationProvider({ apiKey: process.env.DASHSCOPE_API_KEY });
+const wanx = await alibaba.generate({ model: "wanx2.1-t2i-turbo", prompt: "a red cube" });
+
+// Offline conformance (fake transport, no network):
+await runImageGenerationConformance({
+  provider: createOpenAIImageGenerationProvider({ apiKey: "sk-test", fetch: fakeFetch }),
+  model: "gpt-image-1",
+  maxPromptChars: 32000,
+  sample: { prompt: "a red cube", count: 1 },
+});
+```
+
+## Extension and configuration notes
+
+- Implement `ImageGenerationProvider` for other vendors; the contract is
+  structural — no base class, no registry. Providers without an edit route
+  reject `edit` with `ImageGenerationError("unsupported_operation")` rather
+  than pretending.
+- Models declare support with `capabilities.imageGeneration`; hosts gate with
+  `modelSupportsImageGeneration` / `assertImageGenerationSupported`, mirroring
+  the embeddings/speech guard pattern.
+- The DashScope adapter owns the async-task lifecycle (submit with
+  `X-DashScope-Async: enable`, poll until terminal status, download result
+  URLs); `pollIntervalMs` and `timeoutMs` tune the loop, and the abort signal
+  is honored between polls.
+
+## Security and performance notes
+
+- API keys resolve through the existing `CredentialValueSource` seam and are
+  redacted from every thrown error (`redactSecrets`); no new secret paths.
+- All URL fetches (edit inputs, DashScope result images) go through
+  `pinnedFetch` — DNS-pinned, SSRF-guarded, byte-bounded (`maxImageBytes`,
+  25 MiB default); responses over the ceiling reject instead of buffering.
+- Prompts and image bytes are never logged; error messages carry status and a
+  redacted body only. The contract never touches local disk — bytes return to
+  the host.
+- Base64 payloads decode exactly once per image; response mapping allocates
+  per-image and nothing else.
+
+## Related APIs
+
+- [Multimodal content](public-contracts.md): `ImageContent` parts — the edit
+  input vocabulary and the chat image-input path.
+- [Provider conformance](provider-conformance.md): `runImageGenerationConformance`
+  and the offline conformance matrix.
+- [Provider packages](provider-packages.md): subpath import rules for
+  `@arnilo/prism-providers/openai` and `@arnilo/prism-providers/alibaba`.