4,941 lines, then 69

What the 4,941 lines were

Our fleet is nineteen vertical operating systems on one shared shell, and all of them reach the database through a single shared file — the driver. By this summer that file measured — lines, and the honest description of its contents is: it was the first operating system. One vertical's boards, forms and business rules had accreted into the layer that was supposed to be neutral, because every time that OS needed one more thing, the shared file was where the plumbing already lived.

The cost was not performance and it was not readability. It was concurrency of people. We rebuild the fleet in parallel lanes — one lane per OS — and fourteen lanes editing one file is a fourteen-way merge conflict on every change. The monolith did not slow the code down; it slowed the organisation down to one lane at a time. That is the specific problem the rewrite had to solve, and it is worth being precise about, because it explains what got kept.

The cut

The question that decided every line was: which second caller exists? Fold one OS's rules into a shared layer and every rule looks shared — until you ask that question. Almost nothing had a second caller. What genuinely did was embarrassingly small: resolve which OS a call belongs to, and hand it the call.

So the driver became a registry. Each OS is one module that exports one object — its slug, its database schema, its storage bucket, its collections, its pages, its mutations. The driver loads the registry from the same OS map the shell and the guards read, so an OS cannot be half-registered, and dispatches. The shape, not the verbatim file:

// one module per OS; the OS map is the single registration point
const registry = {};
for (const slug of Object.keys(OS_MAP)) registry[slug] = load(slug);

function readCollection(os, name, ctx) {
  const m = registry[os].collections;
  if (!m || !m[name]) throw new Error(`no mapping for ${os}/${name}`);
  return m[name](ctx.providerId, ctx);   // provider scope is argument one, always
}

Today that registry file measures — lines. The deleted behaviour was behaviour with no second caller — which is a polite way of saying the shared layer had been hoarding things that were never shared. Nothing was rewritten into cleverness; it was mostly moved to the one OS that owned it, or deleted because not even that OS used it any more.

The seam, and why it exists

Some weeks later a second surface arrived — a phone app for crews, deliberately built without the desktop shell, because a dense 240-pixel sidebar has no business on a phone. It needed the same twenty lines of REST plumbing the driver used. The alternative to sharing them was a second copy, and the gotchas in those twenty lines are exactly the kind that drift apart between copies. So they were extracted into a seam file — — lines — that both surfaces import.

Three of those gotchas, because they are the real content of the seam:

• A bodyless request must not claim a body type. The storage API answers 400 to a DELETE that says Content-Type: application/json and carries nothing. That one once cost us a purge run — the header is only set when a body exists.
• The REST layer selects a Postgres schema per request by header — one header name on reads, a different one on writes. Cross them and the failure says relation does not exist, which mentions neither schemas nor headers. More on why schemas at all in One database, nineteen worlds.
• A non-2xx becomes an exception carrying the status and the first two hundred characters of the body. “The database said no” with no detail is not an error message, it is a debugging session.

What stops it growing back

Nothing about a split is self-enforcing. The first lane that needs “just one more thing” in the shared file recreates the exact condition the split removed — and it will look reasonable in review, because one function is not a monolith. Twelve lanes doing it is. So the boundary is a CI guard, not a convention.

The guard checks the half that fails silently hardest: mutation verbs. These used to live in one flat table — stock-save, document-save, crew-add. On a flat table, when a second OS defines a verb the first already uses, the later definition wins, both lanes' tests pass, and the bug ships as one vertical's booking mutating another vertical's stock in production. Verbs are now namespaced per OS, which makes that bug unrepresentable — and the guard is what proves the namespacing is still real on every test run. The full set is in Ten guards, ten scars.

One number is deliberately boring now: adding the twentieth OS adds roughly one line to the shared layer — its registry entry. That is the whole point.