Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel
Add Forge descriptor abstraction scaffold
Yuechen Li2f9489db484d
diff --git a/Aetheris.Forge/Abstractions/ForgeDescriptorValidator.cs b/Aetheris.Forge/Abstractions/ForgeDescriptorValidator.csnew file mode 100644index 00000000..6d8944f8--- /dev/null+++ b/Aetheris.Forge/Abstractions/ForgeDescriptorValidator.cs@@ -0,0 +1,119 @@+using System.Text.RegularExpressions;++namespace Aetheris.Forge.Abstractions;++public static partial class ForgeDescriptorValidator+{+ public static ForgeDescriptorValidationResult Validate(ForgePackageDescriptor package)+ {+ var diagnostics = new List<ForgeDescriptorDiagnostic>();+ ValidatePackage(package, diagnostics);+ return new ForgeDescriptorValidationResult(diagnostics.OrderBy(d => d.Path, StringComparer.Ordinal).ThenBy(d => d.Code, StringComparer.Ordinal).ToArray());+ }++ private static void ValidatePackage(ForgePackageDescriptor package, List<ForgeDescriptorDiagnostic> diagnostics)+ {+ RequireId(package.PackageId, "package", "packageId", diagnostics);+ if (string.IsNullOrWhiteSpace(package.SemanticVersion) || !VersionRegex().IsMatch(package.SemanticVersion))+ Add(diagnostics, "forge.package.invalid-version", "semanticVersion", "Package semanticVersion must be a non-empty semantic version.");+ ValidateTrustTier(package.RequestedTrustTier, "requestedTrustTier", diagnostics);+ Duplicates(package.Concepts.Select(c => c.ConceptId), "forge.package.duplicate-concept-id", "concepts", diagnostics);+ Duplicates(package.Templates.Select(t => t.TemplateId), "forge.package.duplicate-template-id", "templates", diagnostics);+ Duplicates(package.Capabilities.Select(c => c.CapabilityId), "forge.package.duplicate-capability-id", "capabilities", diagnostics);+ ValidateRefs(package.Examples, e => e.ExampleId, e => e.SourcePathOrSnippet, "examples", "example", diagnostics);+ ValidateRefs(package.Fixtures, f => f.FixtureId, f => f.Path, "fixtures", "fixture", diagnostics);+ ValidateRefs(package.LlmGuidance, g => g.GuidanceId, g => g.Path, "llmGuidance", "llm-guidance", diagnostics);++ var conceptIds = package.Concepts.Select(c => c.ConceptId).Where(IsValidId).ToHashSet(StringComparer.Ordinal);+ var capabilityIds = package.Capabilities.Select(c => c.CapabilityId).Where(IsValidId).ToHashSet(StringComparer.Ordinal);+ for (var i = 0; i < package.Capabilities.Count; i++) ValidateCapability(package.Capabilities[i], $"capabilities[{i}]", diagnostics);+ for (var i = 0; i < package.Concepts.Count; i++) ValidateConcept(package.Concepts[i], $"concepts[{i}]", capabilityIds, diagnostics);+ for (var i = 0; i < package.Templates.Count; i++) ValidateTemplate(package.Templates[i], $"templates[{i}]", conceptIds, diagnostics);+ }++ private static void ValidateConcept(ForgeConceptDescriptor concept, string path, HashSet<string> capabilityIds, List<ForgeDescriptorDiagnostic> diagnostics)+ {+ RequireId(concept.ConceptId, "concept", $"{path}.conceptId", diagnostics);+ if (string.IsNullOrWhiteSpace(concept.Category)) Add(diagnostics, "forge.concept.missing-category", $"{path}.category", "Concept category is required.");+ Duplicates(concept.Fields.Select(f => f.FieldName), "forge.concept.duplicate-field-name", $"{path}.fields", diagnostics);+ Duplicates(concept.Diagnostics.Select(d => d.DiagnosticId), "forge.concept.duplicate-diagnostic-id", $"{path}.diagnostics", diagnostics);+ ValidateRefs(concept.Examples, e => e.ExampleId, e => e.SourcePathOrSnippet, $"{path}.examples", "example", diagnostics);+ ValidateRefs(concept.Fixtures, f => f.FixtureId, f => f.Path, $"{path}.fixtures", "fixture", diagnostics);+ ValidateRefs(concept.LlmGuidance, g => g.GuidanceId, g => g.Path, $"{path}.llmGuidance", "llm-guidance", diagnostics);+ for (var i = 0; i < concept.Fields.Count; i++) ValidateField(concept.Fields[i], $"{path}.fields[{i}]", diagnostics);+ for (var i = 0; i < concept.Diagnostics.Count; i++) ValidateDiagnostic(concept.Diagnostics[i], $"{path}.diagnostics[{i}]", diagnostics);+ for (var i = 0; i < concept.LoweringContracts.Count; i++)+ {+ var contract = concept.LoweringContracts[i];+ var cpath = $"{path}.loweringContracts[{i}]";+ RequireId(contract.ContractId, "lowering-contract", $"{cpath}.contractId", diagnostics);+ RequireId(contract.SourceConceptId, "concept", $"{cpath}.sourceConceptId", diagnostics);+ if (string.IsNullOrWhiteSpace(contract.TargetAirFeatureFamily)) Add(diagnostics, "forge.lowering.missing-target", $"{cpath}.targetAirFeatureFamily", "Lowering contract targetAirFeatureFamily is required.");+ foreach (var required in contract.RequiredCapabilities.Where(r => !capabilityIds.Contains(r)))+ Add(diagnostics, "forge.lowering.unknown-capability", $"{cpath}.requiredCapabilities", $"Lowering contract requires undeclared capability '{required}'.");+ }+ }++ private static void ValidateTemplate(ForgeTemplateDescriptor template, string path, HashSet<string> conceptIds, List<ForgeDescriptorDiagnostic> diagnostics)+ {+ RequireId(template.TemplateId, "template", $"{path}.templateId", diagnostics);+ Duplicates(template.Parameters.Select(p => p.FieldName), "forge.template.duplicate-parameter-name", $"{path}.parameters", diagnostics);+ Duplicates(template.Diagnostics.Select(d => d.DiagnosticId), "forge.template.duplicate-diagnostic-id", $"{path}.diagnostics", diagnostics);+ foreach (var id in template.ConceptRequirements.Concat(template.ExpandsToConceptIds).Where(id => !conceptIds.Contains(id)))+ Add(diagnostics, "forge.template.unknown-concept-id", path, $"Template references unknown same-package concept '{id}'.");+ for (var i = 0; i < template.Parameters.Count; i++) ValidateField(template.Parameters[i], $"{path}.parameters[{i}]", diagnostics);+ for (var i = 0; i < template.Diagnostics.Count; i++) ValidateDiagnostic(template.Diagnostics[i], $"{path}.diagnostics[{i}]", diagnostics);+ }++ private static void ValidateField(ForgeFieldDescriptor field, string path, List<ForgeDescriptorDiagnostic> diagnostics)+ {+ if (string.IsNullOrWhiteSpace(field.FieldName)) Add(diagnostics, "forge.field.missing-name", $"{path}.fieldName", "Field name is required.");+ if (!Enum.IsDefined(field.FieldType)) Add(diagnostics, "forge.field.invalid-type", $"{path}.fieldType", "Field type is invalid.");+ if (field.Required && !string.IsNullOrWhiteSpace(field.DefaultValue)) Add(diagnostics, "forge.field.required-with-default", path, "Required fields must not declare defaultValue metadata.");+ }++ private static void ValidateDiagnostic(ForgeDiagnosticDescriptor descriptor, string path, List<ForgeDescriptorDiagnostic> diagnostics)+ {+ RequireId(descriptor.DiagnosticId, "diagnostic", $"{path}.diagnosticId", diagnostics);+ if (!Enum.IsDefined(descriptor.Severity)) Add(diagnostics, "forge.diagnostic.invalid-severity", $"{path}.severity", "Diagnostic severity is invalid.");+ if (string.IsNullOrWhiteSpace(descriptor.MessageTemplate)) Add(diagnostics, "forge.diagnostic.missing-message-template", $"{path}.messageTemplate", "Diagnostic messageTemplate is required.");+ }++ private static void ValidateCapability(ForgeCapabilityDescriptor capability, string path, List<ForgeDescriptorDiagnostic> diagnostics)+ {+ RequireId(capability.CapabilityId, "capability", $"{path}.capabilityId", diagnostics);+ ValidateTrustTier(capability.Tier, $"{path}.tier", diagnostics);+ }++ private static void ValidateTrustTier(ForgeTrustTier tier, string path, List<ForgeDescriptorDiagnostic> diagnostics)+ { if (!Enum.IsDefined(tier)) Add(diagnostics, "forge.trust-tier.invalid", path, "Trust tier must be one of the declared Forge trust tiers."); }++ private static void ValidateRefs<T>(IReadOnlyList<T> refs, Func<T,string> id, Func<T,string> path, string basePath, string kind, List<ForgeDescriptorDiagnostic> diagnostics)+ {+ Duplicates(refs.Select(id), $"forge.{kind}.duplicate-id", basePath, diagnostics);+ for (var i = 0; i < refs.Count; i++)+ {+ if (string.IsNullOrWhiteSpace(id(refs[i]))) Add(diagnostics, $"forge.{kind}.missing-id", $"{basePath}[{i}]", $"{kind} id is required.");+ if (string.IsNullOrWhiteSpace(path(refs[i]))) Add(diagnostics, $"forge.{kind}.missing-path", $"{basePath}[{i}]", $"{kind} path or snippet is required.");+ }+ }++ private static void Duplicates(IEnumerable<string> values, string code, string path, List<ForgeDescriptorDiagnostic> diagnostics)+ {+ foreach (var value in values.Where(v => !string.IsNullOrWhiteSpace(v)).GroupBy(v => v, StringComparer.Ordinal).Where(g => g.Count() > 1).Select(g => g.Key).Order(StringComparer.Ordinal))+ Add(diagnostics, code, path, $"Duplicate id/name '{value}'.");+ }++ private static void RequireId(string value, string kind, string path, List<ForgeDescriptorDiagnostic> diagnostics)+ {+ if (string.IsNullOrWhiteSpace(value)) Add(diagnostics, $"forge.{kind}.missing-id", path, $"{kind} id is required.");+ else if (!IsValidId(value)) Add(diagnostics, $"forge.{kind}.invalid-id", path, $"{kind} id '{value}' is invalid.");+ }++ private static bool IsValidId(string value) => IdRegex().IsMatch(value);+ private static void Add(List<ForgeDescriptorDiagnostic> diagnostics, string code, string path, string message) => diagnostics.Add(new ForgeDescriptorDiagnostic(code, path, message));+ [GeneratedRegex("^[A-Za-z][A-Za-z0-9]*(?:[.-][A-Za-z][A-Za-z0-9]*)*$")]+ private static partial Regex IdRegex();+ [GeneratedRegex("^\\d+\\.\\d+\\.\\d+(?:[-+][0-9A-Za-z.-]+)?$")]+ private static partial Regex VersionRegex();+}diff --git a/Aetheris.Forge/Abstractions/ForgeDescriptors.cs b/Aetheris.Forge/Abstractions/ForgeDescriptors.csnew file mode 100644index 00000000..232fb960--- /dev/null+++ b/Aetheris.Forge/Abstractions/ForgeDescriptors.cs@@ -0,0 +1,113 @@+namespace Aetheris.Forge.Abstractions;++public enum ForgeTrustTier+{+ SemanticDocsOnly = 1,+ ValidationDerivation = 2,+ LoweringProvider = 3,+ MaterializerProvider = 4,+ UnsafeNativeExperimental = 5,+}++public enum ForgeDiagnosticSeverity+{+ Info = 1,+ Warning = 2,+ Error = 3,+}++public enum ForgeFieldType+{+ Length = 1,+ Angle = 2,+ Integer = 3,+ Real = 4,+ Boolean = 5,+ String = 6,+ FaceSelector = 7,+ FaceLocalPoint2D = 8,+ HoleEndCondition = 9,+ SemanticReference = 10,+}++public sealed record ForgePackageDescriptor(+ string PackageId,+ string DisplayName,+ string SemanticVersion,+ string Vendor,+ string Description,+ ForgeTrustTier RequestedTrustTier,+ IReadOnlyList<string> HostRequirements,+ IReadOnlyList<ForgeConceptDescriptor> Concepts,+ IReadOnlyList<ForgeTemplateDescriptor> Templates,+ IReadOnlyList<ForgeCapabilityDescriptor> Capabilities,+ IReadOnlyList<ForgeExampleDescriptor> Examples,+ IReadOnlyList<ForgeFixtureDescriptor> Fixtures,+ IReadOnlyList<ForgeLlmGuidanceDescriptor> LlmGuidance);++public sealed record ForgeConceptDescriptor(+ string ConceptId,+ string DisplayName,+ string Category,+ string Description,+ IReadOnlyList<ForgeFieldDescriptor> Fields,+ IReadOnlyList<ForgeDiagnosticDescriptor> Diagnostics,+ IReadOnlyList<string> CapabilityRequirements,+ IReadOnlyList<ForgeLoweringContractDescriptor> LoweringContracts,+ IReadOnlyList<ForgeExampleDescriptor> Examples,+ IReadOnlyList<ForgeFixtureDescriptor> Fixtures,+ IReadOnlyList<ForgeLlmGuidanceDescriptor> LlmGuidance,+ IReadOnlyList<string>? ManufacturingAssumptions = null,+ IReadOnlyList<string>? DerivedFields = null,+ IReadOnlyList<string>? ValidationRuleIds = null);++public sealed record ForgeTemplateDescriptor(+ string TemplateId,+ string DisplayName,+ string Description,+ IReadOnlyList<ForgeFieldDescriptor> Parameters,+ IReadOnlyList<string> ConceptRequirements,+ IReadOnlyList<string> ExpandsToConceptIds,+ IReadOnlyList<ForgeDiagnosticDescriptor> Diagnostics,+ IReadOnlyList<ForgeExampleDescriptor> Examples,+ IReadOnlyList<ForgeFixtureDescriptor> Fixtures,+ IReadOnlyList<ForgeLlmGuidanceDescriptor> LlmGuidance);++public sealed record ForgeFieldDescriptor(+ string FieldName,+ ForgeFieldType FieldType,+ bool Required,+ string? QuantityKind,+ string Description,+ string? DefaultValue = null,+ IReadOnlyList<string>? AllowedValues = null);++public sealed record ForgeDiagnosticDescriptor(+ string DiagnosticId,+ ForgeDiagnosticSeverity Severity,+ string MessageTemplate,+ string Description);++public sealed record ForgeCapabilityDescriptor(+ string CapabilityId,+ ForgeTrustTier Tier,+ string Description,+ IReadOnlyList<string> RequiredHostFeatures);++public sealed record ForgeLoweringContractDescriptor(+ string ContractId,+ string SourceConceptId,+ string TargetAirFeatureFamily,+ IReadOnlyList<string> RequiredCapabilities,+ string Description);++public sealed record ForgeExampleDescriptor(string ExampleId, string SourcePathOrSnippet, string Description);+public sealed record ForgeFixtureDescriptor(string FixtureId, string Path, string Description);+public sealed record ForgeLlmGuidanceDescriptor(string GuidanceId, string Path, string Description);++public sealed record ForgeDescriptorDiagnostic(string Code, string Path, string Message);++public sealed record ForgeDescriptorValidationResult(IReadOnlyList<ForgeDescriptorDiagnostic> Diagnostics)+{+ public bool IsValid => Diagnostics.Count == 0;+}diff --git a/Aetheris.Forge/Examples/StandardHoleForgeDescriptor.cs b/Aetheris.Forge/Examples/StandardHoleForgeDescriptor.csnew file mode 100644index 00000000..ba19d442--- /dev/null+++ b/Aetheris.Forge/Examples/StandardHoleForgeDescriptor.cs@@ -0,0 +1,52 @@+using Aetheris.Forge.Abstractions;++namespace Aetheris.Forge.Examples;++public static class StandardHoleForgeDescriptor+{+ public static ForgePackageDescriptor CreatePackage() => new(+ PackageId: "Aetheris.Standard",+ DisplayName: "Aetheris Standard Semantic Concepts",+ SemanticVersion: "0.1.0",+ Vendor: "Aetheris",+ Description: "Descriptor-only fixture for standard semantic CAD concepts.",+ RequestedTrustTier: ForgeTrustTier.SemanticDocsOnly,+ HostRequirements: ["Aetheris.Forge.Abstractions"],+ Concepts: [CreateConcept()],+ Templates: [],+ Capabilities: [new ForgeCapabilityDescriptor("Standard.Hole.LoweringMetadata", ForgeTrustTier.LoweringProvider, "Metadata describing the allowed Standard.Hole AIR lowering target; no lowerer is executed.", ["AirHoleFeature"])],+ Examples: [new ForgeExampleDescriptor("standard-hole-minimal", "hole(entryFace: face, center: uv, shaftDiameter: 5mm, endCondition: through)", "Minimal Standard.Hole descriptor source snippet.")],+ Fixtures: [new ForgeFixtureDescriptor("standard-hole-validation-fixture", "fixtures/forge/standard-hole.json", "Descriptor validation fixture path; existence is not required by FORGE-X1.")],+ LlmGuidance: [new ForgeLlmGuidanceDescriptor("standard-hole-llm-guidance", "docs/llm/standard-hole.md", "Guidance link for authoring Standard.Hole semantics.")]);++ public static ForgeConceptDescriptor CreateConcept() => new(+ ConceptId: "Standard.Hole",+ DisplayName: "Standard Hole",+ Category: "Hole",+ Description: "Descriptor-only semantic concept for a simple hole. This does not change Standard Library behavior.",+ Fields:+ [+ new ForgeFieldDescriptor("entryFace", ForgeFieldType.FaceSelector, true, null, "Face receiving the hole."),+ new ForgeFieldDescriptor("center", ForgeFieldType.FaceLocalPoint2D, true, null, "Face-local hole center."),+ new ForgeFieldDescriptor("shaftDiameter", ForgeFieldType.Length, true, "Length", "Nominal shaft diameter."),+ new ForgeFieldDescriptor("endCondition", ForgeFieldType.HoleEndCondition, true, null, "Through, blind, or other descriptor-level end condition metadata.")+ ],+ Diagnostics:+ [+ new ForgeDiagnosticDescriptor("standard-hole-missing-entry-face", ForgeDiagnosticSeverity.Error, "Standard.Hole requires an entry face.", "Raised when entryFace metadata is absent."),+ new ForgeDiagnosticDescriptor("standard-hole-invalid-center", ForgeDiagnosticSeverity.Error, "Standard.Hole center must be valid on the entry face.", "Raised when center metadata is invalid."),+ new ForgeDiagnosticDescriptor("standard-hole-invalid-diameter", ForgeDiagnosticSeverity.Error, "Standard.Hole shaftDiameter must be positive.", "Raised when shaftDiameter metadata is invalid."),+ new ForgeDiagnosticDescriptor("standard-hole-invalid-end-condition", ForgeDiagnosticSeverity.Error, "Standard.Hole endCondition is unsupported.", "Raised when endCondition metadata is invalid.")+ ],+ CapabilityRequirements: ["Standard.Hole.LoweringMetadata"],+ LoweringContracts:+ [+ new ForgeLoweringContractDescriptor("Standard.Hole.ToAirHoleFeature", "Standard.Hole", "AirHoleFeature", ["Standard.Hole.LoweringMetadata"], "Metadata contract permitting Standard.Hole to describe AirHoleFeature lowering targets without executing lowering.")+ ],+ Examples: [],+ Fixtures: [],+ LlmGuidance: [],+ ManufacturingAssumptions: ["Descriptor scaffold only; no standards-table or tap/thread geometry assumptions are encoded."],+ DerivedFields: [],+ ValidationRuleIds: ["standard-hole-missing-entry-face", "standard-hole-invalid-center", "standard-hole-invalid-diameter", "standard-hole-invalid-end-condition"]);+}diff --git a/Aetheris.Kernel.Core.Tests/Brep/Features/ForgeDescriptorValidationTests.cs b/Aetheris.Kernel.Core.Tests/Brep/Features/ForgeDescriptorValidationTests.csnew file mode 100644index 00000000..45f47b90--- /dev/null+++ b/Aetheris.Kernel.Core.Tests/Brep/Features/ForgeDescriptorValidationTests.cs@@ -0,0 +1,104 @@+using Aetheris.Forge.Abstractions;+using Aetheris.Forge.Examples;++namespace Aetheris.Kernel.Core.Tests.Brep.Features;++public sealed class ForgeDescriptorValidationTests+{+ [Fact]+ public void StandardHolePackageDescriptor_IsValid()+ {+ var result = ForgeDescriptorValidator.Validate(StandardHoleForgeDescriptor.CreatePackage());+ Assert.True(result.IsValid, string.Join(Environment.NewLine, result.Diagnostics));+ }++ [Fact]+ public void MissingPackageId_FailsDeterministically()+ {+ var package = StandardHoleForgeDescriptor.CreatePackage() with { PackageId = "" };+ AssertCodes(package, "forge.package.missing-id");+ }++ [Fact]+ public void DuplicateConceptIds_FailDeterministically()+ {+ var concept = StandardHoleForgeDescriptor.CreateConcept();+ var package = StandardHoleForgeDescriptor.CreatePackage() with { Concepts = [concept, concept] };+ AssertCodes(package, "forge.package.duplicate-concept-id");+ }++ [Fact]+ public void MissingConceptId_FailsDeterministically()+ {+ var concept = StandardHoleForgeDescriptor.CreateConcept() with { ConceptId = "" };+ var package = StandardHoleForgeDescriptor.CreatePackage() with { Concepts = [concept] };+ AssertCodes(package, "forge.concept.missing-id");+ }++ [Fact]+ public void DuplicateFieldNames_FailDeterministically()+ {+ var field = new ForgeFieldDescriptor("entryFace", ForgeFieldType.FaceSelector, true, null, "Duplicate test field.");+ var concept = StandardHoleForgeDescriptor.CreateConcept() with { Fields = [field, field] };+ var package = StandardHoleForgeDescriptor.CreatePackage() with { Concepts = [concept] };+ AssertCodes(package, "forge.concept.duplicate-field-name");+ }++ [Fact]+ public void MissingDiagnosticId_FailsDeterministically()+ {+ var diagnostic = new ForgeDiagnosticDescriptor("", ForgeDiagnosticSeverity.Error, "message", "description");+ var concept = StandardHoleForgeDescriptor.CreateConcept() with { Diagnostics = [diagnostic] };+ var package = StandardHoleForgeDescriptor.CreatePackage() with { Concepts = [concept] };+ AssertCodes(package, "forge.diagnostic.missing-id");+ }++ [Fact]+ public void UnknownTemplateReferencedConcept_FailsDeterministically()+ {+ var template = new ForgeTemplateDescriptor(+ "Standard.HoleTemplate",+ "Hole Template",+ "Template references a missing concept for validation coverage.",+ Parameters: [],+ ConceptRequirements: ["Standard.MissingConcept"],+ ExpandsToConceptIds: [],+ Diagnostics: [],+ Examples: [],+ Fixtures: [],+ LlmGuidance: []);+ var package = StandardHoleForgeDescriptor.CreatePackage() with { Templates = [template] };+ AssertCodes(package, "forge.template.unknown-concept-id");+ }++ [Fact]+ public void LoweringContractMetadata_TargetsAirHoleFeatureWithoutExecution()+ {+ var contract = StandardHoleForgeDescriptor.CreateConcept().LoweringContracts.Single();+ Assert.Equal("AirHoleFeature", contract.TargetAirFeatureFamily);+ Assert.Equal("Standard.Hole.ToAirHoleFeature", contract.ContractId);+ }++ [Fact]+ public void TrustTierNamesAndValues_AreStableAndValidated()+ {+ Assert.Equal(1, (int)ForgeTrustTier.SemanticDocsOnly);+ Assert.Equal(2, (int)ForgeTrustTier.ValidationDerivation);+ Assert.Equal(3, (int)ForgeTrustTier.LoweringProvider);+ Assert.Equal(4, (int)ForgeTrustTier.MaterializerProvider);+ Assert.Equal(5, (int)ForgeTrustTier.UnsafeNativeExperimental);++ var package = StandardHoleForgeDescriptor.CreatePackage() with { RequestedTrustTier = (ForgeTrustTier)99 };+ AssertCodes(package, "forge.trust-tier.invalid");+ }++ private static void AssertCodes(ForgePackageDescriptor package, params string[] expectedCodes)+ {+ var result = ForgeDescriptorValidator.Validate(package);+ var codes = result.Diagnostics.Select(d => d.Code).ToArray();+ Assert.False(result.IsValid);+ Assert.Equal(codes.Order(StringComparer.Ordinal), codes);+ foreach (var expectedCode in expectedCodes)+ Assert.Contains(expectedCode, codes);+ }+}diff --git a/docs/audits/forge-a0-semantic-extension-architecture-audit.md b/docs/audits/forge-a0-semantic-extension-architecture-audit.mdindex 2d010a35..63e9aa4e 100644--- a/docs/audits/forge-a0-semantic-extension-architecture-audit.md+++ b/docs/audits/forge-a0-semantic-extension-architecture-audit.md@@ -471,3 +471,5 @@ This milestone explicitly does not include:- parser/lowering/kernel behavior changes;- migration of old Forge code into a public semantic SDK;- weakening or deleting existing tests.++See also: [FORGE-X1 concept/template descriptor scaffold](../implementation/forge-x1-concept-template-descriptor-scaffold.md).diff --git a/docs/implementation/forge-x1-concept-template-descriptor-scaffold.md b/docs/implementation/forge-x1-concept-template-descriptor-scaffold.mdnew file mode 100644index 00000000..0ef0af29--- /dev/null+++ b/docs/implementation/forge-x1-concept-template-descriptor-scaffold.md@@ -0,0 +1,76 @@+# FORGE-X1 concept/template descriptor scaffold++FORGE-X1 adds the first production scaffold for Forge semantic extension descriptors. It follows the FORGE-A0 direction that Forge packages are semantic CAD concept/template packs, not arbitrary geometry plug-ins.++## What was added++The scaffold lives in the existing `Aetheris.Forge` project under the `Aetheris.Forge.Abstractions` namespace. This keeps the milestone lightweight and lets the descriptor model coexist with the current Forge geometry helpers without migrating or deleting them.++Descriptor families now cover:++- `ForgePackageDescriptor`+- `ForgeConceptDescriptor`+- `ForgeTemplateDescriptor`+- `ForgeFieldDescriptor`+- `ForgeDiagnosticDescriptor`+- `ForgeCapabilityDescriptor`+- `ForgeLoweringContractDescriptor`+- `ForgeExampleDescriptor`+- `ForgeFixtureDescriptor`+- `ForgeLlmGuidanceDescriptor`++`ForgeDescriptorValidator` performs deterministic metadata validation and returns stable diagnostic codes/paths/messages. It validates required ids, id shape, semantic versions, duplicate concepts/templates/capabilities/fields/diagnostics, invalid enum values, unknown same-package template concept references, and lowering contracts that reference undeclared capabilities.++## Trust tiers++FORGE-X1 encodes the FORGE-A0 trust model as metadata only:++1. `SemanticDocsOnly`+2. `ValidationDerivation`+3. `LoweringProvider`+4. `MaterializerProvider`+5. `UnsafeNativeExperimental`++The validator rejects undefined tier enum values. Declaring a capability or requested package tier does not load code, execute code, or grant trust.++## Built-in Standard.Hole example descriptor++`Aetheris.Forge.Examples.StandardHoleForgeDescriptor` provides a descriptor validation fixture for package `Aetheris.Standard` and concept `Standard.Hole`. Its fields mirror descriptor-level equivalents of recent semantic-hole work:++- `entryFace`: `FaceSelector`, required+- `center`: `FaceLocalPoint2D`, required+- `shaftDiameter`: `Length`, required+- `endCondition`: `HoleEndCondition`, required++The example includes diagnostic metadata and a lowering contract whose target AIR feature family is `AirHoleFeature`. This is contract metadata only; no lowerer is invoked.++## Deferred work++FORGE-X1 intentionally does not implement:++- dynamic NuGet package loading;+- assembly scanning;+- plug-in execution;+- runtime package trust decisions;+- parser grammar extension or Firmament source integration;+- Standard Library behavior changes;+- fastener, ISO, ASME, thread, or tap standards tables;+- BRep/materializer extension APIs;+- lowering execution;+- STEP, DisplayIR, frontend, or product behavior changes.++## Relationship to FORGE-A0++FORGE-A0 recommended evolving Forge into a semantic CAD extension SDK made of concepts, templates, validators, semantic feature schemas, lowering contracts, examples, fixtures, and LLM guidance. FORGE-X1 implements the first stable descriptor/validation layer for that architecture while preserving the old Forge project behavior.++## Validation commands++Run these checks for this milestone:++```bash+dotnet restore Aetheris.slnx+dotnet build Aetheris.slnx -f net10.0 --no-restore /m:1+dotnet test Aetheris.slnx -f net10.0 --no-build --filter "Forge|Standard|Hole|FirmamentV2|Air"+git diff --check+git status --short+```