feat(core): parallel branch yields with consensus-aware merge (#60)

- Introduce yields(String...) on parallel branches for structured domain output via the inject→execute→extract pipeline.
- Rewrite ConsensusEvaluator to use structured BranchResult data, fixing bugs in heuristic-based vote extraction.
- Extract AgentLifecycleRunner to unify agent execution across StandardNodeExecutor and ParallelNodeExecutor, restoring missing listener events on branches.

Resolve: #59

Signed-off-by: Aleksandr Suvorov <asuvorov@hensu.io>

Author: alxsuv

AGENTS.md

@@ -100,6 +100,9 @@ hensu-langchain4j-adapter     # LangChain4j integration (Claude, GPT, Gemini, De
 - `WorkflowStateRepository` - Tenant-scoped storage for execution state snapshots (defaults to in-memory; JDBC impl in server)
 - `ExecutionListener` - Lifecycle callbacks including `onCheckpoint(HensuState)` for inter-node persistence
 - `ProcessorPipeline` - Orchestrates pre/post node execution processor chains
+- `EngineVariables` - SSOT for engine-managed variable names (`score`, `approved`, `recommendation`)
+- `AgentLifecycleRunner` - Stateless agent call lifecycle (resolve → enrich → lookup → listener → execute → convert); shared by `StandardNodeExecutor` and `ParallelNodeExecutor`
+- `SynchronizedListenerDecorator` - Thread-safe `ExecutionListener` wrapper for parallel branch execution
 
 **Execution Lifecycle**: The `WorkflowExecutor` processes each node through a strict PRE-EXECUTE-POST pipeline.
 Pre-execution processors run in order: checkpoint → node start. Post-execution processors run in order: output
@@ -142,7 +145,7 @@ Workflow
 
 - `StandardNode` - Regular step with agent execution, typed state variable output (`writes`), and transitions
 - `LoopNode` - Iterative execution with break conditions
-- `ParallelNode` - Concurrent execution with consensus
+- `ParallelNode` - Concurrent execution with consensus; branches declare domain output via `yields()`
 - `ForkNode` - Spawn parallel execution paths
 - `JoinNode` - Await and merge forked paths
 - `GenericNode` - Custom execution logic via registered handlers
@@ -154,7 +157,7 @@ Workflow
 
 - `SuccessTransition` / `FailureTransition` - Based on execution result
 - `ScoreTransition` - Conditional on rubric score (e.g., score >= 80 → approve)
-- `ApprovalTransition` - Routes on the `approved` boolean engine variable (written via `writes("approved")`); falls through if absent or non-boolean
+- `ApprovalTransition` - Routes on the `approved` boolean engine variable (injected by `ApprovalVariableInjector`); falls through if absent or non-boolean
 - `AlwaysTransition` - Unconditional
 
 ### State Schema
@@ -374,6 +377,11 @@ CRUD operations, UPSERT semantics, FK constraints, tenant isolation, and seriali
 - `hensu-core/.../workflow/state/WorkflowStateSchema.java` - Typed state variable schema (optional per-workflow declaration)
 - `hensu-core/.../workflow/state/StateVariableDeclaration.java` - Single variable declaration (name, type, isInput)
 - `hensu-core/.../workflow/state/VarType.java` - Variable type enum (STRING, NUMBER, BOOLEAN, LIST_STRING)
+- `hensu-core/.../execution/EngineVariables.java` - SSOT for engine-managed variable names (score, approved, recommendation)
+- `hensu-core/.../execution/SynchronizedListenerDecorator.java` - Thread-safe listener wrapper for parallel branches
+- `hensu-core/.../execution/executor/AgentLifecycleRunner.java` - Shared agent call lifecycle (resolve → enrich → execute)
+- `hensu-core/.../execution/parallel/BranchExecutionConfig.java` - Per-branch config carried on ExecutionContext
+- `hensu-core/.../execution/enricher/YieldsVariableInjector.java` - Injects yield format instructions for branch prompts
 - `hensu-core/.../workflow/transition/ApprovalTransition.java` - Boolean approval routing via `approved` engine variable
 - `hensu-core/.../workflow/validation/WorkflowValidator.java` - Load-time validator for `writes` and prompt variable references
 

docs/developer-guide-core.md

@@ -11,6 +11,7 @@ This guide covers API usage, adapter development, extension points, and testing
 - [Execution Pipeline](#execution-pipeline)
   - [Pre-Execution Pipeline](#pre-execution-pipeline)
   - [Post-Execution Pipeline](#post-execution-pipeline)
+  - [Parallel Branch Concurrency](#parallel-branch-concurrency)
   - [Agentic Output Validation](#agentic-output-validation)
 - [Creating Custom Adapters](#creating-custom-adapters)
 - [Generic Nodes](#generic-nodes)
@@ -194,6 +195,29 @@ step, enabling self-correcting loops.
 rule that returns a valid target node ID wins, and the state is updated to point to that next node. Throws
 `IllegalStateException` if no rule matches, preventing the workflow from silently getting stuck.
 
+### Parallel Branch Concurrency
+
+`ParallelNodeExecutor` runs each branch on a virtual thread with two concurrency guarantees:
+
+**1. ScopedValue isolation** – each branch receives an isolated context snapshot bound via
+`ScopedValue.where(BRANCH_CONTEXT, snapshot)`. Branch mutations never leak into sibling branches
+or the parent state. This is the same mechanism used for tenant isolation (`TenantContext`).
+
+> **Extension rule:** Never use `ThreadLocal` in branch-aware code. `ScopedValue` is the only
+> safe context propagation mechanism for virtual threads. See `10-java-standards.md` for details.
+
+**2. SynchronizedListenerDecorator** – the parent `ExecutionListener` is wrapped in a
+`SynchronizedListenerDecorator` before branch submission. Every callback is `synchronized` so that
+multi-line output (e.g., box-drawing in verbose CLI, SSE event frames) completes atomically without
+interleaving across concurrent branches.
+
+Custom `ExecutionListener` implementations do **not** need their own synchronization when used with
+parallel nodes – the decorator handles it. Only the parallel execution path pays the synchronization
+cost; sequential nodes use the raw listener.
+
+> **JEP 491 (Java 24+):** Virtual thread pinning on `synchronized` blocks was eliminated. Monitor
+> contention on I/O-bound listener callbacks is negligible for typical branch counts (3–10).
+
 ### Agentic Output Validation
 
 LLM-generated outputs are non-deterministic and treated as **untrusted data**. Unlike REST input (short, user-typed,
@@ -711,28 +735,41 @@ Validation is a no-op when no schema is declared. Legacy workflows always pass t
 
 ## Engine Variable Injection
 
-Before each agent call, `StandardNodeExecutor` runs `EngineVariablePromptEnricher` to append
+Before each agent call, `AgentLifecycleRunner` runs `EngineVariablePromptEnricher` to append
 format requirements to the resolved prompt. The enricher is a dumb iterator over an ordered chain
 of `EngineVariableInjector`s — each one self-contained, deciding independently whether it applies.
 
+Engine variable names (`score`, `approved`, `recommendation`) are defined in the `EngineVariables`
+class — the single source of truth for all engine-managed variable keys.
+
 ### Injection Pipeline
 
+Each injector fires when **either** of two conditions is met:
+1. The node has a matching transition rule (e.g., `ScoreTransition` for `ScoreVariableInjector`)
+2. The execution context carries a `BranchExecutionConfig` where `needsSelfScoring()` returns true
+   (consensus branch with a non-JUDGE_DECIDES strategy)
+
 ```mermaid
 flowchart LR
-    r(["RubricPromptInjector"]) -->|"rubricId != null"| s(["ScoreVariableInjector"])
-    s -->|"has ScoreTransition"| a(["ApprovalVariableInjector"])
-    a -->|"has ApprovalTransition"| rec(["RecommendationVariable\nInjector"])
-    rec -->|"has Score/Approval\nTransition"| w(["WritesVariableInjector"])
+    r(["RubricPromptInjector\n· rubricId != null"]) --> s(["ScoreVariableInjector\n· ScoreTransition or\nconsensus branch"])
+    s --> a(["ApprovalVariableInjector\n· ApprovalTransition or\nconsensus branch"])
+    a --> rec(["RecommendationVariable\nInjector\n· Score/Approval or\nconsensus branch"])
+    rec --> w(["WritesVariableInjector\n· has writes()"])
+    w --> y(["YieldsVariableInjector\n· has yields()"])
 
     style r fill:#2c2c2e, stroke:#48484a, color:#ebebf5, stroke-width:1px
     style s fill:#2c2c2e, stroke:#48484a, color:#ebebf5, stroke-width:1px
     style a fill:#2c2c2e, stroke:#48484a, color:#ebebf5, stroke-width:1px
     style rec fill:#2c2c2e, stroke:#48484a, color:#ebebf5, stroke-width:1px
     style w fill:#2c2c2e, stroke:#48484a, color:#ebebf5, stroke-width:1px
+    style y fill:#2c2c2e, stroke:#48484a, color:#ebebf5, stroke-width:1px
 
     linkStyle default stroke:#0A84FF, stroke-width:1px
 ```
 
+Each injector runs unconditionally in order. The condition listed under each name is when that
+injector **appends** its instruction – otherwise it passes the prompt through unchanged.
+
 ### Description Hints in WritesVariableInjector
 
 When a variable is declared with a description in the state schema, `WritesVariableInjector` includes it in the appended instruction:
@@ -757,6 +794,7 @@ EngineVariablePromptEnricher enricher = new EngineVariablePromptEnricher(
         new ApprovalVariableInjector(),
         new RecommendationVariableInjector(),
         new WritesVariableInjector(),
+        new YieldsVariableInjector(),
         new MyCustomInjector()   // appended after built-ins
     ));
 ```
@@ -1268,7 +1306,11 @@ Environment variables matching `*_API_KEY`, `*_KEY`, `*_SECRET`, or `*_TOKEN` pa
 | `plan/Planner.java`                                     | Planner interface (`createPlan` / `revisePlan`)                                                  |
 | `plan/StaticPlanner.java`                               | Resolves predefined `plan { }` steps from `PlanningConfig`                                       |
 | `plan/LlmPlanner.java`                                  | LLM-based plan generation and revision (`DYNAMIC` mode)                                          |
+| `execution/EngineVariables.java`                        | SSOT for engine variable names (`score`, `approved`, `recommendation`)                           |
+| `execution/SynchronizedListenerDecorator.java`          | Thread-safe listener wrapper for parallel branch execution                                       |
+| `execution/executor/AgentLifecycleRunner.java`          | Composition-based agent call: prompt enrichment → agent execution → output extraction            |
 | `execution/executor/AgenticNodeExecutor.java`           | Drives preparation + execution `PlanPipeline`s for `StandardNode`                                |
+| `execution/parallel/BranchExecutionConfig.java`         | Typed branch metadata on `ExecutionContext` (consensus strategy, yields list)                    |
 | `template/SimpleTemplateResolver.java`                  | `{variable}` substitution                                                                        |
 | `review/ReviewHandler.java`                             | Human review interface                                                                           |
 | `execution/pipeline/ProcessorPipeline.java`             | Orchestrates pre/post processor chains                                                           |

docs/developer-guide-serialization.md

@@ -236,13 +236,36 @@ Java records have no inner `Builder` class — Jackson deserializes them via the
 
 ### Current registrations
 
+**Snapshot hierarchy** (embedded in `ExecutionStep`):
+
 | Class                              | Embedded in                      | Reason                                      |
 |------------------------------------|----------------------------------|---------------------------------------------|
 | `HensuSnapshot`                    | `ExecutionStep.Builder.snapshot` | Canonical constructor + component accessors |
 | `PlanSnapshot`                     | `HensuSnapshot.planSnapshot`     | Nested record inside `HensuSnapshot`        |
 | `PlanSnapshot.PlannedStepSnapshot` | `PlanSnapshot.steps()`           | Nested record inside `PlanSnapshot`         |
 | `PlanSnapshot.StepResultSnapshot`  | `PlanSnapshot.results()`         | Nested record inside `PlanSnapshot`         |
 
+**Parallel execution types** (manually deserialized in `NodeDeserializer`, but serialized via default Jackson `BeanSerializer` in `WorkflowSerializer.toJson()`):
+
+| Class                       | Embedded in / Context                           | Reason                                                      |
+|-----------------------------|-------------------------------------------------|-------------------------------------------------------------|
+| `Branch`                    | `ParallelNode` branch list                      | Record with `yields` (`List<String>`) component             |
+| `ConsensusConfig`           | `ParallelNode` consensus configuration          | Record with strategy enum + nullable threshold              |
+| `ConsensusStrategy`         | `ConsensusConfig.strategy()`                    | Enum – Jackson needs reflection to serialize enum constants |
+| `ConsensusResult`           | State context map (checkpoint serialization)    | Stored under `consensus_votes` key during execution         |
+| `ConsensusResult.Vote`      | `ConsensusResult.votes()` map values            | Inner record with vote type, score, weight                  |
+| `ConsensusResult.VoteType`  | `ConsensusResult.Vote.voteType()`               | Enum (APPROVE / REJECT)                                     |
+| `ScoreCondition`            | `ScoreTransition` condition list                | Nested record inside transition rules                       |
+| `DoubleRange`               | `ScoreCondition.range()`                        | Nested record inside `ScoreCondition`                       |
+
+> **Why not `treeToValue`?** These types are simple records with primitive/string/enum fields.
+> Manual `JsonNode` extraction in `NodeDeserializer` avoids reflection during deserialization.
+> Registration is needed only for the **serialization** path (`WorkflowSerializer.toJson()`),
+> where Jackson's default `BeanSerializer` reads component accessors reflectively.
+
+> **`Branch.yields`** is a `List<String>`. `NodeDeserializer` extracts it by iterating the JSON
+> array node manually — no `treeToValue` or `convertValue` needed for `List<String>`.
+
 Unlike the `treeToValue` pattern, these records do **not** need a custom deserializer or mixin. Registration alone is sufficient because Jackson's built-in record support handles the canonical constructor mapping.
 
 ### Checklist before adding a new record type

docs/developer-guide-server.md

@@ -1268,15 +1268,19 @@ Registrations are split across four dedicated classes to keep each concern isola
 
 #### NativeImageConfig — Hensu domain model
 
-**Three patterns require registration here:**
+**Five patterns require registration here** (matching `NativeImageConfig` javadoc §1–§5):
 
 1. **`@JsonPOJOBuilder` mixin targets** — Jackson instantiates the builder via its private no-arg constructor, calls each setter, then calls `build()`. GraalVM cannot trace these calls through the generic mixin machinery.
 
 2. **`treeToValue` delegation** — When a custom deserializer calls `mapper.treeToValue(node, SomeClass.class)`, Jackson uses POJO reflection for `SomeClass`. Simple records (primitives, strings, enums only) should be **fixed** by switching to manual `JsonNode` extraction instead. Register only types where manual extraction is impractical (e.g., nested `Duration` fields).
 
-3. **Record types embedded in builder classes** — When a `record` is a field inside a mixin-registered builder type, Jackson reaches it via its canonical constructor and component accessors. GraalVM cannot trace those calls statically. Register the record and every nested record transitively. No mixin or custom deserializer is needed — registration alone is sufficient.
+3. **Manual deser, default Jackson ser** — Types deserialized manually in `NodeDeserializer` (direct `JsonNode` extraction) but serialized via Jackson's default `BeanSerializer` in `WorkflowSerializer.toJson()`. The deserialization path needs no reflection, but the serialization path reads record component accessors reflectively. Current types: `Branch`, `ConsensusConfig`, `ConsensusStrategy`, `ConsensusResult`, `ConsensusResult.Vote`, `ConsensusResult.VoteType`, `ScoreCondition`, `DoubleRange`.
 
-**When to add vs. fix:** if the class is a simple record with no `Duration`/nested-complex fields, fix the deserializer. If it contains `Duration` or deeply nested types, add it here. For records embedded in builder types, always register them. See [hensu-serialization Developer Guide](developer-guide-serialization.md#the-treetovalue-rule) for the full rule.
+4. **Simple immutable types with custom deser but default ser** — `WorkflowStateSchema` and `StateVariableDeclaration` use a custom deserializer (`WorkflowStateSchemaDeserializer`) that extracts fields manually. However, Jackson's default serializer reads `getVariables()` reflectively, so both classes must be registered.
+
+5. **Record types embedded in builder classes** — When a `record` is a field inside a mixin-registered builder type, Jackson reaches it via its canonical constructor and component accessors. GraalVM cannot trace those calls statically. Register the record and every nested record transitively. No mixin or custom deserializer is needed — registration alone is sufficient. Current types: `ReviewConfig`, `HensuSnapshot`, `PlanSnapshot` hierarchy.
+
+**When to add vs. fix:** if the class is a simple record with no `Duration`/nested-complex fields, fix the deserializer. If it contains `Duration` or deeply nested types, add it here. For records embedded in builder types, always register them. For types in pattern 3, registration is needed only because the serialization path uses default Jackson. See [hensu-serialization Developer Guide](developer-guide-serialization.md#the-treetovalue-rule) for the full rule.
 
 #### LangChain4j*NativeConfig — third-party provider DTOs