Editing the delivered value set leaves the workload spec unchanged — how does folding a checksum of the values into that spec force a replacement?

## Why the edit alone changes nothing A platform that keeps a declared set of instances running works by comparison: it reads the **declared shape** of an instance from the workload spec, compares it with the instances that exist, and acts on the difference. The delivered value set is a **separate object** that the spec merely references by name. Editing that object changes its own contents and nothing about the spec, so the comparison finds no difference and the loop — correctly, by its own rules — does nothing at all. That leaves a workload whose behaviour is supposed to depend on a value, and a platform with no way to know it does. The processes read those values once at start-up, so the only way the edit reaches them is for the processes to be new ones. ## The checksum trick The fix is to make the dependency **part of the declared shape**: 1. Whatever renders the spec reads the exact value set that will be delivered. 2. It computes a checksum over those bytes, normalised so that the same logical set always produces the same checksum. 3. It writes the checksum into a field of the **instance template** — the part of the spec that describes what each instance looks like. 4. The spec is submitted. If the values changed, the checksum changed, so every running instance now differs from what is declared. 5. The loop replaces the instances through its ordinary replacement path, and each new process reads the current values at start-up. The checksum's value is never read by anything. It is a deliberate, inert marker whose only job is to change when the values change. ## The properties that make it trustworthy - **Idempotent.** Re-submitting an unchanged spec with unchanged values produces the same checksum and therefore no replacement. There is no churn on every apply. - **Reversible.** Reverting the values restores the previous checksum, which restores the previous declared shape — so rolling back the configuration is the same operation as rolling it forward. - **Explicit.** The spec now records which value set the running instances were started against, which is exactly the fact an operator needs during an incident. - **Safe against partial edits.** The checksum covers the whole set, so changing any part of it is one change to one marker. ## Where it goes wrong - **The field is not part of the instance's declared shape.** Written into a field the loop treats as descriptive rather than defining, the checksum changes and nothing is replaced. This is the most common way the technique silently does nothing. - **The checksum is computed over the wrong bytes.** Hashing the source template rather than the rendered, delivered values means an edit that changes the rendered output without changing the template is missed — and, in the other direction, an irrelevant template edit forces a pointless fleet replacement. - **Unstable serialisation.** If the value set is serialised with unordered keys or with a timestamp in it, the checksum differs on every render and the fleet is replaced every time anyone submits the spec. - **Someone else edits the values.** If a person or another process can change the delivered set directly, without going through whatever renders the spec, the checksum is stale and the guarantee is gone. ## What it costs, and when not to use it Every value edit becomes a **full replacement of every instance**. For the chat gateway, that means forty long-lived processes are torn down and rebuilt, and every long-lived client connection they hold is broken and re-established. Weigh that against the alternative: | Approach | What an edit costs | What it guarantees | |---|---|---| | Edit the values only | Nothing, and nothing happens | Nothing, unless the process re-reads on its own | | Checksum folded into the spec | A full replacement of the fleet | Every instance is running the edited values once it completes | | Process re-reads on signal or watch | A reload per instance, connections kept | Only as far as the reload path is complete and actually fires | The rule of thumb is: values that change rarely and must be unambiguous — a credential, a schema, a behaviour switch that must not be half-applied — are good candidates for the checksum. A table edited several times a day during business hours is a poor one, because it converts every edit into a rollout. Many teams use both: a reload path for routine edits, and the checksum for the edits that must be certain. Note what the checksum does **not** do. It does not decide how many instances are replaced at once, or gate the replacement on health — that is the rollout's policy, and it applies whatever the reason for the replacement was. The checksum's only contribution is giving the loop a reason to replace at all.