Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel
docs: add CIR-T0 surface-restricted trim-oracle architecture design
Yuechen Li6e10fe90cd6a
diff --git a/docs/cir-t0-surface-restricted-field-trim-oracle.md b/docs/cir-t0-surface-restricted-field-trim-oracle.mdnew file mode 100644index 00000000..6e4bbe73--- /dev/null+++ b/docs/cir-t0-surface-restricted-field-trim-oracle.md@@ -0,0 +1,374 @@+# CIR-T0: surface-restricted field / trim oracle design++## 1) Problem statement++Current CIR/F8 readiness and candidate generation treat trim support primarily as a **surface-family pair classification** (`TrimCapabilityMatrix`) and do not yet compute retained trim loops from the opposite operand field. This becomes the bottleneck for high-value deferred families (notably planar×toroidal and several cylindrical/spherical combinations) even when both operands are evaluable in CIR.++CIR-T0 defines the architecture pivot:++- from: `source family × opposite family -> static capability`+- to: `source surface S(u,v) + opposite CIR field F(x,y,z) -> restricted field g(u,v)=F(S(u,v)) -> contours + retained region sign`++Scope guardrails for T0:++- design/probe only (no production contour extraction yet),+- no BRep topology behavior changes,+- no STEP behavior changes,+- no CIR materialization changes,+- no surface-feature behavior changes.++## 2) Definition of a surface-restricted field++### Proposed descriptor: `SurfaceRestrictedField`++```text+SurfaceRestrictedField+ SourceSurfaceId / Provenance+ SourceDescriptor (SourceSurfaceDescriptor)+ ParameterizationContract (IRestrictedSurfaceParameterization)+ Domain2D (uMin,uMax,vMin,vMax + seam flags)+ OppositeSelection (operand role + source/opposite subtree ids)+ OppositeField (CirTape preferred; CirNode fallback for diagnostics)+ ToleranceContext+ OrientationPolicy+ Evaluate(u,v) -> RestrictedFieldSample+ EvaluateInterval(domainCell2D) -> FieldInterval (future)+ Diagnostics (construction + sampling provenance)+```++### Why `CirTape` first, `CirNode` second++- `CirTape` is already the runtime execution form with primitive payload transforms and point evaluation, and has interval classification infrastructure that can be adapted conceptually to 2D cells after mapping into world-space bounds.+- `CirNode` should remain available as semantic oracle and for debugging parity checks, but the restricted-field runtime should execute tape-first to stay aligned with CIR-E architecture.++### How “opposite” is encoded++In subtract roots, opposite is role-dependent:++- source from left/base subtree => opposite is right/tool subtree,+- source from right/tool subtree => opposite is left/base subtree.++`SurfaceRestrictedField` should explicitly carry:++- `SourceOperandRole` (`Base`/`Tool`),+- `OppositeOperandRole`,+- subtree identity (at least replay op index + operand side; eventually stable subtree key).++### Relationship to source descriptors++`SourceSurfaceDescriptor` remains the geometry/provenance anchor. `SurfaceRestrictedField` is derived from one descriptor plus one opposite field tape and an explicit parameterization contract. It is not a replacement for descriptor extraction; it is the execution layer above it.++## 3) Current infrastructure audit (what exists now)++### CIR evaluation runtime++- `CirNode` and concrete nodes (box/cylinder/sphere/torus/transform/union/subtract/intersect) provide semantic SDF evaluation and bounds.+- `CirTapeLowerer` composes transforms into inverse payload transforms and lowers booleans to `Min/Max/Neg` instruction sequences.+- `CirTape.Evaluate` provides pointwise field values; `EvaluateInterval` provides conservative 3D AABB intervals.+- `CirRegionPlanner` already uses `JudgmentEngine` for admissibility/utility-based decision among classify/subdivide/sample options.+- `CirAdaptiveVolumeEstimator` already operationalizes planner decisions, adaptive splitting, direct sampling, and trace diagnostics.++### Surface descriptor/readiness infrastructure++- `SourceSurfaceExtractor` inventories primitive-origin surfaces for box/cylinder/sphere/torus and composes transforms.+- `BoundedPlanarPatchGeometry` exists for rectangle and circle; cylindrical caps can emit circle geometry when transform preserves circularity.+- `CylindricalSurfaceGeometryEvidence` carries axis/radius/height plus bottom/top centers.+- `FacePatchCandidateGenerator` currently uses `TrimCapabilityMatrix` pair lookups plus subtract-role heuristics; loop descriptors are scaffolding, not contour-derived.+- `MaterializationReadinessAnalyzer` aggregates evidence layers; explicitly dry-run and conservative.++### Existing docs that frame this pivot++- CURVE-A0 recommends tiered trim representation with surface-intersection provenance first, analytic realization second, numerical cache third.+- CIR-F8/F8.2/F8.10 establish descriptor-first and readiness-gated architecture with deferred torus/general algebraic cases.+- CIR-F15/F16 establish internal identity/token diagnostics for future stitching.+- SURFACE-FEATURE A0-A4 establish descriptor/planning/evidence patterns and explicit exactness honesty.++## 4) Parameterization readiness by surface family++### A) Planar bounded rectangle (box faces): **ready first**++Available now:++- 4 corners (`Corner00/10/11/01`) in world coordinates,+- plane normal,+- finite rectangular domain.++T0 contract:++- `u` axis: `Corner00 -> Corner10`, `v` axis: `Corner00 -> Corner01`,+- domain `[0,1] × [0,1]` (or metric extents, but normalized recommended first),+- mapping `S(u,v)=Corner00 + u*(Corner10-Corner00) + v*(Corner01-Corner00)`.++### B) Planar circular cap (cylinder caps): **near-ready second**++Available now:++- `BoundedPlanarPatchGeometry.Kind=Circle` with center/normal/radius (when transform admissible).++Missing/choice:++- canonical in-plane axis frame for stable `(u,v)`/polar mapping.++T0 recommendation:++- choose disk-local rectangular parameterization over polar for T2/T3 simplicity,+- domain `[-R,R]×[-R,R]` with in-disk predicate for valid samples,+- defer exact seam/orientation intricacies until post-T3.++### C) Cylindrical side: **ready with seam policy definition**++Available now:++- `CylindricalSurfaceGeometryEvidence` axis origin/direction, radius, height, end centers.++Needed contract:++- parameters `(theta,z)` with `theta` in `[0,2π)` and `z` in `[0,height]` (or centered range),+- explicit seam duplication policy for contour extraction at theta wrap,+- world mapping `S(theta,z)=axisPoint(z)+radius*(xFrame*cos(theta)+yFrame*sin(theta))`.++### D) Spherical: **descriptor thin, parameterization not yet contracted**++Current `SourceSurfaceDescriptor` for sphere has family/provenance but no typed sphere geometry evidence (center/radius/frame). This is insufficient for robust restricted parameter mapping.++### E) Toroidal: **later; geometry evidence missing for parameterization contract**++Current torus descriptors are family/provenance only plus deferred diagnostics; no typed major/minor/frame evidence contract.++### First target recommendation for CIR-T1++**Planar bounded rectangle** should be first target due to strongest current evidence shape, no seam singularity, and immediate coverage of box-face subtract scenarios.++## 5) Opposite operand selection plan++### Subtract semantics (first contract)++For `CirSubtractNode(A,B)`:++- for descriptors originating from `A`: opposite field is `Lower(B)`;+- for descriptors originating from `B`: opposite field is `Lower(A)`.++### Can current code identify source/opposite reliably?++Partially:++- current code uses `IsFromNode` by comparing `SourceSurfaceDescriptor.OwningCirNodeKind` to `node.GetType().Name`; this is not robust when both sides share primitive type (e.g., cylinder minus cylinder).++Missing for robust trim-oracle routing:++- stable per-descriptor subtree identity (operand path or unique node id),+- explicit operand-side provenance (`Left`/`Right`) at extraction time.++### Contract addition recommended++Extend descriptor provenance metadata (internal only) with:++- `OwningOperandPath` (e.g., `L`, `R`, `LLR`),+- `OwningBooleanRootOpIndex` where available,+- deterministic source/opposite resolution helper for subtract roots.++Union/intersect semantics can be deferred but conceptually map to sign rules over each side’s field; no need to block subtract-first milestone.++## 6) Relationship to `TrimCapabilityMatrix`++`TrimCapabilityMatrix` should evolve from hard gate to layered helper:++1. **Coarse prior / planning hint**: expected curve families, risk class, and likely snap candidates.+2. **Post-contour classifier**: label extracted contours as line/circle/ellipse/implicit candidate.+3. **Snap registry input**: choose analytic snap strategies allowed for a pair.++It should no longer be the sole determinant of “can we trim at all.”++Impact on torus cases:++- planar×toroidal can move from blanket deferred to “restricted-field contour available; exact snap/export deferred,” enabling meaningful progression without false exactness.++## 7) Sampling/contouring plan (design only)++### Baseline++1. Build restricted field on parameter domain.+2. Sample regular grid of scalar values/signs.+3. Classify 2D cells (inside/outside/mixed).+4. Extract zero contours via marching squares.+5. Lift polyline samples to 3D via `S(u,v)`.++### Reuse from CIR runtime++Reusable immediately:++- opposite field evaluation via `CirTape.Evaluate`,+- tolerance semantics (`ToleranceContext`) and sign classification idioms,+- planner pattern from `CirRegionPlanner`/`CirAdaptiveVolumeEstimator`.++Needs 2D equivalents/new components:++- 2D domain/cell structures,+- 2D interval heuristic (optional early; can start sample-first),+- marching squares implementation and contour stitching,+- seam-aware contour assembly for periodic surfaces.++### JudgmentEngine placement++Use `JudgmentEngine` once multiple bounded strategies compete, e.g.:++- subdivide-vs-direct-sample decisions per 2D cell,+- snap candidate choice (circle/line/implicit polyline),+- exact-snap vs numerical-only vs deferred-export route.++## 8) Output model proposal++Proposed internal records for T2+:++```text+SurfaceFieldSampleGrid+ SurfaceRestrictedFieldId+ Domain2D+ ResolutionU/ResolutionV+ Samples[][] (value, sign, worldPoint optional)+ Diagnostics++SurfaceTrimContour2D+ LoopId+ Closed+ PolylineUV+ Orientation+ ExtractionMethod (MarchingSquares/Other)+ Confidence++SurfaceTrimContour3D+ LoopId+ PolylineXYZ+ SourceContour2DId+ LiftDiagnostics++SurfaceRegionClassification2D+ RegionId+ RepresentativePointUV+ SignClass (Inside/Outside/Mixed/Unknown)+ SupportingSamples++SurfaceRestrictedFieldDiagnostic+ Code+ Message+ Severity+ SourceProvenance+```++Alignment with CURVE-A0 tiering:++- Tier 1: analytic snap result (when available),+- Tier 2: surface-intersection provenance bundle (source surface + opposite field + extraction metadata),+- Tier 3: numerical contour cache/polylines with explicit non-exact flags.++## 9) Materialization pipeline integration plan++### Near-term integration points++- `SourceSurfaceExtractor`: add typed parameterization payloads (first planar rectangle) and operand-path provenance.+- `FacePatchCandidateGenerator`: for subtract candidates, request restricted-field evidence instead of only pair-table best score; retained loops become evidence-backed.+- `TrimCapabilityMatrix`: demote to hint/classifier/snap policy layer.+- `MaterializationReadinessAnalyzer`: add layer signals such as+ - `restricted-field-evidence-ready`,+ - `contour-extracted-numerical-only`,+ - `analytic-snap-ready` / `export-deferred`.++### Connection to existing loop descriptors++`RetainedRegionLoopDescriptor` should gain provenance mode fields (future milestone):++- `LoopProvenanceKind` (`MatrixOnly`, `RestrictedFieldNumeric`, `RestrictedFieldSnappedAnalytic`),+- contour ids/snap diagnostics,+- export capability classification.++This lets `PlanarSurfaceMaterializer` remain unchanged initially while readiness/diagnostics become more truthful for deferred pairs.++### Surface-feature future++The same restricted-field oracle supports groove-like host-surface bounded features by evaluating feature-local tool fields on host parameter domains, consistent with SURFACE-FEATURE descriptor/planning/evidence architecture.++## 10) Export/exactness policy++Hard policy:++- Numerical contours are **not** exact AP242 trims by themselves.+- Exact export requires analytic snap or exact realizable trim curve representation supported by current exporter/importer lanes.+- CIR preview/readiness can consume numerical contours with explicit non-exact/deferred export diagnostics.+- No path may silently promote numerical polylines to exact trim claims.++## 11) Risks and guardrails++Risks:++1. parameterization frame mistakes (uv->xyz misalignment),+2. seam discontinuity errors (cylinder periodic wrap),+3. sampling aliasing/missed small components,+4. contour branching/self-intersection ambiguities,+5. tangent/grazing zero-set instability,+6. singularities (sphere poles, torus inner radius regimes),+7. tolerance sign flips around zero,+8. performance blow-up from brute grids,+9. false exactness in downstream readiness/export messaging.++Guardrails:++- mandatory diagnostics for frame/domain construction,+- deterministic tolerance band policy near zero,+- minimum and adaptive maximum sampling controls,+- contour validity checks (closedness, degeneracy, area thresholds),+- explicit `ExportCapability` field on contour/snap outputs,+- conservative readiness downgrade on ambiguous topology,+- regression fixtures for known tangent and seam-crossing cases.++## 12) Implementation ladder++### CIR-T1++Planar rectangular restricted-field evaluator only:++- construct `SurfaceRestrictedField` from planar rectangle descriptor,+- choose opposite tape for subtract,+- evaluate sample probes `(u,v)->F(S(u,v))`,+- no contour extraction yet.++### CIR-T2++- regular sample grid + sign classification on planar rectangles,+- diagnostics and retention-side sign summaries.++### CIR-T3++- marching squares contour extraction on planar rectangles,+- closed/open loop diagnostics.++### CIR-T4++- analytic snap for planar line/circle first,+- snap confidence and rejection diagnostics.++### CIR-T5++- feed contours/snap into `RetainedRegionLoopDescriptor` provenance,+- readiness analyzer integration for numerical-vs-exact policy.++### CIR-T6++- cylindrical side restricted field (`theta,z`) with seam policy.++### CIR-T7++- surface-feature groove prototype using restricted-field evidence path.++## 13) Recommended CIR-T1 next step++Proceed with **CIR-T1 = planar rectangular restricted-field evaluator** under subtract roots only, with the following acceptance checks:++1. build restricted fields for box planar faces with explicit uv frame/domain diagnostics,+2. resolve opposite operand tape by subtract side,+3. evaluate deterministic probe set and verify sign behavior for:+ - box face vs cylinder field,+ - box face vs sphere field,+ - box face vs torus field,+4. emit readiness diagnostics explicitly stating: evaluation/oracle available, contour extraction not yet implemented, export unchanged.++This gives a low-risk, high-evidence bridge into T2/T3 while respecting all no-behavior-change constraints.