Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel
Enforce Firmament V2 authoring boundary
Yuechen Li304eddcfe864
diff --git a/Aetheris.CLI/CliRunner.cs b/Aetheris.CLI/CliRunner.csindex 1d335372..9f21f209 100644--- a/Aetheris.CLI/CliRunner.cs+++ b/Aetheris.CLI/CliRunner.cs@@ -3497,7 +3497,9 @@ Model CanonicalPanel {private static void WriteBuildHelp(TextWriter stdout){- stdout.WriteLine("Build .firmament input into STEP output.");+ stdout.WriteLine("Build canonical Firmament V2 .firmament input into STEP output.");+ stdout.WriteLine("Explicitly versioned Firmament V1 TOON/JSON files remain readable through the historical compatibility route and emit one warning.");+ stdout.WriteLine("Legacy JSON .firmasm is a separate assembly compatibility format; inspect or export it with 'aetheris asm'.");stdout.WriteLine();stdout.WriteLine(BuildUsage);stdout.WriteLine();diff --git a/Aetheris.Kernel.Core/Brep/Boolean/BrepBoolean.cs b/Aetheris.Kernel.Core/Brep/Boolean/BrepBoolean.csindex d31925c2..22595880 100644--- a/Aetheris.Kernel.Core/Brep/Boolean/BrepBoolean.cs+++ b/Aetheris.Kernel.Core/Brep/Boolean/BrepBoolean.cs@@ -140,9 +140,11 @@ internal sealed record BooleanSubtractIntersectContext(string? SubtractPocketUnsupportedReason);/// <summary>-/// bounded boolean pipeline with narrow real support for axis-aligned box/box cases that resolve to a single box-/// plus the M10k box-minus-Z-aligned-through-cylinder subset that rebuilds to a single box-with-hole solid.-/// Unsupported and non-solid cases return deterministic NotImplemented diagnostics.+/// Bounded compatibility and generic recognized-family facade. This is not a+/// universal exact Boolean kernel: only explicitly admitted operand families are+/// reconstructed, and unsupported arbitrary combinations return typed diagnostics.+/// New semantic construction should use a higher-level construction API or a+/// recognized Recipe so known intent is not rediscovered from temporary bodies./// </summary>public static class BrepBoolean{diff --git a/Aetheris.Kernel.Firmament.Tests/Compatibility/FirmamentV1CodecTests.cs b/Aetheris.Kernel.Firmament.Tests/Compatibility/FirmamentV1CodecTests.csindex 0a605b76..9884fc46 100644--- a/Aetheris.Kernel.Firmament.Tests/Compatibility/FirmamentV1CodecTests.cs+++ b/Aetheris.Kernel.Firmament.Tests/Compatibility/FirmamentV1CodecTests.cs@@ -55,6 +55,32 @@ public sealed class FirmamentV1CodecTestsAssert.Contains(result.Diagnostics, diagnostic => diagnostic.Message.Contains("V1 JSON compatibility", StringComparison.Ordinal));}+ [Theory]+ [InlineData("2")]+ [InlineData("preview")]+ public void NamedV1Readers_RejectOtherDeclaredVersions(string version)+ {+ var toon = new FirmamentV1ToonReader().Read($"""+ firmament:+ version: {version}+ model:+ name: not_v1+ units: mm+ ops[0]:+ """);+ var json = new FirmamentV1JsonReader().Read($$"""+ { "firmament": { "version": "{{version}}" }, "model": { "name": "not_v1", "units": "mm" }, "ops": [] }+ """);++ Assert.False(toon.IsSuccess);+ Assert.False(json.IsSuccess);+ Assert.All(toon.Diagnostics.Concat(json.Diagnostics), diagnostic =>+ {+ Assert.Equal("FirmamentV1.CompatibilityReader", diagnostic.Source);+ Assert.Contains("must declare version '1'", diagnostic.Message, StringComparison.Ordinal);+ });+ }+private static object Snapshot(FirmamentParsedDocument document) => new{document.Firmament.Version,diff --git a/Aetheris.Kernel.Firmament.Tests/FirmamentV2DiagnosticRoutingBuildTests.cs b/Aetheris.Kernel.Firmament.Tests/FirmamentV2DiagnosticRoutingBuildTests.csindex 7c3923e0..23c2cc23 100644--- a/Aetheris.Kernel.Firmament.Tests/FirmamentV2DiagnosticRoutingBuildTests.cs+++ b/Aetheris.Kernel.Firmament.Tests/FirmamentV2DiagnosticRoutingBuildTests.cs@@ -58,6 +58,7 @@ Modify Base { EdgeFinish Break { Face: +Z Target: Boundary Kind: Chamfer DistancAssert.Equal(FirmamentV2ParseDisposition.NotRecognized, v2.Disposition);Assert.True(result.IsSuccess, string.Join(Environment.NewLine, result.Diagnostics.Select(diagnostic => diagnostic.Message)));+ Assert.Single(result.Diagnostics, diagnostic => diagnostic.Message.StartsWith("firmament-v1-compatibility-input:", StringComparison.Ordinal));}finally{@@ -65,6 +66,56 @@ Modify Base { EdgeFinish Break { Face: +Z Target: Boundary Kind: Chamfer Distanc}}+ [Fact]+ public void CompileSource_ValidLegacyToon_CannotCrossCanonicalV2Boundary()+ {+ var source = File.ReadAllText(Path.Combine(RepoRoot(), "testdata", "firmament", "examples", "box_basic.firmament"));++ var result = FirmamentBuildAndExport.CompileSource(source);++ Assert.False(result.IsSuccess);+ Assert.Contains(result.Diagnostics, diagnostic => diagnostic.Source == "FirmamentV2.CompatibilityFirewall");+ Assert.DoesNotContain(result.Diagnostics, diagnostic => diagnostic.Message.StartsWith("firmament-v1-compatibility-input:", StringComparison.Ordinal));+ }++ [Theory]+ [InlineData("2")]+ [InlineData("preview")]+ public void Build_SerializationShapedNonV1Document_DoesNotExecuteAsV1(string version)+ {+ var path = Path.Combine(Path.GetTempPath(), $"aetheris-v2-firewall-{Guid.NewGuid():N}.firmament");+ var output = Path.ChangeExtension(path, ".step");+ File.WriteAllText(path, $"""+ firmament:+ version: {version}+ model:+ name: must_not_fallback+ units: mm+ ops[1]:+ -+ op: box+ id: base+ size[3]:+ 10+ 10+ 10+ """);+ try+ {+ var result = FirmamentBuildAndExport.Run(path, output);++ Assert.False(result.IsSuccess);+ Assert.False(File.Exists(output));+ Assert.Contains(result.Diagnostics, diagnostic => diagnostic.Source == "FirmamentV1.CompatibilityReader");+ Assert.DoesNotContain(result.Diagnostics, diagnostic => diagnostic.Message.StartsWith("firmament-v1-compatibility-input:", StringComparison.Ordinal));+ }+ finally+ {+ File.Delete(path);+ File.Delete(output);+ }+ }+private static string FixturePath() => Path.Combine(RepoRoot(), "fixtures", "FirmamentV2", "Language", "invalid", "concept-struct-diagnostic-routing-x1.invalid.firmfixture");private static string RepoRoot() => Path.GetFullPath(Path.Combine(AppContext.BaseDirectory, "../../../../"));}diff --git a/Aetheris.Kernel.Firmament/Compatibility/V1/FirmamentV1Codecs.cs b/Aetheris.Kernel.Firmament/Compatibility/V1/FirmamentV1Codecs.csindex 76cf1212..e0a6bf9e 100644--- a/Aetheris.Kernel.Firmament/Compatibility/V1/FirmamentV1Codecs.cs+++ b/Aetheris.Kernel.Firmament/Compatibility/V1/FirmamentV1Codecs.cs@@ -8,13 +8,13 @@ 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);+ public KernelResult<FirmamentParsedDocument> Read(string sourceText) => FirmamentV1CodecContract.RequireV1(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);+ public KernelResult<FirmamentParsedDocument> Read(string sourceText) => FirmamentV1CodecContract.RequireV1(FirmamentTopLevelParser.ReadJson(sourceText));}/// <summary>@@ -23,7 +23,22 @@ public sealed class FirmamentV1JsonReader/// </summary>public sealed class LegacyFirmamentV1SourceReader{- public KernelResult<FirmamentParsedDocument> ReadAuto(string sourceText) => FirmamentTopLevelParser.ReadAuto(sourceText);+ public KernelResult<FirmamentParsedDocument> ReadAuto(string sourceText) => FirmamentV1CodecContract.RequireV1(FirmamentTopLevelParser.ReadAuto(sourceText));+}++internal static class FirmamentV1CodecContract+{+ public static KernelResult<FirmamentParsedDocument> RequireV1(KernelResult<FirmamentParsedDocument> decoded)+ {+ if (!decoded.IsSuccess || string.Equals(decoded.Value.Firmament.Version, "1", StringComparison.Ordinal)) return decoded;+ return KernelResult<FirmamentParsedDocument>.Failure([+ new Aetheris.Kernel.Core.Diagnostics.KernelDiagnostic(+ Aetheris.Kernel.Core.Diagnostics.KernelDiagnosticCode.ValidationFailed,+ Aetheris.Kernel.Core.Diagnostics.KernelDiagnosticSeverity.Error,+ $"Firmament V1 compatibility input must declare version '1'; found '{decoded.Value.Firmament.Version}'.",+ "FirmamentV1.CompatibilityReader")+ ]);+ }}/// <summary>Deterministic LF-only writer for the historical Firmament V1 TOON form.</summary>diff --git a/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs b/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.csindex cc5912c2..6aa4cfd4 100644--- a/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs+++ b/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs@@ -37,7 +37,7 @@ public static class FirmamentBuildAndExportvar fullSourcePath = Path.GetFullPath(sourcePath);var sourceText = NormalizeLf(File.ReadAllText(fullSourcePath, Encoding.UTF8));- var exportResult = ExportSource(sourceText, Path.GetDirectoryName(fullSourcePath));+ var exportResult = ExportSource(sourceText, Path.GetDirectoryName(fullSourcePath), allowV1Compatibility: true);if (!exportResult.IsSuccess){return KernelResult<FirmamentBuildAndExportResult>.Failure(exportResult.Diagnostics);@@ -60,7 +60,8 @@ public static class FirmamentBuildAndExportnew FirmamentBuildAndExportResult(fullSourcePath,resolvedOutputPath,- export));+ export),+ exportResult.Diagnostics);}/// <summary>@@ -73,7 +74,10 @@ public static class FirmamentBuildAndExport{ArgumentNullException.ThrowIfNull(sourceText);var normalized = NormalizeLf(sourceText);- var export = ExportSource(normalized, sourceDirectory);+ // In-memory compilation is the canonical V2 boundary used by Forge,+ // assemblies, and drawings. Historical V1 execution is intentionally+ // available only to the explicitly versioned file compatibility route.+ var export = ExportSource(normalized, sourceDirectory, allowV1Compatibility: false);if (!export.IsSuccess) return export;var assertions = EvaluateVolumeAssertions(normalized, sourceDirectory, export.Value);return assertions.IsSuccess@@ -107,7 +111,10 @@ public static class FirmamentBuildAndExport}- private static KernelResult<FirmamentStepExportResult> ExportSource(string sourceText, string? sourceDirectory = null)+ private static KernelResult<FirmamentStepExportResult> ExportSource(+ string sourceText,+ string? sourceDirectory = null,+ bool allowV1Compatibility = false){// The V2 parser owns canonical-root admission. Profile/composition// materializers consume only the extracted normalized declaration body,@@ -324,11 +331,47 @@ public static class FirmamentBuildAndExport"FirmamentV2.Parse")).ToArray());}- // V1 is not a peer authoring route: this is the sole retained build fallback- // for historical serialized source and deliberately emits one concise warning.+ if (!allowV1Compatibility)+ {+ return V2SourceRequired(v2Parse);+ }++ // V1 is not a peer authoring route. File builds admit it only when the+ // historical reader proves that the document explicitly declares version 1.+ // This prevents V1's permissive serialization parser from accepting malformed+ // or serialization-shaped V2 input.+ var compatibility = new Compatibility.V1.LegacyFirmamentV1SourceReader().ReadAuto(sourceText);+ if (!compatibility.IsSuccess)+ {+ return KernelResult<FirmamentStepExportResult>.Failure(compatibility.Diagnostics);+ }+ if (!string.Equals(compatibility.Value.Firmament.Version, "1", StringComparison.Ordinal))+ {+ return V2SourceRequired(v2Parse);+ }+return ExportV1CompatibilitySource(sourceText);}+ private static KernelResult<FirmamentStepExportResult> V2SourceRequired(FirmamentV2ParseResult parse)+ {+ var fatal = parse.Diagnostics+ .Where(FirmamentV2Parser.IsFatalDiagnosticCode)+ .Distinct(StringComparer.Ordinal)+ .Select(code => new Kernel.Core.Diagnostics.KernelDiagnostic(+ Kernel.Core.Diagnostics.KernelDiagnosticCode.ValidationFailed,+ Kernel.Core.Diagnostics.KernelDiagnosticSeverity.Error,+ code,+ "FirmamentV2.Parse"))+ .ToList();+ fatal.Add(new Kernel.Core.Diagnostics.KernelDiagnostic(+ Kernel.Core.Diagnostics.KernelDiagnosticCode.ValidationFailed,+ Kernel.Core.Diagnostics.KernelDiagnosticSeverity.Error,+ "firmament-v2-source-required: canonical in-memory compilation requires Firmament V2; historical V1 is accepted only from an explicitly versioned file compatibility input.",+ "FirmamentV2.CompatibilityFirewall"));+ return KernelResult<FirmamentStepExportResult>.Failure(fatal);+ }+private static KernelResult<FirmamentStepExportResult> ExportV1CompatibilitySource(string sourceText){var legacy = FirmamentStepExporter.Export(new FirmamentCompileRequest(new FirmamentSourceDocument(sourceText)));diff --git a/README.md b/README.mdindex ca19faef..2982f215 100644--- a/README.md+++ b/README.md@@ -9,6 +9,8 @@Firmament is a deterministic DSL for generating CAD geometry (STEP AP242) via Aetheris.+Firmament V2 is the sole canonical authoring path. Firmament V1 TOON/JSON and JSON-shaped legacy `.firmasm` remain explicit compatibility/serialization inputs. See the [current authoring and kernel boundaries](docs/architecture/current-authoring-and-kernel-boundaries.md).+## Static engineering dataFirmament `Record` values are immutable typed specifications. A finite standards@@ -46,7 +48,8 @@ limitations are at [yuechen-li-dev.github.io/aetheris](https://yuechen-li-dev.gi## What works today-- primitives and booleans: `box`, `cylinder`, `sphere`, `add`, `subtract`, `intersect`+- canonical V2 semantic construction, including bounded exact through-hole Recipes+- historical V1 primitive/Boolean execution retained as explicit compatibility- placement with `place.on` anchors and `offset[3]`- validation ops: `expect_exists`, `expect_selectable`, `expect_manifold`- schema-aware CNC minimum tool radius validationdiff --git a/docs/architecture-overview.md b/docs/architecture-overview.mdindex e1e78a93..b380268d 100644--- a/docs/architecture-overview.md+++ b/docs/architecture-overview.md@@ -1,4 +1,6 @@-# Architecture Overview (Provisional)+# Architecture Overview (Historical package sketch)++> Current architecture: see [Current authoring and kernel boundaries](architecture/current-authoring-and-kernel-boundaries.md). This older package sketch is retained for historical context and is not the current authoring/kernel authority.This package map is directional only and may evolve with milestone outcomes.diff --git a/docs/architecture/artifacts/archaeology-m1/README.md b/docs/architecture/artifacts/archaeology-m1/README.mdindex 835e8bdb..0bbbb236 100644--- a/docs/architecture/artifacts/archaeology-m1/README.md+++ b/docs/architecture/artifacts/archaeology-m1/README.md@@ -1,5 +1,7 @@# AETHERIS-ARCHAEOLOGY-M1+> Historical archaeology evidence. Current architecture: see [Current authoring and kernel boundaries](../../current-authoring-and-kernel-boundaries.md).+Status: audit complete; architecture frozen for phased migration. Repository evidence was inspected on 2026-08-13. Runtime architecture is unchanged; two narrow compatibility-test/formatter inconsistencies found by the audit were corrected.## Decisionsdiff --git a/docs/architecture/artifacts/archaeology-m2/README.md b/docs/architecture/artifacts/archaeology-m2/README.mdindex e18182bc..4d4e9350 100644--- a/docs/architecture/artifacts/archaeology-m2/README.md+++ b/docs/architecture/artifacts/archaeology-m2/README.md@@ -1,3 +1,5 @@# AETHERIS-ARCHAEOLOGY-M2 evidence+> Historical archaeology evidence. Current architecture: see [Current authoring and kernel boundaries](../../current-authoring-and-kernel-boundaries.md).+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-m6/README.md b/docs/architecture/artifacts/archaeology-m6/README.mdnew file mode 100644index 00000000..2a1df2e6--- /dev/null+++ b/docs/architecture/artifacts/archaeology-m6/README.md@@ -0,0 +1,16 @@+# AETHERIS-ARCHAEOLOGY-M6 closeout++M6 closes the compatibility-cleanup and Boolean/Firmament boundary archaeology series.++The implemented boundary change makes in-memory compilation (Forge, assembly, drawing) V2-only, gates file-level V1 compatibility on a successfully decoded explicit version `1`, and propagates exactly one successful V1 compatibility warning. Serialization-shaped version `2` or unknown-version input can no longer execute as V1.++Evidence:++- [Final caller map](final-caller-map.md)+- [Deprecation table](deprecation-table.md)+- [Compatibility surface](compatibility-surface.md)+- [Current paths and regression index](current-paths.md)+- [Documentation cleanup](docs-cleanup.md)+- [Validation report](validation-report.md)++Canonical architecture: [Current authoring and kernel boundaries](../../current-authoring-and-kernel-boundaries.md).diff --git a/docs/architecture/artifacts/archaeology-m6/compatibility-surface.md b/docs/architecture/artifacts/archaeology-m6/compatibility-surface.mdnew file mode 100644index 00000000..52eb1590--- /dev/null+++ b/docs/architecture/artifacts/archaeology-m6/compatibility-surface.md@@ -0,0 +1,30 @@+# Compatibility surface inventory++## Firmament V1++| Operation | Classification | Evidence |+|---|---|---|+| read TOON | `RETAIN` | `FirmamentV1ToonReader` |+| read JSON | `RETAIN` | `FirmamentV1JsonReader` |+| auto-detect old serialization | `RETAIN` compatibility adapter | `LegacyFirmamentV1SourceReader`; never V2 semantics |+| canonical TOON write | `RETAIN` | deterministic LF-only round-trip tests |+| compile/validate/execute/STEP export | `DEPRECATE`, retain for compatibility | file build requires decoded version `1`; opt-in V1 suite remains |+| in-memory/Forge execution | `REMOVE_NOW` accidental crossover | `CompileSource` is V2-only after M6 |++There is no V1 JSON writer and no new V1 semantics.++## Legacy JSON `.firmasm`++| Operation | Classification | Evidence |+|---|---|---|+| reader/loader | `RETAIN` | `LegacyFirmasmJsonReader` |+| loader alias | `REMOVE_LATER` | `FirmasmManifestLoader` remains documented compatibility only |+| inspect/display | `RETAIN` | current assembly compiler detects JSON only under `.firmasm` profile |+| direct execute/export | `DEPRECATE`, retain for Preview compatibility | `FirmasmAssemblyExecutor` and CLI `asm` flows |+| same-format JSON writer | absent | no compatibility promise |++Migration preserves flat rigid transforms as `Placement LegacyExplicit`. It does not manufacture hierarchy, Interfaces, Roles, or Mates. Current `.firmasm` remains the V2 Assembly document profile.++## Package/API state++V1 codecs and legacy firmasm compatibility types remain public in their existing packages to avoid an M6 breaking move. `BrepBoolean` remains public. Recipes and Surgery are internal; Forge.Host and KernelSDK have neither public access nor friend-assembly access to Surgery.diff --git a/docs/architecture/artifacts/archaeology-m6/current-paths.md b/docs/architecture/artifacts/archaeology-m6/current-paths.mdnew file mode 100644index 00000000..99f541dc--- /dev/null+++ b/docs/architecture/artifacts/archaeology-m6/current-paths.md@@ -0,0 +1,49 @@+# Current path proofs and preserved regressions++## Current V2 through-hole++```text+Firmament V2 Hole<Shaft>+ -> semantic hole construction+ -> ThroughHoleRecipeRequestBuilder+ -> ThroughHoleConstructionRecipe+ -> internal Surgery loop/face/shell builders+ -> BrepSurgeryValidation+ -> STEP AP242 export/reimport+```++`FirmamentV2SemanticHoleTests`, `RecognizedConstructionRecipeTests`, and the CLI build/inspect dogfood exercise this path. The semantic route emits `semantic AirHoleFeature -> ThroughHoleRecipeRequest -> ThroughHoleConstructionRecipe`; it does not create operands for `BrepBoolean` rediscovery.++## V1 compatibility++```text+explicit firmament.version = 1 file+ -> LegacyFirmamentV1SourceReader+ -> FirmamentCompiler / historical executor+ -> bounded BrepBoolean where retained+ -> STEP + one compatibility warning+```++`FirmamentV2DiagnosticRoutingBuildTests` proves valid V1 file compatibility and proves that the V2-only in-memory boundary rejects the same source.++## Generic server compatibility++```text+two stored external bodies + operation+ -> server Boolean endpoint+ -> BrepBoolean+ -> admitted recognized family OR typed NotImplemented rejection+```++`KernelApiIntegrationTests.UnsupportedBoolean_OnV1_ReturnsUnprocessableEntityWithDiagnosticEnvelope` proves the typed rejection contract.++## Permanent teaching evidence++- stepped root cause and history: `BrepBooleanCoaxialSubtractStackFamilyTests`, `BrepBooleanBoxCylinderHoleContinuationTests`, and `docs/brep-boolean-stack-a0...a4`+- overlap/tangency: Boolean hardening and Firmament safe-subtract graph tests+- rotated/conic limitations: rotated analytic Boolean regression tests and deferred-scope documentation+- mixed continuation: safe-composition mixed analytic/prismatic rejection tests+- generic CIR lesson: `GenericCirBrepExecutorLab` and `SteppedHoleExecutionArchitectureLab`+- legacy-vs-Recipe parity: `RecognizedConstructionRecipeTests` and `BrepSurgeryRecipeParityTests`++These are historical/educational contracts, not invitations to expand the central dispatcher.diff --git a/docs/architecture/artifacts/archaeology-m6/deprecation-table.md b/docs/architecture/artifacts/archaeology-m6/deprecation-table.mdnew file mode 100644index 00000000..e61c14c7--- /dev/null+++ b/docs/architecture/artifacts/archaeology-m6/deprecation-table.md@@ -0,0 +1,19 @@+# Compatibility and deprecation table++| Surface | Status | Replacement | Removal timing | Warning behavior |+|---|---|---|---|---|+| Firmament V2 `.firmament` | supported canonical authoring | none | no planned removal | none |+| Firmament V2 Assembly `.firmasm` | supported canonical assembly profile | none | no planned removal | none |+| V1 TOON reader | retained compatibility | none required for historical data | no planned removal | none on direct read |+| V1 JSON reader | retained compatibility | none required for historical data | no planned removal | none on direct read |+| V1 TOON writer | retained deterministic historical serialization | use V2 for new authoring | later, only with consumer evidence | none |+| V1 compile/execute/export | deprecated compatibility | author new work in V2 | later; no release date promised | one warning after successful file build |+| V1 auto reader adapter | retained compatibility facade | named TOON/JSON readers | later | XML documentation only |+| Legacy JSON `.firmasm` reader | retained compatibility | V2 Assembly `.firmasm` for new work | no planned reader removal | one concise legacy-format diagnostic |+| Legacy `.firmasm` direct execution/export | Preview compatibility | V2 Assembly profile | later, after real consumers migrate | existing concise diagnostic |+| `FirmasmManifestLoader` alias | deprecated-by-documentation adapter | `LegacyFirmasmJsonReader` | later | no `[Obsolete]` warning storm |+| `BrepBoolean` | bounded compatibility/generic facade | Recipes or higher-level semantic construction | no planned removal | typed rejection outside admitted families |+| recognized Recipes | internal preferred exact-construction layer | none | potential future advanced API | none |+| strict Surgery builders | internal | no public replacement yet | reconsider after identity/provenance contracts mature | inaccessible to public callers |+| legacy-sense Surgery seam | internal-only compatibility | strict builders for new representations | later if parity permits | none |+| raw topology mutation | unsafe, not exposed | bounded Recipe/Surgery | no exposure planned | inaccessible |diff --git a/docs/architecture/artifacts/archaeology-m6/docs-cleanup.md b/docs/architecture/artifacts/archaeology-m6/docs-cleanup.mdnew file mode 100644index 00000000..87104ecc--- /dev/null+++ b/docs/architecture/artifacts/archaeology-m6/docs-cleanup.md@@ -0,0 +1,9 @@+# Documentation cleanup++- Added `docs/architecture/current-authoring-and-kernel-boundaries.md` as current authority.+- Linked the repository README and historical architecture overview to it.+- Added consistent forward banners to M1/M2 archaeology records and the stepped-Boolean milestone series without rewriting historical outcomes.+- Kept `docs/boolean-deferred.md` as scope evidence and recorded the central-family freeze policy.+- Finalized the Boolean guide with rotated/conic, overlap/tangency, regression-index, and “Do not do this” guidance.+- Finalized the Surgery guide with the Template-to-Recipe-to-Surgery decision ladder.+- Updated `BrepBoolean` API documentation and CLI build help to distinguish canonical V2, V1 compatibility, and legacy JSON `.firmasm`.diff --git a/docs/architecture/artifacts/archaeology-m6/final-caller-map.md b/docs/architecture/artifacts/archaeology-m6/final-caller-map.mdnew file mode 100644index 00000000..f94e4acd--- /dev/null+++ b/docs/architecture/artifacts/archaeology-m6/final-caller-map.md@@ -0,0 +1,22 @@+# Final production BrepBoolean caller map++Direct call sites outside Core, tests, and FrictionLab:++| Milestone | Direct sites | Caller classes |+|---|---:|---:|+| M1 baseline | 15 | 6 |+| M5 | 12 | 4 |+| M6 | 12 | 4 |++M6 deliberately adds no Recipe merely to reduce the count.++| Owner | Sites | Classification | Accepted reason |+|---|---:|---|---|+| `FirmamentPrimitiveExecutor.ExecuteBoolean` | 3 | `LEGACY_V1_COMPATIBILITY` and bounded `CURRENT_SEMANTIC_CALLER` bridge | V1 operation-shaped execution is retained. V2 known through-holes route directly to a Recipe before this bridge; remaining generic add/subtract/intersect operations have no matching semantic Recipe and retain typed rejection. |+| `HoleRecoveryExecutor` | 5 | `UNMIGRATED_SPECIALIZED_FAMILY` | Blind, counterbore, countersink/chamfered, and stepped history need separate topology/history contracts. Profile-stack is preferred where admitted; no cosmetic Recipes were created. |+| `CirBrepMaterializer` box/box subtract | 1 | `GENERIC_CIR_COMPATIBILITY` | Import/recovery has recognized operands but no named reusable construction contract. The recognized box/cylinder path already uses the through-hole Recipe. |+| server `KernelEndpoints` | 3 | `SERVER_EXTERNAL_API` | Public external-body union/subtract/intersect compatibility endpoint. It promises bounded support and surfaces typed `NotImplemented` rejection, not universal Boolean success. |++No `ACCIDENTAL / OBSOLETE` direct caller remains. `ClassifyBooleanCase` has no production caller, but its public signature is preserved for M6 compatibility. Test and FrictionLab callers remain behavior contracts or historical evidence.++No new dispatcher family was added in M6.diff --git a/docs/architecture/artifacts/archaeology-m6/validation-report.md b/docs/architecture/artifacts/archaeology-m6/validation-report.mdnew file mode 100644index 00000000..19e71811--- /dev/null+++ b/docs/architecture/artifacts/archaeology-m6/validation-report.md@@ -0,0 +1,13 @@+# M6 validation report++- `dotnet restore Aetheris.slnx`: succeeded; all projects up to date.+- `dotnet build Aetheris.slnx -f net10.0 --no-restore /m:1`: succeeded with 0 warnings and 0 errors.+- Default solution lane (`Category!=SlowCorpus`): 2,789 passed after the two final codec contract cases were added. Project totals: Core 940; Firmament 1,120; CLI 364; Continuum/SurfaceMeshIR 148; Server 54; Forge.Host 10; FEA 12; Geometry 58; Modules 37; Reconstruction 24; Semantics 9; Collaboration 5; sample 8.+- Full Core lane, including Recipe, Surgery, Boolean compatibility, and STEP AP242 contracts: 959 passed, 0 failed.+- Opt-in Firmament V1 lane: 1,739 passed, 0 failed.+- Focused Boolean/CIR FrictionLab: 40 passed, 0 failed.+- Full opt-in FrictionLab: 394 passed, 5 failed, 399 total.+- The five failures are exactly `TriangleHexPrismProfileParityLabTests`; each throws `ArgumentOutOfRangeException: End must be finite` from `ParameterInterval` through `ProfileExtrusionBRepPlan.cs:128`. They are the documented pre-existing unrelated baseline and no M6 path appears in the stacks.+- Focused V1 codec + malformed-V2 firewall: 12 passed, 0 failed.+- CLI ground truth: top-level and build help clearly separate V2, V1 compatibility, and legacy `.firmasm`; a real V1 file build emitted exactly one `FirmamentV1.Compatibility` warning and produced STEP before the temporary artifact was removed.+- `git diff --check`: clean. Final `git status --short` contains only the intended M6 source, test, and Markdown changes; test-generated STEP artifacts were removed and tracked fixture outputs restored.diff --git a/docs/architecture/current-authoring-and-kernel-boundaries.md b/docs/architecture/current-authoring-and-kernel-boundaries.mdnew file mode 100644index 00000000..5fc7e849--- /dev/null+++ b/docs/architecture/current-authoring-and-kernel-boundaries.md@@ -0,0 +1,54 @@+# Current authoring and kernel boundaries++This page is the canonical map after AETHERIS-ARCHAEOLOGY-M6. Firmament V2 is the sole current authoring language. Historical formats remain readable through explicit compatibility boundaries; they do not define current semantics.++```text+CURRENT AUTHORING+ Firmament V2 (.firmament and the Assembly .firmasm profile)+ -> semantic construction / ConstructionIR+ -> recognized bounded Recipe+ -> internal BRep Surgery+ -> validated BRep -> STEP AP242++HISTORICAL COMPATIBILITY+ explicitly versioned Firmament V1 TOON or JSON+ -> V1 compatibility reader/compiler/executor+ -> bounded BrepBoolean where historical execution requires it++ JSON-shaped legacy .firmasm+ -> LegacyFirmasmJsonReader+ -> transform-preserving migration/direct Preview compatibility++GENERIC COMPATIBILITY+ server or external body Boolean+ -> BrepBoolean+ -> recognized bounded family or typed rejection++GEOMETRY QUERIES+ SignedSide / Distance / Intersection / Contact+ -> evidence only; never topology authority+```++## Boundary rules++- File builds recognize V1 only after its compatibility reader proves an explicit `firmament.version` of `1`. Successful V1 builds emit one compatibility warning.+- `FirmamentBuildAndExport.CompileSource`, used by Forge, assemblies, and drawings, is V2-only. Malformed or legacy source cannot cross that in-memory boundary through V1 fallback.+- `.firmasm` means the current Firmament V2 Assembly document profile. JSON-shaped input is detected as legacy migration data; rigid transforms become `Placement LegacyExplicit`. No hierarchy, Interface, Role, or Mate is invented.+- Recipes own reusable recognized exact-construction intent. They are internal today and are the first plausible future advanced construction surface.+- Surgery realizes caller-authorized topology and remains internal. Identity, provenance, and mutation-safety contracts are not mature enough for Forge.Host or KernelSDK exposure.+- `BrepBoolean` is a bounded compatibility/generic facade, not a universal exact Boolean kernel or the preferred semantic-construction API.+- Geometry queries may support validation and recognition. They do not select trims, loop roles, surviving faces, identity, or feature history.++## Development policy++```text+Template / Module+ -> ConstructionIR or semantic construction+ -> existing Recipe+ -> new bounded reusable Recipe when product use justifies it+ -> internal bespoke Surgery when exact topology is already known+```++A new central `BrepBoolean` family requires a compatibility-critical reason, a documented owner, and a migration/removal plan. Numerical intersection never becomes topology authority.++See [BRep Boolean lessons](../kernel/brep-boolean-lessons.md), [BRep Surgery](../kernel/brep-surgery.md), and the [M6 closeout evidence](artifacts/archaeology-m6/README.md).diff --git a/docs/boolean-deferred.md b/docs/boolean-deferred.mdindex 9a93da10..cd7b761e 100644--- a/docs/boolean-deferred.md+++ b/docs/boolean-deferred.md@@ -1,5 +1,7 @@# Boolean deferred pile (safe-family snapshot)+> Current architecture: see [Current authoring and kernel boundaries](architecture/current-authoring-and-kernel-boundaries.md). Central Boolean-family expansion is frozen unless real compatibility usage justifies a bounded family with an owner and migration plan; current product construction should prefer a Recipe.+This note records the current boolean scope so deferred items can be revisited later without losing context.## Current supported subset (safe family)diff --git a/docs/brep-boolean-stack-a0-stepped-root-cause.md b/docs/brep-boolean-stack-a0-stepped-root-cause.mdindex f3f336be..96c818c7 100644--- a/docs/brep-boolean-stack-a0-stepped-root-cause.md+++ b/docs/brep-boolean-stack-a0-stepped-root-cause.md@@ -1,5 +1,7 @@# BREP-BOOLEAN-STACK-A0 stepped coaxial stack root-cause verification+> Historical evidence; outcomes below are intentionally preserved. Current architecture: see [Current authoring and kernel boundaries](architecture/current-authoring-and-kernel-boundaries.md) and [BRep Boolean lessons](kernel/brep-boolean-lessons.md).+## 1) Purpose and scopeThis milestone verifies (without fixing behavior) whether stepped-hole boolean failure is caused by hard N=2 cliffs in:diff --git a/docs/brep-boolean-stack-a1-nlevel-coaxial-validator.md b/docs/brep-boolean-stack-a1-nlevel-coaxial-validator.mdindex c630a246..66faf652 100644--- a/docs/brep-boolean-stack-a1-nlevel-coaxial-validator.md+++ b/docs/brep-boolean-stack-a1-nlevel-coaxial-validator.md@@ -1,5 +1,7 @@# BREP-BOOLEAN-STACK-A1 N-level coaxial validator generalization+> Historical evidence; outcomes below are intentionally preserved. Current architecture: see [Current authoring and kernel boundaries](architecture/current-authoring-and-kernel-boundaries.md) and [BRep Boolean lessons](kernel/brep-boolean-lessons.md).+## SummaryA1 generalizes safe-composition continuation validation so N-level coaxial subtract stacks are classified before independent-hole interference rejection runs.diff --git a/docs/brep-boolean-stack-a2-stepped-downstream-blocker.md b/docs/brep-boolean-stack-a2-stepped-downstream-blocker.mdindex 2acb748c..ba5b54c7 100644--- a/docs/brep-boolean-stack-a2-stepped-downstream-blocker.md+++ b/docs/brep-boolean-stack-a2-stepped-downstream-blocker.md@@ -1,5 +1,7 @@# BREP-BOOLEAN-STACK-A2 stepped-hole downstream blocker after A1/A1.1 validator fix+> Historical evidence; outcomes below are intentionally preserved. Current architecture: see [Current authoring and kernel boundaries](architecture/current-authoring-and-kernel-boundaries.md) and [BRep Boolean lessons](kernel/brep-boolean-lessons.md).+## OutcomeA2 confirms validator admission succeeds but bounded stepped execution still fails downstream in repeated subtract execution.diff --git a/docs/brep-boolean-stack-a4-stepped-repeated-subtract-productionization.md b/docs/brep-boolean-stack-a4-stepped-repeated-subtract-productionization.mdindex efca5d13..84f090ab 100644--- a/docs/brep-boolean-stack-a4-stepped-repeated-subtract-productionization.md+++ b/docs/brep-boolean-stack-a4-stepped-repeated-subtract-productionization.md@@ -1,5 +1,7 @@# BREP-BOOLEAN-STACK-A4: stepped repeated-subtract productionization (V13.3)+> Historical evidence; outcomes below are intentionally preserved. Current architecture: see [Current authoring and kernel boundaries](architecture/current-authoring-and-kernel-boundaries.md) and [BRep Boolean lessons](kernel/brep-boolean-lessons.md).+## Inputs- A3.1 FrictionLab evidence: repeated-subtract variants succeed on canonical stepped case.- V13.2 contract fix: explicit stepped tier placement semantics on `HoleProfileSegment`.diff --git a/docs/kernel/brep-boolean-lessons.md b/docs/kernel/brep-boolean-lessons.mdindex 41bbc0fc..0474479f 100644--- a/docs/kernel/brep-boolean-lessons.md+++ b/docs/kernel/brep-boolean-lessons.md@@ -57,6 +57,12 @@ A counterbore predicts two cylindrical walls, an annular shoulder, ordered radiiThe generic CIR experiment recursively mapped a Boolean expression tree to `BrepBoolean`. It succeeded only for families already supported below and did not remove stepped/conic limitations. A generic syntax tree is a generic traversal mechanism; it does not create a generic topology reconstruction algorithm.+## Rotated, conic, overlap, and tangency cases++Rotating a cylinder or cone changes more than an axis value: support intersections, seam placement, parameter intervals, face splitting, and orientation all change. The preserved rotated/conic regressions show why recognition success cannot substitute for a complete reconstruction contract. Overlap and tangency are similarly topological events, not merely small distances. A zero-distance witness may mean intended contact, a non-manifold result, coincident support, or tolerance noise; the owning bounded family must decide.++The stepped-hole root-cause and continuation/history suites, overlap/tangency regressions, rotated/conic failures, mixed-continuation evidence, and generic CIR executor lab remain permanent educational evidence. Their entry points are indexed in the [M6 current-paths evidence](../architecture/artifacts/archaeology-m6/current-paths.md).+## Contrasting recipe: polygonal through cutThe polygonal recipe is deliberately not a circular-hole parameterization.@@ -80,6 +86,13 @@ Use this decision ladder:Do not add a central dispatcher case merely because a new pair of bodies can be recognized. The recognition must name a useful construction contract, and the result graph must be predictable enough for explicit validation.+## Do not do this++- Do not convert arbitrary intersection witnesses directly into authoritative trims.+- Do not treat numerical zero as proof of topological identity or intended contact.+- Do not recognize a temporary tool body again when the semantic caller already knows the construction intent.+- Do not add one central dispatcher case per product feature.+### Bespoke bounded exampleFor a known planar plate with a known inner polygonal opening, gather intersection/contact evidence only to check the authored polygon against the support. Author the outer loop and the explicitly ordered inner loop, create one known wall face per inner edge, assemble the caller-selected faces into a shell, validate manifold incidence/bindings/finite geometry, then inspect and reimport STEP. The developer owns the expected topology, orientation, IDs, provenance, and tolerance decisions. `IntersectionQuery` witnesses are not authoritative trims unless that bespoke recipe explicitly adopts them under its own contract.diff --git a/docs/kernel/brep-surgery.md b/docs/kernel/brep-surgery.mdindex 7c2097d5..d4ed4b5d 100644--- a/docs/kernel/brep-surgery.md+++ b/docs/kernel/brep-surgery.md@@ -63,6 +63,15 @@ prism feature knowledge.- Export and reimport through the normal STEP path.- Do not use generic numerical intersections as topology authority.+## Developer decision ladder++1. Use a Template for ordinary reusable product authoring.+2. Use a typed construction primitive when one directly names the result.+3. Use an existing recognized Recipe when its admission contract matches.+4. Add a new reusable Recipe only when a bounded family has repeat product value and a fully predictable topology graph.+5. Use bespoke internal Surgery when the caller already knows the exact topology but reuse does not justify a Recipe.+6. Use bounded generic `BrepBoolean` only for compatibility or experimental external-body workflows; expect typed rejection outside admitted families.+## M3 compatibility seamsSome established Boolean builders predate `DirectedEdgeUse` closure semantics, and orthogonal retessellation can retain T-junction incidence across merged coplanar rectangles. M3 preserves their canonical coedge senses and assembly rather than silently changing STEP. The narrowly named `CreateKnownLoopPreservingLegacySense` shares deterministic coedge-cycle mechanics but deliberately omits the newer endpoint-closure check; it is internal and used only at documented compatibility seams. Strict new loop/shell construction uses `CreateKnownLoop` and `BrepShellAssembler`. The remaining seams are evidence for recipe-local orientation work in M4, not reasons to weaken the strict primitives.