exportSTEP rejects valid sweep+fuse compound ("Failed to read exported STEP file")

[andymai]

Summary

A geometrically-valid-looking shape built from sweep + fuseAll verifies fine (positive volume, sensible bounds, validSolid where checked) but exportSTEP returns Result.Err("Failed to read exported STEP file"). So a shape that all in-memory checks accept cannot round-trip to STEP — the primary interchange format.

Repro

A miniature spiral-staircase model (one of the brepjs-agent benchmark parts, #1124):

• Central column: cylinder
• Treads: annular-sector profile drawn with threePointsArcTo (outer + inner arcs), sketchOnPlane('XY').extrude(...) → ValidSolid, arranged helically (~20 of them)
• Balusters: vertical cylinder rods at each tread's outer-mid radius
• Handrail: sketchCircle(...).wire swept along a helical path via sweep(railProfile, railPath, { frenet: true })
• Everything combined with fuseAll([...])

The resulting shape:

• ✅ measureVolume > 0, getBounds sane, renders correctly in the viewer
• ❌ exportSTEP(shape) → Err("Failed to read exported STEP file") (the writer's read-back validation rejects it)

Suspected cause

The fused result is almost certainly a Compound containing a sub-shape that STEPControl_Writer (or the read-back step that validates the write) won't accept — likely a degenerate/near-degenerate face from the frenet sweep along the tight helix, or a non-manifold seam where the swept rail meets the balusters. The in-memory volume/bounds checks don't catch this because they don't exercise STEP's stricter topology/geometry validation.

Ask

1. Investigate whether the offending sub-shape comes from the sweep, the fuseAll, or the STEP writer itself.
2. Consider running a validity/heal pass (or surfacing the specific invalid sub-shape) before/at export, and
3. At minimum, surface a more actionable error than "Failed to read exported STEP file" — e.g. which sub-shape index/type failed, so callers can locate and heal it.

I can attach the full .brep.ts repro on request (it lives in gitignored benchmark scratch). Surfaced by the brepjs-agent work (#1124).

[andymai]

Root cause (investigated)

Reproduced with the #9 spiral-staircase benchmark part and bisected the failure. Findings:

1. The error is a WASM trap, not a write or read failure

The raw error from the kernel is:

RuntimeError: memory access out of bounds
  at wasm://wasm/…

i.e. the OCCT STEP writer traps (OOB) while transferring the shape. It is neither a writer "non-success status" nor an FS readback failure — but meshFns.ts classified any non-"STEP export failed" error as a file-read error, hence the misleading "Failed to read exported STEP file" message. (Fixed in #1128 — see below.)

2. Both export paths crash identically

• V8 stream path (StepStreamIO.exportSTEP, used for single shapes) → OOB
• V7 FS path (STEPControl_Writer, forced via multi-shape array) → same OOB

So a TS-level path fallback does not help; the crash is in the OCCT transfer itself.

3. The culprit is one degenerate-but-"valid" sub-solid

• fuseAll(parts) did not merge the parts — the result is a Compound of 65 separate solids (the parts are disjoint / barely touching). Volume is positive (123760).
• Bisecting export per-solid on a fresh kernel: solid[0] (vol ≈ 403) is the trigger.
• That solid passes isValid and validSolid, but getBounds throws on it, and STEP export OOB-crashes on it.

So three validity tiers disagree: BRepCheck (isValid/validSolid) says OK → bounding-box eval (getBounds) throws → STEP serialization hard-crashes. "Valid" in OCCT means topologically consistent, not serializable.

4. The crash poisons the kernel

A WASM OOB trap corrupts the Emscripten heap, so every subsequent kernel call in the session fails (this is why a naive per-solid loop reports "0/65" — only the first export actually crashed; the rest inherit a dead module). This makes a try/catch-and-continue mitigation ineffective for keeping a session alive — the only safe mitigation is to not make the crashing call.

What #1128 fixes (TS side)

Classifies the three cases distinctly so a WASM trap is reported as STEP_EXPORT_CRASHED (surfacing the real cause) instead of a phantom file-read error. Same fix for STL. This improves reporting only — the underlying OCCT crash remains.

What remains (kernel level)

The OOB crash on a BRepCheck-valid, degenerate sub-solid is a brepjs-opencascade (OCCT WASM) / upstream-OCCT issue. Notes for whoever picks it up:

• validSolid/isValid do not detect it; getBounds throwing does — a cheap pre-export guard could refuse export (clean Err) instead of crashing the kernel, if we want defense-in-depth in TS. (Tradeoff: an extra bounds probe per export; heuristic, not universal.)
• Worth checking which op produces the degenerate solid (the model uses extrude of threePointsArcTo annular-sector profiles and a frenet sweep along a helix).

[andymai]

Status update — TS-side resolved, kernel-level still open

✅ Resolved (brepjs / TypeScript side)

PR	What it does
#1128	Accurate reporting — a WASM trap from the writer now surfaces as STEP_EXPORT_CRASHED instead of the phantom "Failed to read exported STEP file".
#1131	Prevents the crash — exportSTEP/exportSTL run a cheap getBounds probe first. The degenerate solid makes getBounds throw catchably while the writer OOB-traps on the same geometry, so we now return a clean STEP/STL_EXPORT_UNSERIALIZABLE Err before the kernel-poisoning call. (Re-throws TypeError so genuine programming bugs still surface.)
#1133	Locates the bad piece (ask 3) — when the probe fails on a multi-solid compound, the error names the offending sub-solid index(es), e.g. …; offending sub-solid (of 65): index 0, so callers can heal/drop it instead of guessing.

Net effect: a serialization-hostile shape no longer kills the session, the error is accurate, and it points at the offending sub-solid. The probe is heuristic, not universal — it only catches shapes whose bounding-box evaluation also throws (which is the signature of this bug).

🔬 Reproduction findings

Attempted to reconstruct the degenerate solid[0] from the recipe (annular-sector threePointsArcTo treads + frenet handrail sweep). Three independent sweeps on the same occt-wasm build brepjs-agent uses:

• extreme frenet sweeps (R20, pitch 20, fat profile),
• a wide annular-tread parameter sweep (tiny angles, near-zero inner radius, thin bands),
• a full placed-and-fused 38→87-solid staircase,

…all produced valid, serializable geometry — zero getBounds throwers. So the degeneracy is not a generic property of these operations; it depends on specific numeric details of the actual solid[0] that aren't inferable from the description.

❌ Still open (kernel / upstream)

The root cause — OCCT's STEP writer OOB-trapping on a BRepCheck-valid but degenerate sub-solid — remains. Notes for whoever picks it up:

• It lives in brepjs-opencascade (prebuilt OCCT WASM); the actual STEPControl_Writer/StepStreamIO is compiled in via the Docker image. A fix means a Docker rebuild, and an OOB memory trap is not catchable in C++, so there's no binding-level shortcut — the real fixes are (a) stop emitting the degenerate geometry, or (b) fix OCCT.
• Unblock needed: the isolated solid[0] (e.g. toBREP-exported from the failing session). With it we can characterize the exact degeneracy and decide whether it traces to a brepjs operation (Docker-free fix) or warrants a minimal upstream OCCT repro.

Keeping this issue open to track the kernel-level fix.

[andymai]

Kernel root cause bisected — minimal repro is a disjoint fuseAll

Following the earlier investigation, I isolated the degeneracy down to a 2-solid minimal repro and characterized exactly why every in-memory check misses it.

Minimal reproduction

const r = exportSTEP(unwrap(fuseAll([tread0, rail])));
// -> Err(STEP_EXPORT_CRASHED: memory access out of bounds)

where tread0 is one annular-sector tread (threePointsArcTo profile + extrude) and rail is the frenet-swept handrail tube. The two solids are geometrically disjoint (tread R10–62 @ Z4–8; rail R66 @ Z14–130). Reproduces deterministically, including when both inputs are loaded back from BREP — so it's a property of the geometry, not of any in-memory op state.

What is and isn't the trigger (bisected)

• ✅ fuseAll([tread0, rail]) → corrupt (the N-way general fuse, BRepAlgoAPI_BuilderAlgo)
• ✅ fuseAll([…all treads, rail]), fuseAll([base, tread0, rail]) → corrupt
• ❌ pairwise fuse(tread0, rail) → clean (different OCCT algorithm)
• ❌ tread0 alone, rail alone, tread0 + plain box, rail + plain box → all clean
• ❌ balusters / column → irrelevant

So neither input is "poison"; it's the specific tread+rail pairing through the general-fuse list path. The fuse silently splits/corrupts the disjoint inputs (volumes stay correct), and the corrupt sub-solids are all PLANE/CYLINDRE faces — no NURBS, no NaN — pointing at a corrupt pcurve/topology representation from the boolean, not bad surface geometry.

Why no TS-side guard catches it

On the corrupt solid, all of these pass: isValid, validSolid, checkBoolean, mesh (real triangulation), getBounds, measureArea. So #1131's getBounds probe does not fire here — the only thing that saves us is #1128 classifying the writer's WebAssembly.RuntimeError as STEP_EXPORT_CRASHED. autoHeal/healSolid report success but the result still traps; fixShape fails. There is no known non-trapping check that flags it, and a caught writer trap still poisons the writer for the rest of the session (later valid shapes fail too). Conclusion: this can only be fixed at the kernel (OCCT BOPAlgo) level.

Status

• Added a real-geometry regression test (tests/stepExportDegenerate.test.ts) locking the "caught & classified, never a phantom file-read error" guarantee.
• Prepared a self-contained upstream repro (the two input BREPs + a runnable JS repro + a standalone OCCT C++ repro) for the kernel/OCCT side.

Leaving open for the kernel fix.

[andymai]

Upstream kernel issue filed with a self-contained repro (input BREPs + JS + standalone OCCT C++): andymai/opencascade.js#3. The kernel fix tracks there; this issue stays open until it lands.