Observed State: The Facts

"An observation is a measurement with a clock on it. The clock is part of the fact."

Facts, timestamped

Observed state is what a probe actually saw, and when. Not what should be true — what a bounded, read-only check found at a specific instant. Every observation carries an observed_at, because a fact without a timestamp is a rumor.

Reachability is not one signal

The biggest trap is collapsing "can I reach it?" into a single yes/no. A machine can be a visible peer on the network, accept an SSH connection, and answer a probe — and those are three independent facts. It can be a visible peer that refuses SSH. It can accept SSH but time the probe out. Store them separately, because each failure points at a different cause.

Partial is a real outcome

A probe doesn't only pass or fail. It can half-succeed: it read the OS build, then timed out before it got disk usage. Flattening that to "failed" throws away the half you have; flattening it to "passed" invents the half you don't. Partial is its own honest result.

Freshness is a fact too

A three-day-old observation is not a current one, no matter how green it looked when it landed. The moment observed_at slips past the freshness budget, the honest reading is stale — not the last value pretending to still be true.

The registry is canonical; observations are replaceable history. You can throw away last week's snapshots without losing anything that matters. You can never throw away who is on the roll.

Code

One observation, honest about its own edges·json

{
  "host_id": "server",
  "observed_at": "2026-07-19T04:12:07Z",
  "age_seconds": 47,
  "reachable": {
    "tailscale_peer": true,
    "ssh": true,
    "probe": "succeeded"        // succeeded | partial | failed -- not a bool
  },
  "os": { "product": "macOS", "build": "25F84" },
  "resources": { "load1": 1.8, "disk_free_gb": 812, "uptime_days": 6 },
  "gui_phase": "desktop_ready",
  "filevault": "off",
  "services": [{ "name": "backup-agent", "loaded": true }],
  "drift": []
}
// reachable has THREE signals, not one. A host can be a visible peer,
// accept SSH, and still fail the probe -- or answer everything while
// being 3 minutes stale. age_seconds is a fact, not a footnote.

Exercise

For one machine, sketch a single observation record. Break 'reachable' into at least three separate signals, and add a field that makes the record honest about how old it is. Then describe one real failure where two of your three signals disagree.

Hint

Two signals disagreeing is the interesting case: a laptop that's a visible tailnet peer (radio on) but refuses SSH (asleep, or key rotated). One bool would have called that simply 'up' or 'down' and been wrong either way.

Facts, timestamped

Reachability is not one signal

Partial is a real outcome

Freshness is a fact too

Code

External links

Exercise

Progress

Comments 0