Skip to content

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.md
index 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 future
milestone assignment is a disposition, not an implemented feature. X0 remains
diff --git a/docs/development/FIRMAMENT-SYNTAX-REVIEW-2026-10.md b/docs/development/FIRMAMENT-SYNTAX-REVIEW-2026-10.md
new file mode 100644
index 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.md
index 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.md
index 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/bo
For 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.md
index 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.
+
```firmament
Feature 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.md
index 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.
+
## Angles
Radians 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.md
index 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:**
```firmament
Model 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.