Skip to content

Commit adf56f6

Browse files
committed
docs/ci.md: the floor pages describe the constant rule the code now runs
The overlay paragraph claimed "each floor is lowered by the pinned private-fixture row count" recorded in the file, that "every ctest row carrying the private_fixtures label must" run, that "ctest -N lists a placeholder's row whether" it runs or skips (so the registered population is the same in both worlds), and that "a row that stops executing fails the floor". None of that is true of the code: the numbers live in PRIVATE_FIXTURE_PROFILE_FLOORS, the absent floor is full minus the pinned count and never moves with the run, the registered populations differ (release 902/901, kernel 331/424, debug 883/882, sanitizers 874/875), and the profile tables now name the table, not the two historical constants. "The full-run release and kernel floors are 792" is stale and replaced by the table's own numbers, and "Raise the constant when a row lands" now says to raise the table's full number. The A/B population table is in place; both columns are to be re-measured after the registration fix (lane FA) merges. Two floor sentences leave as the page takes the table's rule: 4c040e4's "KERNEL_MIN_TESTS in scripts/ci_verify.py pins the expected row count; the ctest-floor stage fails when fewer rows ran or CTest printed no count it can read." is reworded in place to the floor table's rule, and 2a9a2db's "EXCLUDED_REGISTERED_MIN does not move:" becomes the registered-floor paragraph read only on an --exclude-label run, out of the overlay rule entirely. Neither claim is dropped; both now describe PRIVATE_FIXTURE_PROFILE_FLOORS.
1 parent 143a06e commit adf56f6

1 file changed

Lines changed: 42 additions & 24 deletions

File tree

‎docs/ci.md‎

Lines changed: 42 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -70,13 +70,13 @@ instead ([Run-failure codes](pages/run-failure-codes.md)).
7070

7171
| Profile | Build | Additional coverage |
7272
| --- | --- | --- |
73-
| `release` | Release, tutorial enabled | Standard CI checks behind a row floor (`RELEASE_MIN_TESTS`; `--min-tests N` overrides it), installed package, and installed native include-independence proof |
73+
| `release` | Release, tutorial enabled | Standard CI checks behind a row floor (`PRIVATE_FIXTURE_PROFILE_FLOORS`; `--min-tests N` overrides it), installed package, and installed native include-independence proof |
7474
| `debug` | Debug, tutorial enabled | The standard checks and installed package without Release optimization; no default row floor, examples, include-independence proof or twin-parity guard |
7575
| `sanitizers` | Debug, ASan and UBSan | Instrumented library, tests and installed consumer; Linux CI also requires leak detection |
7676
| `native` | Release, live runner enabled | JSON, journal, transport tests, installed runner help, and installed native include-independence proof |
7777
| `live-sanitizers` | Debug, live runner enabled, ASan and UBSan | Every runner target instrumented and audited from compile commands; all runner CTest rows, Python E2Es and installed runner help; WebSocket-enabled curl mandatory while `runner/transport.cpp` exists, no skips accepted |
7878
| `live-tsan` | Debug, live runner enabled, ThreadSanitizer | Separate build instruments every runner target, audits compile commands and runs all runner rows and Python E2Es; WebSocket-enabled curl is mandatory and skips are refused |
79-
| `kernel` | Release, live runner enabled, Pine source layer OFF | The source-free CTest set behind a row floor (`KERNEL_MIN_TESTS`; `--min-tests N` overrides it), installed package, and the `nm` half of the include-independence proof over `libpineforge_kernel.a` |
79+
| `kernel` | Release, live runner enabled, Pine source layer OFF | The source-free CTest set behind a row floor (`PRIVATE_FIXTURE_PROFILE_FLOORS`; `--min-tests N` overrides it), installed package, and the `nm` half of the include-independence proof over `libpineforge_kernel.a` |
8080

8181
By default each profile uses `build-ci-<profile>`. Keep separate build directories
8282
for different profiles and toolchains. The verifier never deletes a build tree
@@ -134,27 +134,44 @@ Only the native cell accepts the caller's existing PR-only slow-label exclusion.
134134
The kernel profile also gates the CTest row count: `tests/CMakeLists.txt`
135135
drops every test TU whose include closure reaches `pineforge/source/` or
136136
`compat/pine/`, so a lane whose native witnesses shared a TU with an adapter
137-
twin would leave the kernel-only gate without any failure. `KERNEL_MIN_TESTS`
138-
in `scripts/ci_verify.py` pins the expected row count; the `ctest-floor`
139-
stage fails when fewer rows ran or CTest printed no count it can read. Only
140-
rows whose test ran count: a row CTest skipped or could not start is listed
141-
beside the count (`ctest-floor.log`, `ctestSkipped` / `ctestNotRun` in
142-
`ci-summary.json`), never counted, so the unsupported-WebSocket skip above is
143-
reported rather than counted, and a row that stops executing fails the floor
144-
too. The release profile
145-
carries the same gate with `RELEASE_MIN_TESTS`, so a row deleted from the
146-
default build fails too; `debug` and `sanitizers` register a subset of the
147-
release rows. Raise the constant when a row lands, and pass `--min-tests N` to
148-
override it for one run (the flag gates any profile; `kernel` and `release`
149-
have a default). The two run floors are overlay-aware, keyed on
150-
`PINEFORGE_PRIVATE_FIXTURES`: with the variable set and non-empty (the
151-
private-fixture overlay is present in the tree) the full constants apply and
152-
every ctest row carrying the `private_fixtures` label must run, so a skip
153-
fails the run -- a skip there means the overlay did not reach the tree; with
154-
the variable unset (public CI, where the overlay's rows register as
155-
placeholders and skip) each floor is lowered by the pinned private-fixture row
156-
count recorded in `tests/private_fixture_rows.txt`. `EXCLUDED_REGISTERED_MIN`
157-
does not move: `ctest -N` lists a placeholder's row whether it runs or skips.
137+
twin would leave the kernel-only gate without any failure. The campaign's
138+
per-profile row floors live in ONE table in `scripts/ci_verify.py`,
139+
`PRIVATE_FIXTURE_PROFILE_FLOORS`, which states for each of `release` and
140+
`kernel` the profile's full overlay-present population and how many pinned
141+
private-fixture rows that population registers; the `ctest-floor` stage fails
142+
when fewer rows ran than the floor, or when CTest printed no count it can
143+
read. Only rows whose test ran count: a row CTest skipped, disabled or could
144+
not start is listed beside the count (`ctest-floor.log`, `ctestSkipped` /
145+
`ctestNotRun` / `ctestDisabled` in `ci-summary.json`), never counted. The
146+
release profile carries the same gate, so a row deleted from the default build
147+
fails too; `debug` and `sanitizers` register a subset of the release rows and
148+
have no row floor of their own. Raise the table's `full` number when a row
149+
lands, and pass `--min-tests N` to override it for one run (the flag gates any
150+
profile; `kernel` and `release` have a default).
151+
152+
The two run floors are overlay-aware, keyed on `PINEFORGE_PRIVATE_FIXTURES`.
153+
Both numbers are constants of the profile, measured on the campaign's
154+
two-world runs; they never move with the run's own `ctest -N` count or its
155+
observed skips:
156+
157+
| profile | floor, overlay present | floor, overlay absent | registered (present / absent) |
158+
|---|---|---|---|
159+
| `release` | 902 | 605 | 902 / 901 |
160+
| `kernel` | 331 | 303 | 331 / 424 |
161+
162+
With the variable set and non-empty (the private-fixture overlay is present in
163+
the tree) the floor is the full population and EVERY row of it must run: a row
164+
that skips, is disabled or cannot start fails the run -- a skip there means the
165+
overlay did not reach the tree. With the variable unset (public CI, where the
166+
pinned rows register as placeholders and skip) the floor is that profile's
167+
full population minus the pinned rows it registers, so a public row that
168+
leaves the registry or stops running falls under the floor either way, an
169+
unpinned skip is a loss with no margin to absorb it, and an explicit
170+
`--min-tests N` is used verbatim in both modes and is never lowered. The
171+
registered column is why the absent floor is not the absent registration, and
172+
it is to be re-measured after the registration fix lands.
173+
`EXCLUDED_REGISTERED_MIN` is a registered floor, read only on an
174+
`--exclude-label` run, and stays out of the overlay rule entirely.
158175

159176
For PR runs with `--exclude-label slow`, the verifier asks CTest to enumerate
160177
the registered rows both with `ctest -N` and with `ctest -N -LE slow`. It then
@@ -168,7 +185,8 @@ plus wave G's six rows, wave H's twenty-four, INT26's own tape row, INT27's
168185
thirteen, XSYM-D's four, K-SESSION-WINDOWS' four, INT28's twenty-four,
169186
INT28-FIX's four, INT29's seven, W15-KERNEL-CAL's two, INT30's twenty-four,
170187
TAIL-I's one, XAU-CAL's four and FIX-E1E2's two). The full-run release and
171-
kernel floors are 792 and 299 rows that ran; full runs do not exclude a label.
188+
kernel floors are the table's own numbers above (605 and 303 rows absent, 902
189+
and 331 with the overlay present); full runs do not exclude a label.
172190

173191
Preflight also runs the detached-comment census of the kernel compile closure
174192
(`detached-comments`: `scripts/measure_detached_comments.py --check-ceiling`)

0 commit comments

Comments
 (0)