meshcheck Phase 0: a deterministic glTF report card and the corpus that proves it

What shipped

At the end of Phase 0 meshcheck is a working, demoable product with no server attached. A two-crate Cargo workspace turns a GLB/glTF file into a machine-readable report card: Scene::from_bytes parses the container (buffers from the GLB BIN chunk, data: URIs, and external files via an injected resolver), fills the entire stats block, and 28 deterministic checks run over it — SPEC-001..004, GEO-001..009, XFM-001..003, UV-001..006, MAT-001..006, PERF-001..006 — each reading its thresholds from config/*.toml. The report is the full SPEC_02 envelope with a canonical id order, a summary/verdict rollup, and a committed JSON Schema guarded by a drift test. meshcheck-corpus check file.glb --profile pc prints it.

The other half is the ground truth. meshcheck-corpus generate fetches six pinned Khronos sample assets and stamps out 21 programmatic mutations — one labelled defect each — writing corpus/manifest.toml, the committed record of expectations. meshcheck-corpus bench --full-gate consumes that manifest and asserts detection over broken/, exact-precision over clean/, byte-identical double runs over every asset, and checks_only p95 latency per size class, then rewrites the Phase 0 table in BENCHMARKS.md and exits non-zero on any red row. A GitHub Actions workflow runs the whole gate on every push to main.

Decisions

The spine of the phase was determinism, and most decisions serve it. CheckId is a {group, num} struct whose derived Ord is the canonical report order, so parallel checks sort into stable output. Core never reads the clock — ReportMeta injects ids and timestamps — and every float passes through q6. Parsing uses from_slice_without_validation because the gltf crate’s own validation rejects exactly the assets SPEC-001/002/003 exist to report on. Edge identity welds vertices by exact position bits, so Box.glb’s 24 split vertices collapse back to 8 corners and the cube reads as closed.

Two calibration decisions were forced by real assets rather than theory. Duck.glb does not pass cleanly — its authored UVs genuinely overlap — so its UV warns were ruled true positives and recorded as manifest expected_warnings instead of being tuned away. GEO-002’s hole_area_pct was recalibrated from an M1 placeholder of 1.0 to 50.0 so that seam-open Khronos assets warn rather than fail, with error reserved for majority-open meshes. Both are logged, not silent.

The bench itself made two honesty calls. Latency is measured out-of-band with Instant while timing_ms stays zeroed, so double-run reports are byte-identical with no normalization. And corrupt_json, which needs the external Khronos validator to trip SPEC-001, is reported as excluded when no validator is installed — never counted as a pass.

What broke

Plenty, and it was useful. The gltf crate refused the unknown-extension fixture until we stopped validating at parse time. The validator CLI flag was wrong on the first pass (-s -o <dir> instead of the real -o stdout flag); downloading the 2.0.0-dev.3.10 binary and reading --help settled it. parry3d produced 189 compile errors when default-features = false stripped its required dim3/std features — the fix was enabling required-features and std alongside enhanced-determinism. A hand-rolled Moller tri-tri test was written as a parry fallback, then deleted once parry proved reliable on flat triangles.

The corpus surfaced two more. The naive unweld tripped nothing, because duplicating a shared vertex produces bit-identical copies that GEO-005 excludes (they would self-weld); a 1e-5 sub-tolerance jitter fixed it. The 8192² upsize texture first wrote a 268 MB file under NoFilter+Fast; the Up filter turns flat rows into zero deltas and dropped it to 360 KB. And the clean-corpus sweep flagged two error-level GEO-002 fails (Avocado, DamagedHelmet) that went to review as review_todo markers rather than being self-approved — which is what produced the hole_area_pct retune above.

Numbers

All measurements are from the dev machine (Windows, cargo 1.96, release). Detection is 100% of the 20 evaluated broken assets, with corrupt_json excluded because no validator is present. Precision is zero false positives and zero regressions across the six clean assets, whose warn sets exactly equal their manifest expectations. Determinism is 0 byte diffs over all 27 assets run twice. checks_only p95 is 44 ms for the ≤50k-tri class and 567 ms for the ≤500k-tri class (a 196k-tri exploded Box dominates the big class), against targets of 500 ms and 3 s. Schema drift is none and the wasm32 core build compiles. The per-check budget has headroom: Box.glb’s geometry kit builds in 3.69 µs and its full check registry runs in 49.61 µs with the kit cached.

Next

Phase 1 lifts the core onto Vercel Functions with meshcheck-core compiled to wasm behind a TypeScript API — /validate, uploads, jobs, an API-key credit ledger in Neon Postgres, and Blob storage with a retention sweep. The gate that matters most is wasm-vs-native report parity over the corpus, byte-identical modulo the documented GEO-009 skip, so the same determinism guarantees survive the platform move.