Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Add bounded prismatic material offset features

Yuechen Li043789a5a741
diff --git a/Aetheris.Kernel.Firmament.Tests/GeomOffsetX1Tests.cs b/Aetheris.Kernel.Firmament.Tests/GeomOffsetX1Tests.cs
new file mode 100644
index 00000000..f64466b9
--- /dev/null
+++ b/Aetheris.Kernel.Firmament.Tests/GeomOffsetX1Tests.cs
@@ -0,0 +1,147 @@
+using Aetheris.Kernel.Core.Brep;
+using Aetheris.Kernel.Core.Brep.Verification;
+using Aetheris.Kernel.Core.Geometry;
+using Aetheris.Kernel.Core.Step242;
+using Aetheris.Kernel.Firmament.Materializer;
+
+namespace Aetheris.Kernel.Firmament.Tests;
+
+public sealed class GeomOffsetX1Tests
+{
+ [Fact]
+ public void PrismAddAndFiniteRemove_LowerThroughTypedAirAndExactSectionStack()
+ {
+ var parsed = PrismaticProfileCompositionParser.Parse(Source("""
+ AddOffset<Prism> Pad { Target: Plate; On: Top; Profile: PadProfile; Height: 3mm }
+ RemoveOffset<Prism> Groove { Target: Plate; On: StockBody.Top; Profile: GrooveProfile; Depth: 4mm }
+ """));
+
+ Assert.Empty(parsed.Diagnostics);
+ var feature = Assert.IsType<PrismaticProfileCompositionFeature>(parsed.Feature);
+ Assert.Collection(feature.MaterialOffsets!,
+ add =>
+ {
+ Assert.Equal(("Add", "Prism", "Plate", "Height"), (add.OperationKind, add.ToolFamily, add.Target, add.Termination));
+ Assert.Equal([5d, -4d, 10d, 15d, 4d, 13d], add.AuthorizedRegion);
+ },
+ remove =>
+ {
+ Assert.Equal(("Remove", "Prism", "Plate", "Depth"), (remove.OperationKind, remove.ToolFamily, remove.Target, remove.Termination));
+ Assert.Equal([13d, -3d, 6d, 23d, 3d, 10d], remove.AuthorizedRegion);
+ });
+ var stack = Assert.IsType<PrismaticSectionStackConstruction>(PrismaticSectionStackCompiler.Normalize(parsed, out var stackDiagnostics));
+ Assert.Empty(stackDiagnostics);
+ var correspondence = Assert.IsType<SemanticTopologyCorrespondence>(PrismaticSectionStackEmitter.Emit(stack).Correspondence);
+ Assert.Contains(correspondence.Descendants, item => item.SourceStableId == "offset:Plate.Pad" && item.Role == SemanticTopologyRole.ExtrusionSideFace);
+ Assert.Contains(correspondence.Descendants, item => item.SourceStableId == "offset:Plate.Groove" && item.Role == SemanticTopologyRole.ExtrusionSideFace);
+
+ var result = FirmamentBuildAndExport.CompileSource(Source("""
+ AddOffset<Prism> Pad { Target: Plate; On: Top; Profile: PadProfile; Height: 3mm }
+ RemoveOffset<Prism> Groove { Target: Plate; On: StockBody.Top; Profile: GrooveProfile; Depth: 4mm }
+ """));
+ Assert.True(result.IsSuccess, string.Join(Environment.NewLine, result.Diagnostics.Select(item => item.Message)));
+ Assert.Equal(2, result.Value.EngineeringFeatures!.Count);
+ Assert.All(result.Value.EngineeringFeatures, item => Assert.Contains("Offset<Prism>", item.Kind));
+ var imported = Step242Importer.ImportBody(result.Value.StepText);
+ Assert.True(imported.IsSuccess, string.Join(Environment.NewLine, imported.Diagnostics.Select(item => item.Message)));
+ Assert.All(imported.Value.Topology.Edges, edge => Assert.Equal(2, imported.Value.Topology.Coedges.Count(use => use.EdgeId == edge.Id)));
+ Assert.All(imported.Value.Topology.Faces, face => Assert.Equal(SurfaceGeometryKind.Plane, imported.Value.GetFaceSurface(face.Id).Kind));
+ var mass = BrepMassProperties.Evaluate(imported.Value);
+ Assert.NotEqual(BrepMassPropertiesStatus.Unavailable, mass.Status);
+ Assert.Equal(12000d + 240d - 168d, mass.AbsoluteVolume, 6);
+ }
+
+ [Fact]
+ public void PrismThroughNotch_MayCrossTargetBoundaryAndRemainsOneBody()
+ {
+ var result = FirmamentBuildAndExport.CompileSource(Source("""
+ RemoveOffset<Prism> Notch { Target: Plate; On: Top; Profile: NotchProfile; Termination: ThroughAll }
+ """));
+
+ Assert.True(result.IsSuccess, string.Join(Environment.NewLine, result.Diagnostics.Select(item => item.Message)));
+ var report = Assert.Single(result.Value.EngineeringFeatures!);
+ Assert.Equal("ThroughAll", report.ExtentKind);
+ var imported = Step242Importer.ImportBody(result.Value.StepText);
+ Assert.True(imported.IsSuccess);
+ Assert.Single(imported.Value.Topology.Bodies);
+ Assert.Equal(11400d, BrepMassProperties.Evaluate(imported.Value).AbsoluteVolume, 6);
+ }
+
+ [Theory]
+ [InlineData("RemoveOffset<Prism> Bad { Target: Missing; On: Top; Profile: GrooveProfile; Depth: 4mm }", "offset-target-not-found")]
+ [InlineData("RemoveOffset<Cylinder> Bad { Target: Plate; On: Top; Profile: GrooveProfile; Depth: 4mm }", "offset-tool-family-not-qualified")]
+ [InlineData("RemoveOffset<Prism> Bad { Target: Plate; On: Top; Profile: GrooveProfile; Depth: 0mm }", "offset-tool-zero-dimension")]
+ [InlineData("AddOffset<Prism> Bad { Target: Plate; On: Top; Profile: PadProfile; Height: 0mm }", "offset-tool-zero-dimension")]
+ [InlineData("RemoveOffset<Prism> Bad { Target: Plate; On: Top; Profile: GrooveProfile; Along: +X; Depth: 4mm }", "offset-axis-invalid")]
+ [InlineData("AddOffset<Prism> Bad { Target: Plate; On: Top; Profile: FarProfile; Height: 3mm }", "offset-add-disconnected")]
+ [InlineData("AddOffset<Prism> Bad { Target: Plate; On: Top; Profile: TangentProfile; Height: 3mm }", "offset-tangent-contact")]
+ [InlineData("AddOffset<Prism> Bad { Target: Plate; On: Top; Profile: CircleProfile; Height: 3mm }", "offset-profile-curve-not-qualified")]
+ [InlineData("RemoveOffset<Prism> Bad { Target: Plate; On: Top; Profile: SplitProfile; Termination: ThroughAll }", "offset-remove-splits-body")]
+ [InlineData("RemoveOffset<Prism> Bad { Target: Plate; On: Top; Profile: StockProfile; Termination: ThroughAll }", "offset-remove-entire-body")]
+ public void InvalidPrismOffsets_FailClosedWithoutArtifact(string operation, string expected)
+ {
+ var result = FirmamentBuildAndExport.CompileSource(Source(operation));
+ Assert.False(result.IsSuccess);
+ Assert.Contains(result.Diagnostics, item => item.Message.Contains(expected, StringComparison.OrdinalIgnoreCase));
+ }
+
+ [Fact]
+ public void SameSource_ProducesByteIdenticalStepAndStableAir()
+ {
+ var source = Source("RemoveOffset<Prism> Groove { Target: Plate; On: Top; Profile: GrooveProfile; Depth: 4mm }");
+ var a = FirmamentBuildAndExport.CompileSource(source);
+ var b = FirmamentBuildAndExport.CompileSource(source);
+ Assert.True(a.IsSuccess && b.IsSuccess, string.Join(Environment.NewLine, a.Diagnostics.Concat(b.Diagnostics).Select(item => item.Message)));
+ Assert.Equal(a.Value.StepText, b.Value.StepText);
+ var firstAir = Assert.Single(PrismaticProfileCompositionParser.Parse(source).Feature!.MaterialOffsets!);
+ var secondAir = Assert.Single(PrismaticProfileCompositionParser.Parse(source).Feature!.MaterialOffsets!);
+ Assert.Equal((firstAir.StableId, firstAir.OperationKind, firstAir.ToolFamily, firstAir.Target,
+ firstAir.Support, firstAir.ProfileReference, firstAir.Direction, firstAir.Termination,
+ firstAir.From, firstAir.To, firstAir.Extent),
+ (secondAir.StableId, secondAir.OperationKind, secondAir.ToolFamily, secondAir.Target,
+ secondAir.Support, secondAir.ProfileReference, secondAir.Direction, secondAir.Termination,
+ secondAir.From, secondAir.To, secondAir.Extent));
+ Assert.Equal(firstAir.AuthorizedRegion, secondAir.AuthorizedRegion);
+ }
+
+ [Fact]
+ public void RoundedPrism_AuthorizedRegionUsesExactArcExtrema()
+ {
+ var parsed = PrismaticProfileCompositionParser.Parse(Source("AddOffset<Prism> RoundPad { Target: Plate; On: Top; Profile: RoundedProfile; Height: 2mm }"));
+
+ Assert.Empty(parsed.Diagnostics);
+ var offset = Assert.Single(parsed.Feature!.MaterialOffsets!);
+ Assert.Collection(offset.AuthorizedRegion,
+ value => Assert.Equal(-3d, value, 12), value => Assert.Equal(-4d, value, 12),
+ value => Assert.Equal(10d, value, 12), value => Assert.Equal(5d, value, 12),
+ value => Assert.Equal(2d, value, 12), value => Assert.Equal(12d, value, 12));
+ }
+
+ private static string Source(string operation) => $$"""
+ Model OffsetPrism {
+ Units: mm
+ Rect2 Stock { Center: [0mm,0mm]; Size: [40mm,30mm] }
+ Rect2 Pad { Center: [10mm,0mm]; Size: [10mm,8mm] }
+ Rect2 Groove { Center: [18mm,0mm]; Size: [10mm,6mm] }
+ Rect2 Notch { Center: [19mm,0mm]; Size: [10mm,10mm] }
+ Rect2 Far { Center: [80mm,0mm]; Size: [4mm,4mm] }
+ Rect2 Tangent { Center: [22mm,0mm]; Size: [4mm,4mm] }
+ Rect2 Split { Center: [0mm,0mm]; Size: [4mm,40mm] }
+ Circle2 Round { Center: [0mm,0mm]; Radius: 3mm }
+ RoundedRect2 Rounded { Center: [1mm,-1mm]; Size: [8mm,6mm]; Radius: 2mm }
+ Profile StockProfile { Loop Outer { Stock.Bottom |> Stock.Right |> Stock.Top |> Stock.Left |> Close } }
+ Profile PadProfile { Loop Outer { Pad.Bottom |> Pad.Right |> Pad.Top |> Pad.Left |> Close } }
+ Profile GrooveProfile { Loop Outer { Groove.Bottom |> Groove.Right |> Groove.Top |> Groove.Left |> Close } }
+ Profile NotchProfile { Loop Outer { Notch.Bottom |> Notch.Right |> Notch.Top |> Notch.Left |> Close } }
+ Profile FarProfile { Loop Outer { Far.Bottom |> Far.Right |> Far.Top |> Far.Left |> Close } }
+ Profile TangentProfile { Loop Outer { Tangent.Bottom |> Tangent.Right |> Tangent.Top |> Tangent.Left |> Close } }
+ Profile SplitProfile { Loop Outer { Split.Bottom |> Split.Right |> Split.Top |> Split.Left |> Close } }
+ Profile CircleProfile { Loop Outer { Round |> TraceLoop } }
+ Profile RoundedProfile { Loop Outer { Rounded |> TraceLoop } }
+ Compose Plate {
+ Base StockBody { Profile: StockProfile; From: 0mm; To: 10mm; Role: Stock }
+ {{operation}}
+ }
+ }
+ """;
+}
diff --git a/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs b/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs
index bf8e849c..b2e9d00d 100644
--- a/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs
+++ b/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs
@@ -2231,6 +2231,14 @@ public static class FirmamentBuildAndExport
item.Name, "Pocket", item.StableId, item.Host, item.SupportFace, item.ProfileReference,
item.Depth, "Depth", "Remove", item.RemainingFloor, item.MinimumFloorThickness,
item.MinimumFloorPolicySource, "PrismaticSectionStack/Remove", item.SupportSpan, item.ParentSupport)))
+ .Concat((feature.MaterialOffsets ?? []).Select(item => new FirmamentEngineeringFeatureReport(
+ item.Name, $"{item.OperationKind}Offset<{item.ToolFamily}>", item.StableId, item.Target, item.Support,
+ item.ProfileReference, item.Extent, item.Termination, item.OperationKind,
+ PolicySource: "BoundedMaterialOffsetX1",
+ MaterializationRoute: $"MaterialOffsetAir/{item.ToolFamily}->PrismaticSectionStack/{item.OperationKind}",
+ SupportSpan: item.SupportSpan, ParentSupport: item.ParentSupport,
+ ToolFamily: item.ToolFamily, Direction: item.Direction, Termination: item.Termination,
+ AuthorizedRegion: item.AuthorizedRegion)))
.OrderBy(item => item.FeatureId, StringComparer.Ordinal)
.ToArray();
diff --git a/Aetheris.Kernel.Firmament/FirmamentStepExportResult.cs b/Aetheris.Kernel.Firmament/FirmamentStepExportResult.cs
index 2a637807..eec322fc 100644
--- a/Aetheris.Kernel.Firmament/FirmamentStepExportResult.cs
+++ b/Aetheris.Kernel.Firmament/FirmamentStepExportResult.cs
@@ -133,7 +133,12 @@ public sealed record FirmamentEngineeringFeatureReport(
string? PolicySource = null,
string MaterializationRoute = "PrismaticSectionStack",
string? SupportSpan = null,
- string? ParentSupport = null);
+ string? ParentSupport = null,
+ string? ToolFamily = null,
+ string? Direction = null,
+ string? Termination = null,
+ IReadOnlyList<double>? AuthorizedRegion = null,
+ string Validity = "Valid");
public sealed record FirmamentStandardPartReport(
string Family,
diff --git a/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentInterop/FirmamentV2DiagnosticAdapter.cs b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentInterop/FirmamentV2DiagnosticAdapter.cs
index 5a6f6540..ffd22993 100644
--- a/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentInterop/FirmamentV2DiagnosticAdapter.cs
+++ b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentInterop/FirmamentV2DiagnosticAdapter.cs
@@ -32,7 +32,8 @@ public static class FirmamentV2DiagnosticAdapter
string? fieldName = null) =>
new(
diagnosticCode,
- FirmamentV2Parser.IsFatalDiagnosticCode(diagnosticCode) ? FirmamentDiagnosticSeverity.Fatal : FirmamentDiagnosticSeverity.Warning,
+ diagnosticCode.StartsWith("offset-", StringComparison.Ordinal) || FirmamentV2Parser.IsFatalDiagnosticCode(diagnosticCode)
+ ? FirmamentDiagnosticSeverity.Fatal : FirmamentDiagnosticSeverity.Warning,
MessageFor(diagnosticCode),
FirmamentV2InteropValueAdapter.AdaptSourceSpan(sourceSpan),
target,
diff --git a/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Parser.cs b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Parser.cs
index 0338178a..164b3d23 100644
--- a/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Parser.cs
+++ b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Parser.cs
@@ -970,7 +970,7 @@ public static class FirmamentV2Parser
var known = new HashSet<string>(StringComparer.Ordinal)
{
- "Box", "Cylinder", "Cone", "Sphere", "Torus", "RoundedBox", "Frustum", "StandardPart", "ExactCoaxialPart", "Point2", "Line2", "Rect2", "Circle2", "Ellipse2Guide", "Concept", "Struct", "Construction", "Profile", "Span", "Compose", "Boss", "Pocket", "EdgeFinish",
+ "Box", "Cylinder", "Cone", "Sphere", "Torus", "RoundedBox", "Frustum", "StandardPart", "ExactCoaxialPart", "Point2", "Line2", "Rect2", "Circle2", "Ellipse2Guide", "Concept", "Struct", "Construction", "Profile", "Span", "Compose", "Boss", "Pocket", "AddOffset", "RemoveOffset", "EdgeFinish",
"Record", "Static", "Template", "template", "ProfileDelta", "Selection", "InlineStep", "Recognize", "Replace", "Pmi", "Modify", "Match", "Require", "Assert"
};
var compatibilityOnly = new HashSet<string>(StringComparer.Ordinal)
diff --git a/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2ValidationReport.cs b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2ValidationReport.cs
index e406f72a..105c6894 100644
--- a/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2ValidationReport.cs
+++ b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2ValidationReport.cs
@@ -307,7 +307,8 @@ public static class FirmamentV2ValidationReportBuilder
new(code, IsFatal(code) ? "fatal" : "warning", Message(code));
private static bool IsFatal(string code) =>
- code.StartsWith(SemanticSymmetryAuthoring.Prefix, StringComparison.Ordinal)
+ code.StartsWith("offset-", StringComparison.Ordinal)
+ || code.StartsWith(SemanticSymmetryAuthoring.Prefix, StringComparison.Ordinal)
|| code.StartsWith("firmament-span-", StringComparison.Ordinal)
|| code.StartsWith("firmament-feature-footprint-outside-span:", StringComparison.Ordinal)
|| FirmamentV2Parser.IsFatalDiagnosticCode(code);
diff --git a/Aetheris.Kernel.Firmament/Materializer/PrismaticProfileComposition.cs b/Aetheris.Kernel.Firmament/Materializer/PrismaticProfileComposition.cs
index b2bc4f66..d352039c 100644
--- a/Aetheris.Kernel.Firmament/Materializer/PrismaticProfileComposition.cs
+++ b/Aetheris.Kernel.Firmament/Materializer/PrismaticProfileComposition.cs
@@ -26,6 +26,19 @@ public sealed record PrismaticPocketFeature(
double Depth, double HostThickness, double RemainingFloor, double MinimumFloorThickness,
string MinimumFloorPolicySource, double From, double To, string SourceSpan,
string? SupportSpan = null, string? ParentSupport = null);
+/// <summary>
+/// Typed AIR for a bounded local material delta. The profile remains semantic
+/// authority until section-stack planning; no public tool body reaches B-rep.
+/// </summary>
+public sealed record PrismaticMaterialOffsetFeature(
+ string Name, string StableId, PrismaticProfileIntent Intent, string ToolFamily,
+ string Target, string Support, string ProfileReference, string Direction,
+ string Termination, double From, double To, double Extent, string SourceSpan,
+ IReadOnlyList<double> AuthorizedRegion,
+ string? SupportSpan = null, string? ParentSupport = null)
+{
+ public string OperationKind => Intent == PrismaticProfileIntent.Add ? "Add" : "Remove";
+}
public sealed record PrismaticShaftHoleFeature(
string Name, string StableId, string ProfileReference, double CenterX, double CenterY, double Diameter,
double From, double To, string SemanticRole, string SourceSpan,
@@ -125,7 +138,8 @@ public sealed record PrismaticProfileCompositionFeature(
IReadOnlyList<PrismaticConstructionPlaneBlindDrillFeature>? ConstructionPlaneBlindDrills = null,
IReadOnlyList<PrismaticCounterboreHoleFeature>? CounterboreHoles = null,
IReadOnlyList<PrismaticBossFeature>? Bosses = null,
- IReadOnlyList<PrismaticPocketFeature>? Pockets = null)
+ IReadOnlyList<PrismaticPocketFeature>? Pockets = null,
+ IReadOnlyList<PrismaticMaterialOffsetFeature>? MaterialOffsets = null)
{
public IEnumerable<(string Name, string StableId, string ProfileReference)> AllSlotProfiles =>
(CapsuleSlots ?? []).Select(x => (x.Name, x.StableId, x.ProfileReference))
@@ -165,6 +179,10 @@ public static class PrismaticProfileCompositionParser
private static readonly Regex Operation = new(@"\b(?<intent>Base|Add|Remove)\s+(?<n>\w+)\s*\{\s*Profile\s*:\s*(?<profile>\w+)\s*;?\s*From\s*:\s*(?<from>[-+.\d]+)mm\s*;?\s*To\s*:\s*(?<to>[-+.\d]+)mm(?:\s*;?\s*Role\s*:\s*(?<role>\w+))?", RegexOptions.Singleline | RegexOptions.CultureInvariant);
private static readonly Regex BossHeader = new(@"\bBoss\s+(?<n>\w+)\s*\{", RegexOptions.CultureInvariant);
private static readonly Regex PocketHeader = new(@"\bPocket\s+(?<n>\w+)\s*\{", RegexOptions.CultureInvariant);
+ private static readonly Regex OffsetHeader = new(@"\b(?<intent>AddOffset|RemoveOffset)\s*<\s*(?<tool>[A-Za-z_]\w*)\s*>\s+(?<n>[A-Za-z_]\w*)\s*\{", RegexOptions.CultureInvariant);
+ private static readonly Regex OffsetTarget = new(@"\bTarget\s*:\s*(?<value>[A-Za-z_]\w*)", RegexOptions.CultureInvariant);
+ private static readonly Regex OffsetDirection = new(@"\b(?:Along|Axis|Direction)\s*:\s*(?<value>[+-][XYZ])", RegexOptions.CultureInvariant);
+ private static readonly Regex OffsetThroughAll = new(@"\b(?:Termination|Extent)\s*:\s*ThroughAll\b", RegexOptions.CultureInvariant | RegexOptions.IgnoreCase);
private static readonly Regex SemanticProfile = new(@"\bProfile\s*:\s*(?<profile>\w+)", RegexOptions.CultureInvariant);
private static readonly Regex SemanticSupport = new(@"\bOn\s*:\s*(?<face>[A-Za-z_]\w*(?:\.Top)?|[+-][XYZ])", RegexOptions.CultureInvariant);
private static readonly Regex BossHeight = new(@"\bHeight\s*:\s*(?<value>[-+.\d]+)mm", RegexOptions.CultureInvariant);
@@ -307,6 +325,7 @@ public static class PrismaticProfileCompositionParser
diagnostics.Add($"compose-role-cardinality:Base:expected=1:actual={baseOperations.Length}");
var bosses = new List<PrismaticBossFeature>();
var pockets = new List<PrismaticPocketFeature>();
+ var materialOffsets = new List<PrismaticMaterialOffsetFeature>();
// Cardinality is authored semantics, not a LINQ assertion. Never call
// Single/SingleOrDefault while malformed input can still reach this boundary.
var stock = baseOperations.Length == 1 ? baseOperations[0] : null;
@@ -382,6 +401,127 @@ public static class PrismaticProfileCompositionParser
pockets.Add(new(name, stableId, compose.Groups["n"].Value, face, profileName, depth, hostThickness, remaining, minimumFloor, policySource, selectedSupport.To - depth, selectedSupport.To, sourceSpan, supportSpan?.SpanId, supportSpan?.ParentId));
operations.Add(new(name, PrismaticProfileIntent.Remove, profileName, selectedSupport.To - depth, selectedSupport.To, "Pocket", sourceSpan, stableId, "Pocket"));
}
+
+ foreach (Match header in OffsetHeader.Matches(composeBody))
+ {
+ var name = header.Groups["n"].Value;
+ var intentText = header.Groups["intent"].Value;
+ var toolFamily = header.Groups["tool"].Value;
+ var intent = intentText == "AddOffset" ? PrismaticProfileIntent.Add : PrismaticProfileIntent.Remove;
+ var body = Block(composeBody, header.Index + header.Length - 1);
+ if (body is null) { diagnostics.Add($"offset-malformed:{name}:unclosed"); continue; }
+ if (!string.Equals(toolFamily, "Prism", StringComparison.Ordinal))
+ { diagnostics.Add($"offset-tool-family-not-qualified:{name}:tool={toolFamily}:qualified=Prism"); continue; }
+
+ var targetMatch = OffsetTarget.Match(body);
+ var profileMatch = SemanticProfile.Match(body);
+ var supportMatch = SemanticSupport.Match(body);
+ var directionMatch = OffsetDirection.Match(body);
+ var heightMatch = BossHeight.Match(body);
+ var depthMatch = PocketDepth.Match(body);
+ var throughAll = OffsetThroughAll.IsMatch(body);
+ if (!targetMatch.Success || !profileMatch.Success || !supportMatch.Success)
+ { diagnostics.Add($"offset-missing-required-field:{name}:required=Target,On,Profile"); continue; }
+ var target = targetMatch.Groups["value"].Value;
+ var profileName = profileMatch.Groups["profile"].Value;
+ var support = supportMatch.Groups["face"].Value;
+ var direction = directionMatch.Success ? directionMatch.Groups["value"].Value : "+Z";
+ if (!string.Equals(target, compose.Groups["n"].Value, StringComparison.Ordinal))
+ { diagnostics.Add($"offset-target-not-found:{name}:target={target}:active={compose.Groups["n"].Value}"); continue; }
+ if (!string.Equals(direction, "+Z", StringComparison.Ordinal))
+ { diagnostics.Add($"offset-axis-invalid:{name}:axis={direction}:qualified=+Z-prismatic-compose"); continue; }
+ if (!names.Add(name)) { diagnostics.Add($"compose-duplicate-operation:{name}"); continue; }
+ if (!profiles.TryGetValue(profileName, out var offsetProfile))
+ { diagnostics.Add($"offset-profile-not-found:{name}:profile={profileName}"); continue; }
+ var profileArea = Math.Abs(PrismaticSectionStackCompiler.ProfileArea(offsetProfile));
+ if (!double.IsFinite(profileArea) || profileArea <= 1e-9d)
+ { diagnostics.Add($"offset-profile-zero-area:{name}:profile={profileName}"); continue; }
+ if (offsetProfile.Loops.SelectMany(loop => loop.Segments)
+ .Any(segment => segment.Geometry is not (LineArcLineSegment2D or LineArcCircularArc2D)))
+ { diagnostics.Add($"offset-profile-curve-not-qualified:{name}:profile={profileName}:qualified=line,circular-arc"); continue; }
+
+ surfaceSpans.TryGetValue(support, out var supportSpan);
+ if (supportSpan is null && !IsTopSelector(support))
+ { diagnostics.Add($"offset-support-invalid:{name}:On={support}:qualified=Top-or-<feature>.Top-or-Span<Plane>"); continue; }
+ // A Span is an authored support contract. Both operations fail
+ // closed if their tool footprint escapes it. Edge notches remain
+ // available by naming the whole Top support.
+ if (supportSpan is not null && !IsProfileFootprintInsideSpan(supportSpan, offsetProfile, profiles))
+ { diagnostics.Add($"offset-support-invalid:{name}:profile={profileName}:outside-span={supportSpan.SpanId}"); continue; }
+ var candidates = supportSpan is null
+ ? ResolveTopSupports(support, stock, operations, offsetProfile, profiles)
+ : ResolveSpanTopSupportsForOffset(supportSpan, operations, offsetProfile, profiles);
+ if (candidates.Count == 0)
+ {
+ var tangent = operations.Where(operation => operation.Intent != PrismaticProfileIntent.Remove)
+ .Any(operation => profiles.TryGetValue(operation.ProfileReference, out var supportProfile)
+ && ProfilesTouch(supportProfile, offsetProfile));
+ diagnostics.Add(tangent
+ ? $"offset-tangent-contact:{name}:target={target}:profile={profileName}"
+ : intent == PrismaticProfileIntent.Add
+ ? $"offset-add-disconnected:{name}:target={target}:profile={profileName}"
+ : $"offset-no-intersection:{name}:target={target}:profile={profileName}");
+ continue;
+ }
+ if (candidates.Count > 1)
+ { diagnostics.Add($"offset-support-ambiguous:{name}:candidates={string.Join(",", candidates.Select(x => x.Name).Order(StringComparer.Ordinal))}"); continue; }
+ var selectedSupport = candidates[0];
+
+ double extent;
+ string termination;
+ double from;
+ double to;
+ if (intent == PrismaticProfileIntent.Add)
+ {
+ if (!heightMatch.Success || throughAll || depthMatch.Success)
+ { diagnostics.Add($"offset-missing-required-field:{name}:AddOffset<Prism>-requires=Height"); continue; }
+ extent = N(heightMatch, "value");
+ if (!double.IsFinite(extent) || extent <= 0d)
+ { diagnostics.Add($"offset-tool-zero-dimension:{name}:Height={extent:R}mm"); continue; }
+ termination = "Height";
+ from = selectedSupport.To;
+ to = from + extent;
+ }
+ else
+ {
+ if (throughAll == depthMatch.Success)
+ { diagnostics.Add($"offset-missing-required-field:{name}:RemoveOffset<Prism>-requires-exactly-one-of=Depth,Termination:ThroughAll"); continue; }
+ to = selectedSupport.To;
+ if (throughAll)
+ {
+ termination = "ThroughAll";
+ from = operations.Where(operation => operation.Intent != PrismaticProfileIntent.Remove).Min(operation => operation.From);
+ extent = to - from;
+ }
+ else
+ {
+ extent = N(depthMatch, "value");
+ if (!double.IsFinite(extent) || extent <= 0d)
+ { diagnostics.Add($"offset-tool-zero-dimension:{name}:Depth={extent:R}mm"); continue; }
+ termination = "Depth";
+ from = to - extent;
+ }
+ }
+ if (!(from < to)) { diagnostics.Add($"offset-tool-zero-dimension:{name}:extent={extent:R}mm"); continue; }
+ if (intent == PrismaticProfileIntent.Remove && throughAll)
+ {
+ if (ToolContainsProfile(offsetProfile, profiles[stock.ProfileReference]))
+ { diagnostics.Add($"offset-remove-entire-body:{name}:target={target}"); continue; }
+ var splitProbe = ProfileArrangementBuilder.Compose("XY",
+ [stock with { From = 0d, To = 1d }, new(name, PrismaticProfileIntent.Remove, profileName, 0d, 1d, "MaterialOffset", $"offset:{header.Index}")],
+ profiles, $"offset-split-probe:{name}");
+ if (splitProbe.Region is null || splitProbe.Arrangement.Diagnostics.Any(item => item.Contains("disconnected", StringComparison.OrdinalIgnoreCase)))
+ { diagnostics.Add($"offset-remove-splits-body:{name}:target={target}"); continue; }
+ }
+
+ var bounds = ProfileBounds(offsetProfile);
+ var stableId = $"offset:{compose.Groups["n"].Value}.{name}";
+ var sourceSpan = $"offset:{header.Index}";
+ materialOffsets.Add(new(name, stableId, intent, "Prism", target, support, profileName, direction,
+ termination, from, to, extent, sourceSpan,
+ [bounds.MinX, bounds.MinY, from, bounds.MaxX, bounds.MaxY, to], supportSpan?.SpanId, supportSpan?.ParentId));
+ operations.Add(new(name, intent, profileName, from, to, "MaterialOffset", sourceSpan, stableId, $"{intentText}<Prism>"));
+ }
}
var shaftHoles = new List<PrismaticShaftHoleFeature>();
var counterboreHoles = new List<PrismaticCounterboreHoleFeature>();
@@ -541,7 +681,7 @@ public static class PrismaticProfileCompositionParser
}
}
var levels = operations.SelectMany(o => new[] { o.From, o.To }).Distinct().Order().ToArray();
- var feature = diagnostics.Count == 0 ? new PrismaticProfileCompositionFeature(compose.Groups["n"].Value, placement.ProfilePlane, placement.Axis, placement, operations, levels, "parser-backed-scaffold-profile-composition", shaftHoles, capsuleSlots, roundedRectangleSlots, constructionPlaneBlindDrills, counterboreHoles, bosses, pockets) : null;
+ var feature = diagnostics.Count == 0 ? new PrismaticProfileCompositionFeature(compose.Groups["n"].Value, placement.ProfilePlane, placement.Axis, placement, operations, levels, "parser-backed-scaffold-profile-composition", shaftHoles, capsuleSlots, roundedRectangleSlots, constructionPlaneBlindDrills, counterboreHoles, bosses, pockets, materialOffsets) : null;
return new(feature, profiles, diagnostics.Distinct().ToArray(), expansion.Evidence);
}
@@ -561,6 +701,103 @@ public static class PrismaticProfileCompositionParser
.ToArray();
}
+ private static IReadOnlyList<PrismaticProfileOperation> ResolveSpanTopSupportsForOffset(
+ GeometricSpanView span,
+ IReadOnlyList<PrismaticProfileOperation> operations,
+ ResolvedProfile2D footprint,
+ IReadOnlyDictionary<string, ResolvedProfile2D> profiles)
+ {
+ if (span.ParentPlane is null) return [];
+ var top = span.ParentPlane.Origin.Z;
+ return operations.Where(operation => operation.Intent != PrismaticProfileIntent.Remove
+ && Math.Abs(operation.To - top) <= PlanarSpanContainment.Tolerance
+ && HasConnectedBossSupport(operation, footprint, profiles))
+ .ToArray();
+ }
+
+ private static (double MinX, double MinY, double MaxX, double MaxY) ProfileBounds(ResolvedProfile2D profile)
+ {
+ var points = profile.Loops.SelectMany(loop => loop.Segments).SelectMany(segment => segment.Geometry switch
+ {
+ LineArcLineSegment2D line => new[] { line.Start, line.End }.AsEnumerable(),
+ LineArcCircularArc2D arc => ArcBoundsPoints(arc),
+ _ => Enumerable.Empty<(double X, double Y)>()
+ }).ToArray();
+ return (points.Min(point => point.Item1), points.Min(point => point.Item2), points.Max(point => point.Item1), points.Max(point => point.Item2));
+ }
+
+ private static IEnumerable<(double X, double Y)> ArcBoundsPoints(LineArcCircularArc2D arc)
+ {
+ var endAngle = arc.StartAngleRadians + arc.SweepAngleRadians;
+ var candidateAngles = new[]
+ {
+ arc.StartAngleRadians,
+ endAngle,
+ 0d,
+ Math.PI / 2d,
+ Math.PI,
+ 3d * Math.PI / 2d
+ };
+ return candidateAngles
+ .Where(angle => angle == arc.StartAngleRadians || angle == endAngle || IsAngleOnArc(angle, arc.StartAngleRadians, arc.SweepAngleRadians))
+ .Select(angle => ArcPoint(arc, angle));
+ }
+
+ private static (double X, double Y) ArcPoint(LineArcCircularArc2D arc, double angle)
+ {
+ const double tolerance = 1e-12d;
+ var normalized = NormalizeAngle(angle);
+ if (Math.Abs(normalized) <= tolerance || Math.Abs(normalized - 2d * Math.PI) <= tolerance) return (arc.Center.X + arc.Radius, arc.Center.Y);
+ if (Math.Abs(normalized - Math.PI / 2d) <= tolerance) return (arc.Center.X, arc.Center.Y + arc.Radius);
+ if (Math.Abs(normalized - Math.PI) <= tolerance) return (arc.Center.X - arc.Radius, arc.Center.Y);
+ if (Math.Abs(normalized - 3d * Math.PI / 2d) <= tolerance) return (arc.Center.X, arc.Center.Y - arc.Radius);
+ return (arc.Center.X + arc.Radius * Math.Cos(angle), arc.Center.Y + arc.Radius * Math.Sin(angle));
+ }
+
+ private static bool IsAngleOnArc(double angle, double start, double sweep)
+ {
+ const double tolerance = 1e-12d;
+ if (Math.Abs(sweep) >= 2d * Math.PI - tolerance) return true;
+ var directedDelta = sweep >= 0d ? NormalizeAngle(angle - start) : NormalizeAngle(start - angle);
+ return directedDelta <= Math.Abs(sweep) + tolerance;
+ }
+
+ private static double NormalizeAngle(double angle)
+ {
+ var normalized = angle % (2d * Math.PI);
+ return normalized < 0d ? normalized + 2d * Math.PI : normalized;
+ }
+
+ private static bool ProfilesTouch(ResolvedProfile2D left, ResolvedProfile2D right)
+ {
+ const double tolerance = 1e-8d;
+ var leftSegments = left.Loops.SelectMany(loop => loop.Segments).ToArray();
+ var rightSegments = right.Loops.SelectMany(loop => loop.Segments).ToArray();
+ return Endpoints(leftSegments).Any(point => rightSegments.Any(segment => DistanceToCurve(point, segment.Geometry) <= tolerance))
+ || Endpoints(rightSegments).Any(point => leftSegments.Any(segment => DistanceToCurve(point, segment.Geometry) <= tolerance));
+ }
+
+ private static bool ToolContainsProfile(ResolvedProfile2D tool, ResolvedProfile2D target)
+ {
+ var toolArea = Math.Abs(PrismaticSectionStackCompiler.ProfileArea(tool));
+ var targetArea = Math.Abs(PrismaticSectionStackCompiler.ProfileArea(target));
+ return toolArea + 1e-8d >= targetArea
+ && Endpoints(target.Loops.SelectMany(loop => loop.Segments)).All(point =>
+ ProfileArrangementBuilder.PointInProfile(tool, point) is not ArrangementPointLocation.Outside);
+ }
+
+ private static IEnumerable<(double X, double Y)> Endpoints(IEnumerable<ResolvedProfileSegment2D> segments) =>
+ segments.SelectMany(segment => segment.Geometry switch
+ {
+ LineArcLineSegment2D line => new[] { line.Start, line.End }.AsEnumerable(),
+ LineArcCircularArc2D arc => new[]
+ {
+ (arc.Center.X + arc.Radius * Math.Cos(arc.StartAngleRadians), arc.Center.Y + arc.Radius * Math.Sin(arc.StartAngleRadians)),
+ (arc.Center.X + arc.Radius * Math.Cos(arc.StartAngleRadians + arc.SweepAngleRadians), arc.Center.Y + arc.Radius * Math.Sin(arc.StartAngleRadians + arc.SweepAngleRadians))
+ },
+ _ => Enumerable.Empty<(double X, double Y)>()
+ });
+
private static bool IsProfileFootprintInsideSpan(
GeometricSpanView span,
ResolvedProfile2D footprint,
diff --git a/Aetheris.Kernel.Firmament/Materializer/PrismaticSectionStackCompiler.cs b/Aetheris.Kernel.Firmament/Materializer/PrismaticSectionStackCompiler.cs
index a1341470..b5f07114 100644
--- a/Aetheris.Kernel.Firmament/Materializer/PrismaticSectionStackCompiler.cs
+++ b/Aetheris.Kernel.Firmament/Materializer/PrismaticSectionStackCompiler.cs
@@ -280,7 +280,8 @@ public static class PrismaticSectionStackEmitter
descendants.Add(new($"construction:{stack.Feature.Name}:{fragment.StableId}", "ArrangementFragment", SemanticTopologyRole.Unknown, source, ParentStableId: fragment.Source.StableId));
}
foreach (var feature in (stack.Feature.Bosses ?? []).Select(item => (item.StableId, item.ProfileReference, Kind: "Boss"))
- .Concat((stack.Feature.Pockets ?? []).Select(item => (item.StableId, item.ProfileReference, Kind: "Pocket"))))
+ .Concat((stack.Feature.Pockets ?? []).Select(item => (item.StableId, item.ProfileReference, Kind: "Pocket")))
+ .Concat((stack.Feature.MaterialOffsets ?? []).Select(item => (item.StableId, item.ProfileReference, Kind: $"{item.OperationKind}Offset<{item.ToolFamily}>"))))
{
var prefix = $"profile:{feature.ProfileReference}.Outer.";
foreach (var item in sideFaces.Select((side, index) => (Side: side, Face: faces[capFaces.Count + index]))
diff --git a/docs/development/audits/geom-offset-x1-material-delta-audit.md b/docs/development/audits/geom-offset-x1-material-delta-audit.md
new file mode 100644
index 00000000..08f671ad
--- /dev/null
+++ b/docs/development/audits/geom-offset-x1-material-delta-audit.md
@@ -0,0 +1,37 @@
+# GEOM-OFFSET-X1 material-delta audit
+
+This audit was completed before selecting the public `AddOffset<T>` / `RemoveOffset<T>` names and the internal `PrismaticMaterialOffsetFeature` AIR record.
+
+## Existing authorities
+
+| Existing operation | Bounded material meaning | Preserved semantic information |
+|---|---|---|
+| `Boss` | connected finite profile addition | host, support, profile, height, stable feature identity |
+| `Pocket` | enclosed finite top removal | host, support, profile, depth, remaining-floor policy |
+| `Hole` / `Slot` | typed analytic or profile openings | feature variant, diameter/width, placement, termination, topology descendants |
+| Compose `Add` / `Remove` | axial section-stack construction | source-ordered profile intent and exact axial intervals |
+| `ProfileDelta` | pre-solid 2D boundary change | boundary operation and profile provenance |
+| Sculpt `OffsetRegion` | displacement of an existing region | `MayModify`, authorized envelope, preservation contracts, geometric delta |
+| Sculpt section chains | bounded surface-chain add/remove | attachment/support, authorized envelope, preservation evidence, replay identity |
+
+`OffsetRegion` is therefore not an available name for material addition/removal: it already means displacement of an existing surface region.
+
+## Reusable implementation evidence
+
+The prismatic section-stack compiler is safe to reuse for the X1 Prism lane. It consumes closed `ResolvedProfile2D` values, preserves source order and line/arc carriers, rejects invalid or disconnected slab material, emits deterministic exact B-rep topology, and supports STEP round-trip. This is stronger than recognizing an anonymous temporary solid after a Boolean.
+
+The low-level `BrepBoolean` implementation is deliberately a recognized-family facade, not a general kernel. Its proven lanes include box/safe-root analytic holes, box sphere cavities/pits, orthogonal box additions, prismatic through cuts, and narrow cylinder-root coaxial holes/keyways. The current cylinder-root validator explicitly requires world-Z-aligned bores; it cannot qualify a perpendicular cross-hole. There is no bounded spherical-cap union builder. Those gaps prevent honest Cylinder/Sphere promotion in this pass.
+
+## Decisions
+
+- Public names: `AddOffset<Prism>` and `RemoveOffset<Prism>` are unambiguous beside Sculpt `OffsetRegion`.
+- Target is mandatory and must name the active Compose body.
+- X1 Prism direction is `+Z` in the Compose frame. General axis projection is not inferred.
+- Add uses positive `Height`; Remove uses exactly one of positive `Depth` or `Termination: ThroughAll`.
+- Whole-plane removal profiles may cross the target silhouette, enabling edge grooves and notches. A `Span<Plane>` remains a strict support contract, so a footprint escaping it is rejected.
+- Typed AIR retains intent, tool family, target, support, profile, direction, termination, authorized region, and stable identity until section-stack planning.
+- Cylinder and Sphere spellings fail typed as not qualified; they do not fall through to public arbitrary Booleans.
+
+## Hole-host decision
+
+Curved-support `Hole` is deferred to `GEOM-HOLE-HOST-X1`. Current Hole placement and the reusable cylinder-root subtraction path are planar/world-Z or coaxial. Generalizing them now would either infer an ambiguous curved-surface frame or require the same missing exact curved-target intersection machinery as Cylinder offsets.
diff --git a/docs/public/README.md b/docs/public/README.md
index 1a0ef8a3..621995de 100644
--- a/docs/public/README.md
+++ b/docs/public/README.md
@@ -4,7 +4,7 @@ This directory is the only authoritative in-repository guide to behavior shipped
Start with [Getting Started](getting-started.md), then use these guides:
-- Firmament: [overview](firmament/overview.md), [language style](firmament/language-style.md), [syntax](firmament/syntax.md), [geometry](firmament/geometry.md), [closed 2D boundaries](firmament/boundaries.md), [Revolve](firmament/revolve.md), [bounded mathematical sculpting](firmament/sculpting.md), [Section chains](firmament/section-chains.md), [PlasticShell](firmament/plastic-shell.md), [Circular Sweep](firmament/sweep.md), [Formed Wire](firmament/wire-form.md), [Structural members and weldments](firmament/structural.md), [Semantic piping and local autorouting](firmament/piping.md), [Paperclip Template](firmament/paperclip.md), [Templates](firmament/templates.md), [materials](firmament/materials.md), [PMI](firmament/pmi.md), [Sheet Metal](firmament/sheet-metal.md), [FEA](firmament/fea.md), and [STEP import](firmament/step-import.md)
+- Firmament: [overview](firmament/overview.md), [language style](firmament/language-style.md), [syntax](firmament/syntax.md), [geometry](firmament/geometry.md), [closed 2D boundaries](firmament/boundaries.md), [bounded material offsets](firmament/material-offsets.md), [Revolve](firmament/revolve.md), [bounded mathematical sculpting](firmament/sculpting.md), [Section chains](firmament/section-chains.md), [PlasticShell](firmament/plastic-shell.md), [Circular Sweep](firmament/sweep.md), [Formed Wire](firmament/wire-form.md), [Structural members and weldments](firmament/structural.md), [Semantic piping and local autorouting](firmament/piping.md), [Paperclip Template](firmament/paperclip.md), [Templates](firmament/templates.md), [materials](firmament/materials.md), [PMI](firmament/pmi.md), [Sheet Metal](firmament/sheet-metal.md), [FEA](firmament/fea.md), and [STEP import](firmament/step-import.md)
- Non-manufacturing work: [Virtual Sculpture and Sol 1](virtual-sculpture.md)
- Standard Library: [product-family index, invocation, authoring, and compatibility](standard-library/README.md)
- Interoperability: [Forge Host Protocol v1](forge/interop.md)
diff --git a/docs/public/firmament/material-offsets.md b/docs/public/firmament/material-offsets.md
new file mode 100644
index 00000000..2497879d
--- /dev/null
+++ b/docs/public/firmament/material-offsets.md
@@ -0,0 +1,30 @@
+# Bounded material offsets
+
+`AddOffset` and `RemoveOffset` describe a bounded local material change using a closed semantic tool family. They are the geometric fallback between named engineering features and advanced Sculpt operations; they are not arbitrary public Boolean union or subtraction.
+
+Use a stronger noun when one exists: use `Hole` for a hole, `Pocket` for an enclosed finite pocket, `Boss` for a boss, and `Slot` for a slot. Use an Offset for a bounded local pad, groove, channel, or edge notch that lacks that stronger engineering meaning. Use Sculpt when explicit topology surgery and preservation contracts are required.
+
+## Qualified Prism lane
+
+```firmament
+Compose Plate {
+ Base StockBody { Profile: StockProfile; From: 0mm; To: 10mm; Role: Stock }
+
+ RemoveOffset<Prism> EdgeGroove {
+ Target: Plate
+ On: Top
+ Profile: GrooveProfile
+ Depth: 4mm
+ }
+}
+```
+
+`Prism` consumes an existing closed, nonzero-area Profile made from bounded line and circular-arc segments. Full-circle and ellipse primitives are rejected until the section-arrangement authority admits them; a circle can be authored as two bounded semicircular arcs when needed. The current bounded lane uses the Compose `+Z` frame. Add requires a positive `Height`. Remove requires exactly one of a positive `Depth` or `Termination: ThroughAll`.
+
+A removal profile on the whole `Top` support may cross the target silhouette; this is how edge grooves and notches are expressed. The tool must still remove positive material, leave one connected nonempty body, and produce valid exact topology. On a bounded `Span<Plane>`, the full footprint must remain inside the span because the span is an authored support contract.
+
+The compiler retains target, support, profile, direction, termination, authorized bounds, material effect, and stable identity before lowering through the existing exact section-stack construction path. Zero dimensions, missing targets, non-intersection, disconnected addition, splitting removal, and complete removal fail without emitting a body.
+
+Cylinder and Sphere offsets are not qualified yet. In particular, arbitrary-axis removal against curved targets and exact spherical-cap addition require new bounded analytic topology builders. The compiler rejects those tool families rather than exposing or guessing a general Boolean operation.
+
+Do not confuse material offsets with Sculpt `OffsetRegion`: `OffsetRegion` displaces an existing surface region; `AddOffset` and `RemoveOffset` change material using a bounded semantic tool.
diff --git a/docs/public/firmament/syntax.md b/docs/public/firmament/syntax.md
index d2885e1d..e86e95e2 100644
--- a/docs/public/firmament/syntax.md
+++ b/docs/public/firmament/syntax.md
@@ -16,6 +16,8 @@ For example, begin a formed-wire program with `schema WireForm`. An explicit sch
A canonical native part begins with `Model`, declares `Units`, creates named solids, and applies semantic features in `Modify` or `Compose`:
+The bounded material-offset subset is `AddOffset<Prism>` and `RemoveOffset<Prism>` inside an active `Compose`; see [bounded material offsets](material-offsets.md). `Cylinder` and `Sphere` offset families are reserved but not qualified.
+
```firmament
Model Plate {
Units: mm
diff --git a/docs/public/reference/release-notes.md b/docs/public/reference/release-notes.md
index a300c6a0..0cf597b5 100644
--- a/docs/public/reference/release-notes.md
+++ b/docs/public/reference/release-notes.md
@@ -9,6 +9,8 @@ Preview 3 is the feature-frozen Windows x64 release of Aetheris's integrated sem
## Geometry
+- GEOM-OFFSET-X1 meaningful progression: typed `AddOffset<Prism>` / `RemoveOffset<Prism>` authoring through exact Profile/Compose section-stack construction, with explicit target/support/termination/authorized-region evidence and fail-closed safety diagnostics. Cylinder and Sphere remain explicitly unqualified pending bounded curved-topology builders.
+
- Bounded analytic and prismatic modeling: named primitives and profiles, semantic holes, slots and patterns, admitted chamfer/fillet routes, hollow/lattice routes, and deterministic AP242 output.
- First-class connected finite Boss and finite-depth Pocket operations on the documented Compose host, with explicit through-depth and minimum-floor rejection.
- Parser-backed Sphere, Cone, and Torus single-solid AP242 routes. This is not general freeform or Boolean authoring.
diff --git a/docs/public/reference/supported-features.md b/docs/public/reference/supported-features.md
index 8db8010b..4cbd1008 100644
--- a/docs/public/reference/supported-features.md
+++ b/docs/public/reference/supported-features.md
@@ -19,6 +19,7 @@
| Semantic piping / routing | Bounded (X3a) | Logical connections; equipment-owned port Interfaces and hollow nozzle stubs; target-port-scoped owner KeepOut exemptions; coincident endpoint mates; explicit orthogonal 3D routes; deterministic A* proposals; editable accepted routes; 90-degree elbows; bounded local rerouting; AP242 assembly, BOM, and pipe Cut List. No freeform, stress-, flow-, slope-, or plant-scale routing. See [guide](../firmament/piping.md). |
| Boss | Bounded | First-class connected finite profile addition; relative `On: Top` resolves the highest current semantic support under the footprint, named `<feature>.Top`/`Base.Top` is explicit, ambiguity fails typed; positive height; lowers through existing `Add`; no arbitrary solid union |
| Pocket | Bounded | First-class enclosed finite-depth `On: Top` profile removal; positive depth, non-through termination, and minimum remaining floor enforced; lowers through existing `Remove` |
+| `AddOffset<Prism>` / `RemoveOffset<Prism>` | Bounded (X1 Prism subset) | Explicit active Compose target, closed Profile tool, whole Top or bounded `Span<Plane>` support, `+Z` direction; Add uses positive Height, Remove uses positive Depth or ThroughAll; edge-crossing removals allowed on whole Top; Cylinder/Sphere deferred and rejected typed |
| Lower-level profile composition | Bounded | Existing prismatic `Compose` `Add`/`Remove` remains compatible for bounded blockout authoring |
| Semantic holes, slots, patterns | Bounded | Qualified shaft/counterbore/countersink and finite static pattern routes; no stable generated-instance selector |
| Edge finishes/hollow/lattice | Bounded | Documented admitted chamfer/fillet, hollow, and cubic-truss routes; not arbitrary topology |
diff --git a/docs/release/GEOM-OFFSET-X1.md b/docs/release/GEOM-OFFSET-X1.md
new file mode 100644
index 00000000..cdb9a5a9
--- /dev/null
+++ b/docs/release/GEOM-OFFSET-X1.md
@@ -0,0 +1,47 @@
+# GEOM-OFFSET-X1 — bounded local material add/remove
+
+## Executive verdict
+
+**Meaningful progression.** Aetheris now expresses the Prism subset of common bounded local material addition/removal without exposing public arbitrary Boolean operands. The exact curved-tool matrix is not accepted: Cylinder cross-holes/curved-target cuts and spherical addition remain blocked on missing bounded analytic topology builders.
+
+## Operation matrix
+
+| Tool | Add | Remove | Host/support | Termination | Qualified |
+|---|---|---|---|---|---|
+| Prism | connected profile pad | groove, channel, finite/through edge notch | active Compose body; whole Top or bounded `Span<Plane>`; `+Z` frame | Add `Height`; Remove `Depth` or `ThroughAll` | Yes |
+| Cylinder | — | — | exact curved-target intersections unavailable | — | No; typed rejection |
+| Sphere | — | — | exact cap union unavailable | — | No; typed rejection |
+
+## Semantic and safety result
+
+`PrismaticMaterialOffsetFeature` is the typed AIR boundary. It retains Add/Remove, Prism, explicit target, support, source Profile, direction, termination, extent, stable ID, and six-coordinate authorized region. Materialization reuses the exact Profile/Compose section-stack path; the author never supplies an arbitrary body operand.
+
+The qualified tests demonstrate positive Add/Remove, an edge-crossing through notch, exact line/circular-arc profile bounds, exact planar carriers, single-body STEP reimport, analytic volume, deterministic AIR/STEP, stable result-wall descendants, and fail-closed rejection for zero extent, missing target, unsupported tool family/profile curve, no intersection/disconnected Add, splitting Remove, and complete removal. Failure occurs before output artifact construction.
+
+Outside the authorized profile extrusion bounds, section-stack source geometry is preserved. The source Profile provides stable derived wall/cap identity through existing profile segment provenance; the offset itself has stable identity `offset:<target>.<name>`.
+
+## Relation to named features
+
+- `Boss` remains preferred for boss intent and preserves boss-specific identity.
+- `Pocket` remains preferred for an enclosed finite pocket and enforces minimum floor policy.
+- `Hole` and `Slot` remain preferred for their typed engineering variants and topology descendants.
+- `ProfileDelta` changes a 2D boundary before solid construction; Offset changes an existing 3D construction state.
+- `OffsetRegion` displaces an existing Sculpt surface region and is not a material-offset synonym.
+
+## Deferred boundaries
+
+The existing Boolean facade proves selected box/cylinder/sphere cases but is not a general exact kernel. Its cylinder-root path is world-Z/coaxial and cannot manufacture a perpendicular cylinder-cylinder intersection. It has a bounded box/sphere pit builder but no connected exact spherical-cap union builder. Promoting either family now would discard semantic tool intent early or require a faceted/general-Boolean fallback, both forbidden by this milestone.
+
+Curved-support Hole is therefore deferred to `GEOM-HOLE-HOST-X1`. The BenchCAD `topup_ball_knob_axial_hole` witness was not rerun because the required sphere-target Cylinder removal is not qualified; the historical 0.9409 score is not acceptance evidence.
+
+## Qualification evidence
+
+- Release solution build: zero warnings and zero errors.
+- Full solution tests: 3,469 passed, including the focused Offset suite at 14/14. (`Aetheris.FrictionLab.Tests` currently discovers no tests.)
+- Repository and freshly packaged CLI produced byte-identical groove STEP (`4C30A48E85BE1DA8A3F006F36181880A7EA0CC32BD497E628BBF697B3AE33B58`).
+- Groove STEP reimport: one enclosed-manifold body, 17 planar faces, and bounds `[-20,-15,0]` to `[20,15,10]`. The independent Add-plus-Remove volume witness is exactly `12000 + 240 - 168 = 12072 mm³`.
+- Eight Prism invalid fixtures produced their typed diagnostics and no STEP artifact, including zero height/depth, invalid axis, non-intersection, tangency, disconnected Add, splitting Remove, and complete removal.
+- Canonical Offset fixtures all build. The repository-wide qualification script still exits nonzero after its fixture actions because the pre-existing `Assembly/annular-pair.firmament` uses compatibility-only `LegacyExplicit` placement, which the canonical-content guard rejects. GEOM-OFFSET-X1 does not rewrite that unrelated assembly fixture.
+- Public-document dialect/link checks passed; the repository layout guard inspected 4,115 tracked files successfully; `git diff --check` passed.
+
+The Prism implementation intentionally uses the existing Compose section-stack construction authority rather than routing through Sculpt `ConstructionState`. This retains transactional plan-first materialization, ordered semantic operations, exact source provenance, and deterministic replay for this bounded lane without introducing a second construction executor. Cylinder/Sphere need new exact topology builders before they can share an equivalent contract.
diff --git a/fixtures/Canonical/Offset/prism-groove.firmament b/fixtures/Canonical/Offset/prism-groove.firmament
new file mode 100644
index 00000000..3a0fc4ea
--- /dev/null
+++ b/fixtures/Canonical/Offset/prism-groove.firmament
@@ -0,0 +1,11 @@
+Model PrismGroove {
+ Units: mm
+ Rect2 Stock { Center: [0mm,0mm]; Size: [40mm,30mm] }
+ Rect2 Groove { Center: [18mm,0mm]; Size: [10mm,6mm] }
+ Profile StockProfile { Loop Outer { Stock.Bottom |> Stock.Right |> Stock.Top |> Stock.Left |> Close } }
+ Profile GrooveProfile { Loop Outer { Groove.Bottom |> Groove.Right |> Groove.Top |> Groove.Left |> Close } }
+ Compose Plate {
+ Base StockBody { Profile: StockProfile; From: 0mm; To: 10mm; Role: Stock }
+ RemoveOffset<Prism> GrooveCut { Target: Plate; On: Top; Profile: GrooveProfile; Depth: 4mm }
+ }
+}
diff --git a/fixtures/Canonical/Offset/prism-pad.firmament b/fixtures/Canonical/Offset/prism-pad.firmament
new file mode 100644
index 00000000..796fd96e
--- /dev/null
+++ b/fixtures/Canonical/Offset/prism-pad.firmament
@@ -0,0 +1,11 @@
+Model PrismPad {
+ Units: mm
+ Rect2 Stock { Center: [0mm,0mm]; Size: [40mm,30mm] }
+ Rect2 Pad { Center: [10mm,0mm]; Size: [10mm,8mm] }
+ Profile StockProfile { Loop Outer { Stock.Bottom |> Stock.Right |> Stock.Top |> Stock.Left |> Close } }
+ Profile PadProfile { Loop Outer { Pad.Bottom |> Pad.Right |> Pad.Top |> Pad.Left |> Close } }
+ Compose Plate {
+ Base StockBody { Profile: StockProfile; From: 0mm; To: 10mm; Role: Stock }
+ AddOffset<Prism> LocalPad { Target: Plate; On: Top; Profile: PadProfile; Height: 3mm }
+ }
+}
diff --git a/fixtures/Canonical/Offset/prism-through-notch.firmament b/fixtures/Canonical/Offset/prism-through-notch.firmament
new file mode 100644
index 00000000..86658ced
--- /dev/null
+++ b/fixtures/Canonical/Offset/prism-through-notch.firmament
@@ -0,0 +1,11 @@
+Model PrismThroughNotch {
+ Units: mm
+ Rect2 Stock { Center: [0mm,0mm]; Size: [40mm,30mm] }
+ Rect2 Notch { Center: [19mm,0mm]; Size: [10mm,10mm] }
+ Profile StockProfile { Loop Outer { Stock.Bottom |> Stock.Right |> Stock.Top |> Stock.Left |> Close } }
+ Profile NotchProfile { Loop Outer { Notch.Bottom |> Notch.Right |> Notch.Top |> Notch.Left |> Close } }
+ Compose Plate {
+ Base StockBody { Profile: StockProfile; From: 0mm; To: 10mm; Role: Stock }
+ RemoveOffset<Prism> EdgeNotch { Target: Plate; On: Top; Profile: NotchProfile; Termination: ThroughAll }
+ }
+}
diff --git a/fixtures/Canonical/qualification.json b/fixtures/Canonical/qualification.json
index e42b1bf4..8b67abcf 100644
--- a/fixtures/Canonical/qualification.json
+++ b/fixtures/Canonical/qualification.json
@@ -34,6 +34,7 @@
{ "path": "Boundary2", "operation": "build-step" },
{ "path": "Revolve", "operation": "build-step" },
{ "path": "Symmetry", "operation": "build-step" },
+ { "path": "Offset", "operation": "build-step" },
{ "path": "PMI", "operation": "build-step" },
{ "path": "Templates", "operation": "build-step" },
{ "path": "Integration", "operation": "build-step" }
diff --git a/fixtures/Invalid/Offset/complete-remove.firmament b/fixtures/Invalid/Offset/complete-remove.firmament
new file mode 100644
index 00000000..117d0b8b
--- /dev/null
+++ b/fixtures/Invalid/Offset/complete-remove.firmament
@@ -0,0 +1,9 @@
+Model CompleteOffsetRemove {
+ Units: mm
+ Rect2 Stock { Center: [0mm,0mm]; Size: [40mm,30mm] }
+ Profile StockProfile { Loop Outer { Stock.Bottom |> Stock.Right |> Stock.Top |> Stock.Left |> Close } }
+ Compose Plate {
+ Base StockBody { Profile: StockProfile; From: 0mm; To: 10mm }
+ RemoveOffset<Prism> Invalid { Target: Plate; On: Top; Profile: StockProfile; Termination: ThroughAll }
+ }
+}
diff --git a/fixtures/Invalid/Offset/disconnected-add.firmament b/fixtures/Invalid/Offset/disconnected-add.firmament
new file mode 100644
index 00000000..ac4f8d4d
--- /dev/null
+++ b/fixtures/Invalid/Offset/disconnected-add.firmament
@@ -0,0 +1,11 @@
+Model DisconnectedOffsetAdd {
+ Units: mm
+ Rect2 Stock { Center: [0mm,0mm]; Size: [40mm,30mm] }
+ Rect2 Tool { Center: [80mm,0mm]; Size: [4mm,4mm] }
+ Profile StockProfile { Loop Outer { Stock.Bottom |> Stock.Right |> Stock.Top |> Stock.Left |> Close } }
+ Profile ToolProfile { Loop Outer { Tool.Bottom |> Tool.Right |> Tool.Top |> Tool.Left |> Close } }
+ Compose Plate {
+ Base StockBody { Profile: StockProfile; From: 0mm; To: 10mm }
+ AddOffset<Prism> Invalid { Target: Plate; On: Top; Profile: ToolProfile; Height: 3mm }
+ }
+}
diff --git a/fixtures/Invalid/Offset/invalid-axis.firmament b/fixtures/Invalid/Offset/invalid-axis.firmament
new file mode 100644
index 00000000..905d896d
--- /dev/null
+++ b/fixtures/Invalid/Offset/invalid-axis.firmament
@@ -0,0 +1,11 @@
+Model InvalidAxisOffset {
+ Units: mm
+ Rect2 Stock { Center: [0mm,0mm]; Size: [40mm,30mm] }
+ Rect2 Tool { Center: [0mm,0mm]; Size: [8mm,6mm] }
+ Profile StockProfile { Loop Outer { Stock.Bottom |> Stock.Right |> Stock.Top |> Stock.Left |> Close } }
+ Profile ToolProfile { Loop Outer { Tool.Bottom |> Tool.Right |> Tool.Top |> Tool.Left |> Close } }
+ Compose Plate {
+ Base StockBody { Profile: StockProfile; From: 0mm; To: 10mm }
+ RemoveOffset<Prism> Invalid { Target: Plate; On: Top; Profile: ToolProfile; Along: +X; Depth: 2mm }
+ }
+}
diff --git a/fixtures/Invalid/Offset/no-intersection.firmament b/fixtures/Invalid/Offset/no-intersection.firmament
new file mode 100644
index 00000000..5c57db05
--- /dev/null
+++ b/fixtures/Invalid/Offset/no-intersection.firmament
@@ -0,0 +1,11 @@
+Model NoIntersectionOffset {
+ Units: mm
+ Rect2 Stock { Center: [0mm,0mm]; Size: [40mm,30mm] }
+ Rect2 Tool { Center: [80mm,0mm]; Size: [4mm,4mm] }
+ Profile StockProfile { Loop Outer { Stock.Bottom |> Stock.Right |> Stock.Top |> Stock.Left |> Close } }
+ Profile ToolProfile { Loop Outer { Tool.Bottom |> Tool.Right |> Tool.Top |> Tool.Left |> Close } }
+ Compose Plate {
+ Base StockBody { Profile: StockProfile; From: 0mm; To: 10mm }
+ RemoveOffset<Prism> Invalid { Target: Plate; On: Top; Profile: ToolProfile; Depth: 2mm }
+ }
+}
diff --git a/fixtures/Invalid/Offset/splitting-remove.firmament b/fixtures/Invalid/Offset/splitting-remove.firmament
new file mode 100644
index 00000000..e907ee3b
--- /dev/null
+++ b/fixtures/Invalid/Offset/splitting-remove.firmament
@@ -0,0 +1,11 @@
+Model SplittingOffsetRemove {
+ Units: mm
+ Rect2 Stock { Center: [0mm,0mm]; Size: [40mm,30mm] }
+ Rect2 Tool { Center: [0mm,0mm]; Size: [4mm,40mm] }
+ Profile StockProfile { Loop Outer { Stock.Bottom |> Stock.Right |> Stock.Top |> Stock.Left |> Close } }
+ Profile ToolProfile { Loop Outer { Tool.Bottom |> Tool.Right |> Tool.Top |> Tool.Left |> Close } }
+ Compose Plate {
+ Base StockBody { Profile: StockProfile; From: 0mm; To: 10mm }
+ RemoveOffset<Prism> Invalid { Target: Plate; On: Top; Profile: ToolProfile; Termination: ThroughAll }
+ }
+}
diff --git a/fixtures/Invalid/Offset/tangent-add.firmament b/fixtures/Invalid/Offset/tangent-add.firmament
new file mode 100644
index 00000000..e30fea9e
--- /dev/null
+++ b/fixtures/Invalid/Offset/tangent-add.firmament
@@ -0,0 +1,11 @@
+Model TangentOffsetAdd {
+ Units: mm
+ Rect2 Stock { Center: [0mm,0mm]; Size: [40mm,30mm] }
+ Rect2 Tool { Center: [22mm,0mm]; Size: [4mm,4mm] }
+ Profile StockProfile { Loop Outer { Stock.Bottom |> Stock.Right |> Stock.Top |> Stock.Left |> Close } }
+ Profile ToolProfile { Loop Outer { Tool.Bottom |> Tool.Right |> Tool.Top |> Tool.Left |> Close } }
+ Compose Plate {
+ Base StockBody { Profile: StockProfile; From: 0mm; To: 10mm }
+ AddOffset<Prism> Invalid { Target: Plate; On: Top; Profile: ToolProfile; Height: 2mm }
+ }
+}
diff --git a/fixtures/Invalid/Offset/zero-depth.firmament b/fixtures/Invalid/Offset/zero-depth.firmament
new file mode 100644
index 00000000..95c0a8a4
--- /dev/null
+++ b/fixtures/Invalid/Offset/zero-depth.firmament
@@ -0,0 +1,11 @@
+Model ZeroDepthOffset {
+ Units: mm
+ Rect2 Stock { Center: [0mm,0mm]; Size: [40mm,30mm] }
+ Rect2 Tool { Center: [18mm,0mm]; Size: [10mm,6mm] }
+ Profile StockProfile { Loop Outer { Stock.Bottom |> Stock.Right |> Stock.Top |> Stock.Left |> Close } }
+ Profile ToolProfile { Loop Outer { Tool.Bottom |> Tool.Right |> Tool.Top |> Tool.Left |> Close } }
+ Compose Plate {
+ Base StockBody { Profile: StockProfile; From: 0mm; To: 10mm }
+ RemoveOffset<Prism> Invalid { Target: Plate; On: Top; Profile: ToolProfile; Depth: 0mm }
+ }
+}
diff --git a/fixtures/Invalid/Offset/zero-height.firmament b/fixtures/Invalid/Offset/zero-height.firmament
new file mode 100644
index 00000000..fbc79333
--- /dev/null
+++ b/fixtures/Invalid/Offset/zero-height.firmament
@@ -0,0 +1,11 @@
+Model ZeroHeightOffset {
+ Units: mm
+ Rect2 Stock { Center: [0mm,0mm]; Size: [40mm,30mm] }
+ Rect2 Tool { Center: [0mm,0mm]; Size: [8mm,6mm] }
+ Profile StockProfile { Loop Outer { Stock.Bottom |> Stock.Right |> Stock.Top |> Stock.Left |> Close } }
+ Profile ToolProfile { Loop Outer { Tool.Bottom |> Tool.Right |> Tool.Top |> Tool.Left |> Close } }
+ Compose Plate {
+ Base StockBody { Profile: StockProfile; From: 0mm; To: 10mm }
+ AddOffset<Prism> Invalid { Target: Plate; On: Top; Profile: ToolProfile; Height: 0mm }
+ }
+}
diff --git a/tools/vscode-firmament/syntaxes/firmament.tmLanguage.json b/tools/vscode-firmament/syntaxes/firmament.tmLanguage.json
index 46dd5499..09bbde07 100644
--- a/tools/vscode-firmament/syntaxes/firmament.tmLanguage.json
+++ b/tools/vscode-firmament/syntaxes/firmament.tmLanguage.json
@@ -31,7 +31,7 @@
"patterns": [
{
"name": "meta.feature.generic.firmament",
- "match": "\\b(Hole|Slot)(<)(Shaft|Counterbore|Countersink|Capsule|RoundedRectangle)(>)",
+ "match": "\\b(Hole|Slot|AddOffset|RemoveOffset)(<)(Shaft|Counterbore|Countersink|Capsule|RoundedRectangle|Prism|Cylinder|Sphere)(>)",
"captures": {
"1": { "name": "keyword.declaration.feature.firmament" },
"2": { "name": "punctuation.definition.generic.begin.firmament" },
@@ -49,7 +49,7 @@
},
{
"name": "keyword.declaration.firmament",
- "match": "\\b(?:Model|Units|Use|Enum|Box|Cylinder|Cone|Sphere|Torus|RoundedBox|Frustum|Concept|Struct|Construction|Plane|Path|Profile|ProfileDelta|Sweep|Compose|Boss|Pocket|Modify|Selection|Record|Static|Table|Template|Pattern|Match|Require|Pmi|Datum|HoleDiameter|Assert|InlineStep|Recognize|Replace|EdgeFinish|Hole|Slot|Region|Segment|Loop|Base|Extrude|SheetMetal|Flange|Analysis|Fixed|Force|Material|Results|Lattice)\\b"
+ "match": "\\b(?:Model|Units|Use|Enum|Box|Cylinder|Cone|Sphere|Torus|RoundedBox|Frustum|Concept|Struct|Construction|Plane|Path|Profile|ProfileDelta|Sweep|Compose|Boss|Pocket|AddOffset|RemoveOffset|Modify|Selection|Record|Static|Table|Template|Pattern|Match|Require|Pmi|Datum|HoleDiameter|Assert|InlineStep|Recognize|Replace|EdgeFinish|Hole|Slot|Region|Segment|Loop|Base|Extrude|SheetMetal|Flange|Analysis|Fixed|Force|Material|Results|Lattice)\\b"
},
{ "name": "keyword.control.firmament", "match": "\\b(?:with|With|From|Using|On|Over|As|Current|Key)\\b" }
]