agent-workflow-sdk 0.4.0__tar.gz → 0.5.0__tar.gz

{agent_workflow_sdk-0.4.0 → agent_workflow_sdk-0.5.0}/CHANGELOG.md

@@ -4,6 +4,31 @@ All notable changes to `agent-workflow-sdk` are documented here. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the
 project aims to follow [Semantic Versioning](https://semver.org/).
 
+## [0.5.0] - 2026-10-04
+
+### Added
+
+- `by_key(policy)` reducer (`agentflow.state`, re-exported from `agentflow`):
+  a reducer for a dict channel whose fields each fold with their own reducer.
+  Where `merge` applies one last-wins policy to a whole dict, `by_key` lets a
+  single structured channel hold fields that accumulate differently — e.g. one
+  `search` channel where `intents` / `candidates` / `verified` grow via
+  `append` while `events` / `incumbent` are replaced via `last`. This is the
+  core primitive a dual-state search/optimization layer (single planner,
+  concurrent workers, a deterministic promotion boundary) builds on; the
+  fan-out, state isolation, checkpoints, Store, and quality gates it also needs
+  already exist. See the dual-state search recipe and
+  `examples/dual_state_search.py`.
+
+### Notes
+
+- `by_key` folding is one level of structure, not a recursive deep-merge: each
+  field's value is combined whole by its reducer (so `last` on a field replaces
+  the whole object, it does not patch one of its keys). Writing a field absent
+  from the policy raises `KeyError`, mirroring how the engine rejects writes to
+  undeclared top-level channels. Use it for distinct fields that accumulate
+  differently, not for concurrent partial patches of the same nested object.
+
 ## [0.4.0] - 2026-10-03
 
 ### Added

{agent_workflow_sdk-0.4.0 → agent_workflow_sdk-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agent-workflow-sdk
-Version: 0.4.0
+Version: 0.5.0
 Summary: Async-first SDK for orchestrating local coding-agent CLIs (Claude Code, Codex, Kiro) and LLMs as durable, graph-based workflows.
 Project-URL: Homepage, https://github.com/dankosorkin/agent-workflow-sdk
 Project-URL: Repository, https://github.com/dankosorkin/agent-workflow-sdk
@@ -188,7 +188,8 @@ shows the iterate-until-converged loop.
 State is a `TypedDict` subclass of `State`. Each field is a channel; annotate
 it with a reducer that folds each node's update into the current value. A
 field without a reducer uses `last` (last-value-wins). Built-in reducers:
-`last`, `append`, `add`, `merge`, `union`. A node returns a partial update; it
+`last`, `append`, `add`, `merge`, `union`, and `by_key` (a dict channel whose
+fields each fold with their own reducer). A node returns a partial update; it
 never mutates the state it was given.
 
 ### Nodes and edges

{agent_workflow_sdk-0.4.0 → agent_workflow_sdk-0.5.0}/README.md

@@ -139,7 +139,8 @@ shows the iterate-until-converged loop.
 State is a `TypedDict` subclass of `State`. Each field is a channel; annotate
 it with a reducer that folds each node's update into the current value. A
 field without a reducer uses `last` (last-value-wins). Built-in reducers:
-`last`, `append`, `add`, `merge`, `union`. A node returns a partial update; it
+`last`, `append`, `add`, `merge`, `union`, and `by_key` (a dict channel whose
+fields each fold with their own reducer). A node returns a partial update; it
 never mutates the state it was given.
 
 ### Nodes and edges

{agent_workflow_sdk-0.4.0 → agent_workflow_sdk-0.5.0}/agentflow/__init__.py

@@ -90,6 +90,7 @@ from agentflow.state import (
     State,
     add,
     append,
+    by_key,
     last,
     merge,
     union,
@@ -97,7 +98,7 @@ from agentflow.state import (
 from agentflow.store import Item, MemoryStore, Store
 from agentflow.telemetry import JsonlTelemetry, MultiHooks
 
-__version__ = "0.4.0"
+__version__ = "0.5.0"
 
 __all__ = [
     "__version__",
@@ -109,6 +110,7 @@ __all__ = [
     "append",
     "add",
     "merge",
+    "by_key",
     "union",
     # graph
     "Graph",

{agent_workflow_sdk-0.4.0 → agent_workflow_sdk-0.5.0}/agentflow/state.py

@@ -57,6 +57,7 @@ __all__ = [
     "append",
     "add",
     "merge",
+    "by_key",
     "union",
     "channels_from_schema",
     "apply_update",
@@ -129,6 +130,65 @@ def merge(current: Any, update: Any) -> dict:
     return base
 
 
+def by_key(policy: Mapping[str, Reducer]) -> Reducer:
+    """Build a reducer for a dict channel that folds each key with its own reducer.
+
+    Where :func:`merge` applies one policy (last-wins) to a whole dict, this
+    lets a single structured channel hold keys that accumulate differently —
+    for example an ``intents`` list that grows with :func:`append` beside an
+    ``events`` list that is replaced with :func:`last` and an ``incumbent`` that
+    is overwritten whole::
+
+        search = by_key({
+            "intents":   append,   # grow
+            "candidates": append,  # grow (concurrent workers each add one)
+            "verified":  append,   # grow
+            "events":    last,     # replace (planner clears what it consumed)
+            "incumbent": last,     # overwrite the current best, whole
+        })
+
+        class OptState(State):
+            search: Annotated[dict, search]
+
+    Folding rules, given ``current`` (``None`` is treated as ``{}``) and an
+    ``update`` dict:
+
+    - Only keys present in ``update`` are folded; a key absent from ``update``
+      keeps its ``current`` value untouched.
+    - Each folded key ``k`` is combined as ``policy[k](current.get(k),
+      update[k])`` — so ``{"events": []}`` genuinely clears ``events`` (that is
+      a ``last`` of an empty list, not a no-op), while ``{}`` or ``None`` is a
+      no-op returning a copy of ``current``.
+    - A key in ``update`` that is not in ``policy`` raises :class:`KeyError`.
+      Writing an undeclared field is a bug (usually a typo), mirroring how the
+      engine rejects writes to undeclared top-level channels.
+    - A key in ``current`` that is not in ``policy`` is passed through
+      unchanged; the policy only governs keys an update actually writes.
+
+    The value under each key is combined *whole* by that key's reducer; this is
+    one level of structure, not a recursive deep-merge. It is for distinct keys
+    that accumulate differently, not for concurrent partial patches of the same
+    nested object.
+    """
+    policy = dict(policy)
+
+    def _by_key(current: Any, update: Any) -> dict:
+        base = dict(current) if current is not None else {}
+        if not update:
+            return base
+        for key, value in update.items():
+            reducer = policy.get(key)
+            if reducer is None:
+                raise KeyError(
+                    f"by_key update wrote field {key!r} with no reducer in policy; "
+                    f"declared fields: {sorted(policy)}"
+                )
+            base[key] = reducer(base.get(key), value)
+        return base
+
+    return _by_key
+
+
 def union(current: Any, update: Any) -> set:
     """Set union. ``None`` current is the empty set."""
     base = set(current) if current is not None else set()

{agent_workflow_sdk-0.4.0 → agent_workflow_sdk-0.5.0}/docs/concepts/state.md

@@ -31,6 +31,35 @@ A field annotated `Annotated[type, reducer]` uses that reducer. A bare field use
 
 `append` extends when the update is a list or tuple, and appends a single element otherwise. Any pure `(current, update) -> new` is a valid reducer — the built-ins are just the common ones. A reducer must be pure and must treat a `None` current as its empty value.
 
+## Structured channels with `by_key`
+
+`merge` folds a whole dict with one policy (last-wins). When one dict channel holds fields that must accumulate differently, `by_key` gives each field its own reducer:
+
+```python
+from agentflow import State, append, by_key, last
+from typing import Annotated
+
+search = by_key({
+    "intents": append,     # grow
+    "candidates": append,  # grow (concurrent workers each add one)
+    "events": last,        # replace
+    "incumbent": last,     # overwrite the current best, whole
+})
+
+class OptState(State):
+    search: Annotated[dict, search]
+```
+
+A node writes the fields it changes, and each is folded by that field's reducer. `{"search": {"candidates": [c]}}` appends one candidate; `{"search": {"events": []}}` clears events. Fields a node does not write are left untouched, so two nodes in one super-step writing different fields never clobber each other.
+
+Three rules worth stating plainly:
+
+- A field in the update that is not in the policy raises `KeyError`. Writing an undeclared field is a bug, just like writing an undeclared top-level channel.
+- Each field's value is folded whole by its reducer. This is one level of structure, not a recursive deep-merge: `last` on `incumbent` replaces the whole object, it does not patch one of its keys.
+- Use `by_key` for distinct fields that accumulate differently, not for concurrent partial patches of the same nested object.
+
+This is the channel behind a search or optimization loop, where a planner appends intents, concurrent workers append candidates, and a verifier replaces events and overwrites the incumbent whole. See the [dual-state search recipe](../patterns/long-running-loops.md#recipe-dual-state-search-with-a-planner-and-a-promotion-boundary) and `examples/dual_state_search.py`.
+
 ## Nodes return deltas, not absolutes
 
 A node returns a partial update — a dict of channel names to values — and the engine folds each value through that channel's reducer:

{agent_workflow_sdk-0.4.0 → agent_workflow_sdk-0.5.0}/docs/patterns/long-running-loops.md

@@ -64,6 +64,28 @@ flowchart TD
 
 Two things matter here. First, reducers do the merging: give the aggregate channel an `append` or `merge` reducer so the parallel updates fold together deterministically instead of racing. Second, a super-step is all-or-nothing — if any branch raises, the whole step is discarded and no checkpoint is written, so a resume never sees a half-merged aggregate. Bound the fan-out with `compile(max_node_concurrency=...)` if the branches hit a shared resource.
 
+## Recipe: dual-state search with a planner and a promotion boundary
+
+A search or optimization loop separates proposing from judging. One structured channel holds the whole search, and a single `planner` is the only writer of the proposals. Several workers run concurrently, each producing one candidate. A single deterministic `verifier` is the promotion boundary: it checks candidates, overwrites the current best whole, and emits events the router reacts to.
+
+```mermaid
+flowchart LR
+    START --> planner --> dispatch{runnable?}
+    dispatch -- fan out --> workers
+    workers --> verifier
+    verifier -- improved --> planner
+    verifier -- done --> END
+```
+
+The reason this needs [`by_key`](../concepts/state.md#structured-channels-with-by_key): the one `search` channel holds fields that fold differently — `intents` and `candidates` and `verified` grow with `append`, `events` is replaced with `last`, `incumbent` is overwritten whole with `last`. A single `merge` cannot express that; `by_key` gives each field its own reducer, so concurrent workers appending candidates never clobber the planner's intents.
+
+Two subtleties this recipe makes you confront, both consequences of reducers, not bugs:
+
+- An `append` channel does not clear when you write `[]` to it — `append(current, [])` adds nothing. To drain one, have the consumer work off what it has not yet handled (key by id) rather than relying on a clear.
+- `intents` accumulates across rounds, so dispatch must compute a *runnable* subset (proposed minus already verified) instead of fanning out the raw list. This is the frontier idea: runnable work is a function of state, not the whole backlog.
+
+`examples/dual_state_search.py` is a runnable, offline version — a planner proposing strategies, workers scoring them concurrently, and a verifier promoting the best. The domain types (intents, candidates, verified, incumbent) live in the consumer; the core provides only the `by_key` channel they fold through.
+
 ## Recipe: budget-aware stopping
 
 An autonomous run needs a ceiling — a router that stops not only on quality but on cost. Keep the budget where it belongs: `attempts` is a decision input that must survive a resume, so it lives in state; wall-clock time and token counts are non-deterministic, so keep them in [`RunMetrics`](../durability/observability.md) or your own hook rather than in the checkpoint. Putting a timestamp in state means a resume would "replay" a time from the past and mislead the router.

{agent_workflow_sdk-0.4.0 → agent_workflow_sdk-0.5.0}/docs/reference/api/state.md

@@ -12,4 +12,5 @@ State schemas, channels, and the built-in reducers. See the [State and reducers]
         - append
         - add
         - merge
+        - by_key
         - union

{agent_workflow_sdk-0.4.0 → agent_workflow_sdk-0.5.0}/docs/reference/api.md

@@ -15,6 +15,7 @@ class MyState(State):
 | `append` | list concatenation |
 | `add` | numeric sum |
 | `merge` | dict merge (update wins) |
+| `by_key` | per-key reducers for one dict channel |
 | `union` | set union |
 
 ## Graph — [guide](../concepts/nodes-and-edges.md)

{agent_workflow_sdk-0.4.0 → agent_workflow_sdk-0.5.0}/docs/reference/glossary.md

@@ -81,7 +81,7 @@ How an [agent backend](#agent-backend) answers a tool-authorization request. `Al
 A checked "good enough?" decision added with [`add_quality_gate`](../durability/quality-gates.md): an [evaluator](#evaluator) plus three-way routing (accept / revise / escalate) and an attempt budget. See [quality gates](../durability/quality-gates.md).
 
 ### Reducer
-A pure `(current, update) -> new` function that folds a node's update into a [channel](#channel). `last`, `append`, `add`, `merge`, `union`, or custom. See [state and reducers](../concepts/state.md).
+A pure `(current, update) -> new` function that folds a node's update into a [channel](#channel). `last`, `append`, `add`, `merge`, `by_key`, `union`, or custom. See [state and reducers](../concepts/state.md).
 
 ### Resume
 Continuing a suspended or crashed run from its last [checkpoint](#checkpoint), via `app.resume(thread, value)`. Requires a [checkpointer](#checkpointer). See [human-in-the-loop](../durability/human-in-the-loop.md).

agent_workflow_sdk-0.5.0/examples/dual_state_search.py

@@ -0,0 +1,188 @@
+# Copyright 2026 Daniel Sorkin
+#
+# 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.
+
+"""Dual-state search with a by_key channel: planner, workers, verifier.
+
+Run: python examples/dual_state_search.py
+
+Shows the shape a search/optimization loop takes on top of the core: one
+structured ``search`` channel whose fields accumulate differently, folded by
+``by_key``. A single planner is the only writer of ``intents``; several workers
+run concurrently in one super-step and each appends a ``candidate``; a single
+deterministic verifier is the promotion boundary — it appends to ``verified``,
+replaces the current ``incumbent`` whole, and clears the ``events`` it handled.
+
+Everything here is a plain function so the example runs on the dependency-free
+core — no backend, no network. A real planner would call an LLM/agent and a
+real worker would run one narrow experiment; the state plumbing is identical.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Annotated
+
+from agentflow import END, START, Graph, State, append, by_key, last
+
+# One structured channel, each field with its own fold policy. intents and
+# candidates and verified grow (append); events is replaced each step (last);
+# incumbent is overwritten whole when a better candidate is promoted (last).
+search_channel = by_key(
+    {
+        "intents": append,
+        "candidates": append,
+        "verified": append,
+        "events": last,
+        "incumbent": last,
+    }
+)
+
+
+class SearchState(State):
+    search: Annotated[dict, search_channel]
+    rounds: Annotated[int, last]
+
+
+# A tiny deterministic "objective": lower is better. Each strategy name maps to
+# a score, so the run is fully reproducible without any model.
+STRATEGY_SCORES = {
+    "try_index": 4.0,
+    "reorder_stages": 7.0,
+    "push_match": 2.5,
+}
+
+
+async def planner(state: SearchState, ctx) -> dict:
+    """The only writer of intents. Proposes strategies not yet verified."""
+    search = state["search"]
+    tried = {v["strategy"] for v in search.get("verified", [])}
+    proposals = [s for s in STRATEGY_SCORES if s not in tried]
+    # propose at most two per round, so re-planning happens more than once
+    new_intents = proposals[:2]
+    print(f"planner: proposing {new_intents or '(nothing new)'}")
+    return {
+        "search": {"intents": new_intents, "events": []},  # clear handled events
+        "rounds": state.get("rounds", 0) + 1,
+    }
+
+
+def _worker(strategy: str):
+    """Build a worker node that runs one narrow experiment for a strategy."""
+
+    async def worker(state: SearchState, ctx) -> dict:
+        # a real worker would run an index/pipeline experiment here
+        candidate = {"strategy": strategy, "score": STRATEGY_SCORES[strategy]}
+        return {"search": {"candidates": [candidate]}}
+
+    worker.__name__ = f"worker_{strategy}"
+    return worker
+
+
+async def verifier(state: SearchState, ctx) -> dict:
+    """Promotion boundary: deterministic, no model. Verifies new candidates,
+    promotes a new incumbent if one beats the current best, emits events.
+
+    Note ``candidates`` is an append channel: writing ``[]`` to it does not
+    clear it (``append`` of an empty list is a no-op). So the verifier works
+    off the candidates it has not verified yet, keyed by strategy, rather than
+    relying on a clear. This is the honest way to drain an append channel.
+    """
+    search = state["search"]
+    already = {v["strategy"] for v in search.get("verified", [])}
+    candidates = [c for c in search.get("candidates", []) if c["strategy"] not in already]
+    incumbent = search.get("incumbent")
+
+    verified = [{"strategy": c["strategy"], "score": c["score"]} for c in candidates]
+    best = min(candidates, key=lambda c: c["score"]) if candidates else None
+
+    updates: dict = {"search": {"verified": verified}}
+    if best is not None and (incumbent is None or best["score"] < incumbent["score"]):
+        updates["search"]["incumbent"] = best
+        updates["search"]["events"] = ["NEW_INCUMBENT"]
+        print(f"verifier: NEW_INCUMBENT {best['strategy']} score={best['score']}")
+    else:
+        updates["search"]["events"] = ["NO_IMPROVEMENT"]
+        print("verifier: no improvement this round")
+    return updates
+
+
+def route_after_verifier(state: SearchState) -> str:
+    """Event-driven re-planning: loop back to the planner while there is still
+    something to try and we improved; stop otherwise or at a round cap."""
+    search = state["search"]
+    tried = {v["strategy"] for v in search.get("verified", [])}
+    exhausted = tried >= set(STRATEGY_SCORES)
+    if exhausted or state.get("rounds", 0) >= 5:
+        return "done"
+    if "NEW_INCUMBENT" in search.get("events", []):
+        return "replan"
+    return "done"
+
+
+def dispatch(state: SearchState) -> list[str]:
+    """Fan out one worker per *runnable* intent, all in the next super-step.
+
+    ``intents`` is an append channel, so it accumulates every proposal ever
+    made. The runnable frontier is the subset not already verified — this is
+    why you compute a frontier instead of dispatching the raw intents list.
+    """
+    search = state["search"]
+    tried = {v["strategy"] for v in search.get("verified", [])}
+    runnable = [i for i in search.get("intents", []) if i in STRATEGY_SCORES and i not in tried]
+    return runnable or ["noop"]
+
+
+async def noop(state: SearchState, ctx) -> dict:
+    return {"search": {"candidates": []}}
+
+
+def build() -> Graph:
+    g = Graph(SearchState)
+    g.add_node("planner", planner)
+    for strategy in STRATEGY_SCORES:
+        g.add_node(f"worker_{strategy}", _worker(strategy))
+    g.add_node("noop", noop)
+    g.add_node("verifier", verifier)
+
+    g.add_edge(START, "planner")
+
+    # planner fans out to a worker per runnable intent (concurrent super-step)
+    worker_targets = {s: f"worker_{s}" for s in STRATEGY_SCORES}
+    worker_targets["noop"] = "noop"
+    g.add_conditional_edges("planner", dispatch, worker_targets)
+
+    # every worker leads into the single verifier
+    for strategy in STRATEGY_SCORES:
+        g.add_edge(f"worker_{strategy}", "verifier")
+    g.add_edge("noop", "verifier")
+
+    # verifier either re-plans or ends
+    g.add_conditional_edges("verifier", route_after_verifier, {"replan": "planner", "done": END})
+    return g
+
+
+async def main() -> None:
+    app = build().compile()
+    out = await app.invoke({"search": {}, "rounds": 0})
+    search = out["search"]
+    print()
+    print(f"rounds run:    {out['rounds']}")
+    print(f"verified:      {[v['strategy'] for v in search['verified']]}")
+    print(f"best incumbent: {search['incumbent']}")
+    # candidates was cleared by the verifier each round; events holds the last
+    print(f"last events:   {search['events']}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

{agent_workflow_sdk-0.4.0 → agent_workflow_sdk-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "agent-workflow-sdk"
-version = "0.4.0"
+version = "0.5.0"
 description = "Async-first SDK for orchestrating local coding-agent CLIs (Claude Code, Codex, Kiro) and LLMs as durable, graph-based workflows."
 readme = "README.md"
 requires-python = ">=3.11"

agent_workflow_sdk-0.5.0/tests/test_reducers.py

@@ -0,0 +1,168 @@
+# Copyright 2026 Daniel Sorkin
+#
+# 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.
+
+"""Tests for the by_key per-key reducer.
+
+Unit tests fold values through the reducer directly; the integration test
+drives a real fan-out through the engine so two concurrent workers each add a
+candidate to the same structured channel and the merge is deterministic.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import pytest
+from agentflow import END, START, Graph, State, append, by_key, last, merge
+
+# --- unit: folding rules ---------------------------------------------------
+
+
+def test_folds_each_key_with_its_own_reducer():
+    r = by_key({"intents": append, "events": last})
+    current = {"intents": ["i1", "i2"], "events": ["OLD"]}
+    out = r(current, {"intents": ["i3"], "events": ["NEW"]})
+    assert out == {"intents": ["i1", "i2", "i3"], "events": ["NEW"]}
+
+
+def test_absent_key_is_left_untouched():
+    r = by_key({"intents": append, "events": last})
+    current = {"intents": ["i1"], "events": ["OLD"]}
+    # update touches only events; intents must survive unchanged
+    out = r(current, {"events": ["NEW"]})
+    assert out == {"intents": ["i1"], "events": ["NEW"]}
+
+
+def test_empty_list_update_clears_via_last():
+    # {"events": []} is a real last([...], []) -> [], not a no-op
+    r = by_key({"events": last})
+    out = r({"events": ["A", "B"]}, {"events": []})
+    assert out == {"events": []}
+
+
+def test_none_current_starts_empty():
+    r = by_key({"intents": append})
+    out = r(None, {"intents": ["i1"]})
+    assert out == {"intents": ["i1"]}
+
+
+def test_empty_update_is_noop_copy():
+    r = by_key({"intents": append})
+    current = {"intents": ["i1"]}
+    for empty in ({}, None):
+        out = r(current, empty)
+        assert out == {"intents": ["i1"]}
+        assert out is not current  # a copy, not the same object
+
+
+def test_incumbent_last_overwrites_whole():
+    # the promotion case: incumbent is replaced whole, not deep-merged
+    r = by_key({"incumbent": last})
+    current = {"incumbent": {"obj": 10.0, "plan": "IXSCAN"}}
+    out = r(current, {"incumbent": {"obj": 7.5}})
+    assert out == {"incumbent": {"obj": 7.5}}  # plan is gone, by design
+
+
+def test_key_not_in_policy_raises():
+    r = by_key({"intents": append})
+    with pytest.raises(KeyError, match="incumbnet"):
+        r({}, {"incumbnet": {}})  # typo -> loud failure
+
+
+def test_current_key_outside_policy_passes_through():
+    # a key already in current that the policy does not govern is preserved
+    # as long as the update does not write it
+    r = by_key({"intents": append})
+    out = r({"legacy": 1, "intents": ["i1"]}, {"intents": ["i2"]})
+    assert out == {"legacy": 1, "intents": ["i1", "i2"]}
+
+
+def test_mixed_policy_with_merge_inside():
+    # a nested reducer can itself be merge (shallow) for a sub-dict field
+    r = by_key({"bounds": merge, "events": last})
+    current = {"bounds": {"lo": 1.0}, "events": ["x"]}
+    out = r(current, {"bounds": {"hi": 9.0}, "events": []})
+    assert out == {"bounds": {"lo": 1.0, "hi": 9.0}, "events": []}
+
+
+# --- integration: concurrent fan-out into one by_key channel ---------------
+
+
+SEARCH = by_key(
+    {
+        "intents": append,
+        "candidates": append,
+        "verified": append,
+        "events": last,
+        "incumbent": last,
+    }
+)
+
+
+class OptState(State):
+    search: Annotated[dict, SEARCH]
+
+
+async def test_concurrent_workers_append_into_one_channel():
+    """Two workers in the same super-step each add a candidate; both survive.
+
+    This is the dual-state shape: distinct keys of one structured channel
+    accumulate differently (candidates grows via append, events replaced via
+    last), and concurrent writers do not clobber each other.
+    """
+    g = Graph(OptState)
+
+    async def planner(state, ctx):
+        return {"search": {"intents": ["try_index", "reorder"], "events": ["PLANNED"]}}
+
+    async def worker_a(state, ctx):
+        return {"search": {"candidates": [{"id": "a"}]}}
+
+    async def worker_b(state, ctx):
+        return {"search": {"candidates": [{"id": "b"}]}}
+
+    async def verifier(state, ctx):
+        cands = state["search"]["candidates"]
+        # promote a winner whole; clear the events the planner emitted
+        return {
+            "search": {
+                "verified": [{"from": len(cands)}],
+                "incumbent": {"obj": 1.0},
+                "events": [],
+            }
+        }
+
+    g.add_node("planner", planner)
+    g.add_node("worker_a", worker_a)
+    g.add_node("worker_b", worker_b)
+    g.add_node("verifier", verifier)
+    g.add_edge(START, "planner")
+    # fan-out both workers in one super-step
+    g.add_conditional_edges("planner", lambda s: ["a", "b"], {"a": "worker_a", "b": "worker_b"})
+    g.add_edge("worker_a", "verifier")
+    g.add_edge("worker_b", "verifier")
+    g.add_edge("verifier", END)
+
+    out = await g.compile().invoke({"search": {}})
+    search = out["search"]
+
+    # both workers' candidates merged (frontier order: a then b)
+    assert search["candidates"] == [{"id": "a"}, {"id": "b"}]
+    # planner's intents preserved through later super-steps
+    assert search["intents"] == ["try_index", "reorder"]
+    # verifier saw both candidates and promoted a whole incumbent
+    assert search["verified"] == [{"from": 2}]
+    assert search["incumbent"] == {"obj": 1.0}
+    # events were replaced, not appended (last): planner's PLANNED is gone
+    assert search["events"] == []