Never on the Save Path

"A symptom captured mid-flare must not depend on Office being awake. The network is never allowed onto the save path."

Local Write Comes First, Always

The capture contract has one non-negotiable rule: the local write commits first, always, with immediate visual confirmation. When Dad writes a crumb, it lands in device-local storage and shows as saved before any network attempt begins. Neither Office reachability nor Pippa availability sits between him and a captured thought. This is not a nicety for spotty connections — it is the difference between a tool you can trust with a 2 a.m. flare and one that shrugs "couldn't reach the server, try again."

The Outbox State Machine

Behind that guarantee is a small state machine. A new crumb is LOCAL_ONLY the instant it is written, then QUEUED, then SYNCING when a connection is available, then SYNCED once the server has durably acknowledged it. If sync fails in a way that needs a human, it becomes FAILED_NEEDS_ATTENTION rather than silently vanishing. The crucial rule: the local payload is never deleted before an idempotent server acknowledgement — so a retry can never duplicate a crumb, and a lost connection can never lose one.

The network is never on the critical save path. The device commits and confirms first; the outbox drains on its own when connectivity returns. PWA storage is a staging area, not the final archive — but nothing leaves it until the office has durably taken over, and the Stream always surfaces the unsynced count so the staging state is visible, never hidden.

Why Health Makes This Non-Optional

Waystone learned this in a dead hotel network in Grindelwald; Forge inherits it for a sharper reason. Symptoms arrive at the worst moments — mid-flare, half-asleep, in a waiting room with one bar. If capture required a round-trip, the exact moments most worth recording would be the ones the tool dropped. So the save path is local and synchronous, and the sync is a background afterthought. When you build a capture surface for anything that matters, put the network after the confirmation, never before it.

Code

The outbox state machine·text

write crumb
   |
   v
LOCAL_ONLY  --(queued for send)-->  QUEUED
   |                                   |
   | (visual confirm shown NOW,        | (connection available)
   |  before any network)              v
   |                                SYNCING --(idempotent ack)--> SYNCED
   |                                   |
   |                                   | (error needing a human)
   |                                   v
   '------------------------> FAILED_NEEDS_ATTENTION

# Rule: the local payload is never deleted before an idempotent
# server ack. Retry cannot duplicate; a dropped link cannot lose.

Exercise

Imagine capturing a symptom in an elevator with no signal. Trace what Forge does at t=0 (offline) and at t=later (signal returns). Which single step must never wait for the network — and what state is the crumb in during the ride down?

Hint

At t=0 the crumb is written LOCAL_ONLY and confirmed immediately; during the ride it sits QUEUED; at t=later it goes SYNCING then SYNCED. The commit-and-confirm step is the one that must never wait.

Local Write Comes First, Always

The Outbox State Machine

Why Health Makes This Non-Optional

Code

External links

Exercise

Progress

Comments 0