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.csindex 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 SteppedHoleExecutionArchitectureLabTestspublic 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.mdindex 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 scopeFrictionLab-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 definitionCanonical 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).