Shared State Management — Patterns

Append facts, derive the view

Problem. When participants update a mutable record in place, each rewrite is an opportunity to lose something. A model asked to add one finding returns the whole structure with three earlier entries quietly missing, and nothing detects it.

Approach. Make the record append-only: every participant adds a fact with its author, timestamp, and source, and never rewrites what is there. Reading goes through a projection that applies defined precedence rules to produce the current view. Corrections are new entries that supersede, not edits that erase.

Trade-off. The log grows, projections need maintenance and correctness tests, and contradictory entries now accumulate visibly rather than being resolved by whoever wrote last. Making disagreement visible is the point, but someone must then decide what to do with it.

Claim before working, with an expiry

Problem. Two participants reading the same work list both take the next item. Checking whether an item is taken and then taking it is two operations, and the gap between them is where duplicate work and duplicate side effects are created.

Approach. Make claiming a single atomic operation that fails for everyone but the winner, and attach an expiry so a participant that dies does not hold the item permanently. Require the holder to renew while working and to release explicitly on completion, with a sweeper reclaiming anything expired.

Trade-off. Expiry duration is a guess that trades duplicated work against stalled items, and reclaiming an item whose original holder is merely slow produces exactly the duplicate execution the mechanism exists to prevent. Side effects therefore still need idempotency keys; claiming narrows the window rather than closing it.

Versioned writes with an explicit loser path

Problem. A blind write by a participant holding a stale value destroys an update it never saw, with no error. The losing update is usually the more recent and more correct one.

Approach. Attach a version to every readable unit, require writes to state the version they were derived from, and reject writes whose version is no longer current. Give the rejected writer a defined path — re-read and re-derive, merge, or escalate — rather than retrying blindly.

Trade-off. Under contention, participants spend iterations losing and re-deriving, which costs model calls. Finer-grained versioning reduces contention and increases the number of units whose mutual consistency nothing is enforcing.

Large things by reference, summaries in the record

Problem. Participants write whole documents, full tool payloads, and generated files into the shared record. It stops fitting anyone's context, every read transfers megabytes, and retention obligations now apply to a store nobody treats as a document store.

Approach. Keep artefacts in storage built for them and put a reference in the record: an identifier, a content hash, a type, a size, and a short description sufficient for a participant to decide whether to fetch it. Fetching is a deliberate act with its own cost, not a side effect of reading the record.

Trade-off. Two stores must be kept consistent, and a failure between writing the artefact and recording the reference leaves an orphan. Participants also skip fetching and reason from the description alone, so the description has to be honest about what it omits.