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.csnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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).