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.csnew file mode 100644index 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.csindex 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 AssemblyDatumAuthoringusedFrames[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 AssemblyDatumAuthoringreturn 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 AssemblyDatumAuthoringprivate 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.csindex 0a23793a..e29981f8 100644--- a/Aetheris.Kernel.Firmament/Assembly/AssemblyFrameAuthoring.cs+++ b/Aetheris.Kernel.Firmament/Assembly/AssemblyFrameAuthoring.cs@@ -147,9 +147,20 @@ internal static class AssemblyFrameAuthoringvar 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.csindex d3bee228..af08de2e 100644--- a/Aetheris.Kernel.Firmament/Assembly/AssemblyM0Compiler.cs+++ b/Aetheris.Kernel.Firmament/Assembly/AssemblyM0Compiler.cs@@ -81,6 +81,7 @@ public sealed class AssemblyM0Compilervar 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.csindex 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.csindex eb30f3b8..22ed2943 100644--- a/Aetheris.Kernel.Firmament/Assembly/AssemblyM0Parser.cs+++ b/Aetheris.Kernel.Firmament/Assembly/AssemblyM0Parser.cs@@ -122,7 +122,7 @@ public sealed class AssemblyM0Parservar 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 AssemblyM0Parservar 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 AssemblyM0Parservar 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 AssemblyM0Parserbindings.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.mdindex 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.mdindex 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 ownsits children, local dimensions and published mounting frame. Pattern componentoccurrences 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.mdnew file mode 100644index 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.mdindex 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 itsplane, then realize each member at a complete frame on that plane. The producttree remains containment; datum geometry is semantic design authority, not adiff --git a/fixtures/Canonical/AssemblyInterfaces/GuitarX0/hardware-definitions.firmament b/fixtures/Canonical/AssemblyInterfaces/GuitarX0/hardware-definitions.firmamentindex 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.firmamentindex 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.firmasmnew file mode 100644index 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.pyindex 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 }