Wave 39/45: diagnostics.kernel takes a typed contract, as main's other diagnostics commands do

1 commits, squashed; the originals stay reachable from branch jyviko/merge-main-develop-solidcore (#11360).

- 7ad1d3e12 jyviko: diagnostics.kernel takes a typed contract, as main's other diagnostics commands do

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DtL5M41G8Nua7HvuFPZkmJ
This commit is contained in:
jyviko
2026-11-02 16:58:17 -05:00
parent f582b1f39e
commit 28e983e191
115 changed files with 18703 additions and 600 deletions
+30 -12
View File
@@ -1,17 +1,22 @@
# Kernel regression rig
Every geometry case the old kernel (truck) got wrong, recorded in an issue, a pull request or a
crash report, is a use case here with its own right answer. The kernel, SMLib, is held to all of
them. `cargo xtask kernel-cases` runs them and writes [`docs/kernel-cases.md`](../../docs/kernel-cases.md).
crash report, is a use case here with its own right answer. The kernel, solidcore, is held to all
of them, as is the C++ SMLib kernel it was ported from when asked for. `cargo xtask kernel-cases`
runs them on solidcore; `--kernel smlib` runs them on C++ and writes
[`docs/kernel-cases.md`](../../docs/kernel-cases.md).
```sh
cargo xtask kernel-cases # every case
cargo xtask kernel-cases # every case, on solidcore
cargo xtask kernel-cases --cli target/release/solidcraft-cli --out /tmp/run # with a CLI already built
cargo run -p solidcraft-cli --features smlib -- kernel-cases tests/kernel-cases/booleans/<id> # one case
cargo xtask kernel-cases --kernel both --cli target/release/solidcraft-cli # SMLib and solidcore side by side
cargo run -p solidcraft-cli -- kernel-cases tests/kernel-cases/booleans/<id> # one case
```
The CLI links SMLib by default (`scripts/fetch-smlib.sh` fetches the prebuilt library first);
built with `--no-default-features`, every operation answers that SMLib is not built. The run's output folder (`--out`, default `target/kernel-cases`)
The CLI builds with solidcore alone by default. The C++ SMLib kernel is opt-in at build time:
`--features smlib` links it (`scripts/fetch-smlib.sh` fetches the prebuilt library first), and
`--kernel smlib` or `both` without `--cli` builds the CLI that way. On a build without it, asking
for SMLib answers that this build doesn't include it. The run's output folder (`--out`, default `target/kernel-cases`)
gets `results.json`, every case's full result, and `dumps/<area>-<case>/`: the inputs of each
SMLib call a case failed in, for replay (the CLI's `--dumps=DIR`, which the rig always passes).
`--validation MODE` runs the cases' features under that mode of SMLib's check
@@ -19,6 +24,13 @@ SMLib call a case failed in, for replay (the CLI's `--dumps=DIR`, which the rig
once), `each_step` (after every sweep, boolean and blend, as before) or `off`; the
`KNOWN_FAILING` lists are each_feature's.
`--kernel solidcore|smlib|both` (default `solidcore`) picks the backend each case's process runs on,
through `SOLIDCRAFT_KERNEL`. A `solidcore` run keeps its `results.json`, `dumps/` and `report.md`
in `<out>/solidcore/` and leaves `docs/kernel-cases.md`, which is the `smlib` run's, alone. `both` runs every case on each
backend, keeps `docs/kernel-cases.md` as the SMLib report and writes the two side by side to
[`docs/kernel-cases-backends.md`](../../docs/kernel-cases-backends.md) (cases that differ first)
and `<out>/backends.json`.
## Rules
- **The answer never comes from a kernel.** Not from truck's output, nor any commercial
@@ -126,17 +138,19 @@ the frozen truck-geometry PRs, a `kernel-paused` PR), for the report's coverage
Every area is a regression suite: each case is one small case of one issue, with its exact
answer. `.github/workflows/kernel-rig.yml` runs them, and the ladder, on pull requests (not
drafts). A plan job (`scripts/ci/kernel_rig_plan.py`) picks the areas from the changed files, one
job builds `solidcraft-cli` (release, SMLib) and the rig's runner, and a matrix of shards, one per
job builds `solidcraft-cli` (release, `--features smlib`, for the ladder's `--kernel smlib`) and the rig's runner, and a matrix of shards, one per
selected area plus the ladder, runs them in parallel; the `kernel-rig` check passes when every
selected shard does (and when none was selected). Pushes to main and develop, merge groups, the
release gate (`release-gate.yml`) and a run by hand run every area. Each area's shard runs:
```sh
cargo xtask kernel-cases --area <area> --cli target/release/solidcraft-cli \
--known-failing tests/kernel-cases/<area>/KNOWN_FAILING
--known-failing tests/kernel-cases/<area>/KNOWN_FAILING.solidcore
```
`<area>/KNOWN_FAILING` lists the cases of that area that fail today, sorted, one a line with its
The gate grades the kernel the run is on, so a list is one kernel's: `<area>/KNOWN_FAILING.solidcore`
for the default, `<area>/KNOWN_FAILING` with `--kernel smlib` (`--kernel both` is refused). Each lists
the cases of that area that fail today on it, sorted, one a line with its
cause (`<case> <why it fails today>`; `#` starts a comment; the header names the baseline: the
develop commit and SMLib revision it was taken from). The gate fails on a **regression**, a
case that fails (or crashes, hangs, or is not supported yet) and is not listed, and on a
@@ -208,11 +222,15 @@ running part grows one tier at a time through `base`), so the last case carries
`method` gives the derivation).
```sh
cargo xtask kernel-cases --ladder --cli target/release/solidcraft-cli
cargo xtask kernel-cases --ladder --cli target/release/solidcraft-cli --gate
cargo xtask kernel-cases --ladder --cli target/release/solidcraft-cli --record "why"
cargo xtask kernel-cases --ladder --kernel smlib --cli target/release/solidcraft-cli
cargo xtask kernel-cases --ladder --kernel smlib --cli target/release/solidcraft-cli --gate
cargo xtask kernel-cases --ladder --kernel smlib --cli target/release/solidcraft-cli --record "why"
```
The golden is the C++ kernel's, so these say `--kernel smlib`. Without it a run is on solidcore and is
graded against the same golden; today that differs on one case,
`ladder/09-shells-and-offsets/010-shell-under-rounded-top`.
The ladder needs no known-failing list: the golden is the reference. Its shard in the kernel rig
gate runs with `--gate`, which fails on any case whose status or counts differ from the golden,
better or worse, and on a case with no golden; times are not compared there (they are the
@@ -0,0 +1,3 @@
# The assemblies cases that fail today on solidcore, one a line: `<case> <why it fails today>`. Sorted.
# The kernel rig gate fails on a case that fails and is not listed, and on a listed case that passes.
# Baseline: solidcore pin de85a3e00, tests/kernel-cases run by `cargo xtask kernel-cases`, x86_64 Linux.
@@ -0,0 +1,3 @@
# The booleans cases that fail today on solidcore, one a line: `<case> <why it fails today>`. Sorted.
# The kernel rig gate fails on a case that fails and is not listed, and on a listed case that passes.
# Baseline: solidcore pin de85a3e00, tests/kernel-cases run by `cargo xtask kernel-cases`, x86_64 Linux.
@@ -0,0 +1,3 @@
# The construction cases that fail today on solidcore, one a line: `<case> <why it fails today>`. Sorted.
# The kernel rig gate fails on a case that fails and is not listed, and on a listed case that passes.
# Baseline: solidcore pin de85a3e00, tests/kernel-cases run by `cargo xtask kernel-cases`, x86_64 Linux.
@@ -0,0 +1,3 @@
# The continuity cases that fail today on solidcore, one a line: `<case> <why it fails today>`. Sorted.
# The kernel rig gate fails on a case that fails and is not listed, and on a listed case that passes.
# Baseline: solidcore pin de85a3e00, tests/kernel-cases run by `cargo xtask kernel-cases`, x86_64 Linux.
@@ -0,0 +1,3 @@
# The crashes cases that fail today on solidcore, one a line: `<case> <why it fails today>`. Sorted.
# The kernel rig gate fails on a case that fails and is not listed, and on a listed case that passes.
# Baseline: solidcore pin de85a3e00, tests/kernel-cases run by `cargo xtask kernel-cases`, x86_64 Linux.
@@ -0,0 +1,37 @@
# The fillets cases that fail today on solidcore, one a line: `<case> <why it fails today>`. Sorted.
# The kernel rig gate fails on a case that fails and is not listed, and on a listed case that passes.
# Baseline: solidcore pin de85a3e00, tests/kernel-cases run by `cargo xtask kernel-cases`, x86_64 Linux.
1080-fillet-equal-slope-basin-1-mm-rim-loop-4 [fail] continuity_order: got {'body': 'Slab', 'edges': 'blend', 'order': 'g0', want >= g1 at every blend seam
1080-fillet-sloped-basin-1-mm-rim-r4-2-edges [fail] continuity_order: got {'body': 'Slab', 'edges': 'blend', 'order': 'g0', want >= g1 at every blend seam
1080-fillet-sloped-basin-1-mm-rim-r4-4-edges [fail] continuity_order: got {'body': 'Slab', 'edges': 'blend', 'order': 'g0', want >= g1 at every blend seam
1207-fillet-bar-top-edge-after-boss-arc-round-r0-5 [fail] step 4 (solid.fillet): body `Arm`: the operation failed: SMLib fillet: SMLib's check refuses the result: 5 failed tests: SmBSplineCurve::Test #15 Bad Repeated CPts: BSplineCurve has Internal Coincident ControlPoints (causes
2893-chamfer-distance-and-angle-past-the-wall-refused [fail] refused, but not because "angle": step 2 (solid.chamfer): SMLib chamfer: operation: SMLib rejected the input (SM_ERR_INVALID_INPUT)
2893-chamfer-two-distances-elliptical-rim [fail] refused, but not because "not supported yet": step 3 (solid.chamfer): SMLib chamfer: operation: SMLib failed (status 1001) (tangent propagation blended the picked edges' tangent chain with them; with it off, tangent_chain:
4782-fillet-bar-edge-wider-than-both-faces [fail] continuity_order: got Box: no null seams want >= g1 at every blend seam
5158-fillet-round-just-past-a-10mm-face [fail] step 2 (solid.fillet): SMLib fillet: operation: SMLib failed (status 1001)
851-fillet-arc-then-top-front [fail] fillet status 1001, as on SMLib 5e8c9c1 (see KNOWN_FAILING): with tangent_chain true since 21f00a917 the top front edge's chain takes the arc round's end curve, where the R2 ball sits on that round's centre circle (a torus of tube-centre radius 0, the three-edge rolling-ball corner)
851-fillet-top-front-then-upright [fail] fillet status 1001, as on SMLib 5e8c9c1 (see KNOWN_FAILING): with tangent_chain true since 21f00a917 the upright's chain takes the first round's end curve, where the R2 ball sits on that round's axis (a torus of tube-centre radius 0, the three-edge rolling-ball corner)
9-fillet-corner-curvature-with-reduce-fit [unsupported] solid.fillet builds `corner: g2` with `fit: exact` only
9-fillet-corner-curvature-with-taper-fit [unsupported] solid.fillet builds `corner: g2` with `fit: exact` only
cov-fillet-g2-corner-beside-a-cylinder [fail] step 6 (solid.fillet): the open setback corner is not a closed solid, as on SMLib d01d7b0
cov-fillet-g2-five-edge-apex-corner [fail] step 12 (solid.fillet): invalid input: the setback must be more than 3.5056 mm at the corner (-0.000, 0.000, 30.000): the rounds' contact lines meet 3
cov-fillet-g2-four-edge-apex-corner [fail] step 11 (solid.fillet): invalid input: the setback must be more than 3.9027 mm at the corner (0.000, 0.000, 30.000): the rounds' contact lines meet 3.
cov-fillet-g2-mixed-corner [unsupported] refused as on SMLib d01d7b0: a G2 corner is set back only where every edge meeting it is rounded and all are convex or all concave
cov-fillet-g2-oblique-three-edge-corner [unsupported] refused on solidcore: its three edges meet at different wedge angles, and one curvature fillet takes the first edge's equal-area thumbweight for every edge (solidcore#2250, issuecomment-6563419897); SMLib d01d7b0 fails it too (see KNOWN_FAILING)
cov-fillet-g2-pocket-corner [fail] continuity_order: G1 at one seam where the corner patch meets a contact face (g2 wanted), as on SMLib d01d7b0 (see KNOWN_FAILING)
cov-fillet-section-curvature-pipe-on-plate-r2 [fail] solidcore builds the order-2 section as SMLib d01d7b0 did (40302.5908, G2 on both seams); the case now grades SMLib 5e8c9c1's section, the round as its definition, G3 on the pipe and 40307.8856 (fork 4a10ed8 and 79db628, to be ported in solidcore#2273)
cov-fillet-turn-swept-boss-base-r1 [fail] as on SMLib: solid.fillet has no `turn`; the corners are mitred (12508.9675, the Mitre case's volume)
cov-fillet-turn-swept-pocket-sharp-corner-refused-r1 [fail] as on SMLib: solid.fillet has no `turn`, so the sharp concave corners are mitred, not refused
cov-junction-boss-tilt-20-root-round [fail] fillet status 1001 on a cylinder tilted 20 degrees into the plate, as on SMLib
cov-junction-boss-tilt-40-root-round [fail] fillet status 1001 on a cylinder tilted 40 degrees into the plate, as on SMLib
cov-junction-tee-equal-round [fail] the result is not a closed solid, as on SMLib: equal pipes' intersection is two plane ellipses crossing, a corner the old corner code cannot join (the corner step)
cov-junction-y-junction-120-round [unsupported] refused as on SMLib: the faces between the three intersection curves narrow to nothing at the two triple points, so the room check trips (the corner step)
report-drafted-peg-front-and-concave-rounds-together-r2 [unsupported] step 13 (solid.fillet): invalid input: not supported yet: the fillet meets a corner of this kind, which SMLib's blends do not handle yet (where its ed
report-fillet-concave-arc-and-front-top-edge-together-r5-solver-residues [fail] bbox.min: got [0.4892940775280783, 0.05636444090890084, 0.0] want [0.4892940775280783, 0.05792545052986289, 0.0]
report-fillet-concave-arc-and-front-top-edge-together-r7-solver-residues [fail] bbox.min: got [0.4892940775169876, 0.02441657049978923, 0.0] want [0.4892940775280783, 0.05792545052986289, 0.0]
report-fillet-curvature-three-edges-at-bar-corner [fail] continuity_order: G1 at one seam where the corner patch meets a contact face (g2 wanted), as on SMLib d01d7b0 (see KNOWN_FAILING)
report-fillet-curvature-three-edges-at-bar-corner-solver-residues [fail] continuity_order: G1 at one seam where the corner patch meets a contact face (g2 wanted), as on SMLib d01d7b0 (see KNOWN_FAILING)
report-peg-front-and-concave-chamfers-together-d2 [fail] step 13 (solid.chamfer): SMLib chamfer: operation: SMLib failed (status 1001)
report-peg-front-and-concave-rounds-together-r2 [fail] continuity_order: got {'body': 'Peg', 'edges': 'blend', 'order': 'g0', ' want >= g1 at every blend seam
report-peg-front-and-concave-rounds-together-r5 [fail] continuity_order: got {'body': 'Peg', 'edges': 'blend', 'order': 'g0', ' want >= g1 at every blend seam
report-peg-step-front-and-concave-rounds-together-r2 [fail] continuity_order: got {'body': 'Peg', 'edges': 'blend', 'order': 'g0', ' want >= g1 at every blend seam
@@ -0,0 +1,3 @@
# The frames cases that fail today on solidcore, one a line: `<case> <why it fails today>`. Sorted.
# The kernel rig gate fails on a case that fails and is not listed, and on a listed case that passes.
# Baseline: solidcore pin de85a3e00, tests/kernel-cases run by `cargo xtask kernel-cases`, x86_64 Linux.
@@ -0,0 +1,3 @@
# The history cases that fail today on solidcore, one a line: `<case> <why it fails today>`. Sorted.
# The kernel rig gate fails on a case that fails and is not listed, and on a listed case that passes.
# Baseline: solidcore pin de85a3e00, tests/kernel-cases run by `cargo xtask kernel-cases`, x86_64 Linux.
@@ -0,0 +1,3 @@
# The import cases that fail today on solidcore, one a line: `<case> <why it fails today>`. Sorted.
# The kernel rig gate fails on a case that fails and is not listed, and on a listed case that passes.
# Baseline: solidcore pin de85a3e00, tests/kernel-cases run by `cargo xtask kernel-cases`, x86_64 Linux.
@@ -0,0 +1,3 @@
# The inspect cases that fail today on solidcore, one a line: `<case> <why it fails today>`. Sorted.
# The kernel rig gate fails on a case that fails and is not listed, and on a listed case that passes.
# Baseline: solidcore pin de85a3e00, tests/kernel-cases run by `cargo xtask kernel-cases`, x86_64 Linux.
@@ -0,0 +1,3 @@
# The plastic cases that fail today on solidcore, one a line: `<case> <why it fails today>`. Sorted.
# The kernel rig gate fails on a case that fails and is not listed, and on a listed case that passes.
# Baseline: solidcore pin de85a3e00, tests/kernel-cases run by `cargo xtask kernel-cases`, x86_64 Linux.
@@ -0,0 +1,3 @@
# The sheet-metal cases that fail today on solidcore, one a line: `<case> <why it fails today>`. Sorted.
# The kernel rig gate fails on a case that fails and is not listed, and on a listed case that passes.
# Baseline: solidcore pin de85a3e00, tests/kernel-cases run by `cargo xtask kernel-cases`, x86_64 Linux.
@@ -0,0 +1,4 @@
# The shell cases that fail today on solidcore, one a line: `<case> <why it fails today>`. Sorted.
# The kernel rig gate fails on a case that fails and is not listed, and on a listed case that passes.
# Baseline: solidcore pin de85a3e00, tests/kernel-cases run by `cargo xtask kernel-cases`, x86_64 Linux.
cov-shell-again-open-at-an-inner-wall-of-a-shelled-box [fail] step 9 (solid.shell): SMLib shell: operation: SMLib failed (status 1001)
@@ -0,0 +1,3 @@
# The solids cases that fail today on solidcore, one a line: `<case> <why it fails today>`. Sorted.
# The kernel rig gate fails on a case that fails and is not listed, and on a listed case that passes.
# Baseline: solidcore pin de85a3e00, tests/kernel-cases run by `cargo xtask kernel-cases`, x86_64 Linux.
@@ -0,0 +1,3 @@
# The surfaces cases that fail today on solidcore, one a line: `<case> <why it fails today>`. Sorted.
# The kernel rig gate fails on a case that fails and is not listed, and on a listed case that passes.
# Baseline: solidcore pin de85a3e00, tests/kernel-cases run by `cargo xtask kernel-cases`, x86_64 Linux.
@@ -0,0 +1,3 @@
# The sweeps cases that fail today on solidcore, one a line: `<case> <why it fails today>`. Sorted.
# The kernel rig gate fails on a case that fails and is not listed, and on a listed case that passes.
# Baseline: solidcore pin de85a3e00, tests/kernel-cases run by `cargo xtask kernel-cases`, x86_64 Linux.
@@ -0,0 +1,3 @@
# The tessellation cases that fail today on solidcore, one a line: `<case> <why it fails today>`. Sorted.
# The kernel rig gate fails on a case that fails and is not listed, and on a listed case that passes.
# Baseline: solidcore pin de85a3e00, tests/kernel-cases run by `cargo xtask kernel-cases`, x86_64 Linux.
@@ -0,0 +1,3 @@
# The threads cases that fail today on solidcore, one a line: `<case> <why it fails today>`. Sorted.
# The kernel rig gate fails on a case that fails and is not listed, and on a listed case that passes.
# Baseline: solidcore pin de85a3e00, tests/kernel-cases run by `cargo xtask kernel-cases`, x86_64 Linux.