Skip to content

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.cs
index 8685e1e2..a0268311 100644
--- a/Aetheris.CLI/CliRunner.cs
+++ b/Aetheris.CLI/CliRunner.cs
@@ -2653,7 +2653,7 @@ public static class CliRunner
if (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.cs
index 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.cs
index 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.cs
new file mode 100644
index 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.cs
index 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 Norma
public 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.cs
index 323423bf..dcc05058 100644
--- a/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Parser.cs
+++ b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Parser.cs
@@ -67,6 +67,8 @@ public static class FirmamentV2Parser
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 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 FirmamentV2Parser
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 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 FirmamentV2Parser
private 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 FirmamentV2Parser
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);
+ 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 FirmamentV2Parser
return 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 FirmamentV2Parser
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);
+ 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 FirmamentV2Parser
byName[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 FirmamentV2Parser
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))
+ 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 FirmamentV2Parser
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 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 FirmamentV2Parser
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; }
+ 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 FirmamentV2Parser
private 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.cs
index 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 FirmamentV2SemanticHoleLowering
AirHoleEndCondition 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 FirmamentV2SemanticHoleLowering
var 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 FirmamentV2SemanticHoleLowering
var 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.md
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.firmament
new file mode 100644
index 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.firmament
new file mode 100644
index 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.firmament
new file mode 100644
index 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]
+ }
+}