Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel
Diagnostics and failure recovery
Drawing generation reports drawing-definition-incomplete when no qualified plan
accounts for the complete nominal body. --reference-only requests explicitly
incomplete review views. drawing-pmi-geometry-mismatch identifies conflicting
diameter/depth/quantity requirements; drawing-tolerance-envelope-invalid and
drawing-tolerance-zero-width reject contradictory dimensional limits. Missing
material, linear or angular requirements are recorded independently in definition
evidence and visibly marked on the PDF. Process capability is not inferred from a
successful export. See drawing generation.
Generic V2 build/validation errors use structured objects with code, severity, message, sourceFile, optional sourceSpan, line, column, and locationNote. The existing fatal spelling means an error that prevents admission; warning remains nonfatal. Parser route metadata is for debugging. An enclosing-declaration span is explicitly labelled when the legacy producer supplied no precise original-source provenance. Monaco consumes the same compiler presentation. Specialized domain commands are not yet all migrated to this representation.
Unknown canonical statements and Box fields are errors. Local 2D Concept layouts admit XY, XZ and YZ for Profile consumers. profile-layout-placement-unsupported rejects other layout selectors instead of substituting XY; profile-layout-spatial-members-unsupported identifies a non-XY layout mixing local guides with spatial semantic members. Use a traced Construction Plane for arbitrary supported orientations. SemanticSourceNotFound preserves the missing source and the provenance explanation. An accidental through-depth Pocket fails; explicit end: ThroughAll selects the admitted through cut. Box top-boundary Fillet with disjoint ThroughAll shaft/counterbore holes is supported; CombinedFeatureInteractionUnsupported identifies a hole touching the finish band or another hole. Unsupported combined selectors retain CombinedFeatureSelectionLost at the EdgeFinish declaration.
Exact face grafts and subdivision meshes
surf-face-pmi-projection-unsupported/surf-face-associated-target-unsupported: this edit cannot retain the required PMI/interface meaning. The predecessor remains authoritative; no metadata is silently dropped.surf-face-boundary-mismatch/surf-face-graph-unsupported: retain the named four-line boundary and affine parameter grid, or use explicit mesh sculpting for the broader deformation.FaceNhandles become stale after replacement.mesh-conversion-deviation-exceeded: increase sphere cage segments or explicitly authorize a larger finite conversion budget.mesh-vertex-unresolved/mesh-edge-unresolved: inspect the current cage; historical handles are not rebound by proximity.mesh-preservation-failed/mesh-local-foldover: the edit violates its protected vertex contract or reverses a predecessor face triangle.mesh-subdivision-budget-exceeded: refinement exceeds 24,576 faces.sculpt-mesh-export-format-unsupported: the selected MeshState produces STL or GLB, not STEP. Validation reportsMeshBuiltandstepExportAvailable: false; select an exact state for STEP.mesh-export-precision-exhausted: 32-bit coordinates cannot retain a finite closed output mesh. No new artifact is emitted.mesh-export-precision-budget-exceeded: coordinate quantization exceeds the inheritedmaximumDeviationbudget, even though topology may remain closed.
Global mesh self-intersection remains NotCertified, independent of successful
topology and local foldover checks.
Profile rim finishes
ProfileBoundaryEdgeFinishSequenceUnsupported: this Profile/Compose owner admits one finish operation. Multiple requested finishes cannot be compiled as a first-operation-only result. Uncalled recipes do not count as operations.ProfileEdgeFinishInsetCollapse: the requested circular-segment finish reaches or exceeds its inradius. Reduce the radius/distance to retain a cap.ProfileBoundaryFilletInsetInvalid/ProfileBoundaryChamferInsetCollapse: an inset polygon edge collapses or reverses; reduce the finish size.ProfileEdgeFinishJunctionUnsupported: a sharp curved junction lacks a qualified shared intersection for this profile family. This does not require ordinary CAD authors to supply a general surface blend.ProfileEdgeFinishMixedShellFinishExceedsHostThickness: the finish consumes the full thickness rather than leaving the admitted stock region.ProfileBoundaryFilletEndClearanceRequiresOpenChain: removeendClearancefrom a closed-loop finish, or select the intended open chain.ProfileEdgeFinishMiterNumericToleranceExhausted/ProfileEdgeFinishMiterRefinementLimit: the finite miter representation cannot meet its certified tolerance within the bounded numerical budget. No artifact is admitted.
When a planner reports one unambiguous EdgeFinish operation, the diagnostic uses that enclosing declaration's span; expanded provenance is mapped where retained.
Circular Sweep
firmament-sweep-section-invalid: circular diameter is missing, non-finite, or non-positive.firmament-sweep-path-disconnected: a segment does not continue from its predecessor.firmament-sweep-path-not-tangent: adjacent segments meet at a sharp corner.firmament-sweep-path-nonplanar: the path is outside the supported planar XY boundary.firmament-sweep-bend-radius-too-small: an arc radius does not exceed the section radius.firmament-sweep-self-intersection: nonadjacent centerline regions violate required clearance.firmament-sweep-material-unresolved: the material identity is absent from the deployed catalog.
Formed Wire
wireform-diameter-invalid: stock diameter is missing, non-finite, or non-positive.wireform-start-frame-invalid: Origin/Tangent/Up is missing, the tangent is zero, or Up is parallel to the tangent.wireform-straight-length-invalid:<operation>: Straight length is not finite and positive.wireform-bend-radius-invalid:<operation>: centerline bend radius is not positive or does not exceedDiameter / 2. This local geometric check runs before body construction.wireform-bend-angle-invalid:<operation>: Bend angle is zero or exceeds ±180°.wireform-bend-plane-invalid:<operation>: Plane is not current localUporRight.wireform-material-unresolved: the material identity is absent from the deployed catalog.wireform-self-intersection:<opA>:<opB>: nonadjacent wire portions violate diameter clearance. This later global check uses conservative 3D chord/sagitta bounds and rejects intentional contact.
The Standard Paperclip template has stricter product policy (InnerBendRadius > WireDiameter) than generic WireForm's geometric Radius > Diameter / 2; named Template Require clauses can therefore reject a Paperclip specialization before WireForm lowering.
Surface trim closure
surf-intersection-none: the qualified supports do not intersect inside the bounded domains.surf-intersection-ambiguous: multiple branches exist without an admissible seed/reference boundary.surf-pcurve-invalid: a face-local UV curve is missing, outside its domain, misoriented, or reconstructs away from the shared 3D edge.surf-trim-loop-open: ordered trim coedges do not close through shared topology vertices.surf-inner-loop-invalid: an opening loop is not a valid bounded hole in the replacement face.surf-extension-unsupported: the surface family, degree, stability envelope, or requested extension is outside the qualified matrix.surf-imported-selector-unresolved: a STEPADVANCED_FACEidentity does not resolve to exactly one current face.surf-association-target-removed: PMI or an Assembly Interface has no explicitPreservedcorrespondence; Aetheris refuses name- or proximity-based rebinding.surf-association-current-geometry-missing: an explicitly preserved association references a face absent from the outputBodyState.surf-blend-g2-unsatisfied: a constructible blend candidate fails the hard transverse normal-curvature contract and is rejected before scoring.surf-blend-candidate-rejected: compact per-candidate evidence emitted when the complete request has no selectable candidate.surf-blend-no-eligible-candidates: representation, continuity, topology, locality, or preservation gates leave no candidate at the declared minimum continuity.surf-blend-override-ineligible:UseCandidatenames an absent candidate or one that fails the active hard requirements.surf-blend-locality-violation: a candidate exceeds the authorized transition envelope and cannot enter utility judgment.surf-boundary-g2-violation: realized exact boundary second-difference evidence exceeds the planar-shoulder normal-curvature tolerance.surf-certified-bounds-invalid: a claimed exact polynomial bounds certificate does not contain deterministic surface samples.surf-selector-target-replaced: a historical native or imported selector has an explicit successor and cannot be reused.
Construction-state replay and SectionChain sculpting
bodystate-operation-replay-failed: replay stopped atomically at the named typed operation; the reported predecessor remains authoritative.bodystate-operation-order-invalid: an operation's authored predecessor does not equal the preceding operation's authored output; replay does not reorder or guess intent.bodystate-operation-version-unsupported: the retained operation payload version is not admitted.bodystate-operation-support-missing: a semantic support read by an operation is absent; Aetheris does not guess a nearest face.bodystate-preserved-region-modified: realized construction touched a protected semantic region.section-chain-add-not-attached: the additive terminal does not exactly correspond to its support, or no positive connected volume resulted.section-chain-add-remote-intersection: a non-terminal additive section crosses the predecessor outside the intended attachment.section-chain-remove-no-material: the admitted removal corridor does not remove positive bounded material.section-chain-remove-disconnects-body: a duct reaches the protected outer boundary and would sever the admitted housing result.section-chain-housing-base-unsupported: an upstream crown/patch changed the predecessor outside the currently qualified planar composition lane.
Start with aetheris validate source.firmament --json; use build when geometry, AP242, assertions, or artifacts are involved. A diagnostic code is the stable automation key, while its message identifies the value/target and expected category where useful.
Common recovery patterns:
| Failure | What to check |
|---|---|
| unknown keyword/Template | spelling, Use declaration, and qualified Template name |
| missing Template argument | the Template's typed parameter list or Forge describe output |
| unit mismatch | use the required dimension (mm, deg, N) rather than a bare/wrong-dimension value |
firmament-v2-polyhedron-face-count-unsupported |
Polyhedron<N> requires a compile-time regular convex face count: 4, 6, 8, 12 or 20; N is not the side count of a prism. |
firmament-v2-ellipsoid-radii-invalid |
Supply three finite positive X/Y/Z semiaxes with length units in radii. |
firmament-v2-uniform-stock-fillet-unsupported |
Use one EdgeFinish<Fillet> with target: AllEdges, positive radius and no face selector. A body that is not Box or Polyhedron stock is built first and rounded whole, which reports firmament-uniform-rounding instead; this code remains for chamfers, several AllEdges finishes and validate --parse-only. |
firmament-uniform-rounding |
Rounding every edge of the built body was refused; the message names why. uniform-rounding-spline-edge-unsupported / -elliptical-edge-unsupported: the body has those edges (count and ids given); use a local EdgeFinish on the edges you need. -mixed-vertex-unsupported: the named corner joins two concave edges and a convex one (a boss's foot corner). -split-face-unsupported: the named faces lie on one plane (a face split in two by its construction). -curved-face-unsupported: a face is not a plane, cylinder or cone. -edge-unsupported / -vertex-unsupported: the named edge's faces do not share its line or axis, or the named corner joins other than three edges. -radius-too-large / -radius-consumes-faces: the message says what the radius used up or where the ball reached another face; use a radius below the one reported. |
UniformFilletRadiusTooLarge |
Reduce the radius below the reported stock inradius; this construction requires positive remaining planar faces and edge spans. |
drawing-pmi-target-unlocated |
The PMI needs a geometric face association. Automatic generation refuses a model-center leader. |
drawing-pmi-value-unavailable |
Supply an admitted finite PMI nominal/depth; a missing measure is not interpreted as zero. |
drawing-layout-impossible |
Use fewer PMI entries per authored view or a larger allocation; labels, strokes and sheet keepouts must remain clear. |
drawing-title-block-overflow / drawing-notes-overflow |
Shorten presentation metadata/notes or use an additional authored sheet. Text was not truncated. |
drawing-signoff-incomplete |
Provide both a role name and its ISO date, or leave both blank; unperformed reviews must remain blank. |
| unknown material | one of the four exact catalog references in the materials guide |
| unresolved PMI target | named hole/face selector exists in the same semantic domain |
| invalid tolerance | PlusMinus(plus, minus) uses Length values for a diameter |
| Sheet Metal region mismatch | use a named planar region such as Base, not face(+Z) |
sheetmetal-hole-domain-syntax |
replace Model Hole<Shaft> with Sheet Metal Hole Name syntax |
sheetmetal-pmi-domain-syntax |
use Manufacturing plus DatumFeature targeting a named Sheet Metal region |
| inlineSTEP file/face failure | resolve the file relative to the source and use an existing AP242 face identity |
| empty FEA selection | selected face exists and intersects occupied cut cells at the requested lattice |
| unsupported constitutive model | Preview 3 production scope is linear elastic isotropic |
Successful builds enforce PMI/AP242 parity. firmament-v2-pmi-export-evidence-mismatch means a supported record failed independent export reinspection; no artifact is written. See targets for cross-domain forms.