Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Add BREP-BOOLEAN-STACK-A3 stepped execution architecture lab

Yuechen Lib6395c7eb2c0
diff --git a/Aetheris.Firmament.FrictionLab/CIRLab/SteppedHoleExecutionArchitectureLab.cs b/Aetheris.Firmament.FrictionLab/CIRLab/SteppedHoleExecutionArchitectureLab.cs
new file mode 100644
index 00000000..11b34c13
--- /dev/null
+++ b/Aetheris.Firmament.FrictionLab/CIRLab/SteppedHoleExecutionArchitectureLab.cs
@@ -0,0 +1,144 @@
+using Aetheris.Kernel.Core.Brep;
+using Aetheris.Kernel.Core.Brep.Boolean;
+using Aetheris.Kernel.Core.Cir;
+using Aetheris.Kernel.Core.Judgment;
+using Aetheris.Kernel.Core.Math;
+using Aetheris.Kernel.Core.Step242;
+using Aetheris.Kernel.Firmament.Materializer;
+
+namespace Aetheris.Firmament.FrictionLab.CIRLab;
+
+public static class SteppedHoleExecutionArchitectureLab
+{
+ public static SteppedHoleExecutionArchitectureLabResult RunCanonicalSteppedScenario()
+ {
+ var diagnostics = new List<string> { "BREP-BOOLEAN-STACK-A3 started." };
+ var plan = (HoleRecoveryPlan)new HoleRecoveryPolicy().Evaluate(new FrepMaterializerContext(BuildCanonicalStepped())).Plan!;
+ var results = new List<SteppedArchitectureStrategyResult>
+ {
+ ExecuteRepeatedSubtract("repeated-subtract-small-medium-large", ["small","medium","large"]),
+ ExecuteRepeatedSubtract("repeated-subtract-large-medium-small", ["large","medium","small"]),
+ ExecuteRepeatedSubtract("repeated-subtract-medium-large-small", ["medium","large","small"]),
+ ExecuteUnionTool(),
+ new("n-level-builder-analysis", SteppedArchitectureStrategyStatus.Deferred, null, "n-level-builder-not-implemented", "analysis", ["Two-level builder exists; no N-level builder available in current API."], true, false, false, false, [], false, false, false, 0, 0, 0, 0, 0, "introduce internal N-level builder"),
+ new("profile-stack-tool-builder-analysis", SteppedArchitectureStrategyStatus.Deferred, null, "profile-stack-tool-builder-missing", "analysis", ["ProfileStack has sufficient tiers; no reusable profile-stack tool builder exists."], true, false, false, false, [], false, false, false, 0, 0, 0, 0, 0, "build reusable axial profile-stack tool builder"),
+ ExecuteDeferredBaseline(plan),
+ ExecuteCounterboreBaseline(),
+ ExecuteInvalidNonCoaxialControl()
+ };
+
+ return new(results, ChooseRecommendation(results), diagnostics);
+ }
+
+ private static SteppedArchitectureStrategyResult ExecuteRepeatedSubtract(string name, IReadOnlyList<string> order)
+ {
+ var box = BrepPrimitives.CreateBox(30, 30, 20); if (!box.IsSuccess) return Failed(name, "primitive-box-failed", "primitive", []);
+ var body = box.Value;
+ foreach (var step in order)
+ {
+ var tool = CreateTool(step); if (!tool.IsSuccess) return Failed(name, $"primitive-{step}-failed", "primitive", []);
+ var sub = BrepBoolean.Subtract(body, tool.Value);
+ if (!sub.IsSuccess || sub.Value is null) return Failed(name, $"subtract-{step}-failed", "boolean-subtract", sub.Diagnostics.Select(d => d.Code.ToString()).ToList());
+ body = sub.Value;
+ }
+ return Success(name, body);
+ }
+
+ private static SteppedArchitectureStrategyResult ExecuteUnionTool()
+ {
+ var box = BrepPrimitives.CreateBox(30, 30, 20); var s = CreateTool("small"); var m = CreateTool("medium"); var l = CreateTool("large");
+ if (!box.IsSuccess || !s.IsSuccess || !m.IsSuccess || !l.IsSuccess) return Failed("unioned-tool-single-subtract", "primitive-failed", "primitive", []);
+ var u1 = BrepBoolean.Union(s.Value, m.Value); if (!u1.IsSuccess || u1.Value is null) return Failed("unioned-tool-single-subtract", "union-small-medium-failed", "boolean-union", u1.Diagnostics.Select(d => d.Code.ToString()).ToList());
+ var u2 = BrepBoolean.Union(u1.Value, l.Value); if (!u2.IsSuccess || u2.Value is null) return Failed("unioned-tool-single-subtract", "union-tool-failed", "boolean-union", u2.Diagnostics.Select(d => d.Code.ToString()).ToList());
+ var sub = BrepBoolean.Subtract(box.Value, u2.Value); if (!sub.IsSuccess || sub.Value is null) return Failed("unioned-tool-single-subtract", "subtract-tool-failed", "boolean-subtract", sub.Diagnostics.Select(d => d.Code.ToString()).ToList());
+ return Success("unioned-tool-single-subtract", sub.Value);
+ }
+
+ private static SteppedArchitectureStrategyResult ExecuteDeferredBaseline(HoleRecoveryPlan plan)
+ {
+ var exec = HoleRecoveryExecutor.Execute(plan);
+ return new("deferred-baseline-current-production", exec.Status == HoleRecoveryExecutionStatus.UnsupportedPlan ? SteppedArchitectureStrategyStatus.Deferred : SteppedArchitectureStrategyStatus.Failed, exec.Body, "stepped-execution-deferred", "executor", exec.Diagnostics, true, true, false, false, [], false, false, false, 0, 0, 0, 0, 0, "keep deferred");
+ }
+
+ private static SteppedArchitectureStrategyResult ExecuteCounterboreBaseline()
+ {
+ var eval = new HoleRecoveryPolicy().Evaluate(new FrepMaterializerContext(new CirSubtractNode(new CirSubtractNode(new CirBoxNode(30,30,20), new CirCylinderNode(2,30)), new CirTransformNode(new CirCylinderNode(4,4), Transform3D.CreateTranslation(new Vector3D(0,0,-8))))));
+ var exec = HoleRecoveryExecutor.Execute((HoleRecoveryPlan)eval.Plan!);
+ return exec.Body is null ? Failed("counterbore-baseline", "counterbore-baseline-failed", "baseline", exec.Diagnostics.ToList()) : Success("counterbore-baseline", exec.Body);
+ }
+
+ private static SteppedArchitectureStrategyResult ExecuteInvalidNonCoaxialControl()
+ {
+ var eval = new HoleRecoveryPolicy().Evaluate(new FrepMaterializerContext(BuildNonCoaxialStepped()));
+ var diags = eval.Diagnostics.Concat(eval.RejectionReasons).ToList();
+ return new("invalid-control-non-coaxial", eval.Admissible ? SteppedArchitectureStrategyStatus.Failed : SteppedArchitectureStrategyStatus.Skipped, null, eval.Admissible ? "invalid-control-unexpected-admission" : "unsupported-non-coaxial", "admission", diags, eval.Admissible, false, false, false, [], false, false, false, 0, 0, 0, 0, 0, "keep guardrails");
+ }
+
+ private static string ChooseRecommendation(IReadOnlyList<SteppedArchitectureStrategyResult> results)
+ {
+ if (results.Any(r => r.Strategy == "unioned-tool-single-subtract" && r.Status == SteppedArchitectureStrategyStatus.Succeeded)) return "unioned-tool-production";
+ if (results.Any(r => r.Strategy.Contains("repeated-subtract", StringComparison.Ordinal) && r.Status == SteppedArchitectureStrategyStatus.Succeeded)) return "repeated-subtract-production";
+ var engine = new JudgmentEngine<int>();
+ var pick = engine.Evaluate(1, [new("profile-stack-tool-builder-production", _ => true, _ => 0.9), new("n-level-builder-production", _ => true, _ => 0.8), new("keep-deferred", _ => true, _ => 0.1)]);
+ return pick.Selection?.Candidate.Name ?? "keep-deferred";
+ }
+
+ private static Aetheris.Kernel.Core.Results.KernelResult<BrepBody> CreateTool(string step)
+ {
+ return step switch
+ {
+ "small" => BrepPrimitives.CreateCylinder(2, 30),
+ "medium" => Translate(BrepPrimitives.CreateCylinder(3, 8), 6),
+ "large" => Translate(BrepPrimitives.CreateCylinder(4, 4), 8),
+ _ => BrepPrimitives.CreateCylinder(1, 1)
+ };
+ }
+
+ private static Aetheris.Kernel.Core.Results.KernelResult<BrepBody> Translate(Aetheris.Kernel.Core.Results.KernelResult<BrepBody> source, double z)
+ {
+ if (!source.IsSuccess) return source;
+ var t = new Vector3D(0,0,z);
+ var body = source.Value;
+ var copy = new Dictionary<Aetheris.Kernel.Core.Topology.VertexId, Point3D>();
+ foreach (var v in body.Topology.Vertices)
+ {
+ if (body.TryGetVertexPoint(v.Id, out var point)) copy[v.Id] = point + t;
+ }
+ var g = new Aetheris.Kernel.Core.Brep.BrepGeometryStore();
+ foreach (var c in body.Geometry.Curves)
+ {
+ var gc = c.Value;
+ g.AddCurve(c.Key, gc.Kind switch
+ {
+ Aetheris.Kernel.Core.Geometry.CurveGeometryKind.Line3 => Aetheris.Kernel.Core.Geometry.CurveGeometry.FromLine(new Aetheris.Kernel.Core.Geometry.Curves.Line3Curve(gc.Line3!.Value.Origin + t, gc.Line3.Value.Direction)),
+ Aetheris.Kernel.Core.Geometry.CurveGeometryKind.Circle3 => Aetheris.Kernel.Core.Geometry.CurveGeometry.FromCircle(new Aetheris.Kernel.Core.Geometry.Curves.Circle3Curve(gc.Circle3!.Value.Center + t, gc.Circle3.Value.Normal, gc.Circle3.Value.Radius, gc.Circle3.Value.XAxis)),
+ _ => gc
+ });
+ }
+ foreach (var sf in body.Geometry.Surfaces)
+ {
+ var gs = sf.Value;
+ g.AddSurface(sf.Key, gs.Kind switch
+ {
+ Aetheris.Kernel.Core.Geometry.SurfaceGeometryKind.Plane => Aetheris.Kernel.Core.Geometry.SurfaceGeometry.FromPlane(new Aetheris.Kernel.Core.Geometry.Surfaces.PlaneSurface(gs.Plane!.Value.Origin + t, gs.Plane.Value.Normal, gs.Plane.Value.UAxis)),
+ Aetheris.Kernel.Core.Geometry.SurfaceGeometryKind.Cylinder => Aetheris.Kernel.Core.Geometry.SurfaceGeometry.FromCylinder(new Aetheris.Kernel.Core.Geometry.Surfaces.CylinderSurface(gs.Cylinder!.Value.Origin + t, gs.Cylinder.Value.Axis, gs.Cylinder.Value.Radius, gs.Cylinder.Value.XAxis)),
+ _ => gs
+ });
+ }
+ return Aetheris.Kernel.Core.Results.KernelResult<BrepBody>.Success(new BrepBody(body.Topology, g, body.Bindings, copy, body.SafeBooleanComposition?.Translate(t)));
+ }
+
+ private static SteppedArchitectureStrategyResult Success(string name, BrepBody body)
+ {
+ var step = Step242Exporter.ExportBody(body);
+ var text = step.IsSuccess ? step.Value : string.Empty;
+ var markers = new[] { "ISO-10303-21", "MANIFOLD_SOLID_BREP", "ADVANCED_FACE", "CYLINDRICAL_SURFACE" }.Where(m => text.Contains(m, StringComparison.Ordinal)).ToArray();
+ return new(name, SteppedArchitectureStrategyStatus.Succeeded, body, "none", "none", [], true, true, true, step.IsSuccess, markers, body.SafeBooleanComposition is not null, text.Contains("MANIFOLD_SOLID_BREP", StringComparison.Ordinal), text.Contains("BREP_WITH_VOIDS", StringComparison.Ordinal), body.Topology.Faces.Count(), body.Topology.Loops.Count(), body.Topology.Edges.Count(), body.Topology.Coedges.Count(), body.Topology.Vertices.Count(), "candidate");
+ }
+
+ private static SteppedArchitectureStrategyResult Failed(string name, string code, string stage, IReadOnlyList<string> diagnostics)
+ => new(name, SteppedArchitectureStrategyStatus.Failed, null, code, stage, diagnostics, true, true, false, false, [], false, false, false, 0, 0, 0, 0, 0, "investigate blocker");
+
+ private static CirNode BuildCanonicalStepped() => new CirSubtractNode(new CirSubtractNode(new CirSubtractNode(new CirBoxNode(30,30,20), new CirCylinderNode(2,30)), new CirTransformNode(new CirCylinderNode(3,8), Transform3D.CreateTranslation(new Vector3D(0,0,-6)))), new CirTransformNode(new CirCylinderNode(4,4), Transform3D.CreateTranslation(new Vector3D(0,0,-8))));
+ private static CirNode BuildNonCoaxialStepped() => new CirSubtractNode(new CirSubtractNode(new CirSubtractNode(new CirBoxNode(30,30,20), new CirCylinderNode(2,30)), new CirTransformNode(new CirCylinderNode(3,8), Transform3D.CreateTranslation(new Vector3D(1,0,-6)))), new CirTransformNode(new CirCylinderNode(4,4), Transform3D.CreateTranslation(new Vector3D(0,0,-8))));
+}
diff --git a/Aetheris.Firmament.FrictionLab/CIRLab/SteppedHoleExecutionArchitectureLabResult.cs b/Aetheris.Firmament.FrictionLab/CIRLab/SteppedHoleExecutionArchitectureLabResult.cs
new file mode 100644
index 00000000..fb8f7115
--- /dev/null
+++ b/Aetheris.Firmament.FrictionLab/CIRLab/SteppedHoleExecutionArchitectureLabResult.cs
@@ -0,0 +1,32 @@
+using Aetheris.Kernel.Core.Brep;
+
+namespace Aetheris.Firmament.FrictionLab.CIRLab;
+
+public enum SteppedArchitectureStrategyStatus { Succeeded, Failed, Deferred, Skipped }
+
+public sealed record SteppedArchitectureStrategyResult(
+ string Strategy,
+ SteppedArchitectureStrategyStatus Status,
+ BrepBody? Body,
+ string FailureCode,
+ string FailureStage,
+ IReadOnlyList<string> Diagnostics,
+ bool Admissible,
+ bool Executed,
+ bool StepSmokeAttempted,
+ bool StepSmokeSucceeded,
+ IReadOnlyList<string> StepMarkers,
+ bool HasSafeBooleanComposition,
+ bool ManifoldSolidBrep,
+ bool HasBrepWithVoids,
+ int FaceCount,
+ int LoopCount,
+ int EdgeCount,
+ int CoedgeCount,
+ int VertexCount,
+ string RecommendedNextStep);
+
+public sealed record SteppedHoleExecutionArchitectureLabResult(
+ IReadOnlyList<SteppedArchitectureStrategyResult> Strategies,
+ string Recommendation,
+ IReadOnlyList<string> Diagnostics);
diff --git a/Aetheris.FrictionLab.Tests/CIRLab/SteppedHoleExecutionArchitectureLabTests.cs b/Aetheris.FrictionLab.Tests/CIRLab/SteppedHoleExecutionArchitectureLabTests.cs
new file mode 100644
index 00000000..ba5da54e
--- /dev/null
+++ b/Aetheris.FrictionLab.Tests/CIRLab/SteppedHoleExecutionArchitectureLabTests.cs
@@ -0,0 +1,69 @@
+using Aetheris.Firmament.FrictionLab.CIRLab;
+
+namespace Aetheris.FrictionLab.Tests.CIRLab;
+
+public class SteppedHoleExecutionArchitectureLabTests
+{
+ [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");
+ }
+
+ [Fact]
+ public void SteppedArchitectureLab_RecordsFailureStages()
+ {
+ var failed = SteppedHoleExecutionArchitectureLab.RunCanonicalSteppedScenario().Strategies.Where(s => s.Status is SteppedArchitectureStrategyStatus.Failed or SteppedArchitectureStrategyStatus.Deferred);
+ Assert.All(failed, s =>
+ {
+ Assert.False(string.IsNullOrWhiteSpace(s.FailureCode));
+ Assert.False(string.IsNullOrWhiteSpace(s.FailureStage));
+ Assert.NotEmpty(s.Diagnostics);
+ });
+ }
+
+ [Fact]
+ public void SteppedArchitectureLab_StepSmokeForSuccessfulStrategies()
+ {
+ var success = SteppedHoleExecutionArchitectureLab.RunCanonicalSteppedScenario().Strategies.Where(s => s.Status == SteppedArchitectureStrategyStatus.Succeeded);
+ foreach (var s in success)
+ {
+ Assert.True(s.StepSmokeAttempted);
+ Assert.True(s.StepSmokeSucceeded);
+ Assert.Contains("ISO-10303-21", s.StepMarkers);
+ Assert.Contains("MANIFOLD_SOLID_BREP", s.StepMarkers);
+ Assert.False(s.HasBrepWithVoids);
+ }
+ }
+
+ [Fact]
+ public void SteppedArchitectureLab_CounterboreBaselineStillWorks()
+ {
+ var r = SteppedHoleExecutionArchitectureLab.RunCanonicalSteppedScenario().Strategies.Single(s => s.Strategy == "counterbore-baseline");
+ Assert.True(r.Status == SteppedArchitectureStrategyStatus.Succeeded || !string.IsNullOrWhiteSpace(r.FailureCode));
+ }
+
+ [Fact]
+ public void SteppedArchitectureLab_DeterministicResults()
+ {
+ var a = SteppedHoleExecutionArchitectureLab.RunCanonicalSteppedScenario();
+ var b = SteppedHoleExecutionArchitectureLab.RunCanonicalSteppedScenario();
+ Assert.Equal(string.Join(";", a.Strategies.Select(x => x.Strategy)), string.Join(";", b.Strategies.Select(x => x.Strategy)));
+ Assert.Equal(string.Join(";", a.Strategies.Select(x => x.Status)), string.Join(";", b.Strategies.Select(x => x.Status)));
+ Assert.Equal(string.Join(";", a.Strategies.Select(x => x.FailureCode)), string.Join(";", b.Strategies.Select(x => x.FailureCode)));
+ }
+
+ [Fact]
+ 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" });
+ }
+}
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
new file mode 100644
index 00000000..ee6d34da
--- /dev/null
+++ b/docs/frictionlab/brep-boolean-stack-a3-stepped-execution-architecture-lab.md
@@ -0,0 +1,79 @@
+# BREP-BOOLEAN-STACK-A3: stepped-hole execution architecture lab
+
+## 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
+Canonical bounded stepped hole:
+- Host `box(30,30,20)`.
+- Small through `r=2`.
+- Medium blind `r=3`, depth 8.
+- 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.