Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel
Support canonical STEP traceability and semantic declarations
Yuechen Li07552352b240
diff --git a/Aetheris.CLI/CliRunner.cs b/Aetheris.CLI/CliRunner.csindex 8685e1e2..a0268311 100644--- a/Aetheris.CLI/CliRunner.cs+++ b/Aetheris.CLI/CliRunner.cs@@ -2653,7 +2653,7 @@ public static class CliRunnerif (analysis.Face is not null){- stdout.WriteLine($"Face {analysis.Face.FaceId}: type={analysis.Face.SurfaceType ?? "n/a"}, status={analysis.Face.SurfaceStatus}, bbox={FormatBox(analysis.Face.BoundingBox)}, point={FormatPoint(analysis.Face.RepresentativePoint)}, anchor={FormatPoint(analysis.Face.AnchorPoint)}, apex={FormatPoint(analysis.Face.Apex)}, normal={FormatVector(analysis.Face.PlanarNormal)}, axis={FormatVector(analysis.Face.Axis)}, radius={FormatDouble(analysis.Face.Radius)}, placementRadius={FormatDouble(analysis.Face.PlacementRadius)}, majorRadius={FormatDouble(analysis.Face.MajorRadius)}, minorRadius={FormatDouble(analysis.Face.MinorRadius)}, semiAngleRadians={FormatDouble(analysis.Face.SemiAngleRadians)}, edges=[{string.Join(",", analysis.Face.AdjacentEdgeIds)}]");+ stdout.WriteLine($"Face {analysis.Face.FaceId}: stepEntity={analysis.Face.StepEntity ?? "n/a"}, type={analysis.Face.SurfaceType ?? "n/a"}, status={analysis.Face.SurfaceStatus}, bbox={FormatBox(analysis.Face.BoundingBox)}, point={FormatPoint(analysis.Face.RepresentativePoint)}, anchor={FormatPoint(analysis.Face.AnchorPoint)}, apex={FormatPoint(analysis.Face.Apex)}, normal={FormatVector(analysis.Face.PlanarNormal)}, axis={FormatVector(analysis.Face.Axis)}, radius={FormatDouble(analysis.Face.Radius)}, placementRadius={FormatDouble(analysis.Face.PlacementRadius)}, majorRadius={FormatDouble(analysis.Face.MajorRadius)}, minorRadius={FormatDouble(analysis.Face.MinorRadius)}, semiAngleRadians={FormatDouble(analysis.Face.SemiAngleRadians)}, edges=[{string.Join(",", analysis.Face.AdjacentEdgeIds)}]");}if (analysis.Edge is not null)diff --git a/Aetheris.CLI/StepAnalysisModels.cs b/Aetheris.CLI/StepAnalysisModels.csindex 5a07d303..cbce2105 100644--- a/Aetheris.CLI/StepAnalysisModels.cs+++ b/Aetheris.CLI/StepAnalysisModels.cs@@ -40,7 +40,8 @@ public sealed record FaceDetail(double? MajorRadius,double? MinorRadius,double? SemiAngleRadians,- IReadOnlyList<int> AdjacentEdgeIds);+ IReadOnlyList<int> AdjacentEdgeIds,+ [property: JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] string? StepEntity = null);public sealed record EdgeDetail(int EdgeId,diff --git a/Aetheris.CLI/StepAnalyzer.cs b/Aetheris.CLI/StepAnalyzer.csindex f4c000d7..93f8a999 100644--- a/Aetheris.CLI/StepAnalyzer.cs+++ b/Aetheris.CLI/StepAnalyzer.cs@@ -9,6 +9,7 @@ using Aetheris.Kernel.Core.Numerics;using Aetheris.Kernel.Core.Step242;using Aetheris.Kernel.Core.Topology;using Aetheris.Kernel.Firmament.Materializer;+using System.Text.RegularExpressions;namespace Aetheris.CLI;@@ -38,7 +39,16 @@ public sealed record VolumeAnalysisResult(public static AnalyzeResult Analyze(string stepPath, int? faceId = null, int? edgeId = null, int? vertexId = null){var (fullPath, body) = ImportStepBody(stepPath);- return AnalyzeImportedBody(body, fullPath, faceId, edgeId, vertexId);+ var analysis = AnalyzeImportedBody(body, fullPath, faceId, edgeId, vertexId);+ if (analysis.Face is null) return analysis;++ // Imported B-rep IDs are the public sequential vocabulary. Preserve the+ // originating ADVANCED_FACE alongside it for traceability, never as a+ // requirement for normal authoring.+ var entities = Regex.Matches(File.ReadAllText(fullPath), @"(?m)^\s*(#[0-9]+)\s*=\s*ADVANCED_FACE\s*\(", RegexOptions.CultureInvariant)+ .Cast<Match>().Select(match => match.Groups[1].Value).ToArray();+ var entity = analysis.Face.FaceId > 0 && analysis.Face.FaceId <= entities.Length ? entities[analysis.Face.FaceId - 1] : null;+ return analysis with { Face = analysis.Face with { StepEntity = entity } };}public static AnalyzeResult AnalyzeImportedBody(BrepBody body, string stepPath, int? faceId = null, int? edgeId = null, int? vertexId = null)diff --git a/Aetheris.Kernel.Firmament.Tests/FirmamentV2CanonicalSafetyAndLabelingTests.cs b/Aetheris.Kernel.Firmament.Tests/FirmamentV2CanonicalSafetyAndLabelingTests.csnew file mode 100644index 00000000..bcf79fcd--- /dev/null+++ b/Aetheris.Kernel.Firmament.Tests/FirmamentV2CanonicalSafetyAndLabelingTests.cs@@ -0,0 +1,66 @@+using Aetheris.Kernel.Firmament.FirmamentV2;++namespace Aetheris.Kernel.Firmament.Tests;++public sealed class FirmamentV2CanonicalSafetyAndLabelingTests+{+ [Theory]+ [InlineData("counterbore-hole.firmament", FirmamentV2SemanticHoleVariant.Counterbore)]+ [InlineData("countersink-hole.firmament", FirmamentV2SemanticHoleVariant.Countersink)]+ public void CanonicalHoleFamilies_BindCompleteVariantContracts(string fixture, FirmamentV2SemanticHoleVariant expected)+ {+ var parse = FirmamentV2Parser.Parse(File.ReadAllText(Canonical(fixture)));++ Assert.True(parse.IsSuccess, string.Join(Environment.NewLine, parse.Diagnostics));+ var hole = Assert.Single(Assert.Single(parse.Document!.ModifyBlocks!).SemanticHoles);+ Assert.Equal(expected, hole.Variant);+ Assert.True(expected == FirmamentV2SemanticHoleVariant.Counterbore ? hole.CounterboreDiameter is > 0d && hole.CounterboreDepth is > 0d : hole.CountersinkDiameter is > 0d && hole.CountersinkAngleDegrees is > 0d);+ }++ [Theory]+ [InlineData("Hole<Blind> Pilot { On: +Z Center: Point2(0mm, 0mm) Diameter: 5mm End: ThroughAll }")]+ [InlineData("Hole<Unknown> Pilot { On: +Z Center: Point2(0mm, 0mm) Diameter: 5mm End: ThroughAll }")]+ public void CanonicalUnknownHoleVariant_IsNeverDiscarded(string declaration)+ {+ var parse = FirmamentV2Parser.Parse($"Model Bad {{ Units: mm Box Base {{ Size: [10mm, 10mm, 10mm] }} Modify Base {{ {declaration} }} }}");++ Assert.False(parse.IsSuccess);+ Assert.Contains(FirmamentV2Parser.HoleVariantUnknown, parse.Diagnostics);+ }++ [Theory]+ [InlineData("CounterboreDiameter: 10mm", FirmamentV2Parser.HoleCounterboreInvalid)]+ [InlineData("CounterboreDepth: 3mm", FirmamentV2Parser.HoleCounterboreInvalid)]+ public void CanonicalCounterbore_MissingVariantFields_AreDiagnostics(string fields, string diagnostic)+ {+ var source = $"Model Bad {{ Units: mm Box Base {{ Size: [10mm, 10mm, 10mm] }} Modify Base {{ Hole<Counterbore> Pilot {{ On: +Z Center: Point2(0mm, 0mm) Diameter: 5mm {fields} End: ThroughAll }} }} }}";+ var parse = FirmamentV2Parser.Parse(source);+ Assert.False(parse.IsSuccess);+ Assert.Contains(diagnostic, parse.Diagnostics);+ }++ [Fact]+ public void CanonicalInlineStepRecognitionAndReplacement_UseAnalysisFaceIds()+ {+ var fixture = Canonical("inline-step-recognize-replace.firmament");+ var parse = FirmamentV2Parser.Parse(File.ReadAllText(fixture), Path.GetDirectoryName(fixture));++ Assert.True(parse.IsSuccess, string.Join(Environment.NewLine, parse.Diagnostics));+ var region = Assert.Single(parse.Document!.RecognizedRegions!);+ Assert.Equal("#191", Assert.Single(region.FaceRefs));+ var replacement = Assert.Single(parse.Document.Replacements!);+ Assert.Equal("Source.face(\"#191\")", replacement.PlacementTarget);+ }++ [Theory]+ [InlineData("Recognise Source { }")]+ [InlineData("InlineStepp Source { Path: \"source.step\" }")]+ public void CanonicalDeclarationTypos_AreNeverSilentlyIgnored(string declaration)+ {+ var parse = FirmamentV2Parser.Parse($"Model Bad {{ Units: mm Box Base {{ Size: [10mm, 10mm, 10mm] }} {declaration} }}");+ Assert.False(parse.IsSuccess);+ Assert.Contains(FirmamentV2Parser.CanonicalDeclarationUnrecognized, parse.Diagnostics);+ }++ private static string Canonical(string name) => Path.GetFullPath(Path.Combine(AppContext.BaseDirectory, "../../../../fixtures/FirmamentV2/Canonical/valid", name));+}diff --git a/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Ast.cs b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Ast.csindex f68c75e6..703380b9 100644--- a/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Ast.cs+++ b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Ast.cs@@ -75,6 +75,23 @@ public sealed record FirmamentV2InlineStepRecord(string SourcePath, string Normapublic sealed record ImportedStepTopologyMap(IReadOnlyDictionary<string, string> FaceEntityToFaceId, IReadOnlyDictionary<string, string> FaceIdToFaceEntity){public bool TryResolveFaceEntity(string entityRef, out string faceId) => FaceEntityToFaceId.TryGetValue(entityRef, out faceId!);+ public bool TryResolveSequentialFaceId(int faceId, out string entityRef) => FaceIdToFaceEntity.TryGetValue($"face-{faceId}", out entityRef!);+ public bool TryResolveFaceReference(string reference, out string entityRef)+ {+ if (reference.StartsWith('#'))+ {+ if (FaceEntityToFaceId.ContainsKey(reference)) { entityRef = reference; return true; }+ entityRef = string.Empty;+ return false;+ }+ if (int.TryParse(reference, out var sequential) && TryResolveSequentialFaceId(sequential, out var resolved))+ {+ entityRef = resolved;+ return true;+ }+ entityRef = string.Empty;+ return false;+ }}public sealed record FirmamentV2RecognizedRegion(string BodyName, string RegionName, string Kind, IReadOnlyList<string> FaceRefs, string Confidence, FirmamentV2RecognitionEvidence? Evidence = null, FirmamentV2SemanticProposal? Proposal = null){diff --git a/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Parser.cs b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Parser.csindex 323423bf..dcc05058 100644--- a/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Parser.cs+++ b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Parser.cs@@ -67,6 +67,8 @@ public static class FirmamentV2Parserpublic 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 CanonicalDeclarationUnrecognized = "firmament-v2-canonical-declaration-unrecognized";+ public const string CanonicalFieldUnknown = "firmament-v2-canonical-field-unknown";public const string SelectionMalformed = "firmament-v2-selection-malformed";public const string SelectionDuplicateName = "firmament-v2-selection-duplicate-name";public const string SelectionUnknownSource = "firmament-v2-selection-unknown-source";@@ -259,9 +261,15 @@ public static class FirmamentV2Parserprivate 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 CanonicalInlineStepHeaderRegex = new(@"\bInlineStep\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);+ // Match the declaration-shaped header first; variant admission belongs in the+ // binder so a misspelled family can never disappear from a Modify block.+ private static readonly Regex CanonicalHoleHeaderRegex = new(@"\bHole\s*<\s*(?<variant>[A-Za-z_][A-Za-z0-9_]*)\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);+ private static readonly Regex CanonicalRecognizeHeaderRegex = new(@"\bRecognize\s+(?<body>[A-Za-z_][A-Za-z0-9_]*)\s*\{", RegexOptions.CultureInvariant);+ private static readonly Regex CanonicalRegionHeaderRegex = new(@"\bRegion\s+(?<name>[A-Za-z_][A-Za-z0-9_]*)\s*\{", RegexOptions.CultureInvariant);+ private static readonly Regex CanonicalReplaceHeaderRegex = new(@"\bReplace\s+(?<body>[A-Za-z_][A-Za-z0-9_]*)\.(?<region>[A-Za-z_][A-Za-z0-9_]*)\s+With\s+(?<kind>[A-Za-z_][A-Za-z0-9_]*(?:\s*<\s*[A-Za-z_][A-Za-z0-9_]*\s*>)?)\s+(?<name>[A-Za-z_][A-Za-z0-9_]*)\s*\{", RegexOptions.CultureInvariant);public static FirmamentV2ParseResult Parse(string sourceText) => Parse(sourceText, null, null);@@ -305,7 +313,7 @@ public static class FirmamentV2Parser{var parsed = Recognized(ContainsCanonicalAdvancedDeclaration(source)? ParseCanonicalAdvancedDocument(source, diagnostics, templateExpansion.Instantiations)- : ParseCanonicalDocument(source, diagnostics));+ : ParseCanonicalDocument(source, diagnostics, sourceDirectory));if (parsed.Document is null) return parsed;var normalized = parsed.Document with { StaticAuthoring = canonicalStaticExpansion.Document };@@ -768,7 +776,7 @@ public static class FirmamentV2Parserprivate static FirmamentV2SolidBinding? ParseInlineStep(string name, string body, List<string> diagnostics, string? sourceDirectory){- var match = PathRegex.Match(body);+ var match = Regex.Match(body, "\\b(?:path|Path)\\s*:\\s*\\\"(?<path>[^\\\"]+)\\\"", RegexOptions.CultureInvariant);if (!match.Success) { diagnostics.Add(InlineStepPathMissing); return null; }var sourcePath = match.Groups["path"].Value;@@ -866,6 +874,8 @@ public static class FirmamentV2Parservar 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);+ if (Regex.IsMatch(body, @"\b(?!(?:InlineStep|Recognize|Replace)\b)(?:Inline[A-Za-z_][A-Za-z0-9_]*|Recogniz[A-Za-z_][A-Za-z0-9_]*|Replac[A-Za-z_][A-Za-z0-9_]*)\b", RegexOptions.CultureInvariant))+ return CanonicalFailure(diagnostics, CanonicalDeclarationUnrecognized);var adapterSource = Regex.Replace(body, @"(?m)^\s*Units\s*:\s*mm\s*$", string.Empty, RegexOptions.CultureInvariant);if (PrismaticProfileCompositionParser.IsCompositionSource(adapterSource))@@ -1034,7 +1044,7 @@ public static class FirmamentV2Parserreturn true;}- private static FirmamentV2ParseResult ParseCanonicalDocument(string source, List<string> diagnostics)+ private static FirmamentV2ParseResult ParseCanonicalDocument(string source, List<string> diagnostics, string? sourceDirectory){var model = CanonicalModelRegex.Match(source);var rootOpen = model.Success ? source.IndexOf('{', model.Index) : -1;@@ -1046,6 +1056,8 @@ public static class FirmamentV2Parservar 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);+ if (Regex.IsMatch(body, @"\b(?!(?:InlineStep|Recognize|Replace)\b)(?:Inline[A-Za-z_][A-Za-z0-9_]*|Recogniz[A-Za-z_][A-Za-z0-9_]*|Recognis[A-Za-z_][A-Za-z0-9_]*|Replac[A-Za-z_][A-Za-z0-9_]*)\b", RegexOptions.CultureInvariant))+ return CanonicalFailure(diagnostics, CanonicalDeclarationUnrecognized);var solids = new List<FirmamentV2SolidBinding>();var byName = new Dictionary<string, FirmamentV2SolidBinding>(StringComparer.Ordinal);@@ -1063,6 +1075,18 @@ public static class FirmamentV2ParserbyName[name] = solid;solids.Add(solid);}+ foreach (Match inlineStep in CanonicalInlineStepHeaderRegex.Matches(body))+ {+ var open = body.IndexOf('{', inlineStep.Index);+ var close = FindMatchingBrace(body, open);+ if (close < 0) return CanonicalFailure(diagnostics, CanonicalPrimitiveMalformed);+ var name = inlineStep.Groups["name"].Value;+ if (!byName.TryAdd(name, null!)) return CanonicalFailure(diagnostics, DuplicateName);+ var binding = ParseInlineStep(name, body[(open + 1)..close], diagnostics, sourceDirectory);+ if (binding is null) return CanonicalFailure(diagnostics, InlineStepPathMissing);+ byName[name] = binding;+ solids.Add(binding);+ }if (solids.Count == 0) return CanonicalFailure(diagnostics, MissingSolid);var modifies = new List<FirmamentV2ModifyBlock>();@@ -1077,17 +1101,22 @@ public static class FirmamentV2Parservar 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))+ if (diagnostics.Any(IsFatalDiagnosticCode) || diagnostics.Contains(CanonicalPoint2Invalid) || diagnostics.Contains(CanonicalModifyMalformed) || diagnostics.Contains(CanonicalFieldUnknown))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));}+ var recognizedRegions = ParseCanonicalRecognizedRegions(body, byName, diagnostics);+ var replacements = ParseCanonicalReplacements(body, byName, recognizedRegions, diagnostics);+ if (diagnostics.Any(IsFatalDiagnosticCode) || diagnostics.Contains(CanonicalDeclarationUnrecognized) || diagnostics.Contains(CanonicalFieldUnknown))+ return CanonicalFailure(diagnostics, CanonicalDeclarationUnrecognized);+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());+ return FirmamentV2ParseResult.Success(new FirmamentV2Document(model.Groups["name"].Value, "mm", solids, modifies, RecognizedRegions: recognizedRegions, Replacements: replacements), diagnostics.Distinct(StringComparer.Ordinal).ToArray());}private static FirmamentV2PrimitiveRecord? ParseCanonicalPrimitive(string type, string body, List<string> diagnostics)@@ -1118,11 +1147,34 @@ public static class FirmamentV2Parserprivate 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 headers = CanonicalHoleHeaderRegex.Matches(body);+ if (Regex.Matches(body, @"\bHole\s*<", RegexOptions.CultureInvariant).Count != headers.Count)+ {+ diagnostics.Add(CanonicalModifyMalformed);+ return holes;+ }+ foreach (Match hole in headers){var open = body.IndexOf('{', hole.Index); var close = FindMatchingBrace(body, open);if (close < 0) { diagnostics.Add(CanonicalModifyMalformed); continue; }var holeBody = body[(open + 1)..close];+ if (!Enum.TryParse<FirmamentV2SemanticHoleVariant>(hole.Groups["variant"].Value, ignoreCase: false, out var variant))+ {+ diagnostics.Add(HoleVariantUnknown);+ continue;+ }++ var knownFields = variant switch+ {+ FirmamentV2SemanticHoleVariant.Counterbore => new[] { "On", "Center", "Diameter", "CounterboreDiameter", "CounterboreDepth", "End" },+ FirmamentV2SemanticHoleVariant.Countersink => new[] { "On", "Center", "Diameter", "CountersinkDiameter", "CountersinkAngle", "End" },+ _ => new[] { "On", "Center", "Diameter", "End" }+ };+ if (CanonicalBodyHasUnknownField(holeBody, knownFields))+ {+ diagnostics.Add(CanonicalFieldUnknown);+ continue;+ }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);@@ -1130,17 +1182,181 @@ public static class FirmamentV2Parserif (!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; }+ double? counterboreDiameter = null, counterboreDepth = null, countersinkDiameter = null, countersinkAngle = null;+ if (variant == FirmamentV2SemanticHoleVariant.Counterbore)+ {+ var cbDiameter = Regex.Match(holeBody, @"\bCounterboreDiameter\s*:\s*(?<value>[-+0-9.eE]+)mm\b", RegexOptions.CultureInvariant);+ var cbDepth = Regex.Match(holeBody, @"\bCounterboreDepth\s*:\s*(?<value>[-+0-9.eE]+)mm\b", RegexOptions.CultureInvariant);+ if (!cbDiameter.Success || !cbDepth.Success ||+ !double.TryParse(cbDiameter.Groups["value"].Value, NumberStyles.Float, CultureInfo.InvariantCulture, out var diameterValue) ||+ !double.TryParse(cbDepth.Groups["value"].Value, NumberStyles.Float, CultureInfo.InvariantCulture, out var depthValue) ||+ !double.IsFinite(diameterValue) || !double.IsFinite(depthValue) || diameterValue <= shaft || depthValue <= 0d)+ {+ diagnostics.Add(HoleCounterboreInvalid);+ continue;+ }+ counterboreDiameter = diameterValue;+ counterboreDepth = depthValue;+ }+ if (variant == FirmamentV2SemanticHoleVariant.Countersink)+ {+ var csDiameter = Regex.Match(holeBody, @"\bCountersinkDiameter\s*:\s*(?<value>[-+0-9.eE]+)mm\b", RegexOptions.CultureInvariant);+ var csAngle = Regex.Match(holeBody, @"\bCountersinkAngle\s*:\s*(?<value>[-+0-9.eE]+)deg\b", RegexOptions.CultureInvariant);+ if (!csDiameter.Success || !csAngle.Success ||+ !double.TryParse(csDiameter.Groups["value"].Value, NumberStyles.Float, CultureInfo.InvariantCulture, out var diameterValue) ||+ !double.TryParse(csAngle.Groups["value"].Value, NumberStyles.Float, CultureInfo.InvariantCulture, out var angleValue) ||+ !double.IsFinite(diameterValue) || !double.IsFinite(angleValue) || diameterValue <= shaft || angleValue <= 0d || angleValue >= 180d)+ {+ diagnostics.Add(HoleCountersinkInvalid);+ continue;+ }+ countersinkDiameter = diameterValue;+ countersinkAngle = angleValue;+ }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)));+ holes.Add(new(hole.Groups["name"].Value, variant, face, new FirmamentV2FaceLocalPoint2D(u, v, FirmamentV2FaceLocalPoint2D.ConventionFor(face.Axis)), shaft, endValue,+ counterboreDiameter, counterboreDepth, countersinkDiameter, countersinkAngle,+ SourceSpan: new FirmamentV2SourceSpan(bodyOffset + hole.Index, close - hole.Index + 1)));}return holes;}+ private static bool CanonicalBodyHasUnknownField(string body, IReadOnlyCollection<string> knownFields) =>+ Regex.Matches(body, @"(?m)^\s*(?<field>[A-Za-z_][A-Za-z0-9_]*)\s*:", RegexOptions.CultureInvariant)+ .Cast<Match>()+ .Any(match => !knownFields.Contains(match.Groups["field"].Value, StringComparer.Ordinal));++ // Canonical semantic STEP declarations bind directly to the normalized V2 nodes+ // used by the compatibility parser. FaceRefs deliberately remain STEP entities+ // downstream; the public canonical surface accepts analysis-facing ordinals.+ private static IReadOnlyList<FirmamentV2RecognizedRegion> ParseCanonicalRecognizedRegions(string source, Dictionary<string, FirmamentV2SolidBinding> solids, List<string> diagnostics)+ {+ var regions = new List<FirmamentV2RecognizedRegion>();+ var seen = new HashSet<string>(StringComparer.Ordinal);+ foreach (Match recognize in CanonicalRecognizeHeaderRegex.Matches(source))+ {+ var bodyName = recognize.Groups["body"].Value;+ if (!solids.TryGetValue(bodyName, out var solid) || solid.InlineStep is null) { diagnostics.Add(UnknownRecognitionBody); continue; }+ var open = source.IndexOf('{', recognize.Index); var close = FindMatchingBrace(source, open);+ if (close < 0) { diagnostics.Add(CanonicalDeclarationUnrecognized); continue; }+ var recognizeBody = source[(open + 1)..close];+ foreach (Match region in CanonicalRegionHeaderRegex.Matches(recognizeBody))+ {+ var name = region.Groups["name"].Value;+ if (!seen.Add($"{bodyName}.{name}")) { diagnostics.Add(DuplicateRegion); continue; }+ var regionOpen = recognizeBody.IndexOf('{', region.Index); var regionClose = FindMatchingBrace(recognizeBody, regionOpen);+ if (regionClose < 0) { diagnostics.Add(CanonicalDeclarationUnrecognized); continue; }+ var regionBody = recognizeBody[(regionOpen + 1)..regionClose];+ var kindMatch = Regex.Match(regionBody, @"\bKind\s*:\s*(?<value>[A-Za-z_][A-Za-z0-9_]*(?:\s*<\s*[A-Za-z_][A-Za-z0-9_]*\s*>)?)", RegexOptions.CultureInvariant);+ var kind = kindMatch.Success ? NormalizeRecognitionKind(kindMatch.Groups["value"].Value) : string.Empty;+ if (kind is not ("datumPlane" or "holeShaft")) { diagnostics.Add(InvalidRecognitionKind); continue; }+ var confidenceMatch = Regex.Match(regionBody, @"\bConfidence\s*:\s*(?<value>[A-Za-z_][A-Za-z0-9_]*)", RegexOptions.CultureInvariant);+ var confidence = confidenceMatch.Success ? confidenceMatch.Groups["value"].Value.ToLowerInvariant() : "medium";+ if (confidence is not ("low" or "medium" or "high" or "certain")) { diagnostics.Add(InvalidRecognitionConfidence); continue; }+ var faces = ParseCanonicalFaceReferences(regionBody, solid.InlineStep.TopologyMap, diagnostics);+ if (faces.Count == 0) continue;+ var evidence = ParseCanonicalRecognitionEvidence(regionBody, diagnostics);+ regions.Add(new FirmamentV2RecognizedRegion(bodyName, name, kind, faces, confidence, evidence));+ }+ }+ return regions;+ }++ private static IReadOnlyList<string> ParseCanonicalFaceReferences(string regionBody, ImportedStepTopologyMap topologyMap, List<string> diagnostics)+ {+ var faces = new List<string>();+ var friendly = Regex.Match(regionBody, @"\bFaces\s*:\s*\[(?<faces>[^\]]*)\]", RegexOptions.CultureInvariant | RegexOptions.Singleline);+ var raw = Regex.Match(regionBody, @"\bStepFaceEntities\s*:\s*\[(?<faces>[^\]]*)\]", RegexOptions.CultureInvariant | RegexOptions.Singleline);+ if (friendly.Success && raw.Success) { diagnostics.Add(UnknownRecognitionFace); return []; }+ if (friendly.Success)+ {+ foreach (var token in friendly.Groups["faces"].Value.Split(',', StringSplitOptions.TrimEntries | StringSplitOptions.RemoveEmptyEntries))+ {+ if (!int.TryParse(token, NumberStyles.None, CultureInfo.InvariantCulture, out var faceId) || faceId <= 0 || !topologyMap.TryResolveSequentialFaceId(faceId, out var entity)) { diagnostics.Add(UnknownRecognitionFace); return []; }+ faces.Add(entity);+ }+ }+ else if (raw.Success)+ {+ foreach (Match entity in Regex.Matches(raw.Groups["faces"].Value, "\\\"(?<entity>#[0-9]+)\\\"", RegexOptions.CultureInvariant))+ {+ var value = entity.Groups["entity"].Value;+ if (!topologyMap.TryResolveFaceEntity(value, out _)) { diagnostics.Add(UnknownRecognitionFace); return []; }+ faces.Add(value);+ }+ }+ if (faces.Count == 0 || faces.Distinct(StringComparer.Ordinal).Count() != faces.Count) { diagnostics.Add(UnknownRecognitionFace); return []; }+ return faces;+ }++ private static FirmamentV2RecognitionEvidence? ParseCanonicalRecognitionEvidence(string regionBody, List<string> diagnostics)+ {+ var header = Regex.Match(regionBody, @"\bEvidence\s*:\?\s*\{", RegexOptions.CultureInvariant);+ if (!header.Success) return null;+ var open = regionBody.IndexOf('{', header.Index); var close = FindMatchingBrace(regionBody, open);+ if (close < 0) { diagnostics.Add(CanonicalDeclarationUnrecognized); return null; }+ var body = regionBody[(open + 1)..close];+ var surface = Regex.Match(body, @"\bSurfaceFamily\s*:\s*(?<value>[A-Za-z_][A-Za-z0-9_]*)", RegexOptions.CultureInvariant);+ var families = new List<string>();+ if (surface.Success)+ {+ var family = surface.Groups["value"].Value.ToLowerInvariant();+ if (family is not ("cylindrical" or "planar")) diagnostics.Add(RecognitionEvidenceSurfaceFamilyUnknown); else families.Add(family);+ }+ double? radius = null;+ if (Regex.IsMatch(body, @"\bRadius\s*:", RegexOptions.CultureInvariant))+ {+ var match = Regex.Match(body, @"\bRadius\s*:\s*(?<value>[-+0-9.eE]+)mm\b", RegexOptions.CultureInvariant);+ if (!match.Success || !double.TryParse(match.Groups["value"].Value, NumberStyles.Float, CultureInfo.InvariantCulture, out var value) || value <= 0d || !double.IsFinite(value)) diagnostics.Add(RecognitionEvidenceRadiusInvalid); else radius = value;+ }+ bool? through = null;+ var throughMatch = Regex.Match(body, @"\bThrough\s*:\s*(?<value>true|false)\b", RegexOptions.CultureInvariant | RegexOptions.IgnoreCase);+ if (throughMatch.Success) through = bool.Parse(throughMatch.Groups["value"].Value);+ return new FirmamentV2RecognitionEvidence(families, radius, Through: through, Notes: []);+ }++ private static IReadOnlyList<FirmamentV2ReplacementDecl> ParseCanonicalReplacements(string source, Dictionary<string, FirmamentV2SolidBinding> solids, IReadOnlyList<FirmamentV2RecognizedRegion> recognizedRegions, List<string> diagnostics)+ {+ var replacements = new List<FirmamentV2ReplacementDecl>();+ foreach (Match replace in CanonicalReplaceHeaderRegex.Matches(source))+ {+ var bodyName = replace.Groups["body"].Value; var regionName = replace.Groups["region"].Value;+ if (!solids.TryGetValue(bodyName, out var solid) || solid.InlineStep is null) { diagnostics.Add(UnknownReplacementBody); continue; }+ var region = recognizedRegions.SingleOrDefault(candidate => candidate.BodyName == bodyName && candidate.RegionName == regionName);+ if (region is null) { diagnostics.Add(UnknownReplacementRegion); continue; }+ var kind = NormalizeRecognitionKind(replace.Groups["kind"].Value);+ if (kind != "holeShaft") { diagnostics.Add(ReplacementUnsupportedKind); continue; }+ if (region.Kind != kind) { diagnostics.Add(ReplacementKindMismatch); continue; }+ var open = source.IndexOf('{', replace.Index); var close = FindMatchingBrace(source, open);+ if (close < 0) { diagnostics.Add(CanonicalDeclarationUnrecognized); continue; }+ var body = source[(open + 1)..close];+ var face = Regex.Match(body, @"\bOn\s*:\s*(?<body>[A-Za-z_][A-Za-z0-9_]*)\.Face\(\s*(?<face>[0-9]+)\s*\)", RegexOptions.CultureInvariant);+ if (!face.Success || face.Groups["body"].Value != bodyName || !int.TryParse(face.Groups["face"].Value, out var faceId) || !solid.InlineStep.TopologyMap.TryResolveSequentialFaceId(faceId, out var entity)) { diagnostics.Add(ReplacementFaceUnresolved); continue; }+ var center = Regex.Match(body, @"\bCenter\s*:\s*Point2\(\s*(?<u>[-+0-9.eE]+)mm\s*,\s*(?<v>[-+0-9.eE]+)mm\s*\)", RegexOptions.CultureInvariant);+ if (!center.Success || !double.TryParse(center.Groups["u"].Value, NumberStyles.Float, CultureInfo.InvariantCulture, out var u) || !double.TryParse(center.Groups["v"].Value, NumberStyles.Float, CultureInfo.InvariantCulture, out var v)) { diagnostics.Add(HoleCenterMissing); continue; }+ var diameter = Regex.Match(body, @"\bDiameter\s*:\s*(?<value>[-+0-9.eE]+)mm\b", RegexOptions.CultureInvariant);+ if (!diameter.Success || !double.TryParse(diameter.Groups["value"].Value, NumberStyles.Float, CultureInfo.InvariantCulture, out var d) || d <= 0d || !double.IsFinite(d)) { diagnostics.Add(ReplacementRadiusInvalid); continue; }+ if (!Regex.IsMatch(body, @"\bEnd\s*:\s*ThroughAll\b", RegexOptions.CultureInvariant)) { diagnostics.Add(ReplacementEndUnsupported); continue; }+ var host = Regex.Match(body, @"\bHostSize\s*:\s*\[(?<values>[^\]]*)\]", RegexOptions.CultureInvariant);+ var hostSize = host.Success ? ParseCanonicalLengthTriple(host.Groups["values"].Value) : null;+ if (hostSize is null) { diagnostics.Add(ReplacementVerificationFailed); continue; }+ replacements.Add(new FirmamentV2ReplacementDecl(bodyName, regionName, kind, replace.Groups["name"].Value, $"{bodyName}.face(\"{entity}\")", new FirmamentV2FaceLocalPoint2D(u, v, string.Empty), d / 2d, "throughAll", hostSize, replace.Value));+ }+ return replacements;+ }++ private static IReadOnlyList<double>? ParseCanonicalLengthTriple(string raw)+ {+ var values = raw.Split(',', StringSplitOptions.TrimEntries | StringSplitOptions.RemoveEmptyEntries)+ .Select(ParsePhase3Length)+ .ToArray();+ return values.Length == 3 && values.All(value => double.IsFinite(value) && value > 0d) ? values : null;+ }+private static IReadOnlyList<FirmamentV2EdgeFinishDecl> ParseCanonicalEdgeFinishes(string body, int bodyOffset, List<string> diagnostics){var finishes = new List<FirmamentV2EdgeFinishDecl>();@@ -2012,7 +2228,9 @@ public static class FirmamentV2Parserprivate static string NormalizeRecognitionKind(string raw){raw = raw.Trim().Trim('"').Replace(" ", string.Empty, StringComparison.Ordinal);- return string.Equals(raw, "hole<shaft>", StringComparison.Ordinal) ? "holeShaft" : raw;+ return string.Equals(raw, "hole<shaft>", StringComparison.OrdinalIgnoreCase) || string.Equals(raw, "holeShaft", StringComparison.OrdinalIgnoreCase)+ ? "holeShaft"+ : string.Equals(raw, "datumPlane", StringComparison.OrdinalIgnoreCase) ? "datumPlane" : raw;}private static FirmamentV2RecognitionEvidence? ParseRecognitionEvidence(string regionBody, List<string> diagnostics)diff --git a/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2SemanticHoleLowering.cs b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2SemanticHoleLowering.csindex 984f42aa..eb8f8f46 100644--- a/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2SemanticHoleLowering.cs+++ b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2SemanticHoleLowering.cs@@ -7,6 +7,9 @@ internal static class FirmamentV2SemanticHoleLowering{public static AirHoleFeature Lower(FirmamentV2Document document, FirmamentV2ModifyBlock modify, FirmamentV2SemanticHoleDecl hole){+ // This lowerer receives parser-validated declarations. Keep the contract+ // explicit nevertheless: optional parsed scalars are never dereferenced.+ static double Required(double? value, string field) => value ?? throw new ArgumentException($"Validated hole is missing {field}.", nameof(value));if (hole.Placement is FirmamentV2ConstructionPlaneHolePlacement construction){var plane = construction.Plane;@@ -15,9 +18,9 @@ internal static class FirmamentV2SemanticHoleLoweringAirHoleEndCondition constructionEnd = hole.EndCondition.Kind switch{FirmamentV2SemanticHoleEndKind.ThroughAll => new AirHoleEndCondition.ThroughAll(),- FirmamentV2SemanticHoleEndKind.ShaftDepth => new AirHoleEndCondition.ShaftDepth(hole.EndCondition.Depth!.Value),- FirmamentV2SemanticHoleEndKind.TotalDepth => new AirHoleEndCondition.TotalDepth(hole.EndCondition.Depth!.Value),- _ => new AirHoleEndCondition.Depth(hole.EndCondition.Depth!.Value)+ FirmamentV2SemanticHoleEndKind.ShaftDepth => new AirHoleEndCondition.ShaftDepth(Required(hole.EndCondition.Depth, "end depth")),+ FirmamentV2SemanticHoleEndKind.TotalDepth => new AirHoleEndCondition.TotalDepth(Required(hole.EndCondition.Depth, "end depth")),+ _ => new AirHoleEndCondition.Depth(Required(hole.EndCondition.Depth, "end depth"))};AirHoleTermination? constructionTermination = hole.Termination?.Kind switch{@@ -40,7 +43,7 @@ internal static class FirmamentV2SemanticHoleLoweringvar placement = new AirFaceLocalHolePlacement(hole.EntryFace.Axis switch { "+Z" => "top", "-Z" => "bottom", _ => hole.EntryFace.Source }, hole.Center.U, hole.Center.V, FirmamentV2FaceLocalPoint2D.ConventionFor(hole.EntryFace.Axis), hole.EntryFace.ResolvedSelector, pointSource);var axis = new AirHoleAxis(Direction3D.Create(hole.EntryFace.Axis switch { "-Z" => new Vector3D(0,0,-1), "+Z" => new Vector3D(0,0,1), "+X" => new Vector3D(1,0,0), "-X" => new Vector3D(-1,0,0), "+Y" => new Vector3D(0,1,0), _ => new Vector3D(0,-1,0) }), true);var shaft = new AirHoleShaft(hole.ShaftDiameter);- AirHoleEndCondition endCondition = hole.EndCondition.Kind == FirmamentV2SemanticHoleEndKind.ThroughAll ? new AirHoleEndCondition.ThroughAll() : new AirHoleEndCondition.Depth(hole.EndCondition.Depth!.Value);+ AirHoleEndCondition endCondition = hole.EndCondition.Kind == FirmamentV2SemanticHoleEndKind.ThroughAll ? new AirHoleEndCondition.ThroughAll() : new AirHoleEndCondition.Depth(Required(hole.EndCondition.Depth, "end depth"));var notes = new List<string> { $"source-variant:{hole.Variant}", $"target-solid:{modify.TargetSolid}", $"entry-face:{hole.EntryFace.Source}" };if (hole.ResolvedCenter is { } center){@@ -52,8 +55,8 @@ internal static class FirmamentV2SemanticHoleLoweringvar provenance = new AirProvenance("CONCEPT-MATERIALIZATION-M2", "Typed Concept Point3 semantic hole source", hole.Name, $"{modify.TargetSolid}.{hole.Name}", nameof(AirHoleFeature), AirSelectionClass.None, AirRuleKind.None, $"FirmamentV2 hole<{hole.Variant}>", true, notes);return hole.Variant switch{- FirmamentV2SemanticHoleVariant.Counterbore => AirHoleFeature.CreateCounterbore(hole.Name, $"{modify.TargetSolid}.{hole.Name}", modify.TargetSolid, placement, axis, shaft, endCondition, new AirHoleCounterboreComponent(hole.CounterboreDiameter!.Value, hole.CounterboreDepth!.Value), provenance),- FirmamentV2SemanticHoleVariant.Countersink => AirHoleFeature.CreateCountersink(hole.Name, $"{modify.TargetSolid}.{hole.Name}", modify.TargetSolid, placement, axis, shaft, endCondition, new AirHoleCountersinkComponent(hole.CountersinkDiameter!.Value, hole.CountersinkAngleDegrees!.Value), provenance),+ FirmamentV2SemanticHoleVariant.Counterbore => AirHoleFeature.CreateCounterbore(hole.Name, $"{modify.TargetSolid}.{hole.Name}", modify.TargetSolid, placement, axis, shaft, endCondition, new AirHoleCounterboreComponent(Required(hole.CounterboreDiameter, "CounterboreDiameter"), Required(hole.CounterboreDepth, "CounterboreDepth")), provenance),+ FirmamentV2SemanticHoleVariant.Countersink => AirHoleFeature.CreateCountersink(hole.Name, $"{modify.TargetSolid}.{hole.Name}", modify.TargetSolid, placement, axis, shaft, endCondition, new AirHoleCountersinkComponent(Required(hole.CountersinkDiameter, "CountersinkDiameter"), Required(hole.CountersinkAngleDegrees, "CountersinkAngle")), provenance),_ => AirHoleFeature.CreateSimpleShaft(hole.Name, $"{modify.TargetSolid}.{hole.Name}", modify.TargetSolid, placement, axis, shaft, endCondition, provenance)};}diff --git a/docs/firmament/v2-canonical-authoring.md b/docs/firmament/v2-canonical-authoring.mdindex 87c0c9bc..f8b0b3a4 100644--- a/docs/firmament/v2-canonical-authoring.md+++ b/docs/firmament/v2-canonical-authoring.md@@ -1,5 +1,15 @@# Firmament V2 canonical authoring+`Hole<Shaft>`, `Hole<Counterbore>`, and `Hole<Countersink>` are canonical+families. Counterbore requires `CounterboreDiameter` and `CounterboreDepth`;+Countersink requires `CountersinkDiameter` and `CountersinkAngle` in `deg`.+Unknown families (for example `Hole<Blind>`) are rejected immediately.++Canonical `InlineStep`, `Recognize`, and `Replace` use the sequential face IDs+reported by `aetheris analyze`; raw STEP entity IDs are an explicit advanced+form only. See [semantic labeling](v2-semantic-labeling.md) for a copyable+analyze-to-replacement workflow.+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:diff --git a/docs/firmament/v2-canonical-safety-and-labeling-x4.md b/docs/firmament/v2-canonical-safety-and-labeling-x4.mdnew file mode 100644index 00000000..39ecaa4f--- /dev/null+++ b/docs/firmament/v2-canonical-safety-and-labeling-x4.md@@ -0,0 +1,25 @@+# CANONICAL-SAFETY-AND-LABELING-X4++Round 2 found two frontend integrity faults: canonical Counterbore/Countersink+fields were omitted before lowering and an unknown `Hole<Variant>` could be+ignored. Canonical Hole headers now bind any candidate identifier and reject+unknown variants with `firmament-v2-hole-variant-unknown`. Variant contracts+bind `CounterboreDiameter`/`CounterboreDepth` or+`CountersinkDiameter`/`CountersinkAngle` before a semantic hole is created;+invalid or incomplete values produce the existing variant diagnostics.++Lowering no longer dereferences nullable user fields. Parser validation is the+source-to-AIR boundary: an invalid declaration never creates a document that+can reach the AIR materializer. Canonical Hole blocks also reject unknown field+names rather than silently ignoring a misspelling.++The canonical V2 root now admits `InlineStep`, `Recognize`, and `Replace`.+They produce the same normalized `FirmamentV2InlineStepRecord`,+`FirmamentV2RecognizedRegion`, and `FirmamentV2ReplacementDecl` used by the+lowercase compatibility adapter. Sequential face IDs resolve via the imported+topology map; raw STEP entities remain an explicit advanced form.++The repository fixture+`fixtures/FirmamentV2/Canonical/valid/inline-step-recognize-replace.firmament`+is the replay path: analyze face 7, recognize it by `Faces: [7]`, and execute+the bounded verified hole replacement. It does not require raw STEP grep.diff --git a/docs/firmament/v2-semantic-labeling.md b/docs/firmament/v2-semantic-labeling.mdnew file mode 100644index 00000000..ec140323--- /dev/null+++ b/docs/firmament/v2-semantic-labeling.md@@ -0,0 +1,40 @@+# Firmament V2 semantic STEP labeling++The canonical language supports imported canonical STEP, human-readable face IDs,+recognition, and the bounded through-hole replacement route.++```firmament+Model LabeledPart {+ Units: mm+ InlineStep Source { Path: "part.step" }++ Recognize Source {+ Region MountHole {+ Kind: HoleShaft+ Confidence: High+ Faces: [7]+ Evidence: { SurfaceFamily: Cylindrical Radius: 4mm Through: true }+ }+ }++ Replace Source.MountHole With Hole<Shaft> MountHole {+ On: Source.Face(7)+ Center: Point2(0mm, 0mm)+ Diameter: 8mm+ End: ThroughAll+ HostSize: [80mm, 50mm, 25mm]+ }+}+```++Run `aetheris analyze part.step --face 7 --json` to inspect a face before+authoring. `Faces` and `Source.Face(n)` use the sequential analysis-facing ID;+the parser resolves it to the imported STEP `ADVANCED_FACE` entity through the+InlineStep topology map. For traceability only, `StepFaceEntities: ["#191"]`+is also accepted in a `Region`; do not mix it with `Faces`.++Currently admitted recognition kinds are `HoleShaft` and `DatumPlane`. The+replacement materializer is intentionally limited to verified `Hole<Shaft>`+through-all rebuilds and requires `On`, `Center`, `Diameter`, and `HostSize`.+The lowercase `solid … : InlineStep`, `recognize`, and `replace` forms remain+compatibility syntax and normalize to the same V2 records.diff --git a/fixtures/FirmamentV2/Canonical/valid/counterbore-hole.firmament b/fixtures/FirmamentV2/Canonical/valid/counterbore-hole.firmamentnew file mode 100644index 00000000..2cac1966--- /dev/null+++ b/fixtures/FirmamentV2/Canonical/valid/counterbore-hole.firmament@@ -0,0 +1,18 @@+Model CounterboreHole {+ Units: mm++ Box Base {+ Size: [80mm, 50mm, 25mm]+ }++ Modify Base {+ Hole<Counterbore> Mount {+ On: +Z+ Center: Point2(0mm, 0mm)+ Diameter: 6mm+ CounterboreDiameter: 11mm+ CounterboreDepth: 4mm+ End: ThroughAll+ }+ }+}diff --git a/fixtures/FirmamentV2/Canonical/valid/countersink-hole.firmament b/fixtures/FirmamentV2/Canonical/valid/countersink-hole.firmamentnew file mode 100644index 00000000..50a114fe--- /dev/null+++ b/fixtures/FirmamentV2/Canonical/valid/countersink-hole.firmament@@ -0,0 +1,18 @@+Model CountersinkHole {+ Units: mm++ Box Base {+ Size: [80mm, 50mm, 25mm]+ }++ Modify Base {+ Hole<Countersink> Mount {+ On: +Z+ Center: Point2(0mm, 0mm)+ Diameter: 6mm+ CountersinkDiameter: 12mm+ CountersinkAngle: 90deg+ End: ThroughAll+ }+ }+}diff --git a/fixtures/FirmamentV2/Canonical/valid/inline-step-recognize-replace.firmament b/fixtures/FirmamentV2/Canonical/valid/inline-step-recognize-replace.firmamentnew file mode 100644index 00000000..88913d53--- /dev/null+++ b/fixtures/FirmamentV2/Canonical/valid/inline-step-recognize-replace.firmament@@ -0,0 +1,28 @@+Model InlineStepRecognizeReplace {+ Units: mm++ InlineStep Source {+ Path: "../../InlineStep/testdata/canonical-through-hole.step"+ }++ Recognize Source {+ Region MountHole {+ Kind: HoleShaft+ Confidence: High+ Faces: [7]+ Evidence: {+ SurfaceFamily: Cylindrical+ Radius: 1mm+ Through: true+ }+ }+ }++ Replace Source.MountHole With Hole<Shaft> MountHole {+ On: Source.Face(7)+ Center: Point2(0mm, 0mm)+ Diameter: 2mm+ End: ThroughAll+ HostSize: [10mm, 8mm, 6mm]+ }+}