DEV Community: Den

What Was the Moment You Realized the Bug Wasn't Where You Thought It Was?

Den — Mon, 07 Sep 2026 17:27:22 +0000

I've noticed a pattern in almost every bug I've written up here: the fix never ends up where I started looking.

A validation error that looked like a schema problem turned out to be an encoding mismatch three layers upstream. A "frozen" simulator turned out to be working correctly — the bug was an unstated assumption in my evaluation algorithm, not the code executing it. A user's data disappearing turned out to be two browser tabs disagreeing about which one held the truth.

Every time, I started debugging with a theory about where the problem lived, and every time, the actual cause was one layer removed from that theory — not wrong code, but a wrong assumption about which code even mattered.

I don't think this is unique to me. I think it might be the actual shape of most non-trivial bugs: the symptom points at a location, and the location is almost never the cause.

So — what's yours? The moment you were dead certain the bug was in X, spent hours proving X was fine, and found it living quietly in Y instead. Doesn't have to be dramatic. I'm just curious whether everyone's "it wasn't where I thought" story rhymes with mine, or if there's a completely different shape to it depending on the stack.

Why My React State Kept "Working" — Until Two Tabs Opened at Once

Den — Mon, 07 Sep 2026 08:27:57 +0000

For weeks, the saved-articles feature in one of my side projects worked fine. useState held the list, a save button pushed to it, a sidebar rendered it. Every manual test passed. Then a user reported that saving an article in one tab made it vanish from the sidebar in another tab — and sometimes an article they'd just unsaved would come back a few seconds later, unsaved-then-resaved, like the app couldn't make up its mind.

I couldn't reproduce it for a day. I only had one tab open. That should have been my first clue.

The setup that looked fine

The saved-articles state lived exactly where every React tutorial tells you to put it:

function useSavedArticles() {
  const [saved, setSaved] = useState(() => {
    const raw = localStorage.getItem("saved-articles");
    return raw ? JSON.parse(raw) : [];
  });

  const save = (article) => {
    setSaved((prev) => {
      const next = [...prev, article];
      localStorage.setItem("saved-articles", JSON.stringify(next));
      return next;
    });
  };

  return { saved, save };
}

Read from localStorage on mount, write to it on every change. This is the pattern I'd copy-pasted from a dozen "persist state with localStorage" articles, and it works — for exactly one tab.

Where it breaks

localStorage is shared across every tab on the same origin. useState is not. Each tab has its own React tree, its own saved state, its own copy of the array sitting in memory.

So the sequence that broke it looked like this:

Tab A: user saves Article 1 → saved = [1] in Tab A's memory, localStorage now says [1].
Tab B was already open before that. Its saved state was initialized from localStorage when it first mounted — which was empty. Tab B's memory still says saved = [].
Tab B: user unsaves nothing, does nothing — but then saves Article 2. Tab B computes next from its own stale prev, which is [], so it writes [2] to localStorage — silently overwriting Article 1.
Tab A, still showing [1] in its own memory, looks "correct" locally. Refresh Tab A, and Article 1 is gone, because localStorage only ever had [2].

Nothing in either tab was ever wrong, in isolation. The bug wasn't a logic error — it was two independent sources of truth that agreed by coincidence during testing and diverged under real use, because I always tested with one tab and the user always worked with several.

The fix: listen for the event you're already causing

The browser actually tells you when another tab changes localStorage — it's just an event most of us never wire up, because single-tab testing never fires it. window emits a storage event on every tab except the one that made the write.

function useSavedArticles() {
  const [saved, setSaved] = useState(() => readSaved());

  useEffect(() => {
    const handleStorageChange = (event) => {
      if (event.key === "saved-articles") {
        setSaved(readSaved());
      }
    };
    window.addEventListener("storage", handleStorageChange);
    return () => window.removeEventListener("storage", handleStorageChange);
  }, []);

  const save = (article) => {
    setSaved((prev) => {
      const next = [...prev, article];
      localStorage.setItem("saved-articles", JSON.stringify(next));
      return next;
    });
  };

  return { saved, save };
}

function readSaved() {
  const raw = localStorage.getItem("saved-articles");
  return raw ? JSON.parse(raw) : [];
}

Now when Tab A writes, Tab B's storage listener fires and re-reads from localStorage, replacing its stale in-memory copy instead of computing a new one from state it never updated. The write in step 3 above now happens against Tab B's current data, not the snapshot it took when it first mounted.

BroadcastChannel is the newer, cleaner alternative if you want structured messages instead of parsing whatever landed in a storage key — but for a simple "resync on external change" case, the storage event needs no extra API and works in every browser that already supports localStorage.

The actual lesson

useState scopes to a component tree. A component tree scopes to a tab. localStorage scopes to an origin. The moment your persistence layer is broader than your state's scope, "keep them in sync" stops being optional — it's a requirement you inherited the second you chose localStorage, whether or not you noticed choosing it.

I hadn't noticed. I'd been testing the save button, not the two things it was supposed to keep in agreement.

I write about things that break while I build Boolflow and RealFeedApp. If you've solved cross-tab sync differently — BroadcastChannel, a shared worker, something else — I'd like to hear it.

How I Structure a FastAPI Service: Layers, DI, and Where Validation Actually Belongs

Den — Sun, 06 Sep 2026 12:00:13 +0000

Every FastAPI tutorial starts the same way: one file, a few @app.get decorators, a Pydantic model, done. That's great for a demo. It falls apart the moment you have more than one entity, more than one person touching the code, or a bug report that starts with "it validated fine but broke downstream."

I've hit that wall enough times (see my last post, ValidationError Is Not a Policy, on why a passing ValidationError check isn't a policy) that I've settled on a structure I now reach for by default. Nothing exotic — no hexagonal-architecture diagrams, no ports-and-adapters ceremony. Just four layers with one job each, and a DI setup that keeps them from knowing too much about one another.

The four layers

app/
├── api/          # routers — HTTP in, HTTP out, nothing else
├── services/     # business logic — no HTTP, no SQL
├── repositories/ # persistence — no business logic
├── schemas/      # Pydantic models — shape, not meaning

The rule I enforce on myself: each layer is only allowed to talk to the one directly below it. A router never touches a repository. A service never sees a Request object. If I catch myself importing fastapi inside services/, that's a signal the logic is in the wrong place.

`api/` — routers

The router's job is translation: turn an HTTP request into a function call, turn a return value into an HTTP response. That's it.

@router.post("/orders", response_model=OrderOut)
async def create_order(
    payload: OrderCreate,
    service: OrderService = Depends(get_order_service),
):
    order = await service.create(payload)
    return order

No try/except here beyond translating known service exceptions into HTTP status codes. If a router has an if statement that isn't about status codes, it's doing the service's job.

`services/` — business logic

This is where the actual rules live: what makes an order valid, what happens when stock runs out, which side effects fire in which order. Services depend on repository interfaces, not concrete database calls — which is what makes them testable without spinning up Postgres.

class OrderService:
    def __init__(self, orders: OrderRepository, inventory: InventoryRepository):
        self.orders = orders
        self.inventory = inventory

    async def create(self, data: OrderCreate) -> Order:
        if not await self.inventory.has_stock(data.sku, data.quantity):
            raise InsufficientStockError(data.sku)
        return await self.orders.save(Order.from_create(data))

`repositories/` — persistence

Repositories know SQL (or whatever storage you use). They don't know why a row is being saved, only how. This is the layer I swap out in tests for an in-memory fake.

`schemas/` — Pydantic models

Here's the distinction that took me longest to internalize: schemas describe shape, services describe meaning. A Pydantic model can tell you a field is a positive integer. It cannot tell you that quantity can't exceed available stock, or that a discount code has expired. Those are business rules, and they belong in the service layer — not stuffed into a @validator.

I made this mistake for a while: piling business logic into Pydantic validators because it felt convenient. It works right up until the rule needs to check something outside the payload — a database lookup, another field's async state, today's date against a promo window. Then the validator either can't do it, or does it badly with hidden side effects. Split it: Pydantic checks is this shape well-formed, the service checks is this operation allowed.

Dependency injection: keep it boring

FastAPI's Depends() is enough. I don't reach for a DI container unless the service genuinely has cross-cutting concerns (multi-tenant config, feature flags per request). Most of the time this is all it takes:

def get_order_repository(db: AsyncSession = Depends(get_db)) -> OrderRepository:
    return OrderRepository(db)

def get_order_service(
    orders: OrderRepository = Depends(get_order_repository),
    inventory: InventoryRepository = Depends(get_inventory_repository),
) -> OrderService:
    return OrderService(orders, inventory)

The payoff shows up in tests, not in the app itself:

def test_create_order_raises_when_out_of_stock():
    service = OrderService(
        orders=FakeOrderRepository(),
        inventory=FakeInventoryRepository(stock={"SKU1": 0}),
    )
    with pytest.raises(InsufficientStockError):
        await service.create(OrderCreate(sku="SKU1", quantity=1))

No TestClient, no database, no mocking fastapi.Depends. Just a plain object with fake dependencies.

Where this breaks down

This structure earns its keep once you have real business rules and more than a couple of endpoints. For a small internal tool or a weekend project, it's overkill — a single main.py is the right call, and I'd tell anyone insisting on four layers for a CRUD toy to stop. The cost is real: more files, more indirection, one extra hop to trace a request end to end.

The tell that it's time to split things up isn't line count, it's this: the moment a validator needs to ask "but is this actually allowed right now" instead of "is this shaped correctly," you've outgrown a single file, whether you've noticed it yet or not.

I write about things that break while I build Boolflow and RealFeedApp. If you've got a different way of drawing these lines, I'd like to hear where it diverges.

I Found a 100GB "Bug" Hiding in My NVIDIA Driver

Den — Fri, 04 Sep 2026 08:42:39 +0000

I was clearing out disk space last week when I noticed one folder eating almost 100GB of my SSD. Not a game. Not a video project. Not Docker images. A cache folder I'd never opened in my life:

C:\Users\<Username>\AppData\Local\NVIDIA\DXCache

Ninety-something gigabytes of .nvph files with names that mean nothing, sitting quietly on my drive for who knows how long.

What's actually in there

When a game runs, the GPU driver compiles shaders — small programs that tell your graphics card how to render lighting, materials, effects, and so on. Compiling them on the fly causes stutter, so drivers cache the compiled result on disk. Next time you launch the same game, it loads the precompiled shader instead of recompiling it, and you get a smoother experience.

That part, on its own, isn't the problem. The problem is what happens after — and also why there's so much more of it to cache than there used to be.

Why this got so much bigger with modern engines

If it feels like shader compilation stutter became a bigger deal in the last few years, that's not just perception. Unreal Engine 4 titles had this problem too, but it was quieter, for a few concrete reasons:

DX11 vs DX12/Vulkan. Most UE4 games shipped on DX11, where the driver handles shader compilation itself and hides a lot of the cost. UE5 pushes much harder toward DX12 and Vulkan, and on those APIs, compiling a Pipeline State Object (PSO) is the engine's job, not the driver's. Epic has said outright that runtime hitches from PSO creation are inherent to those APIs in a way they simply aren't on DX11.
Way more PSO combinations. Nanite and Lumen introduce dynamic lighting and materials that generate far more unique shader/pipeline-state combinations than UE4's more static rendering paths. More unique PSOs means more first-time compilations happening live, mid-gameplay, which is exactly what shows up as a stutter.
The old fix was manual and incomplete. UE4 relied on developers manually recording and bundling PSOs into the build ahead of time. It worked, but it was tedious for large projects and still left gaps — Epic's own words were that it "could be burdensome for large projects, and still leave gaps in the cache leading to hitches."
Epic is actively patching this, version by version. UE5.1 introduced Automated PSO Gathering to replace the manual process, and UE5.2 added the ability to skip drawing an object if its PSO isn't ready yet instead of stalling the frame. That's a tacit admission this was a real architectural problem, not a one-off bug.

So it's less "this didn't exist in UE4" and more "UE4 could mostly hide it behind DX11, and UE5's push into DX12/Vulkan plus Nanite/Lumen's sheer number of shader permutations made it impossible to hide anymore." Which also means: modern games are compiling and caching more shader variants than ever, feeding the exact kind of unmanaged, ever-growing cache this whole post is about.

The part nobody tells you

Once a shader is compiled and cached, nothing ever removes it — not when you finish playing the game, not when you uninstall it, not when a driver update makes an old cache entry irrelevant. DXCache just grows. Forever. One direction only.

And by default, the NVIDIA Control Panel setting that controls this — Manage 3D Settings → Shader Cache Size — is set to "Driver Default." The full dropdown looks like this:

Driver Default
Disabled
128 MB
256 MB
512 MB
1 GB
5 GB
10 GB
100 GB
Unlimited

Here's the part that surprised me: NVIDIA's own documentation on what "Driver Default" actually resolves to is close to nonexistent. The only official description I could find comes from the driver 495/496.13 release notes, which introduced this setting with a single sentence: "Added Shader Cache Size control to set the maximum amount of disk space to use for storing shader compiles." That's it. No page explaining what number "Driver Default" maps to, no doc on the eviction policy once a limit is hit, nothing on how it interacts with per-game overrides. It's telling that even developers on NVIDIA's own developer forum have publicly asked whether any detailed documentation of the caching policy exists at all — without getting a concrete answer. So "Driver Default" isn't a documented default in the "this is 2GB, here's why" sense — it's a black box that, in practice, behaves like there's effectively no ceiling, which tracks with mine sitting at nearly 100GB without me ever touching the setting.

So the math is simple: every game you've ever installed, played for an hour, and uninstalled left a tip behind in DXCache, and it's still there. I'd been PC gaming for years without ever touching that setting, which is exactly how a folder quietly gets to 100GB without a single warning, notification, or disk-cleanup prompt from Windows.

Why this is worse than it sounds

A few things make this specifically sneaky, rather than just "oh well, cache happens":

It survives uninstalls. Deleting a game does not touch its shader cache. The game is gone; the cache is forever.
Windows Disk Cleanup doesn't know about it. It's not temp files in the usual sense — it's driver-managed and lives outside the paths Windows normally offers to clean.
The default has no limit. Most caching systems assume someone eventually caps them. This one ships wide open by default.
It's invisible until you go looking. There's no indicator anywhere in the NVIDIA app or Windows that tells you this folder exists, let alone how large it's gotten.

It's not a bug in the "crash" sense. It's a design decision — unlimited-by-default plus no lifecycle management — that quietly behaves like a slow memory leak, except on your disk, and over years instead of hours.

The DX12 caveat, because I got this wrong at first

Worth being upfront about a wrinkle here: the Shader Cache Size setting in the NVIDIA Control Panel primarily governs the DX11 and older cache path. A lot of modern DX12 and Vulkan titles manage their own shader caching independently, sometimes in different folders, sometimes with their own size limits, sometimes with none. So DXCache specifically tends to fill up from DX11 titles, but it's not the whole picture — if you're chasing every byte, check your Vulkan cache and any per-game shader cache folders too (many are under %LOCALAPPDATA% as well, just organized differently per engine).

What I did about it

Checked the actual size first. Right-click → Properties on the folder, or in PowerShell:

   Get-ChildItem "C:\Users\<Username>\AppData\Local\NVIDIA\DXCache" -Recurse | Measure-Object -Property Length -Sum

Deleted the contents, not the folder itself — NVIDIA will rebuild it as needed. The cost of clearing it is a few seconds of shader recompilation stutter the next time you launch each game, which is a fair trade for 100GB.
Set an actual limit in NVIDIA Control Panel → Manage 3D Settings → Global Settings → Shader Cache Size. I put mine at 10GB. Plenty for active games, capped for everything I've since uninstalled.

Worth knowing: once the cache hits that limit, the driver doesn't just stop adding new entries — it starts evicting old ones to make room. So if you play a lot of heavy titles at once and set the cap too low, you can end up with cache getting wiped out and rebuilt constantly, which brings back the exact stutter this whole system exists to prevent. 10GB was comfortable for my library; if you've got a dozen big games installed at once, you may want more headroom.

Made a note to check it again in six months, because "set it once and forget it" is exactly the mindset that got me to 100GB in the first place.

The bigger pattern

This isn't really an NVIDIA-specific story once you zoom out. It's the same shape as a dozen other quiet disk hogs: Docker's dangling image layers, npm's global cache, browser service-worker caches, pip's wheel cache. Anything designed to cache the output of expensive work will keep that output around forever unless something explicitly ties its lifetime to the thing that created it — and "unlimited by default" is a decision, not an oversight, that someone made and shipped.

Caches without owners don't fail loudly. They just sit there, growing, until you go looking for missing disk space and find out where it's been hiding the whole time.

If you're on NVIDIA and haven't checked, it might be worth a look:

C:\Users\<Username>\AppData\Local\NVIDIA\DXCache

You might be surprised what's in there.

Three Questions I Ask Myself Before Adding a Dependency

Den — Thu, 03 Sep 2026 20:02:46 +0000

Every time I'm about to type npm install or pip install, I pause for a second. Not because I'm against libraries — I use them every day. It's because I once got burned on a project where package.json grew to 340 lines, and nobody could explain why half of those packages were there.

Since then, I ask myself three questions. Nothing philosophical — they take less than a minute, but they save hours of untangling version conflicts and weird bugs six months down the road.

Question 1: Can I really not write this myself in 20 lines?

This is the most common source of self-deception. A library looks convenient because it "solves the whole problem," but often I only need 5% of what it does.

The classic example is left-pad (yes, the one that broke half of the npm ecosystem in 2016). Padding a string on the left is a one-liner. It doesn't need to be a package with dependencies, tests, and versioning — it's literally:

const leftPad = (str, len, ch = ' ') => str.padStart(len, ch);

I'm not saying all utility packages are evil. But if a function fits in 15-20 lines and doesn't need to handle edge cases I'll never actually encounter, I write it myself. The upside: I know exactly how it works when it breaks at 2 a.m. a year from now.

The check is simple: I open the package source. If it's 200 lines of code and 15 dependencies for functionality I'm using 10% of — that's a red flag.

Question 2: Who maintains this, and what happens if that person disappears tomorrow?

This isn't a question about code quality today — it's about risk a year or two from now. I look at a few things:

When was the last commit. Not "how long since the last release" — a package can be stable and just not need updates. What I care about is whether the maintainer responds to issues and PRs.
How many maintainers. A single person maintaining something in their spare time isn't a dealbreaker, but it's a risk — especially if the package isn't a small utility but something a critical part of my project depends on (auth, money handling, data parsing).
Are there active forks. If the original project has gone quiet but a fork is thriving, the community may have already voted with its feet, and that's where I should be looking instead.

There's no universal threshold like "three months without a commit is bad." Sometimes a package just does one thing well and there's simply nothing to fix. The real question is: if it breaks, or a vulnerability is found, who fixes it, and how fast?

Question 3: What happens to my project if I remove this dependency in a year?

This question is about architectural coupling, not the library itself. I try to picture the scenario in advance: the library goes unmaintained, or I just want to swap it for something else. How deeply has it embedded itself in my code?

If the dependency is used in one module behind a clean interface, replacing it is a one-day job. If its calls are scattered across the whole project, and its specific abstractions (custom state types, an unusual API) have become part of my own design, I'm stuck with it forever — even if I stop liking it.

The practical takeaway: I try to wrap third-party libraries behind my own thin abstraction layer, especially for non-critical things like logging, an HTTP client, or date formatting. Not for the sake of "clean architecture" as an abstract virtue, but because it literally lowers the future cost of replacement from "rewrite half the project" to "rewrite one file."

What this actually looks like in practice

I'm not anti-dependency. I use React, FastAPI, pytest without a second thought, because the answer to all three questions is obvious: writing something comparable myself is unrealistic, maintenance is strong, and the coupling is so fundamental that replacement isn't even a real question.

But every time I'm about to add a package for something small — date formatting, a debounce function, deep object comparison — I spend a minute on these three questions. Sometimes the answer is "yes, install it." Sometimes I close the terminal and write 10 lines myself.

Fewer dependencies isn't the goal by itself. But every one I add is a future responsibility I'm taking on without thinking, unless I ask myself these questions first.

The Memory Limit That Didn't Kill Anything

Den — Wed, 02 Sep 2026 17:37:13 +0000

The process that runs my language model has a habit of growing. Not dramatically — it starts at a reasonable size and drifts upward over a shift, and the cause is somewhere in code I don't own. I spent a day trying to configure the leak away, failed, and did the sensible thing instead: stopped trying to fix it and put a ceiling on it, so the damage would be confined to one service instead of the whole box.

I gave it a soft ceiling. MemoryHigh in the unit file, a bit under what I'd measured the process to need.

That is how I turned a leak into an outage.

Everything was green

The symptom, when it arrived, was that nothing was wrong. The service was active (running). Its PID was current, its log had no errors, and top showed a process of unremarkable size. Every dashboard I had said the system was up, and it was up. It was just doing a batch of work — the kind that normally takes minutes — for most of a day.

The thing you have to understand about a soft limit is what the kernel does when you cross it. It doesn't kill the process. It doesn't return an allocation failure. It applies back pressure: it reclaims pages, pushes what it can to swap, and throttles the process's allocations until it fits back under the line. From inside the process, memory still works. Every allocation succeeds. Nothing raises. The program is simply slower, by a factor that has no upper bound, because its working set now lives on a disk.

A hard limit produces an event. A soft limit produces a symptom. MemoryMax kills the process, systemd restarts it, and you lose one unit of work loudly. MemoryHigh keeps it alive and makes it useless, and there is no line in any log that says so.

Where the truth was

Not in top. Resident size looked fine — that was the point, the kernel was keeping it fine.

The truth lives in the cgroup's own counters, which nobody looks at because nothing points you there:

cat /sys/fs/cgroup/system.slice/<service>/memory.events
cat /sys/fs/cgroup/system.slice/<service>/memory.swap.current

memory.events has a high counter — the number of times the process was throttled at the soft ceiling — and an oom_kill counter. Mine read a throttle count in the millions against zero kills. That pair is the entire diagnosis in two numbers: nothing died, everything was strangled. And memory.swap.current said that essentially all the swap on the machine belonged to this one service.

When a process is slow for no reason, check whether something is holding it under water on purpose. A limit you set yourself is the easiest cause to overlook, because you remember configuring it as a safety measure and safety measures aren't suspects.

The measurement that caused it

The ceiling wasn't arbitrary. I measured the process's working size and set the limit above it.

I measured it at the wrong moment. I took the number shortly after the model loaded, which is the calmest instant in that process's life: weights in memory, nothing computed yet, none of the caches and scratch buffers that only exist once real work is running. The number I recorded was a startup value wearing the label "working set". The real figure under load was meaningfully higher, and my ceiling landed underneath it.

So the process spent its life a few percent over a line it could never get back under, being throttled continuously, on every batch, forever.

A limit derived from a measurement inherits every flaw in how you measured. If the measurement was taken when the system was idle, the limit is a limit on idleness. Sample under load, or don't sample.

Slowness is not a local property

Here's the part that turned a slow service into a dead website.

The worker reads its queue from Postgres and then, in the same transaction, goes off to the model. That was already sloppy, and for a batch that takes minutes it was survivable sloppiness. With the batch now taking most of a day, the worker sat in idle in transaction for most of a day, holding a perfectly ordinary read lock on one table.

Then a deploy landed. Startup ran a migration, the migration wanted ALTER TABLE, and the ALTER queued behind the worker's read lock. Fine so far — a migration waiting is not an outage.

Except for the Postgres behaviour that everyone learns exactly once: a waiting AccessExclusiveLock blocks everything that queues up behind it. The migration wasn't just waiting, it was a wall. Every subsequent query against that table joined a line behind a lock that would not be granted until a language model finished a job it was never going to finish on time. The API never reached listen. Its last log line was Waiting for application startup, and systemctl reported it active (running), which was true and worthless. nginx returned 502 for everything except static images.

The whole cascade fits in one query, which is the one thing I'd want anyone to take from this:

SELECT pid, state, wait_event_type, left(query, 60) FROM pg_stat_activity;

An active | Lock | ALTER TABLE … sitting next to an idle in transaction | SELECT … is not a clue. It's the answer.

Both sides are fixed now, because both sides were wrong: DDL runs with a lock_timeout and logs who was holding, and the worker closes its transaction before it goes anywhere near the model. Never hold a database transaction across a call to something whose duration you don't control, and treat a lock without a timeout as a promise to hang the table rather than a promise to wait.

The alarm that had been ringing so long it was quiet

I found all of this by accident, which was its own lesson.

There was an hourly health check, and it had been finding problems the entire time. It said nothing, because alert state was stored as a single boolean for the whole system, and the rule was to notify on change. Chronically elevated swap had set that flag days earlier and it never came back down — so when new failures appeared underneath it, first the worker falling behind, then the API not answering, the state didn't change, and not one message was sent. Meanwhile the morning summary printed the numbers with no verdict attached and signed off with "all services running."

An alarm that stays silent because the system was already unhealthy is worse than no alarm, because it manufactures the feeling of being watched. State has to be tracked per check, not per system; unresolved problems have to keep repeating rather than being deduplicated into silence; and no report gets to print an all-clear until every check has actually passed.

What I'd take from it

I set the soft limit because a hard one felt violent — killing a process over a few megabytes seemed like an overreaction, and back pressure sounded like the gentler, more grown-up choice.

It's the opposite. The hard limit fails: the process dies, systemd brings it back, one batch is lost, and the log says exactly what happened. The soft limit degrades: nothing fails, nothing is logged, no counter you routinely look at moves, and the system quietly stops doing its job while continuing to report that it is doing its job. One of those is an event you can build on. The other is a fact your monitoring is structurally unable to notice.

Prefer the failure you can see to the degradation you can't. It's the same rule I keep arriving at from other directions — an absent value beats a wrong one — because the common thread isn't memory or validation. It's that a system which fails loudly is one you can operate, and a system which merely gets worse is one you find out about from your users.

The limit is gone now. In its place: a hard cap, and swap turned off entirely for that service. If it grows past what the machine can give it, it dies, and I hear about it.

Both of those are better than what I had, which was a process that was alive the entire time.

ValidationError Is Not a Policy

Den — Mon, 31 Aug 2026 18:01:21 +0000

Every article about data validation ends in the same place. Mine does too: define the schema, validate at the boundary, and when the payload doesn't match, raise. That's an honest end to the topic and a dishonest end to the job.

raise ValidationError is punctuation. It states that this record is wrong. It says nothing about what the system owes the record next — and that part isn't a matter of taste. It's decided by one question:

Who is supposed to fix this, and can they?

The tutorial always assumes the same answer: a client sent bad JSON, you return 400, and the client fixes it. That's one boundary out of several, and it's the only one where the fixer is a person who will read your error message.

I run a science-and-tech digest that has three boundaries inside one process, with three different answers. The validation code is nearly identical in all three. What happens on the line after it isn't.

Data from strangers: nobody is going to fix it

Feeds are the classic hostile-but-not-malicious input. Publishers ship entries with no link, entries whose title is a chunk of HTML, entries with no date, and occasionally a document that isn't well-formed at all. None of these people are waiting for my error message.

The first decision isn't whether to reject. It's what to reject.

The naive version validates the feed: one malformed entry and the whole poll fails, so a publisher's typo silences a source for as long as the typo lives. What I do instead is validate per entry — an entry with no link or no title is skipped, the rest of the batch is kept, and nothing anywhere logs an incident, because this isn't one.

Reject the smallest thing you can name. The unit of rejection is a design decision and it's usually more consequential than the rule that triggered it. Get the unit wrong and a correct validator becomes an outage with good intentions.

The second decision is subtler, because sometimes I don't reject at all. Entries without a date get stamped with the time I saw them. That is, plainly, a fabricated value — the kind of thing every validation article tells you not to do. I do it anyway, because I can say exactly what it costs: the item is at most slightly too fresh, freshness decays over hours, and it leaves the ranking window on its own. What it buys is that the article exists at all, and a dropped article never comes back.

A default is a lie you've decided you can afford. Which is fine, as long as you can name the price. If you can't, you haven't chosen a fallback — you've chosen not to think about the case.

The third decision has nothing to do with validity. Some feeds — WordPress archives especially — hand you their entire history on a normal poll. Every entry perfectly valid, every field present, and accepting all of them would bury everything published this morning under a decade of old posts. So there's a ceiling on how many entries I take from one feed per poll.

Validity says nothing about quantity, and quantity is its own failure mode. A schema will happily certify ten thousand records that shouldn't have arrived together.

Data from a generator you invited: there's nobody to return the error to

This is the boundary the tutorials don't cover, and it's the one that made me write this. When a model returns a translation my checks reject, the 400 has no recipient. There's no client to notify, no caller to fix its request, no human on the other end of the connection.

Detecting the bad value is its own story, and I've told it separately: a schema-valid response can hold the right number of fields with the wrong language inside them, or a correct headline with a foreign clause welded onto its tail — which a share-based check waves through every time, because by proportion the correct text wins comfortably. The short version is that structured output guarantees shape and nothing about meaning, so the semantic validator is yours to write and it's about as much code as the schema.

Here I care about the line after that check. Not how the bad value is caught, but what the rejection becomes.

If a rejected translation is simply dropped, that's not validation, that's deletion. The next pass through the pipeline takes fresh work off the top; it never revisits what quietly disappeared. Rejecting a value and moving on feels rigorous and is indistinguishable, downstream, from never having tried.

What makes it real is that the rejection leaves a shape behind. The slot stays empty rather than being filled with the bad value, and empty is exactly what the regeneration path looks for. The record's own state is the queue. Nothing needs to be enqueued, retried, or remembered elsewhere, because absence is already the signal.

When there's nobody to return the error to, the rejection has to become a work item — or it's a deletion with better manners. And the corollary that decides your data model: never store a wrong value where an absent one would fit, because absence is a state the system can act on and wrongness looks exactly like success to every query you'll ever write.

Data from yourself: stop

The third boundary is configuration, and its policy is the opposite of the first two. Skipping is wrong. Substituting is wrong. Continuing is wrong.

The database URL in this project used to have a sensible-looking default pointing at a local file. With an unconfigured environment the application started perfectly, connected to an empty database, served an empty feed, and reported nothing unusual, because nothing unusual had happened by its own account. The symptom presented as "the feed is quiet today" rather than "the database was never configured", and those two look identical from the outside for as long as you're willing to keep looking.

The default is gone. The process now refuses to start and says which variable is missing.

The dangerous default is the one that works. A fallback that crashes on first use is a typo with a stack trace. A fallback that lets the process come up healthy is a phantom system: fully operational, structurally sound, connected to nothing. Config isn't the place for resilience — there is no degraded mode worth having when the thing that's misconfigured is what the service is for.

The line after the validator

Same library, same schema shape, three boundaries, three policies:

from strangers — skip the smallest failing unit, substitute only where you can price the lie, and cap the volume separately from the validity;
from a generator — turn the rejection into a state the pipeline reads as unfinished work;
from yourself — refuse to start.

None of that is derivable from the schema, because the schema doesn't know who's on the other side of the boundary. It knows what the data should look like. Whether a wrong record is somebody else's problem, your system's own backlog, or a reason to stop the process is a question about ownership, and it's yours to answer for every boundary you draw.

Validation tells you the data is wrong. It never tells you what you owe it.

This is the third of three on the same seam, and they read in any order:

JSON and Data Validation in Python — the contract: json, jsonschema, Pydantic, and where to put the boundary.
The Schema Was Valid. The Translation Was in Chinese. — what a schema doesn't buy you when the producer is a language model.
This one — what the system does on the line after the rejection.

All three come out of the same science-and-tech digest.

JSON and Data Validation in Python: From File Reading to Strict Contracts

Den — Mon, 31 Aug 2026 14:34:52 +0000

JSON (JavaScript Object Notation) is a text-based data interchange format that has become a de facto standard in modern web development. Thanks to its simplicity, readability, and language independence, JSON is used everywhere: for exchanging data between clients and servers through APIs, storing configuration files such as settings.json, and recording application events in logs.

In the Python ecosystem, JSON support is available directly in the standard library, while data validation can be handled with specialized libraries.

Working with JSON in Python

You don't need to install any third-party packages to work with JSON. Python's standard library includes the json module, which can convert JSON strings and files into native Python structures such as dictionaries and lists, and convert them back to JSON.

Reading JSON from a file

import json

with open("data.json", "r", encoding="utf-8") as file:
    data = json.load(file)

If the JSON data is already available as a string, for example as a response received from an external API, use loads():

import json

json_string = '{"name": "John", "age": 42}'
data = json.loads(json_string)

print(data["age"])  # Output: 42

The distinction is simple:

json.load() reads JSON from a file-like object.
json.loads() parses JSON from a string.

Writing JSON back to a file

It is important to remember that the json module works with objects in memory. If you modify the data, you must explicitly write it back to a file if you want to persist the changes.

import json

# Add a new field
data["company"] = "Tech Company"

with open("data.json", "w", encoding="utf-8") as file:
    json.dump(data, file, indent=4, ensure_ascii=False)

The indent=4 parameter formats the JSON with indentation, making the file easier for humans to read.

ensure_ascii=False keeps non-ASCII characters readable instead of converting them into Unicode escape sequences.

For example, without it, text such as:

{
    "name": "\u0410\u043d\u0434\u0440\u0435\u0439"
}

may be produced instead of:

{
    "name": "Андрей"
}

Why Do We Need Data Validation?

Imagine that your application receives JSON from a mobile client.

A developer working on the mobile application accidentally renames the user_id field to userid. Your backend may then fail when it tries to access the missing key:

user_id = data["user_id"]

This results in a KeyError.

An even more dangerous situation occurs when the structure is correct but the data type is not. For example, the server expects an integer:

{
    "age": 25
}

but receives:

{
    "age": "twenty-five"
}

An operation expecting a number may then fail with a TypeError.

This is why applications often use schemas and data validation.

A schema describes the expected structure of the data: which fields are allowed, which fields are required, what types their values must have, and what additional constraints apply.

In other words, a schema acts as a contract between different parts of a system.

Strict Validation with `jsonschema`

You can write validation manually:

if not isinstance(data.get("age"), int):
    ...

However, as the data structure becomes more complicated, manually maintaining dozens or hundreds of such checks quickly becomes difficult.

A more standardized approach is the jsonschema library.

Install it with:

pip install jsonschema

Let's define a strict user contract.

from jsonschema import validate, ValidationError

# 1. Define the contract
user_schema = {
    "type": "object",
    "properties": {
        "username": {
            "type": "string",
            "minLength": 3
        },
        "age": {
            "type": "integer",
            "minimum": 0
        },
        "email": {
            "type": "string",
            "format": "email"
        },
        "is_active": {
            "type": "boolean"
        }
    },
    "required": ["username", "age"],
    "additionalProperties": False
}

# 2. Data received from an external source
incoming_data = {
    "username": "john_smith",
    "age": 25,
    "email": "john@example.com",
    "is_active": True
}

# 3. Validate the data
try:
    validate(instance=incoming_data, schema=user_schema)
    print("Data is valid. It can be stored in the database.")

except ValidationError as error:
    print(f"Data validation error: {error.message}")
    # The API could return HTTP 400 Bad Request here.

The important part is:

"additionalProperties": False

It means that fields not explicitly defined in the schema are rejected.

For example, this object would fail validation:

incoming_data = {
    "username": "john_smith",
    "age": 25,
    "role": "admin"
}

because role is not part of the contract.

This can be extremely useful for APIs where silently accepting unexpected fields could lead to bugs or security problems.

More Complex Validation Rules

JSON Schema supports much more than simple type checking.

For example, enum restricts a value to a predefined set:

{
    "type": "string",
    "enum": ["admin", "editor", "viewer"]
}

Only one of these three values will be accepted.

Regular expressions can be used with pattern:

{
    "type": "string",
    "pattern": "^[A-Za-z]+$"
}

This example allows only Latin letters.

JSON Schema can also describe arrays, nested objects, numeric limits, string lengths, conditional requirements, and relationships between fields.

As a result, even fairly complex API contracts can be described declaratively instead of implementing every rule manually in Python.

An Alternative Approach: Pydantic and Type Hints

There is another popular approach in modern Python applications: using Pydantic models.

Instead of describing the structure as a dictionary containing a JSON Schema, you describe it using Python classes and type annotations.

For example:

from pydantic import BaseModel, EmailStr, ValidationError


class User(BaseModel):
    username: str
    age: int
    email: EmailStr
    is_active: bool = True


try:
    user = User(**incoming_data)

    print(user.model_dump_json(indent=2))

except ValidationError as error:
    print(error.errors())

This approach provides several useful features.

Pydantic can parse incoming data and, where appropriate, convert compatible values to the declared Python types.

For example:

incoming_data = {
    "username": "john_smith",
    "age": "25",
    "email": "john@example.com"
}

Depending on the field and Pydantic configuration, the string "25" can be parsed as the integer 25.

The resulting object is no longer just an arbitrary dictionary. It is a User instance with a defined structure and validated fields.

The default value also means that is_active does not have to be supplied:

class User(BaseModel):
    username: str
    age: int
    email: EmailStr
    is_active: bool = True

If the field is omitted, Pydantic uses True.

Pydantic in API Development

Pydantic is widely used in modern Python web applications and is a core part of frameworks such as FastAPI.

One of its major advantages is that the same model can serve multiple purposes:

validate incoming data;
provide typed Python objects;
serialize data back to JSON;
describe API schemas;
generate API documentation.

This makes Pydantic particularly convenient when building typed REST APIs.

Instead of passing unvalidated dictionaries throughout the application:

def process_user(data):
    ...

you can work with a well-defined model:

def process_user(user: User):
    ...

The difference becomes increasingly important as the application grows.

A Practical API Validation Workflow

In a typical backend application, validation should happen at the system boundary — before untrusted external data reaches the business logic.

The workflow looks like this:

Client
   │
   ▼
JSON request
   │
   ▼
Validation
   │
   ├── Invalid ──► HTTP 400
   │
   ▼
Validated data
   │
   ▼
Business logic
   │
   ▼
Database

The basic process is:

Receive the JSON request body.
Parse the JSON.
Validate it against the expected schema or model.
If validation fails, collect the validation errors.
Return a structured HTTP error response, typically with a 4xx status code.
Only after successful validation pass the data to the business logic.
Store or process the validated data.

This creates a clear boundary between untrusted external input and internal application state.

Why Strict Contracts Matter

Without validation, every function that receives external data has to protect itself:

if data and "username" in data and data["username"] is not None:
    ...

Then another function adds its own checks:

if "age" in data and isinstance(data["age"], int):
    ...

And another one checks something else.

Over time, this leads to duplicated validation logic scattered throughout the codebase.

A schema or model moves these checks to a single, well-defined boundary.

After validation succeeds, the rest of the application can operate under a much stronger assumption:

If the data reached the business logic, it already satisfies the contract.

That does not eliminate the need for error handling, but it dramatically reduces the number of defensive checks required throughout the code.

JSON Is More Than Just a File Format

JSON itself is simple. The difficult part is usually not parsing JSON — it is ensuring that the data represented by JSON actually matches what the application expects.

For small scripts, the standard json module is usually enough.

For APIs and larger applications, schema validation becomes increasingly important. Depending on the architecture, jsonschema, Pydantic, or another validation system can turn loosely structured JSON into a well-defined data contract.

The result is not just cleaner code. It is a system where the boundaries between components are explicit, errors are detected earlier, and changes to data structures are much easier to control.

The Schema Was Valid. The Translation Was in Chinese

Den — Mon, 31 Aug 2026 14:16:55 +0000

Constraining a model's output with a JSON schema feels like the moment the LLM stops being a text generator and becomes a function. You declare the fields, the server enforces the grammar, and what comes back parses every time. After months of regex-scraping JSON out of prose, it's a genuine relief.

Then you ship it, and you find out what a schema actually promises. It promises a shape. Everything you care about is content, and content is on you.

Here's the list of things that came back schema-valid and wrong, in the order I found them.

The array was the right shape and the wrong length

The model processes several items per call and returns one object per item. The schema says: an array of objects, each with these required fields.

Sometimes it returned one object for three inputs. Perfectly valid — an array of one is an array. The schema constrains what an element looks like; it has no idea how many elements you were expecting, because it never saw your input.

The fix is boring and unavoidable: reconcile the response against the request by id. Send ids in, require ids back, diff the sets, and re-ask individually for whatever went missing. What made this worth catching rather than shrugging at is what silence would have cost — a dropped item doesn't come back around on the next pass, because the next pass selects a fresh top slice of new work. "Probably fine, it'll get picked up later" is only true if something actually picks it up later.

The same reconciliation gives you a free failure mode for the whole batch: if the entire call times out, retry the items one at a time instead of losing all of them to one pathological input.

The field was a string, and it was the wrong language

Each item comes back with a translations object: one key per target language, each holding a title and summary.

A small model mixes those slots up. Under the key for one language, you get fluent text in a different one — sometimes the source language untranslated, sometimes a language nobody asked for. The schema is entirely satisfied: the required key is present, its value is an object, the fields are strings. All true. All useless.

So you write the check the schema can't: does this text use the writing system its language key implies? Count characters by script, compare to what's expected for that key, reject the mismatch.

This works, and it's the easy half.

The hard half: the wrong language glued onto the right one

The check above compares shares — the language's own script should dominate. That catches wholesale substitution and misses the failure that actually reached my users.

The model sometimes finishes a translation correctly and then keeps going, appending a second translation into the same field. What ships looks like a correct headline with a foreign clause welded to its tail. By share, the correct text wins comfortably — the tail is a fraction of the string. The dominance check passed it every time, and a batch of headlines went out with a foreign fragment stapled on the end.

The fix isn't a better ratio. It's noticing that ratios are the wrong tool here:

A threshold that looks reasonable will catch the common case and wave through the dangerous one. Any share-based test assumes the two things being weighed are commensurable. Correct output and corrupt output aren't. Two characters of a script that has no business appearing is not a small problem in proportion to the string — it's the whole failure, at any size.

So the rule became presence, not proportion: scripts that cannot legitimately appear in this language are rejected on sight, at a count of one.

The nuance that makes it survivable is knowing where not to apply zero tolerance. Latin characters stay legal everywhere, because product names, acronyms and companies are legitimate in any language, and banning them would reject far more good translations than it saves. Zero tolerance is only affordable where you can name the reason no legitimate case exists. Otherwise you're just building a stricter bug.

The field was populated, and the contents were filler

The schema language tempts you to push semantics into it. My keyword list looked like a great candidate: require at least three entries, and the model has to produce three.

It does. It pads. Ask a summarizer for a minimum of three keywords per science article and the shortfall gets filled with study, research, science — perfectly valid strings, perfectly useless index terms, and worse than an empty list because now they're indistinguishable from real ones.

I dropped the minimum. The schema's job is to guarantee the field exists and holds strings; how many there should be is a question about meaning, which belongs to the prompt. An upper bound stayed, and only because it matches a truncation the code performs anyway — no point paying to generate items you're about to throw away.

A schema can force a field to exist. It cannot force it to be worth having. Every constraint you add gets satisfied by the cheapest available route, and for a minimum count the cheapest route is filler.

What to do with a value you've rejected

Having caught a bad translation, the instinct is to keep it — something is better than nothing, surely.

It isn't. I drop it and leave the slot empty, which gets you two things. The reader sees an honest fallback to the original language instead of confident nonsense in theirs. And an empty slot is a work item: a later pass sees a missing translation and regenerates it, whereas a filled slot containing garbage looks done forever.

Prefer an absent field to a wrong one. Absence is a state your system can act on. Wrongness looks exactly like success to every piece of code downstream.

Two things about the plumbing

Not every server accepts your schema. Older runtimes reject the schema object outright with a 400. Retrying without it is right, but retry and remember — flip a flag for the process, so you're not paying two round trips for every call from then on. Degrade to prompt-only and log it loudly.

Parse defensively even with a grammar. Whether the wrapper is an array, a sequence of bare objects, or a single object varies with the model and whether the schema survived. Rather than requiring one canonical shape, scan for top-level {...} and decode each one incrementally. It's a few lines, it's shape-agnostic, and it turns "the model wrapped it differently today" from an outage into a non-event.

What I'd take away from it

Structured output moved a whole class of problems — malformed JSON, missing keys, prose wrapped around the payload — from my code into the runtime, and that's a real win I wouldn't give back.

What it didn't do is make the output correct. It relocated the boundary. The grammar handles syntax; everything about meaning is still yours, and the failures that reach production are all on the meaning side, because syntax errors are loud and semantic ones are polite. Wrong language in the right slot, a foreign clause on the tail, three words of filler in a keyword list — every one of those was valid against the schema and would have been caught by five minutes of looking at what actually shipped.

So budget for the validator you write yourself, and expect it to be about as much code as the schema. Mine runs on a science-and-tech digest I maintain, where the model translates into several languages at once and every one of them is a slot it can put the wrong thing into. The schema stopped me from ever parsing a broken response. It never once stopped me from publishing a wrong one.

Everything worked when I looked at it. That was the bug.

Den — Mon, 31 Aug 2026 13:03:57 +0000

In the last post
I opened the source of Boolflow, my browser-based
digital logic simulator, and found that the roadmap I had confidently published
was in the wrong order. I ended it planning to build an explicit tick counter.

I did not build the tick counter. I opened the deployment instead, and spent the
day finding four things that had been broken for months while looking completely
fine.

That is the thread running through all of them. Not one of these bugs made
anything fail in front of me. Every single one was hidden by the normal path
working exactly as intended.

The prerenderer I wrote in June went live in August

Boolflow is a Vite SPA with a prerender step: prerender.mjs walks a route
table, renders each page with renderToString, and writes a real HTML file per
URL. I wrote it on 4 June. It has been sitting in the repository ever since,
correct and tested and doing nothing at all.

Here is what production actually served, on every URL:

/                          200  4493 bytes
/help                      200  4493 bytes
/ru/help                   200  4493 bytes
/ru/articles/karnaugh-maps 200  4493 bytes
/verilog                   200  4493 bytes
/nonexistent-page-xyz      200  4493 bytes

The same 4.5 KB on all of them. Same <title>. Same description. <div id="root"></div> — empty. It was the Vite build output before the prerender
step overwrote it.

The cause is three lines of package.json:

"build":       "vite build",
"prerender":   "node prerender.mjs",
"build:full":  "npm run build && npm run build:server && npm run prerender",

And one line of my own deployment guide, step 11, "Updating the application":

npm run build

The prerender lived in build:full. The documented update procedure called
build. Not sometimes — structurally, every time, for three months. The
deployment instructions I wrote could not have produced a prerendered site if I
had followed them perfectly.

And here is why I never noticed: the site looks perfect in a browser. You
request /ru/help, get 4.5 KB of empty shell, the JavaScript loads, React
hydrates, and the Russian help page appears. Every human visitor, including me,
saw a working site. Only crawlers — and anything else that does not execute
JavaScript — saw the shell.

The fix is embarrassingly small. build is now the whole pipeline:

"build":        "npm run build:client && npm run build:server && npm run prerender",
"build:client": "vite build",

You can no longer deploy half a build, because there is no longer a script that
produces half a build.

Meanwhile, every page told Google it was the homepage

The shell has a static <link rel="canonical" href="https://boolflow.site/"> —
correct for the landing page, meaningless for the other sixty-four URLs it was
being served as.

So the sitemap advertised 65 URLs, and all 65 responded with the same title, the
same description, and a canonical tag pointing at the homepage. That is not
"pages ranking badly." That is me explicitly instructing Google to collapse the
entire site into one page.

Three smaller things were wrong in the same layer, and all three had the same
character — a thing that returns 200 and looks fine:

/nonexistent-page-xyz returned 200. Every typo was an indexable page.
www.boolflow.site returned 200 with no redirect, so the whole site existed twice, on two hosts, with canonicals pointing at only one of them.
The sitemap was hand-maintained next to a script that already knew the exact route list. It had drifted, of course. It now gets generated from that route list, so it cannot advertise a URL that has no page.

The URL said Russian. The code asked localStorage.

Boolflow has EN/RU/DE. Articles and help live under /ru/… and /de/…. The
language context read the language from exactly one place:

const [lang, setLang] = useState(() => localStorage.getItem('boolflow-lang') || 'EN');

The URL is not in that expression. So /ru/help rendered its body from the
path and its chrome from localStorage, and the prerendered file proves it — a
Russian <h1> under an English header:

dist/ru/help  →  header: "How to use Boolflow"
                 h1:     "Справка Boolflow"

Worse, the provider also set document.documentElement.lang from localStorage,
so hydration rewrote the prerendered lang="ru" back to lang="en".

The URL prefix now wins, falling back to the stored preference only on paths
that have no prefix. One consequence I did not expect: the moment the URL became
authoritative, I found the translations for the landing page and all six tool
pages were already written — full EN/RU/DE copy, sitting in the source,
reachable only as a localStorage state. They had no addresses. Google had never
seen them and could not have.

Giving them addresses took an afternoon and added fourteen pages of content that
already existed.

The bug that survived because it was usually idempotent

This is the one I am actually pleased about, because it validated the last post
in a way I did not intend.

Stateful elements — flip-flops, counters, latches — keep their state in a
module-level Map, keyed by node id, mutated in place:

const st = nodeStates.get(n.id) ?? { q: 0, prevClk: 0 };
let q = st.q;
if (clk === 1 && st.prevClk === 0) q = d ?? 0;   // rising edge
nodeStates.set(n.id, { q, prevClk: clk ?? 0 });

simulate() runs more than once per logical tick. Boolflow has four layers, and
signals cross between them through named VIA elements, so the layer loop
simulates everything once, discovers the VIA values, then re-simulates the
layers that received them.

Normally that is harmless. Run it twice with the same inputs and you get the
same answer, because prevClk has already caught up and there is no edge left
to detect.

Except a VIA delivers its value on the second pass. So:

Clock goes 0 → 1. Pass one runs. D is still unresolved, null. The flip-flop sees the rising edge and latches 0. prevClk becomes 1.
The VIA value arrives. The layer is re-simulated with the real D.
prevClk is already 1. There is no edge. Nothing happens.

The flip-flop latches a stale value, and only when its data crosses a layer
boundary — which is the entire reason the layer feature exists.

Here is the test, replaying the layer loop verbatim with the same flip-flop wired
two ways:

D flip-flop, D held at 1, one rising clock edge. Expected Q = 1.

  same layer, direct wire   ->  Q = 1   ok
  D arrives through a VIA   ->  Q = 0   WRONG

The fix is to stop mutating one map. State is now split: committed is what it
was at the start of the tick, working is what is being computed during it.
Every pass reads from committed, so repeated passes recompute the same
transition with progressively better inputs instead of racing to consume the
edge first.

  same layer, direct wire   ->  Q = 1   ok
  D arrives through a VIA   ->  Q = 1   ok

Now the part I like. In the last post I argued that an explicit tick counter had
to come before waveforms and sequential tests, and I argued it on architectural
grounds — the engine has no notion of time, so features that need time cannot be
built honestly. It was a good argument and it was entirely theoretical.

It turns out the engine not knowing when a tick begins was not a future problem.
It was corrupting multi-layer clocked circuits in production. The invisible
refactor I was defending on taste was a bug fix with a reproduction case.

A captcha that rendered perfectly and could not be read

Admin login has an image captcha. I could not get past it. My first assumption
was that I was typing it wrong.

The endpoint is healthy: 200, image/png, 11875 bytes, correct https URL.
So I downloaded three and looked at them. 4U2S2 — the last 2 sliced off by
the right edge. W3NPQ — the Q running into the border.

Then the arithmetic. Each character is drawn into a 36×42 box and rotated up to
25° with expand=1, which makes it bigger than its box:

36·cos25° + 42·sin25° ≈ 50 px wide
36·sin25° + 42·cos25° ≈ 53 px tall

The canvas was 150 × 50. A single glyph did not fit vertically. And with a
start of x = 10 and a random advance of 22–26 px, the fifth character began at
98–114 and ended at 148–164 — off the right edge of a 150 px image.

Two round numbers, chosen once, never checked against the thing they had to
hold. The canvas is now derived from the glyph geometry rather than guessed:

canvas: 169 × 60   glyph: 49 × 52
right edge of last character: 161 ≤ 169

I also dropped the remaining lookalike characters — Q Z 2 S 5 B 8 6 V on top of
the O 0 I 1 L that were already excluded — leaving 22 characters and about 5.1
million combinations, which is plenty for something that allows five guesses.

To check it honestly I generated four captchas without looking at the answers,
read them, and only then compared. Three for three.

The tool pages had nothing to say to a crawler

An SEO audit flagged three URLs as thin. I counted the rendered words myself:

    9  /check         "All connections are complete."
   13  /truth-table   "No inputs or outputs on this layer."
   22  /verilog

The audit's advice was the usual boilerplate about ensuring sufficient word
count. Word count is not a ranking factor and padding pages is how you get
useless pages, so I ignored the advice — but the diagnosis was correct, and the
reason was structural rather than editorial.

These pages render the result of processing a circuit. With no circuit there is
nothing to render. And a crawler will never load a circuit — nor will a human
arriving from a search for "convert logic circuit to verilog", who lands on an
empty box and leaves.

So each tool now carries an explanatory section that does not depend on editor
state: what the tool does, a real sample of its output, the limitations, a link
to the relevant article. The samples are taken from what the exporters actually
emit, because a fake code sample in a page about generating code would be a
strange thing to ship.

   22 → 235  /verilog        9 → 219  /check
   13 → 220  /truth-table   21 → 259  /cpp

What the day actually cost

Honest accounting: I closed one of five roadmap items, and only half of it —
combinational test cases, which turned out to need none of the refactors I said
they needed. Everything else was infrastructure, and none of it was on any plan.

What changed for users: nothing visible. What changed for everyone who has ever
searched for a logic simulator: eighty-one pages that were previously
unreachable, in three languages, are now crawlable for the first time.

The pattern

I keep coming back to the shape of these four.

The site rendered. The flip-flop latched. The captcha returned a valid PNG. The
tool pages worked when you used them. In every case the thing I would naturally
check was the thing that was working, and the failure lived one step off the path
I ever walked: no JavaScript, a signal arriving late, the fifth character, an
empty editor.

The uncomfortable version of this lesson is that the more reliable your happy
path, the better it hides everything else. I have no clean method to offer. The
only thing that worked was going and looking at the artifact directly — curl
the URL instead of opening it, count the bytes, download the image and actually
look at it, replay the loop with the state printed.

Every one of these was found by looking at the output rather than at the code
that produces it.

Boolflow is free and open in the browser at boolflow.site.
The tick counter is next. This time I have a reproduction case for why.

I know what to build next. My own architecture disagrees about the order

Den — Wed, 26 Aug 2026 12:07:23 +0000

In the last post
I compared Boolflow, my browser-based
digital logic simulator, against nine other tools and came away with three
honest gaps: no sub-circuits, no waveforms, no test cases. I ended that article
with a tidy numbered list and the confidence of a man who had not yet opened the
files.

Then I opened the files.

This post is what I found. It is a roadmap, but it is the kind of roadmap you
get after reading your own code rather than before — which is to say the order
changed, the list got longer, and the reason is a single design decision I made
about eighteen months ago without noticing I was making it.

The fact underneath everything

Here is the whole simulation entry point. Fifty-six lines, and I am showing you
the load-bearing half:

export function simulate(nodes, edges, seedVals = {}) {
  const vals = { ...seedVals };

  // ... seed INPUT / CLOCK / CONST nodes into vals ...

  simulateComb(combNodes, getInput, vals);     // pass 1: upstream combinational
  simulateStateful(statefulNodes, getInput, vals);
  simulateComb(combNodes, getInput, vals);     // pass 2: downstream

  return vals;
}

Three phases. Combinational, then stateful, then combinational again. It takes a
flat list of nodes and edges and returns a flat object of wire values.

"Phase" rather than "pass", because each combinational phase is itself a loop —
it relaxes the whole network repeatedly until, in principle, everything settles:

export function simulateComb(combNodes, getInput, vals) {
  const iters = Math.max(combNodes.length * 2, 10);

  for (let pass = 0; pass < iters; pass++) {
    combNodes.forEach(n => { /* evaluate one gate into vals */ });
  }
}

Look at what is missing. There is no time parameter. There is no delay model, no
event queue, no notion of "before" and "after". simulate() does not advance a
simulation — it computes what all the wires settle to, right now, given the
current inputs. Call it twice with the same arguments and, for a purely
combinational circuit, you get the same answer twice.

Look also at what that loop does not do: it never checks whether anything
changed. It runs its full 2N iterations every single time, and it has no way to
report that the network failed to settle. I will come back to both of those at
the end, because together they turn out to be the cheapest thing on this entire
page.

Boolflow does not simulate time. It computes steady states.

That is not a bug. For a teaching tool it is arguably the right call: a beginner
toggling an INPUT wants to see the output change, not to reason about
nanosecond-scale propagation. It is also why the whole engine is under 600 lines
and runs instantly on every keystroke.

But it means time in Boolflow is emergent. It exists only because something
else happens to call simulate() again. And what calls simulate() again is
React:

const interval = setInterval(() => {
  setLayers(ls => ls.map(l => ({
    ...l,
    nodes: l.nodes.map(n => {
      if (n.data?.type !== 'CLOCK' || n.data.running === false) return n;
      return { ...n, data: { ...n.data, value: n.data.value ? 0 : 1 } };
    }),
  })));
}, Math.round(1000 / freq));

A setInterval flips the CLOCK node's value, React re-renders, a useMemo
recomputes the simulation. One clock tick equals one React render.

Every item on my roadmap collides with that sentence.

Sub-circuits: the problem is not drawing, it is identity

The visible half of sub-circuits is easy and boring: save a circuit, show it in
the palette, draw it as a box with pins. A weekend, maybe two.

The invisible half is this file, and specifically these four lines:

// Persistent state for edge-triggered / stateful elements.
// Lives at module level so state survives across simulate() calls.
export const nodeStates = new Map();
export function clearNodeState(id) { nodeStates.delete(id); }

Every flip-flop, latch, counter and register in Boolflow keeps its state in one
module-level Map, keyed by node id. A D flip-flop reads and writes it like
this:

const st = nodeStates.get(n.id) ?? { q: 0, prevClk: 0 };
let q = st.q;
if (clk === 1 && st.prevClk === 0) q = d ?? 0;
nodeStates.set(n.id, { q, prevClk: clk ?? 0 });

Note prevClk. That is how edge detection works: compare this call's clock value
to the previous call's. The flip-flop's entire sense of time is "the last time
somebody ran the simulation." It is a global mutable Map standing in for a
clock, and for a flat circuit it works perfectly well.

Now instantiate a sub-circuit containing that flip-flop twice.

Both instances contain a node whose id is, say, n7. Both read and write
nodeStates.get('n7'). Your two counters are now the same counter, wired to
different pins, fighting over one entry in a Map. Put a 4-bit register inside a
block and drop four of them on the canvas, and all four hold identical data
forever.

So sub-circuits are not a drawing feature. They are a request to make node
identity hierarchical: a node is no longer n7, it is
inst3/inst1/n7 — a path from the top-level sheet down through every enclosing
instance.

There are two ways out.

Recursive evaluation. Teach simulate() to descend into a sub-circuit,
evaluate it with its own scoped state, and return its outputs. Conceptually
clean. It also means threading an instance path through every function that
touches nodeStates, and it makes the value map — currently a flat
{"n7:out-0": 1} — into something nested or path-keyed.

Flattening. When a sub-circuit is placed, inline a copy of its nodes and
edges into the parent, rewriting every id to instanceId/originalId. The
simulator never learns that hierarchy exists; it keeps receiving one flat list,
just a longer one. All the work moves into the editor layer and one id-rewriting
function.

I am going with flattening, for three reasons. It leaves the simulation engine
almost untouched, which matters when the engine is the part I trust most. It
gives correct per-instance state for free, because rewritten ids are unique by
construction. And it is what Digital does
— its docs note that embedded circuits are included as often as the circuit is
used — which is reassuring, because Digital is the most rigorously built tool in
this category.

The cost is honest and worth stating: flattening a block used fifty times means
fifty copies in memory, and a deep hierarchy multiplies. A tool built for CPU
scale would not accept that. Boolflow is built for someone learning what a
register is, and at that scale I will take the trade.

Waveforms: I have to make time real first

A timing diagram plots signal values against time. I have signal values. I do
not have time.

What I have is a setInterval that mutates a React node and hopes. To draw a
waveform I need three things that do not exist yet:

An explicit tick counter — a monotonically increasing integer that says which simulation step we are on, owned by the simulator rather than inferred from React's render cycle.
A history buffer — a ring buffer recording the value map at each tick, for the last N ticks. This part is genuinely easy; simulate() already returns exactly the object that needs recording.
A step control — the ability to advance one tick deliberately, so a learner can walk a shift register through its states instead of watching it blur past at 4 Hz.

Item 3 is the one I actually care about. Watching a counter run is mildly
interesting; stepping it one clock edge at a time while reading the flip-flop
outputs is where the concept lands. Logicly has had step-by-step propagation
debugging for years and it is the single feature of theirs I have been quietly
jealous of.

While reading this code I also found a bug I had never noticed:

const freq = allClocks[0]?.data.freq ?? 1;

Every CLOCK element on the canvas ticks on one shared interval, running at
whichever clock happens to be first in the array. Give two clocks different
frequencies and Boolflow will cheerfully ignore you. Nobody has reported it,
which I suspect means nobody has tried — but the fix belongs in exactly this
refactor, because a real tick counter makes per-clock division trivial instead
of awkward.

There is one thing a waveform in Boolflow will not show, and I would rather say
it here than have someone find out the hard way: glitches. With no propagation
delay model, a hazard that a real circuit would exhibit as a brief spurious pulse
simply does not exist in my engine. The diagram will be idealised. For teaching
what a shift register does, idealised is fine and possibly better. For teaching
why you need a synchroniser, it is a lie, and the metastability article I wrote
will have to keep saying so in words.

Test cases: the cheap one, for a good reason

Of the three features this is the least work, and it is worth understanding why,
because the reason is not that testing is simple.

Boolflow already has a truth table generator. To build a truth table for a
combinational circuit you enumerate every input combination, force the INPUT
nodes to each combination in turn, run the simulation, and read the OUTPUT
nodes. That is: set inputs, evaluate, collect outputs, in a loop, headless,
without touching the canvas.

That is also exactly what a test runner does. The only thing a test case adds is
a column of expected values and a comparison. The machinery is already written
and already shipping.

For combinational circuits I could have this working in a couple of evenings.
For sequential circuits — the ones where testing actually earns its keep — a
test case is a sequence of steps with expected outputs after each one, which
means it needs the tick counter from the waveform work. So it is cheap, but only
after something else is done.

Digital's model is the one to copy: declare inputs and expected outputs in a
table, run, get pass or fail. It is also the missing half of "exercises with
checkable answers", which I promised readers two articles ago and have not
delivered.

So the roadmap has five items, not three

Reading the code turned a list of three features into a dependency graph:

make time explicit ──────┬──→ waveforms + step mode
                         └──→ sequential test cases

hierarchical node identity ───→ sub-circuits

Which gives an actual order:

Explicit tick counter and history buffer. Invisible to users. Unblocks two of the three features and fixes the shared-clock-frequency bug on the way past.
Step mode and the waveform panel. The first visible payoff.
Hierarchical node ids by flattening. Also invisible, also a prerequisite.
Sub-circuits. The largest gap against every other tool in the comparison.
Test cases, combinational first, sequential once step mode lands.

Two of the five ship with nothing to show for them. That is the part I did not
expect when I wrote the confident numbered list last month, and it is the honest
shape of the work.

Four more things the comparison suggested, and one trap

The five above are commitments. These are candidates — things I noticed while
looking at other tools, none of which I have promised anyone. I am listing them
because the cheapest one is genuinely embarrassing.

Tell the user the circuit did not settle. Remember that relaxation loop with
no convergence check. Add a comparison of vals before and after each iteration
and you get two things from about ten lines: an early break when the network is
stable, which stops a hundred-node circuit from grinding through two hundred
pointless iterations on every render — and the ability to say "this circuit is
oscillating" when the loop runs out without settling.

Right now a ring of three inverters just exhausts its iteration budget and
returns whatever state it happened to stop on. Boolflow reports a confident,
wrong answer with no warning at all. Oscillation detection is one of the marquee
reasons people move from Logisim to Digital; in my engine it costs ten lines and
I simply had not thought to look.

A link to a circuit. Falstad, CircuitVerse and DigiSim all let you send
someone a URL. Boolflow lets you download a JSON file and email it, like it is

The awkward part is that the backend for this already exists — the endpoints to store a scheme and fetch it by id have been written and working for months, and nothing in the UI ever calls them. This is not a feature, it is a missing button.

An <iframe> embed. This follows almost free from the link, and of
everything on this page it is the item with the best odds of mattering. In the v4
post I wrote that a browser tool has almost nothing for a search engine to index
and that this might decide whether anyone ever finds the project. An embed is the
answer to exactly that: every live circuit on somebody else's course page or blog
post is both a working demo and a way in. It is the only item here that
compounds.

A truth table that turns back into a circuit. Boolflow already goes from
circuit to truth table. Digital goes the other way too — you type the table you
want and it synthesises and minimises the logic. That is a self-contained module
that emits nodes and edges into the existing structures and touches the engine
not at all, and it would give the Karnaugh map article something to link to
instead of leaving the reader with nowhere to click. In the desktop tier Digital
has this. In the browser tier, essentially nobody does.

And the trap: buses. Multi-bit wires sit innocently in a feature list next to
those four, and CircuitVerse and LogicCircuit both have them. But today a wire
value is one bit — vals is a flat map of "n7:out-0" → 1. Making a port carry
four bits rewrites every gate in the combinational evaluator, all three
exporters, the wire renderer and the port definitions. It is the single most
invasive item anyone could reasonably ask me for, and it looks like the smallest.
I am not touching it before sub-circuits exist.

The pattern I did not expect: three of those four are cheap precisely because
they do not involve the simulator. The expensive work is all in the engine, and
the engine is the part I was proudest of.

What I am still not building

Unchanged from the comparison post: no accounts, no groups, no assignments, no
grading, no teacher dashboards. CircuitVerse has done all of that properly for
years, and there is no version of this where I do it better alone. If you need a
classroom platform, use CircuitVerse — I mean that as a recommendation, not a
concession.

Boolflow's job is to be the thing you open in a tab at 2am with no account and no
install, build something, and understand it.

Questions I would like answered

Flattening versus recursive evaluation — has anyone here built hierarchy into a simulator and regretted flattening? The memory cost is the obvious objection; I want to hear the non-obvious one.
Idealised waveforms — if you teach digital logic, is a timing diagram with no propagation delay useful, or is it actively misleading? I can fake a uniform unit delay per gate, but faking it convincingly may be worse than admitting the model has no delay at all.
Step mode granularity — one clock edge per step, or one gate evaluation per step? Digital does single-gate stepping specifically to debug oscillation. Clock-edge stepping is simpler and probably what a learner wants. I keep changing my mind.
Is two invisible refactors out of five a reasonable thing to publish? I went back and forth on whether a roadmap post should only contain things users can see.
Embeds versus sub-circuits — the disciplined answer is to finish the five before touching the candidate list. The other answer is that an embed takes a fraction of the effort and is the only item that brings new people in. If you have run a small project past this fork, I would like to know which way you went.

Boolflow is at boolflow.site — free, no account,
nothing to install.

Tell me which of these you would actually use, and I will believe you over my own
dependency graph.

I compared my logic simulator to 9 others. Here is where mine loses

Den — Wed, 26 Aug 2026 07:04:57 +0000

I have written four posts about Boolflow now — the first release, v2, v3 and v4. Every one of them was about what I added.

None of them answered the question I actually get asked, which is some polite variant of: Logisim exists. Why does this?

For a long time I did not have a real answer, because I had never done the work. So I did it. I spent a couple of weeks with nine other digital logic simulators — installing them, building the same handful of circuits in each, reading their docs and their source where it was available — and then I put my own tool in the same table and looked at the result.

The result is not flattering in the places you would expect, and it is better than I thought in one place I did not expect. Both halves are below.

The field

There is no single "logic simulator market". There are three clusters that barely compete with each other, plus one commercial outlier.

Desktop, free, open source. Logisim Evolution is the default answer in most university courses — GPL-3.0, Java, 7.5k stars, and still actively developed (v4.1.0 landed in February 2026). Digital by Helmut Neemann is the connoisseur's pick: GPL-3.0, 5.9k stars, and in several areas — test cases, circuit analysis, hardware export — genuinely ahead of Logisim. LogicCircuit is a free open-source Windows/.NET tool with unrestricted circuit hierarchy, multi-bit buses, a built-in oscilloscope and — since 2024 — HDL export to Verilog and Nand2Tetris. Deeds comes out of the University of Genoa and is the most curricular of the four — combinational and sequential design, an FSM editor, and a microcomputer emulator with a custom 8-bit CPU, all wrapped in course material. Windows only.

Browser, free. CircuitVerse is the serious one: MIT-licensed, subcircuits, timing diagrams, propagation delay control, Verilog modules, testbenches, and a full classroom layer with groups, assignments, deadlines, grading and grade export. Falstad's CircuitJS1 is GPL-2.0 and is really an analog simulator with digital parts — the animated current flow is unmatched for intuition, but it is not organised around gate-to-CPU teaching. simulator.io is clean and account-free to try, has real-time collaboration, and has a 2015 copyright line in its footer that tells you most of what you need to know about its development pace.

Commercial. Logicly is Windows and macOS, aimed squarely at teachers, with custom ICs and step-by-step propagation debugging. It costs $59 for a student licence, $599 for a classroom and $1,299 for a campus — one-time, not subscription.

And then there is DigiSim, which I found late and which is the closest thing to a direct competitor Boolflow has. Browser-based, real-time, four labs (digital, relay, electricity, analog), 61 components, narrated lessons in seven languages, freemium — the free tier gives you 16 of 61 components, Pro is $6/month, classroom is $4/seat/year. It is doing the same thing I am doing — putting the lessons inside the simulator — with a business model and more languages. Finding it was the least fun afternoon of this whole exercise, and also the most useful.

Boolflow, for the table below: browser-only, free, no account, 74 element types, 20 worked examples, exports Verilog / VHDL / C++, generates truth tables, four design layers linked by VIA nodes, and ships 17 theory articles in English, Russian and German.

The table

	Runs in	Price	Sub-circuits	HDL export	Waveforms	Classroom	Account
Logisim Evolution	Desktop (Java)	Free, GPL-3.0	Yes	VHDL + Verilog	Chronogram	No	No
Digital	Desktop (Java)	Free, GPL-3.0	Yes	VHDL + Verilog + JEDEC	Measurement graphs	No	No
LogicCircuit	Desktop (Windows)	Free, open source	Yes	Verilog + Nand2Tetris	Oscilloscope	No	No
Deeds	Desktop (Windows)	Free	Yes	VHDL	Timing diagrams	Course material	No
CircuitVerse	Browser	Free, MIT	Yes	Verilog	Timing diagram	Full	To save online
Falstad	Browser	Free, GPL-2.0	Yes	No	Scope	No	No
simulator.io	Browser	Free	No	No	No	No	To save
Logicly	Desktop + web demo	$59 / $599 / $1,299	Yes	No	Step debug	Teacher-oriented	No
DigiSim	Browser	Free tier / $6 mo	Yes	No	Yes	Paid tier	Optional
Boolflow	Browser	Free	No	Verilog + VHDL + C++	No	No	No

The bold entries in my own row are the ones that matter. Three of them are gaps.

Where Boolflow loses

I want to be specific here rather than doing the humble-brag thing where the weakness is secretly a strength.

1. No sub-circuits. This is the big one.

Every serious tool in that table lets you build a circuit, save it, and drop it into another circuit as a single block. Logisim, Digital, LogicCircuit, Deeds, CircuitVerse, Logicly, DigiSim — all of them. It is the feature that takes you from "I built a full adder" to "I built a 4-bit ALU out of four full adders" to "I built a CPU".

Boolflow does not have it. What Boolflow has is layers — up to four independent sheets connected by VIA nodes — and I have caught myself describing them as if they solve the same problem. They do not. Layers are a way to stop one canvas becoming unreadable. Sub-circuits are a way to build abstractions. One is a viewing convenience, the other is the thing computer architecture is made of.

Writing the v4 article series taught digital logic. Writing this comparison taught me that my tool tops out exactly where the interesting part of the subject begins.

2. No timing diagrams.

Logisim has a chronogram. Digital has measurement graphs. LogicCircuit has an oscilloscope. CircuitVerse has timing diagrams with configurable propagation delay. Falstad has a scope.

Boolflow shows you the current state of every wire, and nothing else. For combinational logic that is genuinely fine — the truth table generator covers it. For anything clocked, it is a real handicap. You cannot debug a shift register by staring at its present value. I wrote an entire article about metastability for a tool that cannot draw you a single waveform, which in retrospect is funny.

3. No test framework, no classroom layer.

Digital lets you write test cases and run them against a circuit. CircuitVerse has testbenches where an author declares input vectors and expected outputs, plus groups, assignments with deadlines, grading and grade export.

Boolflow has a Circuit Check — a linter that finds unconnected inputs and floating outputs — and that is the whole of its verification story. If you are a teacher with thirty students, CircuitVerse solves your actual problem and Boolflow does not solve any part of it.

4. No path to hardware.

Logisim Evolution has FPGA board integration. Digital goes further: JEDEC output for GAL16v8 and GAL22v10, ATF150x CPLD support up to 128 macro-cells, direct support for BASYS3 and TinyFPGA BX boards, and it will drive ghdl or Icarus Verilog to simulate its own generated HDL.

Boolflow emits Verilog and VHDL text and then wishes you luck. That is a real feature — it is not nothing to get synthesisable HDL out of a drawing — but "here is a file" and "here is your circuit running on a board" are different products.

5. Nobody has heard of it.

Logisim Evolution has 7,482 stars and a decade of course syllabuses pointing at it. Digital has 5,943. Boolflow has me. When a tool is used by thousands of students, the bugs that matter have been found. Mine have not.

Where Boolflow actually wins

Shorter list, and I checked each one against the other nine rather than assuming.

Zero friction, all the way down

Logisim and Digital need Java. LogicCircuit and Deeds need Windows. Logicly needs $59. simulator.io and CircuitVerse need an account before your work survives a browser refresh. DigiSim's free tier caps you at 16 components.

Boolflow: open the URL, place gates, save a JSON file. No install, no login, no tier, no component limit. Only Falstad matches that, and Falstad is an analog simulator you can coerce into doing logic.

That sounds like a small thing until you watch someone try to use a simulator during a forty-minute class on a locked-down school laptop.

C++ export

Nine other tools. Verilog appears in four of them, VHDL in three. C++ appears in none of them.

I added it almost as a curiosity — take the drawn circuit, emit a plain C++ function that computes the same outputs, with an optional test harness. It turns out to be the bridge that people who write software but not hardware actually want. You do not have to learn an HDL to check that the thing you drew does what you think it does; you compile it and call it.

I did not know this was unique until I went looking. It is now the feature I would lead with.

The theory sits next to the tool

This was the whole point of v4 and it holds up. Seventeen articles, each one ending in a link that drops you into the editor to build the thing you just read about.

Only two other tools in the table do this. Deeds does it well and is Windows-only 32-bit software from a university. DigiSim does it better than I do — 98 narrated lessons against my 17 articles — and puts most of them behind a subscription. CircuitVerse, the strongest browser tool by a distance, has documentation rather than a curriculum.

So the niche is real. It is just narrower than I thought and I am not alone in it.

Trilingual, including the interface

Boolflow's UI, its 17 articles and its per-element help all exist in English, Russian and German. Digital has seven interface languages but is desktop Java. DigiSim has seven languages and charges for most of the lessons. CircuitVerse is English-first. Logisim's teaching material is overwhelmingly English.

If you are learning digital logic in German or Russian and you want the theory and the tool in your own language, in a browser, for free, the list of options is short.

The Circuit Check

I could not find an equivalent in any of the other nine as a first-class feature: a button that scans the schematic and tells you which inputs are unconnected and which outputs go nowhere.

It is not clever. It is about eighty lines of code. It is also the single most common thing a beginner gets wrong, and every other tool makes them find it by wondering why nothing happens.

What this changed on my roadmap

I went in wanting to write a piece about how Boolflow compares. I came out with a re-ordered backlog, which is a better outcome.

Sub-circuits. Not "some day". Next. Everything else on this list is smaller than the gap between having them and not.
Waveforms. A timing panel for clocked circuits. The flip-flop and counter articles are currently writing cheques the editor cannot cash.
Test cases. Digital's model — declare inputs and expected outputs, run, see pass or fail — is the right one, and it is also the missing half of "exercises with checkable answers", which I promised in the v4 post.
Everything classroom-shaped: deliberately not. Accounts, groups, grading, dashboards. CircuitVerse has done this properly for years and I am not going to do it better as one person. If you need it, use CircuitVerse. I would rather be the tool a single person opens at 2am than a worse version of a platform that already exists.

So which one should you use?

Honestly:

Taking a university digital logic course? Logisim Evolution. It is what your assignments assume.
Teaching a class of thirty? CircuitVerse. Nothing else free gives you assignments and grading.
Pushing a design onto real hardware? Digital. JEDEC, CPLD and board support that nothing else free comes close to.
Trying to understand what current actually does? Falstad. Watch the dots move.
Want a paid, polished, teacher-first desktop app? Logicly.
Want narrated lessons across digital, analog and relay logic and don't mind paying? DigiSim.
Want to open a tab right now, place a gate within ten seconds, generate a truth table, and read the theory in the same site in English, Russian or German — with no install, no account and no limit? That one is Boolflow.

That last sentence is a narrow claim. It is also, after two weeks of checking, a true one.

Tell me what I got wrong

Genuinely — this is the part I want feedback on:

If you maintain or teach with one of these tools and I have misrepresented it, say so and I will correct the post. I tested each one myself but two weeks is two weeks.
If you use a simulator I did not cover, name it. I deliberately left out Multisim, Proteus, Tinkercad and Wokwi as different categories, but I may have missed something in-category.
Is my read on sub-circuits right? Is that the feature that would actually change whether you'd use Boolflow, or am I fixating on it because it is the most obvious hole?
And the C++ export: is that useful to you, or is it a solution I invented for a problem nobody has?

Boolflow is at boolflow.site, the articles are at boolflow.site/articles, and it is free with nothing to install.