Status is observed, not declared

A status column is a convenience. Some piece of code did a thing, and on its way out it wrote down that it did the thing. The problem is that the write and the reality are two separate events, and only one of them is guaranteed. The code can set status = "published" and then the publish can fail, or half-succeed, or succeed into the wrong place. The field is now confidently, permanently wrong — and everything downstream that reads it inherits the lie.

Status is observed, not declared — and the drift is the signal. It computes real state from ground truth instead of trusting a field that says "done." I've been burned too many times by a green light that was lying.

That's the principle, stated plainly on my own site. "Observed, not declared" is the whole idea in four words. A declared status is what a system says about itself. An observed status is what you find when you independently go and measure the thing the status is supposed to describe. When those two disagree, the disagreement — the drift — is not noise to be reconciled away. It is the single most valuable thing the system can hand me.

The clearest example is indexing. Across the portfolio, the question "is this site's content actually in Google?" has an easy wrong answer — a column somewhere that says indexed: true — and a real answer that only exists if you reconcile the whole funnel, per site, stage by stage:

# the observed indexing funnel — each stage measured, not assumed
dev_db_pages        ->  # what the database thinks exists
production_pages    ->  # what's actually live and reachable
sitemap_urls        ->  # what we told Google about
gsc_submitted       ->  # what Search Console accepted
gsc_impression_pages     # what has EVER earned an impression

Every arrow in that chain is a place reality can quietly diverge from the claim. The database can hold ten thousand pages that never made it to production. Production can serve pages that never made it into the sitemap. The sitemap can list URLs Search Console silently dropped. And a page can be fully "submitted" and "accepted" and still have never once been shown to a human — which, functionally, means it does not exist.

A declared status collapses all of that into one boolean and throws the interesting part away. The observed funnel keeps every stage, so the drift localizes the problem for you. If dev-DB and production match but the sitemap is short, the bug is in the sitemap build. If the sitemap is complete but Search Console shows a fraction submitted, the bug is in submission. If everything is submitted and nothing earns an impression, the bug isn't plumbing at all — it's that the pages aren't worth showing. The gap doesn't just tell me something's wrong; it tells me where.

Once you start refusing declared status, you can't stop, because the label-versus-reality gap is everywhere. Take something as basic as "how many sites are live?" The lazy version reads a status = "live" flag off each project and sums them. That number is always subtly wrong, because "live" is a thing that was true when someone set the flag, and deploys and DNS and expirations don't come back to update it.

So the honest count comes from probing what's actually deployed and responding right now — not from trusting the flag. It's more work, and it occasionally tells me something I didn't want to hear, which is exactly the point. A number I have to earn by measurement is a number I can put on a page and defend. A number I copied out of a status field is a number that's true until it embarrasses me.

The place this bites hardest is the most visible one: the homepage. My site opens with a stat — merged pull requests, repositories touched, active days — and every one of those numbers is a claim about the outside world at a moment in time. The lazy way to render a hero number is to hardcode it, or to fetch it once and let it drift. Both are declarations. The figure sits there looking authoritative long after it stopped being true, and nobody notices until a visitor does the math.

So the build refuses to do that. A script, fetch-dev-activity.mjs, runs at build time and pulls the real figure from the command center's warehouse before it lets the number onto the page. And before it trusts what it got back, it checks the freshness of the source: the snapshot carries a generated_at timestamp, and if that timestamp is more than thirty days old, the script calls loudFail and exits non-zero. The build breaks rather than ship a stale "verified" number. A page I can't stand behind is not allowed to render.

// refuse to publish a number the build can't vouch for
const STALE_DAYS = 30
if (!d.generated_at ||
    (Date.now() - new Date(d.generated_at).getTime()) / 86400000 > STALE_DAYS) {
  loudFail(`snapshot is stale (generated_at=${d.generated_at}) ` +
           `— refusing to ship a stale "verified" number.`)
}

The fallback path is the same instinct pointed the other way. If the warehouse is unreachable, the script doesn't invent a number and it doesn't quietly ship a zero — it reaches for a last-good cache, prints a FALLBACK-USED line to the build log so the substitution is visible, and only then continues. Because the source upstream recomputes on a nightly cadence, a snapshot that's merely a day old is normal and shouldn't trip an alarm — so a separate watchdog, not the build, watches the served snapshot's own age and complains only when it genuinely rots. In every branch the rule is identical: the page shows a number the build could vouch for at the moment it ran, or it shows nothing and says so.

This principle isn't abstract for me, and it isn't free advice. The most expensive lesson I've written up — a self-inflicted Helpful-Content demotion that dragged my whole site's rankings down — was, at its root, a green light that lied. A content pipeline generated pages and dutifully marked each one published: true. Every row said success. The declared status of the system was: working perfectly, shipping content, no errors.

The observed status, if I'd been measuring it, was the opposite: those pages were earning impressions and zero clicks, and Google was quietly forming the opinion that my domain published things nobody wanted. That is the last arrow of the indexing funnel screaming, and I wasn't reading it. The drift between "published successfully" and "actually helping anyone" was enormous — and it was invisible precisely because I was trusting the declaration instead of watching the ground truth.

I rebuilt the command center's instincts around that scar. It is now, by temperament, suspicious of its own good news. The indexing funnel, the live-domain probe, the build that won't print a stale stat — those aren't separate features. They're the same reflex, learned the hard way, applied to every place a status could sit and rot.

The uncomfortable thing about "observed, not declared" is that it's more work forever. You don't get to write a status once and move on; you have to keep measuring, because the truth keeps drifting away from the record of it. But that's the trade I want. A system that reports what it wishes were true will let you sail confidently off a cliff. A system that keeps checking, and shows you the gap, is one you can actually leave alone — because the first thing it will tell you when something breaks is that its own green light is lying.