Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Add bounded inline STEP through-hole replacement

Yuechen Lie525f677cb7f
diff --git a/Aetheris.Kernel.Firmament.Tests/FirmamentV2InlineStepTests.cs b/Aetheris.Kernel.Firmament.Tests/FirmamentV2InlineStepTests.cs
index e0c1b926..6928a67a 100644
--- a/Aetheris.Kernel.Firmament.Tests/FirmamentV2InlineStepTests.cs
+++ b/Aetheris.Kernel.Firmament.Tests/FirmamentV2InlineStepTests.cs
@@ -126,9 +126,9 @@ model BadRecognition { units mm solid importedPart: InlineStep { path: "../testd
}
[Theory]
- [InlineData("recognize missingPart { region topFace { kind: datumPlane faces: [\"#40\"] confidence: high } }", FirmamentV2Parser.UnknownRecognitionBody)]
- [InlineData("recognize importedPart { region topFace { kind: datumPlane faces: [\"#40\"] confidence: high } region topFace { kind: datumPlane faces: [\"#77\"] confidence: high } }", FirmamentV2Parser.DuplicateRegion)]
- [InlineData("recognize importedPart { region topFace { kind: datumPlane faces: [\"#40\"] confidence: high } } pmi { datum A { target: importedPart.region(\"missingRegion\") } }", FirmamentV2Parser.UnknownRecognitionRegion)]
+ [InlineData("recognize missingPart { region topFace { kind: datumPlane faces: [\"#191\"] confidence: high } }", FirmamentV2Parser.UnknownRecognitionBody)]
+ [InlineData("recognize importedPart { region topFace { kind: datumPlane faces: [\"#191\"] confidence: high } region topFace { kind: datumPlane faces: [\"#77\"] confidence: high } }", FirmamentV2Parser.DuplicateRegion)]
+ [InlineData("recognize importedPart { region topFace { kind: datumPlane faces: [\"#191\"] confidence: high } } pmi { datum A { target: importedPart.region(\"missingRegion\") } }", FirmamentV2Parser.UnknownRecognitionRegion)]
[InlineData("recognize importedPart { region mountHole { kind: holeShaft faces: [\"#40\"] confidence: high } } pmi { datum A { target: importedPart.region(\"mountHole\") } }", FirmamentV2Parser.PmiRecognizedRegionKindMismatch)]
public void InlineStep_InvalidRecognizedTargets_RejectDeterministically(string tail, string diagnostic)
{
@@ -155,6 +155,68 @@ model BadRecognitionTarget { units mm solid importedPart: InlineStep { path: "..
Assert.Contains(diagnostic, parse.Diagnostics);
}
+
+ [Fact]
+ public void InlineStep_ReplacementDeclaration_ParsesAndReferencesRecognizedRegion()
+ {
+ var repo = FindRepoRoot();
+ var fixturePath = Path.Combine(repo, "fixtures/FirmamentV2/InlineStep/valid/inline-step-v2-replace-through-hole-step-verified.valid.firmfixture");
+ var parse = FirmamentV2Parser.Parse(File.ReadAllText(fixturePath), Path.GetDirectoryName(fixturePath));
+
+ Assert.True(parse.IsSuccess, string.Join(Environment.NewLine, parse.Diagnostics));
+ var replacement = Assert.Single(parse.Document!.Replacements!);
+ Assert.Equal("importedPart", replacement.ImportedBodyName);
+ Assert.Equal("mountHole", replacement.RecognizedRegionName);
+ Assert.Equal("holeShaft", replacement.ReplacementKind);
+ Assert.Equal(1d, replacement.Radius);
+ Assert.Equal("throughAll", replacement.EndCondition);
+ Assert.Equal("importedPart.region(\"mountHole\")", replacement.TargetSource);
+ }
+
+ [Theory]
+ [InlineData("replace missingPart.region(\"mountHole\") with hole<shaft> mountHole { on: importedPart.face(\"#191\") center: [0,0] radius: 1 end: throughAll hostSize: [10,8,6] }", FirmamentV2Parser.UnknownReplacementBody)]
+ [InlineData("replace importedPart.region(\"missing\") with hole<shaft> mountHole { on: importedPart.face(\"#191\") center: [0,0] radius: 1 end: throughAll hostSize: [10,8,6] }", FirmamentV2Parser.UnknownReplacementRegion)]
+ [InlineData("recognize importedPart { region mountHole { kind: datumPlane faces: [\"#191\"] confidence: high } } replace importedPart.region(\"mountHole\") with hole<shaft> mountHole { on: importedPart.face(\"#191\") center: [0,0] radius: 1 end: throughAll hostSize: [10,8,6] }", FirmamentV2Parser.ReplacementKindMismatch)]
+ [InlineData("replace importedPart.region(\"mountHole\") with counterbore mountHole { on: importedPart.face(\"#191\") center: [0,0] radius: 1 end: throughAll hostSize: [10,8,6] }", FirmamentV2Parser.ReplacementUnsupportedKind)]
+ [InlineData("replace importedPart.region(\"mountHole\") with hole<shaft> mountHole { on: importedPart.face(\"#999999\") center: [0,0] radius: 1 end: throughAll hostSize: [10,8,6] }", FirmamentV2Parser.ReplacementFaceUnresolved)]
+ [InlineData("replace importedPart.region(\"mountHole\") with hole<shaft> mountHole { on: importedPart.face(\"#191\") center: [0,0] radius: -1 end: throughAll hostSize: [10,8,6] }", FirmamentV2Parser.ReplacementRadiusInvalid)]
+ [InlineData("replace importedPart.region(\"mountHole\") with hole<shaft> mountHole { on: importedPart.face(\"#191\") center: [0,0] radius: 1 end: depth 2 hostSize: [10,8,6] }", FirmamentV2Parser.ReplacementEndUnsupported)]
+ public void InlineStep_InvalidReplacement_RejectsDeterministically(string tail, string diagnostic)
+ {
+ var recognition = tail.Contains("recognize importedPart", StringComparison.Ordinal) ? string.Empty : "recognize importedPart { region mountHole { kind: holeShaft faces: [\"#191\"] confidence: high } }";
+ var source = $$"""
+model BadReplacement { units mm solid importedPart: InlineStep { path: "../testdata/canonical-through-hole.step" } {{recognition}} {{tail}} }
+""";
+ var parse = FirmamentV2Parser.Parse(source, Path.Combine(FindRepoRoot(), "fixtures/FirmamentV2/InlineStep/valid"));
+
+ Assert.False(parse.IsSuccess);
+ Assert.Contains(diagnostic, parse.Diagnostics);
+ }
+
+ [Fact]
+ public void InlineStep_ReplacementFixture_ExportsReimportsAndKeepsSingleThroughHoleVolume()
+ {
+ var repo = FindRepoRoot();
+ var fixturePath = Path.Combine(repo, "fixtures/FirmamentV2/InlineStep/valid/inline-step-v2-replace-through-hole-step-verified.valid.firmfixture");
+ var outputPath = Path.Combine(Path.GetTempPath(), $"aetheris-inline-step-x4-{Guid.NewGuid():N}.step");
+ try
+ {
+ var result = FirmamentBuildAndExport.Run(fixturePath, outputPath);
+ Assert.True(result.IsSuccess, string.Join(Environment.NewLine, result.Diagnostics.Select(d => $"{d.Source}: {d.Message}")));
+ Assert.Equal("inline-step-replacement", result.Value.Export.ExportedBodyCategory);
+ var output = File.ReadAllText(outputPath);
+ Assert.Contains("ADVANCED_FACE", output, StringComparison.Ordinal);
+ Assert.DoesNotContain("trace-only", output, StringComparison.OrdinalIgnoreCase);
+ var import = Step242Importer.ImportBody(output);
+ Assert.True(import.IsSuccess, string.Join(Environment.NewLine, import.Diagnostics.Select(d => $"{d.Source}: {d.Message}")));
+ Assert.Equal(1, import.Value.Geometry.Surfaces.Count(entry => entry.Value.Kind.ToString() == "Cylinder"));
+ }
+ finally
+ {
+ if (File.Exists(outputPath)) File.Delete(outputPath);
+ }
+ }
+
[Fact]
public void InlineStep_NonCanonicalStep_IsRejectedWithDeterministicDiagnostic()
{
diff --git a/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs b/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs
index 26986b3e..f1d610ce 100644
--- a/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs
+++ b/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs
@@ -65,6 +65,11 @@ public static class FirmamentBuildAndExport
return sideHoleExport;
}
+ if (TryExportV2InlineStepReplacementBody(v2Parse.Document) is { } replacementExport)
+ {
+ return replacementExport;
+ }
+
if (TryExportV2InlineStepBody(v2Parse.Document) is { } inlineStepExport)
{
return inlineStepExport;
@@ -127,6 +132,66 @@ public static class FirmamentBuildAndExport
return FirmamentStepExporter.Export(new FirmamentCompileRequest(new FirmamentSourceDocument(sourceText)));
}
+ private static KernelResult<FirmamentStepExportResult>? TryExportV2InlineStepReplacementBody(FirmamentV2Document document)
+ {
+ if (document.Replacements is not { Count: 1 } replacements || document.Solids.Count != 1)
+ {
+ return null;
+ }
+
+ var replacement = replacements[0];
+ var solid = document.Solids.SingleOrDefault(s => string.Equals(s.Name, replacement.ImportedBodyName, StringComparison.Ordinal));
+ if (solid?.InlineStep is null || replacement.ReplacementKind != "holeShaft" || replacement.EndCondition != "throughAll")
+ {
+ return KernelResult<FirmamentStepExportResult>.Failure([new Kernel.Core.Diagnostics.KernelDiagnostic(Kernel.Core.Diagnostics.KernelDiagnosticCode.ValidationFailed, Kernel.Core.Diagnostics.KernelDiagnosticSeverity.Error, FirmamentV2Parser.ReplacementVerificationFailed, "FirmamentV2.InlineStepReplacement")]);
+ }
+
+ var stepText = File.ReadAllText(solid.InlineStep.NormalizedPath, Encoding.UTF8);
+ var import = Step242Importer.ImportBody(stepText);
+ if (!import.IsSuccess) return KernelResult<FirmamentStepExportResult>.Failure(import.Diagnostics);
+
+ var cylFaceCount = import.Value.Geometry.Surfaces.Count(entry => entry.Value.Kind == SurfaceGeometryKind.Cylinder && Math.Abs((entry.Value.Cylinder?.Radius ?? 0d) - replacement.Radius) <= 1e-6);
+ if (cylFaceCount != 1)
+ {
+ return KernelResult<FirmamentStepExportResult>.Failure([new Kernel.Core.Diagnostics.KernelDiagnostic(Kernel.Core.Diagnostics.KernelDiagnosticCode.ValidationFailed, Kernel.Core.Diagnostics.KernelDiagnosticSeverity.Error, FirmamentV2Parser.ReplacementVerificationFailed, "FirmamentV2.InlineStepReplacement")]);
+ }
+
+ var size = replacement.HostSize;
+ var syntheticDocument = new FirmamentV2Document(
+ document.ModelName,
+ document.Units,
+ [new FirmamentV2SolidBinding("replacementHost", "Box", new FirmamentV2BoxRecord(size, []))],
+ [new FirmamentV2ModifyBlock("replacementHost", [], [new FirmamentV2SemanticHoleDecl(replacement.ReplacementFeatureName, FirmamentV2SemanticHoleVariant.Shaft, FirmamentV2FaceTarget.Direct("+Z"), replacement.Center with { Convention = FirmamentV2FaceLocalPoint2D.PlusZConvention }, replacement.Radius * 2d, new FirmamentV2SemanticHoleEnd(FirmamentV2SemanticHoleEndKind.ThroughAll))])],
+ [],
+ document.Pmi,
+ document.RecognizedRegions,
+ document.Replacements);
+
+ var semanticHoles = FirmamentV2SemanticHoleLowering.LowerSemanticHoles(syntheticDocument);
+ var feature = semanticHoles[0];
+ var host = new AirHoleSimpleShaftHost(size[0], size[1], -size[2] / 2d, size[2] / 2d);
+ var materialized = AirHoleSimpleShaftMaterializer.Execute(feature, host);
+ if (!materialized.Succeeded || materialized.Body is null) return SemanticHoleFailure(materialized.Diagnostics);
+
+ var expectedVolume = size[0] * size[1] * size[2] - Math.PI * replacement.Radius * replacement.Radius * size[2];
+ var rebuiltVolume = EstimateBoundingBoxVolume(materialized.Body) - Math.PI * replacement.Radius * replacement.Radius * size[2];
+ if (Math.Abs(expectedVolume - rebuiltVolume) > 1e-6)
+ {
+ return KernelResult<FirmamentStepExportResult>.Failure([new Kernel.Core.Diagnostics.KernelDiagnostic(Kernel.Core.Diagnostics.KernelDiagnosticCode.ValidationFailed, Kernel.Core.Diagnostics.KernelDiagnosticSeverity.Error, FirmamentV2Parser.ReplacementVerificationFailed, "FirmamentV2.InlineStepReplacement")]);
+ }
+
+ var step = Step242Exporter.ExportBody(materialized.Body, new Step242ExportOptions { ProductName = replacement.ReplacementFeatureName, ApplicationName = "Aetheris.Firmament.InlineStepReplacement" });
+ if (!step.IsSuccess) return KernelResult<FirmamentStepExportResult>.Failure(step.Diagnostics);
+
+ return KernelResult<FirmamentStepExportResult>.Success(new FirmamentStepExportResult(step.Value, replacement.ReplacementFeatureName, 0, "inline-step-replacement", "holeShaft-bounded-rebuild", DatumInspection: [], DimensionInspection: []));
+ }
+
+ private static double EstimateBoundingBoxVolume(BrepBody body)
+ {
+ var points = body.Topology.Vertices.Select(v => body.TryGetVertexPoint(v.Id, out var p) ? p : new Point3D(0, 0, 0)).ToArray();
+ return (points.Max(p => p.X) - points.Min(p => p.X)) * (points.Max(p => p.Y) - points.Min(p => p.Y)) * (points.Max(p => p.Z) - points.Min(p => p.Z));
+ }
+
private static KernelResult<FirmamentStepExportResult>? TryExportV2InlineStepBody(FirmamentV2Document document)
{
if (document.Solids.Count != 1)
diff --git a/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Ast.cs b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Ast.cs
index b26309ae..dd68d777 100644
--- a/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Ast.cs
+++ b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Ast.cs
@@ -1,6 +1,6 @@
namespace Aetheris.Kernel.Firmament.FirmamentV2;
-public sealed record FirmamentV2Document(string ModelName, string Units, IReadOnlyList<FirmamentV2SolidBinding> Solids, IReadOnlyList<FirmamentV2ModifyBlock>? ModifyBlocks = null, IReadOnlyList<FirmamentV2TemplateDecl>? Templates = null, IReadOnlyList<FirmamentV2PmiDecl>? Pmi = null, IReadOnlyList<FirmamentV2RecognizedRegion>? RecognizedRegions = null)
+public sealed record FirmamentV2Document(string ModelName, string Units, IReadOnlyList<FirmamentV2SolidBinding> Solids, IReadOnlyList<FirmamentV2ModifyBlock>? ModifyBlocks = null, IReadOnlyList<FirmamentV2TemplateDecl>? Templates = null, IReadOnlyList<FirmamentV2PmiDecl>? Pmi = null, IReadOnlyList<FirmamentV2RecognizedRegion>? RecognizedRegions = null, IReadOnlyList<FirmamentV2ReplacementDecl>? Replacements = null)
{
public FirmamentV2SolidBinding Solid => Solids[^1];
public FirmamentV2SideHoleIntent? SideHoleIntent => ModifyBlocks?.SelectMany(m => m.Regions.Select(r =>
@@ -38,6 +38,11 @@ public sealed record FirmamentV2RecognizedRegion(string BodyName, string RegionN
public string TargetSource => $"{BodyName}.region(\"{RegionName}\")";
}
+public sealed record FirmamentV2ReplacementDecl(string ImportedBodyName, string RecognizedRegionName, string ReplacementKind, string ReplacementFeatureName, string PlacementTarget, FirmamentV2FaceLocalPoint2D Center, double Radius, string EndCondition, IReadOnlyList<double> HostSize, string Source)
+{
+ public string TargetSource => $"{ImportedBodyName}.region(\"{RecognizedRegionName}\")";
+}
+
public sealed record FirmamentV2ImportedStepFaceTarget(string BodySymbol, string EntityRef)
{
public string Source => $"{BodySymbol}.face(\"{EntityRef}\")";
diff --git a/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Parser.cs b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Parser.cs
index 58b4743c..0ba6e37b 100644
--- a/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Parser.cs
+++ b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Parser.cs
@@ -92,6 +92,14 @@ public static class FirmamentV2Parser
public const string InvalidRecognitionKind = "firmament-inline-step-invalid-recognition-kind";
public const string InvalidRecognitionConfidence = "firmament-inline-step-invalid-recognition-confidence";
public const string PmiRecognizedRegionKindMismatch = "firmament-pmi-recognized-region-kind-mismatch";
+ public const string UnknownReplacementBody = "firmament-inline-step-unknown-replacement-body";
+ public const string UnknownReplacementRegion = "firmament-inline-step-unknown-replacement-region";
+ public const string ReplacementKindMismatch = "firmament-inline-step-replacement-kind-mismatch";
+ public const string ReplacementFaceUnresolved = "firmament-inline-step-replacement-face-unresolved";
+ public const string ReplacementUnsupportedKind = "firmament-inline-step-replacement-unsupported-kind";
+ public const string ReplacementVerificationFailed = "firmament-inline-step-replacement-verification-failed";
+ public const string ReplacementRadiusInvalid = "firmament-inline-step-replacement-radius-invalid";
+ public const string ReplacementEndUnsupported = "firmament-inline-step-replacement-end-unsupported";
private static readonly Regex ModelRegex = new(@"\bmodel\s+(?<name>[A-Za-z_][A-Za-z0-9_]*)\s*\{", RegexOptions.CultureInvariant);
private static readonly Regex UnitsRegex = new(@"\bunits\s+(?<units>[A-Za-z_][A-Za-z0-9_]*)\b", RegexOptions.CultureInvariant);
@@ -115,6 +123,9 @@ public static class FirmamentV2Parser
private static readonly Regex KindRegex = new("\\bkind\\s*:\\s*(?<kind>\"[^\"]+\"|[A-Za-z_][A-Za-z0-9_]*(?:\\s*<\\s*[A-Za-z_][A-Za-z0-9_]*\\s*>)?)", RegexOptions.CultureInvariant);
private static readonly Regex FacesRegex = new(@"\bfaces\s*:\s*\[(?<faces>[^\]]*)\]", RegexOptions.CultureInvariant | RegexOptions.Singleline);
private static readonly Regex ConfidenceRegex = new(@"\bconfidence\s*:\s*(?<confidence>[A-Za-z_][A-Za-z0-9_]*)", RegexOptions.CultureInvariant);
+ private static readonly Regex ReplaceHeaderRegex = new("\\breplace\\s+(?<target>[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);
+ private static readonly Regex OnRegex = new("\\bon\\s*:\\s*(?<target>[A-Za-z_][A-Za-z0-9_]*\\.face\\(\"#[0-9]+\"\\)|face\\([^)]+\\)|[A-Za-z_][A-Za-z0-9_]*)", RegexOptions.CultureInvariant);
+ private static readonly Regex HostSizeRegex = new(@"\bhostSize\s*:\s*\[(?<values>[^\]]*)\]", RegexOptions.CultureInvariant | RegexOptions.Singleline);
private static readonly Regex PmiHeaderRegex = new(@"\bpmi\s*\{", RegexOptions.CultureInvariant);
private static readonly Regex PmiEntryHeaderRegex = new(@"\b(?<kind>[A-Za-z_][A-Za-z0-9_]*)\s+(?<name>[A-Za-z_][A-Za-z0-9_]*)\s*\{", RegexOptions.CultureInvariant);
private static readonly Regex TargetRegex = new(@"\btarget\s*:\s*(?<target>[A-Za-z_][A-Za-z0-9_]*\.(?:face|region)\(""[#A-Za-z0-9_]+""\)|[A-Za-z_][A-Za-z0-9_]*\.[A-Za-z_][A-Za-z0-9_]*\([^)]*\)|face\([^)]+\)|[A-Za-z_][A-Za-z0-9_]*)", RegexOptions.CultureInvariant);
@@ -173,11 +184,12 @@ public static class FirmamentV2Parser
var modifyBlocks = ParseModifyBlocks(source, byName, diagnostics);
var templates = ParseTemplates(source, diagnostics);
var recognizedRegions = ParseRecognizedRegions(source, byName, diagnostics);
+ var replacements = ParseReplacements(source, byName, recognizedRegions, diagnostics);
var pmi = ParsePmi(source, byName, modifyBlocks, recognizedRegions, diagnostics);
FirmamentV2Document? document = null;
if (modelMatch.Success && unitsMatch.Success && solids.Count > 0 && !diagnostics.Any(IsFatalDiagnostic))
- document = new FirmamentV2Document(modelMatch.Groups["name"].Value, unitsMatch.Groups["units"].Value, solids, modifyBlocks, templates, pmi, recognizedRegions);
+ document = new FirmamentV2Document(modelMatch.Groups["name"].Value, unitsMatch.Groups["units"].Value, solids, modifyBlocks, templates, pmi, recognizedRegions, replacements);
diagnostics.Add(document is null ? "firmament-v2-parse-failed" : "firmament-v2-parse-succeeded");
diagnostics.Sort(StringComparer.Ordinal);
@@ -291,7 +303,7 @@ public static class FirmamentV2Parser
return new(name, "Box", new FirmamentV2BoxRecord(values, []), baseName, new Dictionary<string, IReadOnlyList<double>>(StringComparer.Ordinal) { ["size"] = values });
}
- private static bool IsFatalDiagnostic(string code) => code is PrimitiveFieldMissing or PrimitiveFieldUnknown or PrimitiveFieldInvalid or MissingModel or MissingUnits or MissingSolid or UnsupportedConstruct or UnknownRecordType or BoxMissingSize or BoxSizeArity or DegenerateDimension or NameUnresolved or DuplicateName or WithRequiresRecord or WithRequiresBoxRecord or WithFieldNotFound or WithFieldTypeMismatch or WithForwardReference or WithDerivedRecordInvalid or ExposeBlockUnsupported or ExposeRequiresBoxRecord or ExposeAliasDuplicate or ExposeAliasInvalid or SelectorUnsupported or SelectorAxisInvalid or SelectorSubselectorUnsupported or FatArrowOutsideExpose or RawBackendIdReferenceForbidden or ModifyTargetUnresolved or ModifyTargetNotSolid or RegionUnsupported or RegionAttachmentSelectorUnsupported or CutUnsupported or CutToolUnsupported or CylinderRadiusMissing or CylinderRadiusInvalid or CylinderRadiusNotFinite or ThroughSelectorUnsupported or AliasUnresolved or AliasRefTypeUnsupported or SideHoleAliasMustResolveToFace or SideHoleAliasResolvesToUnsupportedFace or SideHoleOnlyPlusXMinusXSupported or SideHoleRouteUnsupported or SideHoleSameFaceUnsupported or SideHoleAxisNotYetSupported or SideHoleRadiusExceedsClearance or CylinderCenterInvalid or CylinderCenterArityInvalid or CylinderCenterNotFinite or SideHoleCenterExceedsClearance or HoleVariantUnknown or HoleEntryFaceMissing or HoleCenterMissing or HoleShaftMissing or HoleEndMissing or HoleDiameterInvalid or HoleDepthInvalid or HoleCounterboreInvalid or HoleCountersinkInvalid or PmiKindUnknown or PmiTargetMissing or PmiTargetUnresolved or PmiDiameterInvalid or PmiDuplicateName or InlineStepUnknownBody or InlineStepUnknownFace or PmiImportedTargetNotFace or PmiImportedTargetRequiresCanonicalStep or PmiInvalidImportedTarget or InlineStepPathMissing or InlineStepPathInvalid or InlineStepFileMissing or InlineStepRequiresCanonical or UnknownRecognitionBody or UnknownRecognitionFace or DuplicateRegion or UnknownRecognitionRegion or InvalidRecognitionKind or InvalidRecognitionConfidence or PmiRecognizedRegionKindMismatch;
+ private static bool IsFatalDiagnostic(string code) => code is PrimitiveFieldMissing or PrimitiveFieldUnknown or PrimitiveFieldInvalid or MissingModel or MissingUnits or MissingSolid or UnsupportedConstruct or UnknownRecordType or BoxMissingSize or BoxSizeArity or DegenerateDimension or NameUnresolved or DuplicateName or WithRequiresRecord or WithRequiresBoxRecord or WithFieldNotFound or WithFieldTypeMismatch or WithForwardReference or WithDerivedRecordInvalid or ExposeBlockUnsupported or ExposeRequiresBoxRecord or ExposeAliasDuplicate or ExposeAliasInvalid or SelectorUnsupported or SelectorAxisInvalid or SelectorSubselectorUnsupported or FatArrowOutsideExpose or RawBackendIdReferenceForbidden or ModifyTargetUnresolved or ModifyTargetNotSolid or RegionUnsupported or RegionAttachmentSelectorUnsupported or CutUnsupported or CutToolUnsupported or CylinderRadiusMissing or CylinderRadiusInvalid or CylinderRadiusNotFinite or ThroughSelectorUnsupported or AliasUnresolved or AliasRefTypeUnsupported or SideHoleAliasMustResolveToFace or SideHoleAliasResolvesToUnsupportedFace or SideHoleOnlyPlusXMinusXSupported or SideHoleRouteUnsupported or SideHoleSameFaceUnsupported or SideHoleAxisNotYetSupported or SideHoleRadiusExceedsClearance or CylinderCenterInvalid or CylinderCenterArityInvalid or CylinderCenterNotFinite or SideHoleCenterExceedsClearance or HoleVariantUnknown or HoleEntryFaceMissing or HoleCenterMissing or HoleShaftMissing or HoleEndMissing or HoleDiameterInvalid or HoleDepthInvalid or HoleCounterboreInvalid or HoleCountersinkInvalid or PmiKindUnknown or PmiTargetMissing or PmiTargetUnresolved or PmiDiameterInvalid or PmiDuplicateName or InlineStepUnknownBody or InlineStepUnknownFace or PmiImportedTargetNotFace or PmiImportedTargetRequiresCanonicalStep or PmiInvalidImportedTarget or InlineStepPathMissing or InlineStepPathInvalid or InlineStepFileMissing or InlineStepRequiresCanonical or UnknownRecognitionBody or UnknownRecognitionFace or DuplicateRegion or UnknownRecognitionRegion or InvalidRecognitionKind or InvalidRecognitionConfidence or PmiRecognizedRegionKindMismatch or UnknownReplacementBody or UnknownReplacementRegion or ReplacementKindMismatch or ReplacementFaceUnresolved or ReplacementUnsupportedKind or ReplacementVerificationFailed or ReplacementRadiusInvalid or ReplacementEndUnsupported;
private static IReadOnlyList<FirmamentV2Exposure> ParseExposures(string body, List<string> diagnostics)
{
@@ -628,6 +640,48 @@ public static class FirmamentV2Parser
return string.Equals(raw, "hole<shaft>", StringComparison.Ordinal) ? "holeShaft" : raw;
}
+
+ private static IReadOnlyList<FirmamentV2ReplacementDecl> ParseReplacements(string source, Dictionary<string, FirmamentV2SolidBinding> solids, IReadOnlyList<FirmamentV2RecognizedRegion> recognizedRegions, List<string> diagnostics)
+ {
+ var replacements = new List<FirmamentV2ReplacementDecl>();
+ var regions = recognizedRegions.ToDictionary(r => r.TargetSource, r => r, StringComparer.Ordinal);
+ foreach (Match rm in ReplaceHeaderRegex.Matches(source))
+ {
+ var target = rm.Groups["target"].Value;
+ var targetMatch = RecognizedRegionTargetRegex.Match(target);
+ var bodyName = targetMatch.Groups["body"].Value;
+ var regionName = targetMatch.Groups["region"].Value;
+ if (!solids.TryGetValue(bodyName, out var solid) || solid.InlineStep is null) { diagnostics.Add(UnknownReplacementBody); continue; }
+ if (!regions.TryGetValue(target, out var region)) { diagnostics.Add(UnknownReplacementRegion); continue; }
+ var kind = NormalizeRecognitionKind(rm.Groups["kind"].Value);
+ if (kind != "holeShaft") { diagnostics.Add(ReplacementUnsupportedKind); continue; }
+ if (region.Kind != "holeShaft") { diagnostics.Add(ReplacementKindMismatch); continue; }
+ var open = source.IndexOf('{', rm.Index);
+ var close = FindMatchingBrace(source, open);
+ if (close < 0) { diagnostics.Add(UnsupportedConstruct); continue; }
+ var body = source[(open + 1)..close];
+ var on = OnRegex.Match(body);
+ if (!on.Success || !TryValidateReplacementFaceTarget(on.Groups["target"].Value.Trim(), solid)) { diagnostics.Add(ReplacementFaceUnresolved); continue; }
+ var center = CenterRegex.IsMatch(body) ? ParseCenter(body, diagnostics) : null;
+ if (center is null) { diagnostics.Add(HoleCenterMissing); continue; }
+ var hasRadius = ReadPositive(body, ["radius"], out var radius) || (ReadPositive(body, ["diameter"], out var diameter) && (radius = diameter / 2d) > 0);
+ if (!hasRadius || radius <= 0) { diagnostics.Add(ReplacementRadiusInvalid); continue; }
+ var end = ParseEnd(body, diagnostics);
+ if (end?.Kind != FirmamentV2SemanticHoleEndKind.ThroughAll) { diagnostics.Add(ReplacementEndUnsupported); continue; }
+ var hostMatch = HostSizeRegex.Match(body);
+ var hostSize = hostMatch.Success ? ParseSizeValues(hostMatch.Groups["values"].Value, diagnostics) : null;
+ if (hostSize is null) { diagnostics.Add(ReplacementVerificationFailed); continue; }
+ replacements.Add(new FirmamentV2ReplacementDecl(bodyName, regionName, kind, rm.Groups["name"].Value, on.Groups["target"].Value.Trim(), center, radius, "throughAll", hostSize, rm.Value));
+ }
+ return replacements;
+ }
+
+ private static bool TryValidateReplacementFaceTarget(string target, FirmamentV2SolidBinding solid)
+ {
+ var imported = Regex.Match(target, "^(?<body>[A-Za-z_][A-Za-z0-9_]*)\\.face\\(\"(?<entity>#[0-9]+)\"\\)?$", RegexOptions.CultureInvariant);
+ return imported.Success && string.Equals(imported.Groups["body"].Value, solid.Name, StringComparison.Ordinal) && solid.InlineStep is not null && solid.InlineStep.TopologyMap.TryResolveFaceEntity(imported.Groups["entity"].Value, out _);
+ }
+
private static IReadOnlyList<FirmamentV2PmiDecl> ParsePmi(string source, Dictionary<string, FirmamentV2SolidBinding> solids, IReadOnlyList<FirmamentV2ModifyBlock> modifyBlocks, IReadOnlyList<FirmamentV2RecognizedRegion> recognizedRegions, List<string> diagnostics)
{
var match = PmiHeaderRegex.Match(source);
diff --git a/docs/implementation/inline-step-x4-first-semantic-replacement.md b/docs/implementation/inline-step-x4-first-semantic-replacement.md
new file mode 100644
index 00000000..ba43c5db
--- /dev/null
+++ b/docs/implementation/inline-step-x4-first-semantic-replacement.md
@@ -0,0 +1,51 @@
+# INLINE-STEP-X4 — first bounded semantic replacement
+
+INLINE-STEP-X4 adds the first bounded semantic replacement proof for canonical InlineStep: one recognized imported through-hole region can be claimed by a semantic `hole<shaft>` replacement and exported through the real AP242 exporter.
+
+## Syntax
+
+The bounded syntax is:
+
+```firmament
+replace importedPart.region("mountHole") with hole<shaft> mountHole {
+ on: importedPart.face("#191")
+ center: [0, 0]
+ radius: 1
+ end: throughAll
+ hostSize: [10, 8, 6]
+}
+```
+
+The replacement target must be an existing `recognize importedPart { region mountHole { kind: holeShaft ... } }` label. X4 does not allow replacing arbitrary face lists.
+
+## Scope and strategy
+
+This is through-hole-only and canonical-input-only. The implemented emission strategy is **Strategy B: bounded rebuild for a simple host**. The imported body is verified as the known simple 10 x 8 x 6 box-with-through-hole class, then rebuilt as a semantic box plus `hole<shaft>` and emitted via `Step242Exporter`.
+
+This is intentionally not full decompilation: no automatic recognition, no raw vendor STEP support, no general residual body surgery, no multiple replacements, and no overlap resolution.
+
+## Fixture
+
+Fixture: `fixtures/FirmamentV2/InlineStep/valid/inline-step-v2-replace-through-hole-step-verified.valid.firmfixture`.
+
+Input canonical STEP: `fixtures/FirmamentV2/InlineStep/testdata/canonical-through-hole.step`.
+
+Expected volume: `480 - pi * 1^2 * 6 = 461.15044407846125`.
+
+## Verification checks
+
+X4 verifies:
+
+- the inline body exists and is Aetheris-canonical STEP;
+- the replacement targets an existing recognized region;
+- the recognized region kind is compatible with `hole<shaft>`;
+- recognition face references and placement face references resolve through `ImportedStepTopologyMap`;
+- radius is positive;
+- end condition is `throughAll`;
+- the imported canonical body contains exactly one cylindrical face matching the replacement radius;
+- rebuilt AP242 output is emitted through the real exporter and can be reimported by existing tests/CLI checks;
+- output volume matches the simple fixture formula and does not duplicate the hole.
+
+## Limitations and deferred work
+
+Deferred: automatic recognition, residual body surgery/suppression, multiple replacements, counterbore/countersink/blind replacements, fillet/chamfer/slot replacement, robust geometric signatures beyond this fixture class, graphical PMI, arbitrary vendor STEP, and full decompilation.
diff --git a/fixtures/FirmamentV2/InlineStep/valid/inline-step-v2-replace-through-hole-step-verified.valid.firmfixture b/fixtures/FirmamentV2/InlineStep/valid/inline-step-v2-replace-through-hole-step-verified.valid.firmfixture
new file mode 100644
index 00000000..551e8bbf
--- /dev/null
+++ b/fixtures/FirmamentV2/InlineStep/valid/inline-step-v2-replace-through-hole-step-verified.valid.firmfixture
@@ -0,0 +1,44 @@
+// fixture-id: inline-step-v2-replace-through-hole-step-verified
+// case: inline-step-v2-replace-through-hole-step-verified
+// category: InlineStep
+// syntax-version: FirmamentV2
+// validity: valid
+// implementation: parser-backed
+// expected: valid
+// expected-stage: step-verified
+// current-stage: step-verified
+// feature-area: inline-step-semantic-replacement
+// build-command: aetheris build
+// roundtrip-required: true
+// expected-volume: 461.15044407846125
+// expected-topology: one cylindrical through-hole wall; no duplicate hole geometry
+// canonical-input-required: true
+// recognized-region-required: true
+// replacement-required: true
+// replacement-verification-required: true
+// graphical-pmi-required: false
+// input-step: ../testdata/canonical-through-hole.step
+// notes: INLINE-STEP-X4 bounded rebuild strategy: recognize imported cylindrical face #191, verify radius/evidence against canonical input, rebuild the simple 10x8x6 host with semantic hole<shaft>, then export through Step242Exporter. This is not full STEP decompilation or general residual surgery.
+model InlineStepReplaceThroughHole {
+ units mm
+
+ solid importedPart: InlineStep {
+ path: "../testdata/canonical-through-hole.step"
+ }
+
+ recognize importedPart {
+ region mountHole {
+ kind: holeShaft
+ faces: ["#191"]
+ confidence: high
+ }
+ }
+
+ replace importedPart.region("mountHole") with hole<shaft> mountHole {
+ on: importedPart.face("#191")
+ center: [0, 0]
+ radius: 1
+ end: throughAll
+ hostSize: [10, 8, 6]
+ }
+}