feat(evals): add near-field residual and complement-QBX routes

docs/exec-plans/completed/20260612-analytic-local-residual-moments.md

@@ -0,0 +1,53 @@
+# Analytic Local Residual Moments
+
+## Objective
+
+Test the simplest analytic/asymptotic local-residual approximation for the 2D log
+Ewald split: full-space Taylor moments of the compact residual. Use it for both
+interior windows and trim-intersecting windows first, then measure where the
+boundary error appears.
+
+## Scope
+
+- Add a full-space analytic local residual estimator to the near-field split
+  sweep.
+- Compare analytic local residual values against high-order folded local
+  residual references.
+- Report interior, boundary-near, exterior-near, and vertex-near target errors.
+- Run the comparison on `ipa` and update the report.
+
+## Non-Goals
+
+- Implement boundary-aware moments.
+- Implement curved CAD fixtures.
+- Replace direct local residual references.
+
+## Acceptance Criteria
+
+- [x] Report identifies when full-space analytic moments are accurate enough and
+  when trim boundaries dominate the error.
+- [x] `make dev` passes before handoff.
+
+## Checklist
+
+- [x] Add analytic local estimator and report fields.
+- [x] Run the comparison on `ipa`.
+- [x] Update docs with conclusions.
+- [x] Validate with `make dev`.
+
+## Outcomes
+
+- The leading full-space moment `sigma^2 rho(x)/4` works for interior windows
+  when the target is well away from the trim. At `sigma=0.08`, interior analytic
+  local relative errors ranged from `2.6e-6` to `6.4e-4`.
+- The same full-space moment fails for trim-intersecting windows. Median
+  trim-near analytic local relative errors were `0.31`, `0.79`, and `1.41` for
+  `sigma=0.08`, `0.16`, and `0.32`, respectively.
+- Exterior-near targets are especially bad because the full-space moment includes
+  material outside the source region.
+- The next step is a window/boundary classifier: interior windows use analytic
+  moments; trim-intersecting windows need boundary-aware corrections.
+
+## Validation
+
+Ran `make dev` successfully after implementation and report updates.

docs/exec-plans/completed/20260612-boxcode-nearfield-template-experiment.md

@@ -0,0 +1,71 @@
+# Box-Code Near-Field Template Experiment
+
+## Objective
+
+Evaluate whether folded-decomposition charts can support reusable near-field
+template corrections for box-code and Volumential-style workflows.
+
+## Scope
+
+- Derive the mapped-kernel form for a 2D fan folded piece.
+- Focus the near-field form on point targets in physical space.
+- Identify singular factors that can be separated from smooth geometry payloads.
+- Frame the reuse hypothesis as a functional expansion in smooth metric fields
+  `M(z)`, not just as raw runtime geometry data.
+- Add a small analytic experiment driver with deterministic tests.
+- Document feasibility limits and the next CUTKIT/Volumential boundary.
+
+## Non-Goals
+
+- No production Volumential integration in this branch.
+- No CAD dependency for the first prototype.
+- No claim that arbitrary cut shapes have finite exact correction tables.
+
+## Acceptance Criteria
+
+- The derivation states the mapped self-interaction form and its split.
+- The derivation records the point-target form, target/source geometry taxonomy,
+  and measurement criteria from issue 61.
+- The prototype records a point-target template experiment with a direct
+  high-order reference value.
+- Tests check the experiment against an analytic or independently computed
+  invariant.
+- Documentation explains whether the idea is feasible and what data must remain
+  runtime geometry payload.
+
+## Completed Checklist
+
+- [x] Read issue 61 and repository orientation docs.
+- [x] Work through the 2D fan-map singularity derivation.
+- [x] Add an experiment module or script for the near-field template prototype.
+- [x] Add tests for the prototype invariants.
+- [x] Update docs and doc index if new documentation is added.
+- [x] Run targeted tests and `make dev`.
+- [x] Move this plan to completed with outcomes.
+
+## Outcomes
+
+- The near-field template idea is feasible as a CUTKIT experiment: singular and
+  nearly singular folded-piece interactions can be expressed on fixed template
+  domains.
+- The reusable singular part is a template-space log singular model. The metric
+  field `M(z) = DT(z)^T DT(z)` and higher-order terms are smooth geometry data.
+- The practical reuse hypothesis is that a functional expansion in `M(z)` and
+  smooth-remainder data covers the folded-decomposition cases with few modes.
+- The first prototype covers analytic straight fan maps, point-target
+  integrals, a log-kernel scale-law check, and a diagonal metric-remainder
+  sample.
+
+## Validation
+
+- `uv run --extra dev python -m pytest tests/evals/test_nearfield_templates.py tests/test_script_wrappers.py`
+- `uv run --extra dev python scripts/run_nearfield_template_experiment.py --order 6`
+- `make dev`
+
+## Remaining Risks
+
+- Template corrections may be reusable only after parameterized compression, not
+  as shape-independent lookup tables.
+- Self-interaction singular quadrature may need specialized rules beyond the
+  first direct high-order reference prototype.
+- Curved analytic pieces and adjacent-piece cases still need follow-up coverage.

docs/exec-plans/completed/20260612-dmk-split-nearfield-experiments.md

@@ -0,0 +1,65 @@
+# DMK Split Near-Field Experiments
+
+## Objective
+
+Run a first numerical check of the preferred near-field direction: split the 2D
+log kernel into a smooth Ewald/heat-kernel part plus a localized singular
+residual, evaluate the smooth part with folded fan quadrature, and measure when
+the residual may require boundary-aware handling.
+
+## Scope
+
+- Extend the existing straight-fan near-field prototype with a 2D log Ewald split.
+- Compare ordinary folded quadrature convergence for the full kernel versus the
+  smoothed kernel.
+- Compare current robust interior-style seeds against a simple node-barycenter
+  seed on CAD-like fan fixtures.
+- Run the numerical sweep on `ipa` and summarize results in
+  `docs/nearfield-template-experiments.md` and
+  `docs/nearfield-dmk-split-report.md`.
+
+## Non-Goals
+
+- Implement the final boundary-aware correction tables.
+- Add a production near-field API.
+- Replace existing folded decomposition seed policy.
+
+## Acceptance Criteria
+
+- [x] Experiment script emits machine-readable and Markdown summaries.
+- [x] Results include interior, boundary-near, and exterior-near target cases.
+- [x] Report states whether the smooth split improves quadrature convergence and
+  whether seed choice materially changes fan quality in the fixtures.
+- [x] `make dev` passes before handoff.
+
+## Checklist
+
+- [x] Add Ewald-split utilities and experiment dataclasses.
+- [x] Add CLI options for the DMK-style sweep and report output.
+- [x] Run the sweep on `ipa`.
+- [x] Add a concise report to the near-field notes.
+- [x] Validate with `make dev`.
+
+## Outcomes
+
+- The 2D log Ewald split made the smoothed folded-quadrature path much easier:
+  at `order=24`, smooth-part errors were at least about `70x` smaller than direct
+  full-log errors across the tested cases.
+- Median improvement was `1.8e3`, `6.6e2`, and `1.4e3` for `sigma` values
+  `0.08`, `0.16`, and `0.32`, respectively.
+- Boundary-near targets also benefited strongly, so the smooth remainder is not
+  the bottleneck in these fixtures.
+- The node-barycenter seed is viable but not uniformly better than the current
+  robust interior anchor; seed choice should remain a measured quality parameter.
+- The next unresolved issue is the localized singular residual when its window
+  intersects a rigid trim boundary.
+
+## Validation
+
+Ran `make dev` successfully after the implementation and report updates.
+
+## Risks
+
+- The straight-fan fixtures may understate CAD curvature effects.
+- Boundary-aware residual behavior requires a later local-residual experiment with
+  curved or trim-intersecting fixtures to be conclusive.

docs/exec-plans/completed/20260612-local-residual-nearfield-experiment.md

@@ -0,0 +1,52 @@
+# Local Residual Near-Field Experiment
+
+## Objective
+
+Measure the compact singular residual from the DMK-style 2D log split directly,
+to decide whether ordinary folded quadrature is adequate or whether analytic or
+boundary-aware precomputed handling is needed.
+
+## Scope
+
+- Extend the near-field split sweep with local-residual folded quadrature values.
+- Report full, smooth, local, and reconstructed errors against high-order
+  references.
+- Run the residual-inclusive sweep on `ipa`.
+- Update the near-field DMK report with conclusions.
+
+## Non-Goals
+
+- Implement analytic residual moments.
+- Implement boundary-aware precomputed correction tables.
+- Add curved CAD fan fixtures.
+
+## Acceptance Criteria
+
+- [x] Residual-inclusive report identifies whether direct local folded quadrature
+  is the new bottleneck.
+- [x] Results include the same target and seed cases as the smooth split sweep.
+- [x] `make dev` passes before handoff.
+
+## Checklist
+
+- [x] Add local residual measurements to experiment dataclasses and CLI tables.
+- [x] Run the sweep on `ipa`.
+- [x] Update reports and notes.
+- [x] Validate with `make dev`.
+
+## Outcomes
+
+- Direct ordinary folded quadrature of the compact residual is not competitive as
+  the primary method.
+- At `order=24`, smooth-part median relative errors are near `1e-7`, while local
+  residual median relative errors range from `4.2e-4` to `8.9e-3` depending on
+  `sigma`.
+- Reconstructing `smooth + local` with direct local quadrature reproduces the
+  direct full-log error, confirming that the residual is the remaining hard part.
+- The next implementation choice should be a special local residual method:
+  analytic/asymptotic moments for interior windows or boundary-aware precomputed
+  folded-fan corrections for trim-intersecting windows.
+
+## Validation
+
+Ran `make dev` successfully after the implementation and report updates.

docs/exec-plans/completed/20260613-local-model-catalogue.md

@@ -0,0 +1,37 @@
+# Local Model Catalogue
+
+## Objective
+
+Record the local analytic/asymptotic model catalogue for compact near-field
+residual corrections in 2D and 3D.
+
+## Scope
+
+- Catalog one-feature residual windows: interiors, smooth boundaries, corners,
+  faces, edges, and vertices.
+- Derive the common Taylor/modal moment expansion used by these models.
+- Record the 2D log residual radial moments used by the current experiments.
+- Link the catalogue from the near-field experiment documentation.
+
+## Acceptance Criteria
+
+- The catalogue states the routing rule that each residual support should see at
+  most one geometric singular feature.
+- 2D and 3D local models include moment formulas and leading terms where known.
+- The main near-field docs point to the catalogue as the next design reference.
+- Documentation validation passes.
+
+## Checklist
+
+- [x] Add local model catalogue.
+- [x] Add common Taylor/modal expansion.
+- [x] Add 2D log residual moment derivation.
+- [x] Link from docs index and near-field reports.
+- [x] Run validation.
+
+## Outcome
+
+Added `docs/nearfield-local-model-catalogue.md`, covering the one-feature local
+models and their expansion structure. The next implementation step is a
+window/feature classifier followed by the 2D straight-boundary half-plane moment
+experiment.

docs/exec-plans/completed/20260613-local-model-moment-tests.md

@@ -0,0 +1,64 @@
+# Local Model Moment Tests
+
+## Objective
+
+Turn the 2D straight-feature local model catalogue into executable checks for the
+log Ewald residual moments.
+
+## Scope
+
+- Add a radial moment helper for the 2D local log residual.
+- Add a sector monomial moment helper for full-plane, half-plane, and wedge
+  models at the local feature point.
+- Test the helpers against known full-plane values and independent polar
+  quadrature references.
+- Add a practical curved cut-cell check using an exact rational quadratic trim
+  and folded curve quadrature.
+- Add an exact target-centered curved-boundary model with ray clipping and finite
+  radial Ewald moments.
+- Add a high-order Taylor graph boundary model and compare it with the exact
+  circular boundary model.
+- Add a precomputation-style interpolation check for high-order smooth-boundary
+  moments.
+
+## Acceptance Criteria
+
+- Full-plane leading and second moments match closed-form values.
+- Half-plane and wedge sector moments match direct numerical quadrature within
+  the reference quadrature tolerance.
+- On a curved cut-cell sample, the half-plane model beats the full-plane model
+  for a target on the smooth trim.
+- The exact curved-boundary model agrees under refinement to better than
+  `1e-10` relative error.
+- The Taylor boundary model reaches below `1e-10` relative error at sufficiently
+  high geometry order for tested local windows.
+- The precomputed table interpolation reaches below `1e-10` relative error on
+  intermediate local-window samples.
+- The near-field targeted tests and full validation pass.
+
+## Checklist
+
+- [x] Implement radial moment helper.
+- [x] Implement sector monomial moment helper.
+- [x] Add full-plane moment tests.
+- [x] Add half-plane and wedge reference tests.
+- [x] Add curved cut-cell practical test.
+- [x] Add machine-precision curved-boundary model refinement test.
+- [x] Add high-order Taylor boundary model convergence test.
+- [x] Add precomputed boundary-table interpolation test.
+- [x] Run full validation.
+
+## Outcome
+
+Added 2D log-residual moment helpers for straight local models and tests covering
+full-plane, half-plane, and wedge sectors. The numerical reference uses a
+log-radius polar quadrature to avoid direct endpoint integration of the
+logarithmic singularity. Added a curved rational cut-cell experiment showing that
+the half-plane model is only a leading diagnostic for a target on a smooth curved
+trim; the full-plane moment incorrectly includes outside-domain mass, while
+machine precision requires exact or high-order curved boundary ray clipping with
+finite radial moments. The high-order Taylor graph model reaches the `1e-10`
+relative target on the rational quarter-circle trim at order 8 for `sigma=0.02`
+and at order 6 for `sigma=0.005, 0.01`. A first interpolation-table check over
+the normalized boundary scale also reaches the `1e-10` target, while direct
+online graph-strip quadrature is not accurate enough near the target endpoint.

docs/exec-plans/completed/20260615-complement-subtraction-singular-quadrature.md

@@ -0,0 +1,49 @@
+# Complement-Subtraction Singular Quadrature
+
+## Objective
+
+Record and validate the strategy
+
+```text
+int_{Omega cap B} K(x,y) p(y) dy = int_B K(x,y) p(y) dy - int_{B \ Omega} K(x,y) p(y) dy
+```
+
+for cut-box near-field moments, using existing full-box singular tables for the
+first term and folded decomposition for the smooth complement term.
+
+## Scope
+
+- Document the mathematical route and validity conditions.
+- Identify when the complement integral is smooth and when it still needs a
+  singular/near-singular fallback.
+- Connect the route to existing full-box moment tables and folded fan pieces.
+- Keep this as a design note first; production implementation comes after the
+  classifier/table API is settled.
+
+## Acceptance Criteria
+
+- `docs/nearfield-template-experiments.md` explains complement subtraction as a
+  candidate cut-box singular quadrature route.
+- `docs/nearfield-local-model-catalogue.md` records the smoothness conditions,
+  endpoint-node caveats, and fallback cases.
+- `docs/index.md` remains current if a new standalone document is added.
+- `make dev` passes before handoff.
+
+## Checklist
+
+- [x] Add complement-subtraction derivation and algorithm sketch.
+- [x] Record smooth-complement conditions and failure modes.
+- [x] Validate documentation with `make dev`.
+- [x] Move this plan to `docs/exec-plans/completed/` with outcomes.
+
+## Outcomes
+
+- Added the full-box-minus-complement identity to
+  `docs/nearfield-template-experiments.md` as a candidate cut-box singular
+  quadrature route.
+- Recorded the key condition: the complement folded integral is smooth only when
+  the target is separated from `B \ Omega`.
+- Added routing rules and the open-quadrature caveat to
+  `docs/nearfield-local-model-catalogue.md`, including when to fall back to
+  boundary moments, wedge/cone models, refinement, or target-centered Duffy.
+- Validation passed with `make dev`.