Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

AIR-V1 scaffold AirProfileStackExtrude route for through/stepped

Yuechen Li67e75bc04561
diff --git a/Aetheris.Kernel.Firmament.Tests/AirProfileStackExtrudeTests.cs b/Aetheris.Kernel.Firmament.Tests/AirProfileStackExtrudeTests.cs
new file mode 100644
index 00000000..a4d1c0dc
--- /dev/null
+++ b/Aetheris.Kernel.Firmament.Tests/AirProfileStackExtrudeTests.cs
@@ -0,0 +1,81 @@
+using Aetheris.Kernel.Core.Cir;
+using Aetheris.Kernel.Core.Math;
+using Aetheris.Kernel.Core.Numerics;
+using Aetheris.Kernel.Core.Step242;
+using Aetheris.Kernel.Firmament.Materializer;
+
+namespace Aetheris.Kernel.Firmament.Tests;
+
+public sealed class AirProfileStackExtrudeTests
+{
+ [Fact]
+ public void AirProfileStack_FromSpec_ThroughHole_Validates()
+ {
+ var spec = new ProfileStackExtrudeSpec(20,20,-5,5,[new ProfileStackLayer(-5,5,2,"through",[])],[]);
+ Assert.True(AirProfileStackExtrudeAdapter.TryFromProfileStackSpec(spec, out var air, out _));
+ Assert.NotNull(air);
+ Assert.True(AirProfileStackExtrudeAdapter.TryValidate(air!, out _));
+ }
+
+ [Fact]
+ public void AirProfileStack_FromHolePlan_ThroughHole_ConvertsAndExecutes()
+ {
+ var plan = (HoleRecoveryPlan)new HoleRecoveryPolicy().Evaluate(new FrepMaterializerContext(new CirSubtractNode(new CirBoxNode(20,20,10), new CirCylinderNode(2,20)))).Plan!;
+ Assert.True(AirProfileStackExtrudeAdapter.TryFromHoleRecoveryPlan(plan, out _, out var d));
+ var exec = HoleRecoveryExecutor.Execute(plan);
+ Assert.Equal(HoleRecoveryExecutionStatus.Succeeded, exec.Status);
+ Assert.Contains(exec.Diagnostics, x => x.Contains("air-profile-stack-extrude", StringComparison.Ordinal));
+ var step = Step242Exporter.ExportBody(exec.Body!);
+ Assert.True(step.IsSuccess);
+ }
+
+ [Fact]
+ public void AirProfileStack_FromHolePlan_Stepped_ConvertsAndExecutes()
+ {
+ var plan = (HoleRecoveryPlan)new HoleRecoveryPolicy().Evaluate(new FrepMaterializerContext(BuildStepped())).Plan!;
+ Assert.True(AirProfileStackExtrudeAdapter.TryFromHoleRecoveryPlan(plan, out _, out _));
+ var exec = HoleRecoveryExecutor.Execute(plan);
+ Assert.Equal(HoleRecoveryExecutionStatus.Succeeded, exec.Status);
+ Assert.Contains(exec.Diagnostics, x => x.Contains("air-to-profile-stack-executor", StringComparison.Ordinal));
+ }
+
+ [Fact]
+ public void AirProfileStack_BlindHole_ExplicitlyDeferredInV1()
+ {
+ var plan = (HoleRecoveryPlan)new HoleRecoveryPolicy().Evaluate(new FrepMaterializerContext(new CirSubtractNode(new CirBoxNode(20,20,10), new CirTransformNode(new CirCylinderNode(2,4), Transform3D.CreateTranslation(new Vector3D(0,0,3)))))).Plan!;
+ Assert.False(AirProfileStackExtrudeAdapter.TryFromHoleRecoveryPlan(plan, out _, out var d));
+ Assert.Contains(d, x => x.Contains("air-profile-stack-v1-blind-deferred", StringComparison.Ordinal));
+ Assert.Equal(HoleRecoveryExecutionStatus.Succeeded, HoleRecoveryExecutor.Execute(plan).Status);
+ }
+
+ [Fact]
+ public void AirProfileStack_Counterbore_ExplicitlyDeferredInV1()
+ {
+ var plan = (HoleRecoveryPlan)new HoleRecoveryPolicy().Evaluate(new FrepMaterializerContext(new CirSubtractNode(new CirSubtractNode(new CirBoxNode(20,20,10), new CirCylinderNode(2,20)), new CirTransformNode(new CirCylinderNode(4,4), Transform3D.CreateTranslation(new Vector3D(0,0,3)))))).Plan!;
+ Assert.False(AirProfileStackExtrudeAdapter.TryFromHoleRecoveryPlan(plan, out _, out var d));
+ Assert.Contains(d, x => x.Contains("air-profile-stack-v1-counterbore-deferred", StringComparison.Ordinal));
+ Assert.Equal(HoleRecoveryExecutionStatus.Succeeded, HoleRecoveryExecutor.Execute(plan).Status);
+ }
+
+ [Fact]
+ public void AirProfileStack_ConicalVariants_DeferredInV1()
+ {
+ var root = new CirSubtractNode(new CirSubtractNode(new CirBoxNode(20,20,10), new CirCylinderNode(2,20)), new CirTransformNode(new CirConeNode(2, 4, 4), Transform3D.CreateTranslation(new Vector3D(0, 0, 3))));
+ var plan = (HoleRecoveryPlan)new HoleRecoveryPolicy().Evaluate(new FrepMaterializerContext(root)).Plan!;
+ Assert.False(AirProfileStackExtrudeAdapter.TryFromHoleRecoveryPlan(plan, out _, out var d));
+ Assert.Contains(d, x => x.Contains("air-profile-stack-v1-conical-deferred", StringComparison.Ordinal));
+ Assert.Equal(HoleRecoveryExecutionStatus.Succeeded, HoleRecoveryExecutor.Execute(plan).Status);
+ }
+
+ [Fact]
+ public void AirProfileStack_InvalidLayerOrdering_RejectsBeforeEmitter()
+ {
+ var air = new AirProfileStackExtrude([
+ new AirProfileStackLayer(-5,0,new AirProfileRegion2D(new AirRectangleProfile(20,20),new AirCenteredCircleLoop(2),"a",[]),"a",[]),
+ new AirProfileStackLayer(1,5,new AirProfileRegion2D(new AirRectangleProfile(20,20),new AirCenteredCircleLoop(3),"b",[]),"b",[])
+ ],-5,5,[],[]);
+ Assert.False(AirProfileStackExtrudeAdapter.TryToProfileStackSpec(air, out _, out _));
+ }
+
+ private static CirNode BuildStepped() => new CirSubtractNode(new CirSubtractNode(new CirSubtractNode(new CirBoxNode(20,20,10), new CirCylinderNode(2,20)), new CirTransformNode(new CirCylinderNode(3,6), Transform3D.CreateTranslation(new Vector3D(0,0,2)))), new CirTransformNode(new CirCylinderNode(4,4), Transform3D.CreateTranslation(new Vector3D(0,0,3))));
+}
diff --git a/Aetheris.Kernel.Firmament.Tests/ProfileStackExtrudeHoleFamilyMigrationTests.cs b/Aetheris.Kernel.Firmament.Tests/ProfileStackExtrudeHoleFamilyMigrationTests.cs
index 8e7b0556..f10f4e31 100644
--- a/Aetheris.Kernel.Firmament.Tests/ProfileStackExtrudeHoleFamilyMigrationTests.cs
+++ b/Aetheris.Kernel.Firmament.Tests/ProfileStackExtrudeHoleFamilyMigrationTests.cs
@@ -25,7 +25,7 @@ public sealed class ProfileStackExtrudeHoleFamilyMigrationTests
var plan = (HoleRecoveryPlan)new HoleRecoveryPolicy().Evaluate(new FrepMaterializerContext(root)).Plan!;
var result = HoleRecoveryExecutor.Execute(plan);
Assert.Equal(HoleRecoveryExecutionStatus.Succeeded, result.Status);
- Assert.Contains(result.Diagnostics, d => d.Contains("deferred: Blind", StringComparison.OrdinalIgnoreCase));
+ Assert.Contains(result.Diagnostics, d => d.Contains("air-profile-stack-v1-blind-deferred", StringComparison.OrdinalIgnoreCase));
Assert.Contains(result.Diagnostics, d => d.Contains("Blind subtract succeeded", StringComparison.OrdinalIgnoreCase));
}
@@ -36,7 +36,7 @@ public sealed class ProfileStackExtrudeHoleFamilyMigrationTests
var plan = (HoleRecoveryPlan)new HoleRecoveryPolicy().Evaluate(new FrepMaterializerContext(root)).Plan!;
var result = HoleRecoveryExecutor.Execute(plan);
Assert.Equal(HoleRecoveryExecutionStatus.Succeeded, result.Status);
- Assert.Contains(result.Diagnostics, d => d.Contains("deferred: Counterbore", StringComparison.OrdinalIgnoreCase));
+ Assert.Contains(result.Diagnostics, d => d.Contains("air-profile-stack-v1-counterbore-deferred", StringComparison.OrdinalIgnoreCase));
Assert.Contains(result.Diagnostics, d => d.Contains("Second subtract succeeded", StringComparison.OrdinalIgnoreCase));
}
diff --git a/Aetheris.Kernel.Firmament/Materializer/AirProfileStackExtrude.cs b/Aetheris.Kernel.Firmament/Materializer/AirProfileStackExtrude.cs
new file mode 100644
index 00000000..846be6ef
--- /dev/null
+++ b/Aetheris.Kernel.Firmament/Materializer/AirProfileStackExtrude.cs
@@ -0,0 +1,140 @@
+namespace Aetheris.Kernel.Firmament.Materializer;
+
+public sealed record AirRectangleProfile(double Width, double Height);
+
+public sealed record AirCenteredCircleLoop(double Radius);
+
+public sealed record AirProfileRegion2D(
+ AirRectangleProfile Outer,
+ AirCenteredCircleLoop? InnerCircle,
+ string Role,
+ IReadOnlyList<string> Diagnostics);
+
+public sealed record AirProfileStackLayer(
+ double ZMin,
+ double ZMax,
+ AirProfileRegion2D Region,
+ string Role,
+ IReadOnlyList<string> Diagnostics);
+
+public sealed record AirProfileStackExtrude(
+ IReadOnlyList<AirProfileStackLayer> Layers,
+ double GlobalZMin,
+ double GlobalZMax,
+ IReadOnlyList<string> Provenance,
+ IReadOnlyList<string> Diagnostics);
+
+public static class AirProfileStackExtrudeAdapter
+{
+ public static bool TryFromProfileStackSpec(ProfileStackExtrudeSpec spec, out AirProfileStackExtrude? air, out IReadOnlyList<string> diagnostics)
+ {
+ var d = new List<string> { "air-profile-stack adapter started.", "air-profile-stack-extrude", "air-converted-from-profile-stack-spec" };
+ air = null;
+
+ var layers = spec.Layers.Select((l, i) => new AirProfileStackLayer(
+ l.ZMin,
+ l.ZMax,
+ new AirProfileRegion2D(new AirRectangleProfile(spec.Width, spec.Depth), l.InnerCircleRadius.HasValue ? new AirCenteredCircleLoop(l.InnerCircleRadius.Value) : null, l.Role, l.Diagnostics),
+ l.Role,
+ [.. l.Diagnostics, $"air-layer-index={i}"])).ToArray();
+
+ var model = new AirProfileStackExtrude(layers, spec.ZMin, spec.ZMax, ["source:ProfileStackExtrudeSpec"], [.. spec.Diagnostics, .. d]);
+ if (!TryValidate(model, out var issues))
+ {
+ diagnostics = [.. d, .. issues];
+ return false;
+ }
+
+ air = model;
+ diagnostics = d;
+ return true;
+ }
+
+ public static bool TryFromHoleRecoveryPlan(HoleRecoveryPlan plan, out AirProfileStackExtrude? air, out IReadOnlyList<string> diagnostics)
+ {
+ var d = new List<string> { "air-profile-stack adapter started.", "air-profile-stack-extrude", "air-converted-from-hole-plan" };
+ air = null;
+
+ if (plan.HoleKind == HoleKind.Blind)
+ {
+ diagnostics = [.. d, "air-profile-stack-v1-blind-deferred"];
+ return false;
+ }
+
+ if (plan.HoleKind == HoleKind.Counterbore)
+ {
+ diagnostics = [.. d, "air-profile-stack-v1-counterbore-deferred"];
+ return false;
+ }
+
+ if (plan.HoleKind is HoleKind.Countersink or HoleKind.ChamferedEntry)
+ {
+ diagnostics = [.. d, "air-profile-stack-v1-conical-deferred"];
+ return false;
+ }
+
+ if (!ProfileStackExtrudePlanAdapter.TryFromHoleRecoveryPlan(plan, out var spec, out var profileDiagnostics) || spec is null)
+ {
+ diagnostics = [.. d, .. profileDiagnostics];
+ return false;
+ }
+
+ if (!TryFromProfileStackSpec(spec, out var converted, out var specDiagnostics) || converted is null)
+ {
+ diagnostics = [.. d, .. profileDiagnostics, .. specDiagnostics];
+ return false;
+ }
+
+ air = converted with { Provenance = ["source:HoleRecoveryPlan", "normalized:ProfileStackExtrudeSpec"], Diagnostics = [.. converted.Diagnostics, .. profileDiagnostics] };
+ diagnostics = [.. d, .. profileDiagnostics, .. specDiagnostics];
+ return true;
+ }
+
+ public static bool TryToProfileStackSpec(AirProfileStackExtrude air, out ProfileStackExtrudeSpec? spec, out IReadOnlyList<string> diagnostics)
+ {
+ var d = new List<string> { "air-to-profile-stack-executor" };
+ spec = null;
+ if (!TryValidate(air, out var issues))
+ {
+ diagnostics = [.. d, .. issues];
+ return false;
+ }
+
+ var ordered = air.Layers.OrderBy(l => l.ZMin).ToArray();
+ spec = new ProfileStackExtrudeSpec(
+ ordered[0].Region.Outer.Width,
+ ordered[0].Region.Outer.Height,
+ air.GlobalZMin,
+ air.GlobalZMax,
+ ordered.Select(l => new ProfileStackLayer(l.ZMin, l.ZMax, l.Region.InnerCircle?.Radius, l.Role, l.Diagnostics)).ToArray(),
+ [.. air.Diagnostics, .. d]);
+ diagnostics = d;
+ return true;
+ }
+
+ public static bool TryValidate(AirProfileStackExtrude air, out IReadOnlyList<string> diagnostics)
+ {
+ var d = new List<string>();
+ var tol = 1e-9;
+ var ordered = air.Layers.OrderBy(l => l.ZMin).ToArray();
+ if (ordered.Length == 0 || air.GlobalZMax - air.GlobalZMin <= tol)
+ {
+ diagnostics = ["air-validation-failed-empty-or-global-z"];
+ return false;
+ }
+
+ for (var i = 0; i < ordered.Length; i++)
+ {
+ var l = ordered[i];
+ if (l.ZMax - l.ZMin <= tol) d.Add($"air-validation-failed-non-positive-span[{i}]");
+ if (l.ZMin < air.GlobalZMin - tol || l.ZMax > air.GlobalZMax + tol) d.Add($"air-validation-failed-outside-global[{i}]");
+ if (l.Region.Outer.Width <= tol || l.Region.Outer.Height <= tol) d.Add($"air-validation-failed-invalid-outer-rect[{i}]");
+ if (l.Region.InnerCircle is not null && l.Region.InnerCircle.Radius <= tol) d.Add($"air-validation-failed-invalid-inner-radius[{i}]");
+ if (i > 0 && Math.Abs(ordered[i - 1].ZMax - l.ZMin) > tol) d.Add($"air-validation-failed-non-contiguous[{i - 1}->{i}]");
+ }
+
+ if (Math.Abs(ordered[0].ZMin - air.GlobalZMin) > tol || Math.Abs(ordered[^1].ZMax - air.GlobalZMax) > tol) d.Add("air-validation-failed-global-bounds-mismatch");
+ diagnostics = d;
+ return d.Count == 0;
+ }
+}
diff --git a/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryExecutor.cs b/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryExecutor.cs
index 06c7d440..e88d99fc 100644
--- a/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryExecutor.cs
+++ b/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryExecutor.cs
@@ -47,15 +47,24 @@ public static class HoleRecoveryExecutor
return ExecuteCountersinkLike(plan, diagnostics, "chamfer cone");
}
- if (ProfileStackExtrudePlanAdapter.TryFromHoleRecoveryPlan(plan, out var profileSpec, out var profileDiags) && profileSpec is not null)
+ if (AirProfileStackExtrudeAdapter.TryFromHoleRecoveryPlan(plan, out var air, out var airDiagnostics) && air is not null)
{
- diagnostics.AddRange(profileDiags);
+ diagnostics.AddRange(airDiagnostics);
if (plan.HoleKind == HoleKind.Stepped)
{
diagnostics.Add("Stepped executor marker: no-hidden-placement-inference; explicit z-span authority.");
diagnostics.Add("stepped executor route: profile-stack-extrude");
}
- diagnostics.Add("hole-family executor route: profile-stack-extrude");
+
+ if (!AirProfileStackExtrudeAdapter.TryToProfileStackSpec(air, out var profileSpec, out var toSpecDiagnostics) || profileSpec is null)
+ {
+ diagnostics.AddRange(toSpecDiagnostics);
+ diagnostics.Add("hole-family AIR conversion failed before emitter.");
+ return new(HoleRecoveryExecutionStatus.UnsupportedPlan, null, diagnostics);
+ }
+
+ diagnostics.AddRange(toSpecDiagnostics);
+ diagnostics.Add("hole-family executor route: profile-stack-extrude via AIR");
var profileResult = ProfileStackExtrudeExecutor.Execute(profileSpec);
diagnostics.AddRange(profileResult.Diagnostics);
@@ -70,7 +79,7 @@ public static class HoleRecoveryExecutor
return new(HoleRecoveryExecutionStatus.Succeeded, profileResult.Body, diagnostics);
}
- diagnostics.AddRange(profileDiags);
+ diagnostics.AddRange(airDiagnostics);
if (plan.HoleKind == HoleKind.Through)
{
diff --git a/docs/air-v1-profile-stack-extrude-production-scaffold.md b/docs/air-v1-profile-stack-extrude-production-scaffold.md
new file mode 100644
index 00000000..8bdd70a8
--- /dev/null
+++ b/docs/air-v1-profile-stack-extrude-production-scaffold.md
@@ -0,0 +1,62 @@
+# AIR-V1: production AirProfileStackExtrude scaffold for cylindrical contiguous stacks
+
+## DVT scope
+
+AIR-V1 productionizes the first AIR atom (`AirProfileStackExtrude`) for bounded cylindrical contiguous profile-stack extrusion.
+
+Supported in V1:
+- Through-hole route.
+- Stepped-hole route.
+
+Deferred to V2:
+- Blind-hole no-hole interval execution.
+- Counterbore overlap/non-uniform execution.
+- Conical countersink/chamfer profile-stack AIR execution.
+
+## Production model location
+
+`Aetheris.Kernel.Firmament/Materializer/AirProfileStackExtrude.cs`
+
+Namespace: `Aetheris.Kernel.Firmament.Materializer`.
+
+## AIR model shape
+
+- `AirProfileStackExtrude`
+- `AirProfileStackLayer`
+- `AirProfileRegion2D`
+- `AirRectangleProfile`
+- `AirCenteredCircleLoop`
+
+Model is constrained to:
+- outer rectangle,
+- optional centered inner circular loop,
+- ordered contiguous positive z-span layers,
+- explicit global z bounds,
+- provenance + diagnostics.
+
+## Conversion route
+
+- `ProfileStackExtrudeSpec -> AirProfileStackExtrude`
+- `HoleRecoveryPlan -> ProfileStackExtrudeSpec -> AirProfileStackExtrude`
+- `AirProfileStackExtrude -> ProfileStackExtrudeSpec -> ProfileStackExtrudeExecutor`
+
+## Diagnostics
+
+AIR route emits:
+- `air-profile-stack-extrude`
+- `air-converted-from-hole-plan`
+- `air-to-profile-stack-executor`
+
+Deferred diagnostics:
+- `air-profile-stack-v1-blind-deferred`
+- `air-profile-stack-v1-counterbore-deferred`
+- `air-profile-stack-v1-conical-deferred`
+
+## Behavior boundary
+
+No emitter rewrite was done. BRep/STEP behavior remains on existing production executor and exporter route; only bounded AIR scaffold/routing diagnostics are introduced.
+
+## AIR-V2 next scope
+
+- Introduce AIR execution semantics for blind/counterbore no-hole/overlap intervals.
+- Add explicit conical profile region for countersink/chamfer adaptation.
diff --git a/docs/cir-recovery-v19-hole-family-capability-manifest.md b/docs/cir-recovery-v19-hole-family-capability-manifest.md
index 29404098..8e06f7a2 100644
--- a/docs/cir-recovery-v19-hole-family-capability-manifest.md
+++ b/docs/cir-recovery-v19-hole-family-capability-manifest.md
@@ -191,3 +191,8 @@ Candidate next labs (user-prioritized):
- Generic profile-stack executor lab.
- Further stepped-hole expansion/hardening beyond bounded family.
- Surface-feature/groove semantic bridge lab.
+
+
+## AIR-V1 note
+
+Through-hole and stepped-hole profile-stack routes now materialize a bounded AIR scaffold (`AirProfileStackExtrude`) before executor emission. Blind/counterbore/conical variants are explicitly deferred in AIR-V1 and remain on their legacy executor routes.
diff --git a/docs/cir-sweep-v2-cylindrical-hole-profile-stack-migration.md b/docs/cir-sweep-v2-cylindrical-hole-profile-stack-migration.md
index 573812d2..884b71bd 100644
--- a/docs/cir-sweep-v2-cylindrical-hole-profile-stack-migration.md
+++ b/docs/cir-sweep-v2-cylindrical-hole-profile-stack-migration.md
@@ -54,3 +54,8 @@ Conical variants (`Countersink`, `ChamferedEntry`) intentionally remain on exist
## V3 recommendation
CIR-SWEEP-V3 can evaluate conical profile-stack/revolve/sweep route candidates for countersink/chamfered-entry without changing public APIs.
+
+
+## AIR-V1 note
+
+Through-hole and stepped-hole profile-stack routes now materialize a bounded AIR scaffold (`AirProfileStackExtrude`) before executor emission. Blind/counterbore/conical variants are explicitly deferred in AIR-V1 and remain on their legacy executor routes.