mesh: unstructured all-hex octree mesher

`fieldcraft_mesh::octree::octree_hex_mesh` meshes any closed part with hex8 only:

- an adaptive 3-refinement grid (27-tree) with strong balance and closure, filled with
  conforming node-marking transition templates (Schneiders; checked over all 48 symmetries);
- a core of grid cells kept clear of the boundary (the HybridOctree buffer rule), with
  non-manifold cleanup and a genus check against the part;
- a feature graph from the B-rep (corners, curves, patches) and a partition-first map of the
  core's boundary onto it, then two boundary layers: a padding layer and a pillow per patch,
  so every face boundary and sharp edge is captured by element edges;
- a Garanzha-type untangling and fitting energy (shape term |J|^3/chi, a volume term and a
  soft fitting term, deterministic across platforms), a compass search on the worst
  elements and a certified repair; failures refine the grid near them and rebuild, within
  bounded attempts and growth.

The output passes the certified Jacobian check of every element and a gate that the
boundary encloses the elements' volume; boundary quads carry their B-rep faces. Quality is
reported with the same scaled Jacobian as mesh.quality. Literature notes for each step are in
docs/meshing/literature.md (B1.6-B1.10).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01NmAttHhUZTokgPeEJia8sm

docs/architecture.md

@@ -68,12 +68,21 @@ Rules beyond the layer order:
    its B-rep face tag survives. Then constrained Delaunay refinement to a
    size field, ODT smoothing interleaved as in Tournois et al. 2009, and the Klingner–Shewchuk 2007
    improvement schedule against slivers.
-4. **Hexahedral meshing (the core).** Octree/grid dual all-hex first, the one family that meshes
-   any input validly (Livesu et al. 2021 dual schemes, Pitzalis et al. 2021 refinement, Gao et al.
-   2019 feature projection and padding, Garanzha et al. 2021 untangling). Then hex-dominant by tet
+4. **Hexahedral meshing (the core).** Grid-based all-hex first, the one family that meshes any
+   input validly. `fieldcraft-mesh::octree` (command `mesh.hex.octree`): a 27-tree over the part,
+   refined by curvature, thickness and narrow faces, balanced and cut by the 3-refinement
+   node-marking templates (Schneiders 1996, Ito et al. 2009) into a conforming grid; the core of
+   grid elements inside the part (exact inside test) is cleaned to a manifold boundary; the part's
+   patches, sharp curves and corners are mapped onto it (Gao et al. 2019); one padding layer and a
+   pillow under each patch carry the boundary and capture every sharp curve; the foldover-free
+   energy (Garanzha et al. 2021) with a growing fitting term moves the boundary onto the geometry
+   while every element stays valid; the worst elements are improved, and every element is proven
+   valid by the certified Bernstein Jacobian check (Johnen et al. 2013; Marschner et al. 2020)
+   before the boundary quads are tagged with their B-rep faces. Where a stage fails the grid is
+   refined there and the mesh rebuilt. The dual schemes of Livesu et al. 2021 (fewer elements,
+   concave transitions) are the next upgrade of the transitions. Then hex-dominant by tet
    recombination (Pellerin et al. 2018), then polycube (DualCube labelling) for blocky parts;
-   frame-field/integer-grid-map methods stay research. Validity uses a certified trilinear Jacobian
-   check (Marschner et al. 2020), not corner Jacobians alone.
+   frame-field/integer-grid-map methods stay research.
 5. **Structured hex and face meshing.** Faces get all-quad meshes on shared, prescribed edge
    nodes (`fieldcraft-mesh::quad`): transfinite interpolation for four-sided faces (Gordon and
    Hall 1973), and for free faces a half-resolution constrained Delaunay triangulation,

docs/meshing/literature.md

@@ -531,6 +531,53 @@ Delaunay methods with Voronoi/ODT improvement, then (2) all-hex and hex-dominant
   with conforming templates and no dualization.
 - **Use.** Lets us refine a coarse aligned hex mesh, for example polycube output, as well as an octree.
 - **Code.** `cg3hci/Gen-Adapt-Ref-for-Hexmeshing` is **MIT**: READ OK.
+- **Finding (2026-10).** The reference pipeline chooses transition vertices with an integer linear
+  program (Gurobi) and installs CinoLib's schemes by heuristics that are retried with other
+  parameters when they fail; neither was adopted (see B1.10).
+
+**B1.7 Schneiders, Algorithms for quadrilateral and hexahedral mesh generation (VKI lecture notes,
+2000), §5.** **Verdict: built on (the transition templates of `fieldcraft-mesh::octree`).**
+- **Link.** https://www.robertschneiders.de/papers/vki.pdf (author's copy).
+- **Method.** 3-refinement driven by nodal marks: an element is split by the template of its
+  marked corners, and faces split by their own marks only, so the refinement is conforming.
+- **Limit (stated there).** The 2D templates of the original set make some 3D mark patterns
+  impossible: a hexahedron with seven marked corners has 51 boundary quads, an odd number, so no
+  hexahedral mesh of it exists (Mitchell's parity condition). Concave refined regions therefore
+  need their concave cells refined. The fix is a modified edge rule (an edge with a marked end
+  splits in three) with buffer layers in the face templates.
+
+**B1.8 Ito, Shih, Soni 2009, Octree-based reasonable-quality hexahedral mesh generation using a
+new set of refinement templates.** **Verdict: reference.**
+- **Citation.** IJNME 77(13):1809–1833, 2009. Templates for concave edges of the refined region
+  (paper not obtained; cited after Tong and Zhang 2025).
+
+**B1.9 Tong, Halilaj, Zhang 2024, HybridOctree_Hex.** **Verdict: reference (buffer-zone rule adopted).**
+- **Citation.** H. Tong, E. Halilaj, Y. J. Zhang, *HybridOctree_Hex: Hybrid octree-based adaptive
+  all-hexahedral mesh generation with Jacobian control*, arXiv 2401.05984, 2024.
+- **Method.** Dual of a strongly balanced, paired octree with five templates (a 13-hexahedron
+  frustum per transition face plus four transition-edge templates); a core cleared at the
+  boundary so that the normals of the quads around each core boundary vertex lie in one
+  half-space, then a buffer layer projected onto the surface and optimised.
+- **Code.** `CMU-CBML/HybridOctree_Hex` is **BSD-3-Clause**: READ OK (hard-coded template
+  geometry, not adopted).
+
+**B1.10 Tong, Zhang 2025, MCHex.** **Verdict: reference (next boundary stage to evaluate).**
+- **Citation.** H. Tong, Y. J. Zhang, *MCHex: Marching cubes based adaptive hexahedral mesh
+  generation with guaranteed positive Jacobian*, arXiv 2511.02064, 2025.
+- **Method.** The same 3-refinement templates (B1.7); the boundary cells are cut by marching
+  cubes on a signed distance field, every cut cell's pieces are 3-regular polyhedra, and their
+  midpoint subdivision gives hexahedra with a proven positive Jacobian (Bernstein coefficients) and
+  a boundary that is pillowed by construction; 17 of the 31 cube cases are refined locally first.
+- **Limits (stated there).** Sharp edges and corners are lost (marching cubes smooths them), and
+  the convex-only transitions over-refine. ModelCraft keeps the core-padding-pillow boundary with
+  feature capture for CAD parts; MCHex's cut cells are the candidate for organic shapes.
+
+**Implemented (`fieldcraft-mesh::octree`, `mesh.hex.octree`, 2026-10).** B1.7 templates on a
+27-tree refined by curvature, thickness and narrow faces; a core cleared by the B1.9 rule; the
+feature map of B1.4 (patches first); padding plus a pillow per patch (B1.4 §3.4); the B6.4 energy
+with a fitting term (B1.4 §3.5); the certified check of B6.6 with local repair. The dual schemes
+of B1.5 were not adopted (B1.6 finding); concave refined regions are closed by refinement (B1.7
+limit), so curvature refines one level only.
 
 ---