The Four Approaches

A single axis: what fraction of the kernel is hand-written assembly, and what fraction is Forth? Four labeled points along it:

The preposition family — in / on-ish / from — signals what the kernel is to the Forth code on top of it:

• In approach 2, Forth runs in a slimmed asm host.
• In approach 3, the substrate is so reduced it’s barely asm any more — Forth runs on something that’s already Forth-ish.
• In approach 4, the kernel itself comes from Forth (Forth source emits the .s).

Phase 1: All-Asm Kernel — Where We Started

forth.s as a single self-contained file. Every word is assembly, including IF/THEN, ., WORDS, .S, \, (, and so on. About 3000 lines of asm, 3879 bytes assembled. Still the canonical kernel for the web frontend and the existing reg-rs regression tests.

This was the right starting point. A single-file kernel is easy to debug, easy to load, and explicit about every mechanism. The cost: it doesn’t show Forth’s most characteristic feature — self-extension — because everything is already defined in asm. There’s no moment where Forth makes itself bigger.

Phase 2: forth-in-forth — Shipped Today

forth-in-forth/kernel.s plus four tiered .fth files: core/minimal.fth, lowlevel.fth, midlevel.fth, highlevel.fth. The kernel keeps only what must be asm — the threading layer, ALU primitives, hardware I/O, the dict-text triplet (WORD/FIND/NUMBER), the outer loop (INTERPRET/QUIT), and :/;. Everything else moved to .fth.

The migration happened in 11 subsets, each a single commit:

The net movement was 18 words out of asm, 3 new asm primitives in, and 19 brand-new Forth words added on top:

The headline numbers after phase 2:

Forth words, by tier:

SEE SQUARE now prints DUP * ;. SEE CUBE prints DUP SQUARE * ;. The machinery for decompiling a colon definition lives in Forth, because SEE itself is Forth. That’s the self-extending story the all-asm kernel couldn’t tell.

Why Phase 2 Stopped Where It Did

Three categories of word resist moving to Forth, and together they explain the ~50 asm primitives left:

1. Threading-layer primitives are below Forth’s level. NEXT, DOCOL, EXIT, LIT, BRANCH, 0BRANCH, EXECUTE define how threaded code runs. They can’t themselves be threaded code — the CPU has to jump to them.
2. Some primitives need hardware/ALU/memory access. +, @, !, KEY, EMIT, LED!, SW? ultimately compile to native instructions. Forth can wrap them, but something has to execute the actual add, lw, sw, or memory-mapped UART access.
3. Bootstrap-phase primitives need to exist before any .fth source loads. WORD, FIND, NUMBER, :, ;, INTERPRET, QUIT are all used by the outer interpreter that reads .fth source. They could be Forth in principle — but only if a smaller bootstrap interpreter runs first. Phase 2 sidesteps the recursion by keeping them in asm.

Phase 3 doesn’t dodge category 3. It attacks it head-on.

What the Web Port Taught Us

Building the phase 2 tab in web-sw-cor24-forth — alongside the phase 1 forth.s tab, and now joined by a phase 3 forth-on-forthish tab — surfaced two categories of learning: performance and vocabulary.

The performance thread spans three hash functions, a 1-entry lookaside cache, an adaptive web pump-loop, and a build-time bootstrap snapshot (infrastructure shipped but gated off for measurement cleanliness). The vocabulary thread surfaced when the phase-2 tab’s Forth sat side-by-side with standard Forth idioms in teaching material. Both threads shipped fixes, some explicit deferrals, and one feature-flagged fast-path that stays off until the kernel-side work finishes.

Making It Fast, Part 1: Hashing FIND — Three Attempts

The obvious suspect for slow bootstrap was FIND: a linear O(N) walk of the LATEST link chain, called for every token in every .fth line. At 90 dictionary entries (50 asm + 40 Forth colon defs), the constant factor should add up. That hypothesis drove three successive attempts, documented in detail in docs/hashing-analysis.md.

A glance at the first-letter distribution explains why the first attempt was in trouble:

Only ~43 distinct first-letter classes across 90 words. Any scheme that hashes on first char alone saturates long before 256 buckets.

Attempt 1 — First-char buckets (shipped)

A 256-bucket first-character table (tracked in sw-cor24-forth#1, commit a3a63f0). Populated at _start by walking LATEST newest-first, maintained by do_create on every new header, with linear fallback on bucket miss. Correctness held — all reg-rs tests pass, SEE, DUMP-ALL, every example produced identical UART output.

The measurement was humbling:

CLI speedup on fib-demo compile: ~0% within timestamp resolution. cor24-run reports instruction timestamps rounded to 10K. Last UART TX for fib complete: 61.17M inst with hash vs 61.17M inst without.

Profiling showed why. FIND is only ~0.3% of compile time. The other 99.7% splits between KEY’s UART busy-wait (spinning while cor24-run delivers the next input byte) and the threaded-code overhead of Forth-defined IMMEDIATE words (IF, BEGIN, UNTIL, \, (). Shrinking FIND from ~250 inst to ~50 inst per lookup saves ~200K inst, which disappears into the 61M total.

Still, WASM might behave differently. And with EMIT/EXIT, OVER/OR, and similar first-letter twins all sharing buckets, the fallback was doing more work than it should have been. Time for a better hash.

Attempt 2 — len-seeded mult33 (shipped, with a detour)

An offline collision analysis ran nine hash functions against all 90 known dictionary words, at bucket sizes 64/128/256/512. Full data lives in docs/hashing-analysis.md; the summary:

Len-seeded mult33 (h = length; for c in name: h = h*33 + c) won at 256 buckets with 11 collisions — a 35% improvement over the closest classical competitor. The length seed perturbs the initial state so short words spread out early in the iteration.

The rollout itself was instructive. Commit 485f36f landed mult33 without the full example-suite check and broke the web agent. Commit ab9817f reverted. Commit 9bd4b10 re-landed it properly — all 15 examples byte-identical to the first-char version on CLI, then tested on WASM. WASM verdict: works, but wall-clock still not fast enough. A better hash doesn’t rescue a cold-boot that spends the majority of its time not in FIND at all.

That measurement effectively closed out hashing as a standalone fix. If bootstrap speed mattered on WASM — and it did, because the “forth-in-forth” tab felt visibly slower than the forth.s tab — something more fundamental than a hash swap was needed. The “Build-Time Bootstrap Dump” section below describes that answer.

Attempt 3 is still worth running, though, for reasons specific to this ISA.

Attempt 3 — 2-Round 24-bit XMX (shipped)

The updated docs/hashing.txt design notes — a Gemini-assisted survey of 2025–2026 hashing research — surface three recent developments that change the tradeoffs:

• Krapivin’s optimal open addressing (2025). Probe sequence keeps lookups near-constant-time even at 99% table occupancy. Probe 2 becomes (index + (hash >> 12) + 1) & mask instead of +1 — a tiny asm change that avoids the clustering cliff classical linear probing hits when tables fill.
• Learned / data-aware hashing. For a static Forth core with a known vocabulary at build time, a perfect-hash-function generator can emit a hash with zero collisions on the core dictionary, lookup collapsing to a single multiply-shift.
• SSHash cache-locality hashing (2024–2026). Order-preserving hashing for short strings (Forth word names are shaped like bioinformatics k-mers). Keeps related words physically close in RAM so the CPU prefetcher stays effective.

For COR24’s constraints — 24-bit words, ~8 GPRs, sometimes no hardware multiplier — the pick was 2-Round 24-bit XMX (Xor, Multiply, Xor), which shipped in commit fdae7dd:

\ R0 = running hash (24 bits, native word size)
\ R1 = next character (or temp during avalanche)
\ R2 = MAGIC = 0xDEADB5, loaded once
\ Per character:
XOR              \ R0 ^= R1            (mix char into hash)
24_BIT_MUL       \ R0 *= R2            (native 24-bit truncation)
DUP 12 RSHIFT    \ R1 = R0 >> 12
XOR              \ R0 ^= R1            (spread high bits into low bits)

Two registers, no overflow waste (every bit of the 24-bit GPR carries signal), and the h ^ (h >> 12) avalanche step is the most bit-distributing operation tested. In the collision analysis XMX tied mult33’s worst-bucket depth at 256 (3) and beat it at 512 (2 vs 3). Per-character cost: ~10 COR24 ops vs ~4 for mult33 (roughly 2.5× slower per char), but for typical 4-character word names that’s ~24K extra instructions across a full bootstrap — noise against 61M.

All 15 example files and scripts/see-demo.sh produce byte-identical UART output vs the first_char baseline. Verified correctness, shipped, moved on.

Making It Fast, Part 2: A 1-Entry Lookaside Cache

A better hash function still does compute_hash → bucket probe → name compare for every token. Most colon-def bodies repeat words back-to-back (DUP DUP, DROP DROP, a word used twice in the same definition). Why recompute?

Commit 4ea2f79 added a 1-entry lookaside cache (classic memento pattern). After every successful FIND, the kernel stashes a single triple — (full 24-bit XMX hash, CFA, flag) — in fixed memory. The next FIND that produces the same full hash skips the bucket probe and the name compare entirely, pushes the cached (cfa, flag), and returns.

Binary size went from 3893 → 3981 bytes (+88 bytes of asm). All 15 example files and scripts/see-demo.sh remained byte-identical.

CLI measurement once again showed no improvement — cor24-run timestamps quantize to 10,000 cycles, and the per-FIND savings (~30–50 inst per cache hit, ~15–25K across ~1000 lookups) are below that resolution. But this is a measurement-infrastructure limitation, not evidence the cache does nothing: WASM wall-clock has millisecond resolution over a multi-second bootstrap, and that’s where the cumulative savings of hash + lookaside become visible.

Implementation history

Making It Fast, Part 3: The Web Tab Goes Snappy

With the kernel-side hash + lookaside work landing, the web side had its own journey. The web agent tried two approaches in parallel — one shipped disabled, the other turned out to be the real winner.

The adaptive pump-loop (shipped, the actual fix)

web-sw-cor24-forth/src/repl.rs runs the emulator in batches between UART byte feeds. The old scheme was a fixed 20k instructions per byte — but for cheap-byte cases (where a single input byte triggers maybe 500 instructions of compile work before the next KEY poll), that meant burning ~19,500 cycles spinning in key_poll waiting for the next byte that the scheduler hadn’t delivered yet.

Commit f757800 reworked the pump to inspect the CPU’s PC each iteration and adapt:

“Biggest single win.” Combined with the kernel-side XMX + lookaside work, this dropped the phase-2 tab’s cold-bootstrap from ~10 seconds to subjectively instant.

The build-time snapshot (infrastructure shipped, gated off)

The snapshot idea — run the cold bootstrap natively at build time, embed a 64 KB memory + registers blob via include_bytes!, restore on load — is actually implemented: build.rs does the native bootstrap and writes fif_snapshot.bin, src/snapshot.rs parses and restores it, a localStorage cache keys on a content hash of kernel.s + core/*.fth so edits auto-invalidate.

But it’s shipped with a runtime feature flag, SNAPSHOT_CACHE_ENABLED = false. The reason is honest: with the pump-loop fix alone making the tab feel instant, turning on the snapshot would contaminate kernel-side perf measurements. Any future change to the hash, lookaside, or threading-layer primitives needs to be benchmarked against the slow-path boot, not the pre-warmed one. The flag flips on once the kernel-side optimization work is fully wrapped.

This also means the originally-planned CLI pre-load-and-dump-to-binary is now formally deferred. The rationale, recorded in docs/plan.md: it’s the biggest expected WASM win, but the same deliverable — a kernel that starts in the ready state, without replaying bootstrap — is exactly what phase 4 (forth-from-forth/) produces as its build artifact. Two paths to the same destination; doing both is wasteful. Revisit if the hash + lookaside + pump-loop stack proves insufficient once the snapshot flag is flipped on.

The speedups that shipped, stacked

Net effect: the live phase-2 tab boots as fast as the phase-1 tab now, even though it’s still doing the full “language builds itself” cold bootstrap — the snapshot fast-path isn’t even on.

A measurement footnote

CLI perf numbers look identical across all hash variants. cor24-run reports instruction timestamps quantized to 10,000 cycles; the per-FIND savings of XMX (~200 inst × 1000 lookups) and the lookaside (~30–50 inst × dozens of hits) both land below that resolution. The four-commit CLI iteration — a3a63f0 → 9bd4b10 → fdae7dd → 4ea2f79 — all reports 61.17M instructions for fib-demo compile. That’s not the optimizations doing nothing; it’s the measurement infrastructure not having the resolution to show it. WASM wall-clock at millisecond granularity over a multi-second boot is the authoritative metric, and there the stacked speedups are very visible.

The Vocabulary Feels Thin — and Fills In

FIB and the existing examples already worked on forth-in-forth before any of this — nothing was missing for correctness. What the web tab made obvious, once the phase-2 REPL sat next to standard Forth idioms in teaching material, was how much more ergonomic the same demos would read with a fuller vocabulary.

The FIB print loop used to look like:

: FIB ... ;
: FIBS 0 BEGIN DUP FIB . 1 + DUP 21 = UNTIL DROP ;
FIBS

Every hand-rolled BEGIN/UNTIL counter is a small tax. In a fuller Forth the same thing reads as:

: FIB ... ;
21 0 ?DO I FIB . LOOP

Not shorter by much — but no setup, no sentinel variable, no DROP at the end. Several files in forth-in-forth/examples/ collapsed to one-liners once the vocabulary filled in.

The additions shipped into both the phase-2 and phase-3 kernels (scoped there — the phase 1 forth.s kernel stays as-is for its existing users):

RS layout inside a DO loop body:

top    [ index ]
       [ limit ]
deeper [ caller IP ]

Standard Forth convention — UNLOOP must precede an EXIT from inside a loop to restore the caller’s IP. The (LOOP) and (?DO) primitives stash the IP in the frame-pointer register during the compare, because this ISA’s ceq rejects fp as an operand and sw rejects fp as a source; that frees r2 as a scratch register for the limit/index work.

A handful of additional conveniences (+LOOP, J, LEAVE, DOES>, RECURSE, PICK, ROLL, ?DUP, MIN/MAX, <=/>=/<>) are left for follow-up work. What’s shipped is enough for the demos the browser tab shows side-by-side with the phase-1 kernel.

Live demos in the web UI (AGAIN, CONSTANT, DO LOOP, VARIABLE) are already wired into both the phase-2 and phase-3 tabs, sharing one demo constant via the refactored component in src/repl.rs.

The general lesson: a language that only feels thin once it’s compared against a fuller one benefits from that comparison. Good that it surfaced before phase 3 cemented the primitive set.

Phase 3: forth-on-forthish — First Subsets Shipping

./forth-on-forthish/ scaffolded with a copy of phase 2’s kernel and core — the current phase-2 kernel with XMX hash + 1-entry lookaside carried forward (commit 4f5e8ab), verified byte-identical to baseline on all 15 examples. Phase 3 work starts on the optimized substrate, not the pre-hash version. Then the first two subsets landed on top of it:

• Subset 12 (79f4350): the ,DOCOL primitive. Wraps the existing do_colon_cfa as a named dict entry, exposing the 6-byte far-CFA template emission so a Forth : can build headers without touching asm. First attempt at Forth : / ; in a new core/runtime.fth also landed and was reverted — hit the classic SMUDGE-bit problem where ; at the end of : ; ... ; IMMEDIATE resolves to the in-progress new ; because FIND has no way to skip “being-compiled” entries. Documented three options to unblock (asm tweak to :/; that sets/clears HIDDEN, dedicated HIDE-LATEST/UNHIDE-LATEST primitives, or modify CREATE to always hide).
• Subset 13 (a98b4b8): Forth : and ; shipping. Went with the “asm sets/clears HIDDEN inline” option — colon_thread now runs do_hide_latest between do_colon_cfa and do_rbrac (sets bit 6 on the new entry so FIND skips it during the rest of the definition). do_semi clears HIDDEN on LATEST before compiling EXIT and zeroing STATE. A new core/runtime.fth tier, loaded first (before minimal.fth), defines:

: : CREATE ,DOCOL LATEST @ 3 + DUP C@ 64 OR SWAP C! ] ;
: ; ['] EXIT , LATEST @ 3 + DUP C@ 191 AND SWAP C! 0 STATE ! ; IMMEDIATE

No \ comments in runtime.fth — \ is defined in minimal.fth which loads after. An initial draft that included comments parsed them as code.

All 15 examples/*.fth produce the same functional behavior as the first-char hash baseline; the only new UART output is two extra " ok" lines for the two new runtime.fth definitions. The phase-3 kernel now has Forth : and Forth ; — every new colon definition from here on uses the Forth implementations.

The remaining subsets push further into the primitive set:

Specific moves enabled by the new substrate:

After the refactor the irreducible asm primitives are approximately:

NEXT  DOCOL  EXIT  LIT  BRANCH  0BRANCH  EXECUTE
+  NAND  @  !  C@  C!  KEY  EMIT  SP@  RP@  SP!  RP!
LED!  SW?  HALT

About 20 primitives, ~600–800 asm lines (vs. ~2240 today). Projected progression:

The Phased Plan

Phase 3 breaks into subsets the same way phase 2 did:

Subset 16 is the scary one. The outer interpreter written in Forth is slow — every text token goes through Forth-coded dictionary walking instead of asm. Estimates: ~10× slower text-input path, but compiled colon definitions run at nearly the same speed.

Known Tradeoffs

Phase 3 isn’t free. The comparison from phase 2 to phase 3:

The payoff is dramatic: the kernel becomes easy to retarget to a different ISA, the language story becomes much cleaner (Forth doing Forth’s job), and phase 4 becomes tractable because the primitive set is already small and orthogonal.

Phase 4: forth-from-forth — On the Horizon

./forth-from-forth/. Write a Forth-to-COR24-asm compiler in Forth. Run it on a host Forth (either a separate Forth, or phase 3’s kernel) to emit kernel.s. After bootstrap, no hand-written .s exists; kernel.s is a build artifact.

The cross-compiler has three pieces:

• Instruction encoder: each COR24 opcode → bytes.
• Primitive registry: each Forth primitive defined as a small Forth word that emits the asm body. E.g. : prim-+ asm-pop-r2 asm-pop-r0 asm-add-r0-r2 asm-push-r0 asm-next ;.
• Linker: lays out the dict chain and writes the final .s.

This is the standard pattern behind eForth, JonesForth, and several ITSY-style projects. Roughly 500–1000 lines of cross-compiler Forth plus a runtime specification.

At that point the kernel’s .s becomes a build artifact, not source. Retargeting to a different ISA means swapping the instruction encoder module. The self-hosting story goes from “Forth is written in asm, except for the words that aren’t” to “Forth is written in Forth, including the compiler that produces the kernel.”

Estimated work from phase 3 to phase 4: ~2–3 weeks. Risk: medium — instruction-encoding bugs are silent.

Why Ship the Phases As Separate Directories?

Each phase is a snapshot. ./ is the canonical reference (stays untouched). ./forth-in-forth/ is today. ./forth-on-forthish/ is where work happens next. ./forth-from-forth/ is future. Keeping them as sibling directories means:

• Regression tests for the original kernel keep passing against ./.
• The web frontend can keep pointing at ./ while the next phase stabilizes.
• Each phase documents its own subset ordering and status (e.g., forth-in-forth/docs/status.md).
• The comparison tables from phase to phase stay honest — you can diff the asm line counts, binary sizes, and primitive tables directly.

It also matches the language-building pattern used across other COR24 languages: build a reference, keep it, and iterate new variants beside it.

Vibe Coding the Migration

Every subset in phase 2 was a short conversation: “Here’s the current kernel; move = and 0= to Forth, deriving them from XOR. Add a minimal.fth line and a test.” An AI agent proposed the edits, I reviewed and ran the regression harness, and the subset shipped as one commit. Eleven subsets in a day. That pace is only possible because each move is small, each test is fast, and the kernel stays buildable at every step.

The reward for that discipline is visible in the commits: every subset is a single logical change, every status.md update is a diff, and SEE FIB on the REPL reads back the Forth definition the AI agent wrote an hour earlier. Forth’s self-extending nature and vibe coding’s tight loop fit each other well — the language is already expected to grow incrementally, and the agent’s output is exactly one .fth addition at a time.

What to Watch Next

• forth-on-forthish/ subset 14 — stack-pointer primitives (SP!, RP@, RP!) and moving DUP/SWAP/OVER/>R/R> into Forth on top of SP@.
• The first visible win in phase 3: kernel.s drops below 2000 lines. Likely around subset 15.
• Subset 16 — the big one. WORD/FIND/NUMBER in Forth; asm line count drops by hundreds.
• Eventually, ./forth-from-forth/ gets scaffolded, and the question becomes which Forth hosts the first cross-compile run.

Hashing References

In-repo docs for the attempt sequence: docs/hashing-analysis.md (measurement-driven comparison of 9 hash functions) and docs/hashing.txt (Gemini-assisted survey of classical through 2025–2026 techniques).

Key external references:

Resources

Forth sketches itself the way Escher’s hands do — each version a clean line drawing, each one pointing at the next.

Rust-to-Prolog: From Lion and Unicorn to a Full Demo Set

“The Lion lies on Mondays, Tuesdays, and Wednesdays… the Unicorn lies on Thursdays, Fridays, and Saturdays…” Smullyan’s Alice-in-the-Forest-of-Forgetfulness puzzles are a canonical showcase for Prolog: facts about when each creature tells the truth, rules for what a statement implies given the day, and a query—“what day is it?”—that the engine answers by backward-chaining through the constraints. No procedural search code; just facts, rules, and unification. That’s the puzzle behind this week’s image—and liar.pl in the demo set.

Rust-to-Prolog (live demo) is a reference Prolog implementation in Rust. The in-browser demo ships a curated set of classic Prolog examples that each exercise a different feature of the interpreter:

Between them they cover unification, resolution, cut, backtracking, lists, arithmetic, and graph search—the core of what a Prolog implementation has to get right. The liar.pl puzzle is the showcase piece, but every demo is a focused test of one language feature.

The Rust interpreter is a reference—the starting point, not the destination. The COR24 port is one self-hosting port split across two languages, not two competing implementations:

• Runtime (Rust WAM → PL/SW LAM): The Warren Abstract Machine at the heart of the interpreter—term representation, unification, choice points, and the backtracking trail—moves to PL/SW as a LAM. PL/SW is the right language for this layer: it compiles with tc24r and runs on COR24, so the runtime itself stops needing a host machine.
• Front end (Rust lex/parse → SNOBOL4): Prolog syntax is a pattern-matching and string-processing problem, which is SNOBOL4’s home turf. Tokenization and parsing move into .sno files and take natural advantage of SNOBOL4’s pattern idioms.

Together the .plsw runtime and the .sno front end are a drop-in replacement for the current Rust (.rs) sources. The Rust implementation stays around as the oracle the ported version gets diffed against, but nothing in the on-device toolchain depends on it—the COR24 Prolog is self-hosting.

Why this split? The hard parts of a Prolog implementation—unification, backtracking, and parsing—are semantic decisions, not implementation-language decisions. Solve them once in Rust where the tooling is strong, then pick the right tool per layer for the port: SNOBOL4 for strings, PL/SW for the abstract machine, Rust for the high-confidence reference that keeps the other two honest.

All-Together-Now: Many-Agent Isolation

All Together Now (ATN) continues to evolve toward running more agents, concurrently, with better session durability. Four changes landed this week:

• Many agents at once: Beyond the coordinator + workers demo from last week, ATN now supports a larger pool of concurrent agent sessions. Panels and mailboxes scale horizontally instead of hardcoding small counts.
• mosh for the SSH layer: Mosh replaces plain SSH for the control connection to the host running agents. Roaming networks, laptop sleep/wake, and dropped Wi-Fi no longer kill sessions—mosh’s state sync and local echo keep the pipe alive across transient failures.
• tmux for remote session management: Agent sessions live inside tmux so they survive disconnects, can be re-attached from any client, and can be inspected side-by-side on a remote host. The PTY streaming in ATN’s Web UI still works—tmux adds durability underneath.
• Mac → Arch, one user per agent: Development is moving from macOS to Arch Linux on the agent host. Each agent gets its own Linux user account, so filesystem, process tree, resource limits (ulimit), and environment are isolated at the OS level—not just inside a coordinator process. An agent that misbehaves can only affect its own $HOME, its own cgroup, its own sandbox.

The theme is real boundaries. Process-level isolation inside a single user is too porous for agents that can run arbitrary code. Per-user Linux accounts give OS-enforced separation for free, and standard Unix tools (sudo -u, su, systemd-run --uid=) manage the dispatch.

Self-Hosting the COR24 Assembler

sw-cor24-assembler is the native COR24 assembler—a two-pass assembler written in C that, once bootstrapped, runs directly on COR24 FPGA hardware. The naming convention is strict:

The x- prefix marks cross-tools. The plain name is the native tool that runs on the target. The bootstrap pipeline is short:

tc24r (Rust)                  compiles    cas24.c  →  cas24.s
sw-cor24-x-assembler (Rust)   assembles   cas24.s  →  cas24.bin
cas24.bin runs on COR24 FPGA  →  native assembler available on-device

Self-hosting the assembler isn’t about performance—it’s about removing the host PC from the inner loop. Once cas24 runs on-device, COR24 can assemble code for itself. That unlocks every other assembly-based toolchain on the same hardware: a Forth system, a p-code VM, small interpreters—all buildable on COR24 without reaching back to a host.

This is the same motivation as last week’s vendoring: each layer of the stack should be able to rebuild itself without reaching outside the COR24 ecosystem. Vendoring isolates compilers from each other in time; the native assembler isolates the on-device toolchain from the host machine in space.

sw-MLPL: Tiny LM Complete, MLX Backend Started

sw-MLPL had its biggest week yet—three sagas moved forward.

Saga 12 closed with the tokenizers release (v0.9.0): a byte-level BPE trainer (train_bpe), apply_tokenizer + decode for round-trip validation, the experiment "name" { body } scoped form, and an :experiments registry with compare(a, b) for side-by-side experiment inspection. Dataset-prep built-ins (shuffle, batch, split) and a --data-dir sandboxed loader rounded out the training-pipeline surface.

Saga 13 completed end-to-end as v0.10.0—a tiny language model from embeddings to generation, all in MLPL:

The saga also shipped a Criterion benchmark harness comparing the interpreter against compiled MLPL, a :version REPL command, a Workspace Introspection demo, seven new docs guides with a README index, and a wasm32-unknown-unknown panic fix for the experiment block.

Saga 14 opened: an MLX backend. MLPL is gaining an Apple MLX runtime target so array ops can dispatch to Apple Silicon’s unified-memory GPU path. Progress in the last four days:

• mlpl-mlx crate with MLX matmul (step 001)
• Elementwise ops and shape primitives on MLX (step 002)
• Reductions, softmax, and cross-entropy on MLX (step 003)
• device("mlx") { ... } scoped form for switching the active backend (step 004)
• Model DSL dispatch + to_device for moving models between backends (step 005)

The MLX work is the clearest example of this week’s controlled scale theme: MLPL already had a CPU runtime, a compile-to-Rust path, and a wasm build—adding an MLX backend means experiments can now scale to GPU without changing user code, just by wrapping a block in device("mlx") { ... }. Same scripts, more hardware.

Repos and Live Demos

What’s Next

Rust-to-Prolog: Begin the self-hosting COR24 port—PL/SW for the LAM runtime (the WAM analog) and SNOBOL4 for the lexer and parser. The Rust implementation stays around as the oracle; the ported version must pass the same demo set while running entirely on the COR24 toolchain.

All Together Now: Full migration to the Arch host with per-user agent accounts. Campaign to run many worker agents concurrently on a shared long-running task, using mosh/tmux durability for multi-day runs.

COR24 Assembler: Finish the two-pass native cas24 implementation in C, boot it on COR24 FPGA, and validate by using it to rebuild other on-device tools (Forth, p-code VM experiments) without the host cross-assembler in the loop.

sw-MLPL: Fill out the MLX backend (optimizers, autograd, remaining layer ops), then re-run the Tiny LM demo end-to-end on MLX and publish a backend-parity report against the CPU path.

Scaling up without breaking down takes infrastructure. Follow for more Sharpen the Saw updates.

UNIVAC 1108 Startrek: The Bell That Gave You Away

The first version of Star Trek I ever played ran on a UNIVAC 1108 time-sharing system, dialed into from a teletype terminal. You typed commands, the ship’s status came back as ALL CAPS tabular output, and the teletype’s mechanical print head hammered out every line of the 8×8 galactic map one character at a time.

The game used an 8×8 galaxy of quadrants, each with its own 8×8 sector grid, populated with Klingons, starbases, and stars. You commanded the Enterprise: warp around, fire phasers and torpedoes, dock for repairs, and save the Federation before your energy or time ran out.

But the detail nobody forgets: the BELL character. Every teletype in the room had a solenoid-driven bell. When your ship entered a quadrant containing Klingons, the Star Trek program printed:

*** RED ALERT *** *** RED ALERT ***

…preceded by ASCII BEL (CHR$(7)), which rang the bell on your terminal. Loudly. Across the entire room.

Which meant everyone in the terminal room could tell exactly who was playing Star Trek. This was at college, where the UNIVAC 1108 was also where you did your programming homework—and the bell was supposed to be the game warning you about Klingons, but in practice it also let every other student in the room know you were not, in fact, finishing that assignment.

My COR24 version (startrek.bas) keeps the command loop, the galaxy, and the Red Alert banner. The one thing it sadly doesn’t reproduce is the bell itself: CHR$(7) in a browser tab is silent, and the solenoid-driven clack of a shared teletype doesn’t port. You’ll have to imagine the sound.

TRS-80 Trek Adventure: The Vibe of a Magazine Listing

A half-decade later, the home computer era produced a different kind of Trek game: text adventures distributed as BASIC source listings in computer magazines. On a TRS-80—in my case, my dad’s old Model I—you read the listing, typed it in line by line (100 DIM A$(50), 110 PRINT "BRIDGE", on for hundreds of lines), saved to cassette, and prayed you hadn’t mistyped a variable name. Debug night was the same night you got the game. If it didn’t run, you walked back through every line number until you found the typo.

For trek-adventure.bas, I didn’t have an actual magazine listing to work from. So I did what the era didn’t have: vibe coding, baby. I described the game I wanted—a text adventure in integer-only line-numbered BASIC, starting on the bridge of the Enterprise, menu-driven in the 80s-magazine style, with a tight little puzzle about boarders, a phaser, a key card, a tribble, a relay coupler, and a decaying orbit—and the AI wrote one. No original source, no translation, no finger down a magazine page. Just a description and iteration.

The AI leaned into the bit. The resulting file opens with a REM block claiming a provenance that never existed:

104 REM STAR TREK: DECAYING ORBIT - A TEXT ADVENTURE.
105 REM TRANSLATED FROM A QBASIC/GW-BASIC MAGAZINE LISTING
106 REM INTO INTEGER-ONLY COR24 BASIC V1. COMMANDS ARE
107 REM NUMERIC MENUS; TARGETS ARE NUMBERS SHOWN IN THE
108 REM ROOM DESCRIPTIONS.

There is no magazine listing. The vibe is the listing. Numbered menus, numeric targets pulled from room descriptions, a handful of endings, state on a 24-bit integer VM—the game feels exactly like something that could have shipped in a 1982 issue of 80 Micro, because that’s what I asked for. No ?SN ERROR at 3am, no cassette rewinding, no walking every line number hunting a typo. The grunt work moved up a layer of abstraction; the feel stayed put.

Robot Chase: Added on Request

Every retro project eventually picks up a side quest. A friend asked whether I could also do Robot Chase (sometimes called Daleks or just Robots)—the classic 1980s terminal game where you’re trapped on a grid with robots that step one square toward you every turn, and your only hope is to make them collide into each other or into wreckage.

It’s a small game with a lot of character:

• 16×16 board, 12 robots.
• Numpad-style movement: 7 8 9 / 4 5 6 / 1 2 3—5 waits a turn.
• Three emergency teleports per game. 99 resigns.
• 10 gives a 4×4 long-range-scan summary, collapsing the board into regional robot counts so you can plan routes.
• Collide a robot with another robot or with wreckage, and the tile becomes a * wreck. Touch a robot or a wreck yourself, and you lose.

COR24 BASIC is integer-only and has no clock, so the PRNG seed comes from whatever the variable R holds when you start the game. First run, R=0 → deterministic default seed 5237. Subsequent runs pick up the previous game’s residual R, which in practice gives you a different board each time. Pure, old-school deterministic pseudo-randomness. No time(), no /dev/urandom, just whatever integer happens to be sitting in R.

My version runs as robot-chase.bas.

Why COR24 BASIC?

All three games run on COR24 BASIC v1, which is deliberately time-sharing-era BASIC, not a modern dialect. The design target is the experience of UNIVAC 1100-series terminal BASIC: line numbers, integer arithmetic, single-letter variables, GOSUB/RETURN, GOTO, interactive LIST and RUN. No floats, no strings beyond CHR$(n) inside PRINT, no structured programming. Just enough to type a program into a terminal and watch it go.

The implementation is a four-layer stack:

The interpreter is a Pascal program compiled to p-code by p24p, assembled by pa24r into .p24 bytecode, and run on pv24t (the p-code VM). The p-code machine handles arithmetic, stacks, calls, and memory; the BASIC runtime on top of it handles line-numbered statements and interactive editing.

This matters for the games because integer-only BASIC on a 24-bit word is a real constraint. No floating-point Klingon positioning, no shortcut RNGs, no lazy string parsing. You write the game like you’re writing it in 1975—arrays of integers, careful arithmetic, explicit line numbers, GOSUB instead of functions—and the emulator gives it back to you pixel-true in a browser tab.

Try the Demos

sw-embed.github.io/web-sw-cor24-basic runs the entire stack in WebAssembly. Pick a program from the examples list, click RUN, and the integer-only BASIC interpreter—running on a Pascal-compiled p-code VM—plays the game in your browser:

All three are line-numbered BASIC source you can inspect, edit, re-run, and (if you want) port to your own time-sharing-era BASIC. The listings are MIT-licensed in sw-cor24-basic/examples.

Three eras, one interpreter, one browser tab. The bell is silent now, but the galaxy still needs defending.

TBT: what we built with, what we still build from.

All Together Now: Multi-Agent Coordination Demo

All Together Now (ATN) is a program manager that orchestrates multiple AI agent sessions running in isolated PTY environments. The new milestone is a demo that shows Claude Code as coordinator delegating tasks to multiple opencode/GLM-5 worker agents, with the agents collaborating through mailboxes and a shared wiki.

The Web UI (Yew/WASM) now presents this as a multi-panel layout:

• Agent terminal panels: Each agent’s TUI runs in its own panel, with live PTY streaming so you see exactly what the agent sees
• Tabbed views: Switch between agent-graphs (who’s talking to whom), wiki pages (shared durable state), agentrail Sagas per agent (workflow history), and mailbox events (messages flowing to and from the coordinator)

The coordination model separates two planes: a terminal I/O plane (raw PTY bytes, keystroke forwarding) and an orchestration plane (structured JSON events for feature requests, completion notices, and status updates). The coordinator doesn’t type into worker terminals—it sends structured messages through mailboxes. Workers read their mailbox, do their work, and post results back. The wiki provides durable shared state: goals, decisions, and context that any agent can read without asking.

This matters because the alternative—agents talking through unstructured terminal paste—is fragile and loses context. Mailboxes give you a clean event log. The wiki gives you shared memory that survives agent restarts. Agentrail sagas give you per-agent workflow audit trails.

Fuzzit: Testing Tools with Extreme Inputs

Fuzzit is an LLM-guided fuzz testing tool built to discover crashes, hangs, panics, and unexpected behavior in CLIs, compilers, interpreters, REPLs, and APIs. The core idea: a tool that tests other tools by throwing extreme and random inputs at them to validate error handling.

Fuzzit runs four-layer fuzzing campaigns with budget allocation across:

Each finding gets deterministically classified: panic, hang (wall-time timeout), segfault, unexpected exit code, or stderr anomaly. Interesting findings are automatically promoted to Rust regression tests, so once Fuzzit finds a bug, the fix stays tested forever.

No cloud dependencies—Fuzzit uses local Ollama for LLM-guided seeds, making it practical for testing proprietary tools and compilers that can’t be sent to external services. The nine-crate workspace (fz-core, fz-manifest, fz-corpus, fz-exec, fz-classify, fz-mutate, fz-llm, fz-artifacts, fz-cli) keeps concerns separated and testable.

The immediate use case: Fuzzit is already testing the COR24 compiler toolchain (tc24r, PL/SW, Pascal) to find codegen bugs that downstream languages would otherwise discover the hard way.

Vendoring: Parallel Development Without the Pain

The COR24 compiler chain has a dependency problem. PL/SW is written in C and compiled by tc24r (the C cross-compiler). SNOBOL4 is written in PL/SW. A new Fortran compiler will be written in SNOBOL4. Each layer depends on the one below it, and changes at any level can break everything above.

Vendoring solves this by pinning stable snapshots:

• PL/SW vendors tc24r: The PL/SW repo includes a known-good version of the C compiler. I can add features or fix bugs in tc24r’s main branch without breaking PL/SW mid-development. When a tc24r improvement is ready and tested, PL/SW explicitly updates its vendored copy.
• SNOBOL4 vendors PL/SW: Same pattern one level up. SNOBOL4 works against a stable PL/SW compiler. PL/SW macro system changes don’t destabilize the SNOBOL4 interpreter until deliberately promoted.
• Fortran vendors SNOBOL4: The new Fortran compiler (upcoming) will vendor SNOBOL4, giving it a stable implementation language while SNOBOL4 continues evolving.

This is the same idea behind Go’s vendor/ directory or Rust’s Cargo.lock—except applied to entire compiler toolchains in an embedded ecosystem. Each project controls when it absorbs upstream changes, so three developers (or three agent sessions) can work on three layers simultaneously without coordination overhead.

The alternative was what we had before: fix a C compiler bug, rebuild PL/SW, discover the fix exposed a PL/SW assumption, fix that, rebuild SNOBOL4, discover that exposed a SNOBOL4 assumption. Vendoring breaks the cascade. Fix, test, promote when ready.

Emacs Graphics: PaperBanana-Style Visuals in Emacs

Graphical Experiments is a new project exploring what happens when you bring PaperBanana-styled graphics into Emacs—SVG menu cards, inline charts, animated headers, and slide presentations, all rendered in native Emacs buffers.

The project is a kit of six Elisp packages:

The immediate goal is a visual toolkit for Emacs that feels like PaperBanana’s aesthetic—warm card layouts, clean data visualizations, and interactive menus—without leaving the editor. The longer-term direction includes clickable menu actions, layout helpers for arrows and swimlanes, Org integration for slides rendered from headings, and Rust-backed SVG layout for more complex graph visualizations.

Everything is built on Emacs 29+’s native SVG support (svg.el), keeping the code small and hackable. No external rendering dependencies—if your Emacs build supports SVG images, the demos work.

Repos and Live Demos

What’s Next

All Together Now: Live multi-agent demo with Claude Code coordinating opencode/GLM-5 workers on a real task—likely a collaborative code review or multi-repo refactor. The Web UI will stream all panels simultaneously.

Fuzzit: Expanding target coverage beyond compilers—next up are the COR24 embedded tools (monitor, shell, editor) and the agentrail-rs CLI. Campaign comparison reports to track regression across tool versions.

Emacs Graphics: Clickable menu actions on the SVG cards, Org-mode integration so presentation slides render from headings, and exploring Rust-backed SVG layout helpers for more complex graph and swimlane diagrams.

Vendoring: Establishing the Fortran-vendors-SNOBOL4 relationship as the Fortran compiler scaffolding begins. Documenting the vendoring protocol so agent sessions can update pinned versions without manual intervention.

Parallel work needs parallel infrastructure. Follow for more Sharpen the Saw updates.

Saga Archiving in agentrail-rs

Agentrail-rs tracks AI agent workflows as append-only saga records. Until now, one project meant one saga directory. That breaks down when a project has multiple concurrent workstreams—say, a language project where one saga covers the parser, another the runtime, and a third the test harness.

Saga archiving adds the ability to close out a completed saga and start a new one without losing history. Archived sagas move to a timestamped subdirectory, keeping the active saga directory clean while preserving the full trajectory for later analysis or ICRL replay. MLPL is the first project using saga archiving—each phase of the language (lexer, parser, interpreter, compiler) gets its own saga, archived when complete.

Not every project needs multiple sagas. The C compiler (tc24r) uses a single ever-growing saga that accumulates GitHub issues as they arrive from downstream projects like APL and PL/SW. When an APL feature hits a codegen gap, the issue lands in tc24r’s saga and stays there until fixed. One saga, one backlog—simple and appropriate for a project driven by external bug reports rather than internal phases.

MLPL: An APL2/J/BQN-Inspired ML Language

MLPL is a new Rust-based language inspired by APL2, J, BQN, and K, purpose-built for machine learning workflows. Unlike the integer APL on COR24—which is a minimal subset running on embedded hardware—MLPL runs on Linux and Mac with full floating-point support, first-class tensors, visual debugging, and a contract-first compartmentalized architecture.

The language is being built in Rust with a phased approach: parser and AST first, then a tree-walking interpreter, then compilation. The two APL projects inform each other: operator semantics and reduction patterns tested in COR24’s constrained integer environment validate core ideas, while MLPL extends them into floating-point territory and higher-rank tensor operations that embedded hardware can’t touch. MLPL is also the proving ground for agentrail’s new saga archiving—each language phase gets its own saga with clean boundaries.

PL/SW: Macros for a PL/I-Inspired Systems Language

PL/SW is a systems programming language inspired by PL/I, targeting COR24 today with an eye toward future FPGA soft CPUs. It compiles to human-readable COR24 assembler, which means you can inspect every instruction the compiler emits.

This week’s milestone: compile-time macro metaprogramming. PL/SW macros expand at compile time and generate COR24 assembly directly, enabling:

• Hardware abstraction: %MMIO_WRITE(addr, val) expands to the correct load/store sequence
• Inline patterns: Loop unrolling and register allocation hints without runtime cost
• BASED record templates: Structured memory access patterns that the macro system can verify at compile time

The macro system is the bridge between PL/SW-as-a-language and PL/SW-as-a-systems-tool. Without it, every hardware interaction required inline assembly. With it, the language can express hardware patterns in its own syntax. The COR24 demo hub hosts the emulator where PL/SW programs run.

Fixing the C Compiler to Unblock APL

The COR24 APL interpreter is written in C and compiled by tc24r (a chibicc-inspired C compiler targeting COR24’s 24-bit RISC ISA). APL’s array operations hit several compiler gaps:

• Missing features: Certain C constructs that APL’s runtime relied on weren’t yet implemented in tc24r
• Code generation bugs: Edge cases in pointer arithmetic and array indexing produced incorrect COR24 assembly

Each fix in tc24r immediately unblocked APL features that were waiting on correct codegen. The APL REPL now handles more complex array expressions thanks to these fixes.

Extending Pascal to Unblock BASIC

A similar dependency chain on the Pascal side. The COR24 BASIC interpreter runs on a Pascal p-code VM: Pascal source compiles to p-code assembler (pa24r), links via pl24r, and executes on the COR24 virtual machine. BASIC features that need new p-code instructions require Pascal compiler work first.

The Pascal compiler extensions this round added capabilities that BASIC’s string handling and control flow were blocked on. Like the C/APL chain, every Pascal fix cascades into BASIC functionality.

Embedded Tools: Monitor, Shell, and Editor

The COR24 ecosystem also gained progress on three infrastructure tools that make the platform usable as more than a compiler target.

Monitor (sw-cor24-monitor) is the low-level system monitor—the first thing that runs on COR24 hardware. It provides memory inspection, register dumps, and direct machine-code entry. Think of it as the boot ROM’s interactive console.

Script (sw-cor24-script) is a shell and scripting environment for COR24. It gives the platform a command-line interface for running programs, piping output, and automating tasks—the glue layer between the monitor and the language tools above it.

Yocto-Ed (sw-cor24-yocto-ed) is an Emacs-inspired line editor for COR24. On embedded hardware without a full terminal, a line editor is the practical way to edit source files and configuration. Yocto-Ed borrows Emacs keybindings and concepts (kill ring, incremental search) scaled down to fit in COR24’s memory constraints.

All three are works in progress with live demos planned.

Repos and Live Demos

What’s Next

Agentrail-rs: Multi-saga coordination—archived sagas feeding context into new ones, so an agent starting a fresh workstream can learn from completed ones.

MLPL: Parser completion and first interpreter pass. The APL operator semantics validated on COR24 hardware will inform which primitives make it into MLPL’s core.

PL/SW: Macro library for COR24 peripheral access patterns, targeting the MakerLisp hardware and eventually FPGA soft CPUs.

COR24 compilers: Continuing to close gaps in tc24r and the Pascal toolchain as APL and BASIC push further into their respective feature sets.

Sharpen the tools, shorten the chains. Follow for more Sharpen the Saw updates.

The Landing Page

The COR24 Software Tools page is a Yew/WebAssembly single-page application that ties together everything I’ve built for the COR24 24-bit RISC processor. All nineteen tools target the COR24 ISA—assemblers, compilers, interpreters, and system software, all generating or executing COR24 machine code. They’re organized into five groups: foundation tools, cross-compilers, the p-code system, native languages, and system software. Each group has interactive browser demos, documentation, and links to source.

Two weeks ago, most of these existed as scattered repos. Now they have a home, and every one of them is a bucket list item I can point to and say: done, or close to it.

Bucket List Items: Checked Off

Here’s what’s actually built and working, mapped back to the list from Part 1.

Write a Lisp

Tiny Macro Lisp — a Lisp interpreter written in C, targeting COR24. Lexical scoping, defmacro, closures, and a mark-and-sweep garbage collector. It runs in the browser as a live REPL. This was two bucket list items in one: write a Lisp and implement a garbage collector.

I’ve wanted to write a Lisp since I first read Structure and Interpretation of Computer Programs decades ago. The garbage collector was the part I was most nervous about. Turns out, once you have a clear mark phase and a clear sweep phase, it’s not mysterious—it’s just graph traversal with consequences.

Implement a Garbage Collector

See above. Mark-and-sweep, integrated into the Lisp runtime. Every cons cell, every closure, every environment frame is a heap object that gets traced. When the free list runs low, the collector walks the root set and reclaims everything unreachable. Simple, correct, and satisfying to watch in the debugger.

Implement a P-Code VM

P-code VM, Assembler & Linker — the VM is written in COR24 assembly (running on the emulator), with a Rust-based assembler and linker for the toolchain. Plus a Pascal compiler (p24p) that targets the p-code instruction set, and a P-code AOT compiler (pc-aotc) that translates p-code bytecode to native COR24 assembly.

This is straight out of the 1970s UCSD Pascal playbook. A stack-based virtual machine with its own instruction set, a compiler that targets it, and an ahead-of-time compiler that eliminates the interpretation overhead. Three layers of abstraction, all visible and inspectable in the browser.

Design a Systems Programming Language (PL/SW)

PL/SW — inspired by PL/I, targeting COR24. A compiled systems language with structured control flow, typed variables, and direct hardware access. It has its own IDE in the browser.

PL/I was the language IBM designed to replace everything—FORTRAN, COBOL, assembly. It was too ambitious, too complex, and too slow. But the idea of a language that spans systems programming and application programming has always appealed to me. PL/SW is my take on what PL/I might have been if it had been designed for a small machine instead of a mainframe.

Design a Scripting Language (SWS)

SWS — a Tcl-like scripting language for shell and editor automation on COR24. Where PL/SW is for building the system, SWS is for gluing it together. Command substitution, string manipulation, interactive use.

Every system needs a scripting layer. Something you can type at a prompt, something that can automate the editor, something that doesn’t require a compile step. SWS fills that role.

Implement a Monitor

Resident Monitor — boots at address 0, provides program invocation, I/O services, and a command interface. Written in COR24 assembly with some C components. This is the closest thing the COR24 has to an operating system: it loads programs, manages memory regions, and provides system calls.

Implement an Editor

yocto-ed — a minimal modal text editor with a gap buffer implementation. Written in C, compiled with the tc24r cross-compiler. This one is practical: I needed an editor to dogfood the C compiler, so I wrote one. Gap buffers are one of those data structures you hear about but rarely implement yourself.

Write a Compiler (Several, Actually)

• Tiny C Cross-Compiler (tc24r) — compiles a subset of C to COR24 assembly, written in Rust
• Pascal Compiler (p24p) — compiles Pascal to p-code, written in C
• Fortran Compiler — translates Fortran to COR24 assembly, written in C
• P-code AOT Compiler (pc-aotc) — translates p-code bytecode to native COR24 assembly
• Native Assembler (as24) — runs on the COR24 itself, part of the self-hosting toolchain

Five compilers/translators. Each one taught me something different about parsing, code generation, register allocation, and the gap between source language semantics and machine capabilities.

Implement an Interpreter

Beyond the Lisp interpreter, there’s also:

• Forth IDE — a direct-threaded code Forth with dictionary browsing and stack inspection
• APL Interpreter (apl-sw) — integer-only APL with rank-2 arrays
• BASIC Interpreter — classic BASIC with line numbers, GOTO/GOSUB, string variables

Four interpreters across four very different language paradigms: functional (Lisp), concatenative (Forth), array-oriented (APL), and imperative (BASIC).

Still on the List

A few items from Part 1 aren’t checked off yet:

• Debugger — a source-level debugger is planned but not yet implemented
• Shell — the monitor handles basic command dispatch, but a proper shell with pipes and redirection is future work
• Linker — the p-code linker exists, but a general-purpose native linker is still to come

The Vibe-Coding Part

All of this was built with AI assistance via agentrail-rs. The pattern: I describe what I want at an architectural level—“implement a mark-and-sweep garbage collector for the Lisp runtime”—and the AI writes the implementation. I review, test, redirect, and iterate. The landing page itself is a Yew SPA compiled to WebAssembly with Trunk, using the Catppuccin Mocha theme.

Two weeks. Nineteen tools. One person, operating as architect and project manager rather than line-by-line coder.

This is what retirement plus AI looks like. The bucket list is getting shorter.

Previous: Bucket List (1/?): Things I’ve Always Wanted to Build — the full list.

Emacs Meets the CLI: pjmai-rs

pjmai-rs is a project manager that maintains a stack-based navigation history, groups, and per-project metadata. It works well from the terminal, but Emacs shell-mode has a blind spot: when the CLI changes directories via exit-code signaling, Emacs doesn’t update default-directory. File completion breaks. Dired opens the wrong place.

The new pjmai.el package (376 lines) solves this by calling the binary directly from Elisp and managing per-project shell buffers where default-directory is correct from the start.

What It Does

Everything lives under the C-c p prefix:

Each project gets a dedicated shell buffer (*pjmai:projectname*) with the correct working directory set before the shell spawns. Tab completion just works. The shell function is pluggable—#'shell by default, but #'vterm or #'eshell are configurable.

25 ERT tests cover the CLI interface, JSON parsing, project completion, shell buffer management, and keymap structure.

Emacs Meets the CLI: reg-rs

reg-rs is a regression testing tool that captures command output and diffs against baselines. Like pjmai-rs, it had great terminal ergonomics but required context-switching away from Emacs.

my-reg-rs.el (208 lines) puts regression testing under C-c r:

Output goes to compilation-mode buffers, so next-error navigation works naturally. The package auto-detects the project root by checking for work/reg-rs/, .rgt/.tdb files, or falling back to project.el.

All Together Now: A Multi-Agent Program Manager

The bigger project this week. I’ve been running multiple Claude Code instances across repos and the coordination overhead was becoming the bottleneck—switching tabs, manually checking wikis, copying context between agents. All Together Now (ATN) is a Program Manager that owns the agent terminals and provides a unified control plane.

The Architecture

ATN runs as an Axum HTTP server that spawns N agents via portable-pty, streams their terminal output through SSE to a browser dashboard, and maintains a shared wiki for coordination state.

Four Phases in One Session

29 tests pass across the workspace. Zero clippy warnings.

The Six Crates

Why PTY Ownership Matters

The key insight: if the Program Manager owns the pseudo-terminals, it can:

1. Stream output to a web dashboard without agents knowing
2. Inject commands into agent sessions (serialized, no interleaving)
3. Detect state by parsing output (prompt markers, idle timeouts, question detection)
4. Log transcripts for debugging and replay

The serialized writer queue per agent prevents input corruption when multiple sources (human, coordinator, macros) write to the same terminal.

Wiki as Coordination Layer

ATN seeds five coordination pages on startup:

The wiki uses ETag-based Compare-and-Swap from the wiki-rs project, so concurrent agent writes get conflict detection instead of silent data loss.

What’s Next

ATN Phase 5: Message routing—agents write JSON to an outbox, the PGM routes push events to the correct target agent or escalates to human review.

Emacs packages: Phase 2 additions—transient menus for discoverability, completion annotations showing project paths and languages.

Emacs as ATN frontend: The pjmai-rs and reg-rs Emacs packages prove the pattern—call a Rust binary from Elisp, parse structured output, manage buffers. The same approach will give Emacs users a native ATN interface: agent status, wiki edits, and command injection without leaving the editor.

Tying it together: ATN + agentrail-rs integration, where each agent’s workflow progress is visible in the dashboard (and eventually in Emacs) and skills/experiences flow between sessions.

Better tools, better integration. Follow for more Sharpen the Saw updates.

Resource	Link
Live Demo	wiki-rs (3 client-side wikis)
Source	GitHub
Video	wiki-rs: Six Wikis, One Engine
Agent Wiki	Sample synced page
Comments	Discord

The Throwback

I was a reader of Ward Cunningham’s original WikiWikiWeb in the late 1990s. The concept was radical at the time: a website where any visitor could edit any page, with no approval process, no gatekeeping. Pages linked to each other with CamelCase words. If a page didn’t exist, the link showed up differently—click it, and you created it. The entire system ran on flat files.

In the early 2000s at Sun Microsystems, I started installing wikis for my teams. The first was TiKi, a Ruby-based wiki—CGI scripts, flat-file storage, pre-Rails era. It was fragile but functional. Later I moved to VQWiki, a Java servlet-based wiki that could deploy as a WAR file and supported both file and database storage. VQWiki was reliable enough for engineering teams to depend on.

Along the way I used TiddlyWiki for personal projects—an entire wiki in a single HTML file, no server required. And these days I use GitHub Wikis for public projects, which are just git-backed markdown repositories.

Each of these represents a different answer to the same question: where do the pages live?

The Storage Question

Every wiki engine has to answer this:

The storage architecture determines everything about a wiki: how it scales, how it versions, how it deploys, whether it needs a server, and how portable the data is.

wiki-rs: Six Approaches in Rust

I wanted to build all of these approaches in one codebase to see how they compare. wiki-rs implements six wiki variants, all sharing the same UI and wiki engine, differing only in storage:

The three client-side wikis run entirely in the browser via WebAssembly—no server, no installation. The three server wikis use Axum and require a local backend.

Shared Engine, Pluggable Storage

The architecture uses two storage traits:

• WikiStorage (sync) — for WASM frontends where async isn’t available
• AsyncWikiStorage (async) — for server backends

Each wiki variant is a thin wrapper (~30 lines) that implements the appropriate trait and calls the shared render_wiki() entry point. The wiki engine—parsing, rendering, link resolution, editing—is identical across all six.

The full codebase is 11 crates in a Cargo workspace, totaling ~2,600 lines of Rust.

Wiki Engine Features

The engine handles the essentials:

• Wiki links: [[PageName]] and [[PageName|display text]]
• Red links: nonexistent pages show as red; clicking creates the page
• Markdown: headings, bold, italic, code blocks, lists (via pulldown-cmark)
• Page aging: five visual tiers (Fresh, Recent, Stale, Old, Ancient) based on when a page was last edited—complete with yellowing, parchment gradients, and folded-corner effects
• Sub-wiki theming: five color themes detected by page title prefix (e.g., Tech/Rust gets the Ocean theme)
• XSS protection: raw HTML filtered out; wiki links inside backticks aren’t expanded

Import: VQWiki and TiddlyWiki

Since I have old wiki content in both VQWiki and TiddlyWiki formats, the project includes markup converters for both:

• VQWiki importer: converts VQWiki’s custom markup (!!! headings, '''bold''', [link|url]) to standard wiki markdown
• TiddlyWiki importer: extracts tiddlers from TiddlyWiki HTML files and converts their markup

Both converters have test suites validating the markup transformations.

What I Learned

Building six variants of the same wiki clarified the trade-offs:

Ephemeral is great for demos and testing. No persistence means no state bugs, but close the tab and everything’s gone.

Browser localStorage is surprisingly useful for personal wikis. No server, data persists across sessions, and the 5-10 MB limit is plenty for text. The limitation is portability—the data lives in one browser on one machine.

Export/Import solves portability. Download the wiki as JSON, email it, upload it elsewhere. But there’s no real-time versioning.

Server File is the closest to the original WikiWikiWeb. Flat .md files that you can read, grep, and back up with any tool. Simple and transparent, but no built-in versioning.

Server SQLite adds transactions, queries, and atomic operations. The trade-off is opacity—your wiki is inside a database file, not human-readable files.

Server Git is the most powerful. Every edit is a git commit with full history, diff, blame, and branch support. But it’s also the most complex and has the highest overhead per edit.

From Throwback to AI Coordination

A pattern I follow with these projects: think of a cool technology I used in the past, figure out how to recreate it in some demonstrable way, and think about how it could benefit from AI features—or how an AI agent could benefit from a modern tool based on the technology.

While working on an ambitious multi-repo project with multiple AI agents, I needed to act as coordinator between agents to implement a major refactoring. Each agent worked in its own repo, but they had shared dependencies, sequencing constraints, and status updates that needed to flow between them. I was the bottleneck—manually relaying context from one agent session to another.

I wondered if there was a way to delegate this coordination to an AI agent. And then I realized: my server-based wikis were already designed to share structured information. A wiki could serve as the shared state layer—goals, dependencies, requests, status, context—all on editable pages that any agent could read and update.

The problem: multiple agents editing the same wiki pages simultaneously will corrupt each other’s work. So I added a Compare-and-Swap (CAS) API to the wiki server. Each edit includes the page’s current version hash. If the page changed since the agent last read it, the write is rejected and the agent must re-read, merge, and retry. This gives you serialized concurrent edits without locking—the same pattern databases use for optimistic concurrency.

Then I needed a way to monitor and document what the agents were doing. So I added a tool to export the CAS wiki as a snapshot to a GitHub Wiki. Now the coordination state is visible, versioned, and browsable on GitHub—a living record of how the agents collaborated.

During early testing, one agent overwrote another agent’s request on a shared page—a classic lost-update problem. The affected agent eventually noticed (its request had vanished), but the damage was done. That’s exactly what CAS prevents at the API level. But it also showed that structural serialization isn’t enough—agents can still make semantic conflicts even when their writes don’t collide. So I asked the wiki-rs agent to add a feature to help serialize semantic changes too, ensuring agents merge intent rather than just bytes.

This is where throwback meets frontier: a thirty-year-old concept (the wiki), rebuilt in Rust, extended with concurrency primitives, and put to work as infrastructure for multi-agent AI coordination.

Quality

The project was built with a TDD red/green/refactor process:

• 50 integration tests across unit, API, and Playwright browser tests
• Zero clippy warnings
• 69/69 on the sw-checklist quality gates

The wiki is thirty years old and still the simplest way to organize knowledge. What’s on yours?

Fourth ML Frontier episode. In 2022, Chain of Thought changed how we think about AI reasoning. By 2026, the question has shifted from “how to make CoT better” to “is it real reasoning at all?”

Resource	Link
Papers	10 papers (2024–2026)
Video	ML Frontier 4: Is CoT Real?
Comments	Discord

What Chain of Thought Promised

Wei et al. (2022) showed that prompting language models to “think step by step” dramatically improved performance on math, logic, and multi-step reasoning tasks. The idea was simple: instead of jumping straight to an answer, generate intermediate reasoning steps. The model explains its work, and the answer improves.

This became the foundation for everything from coding assistants to scientific reasoning pipelines. But a deeper question was always lurking: are those reasoning steps real?

The Faithfulness Problem

Recent research shows models can produce plausible-looking reasoning steps that don’t reflect their actual internal computation. The chain of thought looks like reasoning—it has logical connectives, intermediate conclusions, references to the problem—but the model may have arrived at the answer through entirely different internal pathways.

This is the faithfulness gap. A model’s visible reasoning trace can be:

• Post-hoc rationalization — constructing a justification after already deciding the answer
• Biased by surface features — following patterns in the prompt rather than the problem structure
• Unfaithful to internal state — the actual computation happening in the model’s hidden layers doesn’t match the text it generates

“Reasoning Models Don’t Always Say What They Think” (arXiv 2505.05410) shows that even models specifically trained to reason via CoT produce traces that are often unfaithful to their actual decision process. A March 2026 follow-up, “Reasoning Models Struggle to Control their Chains of Thought” (arXiv 2603.05706), goes further: models can’t reliably steer or suppress their reasoning traces even when instructed to. And “Diagnosing Pathological Chain-of-Thought in Reasoning Models” (arXiv 2602.13904) catalogs specific failure modes where CoT reasoning becomes actively pathological.

The implication is uncomfortable: when a model shows you its “thinking,” you can’t assume it’s showing you how it actually thinks.

CoT Is Task-Dependent

The research also reveals that Chain of Thought isn’t universally beneficial. It helps with:

• Math and arithmetic — multi-step calculations benefit from intermediate results
• Multi-hop logic — problems requiring sequential deductions
• Complex planning — tasks with dependencies between steps

But CoT can actually hurt performance on:

• Pattern recognition — tasks where the answer is immediate/intuitive
• Simple classification — forcing step-by-step reasoning adds noise
• Tasks with misleading structure — when the “obvious” reasoning path leads away from the correct answer

A 2024 meta-analysis, “To CoT or not to CoT?” (arXiv 2409.12183), confirms this systematically: CoT provides negligible or negative benefit on many task types including commonsense reasoning and factual retrieval. The blanket advice of “always use Chain of Thought” is wrong. The right approach depends on the task.

Adaptive Reasoning: Knowing When to Think

The field is moving toward conditional reasoning—models that decide when to think step by step and when to skip it. Wang and Zhou (2024) showed that chain-of-thought reasoning can emerge from models without explicit prompting, suggesting the capability is latent rather than purely prompt-dependent.

This points toward a future where models dynamically allocate reasoning effort:

• Simple questions get immediate answers
• Complex questions trigger step-by-step decomposition
• Ambiguous questions get clarifying sub-questions

“s1: Simple Test-Time Scaling” (arXiv 2501.19393) demonstrates this with budget-forcing—a simple mechanism to control how much reasoning a model performs at test time, truncating or extending thinking adaptively. “Outcome-Based RL Provably Leads Transformers to Reason” (arXiv 2601.15158) shows that RL training can teach transformers when reasoning is needed, not just how to reason. The model itself becomes the judge of how much thinking a problem requires.

Latent Reasoning: Thinking Without Showing

Some of the most interesting current work explores latent reasoning—models that reason internally without generating visible steps. Instead of producing a text trace, the model uses its internal representations to perform multi-step computation within the forward pass.

This connects to research on:

• Implicit chain of thought — reasoning encoded in hidden states rather than output tokens
• Pause tokens — giving models extra computation steps without requiring text output
• Internal scratchpads — dedicated hidden-state computation that doesn’t appear in the response

COCONUT (arXiv 2412.06769) demonstrates this concretely: LLMs reason using continuous hidden states as “thoughts” instead of generating discrete tokens. Two 2026 papers push further: “Latent Chain-of-Thought as Planning” (arXiv 2601.21358) decouples reasoning from verbalization entirely, and “Latent Reasoning with Supervised Thinking States” (arXiv 2602.08332) trains models to reason through supervised internal states.

If latent reasoning works at scale, it could offer the accuracy benefits of CoT without the token cost or the faithfulness problem—because there’s no visible trace to be unfaithful.

CoT as Part of an Ecosystem

Chain of Thought is no longer a standalone technique. It’s one component in a broader ecosystem:

This makes CoT the bridge concept between language models as predictors (next token), as reasoners (multi-step logic), and as agents (goal-directed behavior). Understanding where CoT works and where it breaks is essential for building systems that combine all three.

The Open Questions

Papers

Is the reasoning real, or just a good story? Follow for more ML Frontier episodes exploring research at the edge.

The Problem agentrail Solves

AI coding agents lose operational knowledge between sessions. An agent might figure out the right sequence of commands for a complex task—TTS generation, video compositing, file manipulation—then lose that knowledge when the session ends. Next time, it starts from scratch. Sometimes it succeeds. Sometimes it improvises and fails.

agentrail-rs gives agents structured handoffs, deterministic step execution, and in-context reinforcement learning so they succeed on first attempts instead of guessing.

What’s Working: Beyond the Walking Skeleton

Phase 0 through Phase 5 (partial) are implemented. The CLI has 8 commands that manage the full saga lifecycle:

agentrail init my-project      # Create a new saga
agentrail plan                  # Show the step sequence
agentrail next                  # Get instructions for the next step
agentrail begin step-name       # Mark a step as in-progress
agentrail complete step-name    # Mark a step as done
agentrail status                # Show saga state
agentrail history               # Show completed steps
agentrail abort                 # Cancel the saga

Everything persists to a .agentrail/ directory: TOML configs, JSON trajectories, JSONL session snapshots. The 24 integration tests all pass, and pre-commit quality gates enforce formatting, lints, and test coverage.

Two-Layer Architecture

The architecture separates the generic engine from domain-specific knowledge:

Layer 1 (this repo) — task-agnostic inference-time learning:

• Workflow state machine (sagas with typed steps)
• Dual memory following the XSkill pattern: skills (strategic workflow documents) and experiences (tactical per-run records)
• ICRL injection: retrieve successful experiences and inject them into agent prompts
• Distillation: analyze experience batches, generate and update skill documents

Layer 2 (separate repos, future) — domain-specific knowledge:

• Per-domain repos (e.g., agentrail-domain-media, agentrail-domain-rust)
• Skill documents, curated experience libraries, executor implementations, validators
• Optional knowledge graphs for reward signals

The separation means the engine never changes when you add a new domain. You just create a new Layer 2 repo with the right skill files and executors.

The XSkill Connection

The dual-memory pattern comes directly from the XSkill paper (arXiv 2603.12056). Their ablation analysis shows that removing either skills or experiences hurts performance—you need both.

In agentrail-rs:

When you run agentrail next, it retrieves relevant skills and past trajectories and includes them in the output. The agent sees both how to approach this kind of task (skill) and what actually worked last time (experience).

Research Foundations

The architecture maps to specific research:

The Sleepy Coder result was pivotal. I’d spent weeks trying to fine-tune a small model for my specific agent tasks. The fine-tuned model performed worse than the base model with good prompts. That’s what pushed me toward ICRL: don’t change the model’s weights, change what it sees in context.

Implementation Progress

Phase 1 added task_type to step configs, trajectory retrieval in agentrail next, and experience recording with --reward/--actions flags on complete. Phase 2a introduced the Skill type with TOML storage and injection into next output. Phase 2d added the distill command that analyzes experience batches to generate skill documents. Phase 3 brought the domain registry, executor trait, and validator trait. Phase 5 implemented the hybrid orchestrator loop where deterministic steps auto-advance and semantic work gets escalated to the agent.

What remains: Phase 2b/2c (enriched Experience type, experience retrieval by embedding), Phase 3 completion (first real domain repo), and Phase 4 (knowledge graph rewards).

What’s Next: Domain-Specific Layer 2

The engine (Layer 1) is functional. The next challenge is building real Layer 2 domain repos and proving the architecture works on actual projects. This week I’m testing it against three new projects:

1. A C compiler running in a browser — requires WebAssembly compilation skills
2. A Macro Lisp implemented in C — requires C development and language implementation skills
3. The Macro Lisp running inside a browser — combines all of the above with Web UI skills

This is a deliberate stress test. Each project demands different domain expertise: C, Rust, Lisp, and Web UI. If agentrail-rs can carry skills and experiences across these domains and help the agent succeed on first attempts, the architecture works. If not, I’ll learn where it breaks.

Crate Layout

The project is a Cargo workspace (edition 2024) with clean separation:

Papers

Better tools, better agents. Follow for more Sharpen the Saw updates.

Resource	Link
Live Demo	COR24 Assembly Emulator
Source	GitHub
Video	Browser-Based Assembly: COR24 RISC Emulator in Rust
MakerLisp	makerlisp.com (COR24 creators)
COR24 Soft CPU	FPGA Implementation
COR24 Dev Board	Hardware Kit
Comments	Discord

What is COR24?

COR24 (C-Oriented RISC 24-bit) is a soft CPU architecture designed by MakerLisp. The design priorities were simplicity, speed, and a good impedance match to C compilers on low-density FPGAs—no legacy requirements, no committee compromises. The “C-Oriented” in the name is literal: architectural decisions were informed by what a practical C compiler needs from this class of processor.

Origin Story

MakerLisp developed COR24 as a replacement for the eZ80, which was the best option they could find for their class of small embedded problems. During the pandemic-era chip shortage, mass-market microcontrollers became unavailable, so they designed their own CPU for FPGAs. The result: a 24-bit RISC architecture that runs at 101 MHz on inexpensive Lattice FPGAs—a simple, fast, and rational alternative built from the ground up with no legacy baggage.

The CPU is written in Verilog and released under the MIT license. It’s both a practical embedded solution for small computing problems and an excellent architecture for learning CPU fundamentals. You can build your own hardware implementation or use the browser emulator to explore the architecture.

Architecture Overview

COR24 keeps things simple. Three general-purpose registers, five special-purpose registers, one condition flag, and instructions that are 1, 2, or 4 bytes long.

Registers

Only r0, r1, and r2 are truly general-purpose. The named registers (fp, sp, z, iv, ir) have dedicated roles. The z register provides a constant zero accessible only in compare instructions (ceq r0, z, clu z, r0, cls r0, z)—it is not a general-purpose register and cannot be used in mov, ALU, or load/store instructions. The architecture uses a separate condition flag (C) set by compare instructions and tested by branch instructions.

Memory Model

• 24-bit address space (16 MB addressable)
• Byte-addressable with little-endian ordering
• Memory-mapped I/O at 0xFF0000 - 0xFFFFFF
• Stack grows downward (standard convention)

Instruction Categories

Instructions are 1, 2, or 4 bytes (never 3). Register-only operations are compact (1 byte). Loading 8-bit constants (sign- or zero-extended) uses 2-byte instructions (lc, lcu). Loading full 24-bit values—whether addresses or integers that don’t fit in 8 bits—requires 4-byte instructions (la). Note: data words are 3 bytes (24-bit), but instruction encoding never uses 3 bytes.

The Dev Board

The COR24-TB dev board exposes the CPU’s I/O in a hands-on layout. The S2 button is a user switch—press it and the CPU sees an input event your assembly code can poll or respond to. D2 is a user LED wired to a memory-mapped output address, so your code can toggle it directly with a store instruction. The board breaks out UART connectors for serial communication, with hardware support for an internal interrupt when data arrives—meaning your program doesn’t have to busy-wait on the serial port. Beyond these, the board has six additional GPIO pins intended for a four-wire SPI interface and a two-wire I2C bus. MakerLisp is actively developing bit-bang I2C support (temperature sensor reading is next), followed by an I2C real-time calendar clock, a 4-position 7-segment display via SPI, and SD card access via SPI. A Reset button and Power LED round out the essentials.

The emulator models the S2 button, D2 LED, and UART with interrupt support, so programs written for the browser run the same way on real hardware.

The Browser Emulator

cor24-rs brings COR24 to the web using Rust compiled to WebAssembly. No downloads, no setup—just open the page and start coding.

Features

• Three Tabs - Assembly, C, and Rust pipelines, all running on the same COR24 CPU
• Interactive Assembly Editor - Syntax highlighting, error messages, line numbers
• Step-by-Step Execution - Execute one instruction at a time with log-scale speed control
• Register & Memory Viewer - Watch CPU state change in real-time with highlighted changes
• Instruction Trace - Last 100 executed instructions visible in the web UI
• 11 Assembler Examples - Pre-loaded programs including Blink LED, Fibonacci, Countdown, Variables, and Assert
• 12 Rust Pipeline Demos - From simple add to UART echo with interrupts
• 2 C Pipeline Examples - Fibonacci and Sieve of Eratosthenes via MakerLisp’s CC24 compiler
• Coding Challenges - Test your assembly skills with suggested exercises
• ISA Reference - Complete instruction documentation inline with CPU state, interrupts, and memory map
• Interactive Tutorial - Comprehensive introduction covering registers, instructions, I/O, and idioms
• Self-Test Mode - ?selftest URL parameter runs all 15 examples automatically with pass/fail reporting
• Animated Tours - ?showme-asm, ?showme-c, ?showme-rust walk through each pipeline
• Realistic UART Timing - TX busy for 10 cycles per character; dropped characters when writing without polling

Example: Fibonacci

Here’s a recursive Fibonacci implementation in COR24 assembly:

_fib:
        push    fp              ; Save frame pointer
        push    r2              ; Save r2
        push    r1              ; Save return address
        mov     fp,sp           ; Set up frame
        add     sp,-3           ; Local variable space
        lw      r2,9(fp)        ; Load argument n

        lc      r0,2            ; Load constant 2
        cls     r2,r0           ; Compare n < 2
        brf     L17             ; Branch if false

        lc      r0,1            ; Return 1
        bra     L16             ; Jump to epilogue

L17:
        mov     r0,r2           ; r0 = n
        add     r0,-1           ; r0 = n - 1
        push    r0              ; Push argument
        la      r0,_fib         ; Load fib address
        jal     r1,(r0)         ; Call fib(n-1)
        add     sp,3            ; Clean up argument
        sw      r0,-3(fp)       ; Save result

        mov     r0,r2           ; r0 = n
        add     r0,-2           ; r0 = n - 2
        push    r0              ; Push argument
        la      r0,_fib         ; Load fib address
        jal     r1,(r0)         ; Call fib(n-2)
        add     sp,3            ; Clean up argument
        lw      r1,-3(fp)       ; Load fib(n-1)
        add     r0,r1           ; r0 = fib(n-1) + fib(n-2)

L16:
        mov     sp,fp           ; Restore stack
        pop     r1              ; Restore return address
        pop     r2              ; Restore r2
        pop     fp              ; Restore frame pointer
        jmp     (r1)            ; Return

This demonstrates the full calling convention: prologue/epilogue, argument passing via stack, and recursive calls.

Command Line Tools

Beyond the browser emulator, cor24-rs includes CLI tools for local development:

# Assemble and run in the debugger
cor24-dbg program.s

# Or assemble and run directly
cor24-run program.s

# With LED visualization
cor24-run program.s --leds

The CLI debugger (cor24-dbg) supports breakpoints, step execution, UART I/O, LED/button simulation, and instruction trace. The --uart-never-ready flag forces TX to never clear, useful for testing polling behavior.

Rust to COR24 Pipeline (Experimental)

The project includes experimental support for compiling Rust to COR24:

Rust (.rs) → WASM (.wasm) → COR24 Assembly (.s) → Binary
            ↑               ↑
         rustc          wasm2cor24
        (standard)       (this project)

Write embedded Rust with #![no_std], compile to WebAssembly, then translate to COR24 assembly. The wasm2cor24 translator handles the stack-based IR conversion.

This approach leverages Rust’s existing toolchain—no compiler modifications needed. The wasmparser crate handles WASM parsing, and COR24’s stack-oriented design maps reasonably well from WASM’s stack machine.

Why Learn Assembly?

Even if you never write production assembly, understanding it changes how you think about code:

1. Performance intuition - Know what your high-level code compiles to
2. Debugging - Read crash dumps and disassembly when things go wrong
3. Security - Understand buffer overflows, ROP chains, exploitation
4. Embedded systems - Some hardware requires low-level access
5. Appreciation - Respect the layers beneath your abstractions

COR24 is simple enough to fit in your head but realistic enough to represent real CPU design patterns. And unlike purely educational architectures, it’s also a practical platform for small embedded problems—the kind of work that used to require an eZ80 or similar microcontroller.

Implementation Details

The emulator core is written in Rust, compiled to WebAssembly via Trunk. Key components:

The decode ROM is particularly interesting—it’s extracted directly from the hardware Verilog implementation, ensuring the emulator matches the real CPU behavior exactly.

Try It Yourself

Live Demo: sw-embed.github.io/cor24-rs

The demo includes:

• Pre-loaded example programs
• Interactive tutorials
• Coding challenges with automated verification
• Complete ISA reference

Start with the “Hello World” example, then work through the challenges. By the time you complete them, you’ll understand registers, memory, stack operations, and function calls.

Key Takeaways

1. COR24 is a real CPU - Designed for FPGAs, runs at 101 MHz, MIT licensed, practical for embedded work
2. cor24-rs makes it accessible - Browser-based, no installation required
3. Assembly isn’t scary - With good tools, you can see every step
4. Rust + WASM works - The entire emulator compiles to a web application
5. Simple doesn’t mean toy - COR24’s design prioritizes C compiler compatibility and practical embedded I/O, not just teaching

Resources

• MakerLisp - COR24 creators
• COR24 Soft CPU - FPGA implementation details
• COR24 Dev Board - Hardware development board
• cor24-rs Demo - Live browser emulator
• cor24-rs Source - Full source code

Assembly language is the ground truth. Everything else is abstraction.

The Two Enablers

Retirement gave me the time. No more deadlines, no more sprints, no more meetings about meetings. Just curiosity and a compiler.

AI gave me reach. The AI writes the code. I give direction, goals, test criteria, architectural restrictions. I prioritize. I use AI to help me research what’s possible, what’s been done historically, how to approach things. I’m working at a higher level than coding—reprising the roles I held during my career: team lead, architect, product manager, engineering manager. I trust but verify the work of AI designers, planners, coders, testers, and technical writers.

Projects that would have required a team, or a semester, or a level of domain expertise I didn’t have—now one person can attempt them. Not by typing faster, but by operating at the right level of abstraction.

Together, retirement and AI unlocked the list.

The List (Abridged)

I’ve organized these loosely by category, but the real list is messier than this. Some items are decades old. Some I added last month. Some I’ve already done and blogged about. Some I’m actively working on. Many are still waiting.

Embedded and Hardware

Program microcontrollers in Rust (no_std). Not just blink-an-LED—real sensor networks, real communication protocols. I’ve been doing this with BMP280 pressure sensors and I2C multiplexers, building arrays of dozens of sensors for a patent proof-of-concept.

Learn to program FPGAs. I’ve always been fascinated by hardware description languages—the idea that you’re not writing instructions, you’re describing circuits. This connects directly to another item on the list…

Build a ternary computer. Base-3 computing. Three-valued logic instead of binary. This is a real project—I’m in planning mode, starting with emulation, with the goal of implementing it on an FPGA. Why? Because balanced ternary is mathematically elegant, and because “why not” is a valid engineering motivation when you’re retired.

Program Arduinos, Raspberry Pis, ESP32-C3s, ESP32-C6s, and various other 8-bit, 16-bit, and 32-bit microcontrollers. I want to understand the full spectrum, not just the popular ones.

Compilers and Languages

Write my own C compiler. Sort of. Take an existing small C compiler and modify it for a custom ISA, adding features along the way. I never got to take a compiler class in college, and I’ve regretted it ever since. Every time I’ve used a compiler—which is every day of my career—I’ve been using a tool I didn’t fully understand. Time to fix that.

Implement ToonTalk. A visual programming language I wrote about in the Throwback Thursday series. The original was built for teaching children to program through animated characters and spatial metaphors. I want to see if the concept can be modernized.

Emulate Everything

I’ve always been drawn to instruction set architectures. The idea that you can simulate an entire computer in software—every register, every memory access, every instruction decode cycle—is endlessly satisfying.

The collection so far includes the IBM 1130 (a 1960s minicomputer I have personal history with), the MakerLisp COR24 (a modern 24-bit RISC for FPGAs), and plans for the RCA 1802, TI-1000, IBM 360/370/390, and RISC-V I32. Each one teaches something different about computer architecture.

Machine Learning and AI

Fine-tune an open-weights LLM. Not use one—train one. Understand the full pipeline: dataset preparation, tokenizer choices, LoRA adapters, evaluation. I’ve written about small models and neural net internals, but I want the hands-on experience of taking a base model and shaping its behavior.

Creative and Media

Program Blender 3D to create physics-based animations. Not art—engineering visualizations. Simulating how things move, collide, flow.

Generate sound effects procedurally. No samples, no recordings—synthesize sounds from parameters. Explosions, rain, footsteps, all from math.

Generate music. I’ve already built midi-cli-rs and music-pipe-rs, Unix-pipeline tools for algorithmic composition. There’s more to explore here.

Practical Home Projects

These are the ones my family actually cares about:

• Cat tracker — know where the cats are without searching the house
• Senior monitoring — help a family member with memory issues stay safe, without being intrusive
• Spam call blocker — something smarter than a blocklist
• Turkey deterrent — they invade the property regularly and are remarkably persistent
• Wildfire detection — early warning for a fire-prone area
• Automated exterior sprinkler system — part wildfire defense, part garden automation

Each of these is a real project, not a hypothetical. Some are in progress. Some are in the planning stage. All of them combine embedded hardware, software, and problem-solving in ways that make them genuinely fun.

Why Blog About It?

Three reasons.

Accountability to myself. Writing about what I’m doing forces me to think clearly about it. If I can’t explain it, I don’t understand it well enough.

Sharing the approach. The combination of retirement + AI + decades of software experience creates an unusual vantage point. I’m not a student learning for the first time, and I’m not an expert in most of these domains. I’m an experienced engineer exploring unfamiliar territory with modern tools.

The list itself. Maybe other people have similar lists. Maybe seeing someone actually working through theirs is encouraging.

What’s Next

Future Bucket List posts will cover a few items at a time, mixing categories. I’ll share what I’ve learned, what surprised me, what’s harder or easier than expected, and where AI helped or didn’t. No particular order. No schedule. Just whatever I’m working on.

Everyone’s list is different. This is mine. What’s on yours?

You ship a fix. Tests pass. Three weeks later a customer reports that a flag you didn’t touch now produces different output. Nothing in your test suite catches it because your tests check behavior, not output. What you needed was a regression test—a snapshot of what the command actually produced, compared against what it produces now.

Resource	Link
Video	reg-rs: Snapshot Regression Testing
Repo	sw-cli-tools/reg-rs
Motivation	Why I Built This
References	Historical Context
Comments	Discord

What is reg-rs?

reg-rs (regress) is a CLI tool that captures the output of shell commands—stdout, stderr, and exit code—as “golden” baselines, then re-runs those commands and compares the results to detect regressions. Think of it as snapshot testing for any command-line tool.

Quick Start with Aliases

reg-rs ships with shell aliases that make the workflow fast. Source them once (or add to your .zshrc/.bashrc):

source /path/to/reg-rs/bin/source-rg.sh

Then the full create-run-check-update cycle looks like this:

# 1. Create the thing you're testing
echo 'echo "Hello, World!"' > greet.sh

# 2. Create a regression test — captures the output as the baseline
adrg greet 'bash greet.sh'

# 3. Run the test — compares current output against the saved baseline
rnrg greet
#   PASS

# 4. See the results
lsrg greet
#   PASS   greet   bash greet.sh

# 5. Now change greet.sh (simulate a code change)
echo 'echo "Hey there!"' > greet.sh

# 6. Run the test again
rnrg greet
#   FAIL

# 7. See what changed
shrg greet -vv
#   baseline: "Hello, World!"
#   latest:   "Hey there!"
#   diff:     - Hello, World!
#             + Hey there!

# 8. You decide this change is intentional — accept the new output
uprg greet

# 9. Run again — passes with the new baseline
rnrg greet
#   PASS

The aliases: adrg (add), rnrg (run), lsrg (list), shrg (show), uprg (update/rebase), rmrg (remove), rsrg (reset), strg (status server), hlrg (help). Tab completion is included.

Or use the full commands: reg-rs create, reg-rs run, reg-rs list, reg-rs show, reg-rs rebase, etc.

Text-Based Test Format (.rgt)

A recent major change: tests are now stored as plain text files instead of binary SQLite databases. Each test has up to three files:

An .rgt file looks like:

command = "git --version"
timeout = 10
exit_code = 0
desc = "Version string format check"
expects = "Prints version in semver format"

The .out file is just the golden output, plain text:

git version 2.44.0

This makes tests git-friendly—baselines show up in diffs, code reviews, and blame. The .tdb cache is gitignored; it only stores runtime results for reporting. If you have existing .tdb tests, reg-rs migrate (or mgrg) converts them to the new format.

Detecting a Regression

Here’s a concrete example of reg-rs catching a version change:

# Set up a baseline
echo 'version 1.0.0' > version.txt
adrg version_test 'cat version.txt'

# Run it again---passes, output matches
rnrg version_test
# PASS

# Simulate a change
echo 'version 2.0.0' > version.txt

# Run again---regression detected
rnrg version_test
# FAIL

# See exactly what changed
shrg version_test -vv
# stdout differences:
#   - version 1.0.0
#   + version 2.0.0

# Intentional change? Accept the new baseline
uprg version_test

Dogfooding: reg-rs Tests Itself

reg-rs uses itself to regression-test its own CLI. The test directory contains golden baselines for every subcommand’s help output. After any code change, rnrg checks that no help text, flag names, or usage strings changed accidentally. The demo scripts that exercise this workflow run automatically as part of cargo test.

Monitor: Web Dashboard

reg-rs status -p test
# or: strg test

This launches an Axum web server on port 4740 with a live dashboard. The landing page shows summary counts (pass/fail/pending) across all projects, updating in real time via Server-Sent Events (SSE)—no polling, no page refresh. The SSE stream sends JSON payloads and the client updates the DOM directly, so you see pass counts climb and pending counts drop as each test completes.

The detail view has collapsible sections for failures, passes, and pending tests. Failed tests show inline character-level diffs—expected baseline in green, actual output in yellow—so you can see exactly what changed and decide whether to investigate or rebase. A JSON API at /api/status is available for programmatic access.

The Throwback

In 2000, I was working at Forte Software in Oakland, California. Forte had a C/C++-based regression testing tool called regress. The concept was straightforward: run a command, save the output, run it again later, diff the results. Simple, but it caught real bugs that unit tests missed—the kind where the output format changed, or an error message got reworded, or a flag silently started behaving differently.

Sun Microsystems acquired Forte, and since Sun was focused on Java, I wrote jregress over the next year—a clean-room implementation, not a port. It was partly a learning exercise, partly practical: the Java development teams and QA needed a regression tool that lived in their ecosystem, and writing it in Java meant I could maintain it myself and add features as QA requested them. Oracle acquired Sun in 2010, and as far as I know, jregress is still being maintained and used there today. There may have been an attempt to open-source it, but I haven’t found it online.

The concept hasn’t changed in 25 years. What’s changed is the tooling around it: Rust gives you single-binary distribution, text-based .rgt files make tests git-friendly, clap gives you a polished CLI with shell aliases and tab completion, and Axum gives you a live monitoring dashboard with SSE. The next evolution is AI—using language models to generate test cases, explain regressions, and maintain baselines as code evolves.

Advanced Features

The basics—add, run, list/show—cover simple cases. Real CLI tools present harder challenges: non-deterministic output, interactive prompts, binary files, and slow test suites. reg-rs has features for all of these.

Taming Non-Deterministic Output

CLI output often contains timestamps, temp paths, PIDs, and version strings that change between runs. reg-rs provides two mechanisms to handle this.

--preprocess (-P): Pipe stdout/stderr through a shell command before diffing:

# Mask temp directory paths (macOS resolves /tmp to /private/var/...)
adrg my_test 'my_tool run' \
  -P "sed 's|/tmp/[^ ]*|<TMPDIR>|g; s|/private/var/[^ ]*|<TMPDIR>|g'"

--diff-mode (-M): Built-in normalization for common formats:

# JSON: sorts keys and pretty-prints before diffing
adrg api_test 'curl -s localhost:8080/status' -M json

# Lines-unordered: sorts lines before diffing
adrg completions 'mytool complete commands' -M lines-unordered

Command Timeouts

Interactive CLIs that prompt for input will hang indefinitely in non-interactive shells. The --timeout flag (in seconds) makes them fail fast:

adrg pjmai_help 'pjmai-rs --help' --timeout 10

Self-Documenting Tests

Tests can carry their own documentation, stored in the .rgt file:

adrg pjmai_help 'pjmai-rs --help' --timeout 10 \
  --desc "Verifies help text is stable" \
  --expects "Standard clap help output" \
  --flaky-note "None - deterministic"

These metadata fields appear in failure reports at -vv verbosity and are consumed by the analyze subcommand for AI-powered triage.

Parallel Execution

The --parallel flag runs all matching tests concurrently, one thread per test:

rnrg pjmai --parallel

Each test has its own independent files, so there are no concurrency conflicts.

Testing Binary Output

Not all CLI tools produce text. favicon generates PNG and ICO images—binary output where line diffs are meaningless. The subject study documents approaches including SHA-256 checksums, base64 encoding, and hybrid strategies for visual comparison.

AI Features

Several AI features are implemented (not just planned). All require ANTHROPIC_API_KEY.

AI-Powered Test Creation (--describe)

Describe what you want to test in natural language instead of writing the shell command:

reg-rs create -t status -D "show git status of current directory"
# AI generates: git status

Add --context (-C) to feed the AI existing help text for better command generation:

reg-rs create -t pjmai_list \
  -D "test the list subcommand with no projects" \
  -C "pjmai-rs --help"

AI Failure Analysis (analyze)

When tests fail, the analyze subcommand sends the original output, latest output, and diff to Claude for triage:

reg-rs analyze -p my_failing_test

It classifies failures as true regressions, flaky tests, environmental changes, or stale baselines—helping you decide whether to investigate or rebase.

Getting Started

Clone and build:

git clone https://github.com/sw-cli-tools/reg-rs.git
cd reg-rs
cargo build --release

Set up aliases:

source bin/source-rg.sh

Create your first test:

adrg hello 'echo hello world'
rnrg hello
lsrg hello

The best test is the one that catches the change nobody expected. Regression testing has been doing that for decades—now with better tools.

Third ML Frontier episode. What if scaling AI didn’t mean bigger models, but better structure? A line of research from Princeton proposes an alternative trajectory: Domain-Specific Superintelligence built on Knowledge Graphs.

Resource	Link
Papers	4 papers covered
Video	ML Frontier 3: Structure Beats Scale
Code	JHA Lab (GitHub)
Comments	Discord

The Premise: Structure Over Scale

The dominant AI trajectory is clear: make models bigger, train on more data, throw more compute at the problem. It works, but it’s expensive, opaque, and increasingly difficult to verify.

Princeton’s JHA Lab proposes a fundamentally different path. Instead of one giant general model, build smaller expert models grounded in structured knowledge—specifically, Knowledge Graphs. The result: Domain-Specific Superintelligence (DSS).

Knowledge Graphs as Training Engines

A Knowledge Graph (KG) is a structured representation of facts and relationships—nodes connected by labeled edges. In traditional AI pipelines, KGs serve as memory or lookup tables. The key insight here is that a KG can serve a much deeper role.

Step 1 — Supervised Fine-Tuning (SFT). Use the graph to generate reasoning tasks. Paths through the graph become structured training problems. The model learns to follow real domain relationships, not just pattern-match on surface text. This is grounded learning—every training example traces back to verified structure.

Step 2 — Reinforcement Learning with KG Rewards. This is the breakthrough. Every reasoning path in the graph becomes a verifiable reward signal. Valid multi-hop paths are rewarded; invalid reasoning is penalized. The graph itself is the reward model.

The Implicit Reward Model

Traditional RL for language models requires a separate reward model—often a black box trained on human preferences. The KG approach eliminates that dependency.

Because the graph encodes real relationships, the reward signal is transparent and verifiable. There’s no black-box scoring. You can trace exactly why a reasoning path was rewarded or penalized. This is what the authors call an implicit reward model: the structure of knowledge itself provides the training signal.

Zero-Shot Scaling Through Composition

Train on simple paths, generalize to complex multi-hop reasoning. This is compositional generalization—the model learns reasoning primitives from short KG paths, then composes them into longer chains at inference time without having seen those specific chains during training.

The result is zero-shot scaling: stronger reasoning without a larger model. Structure replaces scale.

The Full Stack

The research describes a concrete pipeline:

Why This Matters

Three practical implications:

Verifiable outputs. Every reasoning step maps to a KG path. You can audit why the model produced a particular answer—something large general models can’t offer.

Domain accuracy. Expert models grounded in domain-specific KGs should outperform general models on specialized tasks, with fewer parameters.

Smaller compute footprint. If structure can substitute for scale, the cost curve of AI changes fundamentally. Not every problem needs a trillion-parameter model.

A Different Trajectory

This isn’t a minor optimization. It’s a different thesis about how AI should be built:

Whether this pans out at production scale remains to be seen. But the research direction is compelling: less brute force, more structure.

Papers

Structure over scale. Follow for more ML Frontier episodes exploring research at the edge.

The Problem

We needed high-resolution barometric pressure data from dozens of sensors split across two physical locations. Each location needed multiple sensors—not just for coverage, but because averaging across several readings reduces noise and gives more trustworthy measurements. A single BMP280 reading has enough jitter that you want redundancy.

The existing BMP280 driver crate worked fine for one sensor at the default address. We needed it to support both I2C addresses so we could put two sensors on each bus—and then use multiplexers to scale that to many.

Why Fork the Driver?

The original bmp280-ehal crate is a platform-agnostic, no_std Rust driver built on embedded-hal traits. It runs on anything from bare-metal microcontrollers to Raspberry Pi. But it had a limitation: it assumed the default I2C address (0x76) and had no way to talk to a second sensor at the alternate address (0x77).

I needed the driver to address both 0x76 and 0x77—two sensors per bus instead of one. That change alone doubled capacity, and multiplexers would scale it from there. So I forked the driver and made three changes:

Commit 1: Refactor constructor (0b66fda)

Simplified the API by removing the implicit address tracking. The old constructor tied the driver to a single address at creation time. The refactored version makes read_calibration() public and removes the stored address, laying the groundwork for multi-address support.

Commit 2: Per-sensor calibration (d393bd6)

The structural change that enables multi-sensor support. Instead of flat calibration fields on the driver struct, this commit introduces:

• TempComp and PressureComp structs for temperature and pressure compensation data
• Sensors container holding Option<TempComp> and Option<PressureComp> for both addresses (0x76 and 0x77)
• Every reading method now takes an explicit address parameter

Each BMP280 ships with unique factory calibration coefficients baked into its NVM. The driver reads 24 bytes of calibration data per sensor and stores it independently. This matters because the compensation polynomial uses 12 coefficients—get them wrong and your pressure reading is meaningless.

Commit 3: Documentation and multi-sensor guide (21f16dc)

Updated the README and added comprehensive documentation in docs/multiple-sensor-support.md covering:

• Two sensors on one bus (differential pressure)
• I2C multiplexer topologies (TCA9548A, PCA9546A, TCA9543A)
• Cascading mux trees for large sensor arrays
• I2C extenders for long-distance distribution

The Hardware Setup

Doubling capacity with dual addresses

The BMP280 supports two I2C addresses (0x76 and 0x77), selected by the SDO pin. The old driver only tracked one. The new driver stores calibration for both, doubling capacity in every topology:

Multiplexer arrays

For the patent prototype, we used TCA9548A 8-channel I2C multiplexers. Each mux channel is an electrically isolated I2C bus, so sensors on different channels can share the same address:

                          ┌─── ch 0 ─── BMP280 (0x76) + BMP280 (0x77)
  Pi ── I2C ── TCA9548A ──┼─── ch 1 ─── BMP280 (0x76) + BMP280 (0x77)
               (addr 0x70) ├─── ch 2 ─── BMP280 (0x76) + BMP280 (0x77)
                          └─── ...         (up to 16 sensors per mux)

A Raspberry Pi at each location ran a Rust application on Linux that cycled through mux channels, read calibrated pressure/temperature data from every sensor, and logged the raw values. A separate PC-based Rust application pulled the log files for analysis, producing plots and spreadsheets.

What We Learned: BMP280 → BMP581

The BMP280 worked for the initial proof-of-concept, but we hit its limits. The sensor’s resolution wasn’t granular enough for the pressure differentials we needed to measure. The BMP581—Bosch’s newer generation—offers significantly better resolution and noise characteristics.

We also changed the architecture. Instead of running I2C extenders to reach distant sensor locations from a single controller, we gave each location its own Raspberry Pi with its own mux and BMP581 sensor array. The Pi boards communicate over gigabit LAN, which is simpler, more reliable, and eliminates the signal integrity issues that come with long I2C runs.

Location A:  Pi ── I2C ── TCA9548A ── BMP581s ──┐
                                                  ├── Gigabit LAN
Location B:  Pi ── I2C ── TCA9548A ── BMP581s ──┘
                                                  │
                                        Analysis PC (Rust)

Using the Driver

Basic usage with a single sensor:

use bmp280_ehal::BMP280;

let mut bmp = BMP280::new(i2c)?;
let temp = bmp.temp(0x76);     // Celsius
let pres = bmp.pressure(0x76); // Pascals

Two sensors on one bus:

let mut bmp = BMP280::new(i2c)?;
bmp.read_calibration(0x77);

let delta_p = bmp.pressure(0x76) - bmp.pressure(0x77);

With a multiplexer:

fn select_channel<I2C, E>(i2c: &mut I2C, ch: u8) -> Result<(), E>
where I2C: embedded_hal::blocking::i2c::Write<Error = E>
{
    i2c.write(0x70, &[1 << ch])
}

See the multi-sensor documentation for shared-bus patterns and cascaded mux topologies.

Fun Fact: Some of the Raspberry Pi boards with I2C multiplexers and BMP581 sensor arrays were submerged in diving bell-like enclosures with low power and LAN cables tethered.

References

Resource	Link
Paper	arXiv 2603.12056
Project	XSkill Project Page
Code	GitHub (MIT)
Video	XSkill: Memory Layer
Comments	Discord

The Problem: Isolated Episodes

Multimodal agents solve complex visual and tool-heavy tasks, but each run starts from scratch. An agent might figure out a multi-step workflow for extracting color data from an image—only to lose that knowledge when the next task begins. Useful lessons evaporate between sessions.

Two Kinds of Memory

XSkill introduces a dual-memory architecture that separates strategic knowledge from tactical knowledge:

Skills are structured Markdown documents containing workflows and tool templates for a class of tasks. A skill says: here is the overall approach for this kind of problem.

Experiences are smaller tactical lessons with triggering conditions, recommended actions, and failure notes. An experience says: when this specific pattern appears, use this tactic instead of guessing.

That split matters. Ablation analysis shows that removing either type hurts performance—skills alone aren’t enough, and experiences alone aren’t enough.

Two-Phase Framework

The framework operates in a loop:

Phase 1 — Accumulation. After completing rollout batches, the agent reviews past trajectories through visually-grounded summarization, cross-rollout critique, and hierarchical consolidation. This produces skill documents and experience items stored in persistent banks.

Phase 2 — Inference. Given a new task, the agent decomposes it, retrieves relevant skills and experiences via semantic search, adapts them to the current visual context, and injects them into the system prompt.

The key claim: agents improve through memory accumulation and retrieval, not parameter updates. No fine-tuning required.

Results

Evaluated across five benchmarks spanning visual tool use (VisualToolBench, TIR-Bench), multimodal search (MMSearch-Plus, MMBrowseComp), and comprehensive agent tasks (AgentVista):

Average gains of 2.6 to 6.7 points over baselines (Agent Workflow Memory, Dynamic CheatSheet, Agent-KB). Performance consistently improves as rollout count increases from 1 to 4.

Practical impact: syntax errors drop from 20.3% to 11.4% with skills, and tool name errors fall from 2.85% to 0.32%.

Concrete Example

A visual task requires identifying the color of a region behind specific text in an image. Without memory, the agent guesses. With XSkill, it retrieves a structured workflow: locate the text, isolate the region, sample pixels via code interpreter, and infer the color from actual data. Code interpreter usage increases from 66.6% to 77.0% on VisualToolBench—the agent learns to measure instead of guess.

Why This Matters

XSkill sits at the intersection of agents, tools, multimodal reasoning, and continual improvement. The practical takeaway isn’t just that memory helps—it’s that different kinds of memory help in different ways. Strategic workflows and situational tactics serve complementary roles.

Not a bigger model. A smarter memory layer.

References

Second ML Frontier episode. This one covers In-Context Reinforcement Learning—how transformers learn decision policies from trajectory examples in the prompt, without weight updates.

Resource	Link
Papers	5 papers covered
Video	ML Frontier 2: ICRL
Related	Saw (2/?): agentrail-rs — practical ICRL application
Comments	Discord

What is In-Context Reinforcement Learning?

The model observes sequences of states, actions, and rewards stored in the prompt. Instead of updating weights through gradient descent, the transformer approximates a policy from those trajectory examples.

Think of it like learning to cook by reading a journal of recipes that worked—and ones that didn’t—with notes on what went wrong.

Why Does This Matter?

AI agents often lose procedural knowledge when context is truncated between sessions. They know the goal but forget which API to call, which flags to use, which client library to reference, or how to validate output.

The traditional approach—writing instructions in markdown files—isn’t reliable. Agents ignore rules even when they’re present. ICRL offers a different path: instead of telling the agent what to do, show it what worked and what didn’t, with reward signals attached.

By embedding successful execution traces in the prompt, agents can reuse proven approaches instead of improvising from scratch.

Research Evidence

Decision Transformer (Chen et al., 2021)

Paper: arXiv 2106.01345

In brief: The paper that started it all. Instead of training an RL agent with value functions and policy gradients, just frame the problem as sequence prediction. Feed the transformer trajectories of (return-to-go, state, action) and let it predict the next action conditioned on the desired return. The transformer learns a policy by modeling sequences—no Bellman equations needed.

Why it matters: Reframed RL as something transformers already do well: sequence modeling.

Transformers Learn TD Methods (Wang et al., ICLR 2025)

Paper: arXiv 2405.13861

In brief: This paper shows that transformers don’t just pattern-match on trajectories—they actually approximate temporal-difference (TD) learning algorithms during the forward pass. The model internally implements something resembling TD updates, without being explicitly trained to do so.

Why it matters: Transformers aren’t just memorizing trajectories. They’re learning the underlying RL algorithm in-context.

OmniRL (2025)

Paper: arXiv 2502.02869

In brief: OmniRL proposes a transformer architecture that emulates actor-critic RL in-context, improving decision quality across multiple tasks. Rather than specializing in one environment, the model generalizes its in-context RL capabilities across diverse settings.

Why it matters: ICRL isn’t limited to one task—it scales across environments.

Reflexion (Shinn et al., NeurIPS 2023)

Paper: arXiv 2303.11366

In brief: Reflexion takes a different angle: instead of embedding raw trajectories, the agent generates verbal reflections on its failures and successes. These self-critiques are stored and injected into future prompts. The agent learns from its own written analysis of what went wrong.

Why it matters: Shows that trajectory-based learning doesn’t require structured (state, action, reward) tuples—natural language reflections work too.

Voyager (Wang et al., 2023)

Paper: arXiv 2305.16291

In brief: An open-ended Minecraft agent that builds a skill library from successful code executions. When Voyager solves a task, it stores the working code as a reusable skill. Future tasks can retrieve and compose these skills. The agent explores, learns, and accumulates capabilities without any weight updates.

Why it matters: Demonstrates ICRL at scale—an agent that gets better over time by accumulating proven solutions.

Papers

Practical Application: agentrail-rs

This isn’t just theory. I’m building agentrail-rs to apply ICRL to AI coding agents used for non-coding tasks—TTS generation, video compositing, file manipulation. The tool records trajectories (state, action, result, reward) and injects successful examples into future agent prompts. Early days, but the research says this should work.

See Saw (2/?): agentrail-rs for more on the engineering side.

Key Takeaways

In-Context RL turns agents from amnesiacs into learners. Follow for more ML Frontier episodes exploring research at the edge.

Welcome back to the Sharpen the Saw series, where I maintain existing tools, vibe-code new ones, and try new approaches to development workflows. Three tools, one pattern: each one hit a ceiling that required rethinking how it stores and shares information. This week covers reg-rs migrating from binary to text-based test definitions, avoid-compaction structuring multi-session AI agent workflows, and agentrail-rs adding reinforcement learning from an agent’s own success history.

reg-rs: Three Improvements to Regression Testing

reg-rs captures command output as golden baselines and flags regressions on re-run. This round of sharpening addressed three friction points: clunky commands, opaque binary storage, and noisy output.

Shell Aliases

The full command syntax (reg-rs run -p my_test -v) gets old fast. Shell aliases in source-rg.sh cut it to 4 characters with tab completion in zsh and bash:

Muscle memory builds fast. hlrg prints the full cheat sheet with examples.

Git-Friendly .rgt Format

The legacy .tdb format stored tests in SQLite binary files. git diff showed noise, merge conflicts were unresolvable, and new developers needed setup scripts. Regression tests are documentation—they define what your CLI actually does—so hiding them in binary blobs defeated the purpose.

The new .rgt format splits each test across git-tracked text files:

A test definition reads like documentation:

command = "myapp --version"
timeout = 10
exit_code = 0
desc = "Version string format check"
preprocess = "jq --sort-keys"
diff_mode = "json"

reg-rs create now writes .rgt directly—no intermediate .tdb step. Existing tests migrate with mgrg. PR reviewers see exactly what changed and why, git clone inherits every test, and merge conflicts resolve with standard tools.

Output Verbosity Controls

Previously, running tests dumped SQL debug info and full diffs regardless of context. Now output scales to what you need:

Exit codes are now meaningful too: 0 for all pass, 1 for regressions detected, 2 for errors. This makes reg-rs usable in CI pipelines where you check $? rather than parse output.

avoid-compaction: Structured Multi-Session Agent Workflows

avoid-compaction solves a problem anyone using AI coding agents hits eventually: context death. Long conversations get automatically compacted—the system summarizes older messages to make room for new ones, losing decisions, constraints, and procedural knowledge along the way.

The Insight

Rather than fighting compaction with longer context windows, avoid-compaction embraces frequent restarts as a feature. Each restart gives the agent a full, fresh context window. The trick is making handoffs explicit and structured so nothing is lost between sessions.

The Saga/Step Model

Work is organized into sagas (projects) composed of steps (focused units of work):

.avoid-compaction/
  saga.toml                    # name, status, current step
  plan.md                      # evolving project plan
  planned-steps.md             # upcoming steps preview
  steps/001-add-routes/
    step.toml                  # status, description, context files
    prompt.md                  # what the agent was told to do
    summary.md                 # what the agent actually did
  steps/002-add-tests/
    ...

Each session follows the same loop:

1. New Claude session starts with fresh context
2. Agent runs next to see the current step’s prompt and context
3. Agent does the work
4. Agent runs complete with a summary and next-step definition
5. User restarts Claude
6. Next session picks up exactly where the last left off

Why This Matters

The difference is reliability. Without structured handoffs, session 4 of a complex feature often forgets constraints from session 1. The agent improvises, makes contradictory decisions, or redoes work. With avoid-compaction:

• Every session starts with full context for its specific task
• Summaries accumulate so later sessions can reference earlier decisions
• The plan evolves as work reveals new insights
• Nothing is lost to compaction—it’s all in the filesystem

Current Improvements

The tool is going through a refactoring sequence to meet code quality standards:

1. Merging small command modules into larger, cohesive modules
2. Extracting shared display logic into reusable formatters
3. Workspace conversion to split concerns across crates
4. Session crate extraction for reusable JSONL handling

Each spike is low-to-medium risk, guided by the principle that smaller modules with clear responsibilities are easier to test, review, and extend.

agentrail-rs: Learning from Success

agentrail-rs is the evolution of avoid-compaction, adding a critical capability: In-Context Reinforcement Learning (ICRL). Where avoid-compaction structures handoffs, agentrail-rs teaches agents from their own history.

The 75% Problem

I use AI coding agents for more than coding—TTS audio generation, video compositing, file manipulation, and other multi-step production tasks. In practice, agents succeed about 75% of the time on these workflows. The failures aren’t random—they’re procedural: the agent forgets which API to call, which flags to use, which client library to reference, or how to validate output.

The traditional approach—writing instructions in markdown files like AGENTS.md or CLAUDE.md—isn’t reliable. Even when rules, instructions, and prohibitions are present, agents often ignore them. Claude, when called out, will say “You’re right, I should have done that”—and a few moments later make the same kind of mistake. Bigger prompts and more examples hit diminishing returns. The agent needs to learn from reward-based examples—both good and bad—delivered in-context, not static documentation it may or may not follow. That’s the core idea behind ICRL: show the agent what worked, what didn’t, and let the rewards guide its next attempt.

How ICRL Works

After each step, agentrail-rs records a trajectory:

state → action → result → reward

Successful trajectories are stored at .agentrail/trajectories/{task_type}/run_NNN.json. When the agent hits the same task type in a new session, the CLI retrieves the top N successful trajectories and injects them into the prompt: “Here’s how you succeeded at this before.”

The agent reads its own success patterns and self-corrects—no weight updates, no fine-tuning, no training pipeline. Just examples from its own history, delivered in context.

Four Step Types

agentrail-rs distinguishes what needs an agent from what doesn’t:

Deterministic steps can’t fail due to agent forgetfulness—they’re hard-specified. Validation steps create the reward signals that make ICRL work.

Architecture

The project is structured as a five-crate Cargo workspace:

The core and store crates are done. The next phase wires up the CLI, then deterministic execution, then the full ICRL retrieval and injection loop.

The Expected Payoff

Once the trajectory system is live (I just started vibe-coding it today), agents working on repetitive task types should see reliability climb from ~75% toward deterministic. Each success makes the next attempt more likely to succeed, without any manual intervention. The goal is a self-improving loop: agents learn their own procedures through experience.

Three Problems, Three Approaches

These projects aren’t related by a common architecture or shared abstraction. They’re related because each one solves a different productivity problem I keep hitting:

• reg-rs catches regressions that slip in whenever a feature is added or a fix applied—the kind of silent breakage that unit tests don’t cover because they test behavior, not actual output.
• avoid-compaction is a direct reaction to Claude Code auto-compacting multiple times per day, with noticeable performance degradation after each compaction. Structured restarts with explicit handoffs beat a slowly decaying context window.
• agentrail-rs tackles the opposite problem: not forgetting, but improvising. LLMs are probabilistic, and Claude keeps trying new (failing) approaches to routine tasks instead of sticking with the proven-working ones it has used and documented before. ICRL feeds successful trajectories back into context so the agent repeats what works.

Different problems, different solutions, same goal: spend less time fighting tools and more time building.

Habit 7: Sharpen the Saw. Spend less time fighting tools, more time building.

The Problem

COR24 is a 24-bit RISC soft CPU designed by MakerLisp for FPGAs. It has 3 general-purpose registers, a 24-bit address space, and runs at 101 MHz on inexpensive Lattice FPGAs. It’s MIT-licensed, well-documented, and has real hardware you can buy.

But LLVM doesn’t have a COR24 backend. Neither does GCC. Writing a full compiler backend could take a lot more effort. We need another way in.

The Trick: Borrow a Target

rustc supports MSP430, a 16-bit TI microcontroller, via LLVM’s MSP430 backend. It’s a nightly-only target (msp430-none-elf), but it works. The key insight: MSP430’s instruction set is close enough to COR24 that a translator can bridge the gap.

The full pipeline:

Rust Source (.rs)
     ↓  rustc --target msp430-none-elf --emit asm
MSP430 Assembly (.msp430.s)
     ↓  msp430-to-cor24 translator
COR24 Assembly (.cor24.s)
     ↓  COR24 assembler
Machine Code → COR24 Emulator (or real FPGA hardware)

No custom compiler. No modified LLVM. Just Rust’s nightly toolchain and a ~1,800-line translator written in Rust. This is a proof-of-concept—an educational demo, not a production tool for real COR24 hardware.

Level 1: The Compiler Optimizes Away Your Code

Let’s start simple. Three numbers, one add:

#![no_std]

const RESULT_ADDR: u16 = 0x0100;

#[inline(never)]
#[no_mangle]
pub fn demo_add() -> u16 {
    let a: u16 = 100;
    let b: u16 = 200;
    let c: u16 = 42;
    a + b + c  // Returns 342
}

#[no_mangle]
pub unsafe fn start() -> ! {
    let result = demo_add();
    core::ptr::write_volatile(RESULT_ADDR as *mut u16, result);
    loop {}
}

Compile to MSP430 and the rabbit hole opens immediately. Here’s what rustc emits for demo_add:

demo_add:
    mov     #342, r12
    ret

Two instructions. LLVM constant-folded 100 + 200 + 42 into 342 at compile time. The addition doesn’t exist in the output—the compiler proved the answer is always the same and replaced the computation with a constant load.

The translator converts this to COR24:

demo_add:
    la      r0, 0x000156    ; load 342 (24-bit)
    jmp     (r1)            ; return via r1

Run it in the emulator (scripts/demo-add.sh):

Executed 3 instructions
CPU halted (self-branch detected)

=== Registers ===
  r0:  0x000156  (     342)

Two instructions in demo_add, three total to reach halt. The “add” demo that doesn’t add.

Level 1.5: More Variables Than Registers

What happens when Rust needs more live variables than COR24 has registers? MSP430 has 12 general-purpose registers. COR24 has 3. The translator has to spill the extras to the stack.

The accumulate function keeps 5 values alive simultaneously:

#[inline(never)]
#[no_mangle]
pub unsafe fn accumulate(seed: u16) -> u16 {
    let a = seed + 1;
    let b = a + seed;
    let c = b + a;
    let d = c + b;
    let e = d + c;
    let result = a ^ b ^ c ^ d ^ e;
    mem_write(RESULT_ADDR, result as u8);
    uart_putc(a);
    uart_putc(b);
    uart_putc(c);
    uart_putc(d);
    uart_putc(e);
    loop {}
}

The MSP430 assembly uses registers r6 through r10—five registers that don’t exist on COR24:

accumulate:
    push    r6
    push    r7
    push    r8
    push    r9
    push    r10             ; save 5 callee-saved registers
    mov     r12, r10        ; seed
    mov     r10, r6
    inc     r6              ; a = seed + 1
    add     r6, r10         ; b = a + seed
    mov     r10, r9
    add     r6, r9          ; c = b + a
    ...

The translator maps these to frame-pointer-relative stack slots, each 3 bytes (one COR24 word). Where MSP430 writes mov r10, r6, COR24 must load from one spill slot, operate, and store to another:

accumulate:
    sw      r0, 30(fp)     ; spill seed (r10 → offset 30)
    lw      r0, 6(fp)      ; save spill slot for r6
    push    r0
    ...
    lw      r0, 18(fp)     ; load r10 (seed)
    sw      r0, 6(fp)      ; copy to r6 slot
    lw      r0, 6(fp)      ; load r6
    add     r0, 1          ; a = seed + 1
    sw      r0, 6(fp)      ; store r6 back
    ...
    la      r0, 0xFF0000   ; RESULT_ADDR
    ; call mmio_write
    push    r1
    la      r2, mmio_write
    jal     r1, (r2)       ; jal saves return addr in r1
    pop     r1

It’s verbose—the COR24 output is much longer than the MSP430 input. But it’s correct. The emulator confirms the computation with 148 instructions and the XOR result stored to memory at 0x0100.

Level 2: The Compiler Writes Your Destructor

Rust’s Drop trait guarantees cleanup when a value goes out of scope. Does that work on a CPU with no OS, no allocator, no runtime?

pub struct Guard { addr: u16 }

impl Guard {
    #[inline(never)]
    #[no_mangle]
    pub fn guard_new(addr: u16) -> Guard {
        unsafe { mem_write(addr, 1); }  // mark: alive
        Guard { addr }
    }
}

impl Drop for Guard {
    #[inline(never)]
    fn drop(&mut self) {
        unsafe { mem_write(self.addr, 0); }  // mark: gone
    }
}

#[no_mangle]
pub unsafe fn start() -> ! {
    {
        let _g = Guard::guard_new(STATUS_ADDR);
        // STATUS_ADDR = 1 (guard is alive)
    }
    // STATUS_ADDR = 0 (compiler called drop here)

    mem_write(STATUS_ADDR, 0xFF);  // proof we continued
    loop {}
}

Look at the MSP430 assembly for start—the compiler inserted the drop call:

start:
    sub     #2, r1              ; allocate stack space
    mov     #256, r12           ; STATUS_ADDR
    call    #guard_new          ; create guard → writes 1
    mov     #256, 0(r1)         ; store Guard on stack
    mov     r1, r12             ; pass &Guard to drop
    call    #<Guard::drop>      ; compiler-inserted! → writes 0
    mov     #256, r12
    mov     #255, r13
    call    #mem_write          ; writes 0xFF
.LBB4_1:
    jmp     .LBB4_1             ; halt

The call #<Guard::drop> on line 6 is the compiler honoring the Drop contract. You didn’t write that call—rustc did. Memory at STATUS_ADDR goes: 0 → 1 → 0 → 0xFF, proving the destructor ran at the right moment.

The translated COR24 assembly preserves this structure—each call becomes a jal (jump-and-link), which saves the return address in r1:

start:
    sub     sp, 3               ; allocate stack space
    la      r0, 0x000100        ; STATUS_ADDR
    ; call guard_new
    push    r1
    la      r2, guard_new
    jal     r1, (r2)            ; create guard → writes 1
    pop     r1
    ...
    ; call <Guard::drop>        ; compiler-inserted!
    push    r1
    la      r2, <Guard::drop>
    jal     r1, (r2)            ; → writes 0
    pop     r1

RAII works on bare metal, on an architecture the Rust compiler has never heard of.

Level 3: Interrupts via asm! Passthrough

Here’s where it gets interesting. COR24’s interrupt mechanism uses hardware registers that MSP430 doesn’t have:

• iv: Interrupt vector—CPU jumps here when an interrupt fires
• ir: Interrupt return—saved PC to return to after the ISR
• jmp (ir): Return from interrupt

There’s no MSP430 equivalent—the LLVM backend has no concept of these registers. But Rust’s asm! macro combined with the translator’s passthrough mechanism can handle it.

The demo_echo_v2 example splits the problem: application logic in pure Rust, interrupt plumbing in asm! passthrough:

#![feature(asm_experimental_arch)]

/// Application logic --- pure Rust, compiled normally
#[inline(never)]
#[no_mangle]
pub fn to_upper(ch: u16) -> u16 {
    if ch >= 0x61 && ch <= 0x7A {
        ch & 0xDF  // clear bit 5
    } else {
        ch
    }
}

#[inline(never)]
#[no_mangle]
pub unsafe fn handle_rx() {
    let ch = mmio_read(UART_DATA);
    if ch == 0x21 {               // '!'
        mmio_write(HALT_FLAG, 1);
    } else {
        uart_putc(to_upper(ch));
    }
}

The ISR wrapper uses asm! with a @cor24: prefix that the translator passes through verbatim:

#[no_mangle]
pub unsafe fn isr_handler() {
    // Save COR24 state (asm! --- no Rust equivalent)
    core::arch::asm!(
        "; @cor24: push r0",
        "; @cor24: push r1",
        "; @cor24: push r2",
        "; @cor24: mov r2, c",      // save condition flag
        "; @cor24: push r2",
    );

    handle_rx();  // ← pure Rust, compiled through the pipeline

    // Restore state and return from interrupt
    core::arch::asm!(
        "; @cor24: pop r2",
        "; @cor24: clu z, r2",      // restore condition flag
        "; @cor24: pop r2",
        "; @cor24: pop r1",
        "; @cor24: pop r0",
        "; @cor24: jmp (ir)",       // return from interrupt
        options(noreturn)
    );
}

The "; @cor24: ..." lines look like MSP430 comments (so rustc ignores them), but the translator recognizes the prefix and emits them as real COR24 instructions. In the final COR24 assembly:

isr_handler:
    push r0
    push r1
    push r2
    mov r2, c                     ; save condition flag
    push r2
    ; call handle_rx              ← compiled Rust
    push    r1
    la      r2, handle_rx
    jal     r1, (r2)              ; jal saves return addr in r1
    pop     r1
    pop r2
    clu z, r2                     ; restore condition flag
    pop r2
    pop r1
    pop r0
    jmp (ir)                      ← hardware interrupt return

The start function sets up the interrupt vector and enables UART reception:

core::arch::asm!(
    "; @cor24: la r0, isr_handler",
    "; @cor24: mov iv, r0",         // iv = interrupt vector register
    "; @cor24: lc r0, 1",
    "; @cor24: la r1, 0xFF0010",    // UART interrupt enable register
    "; @cor24: sb r0, 0(r1)",       // enable UART RX interrupt
);

Type a letter, the hardware fires an interrupt, the ISR saves registers, calls handle_rx (compiled Rust), converts to uppercase, echoes it via UART, restores registers, and returns. The boundary between Rust and hardware is exactly where you’d expect it.

What the Translator Actually Does

The msp430-to-cor24 translator (~1,800 lines of Rust) handles the mechanical differences:

COR24’s calling convention centers on the jal (jump-and-link) instruction. jal r1, (r2) jumps to the address in r2 and saves the return address in r1. The callee returns with jmp (r1). Since the translator re-uses r1 for the return address, it saves and restores r1 around each call with push r1 / pop r1. COR24’s native C compiler convention uses a standard prologue (push fp; push r2; push r1; mov fp,sp) and passes arguments on the stack—the translator doesn’t follow that full protocol, but it does use the same jal/jmp (r1) mechanism for call and return.

The entry point handling is worth noting. rustc emits functions in alphabetical section order, so the panic handler often lands at address 0. Every demo uses a #[no_mangle] pub unsafe fn start() -> ! as its entry point—a convention I chose for this project. The translator looks for a start label and emits a reset vector prologue (la r0, start + jmp (r0) at address 0), mimicking how real microcontrollers boot. This isn’t a Rust or MSP430 convention; it’s a project-level rule that keeps the translator simple and every demo consistent.

Try It Yourself

# Prerequisites
rustup toolchain install nightly
rustup target add msp430-none-elf --toolchain nightly

# Clone and build
git clone https://github.com/sw-embed/cor24-rs.git
cd cor24-rs/rust-to-cor24

# Run the add demo (full pipeline)
bash scripts/demo-add.sh

# Run the UART hello demo
bash scripts/demo-uart-hello.sh

# Or compile any demo project
cargo run --bin msp430-to-cor24 -- --compile demos/demo_drop

Each demo script traces the full pipeline: Rust source → MSP430 assembly → COR24 assembly → emulator output with register dumps.

Key Takeaways

1. You don’t need a compiler backend to target a new architecture. If a similar-enough target exists, a translator can bridge the gap.

2. The Rust compiler is surprisingly good at bare-metal code. Constant folding, dead code elimination, and Drop all work correctly even when the output gets re-targeted to an architecture LLVM has never seen.

3. asm! passthrough is the escape hatch. Hardware-specific operations (interrupt setup, condition flag save/restore) bypass the translation layer entirely using comment-prefix conventions.

4. The pipeline is auditable. Every intermediate artifact (.msp430.s, .cor24.s, register dumps) is human-readable. You can trace any behavior from source to silicon.

The rabbit hole goes deeper. Next time: what happens when the 16-bit intermediate can’t express a 24-bit value.

First Machine Learning Mondays post. ML Frontier explores cutting-edge research in machine learning.

Resource	Link
Papers	5 papers covered
Video	ML Frontier #01: Neural Collapse
Comments	Discord

What is Neural Collapse?

During the final phase of training, deep network representations converge to a specific geometric pattern. Class means become equidistant and form a symmetric simplex structure in the feature space.

Think of it like points arranging themselves at equal distances on a sphere.

Why Does This Happen?

When networks are trained past zero training error, representations continue simplifying. The network finds the most symmetric way to separate classes, forming equal angles between all class centers.

This isn’t random—it’s mathematically optimal.

2024-2025 Breakthroughs

Recent research proves neural collapse is globally optimal in deep transformers and ResNets with regularization. As depth increases, the network provably converges to this collapsed geometry.

This changes how we think about deep learning. Collapse explains why overparameterized networks generalize well. It also guides continual learning, where progressive collapse prevents catastrophic forgetting.

Papers

Paper Summaries

Beyond Unconstrained Features (Sep 2024)

Paper: Hong & Ling

In brief: Most neural collapse theory assumes you can put class markers anywhere you want—like sticking Post-it notes anywhere on a wall. But real shallow networks have limits. This paper shows neural collapse still emerges even in small networks with real data constraints, not just idealized deep networks.

Why it matters: Neural collapse isn’t just a “big model” phenomenon—it happens in smaller, practical architectures too.

Wide Networks with Weight Decay (Oct 2024)

Paper: Jacot, Súkeník, Wang & Mondelli

In brief: If you train a wide neural network with weight decay (a common regularization trick), this paper proves the network will exhibit neural collapse. It’s the first proof that end-to-end training (not just theory) leads to collapse.

Why it matters: Weight decay isn’t just preventing overfitting—it’s actively pushing the network toward optimal geometry.

Beyond the Unconstrained Features Model (Jan 2025)

Paper: arXiv 2501.19104

In brief: The “unconstrained features model” assumes networks can place representations anywhere. Real networks have architectural constraints. This paper extends neural collapse theory to realistic settings where the architecture limits what’s possible.

Why it matters: The theory holds up in real-world conditions, not just toy examples.

Progressive Neural Collapse for Continual Learning (May 2025)

Paper: arXiv 2505.24254

In brief: When you teach a network new things, it often forgets old things (catastrophic forgetting). This paper uses neural collapse to fix that: by carefully managing how class representations “collapse” over time, the network can keep learning new tasks without losing old knowledge.

Why it matters: Neural collapse isn’t just a curiosity—it’s a tool for building better learning systems.

Globally Optimal in Transformers and ResNets (May 2025)

Paper: Súkeník et al.

In brief: Imagine you have a box of crayons and need to organize them so each color is as far from every other color as possible. This paper proves that deep neural networks automatically find the best possible arrangement—not just a good one, but the mathematically perfect one. And this happens in both transformers (like GPT) and ResNets (like image classifiers).

Why it matters: It’s not a coincidence that networks learn this way. It’s provably optimal.

Key Takeaways

Neural collapse reveals the hidden geometry of learning. Follow for more ML Frontier episodes exploring cutting-edge research.

Three tools, one theme: sharpening the foundation. This week covers pjmai-rs bug fixes and new features, plus a first look at two Rust frameworks for building LLM-powered applications—Rig and langchain-rust.

pjmai-rs: Fixing the Foundation

Before adding AI features to any tool, you need a solid foundation. Since the last update, pjmai-rs received critical fixes and practical new features.

The Rust 2024 Edition Bug

Upgrading to Rust edition 2024 broke project removal silently. The IndexMap::remove() method changed semantics—it now preserves insertion order differently. The fix:

// Rust 2024 broke this
- projects.remove(name)

// shift_remove maintains expected behavior
+ projects.shift_remove(name)

A one-line fix, but the kind that silently corrupts data if you miss it. The 2024 edition migration guide mentions this change, but it’s easy to overlook in a large codebase.

Shell Integration Improvements

• Help flags: All aliases (chpj, hypj, stpj, etc.) now properly pass --help through
• After-help messages: Every subcommand shows examples and related commands
• Version matching: --version output now matches Cargo.toml
• Argument validation: Better error messages for invalid flag combinations

New Capabilities

These features are covered in detail in the Personal Software post.

Rig: Type-Safe AI Agents in Rust

Rig (rig-core 0.32) is a Rust library for building LLM applications with a unified API across providers. I built try-rig to explore it hands-on with Ollama running locally—no cloud API keys needed.

A Simple Agent

The builder pattern makes agent construction readable:

use rig::providers::ollama;
use rig::client::Nothing;
use rig::completion::Prompt;

let client = ollama::Client::new(Nothing)?;

let agent = client
    .agent("llama3.2")
    .preamble("You are a helpful assistant. Be concise.")
    .build();

let response = agent.prompt("What is Rust?").await?;

Swap ollama::Client for openai::Client or anthropic::Client and the rest stays the same.

Tool-Equipped Agents

Where Rig gets interesting is tools. Define a tool by implementing the Tool trait with typed args:

#[derive(Deserialize, Serialize)]
pub struct Calculator;

impl Tool for Calculator {
    const NAME: &'static str = "calculator";
    type Error = CalcError;
    type Args = CalcArgs;
    type Output = f64;

    async fn definition(&self, _prompt: String) -> ToolDefinition {
        ToolDefinition {
            name: "calculator".to_string(),
            description: "Perform arithmetic: add, subtract, multiply, divide".to_string(),
            parameters: json!({ /* JSON Schema */ }),
        }
    }

    async fn call(&self, args: Self::Args) -> Result<Self::Output, Self::Error> {
        match args.operation.as_str() {
            "add" => Ok(args.x + args.y),
            "multiply" => Ok(args.x * args.y),
            // ...
        }
    }
}

Then chain tools onto the agent builder:

let agent = client
    .agent(model)
    .preamble("Use tools for math, weather, files, date/time, and text.")
    .tool(Calculator)
    .tool(WeatherLookup)
    .tool(FileSearch)
    .tool(DateTime)
    .tool(StringTool)
    .build();

The compiler verifies all tool types at build time. No runtime surprises from mismatched schemas.

RAG with Embeddings

Rig has built-in vector store support. The RAG agent in try-rig uses nomic-embed-text via Ollama for fully local embeddings:

let embedding_model = client.embedding_model_with_ndims("nomic-embed-text", 768);

let embeddings = EmbeddingsBuilder::new(embedding_model.clone())
    .documents(knowledge_entries)?
    .build()
    .await?;

let vector_store = InMemoryVectorStore::from_documents(embeddings);
let index = vector_store.index(embedding_model);

let rag_agent = client
    .agent(model)
    .preamble("Use the provided context to answer accurately.")
    .dynamic_context(2, index)  // inject top 2 results
    .build();

Multi-Agent Orchestration

Rig agents can be used as tools for other agents. The try-rig demo builds a math specialist and a weather specialist, then hands both to an orchestrator:

let calc_agent = client.agent(model)
    .preamble("You are a math specialist.")
    .name("math_agent")
    .description("Arithmetic: add, subtract, multiply, divide.")
    .tool(Calculator)
    .build();

let weather_agent = client.agent(model)
    .preamble("You are a weather specialist.")
    .name("weather_agent")
    .tool(WeatherLookup)
    .build();

let orchestrator = client.agent(model)
    .preamble("Route questions to math_agent or weather_agent.")
    .tool(calc_agent)
    .tool(weather_agent)
    .build();

The orchestrator decides which specialist to call based on the question. Agents as tools—composable all the way down.

Typed Extraction

Rig can also extract structured data from unstructured text using schemars:

#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct ContactInfo {
    pub name: Option<String>,
    pub email: Option<String>,
    pub phone: Option<String>,
}

let extractor = client
    .extractor::<ContactInfo>(model)
    .preamble("Extract contact information from text.")
    .build();

let contact = extractor.extract("Call Jane at 555-1234 or jane@example.com").await?;

The output is a proper Rust struct, not a string you have to parse.

The try-rig CLI

All of these patterns are runnable from try-rig:

try-rig ask "What is Rust?"           # Simple agent
try-rig tools "What is 42 * 17?"      # Tool calling
try-rig rag "Explain Rust ownership"   # RAG with embeddings
try-rig multi "Weather in Tokyo?"      # Multi-agent routing
try-rig extract "Call Jane at 555-1234"# Typed extraction
try-rig stream "Explain TCP/IP"        # Streaming response

Five times less memory than equivalent Python, zero Python dependencies, and the compiler catches your mistakes before runtime.

langchain-rust: Chain Abstractions for Rust

langchain-rust (v4.6.0) brings LangChain’s composable chain architecture to Rust. Where Rig focuses on type-safe agents, langchain-rust focuses on chain orchestration. The try-langchain-rust repo has 13 runnable examples across the full feature set.

LLM Chains and Prompt Templates

The chain builder composes prompts and LLMs into reusable pipelines:

use langchain_rust::{
    chain::{Chain, LLMChainBuilder},
    fmt_message, fmt_template, message_formatter,
    prompt::HumanMessagePromptTemplate,
    prompt_args, schemas::messages::Message, template_fstring,
};

let prompt = message_formatter![
    fmt_message!(Message::new_system_message("You are a concise technical writer.")),
    fmt_template!(HumanMessagePromptTemplate::new(template_fstring!(
        "Explain {topic} in 2-3 sentences.", "topic"
    )))
];

let chain = LLMChainBuilder::new()
    .prompt(prompt)
    .llm(llm)
    .build()?;

let result = chain.invoke(prompt_args! { "topic" => "ownership in Rust" }).await?;

Ollama works the same way—swap the LLM and everything else stays identical:

let ollama = Ollama::default().with_model("llama3.2");
// use ollama in place of llm above

Sequential Chains

Pipe one chain’s output into the next. This example generates a story concept, then a title, then an opening line:

let concept_chain = LLMChainBuilder::new()
    .prompt(/* "Create a concept about " */)
    .llm(llm.clone())
    .output_key("concept")
    .build()?;

let title_chain = LLMChainBuilder::new()
    .prompt(/* "Suggest a title for " */)
    .llm(llm.clone())
    .output_key("title")
    .build()?;

let chain = sequential_chain!(concept_chain, title_chain, opening_chain);

let output = chain.execute(prompt_args! { "topic" => "a robot that learns to paint" }).await?;
println!("Title: {}", output["title"]);

Conversational Memory

Multi-turn dialogue with automatic context retention:

let chain = ConversationalChainBuilder::new()
    .llm(llm)
    .memory(SimpleMemory::new().into())
    .build()?;

chain.invoke(prompt_args! { "input" => "My name is Alice and I'm learning Rust." }).await?;
// Turn 2: chain remembers Alice and Rust
chain.invoke(prompt_args! { "input" => "What's my name?" }).await?;

RAG with Vector Store

The conversational retriever chain combines memory, vector search, and LLM generation. The try-langchain-rust demo uses SQLite for the vector store:

let store = StoreBuilder::new()
    .embedder(OpenAiEmbedder::default())
    .connection_url("sqlite::memory:")
    .table("documents")
    .vector_dimensions(1536)
    .build().await?;

store.initialize().await?;
add_documents!(store, &documents).await?;

let chain = ConversationalRetrieverChainBuilder::new()
    .llm(llm)
    .rephrase_question(true)
    .memory(SimpleMemory::new().into())
    .retriever(Retriever::new(store, 3))
    .prompt(prompt)
    .build()?;

Multi-turn RAG conversations work out of the box—the chain rephrases follow-up questions using conversation history before searching the vector store.

Agents and Semantic Routing

Agents select tools autonomously. The demo uses a CommandExecutor tool:

let agent = ConversationalAgentBuilder::new()
    .tools(&[Arc::new(CommandExecutor::default())])
    .build(llm)?;

let executor = AgentExecutor::from_agent(agent)
    .with_memory(SimpleMemory::new().into());

executor.invoke(prompt_args! { "input" => "List the files in the current directory" }).await?;

Semantic routing dispatches queries by meaning—define example utterances for each route and the router classifies new inputs:

let coding_route = Router::new("coding", &[
    "How do I write a function in Rust?",
    "Explain generics in programming",
]);
let devops_route = Router::new("devops", &[
    "Set up a CI/CD pipeline",
    "Configure Docker containers",
]);

let router = RouteLayerBuilder::default()
    .embedder(OpenAiEmbedder::default())
    .add_route(coding_route)
    .add_route(devops_route)
    .threshold(0.80)
    .build().await?;

let route = router.call("Explain the borrow checker").await?;
// → "coding"

The try-langchain-rust Examples

All 13 examples are runnable from try-langchain-rust:

cargo run --example llm_chain         # Prompt templates + LLM chain
cargo run --example conversational    # Multi-turn memory
cargo run --example ollama            # Local LLM (no API key)
cargo run --example streaming         # Token-by-token output
cargo run --example vector_store      # SQLite similarity search
cargo run --example doc_loader        # Text/CSV loading + splitting
cargo run --example qa_chain          # Q&A over documents
cargo run --example rag_chat          # Conversational RAG
cargo run --example agent             # Agent with tools
cargo run --example sequential        # Chained pipelines
cargo run --example semantic_router   # Route by meaning

Rig vs. langchain-rust

They’re complementary more than competing. A project could use Rig for the agent layer and langchain-rust for document ingestion and retrieval.

What’s Next for pjmai-rs

The Phase 4 roadmap for pjmai-rs includes AI integration:

• AI context injection: ctpj --for-agent already outputs project metadata as JSON for AI prompts
• Restricted PATH mode: Sandboxed environments for autonomous agents
• AI-assisted discovery: Let agents find and register projects automatically

The question isn’t whether pjmai-rs will use Rig or langchain-rust—it’s which patterns from each framework make sense for a CLI tool that helps AI agents navigate codebases.