BigBrain · what holds the repos together
One registry, and nothing faked.
The system is split across many repos that load each other's code. A small control plane outside all of them holds what is true about the machine rather than about any one repo: where each repo lives, which repo may reach into which, and the checks that fail loudly when either drifts.
The system is spread over many separate code folders that borrow from each other. One small shared folder keeps track of where each one lives and which may borrow from which, and runs checks that complain loudly when something is out of place.
The registry: one place a path is written
One file lists every repo: where its checkout lives, its project and its services. No repo writes another repo's path anywhere else.
One file lists every code folder and where it lives. No folder writes down where another one is.
- Code reaches a sibling through a small library that looks the path up.
bb.pathandbb.loadthrow when the repo is unknown or its checkout is missing.Code asks the shared library where another folder is. If the folder is unknown or missing, it stops with an error. - Adding a repo is a hand edit, then a restart. The long-running worker reads the registry once at boot, and the doctor fails while the worker is serving an older copy.A new folder is added to the list by hand, then the service restarts. A check fails until the running service has the new list.
Declared edges
Every place one repo reaches into another is listed as an edge, so the couplings can be re-checked continuously instead of remembered.
Every time one folder borrows from another, that link is written in a list, so it can be checked again and again.
- A lint fails on any relative path that leaves the repo without a matching edge. That is what stops the split rotting back into
../../.A check fails on any shortcut into another folder that isn't on the list. - The doctor walks every declared edge and fails when its target file is gone.Another check confirms that everything on the list still exists.
A missing sibling is loud
Before the split, cross-repo requires sat in try/catch blocks that fell back to a stub. The smart-home adapter fell back to an in-memory mock, so the lights could stop working while the health check still reported green.
Code used to quietly swap in a fake when a piece it needed was missing. Once, the smart-home part did this, so the lights stopped working while every status check still said all was well.
- The default,
bb.load, throws.Normally, a missing piece stops the program with an error. bb.loadOptionalis the only soft path. It returns null and registers a degradation that prints at startup, appends to the event log and turns the health check non-200 while it lasts.Where a piece really is optional, its absence is printed, logged and shown as a failing status check until it is fixed.- There is no third option: a
try { require } catch { return stub }is never written.Swapping in a quiet fake is never allowed.
The doctor stays at zero failures
bb doctor runs every machine-wide check in one pass and must report zero failures. A warning gets noted; a failure is fixed before other work.
One command runs every machine-wide check. It must always report zero failures, and a failure is fixed before anything else.
- It checks that the registry the worker serves is the one on disk, that every edge resolves, and that no credential is set to two different values.It checks that the running service has the latest list of folders, that every borrowing link works, and that no password is saved with two different values.
- It checks that the shared files each repo carries match the control plane's copy byte for byte, and runs every repo's conformance test.It checks that copies of shared files have not drifted, and that every folder still passes the code standard below.
One full suite at a time
Agents work in parallel on one machine, and full test suites that ran side by side collided and timed out. bb suite puts every full run into one machine-wide slot, in arrival order.
Many AI helpers share one computer. When several ran the full set of tests at once, the runs got in each other's way, so now they line up and take turns.
- A holder that died is cleared by whoever notices, by process id and start time. A nested call sees the slot is already held and runs straight through.If a run crashes while holding its turn, the next one in line clears it.
- Test counts are read from each runner's own output. A count that cannot be read is an anomaly and fails the run; it is never taken as zero tests.The number of tests that passed is read from each run. A number that can't be read counts as a failure, never as zero.
Why full runs moved to one per wave of tickets is on Practice.
How the owner fits test runs into the work is on Practice.
The code standard
A fresh agent with one ticket and no memory must find a repo's domains, interfaces, features and errors from the tree alone. These practices say what that means. Each repo carries the same conformance test, copied verbatim from the control plane, so the rules are enforced by tests rather than by a lint, a hook or CI.
An AI helper starts every ticket knowing nothing about the code. These rules make each folder easy to find its way around, and every folder runs the same test that checks them.
- Structure reveals domains
ls srcnames the domains, one folder each; itsindexis the public surface.Folder names say what the code is about. - Interfaces are declaredTyped
.tssources run on Node's native type stripping, with no build step, andnpm testtypechecks.Code states what it expects, and the tests check it. - Errors are a taxonomyOne errors module per repo, with coded classes carrying a code, domain and HTTP status. No bare
throw new Error.Every error has a name and a code, so it can be looked up. - Features are registriesRoutes, jobs, commands, events, env vars, errors and screens are exported data, rendered to a doc that a test fails on when stale.Each folder keeps one list of everything it does, and a test fails if the written copy falls behind.
- Knowledge is executableScripts, doctor checks and tests instead of written procedures. Counts and measurements come from tests, never prose.Steps are scripts and checks, not instructions to follow by hand.
- Context files are mapsThe agent file is a short page of pointers and invariants, the README is install and use, and rationale still in force is a short decision record.The notes for AI helpers point to where things are rather than explaining everything.
- Conventions are enforced by testsEvery rule a repo adopts is an assertion in its conformance test.A rule that matters is a test, not a reminder.
- Changes are localA feature touches one domain folder and its tests. A comment cites a ticket only for a rule still in force.A change stays in one area of the code.
- One entry point per action
start,test,registryand, for servers,restartare each one npm script.Each everyday task has one command. - Logs carry a domain tag
log(domain, event, fields): one line per event, greppable by domain.Every log line says which area of the code wrote it.
bb doctor --conformance runs every adopted repo's conformance test and names the repos that have not adopted it yet.
One command runs the standard's test in every folder and lists any folder not yet using it.
Paths, hostnames, names and figures taken out.
Private details have been taken out.