DEV Community: Luca

Architecture-first vs problem-first: what five months of over-engineering looks like

Luca — Mon, 13 Jul 2026 18:24:22 +0000

Why build something? And what if nobody ends up using it?

There are good answers to the first one. You build because you need a thing that doesn't exist yet. You build to see if you can, the technical challenge, the "is this even possible?" You build to impress someone, or just because you think it'll make people's day a little less annoying.

All of those are real reasons, and at different points, I told myself most of them.

Then, a few days ago, late in the day, at the end of a coding session, five months into the project, I asked myself those two questions back-to-back. And for the first time, I couldn't answer the second one.

Zeri worked. Every feature did what it was supposed to do. Both processes handshake cleanly, a variable set in one context showing up in another a second later, the TUI rendering exactly as I'd pictured it. And I sat there and couldn't come up with one honest sentence explaining why anyone would actually download it.

That gap, between something built well and something that has a reason to exist, turned out to be the most useful thing this whole project taught me. So I'm shipping it anyway, and I'll tell you why.

What I built

Zeri is a TUI multi-language REPL. You launch it, pick a language, Python, JavaScript (with Bun), Ruby, or LuaJIT, and you get an interactive session in your terminal. You can switch languages mid-session, share variables across them, save and reload your work, manage snippets, and talk to a local LLM through a command running on Ollama.

The feature list isn't the interesting part, though. The interesting part is what's underneath.

Two processes, one app

Zeri is split into two processes: a headless engine written in C++23 and a TUI frontend built in Go using Bubble Tea and Lip Gloss. The engine does all the evaluation, state, and runtime coordination. The frontend does rendering, input, and everything the user actually sees and touches. They talk to each other over a custom binary IPC protocol that I built from scratch.

Why split them at all? Separation of concerns, but taken seriously instead of as a buzzword. The engine has no idea what's rendering its output; it could be my TUI, could be a web UI, could be an editor plugin, doesn't care. And the frontend has no idea how code actually gets evaluated. The nice side effect is that the engine can't crash the UI and the UI can't freeze the engine, because each one runs its own lifecycle in its own process.

I went with C++ for the engine because I needed tight control over memory and process management, the engine spawns and babysits multiple language runtimes, and I wanted to be close to the metal for that. Go for the frontend because the Charm stack is honestly the best TUI tooling I've found in any language, with a strong focus on the UX/UI part that is necessary. Go's concurrency model makes handling async IPC messages way less painful than it would be elsewhere.

The protocol

The thing connecting the engine and the frontend is a custom binary protocol. Every message is a fixed header, payload length, message type, sequence number, and then the payload. The framing is binary on purpose: the receiver reads four bytes, knows exactly how long the message is and what kind it is, and grabs the rest without parsing anything to find where the message ends.

The payload inside that frame is just JSON, and that split is deliberate. The framing runs constantly and has to be cheap, so it's binary. The payload I want to read in a log and debug is JSON. Fast where it has to be, simple where it can afford to be. Chasing binary all the way down would've bought me almost nothing and cost me every debugging session for five months.

That protocol came out of Zeri, and I pulled it into a standalone library, Yuumi, with a dedicated SDK per language. This is turning into a real rabbit hole; we'll see how it goes.

Sidecar runtimes

Each language runs as its own sidecar process. Switch to Python, Zeri spawns or reuses a Python process; run some code, the engine routes it to the right sidecar, grabs the output, and ships it back to the frontend over IPC.

Think of it like a restaurant kitchen. The engine is the head chef calling out orders; each sidecar is a station, one does Python, one Ruby, one Lua. If the fry station catches fire, the pasta station keeps going (pasta, because I'm Italian). A segfault in one runtime doesn't take down the others: they're fully isolated, each with its own memory and lifecycle. The engine stands in the middle, orchestrating, handling timeouts and failures when a station goes down.

SharedScope

The piece I'm proudest of, technically, is SharedScope, sharing variables across languages. You set a value in Python, switch over to JavaScript, ask for it, and it's there. Sounds simple. It is absolutely not simple, and explaining why is the most interesting part of the whole engine.

The problem is that a value in one language isn't the same object in another. A Python int and a JavaScript number are different things in memory. None, null, and nil are three different ways of saying nothing. A dict isn't an object isn't a table. So there's no "just pass the variable"; something in the middle has to own a neutral version of that value that doesn't belong to any single language.

That something is the C++ engine. It works like a hub: every language runtime is a spoke, isolated, with its own namespace, and the engine sits in the center holding the canonical copy of every shared value as a language-agnostic type. When Python calls set, the value gets serialized to JSON, shipped to the engine over the protocol, and rebuilt into that neutral representation, a normalized form where every int becomes a 64-bit integer, every float a double, strings, booleans, null, and arrays and maps built recursively out of those. When JavaScript later calls get, the engine serializes its canonical copy back out, and the JS side rebuilds it natively. The runtimes never touch each other. They only ever talk to the hub.

Two things I decided on purpose matter more than they look. First, it's copy by value, not shared memory. You're not getting a live reference; modify the object on the JavaScript side, and the Python side has no idea. If you want the change to propagate, you set it again. Pretending otherwise would've meant faking shared memory across four separate processes, which is a lie waiting to crash. Second, if a value doesn't fit the supported set, a function, a class instance, a Python set, a BigInt, or an integer too large for 64 bits, the engine doesn't quietly mangle it into something wrong. It refuses, explicitly, and the set call fails on the spot. I'd rather it break loudly than hand you corrupted data three steps later.

So the scope is honest and narrow: primitives and simple containers, by value, with hard edges where the languages stop agreeing. Within that box, it's reliable, and getting it reliable, the type normalization, the failure modes, the request/response handshake underneath it, is the hardest engineering in the project.

And it works. A variable I wrote in Python, read back in JavaScript, a second later, exactly right.

It was both interesting and frustrating to create this software, and it was fitting to describe it so comprehensively. And that's precisely what makes the next section so annoying to write.

The gap

Everything worked. The handshake was clean, SharedScope moved values across languages without choking, sessions saved and restored, the AI thing answered, the TUI looked great. I could demo every single feature, and every single one did its job.

But I kept landing back on the same question, and it would not leave me alone: who is this for?

I tried to answer it honestly. A developer who works across multiple languages. Okay, but when exactly? If I'm writing Python, I open a Python REPL. If I'm in JavaScript, I open Node or Bun. The moment I need both, I open two terminals, and that costs me about three seconds. Zeri's cross-language sharing is cool, but when was the last time I actually needed to set a variable in Python and read it back in JavaScript inside a REPL? I couldn't remember it ever happening.

Session persistence is useful, except that most REPLs already have history. The AI integration is handy, except Ollama already ships a CLI. Snippet management is nice, except so is a file.

Every feature was built well. None of them answered the question. I'd built a pile of solutions and gone looking for a problem afterward.

How I missed it for five months

The honest answer is that I never asked. Zeri started as an architecture flex. "Can I build a two-process TUI app with a custom IPC protocol?"

The answer turned out to be yes, and the momentum of building just carried me for five months straight. Every week handed me a new interesting problem: serialization, process management, runtime orchestration, cross-language type mapping. I was learning C++23, learning Go's concurrency patterns, designing a binary protocol from nothing. The work was real, and I got better at my job because of it.

But not once did I stop and ask the boring question: what specific frustration does this kill? What's painful right now that Zeri makes painless?

I know what that question sounds like when it has an answer, because my other projects all have one. One of them exists because sharing dumb code before it's PR-ready is awkward; you're pasting into Slack or screen-sharing, both terrible for async. Another exists because I lose the first two hours of every new project to the same scaffolding I've done a hundred times. Another because I watch myself burn tokens sending bloated prompts to an LLM with no tooling to tighten them up first.

Each of those starts with "I keep running into this." Zeri starts with "I wonder if I can build this." That's the whole gap. Not skill, not effort, origin.

Architecture-first vs problem-first

I've started calling these two modes architecture-first and problem-first, and you can probably already guess the split: one puts solving a real problem front and center, the other aims at "the best possible architecture nobody asked for", basically a very complicated paperweight.

Problem-first: something annoys you, you build the smallest thing that makes it stop. The problem leads, easy.

Architecture-first: you build the cool thing, then go looking for a reason it should exist. The justification limps along behind; all of this breaks at some point.

Zeri is exactly this. Every other project I've ever had or started starts with a problem, even a small one. Five months of architecture, implementation, and searching for a final goal. Good execution. Beautiful. Now what?

What this actually means

I don't think this is just my problem. I think it's a recurring pattern, and I think many developers fall for it, especially self-taught developers building a portfolio, which is exactly my situation. The goal of impressing with a perfect project overrides the purpose of our development.

What five months of working alone taught me

When you're learning systems programming, there's a real high in making low-level things work. Two processes talking over a protocol you designed yourself is satisfying. Serializing values across language boundaries is a proper puzzle. The feedback loop never stops: something breaks, you fix it, you learn something, repeat. Five months of that is a genuinely good education.

The trap is that building feels like progress even when you're going nowhere in particular. Every bug fix, every feature, every refactor is real work; it's just not necessarily pointed at anything. And from the inside, you can't tell the difference.

Working solo makes it worse. Nobody reviews your code, nobody asks "wait, why are we building this this way?" You get fast at debugging, and you start trusting your own judgment, but you lose the one thing that would've saved you: someone to ask the uncomfortable question. It's like spending a whole Sunday slow-cooking a ragù from scratch, perfect technique, six hours on the stove, and only realizing at dinner that nobody at the table eats meat. Good execution, bad dish. Five months alone is exactly how you end up cooking that ragù.

So if you're building solo, find someone who'll ask why your project gets to exist at all, not about your code, but about the thing itself. Write it up and post it on Dev.to, Hacker News, Reddit. You might get the answer you couldn't reach on your own.

When to stop and ask

If I did this again, I'd put a checkpoint at the one-month mark, not to review the code, but to pressure-test the thesis. Can I say in one sentence who this is for and what it fixes? If I can't, that's not a signal to quit. It's a signal to stop typing and think. Maybe the answer's there, and I just haven't found the words. Maybe it isn't, and I should call it a learning project out loud instead of pretending it's a product. Either one is fine. Spending five months not asking is the part that isn't.

What do you do with something "empty"?

I could've just shelved Zeri. I didn't, for three reasons.

The engineering is real and worth showing. If you're building a portfolio and job hunting, something that proves you can think at the systems level has value even when it isn't a product. The lesson is worth sharing because the architecture-vs-product question barely comes up in "what I learned building X" posts, which are usually all about technical decisions and rarely about whether the thing should exist. And open source is unpredictable; maybe somebody looks at this and sees a use case I'm too close to see. Shipping it keeps that door open. Not shipping it closes it for no reason.

Where this goes

The Zeri repo is open on my GitHub: github.com/ilmartotch/ZeriReplEngine. I'm deliberately not calling this a launch, because it isn't one. It's a portfolio piece and an open invitation: here's what I built, here's what building it taught me, here's what I'd do differently next time.

Yuumi, the protocol, is turning into its own library, and funnily enough, it has a clearer identity than Zeri ever did. It's one of the better things to come out of all this. The rest of my projects are in the pipeline.

Five months. A solid architecture. One genuinely useful lesson. I'd do it again. I would simply have asked the question much earlier and differently.

I have two years of experience in this (software engineering), so take all of it with you and keep that in mind. I'm not handing down lessons from a mountain, I'm telling you what I figured out the slow and expensive way and betting it's useful to somebody a few steps behind me.

I'm ready for the salt or the flame; in the end, I'm a League of Legends player.

Designed to survive: how Zeri's core assumes everything can die

Luca — Mon, 13 Jul 2026 18:24:07 +0000

The value that belongs to no one

The project structure is like a kitchen in mid-service. Four stations, four cooks, and none of them speak the same language. The one on the grill thinks in Python. Pasta speaks JavaScript. Garde-manger works in Ruby, and the dessert chef only knows Lua. An order comes in that needs all four to touch the same plate. Now: how do you pass a half-finished dish between people who can't read each other's tickets?

That's the problem Zeri spends most of its complexity solving. It's a terminal REPL where you can start a value in one language and finish it in another, set a dictionary in Python, read it back in JavaScript, and change it in Lua. Sounds small. It isn't, because a value in one language simply is not the same object in another. A Python int and a JavaScript number are different things in memory. None, null, and nil are three different ways of saying nothing, and they don't agree on much beyond the sentiment. Somebody in the middle has to own a neutral version of that value, one that belongs to no language, so it can be handed to any of them.

The companion piece to this article argues about why I built a thing like this before I had a user who asked for it. This one is about the how, and the how turned out to have a single idea running under every part of it, so I'll say it once up front and then let it resurface: every boundary in this system is built assuming the other side can die. Two processes, two protocols, four sidecars, one shared hub, and each seam is designed around the possibility that whatever's on the far end goes away mid-sentence. Not as a failure case bolted on afterward. As the thing that decides the shape.

None of what follows is theory. Every claim is a line I can point at, and a couple of them are lines I had to fix while writing this, which, honestly, is the best argument I know of for writing the article at all.

Two processes that agree to die together

Zeri runs as two processes. There's a headless engine written in C++ that does evaluation, holds state, and supervises the language runtimes. And there's a terminal UI written in Go, built on the Charm stack, that does rendering and input. They talk over a socket. That's the whole topology.

The split isn't decoration. The engine has no idea what renders its output; the UI has no idea how code gets evaluated. That ignorance is the point; it means a crash on one side can't corrupt the memory of the other, because there's no shared memory to corrupt. Two address spaces, one pipe between them.

Why C++ for the engine specifically? Because the engine is the thing that owns other processes. It forks runtimes, wires up their file descriptors, sets death signals, and builds job objects. That's memory-and-process work, and it's the job C++ is actually good at. Go got the frontend for the opposite reason: an event-driven TUI wants cheap concurrency and good tooling, and the Charm stack is built for exactly that shape.

Now the interesting part, and the first place the "assume death" rule shows up, with a twist I didn't expect when I started. The two sides do not survive each other symmetrically. The frontend survives a dead engine: if the engine process crashes, the UI catches it and transitions to a disconnected state through two independent paths (one watching the process, one watching the transport). But the engine does not survive a frontend that walks away. Any I/O error on the bridge triggers a shutdown:

bridge.on_error([bridgeTerminal](yuumi::Error) {
    bridgeTerminal->RequestShutdown();
});

That call unblocks the REPL read loop with an empty value; the loop breaks, and the process exits. This is deliberate. An engine with no frontend attached is a headless process nobody can see, and nobody can kill cleanly. So the engine chooses to die with the thing it serves rather than outlive it. The rule isn't "nothing ever dies." The rule is "process isolation stops a crash from spreading corruption, and past that, dying on purpose beats staying." Symmetry would have been easier to write and worse to run.

Two protocols, because there are two kinds of "other side"

Here's a design decision that looks like duplication until you see why it isn't: Zeri has two internal protocols, one for the UI-to-engine link, one for the engine-to-runtime link. I could have reused one for both. I didn't, and the reason is that the two boundaries are talking to two different kinds of unreliable.

The first protocol carries the UI-to-engine conversation. Its frame is a fixed six-byte header, four bytes of payload length in little-endian, one channel byte, one flags byte, followed by a JSON payload.

frame := make([]byte, frameHeaderSize+len(payload))
binary.LittleEndian.PutUint32(frame[0:4], uint32(len(payload)))
frame[4] = byte(ch)
frame[5] = 0
copy(frame[frameHeaderSize:], payload)

The header is binary because binary is cheap and unambiguous: read the first four bytes, you know exactly how many bytes the rest of the message is, and you take that many without ever inspecting a single character of the payload to find where it ends. The payload is JSON because JSON is easier to debug: when something goes wrong, you can read the message. Binary where it has to be fast, text where it can afford to be simple. That split runs through both protocols.

The frame carries a length, a channel, and a flags byte, and nothing else: no sequence counter, no framing metadata beyond what it takes to find the next boundary. The channel byte does the multiplexing, so control traffic and data traffic share one socket without stepping on each other. The flags byte is reserved: there's an enum declaring Compressed and Encrypted bits, but nothing sets them yet. It's a byte I designed room for and haven't spent, which is cheaper than a protocol change I'd have to make later to claw the room back.

The read side is where the "assume death" rule gets concrete:

std::vector<std::byte> header(6);
asio::read(_transport.socket(), asio::buffer(header), ec);
if (ec) break;

std::memcpy(&length, header.data(), 4);
if (length > MAX_MESSAGE_SIZE) break;

std::vector<std::byte> body(length);
asio::read(_transport.socket(), asio::buffer(body), ec);
if (ec) break;

Every failure is a break. A length that exceeds the cap is a break; the engine does not try to resynchronize because a corrupt length means the stream is no longer interpretable, and the only honest move is to stop. A truncated header is indistinguishable from an error and also breaks. There's no "half a frame" state here. When the loop exits, one line decides whether that exit was a death or a shutdown I asked for:

if (_connected.exchange(false)) {
    notify_error(Error::ConnectionLost);
}

The exchange is the anti-double-notify. If a clean stop() already set the flag to false, the exchange returns false, and the error handler never fires. It's the difference between "it died" and "I killed it," encoded in a single atomic swap.

The second protocol, I call it ZeriWire, carries the engine-to-runtime conversation, and it's a different animal because the far end is a different kind of fragile. It's a five-byte header (length plus a message-type byte, no channel, no flags) over the child process's stdin and stdout. And unlike the first protocol, its decoder is an incremental state machine:

case State::READ_PAYLOAD: {
    const size_t need = m_payloadLen - m_payloadPos;
    const size_t take = std::min(need, len - pos);
    std::memcpy(m_payload.data() + m_payloadPos, ptr + pos, take);
    m_payloadPos += take;
    pos += take;

    if (m_payloadPos < m_payloadLen) break;    // payload split across two reads

    ZeriFrame frame{ m_frameType, std::move(m_payload) };
    ResetState();
    SavePending(ptr, len, pos);                // bytes belonging to the next frame
    return frame;
}

Why the extra machinery? Because the first protocol reads from a socket where a blocking read fills the whole buffer or fails. ZeriWire reads from an anonymous pipe, where a read hands you an arbitrary 4096-byte chunk that has no respect for message boundaries. A frame can be split across two reads; two frames can arrive in one. The state machine is the price of that. And it needs no channels (the message type is the discipline), no version handshake, no PID check, because the engine launched this child itself. The first protocol exchanges a magic number and a version because its peer connected from outside and has to prove it's the right kind of stranger. ZeriWire's only handshake is a READY event that means "the bootstrap loaded," not "you are who you claim to be."

That's the whole reason for two protocols. A UI that connects is one contract. A child who can die mid-sentence is another. The protocols are shaped like the things they distrust.

Sidecars: every runtime is a process that can burn down alone

Each language runs as its own sidecar process. Python, JavaScript and TypeScript through Bun, Ruby, and Lua through LuaJIT, four isolated processes, each with its own memory and its own lifecycle. The engine is the pass: it calls the orders, times them, and handles the failures. Every station is a process, not a thread, and that distinction is the entire safety model.

The runtimes aren't bundled. They're discovered on PATH at startup, four lines, one per language:

addRuntime("lua", { "luajit" }, false, "luajit");
addRuntime("python", { "python3", "python" }, false, "python3");
addRuntime("js", { "bun" });
addRuntime("ruby", { "ruby" }, true);

No hardcoded paths, no vendored binaries — just names to look up. If a runtime isn't there, that language is marked unavailable and the rest carry on.

The "each station burns down alone" guarantee isn't a comment in the code; it's a system call. On POSIX, the engine forks and execs:

const pid_t pid = fork();
if (pid == 0) {
#ifdef __linux__
    prctl(PR_SET_PDEATHSIG, SIGTERM);
    if (getppid() == 1) _exit(1);
#endif
    dup2(outWrite.Get(), STDOUT_FILENO);
    dup2(inRead.Get(), STDIN_FILENO);
    // ... (omitted: close inherited fds, build argv)
    execvp(executable.c_str(), argv.data());
    _exit(127);
}

A SIGSEGV in Python3 is a SIGSEGV in Python3, full stop, the engine's address space isn't reachable from the sidecar, because the only channel between them is a pair of anonymous pipes. There's no dlopen("libpython") anywhere; nothing is loaded in-process. And the runtime can't outlive its parent: PR_SET_PDEATHSIG asks the OS to send the child a signal when the parent dies, while the getppid() == 1 check closes the race window where the parent dies between the fork and the death-signal setup. On macOS, the same result comes from a small daemon watching the parent for exit; on Windows, a job object with kill-on-close is created, where the child is created suspended and assigned to the job before it's ever allowed to run. Three platforms, one promise, no orphaned runtimes, ever.

Supervision is layered, and the timeouts are ordered on purpose:

inline constexpr std::chrono::seconds kLaunchHandshakeTimeout{ 5 };
inline constexpr std::chrono::seconds kWatchdogTimeout{ 30 };
inline constexpr std::chrono::seconds kExecuteCompletionTimeout{ 35 };

The outer timeout (35s) is strictly larger than the watchdog (30s). That ordering is the design; the outer layer only wakes up if the inner safety net has already failed. It's the safety net for the safety net. And when the watchdog does fire, it doesn't report an absence; it manufactures a synthetic result and hands it to the caller, so the layer above never has to know the answer simply never came. Death gets translated into a value.

There's an honest wrinkle here I'll own rather than hide. When a sidecar dies, it actually tries to say so; the Python bootstrap catches its own top-level exception and sends a CRASHED event on the way out. The engine, in this version, doesn't listen; the dispatch for that event only looks for READY, and everything else is dropped, which a comment in the code cheerfully admits. So the sidecar shouts, nobody's listening, and the watchdog quietly cleans up thirty seconds later. It works. It's not elegant. It's on the list.

And when a launch fails entirely, the engine degrades instead of erroring out; it falls back to one-shot execution, running the code in a fresh, short-lived process. You lose the persistent namespace for that runtime, not the functionality. A dead sidecar gets recreated on the next command, transparently, and the only cost to you is the variables that lived in that one process. Only that one.

SharedScope: the hub that owns the neutral copy

Back to the four cooks. The value that has to move between them can't live in any one language, so it lives in the engine, in a single canonical form that belongs to none of them. The engine is the hub. Each runtime is a spoke with its own namespace, and the spokes never touch each other; the only way a value gets from Python to Bun is through the engine. The store itself is unremarkable to look at:

std::map<std::string, AnyValue> m_sharedVariables;
mutable std::shared_mutex m_sharedMutex;

The interesting work is the translation at the boundary, and it happens in the engine, not in each sidecar. When a value comes in as JSON, it's normalized into a neutral representation, and the rules are readable line by line:

if (value.is_boolean())        return AnyValue(value.get<bool>());
if (value.is_number_integer()) return AnyValue(value.get<std::int64_t>());
if (value.is_number_float())   return AnyValue(value.get<double>());
if (value.is_string())         return AnyValue(value.get<std::string>());

if (value.is_array()) {
    std::vector<AnyValue> out;
    for (const auto& item : value) {
        const auto converted = JsonToAnyValue(item);   // recursion
        if (!converted.has_value()) {
            return std::nullopt;                        // one bad leaf
        }                                               // invalidates the whole container
        out.push_back(*converted);
    }
    return AnyValue(std::move(out));
}
// ... (omitted: object branch, same recursive shape)

Every integer collapses to a 64-bit int, every float to a double, strings stay strings, and arrays and maps are rebuilt recursively. The canonical form is a value that can hold exactly seven things: null, bool, int64, double, string, array-of-those, map-of-those. Nothing else can be constructed. And that recursive return std::nullopt is the property worth staring at: a dictionary with a nested array survives the trip if and only if every leaf inside it is representable. One member that isn't collapses the whole container to nothing. There's no partial success, no "I saved the parts I could." Either the value crosses the whole, or it doesn't cross.

Two decisions shaped this, and both are the "assume death" rule wearing different clothes.

The first is copy-by-value, not shared memory. GetShared returns by value; no overload hands back a reference, no GetSharedRef, nothing that could be mistaken for a live pointer into the hub. This is deliberate to the point of stubbornness. Four processes, four different garbage collectors, or in LuaJIT's case, its own, and a live reference across that boundary would be a promise none of the four could keep. The copy is the discipline. Pretending four separate processes share memory would be a lie engineered to crash later, so the system doesn't pretend.

The second is loud failure. If a value doesn't fit the supported set, the engine doesn't mangle it into something that looks fine; it refuses, and the set fails on the spot:

const auto converted = DeserializeAnyValue(message["value"]);
if (converted.has_value()) {
    runtimeState.SetShared(key, *converted);
} else {
    response["error"] = "Unsupported value type.";
}

That error rides back to the user's code and becomes an exception on the exact line that called set, not three steps later, wearing a disguise, in some unrelated function. Break loudly beats deliver-corrupt-quietly.

Except, and this is one of the lines I had to fix while writing this article, the rule had a hole in it, and the hole said the opposite of what the rule promised. The integer branch did value.get<std::int64_t>() with no range check. An unsigned integer above int64 max would get silently truncated, and one bigger still would quietly degrade to a float. It was the single place in the whole system that would hand you the wrong value without a word, the exact betrayal the loud-failure rule exists to prevent, sitting right in the middle of the mechanism that's supposed to enforce it. I found it setting a big number in Python and reading a different number back in JavaScript. The fix is boring: an out-of-range integer is now refused the same way a BigInt is, returns nothing, and raises on the line. The canonical set is still seven types. The rule now actually holds.

One last detail I like, because it shows the same data can warrant two different policies. When a shared value can't be serialized, the machine-facing list skips it silently, a lost entry, no trace. But the human-facing /shared list command shows it, marked <unsupported>. Same underlying value, two audiences, two honest answers: the machine gets a clean list it can consume, the human gets the truth that something's wrong.

The AI layer, and where it deliberately isn't

Zeri has a local-LLM feature; you can talk to a model from inside the REPL. It's worth thirty seconds here purely because of where it lives, which is a clean example of the engine/frontend boundary holding.

The whole thing lives in the Go layer. The TUI builds an OpenAI-compatible request, streams the response back as UI events, and the C++ engine never sees a token, a prompt, or a reply.

req, err := http.NewRequestWithContext(ctx, http.MethodPost,
    target+"/v1/chat/completions", bytes.NewReader(body))

There's one honest caveat. The engine isn't totally ignorant of the feature: it stores and serves the AI settings, endpoint, model and key, because the engine owns persistence and the UI has no store of its own. So the division is precise, the UI knows how to talk to the model, and the engine knows where the keys are. The engine holds the configuration and never once uses it. It's the tidiest possible version of "not my job."

Yuumi, and why the protocol got its own name

The UI-to-engine protocol, the framing, the transport, the handshake, the bridge, is factored out into its own thing, called Yuumi. Inside the repo, it's a separate build target on the C++ side and a separate package on the Go side, with one property that matters, the dependencies only point one way. Nothing under Yuumi includes anything from Zeri. Yuumi does not know Zeri exists; it transports and it doesn't understand. The bridge hands up a raw, uninterpreted map and lets the layer above decide what any of it means.

That discipline, the seam being real, not aspirational, is what later made it possible to spin the idea out into a project of its own. I'm not going to oversell that here. The point for this article is narrower and more useful: drawing a boundary strictly enough that one side genuinely can't reach into the other is what lets you eventually lift that side out. The isolation wasn't for show. It was the thing that made the piece separable.

The one idea, again

If you've read this far, you've seen the same decision made in five different places. The two-process split contains a crash. The two protocols each distrust a different kind of peer. The sidecars burn down alone. Copy-by-value refuses to fake a shared memory that four processes couldn't honor. Loud failure refuses to hand you a value it isn't sure about, and where it quietly did anyway, that was a bug, and now it doesn't.

None of this makes Zeri important. It's still a REPL that went looking for a problem architecture-first, and the companion article is honest about what that cost. But the architecture itself has one spine, and the spine is a single sentence: assume the other side can die, and design the seam so that when it does, nothing lies to you about it. Everything else in this system is a consequence of taking that seriously.

If you want the why, why build this before anyone asked, that's the other article. This was how. If you want more information about the project or some aspects of the code in particular, I am open to further explanations.