Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel
Clarify Firmament authoring guidance
Yuechen Li89ca621ffbcb
diff --git a/docs/development/FIRMAMENT-LANGUAGE-DECISIONS-2026-10.md b/docs/development/FIRMAMENT-LANGUAGE-DECISIONS-2026-10.mdindex cfc7c6b9..a4ffbe81 100644--- a/docs/development/FIRMAMENT-LANGUAGE-DECISIONS-2026-10.md+++ b/docs/development/FIRMAMENT-LANGUAGE-DECISIONS-2026-10.md@@ -1,5 +1,12 @@# October 2026 Firmament language decision register+The October 14 [syntax review](FIRMAMENT-SYNTAX-REVIEW-2026-10.md) supplements+this register with twenty current language/teaching seams and exact execution+witnesses. Its ignored-include and schema-formatting findings remain open;+documentation repair does not implement recommendations #1–#4, #7 or #23.+All 24 original recommendations and their historical dispositions are preserved+below. Later production amendments supersede only the scopes they qualify.+Source: [Claude's original authoring audit](firmament-authoring-pass-2026-10.md).This register preserves its 24 recommendations and their rationale. A futuremilestone assignment is a disposition, not an implemented feature. X0 remainsdiff --git a/docs/development/FIRMAMENT-SYNTAX-REVIEW-2026-10.md b/docs/development/FIRMAMENT-SYNTAX-REVIEW-2026-10.mdnew file mode 100644index 00000000..dde7a2ec--- /dev/null+++ b/docs/development/FIRMAMENT-SYNTAX-REVIEW-2026-10.md@@ -0,0 +1,269 @@+# Firmament syntax review — 2026-10-14++## Purpose and boundary++This review accompanies the rewrite of [Writing Firmament](../public/firmament/syntax.md).+The question is what a human or agent can infer from the language's surface,+and where that inference differs from current admission. This pass changes+Markdown only. It does not implement a new grammar, extend compatibility,+change geometry or close frontend milestones.++The working model remains: Model is a class-like artifact owner, Struct is+reusable construction, Feature is function-like and Pattern is finite repetition.+These are organizational analogies, not an implementation of runtime OOP.++Evidence is from checkout `d4032b00` and its existing Release CLI assemblies.+The Firmament assembly used for probes was built on October 14 at 14:28 local+time; no rebuild was performed during this documentation-only pass. Source+inspection corroborates the defects below. In-memory probes call the existing+`FirmamentBuildAndExport.CompileSource`; fixture checks use the repository CLI's+normal `validate --json`, not an installed CLI or a shadow parser.++The [original October audit](FIRMAMENT-LANGUAGE-DECISIONS-2026-10.md) and+[earlier inconsistency register](firmament-language-inconsistencies.md) remain+historical evidence. Their resolved/retained labels are not proof that every+current owner shares the same syntax. Earlier reports must not be silently+rewritten as if later repairs had already existed.++## Findings and decisions still needed++“Observed” below means executed in this pass. “Inspected” means checked against+the current source and named guides/tests; it does not claim a new exhaustive+runtime qualification. An open question is not an approved syntax change.++| ID | Area and current behavior | Classification | Decision or next evidence needed |+| --- | --- | --- | --- |+| S01 | camelCase built-in fields work in ordinary Box/Hole authoring, but symmetry still requires `Across`, `Source`, `About`, `Count`, `Angle`. Changing only those labels rejects admitted fixtures. Observed. | Active casing inconsistency. | Apply the established casing policy through the symmetry owner, with alias/geometry parity, rather than tell authors to lowercase unsupported fields. |+| S02 | `using/as/on/over` have lowercase link forms; pipeline endpoint `From/To` and mirror-header `From` remain PascalCase. Inspected. | Incomplete linking-word policy. | Decide which words are structural operators and which are lowercase links. Do not infer `from` support from the field `from:`. |+| S03 | Direct Hole accepts `Point2(0mm, 0mm)` and rejects `[0mm, 0mm]`; Rect2 accepts a list. The composed Hole reader contains both list and Point2 forms. Observed direct pair; inspected composed owner. | Same conceptual value, inconsistent admission. | Choose a point-construction policy with explicit context conversions; keep Point2, Point3 and vector types distinct. The old “Compose only accepts arrays” claim is stale. |+| S04 | Native fields require dimensional lengths; historical primitive source can inherit mm. A Model without `units` rejects; a Struct containing the same dimensional Box builds without it. Observed. | Compatibility plus root-dependent units policy. | Specify the purpose and scope of a root units declaration separately from literal typing. No change to engineering units doctrine is proposed. |+| S05 | Model, material-bearing Struct, wrapper-free construction and library-only documents have different entry rules. A bare Box fails in-memory compilation; the same Box inside Struct builds. Observed pair; other entry forms inspected. | Root/scope contract incomplete. | Define legal source-unit kinds and contexts. “Everything is an optional wrapper” would be false. |+| S06 | Feature definitions, named Feature invocations, finite feature Templates and scalar Functions all resemble functions but have different bodies/results/scopes. Inspected. | Overloaded surface and missing teaching distinction. | Keep semantic geometry recipes distinct from scalar expressions; decide whether the two Template recipe forms need one declaration convention later. |+| S07 | Pattern maps a Set with an explicit binder, maps semantic points with `Source`/`Item`, or maps record arrays through Template/`Current`; radial Pattern is another owner. Placing the beginner Pattern inside Modify builds. | Active repetition inconsistency. | Define one mental model for element binding and scope before changing spellings. `Item` and `Current` are not interchangeable aliases. This pass does not replace expansion. |+| S08 | Product specialization uses `Template<...> Struct Name`; finite feature Templates use `Template<spec: Type> Name`; call-shaped feature Template aliases also remain. Inspected. | Multiple declaration shapes plus compatibility. | Decide which family authors should learn first and how each names its output. Preserve admitted alias intent until replacement is qualified. |+| S09 | `<...>` denotes closed variants (`Hole<Shaft>`), types (`Set<Point2>`), counts (`RegularPolygon2<6>`), Interface families and actual Template arguments. Direct EdgeFinish instead uses `kind: Chamfer`; `EdgeFinish<Chamfer>` rejects. Observed finish pair. | Variant/type/configuration distinction obscured. | Document these meanings now; decide whether feature variants deserve consistent notation later. No universal generic-programming contract exists. |+| S10 | Pocket uses `depth` and must leave a floor; through-cut Remove uses `Role: ThroughCut`; Hole uses `end`; Slot uses `extent` and `role`. Inspected. | Engineering differences with vocabulary friction. | Preserve blind/through semantics while deciding whether termination vocabulary can be shared. Missing geometry combinations are separate from this syntax question. |+| S11 | `on XY`, `on: +Z`, a Plane/Frame and an Assembly attachment are differently typed, context-owned references. Inspected. | Legitimate type distinctions, overloaded placement word. | Publish a consumer-by-reference matrix before promising general plane/frame substitution. The historical ignored-XZ defect is covered by existing tests, not a reason to offer silent defaults. |+| S12 | Primitive EdgeFinish uses face + Boundary target; composed finishing uses a Profile boundary/support. Native semantic faces and imported `#face` references have different identities. Inspected. | Typed selector differences, uneven surface. | Explain selector types and target ownership. Do not merge imported entity IDs with native semantic identities or invent a universal string selector. |+| S13 | Newline/semicolon fields coexist with mandatory semicolons in Function, Points, PMI Note and Assembly provenance grammars. Inspected. A dense Hole seed without field separators fails with mirror + override, while the semicolon-separated version builds. Observed. | Active lexical/termination inconsistency and rewrite sensitivity. | Decide one general separator rule and list unavoidable domain exceptions. Do not make whitespace changes a semantic migration by accident. |+| S14 | `/* ... */` before schema rejects as late; `//` succeeds. A selector followed by a trailing comment, or a selector sharing a line with Model, may be ignored. Observed; exact witnesses below. | Confirmed frontend correctness defect. | Consume schema through the same token boundary as admission, or explicitly reject malformed placement. Unrecognized names must not bypass selection because of formatting. |+| S15 | Both `include` and `Include` of a nonexistent file before a plain mechanical Model compile successfully. Other project/include consumers have fail-closed tests. Observed mechanical case; inspected project tests. | Confirmed ignored intent and inconsistent module contract. | Each directive must be consumed by a real owner or rejected. Define supported mechanical module consumption before advertising universal include. No parallel loader should be added just to hide this gap. |+| S16 | Record is data; Struct is construction; Concept Struct is non-materialized construction; Concept can name a contract or a typed geometric family. Earlier prose grouped Record/Struct together. | Documentation ambiguity plus overloaded vocabulary. | The rewrite separates their roles. Whether Concept declarations should become more visibly distinct remains a language decision. |+| S17 | AST expression syntax does not establish one evaluator in every position. Static values, Feature-local `let`, Template arguments and scalar Functions retain bounded owners. Inspected. | Semantic consolidation still incomplete. | Inventory admitted expression positions/types before promising general local values. No general Let, runtime control flow or new evaluator is introduced here. |+| S18 | `=>` means a Set association, Pattern binder, Require condition or compatibility exposure alias. `with` derives Records, features or historical solids in different contexts. Inspected. | Contextual operator overlap. | Keep a role-specific reference. Decide which overlaps are useful consistency and which hide distinct operations; do not declare global equivalence. |+| S19 | Public schema names are Mechanical, WireForm, Sweep, SectionChain, Garment; these are not all product roots. Garment admits bounded Feature Profile use, contradicting the old page's Mechanical-only claim. | Documentation errors and non-universal domain grammar. | Correct teaching now. Decide separately whether all roots need an explicit document-kind model; do not invent schema names. |+| S20 | The old entry page mixed complete files, rootless fragments, undefined names, an unowned Pattern and migration commentary. Its Polygon2 “Rhombus only” statement and geometry's stock-placement warning were stale. | Documentation defects. | Repaired in this pass; complete examples are compiled, fragments identify prerequisites. A generated whole-language grammar still requires complete owner coverage. |++S01–S19 remain implementation or design matters unless explicitly described as+a documentation correction. This review authorizes no compatibility removal.++## Exact executed witnesses++All probes used the existing normal engineering compilation entry point, not+just syntax acceptance. They return STEP in memory on success. No source fixture+or generated model file was added in this pass.++### S15 — ignored mechanical include++```firmament+include "__missing_syntax_review__.firmament";+Model Example {+ units: mm+ Box stock { size: [30mm, 20mm, 6mm] }+}+```++Observed: success, no diagnostics. `Include` behaves the same. The result was+repeated with the repository root supplied as `sourceDirectory`, so this is not+merely a missing base-directory test. The mechanical scope binder skips+`DirectiveSyntax`; it does not require a consumption receipt for the include.+The normal file export path also passes the source to this admission path.++This finding is bounded to an ordinary mechanical Model. Assembly project+loading, including file-backed Profile dependencies, has missing/cycle checks;+those consumers are not being declared broken by this witness.++### S14 — schema formatting changes admission++Append the same Model above to each prefix:++| Prefix | Observed normal compilation |+| --- | --- |+| `schema DoesNotExist` followed by newline | Rejects: `firmament-schema-unknown:DoesNotExist:available=Mechanical,WireForm,Sweep,SectionChain,Garment`. |+| `schema DoesNotExist ` followed immediately by Model | Builds, no diagnostics. |+| `schema DoesNotExist // selector` followed by newline | Builds, no diagnostics. |+| `schema WireForm` followed by newline | Rejects: `wireform-declaration-missing: No WireForm declaration was found.` |+| `schema WireForm ` followed immediately by Model | Builds, no diagnostics. |+| `/* author comment */`, newline, `schema Mechanical`, newline | Rejects: `firmament-schema-late`. |+| `// author comment`, newline, `schema Mechanical`, newline | Builds. |++The selector matches a whole line before shared parsing. Forms it misses can+become generic directives which the mechanical binder skips. This is an+admission gap, not merely a recommendation to put headers on separate lines.++### S01 — symmetry casing++The existing [radial bolt-circle](../../fixtures/Canonical/Symmetry/radial-bolt-circle.firmament)+and [mirrored-hole](../../fixtures/Canonical/Symmetry/mirrored-hole.firmament)+sources both compile in memory. Change only these labels:++| Change | Observed outcome |+| --- | --- |+| Radial `Source/About/Count/Angle` to `source/about/count/angle` | Rejects: `firmament-symmetry-radial-field-missing:BoltCircle`. |+| Mirror `Across` to `across` | Rejects: `firmament-symmetry-plane-unresolved:RightMount`. |++The mirror error describes resolution rather than the spelling failure. An+alias repair should also improve that diagnostic rather than erase evidence.++### S03/S09 — intuitive substitutions that fail++Inside `Modify stock` of the Model above:++```firmament+Hole<Shaft> bore {+ on: +Z+ center: Point2(0mm, 0mm)+ diameter: 4mm+ end: ThroughAll+}+```++Observed: builds. Change only center to `[0mm, 0mm]`: rejects, including+`firmament-v2-canonical-point2-invalid`.++```firmament+EdgeFinish top {+ face: +Z+ target: Boundary+ kind: Chamfer+ distance: 0.5mm+}+```++Observed: builds. Replace the header with `EdgeFinish<Chamfer> top` and remove+`kind`: rejects as malformed Modify/unknown fields. The intended variant is not+recognized in that position, and the resulting field errors are less helpful+than a direct unsupported-variant diagnostic would be.++### S04/S05 — entry and units++| Source | Observed outcome |+| --- | --- |+| `Model Example { Box stock { size: [30mm,20mm,6mm] } }` | Rejects: `firmament-v2-canonical-units-invalid`. |+| `Struct Example { Box stock { size: [30mm,20mm,6mm] } }` | Builds. |+| `Box stock { size: [30mm,20mm,6mm] }` | Rejects with missing Model/solid/units and V2 source-required diagnostics. |++This does not assert that all wrapper-free profile/domain programs reject.+It shows why omitting the enclosing context from an example is misleading.++### S13 — dense fields interact with symmetry expansion++In the documented mirror/override context, these seed bodies are not equivalent+under current execution:++```text+// Rejects when mirrored and then derived with { Diameter: 8mm }:+Hole<Shaft> leftMount { on:+Z center:Point2(26mm,0mm) diameter:6mm end:ThroughAll }++// Builds in the same context:+Hole<Shaft> leftMount { on:+Z; center:Point2(26mm,0mm); diameter:6mm; end:ThroughAll }+```++The complete context is a 90 x 44 x 8mm Box, a center Plane with normal +X,+`Mirrored Feature rightMount From leftMount { Across: centerPlane }`, then+`Feature largerMount = rightMount with { Diameter: 8mm }` inside Modify.+The failing variant reports canonical document/Modify malformed diagnostics.+The existing symmetry override reader replaces field text up to a semicolon,+newline or closing brace. Recognition of adjacent fields by the shared parser+does not make that rewrite safe. The entry page consequently teaches newlines+or semicolons, not dense implicit field boundaries.++## Ownership map++| Concern | Current source / reference |+| --- | --- |+| Structural declarations, clauses, directives and endpoint spellings | [FirmamentSyntaxParser.cs](../../Aetheris.Kernel.Firmament/FirmamentV2/Syntax/FirmamentSyntaxParser.cs) |+| Field aliases, consumed fields and dimensional expressions | [FirmamentSyntaxValues.cs](../../Aetheris.Kernel.Firmament/FirmamentV2/Syntax/FirmamentSyntaxValues.cs) |+| Preferred spellings versus protected authored names | [FirmamentSourceSpelling.cs](../../Aetheris.Kernel.Firmament/FirmamentV2/FirmamentSourceSpelling.cs), [language style](../public/firmament/language-style.md) |+| Model/Struct units, direct Hole/finish and ignored directives | [FirmamentV2MechanicalBinding.cs](../../Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2MechanicalBinding.cs) |+| Schema recognition and domain restrictions | [FirmamentFrontendSchema.cs](../../Aetheris.Kernel.Firmament/FirmamentFrontendSchema.cs) |+| Mirror/radial spellings and overrides | [SemanticSymmetryAuthoring.cs](../../Aetheris.Kernel.Firmament/FirmamentV2/SemanticSymmetryAuthoring.cs) |+| Profile pipelines and identity | [ProfileAuthoringParser.cs](../../Aetheris.Kernel.Firmament/FirmamentV2/ProfileAuthoringParser.cs) |+| Point lists in composed features, feature support | [PrismaticProfileComposition.cs](../../Aetheris.Kernel.Firmament/Materializer/PrismaticProfileComposition.cs), [geometry](../public/firmament/geometry.md) |+| Polygon variants and closed boundaries | [ClosedBoundary2Authoring.cs](../../Aetheris.Kernel.Firmament/FirmamentV2/ClosedBoundary2Authoring.cs) |+| Specialization and Feature/Pattern ownership | [Template expansion](../../Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2TemplateExpansion.cs), [Feature expansion](../../Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2FeatureExpansion.cs), [Templates guide](../public/firmament/templates.md) |+| Include contracts that differ from the witness | [project snapshots](../public/firmament/project-snapshots.md), [ConceptDerivationTests.cs](../../Aetheris.Kernel.Firmament.Tests/ConceptDerivationTests.cs), [AssemblyInterfaceX1Tests.cs](../../Aetheris.Kernel.Firmament.Tests/Assembly/AssemblyInterfaceX1Tests.cs) |++## Historical claims checked before rewriting++The existing [mechanical migration tests](../../Aetheris.Kernel.Firmament.Tests/FirmamentMechanicalFrontendMigrationTests.cs)+cover unused Slot2 preserving STEP, unknown Fillet and fields rejecting, and+Model/Struct using the same binder. The [X0 tests](../../Aetheris.Kernel.Firmament.Tests/FirmamentFrontendX0Tests.cs)+cover the asymmetric XY/XZ rejection witness. These were inspected, not rerun as+a full regression suite in this documentation-only pass. They prevent treating+the old audit's route behavior as an unqualified description of current source.++The old Box/Hole Z-placement warning is removed from the public geometry guide.+The [bottom-anchored stock regression](../../Aetheris.Kernel.Firmament.Tests/FirmamentV2SemanticHoleTests.cs)+checks host and materialized vertex bounds at 0..height. This is a specific+repaired route, not proof that every domain shares one placement convention.++The old “Feature is Mechanical-only” sentence is corrected: the schema owner+also permits Garment, whose documented Feature use is bounded Profile recipes.+The Polygon2 Rhombus-only statement is corrected against its current owner.++## Priorities for subsequent implementation++1. Close S14/S15 consumed-directive gaps. A schema or include cannot be admitted+ merely because its AST node is recognized. Preserve legitimate project+ consumers; fail closed where no consumer exists.+2. Reconcile the existing capitalization policy with S01/S02. Prove equivalent+ aliases preserve generated identities and geometry; avoid a global text fold.+3. Decide entry/scoping and finite Pattern binding (S05–S08), then point and+ expression rules (S03/S04/S17). These determine what authors can safely infer.+4. Specify termination and selector vocabularies with their engineering types+ (S09–S13/S18/S19). Similar-looking operations need not share an untyped API.++These are ordered proposals for the next code pass, not work implemented here.+Do not add another diagnostic-only parser to represent a grammar that execution+does not honor. The current compiler remains the admission authority.++## Documentation verification++The four complete files in the rewritten entry page compile through the existing+engineering entry point and return nonempty STEP. They cover a direct Hole,+layout/Profile extrusion, Feature + Set Pattern, and product Template.+The sphere example moved to the Revolve guide is also compiled in memory.+The Rhombus, mirror/override and radial fragments also build when wrapped in+their stated Model/material contexts, with semicolon-separated seed fields.+Endpoint selection is exercised by the complete sphere. Fragments remain+labelled and are not represented as standalone executable files.++Eight existing sources were checked with the real CLI's normal validation:+[through-hole](../../fixtures/Canonical/Features/Holes/through-hole.firmament),+[preferred-profile-links](../../fixtures/Regression/FrontendMigration/preferred-profile-links.firmament),+[simple-hole-feature](../../fixtures/Canonical/Feature/simple-hole-feature.firmament),+[pattern-feature-map](../../fixtures/Canonical/Set/pattern-feature-map.firmament),+[generic-mounting-plate](../../fixtures/Canonical/Templates/generic-mounting-plate.firmament),+[boss-pocket-block](../../fixtures/Canonical/Features/Boss/boss-pocket-block.firmament),+[boundary-chamfer](../../fixtures/Canonical/Features/EdgeFinish/boundary-chamfer.firmament)+and [straight-slot](../../fixtures/Canonical/Features/Slots/straight-slot.firmament).+All reported `valid` at level `Built`. This is example evidence, not a full corpus+retest or a new frontend acceptance verdict.++The existing `PublicMarkdownRelativeLinksResolveInsideRepository` test passed+(1 passed, 0 failed), run from Aetheris.CLI.Tests in Release with `--no-build`,+`-m:1`, `-nr:false` and one test CPU. Relative links in every changed Markdown+file, balanced code fences, and `git diff --check` also pass. Only Markdown files+changed. No .NET runtime/test/build hosts remained after the checks. No compiler,+fixture or geometry changes are made, and no full .NET regression or pre/post+geometry qualification is claimed for documentation edits.++## Verdict++The entry document now has one learning order, runnable starting examples,+explicit fragment contexts, and a distinction between preferred style, current+admission and compatibility. Twenty syntax/teaching seams have named ownership+and dispositions. The ignored include and schema-formatting cases remain real+correctness defects for the next implementation pass. A cleaner manual must+not be mistaken for a repaired compiler.diff --git a/docs/development/firmament-language-inconsistencies.md b/docs/development/firmament-language-inconsistencies.mdindex eb41f538..a4d86272 100644--- a/docs/development/firmament-language-inconsistencies.md+++ b/docs/development/firmament-language-inconsistencies.md@@ -1,5 +1,11 @@# Firmament language reconciliation register+October 14 documentation review: the [current syntax review](FIRMAMENT-SYNTAX-REVIEW-2026-10.md)+records twenty author-visible seams, including reproduced ignored mechanical+includes, schema-formatting admission gaps and symmetry casing failures.+Historical classifications below remain preserved; they do not close those+current findings or assert a uniform whole-language grammar.+October 2026 qualification: historical resolved classifications below do not close the route-dependent correctness gaps in the [October decision register](FIRMAMENT-LANGUAGE-DECISIONS-2026-10.md) and [frontend X0 report](../release/FIRMAMENT-FRONTEND-X0.md). In particular, root admission and consumed-source integrity remain incomplete.This A5d register classifies the language seams first exposed by A5b and completes the Template reconciliation begun in A5c. The public dialect is defined by [`docs/public/firmament`](../public/firmament/overview.md), especially the [language-style contract](../public/firmament/language-style.md) and [Templates guide](../public/firmament/templates.md). Parser/lowering ownership is recorded in the [active grammar inventory](firmament-v2-grammar-inventory.md).diff --git a/docs/public/firmament/geometry.md b/docs/public/firmament/geometry.mdindex 192054d8..40d5c07f 100644--- a/docs/public/firmament/geometry.md+++ b/docs/public/firmament/geometry.md@@ -12,7 +12,13 @@ A face-local `Hole<Shaft>` or `Hole<Counterbore>` on a `Box` may cross the edge## Boss-Known placement inconsistency: a plain direct `Box` currently exports from Z = 0 to its height, while the direct semantic Hole route without Concept IR centers the stock about Z = 0. Adding a hole can therefore change world placement even when dimensions are unchanged. Inspect STEP bounds when composing these parts; the [LANG-BURN-X1 report](../../release/LANG-BURN-X1-FIRMAMENT-BURN-IN.md) preserves the repro and proposed compatibility-aware repair. Explicit Profile/Compose `From`/`To` intervals avoid this route-dependent placement.+Direct Box stock and its semantic Hole host use the same bottom-anchored frame:+X/Y are centered and Z runs from 0 to height. Adding a direct Hole does not+recenter the stock. The earlier discrepancy in the+[LANG-BURN-X1 report](../../release/LANG-BURN-X1-FIRMAMENT-BURN-IN.md) is historical;+the [stock-frame regression](../../../Aetheris.Kernel.Firmament.Tests/FirmamentV2SemanticHoleTests.cs)+checks host and materialized bounds. Profile/Compose construction uses its+explicit `from`/`to` interval.`Boss` is the first-class finite profile feature for adding connected material. In Preview 3 it is declared inside the active profile-based `Compose` body, targets that body's top support (`On: Top`), consumes an already-admitted line/arc `Profile`, and extrudes outward along `+Z` by a positive `Height`. A `Compose` does not reopen or augment a separately declared direct `Box`; use a rectangular Base Profile when the stock is box-shaped.@@ -127,7 +133,7 @@ The canonical [Boss + Pocket block](../../../fixtures/Canonical/Features/Boss/boFor readable local geometry, start with the [line/arc Concept Path](../../../fixtures/Canonical/Profiles/concept-path-line-arc-profile.firmament). The [profile-delta recess](../../../fixtures/Canonical/Profiles/profile-delta-recess-extrusion.firmament) then shows that semantic `ProfileDelta` programming is not Sheet-Metal-specific: a Table row, `with` override, and typed Template modify an ordinary extruded profile.-For geometry that already exposes named spans, prefer the finite [Profile pipeline flagship](../../../fixtures/Canonical/Pipeline/profile-pipeline-flagship.firmament). `Stock.Bottom |> Stock.Right |> Stock.Top |> Stock.Left |> Close` inherits segment identities and derives endpoint continuity and orientation from the named source geometry. The [mixed line/arc witness](../../../fixtures/Canonical/Pipeline/line-arc-profile.firmament), [inner-loop witness](../../../fixtures/Canonical/Pipeline/profile-with-inner-loop.firmament), [open Concept Path](../../../fixtures/Canonical/Pipeline/open-path.firmament), and [whole-loop trace](../../../fixtures/Canonical/Pipeline/traceloop-profile.firmament) exercise the same resolved Profile/Path boundary. Use manual `Segment` declarations when bespoke endpoints, circle-arc sweep selection, or debugging requires explicit low-level control.+For geometry that already exposes named spans, prefer the finite [Profile pipeline flagship](../../../fixtures/Canonical/Pipeline/profile-pipeline-flagship.firmament). `Stock.Bottom |> Stock.Right |> Stock.Top |> Stock.Left |> Close` inherits segment identities and derives endpoint continuity and orientation from the named source geometry. The [mixed line/arc witness](../../../fixtures/Canonical/Pipeline/line-arc-profile.firmament), [inner-loop witness](../../../fixtures/Canonical/Pipeline/profile-with-inner-loop.firmament), [open Concept Path](../../../fixtures/Canonical/Pipeline/open-path.firmament), and [whole-loop trace](../../../fixtures/Canonical/Pipeline/traceloop-profile.firmament) exercise the same resolved Profile/Path boundary. Pipelines also support named endpoint selection with `From`/`To` and arc traversal with `Reverse`; see [syntax](syntax.md#constructing-from-a-layout). Use manual `Segment` declarations when deliberate low-level control or debugging requires them.Sheet Metal has its own `Hole Name` syntax for planar circular openings; countersink and counterbore forms are Model-domain features and deliberately fail in Sheet Metal rather than being ignored.diff --git a/docs/public/firmament/language-style.md b/docs/public/firmament/language-style.mdindex 38d82d3e..5ac2aa0c 100644--- a/docs/public/firmament/language-style.md+++ b/docs/public/firmament/language-style.md@@ -28,6 +28,13 @@ standards, imported identities and part numbers retain their source spelling.Existing PascalCase properties and supported historical aliases remain accepted,without style warnings. Older examples need not be rewritten wholesale.+The table describes preferred style, not universal case folding. Some owners+still require PascalCase built-ins: Profile pipeline `From`/`To`, `Reverse`,+`Close`, `TraceLoop`, mirror `From`/`Across`, and radial `Source`/`About`/`Count`/`Angle`.+Use those admitted forms today. The [syntax review](../../development/FIRMAMENT-SYNTAX-REVIEW-2026-10.md)+tracks these gaps; the formatter must not be treated as proof that every owner+admits a lowercased spelling.+```firmamentFeature Coil(center: Point2, width: Length, depth: Length,height: Length, support: Plane) -> Boss {diff --git a/docs/public/firmament/revolve.md b/docs/public/firmament/revolve.mdindex 04ef7167..36a38e0b 100644--- a/docs/public/firmament/revolve.md+++ b/docs/public/firmament/revolve.md@@ -20,6 +20,35 @@ Revolve Ring {The axis must preexist, have a finite nonzero direction, and lie in the Profile construction plane. The Profile frame fixes the zero-angle radial direction; partial revolutions do not use a hidden world-axis orientation. Arbitrary 3D axes are supported when they are coplanar with the Profile.+## A semicircular meridian++**Complete file:** this example selects a circular span with named endpoints,+closes it along the axis, and revolves that Profile into a sphere. It uses the+ordinary Mechanical schema; there is no `schema Revolve`.++```firmament+schema Mechanical++Model RevolvedSphere {+ units: mm+ Axis mainAxis { origin: [0mm, 0mm, 0mm]; direction: [0, 1, 0] }+ Point2 south { position: [0mm, -20mm] }+ Point2 north { position: [0mm, 20mm] }+ Point2 center { position: [0mm, 0mm] }+ Concept Circle2 meridian { center: center; radius: 20mm }+ Line2 diameter { from: north; to: south }+ Profile sphereSection {+ meridian From south To north as arc+ |> diameter as axisClosure+ |> Close+ }+ Revolve ball { profile: sphereSection; about: mainAxis; angle: full }+}+```++Pipeline endpoint words currently use `From`/`To`; fields such as `from:` use+camelCase. See [Writing Firmament](syntax.md) for the distinction and conventions.+## AnglesRadians are dimensionless numeric values. Degree literals use `deg`. The lowercase semantic aliases `quarter`, `half`, and `full` mean π/2, π, and 2π. All forms lower through one angle path.diff --git a/docs/public/firmament/syntax.md b/docs/public/firmament/syntax.mdindex bdd8ae2d..57f28c08 100644--- a/docs/public/firmament/syntax.md+++ b/docs/public/firmament/syntax.md@@ -1,17 +1,25 @@-# Firmament V2 syntax+# Writing Firmament-## Definitions, values and construction+Firmament describes finite engineering artifacts at compile time. Start with a+`Model`, describe its construction, then validate and build it. Geometry is+materialized from that description; the source has no runtime objects or+interactive program loops.-Firmament describes a finite engineering artifact at compile time. `Model` is the-class-like owner of an artifact, `Struct` groups reusable construction, `Feature`-is a typed function-like recipe, and `Pattern` performs bounded repetition.-These analogies explain organization; they do not introduce runtime objects,-inheritance, mutable state or arbitrary loops.+This page teaches common mechanical authoring, then points to other domains.+**Complete files** can be saved and built on their own. **Fragments** require+the stated enclosing declarations. A form being legal in one domain does not+make it legal in every other domain.++## A first part++**Complete file — a plate with a through hole:**```firmamentModel Plate {units: mm+Box stock { size: [80mm, 50mm, 8mm] }+Modify stock {Hole<Shaft> mount {on: +Z@@ -23,336 +31,457 @@ Model Plate {}```-A declaration has a PascalCase construct or type, an optional `<Variant>`, a-case-sensitive name and a brace-delimited body. Fields use `camelCase: value`.-Lists use brackets; calls use parentheses. Separate adjacent fields with a newline-or semicolon; dense one-line bodies may also use the owning grammar's established-field boundaries. Required terminators in specialized grammars are documented in-their guides.+`stock` names the body. `Modify stock` applies the hole to it. `Hole<Shaft>`+selects a built-in variant; `ThroughAll` specifies termination. This Box is+centered in X/Y and bottom-anchored in Z: its height runs from 0 to 8mm. Adding+this hole does not change the stock's placement.-| Source role | Preferred spelling |-| --- | --- |-| Constructs and types | `Model`, `Struct`, `Box`, `Profile`, `Feature`, `Length` |-| Built-in fields | `units`, `size`, `center`, `counterboreDepth` |-| Linking words | `using`, `as`, `on`, `over`, `with`, `include`, `expose`, `bind` |-| Local values and parameters | `stock`, `outline`, `mountPoint`, `depth` |-| Engineering symbols and enum values | `XY`, `+Z`, `Outer`, `ThroughAll`, `World`, `mm` |--`Profile outline using layout` selects its construction frame/context;-`guide.Bottom as south` gives traced geometry an explicit identity. `Using` and-`As` remain admitted aliases at those grammar positions. A field such as-`on: +Z` is distinct from a header clause such as `Concept Struct layout on XY`.-See [language style](language-style.md) for formatting and compatibility rules.--Built-in PascalCase field aliases remain admitted by their owners. User names,-named recipe arguments and published members preserve their authored spelling;-`Spec.Width` is not automatically renamed to `spec.width`. Unknown statements or-fields are errors in migrated AST scopes, regardless of whether the remaining-geometry could build.--## Frontend schema and validation--An optional `schema <Name>` header selects a specialized frontend. Put it before-`Model`, after any leading comments. Explicit selection is authoritative: rejection-does not retry another frontend. `Revolve` belongs to `Mechanical`; it is not a-schema name.--| Schema | Authoring guide |-| --- | --- |-| `Mechanical` | Ordinary parts, profiles and semantic features; the example above. |-| `WireForm` | [Formed wire](wire-form.md), bends and coils. |-| `Sweep` | Circular-section Concept Path sweeps. |-| `SectionChain` | [Section chains](section-chains.md) and ruled/G1 bodies. |-| `Garment` | [Garments](garments.md), panels, stitch interfaces and fitting poses. |--Use `aetheris validate file.firmament --json` before building. Normal mechanical-validation performs engineering compilation in memory. `--parse-only` reports-`ParsedNotBuilt`, rather than claiming geometry construction has succeeded.-`--explain` exposes the chosen parser route as developer metadata. See-[diagnostics](../reference/diagnostics.md) for the structured diagnostic contract.--Normal mechanical construction, Revolve, Gear, Panel, Plateau, SectionChain and-Loft bind their admitted inputs from the shared recursive-descent AST. Lowercase-primitive solids, derived Box records, exposure aliases, Hole modifications and region/cut operations now-use that AST too; their remaining legacy semantic extensions have separate owners.-See [migration status](../../release/FIRMAMENT-LOWERCASE-AST-MIGRATION.md) for the-qualified boundary. Specialized frontend coverage is not a promise of a single-whole-language AST binder yet.--## Compatibility spelling--New source uses `Model`, `units: mm` and direct named primitives, as above.-Historical `model`, `units mm`, `solid name: Box`, `modify` and `hole<shaft>` are-bounded compatibility spellings. Inside that historical primitive grammar only,-bare length values inherit the model's millimetres. Native fields retain explicit-dimensional values: write `size: [30mm, 24mm, 12mm]`.--`solid tall: stock with { size: [30, 24, 20] }` retains immutable Box derivation:-the original `stock` is unchanged. `expose { face(+Z) as top }` names a face;-the historical `face(+Z) => top` association remains compatible. Neither form-requests an extra geometric operation.--These aliases preserve legitimate existing intent; they do not establish a second-preferred language. The convention formatter does not mechanically convert old-solid grammar into native declarations. Serialization-shaped V1 `model:` and-`firmament:` documents have an explicit compatibility boundary and are not native-V2 examples. Unknown casing is never a request for arbitrary case-insensitive-interpretation.--## Reusable semantic construction with Feature--`Feature` is Firmament's function-like abstraction for reusable semantic construction. It accepts typed inputs and returns exactly one typed semantic output. Feature evaluation is pure, deterministic, file-local, and expanded before Feature AIR; a definition does not materialize geometry until it is invoked.+Save it as `plate.firmament`, then run:-```firmament-Feature M8Counterbore(center: Point2, depth: Length = 4mm) -> Hole<Counterbore> {- let counterboreDiameter: Length = 8.5mm + 5.5mm- return Hole<Counterbore> {- on: +Z- center: center- diameter: 8.5mm- counterboreDiameter: counterboreDiameter- counterboreDepth: depth- end: ThroughAll- }-}--Modify Plate {- M8Counterbore(center: Point2(-20mm, 0mm))- M8Counterbore(center: Point2(20mm, 0mm), depth: 5mm)-}+```sh+aetheris validate plate.firmament --json+aetheris build plate.firmament --output artifacts/local/plate.step```-Parameters are strongly typed and calls may use positional or named arguments. Defaults are optional. A body contains immutable typed `let` derivations and optional private `Point2`, `Line2`, `CubicBezier2`, `Rect2`, `RoundedRect2`, `Circle2`, and `Profile` construction declarations followed by one terminal `return`. Local construction names are qualified separately for each invocation. Product Templates specialize before Feature argument binding; Feature results then lower before patterns and Feature AIR. A Feature may return `Hole<Shaft>`, `Hole<Counterbore>`, `Hole<Countersink>`, `Boss`, `Pocket`, `EdgeFinish`, or `Profile`, and may call another Feature with the same return type. Direct and indirect recursion are rejected. Feature names occupy the callable namespace, separate from typed construction declarations such as `Profile`. Named results use `Feature Name = Function(...)`; the name becomes the returned feature identity and appears in invocation inspection. See [functional pickup construction](functional-pickup.md) for a qualified part example and [garment authoring](garments.md) for reusable Profile recipes.+Normal mechanical validation performs engineering compilation in memory.+`--parse-only` reports `ParsedNotBuilt`; it does not prove the part can be built.+`--explain` adds developer information about admission and the chosen frontend.+See [diagnostics](../reference/diagnostics.md) for interpreting failures.-Firmament intentionally does not provide general runtime control flow. `if`/`else`, conditional expressions, `match` inside Feature, mutable variables, exceptions, and `for`/`while` loops are rejected. A Firmament program describes one deterministic engineering construction, not a runtime family of topologically unrelated outputs.+## How to read the language-Use each abstraction for its single role:+The useful organizing analogy is `Model` as a class-like artifact owner, `Struct`+as reusable construction, `Feature` as a typed function-like recipe, and `Pattern`+as a finite loop. These analogies do not promise inheritance, runtime methods,+mutation or general-purpose computation.-| Construct | Role |+| Construct | What it describes || --- | --- |-| `Feature` | Function-like reusable semantic construction. |-| `Pattern` | Bounded finite geometric repetition; it is the loop substitute. |-| `Template` | Compile-time product/configuration specialization; it is the structural branch substitute. |-| `|>` | Finite semantic composition of compatible Profile/Path geometry. |-| `Concept` | Semantic contract or capability. |-| `Record` / `Struct` | Typed data and semantic structure. |-| `Set<T>` | Finite immutable source-ordered data whose entries have stable names. |+| `Model` | An enclosing engineering artifact and its construction. |+| `Struct` | Named construction that may be specialized and used by a consuming artifact. |+| `Concept Struct` | Non-materialized construction data: points, guides, frames and semantic members. |+| `Concept` | A semantic contract, or a domain-qualified construction value such as `Concept Path`. |+| `Profile` | Named planar boundaries consumed by an extrusion or another feature. |+| `Feature` | A reusable recipe returning one typed semantic result. |+| `Template` | Typed compile-time specialization of a declared product or bounded feature recipe. |+| `Record` / `Static` | A data shape / an immutable compile-time binding. A Record is not a body. |+| `Pattern` | Finite repetition of admitted construction over a declared source. |+| `Assembly` / `Scene` | Product occurrences and relations / spatial presentation. |++Use `Model` for an ordinary standalone part. A Struct, Template library, Profile+module or Assembly has its own entry and consumption rules; it is not simply a+Model with a different keyword.++### Declarations, fields and names++These are notation sketches, not executable files:++```text+Construct name { field: value }+Construct<Variant> name { field: value }+Feature Recipe(parameter: Type = defaultValue) -> ResultType { ... }+Struct instance = ProductFamily<parameter: value>+```-Feature composes with an existing bounded Pattern without exposing its internals:+Braces delimit bodies, brackets delimit lists, parentheses delimit calls, and+`name.member` selects a published member. A colon labels a field, parameter or+declared type according to its context. Declaration bodies, typed values and+Template specializations are distinct forms, not interchangeable object literals.-```firmament-Feature MountHole(center: Point3, diameter: Length = 6mm) -> Hole<Shaft> {- return Hole<Shaft> {- on: Base.Top- center: center- diameter: diameter- end: ThroughAll- }-}+Identifiers and published member names are case-sensitive. Preserve library+names, including named call arguments. `spec.Width` does not become `spec.width`+because the preferred local name is camelCase.-Concept Struct Design {- Bounds: Box3 { Size: [60mm, 40mm, 10mm] }- Points: Grid {- Within: Bounds.Face(+Z).Inset(8mm)- Columns: 2- Rows: 2- }-}+### Capitalization-Pattern Mounts {- Source: Design.Points- MountHole(center: Item)-}-```+| Role | Preferred spelling | Examples |+| --- | --- | --- |+| Constructs and types | PascalCase | `Model`, `Box`, `Feature`, `Length`, `Point2` |+| Built-in fields | camelCase | `units`, `size`, `counterboreDepth` |+| Local geometry, values and parameters | camelCase | `stock`, `outline`, `mountPoint`, `depth` |+| Linking words in their admitted positions | lowercase | `using`, `as`, `on`, `over`, `with`, `include`, `expose`, `bind` |+| Engineering symbols and enum values | Preserve domain spelling | `XY`, `+Z`, `Outer`, `ThroughAll`, `World`, `mm` |-The two-column, two-row Grid is the explicit four-hole rectangular distribution. This semantic PointSet Pattern uses `Item`. The older `Pattern Name over Records { Template<Current> }` form remains the record-array composition syntax for finite feature Templates; `Current` is the selected record. Feature functions do not replace that compatibility form.+`Profile outline using layout` selects a construction context;+`boundary.Bottom as south` assigns an output identity. `Using` and `As` remain+accepted aliases at those positions. A header clause such as+`Concept Struct layout on XY` differs from a field such as `on: +Z`.-A Feature may return a call to another Feature with the same declared result type:+This convention is not global case-insensitive parsing. Owners admit many+PascalCase field aliases, but some still **require** particular spellings.+Use `From`, `To`, `Reverse`, `Close` and `TraceLoop` in Profile pipelines.+Symmetry currently requires `From`, `Across`, `Source`, `About`, `Count` and+`Angle` in the forms below. Do not lowercase them merely to match the style table.+See [language style](language-style.md) for formatter behavior.-```firmament-Feature CoreCounterbore(center: Point2, depth: Length) -> Hole<Counterbore> {- return Hole<Counterbore> {- on: +Z- center: center- diameter: 8.5mm- counterboreDiameter: 14mm- counterboreDepth: depth- end: ThroughAll- }-}+### Whitespace, comments and terminators-Feature M8Counterbore(center: Point2) -> Hole<Counterbore> {- return CoreCounterbore(center: center, depth: 4mm)-}-```+Use two-space indentation. Put ordinary fields on separate lines, or separate+them with semicolons in a short body. Separate list elements and call arguments+with commas. Do not rely on the parser guessing dense adjacent field boundaries.++Use `//` for comments, including before an optional `schema` header. The shared+lexer also recognizes `/* ... */`, but the schema selector currently rejects a+block comment before that header. `#` is not a general comment marker.++Some specialized forms **require** semicolons: scalar Function expressions,+point-recipe fields, PMI Note fields and Assembly root-provenance statements.+Follow the consuming guide; there is no uniform statement-termination rule yet.++### Values and units-Structurally different edge finishes should be separate Features —for example, `StandardChamfer` and `StandardFillet`. A caller may instead select a specialized product with Template where that owning Template grammar admits the returned construction. Feature itself cannot branch between them.+Write dimensions explicitly in new mechanical source: `8mm`, `90deg`,+`Point2(12mm, -4mm)`. Use bare numbers for dimensionless counts and vector+components. `units: mm` belongs in an ordinary mechanical Model; it does not+make dimensions optional in every native field.-Feature is supported by the `Mechanical` frontend. `WireForm`, `Sweep`, and `SectionChain` reject Feature declarations explicitly; shared cross-schema Feature IR and module/library packaging are deferred.+Points and lists overlap without being universal aliases. The direct Hole above+requires `Point2(...)`; a Rect2's `center` accepts `[x, y]`. A semantic Grid may+publish Point3 values in its own frame. Use the field owner's documented type+and spelling rather than replacing all point forms mechanically.+Arithmetic is available in admitted value positions, with dimensional checks.+Expression support is not uniform across every field, Template argument and+domain. `Static` and Feature-local `let` are scoped compile-time facilities;+there is no general `let`-anywhere rule. Scalar `Function` recipes are described+in [points and functions](concept-points-and-functions.md).-## Finite named sets and mapping+## Constructing from a layout-`Set<T>` is a finite immutable collection of named typed values. Use it when entries have semantic identity and should be addressable by name; use `T[]` for an anonymous ordered sequence.+Use a `Concept Struct` for design geometry, trace its named guides into a+`Profile`, then consume that Profile. The layout itself creates no material.++**Complete file — a profile extruded from Z = 0 to 12mm:**```firmament-Static MountPoints: Set<Point2> {- LowerLeft => Point2(-16mm, -9mm)- LowerRight => Point2(16mm, -9mm)- UpperLeft => Point2(-16mm, 9mm)- UpperRight => Point2(16mm, 9mm)-}+Model ProfilePlate {+ units: mm-Pattern Mounts over MountPoints {- point => M8Counterbore(center: point)-}-```+ Concept Struct layout on XY {+ Rect2 boundary { center: [0mm, 0mm]; size: [30mm, 24mm] }+ }-`MountPoints.LowerLeft` has type `Point2`; Record-valued entries compose naturally, for example `MountSpecs.Left.Center`. Set entry names are unique, values may be equal, and authored order is authoritative. An empty typed Set is valid and a Pattern over it produces zero instances. Inspection exposes the element type, cardinality, entries, source order, provenance, and generated associations.+ Profile outline using layout {+ Loop Outer {+ boundary.Bottom as south+ |> boundary.Right as east+ |> boundary.Top as north+ |> boundary.Left as west+ |> Close+ }+ }-Inside a Set, `Name => Value` is a named association. Inside Pattern, `value => construction` maps every member of that finite Set to one semantic construction. Neither spelling is conditional control flow. Set has no mutation, indexing, filtering, sorting, `Map`, `Fold`, arbitrary keys, or runtime collection API, and Pattern retains the existing 1,024-instance safety bound.+ Extrude stock { profile: outline; from: 0mm; to: 12mm }+}+```-Choose among the closed data forms by meaning: a `Record` is one structured value; an `Enum` is one-of-N alternatives; `T[]` is anonymous ordered data; `Set<T>` is a dataset in which all N named entries exist simultaneously. Pattern performs finite construction mapping, Feature supplies a reusable semantic transformation, and `|>` composes finite compatible geometry. Match is unchanged.+`|>` traces finite compatible geometry in source order. The first stage chooses+its source direction; later stages orient themselves to the current endpoint.+A disconnected or ambiguous continuation fails. `Reverse` prefers reversed+orientation, falling back to a connectable direction after the opening stage.+`Close` verifies closure; it never supplies a missing line.-## Mirror and radial symmetry+`boundary |> TraceLoop` copies a whole closed guide and normalizes winding for+the target loop. Supported families include Rect2, Square2, RoundedRect2,+Polygon2, RegularPolygon2, closed Concept Paths, Circle2 and Ellipse2. A full+circle or ellipse retains a single boundary segment; its traced identity derives+from the guide name, allowing distinct inner/outer guides.-Mirror and radial Pattern are resolved before geometry materialization. They transform semantic construction intent, not finished BRep topology.+Segment identities are Profile-wide. Loops do not silently namespace duplicate+edge names. Use `as` to disambiguate repeated leaf identities, or rename a manual+Segment. Manual `Segment` construction remains available for low-level control;+ordinary profiles can use pipelines.-An explicitly named destination derives from an existing Profile or concrete feature and an existing Plane:+**Fragment — endpoint selection inside a Profile pipeline, with the named guide+and points already declared:**```firmament-Plane CenterPlane { origin: [0mm,0mm,0mm]; normal: [1,0,0]; up: [0,0,1] }-Hole<Shaft> LeftMount { on: +Z; center: Point2(24mm,0mm); diameter: 6mm; end: ThroughAll }-Mirrored Feature RightMount From LeftMount { Across: CenterPlane }+guide From startPoint To endPoint as selectedEdge```-Profiles may use either that direct Plane spelling or a `Construction Plane` traced from a `Concept Struct` Plane. Reflection analytically transforms points and curves, reverses arc traversal, then restores the Profile's canonical outer/inner winding. Frames use reflected origin/X/Z followed by canonical right-handed Y reconstruction; negative-determinant frames never reach a consumer. Mirroring an already-materialized STEP/BRep is not safe authoring and is not provided by this syntax.+After the opening stage, `guide To endPoint` uses the preceding endpoint as its+start. Endpoints must be named points on the guide. Circular spans use the same+form; `Reverse` selects the opposite traversal. `|>` is not a general map, filter,+arithmetic or function-composition operator. A Concept Path may remain open;+a material Profile must satisfy its boundary rules.-Keep the source Profile semantic too. For example, an arbitrary triangular source should be authored as `Triangle2<Explicit> LeftBoundary { A: [...] B: [...] C: [...] }` and consumed with `LeftBoundary |> TraceLoop`; an axis-aligned four-sided section should use `Rect2`. Use `Polygon2<Explicit>` only when the linear boundary is genuinely an otherwise-unconstrained polygon. Closed boundaries lower to ordinary named Profile guides before Mirror resolves them.+Closed boundaries should express their engineering shape. Use Rect2 for a+rectangle, Triangle2 for a triangle, or a named Polygon2 variant. Current Polygon2+variants include `Rhombus`, `Parallelogram`, `Trapezoid` and `Explicit`. Explicit+references a named point set; it does not introduce inline arbitrary vertex-array+syntax. `RegularPolygon2<N>` uses a bounded vertex count. These are built-in+shape parameters, not user-extensible generic types.-A radial feature Pattern uses an existing Axis and includes the source construction as instance zero:+**Fragment — layout and Profile declarations inside a Model:**```firmament-Axis MainAxis { origin: [0mm,0mm,0mm]; direction: [0,0,1] }-Hole<Shaft> BoltSeed { on: +Z; center: Point2(26mm,0mm); diameter: 6mm; end: ThroughAll }-Radial Pattern BoltCircle { Source: BoltSeed About: MainAxis Count: 6 Angle: full }+Concept Struct layout on XY {+ Polygon2<Rhombus> diamond {+ center: [0mm, 0mm]+ diagonals: [90mm, 64mm]+ }+}+Profile outline using layout { Loop Outer { diamond |> TraceLoop } }```-`Count` is in `1..1024`; one is a valid trivial Pattern. `full` uses `theta[i] = i * 2*pi/Count` and omits the full-angle duplicate endpoint. Partial angles use inclusive endpoints, `theta[i] = i * Angle/(Count-1)`. Angles reuse Revolve spellings (`radians`, `deg`, `quarter`, `half`, `full`). Current radial feature lowering is deliberately bounded to planar Point2-centered Hole semantics about the support-normal Axis. Profile radial Pattern, whole Model/Struct derivation, arbitrary selector rebinding, Boss/Pocket radial derivation, and assembly occurrence symmetry remain explicit future qualifications.+The diagonals are full positive lengths, giving vertices at the south, east,+north and west half-diagonal offsets. This still needs a material consumer such+as Extrude. For a circular span and full material consumer, see the complete+[semicircular Revolve example](revolve.md#a-semicircular-meridian).-Intentional asymmetry uses immutable `with`, not a mirror-exception mini-language:+See [geometry](geometry.md), [spans](spans.md), [Concept derivation](concept-derivation.md)+and [boundary edits](profile-boundary-edits.md) for detailed construction forms.-```firmament-Mirrored Feature RightMount From LeftMount { Across: CenterPlane }-Feature RightMountCustom = RightMount with { Diameter: 8mm }-```+## Adding and removing material-The derived feature retains the source/mirror/override provenance chain in `inspect --json`. Material, scalar magnitudes, and enum tags are invariant values; meaningless declarations such as `Mirrored Material` fail typed.+`Modify` targets an existing body. `Compose` creates a profile-based body with a+base material interval and admitted operations inside it. Compose does not+reopen a separately declared Box, and neither construct admits arbitrary Boolean+or feature combinations.-A Profile exactly on its reflection line may be retained as an equivalent named semantic derivation because it has not yet created material. A concrete feature whose center is unchanged is rejected as `firmament-symmetry-redundant-feature-mirror` so a Compose/Modify cannot silently create coincident duplicate material.+| Intent | Current vocabulary | Placement / termination |+| --- | --- | --- |+| Drill a hole | `Hole<Shaft>`, `Hole<Counterbore>`, `Hole<Countersink>` | `on`, `center`, `end: ThroughAll` or a bounded blind end. |+| Add a profile boss | `Boss` in profile-based Compose | Top support, a Profile and positive `height`. |+| Remove a finite-depth recess | `Pocket` in profile-based Compose | Profile and positive `depth`; must leave the admitted floor. |+| Cut through a profile-based body | Admitted `Remove` with `Role: ThroughCut` | Use the through-cut form rather than a through-depth Pocket. |+| Make a capsule slot | `Slot<Capsule>` in its admitted composition | `length`, `width`, `direction`, `extent` and `role`. |+| Finish selected edges | `EdgeFinish` with `kind: Chamfer` or `kind: Fillet` | Selector and capability depend on the target body. |-### Built-in closed polygons+For a primitive boundary chamfer, the selector is `face: +Z` plus+`target: Boundary`; a profile-composed finish names its Profile boundary and+support instead. `EdgeFinish<Chamfer>` is not the direct primitive spelling.+A bare `Fillet corners { ... }` is not an alternative EdgeFinish declaration.-`Polygon2<Rhombus>` is the first bounded closed-polygon authoring form. A rhombus is specified by its center and full horizontal/vertical diagonal lengths:+Read the [feature support and examples](geometry.md) before combining operations.+A feature's existence does not imply that every combination is admitted.+Unknown syntax, unresolved selections and unsupported operations must be+diagnosed; plausible remaining geometry is not evidence that all intent ran.-```firmament-Concept Struct Layout on XY {- Polygon2<Rhombus> MountBoundaryShape {- center: [0mm, 0mm]- diagonals: [90mm, 64mm]- }-}+### Frames and selectors-Profile MountBoundary using Layout {- Loop Outer { MountBoundaryShape |> TraceLoop }-}-```+`XY`, `XZ`, an axis such as `+Z`, a Plane, a datum frame and a published face are+different reference types. `on` appears in several contexts; it is not one+universal placement operation. A profile context, Hole support, section frame+and Assembly attachment each have their own type and admission rules.++Use only a plane or frame admitted by that consumer. Do not assume replacing+`on XY` with `on XZ` rotates every downstream feature. Follow+[Concept derivation](concept-derivation.md) and the consuming guide; unsupported+placement must reject rather than substitute XY.-This produces vertices at south, east, north, and west half-diagonal offsets and a counter-clockwise closed boundary. It lowers before pipeline validation to the ordinary typed `Point2`, `Line2`, and Profile path, so closure, orientation, Span containment, materialization, and STEP export keep their existing owners.+Native named faces, signed primitive faces and imported `#face` references are+also distinct. Assembly occurrence identity does not by itself define a mate.+See [STEP import](step-import.md), [assembly foundations](assembly-authoring-foundation.md)+and [datum seating](datum-seating.md).-The angle-bracket argument is a closed built-in shape variant, not a general generic or user-defined type. The admitted variant is `Rhombus`; both diagonals must be finite positive lengths. It intentionally does not add arbitrary vertex arrays, `Connect`, a scene graph, or a second polygon materializer. Use `Rect2` when the four sides are axis-aligned; unequal horizontal and vertical rhombus diagonals do not describe that rectangle.+## Reusing construction-## Finite Profile and Path composition+### Feature: a typed recipe-Named single-loop Profiles can be placed through Concept Curve2 values before-being traced into a new Profile. See [Concept derivation](concept-derivation.md)-for From/On/Translate/Rotate and bounded uniform Scale/Pivot syntax.+A Feature definition describes one result. Calling it materializes that result+in an admitted consuming scope. Parameters may be positional or named, with+defaults. A body may contain typed immutable `let` derivations and admitted+private construction, followed by one terminal `return`. Calls may delegate to+another Feature with the same result type; recursion is rejected.-`|>` composes compatible semantic geometry in a finite authoring pipeline. In a Profile loop, each source span is traced in authored order and automatically oriented to continue from the preceding endpoint:+Return kinds include Hole variants, Boss, Pocket, EdgeFinish and Profile. A+definition does not grant those results new support in an unsupported consumer.+Feature-local Profile construction is also used by Garment; WireForm, Sweep and+SectionChain reject Feature declarations.++### Pattern: finite repetition++**Complete file — two named points mapped to two holes:**```firmament-Profile BaseProfile using Layout {- Loop Outer {- Stock.Bottom- |> Stock.Right- |> Stock.Top- |> Stock.Left- |> Close+Model MountingPlate {+ units: mm++ Feature Drill(center: Point2, diameter: Length = 6mm) -> Hole<Shaft> {+ return Hole<Shaft> {+ on: +Z+ center: center+ diameter: diameter+ end: ThroughAll}+ }++ Static mountPoints: Set<Point2> {+ left => Point2(-12mm, 0mm)+ right => Point2(12mm, 0mm)+ }++ Box stock { size: [50mm, 30mm, 8mm] }+ Modify stock {+ Pattern mounts over mountPoints {+ point => Drill(center: point)+ }+ }}```-The first stage uses its source direction. Later stages match the current endpoint against the candidate span's endpoints. A unique end match reverses the traced geometry automatically; no match reports `firmament-profile-pipeline-disconnected`, and a degenerate two-way match reports `firmament-profile-pipeline-orientation-ambiguous`. `Reverse Stock.Left` prefers reversed orientation first and then falls back to the normal connectable orientation; on the opening stage it selects the initial direction. `Stock.Bottom as MountingEdge` changes the output segment identity while retaining source provenance.+The Pattern belongs **inside the target Modify**, not at the root of this file.+Each Set entry has a unique stable name; equal values are allowed and source+order is authoritative. `mountPoints.left` selects that value. An empty typed+Set yields zero mapped instances. Arrays provide anonymous ordered data; Sets+provide named ordered data. Pattern has a 1,024-instance safety bound.-To trace only part of a guide, use `Guide To Point`. The current pipeline endpoint is the implicit start. On the opening stage, use `Guide From Start To End`; `Guide To End` may omit `From` when the guide's natural start is intended. Endpoints must be named points on the guide. This is bounded selection, not a general slicing expression:+`=>` in a Set associates a name with a value; in this Pattern it binds the element+name for finite mapping. It is not a general lambda syntax. Other owners still+have different Pattern forms:-```firmament-Profile Bracket using Layout {- Horizontal.Bottom as South- |> Horizontal.Right as East- |> Horizontal.Top To Notch as Inner- |> Vertical.Right To Vertical.TopRight as Upright- |> Vertical.Top as North- |> Vertical.Left To Horizontal.BottomLeft as West- |> Close-}-```+| Pattern source | Binding form |+| --- | --- |+| Named Set mapped to a Feature | `Pattern name over values { value => Recipe(value) }` |+| Semantic PointSet / Grid | `Pattern name { Source: layout.Points ... Item ... }` |+| Record array with finite feature Template | `Pattern name over records { Recipe<Current> }` |+| Radial feature symmetry | `Radial Pattern name { Source: seed About: axis Count: n Angle: full }` |-The same form traces partial circular arcs. Endpoint order chooses the normal counter-clockwise circle span; `Reverse` selects the clockwise span. No pipeline `Sweep` keyword is needed.+These are context-specific forms, not interchangeable spellings of one loop.+`Item`, `Current` and an explicit element name are not global aliases. See+[Templates and finite data](templates.md) and the [functional pickup](functional-pickup.md).+A named Feature invocation may use `Feature result = Recipe(...)`; it differs+from a Feature definition and from a Pattern.-A half-circle revolve meridian uses the same syntax through the ordinary Mechanical schema:+### Template: specialize a product++**Complete file — one sized member of a product family:**```firmament-schema Mechanical--Model RevolvedSphere {- units: mm- Axis MainAxis { origin: [0mm, 0mm, 0mm]; direction: [0, 1, 0] }- Point2 South { position: [0mm, -20mm] }- Point2 North { position: [0mm, 20mm] }- Point2 Center { position: [0mm, 0mm] }- Concept Circle2 Meridian { center: Center; radius: 20mm }- Line2 Diameter { from: North; to: South }- Profile SphereSection {- Meridian From South To North as Arc- |> Diameter as AxisClosure- |> Close- }- Revolve Ball { profile: SphereSection; about: MainAxis; angle: full }+Template<width: Length, height: Length, thickness: Length>+Struct PlateFamily {+ Require positive => width > 0mm && height > 0mm && thickness > 0mm+ Box stock { size: [width, height, thickness] }}++Struct standardPlate = PlateFamily<width: 80mm, height: 50mm, thickness: 8mm>```-`|> Close` validates that the authored chain already closes. It never invents a missing line. Any admitted closed ordered guide family may be copied with `Outline |> TraceLoop`, including `Rect2`, `Square2`, `RoundedRect2`, `Polygon2`, `RegularPolygon2`, a closed `Concept Path`, `Circle2`, and `Ellipse2`. The resulting identities are the family's ordinary named edges; full circles and ellipses retain the single `Boundary` identity. `TraceLoop` normalizes winding for the target outer or inner loop when required.+The output declaration is explicit. Product Templates specialize Struct, Model,+Concept Struct, Panel, SheetMetal, Profile or ProfileDelta. `Require` checks+specialization admissibility. Typed Record values may carry a configuration;+`Static` binds them and `with` derives checked immutable values. A separate+finite feature-Template form is used by record-array Patterns.++`<...>` therefore means several things: a built-in Hole variant, a Set element+type, or Template parameters/arguments. It does not make every construct a+general generic. See [Templates](templates.md) for constraints, finite Tables,+supported argument types and compatibility forms.++Feature, Template and Pattern describe deterministic finite construction. They+do not add mutable state, exceptions, arbitrary recursion, `for`/`while`, or+general `if`/`else` control flow. Use domain-specific forms only where admitted.++## Mirror and radial symmetry++Symmetry transforms semantic construction before materialization. It does not+mirror a finished STEP/BRep. These fragments use the **currently required**+PascalCase symmetry fields, despite the general camelCase field convention.-Recognized guide declarations may appear at the start of an implicit-loop Profile body, followed by exactly one pipeline expression:+**Fragment — inside Modify, with a concrete `leftMount` Hole and a model-level+`centerPlane` already declared:**```firmament-Profile SideProfile using PositiveXWorkplane {- Rect2 Outline { center: [0mm, 0mm]; size: [20mm, 10mm] }- Outline |> TraceLoop-}+Mirrored Feature rightMount From leftMount { Across: centerPlane }+Feature largerMount = rightMount with { Diameter: 8mm }```-Segment names are Profile-wide identities. Manual `Segment` and pipeline stages both preserve their authored or inherited leaf names; loops do not silently qualify them. A traced full `Circle2` or `Ellipse2` derives its segment identity from the guide name, so `Outside |> TraceLoop` and `Inside |> TraceLoop` have distinct identities. If two loops would introduce the same name, binding reports `firmament-profile-segment-identity-collision`. Resolve the collision explicitly with `as` on the pipeline stages (for example, `Cutout.Bottom as CutoutBottom`) or by renaming a manual Segment.+`Mirrored Profile result From source { Across: plane }` derives a Profile.+Reflection transforms curves, restores loop winding and reconstructs a+right-handed frame. Construction Planes traced from Concept Planes are admitted+in the Profile form. Material, scalar magnitudes and enum tags are invariant;+`Mirrored Material` is not an admitted operation.++`with` derives a new feature with source/mirror/override provenance. A Profile+on its reflection line may remain an equivalent named derivation. A concrete+feature with an unchanged center rejects as a redundant coincident feature.-A `Concept Path` may also compose existing named spans and remain open:+**Fragment — inside Modify, with `boltSeed` and a model-level `mainAxis`:**```firmament-Concept Path Guide {- Stock.Bottom- |> Stock.Right- |> Stock.Top as Return-}+Radial Pattern boltCircle { Source: boltSeed About: mainAxis Count: 6 Angle: full }```-Pipeline source order is semantic order. Stages are limited to geometry references (qualified or unqualified), bounded `From`/`To` named endpoints, optional `Reverse`, optional `as`, `Close`, and `TraceLoop` in their admitted contexts. The operator has lower binding precedence than member access and does not admit arithmetic stages, calls, lambdas, conditionals, filtering, mutation, runtime execution, or repetition. Use Feature for a reusable semantic transformation, Pattern for bounded repetition, Template for specialization, and `|>` for finite semantic composition. Manual `Segment { Trace/From/To }` remains supported for compatibility and deliberate low-level parity tests; ordinary canonical Profile authoring does not require it.+The source is instance zero. `Count` is 1..1024. A full circle uses+`theta[i] = i * 2*pi/Count`, without a duplicate endpoint. A partial angle includes+both endpoints: `theta[i] = i * Angle/(Count-1)` when Count exceeds one. Angles+accept the Revolve spellings `radians`, `deg`, `quarter`, `half`, `full`.+Support is bounded to planar Point2-centered Holes about their support-normal+Axis. It does not imply Profile, Boss/Pocket, whole Struct or Assembly symmetry.++Complete sources: [mirrored hole](../../../fixtures/Canonical/Symmetry/mirrored-hole.firmament),+[mirror override](../../../fixtures/Canonical/Symmetry/mirrored-feature-with-override.firmament),+[radial bolt circle](../../../fixtures/Canonical/Symmetry/radial-bolt-circle.firmament).++## Choosing a domain and organizing files++An optional `schema Name` header selects one of these frontends. Put it on its+own line before declarations, preceded only by blank lines or `//` comments.+Do not put a trailing comment on the selector line: selection can currently be+bypassed by that formatting. Names are case-sensitive. A recognized explicit+selection is authoritative; rejection does not retry another frontend.+Revolve is an operation in Mechanical, not a schema.++| Schema | Guide |+| --- | --- |+| `Mechanical` | [Geometry](geometry.md), [Revolve](revolve.md), [gears](gears.md). |+| `WireForm` | [Formed wire](wire-form.md). |+| `Sweep` | [Circular-section sweeps](sweep.md). |+| `SectionChain` | [Framed section chains](section-chains.md). |+| `Garment` | [Panels, stitch interfaces and fitting](garments.md). |++This selector does not list every Firmament root or product domain. Assembly,+Scene, SheetMetal, structural and piping sources have their own entry forms.+Do not invent `schema Assembly` or wrap arbitrary domain declarations in a Model.++| Authoring task | Start here |+| --- | --- |+| Parts, ports, constraints and product occurrences | [Assemblies](assemblies.md), [components and sites](assembly-components-and-sites.md). |+| Spatial layout and presentation | [Scenes](scenes.md). |+| Sheet manufacturing, regions and bends | [Sheet metal](sheet-metal.md). |+| Structural / piping domains | [Structural](structural.md), [piping](piping.md). |+| Engineering annotations | [PMI](pmi.md). |+| File-backed modules and source-only projects | [Project snapshots](project-snapshots.md), [Concept derivation](concept-derivation.md). |++Assembly occurrence trees use `<Assembly>` / `<Part>` tags as well as brace+bodies. Tree nesting does not create a Mate. Inclusion is owned by the consuming+project/domain; `include` is **not** a universal mechanical preprocessor.+A bare include before an ordinary mechanical Model can currently be ignored,+even when its file is missing. Use a documented include consumer; the review+below preserves this reproduction.++## Reading older source++New ordinary parts should use the forms at the top of this page. Historical+`model`, `units mm`, `solid name: Box`, `modify` and `hole<shaft>` are bounded+compatibility forms. Bare lengths inherit millimetres only in the historical+primitive grammar that admits them. This is not a second preferred style.++Historical immutable Box derivation uses+`solid tall: stock with { size: [30, 24, 20] }`. Exposure uses+`expose { face(+Z) as top }`, with `=> top` also retained there. These forms do+not make `with`, `as` or `=>` universally interchangeable. Serialization-shaped+V1 `model:` and `firmament:` documents have an explicit compatibility path.++The formatter preserves names, published members and numeric values. It does+not migrate solid grammar into native declarations or prove a program builds.+Validate the consuming artifact after formatting.++## Current language seams++The preferred style is more consistent than the grammar enforced by every+owner. Author-visible differences remain in casing, points/lists, Pattern+binders, terminators, root/scope rules, frame/selector types, and meanings of+angle brackets and `with`. Some are legitimate domain distinctions; others are+compatibility debt or bugs.++The [October syntax review](../../development/FIRMAMENT-SYNTAX-REVIEW-2026-10.md)+records witnesses, current behavior, ownership and open decisions. It includes+the ignored mechanical include and schema-comment failures. It describes the+language as it exists, not unimplemented syntax. The [decision register](../../development/FIRMAMENT-LANGUAGE-DECISIONS-2026-10.md)+preserves the original authoring audit and later migration dispositions.++Use [supported features](../reference/supported-features.md) for capability+boundaries and the linked domain guides for detailed syntax. Proposals and+migration reports explain design/history; they do not grant source admission.