Tech Notes

The guess and check pattern

2026-10-01T00:00:00Z

Here's a software pattern that I've found new use for in our new world of agents. I'll motivate it with an example from build systems.

When using build systems you often write down some information that feels redundant. For example, from the source code you can see that module A imports from module B, but then the build system requires you to separately tell it to build module B before building A. Why do we need to write this out, when it is visible from the source? It is tempting to figure it out automatically, as tools like ekam do.

The easy answer for why we don't always do this is the normal software answer of path dependence and how software tends to be clunky. But there are also two good reasons: information like this can be costly to gather and also can be hard to get completely right. It can be costly if your language design you might need to parse the whole source tree to find where a given module actually lives, as perhaps with C++ modules. It can be hard to get correct if there is configuration complexity; for example in a C file with #include "config.h", it is not clear which of potentially multiple config.h candidates it means; a tool that guesses will be hard to predict and sometimes wrong. (Just so I'm not only picking on C, I'll add that finding where a given import ... from 'x' in JavaScript resolves to has surprisingly complex semantics, and can even depend on the path of the source file.)

However, in the common case it really is often possible to automate things, and it's not that costly. This leads us to what in my head I call the guess and check pattern: use a tool to automatically guess, edit and/or verify the result, and write that down as the definitive answer.

For example Gazelle updates Bazel BUILD files from Go source. Bazel then gets to run quickly without parsing Go source, and if Gazelle gets things wrong, you can still edit the files. As an additional benefit, you check the result in to source control, which means a human gets to see what actually changed, and it pins down the result.

For another example of this pattern, consider "lock files" as used in programming language package managers. When you npm add or cargo add etc., the tooling makes network requests, runs a complex algorithm to resolve what you meant, and writes down the result. Builds after this point can use the lock files without looking around on the network or guessing about versions.

I used this pattern in my Windows emulator projects. For any given Windows function I declare the emulator's version of the function in Rust. To automate writing out the function's matching argument list I can generate it from metadata published by Microsoft. But I only need that metadata when I run the generator, and the output doesn't need to be perfect! I can generate code that is most of the way there, because it's fine as a human to fix up the details after. The generator can even just make up type names that don't exist because the compiler will catch it afterwards.

Another way to look at this pattern is to see there's a chain of work to guarantee determinism atop a nondeterministc start: you can use a tool that makes a guess, and as long as you write down that guess and use deterministic steps from that written state onward you still have determinism in the result.

Which finally leads me to one way I've been tentatively experimenting with AI. AI behavior matches the shape I've been describing. An agent can do a long slow processing step and generate some output — not limited to code, even things like gathering data — as long as I write the output down as a result and have a human and/or tooling verification pass after. Keeping this pattern in mind has helped me find places where AI is suitable: problems where I know up front that a plausible guess is all I require, and that framing helps me keep in mind that the output is always just a guess.

(PS: just in case it wasn't obvious, my blog posts are always just me banging away on a keyboard, no clankers will keep me from my meandering!)

Computing graph dominators

2026-08-13T00:00:00Z

A few years back I wrote about the dominator tree of a dependency graph, which is one of my favorite tricks for thinking about dependencies. It turns out a new tinkering project of mine again needs a dominator tree, so I invested some time to deepen my understanding.

In this post I present an algorithm for computing graph dominators along with the intuition behind it.

Definitions

There are two central definitions that I will handwave some details about; you can read Wikipedia for those. Here's a graph to visualize them. Hover some nodes while you read.

Node x dominates node y if all paths from the graph's root (a, in this example) to y must go through x. If you hover a node here, its dominators are shown in yellow.
Node x immediately dominates y if it is the lowest dominator above y. The immediate dominator of the hovered node is shown with a thicker outline.

Again, see my earlier post for some other framings of what these mean or how to think about them.

Choosing an algorithm

There is a continuous stream of research going back to 1959 publishing different algorithms for computing dominators with varying levels of implementation complexity. Lengauer-Tarjan ("LT") from 1979 seems to be the standard but it is relatively complex, involving spanning trees and union find.

In LLVM, i.e. in a tool where performance really does matter, it appears they use LT but have changed their implementation over time. For example in this work in 2017 they mention in a large compile they were computing 6.5 million dominator trees(!) and they changed to an approach that supports incremental updates.

The paper "A Simple, Fast Dominance Algorithm" from 2001 describes a simple algorithm that they claim is both useful for learning and in practice about 2.5x faster than LT.

The later paper "Finding Dominators in Practice" compares multiple algorithms, and regarding the above claim they write: "a more careful implementation of [Lengauer-Tarjan] later led to different results (personal communication)", which is not a great sign. However, in that paper they also gather numbers comparing five different algorithms across a collection of graphs and find that they all land somewhere between 2-5x the time of a breadth-first search, which itself they measure in microseconds. Which is to say, for the kinds of graphs that you or I likely care about, the difference doesn't matter.

If you like reading papers (I do! it's a worthy habit to develop!), you're best off reading "A Simple, Fast Dominance Algorithm" directly. But in part for deepening my own understanding by saying it in my own words, the rest of this post will dive into the "Simple, Fast" algorithm.

The approach

Their presentation is roughly two parts. First, they describe a general approach for computing dominators and why it works. Second, they show an algorithm that uses some representation tricks to implement that approach efficiently.

The general approach is describing the computation as a data-flow equation, which defines a per-node computation that recursively depends on itself.

Define dom[n] as the set of dominators for node n. Then the data flow equation is:

dom[root] = {root}
dom[n] = intersect(dom[p] for p in predecessors(n)) union {n}

In words, the dominator set of a node is the intersection of the dominators of the node's predecessors, as well as the node itself. (To make sense of this, don't overlook that dom[n] always includes n!)

To compute this, you run in a loop that updates each node until the output stops changing.

changed = True
while changed:
    changed = False
    for n in nodes:
        new = recompute(n)
        if new != dom[n]
            dom[n] = new
            changed = True

In the paper, they connect this to other research that shows this will converge on the correct answer in a relatively small number of iterations — if you iterate the nodes in reverse postorder, more on that in a moment. For our purposes of intuition, I think it's enough to say "this is guaranteed to converge on the correct result fast enough, see the paper for proof".

Why does this work? In the above sample graph, try hovering the predecessors of node g or h and mentally intersect the sets in yellow to see it produce their own yellow sets. Intuitively the sets represent something like a path from the root (though they may not be a full path; witness the dominator set for g), and intersecting the sets results in the nodes found on all paths from the root.

As given this is inefficient to compute — though I suspect if you're writing Python or whatever and working with a small graph it's probably fine. The actual algorithm from the paper is more efficient.

Traversal order

To get to the algorithm we first must detour into graph traversal, as it relies on a reverse postorder traversal of the graph.

A preorder traversal visits a node then its children; a postorder visits the children before the node, recursively; a reverse postorder is the postorder's order but reversed.

Importantly, reverse postorder is different than preorder. In the below graph, I've numbered the nodes in their traversal order so you can compare them.

In a preorder traversal, the recursion makes its way all the way down the left side to the bottom before visiting the right side, so the right child of 0 is visited last. With a reverse postorder you get the invariant that each node is visited before any of its children, which is the important property the algorithm relies on.

(I fear in writing this section that it is all rather obvious to you, reader. I think many years of working on build systems has given me intuition for algorithms over acyclic graphs and for whatever reason as soon as cycles get involved I start getting confused. In the first graph in this post there is a "back edge", from g to b, but also the right way to think about it is that in terms of a traversal g still comes "later".)

By the way, in "Finding Dominators in Practice" when discussing this algorithm and its use of postorder they write:

Initializing T as a [postorder] tree is bad both in theory and in practice because it causes the back edges to be processed, even though they contribute nothing to the [nearest common ancestors]. Intuitively, a much better initial approximation of the dominator tree is a [breadth-first search] tree.

This wording feels kind of aggressive to me! The general dataflow approach produces the correct answer regardless of the iteration order, so changing the order doesn't affect correctness, and in their results they measured both approaches and found their idea improved performance by roughly 10% on the graphs they were measuring.

But I believe the original paper's proof of the bound on the number of iterations relies on specifically reverse postorder. (I asked Claude about this and it found a counterexample 14-node graph where the RPO order takes one pass and the BFS order takes 3 passes.)

Dominator tree

With reverse postorder ("RPO") defined, let's look at the actual algorithm.

The first trick of the algorithm is that instead of computing dominator sets, you instead compute for each node just its immediate dominator. If you look at each node's immediate dominator as a parent pointer you get a dominator tree. Given immediate dominators, you can read the dominator set of a given node by walking the dominator tree upwards.

Here's the first graph again, with its dominator tree (the thing we're trying to compute) alongside it. Look at a node and its ancestors in the dominator tree, and compare to the yellow nodes when you hover it on the left.

To compute immediate dominators, it's again an iterative data flow calculation.

idom[root] = root  # unlike the sets before, idom stores single nodes
idom[n] = intersect_dom(predecessors(n))

For example, to compute the immediate dominator of node g, we look at its predecessors d and e and walk the dominator tree upwards to find the place where their dominator sets intersect.

This is another cyclical definition, so we again iterate it for all nodes until it stabilizes.

Meet point

The second trick of the algorithm is in how to efficiently find the intersection. This is where the RPO matters. Here is the graph again with the nodes labeled by their RPO index.

The RPO numbering gives the property that a parent always has a number lower than its children. Given two "fingers" pointing at two nodes in the tree, to find where they meet, move whichever finger is pointing at a larger number to its parent. To intersect more than two predecessors, intersect two at a time.

intersect(a, b):
    while a != b:
        while a > b:
            a = idom[a]  # walk a upwards
        while b > a:
            b = idom[b]  # walk b upwards
    return a

Try clicking a node with multiple predecessors in the graph (3, 6, or 7) to see this in action. (Note that we're finding the meet point of the predecessors of the node, which comes from the full graph, while the intersection operation uses the idom tree, which is a subset of the graph. This means the moving circles visually skip some nodes in the above graph.)

Details

In the above I've been a bit loose about initialization: the code is reading from a data structure while that data structure is still under construction, which might feel like it wouldn't work. I think for intuition's purposes the right way to think about it is that the "while changed" loop effectively recomputes everything after any change anywhere, and that it's also guaranteed to converge.

That looks inefficient, but the algorithm also does the per-node processing in RPO, which is effectively "top down". That doesn't guarantee a single pass, but it does mean it's not that many passes. (For an example of how it isn't a simple top down single pass, consider how the first time the algorithm visits node 3 in the RPO it hasn't yet computed idom for its predecessor node 6.)

Here's the complete Rust implementation I ended up with in my toy application. I cannot guarantee it's correct as I am still learning, but it at least passes some simple tests!

// Inputs:
// nodes numbered in reverse postorder, so node 0 is the start
// preds[i]: array of predecessors of node i
// order[i]: the ith node visited in the reverse postorder

// Output:
// idom[i]: the immediate dominator of node i
let mut idom = Vec::with_capacity(graph.len());
let unset = usize::MAX;
idom.resize(graph.len(), unset);  // initialize all results to unset
idom[0] = 0;  // idom[start] is itself

let mut changed = true;
while changed {
    changed = false;
    // compute idom[i] for all nodes except the root
    for i in order[1..].iter().copied() {
        // only consider predecessors that have been initialized
        let mut preds = preds[i].iter().copied()
            .filter(|&j| idom[j] != unset);
        let Some(mut new) = preds.next() else {
            continue;  // node is not reachable
        };
        for pred in preds {
            let mut f1 = new;
            let mut f2 = pred;
            while f1 != f2 {
                while f1 > f2 {
                    f1 = idom[f1];
                }
                while f2 > f1 {
                    f2 = idom[f2];
                }
            }
            new = f1;
        }
        if idom[i] != new {
            idom[i] = new;
            changed = true;
        }
    }
}

PS: If you're not familiar with Rust, you should know that this might look like it's allocating where it isn't. The .filter() call only creates a filtering iterator, not an array, which inlines to a loop when it's read from. And the .iter().copied() calls mean to iterate by value rather than by reference, where the copied thing here is just integers.

Jujutsu tutorial

2026-07-22T00:00:00Z

A friend asked me how to learn to use the Jujutsu version control system, which has been my favorite new piece of tech from the last few years.

I thought I'd quickly write up the tutorial I'd wished I'd had. That snowballed into actually trying to write The Tutorial, complete with chapters and an index and so on.

(In particular it also contains a sales pitch about why learning this tool is worth your time. This is uncomfortable for me because I am not really the sort of person who advocates but I found it a useful exercise exactly because of that. Also it received this nice comment.)

Go read the tutorial!