Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Add Firmament V2 with derivation doctrine

Yuechen Li97dd18e86e0a
diff --git a/Aetheris.CLI.Tests/FirmamentFixtureCorpusTests.cs b/Aetheris.CLI.Tests/FirmamentFixtureCorpusTests.cs
index 827e09dc..631bed5b 100644
--- a/Aetheris.CLI.Tests/FirmamentFixtureCorpusTests.cs
+++ b/Aetheris.CLI.Tests/FirmamentFixtureCorpusTests.cs
@@ -8,6 +8,7 @@ public sealed class FirmamentFixtureCorpusTests
private static readonly string V2CorpusRoot = Path.GetFullPath(Path.Combine(AppContext.BaseDirectory, "../../../../fixtures/FirmamentV2"));
private static readonly string V2DoctrinePath = Path.GetFullPath(Path.Combine(AppContext.BaseDirectory, "../../../../docs/air-firmament-a2-firmament-v2-source-language-design.md"));
private static readonly string V21DoctrinePath = Path.GetFullPath(Path.Combine(AppContext.BaseDirectory, "../../../../docs/air-firmament-a2-1-semantic-references-admissibility-surface-doctrine.md"));
+ private static readonly string V22DoctrinePath = Path.GetFullPath(Path.Combine(AppContext.BaseDirectory, "../../../../docs/air-firmament-a2-2-record-derivation-with.md"));
private static readonly string[] RequiredMetadata = ["fixture-id", "case", "category", "validity", "implementation", "expected", "expected-stage"];
[Fact]
@@ -110,6 +111,12 @@ public sealed class FirmamentFixtureCorpusTests
Assert.Contains(fixtures, p => p.EndsWith("Surface/future/ruled-surface-rails-v2.valid.firmfixture", StringComparison.Ordinal));
Assert.Contains(fixtures, p => p.EndsWith("Surface/future/offset-surface-detail-v2.valid.firmfixture", StringComparison.Ordinal));
Assert.Contains(fixtures, p => p.EndsWith("Pattern/future/linear-pattern-v2.valid.firmfixture", StringComparison.Ordinal));
+ Assert.Contains(fixtures, p => p.EndsWith("RecordDerivation/valid/box-with-size-variant-v2.valid.firmfixture", StringComparison.Ordinal));
+ Assert.Contains(fixtures, p => p.EndsWith("RecordDerivation/valid/feature-with-radius-variant-v2.valid.firmfixture", StringComparison.Ordinal));
+ Assert.Contains(fixtures, p => p.EndsWith("RecordDerivation/valid/material-with-property-variant-v2.valid.firmfixture", StringComparison.Ordinal));
+ Assert.Contains(fixtures, p => p.EndsWith("RecordDerivation/invalid/with-degenerate-box-v2.invalid.firmfixture", StringComparison.Ordinal));
+ Assert.Contains(fixtures, p => p.EndsWith("RecordDerivation/invalid/with-selector-target-v2.invalid.firmfixture", StringComparison.Ordinal));
+ Assert.Contains(fixtures, p => p.EndsWith("RecordDerivation/invalid/with-unknown-field-v2.invalid.firmfixture", StringComparison.Ordinal));
foreach (var path in fixtures)
{
@@ -212,6 +219,70 @@ public sealed class FirmamentFixtureCorpusTests
Assert.Contains("not BRep IDs", doc, StringComparison.OrdinalIgnoreCase);
}
+
+ [Fact]
+ public void FirmamentV2RecordDerivation_MetadataRecognized()
+ {
+ var fixtures = DiscoverV2Fixtures().Where(p => p.Contains("/RecordDerivation/", StringComparison.Ordinal)).ToArray();
+ Assert.Equal(6, fixtures.Length);
+ foreach (var path in fixtures)
+ {
+ var fixture = LoadMetadata(path);
+ Assert.Equal("FirmamentV2", fixture["syntax-version"]);
+ Assert.Equal("RecordDerivation", fixture["category"]);
+ Assert.True(fixture.ContainsKey("expected-diagnostic"), path);
+ }
+ }
+
+ [Fact]
+ public void FirmamentV2RecordDerivation_NotV1ParseFailures()
+ {
+ foreach (var path in DiscoverV2Fixtures().Where(p => p.Contains("/RecordDerivation/", StringComparison.Ordinal)))
+ {
+ using var doc = Trace(path);
+ var metadata = LoadMetadata(path);
+ var diagnostics = doc.RootElement.GetProperty("diagnostics").EnumerateArray().Select(x => x.GetString()).ToArray();
+ Assert.False(doc.RootElement.GetProperty("fixture").GetProperty("parserBacked").GetBoolean());
+ Assert.True(doc.RootElement.GetProperty("fixture").GetProperty("expectationSatisfied").GetBoolean(), path);
+ Assert.Equal(metadata["expected-stage"], doc.RootElement.GetProperty("actualStageReached").GetString());
+ Assert.Contains(metadata["expected-diagnostic"], diagnostics);
+ Assert.DoesNotContain("air-x11-firmament-parse-failed", diagnostics);
+ }
+ }
+
+ [Fact]
+ public void FirmamentV2RecordDerivation_InvalidFixtures_ReportExpectedDiagnostics()
+ {
+ var expected = new[]
+ {
+ (Path: "RecordDerivation/invalid/with-degenerate-box-v2.invalid.firmfixture", Diagnostic: "firmament-degenerate-dimension"),
+ (Path: "RecordDerivation/invalid/with-selector-target-v2.invalid.firmfixture", Diagnostic: "firmament-with-requires-record"),
+ (Path: "RecordDerivation/invalid/with-unknown-field-v2.invalid.firmfixture", Diagnostic: "firmament-with-field-not-found")
+ };
+
+ foreach (var item in expected)
+ {
+ using var doc = Trace(Path.Combine(V2CorpusRoot, item.Path));
+ var diagnostics = doc.RootElement.GetProperty("diagnostics").EnumerateArray().Select(x => x.GetString()).ToArray();
+ Assert.True(doc.RootElement.GetProperty("fixture").GetProperty("expectationSatisfied").GetBoolean(), item.Path);
+ Assert.Contains(item.Diagnostic, diagnostics);
+ }
+ }
+
+ [Fact]
+ public void FirmamentV2Doctrine_DocsMentionWithDerivation()
+ {
+ Assert.True(File.Exists(V22DoctrinePath), V22DoctrinePath);
+ var doc = File.ReadAllText(V22DoctrinePath);
+ Assert.Contains("immutable record derivation", doc, StringComparison.OrdinalIgnoreCase);
+ Assert.Contains("not mutation", doc, StringComparison.OrdinalIgnoreCase);
+ Assert.Contains("not topology editing", doc, StringComparison.OrdinalIgnoreCase);
+ Assert.Contains("admissibility", doc, StringComparison.OrdinalIgnoreCase);
+ Assert.Contains("no control flow", doc, StringComparison.OrdinalIgnoreCase);
+ Assert.Contains("nested `with`", doc, StringComparison.OrdinalIgnoreCase);
+ Assert.Contains("=>", doc, StringComparison.Ordinal);
+ }
+
[Fact]
public void FirmamentFixtureCorpus_DoesNotRequireFeatureImplementation()
{
diff --git a/docs/air-a0-aetheris-v2-compiler-ir-constitution.md b/docs/air-a0-aetheris-v2-compiler-ir-constitution.md
index 557d184a..3a795c0f 100644
--- a/docs/air-a0-aetheris-v2-compiler-ir-constitution.md
+++ b/docs/air-a0-aetheris-v2-compiler-ir-constitution.md
@@ -55,6 +55,8 @@ This document is documentation/design only. It does not implement AIR, change pr
Firmament V2 is the canonical human-facing source-language design for this constitution. V2 source is expected to lower through source AST and semantic intent into Feature AIR, then Constructive/Compositional AIR, BRepPlan, BRep, and STEP/artifacts. AIR remains IR, BRep remains the topology/export backend, and CIR remains an optional computational implicit mirror for admitted analysis rather than topology authority. See `docs/air-firmament-a2-firmament-v2-source-language-design.md`.
+Firmament V2 `with` derivation is source-level record derivation resolved during name/record resolution before Feature AIR lowering. It produces revalidated source records and must not become mutation, topology editing, backend patching, CIR topology authority, or STEP/BRep behavior. See `docs/air-firmament-a2-2-record-derivation-with.md`.
+
AIR-A1 extends this constitution with **AIR Regions**: scoped construction islands inside AIR for local-frame features whose effects escape only through explicit yields and route-selected parent integration. The doctrine is that different-axis features such as side holes, side pockets, bosses, pattern elements, and future shell/local offset contexts should be represented as scoped local AIR intent first; Boolean remains only one possible admitted backend integration route, not the default representation. See `docs/air-a1-air-regions-scoped-feature-lowering-audit.md`.
## 2. Compiler analogy
diff --git a/docs/air-firmament-a1-firmament-fixture-corpus.md b/docs/air-firmament-a1-firmament-fixture-corpus.md
index 76dd1e30..63e63aaf 100644
--- a/docs/air-firmament-a1-firmament-fixture-corpus.md
+++ b/docs/air-firmament-a1-firmament-fixture-corpus.md
@@ -153,6 +153,7 @@ fixtures/FirmamentV2/
Admissibility/
Pattern/
Material/
+ RecordDerivation/
Invalid/
```
@@ -161,3 +162,7 @@ Future features should be written in V2 syntax first, marked not implemented/fut
## A2.1 semantic-reference and admissibility fixture expansion
A2.1 expands the `fixtures/FirmamentV2/` metadata-only taxonomy with semantic-reference, admissibility, surface-doctrine, and pattern-as-record pilot fixtures. These fixtures remain `syntax-version: FirmamentV2` and are deliberately classified by metadata rather than by the V1 parser. Valid design examples use `implementation: not-implemented`, `expected-stage: not-implemented`, and `expected-diagnostic: firmament-v2-parser-not-ready`; invalid doctrine examples use `implementation: rejected` with stable diagnostics such as `firmament-raw-backend-id-reference-forbidden`, `firmament-degenerate-dimension`, and `firmament-shell-thickness-collapses-body`.
+
+## A2.2 record-derivation fixture expansion
+
+A2.2 expands the `fixtures/FirmamentV2/` metadata-only taxonomy with `RecordDerivation/` fixtures for valid `with` variants and invalid derivation diagnostics. Valid design examples remain `implementation: not-implemented`, `expected-stage: not-implemented`, and `expected-diagnostic: firmament-v2-parser-not-ready`; invalid doctrine examples use `implementation: rejected` with diagnostics such as `firmament-degenerate-dimension`, `firmament-with-requires-record`, and `firmament-with-field-not-found`. These fixtures are classified by metadata and must not be routed through the V1 parser as incidental parse failures.
diff --git a/docs/air-firmament-a2-1-semantic-references-admissibility-surface-doctrine.md b/docs/air-firmament-a2-1-semantic-references-admissibility-surface-doctrine.md
index 78174d8c..dfbb158f 100644
--- a/docs/air-firmament-a2-1-semantic-references-admissibility-surface-doctrine.md
+++ b/docs/air-firmament-a2-1-semantic-references-admissibility-surface-doctrine.md
@@ -381,6 +381,8 @@ A2.1 tests should verify that metadata is recognized, V2 semantic-reference fixt
A2.1 extends A2 rather than replacing it. A2 remains the broader V2 source-language audit; this document is the semantic-reference, admissibility, and surface-doctrine addendum. The A1 fixture-corpus doc records the expanded V2 metadata-only taxonomy. The A0 compiler IR constitution records that Firmament V2 rejects provable degenerate construction intent before backend emission when possible.
+A2.2 extends this doctrine with `with` record derivation/configuration. `=>` remains the semantic exposure construct; `with` derives record values and must revalidate derived records rather than mutating selectors, backend topology, or existing objects. See `docs/air-firmament-a2-2-record-derivation-with.md`.
+
## 21. Non-goals
A2.1 explicitly preserves: no parser implementation; no backend implementation; no shell implementation; no fillet implementation; no surfacing implementation; no pattern implementation; no material implementation; no broad Boolean; no CIR topology authority; no STEP behavior change; no BRep topology behavior change; no Firmasm redesign; no corpus migration; no production route replacement; no general side-hole support; no arbitrary face/axis support; no production analyzer/map behavior changes; no CIR evaluator/tape behavior changes; no route-selection/JudgmentUtility production behavior changes; no AirEdgeSweep behavior changes; no BrepBoundedChamfer/BrepBoundedFillet behavior changes; no triangle migration; and no NURBS/freeform implementation.
diff --git a/docs/air-firmament-a2-2-record-derivation-with.md b/docs/air-firmament-a2-2-record-derivation-with.md
new file mode 100644
index 00000000..a3a3aba8
--- /dev/null
+++ b/docs/air-firmament-a2-2-record-derivation-with.md
@@ -0,0 +1,361 @@
+# AIR-FIRMAMENT-A2.2 — Firmament V2 record derivation with `with`
+
+## 1. Purpose
+
+A2.2 defines `with` as Firmament V2's record derivation and configuration mechanism. Firmament V2 is a typed declarative record language, so configuration should remain data-shaped: named records are authored once, then immutable derived records express variants by overriding selected fields.
+
+This doctrine covers immutable record derivation, model variants, feature variants, material variants, configuration records, admissibility revalidation, and the forbidden meanings that `with` must never acquire. `with` is admitted because it preserves the language's record/object nature while giving users a clean way to define variants without conditionals, loops, macros, arbitrary logic, mutation, topology editing, or backend patching.
+
+A2.2 is design, documentation, and metadata-fixture work only. It does not implement a full V2 parser, backend behavior, geometry features, source evaluation, or corpus migration.
+
+## 2. Firmament V2 identity recap
+
+```text
+Firmament V2 is a typed declarative record language for CAD construction intent.
+
+It has no loops, no conditionals, no user-defined functions, no arbitrary logic, and no backend topology IDs.
+
+`with` provides configuration/variant ergonomics without adding general control flow.
+```
+
+Firmament V2 remains a source language for construction intent. Feature AIR, Constructive/Compositional AIR, BRepPlan, BRep, and STEP remain downstream compiler/backend stages rather than source-level editing targets.
+
+## 3. `with` doctrine
+
+```text
+`with` creates a new source-level record value by copying an existing record and overriding selected fields.
+
+It is immutable source-level record derivation.
+It is not mutation.
+It is not topology editing.
+It is not control flow.
+It is not backend patching.
+It does not operate on BRep entities.
+```
+
+Example:
+
+```firmament
+solid base = Box {
+ size: [10, 8, 6]
+}
+
+solid tall = base with {
+ size: [10, 8, 12]
+}
+```
+
+Meaning:
+
+```text
+`tall` is a new Box-derived source record with a different size.
+`base` is unchanged.
+Both records must satisfy Box admissibility.
+```
+
+## 4. Revalidation / admissibility
+
+Derived records must be revalidated under the same admissibility contracts as directly-authored records. Copying a valid source record does not make every override valid; the derived record must still satisfy constructor, field-type, geometric, semantic-reference, and feature admissibility rules before lowering.
+
+```firmament
+solid base = Box {
+ size: [10, 8, 6]
+}
+
+solid bad = base with {
+ size: [10, 0, 6]
+}
+```
+
+Expected diagnostic:
+
+```text
+firmament-degenerate-dimension
+```
+
+Nested feature derivation is also revalidated:
+
+```firmament
+feature hole = Cut {
+ on: face(+X)
+
+ tool: Cylinder {
+ radius: 1
+ through: face(-X)
+ }
+}
+
+feature badHole = hole with {
+ tool: hole.tool with {
+ radius: -2
+ }
+}
+```
+
+Expected diagnostic:
+
+```text
+firmament-negative-radius
+```
+
+A compiler may report a wrapper diagnostic such as `firmament-with-derived-record-invalid`, but it must preserve the specific admissibility cause.
+
+## 5. Valid uses of `with`
+
+### A. Solid variants
+
+```firmament
+solid base = Box {
+ size: [10, 8, 6]
+}
+
+solid small = base with {
+ size: [8, 6, 4]
+}
+
+solid large = base with {
+ size: [20, 16, 12]
+}
+```
+
+### B. Feature variants
+
+```firmament
+feature sideHole = Cut {
+ on: face(+X)
+
+ tool: Cylinder {
+ radius: 1
+ through: face(-X)
+ }
+}
+
+feature largeSideHole = sideHole with {
+ tool: sideHole.tool with {
+ radius: 2
+ }
+}
+```
+
+### C. Material variants
+
+```firmament
+material steel = Isotropic {
+ youngs: 200 GPa
+ poisson: 0.30
+ density: 7850 kg/m^3
+}
+
+material softSteel = steel with {
+ youngs: 180 GPa
+}
+```
+
+### D. Pattern variants
+
+```firmament
+feature ribs = LinearPattern {
+ seed: rib
+ count: 6
+ spacing: 10
+ direction: +Y
+}
+
+feature denseRibs = ribs with {
+ count: 12
+ spacing: 5
+}
+```
+
+Pattern examples remain doctrine/design unless a later milestone implements pattern parsing and lowering.
+
+### E. Configuration records
+
+```firmament
+config defaultBox = BoxConfig {
+ size: [10, 8, 6]
+ holeRadius: 1
+}
+
+config largeBox = defaultBox with {
+ size: [20, 16, 12]
+ holeRadius: 2
+}
+```
+
+`config` is design-level/future doctrine in A2.2. It records how configuration should stay declarative if admitted later; it is not parser-backed here.
+
+## 6. Invalid uses of `with`
+
+`with` requires a source-level record value. It is explicitly forbidden on semantic references and selectors:
+
+```firmament
+select topFace = base.face(+Z)
+
+solid bad = topFace with {
+ ...
+}
+```
+
+Expected diagnostic:
+
+```text
+firmament-with-requires-record
+```
+
+Also forbidden:
+
+- `with` on raw BRep IDs;
+- `with` on STEP entity IDs;
+- `with` on coedges/backend topology;
+- `with` to mutate an existing object in place;
+- `with` to bypass feature admissibility.
+
+Suggested diagnostics:
+
+- `firmament-with-requires-record`
+- `firmament-with-field-not-found`
+- `firmament-with-field-type-mismatch`
+- `firmament-with-cannot-target-selector`
+- `firmament-with-cannot-target-backend-id`
+- `firmament-with-derived-record-invalid`
+
+## 7. Nested `with`
+
+Nested derivation is valid when every target is a source-level record value:
+
+```firmament
+feature largerHole = sideHole with {
+ tool: sideHole.tool with {
+ radius: 2
+ }
+}
+```
+
+Rules:
+
+- inner derivation is evaluated as source record derivation;
+- outer derived record receives the derived field value;
+- all derived records are revalidated;
+- no mutation occurs.
+
+## 8. `with` and identity
+
+```text
+A `with` expression creates a new source object identity when bound to a new name.
+The original object remains unchanged.
+Derived objects may share provenance with their source record for trace/debugging.
+```
+
+Example:
+
+```firmament
+solid base = Box { size: [10, 8, 6] }
+solid tall = base with { size: [10, 8, 12] }
+```
+
+`base` and `tall` are distinct source solids. The compiler may retain provenance that `tall` was derived from `base`, but that provenance is debug/trace metadata, not source mutation or shared backend topology identity.
+
+## 9. `with` and source ordering
+
+A `with` source must refer to a previously defined record in the current scope. Forward references are not part of A2.2 doctrine unless later admitted. Duplicate names remain invalid.
+
+Suggested diagnostics:
+
+- `firmament-name-unresolved`
+- `firmament-duplicate-name`
+
+## 10. `with` and no-control-flow doctrine
+
+`with` replaces common configuration use cases that would otherwise push users toward conditionals.
+
+Bad:
+
+```text
+if variant == large { ... }
+```
+
+Good:
+
+```firmament
+config large = default with {
+ size: [20, 16, 12]
+}
+```
+
+Variants are data. Patterns are data. Record derivation is data. No runtime branching, looping, macro expansion, or arbitrary execution is introduced.
+
+## 11. Interaction with `=>`
+
+`=>` binds semantic selectors and feature roles to names. `with` derives record values. They are separate constructs.
+
+Valid:
+
+```firmament
+solid base = Box {
+ size: [10, 8, 6]
+
+ expose {
+ face(+Z) => top
+ }
+}
+
+solid tall = base with {
+ size: [10, 8, 12]
+}
+```
+
+Whether exposed aliases are copied into derived records by default is a design question, not implemented doctrine in A2.2. Conservative doctrine for now:
+
+- record fields are copied by `with`;
+- semantic exposure aliases are copied only if they remain valid under the derived record and the feature family admits that behavior;
+- otherwise, alias copying may be blocked or re-resolved;
+- A2.2 does not implement alias-copying behavior.
+
+## 12. Lowering model
+
+```text
+Firmament V2 source
+ -> parse
+ -> resolve names / `with` derivation
+ -> validate derived records
+ -> semantic intent
+ -> Feature AIR
+ -> Constructive / Compositional AIR
+ -> BRepPlan
+ -> BRep
+ -> STEP/artifacts
+```
+
+`with` should be resolved before Feature AIR lowering as source-level record derivation. Downstream stages should see admitted source records and provenance, not an instruction to mutate backend topology.
+
+## 13. Firmasm note
+
+Firmasm remains JSON/record-like and does not need a `with` redesign unless a later machine-level configuration representation is needed. A2.2 does not redesign Firmasm.
+
+## 14. Pilot metadata/design fixtures
+
+A2.2 adds metadata-only Firmament V2 fixtures under `fixtures/FirmamentV2/RecordDerivation/`. Until a V2 parser exists, valid examples are classified as future design/not implemented with `firmament-v2-parser-not-ready`, and invalid examples are classified by metadata diagnostics. They must not be sent through the V1 parser as random failures.
+
+The pilot fixture set is:
+
+```text
+fixtures/FirmamentV2/RecordDerivation/valid/box-with-size-variant-v2.valid.firmfixture
+fixtures/FirmamentV2/RecordDerivation/valid/feature-with-radius-variant-v2.valid.firmfixture
+fixtures/FirmamentV2/RecordDerivation/valid/material-with-property-variant-v2.valid.firmfixture
+fixtures/FirmamentV2/RecordDerivation/invalid/with-degenerate-box-v2.invalid.firmfixture
+fixtures/FirmamentV2/RecordDerivation/invalid/with-selector-target-v2.invalid.firmfixture
+fixtures/FirmamentV2/RecordDerivation/invalid/with-unknown-field-v2.invalid.firmfixture
+```
+
+## 15. Tests
+
+A2.2 tests should verify that record-derivation fixtures are discoverable metadata-only Firmament V2 fixtures, that they are classified by metadata instead of as V1 parse failures, that invalid fixtures report expected diagnostics (`firmament-degenerate-dimension`, `firmament-with-requires-record`, `firmament-with-field-not-found`), that doctrine mentions immutable derivation, no mutation, no topology editing, admissibility revalidation, no control flow, nested `with`, and the interaction with `=>`, and that existing V1 box and side-hole fixtures remain valid.
+
+## 16. Docs updates
+
+A2.2 extends A2 and A2.1 rather than replacing them. A2 remains the broad Firmament V2 source-language audit, A2.1 remains the semantic-reference/admissibility/surface-doctrine addendum, and A2.2 is the record-derivation/configuration addendum. The A1 fixture-corpus doc records the expanded `RecordDerivation` V2 fixture taxonomy. The A0 compiler IR constitution records that `with` is source-level record derivation resolved before AIR lowering.
+
+## 17. Non-goals
+
+A2.2 explicitly preserves: no parser implementation; no backend implementation; no geometry implementation; no source evaluator; no conditionals; no loops; no functions; no macros; no shell implementation; no fillet implementation; no surfacing implementation; no pattern implementation; no material implementation; no broad Boolean; no CIR topology authority; no STEP behavior change; no BRep topology behavior change; no Firmasm redesign; no corpus migration; no production route replacement; no general side-hole support; no arbitrary face/axis support; no production analyzer/map behavior changes; no CIR evaluator/tape behavior changes; no route-selection/JudgmentUtility production behavior changes; no AirEdgeSweep behavior changes; no BrepBoundedChamfer/BrepBoundedFillet behavior changes; no triangle migration; and no NURBS/freeform implementation.
diff --git a/docs/air-firmament-a2-firmament-v2-source-language-design.md b/docs/air-firmament-a2-firmament-v2-source-language-design.md
index 4ddcfd08..87a3e0fb 100644
--- a/docs/air-firmament-a2-firmament-v2-source-language-design.md
+++ b/docs/air-firmament-a2-firmament-v2-source-language-design.md
@@ -6,6 +6,8 @@ Firmament V2 is the next canonical human-facing Aetheris source language. It is
A2 is a design/audit milestone. It defines doctrine, policy, syntax shape, source constructs, lowering expectations, and fixture process. It does not implement a full V2 parser, migrate the corpus, add geometry features, replace production routes, change STEP behavior, change BRep topology behavior, or promote CIR to topology authority.
+A2.2 adds `with` as the Firmament V2 record-derivation/configuration doctrine: immutable source records may derive named variants by overriding fields, then revalidating under the same admissibility contracts before AIR lowering. See `docs/air-firmament-a2-2-record-derivation-with.md`.
+
## Relationship to Firmament V1
```text
diff --git a/fixtures/FirmamentV2/RecordDerivation/invalid/with-degenerate-box-v2.invalid.firmfixture b/fixtures/FirmamentV2/RecordDerivation/invalid/with-degenerate-box-v2.invalid.firmfixture
new file mode 100644
index 00000000..0ab26f16
--- /dev/null
+++ b/fixtures/FirmamentV2/RecordDerivation/invalid/with-degenerate-box-v2.invalid.firmfixture
@@ -0,0 +1,22 @@
+// fixture-id: with-degenerate-box-v2
+// case: firmament-v2-with-degenerate-box
+// category: RecordDerivation
+// syntax-version: FirmamentV2
+// validity: invalid
+// implementation: rejected
+// expected: invalid
+// expected-stage: rejected
+// expected-diagnostic: firmament-degenerate-dimension
+// notes: AIR-FIRMAMENT-A2.2 metadata-only invalid derivation fixture; derived Box must be revalidated.
+
+model WithDegenerateBox {
+ units mm
+
+ solid base = Box {
+ size: [10, 8, 6]
+ }
+
+ solid bad = base with {
+ size: [10, 0, 6]
+ }
+}
diff --git a/fixtures/FirmamentV2/RecordDerivation/invalid/with-selector-target-v2.invalid.firmfixture b/fixtures/FirmamentV2/RecordDerivation/invalid/with-selector-target-v2.invalid.firmfixture
new file mode 100644
index 00000000..5a817e82
--- /dev/null
+++ b/fixtures/FirmamentV2/RecordDerivation/invalid/with-selector-target-v2.invalid.firmfixture
@@ -0,0 +1,24 @@
+// fixture-id: with-selector-target-v2
+// case: firmament-v2-with-selector-target
+// category: RecordDerivation
+// syntax-version: FirmamentV2
+// validity: invalid
+// implementation: rejected
+// expected: invalid
+// expected-stage: rejected
+// expected-diagnostic: firmament-with-requires-record
+// notes: AIR-FIRMAMENT-A2.2 metadata-only invalid derivation fixture; with cannot target selectors.
+
+model WithSelectorTarget {
+ units mm
+
+ solid base = Box {
+ size: [10, 8, 6]
+ }
+
+ select topFace = base.face(+Z)
+
+ solid bad = topFace with {
+ size: [10, 8, 12]
+ }
+}
diff --git a/fixtures/FirmamentV2/RecordDerivation/invalid/with-unknown-field-v2.invalid.firmfixture b/fixtures/FirmamentV2/RecordDerivation/invalid/with-unknown-field-v2.invalid.firmfixture
new file mode 100644
index 00000000..79de9496
--- /dev/null
+++ b/fixtures/FirmamentV2/RecordDerivation/invalid/with-unknown-field-v2.invalid.firmfixture
@@ -0,0 +1,22 @@
+// fixture-id: with-unknown-field-v2
+// case: firmament-v2-with-unknown-field
+// category: RecordDerivation
+// syntax-version: FirmamentV2
+// validity: invalid
+// implementation: rejected
+// expected: invalid
+// expected-stage: rejected
+// expected-diagnostic: firmament-with-field-not-found
+// notes: AIR-FIRMAMENT-A2.2 metadata-only invalid derivation fixture; overridden fields must exist on the source record type.
+
+model WithUnknownField {
+ units mm
+
+ solid base = Box {
+ size: [10, 8, 6]
+ }
+
+ solid bad = base with {
+ colorway: "blue"
+ }
+}
diff --git a/fixtures/FirmamentV2/RecordDerivation/valid/box-with-size-variant-v2.valid.firmfixture b/fixtures/FirmamentV2/RecordDerivation/valid/box-with-size-variant-v2.valid.firmfixture
new file mode 100644
index 00000000..3da64f1e
--- /dev/null
+++ b/fixtures/FirmamentV2/RecordDerivation/valid/box-with-size-variant-v2.valid.firmfixture
@@ -0,0 +1,22 @@
+// fixture-id: box-with-size-variant-v2
+// case: firmament-v2-box-with-size-variant
+// category: RecordDerivation
+// syntax-version: FirmamentV2
+// validity: valid
+// implementation: not-implemented
+// expected: valid
+// expected-stage: not-implemented
+// expected-diagnostic: firmament-v2-parser-not-ready
+// notes: AIR-FIRMAMENT-A2.2 metadata-only record derivation fixture; not parser-backed.
+
+model BoxWithSizeVariant {
+ units mm
+
+ solid base = Box {
+ size: [10, 8, 6]
+ }
+
+ solid tall = base with {
+ size: [10, 8, 12]
+ }
+}
diff --git a/fixtures/FirmamentV2/RecordDerivation/valid/feature-with-radius-variant-v2.valid.firmfixture b/fixtures/FirmamentV2/RecordDerivation/valid/feature-with-radius-variant-v2.valid.firmfixture
new file mode 100644
index 00000000..a0c2640a
--- /dev/null
+++ b/fixtures/FirmamentV2/RecordDerivation/valid/feature-with-radius-variant-v2.valid.firmfixture
@@ -0,0 +1,29 @@
+// fixture-id: feature-with-radius-variant-v2
+// case: firmament-v2-feature-with-radius-variant
+// category: RecordDerivation
+// syntax-version: FirmamentV2
+// validity: valid
+// implementation: not-implemented
+// expected: valid
+// expected-stage: not-implemented
+// expected-diagnostic: firmament-v2-parser-not-ready
+// notes: AIR-FIRMAMENT-A2.2 metadata-only nested with feature variant fixture; not parser-backed.
+
+model FeatureWithRadiusVariant {
+ units mm
+
+ feature sideHole = Cut {
+ on: face(+X)
+
+ tool: Cylinder {
+ radius: 1
+ through: face(-X)
+ }
+ }
+
+ feature largeSideHole = sideHole with {
+ tool: sideHole.tool with {
+ radius: 2
+ }
+ }
+}
diff --git a/fixtures/FirmamentV2/RecordDerivation/valid/material-with-property-variant-v2.valid.firmfixture b/fixtures/FirmamentV2/RecordDerivation/valid/material-with-property-variant-v2.valid.firmfixture
new file mode 100644
index 00000000..61e486f7
--- /dev/null
+++ b/fixtures/FirmamentV2/RecordDerivation/valid/material-with-property-variant-v2.valid.firmfixture
@@ -0,0 +1,24 @@
+// fixture-id: material-with-property-variant-v2
+// case: firmament-v2-material-with-property-variant
+// category: RecordDerivation
+// syntax-version: FirmamentV2
+// validity: valid
+// implementation: not-implemented
+// expected: valid
+// expected-stage: not-implemented
+// expected-diagnostic: firmament-v2-parser-not-ready
+// notes: AIR-FIRMAMENT-A2.2 metadata-only material variant fixture; material parsing/lowering is not implemented.
+
+model MaterialWithPropertyVariant {
+ units mm
+
+ material steel = Isotropic {
+ youngs: 200 GPa
+ poisson: 0.30
+ density: 7850 kg/m^3
+ }
+
+ material softSteel = steel with {
+ youngs: 180 GPa
+ }
+}