Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

53.4 KB
Raw Blame
using Aetheris.Kernel.Core.Results;
using Aetheris.Kernel.Core.Diagnostics;
using System.Security.Cryptography;
using System.Diagnostics;
using System.Text;
using System.Text.Json;
using Aetheris.Kernel.Core.Brep;
using Aetheris.Kernel.Core.Brep.Verification;
using Aetheris.Kernel.Core.Brep.Queries;
using Aetheris.Kernel.Core.Geometry;
using Aetheris.Kernel.Core.Math;
using Aetheris.Kernel.Core.Step242;
using Aetheris.Kernel.Firmament.FirmamentV2;
using Aetheris.Surfacing;
using Aetheris.Semantics;

namespace Aetheris.Kernel.Firmament.Assembly;

public sealed record AssemblyExecutedGeometry(
    AssemblyGeometryArtifactIr Artifact,
    IReadOnlyDictionary<string, BrepBody> DefinitionBodies,
    IReadOnlyDictionary<string, BrepBody> InstanceBodies)
{
    public IReadOnlyDictionary<string, FirmamentCirRetention> DefinitionCir { get; init; } = new Dictionary<string, FirmamentCirRetention>();
    public IReadOnlyDictionary<string, IReadOnlyList<ConceptIrStructInstance>> DefinitionConcepts { get; init; } = new Dictionary<string, IReadOnlyList<ConceptIrStructInstance>>();
}

public sealed record AssemblyM1CompilationResult(
    AssemblyIr? Ir,
    AssemblyExecutedGeometry? Geometry,
    IReadOnlyList<AssemblyDiagnostic> Diagnostics,
    AssemblyPerformanceIr? Performance = null,
    AssemblyCompilationReuse? Reuse = null)
{
    /// <summary>Input key of each definition that came from (or entered) a session's definition
    /// cache. Values derived only from such a definition can be reused while its key is unchanged.</summary>
    public IReadOnlyDictionary<string, string>? DefinitionInputKeys { get; init; }
    public bool IsSuccess => Ir is not null && Geometry is not null && Diagnostics.All(diagnostic => diagnostic.Severity != AssemblyDiagnosticSeverity.Error);
}

/// <summary>
/// Exact part materialization supplied by a domain compiler to the ordinary
/// Assembly pipeline.  This is the cross-profile seam used by Sheet Metal: the
/// Assembly compiler continues to own hierarchy, mates, placement and product
/// export, while the owning part compiler remains authoritative for geometry.
/// </summary>
public sealed record AssemblyPartMaterialization(
    BrepBody Body,
    string SpecializationIdentity,
    IReadOnlyList<SemanticProvenance> Provenance,
    IReadOnlyList<SemanticValue>? Semantics = null);

public delegate AssemblyPartMaterialization? AssemblyPartMaterializer(
    string definitionIdentity,
    string? declarationSource,
    string sourceIdentity,
    IList<AssemblyDiagnostic> diagnostics);

internal sealed record MaterializedAssemblyDefinition(
    string DefinitionIdentity,
    string SpecializationIdentity,
    BrepBody Body,
    IReadOnlyList<SemanticValue> Semantics,
    AssemblyDefinitionArtifactIr Artifact,
    string? CanonicalStep = null,
    FirmamentCirRetention? Cir = null,
    string? InputKey = null,
    string? DeclarationScope = null)
{
    public IReadOnlyList<ConceptIrStructInstance> Concepts { get; init; } = [];
}

/// <summary>
/// M1's definition seam: specialize through the ordinary Firmament compiler, then
/// reimport its canonical AP242 exact body. Assembly has no second part generator.
/// </summary>
internal static partial class AssemblyDefinitionMaterializer
{
    public static MaterializedAssemblyDefinition? TryMaterialize(string definitionIdentity, string? definitionSource, string sourceIdentity, List<AssemblyDiagnostic> diagnostics, FirmamentProjectSnapshot? project = null,
        Func<string, KernelResult<BrepBody>>? importBody = null)
    {
        // BUILD-PERF-M2: a session supplies an importer that returns a clone of a body it already
        // imported from the identical canonical STEP text (the importer is deterministic).
        importBody ??= stepText => Step242Importer.ImportBody(stepText);
        if (!string.IsNullOrWhiteSpace(definitionSource))
        {
            // Keep the authored SectionChain in its own source document so sibling
            // assembly templates cannot leak unrelated profiles into its binder.
            var sectionFile = System.Text.RegularExpressions.Regex.Match(definitionIdentity,
                "^(?:SectionChainFile|LoftFile)<\\\"(?<path>[^\\\"]+)\\\">$", System.Text.RegularExpressions.RegexOptions.CultureInvariant);
            if (sectionFile.Success)
            {
                var requestedPath = sectionFile.Groups["path"].Value;
                string sectionPath;
                string sectionSource;
                if (project is not null)
                {
                    try
                    {
                        sectionPath = FirmamentProjectSnapshot.NormalizePath(requestedPath);
                    }
                    catch (ArgumentException)
                    {
                        diagnostics.Add(new("assembly-profile-invalid-resource-path", $"SectionChain source '{requestedPath}' escapes the project root or uses an invalid path."));
                        return null;
                    }
                    if (!sectionPath.EndsWith(".firmament", StringComparison.OrdinalIgnoreCase))
                    {
                        diagnostics.Add(new("assembly-profile-resource-kind-invalid", $"SectionChain source '{sectionPath}' must be a .firmament document."));
                        return null;
                    }
                    if (!project.TryResolve(sectionPath, out sectionSource!))
                    {
                        diagnostics.Add(new("assembly-profile-unresolved-resource", $"SectionChain source '{sectionPath}' was not found in the project snapshot."));
                        return null;
                    }
                }
                else
                {
                    var baseDirectory = Path.GetDirectoryName(Path.GetFullPath(sourceIdentity)) ?? Directory.GetCurrentDirectory();
                    sectionPath = Path.GetFullPath(Path.Combine(baseDirectory, requestedPath.Replace('/', Path.DirectorySeparatorChar)));
                    if (!File.Exists(sectionPath))
                    {
                        diagnostics.Add(new("assembly-profile-unresolved-resource", $"SectionChain source '{requestedPath}' was not found at '{sectionPath}'."));
                        return null;
                    }
                    sectionSource = File.ReadAllText(sectionPath);
                }
                var loaded = AssemblyM0Parser.LoadResource(sectionPath, project, [], diagnostics);
                if (loaded is null) return null;
                sectionSource = loaded;
                var section = SectionChainAuthoringParser.Compile(AssemblyPublishedPorts.Strip(sectionSource, diagnostics));
                if (!section.IsSuccess || section.Materialization?.Body is not { } sectionBody ||
                    section.Materialization.StructureKind != SectionChainStructureKind.ClosedSolid)
                {
                    foreach (var diagnostic in section.Diagnostics)
                        diagnostics.Add(new("assembly-definition-materialization-failed", $"SectionChain source '{sectionPath}': {diagnostic}"));
                    if (section.IsSuccess)
                        diagnostics.Add(new("assembly-definition-materialization-failed", $"SectionChain source '{sectionPath}' must materialize one capped closed solid."));
                    return null;
                }
                var sectionStep = Step242Exporter.ExportBody(sectionBody);
                if (!sectionStep.IsSuccess || sectionStep.Value is null)
                {
                    foreach (var diagnostic in sectionStep.Diagnostics)
                        diagnostics.Add(new("assembly-definition-materialization-failed", $"SectionChain source '{sectionPath}' STEP export failed: {diagnostic.Message}"));
                    return null;
                }
                var sectionImport = importBody(sectionStep.Value);
                if (!sectionImport.IsSuccess || sectionImport.Value is null)
                {
                    foreach (var diagnostic in sectionImport.Diagnostics)
                        diagnostics.Add(new("assembly-definition-reimport-failed", $"SectionChain source '{sectionPath}' STEP reimport failed: {diagnostic.Message}"));
                    return null;
                }
                var sectionHash = Convert.ToHexString(SHA256.HashData(Encoding.UTF8.GetBytes(sectionStep.Value)));
                var sectionStableId = "assembly-definition:" + Convert.ToHexString(SHA256.HashData(Encoding.UTF8.GetBytes(definitionIdentity)))[..16];
                var sectionProvenance = new[] { new SemanticProvenance("section-chain-source", sectionPath, section.Chain!.StableId, SemanticSourceSpan.Generated(sourceIdentity)) }
                    .Concat((section.ProfileDerivations ?? []).Select(d => new SemanticProvenance("concept-boundary-placement",
                        d.ConceptCurve, d.Profile + ":" + d.Transform, SemanticSourceSpan.Generated(sectionPath)))).ToArray();
                var ports = AssemblyPublishedPorts.Read(sectionSource,section.Chain.StableId,definitionIdentity,sectionPath,diagnostics,section.Chain);
                return new(definitionIdentity, "section-chain:" + sectionHash[..16], sectionImport.Value, ports,
                    new(sectionStableId, definitionIdentity, "section-chain:" + sectionHash[..16], sectionHash, Metrics(sectionImport.Value), sectionProvenance), sectionStep.Value);
            }
            var gearDocument = GearAuthoring.ParseDefinitions(definitionSource);
            var gear = gearDocument.Gears.SingleOrDefault(candidate => string.Equals(candidate.Name, definitionIdentity, StringComparison.Ordinal));
            if (gear is not null)
            {
                var materialization = GearAuthoring.Materialize(gear, out var gearDiagnostics);
                if (materialization is null)
                {
                    foreach (var diagnostic in gearDiagnostics)
                        diagnostics.Add(new("assembly-definition-materialization-failed", $"Gear definition '{definitionIdentity}' failed Gear-authoritative materialization: {diagnostic}"));
                    return null;
                }
                var step = Step242Exporter.ExportBody(materialization.Body);
                var gearHash = step.IsSuccess
                    ? Convert.ToHexString(SHA256.HashData(Encoding.UTF8.GetBytes(step.Value)))
                    : Convert.ToHexString(SHA256.HashData(Encoding.UTF8.GetBytes(definitionIdentity)));
                var gearStableId = "assembly-definition:" + Convert.ToHexString(SHA256.HashData(Encoding.UTF8.GetBytes(definitionIdentity)))[..16];
                var gearProvenance = new[] { new SemanticProvenance("gear-definition", definitionIdentity, "GearAuthoring.Materialize", SemanticSourceSpan.Generated(sourceIdentity)) };
                return new(definitionIdentity, "gear:" + definitionIdentity, materialization.Body, [],
                    new(gearStableId, definitionIdentity, "gear:" + definitionIdentity, gearHash, Metrics(materialization.Body), gearProvenance));
            }
            // An ordinary template specialization must not see sibling Gear roots:
            // the standalone build route would otherwise select the Gear profile and
            // successfully return that gear for every shaft, support and wheel.
            // Use producer-owned declaration spans; retain offsets for diagnostics.
            definitionSource = WithoutGears(definitionSource, gearDocument);
        }
        var externalStep = System.Text.RegularExpressions.Regex.Match(definitionIdentity, "^ExternalStep<\\\"(?<path>[^\\\"]+)\\\">$", System.Text.RegularExpressions.RegexOptions.CultureInvariant);
        if (externalStep.Success)
        {
            string resolvedPath; string stepText;
            if (project is not null)
            {
                resolvedPath = FirmamentProjectSnapshot.NormalizePath(Path.Combine(Path.GetDirectoryName(sourceIdentity) ?? "", externalStep.Groups["path"].Value));
                if (!project.TryResolve(resolvedPath, out stepText!))
                { diagnostics.Add(new("assembly-profile-unresolved-resource", "Missing snapshot STEP asset: " + resolvedPath)); return null; }
            }
            else
            {
                var baseDirectory = Path.GetDirectoryName(Path.GetFullPath(sourceIdentity)) ?? Directory.GetCurrentDirectory();
                resolvedPath = Path.GetFullPath(Path.Combine(baseDirectory, externalStep.Groups["path"].Value.Replace('/', Path.DirectorySeparatorChar)));
                if (!File.Exists(resolvedPath))
                { diagnostics.Add(new("assembly-profile-unresolved-resource", "Missing STEP asset: " + resolvedPath)); return null; }
                stepText = File.ReadAllText(resolvedPath);
            }
            var externalImport = Step242Importer.ImportBody(stepText);
            if (!externalImport.IsSuccess || externalImport.Value is null)
            {
                foreach (var diagnostic in externalImport.Diagnostics)
                    diagnostics.Add(new("assembly-definition-reimport-failed", $"External STEP definition '{definitionIdentity}' failed import: {diagnostic.Message}"));
                return null;
            }
            var externalHash = Convert.ToHexString(SHA256.HashData(Encoding.UTF8.GetBytes(stepText)));
            var externalStableId = "assembly-definition:" + Convert.ToHexString(SHA256.HashData(Encoding.UTF8.GetBytes(definitionIdentity)))[..16];
            var externalProvenance = new[] { new SemanticProvenance("imported-step-definition", resolvedPath, externalHash, SemanticSourceSpan.Generated(sourceIdentity)) };
            return new(definitionIdentity, "external-step:" + externalHash[..16], externalImport.Value, [],
                new(externalStableId, definitionIdentity, "external-step:" + externalHash[..16], externalHash, Metrics(externalImport.Value), externalProvenance), stepText);
        }
        if (string.IsNullOrWhiteSpace(definitionSource) || !definitionIdentity.Contains('<', StringComparison.Ordinal)) return null;
        // BUILD-PERF-M2: compile from the declarations this definition depends on. If that closure
        // does not compile on its own (the scope analysis is conservative, but not a full binder),
        // the definition compiles against the whole catalog exactly as before.
        if (ScopeDeclarations && AssemblyDeclarationScope.Closure(definitionSource, TemplateName(definitionIdentity)) is { } scoped
            && !ReferenceEquals(scoped, definitionSource))
        {
            var attempt = new List<AssemblyDiagnostic>();
            MaterializedAssemblyDefinition? scopedResult = null;
            try { scopedResult = MaterializeOrdinary(definitionIdentity, scoped, sourceIdentity, attempt, importBody); }
            catch (Exception exception) when (exception is not OutOfMemoryException) { scopedResult = null; }
            if (scopedResult is not null && attempt.All(diagnostic => diagnostic.Severity != AssemblyDiagnosticSeverity.Error))
            {
                diagnostics.AddRange(attempt);
                return scopedResult with { DeclarationScope = scoped };
            }
        }
        return MaterializeOrdinary(definitionIdentity, definitionSource, sourceIdentity, diagnostics, importBody);
    }

    /// <summary>Compiles scoped declarations instead of the whole catalog. Tests switch it off for
    /// one execution flow to compare both; it is flow-local so parallel tests are unaffected.</summary>
    internal static bool ScopeDeclarations { get => !WholeCatalog.Value; set => WholeCatalog.Value = !value; }
    private static readonly AsyncLocal<bool> WholeCatalog = new();

    internal static string TemplateName(string definitionIdentity) => definitionIdentity[..definitionIdentity.IndexOf('<')];

    /// <summary>The declarations an ordinary (non-Gear) definition compiles against: Gear roots are
    /// blanked (offsets kept), so a template specialization never selects a sibling Gear profile.</summary>
    internal static string OrdinaryDeclarations(string declarations)
    {
        if (!GearAuthoring.HasGearDefinitions(declarations)) return declarations;
        return WithoutGears(declarations, GearAuthoring.ParseDefinitions(declarations));
    }

    private static string WithoutGears(string declarations, GearAuthoringDocument gearDocument)
    {
        if (gearDocument.Gears.Count == 0) return declarations;
        var ordinaryDeclarations = declarations.ToCharArray();
        foreach (var sibling in gearDocument.Gears)
            for (var i = sibling.SourceSpan.Start; i < sibling.SourceSpan.Start + sibling.SourceSpan.Length; i++)
                if (ordinaryDeclarations[i] is not ('\r' or '\n')) ordinaryDeclarations[i] = ' ';
        return new string(ordinaryDeclarations);
    }

    private static MaterializedAssemblyDefinition? MaterializeOrdinary(string definitionIdentity, string definitionSource, string sourceIdentity,
        List<AssemblyDiagnostic> diagnostics, Func<string, KernelResult<BrepBody>> importBody)
    {        // Assembly files keep reusable declarations beside relational assembly syntax.
        // Wrap that declaration catalog in the ordinary V2 Model root for the exact
        // same compiler/build path used by standalone Firmament parts.
        var templateName = TemplateName(definitionIdentity);
        var inspectionDiagnostics = new List<string>();
        var targetKind = FirmamentV2TemplateExpansion.Inspect(definitionSource, inspectionDiagnostics)
            .SingleOrDefault(template => string.Equals(template.Name, templateName, StringComparison.Ordinal))?.TargetKind
            ?? "Struct";
        var application = $"{targetKind} __AssemblyPart = {definitionIdentity}" + Environment.NewLine;
        var module = targetKind == "Model"
            ? definitionSource + Environment.NewLine + application
            : "Model __AssemblyDefinition {" + Environment.NewLine
              + "Units: mm" + Environment.NewLine
              + definitionSource + Environment.NewLine
              + application
              + "}" + Environment.NewLine;
        IReadOnlyList<SemanticValue> publishedPorts = [];
        if (System.Text.RegularExpressions.Regex.IsMatch(module,@"\bExpose\s*\{\s*Semantic\s+[A-Za-z_]\w*\s*\{"))
        {
            var expansion = FirmamentTemplateSourceCompiler.Expand(module,out var expansionDiagnostics);
            if (expansion is null || expansionDiagnostics.Count > 0)
            {
                foreach (var error in expansionDiagnostics) diagnostics.Add(new("assembly-port-specialization-failed",error));
                return null;
            }
            publishedPorts = AssemblyPublishedPorts.Read(expansion.ExpandedSource,"__AssemblyPart",definitionIdentity,sourceIdentity,diagnostics);
            module = AssemblyPublishedPorts.Strip(module,diagnostics);
        }
        var build = FirmamentBuildAndExport.CompileSource(module, Path.GetDirectoryName(Path.GetFullPath(sourceIdentity)));
        if (!build.IsSuccess || build.Value is null)
        {
            foreach (var diagnostic in build.Diagnostics)
            {
                var presented = FirmamentBuildAdmissionValidation.Present(diagnostic, sourceIdentity, module);
                var message = diagnostic.Message == presented.Message || diagnostic.Message.Contains(": ", StringComparison.Ordinal)
                    ? diagnostic.Message : diagnostic.Message + ": " + presented.Message;
                diagnostics.Add(new("assembly-definition-materialization-failed", $"Definition '{definitionIdentity}' failed ordinary Firmament materialization: {message}")
                {
                    SourceSpan = presented.SourceSpan is { } span ? new(sourceIdentity + "#definition:" + definitionIdentity, span.Start, span.Length) : null,
                    LocationNote = "Offsets identify the specialized definition source; exact original-file expansion mapping is unavailable."
                });
            }
            return null;
        }
        var import = importBody(build.Value.StepText);
        if (!import.IsSuccess || import.Value is null)
        {
            foreach (var diagnostic in import.Diagnostics)
                diagnostics.Add(new("assembly-definition-reimport-failed", $"Definition '{definitionIdentity}' AP242 reimport failed: {diagnostic.Message}"));
            return null;
        }
        var specialization = build.Value.ConceptIr?.TemplateInstantiations?.LastOrDefault()?.SpecializationIdentity
            ?? "ordinary:" + definitionIdentity;
        var provenance = new List<SemanticProvenance>
        {
            new("Firmament-definition", definitionIdentity, "ordinary Firmament build and canonical AP242 reimport", SemanticSourceSpan.Generated(sourceIdentity)),
            new("template-specialization", specialization, definitionIdentity, SemanticSourceSpan.Generated(sourceIdentity))
        };
        if (build.Value.ConceptIr?.TemplateInstantiations?.LastOrDefault()?.RecordArguments is { Count: > 0 } records)
            provenance.AddRange(records.OrderBy(pair => pair.Key, StringComparer.Ordinal).Select(pair =>
                new SemanticProvenance("static-record", pair.Value.StaticValue, $"{pair.Key}:{pair.Value.RecordType};{pair.Value.Provenance}", SemanticSourceSpan.Generated(sourceIdentity))));
        var semantics = (build.Value.ConceptIr is null ? Array.Empty<SemanticValue>() : SemanticValues(build.Value.ConceptIr, provenance, sourceIdentity))
            .Concat(WindingSemantics(build.Value.WireForm, provenance, sourceIdentity)).Concat(publishedPorts).ToArray();
        var hash = Convert.ToHexString(SHA256.HashData(Encoding.UTF8.GetBytes(build.Value.StepText)));
        var stableId = "assembly-definition:" + Convert.ToHexString(SHA256.HashData(Encoding.UTF8.GetBytes(definitionIdentity)))[..16];
        var artifact = new AssemblyDefinitionArtifactIr(stableId, definitionIdentity, specialization, hash, Metrics(import.Value), provenance);
        return new(definitionIdentity, specialization, import.Value, semantics, artifact, build.Value.StepText, build.Value.Cir)
        { Concepts = build.Value.ConceptDisplayValues };
    }

    private static IEnumerable<SemanticValue> WindingSemantics(FirmamentWireFormReport? wire,
        IReadOnlyList<SemanticProvenance> provenance, string sourceIdentity)
    {
        return WindingSemantics((wire?.Operations ?? []).Where(o => o.AxisDatum is not null)
            .Select(o => (o.Name, o.StableId, o.AxisDatum!)), provenance, sourceIdentity);
    }

    internal static IEnumerable<SemanticValue> WindingSemantics(Materializer.WireFormFeatureAir wire,
        IReadOnlyList<SemanticProvenance> provenance, string sourceIdentity) => WindingSemantics(
            wire.Operations.OfType<Materializer.WireAxisCoilAir>().Select(o => (o.Name, o.StableId(wire.Name),
                Materializer.WireFormReportFactory.AxisDatum(o, wire.DiameterMm))), provenance, sourceIdentity);

    private static IEnumerable<SemanticValue> WindingSemantics(
        IEnumerable<(string Name, string StableId, FirmamentWireAxisDatum AxisDatum)> operations,
        IReadOnlyList<SemanticProvenance> provenance, string sourceIdentity)
    {
        foreach (var operation in operations)
        {
            var datum = operation.AxisDatum;
            var id = operation.StableId + ":winding-datum";
            var o = datum.Origin; var x = datum.Radial; var z = datum.Direction;
            var y = new Vector3D(z[0], z[1], z[2]).Cross(new(x[0], x[1], x[2]));
            var span = SemanticSourceSpan.Generated(sourceIdentity);
            SemanticValue[] members = [
                new(id + ":axis", new("Axis"), [new AxisCapability()],
                    [new ExactAxisBinding(o[0], o[1], o[2], z[0], z[1], z[2], id + ":axis")], exposedName: "Axis"),
                new(id + ":frame", new("DatumFrame"), [new DatumFrameCapability()],
                    [new ExactDatumFrameBinding(o[0], o[1], o[2], x[0], x[1], x[2], y.X, y.Y, y.Z, z[0], z[1], z[2], id + ":frame")], exposedName: "Frame"),
                new(id + ":clear-diameter", new("Length"), [new DimensionalCapability()],
                    [new TolerancedDimensionBinding(datum.ClearDiameterMm, 0, 0, "mm", id + ":clear-diameter")], exposedName: "ClearDiameter")
            ];
            yield return new(id, new("Semantic"), [new AxisCapability(), new DatumFrameCapability(), new DimensionalCapability()],
                exposedMembers: members, provenance: provenance, authoredSourceSpan: span, exposedName: operation.Name);
        }
    }

    private static IReadOnlyList<SemanticValue> SemanticValues(ConceptIrDocument ir, IReadOnlyList<SemanticProvenance> provenance, string sourceIdentity)
    {
        var members = ir.MaterializedStruct.ExposedMembers
            .Where(member => member.Value is ConceptIrAxisValue or ConceptIrPlaneValue or ConceptIrPoint3Value or ConceptIrLengthValue)
            .OrderBy(member => member.Name, StringComparer.Ordinal)
            .Select(member => FromMember(member, provenance, sourceIdentity)).ToArray();
        if (members.Length == 0) return [];
        return [new SemanticValue(
            "template-semantic:" + ir.MaterializedStruct.Name,
            new("Semantic"),
            members.SelectMany(member => member.Capabilities.Values).DistinctBy(capability => capability.GetType()),
            exposedMembers: members,
            provenance: provenance,
            authoredSourceSpan: SemanticSourceSpan.Generated(sourceIdentity),
            exposedName: "Interface")];
    }

    private static SemanticValue FromMember(ConceptIrSemanticMember member, IReadOnlyList<SemanticProvenance> provenance, string sourceIdentity)
    {
        var span = new SemanticSourceSpan(sourceIdentity, member.SourceSpan.Start, member.SourceSpan.Length);
        return member.Value switch
        {
            ConceptIrAxisValue axis => new(member.StableId, new("Axis"), [new AxisCapability()],
                [new ExactAxisBinding(axis.Origin.X, axis.Origin.Y, axis.Origin.Z, axis.Direction.X, axis.Direction.Y, axis.Direction.Z, member.StableId)],
                provenance: provenance, authoredSourceSpan: span, exposedName: member.Name),
            ConceptIrPlaneValue plane => new(member.StableId, new("Plane"), [new PlaneCapability()],
                [new ExactPlaneBinding(plane.Origin.X, plane.Origin.Y, plane.Origin.Z, plane.Normal.X, plane.Normal.Y, plane.Normal.Z, member.StableId)],
                provenance: provenance, authoredSourceSpan: span, exposedName: member.Name),
            ConceptIrPoint3Value point => new(member.StableId, new("Point"), [new PointCapability()],
                [new ExactPointBinding(point.Point.X, point.Point.Y, point.Point.Z, member.StableId)],
                provenance: provenance, authoredSourceSpan: span, exposedName: member.Name),
            ConceptIrLengthValue length => new(member.StableId, new("Length"), [new DimensionalCapability()],
                [new TolerancedDimensionBinding(length.Value, 0, 0, length.Unit, member.StableId)],
                provenance: provenance, authoredSourceSpan: span, exposedName: member.Name),
            _ => throw new InvalidOperationException($"Unsupported assembly semantic member '{member.Name}'.")
        };
    }

    internal static AssemblyGeometryMetricsIr Metrics(BrepBody body)
    {
        var points = body.Topology.Vertices.Select(vertex => body.TryGetVertexPoint(vertex.Id, out var point) ? point : (Point3D?)null).Where(point => point.HasValue).Select(point => point!.Value).ToArray();
        var minimum = points.Length == 0 ? [0d, 0d, 0d] : new[] { points.Min(point => point.X), points.Min(point => point.Y), points.Min(point => point.Z) };
        var maximum = points.Length == 0 ? [0d, 0d, 0d] : new[] { points.Max(point => point.X), points.Max(point => point.Y), points.Max(point => point.Z) };
        return new(body.Topology.Bodies.Count(), body.Topology.Faces.Count(), body.Topology.Edges.Count(), body.Topology.Vertices.Count(), minimum, maximum);
    }
}

public sealed class AssemblyM1Pipeline
{
    private readonly AssemblyDefinitionCache? cache;
    public AssemblyM1Pipeline() { }
    internal AssemblyM1Pipeline(AssemblyDefinitionCache cache) => this.cache = cache;
    public AssemblyM1CompilationResult CompileFile(string path, AssemblyPartMaterializer? domainMaterializer = null)
    {
        var parsed = new AssemblyM0Parser { PortCache = cache?.PublishedPorts }.ParseFile(path);
        return CompileParsed(parsed, domainMaterializer);
    }

    public AssemblyM1CompilationResult Compile(string source, string sourceIdentity = "<memory>", AssemblyPartMaterializer? domainMaterializer = null)
    {
        var parsed = new AssemblyM0Parser { PortCache = cache?.PublishedPorts }.Parse(source, sourceIdentity);
        return CompileParsed(parsed, domainMaterializer);
    }

    internal AssemblyM1CompilationResult CompileModule(Aetheris.Kernel.Firmament.Modules.FirmamentModuleGraph graph,
        Aetheris.Kernel.Firmament.Modules.FirmamentModuleGraph.Reference reference)
        => CompileParsed(graph.ParseAssembly(reference), null, graph.Project);

    public AssemblyM1CompilationResult CompileProject(FirmamentProjectSnapshot project)
    {
        ArgumentNullException.ThrowIfNull(project);
        var profile = project.TryResolve(project.RootDocument, out var root)
            ? FirmamentAssemblyDocumentCompiler.ValidateProfile(root, FirmamentDocumentProfile.Assembly, project.RootDocument, project)
            : [];
        if (profile.Any(diagnostic => diagnostic.Severity == AssemblyDiagnosticSeverity.Error))
            return new(null, null, profile);
        AssemblyM0Parser.ParseResult parsed;
        using (BuildPerfTrace.Phase("assembly.parse-project")) parsed = new AssemblyM0Parser { PortCache = cache?.PublishedPorts }.ParseProject(project);
        return CompileParsed(parsed, null, project);
    }

    private AssemblyM1CompilationResult CompileParsed(AssemblyM0Parser.ParseResult parsed, AssemblyPartMaterializer? domainMaterializer, FirmamentProjectSnapshot? project = null)
    {
        if (!parsed.IsSuccess || parsed.Source is null) return new(null, null, parsed.Diagnostics);
        var diagnostics = parsed.Diagnostics.ToList();
        var routeWatch = Stopwatch.StartNew();
        AssemblySource? routeSource; IReadOnlyList<AssemblyRouteBindingEvidence> routeBindings;
        using (BuildPerfTrace.Phase("assembly.route-bindings")) routeSource = AssemblyRouteBindings.Resolve(parsed.Source, diagnostics, out routeBindings);
        if (routeSource is null) return new(null, null, diagnostics);
        parsed = parsed with { Source = routeSource };
        routeWatch.Stop();
        var materializationWatch = Stopwatch.StartNew();
        var definitions = parsed.Source.Root.Flatten().Where(member => member.Kind == AssemblyInstanceKind.Part)
            .Select(member => member.DefinitionIdentity).Distinct(StringComparer.Ordinal).Order(StringComparer.Ordinal)
            .Select(identity => { using var definitionPhase = BuildPerfTrace.Phase("assembly.definition");
                if (parsed.Source.ModuleGraph?.TryReference(identity, out var imported) == true)
                    return AssemblyDefinitionMaterializer.MaterializeModule(parsed.Source.ModuleGraph, imported, identity, diagnostics, cache);
                return cache is null
                ? Materialize(identity, parsed.Source.DefinitionSource, parsed.Source.SourceIdentity, diagnostics, domainMaterializer, project)
                : cache.Materialize(identity, parsed.Source.DefinitionSource, parsed.Source.SourceIdentity, diagnostics, project,
                    () => Materialize(identity, parsed.Source.DefinitionSource, parsed.Source.SourceIdentity, diagnostics, domainMaterializer, project, cache.ImportCanonical)); })
            .Where(definition => definition is not null).Cast<MaterializedAssemblyDefinition>().ToDictionary(definition => definition.DefinitionIdentity, StringComparer.Ordinal);
        materializationWatch.Stop();
        var enriched = parsed.Source with { Root = Enrich(parsed.Source.Root, definitions) };
        AssemblyCompilationResult compiled;
        using (BuildPerfTrace.Phase("assembly.m0-compile")) compiled = new AssemblyM0Compiler().Compile(enriched, parsed.ElapsedMilliseconds);
        diagnostics.AddRange(compiled.Diagnostics);
        if (compiled.Ir is null) return new(null, null, diagnostics, compiled.Performance);
        var geometryWatch = Stopwatch.StartNew();
        AssemblyExecutedGeometry? geometry; AssemblyIr validatedIr;
        using (BuildPerfTrace.Phase("assembly.execute")) geometry = Execute(compiled.Ir, definitions, diagnostics, out validatedIr, cache);
        geometryWatch.Stop();
        var performance = compiled.Performance is null ? null : compiled.Performance with
        {
            DefinitionMaterializationMilliseconds = materializationWatch.Elapsed.TotalMilliseconds,
            GeometryExecutionMilliseconds = geometryWatch.Elapsed.TotalMilliseconds,
            RouteBindingMilliseconds = routeWatch.Elapsed.TotalMilliseconds
        };
        return new(validatedIr with { RouteBindings = routeBindings }, geometry, diagnostics, performance)
        {
            DefinitionInputKeys = definitions.Values.Where(definition => definition.InputKey is not null)
                .ToDictionary(definition => definition.DefinitionIdentity, definition => definition.InputKey!, StringComparer.Ordinal)
        };
    }

    private static MaterializedAssemblyDefinition? Materialize(string identity, string? declarations, string sourceIdentity,
        List<AssemblyDiagnostic> diagnostics, AssemblyPartMaterializer? domainMaterializer, FirmamentProjectSnapshot? project,
        Func<string, KernelResult<BrepBody>>? importBody = null)
    {
        if (domainMaterializer?.Invoke(identity, declarations, sourceIdentity, diagnostics) is { } supplied)
        {
            var step = Step242Exporter.ExportBody(supplied.Body);
            var hash = step.IsSuccess
                ? Convert.ToHexString(SHA256.HashData(Encoding.UTF8.GetBytes(step.Value)))
                : Convert.ToHexString(SHA256.HashData(Encoding.UTF8.GetBytes(identity + supplied.SpecializationIdentity)));
            var stableId = "assembly-definition:" + Convert.ToHexString(SHA256.HashData(Encoding.UTF8.GetBytes(identity)))[..16];
            var artifact = new AssemblyDefinitionArtifactIr(stableId, identity, supplied.SpecializationIdentity, hash,
                AssemblyDefinitionMaterializer.Metrics(supplied.Body), supplied.Provenance);
            return new(identity, supplied.SpecializationIdentity, supplied.Body, supplied.Semantics ?? [], artifact);
        }
        using var materializePhase = BuildPerfTrace.Phase("assembly.definition-materialize");
        return AssemblyDefinitionMaterializer.TryMaterialize(identity, declarations, sourceIdentity, diagnostics, project, importBody);
    }

    private static AssemblyMemberSource Enrich(AssemblyMemberSource member, IReadOnlyDictionary<string, MaterializedAssemblyDefinition> definitions)
    {
        var generated = definitions.TryGetValue(member.DefinitionIdentity, out var definition) ? definition.Semantics : [];
        var provenance = definitions.TryGetValue(member.DefinitionIdentity, out definition)
            ? [.. member.Provenance ?? [], .. definition.Artifact.Provenance]
            : member.Provenance;
        return member with
        {
            Children = member.Children.Select(child => Enrich(child, definitions)).ToArray(),
            ExposedSemantics = [.. member.ExposedSemantics.Where(value =>
                !(value.Provenance.Any(p => p.Stage == "definition-port-publication")
                  && generated.Any(g => g.ExposedName == value.ExposedName))), .. generated],
            Provenance = provenance
        };
    }

    private static AssemblyExecutedGeometry? Execute(AssemblyIr ir, IReadOnlyDictionary<string, MaterializedAssemblyDefinition> definitions, List<AssemblyDiagnostic> diagnostics, out AssemblyIr validatedIr,
        AssemblyDefinitionCache? cache = null)
    {
        var instances = new Dictionary<string, BrepBody>(StringComparer.Ordinal);
        // A world body is determined by its definition's input key and its exact transform.
        var worldKeys = new Dictionary<string, string>(StringComparer.Ordinal);
        var instanceArtifacts = new List<AssemblyInstanceGeometryIr>();
        foreach (var instance in ir.Instances.Where(item => item.Kind == AssemblyInstanceKind.Part).OrderBy(item => item.StableId, StringComparer.Ordinal))
        {
            if (!definitions.TryGetValue(instance.DefinitionIdentity, out var definition)) continue;
            if (instance.ResolvedTransform is null)
            {
                diagnostics.Add(new("assembly-geometry-unresolved-transform", $"Part instance '{instance.Path}' has geometry but no resolved transform."));
                continue;
            }
            var transform = Transform3D.FromRowMajor(instance.ResolvedTransform.Matrix);
            var body = FirmasmAssemblyExecutor.TransformBody(definition.Body, transform);
            instances[instance.StableId] = body;
            if (definition.InputKey is { } inputKey)
                worldKeys[instance.StableId] = inputKey + "|" + string.Join(',', instance.ResolvedTransform.Matrix.Select(value => BitConverter.DoubleToInt64Bits(value).ToString(System.Globalization.CultureInfo.InvariantCulture)));
            instanceArtifacts.Add(new(instance.StableId, definition.Artifact.StableId, instance.ResolvedTransform, AssemblyDefinitionMaterializer.Metrics(body)));
        }
        if (definitions.Count == 0 || instanceArtifacts.Count == 0)
        {
            validatedIr = ir;
            diagnostics.Add(new("assembly-geometry-no-materialized-definitions", "No Template-specialized part definitions were available for executable Assembly geometry."));
            return null;
        }
        IReadOnlyList<AssemblyMateResidualIr> residuals;
        using (BuildPerfTrace.Phase("assembly.validate-residuals")) residuals = AssemblyWorldQuery.ValidateResiduals(ir, instances.Keys.ToHashSet(StringComparer.Ordinal));
        var byConstraint = residuals.ToDictionary(residual => residual.ConstraintStableId, StringComparer.Ordinal);
        var constraints = ir.PlacementConstraints.Select(constraint => byConstraint.TryGetValue(constraint.StableId, out var residual)
            ? constraint with { Residual = Math.Max(residual.PositionResidualMm, residual.AngularResidualRadians), Status = residual.Passed ? "geometry-validated" : "geometry-residual-failed" }
            : constraint).ToArray();
        foreach (var residual in residuals.Where(item => !item.Passed))
            diagnostics.Add(new("assembly-mate-geometry-residual", $"Constraint '{residual.ConstraintStableId}' residual position={residual.PositionResidualMm:G6}mm angle={residual.AngularResidualRadians:G6}rad."));
        using (BuildPerfTrace.Phase("assembly.validate-interference")) ValidateSolidInterference(ir, instances, diagnostics);
        IReadOnlyList<AssemblyDatumSeatEvidence> datumSeats;
        using (BuildPerfTrace.Phase("assembly.validate-datum-seats")) datumSeats = ValidateDatumSeats(ir, instances, diagnostics, worldKeys, cache);
        validatedIr = ir with { Schema = "aetheris/assembly-ir/m1", PlacementConstraints = constraints, Diagnostics = diagnostics };
        var definitionsIr = definitions.Values.Select(definition => definition.Artifact).OrderBy(definition => definition.StableId, StringComparer.Ordinal).ToArray();
        var canonical = JsonSerializer.Serialize(new { definitions = definitionsIr, instances = instanceArtifacts, residuals });
        var hash = Convert.ToHexString(SHA256.HashData(Encoding.UTF8.GetBytes(canonical)));
        var artifact = new AssemblyGeometryArtifactIr("aetheris/assembly-geometry/m1", definitionsIr, instanceArtifacts, residuals, hash, datumSeats);
        return new(artifact, definitions.ToDictionary(pair => pair.Key, pair => pair.Value.Body, StringComparer.Ordinal), instances)
        {
            DefinitionConcepts = definitions.Where(p => p.Value.Concepts.Count > 0).ToDictionary(p => p.Key, p => p.Value.Concepts, StringComparer.Ordinal),
            DefinitionCir = definitions.Where(p => p.Value.Cir is not null)
                .ToDictionary(p => p.Key, p => p.Value.Cir! with { DefinitionId = p.Value.Artifact.StableId }, StringComparer.Ordinal)
        };
    }

    private static void ValidateSolidInterference(AssemblyIr ir, IReadOnlyDictionary<string, BrepBody> instances, List<AssemblyDiagnostic> diagnostics)
    {
        var ordered = instances.OrderBy(pair => pair.Key, StringComparer.Ordinal).ToArray();
        var paths = ir.Instances.ToDictionary(instance => instance.StableId, instance => instance.Path.ToString(), StringComparer.Ordinal);
        for (var left = 0; left < ordered.Length - 1; left++)
        for (var right = left + 1; right < ordered.Length; right++)
        {
            var result = BrepSolidInterference.Analyze(ordered[left].Value, ordered[right].Value);
            if (result.Status != BrepSolidInterferenceStatus.Interfering) continue;
            diagnostics.Add(new(
                "assembly-solid-volume-interference",
                $"Part occurrences '{paths[ordered[left].Key]}' and '{paths[ordered[right].Key]}' occupy overlapping solid volume. "
                + $"The assembly is physically invalid and cannot be materialized (proof={result.Evidence}; penetration witness={result.PenetrationWitnessMm:G6}mm; "
                + $"contained tetrahedron={result.WitnessTetrahedronVolumeMm3:G6}mm^3). Face/edge contact is allowed, but positive-volume overlap is not."));
        }
    }

    private static IReadOnlyList<AssemblyDatumSeatEvidence> ValidateDatumSeats(AssemblyIr ir,
        IReadOnlyDictionary<string, BrepBody> bodies, List<AssemblyDiagnostic> diagnostics,
        IReadOnlyDictionary<string, string>? worldKeys = null, AssemblyDefinitionCache? cache = null)
    {
        var evidence = new List<AssemblyDatumSeatEvidence>();
        // A seat query tessellates its body lazily; an identical world body (same definition input
        // key, same transform) reuses the query from an earlier build in this session.
        var queries = bodies.ToDictionary(p => p.Key, p => cache is not null && worldKeys?.GetValueOrDefault(p.Key) is { } worldKey
            ? cache.SeatQueries.GetOrAdd(worldKey, () => new BrepPlanarSeatQuery(p.Value))
            : new BrepPlanarSeatQuery(p.Value), StringComparer.Ordinal);
        var points = new List<(AssemblyInstanceIr Instance, Point3D Point, Vector3D Normal)>();
        foreach (var instance in ir.Instances.Where(i => i.DatumSeat is not null))
        {
            var seat = instance.DatumSeat!;
            var value = instance.SemanticRoot;
            foreach (var segment in seat.Port.Split('.'))
            {
                if (!value.ExposedMembers.TryGetValue(segment, out var next)) { value = null!; break; }
                value = next;
            }
            if (value is null || !value.TryBinding<ExactDatumFrameBinding>(out var frame) ||
                instance.ResolvedTransform is null || !bodies.TryGetValue(instance.StableId, out var body))
            { diagnostics.Add(new("assembly-datum-port-invalid", $"'{instance.Path}' requires a published seating Frame and material body.")); continue; }
            var world = Transform3D.FromRowMajor(instance.ResolvedTransform.Matrix);
            var point = world.Apply(new Point3D(frame.OriginX, frame.OriginY, frame.OriginZ));
            var parent = ir.Instances.Single(i => i.StableId == instance.ParentStableId);
            var parentWorld = Transform3D.FromRowMajor(parent.ResolvedTransform!.Matrix);
            var origin = parentWorld.Apply(new Point3D(seat.Origin[0], seat.Origin[1], seat.Origin[2]));
            var normal = parentWorld.Apply(new Vector3D(seat.Normal[0], seat.Normal[1], seat.Normal[2]));
            normal.TryNormalize(out normal);
            var residual = Math.Abs((point - origin).Dot(normal));
            var faces = queries[instance.StableId].FindFaces(point, normal);
            var passed = residual <= 1e-7 && faces.Count > 0;
            evidence.Add(new(instance.StableId, seat.Interface, seat.Datum, residual,
                faces.Select(f => f.ToString()).ToArray(), seat.Support, passed));
            if (!passed) diagnostics.Add(new("assembly-datum-material-seat-missing", $"'{instance.Path}' has no admitted planar material face at its seating point on '{seat.Datum}' (residual={residual:G6}mm)."));
            points.Add((instance, point, normal));
        }
        foreach (var support in points.Where(p => p.Instance.DatumSeat!.Support))
        foreach (var seated in points.Where(p => !p.Instance.DatumSeat!.Support && p.Instance.DatumSeat.Datum == support.Instance.DatumSeat!.Datum))
        {
            if (queries[support.Instance.StableId].FindFaces(seated.Point, seated.Normal).Count > 0) continue;
            diagnostics.Add(new("assembly-datum-support-contact-missing", $"'{seated.Instance.Path}' seating point does not contact the planar support of '{support.Instance.Path}'."));
            var index = evidence.FindIndex(e => e.InstanceStableId == seated.Instance.StableId);
            if (index >= 0) evidence[index] = evidence[index] with { Passed = false };
        }
        return evidence;
    }
}

public static class AssemblyWorldQuery
{
    public static SemanticBinding Resolve(AssemblyIr ir, string semanticValueId)
        => Resolve(ir, semanticValueId, new HashSet<string>(StringComparer.Ordinal));

    private static SemanticBinding Resolve(AssemblyIr ir, string semanticValueId, HashSet<string> visited)
    {
        if (!visited.Add(semanticValueId)) throw new InvalidOperationException($"Cyclic exposed semantic '{semanticValueId}'.");
        var instance = ir.Instances.FirstOrDefault(candidate => Flatten(candidate.SemanticRoot).Any(value => value.StableIdentity == semanticValueId))
            ?? throw new KeyNotFoundException($"Semantic value '{semanticValueId}' has no owning assembly instance.");
        if (instance.ResolvedTransform is null) throw new InvalidOperationException($"Instance '{instance.Path}' has no resolved world transform.");
        var value = Flatten(instance.SemanticRoot).Single(candidate => candidate.StableIdentity == semanticValueId);
        if (value.TryBinding<AssemblyExposedSemanticBinding>(out var alias))
        {
            var target = ExposedTarget(ir.Instances, instance, alias);
            return Resolve(ir, target.Value.StableIdentity, visited);
        }
        var transform = Transform3D.FromRowMajor(instance.ResolvedTransform.Matrix);
        if (value.TryBinding<ExactAxisBinding>(out var axis))
        {
            var origin = transform.Apply(new Point3D(axis.OriginX, axis.OriginY, axis.OriginZ));
            var direction = transform.Apply(new Vector3D(axis.DirectionX, axis.DirectionY, axis.DirectionZ));
            return new ExactAxisBinding(origin.X, origin.Y, origin.Z, direction.X, direction.Y, direction.Z, axis.AxisStableId + ":world:" + instance.StableId);
        }
        if (value.TryBinding<ExactPlaneBinding>(out var plane))
        {
            var origin = transform.Apply(new Point3D(plane.OriginX, plane.OriginY, plane.OriginZ));
            var normal = transform.Apply(new Vector3D(plane.NormalX, plane.NormalY, plane.NormalZ));
            return new ExactPlaneBinding(origin.X, origin.Y, origin.Z, normal.X, normal.Y, normal.Z, plane.PlaneStableId + ":world:" + instance.StableId);
        }
        if (value.TryBinding<ExactDatumFrameBinding>(out var frame))
        {
            var origin = transform.Apply(new Point3D(frame.OriginX, frame.OriginY, frame.OriginZ));
            var x = transform.Apply(new Vector3D(frame.XAxisX, frame.XAxisY, frame.XAxisZ));
            var y = transform.Apply(new Vector3D(frame.YAxisX, frame.YAxisY, frame.YAxisZ));
            var z = transform.Apply(new Vector3D(frame.ZAxisX, frame.ZAxisY, frame.ZAxisZ));
            return new ExactDatumFrameBinding(origin.X, origin.Y, origin.Z, x.X, x.Y, x.Z, y.X, y.Y, y.Z, z.X, z.Y, z.Z,
                frame.FrameStableId + ":world:" + instance.StableId);
        }
        if (value.TryBinding<ExactPointBinding>(out var point))
        {
            var world = transform.Apply(new Point3D(point.X, point.Y, point.Z));
            return new ExactPointBinding(world.X, world.Y, world.Z, point.PointStableId + ":world:" + instance.StableId);
        }
        if (value.TryBinding<ExactBrepBodyBinding>(out var body))
            return new ExactBrepBodyBinding(FirmasmAssemblyExecutor.TransformBody(body.Body, transform), body.BodyStableId + ":world:" + instance.StableId);
        throw new InvalidOperationException($"Semantic value '{semanticValueId}' has no world-queryable exact binding.");
    }

    internal static (AssemblyInstanceIr Owner, SemanticValue Value) ExposedTarget(IReadOnlyList<AssemblyInstanceIr> instances,
        AssemblyInstanceIr owner, AssemblyExposedSemanticBinding alias)
    {
        var path = new AssemblyPath([.. owner.Path.Segments, .. alias.RelativeOccurrencePath]).ToString();
        var instance = instances.Single(i => i.Path.ToString() == path);
        var value = instance.SemanticRoot;
        if (alias.SemanticPath.Length > 0)
            foreach (var member in alias.SemanticPath.Split('.')) value = value.ExposedMembers[member];
        return (instance, value);
    }

    public static IReadOnlyList<AssemblyMateResidualIr> ValidateResiduals(AssemblyIr ir, IReadOnlySet<string> materializedInstanceIds, double positionToleranceMm = 1e-8, double angularToleranceRadians = 1e-8)
    {
        var result = new List<AssemblyMateResidualIr>();
        foreach (var constraint in ir.PlacementConstraints.OrderBy(item => item.StableId, StringComparer.Ordinal))
        {
            var owners = ir.Instances.Where(instance => Flatten(instance.SemanticRoot).Any(value => value.StableIdentity == constraint.FirstSemanticValueId || value.StableIdentity == constraint.SecondSemanticValueId)).ToArray();
            if (owners.Length != 2 || owners.Any(owner => !materializedInstanceIds.Contains(owner.StableId))) continue;
            var first = Resolve(ir, constraint.FirstSemanticValueId);
            var second = Resolve(ir, constraint.SecondSemanticValueId);
            if (constraint.Seating is { } seating && first is ExactDatumFrameBinding seatFrame)
            {
                var m=AssemblyM0Compiler.SeatMatrix(seatFrame,seating).ToRowMajor();
                first=new ExactDatumFrameBinding(m[12],m[13],m[14],m[0],m[1],m[2],m[4],m[5],m[6],m[8],m[9],m[10],seatFrame.FrameStableId+":seat");
            }
            var (position, angle) = Residual(constraint.Kind, first, second, constraint.OffsetMm, constraint.Seating is null ? constraint.Orientation : DatumOrientationRelation.SameDirection);
            result.Add(new(constraint.StableId, constraint.Kind, position, angle, position <= positionToleranceMm && angle <= angularToleranceRadians, "world exact semantic binding over materialized BRep instance"));
        }
        return result;
    }

    private static (double Position, double Angle) Residual(PlacementConstraintKind kind, SemanticBinding first, SemanticBinding second, double offset, DatumOrientationRelation orientation)
    {
        if (first is ExactAxisBinding a && second is ExactAxisBinding b)
        {
            var ad = Unit(new(a.DirectionX, a.DirectionY, a.DirectionZ)); var bd = Unit(new(b.DirectionX, b.DirectionY, b.DirectionZ));
            var delta = new Vector3D(a.OriginX - b.OriginX, a.OriginY - b.OriginY, a.OriginZ - b.OriginZ);
            var cross = Cross(delta, bd);
            return (cross.Length, UndirectedAngle(ad, bd));
        }
        if (first is ExactPlaneBinding p && second is ExactPlaneBinding q)
        {
            var pn = Unit(new(p.NormalX, p.NormalY, p.NormalZ)); var qn = Unit(new(q.NormalX, q.NormalY, q.NormalZ));
            var delta = new Vector3D(p.OriginX - q.OriginX, p.OriginY - q.OriginY, p.OriginZ - q.OriginZ);
            return (Math.Abs(delta.Dot(qn) - offset), UndirectedAngle(pn, qn));
        }
        if (first is ExactPointBinding x && second is ExactPointBinding y)
        {
            var delta = new Vector3D(x.X - y.X, x.Y - y.Y, x.Z - y.Z);
            return (Math.Abs(delta.Length - offset), 0);
        }
        if (first is ExactDatumFrameBinding f && second is ExactDatumFrameBinding g)
        {
            var delta = new Vector3D(f.OriginX - g.OriginX, f.OriginY - g.OriginY, f.OriginZ - g.OriginZ);
            var fx = Unit(new(f.XAxisX, f.XAxisY, f.XAxisZ)); var gx = Unit(new(g.XAxisX, g.XAxisY, g.XAxisZ));
            var fz = Unit(new(f.ZAxisX, f.ZAxisY, f.ZAxisZ)); var gz = Unit(new(g.ZAxisX, g.ZAxisY, g.ZAxisZ));
            var expectedZDot = orientation == DatumOrientationRelation.OpposedDirection ? -1d : 1d;
            return (delta.Length, Math.Max(DirectedAngle(fx, gx), DirectedAngle(fz, gz * expectedZDot)));
        }
        return (double.PositiveInfinity, double.PositiveInfinity);
    }

    // atan2 retains precision near aligned axes; acos(dot) turns rounding at 1 into
    // a spurious ~1e-8 rad residual even for identical oblique datum frames.
    private static double DirectedAngle(Vector3D a, Vector3D b) => double.Atan2(Cross(a, b).Length, a.Dot(b));
    private static double UndirectedAngle(Vector3D a, Vector3D b) => double.Atan2(Cross(a, b).Length, double.Abs(a.Dot(b)));
    private static Vector3D Unit(Vector3D value) => value / value.Length;
    private static Vector3D Cross(Vector3D a, Vector3D b) => new(a.Y * b.Z - a.Z * b.Y, a.Z * b.X - a.X * b.Z, a.X * b.Y - a.Y * b.X);
    private static IEnumerable<SemanticValue> Flatten(SemanticValue root)
    {
        yield return root;
        foreach (var child in root.ExposedMembers.Values.SelectMany(Flatten)) yield return child;
    }
}

internal static class AssemblyMemberSourceExtensions
{
    public static IEnumerable<AssemblyMemberSource> Flatten(this AssemblyMemberSource root)
    {
        yield return root;
        foreach (var child in root.Children.SelectMany(Flatten)) yield return child;
    }
}