Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Expose versioned Firmament semantic schemas through the language API

Yuechen Li542cd4ab6ecb
diff --git a/Aetheris.Firmament.SchemaGenerator/Aetheris.Firmament.SchemaGenerator.csproj b/Aetheris.Firmament.SchemaGenerator/Aetheris.Firmament.SchemaGenerator.csproj
new file mode 100644
index 00000000..75025f2d
--- /dev/null
+++ b/Aetheris.Firmament.SchemaGenerator/Aetheris.Firmament.SchemaGenerator.csproj
@@ -0,0 +1,13 @@
+<Project Sdk="Microsoft.NET.Sdk">
+ <PropertyGroup>
+ <TargetFramework>netstandard2.0</TargetFramework>
+ <LangVersion>latest</LangVersion>
+ <Nullable>enable</Nullable>
+ <IsRoslynComponent>true</IsRoslynComponent>
+ <EnforceExtendedAnalyzerRules>true</EnforceExtendedAnalyzerRules>
+ </PropertyGroup>
+ <ItemGroup>
+ <PackageReference Include="Microsoft.CodeAnalysis.CSharp" Version="4.14.0" PrivateAssets="all" />
+ <AdditionalFiles Include="AnalyzerReleases.Unshipped.md" />
+ </ItemGroup>
+</Project>
diff --git a/Aetheris.Firmament.SchemaGenerator/AnalyzerReleases.Unshipped.md b/Aetheris.Firmament.SchemaGenerator/AnalyzerReleases.Unshipped.md
new file mode 100644
index 00000000..319ef395
--- /dev/null
+++ b/Aetheris.Firmament.SchemaGenerator/AnalyzerReleases.Unshipped.md
@@ -0,0 +1,5 @@
+### New Rules
+
+Rule ID | Category | Severity | Notes
+--------|----------|----------|------
+FMS001 | Firmament schema | Error | Invalid semantic schema declaration
diff --git a/Aetheris.Firmament.SchemaGenerator/IsExternalInit.cs b/Aetheris.Firmament.SchemaGenerator/IsExternalInit.cs
new file mode 100644
index 00000000..49f64593
--- /dev/null
+++ b/Aetheris.Firmament.SchemaGenerator/IsExternalInit.cs
@@ -0,0 +1,2 @@
+namespace System.Runtime.CompilerServices;
+internal static class IsExternalInit { }
diff --git a/Aetheris.Firmament.SchemaGenerator/SemanticSchemaGenerator.cs b/Aetheris.Firmament.SchemaGenerator/SemanticSchemaGenerator.cs
new file mode 100644
index 00000000..9c866910
--- /dev/null
+++ b/Aetheris.Firmament.SchemaGenerator/SemanticSchemaGenerator.cs
@@ -0,0 +1,107 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Text;
+using Microsoft.CodeAnalysis;
+using Microsoft.CodeAnalysis.CSharp;
+
+namespace Aetheris.Firmament.SchemaGenerator;
+
+[Generator]
+public sealed class SemanticSchemaGenerator : IIncrementalGenerator
+{
+ private static readonly DiagnosticDescriptor Invalid = new("FMS001", "Invalid Firmament schema", "{0}",
+ "Firmament schema", DiagnosticSeverity.Error, true);
+ private static readonly HashSet<string> Kinds = new(StringComparer.Ordinal)
+ { "Length", "Angle", "Scalar", "Count", "Boolean", "String", "Choice", "Vector", "Point", "Profile", "ConstructionPlane", "FaceSelector", "BodySelector", "ConstructReference", "Box3", "TypeRequirement" };
+
+ public void Initialize(IncrementalGeneratorInitializationContext context)
+ {
+ var declarations = context.SyntaxProvider.ForAttributeWithMetadataName(
+ "Aetheris.Kernel.Firmament.FirmamentV2.FirmamentConstructAttribute",
+ static (node, _) => node is Microsoft.CodeAnalysis.CSharp.Syntax.ClassDeclarationSyntax,
+ static (ctx, _) => (INamedTypeSymbol)ctx.TargetSymbol);
+ context.RegisterSourceOutput(declarations.Collect(), static (output, symbols) => Generate(output, symbols));
+ }
+
+ private static void Generate(SourceProductionContext output, System.Collections.Immutable.ImmutableArray<INamedTypeSymbol> symbols)
+ {
+ var entries = new List<Entry>();
+ var constructIds = new HashSet<string>(StringComparer.Ordinal);
+ var names = new HashSet<string>(StringComparer.Ordinal);
+ foreach (var symbol in symbols.OrderBy(s => s.ToDisplayString(), StringComparer.Ordinal))
+ {
+ var construct = symbol.GetAttributes().Single(a => a.AttributeClass?.Name == "FirmamentConstructAttribute");
+ var id = Arg(construct, 0); var name = Arg(construct, 1);
+ if (!ValidId(id) || !ValidId(name) || !constructIds.Add(id) || !names.Add(name))
+ { Error(output, symbol, $"construct '{name}' needs a unique, nonempty stable ID and name"); continue; }
+ var fields = new List<Field>();
+ var outputs = new List<Output>();
+ var fieldIds = new HashSet<string>(StringComparer.Ordinal);
+ var fieldNames = new HashSet<string>(StringComparer.Ordinal);
+ var outputIds = new HashSet<string>(StringComparer.Ordinal);
+ foreach (var attribute in symbol.GetAttributes())
+ {
+ if (attribute.AttributeClass?.Name == "FirmamentFieldAttribute")
+ {
+ var fieldId = Arg(attribute, 0); var fieldName = Arg(attribute, 1);
+ var kind = attribute.ConstructorArguments[2].Value is int value ? EnumName(attribute.ConstructorArguments[2], value) : "";
+ var unitConstant = Named(attribute, "Unit");
+ var unit = unitConstant.Value is int unitValue ? EnumName(unitConstant, unitValue) : kind == "Length" ? "Length" : kind == "Angle" ? "Angle" : "None";
+ var choiceConstant = Named(attribute, "Choices");
+ var choices = choiceConstant.Kind == TypedConstantKind.Array ? choiceConstant.Values.Select(v => v.Value?.ToString() ?? "").ToArray() : Array.Empty<string>();
+ if (!ValidId(fieldId) || !ValidId(fieldName) || !fieldIds.Add(fieldId) || !fieldNames.Add(fieldName) || !Kinds.Contains(kind)
+ || kind == "Choice" && choices.Length == 0 || kind != "Choice" && choices.Length != 0
+ || unit is not ("None" or "Length" or "Angle")
+ || kind == "Length" && unit != "Length" || kind == "Angle" && unit != "Angle"
+ || kind is not ("Length" or "Angle" or "Vector" or "Point") && unit != "None")
+ { Error(output, symbol, $"field '{fieldName}' in {name} has a duplicate/missing ID, unsupported kind, or invalid choices"); continue; }
+ fields.Add(new(fieldId, fieldName, kind, unit, Bool(attribute, "Required"), Str(attribute, "Default"), Str(attribute, "Description"), choices));
+ }
+ else if (attribute.AttributeClass?.Name == "FirmamentOutputAttribute")
+ {
+ var outputId = Arg(attribute, 0); var outputName = Arg(attribute, 1); var outputKind = Arg(attribute, 2);
+ if (!ValidId(outputId) || !ValidId(outputName) || !outputIds.Add(outputId))
+ { Error(output, symbol, $"output '{outputName}' in {name} has a duplicate/missing ID"); continue; }
+ outputs.Add(new(outputId, outputName, outputKind, Bool(attribute, "SourceAddressable"), Str(attribute, "SourceRole")));
+ }
+ }
+ entries.Add(new(id, name, Str(construct, "Context"), Str(construct, "Entry"), Str(construct, "Description"), Str(construct, "CompatibilityAlias"), fields.OrderBy(f => f.Id, StringComparer.Ordinal).ToArray(), outputs.OrderBy(o => o.Id, StringComparer.Ordinal).ToArray()));
+ }
+ entries.Sort((a, b) => StringComparer.Ordinal.Compare(a.Id, b.Id));
+ var source = new StringBuilder("// <auto-generated/>\n#nullable enable\nnamespace Aetheris.Kernel.Firmament.FirmamentV2;\npublic static class FirmamentSemanticSchemas\n{\n");
+ source.Append(" public const string Version = \"firmament-semantic-schema/1\";\n");
+ source.Append(" public static readonly System.Collections.Generic.IReadOnlyList<FirmamentConstructSchema> All = System.Array.AsReadOnly(new FirmamentConstructSchema[]\n {\n");
+ foreach (var entry in entries)
+ {
+ source.Append(" new(new FirmamentConstructId(").Append(Q(entry.Id)).Append("), ").Append(Q(entry.Name)).Append(", ").Append(Q(entry.Context)).Append(", ").Append(Q(entry.Snippet)).Append(", ").Append(Q(entry.Description)).Append(", ").Append(Q(entry.Alias)).Append(",\n System.Array.AsReadOnly(new FirmamentFieldSchema[] {\n");
+ foreach (var field in entry.Fields)
+ {
+ source.Append(" new(new FirmamentFieldId(").Append(Q(entry.Id + "." + field.Id)).Append("), ").Append(Q(field.Name)).Append(", FirmamentSchemaValueKind.").Append(field.Kind).Append(", FirmamentUnitKind.").Append(field.Unit).Append(", ").Append(field.Required ? "true" : "false").Append(", ").Append(Q(field.Default)).Append(", System.Array.AsReadOnly(new string[] { ").Append(string.Join(", ", field.Choices.Select(Q))).Append(" }), ").Append(Q(field.Description)).Append(", true),\n");
+ }
+ source.Append(" }), System.Array.AsReadOnly(new FirmamentOutputSchema[] {\n");
+ foreach (var item in entry.Outputs)
+ source.Append(" new(new FirmamentOutputId(").Append(Q(entry.Id + "." + item.Id)).Append("), ").Append(Q(item.Name)).Append(", ").Append(Q(item.Kind)).Append(", ").Append(item.Addressable ? "true" : "false").Append(", ").Append(Q(item.Role)).Append("),\n");
+ source.Append(" })),\n");
+ }
+ source.Append(" });\n public static FirmamentConstructSchema? Get(string name) => System.Linq.Enumerable.FirstOrDefault(All, x => x.Name == name);\n}\n");
+ output.AddSource("FirmamentSemanticSchemas.g.cs", source.ToString());
+ }
+
+ private static string EnumName(TypedConstant constant, int value) => constant.Type?.GetMembers().OfType<IFieldSymbol>().FirstOrDefault(f => f.HasConstantValue && f.ConstantValue is int i && i == value)?.Name ?? "";
+ private static string Arg(AttributeData attribute, int index) => attribute.ConstructorArguments[index].Value?.ToString() ?? "";
+ private static TypedConstant Named(AttributeData attribute, string name) => attribute.NamedArguments.FirstOrDefault(p => p.Key == name).Value;
+ private static string? Str(AttributeData attribute, string name) => Named(attribute, name).Value?.ToString();
+ private static bool Bool(AttributeData attribute, string name) => Named(attribute, name).Value is true;
+ private static bool ValidId(string value) => !string.IsNullOrWhiteSpace(value) && value.All(c => char.IsLetterOrDigit(c) || c == '_');
+ private static string Q(string? value) => value is null ? "null" : SymbolDisplay.FormatLiteral(value, true);
+ private static void Error(SourceProductionContext output, INamedTypeSymbol symbol, string message) => output.ReportDiagnostic(Diagnostic.Create(Invalid, symbol.Locations.FirstOrDefault(), message));
+
+ private sealed record Entry(string Id, string Name, string? Context, string? Snippet, string? Description, string? Alias, Field[] Fields, Output[] Outputs);
+ private sealed record Field(string Id, string Name, string Kind, string Unit, bool Required, string? Default, string? Description, string[] Choices);
+ private sealed record Output(string Id, string Name, string Kind, bool Addressable, string? Role);
+}
+
+
+
+
diff --git a/Aetheris.Kernel.Firmament.Tests/Aetheris.Kernel.Firmament.Tests.csproj b/Aetheris.Kernel.Firmament.Tests/Aetheris.Kernel.Firmament.Tests.csproj
index 2cd42219..83e2c038 100644
--- a/Aetheris.Kernel.Firmament.Tests/Aetheris.Kernel.Firmament.Tests.csproj
+++ b/Aetheris.Kernel.Firmament.Tests/Aetheris.Kernel.Firmament.Tests.csproj
@@ -36,6 +36,7 @@
<PackageReference Include="coverlet.collector" Version="6.0.0" />
<PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.11.1" />
<PackageReference Include="DocumentFormat.OpenXml" Version="3.3.0" />
+ <PackageReference Include="Microsoft.CodeAnalysis.CSharp" Version="4.14.0" />
<PackageReference Include="xunit" Version="2.9.2" />
<PackageReference Include="xunit.runner.visualstudio" Version="2.8.2" />
</ItemGroup>
@@ -46,6 +47,7 @@
<ItemGroup>
<ProjectReference Include="..\Aetheris.Kernel.Firmament\Aetheris.Kernel.Firmament.csproj" />
+ <ProjectReference Include="..\Aetheris.Firmament.SchemaGenerator\Aetheris.Firmament.SchemaGenerator.csproj" />
<ProjectReference Include="..\Aetheris.Surfacing\Aetheris.Surfacing.csproj" />
<ProjectReference Include="..\Aetheris.Kernel.Core\Aetheris.Kernel.Core.csproj" />
<ProjectReference Include="..\Aetheris.Firmament.FrictionLab\Aetheris.Firmament.FrictionLab.csproj" />
diff --git a/Aetheris.Kernel.Firmament.Tests/FirmamentSemanticSchemaTests.cs b/Aetheris.Kernel.Firmament.Tests/FirmamentSemanticSchemaTests.cs
new file mode 100644
index 00000000..449948d6
--- /dev/null
+++ b/Aetheris.Kernel.Firmament.Tests/FirmamentSemanticSchemaTests.cs
@@ -0,0 +1,55 @@
+using Aetheris.Kernel.Firmament.FirmamentV2;
+
+namespace Aetheris.Kernel.Firmament.Tests;
+
+public sealed class FirmamentSemanticSchemaTests
+{
+ [Fact]
+ public void GeneratedRegistry_IsStableOptInAndCoversFirstConstructs()
+ {
+ Assert.Equal("firmament-semantic-schema/1", FirmamentSemanticSchemas.Version);
+ Assert.Equal(["Box", "Concept", "Helix", "Hole", "Loft"], FirmamentSemanticSchemas.All.Select(s => s.Name));
+ var hole = Assert.IsType<FirmamentConstructSchema>(FirmamentSemanticSchemas.Get("Hole"));
+ var diameter = Assert.Single(hole.Fields, f => f.Name == "Diameter");
+ Assert.Equal("Hole.Diameter", diameter.Id.Value);
+ Assert.Equal(FirmamentSchemaValueKind.Length, diameter.Kind);
+ Assert.Equal(FirmamentUnitKind.Length, diameter.Unit);
+ Assert.True(diameter.Required);
+ var wall = Assert.Single(hole.Outputs);
+ Assert.Equal("Hole.Wall", wall.Id.Value);
+ Assert.Equal("HoleWallFace", wall.SourceRole);
+ Assert.True(wall.SourceAddressable);
+ }
+
+ [Fact]
+ public void ExistingLanguageHelp_ConsumesGeneratedHelixAndLoftFields()
+ {
+ var helix = FirmamentSemanticSchemas.Get("Helix")!;
+ Assert.Equal("WireForm", helix.Context);
+ Assert.Equal("AxisCoil", helix.CompatibilityAlias);
+ Assert.Equal(helix.Fields.Select(f => f.Name), FirmamentSchemaAuthoringFields.For("Helix").Select(f => f.Name));
+ Assert.Equal(helix.Fields.Select(f => f.Name), LoftOrHelixCompletion("Model M { WireForm Spring { Helix Winding {\n ", "Helix").Fields.Select(f => f.Name));
+
+ var loft = FirmamentSemanticSchemas.Get("Loft")!;
+ Assert.Contains("Loft Body", loft.Entry);
+ Assert.Equal(loft.Fields.Select(f => f.Name), LoftAuthoringParser.SolidFields.Select(f => f.Name));
+ Assert.Equal(loft.Fields.Select(f => f.Name), LoftOrHelixCompletion("Model M { Loft Body {\n ", "Loft").Fields.Select(f => f.Name));
+ }
+
+ [Fact]
+ public void ConceptAndBox_KeepTheirSemanticBoundaries()
+ {
+ Assert.Empty(FirmamentSemanticSchemas.Get("Concept")!.Fields);
+ var box = FirmamentSemanticSchemas.Get("Box")!;
+ Assert.Contains(box.Fields, f => f.Name == "Size" && f.Kind == FirmamentSchemaValueKind.Vector && f.Unit == FirmamentUnitKind.Length);
+ Assert.Contains(box.Fields, f => f.Name == "Bounds" && f.Kind == FirmamentSchemaValueKind.Box3);
+ Assert.All(box.Fields, f => Assert.False(f.Required)); // Size or Bounds is required, not either field alone.
+ }
+
+ private static FirmamentLanguageCompletion LoftOrHelixCompletion(string source, string expected)
+ {
+ var result = FirmamentLanguageService.Complete(source, "draft.firmament", "1", source.Length);
+ Assert.Equal(expected, result.Context);
+ return result;
+ }
+}
diff --git a/Aetheris.Kernel.Firmament.Tests/SemanticSchemaGeneratorTests.cs b/Aetheris.Kernel.Firmament.Tests/SemanticSchemaGeneratorTests.cs
new file mode 100644
index 00000000..f690cbb9
--- /dev/null
+++ b/Aetheris.Kernel.Firmament.Tests/SemanticSchemaGeneratorTests.cs
@@ -0,0 +1,61 @@
+using Aetheris.Firmament.SchemaGenerator;
+using Microsoft.CodeAnalysis;
+using Microsoft.CodeAnalysis.CSharp;
+
+namespace Aetheris.Kernel.Firmament.Tests;
+
+public sealed class FirmamentSchemaGeneratorTests
+{
+ private const string Prelude = """
+ using System;
+ namespace Aetheris.Kernel.Firmament.FirmamentV2 {
+ [AttributeUsage(AttributeTargets.Class)] public sealed class FirmamentConstructAttribute(string id, string name) : Attribute { }
+ [AttributeUsage(AttributeTargets.Class, AllowMultiple = true)] public sealed class FirmamentFieldAttribute(string id, string name, FirmamentSchemaValueKind kind) : Attribute { }
+ public enum FirmamentSchemaValueKind { Length, Angle, Scalar, Count, Boolean, String, Choice, Vector, Point, Profile, ConstructionPlane, FaceSelector, BodySelector, ConstructReference, Box3, TypeRequirement }
+ }
+ """;
+
+ [Fact]
+ public void EquivalentDeclarationOrder_ProducesIdenticalGeneratedSource()
+ {
+ const string a = """
+ [Aetheris.Kernel.Firmament.FirmamentV2.FirmamentConstruct("Box", "Box")]
+ [Aetheris.Kernel.Firmament.FirmamentV2.FirmamentField("Size", "Size", Aetheris.Kernel.Firmament.FirmamentV2.FirmamentSchemaValueKind.Vector)]
+ public class BoxSpec { }
+ [Aetheris.Kernel.Firmament.FirmamentV2.FirmamentConstruct("Hole", "Hole")]
+ public class HoleSpec { }
+ """;
+ const string b = """
+ [Aetheris.Kernel.Firmament.FirmamentV2.FirmamentConstruct("Hole", "Hole")]
+ public class HoleSpec { }
+ [Aetheris.Kernel.Firmament.FirmamentV2.FirmamentConstruct("Box", "Box")]
+ [Aetheris.Kernel.Firmament.FirmamentV2.FirmamentField("Size", "Size", Aetheris.Kernel.Firmament.FirmamentV2.FirmamentSchemaValueKind.Vector)]
+ public class BoxSpec { }
+ """;
+ Assert.Equal(Generate(Prelude + a).Source, Generate(Prelude + b).Source);
+ }
+
+ [Fact]
+ public void DuplicateFieldId_IsCompileTimeError()
+ {
+ const string source = """
+ [Aetheris.Kernel.Firmament.FirmamentV2.FirmamentConstruct("Box", "Box")]
+ [Aetheris.Kernel.Firmament.FirmamentV2.FirmamentField("Size", "Size", Aetheris.Kernel.Firmament.FirmamentV2.FirmamentSchemaValueKind.Vector)]
+ [Aetheris.Kernel.Firmament.FirmamentV2.FirmamentField("Size", "Other", Aetheris.Kernel.Firmament.FirmamentV2.FirmamentSchemaValueKind.Vector)]
+ public class BoxSpec { }
+ """;
+ Assert.Contains(Generate(Prelude + source).Diagnostics, d => d.Id == "FMS001" && d.Severity == DiagnosticSeverity.Error);
+ }
+
+ private static (string Source, IReadOnlyList<Diagnostic> Diagnostics) Generate(string source)
+ {
+ var references = ((string)AppContext.GetData("TRUSTED_PLATFORM_ASSEMBLIES")!).Split(Path.PathSeparator)
+ .Select(path => MetadataReference.CreateFromFile(path));
+ var compilation = CSharpCompilation.Create("SyntheticSchema", [CSharpSyntaxTree.ParseText(source, new CSharpParseOptions(LanguageVersion.Preview))],
+ references, new CSharpCompilationOptions(OutputKind.DynamicallyLinkedLibrary));
+ GeneratorDriver driver = CSharpGeneratorDriver.Create(new SemanticSchemaGenerator());
+ driver = driver.RunGenerators(compilation);
+ var result = Assert.Single(driver.GetRunResult().Results);
+ return (Assert.Single(result.GeneratedSources).SourceText.ToString(), result.Diagnostics);
+ }
+}
diff --git a/Aetheris.Kernel.Firmament/Aetheris.Kernel.Firmament.csproj b/Aetheris.Kernel.Firmament/Aetheris.Kernel.Firmament.csproj
index 906eaea1..cdb4200b 100644
--- a/Aetheris.Kernel.Firmament/Aetheris.Kernel.Firmament.csproj
+++ b/Aetheris.Kernel.Firmament/Aetheris.Kernel.Firmament.csproj
@@ -3,10 +3,13 @@
<TargetFramework>net10.0</TargetFramework>
<ImplicitUsings>enable</ImplicitUsings>
<Nullable>enable</Nullable>
+ <EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles>
+ <CompilerGeneratedFilesOutputPath>$(BaseIntermediateOutputPath)Generated</CompilerGeneratedFilesOutputPath>
<Description>The Firmament V2 parser, compiler, semantic pipeline, assembly, drawing, and review runtime for Aetheris.</Description>
</PropertyGroup>
<ItemGroup>
+ <ProjectReference Include="..\Aetheris.Firmament.SchemaGenerator\Aetheris.Firmament.SchemaGenerator.csproj" OutputItemType="Analyzer" ReferenceOutputAssembly="false" />
<ProjectReference Include="..\Aetheris.Continuum\Aetheris.Continuum.csproj" />
<ProjectReference Include="..\Aetheris.Kernel.Core\Aetheris.Kernel.Core.csproj" />
<ProjectReference Include="..\Aetheris.Semantics\Aetheris.Semantics.csproj" />
diff --git a/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentAuthoringField.cs b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentAuthoringField.cs
index ac81213a..c0194678 100644
--- a/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentAuthoringField.cs
+++ b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentAuthoringField.cs
@@ -4,3 +4,20 @@ namespace Aetheris.Kernel.Firmament.FirmamentV2;
public sealed record FirmamentAuthoringField(
string Name, string Type, bool Required, string Meaning,
string? Default = null, IReadOnlyList<string>? Choices = null);
+
+public static class FirmamentSchemaAuthoringFields
+{
+ private static readonly IReadOnlyDictionary<string, IReadOnlyList<FirmamentAuthoringField>> Cache =
+ FirmamentSemanticSchemas.All.ToDictionary(schema => schema.Name,
+ schema => (IReadOnlyList<FirmamentAuthoringField>)schema.Fields.Select(field => new FirmamentAuthoringField(
+ field.Name, field.Kind switch
+ {
+ FirmamentSchemaValueKind.Choice => "Enum",
+ FirmamentSchemaValueKind.Vector => "Vector3",
+ _ => field.Kind.ToString()
+ }, field.Required, field.Description ?? string.Empty, field.Default,
+ field.Choices.Count == 0 ? null : field.Choices)).ToArray(), StringComparer.Ordinal);
+
+ public static IReadOnlyList<FirmamentAuthoringField> For(string construct) =>
+ Cache.TryGetValue(construct, out var fields) ? fields : [];
+}
diff --git a/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentLanguageService.cs b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentLanguageService.cs
index 9bec47f5..72a9aaa6 100644
--- a/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentLanguageService.cs
+++ b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentLanguageService.cs
@@ -26,7 +26,7 @@ public static class FirmamentLanguageService
string context;
if (WireFormAuthoring.IsInsideHelix(source, offset))
{
- fields = WireFormAuthoring.HelixFields;
+ fields = FirmamentSchemaAuthoringFields.For("Helix");
context = "Helix";
}
else if (LoftAuthoringParser.TryGetAuthoringFields(source, offset, out fields)) context = "Loft";
diff --git a/Aetheris.Kernel.Firmament/FirmamentV2/LoftAuthoringParser.cs b/Aetheris.Kernel.Firmament/FirmamentV2/LoftAuthoringParser.cs
index 15808963..8215c251 100644
--- a/Aetheris.Kernel.Firmament/FirmamentV2/LoftAuthoringParser.cs
+++ b/Aetheris.Kernel.Firmament/FirmamentV2/LoftAuthoringParser.cs
@@ -16,17 +16,7 @@ public static class LoftAuthoringParser
{
private static readonly Regex Header = new(@"\bLoft(?:\s*<\s*(?<kind>Hollow)\s*>)?\s+(?<name>[A-Za-z_]\w*)\s*\{", RegexOptions.CultureInvariant);
- public static readonly IReadOnlyList<FirmamentAuthoringField> SolidFields =
- [
- new("RearProfile", "Profile", true, "Closed rear section profile."),
- new("RearFrame", "ConstructionPlane", true, "Placement of the rear section."),
- new("FrontProfile", "Profile", true, "Closed front section profile."),
- new("FrontFrame", "ConstructionPlane", true, "Placement of the front section."),
- new("Rule", "Enum", true, "Section interpolation rule.", null, ["Ruled"]),
- new("Correspondence", "Enum", true, "Point correspondence between sections.", null, ["CommonRay"]),
- new("Reference", "Vector3", false, "Reference ray for section correspondence."),
- new("Twist", "Angle", false, "Relative section rotation.", "0deg")
- ];
+ public static readonly IReadOnlyList<FirmamentAuthoringField> SolidFields = FirmamentSchemaAuthoringFields.For("Loft");
public static readonly IReadOnlyList<FirmamentAuthoringField> HollowFields =
[.. SolidFields,
new("Thickness", "Length", true, "Hollow wall thickness."),
diff --git a/Aetheris.Kernel.Firmament/FirmamentV2/SemanticConstructDeclarations.cs b/Aetheris.Kernel.Firmament/FirmamentV2/SemanticConstructDeclarations.cs
new file mode 100644
index 00000000..25538b5e
--- /dev/null
+++ b/Aetheris.Kernel.Firmament/FirmamentV2/SemanticConstructDeclarations.cs
@@ -0,0 +1,41 @@
+namespace Aetheris.Kernel.Firmament.FirmamentV2;
+
+// These are opt-in public Firmament surfaces. The parser remains the execution authority.
+[FirmamentConstruct("Box", "Box", Context = "Model or Struct", Entry = "Box Body { Size: [10mm, 10mm, 10mm] }", Description = "Rectangular solid.")]
+[FirmamentField("Size", "Size", FirmamentSchemaValueKind.Vector, Unit = FirmamentUnitKind.Length, Description = "Three lengths for the box dimensions; supply Size or Bounds.")]
+[FirmamentField("Bounds", "Bounds", FirmamentSchemaValueKind.Box3, Description = "A semantic Box3 bound instead of Size.")]
+public static class BoxSemanticDeclaration { }
+
+[FirmamentConstruct("Hole", "Hole", Context = "Modify body", Entry = "Modify Body { Hole<Shaft> H { On: +Z; Center: Point2(0mm, 0mm); Diameter: 6mm; End: ThroughAll } }", Description = "Semantic drilled hole.")]
+[FirmamentField("On", "On", FirmamentSchemaValueKind.FaceSelector, Required = true, Description = "Entry face of the hole.")]
+[FirmamentField("Center", "Center", FirmamentSchemaValueKind.Point, Required = true, Description = "Center in the support face.")]
+[FirmamentField("Diameter", "Diameter", FirmamentSchemaValueKind.Length, Required = true, Description = "Shaft diameter.")]
+[FirmamentField("End", "End", FirmamentSchemaValueKind.String, Required = true, Description = "ThroughAll or a blind termination expression.")]
+[FirmamentField("PatternIdentity", "PatternIdentity", FirmamentSchemaValueKind.String, Description = "Optional pattern identity.")]
+[FirmamentOutput("Wall", "Wall", "Face", SourceAddressable = true, SourceRole = nameof(Materializer.SemanticTopologyRole.HoleWallFace))]
+public static class HoleSemanticDeclaration { }
+
+[FirmamentConstruct("Helix", "Helix", Context = "WireForm", Entry = "WireForm Spring { Diameter: 1mm; Origin: [0mm, 0mm, 0mm]; Tangent: [0, 0, 1]; Up: [0, 1, 0]; Helix Winding { Radius: 5mm; Turns: 4; Pitch: 2mm } }", CompatibilityAlias = "AxisCoil", Description = "WireForm centerline helix.")]
+[FirmamentField("Radius", "Radius", FirmamentSchemaValueKind.Length, Required = true, Description = "Centerline radius.")]
+[FirmamentField("Turns", "Turns", FirmamentSchemaValueKind.Scalar, Required = true, Description = "Number of winding turns.")]
+[FirmamentField("Pitch", "Pitch", FirmamentSchemaValueKind.Length, Description = "Axial distance per turn; supply Pitch or Height.")]
+[FirmamentField("Height", "Height", FirmamentSchemaValueKind.Length, Description = "Total axial span; supply Height or Pitch.")]
+[FirmamentField("Handedness", "Handedness", FirmamentSchemaValueKind.Choice, Default = "RightHanded", Choices = ["RightHanded", "LeftHanded"], Description = "Winding direction.")]
+[FirmamentField("StartPhase", "StartPhase", FirmamentSchemaValueKind.Angle, Default = "0deg", Description = "Starting radial rotation.")]
+public static class HelixSemanticDeclaration { }
+
+[FirmamentConstruct("Loft", "Loft", Context = "Model with two authored profiles and frames", Entry = "Loft Body { RearProfile: Rear; RearFrame: RearPlane; FrontProfile: Front; FrontFrame: FrontPlane; Rule: Ruled; Correspondence: CommonRay; Reference: [1, 0, 0] }", Description = "Two-section ruled loft.")]
+[FirmamentField("RearProfile", "RearProfile", FirmamentSchemaValueKind.Profile, Required = true, Description = "Closed rear section profile.")]
+[FirmamentField("RearFrame", "RearFrame", FirmamentSchemaValueKind.ConstructionPlane, Required = true, Description = "Placement of the rear section.")]
+[FirmamentField("FrontProfile", "FrontProfile", FirmamentSchemaValueKind.Profile, Required = true, Description = "Closed front section profile.")]
+[FirmamentField("FrontFrame", "FrontFrame", FirmamentSchemaValueKind.ConstructionPlane, Required = true, Description = "Placement of the front section.")]
+[FirmamentField("Rule", "Rule", FirmamentSchemaValueKind.Choice, Required = true, Choices = ["Ruled"], Description = "Section interpolation rule.")]
+[FirmamentField("Correspondence", "Correspondence", FirmamentSchemaValueKind.Choice, Required = true, Choices = ["CommonRay"], Description = "Point correspondence between sections.")]
+[FirmamentField("Reference", "Reference", FirmamentSchemaValueKind.Vector, Required = true, Description = "Reference ray for section correspondence.")]
+[FirmamentField("Twist", "Twist", FirmamentSchemaValueKind.Angle, Default = "0deg", Description = "Relative section rotation.")]
+public static class LoftSemanticDeclaration { }
+
+[FirmamentConstruct("Concept", "Concept", Context = "Document", Entry = "Concept MountingFrame { Bounds: Box3; TopPlane: Plane }", Description = "Named semantic requirements; member names and types are authored per Concept.")]
+public static class ConceptSemanticDeclaration { }
+
+
diff --git a/Aetheris.Kernel.Firmament/FirmamentV2/SemanticSchema.cs b/Aetheris.Kernel.Firmament/FirmamentV2/SemanticSchema.cs
new file mode 100644
index 00000000..60f7afc0
--- /dev/null
+++ b/Aetheris.Kernel.Firmament/FirmamentV2/SemanticSchema.cs
@@ -0,0 +1,50 @@
+namespace Aetheris.Kernel.Firmament.FirmamentV2;
+
+// Only declarations explicitly marked with these attributes enter the generated registry.
+[AttributeUsage(AttributeTargets.Class, AllowMultiple = false)]
+public sealed class FirmamentConstructAttribute(string stableId, string name) : Attribute
+{
+ public string StableId { get; } = stableId;
+ public string Name { get; } = name;
+ public string? Context { get; init; }
+ public string? Entry { get; init; }
+ public string? Description { get; init; }
+ public string? CompatibilityAlias { get; init; }
+}
+
+public enum FirmamentSchemaValueKind { Length, Angle, Scalar, Count, Boolean, String, Choice, Vector, Point, Profile, ConstructionPlane, FaceSelector, BodySelector, ConstructReference, Box3, TypeRequirement }
+public enum FirmamentUnitKind { None, Length, Angle }
+
+[AttributeUsage(AttributeTargets.Class, AllowMultiple = true)]
+public sealed class FirmamentFieldAttribute(string stableId, string name, FirmamentSchemaValueKind kind) : Attribute
+{
+ public string StableId { get; } = stableId;
+ public string Name { get; } = name;
+ public FirmamentSchemaValueKind Kind { get; } = kind;
+ public FirmamentUnitKind Unit { get; init; }
+ public bool Required { get; init; }
+ public string? Default { get; init; }
+ public string? Description { get; init; }
+ public string[]? Choices { get; init; }
+}
+
+[AttributeUsage(AttributeTargets.Class, AllowMultiple = true)]
+public sealed class FirmamentOutputAttribute(string stableId, string name, string kind) : Attribute
+{
+ public string StableId { get; } = stableId;
+ public string Name { get; } = name;
+ public string Kind { get; } = kind;
+ public bool SourceAddressable { get; init; }
+ public string? SourceRole { get; init; }
+}
+
+public readonly record struct FirmamentConstructId(string Value);
+public readonly record struct FirmamentFieldId(string Value);
+public readonly record struct FirmamentOutputId(string Value);
+public sealed record FirmamentFieldSchema(FirmamentFieldId Id, string Name, FirmamentSchemaValueKind Kind, FirmamentUnitKind Unit,
+ bool Required, string? Default, IReadOnlyList<string> Choices, string? Description, bool SourceEditable);
+public sealed record FirmamentOutputSchema(FirmamentOutputId Id, string Name, string Kind, bool SourceAddressable, string? SourceRole);
+public sealed record FirmamentConstructSchema(FirmamentConstructId Id, string Name, string? Context, string? Entry,
+ string? Description, string? CompatibilityAlias, IReadOnlyList<FirmamentFieldSchema> Fields,
+ IReadOnlyList<FirmamentOutputSchema> Outputs);
+
diff --git a/Aetheris.Kernel.Firmament/Materializer/WireCoils.cs b/Aetheris.Kernel.Firmament/Materializer/WireCoils.cs
index 4066b2d7..2a859533 100644
--- a/Aetheris.Kernel.Firmament/Materializer/WireCoils.cs
+++ b/Aetheris.Kernel.Firmament/Materializer/WireCoils.cs
@@ -19,16 +19,7 @@ internal static class WireCoilAuthoring
private const string HeightField = "Height";
private const string HandednessField = "Handedness";
private const string StartPhaseField = "StartPhase";
- // This is the same bounded Axis/Helix contract consumed by CreateAxis below.
- internal static readonly IReadOnlyList<FirmamentAuthoringField> AxisFields =
- [
- new(RadiusField, "Length", true, "Centerline radius."),
- new(TurnsField, "Scalar", true, "Number of complete winding turns."),
- new(PitchField, "Length", false, "Axial distance per turn. Supply Pitch or Height."),
- new(HeightField, "Length", false, "Total axial span. Supply Height or Pitch."),
- new(HandednessField, "Enum", false, "Winding direction.", "RightHanded", ["RightHanded", "LeftHanded"]),
- new(StartPhaseField, "Angle", false, "Rotation of the starting radial frame.", "0deg")
- ];
+ internal static readonly IReadOnlyList<FirmamentAuthoringField> AxisFields = FirmamentSchemaAuthoringFields.For("Helix");
private const double ApproximationTolerance = 0.01d;
internal static KernelResult<WireAxisCoilAir> CreateAxis(string name, int ordinal, string body, WireState input, double diameter)
diff --git a/Aetheris.Web.Runtime/Program.cs b/Aetheris.Web.Runtime/Program.cs
index 87889789..5031d7bd 100644
--- a/Aetheris.Web.Runtime/Program.cs
+++ b/Aetheris.Web.Runtime/Program.cs
@@ -35,6 +35,7 @@ public static partial class Program
"info" => Info(),
"compile" => Compile(request),
"languageComplete" => LanguageComplete(request),
+ "languageSchema" => LanguageSchema(),
"snapshot" => Session(request).Snapshot,
"setProperty" => SetProperty(request),
"setSource" => SetSource(request),
@@ -90,6 +91,25 @@ public static partial class Program
request.SourceRevision, request.Offset.Value);
}
+ private static object LanguageSchema() => new
+ {
+ version = FirmamentSemanticSchemas.Version,
+ constructs = FirmamentSemanticSchemas.All.Select(construct => new
+ {
+ id = construct.Id.Value, construct.Name, construct.Context, construct.Entry,
+ construct.Description, construct.CompatibilityAlias,
+ fields = construct.Fields.Select(field => new
+ {
+ id = field.Id.Value, field.Name, kind = field.Kind.ToString(), unit = field.Unit.ToString(),
+ field.Required, field.Default, field.Choices, field.Description, field.SourceEditable
+ }),
+ outputs = construct.Outputs.Select(item => new
+ {
+ id = item.Id.Value, item.Name, item.Kind, item.SourceAddressable, item.SourceRole
+ })
+ })
+ };
+
private static object SetProperty(WebRequest request)
{
var session = Session(request);
@@ -236,6 +256,9 @@ public static partial class Program
sourceMap?.TryGetSourceSpan(symbol, out var span) == true
? SourceRefAt(_sourceName, effective, span.Start, span.Length) : null;
var boxSource = CompilerSource(entityId);
+ // Preserve the exported body category in Kind; report the authored construct separately.
+ var semanticConstruct = boxSource is null ? null : FirmamentV2Parser.Parse(effective).Document?.Solids
+ .FirstOrDefault(solid => string.Equals(solid.Name, entityId, StringComparison.Ordinal))?.RecordType;
var featureSources = (build.Value.Features ?? []).ToDictionary(feature => feature.FeatureId,
feature => CompilerSource(feature.FeatureId), StringComparer.Ordinal);
var mesh = WebMeshBuilder.Build(Name, definitionId, entityId, displayBody,
@@ -243,7 +266,7 @@ public static partial class Program
var meshMs = watch.Elapsed.TotalMilliseconds;
var featureNodes = (build.Value.EngineeringFeatures ?? []).Select(feature => new WebTreeNode(feature.FeatureId, feature.Kind, feature.Name, entityId, [], true, null))
.Concat((build.Value.Features ?? []).Select(feature => new WebTreeNode(feature.FeatureId, feature.Kind, feature.Name, entityId, [], true, featureSources[feature.FeatureId], feature.Diameter))).ToArray();
- var body = new WebTreeNode(entityId, build.Value.ExportedBodyCategory, Name, Id, featureNodes.Select(item => item.Id).ToArray(), true, boxSource ?? SourceRef(_sourceName, 0, effective.Length));
+ var body = new WebTreeNode(entityId, build.Value.ExportedBodyCategory, Name, Id, featureNodes.Select(item => item.Id).ToArray(), true, boxSource ?? SourceRef(_sourceName, 0, effective.Length), SemanticConstruct: semanticConstruct);
var root = new WebTreeNode(Id, "Model", Name, null, [body.Id], true, SourceRef(_sourceName, 0, effective.Length));
var tree = new { rootId = root.Id, nodes = new[] { root, body }.Concat(featureNodes).ToArray() };
return WebBuildResult.Passed(step, tree, mesh, [Id, entityId, .. featureNodes.Select(item => item.Id)], compileMs, meshMs);
@@ -417,7 +440,7 @@ internal static class WebMeshBuilder
internal sealed record WebPropertyValue(double Value, string Unit);
internal sealed record WebSourceRef(string Source, int Line, int Column, int Start, int Length);
internal sealed record WebProperty(string Id, string OwnerEntityId, string Name, string Type, string Unit, double Value, bool Writable, int Start, int Length, WebSourceRef Source);
-internal sealed record WebTreeNode(string Id, string Kind, string Name, string? ParentId, IReadOnlyList<string> Children, bool Visible, WebSourceRef? Source, double? HoleDiameterMm = null);
+internal sealed record WebTreeNode(string Id, string Kind, string Name, string? ParentId, IReadOnlyList<string> Children, bool Visible, WebSourceRef? Source, double? HoleDiameterMm = null, string? SemanticConstruct = null);
internal sealed record WebDiagnostic(string Severity, string Code, string Message, WebSourceRef? Source = null, string? Details = null);
internal sealed record WebBuildResult(bool Success, int Revision, object? Model, IReadOnlyList<WebDiagnostic> Diagnostics, bool RetainedPreviousGeometry,
object? Tree = null, object? Mesh = null, IReadOnlyList<string>? EntityIds = null, object? Timings = null, object? Changes = null, string? StepText = null)
diff --git a/Aetheris.Web.Runtime/sdk/src/index.d.ts b/Aetheris.Web.Runtime/sdk/src/index.d.ts
index 02ad153a..2ec78b61 100644
--- a/Aetheris.Web.Runtime/sdk/src/index.d.ts
+++ b/Aetheris.Web.Runtime/sdk/src/index.d.ts
@@ -4,7 +4,7 @@ export interface SourceReference { readonly source: string; readonly line: numbe
export interface Diagnostic { readonly severity: DiagnosticSeverity; readonly code: string; readonly message: string; readonly source?: SourceReference; readonly details?: string }
export interface UnitValue { readonly value: number; readonly unit: Unit }
export interface EditableProperty { readonly id: string; readonly ownerEntityId: string; readonly name: string; readonly type: 'Length' | 'Angle' | 'Integer' | 'Number' | 'Boolean' | 'Enum'; readonly unit: Unit; readonly value: number; readonly writable: boolean; readonly source: SourceReference }
-export interface ModelTreeNode { readonly id: string; readonly kind: string; readonly name: string; readonly parentId?: string; readonly children: readonly string[]; readonly visible: boolean; readonly source?: SourceReference; readonly holeDiameterMm?: number | null }
+export interface ModelTreeNode { readonly id: string; readonly kind: string; readonly name: string; readonly parentId?: string; readonly children: readonly string[]; readonly visible: boolean; readonly source?: SourceReference; readonly holeDiameterMm?: number | null; readonly semanticConstruct?: string | null }
export interface ModelTree { readonly rootId: string; readonly nodes: readonly ModelTreeNode[] }
export type SourceAddressability = 'AuthoredStable' | 'DerivedStable' | 'ImportedStable' | 'RuntimeOnly' | 'Ambiguous' | 'Unstable';
export interface MeshRange { readonly startTriangle: number; readonly triangleCount: number; readonly faceId: string; readonly semanticEntityId: string; readonly semanticTopologyId?: string | null; readonly topologyKind?: 'Face'; readonly outputRole?: string | null; readonly originFeature?: string | null; readonly sourceAddressability?: SourceAddressability; readonly selector?: string | null; readonly selectorReason?: string | null; readonly source?: SourceReference | null; readonly buildRevision?: number }
@@ -22,13 +22,17 @@ export interface CompileOptions extends OperationOptions { readonly sourceName?:
export interface LanguageOptions { readonly sourceName?: string; readonly sourceRevision: string }
export interface LanguageField { readonly name: string; readonly type: string; readonly required: boolean; readonly meaning: string; readonly default?: string | null; readonly choices?: readonly string[] | null }
export interface LanguageCompletion { readonly document: string; readonly revision: string; readonly context: string; readonly replaceStart: number; readonly replaceLength: number; readonly fields: readonly LanguageField[]; readonly missingRequiredFields: readonly string[] }
+export interface SemanticFieldSchema { readonly id: string; readonly name: string; readonly kind: string; readonly unit: 'None' | 'Length' | 'Angle'; readonly required: boolean; readonly default: string | null; readonly choices: readonly string[]; readonly description: string | null; readonly sourceEditable: boolean }
+export interface SemanticOutputSchema { readonly id: string; readonly name: string; readonly kind: string; readonly sourceAddressable: boolean; readonly sourceRole: string | null }
+export interface SemanticConstructSchema { readonly id: string; readonly name: string; readonly context: string | null; readonly entry: string | null; readonly description: string | null; readonly compatibilityAlias: string | null; readonly fields: readonly SemanticFieldSchema[]; readonly outputs: readonly SemanticOutputSchema[] }
+export interface SemanticSchema { readonly version: 'firmament-semantic-schema/1'; readonly constructs: readonly SemanticConstructSchema[] }
export interface SelectorCandidate { readonly selector: string; readonly kind: string; readonly semanticKey: string | null; readonly outputRole: string | null; readonly source: SourceReference; readonly qualification: SourceAddressability; readonly buildRevision: number }
export interface AetherisOptions { readonly worker?: boolean; readonly wasmUrl?: string | URL; readonly diagnostics?: (diagnostics: readonly Diagnostic[]) => void }
export class AetherisError extends Error { readonly code: string; readonly details?: string }
export class Aetheris {
static create(options?: AetherisOptions): Promise<Aetheris>;
readonly runtimeInfo: RuntimeInfo;
- readonly language: { complete(source: string, offset: number, options: LanguageOptions): Promise<LanguageCompletion> };
+ readonly language: { complete(source: string, offset: number, options: LanguageOptions): Promise<LanguageCompletion>; schema(): Promise<SemanticSchema> };
info(): Promise<RuntimeInfo>;
capabilities(): Promise<RuntimeCapabilities>;
compile(source: string, options?: CompileOptions): Promise<{ model: ModelSession | null; diagnostics: readonly Diagnostic[] }>;
diff --git a/Aetheris.Web.Runtime/sdk/src/index.js b/Aetheris.Web.Runtime/sdk/src/index.js
index 93ebb855..f4424eee 100644
--- a/Aetheris.Web.Runtime/sdk/src/index.js
+++ b/Aetheris.Web.Runtime/sdk/src/index.js
@@ -56,6 +56,7 @@ export class Aetheris {
constructor(transport, diagnostics) {
this.transport = transport; this.diagnostics = diagnostics;
this.language = {
+ schema: () => this.transport.request({ operation: 'languageSchema' }),
complete: (source, offset, options = {}) => this.transport.request({ operation: 'languageComplete', source, offset,
sourceName: options.sourceName, sourceRevision: options.sourceRevision })
};
diff --git a/Aetheris.Web.Runtime/sdk/tests/language.test.mjs b/Aetheris.Web.Runtime/sdk/tests/language.test.mjs
index 424e9551..08507f6b 100644
--- a/Aetheris.Web.Runtime/sdk/tests/language.test.mjs
+++ b/Aetheris.Web.Runtime/sdk/tests/language.test.mjs
@@ -15,3 +15,14 @@ test('public language completion sends source revision and offset through runtim
assert.deepEqual(requests, [{ operation: 'languageComplete', source: 'Helix H { Rad', offset: 13,
sourceName: 'spring.firmament', sourceRevision: 'draft-3' }]);
});
+
+test('public semantic schema uses the versioned runtime contract', async () => {
+ const requests = [];
+ const cad = new Aetheris({ request: async request => {
+ requests.push(request);
+ return { version: 'firmament-semantic-schema/1', constructs: [] };
+ } });
+ const schema = await cad.language.schema();
+ assert.equal(schema.version, 'firmament-semantic-schema/1');
+ assert.deepEqual(requests, [{ operation: 'languageSchema' }]);
+});
diff --git a/Aetheris.slnx b/Aetheris.slnx
index 3d9b4bb3..d3cd7c1c 100644
--- a/Aetheris.slnx
+++ b/Aetheris.slnx
@@ -4,6 +4,7 @@
<Project Path="Aetheris.Drawing.Tests/Aetheris.Drawing.Tests.csproj" />
<Project Path="Aetheris.Server.Tests/Aetheris.Server.Tests.csproj" />
<Project Path="Aetheris.Kernel.Core/Aetheris.Kernel.Core.csproj" />
+ <Project Path="Aetheris.Firmament.SchemaGenerator/Aetheris.Firmament.SchemaGenerator.csproj" />
<Project Path="Aetheris.Geometry/Aetheris.Geometry.csproj" />
<Project Path="Aetheris.Geometry.Tests/Aetheris.Geometry.Tests.csproj" />
<Project Path="Aetheris.Reconstruction/Aetheris.Reconstruction.csproj" />
diff --git a/docs/architecture/Compile-Time Semantic Introspection.md b/docs/architecture/Compile-Time Semantic Introspection.md
new file mode 100644
index 00000000..4688df88
--- /dev/null
+++ b/docs/architecture/Compile-Time Semantic Introspection.md
@@ -0,0 +1,13 @@
+# Compile-Time Semantic Introspection
+
+Firmament schema is an opt-in, static description of the public authoring surface. It does not perform runtime reflection, mutate semantic objects, or replace the parser and binder.
+
+`Aetheris.Firmament.SchemaGenerator` is a Roslyn incremental source generator. It visits classes marked with `FirmamentConstructAttribute`, reads explicit `FirmamentFieldAttribute` and `FirmamentOutputAttribute` declarations, validates stable IDs and supported kinds, sorts by stable ID, and emits `FirmamentSemanticSchemas.g.cs`. The generated file is inspectable at `Aetheris.Kernel.Firmament/obj/Generated/Aetheris.Firmament.SchemaGenerator/Aetheris.Firmament.SchemaGenerator.SemanticSchemaGenerator/FirmamentSemanticSchemas.g.cs` after a build. It is excluded from source control with `obj/`.
+
+The generated registry contains read-only `FirmamentConstructSchema`, `FirmamentFieldSchema`, and `FirmamentOutputSchema` descriptors. IDs are explicit construct, field, and output keys; field/output IDs are qualified by construct ID. They do not depend on declaration or hash iteration order. Unit kind is derived from Length or Angle value kinds, or declared explicitly for a vector or point such as Box Size. Descriptors contain no callbacks, UI layout, runtime setters, or CLR member names. `FMS001` is a build error for duplicate/missing construct or field IDs, duplicate construct names, unsupported kinds, incompatible units, invalid choice declarations, and duplicate output IDs.
+
+The schema is available to the browser through versioned `language.schema()` transport. Its JSON uses semantic strings for kinds and units. The existing `language.complete()` path takes Helix and solid Loft fields from the generated descriptors. It still uses parser-owned context detection. The Web tree preserves its existing body `kind` and separately projects the parser's `semanticConstruct` for schema lookup. Helios shows generic field and output metadata for a selected construct when that identity matches a schema; it never edits the compiled object through schema metadata.
+
+This first slice has a deliberate boundary. Box and Hole descriptors are informational, while their parser rules remain separately implemented. Concept requirements are user-defined members, so Concept has a construct descriptor but no fixed field list. The current Web session does not provide a general semantic-instance-to-authored-field projection or per-field source span. Helios therefore labels unavailable values explicitly and only links fields to source when the existing SDK property supplies a range. Generic Inspector editing from the schema is disabled. The pre-existing experimental effective override editor remains separate and is not schema authority.
+
+The schema path uses ordinary generated C# and static collection access. It does not scan assemblies, use `PropertyInfo`, call `MethodInfo`, invoke `dynamic`, or require runtime reflection metadata preservation. The existing Web host's JSON transport still uses reflection-enabled serialization; that broader host has IL2026 trim warnings. NativeAOT compatibility of the broader runtime still requires its normal qualification path; the schema introduces no reflection-specific preservation requirement.
diff --git a/docs/release/FIRMAMENT-SCHEMA-X0.md b/docs/release/FIRMAMENT-SCHEMA-X0.md
new file mode 100644
index 00000000..62f1a7e5
--- /dev/null
+++ b/docs/release/FIRMAMENT-SCHEMA-X0.md
@@ -0,0 +1,45 @@
+# FIRMAMENT-SCHEMA-X0
+
+**Verdict: Meaningful progression.** A compile-time generated, opt-in semantic schema now exists, Helix and solid Loft LX field help reads it, the Web SDK exposes it, and Helios can render its field/output descriptors generically. The mission's accepted criterion is not met because authored values/ranges and source rewrite are not supplied by the compiler/Web session, and Box/Hole metadata is not yet the parser's sole semantic declaration.
+
+## Delivered
+
+- Roslyn incremental generator in `Aetheris.Firmament.SchemaGenerator`; `FMS001` reports invalid declarations at build time.
+- Static immutable registry with explicit construct, field, and output IDs, value kind, unit kind, required/default/choices, source editability, context, entry sketch, compatibility alias, and source output role.
+- First descriptors: Box (Size or Bounds), Hole (On, Center, Diameter, End, PatternIdentity, Wall output), Helix (WireForm owner and AxisCoil compatibility), solid Loft (two profiles/frames, rule, correspondence, reference, twist), and Concept (dynamic semantic requirements).
+- Existing Helix and solid Loft LX field lists replaced by generated schema projections. Hollow Loft extension fields remain parser-owned. Existing parser context recognition remains authoritative.
+- Versioned `Aetheris.language.schema()` Web SDK API and generic Helios Inspector field/output metadata.
+
+## Coverage and limits
+
+| Construct | Generated field coverage | LX use | Helios Inspector | Output |
+| --- | --- | --- | --- | --- |
+| Box | Size, Bounds; alternative requirement described, not encoded as a group | No | Descriptor via compiler-projected `semanticConstruct`; authored value often unavailable | No generated output |
+| Hole | Shaft fields; variants and blind-end details incomplete | No | Generic descriptor when model kind is Hole; authored value often unavailable | Wall, Face, `HoleWallFace` role |
+| Helix | Axis Helix fields, units, defaults, choices | Yes | Descriptor only when a Helix tree node exists | None |
+| Loft | Solid Loft fields; Hollow adds parser-owned Thickness and SeamGap | Yes for solid fields | Descriptor only when a Loft tree node exists | None |
+| Concept | Dynamic member names/types remain in Concept IR | No | Descriptor only; no fixed member rows | None |
+
+The canonical entries in the schema are syntax sketches. Loft still needs authored profiles and construction planes; the SDK does not yet provide a complete insertable model for it. Bare-context Helix/Loft discovery and the requested fresh-agent UI workflows were not qualified. This is a concrete remaining gap, not an accepted result.
+
+## Verification
+
+- `dotnet test Aetheris.Kernel.Firmament.Tests/Aetheris.Kernel.Firmament.Tests.csproj --filter 'FullyQualifiedName~FirmamentSchemaGeneratorTests|FullyQualifiedName~FirmamentSemanticSchemaTests|FullyQualifiedName~FirmamentLanguageServiceTests' -m:1` — 8 passed.
+- `dotnet build Aetheris.Web.Runtime/Aetheris.Web.Runtime.csproj -m:1` — passed, with existing WebAssembly/trimming warnings.
+- `dotnet build Aetheris.slnx -m:1` — passed; `dotnet test Aetheris.slnx --no-build --no-restore -m:1` — all discovered tests passed across the solution. The focused schema tests were rerun after the final build (8 passed).
+- `node --test tests/language.test.mjs` in `Aetheris.Web.Runtime/sdk` — 2 passed.
+- `npm run sdk:install` and `npm run build` in HeliosCAD — passed.
+- Inspector unit tests — 5 passed.
+- Helios Chromium correspondence workflows — Box and Hole passed with generic schema fields visible; the existing LX browser workflow also passed.
+
+The generator test compares equivalent declarations in different orders and verifies a duplicate field ID produces `FMS001`. The generated source is emitted under `obj/Generated` for inspection.
+
+## Duplication and next owner boundary
+
+Helix's and solid Loft's separate LX field tables were removed. Parser constants and validation remain authoritative and still duplicate some field names. Box/Hole parser rules are still handwritten. Helios has no Box/Hole-specific schema field rendering branch; its existing specialized source actions and effective override editor remain. No generated docs pipeline was added; this document is handwritten.
+
+The next bounded dependency is a compiler-owned projection from a compiled semantic instance to authored field values and source spans, serialized by the Web session. The current `ParameterInspector` exposes a few numeric model-level properties (`Width`, `Height`, `Thickness`, `HoleDiameter`) and does not associate Box `Size` or Hole `Diameter` with their construct instances. That is why the generic Inspector can show field definitions and Hole Wall but labels most authored values unavailable. A value/span projection would let Inspector show genuine authored/effective values and support a verified source-range rewrite. The schema itself must not become a setter or alternate state store.
+
+## Reflection audit
+
+The generated schema path performs no runtime assembly scan, `PropertyInfo`-based member walk, dynamic mutation, or generated runtime reflection. The schema adds no NativeAOT reflection-preservation attributes. The pre-existing Web host still uses reflection-enabled `System.Text.Json` serialization and produces IL2026 warnings; this milestone does not make that host fully trim-safe. NativeAOT qualification for the full Aetheris application was not run.