A defaulted scalar's `.csg` is byte-identical to a correct part's, so no `.csg` rule can decide #308

[CameronBrooks11]

Epic #305. The uncovered remainder of #308, which PR #329 closed only in part.

What is wrong

#308's headline reproduction still passes at exit 0 on both pinned engines,
and PR #329 does not fix it. That PR guards Unable to convert, which
OpenSCAD prints for a vector- or **transform-**valued parameter it could
not convert. A scalar dimension taking undef is narrated by nothing at
all.

Measured under both engines the CI matrix pins — apt 2021.01 and the pinned
2026.08.01 snapshot — each source rendered with
openscad --export-format binstl -o out.stl p.scad, each o = undef:

source	stderr, both engines
linear_extrude(o) square([40,30]);	(nothing)
linear_extrude(height=o) square([40,30]);	(nothing)
cube(o);	(nothing)
cube(size=o);	(nothing)
cylinder(h=o, d=10);	(nothing)
sphere(o);	(nothing)
circle(r=o);	(nothing)
resize(o) cube(5);	(nothing)
linear_extrude(o + 1) square([40,30]);	WARNING: undefined operation (undefined + number)
cube(o + 1);	WARNING: undefined operation (undefined + number)
cylinder(h = o + 1, d = 10);	WARNING: undefined operation (undefined + number)

Every one of them exits 0 and exports a clean, watertight, single-solid mesh
built to a dimension nobody wrote down. #308's own example is the ninth row:
100 mm tall because a name was undefined, and no Unable to convert line
anywhere in stderr.

Why the obvious signals do not work

undefined operation cannot be used on the success path. It was tried in
PR #306 and reverted: holes = 4; echo("holes: " + holes); — + where
str() was meant — prints undefined operation (string + number) beside a
completely correct 272-facet part.

Nor can its operand types. The idea that (undefined + number) marks the
dimension case and (string + number) marks the echo case does not survive
contact with an optional parameter left at its undef default:

o = undef;
echo("holes: " + o);          // WARNING: undefined operation (string + undefined)
cube([40,30,6]);              // ... beside geometry that is exactly right

Both engines, measured. So undefined as an operand is not evidence that the
value reached geometry.

And the silent rows have no signal at all. For linear_extrude(undef)
there is no warning to key on, no exit code, and nothing in the export.

What this means

Any fix needs a channel other than stderr. partspec lint's tier 2 already
reads the .csg export, which is evaluated before any boolean runs and
is where a substituted default would be visible as a literal — that is the
most promising lead, but it is a lead and not a design, and lint exits 0
whatever it finds, so it is advisory by construction.

Until then this shape is uncovered, and
src/partspec/engines/openscad.py's _SUBSTITUTED_VALUE_MARKERS docstring
says so rather than implying #308 closed.

[CameronBrooks11]

Design proposal for #332 and #338 — measured, not implemented

Everything below was re-run at w3-scad HEAD (branch off main@60d1709) under
both pinned engines: apt openscad 2021.01 and
PARTSPEC_OPENSCAD=.../squashfs-root/AppRun 2026.08.01. Cross-linked from #338.

Conclusion up front: the .csg tier cannot decide either issue, and the
reason is not "not yet" — it is that a defaulted part's .csg is byte-identical
to a correct part's. The channel #332 hoped for does not carry the signal.
The recommendation is therefore an advisory lint rule plus a contract-authoring
rule, not a new refusal. Details, with the measurements, below.

---

1. #332's table re-verified — with two corrections

Each source o = undef; plus the row, rendered
openscad --export-format binstl -o out.stl p.scad.

#	source	stderr 2021.01	stderr 2026.08.01	exit	facets
1	linear_extrude(o) square([40,30]);	(nothing)	(nothing)	0	12
2	linear_extrude(height=o) square([40,30]);	(nothing)	(nothing)	0	12
3	cube(o);	(nothing)	(nothing)	0	12
4	cube(size=o);	(nothing)	(nothing)	0	12
5	cylinder(h=o, d=10);	(nothing)	(nothing)	0	60
6	sphere(o);	(nothing)	(nothing)	0	26
7	circle(r=o);	(nothing)	(nothing)	1	no STL
8	resize(o) cube(5);	(nothing)	(nothing)	0	12
9	linear_extrude(o + 1) square([40,30]);	undefined operation (undefined + number) twice	once	0	12
10	cube(o + 1);	undefined operation (undefined + number)	same	0	12
11	cylinder(h = o + 1, d = 10);	undefined operation (undefined + number)	same	0	60

The stderr column is exactly right, eleven for eleven. Two corrections to the
prose around it:

• Row 7 does not exit 0. circle() is 2D, so the STL export refuses it:
  exit 1, no STL, on both engines (2026.08.01 says
  Current top level object is not a 3D object.; 2021.01 says nothing matching
  WARNING|ERROR and exits 1 anyway). partspec reports that as a build failure,
  not a silent pass — so the sentence "Every one of them exits 0 and exports a
  clean, watertight, single-solid mesh" holds for ten of the eleven.
• Row 9 prints the warning twice on 2021.01, once on 2026.08.01. Cosmetic,
  but it is the only per-engine difference in the whole table.

Everything else — including "undefined as an operand is not evidence that the
value reached geometry" — reproduces.

---

2. What the .csg tier can actually see. I went and looked.

openscad -o tree.csg p.scad, both engines, all eleven rows plus #338's cases.

2.1 The eleven rows

#	what the .csg contains (identical on both engines unless noted)
1, 2, 9	linear_extrude(height = 100, ...) { square(size = [40, 30], ...); }
3, 4, 10	cube(size = [1, 1, 1], center = false);
5, 11	cylinder($fn = 0, $fa = 12, $fs = 2, h = 1, r1 = 5, r2 = 5, center = false);
6	sphere($fn = 0, $fa = 12, $fs = 2, r = 1);
7	circle($fn = 0, $fa = 12, $fs = 2, r = 1);
8	resize(newsize = [0,0,0], auto = [0,0,0], convexity = 0) { cube(size = [5,5,5], ...); }

So #332's lead — "a substituted default would be visible as a literal" — is
true and useless. It is visible as a literal, and so is a correct value.

The decisive measurement. Four correct sources, each written by hand to the
value the engine substitutes, exported to .csg beside the defaulted one:

defaulted source	correct source	cmp -s bad.csg good.csg, 2021.01	2026.08.01
o=undef; cube(o);	cube(1);	IDENTICAL	IDENTICAL
o=undef; linear_extrude(o) square([40,30]);	linear_extrude(100) square([40,30]);	IDENTICAL	IDENTICAL
o=undef; cylinder(h=o,d=10);	cylinder(h=1,d=10);	IDENTICAL	IDENTICAL
o=undef; sphere(o);	sphere(1);	IDENTICAL	IDENTICAL

Any rule that refuses the left column refuses the right column, byte for
byte. cube(1), sphere(1), cylinder(h=1) are ordinary correct code. That
is the false exit 4 on a correct part this repo is most careful about, and it is
not a risk here — it is a certainty, provable from the file.

2.2 undef in the .csg is not a signal either

It does occur — and it occurs on correct parts:

polygon([[0,0],[10,0],[0,10]]);      # a completely correct part
  -> polygon(points = [[0, 0], [10, 0], [0, 10]], paths = undef, convexity = 1);   BOTH engines

paths = undef is the default serialization. And where undef genuinely
reaches a parameter, the two engines disagree:

o = undef; polygon(points=o);
  2021.01     polygon(points = undef, paths = undef, convexity = 1);
  2026.08.01  polygon(points = [],    paths = undef, convexity = 1);

So keying on the token undef would refuse every correct polygon() on both
engines and give one source two different answers on the two pinned engines —
F13 inside the detector itself.

2.3 #338's two cases

(a) the vanished loop. This is the one place the .csg carries something
stderr does not:

module rail(n = undef) { cube([40,8,6]); for (i = [1:n]) translate([i*8,0,6]) cube([6,8,4]); }
rail();

BOTH engines:  group() { cube(size = [40, 8, 6], center = false); group(); }
n = 4      ->  group() { cube(...); group() { multmatrix(...) {...} x4 } }

An empty group() where children were expected. Real signal, zero cost to
read — and it false-fires immediately. A correct part:

module frame(pins = []) { cube([40,8,6]); for (p = pins) translate([p,0,6]) cube([6,8,4]); }
frame();
  BOTH engines:  group() { cube(size = [40, 8, 6], center = false); group(); }

Byte-identical to the defect. for over an empty list, if (false), and a
module invoked without children all produce it, and they are all correct.

(b) n = undef; r = [0:n]; h = r[2]; linear_extrude(h) square([40,30]);

BOTH engines:  linear_extrude(height = 100, ...) { square(size = [40, 30], ...); }

Row 1 again, byte for byte. Nothing distinguishes it from
linear_extrude(100) square([40,30]).

(c) the protected echo case from PR #306 / round-2 of #329 — the one a fix
must not refuse:

module plate(w, h, holes = undef) { echo("hole positions:", [0:holes]); difference(){...} }
plate(40, 30);

BOTH engines:  group() { difference() { cube(size = [40, 30, 6], center = true);
                                        cylinder($fn = 64, ..., h = 20, r1 = 4, r2 = 4, center = true); } }

Clean, and identical to the same source with the echo deleted — an echo
leaves no node at all. That is the one piece of good news: a .csg-based
mechanism has no visibility into echo-only faults, so it cannot reproduce
#306's and #329's false refusal. It also cannot see (b), which is the same
fact from the other side.

---

3. What it would cost

Cost is not the blocker, but it is not small, and it is worth having on the
record because it applies to any future .csg rule.

• One extra engine invocation per file. lint_scad_tier2 already pays it.

• .csg has no locations. No file, no line, anywhere, on either engine.
  Modules are flattened, loops unrolled, if erased. Every "correlate by source
  line" design — A defaulted scalar's .csg is byte-identical to a correct part's, so no .csg rule can decide #308 #332's, Geometry vanished from a failed range makes a part too small; a two-sided envelope is what catches it #338's and A fault inside % background geometry refuses a part whose exported mesh is byte-identical to the correct one #336's alike — has nothing on the .csg
  side to correlate against.

• A file whose .csg contains a " is refused whole (lint.py, PR feat(lint): tier 2 — the geometry rules, over the folded tree #125
  re-review: the format does not escape string interiors, so no parse of such a
  file can be trusted). Measured over this repository's own 25 .scad files:
  4 of 25 get no tier-2 answer on 2021.01, 3 of 25 on 2026.08.01. The
  numbers differ because import_stl() was removed between the two engines, so
  the coverage of a .csg rule is itself engine-dependent. Any file using
  text(), import() or surface() is in this set. For an advisory rule that
  is an honest unsupported entry; for a refusal it would have to become
  incomplete (exit 2) on correct parts, which trades one false red for
  another.

• The .ast export is a real second channel, and it is the expensive one.
  openscad -o out.ast p.scad emits the engine's own re-serialization of the
  unevaluated source, include<>-expanded into one flat text, with module
  definitions and their defaults intact — identical on both engines:

  module widget(n = undef) {
  	cube([10, 10, LIB_H]);
  }
  LIB_H = undef;
  widget();
  

  Paired with the .csg this is exactly the two inputs the problem needs: the
  .ast says the argument was a name, the .csg says the folded value is the
  module's default. But the .ast is full OpenSCAD source syntax, not the
  literal-only subset csg.py exists to read — so consuming it means the
  full-language parser lint tier 2: geometry-dependent rules over the .csg tree, prior-art first #118's prior-art survey deliberately refused (sca2d is
  GPLv3, tree-sitter is a whole grammar) — and it carries no locations
  either, so the AST-node-to-CSG-node correlation across flattened modules and
  unrolled loops remains unsolved. Two hard halves, for a rule whose false
  positives are shown in §2.1.

• No engine flag helps. Measured on rows 1, 3 and 5, both engines:
  --check-parameters=true --check-parameter-ranges=true --hardwarnings
  changes nothing — exit 0, empty stderr. -o out.term prints
  No top-level CSG object and is useless here.

---

4. What it would refuse falsely — the decisive question

Answered above, and worth collecting:

candidate rule	falsely refuses	evidence
.csg node carries the module's default literal	cube(1), sphere(1), cylinder(h=1), linear_extrude(100)	§2.1 — the .csg files are byte-identical
undef token in the .csg	every correct polygon() (paths = undef)	§2.2 — and diverges between engines
empty group() in the .csg	for (p = []), if (false), a childless module	§2.3(a) — byte-identical to the defect
source-side "a name bound to undef reaches geometry"	the standard OpenSCAD optional-parameter idiom (module m(chamfer = undef) { if (is_undef(chamfer)) ... }), which is how BOSL2 and most libraries spell "not supplied"	not a .csg rule at all, but it is the obvious tier-1 alternative and it over-fires on the language's own convention

The protected echo case (§2.3(c)) is the one thing a .csg rule would not
falsely refuse — because it cannot see it, which is the same reason it cannot
see #338(b).

---

5. One mechanism or two?

Neither issue gets a .csg mechanism, so the question resolves differently
than it was posed.

• A defaulted scalar's .csg is byte-identical to a correct part's, so no .csg rule can decide #308 #332 and Geometry vanished from a failed range makes a part too small; a two-sided envelope is what catches it #338(b) are one shape: a scalar dimension defaulted, mesh
  well-formed, part the wrong size. Whether the undef arrives directly or via
  a failed range is irrelevant — the .csg is the same file. One answer covers
  both, and Geometry vanished from a failed range makes a part too small; a two-sided envelope is what catches it #338(b) should be tracked with A defaulted scalar's .csg is byte-identical to a correct part's, so no .csg rule can decide #308 #332 rather than separately.
• Geometry vanished from a failed range makes a part too small; a two-sided envelope is what catches it #338(a) is a different shape: geometry that vanished, part the wrong
  smallness. It wants a different answer, and it matters that it does —
  see §6.
• A fault inside % background geometry refuses a part whose exported mesh is byte-identical to the correct one #336 is a third and is already decided (documented, keeps refusing). Its
  proposed .csg correlation dies on the same "no locations" fact as these.

---

6. The recommendation

There is a mechanism that catches all three, it is already shipped, and it is
not a guard: a contract that asserts a dimension. Measured at HEAD, both
engines, contract = watertight() + solid_count(1) + an envelope:

source	envelope(max=(40,30,6))	envelope(min=max=(40,8,10))
#332 row 1 (linear_extrude(undef))	FAIL, exit 1	—
#338(b) (range → linear_extrude)	FAIL, exit 1	—
#338(a) (rail(), loop vanished)	PASS, exit 0	FAIL, exit 1
#338(c) (protected echo, correct part)	PASS, exit 0	—
rail() with n = 4 (correct part)	—	PASS, exit 0

Identical on 2021.01 and 2026.08.01. Note the third row: a one-sided max
envelope does not catch geometry that vanished, because the part got
smaller. That is the concrete reason #338(a) is a different shape, and it is a
contract-authoring rule worth stating in as many words.

So the proposal is three pieces, in decreasing order of confidence:

1. Say it in the authoring guidance (cheapest, highest value): a contract
   whose only geometry claims are watertight() and solid_count() cannot
   catch a dimensional fault, because it asserts no dimension. A defaulted scalar's .csg is byte-identical to a correct part's, so no .csg rule can decide #308 #332's and
   Geometry vanished from a failed range makes a part too small; a two-sided envelope is what catches it #338's reproductions are all built on exactly that contract. And a max-only
   envelope cannot catch geometry that disappeared — for anything built by a
   loop or an if, assert a lower bound too. (Files owned by other lanes —
   SPEC-contract.md, skills/contract-authoring,
   skills/openscad-authoring. Not touched here; needs an owner.)
2. An advisory lint tier-1 rule, engine-free: a top-level x = undef;, or
   a module parameter defaulted undef, whose name reaches a geometry call
   without an is_undef/== undef test on the path. lint exits 0 whatever it
   finds (LINT.md), which is exactly where a rule with the §4 false-positive
   profile belongs: it can be noisy about the optional-parameter idiom without
   ever failing a correct part. This is the honest home for A defaulted scalar's .csg is byte-identical to a correct part's, so no .csg rule can decide #308 #332's signal.
3. Nothing on the success-path guard. No new stderr marker and no .csg
   refusal. _SUBSTITUTED_VALUE_MARKERS and _NON_GEOMETRY_CONVERSIONS keep
   their docstrings' current statement — that these shapes are uncovered — and
   A defaulted scalar's .csg is byte-identical to a correct part's, so no .csg rule can decide #308 #332 and Geometry vanished from a failed range makes a part too small; a two-sided envelope is what catches it #338 stay open as documented remainders rather than as work
   waiting for a channel that §2 shows does not exist.

If (3) is accepted, the honest next step is to retitle #332 and #338 from "this
needs a fix" to "this is the boundary of what stderr can decide, and here is
what covers it instead", and to fold #338(b) into #332.

---

7. Found while measuring — not part of this proposal

for (i = [1 : 0]), a descending range with a positive step, builds a
different part on the two pinned engines:

for (i = [1 : 0]) translate([i*10, 0, 0]) cube(2);

2021.01     exit 0, 24 facets, TWO cubes at x=0 and x=10, stderr silent
2026.08.01  exit 1, no STL, `WARNING: begin is greater than the end, but step is positive`

That is FAILURE-MODES entry 1's class (F13) with no diagnostic at all on the
older engine. Filed separately.