Erratum drafts: the board, the kind of frequency, and the catalogue count

.claude/skills/fpga-synth/SKILL.md

@@ -312,6 +312,42 @@ remedy** until it survives several cold starts in a row.
 until an independent signal confirms it took, and report the attempt count so the retry is visible
 rather than assumed.
 
+### 🧷 Vary ONE parameter, and build the control with the others held identical
+
+Bisecting frame length against bring-up nearly produced an uninterpretable result: the test builds
+differed from the known-good one in **four** parameters at once (frame length, sweep mode, skew,
+request interval). A failure could not have been attributed to any of them. Building the control —
+same everything, frame length back at its original value — is what made the measurement mean
+something, and it exonerated two of the four parameters for free.
+
+Measured (node link-ups, all other parameters identical): 74 bytes on the wire ~48%, 314 bytes 3/8,
+714 bytes 4/8, **1514 bytes 0/20**. A sharp threshold, ordinary lottery rate either side of it.
+Mechanism still open: 1024 sits in the gap, but the RX and TX indices are both 11-bit, so no
+10-bit bound exists in the datapath.
+
+**Watch parameter widths:** `parameter [13:0] IVL0` silently truncated 25 000 to 8 616, so an
+interval quoted as 200 µs was really 69 µs.
+
+### 📏 Check frame duty cycle before choosing a request interval
+
+A 1514-byte frame occupies **12.1 µs** at 1 Gbit/s. A design whose request interval sweeps down to
+10 µs and 6 µs runs at **121% and 202% duty** at full MTU — saturated, no inter-frame gap, on every
+node at once. The same table is fine at 64 bytes (~5%). Compute
+`frame_time = (FLEN + 14) * 8 / 1e9` against the interval before believing a load figure: a
+throughput number from a saturated transmitter measures the transmitter, not the link.
+
+### 🔁 Audit MDIO designs for HOW OFTEN they write, not just what they write
+
+"Rewriting the PHY configuration restarts auto-negotiation" invalidated **three separate designs**
+here: an uncapped 1 s retry (0 links in 4), a 6 s runtime skew sweep built to measure the timing
+window, and a *supposedly fixed-skew* build that gated the skew **stepping** but not the
+**reprogramming** — its state machine still re-entered the MDIO write sequence every 6 s.
+
+The third is the instructive one: the parameter was named `SWEEP`, the intent was "do not disturb
+the PHY", and it disturbed it every six seconds. **Grep every path that can re-enter the programming
+state, not just the one that changes the value.** A measurement procedure that perturbs what it
+measures yields no data, and looks exactly like broken hardware.
+
 ### 🧪 Assume the instrument is wrong until a second signal agrees
 
 Three separate instrument defects surfaced in one investigation on this project:

.github/workflows/artefact-agreement.yml

@@ -0,0 +1,36 @@
+name: Artefact agreement
+
+# Every other check in this repository verifies an artefact against ITSELF: the
+# oracle round-trips, the RTL simulates, the catalogue validates. All of them
+# passed while the oracle and the RTL implemented different formats under the
+# name TNF16, and while a synthesised, measured format had no catalogue row at
+# all. No within-artefact test can catch either. This one compares declared
+# PARAMETERS across artefacts.
+#
+# It runs as a ratchet: the known divergences are recorded in
+# conformance/artefact_agreement_baseline.txt and the job fails only on NEW
+# ones, or when a baseline entry stops reproducing (so the file cannot rot into
+# a permanent excuse). Background: research/frontier/WITHDRAWAL_10_*.md and
+# WITHDRAWAL_11_*.md.
+
+on:
+  pull_request:
+  push:
+    branches: [main, master]
+
+jobs:
+  artefact-agreement:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Check out the SSOT catalogue
+        uses: actions/checkout@v4
+        with:
+          repository: gHashTag/t27
+          path: ../t27
+        continue-on-error: true
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Compare declared parameters across artefacts
+        run: python3 conformance/check_artefact_agreement.py

.github/workflows/doc-refs.yml

@@ -0,0 +1,24 @@
+name: Document references
+
+# Enumerating every pair of artefacts that must agree showed all existing gates
+# are code against code, and that every pair with a DOCUMENT on one side was
+# unguarded. A document naming a file, a script or a gate makes a checkable claim
+# about the tree, and a path in prose does not update itself when the tree moves.
+#
+# Ratcheted: 250 historical dangling references are baselined and the job fails
+# only on new ones. Temporary paths, sibling-repository paths, and files a
+# document names precisely to record their absence are excluded explicitly.
+
+on:
+  pull_request:
+  push:
+    branches: [main, master]
+
+jobs:
+  doc-refs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: '3.12' }
+      - run: python3 tools/check_doc_refs.py

.github/workflows/figure-names.yml

@@ -0,0 +1,19 @@
+name: Figure names
+
+# Three figures carried "TEF" and "GF-T" -- the format's names one and two
+# renames ago -- long after every sentence said TNF. Two had no generator at
+# all: the PDFs sat in the tree and the code that drew them did not, and a file
+# nobody regenerates is a file nobody renames. No textual gate can see it; the
+# names are inside vector graphics.
+
+on: [pull_request, push]
+
+jobs:
+  figure-names:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: '3.12' }
+      - run: sudo apt-get update && sudo apt-get install -y poppler-utils
+      - run: python3 tools/check_figure_names.py

.github/workflows/harness.yml

@@ -0,0 +1,29 @@
+name: Harness observation
+
+# Three harness confounds in three iterations, none visible in any number
+# because every design synthesised, routed and reported plausible figures:
+#   1. a shared accumulator held the critical path, so delay differences bounded
+#      the shared block rather than the varying part;
+#   2. observing four output bits pruned a 32-bit datapath to 15% of itself and
+#      an unrelated 6-bit design barely at all, reversing a 2.34x conclusion;
+#   3. designs consuming fewer harness sources pruned the rest, so net-of-harness
+#      subtraction used a subtrahend that varied with the design.
+#
+# Synthesis removes logic that does not reach an output. A harness must fold
+# every output bit of the design under test, and every source it provides, into
+# what it observes -- or the comparison is between designs cut to different
+# fractions of themselves.
+
+on:
+  pull_request:
+  push:
+    branches: [main, master]
+
+jobs:
+  harness:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: '3.12' }
+      - run: python3 tools/check_harness.py

.github/workflows/latex-hygiene.yml

@@ -0,0 +1,16 @@
+name: LaTeX hygiene
+
+# Defects LaTeX resolves silently. Four duplicate \label definitions sent twelve
+# \ref commands to the wrong theorems and tables while the build reported zero
+# errors and zero undefined references.
+
+on: [pull_request, push]
+
+jobs:
+  latex-hygiene:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: '3.12' }
+      - run: python3 tools/check_latex_hygiene.py

.github/workflows/orphan-artefacts.yml

@@ -0,0 +1,18 @@
+name: Orphaned artefacts
+
+# Two of the paper's six figures had no generator: the PDFs sat in the tree and
+# the code that drew them did not. They were also the only two still carrying
+# the format's name from two renames ago, and the two facts are one fact -- a
+# file nobody regenerates is a file nobody renames. An orphaned artefact is not
+# merely a reproducibility gap; it is where staleness accumulates.
+
+on: [pull_request, push]
+
+jobs:
+  orphan-artefacts:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: '3.12' }
+      - run: python3 tools/check_orphan_artefacts.py

.github/workflows/overfull.yml

@@ -0,0 +1,19 @@
+name: Overfull boxes
+
+# The build reported zero errors and zero undefined references while a display
+# equation stuck 57.5pt past the right margin and seven paragraphs and table
+# rows did the same. LaTeX calls an overfull box a warning, prints it among
+# hundreds of lines of engine chatter, and typesets the page anyway. It is not a
+# warning to a reader -- it is text they cannot see.
+
+on: [pull_request, push]
+
+jobs:
+  overfull:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: '3.12' }
+      - run: cargo install tectonic || true
+      - run: python3 tools/check_overfull.py

.github/workflows/paper-numbers.yml

@@ -0,0 +1,26 @@
+name: Paper traceability
+
+# Three earlier gates in this repository guard code against code, and each was
+# found by tripping over the defect it now catches. Enumerating every pair of
+# artefacts that must agree showed all three occupy one region, and that every
+# pair with a DOCUMENT on either side is unguarded -- which is where a withdrawn
+# claim's number survives, since it does not remove itself from a paper.
+#
+# This asks whether each distinctive figure in the paper appears in any file
+# under research/, fpga/ or conformance/. It excludes constants stated beside
+# their own formula, figures attributed to someone else's paper, and rounding.
+
+on:
+  pull_request:
+    paths: ['research/arxiv_tnf/**', 'research/**', 'fpga/**']
+  push:
+    branches: [main, master]
+
+jobs:
+  paper-numbers:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: '3.12' }
+      - run: python3 tools/check_paper_numbers.py

.github/workflows/ref-kinds.yml

@@ -0,0 +1,18 @@
+name: Reference kinds
+
+# A \ref can exist, be unique, and still be wrong: the paper said
+# "Appendix~\ref{sec:limits}" in a document with no appendix, and
+# "Section~\ref{sec:blockrelated}" inside the section labelled sec:blockrelated.
+# LaTeX resolves both silently and correctly by its own rules; the sentence is
+# what is wrong, and the sentence names the kind.
+
+on: [pull_request, push]
+
+jobs:
+  ref-kinds:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: '3.12' }
+      - run: python3 tools/check_ref_kinds.py

.github/workflows/script-rot.yml

@@ -0,0 +1,26 @@
+name: Reproduction scripts
+
+# fpga/tnet/mk8.sh -- the script that produced the 21-format silicon table --
+# instantiated `gft_add_w` while the file it reads defines `tef_add_w`. The
+# TEF-to-TNF rename changed the module name and left the script, so yosys
+# errored, no JSON was produced, and every run reported empty fields. The table
+# had already been written, so nobody ran it again. mkgf.sh, which produced the
+# GF rows, carried the identical defect.
+#
+# A reproduction path that is never run is a claim, not a capability.
+
+on:
+  pull_request:
+  push:
+    branches: [main, master]
+
+jobs:
+  script-rot:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Every instantiated module must exist in the files its script reads
+        run: python3 tools/check_script_rot.py

.github/workflows/self-consistency.yml

@@ -0,0 +1,20 @@
+name: Document self-consistency
+
+# Every other gate compares a document against something else -- data files, the
+# tree, a sibling artefact. None compared a document against itself, and the
+# paper carried three different counts of its own retractions: four in the
+# roadmap, eleven in the abstract, sixteen in the method section.
+#
+# A number a document states about its own contents is checkable against those
+# contents.
+
+on: [pull_request, push]
+
+jobs:
+  self-consistency:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: '3.12' }
+      - run: python3 tools/check_self_consistency.py

.github/workflows/withdrawn-live.yml

@@ -0,0 +1,18 @@
+name: Withdrawn numbers
+
+# The paper carried two paragraphs about one measurement eighteen lines apart:
+# the first asserted a figure "and that number is real", the second withdrew it
+# as a single placement run. The abstract quoted the withdrawn one. Nothing
+# checked it -- the traceability gate asks whether a number appears in a data
+# file, which a withdrawn number does, having been measured once.
+
+on: [pull_request, push]
+
+jobs:
+  withdrawn-live:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: '3.12' }
+      - run: python3 tools/check_withdrawn_live.py

.gitignore

@@ -415,3 +415,8 @@ apps/queen/Trinity.app/
 trinet-keys.txt
 *.trinet-keys
 research/.gate_cache/
+
+# synthesis scratch from the closure measurements: generated wrappers and netlists
+fpga/phiscale/c_*.v
+fpga/phiscale/c_*.json
+fpga/phiscale/c[sy]_*.log