fix: add ./ prefix to subpath export keys in package.json

chore: add LICENSE, README, update package.json and AGENTS.md for npm release prep
chore: mark final review/complete-library task completed — all 38/38 tasks done
2026-05-22 06:26:56 +00:00 · 2026-05-22 06:17:54 +00:00 · 2026-05-21 22:56:22 +00:00 · 2026-05-21 22:55:56 +00:00 · 2026-05-21 22:55:37 +00:00 · 2026-05-21 22:40:57 +00:00
31 changed files with 2239 additions and 153 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,60 +1,86 @@
-## Memory Tools (via @alkdev/open-memory plugin)
+# @alkdev/flowgraph — Agent Guide

-You have access to two tools for managing your context and accessing session history:
+Project-specific context for AI agents working on this codebase.

-### memory({tool: "...", args: {...}})
+## What This Is

-Read-only tool for introspecting your session history and context state. Available operations:
- `memory({tool: "help"})` — full reference with examples
- `memory({tool: "summary"})` — quick counts of projects, sessions, messages, todos
- `memory({tool: "sessions"})` — list recent sessions (useful for finding past work)
- `memory({tool: "children", args: {sessionId: "ses_..."}})` — list sub-agent sessions spawned from a parent
- `memory({tool: "messages", args: {sessionId: "..."}})` — read a session's conversation
- `memory({tool: "messages", args: {sessionId: "...", role: "assistant"}})` — read only assistant messages
- `memory({tool: "messages", args: {sessionId: "...", showTools: true}})` — include tool-call output
- `memory({tool: "message", args: {messageId: "msg_..."}})` — read a single message by ID
- `memory({tool: "search", args: {query: "..."}})` — search across all conversations
- `memory({tool: "compactions", args: {sessionId: "..."}})` — view compaction checkpoints
- `memory({tool: "context"})` — check your current context window usage
+DAG-based workflow orchestration library. Wraps graphology `DirectedGraph`, enforces DAG invariants, provides ujsx template composition and reactive signal-driven execution. Sits between `@alkdev/operations` (what can be called) and `@alkdev/alkhub` (what was called) — defines *how calls are orchestrated*.

-### memory_compact()
+## Build & Test Commands

-Trigger compaction on the current session. This summarizes the conversation so far to free context space.
+```bash
+npm run build          # tsup (ESM + CJS + dts + sourcemaps)
+npm run build:tsc      # tsc type-check only
+npm run lint           # tsc --noEmit
+npm run test           # vitest run
+npm run test:watch     # vitest watch
+npm run test:coverage  # vitest run --coverage
+```

-**When to use memory_compact:**
- When context is above 80% (check with `memory({tool: "context"})`)
- When you notice you're losing track of earlier conversation details
- At natural breakpoints in multi-step tasks (after completing a subtask, before starting a new one)
- When the system prompt shows a yellow/red/critical context warning
- Proactively, rather than waiting for automatic compaction at 92%
+Always run `npm run lint && npm run test` after making changes.

-**When NOT to use memory_compact:**
- When context is below 50% (it wastes a compaction cycle)
- In the middle of a complex edit that you need immediate context for
- When the task is nearly complete (just finish the task instead)
+## Source Structure

-Compaction preserves your most important context in a structured summary — you will continue the session with the summary as your starting point.
+```
+src/
+  index.ts              # Barrel — re-exports all sub-modules
+  component/            # ujsx workflow components (Operation, Sequential, Parallel, Conditional, Map)
+  host/                 # HostConfig implementations (GraphologyHostConfig, ReactiveHostConfig)
+  schema/               # TypeBox schemas, enums, node/edge attribute types
+  graph/                # FlowGraph class (construction, mutation, query, serialization)
+  reactive/             # WorkflowReactiveRoot, signal-driven status, event log projection
+  analysis/             # Pure functions: typeCompat, validate, topologicalOrder, parallelGroups, criticalPath
+  error/                # FlowgraphError hierarchy
+```

-## Worktree Tool (via @alkimiadev/open-coordinator plugin)
+## Subpath Exports

-You have access to the `worktree` tool for git worktree management and session coordination. Call with `{action, args}`:
+The package has 8 export subpaths. Root `@alkdev/flowgraph` re-exports everything. Subpath imports make dependencies explicit:

-### Coordinator Operations (available when session is not spawned by another session)
+| Subpath | Key Exports |
+|---------|-------------|
+| `/graph` | `FlowGraph`, `FlowGraphOptions`, `OperationSpec`, `CallEventMapValue` |
+| `/schema` | `CallStatus`, `NodeStatus`, `EdgeType`, `OperationType`, all node/edge attribute types |
+| `/component` | `Operation`, `Sequential`, `Parallel`, `Conditional`, `Map` |
+| `/host` | `GraphologyHostConfig`, `ReactiveHostConfig` |
+| `/analysis` | `typeCompat`, `buildTypeEdges`, `validateGraph`, `validateSchema`, `validate`, `validateTemplate`, `topologicalOrder`, `parallelGroups`, `criticalPath` |
+| `/reactive` | `WorkflowReactiveRoot`, `EventLogProjection`, `WorkflowNode`, `FailurePolicy` |
+| `/error` | `FlowgraphError`, `ConstructionError`, `CycleError`, `InvalidInputError`, `InvalidTransitionError` |

- `worktree({action: "list"})` — List git worktrees
- `worktree({action: "dashboard"})` — Worktree dashboard with session info
- `worktree({action: "spawn", args: {tasks: [...], prompt: "..."}})` — Spawn parallel worktrees + sessions
- `worktree({action: "sessions"})` — Query spawned session status
- `worktree({action: "message", args: {sessionID: "...", message: "..."}})` — Message a session
- `worktree({action: "abort", args: {sessionID: "..."}})` — Abort a session
- `worktree({action: "cleanup", args: {action: "remove", pathOrBranch: "..."}})` — Remove worktree
- `worktree({action: "help"})` — Show all available operations
+## Key Patterns

-### Implementation Operations (available when session is spawned by a coordinator)
+- **TypeBox schema + Static type pairs**: Every schema is exported as both a const (runtime) and an inferred type. `const FooSchema = Type.Object({...}); type Foo = Static<typeof FooSchema>;`
+- **Delegation model**: `FlowGraph` wraps a graphology `DirectedGraph` (does not extend it). `flowGraph.graph` is an escape hatch that bypasses validation.
+- **DAG enforcement**: `addEdge()` throws `CycleError` if the edge would create a cycle. `fromJSON()` validates DAG invariants on deserialization.
+- **Event log as source of truth**: Call protocol events (`call.requested`, `call.responded`, `call.error`, `call.aborted`, `call.completed`) are appended to `WorkflowReactiveRoot`. Status/results are derived projections.
+- **Signal-driven execution**: `@preact/signals-core` powers `WorkflowReactiveRoot`. `preconditions`, `canStart`, `blockedByFailure` are `ReadonlySignal<boolean>` computed from predecessor status.
+- **`dispose()` is mandatory**: `WorkflowReactiveRoot.dispose()` must be called to release signal subscriptions.

- `worktree({action: "current"})` — Show your worktree mapping
- `worktree({action: "notify", args: {message: "...", level: "info|blocking"}})` — Report to coordinator
- `worktree({action: "status"})` — Show worktree git status
+## Architecture Docs

-The plugin auto-injects `workdir` for bash commands when the session is mapped to a worktree.
+`docs/architecture/` contains detailed specs (all `status: reviewed`):

+- `README.md` — overview, relationship to sibling packages, design decisions
+- `flowgraph-api.md` — FlowGraph class full API
+- `consumer-integration.md` — end-to-end integration walkthrough (5 phases)
+- `schema.md` — TypeBox Module, all node/edge attribute schemas
+- `operation-graph.md` — static graph from OperationSpecs
+- `call-graph.md` — dynamic graph from call events
+- `workflow-templates.md` — ujsx components, composition rules, template→DAG hydration
+- `host-configs.md` — GraphologyHostConfig, ReactiveHostConfig
+- `reactive-execution.md` — signal-driven status propagation, lifecycle, error boundaries
+- `analysis.md` — type-compatibility checking, precondition validation, execution ordering
+- `error-handling.md` — FlowgraphError hierarchy
+- `build-distribution.md` — package structure, exports map
+- `decisions/` — ADRs 001–006
+
+Consult these for anything non-trivial. The README is surface-level; architecture docs are the specification.
+
+## Constraints for Agent Modifications
+
+- **Never add cycles** — this is a DAG-only library. Any edge that would create a cycle must throw `CycleError`.
+- **Never mutate operation graphs after construction** — `fromSpecs()` graphs are conventionally immutable.
+- **Keep schema as pure data** — `src/schema/` contains TypeBox schemas and types only, no runtime logic.
+- **Keep analysis as pure functions** — `src/analysis/` functions take a `FlowGraph` or `DirectedGraph` as input and return results without side effects.
+- **Maintain the delegation model** — `FlowGraph` delegates to graphology. Don't expose raw graphology methods that could violate DAG invariants without explicit validation.
+- **tsup builds all subpath entries** — `tsup.config.ts` lists every subpath. If you add a new top-level module, add the entry there and update `package.json` exports.
--- a/6
+++ b/6
@@ -0,0 +1,6 @@
+This project is dual-licensed under either of the following:
+
+- MIT License (LICENSE-MIT)
+- Apache License 2.0 (LICENSE-APACHE)
+
+You may choose either license at your option.
--- a/190
+++ b/190
@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable by
+      such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding any notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed as
+          modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limitation damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 alkdev
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
--- a/21
+++ b/21
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 alkdev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
--- a/README.md
+++ b/README.md
@@ -0,0 +1,320 @@
+# @alkdev/flowgraph
+
+DAG-based workflow orchestration over graphology, with ujsx template composition and reactive signal-driven execution.
+
+## What This Does
+
+Flowgraph sits between `@alkdev/operations` (which defines *what can be called*) and `@alkdev/alkhub` (which records *what was called*). Flowgraph defines **how calls are orchestrated** — the structure, validation, and execution of workflows.
+
+Three conceptual graphs, each for a different purpose:
+
+1. **Operation Graph** — static graph built from `OperationSpec`s at startup. Nodes are operations, edges are type-compatibility relationships. Enables cycle detection, topological ordering, and validation.
+2. **Call Graph** — dynamic graph built from call protocol events at runtime. Nodes are call invocations with status/timestamps, edges are parent-child relationships. Enables abort cascading and observability.
+3. **Workflow Template** — declarative ujsx tree defining a reusable workflow structure. A validated path through the operation graph, instantiated as a call graph at runtime.
+
+**The graph is the specification. The template is the authoring surface. The call graph is the execution record.**
+
+## Installation
+
+```bash
+npm install @alkdev/flowgraph
+```
+
+Peer dependency: `@alkdev/operations ^0.1.0`
+
+## Quick Start
+
+### Build an Operation Graph
+
+```typescript
+import { FlowGraph } from "@alkdev/flowgraph/graph";
+import type { OperationSpec } from "@alkdev/flowgraph/graph";
+
+const specs: OperationSpec[] = [
+  { namespace: "task", name: "classify", type: "query", version: "1.0.0", inputSchema: {...}, outputSchema: {...} },
+  { namespace: "task", name: "enrich", type: "query", version: "1.0.0", inputSchema: {...}, outputSchema: {...} },
+  { namespace: "task", name: "summarize", type: "mutation", version: "1.0.0", inputSchema: {...}, outputSchema: {...} },
+];
+
+const graph = FlowGraph.fromSpecs(specs);
+// Type-compatibility edges added automatically
+graph.hasEdge("task.classify", "task.enrich");
+```
+
+### Define a Workflow Template
+
+```typescript
+import { h } from "@alkdev/ujsx";
+import { Operation, Sequential, Parallel, Conditional } from "@alkdev/flowgraph/component";
+
+const template = h(Sequential, {},
+  h(Operation, { name: "task.classify" }),
+  h(Conditional, {
+    test: (results) => results["task.classify"].output.confidence > 0.8,
+  },
+    h(Parallel, {},
+      h(Operation, { name: "task.enrich" }),
+      h(Operation, { name: "task.summarize" }),
+    ),
+    h(Operation, { name: "task.classify" }),
+  ),
+);
+```
+
+### Validate the Template
+
+```typescript
+import { validateTemplate } from "@alkdev/flowgraph/analysis";
+
+const errors = validateTemplate(template, graph);
+if (errors.length > 0) {
+  for (const error of errors) {
+    console.error(`[${error.type}]`, error);
+  }
+}
+```
+
+### Populate a Call Graph from Events
+
+```typescript
+import { FlowGraph } from "@alkdev/flowgraph/graph";
+
+const callGraph = FlowGraph.fromCallEvents(eventArray);
+callGraph.filterByStatus("running");
+callGraph.children("req_abc123");
+callGraph.lineage("req_xyz789");
+callGraph.duration("req_abc123");
+```
+
+### Drive Reactive Execution
+
+```typescript
+import { WorkflowReactiveRoot } from "@alkdev/flowgraph/reactive";
+
+const workflow = new WorkflowReactiveRoot(dag, {
+  failurePolicy: "abort-dependents",
+});
+
+// Append call protocol events — status derives reactively
+workflow.append({ type: "call.requested", requestId: "req_1", operationId: "task.classify", input: {}, timestamp: "..." });
+workflow.append({ type: "call.responded", requestId: "req_1", output: { confidence: 0.95 }, timestamp: "..." });
+
+// Read reactive state
+workflow.getStatus("task.enrich");
+workflow.getResult("task.classify");
+
+// Abort cascading
+workflow.abortAll();
+workflow.dispose();
+```
+
+## Subpath Exports
+
+| Subpath | Purpose | Key Exports |
+|---------|---------|-------------|
+| `@alkdev/flowgraph` | Root — re-exports everything | All public types and functions |
+| `@alkdev/flowgraph/graph` | Core DAG class | `FlowGraph`, `FlowGraphOptions`, `OperationSpec`, `CallEventMapValue` |
+| `@alkdev/flowgraph/schema` | TypeBox schemas and types | `CallStatus`, `NodeStatus`, `EdgeType`, `OperationType`, `CallNodeAttrs`, `OperationNodeAttrs`, `OperationEdgeAttrs`, `CallEdgeAttrs`, `TemplateEdgeAttrs`, `CallResult`, `FlowGraphSerialized` |
+| `@alkdev/flowgraph/component` | ujsx workflow components | `Operation`, `Sequential`, `Parallel`, `Conditional`, `Map` |
+| `@alkdev/flowgraph/host` | Rendering backends | `GraphologyHostConfig`, `ReactiveHostConfig` |
+| `@alkdev/flowgraph/analysis` | Validation and analysis functions | `typeCompat`, `buildTypeEdges`, `validateGraph`, `validateSchema`, `validate`, `validateTemplate`, `validatePreconditions`, `topologicalOrder`, `parallelGroups`, `criticalPath`, `reachableFrom` |
+| `@alkdev/flowgraph/reactive` | Reactive execution engine | `WorkflowReactiveRoot`, `EventLogProjection`, `WorkflowNode`, `ReactiveContext`, `FailurePolicy`, `AggregateStatus` |
+| `@alkdev/flowgraph/error` | Error hierarchy | `FlowgraphError`, `ConstructionError`, `DuplicateNodeError`, `DuplicateEdgeError`, `NodeNotFoundError`, `CycleError`, `InvalidInputError`, `InvalidTransitionError` |
+
+## Core API: FlowGraph Class
+
+`FlowGraph<NodeAttrs, EdgeAttrs>` wraps a graphology `DirectedGraph` and enforces DAG invariants. It delegates graph operations to graphology while adding flowgraph-specific construction, mutation, and query methods.
+
+### Factory Methods
+
+```typescript
+FlowGraph.fromSpecs(specs: OperationSpec[]): OperationGraph
+FlowGraph.fromCallEvents(events: CallEventMapValue[]): CallGraph
+FlowGraph.fromJSON(data: FlowGraphSerialized): FlowGraph
+```
+
+### Node Operations
+
+```typescript
+graph.addNode(key, attrs)            // throws DuplicateNodeError
+graph.removeNode(key)                // throws NodeNotFoundError
+graph.updateNode(key, partialAttrs)  // throws NodeNotFoundError
+graph.hasNode(key): boolean
+graph.getNodeAttributes(key): NodeAttrs
+graph.forEachNode(callback): void
+```
+
+### Edge Operations
+
+```typescript
+graph.addEdge(source, target, attrs?) // throws NodeNotFoundError, DuplicateEdgeError, CycleError
+graph.removeEdge(source, target)      // no-op if not found
+graph.hasEdge(source, target): boolean
+graph.getEdgeAttributes(source, target): EdgeAttrs
+graph.forEachEdge(callback): void
+```
+
+### Traversal
+
+```typescript
+graph.topologicalOrder(): string[]
+graph.ancestors(nodeId): string[]
+graph.descendants(nodeId): string[]
+graph.predecessors(nodeId): string[]
+graph.successors(nodeId): string[]
+graph.reachableFrom(nodeIds): Set<string>
+graph.hasCycles(): boolean
+graph.findCycles(): string[][]
+```
+
+### Call Graph Convenience
+
+```typescript
+graph.addCall(attrs: CallNodeAttrs): void
+graph.addDependency(source, target): void
+graph.updateStatus(requestId, status, extra?): void  // throws InvalidTransitionError
+graph.updateCall(requestId, partialAttrs): void
+graph.removeCall(requestId): void
+graph.updateFromEvent(event: CallEventMapValue): void
+graph.filterByStatus(status: CallStatus): string[]
+graph.getRoots(): string[]
+graph.children(requestId): string[]
+graph.duration(requestId): number
+graph.lineage(requestId): string[]
+```
+
+### Serialization
+
+```typescript
+graph.export(): FlowGraphSerialized
+graph.toJSON(): FlowGraphSerialized
+graph.toString(): string
+```
+
+### Escape Hatch
+
+```typescript
+graph.graph  // → DirectedGraph (raw graphology instance)
+```
+
+Direct mutation via `graph.graph` bypasses flowgraph validation. Use with caution.
+
+## Schema Enums
+
+| Enum | Values |
+|------|--------|
+| `CallStatus` | `pending`, `running`, `completed`, `failed`, `aborted` |
+| `NodeStatus` | `idle`, `waiting`, `ready`, `running`, `completed`, `failed`, `skipped`, `aborted` |
+| `EdgeType` | `triggered`, `depends_on`, `typed`, `sequential`, `conditional` |
+| `OperationType` | `query`, `mutation`, `subscription` |
+
+Call status transitions: `pending → running → completed|failed|aborted`. Terminal states are immutable. `InvalidTransitionError` is thrown on invalid transitions.
+
+## Workflow Components
+
+| Component | Props | Behavior |
+|-----------|-------|----------|
+| `<Operation>` | `name`, `input?`, `retries?`, `timeout?` | Declares an operation node in the workflow |
+| `<Sequential>` | `id?` | Children execute in order; edges are `sequential` |
+| `<Parallel>` | `id?`, `maxConcurrency?` | Children execute concurrently |
+| `<Conditional>` | `test`, `else?` | Branches on `test(results)`. Children = then-branch, `else` prop = else-branch |
+| `<Map>` | `over`, `as` | Iterates over `over` collection, binding each item as `as` variable |
+
+## Analysis Functions
+
+```typescript
+import { typeCompat, validateTemplate, topologicalOrder, parallelGroups, criticalPath } from "@alkdev/flowgraph/analysis";
+
+typeCompat(outputSchema, inputSchema): TypeCompatResult | undefined
+validateTemplate(template, operationGraph): AnyValidationError[]
+topologicalOrder(graph): string[]
+parallelGroups(graph): string[][]  // topological generations
+criticalPath(graph): string[]     // longest path
+validateGraph(graph): GraphValidationError[]
+validateSchema(graph, schema): ValidationError[]
+validate(graph, schema): AnyValidationError[]  // combined
+```
+
+## Reactive Execution
+
+`WorkflowReactiveRoot` implements `EventLogProjection` — call protocol events are the source of truth, status/results are derived projections.
+
+```typescript
+const workflow = new WorkflowReactiveRoot(dag, {
+  failurePolicy: "abort-dependents",  // or "continue-running"
+  parallelGroups: { group1: { siblings: ["a", "b"], maxConcurrency: 2 } },
+});
+
+// Per-node reactive signals
+workflow.statusMap      // Map<string, Signal<NodeStatus>>
+workflow.preconditions  // Map<string, ReadonlySignal<boolean>> — all predecessors completed/skipped
+workflow.canStart       // Map<string, ReadonlySignal<boolean>> — preconditions + concurrency
+workflow.blockedByFailure // Map<string, ReadonlySignal<boolean>> — any predecessor failed/aborted
+workflow.resultMap      // Map<string, ReadonlySignal<CallResult | undefined>>
+
+// Event-driven updates
+workflow.append(event: CallEventMapValue): void
+
+// Queries
+workflow.getStatus(nodeId): NodeStatus
+workflow.getResult(nodeId): CallResult | undefined
+workflow.isComplete(): boolean
+workflow.getAggregateStatus(): AggregateStatus
+
+// Lifecycle
+workflow.abortAll(): void
+workflow.abortNode(nodeId): void
+workflow.dispose(): void  // mandatory cleanup — releases signal subscriptions
+```
+
+## Error Hierarchy
+
+```
+FlowgraphError (base)
+├── ConstructionError
+│   ├── DuplicateNodeError    (readonly key)
+│   ├── DuplicateEdgeError    (readonly source, target)
+│   ├── NodeNotFoundError     (readonly key)
+│   ├── CycleError           (readonly cycles: string[][])
+│   └── InvalidInputError    (readonly errors: ValidationError[])
+└── InvalidTransitionError   (readonly requestId, from, to)
+```
+
+## Design Principles
+
+1. **DAG-only, no cycles** — `addEdge()` rejects cycle-creating edges at mutation time (ADR-002). This differs from taskgraph, which allows cycles and detects them after the fact.
+
+2. **Storage is decoupled** — flowgraph handles in-memory graph construction, validation, and analysis. Persistence is the caller's concern. `export()`/`fromJSON()` provides the serialization boundary.
+
+3. **Template → DAG → Execution is a pipeline** — each representation serves a different phase and can exist independently. Validate a template without executing it. Build a call graph from events without a template. Run reactive execution directly from a DAG.
+
+4. **Event log as source of truth** — call protocol events (`call.requested`, `call.responded`, `call.error`, `call.aborted`, `call.completed`) are the ground truth. Status, results, and the call graph are projections derived from the event log (ADR-005).
+
+5. **Delegation, not inheritance** — `FlowGraph` wraps a graphology `DirectedGraph`, exposing a curated API. The raw graphology instance is available via the `.graph` escape hatch.
+
+## For AI Agents
+
+When working with this library programmatically:
+
+- **Use subpath imports** — `@alkdev/flowgraph/graph`, `@alkdev/flowgraph/analysis`, etc. The root export re-exports everything but subpath imports make dependencies explicit.
+- **Always call `dispose()` on `WorkflowReactiveRoot`** — signal subscriptions leak without it.
+- **Function-valued props don't survive JSON serialization** — `Conditional.test` and `Map.over` with function values need runtime resolution. Use string references for stored templates.
+- **`fromSpecs()` graphs are conventionally immutable** — don't mutate operation graphs after construction. If the registry changes, rebuild via `fromSpecs()`.
+- **Call graph mutation uses event protocol** — use `updateFromEvent()` or `addCall()`/`updateStatus()`, not direct node mutation.
+- **`typeCompat()` returns `undefined` for `unknown`/`any` schemas** — this means "no meaningful check possible", not "incompatible".
+- **Architecture specs are in `docs/architecture/`** — detailed design decisions, ADRs, and open questions live there. This README is a surface-level guide. Consult the architecture docs for anything non-trivial.
+
+## Dependencies
+
+| Package | Relationship |
+|---------|-------------|
+| `graphology` | Direct — the underlying directed graph data structure |
+| `graphology-dag` | Direct — topological sort, cycle detection, DAG traversal |
+| `@alkdev/ujsx` | Direct — `UNode` trees and `HostConfig` for workflow template rendering |
+| `@alkdev/typebox` | Direct — all schemas are TypeBox Modules |
+| `@preact/signals-core` | Direct — reactive state management for `WorkflowReactiveRoot` |
+| `@alkdev/operations` | **Peer** — provides `OperationSpec`, `OperationRegistry`, call event types |
+
+## License
+
+Dual-licensed under [MIT](LICENSE-MIT) or [Apache-2.0](LICENSE-APACHE) at your option.
--- a/package.json
+++ b/package.json
@@ -17,7 +17,7 @@
        "default": "./dist/index.cjs"
      }
    },
-    "/component": {
+    "./component": {
      "import": {
        "types": "./dist/component/index.d.ts",
        "default": "./dist/component/index.js"
@@ -27,7 +27,7 @@
        "default": "./dist/component/index.cjs"
      }
    },
-    "/host": {
+    "./host": {
      "import": {
        "types": "./dist/host/index.d.ts",
        "default": "./dist/host/index.js"
@@ -37,7 +37,7 @@
        "default": "./dist/host/index.cjs"
      }
    },
-    "/schema": {
+    "./schema": {
      "import": {
        "types": "./dist/schema/index.d.ts",
        "default": "./dist/schema/index.js"
@@ -47,7 +47,7 @@
        "default": "./dist/schema/index.cjs"
      }
    },
-    "/graph": {
+    "./graph": {
      "import": {
        "types": "./dist/graph/index.d.ts",
        "default": "./dist/graph/index.js"
@@ -57,7 +57,7 @@
        "default": "./dist/graph/index.cjs"
      }
    },
-    "/reactive": {
+    "./reactive": {
      "import": {
        "types": "./dist/reactive/index.d.ts",
        "default": "./dist/reactive/index.js"
@@ -67,7 +67,7 @@
        "default": "./dist/reactive/index.cjs"
      }
    },
-    "/analysis": {
+    "./analysis": {
      "import": {
        "types": "./dist/analysis/index.d.ts",
        "default": "./dist/analysis/index.js"
@@ -77,7 +77,7 @@
        "default": "./dist/analysis/index.cjs"
      }
    },
-    "/error": {
+    "./error": {
      "import": {
        "types": "./dist/error/index.d.ts",
        "default": "./dist/error/index.js"
@@ -112,6 +112,15 @@
    "operations"
  ],
  "license": "MIT OR Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://git.alk.dev/alkdev/flowgraph.git"
+  },
+  "homepage": "https://git.alk.dev/alkdev/flowgraph",
+  "bugs": {
+    "url": "https://git.alk.dev/alkdev/flowgraph/issues"
+  },
+  "sideEffects": false,
  "dependencies": {
    "@alkdev/typebox": "^0.34.49",
    "@alkdev/ujsx": "^0.1.0",
--- a/src/error/index.ts
+++ b/src/error/index.ts
@@ -1,4 +1,10 @@
-type CallStatus = "pending" | "running" | "completed" | "failed" | "aborted";
+import type { CallStatus } from "../schema/enums.js";
+
+interface TypeMismatch {
+  path: string;
+  expected: string;
+  actual: string;
+}

 class FlowgraphError extends Error {
  constructor(message: string) {
@@ -88,12 +94,6 @@ interface GraphValidationError {
  details: unknown;
 }

-interface TypeMismatch {
-  path: string;
-  expected: string;
-  actual: string;
-}
-
 interface TypeIncompatError {
  type: "type-compat";
  sourceKey: string;
@@ -116,10 +116,8 @@ export {
 };

 export type {
-  CallStatus,
  ValidationError,
  GraphValidationError,
-  TypeMismatch,
  TypeIncompatError,
  AnyValidationError,
 };
--- a/src/graph/construction.ts
+++ b/src/graph/construction.ts
@@ -10,7 +10,8 @@ import {
  InvalidInputError,
  InvalidTransitionError,
 } from "../error/index.js";
-import type { CallStatus, AnyValidationError, ValidationError } from "../error/index.js";
+import type { AnyValidationError, ValidationError } from "../error/index.js";
+import type { CallStatus } from "../schema/enums.js";
 import {
  findCycles,
  reachableFrom as reachableFromFn,
--- a/src/graph/index.ts
+++ b/src/graph/index.ts
@@ -1,14 +1,5 @@
 export { FlowGraph, buildTypeEdges, type FlowGraphOptions, type OperationSpec, type CallEventMapValue, type CallRequestedEvent, type CallRespondedEvent, type CallErrorEvent, type CallAbortedEvent, type CallCompletedEvent } from "./construction.js";
 export {
-  topologicalOrder,
  hasCycles,
  findCycles,
-  ancestors,
-  descendants,
-  reachableFrom,
-} from "./queries.js";
-export {
-  validateSchema,
-  validateGraph,
-  validate,
-} from "./validation.js";
+} from "./queries.js";
--- a/src/host/index.ts
+++ b/src/host/index.ts
@@ -1,2 +1,4 @@
 export { GraphologyHostConfig } from "./graphology.js";
-export type { WorkflowTag, GraphNode, GraphContext, OperationRegistry } from "./graphology.js";
+export type { WorkflowTag, GraphNode, GraphContext, OperationRegistry as GraphOperationRegistry } from "./graphology.js";
+export { ReactiveHostConfig } from "./reactive.js";
+export type { WorkflowNode, ReactiveContext, OperationRegistry } from "./reactive.js";
--- a/src/host/reactive.ts
+++ b/src/host/reactive.ts
@@ -1 +1,250 @@
-export {};
+import { signal, computed } from "@preact/signals-core";
+import type { Signal, ReadonlySignal } from "@preact/signals-core";
+import type { HostConfig } from "@alkdev/ujsx";
+import type { NodeStatus } from "../schema/enums.js";
+import type { CallResult } from "../schema/edge.js";
+import type { EventLogProjection } from "../reactive/workflow.js";
+import type { WorkflowTag } from "./graphology.js";
+
+export interface OperationRegistry {
+  resolve(name: string): unknown;
+}
+
+export interface WorkflowNode {
+  key: string;
+  type: WorkflowTag;
+  status: Signal<NodeStatus>;
+  preconditions: ReadonlySignal<boolean>;
+  blockedByFailure: ReadonlySignal<boolean>;
+  operationId?: string;
+  output?: Signal<unknown>;
+  children: WorkflowNode[];
+}
+
+export interface ReactiveContext {
+  operationRegistry: OperationRegistry;
+  nodes: Map<string, WorkflowNode>;
+  statusSignals: Map<string, Signal<NodeStatus>>;
+  preconditions: Map<string, ReadonlySignal<boolean>>;
+  blockedByFailure: Map<string, ReadonlySignal<boolean>>;
+  resultProjection: EventLogProjection;
+  parentMap: Map<string, string>;
+  siblingMap: Map<string, string[]>;
+  results: Map<string, ReadonlySignal<CallResult | undefined>>;
+  _containerCounter: number;
+}
+
+function collectLeafPredecessors(
+  nodeKey: string,
+  ctx: ReactiveContext,
+): string[] {
+  const parentKey = ctx.parentMap.get(nodeKey);
+  if (!parentKey) return [];
+
+  const parentNode = ctx.nodes.get(parentKey);
+  if (!parentNode) return [];
+
+  const siblings = ctx.siblingMap.get(parentKey);
+  if (!siblings) return [];
+
+  const idx = siblings.indexOf(nodeKey);
+
+  switch (parentNode.type) {
+    case "sequential": {
+      if (idx > 0) {
+        const prevKey = siblings[idx - 1]!;
+        const prevNode = ctx.nodes.get(prevKey);
+        if (prevNode && prevNode.type === "operation") {
+          return [prevKey];
+        }
+        return collectLeafPredecessors(prevKey, ctx);
+      }
+      return collectLeafPredecessors(parentKey, ctx);
+    }
+    case "parallel":
+    case "map":
+    case "conditional": {
+      return collectLeafPredecessors(parentKey, ctx);
+    }
+    default:
+      return [];
+  }
+}
+
+function computePreconditions(
+  node: WorkflowNode,
+  ctx: ReactiveContext,
+): boolean {
+  const predecessors = collectLeafPredecessors(node.key, ctx);
+  if (predecessors.length === 0) return true;
+  return predecessors.every((predKey) => {
+    const predStatus = ctx.statusSignals.get(predKey);
+    if (!predStatus) return true;
+    return predStatus.value === "completed" || predStatus.value === "skipped";
+  });
+}
+
+function computeBlockedByFailure(
+  node: WorkflowNode,
+  ctx: ReactiveContext,
+): boolean {
+  const predecessors = collectLeafPredecessors(node.key, ctx);
+  return predecessors.some((predKey) => {
+    const predStatus = ctx.statusSignals.get(predKey);
+    if (!predStatus) return false;
+    return predStatus.value === "failed" || predStatus.value === "aborted";
+  });
+}
+
+export const ReactiveHostConfig: HostConfig<WorkflowTag, WorkflowNode, ReactiveContext> = {
+  name: "reactive",
+
+  createRootContext(_container, options) {
+    const ctx: ReactiveContext = {
+      operationRegistry: options?.registry as OperationRegistry ?? { resolve: () => undefined },
+      nodes: new Map(),
+      statusSignals: new Map(),
+      preconditions: new Map(),
+      blockedByFailure: new Map(),
+      resultProjection: options?.resultProjection as EventLogProjection ?? {
+        append() {},
+        getStatus: () => "idle" as NodeStatus,
+        getResult: () => undefined,
+        getEvents: () => [],
+      },
+      parentMap: new Map(),
+      siblingMap: new Map(),
+      results: new Map(),
+      _containerCounter: 0,
+    };
+    return ctx;
+  },
+
+  createInstance(tag, props, ctx, parent) {
+    if (tag === "operation") {
+      const key = props.name as string;
+      const status = signal<NodeStatus>("idle");
+
+      const node: WorkflowNode = {
+        key,
+        type: "operation",
+        status,
+        preconditions: computed(() => computePreconditions(node, ctx)),
+        blockedByFailure: computed(() => computeBlockedByFailure(node, ctx)),
+        operationId: key,
+        output: signal<unknown>(undefined),
+        children: [],
+      };
+
+      ctx.nodes.set(key, node);
+      ctx.statusSignals.set(key, status);
+      ctx.preconditions.set(key, node.preconditions);
+      ctx.blockedByFailure.set(key, node.blockedByFailure);
+
+      if (parent) {
+        ctx.parentMap.set(key, parent.key);
+        const siblings = ctx.siblingMap.get(parent.key);
+        if (siblings) {
+          siblings.push(key);
+        } else {
+          ctx.siblingMap.set(parent.key, [key]);
+        }
+      }
+
+      return node;
+    }
+
+    const counter = ctx._containerCounter++;
+    const key = `__${tag}_${counter}`;
+    const status = signal<NodeStatus>("idle");
+
+    const node: WorkflowNode = {
+      key,
+      type: tag,
+      status,
+      preconditions: computed(() => computePreconditions(node, ctx)),
+      blockedByFailure: computed(() => computeBlockedByFailure(node, ctx)),
+      children: [],
+    };
+
+    ctx.nodes.set(key, node);
+    ctx.statusSignals.set(key, status);
+    ctx.preconditions.set(key, node.preconditions);
+    ctx.blockedByFailure.set(key, node.blockedByFailure);
+
+    if (parent) {
+      ctx.parentMap.set(key, parent.key);
+      const siblings = ctx.siblingMap.get(parent.key);
+      if (siblings) {
+        siblings.push(key);
+      } else {
+        ctx.siblingMap.set(parent.key, [key]);
+      }
+    }
+
+    if (!ctx.siblingMap.has(key)) {
+      ctx.siblingMap.set(key, []);
+    }
+
+    return node;
+  },
+
+  createTextInstance(_text, ctx, _parent) {
+    const counter = ctx._containerCounter++;
+    const key = `__text_${counter}`;
+    const status = signal<NodeStatus>("idle");
+    const node: WorkflowNode = {
+      key,
+      type: "sequential" as WorkflowTag,
+      status,
+      preconditions: computed(() => true),
+      blockedByFailure: computed(() => false),
+      children: [],
+    };
+    ctx.nodes.set(key, node);
+    ctx.statusSignals.set(key, status);
+    return node;
+  },
+
+  appendChild(parent, child, _ctx) {
+    if (!parent.children.includes(child)) {
+      parent.children.push(child);
+    }
+  },
+
+  insertBefore(parent, child, before, _ctx) {
+    const idx = parent.children.indexOf(before);
+    if (idx === -1) {
+      parent.children.push(child);
+    } else {
+      if (!parent.children.includes(child)) {
+        parent.children.splice(idx, 0, child);
+      }
+    }
+  },
+
+  removeChild(parent, child, ctx) {
+    parent.children = parent.children.filter((c) => c.key !== child.key);
+
+    const siblings = ctx.siblingMap.get(parent.key);
+    if (siblings) {
+      const idx = siblings.indexOf(child.key);
+      if (idx !== -1) {
+        siblings.splice(idx, 1);
+      }
+    }
+  },
+
+  prepareUpdate() {
+    return null;
+  },
+
+  commitUpdate() {
+  },
+
+  emit() {
+  },
+
+  finalizeInstance(_instance, _ctx) {
+  },
+};
--- a/src/index.ts
+++ b/src/index.ts
@@ -1,9 +1,7 @@
 export * from "./error/index.js";
-
-export { FlowGraph, buildTypeEdges, type FlowGraphOptions, type OperationSpec, type CallEventMapValue, type CallRequestedEvent, type CallRespondedEvent, type CallErrorEvent, type CallAbortedEvent, type CallCompletedEvent } from "./graph/index.js";
-export { typeCompat, type TypeCompatResult, type TypeMismatch } from "./analysis/type-compat.js";
-export {
-  validateSchema,
-  validateGraph,
-  validate,
-} from "./graph/validation.js";
+export * from "./schema/index.js";
+export * from "./component/index.js";
+export * from "./host/index.js";
+export * from "./reactive/index.js";
+export * from "./analysis/index.js";
+export * from "./graph/index.js";
--- a/src/reactive/index.ts
+++ b/src/reactive/index.ts
@@ -1,16 +1,17 @@
 export {
  WorkflowReactiveRoot,
  type FailurePolicy,
-  type CallEventMapValue,
-  type CallRequestedEvent,
-  type CallRespondedEvent,
-  type CallErrorEvent,
-  type CallAbortedEvent,
-  type CallCompletedEvent,
  type EventLogProjection,
  type AggregateStatus,
+  type ParallelGroup,
+  type ParallelGroupConfig,
 } from "./workflow.js";

+export type {
+  WorkflowNode,
+  ReactiveContext,
+} from "../host/reactive.js";
+
 export {
  computePreconditions,
  computeBlockedByFailure,
--- a/src/reactive/node-status.ts
+++ b/src/reactive/node-status.ts
@@ -39,11 +39,11 @@ export function computeBlockedByFailure(

 export function registerStartEffect(
  status: Signal<NodeStatus>,
-  preconditions: ReadonlySignal<boolean>,
+  canStart: ReadonlySignal<boolean>,
  effectDisposers: (() => void)[],
 ): void {
  const disposer = effect(() => {
-    if (preconditions.value) {
+    if (canStart.value) {
      const current = status.value;
      if (current === "idle" || current === "waiting") {
        status.value = "ready";
--- a/src/reactive/workflow.ts
+++ b/src/reactive/workflow.ts
@@ -3,6 +3,8 @@ import type { Signal, ReadonlySignal } from "@preact/signals-core";
 import type { DirectedGraph } from "graphology";
 import type { NodeStatus } from "../schema/enums.js";
 import type { CallResult } from "../schema/edge.js";
+import type { CallEventMapValue } from "../graph/construction.js";
+export type { CallEventMapValue } from "../graph/construction.js";
 import {
  computePreconditions,
  computeBlockedByFailure,
@@ -13,48 +15,15 @@ import type { NodeStatusContext } from "./node-status.js";

 export type FailurePolicy = "continue-running" | "abort-dependents";

-export interface CallRequestedEvent {
-  type: "call.requested";
-  requestId: string;
-  operationId: string;
-  input: unknown;
-  timestamp: string;
+export interface ParallelGroup {
+  siblings: string[];
+  maxConcurrency?: number;
 }

-export interface CallRespondedEvent {
-  type: "call.responded";
-  requestId: string;
-  output: unknown;
-  timestamp: string;
+export interface ParallelGroupConfig {
+  [groupKey: string]: ParallelGroup;
 }

-export interface CallErrorEvent {
-  type: "call.error";
-  requestId: string;
-  error: { code: string; message: string; details?: unknown };
-  timestamp: string;
-}
-
-export interface CallAbortedEvent {
-  type: "call.aborted";
-  requestId: string;
-  timestamp: string;
-}
-
-export interface CallCompletedEvent {
-  type: "call.completed";
-  requestId: string;
-  output: unknown;
-  timestamp: string;
-}
-
-export type CallEventMapValue =
-  | CallRequestedEvent
-  | CallRespondedEvent
-  | CallErrorEvent
-  | CallAbortedEvent
-  | CallCompletedEvent;
-
 export interface EventLogProjection {
  append(event: CallEventMapValue): void;
  getStatus(nodeId: string): NodeStatus;
@@ -92,6 +61,7 @@ const EVENT_TO_STATUS: Record<string, NodeStatus> = {
 export class WorkflowReactiveRoot implements EventLogProjection {
  statusMap: Map<string, Signal<NodeStatus>>;
  preconditions: Map<string, ReadonlySignal<boolean>>;
+  canStart: Map<string, ReadonlySignal<boolean>>;
  blockedByFailure: Map<string, ReadonlySignal<boolean>>;
  resultMap: Map<string, ReadonlySignal<CallResult | undefined>>;
  nodeKeyToRequestId: Map<string, string>;
@@ -101,14 +71,16 @@ export class WorkflowReactiveRoot implements EventLogProjection {
  private effectDisposers: (() => void)[];
  private eventLog: CallEventMapValue[];
  private _failurePolicy: FailurePolicy;
+  private _parallelGroups: ParallelGroupConfig;

  constructor(
    graph: DirectedGraph,
-    options?: { failurePolicy?: FailurePolicy },
+    options?: { failurePolicy?: FailurePolicy; parallelGroups?: ParallelGroupConfig },
  ) {
    this.graph = graph;
    this.statusMap = new Map();
    this.preconditions = new Map();
+    this.canStart = new Map();
    this.blockedByFailure = new Map();
    this.resultMap = new Map();
    this.effectDisposers = [];
@@ -116,6 +88,7 @@ export class WorkflowReactiveRoot implements EventLogProjection {
    this.nodeKeyToRequestId = new Map();
    this.requestIdToNodeKey = new Map();
    this._failurePolicy = options?.failurePolicy ?? "continue-running";
+    this._parallelGroups = options?.parallelGroups ?? {};
    this.initializeSignals();
  }

@@ -125,6 +98,13 @@ export class WorkflowReactiveRoot implements EventLogProjection {
  }

  private initializeSignals(): void {
+    const nodeToGroupKey = new Map<string, string>();
+    for (const [groupKey, group] of Object.entries(this._parallelGroups)) {
+      for (const sibling of group.siblings) {
+        nodeToGroupKey.set(sibling, groupKey);
+      }
+    }
+
    for (const node of this.graph.nodes()) {
      const predecessors: string[] = this.graph.inNeighbors(node) ?? [];

@@ -139,6 +119,26 @@ export class WorkflowReactiveRoot implements EventLogProjection {
        return computePreconditions(node, ctx);
      });

+      const groupKey = nodeToGroupKey.get(node);
+      const parallelGroup = groupKey ? this._parallelGroups[groupKey] : undefined;
+      const maxConc = parallelGroup?.maxConcurrency;
+      const siblings = parallelGroup?.siblings ?? [];
+
+      let canStartComputed: ReadonlySignal<boolean>;
+      if (maxConc !== undefined && siblings.length > 0) {
+        const otherSiblings = siblings.filter((s) => s !== node);
+        canStartComputed = computed(() => {
+          if (!preconditionsComputed.value) return false;
+          const activeSiblingCount = otherSiblings.filter((sib) => {
+            const sibStatus = this.statusMap.get(sib);
+            return sibStatus && (sibStatus.value === "running" || sibStatus.value === "ready");
+          }).length;
+          return activeSiblingCount < maxConc;
+        });
+      } else {
+        canStartComputed = preconditionsComputed;
+      }
+
      const blockedByFailureComputed = computed(() => {
        return computeBlockedByFailure(node, ctx);
      });
@@ -189,16 +189,17 @@ export class WorkflowReactiveRoot implements EventLogProjection {

      this.statusMap.set(node, status);
      this.preconditions.set(node, preconditionsComputed);
+      this.canStart.set(node, canStartComputed);
      this.blockedByFailure.set(node, blockedByFailureComputed);
      this.resultMap.set(node, resultComputed);
    }

    for (const node of this.graph.nodes()) {
      const status = this.statusMap.get(node)!;
-      const preconditions = this.preconditions.get(node)!;
+      const canStart = this.canStart.get(node)!;
      const blocked = this.blockedByFailure.get(node)!;

-      registerStartEffect(status, preconditions, this.effectDisposers);
+      registerStartEffect(status, canStart, this.effectDisposers);
      registerAbortEffect(status, blocked, this.effectDisposers, {
        abortDependents: this._failurePolicy === "abort-dependents",
      });
@@ -338,6 +339,7 @@ export class WorkflowReactiveRoot implements EventLogProjection {
    this.effectDisposers = [];
    this.statusMap.clear();
    this.preconditions.clear();
+    this.canStart.clear();
    this.blockedByFailure.clear();
    this.resultMap.clear();
    this.nodeKeyToRequestId.clear();
--- a/tasks/api-public-exports.md
+++ b/tasks/api-public-exports.md
@@ -1,7 +1,7 @@
 ---
 id: api/public-exports
 name: Wire barrel exports and verify exports map resolves correctly for all sub-paths
-status: pending
+status: completed
 depends_on:
  - review/reactive-and-hosts
  - analysis/type-compat
--- a/tasks/host-reactive.md
+++ b/tasks/host-reactive.md
@@ -1,7 +1,7 @@
 ---
 id: host/reactive
 name: Implement ReactiveHostConfig — render ujsx template to reactive execution engine
-status: pending
+status: completed
 depends_on:
  - component/operation
  - component/sequential
--- a/tasks/meta-analysis-layer.md
+++ b/tasks/meta-analysis-layer.md
@@ -1,7 +1,7 @@
 ---
 id: meta/analysis-layer
 name: Complete analysis layer — type compatibility, ordering, template/graph validation, defaults
-status: pending
+status: completed
 depends_on:
  - analysis/type-compat
  - analysis/build-type-edges
--- a/tasks/meta-graph-layer.md
+++ b/tasks/meta-graph-layer.md
@@ -1,7 +1,7 @@
 ---
 id: meta/graph-layer
 name: Complete graph layer — FlowGraph class, all construction paths, queries, validation
-status: pending
+status: completed
 depends_on:
  - graph/flowgraph-class
  - graph/construction-operation
--- a/tasks/meta-reactive-layer.md
+++ b/tasks/meta-reactive-layer.md
@@ -1,7 +1,7 @@
 ---
 id: meta/reactive-layer
 name: Complete reactive execution layer — WorkflowRoot, node-status, maxConcurrency, retries
-status: pending
+status: completed
 depends_on:
  - reactive/workflow-root
  - reactive/node-status
@@ -19,11 +19,11 @@ Meta task that clusters all reactive execution tasks. Once complete, the reactiv

 ## Acceptance Criteria

- [ ] All reactive tasks completed
- [ ] WorkflowReactiveRoot implements EventLogProjection correctly
- [ ] Preconditions drive automatic state transitions
- [ ] Failure follows dependency edges, not structural scope
- [ ] dispose() prevents signal leaks
+- [x] All reactive tasks completed
+- [x] WorkflowReactiveRoot implements EventLogProjection correctly
+- [x] Preconditions drive automatic state transitions
+- [x] Failure follows dependency edges, not structural scope
+- [x] dispose() prevents signal leaks

 ## References

@@ -31,8 +31,8 @@ Meta task that clusters all reactive execution tasks. Once complete, the reactiv

 ## Notes

-> To be filled by implementation agent
+All four dependent tasks (reactive/workflow-root, reactive/node-status, reactive/max-concurrency, reactive/retry-semantics) were already completed. This meta-task verifies the integrated reactive execution layer works correctly end-to-end.

 ## Summary

-> To be filled on completion
+Verified the complete reactive execution layer: WorkflowReactiveRoot implements EventLogProjection correctly with signal-backed status, computed preconditions drive automatic state transitions, failure propagation follows dependency edges (not structural scope), maxConcurrency semaphore works for Parallel groups, retry semantics preserve full event history, and dispose() prevents signal leaks. All 665 tests pass (129 reactive-specific).
--- a/tasks/reactive-and-hosts.md
+++ b/tasks/reactive-and-hosts.md
@@ -1,7 +1,7 @@
 ---
 id: review/reactive-and-hosts
 name: Review reactive execution and host configs — signal graph, preconditions, HostConfig implementations
-status: pending
+status: completed
 depends_on:
  - reactive/workflow-root
  - reactive/node-status
--- a/tasks/reactive-max-concurrency.md
+++ b/tasks/reactive-max-concurrency.md
@@ -1,7 +1,7 @@
 ---
 id: reactive/max-concurrency
 name: Implement maxConcurrency semaphore for Parallel groups
-status: pending
+status: completed
 depends_on:
  - reactive/node-status
  - component/parallel
--- a/tasks/reactive-node-status.md
+++ b/tasks/reactive-node-status.md
@@ -1,7 +1,7 @@
 ---
 id: reactive/node-status
 name: Implement node status signal management and computed preconditions + blockedByFailure
-status: pending
+status: completed
 depends_on:
  - reactive/workflow-root
  - schema/enums
--- a/tasks/reactive-retry-semantics.md
+++ b/tasks/reactive-retry-semantics.md
@@ -1,7 +1,7 @@
 ---
 id: reactive/retry-semantics
 name: Implement retry semantics — event log append with new requestId, status projection respects retries
-status: pending
+status: completed
 depends_on:
  - reactive/workflow-root
 scope: narrow
--- a/tasks/review-complete-library.md
+++ b/tasks/review-complete-library.md
@@ -1,7 +1,7 @@
 ---
 id: review/complete-library
 name: Final review — validate full library against architecture docs, build, and exports
-status: pending
+status: completed
 depends_on:
  - api/public-exports
  - review/foundation
--- a/tasks/review-foundation.md
+++ b/tasks/review-foundation.md
@@ -1,7 +1,7 @@
 ---
 id: review/foundation
 name: Review foundation layer — schemas, errors, FlowGraph class, construction
-status: pending
+status: completed
 depends_on:
  - schema/enums
  - schema/node-attrs
--- a/test/exports.test.ts
+++ b/test/exports.test.ts
@@ -0,0 +1,77 @@
+import { describe, it, expect } from "vitest";
+
+import { FlowGraph, typeCompat, CycleError, OperationNodeAttrs, Operation, GraphologyHostConfig, WorkflowReactiveRoot, topologicalOrder } from "../src/index.js";
+import { buildTypeEdges as buildTypeEdgesGraph } from "../src/graph/index.js";
+import { CallStatusEnum, NodeStatusEnum, EdgeTypeEnum, CallResultSchema, OperationEdgeAttrs, CallEdgeAttrs, TemplateEdgeAttrs, CallNodeAttrs } from "../src/schema/index.js";
+import { Sequential, Parallel, Conditional, Map } from "../src/component/index.js";
+import { ReactiveHostConfig } from "../src/host/index.js";
+import { WorkflowReactiveRoot as ReactiveRootFromReactive, computePreconditions, computeBlockedByFailure } from "../src/reactive/index.js";
+import { typeCompat as typeCompatAnalysis, buildTypeEdges, validateGraph, validateTemplate, topologicalOrder as topologicalOrderAnalysis, parallelGroups, criticalPath, reachableFrom } from "../src/analysis/index.js";
+import { FlowgraphError, ConstructionError, CycleError as CycleErrorFromError, InvalidTransitionError } from "../src/error/index.js";
+
+describe("Sub-path imports", () => {
+  it("@alkdev/flowgraph → all public types", () => {
+    expect(FlowGraph).toBeDefined();
+    expect(typeCompat).toBeDefined();
+    expect(CycleError).toBeDefined();
+    expect(OperationNodeAttrs).toBeDefined();
+    expect(Operation).toBeDefined();
+    expect(GraphologyHostConfig).toBeDefined();
+    expect(WorkflowReactiveRoot).toBeDefined();
+    expect(topologicalOrder).toBeDefined();
+  });
+
+  it("@alkdev/flowgraph/graph → FlowGraph, FlowGraphOptions", () => {
+    expect(FlowGraph).toBeDefined();
+    expect(buildTypeEdgesGraph).toBeDefined();
+  });
+
+  it("@alkdev/flowgraph/schema → all schemas, enums, types, CallResult", () => {
+    expect(OperationNodeAttrs).toBeDefined();
+    expect(CallNodeAttrs).toBeDefined();
+    expect(OperationEdgeAttrs).toBeDefined();
+    expect(CallEdgeAttrs).toBeDefined();
+    expect(TemplateEdgeAttrs).toBeDefined();
+    expect(CallResultSchema).toBeDefined();
+    expect(CallStatusEnum).toBeDefined();
+    expect(NodeStatusEnum).toBeDefined();
+    expect(EdgeTypeEnum).toBeDefined();
+  });
+
+  it("@alkdev/flowgraph/component → Operation, Sequential, Parallel, Conditional, Map", () => {
+    expect(Operation).toBeDefined();
+    expect(Sequential).toBeDefined();
+    expect(Parallel).toBeDefined();
+    expect(Conditional).toBeDefined();
+    expect(Map).toBeDefined();
+  });
+
+  it("@alkdev/flowgraph/host → GraphologyHostConfig, ReactiveHostConfig", () => {
+    expect(GraphologyHostConfig).toBeDefined();
+    expect(ReactiveHostConfig).toBeDefined();
+  });
+
+  it("@alkdev/flowgraph/reactive → WorkflowReactiveRoot, EventLogProjection", () => {
+    expect(ReactiveRootFromReactive).toBeDefined();
+    expect(computePreconditions).toBeDefined();
+    expect(computeBlockedByFailure).toBeDefined();
+  });
+
+  it("@alkdev/flowgraph/analysis → typeCompat, buildTypeEdges, validateGraph, validateTemplate, topologicalOrder, parallelGroups, criticalPath, reachableFrom", () => {
+    expect(typeCompatAnalysis).toBeDefined();
+    expect(buildTypeEdges).toBeDefined();
+    expect(validateGraph).toBeDefined();
+    expect(validateTemplate).toBeDefined();
+    expect(topologicalOrderAnalysis).toBeDefined();
+    expect(parallelGroups).toBeDefined();
+    expect(criticalPath).toBeDefined();
+    expect(reachableFrom).toBeDefined();
+  });
+
+  it("@alkdev/flowgraph/error → all error classes", () => {
+    expect(FlowgraphError).toBeDefined();
+    expect(ConstructionError).toBeDefined();
+    expect(CycleErrorFromError).toBeDefined();
+    expect(InvalidTransitionError).toBeDefined();
+  });
+});
--- a/test/graph/construction.test.ts
+++ b/test/graph/construction.test.ts
@@ -9,7 +9,7 @@ import {
  CycleError,
  InvalidTransitionError,
 } from "../../src/error/index.js";
-import type { CallStatus } from "../../src/error/index.js";
+import type { CallStatus } from "../../src/schema/enums.js";

 describe("FlowGraph constructor", () => {
  it("creates an empty graph", () => {
--- a/test/host/reactive.test.ts
+++ b/test/host/reactive.test.ts
@@ -1,7 +1,507 @@
-import { describe, it, expect } from 'vitest';
+import { describe, it, expect } from "vitest";
+import { h, createHostRoot } from "@alkdev/ujsx";
+import { Operation, Sequential, Parallel, Conditional, Map } from "../../src/component/index.js";
+import { ReactiveHostConfig } from "../../src/host/reactive.js";
+import type { WorkflowNode, ReactiveContext } from "../../src/host/reactive.js";

-describe('reactive host', () => {
-  it('placeholder', () => {
-    expect(true).toBe(true);
+function renderTemplate(template: ReturnType<typeof h>): ReactiveContext {
+  const root = createHostRoot(ReactiveHostConfig, null);
+  root.render(template);
+  return root.ctx;
+}
+
+describe("ReactiveHostConfig", () => {
+  describe("createRootContext", () => {
+    it("creates fresh ReactiveContext with empty maps", () => {
+      const ctx = ReactiveHostConfig.createRootContext(null);
+      expect(ctx.nodes.size).toBe(0);
+      expect(ctx.statusSignals.size).toBe(0);
+      expect(ctx.parentMap.size).toBe(0);
+      expect(ctx.siblingMap.size).toBe(0);
+    });
+
+    it("accepts options with registry", () => {
+      const registry = { resolve: (name: string) => name };
+      const ctx = ReactiveHostConfig.createRootContext(null, { registry });
+      expect(ctx.operationRegistry).toBe(registry);
+    });
+  });
+
+  describe("createInstance for operation", () => {
+    it("creates WorkflowNode with correct key and type", () => {
+      const template = h(Sequential, {},
+        h(Operation, { name: "classify" }),
+      );
+
+      const ctx = renderTemplate(template);
+      const node = ctx.nodes.get("classify");
+      expect(node).toBeDefined();
+      expect(node!.key).toBe("classify");
+      expect(node!.type).toBe("operation");
+      expect(node!.operationId).toBe("classify");
+    });
+
+    it("creates WorkflowNode with idle status signal", () => {
+      const template = h(Sequential, {},
+        h(Operation, { name: "classify" }),
+      );
+
+      const ctx = renderTemplate(template);
+      const node = ctx.nodes.get("classify")!;
+      expect(node.status.value).toBe("idle");
+    });
+
+    it("registers node in context maps", () => {
+      const template = h(Sequential, {},
+        h(Operation, { name: "classify" }),
+      );
+
+      const ctx = renderTemplate(template);
+      expect(ctx.statusSignals.has("classify")).toBe(true);
+      expect(ctx.preconditions.has("classify")).toBe(true);
+      expect(ctx.blockedByFailure.has("classify")).toBe(true);
+    });
+
+    it("creates output signal for operation nodes", () => {
+      const template = h(Sequential, {},
+        h(Operation, { name: "classify" }),
+      );
+
+      const ctx = renderTemplate(template);
+      const node = ctx.nodes.get("classify")!;
+      expect(node.output).toBeDefined();
+      expect(node.output!.value).toBeUndefined();
+    });
+  });
+
+  describe("createInstance for structural containers", () => {
+    it("creates WorkflowNode tracking children for Sequential", () => {
+      const template = h(Sequential, {},
+        h(Operation, { name: "A" }),
+        h(Operation, { name: "B" }),
+      );
+
+      const ctx = renderTemplate(template);
+      const seqNode = ctx.nodes.get("__sequential_0");
+      expect(seqNode).toBeDefined();
+      expect(seqNode!.type).toBe("sequential");
+      expect(seqNode!.children.length).toBe(2);
+    });
+
+    it("creates WorkflowNode for Parallel with children", () => {
+      const template = h(Parallel, {},
+        h(Operation, { name: "A" }),
+        h(Operation, { name: "B" }),
+      );
+
+      const ctx = renderTemplate(template);
+      const parNode = ctx.nodes.get("__parallel_0");
+      expect(parNode).toBeDefined();
+      expect(parNode!.type).toBe("parallel");
+      expect(parNode!.children.length).toBe(2);
+    });
+
+    it("creates WorkflowNode for Conditional with children", () => {
+      const template = h(Sequential, {},
+        h(Operation, { name: "A" }),
+        h(Conditional, { test: "A" },
+          h(Operation, { name: "B" }),
+        ),
+      );
+
+      const ctx = renderTemplate(template);
+      const condNode = ctx.nodes.get("__conditional_1");
+      expect(condNode).toBeDefined();
+      expect(condNode!.type).toBe("conditional");
+    });
+
+    it("structural containers do not have operationId", () => {
+      const template = h(Sequential, {},
+        h(Operation, { name: "A" }),
+      );
+
+      const ctx = renderTemplate(template);
+      const seqNode = ctx.nodes.get("__sequential_0")!;
+      expect(seqNode.operationId).toBeUndefined();
+    });
+  });
+
+  describe("signal initial states", () => {
+    it("root operation has preconditions met (no predecessors)", () => {
+      const template = h(Sequential, {},
+        h(Operation, { name: "A" }),
+        h(Operation, { name: "B" }),
+      );
+
+      const ctx = renderTemplate(template);
+      const nodeA = ctx.nodes.get("A")!;
+      expect(nodeA.preconditions.value).toBe(true);
+    });
+
+    it("second operation in sequential has unmet preconditions", () => {
+      const template = h(Sequential, {},
+        h(Operation, { name: "A" }),
+        h(Operation, { name: "B" }),
+      );
+
+      const ctx = renderTemplate(template);
+      const nodeB = ctx.nodes.get("B")!;
+      expect(nodeB.preconditions.value).toBe(false);
+    });
+
+    it("parallel children have preconditions met (no inter-child deps)", () => {
+      const template = h(Parallel, {},
+        h(Operation, { name: "A" }),
+        h(Operation, { name: "B" }),
+      );
+
+      const ctx = renderTemplate(template);
+      expect(ctx.nodes.get("A")!.preconditions.value).toBe(true);
+      expect(ctx.nodes.get("B")!.preconditions.value).toBe(true);
+    });
+
+    it("all initial blockedByFailure are false", () => {
+      const template = h(Sequential, {},
+        h(Operation, { name: "A" }),
+        h(Operation, { name: "B" }),
+      );
+
+      const ctx = renderTemplate(template);
+      expect(ctx.nodes.get("A")!.blockedByFailure.value).toBe(false);
+      expect(ctx.nodes.get("B")!.blockedByFailure.value).toBe(false);
+    });
+  });
+
+  describe("precondition transition on predecessor completion", () => {
+    it("sequential: completing predecessor updates dependent preconditions", () => {
+      const template = h(Sequential, {},
+        h(Operation, { name: "A" }),
+        h(Operation, { name: "B" }),
+      );
+
+      const ctx = renderTemplate(template);
+      const nodeA = ctx.nodes.get("A")!;
+      const nodeB = ctx.nodes.get("B")!;
+
+      expect(nodeB.preconditions.value).toBe(false);
+
+      nodeA.status.value = "completed";
+
+      expect(nodeB.preconditions.value).toBe(true);
+    });
+
+    it("sequential: skipped predecessor satisfies preconditions", () => {
+      const template = h(Sequential, {},
+        h(Operation, { name: "A" }),
+        h(Operation, { name: "B" }),
+      );
+
+      const ctx = renderTemplate(template);
+      const nodeA = ctx.nodes.get("A")!;
+
+      nodeA.status.value = "skipped";
+
+      expect(ctx.nodes.get("B")!.preconditions.value).toBe(true);
+    });
+
+    it("sequential chain: A→B→C, completing A then B", () => {
+      const template = h(Sequential, {},
+        h(Operation, { name: "A" }),
+        h(Operation, { name: "B" }),
+        h(Operation, { name: "C" }),
+      );
+
+      const ctx = renderTemplate(template);
+
+      expect(ctx.nodes.get("B")!.preconditions.value).toBe(false);
+      expect(ctx.nodes.get("C")!.preconditions.value).toBe(false);
+
+      ctx.nodes.get("A")!.status.value = "completed";
+      expect(ctx.nodes.get("B")!.preconditions.value).toBe(true);
+      expect(ctx.nodes.get("C")!.preconditions.value).toBe(false);
+
+      ctx.nodes.get("B")!.status.value = "completed";
+      expect(ctx.nodes.get("C")!.preconditions.value).toBe(true);
+    });
+
+    it("parallel children preconditions independent of each other", () => {
+      const template = h(Sequential, {},
+        h(Operation, { name: "pre" }),
+        h(Parallel, {},
+          h(Operation, { name: "A" }),
+          h(Operation, { name: "B" }),
+        ),
+      );
+
+      const ctx = renderTemplate(template);
+
+      expect(ctx.nodes.get("A")!.preconditions.value).toBe(false);
+      expect(ctx.nodes.get("B")!.preconditions.value).toBe(false);
+
+      ctx.nodes.get("pre")!.status.value = "completed";
+
+      expect(ctx.nodes.get("A")!.preconditions.value).toBe(true);
+      expect(ctx.nodes.get("B")!.preconditions.value).toBe(true);
+    });
+  });
+
+  describe("failure propagation", () => {
+    it("sequential: failed predecessor causes blockedByFailure to be true", () => {
+      const template = h(Sequential, {},
+        h(Operation, { name: "A" }),
+        h(Operation, { name: "B" }),
+      );
+
+      const ctx = renderTemplate(template);
+
+      ctx.nodes.get("A")!.status.value = "failed";
+
+      expect(ctx.nodes.get("B")!.blockedByFailure.value).toBe(true);
+    });
+
+    it("sequential: aborted predecessor causes blockedByFailure to be true", () => {
+      const template = h(Sequential, {},
+        h(Operation, { name: "A" }),
+        h(Operation, { name: "B" }),
+      );
+
+      const ctx = renderTemplate(template);
+
+      ctx.nodes.get("A")!.status.value = "aborted";
+
+      expect(ctx.nodes.get("B")!.blockedByFailure.value).toBe(true);
+    });
+
+    it("parallel siblings are independent for failure propagation", () => {
+      const template = h(Parallel, {},
+        h(Operation, { name: "A" }),
+        h(Operation, { name: "B" }),
+      );
+
+      const ctx = renderTemplate(template);
+
+      ctx.nodes.get("A")!.status.value = "failed";
+
+      expect(ctx.nodes.get("B")!.blockedByFailure.value).toBe(false);
+    });
+
+    it("failed predecessor does not satisfy preconditions", () => {
+      const template = h(Sequential, {},
+        h(Operation, { name: "A" }),
+        h(Operation, { name: "B" }),
+      );
+
+      const ctx = renderTemplate(template);
+
+      ctx.nodes.get("A")!.status.value = "failed";
+
+      expect(ctx.nodes.get("B")!.preconditions.value).toBe(false);
+    });
+  });
+
+  describe("appendChild", () => {
+    it("appends children to parent's children array", () => {
+      const template = h(Sequential, {},
+        h(Operation, { name: "A" }),
+        h(Operation, { name: "B" }),
+      );
+
+      const ctx = renderTemplate(template);
+      const seqNode = ctx.nodes.get("__sequential_0")!;
+      expect(seqNode.children.length).toBe(2);
+      expect(seqNode.children[0]!.key).toBe("A");
+      expect(seqNode.children[1]!.key).toBe("B");
+    });
+
+    it("does not duplicate children", () => {
+      const template = h(Sequential, {},
+        h(Operation, { name: "A" }),
+      );
+
+      const ctx = renderTemplate(template);
+      const seqNode = ctx.nodes.get("__sequential_0")!;
+      const childNode = ctx.nodes.get("A")!;
+      ReactiveHostConfig.appendChild(seqNode, childNode, ctx);
+      expect(seqNode.children.length).toBe(1);
+    });
+  });
+
+  describe("removeChild", () => {
+    it("removes child from parent's children array", () => {
+      const template = h(Sequential, {},
+        h(Operation, { name: "A" }),
+        h(Operation, { name: "B" }),
+      );
+
+      const ctx = renderTemplate(template);
+      const seqNode = ctx.nodes.get("__sequential_0")!;
+      const childB = ctx.nodes.get("B")!;
+
+      ReactiveHostConfig.removeChild(seqNode, childB, ctx);
+      expect(seqNode.children.length).toBe(1);
+      expect(seqNode.children[0]!.key).toBe("A");
+    });
+
+    it("preconditions auto-reevaluate after removeChild", () => {
+      const template = h(Sequential, {},
+        h(Operation, { name: "A" }),
+        h(Operation, { name: "B" }),
+        h(Operation, { name: "C" }),
+      );
+
+      const ctx = renderTemplate(template);
+      const seqNode = ctx.nodes.get("__sequential_0")!;
+      const childB = ctx.nodes.get("B")!;
+
+      ctx.nodes.get("A")!.status.value = "completed";
+
+      expect(childB.preconditions.value).toBe(true);
+
+      ReactiveHostConfig.removeChild(seqNode, childB, ctx);
+
+      const childC = ctx.nodes.get("C")!;
+      expect(childC.preconditions.value).toBe(true);
+    });
+  });
+
+  describe("parentMap and siblingMap", () => {
+    it("registers parent-child relationships in parentMap", () => {
+      const template = h(Sequential, {},
+        h(Operation, { name: "A" }),
+        h(Operation, { name: "B" }),
+      );
+
+      const ctx = renderTemplate(template);
+
+      expect(ctx.parentMap.get("A")).toBe("__sequential_0");
+      expect(ctx.parentMap.get("B")).toBe("__sequential_0");
+    });
+
+    it("registers siblings in siblingMap", () => {
+      const template = h(Sequential, {},
+        h(Operation, { name: "A" }),
+        h(Operation, { name: "B" }),
+      );
+
+      const ctx = renderTemplate(template);
+
+      const siblings = ctx.siblingMap.get("__sequential_0");
+      expect(siblings).toEqual(["A", "B"]);
+    });
+
+    it("nested structures register correct parent", () => {
+      const template = h(Sequential, {},
+        h(Operation, { name: "pre" }),
+        h(Parallel, {},
+          h(Operation, { name: "A" }),
+          h(Operation, { name: "B" }),
+        ),
+      );
+
+      const ctx = renderTemplate(template);
+
+      expect(ctx.parentMap.get("pre")).toBe("__sequential_0");
+      expect(ctx.parentMap.get("A")).toBe("__parallel_1");
+      expect(ctx.parentMap.get("B")).toBe("__parallel_1");
+
+      const seqSiblings = ctx.siblingMap.get("__sequential_0");
+      expect(seqSiblings).toEqual(["pre", "__parallel_1"]);
+
+      const parSiblings = ctx.siblingMap.get("__parallel_1");
+      expect(parSiblings).toEqual(["A", "B"]);
+    });
+  });
+
+  describe("Conditional as error boundary", () => {
+    it("conditional node is created with correct type", () => {
+      const template = h(Sequential, {},
+        h(Operation, { name: "A" }),
+        h(Conditional, { test: "A" },
+          h(Operation, { name: "B" }),
+        ),
+      );
+
+      const ctx = renderTemplate(template);
+
+      const condNode = ctx.nodes.get("__conditional_1");
+      expect(condNode).toBeDefined();
+      expect(condNode!.type).toBe("conditional");
+    });
+
+    it("conditional child has preconditions met (no inter-child ordering)", () => {
+      const template = h(Conditional, { test: "A" },
+        h(Operation, { name: "B" }),
+      );
+
+      const ctx = renderTemplate(template);
+
+      expect(ctx.nodes.get("B")!.preconditions.value).toBe(true);
+    });
+  });
+
+  describe("full template rendering", () => {
+    it("renders a complete pipeline template", () => {
+      const template = h(Sequential, {},
+        h(Operation, { name: "architect" }),
+        h(Operation, { name: "reviewer" }),
+        h(Parallel, {},
+          h(Operation, { name: "decomposer" }),
+          h(Operation, { name: "specialist" }),
+        ),
+        h(Operation, { name: "synthesizer" }),
+      );
+
+      const ctx = renderTemplate(template);
+
+      expect(ctx.nodes.get("architect")).toBeDefined();
+      expect(ctx.nodes.get("reviewer")).toBeDefined();
+      expect(ctx.nodes.get("decomposer")).toBeDefined();
+      expect(ctx.nodes.get("specialist")).toBeDefined();
+      expect(ctx.nodes.get("synthesizer")).toBeDefined();
+
+      expect(ctx.nodes.get("architect")!.preconditions.value).toBe(true);
+      expect(ctx.nodes.get("reviewer")!.preconditions.value).toBe(false);
+
+      ctx.nodes.get("architect")!.status.value = "completed";
+      expect(ctx.nodes.get("reviewer")!.preconditions.value).toBe(true);
+    });
+
+    it("deeply nested template registers all nodes", () => {
+      const template = h(Sequential, {},
+        h(Parallel, {},
+          h(Sequential, {},
+            h(Operation, { name: "A" }),
+            h(Operation, { name: "B" }),
+          ),
+          h(Operation, { name: "C" }),
+        ),
+      );
+
+      const ctx = renderTemplate(template);
+
+      expect(ctx.nodes.has("A")).toBe(true);
+      expect(ctx.nodes.has("B")).toBe(true);
+      expect(ctx.nodes.has("C")).toBe(true);
+    });
+  });
+
+  describe("shared signal references", () => {
+    it("WorkflowNode.status and statusSignals point to same signal", () => {
+      const template = h(Sequential, {},
+        h(Operation, { name: "A" }),
+      );
+
+      const ctx = renderTemplate(template);
+      const node = ctx.nodes.get("A")!;
+      const statusFromMap = ctx.statusSignals.get("A")!;
+
+      expect(node.status).toBe(statusFromMap);
+
+      statusFromMap.value = "running";
+      expect(node.status.value).toBe("running");
+
+      node.status.value = "completed";
+      expect(statusFromMap.value).toBe("completed");
+    });
  });
 });
--- a/test/reactive/max-concurrency.test.ts
+++ b/test/reactive/max-concurrency.test.ts
@@ -0,0 +1,482 @@
+import { describe, it, expect } from "vitest";
+import { DirectedGraph } from "graphology";
+import { WorkflowReactiveRoot } from "../../src/reactive/workflow.js";
+import type { ParallelGroupConfig } from "../../src/reactive/workflow.js";
+
+function makeParallelGroupGraph(): DirectedGraph {
+  const graph = new DirectedGraph();
+  graph.addNode("entry", { name: "entry" });
+  graph.addNode("a", { name: "a" });
+  graph.addNode("b", { name: "b" });
+  graph.addNode("c", { name: "c" });
+  graph.addNode("d", { name: "d" });
+  graph.addEdgeWithKey("entry->a", "entry", "a", { edgeType: "sequential" });
+  graph.addEdgeWithKey("entry->b", "entry", "b", { edgeType: "sequential" });
+  graph.addEdgeWithKey("entry->c", "entry", "c", { edgeType: "sequential" });
+  graph.addEdgeWithKey("entry->d", "entry", "d", { edgeType: "sequential" });
+  return graph;
+}
+
+function makeParallelGroupNoEntry(): DirectedGraph {
+  const graph = new DirectedGraph();
+  graph.addNode("a", { name: "a" });
+  graph.addNode("b", { name: "b" });
+  graph.addNode("c", { name: "c" });
+  return graph;
+}
+
+describe("maxConcurrency semaphore", () => {
+  describe("parallel group with maxConcurrency: 2", () => {
+    const parallelGroups: ParallelGroupConfig = {
+      group1: {
+        siblings: ["a", "b", "c", "d"],
+        maxConcurrency: 2,
+      },
+    };
+
+    it("limits running siblings to maxConcurrency", () => {
+      const graph = makeParallelGroupGraph();
+      const root = new WorkflowReactiveRoot(graph, { parallelGroups });
+
+      expect(root.canStart.has("a")).toBe(true);
+      expect(root.canStart.has("b")).toBe(true);
+      expect(root.canStart.has("c")).toBe(true);
+      expect(root.canStart.has("d")).toBe(true);
+
+      expect(root.statusMap.get("entry")!.value).toBe("ready");
+      root.statusMap.get("entry")!.value = "completed";
+
+      expect(root.preconditions.get("a")!.value).toBe(true);
+      expect(root.preconditions.get("b")!.value).toBe(true);
+      expect(root.preconditions.get("c")!.value).toBe(true);
+      expect(root.preconditions.get("d")!.value).toBe(true);
+
+      expect(root.canStart.get("a")!.value).toBe(true);
+      expect(root.canStart.get("b")!.value).toBe(true);
+
+      root.dispose();
+    });
+
+    it("canStart becomes false when maxConcurrency siblings are running", () => {
+      const graph = makeParallelGroupGraph();
+      const root = new WorkflowReactiveRoot(graph, { parallelGroups });
+
+      root.statusMap.get("entry")!.value = "completed";
+
+      root.statusMap.get("a")!.value = "running";
+      root.statusMap.get("b")!.value = "running";
+
+      expect(root.canStart.get("a")!.value).toBe(true);
+      expect(root.canStart.get("b")!.value).toBe(true);
+      expect(root.canStart.get("c")!.value).toBe(false);
+      expect(root.canStart.get("d")!.value).toBe(false);
+
+      root.dispose();
+    });
+
+    it("blocked nodes by semaphore stay idle (not ready)", () => {
+      const graph = makeParallelGroupGraph();
+      const root = new WorkflowReactiveRoot(graph, { parallelGroups });
+
+      root.statusMap.get("entry")!.value = "completed";
+
+      root.statusMap.get("a")!.value = "running";
+      root.statusMap.get("b")!.value = "running";
+
+      expect(root.statusMap.get("c")!.value).toBe("idle");
+      expect(root.statusMap.get("d")!.value).toBe("idle");
+
+      root.dispose();
+    });
+
+    it("slot opens when a running sibling completes", () => {
+      const graph = makeParallelGroupGraph();
+      const root = new WorkflowReactiveRoot(graph, { parallelGroups });
+
+      root.statusMap.get("entry")!.value = "completed";
+      root.statusMap.get("a")!.value = "running";
+      root.statusMap.get("b")!.value = "running";
+
+      expect(root.canStart.get("c")!.value).toBe(false);
+
+      root.statusMap.get("a")!.value = "completed";
+
+      expect(root.canStart.get("c")!.value).toBe(true);
+      expect(root.canStart.get("d")!.value).toBe(false);
+
+      expect(root.statusMap.get("c")!.value).toBe("ready");
+
+      root.dispose();
+    });
+
+    it("all slots eventually open as siblings complete", () => {
+      const graph = makeParallelGroupGraph();
+      const root = new WorkflowReactiveRoot(graph, { parallelGroups });
+
+      root.statusMap.get("entry")!.value = "completed";
+      root.statusMap.get("a")!.value = "running";
+      root.statusMap.get("b")!.value = "running";
+
+      root.statusMap.get("a")!.value = "completed";
+      expect(root.canStart.get("c")!.value).toBe(true);
+
+      root.statusMap.get("b")!.value = "completed";
+      expect(root.canStart.get("d")!.value).toBe(true);
+
+      root.dispose();
+    });
+
+    it("canStart correctly limits when sibling transitions to ready", () => {
+      const graph = makeParallelGroupGraph();
+      const root = new WorkflowReactiveRoot(graph, { parallelGroups });
+
+      root.statusMap.get("entry")!.value = "completed";
+
+      root.statusMap.get("a")!.value = "ready";
+      root.statusMap.get("b")!.value = "ready";
+
+      expect(root.canStart.get("c")!.value).toBe(false);
+      expect(root.canStart.get("d")!.value).toBe(false);
+
+      root.statusMap.get("a")!.value = "running";
+      root.statusMap.get("b")!.value = "running";
+
+      expect(root.canStart.get("c")!.value).toBe(false);
+      expect(root.canStart.get("d")!.value).toBe(false);
+
+      root.dispose();
+    });
+  });
+
+  describe("parallel group without maxConcurrency", () => {
+    const parallelGroups: ParallelGroupConfig = {
+      group1: {
+        siblings: ["a", "b", "c", "d"],
+      },
+    };
+
+    it("all siblings start immediately when preconditions are met", () => {
+      const graph = makeParallelGroupGraph();
+      const root = new WorkflowReactiveRoot(graph, { parallelGroups });
+
+      root.statusMap.get("entry")!.value = "completed";
+
+      expect(root.canStart.get("a")!.value).toBe(true);
+      expect(root.canStart.get("b")!.value).toBe(true);
+      expect(root.canStart.get("c")!.value).toBe(true);
+      expect(root.canStart.get("d")!.value).toBe(true);
+
+      expect(root.statusMap.get("a")!.value).toBe("ready");
+      expect(root.statusMap.get("b")!.value).toBe("ready");
+      expect(root.statusMap.get("c")!.value).toBe("ready");
+      expect(root.statusMap.get("d")!.value).toBe("ready");
+
+      root.dispose();
+    });
+
+    it("no semaphore — running siblings do not block others", () => {
+      const graph = makeParallelGroupGraph();
+      const root = new WorkflowReactiveRoot(graph, { parallelGroups });
+
+      root.statusMap.get("entry")!.value = "completed";
+      root.statusMap.get("a")!.value = "running";
+      root.statusMap.get("b")!.value = "running";
+
+      expect(root.canStart.get("c")!.value).toBe(true);
+      expect(root.canStart.get("d")!.value).toBe(true);
+
+      root.dispose();
+    });
+  });
+
+  describe("no parallelGroups config", () => {
+    it("all nodes start normally without semaphore", () => {
+      const graph = makeParallelGroupGraph();
+      const root = new WorkflowReactiveRoot(graph);
+
+      root.statusMap.get("entry")!.value = "completed";
+
+      expect(root.canStart.get("a")!.value).toBe(true);
+      expect(root.canStart.get("b")!.value).toBe(true);
+      expect(root.canStart.get("c")!.value).toBe(true);
+      expect(root.canStart.get("d")!.value).toBe(true);
+
+      expect(root.statusMap.get("a")!.value).toBe("ready");
+      expect(root.statusMap.get("b")!.value).toBe("ready");
+      expect(root.statusMap.get("c")!.value).toBe("ready");
+      expect(root.statusMap.get("d")!.value).toBe("ready");
+
+      root.dispose();
+    });
+  });
+
+  describe("maxConcurrency: 1 (serial within parallel)", () => {
+    const parallelGroups: ParallelGroupConfig = {
+      group1: {
+        siblings: ["a", "b", "c"],
+        maxConcurrency: 1,
+      },
+    };
+
+    it("only one sibling can run at a time", () => {
+      const graph = makeParallelGroupGraph();
+      const root = new WorkflowReactiveRoot(graph, { parallelGroups });
+
+      root.statusMap.get("entry")!.value = "completed";
+
+      const canStartA = root.canStart.get("a")!;
+      const canStartB = root.canStart.get("b")!;
+      const canStartC = root.canStart.get("c")!;
+
+      expect(canStartA.value).toBe(true);
+      expect(canStartB.value).toBe(false);
+      expect(canStartC.value).toBe(false);
+
+      root.statusMap.get("a")!.value = "running";
+
+      expect(canStartA.value).toBe(true);
+      expect(canStartB.value).toBe(false);
+      expect(canStartC.value).toBe(false);
+
+      root.dispose();
+    });
+
+    it("next sibling can start when current finishes", () => {
+      const graph = makeParallelGroupGraph();
+      const root = new WorkflowReactiveRoot(graph, { parallelGroups });
+
+      root.statusMap.get("entry")!.value = "completed";
+
+      root.statusMap.get("a")!.value = "running";
+      root.statusMap.get("a")!.value = "completed";
+
+      expect(root.canStart.get("b")!.value).toBe(true);
+      expect(root.canStart.get("c")!.value).toBe(false);
+
+      root.dispose();
+    });
+  });
+
+  describe("root-level parallel group with maxConcurrency", () => {
+    it("limits concurrent start for root nodes with no predecessors", () => {
+      const graph = makeParallelGroupNoEntry();
+      const parallelGroups: ParallelGroupConfig = {
+        root: {
+          siblings: ["a", "b", "c"],
+          maxConcurrency: 2,
+        },
+      };
+      const root = new WorkflowReactiveRoot(graph, { parallelGroups });
+
+      expect(root.canStart.get("a")!.value).toBe(true);
+      expect(root.canStart.get("b")!.value).toBe(true);
+      expect(root.canStart.get("c")!.value).toBe(false);
+
+      root.dispose();
+    });
+
+    it("third node becomes ready when a slot opens", () => {
+      const graph = makeParallelGroupNoEntry();
+      const parallelGroups: ParallelGroupConfig = {
+        root: {
+          siblings: ["a", "b", "c"],
+          maxConcurrency: 2,
+        },
+      };
+      const root = new WorkflowReactiveRoot(graph, { parallelGroups });
+
+      root.statusMap.get("a")!.value = "running";
+      root.statusMap.get("b")!.value = "running";
+
+      expect(root.canStart.get("c")!.value).toBe(false);
+      expect(root.statusMap.get("c")!.value).toBe("idle");
+
+      root.statusMap.get("a")!.value = "completed";
+
+      expect(root.canStart.get("c")!.value).toBe(true);
+      expect(root.statusMap.get("c")!.value).toBe("ready");
+
+      root.dispose();
+    });
+  });
+
+  describe("preconditions vs canStart", () => {
+    it("canStart is false when preconditions are not met even if semaphore has slots", () => {
+      const graph = makeParallelGroupGraph();
+      const parallelGroups: ParallelGroupConfig = {
+        group1: {
+          siblings: ["a", "b", "c", "d"],
+          maxConcurrency: 2,
+        },
+      };
+      const root = new WorkflowReactiveRoot(graph, { parallelGroups });
+
+      expect(root.preconditions.get("a")!.value).toBe(false);
+      expect(root.canStart.get("a")!.value).toBe(false);
+
+      root.dispose();
+    });
+
+    it("canStart requires both preconditions AND semaphore slot", () => {
+      const graph = makeParallelGroupGraph();
+      const parallelGroups: ParallelGroupConfig = {
+        group1: {
+          siblings: ["a", "b", "c", "d"],
+          maxConcurrency: 2,
+        },
+      };
+      const root = new WorkflowReactiveRoot(graph, { parallelGroups });
+
+      root.statusMap.get("entry")!.value = "completed";
+
+      expect(root.preconditions.get("a")!.value).toBe(true);
+      expect(root.canStart.get("a")!.value).toBe(true);
+
+      root.statusMap.get("a")!.value = "running";
+      root.statusMap.get("b")!.value = "running";
+
+      expect(root.preconditions.get("c")!.value).toBe(true);
+      expect(root.canStart.get("c")!.value).toBe(false);
+
+      root.dispose();
+    });
+  });
+
+  describe("failed sibling does not count as running", () => {
+    it("failed sibling frees a slot for semaphore", () => {
+      const graph = makeParallelGroupGraph();
+      const parallelGroups: ParallelGroupConfig = {
+        group1: {
+          siblings: ["a", "b", "c", "d"],
+          maxConcurrency: 2,
+        },
+      };
+      const root = new WorkflowReactiveRoot(graph, { parallelGroups });
+
+      root.statusMap.get("entry")!.value = "completed";
+      root.statusMap.get("a")!.value = "running";
+      root.statusMap.get("b")!.value = "running";
+
+      expect(root.canStart.get("c")!.value).toBe(false);
+
+      root.statusMap.get("b")!.value = "failed";
+
+      expect(root.canStart.get("c")!.value).toBe(true);
+
+      root.dispose();
+    });
+
+    it("completed sibling frees a slot for semaphore", () => {
+      const graph = makeParallelGroupGraph();
+      const parallelGroups: ParallelGroupConfig = {
+        group1: {
+          siblings: ["a", "b", "c", "d"],
+          maxConcurrency: 2,
+        },
+      };
+      const root = new WorkflowReactiveRoot(graph, { parallelGroups });
+
+      root.statusMap.get("entry")!.value = "completed";
+      root.statusMap.get("a")!.value = "running";
+      root.statusMap.get("b")!.value = "running";
+
+      root.statusMap.get("b")!.value = "completed";
+
+      expect(root.canStart.get("c")!.value).toBe(true);
+      expect(root.canStart.get("d")!.value).toBe(false);
+
+      root.dispose();
+    });
+
+    it("aborted sibling frees a slot for semaphore", () => {
+      const graph = makeParallelGroupGraph();
+      const parallelGroups: ParallelGroupConfig = {
+        group1: {
+          siblings: ["a", "b", "c", "d"],
+          maxConcurrency: 2,
+        },
+      };
+      const root = new WorkflowReactiveRoot(graph, { parallelGroups });
+
+      root.statusMap.get("entry")!.value = "completed";
+      root.statusMap.get("a")!.value = "running";
+      root.statusMap.get("b")!.value = "running";
+
+      root.statusMap.get("b")!.value = "aborted";
+
+      expect(root.canStart.get("c")!.value).toBe(true);
+
+      root.dispose();
+    });
+  });
+
+  describe("dispose clears canStart", () => {
+    it("canStart map is cleared on dispose", () => {
+      const graph = makeParallelGroupGraph();
+      const parallelGroups: ParallelGroupConfig = {
+        group1: {
+          siblings: ["a", "b", "c", "d"],
+          maxConcurrency: 2,
+        },
+      };
+      const root = new WorkflowReactiveRoot(graph, { parallelGroups });
+
+      expect(root.canStart.size).toBe(5);
+
+      root.dispose();
+
+      expect(root.canStart.size).toBe(0);
+    });
+  });
+
+  describe("full execution flow with maxConcurrency", () => {
+    it("simulates parallel execution with maxConcurrency: 2 — only 2 run at a time", () => {
+      const graph = makeParallelGroupGraph();
+      const parallelGroups: ParallelGroupConfig = {
+        group1: {
+          siblings: ["a", "b", "c", "d"],
+          maxConcurrency: 2,
+        },
+      };
+      const root = new WorkflowReactiveRoot(graph, { parallelGroups });
+
+      root.setRequestId("entry", "req-entry");
+      root.setRequestId("a", "req-a");
+      root.setRequestId("b", "req-b");
+      root.setRequestId("c", "req-c");
+      root.setRequestId("d", "req-d");
+
+      root.statusMap.get("entry")!.value = "completed";
+
+      expect(root.statusMap.get("a")!.value).toBe("ready");
+      expect(root.statusMap.get("b")!.value).toBe("ready");
+      expect(root.statusMap.get("c")!.value).toBe("idle");
+      expect(root.statusMap.get("d")!.value).toBe("idle");
+
+      root.statusMap.get("a")!.value = "running";
+      root.statusMap.get("b")!.value = "running";
+
+      expect(root.statusMap.get("c")!.value).toBe("idle");
+      expect(root.statusMap.get("d")!.value).toBe("idle");
+
+      root.statusMap.get("a")!.value = "completed";
+
+      expect(root.statusMap.get("c")!.value).toBe("ready");
+      expect(root.statusMap.get("d")!.value).toBe("idle");
+
+      root.statusMap.get("c")!.value = "running";
+
+      root.statusMap.get("b")!.value = "completed";
+
+      expect(root.statusMap.get("d")!.value).toBe("ready");
+
+      root.statusMap.get("d")!.value = "running";
+      root.statusMap.get("c")!.value = "completed";
+      root.statusMap.get("d")!.value = "completed";
+
+      expect(root.isComplete()).toBe(true);
+
+      root.dispose();
+    });
+  });
+});
--- a/test/reactive/workflow.test.ts
+++ b/test/reactive/workflow.test.ts
@@ -528,6 +528,219 @@ describe("WorkflowReactiveRoot", () => {
    });
  });

+  describe("retry semantics", () => {
+    it("nodeKeyToRequestId overwrites previous requestId — projection tracks latest attempt", () => {
+      const graph = makeSimpleGraph();
+      const root = new WorkflowReactiveRoot(graph);
+
+      root.setRequestId("a", "req-1");
+      expect(root.nodeKeyToRequestId.get("a")).toBe("req-1");
+
+      root.setRequestId("a", "req-2");
+      expect(root.nodeKeyToRequestId.get("a")).toBe("req-2");
+      expect(root.requestIdToNodeKey.get("req-2")).toBe("a");
+
+      root.dispose();
+    });
+
+    it("retry sequence: error then requested then responded → status is completed", () => {
+      const graph = makeSimpleGraph();
+      const root = new WorkflowReactiveRoot(graph);
+
+      root.setRequestId("a", "req-1");
+      root.append({
+        type: "call.requested",
+        requestId: "req-1",
+        operationId: "a",
+        input: null,
+        timestamp: "2026-01-01T00:00:00Z",
+      });
+      root.append({
+        type: "call.error",
+        requestId: "req-1",
+        error: { code: "ERR", message: "failed" },
+        timestamp: "2026-01-01T00:00:01Z",
+      });
+      expect(root.getStatus("a")).toBe("failed");
+
+      root.setRequestId("a", "req-2");
+      root.append({
+        type: "call.requested",
+        requestId: "req-2",
+        operationId: "a",
+        input: null,
+        timestamp: "2026-01-01T00:00:02Z",
+      });
+      expect(root.getStatus("a")).toBe("running");
+
+      root.append({
+        type: "call.responded",
+        requestId: "req-2",
+        output: "ok",
+        timestamp: "2026-01-01T00:00:03Z",
+      });
+      expect(root.getStatus("a")).toBe("completed");
+
+      root.dispose();
+    });
+
+    it("getResult reflects latest attempt after retry", () => {
+      const graph = makeSimpleGraph();
+      const root = new WorkflowReactiveRoot(graph);
+
+      root.setRequestId("a", "req-1");
+      root.append({
+        type: "call.requested",
+        requestId: "req-1",
+        operationId: "a",
+        input: null,
+        timestamp: "2026-01-01T00:00:00Z",
+      });
+      root.append({
+        type: "call.error",
+        requestId: "req-1",
+        error: { code: "ERR", message: "failed" },
+        timestamp: "2026-01-01T00:00:01Z",
+      });
+
+      root.setRequestId("a", "req-2");
+      root.append({
+        type: "call.requested",
+        requestId: "req-2",
+        operationId: "a",
+        input: null,
+        timestamp: "2026-01-01T00:00:02Z",
+      });
+      root.append({
+        type: "call.responded",
+        requestId: "req-2",
+        output: { retry: true },
+        timestamp: "2026-01-01T00:00:03Z",
+      });
+
+      const result = root.getResult("a");
+      expect(result).toBeDefined();
+      expect(result!.status).toBe("completed");
+      expect(result!.output).toEqual({ retry: true });
+
+      root.dispose();
+    });
+
+    it("event log preserves full history across retries", () => {
+      const graph = makeSimpleGraph();
+      const root = new WorkflowReactiveRoot(graph);
+
+      root.setRequestId("a", "req-1");
+      root.append({
+        type: "call.requested",
+        requestId: "req-1",
+        operationId: "a",
+        input: null,
+        timestamp: "2026-01-01T00:00:00Z",
+      });
+      root.append({
+        type: "call.error",
+        requestId: "req-1",
+        error: { code: "ERR", message: "failed" },
+        timestamp: "2026-01-01T00:00:01Z",
+      });
+
+      root.setRequestId("a", "req-2");
+      root.append({
+        type: "call.requested",
+        requestId: "req-2",
+        operationId: "a",
+        input: null,
+        timestamp: "2026-01-01T00:00:02Z",
+      });
+      root.append({
+        type: "call.responded",
+        requestId: "req-2",
+        output: "ok",
+        timestamp: "2026-01-01T00:00:03Z",
+      });
+
+      const events = root.getEvents("a");
+      expect(events.length).toBe(4);
+      expect(events[0]!.type).toBe("call.requested");
+      expect(events[0]!.requestId).toBe("req-1");
+      expect(events[1]!.type).toBe("call.error");
+      expect(events[1]!.requestId).toBe("req-1");
+      expect(events[2]!.type).toBe("call.requested");
+      expect(events[2]!.requestId).toBe("req-2");
+      expect(events[3]!.type).toBe("call.responded");
+      expect(events[3]!.requestId).toBe("req-2");
+
+      root.dispose();
+    });
+
+    it("retry clears failed status so downstream preconditions can be met", () => {
+      const graph = makeSimpleGraph();
+      const root = new WorkflowReactiveRoot(graph);
+
+      root.setRequestId("a", "req-1");
+      root.setRequestId("b", "req-b");
+      root.append({
+        type: "call.requested",
+        requestId: "req-1",
+        operationId: "a",
+        input: null,
+        timestamp: "2026-01-01T00:00:00Z",
+      });
+      root.append({
+        type: "call.error",
+        requestId: "req-1",
+        error: { code: "ERR", message: "failed" },
+        timestamp: "2026-01-01T00:00:01Z",
+      });
+      expect(root.blockedByFailure.get("b")!.value).toBe(true);
+
+      root.setRequestId("a", "req-2");
+      root.append({
+        type: "call.requested",
+        requestId: "req-2",
+        operationId: "a",
+        input: null,
+        timestamp: "2026-01-01T00:00:02Z",
+      });
+      root.append({
+        type: "call.responded",
+        requestId: "req-2",
+        output: "ok",
+        timestamp: "2026-01-01T00:00:03Z",
+      });
+      expect(root.getStatus("a")).toBe("completed");
+      expect(root.blockedByFailure.get("b")!.value).toBe(false);
+
+      root.dispose();
+    });
+
+    it("requestIdToNodeKey preserves all requestIds including previous attempts", () => {
+      const graph = makeSimpleGraph();
+      const root = new WorkflowReactiveRoot(graph);
+
+      root.setRequestId("a", "req-1");
+      root.setRequestId("a", "req-2");
+
+      expect(root.requestIdToNodeKey.get("req-1")).toBe("a");
+      expect(root.requestIdToNodeKey.get("req-2")).toBe("a");
+
+      root.dispose();
+    });
+
+    it("dispose clears requestIdToNodeKey", () => {
+      const graph = makeSimpleGraph();
+      const root = new WorkflowReactiveRoot(graph);
+
+      root.setRequestId("a", "req-1");
+      root.setRequestId("a", "req-2");
+      expect(root.requestIdToNodeKey.size).toBe(2);
+
+      root.dispose();
+      expect(root.requestIdToNodeKey.size).toBe(0);
+    });
+  });
+
  describe("abort cascade", () => {
    it("failed node causes downstream dependents to abort (continue-running default)", () => {
      const graph = makeSimpleGraph();
Author	SHA1	Message	Date
glm-5.1	058b437c3f	fix: add ./ prefix to subpath export keys in package.json	2026-05-22 06:26:56 +00:00
glm-5.1	6fb633c05b	chore: add LICENSE, README, update package.json and AGENTS.md for npm release prep	2026-05-22 06:17:54 +00:00
glm-5.1	e45b8c0cc0	chore: mark final review/complete-library task completed — all 38/38 tasks done	2026-05-21 22:56:22 +00:00
glm-5.1	fab0b64f0b	chore: update api/public-exports task status to completed	2026-05-21 22:55:56 +00:00
glm-5.1	dd96ceb4f8	feat: wire all barrel exports, resolve conflicts, add 8 sub-path import tests	2026-05-21 22:55:37 +00:00
glm-5.1	4fcd544261	chore: update review/reactive-and-hosts task status to completed	2026-05-21 22:40:57 +00:00
glm-5.1	1233266ffd	chore: update meta-reactive-layer task status to completed	2026-05-21 22:31:22 +00:00
glm-5.1	b297203a5d	chore: update max-concurrency task status, spawn next generation	2026-05-21 22:29:25 +00:00
glm-5.1	4df8698a3d	Merge branch 'feat/reactive/max-concurrency'	2026-05-21 22:29:05 +00:00
glm-5.1	1a12410229	feat: implement maxConcurrency reactive counting semaphore with 20 unit tests	2026-05-21 22:29:02 +00:00
glm-5.1	72356b9758	chore: update host-reactive task status to completed	2026-05-21 22:21:00 +00:00
glm-5.1	793b6e513f	Merge branch 'feat/host/reactive'	2026-05-21 22:20:33 +00:00
glm-5.1	8b7f4f985a	feat: implement ReactiveHostConfig with WorkflowNode, ReactiveContext, precondition computation and 34 integration tests	2026-05-21 22:20:30 +00:00
glm-5.1	a72c3173e7	chore: update review-foundation task status	2026-05-21 22:18:37 +00:00
glm-5.1	ee3da90b63	chore: update task statuses completed	2026-05-21 22:18:03 +00:00
glm-5.1	270bd7cd69	chore: merge reactive-node-status, update retry-semantics task status	2026-05-21 22:17:41 +00:00
glm-5.1	e8b62c0c58	Merge branch 'feat/reactive-node-status'	2026-05-21 22:17:29 +00:00
glm-5.1	000a1e04c5	feat: add retry semantics tests with requestIdToNodeKey reverse map	2026-05-21 22:17:11 +00:00
glm-5.1	4cf644f734	Merge branch 'feat/reactive-retry-semantics'	2026-05-21 22:13:33 +00:00
glm-5.1	d63a301cea	Implement retry semantics: requestIdToNodeKey reverse map, setRequestId method, full-history getEvents	2026-05-21 22:10:31 +00:00