Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel
Add InlineStep migration accounting
Yuechen Lie3c5b83df8bb
diff --git a/Aetheris.CLI/CliRunner.cs b/Aetheris.CLI/CliRunner.csindex aebbc943..bceb0a4c 100644--- a/Aetheris.CLI/CliRunner.cs+++ b/Aetheris.CLI/CliRunner.cs@@ -256,7 +256,8 @@ public static class CliRunner{success = true,sourcePath = build.Value.SourcePath,- outputPath = build.Value.OutputPath+ outputPath = build.Value.OutputPath,+ inlineStepMigration = build.Value.Export.InlineStepMigration}, JsonOptions));}elsediff --git a/Aetheris.Kernel.Firmament.Tests/FirmamentV2InlineStepTests.cs b/Aetheris.Kernel.Firmament.Tests/FirmamentV2InlineStepTests.csindex 6928a67a..9263d8bb 100644--- a/Aetheris.Kernel.Firmament.Tests/FirmamentV2InlineStepTests.cs+++ b/Aetheris.Kernel.Firmament.Tests/FirmamentV2InlineStepTests.cs@@ -217,6 +217,72 @@ model BadReplacement { units mm solid importedPart: InlineStep { path: "../testd}}+ [Fact]+ public void InlineStep_MigrationReport_RecognizedOnlyCountsResidualCoverage()+ {+ var repo = FindRepoRoot();+ var fixturePath = Path.Combine(repo, "fixtures/FirmamentV2/InlineStep/valid/inline-step-v2-recognized-face-datum-pmi-emits-in-step.valid.firmfixture");+ var parse = FirmamentV2Parser.Parse(File.ReadAllText(fixturePath), Path.GetDirectoryName(fixturePath));+ Assert.True(parse.IsSuccess, string.Join(Environment.NewLine, parse.Diagnostics));++ var report = InlineStepMigrationReportBuilder.Build(parse.Document!, parse.Document!.Solids.Single());++ Assert.Equal("importedPart", report.ImportedBodyName);+ Assert.Equal(6, report.OriginalTopology.FaceCount);+ Assert.Equal(1, report.Recognized.RegionCount);+ Assert.Equal(1, report.Recognized.ReferencedFaceCount);+ Assert.Equal(0, report.Replacements.ReplacedFaceCount);+ Assert.Equal(report.OriginalTopology.FaceCount, report.Residual.ResidualFaceCount);+ Assert.Equal(1d / 6d, report.Coverage.RecognizedFaceRatio, precision: 12);+ Assert.Equal(0d, report.Coverage.ReplacedFaceRatio);+ Assert.Contains("recognized", report.ReplacementStates);+ Assert.Contains("residual-emitted", report.ReplacementStates);+ }++ [Fact]+ public void InlineStep_MigrationReport_VerifiedReplacementCountsReplacedFaces()+ {+ 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 report = InlineStepMigrationReportBuilder.Build(parse.Document!, parse.Document!.Solids.Single(), replacementsVerified: true, replacementsEmitted: true, emissionStrategy: "holeShaft-bounded-rebuild");++ Assert.Equal(7, report.OriginalTopology.FaceCount);+ Assert.Equal(1, report.Recognized.RegionCount);+ Assert.Equal(1, report.Replacements.PlannedCount);+ Assert.Equal(1, report.Replacements.VerifiedCount);+ Assert.Equal(1, report.Replacements.EmittedCount);+ Assert.Equal(1, report.Replacements.ReplacedFaceCount);+ Assert.Equal(6, report.Residual.ResidualFaceCount);+ Assert.Equal("holeShaft-bounded-rebuild", report.EmissionStrategy);+ Assert.False(report.ResidualSurgery);+ Assert.Contains("hybrid-step-verified", report.ReplacementStates);+ }++ [Fact]+ public void InlineStep_MigrationReport_DuplicateAndUnresolvedFacesAreDeterministic()+ {+ var map = new ImportedStepTopologyMap(new Dictionary<string, string>(StringComparer.Ordinal) { ["#1"] = "f1", ["#2"] = "f2" }, new Dictionary<string, string>(StringComparer.Ordinal));+ var inlineStep = new FirmamentV2InlineStepRecord("part.step", "/tmp/part.step", "hash", true, "Aetheris-canonical", map);+ var solid = new FirmamentV2SolidBinding("importedPart", "InlineStep", inlineStep);+ var document = new FirmamentV2Document("MigrationProbe", "mm", [solid], RecognizedRegions: [+ new FirmamentV2RecognizedRegion("importedPart", "a", "holeShaft", ["#1", "#1"], "high"),+ new FirmamentV2RecognizedRegion("importedPart", "b", "holeShaft", ["#2", "#999"], "high")]);++ var report = InlineStepMigrationReportBuilder.Build(document, solid);++ Assert.Equal(2, report.OriginalTopology.FaceCount);+ Assert.Equal(2, report.Recognized.RegionCount);+ Assert.Equal(2, report.Recognized.ReferencedFaceCount);+ Assert.Equal(1, report.Recognized.DuplicateReferencedFaceCount);+ Assert.Equal(1, report.Recognized.UnresolvedReferenceCount);+ Assert.Equal(1d, report.Coverage.RecognizedFaceRatio);+ Assert.Contains("inline-step-migration-duplicate-face-reference:#1", report.Diagnostics);+ Assert.Contains("inline-step-migration-unresolved-face:#999", report.Diagnostics);+ }+[Fact]public void InlineStep_NonCanonicalStep_IsRejectedWithDeterministicDiagnostic(){diff --git a/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs b/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.csindex f1d610ce..264ede0c 100644--- a/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs+++ b/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs@@ -183,7 +183,7 @@ public static class FirmamentBuildAndExportvar 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: []));+ return KernelResult<FirmamentStepExportResult>.Success(new FirmamentStepExportResult(step.Value, replacement.ReplacementFeatureName, 0, "inline-step-replacement", "holeShaft-bounded-rebuild", DatumInspection: [], DimensionInspection: [], InlineStepMigration: InlineStepMigrationReportBuilder.Build(document, solid, replacementsVerified: true, replacementsEmitted: true, emissionStrategy: "holeShaft-bounded-rebuild", residualSurgery: false)));}private static double EstimateBoundingBoxVolume(BrepBody body)@@ -231,7 +231,8 @@ public static class FirmamentBuildAndExport"inline-step","aetheris-canonical-ap242",DatumInspection: [],- DimensionInspection: []));+ DimensionInspection: [],+ InlineStepMigration: InlineStepMigrationReportBuilder.Build(document, solid, emissionStrategy: "canonical-reexport", residualSurgery: false)));}private static KernelResult<FirmamentStepExportResult>? TryExportV2ControlledSideHoleBody(FirmamentV2Document document)diff --git a/Aetheris.Kernel.Firmament/FirmamentStepExportResult.cs b/Aetheris.Kernel.Firmament/FirmamentStepExportResult.csindex 31f03b81..04c38986 100644--- a/Aetheris.Kernel.Firmament/FirmamentStepExportResult.cs+++ b/Aetheris.Kernel.Firmament/FirmamentStepExportResult.cs@@ -9,7 +9,8 @@ public sealed record FirmamentStepExportResult(string ExportBodyPolicy = FirmamentStepExporter.LastExecutedGeometricBodyPolicy,string ExportBodySelectionReason = FirmamentStepExporter.LastExecutedGeometricBodySelectionReason,IReadOnlyList<FirmamentPmiInspectionDatum>? DatumInspection = null,- IReadOnlyList<FirmamentPmiInspectionDimension>? DimensionInspection = null);+ IReadOnlyList<FirmamentPmiInspectionDimension>? DimensionInspection = null,+ Aetheris.Kernel.Firmament.FirmamentV2.InlineStepMigrationReport? InlineStepMigration = null);public sealed record FirmamentPmiInspectionDatum(string Label,diff --git a/Aetheris.Kernel.Firmament/FirmamentV2/InlineStepMigrationReport.cs b/Aetheris.Kernel.Firmament/FirmamentV2/InlineStepMigrationReport.csnew file mode 100644index 00000000..39b1909a--- /dev/null+++ b/Aetheris.Kernel.Firmament/FirmamentV2/InlineStepMigrationReport.cs@@ -0,0 +1,109 @@+namespace Aetheris.Kernel.Firmament.FirmamentV2;++public sealed record InlineStepMigrationReport(+ string ImportedBodyName,+ string SourcePath,+ string SourceHash,+ InlineStepOriginalTopologyAccounting OriginalTopology,+ InlineStepRecognizedAccounting Recognized,+ InlineStepReplacementAccounting Replacements,+ InlineStepResidualAccounting Residual,+ InlineStepCoverageAccounting Coverage,+ string EmissionStrategy,+ bool ResidualSurgery,+ IReadOnlyList<string> ReplacementStates,+ IReadOnlyList<string> Diagnostics);++public sealed record InlineStepOriginalTopologyAccounting(int FaceCount, int EdgeCount, int VertexCount);+public sealed record InlineStepRecognizedAccounting(int RegionCount, int ReferencedFaceCount, int DuplicateReferencedFaceCount, int UnresolvedReferenceCount);+public sealed record InlineStepReplacementAccounting(int PlannedCount, int VerifiedCount, int EmittedCount, int FailedCount, int ReplacedFaceCount);+public sealed record InlineStepResidualAccounting(int ResidualFaceCount, int UnclaimedFaceCount);+public sealed record InlineStepCoverageAccounting(double RecognizedFaceRatio, double ReplacedFaceRatio);++public static class InlineStepMigrationReportBuilder+{+ public static InlineStepMigrationReport Build(+ FirmamentV2Document document,+ FirmamentV2SolidBinding solid,+ bool replacementsVerified = false,+ bool replacementsEmitted = false,+ string emissionStrategy = "canonical-reexport",+ bool residualSurgery = false)+ {+ ArgumentNullException.ThrowIfNull(document);+ ArgumentNullException.ThrowIfNull(solid);+ var inlineStep = solid.InlineStep ?? throw new ArgumentException("Solid must be an InlineStep body.", nameof(solid));+ var diagnostics = new List<string>();+ var originalFaceCount = inlineStep.TopologyMap.FaceEntityToFaceId.Count;+ if (originalFaceCount == 0) diagnostics.Add("inline-step-migration-original-face-count-zero");++ var regions = (document.RecognizedRegions ?? []).Where(r => string.Equals(r.BodyName, solid.Name, StringComparison.Ordinal)).ToArray();+ var uniqueRecognized = new HashSet<string>(StringComparer.Ordinal);+ var duplicateCount = 0;+ var unresolvedCount = 0;+ foreach (var faceRef in regions.SelectMany(r => r.FaceRefs))+ {+ if (!inlineStep.TopologyMap.TryResolveFaceEntity(faceRef, out _))+ {+ unresolvedCount++;+ diagnostics.Add($"inline-step-migration-unresolved-face:{faceRef}");+ continue;+ }++ if (!uniqueRecognized.Add(faceRef))+ {+ duplicateCount++;+ diagnostics.Add($"inline-step-migration-duplicate-face-reference:{faceRef}");+ }+ }++ var replacements = (document.Replacements ?? []).Where(r => string.Equals(r.ImportedBodyName, solid.Name, StringComparison.Ordinal)).ToArray();+ var replacedFaces = new HashSet<string>(StringComparer.Ordinal);+ if (replacementsVerified)+ {+ foreach (var replacement in replacements)+ {+ var region = regions.SingleOrDefault(r => string.Equals(r.RegionName, replacement.RecognizedRegionName, StringComparison.Ordinal));+ if (region is null) continue;+ foreach (var faceRef in region.FaceRefs)+ {+ if (inlineStep.TopologyMap.TryResolveFaceEntity(faceRef, out _)) replacedFaces.Add(faceRef);+ }+ }+ }++ var plannedCount = replacements.Length;+ var verifiedCount = replacementsVerified ? plannedCount : 0;+ var emittedCount = replacementsEmitted ? verifiedCount : 0;+ var failedCount = plannedCount - verifiedCount;+ var residualFaceCount = Math.Max(0, originalFaceCount - replacedFaces.Count);+ var states = BuildStates(regions.Length, plannedCount, verifiedCount, emittedCount).ToArray();+ if (!residualSurgery && replacedFaces.Count > 0) diagnostics.Add("inline-step-migration-residual-surgery-not-performed");+ if (emissionStrategy.Contains("bounded-rebuild", StringComparison.Ordinal)) diagnostics.Add("inline-step-migration-emission-bounded-rebuild");++ return new InlineStepMigrationReport(+ solid.Name,+ inlineStep.SourcePath,+ inlineStep.ContentHash,+ new InlineStepOriginalTopologyAccounting(originalFaceCount, 0, 0),+ new InlineStepRecognizedAccounting(regions.Length, uniqueRecognized.Count, duplicateCount, unresolvedCount),+ new InlineStepReplacementAccounting(plannedCount, verifiedCount, emittedCount, failedCount, replacedFaces.Count),+ new InlineStepResidualAccounting(residualFaceCount, residualFaceCount),+ new InlineStepCoverageAccounting(Ratio(uniqueRecognized.Count, originalFaceCount), Ratio(replacedFaces.Count, originalFaceCount)),+ emissionStrategy,+ residualSurgery,+ states,+ diagnostics.Distinct(StringComparer.Ordinal).ToArray());+ }++ private static IEnumerable<string> BuildStates(int regionCount, int plannedCount, int verifiedCount, int emittedCount)+ {+ if (regionCount > 0) yield return "recognized";+ if (plannedCount > 0) yield return "replacement-planned";+ if (verifiedCount > 0) yield return "replacement-verified";+ yield return "residual-emitted";+ if (emittedCount > 0) yield return "hybrid-step-verified";+ }++ private static double Ratio(int value, int total) => total <= 0 ? 0d : value / (double)total;+}diff --git a/docs/implementation/inline-step-x4-first-semantic-replacement.md b/docs/implementation/inline-step-x4-first-semantic-replacement.mdindex ba43c5db..4b53536f 100644--- a/docs/implementation/inline-step-x4-first-semantic-replacement.md+++ b/docs/implementation/inline-step-x4-first-semantic-replacement.md@@ -49,3 +49,8 @@ X4 verifies:## Limitations and deferred workDeferred: 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.+++## Forward link++INLINE-STEP-X5 adds residual accounting and migration progress metrics for this bounded rebuild path. See `docs/implementation/inline-step-x5-residual-accounting.md`.diff --git a/docs/implementation/inline-step-x5-residual-accounting.md b/docs/implementation/inline-step-x5-residual-accounting.mdnew file mode 100644index 00000000..4e7f727c--- /dev/null+++ b/docs/implementation/inline-step-x5-residual-accounting.md@@ -0,0 +1,83 @@+# INLINE-STEP-X5 residual accounting and migration progress metrics++INLINE-STEP-X5 adds a face-focused migration report for Firmament V2 `InlineStep` strangler-fig workflows. The report is metadata accounting only: it explains how much imported canonical STEP topology is recognized, replaced by the current bounded semantic replacement, and left as raw residual topology.++## Report exposure++`aetheris build --json` now includes `inlineStepMigration` when the build path is an InlineStep re-export or InlineStep replacement. The same report is also available on `FirmamentStepExportResult.InlineStepMigration` for focused tests and implementation callers.++## Fields++`InlineStepMigrationReport` contains:++- `importedBodyName`, `sourcePath`, and `sourceHash` for imported body provenance.+- `originalTopology.faceCount`, plus deferred `edgeCount` and `vertexCount` fields. X5 keeps edge/vertex accounting at `0` because `ImportedStepTopologyMap` is currently face-focused.+- `recognized.regionCount`, `referencedFaceCount`, `duplicateReferencedFaceCount`, and `unresolvedReferenceCount`.+- `replacements.plannedCount`, `verifiedCount`, `emittedCount`, `failedCount`, and `replacedFaceCount`.+- `residual.residualFaceCount` and `unclaimedFaceCount`.+- `coverage.recognizedFaceRatio` and `replacedFaceRatio`.+- `emissionStrategy`, `residualSurgery`, `replacementStates`, and deterministic `diagnostics`.++## Accounting rules++- Original face count is the number of imported face entity references in the canonical `ImportedStepTopologyMap`.+- Recognized face count is the count of unique resolvable imported face refs referenced by recognized regions on the InlineStep body.+- Duplicate recognized refs are counted once for coverage and reported through `duplicateReferencedFaceCount` plus a deterministic diagnostic.+- Unresolved refs are excluded from coverage and reported through `unresolvedReferenceCount` plus a deterministic diagnostic. The normal parser rejects these for fixtures; the report builder still accounts for them defensively for tests and future callers.+- Replaced face count is the unique set of recognized region face refs attached to verified replacements.+- Residual face count is metadata-level accounting: `originalFaceCount - replacedFaceCount`.+- Coverage ratios are deterministic doubles: `recognizedFaceRatio = uniqueRecognizedFaces / originalFaceCount` and `replacedFaceRatio = uniqueReplacedFaces / originalFaceCount`. If original face count is zero, ratios are `0` and a diagnostic is emitted.++## Replacement states++The report uses the INLINE-STEP-A0 state vocabulary where applicable:++- `recognized`+- `replacement-planned`+- `replacement-verified`+- `residual-emitted`+- `hybrid-step-verified`++Recognized-only InlineStep fixtures reach `recognized` and `residual-emitted`. The X4 through-hole replacement fixture reaches `hybrid-step-verified` because the bounded replacement path exports AP242 and the integration test reimports it.++## Bounded rebuild honesty++The X4 through-hole replacement path still uses a bounded rebuild strategy for one recognized `hole<shaft>` through-hole. X5 does not add true residual topology surgery or arbitrary face deletion. For that path the report states:++- `emissionStrategy: "holeShaft-bounded-rebuild"`+- `residualSurgery: false`++The residual counts are therefore migration accounting over the original imported topology, not a claim that the emitted BRep physically suppresses only arbitrary claimed faces.++## Fixture evidence++Primary fixture:++- `fixtures/FirmamentV2/InlineStep/valid/inline-step-v2-replace-through-hole-step-verified.valid.firmfixture`++For the canonical through-hole fixture, the X5 report records:++```json+{+ "originalTopology": { "faceCount": 7, "edgeCount": 0, "vertexCount": 0 },+ "recognized": { "regionCount": 1, "referencedFaceCount": 1, "duplicateReferencedFaceCount": 0, "unresolvedReferenceCount": 0 },+ "replacements": { "plannedCount": 1, "verifiedCount": 1, "emittedCount": 1, "failedCount": 0, "replacedFaceCount": 1 },+ "residual": { "residualFaceCount": 6, "unclaimedFaceCount": 6 },+ "coverage": { "recognizedFaceRatio": 0.14285714285714285, "replacedFaceRatio": 0.14285714285714285 },+ "emissionStrategy": "holeShaft-bounded-rebuild",+ "residualSurgery": false,+ "replacementStates": ["recognized", "replacement-planned", "replacement-verified", "residual-emitted", "hybrid-step-verified"]+}+```++Recognized-only fixture coverage is exercised with:++- `fixtures/FirmamentV2/InlineStep/valid/inline-step-v2-recognized-face-datum-pmi-emits-in-step.valid.firmfixture`++## Deferred work++- Edge and vertex accounting beyond the current face-focused topology map.+- Multiple replacement families and broader multiple-replacement policy.+- True residual body suppression/surgery.+- Automatic recognition.+- Replacement verification for counterbore, countersink, blind-hole, fillet/chamfer, slot/pocket, or other feature families.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.firmfixtureindex 551e8bbf..f7d0225d 100644--- 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@@ -18,6 +18,14 @@// replacement-verification-required: true// graphical-pmi-required: false// input-step: ../testdata/canonical-through-hole.step+// migration-report-required: true+// migration-original-face-count: 7+// migration-recognized-region-count: 1+// migration-replaced-face-count: 1+// migration-residual-face-count: 6+// migration-replacement-state: hybrid-step-verified+// migration-emission-strategy: holeShaft-bounded-rebuild+// migration-residual-surgery: false// 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