@woosh/meep-engine 3.56.0 → 3.58.0

package/src/generation/foliage/ANNUAL_SHOOTS_BRIEF_2026_10_25.md

@@ -0,0 +1,220 @@
+# Annual Shoots: Leaves on Real-Sized Shoots
+
+## Problem
+
+The oak's leaf cards are a median 0.90 m long (species card 0.95 x 0.85 m). Each draws 5 leaves at about 0.3-0.4 m
+against a real 6-12 cm, and each moves as one rigid plate, so wind displaces large patches of the crown together. The
+cards are big because they stand in for twigs the skeleton never grows: the oak's leaf carriers (generator 2) are a
+median 1.24 m long, where a current-year oak shoot averages 5.5 cm.
+
+Shrinking the cards alone thins the crown: at 0.25 m cards the oak's leaf area falls from 163 to 45 m^2 and its side
+opacity from 0.75 to 0.33, because the density rule ties leaf area per metre of carrier to card size. (Both opacities
+came from a raster window that clipped the crown; see "Landed".)
+
+## Sources
+
+**[BB2000]** Buck-Sorlin, G.H. & Bell, A.D. (2000). Models of crown architecture in *Quercus petraea* and *Q. robur*:
+shoot lengths and bud numbers. *Forestry* 73(1): 1-19. Peripheral branches at mid-crown of two *Q. petraea* (70-120
+years) and one *Q. robur* (30 years); no difference found between the species in bud patterns or length distributions.
+
+| Quantity | Value | Where |
+| :--- | :--- | :--- |
+| Extension unit (one season's shoot) length, all oaks | mean 5.5 cm, median 3.8 cm, sd 5.0 | Table 4 |
+| Same, the *Q. robur* | mean 7.2 cm, median 5.8 cm | Table 4 |
+| Longest shoot by branching order | 30 cm (order 1) to 8 cm (order 4) | p. 9 |
+| Modal length | 3 cm (order 1) to 2 cm (order 4) | p. 9 |
+| Length distribution | negative binomial, orders 1-2 (p = 0.58, 0.60); Poisson with mean - 1, orders 3-4 | p. 10-11 |
+| Terminal shoot length | 11.7 +- 6.1 cm, about 1-31 cm | p. 11-12 |
+| Lateral lengths, subapical zone (0.8-0.99) | means 3.4-9.0 cm | p. 11 |
+| Lateral lengths, median zone (0.3-0.55) | means 3.4-7.0 cm, at most about 15 cm | p. 11 |
+| Where laterals grow out | none below 0.3; 23.3% at 0.3-0.55; almost none at 0.55-0.8 (female flowers); 71.4% at 0.8-0.99 | p. 11, Fig. 7 |
+| Share of all new shoots | subapical-zone laterals 44.4%, median-zone laterals 14.4% | p. 11 |
+| Subapical buds (pseudo-whorl under the terminal bud) | almost always 4 | p. 7, 17 |
+| Median buds | modal 6-10, range 0-21; length = 0.98 m - 2.7 cm (all orders) | p. 8, Table 5 |
+| Shoot types | spring flush 92.7%, Lammas 5.2%, sylleptic 2.1% | Table 3 |
+| Current shoot diameter | d = 0.27 + 0.02 l (cm), never above 5.5 mm | Table 7, p. 13 |
+| Branching orders on a branch | up to 7 | p. 15 |
+
+Subapical and median buds each sit in the axil of a leaf; basal buds have none (footnote 3, p. 5).
+
+**[BB1998]** Buck-Sorlin, G.H. & Bell, A.D. (1998). A quantification of shoot shedding in pedunculate oak (*Quercus
+robur* L.). *Botanical Journal of the Linnean Society* 127: 371-391. Everything shed in one year by one free-standing
+*Q. robur* (about 14 m, 40 years).
+
+| Quantity | Value | Where |
+| :--- | :--- | :--- |
+| Shoot fragments shed in a year | 14,767 (13,185 actively shed, 1,582 broken) | p. 376 |
+| Age of shed fragments with current growth | 21.3% current, 33.8% 1 year, 21.6% 2 years, 23.3% 3-10 years | p. 382-383 |
+| Unbranched / a single extension unit | 70.5% / 35.8% (live); 90.7% / 66.6% (dead) | p. 381 |
+| Longest extension unit under 5 cm | 83.7% | p. 377 |
+| Most at risk | the highest branching orders; short shoots whose terminal bud seldom extends the axis | p. 388 |
+| Where | shoots up to about 10 years old: the outer metre of the crown | p. 388 |
+| How | always at the base of a module (the axis from one bud), never along it | p. 388 |
+| Net effect | "the surplus of peripheral shoots apparently produced every year is mostly thinned out within 2 years" | p. 388 |
+
+**[W1989]** Wilson, B.F. (1989). Tree branches as populations of twigs. *Can. J. Bot.* 67: 434-442, as cited in
+[BB2000] p. 15: twig populations fluctuate but show no long-term change in numbers.
+
+**[TP2015]** *Tree Physiology* (2015) table comparing *Q. robur* and *Q. faginea*: 11.2 +- 0.9 leaves per shoot. The age
+of the trees is not stated.
+
+## Derived
+
+- **Shoots per mother shoot per year: about 2.65.** On [BB2000]'s branch o1b1, laterals were 44.4% + 14.4% of new
+  shoots, which is 71.4% + 23.3% of laterals, so laterals were 62.2% of all new shoots and terminals 37.8%. If every
+  mother shoot grew its terminal bud, each yielded 1 terminal, 1.17 subapical laterals (29% of its 4 subapical buds)
+  and 0.38 median laterals.
+- **Survival: about 38% of new shoots a year.** A population that holds steady [W1989] keeps 1 / 2.65 of what it
+  produces, which matches "mostly thinned out within 2 years" [BB1998].
+- **Leaves per shoot: 4 + median buds**, 9-14 for typical lengths, against 11.2 in [TP2015].
+
+## Decisions
+
+Alex's direction (2026-10-25): appearance, flexibility and working well with the other parameters come before
+real-world accuracy.
+
+1. **The leaf-bearing unit is the current-year shoot.** A deciduous oak's leaves sit on this year's growth only. One
+   card per current-year shoot draws that shoot's leaves crowded at its tip (a new `rosette` leaf arrangement in the
+   atlas). The card covers the shoot plus its leaves, about 0.2 m for the oak.
+2. **The peripheral twig system is grown year by year** in a pass after the framework, from an explicit rule list,
+   `TreeSpeciesConfig.shoot_rules` (`ShootSystemRule`: carrier generator, shoot generator, years, vigour, and the
+   demography above as defaults). The shoot generator is an ordinary `BranchGeneratorConfig` for the twigs' look. A
+   module (the axis grown from one bud) is one skeleton branch, one segment per year, so shedding removes a module at
+   its base, as [BB1998] observed.
+3. **Every year**, each living module adds a terminal extension unit, and each unit grown the year before bursts its
+   buds: about 1.17 laterals in its subapical zone and 0.38 in its median zone. Lengths are drawn from [BB2000]'s
+   distributions, shorter with branching order.
+4. **Shedding** keeps, of each year's new shoots, the expected `vigour / 2.65` share, taking the highest-order and
+   shortest first [BB1998]. A deterministic dither keeps counts close to their expectation, so the crown does not
+   swing with seed luck.
+5. **Density closure (the one unsourced part).** Steady state fixes how a population changes, not how big it is. Each
+   carrier's own last `years` of growth seeds the system: its extension units are laid back from its tip, and each
+   one's buds start lineages. `vigour` (default above 1, a growing crown) is the authored knob that sets how full the
+   crown is; at 1 the periphery holds steady. LAI is reported as a check, not fitted.
+6. **Leaves only on current growth** is keyed on a runtime fact: the skeleton records where each module's current-year
+   unit starts. A carrier without that record keeps today's density rule, so every other preset is unchanged.
+7. **Levels.** All modules take the carrier's level + 1, the twig layer, so the LOD chain and the wind rig treat them as
+   one layer. Branching order is tracked inside the pass only.
+8. **Joints** come from the existing derived placement. Each current shoot carrying a card will likely take its own
+   joint, which is the leaf-scale motion this work is for. The `max_joints` safety net rises from 4,096 to 16,384 so
+   the oak does not reach it; that number is chosen.
+
+Not modelled: Lammas and sylleptic shoots (7.3% of shoots), male and female short shoots, and shedding of shoots older
+than the simulated `years`.
+
+## Plan
+
+1. `ShootSystemRule` config with [BB2000]/[BB1998] defaults, wired into `TreeSpeciesConfig`.
+2. `tree_skeleton_grow_shoots`: the demography as a pure, seeded function producing module records, then written into
+   the skeleton before the pipe-model pass, with radii from [BB2000] Table 7.
+3. Foliage: one card per current-year shoot; the `rosette` arrangement; segment mechanics take the same leaf area.
+4. The oak preset grows shoots on generators 2 and 4, with cards sized for 6-12 cm leaves.
+5. Specs: outgrowth positions and counts, steady survival at vigour 1, length means by order, leaves only on current
+   growth, mechanics leaf area equal to the cards'. Mutation-test them.
+6. Measure the oak (cards, joints, leaf area, opacity, triangles, generation time) and look at it in the playground.
+
+## Landed
+
+Built as planned, with these differences.
+
+- **Pass order.** The shoots are written after the pipe-model pass, not before. The pipe pass would otherwise thicken
+  the framework under shoots already placed against it, and they would end up inside its wood. Twig radii are not
+  left to the pipe model: each axis's radius is computed bottom-up from [BB2000] Table 7. Each unit takes the
+  largest of:
+  - its current-shoot diameter, aged by one year per unit below the tip;
+  - the pipe area of what it carries;
+  - 1 / 0.82 of its thickest lateral.
+
+  The radius floor is 1.9 mm, the thinnest tip the bark mesher draws cleanly, and the framework's own floor in
+  `tree_skeleton_grow.spec.js`. A carrier's young end is thickened the same way, then swept so it still tapers.
+- **No twig grows through wood.** All carriers are thickened first. Then each axis's path is computed and tested
+  against a spatial hash of the framework (`FrameworkHash`). An axis that would cross the framework is a blocked bud
+  and does not grow, nor does anything on it. Its own junction with its mother is exempt. Measured at seed 1337: 286
+  of 2,639 modules are blocked, and 195 more lose their mother that way.
+- **Plagiotropic mothers** knock out ventral buds as the framework's do: a bud turns by the golden angle, up to 5
+  times, until it clears the downward cone.
+- **Each segment now bends under its own load.** Before, only what a segment carried loaded it, so a twig of one unit,
+  carrying its card at the tip, had zero compliance. A segment's own drag and mass now act at L / 6 from its base.
+  Together with the twig layer, this moved the oak's boughs, so `elastic_modulus` was refitted from 3.33e7 to 4.55e7.
+  Over 12 seeds, the median primary bough of the oak, bent as one cantilever, is back at its old compliance (ratio
+  0.999). Against their sway before, maple boughs move 1.12x, pine 1.14x and birch 1.04x.
+- **The oak preset**, tuned for its look:
+  - Its secondary branches (generator 2) are 1.4x longer, with 12 to a bough where there were 8.
+  - Shoot rules run on generators 1, 2 and 4, with `years: 10` and `vigour: 1.3`.
+  - The cards are `TriStarCluster` cards of 0.17 x 0.17 m. Each carries a `rosette` of 11 leaflets.
+- **`max_joints`** rose to 16,384, as planned.
+
+**Measured, oak at seed 1337, master (6aff5265e) against now:**
+
+| | master | now |
+| :--- | ---: | ---: |
+| current shoots | none | 2,158 |
+| cards | 842 | 2,261 |
+| median card length | 0.90 m | 0.17 m (p10 0.14, p90 0.20) |
+| skeleton nodes | 766 | 9,860 |
+| wind joints (1 cm) | 447 | 5,703 |
+| leaf area | 164 m^2 | 93 m^2 |
+| LAI over the crown's top silhouette | 4.0 | 3.2 |
+| side opacity over the silhouette | 0.64 (40.0 m^2) | 0.49 (26.7 m^2) |
+| top opacity | 0.74 (40.8 m^2) | 0.61 (29.3 m^2) |
+| generation, best of 8 | 291 ms | 441 ms |
+
+The playground draws the oak at LOD 0 in 82,761 triangles.
+
+**Opacity is set by the framework's gaps, not by the leaf.** The crown is more see-through than master's. Each leaf now
+sits on its own twig, and the gaps between boughs show. Raising the leaf does little:
+
+| years : vigour | shoots | joints | leaf | LAI | side opacity |
+| :--- | ---: | ---: | ---: | ---: | ---: |
+| 10 : 1.3 (preset) | 2,158 | 5,703 | 93 m^2 | 3.2 | 0.49 |
+| 12 : 1.3 | 3,042 | 8,066 | 129 m^2 | 4.2 | 0.55 |
+| 10 : 1.5 | 4,919 | 10,455 | 202 m^2 | 6.7 | 0.62 |
+| 10 : 1.7 | 9,442 | 15,719 | 372 m^2 | 12.1 | 0.67 |
+
+At vigour 1.7, four times the leaf area gives 0.67. A fuller crown is a framework change: more or longer boughs.
+
+**Correction (2026-10-26).** The first version of these tables came from a probe whose raster window was a fixed 14 m
+square. It clipped the oak's top view, and master's side view too, whose 0.9 m cards reach past it. With a window
+fitted to the leaves, master's oak reads side 0.64 over 40.0 m^2, top 0.74 over 40.8 m^2, LAI 4.0 (first stated as
+0.75 over 33.9, 0.83 over 21.9 and 7.5), and the oak with shoots LAI 3.2 (first stated as 5.2, "an oak crown's"). It is
+lower than master's, not equal to a real crown's.
+
+**Other presets** keep their cards. They have no `shoot_rules`, so they change only through the new self-load and
+modulus. Joints at seed 1337, master against now: pine 525 to 544, birch 186 to 185, willow 514 to 513, maple 313 to
+332, spruce 423 to 435, palm 65 to 65, shrub 46 to 54, fern 26 to 24. Their card counts are unchanged.
+
+**Specs.**
+- **Demography:** `shoot_demography.spec.js`, 6 specs.
+- **Shoot layer:** `tree_skeleton_grow_shoots.spec.js`, 10 specs:
+  - The twig layer and its records.
+  - The framework is untouched by the shoot rules.
+  - One card per current shoot, anchored on its current unit.
+  - A single-unit twig bends.
+  - Determinism.
+  - Twig against mother radius.
+  - Year-old wood against Table 7.
+  - Every atlas variant is used.
+  - A carrier's young end and its tip against Table 7.
+- **Mutation testing:** 11 mutants, all killed:
+  - zone widened;
+  - no shedding;
+  - no order shortening;
+  - no framework avoidance;
+  - no plagiotropic knockout;
+  - no self-load;
+  - leaves along the whole carrier;
+  - no carrier thickening;
+  - no twig radius floor;
+  - no ageing;
+  - one maturity for every card.
+- **Existing specs:**
+  - `tree_skeleton_grow.spec.js` allows twigs Table 7's slenderness, up to 50, against 26 for the framework.
+  - Its interpenetration check skips twig against twig, and twig against its mother within one segment of the
+    junction.
+  - The density and reach specs moved from the oak to the maple, which still has density-rule cards.
+
+**Not done.**
+- Lammas and sylleptic shoots.
+- Shedding of shoots older than `years`.
+- Shoots for the other broadleaf presets. Maple and birch would take the same rules once their own shoot lengths are
+  sourced.

package/src/generation/foliage/CROWN_FILLING_BRIEF_2026_10_26.md

@@ -0,0 +1,172 @@
+# Crown Filling by Light
+
+Follows `SHOOT_SYSTEMS_ALL_SPECIES_BRIEF_2026_10_26.md`, which grew every woody species' twigs from sourced shoot
+demography and left the crowns barren.
+
+## Problem
+
+Each carrier grows its twig system alone for a fixed number of years, at a fixed vigour (net shoots a shoot leaves a
+year), with shoots shed by a chosen rank of age, order and length. Nothing in that knows where the crown is empty or
+crowded. Seed 1337, against master's metre-long cards:
+
+| preset | leaf area, master -> now | side opacity, master -> now |
+| :--- | ---: | ---: |
+| birch | 45 -> 2 m^2 | 0.44 -> 0.10 |
+| willow | 241 -> 7 m^2 | 0.67 -> 0.18 |
+| pine | 174 -> 24 m^2 | 0.69 -> 0.33 |
+| spruce | 161 -> 20 m^2 | 0.57 -> 0.34 |
+| maple | 150 -> 63 m^2 | 0.66 -> 0.43 |
+| oak | 164 -> 113 m^2 | 0.64 -> 0.51 |
+
+**The target** is the US Forest Inventory's crown ratings of 15,011 leaf-on trees seen from the side (Randolph 2006,
+USDA GTR SRS-94, Tables 1-4). Healthy crowns block a mean 45% of their outline (oaks, maples, birches 46-51%), and their
+foliated parts let about 15% of skylight through (interquartile 10-20%). From below, open-grown crowns intercept 0.75-0.92
+of light (Nowak 1996, Forest Science 42: 504-507, Table 2).
+
+## Principle
+
+A real crown is full because it grows until it shades itself. Shoots in light make more shoots; shoots in shade make
+fewer, and an axis in deep shade dies. The papers already in hand measure exactly this:
+
+- **Spruce.** Rb, the net shoots a shoot leaves a year, rises with the light a branch receives: about 0.65 at
+  4-5 mol m^-2 d^-1 to about 2.2 at 10-12, against 37.1 under open sky, so 0.12 to 0.30 of full light. Below 1 in deep
+  shade, a branch's foliage shrinks with age (Niinemets & Lukjanova 2003, New Phytol. 158: 75-89, Fig. 5b, Table 1).
+- **Pine.** Branching stops at a relative light of 0.20-0.25 (Ilonen et al. 1979, Silva Fennica 13: 319-321). A shoot
+  with no needles left is dead (Kellomäki & Kurttio 1991, p. 104).
+- **Birch.** The bud population grows 1.52 a year in the top of the crown, 0.999 at its bottom (Maillette 1982, J.
+  Appl. Ecol. 19: 219-238, Table 1).
+- **Red maple.** Shaded branches die, so foliage stays at the crown's periphery (Wilson 1966, Harvard Forest Paper 14,
+  p. 19).
+
+So vigour becomes a function of light, and the crown's leaf area becomes an outcome: growth stops where the crown has
+shaded its own interior to the light at which shoots no longer replace themselves.
+
+## Design
+
+The framework (trunk, boughs and branches from the generator graph) stays as it is. Everything younger grows by light.
+`tree_skeleton_grow_shoots` is rebuilt around one tree-wide simulation:
+
+1. **One season loop for the whole tree.** Every carrier's twig system grows in the same loop, so the systems compete
+   for the same light. `years` and the light response move from the per-carrier `ShootSystemRule` to a species-level
+   `ShootGrowthConfig`. The rules keep what differs by carrier: bud zones, lengths, orders, angles.
+2. **Shoots have geometry as they grow.** Each new unit's start, heading and end are fixed in its season (tropisms,
+   zigzag, insertion and phyllotaxis, as the writer does today), so light can be measured where the leaves are. The
+   writer then only turns the surviving axes into skeleton branches.
+3. **The light field.** Each season, the leaf area of every leaf-bearing unit is deposited in a voxel grid over the
+   crown.
+   - **Light at each voxel:** relative irradiance from the sky by Beer-Lambert, `exp(-G Omega LAD path)`.
+   - **Extinction:** `G = 0.5`, the projection of a spherical leaf angle distribution.
+   - **Clumping:** `Omega` is the species' shoot clumping; Scots pine about 0.58 from its silhouette-to-area ratio of
+     0.146 (Smolander, Stenberg & Linder 1994, Tree Physiol. 14: 971-980), broadleaves 1 for want of data.
+   - **Sky:** a standard overcast sky, radiance `(1 + 2 sin elevation) / 3` (Moon & Spencer 1942), weighted for a
+     horizontal receiver as hemispherical photographs measure it.
+   - **Directions:** lattice directions, so each is one sweep of the grid. The cost is grid cells times directions,
+     whatever the leaf count.
+4. **Vigour follows light.** An axis in relative light `Q` leaves `Rb(Q)` net shoots a year. `Rb` rises linearly from 1
+   at the species' compensation light to its full vigour at its saturation light, flat above, and falls below 1 under
+   compensation. A season's new shoots on an axis survive at `Rb(Q) / yield`, its gross yield of new shoots. The shoots
+   kept are the best lit, with a dithered count so the total is exact on average. This replaces the chosen
+   age/order/length rank.
+5. **Death by shade is not a separate rule.** A terminal that is shed takes its axis with it [BB1998], and in shade the
+   terminal is shed. A shaded branch thins and dies as `Rb < 1` makes it.
+6. **Long enough to fill.** `years` covers the time the periphery takes to reach the light limit, so crown fullness is
+   set by light, not by when the simulation stops. The equilibrium is measured, not assumed.
+7. **Wood.** The [BB2000] Table 7 diameter holds only for current and year-old units, the shoots it was measured on.
+   Older wood is the pipe model plus what its laterals need where they join, for twig and carrier alike.
+8. **Framework avoidance** is tested when a unit grows, as now.
+
+**Per-species light response:**
+
+| preset | compensation `Q` | saturation `Q` | full vigour | source |
+| :--- | ---: | ---: | ---: | :--- |
+| spruce | 0.16 | 0.30 | 2.19 | [NL2003] Fig. 5b line through (0.12, 0.65), (0.30, 2.2); Table 1 max |
+| pine | 0.22 | 0.30 | 1.867 | Ilonen 1979 (0.20-0.25); saturation spruce's; [NL2003] Fig. 2 |
+| birch | 0.22 | 0.30 | 1.52 | top of crown [M1982]; light points pine's |
+| oak, maple, willow, shrub | chosen | chosen | chosen | none found |
+
+**Gaps.** Only spruce has a measured light curve. Pine has its compensation point. The others borrow the curve's
+shape, and that is marked in the code.
+
+## Measuring
+
+- **Fullness:** crown density and foliage transparency against Randolph 2006, and interception from below against Nowak
+  1996, measured with the crown opacity benchmark being built in a sibling session. Until that lands, the scratchpad
+  probe stands in.
+- **Specs, from the principle:**
+  - In a uniform light field, the twig population changes by `Rb(Q)` a year.
+  - Shoots in shade die.
+  - Leaf area stops growing with `years` once the crown is full.
+  - Doubling `years` past equilibrium changes leaf area little.
+  - A crown with more framework does not end up with proportionally more leaf.
+
+## Plan
+
+1. `ShootGrowthConfig`; the rule loses `years` and `vigour`.
+2. `shoot_light_field`: voxel leaf area, sky sweeps, irradiance query. Specs against Beer-Lambert in closed form.
+3. The tree-wide simulation with geometry, light-driven survival, framework avoidance at growth.
+4. The writer and radii on the simulated axes.
+5. Presets: light response per species.
+6. Specs green (including the willow seam and the season order), mutation-tested.
+7. Measure every preset against the targets; look at each in the playground.
+
+## Landed (2026-10-26, uncommitted)
+
+As designed, plus what building it turned up:
+
+- **The simulation:** `shoot_systems_simulate` runs every carrier's twig system in one season loop against a
+  `ShootLightField` (leaf-area voxels of `light_cell`, 17 lattice sweeps of the overcast sky, matches Beer-Lambert in
+  closed form within 0.01). Each season: extension with tropisms, short-shoot survival `short_shoot_survival x
+  min(1, Rb(Q))`, bursts, syllepsis, shedding to `Rb(Q) / yield` (rank: log keep share, age, order, length, jitter),
+  the cascade of a shed mother, then the wood.
+- **Dynamic girth** (Alex's pick over a forecast radius): `ShootGirth` thickens the wood each season with what it
+  carries, never thinning: the pipe model at the species' `pipe_model_exponent` over the shoots' Table 7 radius, Table
+  7 for a unit of its age, and `1 / SHOOT_LATERAL_RADIUS_RATIO` of a lateral where it joins, on twigs, carriers and the
+  framework above them. A shoot grows only where it clears today's wood; a shoot the wood has grown into by the end
+  of a season dies with all it carries. The framework hash (`ShootFrameworkHash`, allocation-free) is rebuilt each
+  season.
+- **Framework ages** come from the leader growth: a branch is born when its parent's tip passed its seat, so a carrier
+  carries `round(age)` units over its whole length.
+- **Cards follow leaves:** a unit carries its leaves (`leaves_per_unit + leaves_per_metre L`, times `leaf_survival` at
+  its age) over the leaves one card draws (`foliage_card_leaf_count`), dithered; short shoots get their own rosette
+  tiles (`foliage_atlas_tiles.js`).
+- **Skinning seats** (found by the willow seam spec once twigs grew on twigs): where more than four joints meet, the
+  four kept are those that leave the seat least far from where all of them would carry it, and a dropped joint folds
+  into the kept one that carries the point most alike. "How far apart" is each joint on the path between them turning
+  by its reference-wind rotation about its pivot (`TreeSkeleton.joint_rotation`, written by
+  `tree_skeleton_assign_skin_joints`). Willow seats over the 1 cm tolerance: 178 by weight-then-hops, 6 by
+  weight-times-hops, 0 now.
+
+**Specs restated from their principle** (each mutation-tested red):
+- interpenetration: a child may meet its mother's wood only in the crotch, the run of its first segments that still
+  lie in her wood, and a child whose tip is in her wood is buried; twigs no longer get a year-old-girth allowance. The
+  spec finds candidate pairs by a grid (it was n^2 and timed out at 90k segments).
+- conifer tiers: they come from the whorls (spiral boughs: empty bands 5.4x fewer on spruce, 3.9x on pine);
+  plagiotropism no longer moves them (0.95x).
+- spire: the leader's top unit, clothed in at least half the needles a unit of `leader_growth` carries.
+- autumn order: the leaves that fell were more exposed and younger than those kept, by a quarter of the summer spread.
+- shoot demography: from `tree_skeleton_grow`'s records (zones, the four-bud whorl, ancestry, light response).
+
+**Measured at seed 1337** with master's `foliage_measure_leaf_area` and `tree_crown_opacity` (copied in for the run):
+
+| preset | leaf m^2 | crown LAI | side density | side transparency | below density | below transparency | generate |
+| :--- | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
+| oak | 90.9 | 3.11 | 0.51 | 0.44 | 0.53 | 0.38 | 0.9 s |
+| pine | 35.0 | 1.60 | 0.38 | 0.60 | 0.41 | 0.53 | 1.0 s |
+| birch | 64.5 | 6.59 | 0.56 | 0.38 | 0.80 | 0.15 | 2.5 s |
+| willow | 136.3 | 3.68 | 0.69 | 0.30 | 0.71 | 0.25 | 2.0 s |
+| maple | 36.3 | 1.42 | 0.33 | 0.55 | 0.32 | 0.43 | 1.1 s |
+| spruce | 117.8 | 4.44 | 0.36 | 0.28 | 0.45 | 0.25 | 3.1 s |
+| shrub | 57.8 | 4.65 | 0.62 | 0.34 | 0.77 | 0.18 | 0.3 s |
+
+(generate: skeleton and cards, `probe_crowns.mjs`.) FIA's targets are density 45-51% and transparency about 15%
+[Randolph 2006].
+
+**Open, measured:**
+- Every preset is far more see-through than FIA's 15%; only oak's density is in range.
+- **The shrub was barren** at a chosen Rb of 1.3 (2.1 m^2, crown LAI 0.18): light did not limit it, the stool's young
+  stems seeded few lineages, and 1.3 of a gross yield of 7.17 kept under one burst shoot in five even in full sun. No
+  net shoot yield was found for hazel (Grisafi et al. 2024 report one season's bud fates; orchard LAI 0.80-2.86,
+  Oeztuerk et al. 2018, is per ground area). Alex's pick: full-sun vigour is the gross yield the rule's Grisafi
+  numbers give (`shoot_expected_yield`, 7.17), so only shade sheds hazel shoots. Light saturates the crown from about
+  2.8 up. The shrub row above is measured at that vigour; master's leaf-area and opacity specs pass on this tree.
+- Engulfment took birch from 115 to 83 m^2 (probe), willow from 167 to 157, spruce from 140 to 121.

package/src/generation/foliage/CROWN_FULLNESS_BRIEF_2026_10_26.md

@@ -0,0 +1,86 @@
+# Crown Fullness: what keeps the crowns bare
+
+Alex, 2026-10-26: oak, pine, maple and spruce "look largely naked" as a whole, though their leaves look right.
+
+## Measured (seed 1337, master 7d610267e)
+
+**What sheds the shoots.** The light of every shoot candidate, as the simulation judged it:
+
+| preset | DBH | height | crown width | leaf | framework | twigs | candidates kept | below compensation | saturated |
+| :--- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
+| oak | 87 cm | 8.6 m | 6.1 m | 89 m² | 151 m | 1,811 | 47% | 15% | 71% |
+| pine | 73 cm | 10.6 m | 5.0 m | 16 m² | 71 m | 838 | 67% | 0% | 100% |
+| maple | 88 cm | 8.6 m | 6.3 m | 49 m² | 114 m | 2,600 | 83% | 14% | 60% |
+| spruce | 69 cm | 10.7 m | 6.3 m | 80 m² | 78 m | 40,061 | 93% | 6% | 82% |
+
+Light does not bind these crowns: most candidates sit in saturating light.
+
+**Vigour does not fill them** (`ShootGrowthConfig.vigour` raised 2× and 4×):
+
+| preset | leaf ×1 / ×2 / ×4 | side density ×1 / ×2 / ×4 |
+| :--- | :--- | :--- |
+| oak | 89 / 101 / 82 m² | 0.50 / 0.46 / 0.45 |
+| pine | 16 / 35 / 35 m² | 0.34 / 0.42 / 0.42 |
+| maple | 51 / 48 / 47 m² | 0.41 / 0.40 / 0.40 |
+| spruce | 78 / 74 / 72 m² | 0.33 / 0.33 / 0.33 |
+
+Above its gross yield every burst shoot is kept. The twig systems then stop growing outward for want of buds and
+room, not of light.
+
+**The framework does** (every non-root `BranchSpawnRule.count` doubled):
+
+| preset | leaf ×1 → ×2 | crown LAI | side density | side transparency | below density |
+| :--- | :--- | :--- | :--- | :--- | :--- |
+| oak | 89 → 188 m² | 3.1 → 5.3 | 0.50 → 0.66 | 0.42 → 0.33 | 0.58 → 0.71 |
+| pine | 16 → 38 m² | 0.7 → 1.4 | 0.34 → 0.48 | 0.64 → 0.56 | 0.35 → 0.46 |
+| maple | 51 → 116 m² | 2.0 → 4.3 | 0.41 → 0.62 | 0.42 → 0.37 | 0.42 → 0.63 |
+| spruce | 78 → 199 m² | 3.0 → 6.0 | 0.33 → 0.51 | 0.31 → 0.24 | 0.42 → 0.59 |
+
+FIA rates healthy crowns at 45-51% density and about 15% transparency [Randolph 2006].
+
+## Diagnosis
+
+The crowns are bare because their framework is sparse, and the framework's density is authored:
+- `count: 5` boughs, `count: 2` branches each, and so on, chosen per preset, not sourced;
+- each carrier wears a twig sleeve of limited reach;
+- between sleeves the crown is empty, and no twig system can reach across, at any vigour.
+
+The crown-filling principle ("fullness is set by light, not by when the simulation stops") holds for the twigs but
+not for the framework they hang on.
+
+The trunks are also far too thick for their height (an 87 cm DBH oak 8.6 m tall), the pipe model's known
+over-thickening. That is a separate defect; it makes trunk-based leaf targets meaningless here.
+
+## Targets
+
+**Expected whole-tree leaf area.** These are trees of the size the presets mean to be, not of their over-thick trunks;
+all sources are forest-grown trees.
+
+| preset | measured | expected | basis |
+| :--- | ---: | ---: | :--- |
+| oak (DBH 40 cm, h 14 m) | 89 m² | 280-430 m² one-sided | Forrester et al. 2017 (*Q. robur*, Table A.5); Gómez-García & Pérez-Rodríguez 2015 leaf mass × SLA 12.9-16.2 m²/kg |
+| maple (DBH 30 cm, h 13 m) | 49 m² | ~130 m² one-sided | Martin et al. 1998, *Can. J. For. Res.* 28: 1648-1659, *A. rubrum*, Table 4 (n = 11, DBH 6-52 cm) |
+| pine (DBH 25 cm, h 11 m) | 16 m² | 35-64 m² projected | Forrester et al. 2017; Repola 2009, *Silva Fennica* 43: 184 needle mass × projected SLA 3.9-5.7 m²/kg |
+| spruce (DBH 25 cm, h 11 m) | 78 m² | 100-150 m² projected | Forrester et al. 2017; Repola 2009 × SLA 3.3-5.0 m²/kg |
+
+- Every preset carries a third to two-thirds of the leaf a real tree of its size does.
+- Doubling the framework brings oak, maple and spruce into their ranges, and pine near its lower end. That fits the
+  diagnosis.
+- European oak allometries run about twice the American oaks' (Martin et al. 1998) at the same DBH.
+- No open-grown allometry, crown-level LAI or leaf area density was found for these species.
+- The research subagent's working files are in the session scratchpad.
+
+## The fork
+
+1. **Grow the framework from shoots too** (self-organizing, as Palubicki et al. 2009 do):
+   - The same bud demography and light that fill the periphery grow the whole crown. The boughs are the shoots that
+     survived and thickened, and branch spacing is an outcome of self-shading.
+   - The generator graph keeps what shoots cannot give: the trunk, whorl and architectural model, roots, stubs.
+   - This is the principled end state and a large refactor of `tree_skeleton_grow`.
+2. **Derive the framework's density from the twigs' reach:**
+   - A carrier's twig system wears a sleeve of measurable reach. Carriers are spaced so the sleeves tile the crown,
+     as card density was derived from the leaf sleeve.
+   - The generator graph stays and its counts become outcomes.
+   - Smaller, but the framework's other shape choices stay authored.
+3. **Source the counts per species:** branches per whorl and per metre of stem are measured for pine and spruce;
+   oak and maple are thinner.