Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Add Firmament perforation parsing and STEP export

Yuechen Lic3e84229c992
diff --git a/Aetheris.CLI/CliRunner.cs b/Aetheris.CLI/CliRunner.cs
index 7f6878b8..16870dd1 100644
--- a/Aetheris.CLI/CliRunner.cs
+++ b/Aetheris.CLI/CliRunner.cs
@@ -514,10 +514,11 @@ public static class CliRunner
features = build.Value.Export.Features,
engineeringFeatures = build.Value.Export.EngineeringFeatures,
patterns = build.Value.Export.Patterns,
+ perforation = build.Value.Export.Perforation,
structural = build.Value.Export.Structural,
piping = build.Value.Export.Piping,
gear = build.Value.Export.Gear,
- featureCount = (build.Value.Export.Features?.Count ?? 0) + (build.Value.Export.EngineeringFeatures?.Count ?? 0),
+ featureCount = (build.Value.Export.Features?.Count ?? 0) + (build.Value.Export.EngineeringFeatures?.Count ?? 0) + (build.Value.Export.Perforation is null ? 0 : 1),
inlineStepMigration = build.Value.Export.InlineStepMigration,
inlineStepReplacementAssist = build.Value.Export.InlineStepReplacementAssist,
diagnostics = build.Diagnostics.Select(d => new { d.Source, d.Message, severity = d.Severity.ToString() }),
diff --git a/Aetheris.Kernel.Core/Brep/Boolean/BrepBooleanBoxCylinderHoleBuilder.cs b/Aetheris.Kernel.Core/Brep/Boolean/BrepBooleanBoxCylinderHoleBuilder.cs
index c9a7184a..2d67ceaf 100644
--- a/Aetheris.Kernel.Core/Brep/Boolean/BrepBooleanBoxCylinderHoleBuilder.cs
+++ b/Aetheris.Kernel.Core/Brep/Boolean/BrepBooleanBoxCylinderHoleBuilder.cs
@@ -895,7 +895,7 @@ public static class BrepBooleanBoxCylinderHoleBuilder
var bindings = new BrepBindingModel();
for (var i = 0; i < 12; i++)
{
- bindings.AddEdgeBinding(new EdgeGeometryBinding(new EdgeId(i + 1), new CurveGeometryId(i + 1), new ParameterInterval(0d, 1d)));
+ bindings.AddEdgeBinding(new EdgeGeometryBinding(new EdgeId(i + 1), new CurveGeometryId(i + 1), new ParameterInterval(0d, lineCurves[i].Item2.Length)));
}
bindings.AddFaceBinding(new FaceGeometryBinding(bottomFace, new SurfaceGeometryId(1)));
diff --git a/Aetheris.Kernel.Firmament.Tests/FirmamentPerforationTests.cs b/Aetheris.Kernel.Firmament.Tests/FirmamentPerforationTests.cs
new file mode 100644
index 00000000..f818cf93
--- /dev/null
+++ b/Aetheris.Kernel.Firmament.Tests/FirmamentPerforationTests.cs
@@ -0,0 +1,98 @@
+using Aetheris.Kernel.Firmament.FirmamentV2;
+
+namespace Aetheris.Kernel.Firmament.Tests;
+
+public sealed class FirmamentPerforationTests
+{
+ private const string GridSource = """
+ Model PerforatedPanel {
+ Units: mm
+ Box Body { Size: [30mm, 30mm, 2mm] }
+ Modify Body {
+ Perforation Vent {
+ On: +Z
+ Diameter: 6mm
+ Layout: Grid
+ Pitch: 12mm
+ Margin: 3mm
+ }
+ }
+ }
+ """;
+
+ [Fact]
+ public void Grid_BuildsManifoldStepAndPerInstanceWallCorrespondence()
+ {
+ var built = FirmamentBuildAndExport.CompileSource(GridSource);
+ Assert.True(built.IsSuccess, string.Join(" | ", built.Diagnostics.Select(d => d.Message)));
+ var report = Assert.IsType<FirmamentPerforationReport>(built.Value.Perforation);
+ Assert.Equal(4, report.InstanceCount);
+ Assert.True(report.Manifold && report.StepReimportedManifold);
+ Assert.Equal(4, built.Value.RuntimeCorrespondence!.Descendants.Count);
+ Assert.All(built.Value.RuntimeCorrespondence.Descendants, descendant =>
+ {
+ Assert.NotNull(descendant.Face);
+ Assert.Equal("Body.Vent", descendant.ParentStableId);
+ });
+ Assert.Contains("Body.Vent", built.Value.RuntimeCorrespondence.SourceSpans!.Keys);
+ Assert.Equal("Body.Vent.Row0.Col0", report.InstanceIds[0]);
+ Assert.NotEmpty(built.Value.StepText);
+ }
+
+ [Fact]
+ public void Hex_StaggersRowsAndClipsFullOpenings()
+ {
+ var parsed = FirmamentV2Parser.Parse(GridSource.Replace("Layout: Grid", "Layout: Hex", StringComparison.Ordinal));
+ Assert.True(parsed.IsSuccess, string.Join(" | ", parsed.Diagnostics));
+ var feature = Assert.Single(Assert.Single(parsed.Document!.ModifyBlocks!).Perforations!);
+ var plan = FirmamentPerforationPlanner.Plan(30, 30, feature);
+ Assert.True(plan.Succeeded, plan.Diagnostic);
+ Assert.Equal(-6, plan.Instances[0].X, 8);
+ Assert.Equal(0, plan.Instances.First(i => i.Row == 1).X, 8);
+ Assert.All(plan.Instances, instance =>
+ {
+ Assert.InRange(instance.X, -9, 9);
+ Assert.InRange(instance.Y, -9, 9);
+ });
+ }
+
+ [Fact]
+ public void InvalidPitchAndNoRoomFailWithSpecificDiagnostics()
+ {
+ var overlap = FirmamentBuildAndExport.CompileSource(GridSource.Replace("Pitch: 12mm", "Pitch: 6mm", StringComparison.Ordinal));
+ Assert.False(overlap.IsSuccess);
+ Assert.Contains(overlap.Diagnostics, d => d.Message.Contains("perforation-hole-overlap", StringComparison.Ordinal));
+ var noRoom = FirmamentBuildAndExport.CompileSource(GridSource.Replace("Margin: 3mm", "Margin: 15mm", StringComparison.Ordinal));
+ Assert.False(noRoom.IsSuccess);
+ Assert.Contains(noRoom.Diagnostics, d => d.Message.Contains("perforation-support-too-small", StringComparison.Ordinal));
+ }
+
+ [Fact]
+ public void CylinderSupport_ReportsExactTopologyBoundaryWithoutExportingUncutStock()
+ {
+ const string source = """
+ Model Sleeve {
+ Units: mm
+ Cylinder Tube { Radius: 20mm; Height: 60mm }
+ Modify Tube {
+ Perforation Vents { On: Wall; Diameter: 6mm; Layout: Hex; Pitch: 9mm; Margin: 8mm }
+ }
+ }
+ """;
+ var built = FirmamentBuildAndExport.CompileSource(source);
+ Assert.False(built.IsSuccess);
+ Assert.Contains(built.Diagnostics, d => d.Message.Contains("perforation-cylindrical-topology-unavailable", StringComparison.Ordinal));
+ }
+
+ [Fact]
+ public void SchemaAndLanguageService_ExposeCanonicalFields()
+ {
+ var schema = Assert.IsType<FirmamentConstructSchema>(FirmamentSemanticSchemas.Get("Perforation"));
+ Assert.Contains(schema.Fields, field => field.Name == "Diameter" && field.Required);
+ Assert.Contains(schema.Fields, field => field.Name == "Layout" && field.Choices.Contains("Hex"));
+ const string source = "Model X { Units: mm Box Body { Size: [30mm,30mm,2mm] } Modify Body { Perforation Vent {\n Dia";
+ var completion = FirmamentLanguageService.Complete(source, "x", "r1", source.Length);
+ Assert.Equal("Perforation", completion.Context);
+ Assert.Contains(completion.Fields, field => field.Name == "Diameter");
+ }
+}
diff --git a/Aetheris.Kernel.Firmament.Tests/FirmamentSemanticSchemaTests.cs b/Aetheris.Kernel.Firmament.Tests/FirmamentSemanticSchemaTests.cs
index 73d11ac0..ac48c079 100644
--- a/Aetheris.Kernel.Firmament.Tests/FirmamentSemanticSchemaTests.cs
+++ b/Aetheris.Kernel.Firmament.Tests/FirmamentSemanticSchemaTests.cs
@@ -8,7 +8,7 @@ public sealed class FirmamentSemanticSchemaTests
public void GeneratedRegistry_IsStableOptInAndCoversFirstConstructs()
{
Assert.Equal("firmament-semantic-schema/1", FirmamentSemanticSchemas.Version);
- Assert.Equal(["Box", "Concept", "Helix", "Hole", "Loft"], FirmamentSemanticSchemas.All.Select(s => s.Name));
+ Assert.Equal(["Box", "Concept", "Helix", "Hole", "Loft", "Perforation"], FirmamentSemanticSchemas.All.Select(s => s.Name));
var hole = Assert.IsType<FirmamentConstructSchema>(FirmamentSemanticSchemas.Get("Hole"));
var diameter = Assert.Single(hole.Fields, f => f.Name == "Diameter");
Assert.Equal("Hole.Diameter", diameter.Id.Value);
diff --git a/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs b/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs
index 7f940dd5..cf918b24 100644
--- a/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs
+++ b/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs
@@ -540,6 +540,10 @@ public static class FirmamentBuildAndExport
{
return standardPartExport;
}
+ if (TryExportV2PerforationBody(v2Parse.Document) is { } perforationExport)
+ {
+ return perforationExport;
+ }
// Do not let the existing semantic-hole route silently export the unmodified host.
// M9 has an explicit AIR/graph contract, but the authoritative single-body merge
@@ -2051,6 +2055,64 @@ public static class FirmamentBuildAndExport
return new BrepBody(body.Topology, geometry, body.Bindings, vertexPoints, safeBooleanComposition: null, body.ShellRepresentation);
}
+ private static KernelResult<FirmamentStepExportResult>? TryExportV2PerforationBody(FirmamentV2Document document)
+ {
+ var features = (document.ModifyBlocks ?? []).SelectMany(block => (block.Perforations ?? []).Select(feature => (block.TargetSolid, Feature: feature))).ToArray();
+ if (features.Length == 0) return null;
+ KernelResult<FirmamentStepExportResult> Failure(string diagnostic) =>
+ KernelResult<FirmamentStepExportResult>.Failure([new KernelDiagnostic(KernelDiagnosticCode.ValidationFailed, KernelDiagnosticSeverity.Error, diagnostic, "FirmamentV2.Perforation")]);
+ if (features.Length != 1 || document.Solids.Count != 1 || document.ModifyBlocks!.Any(block => block.SemanticHoles.Count > 0 || (block.EdgeFinishes?.Count ?? 0) > 0))
+ return Failure("perforation-composition-unsupported: X0 admits one Perforation on one Box without other Modify features");
+ var (target, feature) = features[0];
+ if (document.Solid.Name != target || document.Solid.Box is not { Size.Count: 3 } box)
+ return Failure("perforation-cylindrical-topology-unavailable: the piping authority constructs constant-thickness annular stock, but the current BRep Boolean route does not materialize radial cylinder-to-cylinder intersections on its wall");
+ var plan = FirmamentPerforationPlanner.Plan(box.Size[0], box.Size[1], feature);
+ if (!plan.Succeeded) return Failure(plan.Diagnostic!);
+ var featureId = $"{target}.{feature.Name}";
+ var axis = Direction3D.Create(new Vector3D(0, 0, 1));
+ var reference = Direction3D.Create(new Vector3D(1, 0, 0));
+ var extents = new AxisAlignedBoxExtents(-box.Size[0] / 2, box.Size[0] / 2, -box.Size[1] / 2, box.Size[1] / 2, 0, box.Size[2]);
+ var holes = plan.Instances.Select(instance =>
+ {
+ var center = new Point3D(instance.X, instance.Y, 0);
+ var cylinder = new RecognizedCylinder(center, axis, feature.Diameter / 2, 0, box.Size[2]);
+ return new SupportedBooleanHole(instance.StableId(featureId), new AnalyticSurface(AnalyticSurfaceKind.Cylinder, Cylinder: cylinder),
+ instance.X, instance.Y, center, new Point3D(instance.X, instance.Y, box.Size[2]), axis, reference,
+ feature.Diameter / 2, feature.Diameter / 2, SupportedBooleanHoleSpanKind.Through, 0, box.Size[2]);
+ }).ToArray();
+ var wallFaces = new Dictionary<string, FaceId>(StringComparer.Ordinal);
+ var duplicate = false;
+ // The regular layout planner proves non-interference and full edge clearance before this single topology build.
+ var built = BrepBooleanBoxCylinderHoleBuilder.BuildComposition(new SafeBooleanComposition(extents, holes), ToleranceContext.Default,
+ (id, face) => { if (!wallFaces.TryAdd(id, face)) duplicate = true; });
+ if (!built.IsSuccess || built.Value is null)
+ return Failure("perforation-brep-failed: " + string.Join(" | ", built.Diagnostics.Select(d => d.Message)));
+ var body = built.Value;
+ if (duplicate || wallFaces.Count != holes.Length || !FirmamentManifoldChecker.IsManifold(body))
+ return Failure("perforation-topology-invalid: wall provenance or manifold check failed");
+ var preflight = BrepExportPreflight.Validate(body);
+ if (!preflight.IsValid) return Failure("perforation-export-preflight-failed: " + string.Join(" | ", preflight.Diagnostics.Take(4).Select(d => $"{d.Code}: {d.Context}")));
+ var step = Step242Exporter.ExportBody(body);
+ if (!step.IsSuccess || step.Value is null) return Failure("perforation-step-export-failed: " + string.Join(" | ", step.Diagnostics.Select(d => d.Message)));
+ var reimport = Step242Importer.ImportBody(step.Value);
+ if (!reimport.IsSuccess || reimport.Value is null || !FirmamentManifoldChecker.IsManifold(reimport.Value))
+ return Failure("perforation-step-reimport-invalid: production STEP did not reimport as a manifold");
+ var descendants = holes.Select(hole => new SemanticTopologyDescendant(
+ $"material:perforation:{hole.FeatureId}:wall", "Face", SemanticTopologyRole.HoleWallFace,
+ $"perforation:{hole.FeatureId}", Face: wallFaces[hole.FeatureId!], ParentStableId: featureId,
+ Addressability: SemanticTopologyAddressability.DerivedStable)).ToArray();
+ var correspondence = new SemanticTopologyCorrespondence(featureId, descendants, ["Perforation", "BrepBooleanBoxCylinderHoleBuilder"])
+ {
+ SourceSpans = new Dictionary<string, FirmamentV2SourceSpan> { [featureId] = feature.SourceSpan }
+ };
+ var hash = Convert.ToHexString(SHA256.HashData(Encoding.UTF8.GetBytes(step.Value)));
+ var report = new FirmamentPerforationReport(featureId, feature.SupportFace, feature.Layout, feature.Diameter, feature.Pitch,
+ feature.Margin, feature.MinimumLigament, plan.Instances.Count, holes.Select(hole => hole.FeatureId!).ToArray(),
+ body.Topology.Vertices.Count(), body.Topology.Edges.Count(), body.Topology.Faces.Count(), true, true, hash);
+ return KernelResult<FirmamentStepExportResult>.Success(new FirmamentStepExportResult(step.Value, featureId, 0,
+ "perforation", "circular-through", Perforation: report) { RuntimeBody = body, RuntimeCorrespondence = correspondence });
+ }
+
private static KernelResult<FirmamentStepExportResult>? TryExportV2SemanticHoleBody(FirmamentV2Document document)
{
if ((document.ModifyBlocks ?? []).Any(m => (m.EdgeFinishes?.Count ?? 0) > 0)) return null;
diff --git a/Aetheris.Kernel.Firmament/FirmamentStepExportResult.cs b/Aetheris.Kernel.Firmament/FirmamentStepExportResult.cs
index 038d7798..cf3c5937 100644
--- a/Aetheris.Kernel.Firmament/FirmamentStepExportResult.cs
+++ b/Aetheris.Kernel.Firmament/FirmamentStepExportResult.cs
@@ -33,7 +33,8 @@ public sealed record FirmamentStepExportResult(
Aetheris.Kernel.Firmament.Piping.PipingReport? Piping = null,
FirmamentRevolveReport? Revolve = null,
FirmamentGearReport? Gear = null,
- Aetheris.Kernel.Firmament.FirmamentV2.FirmamentPlateauReport? Plateau = null)
+ Aetheris.Kernel.Firmament.FirmamentV2.FirmamentPlateauReport? Plateau = null,
+ FirmamentPerforationReport? Perforation = null)
{
// In-process display can use the exact body that was exported to STEP.
// It is intentionally absent from CLI/JSON artifact serialization.
@@ -41,6 +42,12 @@ public sealed record FirmamentStepExportResult(
[JsonIgnore] public SemanticTopologyCorrespondence? RuntimeCorrespondence { get; init; }
}
+public sealed record FirmamentPerforationReport(
+ string FeatureId, string Support, string Layout, double Diameter, double Pitch,
+ double Margin, double MinimumLigament, int InstanceCount,
+ IReadOnlyList<string> InstanceIds, int Vertices, int Edges, int Faces,
+ bool Manifold, bool StepReimportedManifold, string StepSha256);
+
public sealed record FirmamentGearItemReport(
string Name,
string Family,
diff --git a/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentLanguageService.cs b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentLanguageService.cs
index ac1f6637..683ef6ed 100644
--- a/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentLanguageService.cs
+++ b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentLanguageService.cs
@@ -26,7 +26,12 @@ public static class FirmamentLanguageService
IReadOnlyList<FirmamentAuthoringField> fields;
string context;
- if (WireFormAuthoring.IsInsideHelix(source, offset))
+ if (IsInsidePerforation(source, offset))
+ {
+ fields = FirmamentSchemaAuthoringFields.For("Perforation");
+ context = "Perforation";
+ }
+ else if (WireFormAuthoring.IsInsideHelix(source, offset))
{
fields = FirmamentSchemaAuthoringFields.For("Helix");
context = "Helix";
@@ -35,7 +40,7 @@ public static class FirmamentLanguageService
else
{
var entries = FirmamentSemanticSchemas.All
- .Where(item => item.Name is "Helix" or "Loft" && item.Name.StartsWith(prefix, StringComparison.OrdinalIgnoreCase) && item.Entry is not null)
+ .Where(item => item.Name is "Helix" or "Loft" or "Perforation" && item.Name.StartsWith(prefix, StringComparison.OrdinalIgnoreCase) && item.Entry is not null)
.Select(item => new FirmamentLanguageEntry(item.Id.Value, item.Name, item.Context ?? string.Empty, item.Entry!)).ToArray();
return new(document, revision, entries.Length > 0 ? "ConstructEntry" : "Unsupported",
prefixStart, prefix.Length, [], [], entries);
@@ -50,4 +55,11 @@ public static class FirmamentLanguageService
if (context == "Helix" && !present.Contains("Pitch") && !present.Contains("Height")) missing.Add("Pitch or Height");
return new(document, revision, context, prefixStart, prefix.Length, candidates, missing);
}
+
+ private static bool IsInsidePerforation(string source, int offset)
+ {
+ var prefix = source[..offset];
+ var header = Regex.Matches(prefix, @"\bPerforation\s+[A-Za-z_][A-Za-z0-9_]*\s*\{", RegexOptions.CultureInvariant).Cast<Match>().LastOrDefault();
+ return header is not null && !prefix[(header.Index + header.Length)..].Contains('}');
+ }
}
diff --git a/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentPerforationPlanner.cs b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentPerforationPlanner.cs
new file mode 100644
index 00000000..fe91a3d0
--- /dev/null
+++ b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentPerforationPlanner.cs
@@ -0,0 +1,66 @@
+namespace Aetheris.Kernel.Firmament.FirmamentV2;
+
+public sealed record FirmamentPerforationInstance(int Row, int Column, double X, double Y)
+{
+ public string StableId(string featureId) => $"{featureId}.Row{Row}.Col{Column}";
+}
+
+public sealed record FirmamentPerforationPlan(
+ IReadOnlyList<FirmamentPerforationInstance> Instances, string? Diagnostic)
+{
+ public bool Succeeded => Diagnostic is null;
+}
+
+/// <summary>Deterministic box face placement and DFM admission, independent of BRep ordering.</summary>
+public static class FirmamentPerforationPlanner
+{
+ private const int MaximumInstances = 1000;
+ private const double Tol = 1e-9;
+
+ public static FirmamentPerforationPlan Plan(double width, double height, FirmamentV2PerforationDecl feature)
+ {
+ if (feature.SupportFace != "+Z") return new([], "perforation-support-unsupported: only the planar +Z Box face is currently materialized");
+ if (feature.Layout is not ("Grid" or "Hex")) return new([], "perforation-layout-invalid: expected Grid or Hex");
+ if (!double.IsFinite(feature.Diameter) || feature.Diameter <= 0 || !double.IsFinite(feature.Pitch) || feature.Pitch <= 0)
+ return new([], "perforation-dimension-invalid: Diameter and Pitch must be positive finite lengths");
+ if (!double.IsFinite(feature.Margin) || feature.Margin < 0 || !double.IsFinite(feature.MinimumLigament) || feature.MinimumLigament < 0
+ || !double.IsFinite(feature.OffsetX) || !double.IsFinite(feature.OffsetY))
+ return new([], "perforation-policy-invalid: margin and ligament must be nonnegative; offsets must be finite");
+ if (feature.Pitch <= feature.Diameter + Tol || feature.Pitch - feature.Diameter + Tol < feature.MinimumLigament)
+ return new([], "perforation-hole-overlap: pitch must exceed diameter and satisfy MinimumLigament");
+ var radius = feature.Diameter / 2;
+ var xmin = -width / 2 + feature.Margin + radius;
+ var xmax = width / 2 - feature.Margin - radius;
+ var ymin = -height / 2 + feature.Margin + radius;
+ var ymax = height / 2 - feature.Margin - radius;
+ if (!double.IsFinite(xmin) || !double.IsFinite(xmax) || !double.IsFinite(ymin) || !double.IsFinite(ymax) || xmax < xmin - Tol || ymax < ymin - Tol)
+ return new([], "perforation-support-too-small: the support cannot fit a full opening and margin");
+ var rowPitch = feature.Layout == "Hex" ? feature.Pitch * Math.Sqrt(3) / 2 : feature.Pitch;
+ if (Math.Abs(feature.OffsetX) >= feature.Pitch || Math.Abs(feature.OffsetY) >= rowPitch)
+ return new([], "perforation-offset-invalid: offsets must remain within one lattice pitch");
+ if ((xmax - xmin) / feature.Pitch > MaximumInstances || (ymax - ymin) / rowPitch > MaximumInstances)
+ return new([], "perforation-count-exceeded: pattern dimensions exceed the bounded 1000-opening planner");
+ var xOrigin = xmin + ((xmax - xmin) % feature.Pitch) / 2;
+ var yOrigin = ymin + ((ymax - ymin) % rowPitch) / 2;
+ var result = new List<FirmamentPerforationInstance>();
+ // The default field is centered; indices remain anchored to this lattice when an offset clips holes.
+ var rows = Math.Min(MaximumInstances + 1, (int)Math.Ceiling((ymax - ymin) / rowPitch) + 2);
+ var columns = Math.Min(MaximumInstances + 1, (int)Math.Ceiling((xmax - xmin) / feature.Pitch) + 2);
+ for (var row = 0; row < rows; row++)
+ {
+ var y = yOrigin + feature.OffsetY + row * rowPitch;
+ if (y > ymax + Tol) break;
+ if (y < ymin - Tol) continue;
+ var stagger = feature.Layout == "Hex" && row % 2 == 1 ? feature.Pitch / 2 : 0;
+ for (var column = 0; column < columns; column++)
+ {
+ var x = xOrigin + feature.OffsetX + stagger + column * feature.Pitch;
+ if (x > xmax + Tol) break;
+ if (x < xmin - Tol) continue;
+ result.Add(new(row, column, x, y));
+ if (result.Count > MaximumInstances) return new([], "perforation-count-exceeded: at most 1000 openings are admitted");
+ }
+ }
+ return result.Count == 0 ? new([], "perforation-no-admissible-holes: offset and margin leave no full opening") : new(result, null);
+ }
+}
diff --git a/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Ast.cs b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Ast.cs
index a8fe3cc3..ec3e6b22 100644
--- a/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Ast.cs
+++ b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Ast.cs
@@ -177,7 +177,8 @@ public sealed record FirmamentV2ModifyBlock(
string TargetSolid,
IReadOnlyList<FirmamentV2RegionDecl> Regions,
IReadOnlyList<FirmamentV2SemanticHoleDecl> SemanticHoles,
- IReadOnlyList<FirmamentV2EdgeFinishDecl>? EdgeFinishes = null)
+ IReadOnlyList<FirmamentV2EdgeFinishDecl>? EdgeFinishes = null,
+ IReadOnlyList<FirmamentV2PerforationDecl>? Perforations = null)
{
public FirmamentV2ModifyBlock(string TargetSolid, IReadOnlyList<FirmamentV2RegionDecl> Regions) : this(TargetSolid, Regions, []) { }
}
@@ -300,6 +301,11 @@ public enum FirmamentV2ParseDisposition
RecognizedInvalid,
RecognizedValid
}
+/// <summary>One source-owned field of circular through openings; instances are compiler derived.</summary>
+public sealed record FirmamentV2PerforationDecl(
+ string Name, string SupportFace, string Layout, double Diameter, double Pitch,
+ double Margin, double MinimumLigament, double OffsetX, double OffsetY,
+ FirmamentV2SourceSpan SourceSpan);
public sealed record FirmamentV2ParseResult(
bool IsSuccess,
diff --git a/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Parser.cs b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Parser.cs
index 0fc4ec0e..acdd561f 100644
--- a/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Parser.cs
+++ b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Parser.cs
@@ -290,6 +290,7 @@ public static class FirmamentV2Parser
// Match the declaration-shaped header first; variant admission belongs in the
// binder so a misspelled family can never disappear from a Modify block.
private static readonly Regex CanonicalHoleHeaderRegex = new(@"\bHole\s*<\s*(?<variant>[A-Za-z_][A-Za-z0-9_]*)\s*>\s+(?<name>[A-Za-z_][A-Za-z0-9_]*)\s*\{", RegexOptions.CultureInvariant);
+ private static readonly Regex CanonicalPerforationHeaderRegex = new(@"\bPerforation\s+(?<name>[A-Za-z_][A-Za-z0-9_]*)\s*\{", RegexOptions.CultureInvariant);
private static readonly Regex CanonicalEdgeHeaderRegex = new(@"\bEdgeFinish\s+(?<name>[A-Za-z_][A-Za-z0-9_]*)\s*\{", RegexOptions.CultureInvariant);
private static readonly Regex CanonicalRecognizeHeaderRegex = new(@"\bRecognize\s+(?<body>[A-Za-z_][A-Za-z0-9_]*)\s*\{", RegexOptions.CultureInvariant);
private static readonly Regex CanonicalRegionHeaderRegex = new(@"\bRegion\s+(?<name>[A-Za-z_][A-Za-z0-9_]*)\s*\{", RegexOptions.CultureInvariant);
@@ -1493,18 +1494,19 @@ public static class FirmamentV2Parser
{
var target = modify.Groups["target"].Value;
if (!byName.TryGetValue(target, out var solid)) return CanonicalFailure(diagnostics, ModifyTargetUnresolved);
- if (solid.Box is null) return CanonicalFailure(diagnostics, ModifyTargetNotSolid);
var open = body.IndexOf('{', modify.Index);
var close = FindMatchingBrace(body, open);
if (close < 0) return CanonicalFailure(diagnostics, CanonicalModifyMalformed);
var modifyBody = body[(open + 1)..close];
+ if (solid.Box is null && !CanonicalPerforationHeaderRegex.IsMatch(modifyBody)) return CanonicalFailure(diagnostics, ModifyTargetNotSolid);
var holes = ParseCanonicalHoles(modifyBody, solid, rootOpen + 1 + open + 1, diagnostics);
+ var perforations = ParseCanonicalPerforations(modifyBody, rootOpen + 1 + open + 1, diagnostics);
var finishes = ParseCanonicalEdgeFinishes(modifyBody, rootOpen + 1 + open + 1, diagnostics);
if (diagnostics.Any(IsFatalDiagnosticCode) || diagnostics.Contains(CanonicalPoint2Invalid) || diagnostics.Contains(CanonicalModifyMalformed) || diagnostics.Contains(CanonicalFieldUnknown))
return CanonicalFailure(diagnostics, CanonicalModifyMalformed);
// Empty Modify blocks are valid; feature admission belongs to the selected
// production route, not to a phase parser's minimum-count rule.
- modifies.Add(new FirmamentV2ModifyBlock(target, [], holes, finishes));
+ modifies.Add(new FirmamentV2ModifyBlock(target, [], holes, finishes, perforations));
}
var recognizedRegions = ParseCanonicalRecognizedRegions(body, byName, diagnostics);
@@ -1630,6 +1632,41 @@ public static class FirmamentV2Parser
};
}
+ private static IReadOnlyList<FirmamentV2PerforationDecl> ParseCanonicalPerforations(string body, int bodyOffset, List<string> diagnostics)
+ {
+ var result = new List<FirmamentV2PerforationDecl>();
+ var headers = CanonicalPerforationHeaderRegex.Matches(body);
+ if (Regex.Matches(body, @"\bPerforation\s+[A-Za-z_]", RegexOptions.CultureInvariant).Count != headers.Count)
+ diagnostics.Add(CanonicalModifyMalformed);
+ var names = new HashSet<string>(StringComparer.Ordinal);
+ foreach (Match header in headers)
+ {
+ var open = body.IndexOf('{', header.Index);
+ var close = FindMatchingBrace(body, open);
+ if (close < 0 || !names.Add(header.Groups["name"].Value)) { diagnostics.Add(CanonicalModifyMalformed); continue; }
+ var featureBody = body[(open + 1)..close];
+ if (CanonicalBodyHasUnknownField(featureBody, ["On", "Diameter", "Layout", "Pitch", "Margin", "MinimumLigament", "OffsetX", "OffsetY"]))
+ { diagnostics.Add(CanonicalFieldUnknown); continue; }
+ string? ReadWord(string name) => Regex.Match(featureBody, $@"\b{name}\s*:\s*(?<value>[A-Za-z_+\-][A-Za-z_0-9+\-]*)\b", RegexOptions.CultureInvariant) is { Success: true } match ? match.Groups["value"].Value : null;
+ double ReadLength(string name, double fallback)
+ {
+ var match = Regex.Match(featureBody, $@"\b{name}\s*:\s*(?<value>[-+0-9.eE]+)mm\b", RegexOptions.CultureInvariant);
+ return !match.Success
+ ? Regex.IsMatch(featureBody, $@"\b{name}\s*:", RegexOptions.CultureInvariant) ? double.NaN : fallback
+ : double.TryParse(match.Groups["value"].Value, NumberStyles.Float, CultureInfo.InvariantCulture, out var value) ? value : double.NaN;
+ }
+ var on = ReadWord("On"); var layout = ReadWord("Layout");
+ var diameter = ReadLength("Diameter", double.NaN); var pitch = ReadLength("Pitch", double.NaN);
+ var margin = ReadLength("Margin", 0); var ligament = ReadLength("MinimumLigament", 0);
+ var offsetX = ReadLength("OffsetX", 0); var offsetY = ReadLength("OffsetY", 0);
+ if (on is null || layout is null || !double.IsFinite(diameter) || diameter <= 0 || !double.IsFinite(pitch) || pitch <= 0 || !double.IsFinite(margin) || margin < 0 || !double.IsFinite(ligament) || ligament < 0 || !double.IsFinite(offsetX) || !double.IsFinite(offsetY))
+ { diagnostics.Add("perforation-field-invalid"); continue; }
+ result.Add(new(header.Groups["name"].Value, on, layout, diameter, pitch, margin, ligament, offsetX, offsetY,
+ new FirmamentV2SourceSpan(bodyOffset + header.Index, close - header.Index + 1)));
+ }
+ return result;
+ }
+
private static IReadOnlyList<FirmamentV2SemanticHoleDecl> ParseCanonicalHoles(string body, FirmamentV2SolidBinding solid, int bodyOffset, List<string> diagnostics)
{
var holes = new List<FirmamentV2SemanticHoleDecl>();
@@ -2140,7 +2177,7 @@ public static class FirmamentV2Parser
|| code.StartsWith(ConceptIrResolver.PointProjectionUnsupported, StringComparison.Ordinal)
|| code.StartsWith("firmament-static-", StringComparison.Ordinal);
- public static bool IsFatalDiagnosticCode(string code) => code.StartsWith("firmament-v2-hole-wall-", StringComparison.Ordinal) || code.StartsWith(RevolveAuthoringParser.Prefix, StringComparison.Ordinal) || code.StartsWith(FirmamentV2FeatureExpansion.Prefix, StringComparison.Ordinal) || code.StartsWith("firmament-pipeline-", StringComparison.Ordinal) || code.StartsWith("firmament-profile-pipeline-", StringComparison.Ordinal) || code.StartsWith("firmament-profile-traceloop-", StringComparison.Ordinal) || code.StartsWith("firmament-profile-segment-", StringComparison.Ordinal) || code.StartsWith("firmament-boss-", StringComparison.Ordinal) || code.StartsWith("firmament-pocket-", StringComparison.Ordinal) || code.StartsWith("feature-support-", StringComparison.Ordinal) || code.StartsWith("compose-role-cardinality:", StringComparison.Ordinal) || code.StartsWith(ModifyTargetNotBoundToActiveCompose, StringComparison.Ordinal) || code.StartsWith("firmament-v2-assert-volume-", StringComparison.Ordinal) || code.StartsWith(SemanticConstraintMalformed, StringComparison.Ordinal) || code.StartsWith(SemanticConstraintUnsupported, StringComparison.Ordinal) || code.StartsWith(SemanticConstraintDimensionMismatch, StringComparison.Ordinal) || code.StartsWith(SemanticConstraintValidationFailed, StringComparison.Ordinal) || code.StartsWith(PmiProjectionUnknownRequire, StringComparison.Ordinal) || code.StartsWith(PmiProjectionUnsupportedKind, StringComparison.Ordinal) || code.StartsWith(PmiProjectedFieldMustNotOverrideSourceConstraint, StringComparison.Ordinal) || code.StartsWith(AssertVolumeKindUnsupported, StringComparison.Ordinal) || code.StartsWith(CanonicalDeclarationUnknown + ":", StringComparison.Ordinal) || code.StartsWith(CanonicalConstructNotYetSupported + ":", StringComparison.Ordinal) || code.StartsWith(EdgeFinishProfileComposeBoundaryUnsupported, StringComparison.Ordinal) || IsConceptFatalDiagnostic(code) || code is UnknownConstructionPolicy or PrimitiveDoesNotSatisfyHollowConstructible or WallThicknessRequired or WallThicknessMustBePositive or UnsupportedOpening or MultipleOpeningsNotSupported or Phase3EdgeFinishSyntaxInvalid or PrimitiveFieldMissing or PrimitiveFieldUnknown or PrimitiveFieldInvalid or MissingModel or MissingUnits or MissingSolid or UnsupportedConstruct or UnknownRecordType or BoxMissingSize or BoxSizeArity or DegenerateDimension or NameUnresolved or DuplicateName or WithRequiresRecord or WithRequiresBoxRecord or WithFieldNotFound or WithFieldTypeMismatch or WithForwardReference or WithDerivedRecordInvalid or ExposeBlockUnsupported or ExposeRequiresBoxRecord or ExposeAliasDuplicate or ExposeAliasInvalid or SelectorUnsupported or SelectorAxisInvalid or SelectorSubselectorUnsupported or FatArrowOutsideExpose or RawBackendIdReferenceForbidden or ModifyTargetUnresolved or ModifyTargetNotSolid or RegionUnsupported or RegionAttachmentSelectorUnsupported or CutUnsupported or CutToolUnsupported or CylinderRadiusMissing or CylinderRadiusInvalid or CylinderRadiusNotFinite or ThroughSelectorUnsupported or AliasUnresolved or AliasRefTypeUnsupported or SideHoleAliasMustResolveToFace or SideHoleAliasResolvesToUnsupportedFace or SideHoleOnlyPlusXMinusXSupported or SideHoleRouteUnsupported or SideHoleSameFaceUnsupported or SideHoleAxisNotYetSupported or SideHoleRadiusExceedsClearance or CylinderCenterInvalid or CylinderCenterArityInvalid or CylinderCenterNotFinite or SideHoleCenterExceedsClearance or HoleVariantUnknown or HoleEntryFaceMissing or HoleCenterMissing or HoleShaftMissing or HoleEndMissing or HoleDiameterInvalid or HoleDepthInvalid or HoleCounterboreInvalid or HoleCountersinkInvalid or PmiKindUnknown or PmiTargetMissing or PmiTargetUnresolved or PmiDiameterInvalid or PmiDuplicateName or InlineStepUnknownBody or InlineStepUnknownFace or PmiImportedTargetNotFace or PmiImportedTargetRequiresCanonicalStep or PmiInvalidImportedTarget or InlineStepPathMissing or InlineStepPathInvalid or InlineStepFileMissing or InlineStepRequiresCanonical or UnknownRecognitionBody or UnknownRecognitionFace or DuplicateRegion or UnknownRecognitionRegion or InvalidRecognitionKind or InvalidRecognitionConfidence or PmiRecognizedRegionKindMismatch or UnknownReplacementBody or UnknownReplacementRegion or ReplacementKindMismatch or ReplacementFaceUnresolved or ReplacementUnsupportedKind or ReplacementVerificationFailed or ReplacementRadiusInvalid or ReplacementEndUnsupported or LetDuplicateName or LetUnknownType or LetMismatch or LetInvalidLiteral or LetUnitMismatch or LetLiteralOnly or LetRecordDuplicateName or LetRecordDuplicateField or LetReferenceUnknownRecord or LetReferenceUnknownField or LetReferenceNonRecord or LetReferenceRecordUsedAsValue or ExpressionUnknownSymbol or ExpressionUnknownRecord or ExpressionUnknownField or ExpressionRecordUsedAsValue or ExpressionScalarUsedAsRecord or ExpressionTypeMismatch or ExpressionInvalidOperator or ExpressionDivisionByZero or ExpressionCycle or ExpressionUnsupported or ToleranceInvalidType or ToleranceUnitMismatch or ToleranceInvalidLiteral or ToleranceNegativeBilateral or ToleranceMissingMinus or ToleranceMissingPlus or ToleranceUnsupported or RecognitionEvidenceRadiusInvalid or RecognitionEvidenceSurfaceFamilyUnknown or RecognitionEvidenceAxisInvalid or SemanticProposalKindMismatch or SemanticProposalRadiusInvalid or SemanticProposalTargetUnresolved or SemanticProposalEndUnsupported or ConceptUnknownFamily or ConceptUnknownConcept or ConceptMissingRequiredField or ConceptUnknownField or ConceptDuplicateField or ConceptFieldTypeMismatch or ConceptInvalidTarget or ConceptDescriptorUnavailable or PmiDuplicateBlock or PmiDuplicateRecord or PmiDuplicateDatum or PmiUnknownRecordKind or PmiMissingRequiredField or PmiUnknownField or PmiDuplicateField or PmiInvalidTarget or PmiUnknownDatum or PmiDimensionTypeMismatch or PmiDimensionMissingTolerance or PmiToleranceTypeMismatch or StandaloneFillRegionRequired or UnsupportedStandaloneFillPattern or InvalidCellCount or CellSizeMustBePositive or StrutRadiusMustBePositive or NodeRadiusMustBePositive or MaterialBoundsMismatch or StandaloneFillMultipleUnsupported;
+ public static bool IsFatalDiagnosticCode(string code) => code.StartsWith("perforation-", StringComparison.Ordinal) || code.StartsWith("firmament-v2-hole-wall-", StringComparison.Ordinal) || code.StartsWith(RevolveAuthoringParser.Prefix, StringComparison.Ordinal) || code.StartsWith(FirmamentV2FeatureExpansion.Prefix, StringComparison.Ordinal) || code.StartsWith("firmament-pipeline-", StringComparison.Ordinal) || code.StartsWith("firmament-profile-pipeline-", StringComparison.Ordinal) || code.StartsWith("firmament-profile-traceloop-", StringComparison.Ordinal) || code.StartsWith("firmament-profile-segment-", StringComparison.Ordinal) || code.StartsWith("firmament-boss-", StringComparison.Ordinal) || code.StartsWith("firmament-pocket-", StringComparison.Ordinal) || code.StartsWith("feature-support-", StringComparison.Ordinal) || code.StartsWith("compose-role-cardinality:", StringComparison.Ordinal) || code.StartsWith(ModifyTargetNotBoundToActiveCompose, StringComparison.Ordinal) || code.StartsWith("firmament-v2-assert-volume-", StringComparison.Ordinal) || code.StartsWith(SemanticConstraintMalformed, StringComparison.Ordinal) || code.StartsWith(SemanticConstraintUnsupported, StringComparison.Ordinal) || code.StartsWith(SemanticConstraintDimensionMismatch, StringComparison.Ordinal) || code.StartsWith(SemanticConstraintValidationFailed, StringComparison.Ordinal) || code.StartsWith(PmiProjectionUnknownRequire, StringComparison.Ordinal) || code.StartsWith(PmiProjectionUnsupportedKind, StringComparison.Ordinal) || code.StartsWith(PmiProjectedFieldMustNotOverrideSourceConstraint, StringComparison.Ordinal) || code.StartsWith(AssertVolumeKindUnsupported, StringComparison.Ordinal) || code.StartsWith(CanonicalDeclarationUnknown + ":", StringComparison.Ordinal) || code.StartsWith(CanonicalConstructNotYetSupported + ":", StringComparison.Ordinal) || code.StartsWith(EdgeFinishProfileComposeBoundaryUnsupported, StringComparison.Ordinal) || IsConceptFatalDiagnostic(code) || code is UnknownConstructionPolicy or PrimitiveDoesNotSatisfyHollowConstructible or WallThicknessRequired or WallThicknessMustBePositive or UnsupportedOpening or MultipleOpeningsNotSupported or Phase3EdgeFinishSyntaxInvalid or PrimitiveFieldMissing or PrimitiveFieldUnknown or PrimitiveFieldInvalid or MissingModel or MissingUnits or MissingSolid or UnsupportedConstruct or UnknownRecordType or BoxMissingSize or BoxSizeArity or DegenerateDimension or NameUnresolved or DuplicateName or WithRequiresRecord or WithRequiresBoxRecord or WithFieldNotFound or WithFieldTypeMismatch or WithForwardReference or WithDerivedRecordInvalid or ExposeBlockUnsupported or ExposeRequiresBoxRecord or ExposeAliasDuplicate or ExposeAliasInvalid or SelectorUnsupported or SelectorAxisInvalid or SelectorSubselectorUnsupported or FatArrowOutsideExpose or RawBackendIdReferenceForbidden or ModifyTargetUnresolved or ModifyTargetNotSolid or RegionUnsupported or RegionAttachmentSelectorUnsupported or CutUnsupported or CutToolUnsupported or CylinderRadiusMissing or CylinderRadiusInvalid or CylinderRadiusNotFinite or ThroughSelectorUnsupported or AliasUnresolved or AliasRefTypeUnsupported or SideHoleAliasMustResolveToFace or SideHoleAliasResolvesToUnsupportedFace or SideHoleOnlyPlusXMinusXSupported or SideHoleRouteUnsupported or SideHoleSameFaceUnsupported or SideHoleAxisNotYetSupported or SideHoleRadiusExceedsClearance or CylinderCenterInvalid or CylinderCenterArityInvalid or CylinderCenterNotFinite or SideHoleCenterExceedsClearance or HoleVariantUnknown or HoleEntryFaceMissing or HoleCenterMissing or HoleShaftMissing or HoleEndMissing or HoleDiameterInvalid or HoleDepthInvalid or HoleCounterboreInvalid or HoleCountersinkInvalid or PmiKindUnknown or PmiTargetMissing or PmiTargetUnresolved or PmiDiameterInvalid or PmiDuplicateName or InlineStepUnknownBody or InlineStepUnknownFace or PmiImportedTargetNotFace or PmiImportedTargetRequiresCanonicalStep or PmiInvalidImportedTarget or InlineStepPathMissing or InlineStepPathInvalid or InlineStepFileMissing or InlineStepRequiresCanonical or UnknownRecognitionBody or UnknownRecognitionFace or DuplicateRegion or UnknownRecognitionRegion or InvalidRecognitionKind or InvalidRecognitionConfidence or PmiRecognizedRegionKindMismatch or UnknownReplacementBody or UnknownReplacementRegion or ReplacementKindMismatch or ReplacementFaceUnresolved or ReplacementUnsupportedKind or ReplacementVerificationFailed or ReplacementRadiusInvalid or ReplacementEndUnsupported or LetDuplicateName or LetUnknownType or LetMismatch or LetInvalidLiteral or LetUnitMismatch or LetLiteralOnly or LetRecordDuplicateName or LetRecordDuplicateField or LetReferenceUnknownRecord or LetReferenceUnknownField or LetReferenceNonRecord or LetReferenceRecordUsedAsValue or ExpressionUnknownSymbol or ExpressionUnknownRecord or ExpressionUnknownField or ExpressionRecordUsedAsValue or ExpressionScalarUsedAsRecord or ExpressionTypeMismatch or ExpressionInvalidOperator or ExpressionDivisionByZero or ExpressionCycle or ExpressionUnsupported or ToleranceInvalidType or ToleranceUnitMismatch or ToleranceInvalidLiteral or ToleranceNegativeBilateral or ToleranceMissingMinus or ToleranceMissingPlus or ToleranceUnsupported or RecognitionEvidenceRadiusInvalid or RecognitionEvidenceSurfaceFamilyUnknown or RecognitionEvidenceAxisInvalid or SemanticProposalKindMismatch or SemanticProposalRadiusInvalid or SemanticProposalTargetUnresolved or SemanticProposalEndUnsupported or ConceptUnknownFamily or ConceptUnknownConcept or ConceptMissingRequiredField or ConceptUnknownField or ConceptDuplicateField or ConceptFieldTypeMismatch or ConceptInvalidTarget or ConceptDescriptorUnavailable or PmiDuplicateBlock or PmiDuplicateRecord or PmiDuplicateDatum or PmiUnknownRecordKind or PmiMissingRequiredField or PmiUnknownField or PmiDuplicateField or PmiInvalidTarget or PmiUnknownDatum or PmiDimensionTypeMismatch or PmiDimensionMissingTolerance or PmiToleranceTypeMismatch or StandaloneFillRegionRequired or UnsupportedStandaloneFillPattern or InvalidCellCount or CellSizeMustBePositive or StrutRadiusMustBePositive or NodeRadiusMustBePositive or MaterialBoundsMismatch or StandaloneFillMultipleUnsupported;
private static IReadOnlyList<FirmamentV2Exposure> ParseExposures(string body, List<string> diagnostics)
{
diff --git a/Aetheris.Kernel.Firmament/FirmamentV2/SemanticConstructDeclarations.cs b/Aetheris.Kernel.Firmament/FirmamentV2/SemanticConstructDeclarations.cs
index cd61a864..01bc86bd 100644
--- a/Aetheris.Kernel.Firmament/FirmamentV2/SemanticConstructDeclarations.cs
+++ b/Aetheris.Kernel.Firmament/FirmamentV2/SemanticConstructDeclarations.cs
@@ -18,6 +18,19 @@ public static class HoleSemanticDeclaration
public static double ProjectDiameter(FirmamentV2SemanticHoleDecl instance) => instance.ShaftDiameter;
}
+[FirmamentConstruct("Perforation", "Perforation", Context = "Modify Box", Entry = "Modify Body { Perforation Vent { On: +Z; Diameter: 6mm; Layout: Hex; Pitch: 9mm; Margin: 8mm } }", Description = "One semantic field of circular through openings on a planar Box face.")]
+[FirmamentField("On", "On", FirmamentSchemaValueKind.FaceSelector, Required = true, Description = "Semantic support face; X0 admits +Z on Box.")]
+[FirmamentField("Diameter", "Diameter", FirmamentSchemaValueKind.Length, Required = true, Description = "Circular opening diameter.")]
+[FirmamentField("Layout", "Layout", FirmamentSchemaValueKind.Choice, Required = true, Choices = ["Grid", "Hex"], Description = "Grid rows or staggered hex rows.")]
+[FirmamentField("Pitch", "Pitch", FirmamentSchemaValueKind.Length, Required = true, Description = "Center spacing; Hex row spacing is sqrt(3)/2 times Pitch.")]
+[FirmamentField("Margin", "Margin", FirmamentSchemaValueKind.Length, Default = "0mm", Description = "Clear material from each support edge to opening rim.")]
+[FirmamentField("MinimumLigament", "MinimumLigament", FirmamentSchemaValueKind.Length, Default = "0mm", Description = "Additional minimum material between opening rims.")]
+[FirmamentField("OffsetX", "OffsetX", FirmamentSchemaValueKind.Length, Default = "0mm", Description = "Pattern shift in support X.")]
+[FirmamentField("OffsetY", "OffsetY", FirmamentSchemaValueKind.Length, Default = "0mm", Description = "Pattern shift in support Y.")]
+[FirmamentOutput("InstanceCount", "InstanceCount", "Count")]
+[FirmamentOutput("Wall", "Wall", "Face", SourceRole = nameof(Materializer.SemanticTopologyRole.HoleWallFace))]
+public static class PerforationSemanticDeclaration { }
+
[FirmamentConstruct("Helix", "Helix", Context = "WireForm", Entry = "Model HelixWitness {\n Units: mm\n WireForm Spring {\n Diameter: 2mm\n Material: Standard.Materials.StainlessSteel.304_Annealed\n StartFrame { Origin: [0mm, 0mm, 0mm]; Tangent: [1, 0, 0]; Up: [0, 0, 1] }\n Helix Winding { Radius: 6mm; Turns: 1; Pitch: 5mm; Handedness: RightHanded; StartPhase: 0deg }\n }\n}\n", CompatibilityAlias = "AxisCoil", Description = "WireForm centerline helix.")]
[FirmamentField("Radius", "Radius", FirmamentSchemaValueKind.Length, Required = true, Description = "Centerline radius.")]
[FirmamentField("Turns", "Turns", FirmamentSchemaValueKind.Scalar, Required = true, Description = "Number of winding turns.")]
diff --git a/docs/public/firmament/perforation.md b/docs/public/firmament/perforation.md
new file mode 100644
index 00000000..690a0c00
--- /dev/null
+++ b/docs/public/firmament/perforation.md
@@ -0,0 +1,32 @@
+# Circular perforation on a flat box face
+
+`Perforation` describes one field of circular through openings. The compiler places and clips its instances; source does not list individual holes.
+
+```firmament
+Model FlatHexPanel {
+ Units: mm
+ Box Panel { Size: [90mm, 70mm, 3mm] }
+ Modify Panel {
+ Perforation Vent {
+ On: +Z
+ Diameter: 6mm
+ Layout: Hex
+ Pitch: 9mm
+ Margin: 8mm
+ MinimumLigament: 2mm
+ }
+ }
+}
+```
+
+`On: +Z` binds the semantic top face of the Box. Its 2D frame uses world X and Y, with the box center as origin. `Layout: Grid` gives square rows; `Layout: Hex` shifts alternate rows by half the pitch and uses row spacing `Pitch * sqrt(3) / 2`. The default lattice is centered in the admissible region. `OffsetX` and `OffsetY` shift it in millimeters.
+
+`Margin` is material clearance between every hole rim and a box edge. A center outside that inset region is omitted; partial openings are never emitted. `Pitch` must exceed `Diameter` and leave at least `MinimumLigament` between adjacent rims. At most 1000 openings are admitted. The compiler reports the count and pattern-space identities such as `Panel.Vent.Row3.Col7`; every generated wall has source correspondence to the Perforation and its instance.
+
+Current production support is a single Perforation on a Box `+Z` face. Cylindrical supports, including constant-thickness piping sleeves, currently produce `perforation-cylindrical-topology-unavailable`: the BRep Boolean route does not construct radial cylinder-to-cylinder intersections on an annular wall. This source form does not export an unperforated sleeve as if it were complete.
+
+Reproduce the flat witness with:
+
+```text
+dotnet run --project Aetheris.CLI -- build fixtures/Canonical/Perforation/flat-hex-panel.firmament --output artifacts/local/perforation/flat-hex-panel.step --json
+```
diff --git a/docs/release/GEOM-PERFORATION-X0.md b/docs/release/GEOM-PERFORATION-X0.md
new file mode 100644
index 00000000..8472b745
--- /dev/null
+++ b/docs/release/GEOM-PERFORATION-X0.md
@@ -0,0 +1,31 @@
+# GEOM-PERFORATION-X0 — qualification record
+
+**Executive verdict: Meaningful progression.** A single authored `Perforation` now builds a field of circular through openings on the `+Z` face of a Box, with deterministic layout, DFM admission, wall provenance, manifold BRep, and STEP reimport. The requested perforated constant-thickness sleeve is still unavailable.
+
+## Implemented language and lowering
+
+The canonical form is `Modify Panel { Perforation Vent { On: +Z; Diameter: 6mm; Layout: Hex; Pitch: 9mm; Margin: 8mm; MinimumLigament: 2mm } }`. `Layout` admits `Grid` and `Hex`. `Pitch` is horizontal center spacing; hex rows are separated by `Pitch * sqrt(3) / 2` and alternate rows shift by half a pitch. A centered lattice is the default. Optional `OffsetX` and `OffsetY` move the lattice by less than one pitch. Holes whose full rim cannot maintain the margin are omitted. The compiler emits one source feature and pattern-space IDs `Panel.Vent.RowN.ColM`, independent of BRep face numbering. Runtime correspondence maps each generated cylindrical wall to its instance and the authored Perforation source span.
+
+The planner rejects nonpositive diameter/pitch, pitch less than or equal to diameter, insufficient `MinimumLigament`, negative margin/ligament, invalid offsets, supports too small for one opening, empty layouts, and more than 1000 openings. The materializer constructs all noninterfering analytic cylindrical voids in one bounded box composition. It checks closed manifold BRep, strict export preflight, production STEP export, and manifold STEP reimport. A shared multi-hole box builder error was corrected: straight edges now bind their full physical curve parameter interval, allowing strict preflight to validate the construction.
+
+## Witness and measurements
+
+`fixtures/Canonical/Perforation/flat-hex-panel.firmament` is the public flat witness. Reproduce it with:
+
+```text
+dotnet run --project Aetheris.CLI -- build fixtures/Canonical/Perforation/flat-hex-panel.firmament --output artifacts/local/perforation/flat-hex-panel.step --json
+```
+
+On the 2026-09-23 local Windows .NET 10 run, the 90 × 70 × 3 mm Box with 6 mm openings at 9 mm pitch realized **53 holes**, **220 vertices**, **171 edges**, **59 faces** and a **91,502 byte STEP** file. Native CLI wall time was **32.7 seconds**, including compilation, BRep verification, STEP export, and reimport. The SHA-256 of the STEP text was `98167F3754505DF767CEE16CEE1E2B6981CA827EEEEB5C1F04BC93454B950D3A`. A 60 × 60 × 3 mm local variant completed in **6.7 seconds** and produced a 41,635 byte STEP. A 150 × 100 × 3 mm variant spent over a minute of CPU without completing and was stopped. High-count scaling is therefore not qualified. The STEP witness is at `artifacts/local/perforation/flat-hex-panel.step`; its generated bytes remain ignored under the repository artifact policy.
+
+The 53-hole STEP body passed strict native preflight and STEP reimport manifold checks. An OBJ display attempt did not complete within the profiling window, so triangle count and a gallery-quality render are not claimed. WASM AOT, Helios author/build/save/export, and fresh-agent UI workflows remain unqualified.
+
+`dotnet build Aetheris.slnx --no-restore -m:1` passed with seven existing WebAssembly analyzer/toolchain warnings. The serial `dotnet test Aetheris.slnx --no-build --no-restore -m:1` passed every test project except two assertions: the generated schema list expected the old five constructs and was updated, then its targeted schema and Perforation tests passed (12/12); `SurfaceMeshIrTests.ThroughHolePlate_UsesMultiLoopPlanarBands_AndLowersToWatertightMesh` still expects 90 planar cells but gets 87. The latter uses the single-hole recipe, not the changed multi-hole builder branch, and also fails in isolation. This run does not establish an all-green kernel suite.
+
+## Cylindrical boundary
+
+`PipingGeometry.Pipe` already makes constant-thickness annular BRep stock from `PipePolicyIr.OuterDiameterMm` and `WallThicknessMm`. The blocker is the subsequent radial cut: `BrepBooleanSafeCompositionGraphValidator.TryValidateCylinderRootSubtract` admits only world-Z aligned cylinders on a cylinder root. The BRep curve/STEP authority has no production cylinder-to-cylinder radial intersection construction for the two curved sleeve walls and the radial opening wall. A cylindrical `Perforation` currently fails with `perforation-cylindrical-topology-unavailable` before emitting an uncut STEP file. Reusing piping stock alone cannot satisfy the sleeve request; mesh approximation or dozens of unsupported generic Boolean cuts would compromise exact topology.
+
+## Remaining acceptance work
+
+The cylindrical radial intersection and seam construction, high-count performance, irregular trimmed planar supports, Hollow integration, browser AOT and Helios qualification, triangle counts, and public-quality renders remain open. The static generated schema and Firmament language completion expose the planar Perforation fields and entry, and CLI build JSON reports count and stable IDs. Existing PMI/FEA and full solution regressions require separate qualification.
diff --git a/fixtures/Canonical/Perforation/flat-hex-panel.firmament b/fixtures/Canonical/Perforation/flat-hex-panel.firmament
new file mode 100644
index 00000000..ef9d956a
--- /dev/null
+++ b/fixtures/Canonical/Perforation/flat-hex-panel.firmament
@@ -0,0 +1,14 @@
+Model FlatHexPanel {
+ Units: mm
+ Box Panel { Size: [90mm, 70mm, 3mm] }
+ Modify Panel {
+ Perforation Vent {
+ On: +Z
+ Diameter: 6mm
+ Layout: Hex
+ Pitch: 9mm
+ Margin: 8mm
+ MinimumLigament: 2mm
+ }
+ }
+}