Finally land the before-hardening campaign

.github/workflows/ci.yml

@@ -1,12 +1,16 @@
 # Run the no-rot sweep (`just ci`) on every push to main and every pull request.
 #
-# `ci` is the gate's superset minus one thing: fmt-check → doclint → testdoc → readme-check
-# → clippy → the `before` feature matrix → wasm-check → docs → docs-internal →
-# test → doctest → bench-build → fuzz-build → the viz bundle. It builds the fuzz
-# targets but does
-# not run the smoke (`just all` adds that locally — libFuzzer minutes are a poor
-# per-commit spend). CI invokes the recipe rather than re-listing its steps, so
-# the sweep has exactly one definition (the justfile) and the two can't drift.
+# `ci` is the build-everything tier: fmt-check → doclint → testdoc → readme-check
+# → clippy → clippy-default → the workspace feature matrix → wasm-check → docs →
+# docs-internal → test-all → doctest → bench-build → fuzz-build → the viz
+# bundle. It builds the fuzz targets but does not run the smoke (`just all`
+# adds that locally — libFuzzer minutes are a poor per-commit spend). The
+# `instruments` job beside it re-runs the gate's deterministic, counter-based
+# instrument legs — the board verdicts and pins, surface totality, and the
+# supply-chain leg; its job comment says which instrument legs stay local and
+# why. The `gate` recipe line in the justfile remains the roster of record.
+# CI invokes recipes rather than re-listing their steps, so every check has
+# exactly one definition (the justfile) and the two can't drift.
 #
 # What the runner has to supply that a dev machine already has:
 #   - a current stable toolchain (edition 2024 needs 1.85+), with clippy + rustfmt
@@ -49,16 +53,10 @@ jobs:
       - name: Install nightly toolchain (merged doctests and fuzz build)
         uses: dtolnay/rust-toolchain@nightly
 
-      # rust-src is here for the trybuild suite: several `.stderr` snapshots
-      # quote std source (core's `panic!` expansion, `BitOr::bitor`,
-      # `Into::into`), and rustc prints those lines only when the sources are
-      # installed. Without it three cases mismatch on the quoted lines alone,
-      # which invites a blessing that would degrade the snapshots rather than
-      # supply what they need.
       - name: Install stable toolchain (default)
         uses: dtolnay/rust-toolchain@stable
         with:
-          components: clippy, rustfmt, rust-src
+          components: clippy, rustfmt
           targets: wasm32-unknown-unknown
 
       # cargo-rdme carries a version because it is the only tool here whose
@@ -92,3 +90,76 @@ jobs:
 
       - name: just ci
         run: just ci
+
+  # The gate's deterministic instrument legs, re-run on the runner. Only
+  # counter-based legs ride here: their readings are byte-identical under
+  # any machine load, so a shared runner cannot flake them. What stays
+  # local, and why:
+  #   - the judged wall-time legs (bench-judge and its tripwire): criterion
+  #     exponent fits need the quiet-machine regime a shared runner cannot
+  #     promise;
+  #   - the wasmtime fuel tier (the fuzzfit bands and the fuelscape pins):
+  #     deterministic, but it brings a wasm32 guest build plus wasmtime to
+  #     police asymptotics the board legs below already judge at the scales
+  #     of record — the gate keeps the second jaw.
+  #
+  # Runner fit: every step here builds `before` alone (release profile,
+  # counter features) plus the small detached surfacecheck workspace —
+  # never the rumors bench/release tier, whose lib-as-bench compile is
+  # known to exceed 16 GiB; that build lives in `ci`'s bench-build leg,
+  # not in this job.
+  #
+  # Toolchain coupling: surface-totality parses nightly rustdoc JSON
+  # through a `rustdoc-types` pin matched to the installed nightly's
+  # format_version. This job tracks nightly, so a format bump upstream can
+  # turn the leg red on an untouched tree — the checker refuses loudly,
+  # naming both version numbers, and the justfile's surface-totality
+  # comment documents the re-pin procedure.
+  instruments:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      # Nightly first, stable last (each dtolnay/rust-toolchain step runs
+      # `rustup default`, last one sticks): only the surface-json recipe
+      # invokes `cargo +nightly`; every other step must hit stable.
+      - name: Install nightly toolchain (surface-totality rustdoc JSON)
+        uses: dtolnay/rust-toolchain@nightly
+
+      # clippy and rustfmt are for the surfacecheck workspace's own lint
+      # legs, which the surface-totality recipe carries.
+      - name: Install stable toolchain (default)
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          components: clippy, rustfmt
+
+      - name: Install just, cargo-nextest, cargo-audit, and cargo-deny
+        uses: taiki-e/install-action@v2
+        with:
+          tool: just,cargo-nextest,cargo-audit,cargo-deny
+
+      - name: Cache cargo build artifacts
+        uses: Swatinem/rust-cache@v2
+        with:
+          # The detached surfacecheck workspace has its own lockfile and
+          # target directory; cache it beside the root workspace.
+          workspaces: |
+            .
+            crates/before/surfacecheck
+
+      # Build-free and network-bound (the advisory database fetch), so it
+      # runs first.
+      - name: just supply-chain
+        run: just supply-chain
+
+      # The board's acceptance judgment: one invocation measures each
+      # cell's whole ladder and its exit code carries the red/green
+      # verdict, so a red board fails the job.
+      - name: just amp-board-acceptance (the board verdict)
+        run: just amp-board-acceptance
+
+      - name: just worst-cases-pin
+        run: just worst-cases-pin
+
+      - name: just surface-totality
+        run: just surface-totality

.gitignore

@@ -14,3 +14,6 @@ formal/tla/tla2tools.jar
 
 # EventDag analysis dumps (lake exe eventdag); regenerable from the tool.
 formal/lean/eventdag-out/
+
+# macOS Finder metadata; never content.
+.DS_Store

AGENTS.md

@@ -39,15 +39,19 @@ it fully clean before every commit.
 
 ## Contributing a change
 
-One-time setup: everything `just gate` shells out to is a stable Rust
-toolchain (1.85 or later, for edition 2024) with clippy, rustfmt, and
-rust-src, a nightly toolchain (merged doctests), `just`, `cargo-nextest`,
-`cargo-rdme`, and python3 with bash (the `tools/` linters). `just ci`
-additionally wants the `wasm32-unknown-unknown` target, `wasm-pack`,
-`cargo-fuzz`, and node/npm. rust-src is what lets rustc quote std source,
-which `before`'s trybuild snapshots do: without the sources installed, three
-compile-fail cases mismatch on the quoted lines alone while the guarantees
-they pin are perfectly intact.
+One-time setup: most of it provisions itself. `rust-toolchain.toml` names
+the stable toolchain of record along with the components and targets the
+gate shells out to — clippy, rustfmt, and `wasm32-unknown-unknown` — and
+rustup installs them on the first cargo invocation, in the detached
+workspaces too. It is pinned rather than tracking current stable because
+the tree pins numbers derived from the compiler; the file's own comment
+carries that argument and the procedure for bumping it.
+
+What you install yourself: the nightly toolchain the gate's nightly legs
+name (`nightly_toolchain` in the justfile, pinned for the same reason),
+`just`, `cargo-nextest`, `cargo-rdme`, and python3 with bash (the
+`tools/` linters). `just ci` additionally wants `wasm-pack`,
+`cargo-fuzz`, and node/npm.
 
 1. Iterate with the inner loop: `just check`, `just test <filter>`,
    `just clippy`, `just fmt`.
@@ -126,6 +130,12 @@ they pin are perfectly intact.
   which means a new protocol version, never a mutation of an existing one.
   To re-accept deliberately: `just test-all`, then `cargo insta review`
   (install: `cargo install cargo-insta`), then commit the updated
-  `tests/snapshots/*.snap`.
+  `tests/snapshots/*.snap`. One sanctioned exception for tamper sweeps
+  attributing snapshot history: the bookmark `frame_non_trivial` pin
+  (`src/bookmark/format/`) is a ratified *fixture re-pin* — its fixture
+  deliberately carries nested versions so the pin exercises real skyline
+  payload bytes, and the format is attested unchanged by the untouched
+  `frame_empty` pin and the round-trip/corruption suite. Attribute that
+  pin's history to the fixture, never to a protocol change.
 - Redaction leaves no tombstones: deletion-honoring rides on version bounds.
   When reasoning about it, think version ceilings/floors, not markers.