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.mdindex 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.mdnew file mode 100644index 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.firmfixtureindex 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 mmdiff --git a/fixtures/FirmamentV2/Language/valid/let-arithmetic-expressions.valid.firmfixture b/fixtures/FirmamentV2/Language/valid/let-arithmetic-expressions.valid.firmfixtureindex 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 mmdiff --git a/fixtures/FirmamentV2/Language/valid/let-primitive-literals.valid.firmfixture b/fixtures/FirmamentV2/Language/valid/let-primitive-literals.valid.firmfixtureindex 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.firmfixtureindex 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 mmsolid 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.firmfixtureindex 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 mmsolid 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.firmfixtureindex 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