3. The write path (follow one action end to end)

# 3. The write path (follow one action end to end)

This is the whole backend in one diagram. A renderer edits a scene:

```
 React dispatch(action)                                        ← FRONTEND
   │  (optimistic: reducer applies locally for instant UI)
   ▼
 POST /api/local/mutate   { cls, id, action, actor, now }      ← BACKEND route
   │
   ▼
 applyLocalMutation()      (src/lib/server/record/mutation.ts)  ← THE ONE WRITE PATH
   │   1. gate      — can this actor's role dispatch this action's category?
   │   2. reduce    — the pure reducer (src/lib/core/reducer/), clock pinned to `now`
   │   3. persist   — atomic write to the record + monotonic version bump
   │   4. attribute — audit entry
   │   5. echo      — publish on the change stream
   ▼
 the record (canon) ──echo──▶ /api/local/stream ──▶ every open window updates its cache
```

Reads don't take this path — they're local and instant off the cache. **Only writes pay the
round-trip.** Headless callers (the MCP server, loops, the bot) hit the *same* `/api/local/mutate`,
so a headless edit and a renderer edit are indistinguishable downstream.

The **three tiers** that sit on top of this (Tier 0 read queries · Tier 1 actions · Tier 2
operations) are documented in the generated [MCP manual](../../../generated/MCP_MANUAL.md) / [API_PRINCIPLES.md](../API_PRINCIPLES.md).

---

Raw Markdown source