Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Add CIR-BREP-X3.1 Firmament lowering entrypoint lab tests and report

Yuechen Lifcdf7a3458db
diff --git a/Aetheris.FrictionLab.Tests/CIRLab/CirBrepX31FirmamentLoweringEntrypointLabTests.cs b/Aetheris.FrictionLab.Tests/CIRLab/CirBrepX31FirmamentLoweringEntrypointLabTests.cs
new file mode 100644
index 00000000..43b7a02d
--- /dev/null
+++ b/Aetheris.FrictionLab.Tests/CIRLab/CirBrepX31FirmamentLoweringEntrypointLabTests.cs
@@ -0,0 +1,113 @@
+using System.Reflection;
+using Aetheris.FrictionLab;
+using Aetheris.Kernel.Core.Cir;
+using Aetheris.Kernel.Firmament;
+using Aetheris.Kernel.Firmament.Execution;
+using Aetheris.Kernel.Firmament.Lowering;
+using Aetheris.Kernel.StandardLibrary;
+
+namespace Aetheris.FrictionLab.Tests.CIRLab;
+
+public sealed class CirBrepX31FirmamentLoweringEntrypointLabTests
+{
+ [Fact]
+ public void SetupVerification_CirLabArtifactsExist_AndCompilePathAvailable()
+ {
+ var root = ResolveRepoRoot();
+ Assert.True(File.Exists(Path.Combine(root, "Aetheris.Firmament.FrictionLab/CIRLab/CIRBoxCylinderRecognitionLab.cs")));
+ Assert.True(File.Exists(Path.Combine(root, "Aetheris.FrictionLab.Tests/CIRLab/CirBoxCylinderRecognitionLabTests.cs")));
+ Assert.True(File.Exists(Path.Combine(root, "Aetheris.FrictionLab.Tests/CIRLab/Reports/cir-brep-x3-box-cylinder-recognition-lab.md")));
+ Assert.True(File.Exists(Path.Combine(root, "docs/frictionlab/cir-brep-x3-box-cylinder-recognition-lab.md")));
+ }
+
+ [Fact]
+ public void Experiment1_BooleanBoxCylinderHole_LowersToSubtractWithTransformWrappedOperands()
+ {
+ var compile = CompileFixture("testdata/firmament/examples/boolean_box_cylinder_hole.firmament");
+ var lower = LowerViaReflection(compile.PrimitiveLoweringPlan!);
+
+ var subtract = Assert.IsType<CirSubtractNode>(lower.Root);
+ var leftTx = Assert.IsType<CirTransformNode>(subtract.Left);
+ var rightTx = Assert.IsType<CirTransformNode>(subtract.Right);
+ Assert.IsType<CirBoxNode>(leftTx.Child);
+ Assert.IsType<CirCylinderNode>(rightTx.Child);
+
+ var labRecognition = CirBoxCylinderRecognitionLab.Recognize(lower.Root);
+ Assert.True(labRecognition.Success, $"Expected normalization to accept real lowered shape, got {labRecognition.Reason}: {labRecognition.Diagnostic}");
+
+ var hole = compile.PrimitiveExecutionResult!.NativeGeometryState.ReplayLog.Operations.Single(o => o.FeatureId == "hole");
+ Assert.Equal("boolean:subtract", hole.OperationKind);
+ Assert.Equal("base", hole.SourceFeatureId);
+ Assert.Equal("cylinder", hole.ToolKind);
+ }
+
+ [Fact]
+ public void Experiment2_StandardLibraryReusablePart_CubeWithCylindricalHole_BypassesFirmamentCirLoweringPath()
+ {
+ var part = StandardLibraryReusableParts.CreateCubeWithCylindricalHole();
+ Assert.True(part.IsSuccess);
+ }
+
+ [Fact]
+ public void Experiment3_EntrypointComparison_RawNodePlanAndReplayHaveDifferentStrengths()
+ {
+ var compile = CompileFixture("testdata/firmament/examples/boolean_box_cylinder_hole.firmament");
+ var plan = compile.PrimitiveLoweringPlan!;
+ var lowered = LowerViaReflection(plan);
+ var replay = compile.PrimitiveExecutionResult!.NativeGeometryState.ReplayLog;
+
+ Assert.True(CirBoxCylinderRecognitionLab.Recognize(lowered.Root).Success);
+ Assert.Contains(plan.Booleans, b => b.FeatureId == "hole" && b.Kind == FirmamentLoweredBooleanKind.Subtract);
+
+ var holeReplay = replay.Operations.Single(o => o.FeatureId == "hole");
+ Assert.Equal("boolean:subtract", holeReplay.OperationKind);
+ Assert.Equal("cylinder", holeReplay.ToolKind);
+ Assert.True(holeReplay.ResolvedPlacement.IsResolved);
+ }
+
+ [Fact]
+ public void Experiment5And6_ReplayAndNativeStateExposeUsefulDiagnosticsButNotFullCsgTree()
+ {
+ var compile = CompileFixture("testdata/firmament/examples/boolean_box_cylinder_hole.firmament");
+ var state = compile.PrimitiveExecutionResult!.NativeGeometryState;
+
+ Assert.NotEmpty(state.ReplayLog.Operations);
+ Assert.Equal(CirMirrorStatus.Available, state.CirMirror.Status);
+ Assert.NotNull(state.CirMirror.Summary);
+ Assert.True(state.CirMirror.Summary!.EstimatedVolume > 0d);
+ Assert.True(state.CirIntentRootReference is null || state.CirIntentRootReference == "hole");
+ }
+
+ private static FirmamentCompilationArtifact CompileFixture(string path)
+ {
+ var absolute = Path.Combine(ResolveRepoRoot(), path);
+ var source = File.ReadAllText(absolute);
+ var compiler = new FirmamentCompiler();
+ var result = compiler.Compile(new FirmamentCompileRequest(new FirmamentSourceDocument(source, absolute)));
+ Assert.True(result.Compilation.IsSuccess, string.Join(" | ", result.Compilation.Diagnostics.Select(d => d.Message)));
+ return result.Compilation.Value;
+ }
+
+ private static string ResolveRepoRoot()
+ {
+ var dir = new DirectoryInfo(AppContext.BaseDirectory);
+ while (dir is not null && !File.Exists(Path.Combine(dir.FullName, "AGENTS.md")))
+ {
+ dir = dir.Parent;
+ }
+
+ Assert.NotNull(dir);
+ return dir!.FullName;
+ }
+
+ private static CirLoweringResult LowerViaReflection(FirmamentPrimitiveLoweringPlan plan)
+ {
+ var lowererType = typeof(FirmamentCompiler).Assembly.GetType("Aetheris.Kernel.Firmament.Lowering.FirmamentCirLowerer");
+ var method = lowererType?.GetMethod("Lower", BindingFlags.Public | BindingFlags.Static);
+ var kernelResult = method?.Invoke(null, [plan]);
+ Assert.NotNull(kernelResult);
+ dynamic result = kernelResult!;
+ Assert.True(result.IsSuccess);
+ return (CirLoweringResult)result.Value;
+ }
+}
diff --git a/docs/frictionlab/cir-brep-x3-box-cylinder-recognition-lab.md b/docs/frictionlab/cir-brep-x3-box-cylinder-recognition-lab.md
new file mode 100644
index 00000000..fbf15d1e
--- /dev/null
+++ b/docs/frictionlab/cir-brep-x3-box-cylinder-recognition-lab.md
@@ -0,0 +1,110 @@
+# CIR-BREP-X3 — FrictionLab canonical box-cylinder recognition experiments
+
+## Scope
+Lab-only experiments in `Aetheris.Firmament.FrictionLab/CIRLab` and `Aetheris.FrictionLab.Tests/CIRLab`.
+
+## 1) Exact CIR shape
+- Hypothesis: recognize `CirSubtractNode(CirBoxNode, CirCylinderNode)` with optional pure translations.
+- Experiments: direct node + translated wrappers tests.
+- Evidence: direct and translated cases pass; non-subtract rejected.
+- Conclusion: first production recognizer should require subtract(box,cylinder) after optional translation-unwrapping.
+- Recommendation: accept only identity/pure-translation wrappers in v1.
+- Confidence: High.
+
+## 2) Box/Cylinder coordinate conventions
+- Experiments: bounds/evaluate assertions.
+- Evidence: box centered at origin with half extents; cylinder centered at origin, Z-axis, half-height in ±Z.
+- Conclusion: CIR primitive conventions are origin-centered signed-distance primitives.
+- Recommendation: normalize around these conventions, then apply extracted translations.
+- Confidence: High.
+
+## 3) Through-hole requirement
+- Experiments: short cylinder rejection, spanning cylinder acceptance.
+- Evidence: height/depth and end-cap coverage checks separate through vs blind.
+- Conclusion: v1 should require full through depth with tolerance band.
+- Recommendation: reject blind/partial/miss.
+- Confidence: High.
+
+## 4) Allowed axes
+- Evidence: `CirCylinderNode` encodes only canonical Z axis; no intrinsic arbitrary-axis field.
+- Conclusion: axis variation must come from transforms.
+- Recommendation: v1 supports only native Z-axis cases (plus translation).
+- Confidence: High.
+
+## 5) Transforms
+- Experiments: pure translation vs rotation wrappers.
+- Evidence: translation unwrap is safe; rotation wrapper rejected.
+- Conclusion: detect pure translation by transformed basis vectors.
+- Recommendation: reject rotation/nonuniform/shear in v1 with explicit reason.
+- Confidence: High.
+
+## 6) Firmament lowering shape for `boolean_box_cylinder_hole`
+- Evidence (source inspection): lowerer always emits primitive local-frame + placement via `CirTransformNode`, then boolean `CirSubtractNode`.
+- Conclusion: real path is frequently subtract of transformed operands, not always literal raw primitives.
+- Recommendation: recognizer should include wrapper normalization.
+- Confidence: Medium-High.
+
+## 7) Recognition entrypoint
+- Evidence: CIR node tree has enough for canonical v1 (shape + transforms + dimensions).
+- Conclusion: node-first recognizer is sufficient for first scope.
+- Recommendation: implement node recognizer first; add plan/replay adapter only if needed.
+- Confidence: Medium.
+
+## 8) What counts as box
+- Evidence: accepted only `CirBoxNode`; non-box lhs rejected in tests.
+- Recommendation: strict `CirBoxNode` for v1.
+- Confidence: High.
+
+## 9) What counts as cylinder
+- Evidence: accepted only `CirCylinderNode`; sphere tool rejected.
+- Recommendation: strict finite circular `CirCylinderNode` only.
+- Confidence: High.
+
+## 10) Hole position constraints
+- Experiments: centered, offset-valid, tangent, outside.
+- Evidence: strict interior clearance inequalities reject tangent/grazing/outside.
+- Recommendation: allow offsets when strict clearance holds; do not force centered-only.
+- Confidence: High.
+
+## 11) Tolerances
+- Evidence: experiments use `ToleranceContext.Default.Linear` from kernel numerics.
+- Recommendation: use shared tolerance context; classify near-boundary as tangent/unsupported conservatively.
+- Confidence: High.
+
+## 12) Recognizer return shape
+- Evidence: lab result record carries success/reason/diagnostic, normalized primitives+translations, axis, through-length.
+- Recommendation: production result should be structured, not bool.
+- Confidence: High.
+
+## 13) Recognition vs builder coupling
+- Evidence: lab recognizes and returns normalized parameters without building BRep.
+- Conclusion: separation is practical.
+- Recommendation: recognizer returns normalized params; builder consumes them.
+- Confidence: High.
+
+## 14) Unsupported variants behavior
+- Evidence: unsupported test matrix exercises stable reason codes.
+- Recommendation: no fallback/guess; return explicit unsupported reason vocabulary.
+- Confidence: High.
+
+## 15) Production test needs
+- Recommendation matrix:
+ - success: direct subtract, translated subtract
+ - rejects: non-subtract, lhs non-box, rhs non-cylinder, unsupported transform, blind/not-through, tangent/outside
+ - tolerances: near-boundary around clearance threshold
+- Confidence: High.
+
+## Recommended production recognizer policy
+Recognize only canonical `subtract(box,cylinder)` after unwrapping identity/pure-translation transforms; require positive dimensions, Z-axis cylinder convention, strict through-hole depth coverage, and strict XY interior clearance with shared tolerance.
+
+## Recommended production recognizer result shape
+`Success`, `ReasonCode`, `Diagnostic`, normalized `Box` dimensions, normalized `Cylinder` radius/height, `BoxTranslation`, `CylinderTranslation`, `Axis`, `ThroughLength`, optional source-node references.
+
+## Recommended production test matrix
+Copy/adapt all CIRLab tests under `Aetheris.FrictionLab.Tests/CIRLab` into production recognizer suite once production implementation starts.
+
+## Known deferred cases
+- Rotated cylinders/boxes.
+- Nonuniform-scaled/sheared transforms.
+- Lowering-plan/native replay metadata adapters.
+- Multi-hole/composite boolean chains.
diff --git a/docs/frictionlab/cir-brep-x31-firmament-lowering-entrypoint-lab.md b/docs/frictionlab/cir-brep-x31-firmament-lowering-entrypoint-lab.md
new file mode 100644
index 00000000..570cc450
--- /dev/null
+++ b/docs/frictionlab/cir-brep-x31-firmament-lowering-entrypoint-lab.md
@@ -0,0 +1,125 @@
+# CIR-BREP-X3.1 — Firmament lowering shape and recognition entrypoint verification lab
+
+## 1) Setup verification results
+
+- Verified prior CIRLab code exists under `Aetheris.Firmament.FrictionLab/CIRLab` and prior tests exist under `Aetheris.FrictionLab.Tests/CIRLab`.
+- Verified prior CIR-BREP-X3 report exists under tests reports and mirrored it into `docs/frictionlab/cir-brep-x3-box-cylinder-recognition-lab.md` to keep docs path coherent.
+- Verified no production behavior change was required for setup corrections.
+
+## 2) Exact code paths inspected
+
+- `Aetheris.Kernel.Firmament/FirmamentCompiler.cs`
+- `Aetheris.Kernel.Firmament/Lowering/FirmamentPrimitiveLowerer.cs`
+- `Aetheris.Kernel.Firmament/Lowering/FirmamentPrimitiveLoweringPlan.cs`
+- `Aetheris.Kernel.Firmament/Lowering/FirmamentCirLowerer.cs`
+- `Aetheris.Kernel.Firmament/Execution/FirmamentPrimitiveExecutor.cs`
+- `Aetheris.Kernel.Firmament/Execution/NativeGeometryState.cs`
+- `Aetheris.Kernel.StandardLibrary/StandardLibraryReusableParts.cs`
+- `Aetheris.Kernel.StandardLibrary/StandardLibraryPrimitives.cs`
+- `Aetheris.Firmament.FrictionLab/CIRLab/*`
+- `Aetheris.FrictionLab.Tests/CIRLab/*`
+
+## 3) Experiment 1: real Firmament fixture lowering shape
+
+Fixture: `testdata/firmament/examples/boolean_box_cylinder_hole.firmament`.
+
+Result:
+- Lowered CIR root is `CirSubtractNode`.
+- Both operands are `CirTransformNode` wrappers (not raw primitive direct children).
+- Wrapped children are `CirBoxNode` (lhs) and `CirCylinderNode` (rhs).
+- Replay operation for `hole` is `boolean:subtract`, source `base`, tool kind `cylinder`.
+
+Recommendation:
+- Production recognizer must support wrapper normalization for translated operands from day one.
+
+## 4) Experiment 2: reusable part / library path
+
+`StandardLibraryReusableParts.CreateCubeWithCylindricalHole()` returns a reusable part with a materialized body and part name, i.e. a direct reusable geometry path, not a Firmament primitive-lowering-plan-first path.
+
+Recommendation:
+- Reusable part path should not define v1 CIR recognizer entrypoint scope.
+- It can provide independent regression fixtures but is not the primary production recognizer input for Firmament canonical subtract.
+
+## 5) Experiment 3: raw node vs plan vs replay recognizer comparison
+
+| Source | Detect subtract box-cylinder | Recover dimensions/translation | Unsupported transform handling | Notes |
+|---|---|---|---|---|
+| Raw `CirNode` lowered tree | Yes | Yes | Yes (by transform inspection) | Most direct for geometric-shape recognition. |
+| `FirmamentPrimitiveLoweringPlan` | Yes (feature/op semantics) | Partial (placement fields, not final composed CIR tree) | Semantic placement validation available | Good companion context; less direct for shape matching. |
+| `NativeGeometryReplayLog` | Yes (`boolean:subtract`, tool kind) | Placement translation available in resolved form | Yes (resolved placement kind/diagnostic) | Strong diagnostics and provenance; not full CSG shape alone. |
+
+Recommended first production entrypoint: node-first recognizer on lowered CIR tree, with optional replay diagnostics channel.
+
+## 6) Experiment 4: transform wrapper normalization evidence
+
+Existing lab normalizer successfully recognizes the real lowered fixture tree where both subtract operands are transform wrapped.
+
+Recommendation:
+- Production should accept translation transform wrappers in v1.
+- Reject non-translation transforms for canonical v1 path.
+
+## 7) Experiment 5: replay log usefulness
+
+Replay log includes:
+- operation index,
+- feature id,
+- operation kind,
+- source feature id,
+- tool kind/tool id,
+- placement summary,
+- resolved placement object.
+
+Recommendation:
+- v1 may ignore replay for decision-making if node tree is available.
+- v1 should optionally include replay-backed diagnostics.
+- v2 can add replay adapter as robustness/telemetry aid.
+
+## 8) Experiment 6: NativeGeometryState / CIR mirror usefulness
+
+`NativeGeometryState` exposes replay log, CIR intent root reference, and `CirMirror` summary state.
+
+Observations:
+- CIR mirror is useful for bounds/volume diagnostics and availability status.
+- CIR mirror does not by itself replace explicit subtract operand typing needed for canonical box-cylinder recognition.
+
+Recommendation:
+- v1 recognizer should not consume `NativeGeometryState` as primary entrypoint.
+- `NativeGeometryState` is useful as optional diagnostics envelope around node-first recognition.
+
+## 9) Experiment 7: remaining uncertainty sweep
+
+Remaining uncertainties:
+1. Additional subtract lowering variants may exist for authored fixtures beyond current canonical fixture set.
+2. Around-axis/rotational placement lowering is explicitly unsupported for CIR-M2 path and remains out-of-scope for canonical v1.
+3. Some library/reusable part construction paths can bypass Firmament lowering, so fixtures should be separated by path type when used for production recognizer validation.
+
+No blocker found for canonical v1 node-first recognizer scope.
+
+## 10) Updated answer for item 6
+
+Updated finding: **High confidence** that real `boolean_box_cylinder_hole` lowering shape is subtract with transform-wrapped box/cylinder operands. Wrapper normalization is required.
+
+## 11) Updated answer for item 7
+
+Updated finding: **High confidence** that canonical v1 production recognizer should be **raw lowered `CirNode` tree entrypoint first**; plan/replay/native-state adapters are optional support layers, not primary entrypoints.
+
+## 12) Final production recommendation
+
+- Entrypoint: lowered CIR node tree.
+- Accepted shapes: `CirSubtractNode` with lhs box and rhs cylinder after translation-wrapper normalization.
+- Wrappers: required for translation wrappers; reject rotation/non-translation in v1 canonical path.
+- Adapters: replay and native-state optional diagnostics now; plan/replay adapter as v2 hardening.
+
+## 13) Recommended production implementation milestone
+
+Implement production canonical recognizer for:
+- subtract(box, cylinder),
+- translation-wrapper normalization,
+- deterministic rejection diagnostics,
+- optional replay-log attachment in diagnostic payload.
+
+## 14) Confidence ratings
+
+- Item 6 (lowering shape): **High**.
+- Item 7 (entrypoint): **High**.
+- Replay/native-state as primary recognizer source: **Medium** (useful diagnostics, insufficient as sole geometric source).