Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Clarify Firmament ownership and use source-adjacent STEP outputs

Yuechen Li2e75ce8dc05a
diff --git a/Aetheris.Kernel.Firmament.Tests/FirmamentBuildAndExportTests.cs b/Aetheris.Kernel.Firmament.Tests/FirmamentBuildAndExportTests.cs
index 42ba41ec..00a4a62c 100644
--- a/Aetheris.Kernel.Firmament.Tests/FirmamentBuildAndExportTests.cs
+++ b/Aetheris.Kernel.Firmament.Tests/FirmamentBuildAndExportTests.cs
@@ -744,7 +744,7 @@ public sealed class FirmamentBuildAndExportTests
public void Run_FrictionLabFlangeBoltCircle_RemovesOverlapBlocker_AndAdvancesPastSchemaVoidGate()
{
var fullSourcePath = Path.Combine(FirmamentCorpusHarness.RepoRoot(), "Aetheris.Firmament.FrictionLab/Cases/flange-bolt-circle/part.firmament");
- var expectedOutputPath = Path.Combine(FirmamentCorpusHarness.RepoRoot(), "Aetheris.Firmament.FrictionLab/Cases/flange-bolt-circle/part.step");
+ var expectedOutputPath = Path.GetFullPath(Path.Combine(FirmamentCorpusHarness.RepoRoot(), "Aetheris.Firmament.FrictionLab/Cases/flange-bolt-circle/part.step"));
if (File.Exists(expectedOutputPath))
{
File.Delete(expectedOutputPath);
@@ -754,7 +754,7 @@ public sealed class FirmamentBuildAndExportTests
Assert.True(result.IsSuccess, string.Join(Environment.NewLine, result.Diagnostics.Select(d => d.Message)));
Assert.True(File.Exists(result.Value.OutputPath));
- Assert.EndsWith(Path.Combine("testdata", "firmament", "exports", "part.step"), result.Value.OutputPath, StringComparison.Ordinal);
+ Assert.Equal(expectedOutputPath, result.Value.OutputPath);
Assert.DoesNotContain(result.Diagnostics, diagnostic =>
diagnostic.Message.Contains("overlapping cylinder-root hole chains are not supported", StringComparison.Ordinal));
Assert.DoesNotContain(result.Diagnostics, diagnostic =>
@@ -766,7 +766,7 @@ public sealed class FirmamentBuildAndExportTests
public void Run_BoundedPocketFixture_WithSealedCavity_RemainsExplicitlyRejected()
{
var fullSourcePath = FirmamentCorpusHarness.ResolveFixtureFullPath("testdata/firmament/fixtures/m13b-unsupported-sealed-pocket-box.firmament");
- var expectedOutputPath = Path.Combine(FirmamentCorpusHarness.RepoRoot(), "testdata", "firmament", "exports", "m13b-unsupported-sealed-pocket-box.step");
+ var expectedOutputPath = Path.ChangeExtension(fullSourcePath, ".step");
if (File.Exists(expectedOutputPath))
{
File.Delete(expectedOutputPath);
@@ -784,7 +784,7 @@ public sealed class FirmamentBuildAndExportTests
private static void AssertExampleBuildAndExport(string sourcePath, string expectedFileName, string expectedFeatureId, int expectedOpIndex, string expectedBodyCategory, string expectedFeatureKind)
{
var fullSourcePath = FirmamentCorpusHarness.ResolveFixtureFullPath(sourcePath);
- var expectedOutputPath = Path.Combine(FirmamentCorpusHarness.RepoRoot(), "testdata", "firmament", "exports", expectedFileName);
+ var expectedOutputPath = Path.ChangeExtension(fullSourcePath, ".step");
if (File.Exists(expectedOutputPath))
{
File.Delete(expectedOutputPath);
@@ -806,7 +806,7 @@ public sealed class FirmamentBuildAndExportTests
private static void AssertUnsupportedBuildAndExport(string sourcePath, string expectedFileName, string expectedFeatureId, string expectedKind)
{
var fullSourcePath = FirmamentCorpusHarness.ResolveFixtureFullPath(sourcePath);
- var expectedOutputPath = Path.Combine(FirmamentCorpusHarness.RepoRoot(), "testdata", "firmament", "exports", expectedFileName);
+ var expectedOutputPath = Path.ChangeExtension(fullSourcePath, ".step");
if (File.Exists(expectedOutputPath))
{
File.Delete(expectedOutputPath);
diff --git a/Aetheris.Kernel.Firmament/Formatting/FirmamentCanonicalFormatter.cs b/Aetheris.Kernel.Firmament/Formatting/FirmamentCanonicalFormatter.cs
index 56ee9b99..3a44c0fb 100644
--- a/Aetheris.Kernel.Firmament/Formatting/FirmamentCanonicalFormatter.cs
+++ b/Aetheris.Kernel.Firmament/Formatting/FirmamentCanonicalFormatter.cs
@@ -15,21 +15,21 @@ internal static class FirmamentCanonicalFormatter
var builder = new StringBuilder();
AppendHeaderSection(builder, document.Firmament);
- builder.AppendLine();
+ builder.Append('\n');
AppendModelSection(builder, document.Model);
if (document.Schema is not null)
{
- builder.AppendLine();
+ builder.Append('\n');
AppendSchemaSection(builder, document.Schema);
}
- builder.AppendLine();
+ builder.Append('\n');
AppendOpsSection(builder, document.Ops);
if (document.Pmi is not null)
{
- builder.AppendLine();
+ builder.Append('\n');
AppendPmiSection(builder, document.Pmi);
}
@@ -99,7 +99,7 @@ internal static class FirmamentCanonicalFormatter
{
if (index > 0)
{
- builder.AppendLine();
+ builder.Append('\n');
}
builder.Append(Indent(1)).Append("-\n");
@@ -114,7 +114,7 @@ internal static class FirmamentCanonicalFormatter
{
if (index > 0)
{
- builder.AppendLine();
+ builder.Append('\n');
}
builder.Append(Indent(1)).Append("-\n");
diff --git a/Aetheris.Kernel.Firmament/README.md b/Aetheris.Kernel.Firmament/README.md
index 2e37bd41..3be3ddb9 100644
--- a/Aetheris.Kernel.Firmament/README.md
+++ b/Aetheris.Kernel.Firmament/README.md
@@ -1,23 +1,16 @@
# Aetheris.Kernel.Firmament
-This project is the future home of Firmament in Aetheris.
+This project owns the Firmament compiler-facing implementation: the canonical Firmament V2 frontend and assembly profile, AIR/materialization bridges, STEP build/export orchestration, plus frozen V1 and legacy `.firmasm` compatibility paths.
-Current status: pre-M0 scaffold only.
+Current architecture:
-Implemented scaffolding:
-- compile boundary contracts (`FirmamentSourceDocument`, `FirmamentCompileRequest`, `FirmamentCompileResult`)
-- Firmament diagnostic taxonomy placeholders and code-family conventions
-- source location contract placeholders (`FirmamentSourcePosition`, `FirmamentSourceSpan`)
-- deterministic compiler facade stub (`FirmamentCompiler`) that reports not implemented
-- tiny pre-M0 curated corpus scaffold (`testdata/firmament/`) with a manifest and placeholder `.firmament` fixtures consumed by tests
+- Firmament V2 is the sole canonical engineering authoring language. `.firmament` is its general document profile and `.firmasm` is its current Assembly profile.
+- `FirmamentV2/` contains the current parser, typed/static authoring, Concepts/Templates, validation, and lowering integration.
+- `Assembly/` contains current Assembly compilation/interchange and the deprecated JSON-shaped `.firmasm` compatibility reader/migration path.
+- `Parsing/`, `ParsedModel/`, `Validation/`, `Lowering/`, the public `FirmamentCompiler`, and related `op`/`expect` execution represent the older V1 TOON/JSON path. They remain for build compatibility and historical regression, not for new language features.
+- `Materializer/` and parts of `Execution/` are shared implementation substrate; do not assume every file in those folders is V1-owned.
+- `FirmamentBuildAndExport` routes recognized V2 documents through current paths and retains a V1 export fallback for unrecognized historical documents.
-Not implemented yet: parser, semantic validation, selectors, lowering, or STEP behavior. The corpus scaffold is infrastructure-only and will be expanded by future parser/validator/lowering work.
+The V1 parser accepts both TOON-style and JSON-shaped documents and normalizes them into `FirmamentParsedDocument`. Its formatter emits deterministic canonical TOON, not lossless source preservation and not JSON. The broad V1 test suite is opt-in through `AETHERIS_RUN_LEGACY_TESTS=1`.
-The top-level lanes (`Connectors`, `ParsedModel`, `Lanes`, `Mapping`, `Diagnostics`) are intentionally separated to guide future implementation work.
-
-Pre-M0 composition seam note: `ImportOrchestrator.CreateDefault(...)` now supports additive registration while keeping STEP/AP242 as the default import composition, so Firmament can later register its own source-family connector/lane without reshaping STEP-specific wiring.
-
-Canonical corpus note: repository `.firmament` fixtures under `testdata/firmament/fixtures/` are maintained only in canonical TOON-style Firmament syntax; JSON-shaped source text is supported by parser compatibility but is not canonical corpus form.
-
-
-FORGE-M0c note: reusable external/library parts are routed through `Connectors/FirmamentPartLibraryConnector.cs` (currently `standard_library/*`), while operation/schema parsing/validation/lowering remains lane-owned.
+The authoritative ownership and migration audit is [AETHERIS-ARCHAEOLOGY-M1](../docs/architecture/artifacts/archaeology-m1/README.md). The current V2 language reference is [docs/firmament-v2/language-reference.md](../docs/firmament-v2/language-reference.md).
diff --git a/docs/architecture/artifacts/archaeology-m1/README.md b/docs/architecture/artifacts/archaeology-m1/README.md
new file mode 100644
index 00000000..835e8bdb
--- /dev/null
+++ b/docs/architecture/artifacts/archaeology-m1/README.md
@@ -0,0 +1,57 @@
+# AETHERIS-ARCHAEOLOGY-M1
+
+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.
+
+## Decisions
+
+1. Firmament V2 is the sole canonical engineering authoring language. Its `.firmament` general profile and `.firmasm` Assembly profile are current.
+2. The older `firmament/model/ops/schema/pmi` document has two accepted codecs, TOON-style and JSON-shaped. Both normalize to `FirmamentParsedDocument`; the surrounding validator, lowerer, executor, and `expect` machinery are legacy execution semantics, not serialization.
+3. Legacy JSON `.firmasm` is a third, unrelated format with its own `FirmasmManifest` model. It remains a deprecated compatibility input. Read, migration, direct execution, and outbound STEP-package export are live Preview 3 compatibility paths; same-format JSON writing is absent.
+4. `BrepBoolean` is frozen as a compatibility facade over bounded recognized families. It is not a general intersection-to-topology engine. New surface/tool families require a bounded migration or critical regression justification.
+5. Future topology ownership is split three ways:
+ - geometry/contact/intersection queries produce evidence;
+ - recognized construction recipes decide expected topology;
+ - a small BRep Surgery layer realizes explicit topology and validates it.
+
+## Artifact index
+
+| Artifact | Question answered |
+|---|---|
+| [firmament-v1-map.md](firmament-v1-map.md) | What V1 source, model, semantics, callers, fixtures, and tests exist? |
+| [legacy-firmasm-map.md](legacy-firmasm-map.md) | What does legacy JSON `.firmasm` own and what compatibility remains live? |
+| [boolean-callers.md](boolean-callers.md) | Who calls `BrepBoolean`, with what intent and migration risk? |
+| [boolean-internals-map.md](boolean-internals-map.md) | Which Boolean components are recognition, policy, history, recipes, validation, or low-level mechanics? |
+| [surgery-candidates.md](surgery-candidates.md) | What bounded Surgery Kit surface is justified by existing repetition? |
+| [boolean-lessons.md](boolean-lessons.md) | What did the implemented families teach, and why does central expansion not scale? |
+| [migration-plan.md](migration-plan.md) | What are M2-M6, their compatibility risks, rollback boundaries, test classes, and freeze policy? |
+| [validation-report.md](validation-report.md) | What was inspected and what validation passed? |
+
+## Ownership boundary
+
+```text
+Firmament V2 source (canonical intent)
+ | legacy input only
+ | +------------------------+
+ v | V1 TOON / V1 JSON |
+ recognized construction | legacy JSON .firmasm |
+ | +-----------+------------+
+ v |
+ construction recipe versioned codec
+ | |
+ +--------------+------------------+
+ v
+ explicit BRep Surgery
+ |
+ +--------------+------------------+
+ v v
+ topology + bindings validation/provenance
+
+Geometry queries (side/closest/intersection/contact) feed evidence into
+recognition and validation; they do not decide or author result topology.
+```
+
+## Direct verdict
+
+Firmament V1 TOON/JSON and legacy JSON `.firmasm` can be reclassified as versioned serialization/compatibility formats as an architectural destination, while V2 remains sole canonical authoring. They are **not yet codec-only in implementation**: V1 build fallback and legacy `.firmasm` direct execution/export are live dependencies that M2 must wrap and name explicitly before semantic code can be retired.
+
+The current Boolean stack can be decomposed without losing working knowledge. Repeated topology mechanics are extractable; family recognition, expected-topology policy, and `SafeBooleanComposition` history must remain above that substrate as explicit recipes/state. The safest first implementation milestone is M2, the serialization boundary, because it can remove language/format ambiguity without changing geometry or topology.
diff --git a/docs/architecture/artifacts/archaeology-m1/boolean-callers.md b/docs/architecture/artifacts/archaeology-m1/boolean-callers.md
new file mode 100644
index 00000000..1d3ccd5b
--- /dev/null
+++ b/docs/architecture/artifacts/archaeology-m1/boolean-callers.md
@@ -0,0 +1,37 @@
+# BRep Boolean caller map
+
+## Public surface
+
+`BrepBoolean.Union`, `Subtract`, and `Intersect` are thin calls to `Execute(BooleanRequest)`. `Execute` validates, classifies with `JudgmentEngine`, computes bounded evidence, selects a supported family, rebuilds explicit topology, and validates bindings/manifold structure. `ClassifyBooleanCase` is public but no external production caller was found; `Execute` is called through the operation wrappers.
+
+## Production callers
+
+| Caller | Operation | Intent | Current assumption | Future destination | Migration risk |
+|---|---|---|---|---|---|
+| `FirmamentPrimitiveExecutor.ExecuteBoolean` | union/subtract/intersect | `LEGACY_EXECUTION` plus shared V2 primitive bridge | generic-looking op over bodies; succeeds only for admitted dispatcher families | compatibility facade during M2-M5; V2 callers move to construction recipes | high: removing fallback breaks V1 build and some V2 primitive lowering |
+| `ThroughHoleRecoveryExecutor` | box - cylinder | `KNOWN_CONSTRUCTION` | exact box host and through-cylinder tool are already known | `ThroughHoleRecipe` -> Surgery | low: strongest first recipe migration candidate |
+| `HoleRecoveryExecutor` counterbore/stepped/blind/countersink variants | repeated subtract | `KNOWN_CONSTRUCTION` | policy already knows end condition, coaxial tiers, placement, and tool type | family recipes (`BlindHole`, `Counterbore`, `SteppedCoaxial`, `Countersink`) -> Surgery | medium/high: composition order/history and STEP regressions matter |
+| `CirBrepMaterializer` recognized box-cylinder and box-box nodes | subtract | `IMPORT_RECOVERY` / recognized construction | recognizer has already bounded operand kinds and translations | recognized CIR recovery recipe or compatibility facade | medium: recursive CIR shape does not supply missing topology intent |
+| `StandardLibraryReusableParts.CreateCubeWithHole` | subtract | `KNOWN_CONSTRUCTION` | fixed standard cube-with-through-hole recipe | standard part construction recipe -> Surgery | low; preserve exact canonical output |
+| server `KernelEndpoints` Boolean endpoint | all three | `GENERIC_USER_BOOLEAN`, `SERVER_EXPERIMENTAL` | clients can submit two primitive descriptors and an op, while actual kernel is bounded | compatibility facade with explicit supported-family capability response; eventually advanced/unsafe API or remove | high: externally visible generic promise exceeds implementation |
+| `ProfileStackExtrudeExecutor` | no direct call, constructs `SafeBooleanComposition` and calls builder | `KNOWN_CONSTRUCTION` bypassing facade | complete interval/profile stack is already known | direct hole-stack recipe -> Surgery | medium; evidence that intent can bypass general dispatch |
+
+No direct production `BrepBoolean` call was found in `Aetheris.Forge.Host` or `Aetheris.Forge.KernelSDK`. Forge currently consumes standard construction IR or validated exact BRep, which is the correct separation.
+
+## Experimental and test callers
+
+| Caller group | Classification | Preservation |
+|---|---|---|
+| `GenericCirBrepExecutorLab` | `FRICTIONLAB_ONLY` | keep as evidence that recursive generic execution does not generalize topology reconstruction |
+| `SteppedHoleExecutionArchitectureLab` | `FRICTIONLAB_ONLY` | keep as worked strategy comparison; repeated subtract succeeded where unioned composite tool failed |
+| `FrepBrepRecoveryPolicyLab` | `FRICTIONLAB_ONLY` | keep as policy evidence; do not turn wording into a generic capability claim |
+| `Aetheris.Kernel.Core.Tests/Brep/Boolean/*` | `TEST_ONLY`, behavior/historical/educational | preserve hard family and rejection regressions; reorganize by recipe during M4 |
+| tessellation, enclosed-void, STEP inner-shell tests that construct Boolean results | `TEST_ONLY` downstream integration | retain as compatibility contracts for canonical bodies |
+| Firmament Boolean/primitive execution tests | `TEST_ONLY` legacy behavior contract | keep in opt-in V1 lane until production caller migration, then retain representative recipe regressions |
+
+## Caller policy during migration
+
+- Existing callers may continue through the facade while their output is parity-tested.
+- A new caller must declare construction intent and choose an existing recognized recipe. It may not use the server-style generic escape hatch simply because `Union/Subtract/Intersect` exists.
+- A new surface/tool family is not added to the central dispatcher unless needed for a bounded migration or a critical regression in already-supported behavior.
+- Generic user Boolean remains an explicitly bounded compatibility capability, not a promise of arbitrary BRep support.
diff --git a/docs/architecture/artifacts/archaeology-m1/boolean-internals-map.md b/docs/architecture/artifacts/archaeology-m1/boolean-internals-map.md
new file mode 100644
index 00000000..f173ebdd
--- /dev/null
+++ b/docs/architecture/artifacts/archaeology-m1/boolean-internals-map.md
@@ -0,0 +1,47 @@
+# BRep Boolean internals map
+
+## Pipeline decomposition
+
+| Category | Current components | Architectural reading |
+|---|---|---|
+| facade/orchestration | `BrepBoolean`, `BooleanRequest`, analysis/intersection/classification/rebuild records | compatibility pipeline; keep stable while internals migrate |
+| recognition | `BrepBooleanBoxRecognition`, `CylinderRecognition`, `AnalyticSurfaceRecognition`, `PrismaticToolRecognition`, `PrismaticProfileRecognition`, `HoleFeatureRecognition` | evidence adapters that identify bounded families; belongs above Surgery |
+| policy/routing | top-level and subtract/intersect `JudgmentEngine` candidate ladders, `BooleanGuards`, footprint containment, bounded cell classification | explicit family admission/tie-breaking/rejection; recipe selection, not topology mechanics |
+| history/composition | `SafeBooleanComposition`, `SafeBooleanRootDescriptor`, `SupportedBooleanHole`, `SupportedThroughVoidSet`, `SupportedBlindPrismaticPocket`, open slots/occupied cells | accumulated recognized construction history and policy state; not generic BRep topology state |
+| history validation | `BrepBooleanSafeCompositionGraphValidator` and its continuation `JudgmentEngine` | determines whether a next tool belongs to a supported continuation family |
+| family classification | `BrepBooleanCoaxialSubtractStackFamily`, `BrepBooleanCoaxialCountersinkSubtractFamily` | explicit recognized recipe logic |
+| family topology recipes | `BoxCylinderHoleBuilder`, `CylinderOpenSlotBuilder`, `OrthogonalUnionBuilder`, `PolygonalPrismThroughCutBuilder`, box wrapper, mixed-through-void builder | expected topology is hard-coded from known family facts; preserve as recipes/examples |
+| generic low-level mechanics | `TopologyBuilder`; repeated edge-use -> cyclic coedge/loop construction; vertex/edge lookup; geometry/binding assembly; ID remap/copy code | extraction candidates for Surgery, subject to narrow contracts |
+| validation | `BrepBindingValidator`, `BrepBooleanSafeCompositionGraphValidator`, output checks | structural binding validation is reusable; family admissibility remains above Surgery |
+| diagnostics | `BooleanDiagnostic`, `BooleanDiagnosticContext`, kernel diagnostic mapping, Judgment rejection detail | keep family-aware diagnostics at facade/recipe level; Surgery emits structural diagnostics |
+| generic geometry evidence | `SignedSideQuery`, `ClosestPointQuery`, `IntersectionQuery`, `ContactQuery` and bounded overlap calculations | observational only; never result-topology authority |
+
+## What `SafeBooleanComposition` really is
+
+`SafeBooleanComposition` is not a general history graph of arbitrary topology edits. It records an admitted root family (box, cylinder, polygonal extrusion), analytic holes with span/axis/radii, rectangular open slots, orthogonal occupied cells, through-void sets, and one blind-prismatic-pocket form. The graph validator then decides which next family can safely continue.
+
+Therefore:
+
+- `SafeBooleanRootDescriptor` is recognized root/construction metadata, not a generic shell descriptor;
+- `SupportedBooleanHole` is an analytic hole-recipe segment, not a generic face/loop edit;
+- `SupportedThroughVoidSet` is mixed-family continuation policy;
+- `SupportedBlindPrismaticPocket` is a recognized pocket recipe descriptor;
+- `SafeBooleanComposition` should move toward a compatibility/recipe history envelope, not into `Brep.Surgery`.
+
+The stepped-hole `Holes.Count == 1` historical gate proves that behavior depended on the number and ordering of recognized prior operations, not only current operand geometry.
+
+## Family builders versus surgery candidates
+
+| Existing code | Keep as recipe | Candidate mechanical extraction |
+|---|---|---|
+| box/cylinder/cone/sphere hole body creation | expected walls, entry/exit trims, bottoms, shoulders, senses | cyclic loop construction; analytic curve/surface binding; shell/body assembly; validation |
+| cylinder-root open slot | known cylindrical arc, floor and radial walls | edge reuse/orientation; face-with-loop construction; binding validation |
+| orthogonal union from occupied cells | boundary-cell policy and coplanar rectangle merging | indexed vertex/edge reuse; oriented loop assembly; planar binding |
+| polygonal/prismatic through cut | outer/inner footprint policy and reversed inner orientation | ring extrusion topology, inner-loop insertion, surface binding |
+| mixed analytic + prismatic void | exact admitted coexistence/history rules | remap/copy of topology, geometry and bindings; shell stitching/assembly |
+
+The repeated private `AddLoop`/`AddFaceWithLoop` implementations are the clearest immediate extraction pressure. The large `BoxCylinderHoleBuilder` also repeats body assembly and geometry/binding setup, but M3 should extract mechanics incrementally rather than design a universal edit API.
+
+## Freeze marker
+
+The existing class summary already calls the pipeline bounded and describes narrow support. M1 records the stronger policy here rather than adding attributes that could imply runtime enforcement. M4 should add concise architectural comments at dispatcher candidate construction and family builder entry points, once their destination namespaces are settled.
diff --git a/docs/architecture/artifacts/archaeology-m1/boolean-lessons.md b/docs/architecture/artifacts/archaeology-m1/boolean-lessons.md
new file mode 100644
index 00000000..f9397ca2
--- /dev/null
+++ b/docs/architecture/artifacts/archaeology-m1/boolean-lessons.md
@@ -0,0 +1,94 @@
+# BRep Boolean lessons from the implemented families
+
+## 1. Why the public API looks simpler than the work
+
+`Union`, `Subtract`, and `Intersect` describe set intent. A valid exact BRep result additionally needs bounded trims, vertices, edges, cyclic coedges, loops (including holes), faces on correct supports, oriented closed shells, geometry bindings, stable IDs/provenance, and manifold validation. The dispatcher succeeds where Aetheris already knows enough about the operands and expected result to author that graph directly.
+
+Pairwise surface intersection is only evidence about where supports meet. It does not decide which bounded portions survive, which loops are outer versus inner, whether a contact is tangent/degenerate, how prior trims participate, or what product feature the user intended.
+
+## 2. Repository lessons by family
+
+| Family/history | What makes the implemented case bounded | What expanded when the next case arrived |
+|---|---|---|
+| box x box | axis-aligned extents reduce intersection/classification to interval/cell arithmetic; results are a single box or connected orthogonal cell boundary | partial overlaps, face contacts, pockets, existing occupied cells, connectivity, coplanar face merging, and cases not representable as one box required separate policies/builders |
+| box - cylinder through hole | known planar entry/exit faces, one cylindrical wall, two circular trims, and known inner-loop orientation | offsets, multiple holes, root history, arbitrary axes, tangency, and hole interference required composition state and validators |
+| blind cylinder/cone | one entry face plus a known termination cap; span classification is explicit | entry side, contained tools, cap orientation, cone radii, rotated blind tools, and termination coincidence add distinct topology/tolerance cases |
+| counterbore/countersink | coaxial two-segment stack predicts entry ring, transition/shoulder, deep wall, and optional bottom | radius/depth ordering, cone/cylinder transition representation, entry-face rules, and prior segment history require a named family classifier |
+| stepped coaxial stack | all segments are world-Z, coaxial, with one through segment and ordered top-entry blind tiers | an `Holes.Count == 1` gate rejected the third subtract before builder execution; fixing admission required N-level history policy, then production fixtures exposed placement/order coupling |
+| rotated cylinder/cone | bounded axis recognition and section representation make some through cases tractable | rotated cone remains deferred because the builder/export path has a section-curve representation mismatch; rotated blind cases add termination topology not covered by the through builder |
+| prismatic cuts/keyway | caller supplies a recognized polygon/slot/box footprint with bounded extrusion span; topology is ring extrusion with known inner orientation | root kind, containment, through versus blind, mixed prior analytic history, footprint tangency/overlap, and cylinder-root slot geometry each need separate recognition/rebuild routes |
+| sphere cavity/opening | a single sphere and its containment/opening relationship to a box are known | multiple spheres, mixed sphere+prism history, tangent openings, and partial intersections require new face/loop cases; they remain bounded/deferred |
+| orthogonal union | occupied axis-aligned cells give a finite boundary extraction problem | arbitrary orientations/supports and analytic unions lose the cell-boundary simplification |
+| torus | recognition of a toroidal support exists | topology reconstruction remains deferred: more intersection curve families, multiple branches, periodic parameter domains, tangency and representation/export issues appear before a robust result can be authored |
+
+## 3. Stepped-hole history is architectural evidence
+
+The observed sequence was:
+
+```text
+through (small)
+ -> blind continuation (medium)
+ -> second blind continuation (large/shallow)
+```
+
+The third subtract originally fell through to independent-hole interference because the coaxial continuation classifier ran only when `composition.Holes.Count == 1`. This was not merely a local bug. The gate encoded an implicit topology/history assumption: the recognized result model and policy had only represented a pair. Supporting the third tier required an N-level coaxial classifier with constraints over the whole history (axis, center, span types, radius ordering, depth ordering). The builder could construct an injected N=3 composition in one probe, yet the production route still needed admission, placement, execution ordering, diagnostics, and downstream STEP regression work.
+
+The lesson is that a successful pair builder does not generalize the state machine around it. Prior operation history is part of admissibility and expected topology.
+
+## 4. Recursive generic CIR execution did not remove the problem
+
+`GenericCirBrepExecutorLab` recursively mapped CIR primitives, transforms, and Boolean nodes to `BrepPrimitives` and `BrepBoolean`. Through holes, blind holes, and counterbores succeeded because the lower Boolean stack already supported those exact families. Stepped subtraction still failed; countersink was blocked by primitive exposure in that experiment. Merely making traversal generic moved no topology knowledge: each recursive Boolean node still arrived at the same family dispatcher with the same history, representation, and builder constraints.
+
+The experiment therefore separates two concerns:
+
+- generic expression-tree evaluation is feasible;
+- generic topology reconstruction is not supplied by that evaluation.
+
+## 5. The combinatorial expansion
+
+A robust result depends jointly on:
+
+```text
+source support family x tool support family
+x source topology x tool topology
+x intersection curve/contact type
+x tangency or degeneracy
+x prior operation/composition history
+x bounded parameter domains
+x tolerance state
+x expected output topology and orientation
+```
+
+Adding “one surface” is not one row. It cross-products with supported roots, spans, orientations, prior holes/pockets/slots, coincident/tangent cases, curve representations, trim-domain behavior, exporter representations, and validation expectations. Central dispatcher growth therefore couples recognition, policy, history and topology building into an ever-larger matrix even when every individual implemented family is correct.
+
+## 6. Architecture answer
+
+Generalized BRep Boolean topology reconstruction is unscalable as a central ever-expanding family dispatcher because each admitted case requires bespoke knowledge of the expected bounded topology across a cross-product of supports, operand topology, intersections, degeneracy, history, tolerance, and output representation. Numerical intersection supplies only local geometric evidence; it cannot decide feature intent or the result graph. A central dispatcher makes every new product feature pay for inference across combinations that its authoring path already knew.
+
+The scalable direction is:
+
+```text
+high-level construction intent
+ -> recognized bounded recipe (owns expected topology and policy)
+ -> BRep Surgery (owns explicit graph realization and validation)
+```
+
+## 7. Educational preservation
+
+Preserve as worked examples:
+
+- `BrepBoolean.cs` Judgment routing and deterministic rejection diagnostics;
+- `BrepBooleanOrthogonalUnionBuilder` for cell-boundary reconstruction;
+- `BrepBooleanBoxCylinderHoleBuilder` for through, blind, sphere, counterbore/countersink, and stepped analytic topology;
+- `BrepBooleanPolygonalPrismThroughCutBuilder` for outer/inner loop orientation;
+- `BrepBooleanCylinderOpenSlotBuilder` for mixed plane/cylinder explicit topology;
+- `BrepBooleanBoxMixedThroughVoidBuilder` for history-aware remap/composition;
+- safe-composition graph and stepped root-cause tests;
+- deferred-pile and FrictionLab strategy/generic-executor documents.
+
+Recommended durable docs:
+
+1. `docs/kernel/brep-surgery.md`: contracts and low-level mechanics.
+2. `docs/kernel/brep-boolean-lessons.md`: why Boolean looks simple; intersection versus topology; box/box; through and blind holes; counterbore; stepped N-level history; rotated/conic representation; prismatic/keyway; sphere; torus; recursive CIR; intent plus Surgery.
+
+Later comments should be placed at recipe builder entry points, family classifiers, and Surgery boundaries. They should state the known expected topology and bounding assumptions, plus why policy stays above Surgery; individual mechanical methods need concise invariant comments, not essays.
diff --git a/docs/architecture/artifacts/archaeology-m1/firmament-v1-map.md b/docs/architecture/artifacts/archaeology-m1/firmament-v1-map.md
new file mode 100644
index 00000000..7a86a9b0
--- /dev/null
+++ b/docs/architecture/artifacts/archaeology-m1/firmament-v1-map.md
@@ -0,0 +1,142 @@
+# Firmament V1 ownership map
+
+## Format and normalized model
+
+The V1 document is identified by structure, not extension:
+
+```text
+TOON-style: JSON-shaped:
+firmament: { "firmament": {...},
+model: "model": {...},
+schema: (optional) "schema": {...},
+ops[N]: "ops": [...],
+pmi[N]: (optional) "pmi": [...] }
+ \ /
+ +-- FirmamentTopLevelParser -+
+ |
+ v
+ FirmamentParsedDocument
+ - FirmamentParsedHeader
+ - FirmamentParsedModelHeader
+ - FirmamentParsedSchema?
+ - FirmamentParsedOpsSection
+ - FirmamentParsedPmiSection?
+```
+
+`FirmamentTopLevelParser.Parse` tries `JsonDocument.Parse` first. Valid JSON is decoded by `ParseFromRoot`; otherwise the indentation/count-header TOON parser runs and calls `ParseFromToon`. The two syntaxes are not textual aliases: JSON preserves JSON scalar/object rendering through `JsonElement.ToString()`, while TOON has its own indentation, array-count, and nested-value collapsing rules. They do intentionally converge on the same parsed model and therefore share all post-parse semantics.
+
+## Component ownership and disposition
+
+| Component | Current role | Syntax or semantics | Current callers | Future disposition |
+|---|---|---|---|---|
+| `Parsing/FirmamentTopLevelParser.cs` | TOON + JSON parser, structure checks, placement/schema/PMI decoding | mixed codec and early semantic recognition (`KnownOpKind`) | `FirmamentCompiler`, `FirmamentFormatter`, trace probe indirectly | `KEEP_AS_COMPATIBILITY_READER`; split codec from semantic admission in M2 |
+| `ParsedModel/FirmamentParsed*.cs`, `FirmamentKnownOpKind`, `FirmamentOpFamily` | shared normalized V1 document | mixed; raw fields are codec data, known kinds/families are execution semantics | validators, lowerers, formatter, tests | raw/versioned DTO: `KEEP_AS_SERIALIZATION`; op classification: `LEGACY_TEST_ONLY` then `DELETE_LATER` after consumers move |
+| `Validation/FirmamentSchemaValidator`, required-field validators, target/coherence/PMI validators | V1 engineering validation and selector/reference semantics | semantics | `FirmamentCompiler` | `LEGACY_TEST_ONLY`; retain compatibility validation only to the degree needed to read/migrate safely |
+| `Mapping/FirmamentCompiledSchemaMapper.cs`, `CompiledModel/FirmamentCompiledSchema.cs` | V1 process/schema lowering | semantics | `FirmamentCompiler`, DFM validators | `MIGRATE_TO_V2_CONSUMER` only where a V2 concept already exists; otherwise freeze/delete later |
+| `Lowering/FirmamentPrimitiveLowerer.cs`, lowering plan | converts `op` records to executable primitives/booleans/features | semantics | `FirmamentCompiler`; selected V2 primitive bridge feeds the same executor but not this V1 lowerer | `LEGACY_TEST_ONLY`; do not move into serialization |
+| `Execution/FirmamentPrimitiveExecutor.cs` | primitive, Boolean, pattern, chamfer/fillet/draft execution | semantics | V1 compiler and V2 primitive bridge; direct Boolean facade consumer | shared executor portions require separate audit; V1 orchestration `MIGRATE_TO_V2_CONSUMER`/freeze, not serialization |
+| `Execution/FirmamentSelectorResolver`, placement resolver/anchor semantics | selector and placement execution | semantics | V1 executor/tests | `LEGACY_TEST_ONLY`; never infer V2 semantic references from it |
+| `Execution/FirmamentValidationExecutor.cs` | executes V1 `expect_*` operations | semantics/regression language | `FirmamentCompiler` | `LEGACY_TEST_ONLY`, then `DELETE_LATER` after equivalent current tests exist |
+| `FirmamentFormatter` + `Formatting/*` | deterministic canonical TOON writer from normalized model | codec, but canonicalizes rather than preserves | formatter/example tests only | `KEEP_AS_COMPATIBILITY_WRITER`; name it V1 TOON explicitly |
+| `FirmamentStepExporter` | compiles V1 and exports selected executed BRep | legacy execution bridge | `FirmamentBuildAndExport` fallback; tests | `KEEP_AS_COMPATIBILITY_READER/EXEC_BRIDGE` temporarily; remove from ordinary V2 routing only after an explicit legacy command/API exists |
+| `FirmamentCompiler` | full V1 parse -> validate -> lower -> execute -> validation pipeline | legacy authoring/execution | V1 tests, `FirmamentStepExporter`, two FrictionLab tests, AirChamfer legacy tests | `DEPRECATE` as public authoring compiler; retain compatibility facade during M2-M5 |
+| `FirmamentFrontendTraceProbe.ParseOnly` and box trace bridge | parser-backed historical fixture evidence | compatibility/test evidence | CLI trace and fixture tracing | `LEGACY_TEST_ONLY`; V2-only probe remains current |
+| `Connectors/FirmamentPartLibraryConnector.cs` | standard-library part lookup used by legacy `library_part` op | shared primitive behind legacy syntax | V1 execution | connector behavior may be `KEEP_AS_SHARED_PRIMITIVE`; V1 op binding is legacy |
+
+## Execution chain and live dependencies
+
+The exact V1 chain is:
+
+```text
+FirmamentCompiler.Compile
+ -> FirmamentTopLevelParser.Parse
+ -> schema / required-field / target / coherence / PMI validators
+ -> FirmamentCompiledSchemaMapper.Map
+ -> FirmamentPrimitiveLowerer.Lower
+ -> FirmamentPrimitiveExecutor.Execute
+ -> schema DFM + enclosed-void validation
+ -> FirmamentValidationExecutor.Execute (`expect_*`)
+```
+
+Production-relevant dependencies are:
+
+| Entry | Dependency | Classification | Migration note |
+|---|---|---|---|
+| `FirmamentBuildAndExport.ExportSource` | if V2 returns `NotRecognized`, calls `FirmamentStepExporter.Export`, which creates `FirmamentCompiler` | live legacy build compatibility | This is the hidden V1 execution dependency. A real CLI build of `testdata/firmament/examples/box_basic.firmament` succeeded during M1. Keep until M2 names an explicit compatibility route. |
+| `FirmamentPrimitiveExecutor` | invoked by both V1 compiler and `FirmamentV2BuildLowering.LowerPrimitiveBridge` | shared execution implementation | Do not delete wholesale with V1. Separate request/model ownership before moving it. |
+| CLI `build`, `view`, `verify`, and consumers of `FirmamentBuildAndExport` | inherit fallback behavior | compatibility surface | CLI `validate` and `inspect` are V2-only and reject V1; behavior is already asymmetric and must be documented. |
+| `ForgeHost` | calls `FirmamentBuildAndExport.CompileSource` | indirect compatibility exposure | Expanded Forge source is expected V2, but unrecognized input can reach V1 fallback; close or explicitly retain this in M2. |
+| Cadmata fixture service/server build path | calls `FirmamentBuildAndExport.Run` | indirect compatibility exposure | Preserve behavior during M2, then decide whether server accepts legacy input explicitly. |
+| `FirmamentFrontendTraceProbe` / CLI trace | V1 parser-backed fixture support | historical regression/educational | Keep in a named legacy fixture lane. |
+
+`FirmamentCompiler` has no ordinary production caller other than `FirmamentStepExporter`; direct constructor calls are in tests/FrictionLab. That makes the exporter fallback the compatibility choke point.
+
+## Syntax versus engineering semantics
+
+Retain as serialization concerns:
+
+- format identity and declared version;
+- top-level section/shape validation;
+- deterministic ordering/writing;
+- raw values needed for round-trip and provenance;
+- stable authored IDs as data;
+- unknown-data preservation policy (currently unknown sections are rejected, not preserved);
+- source-format and source-location provenance.
+
+Freeze outside serialization:
+
+- the supported `op` catalog and `FirmamentOpFamily`;
+- required engineering fields and selector contracts;
+- implicit sequential feature/reference ordering;
+- placement interpretation;
+- schema DFM enforcement;
+- automatic PMI meaning;
+- lowering, BRep execution, and `expect_*` execution.
+
+## Round-trip audit
+
+| Route | Status | Evidence and loss |
+|---|---|---|
+| V1 TOON -> model -> V1 TOON | **semantically stable, textually lossy** | `FirmamentFormatter` parses and emits deterministic TOON. It normalizes whitespace, field ordering, number formatting, nesting, and comments; comments are not modeled. |
+| V1 JSON -> model -> V1 JSON | **unsupported** | No JSON writer exists. The only writer emits TOON. |
+| V1 JSON -> model -> V1 TOON | **potentially semantically stable for accepted bounded documents, textually lossy** | Both parse paths converge, but JSON representation/order/type distinctions are reduced to raw strings and canonical TOON value parsing. Compatibility tests, not assumption, must define the safe subset. |
+
+No writer should claim losslessness until raw unknown fields, comments, quoting, numeric representation, and source order have an explicit preservation contract.
+
+## Fixtures and tests
+
+Content search found 333 repository files with a V1 `firmament:` root across `testdata/firmament`, the older FrictionLab case corpus, and one parser-backed `fixtures/Firmament` fixture. No committed JSON-shaped V1 source fixture was found by the same structural search; JSON coverage lives mainly as inline test strings.
+
+| Group | Classification | Future treatment |
+|---|---|---|
+| parser/shape, formatter, JSON acceptance tests (`FirmamentScaffoldTests`, `FirmamentFormatterTests`) | compatibility contract | retain under explicitly named V1 codec tests; add cross-codec model equivalence cases |
+| validator/selector/placement/schema/PMI tests | historical regression plus legacy behavior contract | keep opt-in; promote only current V2 concepts into V2 tests |
+| primitive/Boolean/lowering/execution/STEP tests | historical regression and educational examples | keep until caller migration; preserve topology lessons in Core/recipe tests |
+| `expect_*` tests | legacy regression language | keep opt-in, then retire after equivalent test assertions exist outside source syntax |
+| `testdata/firmament/examples` | compatibility artifacts | freeze; do not advertise as current authoring examples |
+| `testdata/firmament/fixtures` | broad historical regression corpus | freeze and label V1; no new feature syntax |
+| `Aetheris.Firmament.FrictionLab/Cases/*/part.firmament` | FrictionLab-only historical inputs | freeze; do not treat as product language direction |
+| placement-lab `*.toon` files | candidate experiment syntax, not the V1 document grammar | FrictionLab-only; do not fold into V1 serialization identity |
+
+The project file already excludes the broad V1 test set unless `AETHERIS_RUN_LEGACY_TESTS=1`; this is strong repository evidence that V1 is frozen compatibility/regression rather than the active language.
+
+## Proposed format identity and ownership
+
+- `FirmamentV1ToonDocument`: reader + deterministic compatibility writer over a versioned V1 DTO.
+- `FirmamentV1JsonDocument`: reader over the same versioned V1 DTO; writer only if Preview compatibility later proves it is required.
+- suggested placement for M2: `Aetheris.Kernel.Firmament.Serialization.V1` initially, avoiding an assembly move; a later package split can follow usage evidence.
+- semantic migration target: an explicit result such as `LegacyFirmamentImportResult` containing source format/version, normalized legacy document, diagnostics, provenance, and optional V2-safe data. It must never manufacture Concepts, Templates, Modules, Interfaces, Mates, or semantic feature meaning.
+
+## Unsafe migration fields
+
+Do not infer current meaning from:
+
+- sequential `ops` order and `from`/`to`/`with` references;
+- V1 selector strings or port contracts;
+- origin/selector/around-axis placement shortcuts;
+- schema process fields and their historical enforcement behavior;
+- `expect_*` operations (tests, not product intent);
+- automatically derived PMI or legacy target strings;
+- operation IDs that were stable only within one flat V1 execution document.
+
+These may be preserved verbatim or imported as legacy evidence. A migration may produce V2 only where the old record contains enough explicit information and the mapping is exact.
diff --git a/docs/architecture/artifacts/archaeology-m1/legacy-firmasm-map.md b/docs/architecture/artifacts/archaeology-m1/legacy-firmasm-map.md
new file mode 100644
index 00000000..5f1424a0
--- /dev/null
+++ b/docs/architecture/artifacts/archaeology-m1/legacy-firmasm-map.md
@@ -0,0 +1,110 @@
+# Legacy JSON `.firmasm` map
+
+## Identity boundary
+
+| Identity | Syntax/model | Status |
+|---|---|---|
+| current `.firmasm` | Firmament V2 Assembly document profile; ordinary V2/Assembly declarations and exactly one exported/root `Assembly` | current, canonical authoring/interchange profile |
+| `LegacyFirmasmJson` | JSON object with `manifest`, `assembly`, `parts`, `instances`; transform-first flat occurrence model | deprecated compatibility/serialization input |
+
+The extension is not deprecated. Only the historical JSON-shaped syntax is deprecated.
+
+## Current implementation graph
+
+```text
+legacy JSON file
+ -> FirmasmManifestLoader.Parse -> FirmasmManifest
+ -> LoadFromFile
+ -> resolve part paths
+ -> Firmament part reference: path wrapper only
+ -> STEP part: Step242Importer.ImportBody
+ -> FirmasmLoadedAssembly
+
+Compatibility route A (current assembly tooling):
+ FirmamentAssemblyDocumentCompiler
+ -> LegacyFirmasmMigration.GenerateCurrentSource
+ -> temporary current .firmasm source with Placement LegacyExplicit
+ -> AssemblyM1Pipeline -> AssemblyIR / geometry
+
+Compatibility route B (old direct CLI):
+ aetheris asm exec
+ -> FirmasmAssemblyExecutor
+ -> STEP-only instances, rigid transforms, composed multi-shell body
+
+Compatibility route C (old outbound package):
+ aetheris asm export
+ -> FirmasmAssemblyRoundtripExporter
+ -> per-instance STEP + roundtrip.package.json
+```
+
+## Component inventory
+
+| Component | Role | Future disposition |
+|---|---|---|
+| `FirmasmManifestContracts.cs` | legacy normalized schema/DTO | `KEEP_AS_SERIALIZATION` |
+| `FirmasmManifestLoader.Parse` | strict JSON schema/version/field parser | `KEEP_AS_COMPATIBILITY_READER` |
+| `FirmasmManifestLoader.LoadFromFile` | path resolution, STEP import, Firmament reference loading | reader plus import bridge; split I/O from codec in M2 |
+| `LegacyFirmasmMigration.GenerateCurrentSource` | deterministic compatibility migration into current Assembly source | `KEEP_AS_COMPATIBILITY_READER`; preserve `LegacyExplicit` authority |
+| `FirmamentAssemblyDocumentCompiler` JSON detection | current `.firmasm` profile dispatcher | retain; replace shape sniffing with named format detection in M2 |
+| `FirmasmAssemblyExecutor` | direct legacy transform-first STEP occurrence execution | `DEPRECATE`, but retain for Preview 3 compatibility |
+| `FirmasmAssemblyRoundtripExporter` | outbound per-instance STEP package | compatibility exporter, not same-format writer; freeze |
+| `AssemblyM2Interop` / `Step242FirmasmPackageImporter` | imports AP242 assembly into current V2 `.firmasm` package | current V2/interchange producer; not legacy JSON |
+
+## Schema and data limits
+
+The JSON schema contains:
+
+- `manifest.version`;
+- `assembly.name` and `assembly.units`;
+- named parts with `kind` (`firmament` or `step`) and relative `source`;
+- flat instances with `id`, part reference, translation, and optional XYZ Euler rotation.
+
+It contains no Interface, Role, Mate, hierarchy semantics, constraint intent, tolerance stack, semantic occurrence relationship, or authored reason for a transform. Migration correctly emits `Placement LegacyExplicit`; it must not infer Mates or mark imported transforms as `MateDerived`.
+
+Direct `FirmasmAssemblyExecutor` supports only loaded STEP parts. A `Firmament` part reference can be loaded by the manifest loader but is rejected by the direct executor. The current migration/Assembly pipeline is therefore the more capable compatibility path.
+
+## Live callers
+
+| Caller | Path | Requirement |
+|---|---|---|
+| CLI `asm inspect` | `.firmasm` -> `FirmamentAssemblyDocumentCompiler`; JSON is migrated | **must retain read + migration** |
+| server `AssemblyDisplayService` | same compiler/profile route | **must retain read + migration** |
+| CLI `asm export-ap242` | same compiler/profile route then `AssemblyIrAp242Exporter` | **must retain export through current AssemblyIR** |
+| CLI `asm exec` | direct legacy loader/executor | **could freeze/deprecate**, retain for Preview 3 |
+| CLI `asm export` | direct executor then per-instance STEP package | **could freeze/deprecate**, retain for Preview 3 |
+| tests under `Assembly/Firmasm*` and CLI assembly tests | loader, migration, authority, direct execution/export | compatibility contract |
+
+M1 CLI evidence: `asm inspect` migrated the OCCT AS1 JSON fixture to AssemblyIR with part placements marked `LegacyExplicit`; `asm exec` produced 18 bodies and the expected deprecation warning.
+
+## Round-trip status
+
+| Route | Status | Notes |
+|---|---|---|
+| legacy JSON -> `FirmasmManifest` -> legacy JSON | **unsupported** | No manifest JSON writer exists. |
+| legacy JSON -> current V2 `.firmasm` | **lossy but intentionally safe** | Parts, flat instance IDs, references, and transforms are represented; comments/order/JSON representation and manifest version are not round-tripped. Missing semantic intent stays missing. |
+| legacy JSON -> executed BRep -> per-instance STEP package | **geometry/interchange stable for admitted STEP subset, not format round-trip** | Output is STEP plus package JSON, not the input format. |
+| current V2 `.firmasm` -> AP242 -> current package | bounded current interchange | Owned by Assembly M2/M3, separate from legacy JSON serialization. |
+
+## Conflated locations and corrections
+
+| Location | Issue | Disposition |
+|---|---|---|
+| `docs/firmament-v2/language-reference.md` former “`.firmasm` is a Legacy compatibility format” sentence | contradicted the same page and implementation | corrected in M1 to distinguish current profile from legacy JSON syntax |
+| `FirmasmAssemblyRoundtripExporter` package field `nativeAuthority = ".firmasm"` | ambiguous when input is legacy JSON | update in M2 to a named legacy format identity or current AssemblyIR authority |
+| CLI command names `asm exec` / `asm export` | accept only the legacy JSON direct path despite general `.firmasm` wording | document/deprecate or rename as legacy in M2; keep aliases for compatibility |
+| `testdata/firmasm` READMEs call JSON manifests `.firmasm` contracts without consistently saying legacy | historical ambiguity | update labels in M2; retain fixtures |
+| historical assembly artifact docs | correctly record transform-first limitations but sometimes predate current profile | retain as historical and add context, do not rewrite history |
+
+## Proposed M2 ownership
+
+Use `Aetheris.Kernel.Firmament.Serialization.LegacyFirmasm` (initially in the existing assembly) with:
+
+- explicit `LegacyFirmasmJson` detection and version validation;
+- parse-only DTO separated from part I/O;
+- deterministic migration result carrying original IDs, paths, transforms, and provenance;
+- no new authoring fields;
+- no inference of Interfaces/Mates;
+- read support and the existing current-V2 migration route as the primary compatibility implementation;
+- direct executor/exporter retained behind a clearly legacy facade until Preview 3 removal policy is decided.
+
+Same-format write support is not currently required by a production caller. Do not build it in M2 unless a Preview 3 compatibility contract is found outside this repository.
diff --git a/docs/architecture/artifacts/archaeology-m1/migration-plan.md b/docs/architecture/artifacts/archaeology-m1/migration-plan.md
new file mode 100644
index 00000000..9c45c2f9
--- /dev/null
+++ b/docs/architecture/artifacts/archaeology-m1/migration-plan.md
@@ -0,0 +1,122 @@
+# Phased migration, freeze, tests, and documentation plan
+
+## Freeze policy effective after M1
+
+Allowed:
+
+- fixes for regressions in already-supported bounded families;
+- diagnostics, validation, and tests that make existing bounds explicit;
+- extraction work required by M2-M5 with parity evidence;
+- new product geometry through V2 Template/construction primitive/recognized recipe, using Surgery where necessary;
+- a new central-dispatch case only when it is an unavoidable bounded migration bridge or critical compatibility regression, documented with an owner and removal plan.
+
+Not allowed:
+
+- adding a surface/tool family to `BrepBoolean` merely to make the generic API appear broader;
+- treating numerical intersection as topology authority;
+- new V1 Concepts/Templates/Modules/authoring features;
+- new transform-first legacy `.firmasm` semantics;
+- arbitrary topology surgery in `Forge.Host`.
+
+Working families, fixtures, and tests remain supported during migration.
+
+## M2 - serialization boundary (first implementation milestone)
+
+| Item | Plan |
+|---|---|
+| goal | remove format/language ambiguity with no geometry change |
+| scope | name `FirmamentV1Toon`, `FirmamentV1Json`, `LegacyFirmasmJson`; split parse DTO/codecs from V1 semantics/I/O; add explicit compatibility route and diagnostics; document CLI asymmetry |
+| movement | initially namespaces/facades inside `Aetheris.Kernel.Firmament`; no assembly move. `FirmamentTopLevelParser` codec portions and `FirmasmManifestLoader.Parse` become explicitly versioned readers. Keep old public facades as adapters. |
+| compatibility | preserve V1 build fallback, legacy JSON `.firmasm` inspect/display/export, and current V2 `.firmasm`; make Forge/server legacy admission explicit rather than accidental |
+| risk | low/medium: format detection and diagnostics can change routing; protect with fixture hashes/model equivalence |
+| rollback | old compiler/loader remain behind adapters; switch routing back without data migration |
+| success evidence | V1 TOON/JSON normalized-model tests; deterministic TOON write; legacy JSON migration authority; V2 `.firmasm` unchanged; CLI compatibility matrix |
+
+M2 should not build a same-format legacy `.firmasm` writer unless an external Preview 3 requirement is proven. It should first isolate live execution dependencies.
+
+## M3 - Surgery substrate extraction
+
+| Item | Plan |
+|---|---|
+| goal | extract repeated explicit topology mechanics without changing recipe policy |
+| scope | oriented loop/face construction, deterministic ID/binding remap, known ring/section scaffolds, shell assembly, validation bundle |
+| movement | private repeated mechanics from Boolean builders and existing Firmament stitching/remap helpers into internal `Aetheris.Kernel.Core.Brep.Surgery` |
+| compatibility | `BrepBoolean` signatures, routing, `SafeBooleanComposition`, outputs and diagnostics remain stable |
+| risk | medium: orientation, IDs, and STEP ordering are sensitive |
+| rollback | each builder can retain or restore its old private helper; extract one primitive at a time |
+| success evidence | topology counts, binding/manifold validation, deterministic STEP/hash where contractual, and legacy Boolean suites green |
+
+## M4 - representative recipe migration
+
+| Item | Plan |
+|---|---|
+| goal | prove policy/recipe/Surgery separation on representative families |
+| scope | through hole first; then polygonal through cut or orthogonal union; preserve facade adapters |
+| movement | recognition/history inputs become explicit recipe requests; recipe calls Surgery; old builders become adapters/worked examples until parity is established |
+| compatibility | no family removal and no generic expansion |
+| risk | medium: provenance/diagnostic parity and hidden composition metadata |
+| rollback | per-family dispatcher switch returns to old builder |
+| success evidence | old/new differential tests across canonical, tolerance-boundary, invalid, and STEP reimport cases |
+
+Add architecture comments at migrated recipe entry points and publish the two kernel teaching docs in this phase.
+
+## M5 - production caller migration and advanced boundary
+
+| Item | Plan |
+|---|---|
+| goal | stop known construction paths from pretending to be generic user Booleans |
+| scope | `ThroughHoleRecoveryExecutor`, `HoleRecoveryExecutor`, StandardLibrary, recognized CIR materialization, then V2 primitive bridge; classify server endpoint |
+| movement | callers invoke recipes; `FirmamentPrimitiveExecutor` retains a compatibility facade only for V1/generic legacy ops. Evaluate proven safe advanced Surgery surface for `Forge.KernelSDK`; unsafe operations require explicit unsafe tier. |
+| compatibility | current artifacts and APIs retained through adapters; server reports bounded capability/rejection honestly |
+| risk | medium/high for stepped/counterbore history; high for external server API semantics |
+| rollback | caller-by-caller feature switches/adapters; no schema/data migration |
+| success evidence | caller-specific integration suites, Forge Host/KernelSDK boundary tests, V2 build artifacts, server rejection contracts |
+
+## M6 - compatibility cleanup
+
+| Item | Plan |
+|---|---|
+| goal | retire obsolete execution surfaces only after telemetry/repository usage is gone |
+| scope | deprecate/remove accidental V1 fallback from ordinary V2 paths, old direct legacy `.firmasm` exec/export aliases if Preview permits, obsolete dispatcher routes/helpers, stale docs |
+| movement | legacy codecs remain versioned compatibility package/namespace; representative regressions move to compatibility and recipe education suites |
+| compatibility | announce removals; preserve readers longer than executors/writers; never reinterpret old data |
+| risk | high if external consumers depend on generic APIs; requires release decision |
+| rollback | compatibility package/facade can be restored independently; canonical V2 artifacts unaffected |
+| success evidence | full active + compatibility suites, package/API diff, documented deprecation window, no unclassified callers |
+
+## Test classification and preservation
+
+| Test/docs group | Classification | Destination |
+|---|---|---|
+| V1 parser/formatter and legacy `.firmasm` loader/migration | compatibility contract | M2 serialization compatibility suite |
+| V1 validator/executor/`expect` | historical regression / legacy behavior contract | opt-in legacy suite; promote only current behavior |
+| Core Boolean happy-path families | behavior contract | recipe parity tests |
+| stepped root cause, continuation graph, overlap/tangency, rotated/conic, mixed continuation | historical regression + educational example | preserve permanently; reorganize under recipe/Surgery lessons |
+| generic CIR and strategy labs | educational experimental evidence | FrictionLab, linked from textbook docs |
+| exact diagnostics tied only to obsolete private implementation | obsolete implementation detail | remove only when equivalent invariant/rejection assertion exists |
+| `docs/boolean-deferred.md` and milestone notes | historical record | retain; add forward links/context rather than rewriting outcomes |
+
+## Documentation cleanup map
+
+| Documents | Classification/action |
+|---|---|
+| `docs/firmament-v2/language-reference.md` | canonical/current; conflicting `.firmasm` sentence corrected in M1 |
+| `Aetheris.Kernel.Firmament/README.md` | severely stale pre-M0 scaffold claim; update in M1 |
+| `docs/firmament-overview.md`, `firmament-language-shape.md`, `firmament-build-workflow.md`, `firmament-demo.md`, `firmament-author-rules.md`, `firmament-selectors.md`, `firmament-placement-semantics.md` | historical V1 docs that often say “current” or “canonical”; add a shared historical banner in M2, retain content for compatibility |
+| `docs/air-firmament-a1-firmament-fixture-corpus.md` | directionally correct but says V1 remains valid; update wording to explicit compatibility/serialization destination in M2 |
+| `docs/build-test-policy-net10-and-legacy-v1.md` | current and consistent; retain |
+| `docs/assembly/artifacts/m0/*`, assembly milestone docs | retain historical; link to current profile distinction |
+| `testdata/firmasm/*/README.md` | update to say legacy JSON compatibility fixture |
+| `docs/boolean-deferred.md` | current truthful scope statement; retain and link to freeze policy |
+| stepped/CIR recovery/FrictionLab Boolean docs | retain historical/educational, including failures and later fixes |
+
+## Rollback doctrine shared by every phase
+
+Each phase must:
+
+- keep `dotnet restore Aetheris.slnx` and `dotnet build Aetheris.slnx -f net10.0 --no-restore /m:1` green;
+- run active tests plus the relevant explicitly enabled legacy suite;
+- compare existing canonical artifacts where byte stability is contractual and topology/semantic equivalence otherwise;
+- preserve old facade/adapters until the new path proves parity;
+- avoid combining namespace/package movement with behavior expansion;
+- end with an independently revertible commit boundary.
diff --git a/docs/architecture/artifacts/archaeology-m1/surgery-candidates.md b/docs/architecture/artifacts/archaeology-m1/surgery-candidates.md
new file mode 100644
index 00000000..d8ad7145
--- /dev/null
+++ b/docs/architecture/artifacts/archaeology-m1/surgery-candidates.md
@@ -0,0 +1,63 @@
+# BRep Surgery candidate surface
+
+## Proposed boundary
+
+Initial internal namespace:
+
+```text
+Aetheris.Kernel.Core.Brep.Surgery
+```
+
+M3 should keep it internal. Only after recipe migrations prove contracts should selected operations be surfaced through `Aetheris.Forge.KernelSDK`. Ordinary `Aetheris.Forge.Host` must not gain arbitrary topology editing.
+
+## Bounded candidate operations
+
+These candidates are based on repeated code in current builders, not a speculative complete modeling API.
+
+| Candidate | Existing pressure | Contract |
+|---|---|---|
+| `AddOrientedLoop` / `AddFaceWithLoops` | duplicated coedge allocation/linking in hole, slot, prism, and orthogonal builders | consume ordered edge uses; create cyclic next/previous coedges and a loop; no feature recognition |
+| `TopologyAssemblyBuilder` extension over `TopologyBuilder` | every recipe separately assembles faces -> shell -> body | explicit IDs in, explicit shell/body out; caller chooses topology |
+| indexed vertex/edge reuse for known boundary graphs | orthogonal union and polygonal extrusion builders maintain lookup maps | deterministic reuse by caller-provided geometric key; no tolerance-based topology inference |
+| known ring/section extrusion scaffold | polygonal through-cut and profile/section emitters construct corresponding lower/upper rings and side faces | caller supplies correspondence, orientation, and expected inner/outer roles |
+| insert a known inner trim loop on a known face | through-hole/prism recipes build outer plus reversed inner loops | explicit target face/loop and trim curve; no intersection search |
+| append known analytic curve/surface bindings | hole/slot builders repeatedly create circle/line and plane/cylinder/cone/sphere bindings | geometry and parameter domains are caller-provided; validate binding completeness |
+| deterministic topology/geometry/binding remap | mixed-void and assembly transformation paths copy/remap IDs | preserve maps and provenance; reject collisions/dangling references |
+| explicit shell assembly/stitch from known paired edges | Firmament `SurfaceFamilyShellAssembler`, `SurfaceFamilyStitchExecutor`, combined-body remapper, and Boolean mixed builders | caller supplies pairing/evidence; Surgery performs mutation and reports structural failures |
+| validation bundle | all builders call `BrepBindingValidator`; several paths separately check manifold/export properties | binding, loop closure, shell connectivity/orientation, manifoldness, and optional provenance checks |
+
+## Not Surgery
+
+The layer must not answer:
+
+- whether operands represent a through hole, counterbore, keyway, sphere cavity, or union;
+- which entry/exit faces a numerical intersection implies;
+- whether a continuation is semantically allowed;
+- what result topology subtraction should have;
+- whether one recognized family should beat another;
+- how to infer intent from imported or legacy geometry.
+
+Those decisions remain in construction recipes, recognizers, and Judgment-backed policy.
+
+## Safe, unsafe, and internal API placement
+
+| Tier | Candidate exposure | Examples |
+|---|---|---|
+| safe advanced (`KernelSDK`, later) | bounded constructors with complete inputs and mandatory validation | create a closed ring extrusion; add a validated inner loop; deterministic remap with complete correspondence |
+| explicit unsafe (`KernelSDK` only with unsafe consent) | partial topology replacement where caller owns invariants | replace loops/faces, stitch caller-selected shells, preserve imported residual topology |
+| internal-only | raw ID allocation, unchecked topology mutation, binding-store mutation, bypassing validation | `TopologyModel.Add*`, arbitrary coedge rewiring, unchecked face/shell deletion |
+
+`KernelSdk` currently exposes only a signed-side query. That small surface is useful evidence: M3 should not broaden public APIs while contracts are still being extracted. Forge already has an unsafe-consent concept; M5/M6 can decide whether surgery participates in that permission model.
+
+## Geometry query separation
+
+Keep `SignedSideQuery`, `ClosestPointQuery`, `IntersectionQuery`, and `ContactQuery` in geometry/query ownership. A recipe may use their results as predicates or evidence. Surgery accepts the caller's explicit trims/topology plan and does not convert arbitrary intersection curves into semantic topology.
+
+## M3 acceptance test
+
+Extract only enough mechanics for two representative paths:
+
+1. polygonal prism through-cut or standard cube-through-hole, proving loop/face/binding mechanics; and
+2. one mixed/remap path, proving ID/binding preservation.
+
+The existing `BrepBoolean` facade must produce byte/topology-equivalent canonical artifacts before and after extraction. If an abstraction needs family names in its inputs, it belongs in the recipe layer, not Surgery.
diff --git a/docs/architecture/artifacts/archaeology-m1/validation-report.md b/docs/architecture/artifacts/archaeology-m1/validation-report.md
new file mode 100644
index 00000000..a9ad5c2e
--- /dev/null
+++ b/docs/architecture/artifacts/archaeology-m1/validation-report.md
@@ -0,0 +1,42 @@
+# M1 validation report
+
+This report records the final M1 validation. The architecture work is documentation-first. Two narrow fixes discovered during validation were also made: canonical V1 formatting no longer mixes platform newlines, and legacy build tests now assert the intentional adjacent default output path.
+
+## Ground-truth CLI inspection
+
+| Command | Result |
+|---|---|
+| `dotnet run --project Aetheris.CLI -- --help` | passed; confirms current command surface |
+| `dotnet run --project Aetheris.CLI -- asm --help` | passed; explicitly states current `.firmasm` is the V2 Assembly profile and only JSON syntax is legacy |
+| `aetheris validate` on V1 TOON fixture | rejected by V2-only validation, proving CLI validation no longer provides V1 validation compatibility |
+| `aetheris inspect` on V1 example | rejected by V2-only inspection |
+| `aetheris build` on V1 `box_basic.firmament` | passed and emitted STEP, proving live V1 compiler/executor fallback |
+| `aetheris asm inspect` on legacy OCCT AS1 JSON `.firmasm` | passed through migration; AssemblyIR part placements reported `LegacyExplicit` |
+| `aetheris asm exec` on the same fixture | passed; 5 parts, 18 instances/bodies, deprecation warning |
+
+The generated `.tmp/archaeology-v1-box.step` is an untracked temporary validation artifact ignored by Git; it is not part of this milestone.
+
+## Build and tests
+
+| Validation | Result |
+|---|---|
+| `dotnet restore Aetheris.slnx` | passed; all projects up to date |
+| `dotnet build Aetheris.slnx -f net10.0 --no-restore /m:1` | passed; 0 warnings, 0 errors |
+| active Core, Firmament, CLI, Semantics, Forge Host, Server, and Modules tests | 2,526 passed, 0 failed |
+| full opt-in Firmament legacy suite (`AETHERIS_RUN_LEGACY_TESTS=1`) | 1,731 passed, 0 failed |
+| focused Boolean/stepped-hole FrictionLab set | 40 passed, 0 failed |
+| full opt-in FrictionLab suite | 394 passed, 5 failed |
+
+The five full-FrictionsLab failures are all methods of `TriangleHexPrismProfileParityLabTests`. They share the same pre-existing failure: `ProfileExtrusionBRepPlanner.TryPlan` constructs a `ParameterInterval` with a non-finite end at `ProfileExtrusionBRepPlan.cs:128`. This is unrelated to V1 serialization or bounded Boolean archaeology and was not patched as part of M1. The focused Boolean audit set is green.
+
+Before the narrow fixes, the full Firmament legacy suite reported 76 failures: platform-mixed formatter newlines and tests that still expected the retired `testdata/firmament/exports` default. After making LF output explicit and aligning those tests/docs with `ResolveDefaultOutputPath`, the same suite passes 1,731/1,731.
+
+## Changed files
+
+- architecture artifact set under this directory;
+- `docs/firmament-v2/language-reference.md` (one contradictory profile statement corrected);
+- `Aetheris.Kernel.Firmament/README.md` (stale pre-M0 scaffold description replaced with current ownership summary);
+- `FirmamentCanonicalFormatter` (blank lines use explicit LF, matching the existing canonical contract);
+- `FirmamentBuildAndExportTests` and `docs/cli-baseline.md` (default output expectations aligned with the implemented adjacent-source contract).
+
+No schema, fixture, geometry, topology, parser, lowering, executor, API, or Boolean runtime behavior was changed.
diff --git a/docs/cli-baseline.md b/docs/cli-baseline.md
index bad58ff4..0c42a79e 100644
--- a/docs/cli-baseline.md
+++ b/docs/cli-baseline.md
@@ -10,7 +10,7 @@ aetheris analyze <file.step> [--face <id>] [--edge <id>] [--vertex <id>] [--json
## Contract notes
- `build` runs `FirmamentBuildAndExport.Run`; no parallel compile/export path is introduced.
-- `build` default output path remains deterministic: `<repo>/testdata/firmament/exports/<source-filename>.step`.
+- `build` default output path is deterministic and adjacent to the source: `<source-directory>/<source-filename>.step`. Use `--out` to place it elsewhere.
- `analyze` imports STEP with `Step242Importer.ImportBody` and reports imported topology/geometry facts.
- At most one detail selector is allowed on `analyze`: `--face`, `--edge`, or `--vertex`.
- `analyze --json` is the canonical machine-readable mode.
diff --git a/docs/firmament-v2/language-reference.md b/docs/firmament-v2/language-reference.md
index f60aae1d..0c04668b 100644
--- a/docs/firmament-v2/language-reference.md
+++ b/docs/firmament-v2/language-reference.md
@@ -21,7 +21,7 @@ There are two current frontend lanes:
1. the canonical `Model { Units: mm ... }` V2 parser/binder; and
2. the supported Assembly relational parser for `Interface` plus `Assembly` source. M1 lets its Part tags apply declarations from the adjacent canonical V2 definition catalog.
-This split is implementation structure, not two languages. `.firmasm` is a Legacy compatibility format and is not Firmament V2 architecture.
+This split is implementation structure, not two languages. Current `.firmasm` is the Firmament V2 Assembly profile. Only the historical JSON-shaped `.firmasm` syntax is a legacy compatibility format; it is migrated into this current profile and does not define V2 architecture.
## Lexical structure