Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

knobs authoring improvement, etc.

Yuechen Li062c20df1a92
diff --git a/Aetheris.Kernel.Firmament.Tests/Assembly/CoaxialDatumTests.cs b/Aetheris.Kernel.Firmament.Tests/Assembly/CoaxialDatumTests.cs
new file mode 100644
index 00000000..fef76427
--- /dev/null
+++ b/Aetheris.Kernel.Firmament.Tests/Assembly/CoaxialDatumTests.cs
@@ -0,0 +1,155 @@
+using Aetheris.Kernel.Core.Math;
+using Aetheris.Kernel.Firmament.Assembly;
+using Aetheris.Semantics;
+
+namespace Aetheris.Kernel.Firmament.Tests.Assembly;
+
+public sealed class CoaxialDatumTests
+{
+ private const string Fixture = "fixtures/Canonical/AssemblyInterfaces/coaxial-knob.firmasm";
+ private static string Source => File.ReadAllText(FirmamentCorpusHarness.ResolveFixtureFullPath("fixtures/Canonical/AssemblyInterfaces/GuitarX0/hardware-definitions.firmament"))
+ + File.ReadAllText(FirmamentCorpusHarness.ResolveFixtureFullPath("fixtures/Canonical/AssemblyInterfaces/GuitarX0/knob.firmament"))
+ + string.Join('\n', File.ReadAllLines(FirmamentCorpusHarness.ResolveFixtureFullPath(Fixture)).Where(l => !l.StartsWith("Include")));
+
+ [Fact]
+ public void CompleteKnobRotatesAsOneRigidOccurrenceWithNoGeometryRebuild()
+ {
+ var compiled = new AssemblyM1Pipeline().CompileFile(FirmamentCorpusHarness.ResolveFixtureFullPath(Fixture));
+ Assert.True(compiled.IsSuccess, Evidence(compiled.Diagnostics));
+ var ir = compiled.Ir!;
+ Assert.Equal(5, ir.Instances.Count); // Concept target is not a product occurrence.
+ Assert.Equal(3, compiled.Geometry!.Artifact.Definitions.Count);
+ var seat = Assert.Single(ir.AxisSeats!);
+ Assert.True(seat.Passed);
+ Assert.Equal(1, seat.DegreesOfFreedom);
+ Assert.Equal(7, seat.Seating.StationMm);
+ Assert.Equal(30, seat.Seating.ClockingDegrees);
+ Assert.Equal(3, Assert.Single(ir.AssemblyDefinitions!).LocalAxisSeats!.Count);
+ Assert.All(ir.AssemblyDefinitions![0].LocalAxisSeats!, e => { Assert.True(e.Passed); Assert.Equal(0,e.DegreesOfFreedom); });
+ var joint = Assert.Single(ir.Joints!);
+ Assert.Equal("VolumeRotation", joint.Name);
+ Assert.Equal(MechanicalInterfaceFamily.Revolute, joint.Family);
+ var zero = AssemblyKinematics.Evaluate(ir, new Dictionary<string,double>());
+ var pose = AssemblyKinematics.Evaluate(ir, new Dictionary<string,double> { ["VolumeRotation"] = 90 });
+ Assert.True(pose.IsSuccess, Evidence(pose.Diagnostics));
+ var zeroKnob = Instance(zero.Instances,"Controls.VolumeKnob");
+ var posedKnob = Instance(pose.Instances,"Controls.VolumeKnob");
+ Assert.Equal(10,zeroKnob.ResolvedTransform!.Matrix[12],6); // Station follows X, not world Z.
+ Assert.Equal(4,zeroKnob.ResolvedTransform.Matrix[13],6);
+ Assert.Equal(5,zeroKnob.ResolvedTransform.Matrix[14],6);
+ Assert.NotEqual(zeroKnob.ResolvedTransform.Matrix[0..12],posedKnob.ResolvedTransform!.Matrix[0..12]);
+ foreach (var original in ir.Instances.Where(i => i.Kind == AssemblyInstanceKind.Part))
+ {
+ var posed = pose.Instances.Single(i => i.StableId == original.StableId);
+ Assert.Same(original.SemanticRoot,posed.SemanticRoot);
+ Assert.Equal(original.DefinitionIdentity,posed.DefinitionIdentity);
+ var before = Matrix(original) * Matrix(zeroKnob).Inverse();
+ var after = Matrix(posed) * Matrix(posedKnob).Inverse();
+ AssertMatrix(before,after);
+ AssertMatrix(Matrix(original),Matrix(zero.Instances.Single(i => i.StableId == original.StableId)));
+ }
+ }
+
+ [Fact]
+ public void DatumOnlyEditReusesAllExactBodiesAndSignedStationIsDeterministic()
+ {
+ using var session = new FirmamentCompilationSession();
+ var first = session.Compile(Source);
+ Assert.True(first.IsSuccess,Evidence(first.Diagnostics));
+ var shifted = session.Compile(Source.Replace("Origin: [3mm,4mm,5mm]","Origin: [13mm,4mm,5mm]").Replace("At: 7mm","At: -7mm"));
+ Assert.True(shifted.IsSuccess,Evidence(shifted.Diagnostics));
+ Assert.Equal(3,shifted.Reuse!.ReusedDefinitions);
+ Assert.Equal(6,Instance(shifted.Ir!.Instances,"Controls.VolumeKnob").ResolvedTransform!.Matrix[12],6);
+ Assert.Equal(first.Geometry!.Artifact.Definitions.Select(d=>d.StepSha256),shifted.Geometry!.Artifact.Definitions.Select(d=>d.StepSha256));
+ }
+
+ [Fact]
+ public void CompositePublicAxisAndFrameFollowSolvedLocalChildPlacement()
+ {
+ var source = Source.Replace("At: 0mm; Clocking: 0deg;","At: 2mm; Clocking: 0deg;");
+ var result = new AssemblyM0Compiler().Compile(new AssemblyM0Parser().Parse(source).Source!);
+ Assert.True(result.IsSuccess,Evidence(result.Diagnostics));
+ var knob = Instance(result.Ir!.Instances,"Controls.VolumeKnob");
+ Assert.Equal(8,knob.ResolvedTransform!.Matrix[12],6); // Public seat is 2mm from definition origin.
+ var pub = knob.SemanticRoot.ExposedMembers["Spindle"];
+ Assert.True(pub.ExposedMembers["Frame"].TryBinding<ExactDatumFrameBinding>(out var frame));
+ Assert.Equal(2,frame.OriginZ,6);
+ Assert.True(pub.ExposedMembers["Axis"].TryBinding<ExactAxisBinding>(out var axis));
+ Assert.Equal(2,axis.OriginZ,6);
+ Assert.True(Assert.Single(result.Ir.AxisSeats!).Passed);
+ }
+
+ [Fact]
+ public void OpposedDirectionReversesMemberAxisWithoutReversingStation()
+ {
+ var source = Source.Replace("At: 7mm; Clocking: 30deg;","At: 7mm; Clocking: 30deg; Orientation: OpposedDirection;");
+ var result = new AssemblyM0Compiler().Compile(new AssemblyM0Parser().Parse(source).Source!);
+ Assert.True(result.IsSuccess,Evidence(result.Diagnostics));
+ var knob = Instance(result.Ir!.Instances,"Controls.VolumeKnob");
+ Assert.Equal(10,knob.ResolvedTransform!.Matrix[12],6);
+ Assert.Equal(-1,knob.ResolvedTransform.Matrix[8],6);
+ AssertMatrix(Matrix(knob),Matrix(Instance(AssemblyKinematics.Evaluate(result.Ir,new Dictionary<string,double>()).Instances,"Controls.VolumeKnob")));
+ Assert.True(Assert.Single(result.Ir.AxisSeats!).Passed);
+ }
+
+ [Fact]
+ public void ClockingDefaultsToZeroAndReferenceProjectsPerpendicularToDirection()
+ {
+ var source = Source.Replace("Clocking: 30deg;", "").Replace("Reference: [0,3,1]", "Reference: [9,3,1]");
+ var result = new AssemblyM0Compiler().Compile(new AssemblyM0Parser().Parse(source).Source!);
+ Assert.True(result.IsSuccess,Evidence(result.Diagnostics));
+ var m=Instance(result.Ir!.Instances,"Controls.VolumeKnob").ResolvedTransform!.Matrix;
+ Assert.Equal(0,m[0],6);
+ Assert.Equal(3/Math.Sqrt(10),m[1],6);
+ Assert.Equal(1/Math.Sqrt(10),m[2],6);
+ Assert.Equal(0,Assert.Single(result.Ir.AxisSeats!).Seating.ClockingDegrees);
+ }
+
+ [Theory]
+ [InlineData("Direction: [2,0,0]","Direction: [0,0,0]","assembly-axis-invalid-basis")]
+ [InlineData("Reference: [0,3,1]","Reference: [2,0,0]","assembly-axis-invalid-basis")]
+ [InlineData("At: 7mm;","","assembly-axis-station-missing")]
+ [InlineData("At: 7mm","At: 7deg","assembly-datum-measure-invalid")]
+ [InlineData("Clocking: 30deg","Clocking: 30mm","assembly-datum-measure-invalid")]
+ [InlineData("At: 7mm","At: 7mm; At: 8mm","assembly-datum-measure-invalid")]
+ [InlineData("Mate GripOnSpindle:","Mate SkirtOnSpindle:","assembly-datum-mate-duplicate")]
+ [InlineData("Clocking: 30deg","Clocking: 30deg; Support: true","assembly-datum-fields-invalid")]
+ [InlineData("Reference: [0,3,1]","Reference: [0,NaN,1]","assembly-datum-vector-invalid")]
+ [InlineData("Controls.VolumeKnob.Spindle]","Controls.VolumeKnob.Mount]","assembly-datum-member-outside-contract")]
+ [InlineData("Member: Controls.VolumeKnob.Spindle","Member: Controls.VolumeKnob.KnobSkirt.SpindleSeat","assembly-datum-member-scope")]
+ [InlineData("[Controls.VolumeKnob.Spindle]","[Controls.VolumeKnob.Spindle,Controls.Other.Spindle]","assembly-axis-revolute-member-count")]
+ [InlineData("-> [0,0,1]","-> [1,0,0]","assembly-axis-port-invalid")]
+ [InlineData("Axis Axis = [0mm,0mm,0mm]","Axis Axis = [1mm,0mm,0mm]","assembly-axis-port-invalid")]
+ [InlineData("<Assembly VolumeKnob = ControlKnob></Assembly>","<Assembly VolumeKnob = ControlKnob> Placement { From: Origin; To: World; } </Assembly>","assembly-placement-authority-conflict")]
+ [InlineData("Interface<Fixed> CoaxialStack","Interface<Revolute> CoaxialStack","assembly-axis-internal-motion-unsupported")]
+ public void InvalidAxisContractsFailClosed(string from,string to,string code)
+ {
+ var result = new AssemblyM0Parser().Parse(Source.Replace(from,to));
+ Assert.False(result.IsSuccess);
+ Assert.Contains(result.Diagnostics,d=>d.Code==code);
+ }
+
+ [Fact]
+ public void GuitarHasFourInstancesOfOneCoaxialKnobDefinition()
+ {
+ var compiled = new AssemblyM1Pipeline().CompileFile(FirmamentCorpusHarness.ResolveFixtureFullPath("fixtures/Canonical/AssemblyInterfaces/GuitarX0/guitar.firmasm"));
+ Assert.True(compiled.IsSuccess,Evidence(compiled.Diagnostics));
+ var ir=compiled.Ir!;
+ var knobs=ir.Instances.Where(i=>i.DefinitionIdentity=="ControlKnob").ToArray();
+ Assert.Equal(4,knobs.Length);
+ var definition=Assert.Single(ir.AssemblyDefinitions!,d=>d.DefinitionIdentity=="ControlKnob");
+ Assert.Equal(new double[]{0,3,12},definition.LocalAxisSeats!.Select(e=>e.Seating.StationMm).Order());
+ Assert.All(definition.LocalAxisSeats!,e=>Assert.True(e.Passed));
+ Assert.Equal(91,compiled.Geometry!.Artifact.Instances.Count);
+ Assert.Equal(53,compiled.Geometry.Artifact.Definitions.Count);
+ }
+
+ private static AssemblyInstanceIr Instance(IReadOnlyList<AssemblyInstanceIr> instances,string path)=>instances.Single(i=>i.Path.ToString()==path);
+ private static Transform3D Matrix(AssemblyInstanceIr instance)=>Transform3D.FromRowMajor(instance.ResolvedTransform!.Matrix);
+ private static string Evidence(IReadOnlyList<AssemblyDiagnostic> diagnostics)=>string.Join('\n',diagnostics.Select(d=>d.Code+": "+d.Message));
+ private static void AssertMatrix(Transform3D expected,Transform3D actual)
+ {
+ var a=expected.ToRowMajor(); var b=actual.ToRowMajor();
+ for(var i=0;i<16;i++) Assert.Equal(a[i],b[i],6);
+ }
+}
diff --git a/Aetheris.Kernel.Firmament/Assembly/AssemblyDatumAuthoring.cs b/Aetheris.Kernel.Firmament/Assembly/AssemblyDatumAuthoring.cs
index 17be4278..4e40254f 100644
--- a/Aetheris.Kernel.Firmament/Assembly/AssemblyDatumAuthoring.cs
+++ b/Aetheris.Kernel.Firmament/Assembly/AssemblyDatumAuthoring.cs
@@ -5,7 +5,7 @@ using Aetheris.Semantics;
namespace Aetheris.Kernel.Firmament.Assembly;
-internal sealed record AssemblyLayoutDatum(string Identity, string Plane, AssemblyFrameTransformSource Transform);
+internal sealed record AssemblyLayoutDatum(string Identity, string Plane, AssemblyFrameTransformSource Transform, bool IsAxis = false);
/// <summary>Bounded datum-directed Fixed seating. No constraint search or synthetic parts.</summary>
internal static class AssemblyDatumAuthoring
@@ -19,10 +19,34 @@ internal static class AssemblyDatumAuthoring
{
if (!IsTopLevel(source, header.Index)) continue;
var body = AssemblyM0Parser.BalancedBody(source, header.Index + header.Length - 1, diagnostics, "Concept layout");
- if (body is null || !Regex.IsMatch(body, @"\bPlane\s+\w+\s*\{")) continue;
+ if (body is null || !Regex.IsMatch(body, @"\b(?:Plane|Axis)\s+\w+\s*\{")) continue;
var owner = header.Groups["name"].Value;
var remaining = body;
var planes = new Dictionary<string, AssemblyFrameTransformSource>(StringComparer.Ordinal);
+ foreach (Match member in Regex.Matches(body, @"\bAxis\s+(?<name>\w+)\s*\{"))
+ {
+ var fields = AssemblyM0Parser.BalancedBody(body, member.Index + member.Length - 1, diagnostics, "layout axis");
+ if (fields is null) continue;
+ var name = member.Groups["name"].Value;
+ var errorsBefore = diagnostics.Count;
+ var origin = Vector(fields, "Origin", 3, true, diagnostics);
+ var direction = Vector(fields, "Direction", 3, false, diagnostics);
+ var reference = Vector(fields, "Reference", 3, false, diagnostics);
+ CheckFields(fields, ["Origin", "Direction", "Reference"], diagnostics);
+ if (diagnostics.Count != errorsBefore) continue;
+ var z = new Vector3D(direction[0], direction[1], direction[2]);
+ var radial = new Vector3D(reference[0], reference[1], reference[2]);
+ if (!TryUnit(z, out z) || !TryUnit(radial, out radial) || !TryUnit(radial - z * radial.Dot(z), out var x))
+ {
+ diagnostics.Add(new("assembly-axis-invalid-basis", $"Axis '{owner}.{name}' requires a nonzero Direction and a nonparallel Reference."));
+ continue;
+ }
+ var y = z.Cross(x);
+ var transform = new AssemblyFrameTransformSource(owner + "_" + name, "World", origin, "Z", 0,
+ [z.X,z.Y,z.Z], [y.X,y.Y,y.Z], new(sourceIdentity, header.Index + member.Index, member.Length + fields.Length + 1));
+ result.Add(new(owner + "." + name, owner + "." + name, transform, IsAxis: true));
+ remaining = remaining.Replace(member.Value + fields + "}", "", StringComparison.Ordinal);
+ }
foreach (Match member in Regex.Matches(body, @"\bPlane\s+(?<name>\w+)\s*\{"))
{
var fields = AssemblyM0Parser.BalancedBody(body, member.Index + member.Length - 1, diagnostics, "layout plane")!;
@@ -115,8 +139,10 @@ internal static class AssemblyDatumAuthoring
{
var usedFrames = new Dictionary<string, AssemblyFrameTransformSource>(StringComparer.Ordinal);
var seats = new Dictionary<string, (AssemblyDatumSeat Seat, AssemblyFramePlacementSource Placement)>(StringComparer.Ordinal);
+ var axisSeats = new Dictionary<string, (string Member, string Interface, string Datum, AssemblyFramePlacementSource Placement)>(StringComparer.Ordinal);
var resolved = new Dictionary<string, AssemblyLayoutDatum>(StringComparer.Ordinal);
var active = new HashSet<string>(StringComparer.Ordinal);
+ var mateNames = new HashSet<string>(StringComparer.Ordinal);
AssemblyLayoutDatum? Resolve(AssemblyLayoutDatum value)
{
if (resolved.TryGetValue(value.Identity, out var cached)) return cached;
@@ -185,13 +211,51 @@ internal static class AssemblyDatumAuthoring
{
var fields = AssemblyM0Parser.BalancedBody(body, header.Index + header.Length - 1, diagnostics, "datum Mate")!;
if (fields is null) continue;
- var contract = interfaces.FirstOrDefault(i => i.Name == header.Groups["type"].Value)?.DatumContract;
+ var definition = interfaces.FirstOrDefault(i => i.Name == header.Groups["type"].Value);
+ var contract = definition?.DatumContract;
if (contract is null)
{
if (Regex.IsMatch(fields, @"\bMember\s*:")) diagnostics.Add(new("assembly-datum-interface-unresolved", "Member/At Mate requires a datum-directed Fixed Interface."));
continue;
}
var member = Field(fields, "Member", diagnostics);
+ if (!mateNames.Add(header.Groups["name"].Value))
+ { diagnostics.Add(new("assembly-datum-mate-duplicate", $"Datum Mate '{header.Groups["name"].Value}' is duplicated in '{root.Name}'.")); continue; }
+ if (layout.FirstOrDefault(d => d.Identity == contract.Datum) is { IsAxis: true } axis)
+ {
+ if (!contract.Members.Contains(member, StringComparer.Ordinal))
+ diagnostics.Add(new("assembly-datum-member-outside-contract", $"'{member}' is not a member of '{definition!.Name}'."));
+ var axisParts = member.Split('.');
+ var child = axisParts.Length == 3 && axisParts[0] == root.Name ? root.Children.FirstOrDefault(c => c.Name == axisParts[1]) : null;
+ if (child is null)
+ { diagnostics.Add(new("assembly-datum-member-scope", "Axis seating requires a direct occurrence's published semantic port.")); continue; }
+ var port = child.ExposedSemantics.FirstOrDefault(p => p.ExposedName == axisParts[2]);
+ if (!ValidAxisPort(port))
+ { diagnostics.Add(new("assembly-axis-port-invalid", $"'{member}' requires an exact Axis and an aligned seating Frame with origin on the axis.")); continue; }
+ if (!Regex.IsMatch(fields, @"\bAt\s*:")) diagnostics.Add(new("assembly-axis-station-missing", "Axis seating requires At in mm."));
+ var station = Measure(fields, "At", "mm", diagnostics);
+ var clocking = Measure(fields, "Clocking", "deg", diagnostics);
+ var axisOrientation = Regex.IsMatch(fields, @"\bOrientation\s*:") ? Field(fields, "Orientation", diagnostics) : "SameDirection";
+ if (axisOrientation is not ("SameDirection" or "OpposedDirection"))
+ diagnostics.Add(new("assembly-datum-orientation-invalid", "Orientation requires SameDirection or OpposedDirection."));
+ CheckFields(fields, ["Member", "At", "Clocking", "Orientation"], diagnostics);
+ var resolvedAxis = Resolve(axis);
+ if (resolvedAxis is null) continue;
+ var basis = AssemblyFrameAuthoring.Compose(Transform3D.Identity, resolvedAxis.Transform, diagnostics);
+ var axisTarget = AssemblyFrameAuthoring.Compose(basis, new("AxisStation", "World", [0,0,station], "Z", clocking), diagnostics).ToRowMajor();
+ var sign = axisOrientation == "OpposedDirection" ? -1 : 1;
+ var name = resolvedAxis.Transform.Name + "__" + header.Groups["name"].Value;
+ usedFrames[name] = new(name, "World", [axisTarget[12],axisTarget[13],axisTarget[14]], "Z", 0,
+ [sign*axisTarget[8],sign*axisTarget[9],sign*axisTarget[10]], [sign*axisTarget[4],sign*axisTarget[5],sign*axisTarget[6]], axis.Transform.SourceSpan);
+ var placement = new AssemblyFramePlacementSource(axisParts[2] + ".Frame", new(name, name + ".Frame", [0,0,0], "Z", 0), definition!.Family, header.Groups["name"].Value,
+ new(definition.Name, contract.Datum, member, station, clocking, Enum.TryParse<DatumOrientationRelation>(axisOrientation, out var relation) ? relation : DatumOrientationRelation.SameDirection));
+ var axisOccurrence = root.Name + "." + child.Name;
+ if (seats.ContainsKey(axisOccurrence) || !axisSeats.TryAdd(axisOccurrence, (member, definition.Name, contract.Datum, placement)))
+ diagnostics.Add(new("assembly-placement-authority-conflict", $"'{axisOccurrence}' has multiple datum Mates."));
+ continue;
+ }
+ if (definition!.Family != MechanicalInterfaceFamily.Fixed)
+ { diagnostics.Add(new("assembly-datum-family-invalid", "A plane datum requires Interface<Fixed>; Revolute requires a Concept Axis.")); continue; }
var at = Field(fields, "At", diagnostics);
var orientation = Field(fields, "Orientation", diagnostics);
var support = Regex.IsMatch(fields, @"\bSupport\s*:\s*true\b");
@@ -225,17 +289,26 @@ internal static class AssemblyDatumAuthoring
usedFrames[targetSpec.Name] = targetSpec;
var seat = new AssemblyDatumSeat(header.Groups["type"].Value, contract.Datum, parts[2] + ".Frame",
datum.Transform.Translation.ToArray(), datum.Transform.Normal!.ToArray(), support);
- if (!seats.TryAdd(occurrence, (seat, new(parts[2] + ".Frame", new(header.Groups["name"].Value,
+ if (axisSeats.ContainsKey(occurrence) || !seats.TryAdd(occurrence, (seat, new(parts[2] + ".Frame", new(header.Groups["name"].Value,
targetSpec.Name + ".Frame", [0,0,0], "Z", 0)))))
diagnostics.Add(new("assembly-placement-authority-conflict", $"'{occurrence}' has multiple datum-directed Mates."));
}
// Each member of a contract declared in this scope must be realized once.
foreach (var definition in interfaces.Where(i => i.DatumContract is not null))
foreach (var member in definition.DatumContract!.Members.Where(p => p.StartsWith(root.Name + ".", StringComparison.Ordinal)))
- if (!seats.Any(p => p.Value.Seat.Interface == definition.Name && p.Key + "." + p.Value.Seat.Port[..^6] == member))
+ if (!seats.Any(p => p.Value.Seat.Interface == definition.Name && p.Key + "." + p.Value.Seat.Port[..^6] == member)
+ && !axisSeats.Any(p => p.Value.Interface == definition.Name && p.Value.Member == member))
diagnostics.Add(new("assembly-datum-member-unseated", $"Contract member '{member}' requires one datum Mate."));
var children = root.Children.Select(child =>
{
+ if (axisSeats.TryGetValue(root.Name + "." + child.Name, out var axisSeating))
+ {
+ if (child.FramePlacement is not null || child.ExplicitTransform is not null)
+ diagnostics.Add(new("assembly-placement-authority-conflict", $"'{root.Name}.{child.Name}' has authored Placement and axis Mate."));
+ return child with { FramePlacement = axisSeating.Placement, PlacementAuthority = PlacementAuthority.MateDerived,
+ Provenance = [.. child.Provenance ?? [], new("concept-axis-seating", axisSeating.Datum, axisSeating.Interface),
+ new("concept-axis-member", axisSeating.Member, axisSeating.Placement.MateName!)] };
+ }
if (!seats.TryGetValue(root.Name + "." + child.Name, out var seating)) return child;
if (child.FramePlacement is not null || child.ExplicitTransform is not null)
diagnostics.Add(new("assembly-placement-authority-conflict", $"'{root.Name}.{child.Name}' has authored Placement and datum Mate."));
@@ -248,6 +321,55 @@ internal static class AssemblyDatumAuthoring
return root with { Children = children };
}
+ internal static IReadOnlyList<AssemblyAxisSeatEvidence> ValidateAxisSeats(AssemblySource source, AssemblyIr ir,
+ List<AssemblyDiagnostic> diagnostics)
+ {
+ var result = new List<AssemblyAxisSeatEvidence>();
+ foreach (var child in source.Root.Children.Where(c => c.FramePlacement?.AxisSeat is not null))
+ {
+ var placement = child.FramePlacement!;
+ var seat = placement.AxisSeat!;
+ var instance = ir.Instances.Single(i => i.Path.ToString() == source.Root.Name + "." + child.Name);
+ var joint = ir.Joints?.SingleOrDefault(j => j.Name == placement.MateName);
+ if (joint is null || instance.ResolvedTransform is null) continue; // Existing placement diagnostics own unresolved input.
+ if (!AssemblyM0Compiler.TryResolve(AssemblyPath.Parse(seat.Member + ".Axis"), ir.Instances, out var axisReference)) continue;
+ var axis = (ExactAxisBinding)AssemblyWorldQuery.Resolve(ir, axisReference!.Value.StableIdentity);
+ var target = (ExactDatumFrameBinding)AssemblyWorldQuery.Resolve(ir, joint.ParentFrameSemanticId);
+ var frame = (ExactDatumFrameBinding)AssemblyWorldQuery.Resolve(ir, joint.ChildFrameSemanticId);
+ var direction = new Vector3D(axis.DirectionX,axis.DirectionY,axis.DirectionZ);
+ direction.TryNormalize(out direction);
+ var z = new Vector3D(target.ZAxisX,target.ZAxisY,target.ZAxisZ);
+ var delta = new Vector3D(axis.OriginX-target.OriginX,axis.OriginY-target.OriginY,axis.OriginZ-target.OriginZ);
+ var axisResidual = delta.Cross(z).Length;
+ var stationResidual = new Vector3D(frame.OriginX-target.OriginX,frame.OriginY-target.OriginY,frame.OriginZ-target.OriginZ).Length;
+ var x = new Vector3D(frame.XAxisX,frame.XAxisY,frame.XAxisZ);
+ var targetX = new Vector3D(target.XAxisX,target.XAxisY,target.XAxisZ);
+ var angle = Math.Max(Math.Atan2(direction.Cross(z).Length, direction.Dot(z)), Math.Atan2(x.Cross(targetX).Length, x.Dot(targetX)));
+ var passed = axisResidual <= 1e-6 && stationResidual <= 1e-6 && angle <= 1e-6;
+ result.Add(new(placement.MateName!, instance.StableId, seat, joint.DegreesOfFreedom, axisResidual, stationResidual, angle, passed));
+ if (!passed) diagnostics.Add(new("assembly-axis-residual-failed", $"Axis Mate '{placement.MateName}' failed exact datum residual validation."));
+ }
+ return result;
+ }
+
+ private static bool ValidAxisPort(SemanticValue? port)
+ {
+ if (port is null || !port.ExposedMembers.TryGetValue("Axis", out var a) || !a.TryBinding<ExactAxisBinding>(out var axis)
+ || !port.ExposedMembers.TryGetValue("Frame", out var f) || !f.TryBinding<ExactDatumFrameBinding>(out var frame)) return false;
+ var direction = new Vector3D(axis.DirectionX,axis.DirectionY,axis.DirectionZ);
+ var z = new Vector3D(frame.ZAxisX,frame.ZAxisY,frame.ZAxisZ);
+ var delta = new Vector3D(frame.OriginX-axis.OriginX,frame.OriginY-axis.OriginY,frame.OriginZ-axis.OriginZ);
+ return TryUnit(direction, out direction) && TryUnit(z, out z)
+ && (direction - z).Length <= 1e-6 && delta.Cross(direction).Length <= 1e-6;
+ }
+
+ private static bool TryUnit(Vector3D value, out Vector3D unit)
+ {
+ var scale = Math.Max(Math.Abs(value.X), Math.Max(Math.Abs(value.Y), Math.Abs(value.Z)));
+ unit = Vector3D.Zero;
+ return double.IsFinite(scale) && scale > 1e-12 && (value / scale).TryNormalize(out unit);
+ }
+
private static double Measure(string fields, string name, string unit, List<AssemblyDiagnostic> diagnostics)
{
var matches = Regex.Matches(fields, $@"\b{name}\s*:\s*(?<v>[-+0-9.eE]+){unit}\s*;?");
@@ -297,7 +419,7 @@ internal static class AssemblyDatumAuthoring
private static void CheckFields(string fields, string[] names, List<AssemblyDiagnostic> diagnostics)
{
- var remaining = Regex.Replace(fields, $@"\b(?:{string.Join('|', names)})\s*:\s*(?:\[[^]]*\]|[A-Za-z_]\w*(?:\.\w+)*)\s*;?", "");
+ var remaining = Regex.Replace(fields, $@"\b(?:{string.Join('|', names)})\s*:\s*(?:\[[^]]*\]|[-+0-9.eE]+(?:mm|deg)|[A-Za-z_]\w*(?:\.\w+)*)\s*;?", "");
if (!string.IsNullOrWhiteSpace(remaining.Replace(";", ""))) diagnostics.Add(new("assembly-datum-fields-invalid", $"Unknown or malformed datum fields: {remaining.Trim()}"));
}
}
diff --git a/Aetheris.Kernel.Firmament/Assembly/AssemblyFrameAuthoring.cs b/Aetheris.Kernel.Firmament/Assembly/AssemblyFrameAuthoring.cs
index 0a23793a..e29981f8 100644
--- a/Aetheris.Kernel.Firmament/Assembly/AssemblyFrameAuthoring.cs
+++ b/Aetheris.Kernel.Firmament/Assembly/AssemblyFrameAuthoring.cs
@@ -147,9 +147,20 @@ internal static class AssemblyFrameAuthoring
var a = Publish(owner, "__LayoutSource" + suffix, from.Value.Frame, layout.From);
var b = Publish(to.Value.Owner, "__LayoutTarget" + suffix, Compose(to.Value.Frame, layout.Target, diagnostics), layout.Target.From);
var name = "__Layout" + suffix;
- interfaces.Add(new("interface:" + name, name, [new("Moving", ["DatumFrameCapable"]),new("Target", ["DatumFrameCapable"])],
- [new(PlacementConstraintKind.FrameCoincident,"Moving",".","Target",".")], SourceSpan: layout.Target.SourceSpan));
- mates.Add(new(name,name,[new("Moving",a),new("Target",b)],layout.Target.SourceSpan));
+ if (layout.JointFamily is { } family)
+ {
+ interfaces.Add(new("interface:" + name, name, [new("A", ["DatumFrameCapable"]),new("B", ["DatumFrameCapable"])],
+ [new(PlacementConstraintKind.FrameCoincident,"A",".","B",".")],
+ AdmittedFreeMotions: family == MechanicalInterfaceFamily.Revolute ? ["rotation:about-axis"] : [],
+ Family: family, SourceSpan: layout.Target.SourceSpan));
+ mates.Add(new(layout.MateName!,name,[new("A",b),new("B",a)],layout.Target.SourceSpan));
+ }
+ else
+ {
+ interfaces.Add(new("interface:" + name, name, [new("Moving", ["DatumFrameCapable"]),new("Target", ["DatumFrameCapable"])],
+ [new(PlacementConstraintKind.FrameCoincident,"Moving",".","Target",".")], SourceSpan: layout.Target.SourceSpan));
+ mates.Add(new(name,name,[new("Moving",a),new("Target",b)],layout.Target.SourceSpan));
+ }
}
// Validate unused named transforms too: a malformed/cyclic declaration must not disappear.
foreach (var name in named.Keys) Resolve(name + ".Frame", root.Path.ToString(), []);
diff --git a/Aetheris.Kernel.Firmament/Assembly/AssemblyM0Compiler.cs b/Aetheris.Kernel.Firmament/Assembly/AssemblyM0Compiler.cs
index d3bee228..af08de2e 100644
--- a/Aetheris.Kernel.Firmament/Assembly/AssemblyM0Compiler.cs
+++ b/Aetheris.Kernel.Firmament/Assembly/AssemblyM0Compiler.cs
@@ -81,6 +81,7 @@ public sealed class AssemblyM0Compiler
var ir = new AssemblyIr("aetheris/assembly-ir/m0", $"assembly:{source.Name}", source.Name,
instances.Single(x => x.ParentStableId is null).StableId, instances, source.Interfaces, mates,
constraints, placements, relations, stackups, fits, diagnostics, assemblyDefinitions, panelMateEvidence, datums, datumSolutions, source.SourceDependencies, joints, source.Patterns);
+ ir = ir with { AxisSeats = AssemblyDatumAuthoring.ValidateAxisSeats(source, ir, diagnostics) };
return new(ir, diagnostics, perf);
static string SemanticPath(AssemblyInstanceIr instance, SemanticValue value)
diff --git a/Aetheris.Kernel.Firmament/Assembly/AssemblyM0Models.cs b/Aetheris.Kernel.Firmament/Assembly/AssemblyM0Models.cs
index 20acae96..79c259f1 100644
--- a/Aetheris.Kernel.Firmament/Assembly/AssemblyM0Models.cs
+++ b/Aetheris.Kernel.Firmament/Assembly/AssemblyM0Models.cs
@@ -71,7 +71,13 @@ public sealed record AssemblyMemberSource(
public sealed record AssemblyFrameTransformSource(string Name, string From, double[] Translation,
string RotationAxis, double RotationDegrees, double[]? Normal = null, double[]? Up = null,
SemanticSourceSpan? SourceSpan = null);
-public sealed record AssemblyFramePlacementSource(string From, AssemblyFrameTransformSource Target);
+public sealed record AssemblyFramePlacementSource(string From, AssemblyFrameTransformSource Target,
+ MechanicalInterfaceFamily? JointFamily = null, string? MateName = null, AssemblyAxisSeatSource? AxisSeat = null);
+public sealed record AssemblyAxisSeatSource(string Interface, string Datum, string Member,
+ double StationMm, double ClockingDegrees, DatumOrientationRelation Orientation);
+public sealed record AssemblyAxisSeatEvidence(string Mate, string InstanceStableId, AssemblyAxisSeatSource Seating,
+ int DegreesOfFreedom, double AxisResidualMm, double StationResidualMm, double AngularResidualRadians,
+ bool Passed, string Evidence = "exact published axis/frame against Concept target; no material-carrier inference");
/// <summary>A reusable, locally-authored Assembly product definition. Its children
/// remain product-visible, while only <see cref="AssemblyMemberSource.ExposedSemantics"/>
@@ -192,7 +198,8 @@ public sealed record AssemblyDefinitionIr(
IReadOnlyList<PlacementConstraintIr>? LocalPlacementConstraints = null,
IReadOnlyList<AssemblyDatumIr>? LocalDatums = null,
IReadOnlyList<DatumMateSolutionIr>? LocalDatumMateSolutions = null,
- IReadOnlyList<InterfaceFitResultIr>? LocalFitResults = null);
+ IReadOnlyList<InterfaceFitResultIr>? LocalFitResults = null,
+ IReadOnlyList<AssemblyAxisSeatEvidence>? LocalAxisSeats = null);
public sealed record AssemblyPerformanceIr(double ParseMilliseconds, double BindMilliseconds, double MateValidationMilliseconds, double PlacementMilliseconds, double DimensionalGraphMilliseconds, double ToleranceAnalysisMilliseconds, double DefinitionMaterializationMilliseconds = 0, double GeometryExecutionMilliseconds = 0);
public sealed record AssemblyGeometryMetricsIr(int Bodies, int Faces, int Edges, int Vertices, double[] Minimum, double[] Maximum);
@@ -215,7 +222,8 @@ public sealed record AssemblyIr(
IReadOnlyList<DatumMateSolutionIr>? DatumMateSolutions = null,
IReadOnlyList<AssemblySourceDependencyIr>? SourceDependencies = null,
IReadOnlyList<AssemblyJointIr>? Joints = null,
- IReadOnlyList<FirmamentV2CanonicalPatternDecl>? Patterns = null);
+ IReadOnlyList<FirmamentV2CanonicalPatternDecl>? Patterns = null,
+ IReadOnlyList<AssemblyAxisSeatEvidence>? AxisSeats = null);
public sealed record AssemblyCompilationResult(AssemblyIr? Ir, IReadOnlyList<AssemblyDiagnostic> Diagnostics, AssemblyPerformanceIr? Performance = null)
{
diff --git a/Aetheris.Kernel.Firmament/Assembly/AssemblyM0Parser.cs b/Aetheris.Kernel.Firmament/Assembly/AssemblyM0Parser.cs
index eb30f3b8..22ed2943 100644
--- a/Aetheris.Kernel.Firmament/Assembly/AssemblyM0Parser.cs
+++ b/Aetheris.Kernel.Firmament/Assembly/AssemblyM0Parser.cs
@@ -122,7 +122,7 @@ public sealed class AssemblyM0Parser
var layout = AssemblyDatumAuthoring.ParseLayouts(source, sourceIdentity, diagnostics, out var partDeclarations);
foreach (var contract in interfaces.Where(i => i.DatumContract is not null))
if (!layout.Any(d => d.Identity == contract.DatumContract!.Datum && d.Plane == d.Identity))
- diagnostics.Add(new("assembly-datum-plane-unresolved", $"Interface '{contract.Name}' requires a declared Concept plane '{contract.DatumContract!.Datum}'."));
+ diagnostics.Add(new("assembly-datum-plane-unresolved", $"Interface '{contract.Name}' requires a declared Concept plane or Axis '{contract.DatumContract!.Datum}'."));
var declarationChars = partDeclarations.ToCharArray();
foreach (Match header in Regex.Matches(source, @"\b(?:Template\s*<[^>]+>\s*Assembly|Assembly|Interface(?:\s*<[^>]+>)?)\s+[A-Za-z_]\w*(?:\s*:\s*[A-Za-z_]\w*)?\s*\{"))
{
@@ -240,10 +240,13 @@ public sealed class AssemblyM0Parser
var name = header.Groups["name"].Value;
if (Regex.IsMatch(body, @"\bDatum\s*:"))
{
- if (header.Groups["family"].Value != "Fixed") diagnostics.Add(new("assembly-datum-family-invalid", "Datum contracts require Interface<Fixed>."));
+ var datumFamily = header.Groups["family"].Value == "Revolute" ? MechanicalInterfaceFamily.Revolute : MechanicalInterfaceFamily.Fixed;
+ if (header.Groups["family"].Value is not ("Fixed" or "Revolute")) diagnostics.Add(new("assembly-datum-family-invalid", "Datum contracts require Interface<Fixed> or Interface<Revolute>."));
var contract = AssemblyDatumAuthoring.ParseContract(body, diagnostics);
+ if (datumFamily == MechanicalInterfaceFamily.Revolute && contract.Members.Count != 1)
+ diagnostics.Add(new("assembly-axis-revolute-member-count", "A datum Revolute contract requires exactly one moving occurrence."));
if (result.Any(i => i.Name == name)) diagnostics.Add(new("assembly-interface-duplicate-name", $"Interface '{name}' is duplicated."));
- else result.Add(new("interface:" + name, name, [], [], Family: MechanicalInterfaceFamily.Fixed, DatumContract: contract));
+ else result.Add(new("interface:" + name, name, [], [], Family: datumFamily, DatumContract: contract));
continue;
}
var family = header.Groups["family"].Success ? Enum.Parse<MechanicalInterfaceFamily>(header.Groups["family"].Value) : MechanicalInterfaceFamily.Custom;
@@ -396,6 +399,8 @@ public sealed class AssemblyM0Parser
var root = ParseTree(body, sourceIdentity, diagnostics, result, interfaces, new Dictionary<string, AssemblyMemberSource>(StringComparer.Ordinal), gearAuthorities, publishedPorts);
if (root is null) continue;
root = AssemblyDatumAuthoring.Bind(body, root, layout ?? [], interfaces, diagnostics, out var datumFrames, publishedPorts);
+ if (root.Children.Any(c => c.FramePlacement?.JointFamily == MechanicalInterfaceFamily.Revolute))
+ diagnostics.Add(new("assembly-axis-internal-motion-unsupported", "Reusable definitions have rigid solved children. Declare a Revolute mate on the complete occurrence in its owning root assembly."));
var exposed = ParseAssemblyExposes(body, root, sourceIdentity, diagnostics);
root = root with { ExposedSemantics = exposed, IsEncapsulatedDefinition = true };
var name = template.Groups["name"].Value;
@@ -563,7 +568,7 @@ public sealed class AssemblyM0Parser
[.. definition.Provenance, new("assembly-template-specialization", definition.Name, specializationIdentity, SemanticSourceSpan.Generated(sourceIdentity))],
local.Ir.Instances, local.Ir.Mates, local.Ir.Placements, local.Ir.DimensionalRelations, local.Ir.ToleranceStackups,
publicSemantics, publicRelations, watch.Elapsed.TotalMilliseconds,
- local.Ir.PlacementConstraints, local.Ir.Datums, local.Ir.DatumMateSolutions, local.Ir.FitResults);
+ local.Ir.PlacementConstraints, local.Ir.Datums, local.Ir.DatumMateSolutions, local.Ir.FitResults, local.Ir.AxisSeats);
specializedRoot = specializedRoot with { ExposedSemantics = publicSemantics, IsEncapsulatedDefinition = true, SolvedAssemblyDefinition = definitionIr, DefinitionIdentity = specializationIdentity };
specializationCache[specializationIdentity] = specializedRoot;
return RenameOccurrence(specializedRoot, occurrenceName);
@@ -583,9 +588,24 @@ public sealed class AssemblyM0Parser
bindings.Add(gear with { RelativeOccurrencePath = [.. owner.Path.Segments.Skip(1), .. gear.RelativeOccurrencePath ?? []] });
}
try { bindings.Add(AssemblyWorldQuery.Resolve(localIr, reference!.Value.StableIdentity)); } catch (InvalidOperationException) { }
- return new(exposed.StableIdentity, exposed.Type, exposed.Capabilities.Values, bindings, exposed.ExposedMembers.Values, exposed.Provenance,
+ return new(exposed.StableIdentity, exposed.Type, exposed.Capabilities.Values, bindings,
+ exposed.ExposedMembers.Values.Select(member => reference!.Value.ExposedMembers.TryGetValue(member.ExposedName!, out var local)
+ ? BindMember(member, local) : member), exposed.Provenance,
exposed.AuthoredSourceSpan, SemanticSourceSpan.Generated(sourceIdentity), exposed.ExposedName);
+ SemanticValue BindMember(SemanticValue member, SemanticValue local)
+ {
+ // Typed endpoints (notably Gear) can synthesize public members that
+ // are not source children. Their typed authority retains ownership;
+ // ordinary published composites rebase only corresponding children.
+ var transformed = member.Bindings.Where(binding => binding is not (ExactAxisBinding or ExactPlaneBinding or ExactDatumFrameBinding or ExactPointBinding)).ToList();
+ try { transformed.Add(AssemblyWorldQuery.Resolve(localIr, local.StableIdentity)); } catch (InvalidOperationException) { }
+ return new(member.StableIdentity, member.Type, member.Capabilities.Values, transformed,
+ member.ExposedMembers.Values.Select(child => local.ExposedMembers.TryGetValue(child.ExposedName!, out var value)
+ ? BindMember(child, value) : child),
+ member.Provenance, member.AuthoredSourceSpan, member.GeneratedSourceSpan, member.ExposedName);
+ }
+
static IEnumerable<SemanticValue> Flatten(SemanticValue value)
{
yield return value;
diff --git a/docs/public/firmament/assemblies.md b/docs/public/firmament/assemblies.md
index b81c382c..7461ad46 100644
--- a/docs/public/firmament/assemblies.md
+++ b/docs/public/firmament/assemblies.md
@@ -1,5 +1,8 @@
# Typed interfaces and reusable subassemblies
+For common-axis placement and whole-component rotation, see
+[Concept-directed coaxial mating](concept-axis-mating-proposal.md).
+
For layout-first placement against authored Concept planes, see
[Concept-directed Fixed seating](datum-seating.md).
diff --git a/docs/public/firmament/assembly-components-and-sites.md b/docs/public/firmament/assembly-components-and-sites.md
index e2e159e1..db7c2335 100644
--- a/docs/public/firmament/assembly-components-and-sites.md
+++ b/docs/public/firmament/assembly-components-and-sites.md
@@ -1,5 +1,9 @@
# Components and mounting sites
+The knob stack now seats three rigid children on one Concept spindle at stations
+0, 3 and 12mm. See [Concept-directed coaxial mating](concept-axis-mating-proposal.md)
+for its Fixed contract and the complete-knob Revolute example.
+
Organize an assembly around complete components: a knob, selector or tuner owns
its children, local dimensions and published mounting frame. Pattern component
occurrences rather than separate categories of their constituent parts.
diff --git a/docs/public/firmament/concept-axis-mating-proposal.md b/docs/public/firmament/concept-axis-mating-proposal.md
new file mode 100644
index 00000000..2574f9a7
--- /dev/null
+++ b/docs/public/firmament/concept-axis-mating-proposal.md
@@ -0,0 +1,262 @@
+# Concept-directed coaxial mating
+
+Status: implemented through the existing assembly frame solver and kinematics path.
+The guitar knob stack uses Fixed axis seating. The complete-knob fixture qualifies
+one root-owned Revolute with rigid children. Geometry construction remains independent.
+
+## Design intent
+
+Declare one Concept axis, publish each component's corresponding axis and seat
+frame, then realize the components on that common datum. Do not solve a network
+of pairwise cylinder coincidences. Product-tree nesting remains containment;
+the Interface owns the relationship and the Mate owns its realization.
+
+A shared axis establishes a common line. It leaves axial translation and angular
+phase unspecified. Fixed placement therefore needs an axial station and clocking;
+Revolute placement fixes the station but permits one angle state. A clocking
+reference is authored explicitly, rather than inferred from global X or Up.
+
+Assembly axes are three-dimensional. The existing `Axis2` is a two-dimensional
+profile/pattern guide, and `Axis2D` is not the current spelling. An Axis2 may later
+be lifted through an explicit construction frame; silently treating a profile
+line as a spatial rotation axis would conflate two meanings. Use the existing
+`Axis` name for spatial datum intent.
+
+## Knob syntax
+
+```firmament
+Concept Struct KnobLayout {
+ Axis Spindle {
+ Origin: [0mm,0mm,0mm];
+ Direction: [0,0,1];
+ Reference: [1,0,0];
+ }
+}
+
+Subassembly ControlKnob {
+ <Assembly ControlKnob>
+ <Part Skirt = Drum<R:12mm,H:3mm>></Part>
+ <Part Grip = Drum<R:9mm,H:9mm>></Part>
+ <Part Cap = Drum<R:5mm,H:1mm>></Part>
+ </Assembly>
+
+ Interface<Fixed> CoaxialStack {
+ Datum: KnobLayout.Spindle;
+ Members: [ControlKnob.Skirt.SpindleSeat,
+ ControlKnob.Grip.SpindleSeat,
+ ControlKnob.Cap.SpindleSeat];
+ }
+ Mate SkirtOnSpindle: CoaxialStack {
+ Member: ControlKnob.Skirt.SpindleSeat;
+ At: 0mm;
+ Clocking: 0deg;
+ }
+ Mate GripOnSpindle: CoaxialStack {
+ Member: ControlKnob.Grip.SpindleSeat;
+ At: 3mm;
+ Clocking: 0deg;
+ }
+ Mate CapOnSpindle: CoaxialStack {
+ Member: ControlKnob.Cap.SpindleSeat;
+ At: 12mm;
+ Clocking: 0deg;
+ }
+
+ Anchor: ControlKnob;
+ Expose {
+ DatumFrame Mount = Skirt.SpindleSeat.Frame;
+ Semantic Spindle = Skirt.SpindleSeat;
+ }
+}
+```
+
+The existing public Mount frame can remain compatible with current placement
+callers. The additional composite Spindle publication carries axis and frame for
+coaxial contracts. Each declared member must be realized exactly once. There is
+no Placement block on these mated occurrences and no second placement authority.
+
+Here `At` is a signed Length measured from the Concept axis origin along its
+normalized Direction. It is not a world-space Z coordinate. `Clocking` is an Angle
+about that direction, measured from Reference. Require an explicit At; Clocking
+may default to zero. Existing Orientation spellings can remain SameDirection and
+OpposedDirection, defaulting to SameDirection. The latter reverses the member's
+seat-frame axis without reversing the datum's station convention.
+
+Reference is a dimensionless radial zero-angle direction. Project it perpendicular
+to Direction and normalize; reject zero, nonfinite or parallel vectors. Require
+Reference for this complete-placement contract. Preserve the ordinary Axis value
+as origin/direction: the assembly layout datum owns the auxiliary reference used
+to construct its frame. This does not change revolve's axis meaning.
+
+## Definition-owned ports
+
+The current publication grammar already accepts an explicit axis and frame in
+one semantic port. A Drum can publish the following intent while still using
+Circle2 plus Extrude:
+
+```firmament
+Expose {
+ Semantic SpindleSeat {
+ Axis Axis = [0mm,0mm,0mm] -> [0,0,1];
+ DatumFrame Frame = [0mm,0mm,0mm]
+ x [1,0,0] y [0,1,0] z [0,0,1];
+ }
+}
+```
+
+The axis is definition-owned, not guessed from an occurrence bounding box or an
+arbitrary BRep face. This particular Drum has a circle centered at local origin
+and extrusion along local Z, so the declared axis matches its construction.
+For more general definitions, axis publication must remain explicit or derive
+through a qualified construction source.
+
+Validate that the published frame origin lies on the published axis and its Z
+direction agrees with the axis. A misplaced frame must not silently become the
+material axis merely because it has been named SpindleSeat. Preserve exact datum
+residual evidence; distinguish it from any additional material-carrier proof.
+No arbitrary-body symmetry recognition, bore-fit inference or automatic face
+selection is part of this slice.
+
+## Revolute use
+
+Fix the knob's children to their common local spindle. In the owning control
+assembly, mount the complete knob as one rotating occurrence:
+
+```firmament
+Interface<Revolute> VolumeControl {
+ Datum: ControlLayout.VolumeAxis;
+ Members: [Electronics.VolumeKnob.Spindle];
+}
+Mate VolumeRotation: VolumeControl {
+ Member: Electronics.VolumeKnob.Spindle;
+ At: 0mm;
+ Clocking: 0deg;
+}
+```
+
+ControlLayout.VolumeAxis has its own authored Origin, Direction and Reference,
+or derives from an independently placed shaft's published axis/frame through a
+later qualified derivation form. Clocking specifies the zero-state pose; it does
+not lock a Revolute joint. Its angle state belongs to VolumeRotation and rotates
+the complete knob and its children together.
+
+One axis does not imply shared motion. Giving three separate parts Revolute
+mates would create three independent angular degrees of freedom. Do not silently
+couple those joints. The axis-directed Revolute contract admits one
+moving component per Interface; independent coaxial rotors can declare separate
+Interfaces sharing the same Concept axis. General multi-body coupling is deferred.
+
+The moving member may be a direct Part or a direct reusable Assembly with an
+appropriate exposed port. Traversal through private subassembly children remains
+forbidden. Supporting direct Assembly ports is necessary here: a complete knob
+should not have to be flattened to get a joint.
+
+## Implementation and inspection
+
+AssemblyDatumAuthoring distinguishes Plane and Axis layout datums. Axis layout
+constructs an exact frame from Origin, normalized Direction and the perpendicular
+projection of Reference. Existing plane seating retains its named DatumFrame At
+form. Axis seating uses a required signed mm At and optional deg Clocking.
+
+The binder validates the published Axis/Frame contract, membership, direct-owner
+scope and unique placement authority. Frame authoring lowers the result to the
+existing FrameCoincident solver. Fixed locks the frame; Revolute creates an ordinary
+one-DOF AssemblyJointIr owned by the containing assembly. No helper Part is created.
+Composite public ports rebase their nested Axis and Frame to the solved definition
+coordinate system before reuse.
+
+Inspection exposes `AssemblyIr.AxisSeats` for direct root-owned mates and
+`AssemblyDefinitionIr.LocalAxisSeats` for rigid reusable definitions. Evidence names
+the source Interface, datum, member, signed station, clocking, orientation and DOF.
+It measures exact axis-line, seating-origin and angular residuals against the Concept
+target. This proves the published datums agree; it does not infer cylinder geometry,
+bore fit or surface contact. Existing plane `DatumSeats` retain their separate
+material-contact checks.
+
+Current bounded limits:
+
+- Axis declarations admit literal Origin/Direction/Reference only. Projection from
+ a published shaft is a future derivation form, not currently accepted syntax.
+- Members name a direct Part or direct reusable Assembly public semantic port.
+ Private child traversal is rejected.
+- A datum Revolute contract has exactly one member. The state key is the Mate name.
+- Reusable definitions remain rigid solved components. A Revolute inside a reusable
+ definition reports `assembly-axis-internal-motion-unsupported`; put that joint on
+ the complete occurrence in the root assembly. Dynamic definition propagation is
+ deferred explicitly.
+- No general Lower language, symmetry detector or Revolve rewrite is introduced.
+
+## Geometry choice and qualification
+
+Keep the present extruded circular parts for the first pass. They already express
+the right simple geometry. A shaped rotary knob with an axial silhouette, shoulder
+or taper could later use Revolve for clearer construction intent; switching to
+Revolve must not change its mating contract. Features within one materialized
+part share that part's Concept construction axis; assembly Interfaces apply to
+separate occurrences, not decorative features that are already one rigid body.
+
+The regression suite covers:
+
+- The knob's three members share the datum axis at stations 0, 3 and 12mm.
+- Translating/tilting only the datum changes placement and reuses exact bodies.
+- Nonzero clocking and OpposedDirection produce deterministic proper frames.
+- Missing stations, zero/parallel basis vectors, bad units, unpublished axes,
+ inconsistent axis/frame ports and competing placement authorities fail typed.
+- A whole-knob Revolute has exactly one angle state; its children stay rigid and
+ geometry definitions remain shared when state changes.
+- The real guitar retains 53 exact body definitions and 91 visible part occurrences.
+ Fresh STEP and USD exports qualify the existing interchange path.
+
+Moving the body-level knob seat locations away from their current explicit
+coordinates is a separate layout refinement. This slice removes the
+independent child X/Y/axis assumptions inside each coaxial component.
+
+## Executable examples
+
+The directly authored guitar implementation is
+[`knob.firmament`](../../../fixtures/Canonical/AssemblyInterfaces/GuitarX0/knob.firmament).
+Its leaf names remain KnobSkirt, AmberKnob and KnobCap for appearance compatibility.
+The public Mount frame remains available to its four patterned callers.
+
+[`coaxial-knob.firmasm`](../../../fixtures/Canonical/AssemblyInterfaces/coaxial-knob.firmasm)
+uses that same component on a tilted spindle with nonzero station and clocking:
+
+```powershell
+dotnet run --project Aetheris.CLI -c Release -- asm inspect fixtures/Canonical/AssemblyInterfaces/coaxial-knob.firmasm --json
+dotnet run --project Aetheris.CLI -c Release -- asm export-usd fixtures/Canonical/AssemblyInterfaces/coaxial-knob.firmasm artifacts/local/coaxial-mating/knob.usda --state VolumeRotation=90 --json
+```
+
+Changing only Concept layout reuses the exact part definitions in a
+FirmamentCompilationSession. Changing VolumeRotation evaluates occurrence poses
+against the compiled model; its three child transforms remain rigid and no
+materialization is invoked.
+
+## Qualification evidence (2026-10-01)
+
+- Release solution build succeeded. The fast core lane passed 1,004 tests.
+- Focused axis, datum, kinematics, guitar, Gear and Difference Engine tests: 67 passed.
+- Full solution gate: 4,130 passed, seven existing skips, zero failures, 20 projects.
+ The gate uses one MSBuild worker and serial xUnit test collections, as in the
+ preceding component milestone.
+- All three local knob seats and the complete-knob Revolute have zero exact datum
+ residuals. The same-session datum edit reuses all three exact body definitions.
+- Every guitar position/normal/index buffer and every occurrence transform matches
+ the preceding component witness exactly: 53 display definitions, 91 visible parts,
+ 130 occurrences including the root. The appearance and silhouette are preserved.
+- AP242 export and CLI reimport succeed: 53 geometry definitions, 91 bodies and
+ 129 non-root occurrences (38 subassembly occurrences). The posed knob USD has one
+ Revolute and two authored pose samples. The guitar USD preserves shared hierarchy.
+- Running the guitar generator changes no authored files. This authoring change
+ does not repeat camera-orbit or beauty-render qualification.
+
+Generated evidence lives under ignored `artifacts/local/coaxial-mating/`:
+`guitar-inspect.json`, `knob-inspect.json`, `gear-inspect.json`, `comparison.json`,
+`evidence-summary.json`, `guitar.step`, `guitar.usda`, `knob-posed.usda`,
+`display.json`, `knob-display.json`, `reimport/`, `generator-check.json`, and
+`test-summary.json`. Final validation logs are `build-verified.log`,
+`focused-verified.log`, `fast-verified.log` and `full-verified.log`.
+
+The first full run caught a recursive public-port rebase regression in synthesized
+Gear members. The correction preserves the typed Gear authority and only rebases
+matching ordinary published members. The final focused and full runs above cover
+that correction. The initial failure remains recorded in `full.log`.
diff --git a/docs/public/firmament/datum-seating.md b/docs/public/firmament/datum-seating.md
index 40e23c6c..94780307 100644
--- a/docs/public/firmament/datum-seating.md
+++ b/docs/public/firmament/datum-seating.md
@@ -1,5 +1,8 @@
# Concept-directed Fixed seating
+For spatial axes with station and clocking, including complete-component Revolute
+placement, see [Concept-directed coaxial mating](concept-axis-mating-proposal.md).
+
Author the layout first, declare which published seating ports conform to its
plane, then realize each member at a complete frame on that plane. The product
tree remains containment; datum geometry is semantic design authority, not a
diff --git a/fixtures/Canonical/AssemblyInterfaces/GuitarX0/hardware-definitions.firmament b/fixtures/Canonical/AssemblyInterfaces/GuitarX0/hardware-definitions.firmament
index 5d7c94ec..308621f0 100644
--- a/fixtures/Canonical/AssemblyInterfaces/GuitarX0/hardware-definitions.firmament
+++ b/fixtures/Canonical/AssemblyInterfaces/GuitarX0/hardware-definitions.firmament
@@ -5,7 +5,9 @@ Template<L: Length, W: Length, H: Length, R: Length> Struct Panel {
Extrude Body { Profile: P From: 0mm To: H }
}
Template<R: Length,H: Length> Struct Drum {
- Expose { Semantic BottomSeat { DatumFrame Frame = [0mm,0mm,0mm] x [1,0,0] y [0,1,0] z [0,0,1]; } }
+ Expose { Semantic BottomSeat { DatumFrame Frame = [0mm,0mm,0mm] x [1,0,0] y [0,1,0] z [0,0,1]; }
+ Semantic SpindleSeat { Axis Axis = [0mm,0mm,0mm] -> [0,0,1];
+ DatumFrame Frame = [0mm,0mm,0mm] x [1,0,0] y [0,1,0] z [0,0,1]; } }
Circle2 Outline { Center: [0mm,0mm] Radius: R }
Profile P { Loop Outer { Outline |> TraceLoop } }
Extrude Body { Profile: P From: 0mm To: H }
diff --git a/fixtures/Canonical/AssemblyInterfaces/GuitarX0/knob.firmament b/fixtures/Canonical/AssemblyInterfaces/GuitarX0/knob.firmament
index 558c7470..2c045357 100644
--- a/fixtures/Canonical/AssemblyInterfaces/GuitarX0/knob.firmament
+++ b/fixtures/Canonical/AssemblyInterfaces/GuitarX0/knob.firmament
@@ -1,16 +1,23 @@
-// A complete decorative control knob. All dimensions are local to its mounting seat.
+// A rigid knob stack seated by station on one Concept spindle.
+Concept Struct KnobLayout {
+ Axis Spindle { Origin: [0mm,0mm,0mm]; Direction: [0,0,1]; Reference: [1,0,0]; }
+}
Subassembly ControlKnob {
<Assembly ControlKnob>
- <Part KnobSkirt = Drum<R:12mm,H:3mm>>
- Placement { From: BottomSeat.Frame; To: World; }
- </Part>
- <Part AmberKnob = Drum<R:9mm,H:9mm>>
- Placement { From: BottomSeat.Frame; To: World; TranslateLocal: [0mm,0mm,3mm]; }
- </Part>
- <Part KnobCap = Drum<R:5mm,H:1mm>>
- Placement { From: BottomSeat.Frame; To: World; TranslateLocal: [0mm,0mm,12mm]; }
- </Part>
+ <Part KnobSkirt = Drum<R:12mm,H:3mm>></Part>
+ <Part AmberKnob = Drum<R:9mm,H:9mm>></Part>
+ <Part KnobCap = Drum<R:5mm,H:1mm>></Part>
</Assembly>
+ Interface<Fixed> CoaxialStack {
+ Datum: KnobLayout.Spindle;
+ Members: [ControlKnob.KnobSkirt.SpindleSeat,ControlKnob.AmberKnob.SpindleSeat,ControlKnob.KnobCap.SpindleSeat];
+ }
+ Mate SkirtOnSpindle: CoaxialStack { Member: ControlKnob.KnobSkirt.SpindleSeat; At: 0mm; Clocking: 0deg; }
+ Mate GripOnSpindle: CoaxialStack { Member: ControlKnob.AmberKnob.SpindleSeat; At: 3mm; Clocking: 0deg; }
+ Mate CapOnSpindle: CoaxialStack { Member: ControlKnob.KnobCap.SpindleSeat; At: 12mm; Clocking: 0deg; }
Anchor: ControlKnob;
- Expose { DatumFrame Mount = KnobSkirt.BottomSeat.Frame; }
+ Expose {
+ DatumFrame Mount = KnobSkirt.SpindleSeat.Frame;
+ Semantic Spindle = KnobSkirt.SpindleSeat;
+ }
}
diff --git a/fixtures/Canonical/AssemblyInterfaces/coaxial-knob.firmasm b/fixtures/Canonical/AssemblyInterfaces/coaxial-knob.firmasm
new file mode 100644
index 00000000..78ae3e65
--- /dev/null
+++ b/fixtures/Canonical/AssemblyInterfaces/coaxial-knob.firmasm
@@ -0,0 +1,12 @@
+Include "GuitarX0/hardware-definitions.firmament";
+Include "GuitarX0/knob.firmament";
+// One Concept spindle drives the complete rigid knob, along world X.
+Concept Struct ControlLayout {
+ Axis VolumeAxis { Origin: [3mm,4mm,5mm]; Direction: [2,0,0]; Reference: [0,3,1]; }
+}
+Assembly Controls {
+ <Assembly Controls><Assembly VolumeKnob = ControlKnob></Assembly></Assembly>
+ Anchor: Controls;
+ Interface<Revolute> VolumeControl { Datum: ControlLayout.VolumeAxis; Members: [Controls.VolumeKnob.Spindle]; }
+ Mate VolumeRotation: VolumeControl { Member: Controls.VolumeKnob.Spindle; At: 7mm; Clocking: 30deg; }
+}
diff --git a/scripts/create-guitar-x0.py b/scripts/create-guitar-x0.py
index 23918d7b..dd38e00f 100644
--- a/scripts/create-guitar-x0.py
+++ b/scripts/create-guitar-x0.py
@@ -152,7 +152,9 @@ Template<L: Length, W: Length, H: Length, R: Length> Struct Panel {
Extrude Body { Profile: P From: 0mm To: H }
}
Template<R: Length,H: Length> Struct Drum {
- Expose { Semantic BottomSeat { DatumFrame Frame = [0mm,0mm,0mm] x [1,0,0] y [0,1,0] z [0,0,1]; } }
+ Expose { Semantic BottomSeat { DatumFrame Frame = [0mm,0mm,0mm] x [1,0,0] y [0,1,0] z [0,0,1]; }
+ Semantic SpindleSeat { Axis Axis = [0mm,0mm,0mm] -> [0,0,1];
+ DatumFrame Frame = [0mm,0mm,0mm] x [1,0,0] y [0,1,0] z [0,0,1]; } }
Circle2 Outline { Center: [0mm,0mm] Radius: R }
Profile P { Loop Outer { Outline |> TraceLoop } }
Extrude Body { Profile: P From: 0mm To: H }