JEPA can sound like a sudden new architecture: predict hidden pieces of the world in representation space, avoid pixel reconstruction, learn useful abstractions, then use those abstractions for planning. But the deeper idea is older and cleaner:

intelligence can be framed as settling into states that make the world internally consistent.

That is the energy-based thread. Hopfield networks gave it a physical metaphor. Boltzmann machines made it probabilistic and learnable. LeCun’s energy-based models generalized it into a modeling principle. JEPA is one modern answer to the question that fell out of that lineage: what should the model assign low energy to?

Hopfield: Memory as a Valley

Hopfield’s 1982 paper is usually introduced as associative memory. Store a set of patterns. Give the network a noisy or partial pattern. Let the recurrent dynamics run. If the stored pattern is strong enough and the starting point is close enough, the system settles into the nearest remembered pattern.

The important conceptual move is that recall is not a lookup table. It is motion downhill.

Each network state has an energy. Stable memories are low-energy basins. The update rule decreases energy until the system reaches an attractor. That gives you a physical picture of computation: a memory is not merely an addressable record; it is a basin in a landscape. Recognition is the act of falling into the right basin.

That picture matters because it joins three ideas that still show up in modern representation learning:

• Representation: a pattern is encoded as a state of many simple units.
• Inference: computation is the process of finding a compatible low-energy state.
• Robustness: damaged or partial input can still land in the same attractor.

Hopfield networks are limited, but the metaphor is durable. A model can know something by making the correct configuration easier to settle into than the incorrect ones.

Boltzmann: Search the Landscape, Learn the Landscape

The Boltzmann machine keeps the energy landscape but adds stochasticity. Instead of deterministically falling into the nearest basin, units update probabilistically, with low-energy states more likely than high-energy states. Temperature controls how much the system explores.

That one change makes the architecture feel less like a fixed memory and more like a generative model. The machine can sample states. It can represent uncertainty. Most importantly, it has a learning story: adjust weights so observed data configurations become lower energy than configurations the model dreams up on its own.

The core contrast is:

This is the first bridge toward the modern language. A good model is not merely a function that maps input to output. It is a system that scores configurations. Learning reshapes the score surface so correct configurations become cheap and incorrect ones become expensive.

Energy-Based Models: A General Scoring Rule

LeCun’s energy-based learning tutorial generalizes the pattern:

E(x, y)

The model assigns a scalar energy to a proposed pair. If x is an input and y is a candidate answer, the model should give low energy to compatible pairs and high energy to incompatible pairs. Prediction becomes optimization:

y* = argmin_y E(x, y)

That is a broad frame. Classifiers can be read this way. Structured prediction can be read this way. Planning can be read this way. The energy function is not required to be a normalized probability distribution. That matters because normalization is often the expensive or impossible part.

But energy models have a practical problem: if you tell the model only to make good answers low energy, it may make everything low energy. Useful learning needs a way to avoid collapse. Classical Boltzmann machines use negative samples. Contrastive methods compare positives and negatives. Other methods use architectural constraints, regularizers, variance terms, stop-gradients, masking, or target encoders.

This collapse problem is one of the quiet background reasons JEPA is interesting.

JEPA: Low Energy in Representation Space

JEPA moves the prediction target out of raw observation space.

Instead of asking a model to reconstruct every missing pixel or token, it asks the model to predict the representation of hidden or future content from the representation of visible context. In I-JEPA, a context block from an image predicts the embeddings of target blocks. In V-JEPA, video context predicts video features. The prediction is not “what exact pixels were missing?” but “what abstract state should be true there?”

That changes the energy question:

This is the old energy idea in a new location. The low-energy state is no longer a binary memory pattern or a sampled visible/hidden configuration. It is a compatible relationship between context representation, target representation, and sometimes an action or latent variable.

For world models, that is the attraction: the model does not have to generate the whole future frame. It needs to represent the aspects of the future that matter for understanding and control. The “energy” is the mismatch between predicted latent state and target latent state.

The Lineage

The through-line is not that Hopfield networks literally became JEPA. The architectures are different. The training machinery is different. The scale is different.

The through-line is the habit of thought:

1. Treat cognition as finding compatible configurations.
2. Give configurations a scalar score.
3. Make good configurations low energy.
4. Use dynamics, sampling, gradient descent, or a learned predictor to reach those low-energy states.
5. Move the space of optimization upward, from raw bits to useful representations.

Hopfield shows that memory can be a basin. Boltzmann machines show that probabilistic learning can reshape those basins. Energy-based learning abstracts the basin into a scoring function. JEPA asks the model to build basins in latent space, where the predictable structure of the world lives more cleanly than in pixels.

The promise of nono is simple: give an AI coding agent a real sandbox. Not a prompt-level warning. Not a policy reminder. A kernel-enforced boundary around what the process can read, write, delete, and contact.

That is exactly the kind of tool I want in the local-agent workflow from the Pi post. I am running agents on Lucy, my local AI cluster, through mosh, tmux, unprivileged user accounts, and local models. If those agents are going to edit code and run commands, they need boundaries that do not depend on the model being obedient.

But the path to a usable setup was not “install nono, run Pi, done.” It took a while to find a working combination of nono, Pi, Ollama, and an LLM that could do useful work without getting wedged.

The Goal

The goal was not theoretical sandbox purity. It was more practical:

1. run Pi inside a constrained environment,
2. let Pi use Ollama for a local model,
3. allow enough filesystem access for useful development,
4. prevent obvious damage or secret exposure,
5. keep the loop small enough that failures are understandable.

That last point matters. Sandboxing an agent is not useful if the agent becomes too constrained to act, too confused to use its tools, or too wrapped in indirection to debug.

The Iteration Tax

The first cost was permission tuning.

nono is a capability boundary. That is the point. But agent work is full of little side effects: reading project files, writing scratch files, running commands, following symlinks, touching caches, calling helper binaries, connecting to a local model server, and sometimes discovering that the next thing it needs is outside the allowlist.

That creates a tuning loop:

run agent
watch it fail
inspect what was denied
adjust permissions
run again

Some failures are good. They prove the sandbox is doing its job. Other failures are friction: the agent cannot reach the local service it needs, cannot write where the tool expects, or gets confused by an environment that is almost but not quite normal.

This is where nono gets real. The hard part is not believing in sandboxing. The hard part is finding the permission set that is narrow enough to matter and wide enough to work.

When Models Talk Instead of Act

The second cost was model behavior.

I repeatedly hit a local-model failure mode where the model would describe what it was going to do instead of actually doing it. It would outline a plan, explain the next command, or narrate the intended edit, but not drive the tool loop forward, even after repeated cajoling to just do it.

That is a different problem from sandboxing. nono can enforce filesystem and process boundaries, but it cannot make a weak model become an effective coding agent. If the model does not reliably convert intent into tool calls, the safest sandbox in the world just protects a process that is not doing much.

That distinction is important:

The debugging loop has to identify which layer is failing. Otherwise every problem looks like a nono problem.

The Wrapper That Did Not Work

Along the way, an AI suggested a clever-looking approach: use nono to run a Pi-aware Ollama command.

That sounded plausible. Put the model invocation itself inside the sandbox-aware command path. Make the pieces explicitly aware of each other. More integration should mean more control, right?

In practice, that seemed to cause problems. The extra wrapping made it harder to reason about who was responsible for what. Was nono constraining Pi? Was it constraining Ollama? Was Pi talking to the model server in the expected way? Was the model command itself now part of the agent’s tool surface?

The better shape was simpler:

nono runs Pi
Pi calls Ollama
Ollama serves the model

That preserves the boundary where I actually wanted it: around the agent process and its filesystem behavior. Ollama remains the model service. Pi remains the agent loop. nono remains the sandbox.

The Usable Shape

The most usable setup so far is:

• run Pi under nono,
• let Pi call Ollama normally,
• use gemma4,
• keep the permissions narrow but not theatrical,
• iterate on the deny/fail cases until the agent can actually work.

gemma4 worked better for me than the Qwen and Mistral models I tried in this workflow. That is not a universal benchmark result. It is a practical observation from this setup: nono plus Pi plus Ollama needs a model that can keep the tool loop moving.

This also changes what “model evaluation” means. I do not only care whether a model can answer coding questions. I care whether it can participate in a constrained edit/run/debug loop:

• does it use tools instead of only describing tools?
• does it recover from denied access?
• does it ask for narrower permission changes or thrash?
• does it keep edits small enough to inspect?
• does it learn from command output within the session?

Those are agent-behavior questions, not just language-model questions.

The Model Search Is Part of the Work

I probably need to try many models before finding the right local-agent set.

There are two different targets:

1. models that perform useful tasks out of the box,
2. models that are small enough, regular enough, and steerable enough to fine-tune.

The first target is about immediate productivity. The second is about Lucy’s longer-term role: local models that get better at my repos, my tools, and my recurring failure modes over time.

That may point toward smaller models, not because smaller is automatically better, but because smaller models are more practical to iterate on locally. A model that is slightly weaker out of the box but easier to fine-tune may be more valuable than a stronger local model that is too expensive to adapt.

Small Models, More Attempts

There is also an inference-time angle.

Some problems do not require one perfect answer from one large model. They can be attacked by repeated attempts from a smaller model, especially when there is a verifier: tests, type checks, linters, golden outputs, or a human reviewing a small diff.

That is the same broad lesson as the repeated-sampling work I wrote about in Large-Language-Monkeys: a smaller model plus multiple attempts plus a verifier can sometimes match or beat a larger one-shot model.

For local agents, the tradeoff becomes concrete:

The energy question is not automatic. A small model looping badly can waste time and power. But a small model that makes cheap attempts against a good verifier may be the better local computation shape.

That is why nono matters here. If I am going to let smaller local models iterate, fail, and try again, I want the iteration loop to happen inside a boundary.

What nono Is Really Buying

nono is not making the model smarter. It is making the experiment safer.

That safety changes what I am willing to try. I can give an agent a real shell and a real project while still narrowing the blast radius. I can test local models that may be clumsy. I can preserve transcripts and failures for later training. I can let the loop run longer without treating every mistake as a potential catastrophe.

That is the practical value: sandboxing turns local-agent experimentation from reckless into routine.

Key Takeaways

1. Sandboxing is an integration problem, not just a security checkbox. The permissions have to match the agent’s real workflow.

2. The cleanest setup was layered, not clever. nono runs Pi; Pi calls Ollama; Ollama serves the model.

3. Model behavior dominates quickly. Some models plan instead of act, and sandboxing cannot fix that.

4. The account boundary matters too. I am combining unprivileged Linux accounts, one agent per repo, with nono so the system prevents actual errors my LLMs repeatedly make: no more erasing files without recourse, no more multiple agents modifying the same repo without coordination, and push access only from a coordinator-agent account.

5. Gemma4 was the most usable of the models I tried in this loop. Qwen and Mistral were less effective in this particular setup.

6. The long game is local learning. Sandboxed, observable agent runs can become the raw material for fine-tuning models that learn from repeated mistakes.

Resources

• nono Website
• nono GitHub Repository
• nono Documentation
• Pi Mono Repository

Four tools. Read, Write, Edit, Bash.

That is the part of Pi that looks like a slogan, but after using it the point feels less like minimalism for its own sake and more like friction control. Pi is not trying to become the center of the development environment. It is a small agent loop that can read files, change files, run commands, and leave the rest of the system alone.

My setup makes that especially visible. I use mosh from my MacBook to connect to an Arch Linux server, because it survives network hiccups better than plain ssh. On that server I log into an unprivileged user account and run tmux, which gives me multiple persistent PTYs. One tmux window runs Pi with gemma4 on an RTX 3090 with 24 GB of VRAM. Another tmux window is just a shell prompt, or sometimes an Emacs shell.

I use the same general pattern for other coding agents: Claude Code, Codex, Gemini, and opencode using the Z.ai dev plan with GLM-5. That makes Pi’s shape easier to compare. The machine, project, shell, and tmux workflow stay mostly constant. What changes is how much agent framework shows up before the model starts doing useful work.

That makes Pi a useful counterweight to the current agent-tooling habit of turning every workflow into a platform.

The Working Shape

My current Pi setup is not a cloud-agent command center. It is a local model, a default thinking level, and one package:

{
  "defaultModel": "gemma4",
  "defaultProvider": "ollama",
  "lastChangelogVersion": "0.74.0",
  "packages": [
    "npm:@ollama/pi-web-search"
  ],
  "defaultThinkingLevel": "medium"
}

That lives at:

~/.pi/agent/settings.json

This is the interesting version of Pi to me: not “look how many integrations this has,” but “look how little standing machinery needs to be loaded before the model can start doing useful work.” A local Ollama model is enough to keep the loop close. One web-search package is enough to give it a narrow escape hatch when local context is not enough. The rest is just the agent doing agent things against the current working directory.

Pi matters in that context because its loop is small enough to observe. If I want to turn agent experience into future training data, I need transcripts and actions that are easy to understand. A minimal agent loop is not just easier for me to debug today; it is cleaner raw material for tomorrow’s local learning pipeline.

Minimal Does Not Mean Weak

The core tool set is boring:

Those four operations cover a surprising amount of software work because most coding-agent work eventually becomes:

1. inspect the repo,
2. make a small change,
3. run the command that proves or falsifies it,
4. repeat.

That is not everything an agent might do. It is, however, the irreducible loop under a lot of the tooling we dress up with dashboards, plugin catalogs, project memories, task graphs, and elaborate orchestration.

The point is not that Pi uses a smaller context window. Pi can use whatever context window the selected model supports. The optimization is that Pi spends less of that window on the agent framework itself. More of the model’s available attention can go to the repo, the task, the transcript, and the command output that actually matter.

What Pi Gets Right

Pi’s strength is that it does not make the agent feel more magical than it is. The model can read, edit, and run commands. If the result is wrong, the failure is usually visible in the transcript or the filesystem.

That matters. Agent systems become hard to debug when too much behavior is hidden behind framework policy: tool routers, memory layers, implicit plans, autonomous retries, invisible summarizers. Those pieces can be useful, but they also make the system harder to reason about.

Pi’s small surface area gives it three practical advantages:

• Low ceremony: starting a session does not feel like launching infrastructure.
• Good failure shape: when it gets confused, the mistake is usually local.
• Efficient context use: the initial context is not crowded by unused capabilities.
• Easy composition: additional behavior can live outside the core loop.

That last point is the important one. Minimal systems survive contact with real work when they have an extension path. Pi’s philosophy is not “never add capabilities.” It is “do not pre-spend context on every capability someone might want someday.”

Local Models Change the Feel

Using Pi with Ollama changes the social contract of the tool. A local model is not always the smartest model in the room, but it is cheap to call, private by default, and always available when the machine is available.

That makes Pi useful for narrower work than I would hand to a frontier coding agent:

• asking it to inspect a small code path,
• generating a first-pass script,
• trying a quick refactor in a disposable branch,
• keeping a local search/edit/run loop warm while I think.

The settings file captures that stance. gemma4 via ollama, medium thinking, one web-search package. Enough help to be useful. Not enough machinery to become a second project.

OpenClaw Is Context, Not the Headline

Pi is also part of a broader ecosystem. OpenClaw and related experiments build larger agent experiences on top of Pi-style pieces. That is worth mentioning because it proves the core can be embedded.

But for this post, OpenClaw is not the main point. The main point is that Pi itself is a clean reference design for a coding agent:

model + prompt + four tools + transcript + working directory

Everything else should have to justify itself.

The Slant After Using It

Before using Pi, the obvious story is “minimal agent has only four tools.” After using it, the better story is “minimal agents preserve mechanical sympathy by treating context as a working budget.”

You know what the agent can touch. You know what it can run. You know where configuration lives. You can look at the settings file and understand the operating posture in ten seconds:

• local model,
• local provider,
• medium reasoning effort,
• one explicit package.

That is a better baseline than most agent frameworks provide. A big model context window is still valuable. Pi’s advantage is that it does not fill that window with framework overhead before the problem has earned it.

Key Takeaways

1. The useful unit is the loop. Read, edit, run, observe is the center of coding-agent work.

2. Minimal cores age well. The less policy hidden in the core, the easier the system is to debug and extend.

3. Local models are a different workflow, not just a cheaper backend. Pi plus Ollama makes small, frequent agent use feel natural.

4. Context efficiency is an optimization, not a constraint. Pi can use the model’s full context when the task calls for it; it simply starts by spending fewer tokens on itself.

5. Extensions should orbit the core. Packages and integrations are useful, but they should not make the agent’s basic behavior mysterious.

Resources

• Pi Mono Repository
• Armin’s Extensions
• Pi: The Minimal Agent

Espanso: Shared Glyph Input for Collaborating on a New Language

Espanso is a cross-platform text expander written in Rust. Type a short trigger, get a replacement string anywhere your OS accepts text input—editor, terminal, browser address bar, chat window, IDE. It runs as a background service, the configuration is plain YAML in a known directory, and packages can be shared the same way other tooling shares plugins.

The reason Espanso earned a Sharpen the Saw slot of its own (it was already mentioned in Part 8 as the Tuplet glyph-entry layer) is the collaboration angle: a glyph language is unusable if your collaborator can’t type the glyphs. Sharing a checked-in YAML file means both sides of the design conversation type the same triggers and produce the same source. There is no “it works on my keyboard layout” problem when the layout is a YAML file in the repo.

The use cases keep stacking up beyond glyphs:

• APL, Tuplet, and PAL glyphs — the original reason. Three Espanso config files now ship alongside the language repos: one for APL glyphs (⍳⍴⍵⌽…), one for Tuplet (▪→←ℤ⎧⎨⎩…), and one for PAL, a colleague’s in-development language with its own non-ASCII surface syntax. Same trigger discipline across all three; the same muscle memory works in any editor or terminal that accepts text—and the colleague designing PAL gets a working glyph-entry layer by cloning a config, not by hand-rolling AltGr maps.
• Date and timestamp snippets — ISO dates, blog post front-matter date strings (2026-05-03 00:15:00 -0800), git commit subject prefixes. Anything I type more than three times a week is a candidate.
• Boilerplate scaffolds — front matter blocks for new posts, the standard Sharpen the Saw resource box, the standard “Why Sharpen the Saw?” aside. Every one of those used to be a copy-paste from the previous post; now they expand from a trigger.
• Shell one-liners — the long-but-forgettable invocations: git log --oneline --decorate --graph --all -n 30, the ffmpeg call I always forget the flag order for, the find . -name '*.md' -exec grep -l ... pattern.

The leverage is in the aggregation: each individual snippet saves a few seconds, but the union covers a non-trivial fraction of daily typing, and the muscle memory is the same trigger set everywhere.

The cost to add a new snippet is small enough (one YAML entry, no restart) that the friction curve flips: instead of “is it worth automating?”, the question becomes “is there any reason not to?”. The fact that adding PAL took roughly an afternoon—read the language’s glyph list, write the YAML, install on each machine—is the demonstration: the third language is dramatically cheaper than the first.

Kate: An Editor Where a New Language Is a Config File, Not a Plugin

Kate is the KDE project’s text editor—a serious general-purpose editor that runs on Linux, macOS, and Windows. It is not a replacement for Emacs (where the language and config story is years deep) or for the IDE-of-the-week, but it earns its slot here for one specific reason: giving a collaborator’s in-development language editor support is a single XML file, not a plugin or an LSP project. That cost ratio matters a lot when the language changes weekly.

Beyond that, the usual fast-editor virtues:

• Instant startup, even on a cold launch. Useful for quick edits where a full IDE is overkill.
• Real syntax highlighting and code folding for hundreds of languages out of the box, including the obscure ones (Forth, BASIC, Smalltalk, APL) that most “lightweight” editors treat as plain text.
• Built-in terminal pane and a tabbed multi-document view, so it scales up from “open one file” to “open a whole directory tree” without ceremony.
• Same UX on all three OSes — when I am bouncing between a Linux GPU box, a Mac laptop, and a Windows machine for screen-recording, having one editor with the same keybindings everywhere reduces context-switch tax.

Kate’s role in the toolbox is the editor-equivalent of cat or less: not the place where the heavy work happens, but the place I open first when I just need to look at a file or a directory and see it formatted correctly. It has gradually displaced “open this in TextEdit / Notepad / Gedit and squint” for everything except where Emacs already wins.

The Sharpen the Saw value is portability: the cost of adding a new platform to the workflow drops if the editor moves with you.

Custom syntax highlighting for PAL

Kate’s syntax highlighting is driven by KSyntaxHighlighting XML files—one file per language, declarative keyword lists, region rules, and reference styles. There’s no compiled extension, no language-server dance, no marketplace round-trip. For a language whose grammar is changing week-over-week between two collaborators, that round-trip cost is what would otherwise kill editor support entirely.

For PAL—a colleague’s in-development language with its own keyword set and surface syntax—the recipe is:

1. Drop a pal.xml (KSyntaxHighlighting format) into Kate’s user syntax directory.
2. Bind the .pal extension and any associated glob patterns to the new highlighter.
3. Reload (or restart Kate) and verify on a representative source file.
4. Iterate: keyword list, comment delimiters, string and number rules, any glyph-specific tokens that overlap with the Espanso input layer.

That gives PAL a real editing experience on every machine that has Kate installed—no fork, no plugin maintenance, just a single XML file to ship alongside the language. Both collaborators get the same highlighter from the same checked-in file; a grammar change is one PR away from showing up in everyone’s editor. Same pattern would work for Tuplet and for the COR24 Forth/BASIC/OCaml dialects where Kate’s stock highlighters need a few project-specific tweaks.

The point is the same one that drives the Espanso config story: when two people are designing a language together, editor support and input methods are part of the language—not a downstream nice-to-have that ships after v1.0. Cheap, version-controlled, single-file editor support changes the cadence of language design itself.

ShareX: Screenshot, Annotate, Share

ShareX is a Windows screenshot-and-screen-capture tool with the entire post-capture pipeline built in: region select, scrolling capture, annotation, color picker, OCR, GIF/video record, and a configurable upload step (S3, imgur, custom HTTP, save-to-disk-with-filename-template). Open source, no account required, and the configuration is local.

Why it matters for a blog/video workflow:

• Region capture with annotation in one keystroke — highlight, arrow, blur (for sensitive screen content), text overlay. The result is ready to paste into a post or video frame without bouncing through a separate image editor.
• Filename templates — captures land as 2026-05-03_kate-syntax-highlighting_01.png automatically, in the right directory, ready to be moved into sw-lab/assets/images/posts/ with no rename step.
• GIF and short MP4 capture — for the cases where a screenshot can’t show the interaction (dropdowns, hover states, animations). The same hotkey, the same output directory, the same naming convention.
• OCR built in — when a screenshot of code or a terminal needs to become text for inclusion in a post, no need to retype.

ShareX’s value is the same as Espanso’s, in a different domain: it collapses what used to be a five-tool pipeline (capture → crop → annotate → rename → upload) into a single hotkey with sensible defaults. The blog post images for the COR24 demos and the Sharpen the Saw series go through this pipeline.

On Mac: gh gist create for sharing language snippets

ShareX itself is Windows-only. The Mac-side search for an equivalent went through the usual suspects (Shottr, CleanShot, Skitch, the built-in Cmd-Shift-5) and ended somewhere unexpected: gh gist create, the GitHub CLI’s gist subcommand, doing the share half of the workflow even though it has nothing to do with screenshots.

The realization was that for language-design collaboration—which is what most of the day’s “I want to share this with my collaborator” moments actually are—the artifact is almost always text: a PAL snippet that exposes a parser ambiguity, a Tuplet expression that doesn’t lower the way I expected, a YAML excerpt from one of the Espanso configs, an error message I want a second opinion on. None of those need a screenshot. They need a URL my collaborator can open, comment on, and clone.

gh gist create is exactly that:

gh gist create --public --desc "PAL syntax sketch" pal-snippet.txt
gh gist create --secret config.yml          # private gist
echo "$(pbpaste)" | gh gist create --filename note.md -

The result is a gist URL on stdout, ready to paste into a chat or an email. The collaborator opens it, comments inline, or forks it with their own version of the snippet—which is a much higher-bandwidth conversation than a screenshot would be, because the text is editable on the other side.

ShareX’s “take a screenshot, get back a URL” muscle memory turned out to be the wrong shape for this use case. What I actually wanted was “take this code-shaped thing, get back a URL”, and gh gist create does that natively without going through an image at all. For the rare times an actual screenshot is needed (UI bug, terminal output that won’t paste cleanly), Cmd-Shift-4 plus dropping the image into the relevant blog or language repo and letting git push carry it covers it.

The takeaway: when “share with my collaborator” is the actual goal, the right tool depends on the artifact’s shape. For images, ShareX’s pattern is correct. For language design, the artifact is text, and the screenshot detour is friction the gist tool removes.

Pluggable I2C Devices on the COR24 Emulator

Part 8 introduced I2C support on the COR24 emulator. This week’s work is the design that lets it scale: a three-layer architecture where the bus is emulated once at the MMIO level, and devices plug in via a trait so adding a new chip is one file plus one registry line. SPI is sketched in parallel as phase 2.

The motivation is the goal that justifies the bus work in the first place: adding I/O examples to the COR24 languages. BASIC, Forth, OCaml, Tuplet, and Smalltalk all benefit from the same demo library—read a temperature sensor, persist a value to an EEPROM, read the wall clock, drive a display. If the emulator hard-codes its device list, every new demo means an emulator change. If the device list is pluggable, adding a new simulated peripheral is a separate, scoped piece of work that the language demos consume as data.

Three layers

Layer 1: Guest applications
  C programs + libi2c / libspi running on the COR24
  (i2cspi/tmp101 and i2cspi/tmp125 already exist)
        │  MMIO writes/reads to GPIO-style addresses
        ▼
Layer 2: Bus MMIO emulation (in CPU emulator core)
  Models the FPGA's I2C/SPI line registers exactly. Reconstructs
  logical bus events from line transitions. Routes events to
  whatever device(s) are currently attached.
        │  Bus event API: on_start / on_write_byte / on_read_byte / on_stop
        ▼
Layer 3: Pluggable virtual devices
  Implementations of an I2cSlave / SpiSlave trait for each chip
  to be modeled. New devices = new files.

Layers 1 and 3 grow independently—more demos, more chip models. Layer 2 is small, central, and ideally written once.

Why this is harder than UART

Both I2C and SPI on the COR24-TB FPGA are bit-banged GPIO, not register-driven peripherals. The CPU pokes individual line states (SCL=0, SDA=1, …) and clocks the bus itself. This is materially different from the existing UART, where the CPU writes one byte to IO_UARTDATA and the emulator reacts to that byte.

The emulator can’t just “respond when the CPU writes a byte.” It sees individual line transitions and has to reconstruct logical bus events (START, address+RW, byte-in, byte-out, ACK, STOP for I2C; bit-shift on SCLK edge for SPI) from the physical transitions, then route those events to a virtual device. Open-drain wired-AND for I2C means tracking master and slave drivers separately:

scl_line = master_scl  & !slave_scl_pull
sda_line = master_sda  & !slave_sda_pull

The bus state machine—Idle → Started → RxByte → AckMasterToSlave → TxByte → AckSlaveToMaster → Stopped—is driven by (scl_line, sda_line) transitions, not by writes. This is the price of MMIO-accurate emulation, but the payoff is that the same C source (libi2c.c, the bit-bang loop) runs unmodified on the FPGA and the emulator. If a demo ever needs different code on emulator vs. FPGA, the abstraction has leaked and the emulator should be fixed.

The device trait

The pluggable extension surface is a small Rust trait:

pub trait I2cDevice: Send {
    fn address(&self) -> u8;
    fn name(&self) -> &str { "i2c-device" }

    fn on_start(&mut self) {}
    fn on_write_byte(&mut self, byte: u8) -> Ack { Ack::Nak }
    fn on_read_byte(&mut self) -> u8 { 0xFF }
    fn on_master_ack(&mut self) {}
    fn on_master_nak(&mut self) {}
    fn on_stop(&mut self) {}

    fn on_tick(&mut self) {}                    // for time-based behaviour
    fn stretching_scl(&self) -> bool { false }  // optional clock stretching
}

Adding a new chip is three things: a file at src/peripherals/i2c/devices/<chip>.rs implementing the trait, one line in src/peripherals/i2c/registry.rs mapping a string key to a constructor, and unit tests. No edits to the bus core, no edits to the CPU, no fork.

Construction is string-keyed so the CLI and config files share one parser:

--i2c-device tmp101@0x4A
--i2c-device 'tmp101@0x4A?temp=23.5'
--i2c-device 'ds3231@0x68?epoch=2026-05-03T12:00:00Z'
--i2c-device logger@*          # passive logger on every address
--dump-i2c                     # transaction log on exit

First device set

The TMP101 is the integration anchor: load the existing tmp101.lgo binary (already built by the FPGA-side toolchain), attach a Tmp101 device at 0x4A, run for N instructions, and assert the UART output matches the "%.2f\n" line for the configured temperature. If that single test passes, the whole stack works—libi2c bit-banging, bus state machine, device model, UART output, printf formatter.

The EEPROM and DS3231 are the gate before the trait is declared “public”: two devices with the same shape proves nothing; four devices with three different shapes (sensor / storage / clock / passive logger) proves the trait is general.

SPI as phase 2

The SPI design is the same shape, simpler. No addressing, no START/STOP, no open-drain—just a shift register clocked by SCLK while SELN is low:

pub trait SpiDevice: Send {
    fn name(&self) -> &str { "spi-device" }
    fn on_select(&mut self) {}
    fn on_byte(&mut self, mosi: u8) -> u8;  // simultaneous shift
    fn on_deselect(&mut self) {}
    fn on_tick(&mut self) {}
}

Mode 0 only (CPOL=0, CPHA=0)—which is what spixchg.s already implements. Once the I2C plumbing is in place, the SPI side is mostly mechanical: replace the bus state machine with the simpler shift register, re-use the device-attachment plumbing nearly verbatim.

Why this is Sharpen the Saw

Doing the bus work once at Layer 2 means every COR24 language gets the same I/O library out of it. The BASIC tutorial, the Forth tutorial, the OCaml tutorial, and the Tuplet tutorial all share an example set instead of each one inventing its own. The pluggable device trait means the demo library can grow without the emulator growing—same compartmentalization pattern that drove the sw-MLPL split, applied to peripherals.

Possible Next Steps

Not commitments—just directions any of these threads could grow if the slot opens up:

Espanso — Bundle the per-language glyph configs (APL, Tuplet, PAL) into something installable in one step on a fresh machine, instead of three separate cps. Possibly a shared dotfiles repo, possibly a per-language file that ships with each language’s repo.

Kate — Get the PAL syntax highlighter past the “renders something” stage and confirm it survives a Kate update. A Tuplet highlighter is the obvious second one if the PAL one shakes out cleanly.

ShareX / gh-gist — Possibly revisit a Mac-native ShareX equivalent (CleanShot X, Shottr) if the gist-as-share workflow runs out of road. For now it’s good enough that there’s no urgency.

COR24 I2C Pluggable Devices — The plan walks an order: stub MMIO at 0xFF0020/0xFF0021, master-line state, bus state machine, device trait, the tmp101.lgo end-to-end test as the gate, then --i2c-device CLI, a registry, a second device shape (EEPROM or DS3231) to prove the trait is general, and docs/extending-i2c.md before declaring the API public. SPI follows in the same shape with a simpler bus. How much of that lands and in what order is a function of how much time the I2C work earns relative to everything else competing for it.

Glyph input, syntax highlighting, snippet sharing—three tools and one job: making a new language cheap to collaborate on. Plus a peripheral bus that does the same favor for the COR24 language stack. Follow for more Sharpen the Saw updates.

The AQ Setting

AQ ran on MVS/ESA. From the user’s seat, every interaction was a 3270 block-mode terminal: you didn’t type interactively the way you do at a modern shell — you filled in fields on a screen, pressed Enter (or a PF key), the entire screen went to the host, the host processed it, and a new entire screen came back. Round-trip latency was small only by the standards of the day. The medium shaped the workflow.

Hundreds of developers shared this system. They edited PL/X (IBM’s internal PL/I dialect, used for systems work and OS components) and System/370 assembler. They submitted batch compile jobs to JES2. They scheduled printouts (yes, printouts — a real cabinet of green-bar paper down the hall) or browsed compile output online. The two universal pain points of every developer’s day were:

• Authoring is slow because most of what a working programmer types every day is repetitive boilerplate — IF/ELSE framing, DO/END loops, DCL declarations, PROC headers, MACRODEF blocks — and the editor gives you no help avoiding it.
• Turnaround is slow because submitting a compile job means joining a queue, and on a busy day that queue could be an hour long. By the time results came back, you had context-switched to a different program four times.

Two colleagues built tools to push back on each of those. They were exactly the kind of internal productivity tooling that did not exist as products on the open market in 1985 — IDEs were a Macintosh / Smalltalk lab curiosity, Emacs existed but was a Unix-room thing not a mainframe thing, and the average corporate mainframe shop ran whatever editor IBM happened to ship. Internal tools filled the gap, and the good ones spread by reputation.

PL/EDIT — Templates Before They Were a Word

A colleague (whose name I am withholding here, since I have not asked their consent to publish it forty years on) wrote PL/EDIT. The premise was simple: most of what a PL/X programmer typed was boilerplate. The first three lines of every IF block. The DO/END framing of every loop. The DCL statements at the top of every record declaration. The PROC header with its parameter list and RETURNS clause. The MACRODEF blocks. None of it was creative work. All of it was syntax.

PL/EDIT replaced character-by-character authoring with trigger-driven template expansion. You typed a short trigger like IF and pressed F4, and the editor expanded the trigger into a full IF/ELSE block with named fill fields. You pressed Tab to advance through the fields, Shift-Tab to go back. F4 cost one extra round trip to fetch the expanded screen, and the trade was easy: a few characters of trigger plus one round trip, in exchange for not typing the dozen-plus characters of boilerplate by hand.

The triggers covered every form a working programmer touched dozens of times a day — IF/ELSE blocks, DO WHILE and counted DO loops, SELECT/WHEN dispatch, scalar and record declarations, PROC headers with parameter lists and return types, CALL and RETURN, inline-assembler blocks, the macro-definition forms used for code generation. A help button opened the active trigger list; a Format button re-indented block structure that had gotten ragged.

This is exactly the model that snippets, IDE templates, and YAS-snippet would later mainstream in the 1990s and 2000s. PL/EDIT did it in the mid-1980s. It was not the first template editor anywhere — TECO and Emacs had abbrev-mode, and similar systems had snippets — but it was the only one that hundreds of us had access to, and the productivity difference between using it and not was night and day.

PL/EDIT on COR24 PL/SW

Mass Compile — Submitting Jobs for Programs You Had Not Written Yet

A different colleague tackled the turnaround problem with Mass Compile.

The naive workflow on AQ went: edit a program, save it, submit a compile job, wait. The wait could be five minutes; it could be an hour. Whatever the wait was, you context-switched, and when results came back you context-switched back. If you had a stack of related changes across several programs, you submitted them serially — finish program A, submit, wait, switch to program B, edit, save, submit, wait. The queue and the editor were unsynchronized: time you spent editing was time the compile queue was not running on your behalf.

Mass Compile was a screen — a single 3270 panel — where you could schedule a batch of compile jobs in advance. The trick the screen made possible was the one I still find astonishing: you could submit compile jobs for programs you had not written yet. The compiler did not know that. The compiler did know that when its turn arrived in the queue, it would go look up the named source member in the editor’s working storage and compile whatever was there at that moment. So:

1. You scheduled jobs for programs A, B, C, D — four compiles, queued in order.
2. While the queue waited for A’s slot to open, you finished editing A.
3. While A was compiling, you finished editing B.
4. While B was compiling, you finished editing C.
5. While C was compiling, you finished editing D.

The queue and the editor were now synchronized: every minute the queue spent moving forward was a minute the editor spent moving forward. The total wall-clock time to compile four related changes dropped from “four queue-waits in series” to “one queue-wait plus four edits in parallel with three compiles.”

The catch was the file lock. The editor held an OS-level file lock on each source member while you were editing it; JES2 needed the same lock to read that source when the compile job reached the head of the queue. If your job got there before you finished editing, JES2 waited on you. Messages would scroll into the bottom of your screen telling you, then telling you more emphatically, that a compile job was blocked waiting for your editor to release the lock. Senior engineers learned the social cost of holding the queue on a busy day; you did not want operations or your manager to start wondering why nobody else’s compiles were moving.

This was, in its own way, the first JIT-style “compile under pressure” workflow I ever saw. The compile job did not block on the source being final at submit time. The source was final as of the moment JES2 acquired the file lock, not as of submission. Speculative scheduling, OS-level file-lock arbitration, and a small dose of social pressure to keep you honest. The trick has not really gone away — modern build systems (Bazel, Buck, Cargo) all have variations on “kick off compute against the inputs as soon as they stabilize,” and CI systems do something analogous with branch-based job queues. But none of them show you the queue moving the way the AQ Mass Compile screen did.

Mass Compile on COR24 PL/SW

Why These Two Keep Coming Back

PL/EDIT and Mass Compile are about making each interaction with a slow system carry more weight. PL/EDIT trades a single F4 round trip for a dozen-plus characters of typing you would otherwise do by hand; Mass Compile lets the queue move while you keep editing. Both are productivity multipliers in environments where the dominant cost is wait time.

I keep finding the same shapes today, in different surfaces:

• Snippets and LSP scaffolds in modern editors are PL/EDIT’s children: type a trigger, get a templated form with fill fields. Same idea: stop typing the boilerplate, fill in only the parts that change.
• CI parallelism, build queues, and content-addressed caches are Mass Compile’s children: do not block on the source being final at submit time; do the expensive thing as late as possible against whatever inputs are stable; let the queue move forward in parallel with editing. sw-launcher’s cache-key formula is a content-addressed version of the same idea — the work runs against the inputs that exist when it runs, not when it was scheduled.
• AI agents working from a queue of tasks are Mass Compile’s grandchildren: submit a sequence of work items; let the agent process them while you keep going; surface warnings when an item is blocked on input you have not provided yet.

The 1980s mainframe shop was not primitive. It was constrained — a different set of constraints than today’s, but the people working in it solved their constraints with surprising elegance, and the productivity tooling that survived from that era keeps re-emerging in modern surfaces because the underlying problems — slow authoring, slow turnaround, queue contention — have only changed in detail. The medium changes; the moves stay.

If you have a few minutes, the live demo is worth poking at. Type IF and press F4. Open Mass Compile, add a few rows, edit one of them while the queue runs ahead. The 3270 is gone; the workflow is intact.

Login AUTHORIZED USERS ONLY. ONLINE 24,1.

Source Code’s Third Dimension

Programmers get attached to the medium they happened to learn on. People who started on punch cards remember source as a one-dimensional thing: a stack of cards, fed sequentially, each card eighty columns of fixed-width sequencing, each program a literal physical pile. People who started on glass terminals (which is most of us) think of source as two-dimensional: a window of lines and columns, scrollable in two axes, with the assumption that the meaningful structure lives inside that rectangle.

Every editor we use today is still a 2D-rectangle authoring surface. We have learned to interleave many concerns inside that rectangle — the algorithm, the types of inputs and outputs, the preconditions and postconditions the algorithm assumes, the generated form the compiler ends up emitting, the implementation layers (logging, error handling, instrumentation) that production code accumulates. Modern languages provide affordances for hiding most of this — type signatures collapse, comments fold, error handling moves to attributes or decorators — but it all still lives in the same rectangle, fighting for the same screen real estate, and the front-of-the-eye reading order is whatever the editor’s vertical scrollbar decides.

Punch cards are 1D. Screens are 2D. What if source were 3D?

DiscoveryOne is the project I am sketching to make that question concrete. Every glyph in a DiscoveryOne program has an (x, y, z) coordinate and an aspect label drawn from a fixed set: @front, @left, @right, @top, @bottom, @rear, @internal. A definition is not a block of text; it is a small cube of meaning, and the user views one facet at a time:

The Yew/WASM web app loads the file, projects it onto the requested facet, and runs the WASM module in-page when you click Run. A *Power definition reading n e -> p; p <- 1; loop e times: p <- p * n lives on @front; n : Int, e : Int lives on @left; the output type p : Int lives on @right; e >= 0 lives on @top; p == n^e lives on @bottom. Aspects (preconditions, postconditions, tracing, profiling, error recovery) live on spatially separate @internal layers so the front facet stays uncluttered for reading.

DiscoveryOne is the successor to Tuplet, my current 2D-layout-sensitive language with first-class named tuples and user-mintable verbs (the * operator literally mints new syntax). Tuplet keeps source 2D but layout-sensitive — where a glyph sits on a 2D grid changes its meaning. DiscoveryOne is the next jump: from “layout matters” to “facet matters.” The same glyph in two different @-aspects participates in two different parts of the program’s meaning.

Whether 3D source is useful is a real question. It might turn out that the seven facets are too many, or that the projection UI is too clumsy, or that humans really do read code best as a flat top-to-bottom story. I don’t know. The way to find out is to build it, drive a non-trivial program through it, and see whether reading the front facet of an unfamiliar definition is faster than reading the equivalent flat code with all its types and contracts and tracing inline.

DiscoveryOne is currently pre-M0 — the specification is committed; no code yet. The single demoable target (M7 in the saga plan) is one vertical slice: the user authors a *Power definition and a *syntax do _ while _ end expand syntax declaration, and runs both inside the web app. If that slice feels right, the rest follows.

Five Languages of My Own, in Flight

The other thing on the list right now is making programming languages, plural. Five of mine are currently between “design committed” and “live demo,” each picking a different point on the build/run space. Listed in roughly the order I started them:

PL/SW — PL/I-Inspired Systems Language

sw-cor24-plsw is a small systems-programming language inspired by PL/I (and a little IBM HLASM). It is the language I use to write higher-level COR24 programs — the SNOBOL4 interpreter, parts of the toolchain, the Fortran compiler in flight. It compiles natively to COR24 assembly and has its own vibe-maintenance heatmap of issues closed in the past few weeks (forty-plus, including the inevitable parade of “AST pool too small,” “MAX_PROCS too small,” “emit buffer too small” capacity bumps).

PL/SW’s interesting bet is macros: PL/I-style %DEFINE and MACRODEF GEN blocks that emit assembly. That makes the language usable as a meta-assembler — a higher-level surface that still gives you bit-level control over the COR24 instruction stream. It is the language I would have wanted in 1985 if I had had any say in the matter.

SWS — Tcl-Like Resident Shell

sw-cor24-script is a tiny Tcl-style scripting language that runs inside the resident monitor on COR24, sharing the program registry. The shell is a single binary that loads at 0x020000 (above the monitor at zero), and its commands operate on whatever programs the monitor has loaded into the slot table. It is the missing surface for a “1980s style” embedded workflow — the user types run hello at a prompt, the monitor’s service vector dispatches into the program at that slot, and control flow returns through a longjmp-style trampoline.

SWS exists because every other language in the lab is non-resident — a load happens, a program runs, the run ends, the host runs the next thing. SWS is the language designed for the case where the user is part of the loop: type, run, observe, type again. The repl on a 1 MiB COR24, with a 3 KiB EBR stack, in the year 2026.

sw-MLPL — A Rust-First Array Language

sw-mlpl is the array-and-tensor programming language I am building for the ML side of the bucket list. The lineage is APL → APL2 → J → BQN, but the implementation is Rust-first: a REPL in the terminal and the browser, a mlpl! proc macro that lets MLPL expressions live inside Rust source, an mlpl build path that compiles MLPL programs to native binaries, and a roadmap of backends (Apple MLX for Apple Silicon, CUDA for distributed training, Ollama / llama.cpp / OpenAI-compatible servers for LLM glue).

MLPL is the only one of the five that is mostly built — the live REPL works in the browser today, the language reference is written, the compiler implementation has a tour document for educational reading. What’s still ahead is the long tail of array-language features (rank polymorphism, fork composition, J-style tacit programming) and the big backends. It is the language I will use to do the fine-tune-a-base-model item from part 1.

Tuplet — 2D Layout-Sensitive Language with Mintable Verbs

tuplet is the language I am driving as my main daily-language experiment. It is 2D-layout-sensitive (where a glyph sits on a grid matters), has first-class named tuples and multi-output verbs, and lets the user mint new verbs and new syntax via the * operator. The kernel is small; everything else — including control flow — is library code expressed in the kernel. The host is an OCaml-subset interpreter; the runtime target is Forth running on the COR24 emulator.

Tuplet is currently in the “wakes the dragons” phase of language development — the language compiles, demos run, but the OCaml interpreter underneath has been thrashing its heap until the GC work in flight (sw-cor24-ocaml#28) lands. Once that lands, Tuplet’s heap_limit should shrink, not stay where it is, and the language will start to feel less fragile.

DiscoveryOne — 3D Successor

Already covered above. DiscoveryOne is to Tuplet what Tuplet is to a flat language: one more dimension of authoring surface, one more affordance for separating concerns spatially rather than syntactically. It is the place where I get to ask the broader question — can authoring be 3D? — without bolting it onto a language whose users are already doing real work.

The 1980s Ancestors: Mass Compile and PL/EDIT

Two of the threads above have ancestors I worked on as a junior engineer at IBM in the 1980s — Mass Compile, a screen for scheduling batch compile jobs in advance (including jobs for code you had not finished writing), and PL/EDIT, a template-driven editor that expanded triggers into boilerplate via hotkey. Both ran on AQ, an MVS/ESA time-sharing service. The Throwback Thursday post tells the story in detail. The reason they come up here is the conceptual lineage: Mass Compile’s “do the expensive thing against whatever inputs are stable when it runs” is the same shape as sw-launcher’s content-addressed cache, and PL/EDIT’s “fill in the slot that matters and let the template handle the rest” is the same shape as DiscoveryOne’s facet authoring. Both ideas keep coming back, in different shapes, every time the dev loop gets a new bottleneck.

I maintained both tools; I did not write them. That was the right level for me at the time, and the vibe-maintenance post reprises the lesson forty years later: a tool you maintain long enough teaches you the design choices its author made and the seams where the next idea wants to break in. The bucket list, on this reading, is partly a list of the bottlenecks I have seen over the years and the surfaces I want to build to push back on them.

Visible Compilers — The Missing Tool Category

The unifying gap, behind all of the above, is visibility.

Almost every CS curriculum spends a semester on compilers. Almost every working engineer uses one every day. Almost no engineer has ever watched a compiler run — watched the lexer turn a stream of characters into tokens, watched the parser grow an AST, watched a type checker fail and recover, watched a register allocator color a graph, watched a heap fill up and a GC reclaim it. The mechanism is invisible. We read about it. We trust the diagrams in textbooks. We never see the diagram move.

The next chunk of the bucket list is the tooling that fixes that. For each of the five languages above (and ideally for the COR24 toolchain in general), I want a visible counterpart:

Step-Through Lexer

A panel that shows the source on the left and the token stream on the right. Click “step” — the cursor advances by one token, the new token glows in the right panel, the consumed characters fade in the left panel. Speed it up to “auto” and the whole stream animates past at one-token-per-50ms. See the lexer.

Animated Parser

The same idea for the parser: source on the left, the AST growing on the right as a tree. Each shift / reduce step is a step. The current rule highlights. The error recovery, when it happens, is visible — a subtree dies, a new one grows in its place, the resync token is annotated.

AST Viewer with Types Folded In

A static view (not animated) of the AST after the parser finishes, with type annotations folded into each node. Hover over a node to see its full type; click to dive into a subtree. The same view, but for the typed AST after the type checker runs, with inferred types added. Then the same view for each lowering pass — AST → CFG → SSA → linearized IR — with arrows showing what produced what.

Lowering and Codegen Side-by-Side

Three columns: source, IR, target assembly. Pick a line in any column; the corresponding range highlights in the other two. The lowering passes get their own animation: tail-call elimination shows the call disappearing and the branch appearing; closure conversion shows the free variables being collected and packed; trampolining shows the indirect jump being inserted.

Register Allocation, Visualized

The conflict graph. The live ranges. The interference. The spills. Watch the graph-coloring algorithm run, color by color. Watch the spill heuristics pick which range to evict. See what your compiler optimizer is actually doing when it picks r4 instead of r2 for that loop variable.

Simple Optimizations Before/After

Constant folding. Common subexpression elimination. Dead-code elimination. Loop-invariant code motion. Each one as a side-by-side before/after with the moved/removed code highlighted. The whole point of these is that they’re small and understandable if you can see them; they’re black-box magic if you can’t.

Heap and Stack Instrumentation

A live memory map. The stack growing and shrinking with each call/return. The heap filling with allocations, each allocation a colored block. Free / dispose / reclaim animates: the block fades, the free list pointer redirects, the block is gone. The hardest classes of bug — use-after-free, double-free, leaks — become visible the moment the memory map is.

Garbage Collectors at Work

Mark-and-sweep, copying, generational. Each one a different animation. Mark-and-sweep: a wave of color sweeps the heap from the root set; everything not colored gets reclaimed. Copying: two semi-spaces, the live objects walk from one to the other, the old space is wiped. Generational: nursery / tenured, promotions visible, write-barrier hits flagged. The OCaml interpreter’s incoming GC (sw-cor24-ocaml#28) would be the first candidate — I want to watch it run.

JITs Tiering Up

A function getting called once: interpreted. Called a thousand times: tier-up triggers, a jitter compiles a baseline native version, the call site rewrites itself, subsequent calls run at native speed. Hit a deopt: tier-down to the interpreter, the native code gets discarded, the next thousand calls retrigger the jit. This is the part of modern runtime engineering that is hardest to see; the visualization that makes it watchable would be the tool I would have wanted as a junior engineer.

The pattern across all of these: the textbook diagrams are static. The visualizer shows them moving. Once you have seen a register allocator color a graph, you cannot read about register allocation the same way again — the diagrams in the textbook map onto something you actually watched happen.

Why Now

All three categories above became viable in the same window for the same two reasons — retirement gave the time, AI agents gave the reach. Every one of these projects, on its own, would have been a multi-year team effort five years ago. Today they sit on the list, and the list is moving:

• A new paradigm of programming-language surface (DiscoveryOne) is one vertical slice (M7) from being demoable.
• Five language implementations sit between “compiles” and “in production daily use,” each filling a different niche in the small ecosystem.
• The visible-compiler tool category is the unifying frame — the surface I want to have for every compiler I write, including the five above.

The next post in the series will probably be about whichever of these turns out to land first. My money is on the lexer / parser visualizer for sw-MLPL, since the language is already runnable and the visualizer is mostly “yew web app” away. We’ll see.

The list keeps growing. The bucket keeps filling. That’s the point.

The Corollary to Vibe-Coding

Vibe-coding, as the term gets used: a human describes intent, an AI agent writes the code, the human accepts or redirects. The implicit assumption is that new code is the bottleneck. For a greenfield project, sure — there is nothing to maintain because there is nothing to maintain yet. For a lab whose accumulated output now spans 37 repositories — assemblers, emulators, cross-compilers, p-code VM, native interpreters for BASIC and Forth and APL and Smalltalk and Macrolisp and SNOBOL4, host tooling, the resident-shell trio, web demos for most of them — the bottleneck moved a long time ago. New code lands; new code interacts with old code; old code that was fine on its own now has a corner that nobody exercised; an issue gets opened.

Vibe-maintenance is the same loop with a different verb. The human writes an issue title. The agent reads the relevant code, locates the assumption that was wrong, makes a minimal patch, adds a regression test, and closes the issue. The human’s job is not to write the code; it is to write the issue with enough specificity that the agent has somewhere to start, and to read the diff with enough care that the test does not just pin in the bug under a different name.

The skill the human keeps is not “writing code.” It is symptom description.

The Status Tab as Visualization

web-sw-cor24-demos is the landing page for the COR24 ecosystem. Its Status tab makes the lab’s operational state visible at a glance:

• A 37-row table of every repo with a colored badge — “Try it” (green), “In dev” (yellow), “In plan” (orange), “Future” (red), “n/a” (neutral) — for repo readiness, web-UI readiness, and AgentRail saga presence.
• An issue chart per repo: open vs. closed counts and a sparkline.
• A Closed Issues by Repo & Date heatmap, generated by scripts/gen-closed-issues.sh from the GitHub API.
• A Commits by Repo & Hour heatmap, the same shape one row down.
• A “Gaps” panel calling out the cross-cutting work the lab has not yet done (software floating-point library, native COR24 C compiler, etc.).

The headline number on the closed-issues chart, at the time of writing: 28 repos, 141 issues, 18 days. Eight closed issues a day, sustained, across two dozen active repos. That is not an output a single human writing code by hand achieves. It is also not an output a single human reviewing AI-written code achieves if every issue requires a fresh greenfield design — it is only achievable because most of those 141 issues were bugs in code that already existed, and an agent can fix one of those in a fraction of the time it took to write the original.

The two heatmaps next to each other tell a story: the commits chart shows when work happened (clusters in the morning, fewer at night, weekend bursts when an idea hit); the closed-issues chart shows what work settled (each cell is a problem that has a regression test guarding it). The cells are mostly numbered links, so any cell on the chart is one click from a real PR diff. That traceability is the whole point.

Four Patterns of Vibe-Maintenance

Reading down the closed-issues report by category — not by repo — four kinds of fix dominate.

1. Capacity-Limit Bumps

The numerically-largest category. A compiler or interpreter has an internal table whose size was guessed at first commit (MAX_PROCS = 32, INPUT_BUF_SIZE = 8192, AST pool of 256 nodes, emit buffer of 32 KiB, string literal table of 32 entries). A real program hits the limit, the agent bumps it, and a follow-up issue raises it again later when an even bigger program lands.

A small sample, all closed in this window, all from sw-cor24-plsw and sw-cor24-pascal:

• “AST pool exhaustion (256 nodes) causes misleading parse errors.”
• “Source buffer (8 KiB) too small for larger programs.”
• “Emit buffer (32 KiB) too small for programs with large static data.”
• “DEF_MAX (32) too small — %DEFINE silently dropped when exceeded.”
• “Global symbol table limited to 64 entries (SYM_SCOPE_MAX).”
• “Raise MAX_PROCS from 32 to support larger programs.”
• “Raise MAX_STRINGS limit from 16 to support larger programs.”
• “Raise INPUT_BUF_SIZE from 32768 to support larger programs (third bump).”

Each one is a one-line const change plus a regression test that compiles a representative-sized input. The third-bump issue is the funny one: the limit is no longer a guess, it is a parameter that grows with the corpus. Eventually the right answer is “the table grows dynamically,” but the lab’s working assumption is that bumping a static limit is a one-cycle fix, while a dynamic table is a one-day refactor that earns its keep only after the same limit has been bumped enough times to justify it. The ratchet is the right tool for this kind of debt.

2. Subtle Codegen Bugs

The most interesting category. These are not “the feature is missing”; these are “the feature is silently wrong.” A few from the same window:

• sw-cor24-plsw#8: “BYTE field reads use signed lb instead of unsigned lbu.” A one-instruction error; values 128–255 sign-extend to negative integers, breaking pattern matching and arithmetic.
• sw-cor24-plsw#31: “Function return corrupts r1 -> jmp to PC=0 (programs that call PUT_DEC re-enter _start).” A clobbered callee-saved register; the symptom looks like an infinite loop with the program re-running from the top.
• sw-cor24-pcode#10: “p24-load: patch_code_relocations incorrectly relocates negative push literals.” A pointer-vs-immediate confusion in the linker; small negative integers get rewritten as garbage addresses.
• sw-cor24-x-tinyc#19: “Codegen: integer division with negative dividend returns wrong result.” The C cross-compiler’s sign-handling.
• sw-cor24-snobol4#13: “Arithmetic on a pattern-captured string returns garbage on first use.” A type-tag bug in the SNOBOL4 interpreter’s value union.
• sw-cor24-pascal#16: “write(chr(n)) outputs integer n instead of character.” Built-in dispatch on the wrong type.
• sw-cor24-basic#1: “ABS function silently returns wrong value (parsed as variable A).” The lexer treats ABS as a variable rather than a builtin, so ABS(-3) parses as (A) * BS * (-3) — a beautifully evil bug whose title carries the entire diagnosis.

These are the issues where vibe-maintenance shines. Each title is a complete reproducer in plain English. The agent reads the title, opens the relevant translation unit, finds the wrong instruction or the wrong dispatch, fixes it, writes a one-program regression test, and closes the issue. The human never wrote a line of code; the human wrote a fifteen-word symptom description.

3. Surface Language Features Rolling In

Each language interpreter ships with a minimum viable feature set, and demos that exercise more of the historical language drag in features that didn’t make the first cut:

• BASIC: DIM integer arrays, DATA / READ / RESTORE, ON expr GOTO/GOSUB, MOD, bitwise BAND/BOR/BXOR/SHL/SHR, CONT after STOP. (sw-cor24-basic#2..#7.)
• OCaml: top-level let bindings, multi-line match expressions, mutable refs, records, list combinators (map/fold_left/filter), char literals, block comments, exceptions. (sw-cor24-ocaml#3..#11.)
• Forth: forth-in-forth gets DO/LOOP, ?DO, WHILE/REPEAT, AGAIN, CONSTANT, VARIABLE, hashed dictionary; :NONAME. (sw-cor24-forth#1..#5.)
• SNOBOL4: SIZE/SUBSTR/CHAR builtins, pattern-replacement assignment, case-preserving INPUT mode. (sw-cor24-snobol4#1..#10.)
• TinyC: goto + labels, compound literals, designated initializers, _Noreturn, restrict, inline, octal literals, multi-dimensional array declarations. (sw-cor24-x-tinyc#2..#11.)

Each of these is the kind of feature that would take a human a half-day if they had to read the existing parser, find the right place to extend it, and add the right test fixtures. Vibe-coding compresses that to a half-hour of agent work plus a human-written acceptance criterion. The acceptance criterion is the part that does not get cheaper.

4. Cross-Cutting Tooling Bugs

The last category is the meta one: the tooling that generates the dashboards itself has bugs. A representative pair from the demos repo’s commit log, just in the past two weeks:

• fix UTC-to-local date conversion in gen-issue-chart, rebuild and deploy pages
• fix timezone in activity reports: convert UTC dates/hours to local, regenerate tables

Two separate “use Local::now() instead of Utc::now()” commits in two different generators. The cells in the heatmap were shifted by a few hours, which made yesterday’s work look like today’s, which made the dashboard wrong — subtly, in a way that would only catch the eye of someone who knew what they had committed yesterday. The agent fixed both. They are listed in the dashboard the agent generated. The fact that the dashboard works is itself a regression test on its own generators.

The Skill That Doesn’t Go Away

Every category above leans on the same human contribution: a precise description of the symptom, often as the issue title.

Compare the two SNOBOL4 issues:

• #1: “Missing string builtins: SIZE, SUBSTR, CHAR return 0 for all inputs.”
• #11: “OUTPUT corruption: concat-OUTPUT in a loop truncates when a different block declares a pattern-match with :F(forward_label).”

Both are real titles. Both are diagnoses, not just symptoms — they tell the agent exactly what subsystem to read. #1 is mechanical: open the builtins table, see that the entries return 0, fix them. #11 is forensic: the title names the loop, the operator, the block, the directive, and the conditional — the agent has the entire reproducer one paste away from a test fixture.

The bad version of either title would be “OUTPUT is broken.” That title costs the agent half its budget on guessing what “broken” means and produces a fix that may or may not address the real bug.

The skill the lab keeps practicing is writing the issue at the level of detail the agent needs. That is roughly the same skill an engineer uses to file a useful bug report against another engineer. The difference is that the audience is faster and cheaper than the engineer; the title is read inside a second, the diff is back inside a minute, and the regression test is attached. The economics of writing good issues, in a vibe-maintenance world, are vastly more favorable than they were when the audience was a human queue with their own backlog.

The Feedback Loop

Where It Sits in the Personal-Software Toolkit

sw-checklist keeps the shape of the code in line. sw-launcher keeps the shape of the load plan and memory budget in line. AgentRail keeps the shape of the work in line — one saga, one step at a time, with a faithful audit trail. The Status tab is the operational dashboard that makes the result of all three legible at a glance. None of those tools, individually, would be enough to keep a 37-repo lab maintainable by one person; together they make vibe-maintenance the steady-state mode of operation.

The car is up on the lift. The mechanic is not building anything new today. The mechanic is going around with a torque wrench, an oil drain, and a parts list, and at the end of the afternoon every gauge is in the green again. AI agents do not change which afternoons that work happens on. They change how many cars fit in the shop.

The Problem: Every Language Has Its Own Loader

The COR24 is a 24-bit machine with 1 MiB of SRAM, a 3 KiB EBR hardware stack, and an MMIO aperture at 0xFF0000. The host-side cor24-run emulator accepts a small surface — --load-binary path@hex_addr, --patch hex_addr=hex_value, --uart-input "...", --entry, --speed, -n — and that’s the universe.

What changes between repos is what gets loaded where, which runtime word has to be patched to point at the layer above it, and how source and data ride the UART. The Phase 0 survey looked at thirteen working repos and aggregated the patterns. A few from the comparison table:

Every project’s scripts/run-*.sh re-encodes one of these shapes. None of them validate. None of them cache. None of them notice when the OCaml heap and the DSL heap overlap. And every AI agent that touches these scripts adds its own subtle variation, because the shell script is the spec.

Two Axes, Five Shapes

The original PRD assumed one axis with three points (A: single image, B: runtime+image, C: nested interpreter). The survey says it is actually two axes:

• Build axis: hand-written assembly, compiled from a higher-level language, snapshot rehydrated by host tooling, or composite of N modules linked host-side.
• Run axis: one-shot batch (kick off and check UART), interactive REPL through UART, interactive shell with a resident process model, or edit-then-run via a resident editor.

The cross product yields five primitive shapes that cover everything sw-embed has written so far. The first three were already in the day-zero design; the last two emerged from the survey:

1. Single image at zero, UART source. Heap and stack embedded in the image. (apl, basic, forth, plsw, smalltalk-delegated.)
2. Runtime + image + patch. Native COR24 runtime at 0 plus a p-code image at a higher address with a code_ptr-style patch. (pascal single-unit and multi-unit, the OCaml/tuplet pattern without the heap patch.)
3. Nested interpreter with heap-limit patch and UART-after-EOT data. Adds a second patch (heap limit), and the UART payload is <source> + EOT + <runtime data>. (ocaml, tuplet.)
4. Multi-module composite image. The launcher loads N independently assembled modules at contiguous bases (snobol4 via link24) or at fixed slot addresses (macrolisp’s multi-module demo, monitor’s program registry). Linking happens host-side, not via patches.
5. Resident shell + paste-and-go. Monitor at 0, sws shell at 0x20000, programs at fixed slots, all preloaded together; transfer of control happens inside the emulator via a service-vector / trampoline (mon_invoke_program) and never returns to the host runner. (monitor, script, yocto-ed.)

A scenario picks one shape; the schema makes that pick explicit instead of implied by which shell script you happen to run.

Schema v1.1: Partition Grid (Considered, Then Rejected)

The first revision after the survey, schema v1.1, divided the 1 MiB SRAM into eight fixed partitions of 128 KiB and four regions per partition (code/heap/spare/stack, 32 KiB each). Most existing repos already align to obvious partition boundaries (0x000000, 0x010000, 0x040000, 0x080000, 0x0F0000), so re-stating those addresses in (partition, region) coordinates was mostly a labeling change.

It was the wrong move. The grid canonized a layout without taking a position on the budgets, which let oversized heaps express themselves as multi-cell claims and call it normal:

# v1.1: OCaml's 252 KiB heap, expressed as four contiguous cells.
# Schema accepts it, validator passes, nothing argues back.
[layers.ocaml_interp.segments.value_heap]
kind   = "heap"
grows  = "down"
claims = [
  { partition = 0, region = "spare" },
  { partition = 0, region = "stack" },
  { partition = 1, region = "code"  },
  { partition = 1, region = "heap"  },
]

That’s the OCaml interpreter’s current heap_limit = 0x03F000 written as a partition-cell list. Pinning down the layout this way looked like progress. It was actually normalization of the bug.

Schema v1.2: Memory Profiles + Heap Budgets

The second revision flipped the prior. From docs/memory-stance.md:

The COR24 board emulator targets 1 MiB SRAM. That is more, not less, than every machine these re-implemented languages were originally designed for: Forth in 4–16 KiB, BASIC in 4 KiB (Altair) to 32 KiB (MS BASIC for IBM PC), APL/360 in <128 KiB per partition, Smalltalk-72/76 in 128–512 KiB including the bitmap display, Macrolisp on a PDP-10 with 256 KiB total. The IBM PC shipped in 1981 with 16–256 KiB. By 1985 measure, 1 MiB and a tiny monitor is a luxurious environment.

If macrolisp on a PDP-10 fit in 256 KiB total — runtime, interpreter, and program — then the COR24 macrolisp’s ~288 KiB heap is not a constraint problem. Something has gone soft. The 1 MiB ceiling does not need to be raised. The heaps need to be shrunk.

v1.2 makes that the schema’s stance. Three concrete changes:

1. The fixed grid is gone. Replaced with named memory profiles. Each profile is an ordered list of partitions of arbitrary size, each with its own list of named regions of arbitrary kind and size, plus a budget block:

[memory_profiles.compiled-app]
description = "Single image at 0; small heap; small stack."

[[memory_profiles.compiled-app.partitions]]
name = "code"
base = "0x000000"
size = "0x010000"            # 64 KiB
regions = [
  { name = "code",   kind = "code",  size = "auto" },
  { name = "static", kind = "data",  size = "auto" },
]

[[memory_profiles.compiled-app.partitions]]
name = "heap"
base = "0x010000"
size = "0x008000"            # 32 KiB
regions = [{ name = "heap", kind = "heap", size = "0x008000" }]

[memory_profiles.compiled-app.budget]
code_max  = "0x008000"       # 32 KiB
heap_max  = "0x004000"       # 16 KiB
stack_max = "0x002000"       # 8 KiB
total_max = "0x010000"       # 64 KiB
justification_required = true

2. Five default profiles ship with the launcher, each sized per docs/heap-analysis.md:

A scenario picks a profile by name; the validator enforces that profile’s budget. Layers cite partitions and regions by name, not by hex.

3. Heaps over 32 KiB must argue for themselves through a heap_justification block:

[layers.ocaml_interp.heap_justification]
category = "gc-slack"
note     = "Mark/sweep GC; sized for working set + 2x slack."
measured_floor_kib = 64
tracking_issue     = "sw-cor24-ocaml#28"

Five categories, in roughly descending order of merit:

The default category for an undocumented oversized heap is dead-leak — because the heap-analysis pass found that all three of the demanding repos (ocaml, macrolisp, plsw) match exactly that pattern, and the first job of a budget is to refuse to normalize them.

What the Heap Analysis Found

docs/heap-analysis.md walks every repo with a claimed heap > 32 KiB and assigns it a category, a historical benchmark, and a shrinkage backlog:

OCaml’s GC work in sw-cor24-ocaml#28 is the one in flight. After it lands, tuplet’s heap_limit should shrink, not stay where it is. Macrolisp’s mark byte should be a mark bit (8x reduction). PL/SW’s compiler-output redundancy is fixable in one pass through the transpiler. The schema must support the current sizes transitionally, but the analysis doc must not normalize them. The current sizes are evidence of work to do; not the spec for the launcher.

Layers Are Composites, Not Blobs

Every other piece of the schema survives both revisions. A layer is still (artifact?) + (segments), and segments still have lifecycles:

• Embedded segments live inside the artifact. pvm.s reserves eval_stack, call_stack, and a small heap_seg statically; they are part of pvm.bin and the loader does not allocate them again, but the validator has to know they exist (resolved through the artifact’s listing) so the global overlap check sees them.
• Reserved segments are allocated by the loader at a configured cell with a configured size and zero-filled. The OCaml interpreter’s value heap, the Pascal eval stack, the DSL heap on top — none of these fit in the COR24’s 3 KiB EBR; they live in high SRAM cells and the runtime gets patched to point at them.
• Patched is the verb that ties the two together. A reserved segment with value = "self.address" (or self.end for down-growing heaps) tells the loader to write its own resolved address into the runtime’s heap_base / heap_limit symbol, so the runtime knows where to find the heap the loader just allocated for it.

Patches in v1.2 also accept two value forms that the survey demanded:

• value = "sidecar:<path>" reads a build-time-resolved address from a small text file. ocaml and tuplet today write build/code_ptr_addr.txt and build/heap_limit_addr.txt during their build; the schema makes that explicit and includes the sidecar in the cache key.
• target = "<upstream-layer>.<symbol>" lets a downstream layer reference a symbol in an upstream layer’s listing — including upstream layers from a vendored repo (Phase 2 step 002 just landed the resolver for this; tuplet wants pvm symbols from sw-cor24-ocaml’s build, not its own).

The Wizard’s Spellbook — sw-launch.toml

[scenarios.echo]
target         = "cor24"
memory_profile = "compiled-app"
layers         = ["program", "stdin"]
entry          = "0x000000"

[scenarios.echo.run]
timeout_ms = 2000
max_cycles = 200_000
halt_on    = "uart-eot"

[scenarios.echo.expect]
uart_contains = ["A"]
exit_code     = 0

[layers.program]
kind     = "assembler"
source   = "local"
input    = "src/echo.s"
tool     = "assembler"
artifact = "echo.bin"

[layers.program.segments.code]
kind   = "code"
claims = [{ partition = "code", region = "code" }]

[layers.stdin]
kind = "data"
input = "tests/echo-input.txt"
load.method = "uart"
load.max_bytes = 1024

sw-launch run     <scenario>    Build (with cache) and execute, check expectations.
sw-launch build   <scenario>    Build all layers; do not execute.
sw-launch check   <scenario>    Validate config + lock; no tools run.
sw-launch graph   <scenario>    Print layer DAG (text or --json).
sw-launch cache   list          List cached artifacts.
sw-launch vendor  sync          Resolve and pin all dependencies.
sw-launch doctor                Verify host tools (cor24-run, pa24r, pl24r) found.

Phase 1: What Runs Today

The Phase 1 saga (sw-launcher-phase1, ten steps) closed clean on April 28. End state:

• sw-launch run echo --config tests/fixtures/scenario_a/sw-launch.toml exits 0 and prints A (the captured UART output).
• sw-launch check echo validates the scenario without spawning the emulator.
• sw-launch build echo assembles every assembler-kind layer under <config-dir>/.sw-launch/build/<scenario>/<layer>/ with a sha256-keyed in-process memoization cache.
• 60 tests across 11 binaries, including 2 end-to-end against the real cor24-run binary, all green.
• validate.rs implements 17 stable error codes, each with a negative test asserting the exact code and span.

The integration tests ran against cor24-run 0.1.0, rustc 1.94.1, edition 2024, on Darwin 24.6.0. Every one of those versions is recorded in the repo’s status.md so future-me knows what “Phase 1 worked” actually meant.

Phase 2 (sw-launcher-phase2) is open and seeded with five steps; step 001 (PCode tool with SourceSpec resolution) and step 002 (cross-layer listing-symbol patches resolve at scenario validate time) just landed. Phase 2’s target is end-to-end Scenario B: COR24 runtime at 0 plus a p-code blob at a higher address with a code_ptr patch — the smallest meaningful test that the launcher can express the layered shape that today’s sw-cor24-pcode and sw-cor24-pascal demos use.

Validation: Catch Collisions Before the Emulator Does

The validator is the most important verb. sw-launch check reads the TOML and the lockfile, walks every segment of every layer in the scenario, computes absolute address ranges (resolving profile partitions to addresses, embedded segments through the producing layer’s listing, sidecars from disk), and runs the rules. Each rule has a stable error code so agents can match on it without scraping prose.

A subset, selected for what they catch:

--strict mode promotes most warnings to errors and always rejects dead-leak and algorithmic-bloat justifications. CI runs strict; local check runs lax so the shrinkage work can land incrementally without breaking the build.

Caching, Vendoring, and the Lockfile

The cost of not caching is that every test re-assembles pvm.s, every demo re-builds the host toolchain, every CI run wastes minutes. Phase 1 ships an in-process memoization cache (sha256 keyed on (input bytes, tool version, args, output filename)) inside the assembler tool wrapper; Phase 4 will lift that to a persistent on-disk cache at ~/.cache/sw-launch/. The key formula already accounts for the hard cases:

layer_key = sha256(
    schema_version
  | normalize_toml(layer_config)
  | hash_each(input_files)
  | tool_version_hash
  | dependency_layer_hashes (in topo order)
  | resolved_address_or_uart_marker
  | sidecar_contents (if any)
)

A cache hit is sound — if the key matches, the artifact would be byte-identical to a fresh build, so reusing it can never produce a different scenario result. Sidecar contents are in the key because v1.2’s value = "sidecar:..." patch source needs the cache to invalidate when the sidecar changes.

The vendor side is symmetric. The survey was unflattering — ten of thirteen repos pin nothing at all, and one (tuplet) inherits its pins transitively from sw-cor24-ocaml. Only sw-cor24-ocaml has a real vendor/<tool>/<version>/active.env model with commit SHAs. v1.2 makes the OCaml-style vendored model the default: sw-launch vendor sync (Phase 4) will resolve declared dependencies (sibling:, vendor:, eventually git:) and write sw-launch.lock with each artifact’s commit hash and SHA. sw-launch doctor will record the observed version of each PATH-resolved tool too, so drift is visible even when nothing is explicitly pinned.

What This Buys

The point is not that the TOML is shorter than the shell script — it is often longer. The point is what changes about the system:

1. One verb for agents. sw-launch run <scenario> replaces the ten variants of cor24-run --load-binary ... that agents kept reinventing.
2. Validation before the emulator. The most expensive failure mode — “ran for forty seconds, traps silently, zero output” — is replaced by a fast check that names the colliding region and the offending TOML span.
3. Heaps argue for themselves. A 252 KiB heap is not waved through; it has to declare a category, a measured floor, and a tracking issue. --strict rejects dead-leak and algorithmic-bloat outright.
4. A schema for memory layout. Reserved heaps, embedded stacks, profile-named partitions, sidecar patches, cross-layer symbol references — all first-class in TOML. A new language port describes its memory shape; it does not write a new shell loader.
5. Vendor versions visible. Sibling-repo dependencies are pinned by commit hash in the lockfile, not by “whatever was checked out at 3pm.” PATH-resolved tools have their observed versions recorded too.
6. Phase 1 actually runs. The “what runs today” section is not a roadmap; it is what cargo test exercises, end-to-end, against a real emulator.

The wizard metaphor still fits the post marker: thirteen repos, each with its own ring of power, all in the end answering to one. sw-launcher is the one ring in the boring sense — the one place to encode the load plan — not in the corrupting sense, hopefully. But the more accurate metaphor for v1.2 is that the schema is a budget officer: every heap that wants more than 32 KiB has to file paperwork, and the default verdict on the paperwork is “this is a leak; prove otherwise.”

Where It Sits in the Personal-Software Toolkit

sw-checklist, now part of the AI Tools series, sits at a different layer of the same problem: AI agents working alone produce too much variety in places where uniformity is cheaper. sw-checklist constrains the shape of the code (function/file/module/crate size limits); sw-launcher constrains the shape of the load plan and the memory budget (which addresses, which patches, how big a heap can grow before it has to file paperwork). Both are accidental complexity in Brooks’s sense. Both are paying rent.

Phase 0 (survey) and Phase 1 (Scenario A end-to-end) are done. Schema v1.1 was a wrong turn that taught the right lesson: do not canonize the layout without taking a position on the budgets. Schema v1.2 takes that position, in writing, with five default profiles sized against historical implementations from the 1970s and 1980s. Phase 2 (Scenario B, runtime + p-code blob with cross-layer patches) is in flight; Phase 3 brings Scenario C (nested interpreter, heap-limit-only patches — the tuplet shape); Phase 4 brings persistent caching and vendor sync; Phase 5 brings the resident-shell composite (D + E).

The wizard is just the post marker. The one ring is just the metaphor. The interesting part is the budget officer.

What the Bump Allocator Bought

The Pascal p-code VM is the runtime under pa24r (the Pascal compiler) and pl24r (the linker). Pascal source compiles to p-code; p-code executes on a small stack-and-heap VM that targets the COR24 ISA. Heap allocation, from day one, was the simplest thing that could work:

• A single contiguous heap region.
• A bump pointer.
• Allocate by advancing the pointer.
• free is a no-op.
• Out-of-heap is a hard fault.

That’s it. No metadata per allocation, no headers, no free list, no compaction — just a pointer and a high-water mark. The allocator fits in a handful of p-code instructions, has zero per-allocation overhead, and is trivially correct because there is nothing to be incorrect about. Allocation is O(1) and the worst case equals the best case.

This was the right call. Every Pascal demo on COR24 to date — the BASIC interpreter, small string-handling exercises, the sample programs in the web demo — has a working-set that fits comfortably under whatever heap size the VM is configured with. Nothing on the runway needed reclaim. Building a free list would have been YAGNI-bait: more code, more bugs, more places for a wrong-looking trace to come from, all to solve a problem nobody had.

The Forcing Function: OCaml-in-Pascal Meets Tuplet

The crossing-over moment came from the Tuplet front-end. Tuplet is the new glyph-and-whitespace language introduced in last weekend’s Saw post; its lexer and parser are written in OCaml, and OCaml itself runs — in the dogfooded version — on top of the Pascal p-code VM.

That stack looks like this:

Lex-and-parse is exactly the workload a bump allocator does not like. Lexers churn out token objects; parsers build AST nodes by the thousand and discard most of the intermediate scaffolding (one-shot list cells, temporary closures, exception-carrying error paths). The amount of live data at any instant is small. The amount of allocated data over the lifetime of a parse is enormous. Bump allocation treats those two numbers as the same number.

Doubling the Heap, Once Is a Fix, Twice Is a Signal

For the first few inputs, the bump allocator was fine: small Tuplet sources parsed cleanly. Then the prelude grew, the test corpus grew, and parses started ending the same way — out of heap. The first response was the cheap one: double the heap. That bought one more input. Double again. One more input. The growth rate of the corpus was outrunning the growth rate of the heap, and every doubling pushed the failure later in the parse rather than removing it.

That’s the YAGNI exit signal. The next doubling wasn’t going to fix anything; it was just going to delay the same fault by another constant factor while consuming memory the host didn’t have to spare. The shape of the workload was demanding reclaim, and the allocator had to grow up.

Why YAGNI Worked, and Why It Stopped Working

It’s worth being precise about what changed, because the instinct after a story like this is “I should have built the free list from the start.” That’s the wrong lesson. The bump allocator was load-bearing for almost a year of demo work, during which:

• The runtime stayed small enough to read in one sitting.
• Memory bugs were impossible by construction (you can’t double-free a no-op).
• Every new Pascal feature landed against an allocator that had nothing to break.
• The build-out budget went into things that did matter for shipping demos — string handling, control flow, the p-code instruction set, the assembler, the linker.

The cost of building reclaim earlier wouldn’t just have been the code; it would have been all the other code that didn’t get written because the free list was eating the calendar. YAGNI bought a year of velocity. It paid for itself the first time, and again the second time, and would have paid for itself again if Tuplet had stayed small.

What expired wasn’t the allocator’s correctness. It was the assumption that the workload-set was bounded by demo shapes. A self-hosted compiler front-end is not a demo; it’s a real program with its own internal allocation discipline, and that discipline assumes there’s something on the other end of the heap willing to take memory back. The first time the VM hosts that kind of workload is the first time YAGNI doesn’t apply.

What “Grow Up” Looks Like

Takeaways

• A bump allocator with a no-op free is the right call when the workload-set is bounded by demos. It’s fast, small, and impossible to corrupt.
• “Real users” expire the assumption. A self-hosted compiler front-end is the smallest realistic workload that requires reclaim, because the working-set is small but the lifetime allocation is unbounded.
• Doubling the heap is a perfectly good response to a memory bug — once. Two doublings is a signal. Three is a confession.
• The next allocator should be exactly as small as the workload demands, and no smaller. Free list, header bit, coalesce on free; defer everything else until something asks for it.

YAGNI didn’t fail here. It cashed out. The allocator was a placeholder all along; today is the day it was supposed to be replaced. The trick was knowing it was a placeholder, and trusting the dogfooding loop to ring the bell when the placeholder ran out.

Future Dogfooding posts will follow the same pattern — a placeholder that earned its keep, the workload that finally outgrew it, and what filling the gap actually looked like. Next up: a postmortem on the reclaim implementation itself, once the OCaml-on-Pascal Tuplet parse can run end-to-end without a heap fault.

Brooks: Essential vs Accidental Complexity

Fred Brooks’s No Silver Bullet (1986, later folded into the 20th-anniversary edition of The Mythical Man-Month) draws the line that has framed this argument for forty years:

• Essential complexity is the complexity inherent in the problem itself. Modeling tax law is hard because tax law is hard. There is no clever framework that erases the irregularities of the rules.
• Accidental complexity is the complexity introduced by the tools, languages, and processes we use to attack the problem. CRUD boilerplate, build-system friction, framework idioms — none of it is part of the problem; all of it is part of the cost of solving the problem with the tools at hand.

Brooks’s punchline was that decades of progress had eaten most of the accidental complexity (assemblers, then high-level languages, then garbage collection, then better debuggers), and that future productivity gains would have to come from attacking essential complexity — which is much harder, because it sits inside the problem and refuses to be abstracted away.

That framing still holds. What it does not say — and what is the interesting modern question — is that not all accidental complexity is waste. Some of it is investment. Some of it pays rent.

Hickey: Simple vs Easy, Complect vs Decomplect

Rich Hickey’s Simple Made Easy (Strange Loop 2011) sharpens the same axis from a different angle. Restating it briefly — and this is my paraphrase, not a quote:

• Simple is un-complected: one role, one task, one concept, not braided with anything else. The Latin root is simplex — one fold.
• Easy is familiar and near-at-hand: requires little new learning, fits the muscles you already have.
• Complex is complected — braided, interleaved, two or more concerns sharing a single piece of code.

Hickey’s central claim is that we mistake easy for simple. Reaching for the familiar tool is easy, but it often produces complected code: classes that hold both state and identity, functions that mix decisions with effects, modules that interleave domain logic with transport. Easy now, complex later. Simple, by contrast, is often not easy — it requires more upfront thought to keep concerns separated — but the resulting code is decomplected and stays decomplected as it grows.

Brooks tells you what kind of complexity you are paying. Hickey tells you how the payment compounds. Together they suggest a strategy: accept some accidental cost up front if and only if the payment buys you simple — decomplected, single-role — code.

The Investment Thesis

This is the move I want to defend: some accidental complexity is the cheapest known way to preserve the focus on essential complexity.

A linter is accidental. It rejects code that the language would otherwise compile. The cost is real — the AI agent burns tokens fixing line lengths, the human burns minutes reading diagnostics. The payment is that the next reader can recognize patterns instantly because the surface is uniform.

A TDD loop is accidental. It demands two passes for every line of behavior — the test that fails, then the code that makes it pass. The cost is doubled output. The payment is that essential changes become localized: when the model of the world is wrong, the test names tell you exactly which assumption broke.

Code metrics are accidental. There is nothing wrong, in the language sense, with a 600-line file or a module that holds 12 functions. The payment is that thresholds force the next level of decomposition — a 25-line function ceiling makes you name the sub-step; a 4-functions-per-module warning makes you ask whether two of those functions are really one thing braided with another. Hickey would call that decomplecting.

In all three cases the accidental complexity is paying rent on essential clarity.

sw-checklist as a Forcing Function on AI Agents

sw-checklist is a Rust CLI I run against a project to check conformance. It auto-detects project type — Rust crate, workspace, CLI tool, web UI — and runs the appropriate checks. The interesting checks for this post are the modularity ones:

The numbers themselves are debatable. What is not debatable is what they do to the agent’s behavior over time. There are two regimes:

• Reactive. The agent writes whatever it wants, runs the checklist, sees a failure on “module X has 9 functions,” and rewrites to split. This costs tokens. It also produces good code — the split is often the decomplecting step that the agent would have skipped on its own.
• Anticipatory. Eventually the agent starts splitting before the checklist runs. New code lands closer to the thresholds on the first pass, with named sub-modules and small functions, because the agent has internalized the constraint as a writing style rather than a post-hoc fix-up.

The transition is the interesting moment. It does not happen on day one. It happens after enough cycles that the model has built up a gradient toward the shape of the constraint. From then on, the accidental cost shrinks because the agent is no longer paying for re-writes — it is writing decomplected code on the first try.

The linter and the TDD loop have the same shape. Each one is an accidental cost up front and a style eventually. Each one decomplects a different axis: the linter normalizes the surface, TDD localizes the model, sw-checklist enforces the decomposition.

The Ratchet

De-complexifying as a Practice

Pull the threads together:

1. Brooks: distinguish accidental from essential complexity, and spend on accidental cost only where it preserves essential clarity.
2. Hickey: aim for simple (decomplected), not just easy (familiar). The two are not the same and confusing them is how complected code grows.
3. The investment thesis: linter, TDD, and code metrics are accidental costs that pay rent in decomplecting — they make essential complexity stay visible.
4. The forcing function: AI agents respond to constraints first reactively, then anticipatorily. The sooner the constraint is in the loop, the sooner the agent’s output moves from messy-and-correct to focused-and-correct.
5. The ratchet: tech debt may slip a tooth but the wrench only turns one way. Cumulative direction matters more than per-commit purity.

The phrase I keep coming back to is de-complexify. It is not the same as simplify. Simplifying is reducing scope; de-complexifying is keeping the same scope while pulling the strands apart so each strand has one job. Hickey’s word for the move is decomplect. Brooks would call the result a code base where the essential complexity is visible and the accidental complexity is bounded.

Vibe-coding done well is exactly that: AI agents producing focused, decomplected code, fast, because the constraints are doing the de-complexifying work in the background and the agent has learned to write inside them.

The constraints cost something. They are accidental complexity. They are also the only way I have found to keep the essential complexity in view long enough to actually solve it. sw-checklist is one piece of that personal-software toolkit — a small CLI whose only job is to make the next decomplecting step impossible to ignore.