Skip to content

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.cs
index 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));
}
else
diff --git a/Aetheris.Kernel.Firmament.Tests/FirmamentV2InlineStepTests.cs b/Aetheris.Kernel.Firmament.Tests/FirmamentV2InlineStepTests.cs
index 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.cs
index f1d610ce..264ede0c 100644
--- a/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs
+++ b/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs
@@ -183,7 +183,7 @@ public static class FirmamentBuildAndExport
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: []));
+ 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.cs
index 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.cs
new file mode 100644
index 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.md
index 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 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.
+
+
+## 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.md
new file mode 100644
index 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.firmfixture
index 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