C.W.K.
Stream
Lesson 01 of 05 · published

Every Change Is an Operation

~10 min · durable-operation, state-machine, needs-attention

Level 0Lone Machine
0 XP0/37 lessons0/12 achievements
0/100 XP to next level100 XP to go0% complete
"A click that fires and hopes is a wish. An operation is a record you can still question after everything goes wrong."

A button click is not an operation

The naive model of changing a machine is a button: click restart, it runs, you hope. But what happens if the browser closes mid-restart? If the network drops? If you handed the job to a teammate and went to lunch? With a button, the answer is the same every time: you don't know. A button records nothing. It's a wish with a loading spinner.

An operation is a durable record with a state machine

The fix is to make every mutation — whether Dad clicks it, Pippa assists, or a delegate runs it — a durable operation: a persisted record that walks a known path. draft → planned → awaiting_approval → running → verifying → succeeded | failed | needs_attention | cancelled. At any instant you can ask which state it's in, and the answer is real, because it was written down before it was shown.

What the record carries

An operation isn't just a status; it holds everything you'd need to understand or resume it: a stable id and kind, the human intent, who requested it and who's executing it, the capabilities it needs, the source host, a frozen target snapshot, its risk class and approval rule, preconditions and preflight evidence, ordered steps, per-target state and events, verification checks, and a recovery story. That's a lot — and it's exactly what a button throws on the floor.

needs_attention is a real destination

Notice that one terminal state is neither success nor failure — it's needs_attention. Some operations end genuinely ambiguous: half-applied, or blocked on a capability the executor turned out not to have. Calling that a clean success or a clean failure is a lie; giving it its own honest state is what lets a human step in with the whole record in front of them.

Write it down before you run it. A change you can't ask the state of later isn't an operation — it's a rumor you started on purpose.

Code

The operation state machine·text
draft
  -> planned
  -> awaiting_approval
  -> running
  -> verifying
  -> succeeded | failed | needs_attention | cancelled

# Every mutation is one of these, whether a human clicked it, Pippa
# drafted it, or a delegate is executing it. 'needs_attention' is a
# first-class ending -- the honest home for 'half-done, a person must look.'
What a durable operation records·json
{
  "id": "op_7f3a",
  "kind": "restart_service",
  "intent": "backup agent stopped on the server; bring it back",
  "requested_by": "dad",
  "executed_by": "office-executor",
  "required_capabilities": ["ssh_credentials"],
  "target_snapshot": ["server"],          // frozen at approval
  "risk_class": "medium",
  "approval": "required",
  "preflight": { "reachable": true, "caps_match": true },
  "steps": ["launchctl kickstart -k backup-agent", "verify loaded"],
  "verification": "service loaded AND last-run timestamp advances",
  "recovery": "if verify fails, capture logs, leave stopped, needs_attention",
  "state": "verifying"
}

External links

Exercise

Take a one-click action you do to a machine (restart a service, run an update). Turn it into an operation record: write its intent, its target, one precondition to check first, how you'd verify success, and what you'd do on failure. Then ask: if your terminal closed right after 'running', could you tell what happened?
Hint
If the honest answer is 'I'd have to go look and guess,' you have a button, not an operation. The operation's whole job is to make that question answerable from a record instead of a hunch.

Progress

Progress is local-only — sign in to sync across devices.
Spotted a bug or have feedback on this page?Report an Issue

Comments 0

🔔 Reply notifications (sign in)
Sign inPlease sign in to comment.

No comments yet — be the first.