Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Add Firmament V2 inline canonical STEP wrapper

Yuechen Li17dd11893beb
diff --git a/Aetheris.Kernel.Firmament.Tests/FirmamentV2InlineStepTests.cs b/Aetheris.Kernel.Firmament.Tests/FirmamentV2InlineStepTests.cs
new file mode 100644
index 00000000..aac27f3a
--- /dev/null
+++ b/Aetheris.Kernel.Firmament.Tests/FirmamentV2InlineStepTests.cs
@@ -0,0 +1,83 @@
+using Aetheris.Kernel.Core.Step242;
+using Aetheris.Kernel.Firmament.FirmamentV2;
+
+namespace Aetheris.Kernel.Firmament.Tests;
+
+public sealed class FirmamentV2InlineStepTests
+{
+ private const string FixturePath = "fixtures/FirmamentV2/InlineStep/valid/inline-step-v2-canonical-box-reexport-step-verified.valid.firmfixture";
+ private const string InputStepPath = "fixtures/FirmamentV2/InlineStep/testdata/canonical-box-10x8x6.step";
+
+ [Fact]
+ public void InlineStep_CanonicalBox_ReexportsAndRoundTripsThroughAp242()
+ {
+ var repo = FindRepoRoot();
+ var outputPath = Path.Combine(Path.GetTempPath(), $"aetheris-inline-step-x1-{Guid.NewGuid():N}.step");
+ try
+ {
+ var result = FirmamentBuildAndExport.Run(Path.Combine(repo, FixturePath), outputPath);
+
+ Assert.True(result.IsSuccess, string.Join(Environment.NewLine, result.Diagnostics.Select(d => $"{d.Source}: {d.Message}")));
+ Assert.True(File.Exists(outputPath));
+ Assert.Equal("inline-step", result.Value.Export.ExportedBodyCategory);
+ Assert.Equal("aetheris-canonical-ap242", result.Value.Export.ExportedFeatureKind);
+
+ var output = File.ReadAllText(outputPath);
+ Assert.Contains("ADVANCED_FACE", output, StringComparison.Ordinal);
+ Assert.Contains("VERTEX_POINT", output, StringComparison.Ordinal);
+ Assert.True(Count(output, "ADVANCED_FACE") > 0);
+ Assert.True(Count(output, "VERTEX_POINT") > 0);
+ Assert.Contains("MANIFOLD_SOLID_BREP", output, StringComparison.Ordinal);
+ Assert.DoesNotContain("trace-only", output, StringComparison.OrdinalIgnoreCase);
+ Assert.NotEqual(File.ReadAllText(Path.Combine(repo, InputStepPath)), output);
+
+ var import = Step242Importer.ImportBody(output);
+ Assert.True(import.IsSuccess, string.Join(Environment.NewLine, import.Diagnostics.Select(d => $"{d.Source}: {d.Message}")));
+ Assert.Equal(6, import.Value.Topology.Faces.Count());
+ Assert.Equal(8, import.Value.Topology.Vertices.Count());
+ Assert.Equal(12, import.Value.Topology.Edges.Count());
+ Assert.Equal(480d, ComputeBoxVolume(import.Value), precision: 8);
+ }
+ finally
+ {
+ if (File.Exists(outputPath)) File.Delete(outputPath);
+ }
+ }
+
+ [Fact]
+ public void InlineStep_NonCanonicalStep_IsRejectedWithDeterministicDiagnostic()
+ {
+ var source = """
+model BadInlineStep {
+ units mm
+
+ solid importedPart: InlineStep {
+ path: "../../../../testdata/step242/generated/v0-required/gen_box_v0.step"
+ }
+}
+""";
+
+ var parse = FirmamentV2Parser.Parse(source, Path.Combine(FindRepoRoot(), "fixtures/FirmamentV2/InlineStep/valid"));
+
+ Assert.False(parse.IsSuccess);
+ Assert.Contains(FirmamentV2Parser.InlineStepRequiresCanonical, parse.Diagnostics);
+ }
+
+ private static string FindRepoRoot()
+ {
+ var dir = new DirectoryInfo(AppContext.BaseDirectory);
+ while (dir is not null && !File.Exists(Path.Combine(dir.FullName, "Aetheris.slnx"))) dir = dir.Parent;
+ return dir?.FullName ?? throw new InvalidOperationException("Could not locate repository root.");
+ }
+
+ private static int Count(string text, string needle) => text.Split(needle, StringSplitOptions.None).Length - 1;
+
+ private static double ComputeBoxVolume(Aetheris.Kernel.Core.Brep.BrepBody body)
+ {
+ var points = body.Topology.Vertices.Select(v => body.TryGetVertexPoint(v.Id, out var p) ? p : throw new InvalidOperationException("Missing vertex point.")).ToArray();
+ var minX = points.Min(p => p.X); var maxX = points.Max(p => p.X);
+ var minY = points.Min(p => p.Y); var maxY = points.Max(p => p.Y);
+ var minZ = points.Min(p => p.Z); var maxZ = points.Max(p => p.Z);
+ return (maxX - minX) * (maxY - minY) * (maxZ - minZ);
+ }
+}
diff --git a/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs b/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs
index 0bb8833e..3fb691b7 100644
--- a/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs
+++ b/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs
@@ -23,7 +23,7 @@ public static class FirmamentBuildAndExport
var fullSourcePath = Path.GetFullPath(sourcePath);
var sourceText = NormalizeLf(File.ReadAllText(fullSourcePath, Encoding.UTF8));
- var exportResult = ExportSource(sourceText);
+ var exportResult = ExportSource(sourceText, Path.GetDirectoryName(fullSourcePath));
if (!exportResult.IsSuccess)
{
return KernelResult<FirmamentBuildAndExportResult>.Failure(exportResult.Diagnostics);
@@ -44,9 +44,9 @@ public static class FirmamentBuildAndExport
}
- private static KernelResult<FirmamentStepExportResult> ExportSource(string sourceText)
+ private static KernelResult<FirmamentStepExportResult> ExportSource(string sourceText, string? sourceDirectory = null)
{
- var v2Parse = FirmamentV2Parser.Parse(sourceText);
+ var v2Parse = FirmamentV2Parser.Parse(sourceText, sourceDirectory);
if (v2Parse.IsSuccess && v2Parse.Document is not null)
{
var dfm = FirmamentV2DfmEnforcement.Validate(v2Parse.Document);
@@ -65,6 +65,11 @@ public static class FirmamentBuildAndExport
return sideHoleExport;
}
+ if (TryExportV2InlineStepBody(v2Parse.Document) is { } inlineStepExport)
+ {
+ return inlineStepExport;
+ }
+
var lowering = FirmamentV2BuildLowering.LowerPrimitiveBridge(v2Parse.Document);
if (!lowering.IsSuccess)
{
@@ -101,9 +106,68 @@ public static class FirmamentBuildAndExport
DimensionInspection: []));
}
+ if (v2Parse.Diagnostics.Contains(FirmamentV2Parser.InlineStepRequiresCanonical, StringComparer.Ordinal))
+ {
+ return KernelResult<FirmamentStepExportResult>.Failure([new Kernel.Core.Diagnostics.KernelDiagnostic(
+ Kernel.Core.Diagnostics.KernelDiagnosticCode.ValidationFailed,
+ Kernel.Core.Diagnostics.KernelDiagnosticSeverity.Error,
+ "firmament-inline-step-requires-aetheris-canonical-step: Inline STEP requires an Aetheris-canonical AP242 file. Run `aetheris canon <input.step> --out <canonical.step>` first.",
+ "FirmamentV2.InlineStep")]);
+ }
+
+ if (v2Parse.Diagnostics.Any(d => d.StartsWith("firmament-v2-inline-step-", StringComparison.Ordinal)))
+ {
+ return KernelResult<FirmamentStepExportResult>.Failure(v2Parse.Diagnostics.Select(d => new Kernel.Core.Diagnostics.KernelDiagnostic(
+ Kernel.Core.Diagnostics.KernelDiagnosticCode.ValidationFailed,
+ Kernel.Core.Diagnostics.KernelDiagnosticSeverity.Error,
+ d,
+ "FirmamentV2.InlineStep")).ToArray());
+ }
+
return FirmamentStepExporter.Export(new FirmamentCompileRequest(new FirmamentSourceDocument(sourceText)));
}
+ private static KernelResult<FirmamentStepExportResult>? TryExportV2InlineStepBody(FirmamentV2Document document)
+ {
+ if (document.Solids.Count != 1)
+ {
+ return null;
+ }
+
+ var solid = document.Solids[0];
+ if (solid.Primitive is not FirmamentV2InlineStepRecord inlineStep)
+ {
+ return null;
+ }
+
+ var stepText = File.ReadAllText(inlineStep.NormalizedPath, Encoding.UTF8);
+ var import = Step242Importer.ImportBody(stepText);
+ if (!import.IsSuccess)
+ {
+ return KernelResult<FirmamentStepExportResult>.Failure(import.Diagnostics);
+ }
+
+ var export = Step242Exporter.ExportBody(import.Value, new Step242ExportOptions
+ {
+ ProductName = solid.Name,
+ ApplicationName = "Aetheris.Firmament.InlineStep"
+ });
+ if (!export.IsSuccess)
+ {
+ return KernelResult<FirmamentStepExportResult>.Failure(export.Diagnostics);
+ }
+
+ return KernelResult<FirmamentStepExportResult>.Success(
+ new FirmamentStepExportResult(
+ export.Value,
+ solid.Name,
+ 0,
+ "inline-step",
+ "aetheris-canonical-ap242",
+ DatumInspection: [],
+ DimensionInspection: []));
+ }
+
private static KernelResult<FirmamentStepExportResult>? TryExportV2ControlledSideHoleBody(FirmamentV2Document document)
{
var intent = document.SideHoleIntent;
diff --git a/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Ast.cs b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Ast.cs
index 8e9b75d6..76cd4874 100644
--- a/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Ast.cs
+++ b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Ast.cs
@@ -19,6 +19,7 @@ public sealed record FirmamentV2SolidBinding(string Name, string RecordType, Fir
public FirmamentV2ConeRecord? Cone => Primitive as FirmamentV2ConeRecord;
public FirmamentV2SphereRecord? Sphere => Primitive as FirmamentV2SphereRecord;
public FirmamentV2TorusRecord? Torus => Primitive as FirmamentV2TorusRecord;
+ public FirmamentV2InlineStepRecord? InlineStep => Primitive as FirmamentV2InlineStepRecord;
}
public abstract record FirmamentV2PrimitiveRecord;
@@ -27,6 +28,7 @@ public sealed record FirmamentV2CylinderRecord(double Radius, double Height) : F
public sealed record FirmamentV2ConeRecord(double BottomRadius, double TopRadius, double Height) : FirmamentV2PrimitiveRecord;
public sealed record FirmamentV2SphereRecord(double Radius) : FirmamentV2PrimitiveRecord;
public sealed record FirmamentV2TorusRecord(double MajorRadius, double MinorRadius) : FirmamentV2PrimitiveRecord;
+public sealed record FirmamentV2InlineStepRecord(string SourcePath, string NormalizedPath, string ContentHash, bool CanonicalInput, string CanonicalEvidence) : FirmamentV2PrimitiveRecord;
public sealed record FirmamentV2Exposure(string Alias, string SelectorKind, string Selector, string RefType, string Axis, string? Subselector);
public sealed record FirmamentV2FaceTarget(string Source, string Kind, string Axis, string ResolvedSelector, string RefType)
{
diff --git a/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Parser.cs b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Parser.cs
index 82b39a29..6a0f9dd3 100644
--- a/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Parser.cs
+++ b/Aetheris.Kernel.Firmament/FirmamentV2/FirmamentV2Parser.cs
@@ -1,4 +1,6 @@
using System.Globalization;
+using System.Security.Cryptography;
+using System.Text;
using System.Text.RegularExpressions;
using Aetheris.Kernel.Core.Air;
@@ -74,6 +76,10 @@ public static class FirmamentV2Parser
public const string PmiTargetUnresolved = "firmament-v2-pmi-target-unresolved";
public const string PmiDiameterInvalid = "firmament-v2-pmi-diameter-invalid";
public const string PmiDuplicateName = "firmament-v2-pmi-duplicate-name";
+ public const string InlineStepPathMissing = "firmament-v2-inline-step-path-missing";
+ public const string InlineStepPathInvalid = "firmament-v2-inline-step-path-invalid";
+ public const string InlineStepFileMissing = "firmament-v2-inline-step-file-missing";
+ public const string InlineStepRequiresCanonical = "firmament-inline-step-requires-aetheris-canonical-step";
private static readonly Regex ModelRegex = new(@"\bmodel\s+(?<name>[A-Za-z_][A-Za-z0-9_]*)\s*\{", RegexOptions.CultureInvariant);
private static readonly Regex UnitsRegex = new(@"\bunits\s+(?<units>[A-Za-z_][A-Za-z0-9_]*)\b", RegexOptions.CultureInvariant);
@@ -98,8 +104,11 @@ public static class FirmamentV2Parser
private static readonly Regex ValueRegex = new(@"\b(?:value|diameter)\s*:\s*(?<value>[^\s}]+)", RegexOptions.CultureInvariant);
private static readonly Regex TemplateHeaderRegex = new(@"\btemplate\s*<\s*(?<process>[A-Za-z_][A-Za-z0-9_]*)\s*>\s+(?<name>[A-Za-z_][A-Za-z0-9_]*)\s*\{", RegexOptions.CultureInvariant);
private static readonly Regex ConceptRegex = new(@"\bconcept\s+(?<name>[A-Za-z_][A-Za-z0-9_]*)\s*:\s*(?<value>[-+0-9.eE]+)\s*(?<unit>[A-Za-z_][A-Za-z0-9_]*)?", RegexOptions.CultureInvariant);
+ private static readonly Regex PathRegex = new("\\bpath\\s*:\\s*\"(?<path>[^\"]+)\"", RegexOptions.CultureInvariant);
- public static FirmamentV2ParseResult Parse(string sourceText)
+ public static FirmamentV2ParseResult Parse(string sourceText) => Parse(sourceText, null);
+
+ public static FirmamentV2ParseResult Parse(string sourceText, string? sourceDirectory)
{
ArgumentNullException.ThrowIfNull(sourceText);
var diagnostics = new List<string> { "firmament-v2-parser-invoked" };
@@ -133,7 +142,7 @@ public static class FirmamentV2Parser
FirmamentV2SolidBinding? binding = isWith
? ParseDerived(name, target, body, byName, diagnostics)
- : ParseDirect(name, target, body, diagnostics);
+ : ParseDirect(name, target, body, diagnostics, sourceDirectory);
if (binding is not null)
{
solids.Add(binding);
@@ -155,7 +164,7 @@ public static class FirmamentV2Parser
return document is null ? FirmamentV2ParseResult.Failure(diagnostics) : FirmamentV2ParseResult.Success(document, diagnostics);
}
- private static FirmamentV2SolidBinding? ParseDirect(string name, string recordType, string body, List<string> diagnostics)
+ private static FirmamentV2SolidBinding? ParseDirect(string name, string recordType, string body, List<string> diagnostics, string? sourceDirectory)
{
if (string.Equals(recordType, "Box", StringComparison.Ordinal))
{
@@ -164,6 +173,11 @@ public static class FirmamentV2Parser
return values is null ? null : new(name, "Box", new FirmamentV2BoxRecord(values, exposures));
}
+ if (string.Equals(recordType, "InlineStep", StringComparison.Ordinal))
+ {
+ return ParseInlineStep(name, body, diagnostics, sourceDirectory);
+ }
+
if (recordType is not ("Cylinder" or "Cone" or "Sphere" or "Torus")) { diagnostics.Add(UnknownRecordType); return null; }
var scalars = ParseScalarFields(body, diagnostics);
@@ -182,6 +196,51 @@ public static class FirmamentV2Parser
: new(name, recordType, primitive);
}
+ private static FirmamentV2SolidBinding? ParseInlineStep(string name, string body, List<string> diagnostics, string? sourceDirectory)
+ {
+ var match = PathRegex.Match(body);
+ if (!match.Success) { diagnostics.Add(InlineStepPathMissing); return null; }
+
+ var sourcePath = match.Groups["path"].Value;
+ if (Path.IsPathRooted(sourcePath))
+ {
+ diagnostics.Add(InlineStepPathInvalid);
+ return null;
+ }
+
+ var baseDirectory = string.IsNullOrWhiteSpace(sourceDirectory) ? Directory.GetCurrentDirectory() : sourceDirectory;
+ var normalizedPath = Path.GetFullPath(Path.Combine(baseDirectory!, sourcePath));
+ if (!File.Exists(normalizedPath))
+ {
+ diagnostics.Add(InlineStepFileMissing);
+ return null;
+ }
+
+ var stepText = File.ReadAllText(normalizedPath, Encoding.UTF8);
+ if (!IsAetherisCanonicalStep(stepText, out var evidence))
+ {
+ diagnostics.Add(InlineStepRequiresCanonical);
+ return null;
+ }
+
+ var hash = Convert.ToHexString(SHA256.HashData(Encoding.UTF8.GetBytes(stepText))).ToLowerInvariant();
+ return new FirmamentV2SolidBinding(name, "InlineStep", new FirmamentV2InlineStepRecord(sourcePath, normalizedPath, hash, true, evidence));
+ }
+
+ private static bool IsAetherisCanonicalStep(string stepText, out string evidence)
+ {
+ if (stepText.Contains("Aetheris AP242 subset export", StringComparison.Ordinal)
+ && stepText.Contains("Aetheris.Kernel", StringComparison.Ordinal)
+ && stepText.Contains("FILE_SCHEMA(('AP242_MANAGED_MODEL_BASED_3D_ENGINEERING_MIM_LF'))", StringComparison.Ordinal))
+ {
+ evidence = "aetheris-ap242-subset-export-header";
+ return true;
+ }
+
+ evidence = string.Empty;
+ return false;
+ }
+
private static FirmamentV2SolidBinding? ParseDerived(string name, string baseName, string body, Dictionary<string, FirmamentV2SolidBinding> byName, List<string> diagnostics)
{
if (!byName.TryGetValue(baseName, out var baseSolid)) { diagnostics.Add(NameUnresolved); if (Regex.IsMatch(body, @"\bsize\s*:", RegexOptions.CultureInvariant)) diagnostics.Add(WithForwardReference); return null; }
@@ -196,7 +255,7 @@ public static class FirmamentV2Parser
return new(name, "Box", new FirmamentV2BoxRecord(values, []), baseName, new Dictionary<string, IReadOnlyList<double>>(StringComparer.Ordinal) { ["size"] = values });
}
- private static bool IsFatalDiagnostic(string code) => code is PrimitiveFieldMissing or PrimitiveFieldUnknown or PrimitiveFieldInvalid or MissingModel or MissingUnits or MissingSolid or UnsupportedConstruct or UnknownRecordType or BoxMissingSize or BoxSizeArity or DegenerateDimension or NameUnresolved or DuplicateName or WithRequiresRecord or WithRequiresBoxRecord or WithFieldNotFound or WithFieldTypeMismatch or WithForwardReference or WithDerivedRecordInvalid or ExposeBlockUnsupported or ExposeRequiresBoxRecord or ExposeAliasDuplicate or ExposeAliasInvalid or SelectorUnsupported or SelectorAxisInvalid or SelectorSubselectorUnsupported or FatArrowOutsideExpose or RawBackendIdReferenceForbidden or ModifyTargetUnresolved or ModifyTargetNotSolid or RegionUnsupported or RegionAttachmentSelectorUnsupported or CutUnsupported or CutToolUnsupported or CylinderRadiusMissing or CylinderRadiusInvalid or CylinderRadiusNotFinite or ThroughSelectorUnsupported or AliasUnresolved or AliasRefTypeUnsupported or SideHoleAliasMustResolveToFace or SideHoleAliasResolvesToUnsupportedFace or SideHoleOnlyPlusXMinusXSupported or SideHoleRouteUnsupported or SideHoleSameFaceUnsupported or SideHoleAxisNotYetSupported or SideHoleRadiusExceedsClearance or CylinderCenterInvalid or CylinderCenterArityInvalid or CylinderCenterNotFinite or SideHoleCenterExceedsClearance or HoleVariantUnknown or HoleEntryFaceMissing or HoleCenterMissing or HoleShaftMissing or HoleEndMissing or HoleDiameterInvalid or HoleDepthInvalid or HoleCounterboreInvalid or HoleCountersinkInvalid or PmiKindUnknown or PmiTargetMissing or PmiTargetUnresolved or PmiDiameterInvalid or PmiDuplicateName;
+ private static bool IsFatalDiagnostic(string code) => code is PrimitiveFieldMissing or PrimitiveFieldUnknown or PrimitiveFieldInvalid or MissingModel or MissingUnits or MissingSolid or UnsupportedConstruct or UnknownRecordType or BoxMissingSize or BoxSizeArity or DegenerateDimension or NameUnresolved or DuplicateName or WithRequiresRecord or WithRequiresBoxRecord or WithFieldNotFound or WithFieldTypeMismatch or WithForwardReference or WithDerivedRecordInvalid or ExposeBlockUnsupported or ExposeRequiresBoxRecord or ExposeAliasDuplicate or ExposeAliasInvalid or SelectorUnsupported or SelectorAxisInvalid or SelectorSubselectorUnsupported or FatArrowOutsideExpose or RawBackendIdReferenceForbidden or ModifyTargetUnresolved or ModifyTargetNotSolid or RegionUnsupported or RegionAttachmentSelectorUnsupported or CutUnsupported or CutToolUnsupported or CylinderRadiusMissing or CylinderRadiusInvalid or CylinderRadiusNotFinite or ThroughSelectorUnsupported or AliasUnresolved or AliasRefTypeUnsupported or SideHoleAliasMustResolveToFace or SideHoleAliasResolvesToUnsupportedFace or SideHoleOnlyPlusXMinusXSupported or SideHoleRouteUnsupported or SideHoleSameFaceUnsupported or SideHoleAxisNotYetSupported or SideHoleRadiusExceedsClearance or CylinderCenterInvalid or CylinderCenterArityInvalid or CylinderCenterNotFinite or SideHoleCenterExceedsClearance or HoleVariantUnknown or HoleEntryFaceMissing or HoleCenterMissing or HoleShaftMissing or HoleEndMissing or HoleDiameterInvalid or HoleDepthInvalid or HoleCounterboreInvalid or HoleCountersinkInvalid or PmiKindUnknown or PmiTargetMissing or PmiTargetUnresolved or PmiDiameterInvalid or PmiDuplicateName or InlineStepPathMissing or InlineStepPathInvalid or InlineStepFileMissing or InlineStepRequiresCanonical;
private static IReadOnlyList<FirmamentV2Exposure> ParseExposures(string body, List<string> diagnostics)
{
diff --git a/docs/audits/inline-step-a0-strangler-fig-migration-audit.md b/docs/audits/inline-step-a0-strangler-fig-migration-audit.md
index d3442a84..1c1c720e 100644
--- a/docs/audits/inline-step-a0-strangler-fig-migration-audit.md
+++ b/docs/audits/inline-step-a0-strangler-fig-migration-audit.md
@@ -299,3 +299,7 @@ Open questions:
- No guarantee that source STEP entity IDs are stable across arbitrary external re-export.
- No change to STEP import/export behavior in this milestone.
- No change to Firmament lowering, BRep/materializer behavior, or product behavior in this milestone.
+
+## X1 correction: canonical STEP only
+
+INLINE-STEP-X1 narrows the first implementation milestone: Firmament inline STEP source is **Aetheris-canonical AP242 STEP**, not arbitrary raw vendor STEP. Raw external/vendor STEP remains input to `aetheris canon`; Firmament wraps the canonicalized artifact and re-exports it through `Step242Importer` and `Step242Exporter`. See `docs/implementation/inline-step-x1-canonical-step-wrapper.md`.
diff --git a/docs/implementation/inline-step-x1-canonical-step-wrapper.md b/docs/implementation/inline-step-x1-canonical-step-wrapper.md
new file mode 100644
index 00000000..52ab90df
--- /dev/null
+++ b/docs/implementation/inline-step-x1-canonical-step-wrapper.md
@@ -0,0 +1,78 @@
+# INLINE-STEP-X1 canonical STEP wrapper
+
+INLINE-STEP-X1 adds the smallest Firmament V2 path for wrapping one existing Aetheris-canonical AP242 STEP body and re-exporting it through the real Aetheris import/export pipeline.
+
+## Syntax
+
+The supported syntax follows the existing Firmament V2 typed-record style:
+
+```firmament
+solid importedPart: InlineStep {
+ path: "../testdata/canonical-box-10x8x6.step"
+}
+```
+
+The symbol name (`importedPart`) is preserved as the exported STEP product name. The `path` is preserved in the parsed InlineStep record along with a normalized path, SHA-256 content hash, canonical-input flag, and canonical evidence string.
+
+## Canonical STEP requirement
+
+Inline STEP input must be Aetheris-canonical AP242. Raw external/vendor STEP remains import/canon input, not Firmament source. The intended flow is:
+
+```text
+external/vendor STEP -> aetheris canon -> Aetheris-canonical STEP -> Firmament InlineStep -> AP242 re-export
+```
+
+X1 detects canonical input using the current Aetheris exporter header evidence:
+
+- `FILE_DESCRIPTION(('Aetheris AP242 subset export'), ...)`
+- `FILE_NAME(... 'Aetheris.Kernel','Aetheris.Kernel', ...)`
+- AP242 managed-model schema
+
+Non-canonical or unrecognized STEP is rejected with `firmament-inline-step-requires-aetheris-canonical-step`. User-facing diagnostics should direct authors to run `aetheris canon <input.step> --out <canonical.step>` first.
+
+## Fixture
+
+Valid wrapper fixture:
+
+- `fixtures/FirmamentV2/InlineStep/valid/inline-step-v2-canonical-box-reexport-step-verified.valid.firmfixture`
+
+Canonical input STEP fixture:
+
+- `fixtures/FirmamentV2/InlineStep/testdata/canonical-box-10x8x6.step`
+
+The input fixture is a 10 x 8 x 6 mm box generated by Aetheris, with expected volume `480`, `6` faces, `8` vertices, and `12` edges.
+
+## Real importer/exporter path
+
+The build path is intentionally not byte-preserving STEP editing:
+
+```text
+Firmament V2 InlineStep parse
+ -> resolve fixture-relative STEP path
+ -> verify Aetheris-canonical header evidence
+ -> Step242Importer.ImportBody(...)
+ -> BrepBody
+ -> Step242Exporter.ExportBody(...)
+ -> AP242 output
+ -> Step242Importer.ImportBody(...) verification
+```
+
+The AP242 output is canonicalized and is not expected to be byte-identical to the input STEP.
+
+## Verification checks
+
+Tests verify that the output exists, contains AP242 topology markers (`ADVANCED_FACE`, `VERTEX_POINT`), is not trace-only, reimports through `Step242Importer`, and round-trips to the canonical box topology/volume.
+
+## Deferred features
+
+INLINE-STEP-X1 deliberately does not implement:
+
+- arbitrary raw external STEP inline support;
+- byte-preserving STEP edits;
+- semantic PMI on imported topology;
+- topology identity maps;
+- recognition labels;
+- replacement;
+- residual accounting;
+- graphical PMI;
+- multiple imported bodies or assembly STEP support.
diff --git a/fixtures/FirmamentV2/InlineStep/testdata/canonical-box-10x8x6.step b/fixtures/FirmamentV2/InlineStep/testdata/canonical-box-10x8x6.step
new file mode 100644
index 00000000..a7c01161
--- /dev/null
+++ b/fixtures/FirmamentV2/InlineStep/testdata/canonical-box-10x8x6.step
@@ -0,0 +1,172 @@
+ISO-10303-21;
+HEADER;
+FILE_DESCRIPTION(('Aetheris AP242 subset export'),'2;1');
+FILE_NAME('aetheris_export.step','1970-01-01T00:00:00',('Aetheris'),('Aetheris'),'Aetheris.Kernel','Aetheris.Kernel','');
+FILE_SCHEMA(('AP242_MANAGED_MODEL_BASED_3D_ENGINEERING_MIM_LF'));
+ENDSEC;
+DATA;
+#1=CARTESIAN_POINT($,(0,0,0));
+#2=DIRECTION($,(-0,-0,-1));
+#3=DIRECTION($,(1,0,0));
+#4=AXIS2_PLACEMENT_3D($,#1,#2,#3);
+#5=PLANE($,#4);
+#6=CARTESIAN_POINT($,(-5,-4,0));
+#7=VERTEX_POINT($,#6);
+#8=CARTESIAN_POINT($,(5,-4,-0));
+#9=VERTEX_POINT($,#8);
+#10=CARTESIAN_POINT($,(-5,-4,0));
+#11=DIRECTION($,(1,0,0));
+#12=VECTOR($,#11,1);
+#13=LINE($,#10,#12);
+#14=EDGE_CURVE($,#7,#9,#13,.T.);
+#15=ORIENTED_EDGE($,$,$,#14,.T.);
+#16=CARTESIAN_POINT($,(5,4,-0));
+#17=VERTEX_POINT($,#16);
+#18=CARTESIAN_POINT($,(5,-4,-0));
+#19=DIRECTION($,(0,1,0));
+#20=VECTOR($,#19,1);
+#21=LINE($,#18,#20);
+#22=EDGE_CURVE($,#9,#17,#21,.T.);
+#23=ORIENTED_EDGE($,$,$,#22,.T.);
+#24=CARTESIAN_POINT($,(-5,4,-0));
+#25=VERTEX_POINT($,#24);
+#26=CARTESIAN_POINT($,(5,4,-0));
+#27=DIRECTION($,(-1,0,0));
+#28=VECTOR($,#27,1);
+#29=LINE($,#26,#28);
+#30=EDGE_CURVE($,#17,#25,#29,.T.);
+#31=ORIENTED_EDGE($,$,$,#30,.T.);
+#32=CARTESIAN_POINT($,(-5,4,-0));
+#33=DIRECTION($,(0,-1,0));
+#34=VECTOR($,#33,1);
+#35=LINE($,#32,#34);
+#36=EDGE_CURVE($,#25,#7,#35,.T.);
+#37=ORIENTED_EDGE($,$,$,#36,.T.);
+#38=EDGE_LOOP($,(#15,#23,#31,#37));
+#39=FACE_OUTER_BOUND('',#38,.T.);
+#40=ADVANCED_FACE('',(#39),#5,.T.);
+#41=CARTESIAN_POINT($,(0,0,6));
+#42=DIRECTION($,(0,0,1));
+#43=DIRECTION($,(1,0,0));
+#44=AXIS2_PLACEMENT_3D($,#41,#42,#43);
+#45=PLANE($,#44);
+#46=CARTESIAN_POINT($,(-5,-4,6));
+#47=VERTEX_POINT($,#46);
+#48=CARTESIAN_POINT($,(5,-4,6));
+#49=VERTEX_POINT($,#48);
+#50=CARTESIAN_POINT($,(-5,-4,6));
+#51=DIRECTION($,(1,0,0));
+#52=VECTOR($,#51,1);
+#53=LINE($,#50,#52);
+#54=EDGE_CURVE($,#47,#49,#53,.T.);
+#55=ORIENTED_EDGE($,$,$,#54,.F.);
+#56=CARTESIAN_POINT($,(5,4,6));
+#57=VERTEX_POINT($,#56);
+#58=CARTESIAN_POINT($,(5,-4,6));
+#59=DIRECTION($,(0,1,0));
+#60=VECTOR($,#59,1);
+#61=LINE($,#58,#60);
+#62=EDGE_CURVE($,#49,#57,#61,.T.);
+#63=ORIENTED_EDGE($,$,$,#62,.F.);
+#64=CARTESIAN_POINT($,(-5,4,6));
+#65=VERTEX_POINT($,#64);
+#66=CARTESIAN_POINT($,(5,4,6));
+#67=DIRECTION($,(-1,0,0));
+#68=VECTOR($,#67,1);
+#69=LINE($,#66,#68);
+#70=EDGE_CURVE($,#57,#65,#69,.T.);
+#71=ORIENTED_EDGE($,$,$,#70,.F.);
+#72=CARTESIAN_POINT($,(-5,4,6));
+#73=DIRECTION($,(0,-1,0));
+#74=VECTOR($,#73,1);
+#75=LINE($,#72,#74);
+#76=EDGE_CURVE($,#65,#47,#75,.T.);
+#77=ORIENTED_EDGE($,$,$,#76,.F.);
+#78=EDGE_LOOP($,(#55,#63,#71,#77));
+#79=FACE_OUTER_BOUND('',#78,.T.);
+#80=ADVANCED_FACE('',(#79),#45,.T.);
+#81=CARTESIAN_POINT($,(-5,-4,0));
+#82=DIRECTION($,(0,-1,0));
+#83=DIRECTION($,(0,0,1));
+#84=AXIS2_PLACEMENT_3D($,#81,#82,#83);
+#85=PLANE($,#84);
+#86=ORIENTED_EDGE($,$,$,#14,.T.);
+#87=CARTESIAN_POINT($,(5,-4,-0));
+#88=DIRECTION($,(0,0,1));
+#89=VECTOR($,#88,1);
+#90=LINE($,#87,#89);
+#91=EDGE_CURVE($,#9,#49,#90,.T.);
+#92=ORIENTED_EDGE($,$,$,#91,.T.);
+#93=ORIENTED_EDGE($,$,$,#54,.F.);
+#94=CARTESIAN_POINT($,(-5,-4,0));
+#95=DIRECTION($,(0,0,1));
+#96=VECTOR($,#95,1);
+#97=LINE($,#94,#96);
+#98=EDGE_CURVE($,#7,#47,#97,.T.);
+#99=ORIENTED_EDGE($,$,$,#98,.F.);
+#100=EDGE_LOOP($,(#86,#92,#93,#99));
+#101=FACE_OUTER_BOUND('',#100,.T.);
+#102=ADVANCED_FACE('',(#101),#85,.T.);
+#103=CARTESIAN_POINT($,(5,-4,0));
+#104=DIRECTION($,(1,0,0));
+#105=DIRECTION($,(0,0,1));
+#106=AXIS2_PLACEMENT_3D($,#103,#104,#105);
+#107=PLANE($,#106);
+#108=ORIENTED_EDGE($,$,$,#22,.T.);
+#109=CARTESIAN_POINT($,(5,4,-0));
+#110=DIRECTION($,(0,0,1));
+#111=VECTOR($,#110,1);
+#112=LINE($,#109,#111);
+#113=EDGE_CURVE($,#17,#57,#112,.T.);
+#114=ORIENTED_EDGE($,$,$,#113,.T.);
+#115=ORIENTED_EDGE($,$,$,#62,.F.);
+#116=ORIENTED_EDGE($,$,$,#91,.F.);
+#117=EDGE_LOOP($,(#108,#114,#115,#116));
+#118=FACE_OUTER_BOUND('',#117,.T.);
+#119=ADVANCED_FACE('',(#118),#107,.T.);
+#120=CARTESIAN_POINT($,(5,4,0));
+#121=DIRECTION($,(0,1,-0));
+#122=DIRECTION($,(0,0,1));
+#123=AXIS2_PLACEMENT_3D($,#120,#121,#122);
+#124=PLANE($,#123);
+#125=ORIENTED_EDGE($,$,$,#30,.T.);
+#126=CARTESIAN_POINT($,(-5,4,-0));
+#127=DIRECTION($,(0,0,1));
+#128=VECTOR($,#127,1);
+#129=LINE($,#126,#128);
+#130=EDGE_CURVE($,#25,#65,#129,.T.);
+#131=ORIENTED_EDGE($,$,$,#130,.T.);
+#132=ORIENTED_EDGE($,$,$,#70,.F.);
+#133=ORIENTED_EDGE($,$,$,#113,.F.);
+#134=EDGE_LOOP($,(#125,#131,#132,#133));
+#135=FACE_OUTER_BOUND('',#134,.T.);
+#136=ADVANCED_FACE('',(#135),#124,.T.);
+#137=CARTESIAN_POINT($,(-5,4,0));
+#138=DIRECTION($,(-1,0,0));
+#139=DIRECTION($,(0,0,1));
+#140=AXIS2_PLACEMENT_3D($,#137,#138,#139);
+#141=PLANE($,#140);
+#142=ORIENTED_EDGE($,$,$,#36,.T.);
+#143=ORIENTED_EDGE($,$,$,#98,.T.);
+#144=ORIENTED_EDGE($,$,$,#76,.F.);
+#145=ORIENTED_EDGE($,$,$,#130,.F.);
+#146=EDGE_LOOP($,(#142,#143,#144,#145));
+#147=FACE_OUTER_BOUND('',#146,.T.);
+#148=ADVANCED_FACE('',(#147),#141,.T.);
+#149=CLOSED_SHELL($,(#40,#80,#102,#119,#136,#148));
+#150=MANIFOLD_SOLID_BREP('AetherisBody',#149);
+#151=APPLICATION_CONTEXT('mechanical design');
+#152=PRODUCT_CONTEXT('',#151,'mechanical');
+#153=PRODUCT('AETHERIS','AetherisBody','',(#152));
+#154=PRODUCT_DEFINITION_FORMATION('','',#153);
+#155=PRODUCT_DEFINITION_CONTEXT('design',#151,'design');
+#156=PRODUCT_DEFINITION('','',#154,#155);
+#157=PRODUCT_DEFINITION_SHAPE('','',#156);
+#158=(LENGTH_UNIT()NAMED_UNIT(*)SI_UNIT(.MILLI.,.METRE.));
+#159=(NAMED_UNIT(*)PLANE_ANGLE_UNIT()SI_UNIT($,.RADIAN.));
+#160=(NAMED_UNIT(*)SI_UNIT($,.STERADIAN.)SOLID_ANGLE_UNIT());
+#161=(GEOMETRIC_REPRESENTATION_CONTEXT(3)GLOBAL_UNIT_ASSIGNED_CONTEXT((#158,#159,#160))REPRESENTATION_CONTEXT('3','3D'));
+#162=SHAPE_REPRESENTATION('AetherisBody',(#150),#161);
+#163=SHAPE_DEFINITION_REPRESENTATION(#157,#162);
+ENDSEC;
+END-ISO-10303-21;
diff --git a/fixtures/FirmamentV2/InlineStep/valid/inline-step-v2-canonical-box-reexport-step-verified.valid.firmfixture b/fixtures/FirmamentV2/InlineStep/valid/inline-step-v2-canonical-box-reexport-step-verified.valid.firmfixture
new file mode 100644
index 00000000..a292d4bd
--- /dev/null
+++ b/fixtures/FirmamentV2/InlineStep/valid/inline-step-v2-canonical-box-reexport-step-verified.valid.firmfixture
@@ -0,0 +1,26 @@
+// fixture-id: inline-step-v2-canonical-box-reexport-step-verified
+// case: firmament-v2-inline-step-canonical-box-reexport
+// category: InlineStep
+// syntax-version: FirmamentV2
+// validity: valid
+// implementation: parser-backed
+// expected: valid
+// tier: inline-step
+// expected-stage: step-verified
+// current-stage: step-verified
+// feature-area: inline-step-wrapper
+// build-command: aetheris build
+// roundtrip-required: true
+// expected-volume: 480
+// expected-topology: faces=6, vertices=8, edges=12
+// canonical-input-required: true
+// input-step: ../testdata/canonical-box-10x8x6.step
+// notes: INLINE-STEP-X1 wraps an Aetheris-canonical AP242 fixture and re-exports through Step242Importer/Step242Exporter; output is canonicalized, not byte-identical.
+
+model InlineStepCanonicalBox {
+ units mm
+
+ solid importedPart: InlineStep {
+ path: "../testdata/canonical-box-10x8x6.step"
+ }
+}