Wiki · Architecture & Decisions
ADR-0002 — Verdicts are authored by the Control Plane and projected by Gaia, never computed by Gaia
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
Gate status in the flagellum repository is hand-written prose in nine files, and it has drifted. H-AIF-G7 is recorded NOT RUN at hierarchical-aif/docs/H-AIF-GATES.md:15 and EXECUTED — NOT_ESTABLISHED at hierarchical-aif/ledgers/HIERARCHICAL-AIF-GATE-TO-EXISTING-P-LADDER-MAP.md:53. G5 and G6 disagree likewise.
The obvious fix — have one component compute gate status from receipts so it cannot drift — was proposed in an earlier draft of this architecture, assigned to Gaia.
That proposal violates GAIA LAW. From docs/GAIA.md §1: "Gaia shows ONLY direct signals with provenance. It NEVER summarizes, represents, editorializes, scores, ranks, narrates, or authors a verdict." §6(b) makes count, sum, avg, percent, score, rank, total, ratio and any Gaia-authored verdict a build defect caught mechanically by gaia_lint.cjs. §9: "derived-by-Gaia = FORBIDDEN."
The proposal would have been rejected by the system's own linter.
Decision
- The Control Plane authors every verdict and writes a receipt.
- Gaia projects both the authored verdict and its receipt verbatim, with a provenance triple, adding nothing.
- When a document and a receipt disagree, Gaia emits a drift signal —
{a, b, relation, equal}with both byte-sets carried verbatim, no severity, no diff-percent, no judgment. - The Control Plane resolves the drift. Gaia reports it and never resolves it.
A source's own computed verdict carried verbatim is projection, not derivation, and is allowed — a gate row's PASS|PARTIAL|FAIL|WITHHELD|PENDING travels with its source as locator.
Consequences
Positive. Gaia stays lint-clean and keeps its value as an independent witness. Drift becomes visible rather than silently reconciled — docs/GAIA.md §9 names doc-vs-code drift as something Gaia must surface. Every receipt Gaia projects must be shaped so no field requires Gaia to compute anything, which forces the Control Plane to emit complete records.
Negative. Drift is surfaced but not auto-fixed; a human decision is required to reconcile. This is intentional — an auto-reconcile is exactly the "apparent harmony" the truth contract forbids.
Alternatives considered
Gaia computes the authoritative gate register. Rejected: forbidden by GAIA LAW, and mechanically rejected by gaia_lint.cjs. Would also destroy Gaia's independence — a witness that computes the thing it reports is no longer checking anything.
A tenth prose file holding the "real" status. Rejected: that is the disease, not the cure.
Auto-reconcile the stale document to match the receipt. Rejected: silently rewriting a disagreement is the failure mode the drift signal exists to prevent.
Falsifier
Any Gaia-emitted count, percent, rank, rollup or verdict that Gaia itself derived. gaia_lint.cjs must fail the build on a summarizing fixture before any new Gaia seat is added — that red test is a required step in the build sequence.
Amendment 1 — both sides of a drift signal must be the same kind and the same normalization
- Status: Accepted
- Date: 2026-07-26
- Deciders: Michael (co-sign), Veritas, Custos
- Occasioned by: "address all drift" — and the discovery that most of it could not be addressed, because most of it could not converge.
Context
Decision 3 above says a drift signal carries {a, b, relation, equal} with both byte-sets verbatim. It never said what a and b must be. They turn out, in practice, to be different kinds of thing — and a signal comparing a sentence to a filename cannot reach equal: true in any state of the repository. It is not measuring drift. It is reporting a category error, forever, in the vocabulary of a measurement.
Measured live at 127.0.0.1:8096/api/gaia, 2026-07-26T16:05Z, ten drift signals:
| signal | side a |
side b |
can it ever be equal? |
|---|---|---|---|
drift.fqdn_cjs |
a prose line from CLAUDE.md |
a filename, or "" |
no — prose vs path |
drift.gate_row_schema_path |
a prose line fragment | production/schemas/gate_row.schema.json |
no — prose vs path |
drift.resolver_planned |
"dnsmasq (planned)", 17 bytes |
a JSON array of 21 live tracking rows | no — label vs array |
drift.self_caps_doc_vs_served |
a CAPS JSON blob | the whole of GAIA.md, 54 KB of markdown |
no — JSON vs a document |
drift.replica_ledger.* (×3) |
sha256 of mixed-EOL working-tree bytes |
sha256 of all-CRLF bytes after git archive | tar -x |
no — same type, different normalization |
drift.control_plane_anchor_git |
anchor object | anchor object | yes — and it is equal: true today |
drift.git_dirty_vs_clean |
"" |
git status --short output |
yes — and it is equal: true today |
That table is the whole argument. The two well-formed comparisons converged the moment the world became correct. The five malformed ones stayed red through a day of real corrections — a served schema pointer fixed, a resolver confirmed live, a working tree cleaned — and would have stayed red had every one of those corrections been perfect. The replica family is the sharpest case: even at zero lag the digests differ, because canonical is hashed from mixed-EOL working-tree bytes while the chip receives all-CRLF. Same 206 rows, same content, different digest.
The cost is not the red pixel. It is that an inequality nobody can act on stops being read. drift.git_dirty_vs_clean had been unequal for days, was filed as an accepted oscillation, and was therefore pointing — unread — at a committed receipt that its own commit could not reproduce (docs/receipts/control-plane/phase7_item76_receipt_correction_2026-07-26.md). A permanently-unequal signal is indistinguishable from a broken one, and both get ignored.
Decision
5. Both sides of a drift signal MUST be the same kind and the same normalization.
A comparison is well-formed only if equal: true is reachable — that is, only if some achievable state of the world makes the two byte-sets identical. Path against path. Object against object. Digest against digest computed the same way. Never prose against a path, never a label against an array, never a document against a JSON blob.
6. A signal whose inequality is structural is not a drift signal. Where two things legitimately differ forever — a deployment lagging its source, an anchor awaiting a co-sign that has not happened — that fact belongs in a signal with its own relation (lag, absent) whose equal is not the reading anyone acts on, and it must be classified, dated and signed rather than left to look like an unresolved fault.
7. Extracting a locator from a document is capture, not judgment. Pulling the cited path out of a prose line, so it can be compared against a path, is the same class of operation as grepFirst, which already runs a regex to find the line at all. equal stays a mechanical byte-compare. No severity, no verdict, no diff-percentage, no ranking. GAIA LAW holds: Gaia is still projecting what a source says, only now projecting the part of it that is comparable.
Consequences
Positive. A red drift signal becomes actionable again, which is the only reason to have one. The distinction between "this is wrong" and "these are different things" stops being invisible. And the corrections already made today become visible as progress — drift.gate_row_schema_path's side b moved from "" to the real schema path when the pointers were fixed, and the malformed comparison could not express that.
Negative. Repairing a comparison changes what the platform measures, and a changed measurement can be a way to make a problem disappear. That is why this required a co-sign and why Decision 8 exists.
8. Every repaired comparison must be proved to still bite — point its declared side at a bad value and watch equal go false — and the before/after signal state must be captured on both sides of the change. A comparison repaired without that proof is indistinguishable from a comparison loosened.
Alternatives considered
Leave them and record all five as permanently unequal. Rejected — it is what was already done, informally, in Phase 1, and it is how drift.git_dirty_vs_clean stopped being read while pointing at a live defect. STRUCTURAL must mean "unequal by construction and both sides independently verified true, on this date, by this command". It must never mean "unequal, stop looking".
Add a tolerance so near-matches count as equal. Rejected, and it is the most dangerous option on the list. For the replica family a tolerance would swallow the in-place-edit case — the only thing that family is for — in order to hide a lag that is deliberate and documented.
Delete the malformed signals. Rejected, and already mechanically prevented: verify_gaia.cjs:513-518 requires the hints fqdn, gate_row, resolver, git, self to exist. The ledger was armed against silent removal before this amendment was written.
Normalize line endings so the replica digests match. Rejected as a fix for this: it would change how the canonical ledger is stored in order to satisfy a comparison, which is the tail wagging the dog. The comparison is what is wrong.
Falsifier
A drift signal is added or retained whose a and b are of different kinds, or of the same kind under different normalization, such that no achievable state of the world yields equal: true — and which is not declared structural under Decision 6 with a relation that says so. Also falsified if a comparison is repaired without a mutation showing it still bites (Decision 8).
sha256 fe04d527e2894991 — of the original file, so what was ingested stays checkable.
Plain — written for this website, not the source document
A decision and a later amendment to it share this page. Both concern the part of the platform whose only job is to show signals.
The rule it fixes: the body that runs the science authors every verdict and writes its receipt — the file showing what was run and what came out. The reporting body carries both along verbatim, with a note of where they came from, and adds nothing. It may not count, score, rank, total or narrate. A tidier arrangement had been proposed — let that body work out gate status for itself — and the record turns it down, because it would break the body's own law.
When a document and a receipt disagree, the reporting body says so and stops. A person resolves it. Reconciling it automatically is exactly the apparent harmony the project's truth contract forbids.
The amendment came later, after ten of those disagreement signals were looked at live. Most compared things that were not the same kind — a sentence against a filename, a label against a list — so they could never agree in any state of the world. The amendment requires both sides to be the same kind, and requires a repaired comparison to be shown to still bite.
Plain · written 2026-08-01 by claude-opus-5 · not yet checked by a person · about the document whose sha256 is fe04d527e2894991
Clear — written for this website, not the source document
Two dated notes are stacked here: a decision, accepted, and a later amendment appended below it. Together they govern what the platform's signal-reporting body may and may not do.
The context for the first decision is drift. Gate status in one repository was hand-written prose spread across several files, and the same gate was recorded two different ways in two different places. The obvious fix — have one component work out gate status from the receipts, the files recording what was run, so it cannot drift — had been proposed and assigned to the reporting body. The record shows that this would have broken that body's own law, which says it shows only direct signals with a record of where each came from, and never summarises, scores, ranks, narrates or authors a verdict. The proposal would have been rejected by the system's own linter.
So the decision reads as follows. The body that runs the science authors every verdict and writes a receipt. The reporting body projects both verbatim, with a three-part note of where each came from, adding nothing. When a document and a receipt disagree, it emits a drift signal carrying both byte-sets verbatim, with no severity, no percentage and no judgment. And the body that runs the science resolves the drift; the reporting body reports it and never resolves it. A source's own computed verdict, carried unchanged, counts as projection rather than derivation, and is allowed.
The stated cost is that drift is surfaced but not fixed automatically, so a human decision is needed. The record says this is intentional.
The amendment is the more interesting half. Ten drift signals were measured live, and most of them turned out to compare things of different kinds: a prose line against a filename, a short label against a list of tracking rows, a small blob against a whole document. Two of them were well formed, and both reached agreement the moment the world became correct. The malformed ones stayed red through a day of real corrections and would have stayed red even if every correction had been perfect. One family compared digests — short fingerprints computed from the bytes — taken the same way but over differently-normalised copies, so even with no lag at all the digests differ.
The record is clear about why this matters, and the reason is not the red pixel. An inequality nobody can act on stops being read. One such signal had been unequal for days, was filed as an accepted oscillation, and was therefore pointing — unread — at a real defect.
So the amendment requires that both sides of a comparison be the same kind and the same normalisation, and that agreement be reachable in some achievable state of the world. Where two things legitimately differ forever, that belongs in a signal with its own relation, classified, dated and signed, rather than left looking like an unresolved fault. Pulling a cited path out of a prose line so it can be compared with a path counts as capture rather than judgment, and the comparison stays a mechanical byte-compare.
The amendment also names its own danger: repairing a comparison changes what the platform measures, and a changed measurement can be a way to make a problem disappear. So every repaired comparison must be shown to still bite — point it at a bad value and watch it go unequal — with the signal state captured before and after. A comparison repaired without that proof is indistinguishable from a comparison loosened.
Clear · written 2026-08-01 by claude-opus-5 · not yet checked by a person · about the document whose sha256 is fe04d527e2894991