Single-writer principle

How it works

The single-writer principle assigns every mutable state domain one active writing authority. That authority may be an orchestrator, a state service, a queue consumer, or a leased agent. The important boundary is not the process name. It is that two actors cannot independently commit changes to the same authoritative state at the same time.

A typical control path is:

1. Workers read an identified state version and perform bounded work.
2. They return proposals, results, or patches rather than mutating authoritative state directly.
3. The writer validates each submission against permissions, invariants, and the expected state version.
4. It orders accepted mutations and records the resulting transition.
5. Readers observe the new committed version.

This rule does not require one writer for the entire system. State can be partitioned by run, artifact, account, repository path, or another ownership key. Each partition still needs an unambiguous writer at any instant.

Writer failover must also preserve exclusivity. A lease, fencing token, generation number, or equivalent ownership check should prevent a delayed former writer from committing after replacement. Without that protection, failover creates two writers and defeats the mechanism precisely when the system is already under stress.

Why it matters in an agent harness

Agentic systems make concurrent work easy. Several agents can inspect the same plan, retry the same tool call, or attempt to advance the same job. Their outputs may all be individually reasonable while their combined mutations are invalid. One agent marks a task complete while another records a failure. Two workers publish different revisions. A retry consumes a result after the original execution has already moved the run forward.

The single-writer principle contains this coordination problem. Workers can remain nondeterministic because the commit path is deterministic about who may change state and in what order. This separates model capability from mutation authority. An agent may recommend a transition without possessing permission to make it authoritative.

The rule improves several operating properties:

• Control: one component enforces transition rules, approval requirements, and execution limits.
• Observability: each committed change has a clear actor, prior version, and ordering point.
• Failure containment: a confused or compromised worker can produce a bad proposal without directly corrupting shared state.
• Recovery: a checkpoint and its mutation journal can be reconciled through one ordered history.
• Evaluation: operators can distinguish model output from the harness decision that accepted, rejected, or modified it.

The tradeoff is concentration. The writer can become a throughput limit or availability dependency. That is usually preferable to ambiguous ownership, but it still requires bounded queues, backpressure, durable state, and an explicit failover contract. Partitioning can increase throughput when partitions do not share invariants. If two partitions must update atomically, splitting their writers merely relocates the coordination problem.

Single-writer principle vs state merge

These patterns resolve different kinds of concurrency. Single-writer ownership prevents competing commits. State merge permits independent branches and later reconciles them.

Merge is appropriate when changes are genuinely composable. It is unsafe as a generic answer for state with exclusive transitions. Two summaries can often be combined. Two decisions to spend the final unit of a budget cannot. I use the invariant to choose the pattern: if accepting one mutation can invalidate another, the system needs serialization somewhere.

The Rifty take

We optimize for many readers and proposal producers, but one explicit commit authority per state partition. We accept some coordination latency to gain legible transitions, enforceable permissions, and reliable recovery. Parallel reasoning is useful; parallel authority over the same invariant is usually not.

Implementation checks

• Name the authoritative state and its current writer in the run contract.
• Keep workers read-only or restrict them to isolated proposal storage.
• Require an expected version, generation, or fencing token on every commit.
• Reject stale writes instead of silently applying or merging them.
• Record the proposer separately from the authority that committed the change.
• Define what happens to queued proposals when writer ownership changes.
• Test delayed retries, duplicate delivery, writer crashes, and split ownership.
• Partition only where cross-partition invariants do not require atomic updates.
• Alert on overlapping leases, unexplained version jumps, and rejected stale commits.

Frequently asked questions

Does the single-writer principle require one process for the whole system?

No. It requires one active writing authority for each authoritative state partition, not one global process. A harness can assign separate writers by run, account, artifact, or repository path. The partition is safe only when its invariants do not require atomic coordination with another independently written partition.

Can multiple agents still work in parallel under this principle?

Yes. Multiple agents can research, evaluate, draft, or generate proposed patches concurrently. They should return versioned proposals to the designated writer instead of committing directly. This preserves parallel reasoning and tool use while giving the harness one place to validate permissions, invariants, ordering, and stale results.

How should a harness replace a failed writer?

Replace it through an ownership protocol that makes old authority unusable. A lease alone may be insufficient if a delayed writer can resume after expiry. Generation numbers, fencing tokens, or equivalent commit-time checks let the state store reject mutations from a writer whose ownership has been superseded.

When is state merge better than single-writer ownership?

State merge is better when concurrent changes are independent, provenance remains intact, and reconciliation has explicit semantics. Additive evidence or alternative drafts may qualify. Use a single commit authority when one accepted change can invalidate another, especially for budgets, permissions, workflow transitions, publication state, or irreversible actions.

Does a single writer eliminate race conditions?

No. It removes concurrent commits inside the state domain it controls, but races can remain around external tools, delayed observations, retries, and side effects. The harness still needs idempotency, version checks, durable execution records, and recovery rules for outcomes that occurred outside the writer's transactional boundary.