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.csnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.firmamentnew file mode 100644index 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+ 12diff --git a/testdata/firmament/examples/box_with_hole.firmament b/testdata/firmament/examples/box_with_hole.firmamentnew file mode 100644index 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: 12diff --git a/testdata/firmament/examples/cnc_min_tool_radius_demo.firmament b/testdata/firmament/examples/cnc_min_tool_radius_demo.firmamentnew file mode 100644index 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: 12diff --git a/testdata/firmament/examples/placed_primitive.firmament b/testdata/firmament/examples/placed_primitive.firmamentnew file mode 100644index 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