@arnilo/prism 0.0.4 → 0.0.5

package/docs/workflow-orchestration-primitives.md

@@ -8,6 +8,10 @@ Interactive TUI (**C-012**) is **out of scope** for Plan 057 and deferred. Workf
 
 **Final Task 7 architecture (2026-07-14):** DAG/coordinator semantics remain package-local. Reusable versioned checkpoints, atomic leases, and bounded async event fan-in live in core as `CheckpointStore`, `LeaseStore`, and `EventMultiplexer`. Workflow adapters are thin domain facades; lease fencing plus checkpoint CAS prevents stale-worker commits.
 
+**Phase 8 addendum (2026-07-15):** `@arnilo/prism-workflows` extends the same checkpoint JSON/state machine with `suspended` and terminal `denied` statuses, `suspend()`, persisted suspension/resume records, and `workflow_suspended` / `workflow_resumed` events. An approved resume requires the displayed checkpoint `expectedVersion`; the first checkpoint write CAS-claims it before node execution. Suspended runs are absent from coordinator `queued`/`running` polls, so no worker or polling loop remains active. No SQL migration or second approval store is required.
+
+**Phase 11 addendum (2026-07-16):** schedules use a separate generic checkpoint namespace plus per-fire `LeaseStore` claims and deterministic queued-run IDs; SQLite/PostgreSQL need no workflow-specific table or migration. Background execution remains `enqueueWorkflow` + the existing coordinator. Nested workflow nodes call the same runner with inherited policy/ownership/checkpoint/event seams. Shared JSON state is validated, redacted, byte/history bounded, and checkpointed by version. Replay creates a new checkpoint with immutable source lineage and copied terminal evidence; approval-bearing prior paths cannot be copied.
+
 ## When to use it
 
 - **Workflow package authors** should start here, then follow [Agent/session runtime](agent-session-runtime.md), [Agent loops](agent-loops.md), [Runs and usage ledger](runs-and-usage.md), [CLI/RPC](cli-rpc.md), and [Database persistence](database-persistence.md).
@@ -121,7 +125,7 @@ Static review of `src/agents.ts`, `src/agent-loops.ts`, `src/rpc.ts`, `src/cli-r
 | Event fan-in | Generic core multiplexer | Package queue duplication | **Core multiplexer + package facade** | One bounded/abort-aware implementation |
 | Distributed ownership | Process-local active map | Generic leases + package coordinator | **LeaseStore + fenced checkpoint CAS** | Atomic claims and monotonic fences prevent split brain across processes |
 | Host control (no TUI) | Interactive terminal package | Public APIs + optional RPC/`CommandDefinition` | **Public APIs + optional commands** | Replaces former TUI Tasks for feature completeness |
-| Approval prompts | Core `ApprovalHandler` | Host `ExecutionPolicy` / `CodingApprovalFn` | **Host callbacks** | Mirrors coding-security pattern |
+| Approval prompts | Core `ApprovalHandler` | Durable workflow suspension + host `ExecutionPolicy` | **Checkpoint suspension** | Survives restart; approved tool execution still rechecks current host policy |
 | Interactive TUI | Ship in Plan 057 | Defer C-012 | **Defer** | Explicit product decision after Task 0 |
 
 ## Locked package adapter contracts (Task 1)
@@ -435,6 +439,12 @@ runRpcServer({
 | Workflow `maxCheckpointBytes` | Full checkpoint blob | 1 MiB | Resume metadata only; not full transcripts |
 | Workflow event buffer | Per run merge queue | 2048 | Coalesce node status; drop with `workflow_event_overflow` |
 | Workflow list/status page size | Status helper default | 100 | Bounded run listing for hosts |
+| Nested depth | Default / hard | 8 / 32 | Prevent recursive composition exhaustion |
+| Shared state | Default / hard bytes | 64 KiB / 512 KiB | Keep node context/checkpoints bounded |
+| State history | Default / hard snapshots | 32 / 128 | Preserve replay state without unbounded history |
+| Replay lineage | Default / hard depth | 8 / 32 | Prevent replay-chain abuse |
+| Schedule input | Default / hard bytes | 256 KiB / 1 MiB | Bound persisted trigger payload |
+| Schedule due claims | Default / hard per poll | 16 / 256 | Bound one poll; idle waits 1s by default |
 
 ## Threat model and design matrix
 
@@ -444,7 +454,7 @@ runRpcServer({
 | 2 | Unbounded fan-out (dynamic list) | Workflow package | Cap `maxFanOut`; fail `node_failed` when exceeded |
 | 3 | Resumed checkpoint tampered (wrong tenant/version) | Workflow adapter | Fail closed; no partial node execution |
 | 4 | Checkpoint contains secrets | Workflow + redactor | Redact before persist; `redacted: true` metadata |
-| 5 | Shell/tool approval during workflow | Host + ExecutionPolicy | Show/include `kind`, `command`, `paths`, `risk`, `workflowId`, `nodeId` |
+| 5 | Shell/tool approval during workflow | Host + workflow | Opt-in tool approval suspends before side effects; resume uses ownership + expected-version CAS, then rechecks current `ExecutionPolicy` with workflow/node metadata |
 | 6 | Cancel during node execution | Workflow | `signal` abort → in-flight `session.abort()`; checkpoint marks `aborted` |
 | 7 | Untrusted workflow definition file | Host | Load from trusted path only; schema-validate before `runWorkflow` |
 | 8 | Node output passed to next node | Workflow | Size-bound; type validate; redact at boundary |
@@ -452,6 +462,12 @@ runRpcServer({
 | 10 | Cross-tenant list/status query | Workflow adapter | Scope by ownership; never return other tenants' runs |
 | 11 | RPC workflow cancel races session abort | Workflow commands | Cancel is idempotent; fails closed if run unknown/unauthorized |
 | 12 | 1000-node workflow checkpoint growth | Workflow | Store ready set + bounded outputs only; no full transcript duplication |
+| 13 | Two reviewers resume one suspension | Workflow adapter | Expected-version CAS claims checkpoint before execution; one succeeds, stale reviewer fails |
+| 14 | Forged/cross-tenant resume | Workflow + host | Ownership and definition hash checked; declared schema requires host validator; payload redacted before persistence |
+| 15 | Duplicate/crashed schedule fire | Workflow schedules | Per-fire lease, deterministic run ID, queued checkpoint idempotency, schedule CAS |
+| 16 | Nested workflow broadens capability | Workflow runner | Child inherits parent tool/agent/policy/ownership/signal seams; bounded inherited depth |
+| 17 | Replay mutates evidence or reuses approval | Workflow replay | New checkpoint + immutable lineage; source untouched; copied approval-bearing path rejected |
+| 18 | State/history resource exhaustion | Workflow runner/checkpoint | Host validation plus state byte/history and aggregate checkpoint ceilings |
 
 ## Final primitive decisions (Task 1, superseded where noted by Task 6)
 
@@ -547,7 +563,7 @@ await session.run("Hi", { signal: AbortSignal.timeout(60_000) });
 - Workflow agent nodes call public `AgentSession` APIs only; no imports from `src/agents.ts` internals.
 - Workflow checkpoints adapt `ProductionPersistenceStore.checkpoints` (or any `CheckpointStore`); no raw database handles enter the workflow package.
 - Multimodal and credential packages from Plan 056 compose unchanged in workflow examples (Task 4).
-- `prism-all` umbrella **excludes** `@arnilo/prism-workflows` (optional orchestration; install explicitly). Documented in package README and `docs/release-and-install.md`.
+- `@arnilo/prism-workflows` is available directly and through `prism-sdk`/`prism-all`; installation does not start a worker or workflow.
 - C-012 interactive TUI remains a future optional package if needed; it is not required for workflow feature completeness.
 
 ## Related APIs

package/docs/workflows.md

@@ -2,21 +2,22 @@
 
 ## What it does
 
-`@arnilo/prism-workflows` is an optional package for typed, bounded DAG orchestration over Prism sessions, tools, events, and persistence seams. Hosts define acyclic workflows with agent/function/tool/conditional/fan-out/join nodes; the package runs a Kahn-style scheduler with a bounded worker pool, emits package-local `WorkflowEvent`s, checkpoints progress, and can coordinate queued runs across multiple host processes using durable leases and fencing.
+`@arnilo/prism-workflows` is an optional package for typed, bounded DAG orchestration over Prism sessions, tools, events, and persistence seams. Hosts define acyclic workflows with agent/function/tool/conditional/fan-out/join/nested-workflow nodes; the package runs a Kahn-style scheduler with a bounded worker pool, emits package-local `WorkflowEvent`s, checkpoints progress, and can coordinate queued runs across multiple host processes using durable leases and fencing.
 
 Primary exports:
 
 | Export | Purpose |
 | --- | --- |
 | `defineWorkflow` / `buildGraph` | Validate definitions (acyclicity, edge refs, limits) and build deterministic successor/indegree maps |
-| `agentNode`, `functionNode`, `toolNode`, `conditionalNode`, `fanOutNode`, `joinNode` | Typed node factories |
-| `runWorkflow` / `resumeWorkflow` | Execute or resume a run with concurrency, abort, redaction, and optional checkpoints |
+| `agentNode`, `functionNode`, `toolNode`, `conditionalNode`, `fanOutNode`, `joinNode`, `workflowNode` | Typed node factories, including composition through the same runner |
+| `runWorkflow` / `resumeWorkflow` / `suspend` / `replayWorkflow` | Execute, durably suspend, exactly-once resume, or create an immutable-lineage replay from a succeeded node |
 | `createMemoryWorkflowCheckpoints` | In-process `WorkflowCheckpointAdapter` over core `createMemoryCheckpointStore()` |
 | `createWorkflowCheckpoints` | Adapt core `CheckpointStore` (including SQLite/PostgreSQL persistence capabilities) to workflow checkpoint shapes |
 | `createWorkflowEventBus` | Bounded pub/sub for `WorkflowEvent` with overflow policy |
 | `getWorkflowRun` / `listWorkflowRuns` / `cancelWorkflowRun` | Status, paginated list, and cancel helpers |
-| `createWorkflowCommands` | Optional `CommandDefinition[]` for `runRpcServer` (`workflow.start` / `status` / `list` / `cancel` / `resume`) |
-| `enqueueWorkflow` / `createWorkflowCoordinator` | Persist queued work and atomically claim/renew/execute it across processes using `LeaseStore` |
+| `createWorkflowCommands` | Optional `CommandDefinition[]` for direct/background/replay/status/list/cancel/resume and, when selected, schedule control |
+| `enqueueWorkflow` / `startWorkflowBackground` / `createWorkflowCoordinator` | Persist queued work and atomically claim/renew/execute it across processes using `LeaseStore` |
+| `createWorkflowSchedules` | Explicit ownership-scoped one-time/interval/host-calculated schedules over existing checkpoint/lease stores |
 
 Included through `@arnilo/prism-sdk` and `@arnilo/prism-all`; installing either profile does not start workflows. Interactive TUI is out of scope (C-012 deferred).
 
@@ -40,6 +41,11 @@ Use `createWorkflowCoordinator()` when multiple processes share SQLite/PostgreSQ
 | `limits.maxConcurrency` | Default 8 |
 | `limits.maxNodeOutputBytes` | Default 4 MiB |
 | `limits.maxCheckpointBytes` | Default 1 MiB |
+| `limits.maxNestedDepth` / hard cap | 8 / 32; inherited by child workflows |
+| `limits.maxStateBytes` / hard cap | 64 KiB / 512 KiB |
+| `limits.maxStateHistory` / hard cap | 32 / 128 state snapshots; updates stop before evidence would be discarded |
+| `limits.maxReplayDepth` / hard cap | 8 / 32 lineage generations |
+| `state.initial` / `state.schema` | Initial shared JSON object and optional host-validated schema |
 
 `runWorkflow(workflow, input, options?)`:
 
@@ -56,23 +62,38 @@ Use `createWorkflowCoordinator()` when multiple processes share SQLite/PostgreSQ
 | `signal` | Cancels the run and in-flight agent sessions |
 | `onEvent` | Synchronous `WorkflowEvent` sink |
 | `runId` | Caller-supplied id; otherwise generated (`wfr_…`) |
+| `resume` | For suspended runs: `{ decision: "approve" | "deny", input?, expectedVersion }`; version is mandatory for an exact-once CAS claim |
+| `validateResume` | Host validator for resume input; required when `suspend()` declares `resumeSchema` |
+| `validateState` | Host validator for every initial/restored/updated state; required when workflow declares `state.schema` |
+| `initialState` | Optional host initial state override; nested workflows receive parent state automatically |
 
-`resumeWorkflow(workflow, { runId }, options)` loads the checkpoint, validates schema/version/tenant/`definitionHash`, and continues pending/ready nodes only.
+A function node returns `suspend({ reason, data?, resumeSchema? })` to persist `status: "suspended"`. Its next invocation receives `ctx.resume` only after an approved resume. `resumeWorkflow(workflow, { runId }, options)` validates schema/version/ownership/`definitionHash`, claims the checkpoint before node execution, and continues the suspended node. Denial persists terminal `denied` status without invoking it. Existing failed/aborted checkpoint resume remains available without a human decision.
+
+Every node receives bounded `ctx.state`, `ctx.stateVersion`, and async `ctx.updateState(patch, { mode: "merge" | "replace" })`. Updates serialize, validate, redact, and snapshot before checkpoint save. `workflowNode({ workflow })` runs its child with the same ownership, agent/tool registries, execution policy, redactor, signal, checkpoints, and event bus; child state replaces parent state after success.
+
+`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).
 
+`createWorkflowSchedules({ store, leases, checkpoints, workflows, ownership, ownerId, calculators? })` is inert until its host calls `pollOnce()` or `run({ signal })`. Ownership requires `tenantId` plus `accountId` or `userId`. Methods are `create`, `get`, `list`, `pause`, `resume`, `trigger`, `delete`, `pollOnce`, and `run`. A record has one required `nextRunAt`, optional fixed `intervalMs` or registered `calculatorId` (never both), bounded input/metadata, status, version, and last-fire attribution. Manual trigger requires an idempotency key. Scheduled run IDs derive from schedule ID plus fire timestamp, so retry after enqueue-before-advance finds the same queued checkpoint instead of duplicating it. Defaults: page 100/hard 500, due claims 16/hard 256, input 256 KiB/hard 1 MiB, poll 1s, fire lease 30s.
+
 ## Outputs / response / events
 
 `runWorkflow` / `resumeWorkflow` resolve to `WorkflowRunResult`:
 
 | Field | Notes |
 | --- | --- |
-| `runId`, `workflowId`, `status` | `succeeded` / `failed` / `aborted` |
+| `runId`, `workflowId`, `status` | `queued` / `running` / `suspended` / `succeeded` / `failed` / `denied` / `aborted` |
 | `outputs` | Map of succeeded node outputs |
-| `error` | First fail-fast error when status is `failed` |
-| `version`, `definitionHash`, `createdAt`, `updatedAt` | Checkpoint identity |
+| `state` | Final/current bounded shared JSON state |
+| `lineage` | Replay source/root/node/depth record when this is a replay |
+| `suspension` | Current/persisted `{ nodeId, reason, data?, resumeSchema?, requestedAt }` |
+| `resume` | Attributable resume decision/input/version/time record |
+| `version` | Checkpoint CAS identity shown to reviewers and required on suspended resume |
 
-Package-local `WorkflowEvent` types: `workflow_started`, `workflow_finished`, `node_started`, `node_finished`, `node_failed`, `node_skipped`, `checkpoint_saved`, `agent_event` (wraps a redacted `AgentEvent`), `workflow_event_overflow`. Sequences are monotonic; drain/order is deterministic by `(sequence, nodeId)`.
+Schedule `onEvent` receives bounded-attribution `schedule_fired` or metadata-only `schedule_failed`; schedule input is never copied into these events.
+
+Package-local `WorkflowEvent` types: `workflow_started`, `workflow_suspended`, `workflow_resumed`, `workflow_finished`, `node_started`, `node_finished`, `node_failed`, `node_skipped`, `checkpoint_saved`, `agent_event` (wraps a redacted `AgentEvent`), `workflow_event_overflow`. Sequences are monotonic; drain/order is deterministic by `(sequence, nodeId)`.
 
 ## Request/response example
 
@@ -111,6 +132,10 @@ import {
   cancelWorkflowRun,
   enqueueWorkflow,
   createWorkflowCoordinator,
+  createWorkflowSchedules,
+  replayWorkflow,
+  workflowNode,
+  suspend,
 } from "@arnilo/prism-workflows";
 import { runRpcServer } from "@arnilo/prism";
 import { createSqlitePersistence } from "@arnilo/prism-session-store-sqlite";
@@ -122,11 +147,20 @@ const research = agentNode({
 const draft = functionNode({
   execute: async (ctx) => `Draft from ${String(ctx.upstream.research)}`,
 });
+const publish = functionNode({
+  execute: async (ctx) => ctx.resume
+    ? publishDraft(ctx.upstream.draft, ctx.resume.input)
+    : suspend({
+        reason: "publish",
+        data: { draft: ctx.upstream.draft },
+        resumeSchema: { type: "object", required: ["reviewer"] },
+      }),
+});
 
 const workflow = defineWorkflow({
   id: "research-draft",
-  nodes: { research, draft },
-  edges: [["research", "draft"]],
+  nodes: { research, draft, publish },
+  edges: [["research", "draft"], ["draft", "publish"]],
   limits: { maxNodes: 256, maxFanOut: 32, maxConcurrency: 4 },
 });
 
@@ -157,12 +191,20 @@ const result = await runWorkflow(workflow, { topic: "hooks" }, {
   onEvent: (event) => sink.push(event),
 });
 
-// Durable resume after process restart (reopen persistence, then adapt its store):
-await resumeWorkflow(workflow, { runId: result.runId }, {
-  checkpoints,
-  agentFactory: (name) => agents.resolve(name).createSession(),
-  ownership: { tenantId: "t1" },
-});
+// Durable human resume after process restart. Use result.version shown to reviewer.
+if (result.status === "suspended") {
+  await resumeWorkflow(workflow, { runId: result.runId }, {
+    checkpoints,
+    agentFactory: (name) => agents.resolve(name).createSession(),
+    ownership: { tenantId: "t1" },
+    resume: {
+      decision: "approve",
+      input: { reviewer: "Ada" },
+      expectedVersion: result.version,
+    },
+    validateResume: ({ value }) => validateResumePayload(value),
+  });
+}
 
 await cancelWorkflowRun({
   workflowId: workflow.id,
@@ -172,11 +214,34 @@ await cancelWorkflowRun({
 });
 
 // Optional host control via existing CLI/RPC CommandDefinition seam:
+const schedules = createWorkflowSchedules({
+  store: persistence.checkpoints,
+  leases: persistence.leases,
+  checkpoints,
+  workflows: { [workflow.id]: workflow },
+  ownership: { tenantId: "t1", userId: "ops" },
+  ownerId: process.env.HOSTNAME ?? "scheduler-1",
+});
+await schedules.create({
+  id: "daily-research",
+  workflowId: workflow.id,
+  nextRunAt: "2026-07-17T00:00:00.000Z",
+  intervalMs: 86_400_000,
+  input: { topic: "hooks" },
+});
+// Host calls schedules.pollOnce() from an existing timer, or explicitly starts schedules.run({ signal }).
+
+const replay = await replayWorkflow(workflow, {
+  sourceRunId: result.runId,
+  fromNodeId: "draft",
+}, { checkpoints, ownership: { tenantId: "t1" }, agentFactory });
+
 runRpcServer({
   createSession,
   commands: createWorkflowCommands({
     workflows: { [workflow.id]: workflow },
     checkpoints,
+    schedules,
     runOptions: { ownership: { tenantId: "t1" }, agentFactory },
   }),
 });
@@ -187,7 +252,7 @@ runRpcServer({
 - Workflow semantics stay in this optional package; generic checkpoint persistence and bounded event fan-in live in core.
 - `ProductionPersistenceStore.checkpoints` and `.leases` are optional generic capabilities. First-party SQLite/PostgreSQL adapters own `prism_checkpoints` / `prism_leases`; workflows only adapt them.
 - `createWorkflowEventBus()` delegates queueing, source fan-in, overflow, abort, and close behavior to core `createEventMultiplexer()`.
-- `createWorkflowCommands()` is optional; hosts that already use `runRpcServer({ commands })` can drive start/status/list/cancel/resume without a TUI.
+- `createWorkflowCommands()` is optional; hosts can drive `workflow.start` / `enqueue` / `replay` / `status` / `list` / `cancel` / `resume`. The six `schedule.*` commands appear only when a scoped `schedules` service is supplied.
 - Hosts may bridge `WorkflowEvent` into OpenTelemetry or custom sinks; there is no built-in TUI.
 - Agent exclusivity is per session: one active `run()` at a time, same as core.
 
@@ -195,19 +260,28 @@ runRpcServer({
 
 - Definitions fail closed on cycles, unknown edges, self-edges, and `maxNodes` overflow.
 - Fan-out length is bounded by `maxFanOut`; concurrency by `maxConcurrency`.
-- Node outputs and checkpoints are byte-bounded (`maxNodeOutputBytes`, `maxCheckpointBytes`).
+- Node outputs, shared state/history, schedule input/records, and checkpoints are byte/count/depth bounded. Checkpoint size remains the final aggregate ceiling.
 - Event buses use a bounded buffer (default 2048) with `close` / `drop_oldest` / `drop_newest` overflow.
-- Checkpoints redact via `SecretRedactor` / `secrets` before save; resume rejects tenant, schema, and definition-hash mismatch.
+- Checkpoints redact suspension/resume payloads via `SecretRedactor` / `secrets` before save; resume rejects tenant, schema, definition-hash, and expected-version mismatch.
+- Suspension requires a checkpoint adapter, consumes no worker/polling slot, and is ignored by distributed coordinators until explicit resume.
+- Concurrent resumes race on checkpoint CAS before node execution; one wins and stale/duplicate reviewers fail closed. Approved tool nodes then re-run current `ExecutionPolicy`, so durable approval cannot grant stale permissions.
+- `toolNode({ approval: { reason, data?, resumeSchema? } })` suspends before tool execution. Denial is terminal `denied`; no tool side effect occurs.
 - `cancelWorkflowRun` aborts local runs immediately and writes a durable cancellation request for a remotely leased run; workers check it during lease renewal.
 - Tool nodes attach `workflowId` / `nodeId` on `ExecutionAction.metadata` for approval/audit context.
-- Scheduler stores O(nodes + active outputs); ready-node work uses indegree maps, not repeated full scans.
+- Nested workflows inherit host registries/policies and cannot inject broader tools, agents, ownership, or credentials. Nested depth is inherited; child suspension bubbles to the parent review cursor.
+- Replay source ownership/hash/status/node eligibility are checked before a new checkpoint is created. Source records are immutable, lineage is bounded, and copied approval-bearing paths are rejected.
+- Schedule services are ownership-scoped and explicitly started. Per-fire leases plus deterministic run IDs/CAS prevent duplicate enqueue across coordinators and crash retry. Host calculator IDs resolve only from the supplied map; no callback or cron expression is persisted.
+- Scheduler stores O(nodes + active outputs + bounded state history); ready-node work uses indegree maps, not repeated full scans.
 - Lease acquisition is atomic; opaque tokens protect renew/release; monotonically increasing fencing tokens plus checkpoint compare-and-swap prevent expired workers from committing after takeover. Node functions must honor `ctx.signal` for prompt cooperative cancellation.
 
+Use workflows for known, durable, replayable graphs. Use optional supervisor delegation only when child selection must be dynamic at runtime; do not replace deterministic nodes with model routing without a concrete need.
+
 ## Related APIs
 
 - Examples: `examples/workflow-research-and-review.ts`, `examples/workflow-parallel-research.ts`, `examples/workflow-tool-approval.ts`, `examples/workflow-multimodal-document.ts`, `examples/workflow-sqlite-resume.ts`, `examples/workflow-postgres-resume.ts`, `examples/workflow-event-sink.ts`, `examples/workflow-rpc-cancel.ts`, `examples/workflow-distributed-coordinator.ts` — offline runnable demos; PostgreSQL safely skips unless `PRISM_TEST_POSTGRES_URL` is set.
 - [Workflow orchestration primitives](workflow-orchestration-primitives.md): Task 0–1 inventory and locked adapter contracts
-- [Agent/session runtime](agent-session-runtime.md): `AgentSession.run()`, abort, subscribe
+- [Agent/session runtime](agent-session-runtime.md): `AgentSession.run()`/`stream()`, abort, subscribe
+- [Supervisor delegation](supervisors.md): bounded dynamic child selection.
 - [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
 - [CLI/RPC](cli-rpc.md): host control seam; wire `createWorkflowCommands()` into `runRpcServer`

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

@@ -0,0 +1,169 @@
+# Working and semantic memory
+
+## What it does
+
+`@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 `@arnilo/prism-rag`, plus an in-memory reference path and one PostgreSQL/pgvector production adapter.
+
+## 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.
+
+Ordinary Prism sessions do not require this package or any vector backend.
+
+## Inputs / request
+
+`createMemory(options)`:
+
+| Field | Required | Meaning |
+| --- | --- | --- |
+| `tenantId` | yes | Tenant isolation key |
+| `resourceId` | yes | Resource/user isolation key |
+| `threadId` | for semantic ops | Thread isolation; optional for resource-scoped working memory |
+| `embedder` | yes | Host-owned or package hash embedder |
+| `vectorStore` / `workingStore` | no | Defaults to in-memory adapters |
+| `schema` / `validateWorkingMemory` | no | Working-memory shape checks (JSON Schema subset or host hook) |
+| `workingMemoryTemplate` | no | `{{path}}` template for context injection |
+| `limits` | no | top-K, adjacent range, batch, payload, injected-token caps |
+| `redactor` / `secrets` | no | Redact text/metadata before persist/inject |
+
+Semantic indexing:
+
+```ts
+await memory.remember({ entries: [{ id, text, metadata?, sequence? }] }, { wait?: boolean })
+```
+
+Semantic recall:
+
+```ts
+await memory.recall(query, { topK?, messageRange?, signal? })
+```
+
+## Outputs / response / events
+
+| API | Result |
+| --- | --- |
+| `updateWorking` / `getWorking` | Versioned `WorkingMemoryRecord` |
+| `remember` | `{ accepted, pending, done }` — default `wait: false` indexes asynchronously |
+| `recall` | `{ hits, adjacent }` tenant/thread scoped |
+| `createContextProvider()` | Inert `ContextProvider` blocks for working and/or semantic text |
+| `createWorkingMemoryProcessor({ extract })` | Explicit host-invoked updater; never auto-runs |
+
+No package-owned agent events are emitted. Injection uses existing context assembly only.
+
+## Request/response example
+
+```json
+{
+  "tenantId": "t1",
+  "resourceId": "user-ada",
+  "threadId": "thread-1",
+  "working": { "name": "Ada", "preferences": { "format": "concise" } },
+  "recall": {
+    "query": "preferred response format",
+    "topK": 5,
+    "messageRange": 1
+  }
+}
+```
+
+## Implementation example
+
+```ts
+import { createAgent, createMockProvider, providerDone, providerTextDelta } from "@arnilo/prism";
+import { createHashEmbedder, createMemory } from "@arnilo/prism-memory";
+
+const memory = createMemory({
+  tenantId: "t1",
+  resourceId: "user-ada",
+  threadId: "thread-1",
+  embedder: createHashEmbedder(),
+  workingMemoryTemplate: "Name: {{name}}; Format: {{preferences.format}}",
+  schema: {
+    type: "object",
+    properties: {
+      name: { type: "string" },
+      preferences: {
+        type: "object",
+        properties: { format: { type: "string" } },
+        required: ["format"],
+        additionalProperties: false,
+      },
+    },
+    required: ["name"],
+    additionalProperties: false,
+  },
+});
+
+await memory.updateWorking({ name: "Ada", preferences: { format: "concise" } });
+await memory.remember({ entries: [{ id: "m1", text: "Prefers concise answers" }] });
+
+const agent = createAgent({
+  model: { provider: "mock", model: "demo" },
+  provider: createMockProvider([providerTextDelta("Got it."), providerDone()]),
+  context: [memory.createContextProvider()],
+});
+```
+
+PostgreSQL/pgvector:
+
+```ts
+import { createPostgresMemoryStores, createMemory, createHashEmbedder } from "@arnilo/prism-memory";
+
+const stores = await createPostgresMemoryStores({
+  connectionString: process.env.DATABASE_URL!,
+  schema: "prism_memory",
+  dimensions: 32,
+});
+
+const memory = createMemory({
+  tenantId: "t1",
+  resourceId: "user-ada",
+  threadId: "thread-1",
+  embedder: createHashEmbedder({ dimensions: 32 }),
+  workingStore: stores.workingStore,
+  vectorStore: stores.vectorStore,
+});
+```
+
+## Extension and configuration notes
+
+- 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 (`@arnilo/prism-compaction-observational-memory`) remains unchanged and composable.
+- Profile bundles do not include this package yet.
+
+Shared conformance:
+
+```ts
+import { runMemoryConformance, createHashEmbedder, createMemoryVectorStore, createMemoryWorkingStore } from "@arnilo/prism-memory";
+
+await runMemoryConformance(() => ({
+  embedder: createHashEmbedder(),
+  vectorStore: createMemoryVectorStore(),
+  workingStore: createMemoryWorkingStore(),
+}));
+```
+
+## Security and performance notes
+
+- Every write/query/delete requires `tenantId` + `resourceId`; semantic paths also require `threadId`.
+- Cross-tenant and cross-thread access is denied.
+- 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.
+- Default `remember()` does not block agent completion; pass `{ wait: true }` when indexing must finish first.
+- PostgreSQL live suite is gated by `PRISM_TEST_POSTGRES_URL` and requires the `vector` extension.
+
+## Delegated-agent isolation
+
+Supervisor child factories receive unique derived `resourceId` and `threadId` values. Construct each child's `createMemory()` facade from those exact values; never reuse parent memory scope or let model-supplied IDs select another resource.
+
+## Related APIs
+
+- [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.
+- [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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arnilo/prism",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "description": "Agent harness for AI providers, agents, sessions, and tools.",
   "type": "module",
   "main": "./dist/index.js",
@@ -54,6 +54,10 @@
       "types": "./dist/testing/run-ledger-conformance.d.ts",
       "default": "./dist/testing/run-ledger-conformance.js"
     },
+    "./testing/feedback": {
+      "types": "./dist/testing/feedback.d.ts",
+      "default": "./dist/testing/feedback.js"
+    },
     "./node/config": {
       "types": "./dist/node/config.d.ts",
       "default": "./dist/node/config.js"
@@ -95,6 +99,7 @@
     "!dist/__tests__",
     "!dist/**/*.map",
     "docs",
+    "templates",
     "CHANGELOG.md"
   ],
   "workspaces": [
@@ -108,6 +113,11 @@
     "packages/coding-agent",
     "packages/coding-security",
     "packages/workflows",
+    "packages/evals",
+    "packages/memory",
+    "packages/rag",
+    "packages/server",
+    "packages/supervisor",
     "packages/prism-*"
   ],
   "scripts": {
@@ -116,7 +126,7 @@
     "typecheck": "npm run build && npm run typecheck --workspaces --if-present && tsc -p examples --noEmit",
     "test": "npm run build && node --test dist/__tests__/*.test.js && npm run test --workspaces --if-present",
     "pack:dry-run": "npm pack --dry-run && npm run pack:dry-run --workspaces --if-present",
-    "test:postgres": "npm run test:postgres --workspace @arnilo/prism-session-store-postgres",
+    "test:postgres": "npm run test:postgres --workspace @arnilo/prism-session-store-postgres && npm run test:postgres --workspace @arnilo/prism-memory",
     "release:dry-run": "npm run sdk:ready",
     "release:check": "node scripts/release.mjs check",
     "release:publish": "node scripts/release.mjs publish",

package/templates/init/README.md.tmpl

@@ -0,0 +1,28 @@
+# __PROJECT_NAME__
+
+Minimal Prism agent scaffold generated by `prism init`.
+
+__PROVIDER_README_NOTE__
+
+## Setup
+
+```bash
+npm install
+npm test
+```
+
+`npm test` always uses the built-in mock provider (no network, no credentials).
+
+__NEXT_STEPS_LIVE__
+
+## Layout
+
+- `src/agent.ts` — creates the agent with the selected provider.
+- `src/index.ts` — runs one prompt and prints `AgentRunResult.text`.
+- `src/__tests__/agent.test.ts` — offline mock smoke test.
+__OPTIONAL_DOCS__
+## Notes
+
+- Prism does not auto-load credentials, databases, telemetry, or tools.
+- Keep real secrets out of git; `.gitignore` excludes `.env` and local stores.
+- Docs: https://github.com/ashiqrniloy/prism

package/templates/init/env.example.tmpl

@@ -0,0 +1 @@
+__ENV_EXAMPLE__

package/templates/init/gitignore.tmpl

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

package/templates/init/optional/evals-example.ts.tmpl

@@ -0,0 +1,17 @@
+import type { AgentRunResult } from "@arnilo/prism";
+import { defineScorer, scoreRun } from "@arnilo/prism-evals";
+
+/**
+ * Deterministic scorer example. Not wired into `npm start` — call after a run.
+ */
+export const greetsScorer = defineScorer({
+  id: "greets",
+  score: ({ result }) => ({
+    score: /\bhello\b/i.test(result.text) ? 1 : 0,
+    reason: "checks for a hello greeting",
+  }),
+});
+
+export async function scoreGreeting(result: AgentRunResult) {
+  return scoreRun({ result, scorers: [greetsScorer] });
+}

package/templates/init/optional/workflows-example.ts.tmpl

@@ -0,0 +1,27 @@
+import {
+  createMemoryWorkflowCheckpoints,
+  defineWorkflow,
+  functionNode,
+  runWorkflow,
+} from "@arnilo/prism-workflows";
+
+/**
+ * Tiny workflow example. Not wired into `npm start` — import and call from your host.
+ */
+export async function runHelloWorkflow(name: string) {
+  const workflow = defineWorkflow({
+    id: "hello",
+    nodes: {
+      greet: functionNode({
+        execute: async (ctx) => {
+          const input = ctx.workflowInput as { name?: string };
+          return { message: `Hello, ${input.name ?? name}` };
+        },
+      }),
+    },
+  });
+
+  return runWorkflow(workflow, { name }, {
+    checkpoints: createMemoryWorkflowCheckpoints(),
+  });
+}

package/templates/init/package.json.tmpl

@@ -0,0 +1,22 @@
+{
+  "name": "__PROJECT_NAME__",
+  "version": "0.0.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"
+  },
+  "dependencies": {
+__DEPENDENCIES__
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}