§1. What it is, in one page

planarian @ a924e09 · Spec v4.6 · snapshot main · all versions

Most operating systems can tell you that something broke. Planarian is built to know what should be true, notice when it isn’t, and close the gap without making things worse.

It can do this because the system is declared: a NixOS configuration says which services, drivers, and settings should exist. From that, plus a manifest that adds what NixOS doesn’t say (what depends on what, how to test each thing, how risky it is to touch), Planarian derives desired state. Desired state has conditions: the graphical session should be running after someone logs in; a printer service should be running when the printer is connected; a service the user stopped on purpose is left alone until they say otherwise. Planarian observes actual state continuously and runs health probes under a strict contract (no sudden noises, no side effects, bounded cost). When a probe times out, the answer is Unknown, not Failed.

A gap between desired and observed state opens an incident. Repair follows a strict order:

1. Root-cause. The dependency graph distinguishes “must be up for this to work” from “merely starts before” from “we suspect these are related.” A failed audio service whose required sound-card driver also failed is a symptom; the driver is the target.
2. Deterministic search. A small planner searches the known transitions (restart this, rebind that, apply a cataloged change, roll back) for one whose preconditions hold and whose predicted result closes the gap, safest and least disruptive first.
3. Summon the model. Only if search finds nothing, or the incident’s budget is spent, does a local model get the state, the graph, what was tried, and the manuals. It proposes in the same typed format the planner uses.
4. Escalate. If that also fails, the user gets a plain-language report, and the incident goes quiet with a cooldown rather than retrying forever.

User requests follow the same order: “reconnect Wi-Fi” matches a declared action directly; “stop the backup service while I work on it” becomes an attributed override of desired state, so Planarian doesn’t fight the user; “make it faster” is ambiguous and goes to the model, which asks before proposing.

Whoever proposes, one executor decides, and it decides from facts it derives itself: what the change actually touches in the evaluated configuration, how sensitive and how disruptive that is, what else changed this session. Nothing in a proposal can grant authority. Runtime actions with no lasting effect just run. Configuration changes run as a transaction: journaled before anything happens, activated as a candidate generation, probed, and either committed or reverted, with a watchdog that finishes the job if Planarian itself is killed halfway. Security-relevant, irreversible, or user-data changes wait for approval, and the approval is re-checked against the exact change the moment before it runs. The repair machinery itself can never be changed by any proposal, under any approval.

The model is a convenience and a fallback. If it is absent, broken, or wrong, the system still boots, runs, repairs the easy faults, and reverts the bad changes.

Planarian is meant to be unnoticed under normal use. Its overhead, its notifications, and its effect on a game’s frame time are measured, and none of them may get worse between releases. It defers non-urgent work while the user is absorbed in something, and it never undoes a deliberate choice; it only needs the choice to have a name on it.