Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Reconcile Firmament syntax docs and fixture metadata

Yuechen Lic6d4054dd6a2
diff --git a/docs/v2/aetheris-v2-phase1-scope-contract.md b/docs/v2/aetheris-v2-phase1-scope-contract.md
index cc0e738b..3aeef329 100644
--- a/docs/v2/aetheris-v2-phase1-scope-contract.md
+++ b/docs/v2/aetheris-v2-phase1-scope-contract.md
@@ -75,7 +75,7 @@ SolidWorks, FreeCAD, Onshape, and similar systems may be used as verification/vi
## 4. Firmament V2.0 language doctrine
-Firmament V2.0 is a **typed manufacturing-intent data language**.
+Firmament V2.0 is a **typed manufacturing-intent data language**. See [`firmament-v2-concept-template-syntax-reconciliation.md`](firmament-v2-concept-template-syntax-reconciliation.md) for the Phase 1 doctrine reconciling immutable `let` data, Forge-backed concepts, and deferred templates.
Firmament V2.0 is **not** a general programming language.
diff --git a/docs/v2/firmament-v2-concept-template-syntax-reconciliation.md b/docs/v2/firmament-v2-concept-template-syntax-reconciliation.md
new file mode 100644
index 00000000..74f9b84a
--- /dev/null
+++ b/docs/v2/firmament-v2-concept-template-syntax-reconciliation.md
@@ -0,0 +1,151 @@
+# Firmament V2 concept/template syntax reconciliation
+
+Milestone: **V2-FIRMAMENT-SYNTAX-RECONCILE-A0**
+
+This note is the Phase 1 reference for how `let`, Forge-backed concepts, and future templates relate in Firmament V2. It is intentionally narrow: it reconciles source syntax and fixture doctrine without adding language/runtime behavior.
+
+## Phase 1 boundary
+
+Firmament V2 Phase 1 remains a manufacturing-intent data language over existing STEP/AP242 models. It stays pure data: immutable `let`, typed values, acyclic expression graphs, no loops, no conditionals, no functions, no mutation, no hidden state machines, and no Turing completeness.
+
+Phase 1 is concept-first, not model-generation-template-first. Concepts annotate, validate, and constrain existing geometry/manufacturing intent; templates that generate or suggest structure are deferred.
+
+## What is a `let`?
+
+A `let` is immutable typed manufacturing data. It records values and grouped records that describe source-level manufacturing facts. A `let` has no logic, hidden behavior, mutation, or lifecycle. Concepts and PMI may reference `let` values.
+
+```firmament
+let MountingPattern {
+ holeDiameter: length = 6.0mm tol 0.05mm
+ holeSpacingX: length = 80.0mm tol +0.10mm -0.05mm
+ holeCount: int = 4
+}
+```
+
+Use lowercase primitive types: `int`, `float`, `length`, `angle`, `string`, and `bool`.
+
+## What is a concept?
+
+A concept application is a semantic classification/contract over existing geometry and manufacturing intent. The generic source shape is:
+
+```text
+conceptFamily<ConceptName> { ... }
+```
+
+The parser recognizes this generic shape. Forge descriptors, not parser branches, define the available concept families and concepts, their required fields, field types, validation rules, DFM checks, and later PMI/report behavior. The parser must not hardcode every concept.
+
+Examples:
+
+```firmament
+manufacturing process<CNC> {
+ material: Aluminum6061
+ minimumToolRadius: 1.5mm
+}
+
+feature mountHole: hole<Countersink> {
+ target: part.region("mountHoleA")
+ diameter: MountingPattern.holeDiameter
+ countersinkDiameter: MountingPattern.countersinkDiameter
+ angle: 90deg
+}
+```
+
+In these examples, `process<CNC>` and `hole<Countersink>` are concept-family applications. `process` and `hole` identify the semantic family; `CNC` and `Countersink` identify the family-specific concept. Prefer PascalCase concept names where current Forge descriptors do.
+
+## What is a template?
+
+In Phase 1, prefer the words **concept** or **concept pack** for manufacturing-intent validation. A template is a future specialization that can instantiate or suggest source/geometry from a concept. A concept can validate and annotate existing geometry without generating geometry.
+
+```text
+Concept:
+ semantic meaning + required fields + validation/DFM/PMI/report obligations.
+
+Template:
+ optional future mechanism that can instantiate or suggest source/geometry from a concept.
+```
+
+This distinction keeps Phase 1 from drifting back into full modeling or geometry generation.
+
+## Forge descriptor vs parser responsibilities
+
+Parser grammar owns only stable syntax shapes:
+
+- immutable typed `let` values and grouped records;
+- dotted references to record fields;
+- arithmetic and toleranced typed expressions where implemented;
+- generic `conceptFamily<ConceptName>` application blocks;
+- `pmi` blocks as manufacturing information records.
+
+Forge descriptors own semantic catalog behavior:
+
+- which families and concepts exist;
+- required and optional fields;
+- field types and unit expectations;
+- validation and rejection reasons;
+- DFM checks where implemented;
+- future PMI/report obligations.
+
+Do not add hardcoded magic angle tags such as:
+
+```firmament
+<cnc> { ... }
+<countersink> { ... }
+```
+
+Those forms omit the semantic family. Prefer:
+
+```firmament
+manufacturing process<CNC> { ... }
+feature h1: hole<Countersink> { ... }
+```
+
+## PMI keyword doctrine
+
+Use `pmi` as the manufacturing information block keyword. Do not use `gdt` as the authoring keyword. GD&T is a category of PMI, not the Phase 1 block name.
+
+## Illustrative Phase 1 example
+
+The following is canonical illustrative syntax for Phase 1 doctrine. Some lowering/export behavior remains implementation-dependent and may be deferred by current fixtures.
+
+```firmament
+let MountingPattern {
+ holeDiameter: length = 6.0mm tol 0.05mm
+ countersinkDiameter: length = 10.0mm tol 0.10mm
+}
+
+manufacturing process<CNC> {
+ material: Aluminum6061
+ minimumToolRadius: 1.5mm
+}
+
+feature mountHole: hole<Countersink> {
+ target: part.region("mountHoleA")
+ diameter: MountingPattern.holeDiameter
+ countersinkDiameter: MountingPattern.countersinkDiameter
+ angle: 90deg
+}
+
+pmi {
+ datum A {
+ target: part.region("baseFace")
+ }
+
+ diameter mountHoleDiameter {
+ target: part.region("mountHoleA")
+ dimension: MountingPattern.holeDiameter
+ }
+}
+```
+
+## Deferred syntax and behavior
+
+Phase 1 defers:
+
+- templates that generate geometry;
+- full modeling concepts;
+- move-hole/local BRep surgery;
+- automatic feature reconstruction;
+- automatic DFM execution where not already implemented;
+- PMI lowering for export-deferred controls;
+- graphical PMI;
+- full GD&T/Y14.5 coverage.
diff --git a/fixtures/FirmamentV2/Language/valid/concept-applications-forge.valid.firmfixture b/fixtures/FirmamentV2/Language/valid/concept-applications-forge.valid.firmfixture
index 0de5b1a4..b461f84c 100644
--- a/fixtures/FirmamentV2/Language/valid/concept-applications-forge.valid.firmfixture
+++ b/fixtures/FirmamentV2/Language/valid/concept-applications-forge.valid.firmfixture
@@ -1,7 +1,14 @@
-// fixture: FirmamentV2 Forge concept-family applications
+// fixture-id: concept-applications-forge
+// case: firmament-v2-f1-concept-applications-forge
+// category: Language
// syntax-version: FirmamentV2
+// validity: valid
+// implementation: parser-backed
+// expected: valid
+// expected-stage: feature-air
// expected-parser: FirmamentV2Parser
// expected-concepts: process<CNC>, hole<Countersink>
+// notes: F1 Forge-backed concept-family application syntax; parser recognizes generic conceptFamily<ConceptName> shape.
model ConceptApplicationsForge {
units mm
diff --git a/fixtures/FirmamentV2/Language/valid/let-arithmetic-expressions.valid.firmfixture b/fixtures/FirmamentV2/Language/valid/let-arithmetic-expressions.valid.firmfixture
index 69236cfc..2c461a25 100644
--- a/fixtures/FirmamentV2/Language/valid/let-arithmetic-expressions.valid.firmfixture
+++ b/fixtures/FirmamentV2/Language/valid/let-arithmetic-expressions.valid.firmfixture
@@ -1,7 +1,12 @@
+// fixture-id: let-arithmetic-expressions
// case: let-arithmetic-expressions
-// expected-stage: parsed
+// category: Language
// syntax-version: FirmamentV2
+// validity: valid
// implementation: parser-backed
+// expected: valid
+// expected-stage: feature-air
+// notes: L3 arithmetic expression graph and strict type rules.
model LetArithmeticExpressions {
units mm
diff --git a/fixtures/FirmamentV2/Language/valid/let-primitive-literals.valid.firmfixture b/fixtures/FirmamentV2/Language/valid/let-primitive-literals.valid.firmfixture
index 806c3342..6e0e2ce2 100644
--- a/fixtures/FirmamentV2/Language/valid/let-primitive-literals.valid.firmfixture
+++ b/fixtures/FirmamentV2/Language/valid/let-primitive-literals.valid.firmfixture
@@ -5,6 +5,7 @@
// validity: valid
// implementation: parser-backed
// expected: valid
+// expected-stage: feature-air
// notes: L1 immutable primitive typed let bindings only; not referenced by PMI/features.
model LetPrimitiveLiteralsExample {
diff --git a/fixtures/FirmamentV2/Language/valid/let-record-groups.valid.firmfixture b/fixtures/FirmamentV2/Language/valid/let-record-groups.valid.firmfixture
index e148b7b0..2c485659 100644
--- a/fixtures/FirmamentV2/Language/valid/let-record-groups.valid.firmfixture
+++ b/fixtures/FirmamentV2/Language/valid/let-record-groups.valid.firmfixture
@@ -1,6 +1,13 @@
+// fixture-id: let-record-groups
+// case: let-record-groups
+// category: Language
// syntax-version: FirmamentV2
+// validity: valid
// implementation: parser-backed
-// expected-stage: parser
+// expected: valid
+// expected-stage: feature-air
+// notes: L2 grouped let records and dotted references.
+
model LetRecordGroups {
units mm
solid base: Box { size: [10, 8, 6] }
diff --git a/fixtures/FirmamentV2/Language/valid/let-toleranced-values.valid.firmfixture b/fixtures/FirmamentV2/Language/valid/let-toleranced-values.valid.firmfixture
index 4d8a5c8d..31d6bf7c 100644
--- a/fixtures/FirmamentV2/Language/valid/let-toleranced-values.valid.firmfixture
+++ b/fixtures/FirmamentV2/Language/valid/let-toleranced-values.valid.firmfixture
@@ -1,5 +1,13 @@
-// fixture: FirmamentV2 toleranced let values
+// fixture-id: let-toleranced-values
+// case: firmament-v2-l4-toleranced-values
+// category: Language
// syntax-version: FirmamentV2
+// validity: valid
+// implementation: parser-backed
+// expected: valid
+// expected-stage: feature-air
+// notes: L4 tolerance syntax and toleranced dimension values.
+
model TolerancedValues {
units mm
solid base: Box { size: [100, 80, 10] }
diff --git a/fixtures/FirmamentV2/Language/valid/pmi-record-shaped-basic.valid.firmfixture b/fixtures/FirmamentV2/Language/valid/pmi-record-shaped-basic.valid.firmfixture
index b762349e..4bb7d7a6 100644
--- a/fixtures/FirmamentV2/Language/valid/pmi-record-shaped-basic.valid.firmfixture
+++ b/fixtures/FirmamentV2/Language/valid/pmi-record-shaped-basic.valid.firmfixture
@@ -1,7 +1,12 @@
// fixture-id: pmi-record-shaped-basic
// case: firmament-v2-p1-record-shaped-pmi
+// category: Language
// syntax-version: FirmamentV2
+// validity: valid
+// implementation: parser-backed
// expected: valid
+// expected-stage: feature-air
+// notes: P1 record-shaped pmi block parser coverage.
model PmiRecordShapedBasic {
units mm