The Lifecycle

"A machine doesn't blink in and out of the fleet. It walks a path with named doors."

States, not a switch

Membership isn't a boolean you flip. A machine moves through named states: it starts as a discovered candidate, goes through enrolling, becomes active, can flip to suspended and back, and eventually reaches retired — from which it can still be restored, or, by a separate high-risk action, purged. Each arrow is a door with a name, not a value change.

Enrollment is a ritual, not an insert

Adding a Mac isn't writing a row. It's a sequence: verify the candidate really is a Mac and capture stable identity evidence; check for active or retired duplicates first; assign a host_id, display name, color, role, and policy; prove the intended Tailscale and SSH path with a read-only probe; preview any optional bootstrap work; then create the binding and verify its very first observation. Enrollment is how a machine earns authority — step by step, on the record.

Suspend is the reversible pause

Suspend is for leave this alone for a while. It pauses management without touching membership history, and resume brings it straight back. Reach for it when a machine is going into a drawer for a month, or when you're doing maintenance and don't want the engine acting on it. It is not retirement — nothing is being said goodbye to.

Every transition is typed and audited

None of these are bare row edits. The public interface exposes enroll, suspend, resume, retire, and restore as durable operations that leave events behind — and it deliberately does not offer a raw delete-this-host as the way to remove a machine. The shape of the API is itself a guardrail.

Name the transitions, and they leave a trail. A lifecycle made of typed operations tells you not just where a machine is, but every door it walked through to get there.

Code

The membership lifecycle·text

discovered candidate
  -> enrolling          (verify it's a Mac; capture identity evidence; detect duplicates)
  -> active             (managed; eligible for operations)
       <-> suspended    (reversible pause; membership history preserved)
  -> retired            (tombstoned; blocks new work; keeps everything)
       -> restored      (same logical host, re-verified)
       -> purged        (SEPARATE high-risk action; a minimal audit record remains)

# The public API expresses these as typed operations:
#   enroll_host / suspend_host / resume_host / retire_host / restore_host
# It does NOT expose DELETE /managed-hosts/{id} as the normal 'remove.'
# The verbs are the safety rails: there is no door named 'just delete it.'

Exercise

Draw the lifecycle for one machine you own, using named states and named transitions. Include one reversible pair (like suspend/resume) and one door you'd only walk through deliberately (like retire). Then mark which transitions you'd want an audit event for.

Hint

If your diagram has an arrow labeled just 'delete,' redraw it as 'retire' with a tombstone, and add a separate, scarier 'purge' further along. The point of naming doors is that some of them should feel heavier to open.

States, not a switch

Enrollment is a ritual, not an insert

Suspend is the reversible pause

Every transition is typed and audited

Code

External links

Exercise

Progress

Comments 0