Cabaxiom

Declare the state you want. The loop reads the world, finds the gap and closes it. Then it looks again to prove the gap is gone.

A reconciliation kernel with no domain baked in and nothing to install alongside it. You describe each concern as a Step that reads its own drift and knows how to close it. The kernel resolves the order and runs the steps, then reads reality back. A clean result is verified, not assumed. Pure standard library, zero runtime dependencies.

---

See it work

This is examples/git_repo_state.py, printed verbatim. It takes a throwaway git repository from empty to fully configured, in the right order and then proves the result held.

Throwaway repository: /tmp/reconciler-git-rf6bona1

Plan (what converge would do, in resolved order):
    - user.name: want 'Reconciler Bot', have unset
    - user.email: want 'bot@example.test', have unset
    - commit.gpgsign: want 'false', have unset
    - HEAD: repository has no commits yet
    - branch:feature/login: local branch is missing

First converge:
  applied this run:
    + user.name: set to 'Reconciler Bot'
    + user.email: set to 'bot@example.test'
    + commit.gpgsign: set to 'false'
    + HEAD: created the initial commit
    + branch:feature/login: created local branch
  residual: empty -> desired state verified by re-probe

Second converge (should be a clean no-op):
  applied this run: nothing
  residual: empty -> desired state verified by re-probe

Direct git inspection:
    user.name = 'Reconciler Bot'
    HEAD      = 13fde42
    branch    = feature/login

Three things in that output are the entire idea.

The plan came out ordered. The steps were handed in scrambled. A branch cannot exist before there is a commit and a commit needs user.name and user.email first. Nobody wrote that sequence. The kernel read the dependency graph and produced it - config, then the initial commit, then the branch.

The first converge did the work that was missing and nothing else. Every line under "applied this run" is a real mutation of a real repository. Then the kernel probed a second time and found nothing left. That empty residual isn't bookkeeping. The loop went back to git after acting and confirmed reality now matches intent.

The second converge did nothing and that is the whole point. Running the identical reconcile again applied zero changes and still verified clean. A no-op is not a wasted pass. It's the property that makes every other pass safe.

---

What reconciliation actually is

Most code that touches the world is a script - a fixed run of imperative steps that assumes it starts from a known place. Run it twice and it breaks or worse, it quietly does the wrong thing. Reconciliation drops that model. You keep a picture of the desired state and repeatedly drag the actual state toward it through a short feedback loop:

        +------------------------------------------------+
        |                                                |
        v                                                |
   +---------+       +----------+       +---------+      |
   |  WATCH  | ----> | COMPARE  | ----> |   ACT   | -----+
   |  read   |       | actual   |       | close   |
   | actual  |       |   vs     |       |  the    |
   | state   |       | desired  |       |  gap    |
   +---------+       +----------+       +---------+
                          |
                          v
                     the gap here
                    is called DRIFT

WATCH reads what is true right now, not what you last left behind. COMPARE holds that against what you declared and computes the difference. That difference is the drift - the itemized gap between reality and intent. ACT applies just enough to close it. Then the loop runs again from the top.

A few properties fall straight out of this shape and they are what separate a reconciler from a setup script.

Drift is expected, not exceptional. Someone hand-edits a file. A branch gets deleted, a replica dies, config drifts during an incident. A reconciler does not try to prevent any of that. It assumes the world will wander off and treats every deviation as something to fix next pass. It does not raise an alarm.

It is level-triggered, not edge-triggered. A trigger does not mean "handle this one event". It means "re-check the whole state against desired, now". You never process a single delta. You ask the same question from scratch, every time. That is why you can miss a signal, double-fire a trigger or run on a plain timer and the answer stays correct.

That forces idempotency, which is the reward. Because the same unit of work may run any number of times, doing it twice has to land exactly where doing it once did. A pass that finds nothing to change and does nothing is a first-class outcome, the no-op from the second converge above. A system built this way self-heals. It converges toward desired over repeated cycles no matter how it was knocked off course.

If you have used a Kubernetes controller, you have already met this loop. It runs the same idea on your own Steps. For intuition, it is a thermostat that keeps re-reading the room instead of firing the furnace once. Or an immune system that patrols instead of firing once and going quiet. Reconciliation is what resilience gets built on, precisely because everything drifts eventually.

Cabaxiom is that principle and nothing else, boiled down to a small kernel with no domain vocabulary. It has no idea what a file or a git repo is. You teach it one Step at a time.

---

The building blocks

Step - a unit of desired state

You subclass Step and answer one question. What is the gap between the world and what I want? You report that gap as drift and you know how to close it.

from cabaxiom import Assessment, Step

class Config(Step):
    def __init__(self, key: str, want: str) -> None:
        self.key = key
        self.want = want

    def assess(self) -> Assessment:
        have = read_config(self.key)                  # WATCH
        if have == self.want:                         # COMPARE
            return self.verified()
        return self.drifted(f"want {self.want!r}, have {have!r}")

    def apply(self):
        write_config(self.key, self.want)             # ACT
        return self.changed(self.key)

assess() is WATCH plus COMPARE in one probe and it never mutates. Answer self.verified() when the world already matches and self.drifted(...) with what is wrong when it does not. apply() is ACT, answers what it changed and must be idempotent. The kernel calls both and re-probes after the write. You never write the loop. The git example at the top is three steps of exactly this shape.

The kernel reads only two fields out of your drift, through the Drift protocol - a name and a message. That is the entire contract. DriftItem(name, message) is the ready-made implementation and covers almost every step. Because the kernel reads nothing else, your domain stays entirely yours.

after - declare dependencies, get ordering for free

A step names what must run before it with one class attribute:

class InitialCommit(Step):
    after = (GitConfig,)

class LocalBranch(Step):
    after = (InitialCommit,)

Hand the reconciler these in any order and it sorts them into dependency waves. That is what produced the correct plan in the opening output. A dependency cycle raises ValueError at construction and names the steps it could not place. A dependency on a step outside the set you passed is ignored, so a subset still reconciles cleanly.

Reconciler - the engine

import asyncio

from cabaxiom import Reconciler

reconciler = Reconciler([LocalBranch(...), GitConfig(...), InitialCommit(...)])

asyncio.run(reconciler.plan())                 # the ordered gap, no changes made
residual = asyncio.run(reconciler.converge())  # WATCH -> COMPARE -> ACT -> re-probe

if not residual:
    print("verified clean")

converge() returns a Residual, a list[Drift] of whatever gap outlived the run. Empty means the kernel acted, probed again and confirmed reality now matches intent. The changes made along the way live on a separate channel, residual.applied, which is what the examples print under "applied this run". Keeping the two apart means "what I fixed" never blurs into "what is still wrong".

watch() - the loop that never ends

converge() is one turn of the crank. watch() keeps turning it, once per wake, for as long as the world keeps moving.

from cabaxiom import Clean

async for residual in reconciler.watch():                # one converge per wake
    log_gap(residual)

async for residual in reconciler.watch(settle=Clean()):  # stop at the first clean pass
    log_gap(residual)

The steps say when to look, through Step.watch(). The loop sleeps between wakes. A wake carries no payload and means only look again, so each pass re-asks the whole question and a missed, doubled or coalesced wake is harmless. A declaration whose steps announce nothing converges once and finishes.

---

Choosing behavior

Every axis of behavior is a small object you swap. The defaults resolve to Kahn, Serial, Once and no cancellation. Pass nothing and you get all four.

Axis	The question it answers	Default	Alternatives
Ordering	Given the after graph, in what order do steps run?	Kahn (dependency waves)	DFS (flat post-order), Priority(key=...) (best-first frontier over a key), Components (split into independent chains)
Dispatcher	How does an ordered group actually run?	Serial (one step at a time)	Parallel (gather each wave on the event loop), Pipeline (run independent chains concurrently), ThreadDispatcher (relocate a blocking apply to a thread)
Error policy	When a step fails, stop or push on?	OnError.FailFast	OnError.BestEffort (finish the group, collect failures)
Convergence	How many apply-then-probe passes per converge?	Once (single pass)	Fixpoint(max_passes=...) (repeat until the residual stops changing by value or a ceiling is hit)
Cancellation	When should a run abort cooperatively between steps?	Cancellation (never aborts)	Deadline(seconds) (wall-clock budget), Flag (manual switch), the composites AnyOf / AllOf / Majority that nest into a tree or Quorum(..., rule=...) with Some / Every / Most for a custom rule

Parallel and Pipeline hold no pool and need no ceremony. Hand one to the dispatcher= parameter and it is ready.

import asyncio

from cabaxiom import Reconciler, Parallel, Fixpoint, Deadline

reconciler = Reconciler(
    steps,
    dispatcher=Parallel(),
    convergence=Fixpoint(max_passes=10),
    cancellation=Deadline(seconds=30),
)
residual = asyncio.run(reconciler.converge())

More than converge

A Reconciler reads and writes state through a handful of verbs. Each fans across every step in resolved order, reversed for the teardown verbs. A Step answers assess(), apply() and prune(). The rest are the engine's own reads of what your steps reported.

• drift() reports the gap without touching anything.
• plan() is a dry-run read of the pending diff, in resolved order.
• audit() returns advisory findings about a concern that is already satisfied. These never trigger an apply.
• footprint() previews what a teardown would remove, in reverse order.
• converge() applies, then re-probes, returning the Residual.
• prune() is the reverse-order teardown itself, verifying the same way a converge does.

---

Examples

The examples/ directory holds three runnable, self-contained programs. Each builds a real throwaway resource, converges it, ends with an empty residual and cleans up on the way out. Run any of them with python examples/<name>.py.

git_repo_state.py - the flagship

Drives a real throwaway git repository through plain subprocess calls, over the chain GitConfig -> InitialCommit -> LocalBranch. The steps go in scrambled and Kahn resolves the order. Every drift() is a genuine read, every apply() a genuine mutation. Read it first. Its full output is at the top of this README.

filesystem_layout.py

Brings a temp directory tree to a desired layout with Directory and TextFile steps, ordered so directories land before the files inside them. Then it tampers with a file behind the reconciler's back and re-converges. This is the clearest look at drift as something you recover from.

Tampering: overwrite config/app.toml with the wrong content
  drift now sees 1 problem(s):
    ! /tmp/reconciler-fs-0gafhd5o/config/app.toml: content does not match desired
Converge again to self-heal:
  applied this run:
    + /tmp/reconciler-fs-0gafhd5o/config/app.toml: wrote desired content
  residual: empty -> layout verified by re-probe

parallel_fixpoint.py

Provisions a service dependency graph with the Parallel dispatcher, so each dependency wave is gathered on the event loop and settles a multi-pass replica scale-up with Fixpoint convergence.

Resolved waves (Kahn):
    wave 0: Network
    wave 1: Cache, Database
    wave 2: AppServers

Converge (Parallel dispatcher, Fixpoint convergence):
  applied this run: 6 change(s)
    + Network: provisioned
    + Cache: provisioned
    + Database: provisioned
    + AppServers: scaled up to 1 replica(s)
    + AppServers: scaled up to 2 replica(s)
    + AppServers: scaled up to 3 replica(s)
  residual: empty -> whole stack verified by re-probe

---

Install

pip install cabaxiom

Nothing else is pulled in. The kernel leans on the standard library alone and everything you need is re-exported from the top-level package.

---

When not to reach for this

The re-probe is the entire guarantee and it is only as honest as your drift(). If a step cannot observe the thing it changed, converge() can't tell a real fix from a no-op. An empty residual then means only that drift() returned nothing. Write drift() to read the world, never to echo what apply() intended.

A few more boundaries, stated plainly:

• Reconciliation earns its keep when a system will drift and you want it to keep correcting itself. If all you need is a one-shot transformation that runs once and is never checked again, a plain function is simpler and you should write that instead. The value here is the loop.
• It does not poll or schedule on its own. watch() sleeps until a step announces its world moved through Step.watch(), so the clock belongs to the world rather than to a timer.
• It's not a state store. It keeps no history and no desired-state document. Each step owns its own notion of desired and observed.
• The engine is asyncio to the bone. A blocking or CPU-bound apply() belongs on ThreadDispatcher, which relocates the call to a thread, while everything else stays on the caller's loop.

---

Development

pip install -e ".[dev]"
ruff check .
pytest --cov=cabaxiom --cov-report=term-missing

The suite is written on the standard-library unittest framework with subtests and runs under pytest with coverage, currently at 100% across ordering, execution, convergence, cancellation, planning and pruning. CI lints with Ruff and runs the full suite on CPython 3.10 through 3.14, on every push to master and every pull request. fail-fast is off, so a break on one interpreter does not hide the others.

---

License

Released under the MIT License. See LICENSE.