Property-based tests over randomly generated SDF trees

[kmatzen]

Part of #52 — the CPU-side half. The differential CPU-vs-GLSL testing that issue also proposes needs a headless WebGL context and is not included here.

evaluate.test.ts checks hand-picked points on hand-built shapes. These check invariants that must hold for any tree, which is where the cases nobody thought to write live.

Properties

property	why it matters
1-Lipschitz (globally, and near the surface)	Sphere tracing steps by the returned distance. A field that over-reports makes the march overshoot — which is how thin walls turn into holes in a render.
finite everywhere	NaN/Inf propagates into codegen and the mesher
union commutative, idempotent, exactly min at k=0	boolean algebra the codegen relies on
translation commutes with evaluation	catches inverse-transform sign errors, which move a shape the wrong way
smooth union never exceeds sharp union	a blend must add a fillet, not carve material

Design notes

Deterministic, no new dependency. A seeded mulberry32 PRNG rather than a fuzzing library — failures reproduce exactly and CI cannot flake.

The generator is restricted to shapes that claim exactness. ellipsoid and cone are approximations in their usual formulations, patterns break the bound at cell boundaries, and text is piecewise. Asserting exactness of those would produce noise rather than findings. Exclusions are documented with reasons in the file.

Two guards against passing for the wrong reason. The near-surface test bisects to the zero level set, because random points in an 8-unit cube mostly land far from any surface where the field is smooth and the check is weak. And it asserts probed > 50, so a bisection that never finds surfaces fails rather than silently skipping every sample.

Verified by mutation

Over-reporting sphere distance by 1.5x in evaluate.ts makes both Lipschitz tests fail, at ratios of 1.500x, 1.497x, 1.496x, with the failure output naming the offending trees.

That check is what makes the result meaningful — without it, "8 tests pass" is indistinguishable from "8 tests that assert nothing."

Worth recording that my first mutation attempt was invalid: I assumed non-uniform scale breaks the Lipschitz bound, without reading evaluate.ts:113, where the Math.min(sx, sy, sz) factor already handles it conservatively — and the generator pins scale to 1, so the mutation never executed. Had I stopped there I would have concluded the tests were toothless when the real problem was my choice of defect.

Result

No bugs found. The evaluator is sound on every property tested. A negative result, but a verified one — and the generator is reusable for the GPU differential tests when those become possible.

One honest limit: I predicted only the near-surface variant would catch the mutation, and both did. A uniform 1.5x over-report shows up everywhere, so random sampling finds it fine. The near-surface variant should matter for localized violations at boolean seams, but I have not demonstrated a case where it catches something the plain one misses.

🤖 Generated with Claude Code