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).

kSTEP 0.1.1

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

Second pre-release. The GitHub release carries a platform-independent kstep-cli-0.1.1.zip (JVM only, without native bridges; about 86 MB because
it bundles the Kotlin compiler for *.kstep.kts scripts) and a SHA-256 checksum. Nothing is published to Maven Central or Homebrew. Geometry still needs a system OCCT
build (Linux x86-64 or, new, macOS arm64 via Homebrew).

Added

• macOS arm64 support for the OCCT and PlaneGCS native bridges (ADR-0026): platform-aware Gradle
  build (clang++, .dylib, Homebrew defaults, -Pkstep.brew.prefix), platform whitelist in the
  loaders (detectPlatform), unit tests for it, and a new CI job build-native-macos. Development
  use only: nothing is bundled, the dylib is unsigned, Intel Macs and Windows stay unsupported.
• Release pipeline (.github/workflows/release.yml, ADR-0025): pushing a vX.Y.Z tag builds
  kstep-cli-X.Y.Z.zip (without native bridges) with a SHA-256 checksum and creates or updates the
  GitHub release; pre-release automatically while the major version is 0. No Maven Central,
  Homebrew or signing yet.
• scripts/release/ (tag validation, version check, checksum, release notes, distribution
  verification) and its self-test test-release-scripts.sh, which also runs in CI.
• kstep export --validate: opt-in population-level model validation (USEDIN, INVERSE,
  UNIQUE, acyclic usages) before the Part 21 file is written. Findings give exit code 1 and no
  file; if no verdict can be reached (limits, unsupported construct) it fails closed with the new
  code KSTEP-S-005. Text and --output json output, see ADR-0024. Default off, output without the
  flag is unchanged.
• KStepModel.validateModel() in kstep-script (ModelValidationOutcome.Checked /
  Unavailable).

Changed

• CI action updates (pinned by commit SHA, tags verified): actions/setup-java 6.0.1,
  gradle/actions/setup-gradle 6.4.0, actions/upload-artifact 7.0.2.

Documented

• Interop finding of 2026-10-22: kSTEP Part 21 files (product structure) are read by FreeCAD 1.x
  (OCCT 7.8) without error or warning and yield 0 objects because no geometry is written. An
  independent reader built on OpenCascade 7.9.3's typed STEP model
  (scripts/interop/read_step_structure.cpp) additionally resolves the product structure:
  products, product definitions, formations and both ends of every assembly usage are found, no
  entity is undefined and the OCCT model check reports 0 fails and 0 warnings. This proves
  product-structure read interop with one external implementation (OCCT). Geometry interop,
  other CAD/PLM readers, full AP242 schema conformance and a lossless write-back round trip remain
  unverified, so ADR-0001 acceptance criterion #2 is only partly met.

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

kSTEP 0.1.0 (pre-release)

First tagged pre-release of kSTEP, the type-safe Kotlin DSL for STEP (ISO 10303). The API is unstable and no artifacts are published: build from source (JDK 21). See the CHANGELOG for the full list.

Highlights

• Semantic AP242 core: EXPRESS parser, Kotlin codegen (transitive TYPE aliases, ENUMERATION, closed SELECT), DERIVE properties, USEDIN/INVERSE, UNIQUE UR1/UR2 and acyclic WR1, an opt-in model validator, sixteen entities.
• STEP Part 21 writer/reader, kstep export, kstep render (SVG/PNG/text/GLB), kstep asciidoc, MCP server (kstep mcp).
• Geometry and viewer modules (OpenCascade, PlaneGCS, Compose Desktop) behind native bridges.

Limits

• Native bridges need system libraries and are verified on Linux x86-64 only; CI runs on Linux.
• Part 21 output is verified by self-round-trip only, not against external CAD/PLM tools.
• kstep export does not run model-level validation yet.