Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Add Firmament v1 docs and example pack

Yuechen Lib1b52341acb6
diff --git a/Aetheris.Kernel.Firmament.Tests/FirmamentExamplePackSmokeTests.cs b/Aetheris.Kernel.Firmament.Tests/FirmamentExamplePackSmokeTests.cs
new file mode 100644
index 00000000..814b608b
--- /dev/null
+++ b/Aetheris.Kernel.Firmament.Tests/FirmamentExamplePackSmokeTests.cs
@@ -0,0 +1,62 @@
+using System.Linq;
+
+namespace Aetheris.Kernel.Firmament.Tests;
+
+public sealed class FirmamentExamplePackSmokeTests
+{
+ public static TheoryData<string> ExampleFiles =>
+ [
+ "testdata/firmament/examples/box_basic.firmament",
+ "testdata/firmament/examples/box_with_hole.firmament",
+ "testdata/firmament/examples/placed_primitive.firmament",
+ "testdata/firmament/examples/cnc_min_tool_radius_demo.firmament"
+ ];
+
+ [Theory]
+ [MemberData(nameof(ExampleFiles))]
+ public void ExamplePack_Files_Are_Canonical_And_Compile(string fixturePath)
+ {
+ var source = FirmamentCorpusHarness.ReadFixtureText(fixturePath);
+
+ var formatResult = new FirmamentFormatter().Format(new FirmamentFormatRequest(new FirmamentSourceDocument(source)));
+ Assert.True(formatResult.Formatting.IsSuccess);
+ Assert.Equal(source, formatResult.Formatting.Value.Text);
+
+ var compileResult = FirmamentCorpusHarness.Compile(source);
+ Assert.True(compileResult.Compilation.IsSuccess);
+ }
+
+ [Theory]
+ [InlineData("testdata/firmament/examples/box_basic.firmament", "base", 0, "primitive", "box")]
+ [InlineData("testdata/firmament/examples/placed_primitive.firmament", "post", 1, "primitive", "cylinder")]
+ public void ExamplePack_GoldenPath_Examples_Export(string fixturePath, string expectedFeatureId, int expectedOpIndex, string expectedBodyCategory, string expectedFeatureKind)
+ {
+ var first = ExportFixture(fixturePath);
+ var second = ExportFixture(fixturePath);
+
+ Assert.True(first.IsSuccess);
+ Assert.True(second.IsSuccess);
+ Assert.Equal(expectedFeatureId, first.Value.ExportedFeatureId);
+ Assert.Equal(expectedOpIndex, first.Value.ExportedOpIndex);
+ Assert.Equal(expectedBodyCategory, first.Value.ExportedBodyCategory);
+ Assert.Equal(expectedFeatureKind, first.Value.ExportedFeatureKind);
+ Assert.Equal(FirmamentStepExporter.LastExecutedGeometricBodyPolicy, first.Value.ExportBodyPolicy);
+ Assert.Equal(FirmamentStepExporter.LastExecutedGeometricBodySelectionReason, first.Value.ExportBodySelectionReason);
+ Assert.Equal(first.Value.StepText, second.Value.StepText);
+ Assert.Contains("ISO-10303-21", first.Value.StepText, StringComparison.Ordinal);
+ }
+
+ [Fact]
+ public void ExamplePack_SchemaExample_Attaches_CncSchema_And_BooleanPlan()
+ {
+ var result = FirmamentCorpusHarness.Compile(FirmamentCorpusHarness.ReadFixtureText("testdata/firmament/examples/cnc_min_tool_radius_demo.firmament"));
+
+ Assert.True(result.Compilation.IsSuccess);
+ Assert.NotNull(result.Compilation.Value.CompiledSchema);
+ Assert.Single(result.Compilation.Value.PrimitiveLoweringPlan!.Booleans);
+ Assert.Equal("hole", result.Compilation.Value.PrimitiveLoweringPlan.Booleans.Single().FeatureId);
+ }
+
+ private static Aetheris.Kernel.Core.Results.KernelResult<FirmamentStepExportResult> ExportFixture(string fixturePath) =>
+ FirmamentStepExporter.Export(new FirmamentCompileRequest(new FirmamentSourceDocument(FirmamentCorpusHarness.ReadFixtureText(fixturePath))));
+}
diff --git a/docs/firmament-build-workflow.md b/docs/firmament-build-workflow.md
new file mode 100644
index 00000000..88277961
--- /dev/null
+++ b/docs/firmament-build-workflow.md
@@ -0,0 +1,66 @@
+# Firmament Build and Export Workflow
+
+This document describes the current Firmament v1 golden path as it exists in the repository today.
+
+## Source shape
+
+A Firmament source file is a `.firmament` file with canonical section order:
+
+1. `firmament`
+2. `model`
+3. `schema` (optional)
+4. `ops`
+5. `pmi` (optional)
+
+The syntax is the repository's indentation-based TOON shape, not JSON.
+
+## High-level compile flow
+
+The current in-repo flow is:
+
+1. parse `.firmament` source into the parsed document model
+2. validate required fields, source ordering, selectors, placement, and schema shape
+3. lower supported primitive and boolean ops into execution plans
+4. execute supported geometry ops
+5. execute validation ops against the compiled/executed result
+6. optionally export the selected executed body to STEP AP242
+
+There is not yet a polished standalone Firmament CLI documented in this repository. Today, the workflow is exercised through the compiler/exporter code paths and the automated tests.
+
+## Export policy
+
+The current STEP path exports the **last executed geometric body**.
+
+That means:
+
+- only successfully executed primitive or boolean bodies are candidates
+- validation ops are never export bodies
+- if a later geometric op does not execute, export can fall back to an earlier executed body
+
+This is the current explicit export contract, not a future roadmap statement.
+
+## "Last executed geometric body"
+
+In the current implementation, "last executed geometric body" means:
+
+- walk executed primitives and executed booleans
+- compare their source op indices
+- choose the successfully executed body with the greatest op index
+
+So the exported body is tied to execution success, not simply to the last textual op in the file.
+
+## Where examples and artifacts live
+
+- example source files: `testdata/firmament/examples/`
+- existing fixture corpus used by implementation tests: `testdata/firmament/fixtures/`
+- generated STEP artifacts checked by exporter tests: `testdata/firmament/exports/`
+
+## How to review the golden path today
+
+The most direct way to review the current workflow is through the Firmament tests:
+
+- compile/format/validation coverage in `Aetheris.Kernel.Firmament.Tests`
+- export coverage in `Aetheris.Kernel.Firmament.Tests/FirmamentStepExporterTests.cs`
+- example smoke coverage in `Aetheris.Kernel.Firmament.Tests/FirmamentExamplePackSmokeTests.cs`
+
+That keeps the documentation aligned to the implemented repository surface without inventing a CLI that does not exist yet.
diff --git a/docs/firmament-overview.md b/docs/firmament-overview.md
new file mode 100644
index 00000000..6afcc0c6
--- /dev/null
+++ b/docs/firmament-overview.md
@@ -0,0 +1,83 @@
+# Firmament Overview
+
+Firmament is the Aetheris DSL for defining a small, ordered 3D feature program in `.firmament` files.
+
+In v1 today, the implemented golden path is:
+
+1. write a `.firmament` source file using the canonical indentation-based syntax
+2. compile it through parse, validation, lowering, execution, and validation-execution stages
+3. export the selected executed body to STEP AP242 text
+
+## What Firmament currently supports
+
+Firmament currently supports these source-level concepts:
+
+- primitive features: `box`, `cylinder`, `sphere`
+- boolean features: `add`, `subtract`, `intersect`
+- validation ops: `expect_exists`, `expect_selectable`, `expect_manifold`
+- placement blocks with `place.on` and `offset[3]`
+- selector-shaped references rooted at a source feature id
+- optional schema blocks for `cnc`, `additive`, and `injection_molded`
+- first schema-aware CNC DFM validation for `minimum_tool_radius` on subtract-with-cylinder inputs
+- canonical formatting of supported `.firmament` source
+- STEP AP242 export for the current single-body golden path
+
+## Core concepts
+
+### Features
+
+Features are ordered ops in `ops[n]`.
+
+- primitive ops create geometry
+- boolean ops consume earlier geometry and may create later geometry
+- validation ops check conditions and do not create export bodies
+
+Source feature ids are the stable language identity.
+
+### Selectors
+
+Selectors start from a source feature id and currently use one port:
+
+- `feature_id`
+- `feature_id.port`
+
+Selectors are contract-based. The allowed ports depend on the referenced feature kind.
+
+### Validation ops
+
+Validation ops check feature existence, selector selectability, and manifold expectations against the currently implemented execution contracts.
+
+### Placement
+
+Placement currently supports an anchor plus a translation offset:
+
+- `place.on: origin`
+- `place.on: feature_id.port`
+- `offset[3]` numeric translation
+
+This is intentionally narrow. Arbitrary rotations and generalized transform stacks are not part of the current language surface.
+
+### Schema
+
+Schema is optional metadata attached to the document.
+
+- `cnc` supports `minimum_tool_radius`
+- `additive` supports `printer_resolution`
+- `injection_molded` supports `parting_plane`, `gate_location`, and `draft_angle`
+
+Only the CNC `minimum_tool_radius` rule is currently enforced as schema-aware DFM behavior.
+
+## What Firmament does not support yet
+
+The current implementation does **not** claim support for:
+
+- sketch/extrude authoring systems
+- PMI authoring or PMI export
+- assembly modeling or assembly export
+- multi-body export
+- selector chaining or multi-hop selector resolution
+- topology-stable semantic naming beyond current contract/runtime checks
+- arbitrary orientation systems or generalized transforms
+- a broad manufacturing-intelligence or full DFM engine
+
+For concrete examples, see `testdata/firmament/examples/`. For the practical golden path, see `docs/firmament-build-workflow.md`.
diff --git a/docs/firmament-selectors.md b/docs/firmament-selectors.md
new file mode 100644
index 00000000..eb4fcbab
--- /dev/null
+++ b/docs/firmament-selectors.md
@@ -0,0 +1,82 @@
+# Firmament Selector Contracts
+
+This document describes the selector surface that is implemented today.
+
+## Selector shapes
+
+Firmament currently accepts these target/anchor shapes:
+
+- bare feature id: `feature_id`
+- single-port selector: `feature_id.port`
+
+There is no implemented selector chaining or multi-hop traversal.
+
+## Contract-level selector ports
+
+### Primitive features
+
+#### `box`
+
+- `top_face` → result kind `Face`, cardinality `One`
+- `bottom_face` → result kind `Face`, cardinality `One`
+- `side_faces` → result kind `FaceSet`, cardinality `Many`
+- `edges` → result kind `EdgeSet`, cardinality `Many`
+- `vertices` → result kind `VertexSet`, cardinality `Many`
+
+#### `cylinder`
+
+- `top_face` → `Face`, `One`
+- `bottom_face` → `Face`, `One`
+- `side_face` → `Face`, `One`
+- `circular_edges` → `EdgeSet`, `Many`
+- `edges` → `EdgeSet`, `Many`
+- `vertices` → `VertexSet`, `Many`
+
+#### `sphere`
+
+- `surface` → `Face`, `One`
+- `edges` → `EdgeSet`, `Many`
+- `vertices` → `VertexSet`, `Many`
+
+### Boolean features
+
+Current boolean roots (`add`, `subtract`, `intersect`) share this contract surface:
+
+- `top_face` → `Face`, `One`
+- `bottom_face` → `Face`, `One`
+- `side_faces` → `FaceSet`, `Many`
+- `edges` → `EdgeSet`, `Many`
+- `vertices` → `VertexSet`, `Many`
+
+## Result kinds and cardinality
+
+The current selector contract metadata distinguishes:
+
+- result kinds: `Face`, `FaceSet`, `EdgeSet`, `VertexSet`
+- cardinality: `One`, `Many`
+
+These are attached at compile time for legal selector-shaped targets.
+
+## What is topology-backed today
+
+Selectors are still intentionally narrow.
+
+Today they are backed by current runtime/body topology checks such as:
+
+- face count
+- edge count
+- vertex count
+- placement-anchor extraction from representative face/edge/vertex points
+
+This is enough for current validation and placement flows, but it is not a generalized semantic selector system.
+
+## Not supported yet
+
+The current implementation does **not** support:
+
+- selector chaining such as `a.top_face.edges`
+- multi-hop traversal across derived topology
+- richer topology naming guarantees beyond current feature contracts and runtime checks
+- arbitrary semantic resolution detached from current executed bodies
+
+Selectors must start from a source feature id, which remains the language-stable identity.
diff --git a/testdata/firmament/examples/README.md b/testdata/firmament/examples/README.md
new file mode 100644
index 00000000..c3d42056
--- /dev/null
+++ b/testdata/firmament/examples/README.md
@@ -0,0 +1,10 @@
+# Firmament Example Pack
+
+This directory contains small canonical Firmament examples for the current v1 surface.
+
+- `box_basic.firmament` — minimal single-box golden-path example.
+- `box_with_hole.firmament` — box plus subtract-with-cylinder boolean syntax example.
+- `placed_primitive.firmament` — selector-based placement using `place.on` and `offset[3]`.
+- `cnc_min_tool_radius_demo.firmament` — schema-aware CNC example using `minimum_tool_radius` with a subtract cylinder sized to pass the current rule.
+
+These files are intended to stay minimal, readable, and aligned with the implemented language surface.
diff --git a/testdata/firmament/examples/box_basic.firmament b/testdata/firmament/examples/box_basic.firmament
new file mode 100644
index 00000000..03ff98eb
--- /dev/null
+++ b/testdata/firmament/examples/box_basic.firmament
@@ -0,0 +1,15 @@
+firmament:
+ version: 1
+
+model:
+ name: box_basic
+ units: mm
+
+ops[1]:
+ -
+ op: box
+ id: base
+ size[3]:
+ 40
+ 30
+ 12
diff --git a/testdata/firmament/examples/box_with_hole.firmament b/testdata/firmament/examples/box_with_hole.firmament
new file mode 100644
index 00000000..b9dbf67d
--- /dev/null
+++ b/testdata/firmament/examples/box_with_hole.firmament
@@ -0,0 +1,24 @@
+firmament:
+ version: 1
+
+model:
+ name: box_with_hole
+ units: mm
+
+ops[2]:
+ -
+ op: box
+ id: base
+ size[3]:
+ 40
+ 30
+ 12
+
+ -
+ op: subtract
+ id: hole
+ from: base
+ with:
+ op: cylinder
+ radius: 4
+ height: 12
diff --git a/testdata/firmament/examples/cnc_min_tool_radius_demo.firmament b/testdata/firmament/examples/cnc_min_tool_radius_demo.firmament
new file mode 100644
index 00000000..976a57fa
--- /dev/null
+++ b/testdata/firmament/examples/cnc_min_tool_radius_demo.firmament
@@ -0,0 +1,28 @@
+firmament:
+ version: 1
+
+model:
+ name: cnc_min_tool_radius_demo
+ units: mm
+
+schema:
+ process: cnc
+ minimum_tool_radius: 2
+
+ops[2]:
+ -
+ op: box
+ id: base
+ size[3]:
+ 24
+ 24
+ 12
+
+ -
+ op: subtract
+ id: hole
+ from: base
+ with:
+ op: cylinder
+ radius: 2
+ height: 12
diff --git a/testdata/firmament/examples/placed_primitive.firmament b/testdata/firmament/examples/placed_primitive.firmament
new file mode 100644
index 00000000..95c02cb9
--- /dev/null
+++ b/testdata/firmament/examples/placed_primitive.firmament
@@ -0,0 +1,27 @@
+firmament:
+ version: 1
+
+model:
+ name: placed_primitive
+ units: mm
+
+ops[2]:
+ -
+ op: box
+ id: anchor
+ size[3]:
+ 20
+ 20
+ 8
+
+ -
+ op: cylinder
+ id: post
+ radius: 3
+ height: 10
+ place:
+ on: anchor.top_face
+ offset[3]:
+ 0
+ 0
+ 2