# The semantics of `attest` and `climb` **What this is.** A description of *what the two governance operations compute*, written so that someone who has never read this project's Python can build them in any language and be right — including on inputs nobody thought to write down. **Why it exists.** Until now this project published an *answer key*: 23 questions with the expected answers beside them (`CONFORMANCE_SPEC.json`). Jens Egholm Pedersen (DTU), whose Neuromorphic Intermediate Representation the idea was borrowed from, read it on 2026-09-15 and named the flaw: a test-vector suite pins the computation only where it samples, and no number of vectors converts a suite into a specification. His prescription was to write the specification of the two operations instead. This is that. See `KNOWN_ISSUES.md` A121 and `CORRECTIONS.md`. **Status: normative.** Where this document and the implementation disagree, **one of them is a defect and the disagreement is a finding worth reporting.** This document was written *from* the implementation, so the likely defect is here — but it is checked mechanically by `test_r2_semantics.py`, which compares an implementation written only from this text (`spec_reference.py`) against the live one over **every input in a bounded space**, not over samples. **This document describes; it does not decide.** Nothing here is new behaviour. Where the implementation makes a choice that looks arbitrary, it is recorded as it is, and marked. --- ## 0. Values and vocabulary | term | meaning | |---|---| | **root** | An opaque string. Nothing in either operation inspects, parses or orders roots by content except for **equality** and, in one tie-break, **byte ordering**. A root is never hashed, truncated or combined here. | | **absent** | A root that is `null`, or the empty string, or any value the host language treats as false. Absent means *this witness did not answer*. | | **witness** | A name (string) paired with a root or with absence. | | **verdict** | Exactly one of `AGREE`, `DIVERGED`, `UNPROVEN`. | **Sorting.** Every sorted list in this document is sorted **ascending by the sequence of Unicode code points** of the string, with no locale, case folding or normalisation. **The founding distinction, which the rest of this document exists to protect:** > **A witness that did not answer is not a witness that disagreed.** Collapsing those two makes an unreachable witness read as agreement among the rest. --- ## 1. `attest` ### 1.1 Input A mapping of **witness name → root or absent**, in which names are unique; and an **optional quorum**, a whole number. ### 1.2 Output A record with at least these fields. Other fields may exist; they are explanatory and carry no meaning a second implementation must reproduce. | field | type | |---|---| | `verdict` | `AGREE` \| `DIVERGED` \| `UNPROVEN` | | `agreed` | boolean — true **only** for `AGREE` | | `quorum` | the quorum actually applied | | `answered` | sorted names of witnesses whose root is present | | `silent` | sorted names of witnesses whose root is absent | | `reference` | the agreed or plurality root **in full**, or null | | `outliers` | sorted names of witnesses differing from `reference`, or empty | ### 1.3 Procedure **Step 1 — partition.** `answered` = sorted names with a present root. `silent` = sorted names with an absent root. Every witness is in exactly one. **Step 2 — quorum.** If a quorum was supplied, use it **unchanged**, including values that are zero, negative, or larger than the number of witnesses. A caller that knows its own topology outranks the default. Otherwise the default is ``` quorum = max(2, floor(N / 2) + 1) where N = the number of witnesses ASKED ``` `N` counts **every witness in the input**, answered and silent alike. Three things follow, and each was a defect that was fixed: - Not a constant. With a constant of 2, two witnesses out of a hundred establish agreement for all hundred — a claim far stronger than its evidence, and a route for a small colluding subset to speak for everyone. - Not a majority of *those present*. That would mean **silencing witnesses makes agreement easier**: knock enough offline and the survivors clear a lower bar. A mechanism in which a party gains by suppressing others is the transaction this project exists to refuse. Silence may only ever make a verdict **harder** to reach. - A floor of 2, derived rather than chosen. A pure majority gives `floor(1/2)+1 = 1` for a single witness, so a lone witness would AGREE with itself. One implementation agreeing with itself is not agreement. **Step 3 — tally.** Group the answering witnesses by their root: each distinct root maps to the sorted list of witnesses holding it. **Step 4 — rank.** Order the distinct roots by **descending holder count**, and among equal counts by **ascending root string**. This ordering affects the outcome only through step 5's comparison of the top two counts; it never picks a winner by itself. **Step 5 — reference.** There is a reference **only if all** of: 1. the quorum is met — `count(answered) >= quorum`; **and** 2. at least one root was answered; **and** 3. either there is exactly one distinct root, **or** the highest-held root has **strictly more** holders than the second — a *strict plurality*. Otherwise `reference` is **null**. > **On a tie for top there is no reference and no tie-break is invented.** Choosing between > equally-held roots is a *decision*, and this operation reports evidence and decides > nothing. Earlier code took the first-ranked root unconditionally, which made a witness's > root the reference by nothing but the alphabet. **Step 6 — outliers.** If there is a reference, `outliers` is the sorted list of every answering witness holding a root **different from** it. If there is no reference, `outliers` is **empty** — an outlier is a witness that differs *from a reference*, and where there is none the word names nothing. This applies to both reasons for having no reference: a tie, and a quorum not met. **Step 7 — verdict.** In this order; the first matching rule decides: | # | condition | verdict | `agreed` | |---|---|---|---| | 1 | `count(answered) < quorum` | `UNPROVEN` | false | | 2 | exactly one distinct root among the answered | `AGREE` | true | | 3 | more than one distinct root and `reference` is null | `DIVERGED` | false | | 4 | otherwise (more than one root, strict plurality exists) | `DIVERGED` | false | Rule 1 precedes rule 2: a quorum that was not met is `UNPROVEN` **even if every witness that did answer held the same root.** Nothing was compared, and that is not agreement. ### 1.4 Consequences a second implementation must reproduce - **No witness with zero witnesses.** An empty input yields quorum 2, zero answered, therefore `UNPROVEN`, `reference` null, `outliers` empty. - `agreed` is true **exactly** when `verdict` is `AGREE`. - Whenever `verdict` is `AGREE`, `reference` is the single root held, in full. - Whenever `verdict` is `UNPROVEN`, `reference` is null and `outliers` is empty. - `reference` is published **in full, never truncated**. It is the one field meant to be *compared* rather than read; sixteen characters cannot be checked against anything. Its absence from earlier specifications meant an implementation returning a hardcoded constant upward would have passed every test in this repository. --- ## 2. `climb` `climb` reduces a tree of nested levels to a pair: **the root this level speaks to the level above** (or silence), and **a report**. ### 2.1 Input A **node**, which is either: - a **leaf** — a node with **no `children` key at all**; it may carry `name` and `root`; or - a **level** — a node with a `children` key, holding an ordered list of nodes; it may carry `name` and `quorum`. > A node whose `children` is an **empty list** is a *level* with no children, **not** a > leaf. It attests over nothing and is therefore `UNPROVEN`. The distinction is the > presence of the key, not the length of the list. A missing `name` is the literal string `?`. ### 2.2 Depth limit Levels are counted from 0 at the node first passed in. If a node is reached at depth **greater than 64**, it is **not** recursed into: it returns silence, and a report with verdict `UNPROVEN`. Nesting that deep is far more likely to be a cycle than a hierarchy, so it is refused rather than followed. > **Uniform with every other level report (A123, fixed 2026-09-15).** A refused level > judged nothing, and every field says so honestly: it answered nobody, heard nobody, has > no outliers, did not agree, and speaks silence. Until this specification was written the > over-depth report was a **third shape** — it omitted `answered`, `silent`, `outliers`, > `agreed` and `speaks_upward`, so a caller reading `speaks_upward` on a refused node > raised rather than reading false. Writing the rules down is what surfaced it: the > reference implementation filled the fields in, as every other branch does, and the > differential check reported the disagreement at depth 65 of a 66-level tree. No > conformance vector reaches this branch, so the published root is unchanged. ### 2.3 A leaf A leaf speaks **whatever it holds** — its own root, unchanged, or silence if absent. Its verdict is `AGREE` when it holds a root and `UNPROVEN` when it does not. Its `reference` is what it holds. A leaf has no divergences. ### 2.4 A level **Step 1 — descend, in order.** For each child in the order given, climb it. Record what it spoke under **the name in the child's own report**, and keep the child's report. > **Name collision:** if two children report the same name, the later one **replaces** the > earlier in the map of what was spoken, and the level attests over fewer witnesses than it > has children. The earlier child's report is still kept and its divergences still > propagate. This is recorded because it is the behaviour, not because it is desirable. **Step 2 — carry divergences upward first.** Every divergence from every child is carried into this level's list, in child order, **before** any divergence of this level's own. A divergence found eleven levels down is still named at the summit. Nothing filters, deduplicates, summarises or thresholds them. **Step 3 — attest.** Apply `attest` to the map of what the children spoke, passing this level's `quorum` if it has one and otherwise none — so that a level built by hand receives the same derived majority as one built by a helper. **Step 4 — this level's own divergences.** Only if the verdict is `DIVERGED`, append one entry **per dissenting witness** — never one per diverged level: - If there **is** a reference: one entry for each name in `outliers`. - If there is **no** reference (the tie case): one entry for each name in `answered` — every witness that answered is party to a split, and none holds a reference because there is not one. > A count of levels answers *where*, never *how many*: two dissenters in one level and one > in another would total the same. That is the "outvoted into invisibility" failure > happening at the tally instead of at the vote. Each entry also reports the **denominator** — the number of witnesses asked at that level, `count(answered) + count(silent)` — so that levels of different sizes are comparable. > **The proportion is never a threshold.** There is no fraction below which a dissent stops > counting. One dissenter in a hundred leaves the level `DIVERGED` exactly as one in three > does. **This reports the denominator; it never divides by it.** The text of an entry is explanatory and non-normative. **The number of entries is normative.** **Step 5 — what the level speaks upward.** ``` if verdict == AGREE: speak the reference, unchanged otherwise: speak silence ``` Two properties are load-bearing: - **Unchanged.** Not keyed by the level's name, and not wrapped in a per-level digest. Both were tried and both were wrong: the first meant three ledgers holding the same root produced three different values, so siblings could never agree about anything; the second made a level's value depend on its **height**, so a region three levels deep and a single ledger beside it could never agree. Passing the agreed root through unchanged makes height irrelevant — a federation of one node, one region and one whole country composes exactly as well as three identical nodes, because all any of them says is *the content is this*. **Who** said it is the tally's business, which is exactly why it does not belong in the value. - **Both failures speak silence.** `DIVERGED` and `UNPROVEN` alike speak nothing upward. Either one speaking its root would let a parent read *we could not establish this* as *we established this*. **Step 6 — distinguish the two silences.** A parent must be able to tell *my child disagreed internally* from *my child could not establish anything*. Of the children that spoke silence: - `silent_diverged` — sorted names of those whose own verdict was `DIVERGED`. - `silent_unproven` — sorted names of **all the others** that spoke silence. These partition the silent children, so no reader must choose which field to trust. Note `silent_unproven` is defined by *not* being `DIVERGED`, so a silent child of any other verdict falls here. **Step 7 — report.** The level's report carries its name, the verdict and `agreed` from step 3, `answered`, `silent`, `outliers` and `reference` from step 3, the two silence lists, the accumulated divergences, the child reports in order, the depth, and `speaks_upward` — true exactly when step 5 spoke a root rather than silence. ### 2.5 Clean A whole structure is **clean** only if **both**: 1. its divergence list is **empty**; and 2. its top-level verdict is `AGREE`. The first is the point. **A summit reporting `AGREE` over a hidden disagreement is the most dangerous output this system can produce, and it is what a naive implementation produces by default.** --- ## 3. What this specification does not do - It does not say a conforming implementation is **correct**. It says what it must compute. - It does not make either operation a consensus protocol. `attest` detects divergence, corruption and single-point compromise. It is **not Byzantine consensus** and calling it that would be a lie with a security label on it — witnesses under one hand are copies, not opinions. - It decides nothing and overwrites nobody. A divergence is reported and left standing. - It does not cover the rest of this project. These are two operations. ## 4. How it is checked `spec_reference.py` implements **only what is written above**, importing nothing from this project. `test_r2_semantics.py` runs it against the live `triangulate.attest` and `scale.climb` over a **bounded input space that is enumerated exhaustively** — every witness-count, every assignment of roots and silence, every quorum in range, and every tree shape within the bound — and requires agreement on all of them. That is the difference from the 23 vectors. Inside the bound it is not a sample; it is every point. Outside the bound it proves nothing, and the bound is printed with the result, because a claim about 40,000 cases and a claim about 23 are different claims and quoting one as the other is the failure this project keeps finding.