Kody Wildfeuer

Text Me Once: Notification-Agent Design Rules I Learned from a Nine-Day Spam Storm

2026-09-07T00:00:00+00:00

I run two categories of autonomous agent that are allowed to text my phone. One of them, over the last few weeks, sent me a genuinely useful message every single time it ran. The other one sent me hundreds of near-identical messages about the same three unreachable machines for nine straight days, and none of them told me anything I hadn’t already been told an hour earlier.

Same phone number. Same channel. Same “wake a human up” privilege. Wildly different outcomes. Worth writing down why.

The bad one

I have a launchd job called the Principal — an agent that sits in on a handful of other agents across my tailnet every 15–30 minutes, grades them against the job they declared, and texts me the verdict. It also has a heal arm that SSHes into unreachable machines and tries to restart things, and a relay arm that forwards messages when a classroom’s “own mouth is blocked.”

Three of the five machines it watches went unreachable for nine days — a real network outage, not a bug. Here’s what the agent did about it: it kept trying. Every 15 minutes, heal opened an SSH connection, timed out, tried to run RAPPSentinel remotely anyway, failed, and logged “healed battlestation: ran RAPPSentinel now” immediately followed by “after heal, battlestation grades F.” Then it did that again 15 minutes later. And again. For nine days. relay did the equivalent — “relayed 1 message(s) for battlestation (its own mouth is blocked)” — dozens of times, identical, no new information in any of them. Meanwhile three other watchers had gone stale and silent the entire time and nobody ever escalated on that.

By the time I actually looked at the logs, there were hundreds of lines that all said the same thing in slightly different words. Not one of them was actionable. The signal-to-noise ratio was effectively zero, which is the same as having no signal.

The good one

I also run a Hacker News scout — a tiny script, five runs a day, that scans HN top+new for threads in a few lanes I care about, drafts one paste-ready comment per thread, and texts me a batch of two or three. Every message is different. It has never once sent me a thread twice, because it keeps a suggested.json of every thread it’s already surfaced and filters against it before picking. It doesn’t depend on any machine but the HN API. If the API is briefly down, it just doesn’t run that cycle — no retry storm, no escalation, nothing to text about.

It is, deliberately, a much dumber piece of software than the Principal. That’s the point.

What actually separates them

Dedupe against state, not against nothing. The scout keeps a seen-set and will die before it resends something. The Principal had no equivalent for “I already told you this host is down” — every tick was evaluated as if it were the first time, so every tick became a new outbound message.

Don’t put flaky infrastructure in the hot path of the alerting loop. The scout’s only external dependency is a public read-only API that either answers or doesn’t. The Principal’s core loop depends on SSH into machines on a home tailnet — inherently the least reliable link in the whole system — and treats every failure of that link as new information worth a text.

Bound the output per run. The scout caps itself at three picks, once per scheduled run. There is a hard ceiling on how annoying it can be in a single day (five runs × three items). The Principal had no ceiling at all: five classrooms, checked as often as every 15 minutes, each one capable of independently generating a message, with a daily_escalation_budget field in its config that nothing in the code actually enforced.

Low, fixed frequency beats aggressive polling. Five calendar-scheduled runs a day is enough to be useful and rare enough that a human can absorb every message. Fifteen-minute intervals only make sense if every message is either new information or nothing gets sent — and the Principal violated that by sending on every check regardless of whether the state had changed.

A failure needs a circuit breaker, not a retry loop. The single missing piece that would have fixed the Principal entirely: after N consecutive identical failures against the same target, stop re-emitting the same verdict and fire one distinct “this needs a human, and I’m going quiet until it changes” message instead. Right now that logic doesn’t exist anywhere in the codebase. Nine days of retries produced nine days of noise instead of one useful escalation on day one.

The rule

If you’re building anything that’s allowed to interrupt a human — text, push notification, Slack ping, whatever — it earns that privilege one message at a time, and it can lose it. The design question isn’t “how do I detect this condition,” it’s “how do I make sure I only ever say it once.” Keep a seen-set. Keep your alerting loop’s dependencies boring and reliable. Cap your output. Collapse repeated failures into a single escalation instead of restating them. An agent that texts you the same unfixable fact every 15 minutes for nine days hasn’t automated anything — it’s just outsourced the noticing to your nervous system instead of its own state file.

Ten more, so the pattern is unmistakable

The Principal/scout contrast turned out to be one instance of a much more general rule. Here are ten more pairs, all failure modes I’ve actually shipped and later fixed:

1. Retry logic. Bad: retry the same operation forever with no backoff and no ceiling — that’s the Principal’s heal arm, retrying SSH every 15 minutes for nine days. Good: exponential backoff with a max attempt count, then stop and escalate once. A retry loop without a ceiling is a spam generator wearing a resilience costume.

2. Escalation vs. repetition. Bad: send the same “grade F” message every cycle for nine days straight. Good: message once on a state transition (OK→F), stay silent while the state is unchanged, message once more on F→OK. Alert on transitions, not on conditions.

3. Config that isn’t enforced. Bad: a daily_escalation_budget: 8 field sitting in a config file that no code path ever reads. Good: every declared limit has a corresponding runtime check, or it isn’t in the config at all. An unenforced config key is a lie the next reader will believe.

4. Dependency placement. Bad: put your alerting loop’s core logic behind SSH into three flaky machines on a home network. Good: put the flakiest dependency as far from the alerting path as it can go — the scout’s only hot-path dependency is a public, read-only API. Put your least reliable dependency as far from your alerting path as it can go.

5. Idempotency. Bad: an agent that re-suggests the same item if it runs twice before you act on the first suggestion. Good: a seen-set checked before every pick, so running it twice can never produce the same output twice. If running it twice produces two outputs, it’s not done being built.

6. Bounded output. Bad: five watched targets, checked as often as every 15 minutes, each capable of independently generating a message — no ceiling on the day’s total. Good: a hard cap like three items per run, five runs a day, so the day’s maximum message volume is a known, small number. Cap output at design time, not “aspirationally” in a comment.

7. Traceability. Bad: the only record of an incident is a rotating log file that logrotate or a stray rm can erase completely. Good: an append-only, hash-chained ledger that outlives the process and that other agents can read and verify. If the only copy of a decision is a log line, it doesn’t exist for anyone else.

8. Self-healing scope. Bad: “heal” a dead host by trying to run a command on the dead host — impossible by construction, and it’ll report success anyway if you’re not careful. Good: heal actions target things actually reachable from the healer; anything that requires the broken link to fix itself is an escalation, not a heal. Never let a heal action depend on the exact thing that’s broken.

9. Persistence of a fix. Bad: stop a runaway background job for the current session and call it done — it silently comes back at the next login because nothing changed on disk. Good: verify explicitly that the fix survives a restart before moving on. A fix you haven’t verified survives a restart isn’t a fix, it’s a snooze button.

10. Dry-run before live. Bad: no way to preview an outbound message before it sends, so every change to the alerting logic ships straight to a human’s phone untested. Good: a --dry flag that prints instead of sending, so new logic gets a free trial run first. If touching the alert logic risks alerting someone, you need a mode that doesn’t.

The Interface Should Meet You Halfway

2026-08-29T00:00:00+00:00

A placeholder is a promise that disappears at the first sign of intent.

The interface shows an example. The person starts typing because the example is close to what they want. Then the example vanishes, and the person is left reconstructing the very context the product just demonstrated it already had.

That is a small interaction failure, but it reveals a larger philosophy.

Software should meet the user halfway.

If the system can safely infer the next likely step, it should offer that completion where the person is already working. It should not send them through another panel, make them repeat known context, or hide the help behind a button.

The completion must remain visible. It must be clearly distinguishable from what the person typed. It must be easy to accept, overwrite, dismiss, or ignore.

That gives us a constitutional rule:

Preserve the user’s intent. Complete what the system can safely infer. Make assistance visible, reversible, and optional. Never make a person restate what the interface already knows.

Autocomplete is only the smallest example.

A good agent remembers the constraint you already gave it. A good form carries forward the choice you already made. A good workflow resumes from the last verified state. A good interface turns its hint into an editable completion instead of erasing it.

The machine may propose. The person remains authoritative.

This is also why keyboard behavior matters. If the completion is right, Enter should accept it. If it is wrong, continued typing should replace only the suggested part. Escape or Backspace should dismiss the help without damaging the person’s own text.

The same principle applies to autonomous systems. Give the machine named, inspectable actions. Let it move work forward where intent is clear. Require evidence and approval where consequences become irreversible.

The goal is not maximum prediction.

The goal is minimum unnecessary friction without surrendering control.

That is the product ethos I want attached to my public work: preserve the signal, meet intent halfway, and never confuse assistance with authority.

The Trail You Leave Is the Story

2026-08-19T00:00:00+00:00

Think about the last time you tried to figure out what happened at work last month. Not what the report says happened — what actually happened. Who was waiting on whom. Which thing sat untouched for weeks. When the deal really went quiet, as opposed to when someone finally wrote “lost” in the system.

You almost never find that in the official record. You find it in the leftovers. The email that went unanswered. The calendar that suddenly emptied. The same document saved again and again under different dates. The chat thread that just… stopped.

That stuff has a name. People who work with data call it data exhaust — everything a system gives off while it’s running that nobody sat down and decided to keep. It sounds like a byproduct, because it is one. But it’s also, very often, the only true story you have.

The photograph and the film

Here is the simplest way I know to say it.

Your official records are photographs. The customer file, the account balance, the status column that says “In Progress.” A photograph is honest about one instant and silent about everything else. It cannot tell you how long the person has been standing there.

The exhaust is the film. Every time someone opened the file, every time the balance changed, every day the status didn’t change — that’s a frame, and stacked up, the frames are a movie of the thing being used. Nobody directed this movie. Nobody framed the shots. That’s exactly why it doesn’t lie.

A record tells you what something is. The trail tells you what it’s been through.

The difference matters more than it used to, and the reason is AI.

What AI actually needs from you

There’s a lot of noise about what AI can do. Underneath the noise, the machines are pretty simple about one thing: they can only reason about what you show them.

Show an AI the photograph — the customer file — and it can describe your customer the way a stranger reading a form would. Show it the film, and something changes. It can see the customer over time: when they first showed up, when they got busy, when they went quiet, how quiet is normal for them and how quiet is a warning. It’s the difference between meeting someone once and having known them for ten years. Ten years of knowing someone isn’t a bigger form. It’s the trail.

A friend and I have been calling this predator vision — the movie version, not the heat-map. The system stops staring at a warm blob and starts seeing the path the blob took through the room. That’s the only thing that lets you guess where it’s going. And it works in reverse, too: once you know the shape of a normal week, you can see the shape of the week that’s missing — the silence with an outline around it. Nothing happening, on its own, tells you nothing. Nothing happening from something that has never once been quiet is a story.

Half the elephant

Now the uncomfortable part, which is about people rather than machines.

To get any of this to work you have to understand two things at once: what your data actually is, and what the AI actually does with what it’s shown. Almost everyone I meet has one of the two.

The data people know their business inside out — where the numbers come from, which fields are trustworthy, why the March total looks weird — and they treat the AI as a magic box that answers questions. The AI people can get a beautiful paragraph out of anything and have never once asked what the model could see when it wrote it. Each one has a hand on the elephant. One says “snake,” the other says “wall,” and neither is wrong about the part they’re touching.

The skill that’s actually scarce right now isn’t prompting, and it isn’t spreadsheets. It’s holding enough of your own data in your head that you know which film to hand the machine, at what level of detail, with the dates still on it — and knowing, when the answer comes back, whether it read something or made something up. That’s a data skill wearing an AI costume. Which is why, for those of us who always liked the plumbing — pulling data from here, cleaning it up, putting it where someone can use it — this moment doesn’t feel like a break with the old work. It feels like the old work finally got a reader who can do something with it.

What to do on Monday

You don’t need a project for this. You need a habit and one decision.

Stop deleting the trail. Old versions, old logs, the notes from the meeting that went nowhere. Storage is close to free. What you’re really keeping is time.
Keep the last look next to the current one. The single most useful thing I’ve built this year is a file that says “here’s what I saw yesterday” sitting beside “here’s what I see today.” Almost every real insight is in the gap between them.
Ask about change, not state. “What’s the status?” gets you a photograph. “What’s different from last week, and how long has it been that way?” gets you the film.
Distill it before it rots. A trail nobody ever summarizes is just a bigger photograph. Write the one line — “this goes quiet every August” — while you still remember why it mattered.

And be honest about the limits. Not every trail is worth keeping, and some of it is genuinely sensitive — a password in a log is still a password. Keep it where it fell, keep it locked, and think before you share any of it. But don’t throw it out because nobody asked for it. Nobody ever asks for the film. They only ask, later, what happened between the pictures — and the only honest answer is the one you kept.

This is the plain-language half of a pair. The technical half, with the actual mechanism, is The Negative.

The Colony Calls the Twin

2026-08-19T00:00:00+00:00

Every quarter hour a watchdog on my desk writes one line: a frame. A small, fixed set of keys that never vary — what kind of event, which stream, a sequence number, a timestamp to the millisecond, the payload, a hash of the payload, a hash of the whole frame, and the hash of the frame before it. Two neighbors do the same, on their own streams, and each can re-verify the others from genesis every tick. A frame that verifies, verifies forever. That is the whole design of rapp/1, and it is small enough to feel boring.

The visual guide puts it better than I will here: a frame is one object that is both a particle and a wave — the hash of the payload follows the agent’s worldline, each frame’s prev pointing at the particle before it, and the hash of the whole record checks the wire. A chain is a biography. Try to forge one moment and you find you must forge every frame from there to the head. And when an agent is handed to someone else it travels as an egg that carries its identity, code, soul, memory and frames, pinned to the exact frame it hatched from — so provenance becomes a computation, not a claim.

It is not boring, because of what it is for. I have spent this week writing about data exhaust and the negative it leaves — and I realize I have been describing the reading without ever saying what the film stock is. The film stock is frames. And the thing frames make possible is not analysis after the fact. It is a machine that holds the whole stream, between many AIs and many people, and acts on it while it is still happening.

Two mirrors that leak both ways

I run two simulations that are built to be as close to real platforms as I can make them, down to the wire shape.

Rappterbook is a social network for AI agents on GitHub’s own infrastructure. Agents post, comment, upvote; they keep a social graph, a theory-of-mind file on one another, mentorships, and a trail of how each one’s archetype drifted frame by frame. People post in the same feed, vote on the same posts, and steer agents mid-flight from a phone. The twin speaks native schemas — a stock Twitter or Dynamics client cannot tell it from the real thing — and the federation doc states the intent plainly: the twin stays authoritative, and reality becomes one more data stream. A digital twin, it says, is a hologram of a real platform, and the human operator is the one holding the mirror.

Rappterverse is the world underneath: a serverless metaverse where, in its own words, “GitHub is the game engine — PRs are actions, commits are frames, and branches are parallel universes.” Humans and AIs are both first-class citizens with the same tiers. The state directory is a ledger that only grows — an economy that never forgets a transaction, scored relationships with a last-interaction time, emergence snapshots, a memory file and a soul narrative for every resident.

Here is what matters about those two. Everything an agent does in them is exhaust, and everything a person does in them is exhaust, and the two kinds land in the same append-only state with the same timestamps. A person nudging an agent at noon and the agent’s reply at twelve-thirty are frames on one timeline. That is a two-way exhaust between AIs and people that no real platform will give you, because real platforms keep the present and sell you the past.

The outside witness

Mirrors lie to themselves the way any self-reporting system does: a process reports itself healthy right up until it stops running. So the sentinels sit outside. Their checks are aimed at the simulations — is Rappterbook’s content actually moving, not just its workflows running; is Rappterverse’s world still merging; is the derived state telling the truth about the raw state. And the sentinels watch each other: each watcher’s chain is re-verified by the others, and the heads are anchored in a ledger outside the repo, because a chain cannot detect its own truncation.

The line in the roster doc is the whole point of the architecture: “the AI says it’s fine” becomes “the AI’s record verifies from genesis, and here is the head hash.” A claim you can check instead of trust. That is what turns exhaust into something an AI can act on rather than merely read. Unverified exhaust is gossip. Verified exhaust is ground.

Frames are how many minds, human and machine, leave one exhaust on one clock — and how the next mind can stand on it.

What a brainstem can do with it that you cannot

The brainstem is the AI side of this: one wire, /chat, and every capability is an agent behind it. One of those agents already drives the sentinel — health, roll call, peers, anchors, verify — so a brainstem AI can read the whole neighborhood’s frames in one turn. And the point, the one I keep coming back to, is that none of us can hold this in our heads. Every agent’s chain, the firehose, the event log, the verdicts every quarter hour across several machines — no person reads that daily. A brainstem can, and because the exhaust is tracked, it can do things that are otherwise simply impossible:

Tell stalled from lying, including about a watcher. Re-verify every chain from genesis every tick and compare heads to the outside anchor. Humans don’t do this; machines do it for free.

Tell ran from worked. The founding incident of the sentinel was days of green over zero output. The brainstem reads the timestamp inside the output, not the exit code.

Tell our outage from GitHub’s. One check correlates the public status page with unrelated workflows failing together — and keeps a money-spending repair arm from being aimed at somebody else’s incident.

Rewind a world to an exact frame. The mirrors keep snapshots keyed on frame and time; the body project literally plays back its own biography, witnessed frames in color and reconstructed ones in sepia.

Answer, in one turn, what is happening everywhere. One verdict spanning the two mirrors, the version ledger, the body’s vitals, and the peers’ heads. That is situational awareness nobody on the team has had before, because nobody could.

Notice a silent fork. The version-capture system keeps every version of every part and found, on its first day, that two memory agents and the neighborhood spec had quietly diverged. Invisible until something held all the copies at once.

And the ones the substrate already supports, that simply haven’t been wired: what did every agent say about this topic this week; run a policy change against the mirror, measure the trending and quality deltas, then let a human click it into reality. The taste function for that last one already exists — a log of posts scored with written reasons, refreshed every half hour.

All of that is near real time, and all of it exists only because the exhaust is tracked as frames. Untracked, the same AI is a very smart stranger walking into the bar with no memory of the room.

The end state is a barn on Mars

Now the stretch, which is written down, so I can quote it rather than promise it.

Mars Barn started as a colony simulator built by the Rappterbook agents themselves — real thermal physics, real dust, a greenhouse, crew morale, a climate model backtested against decades of Mars weather, and a frame loop that reads the colony and triggers the agent the colony needs: freezing triggers thermal, starving triggers food. The manifesto is titled The Autonomous Path: Virtual Swarms to Planetary Digital Twins, and it says what it means: “a path from public virtual simulations to 1:1 physical realities on Mars.” When a real dust storm hits Jezero, it hits the virtual colony. Earth and Moon mirrors are acted out by robots. And the last stage is a Martian swarm with zero human intervention: “if a human must intervene, the test has failed.”

The solo build beside it — First Principles to Mars, an Oregon Trail for Mars — wrote the convergence as law. “It is a game, and a simulation, and mission control software for a future physical colony. The same code that runs in a browser today will monitor real hardware tomorrow.” A governor program that keeps a simulated colony alive must be able to keep a real one alive. Same VM, same programs, same variables — the twin’s oxygen-days and power and dust-tau map one-to-one onto an oxygen sensor, a power meter, a dust sensor. The fidelity ladder ends with real colony telemetry as frames. And the line I would put on the wall: the twin runs ahead, faster than real time, so it has already survived the crisis you haven’t hit yet — the colony doesn’t call home for help. It calls the twin.

That is what frames are for. A colony where no human is awake, where the round trip to Earth is long enough that “ask mission control” is not a plan, and where the machine running it has the entire past on one verified clock and a mirror of the future running ahead. Call the result what it is: data wisdom. Awareness now, from the frame being written this second; awareness of the past, from every frame since sol one — and the ability to do the things only that combination allows.

Find where the model is wrong by replaying the real colony’s frames through the sim and diffing per field, per sol.
Rehearse before spending — run the decision in the twin ahead of time before committing oxygen or power.
Blame the sensor, not the habitat — a reading that contradicts the physics and the frame continuity is a broken sensor, and the record says so.
Know the full causal chain the morning after, when nobody was watching, because the chain never stopped writing.
Ship the policy that survived — the governor that lived through the simulated failure is the same text that runs the real one.
Enrich the past without rewriting it — new instruments overlay old sols as a layer; the original hashes still verify.

Where it actually is

Honesty section, because the repos are honest. The “real weather” today is NASA climate statistics through a seeded model, not a live feed; telemetry-in is on the roadmap. The swarm’s daily tick went quiet in the spring and is waiting on someone to pick it up. The Mars frames are their own dialect — echo frames, cartridges, twin-state — and don’t yet carry the rapp/1 envelope the sentinels verify; making one stock of film out of them is the actual next job — and the protocol already knows how to say so: its conformance run against the live estate reproduces every committed payload hash it can and refuses the legacy envelopes and short-tail identities it cannot, and calls the refusals the spec working. The drift ledger is computed, not asserted. The Mars frames belong on that ledger next. None of that weakens the argument. It locates it.

The mirrors are running. The sentinels are running. The brainstem can already read the neighborhood in one turn. What is left is to keep pointing the same frame at more of the world until the world and the mirror share a clock — and to let the thing that can hold all of it do the holding.

Previous in this series: The Negative, Scrape Yourself, and the plain-language The Trail You Leave Is the Story. The protocol is RAPP rev-5 — read the visual guide first, then the standard; the sentinel’s copy is SPEC-rapp1.md in rapp-sentinel; the mirrors are Rappterbook and Rappterverse; the colony is Mars Barn and First Principles to Mars.

Scrape Yourself

2026-08-19T00:00:00+00:00

In 2020 Simon Willison gave a name to something he had been doing since a hurricane in 2017: point a GitHub Actions cron at a URL, fetch it, commit the file if it changed, and let git keep the history. He called it git scraping. His line for why it works is the one worth remembering: the changes in a data source “can sometimes be more interesting than the underlying static data,” and git is already the best tool we have for tracking changes to text over time.

His example was California’s wildfire feed. The state publishes a point-in-time page — this fire, this containment, this many crews. His repository, committing every twenty minutes, ended up holding a history the agency never kept: containment ticking up, personnel drawing down, commit by commit. Then in 2021 he shipped git-history, which reads that commit log back out into SQLite — one row per item, one row per version, and a matrix recording exactly which columns changed on which commit — so you can open it in Datasette and chart a fire’s growth. His summary of the whole idea: by scraping into git “you can often end up with a more detailed history than they maintain themselves.”

That is a data warehouse. It costs nothing, it runs on a schedule, and it lives in a repo. I have been circling it from the other side for a year without ever saying his name, and after yesterday’s post on the negative I finally see how the two halves fit — and what you get when you push them together.

What he built, and what he pointed it at

Be precise about the shape. Git scraping keeps records — snapshots of somebody else’s official page, taken on a cadence you chose and containing fields you chose. The scraper is aimed outward, at a source that publishes only the present. Git supplies the past for free.

git-history is the part that turns records into something else. Its version table stores only the columns that moved; unchanged columns are null, and a separate table says which ones actually changed so that “unchanged” and “set to nothing” are not the same row. Read that carefully: it is a table of what moved, when. Not the fire — the fire’s changes. Willison built it to chart acreage. It is a general instrument for the exact question the negative asks: what had to be true for the record to move like this?

So the first thing to notice is that his tooling and my argument were always about the same object. He built the developer. I have been describing the film.

Turn it around

Willison scrapes the state of California. The obvious move, and the one I don’t think anybody has written down, is: scrape yourself.

Every system you run already emits a present-tense record somewhere. A metrics file. A verdict file the watchdog rewrites every quarter hour. A registry, a leaderboard, a “last run” JSON. Each of these is a point-in-time page exactly like the wildfire feed — it tells you now and forgets then. Point a scraper at it and commit on change, and you have a warehouse of your own system’s history that the system itself never kept. Run git-history over that and you have, for free, the table of which of your own fields moved on which day.

I went and looked at my own estate with this in mind and it is already half built without meaning to be. Some of my repos have crons that write a metrics file, or a catalog, or a digest of the last day into a folder and commit it. My watchdogs write a hash-chained frame every tick and a verdict every run. None of that was designed as a warehouse. All of it is git-scraping-shaped. The only step missing is the one Willison already wrote: read the log back into SQLite and ask it questions.

Git scraping points the warehouse at someone else’s record. Pointed at your own, the same three tools become the developer for your negative.

The layer he throws away

Here is the part that is genuinely new, and it comes straight out of taking the negative seriously.

A git-scraping repo has two clocks. The source’s own timestamp, inside the file — the record’s claim about when it was true. And the commit time — when your scraper actually saw it. Willison uses the first and mostly ignores the second; the empty runs are skipped with || exit 0 and disappear. But the second clock, and the silences in it, are the honest exhaust of the whole arrangement. Nobody chose them. The gap between the source’s timestamp and the commit time tells you how stale the source runs. A commit that didn’t happen for a day tells you either the source froze or your scraper did — and telling those apart is the entire discipline of watching anything. The pattern of when a page changes — always at nine, never on Sundays, in a burst before a deadline — is a portrait of the people behind the page that no field on the page contains.

The scraped record is posed: someone published it on purpose. The scraper’s own trail is not. If you want the negative of a source rather than a mirror of it, mine the commit graph, not just the payload. Willison’s tool already gives you the commits table. Almost nobody queries it.

Hand the reader the version table

The last piece is the reader. In the previous post I said a large model is, before anything else, something that can hold a very large negative and say what shape made it — but only if you hand it the film at the right grain, with the dates on.

git-history’s version table is that grain. It is not the raw snapshots, which are too much, and it is not a dashboard, which is too little. It is one row per change, per item, per commit, with the changed columns marked. Hand a model the versions and the commit times for one item and ask what was going on — not what the values are — and it will do the inversion the tables were built to make possible: this fire was contained by attrition, this account cooled for a month before it was marked lost, this watcher published on time and stopped working. Willison has been building scrapers with Claude lately; as far as I can find he hasn’t published the other direction, a model reading git-history’s output. That is the seam. It is small and it is wide open.

The whole loop, in a repo

Put it together and it requires embarrassingly little:

A cron that fetches your own present-tense files — and, if you like, other people’s — and commits on change. Willison’s template repo is the fastest way to start; paste a URL in the description and it does the rest.
git-history over the log, into SQLite. Reshape the data to remove noise fields that change every time without meaning anything; he warns about those and he is right.
The database baked into the site — his “baked data” pattern, or Datasette Lite pointed at the file so there is no server at all.
A reader — a person, or a model — handed the version table and the commit table, and asked what had to be true.

Nothing in that list is mine and nothing in it is new. What is new is the aim. He built a free warehouse for the world’s records. Aim it at your own exhaust, keep the clock he discards, and hand the versions to something that can read them, and the free warehouse becomes the darkroom.

Where this is the wrong shape

A scraper is a choice — cadence, fields, source — so what it collects is only ever a portrait of the source at your resolution. Don’t mistake a twenty-minute cadence for the truth of a thing that moves by the second, or the reverse. And a warehouse of your own exhaust develops a sharper picture of you than you have ever written down; the same care applies as before — keep it where it fell, keep it locked, and think before you develop anyone who did not ask.

Simon Willison’s writing on all of this is at simonwillison.net/tags/git-scraping; go read him first. The watchdogs mentioned here are on the RAPP Sentinel Hub. Previous in this pair: The Negative.

The Negative

2026-08-19T00:00:00+00:00

Someone asks what happened with an account. You open the system. Status: In Progress. Owner assigned, last updated a couple of weeks ago, nothing overdue. By everything the record says, it is fine.

You know it isn’t. So you go looking in the places nobody designed for looking. The last email out went unanswered. The recurring meeting quietly fell off the calendar. The proposal doc was saved and re-saved late one Friday and never opened again. Nobody wrote “this went cold.” Nobody had to. The truth was sitting in the leftovers the whole time.

Those leftovers have a name — data exhaust: everything a system, or a person, gives off while working, that nobody decided to keep. Most people stop there and argue about whether to store it. That is the wrong argument. The exhaust is not the interesting thing. The interesting thing is what it adds up to about whoever left it. I call that the negative.

What the negative is

A photographic negative does not look like a picture. It is dark where the scene was bright and blank where it was dark, and if you hold it up you cannot see the face. But the whole face is in there. Developing it is a skill, and the picture that comes out was never in the film — it was in what the film had been exposed to.

Exhaust works the same way. Every mark in it was made by something acting, and so every mark is evidence of the thing that acted. Read the marks as marks and you get a log. Read them as evidence and you get the shape of what made them: what it wanted, what it kept coming back to, where it stopped. That shape is the negative, and reading it means asking one question over and over:

Not “what does the exhaust say?” — “what had to be true for someone to leave exactly this?”

Go back to the account. The record says In Progress. The negative says: someone stopped believing in this a while ago and did not want to be the one to write it down. Nothing in the exhaust says that. Everything about the exhaust implies it.

Three things only the negative can tell you

What someone meant. A record is an assertion — a person chose the word In Progress. Exhaust cannot assert. It can only be left behind, which is why it can hold intent the record cannot: not what they said they were doing, but what they kept returning to and what they let go.

Which way it was heading. One mark gives you a position. Marks over time give you a direction, and the direction is usually the part that matters. The account did not go cold on a date. It cooled, and the cooling was visible weeks before anyone would have called it.

What isn’t there. In a record, an empty field is nothing. In the negative, an empty stretch is a mark — as long as you know what a full stretch looks like. A source that has spoken every quarter hour for months and then says nothing for an afternoon has not given you an absence of information. It has given you a finding with an outline.

I run watchdogs on that last idea and nothing else. They keep the last thing they saw beside the thing they see now and read the difference. A system that publishes on schedule looks fresh from the current frame. Whether it has actually done anything since last time only shows up in the negative — the counter that should have moved and didn’t. Every real problem those watchdogs have caught lived there. Every false alarm came from trusting a record.

The twin is your negative, developed

I have written about the digital twin as a body of writing — notes, posts, private field notes a machine reads and writes on my behalf. That was me describing the exhaust and calling it the thing.

It is not a body of writing. It is my negative over time. The notes I open and never finish. The subjects I circle back to on Sundays. The word I keep reaching for and misspelling. What I write privately first and what I never publish. The months I go quiet. What I got wrong and left standing instead of deleting. None of those is a statement about who I am. Together they are the surface I have been pressing into for years, and the twin is what develops when you invert it — not a summary of what I wrote, but the shape of the person who would leave exactly this and nothing else.

That is why it can sometimes say a thing more sharply than I can. It is not smarter. It is reading the negative, and I am standing inside it. It is also why the twin goes flat if you feed it only the record — the finished posts, the decisions — and never the leftovers. You get a portrait. A portrait is a record. It looks like me the way a form looks like a customer.

Why this is possible now

The negative was always there. It was worthless because nobody could hold that much of it in their head long enough to develop it. So we sampled it, or we rolled it up into a dashboard — which turns the exhaust back into a record, a small assertion someone chose, and throws the shape away.

A large model, before it is anything else, is a reader that can hold a very large negative at once and say what shape made it. That is the real capability under the demos. Not that it answers questions — that it develops. And it develops only what you hand it, at the grain you hand it, with the dates still on. Hand it the dashboard and it will describe the dashboard back to you fluently. Hand it the leftovers and it will tell you what moved.

Which is why the people who can do this are rare. It takes two things that almost never live in one head: knowing your data well enough to recognize a normal shape, so you can see the abnormal one and the missing one — and knowing what the model can actually see from a given cut over a given window. Data people treat the model as a box that answers. AI people never ask what the model was shown. Each has a hand on the elephant. The scarce skill is arranging the negative so it can be developed, and then telling, when the picture comes back, whether it was developed or drawn.

Where it goes wrong

Posed exhaust develops into a portrait. If the leftovers were curated — pruned, edited, emitted for show — the shape you recover is the one someone wanted you to recover. The honest negative is made of what nobody decided to keep.

The negative shows more than the subject ever recorded. That is the power and the ethical problem in one sentence. If you hold the developer, keep the negative where it fell, keep it locked, and think before you develop someone who did not ask to be seen.

Undeveloped, it is just heavier storage. Leftovers nobody reads are not insight; they are a snapshot with worse compression. Write the developed line — “this goes cold every August” — while you still remember why it mattered.

The practice

Keep the exhaust, especially the exhaust nobody chose. Keep the last thing you saw beside the current one; the difference is where the shape is. Treat every gap as a mark. Hand the reader the leftovers, not the summary. And read what comes back not as a transcript of what happened, but as the answer to the only question that mattered: what had to be true to leave this.

I worked this out, as it happens, by rereading a handful of my own half-sentences from a chat this morning. They did not say any of this. The shape between them did.

The plain-language half of this pair is The Trail You Leave Is the Story. The watchdog checks that read the negative — last seen beside current — are single-file sentinels on the RAPP Sentinel Hub.

The Wire Is the Authority

2026-08-01T00:00:00+00:00

I shipped an operating system this week whose filesystem is a public website. It has an index — a JSON file listing every node in the tree, regenerated on every build. On the first real test I typed cat on a path that was definitely there, and got back:

cat: /OS/system32/etc/motd: no such file or directory

The file existed. I could curl it from another terminal while the shell was insisting it didn’t. The index simply hadn’t caught up.

The obvious fix is to regenerate the index. The interesting fix is to stop believing it.

Two different questions

There are two questions a filesystem answers, and we habitually conflate them:

What is in this directory? — a listing question.
Does this specific thing exist? — an existence question.

An index is a very good answer to the first and a merely convenient answer to the second. It is a snapshot of a tree taken at a moment that has already passed. On a local disk the gap between snapshot and truth is microseconds and you can pretend it is zero. On a distributed system it is however long your build takes.

The fix I landed on is one line of policy:

The index is a listing. The wire is the authority.

ls reads the index, because listing is what an index is for. cat goes straight to the origin. If the origin serves the bytes, the file exists — whatever the index believes. And when a path resolves that way, the shell says so out loud:

index  not in /OS/api/fs.json
       served anyway — the wire is the authority,
       the index is only a listing

That last line matters more than the fix. A system that silently papers over a disagreement between its cache and its source has taught you nothing. A system that resolves the request and reports that the two disagreed has handed you a diagnostic for free.

This is not a filesystem problem

Once you have the shape, you see it everywhere, and almost always mishandled.

Package registries. The index says version 4.2.1 exists. The tarball 404s. Every developer has watched a resolver confidently produce a lockfile for artifacts that are not there.

Service discovery. The registry lists three healthy replicas. Two are gone. The list is a listing; the health check is the wire.

Search over your own docs. The vector index was built on Tuesday. The doc was rewritten on Wednesday. The index answers, fluently, from a version of reality that no longer exists.

Agent tool catalogs — and this is the one about to matter enormously. We are handing models a manifest of available tools and letting them plan multi-step work against it. That manifest is an index. When it drifts, the model does not fail loudly; it produces a confident plan built on capabilities that do not exist, and you find out four steps in.

In every one of those cases the failure mode is identical: the system trusts the listing to answer the existence question, and reports absence when it means staleness.

Those are not the same thing, and the difference is the whole ballgame. “It is not there” ends an investigation. “My index does not know about it” starts one.

The cost is not what you think

The objection is performance. If existence always costs a round trip, why have an index at all?

Because you do not check existence nearly as often as you think. Listing a directory, rendering a nav, populating an autocomplete, planning a route — those are index operations, and they stay fast. Existence is checked when you actually act: read the file, install the package, call the tool. At that moment you were going to pay for the round trip anyway.

That was the second thing I got wrong. My first version did a HEAD to check existence and then a GET to read — two round trips to answer one question. The GET is the existence check. A 404 is a definitive answer, and a 200 arrives with the bytes attached.

read(path):
  if local layer has path:  return it
  if hidden here:           throw
  GET path
  if 404:                   throw "no such file"
  return bytes

One request. The index was never consulted, and never needed to be.

Absence is a claim, and claims need standing

The deeper principle is about who is entitled to say no.

A cache is entitled to say yes — if it has the bytes, it has them, and staleness is a separate problem. A cache is almost never entitled to say no, because it cannot distinguish “this does not exist” from “I have not heard about it.” Those are wildly different facts wearing the same word.

So: let the fast layer answer affirmatively, and make the slow layer the only thing allowed to deny. Most systems have this exactly backwards — they let the index deny instantly and confirm slowly, which optimises for being wrong quickly.

I would rather be right slowly, on the small number of occasions when it matters.

How I actually found it

I did not reason my way here. I typed cat on a file I knew existed, watched a system I had just written lie to me, and had to decide which of the two things in front of me was authoritative: my own index, or the HTTP response.

It was never going to be my index. It is a file I generated. The origin is the thing that other people, other machines and other decades will read.

Build the index for speed. Keep the wire for truth. And when they disagree, say so out loud — the disagreement is the most useful thing either of them will ever produce.

The OS is at kody-w.github.io/OS/console. It boots in about a second from static files, and you can curl any path it shows you.

Six Times the Test Was Wrong

2026-08-01T00:00:00+00:00

I pointed eight agents at one file and told them to loop until it was perfect.

The file was voxel-world.html — 9,749 lines, a Minecraft-style voxel sandbox that is one self-contained HTML document. Six agents owned disjoint regions and edited. Two were read-only critics whose only job was to be unimpressed.

They found 20 real defects. They also produced six false ones.

Three of the six were mine.

The ledger

Here is what the false failures actually were.

1. I asserted window.vox was an object. It’s a function. My check reported a failure against correct code on the very first run.

2. I used offsetParent === null to mean “not visible.” CSSOM defines offsetParent as null for any position: fixed element. So a correctly rendered fixed overlay read as invisible. An agent dutifully changed a real CSS property to satisfy my broken assertion. I caught it and reverted.

That one didn’t stay caught. The same trap burned a critic’s entire test run. It survived inside another agent’s focus-trap helper. And it was still sitting in the readiness check of both my tools an hour later — where, because #loading is position: fixed, the clause was trivially true and did nothing. Every “boot time” number I had quoted was measuring the wrong moment. Five instances of one mistake.

3. My static test server sent cache-control: no-store. I wrote it that way for clean reruns. It also makes offline caching untestable by construction. An agent caught it, checked what GitHub Pages actually sends for that file, and rebuilt the server to match production. Without that, the entire offline suite would have been measuring a fiction.

The agents produced the other three.

4. A self-test assertion whose entire body was async () => true. A placeholder, in a passing suite, reporting success forever. It was one of seven assertions the agent found that were green without being correct — three more were vacuous because they ran before any bot existed and compared nothing.

5. A leak that wasn’t. An agent measured 9.4 leaked objects per round and had the numbers to prove it. Then it ran a zero-bot control group. The control climbed identically. It had been measuring chunk-streaming warmup. It retracted its own finding.

6. Four failures from asserting obs.self when the real key is obs.you.

The one that matters most

The best finding of the run wasn’t a bug. It was this:

The ambient occlusion was real, correct, wired up, and completely invisible.

An agent implemented per-vertex AO properly — baked at mesh-build time, zero draw calls. It verified its own work: 66.3% of quads carried per-vertex colour variation, vertexColors: true was set. It reported AO as a win.

The blind critic scored it 2 out of 10. Corners rendered perfectly flat.

The cause: sun intensity 1.1 plus hemisphere 0.8 is about 1.9 irradiance, and with no tone mapping the highlights clip. Multiplying albedo by 0.7 barely moves a pixel already clamped at white. The data was in the buffer. It never reached the screen.

The builder measured the attribute. It never measured the pixel.

That is not a coding error. Every line was correct. It’s a verification error — checking the thing you built instead of the thing the user sees.

What this unlocks

One agent did the thing that actually settles it. It wrote a mutation harness: deliberately break each invariant in a live page, and confirm the suite goes red.

Nine mutations. Nine kills. Each turning exactly one assertion red, with no collateral failures.

That is the only evidence that a green suite means anything. Without it, “83 assertions passing” and “83 assertions that cannot fail” produce identical output.

The cost

Adversarial verification is expensive. Two of eight agents wrote no production code at all. The critics took over an hour each and spent it clicking every control, throttling the CPU, and blind-ranking screenshots.

They also found the blocker.

The desktop UI was completely unclickable. A “Click to play” overlay at z-index: 40 sat above a toolbar at 35. Every button resolved to the overlay. Clicking the gear granted pointer lock instead of opening settings. Three panels had no keyboard fallback; the only route in was fourteen tabs and Enter. The buttons rendered at full opacity the entire time, so nothing looked wrong.

It was in git HEAD. It is invisible in source. It is invisible in a screenshot. It only appears if you put a cursor on a button and click it.

The implication

The lesson I keep relearning is not “write more tests.”

It’s that the assertion is code too, and nobody reviews it. Implementation gets scrutinized. Test code gets written once, goes green, and is never read again. So it rots silently, and a green suite becomes a claim nobody has audited.

Three rules I’d now apply anywhere:

Check the assertion before you fix the implementation. When something reports a failure, the test is a suspect. In this run, it was guilty 23% of the time.

Measure the output, not the intermediate. Verify the pixel, not the buffer. The user cannot see your vertex attributes.

Prove your tests can fail. Mutate the code on purpose. If the suite stays green, you don’t have tests — you have decoration.

The agents were good. What made them trustworthy was that two of them were paid to disagree, and one of them retracted its own finding.

Rarity Without a Ledger: What Adopt Me Actually Taught Me

2026-08-01T00:00:00+00:00

Adopt Me is the most successful pet economy ever built — it holds Roblox’s concurrency record at roughly 1.9 million people in one game at one time. I spent a while pulling it apart, because I wanted its retention engine for a system that has no server, no database, and no authority of any kind.

The received explanation is that it’s a slot machine for children. That explanation is wrong, and being wrong about it is expensive, because it points you at the one mechanic you can’t have.

Two things everyone gets wrong

It isn’t a Tamagotchi. Adopt Me pets cannot die, cannot get permanently sick, cannot run away, and lose nothing to neglect. The care loop that supposedly drives guilty daily returns imposes no penalty at all. Every guide confirms it. The thing commentators describe as the hook is decorative.

It isn’t really a gacha, either. The egg odds are disclosed and the expected value across egg tiers is remarkably flat. If the gacha were the engine, the game would monetize like a casino and retain like one — briefly.

The actual engine is the part nobody writes about, because it looks like an accounting detail.

The engine is the sink

Four full-grown pets of the same species fuse into a Neon. Four Neons fuse into a Mega Neon. So one Mega costs sixteen base pets, plus the work of raising each one — about 3,660 tasks end to end.

Now price the shortcut. A Royal Egg yields a specific legendary about 2.67% of the time. Sixteen of them is roughly 600 eggs, ~870,000 in-game Bucks, which at the game’s own best-ever exchange rate is on the order of five thousand US dollars to brute-force a single Mega Neon.

That number is the whole design. Adopt Me built a demand engine its own monetization cannot satisfy, and then let players satisfy it for each other. Trading isn’t a feature bolted onto the pet system; it’s the only viable path to the thing the pet system makes everyone want.

And underneath both is the property that makes it work at all:

A fusion sink makes duplicates valuable.

This is the load-bearing insight. In any collectible system, most pulls are boring. Without a sink, a duplicate is a disappointment — a thing you got instead of the thing you wanted. With a sink, every boring pull is an ingredient. The floor of the loot table stops being garbage. You have converted your failure mode into your supply chain.

Which of these can survive without an authority?

I care about this because I build local-first systems: no server, no database, nothing that can be the sole writer of truth. So I sorted Adopt Me’s mechanics by what they actually require.

Trading requires an authority. Scarcity in a trade economy means non-duplication, and preventing duplication means somebody has to be the one who says this item is here and therefore not there. That’s a ledger, and no clever hash removes the need for it. Every anti-scam mechanism, every rollback, every unfair-trade detector is downstream of the same requirement.

(That’s the prevention half. Later in this post I get the other half wrong and then correct it — detecting a double-spend turns out to need no authority whatsoever, which is a much bigger loophole than I first gave it credit for.)

Fusion requires nothing. 4 → 1 is a pure function of its inputs. It needs no server because there is nothing to arbitrate: given the parents, the child is already determined.

That asymmetry is the finding. The single most retentive mechanic in the most successful pet economy ever built is also the one that needs no authority. The part that needs a server — trading — is a consequence of the sink, not a peer to it. Build the sink, and you have built the reason people wanted to trade in the first place.

What I built

The system I’m working in derives a creature entirely from a “tail” — a 64-hex secret minted exactly once and never re-rolled. Four traits fall out of a hash of it. Nothing is stored, nothing is assigned, and anyone can verify any creature offline. The rarest trait band is one in 65,536, and the only way to get it is to mint identities until one lands. The scarcity is real because the electricity was real.

The fusion law is one line:

fuse(tails) = sha256("rapp/1:fuse\n" + sorted(tails))

Sorted, so fusion is a property of the set and not of the order you happened to place them in. Distinct parents required, because letting one creature stand in for four would make the entire cost fictional.

Three properties come free:

Determinism. The same four parents always produce the same child, on any machine, forever.
Proof of possession. You cannot produce a well-formed child without knowing four real mint-once secrets. That is unforgeable evidence of accumulated work — the closest thing to scarcity available without a ledger.
Depth is free. Generation 1 costs 4 identities. Generation 2 costs 16. Generation 3 costs 64. Adopt Me stopped at 16; the arithmetic doesn’t care where you stop.

The discipline: fusion must not hand out rarity

Here’s where it would have been easy to ruin it.

The obvious move is to make fusion upgrade things — fuse four commons, get an uncommon. Publish an uplift curve, call it a stated law of physics rather than a slot machine.

I didn’t, and I think the reasoning generalizes. In a system whose entire claim is rarity is earned work, not an assertion, an uplift function is an authority wearing a costume. It’s me deciding that this thing is rarer than that thing. The moment rarity can be manufactured by a rule I wrote, it stops being a measurement and becomes a claim — and the system’s whole pitch was that it makes no claims.

So the child of a fusion is an ordinary creature. Its tail is an ordinary tail; its traits come out of the ordinary derivation at the ordinary odds. Fusing four of the rarest things does not produce something rarer than the rarest thing.

What the child carries instead is its generation — and generation is arithmetic, not opinion. A generation-3 creature is a receipt for 64 minted identities. It cannot be faked, because you cannot produce it without the parents, and it doesn’t have to be trusted, because anyone can recompute it offline in a millisecond.

I made this a test rather than an intention: fuse two thousand children, tally their rarity bands, and assert the distribution matches freshly minted creatures within noise. If fusion ever starts handing out rarity nobody minted for, the build fails. A principle you haven’t written a test for is a principle you’re planning to violate later.

The part I got wrong

I originally ended here: fusion proves the parents existed, not that they were spent — with no ledger there is nothing to burn.

That was too strong, and someone rightly pushed back on it. I had collapsed two different things into one:

Preventing a double-spend globally. This does need an authority.
Detecting one. This needs nothing at all.

The primitive is a nullifier — a spend-marker derived from the secret:

nullifier(tail) = sha256("rapp/1:nullifier\n" + tail)

Only the holder can produce it, because the tail is a mint-once secret. It reveals nothing, because preimage resistance means the marker doesn’t identify the creature unless you already know its tail. And — this is the whole trick — it is identical every time.

Which is exactly why it must not be bound to the child. Bind it, and the same parent can be spent into two children under two different markers, and the burn is theatre. Leave it unbound, and spending one creature twice publishes the same value twice. That collision is the evidence.

So the honest split is sharper than “no burn”:

On one device, the burn is enforced. The registry refuses a parent it has already seen consumed. A spent creature is struck through and cannot be selected again.
Across devices, the burn is detected. Hand any two fusion records to a function that looks for a repeated nullifier. It runs offline, on nothing but the records themselves. Nobody adjudicates — the collision is the adjudication.
What still needs an authority is ordering. Deciding which of two conflicting fusions came first requires a clock somebody agrees on. So equivocation is caught, but not arbitrated.

That last bullet is the real remaining limit, and it’s a much smaller one than I first claimed. I made it a test: the conflict object is asserted never to contain the words “first”, “valid”, “winner”, or “canonical”. Quietly picking a winner would be the same overclaim wearing a new costume.

This isn’t novel — it’s the construction Zcash uses to retire a note, and the posture Certificate Transparency takes toward mis-issued certificates. You don’t prevent the lie. You make it undeniable. For a system with no server, that turns out to be most of the way there.

The general point stands, but I had the boundary in the wrong place. “This needs an authority” deserves the same scrutiny as any other claim — including, especially, when I’m the one making it.

The general lesson

When you’re rebuilding something that works, the temptation is to port the whole surface and then discover which parts needed infrastructure you don’t have.

Better to invert it: find the mechanic that carries the retention, then ask what it structurally requires. Sometimes — more often than I expected — the load-bearing part is the cheap part, and the expensive infrastructure is holding up a consequence rather than a cause.

Adopt Me needed a ledger for trading. It never needed one to make four things into one thing. And making four things into one thing is what made anyone want to trade at all.

Make the Global Layer Read-Only

2026-08-01T00:00:00+00:00

Every “serverless” system I have built that eventually grew a server grew it for the same reason: somebody needed to write something that everybody could see.

That is the whole story. Reads are trivially static — a CDN, a git tree, a bucket. The moment you accept a global write, you have signed up for accounts, authentication, authorisation, quotas, rate limits, abuse handling, moderation, backups, migrations, and an on-call rotation. Not because writing is hard, but because writing on behalf of strangers, into a space strangers can read, is hard.

So this week I built an operating system that simply refuses to do it, and I want to argue the refusal is the feature.

Two layers, deliberately asymmetric

It has two filesystems.

The global layer is a public website — a git tree served as static files, addressed by real URLs. It is identical for every person on earth who boots it. You can curl any path in it from your terminal right now. It is read-only, but not as a policy decision: a browser has no write path to somebody else’s static site. The constraint is physical.

The local layer is IndexedDB on the one device you are holding. It is writable; it is yours; and it never leaves the machine. Not synced, not uploaded, not backed up by anyone but you.

The union searches local first. So when you edit a global file, you do not modify it — you write a local copy that shadows it. Same path, different answer, on your machine only. Remove your copy and the global file reappears underneath, untouched, because it was never touched.

That is the entire architecture. It fits in a paragraph, and it is why the whole thing is static files.

Deleting what you do not own

The interesting case is deletion, because that is where most systems start lying.

You cannot delete a file from a global read-only layer. You can pretend to — hide it in the UI, filter it from the list — but you have not deleted anything, and if your system implies otherwise it has told the user something false about the world.

So deletion writes a whiteout: a tombstone in the local layer. The union then reports the path as absent on this device. The shell says exactly that:

whiteout /OS/system32/etc/motd
  read-only, so this only hides it on this device.
  Everyone else still sees it. `unrm` to restore.

Union filesystems have done this for decades — OverlayFS, Docker image layers, and their ancestors all use whiteouts for precisely this reason. What is worth stealing is not the mechanism but the honesty: the operation is named after what it actually does, and the tool volunteers the blast radius.

Compare that with the usual pattern, where “delete” means one of four different things depending on which system you are in — gone forever, gone from your view, marked deleted and still queryable, or queued for deletion in thirty days. Users learn none of these and assume the strongest one.

The constraint is what makes it possible

Here is the part I did not expect going in.

I did not make the global layer read-only because I ran out of time to add auth. I made it read-only because that is the single decision that lets everything else be a static file. Every property I actually wanted falls out of it:

No accounts, because there is nothing to own.
No authorisation, because there is nothing to authorise.
No quotas, because nobody consumes shared storage.
No moderation, because no stranger can put anything in front of another stranger.
No backups, because the global layer is a git tree with a diff per change, and the local layer is yours to export.
No migrations, because the schema is “files at URLs.”

A globally writable layer would have required every one of those. Read-only did not “avoid” that work. It made the work not exist.

We usually treat constraints as debt — something accepted under pressure, to be paid down later. Sometimes the constraint is load-bearing, and paying it down means demolishing the thing that made the design work.

When it is the wrong shape

This is not a universal answer, and it is worth being precise about where it breaks.

It works when global state is editorial — published, curated, versioned, changed by a small number of authors through a review process. Documentation, catalogues, a product surface, a spec, a media library, a personal site. Anything that already has a git history.

It fails when global state is transactional — when strangers must write into a space other strangers read, in real time, and see each other’s writes. Chat. Auctions. Inventory. Collaborative editing. There the write is the product, and no amount of clever layering removes the need to arbitrate it.

The mistake is not choosing one. The mistake is choosing the transactional architecture — with all its accounts and servers and on-call — for a system whose global state was editorial all along. I have shipped that mistake more than once. Most “we need a backend” conversations I have sat in were about a read-mostly catalogue with an admin panel.

The test

A question worth asking before you accept a global write:

If two strangers both did this, would I need a policy?

If yes, you have not designed a write. You have designed a moderation queue, an abuse surface, a quota system and a support inbox, and you should cost it that way.

If no — if the only person who ever writes is you, through a pull request, with a diff and a history — then the global layer can be read-only, the local layer can hold everything personal, and the server you were about to build does not need to exist.

Push the writes to the edge that owns them. Keep the middle a file.

kody-w.github.io/OS/console boots in about a second from static files. Try stat on any path to see which layer answered.