kSTEP 0.2.0

kSTEP 0.2.0 — 2026-10-22 (pre-release)

Third pre-release. It turns kSTEP from a product-structure tool into one that models, exports and reads
back geometry: kstep export writes product structure and placed assembly geometry, kstep import reads
STEP files (kSTEP, OCCT, FreeCAD) back, the OCCT bridge gains booleans, holes, revolve and chamfer, and a
sketch DSL with geometric edge selectors replaces opaque edge indices. As before, the GitHub release carries
a platform-independent JVM-only kstep-cli-0.2.0.zip (about 86 MB because it bundles the Kotlin compiler for
*.kstep.kts scripts) and a SHA-256 checksum, and nothing is published to Maven Central or Homebrew.

Geometry, sketches and kstep import need the native bridges. The zip is built without them, so those
features report a clear "unavailable" error there; build from source with a system OpenCascade (Linux
x86-64, or macOS arm64 via Homebrew) to use them. Interoperability is verified with OpenCascade-based readers
(OpenCascade's typed reader and FreeCAD), not yet with other CAD/PLM systems.

Added

• Sketch DSL and geometric edge selection (ADR-0031, Welle L). New module kstep-sketch
  (dev.kstep.sketch): sketch { } with points, lines, arcs, circles, horizontal/vertical/distance/length/
  coincident/pointOnLine/parallel/perpendicular and the sugar rectangle/offset; Sketch.solve( requireFullyConstrained, maxIterations) analyses degrees of freedom in plain Kotlin (redundant and
  contradictory constraints are named before the solver runs), solves through PlaneGCS and verifies the result;
  SolvedSketch.toRegion()/extrude/revolve/extrudeFeature/revolveFeature. Structured failures:
  SketchException with SketchErrorKind, SketchSolverUnavailableException. Circle/arc radii are fixed
  measures in this version. kstep-geometry: Edges/Faces selectors (parallelTo, ofType, atMax, atMin,
  ofFace, longest, shortest, seams, combined with and/or/minus), Direction3, Point3,
  SelectionTolerance, EdgeSelection.resolve, EdgeSelectionException (candidate list, expected count),
  OcctKernel.selectEdges and selector overloads of fillet/chamfer (the index API is unchanged),
  OcctShape.edges/faces (EdgeInfo/FaceInfo), SelectedFilletFeature/SelectedChamferFeature with
  SelectEdges/TrackedEdges (edges followed through later operations via OCCT's Modified/IsDeleted
  history: filletWithHistory, chamferWithHistory, booleanWithHistory, translateWithHistory,
  holeWithHistory, EdgeHistory, TrackedShape), FeatureRebuildException.selectionFailure, and regions
  with arcs, circles and holes (ProfileRegion, OcctKernel.extrudeRegion/revolveRegion,
  ExtrudeRegionFeature/RevolveRegionFeature). Scripts import dev.kstep.geometry.select.* and
  dev.kstep.sketch.* by default. New error codes KSTEP-S-009 (SKETCH_SOLVER_UNAVAILABLE), KSTEP-S-010
  (SKETCH_INVALID) and KSTEP-S-011 (EDGE_SELECTION_FAILED); KStepScriptOutcome.RuntimeError gained a
  code property (default KSTEP-S-003), and --output json reports it. Native: no new OCCT toolkit; new JNI
  functions nativeShapeEdgeInfo/FaceInfo/FaceEdges, native*Tracked, nativeExtrudeRegion/
  nativeRevolveRegion, each limit re-checked natively. Examples export-sketch-plate-with-hole,
  export-box-fillet-z-edges, export-box-chamfer-top-edges, export-pocket-tracked-fillet,
  hello-sketch-unconstrained; interop check scripts/interop/verify-sketch-selection.sh. Gate (2026-10-22, macOS
  arm64, OCCT 7.9.3): clean check -Pkstep.occt.require=true -Pkstep.planegcs.require=true --no-build-cache, 1590
  tests, 0 failures, 0 errors, 8 skipped (inverse-/property-gated); release-style build without natives: 0 failures,
  verify-dist.sh green.

• kstep import <file.step> (ADR-0030, Welle K): reads a STEP file (kSTEP, OCCT, FreeCAD) back through OCCT's
  XCAF reader and reports product structure, per-part volume/faces/bounding box, the expanded placed
  occurrences and totals, as text or --output json; --validate checks the AP242 V1 entities, --render <out.svg|png|glb> renders the imported geometry. Read-only apart from --render. Kotlin API:
  dev.kstep.shape.importer.StepImporter/ImportedStepModel/StepImportValidation,
  OcctKernel.readStep/OcctStepDocument, OcctShape.boundingBox, BoundingBox, Placement.fromRowMajor3x4
  and rowMajor3x4, StepImportLimits, OcctImportLimitException, MeshPreview (the SVG/PNG/GLB encoders
  of PreviewRenderer, output unchanged). Input hardening: no symbolic links, regular files only, 50 MB cap,
  extern-document references rejected, entity/node/part/face/occurrence/depth limits. Error codes
  KSTEP-I-001 to KSTEP-I-012. Linux CI that requires OCCT now installs libocct-ocaf-dev. New interop
  tools: dump_xcaf_tree nested, freecad_make_box.py, verify-import.sh.

• kstep export merges the geometry of shape(...) registrations into the exported Part 21 file
  (ADR-0027). Ap242ShapeExporter.export(header, roots, assignments) / exportToFile accept all
  roots and several shapes (one per product definition, limits MAX_SHAPES and
  MAX_TOTAL_GEOMETRY_INSTANCES); the single-assignment overload is unchanged in output.

• kstep export --require-geometry: exit 1 and no file unless geometry was merged.

• Error codes KSTEP-S-006 (GEOMETRY_REQUIRED), KSTEP-S-007 (GEOMETRY_UNAVAILABLE) and
  KSTEP-S-008 (GEOMETRY_EXPORT_FAILED); --output json reports a geometry object when shapes
  are involved.

• Placed assembly geometry (ADR-0028, Welle I): place(usage, translation, rotation) in the script
  DSL with vec(...), Rotation.about(...), Rotation.fromAxes(...); the exporter writes a
  CONTEXT_DEPENDENT_SHAPE_REPRESENTATION chain per geometric usage, so OCCT and FreeCAD import the
  components of an assembly (previously only the root). kstep export --output json reports
  geometry.placementCount/usageCount. New interop tools dump_xcaf_tree.cpp,
  freecad_assembly_check.py, verify-placed-assembly.sh. Gate (2026-10-22, macOS arm64, OCCT 7.9.3):
  clean check -Pkstep.occt.require=true -Pkstep.planegcs.require=true --no-build-cache, 1277 tests,
  0 failures, 0 errors, 6 skipped (the six known ones).

• Geometry operations on the OCCT bridge (ADR-0029, Welle J): OcctKernel.makeCylinder,
  translate/transformed, union/cut/common/boolean (single-solid results, face-limited operands),
  hole, revolveProfile (about X or Y, RevolveAxis) and chamfer; OcctEmptyResultException for empty
  boolean results; feature-history cases CylinderFeature, RevolveFeature, TranslateFeature,
  BooleanFeature, HoleFeature, ChamferFeature; example scripts hello-plate-with-hole,
  export-plate-with-hole, export-boolean-{union,common,cut}, export-revolved-sleeve,
  export-chamfered-prism, hello-revolve; scripts/interop/verify-geometry-operations.sh. Gate
  (2026-10-22, macOS arm64, OCCT 7.9.3): clean check -Pkstep.occt.require=true -Pkstep.planegcs.require=true --no-build-cache --rerun-tasks, 1333 tests, 0 failures, 0 errors, 6 skipped
  (the six known ones). The six exported STEP files read back as valid solids in OCCT's typed reader and
  FreeCAD with the closed-form volumes.

Changed

• OcctGeometryException is now open (parent of OcctEmptyResultException); FilletFeature implements the
  new DerivedFeature interface (constructor and copy unchanged); the native bridge links -lTKBO.
• CI/release workflows: the apt-get steps first download (resumable, three attempts with per-attempt
  timeouts) and then install offline, with a 40-minute step limit, after a slow mirror held the Linux OCCT job
  up twice on 2026-10-22 (its dev packages pull in about 450 MB). The Linux OCCT job also caches the downloaded
  packages with actions/cache (one entry per ISO week).
• The MCP server now reports the project version to clients (read from the jar manifest); it reported a
  hard-coded 0.1.0, including in the 0.1.1 release.
• Geometry exports with assembly usages now carry an identity placement for usages without
  place(...); the export text line gains and K placed usage(s). Render, preview and GLB still
  ignore placements.
• kstep export no longer prints "geometry merging is not wired into 'export' yet". A merge failure
  (unreachable or duplicate product definition, closed shape, OCCT error) fails with exit 1 instead
  of writing a structure-only file; native shape handles are closed on every path.
• The OCCT bridge detaches OCCT's default message printers while writing STEP, so OCCT's
  "Statistics on Transfer" banners no longer pollute stdout (and --output json).

Verify the download with the attached .sha256 file (sha256sum -c).