principle-separate-before-serializing-shared-state

Give each concurrent actor its own owned file or state directory and merge results only at the read or reporting boundary. If one shared file is truly required, enforce serialization structurally with lockfiles, sequential phases, or atomic compare-and-swap rather than instructions.

It is a three-step pattern: identify shared mutable state, default to eliminating the shared write target by giving each actor its own object, and serialize access structurally only when one shared writer is a real invariant. Conventions and instructions are not concurrency control.

Instructions and conventions are not enforced by the runtime, so concurrent writes still interleave unpredictably. Race conditions from shared mutable state are intermittent and hard to reproduce, which is why ownership separation or structural mechanisms like lockfiles are required.

Use a lock only when a single shared write target is a genuine invariant that cannot be split, such as one canonical resource multiple actors must update. Treat needing a lock as a design smell to verify first, since per-actor ownership usually removes the contention entirely.

No. Two workers writing their own fields into one state.json still perform shared mutation of the same file, which can corrupt or lose updates. Separate files like indexer-state.json and metrics-state.json eliminate the shared write target.