The Census and Its Drift

"The census doesn't ask what should be true. It goes and looks."

What the Census Actually Measures

The census is Firelink's act of looking. For each member it measures a specific set of read-only facts: disk and repository presence; Git branch, dirty paths, upstream and divergence; GitHub presence; version discovery; the installed native bundle and whether its process is running; registered service state; web endpoint health; launchd ownership; and the Tailscale Serve mapping. None of these are declared — they're all observed, right now, from the host. That's the difference between a hub that knows and a hub that remembers.

The one that catches people most often is Git dirtiness. 'Which repo has uncommitted work I forgot on another Mac?' — the census answers that by actually running the Git equivalent of a status check and reporting dirty paths, ahead/behind counts, and divergence. That was one of the original hub questions from the very first lesson, and it's answered here by measurement, not memory.

Drift Is Where Observed Meets Declared

Every observed fact is compared against what was declared, and the gaps become the drift report: a managed repo missing from the roster, a network declaration absent or contradictory, an operational manifest missing or invalid, a declared service not installed, a GitHub repo absent, a version unknown, a launch target unavailable on this client. Drift isn't failure — it's the honest accounting of where the map and the territory disagree, surfaced so a human can decide what to do about it.

The Census Only Looks — It Never Fixes

Every probe is read-only. The census observes and timestamps; it never writes back silently, never auto-deletes, never retires, never rewrites, never guesses product intent. It will happily tell you a repo is dirty, a service is missing, a version is unknown — and then stop, because deciding what to do about any of those is a human's call. Looking is the census's entire job, and looking without touching is what makes it safe to run constantly.

Make observation exhaustive and read-only. A census that measures many facts and changes none can run as often as you like, be trusted completely, and never be the cause of an incident. The moment a 'read' operation can also write, you've built something you have to be afraid of running.

Code

The census: many read-only probes, all timestamped·python

def observe(member) -> ObservedState:
    now = clock.now()
    return ObservedState(
        measured_at   = now,
        on_disk       = repo_dir_exists(member),
        git           = git_probe(member),      # branch, dirty paths, ahead/behind
        github        = github_presence(member), # exists / absent / inaccessible
        version       = discover_version(member),# from cwk-product.json, else unknown
        installed_app = bundle_installed(member), # native app present?
        process       = process_running(member), # and is it actually running?
        service       = service_state(member),   # running|stopped|missing|unknown
        endpoint      = endpoint_health(member),  # HTTP health probe
        launchd       = launchd_owned(member),    # owned by the expected job?
    )
    # Every field is MEASURED. Nothing here writes, deletes, or repairs.
    # Compare against declared truth elsewhere -> that produces DRIFT.

Exercise

Write down the full set of facts a monitor would need to measure to honestly answer 'is this service healthy and current?' for something you run. Separate them into declared (from config) and observed (measured live). Then check: is every one of your observed probes strictly read-only? Find any probe that could accidentally change state, and describe how you'd split it into a pure read plus a separate, deliberate write.

Hint

Probes that log in, 'wake' a service, or 'touch' a file to check it are secretly writes. A read that has a side effect is the thing that makes people afraid to run the monitor — separate the look from the touch.

What the Census Actually Measures

Drift Is Where Observed Meets Declared

The Census Only Looks — It Never Fixes

Code

External links

Exercise

Progress

Comments 0