GameCult.Geometry.Csg/docs/brush-tree-target.md

# Brush tree: target (r3)

Campaign `brush-tree`, owned by the Aetheria/Ghostlight Self. Drafted by Imagination
(`imagination-brush-tree-target-r3`, session `self-2026-10-11-ag2`) on 2026-10-12.
It supersedes r2 (`a7879dad`). This page holds the ends, not the means: no cut plan. The typed
`brush-tree:target:r3` holds the invariants, the not-in-scope list and the canonical implementations;
this page holds why, the authority map, and what is still unknown.

- **Repos:** `GameCult/GameCult.Geometry.Csg` (the tree, the cage evaluator, the kernel, booleans and the
  weld, the scorer), `GameCult/Brokkr` (the agent's hands in Blender), `GameCult/Aetheria` (the first
  consumer).
- **Working branch:** `eureka/brush-tree`.

## The rulings this target rests on

Read them in the mind by id; their operator quotes are the authority, not this page.

- `brush-tree:ruling:hand-cages-enter-the-tree` (Operator, 2026-10-12): a continuous hull's primary
  form is an artist's cage, entered as a tree primitive with its distance defined once in Geometry.Csg;
  detail is cut into its evaluated surface. Automatic cage generation is research and gates nothing.
- `brush-tree:ruling:boolean-cleanup-tighter-curve-wins` (Operator): detail is boolean cuts into the
  evaluated hull, and the weld cleanup is automated by her rule. Her words: "the surface with the
  tighter curve defines the silhouette of the cut, and the spare vertices that come from the flatter
  surface all get merged away."
- `brush-tree:ruling:panel-lines-by-split-boolean-r2` (Operator): a panel line is a through-cut that
  keeps both sides; the stack's one-segment Bevel and Weighted Normal turn the split into a seam. The weld
  rule applies to its seams too. It is the only panel-line method: the operator chose geometry over
  parallax decals (`aetheria-release:ruling:panel-lines-are-geometry`), so hull panel lines are in this
  campaign's scope.
- `brush-tree:ruling:primary-form-is-the-hand-cage` (Defaulted): research generators are scored against
  the hand cage's limit surface, not against a masked or smoothed scan.
- `brush-tree:ruling:representation-per-hull`: cages for continuous bodies like Dexter Quiet, primitives
  for mechanical hulls like the squatter mech ship.
- `brush-tree:ruling:shippable-part-bar`, `:no-unownable-tools-in-loop`, `:openscad-target`,
  `:brokkr-beats-blender-mcp`, `:cli-not-mcp`, and the defaulted rulings on the Blender sink, `run`, docs
  lookup, look files, the per-ship tree `.cc`, persistence through cultcache-rs, the Package path,
  Studio and impostors: unchanged from r2.
- `brush-tree:ruling:pursue-sdf-composition-remeshing` and `:spike-sdf-smin-to-cage`: still in force,
  but narrowed by `hand-cages-enter-the-tree`. SDF composition with automated remeshing is one research
  generator among the cage-connectivity candidates, not the production path.

## What changed from r2, in one paragraph

r2 made the SDF composition the authority for a continuous hull's shape and derived a fitted cage from
it, with the operator's hand cage as the measuring stick. Two findings ended that. The
cage-connectivity pass (`cage-connectivity-prior-art.md` @ 492f83a) found no open method that reaches
a coarse quad cage at the hand cage's quality. Every method starts from a dense mesh, and only
Lavoue 2009 reports output at about 200 faces, with n-gons and high valence accepted. The operator then
ruled her own cages into the tree, and named her detail practice: boolean cuts into the subdivided form,
then a weld she does by a rule simple enough to automate. So in r3 the cage is authored, not derived.
The field leaves the production path for continuous hulls. The open engineering problem moves from
generating connectivity to cleaning booleans on a curved evaluated surface.

## What the pipeline turns a brush tree into

**The tree** is one typed document per ship (`tree-store-per-ship-cc`). Every part, meaning a top-level
branch, declares its representation, `cage` or `kernel`. The declaration is authored, never inferred.
Each part carries a detail list of cutters, each tagged `cut` (remove) or `split` (keep both sides).

**A `cage` part** (continuous body, Dexter Quiet):

1. **Primary form: the cage primitive.** The tree holds control points, faces (quads and triangles),
   edge crease weights and the mirror plane. She authors it in Blender. A `brokkr-ctl` commit reads the
   cage object and commits it as a new revision of the part against its base revision. After that the
   Blender cage object is a projection, and an edit to it is a proposed commit, as for any brush proxy.
   A commit is refused when a crease chain is open and does not end on the mirror plane (her finding:
   open crease paths give "horrible geometry" in Blender's Catmull-Clark).
2. **Evaluated mesh, derived.** Mirror, then Catmull-Clark to the limit surface at a declared level,
   with Blender's crease rules (`one-subdivision-rule`). Who runs this evaluation is question
   `cage-evaluator`.
3. **Detail, derived from cutters.** Each cutter is a kernel brush, lowered alone to a closed mesh.
   - `cut`: the evaluated mesh minus the cutter (gun ports, vents, intakes).
   - `split`: the evaluated mesh minus the cutter, plus the evaluated mesh intersected with the cutter,
     kept as two pieces that share one seam loop. This is how every panel line is made; there is no
     decal path.
   Every intersection loop is then welded by the rule below, and its edges get the bevel weight.
   Detail never moves the cage. Outside a band around each loop, the output's vertices are the evaluated
   mesh's vertices, unchanged.
4. **Shipped stack on the output object:** Bevel (one segment, limited by weight: the crease loops
   plus every cut and split loop), then Weighted Normal. Seams for UVs lie on closed crease loops, part
   boundaries and split loops, so every panel is its own island.

**The weld rule**, as specified for the spike (`boolean-cleanup-prior-art.md` @ 34cccf3 found it
nowhere under any name):

- Along each intersection loop, compare the two surfaces' normal curvature across the loop. The across
  direction is the surface tangent perpendicular to the loop tangent.
- The surface with the larger magnitude owns the loop. The loop's vertices are sampled at the owner's
  resolution and lie on the owner's surface.
- The yielding surface's vertices within one ring of the loop, plus any of its loop vertices that are
  not owner vertices, collapse onto the nearest owner loop vertex.
- A collapse is refused if it flips a triangle or drops the worst angle below a floor. This is the
  Manifold `CollapseEdge` guard (same file, s.1).
- In a `split`, the two pieces weld their shared loop identically, so the seam stays closed vertex for
  vertex.

Undefined so far, and named as the spike's failure cases: equal curvature, saddles where the across
direction changes sign, a loop crossing a crease, and an ownership switch partway along one loop.

**A `kernel` part** (mechanical, the squatter mech ship): unchanged from r2. The polygon kernel builds
exact planar faces with scoped booleans, a one-segment bevel on hard edges, face-weighted normals and
UVs from each brush's declared charts. Its cutters use the same boolean and weld as a cage part's
detail.

**Both** reach Aetheria the same way (`lowered-hull-through-package`): an object in the ship file,
exported by the existing Package. Nothing reads an evaluated mesh, cut mesh or render back as truth.

### Distance for a cage primitive, stated honestly

`one-distance-per-primitive` holds for the cage. Its distance is defined once in Geometry.Csg as the
unsigned distance to the limit surface, signed by winding number. The cost is the honest part.

- The limit surface has exact evaluation: Stam 1998, OpenSubdiv `LimitStencilTable`, and run 3's
  `X = S c`, linear in the cage. A closest point on it comes from a Newton search
  (Marinov and Kobbelt 2005). So the distance is computable (`subd-cages-mixed-hulls-and-open-kernels.md`
  @ 390db63, s.1).
- No source gives a **cheap distance bound** away from the surface, that is, a Lipschitz-safe lower
  bound usable for sphere tracing, Newton projection from afar, or smooth-min composition with other
  primitives. The r1 field assumed one for every primitive.
- So the cage primitive is refused inside any field composition (smooth union, hard `max` crease) and in
  sphere tracing (`no-silent-skips`). Its distance serves measurement only: heatmaps, scores and fit
  residuals, evaluated near the surface from a dense limit sample. Nothing in the production path needs
  more. A bound, if one is ever needed, is research.

### Where SDF composition still has a role

- **As a research generator.** An SDF program with smooth-min, remeshed and refit to a cage (runs 4-7),
  is one candidate source of cage connectivity. It is scored like any other candidate.
- **As the kernel brushes' distance.** `field.rs` stays the one distance for kernel primitives, for
  heatmaps and scores.
- **Not as a part representation.** No production part is a `field` part, and smooth union leaves the
  production vocabulary. A generator's output, if it ever meets the bar, enters as a cage, and so does
  every continuous hull.

### Authority map (r2 to r3)

- **Owner of a continuous hull's primary form:** the cage primitive in the tree. The field is no longer
  an owner. The cage is no longer derived from the field; it is authored and committed.
- **Inputs:** the operator's cage object in Blender (through the commit primitive only), the part's
  cutter brushes.
- **Outputs:** the lowered part object (evaluated, cut, split and welded mesh, with bevel weights), and
  scores.
- **Derived state:** the evaluated mesh, the cutter meshes, the cut mesh, UV islands, heatmaps, renders.
  These are cache only, regenerated per revision.
- **Forbidden writers:** the SDF program, the cage fitter and any remesher writing a production cage.
  They write research artifacts only, and a research cage enters only by a commit like any other. Also
  forbidden: Blender's Boolean modifier, or hand edits to the lowered object, deciding the shipped
  detail.
- **Shared paths:** the operator's cage edit, a model's script edit and a research generator's
  candidate all enter through the one commit primitive. Cut-in and split use one boolean and one weld.
  Kernel parts' cutters use the same boolean.
- **Deletion line:** r2's "cage connectivity generator" and "cage fitter" leave the production owner
  table and become research ports. `field` leaves the per-part representation enum. Smooth union is not
  added to the tree vocabulary.

### Owners, inputs, outputs, mock points

| Owner | Inputs | Outputs | Mock point |
|---|---|---|---|
| Tree (Geometry.Csg) | text or a cage object, through the one commit primitive | typed tree revision | in-memory store |
| Cage evaluator | cage primitive, level | evaluated mesh (mirror applied) | trait; Blender's output as the oracle (`cage-evaluator`) |
| Cutter lowering | cutter brush | closed cutter mesh | the kernel, per brush |
| Boolean | evaluated mesh, cutter mesh, `cut` or `split` | pieces, intersection loops with both sides' faces | trait; kernel chosen by the spike |
| Weld | pieces, loops, the two surfaces' curvature | welded pieces, loop edges with bevel weight | pure mesh math |
| Kernel | kernel part | mesh with per-face brush and surface ids | trait |
| Scorer | two meshes | the bar's numbers | pure mesh math, no Blender |
| Research generators | a reference (scan or SDF program) | candidate cage | port; never a production writer |
| Brokkr bridge | intents from `brokkr-ctl` | receipts, cage reads, objects in the ship file | directory store or loopback, per `blender-transport` |

## The hand cage

**What it is** (`docs/research/dexter-quiet-cage/` @ d426f86, note @ 4b55c58): half hull of 29 vertices
and 25 faces (19 quads, 6 triangles); about 50 faces mirrored. Nine creases form one chain that the
mirror closes into a loop round the wing rim. At level 3 it evaluates to 3,154 vertices and 3,152 quads,
with 31 irregular vertices and no UVs. Against the scan (vertex to nearest vertex, % of the 1.492
diagonal): cage to scan mean 0.88, p95 2.04, max 3.11; scan to cage mean 1.29, p95 4.12, max 6.03.
Those numbers mix her declared liberty with detail the cage omits by design. They describe the
reference; they are not a bar any production output is held to.

**It is the production primary form, not only the yardstick.** Production fidelity is by construction:
away from detail loops, the shipped part is the cage's limit surface.

**Research generators are scored against it** (`primary-form-is-the-hand-cage`). A candidate's
evaluated limit surface is compared with the hand cage's (Mirror, limit, no Bevel) vertex to nearest
vertex both ways, at half to double 3,154 vertices, and by three-axis silhouette IoU. Every measurement
reports the candidate's source against its reference and the candidate cage against its own source
separately, besides the end-to-end number; run 7 lost a spike to an unattributed number. The scan is the
reference only for the hand cage's own recorded liberty. A candidate is interesting when it is no worse
than the hand cage's own spread and meets the cage bar: at most about 200 faces (4x), quads and
triangles only with at most 24 % triangles, closed creases, and a watertight level-3 limit mesh with at
most 62 irregular vertices. Meeting the bar makes a candidate committable as a cage. It gates nothing
else.

## Not yet known (owed before or during the next cuts)

- **The weld rule's behaviour on real geometry.** It has never been run. The spike brief is
  `spike-boolean-weld.md` (Self's scratch); its measures and failure cases decide whether the rule ships
  as stated, needs a tiebreak, or needs the cutter tessellated to the hull's density.
- **Which boolean kernel:** Manifold through `manifold-csg` (Apache-2.0, C++ underneath, with provenance
  and its own degenerate cleanup), boolmesh (pure Rust, MPL-2.0, released 2026-10-11, 0 % doc coverage),
  or an extension of the crate's own kernel. The spike measures the first two; the crate's kernel is
  planar-convex today.
- **Who evaluates the cage** for the lowering: question `cage-evaluator`.
- **Split pieces' interior caps:** a through-cut of a closed hull leaves cross-section caps inside both
  pieces. Whether they are kept (closed pieces, hidden triangles) or dropped (open pieces) depends on how
  Bevel and Weighted Normal treat the open boundary. The spike probes it.
- **How a `cage` part and a `kernel` part meet** on one hull. Under r3 a union with the same boolean and
  weld is the natural candidate, but nothing has measured it.
- **Text for a cage part.** It prints as a polyhedron-like `subdivision_cage(points, faces, creases,
  mirror)`. OpenSCAD would render the cage's control polyhedron, not its limit surface, so cage parts sit
  outside the "OpenSCAD renders it the same" half of `text-round-trips`, as smooth-min parts did in r2.

## Research it rests on

All in GameCult.Geometry.Csg `docs/research/` on `eureka/brush-tree`:

- `dexter-quiet-cage/` @ 4b55c58: the reference cage, the primary-form note, her screenshots (cage files
  @ d426f86).
- `cage-connectivity-prior-art.md` @ 492f83a: no open method reaches a coarse quad cage at this quality.
- `boolean-cleanup-prior-art.md` @ 34cccf3: no named precedent for the weld rule; Manifold's collapse
  guard; Adaptive Mesh Booleans' failure modes; ownable kernels.
- `detail-on-subd-prior-art.md` @ c513992: cut into the evaluated mesh is the only option that keeps the
  cage independent and regenerable; support loops grow the cage.
- `sdf-authoring-text-prior-art.md` @ 6a575d2: no SDF tool round-trips a typed tree through text.
- `subd-cages-mixed-hulls-and-open-kernels.md` @ 390db63: limit evaluation, closest point, no cheap
  bound.
- `shippable-bar/`, `mesh-probe-run1/` to `mesh-probe-run7-im-field/`,
  `openscad-evaluators-and-csg-export.md`, `primitive-seams-and-sdf-bevel-meshing-prior-art.md`,
  `brush-surfaces-and-sdf-bricks-prior-art.md`, `octahedral-impostors-prior-art.md`: as in r2.