#98 - TDD: Pure-graph parallel dispatch runs all next-nodes concurrently whenever len > 1, ignoring each node's `parallel` flag - cleveractors-core

CoreRasurae commented

2026-08-03 21:50:52 +00:00

Member

Metadata

Commit Message: test(langgraph): capture parallel dispatch node-flag regression (#97)
Branch: tdd/m1-pure-graph-parallel-node-gate

Background and context

Companion TDD issue-capture test for bug #97: the three concurrent-dispatch
sites in PureLangGraph (src/cleveractors/langgraph/pure_graph.py, lines
1078, 1860, 1965) fire every candidate next-node concurrently via
asyncio.gather/asyncio.create_task whenever parallel_execution: true
(the default) and there are 2+ candidates, without checking each node's own
parallel flag (NodeConfig.parallel / can_execute_parallel()). This
violates §6.7 and §12.3 of the Actor Configuration Standard.

This issue delivers a failing-first Behave regression test that proves
the bug exists. The actual fix is delivered by issue #97 on a bugfix/
branch.

Current behavior

No test asserts that non-parallel-marked next-nodes execute strictly
sequentially. The defect can regress undetected.

Expected behavior

A Behave scenario exists that:

Builds a pure-graph route where a single node has two outgoing
unconditional edges to two agent/tool nodes, neither of which declares
parallel: true, with parallel_execution: true at the graph level.
Drives both target nodes to record an observable start/end order (e.g. via
shared state appended to a list).
Asserts the second node's execution starts only after the first node's
execution completes (i.e., no overlap), proving sequential execution.
Fails (via AssertionError) while the bug is present (both start
concurrently), and passes once the fix lands.

Acceptance criteria

A Behave scenario reproduces the bug: with two non-parallel-marked
sibling next-nodes and parallel_execution: true, the assertion that
execution is sequential fails while the bug is present.
The scenario carries all three tags: @tdd_issue, @tdd_issue_97,
@tdd_expected_fail.
The "bug still present" signal uses AssertionError only
(assert ... / raise AssertionError(...)) — never ValueError,
RuntimeError, OSError, or any other exception type.
With @tdd_expected_fail present, nox -s unit_tests is green (the
hook inverts the failing assertion).
The TDD branch is named tdd/m1-pure-graph-parallel-node-gate (same
suffix as the companion bugfix/ branch).

Supporting information

Bug captured: issue #97.
Spec: docs/index.md §6.7, §12.3.
TDD tag/assertion rules per the cleveractors-contributing workflow: the
TDD hook only inverts AssertionError; the three tags are mandatory; only
@tdd_expected_fail is removed by the bug-fix developer, @tdd_issue and
@tdd_issue_97 remain forever as regression guards.

Subtasks

Add a Behave feature scenario under features/ reproducing the
concurrent-dispatch-without-per-node-flag defect, tagged
@tdd_issue @tdd_issue_97 @tdd_expected_fail.
Implement the step definitions (fully — no placeholder steps),
signalling "bug still present" only via AssertionError.
Confirm the assertion actually fails when run without
@tdd_expected_fail, and that nox -s unit_tests is green with the
tag present.
Verify coverage >= 97% via nox -s coverage_report.
Run nox (all default sessions), fix any errors.

Definition of Done

This issue is complete when:

All subtasks above are completed and checked off.
A Git commit is created where the first line matches the Commit Message in
Metadata exactly.
The commit is pushed to the branch matching the Branch in Metadata exactly.
The TDD PR is submitted to master, reviewed (test quality, correct
tagging, AssertionError usage), and merged.

## Metadata - **Commit Message:** `test(langgraph): capture parallel dispatch node-flag regression (#97)` - **Branch:** `tdd/m1-pure-graph-parallel-node-gate` ## Background and context Companion TDD issue-capture test for bug #97: the three concurrent-dispatch sites in `PureLangGraph` (`src/cleveractors/langgraph/pure_graph.py`, lines 1078, 1860, 1965) fire every candidate next-node concurrently via `asyncio.gather`/`asyncio.create_task` whenever `parallel_execution: true` (the default) and there are 2+ candidates, without checking each node's own `parallel` flag (`NodeConfig.parallel` / `can_execute_parallel()`). This violates §6.7 and §12.3 of the Actor Configuration Standard. This issue delivers a **failing-first** Behave regression test that proves the bug exists. The actual fix is delivered by issue #97 on a `bugfix/` branch. ## Current behavior No test asserts that non-`parallel`-marked next-nodes execute strictly sequentially. The defect can regress undetected. ## Expected behavior A Behave scenario exists that: - Builds a pure-graph route where a single node has two outgoing unconditional edges to two agent/tool nodes, neither of which declares `parallel: true`, with `parallel_execution: true` at the graph level. - Drives both target nodes to record an observable start/end order (e.g. via shared state appended to a list). - Asserts the second node's execution starts only after the first node's execution completes (i.e., no overlap), proving sequential execution. - Fails (via `AssertionError`) while the bug is present (both start concurrently), and passes once the fix lands. ## Acceptance criteria - [ ] A Behave scenario reproduces the bug: with two non-`parallel`-marked sibling next-nodes and `parallel_execution: true`, the assertion that execution is sequential fails while the bug is present. - [ ] The scenario carries all three tags: `@tdd_issue`, `@tdd_issue_97`, `@tdd_expected_fail`. - [ ] The "bug still present" signal uses `AssertionError` only (`assert ...` / `raise AssertionError(...)`) — never `ValueError`, `RuntimeError`, `OSError`, or any other exception type. - [ ] With `@tdd_expected_fail` present, `nox -s unit_tests` is green (the hook inverts the failing assertion). - [ ] The TDD branch is named `tdd/m1-pure-graph-parallel-node-gate` (same suffix as the companion `bugfix/` branch). ## Supporting information - Bug captured: issue #97. - Spec: `docs/index.md` §6.7, §12.3. - TDD tag/assertion rules per the `cleveractors-contributing` workflow: the TDD hook only inverts `AssertionError`; the three tags are mandatory; only `@tdd_expected_fail` is removed by the bug-fix developer, `@tdd_issue` and `@tdd_issue_97` remain forever as regression guards. ## Subtasks - [ ] Add a Behave feature scenario under `features/` reproducing the concurrent-dispatch-without-per-node-flag defect, tagged `@tdd_issue @tdd_issue_97 @tdd_expected_fail`. - [ ] Implement the step definitions (fully — no placeholder steps), signalling "bug still present" only via `AssertionError`. - [ ] Confirm the assertion actually fails when run without `@tdd_expected_fail`, and that `nox -s unit_tests` is green with the tag present. - [ ] Verify coverage >= 97% via `nox -s coverage_report`. - [ ] Run `nox` (all default sessions), fix any errors. ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - A Git commit is created where the first line matches the Commit Message in Metadata exactly. - The commit is pushed to the branch matching the Branch in Metadata exactly. - The TDD PR is submitted to `master`, reviewed (test quality, correct tagging, `AssertionError` usage), and merged.