generate_tree_with_roots explodes in Eden: rooted trees are unusable on streamed terrain

[Kieleth]

Symptom

Switching Eden's three tree spawn sites from generate_tree() to generate_tree_with_roots() produces a total explosion: the world blows apart. Observed 2026-08-02, sync prep ([GPU_PREP] path=SYNC), 12 trees spawned, log /tmp/eden_roots.log.

Reverted immediately. Eden is back on generate_tree().

Why the swap was attempted

Every measurement behind the issue #38 fix (8c0e86e) was taken on generate_tree_with_roots: creation overlap 511 pairs to 8, coincident 381 to 0, canopy peak speed 1.19 m/s against a 2.0 limit. Eden calls generate_tree(), a path none of those tests cover, and Eden still dropped its canopies after the fix. Moving Eden onto the measured path was the cheapest way to test whether that was the whole explanation.

It is not, and the rooted path is worse in Eden than the one it replaced.

What is different about the two paths

generate_tree() attaches the trunk to a floor tile. generate_tree_with_roots() builds a root plate plus primary roots that rest on the turtle, with no floor tile required.

The world_z argument means different things to each. Eden passes gz from ground_here(world_x, world_y, gz, SupportMode::ROOTED), which is a floor-tile surface height. generate_tree_with_roots treats its third argument as ground_z and builds a root system DOWNWARD from it: the root plate sits around z = -0.25 with a half-thickness of 0.125, and primary roots spread below that.

On Eden's streamed terrain that puts the entire root system inside the floor tiles that already exist there. Every root is created interpenetrating a tile, and the solver does the only correct thing with an impossible world.

This is the same class as issue #38 (bodies created inside each other) but caused by the caller's frame of reference rather than by discarded positions, and at a far larger scale because it is every root of every tree against a full terrain chunk.

Not yet verified

The mechanism above is inferred from the argument semantics and from #38's measurements. It has NOT been measured: no headless capture of the explosion was taken before reverting. That should come before anyone tries this again.

What this does NOT explain

Eden's canopies still fall off on the ORIGINAL generate_tree() path, and there is an orbiting trunk. Those remain open under issue #38 and task #35. The leading remaining hypothesis is that Eden's ambient forest comes from generate_tree_space_colonization() at examples/eden/src/main.cpp:432, which uses TreeGenerator, a DIFFERENT generator that none of the #38 work touched.

If this is retried

1. Capture the explosion headlessly first, with the creation-overlap scan from tests/test_no_overlap_at_creation.cpp pointed at an Eden world rather than an isolated tree.
2. Decide what world_z should mean when a rooted tree is planted on terrain that already has floor tiles. Either the roots need the tiles removed beneath them, or the rooted path needs a variant that plants ON a surface rather than THROUGH it.
3. Do not switch all three call sites at once again.

[Kieleth]

Follow-up: the engine needs an EXPLOSION DETECTOR

Owner request, 2026-08-02. This run was diagnosed by a human looking at a screen and saying "total explosion". The engine had every number needed to say so itself and said nothing.

That is the recurring shape of this whole campaign: the instruments were present, the signal was not raised. A detector turns "it looks wrong" into a timestamped WARNING with the offending body named.

What it should watch

Physical implausibility, not any particular bug. Candidate signals, cheapest first:

• Speed ceiling. Any DYNAMIC body exceeding a plausible bound for the scene. A leaf at 3 m/s is settling; a leaf at 40 m/s has been launched. Report the particle id, its speed, and its owner entity.
• Kinetic energy spike. Total KE jumping by orders of magnitude between frames means energy was created, and the solver is the only thing that can create it. This catches whole-world blowups that no single body's speed would flag.
• Creation-time overlap. Bodies spawned inside each other, which is issue Foliage floats and drifts: tree canopies detached from their trunks, scattered mid-air #38 and the direct cause here. tests/test_no_overlap_at_creation.cpp already computes this; it belongs in the engine as a runtime check, not only in a test.
• Bodies leaving the world. Anything beyond a sane distance from the origin or below the turtle.

Design constraints, from what this campaign has learned the hard way

• Always compiled in, off or cheap by default, in the shape of ParticleTracer and physics_trace.h: one predicted-not-taken branch when nobody is listening. Instrumentation that has to be switched on at build time rots.
• NAME THE ELEMENT, never just the aggregate. A max with no owner cannot be sanity-checked. That lesson cost this campaign a week on S22, where one immovable corner pair pinned 14,000 bodies and no counter could show which.
• Rate-limited. An explosion produces thousands of violations per frame; one WARNING per frame per class, with a count, or the log becomes the new place the signal hides.
• It must fire on THIS case. The gate for the work is reproducing the rooted-tree explosion headlessly and confirming the detector reports it, before trusting it anywhere else. A detector that has never fired is not yet a detector: same discipline as tests/test_async_prep_churn.cpp, which was proven by reverting its fix and watching it fail.

Why it pays for itself

Every visual bug in this session (#38 floating canopies, #42 this explosion) was found by a human noticing something on screen, sometimes days later. All of them were loud in the physics from frame 2. Eden runs headless in CI via --bench N --headless, so a detector makes these catchable without anyone watching.

[Kieleth]

The trigger is CHUNK STREAMING, not the rooted-tree path

2026-08-02, after the rooted-tree change was reverted. The user reported the world exploding again while only rotating the camera, doing nothing else. This is on plain generate_tree, sync prep, i.e. the merge candidate.

That run was captured: /tmp/eden_premerge.log, 82,479 lines.

Evidence. The final ~250 lines are chunk load/unload traffic, and the particle count moves across it:

[CHUNK_UNLOAD] Unloading 1 chunks
[CHUNK_UNLOAD]   Entity 3633 (FloorTile): got 25 render indices [3466,3465,...]
[CHUNK_UNLOAD] Chunk (2,1) unloaded 3 entities (75 particles queued)

Particles: 19112 -> 18664 -> 18739

Rotating moves the view, which streams chunks, which creates and destroys bodies at runtime. The camera is incidental; it is only what causes the world to load.

Why this reframes issues #38 and #42

This was hypothesis 3 in task #35 and is now the leading one, because it explains everything the tree-generator theory could not:

• Why the issue Foliage floats and drifts: tree canopies detached from their trunks, scattered mid-air #38 fix did not reach Eden: chunk activation bypasses the generator that was fixed.
• Why canopies fall in Eden but never in an isolated tree.
• Why the explosion happens while MOVING rather than at startup.
• Why it survived reverting the rooted-tree change.

Same defect class as #38 throughout: bodies created inside each other, the solver correctly ejecting them. Different creator.

Merge impact

This blocks the merge of the current branch, not because the committed work is wrong (all of it is measured and green) but because "no regression" cannot be claimed while the world explodes during ordinary movement.

THE NEXT MEASUREMENT, before anything else

Does a stock Eden built from BEFORE today's commits explode the same way on rotation?

• Yes -> pre-existing, the merge stands on its own terms, and this becomes a separate priority.
• No -> something in these 7 commits caused it, and the tree placement work is the obvious suspect.

Nothing should be built on top of the chunk-streaming theory until that A/B is run. It is one build and one rotate.

And it is the case for the explosion detector

Every explosion in this campaign has been found by a human noticing something on a screen, then reconstructed from logs afterwards. This one was loud in the physics the instant a chunk loaded. Eden runs headless via --bench N --headless, so a detector that fires on implausible speed or a kinetic-energy spike would have caught it unattended, named the body, and pointed straight at chunk activation.

[Kieleth]

The detector exists, and it re-found the lost reproduction on its first flight

explosion_detector.{h,cpp}: always on, one pass over final velocities at the end of the physics frame, rate-limited to one WARNING per class per second, and every warning names the body. Three signals:

• speed: any body over 40 m/s (calibrated: settled canopy 1.2, Baumgarte ejection cap 4, a 50 m fall 31, the engine's own velocity clamp 100)
• energy: total KE jumping 5x AND +10 kJ AND more than twice the fastest single body's own KE in one frame. That last condition is what separates an explosion from a throw: a thrown boulder is one body (the battery's projectile scenario false-alarmed without it), an explosion is many.
• escape: a body below z=-50 (the turtle boundary makes that unreachable, so reaching it means the boundary failed) or beyond |5000| in x/y

Guarded by tests/test_explosion_detector.cpp: silent through 180 quiet frames, fires within 5 frames of a single-body detonation and names the particle, fires on six bodies at 25 m/s (all UNDER the ceiling; the collective case a per-body check is blind to), and off means off. Zero false positives across the battery, foliage, residual and order suites, guards 19/0, characterization checksum unchanged.

And on its first unattended Eden run it caught this, at frame 1:

[MAX_UP F4] P5377 vz=98.46 z=1.83 at_rest=0
[EXPLOSION WARNING] speed: particle 5138 at 97.1 m/s (ceiling 40.0) pos=(28.7, -20.5, 1.7) mass=0.00 | 2 bodies over ceiling this frame

Two bodies ejected upward at ~98 m/s from ground level at world spawn, riding just under the 100 m/s velocity clamp. mass=0.00 at two decimals means a near-massless body, which smells like foliage.

The reproduction this issue lost is therefore back, and it is cheap: eden --bench 300 --headless, first frames, every run. No camera, no rotation, no human. The spawn-time ejection is the lead for both this issue and #38, and the next investigation has a handle: who ejects P5377 and P5138, and why upward at the clamp.

Detector bugs found while proving it (both by its own test): the rate limiter silently suppressed the first 59 frames after start, which is precisely when spawn-time explosions happen; and the first detonation test kicked a body horizontally into a tile seam, where the solver correctly stopped it before the scan, so the test detonated upward instead.