@arnilo/prism 0.6.0 → 0.7.0

package/docs/web-tools.md

@@ -67,7 +67,7 @@ Default/hard limits: query 4/16 KiB; results 10/20; URLs 5/20; request 256 KiB/1
 
 ## Security and performance notes
 
-Provider credentials never enter tool schemas/results, prompts, telemetry, URLs, or errors. Error text excludes remote bodies. Search snippets, Markdown, and extracted JSON are prompt-injection-capable data: never concatenate them into system instructions or use them to modify tools, permissions, credentials, trust, routing, or schemas. Firecrawl fetches target URLs remotely; Prism cannot claim target DNS pinning after handoff. Use controlled host fetch when that guarantee is required.
+Provider credentials never enter tool schemas/results, prompts, telemetry, URLs, or errors. Error text excludes remote bodies. Search snippets, Markdown, and extracted JSON are prompt-injection-capable data: never concatenate them into system instructions or use them to modify tools, permissions, credentials, trust, routing, or schemas. `snapshotWebEvidence({ url, body, provider })` hashes an already-fetched body into the shared `ArtifactCitation` evidence shape; it does not refetch and does not store credentials. Firecrawl fetches target URLs remotely; Prism cannot claim target DNS pinning after handoff. Use controlled host fetch when that guarantee is required.
 
 Default tests use injected fake fetch and make no public request. Restricted smoke: `PRISM_LIVE_WEB=1 npm run test:live -w @arnilo/prism-web-tools` plus least-privilege provider environment credential. Prefer the [`browser`](browser-automation.md) subpath over ordinary public retrieval; use browser automation only for interactive/authenticated/JavaScript-heavy work behind a host egress proxy. Arbitrary HTML execution, model-selected providers, automatic OAuth forwarding, and generic web/MCP passthrough are unsupported.
 
@@ -77,4 +77,5 @@ Default tests use injected fake fetch and make no public request. Restricted smo
 - [Credential storage](credential-storage.md): explicit resolver composition and environment mapping.
 - [Host security](host-security.md): SSRF, untrusted-content, and secret boundaries.
 - [MCP tools](mcp-tools.md): hardened prototype path for official vendor MCP servers.
+- [Work artifacts and review](work-artifacts-and-review.md): `snapshotWebEvidence` produces shared citation evidence from an already-fetched body.
 - [Performance and resource limits](performance.md): operational ceilings and benchmark evidence.

package/docs/work-artifacts-and-review.md

@@ -2,7 +2,7 @@
 
 ## What it does
 
-`@arnilo/prism-core/runtime/server` ships a durable artifact co-work review service (Phase 9 / 0.0.14): authorized attach of source/output references with MIME/hash/version, producer-run attribution, citations/data sources, and preview metadata; revision comparison; reviewer approve/reject (request-changes) with last-validated recovery; and authorized, expiring delivery links. Core (`@arnilo/prism`) exports artifact **types only** (`ArtifactRecord`, `ArtifactRevision`, `ArtifactApproval`, `ArtifactDeliveryToken`, approval state `pending | approved | rejected`). Prism persists bounded metadata, revisions, approvals, and delivery references over the existing versioned checkpoint store — **never file bodies**; hosts own blob storage and rendering.
+`@arnilo/prism-core/runtime/server` ships a durable artifact co-work review service: authorized attach of source/output references with MIME/hash/version, producer-run attribution, citations/data sources, and preview metadata; revision comparison; reviewer approve/reject (request-changes) with last-validated recovery; and authorized, expiring delivery links. Citations may carry shared evidence fields (`sourceId`, `revision`, `contentHash`, `retrievedAt`, `excerpt`, `span`, `tenantId`, `support`). Approve stamps `evidenceDigest` over those identity tuples. Core (`@arnilo/prism`) exports artifact types plus `checkCitationIntegrity` / `citationBindingDigest` / `approvalEvidenceIntact`. Prism persists bounded metadata, revisions, approvals, and delivery references over the existing versioned checkpoint store — **never file bodies**; hosts own blob storage and rendering. Integrity is existence/hash/span/ACL only; `support` is an optional host verdict, not proof.
 
 ## When to use it
 
@@ -34,8 +34,8 @@ Every operation input carries `ownership` (from host `authorize`, never request
 | `list` | Ownership/thread-scoped `PersistencePage<ArtifactRecord>` |
 | `get` | `ArtifactRecord` |
 | `revise` | `ArtifactRecord` with an appended revision (new revision resets state to pending) |
-| `compare` | `{ artifactId, from, to, changed: { hash, mime, uri, citations } }` — hash+metadata only |
-| `approve` / `reject` | `ArtifactRecord`; approve advances `lastValidatedVersion`, reject never clears it |
+| `compare` | `{ artifactId, from, to, changed: { hash, mime, uri, citations } }` — hash+metadata only; structural Office diffs use `diffDocument` |
+| `approve` / `reject` | `ArtifactRecord`; approve advances `lastValidatedVersion` and stamps `evidenceDigest`; reject never clears last-validated |
 | `lastValidated` | The last approved `ArtifactRevision` (fails closed before any approval) |
 | `deliveryLink` | `{ link, token }` — signed expiring `ArtifactDeliveryToken` |
 
@@ -87,7 +87,7 @@ export const handler = createArtifactHandler({ service: artifacts, authorize: ho
 
 - Every operation requires authenticated identity + thread ownership derived from host `authorize`; cross-ownership access fails closed as `not_found` (never leaks existence).
 - Concurrent reviewer conflicts resolve via checkpoint CAS (`expectedVersion`); the loser gets a retryable `conflict` and no approval is lost or duplicated. A throw before commit persists nothing, so failed updates roll back.
-- Local filesystem paths are rejected in `uri`/citations (`file:`, absolute, or drive paths); records are redacted before persist and on response, so paths/secrets/document-private data never enter records, events, or exports.
+- Local filesystem paths are rejected in `uri`/citations (`file:`, absolute, or drive paths); records are redacted before persist and on response, so paths/secrets/document-private data never enter records, events, or exports. Citation evidence is untrusted/inert: hosts pass already-retrieved snapshots into `checkCitationIntegrity` (no URL refetch, no persisted presigned credentials). A live source hash/revision/ACL change fails integrity even when a semantic judge scores the prose 1.0.
 - Frozen caps (default / hard): artifacts per thread 64/256; revisions per artifact 32/128; record 8/64 KiB; preview 16/64 KiB; citations 32/128 and 2/8 KiB each; MIME 128/512 B; hash 256/1 KiB; compare exactly 2 revisions; delivery TTL 5 min/24 h; delivery token 4/16 KiB. Raising the revision cap may require raising `recordBytes` (aggregate backstop).
 - Compare is hash+metadata-bounded (hosts render content); no file bodies are persisted or transferred. With a wired body store, bodies live in the host's object store and are streamed through the adapter (bounded by `maxBodyBytes` 64 MiB/512 MiB, concurrent transfers 4/16, presign TTL 10 min/24 h); object-store outages surface typed `ERR_PRISM_S3_*` / `ERR_PRISM_ARTIFACT_BODY_*` errors, never silent success.
 
@@ -95,6 +95,14 @@ export const handler = createArtifactHandler({ service: artifacts, authorize: ho
 
 `@arnilo/prism-coding-tools/agent` composes over this service for the coding patch review workflow: `createCodingPatchReviewManifest` builds a bounded manifest (repository/worktree identity, base/head, patch digest, changed paths, diffstat, check and diagnostic summaries) and returns a structural `ArtifactAttachInput` whose `preview.review` embeds the manifest and whose `hash` is the patch SHA-256; `assertCodingPatchAccepted` derives `pending|accepted|rejected|superseded` from the returned `ArtifactRecord` by binding to the exact artifact revision, digest, and identity — any patch/repository/worktree/base/head change supersedes a prior acceptance (a newer revision attached after approval makes the old acceptance stale and refused). Decisions never apply/commit/push/merge; the manifest never embeds a raw patch body. Full contract: [Coding review and diagnostics](coding-review-and-diagnostics.md).
 
+## Business action drafts and editable approvals (0.7.0)
+
+Business tools (e.g. mail, calendar, documents in `@arnilo/prism-core/integrations/work`) record mutations through durable `WorkDraftStore` drafts before execution. Human reviewers can approve, deny, or edit draft payloads directly:
+- AG-UI clients advertise and send `approveWithEdits` with revised arguments (`editedArgs`/`modifiedArguments`).
+- The server resume endpoint accepts `{ decision: "approve", modifiedArguments: { ... } }` under CAS `expectedVersion`.
+- If arguments are modified, a new draft revision is created with bumped revision number and payload digest. The previous revision's approval is invalidated and the mutation requires approval for the revised content.
+- Untyped/malformed edits, recipient escalation, schema violations, or stale CAS versions fail closed.
+
 ## Live probe (plans/064 Task 9)
 
 The S3 artifact-body store has an operator-gated live probe against a real S3-compatible endpoint (use a throwaway bucket):
@@ -115,3 +123,5 @@ Probes: put → get (hash + size verified), presigned delivery URL with `X-Amz-S
 - [Policy and audit](policy-and-audit.md): `onDecision` events bridge here for an auditable review ledger.
 - [Host security](host-security.md): identity/ownership, redaction, and expiring-link boundaries.
 - [Frontend interoperability (AG-UI and ACP)](ag-ui.md): projects artifact progress/approval/download-link as redacted co-work events over the durable-resume stream.
+- [Documents, spreadsheets, and presentations](documents.md): `diffDocument` for structural paragraph/table/cell/slide review.
+- [Evaluations](evaluations.md): `createCitationIntegrityScorer` invariant over `environment.citations`.

package/docs/work-connectors.md

@@ -6,7 +6,7 @@ Least-privilege Microsoft 365 and Google Workspace connectors live in `@arnilo/p
 
 1. **Host-pinned binary** — Prism never downloads or shells an untrusted CLI path.
 2. **Hard-coded argv templates** — models choose typed tool args; they never supply command strings.
-3. **Draft-then-approve** — mutations create a draft; side effects run only after host approval.
+3. **Draft-then-approve & durable resumption** — mutations create a draft with tracked revisions and payload digests; side effects run only after host approval binds to that exact revision; durable checkpoint persistence survives process restart.
 4. **Idempotent retries** — `IdempotencyStore` keyed by identity + operation key.
 5. **Isolated config** — per-identity `configDir` (CLI `HOME`); no credential argv.
 6. **Shared result shapes** — mail/calendar/file/task list/get tools normalize onto `WorkMailMessage` / `WorkCalendarEvent` / `WorkFileItem` / `WorkTaskItem` without hiding provider-specific ops.
@@ -23,6 +23,8 @@ See [Work tools](work-tools.md). Adapter: `createGoogleWorkspaceCliAdapter` / su
 
 Uses [`@googleworkspace/cli` (`gws`)](https://github.com/googleworkspace/cli): `gmail users messages list|get`, `gmail +send`, `calendar events list|insert`, `drive files list|create`, `drive permissions create`, `tasks tasks *`. Docs/Sheets/Slides create remain capability-gated. Discovery `schema` and `auth`/`login`/`setup` are forbidden from Prism argv.
 
+Drive **knowledge synchronization** (RAG import of file text + host-mapped ACL via `changes.list`) is not this CLI adapter. Use `createGoogleDriveConnector` / `syncKnowledge` from `@arnilo/prism-memory/rag` — see [Knowledge synchronization](knowledge-sync.md).
+
 ## Scoped OAuth establishment (0.0.14)
 
 Hosts establish, refresh, and revoke scoped OAuth credentials for these workloads through the existing `OAuthProvider` / credential-store seams (`@arnilo/prism-core/credentials/node`): `createMicrosoft365OAuthProvider` / `createGoogleWorkspaceOAuthProvider` (PKCE + device code), least-privilege scope bundles per capability (`resolveMicrosoft365Scopes` / `resolveGoogleWorkspaceScopes`, read vs mutation). Connectors consume a per-identity token via a late-bound `tokenProvider` injected as an env var — never argv, never model context; revocation fails closed. See [Credential storage](credential-storage.md) and [Work tools](work-tools.md).

package/docs/work-tools.md

@@ -1,6 +1,6 @@
 # Work tools
 
-Optional `@arnilo/prism-core/integrations/work` package: identity-scoped Microsoft 365 and Google Workspace connectors. Host-pinned CLI binaries only; hard-coded `execFile` argv templates; draft-then-approve mutations; side-effect idempotency; shared mail/calendar/file/task result shapes.
+Optional `@arnilo/prism-core/integrations/work` subpath: identity-scoped Microsoft 365 and Google Workspace connectors. Host-pinned CLI binaries only; hard-coded `execFile` argv templates; draft-then-approve mutations; side-effect idempotency; shared mail/calendar/file/task result shapes.
 
 ## When to use
 
@@ -9,7 +9,7 @@ Use when agents must read or mutate tenant mail/calendar/files/tasks through the
 ## Install
 
 ```bash
-npm install @arnilo/prism-core/integrations/work
+npm install @arnilo/prism-core
 # host separately:
 #   npm i -g @pnp/cli-microsoft365
 #   npm i -g @googleworkspace/cli
@@ -87,9 +87,19 @@ Verified against [`@googleworkspace/cli` / `gws`](https://github.com/googleworks
 
 Startup: M365 `version --output json`; GWS `--version`. Forbidden: `login`, `setup`, `auth`, `schema`, `doctor`, `--debug`, `--verbose`, credentials in argv, anonymous share, model-supplied command strings / free-form Discovery.
 
-### Draft → approve → execute
+### Draft → approve → execute (0.7.0, R02)
 
-Mutation tools (`*_mail_draft_send`, `*_draft_*`) create an in-adapter draft and return `{ status: "pending_approval", draftId }` until `approval.isApproved` is true.
+Mutation tools (`*_mail_draft_send`, `*_draft_*`) create an in-adapter draft and return `{ status: "pending_approval", draftId, revision, payloadDigest }` until the host approval gate grants permission.
+
+In Prism 0.7.0, draft lifecycles are durably managed:
+
+- **Exact revision binding**: Every draft carries an integer `revision` (starts at 1) and a deterministic canonical `payloadDigest` (`sha256:<hex>`). Approvals bind strictly to `{ draftId, revision, payloadDigest, identityKey, approvedAt, expiresAt, policyRevision }`.
+- **Durable persistence across restarts**: When adapters are configured with `checkpoints: CheckpointStore` (e.g. `createPostgresEnterpriseState({ pool }).checkpoints` or `createMemoryCheckpointStore()`), drafts are stored under namespace `prism.work.draft`. Drafts survive process restarts; a worker process can resume an exact draft revision approved in a prior process or via a delayed human-in-the-loop review.
+- **Edits invalidate approval**: Any mutation or update to a draft increments `revision`, recalculates `payloadDigest`, clears any previous `approval`, and resets `status` to `pending_approval`. Prior approvals cannot execute a modified draft.
+- **Resuming approved drafts**: Mutation tools accept `{ draftId, revision }` without requiring callers to re-supply the full payload. The tool loads the stored draft, validates approval status and digest, reauthorizes immediately before execution, and executes the effect.
+- **Idempotent duplicate approvals**: Re-approving an approved draft with the same approval object is idempotent. Submitting an approval with a mismatched revision or payload digest is rejected with `ERR_PRISM_WORK_DRAFT_STALE` or `ERR_PRISM_WORK_DRAFT_DIGEST`.
+- **Ambiguous failure handling**: If a connector call fails ambiguously after dispatch, both the idempotency record and the draft are marked `unknown`. Re-running with that draft ID or idempotency key fails closed (`ERR_PRISM_WORK_IDEMPOTENCY_UNKNOWN`) and never auto-replays without explicit operator reconciliation.
+- **Optional body offloading**: Supplying `bodies: ArtifactBodyStore` automatically stores large draft message/file bodies in the object store with an `ArtifactBodyRef` recorded on the draft metadata.
 
 ### Durable idempotency (0.0.23)
 

package/docs/workflows.md

@@ -20,6 +20,9 @@ Primary exports:
 | `defineSaga` / `runSaga` / `resumeSaga` | Bounded linear durable forward steps, reverse compensation, unknown-outcome reconciliation, lease fencing, and manual resolution over existing checkpoint/lease stores |
 | `createWorkflowSchedules` | Explicit ownership-scoped one-time/interval/host-calculated schedules over existing checkpoint/lease stores |
 | `createProactiveScheduleCapabilities` | Scoped, expiring, revocable capability tokens that enable proactive schedules; revocation stops firing fail-closed |
+| `serializeWorkflowGraph` / `collectWorkflowGraphs` | Pure JSON serialization of workflow DAGs (`WorkflowGraphView`) without functions/closures; collect nested graphs |
+| `workflowGraphToMermaid` / `workflowGraphToDot` | Deterministic Mermaid flowchart and Graphviz DOT exporters with node shapes by kind and label escaping |
+| `projectWorkflowGraphRun` / `createWorkflowGraphRunFolder` | Run overlay view (`WorkflowGraphRunView`) from checkpoints, timelines, or live event stream |
 
 Included through the `@arnilo/prism` / `@arnilo/prism-core` family packages; installing them does not start workflows. Interactive TUI is out of scope (C-012 deferred).
 
@@ -106,7 +109,7 @@ Every node receives bounded `ctx.state`, `ctx.stateVersion`, and async `ctx.upda
 
 `replayWorkflow(workflow, { sourceRunId, fromNodeId, runId? }, options)` requires a succeeded source/node, creates a new checkpoint, copies terminal evidence outside the selected node's downstream closure, restores selected-node pre-state, and records `{ sourceRunId, fromNodeId, rootRunId, depth }`. Source evidence is untouched. Copying any prior nested/tool approval is rejected; replay from that approval node or earlier so Phase 8 approval executes again.
 
-`createWorkflowCoordinator({ coordinatorId, workflows, checkpoints, leases, ... })` polls queued/running checkpoints with bounded pages, atomically claims each run, renews its lease, and aborts/fences work after lease loss. Key controls: `leaseTtlMs` (default 30s), `renewalIntervalMs` (default TTL/3), `pollIntervalMs` (default 1s), `maxConcurrentRuns` (default 4), and `pageSize` (default 100, maximum 500).
+`createWorkflowCoordinator({ coordinatorId, workflows, checkpoints, leases, ... })` polls queued/running checkpoints with bounded pages, atomically claims each run, renews its lease, and aborts/fences work after lease loss. Key controls: `leaseTtlMs` (default 30s), `renewalIntervalMs` (default TTL/3), `pollIntervalMs` (default 1s), `maxConcurrentRuns` (default 4), and `pageSize` (default 100, maximum 500). Optional `admission` wraps claims: cursor wrap across pages (default 4 pages/poll, hard 16) so a noisy first page cannot starve later tenants; `perTenant` / `perClass` cap concurrent claims on that worker; `deadlineMs` skips stale `createdAt`; `drain` stops new claims while draining and aborts in-flight after `snapshot().expired`. Workload class is `metadata.workloadClass` (`^[a-z][a-z0-9_-]{0,31}$`, else `default`). `onMetric` labels are `outcome` + `class` only — never tenant or run ids. This is not a second scheduler.
 
 `defineSaga({ id, revision, steps })` validates a bounded linear definition. Each step supplies `run`, `compensate`, and `reconcile`; handlers receive a stable tenant-scoped `operationId`, redacted bounded input/output, prior outputs, and an abort signal. `runSaga(definition, { checkpoints, leases, ownerId, tenantId, runId?, input?, maxAttempts?, leaseTtlMs?, redactor?, onEvent? })` stores a surrogate workflow checkpoint through `WorkflowCheckpointAdapter`, acquires a fenced `LeaseStore` lease, and advances one cursor at a time. `resumeSaga` takes over an expired run; it never replays durably succeeded steps. Forward or compensation handlers mark ambiguous failures with `unknown: true` (or `ERR_PRISM_SAGA_UNKNOWN`), and `reconcile` must return `succeeded`, `failed`, or `unknown` before retry.
 
@@ -404,6 +407,70 @@ For a single bounded refinement, prefer `loopNode`. Keep this host-loop pattern
 - Agent exclusivity is per session: one active `run()` at a time, same as core.
 - Saga definitions remain host code and only their revision, ordered step IDs, bounded JSON snapshots, cursors, attempt counters, and redacted error/provenance metadata are persisted. The surrogate workflow checkpoint namespace is private to the package.
 
+## Graph serialization, Mermaid, DOT, and run overlay
+
+Workflows can be converted to JSON view-models and visualization formats without executing them or shipping JS functions:
+
+```ts
+import {
+  collectWorkflowGraphs,
+  createWorkflowGraphRunFolder,
+  projectWorkflowGraphRun,
+  serializeWorkflowGraph,
+  workflowGraphToDot,
+  workflowGraphToMermaid,
+} from "@arnilo/prism-core/runtime/workflows";
+
+// 1. Pure static graph view (JSON-serializable)
+const view = serializeWorkflowGraph(workflow);
+// view.nodes: [{ id: "stepA", kind: "function", label: "stepA" }, ...]
+// view.edges: [{ from: "stepA", to: "stepB", kind: "always" }, ...]
+
+// 2. Export to Mermaid flowchart
+const mermaid = workflowGraphToMermaid(view);
+// flowchart TD
+//   stepA["stepA"]
+//   stepB["stepB"]
+//   stepA --> stepB
+
+// 3. Export to Graphviz DOT
+const dot = workflowGraphToDot(view);
+
+// 4. Project run state overlay from checkpoint or timeline
+const overlay = projectWorkflowGraphRun(view, checkpoint);
+// overlay.nodes[0].run?.status -> "succeeded" | "failed" | "running" | ...
+
+// 5. Incremental live folder for WebSocket/SSE cockpits
+const folder = createWorkflowGraphRunFolder(view);
+for await (const event of eventBus.subscribe()) {
+  folder.push(event);
+  const live = folder.snapshot();
+}
+
+// 6. Collect nested workflow graphs by ID
+const graphs = collectWorkflowGraphs(hierarchicalWorkflow);
+// Map with parent and child workflow views
+```
+
+### Graph view-model (`WorkflowGraphView`)
+
+- `schemaVersion`: 1
+- `workflowId`, `revision`, `definitionHash`: matches definition
+- `nodes`: deterministically sorted array of `WorkflowGraphNode` with `id`, `kind`, `label`, `metadata`, `nestedWorkflowId`, `loop`
+- `edges`: deterministically sorted array of `WorkflowGraphEdge` with `from`, `to`, `kind` (`"always" | "then" | "else"`)
+- Closures and functions (`when`, `execute`, `map`, `reduce`) are **omitted** by design so the view is safe for JSON wire transfer and audit logging.
+
+### Visualization & escaping
+
+- `workflowGraphToMermaid()` assigns distinct shapes by node kind: diamond for `conditional`, hexagon for `loop`, stadium for `agent`, subroutine for `workflow`, rounded for `tool`, box for `function`.
+- Mermaid and DOT exporters automatically escape double quotes, HTML characters (`<`, `>`), and literal arrows (`-->`) to prevent script injection (XSS) and parser corruption.
+- Output is byte-identical across runs regardless of dictionary key insertion order.
+
+### Run overlay (`WorkflowGraphRunView`)
+
+- Paints per-node runtime status (`status`, `durationMs`, `attempt`, `errorCode`, `skippedReason`) onto the static DAG structure.
+- Does **not** include node outputs — outputs remain on the execution timeline under content-capture policy to protect credentials and manage payload size.
+
 ## Security and performance notes
 
 - Definitions require a non-empty host-authored `revision` and fail closed on cycles, unknown edges, self-edges, invalid limits, and `maxNodes` overflow. Revision and every nested revision enter the deterministic definition hash; hosts must bump revision when function/tool behavior changes. Loop `maxIterations` is required and capped at 64.
@@ -440,6 +507,7 @@ Use workflows for known, durable, replayable graphs. Use optional supervisor del
 - [A2A interoperability](a2a.md): hosts may adapt existing exact-owner workflow status/list/cancel/checkpoint/event surfaces to `A2ATaskLifecycle`; A2A package adds no workflow worker, queue, or schema.
 - [Agent events](agent-events.md): core `AgentEvent` wrapped by `agent_event`
 - [Session stores and branching](session-stores-and-branching.md): session `leafId` reuse on resume
+- [Observational memory compaction](compaction-observational-memory.md): hosts may pass `ctx.nodeId` to `withWorkScope`; the workflow runner stays scope-unaware.
 - [CLI/RPC](cli-rpc.md): host control seam; wire `createWorkflowCommands()` into `runRpcServer`
 - [Database persistence](database-persistence.md): generic `CheckpointStore` and `LeaseStore` capabilities
 - [SQLite persistence](sqlite-persistence.md): durable `persistence.checkpoints`

package/docs/working-and-semantic-memory.md

@@ -4,6 +4,8 @@
 
 `@arnilo/prism-memory` is an optional package for schema/template-backed working memory and embedding-based semantic recall. It owns narrow `Embedder` and `VectorStore` contracts reused by the `@arnilo/prism-memory/rag` subpath, plus an in-memory reference path and one PostgreSQL/pgvector production adapter.
 
+The [memory fabric](memory-fabric.md) subpath is a typed-notes layer on top of these same stores: notes are ordinary rows here, so this page's consent, redaction, lineage, and scope rules are the whole rulebook. [Observational memory](compaction-observational-memory.md) is a separate, **episodic** layer — a source-backed ledger for the current session — and is not a store this package owns or replaces.
+
 ## When to use it
 
 Use it when a host needs durable per-tenant profile/state (working memory) or top-K semantic retrieval over prior thread entries. Do not use it as a replacement for observational memory compaction: observational memory compresses source-backed observations; semantic memory retrieves embeddings; working memory stores the current structured profile.
@@ -27,6 +29,7 @@ Ordinary Prism sessions do not require this package or any vector backend.
 | `redactor` / `secrets` | no | Redact text/metadata before persist/inject |
 | `requireConsent` | no | Strict mode: recall/injection excludes entries lacking explicit consent |
 | `importanceFrom` | no | Host-owned hook deriving importance from a redacted reflection payload (write time only; no default, no LLM) |
+| `onInvalidate` | no | After lineage rows land, before body delete (observational drop / RAG delete wiring) |
 
 Semantic indexing (entries carry `MemoryConsent` source/visibility; unset defaults to `{ source: "user", scope: "thread", visible: true }`):
 
@@ -38,13 +41,13 @@ Semantic indexing (entries carry `MemoryConsent` source/visibility; unset defaul
 | `grantedAt` / `revokedAt` | Optional host/audit timestamps; a revocation excludes the record. |
 
 ```ts
-await memory.remember({ entries: [{ id, text, metadata?, consent?, sequence?, importance?, reflection? }] }, { wait?: boolean })
+await memory.remember({ entries: [{ id, text, metadata?, consent?, sequence?, importance?, reflection?, lineage?: { sourceIds, reason? } }] }, { wait?: boolean })
 ```
 
 Semantic recall (honors consent/visibility at assembly time):
 
 ```ts
-await memory.recall(query, { topK?, messageRange?, requireConsent?, scoring?, signal? })
+await memory.recall(query, { topK?, messageRange?, requireConsent?, scoring?, explain?, shareFromParentThreadId?, signal? })
 ```
 
 #### Composite recall scoring (opt-in)
@@ -99,8 +102,10 @@ Consent + lifecycle (real grant/correct/delete/retention on stored entries):
 ```ts
 await memory.setConsent(entryId, { visible?: boolean, source?, scope? }) // grant/revoke; no re-embed
 await memory.correct(entryId, text)                                       // re-embeds, preserves consent
-await memory.forget({ ids? })                                             // real delete (whole thread if no ids)
-await memory.applyRetention({ maxAgeDays?, maxEntries?, batchSize? })     // bounded real-delete sweep
+await memory.forget({ ids?, hold? })                                      // real delete; hold:true = legal_hold, no body delete
+await memory.shareWith(childThreadId, sourceIds, { expiresAt? })          // parent→child allow-list; empty ids revoke
+await memory.revokeShare(childThreadId)
+await memory.applyRetention({ maxAgeDays?, maxEntries?, batchSize? })     // bounded real-delete sweep; skips legal_hold
 
 const page = await memory.exportMemory({
   identity: { tenantId, resourceId, threadId }, // exact host-verified owner
@@ -117,9 +122,10 @@ const rebuilt = await memory.rebuildIndex({ cursor?, batchSize?, maxMs?, signal?
 | --- | --- |
 | `updateWorking` / `getWorking` | Versioned `WorkingMemoryRecord` |
 | `remember` | `{ accepted, pending, done }` — default `wait: false` indexes asynchronously |
-| `recall` | `{ hits, adjacent }` tenant/thread scoped; invisible/revoked entries excluded |
-| `setConsent` / `correct` | Updated `MemoryVectorRecord` with stamped grant/revoke times |
-| `forget` | Removed count (real delete) |
+| `recall` | `{ hits, adjacent, explanations? }` tenant/thread scoped; invisible/revoked/invalidated entries excluded |
+| `setConsent` / `correct` | Updated `MemoryVectorRecord`; revoke/correct marks lineage before dependents can inject |
+| `forget` | Removed count (real delete); `0` when `hold: true` |
+| `shareWith` / `revokeShare` | Parent-child grant; sibling threads cannot use it |
 | `applyRetention` | `{ deleted, scanned }` bounded real-delete sweep |
 | `exportMemory` | `{ entries, bytes, nextCursor? }` redacted, explicitly consented, identity-bound page |
 | `rebuildIndex` | `{ rebuilt, nextCursor? }` re-embedded bounded page; caller owns resume scheduling |
@@ -215,8 +221,10 @@ const store = await createPostgresVectorStore({
   dimension: 32, // optional; pins the embedding column width (HNSW + drift guard)
 }); // PostgresVectorStoreOptions; dimension must match the embedder's dimensions
 // store implements rag's VectorStore/TransactionalVectorStore contract: upsert,
-// query, getBySource, transaction, lexicalQuery (fts, when available), and
-// getCurrentGeneration/setCurrentGeneration. close() ends adapter-owned pools.
+// query, getBySource, transaction, lexicalQuery (fts, when available),
+// getCurrentGeneration/setCurrentGeneration, and document ACL
+// (`authorization: "acl"`, setSourceAccess, checkSourceAccess).
+// close() ends adapter-owned pools.
 ```
 
 `createPostgresVectorStore()` is the production counterpart to `createMemoryVectorStore()` used by the `rag` subpath; `createPostgresMemoryStores()` reuses the same vector implementation internally.
@@ -226,9 +234,9 @@ const store = await createPostgresVectorStore({
 - Hosts wire the context provider into `AgentConfig.context` or `resolveContextProviders()`.
 - The working-memory processor is opt-in and host-invoked; middleware is not required.
 - `createHashEmbedder()` is for tests/demos only; production hosts supply a real `Embedder`.
-- Observational memory (`/compaction/observational-memory`) remains unchanged and composable.
-- Consent is enforced at the single `recall()` gate, so both direct recall and `createContextProvider()` injection honor it; `visible: false` (or a revoked grant) keeps an entry out of prompts, events, exports, and telemetry. `setConsent`/`correct` re-upsert in place (consent change does not re-embed); `forget`/`applyRetention` are real deletes, not tombstones. Retention uses indexed oldest-first pages plus a scoped count, deleting one default-500/hard-5000 batch without reading a corpus into memory. The PostgreSQL adapter persists consent in a `consent JSONB` column added by `buildMemoryDdl`.
-- The PostgreSQL vector path owns its DDL in Prism (`buildMemoryDdl`/`buildVectorSearchDdl` exported): the `<table>_rag_scope_generations` per-scope generation pointer table, `text_tsv` tsvector column + GIN index for the lexical RAG leg, and an HNSW index when the embedding dimension is pinned. DDL runs against the host's **knowledge database** — the host names `schema`/`table` (defaults `prism_memory`/`semantic_memory`), owns backup/retention of that database, and can run migrations manually with `skipMigrations: true`. Identifiers are validated/quoted; values stay parameterized.
+- Observational memory (`/compaction/observational-memory`) is composable. Stamp `lineage.sourceIds` on semantic writes; pass the same ids as `invalidatedIds` into observational projection/recall, or append `om.observations.dropped` from `onInvalidate`. Multi-source facts stay injectable only if none of their sources are invalidated (regenerate from remaining evidence).
+- Consent is enforced at the single `recall()` gate, so both direct recall and `createContextProvider()` injection honor it; `visible: false` (or a revoked grant) keeps an entry out of prompts, events, exports, and telemetry. `setConsent`/`correct` re-upsert in place (consent change does not re-embed) and write invalidation rows first. `forget`/`applyRetention` are real deletes after those rows land; `forget({ hold: true })` keeps the body for legal hold but still excludes injection/export. A revoked grant is not a legal hold: it blocks injection/export but `forget` still purges the body. Legacy records without `_lineage` are self-only: only their own id is excluded. Caps: walk depth 8, 256 edges, 32 source ids, 64-row delete batches — over-cap throws rather than leak. No claim to retract prior disclosures.
+- The PostgreSQL vector path owns its DDL in Prism (`buildMemoryDdl`/`buildVectorSearchDdl` exported): the `<table>_rag_scope_generations` per-scope generation pointer table, `<table>_rag_source_acl` principal/group grants (query-time EXISTS, indexed by principal and group), `<table>_invalidation` tombstones (query-time NOT EXISTS; `corrected` keeps the source), `<table>_share_grant` parent-child allow-lists, GIN on `metadata._lineage.sourceIds`, `text_tsv` tsvector column + GIN index for the lexical RAG leg, and an HNSW index when the embedding dimension is pinned. DDL runs against the host's **knowledge database** — the host names `schema`/`table` (defaults `prism_memory`/`semantic_memory`), owns backup/retention of that database, and can run migrations manually with `skipMigrations: true`. Identifiers are validated/quoted; values stay parameterized.
 - `createPostgresVectorStore({ dimension })` pins the embedding column width before building indexes: pgvector can only build HNSW over `vector(N)` columns, and dimension mismatch fails closed instead of drifting.
 - `exportMemory()` requires an exact `{ tenantId, resourceId, threadId }` identity equal to its `createMemory()` scope. It excludes legacy consent-less, invisible, and revoked records even when normal recall allows legacy entries. It returns a stable sequence cursor page, redacted before response, with defaults/hard caps of 100/200 entries, 4/32 MiB, and 10/60 seconds. `rebuildIndex()` uses the same stable cursor shape to re-embed one 32/128-record page under a 10/60-second cap; save the cursor durably to resume. Both APIs require a store implementing bounded `listByThread()`; retention also requires `countByThread()`. PostgreSQL/pgvector and the in-memory reference adapter conform; SQLite persistence stores sessions, not semantic vectors.
 - Profile bundles do not include this package yet.
@@ -249,7 +257,9 @@ await runMemoryConformance(() => ({
 
 - Every write/query/delete requires `tenantId` + `resourceId`; semantic paths also require `threadId`.
 - Cross-tenant and cross-thread access is denied.
-- Revoked/invisible/non-consented memories never enter prompts, events, exports, or telemetry; `requireConsent: true` additionally drops consent-less (legacy) entries. Consent checks are O(hits) at recall, within the existing injected-token cap.
+- RAG document ACL (`RagAccessConstraint`) is host-verified and applied inside `query`/`lexicalQuery` before ranking when `authorization` is passed. Missing grants and unresolved access versions deny. `filter` is not ACL.
+- Revoked/invisible/non-consented/invalidated memories never enter prompts, events, exports, or telemetry; `requireConsent: true` additionally drops consent-less (legacy) entries. Query-time invalidation is an indexed NOT EXISTS (no full-corpus scan on recall). Parent-child shares are explicit, tenant-bound, expiring, and fail closed when missing. Cross-tenant lineage/grants reject.
+- `revokedIdsAbsent(environment, deniedIds)` is the 072 invariant body (`metadata.invariant: true`, score 0 cannot be averaged away). Hosts wrap it with `defineScorer`.
 - Configure `secrets` / `redactor` so memory text and metadata cannot persist or inject raw canaries.
 - Injected context is inert text — it cannot grant tools or permissions.
 - Hard caps: top-K ≤ 32, messageRange ≤ 4, embed batch ≤ 128, injected tokens ≤ 8000, payload/working-memory byte limits enforced.
@@ -266,6 +276,7 @@ Supervisor child factories receive unique derived `resourceId` and `threadId` va
 - [Supervisor delegation](supervisors.md): package-derived child resource/thread scope.
 - [Retrieval-augmented generation](rag.md): bounded document chunks reuse this package's embed/vector contracts.
 - [Context and skills](context-and-skills.md): `ContextProvider` injection seam.
-- [Observational memory compaction package](compaction-observational-memory.md): source-backed observation/reflection memory distinction.
+- [Observational memory compaction package](compaction-observational-memory.md): source-backed observation/reflection memory distinction; still episodic, owned by that subpath, not by these stores.
 - [PostgreSQL persistence](postgres-persistence.md): session/run persistence; memory vectors live in this optional package instead.
 - [Middleware hooks](middleware-hooks.md): reuse existing `context` hook if hosts transform injected blocks.
+- [Memory fabric](memory-fabric.md): typed notes over these stores, with recall explanations and conversation search.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arnilo/prism",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Agent harness for AI providers, agents, sessions, and tools.",
   "type": "module",
   "main": "./dist/index.js",

package/templates/README.md

@@ -8,6 +8,8 @@ Ready-to-run project templates for `prism init --template <name>`.
 | --- | --- | --- |
 | `init` | Minimal starter Prism agent with one selected provider and offline mock test | `@arnilo/prism` |
 | `deep-research` | Flagship deep research agent: plan -> search -> extract -> refine loop -> citations -> HITL clarify | `@arnilo/prism`, `@arnilo/prism-web-tools`, `@arnilo/prism-memory`, `@arnilo/prism-workflows` |
+| `personal-assistant` | Personal workstation assistant: single-user ownership, local tools, credential references, and dev inspection | `@arnilo/prism`, `@arnilo/prism-core`, `@arnilo/prism-providers` |
+| `business-worker` | Multi-tenant business worker: durable storage, tenant isolation, verified identity, and governed boundaries | `@arnilo/prism`, `@arnilo/prism-core`, `@arnilo/prism-providers` |
 
 ## Usage
 

package/templates/business-worker/README.md.tmpl

@@ -0,0 +1,19 @@
+# __PROJECT_NAME__
+
+Multi-tenant business worker built with Prism. Features strict tenant isolation, verified identities, durable persistence, and governed invocation boundaries.
+
+## Quickstart
+
+```bash
+npm install
+npm test
+npm start
+```
+
+## Production Readiness Requirements
+
+- **Tenant Isolation**: Non-empty `tenantId` in ownership; tenant-scoped stores and workspaces.
+- **Verified Identity**: Host-verified principal matching tenant ownership; no fabricated identities.
+- **Durable Persistence**: Production readiness strictly rejects in-memory stores; PostgreSQL or SQLite durable stores required.
+- **Workspace Containment**: Execution confined to authorized tenant sandbox directories.
+- **Governed Invocation**: Permission policies, trust verification, parameter validation, and secret redaction enforced.

package/templates/business-worker/env.example.tmpl

@@ -0,0 +1 @@
+BUSINESS_API_KEY=

package/templates/business-worker/gitignore.tmpl

@@ -0,0 +1,11 @@
+node_modules/
+dist/
+.env
+.env.local
+*.db
+*.sqlite
+*.sqlite3
+.prism/
+coverage/
+.DS_Store
+*.log

package/templates/business-worker/manifest.json

@@ -0,0 +1,11 @@
+{
+  "name": "business-worker",
+  "description": "Multi-tenant business worker: durable storage, tenant isolation, verified identity, and governed invocation boundaries",
+  "version": "0.1.0",
+  "tags": ["business", "worker", "multi-tenant", "enterprise", "secure"],
+  "packages": [
+    "@arnilo/prism",
+    "@arnilo/prism-core",
+    "@arnilo/prism-providers"
+  ]
+}

package/templates/business-worker/package.json.tmpl

@@ -0,0 +1,23 @@
+{
+  "name": "__PROJECT_NAME__",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build && node --test dist/__tests__/agent.test.js",
+    "start": "npm run build && node dist/index.js",
+    "dev": "prism dev"
+  },
+  "dependencies": {
+__DEPENDENCIES__
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/templates/business-worker/src/agent.ts.tmpl

@@ -0,0 +1,92 @@
+import {
+  type Agent,
+  createMemoryCheckpointStore,
+  createMockProvider,
+  createSecretRedactor,
+  createSecureAgent,
+  createStaticPermissionPolicy,
+  createStaticTrustPolicy,
+  providerDone,
+  providerTextDelta,
+} from "@arnilo/prism";
+import { createJsonSchemaArgumentValidator } from "@arnilo/prism-core/validation/json-schema";
+import { createMemoryWorkDraftStore, type SyncWorkDraftStore } from "@arnilo/prism-core/integrations/work";
+import type { AgentIdentity } from "@arnilo/prism";
+
+export interface CreateBusinessWorkerOptions {
+  readonly tenantId?: string;
+  readonly userId?: string;
+  readonly identity?: AgentIdentity;
+  readonly store?: import("@arnilo/prism").CheckpointStore;
+  readonly provider?: import("@arnilo/prism").AIProvider;
+  readonly model?: { readonly provider: string; readonly model: string };
+  readonly workspaceRoot?: string;
+}
+
+export function createAppAgent(options: CreateBusinessWorkerOptions = {}): Agent {
+  const tenantId = options.tenantId ?? "tenant-corp";
+  const userId = options.userId ?? "worker-1";
+
+  const identity: AgentIdentity = options.identity ?? {
+    tenantId,
+    userId,
+    principal: { kind: "user", id: userId },
+    scopes: ["worker:execute"],
+    verified: true,
+    issuedAt: new Date().toISOString(),
+  };
+
+  const redactor = createSecretRedactor(
+    [process.env.BUSINESS_API_KEY].filter((v): v is string => typeof v === "string" && v.length > 0),
+  );
+
+  const provider =
+    options.provider ??
+    createMockProvider([
+      providerTextDelta("Business worker ready for tenant tasks."),
+      providerDone(),
+    ]);
+
+  return createSecureAgent({
+    id: "business-worker",
+    definitionRevision: "1",
+    ownership: { tenantId, userId },
+    identity,
+    redactor,
+    permission: createStaticPermissionPolicy(true),
+    trust: createStaticTrustPolicy(true),
+    toolArgumentValidator: createJsonSchemaArgumentValidator(),
+    limits: { maxToolRounds: 15 },
+    runState: { checkpoints: options.store ?? createMemoryCheckpointStore() },
+    tools: [
+      {
+        name: "process_tenant_record",
+        description: "Processes a verified tenant batch item",
+        parameters: {
+          type: "object",
+          properties: {
+            recordId: { type: "string" },
+            action: { type: "string" },
+          },
+          required: ["recordId", "action"],
+          additionalProperties: false,
+        },
+        execute: async (args, ctx) => ({
+          toolCallId: ctx.toolCallId,
+          name: "process_tenant_record",
+          value: {
+            processed: true,
+            tenantId,
+            recordId: (args as { recordId: string }).recordId,
+          },
+        }),
+      },
+    ],
+    provider,
+    model: options.model ?? { provider: "mock", model: "corp-worker-model" },
+  });
+}
+
+export function createWorkerDraftStore(): SyncWorkDraftStore {
+  return createMemoryWorkDraftStore();
+}

package/templates/business-worker/src/index.ts.tmpl

@@ -0,0 +1,13 @@
+import { createAppAgent } from "./agent.js";
+
+async function main() {
+  const agent = createAppAgent({ tenantId: "tenant-acme", userId: "worker-prod-1" });
+  const session = agent.createSession({ id: "biz-session-1" });
+  const result = await session.run("Process batch queue item");
+  console.log(result.text);
+}
+
+main().catch((error) => {
+  console.error("Business worker failed:", error);
+  process.exit(1);
+});

package/templates/business-worker/src/tests/agent.test.ts.tmpl

@@ -0,0 +1,77 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { assertHostCompositionReadiness, inspectHostComposition, HostCompositionError } from "@arnilo/prism";
+import { validateApproval } from "@arnilo/prism-core/integrations/work";
+import type { AgentIdentity } from "@arnilo/prism";
+import { createAppAgent, createWorkerDraftStore } from "../agent.js";
+
+describe("business worker template", () => {
+  it("creates agent and processes task with tenant context", async () => {
+    const agent = createAppAgent({ tenantId: "tenant-enterprise", userId: "worker-test" });
+    const session = agent.createSession({ id: "test-biz-session" });
+    const result = await session.run("Run tenant task");
+    assert.ok(result.text.includes("Business worker ready"));
+  });
+
+  it("fails business readiness if memory-only store is configured", () => {
+    const agent = createAppAgent({ tenantId: "tenant-enterprise", userId: "worker-test" });
+    assert.throws(
+      () => {
+        assertHostCompositionReadiness({
+          profile: "business",
+          agent,
+          store: { kind: "memory", durable: false },
+        });
+      },
+      (error) => error instanceof HostCompositionError && error.message.includes("durable storage"),
+    );
+  });
+
+  it("passes business readiness with durable store and isolated workspace", () => {
+    const agent = createAppAgent({ tenantId: "tenant-enterprise", userId: "worker-test" });
+    const report = inspectHostComposition({
+      profile: "business",
+      agent,
+      store: { kind: "postgres", durable: true },
+      workspaceRoot: "/var/tenant-enterprise",
+      sandboxRoots: ["/var/tenant-enterprise/tasks"],
+      credentialRefs: ["BUSINESS_API_KEY"],
+    });
+
+    assert.equal(report.profile, "business");
+    assert.equal(report.ownership.tenantId, "tenant-enterprise");
+    assert.equal(report.storage.durable, true);
+    assert.equal(report.sandbox.isolated, true);
+    assert.equal(report.readiness.ok, true);
+  });
+
+  it("rejects a stale draft revision after edit", () => {
+    const store = createWorkerDraftStore();
+    const identity: AgentIdentity = {
+      tenantId: "tenant-enterprise",
+      userId: "worker-test",
+      principal: { kind: "user", id: "worker-test" },
+      scopes: ["Mail.Send"],
+      issuedAt: new Date().toISOString(),
+      verified: true,
+    };
+    const draft = store.createDraft({
+      provider: "microsoft365",
+      op: "mail.send",
+      identity,
+      payload: { to: "a@contoso.com", subject: "v1" },
+    });
+    const approval = {
+      draftId: draft.draftId,
+      revision: draft.revision,
+      payloadDigest: draft.payloadDigest,
+    };
+    const updated = store.updateDraft({
+      draftId: draft.draftId,
+      identity,
+      payload: { to: "a@contoso.com", subject: "v2" },
+      expectedRevision: 1,
+    });
+    assert.throws(() => validateApproval(updated, approval), /does not match draft revision/);
+  });
+});