Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Clarify Firmament V1 compatibility paths and diagnostics

Yuechen Liffa9d795cc7b
diff --git a/Aetheris.CLI/CliRunner.cs b/Aetheris.CLI/CliRunner.cs
index 27e69850..1d335372 100644
--- a/Aetheris.CLI/CliRunner.cs
+++ b/Aetheris.CLI/CliRunner.cs
@@ -2,6 +2,7 @@ using System.Security.Cryptography;
using System.Diagnostics;
using System.Text.Json;
using System.Text.Json.Serialization;
+using Aetheris.Kernel.Core.Diagnostics;
using System.Text.RegularExpressions;
using Aetheris.Forge.Abstractions.FirmamentInterop;
using Aetheris.Kernel.Core.Brep.Verification;
@@ -449,6 +450,7 @@ public static class CliRunner
features = build.Value.Export.Features,
inlineStepMigration = build.Value.Export.InlineStepMigration,
inlineStepReplacementAssist = build.Value.Export.InlineStepReplacementAssist,
+ diagnostics = build.Diagnostics.Select(d => new { d.Source, d.Message, severity = d.Severity.ToString() }),
pmiExportEvidence = new
{
datum = (build.Value.Export.DatumInspection ?? []).Select(d => new { kind = "datum", name = d.Label, exportSupport = "supported", exportEvidence = "found", target = d.Target }),
@@ -463,6 +465,8 @@ public static class CliRunner
stdout.WriteLine($"Model: {build.Value.Export.ExportedFeatureId}");
if (build.Value.Export.StandardPart is { } standardPart)
stdout.WriteLine($"Standard part: {standardPart.Family} via {standardPart.Template ?? "direct record"} ({standardPart.SemanticDescendants.Count} semantic descendants)");
+ foreach (var diagnostic in build.Diagnostics.Where(diagnostic => diagnostic.Severity == KernelDiagnosticSeverity.Warning))
+ stderr.WriteLine($"- [Warning] {diagnostic.Source}: {diagnostic.Message}");
}
return 0;
diff --git a/Aetheris.Kernel.Firmament.Tests/Compatibility/FirmamentV1CodecTests.cs b/Aetheris.Kernel.Firmament.Tests/Compatibility/FirmamentV1CodecTests.cs
new file mode 100644
index 00000000..0a605b76
--- /dev/null
+++ b/Aetheris.Kernel.Firmament.Tests/Compatibility/FirmamentV1CodecTests.cs
@@ -0,0 +1,65 @@
+using Aetheris.Kernel.Firmament.Compatibility.V1;
+using Aetheris.Kernel.Firmament.ParsedModel;
+
+namespace Aetheris.Kernel.Firmament.Tests.Compatibility;
+
+public sealed class FirmamentV1CodecTests
+{
+ [Fact]
+ public void Toon_And_Json_NormalizeToEquivalentHistoricalModel()
+ {
+ var toon = new FirmamentV1ToonReader().Read("""
+ firmament:
+ version: 1
+
+ model:
+ name: demo
+ units: mm
+
+ ops[1]:
+ -
+ op: box
+ id: base
+ """);
+ var json = new FirmamentV1JsonReader().Read("""
+ { "firmament": { "version": "1" }, "model": { "name": "demo", "units": "mm" }, "ops": [ { "op": "box", "id": "base" } ] }
+ """);
+
+ Assert.True(toon.IsSuccess, string.Join(Environment.NewLine, toon.Diagnostics));
+ Assert.True(json.IsSuccess, string.Join(Environment.NewLine, json.Diagnostics));
+ Assert.Equivalent(Snapshot(toon.Value), Snapshot(json.Value));
+ }
+
+ [Fact]
+ public void ToonWriter_IsLfOnly_AndReadWriteReadStable()
+ {
+ const string source = "firmament:\r\n version: 1\r\n\r\nmodel:\r\n name: demo\r\n units: mm\r\n\r\nops[0]:\r\n";
+ var parsed = new FirmamentV1ToonReader().Read(source);
+
+ Assert.True(parsed.IsSuccess, string.Join(Environment.NewLine, parsed.Diagnostics));
+ var writer = new FirmamentV1ToonWriter();
+ var canonical = writer.Write(parsed.Value);
+ var reparsed = new FirmamentV1ToonReader().Read(canonical);
+
+ Assert.DoesNotContain("\r", canonical, StringComparison.Ordinal);
+ Assert.Equal(canonical, writer.Write(reparsed.Value));
+ Assert.Equivalent(Snapshot(parsed.Value), Snapshot(reparsed.Value));
+ }
+
+ [Fact]
+ public void ExplicitJsonReader_DoesNotFallThroughToToon()
+ {
+ var result = new FirmamentV1JsonReader().Read("firmament:\n version: 1");
+
+ Assert.False(result.IsSuccess);
+ Assert.Contains(result.Diagnostics, diagnostic => diagnostic.Message.Contains("V1 JSON compatibility", StringComparison.Ordinal));
+ }
+
+ private static object Snapshot(FirmamentParsedDocument document) => new
+ {
+ document.Firmament.Version,
+ document.Model.Name,
+ document.Model.Units,
+ Ops = document.Ops.Entries.Select(op => new { op.OpName, op.KnownKind, op.Family, Fields = op.RawFields.OrderBy(pair => pair.Key).ToArray() }).ToArray()
+ };
+}
diff --git a/Aetheris.Kernel.Firmament/Assembly/FirmamentAssemblyDocumentProfile.cs b/Aetheris.Kernel.Firmament/Assembly/FirmamentAssemblyDocumentProfile.cs
index 5a555e43..b85f73a9 100644
--- a/Aetheris.Kernel.Firmament/Assembly/FirmamentAssemblyDocumentProfile.cs
+++ b/Aetheris.Kernel.Firmament/Assembly/FirmamentAssemblyDocumentProfile.cs
@@ -38,7 +38,7 @@ public sealed class FirmamentAssemblyDocumentCompiler
var migrated = false;
if (profile == FirmamentDocumentProfile.Assembly && LooksLikeJson(source))
{
- var legacy = new FirmasmManifestLoader().LoadFromFile(fullPath);
+ var legacy = new LegacyFirmasmJsonReader().LoadFromFile(fullPath);
if (!legacy.IsSuccess)
{
var diagnostics = legacy.Diagnostics.Select(diagnostic => new AssemblyDiagnostic(
diff --git a/Aetheris.Kernel.Firmament/Assembly/FirmasmAssemblyExecutor.cs b/Aetheris.Kernel.Firmament/Assembly/FirmasmAssemblyExecutor.cs
index 6c3e57e2..5466e3fd 100644
--- a/Aetheris.Kernel.Firmament/Assembly/FirmasmAssemblyExecutor.cs
+++ b/Aetheris.Kernel.Firmament/Assembly/FirmasmAssemblyExecutor.cs
@@ -22,9 +22,10 @@ public sealed record FirmasmExecutionResult(
IReadOnlyList<FirmasmExecutedInstance> Instances,
BrepBody ComposedBody);
+/// <summary>Legacy JSON <c>.firmasm</c> direct execution bridge retained for Preview compatibility.</summary>
public sealed class FirmasmAssemblyExecutor
{
- private readonly FirmasmManifestLoader _loader = new();
+ private readonly LegacyFirmasmJsonReader _loader = new();
public KernelResult<FirmasmExecutionResult> ExecuteFromFile(string manifestPath)
{
diff --git a/Aetheris.Kernel.Firmament/Assembly/FirmasmManifestLoader.cs b/Aetheris.Kernel.Firmament/Assembly/FirmasmManifestLoader.cs
index 430cc62a..f07411b4 100644
--- a/Aetheris.Kernel.Firmament/Assembly/FirmasmManifestLoader.cs
+++ b/Aetheris.Kernel.Firmament/Assembly/FirmasmManifestLoader.cs
@@ -5,7 +5,12 @@ using Aetheris.Kernel.Core.Step242;
namespace Aetheris.Kernel.Firmament.Assembly;
-public sealed class FirmasmManifestLoader
+/// <summary>
+/// Compatibility reader for the deprecated JSON-shaped <c>.firmasm</c> serialization.
+/// It intentionally preserves flat explicit transforms and never derives V2 mates,
+/// interfaces, roles, or hierarchy semantics.
+/// </summary>
+public sealed class LegacyFirmasmJsonReader
{
private static readonly HashSet<string> AllowedTopLevelSections = new(StringComparer.Ordinal)
{
diff --git a/Aetheris.Kernel.Firmament/Assembly/FirmasmManifestLoaderAdapter.cs b/Aetheris.Kernel.Firmament/Assembly/FirmasmManifestLoaderAdapter.cs
new file mode 100644
index 00000000..b570cb3a
--- /dev/null
+++ b/Aetheris.Kernel.Firmament/Assembly/FirmasmManifestLoaderAdapter.cs
@@ -0,0 +1,16 @@
+using Aetheris.Kernel.Core.Results;
+
+namespace Aetheris.Kernel.Firmament.Assembly;
+
+/// <summary>
+/// Compatibility facade retained for existing integrations. New code should use
+/// <see cref="LegacyFirmasmJsonReader"/> to make the historical JSON format explicit.
+/// </summary>
+public sealed class FirmasmManifestLoader
+{
+ private readonly LegacyFirmasmJsonReader _reader = new();
+
+ public KernelResult<FirmasmLoadedAssembly> LoadFromFile(string manifestPath) => _reader.LoadFromFile(manifestPath);
+
+ public KernelResult<FirmasmManifest> Parse(string sourceText) => _reader.Parse(sourceText);
+}
diff --git a/Aetheris.Kernel.Firmament/Compatibility/V1/FirmamentV1Codecs.cs b/Aetheris.Kernel.Firmament/Compatibility/V1/FirmamentV1Codecs.cs
new file mode 100644
index 00000000..76cf1212
--- /dev/null
+++ b/Aetheris.Kernel.Firmament/Compatibility/V1/FirmamentV1Codecs.cs
@@ -0,0 +1,37 @@
+using Aetheris.Kernel.Core.Results;
+using Aetheris.Kernel.Firmament.Formatting;
+using Aetheris.Kernel.Firmament.ParsedModel;
+using Aetheris.Kernel.Firmament.Parsing;
+
+namespace Aetheris.Kernel.Firmament.Compatibility.V1;
+
+/// <summary>Strict reader for the historical Firmament V1 TOON serialization.</summary>
+public sealed class FirmamentV1ToonReader
+{
+ public KernelResult<FirmamentParsedDocument> Read(string sourceText) => FirmamentTopLevelParser.ReadToon(sourceText);
+}
+
+/// <summary>Strict reader for the historical Firmament V1 JSON serialization.</summary>
+public sealed class FirmamentV1JsonReader
+{
+ public KernelResult<FirmamentParsedDocument> Read(string sourceText) => FirmamentTopLevelParser.ReadJson(sourceText);
+}
+
+/// <summary>
+/// Historical compatibility adapter for callers that did not record whether their V1
+/// source was JSON or TOON. Automatic sniffing is not a Firmament V2 source feature.
+/// </summary>
+public sealed class LegacyFirmamentV1SourceReader
+{
+ public KernelResult<FirmamentParsedDocument> ReadAuto(string sourceText) => FirmamentTopLevelParser.ReadAuto(sourceText);
+}
+
+/// <summary>Deterministic LF-only writer for the historical Firmament V1 TOON form.</summary>
+public sealed class FirmamentV1ToonWriter
+{
+ public string Write(FirmamentParsedDocument document)
+ {
+ ArgumentNullException.ThrowIfNull(document);
+ return FirmamentCanonicalFormatter.Format(document);
+ }
+}
diff --git a/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs b/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs
index 4eeba6fc..cc5912c2 100644
--- a/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs
+++ b/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs
@@ -324,7 +324,26 @@ public static class FirmamentBuildAndExport
"FirmamentV2.Parse")).ToArray());
}
- return FirmamentStepExporter.Export(new FirmamentCompileRequest(new FirmamentSourceDocument(sourceText)));
+ // V1 is not a peer authoring route: this is the sole retained build fallback
+ // for historical serialized source and deliberately emits one concise warning.
+ return ExportV1CompatibilitySource(sourceText);
+ }
+
+ private static KernelResult<FirmamentStepExportResult> ExportV1CompatibilitySource(string sourceText)
+ {
+ var legacy = FirmamentStepExporter.Export(new FirmamentCompileRequest(new FirmamentSourceDocument(sourceText)));
+ if (!legacy.IsSuccess)
+ {
+ return legacy;
+ }
+
+ return KernelResult<FirmamentStepExportResult>.Success(legacy.Value, [
+ .. legacy.Diagnostics,
+ new Kernel.Core.Diagnostics.KernelDiagnostic(
+ Kernel.Core.Diagnostics.KernelDiagnosticCode.ValidationFailed,
+ Kernel.Core.Diagnostics.KernelDiagnosticSeverity.Warning,
+ "firmament-v1-compatibility-input: historical Firmament V1 source was accepted through the compatibility build route; Firmament V2 is the canonical authoring language.",
+ "FirmamentV1.Compatibility")]);
}
private static KernelResult<FirmamentStepExportResult>? TryExportV2StandardPart(FirmamentV2Document document)
diff --git a/Aetheris.Kernel.Firmament/FirmamentCompiler.cs b/Aetheris.Kernel.Firmament/FirmamentCompiler.cs
index bba88a7e..d4ff3c29 100644
--- a/Aetheris.Kernel.Firmament/FirmamentCompiler.cs
+++ b/Aetheris.Kernel.Firmament/FirmamentCompiler.cs
@@ -6,6 +6,7 @@ using Aetheris.Kernel.Firmament.Lowering;
using Aetheris.Kernel.Firmament.Mapping;
using Aetheris.Kernel.Firmament.Parsing;
using Aetheris.Kernel.Firmament.Validation;
+using Aetheris.Kernel.Firmament.Compatibility.V1;
namespace Aetheris.Kernel.Firmament;
@@ -15,7 +16,8 @@ public sealed class FirmamentCompiler
{
ArgumentNullException.ThrowIfNull(request);
- var parseResult = FirmamentTopLevelParser.Parse(request.Document.SourceText);
+ // V1 execution is retained as a compatibility lane. V2 callers use the V2 pipeline.
+ var parseResult = new LegacyFirmamentV1SourceReader().ReadAuto(request.Document.SourceText);
if (!parseResult.IsSuccess)
{
return new FirmamentCompileResult(
diff --git a/Aetheris.Kernel.Firmament/FirmamentFormatter.cs b/Aetheris.Kernel.Firmament/FirmamentFormatter.cs
index 6d7696dd..7d86312f 100644
--- a/Aetheris.Kernel.Firmament/FirmamentFormatter.cs
+++ b/Aetheris.Kernel.Firmament/FirmamentFormatter.cs
@@ -1,6 +1,7 @@
using Aetheris.Kernel.Core.Results;
using Aetheris.Kernel.Firmament.Formatting;
using Aetheris.Kernel.Firmament.Parsing;
+using Aetheris.Kernel.Firmament.Compatibility.V1;
namespace Aetheris.Kernel.Firmament;
@@ -10,14 +11,14 @@ public sealed class FirmamentFormatter
{
ArgumentNullException.ThrowIfNull(request);
- var parseResult = FirmamentTopLevelParser.Parse(request.Document.SourceText);
+ var parseResult = new LegacyFirmamentV1SourceReader().ReadAuto(request.Document.SourceText);
if (!parseResult.IsSuccess)
{
return new FirmamentFormatResult(
KernelResult<FirmamentFormattedDocument>.Failure(parseResult.Diagnostics));
}
- var formattedText = FirmamentCanonicalFormatter.Format(parseResult.Value);
+ var formattedText = new FirmamentV1ToonWriter().Write(parseResult.Value);
return new FirmamentFormatResult(
KernelResult<FirmamentFormattedDocument>.Success(
new FirmamentFormattedDocument(formattedText, parseResult.Value)));
diff --git a/Aetheris.Kernel.Firmament/Parsing/FirmamentTopLevelParser.cs b/Aetheris.Kernel.Firmament/Parsing/FirmamentTopLevelParser.cs
index 45419a2a..4867a234 100644
--- a/Aetheris.Kernel.Firmament/Parsing/FirmamentTopLevelParser.cs
+++ b/Aetheris.Kernel.Firmament/Parsing/FirmamentTopLevelParser.cs
@@ -10,15 +10,40 @@ namespace Aetheris.Kernel.Firmament.Parsing;
internal static class FirmamentTopLevelParser
{
- public static KernelResult<FirmamentParsedDocument> Parse(string sourceText)
+ // This parser is the V1 normalized-model decoder. V2 source never enters here.
+ // Callers should select a named V1 codec; ReadAuto is retained only for historical
+ // callers that supplied V1 source without a declared serialization format.
+ public static KernelResult<FirmamentParsedDocument> Parse(string sourceText) => ReadAuto(sourceText);
+
+ public static KernelResult<FirmamentParsedDocument> ReadAuto(string sourceText)
{
ArgumentNullException.ThrowIfNull(sourceText);
if (TryParseJson(sourceText, out var jsonRootResult))
{
- return ParseFromRoot(jsonRootResult);
+ return ReadJson(sourceText);
}
+ return ReadToon(sourceText);
+ }
+
+ public static KernelResult<FirmamentParsedDocument> ReadJson(string sourceText)
+ {
+ ArgumentNullException.ThrowIfNull(sourceText);
+ if (!TryParseJson(sourceText, out var root))
+ {
+ return KernelResult<FirmamentParsedDocument>.Failure([
+ CreateDiagnostic(KernelDiagnosticCode.ValidationFailed,
+ FirmamentDiagnosticCodes.StructureInvalidSectionShape,
+ "Firmament V1 JSON compatibility input is not valid JSON.")]);
+ }
+
+ return ParseFromRoot(root);
+ }
+
+ public static KernelResult<FirmamentParsedDocument> ReadToon(string sourceText)
+ {
+ ArgumentNullException.ThrowIfNull(sourceText);
var toonResult = ParseToonTopLevel(sourceText);
if (!toonResult.IsSuccess)
{
diff --git a/docs/architecture/artifacts/archaeology-m2/README.md b/docs/architecture/artifacts/archaeology-m2/README.md
new file mode 100644
index 00000000..e18182bc
--- /dev/null
+++ b/docs/architecture/artifacts/archaeology-m2/README.md
@@ -0,0 +1,3 @@
+# AETHERIS-ARCHAEOLOGY-M2 evidence
+
+M2 makes versioned compatibility formats explicit without changing geometry semantics. See the [serialization authority](../../firmament-serialization-compatibility.md), [format routing](format-routing.md), and [CLI matrix](cli-compatibility-matrix.md).
diff --git a/docs/architecture/artifacts/archaeology-m2/cli-compatibility-matrix.md b/docs/architecture/artifacts/archaeology-m2/cli-compatibility-matrix.md
new file mode 100644
index 00000000..10bbced7
--- /dev/null
+++ b/docs/architecture/artifacts/archaeology-m2/cli-compatibility-matrix.md
@@ -0,0 +1,11 @@
+# CLI compatibility matrix
+
+| Input | build | validate | inspect | asm | export |
+|---|---|---|---|---|---|
+| V2 `.firmament` | current | current | current | n/a | current |
+| V2 `.firmasm` | profile-specific | n/a | `asm inspect` current | `asm inspect` / `export-ap242` | current AP242 |
+| V1 TOON | compatibility fallback | V2-only (rejects) | V2-only (rejects) | n/a | compatibility STEP |
+| V1 JSON | compatibility fallback | V2-only (rejects) | V2-only (rejects) | n/a | compatibility STEP |
+| legacy JSON `.firmasm` | n/a | n/a | `asm inspect` migration | `asm exec` legacy direct path | `asm export` STEP/package; `export-ap242` via migration |
+
+`asm exec` and `asm export` are retained legacy JSON `.firmasm` compatibility commands and surface one deprecation diagnostic. The extension itself remains current for V2 Assembly documents.
diff --git a/docs/architecture/artifacts/archaeology-m2/format-routing.md b/docs/architecture/artifacts/archaeology-m2/format-routing.md
new file mode 100644
index 00000000..4bda0e6d
--- /dev/null
+++ b/docs/architecture/artifacts/archaeology-m2/format-routing.md
@@ -0,0 +1,9 @@
+# Format routing
+
+- V1 TOON: `FirmamentV1ToonReader` -> `FirmamentParsedDocument` -> retained V1 validation/lowering/execution.
+- V1 JSON: `FirmamentV1JsonReader` -> the same normalized V1 model.
+- Historical auto-detection: `LegacyFirmamentV1SourceReader`; JSON is selected only when it is valid JSON, otherwise TOON is decoded.
+- Legacy JSON `.firmasm`: `LegacyFirmasmJsonReader` -> flat manifest/load bridge -> deterministic V2 Assembly migration with `LegacyExplicit` placement.
+- Current V2 `.firmasm`: `FirmamentAssemblyDocumentCompiler` -> current Assembly parser. JSON shape alone selects the named legacy reader.
+
+The legacy readers preserve data and diagnostics; they do not assign V2 engineering meaning.
diff --git a/docs/architecture/artifacts/archaeology-m2/geometry-parity.md b/docs/architecture/artifacts/archaeology-m2/geometry-parity.md
new file mode 100644
index 00000000..fdbdae52
--- /dev/null
+++ b/docs/architecture/artifacts/archaeology-m2/geometry-parity.md
@@ -0,0 +1,5 @@
+# Geometry parity
+
+M2 changes reader/facade ownership only. The retained V1 compiler, lowering, executor, and STEP exporter are unchanged. A real CLI build of `box_basic.firmament` completed through the compatibility route and produced the recorded deterministic STEP hash in [model-equivalence.md](model-equivalence.md).
+
+Legacy JSON `.firmasm` migration retains all OCCT AS1 instance transforms as `LegacyExplicit`; the migration test proves it emits no `Mate` records. No geometry or placement semantics were reinterpreted.
diff --git a/docs/architecture/artifacts/archaeology-m2/model-equivalence.md b/docs/architecture/artifacts/archaeology-m2/model-equivalence.md
new file mode 100644
index 00000000..7e680991
--- /dev/null
+++ b/docs/architecture/artifacts/archaeology-m2/model-equivalence.md
@@ -0,0 +1,13 @@
+# Model equivalence and deterministic serialization
+
+The codec test uses equivalent V1 TOON and JSON documents and compares their normalized `FirmamentParsedDocument` fields (header, model, operation identity, family, and raw fields). The V1 TOON writer is read/write/read stable and emits LF only.
+
+Representative V1 TOON fixture evidence:
+
+| Input | SHA-256 |
+|---|---|
+| `testdata/firmament/examples/box_basic.firmament` | `FF568A3C34D8F198035E3C2AD2F0C98A58BCD6D7BF41F2BAD4A82E06ACC8CB11` |
+| generated STEP through compatibility build | `EA7B9303D850C3CBF985CD478D68CAF4B415C0B060E304ECA6A779F1E72635DC` |
+| `testdata/firmasm/examples/occt-as1/as1-assembly.firmasm` | `9A96D379BD3E0326898EC37D6A8565C052419C322F6325C686FC38BF27518EAE` |
+
+Diagnostics are explicit: invalid declared V1 JSON reports `Firmament V1 JSON compatibility input is not valid JSON`; accepted V1 builds carry `firmament-v1-compatibility-input`; legacy JSON `.firmasm` carries `legacy-firmasm-syntax`.
diff --git a/docs/architecture/artifacts/archaeology-m2/validation-report.md b/docs/architecture/artifacts/archaeology-m2/validation-report.md
new file mode 100644
index 00000000..a48edb16
--- /dev/null
+++ b/docs/architecture/artifacts/archaeology-m2/validation-report.md
@@ -0,0 +1,12 @@
+# Validation report
+
+- `dotnet restore Aetheris.slnx`: passed.
+- `dotnet build Aetheris.slnx -f net10.0 --no-restore /m:1`: passed.
+- Active Firmament suite: 1,115 passed.
+- Opt-in V1 compatibility suite (`AETHERIS_RUN_LEGACY_TESTS=1`): 1,734 passed.
+- Focused V1 codec, legacy loader, and V2 assembly firewall tests: 24 passed.
+- CLI assembly routing tests: 6 passed.
+- Server routing tests: 46 passed.
+- Forge Host tests: 10 passed.
+
+The historical `TriangleHexPrismProfileParityLabTests` were not implicated or modified.
diff --git a/docs/architecture/firmament-serialization-compatibility.md b/docs/architecture/firmament-serialization-compatibility.md
new file mode 100644
index 00000000..cf86bdcb
--- /dev/null
+++ b/docs/architecture/firmament-serialization-compatibility.md
@@ -0,0 +1,17 @@
+# Firmament serialization and compatibility formats
+
+Firmament V2 is Aetheris's sole canonical engineering authoring language.
+
+| Identity | Status | Entry point / policy |
+|---|---|---|
+| Firmament V2 `.firmament` | Current authoring | `FirmamentV2Parser` |
+| Firmament V2 `.firmasm` Assembly profile | Current assembly authoring | `FirmamentAssemblyDocumentCompiler` |
+| Firmament V1 TOON | Historical serialization and compatibility input | `FirmamentV1ToonReader`; canonical output: `FirmamentV1ToonWriter` |
+| Firmament V1 JSON | Historical serialization and compatibility input | `FirmamentV1JsonReader`; read-only |
+| Legacy JSON `.firmasm` | Deprecated transform-first compatibility serialization | `LegacyFirmasmJsonReader` |
+
+`LegacyFirmamentV1SourceReader` preserves the old JSON-vs-TOON auto-detection route for V1 callers. It is a compatibility adapter, never V2 source semantics.
+
+Legacy JSON `.firmasm` remains an explicit migration input to the V2 Assembly profile. Its flat occurrence transforms are preserved as `Placement LegacyExplicit`; migration must not invent Interfaces, Roles, Mates, hierarchy, or any other modern engineering semantics absent from the historical data.
+
+There is no V1 JSON writer and no same-format legacy JSON `.firmasm` writer. The V1 canonical historical write form is TOON. Legacy `.firmasm` export remains the existing STEP/package compatibility route, not JSON round-trip serialization.
diff --git a/docs/firmament-author-rules.md b/docs/firmament-author-rules.md
index 998f898a..9367ce87 100644
--- a/docs/firmament-author-rules.md
+++ b/docs/firmament-author-rules.md
@@ -1,3 +1,7 @@
+# Historical / Firmament V1 Compatibility Documentation
+
+> This document describes the legacy Firmament V1 authoring/execution model retained for compatibility and regression coverage. Firmament V2 is the current canonical authoring language; see [the serialization authority](architecture/firmament-serialization-compatibility.md).
+
# Firmament Author Rules
These rules apply to **any LLM or developer generating or editing `.firmament` files** in the Aetheris repository.
diff --git a/docs/firmament-build-workflow.md b/docs/firmament-build-workflow.md
index 98a69d66..bf3a25e4 100644
--- a/docs/firmament-build-workflow.md
+++ b/docs/firmament-build-workflow.md
@@ -1,3 +1,7 @@
+# Historical / Firmament V1 Compatibility Documentation
+
+> This document describes the legacy Firmament V1 workflow retained for compatibility and regression coverage. Firmament V2 is the current canonical authoring language; see [the serialization authority](architecture/firmament-serialization-compatibility.md).
+
# Firmament Build and Export Workflow
This document describes the current Firmament v1 golden path as it exists in the repository today.
diff --git a/docs/firmament-demo.md b/docs/firmament-demo.md
index 9d450a57..cd71a102 100644
--- a/docs/firmament-demo.md
+++ b/docs/firmament-demo.md
@@ -1,3 +1,7 @@
+# Historical / Firmament V1 Compatibility Documentation
+
+> This document describes the legacy Firmament V1 workflow retained for compatibility and regression coverage. Firmament V2 is the current canonical authoring language; see [the serialization authority](architecture/firmament-serialization-compatibility.md).
+
# Firmament Demo Script
Use this when you need to demo Firmament v1 quickly and without improvising.
diff --git a/docs/firmament-language-shape.md b/docs/firmament-language-shape.md
index 8f9170b4..67788c2a 100644
--- a/docs/firmament-language-shape.md
+++ b/docs/firmament-language-shape.md
@@ -1,3 +1,7 @@
+# Historical / Firmament V1 Compatibility Documentation
+
+> This document describes the legacy Firmament V1 syntax retained for compatibility and regression coverage. Firmament V2 is the current canonical authoring language; see [the serialization authority](architecture/firmament-serialization-compatibility.md).
+
# Firmament Language Shape
This document defines the **canonical source shape** of `.firmament` files used by the Aetheris Firmament DSL.
diff --git a/docs/firmament-overview.md b/docs/firmament-overview.md
index 421bb7c2..44b4b569 100644
--- a/docs/firmament-overview.md
+++ b/docs/firmament-overview.md
@@ -1,3 +1,7 @@
+# Historical / Firmament V1 Compatibility Documentation
+
+> This document describes the legacy Firmament V1 authoring/execution model retained for compatibility and regression coverage. Firmament V2 is the current canonical authoring language; see [the serialization authority](architecture/firmament-serialization-compatibility.md).
+
# Firmament Overview
Firmament now includes bounded static logic: PascalCase `Enum` declarations and exhaustive enum/boolean `Match` expressions are evaluated into typed Concept IR and erased before Feature AIR. This is compile-time selection, not runtime behavior or general scripting. See [CONCEPT-STATIC-LOGIC-M3](concept-static-logic-m3.md).
diff --git a/docs/firmament-placement-semantics.md b/docs/firmament-placement-semantics.md
index e75e65ff..3ae63194 100644
--- a/docs/firmament-placement-semantics.md
+++ b/docs/firmament-placement-semantics.md
@@ -1,3 +1,7 @@
+# Historical / Firmament V1 Compatibility Documentation
+
+> This document describes the legacy Firmament V1 placement model retained for compatibility and regression coverage. Firmament V2 is the current canonical authoring language; see [the serialization authority](architecture/firmament-serialization-compatibility.md).
+
# Firmament Placement Semantics (current executable rules)
This is the bounded, executable placement model in current Firmament.
diff --git a/docs/firmament-selectors.md b/docs/firmament-selectors.md
index fe4bd137..52b7fdc0 100644
--- a/docs/firmament-selectors.md
+++ b/docs/firmament-selectors.md
@@ -1,3 +1,7 @@
+# Historical / Firmament V1 Compatibility Documentation
+
+> This document describes the legacy Firmament V1 selector model retained for compatibility and regression coverage. Firmament V2 is the current canonical authoring language; see [the serialization authority](architecture/firmament-serialization-compatibility.md).
+
# Firmament Selector Contracts + Primitive Semantic Naming (current v1 reality)
This document is the source-of-truth summary for the selector/semantic naming surface that is implemented **today**.
diff --git a/testdata/firmasm/README.md b/testdata/firmasm/README.md
index c94e31c6..5bf87426 100644
--- a/testdata/firmasm/README.md
+++ b/testdata/firmasm/README.md
@@ -1,4 +1,6 @@
-# .firmasm examples (ASM-A0)
+# Legacy JSON `.firmasm` compatibility fixtures (ASM-A0)
+
+> Historical compatibility serialization: these JSON manifests are not the current `.firmasm` authoring language. Current `.firmasm` is the Firmament V2 Assembly document profile.
`.firmasm` manifests are JSON objects with four top-level sections: