dd1410c266
The published line and the local line of this repository had no common ancestor: the public one carried the hygiene pass (no host names, no internal paths), the local one carried a month of corrections that never shipped. This commit ports the local work onto the public line, keeping the public hygiene wording wherever the two touched the same sentence, and keeping the public version of AERE-CROSS-CLIENT-DETERMINISM.md entirely. Carried: LICENSE/LICENSING corrections, VERIFY-POLICY.md, CITATIONS-UNRESOLVED.md remeasured 2026-08-11, the 'audited' adjective removed from next to Bouncy Castle, citation paths rewritten to published form, AIP-8, the QA consolidation report, the second EIP validation pass, fork-height corrections, the AereSink / threshold-factory correction, the forge test floor, and the architecture-map updates.
118 lines
6.6 KiB
Markdown
118 lines
6.6 KiB
Markdown
# The `[VERIFY]` marker: what it means in this repository
|
|
|
|
**Status:** normative for every Aere Network repository published on `git.aere.network`.
|
|
**Written:** 2026-08-03. Supersedes the earlier wording that described these markers as items
|
|
"for a human to confirm before publication".
|
|
|
|
---
|
|
|
|
## The rule, in one paragraph
|
|
|
|
A `[VERIFY]` or `[VERIFY: ...]` marker is a **permanent, deliberate disclosure that one named fact
|
|
is NOT MEASURED**. It is published exactly as it stands. It does not block publication. It is closed
|
|
in exactly one way, by a measurement that settles the named fact, and the closing measurement is
|
|
written down next to it. **A marker is never closed by deleting it**, and it is never closed by
|
|
softening the sentence around it.
|
|
|
|
## Why the earlier wording was wrong, and how
|
|
|
|
Three documents in this bundle used to say that these markers were flags "for a human to confirm
|
|
before publication" or "before publishing":
|
|
|
|
- `AERE-EIP-COMPATIBILITY-MATRIX.md`, the "How to read this" list and the open-flags heading
|
|
- `AERE-NIST-VALIDATION-STATUS.md`, the Appendix A heading and one marker body
|
|
- `AERE-PROTOCOL-SPECIFICATION.md`, the honesty conventions list and the Section 11 register heading
|
|
|
|
That sentence was not true. These repositories were published on 2026-07-20 with **263** exact
|
|
`[VERIFY]` markers still open across **83** files (measured 2026-08-03 against the published trees,
|
|
not against a working copy). A document that says its unknowns will be resolved before publication,
|
|
and is then published with the unknowns in place, asserts more than was done. That is the same class
|
|
of defect the markers exist to prevent, one level up: **the honesty convention itself was making an
|
|
unmeasured claim.**
|
|
|
|
The repair was to make the text match the practice, not to make the practice match the text. Deleting
|
|
243 disclosures so that a grep would come back empty would have removed real information from readers
|
|
and replaced an honest document with a quiet one.
|
|
|
|
## Why publishing open unknowns is the right choice here
|
|
|
|
This is the same reasoning already recorded in `KNOWN-ISSUES.md` in `aere-contracts`, where our own
|
|
test suite's findings are published deliberately, with status attached. Publishing a finding is
|
|
useful. Publishing it with no status was the oversight, and the fix was to add status, not to remove
|
|
the finding.
|
|
|
|
The prior art we followed is the Rust RFC process, where every RFC carries a mandatory
|
|
"Unresolved questions" section, so the unknowns of a design are an enumerated, permanent part of the
|
|
published document rather than something that disappears at publication time
|
|
(`https://github.com/rust-lang/rfcs/blob/master/0000-template.md`).
|
|
|
|
The prior art we deliberately did **not** follow is the common docs-CI habit of failing a build on
|
|
the literal string `TODO` (for example a Vale `existence` rule at `level: error`,
|
|
`https://docs.vale.sh/topics/styles`). That rule is right for a marker that means "I have not
|
|
finished writing this sentence". It is wrong for a marker that means "this fact about a live chain
|
|
has not been measured", because the only thing it can force is deletion, and deletion here is a lie.
|
|
It is worth noting that GitLab, which runs one of the more thorough public documentation pipelines
|
|
(Vale, markdownlint, link checking, Mermaid validation), does **not** gate on placeholder markers at
|
|
all (`https://docs.gitlab.com/development/documentation/testing/`).
|
|
|
|
## What is actually enforced
|
|
|
|
The guard is `aerenew/scripts/deschise/flaguri-verify.cjs` in the private working repository. It is
|
|
not a marker ban. It checks four things, and it distinguishes "measured and wrong" from
|
|
"could not measure":
|
|
|
|
1. **No document may promise that markers are closed before publication.** The forbidden phrasings
|
|
are matched across line breaks, because a sentence split by a line wrap is the same sentence.
|
|
2. **Every published repository that carries at least one marker must carry this file at its root.**
|
|
A marker whose meaning is only defined in some other repository is undefined for the reader who
|
|
found it.
|
|
3. **The count is tracked, never asserted.** Markers are counted in both forms, `[VERIFY]` and
|
|
`[VERIFY: ...]`, and compared against the recorded snapshot below. Silent drift fails.
|
|
4. **The published surface is measured over the network, not from disk.** A working copy is not
|
|
evidence about what the world can read. If the network cannot be reached, that half of the
|
|
measurement reports NOT MEASURED and never reports green.
|
|
|
|
## Recorded snapshot
|
|
|
|
This file is excluded from every count below and from the guard's own counting, because it defines
|
|
the marker rather than carrying a disclosure. Counting the definition would make the number grow by
|
|
writing the rule down.
|
|
|
|
Working tree of `aerenew/publish-bundle`, measured 2026-08-03:
|
|
|
|
| Repository | `[VERIFY]` exact | `[VERIFY` any form | Files carrying a marker |
|
|
|---|---|---|---|
|
|
| `aere-contracts` | 8 | 16 | 10 |
|
|
| `aere-docs` | 177 | 226 | 46 |
|
|
| `aere-node` | 0 | 0 | 0 |
|
|
| `aere-research` | 60 | 66 | 18 |
|
|
| **total** | **245** | **308** | **74** |
|
|
|
|
Published trees on `git.aere.network`, cloned and measured 2026-08-03
|
|
(`aere-docs` at `58780bd`, `aere-contracts` at `c0fcf3d`, `aere-node` at `48416df`,
|
|
`aere-research` at `37f55e4`, all four commits dated 2026-07-20):
|
|
|
|
| Repository | `[VERIFY]` exact | `[VERIFY` any form | Files carrying a marker |
|
|
|---|---|---|---|
|
|
| `aere-contracts` | 8 | 16 | 10 |
|
|
| `aere-docs` | 171 | 224 | 46 |
|
|
| `aere-node` | 0 | 0 | 0 |
|
|
| `aere-research` | 84 | 92 | 27 |
|
|
| **total** | **263** | **332** | **83** |
|
|
|
|
The two tables do not agree, and that disagreement is itself a finding rather than an error in the
|
|
counting. The working copy and the published repositories have drifted apart in **both** directions
|
|
since 2026-07-20: the working copy holds 21 files that were never published (including
|
|
`KNOWN-ISSUES.md`, `LICENSING.md`, `CITATIONS-UNRESOLVED.md`, `RUN-A-NODE.md`, `genesis.json` and
|
|
`bootnodes.txt`), and the published `aere-research` holds 33 files under `formal-consensus/` that no
|
|
longer exist in the working copy. Any future publication has to reconcile that first, because a
|
|
naive re-stage and force-push would silently delete 33 files that are public today.
|
|
|
|
## For a reader who is not us
|
|
|
|
If you found a `[VERIFY]` marker in one of these documents: it is there on purpose. It marks the
|
|
exact boundary of what we measured. Everything around it is intended to be literally true, and the
|
|
marker tells you which specific claim we could not stand behind on the date the document was written.
|
|
If a marker matters to you, the fastest way to close it is usually to measure it yourself against
|
|
the public endpoint, and we would rather you did that than trust us.
|