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.csindex 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 CliRunnerfeatures = 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 CliRunnerstdout.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.csnew file mode 100644index 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.csindex 5a555e43..b85f73a9 100644--- a/Aetheris.Kernel.Firmament/Assembly/FirmamentAssemblyDocumentProfile.cs+++ b/Aetheris.Kernel.Firmament/Assembly/FirmamentAssemblyDocumentProfile.cs@@ -38,7 +38,7 @@ public sealed class FirmamentAssemblyDocumentCompilervar 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.csindex 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.csindex 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.csnew file mode 100644index 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.csnew file mode 100644index 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.csindex 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.csindex 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.csindex 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.csindex 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdindex 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 RulesThese 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.mdindex 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 WorkflowThis 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.mdindex 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 ScriptUse 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.mdindex 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 ShapeThis 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.mdindex 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 OverviewFirmament 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.mdindex 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.mdindex 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.mdindex 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: