principle-separate-before-serializing-shared-state

First check whether the workers truly need the same mutable object. Give each actor its own owned file, key, or branch and merge only at the read boundary; serialize access structurally with lockfiles or sequential phases only when one shared writer is a real invariant.

Shared mutable state includes files multiple actors both read and write, branches multiple actors push to, keys in a shared state object, and APIs both defined and consumed by different actors. Even two workers writing separate fields into one state.json file is shared mutation.

Use a lock only when a single shared write target is a genuine invariant that cannot be split. Treat needing a lock as a design smell to verify first; when locking is required, enforce it structurally through lockfiles, single-writer actors, or atomic compare-and-swap.

Telling agents or goroutines to take turns does not work because conventions are not enforced by the system. Race conditions from shared writes are intermittent and hard to reproduce, so only structural mechanisms like ownership separation or lockfiles reliably prevent them.

Assign each agent its own state file scoped to its responsibility, such as indexer-state.json and metrics-state.json instead of one shared state.json. Merge the separate files only at the read or reporting boundary where a combined view is needed.