Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel
Preserve Firmament V2 PMI through AP242 export
Yuechen Li97e10ddc2bb5
diff --git a/Aetheris.CLI.Tests/FirmamentFixtureCorpusTests.cs b/Aetheris.CLI.Tests/FirmamentFixtureCorpusTests.csindex 0ede6719..4c6d29c5 100644--- a/Aetheris.CLI.Tests/FirmamentFixtureCorpusTests.cs+++ b/Aetheris.CLI.Tests/FirmamentFixtureCorpusTests.cs@@ -161,7 +161,9 @@ public sealed class FirmamentFixtureCorpusTests}var diagnostics = validation.GetProperty("diagnostics").EnumerateArray().Select(x => x.GetProperty("code").GetString()).ToArray();if (metadata.TryGetValue("expected-diagnostic", out var expectedValidationDiagnostic)) Assert.Contains(expectedValidationDiagnostic, diagnostics);- Assert.Contains("firmament-v2-parser-invoked", diagnostics);+ // The public report itself proves V2 routing. Successful parser trace events+ // are intentionally filtered from user-facing diagnostics.+ Assert.All(diagnostics, code => Assert.StartsWith("firmament-v2-", code, StringComparison.Ordinal));Assert.DoesNotContain("air-x11-firmament-parse-failed", diagnostics);continue;}diff --git a/Aetheris.CLI.Tests/FirmamentV2ConceptPoint3HoleStepPipelineTests.cs b/Aetheris.CLI.Tests/FirmamentV2ConceptPoint3HoleStepPipelineTests.csindex 60d0d3a8..a0e44a7d 100644--- a/Aetheris.CLI.Tests/FirmamentV2ConceptPoint3HoleStepPipelineTests.cs+++ b/Aetheris.CLI.Tests/FirmamentV2ConceptPoint3HoleStepPipelineTests.cs@@ -98,6 +98,33 @@ public sealed class FirmamentV2ConceptPoint3HoleStepPipelineTestsAssert.Equal(2, imported.Value!.Geometry.Surfaces.Count(s => s.Value.Kind == SurfaceGeometryKind.Cylinder));}+ [Fact]+ public void BuildJson_ReportsEverySupportedPmiRecordPreservedByCombinedRoute()+ {+ var dir = Path.Combine(Path.GetTempPath(), "aetheris-preview3-pmi-parity", Guid.NewGuid().ToString("N"));+ Directory.CreateDirectory(dir);+ try+ {+ var source = Path.GetFullPath(Path.Combine(AppContext.BaseDirectory, "../../../../fixtures/FirmamentV2/Canonical/valid/box-holes-pmi-chamfer.firmament"));+ var step = Path.Combine(dir, "mounting-plate.step");+ var output = new StringWriter();++ var exit = CliRunner.Run(["build", source, "--out", step, "--json"], output, new StringWriter());++ Assert.Equal(0, exit);+ using var report = JsonDocument.Parse(output.ToString());+ Assert.Empty(report.RootElement.GetProperty("diagnostics").EnumerateArray());+ Assert.Single(report.RootElement.GetProperty("pmiExportEvidence").GetProperty("datum").EnumerateArray());+ Assert.Equal(2, report.RootElement.GetProperty("pmiExportEvidence").GetProperty("diameter").GetArrayLength());+ var pmi = Step242SemanticPmiInspector.Inspect(File.ReadAllText(step));+ Assert.Equal((1, 2), (pmi.DatumCount, pmi.DimensionCount));+ }+ finally+ {+ Directory.Delete(dir, true);+ }+ }+[Fact]public void ConceptHolesThatSplitTheRequestedChamferChain_AreRejectedByCombinedRoute(){diff --git a/Aetheris.CLI.Tests/PublicDocumentationQualificationTests.cs b/Aetheris.CLI.Tests/PublicDocumentationQualificationTests.csnew file mode 100644index 00000000..f5a09752--- /dev/null+++ b/Aetheris.CLI.Tests/PublicDocumentationQualificationTests.cs@@ -0,0 +1,88 @@+using System.Text.Json;+using System.Text.RegularExpressions;++namespace Aetheris.CLI.Tests;++public sealed class PublicDocumentationQualificationTests+{+ private static readonly string RepoRoot = FindRoot();++ [Fact]+ public void PublicMarkdownRelativeLinksResolveInsideRepository()+ {+ var markdown = Directory.GetFiles(Path.Combine(RepoRoot, "docs", "public"), "*.md", SearchOption.AllDirectories)+ .Append(Path.Combine(RepoRoot, "README.md"));+ foreach (var file in markdown)+ {+ var links = Regex.Matches(File.ReadAllText(file), @"\]\((?<target>[^)]+)\)")+ .Select(match => match.Groups["target"].Value)+ .Where(target => !target.StartsWith("http", StringComparison.OrdinalIgnoreCase) && !target.StartsWith('#'));+ foreach (var target in links)+ {+ var path = target.Split('#', 2)[0].Replace('/', Path.DirectorySeparatorChar);+ var resolved = Path.GetFullPath(Path.Combine(Path.GetDirectoryName(file)!, path));+ Assert.True(File.Exists(resolved) || Directory.Exists(resolved), $"Broken public-doc link '{target}' in {Path.GetRelativePath(RepoRoot, file)}.");+ Assert.StartsWith(RepoRoot, resolved, StringComparison.OrdinalIgnoreCase);+ }+ }+ }++ [Theory]+ [InlineData("fixtures/FirmamentV2/Canonical/valid/box-hole-pmi.firmament", 1, 1)]+ [InlineData("fixtures/FirmamentV2/Canonical/valid/record-array-pattern-holes.firmament", 0, 0)]+ [InlineData("fixtures/FirmamentV2/Canonical/valid/box-holes-pmi-chamfer.firmament", 1, 2)]+ [InlineData("fixtures/FirmamentV2/PublicDogfood/ai-model.firmament", 0, 0)]+ public void PublicModelAndTemplateExamplesBuildThroughRealCli(string relativeSource, int datums, int diameters)+ {+ using var temp = TempDirectory.Create();+ var output = new StringWriter(); var error = new StringWriter();+ var step = Path.Combine(temp.Path, "part.step");+ var exit = CliRunner.Run(["build", Path.Combine(RepoRoot, relativeSource), "--output", step, "--json"], output, error);+ Assert.Equal(0, exit); Assert.Empty(error.ToString()); Assert.True(File.Exists(step));+ using var report = JsonDocument.Parse(output.ToString());+ Assert.True(report.RootElement.GetProperty("success").GetBoolean());+ Assert.Equal(datums, report.RootElement.GetProperty("pmiExportEvidence").GetProperty("datum").GetArrayLength());+ Assert.Equal(diameters, report.RootElement.GetProperty("pmiExportEvidence").GetProperty("diameter").GetArrayLength());+ }++ [Theory]+ [InlineData("fixtures/FirmamentV2/SheetMetal/preview3-l-bracket-hole.firmament")]+ [InlineData("fixtures/FirmamentV2/PublicDogfood/ai-sheet-metal.firmament")]+ public void PublicSheetMetalExampleBuildsAndFlattensWithOneFeature(string relativeSource)+ {+ using var temp = TempDirectory.Create();+ var source = Path.Combine(RepoRoot, relativeSource);+ var output = new StringWriter(); var error = new StringWriter();+ Assert.Equal(0, CliRunner.Run(["build", source, "--output", Path.Combine(temp.Path, "formed.step"), "--json"], output, error));+ using (var report = JsonDocument.Parse(output.ToString()))+ Assert.Equal(1, report.RootElement.GetProperty("part").GetProperty("features").GetInt32());+ output.GetStringBuilder().Clear();+ Assert.Equal(0, CliRunner.Run(["sheetmetal", "flatten", source, "--step", Path.Combine(temp.Path, "flat.step"), "--svg", Path.Combine(temp.Path, "flat.svg"), "--json"], output, error));+ Assert.True(File.Exists(Path.Combine(temp.Path, "flat.step"))); Assert.True(File.Exists(Path.Combine(temp.Path, "flat.svg")));+ }++ [Theory]+ [InlineData("fixtures/FirmamentV2/Materials/catalog-material-coupon.firmament", "FirmamentNative")]+ [InlineData("fixtures/FirmamentV2/FEA/cantilever.firmament", "FirmamentNative")]+ [InlineData("fixtures/FirmamentV2/FEA/inline-step-through-hole.firmament", "InlineStep")]+ [InlineData("fixtures/FirmamentV2/PublicDogfood/ai-fea-a36-cantilever.firmament", "FirmamentNative")]+ public void PublicMaterialAndFeaExamplesSolveThroughRealCli(string relativeSource, string sourceKind)+ {+ using var temp = TempDirectory.Create();+ var output = new StringWriter(); var error = new StringWriter();+ var exit = CliRunner.Run(["fea", Path.Combine(RepoRoot, relativeSource), "--out-dir", temp.Path, "--json"], output, error);+ Assert.Equal(0, exit); Assert.Empty(error.ToString());+ using var report = JsonDocument.Parse(output.ToString());+ Assert.Equal(sourceKind, report.RootElement.GetProperty("analysis").GetProperty("sourceKind").GetString());+ Assert.True(report.RootElement.GetProperty("solver").GetProperty("converged").GetBoolean());+ }++ private static string FindRoot() { var directory = new DirectoryInfo(AppContext.BaseDirectory); while (directory is not null && !File.Exists(Path.Combine(directory.FullName, "Aetheris.slnx"))) directory = directory.Parent; return directory?.FullName ?? throw new DirectoryNotFoundException(); }+ private sealed class TempDirectory : IDisposable+ {+ private TempDirectory(string path) { Path = path; Directory.CreateDirectory(path); }+ public string Path { get; }+ public static TempDirectory Create() => new(System.IO.Path.Combine(System.IO.Path.GetTempPath(), "aetheris-public-docs-" + Guid.NewGuid().ToString("N")));+ public void Dispose() { if (Directory.Exists(Path)) Directory.Delete(Path, true); }+ }+}diff --git a/Aetheris.CLI.Tests/SheetMetalCliTests.cs b/Aetheris.CLI.Tests/SheetMetalCliTests.csindex a504a061..39dd3057 100644--- a/Aetheris.CLI.Tests/SheetMetalCliTests.cs+++ b/Aetheris.CLI.Tests/SheetMetalCliTests.cs@@ -43,6 +43,60 @@ public sealed class SheetMetalCliTestsfinally{if(File.Exists(temp))File.Delete(temp);}}+ [Fact]+ public void BuildAuthoredSheetMetal_ReportsCanonicalHoleAsGeneratedFeature()+ {+ var temp=Path.Combine(Path.GetTempPath(),$"aetheris-sheetmetal-hole-{Guid.NewGuid():N}.step");+ try+ {+ var output=new StringWriter();var error=new StringWriter();+ var input=Path.Combine(RepoRoot,"fixtures/FirmamentV2/SheetMetal/preview3-l-bracket-hole.firmament");+ var exit=CliRunner.Run(["build",input,"--output",temp,"--json"],output,error);+ Assert.Equal(0,exit);Assert.Empty(error.ToString());+ using var report=JsonDocument.Parse(output.ToString());+ Assert.Equal(1,report.RootElement.GetProperty("part").GetProperty("features").GetInt32());+ var analysis=StepAnalyzer.Analyze(temp);+ Assert.Equal(3,analysis.Summary.SurfaceFamilies["cylinder"]);+ }+ finally{if(File.Exists(temp))File.Delete(temp);}+ }++ [Fact]+ public void BuildAuthoredSheetMetal_RejectsModelDomainHoleSyntaxInsteadOfIgnoringIntent()+ {+ var canonical=File.ReadAllText(Path.Combine(RepoRoot,"fixtures/FirmamentV2/SheetMetal/preview3-l-bracket-hole.firmament"));+ var source=canonical.Replace("Hole Mount", "Hole<Shaft> Mount", StringComparison.Ordinal);+ var dir=Path.Combine(Path.GetTempPath(),$"aetheris-sheetmetal-domain-{Guid.NewGuid():N}");Directory.CreateDirectory(dir);+ try+ {+ var input=Path.Combine(dir,"wrong-domain.firmament");File.WriteAllText(input,source);+ var output=new StringWriter();var error=new StringWriter();+ var exit=CliRunner.Run(["build",input,"--json"],output,error);+ Assert.Equal(1,exit);Assert.Empty(error.ToString());+ Assert.Contains("sheetmetal-hole-domain-syntax",output.ToString(),StringComparison.Ordinal);+ Assert.Contains("Hole Mount",output.ToString(),StringComparison.Ordinal);+ }+ finally{Directory.Delete(dir,true);}+ }++ [Fact]+ public void BuildAuthoredSheetMetal_ExplainsModelDomainPmiSyntax()+ {+ var source=File.ReadAllText(Path.Combine(RepoRoot,"fixtures/FirmamentV2/SheetMetal/preview3-l-bracket-hole.firmament"));+ source=source.Insert(source.LastIndexOf('}'),"\n Pmi { Datum A { Target: face(-Z) } }\n");+ var dir=Path.Combine(Path.GetTempPath(),$"aetheris-sheetmetal-pmi-domain-{Guid.NewGuid():N}");Directory.CreateDirectory(dir);+ try+ {+ var input=Path.Combine(dir,"wrong-pmi-domain.firmament");File.WriteAllText(input,source);+ var output=new StringWriter();var error=new StringWriter();+ var exit=CliRunner.Run(["build",input,"--json"],output,error);+ Assert.Equal(1,exit);Assert.Empty(error.ToString());+ Assert.Contains("sheetmetal-pmi-domain-syntax",output.ToString(),StringComparison.Ordinal);+ Assert.Contains("DatumFeature A",output.ToString(),StringComparison.Ordinal);+ }+ finally{Directory.Delete(dir,true);}+ }+[Fact]public void ValidateRoutesModuleShapedSheetMetalThroughDomainCompiler(){diff --git a/Aetheris.Forge.Host.Tests/ForgeProtocolV1Tests.cs b/Aetheris.Forge.Host.Tests/ForgeProtocolV1Tests.csindex 470d4445..266957ca 100644--- a/Aetheris.Forge.Host.Tests/ForgeProtocolV1Tests.cs+++ b/Aetheris.Forge.Host.Tests/ForgeProtocolV1Tests.cs@@ -105,6 +105,19 @@ public sealed class ForgeProtocolV1TestsAssert.True(File.Exists(System.IO.Path.Combine(outputDirectory.Path, "part.step")));}+ [Fact]+ public void PublicInteropRequestInvokesTheProductionTemplate()+ {+ using var outputDirectory = TempDirectory.Create();+ var root = FindRepoRoot();+ var requestPath = System.IO.Path.Combine(root, "samples", "forge-interop-x1", "request.json");+ var request = JsonSerializer.Deserialize(File.ReadAllText(requestPath), ForgeProtocolJsonContext.Default.ForgeTemplateInvocationRequest);+ var result = new ForgeProtocolHost().InvokeTemplate(Enclosure, request!, outputDirectory.Path);+ Assert.True(result.Success, string.Join(Environment.NewLine, result.Diagnostics.Select(item => item.Code + ": " + item.Message)));+ Assert.Equal([ForgeArtifactKind.StepAp242, ForgeArtifactKind.FlatStep, ForgeArtifactKind.Svg], result.Artifacts.Select(item => item.Kind));+ Assert.All(result.Artifacts, artifact => Assert.True(File.Exists(System.IO.Path.Combine(outputDirectory.Path, artifact.Path))));+ }+private static ForgeTemplateInvocationRequest Request(IReadOnlyDictionary<string, object?> values, params ForgeArtifactKind[] artifacts) =>new(1, Elements(values), artifacts);@@ -127,6 +140,13 @@ public sealed class ForgeProtocolV1Testsvar values = ValidArguments(); values[name] = value; return values;}+ private static string FindRepoRoot()+ {+ var directory = new DirectoryInfo(AppContext.BaseDirectory);+ while (directory is not null && !File.Exists(System.IO.Path.Combine(directory.FullName, "Aetheris.slnx"))) directory = directory.Parent;+ return directory?.FullName ?? throw new DirectoryNotFoundException();+ }+private sealed class TempDirectory : IDisposable{private TempDirectory(string path) => Path = path;diff --git a/Aetheris.Kernel.Firmament.Tests/FirmamentV2CanonicalGrammarTests.cs b/Aetheris.Kernel.Firmament.Tests/FirmamentV2CanonicalGrammarTests.csindex 6030199d..feeed600 100644--- a/Aetheris.Kernel.Firmament.Tests/FirmamentV2CanonicalGrammarTests.cs+++ b/Aetheris.Kernel.Firmament.Tests/FirmamentV2CanonicalGrammarTests.cs@@ -1,4 +1,5 @@using Aetheris.Kernel.Firmament.FirmamentV2;+using Aetheris.Kernel.Core.Step242;namespace Aetheris.Kernel.Firmament.Tests;@@ -67,6 +68,40 @@ public sealed class FirmamentV2CanonicalGrammarTests}}+ [Fact]+ public void CanonicalCombinedPart_PreservesSupportedPmiInAp242AndInspectionEvidence()+ {+ var firstOutput = Path.Combine(Path.GetTempPath(), $"aetheris-canonical-pmi-edge-{Guid.NewGuid():N}.step");+ var secondOutput = Path.Combine(Path.GetTempPath(), $"aetheris-canonical-pmi-edge-{Guid.NewGuid():N}.step");+ try+ {+ var fixture = Fixture("box-holes-pmi-chamfer.firmament");+ var parsed = FirmamentV2Parser.Parse(File.ReadAllText(fixture));+ Assert.True(parsed.IsSuccess, string.Join(Environment.NewLine, parsed.Diagnostics));+ Assert.Equal(3, parsed.Document!.Pmi!.Count);++ var first = FirmamentBuildAndExport.Run(fixture, firstOutput);+ var second = FirmamentBuildAndExport.Run(fixture, secondOutput);++ Assert.True(first.IsSuccess, string.Join(Environment.NewLine, first.Diagnostics.Select(d => d.Message)));+ Assert.True(second.IsSuccess, string.Join(Environment.NewLine, second.Diagnostics.Select(d => d.Message)));+ Assert.Equal("CombinedHoleEdgeFinish", first.Value.Export.Combined!.Route);+ Assert.Single(first.Value.Export.DatumInspection!);+ Assert.Equal(2, first.Value.Export.DimensionInspection!.Count);+ Assert.Equal(File.ReadAllText(firstOutput), File.ReadAllText(secondOutput));++ var pmi = Step242SemanticPmiInspector.Inspect(File.ReadAllText(firstOutput));+ Assert.True(pmi.Success, string.Join(Environment.NewLine, pmi.Diagnostics));+ Assert.Equal(1, pmi.DatumCount);+ Assert.Equal(2, pmi.DimensionCount);+ }+ finally+ {+ if (File.Exists(firstOutput)) File.Delete(firstOutput);+ if (File.Exists(secondOutput)) File.Delete(secondOutput);+ }+ }+[Fact]public void CanonicalPoint2_RejectsTheLegacyBracketLiteralWithASpecificDiagnostic(){diff --git a/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs b/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.csindex 6aa4cfd4..880822a0 100644--- a/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs+++ b/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs@@ -43,6 +43,12 @@ public static class FirmamentBuildAndExportreturn KernelResult<FirmamentBuildAndExportResult>.Failure(exportResult.Diagnostics);}+ var pmiParity = VerifyV2PmiExportParity(sourceText, Path.GetDirectoryName(fullSourcePath), exportResult.Value);+ if (!pmiParity.IsSuccess)+ {+ return KernelResult<FirmamentBuildAndExportResult>.Failure(pmiParity.Diagnostics);+ }+var assertions = EvaluateVolumeAssertions(sourceText, Path.GetDirectoryName(fullSourcePath), exportResult.Value);if (!assertions.IsSuccess){@@ -79,6 +85,8 @@ public static class FirmamentBuildAndExport// available only to the explicitly versioned file compatibility route.var export = ExportSource(normalized, sourceDirectory, allowV1Compatibility: false);if (!export.IsSuccess) return export;+ var pmiParity = VerifyV2PmiExportParity(normalized, sourceDirectory, export.Value);+ if (!pmiParity.IsSuccess) return KernelResult<FirmamentStepExportResult>.Failure(pmiParity.Diagnostics);var assertions = EvaluateVolumeAssertions(normalized, sourceDirectory, export.Value);return assertions.IsSuccess? KernelResult<FirmamentStepExportResult>.Success(export.Value with { Assertions = assertions.Value }, export.Diagnostics)@@ -110,6 +118,31 @@ public static class FirmamentBuildAndExport: KernelResult<IReadOnlyList<FirmamentV2VolumeAssertionResult>>.Failure(failures);}+ private static KernelResult<bool> VerifyV2PmiExportParity(string source, string? sourceDirectory, FirmamentStepExportResult export)+ {+ var parsed = FirmamentV2Parser.Parse(source, sourceDirectory);+ if (!parsed.IsSuccess || parsed.Document is null || parsed.Document.Pmi is not { Count: > 0 } pmi)+ return KernelResult<bool>.Success(true);++ var support = ValidateV2PmiExportSupport(parsed.Document);+ if (!support.IsSuccess) return support;++ var expectedDatums = pmi.Count(record => record.Kind == FirmamentV2PmiKind.DatumPlane);+ var expectedDiameters = pmi.Count(record => record.Kind == FirmamentV2PmiKind.HoleDiameter);+ var inspection = Step242SemanticPmiInspector.Inspect(export.StepText);+ if (inspection.Success && inspection.DatumCount == expectedDatums && inspection.DimensionCount == expectedDiameters)+ return KernelResult<bool>.Success(true);++ var actualDatums = inspection.Success ? inspection.DatumCount : 0;+ var actualDiameters = inspection.Success ? inspection.DimensionCount : 0;+ var detail = inspection.Success ? string.Empty : $" Inspector diagnostics: {string.Join("; ", inspection.Diagnostics)}";+ return KernelResult<bool>.Failure([new Kernel.Core.Diagnostics.KernelDiagnostic(+ Kernel.Core.Diagnostics.KernelDiagnosticCode.ValidationFailed,+ Kernel.Core.Diagnostics.KernelDiagnosticSeverity.Error,+ $"firmament-v2-pmi-export-evidence-mismatch: validation admitted {expectedDatums} datum and {expectedDiameters} diameter PMI records, but AP242 reinspection found {actualDatums} datum and {actualDiameters} diameter records.{detail}",+ "FirmamentV2.PmiExportParity")]);+ }+private static KernelResult<FirmamentStepExportResult> ExportSource(string sourceText,@@ -791,7 +824,13 @@ public static class FirmamentBuildAndExport{return CombinedFailure("CombinedFeaturePlanChainInvalid: final combined plan did not produce one enclosed manifold body.");}- var step = Step242Exporter.ExportBody(body);+ var pmiSupport = ValidateV2PmiExportSupport(document);+ if (!pmiSupport.IsSuccess)+ {+ return KernelResult<FirmamentStepExportResult>.Failure(pmiSupport.Diagnostics);+ }+ var semanticPmi = BuildV2SemanticPmi(document, holes, solid.Name);+ var step = Step242Exporter.ExportBody(body, semanticPmi);if (!step.IsSuccess || step.Value is null){return KernelResult<FirmamentStepExportResult>.Failure(step.Diagnostics);@@ -827,7 +866,17 @@ public static class FirmamentBuildAndExportConvert.ToHexString(SHA256.HashData(Encoding.UTF8.GetBytes(step.Value))), body.Topology.Vertices.Count(), body.Topology.Edges.Count(), body.Topology.Faces.Count(),body.Geometry.Surfaces.Count(s => s.Value.Kind == SurfaceGeometryKind.Plane), body.Geometry.Surfaces.Count(s => s.Value.Kind == SurfaceGeometryKind.Cylinder), true, true);var featureReports = holes.Select(h => new FirmamentHoleFeatureReport(h.Name, "Hole", h.FeatureId, h.Shaft.Diameter, h.Placement.U, h.Placement.V, null, null, null, null, "top", null, nameof(AirHoleSimpleShaftMaterializer), "HoleChangedBRepPlan", h.Stack.Kind.ToString(), "CombinedHoleEdgeFinish", 1, 0, 0, report.StepSha256, true)).ToArray();- return KernelResult<FirmamentStepExportResult>.Success(new FirmamentStepExportResult(step.Value, finish.Name, 0, "combined-hole-edgefinish", "CombinedHoleEdgeFinish", ConceptIr: document.ConceptIr, Features: featureReports, Combined: report));+ return KernelResult<FirmamentStepExportResult>.Success(new FirmamentStepExportResult(+ step.Value,+ finish.Name,+ 0,+ "combined-hole-edgefinish",+ "CombinedHoleEdgeFinish",+ DatumInspection: document.Pmi?.Where(p => p.Kind == FirmamentV2PmiKind.DatumPlane).Select(p => new FirmamentPmiInspectionDatum(p.Name, "planar", p.Target)).ToArray() ?? [],+ DimensionInspection: document.Pmi?.Where(p => p.Kind == FirmamentV2PmiKind.HoleDiameter).Select(p => new FirmamentPmiInspectionDimension("Diameter", p.Target, null, p.Value ?? 0d, "explicit-v2-semantic-pmi", p.Name)).ToArray() ?? [],+ ConceptIr: document.ConceptIr,+ Features: featureReports,+ Combined: report));}private static KernelResult<FirmamentStepExportResult> CombinedFailure(string message, IEnumerable<string>? details = null) =>@@ -1757,7 +1806,7 @@ public static class FirmamentBuildAndExportsemanticHoles.Count == 1 ? nameof(AirHoleSimpleShaftMaterializer) : nameof(AirHoleCompositeMaterializer),semanticHoles.Count == 1 ? feature.Stack.Kind.ToString() : "CompositeSimpleShaft",DatumInspection: document.Pmi?.Where(p => p.Kind == FirmamentV2PmiKind.DatumPlane).Select(p => new FirmamentPmiInspectionDatum(p.Name, "planar", p.Target)).ToArray() ?? [],- DimensionInspection: document.Pmi?.Where(p => p.Kind == FirmamentV2PmiKind.HoleDiameter).Select(p => new FirmamentPmiInspectionDimension("Diameter", p.Target, null, p.Value ?? 0d, "explicit-v2-semantic-pmi", null)).ToArray() ?? [],+ DimensionInspection: document.Pmi?.Where(p => p.Kind == FirmamentV2PmiKind.HoleDiameter).Select(p => new FirmamentPmiInspectionDimension("Diameter", p.Target, null, p.Value ?? 0d, "explicit-v2-semantic-pmi", p.Name)).ToArray() ?? [],ConceptIr: document.ConceptIr,Features: featureReports));}diff --git a/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2ValidationReport.cs b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2ValidationReport.csindex a46acf11..330f9e0d 100644--- a/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2ValidationReport.cs+++ b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2ValidationReport.cs@@ -39,13 +39,14 @@ public static class FirmamentV2ValidationReportBuilderconceptCatalog ??= FirmamentV2ForgeConceptRegistry.Catalog;var diagnostics = parse.Diagnostics.Distinct(StringComparer.Ordinal)+ .Where(code => !IsParserTraceDiagnostic(code)).Select(ToParserDiagnostic).Concat(runtimeValidation.Diagnostics.Select(ToRuntimeDiagnostic)).Distinct().ToArray();var fatalCount = diagnostics.Count(diagnostic => diagnostic.Severity == "fatal");- var warningCount = diagnostics.Length - fatalCount;+ var warningCount = diagnostics.Count(diagnostic => diagnostic.Severity == "warning");var document = parse.Document;var lets = document is null ? [] : BuildLets(document);var concepts = document is null ? [] : BuildConcepts(document, runtimeValidation, conceptCatalog);@@ -58,7 +59,7 @@ public static class FirmamentV2ValidationReportBuilder.Distinct().ToArray();fatalCount = diagnostics.Count(diagnostic => diagnostic.Severity == "fatal");- warningCount = diagnostics.Length - fatalCount;+ warningCount = diagnostics.Count(diagnostic => diagnostic.Severity == "warning");var supported = pmi.Count(record => record.ExportSupport is "supported" or "supported-when-target-resolves");var deferred = pmi.Count(record => record.ExportSupport == "deferred");var status = fatalCount > 0 ? "invalid" : deferred > 0 ? "valid-with-deferred-export" : "valid";@@ -305,6 +306,12 @@ public static class FirmamentV2ValidationReportBuilderprivate static FirmamentV2ValidationDiagnostic ToParserDiagnostic(string code) =>new(code, FirmamentV2Parser.IsFatalDiagnosticCode(code) ? "fatal" : "warning", Message(code));+ private static bool IsParserTraceDiagnostic(string code) =>+ code is "firmament-v2-parser-invoked" or "firmament-v2-parse-succeeded"+ || code.EndsWith("-parsed", StringComparison.Ordinal)+ || code.EndsWith("-adapted", StringComparison.Ordinal)+ || code.EndsWith("-symbols-bound", StringComparison.Ordinal);+private static FirmamentV2ValidationDiagnostic ToRuntimeDiagnostic(FirmamentDiagnostic diagnostic) =>new(diagnostic.Code,diff --git a/Aetheris.SheetMetal/SheetMetalAuthoredLowering.cs b/Aetheris.SheetMetal/SheetMetalAuthoredLowering.csindex 7cf98ac6..fac65d9c 100644--- a/Aetheris.SheetMetal/SheetMetalAuthoredLowering.cs+++ b/Aetheris.SheetMetal/SheetMetalAuthoredLowering.cs@@ -56,6 +56,15 @@ internal static class AuthoredSheetMetalCompilervar diagnostics = new List<SheetMetalDiagnostic>();var header = Regex.Match(source, @"\bSheetMetal\s+(?<name>[A-Za-z_][A-Za-z0-9_]*)(?:\s*:\s*(?<concept>[A-Za-z_][A-Za-z0-9_]*))?\s*\{", Rx);if (!header.Success) return Fail("Expected `SheetMetal <Name> { ... }`.");+ var modelStyleHole = Regex.Match(source, @"\bHole\s*<\s*(?<variant>[A-Za-z_][A-Za-z0-9_]*)\s*>", Rx);+ if (modelStyleHole.Success)+ return Fail(+ $"Sheet Metal does not use the Model-domain `Hole<{modelStyleHole.Groups["variant"].Value}>` form. Declare `Hole <Name> {{ On: <planar-region>; Center: (<x>, <y>); Diameter: <length>; }}`; for example, `Hole Mount {{ On: Base; Center: (20mm, 15mm); Diameter: 6mm; }}`.",+ "sheetmetal-hole-domain-syntax");+ if (Regex.IsMatch(source, @"\bPmi\s*\{\s*Datum\s+[A-Za-z_]", Rx))+ return Fail(+ "Sheet Metal PMI does not use the Model-domain `Datum` record or axis-face targets. Add a `Manufacturing <Release> { ... }` block and declare `DatumFeature <Label> { Target: <named-sheet-region>; }` inside `Pmi`; for example, `DatumFeature A { Target: Base; }`.",+ "sheetmetal-pmi-domain-syntax");if (!Scalar(source, "Thickness", "mm", out var thickness) || thickness <= 0)return Fail("Thickness must be a positive millimetre value.");var material = Quoted(source, "Material");diff --git a/README.md b/README.mdindex de5859a8..bb21c392 100644--- a/README.md+++ b/README.md@@ -1,202 +1,34 @@-# Aetheris 2.0.0-preview.3 + Firmament V2+# Aetheris 2.0.0-preview.3-> Aetheris is under feature freeze for the `2.0.0-preview.3` release candidate.-> This milestone accepts correctness, packaging, diagnostics, documentation,-> cross-platform, NativeAOT, determinism, and other release-hardening fixes to-> existing behavior; new feature families are deferred until after Preview 3.->-> The public language-manual source is maintained in the sibling-> `yuechen-li-dev.github.io` repository at `src/aetheris` and published under-> `/aetheris/`. Documentation here includes architecture, implementation-> evidence, and historical milestone records. The Preview 2 support contract-> remains at `docs/preview2/feature-manifest.json`; Preview 3 release topology-> and qualification evidence are recorded in `docs/release/PREVIEW3-HARDEN-A1.md`.+Aetheris turns semantic engineering intent into deterministic CAD and analysis artifacts. Firmament V2 is its authoring language; the Aetheris compiler, geometry kernel, Standard Library, Sheet Metal and FEA modules lower that intent to STEP AP242, manufacturing outputs, and analysis results. Cadmata is the interactive 3D inspection surface, and Forge exposes qualified templates to other programs.-Firmament is a deterministic DSL for generating CAD geometry (STEP AP242) via Aetheris.+Preview 3 is feature-frozen and qualified on Windows x64. It includes bounded exact geometry, typed Templates and static engineering data, STEP AP242 import/export, semantic PMI, authored and reconstructed Sheet Metal workflows, a linear-elastic FEA path, the material catalog, Cadmata, and Forge Host Protocol v1. The exact boundaries are in the [Preview 3 support matrix](docs/public/reference/supported-features.md).-Firmament V2 is the sole canonical authoring path. Firmament V1 TOON/JSON and JSON-shaped legacy `.firmasm` remain explicit compatibility/serialization inputs. See the [current authoring and kernel boundaries](docs/architecture/current-authoring-and-kernel-boundaries.md).+## Start here-## Generic Sheet Metal product families+- [Getting Started](docs/public/getting-started.md) — install, build a real part, inspect it, and invoke a Template.+- [Public documentation](docs/public/README.md) — authoritative user-facing Preview 3 behavior.+- [Firmament overview](docs/public/firmament/overview.md) — the language's engineering mental model.+- [CLI reference](docs/public/reference/cli.md) — stable commands and structured-output expectations.-Firmament `Template` is typed compile-time generic programming—not a document-template, prefab model, macro, or C# geometry generator. The Sheet Metal module-ships its product families as readable Firmament source:+After publication, install the CLI with the .NET 10 SDK:-```firmament-Use SheetMetal.ProductFamilies;--Static Psu: EnclosureSpec = EnclosureSpec {- Width: 240mm Depth: 180mm Height: 60mm LidLipHeight: 8mm- Thickness: 1.2mm InsideRadius: 1.5mm KFactor: 0.42- ReliefPolicy: Rectangular-}-SheetMetal Enclosure = ElectronicsEnclosure < Spec: Psu >-```--The specialization lowers through ordinary Base, Flange, Relief, Cut, exact-flat,-DFM, SVG, and STEP paths. Generic Assembly DatumFrames and tolerance-aware enclosure-fit are documented in the [M7 guide](docs/sheetmetal/aetheris-sheetmetal-m7.md); see-also the [M5 product-family guide](docs/firmament/sheetmetal-product-templates-m5.md).--## Static engineering data--Firmament `Record` values are immutable typed specifications. A finite standards-catalog can be authored directly as a columnar static Table, selected as a-Record, and derived without copying it:--```firmament-Static Table Sizes: BoltRow Key: Size {- Size: [M8, M10]- Diameter: [8mm, 10mm]-}-Static M8 = Sizes[M8]-Static M8Long = M8 with { Length: 80mm }-```--Tables and `with` values are compile-time-only: they feed typed Template Record-parameters and are erased before geometry AIR. A Table is not a runtime-dataframe, SQL surface, or spreadsheet import format. See-[the M1 language note](docs/preview2/firmament-tables-with-m1.md).--## Preview 3 release candidate--Aetheris `2.0.0-preview.3` is qualified for Windows x64 as a release bundle,-the `Aetheris.CLI` .NET global tool, public .NET integration packages, and a-standalone Forge Host Protocol v1 executable. After publication, install the-CLI with:--```bash+```powershelldotnet tool install --global Aetheris.CLI --prerelease+aetheris --version```-The NuGet tool does not include Cadmata; use the Windows bundle for `aetheris view`.-The public manual and installation guidance are at-[yuechen-li-dev.github.io/aetheris](https://yuechen-li-dev.github.io/aetheris/).--Maintainer release builds require the .NET 10 SDK, the Windows NativeAOT C++-toolchain, and TSPack. Cadmata and the Firmament VS Code extension are restored-and built from their committed `manifest.tsx` and `ts-lock.toml` files. Do not-substitute npm install/ci or generate a `package-lock.json` for either workspace.--## What works today--- canonical V2 semantic construction, including bounded exact through-hole Recipes-- historical V1 primitive/Boolean execution retained as explicit compatibility-- placement with `place.on` anchors and `offset[3]`-- validation ops: `expect_exists`, `expect_selectable`, `expect_manifold`-- schema-aware CNC minimum tool radius validation-- deterministic canonical formatting for supported `.firmament` source-- STEP AP242 export for the current single-body golden path-- typed relational assembly inspection (`asm inspect`) plus legacy `.firmasm` execution/export compatibility--## 30-second demo--Open the example at `testdata/firmament/examples/box_with_hole.firmament`.--Then run the demo-oriented helper test:--```bash-export PATH="$HOME/.dotnet:$PATH"-dotnet test Aetheris.Kernel.Firmament.Tests/Aetheris.Kernel.Firmament.Tests.csproj --filter "FullyQualifiedName~FirmamentBuildAndExportTests.Run_BoxWithHoleExample_Writes_Default_Export_Artifact"-```--That flow compiles the example, exports STEP using the current last-successful-body policy, and writes the artifact to:--- `testdata/firmament/exports/box_with_hole.step`--For `box_with_hole.firmament`, the exported body is currently the deterministic fallback body selected by the existing export contract, so the demo stays behaviorally accurate without changing runtime semantics.--If you want the API entry point instead of the test wrapper, use `FirmamentBuildAndExport.Run(string sourcePath)` from `Aetheris.Kernel.Firmament`.--## Automation-friendly test entrypoints--The canonical solution format is `Aetheris.slnx` for both local and automation workflows. Primary targeting is .NET 10 (`net10.0`) only; legacy .NET 8 targeting has been removed.--### Canonical repo-level test path--Use the shell script below as the official automation-friendly entrypoint. It runs the canonical solution (`Aetheris.slnx`) on the sole active framework (`net10.0`), excludes `SlowCorpus` by default, and leaves legacy Firmament V1/FrictionLab tests opt-in.--```bash-export PATH="$HOME/.dotnet:$PATH"-./scripts/test-all.sh-```--### Narrow fallback test paths--If you need a single project or a smaller local repro, use the project-level commands directly:--```bash-export PATH="$HOME/.dotnet:$PATH"-dotnet test Aetheris.Kernel.Firmament.Tests/Aetheris.Kernel.Firmament.Tests.csproj --logger "console;verbosity=minimal"-dotnet test Aetheris.Server.Tests/Aetheris.Server.Tests.csproj --logger "console;verbosity=minimal"-dotnet test Aetheris.Kernel.Core.Tests/Aetheris.Kernel.Core.Tests.csproj --logger "console;verbosity=minimal"-dotnet test Aetheris.Continuum.Tests/Aetheris.Continuum.Tests.csproj --logger "console;verbosity=minimal"-```--If you want the same script with a narrower or broader explicit project list, pass the test projects as arguments:--```bash-export PATH="$HOME/.dotnet:$PATH"-DOTNET_BIN=dotnet ./scripts/test-all.sh Aetheris.Kernel.Firmament.Tests/Aetheris.Kernel.Firmament.Tests.csproj Aetheris.Server.Tests/Aetheris.Server.Tests.csproj-```--For editor/IDE compatibility or solution-wide restore/build flows, use:--```bash-export PATH="$HOME/.dotnet:$PATH"-dotnet test Aetheris.slnx -f net10.0 --filter "Category!=SlowCorpus"-```--Use the `SlowCorpus` category to keep the heavyweight STEP242 NIST audit out of default solution runs. Invoke that corpus explicitly when needed:+From a source checkout, use the same real CLI path without installing it:-```bash-export PATH="$HOME/.dotnet:$PATH"-dotnet test Aetheris.slnx -f net10.0 --filter "Category!=SlowCorpus"-dotnet test Aetheris.Kernel.Core.Tests --filter "Category=SlowCorpus"+```powershell+dotnet run --project Aetheris.CLI -c Release -- build fixtures/FirmamentV2/Canonical/valid/box-holes-pmi-chamfer.firmament --output artifacts/mounting-plate.step --json+dotnet run --project Aetheris.CLI -c Release -- analyze artifacts/mounting-plate.step --json```-Use `Aetheris.slnx` as the only solution entrypoint. For legacy Firmament V1/FrictionLab test validation, run `AETHERIS_RUN_LEGACY_TESTS=1 dotnet test Aetheris.slnx -f net10.0` or `./scripts/test-legacy.sh`. See `docs/build-test-policy-net10-and-legacy-v1.md`.--## Repo map--- exact kernel math, geometry, and BRep: `Aetheris.Kernel.Core/`-- occupied-region, SDF backend, and lattice experiments: `Aetheris.Continuum/`-- Continuum architecture and M0 evidence: `docs/continuum/`-- language/compiler/runtime: `Aetheris.Kernel.Firmament/`-- examples: `testdata/firmament/examples/`-- exported STEP artifacts: `testdata/firmament/exports/`--## Docs--- assembly model and contracts (canonical): `docs/assembly/architecture.md`-- overview: `docs/firmament-overview.md`-- build/export workflow: `docs/firmament-build-workflow.md`-- selector contracts: `docs/firmament-selectors.md`-- demo script: `docs/firmament-demo.md`--## Assembly model snapshot--- Firmament Assembly source lowers to normalized AssemblyIR; `.firmasm` is the current single-root Assembly document profile. Only the historical JSON-shaped `.firmasm` syntax is a deprecated transform-first compatibility lane.-- STEP is treated as foreign interop input/output.-- Multi-root STEP is assembly-like input and must route through assembly extraction/import, not single-part import.-- Current roundtrip export is intentionally bounded to per-instance STEP + `roundtrip.package.json`.--## Notes--- The repository still contains broader Aetheris server/client scaffolding; the Firmament + CLI paths above are the primary deterministic kernel entry points.+The packaged CLI does not include Cadmata; use the Windows bundle for `aetheris view`. Maintainer build and test policy lives in [development documentation](docs/development/README.md). Historical milestone, experiment, architecture, and artifact reports remain valuable evidence, but they are not the public behavior contract.## License and acknowledgments-Aetheris source code is licensed under the GNU Affero General Public License-v3.0 (`AGPL-3.0`), except for third-party assets distributed with the-repository, which retain their respective licenses and attribution.-Alternative licensing is available on request. See [LICENSE](LICENSE) and-[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).+Aetheris source is licensed under GNU AGPL-3.0, except for third-party assets which retain their own licenses and attribution. Alternative licensing is available on request. See [LICENSE](LICENSE) and [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).-Special thanks to the National Institute of Standards and Technology (NIST)-for making available the STEP AP242 test models used during development and-validation. The project's STEP, PMI, Sheet Metal, and reconstruction work-would not have been possible in its present form without those models. The-files retain their original NIST project descriptions and filenames; this-acknowledgment does not imply NIST endorsement, authorship of Aetheris, or-application of the Aetheris license to the models.+Special thanks to the National Institute of Standards and Technology (NIST) for the STEP AP242 test models used in development and validation. Their inclusion does not imply NIST endorsement, authorship of Aetheris, or application of the Aetheris license to those models.diff --git a/docs/development/README.md b/docs/development/README.mdnew file mode 100644index 00000000..173a032e--- /dev/null+++ b/docs/development/README.md@@ -0,0 +1,11 @@+# Development documentation++This index marks the non-public documentation boundary. The authoritative user-facing Preview 3 contract is [`docs/public`](../public/README.md).++- `docs/release/` and `docs/milestones/`: hardening and historical milestone reports+- `docs/architecture/`, `docs/implementation/`, and root architecture notes: internal design and migration records+- `docs/**/artifacts/`: experimental/qualification evidence and generated artifacts+- `docs/research/`, `docs/continuum/experiments/`, and similarly named reports: research or experimental work+- feature-specific legacy directories: implementation archaeology that may predate current syntax++These documents explain why the system evolved and preserve evidence. They do not override public docs or the current executable. Maintainer build/test policy remains in [`docs/build-test-policy-net10-and-legacy-v1.md`](../build-test-policy-net10-and-legacy-v1.md).diff --git a/docs/public/README.md b/docs/public/README.mdnew file mode 100644index 00000000..5348bc17--- /dev/null+++ b/docs/public/README.md@@ -0,0 +1,12 @@+# Aetheris Preview 3 public documentation++This directory is the authoritative in-repository guide to behavior shipped in Aetheris `2.0.0-preview.3`. It describes what users can do now. Files elsewhere under `docs/` may be development reports, architecture notes, experiments, milestone evidence, or generated artifacts; use them for background, not as the public contract.++Start with [Getting Started](getting-started.md), then use these guides:++- Firmament: [overview](firmament/overview.md), [syntax](firmament/syntax.md), [geometry](firmament/geometry.md), [Templates](firmament/templates.md), [materials](firmament/materials.md), [PMI](firmament/pmi.md), [Sheet Metal](firmament/sheet-metal.md), [FEA](firmament/fea.md), and [STEP import](firmament/step-import.md)+- Interoperability: [Forge Host Protocol v1](forge/interop.md)+- Inspection: [Cadmata](cadmata/overview.md) and [Cadmata PMI](cadmata/pmi.md)+- Reference: [CLI](reference/cli.md), [targets/selectors](reference/targets.md), [diagnostics](reference/diagnostics.md), and [supported features](reference/supported-features.md)++All linked example source files are exercised by the public-example qualification tests. Preview 3's reliability rule is simple: a supported requested semantic operation is produced, and an unsupported operation fails with a named diagnostic; successful builds must not silently discard engineering intent.diff --git a/docs/public/cadmata/overview.md b/docs/public/cadmata/overview.mdnew file mode 100644index 00000000..81643e0f--- /dev/null+++ b/docs/public/cadmata/overview.md@@ -0,0 +1,7 @@+# Cadmata++Cadmata is Aetheris's interactive 3D engineering presentation and inspection surface. It displays geometry, supports selection and feature association, and presents semantic PMI—datums, dimensions, GD&T, and engineering notes—with filtering and inspection context.++Use `aetheris view model.firmament` or `aetheris view part.step` from the qualified Windows bundle. The standalone .NET tool package does not contain Cadmata. Cadmata is not primarily a traditional drawing system: static drawing and shop-floor projection are downstream presentations of the semantic model.++Preview 3 qualification is Windows x64. See [PMI presentation](pmi.md) and the [support matrix](../reference/supported-features.md).diff --git a/docs/public/cadmata/pmi.md b/docs/public/cadmata/pmi.mdnew file mode 100644index 00000000..0af84a21--- /dev/null+++ b/docs/public/cadmata/pmi.md@@ -0,0 +1,5 @@+# PMI in Cadmata++Cadmata reads semantic AP242 associations rather than inferring requirements from label positions. Users can filter and select datums, dimensions, geometric tolerances, and engineer-authored notes; the selected presentation remains associated with its semantic feature or face.++The authoritative state is the semantic requirement and its target. Label orientation, camera placement, occlusion handling, and screen layout are presentation choices. Preview 3's public native Firmament export subset is documented in the [PMI guide](../firmament/pmi.md); Cadmata can present broader semantic AP242 content where the importer recognizes it, but that does not expand Firmament authoring support.diff --git a/docs/public/firmament/fea.md b/docs/public/firmament/fea.mdnew file mode 100644index 00000000..53659410--- /dev/null+++ b/docs/public/firmament/fea.md@@ -0,0 +1,15 @@+# Linear-elastic FEA++Preview 3's production FEA path is `Analysis LinearElastic` with the `LinearElasticIsotropic` material model. It supports a native body or bounded canonical `inlineSTEP`, catalog material lookup, `Fixed` component constraints, total-resultant `Force`, requested displacement/strain/stress/reaction results, and an explicit vector-lattice resolution.++Run the qualified aluminum cantilever:++```powershell+aetheris fea fixtures/FirmamentV2/FEA/cantilever.firmament --out-dir artifacts/cantilever --json+```++`Force.vector` is the total resultant distributed across the selected boundary, not a force per node. The solver uses a cut-cell/vector-lattice formulation over the occupied body; it is not a conventional user-authored finite-element mesh. The fixture's simple cantilever provides a physically interpretable sanity witness, but it does not imply general solver qualification for nonlinear, anisotropic, plastic, contact, thermal, or dynamic physics.++The public-only A36 witness [`ai-fea-a36-cantilever.firmament`](../../../fixtures/FirmamentV2/PublicDogfood/ai-fea-a36-cantilever.firmament) is a 100 × 30 × 15 mm beam under a 500 N tip load. At `lattice: [16, 2, 2]`, Preview 3 reports `25.0619 µm`; Euler–Bernoulli beam theory with the catalog's 200 GPa modulus predicts about `24.7 µm`. This is a narrow sanity comparison, not a general accuracy claim.++Native selectors use `beam.face(-X)` and `beam.face(+X)`. Imported selectors use AP242 identity such as `body.face(#170)` after bounded inline import. [`inline-step-through-hole.firmament`](../../../fixtures/FirmamentV2/FEA/inline-step-through-hole.firmament) is the qualified imported example. Arbitrary imported containment is not promised; affected bodies fail loudly with `firmament-analysis-inline-step-containment-unsupported`.diff --git a/docs/public/firmament/geometry.md b/docs/public/firmament/geometry.mdnew file mode 100644index 00000000..28a77d3a--- /dev/null+++ b/docs/public/firmament/geometry.md@@ -0,0 +1,7 @@+# Geometry and semantic features++Preview 3 supports bounded production routes, not an unrestricted general-purpose CAD kernel. Public native examples cover Box, Cylinder, Frustum, RoundedBox, line/arc profile extrusion and composition, semantic shaft/counterbore/countersink holes, slots, patterns, selected chamfer/fillet routes, hollow bodies, and a bounded cubic lattice. Consult the [support matrix](../reference/supported-features.md) before relying on a combination.++Use named features and selectors, never raw internal B-rep IDs in native authoring. [`box-holes-pmi-chamfer.firmament`](../../../fixtures/FirmamentV2/Canonical/valid/box-holes-pmi-chamfer.firmament) demonstrates two holes, an outer-boundary chamfer, and PMI surviving the same AP242 build. [`profile-compose-l-bracket-counterbore-pmi.firmament`](../../../fixtures/FirmamentV2/Canonical/valid/profile-compose-l-bracket-counterbore-pmi.firmament) demonstrates a profile-composed part, pattern holes, a counterbore, a chamfer, and shaft-diameter PMI.++`HoleDiameter` on a `Hole<Counterbore>` targets the shaft `Diameter`; `CounterboreDiameter` remains a distinct feature field and has no separate public PMI record kind in Preview 3. Pattern generation supports geometry as a semantic whole; authored names for generated instances are not a stable public instance-selector family in Preview 3.diff --git a/docs/public/firmament/materials.md b/docs/public/firmament/materials.mdnew file mode 100644index 00000000..6934f1c6--- /dev/null+++ b/docs/public/firmament/materials.md@@ -0,0 +1,20 @@+# Materials++Firmament refers to catalog materials semantically, for example:++```firmament+material: Standard.Materials.Aluminum.5052_H32+```++Preview 3 ships four catalog entries:++| Reference | Material |+|---|---|+| `Standard.Materials.Aluminum.5052_H32` | Aluminum 5052-H32 |+| `Standard.Materials.Aluminum.6061_T6` | Aluminum 6061-T6 |+| `Standard.Materials.Steel.ASTM_A36` | ASTM A36 structural steel |+| `Standard.Materials.StainlessSteel.304_Annealed` | 304 stainless, annealed |++The Standard Library catalog is backed by a deployed SQLite asset and resolved by .NET. Firmament does not expose SQL. FEA consumes catalog density and the properties required by its constitutive model; an unknown material is a named error, not a fallback.++Build/solve [`catalog-material-coupon.firmament`](../../../fixtures/FirmamentV2/Materials/catalog-material-coupon.firmament) with `aetheris fea ... --out-dir artifacts/material --json`.diff --git a/docs/public/firmament/overview.md b/docs/public/firmament/overview.mdnew file mode 100644index 00000000..a687ce42--- /dev/null+++ b/docs/public/firmament/overview.md@@ -0,0 +1,11 @@+# Firmament V2 overview++Firmament is a semantic engineering authoring language. It expresses named bodies, dimensions and units, manufacturable features, reusable typed Templates, engineering requirements, Sheet Metal intent, and analyses. Aetheris is the compiler, kernel, and runtime that validates that intent and lowers supported constructions into artifacts such as STEP AP242, flat STEP, SVG, and FEA results.++A Template is compile-time typed engineering reuse. It accepts values or Records, checks its requirements, specializes deterministically, and then uses the ordinary Firmament lowering path. It is not a text macro or a hidden C# geometry generator.++Units are part of values and types. Lengths such as `8mm`, forces such as `500N`, and angles such as `90deg` are checked by the binder. Static Records, arrays, Tables, `with` derivation, and patterns organize finite engineering data and are erased after specialization.++Named semantic features survive beyond geometry construction. Supported PMI is emitted as AP242 product-definition semantics; feature and topology correspondence is available to inspection consumers such as Cadmata. Presentation orientation is not authoritative engineering state.++Canonical authoring is Firmament V2. V1 and JSON-shaped `.firmasm` exist only as explicitly identified compatibility inputs. See [syntax](syntax.md), [targets](../reference/targets.md), and the [support matrix](../reference/supported-features.md).diff --git a/docs/public/firmament/pmi.md b/docs/public/firmament/pmi.mdnew file mode 100644index 00000000..849131d7--- /dev/null+++ b/docs/public/firmament/pmi.md@@ -0,0 +1,17 @@+# Semantic PMI and AP242++Firmament concepts and explicit PMI lower into the semantic engineering model, STEP AP242 product-definition entities, and Cadmata's semantic presentation. PMI records are measurable requirements; annotations are engineer-authored notes. Camera or label orientation is presentation state, not the requirement.++Preview 3's native Model export supports `Datum` plane records and toleranced `HoleDiameter` records. The diameter record targets a named shaft hole; on a counterbore it means the shaft `Diameter`, not `CounterboreDiameter`. Other parsed PMI kinds may be reported as deferred and cannot be silently omitted by a successful build.++The complete qualified example is [`box-holes-pmi-chamfer.firmament`](../../../fixtures/FirmamentV2/Canonical/valid/box-holes-pmi-chamfer.firmament):++```powershell+aetheris validate fixtures/FirmamentV2/Canonical/valid/box-holes-pmi-chamfer.firmament --json+aetheris build fixtures/FirmamentV2/Canonical/valid/box-holes-pmi-chamfer.firmament --output artifacts/pmi.step --json+aetheris analyze artifacts/pmi.step --json+```++The build's `pmiExportEvidence` and the analyzer's `semanticPmi` are independent public evidence surfaces. Supported validate records and inspected AP242 records must agree at the semantic-record level; one record may lower to several STEP entities.++Pattern-generated geometry may coexist with PMI, but Preview 3 does not publish a stable selector for individual generated pattern instances or quantity/repeated-feature PMI authoring.diff --git a/docs/public/firmament/sheet-metal.md b/docs/public/firmament/sheet-metal.mdnew file mode 100644index 00000000..42c03c5c--- /dev/null+++ b/docs/public/firmament/sheet-metal.md@@ -0,0 +1,14 @@+# Sheet Metal++Authored Sheet Metal uses a specialized semantic model: a base region, named flanges and bend strips, and cuts on named planar regions. It can emit formed STEP, thickness-bearing flat STEP, and flat SVG; it also carries material, K-factor, DFM, semantic layout, and manufacturing definitions on qualified routes.++[`preview3-l-bracket-hole.firmament`](../../../fixtures/FirmamentV2/SheetMetal/preview3-l-bracket-hole.firmament) is the practical first example. Build the formed part and then flatten the same source:++```powershell+aetheris build fixtures/FirmamentV2/SheetMetal/preview3-l-bracket-hole.firmament --output artifacts/bracket-formed.step --json+aetheris sheetmetal flatten fixtures/FirmamentV2/SheetMetal/preview3-l-bracket-hole.firmament --step artifacts/bracket-flat.step --svg artifacts/bracket-flat.svg --json+```++Sheet Metal holes use `Hole Mount { On: Base; Center: (40mm, 20mm); Diameter: 8mm; }`. Model-domain `Hole<Shaft>` is deliberately rejected here with `sheetmetal-hole-domain-syntax`. `On` targets a named planar semantic region (`Base`, a named flange, or a verified exposed region/path), not `face(+Z)`. Manufacturing PMI likewise uses `DatumFeature A { Target: Base; }` inside `Pmi`, together with a named `Manufacturing` block; Model-domain `Datum`/`face(-Z)` syntax is rejected with `sheetmetal-pmi-domain-syntax`.++The JSON `part.features` count is the number of lowered cuts/openings in `SheetMetalPartIr`; bends are reported separately as `part.bends`. Authoring and imported reconstruction are separate workflows. Commands such as `sheetmetal recognize`, `recover-flat`, and `recover` operate on imported STEP and may be partial; they do not turn arbitrary geometry into authoritative authored intent.diff --git a/docs/public/firmament/step-import.md b/docs/public/firmament/step-import.mdnew file mode 100644index 00000000..63957a8b--- /dev/null+++ b/docs/public/firmament/step-import.md@@ -0,0 +1,7 @@+# STEP import and inlineSTEP++Use `aetheris analyze part.step --json` to inspect STEP topology, analytic surface families, bounds, manifold assessment, and semantic PMI. Use `aetheris sheetmetal recognize` for bounded Sheet Metal recognition rather than treating generic topology analysis as manufacturing intent.++Firmament `inlineSTEP` consumes Aetheris-canonical AP242 on the bounded production path. Imported faces are selected by source entity identity, for example `body.face(#170)`, and recognized regions may supply stable semantic aliases. [`inline-step-through-hole.firmament`](../../../fixtures/FirmamentV2/FEA/inline-step-through-hole.firmament) demonstrates FEA on a checked-in canonical STEP resource.++The importer does not promise arbitrary containment, multi-root assemblies, or every AP242 surface family as a single native body. Multi-root assembly-like STEP belongs to assembly import. Unsupported containment in FEA reports `firmament-analysis-inline-step-containment-unsupported`; missing files and unresolved face identities are fatal diagnostics.diff --git a/docs/public/firmament/syntax.md b/docs/public/firmament/syntax.mdnew file mode 100644index 00000000..045bc607--- /dev/null+++ b/docs/public/firmament/syntax.md@@ -0,0 +1,19 @@+# Firmament V2 syntax++A canonical native part begins with `Model`, declares `Units`, creates named solids, and applies semantic features in `Modify` or `Compose`:++```firmament+Model Plate {+ Units: mm+ Box Body { Size: [80mm, 50mm, 8mm] }+ Modify Body {+ Hole<Shaft> Mount { On: +Z Center: Point2(0mm, 0mm) Diameter: 8mm End: ThroughAll }+ }+}+```++Use PascalCase for semantic/declarative constructs and camelCase for ordinary data slots where the owning domain uses them. The parser is permissive where case has no semantic value. New V2 vocabulary does not use snake_case; external identifiers such as `5052_H32` preserve their source spelling.++Punctuation is construct-specific: braces delimit declarations, lists use brackets, and field separators may be line breaks or semicolons in admitted grammar. Copy a qualified fixture when entering a specialized domain: `SheetMetal` and `Analysis` have their own target forms and property vocabulary. The [target reference](../reference/targets.md) calls out these distinctions.++Use `aetheris validate file.firmament --json` before building. Diagnostics are codes intended for automation plus short corrective messages. See [diagnostics](../reference/diagnostics.md).diff --git a/docs/public/firmament/templates.md b/docs/public/firmament/templates.mdnew file mode 100644index 00000000..0139aa6d--- /dev/null+++ b/docs/public/firmament/templates.md@@ -0,0 +1,7 @@+# Templates and static data++Templates are typed compile-time functions over engineering values and Records. `Static` binds immutable values, arrays, or Tables; `Pattern ... Over` repeats an admitted feature from finite static data. `Require` constraints fail before geometry when a specialization is inadmissible.++Build [`record-array-pattern-holes.firmament`](../../../fixtures/FirmamentV2/Canonical/valid/record-array-pattern-holes.firmament) for the shortest array/Template/pattern example. [`table-template-concept-path-compose.firmament`](../../../fixtures/FirmamentV2/Canonical/valid/table-template-concept-path-compose.firmament) adds a keyed Table and profile composition. For Sheet Metal product families, see [`m5-four-wall-tray-template.firmament`](../../../fixtures/FirmamentV2/SheetMetal/m5-four-wall-tray-template.firmament).++Unknown Templates, missing arguments, extra fields, wrong unit dimensions, and failed `Require` constraints are errors. Template expansion does not create a second geometry or diagnostic path: expanded source uses the same binder and materializers as direct source.diff --git a/docs/public/forge/interop.md b/docs/public/forge/interop.mdnew file mode 100644index 00000000..50d93174--- /dev/null+++ b/docs/public/forge/interop.md@@ -0,0 +1,18 @@+# Forge Host Protocol v1++Forge interop has three operations: list Templates, describe one Template, and invoke it. The host owns Firmament types, units, defaults, `Require` checks, specialization, geometry, and artifact production. Foreign clients only exchange explicit JSON and files.++C# can use the direct Forge API. Python, Go, Rust, and TypeScript/Node use the process protocol:++```powershell+dotnet build Aetheris.Forge.Host -c Release+$host = "Aetheris.Forge.Host/bin/Release/net10.0/win-x64/Aetheris.Forge.Host.exe"+& $host list+& $host describe Standard.SheetMetal.ElectronicsEnclosure+python samples/forge-interop-x1/python/client.py $host samples/forge-interop-x1/request.json artifacts/forge-python+go run samples/forge-interop-x1/go/main.go $host samples/forge-interop-x1/request.json artifacts/forge-go+rustc samples/forge-interop-x1/rust/client.rs -o artifacts/forge-rust.exe+node samples/forge-interop-x1/typescript/client.ts $host samples/forge-interop-x1/request.json artifacts/forge-typescript+```++The shared production request is [`request.json`](../../../samples/forge-interop-x1/request.json), and the tiny clients are under [`samples/forge-interop-x1`](../../../samples/forge-interop-x1). Protocol v1 is language-neutral. The shipped NativeAOT binary and release bundle are qualified only for `win-x64`; framework-dependent tests on other operating systems establish protocol logic, not release-binary qualification.diff --git a/docs/public/getting-started.md b/docs/public/getting-started.mdnew file mode 100644index 00000000..249af3e6--- /dev/null+++ b/docs/public/getting-started.md@@ -0,0 +1,34 @@+# Getting Started++Preview 3 is qualified for Windows x64. Install the published .NET global tool with the .NET 10 SDK, or run the CLI from a source checkout:++```powershell+dotnet tool install --global Aetheris.CLI --prerelease+aetheris --help+```++For a source checkout, replace `aetheris` below with `dotnet run --project Aetheris.CLI -c Release --`.++## Build a first part++The qualified first part is [`box-hole-pmi.firmament`](../../fixtures/FirmamentV2/Canonical/valid/box-hole-pmi.firmament). It is a nontrivial plate with a through hole, datum, and toleranced diameter.++```powershell+aetheris validate fixtures/FirmamentV2/Canonical/valid/box-hole-pmi.firmament --json+aetheris build fixtures/FirmamentV2/Canonical/valid/box-hole-pmi.firmament --output artifacts/first-part.step --json+aetheris analyze artifacts/first-part.step --json+```++`validate` checks syntax, binding, units, targets, and supported/deferred PMI without materializing geometry. `build` runs the real geometry and AP242 path. In JSON, `success: true`, the output path, diagnostics, feature reports, and `pmiExportEvidence` describe what was actually emitted. `analyze` independently reinspects topology and semantic PMI.++Use `aetheris view ...` to open Firmament or STEP in Cadmata when using the Windows bundle.++## Invoke a Template++[`record-array-pattern-holes.firmament`](../../fixtures/FirmamentV2/Canonical/valid/record-array-pattern-holes.firmament) demonstrates typed Records, a static array, a Template, and `Pattern ... Over`:++```powershell+aetheris build fixtures/FirmamentV2/Canonical/valid/record-array-pattern-holes.firmament --output artifacts/pattern.step --json+```++Continue with [geometry](firmament/geometry.md), [materials](firmament/materials.md), [PMI](firmament/pmi.md), [Sheet Metal](firmament/sheet-metal.md), [FEA](firmament/fea.md), [STEP import](firmament/step-import.md), or [Forge interop](forge/interop.md).diff --git a/docs/public/reference/cli.md b/docs/public/reference/cli.mdnew file mode 100644index 00000000..3f02bc80--- /dev/null+++ b/docs/public/reference/cli.md@@ -0,0 +1,16 @@+# CLI reference++Primary public commands:++| Command | Purpose |+|---|---|+| `validate <file> [--json]` | Parse, bind, check units/targets/static semantics without geometry |+| `build <file> [--output path] [--json]` | Materialize and export exact STEP AP242 |+| `inspect <firmament-or-step> [--json]` | Inspect source semantics or route STEP to analysis |+| `analyze <step> [--json]` | Reinspect topology, surfaces, bounds, manifold state, and PMI |+| `view <file>` | Open in bundled Cadmata |+| `fea <file> --out-dir dir [--json]` | Compile and solve the bounded linear-elastic analysis |+| `sheetmetal ...` | Inspect, recognize, recover, compare, or flatten Sheet Metal |+| `asm ...` | Inspect/execute/import/export assemblies |++Run `aetheris <command> --help` for exact options. JSON is a public automation surface: `success` reflects the command result; diagnostics are structured; artifact paths are explicit; Sheet Metal reports regions, bends, and lowered features separately; FEA reports requested/result artifacts; builds report emitted features and PMI export evidence. Counts describe semantic items at the stated layer, not arbitrary STEP entity counts.diff --git a/docs/public/reference/diagnostics.md b/docs/public/reference/diagnostics.mdnew file mode 100644index 00000000..a88816be--- /dev/null+++ b/docs/public/reference/diagnostics.md@@ -0,0 +1,22 @@+# Diagnostics and failure recovery++Start with `aetheris validate source.firmament --json`; use `build` when geometry, AP242, assertions, or artifacts are involved. A diagnostic code is the stable automation key, while its message identifies the value/target and expected category where useful.++Common recovery patterns:++| Failure | What to check |+|---|---|+| unknown keyword/Template | spelling, `Use` declaration, and qualified Template name |+| missing Template argument | the Template's typed parameter list or Forge `describe` output |+| unit mismatch | use the required dimension (`mm`, `deg`, `N`) rather than a bare/wrong-dimension value |+| unknown material | one of the four exact catalog references in the materials guide |+| unresolved PMI target | named hole/face selector exists in the same semantic domain |+| invalid tolerance | `PlusMinus(plus, minus)` uses Length values for a diameter |+| Sheet Metal region mismatch | use a named planar region such as `Base`, not `face(+Z)` |+| `sheetmetal-hole-domain-syntax` | replace Model `Hole<Shaft>` with Sheet Metal `Hole Name` syntax |+| `sheetmetal-pmi-domain-syntax` | use `Manufacturing` plus `DatumFeature` targeting a named Sheet Metal region |+| inlineSTEP file/face failure | resolve the file relative to the source and use an existing AP242 face identity |+| empty FEA selection | selected face exists and intersects occupied cut cells at the requested lattice |+| unsupported constitutive model | Preview 3 production scope is linear elastic isotropic |++Successful builds enforce PMI/AP242 parity. `firmament-v2-pmi-export-evidence-mismatch` means a supported record failed independent export reinspection; no artifact is written. See [targets](targets.md) for cross-domain forms.diff --git a/docs/public/reference/supported-features.md b/docs/public/reference/supported-features.mdnew file mode 100644index 00000000..c5563e34--- /dev/null+++ b/docs/public/reference/supported-features.md@@ -0,0 +1,23 @@+# Preview 3 supported features++`Supported` means a qualified public path. `Bounded` means the documented subset is production-tested. `Experimental` is usable evidence without a general product promise. `Not in Preview 3` is intentionally deferred.++| Area | Status | Preview 3 boundary |+|---|---|---|+| Firmament V2 primitives/profiles | Bounded | Named Box/Cylinder/Frustum/RoundedBox and admitted line/arc profile construction/composition |+| Semantic holes, slots, patterns | Bounded | Qualified shaft/counterbore/countersink and finite static pattern routes; no stable generated-instance selector |+| Edge finishes/hollow/lattice | Bounded | Documented admitted chamfer/fillet, hollow, and cubic-truss routes; not arbitrary topology |+| Templates/Records/Static/Tables | Supported | Typed compile-time specialization, finite data, `with`, and `Require` |+| STEP AP242 export | Bounded | Deterministic single-body routes plus semantic PMI; unsupported intent fails loudly |+| STEP import / inlineSTEP | Bounded | Canonical single-body topology and recognized identities; arbitrary containment and multi-root bodies are not native-part promises |+| PMI authoring | Bounded | Plane Datum and toleranced shaft HoleDiameter AP242 export; broader PMI families are deferred |+| Sheet Metal authoring | Bounded | Base/flanges/bends/holes/cuts, formed STEP, flat STEP/SVG, K-factor, DFM, semantic regions |+| Sheet Metal reconstruction | Experimental | Bounded recognition/recovery with explicit partial status and evidence |+| Materials | Supported | Four deployed Standard Library catalog entries |+| FEA | Bounded | LinearElasticIsotropic cut-cell/vector-lattice, Fixed, total-resultant Force, four result families; no nonlinear/contact/dynamics |+| Forge Protocol v1 | Supported | List/describe/invoke embedded public templates; process JSON and file artifacts |+| Cadmata | Bounded | Geometry inspection, selection, semantic PMI presentation and filtering |+| Assemblies | Bounded | Typed Firmament assembly inspection plus explicitly identified legacy `.firmasm` compatibility |+| Platform qualification | Supported | Windows x64 bundle; NativeAOT Forge Host on `win-x64` |+| Linux/macOS release binaries | Not in Preview 3 | Framework logic tests do not constitute binary qualification |+| New geometry/PMI/FEA/Forge families | Not in Preview 3 | Feature-frozen until after Preview 3 |diff --git a/docs/public/reference/targets.md b/docs/public/reference/targets.mdnew file mode 100644index 00000000..5d896c15--- /dev/null+++ b/docs/public/reference/targets.md@@ -0,0 +1,15 @@+# Target and selector reference++Selectors are domain-specific because their semantic models are different.++| Domain | Typical verified form | Example | Used by |+|---|---|---|---|+| Native `Model` geometry | axis face or exposed semantic selector | `+Z`, `face(+Z)`, `Bracket.Outer` | Hole, EdgeFinish, PMI |+| `SheetMetal` | named semantic planar region/path | `On: Base`, `From: Base.Rear` | holes/cuts, flanges, patterns |+| Native FEA | body axis face | `beam.face(-X)` | Fixed, Force |+| Imported STEP / FEA | imported AP242 face identity | `body.face(#170)` | Fixed, Force, bounded PMI |+| Assembly | typed role, port, interface, or DatumFrame references | `Lid.Datums.BodySeat` | mates, fit/placement |++In a native `Model`, hole `On: +Z` selects an entry face while PMI `Target: face(+Z)` selects a datum plane; a named hole is the target of `HoleDiameter`. In Sheet Metal, `face(-Z)` is not a planar-region name and `Hole<Shaft>` is not the hole declaration form. Assembly `.firmasm` has a separate typed relationship model and does not publish Model face selectors as a universal convention.++Raw internal B-rep identifiers are not stable native selectors. `#170` is allowed only as identity from imported STEP, not as a native topology ID invented by an author.diff --git a/docs/release/PREVIEW3-HARDEN-A2.md b/docs/release/PREVIEW3-HARDEN-A2.mdnew file mode 100644index 00000000..4f46ad64--- /dev/null+++ b/docs/release/PREVIEW3-HARDEN-A2.md@@ -0,0 +1,86 @@+# PREVIEW3-HARDEN-A2 — Firmament first-user and public-documentation hardening++> Development hardening report. This records reproduction and release evidence; it is not the user manual. The authoritative public Preview 3 documentation begins at [`docs/public`](../public/README.md).++## Outcome++A2 reached Success. The confirmed PMI loss is repaired at its combined materializer route and guarded at the build boundary by independent AP242 semantic reinspection. Sheet Metal's reported feature undercount was traced to Model-domain syntax being silently ignored, not to a generated hole omitted from the count; canonical syntax reports the feature, and wrong-domain authoring now fails with a corrective diagnostic. Public documentation, fixture-backed qualification, and a compact public/development boundary are in place.++No new geometry, PMI, Sheet Metal, FEA, Forge, or Cadmata feature family was introduced.++## Claude finding classification++| Finding | Reproduction and architectural result | Classification | Resolution |+|---|---|---|---|+| A — PMI + EdgeFinish | Confirmed. `CombinedHoleEdgeFinish` called `Step242Exporter.ExportBody(body)` without semantic PMI and returned empty inspection arrays. Validate admitted 3 supported records while build emitted 0. | ReleaseBlocker | The route now validates support, builds PMI from the same lowered holes, passes it to AP242, and reports record names. A global build/CompileSource parity gate uses `Step242SemanticPmiInspector`; mismatch fails with `firmament-v2-pmi-export-evidence-mismatch` before writing an artifact. |+| B — Counterbore PMI | Existing intended behavior works. `HoleDiameter` targets the counterbore's shaft `Diameter`; the distinct `CounterboreDiameter` has no separate Preview 3 PMI kind. The qualified profile-compose fixture validates, exports, reinspects, and deterministically reimports. The Claude literal used malformed/ambiguous syntax. | DocsFix | Documented the shaft meaning and retained the executable counterbore regression. No syntax was added. |+| C — Sheet Metal PMI target | Model `Datum` and `face(-Z)` are the wrong semantic domain. Sheet Metal manufacturing PMI uses `Manufacturing`, `DatumFeature`, and a named sheet region. The old error came from semantic-layout parsing and mentioned `<missing>`. | MustFix / DocsFix | Added `sheetmetal-pmi-domain-syntax` with the canonical form and documented cross-domain targets. |+| D — pattern holes + PMI | Pattern holes build through the composite hole materializer; PMI can coexist. Generated names such as `MountPattern_0` exist in reports, but no stable public per-instance selector/quantity-PMI authoring family is promised. | DocumentForPreview | Qualified the pattern fixture and documented the boundary; no instance-selection feature added. |+| E — Sheet Metal `features: 0` | Canonical `Hole Mount` lowers to one `SheetFeatureIr`, reports `features: 1`, and produces a third cylindrical surface beyond the two bend cylinders. `Hole<Shaft>` was ignored, so bend cylinders/circles were mistaken for hole evidence. | MustFix | Model-domain `Hole<Shaft>` now fails with `sheetmetal-hole-domain-syntax`; canonical count/topology are regression-tested. |+| F — FEA witness | Reproduced with a new A36 source: 100 × 30 × 15 mm, 500 N, `[16,2,2]`; result `25.0619 µm`, beam-theory sanity value about `24.7 µm`, converged with sub-nanonewton equilibrium residual. | DocsFix (positive witness) | Preserved as bounded public credibility evidence without general solver claims. |+| G — Forge interop | Protocol tests and the checked-in public request produce STEP AP242, flat STEP, and SVG. Protocol logic is language-neutral; release NativeAOT qualification remains `win-x64`. | DocsFix (positive witness) | Public guide reduces the model to list/describe/invoke, links all four tiny clients, and states the RID boundary. |++Claude's proposed build-result diff command remains DeferredPostPreview3 because it is a new CLI capability. The parity gate and structured evidence cover the release-safety requirement without broadening the CLI family.++## Controlled PMI matrix++The minimized fixtures were run through real `aetheris validate`, `build --json`, raw STEP inspection, semantic PMI inspection, STEP reimport, and deterministic reruns:++| Case | Validate supported PMI | Build evidence | Raw/reinspection result |+|---|---:|---:|---|+| hole + PMI (`box-hole-pmi`) | 2 | 1 datum + 1 diameter | 1 datum + 1 diameter |+| hole + EdgeFinish (`box-hole-chamfer`) | 0 | none expected | one reimportable manifold body, hole + chamfer |+| two holes + PMI + EdgeFinish (`box-holes-pmi-chamfer`) | 3 | 1 datum + 2 diameters | 1 datum + 2 diameters; two cylinders; deterministic STEP hash `B029BF44A31D90217FC7450AF69EA9C2FF7C7E155F2249A26DFF3BD85D253966` |++The parity comparison is semantic-record-level. It does not assume one PMI record equals one STEP entity.++## Truthfulness and diagnostics audit++- Successful V2 file builds and in-memory Forge/assembly compilation now reparse requested PMI, reject deferred export, reinspect emitted AP242, and require exact supported datum/diameter counts.+- PMI evidence now uses the authored PMI record name rather than falling back to the target hole name.+- Successful validation no longer exposes parser trace events (`parser-invoked`, `parse-succeeded`, `*-parsed`) as warnings; the clean controlled fixture reports an empty diagnostic array and zero warning count.+- Canonical Sheet Metal summary semantics are explicit: `features` is lowered cuts/openings; bends are separate. Wrong Model hole syntax and wrong Model PMI syntax fail before lowering.+- Existing Template binder, material lookup, inlineSTEP, FEA selection/constitutive, Forge request, and deferred PMI tests cover the other audited silent-success priorities. No new silent omission was reproduced on qualified public fixtures.++## Public documentation boundary++`docs/public` now contains the authoritative landing page, Getting Started, Firmament overview/syntax/geometry/Templates/materials/PMI/Sheet Metal/FEA/STEP import, Forge interop, Cadmata/PMI, CLI/targets/diagnostics, and one Preview 3 support matrix. Root README is a short product landing page. `docs/development/README.md` labels historical and internal documentation without reorganizing or rewriting the archive.++Every public workflow links to a checked-in source fixture. Relative-link qualification rejects broken or escaping links. Terms and platform claims use the Preview 3 release manifest: Windows x64, NativeAOT Forge Host only on `win-x64`, and no Linux/macOS release-binary implication.++## Fresh-user and AI-author dogfood++The automated public-only path performs: first STEP build, typed Template/pattern build, catalog-material FEA, PMI + EdgeFinish AP242 build/reinspection, Sheet Metal formed/flat STEP and SVG, native FEA, inlineSTEP FEA, and the public Forge request. No test reads a milestone report or implementation document.++An AI-style authoring pass using only the public syntax/target/material pages produced three new first-attempt sources under `fixtures/FirmamentV2/PublicDogfood`: a native Model, a Sheet Metal bracket, and the A36 FEA cantilever. All three parsed and ran on first attempt, with zero syntax guesses after selecting the correct domain page and no hidden documentation lookup. The deliberately wrong Sheet Metal Model hole and datum forms recovered in one diagnostic cycle via the new named errors.++## Regression coverage++- combined two-hole + EdgeFinish + three-record PMI, deterministic AP242 and semantic reinspection+- CLI validate/build PMI evidence parity and authored record names+- working counterbore shaft-diameter PMI through composed/chamfered geometry+- canonical Sheet Metal hole feature count plus independent surface-family evidence+- loud Model-hole and Model-PMI syntax failures in Sheet Metal+- public Markdown relative-link integrity+- fixture-backed Model, Template, material, PMI, Sheet Metal, native/imported FEA examples+- checked-in Forge Host Protocol request and all artifact kinds++## Remaining Preview 3 limitations++- Per-instance selectors and quantity PMI for generated patterns are not a public family.+- There is no separate counterbore-diameter PMI record kind; `HoleDiameter` means shaft diameter.+- Sheet Metal uses semantic regions and manufacturing PMI forms, not universal Model face selectors.+- inlineSTEP and Sheet Metal reconstruction remain bounded; arbitrary imported containment is rejected.+- Production FEA is linear elastic isotropic only.+- Forge Host NativeAOT and the release bundle are qualified on Windows x64 only.+- A result-diff CLI command remains post-Preview 3.++## Validation++- Release build: pass, 0 warnings and 0 errors.+- Full serial .NET suite (`Category!=SlowCorpus`): 2,970 passed, 0 failed. The legacy FrictionLab project has no tests in this default filter and remains explicitly opt-in under repository policy.+- Focused public/diagnostic qualification: 15/15 passed before the full run; the same tests are included in the CLI total.+- Cadmata TSPack: policy check exit 0 (21 multi-version dependency and 114 acknowledged/blocked lifecycle-script notices), typecheck pass, 81/81 tests, production build pass, lint pass.+- Forge four-language witness: Python, Go, Rust, and TypeScript produced byte-identical STEP/flat STEP/SVG hashes (`114cd7c0...`, `88c43737...`, `1657e3bb...`).+- Real CLI validate/build/analyze matrix, A36 FEA witness, relative public-link qualification, and deterministic PMI rerun: pass.+- `git diff --check`: pass; line-ending conversion notices only.diff --git a/fixtures/FirmamentV2/Canonical/valid/box-holes-pmi-chamfer.firmament b/fixtures/FirmamentV2/Canonical/valid/box-holes-pmi-chamfer.firmamentnew file mode 100644index 00000000..3e348a96--- /dev/null+++ b/fixtures/FirmamentV2/Canonical/valid/box-holes-pmi-chamfer.firmament@@ -0,0 +1,24 @@+Model MountingPlate {+ Units: mm+ Box Plate { Size: [80mm, 50mm, 8mm] }+ Modify Plate {+ Hole<Shaft> MountLeft { On: +Z Center: Point2(-25mm, 0mm) Diameter: 8mm End: ThroughAll }+ Hole<Shaft> MountRight { On: +Z Center: Point2(25mm, 0mm) Diameter: 8mm End: ThroughAll }+ EdgeFinish TopBreak { Face: +Z Target: Boundary Kind: Chamfer Distance: 1mm }+ }+ Pmi {+ Datum A { Target: face(+Z) }+ HoleDiameter MountLeftDiameter {+ Target: MountLeft+ Value: 8mm+ Tolerance: PlusMinus(0.10mm, 0.00mm)+ DatumRefs: [A]+ }+ HoleDiameter MountRightDiameter {+ Target: MountRight+ Value: 8mm+ Tolerance: PlusMinus(0.10mm, 0.00mm)+ DatumRefs: [A]+ }+ }+}diff --git a/fixtures/FirmamentV2/PublicDogfood/ai-fea-a36-cantilever.firmament b/fixtures/FirmamentV2/PublicDogfood/ai-fea-a36-cantilever.firmamentnew file mode 100644index 00000000..85b28327--- /dev/null+++ b/fixtures/FirmamentV2/PublicDogfood/ai-fea-a36-cantilever.firmament@@ -0,0 +1,19 @@+Model SteelCantilever {+ Units: mm+ solid beam: Box { size: [100, 30, 15] }++ Analysis LinearElastic ServiceLoad {+ body: beam+ material: Standard.Materials.Steel.ASTM_A36+ Fixed Root {+ region: beam.face(-X)+ components: [X, Y, Z]+ }+ Force Tip {+ region: beam.face(+X)+ vector: [0N, -500N, 0N]+ }+ results: [Displacement, Strain, Stress, ReactionForce]+ lattice: [16, 2, 2]+ }+}diff --git a/fixtures/FirmamentV2/PublicDogfood/ai-model.firmament b/fixtures/FirmamentV2/PublicDogfood/ai-model.firmamentnew file mode 100644index 00000000..ddc8dc61--- /dev/null+++ b/fixtures/FirmamentV2/PublicDogfood/ai-model.firmament@@ -0,0 +1,7 @@+Model InspectionBlock {+ Units: mm+ Box Body { Size: [60mm, 40mm, 12mm] }+ Modify Body {+ Hole<Shaft> Mount { On: +Z Center: Point2(0mm, 0mm) Diameter: 6mm End: ThroughAll }+ }+}diff --git a/fixtures/FirmamentV2/PublicDogfood/ai-sheet-metal.firmament b/fixtures/FirmamentV2/PublicDogfood/ai-sheet-metal.firmamentnew file mode 100644index 00000000..88443391--- /dev/null+++ b/fixtures/FirmamentV2/PublicDogfood/ai-sheet-metal.firmament@@ -0,0 +1,18 @@+SheetMetal SensorBracket {+ Thickness: 1.5mm;+ Material: "5052-H32 Aluminum";+ KFactor: 0.42;+ Base: Rectangle(70mm, 45mm);+ Flange Upright {+ From: Base.Rear;+ Length: 25mm;+ Angle: 90deg;+ InsideRadius: 2mm;+ Direction: Up;+ }+ Hole Mount {+ On: Base;+ Center: (35mm, 18mm);+ Diameter: 6mm;+ }+}diff --git a/fixtures/FirmamentV2/SheetMetal/preview3-l-bracket-hole.firmament b/fixtures/FirmamentV2/SheetMetal/preview3-l-bracket-hole.firmamentnew file mode 100644index 00000000..a81162b4--- /dev/null+++ b/fixtures/FirmamentV2/SheetMetal/preview3-l-bracket-hole.firmament@@ -0,0 +1,21 @@+SheetMetal MountingBracket {+ Thickness: 1.5mm;+ Material: "5052-H32 Aluminum";+ KFactor: 0.42;++ Base: Rectangle(80mm, 50mm);++ Flange Upright {+ From: Base.Rear;+ Length: 30mm;+ Angle: 90deg;+ InsideRadius: 2mm;+ Direction: Up;+ }++ Hole Mount {+ On: Base;+ Center: (40mm, 20mm);+ Diameter: 8mm;+ }+}