How it works
A state merge begins when multiple agent branches read from a shared checkpoint and perform work independently. Each branch returns a proposed update rather than mutating authoritative workflow state directly. That proposal should identify its base state version, branch identity, changed fields, supporting artifacts, completion status, and any external actions already attempted.
The merge path is a control loop:
- Validate each proposal against the branch’s output contract and write permissions.
- Reject or quarantine malformed, stale, unauthorized, or incomplete updates.
- Detect conflicts where branches changed the same field, invalidated another result, or made incompatible claims.
- Apply declared reduction rules, such as combining independent records, selecting a verified result, or failing closed on an unresolved conflict.
- Commit the accepted result atomically as a new authoritative state version.
- Record the inputs, decision, rejected updates, and resulting version in the execution journal.
The reducer may be deterministic code or a bounded evaluation step, but the policy must be defined before the branches return. Asking a model to “combine the results” without a schema or conflict policy is synthesis, not a reliable state merge. Retries also need stable proposal identifiers so that replaying a completed branch does not duplicate its contribution.
Why it matters in an agent harness
Parallel agents improve throughput only if their outputs can re-enter the workflow safely. Without a state merge boundary, branches can overwrite newer work, revive stale decisions, duplicate tasks, or convert partial completion into apparent success. The failure is often quiet. The final object still looks structurally valid even though its history is inconsistent.
A proper merge separates computation from authority. Workers may inspect context and propose changes, while one controlled path decides what becomes durable. This preserves a clear permission model: access to a branch does not automatically grant permission to rewrite the workflow record. Field-level write scopes can further prevent a research branch, for example, from changing publication approval or execution limits.
Merge records also make concurrent runs legible. An operator should be able to answer which checkpoint each branch saw, what it proposed, why one update won, and whether any result was discarded. That provenance supports debugging, trajectory evaluation, and replay. A final snapshot alone cannot explain a lost update.
State merge also defines a recovery boundary. If validation fails before commit, the harness can retain the previous authoritative version and rerun only the affected branches. If the merge commits atomically, rollback has a specific target. This does not reverse external side effects. A branch that sent a message or changed a remote system needs an idempotency key, an outcome record, or a compensating action. Merging local state cannot make an already executed side effect disappear.
The central tradeoff is coordination cost. More precise proposals, versions, and conflict checks add latency and implementation work. That cost is justified where concurrent branches influence permissions, durable records, downstream execution, or claims presented as settled fact. Lightweight aggregation may be enough for disposable suggestions, but it should not be mistaken for authoritative state management.
State Merge vs Single-writer principle
The single-writer principle restricts authoritative mutation to one writer. State merge defines how concurrent proposals are reconciled before that writer commits them. They are complementary controls, not competing architectures.
| Control | Primary decision | Typical boundary |
|---|---|---|
| State merge | Which concurrent updates can coexist, conflict, or win | Between parallel branch completion and the next workflow state |
| Single-writer principle | Who may commit authoritative state | At the durable state store or orchestration layer |
A harness can let many workers produce proposals while retaining one merge coordinator as the sole writer. Allowing every worker to resolve and commit its own conflicts removes the boundary that makes the resulting state authoritative.
The Rifty take
We treat state merge as a commit protocol, not a summarization prompt. We optimize for inspectable conflict rules and one authoritative result, accepting some coordination overhead to prevent silent loss and permission drift. When the reducer cannot justify a resolution from declared policy and recorded evidence, the merge should remain unresolved rather than manufacture coherence.
Implementation checks
- Require every branch proposal to name the state version it read.
- Give proposals stable identifiers so retries and replay are idempotent.
- Define field-level write scopes before parallel execution begins.
- Validate proposal schemas and branch completion states before reduction.
- Distinguish mergeable additions from mutually exclusive decisions.
- Fail closed when two privileged or irreversible updates conflict.
- Commit the merged state atomically under a new version.
- Preserve accepted, rejected, and unresolved proposals in the execution journal.
- Record external side effects separately from local state updates.
- Test stale branches, duplicate returns, missing branches, malformed outputs, and reducer interruption.
- Verify that a partial fan-out cannot be reported as complete merely because one branch succeeded.
Frequently asked questions
Should an LLM perform the state merge?
An LLM may evaluate ambiguous content inside a bounded merge step, but it should not control version checks, permissions, atomic commits, or retry handling. Deterministic code should enforce those invariants. Any model judgment should return a structured proposal with recorded evidence and remain subject to explicit acceptance rules.
What should happen when two branches update the same field?
The reducer should apply a declared conflict rule based on the field’s semantics. Safe choices include rejecting both proposals, selecting a higher-authority source, or requesting another evaluation. Last-write-wins is appropriate only when ordering genuinely defines correctness, not merely because one branch happened to finish later.
Does state merge make parallel side effects safe?
No. State merge reconciles workflow records, not changes already made in external systems. Parallel side effects need their own controls, including scoped permissions, idempotency keys, outcome verification, and compensating actions where reversal is possible. The merge should record those outcomes without pretending that a local rollback undoes them.
How can a state merge remain replayable?
Replay requires immutable branch proposals, stable identifiers, recorded base versions, and a versioned merge policy. Given the same accepted inputs and policy, deterministic portions should produce the same state. If model judgment is involved, preserve its prompt, context, output, and acceptance decision so divergence remains visible.