Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Add canonical Firmament V2 document parsing

Yuechen Li93f01c17326a
diff --git a/Aetheris.Kernel.Firmament.Tests/FirmamentV2CanonicalGrammarTests.cs b/Aetheris.Kernel.Firmament.Tests/FirmamentV2CanonicalGrammarTests.cs
new file mode 100644
index 00000000..1c3fafe6
--- /dev/null
+++ b/Aetheris.Kernel.Firmament.Tests/FirmamentV2CanonicalGrammarTests.cs
@@ -0,0 +1,63 @@
+using Aetheris.Kernel.Firmament.FirmamentV2;
+
+namespace Aetheris.Kernel.Firmament.Tests;
+
+public sealed class FirmamentV2CanonicalGrammarTests
+{
+ [Fact]
+ public void CanonicalBarePrimitives_ParseIntoTheNormalizedV2Document()
+ {
+ foreach (var fixture in new[] { "bare-box.firmament", "bare-cylinder.firmament", "bare-rounded-box.firmament", "bare-frustum.firmament" })
+ {
+ var parsed = FirmamentV2Parser.Parse(File.ReadAllText(Fixture(fixture)));
+ Assert.True(parsed.IsSuccess, string.Join(Environment.NewLine, parsed.Diagnostics));
+ Assert.Equal(FirmamentV2ParseDisposition.RecognizedValid, parsed.Disposition);
+ Assert.Contains("firmament-v2-unified-canonical-parsed", parsed.Diagnostics);
+ Assert.Empty(parsed.Document!.ModifyBlocks!);
+ }
+ }
+
+ [Fact]
+ public void CanonicalModify_AdmitsHoleAndEdgeFinishInTheSameBlock()
+ {
+ var parsed = FirmamentV2Parser.Parse(File.ReadAllText(Fixture("box-hole-chamfer.firmament")));
+
+ Assert.True(parsed.IsSuccess, string.Join(Environment.NewLine, parsed.Diagnostics));
+ var modify = Assert.Single(parsed.Document!.ModifyBlocks!);
+ var hole = Assert.Single(modify.SemanticHoles);
+ var edge = Assert.Single(modify.EdgeFinishes!);
+ Assert.Equal("+Z", hole.EntryFace.Axis);
+ Assert.Equal((0d, 0d), (hole.Center.U, hole.Center.V));
+ Assert.Equal(FirmamentV2SemanticHoleEndKind.ThroughAll, hole.EndCondition.Kind);
+ Assert.Equal("Chamfer", edge.Kind);
+ }
+
+ [Fact]
+ public void CanonicalCombinedPart_ExportsThroughTheCombinedSemanticRoute()
+ {
+ var output = Path.Combine(Path.GetTempPath(), $"aetheris-canonical-{Guid.NewGuid():N}.step");
+ try
+ {
+ var build = FirmamentBuildAndExport.Run(Fixture("box-hole-chamfer.firmament"), output);
+ Assert.True(build.IsSuccess, string.Join(Environment.NewLine, build.Diagnostics.Select(d => d.Message)));
+ Assert.Equal("CombinedHoleEdgeFinish", build.Value.Export.Combined!.Route);
+ Assert.True(File.Exists(output));
+ }
+ finally
+ {
+ if (File.Exists(output)) File.Delete(output);
+ }
+ }
+
+ [Fact]
+ public void CanonicalPoint2_RejectsTheLegacyBracketLiteralWithASpecificDiagnostic()
+ {
+ var source = File.ReadAllText(Fixture("box-through-hole.firmament")).Replace("Point2(0mm, 0mm)", "[0mm, 0mm]", StringComparison.Ordinal);
+ var parsed = FirmamentV2Parser.Parse(source);
+
+ Assert.False(parsed.IsSuccess);
+ Assert.Contains(FirmamentV2Parser.CanonicalPoint2Invalid, parsed.Diagnostics);
+ }
+
+ private static string Fixture(string name) => Path.GetFullPath(Path.Combine(AppContext.BaseDirectory, "../../../../fixtures/FirmamentV2/Canonical/valid", name));
+}
diff --git a/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Parser.cs b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Parser.cs
index 3d83a015..d93b9415 100644
--- a/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Parser.cs
+++ b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Parser.cs
@@ -61,6 +61,11 @@ public static class FirmamentV2Parser
public const string WallThicknessMustBePositive = "firmament-v2-wall-thickness-must-be-positive";
public const string UnsupportedOpening = "firmament-v2-unsupported-opening";
public const string MultipleOpeningsNotSupported = "firmament-v2-multiple-openings-not-supported";
+ public const string CanonicalDocumentMalformed = "firmament-v2-canonical-document-malformed";
+ public const string CanonicalUnitsInvalid = "firmament-v2-canonical-units-invalid";
+ public const string CanonicalPrimitiveMalformed = "firmament-v2-canonical-primitive-malformed";
+ public const string CanonicalPoint2Invalid = "firmament-v2-canonical-point2-invalid";
+ public const string CanonicalModifyMalformed = "firmament-v2-canonical-modify-malformed";
public const string ConceptUnknownFamily = "firmament-v2-concept-unknown-family";
public const string ConceptUnknownConcept = "firmament-v2-concept-unknown-concept";
@@ -247,6 +252,11 @@ public static class FirmamentV2Parser
private static readonly Regex PathRegex = new("\\bpath\\s*:\\s*\"(?<path>[^\"]+)\"", RegexOptions.CultureInvariant);
private static readonly Regex FillRegionHeaderRegex = new(@"\bregion\s+(?<name>[A-Za-z_][A-Za-z0-9_]*)\s*\{", RegexOptions.CultureInvariant);
private static readonly Regex FillHeaderRegex = new(@"\bfill\s+(?<name>[A-Za-z_][A-Za-z0-9_]*)\s*\{", RegexOptions.CultureInvariant);
+ private static readonly Regex CanonicalModelRegex = new(@"^\s*Model\s+(?<name>[A-Za-z_][A-Za-z0-9_]*)\s*\{", RegexOptions.CultureInvariant);
+ private static readonly Regex CanonicalPrimitiveHeaderRegex = new(@"\b(?<type>Box|Cylinder|RoundedBox|Frustum)\s+(?<name>[A-Za-z_][A-Za-z0-9_]*)\s*\{", RegexOptions.CultureInvariant);
+ private static readonly Regex CanonicalModifyHeaderRegex = new(@"\bModify\s+(?<target>[A-Za-z_][A-Za-z0-9_]*)\s*\{", RegexOptions.CultureInvariant);
+ private static readonly Regex CanonicalHoleHeaderRegex = new(@"\bHole\s*<\s*(?<variant>Shaft|Counterbore|Countersink)\s*>\s+(?<name>[A-Za-z_][A-Za-z0-9_]*)\s*\{", RegexOptions.CultureInvariant);
+ private static readonly Regex CanonicalEdgeHeaderRegex = new(@"\bEdgeFinish\s+(?<name>[A-Za-z_][A-Za-z0-9_]*)\s*\{", RegexOptions.CultureInvariant);
public static FirmamentV2ParseResult Parse(string sourceText) => Parse(sourceText, null, null);
@@ -274,6 +284,12 @@ public static class FirmamentV2Parser
source = templateExpansion.Source;
v2AdmissionCandidate |= IsV2AdmissionCandidate(source);
+ // Canonical V2 is parsed as one document, before compatibility adapters. The
+ // adapters below remain only for old fixtures and no longer define the language
+ // an author must select for ordinary mechanical work.
+ if (CanonicalModelRegex.IsMatch(source))
+ return Recognized(ParseCanonicalDocument(source, diagnostics));
+
if (Regex.IsMatch(source, @"\b(?:RoundedBox|Frustum|Box)\s*<\s*[A-Za-z_][A-Za-z0-9_]*\s*>\s+[A-Za-z_]", RegexOptions.CultureInvariant))
return Recognized(ParsePrimitiveConstructionPolicyDocument(source, diagnostics));
@@ -791,6 +807,143 @@ public static class FirmamentV2Parser
return new(name, "Box", new FirmamentV2BoxRecord(values, []), baseName, new Dictionary<string, IReadOnlyList<double>>(StringComparer.Ordinal) { ["size"] = values });
}
+ /// <summary>
+ /// The author-facing V2 grammar. It deliberately builds the same normalized
+ /// document as all compatibility forms: materializer selection sees primitive
+ /// and feature semantics, never the spelling that introduced them.
+ /// </summary>
+ private static FirmamentV2ParseResult ParseCanonicalDocument(string source, List<string> diagnostics)
+ {
+ var model = CanonicalModelRegex.Match(source);
+ var rootOpen = model.Success ? source.IndexOf('{', model.Index) : -1;
+ var rootClose = rootOpen >= 0 ? FindMatchingBrace(source, rootOpen) : -1;
+ if (!model.Success || rootClose < 0 || !string.IsNullOrWhiteSpace(source[(rootClose + 1)..]))
+ return CanonicalFailure(diagnostics, CanonicalDocumentMalformed);
+
+ var body = source[(rootOpen + 1)..rootClose];
+ var units = Regex.Match(body, @"\bUnits\s*:\s*(?<value>[A-Za-z_][A-Za-z0-9_]*)\b", RegexOptions.CultureInvariant);
+ if (!units.Success || units.Groups["value"].Value != "mm")
+ return CanonicalFailure(diagnostics, CanonicalUnitsInvalid);
+
+ var solids = new List<FirmamentV2SolidBinding>();
+ var byName = new Dictionary<string, FirmamentV2SolidBinding>(StringComparer.Ordinal);
+ foreach (Match primitive in CanonicalPrimitiveHeaderRegex.Matches(body))
+ {
+ var open = body.IndexOf('{', primitive.Index);
+ var close = FindMatchingBrace(body, open);
+ if (close < 0) return CanonicalFailure(diagnostics, CanonicalPrimitiveMalformed);
+ var name = primitive.Groups["name"].Value;
+ if (!byName.TryAdd(name, null!)) return CanonicalFailure(diagnostics, DuplicateName);
+ var primitiveBody = body[(open + 1)..close];
+ var record = ParseCanonicalPrimitive(primitive.Groups["type"].Value, primitiveBody, diagnostics);
+ if (record is null) return CanonicalFailure(diagnostics, CanonicalPrimitiveMalformed);
+ var solid = new FirmamentV2SolidBinding(name, primitive.Groups["type"].Value, record);
+ byName[name] = solid;
+ solids.Add(solid);
+ }
+ if (solids.Count == 0) return CanonicalFailure(diagnostics, MissingSolid);
+
+ var modifies = new List<FirmamentV2ModifyBlock>();
+ foreach (Match modify in CanonicalModifyHeaderRegex.Matches(body))
+ {
+ var target = modify.Groups["target"].Value;
+ if (!byName.TryGetValue(target, out var solid)) return CanonicalFailure(diagnostics, ModifyTargetUnresolved);
+ if (solid.Box is null) return CanonicalFailure(diagnostics, ModifyTargetNotSolid);
+ var open = body.IndexOf('{', modify.Index);
+ var close = FindMatchingBrace(body, open);
+ if (close < 0) return CanonicalFailure(diagnostics, CanonicalModifyMalformed);
+ var modifyBody = body[(open + 1)..close];
+ var holes = ParseCanonicalHoles(modifyBody, solid, rootOpen + 1 + open + 1, diagnostics);
+ var finishes = ParseCanonicalEdgeFinishes(modifyBody, rootOpen + 1 + open + 1, diagnostics);
+ if (diagnostics.Any(IsFatalDiagnosticCode) || diagnostics.Contains(CanonicalPoint2Invalid) || diagnostics.Contains(CanonicalModifyMalformed))
+ return CanonicalFailure(diagnostics, CanonicalModifyMalformed);
+ // Empty Modify blocks are valid; feature admission belongs to the selected
+ // production route, not to a phase parser's minimum-count rule.
+ modifies.Add(new FirmamentV2ModifyBlock(target, [], holes, finishes));
+ }
+
+ diagnostics.Add("firmament-v2-unified-canonical-parsed");
+ diagnostics.Add("firmament-v2-parse-succeeded");
+ diagnostics.Sort(StringComparer.Ordinal);
+ return FirmamentV2ParseResult.Success(new FirmamentV2Document(model.Groups["name"].Value, "mm", solids, modifies), diagnostics.Distinct(StringComparer.Ordinal).ToArray());
+ }
+
+ private static FirmamentV2PrimitiveRecord? ParseCanonicalPrimitive(string type, string body, List<string> diagnostics)
+ {
+ double Number(string field)
+ {
+ var match = Regex.Match(body, $@"\b{field}\s*:\s*(?<value>[-+0-9.eE]+)mm\b", RegexOptions.CultureInvariant);
+ return match.Success && double.TryParse(match.Groups["value"].Value, NumberStyles.Float, CultureInfo.InvariantCulture, out var value) && double.IsFinite(value) && value > 0d ? value : double.NaN;
+ }
+ IReadOnlyList<double>? Size()
+ {
+ var match = Regex.Match(body, @"\bSize\s*:\s*\[(?<values>[^\]]+)\]", RegexOptions.CultureInvariant);
+ if (!match.Success) return null;
+ var values = match.Groups["values"].Value.Split(',', StringSplitOptions.TrimEntries);
+ var parsed = values.Select(ParsePhase3Length).ToArray();
+ return parsed.Length == 3 && parsed.All(v => double.IsFinite(v) && v > 0d) ? parsed : null;
+ }
+ return type switch
+ {
+ "Box" when Size() is { } size => new FirmamentV2BoxRecord(size, []),
+ "Cylinder" when Number("Radius") is var radius && Number("Height") is var height && double.IsFinite(radius) && double.IsFinite(height) => new FirmamentV2CylinderRecord(radius, height),
+ "RoundedBox" when Size() is { } roundedSize && Number("CornerRadius") is var corner && double.IsFinite(corner) && corner < double.Min(roundedSize[0], roundedSize[1]) / 2d => new FirmamentV2RoundedBoxRecord(roundedSize, corner),
+ "Frustum" when Number("BottomRadius") is var bottom && Number("TopRadius") is var top && Number("Height") is var frustumHeight && double.IsFinite(bottom) && double.IsFinite(top) && double.IsFinite(frustumHeight) && double.Abs(bottom - top) > 1e-12d => new FirmamentV2FrustumRecord(bottom, top, frustumHeight),
+ _ => null
+ };
+ }
+
+ private static IReadOnlyList<FirmamentV2SemanticHoleDecl> ParseCanonicalHoles(string body, FirmamentV2SolidBinding solid, int bodyOffset, List<string> diagnostics)
+ {
+ var holes = new List<FirmamentV2SemanticHoleDecl>();
+ foreach (Match hole in CanonicalHoleHeaderRegex.Matches(body))
+ {
+ var open = body.IndexOf('{', hole.Index); var close = FindMatchingBrace(body, open);
+ if (close < 0) { diagnostics.Add(CanonicalModifyMalformed); continue; }
+ var holeBody = body[(open + 1)..close];
+ var on = Regex.Match(holeBody, @"\bOn\s*:\s*(?<face>[+-][XYZ])\b", RegexOptions.CultureInvariant);
+ var point = Regex.Match(holeBody, @"\bCenter\s*:\s*Point2\(\s*(?<u>[-+0-9.eE]+)mm\s*,\s*(?<v>[-+0-9.eE]+)mm\s*\)", RegexOptions.CultureInvariant);
+ var diameter = Regex.Match(holeBody, @"\bDiameter\s*:\s*(?<value>[-+0-9.eE]+)mm\b", RegexOptions.CultureInvariant);
+ var end = Regex.Match(holeBody, @"\bEnd\s*:\s*(?<kind>ThroughAll|Blind)\b(?:\s+(?<depth>[-+0-9.eE]+)mm)?", RegexOptions.CultureInvariant);
+ if (!on.Success || !diameter.Success || !end.Success) { diagnostics.Add(CanonicalModifyMalformed); continue; }
+ if (!point.Success || !double.TryParse(point.Groups["u"].Value, NumberStyles.Float, CultureInfo.InvariantCulture, out var u) || !double.TryParse(point.Groups["v"].Value, NumberStyles.Float, CultureInfo.InvariantCulture, out var v) || !double.IsFinite(u) || !double.IsFinite(v)) { diagnostics.Add(CanonicalPoint2Invalid); continue; }
+ if (!double.TryParse(diameter.Groups["value"].Value, NumberStyles.Float, CultureInfo.InvariantCulture, out var shaft) || !double.IsFinite(shaft) || shaft <= 0d) { diagnostics.Add(HoleDiameterInvalid); continue; }
+ if (!Enum.TryParse<FirmamentV2SemanticHoleVariant>(hole.Groups["variant"].Value, out var variant)) { diagnostics.Add(HoleVariantUnknown); continue; }
+ FirmamentV2SemanticHoleEnd endValue;
+ if (end.Groups["kind"].Value == "ThroughAll") endValue = new(FirmamentV2SemanticHoleEndKind.ThroughAll);
+ else if (double.TryParse(end.Groups["depth"].Value, NumberStyles.Float, CultureInfo.InvariantCulture, out var depth) && depth > 0d && double.IsFinite(depth)) endValue = new(FirmamentV2SemanticHoleEndKind.Depth, depth);
+ else { diagnostics.Add(HoleBlindDepthInvalid); continue; }
+ var face = FirmamentV2FaceTarget.Direct(on.Groups["face"].Value);
+ holes.Add(new(hole.Groups["name"].Value, variant, face, new FirmamentV2FaceLocalPoint2D(u, v, FirmamentV2FaceLocalPoint2D.ConventionFor(face.Axis)), shaft, endValue, SourceSpan: new FirmamentV2SourceSpan(bodyOffset + hole.Index, close - hole.Index + 1)));
+ }
+ return holes;
+ }
+
+ private static IReadOnlyList<FirmamentV2EdgeFinishDecl> ParseCanonicalEdgeFinishes(string body, int bodyOffset, List<string> diagnostics)
+ {
+ var finishes = new List<FirmamentV2EdgeFinishDecl>();
+ foreach (Match edge in CanonicalEdgeHeaderRegex.Matches(body))
+ {
+ var open = body.IndexOf('{', edge.Index); var close = FindMatchingBrace(body, open);
+ if (close < 0) { diagnostics.Add(CanonicalModifyMalformed); continue; }
+ var edgeBody = body[(open + 1)..close];
+ var face = Regex.Match(edgeBody, @"\bFace\s*:\s*(?<value>[+-][XYZ])\b", RegexOptions.CultureInvariant);
+ var target = Regex.Match(edgeBody, @"\bTarget\s*:\s*(?<value>[A-Za-z_][A-Za-z0-9_]*)\b", RegexOptions.CultureInvariant);
+ var kind = Regex.Match(edgeBody, @"\bKind\s*:\s*(?<value>[A-Za-z_][A-Za-z0-9_]*)\b", RegexOptions.CultureInvariant);
+ var distance = Regex.Match(edgeBody, @"\b(?:Distance|Radius)\s*:\s*(?<value>[-+0-9.eE]+)mm\b", RegexOptions.CultureInvariant);
+ if (!face.Success || !target.Success || !kind.Success || !distance.Success || !double.TryParse(distance.Groups["value"].Value, NumberStyles.Float, CultureInfo.InvariantCulture, out var value) || !double.IsFinite(value) || value <= 0d) { diagnostics.Add(CanonicalModifyMalformed); continue; }
+ finishes.Add(new FirmamentV2EdgeFinishDecl(edge.Groups["name"].Value, face.Groups["value"].Value, target.Groups["value"].Value, kind.Groups["value"].Value, value, new FirmamentV2SourceSpan(bodyOffset + edge.Index, close - edge.Index + 1)));
+ }
+ return finishes;
+ }
+
+ private static FirmamentV2ParseResult CanonicalFailure(List<string> diagnostics, string diagnostic)
+ {
+ diagnostics.Add(diagnostic);
+ diagnostics.Add("firmament-v2-parse-failed");
+ return FirmamentV2ParseResult.Failure(diagnostics.Distinct(StringComparer.Ordinal).Order().ToArray());
+ }
+
private static FirmamentV2ParseResult ParsePhase3ModelingDocument(string source, List<string> diagnostics)
{
var model = Regex.Match(source, @"^\s*Model\s+(?<name>[A-Za-z_][A-Za-z0-9_]*)\s+(?<units>[A-Za-z_][A-Za-z0-9_]*)\b", RegexOptions.CultureInvariant);
diff --git a/docs/firmament/v2-canonical-authoring.md b/docs/firmament/v2-canonical-authoring.md
new file mode 100644
index 00000000..cecbb8ca
--- /dev/null
+++ b/docs/firmament/v2-canonical-authoring.md
@@ -0,0 +1,64 @@
+# Firmament V2 canonical authoring
+
+Firmament V2 is one language. Backend specialization is not an author-facing dialect. Parse the document first; route its semantics after parsing.
+
+Use this form for ordinary parts:
+
+```firmament
+Model Bracket {
+ Units: mm
+
+ Box Base {
+ Size: [80mm, 50mm, 25mm]
+ }
+
+ Modify Base {
+ Hole<Shaft> Mount {
+ On: +Z
+ Center: Point2(0mm, 0mm)
+ Diameter: 8mm
+ End: ThroughAll
+ }
+
+ EdgeFinish TopBreak {
+ Face: +Z
+ Target: Boundary
+ Kind: Chamfer
+ Distance: 1.5mm
+ }
+ }
+}
+```
+
+## Rules
+
+- Keywords and declaration kinds use PascalCase: `Model`, `Units`, `Box`, `Modify`, `Hole`, and `EdgeFinish`.
+- Every canonical document has `Units: mm`. All canonical dimensions carry `mm`; angles carry `deg`.
+- `Size` is the one context-directed array literal: `[xmm, ymm, zmm]`.
+- Points are typed: `Point2(xmm, ymm)` and `Point3(xmm, ymm, zmm)`. Vectors are `Vector2(x, y)` and `Vector3(x, y, z)`. Bracket points are legacy-only and rejected by the canonical grammar.
+- Bare `Box`, `Cylinder`, `RoundedBox`, and `Frustum` declarations require no `Modify` block.
+- A `Modify` block may be empty, or contain any currently admitted feature family. A backend route, not parsing, reports unsupported feature combinations.
+- A shaft hole uses `On`, `Center`, `Diameter`, and `End`. `End: ThroughAll` is the simple through-hole; `End: Blind <depth>mm` is the canonical blind spelling.
+- An edge finish uses `Face`, `Target`, `Kind`, and either `Distance` (chamfer) or `Radius` (fillet).
+
+The currently proven low-ceremony production shape is one Box, one top-face ThroughAll shaft Hole, and one disjoint `+Z Boundary Chamfer`. It routes to `CombinedHoleEdgeFinish`, then authoritative STEP export and STEP reimport verification.
+
+Concept-first authoring remains available for construction planes, profiles, composition, templates, semantic selections, and spatial contracts. It is an escalation for spatial complexity, not a prerequisite for a primitive or ordinary host-relative Hole.
+
+## Canonical examples
+
+- `fixtures/FirmamentV2/Canonical/valid/bare-box.firmament`
+- `fixtures/FirmamentV2/Canonical/valid/bare-cylinder.firmament`
+- `fixtures/FirmamentV2/Canonical/valid/bare-rounded-box.firmament`
+- `fixtures/FirmamentV2/Canonical/valid/bare-frustum.firmament`
+- `fixtures/FirmamentV2/Canonical/valid/box-through-hole.firmament`
+- `fixtures/FirmamentV2/Canonical/valid/box-hole-chamfer.firmament`
+
+## Common diagnostics
+
+- `firmament-v2-canonical-units-invalid`: use `Units: mm`.
+- `firmament-v2-canonical-primitive-malformed`: a primitive is missing a required canonical field or has an invalid dimension.
+- `firmament-v2-canonical-point2-invalid`: use `Point2(xmm, ymm)`, not `[x, y]`.
+- `firmament-v2-canonical-modify-malformed`: a Hole or EdgeFinish declaration is missing a required canonical field.
+
+Legacy lowercase, phase-style, and Concept/Struct sources remain compatibility inputs during migration. New authoring should use the form above.
diff --git a/docs/firmament/v2-unified-grammar-x1.md b/docs/firmament/v2-unified-grammar-x1.md
new file mode 100644
index 00000000..723e86b8
--- /dev/null
+++ b/docs/firmament/v2-unified-grammar-x1.md
@@ -0,0 +1,34 @@
+# FIRMAMENT-V2-UNIFIED-GRAMMAR-X1 reconciliation log
+
+## Decision
+
+Firmament V2 has a canonical `Model { Units: mm ... }` surface for ordinary mechanical parts. Its parser produces the existing `FirmamentV2Document` normalized AST: solids, Modify blocks, semantic holes, edge finishes, and optional Concept IR. Export routing consumes that normalized semantic inventory; it does not receive a parser-lane identifier.
+
+| Concern | Previous forms | Canonical form | Compatibility |
+| --- | --- | --- | --- |
+| Root and units | `Model X mm`, `model X { units mm }` | `Model X { Units: mm }` | Existing forms remain compatibility routes. |
+| Primitive | `Box Base`, `solid Base : Box` | `Box Base { Size: [...] }` | Lowercase record bindings remain compatibility inputs. |
+| Point2 | `[x,y]`, `[xmm,ymm]`, `Point2(...)` | `Point2(xmm, ymm)` | Canonical rejects bracket points with a specific diagnostic. |
+| Hole | `hole<Shaft>`, face selectors, assorted ends | `Hole<Shaft> { On, Center, Diameter, End }` | Existing semantic-hole and construction-plane forms remain supported through their adapters. |
+| Edge finish | phase-only `EdgeFinish` | `EdgeFinish { Face, Target, Kind, Distance/Radius }` inside any `Modify` | Existing phase source remains a compatibility route. |
+
+## Parser inventory at the start of X1
+
+| Historical trigger | Resulting parser/AST | Capability boundary |
+| --- | --- | --- |
+| lowercase `model` | `FirmamentV2Document` direct parser | records, regions, semantic holes; previously no canonical edge vocabulary |
+| leading `Model X mm` | `ParsePhase3ModelingDocument` | one primitive, required Modify, one to three EdgeFinishes |
+| `Concept`, `Concept Struct`, or `Struct` | `ConceptIrResolver` then `FirmamentV2Document` | construction planes, profiles, compose, semantic geometry |
+| `RoundedBox` / construction-policy token shape | bounded special parser | one historical bounded primitive shape |
+
+The canonical root is recognized before those compatibility adapters. It parses the whole balanced document and builds a normal `FirmamentV2Document`; no edge/hole backend is chosen while source spelling is being recognized. `NotRecognized`, `RecognizedInvalid`, and `RecognizedValid` are retained so only true non-V2 inputs can fall back to V1.
+
+## Proven route
+
+`box-hole-chamfer.firmament` is 8 lines including its root and closing braces (compared with the 22-line Concept/Struct reconstruction that motivated X1). It parses to one Box, one `Modify`, one semantic shaft ThroughAll hole, and one edge finish. The existing semantic route selector chooses `CombinedHoleEdgeFinish`; its authoritative plan is exported to STEP and reimport-verified by the focused regression test.
+
+The former Concept/Struct solution is still appropriate when placement requires construction-plane or composed-host semantics. The ordinary part does not need that ceremony.
+
+## Deliberate limits and next work
+
+This change establishes the canonical ordinary grammar and its normalized-AST boundary. The legacy Concept IR and profile/composition syntaxes still have dedicated compatibility parsers, so a complete single lexical grammar for every advanced declaration remains the next release blocker. Slot and semantic-selection declarations also need first-class canonical productions before the compatibility lanes can be retired. This is intentionally not hidden: today, the canonical parser gives specific diagnostics rather than silently switching an author into a different dialect.
diff --git a/fixtures/FirmamentV2/Canonical/valid/bare-box.firmament b/fixtures/FirmamentV2/Canonical/valid/bare-box.firmament
new file mode 100644
index 00000000..5b9c6b20
--- /dev/null
+++ b/fixtures/FirmamentV2/Canonical/valid/bare-box.firmament
@@ -0,0 +1,7 @@
+Model BareBox {
+ Units: mm
+
+ Box Base {
+ Size: [80mm, 50mm, 25mm]
+ }
+}
diff --git a/fixtures/FirmamentV2/Canonical/valid/bare-cylinder.firmament b/fixtures/FirmamentV2/Canonical/valid/bare-cylinder.firmament
new file mode 100644
index 00000000..acbfe105
--- /dev/null
+++ b/fixtures/FirmamentV2/Canonical/valid/bare-cylinder.firmament
@@ -0,0 +1,8 @@
+Model BareCylinder {
+ Units: mm
+
+ Cylinder Base {
+ Radius: 12mm
+ Height: 30mm
+ }
+}
diff --git a/fixtures/FirmamentV2/Canonical/valid/bare-frustum.firmament b/fixtures/FirmamentV2/Canonical/valid/bare-frustum.firmament
new file mode 100644
index 00000000..e91faac9
--- /dev/null
+++ b/fixtures/FirmamentV2/Canonical/valid/bare-frustum.firmament
@@ -0,0 +1,9 @@
+Model TaperedBoss {
+ Units: mm
+
+ Frustum Base {
+ BottomRadius: 20mm
+ TopRadius: 10mm
+ Height: 30mm
+ }
+}
diff --git a/fixtures/FirmamentV2/Canonical/valid/bare-rounded-box.firmament b/fixtures/FirmamentV2/Canonical/valid/bare-rounded-box.firmament
new file mode 100644
index 00000000..e5806507
--- /dev/null
+++ b/fixtures/FirmamentV2/Canonical/valid/bare-rounded-box.firmament
@@ -0,0 +1,8 @@
+Model RoundedEnclosure {
+ Units: mm
+
+ RoundedBox Base {
+ Size: [80mm, 50mm, 25mm]
+ CornerRadius: 6mm
+ }
+}
diff --git a/fixtures/FirmamentV2/Canonical/valid/box-hole-chamfer.firmament b/fixtures/FirmamentV2/Canonical/valid/box-hole-chamfer.firmament
new file mode 100644
index 00000000..81c6247e
--- /dev/null
+++ b/fixtures/FirmamentV2/Canonical/valid/box-hole-chamfer.firmament
@@ -0,0 +1,8 @@
+Model HoleAndChamfer {
+ Units: mm
+ Box Base { Size: [80mm, 50mm, 25mm] }
+ Modify Base {
+ Hole<Shaft> Mount { On: +Z Center: Point2(0mm, 0mm) Diameter: 8mm End: ThroughAll }
+ EdgeFinish TopBreak { Face: +Z Target: Boundary Kind: Chamfer Distance: 1.5mm }
+ }
+}
diff --git a/fixtures/FirmamentV2/Canonical/valid/box-through-hole.firmament b/fixtures/FirmamentV2/Canonical/valid/box-through-hole.firmament
new file mode 100644
index 00000000..b3973bde
--- /dev/null
+++ b/fixtures/FirmamentV2/Canonical/valid/box-through-hole.firmament
@@ -0,0 +1,16 @@
+Model ThroughHole {
+ Units: mm
+
+ Box Base {
+ Size: [80mm, 50mm, 25mm]
+ }
+
+ Modify Base {
+ Hole<Shaft> Mount {
+ On: +Z
+ Center: Point2(0mm, 0mm)
+ Diameter: 8mm
+ End: ThroughAll
+ }
+ }
+}