feat: add CLI falsifiers and exit tables to six examples (#141)

Each flag feeds degenerate input into an existing measured check so the assertion can fail on purpose. Default smoke path is unchanged. README tables document every nonzero code these scripts already returned; no codes were renumbered.

Signed-off-by: TMHSDigital <154358121+TMHSDigital@users.noreply.github.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

Author: TMHSDigital

examples/car-mirror-symmetry/README.md

@@ -58,11 +58,39 @@ windshield as a hot salmon slab.
 # Cheap correctness check (no render) — the CI check:
 blender --background --python car_mirror_symmetry.py --
 
+# Falsifier: Mirror X off. Must exit non-zero (evaluated verts stay at n).
+blender --background --python car_mirror_symmetry.py -- --no-mirror
+
 # Also render a still (EEVEE on a GPU host; use --engine cycles on GPU-less hosts):
 blender --background --python car_mirror_symmetry.py -- --output car.png
 blender --background --python car_mirror_symmetry.py -- --output car.png --engine cycles
 ```
 
-It exits non-zero on failure (applied mirror, doubled centerline, unwelded
-seam, broken symmetry, or a mirrored part off its plane origin). The
-`blender-smoke` workflow runs the check on Blender 5.2 LTS and 4.5 LTS.
+## Exit codes
+
+Per-script sequential checks. `9` is a valid check code; there is no rule
+against it.
+
+| Code | Meaning |
+| --- | --- |
+| 0 | Success |
+| 1 | Uncaught exception (FATAL wrapper) |
+| 2 | argparse / usage |
+| 3 | Body datablock is not the authored half |
+| 4 | Authored centerline vert count ≠ 28 |
+| 5 | Evaluated verts ≠ `2n − c` (`--no-mirror` lands here) |
+| 6 | Evaluated on-plane verts ≠ centerline; also `--output` produced no file |
+| 7 | Evaluated Euler characteristic ≠ 2 |
+| 8 | Non-manifold edges in the evaluated shell |
+| 9 | Evaluated verts lack a mirrored partner |
+| 10 | Mirror partner deviation above tolerance |
+| 11 | Evaluated bbox not symmetric about X |
+| 12 | Mirrored-part origin off the plane |
+| 13 | Mirrored-part datablock is not the authored half |
+| 14 | Mirrored-part evaluated counts did not double |
+| 15 | Mirrored-part partner check failed |
+| 16 | Mirrored-part evaluated mesh stayed on one side |
+
+The `blender-smoke` workflow runs the check on Blender 5.2 LTS and 4.5 LTS
+(5.1 on the weekly cron, the `needs-5.1` PR label, or manual dispatch).
+Smoke does not pass `--output` or `--no-mirror`.

examples/car-mirror-symmetry/car_mirror_symmetry.py

@@ -10,10 +10,15 @@
 and the wheels mirror about their object origins sitting ON the symmetry
 plane. Failure is dramatically visible: a car with one side missing.
 
+``--no-mirror`` turns off the Mirror X axis on every mirrored object and
+still runs the evaluated-count check, so the half-car fails ``2n − c``.
+That is the falsifier (``--same-axis`` in export-preset-axis).
+
 By default it runs only the correctness check (no render) — the CI smoke
 check. Pass --output to also render a still:
 
     blender --background --python car_mirror_symmetry.py --                 # check only
+    blender --background --python car_mirror_symmetry.py -- --no-mirror     # must fail
     blender --background --python car_mirror_symmetry.py -- --output c.png  # + render
 """
 import bpy, bmesh, sys, os, math, argparse
@@ -269,7 +274,13 @@ def _symmetry_dev(verts, tol_plane):
     return dev, lone
 
 
-def check(objs):
+def check(objs, no_mirror=False):
+    if no_mirror:
+        for ob in [objs["body"]] + [w for w, *_ in objs["mirrored"]]:
+            for mod in ob.modifiers:
+                if mod.type == 'MIRROR':
+                    mod.use_axis[0] = False
+
     body = objs["body"]
     me = body.data
 
@@ -502,10 +513,12 @@ def main():
     p.add_argument("--output", default=None, help="optional: render a still PNG here")
     p.add_argument("--engine", default="eevee", choices=("eevee", "cycles"),
                    help="render engine for --output (cycles for GPU-less hosts)")
+    p.add_argument("--no-mirror", action="store_true",
+                   help="turn off Mirror X (must fail)")
     args = p.parse_args(argv)
 
     objs = build_car()
-    code = check(objs)
+    code = check(objs, no_mirror=args.no_mirror)
     if code:
         return code
 

examples/custom-normals-shade/README.md

@@ -73,12 +73,32 @@ strip light whose reflection exposes every normal discontinuity.
 # Cheap correctness check (no render) — the CI check:
 blender --background --python custom_normals_shade.py --
 
+# Falsifier: mark sharp at 20° while auditing 30°. Must exit non-zero.
+blender --background --python custom_normals_shade.py -- --mismatch-angle
+
 # Also render a still (EEVEE on a GPU host; use --engine cycles on GPU-less hosts):
 blender --background --python custom_normals_shade.py -- --output cans.png
 blender --background --python custom_normals_shade.py -- --output cans.png --engine cycles
 ```
 
-It exits non-zero on failure (legacy API resurrected, sharp-set/dihedral
-mismatch, broken normal welds, custom normals lost or dequantized in
-evaluation, or legacy-operator divergence drift). The `blender-smoke`
-workflow runs the check on Blender 5.2 LTS and 4.5 LTS.
+## Exit codes
+
+Per-script sequential checks. `9` is a valid check code; there is no rule
+against it.
+
+| Code | Meaning |
+| --- | --- |
+| 0 | Success |
+| 1 | Uncaught exception (FATAL wrapper) |
+| 2 | argparse / usage |
+| 3 | Legacy shading API present, or modern path missing |
+| 4 | Non-manifold edges (dihedral test undefined) |
+| 5 | Sharp set ≠ independent dihedral (`--mismatch-angle` lands here) |
+| 6 | Evaluated loop normals not welded/split as the sharp set promises |
+| 7 | Custom split normals lost or dequantized in evaluation |
+| 8 | `shade_auto_smooth` operator behavior drifted from the version split |
+| 9 | `--output` produced no file |
+
+The `blender-smoke` workflow runs the check on Blender 5.2 LTS and 4.5 LTS
+(5.1 on the weekly cron, the `needs-5.1` PR label, or manual dispatch).
+Smoke does not pass `--output` or `--mismatch-angle`.

examples/custom-normals-shade/custom_normals_shade.py

@@ -26,11 +26,16 @@
                   that ignores the return set; on 5.1 it FINISHES and adds
                   the NODES modifier. The portable path is the data API.
 
+``--mismatch-angle`` marks sharp at 20° and still audits against the 30°
+dihedral set, so the sharp-set match fails. That is the falsifier
+(``--same-axis`` in export-preset-axis).
+
 By default it runs only the correctness check (no render) — the CI smoke
 check. Pass --output to also render a still (the same can shaded flat /
 smooth-everywhere / by-angle, so a broken path reads as faceting or smear):
 
     blender --background --python custom_normals_shade.py --                 # check only
+    blender --background --python custom_normals_shade.py -- --mismatch-angle
     blender --background --python custom_normals_shade.py -- --output c.png  # + render
 """
 import bpy, bmesh, sys, os, math, argparse
@@ -244,15 +249,16 @@ def check_api_surface(me):
     return 0
 
 
-def check_by_angle(objs):
+def check_by_angle(objs, mismatch_angle=False):
     """set_sharp_from_angle must mark exactly the edges whose independently
     recomputed dihedral crosses the threshold — on every checked mesh."""
+    mark = math.radians(20.0) if mismatch_angle else ANGLE
     total_sharp = total_manifold = 0
     for obj in objs:
         me = obj.data
         for p in me.polygons:
             p.use_smooth = True
-        me.set_sharp_from_angle(angle=ANGLE)
+        me.set_sharp_from_angle(angle=mark)
         dih, nonmanifold = manifold_dihedrals(me)
         if nonmanifold:
             print(f"ERROR: {obj.name}: {nonmanifold} non-manifold edge(s) — the "
@@ -557,13 +563,17 @@ def main():
     p.add_argument("--output", default=None, help="optional: render a still PNG here")
     p.add_argument("--engine", default="eevee", choices=("eevee", "cycles"),
                    help="render engine for --output (cycles for GPU-less hosts)")
+    p.add_argument("--mismatch-angle", action="store_true",
+                   help="mark sharp at 20° while auditing 30° (must fail)")
     args = p.parse_args(argv)
 
     bpy.ops.wm.read_factory_settings(use_empty=True)
     can = build_jerry_can()
 
     for step in (lambda: check_api_surface(can["shell"].data),
-                 lambda: check_by_angle([can["shell"], can["rib"], can["neck"]]),
+                 lambda: check_by_angle(
+                     [can["shell"], can["rib"], can["neck"]],
+                     mismatch_angle=args.mismatch_angle),
                  lambda: check_normal_welds(can["shell"]),
                  lambda: check_custom_normals_roundtrip(can["shell"]),
                  check_legacy_operator):

examples/gltf-export-roundtrip/README.md

@@ -57,11 +57,44 @@ silhouette would lose the rounded edges.
 # Cheap correctness check (no render) — the CI check:
 blender --background --python gltf_export_roundtrip.py --
 
+# Falsifier: export_yup=False. Must exit non-zero (bbox is Z-up on disk).
+blender --background --python gltf_export_roundtrip.py -- --no-yup
+
 # Also render a still (EEVEE on a GPU host; use --engine cycles on GPU-less hosts):
 blender --background --python gltf_export_roundtrip.py -- --output crate.png
 blender --background --python gltf_export_roundtrip.py -- --output crate.png --engine cycles
 ```
 
-It exits non-zero on failure (RNA kwarg drift, cage drift, missing on-disk
-conversion, vertex-split drift, or any round-trip excursion beyond tolerance).
-The `blender-smoke` workflow runs the check on Blender 5.2 LTS and 4.5 LTS.
+## Exit codes
+
+Per-script sequential checks. `9` is a valid check code; there is no rule
+against it.
+
+| Code | Meaning |
+| --- | --- |
+| 0 | Success |
+| 1 | Uncaught exception (FATAL wrapper) |
+| 2 | argparse / usage |
+| 3 | Exporter/importer RNA kwargs drifted |
+| 4 | Base cage drifted from its closed form |
+| 5 | Authored UVs drifted from the box-map closed form |
+| 6 | Bevel produced no evaluated geometry |
+| 7 | On-disk node/mesh/generator contract drifted |
+| 8 | On-disk primitive/material binding count drifted |
+| 9 | On-disk POSITION bounds ≠ axis-converted bbox (`--no-yup` lands here) |
+| 10 | On-disk POSITION count ≠ evaluated loop count |
+| 11 | On-disk UV V-flip failed |
+| 12 | Re-import did not produce exactly one mesh |
+| 13 | Re-imported object carries a transform |
+| 14 | Material names drifted on re-import |
+| 15 | Re-import vert count ≠ evaluated loop count |
+| 16 | Round-trip position drift |
+| 17 | Round-trip normal drift |
+| 18 | Round-trip UV drift |
+| 19 | Re-import triangle count drifted |
+| 20 | Per-triangle material bindings drifted |
+| 21 | `--output` produced no file |
+
+The `blender-smoke` workflow runs the check on Blender 5.2 LTS and 4.5 LTS
+(5.1 on the weekly cron, the `needs-5.1` PR label, or manual dispatch).
+Smoke does not pass `--output` or `--no-yup`.

examples/gltf-export-roundtrip/gltf_export_roundtrip.py

@@ -8,8 +8,11 @@
    data itself — (x, y, z) -> (x, z, -y) on disk — with no node rotation.
    The check parses the exported .gltf JSON and asserts the POSITION accessor
    bounds equal the axis-converted evaluated bounding box, and that the node
-   carries neither rotation nor scale. Exporting with ``export_yup=False``
-   writes raw Z-up data that every engine will display lying on its back.
+   carries neither rotation nor scale. ``--no-yup`` exports with
+   ``export_yup=False`` and still runs that bbox check, so the +Y-up
+   conversion fails. That is the falsifier (``--same-axis`` in
+   export-preset-axis). Exporting with ``export_yup=False`` writes raw Z-up
+   data that every engine will display lying on its back.
 2. Modifiers ship evaluated geometry. ``export_apply=True`` applies the
    crate's bevel modifier: the re-imported mesh matches the
    depsgraph-evaluated mesh, not the base cage. With ``export_apply=False``
@@ -32,6 +35,7 @@
 check. Pass --output to also render a still:
 
     blender --background --python gltf_export_roundtrip.py --                 # check only
+    blender --background --python gltf_export_roundtrip.py -- --no-yup        # must fail
     blender --background --python gltf_export_roundtrip.py -- --output c.png  # + render
 """
 import bpy, bmesh, sys, os, math, json, struct, shutil, tempfile, argparse
@@ -244,7 +248,7 @@ def accessor_floats(idx, ncomp):
 # ---------------------------------------------------------------------------
 # The check. Distinct exit codes per contract; measured maxima printed on success.
 # ---------------------------------------------------------------------------
-def check(crate):
+def check(crate, export_kwargs):
     # contract 0 (version guard): every kwarg we rely on still exists.
     exp_props = {p.identifier for p in bpy.ops.export_scene.gltf.get_rna_type().properties}
     imp_props = {p.identifier for p in bpy.ops.import_scene.gltf.get_rna_type().properties}
@@ -285,7 +289,7 @@ def check(crate):
     tmp = tempfile.mkdtemp(prefix="gltf_roundtrip_")
     try:
         path = os.path.join(tmp, "crate.gltf").replace("\\", "/")
-        bpy.ops.export_scene.gltf(filepath=path, **EXPORT_KWARGS)
+        bpy.ops.export_scene.gltf(filepath=path, **export_kwargs)
 
         # contract 1 (on disk): +Y-up is baked into vertex data, no node transform
         g, acc_floats = read_gltf(path)
@@ -592,13 +596,18 @@ def main():
     p.add_argument("--output", default=None, help="optional: render a still PNG here")
     p.add_argument("--engine", default="eevee", choices=("eevee", "cycles"),
                    help="render engine for --output (cycles for GPU-less hosts)")
+    p.add_argument("--no-yup", action="store_true",
+                   help="export with export_yup=False (must fail)")
     args = p.parse_args(argv)
 
     bpy.ops.wm.read_factory_settings(use_empty=True)
     crate = build_crate()
     for m in make_materials():
         crate.data.materials.append(m)
-    code = check(crate)
+    kwargs = dict(EXPORT_KWARGS)
+    if args.no_yup:
+        kwargs["export_yup"] = False
+    code = check(crate, kwargs)
     if code:
         return code
 

examples/gn-modifier-inputs/README.md

@@ -22,7 +22,10 @@ Follows [`geometry-nodes-python`](../../skills/geometry-nodes-python/SKILL.md).
 # Cheap correctness check (no render) — the CI check:
 blender --background --python gn_modifier_inputs.py --
 
-# Force one side of the split (must fail on the other series):
+# Portable falsifier: write 1.0 to every modifier. Must exit non-zero.
+blender --background --python gn_modifier_inputs.py -- --same-scale
+
+# Force one side of the split (must fail on the other series, not all three):
 blender --background --python gn_modifier_inputs.py -- --api dict
 blender --background --python gn_modifier_inputs.py -- --api rna
 
@@ -31,10 +34,30 @@ blender --background --python gn_modifier_inputs.py -- --output stairs.png
 blender --background --python gn_modifier_inputs.py -- --output stairs.png --engine cycles
 ```
 
-It exits non-zero on failure (missing identifier, write/read raise, readback
-mismatch, evaluated Z-extent ≠ scale, or three extents not distinct). The
-`blender-smoke` workflow runs the check on Blender 5.2 LTS and 4.5 LTS
-(5.1 on the weekly cron).
+## Exit codes
+
+Per-script sequential checks. `9` is a valid check code; there is no rule
+against it. `10` is the shared framing helper.
+
+| Code | Meaning |
+| --- | --- |
+| 0 | Success |
+| 1 | Uncaught exception (FATAL wrapper) |
+| 2 | argparse / usage |
+| 3 | Scale input identifier missing on the tree interface |
+| 4 | Modifiers do not share one node_group |
+| 5 | Version-path write raised (`--api dict` on 5.2, `--api rna` on 4.5) |
+| 6 | Version-path read raised |
+| 7 | Readback ≠ intended scale (`--same-scale` lands here) |
+| 8 | Evaluated Z-extent ≠ intended scale |
+| 9 | Evaluated mesh not sitting on z=0 |
+| 10 | Gallery framing violation |
+| 11 | Evaluated extents not distinct |
+| 12 | `--output` produced no file |
+
+The `blender-smoke` workflow runs the check on Blender 5.2 LTS and 4.5 LTS
+(5.1 on the weekly cron, the `needs-5.1` PR label, or manual dispatch).
+Smoke does not pass `--output`, `--same-scale`, or `--api dict`/`rna`.
 
 ## Falsification
 

examples/gn-modifier-inputs/gn_modifier_inputs.py

@@ -10,10 +10,14 @@
 4.5 LTS and 5.1 write ``mod[identifier] = value``. 5.2+ removed ID
 properties on NodesModifier — that assignment raises TypeError — and
 the replacement is ``mod.properties.inputs.<identifier>.value``.
-``--api dict`` / ``--api rna`` force one side so the witness can fail
-on purpose.
+``--api dict`` / ``--api rna`` force one side of the 5.1/5.2 split — they
+fail on the *other* series, not on every binary. ``--same-scale`` writes
+1.0 to every modifier and still asserts 1 / 2 / 3, so the second cube's
+readback fails on all three. That is the portable falsifier
+(``--same-axis`` in export-preset-axis).
 
     blender --background --python gn_modifier_inputs.py --
+    blender --background --python gn_modifier_inputs.py -- --same-scale
     blender --background --python gn_modifier_inputs.py -- --api dict
     blender --background --python gn_modifier_inputs.py -- --output s.png
 """
@@ -178,7 +182,7 @@ def evaluated_z_extent(obj):
         ev.to_mesh_clear()
 
 
-def check(tree, objs, mods, api):
+def check(tree, objs, mods, api, same_scale=False):
     ident = scale_identifier(tree)
     if not ident:
         print("ERROR: Scale input identifier missing on the tree interface",
@@ -191,8 +195,9 @@ def check(tree, objs, mods, api):
         return 4
 
     for obj, mod, scale in zip(objs, mods, SCALES):
+        written = SCALES[0] if same_scale else scale
         try:
-            set_mod_input(mod, ident, scale, api)
+            set_mod_input(mod, ident, written, api)
         except Exception as e:
             print(
                 f"ERROR: {api} write of {scale} on {obj.name} raised "
@@ -368,11 +373,15 @@ def main():
         "--api", default="auto", choices=("auto", "dict", "rna"),
         help="force the 5.1 dict path, the 5.2 RNA path, or pick from bpy.app.version",
     )
+    p.add_argument(
+        "--same-scale", action="store_true",
+        help="write 1.0 to every modifier (must fail)",
+    )
     args = p.parse_args(argv)
 
     tree, objs, mods = build()
     api = _api_choice(args.api)
-    code = check(tree, objs, mods, api)
+    code = check(tree, objs, mods, api, same_scale=args.same_scale)
     if code:
         return code