reliable-mutations

# Reliable Mutations ## Rule Make a change in **one atomic call** when the action supports it, then **verify the persisted end state and report concrete proof** (counts/ids). Never drive a multi-step change by looping many small writes, and never report success from a tool ✓ alone. ## Why Hosted foreground agent runs have a short soft budget so they can hand off cleanly under synchronous serverless walls. Durable background runs get a much longer budget, but they still should not rely on loops of many small writes: continuations can retry the same intent and leave partial state if each item is committed separately. One atomic call commits or fails as a unit; verification turns a hopeful ✓ into a fact. ## How 1. **Prefer a single atomic call.** If an action accepts the whole set (add many, set all, bulk update), pass the full batch in one call so it commits atomically. Check the action surface for a batch/plural form before reaching for a loop. 2. **Do not loop many small writes under any run budget.** A sequence of N per-item writes can still leave partial or no state when a foreground run hands off, a background run continues, or an upstream provider fails. If no batch action exists, that is a gap in the action layer — add or extend an action that accepts the batch (see the `actions` skill) rather than papering over it with a loop. 3. **Verify the end state after writing.** Re-read the data (a list/read action, a count query) and confirm the result matches intent — the right number of rows, the expected ids/fields. Do this before you tell the user it worked, and include the relevant verification expectation in the app's `AGENTS.md`. 4. **Report proof-of-done, not vibes.** State concrete evidence: "saved 12 of 12 panels (ids …)" or "updated 5 rows". Do not infer success from the presence of a tool ✓ on an individual call. 5. **On a time-budget cutoff, fail loud.** If the turn is cut before the change is fully committed and verified, say so explicitly and report what *did* persist (M of N) and what remains. Never round a partial or unverified write up to "done". ## Don't - Don't loop `for each item: write(item)` for a large set in a single hosted turn. - Don't claim completion because every tool call returned ✓ — a ✓ on an aborted chunk does not mean the row was committed. - Don't silently shrink the scope ("I added a few of them") and present it as the finished task. - Don't try to "fix" this by asking for a longer run timeout — the budget is correct; restructure the write instead. ## Related - `actions` — define or extend a batch/atomic action when only per-item writes exist. - `storing-data` — where app data lives and how reads/writes are scoped. - `performance` — avoid query waterfalls when verifying end state. - Design doc: `packages/core/docs/design/durable-agent-runs.md` — the real ceiling fix (checkpointed and durable runs); this skill is the agent-facing mitigation that reduces how often the ceiling is hit.