Skip to content

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.cs
new file mode 100644
index 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.cs
new file mode 100644
index 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.cs
new file mode 100644
index 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.cs
new file mode 100644
index 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.md
index 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.md
new file mode 100644
index 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
+```