Wiki · Architecture & Decisions
ADR-0005 — The flagellum's CPU-only rendering fence does not bind the lab
How to read this page
Three ways to read this page. Precise is the document itself, exactly as it is written in the repository. Plain and Clear were written for this website to help you meet that document — they are about it. They are not it, and they are not evidence.
This is the design record of the part of the estate whose job is to stop the rest of it claiming more than it has measured. It runs to architecture notes, numbered decision records, phase plans, and the results written after each phase ran.
It is for anyone curious how a decision was actually reached — what was considered, what was refused, and what the refusal cost. The decision records are the most durable part: each names one choice, the alternatives, and the consequence accepted in exchange. The failure-modes page is worth the detour, because it states each refusal as something you could go and test rather than as a promise.
Read the architecture page first. It opens by declaring itself part design and part built, which sets the tone for the whole section. Then the first decision record, then whichever phase interests you — read as a pair, the plan and the results page written afterwards, including the phases where a premise turned out to be wrong and the receipt says so.
What it is not: a description of running software, and not a complete record. Three documents from this area were withheld from publication, because they describe private infrastructure or the operator declined them; they are listed as withheld rather than quietly dropped, so you can see that they exist.
Your browser cannot switch reading levels, so the document itself is shown.
Precise — the source document
This is the document. Rendered from the repository at the commit above, with nothing rewritten for the web. A gate re-renders it on every deploy and fails the build if a single byte differs.
- Status: Accepted
- Date: 2026-07-25
- Deciders: Michael, Veritas, Custos
Context
CLAUDE.md in the flagellum repository states the released product "must remain CPU-only and must contain no LLM inference, GPU computation, WebGL, WebGPU, Three.js, analytics, accounts, or hidden network calls."
An earlier draft of this architecture applied that sentence to the whole platform and concluded that all biological visuals must be SVG or Canvas 2D, and that a rendered lab was forbidden.
That was a scope error. The sentence governs one project's released product. The platform it sits on already renders in THREE with shadows and ACES tone mapping on an NVIDIA T1000 — ui/priv/static/world.js is described in its own header as "a game-quality 3D god-view", and the broadcast path is explicitly GPU-composited.
Decision
The fence is scoped to the artifact it names.
- The flagellum released product remains CPU-only, no WebGL, no GPU, no accounts, no network. Unchanged, and enforced by its own tests.
- The lab view may render fully — WebGL, GPU, shadows, tone mapping — because it is the operator's instrument on THINKER, not a published CPU-only artifact.
- The flagellum's portal inside the lab renders like any other portal, while the product behind it keeps its own build constraints. The portal shows that product; it does not relax it.
Consequences
Positive. The lab can be the immersive environment the mission needs without weakening any published claim. Each artifact carries the fence it actually earned.
Negative. Two rendering regimes exist in one platform, so a contributor must know which artifact they are touching. Mitigated by the flagellum's own airtight build test, which fails if a forbidden runtime path enters its bundle.
Alternatives considered
Apply CPU-only everywhere. Rejected: it forbids the lab the operator requires, and imposes on the platform a constraint that exists to make one published scientific product independently reproducible on any machine.
Drop the flagellum fence to unify. Rejected outright. That fence is a released-product guarantee and a claim-integrity control; loosening it to simplify an internal tool trades evidence for convenience.
Falsifier
A GPU, WebGL, network or account dependency appearing in the flagellum released build. Its existing airtight build test is the mechanical check and must stay green.
sha256 616a0907c9b49f00 — of the original file, so what was ingested stays checkable.
Plain — written for this website, not the source document
A scope error is the whole subject here, and this short dated record corrects it.
One project in this estate — the flagellum — promises that its released product stays plain: no graphics hardware, no accounts, no hidden network calls. An earlier draft of the architecture read that promise as binding on everything, and concluded that a rendered lab was forbidden.
This record says that reading was wrong. The promise governs the one artifact it names, not the whole platform. So the released flagellum product keeps its constraints, enforced by its own tests. The lab may render fully, because it is the operator's instrument rather than a published artifact. The flagellum's doorway inside the lab renders like any other doorway, while the product behind it keeps its own build rules — the doorway shows that product, it does not relax it.
The cost is stated: two rendering regimes now exist in one platform, so a contributor has to know which artifact they are touching. What would show this wrong is a forbidden dependency turning up in the flagellum's released build.
Plain · written 2026-08-01 by claude-opus-5 · not yet checked by a person · about the document whose sha256 is 616a0907c9b49f00
Clear — written for this website, not the source document
The boundary of a rule, and nothing else, is what this short dated decision record settles.
The context: one project's contract says its released product must stay free of a named list of runtime dependencies — no graphics hardware, no accounts, no hidden network calls. An earlier draft applied that sentence to the whole platform and concluded that all biological visuals had to be flat drawings and a rendered lab was not allowed. The record calls this a scope error, and gives its reason. The sentence governs one project's released product. The platform underneath already renders with shadows and tone mapping on real graphics hardware, and composites the broadcast path that way on purpose.
The decision scopes the fence — a written line the project may not cross — to the artifact it names. The released flagellum product is unchanged and stays as constrained as before, enforced by its own tests. The lab view may render fully, because it is the operator's instrument on one machine rather than a published artifact. The flagellum's portal inside the lab renders like any other portal, while the product behind it keeps its own build constraints — the portal shows that product without relaxing it.
The consequences run both ways. In favour: the lab can be the immersive environment the mission asks for without weakening any published claim, and each artifact carries the fence it actually earned. Against: two rendering regimes now exist inside one platform, so a contributor has to know which artifact they are working on. The record says this is reduced by the flagellum's own build test, which fails if a forbidden runtime path enters its bundle.
Two alternatives were rejected. Applying the strict rule everywhere would forbid the lab the operator asked for, and would impose on the whole platform a constraint that exists so one published scientific product can be reproduced independently on any machine. Dropping the flagellum's fence to make everything uniform was rejected outright: that fence is a released-product commitment, and loosening it to simplify an internal tool trades evidence for convenience.
What would show this wrong is concrete: a graphics, network or account dependency appearing in the flagellum's released build. The existing build test is named as the mechanical check.
Clear · written 2026-08-01 by claude-opus-5 · not yet checked by a person · about the document whose sha256 is 616a0907c9b49f00