Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Add production canon metadata mode

Yuechen Liaab9a425c452
diff --git a/Aetheris.CLI.Tests/CliBaselineTests.cs b/Aetheris.CLI.Tests/CliBaselineTests.cs
index 14013254..4ca7529c 100644
--- a/Aetheris.CLI.Tests/CliBaselineTests.cs
+++ b/Aetheris.CLI.Tests/CliBaselineTests.cs
@@ -1053,6 +1053,36 @@ public sealed class CliBaselineTests
File.Delete(outputPath);
}
+
+ [Fact]
+ public void Canon_Command_Production_Mode_Preserves_Supported_Header_And_Product_Metadata()
+ {
+ var sourceText = File.ReadAllText(Path.Combine(RepoRoot, "testdata/firmament/exports/box_basic.step"))
+ .Replace("FILE_DESCRIPTION(('Aetheris AP242 subset export'),'2;1');", "FILE_DESCRIPTION(('Vendor production description'),'2;1');", StringComparison.Ordinal)
+ .Replace("FILE_NAME('aetheris_export.step','1970-01-01T00:00:00',('Aetheris'),('Aetheris'),'Aetheris.Kernel','Aetheris.Kernel','');", "FILE_NAME('vendor-widget.stp','2024-05-06T07:08:09',('Vendor Author'),('Vendor Org'),'Vendor Preprocessor','Vendor CAD','Vendor Approval');", StringComparison.Ordinal)
+ .Replace("PRODUCT('AETHERIS','AetherisBody','',", "PRODUCT('VENDOR-ID','Vendor Widget','Vendor Product Description',", StringComparison.Ordinal);
+ var inputPath = Path.Combine(Path.GetTempPath(), $"cli-canon-production-input-{Guid.NewGuid():N}.step");
+ var outputPath = Path.Combine(Path.GetTempPath(), $"cli-canon-production-output-{Guid.NewGuid():N}.step");
+ File.WriteAllText(inputPath, sourceText);
+ var stdout = new StringWriter();
+ var stderr = new StringWriter();
+
+ var exitCode = Aetheris.CLI.CliRunner.Run(["canon", inputPath, "--out", outputPath, "--mode", "production", "--json"], stdout, stderr);
+
+ Assert.Equal(0, exitCode);
+ Assert.True(string.IsNullOrWhiteSpace(stderr.ToString()), stderr.ToString());
+ var outputText = File.ReadAllText(outputPath);
+ Assert.Contains("FILE_DESCRIPTION(('Vendor production description'),'2;1');", outputText, StringComparison.Ordinal);
+ Assert.Contains("FILE_NAME('vendor-widget.stp','2024-05-06T07:08:09',('Vendor Author'),('Vendor Org'),'Vendor CAD','Vendor CAD','Vendor Approval');", outputText, StringComparison.Ordinal);
+ Assert.Contains("PRODUCT('AETHERIS','Vendor Widget','Vendor Product Description',", outputText, StringComparison.Ordinal);
+ Assert.Contains("MANIFOLD_SOLID_BREP('Vendor Widget'", outputText, StringComparison.Ordinal);
+ Assert.True(Step242Importer.ImportBody(outputText).IsSuccess);
+ Assert.NotEqual(sourceText, outputText);
+
+ File.Delete(inputPath);
+ File.Delete(outputPath);
+ }
+
[Fact]
public void Canon_Command_Json_Failure_Contract_Reports_Missing_Input()
{
diff --git a/Aetheris.CLI/CliRunner.cs b/Aetheris.CLI/CliRunner.cs
index 9fc7cb64..aebbc943 100644
--- a/Aetheris.CLI/CliRunner.cs
+++ b/Aetheris.CLI/CliRunner.cs
@@ -114,7 +114,7 @@ public static class CliRunner
private const string AnalyzeVolumeUsage = "Usage: aetheris analyze volume <file.step> [--approximate --resolution <N>] [--json]";
private const string AnalyzeCompareUsage = "Usage: aetheris analyze compare <reference.step> <candidate.step> [--approximate-volume --resolution <N>] [--json]";
private const string TraceUsage = "Usage: aetheris trace (--case <name>|--fixture <path>) [--out-dir <dir>] [--json]";
- private const string CanonUsage = "Usage: aetheris canon <file.step> --out <canonical.step> [--json]";
+ private const string CanonUsage = "Usage: aetheris canon <file.step> --out <canonical.step> [--mode deterministic|production] [--json]";
private const string AsmExecUsage = "Usage: aetheris asm exec <file.firmasm> [--json]";
private const string AsmExportUsage = "Usage: aetheris asm export <file.firmasm> --out <directory> [--json]";
private const string ExperimentalUsage = "Usage: aetheris experimental <airchamfer-cube|airchamfer-corpus|prismatic-corpus|prismatic-map|loop-chamfer-corpus> [options]";
@@ -446,6 +446,7 @@ public static class CliRunner
var inputPath = args[0];
string? outputPath = null;
var json = false;
+ var canonMode = Aetheris.Kernel.Core.Step242.Step242CanonMode.Deterministic;
for (var i = 1; i < args.Length; i++)
{
@@ -461,6 +462,27 @@ public static class CliRunner
case "--json":
json = true;
break;
+ case "--mode" when i + 1 < args.Length:
+ var modeValue = args[++i];
+ if (string.Equals(modeValue, "deterministic", StringComparison.OrdinalIgnoreCase))
+ {
+ canonMode = Aetheris.Kernel.Core.Step242.Step242CanonMode.Deterministic;
+ }
+ else if (string.Equals(modeValue, "production", StringComparison.OrdinalIgnoreCase) || string.Equals(modeValue, "production-preserve-metadata", StringComparison.OrdinalIgnoreCase))
+ {
+ canonMode = Aetheris.Kernel.Core.Step242.Step242CanonMode.ProductionPreserveMetadata;
+ }
+ else
+ {
+ stderr.WriteLine($"Unknown canon mode '{modeValue}'. Expected deterministic or production.");
+ stderr.WriteLine(CanonUsage);
+ return 1;
+ }
+ break;
+ case "--mode":
+ stderr.WriteLine("Canon option --mode requires deterministic or production.");
+ stderr.WriteLine(CanonUsage);
+ return 1;
case "-h":
case "--help":
WriteCanonHelp(stdout);
@@ -517,7 +539,11 @@ public static class CliRunner
FormatKernelDiagnostics(importResult.Diagnostics));
}
- var exportResult = Aetheris.Kernel.Core.Step242.Step242Exporter.ExportBody(importResult.Value);
+ var exportOptions = canonMode == Aetheris.Kernel.Core.Step242.Step242CanonMode.ProductionPreserveMetadata
+ ? Aetheris.Kernel.Core.Step242.Step242ExportOptions.FromSourceMetadata(Aetheris.Kernel.Core.Step242.Step242SourceMetadataReader.Read(stepText))
+ : new Aetheris.Kernel.Core.Step242.Step242ExportOptions();
+
+ var exportResult = Aetheris.Kernel.Core.Step242.Step242Exporter.ExportBody(importResult.Value, exportOptions);
if (!exportResult.IsSuccess)
{
return WriteCanonFailure(
@@ -548,12 +574,14 @@ public static class CliRunner
inputPath = inputFullPath,
outputPath = outputFullPath,
bodyCount = topology.Bodies.Count(),
- shellCount = topology.Shells.Count()
+ shellCount = topology.Shells.Count(),
+ mode = canonMode == Aetheris.Kernel.Core.Step242.Step242CanonMode.ProductionPreserveMetadata ? "production" : "deterministic"
}, JsonOptions));
}
else
{
stdout.WriteLine($"Canonical STEP written: {outputFullPath}");
+ stdout.WriteLine($"Canon mode: {(canonMode == Aetheris.Kernel.Core.Step242.Step242CanonMode.ProductionPreserveMetadata ? "production" : "deterministic")}");
}
return 0;
@@ -2059,7 +2087,7 @@ public static class CliRunner
stdout.WriteLine(" aetheris trace --case top-face-loop-chamfer");
stdout.WriteLine(" aetheris trace --fixture fixtures/Firmament/Chamfer/valid/top-face-loop-chamfer.valid.firmfixture");
stdout.WriteLine(" aetheris trace --case prismatic-section-transition --json");
- stdout.WriteLine(" aetheris canon input.step --out canonical.step --json");
+ stdout.WriteLine(" aetheris canon input.step --out canonical.step --mode production --json");
stdout.WriteLine(" aetheris asm exec assembly.firmasm --json");
stdout.WriteLine(" aetheris asm export assembly.firmasm --out out/assembly-roundtrip --json");
stdout.WriteLine(" aetheris experimental airchamfer-cube --out edge-x10-airchamfer-cube-one-edge.step --json");
@@ -2206,6 +2234,7 @@ public static class CliRunner
stdout.WriteLine();
stdout.WriteLine("Options:");
stdout.WriteLine(" --out <path> Required canonical AP242 output path.");
+ stdout.WriteLine(" --mode <mode> deterministic (default) or production metadata preservation.");
stdout.WriteLine(" (Assembly-like multi-root STEP is not canonicalized by this command.)");
stdout.WriteLine(" --json Emit machine-readable success/failure JSON.");
stdout.WriteLine(" -h, --help Show this help.");
diff --git a/Aetheris.Kernel.Core/Step242/Step242CanonMode.cs b/Aetheris.Kernel.Core/Step242/Step242CanonMode.cs
new file mode 100644
index 00000000..eb029074
--- /dev/null
+++ b/Aetheris.Kernel.Core/Step242/Step242CanonMode.cs
@@ -0,0 +1,7 @@
+namespace Aetheris.Kernel.Core.Step242;
+
+public enum Step242CanonMode
+{
+ Deterministic,
+ ProductionPreserveMetadata
+}
diff --git a/Aetheris.Kernel.Core/Step242/Step242ExportOptions.cs b/Aetheris.Kernel.Core/Step242/Step242ExportOptions.cs
index 4ba1997c..2549aad6 100644
--- a/Aetheris.Kernel.Core/Step242/Step242ExportOptions.cs
+++ b/Aetheris.Kernel.Core/Step242/Step242ExportOptions.cs
@@ -4,7 +4,56 @@ public sealed class Step242ExportOptions
{
public string ProductName { get; init; } = "AetherisBody";
+ public string ProductId { get; init; } = "AETHERIS";
+
+ public string ProductDescription { get; init; } = "";
+
public string ApplicationName { get; init; } = "Aetheris";
public string AuthoringSystem { get; init; } = "Aetheris.Kernel";
+
+ public Step242HeaderMetadata HeaderMetadata { get; init; } = Step242HeaderMetadata.Deterministic;
+
+ public static Step242ExportOptions FromSourceMetadata(Step242SourceMetadata metadata)
+ {
+ static string Coalesce(string? value, string fallback) => string.IsNullOrWhiteSpace(value) ? fallback : value!;
+
+ return new Step242ExportOptions
+ {
+ ProductName = Coalesce(metadata.ProductName, "AetherisBody"),
+ ProductDescription = Coalesce(metadata.ProductDescription, string.Empty),
+ ApplicationName = Coalesce(metadata.Organization, "Aetheris"),
+ AuthoringSystem = Coalesce(metadata.OriginatingSystem, "Aetheris.Kernel"),
+ HeaderMetadata = new Step242HeaderMetadata(
+ Coalesce(metadata.FileName, "aetheris_export.step"),
+ Coalesce(metadata.Description, "Aetheris AP242 subset export"),
+ Coalesce(metadata.CreationTimestamp, "1970-01-01T00:00:00"),
+ Coalesce(metadata.Author, "Aetheris"),
+ Coalesce(metadata.Organization, Coalesce(metadata.Author, "Aetheris")),
+ Coalesce(metadata.OriginatingSystem, "Aetheris.Kernel"),
+ Coalesce(metadata.OriginatingSystem, "Aetheris.Kernel"),
+ Coalesce(metadata.Authorization, string.Empty))
+ };
+ }
+}
+
+public sealed record Step242HeaderMetadata(
+ string FileName,
+ string Description,
+ string CreationTimestamp,
+ string Author,
+ string Organization,
+ string PreprocessorVersion,
+ string OriginatingSystem,
+ string Authorization)
+{
+ public static Step242HeaderMetadata Deterministic { get; } = new(
+ "aetheris_export.step",
+ "Aetheris AP242 subset export",
+ "1970-01-01T00:00:00",
+ "Aetheris",
+ "Aetheris",
+ "Aetheris.Kernel",
+ "Aetheris.Kernel",
+ string.Empty);
}
diff --git a/Aetheris.Kernel.Core/Step242/Step242Exporter.cs b/Aetheris.Kernel.Core/Step242/Step242Exporter.cs
index bedeeb8d..c86201f2 100644
--- a/Aetheris.Kernel.Core/Step242/Step242Exporter.cs
+++ b/Aetheris.Kernel.Core/Step242/Step242Exporter.cs
@@ -98,7 +98,7 @@ public static class Step242Exporter
var appContextId = writer.AddEntity("APPLICATION_CONTEXT", Step242TextWriter.String("mechanical design"));
var productContextId = writer.AddEntity("PRODUCT_CONTEXT", Step242TextWriter.String(""), Step242TextWriter.Ref(appContextId), Step242TextWriter.String("mechanical"));
- var productId = writer.AddEntity("PRODUCT", Step242TextWriter.String("AETHERIS"), Step242TextWriter.String(options.ProductName), Step242TextWriter.String(""), Step242TextWriter.List(productContextId));
+ var productId = writer.AddEntity("PRODUCT", Step242TextWriter.String(options.ProductId), Step242TextWriter.String(options.ProductName), Step242TextWriter.String(options.ProductDescription), Step242TextWriter.List(productContextId));
var formationId = writer.AddEntity("PRODUCT_DEFINITION_FORMATION", Step242TextWriter.String(""), Step242TextWriter.String(""), Step242TextWriter.Ref(productId));
var definitionContextId = writer.AddEntity("PRODUCT_DEFINITION_CONTEXT", Step242TextWriter.String("design"), Step242TextWriter.Ref(appContextId), Step242TextWriter.String("design"));
var definitionId = writer.AddEntity("PRODUCT_DEFINITION", Step242TextWriter.String(""), Step242TextWriter.String(""), Step242TextWriter.Ref(formationId), Step242TextWriter.Ref(definitionContextId));
@@ -112,7 +112,7 @@ public static class Step242Exporter
var shapeRepresentationId = writer.AddEntity("SHAPE_REPRESENTATION", Step242TextWriter.String(options.ProductName), Step242TextWriter.List(brepId), Step242TextWriter.Ref(repContextId));
writer.AddEntity("SHAPE_DEFINITION_REPRESENTATION", Step242TextWriter.Ref(shapeId), Step242TextWriter.Ref(shapeRepresentationId));
- return KernelResult<string>.Success(writer.Build(options.ApplicationName));
+ return KernelResult<string>.Success(writer.Build(options.HeaderMetadata));
}
private static void EmitAuxiliaryVertexPointForVertexlessAnalyticBody(Step242TextWriter writer, BrepBody body, TopologyModel model)
diff --git a/Aetheris.Kernel.Core/Step242/Step242SourceMetadata.cs b/Aetheris.Kernel.Core/Step242/Step242SourceMetadata.cs
new file mode 100644
index 00000000..a1c0d36b
--- /dev/null
+++ b/Aetheris.Kernel.Core/Step242/Step242SourceMetadata.cs
@@ -0,0 +1,15 @@
+namespace Aetheris.Kernel.Core.Step242;
+
+public sealed record Step242SourceMetadata(
+ string? FileName,
+ string? Description,
+ string? Author,
+ string? Organization,
+ string? CreationTimestamp,
+ string? OriginatingSystem,
+ string? Authorization,
+ string? ProductName,
+ string? ProductDescription)
+{
+ public static Step242SourceMetadata Empty { get; } = new(null, null, null, null, null, null, null, null, null);
+}
diff --git a/Aetheris.Kernel.Core/Step242/Step242SourceMetadataReader.cs b/Aetheris.Kernel.Core/Step242/Step242SourceMetadataReader.cs
new file mode 100644
index 00000000..e77f5698
--- /dev/null
+++ b/Aetheris.Kernel.Core/Step242/Step242SourceMetadataReader.cs
@@ -0,0 +1,63 @@
+using System.Text.RegularExpressions;
+
+namespace Aetheris.Kernel.Core.Step242;
+
+public static class Step242SourceMetadataReader
+{
+ public static Step242SourceMetadata Read(string stepText)
+ {
+ if (string.IsNullOrWhiteSpace(stepText)) return Step242SourceMetadata.Empty;
+
+ var fileName = MatchFileName(stepText);
+ var description = MatchFileDescription(stepText);
+ var product = MatchProduct(stepText);
+
+ return new Step242SourceMetadata(
+ fileName?.FileName,
+ description,
+ fileName?.Author,
+ fileName?.Organization,
+ fileName?.CreationTimestamp,
+ fileName?.OriginatingSystem,
+ fileName?.Authorization,
+ product?.Name,
+ product?.Description);
+ }
+
+ private static FileNameMetadata? MatchFileName(string text)
+ {
+ var match = Regex.Match(text, @"FILE_NAME\s*\(\s*'(?<name>(?:''|[^'])*)'\s*,\s*'(?<time>(?:''|[^'])*)'\s*,\s*\((?<authors>[^)]*)\)\s*,\s*\((?<orgs>[^)]*)\)\s*,\s*'(?<preprocessor>(?:''|[^'])*)'\s*,\s*'(?<originating>(?:''|[^'])*)'\s*,\s*'(?<authorization>(?:''|[^'])*)'", RegexOptions.IgnoreCase | RegexOptions.Singleline);
+ if (!match.Success) return null;
+ return new FileNameMetadata(
+ Unescape(match.Groups["name"].Value),
+ FirstString(match.Groups["authors"].Value),
+ FirstString(match.Groups["orgs"].Value),
+ Unescape(match.Groups["time"].Value),
+ Unescape(match.Groups["originating"].Value),
+ Unescape(match.Groups["authorization"].Value));
+ }
+
+ private static string? MatchFileDescription(string text)
+ {
+ var match = Regex.Match(text, @"FILE_DESCRIPTION\s*\(\s*\((?<items>[^)]*)\)", RegexOptions.IgnoreCase | RegexOptions.Singleline);
+ return match.Success ? FirstString(match.Groups["items"].Value) : null;
+ }
+
+ private static ProductMetadata? MatchProduct(string text)
+ {
+ var match = Regex.Match(text, @"PRODUCT\s*\(\s*'(?<id>(?:''|[^'])*)'\s*,\s*'(?<name>(?:''|[^'])*)'\s*,\s*'(?<description>(?:''|[^'])*)'", RegexOptions.IgnoreCase | RegexOptions.Singleline);
+ if (!match.Success) return null;
+ return new ProductMetadata(Unescape(match.Groups["name"].Value), Unescape(match.Groups["description"].Value));
+ }
+
+ private static string? FirstString(string listText)
+ {
+ var match = Regex.Match(listText, @"'(?<value>(?:''|[^'])*)'", RegexOptions.Singleline);
+ return match.Success ? Unescape(match.Groups["value"].Value) : null;
+ }
+
+ private static string Unescape(string value) => value.Replace("''", "'", StringComparison.Ordinal);
+
+ private sealed record FileNameMetadata(string? FileName, string? Author, string? Organization, string? CreationTimestamp, string? OriginatingSystem, string? Authorization);
+ private sealed record ProductMetadata(string? Name, string? Description);
+}
diff --git a/Aetheris.Kernel.Core/Step242/Step242TextWriter.cs b/Aetheris.Kernel.Core/Step242/Step242TextWriter.cs
index 62264209..c8ec7527 100644
--- a/Aetheris.Kernel.Core/Step242/Step242TextWriter.cs
+++ b/Aetheris.Kernel.Core/Step242/Step242TextWriter.cs
@@ -21,13 +21,13 @@ internal sealed class Step242TextWriter
return id;
}
- public string Build(string applicationName)
+ public string Build(Step242HeaderMetadata headerMetadata)
{
var sb = new StringBuilder();
sb.AppendLine("ISO-10303-21;");
sb.AppendLine("HEADER;");
- sb.AppendLine($"FILE_DESCRIPTION(('Aetheris AP242 subset export'),'2;1');");
- sb.AppendLine($"FILE_NAME('aetheris_export.step','1970-01-01T00:00:00',('Aetheris'),('{EscapeString(applicationName)}'),'Aetheris.Kernel','Aetheris.Kernel','');");
+ sb.AppendLine($"FILE_DESCRIPTION(('{EscapeString(headerMetadata.Description)}'),'2;1');");
+ sb.AppendLine($"FILE_NAME('{EscapeString(headerMetadata.FileName)}','{EscapeString(headerMetadata.CreationTimestamp)}',('{EscapeString(headerMetadata.Author)}'),('{EscapeString(headerMetadata.Organization)}'),'{EscapeString(headerMetadata.PreprocessorVersion)}','{EscapeString(headerMetadata.OriginatingSystem)}','{EscapeString(headerMetadata.Authorization)}');");
sb.AppendLine("FILE_SCHEMA(('AP242_MANAGED_MODEL_BASED_3D_ENGINEERING_MIM_LF'));");
sb.AppendLine("ENDSEC;");
sb.AppendLine("DATA;");
diff --git a/docs/implementation/canon-inline-x2-a0-production-canon-metadata-pmi.md b/docs/implementation/canon-inline-x2-a0-production-canon-metadata-pmi.md
new file mode 100644
index 00000000..fb429210
--- /dev/null
+++ b/docs/implementation/canon-inline-x2-a0-production-canon-metadata-pmi.md
@@ -0,0 +1,97 @@
+# CANON-INLINE-X2-A0 production canon metadata/PMI audit
+
+## Current canon behavior
+
+`aetheris canon` imports a part-like STEP/AP242 file with `Step242Importer.ImportBody` and re-exports the resulting `BrepBody` with `Step242Exporter.ExportBody`. Before this milestone the command always used exporter defaults, which are deterministic and snapshot-friendly:
+
+- `FILE_DESCRIPTION` was always `Aetheris AP242 subset export`.
+- `FILE_NAME` was always `aetheris_export.step`, timestamp `1970-01-01T00:00:00`, author/organization `Aetheris`, and authoring/originating system `Aetheris.Kernel`.
+- `PRODUCT` id was always `AETHERIS`, product name defaulted to `AetherisBody`, and product description was empty.
+- `MANIFOLD_SOLID_BREP`, `BREP_WITH_VOIDS`, and `SHAPE_REPRESENTATION` names used the exporter product name.
+
+That behavior remains the deterministic default.
+
+## Canon modes
+
+The CLI now exposes an explicit mode switch:
+
+```bash
+aetheris canon input.step --out deterministic.step --mode deterministic
+aetheris canon input.step --out production.step --mode production
+```
+
+`deterministic` remains the default and keeps stable generic metadata for tests, snapshots, and reproducible hashes.
+
+`production` means `ProductionPreserveMetadata`: canon still rebuilds Aetheris-canonical AP242 from imported topology, but it preserves the bounded source metadata fields that are currently cheap and explicit to recover.
+
+## Metadata preserved now in production mode
+
+Production mode reads source header/product metadata from the input STEP text and feeds supported values into `Step242ExportOptions`:
+
+- source `FILE_DESCRIPTION` first description string;
+- source `FILE_NAME` file name;
+- source `FILE_NAME` author first string;
+- source `FILE_NAME` organization first string;
+- source `FILE_NAME` creation timestamp;
+- source `FILE_NAME` originating system;
+- source `FILE_NAME` authorization;
+- source `PRODUCT` name;
+- source `PRODUCT` description.
+
+The output remains canonicalized AP242, not a byte-preserving rewrite. Product id remains `AETHERIS` to preserve the Aetheris-canonical identity marker while product/body names and descriptions can carry source part metadata.
+
+## Metadata still dropped or normalized
+
+The current implementation does not preserve arbitrary header cardinality or graph metadata. In particular, it does not preserve:
+
+- multiple authors or organizations beyond the first string;
+- source `FILE_SCHEMA` variants beyond the Aetheris AP242 canonical schema;
+- preprocessor version as distinct from originating system in the production output;
+- arbitrary `PRODUCT_DEFINITION`, presentation, approval, security, management, validation, or vendor extension graphs;
+- original entity ids, ordering, formatting, comments, or byte layout.
+
+This is intentional for X2-A0: production canon is canonical AP242 with bounded metadata preservation, not raw STEP editing.
+
+## Source PMI preservation status
+
+Current status: **partially supported**.
+
+The exporter can emit bounded semantic PMI records when Firmament/Aetheris semantic models supply `Step242SemanticPmi` payloads. Evidence exists for semantic hole diameter and datum output in the STEP exporter and Firmament V2 PMI pipeline.
+
+The importer does **not** parse existing source semantic PMI into a reusable PMI model during canon. Therefore source PMI in an external/vendor STEP file is dropped by `aetheris canon`, including production mode. No source PMI preservation claim should be made until a passing import/canon/re-export test proves it.
+
+Recommended next milestone:
+
+```text
+CANON-PMI-X1 — parse supported semantic PMI subset into Step242SemanticPmi records during import and re-emit in production canon mode
+```
+
+## Inline STEP PMI attachment groundwork
+
+INLINE-STEP-X1 already preserves useful provenance for the wrapper path: parsed `InlineStep` records include the source path, normalized path, SHA-256 content hash, canonical-input flag, and canonical evidence string. X1 still requires Aetheris-canonical AP242 and rejects arbitrary raw external/vendor STEP.
+
+What is missing for INLINE-STEP-X2 semantic PMI attachment is a topology target reference contract:
+
+- There is no stable canonical face/entity id map exposed by `Step242Importer` today.
+- Imported `BrepBody` topology has internal `FaceId`/`EdgeId` handles, but those ids are importer-created and are not yet documented as stable user-facing selectors for Firmament syntax.
+- A clean X2 path is for canonical STEP import to expose an optional map from canonical STEP entity references (for example `ADVANCED_FACE` instance ids) to imported topology handles, then allow Firmament PMI overlays to target imported topology through a narrow canonical reference model.
+
+Smallest proposed target model for INLINE-STEP-X2:
+
+```text
+InlineStepTopologyTarget
+ inline symbol name
+ source canonical content hash
+ topology kind: face | edge | vertex
+ canonical STEP entity reference: #<id>
+ resolved internal topology handle after import
+```
+
+That keeps raw vendor STEP out of Firmament source, avoids graphical PMI, and allows semantic Firmament overlays to bind to Aetheris-canonical topology after `aetheris canon --mode production` has prepared the source.
+
+## Deferred work
+
+- Parse and preserve a tested semantic PMI subset from source AP242.
+- Expose canonical STEP entity to topology handle maps from `Step242Importer`.
+- Add Firmament InlineStep PMI target syntax only after the reference model is implemented.
+- Preserve richer product management metadata only when there is a bounded importer/exporter model and tests.
diff --git a/docs/implementation/inline-step-x1-canonical-step-wrapper.md b/docs/implementation/inline-step-x1-canonical-step-wrapper.md
index 52ab90df..25d37204 100644
--- a/docs/implementation/inline-step-x1-canonical-step-wrapper.md
+++ b/docs/implementation/inline-step-x1-canonical-step-wrapper.md
@@ -16,7 +16,7 @@ The symbol name (`importedPart`) is preserved as the exported STEP product name.
## 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:
+Inline STEP input must be Aetheris-canonical AP242. Raw external/vendor STEP remains import/canon input, not Firmament source. CANON-INLINE-X2-A0 adds the production canon policy for preserving bounded source header/product metadata before wrapping; see `docs/implementation/canon-inline-x2-a0-production-canon-metadata-pmi.md`. The intended flow is:
```text
external/vendor STEP -> aetheris canon -> Aetheris-canonical STEP -> Firmament InlineStep -> AP242 re-export