Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Complete A3.1 stepped execution strategy diagnostics

Yuechen Li0d0b2e90681b
diff --git a/Aetheris.FrictionLab.Tests/CIRLab/SteppedHoleExecutionArchitectureLabTests.cs b/Aetheris.FrictionLab.Tests/CIRLab/SteppedHoleExecutionArchitectureLabTests.cs
index ba5da54e..3c25c9cb 100644
--- a/Aetheris.FrictionLab.Tests/CIRLab/SteppedHoleExecutionArchitectureLabTests.cs
+++ b/Aetheris.FrictionLab.Tests/CIRLab/SteppedHoleExecutionArchitectureLabTests.cs
@@ -4,17 +4,38 @@ namespace Aetheris.FrictionLab.Tests.CIRLab;
public class SteppedHoleExecutionArchitectureLabTests
{
+ private static readonly string[] AllowedRecommendations = ["repeated-subtract-production", "unioned-tool-production", "n-level-builder-production", "profile-stack-tool-builder-production", "keep-deferred"];
+
+ private static readonly string[] RequiredStrategies =
+ [
+ "repeated-subtract-small-medium-large",
+ "repeated-subtract-large-medium-small",
+ "repeated-subtract-medium-large-small",
+ "unioned-tool-single-subtract",
+ "n-level-builder-analysis",
+ "profile-stack-tool-builder-analysis",
+ "deferred-baseline-current-production",
+ "counterbore-baseline"
+ ];
+
[Fact]
public void SteppedArchitectureLab_ProducesStrategyMatrix()
{
var report = SteppedHoleExecutionArchitectureLab.RunCanonicalSteppedScenario();
- Assert.Contains(report.Strategies, s => s.Strategy == "repeated-subtract-small-medium-large");
- Assert.Contains(report.Strategies, s => s.Strategy == "repeated-subtract-large-medium-small");
- Assert.Contains(report.Strategies, s => s.Strategy == "repeated-subtract-medium-large-small");
- Assert.Contains(report.Strategies, s => s.Strategy == "unioned-tool-single-subtract");
- Assert.Contains(report.Strategies, s => s.Strategy == "n-level-builder-analysis");
- Assert.Contains(report.Strategies, s => s.Strategy == "profile-stack-tool-builder-analysis");
- Assert.Contains(report.Strategies, s => s.Strategy == "deferred-baseline-current-production");
+ Assert.All(RequiredStrategies, strategy => Assert.Contains(report.Strategies, s => s.Strategy == strategy));
+ }
+
+ [Fact]
+ public void SteppedArchitectureLab_ReportMatrixContainsConcreteStatuses()
+ {
+ var report = SteppedHoleExecutionArchitectureLab.RunCanonicalSteppedScenario();
+ foreach (var strategy in RequiredStrategies)
+ {
+ var row = report.Strategies.Single(s => s.Strategy == strategy);
+ Assert.True(Enum.IsDefined(row.Status));
+ Assert.False(string.IsNullOrWhiteSpace(row.FailureStage));
+ Assert.False(string.IsNullOrWhiteSpace(row.FailureCode));
+ }
}
[Fact]
@@ -64,6 +85,67 @@ public class SteppedHoleExecutionArchitectureLabTests
public void SteppedArchitectureLab_RecommendationIsExplicit()
{
var r = SteppedHoleExecutionArchitectureLab.RunCanonicalSteppedScenario().Recommendation;
- Assert.Contains(r, new[] { "repeated-subtract-production", "unioned-tool-production", "n-level-builder-production", "profile-stack-tool-builder-production", "keep-deferred" });
+ Assert.False(string.IsNullOrWhiteSpace(r));
+ Assert.Contains(r, AllowedRecommendations);
+ }
+
+ [Fact]
+ public void SteppedArchitectureLab_SelectedRecommendationIsExplicit()
+ {
+ var recommendation = SteppedHoleExecutionArchitectureLab.RunCanonicalSteppedScenario().Recommendation;
+ Assert.False(string.IsNullOrWhiteSpace(recommendation));
+ Assert.Contains(recommendation, AllowedRecommendations);
+ }
+
+ [Fact]
+ public void SteppedArchitectureLab_UnionedToolRowHasConcreteOutcome()
+ {
+ var row = SteppedHoleExecutionArchitectureLab.RunCanonicalSteppedScenario().Strategies.Single(s => s.Strategy == "unioned-tool-single-subtract");
+ Assert.True(row.Status is SteppedArchitectureStrategyStatus.Succeeded or SteppedArchitectureStrategyStatus.Failed or SteppedArchitectureStrategyStatus.Skipped);
+ Assert.False(string.IsNullOrWhiteSpace(row.FailureStage));
+ Assert.False(string.IsNullOrWhiteSpace(row.FailureCode));
+ if (row.Status is SteppedArchitectureStrategyStatus.Skipped)
+ {
+ Assert.NotEmpty(row.Diagnostics);
+ }
+ }
+
+ [Fact]
+ public void SteppedArchitectureLab_RepeatedSubtractRowsHavePerOrderOutcomes()
+ {
+ var rows = SteppedHoleExecutionArchitectureLab.RunCanonicalSteppedScenario().Strategies
+ .Where(s => s.Strategy.StartsWith("repeated-subtract-", StringComparison.Ordinal))
+ .ToArray();
+
+ Assert.Equal(3, rows.Length);
+ Assert.Equal(3, rows.Select(r => r.Strategy).Distinct(StringComparer.Ordinal).Count());
+ Assert.All(rows, row =>
+ {
+ Assert.True(row.Status is SteppedArchitectureStrategyStatus.Succeeded or SteppedArchitectureStrategyStatus.Failed);
+ Assert.False(string.IsNullOrWhiteSpace(row.FailureStage));
+ Assert.False(string.IsNullOrWhiteSpace(row.FailureCode));
+ });
+ }
+
+ [Fact]
+ public void SteppedArchitectureLab_CounterboreBaselineOutcomePresent()
+ {
+ var row = SteppedHoleExecutionArchitectureLab.RunCanonicalSteppedScenario().Strategies.Single(s => s.Strategy == "counterbore-baseline");
+ Assert.True(row.Status is SteppedArchitectureStrategyStatus.Succeeded or SteppedArchitectureStrategyStatus.Failed);
+ Assert.False(string.IsNullOrWhiteSpace(row.FailureStage));
+ Assert.False(string.IsNullOrWhiteSpace(row.FailureCode));
+ }
+
+ [Fact]
+ public void SteppedArchitectureLab_ReportIsDecisionGrade()
+ {
+ var report = SteppedHoleExecutionArchitectureLab.RunCanonicalSteppedScenario();
+ var bannedVagueTerms = new[] { "represented", "compared", "analyzed" };
+ foreach (var strategy in RequiredStrategies)
+ {
+ var row = report.Strategies.Single(s => s.Strategy == strategy);
+ var rowText = string.Join("|", row.RecommendedNextStep, row.FailureCode, row.FailureStage, string.Join(";", row.Diagnostics)).ToLowerInvariant();
+ Assert.DoesNotContain(bannedVagueTerms, term => rowText.Contains(term, StringComparison.Ordinal));
+ }
}
}
diff --git a/docs/frictionlab/brep-boolean-stack-a3-stepped-execution-architecture-lab.md b/docs/frictionlab/brep-boolean-stack-a3-stepped-execution-architecture-lab.md
index ee6d34da..7349e6fd 100644
--- a/docs/frictionlab/brep-boolean-stack-a3-stepped-execution-architecture-lab.md
+++ b/docs/frictionlab/brep-boolean-stack-a3-stepped-execution-architecture-lab.md
@@ -1,21 +1,19 @@
-# BREP-BOOLEAN-STACK-A3: stepped-hole execution architecture lab
+# BREP-BOOLEAN-STACK-A3: stepped-hole execution architecture lab (A3.1 diagnostic completion)
## 1) Purpose and scope
FrictionLab-only architecture experiment to compare stepped-hole execution strategies without changing production executor behavior.
-## 2) Code inspected
-- `HoleRecoveryPolicy`, `SteppedHoleVariant`, `HoleRecoveryPlan`, `HoleRecoveryExecutor`.
-- `BrepBoolean`, `BrepBoolean.Subtract/Union/Intersect`, `BrepBooleanSafeComposition`, graph validator/family/builders.
-- `BrepPrimitives.CreateBox/CreateCylinder`, `Step242Exporter.ExportBody`.
-
-## 3) Candidate strategies tested
-- Hypothesis A: repeated subtract order variants.
-- Hypothesis B: unioned tool then single subtract.
-- Hypothesis C: direct N-level builder feasibility analysis.
-- Hypothesis D: profile-stack tool-builder feasibility analysis.
-- Hypothesis E: retain deferred baseline.
-
-## 4) Scenario definition
+## 2) Code inspected (source of truth)
+- `Aetheris.Firmament.FrictionLab/CIRLab/SteppedHoleExecutionArchitectureLab.cs`
+- `Aetheris.Firmament.FrictionLab/CIRLab/SteppedHoleExecutionArchitectureLabResult.cs`
+- `Aetheris.FrictionLab.Tests/CIRLab/SteppedHoleExecutionArchitectureLabTests.cs`
+- `Aetheris.Kernel.Firmament/Materializer/HoleRecoveryExecutor.cs`
+- `Aetheris.Kernel.Core/Brep/Boolean/BrepBooleanSafeComposition.cs`
+- `Aetheris.Kernel.Core/Brep/Boolean/BrepBooleanBoxCylinderHoleBuilder.cs`
+- `Aetheris.Kernel.Core/Brep/Boolean/BrepBooleanCoaxialSubtractStackFamily.cs`
+- `Aetheris.Kernel.Core/Step242/Step242Exporter.cs`
+
+## 3) Scenario definition
Canonical bounded stepped hole:
- Host `box(30,30,20)`.
- Small through `r=2`.
@@ -23,57 +21,70 @@ Canonical bounded stepped hole:
- Large shallow `r=4`, depth 4.
- Coaxial around Z.
-## 5) Strategy matrix results
-Implemented in lab runner and asserted in tests. Successful strategies receive STEP smoke and topology summaries; failed/deferred strategies carry failure code/stage/diagnostics.
-
-## 6) Repeated subtract order findings
-All tested deterministic orders are represented and compared:
-- `small->medium->large`
-- `large->medium->small`
-- `medium->large->small`
-
-## 7) Unioned tool findings
-Unioned tool route is executed when primitives/union/subtract succeed. Lab captures whether a single subtract is more stable and whether STEP markers remain valid.
-
-## 8) Direct N-level builder feasibility
-Feasible conceptually but not available as a current API surface in production codepaths; recorded as deferred analysis strategy.
-
-## 9) Profile-stack tool builder feasibility
-Feasible from `ProfileStack` data model and likely reusable for future variants; recorded as deferred analysis strategy.
-
-## 10) STEP smoke results
-For each successful strategy, smoke checks include:
-- `ISO-10303-21`
-- `MANIFOLD_SOLID_BREP`
-- `ADVANCED_FACE`
-- `CYLINDRICAL_SURFACE`
-- assert absence of `BREP_WITH_VOIDS`
-
-## 11) SafeBooleanComposition findings
-Lab records whether successful bodies preserve `SafeBooleanComposition` metadata.
-
-## 12) Recommended production strategy
-Lab returns an explicit recommendation token:
-- `repeated-subtract-production`
-- `unioned-tool-production`
-- `n-level-builder-production`
-- `profile-stack-tool-builder-production`
-- `keep-deferred`
-
-Current selection logic prefers successful unioned-tool, then successful repeated-subtract, else uses bounded JudgmentEngine fallback favoring profile-stack-builder analysis over n-level-builder, else keep-deferred.
-
-## 13) Why rejected strategies were rejected
-Each failed/deferred strategy reports explicit `FailureCode`, `FailureStage`, and diagnostics.
-
-## 14) Risks and guardrails
-- No production executor/boolean/exporter behavior changes.
-- Lab-only code under FrictionLab folders.
-- Deterministic matrix assertions included.
-
-## 15) Recommended next production milestone
-Promote winning strategy into production behind dedicated stability coverage and keep current deferred stepped execution until that milestone is complete.
-
-## 16) Confidence ratings
-- Strategy matrix plumbing: high.
-- API-feasibility conclusions (C/D): medium.
-- Production promotion readiness: medium-low pending broader stability corpus.
+## 4) Observed strategy matrix (canonical run)
+
+| Strategy | Status | Executed? | BodyProduced? | StepSmokeAttempted? | StepSmokeSucceeded? | FailureStage | FailureCode | SafeBooleanCompositionPresent? | TopologyCounts | RecommendationWeight / Notes |
+|---|---|---:|---:|---:|---:|---|---|---:|---|---|
+| RepeatedSubtract_SmallMediumLarge (`repeated-subtract-small-medium-large`) | Succeeded | Yes | Yes | Yes | Yes | `none` | `none` | Yes | F=11, L=15, E=21, CE=42, V=20 | Successful candidate; export markers present. |
+| RepeatedSubtract_LargeMediumSmall (`repeated-subtract-large-medium-small`) | Succeeded | Yes | Yes | Yes | Yes | `none` | `none` | Yes | F=11, L=15, E=21, CE=42, V=20 | Successful candidate; export markers present. |
+| RepeatedSubtract_MediumLargeSmall (`repeated-subtract-medium-large-small`) | Succeeded | Yes | Yes | Yes | Yes | `none` | `none` | Yes | F=11, L=15, E=21, CE=42, V=20 | Successful candidate; export markers present. |
+| UnionedToolThenSubtract (`unioned-tool-single-subtract`) | Failed | Yes | No | No | No | `boolean-union` | `union-small-medium-failed` | No | F=0, L=0, E=0, CE=0, V=0 | Union small+medium failed (`NotImplemented`), so route blocked before final subtract. |
+| DirectNLevelBuilderAnalysis (`n-level-builder-analysis`) | Deferred | No | No | No | No | `analysis` | `n-level-builder-not-implemented` | No | F=0, L=0, E=0, CE=0, V=0 | Existing pair classifier/builder path is 2-level-focused; no direct N-level production builder entrypoint wired in runner path. |
+| ProfileStackToolBuilderAnalysis (`profile-stack-tool-builder-analysis`) | Deferred | No | No | No | No | `analysis` | `profile-stack-tool-builder-missing` | No | F=0, L=0, E=0, CE=0, V=0 | `HoleRecoveryPlan.ProfileStack` contains tier stack data but no reusable profile-stack-to-tool builder utility exists in current path. |
+| KeepDeferredBaseline (`deferred-baseline-current-production`) | Deferred | Yes | No | No | No | `executor` | `stepped-execution-deferred` | No | F=0, L=0, E=0, CE=0, V=0 | Current production executor still defers stepped path after large-subtract blocker (`SteppedHoleExecutionDeferredPostValidator: blocker-at-large-subtract`). |
+| CounterboreBaseline (`counterbore-baseline`) | Succeeded | Yes | Yes | Yes | Yes | `none` | `none` | Yes | F=9, L=12, E=18, CE=36, V=16 | Confirms N=2 coaxial counterbore baseline remains healthy in current bounded flow. |
+
+## 5) Repeated subtract variants (per-order outcomes)
+- `small -> medium -> large`: **Succeeded**; STEP smoke attempted/succeeded; body exported; `SafeBooleanComposition` present.
+- `large -> medium -> small`: **Succeeded**; STEP smoke attempted/succeeded; body exported; `SafeBooleanComposition` present.
+- `medium -> large -> small`: **Succeeded**; STEP smoke attempted/succeeded; body exported; `SafeBooleanComposition` present.
+
+All successful rows emitted canonical STEP smoke markers (`ISO-10303-21`, `MANIFOLD_SOLID_BREP`, `ADVANCED_FACE`, `CYLINDRICAL_SURFACE`) and omitted `BREP_WITH_VOIDS`.
+
+## 6) Unioned tool route outcome
+- Tool union was attempted (`small ∪ medium` first).
+- First union failed at stage `boolean-union` with failure code `union-small-medium-failed`.
+- Diagnostic payload includes `NotImplemented` from boolean diagnostics.
+- Because union failed, final subtract and STEP smoke were not attempted.
+- Exact analytic-surface preservation could not be observed on this route because route did not produce a body.
+- `SafeBooleanComposition` metadata did not persist for this route (no result body).
+
+## 7) Direct N-level builder feasibility outcome
+- Direct N-level classifier feasibility exists (`BrepBooleanCoaxialSubtractStackFamily.TryClassifyNLevel`), but there is no production N-level builder route used by the lab to execute this strategy end-to-end.
+- It would require generalized N-tier tool/profile construction + topology/surface binding generation beyond the current pair-focused execution path.
+- A3 did not execute this route because it is analysis-only at this milestone (`n-level-builder-not-implemented`).
+
+## 8) Profile-stack tool-builder feasibility outcome
+- `HoleRecoveryPlan.ProfileStack` already carries tier radii/depth ordering needed to drive a stacked tool-builder concept.
+- Missing piece: reusable profile-stack tool-builder utility wired into a strategy execution path.
+- This path is judged more scalable than hand-specializing direct N-level topology for each tier count, but remains unimplemented in current runner.
+- A3 marks this route deferred as `profile-stack-tool-builder-missing`.
+
+## 9) Counterbore baseline outcome
+- `counterbore-baseline`: **Succeeded** with STEP smoke success and body produced.
+- Why it matters: it verifies the existing bounded N=2 coaxial stack behavior remains intact while stepped-hole architecture remains diagnostic/deferred.
+- This is the control signal that 2-level coaxial flow is still healthy.
+
+## 10) Selected recommendation
+SelectedRecommendation = `repeated-subtract-production`
+
+Reason = Unioned-tool route failed at boolean-union (`union-small-medium-failed`) while all three repeated-subtract order variants succeeded with STEP smoke and safe-composition presence. Deferred routes (direct N-level and profile-stack builder) are analysis-only in current milestone.
+
+Confidence = **medium** (strong evidence for this canonical scenario; broader corpus still needed before production promotion).
+
+## 11) Recommended production strategy and rejects
+Recommended production strategy:
+ `repeated-subtract-production`
+
+Why:
+ Matrix evidence shows 3/3 repeated-subtract variants succeeded end-to-end in canonical stepped scenario; unioned-tool route fails before subtract; deferred-analysis routes are not executable today.
+
+Rejected strategies:
+ - repeated subtract: not rejected in A3.1 (selected winner for next production route).
+ - unioned tool: rejected for now due to concrete union blocker (`union-small-medium-failed`, `NotImplemented`).
+ - n-level builder: rejected for immediate production promotion because execution path is not implemented in current lab/production wiring.
+ - profile-stack builder: rejected for immediate promotion because builder utility is missing, despite favorable scalability potential.
+ - keep deferred: rejected as final recommendation because executable repeated-subtract evidence exists in canonical case.
+
+Next production milestone:
+ **BREP-BOOLEAN-STACK-A4: repeated-subtract productionization gate** (scope: production stepped executor strategy wiring + stability corpus, without union/tool-builder refactors in same milestone).