@arnilo/prism 0.11.0 → 0.12.0

package/docs/history/130-cyclic-workflows-primitive-review.md

@@ -0,0 +1,293 @@
+# Cyclic Workflows Primitive Review: Loop/Graph Primitives and Superstep Engine Justification
+
+Plan: [130-Cyclic-Workflow-Graphs.md](../../plans/130-Cyclic-Workflow-Graphs.md) Task 1  
+Date: 2026-09-25  
+Baseline: Release `0.11.0` / `0.12.0` line in progress  
+Scope: Primitive inventory, capability gap analysis, alternative evaluation, and architectural justification for cyclic workflow execution in `@arnilo/prism-core/runtime/workflows`.
+
+---
+
+## 1. Executive Summary & Review Scope
+
+This review freezes the architectural inventory, capability gap analysis, alternative evaluation, and design justification for **Plan 130: Cyclic Workflow Graphs (Superstep Execution + Dynamic Routing)**.
+
+### 1.1 Context and Problem Statement
+
+Modern agentic architectures heavily depend on cyclic patterns:
+- **Reflection loops**: A worker agent drafts a deliverable, a reviewer agent critiques or tests it, and back-edges route revisions to the worker until acceptance criteria are satisfied.
+- **Planner ↔ Executor interleavings**: A planner decomposes an evolving problem, an executor carries out sub-tasks and observes environmental feedback, and control cycles back to the planner to adjust future actions.
+- **Model-driven dynamic routing**: A node inspects intermediate state or LLM output and dynamically chooses which branch to activate next, creating conversational multi-turn workflows.
+
+In `@arnilo/prism-core/runtime/workflows` today, all workflow definitions are enforced to be Directed Acyclic Graphs (DAGs). Attempting to declare an edge that introduces a cycle triggers an immediate, unconditional validation failure:
+```
+WorkflowDefinitionError: Workflow graph contains a cycle
+```
+(`packages/prism-core/src/runtime/workflows/define.ts:L141`).
+
+Hosts seeking cyclic behavior are forced to either:
+1. Collapse multi-agent cycles into a single monolithic `loopNode` body, destroying per-node observability, telemetry, and checkpointing.
+2. Externalize the loop to host application code by repeatedly invoking `runWorkflow`, sacrificing durable single-run lifecycle, lease coordination, and unified state history.
+
+### 1.2 Review Objectives
+
+1. **Inventory existing primitives**: Rigorously analyze `loopNode`, `conditionalNode`, `fanOutNode`/`joinNode`, `suspend`/`resumeWorkflow`, `replayWorkflow`, and supervisor delegation to document what is already achievable today without new runtime machinery.
+2. **Name the capability gaps precisely**: Articulate why existing primitives cannot cleanly express multi-agent cyclic collaboration.
+3. **Evaluate and reject alternatives**: Critically assess candidate approaches (monolithic `loopNode` bodies, host-side recursion, event-driven reactive topologies, and Kahn scheduler indegree resets) with definitive architectural rationale.
+4. **Justify the chosen design**: Detail why a Bulk Synchronous Parallel (BSP) / Pregel-inspired **superstep activation engine** with explicit bounds (`limits.maxSupersteps`), per-node activation semantics (`"all" | "any"`), and dynamic routing (`routeNode`) provides the minimal, fail-closed, and industry-aligned primitive set.
+5. **Restate fail-closed invariants**: Ensure budget bounding, secret redaction, execution policy enforcement, and bit-for-bit backward compatibility remain strictly preserved.
+
+---
+
+## 2. Inventory of Existing Primitives (What is Achievable Today)
+
+Before introducing any new runtime primitive, Prism requires an exhaustive audit of existing primitives to prove that the proposed capability cannot be cleanly composed from what already ships.
+
+| Primitive / Surface | Source Location | Existing Contract & Capabilities | Achievable Workload Patterns | Inherent Boundary / Limitation |
+|---|---|---|---|---|
+| **`loopNode` (inline body)** | `packages/prism-core/src/runtime/workflows/types.ts:L155`, `run/node-execution.ts:L360-L420` | Executes an inline async function `execute(ctx)` repeatedly until `until(ctx)` evaluates to `true` or `maxIterations` (default/hard cap 64) is reached. Checkpoints iteration records (`WorkflowLoopIterationRecord[]`) into the node's state. | - Single-agent iterative refinement (e.g. LLM self-correction prompt loop within one session).<br>- Polling external resources until ready.<br>- Numerical relaxation / convergence loops. | The entire loop is encapsulated inside **one single graph node**. Downstream edges cannot be reached until the loop completely terminates. Cannot host multiple distinct graph nodes per iteration. |
+| **`loopNode` (sub-step body)** | `packages/prism-core/src/runtime/workflows/types.ts:L163`, `run/node-execution.ts:L420-L460` | Executes a single interior `function` or `tool` node definition repeatedly with `until(ctx)`. Supports durable suspension before tool side effects. | - Bounded tool retries with approval gates.<br>- Repeated execution of a single atomic tool or function. | Restricted to exactly **one** child function or tool definition (`WorkflowLoopBodyDefinition`). Cannot express multi-node sub-graphs (e.g. Worker -> Tool -> Reviewer). |
+| **`conditionalNode`** | `packages/prism-core/src/runtime/workflows/types.ts:L175`, `run/skip.ts:L6-L25` | Evaluates predicate `when(ctx)`. Activates static `then?: string[]` successors when true, or `else?: string[]` successors when false. Unchosen branches are transitively marked `skipped`. | - Binary branching in DAGs (e.g., pass vs fail paths).<br>- Bypassing expensive downstream stages.<br>- Static forward routing. | Edges must be strictly forward and acyclic. Routing targets are static configuration lists, not dynamic expressions. Cannot route backwards or repeat nodes. |
+| **`fanOutNode` & `joinNode`** | `packages/prism-core/src/runtime/workflows/types.ts:L184,L191`, `run/node-execution.ts:L330-L360` | `fanOutNode` dynamically maps an array of items across concurrent workers within `concurrency` and `maxFanOut`. `joinNode` reduces upstream outputs into an aggregated value. | - Parallel role specialist execution (Hierarchical Crew pattern, `docs/multi-agent-patterns.md`).<br>- Map-reduce pipelines. | Strictly one-shot forward DAG execution. Re-running the fan-out based on join output requires an external loop. |
+| **`suspend()` & `resumeWorkflow()`** | `packages/prism-core/src/runtime/workflows/run/main.ts`, `run/checkpoint.ts` | Allows any node to return `suspend({ reason, data?, resumeSchema? })`, saving a `status: "suspended"` checkpoint. `resumeWorkflow` claims the checkpoint with CAS `expectedVersion` and re-invokes the node with `ctx.resume`. | - Durable human-in-the-loop approval gates.<br>- Asynchronous webhooks and external confirmations.<br>- Zero-process suspension while awaiting input. | Re-enters the **same** suspended node only. It does not rewind, loop back, or branch to earlier nodes in the graph. |
+| **`replayWorkflow()`** | `packages/prism-core/src/runtime/workflows/replay.ts` | Forks an existing succeeded run from a specific node (`fromNodeId`), copying terminal evidence outside the downstream closure and executing downstream nodes anew under an immutable lineage record. | - Re-evaluating a downstream DAG segment with modified inputs.<br>- Auditing and scenario counterfactual testing. | Spawns a **new independent run** (`runId` changes, separate checkpoint stream). It is a post-hoc replay utility, not an in-flight control-flow loop. |
+| **Supervisor delegation** | `packages/prism-core/src/runtime/supervisor/`, `src/contracts.ts` | A parent agent session delegates tasks to allow-listed child agent sessions via `supervisor.delegate()` or `createSpawnAgentTool`. | - Dynamic sub-agent spawning during a conversational turn.<br>- Hierarchical tool dispatch. | Operates at the agent/session runtime level, not the workflow graph level. Lacks graph-level checkpoints, workflow state transactions, DAG event scheduling, and topological visualization. |
+
+### 2.1 Pattern Coverage Matrix
+
+Evaluating common multi-agent workflow patterns against the existing primitive set confirms what can and cannot be built today:
+
+| Workflow Pattern | Expressible with Existing Primitives? | How it is Composed Today | Limitation / Compromise Incurred |
+|---|:---:|---|---|
+| **Single-Agent Self-Correction** | **Yes** | `loopNode` with inline `execute` or `generateValidateReviseLoop` (`src/agent-loops.ts:L37`). | Confined to one prompt/turn loop within one agent session. |
+| **Static Branching Pipeline** | **Yes** | `conditionalNode` with `then` / `else` edge lists. | Forward only; cannot loop back on quality failure. |
+| **Hierarchical Crew (One-Shot)** | **Yes** | Manager `agentNode` -> `fanOutNode` specialists -> `joinNode` aggregator (`examples/crew-hierarchy.ts`). | Complete DAG execution; revision requires re-instantiating the pipeline. |
+| **Human-in-the-Loop Review Gate** | **Yes** | `functionNode` calling `suspend()`; resumed via `resumeWorkflow()`. | Pauses pipeline cleanly, but cannot send the deliverable back to an earlier worker node upon rejection. |
+| **Multi-Agent Reflection Loop**<br>*(Worker -> Reviewer -> Worker until approved)* | **No** | **Fails validation** (`Workflow graph contains a cycle`). | Forces embedding all roles into a single `loopNode.execute`, losing distinct graph nodes, per-role telemetry, and discrete checkpoints. |
+| **Planner ↔ Executor Cyclic Interleaving** | **No** | **Fails validation** (`Workflow graph contains a cycle`). | Requires host-side while-loop wrapping `runWorkflow`, fragmenting state across multiple disconnected runs. |
+| **Model-Driven Dynamic Successor Selection** | **No** | Static `conditionalNode` branching only. | Cannot dynamically compute a target successor set from LLM output without pre-declaring rigid combinations. |
+
+---
+
+## 3. The Capability Gap
+
+The audit identifies three fundamental capability gaps that prevent `@arnilo/prism-core/runtime/workflows` from serving as a complete substrate for cyclic multi-agent systems:
+
+### Gap 1: Per-Node Checkpointing, Events, and Attribution Inside an Iteration
+
+In multi-agent systems, collaboration occurs between distinct roles with distinct configurations (different system instructions, different models, different tool allow-lists, and distinct permissions).
+- In a reflection cycle, Worker and Reviewer must be observable as distinct steps on the execution timeline (`projectWorkflowTimeline`).
+- When all logic is crammed into a single `loopNode`, the workflow engine emits only `node_iteration_started` / `node_iteration_finished` for the outer loop node. There are no discrete `node_started`, `node_finished`, or `agent_event` records distinguishing the Worker phase from the Reviewer phase within an iteration.
+- If a crash or timeout occurs during Reviewer execution in iteration 4, checkpoint recovery cannot identify that the Worker succeeded and only the Reviewer needs re-execution; the entire composite iteration is lost or must be re-run from the beginning.
+- Furthermore, per-node resource limits (such as `timeoutMs`, `retries`, and `maxNodeOutputBytes`) apply to the whole loop rather than being enforced independently on Worker and Reviewer.
+
+### Gap 2: Mixed Node Kinds per Iteration
+
+A realistic iterative cycle rarely consists of a single function. A standard software engineering agent workflow consists of:
+1. `agentNode` ("planner"): analyzes requirements and drafts changes.
+2. `toolNode` ("linter_and_test_runner"): executes local tests or build commands in a sandbox.
+3. `agentNode` ("code_reviewer"): reviews code diffs and test output.
+4. `conditionalNode` or routing decision: decides whether to commit or loop back to "planner".
+
+Today's `loopNode` supports only two shapes:
+- `InlineLoopNodeDefinition`: a single raw JavaScript function `execute(ctx)`.
+- `NodeLoopNodeDefinition`: a single child `WorkflowLoopBodyDefinition` (either one function or one tool).
+
+It is syntactically and architecturally impossible to declare a heterogeneous graph of agents, tools, and conditionals inside a `loopNode` without manually simulating a mini-orchestrator inside the `execute` callback.
+
+### Gap 3: Dynamic Successor Activation
+
+Prism's `conditionalNode` requires pre-defining static arrays of successors: `then?: readonly string[]` and `else?: readonly string[]`.
+- In dynamic agentic workflows (e.g. LangGraph's `Command(goto=...)` or AutoGen's dynamic routing), an agent or classifier inspects data and selects one or more destinations from a set of declared valid routes (e.g., `["revise_code"]`, `["request_clarification"]`, `["escalate_to_human"]`, `["deploy"]`).
+- Expressing dynamic multi-way routing using binary `conditionalNode`s requires cascading trees of dummy nodes that clutter the graph, complicate Mermaid/DOT exports, and degrade execution latency.
+- There is currently no primitive that allows a node to evaluate a dynamic selector function (`select: (ctx) => string[]`) and activate only the chosen subset of declared successor edges.
+
+---
+
+## 4. Evaluation of Rejected Alternatives
+
+Four architectural alternatives were considered to address these gaps. Each was rejected based on Prism's design principles:
+
+### Alternative A: Monolithic `loopNode.execute` Bodies (Do Nothing / Status Quo)
+
+- **Description**: Recommend that hosts implement reflection loops by putting all role coordination inside a single `loopNode` whose `execute` function imperatively invokes multiple `AgentSession`s or functions.
+- **Why Rejected**:
+  1. **Destroys Observability**: Telemetry events (`WorkflowEvent`) are emitted only at node boundaries. The inner multi-agent dialogue becomes an opaque black box to event subscribers, AG-UI, and OpenTelemetry spans.
+  2. **Coarse-Grained Checkpointing**: Checkpoint writes occur at the node or loop-iteration boundary. Individual agent steps within the iteration are uncheckpointed.
+  3. **Loss of Graph Topology**: Graph serialization (`serializeWorkflowGraph`), Mermaid diagrams (`workflowGraphToMermaid`), and DOT views cannot visualize the agent interaction topology because it exists only as procedural TypeScript code inside a closure.
+  4. **Violation of Declarative Orchestration**: Forces hosts to reinvent agent execution, error handling, and parameter passing instead of relying on the workflow engine's proven lifecycle.
+
+### Alternative B: Host-Side Recursion Over `runWorkflow`
+
+- **Description**: Hosts execute a workflow representing one iteration (e.g. Worker -> Reviewer). If the reviewer requests revisions, the host application code calls `runWorkflow` again with the previous run's output passed as input.
+- **Why Rejected**:
+  1. **Fragmented Durability**: Each iteration becomes a separate `runId`. There is no unified checkpoint history, no aggregate execution timeline, and no single source of truth for the complete business task.
+  2. **Broken Coordination and Fencing**: `createWorkflowCoordinator` leases and executes single workflow runs. If an iterative task is split into multiple independent runs, workers cannot maintain atomic lease ownership or guarantee fair scheduling across the complete task lifecycle.
+  3. **Suspension Failure**: If a human-in-the-loop review is requested in iteration 3, `suspend()` pauses only that discrete sub-run. The host application must build custom stateful machinery to remember which iteration it was on and restart the outer loop when the sub-run resumes.
+  4. **Lineage Overhead**: Tracking provenance requires external bookkeeping or chaining dozens of `replayWorkflow` lineage records, multiplying database records and memory overhead.
+
+### Alternative C: Event-Driven Topology (Reactive / Typed Event Bus as Edges)
+
+- **Description**: Replace explicit graph edges with a pub/sub event bus where nodes emit typed domain events and downstream nodes subscribe to event patterns (similar to LlamaIndex Workflows).
+- **Why Rejected / Deferred**:
+  1. **Authoring Model Divergence**: Prism's workflow system is built around explicit, auditable graph topologies (`WorkflowDefinition.edges`). An event-driven architecture is a fundamentally different authoring paradigm, not merely a missing primitive.
+  2. **Static Auditability**: Security and compliance teams inspect Prism workflow graphs to verify dataflow boundaries and authorization constraints. In a purely event-driven model, finding the complete topology requires runtime tracing or complex static analysis.
+  3. **Cycle Bound Complexity**: Detecting cycles and enforcing fail-closed iteration bounds (`maxSupersteps`) becomes significantly harder when connections are dynamic event channels rather than static adjacency lists.
+  4. **Composability**: Hosts needing event-driven routing can already compose it cleanly today using `conditionalNode`s inspecting shared JSON state (`ctx.state`).
+
+### Alternative D: Extending the Kahn Scheduler with Indegree Resets
+
+- **Description**: Maintain the existing Kahn topological sort algorithm in `packages/prism-core/src/runtime/workflows/run/scheduler.ts`, but allow backward edges. When a backward edge fires, decrement or reset the target node's `remainingIndegree` so it re-enters the `state.ready` queue.
+- **Why Rejected**:
+  1. **The Kahn Deadlock Trap**: Kahn's algorithm relies on the invariant that indegree reaches zero only when *all* upstream dependencies have completed. On a cyclic graph, a node that has both an initial entry edge (from a start node) and a back-edge (from a reviewer) has an initial indegree of 2. In iteration 1, it can never start because the back-edge has not run yet (deadlock). If the scheduler ignores back-edges on entry, it must know which edges belong to which iteration wave—introducing ad-hoc state tracking that breaks down when multiple concurrent branches exist.
+  2. **Indegree Reset Ambiguity**: When multiple predecessors exist in a cycle, resetting indegrees on completion of any single predecessor causes premature activations; waiting for all causes deadlocks. This is the precise deadlock flaw identified in early AutoGen and solved in Microsoft Agent Framework (MAF) by moving to explicit activation semantics.
+  3. **Regression Risk to DAG Execution**: Mutating the battle-tested, zero-overhead Kahn drain loop threatens bit-for-bit backward compatibility and performance on existing acyclic workflows.
+
+---
+
+## 5. Industry Survey & Baseline Comparisons
+
+To ensure Prism adopts proven, interoperable, and industry-standard primitives, we benchmarked the three leading agent workflow frameworks:
+
+| Framework | Cyclic Execution Mechanism | Loop Bound Guardrail | Node Activation Semantics | Dynamic Routing Primitive |
+|---|---|---|---|---|
+| **LangGraph** (`StateGraph`) | Cyclic edges allowed in graph definition. Nodes write to shared state. Superstep execution rounds synchronize parallel node executions. | `recursion_limit` (default: 25). Throws `GraphRecursionError` on breach. | Superstep wave: all nodes activated in step $N$ execute concurrently; their outputs trigger step $N+1$. | `Command(goto="node_id")` and conditional edges returning dynamic node strings. |
+| **Microsoft Agent Framework (MAF)** | Bulk Synchronous Parallel (BSP) / Pregel-inspired supersteps. Iterations advance through synchronization barriers. Run succeeds on **idle drain**. | `max_iterations` (default: 100). Fails closed on breach. | Activation conditions (`all` vs `any`) configured per edge group. | Dynamic executor routing via message destinations. |
+| **AutoGen** (GraphFlow) | Directed cyclic graphs with message-passing semantics between agents. | `max_turns` / iteration limits configured per conversation pattern. | Per-node `activation_condition`: `"all"` (all predecessors must arrive) vs `"any"` (any predecessor arrival fires node). | Dynamic speaker selection via selector functions / LLM judge. |
+
+### 5.1 Key Industry Lessons Adopted by Prism
+
+1. **The Superstep / Wave Execution Model is the Standard**: Both LangGraph and Microsoft Agent Framework execute cyclic graphs in discrete superstep waves. All active nodes in wave $K$ execute up to configured concurrency; completed nodes post activations for wave $K+1$; an execution barrier synchronizes the transition.
+2. **Termination via Idle Drain**: In a cyclic graph, there is no single fixed "leaf" node. A run naturally and successfully terminates when all pending activations are exhausted and no nodes are currently running (the MAF model).
+3. **Explicit Activation Semantics (`"all"` vs `"any"`) Eliminate Deadlocks**: To allow a node to serve both as a workflow entry point and as the recipient of a cycle back-edge, nodes must support `activation: "any"`. Nodes requiring multi-branch synchronization (joins within a cycle) use `activation: "all"`.
+4. **Constrained Dynamic Routing (`routeNode`)**: Dynamic routing must be constrained to a statically declared successor set. This provides model-driven flexibility (LangGraph `Command(goto)`) while maintaining topological auditability and preventing unvetted arbitrary jumps.
+
+---
+
+## 6. Justification of the Superstep Engine & Prism Design Synthesis
+
+Based on the primitive review, capability gap analysis, and industry survey, Plan 130 synthesizes these requirements into a cohesive, minimal design:
+
+### 6.1 Architecture Overview
+
+```
+                               Workflow Definition
+                                        │
+                         Is graph cyclic OR opt-in?
+                                   ┌────┴────┐
+                                  No        Yes
+                                   │         │
+                     Kahn DAG Scheduler   Superstep Engine
+                     (Bit-for-bit unchanged)   (run/superstep.ts)
+                                             │
+                       ┌─────────────────────┴─────────────────────┐
+                       │  Wave Loop: superstep = 0 .. maxSupersteps  │
+                       │  1. Check budget: superstep < max          │
+                       │  2. Drain pendingActivations into wave     │
+                       │  3. Execute wave within concurrency pool   │
+                       │  4. Nodes complete -> onNodeSucceeded      │
+                       │     - routeNode / conditional evaluate     │
+                       │     - Post activations (all vs any rule)   │
+                       │  5. Barrier: wait for wave completion      │
+                       │  6. Batch persist checkpoint (Schema v2)   │
+                       │  7. Check Idle Drain -> Success            │
+                       └───────────────────────────────────────────┘
+```
+
+### 6.2 Core Design Pillars
+
+#### 1. Opt-In Cycle Policy with Fail-Closed Bounding
+- In `defineWorkflow`, graphs containing cycles are rejected with `WorkflowDefinitionError: Workflow graph contains a cycle` unless `limits.maxSupersteps` is explicitly declared.
+- `limits.maxSupersteps` is validated via the existing `validateWorkflowLimit` helper (positive safe integer, 1 to `HARD_MAX_SUPERSTEPS = 256`).
+- Cyclic runs increment `state.superstep` on each wave. If `state.superstep >= limits.maxSupersteps` and pending work remains, execution immediately aborts and fails closed with `WorkflowSuperstepLimitError` (`ERR_PRISM_WORKFLOW_SUPERSTEP_LIMIT`).
+
+#### 2. Dual-Engine Dispatch (Zero DAG Regressions)
+- The execution engine is selected deterministically at run start:
+  - If the definition is acyclic and does not declare `maxSupersteps`, the engine uses the existing `executeSchedulerBody` Kahn path bit-for-bit. Existing tests, event sequences, and checkpoint formats remain completely undisturbed.
+  - If the definition contains cycles or opts into supersteps, the run dispatches to `run/superstep.ts`.
+- Both engines share a unified completion seam: `onNodeSucceeded(state, nodeId, options, emit)`.
+
+#### 3. Per-Node Activation Semantics (`"all"` vs `"any"`)
+- Every node definition inherits `activation?: "all" | "any"` on `WorkflowNodeBase` (default `"all"`).
+- **`"all"`**: The node activates only when *every* declared predecessor has fired and contributed an activation since the node's last execution.
+- **`"any"`**: The node activates whenever *any* predecessor fires. This enables cycle re-entry nodes (e.g. `worker` receiving entry from `start` or feedback from `reviewer`) to re-fire smoothly without deadlocking.
+- Fail-closed validation: Declaring `activation: "any"` on a node with zero predecessors is rejected at definition time as invalid configuration.
+
+#### 4. Dynamic Routing Primitive (`routeNode`)
+- Exported factory: `routeNode({ select })`.
+- Definition shape: `RouteNodeDefinition` (`kind: "route"`, `select: (ctx) => readonly string[] | Promise<readonly string[]>`).
+- Execution contract:
+  - Evaluates `select(ctx)` against current state and upstream data.
+  - Returns a subset of declared successor node IDs to activate next wave.
+  - Runtime validation: All returned target IDs must be a subset of the node's declared successor edges in `workflow.edges`. An unknown target throws `WorkflowRuntimeError` (`ERR_PRISM_WORKFLOW_ROUTE_TARGET`) fail closed, preventing unauthorized control flow jumps.
+  - Returning `[]` activates nothing, contributing to natural idle drain.
+
+#### 5. Durable Checkpoints (Schema v2)
+- Extends `WorkflowCheckpointValue` with an additive `execution` block:
+  ```ts
+  execution?: {
+    readonly mode: "supersteps";
+    readonly superstep: number;
+    readonly maxSupersteps: number;
+    readonly pending: Readonly<Record<string, { readonly from: readonly string[]; readonly round: number }>>;
+  }
+  ```
+- Increments `WORKFLOW_CHECKPOINT_SCHEMA_VERSION` from `1` to `2`.
+- Checkpoints from cyclic runs record node execution histories through the existing per-node `iterations[]` ledger (`WorkflowLoopIterationRecord`), avoiding unbounded growth while enabling mid-cycle `suspend()` and exact-once CAS resumption via `resumeWorkflow`.
+- Checkpoint persistence cadence: exactly one checkpoint written per wave boundary, ensuring that wave-based execution matches or improves upon today's per-node write overhead.
+
+---
+
+## 7. Universal Invariants, Security Posture, and Threat Model
+
+The superstep engine preserves all Prism universal invariants and defends against specific threat vectors introduced by cyclic topologies:
+
+| Invariant / Threat Vector | Required Posture & Engine Enforcement |
+|---|---|
+| **Bounded Execution Budgets** | Cyclic workflows can easily become infinite money/resource sinks if unconstrained. The engine enforces an explicit `limits.maxSupersteps` (1–256). Exceeding this ceiling fails closed immediately with `WorkflowSuperstepLimitError` before dispatching any over-budget provider calls or tool actions. |
+| **Fail-Closed Definition Validation** | A definition with cycles and no declared `limits.maxSupersteps` throws `WorkflowDefinitionError("Workflow graph contains a cycle")` with the exact historical error message. Self-loops (`["nodeA", "nodeA"]`) remain strictly forbidden. |
+| **Controlled Control Flow (No Goto-Anywhere)** | `routeNode` cannot execute arbitrary jumps across the system. The selector's returned targets are validated at runtime against declared successors (`targets ⊆ declaredSuccessors`). Any undeclared target fails closed with `ERR_PRISM_WORKFLOW_ROUTE_TARGET`. |
+| **Credential and Identity Isolation** | Node executions in cyclic waves reuse the standard `runNode` harness. Cycles do not widen tool allow-lists, relax `ExecutionPolicy` checks, or grant access to credentials. Tenant, account, and user ownership scopes propagate immutably across waves. |
+| **Secret Redaction Across Waves** | Outputs from cyclic node executions and payloads stored in `pendingActivations` pass through `SecretRedactor` before being written to checkpoint stores or emitted over the `WorkflowEventBus`. |
+| **Checkpoint Integrity & Tamper Resistance** | Checkpoint schema v2 persists `superstep` counters and pending activations under CAS versioning. Resuming a cyclic run requires verifying `definitionHash`, ensuring that workflow topology or limits cannot be tampered with between suspension and resumption. |
+| **Process Safety Hard Caps** | All existing byte caps (`maxNodeOutputBytes` 4 MiB/16 MiB, `maxCheckpointBytes` 1 MiB/8 MiB, `maxStateBytes` 64 KiB/512 KiB) remain strictly enforced on every wave iteration. |
+
+---
+
+## 8. Plan Mapping & Downstream Task Directives
+
+This review establishes the technical baseline and contract requirements for all subsequent tasks in [Plan 130](../../plans/130-Cyclic-Workflow-Graphs.md):
+
+- **Task 2: Definition Surface (`types.ts`, `limits.ts`, `define.ts`, `nodes.ts`)**
+  - Add `maxSupersteps?: number` to `WorkflowLimits` with `HARD_MAX_SUPERSTEPS = 256`.
+  - Add `activation?: "all" | "any"` to `WorkflowNodeBase`.
+  - Add `RouteNodeDefinition` and export `routeNode()` factory.
+  - Update `defineWorkflow` to permit cycles only when `limits.maxSupersteps` is present, tagging the definition with `execution: "supersteps"`.
+- **Task 3: Superstep Scheduler Engine (`run/superstep.ts`, `run/scheduler.ts`)**
+  - Implement wave execution loop with synchronization barrier and idle-drain termination.
+  - Implement round-based activation bookkeeping with `"all"` and `"any"` semantics.
+  - Extract shared `onNodeSucceeded` seam between Kahn and superstep engines.
+  - Introduce `WorkflowSuperstepLimitError` (`ERR_PRISM_WORKFLOW_SUPERSTEP_LIMIT`).
+- **Task 4: `routeNode` Dynamic Routing End-to-End**
+  - Wire `routeNode` execution in `run/node-execution.ts`.
+  - Enforce declared successor subset validation and runtime fail-closed checks.
+- **Task 5: Checkpoint Schema v2 (`run/checkpoint.ts`, `types.ts`, `limits.ts`)**
+  - Bump `WORKFLOW_CHECKPOINT_SCHEMA_VERSION = 2`.
+  - Persist `execution` block with `superstep`, `maxSupersteps`, and `pending` activations.
+  - Implement CAS resume for mid-cycle suspended runs.
+- **Task 6: Replay, Serialization, and Graph Export (`replay.ts`, `graph-export.ts`)**
+  - Support latest-iteration evidence resolution for replay on cyclic graphs.
+  - Update Mermaid and DOT exporters to render cycle back-edges cleanly.
+- **Task 7: Example (`examples/cyclic-reflection.ts`)**
+  - Build an offline, zero-network multi-agent reflection and dynamic routing demonstration.
+- **Task 8: Documentation Updates (`docs/workflows.md`, `docs/index.md`)**
+  - Update public documentation with cyclic workflow guide, limits, and node kind references.
+- **Task 9: Final Verification (`release:gate`)**
+  - Execute full test suites, typechecks, and compatibility gates.
+
+---
+
+## 9. Conclusion
+
+Existing Prism primitives (`loopNode`, `conditionalNode`, `fanOutNode`, `suspend`, and `replay`) successfully address single-step iteration, parallel map-reduce, and linear pipelines, but cannot express multi-agent cyclic collaboration without sacrificing per-node observability, granular checkpointing, or declarative graph structure. 
+
+The superstep activation engine proposed in Plan 130 directly mirrors established industry standards (LangGraph supersteps, Microsoft Agent Framework BSP execution, and AutoGen activation conditions), providing a bounded, fail-closed, durable, and fully backward-compatible solution for cyclic agent workflows.

package/docs/history/132-document-ingestion-primitive-review.md

@@ -0,0 +1,124 @@
+# Document ingestion primitive review (plan 132 Task 1)
+
+Plan: [132-Anydoc-Docling-Document-Ingestion.md](../../plans/132-Anydoc-Docling-Document-Ingestion.md) Task 1
+Date: 2026-09-26
+Baseline: `@arnilo/prism` 0.11.1, Bun 1.4.2, glibc 2.44, x86_64
+Scope: where a host Markdown converter fits, and what anydoc 0.2.4 / Docling 2.130.0 actually do on this runtime. Research only. No package change.
+
+Probes lived in `/tmp/prism-132-probe` and `/tmp/prism-132-docling`. Not committed.
+
+## Seams
+
+| Seam | What it does today | Converter fit |
+| --- | --- | --- |
+| `parseDocument` / `importDocument` | ZIP-magic OOXML into an editable `DocumentModel` (`doc`/`sheet`/`deck` only). | Do not use. Different product. |
+| `createDocumentReader` / `DocumentParser` | Literal text for the coding read tool. `extract` must return `pages: number` and refuse over `maxPages`. Default peers: pdf-parse, mammoth, in-package xlsx/pptx. Mistral OCR is opt-in and posts to `api.mistral.ai`. | Do not wrap anydoc. Success Markdown has no page count, so a `pages` field would be invented. Leave the reader and Mistral OCR untouched. |
+| Wiki `extractDocument` | `{ bytes, filename, mediaType, title } → { text, format } \| null`. | Host adapter maps `{ markdown, format }` to `{ text, format }`. Do not change the hook signature. `ocrUsed` / `pages` do not fit this return; RAG metadata can carry them. |
+| RAG `Parser` | `replaceDocument({ parser })` calls `parser.parse` and indexes `text` plus metadata. No office parser. `pdfParser` is uncompressed BT/ET text only. | Host parser. No `@arnilo/prism-memory` → `@arnilo/prism-work` dependency (memory peers are only `@arnilo/prism`). |
+| `WorkSandbox.execFile` | `file`, `args`, `cwd`, `env`, `timeout`, `signal`, `onData`. No stdin. Capabilities fail closed to all-false if metadata is incomplete. Env strip is only `M365_` / `GOOGLE_`. Package does not enforce network isolation. | Not the Docling runner. A host callback must supply stdin bytes, kill-on-abort, and stdout/time caps. No new core primitive. |
+
+Wiki routing today (`packages/memory/src/wiki/ingest.ts`):
+
+- `.txt` `.md` `.json` `.csv` `.html` `.htm`: UTF-8 decode. Hook never runs. `.csv` therefore never becomes an anydoc table unless Task 4 tries the hook first when the host set one.
+- `.pdf`: RAG `pdfParser` first (hard cap 8 MiB, 256 pages). Hook only if that throws. A mixed PDF with text operators succeeds here and never asks for OCR.
+- `.png` `.jpg` `.jpeg` `.gif` `.webp`: stub extract. Hook never runs.
+- anything else (docx, xlsx, pptx, odt, rtf, epub, …): hook, or fail closed.
+
+RAG limits that matter: `HARD_MAX_PARSE_MS_CAP` is 30_000 and is not raised by `replaceDocument` itself (built-in parsers enforce it). Do not raise it for OCR. Prefetch models off the request path. Small warm scans fit 30s; a 2 GiB RSS OCR process does not belong in default CI.
+
+Trust stays at existing boundaries: wiki tool/command `trust: "untrusted_external"`; RAG `retrieveContext` trust `{ untrusted, inert, injectionCapable }`. The converter does not grant authority.
+
+## Frozen result
+
+One work-family result. Not a document model.
+
+```ts
+interface DocumentExtractionResult {
+  readonly markdown: string;
+  readonly format: string;
+  readonly ocrUsed: boolean;
+  readonly pages?: number; // omit unless the engine reported it
+}
+```
+
+- anydoc success: `ocrUsed: false`, omit `pages`.
+- anydoc `needsOcr`: throw. No markdown. Carry `pages: number[]` and `pageCount` on the error. Do not copy `error.message` into logs (it is page numbers today; do not depend on that).
+- Docling success only: `ocrUsed: true`, `pages` from `document.num_pages()`.
+- Any other Docling status, including `partial_success`: throw. No text returned.
+
+`needsOcr` is the only OCR fallback. `encrypted`, `malformed`, `unsupported`, `resourceLimit`, `missingPart`, `io`, `hosted` never call Docling.
+
+## anydoc 0.2.4 on Bun 1.4.2
+
+Published package, not GitHub `main`. `engines.node` is `>= 20`. No Bun engine field. N-API optional packages:
+
+`darwin-x64`, `darwin-arm64`, `linux-x64-gnu`, `linux-arm64-gnu`, `linux-x64-musl`, `linux-arm64-musl`, `win32-x64-msvc`.
+
+No FreeBSD, Android, riscv, or Windows ARM binary. This host loaded `@firecrawl/anydoc-linux-x64-gnu/anydoc.linux-x64-gnu.node` (glibc; ldd: libc, libm, libpthread, libgcc_s, libdl). `bun add` also installed the musl package; the loader did not map it. Do not assume npm's optional-platform filter.
+
+`toMarkdownBytes(bytes, format?, options?)` is the JS wrapper. Native conversion ignores `options`. `options.ocr === 'hosted'` catches `needsOcr` and POSTs the whole file to `https://api.firecrawl.dev/v2/parse` (or `FIRECRAWL_API_URL`). Default is reject. Probe monkeypatched `fetch`; default calls made zero network attempts.
+
+| Case | Result |
+| --- | --- |
+| `formatFromBytes` DOCX / text PDF / scan PDF | `docx` / `pdf` / `pdf` |
+| `formatFromBytes` CSV and PNG | `null` |
+| `formatFromPath('notes.csv')` / `formatFromExtension('.csv')` | `csv` |
+| DOCX 939 B | `Hello Prism DOCX\n` (17 B). Isolated convert 0.57 ms, VmHWM 58 732 KiB |
+| CSV explicit `'csv'` | GFM table, 55 B, 0.14 ms |
+| CSV omitted or `null` format | `code: 'unsupported'`. No OCR |
+| text PDF 872 B, 2 pages | `## Hello Prism PDF page 1\n\n## Hello Prism PDF page 2\n` (53 B). Isolated convert 2.13 ms, VmHWM 61 872 KiB. Warm in-process 0.78 ms |
+| image-only PDF 3007 B | `needsOcr`, `pages: [1]`, `pageCount: 1`, message `page 1 of 1 needs OCR`. No markdown. Isolated 2.02 ms |
+| mixed PDF (2 text pages + 1 scan) | `needsOcr`, `pages: [3]`, `pageCount: 3`. No partial markdown |
+| PNG / garbage | `unsupported` |
+| `toDocument` DOCX | `{ blocks, notes, assets }` only. No pages |
+| `toDocument` PDF | `unsupported` — PDF has no document model |
+
+Import of the native module: ~5–8 ms. Import-only VmHWM 56 212 KiB. No `AbortSignal`. Native work is not preemptable.
+
+Not attested by this probe: `encrypted` (no fixture), `resourceLimit` (no bomb), `hosted` (must not be called). Markdown-only API cannot attest success page count, which pages were text vs image, layout boxes, encryption-on-success, truncation, or asset bytes.
+
+## Docling 2.130.0
+
+`requires_python` is `>=3.10,<4`. This host is CPython 3.14.7. `docling==2.130.0` imports. Standard extra is `docling-slim[standard]==2.130.0` (torch, rapidocr 3.9.2). onnxruntime is not in that extra.
+
+Default PyPI torch for cp314 is the CUDA build and pulls nvidia wheels (cublas/nccl/cusolver, multi-GB). Probe killed that install and used `torch==2.14.0+cpu` and `torchvision==0.29.0+cpu` from `https://download.pytorch.org/whl/cpu`. `torch.cuda.is_available()` was false. Task 3 docs must say CPU index unless the host pins a GPU build. Python stays host-provisioned, not an npm dependency.
+
+`OcrAutoOptions` (the default, `do_ocr=True`) on Linux tries nemotron, then rapidocr/onnxruntime, then easyocr, then rapidocr/torch. This process logged `Auto OCR model selected rapidocr with torch.` Pin `RapidOcrOptions(backend="torch")`. Do not leave auto: another host extra selects a different engine. Docstring that says "EasyOCR if GPU else Tesseract" is stale.
+
+Prefetch: `download_models(artifacts, with_easyocr=False, with_picture_classifier=False)` took 149.9 s and wrote 1 405 021 041 bytes (`du` 1.4 G): layout heron, tableformer, code-formula, RapidOcr torch `ch` models, and RapidOcr onnx `ch` models (downloaded even though the selected backend was torch). Hugging Face warned about unauthenticated requests during prefetch. Runtime must set `artifacts_path` to that directory. `enable_remote_services=False` did not raise.
+
+`DocumentStream(name, BytesIO)` works. The name suffix selects format (`scan.pdf` → PDF, `scan.png` → IMAGE). Use `ImageFormatOption` for images and `PdfFormatOption` for PDFs, both with the same `PdfPipelineOptions`. Do not pass a path or URL into the helper.
+
+| Case | Result |
+| --- | --- |
+| Liberation Sans scan PDF, 8215 B, "SCAN 132" | `success`, `num_pages()==1`, markdown `SCAN 132`, 4.85 s (weights loaded in this process) |
+| Same page as PNG, 7203 B | `success`, 1 page, markdown `## SCAN 132`, 2.17 s. PDF and PNG markdown are not identical |
+| text PDF 872 B | `success`, 2 pages, correct text, 1.38 s. Not the plan route — anydoc handles text PDFs |
+| `max_num_pages=1` on 3-page PDF, `raises_on_error=True` | `ConversionError`: status `failure`, `Document has 3 pages, exceeding the max_num_pages limit of 1.` 0.05 s. No text |
+| same, `raises_on_error=False` | status `failure`, empty markdown, `FailureCategory.POLICY` |
+| `max_file_size=100` | status `failure`, empty markdown, size message. Defaults are `sys.maxsize` — the helper must set both limits |
+| `document_timeout=0.001` | status `partial_success`, errors `document timeout exceeded` and a pipeline stage timeout, markdown empty this time. `convert()` does not raise on `PARTIAL_SUCCESS` even when `raises_on_error=True` (`document_converter.py` treats it like success). Source also sets `PARTIAL_SUCCESS` when some pages complete (`standard_pdf_pipeline.py`). Refuse every non-`success` |
+| offline rerun | `HF_HUB_OFFLINE=1`, `TRANSFORMERS_OFFLINE=1`, `socket.create_connection` raising. `success`, `networkAttempts: []`. `unshare --net` failed with `Operation not permitted`, so this is a process socket guard, not a network namespace |
+
+RSS, one converter, artifacts already on disk: init VmHWM 1 093 704 KiB; after first scan 1 786 460 KiB; after PNG 1 997 992 KiB. A second converter in the same process reached 3 101 088 KiB. Budget one OCR job, not a pool.
+
+A tofu-font ImageMagick page (glyphs missing) still returned `success` with markdown `<!-- image -->\n\n00000000`. `SUCCESS` is not correct text. Keep output untrusted. Do not golden-match OCR except a font-rendered fixture.
+
+## Thresholds for later tasks
+
+This host, small fixtures. Not upstream benchmark claims (anydoc median 4.4 ms, Docling marketing scores).
+
+- anydoc office or text PDF under 10 KiB: under 500 ms, process VmHWM under 128 MiB. Measured 0.6–2.1 ms and 57–62 MiB including Bun.
+- anydoc `needsOcr` reject: under 500 ms, zero markdown bytes. Measured ~2 ms.
+- Docling OCR under 100 KiB after artifacts are on disk: under 30 s, one-converter VmHWM under 4 GiB. Measured ~5 s cold / ~2 s warm and ~2.0 GiB. A later real fixture that exceeds 2× without a recorded reason fails the task.
+- Prefetch (150 s, 1.4 GiB) is provisioning, not a request-path budget.
+
+## Threat notes
+
+- anydoc default path is local. One options flag uploads the whole PDF. The work API must not expose `ocr: 'hosted'` or read `FIRECRAWL_API_KEY`.
+- Docling model bytes come from Hugging Face at prefetch. Pin versions. Runtime uses `artifacts_path` and `enable_remote_services=False`. No `remote-serving` extra.
+- Over-limit Docling input fails with empty markdown (probed). Partial timeout does not raise. Check `status == success` or a timed-out job can be indexed.
+- Mixed PDF: anydoc emits no markdown. Wiki's current PDF built-in can index the text pages and skip the scan. Hook-first when a host extractor is set; null/failure must not fall back.
+- Caps before native anydoc (it accepts no abort and no `maxPages`). Caps inside the Docling `convert()` call (`max_num_pages`, `max_file_size`) plus a worker wall clock (`document_timeout`), because defaults are unbounded.
+- Worker env is not scrubbed by `assertWorkSandboxEnv` beyond two prefixes. Host runner passes an explicit env, no ambient tokens.
+- Helper reads stdin bytes only. No path, no URL, no `HttpSource`.

package/docs/history/README.md

@@ -8,6 +8,8 @@ page instead and note the archive where provenance matters.
 - `release-handoffs.md`: operator publish handoffs per release line (the live [release and install](../release-and-install.md) page keeps current install, inventory, gates, and peer policy).
 - `migrate-to-0.4.md`: retired 0.3-era package reorganization guide (current line: [migrate-to-0.5.md](../migrate-to-0.5.md)).
 - `0.1.0-readiness.md`: frozen 0.1.x readiness record.
+- `retire-node-runtime.md`: the 0.1.x–0.11.x Node 22/24 support story, its two measured CI legs, and the 0.0.16 Node compatibility matrix — retired in 0.12.0 with the `engines.bun` flip.
+- `migrate-to-0.12.0.md`: 0.11 → 0.12 host checklist (Bun runtime, `bun:sqlite` mapping, optional anydoc/Docling).
 - `persistence-credentials-multimodality-primitives.md`, `workflow-orchestration-primitives.md`, `workflow-tui-primitives.md`: plan-era primitive-review inventories.
 - `079-messaging-primitive-review.md`, `080-messaging-followon-primitive-review.md`: messaging-channel primitive reviews (079 shipped runtime; 080 follow-ons + 0.8.0 cut).
 - `081-connected-apps-primitive-review.md`: connected-apps / work-HTTP primitive review (081; page written in 081 Task 1).

package/docs/history/migrate-to-0.12.0.md

@@ -0,0 +1,57 @@
+# Migrate Prism 0.11 to 0.12
+
+> Archived host checklist for the 0.12.0 cut. Current install rules stay in [release and install](../release-and-install.md). Current extraction contract stays in [document extraction](../document-extraction.md).
+
+0.12.0 moves all twelve publishable manifests together. The runtime is Bun `>=1.4.2`. Optional document extraction is not part of a default install.
+
+## Runtime
+
+Install with `bun add`, not `npm install`. Example: `bun add @arnilo/prism @arnilo/prism-core`.
+
+Every publishable manifest declares `engines.bun >=1.4.2` and no longer declares `engines.node`. Bun 1.4.2 does not enforce `engines.bun`. A Node process still installs the tarball, then fails when it reaches SQLite:
+
+- `@arnilo/prism-core/sessions/sqlite requires the Bun runtime (bun:sqlite).`
+- `@arnilo/prism-core/governance/prompts requires the Bun runtime (bun:sqlite).`
+
+A static `import "bun:sqlite"` on Node fails earlier with `ERR_UNSUPPORTED_ESM_URL_SCHEME`. The published 0.11.x line remains the Node host path. Do not mix a 0.12.0 package into a Node process.
+
+`prism init` and provider-add scaffolds write `packageManager` `bun@1.4.2` and Bun install commands. The dev hint is `bun add --dev @arnilo/prism-coding-tools`.
+
+Release-host exception: `npm pack`, `npm publish`, and `npm sbom` stay on the release host. `bun pack` does not exist, and `bun publish` on 1.4.2 has no `--provenance`. Contributors do not run those commands.
+
+## SQLite
+
+The `better-sqlite3` optional peer is gone. There is no SQLite package to install. The driver is the runtime's `bun:sqlite`. Existing database files stay; FTS DDL is unchanged.
+
+Measured on Bun 1.4.2, against the old driver:
+
+| Row | `better-sqlite3` | `bun:sqlite` |
+| --- | --- | --- |
+| Blob read | `Buffer` | `Uint8Array`, not a `Buffer` |
+| `lastInsertRowid` | number | number. `safeIntegers: true` makes it `bigint` |
+| Integer above `2^53-1` | driver-defined | rounds (`9007199254740993n` stores as `9007199254740992`) unless `safeIntegers` |
+| `undefined` bind | throws | stores NULL |
+| `get()` miss | `undefined` | `null` |
+| Constructor options | accepted | no options object. Set `PRAGMA` with `exec`, including `busy_timeout` |
+
+Hosts that passed a constructor options object, or that treated a missing row as `undefined`, must update those call sites. Hosts that only used the Prism session store do not.
+
+## Optional document extraction
+
+Default hosts skip this. Nothing in the default import path installs Python, downloads a model, or calls OCR.
+
+Hosts that want local Markdown conversion:
+
+```bash
+bun add @arnilo/prism-work @firecrawl/anydoc@0.2.4
+```
+
+`@firecrawl/anydoc` is an optional native peer. Conversion stays on the host. The subpath never passes hosted OCR options and never reads an API key. A missing peer fails closed. Unrelated work and memory imports do not need the peer.
+
+Scanned PDFs and explicit image OCR need a host-provisioned Docling worker. Python and Docling are not npm dependencies. Pin `docling==2.130.0` and the CPU torch index. Prefetch models once (`docling-tools models download`, about 1.4 GiB and 150 s) and point the worker at that directory. The package ships `docling/ocr.py`. The host spawns it with a scrubbed env (`HF_HUB_OFFLINE=1`, telemetry off), one OCR job in flight, and no network egress. `WorkSandbox.execFile` cannot feed stdin, so it is not the runner.
+
+OCR never uploads by default. A failed, partial, or over-page conversion returns no Markdown and must not be indexed. One scanned page was about 5 s cold and 2 s warm after prefetch, with about 2 GiB resident. Budget under 30 s and 4 GiB for inputs under 100 KiB. The default no-OCR path does not pay that cost.
+
+## Rollback
+
+Stay on 0.11.1 if the process must be Node, or if a host still depends on the `better-sqlite3` peer. 0.12.0 packages do not load under Node.

package/docs/history/retire-node-runtime.md

@@ -0,0 +1,59 @@
+# Retiring the Node runtime (0.12.0)
+
+> Archived record. Node runtime support retired in **0.12.0**; the live runtime contract is
+> [release and install](../release-and-install.md). Kept verbatim for audit — do not read it as
+> current guidance.
+
+## What the 0.1.x–0.11.x line declared
+
+Through 0.11.1 Prism described itself as a TypeScript/Node.js agent harness and declared
+`engines.node >=22` in every publishable manifest. The support matrix was frozen by Phase 12 Task 0
+in `scripts/phase12-freeze-manifest.json`:
+
+| Runtime | Supported | Measured in CI |
+| --- | --- | --- |
+| Node | 22, 24 (`engines.node >=22`, the 0.x floor) | two declared legs: `verify` imports every public root `exports` default target on Node 24, and `node22-compat` runs the same public export imports on Node 22, for the declared `engines.node >=22` this table recorded. |
+
+The floor moved once: Node 20 was dropped in 0.6.0 (`dev-006`; Node 20 reached upstream end-of-life
+2026-04-30) and the `node20-compat` CI leg became `node22-compat`. `@types/node` stayed on the
+published floor (`^22.20.0`) so that an API the published line could not provide failed the build
+instead of compiling clean against a newer type surface. The docs-example path needed Node >=22.6
+native TypeScript stripping, which is why the import smoke (not the full demo run) was the Node 22
+leg.
+
+**Recorded compatibility matrix (2026-07-26, release 0.0.16):**
+
+| Leg | Node | Result |
+| --- | --- | --- |
+| Full SDK readiness (`bun run sdk:ready`: typecheck, lint, format, test, coverage, pack, release:gate) | 24.18.0 (current) | ✅ green — 1312/1312 tests, lint 0 errors, format clean, coverage 64/72/79 vs 60/70/75 thresholds. |
+| Build toolchain (`tsc` 7.0.2, `biome` 2.5.13) | 20.20.2 (LTS iron) | ✅ both run under Node 20. |
+| Public surface import smoke (all 21 root `exports` default targets) | 20.20.2 | ✅ all import cleanly. |
+| Full core test suite | 20.20.2 | 1311/1312 — the single failure is `examples_demos_run_to_completion_and_emit_no_secret`, which executes `examples/*.ts` via Node's native TypeScript stripping (Node 22.6+). This is a test-harness capability, not an SDK runtime incompatibility, and is exactly why CI scoped Node 20 to build + import smoke. |
+
+## What changed
+
+Plans 124–129 moved the contributor toolchain, the test runner, the CI runtime, and finally the
+consumer contract to Bun:
+
+- **Plan 124** moved every test stage, script wrapper, and CI step to the Bun binary; the only
+  surviving Node process is the branch-coverage audit (`scripts/branch-coverage-audit.mjs`), because
+  Bun 1.4.2 emits no branch data.
+- **Plan 125 Task 1** replaced `engines.node` with `engines.bun >=1.4.2` in all twelve publishable
+  manifests and retired the two declared Node legs together with it. Both legs were *measured*
+  (each ran `scripts/public-import-smoke.mjs`, since deleted) rather than dead, so the retirement
+  removed a real check and replaced it with the packed-consumer import sweep that imports every
+  public subpath of every package on Bun (`scripts/packaging-current.test.mjs`).
+- **Plan 125 Task 4** rewrote the live install and runtime documentation around `bun add`, moved the
+  Node story here, and recorded the retirement in `CHANGELOG.md`.
+
+`engines.bun` is advisory metadata: neither npm nor Bun 1.4.2 enforces it (a manifest declaring
+`engines.bun >=99.0.0` installs silently under both), so the retirement's compensating control is the
+import-side failure message that plan 126 Task 2 adds when the durable storage layer moves to
+`bun:sqlite`. A Node host running a 0.12.0 package fails closed at import with an actionable
+message instead of at install time. No 0.12.0 tarball reaches the registry before plan 129's cut, so
+no Node host sees the gap without the message.
+
+The registry keeps the 0.11.x line for Node hosts; hosts that install with npm can still install
+Prism (the published 0.11.x tarballs declare `engines.node >=22`), but the runtime contract for the
+0.12.0 line is Bun. The release host keeps npm for `pack`/`publish`/`sbom` — runner images ship
+Node, `bun pack` does not exist, and `bun publish` has no `--provenance` on 1.4.2 (plan 125 Task 5).

package/docs/hooks.md

@@ -175,7 +175,7 @@ event onto the seams above — no Prism internals, `@arnilo/prism` as its only p
 runtime dependency. It compiles the five events marked *compiled* in the map.
 
 ```bash
-npm install @arnilo/prism @arnilo/prism-hooks
+bun add @arnilo/prism @arnilo/prism-hooks
 ```
 
 ```ts

package/docs/host-compositions.md

@@ -102,10 +102,10 @@ Always install containing packages directly. **NPM install never accepts subpath
 
 ```bash
 # Correct — install containing published packages:
-npm install @arnilo/prism @arnilo/prism-core @arnilo/prism-providers @arnilo/prism-work
+bun add @arnilo/prism @arnilo/prism-core @arnilo/prism-providers @arnilo/prism-work
 
 # Never install subpaths:
-# npm install @arnilo/prism-work/connectors (WRONG: fails with 404 / E404)
+# bun add @arnilo/prism-work/connectors (WRONG: fails with 404 / E404)
 ```
 
 In your application code, import from documented subpaths:

package/docs/host-security.md

@@ -171,7 +171,7 @@ Wire those values where they matter: provider adapters receive the resolved cred
 - `npm audit --audit-level=high`: 0 vulnerabilities at every severity.
 - Lockfile: 162 registry dependency records, all with `resolved` provenance URL and integrity hash; `npm ls --all` reports a clean graph.
 - License inventory: 160 locked third-party packages; all declare permissive MIT, ISC, BSD, Apache-2.0, or compatible dual licenses. No GPL, AGPL, SSPL, or missing lockfile license metadata.
-- Install scripts: only `better-sqlite3@12.11.1` runs an install script (`prebuild-install || node-gyp rebuild --release`), required by the explicitly installed SQLite adapter. Core and other optional packages add no install hook.
+- Install scripts: no package in the family runs an install script.
 - Secret scan: source, tests, docs, workflow files, package metadata, built tests, packed-install canary, and tarball deny-list checks found no private-key block or common live-token prefix. Runtime redaction fixtures cover requests, events, ledgers, stores, checkpoints, provider/OAuth errors, and credential ciphertext.
 - Threat suites pass for parameterized SQL/tenant isolation, HTTP URL/SSRF rejection, realpath/symlink containment, shell-metacharacter approval, schema prototype-pollution/remote-reference bounds, OAuth polling/abort/redaction, credential tamper/wrong-key/KDF floors, MCP result bounds/timeouts, and coding approval/path policy. `security:threat-suites` also gates CodeQL-remediation regressions (plan 038): linear `trimTrailingSlashes`/parsers with no environment regex evaluation, single-pass HTML sanitization, crypto (not `Math.random`) fixture identifiers, and no clear-text error logging on password-handling paths.