Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel
PLACEMENT-C0 unify placement anchors and canonicalize on_face
Yuechen Li10eb57e89b8e
diff --git a/Aetheris.Kernel.Firmament.Tests/FirmamentExamplePackSmokeTests.cs b/Aetheris.Kernel.Firmament.Tests/FirmamentExamplePackSmokeTests.csindex b7e42295..9fb408a7 100644--- a/Aetheris.Kernel.Firmament.Tests/FirmamentExamplePackSmokeTests.cs+++ b/Aetheris.Kernel.Firmament.Tests/FirmamentExamplePackSmokeTests.cs@@ -95,6 +95,22 @@ public sealed class FirmamentExamplePackSmokeTestsAssert.Single(result.Compilation.Value.PrimitiveExecutionResult!.ExecutedPrimitives);}+ [Theory]+ [InlineData("testdata/firmament/examples/p1_blind_hole_on_face_semantic.firmament")]+ [InlineData("testdata/firmament/examples/p1_flange_radial_hole_semantic.firmament")]+ [InlineData("testdata/firmament/examples/w2_cylinder_root_blind_bore_semantic.firmament")]+ [InlineData("testdata/firmament/examples/w2_box_sphere_exterior_opening_pocket_semantic.firmament")]+ [InlineData("testdata/firmament/examples/placed_primitive.firmament")]+ public void CanonicalExamples_StillBuild(string fixturePath)+ {+ var compileResult = FirmamentCorpusHarness.Compile(FirmamentCorpusHarness.ReadFixtureText(fixturePath));+ Assert.True(compileResult.Compilation.IsSuccess);++ var exportResult = ExportFixture(fixturePath);+ Assert.True(exportResult.IsSuccess);+ Assert.Contains("ISO-10303-21", exportResult.Value.StepText, StringComparison.Ordinal);+ }+private static Aetheris.Kernel.Core.Results.KernelResult<FirmamentStepExportResult> ExportFixture(string fixturePath) =>FirmamentStepExporter.Export(new FirmamentCompileRequest(new FirmamentSourceDocument(FirmamentCorpusHarness.ReadFixtureText(fixturePath))));}diff --git a/Aetheris.Kernel.Firmament.Tests/FirmamentFormatterTests.cs b/Aetheris.Kernel.Firmament.Tests/FirmamentFormatterTests.csindex c3ea75c9..527942d9 100644--- a/Aetheris.Kernel.Firmament.Tests/FirmamentFormatterTests.cs+++ b/Aetheris.Kernel.Firmament.Tests/FirmamentFormatterTests.cs@@ -325,6 +325,39 @@ public sealed class FirmamentFormatterTestsAssert.NotEmpty(result.Formatting.Diagnostics);}+ [Fact]+ public void OnFace_And_CenteredOn_Canonicalization()+ {+ const string source = """+ firmament:+ version: 1++ model:+ name: demo+ units: mm++ ops[1]:+ -+ op: box+ id: rib+ size[3]:+ 3+ 3+ 3+ place:+ centered_on: base.top_face+ offset[3]:+ 0+ 0+ 1+ """;++ var result = Format(source);+ Assert.True(result.Formatting.IsSuccess);+ Assert.Contains("on_face: base.top_face", result.Formatting.Value.Text, StringComparison.Ordinal);+ Assert.DoesNotContain("centered_on:", result.Formatting.Value.Text, StringComparison.Ordinal);+ }+private static FirmamentFormatResult Format(string source){var formatter = new FirmamentFormatter();@@ -375,9 +408,15 @@ public sealed class FirmamentFormatterTests{FirmamentParsedPlacementOriginAnchor => "origin",FirmamentParsedPlacementSelectorAnchor selector => selector.Selector,+ null => null,_ => throw new InvalidOperationException("Unknown placement anchor.")},- entry.Placement.Offset.Select(value => value.ToString("G", CultureInfo.InvariantCulture)).ToArray());+ entry.Placement.Offset.Select(value => value.ToString("G", CultureInfo.InvariantCulture)).ToArray(),+ entry.Placement.OnFace,+ entry.Placement.CenteredOn,+ entry.Placement.AroundAxis,+ entry.Placement.RadialOffset?.ToString("G", CultureInfo.InvariantCulture),+ entry.Placement.AngleDegrees?.ToString("G", CultureInfo.InvariantCulture));return new FirmamentOpMeaningSnapshot(entry.KnownKind, entry.Family, fields, placement);}@@ -438,5 +477,12 @@ public sealed class FirmamentFormatterTestsprivate sealed record FirmamentFieldMeaningSnapshot(string Name, string Value);- private sealed record FirmamentPlacementMeaningSnapshot(string On, IReadOnlyList<string> Offset);+ private sealed record FirmamentPlacementMeaningSnapshot(+ string? On,+ IReadOnlyList<string> Offset,+ string? OnFace,+ string? CenteredOn,+ string? AroundAxis,+ string? RadialOffset,+ string? AngleDegrees);}diff --git a/Aetheris.Kernel.Firmament.Tests/FirmamentPlacementValidationTests.cs b/Aetheris.Kernel.Firmament.Tests/FirmamentPlacementValidationTests.csindex f309f48d..e4ef7eb0 100644--- a/Aetheris.Kernel.Firmament.Tests/FirmamentPlacementValidationTests.cs+++ b/Aetheris.Kernel.Firmament.Tests/FirmamentPlacementValidationTests.cs@@ -57,6 +57,49 @@ public sealed class FirmamentPlacementValidationTestsAssert.Contains("concentric_with", diagnostic.Message, StringComparison.Ordinal);}+ [Fact]+ public void Placement_Alias_Conflict_Between_OnFace_And_CenteredOn_Is_Rejected()+ {+ const string source = """+firmament:+ version: 1++model:+ name: placement_alias_conflict+ units: mm++ops[2]:+ -+ op: box+ id: base+ size[3]:+ 20+ 20+ 10++ -+ op: box+ id: rib+ size[3]:+ 2+ 2+ 2+ place:+ on_face: base.top_face+ centered_on: base.bottom_face+ offset[3]:+ 0+ 0+ 0+""";++ var result = CompileSource(source);+ Assert.False(result.Compilation.IsSuccess);+ var diagnostic = Assert.Single(result.Compilation.Diagnostics);+ Assert.Contains(FirmamentDiagnosticCodes.PlacementInvalidSemanticCombination.Value, diagnostic.Message, StringComparison.Ordinal);+ Assert.Contains("compatibility alias", diagnostic.Message, StringComparison.Ordinal);+ }+[Fact]public void Primitive_With_Sphere_Surface_PlaceAnchor_Is_Valid(){@@ -256,6 +299,11 @@ public sealed class FirmamentPlacementValidationTestsprivate static FirmamentCompileResult CompileFixture(string fixturePath){var source = FirmamentCorpusHarness.ReadFixtureText(fixturePath);+ return CompileSource(source);+ }++ private static FirmamentCompileResult CompileSource(string source)+ {var compiler = new FirmamentCompiler();return compiler.Compile(new FirmamentCompileRequest(new FirmamentSourceDocument(source)));}diff --git a/Aetheris.Kernel.Firmament.Tests/FirmamentPrimitiveLoweringTests.cs b/Aetheris.Kernel.Firmament.Tests/FirmamentPrimitiveLoweringTests.csindex 2deebf74..36720145 100644--- a/Aetheris.Kernel.Firmament.Tests/FirmamentPrimitiveLoweringTests.cs+++ b/Aetheris.Kernel.Firmament.Tests/FirmamentPrimitiveLoweringTests.cs@@ -304,6 +304,59 @@ public sealed class FirmamentPrimitiveLoweringTestsAssert.Equal(new[] { 10d, -5d, 3d }, boolean.Placement.Offset);}+ [Fact]+ public void SemanticPlacement_And_OnOffset_Lower_To_Coherent_Result()+ {+ const string source = """+firmament:+ version: 1++model:+ name: placement_c0_lowering_unification+ units: mm++ops[2]:+ -+ op: box+ id: base+ size[3]:+ 20+ 20+ 10++ -+ op: box+ id: semantic+ size[3]:+ 4+ 4+ 4+ place:+ on_face: base.top_face+ offset[3]:+ 1+ 2+ 3+""";++ var semanticResult = Compile(source);+ Assert.True(semanticResult.Compilation.IsSuccess);+ var semantic = semanticResult.Compilation.Value.PrimitiveLoweringPlan!.Primitives.Single(p => p.FeatureId == "semantic");+ var semanticAnchor = Assert.IsType<FirmamentLoweredPlacementSelectorAnchor>(semantic.Placement!.On);+ Assert.Equal("base.top_face", semanticAnchor.Selector);+ Assert.Equal(new[] { 1d, 2d, 3d }, semantic.Placement.Offset);++ var explicitResult = Compile(source.Replace("on_face", "on", StringComparison.Ordinal));+ Assert.True(explicitResult.Compilation.IsSuccess);+ var explicitPlacement = explicitResult.Compilation.Value.PrimitiveLoweringPlan!.Primitives.Single(p => p.FeatureId == "semantic").Placement!;+ var explicitAnchor = Assert.IsType<FirmamentLoweredPlacementSelectorAnchor>(explicitPlacement.On);+ Assert.Equal("base.top_face", explicitAnchor.Selector);+ Assert.Equal(semantic.Placement.Offset, explicitPlacement.Offset);+ Assert.Equal(semantic.Placement.AroundAxis, explicitPlacement.AroundAxis);+ Assert.Equal(semantic.Placement.RadialOffset, explicitPlacement.RadialOffset);+ Assert.Equal(semantic.Placement.AngleDegrees, explicitPlacement.AngleDegrees);+ }+[Fact]public void Compile_Validation_Family_Ops_Remain_Explicitly_NonLowered(){diff --git a/Aetheris.Kernel.Firmament/Execution/FirmamentPlacementResolver.cs b/Aetheris.Kernel.Firmament/Execution/FirmamentPlacementResolver.csindex 824e0b32..b33b4fcf 100644--- a/Aetheris.Kernel.Firmament/Execution/FirmamentPlacementResolver.cs+++ b/Aetheris.Kernel.Firmament/Execution/FirmamentPlacementResolver.cs@@ -19,10 +19,9 @@ internal static class FirmamentPlacementResolver{if (primitive.Placement is null) return KernelResult<Vector3D>.Success(Vector3D.Zero);- var semanticAnchorResult = ResolveSemanticAnchorPoint(primitive.Placement, featureBodies);- if (!semanticAnchorResult.IsSuccess) return KernelResult<Vector3D>.Failure(semanticAnchorResult.Diagnostics);-- var baseAnchorPoint = semanticAnchorResult.Value;+ var anchorResult = ResolveAnchorPoint(primitive.Placement, featureBodies);+ if (!anchorResult.IsSuccess) return KernelResult<Vector3D>.Failure(anchorResult.Diagnostics);+ var baseAnchorPoint = anchorResult.Value;if (!string.IsNullOrWhiteSpace(primitive.Placement.AroundAxis)){var axisResult = ResolveAxisFromSelector(primitive.Placement.AroundAxis!, featureBodies);@@ -42,9 +41,9 @@ internal static class FirmamentPlacementResolverpublic static KernelResult<Vector3D> ResolvePlacementTranslation(FirmamentLoweredBoolean booleanOp, IReadOnlyDictionary<string, BrepBody> featureBodies){if (booleanOp.Placement is null) return KernelResult<Vector3D>.Success(Vector3D.Zero);- var semanticAnchorResult = ResolveSemanticAnchorPoint(booleanOp.Placement, featureBodies);- if (!semanticAnchorResult.IsSuccess) return KernelResult<Vector3D>.Failure(semanticAnchorResult.Diagnostics);- var baseAnchorPoint = semanticAnchorResult.Value;+ var anchorResult = ResolveAnchorPoint(booleanOp.Placement, featureBodies);+ if (!anchorResult.IsSuccess) return KernelResult<Vector3D>.Failure(anchorResult.Diagnostics);+ var baseAnchorPoint = anchorResult.Value;if (!string.IsNullOrWhiteSpace(booleanOp.Placement.AroundAxis)){var axisResult = ResolveAxisFromSelector(booleanOp.Placement.AroundAxis!, featureBodies);@@ -58,18 +57,8 @@ internal static class FirmamentPlacementResolverreturn KernelResult<Vector3D>.Success((baseAnchorPoint - Point3D.Origin) + ResolveOffset(o));}- private static KernelResult<Point3D> ResolveSemanticAnchorPoint(FirmamentLoweredPlacement placement, IReadOnlyDictionary<string, BrepBody> featureBodies)+ private static KernelResult<Point3D> ResolveAnchorPoint(FirmamentLoweredPlacement placement, IReadOnlyDictionary<string, BrepBody> featureBodies){- if (!string.IsNullOrWhiteSpace(placement.OnFace))- {- return ResolveAnchorPoint(new FirmamentLoweredPlacementSelectorAnchor(placement.OnFace!), featureBodies);- }-- if (!string.IsNullOrWhiteSpace(placement.CenteredOn))- {- return ResolveAnchorPoint(new FirmamentLoweredPlacementSelectorAnchor(placement.CenteredOn!), featureBodies);- }-if (placement.On is not null){return ResolveAnchorPoint(placement.On, featureBodies);@@ -77,9 +66,9 @@ internal static class FirmamentPlacementResolverif (!string.IsNullOrWhiteSpace(placement.AroundAxis)){- var axis = ResolveAxisFromSelector(placement.AroundAxis!, featureBodies);- if (!axis.IsSuccess) return KernelResult<Point3D>.Failure(axis.Diagnostics);- return KernelResult<Point3D>.Success(axis.Value.Origin);+ var axisResult = ResolveAxisFromSelector(placement.AroundAxis!, featureBodies);+ if (!axisResult.IsSuccess) return KernelResult<Point3D>.Failure(axisResult.Diagnostics);+ return KernelResult<Point3D>.Success(axisResult.Value.Origin);}return KernelResult<Point3D>.Success(Point3D.Origin);diff --git a/Aetheris.Kernel.Firmament/Execution/FirmamentPrimitiveExecutor.cs b/Aetheris.Kernel.Firmament/Execution/FirmamentPrimitiveExecutor.csindex 5079d6f8..0ff822a6 100644--- a/Aetheris.Kernel.Firmament/Execution/FirmamentPrimitiveExecutor.cs+++ b/Aetheris.Kernel.Firmament/Execution/FirmamentPrimitiveExecutor.cs@@ -529,7 +529,7 @@ internal static class FirmamentPrimitiveExecutorif (isSphereTool){- return !string.IsNullOrWhiteSpace(boolean.Placement.OnFace)+ return boolean.Placement.UsesSemanticAnchor&& BrepBooleanBoxRecognition.TryRecognizeAxisAlignedBox(baseBody, ToleranceContext.Default, out _, out _);}@@ -545,13 +545,13 @@ internal static class FirmamentPrimitiveExecutorreturn true;}- if (!string.IsNullOrWhiteSpace(boolean.Placement.OnFace)+ if (boolean.Placement.UsesSemanticAnchor&& BrepBooleanCylinderRecognition.TryRecognizeCylinder(baseBody, ToleranceContext.Default, out _, out _)){return true;}- if (string.IsNullOrWhiteSpace(boolean.Placement.OnFace))+ if (!boolean.Placement.UsesSemanticAnchor){return false;}diff --git a/Aetheris.Kernel.Firmament/Formatting/FirmamentCanonicalFormatter.cs b/Aetheris.Kernel.Firmament/Formatting/FirmamentCanonicalFormatter.csindex ca489e6c..56ee9b99 100644--- a/Aetheris.Kernel.Firmament/Formatting/FirmamentCanonicalFormatter.cs+++ b/Aetheris.Kernel.Firmament/Formatting/FirmamentCanonicalFormatter.cs@@ -270,14 +270,45 @@ internal static class FirmamentCanonicalFormatterprivate static void AppendPlacement(StringBuilder builder, int indentLevel, FirmamentParsedPlacement placement){builder.Append(Indent(indentLevel)).Append("place:\n");- var onValue = placement.On switch+ var explicitAnchor = placement.On switch{FirmamentParsedPlacementOriginAnchor => "origin",FirmamentParsedPlacementSelectorAnchor selector => selector.Selector,+ null => null,_ => throw new InvalidOperationException("Unknown placement anchor.")};+ var semanticAnchor = !string.IsNullOrWhiteSpace(placement.OnFace)+ ? placement.OnFace+ : placement.CenteredOn;++ if (!string.IsNullOrWhiteSpace(semanticAnchor))+ {+ AppendScalarField(builder, indentLevel + 1, "on_face", semanticAnchor!);+ }+ else if (!string.IsNullOrWhiteSpace(explicitAnchor))+ {+ AppendScalarField(builder, indentLevel + 1, "on", explicitAnchor!);+ }+ else if (string.IsNullOrWhiteSpace(placement.AroundAxis))+ {+ AppendScalarField(builder, indentLevel + 1, "on", "origin");+ }++ if (!string.IsNullOrWhiteSpace(placement.AroundAxis))+ {+ AppendScalarField(builder, indentLevel + 1, "around_axis", placement.AroundAxis!);+ }++ if (placement.RadialOffset is not null)+ {+ AppendScalarField(builder, indentLevel + 1, "radial_offset", FormatNumber(placement.RadialOffset.Value));+ }++ if (placement.AngleDegrees is not null)+ {+ AppendScalarField(builder, indentLevel + 1, "angle_degrees", FormatNumber(placement.AngleDegrees.Value));+ }- AppendScalarField(builder, indentLevel + 1, "on", onValue);builder.Append(Indent(indentLevel + 1)).Append("offset[").Append(placement.Offset.Count.ToString(CultureInfo.InvariantCulture))diff --git a/Aetheris.Kernel.Firmament/Lowering/FirmamentPrimitiveLowerer.cs b/Aetheris.Kernel.Firmament/Lowering/FirmamentPrimitiveLowerer.csindex 4a652133..f2569b48 100644--- a/Aetheris.Kernel.Firmament/Lowering/FirmamentPrimitiveLowerer.cs+++ b/Aetheris.Kernel.Firmament/Lowering/FirmamentPrimitiveLowerer.cs@@ -185,7 +185,9 @@ internal static class FirmamentPrimitiveLowererreturn null;}- FirmamentLoweredPlacementAnchor? loweredAnchor = placement.On switch+ var canonicalAnchor = ResolveCanonicalPlacementAnchor(placement);+ var usesSemanticAnchor = !string.IsNullOrWhiteSpace(placement.OnFace) || !string.IsNullOrWhiteSpace(placement.CenteredOn);+ FirmamentLoweredPlacementAnchor? loweredAnchor = canonicalAnchor switch{FirmamentParsedPlacementOriginAnchor => new FirmamentLoweredPlacementOriginAnchor(),FirmamentParsedPlacementSelectorAnchor selector => new FirmamentLoweredPlacementSelectorAnchor(selector.Selector),@@ -193,15 +195,29 @@ internal static class FirmamentPrimitiveLowerer};return new FirmamentLoweredPlacement(loweredAnchor,+ usesSemanticAnchor,placement.Offset,- placement.OnFace,- placement.CenteredOn,placement.AroundAxis,placement.RadialOffset,placement.AngleDegrees,placement.UnknownFields);}+ private static FirmamentParsedPlacementAnchor? ResolveCanonicalPlacementAnchor(FirmamentParsedPlacement placement)+ {+ if (!string.IsNullOrWhiteSpace(placement.OnFace))+ {+ return new FirmamentParsedPlacementSelectorAnchor(placement.OnFace!);+ }++ if (!string.IsNullOrWhiteSpace(placement.CenteredOn))+ {+ return new FirmamentParsedPlacementSelectorAnchor(placement.CenteredOn!);+ }++ return placement.On;+ }+private static FirmamentLoweredBoolean LowerBoolean(int opIndex,FirmamentParsedOpEntry entry,diff --git a/Aetheris.Kernel.Firmament/Lowering/FirmamentPrimitiveLoweringPlan.cs b/Aetheris.Kernel.Firmament/Lowering/FirmamentPrimitiveLoweringPlan.csindex 3f29de2c..60a85da9 100644--- a/Aetheris.Kernel.Firmament/Lowering/FirmamentPrimitiveLoweringPlan.cs+++ b/Aetheris.Kernel.Firmament/Lowering/FirmamentPrimitiveLoweringPlan.cs@@ -16,9 +16,8 @@ public sealed record FirmamentLoweredPrimitive(public sealed record FirmamentLoweredPlacement(FirmamentLoweredPlacementAnchor? On,+ bool UsesSemanticAnchor,IReadOnlyList<double> Offset,- string? OnFace,- string? CenteredOn,string? AroundAxis,double? RadialOffset,double? AngleDegrees,diff --git a/Aetheris.Kernel.Firmament/Validation/FirmamentBooleanRequiredFieldValidator.cs b/Aetheris.Kernel.Firmament/Validation/FirmamentBooleanRequiredFieldValidator.csindex 4c35816c..c57a593b 100644--- a/Aetheris.Kernel.Firmament/Validation/FirmamentBooleanRequiredFieldValidator.cs+++ b/Aetheris.Kernel.Firmament/Validation/FirmamentBooleanRequiredFieldValidator.cs@@ -750,6 +750,16 @@ internal static class FirmamentBooleanRequiredFieldValidatorreturn KernelResult<bool>.Failure([semanticSelectorError]);}+ if (!string.IsNullOrWhiteSpace(entry.Placement.OnFace)+ && !string.IsNullOrWhiteSpace(entry.Placement.CenteredOn)+ && !string.Equals(entry.Placement.OnFace, entry.Placement.CenteredOn, StringComparison.Ordinal))+ {+ return KernelResult<bool>.Failure([+ CreateDiagnostic(+ FirmamentDiagnosticCodes.PlacementInvalidSemanticCombination,+ $"Boolean op '{entry.OpName}' at index {opIndex} has ambiguous placement semantics; 'place.centered_on' is a compatibility alias of 'place.on_face' and must match it when both are present.")]);+ }+if (entry.Placement.RadialOffset is not null && string.IsNullOrWhiteSpace(entry.Placement.AroundAxis)){return KernelResult<bool>.Failure([diff --git a/Aetheris.Kernel.Firmament/Validation/FirmamentPrimitiveRequiredFieldValidator.cs b/Aetheris.Kernel.Firmament/Validation/FirmamentPrimitiveRequiredFieldValidator.csindex 541ff5b4..fd57cdbe 100644--- a/Aetheris.Kernel.Firmament/Validation/FirmamentPrimitiveRequiredFieldValidator.cs+++ b/Aetheris.Kernel.Firmament/Validation/FirmamentPrimitiveRequiredFieldValidator.cs@@ -485,6 +485,16 @@ internal static class FirmamentPrimitiveRequiredFieldValidatorreturn KernelResult<bool>.Failure([semanticSelectorError]);}+ if (!string.IsNullOrWhiteSpace(entry.Placement.OnFace)+ && !string.IsNullOrWhiteSpace(entry.Placement.CenteredOn)+ && !string.Equals(entry.Placement.OnFace, entry.Placement.CenteredOn, StringComparison.Ordinal))+ {+ return KernelResult<bool>.Failure([+ CreateDiagnostic(+ FirmamentDiagnosticCodes.PlacementInvalidSemanticCombination,+ $"Primitive op '{entry.OpName}' at index {opIndex} has ambiguous placement semantics; 'place.centered_on' is a compatibility alias of 'place.on_face' and must match it when both are present.")]);+ }+if (entry.Placement.RadialOffset is not null && string.IsNullOrWhiteSpace(entry.Placement.AroundAxis)){return KernelResult<bool>.Failure([diff --git a/docs/firmament-language-shape.md b/docs/firmament-language-shape.mdindex 19f8ab29..8f9170b4 100644--- a/docs/firmament-language-shape.md+++ b/docs/firmament-language-shape.md@@ -197,12 +197,11 @@ place:0```-Semantic placement subset (P1):+Semantic-first placement form:```place:on_face: base.top_face- centered_on: flange.top_facearound_axis: flange.side_faceradial_offset: 20angle_degrees: 30@@ -213,7 +212,9 @@ place:```Rules:-- Supported semantic fields are exactly: `on_face`, `centered_on`, `around_axis`, `radial_offset`, `angle_degrees`.+- Supported semantic fields are exactly: `on_face`, `centered_on` (compatibility alias), `around_axis`, `radial_offset`, `angle_degrees`.+- Canonical output normalizes semantic anchors to `on_face`.+- If both `on_face` and `centered_on` are provided, they must match.- `radial_offset` requires `around_axis`.- Unknown placement semantic keys are rejected.- This is a minimal ergonomics subset; it is **not** a general frame/constraint language.diff --git a/docs/firmament-overview.md b/docs/firmament-overview.mdindex 67312921..7746cbc9 100644--- a/docs/firmament-overview.md+++ b/docs/firmament-overview.md@@ -15,7 +15,7 @@ Firmament currently supports these source-level concepts:- primitive features: `box`, `cylinder`, `sphere`- boolean features: `add`, `subtract`, `intersect`- validation ops: `expect_exists`, `expect_selectable`, `expect_manifold`-- placement blocks with legacy `place.on` + `offset[3]` and minimal P1 semantic placement (`on_face`, `centered_on`, `around_axis`, `radial_offset`)+- placement blocks with a unified model: semantic-first `on_face` anchors plus explicit `on` + `offset[3]` fallback (`centered_on` remains a compatibility alias), and optional axis placement (`around_axis`, `radial_offset`, `angle_degrees`)- selector-shaped references rooted at a source feature id- optional schema blocks for `cnc`, `additive`, and `injection_molded`- first schema-aware CNC DFM validation for `minimum_tool_radius` on subtract-with-cylinder inputs@@ -49,14 +49,11 @@ Validation ops check feature existence, selector selectability, and manifold exp### Placement-Placement currently supports two small models:+Placement currently supports one coherent model with two input styles:-- `place.on: origin`-- `place.on: feature_id.port`-- `offset[3]` numeric translation-- `place.on_face: feature_id.port`-- `place.centered_on: feature_id.port`-- `place.around_axis: feature_id.port` (+ optional `place.radial_offset` and `place.angle_degrees`)+- semantic anchor: `place.on_face: feature_id.port` (`place.centered_on` accepted as a compatibility alias and normalized to `on_face`)+- explicit spatial fallback: `place.on: origin|feature_id.port` with `offset[3]`+- optional radial placement: `place.around_axis: feature_id.port` (+ optional `place.radial_offset` and `place.angle_degrees`)This is intentionally narrow. It lowers deterministically into selector anchor extraction + axis/radial translation and does not introduce a general frame system or constraint solver.diff --git a/docs/firmament-placement-semantics.md b/docs/firmament-placement-semantics.mdindex ad3c8586..e75e65ff 100644--- a/docs/firmament-placement-semantics.md+++ b/docs/firmament-placement-semantics.md@@ -10,22 +10,23 @@ For primitives, note there is still primitive-specific default publish framing i----## 2) Placement keys and mode split+## 2) Placement keys in one unified modelSupported keys:- `on`- `offset[3]`- `on_face`-- `centered_on`- `around_axis`- `radial_offset`- `angle_degrees`-Mode behavior:+Unified behavior:-- legacy mode (no semantic keys): `on` + `offset[3]` required,-- semantic mode (any semantic key present): `on` optional, `offset[3]` defaults to zero if omitted/malformed,+- semantic anchor placement prefers `on_face`,+- explicit spatial fallback uses `on` + `offset[3]`,+- `centered_on` is a compatibility alias of `on_face`,+- if both `on_face` and `centered_on` are present they must match exactly,- `radial_offset` requires `around_axis`.---@@ -34,11 +35,10 @@ Mode behavior:Base anchor point is resolved in this strict precedence:-1. `on_face`-2. `centered_on`-3. `on`-4. if none above and `around_axis` exists: axis origin-5. otherwise world origin `(0,0,0)`+1. canonical semantic anchor (`on_face`, or `centered_on` alias normalized to `on_face`)+2. `on` fallback anchor+3. if none above and `around_axis` exists: axis origin+4. otherwise world origin `(0,0,0)`---@@ -122,4 +122,4 @@ Reference: `testdata/firmament/examples/w2_box_sphere_exterior_opening_pocket_se- Using contained sphere placement when you intended an exterior-opening pocket.- Tangent/grazing placement (zero-thickness boundary conditions) instead of strict overlap.- Assuming `offset` is face-local; it is world XYZ.-- Assuming `on_face` and `centered_on` are distinct mating semantics; currently they share anchor extraction behavior.+- Authoring both `on_face` and `centered_on` with different selectors (now rejected as ambiguous).diff --git a/docs/firmament-selectors.md b/docs/firmament-selectors.mdindex 2fb2c762..fe4bd137 100644--- a/docs/firmament-selectors.md+++ b/docs/firmament-selectors.md@@ -91,13 +91,13 @@ Current boolean outputs (`add`, `subtract`, `intersect`, plus bounded draft/cham## Placement-relevant meaning of names-For placement anchors (`place.on`, `place.on_face`, `place.centered_on`) the resolver currently uses representative geometry points and centroids:+For placement anchors (`place.on`, `place.on_face`, and compatibility alias `place.centered_on`) the resolver uses one shared anchor extraction path with representative geometry points and centroids:- face/face-set ports → representative face points then centroid,- edge-set ports → edge endpoint points then centroid,- vertex-set ports → vertex points then centroid.-Important implication: names such as `on_face` vs `centered_on` are currently ergonomic aliases over the same anchor extraction behavior, not different mating solvers.+Important implication: `centered_on` is a compatibility alias of `on_face`, not a different mating solver. Canonical formatting normalizes alias usage to `on_face`.---diff --git a/testdata/firmament/examples/README.md b/testdata/firmament/examples/README.mdindex 1bdb3dba..7c8c8711 100644--- a/testdata/firmament/examples/README.md+++ b/testdata/firmament/examples/README.md@@ -1,6 +1,7 @@# Firmament Example PackThis directory contains small canonical Firmament examples for the current v1 surface.+Placement examples use canonical `place.on_face` for semantic anchors; `place.centered_on` remains accepted as a compatibility alias but is normalized by formatter output.These examples represent the currently supported boolean subset.Other combinations may fail and are intentionally not supported yet.diff --git a/testdata/firmament/examples/m7_pmi_explicit_dimensions.firmament b/testdata/firmament/examples/m7_pmi_explicit_dimensions.firmamentindex eed76903..a8ed0ad3 100644--- a/testdata/firmament/examples/m7_pmi_explicit_dimensions.firmament+++ b/testdata/firmament/examples/m7_pmi_explicit_dimensions.firmament@@ -24,7 +24,6 @@ ops[2]:height: 24place:on_face: base.top_face- centered_on: base.top_facepmi[3]:-