feat(dsl,compiler): valley + cherry-valley horizon — surround generator, biome layer, tree layer (spec-0026 W-B, task #155)

[stellarfeline]

spec-0026 slice W-B (task #155): the VALLEY + CHERRY-VALLEY surround generator, biome layer and tree layer, plugged into the W-A foundation's horizon contract. This is the engine work the hollow-vigil {base:"valley", flora:"cherry"} construction round needs; do not merge before the owner has viewed that round (player-experienceable — owner playtest is the gate; base branch = worker/spec-0026-foundation, which must land first anyway).

What this adds, at design level

Surround generator (crates/compiler/src/surround.rs, new). A valley is a mountain annulus of total footprint ratio× the scene's union XZ bounds (2..=3, default 2.5): flat walkable gap floor (top y=63 → valley walk_ref_y 64 — like flatland, a valley relocates nothing vs void), then a domain-warped, ridged-multifractal rim (rim_height default 48, ridge floor 0.3 so the ring never opens). Composed entirely from the in-house position-addressed value-noise family (edit.rs primitives made pub(crate); Musgrave ridge composition + Bridson Poisson disk are ideas-only re-implementations — ledger rows added to ACKNOWLEDGEMENTS). Everything derives from stream_seed(seed, "horizon/valley"); no trig anywhere (libm sin/cos is not bit-stable across hosts — the Poisson sampler uses square rejection instead).

Un-climbability is proven twice, promised never (spec §5).

• By construction: every surround surface height is quantized to 2-block steps — a 1-block riser does not exist anywhere on the annulus, and vanilla players cannot step/jump 2. Trees are planted only where their whole canopy footprint clears the crest line (checked per cell, no guessed margin), so no canopy forms a ladder on the inner wall.
• Empirically: DW0369 (build, exit 3) — a nav walk flood seeded on every gap-floor cell must never stand outward of the crest line, over the assembled (and, when a stage-7 script exists, edited) world. The generator also runs its own conservative flood (unlimited drops, tree solids included) and dies at generation if it ever regresses.

Biome layer. Per-band /fillbiome in setup_finish (after place_verify, so the chunks provably exist) — vanilla's own tint/ambience channel, no resource pack. flora: oak ⇒ minecraft:windswept_forest, cherry ⇒ minecraft:cherry_grove. The pass wraps in gamerule max_block_modifications <largest band volume> (1.21.11's renamed commandModificationBlockLimit) and restores the 32768 default; one command per band, so paint can never half-apply. Flatland note: flatland needs no fillbiome — its superflat generator already declares minecraft:plains; the fillbiome channel is surround-only.

Tree layer. Deterministic Bridson-family Poisson-disk scatter (r=7) over the crest band and outer face — 树在山上: never in the gap floor, never in the scene, never on the inner wall. One parameterized tree shape (the greenfield hand-shaped small tree grown a storey taller); species ids come from the flora table.

Cherry-valley is a parameter row, not a fork (criterion 6). One code path; flora/palette are positionally-parallel id tables (oak_log→cherry_log, oak_leaves→cherry_leaves, understory short_grass/fern → pink_petals/short_grass; rock ids shared). Proven at two levels: a generator test decodes same-seed oak/cherry tiles and asserts positions/states identical with ids mapped; process-level, tools/check-flora-parity.py (new) diffs two full emissions and fails on anything beyond flora/palette block ids + the biome id (manifest.json is exempt as a declaration mirror — it embeds the campaign declaration hash).

Plumbing (the W-A plug-in contract, followed to the letter). base_implemented(Valley)→true; valley walk_ref_y arm; DSL DW0141 reserved arm for valley/cherry-valley deleted (summit/sky stay reserved). Tiles are NOT an AreaPlacement: Plan.surround is a separate field, Plan::placed_pieces() is the explicit placement/model iterator — emit (structures, sentinels, forceload, place_all, place_verify), read_structures and the assembled voxel model opt in; boundary-region derivation, lighting scope, anchors and analysis keep reading plan.areas and never see the surround (spec §5 exclusion by construction). Render plan gains one vista shot (scene edge looking outward at the rim — the establishing shot of spec §6).

What CI now proves (all green locally)

• v09_valley_builds_byte_identical_and_ships_surround: double-build byte-identity for the valley fixture (criterion 1 valley row); tiles shipped + placed; fillbiome + gamerule wrap present; vista shot present; void ambient in server.properties.
• v09_cherry_valley_is_a_parameter_row: same-seed valley vs cherry-valley emission, check-flora-parity.py green (criterion 6).
• surround::tests (10): determinism; ≤48×48×48 tile envelope + exact annulus coverage; even-step heights + ridge-never-opens; oak/cherry byte-parallelism at generator level; trees-stay-on-the-mountains; Poisson spacing; param-range refusal; build-range + no-gravity-block palette; nav flood over decoded serialized tiles; DW0369 red on a deliberately carved staircase (doctored world).
• docs/reference/compiler.md: DW0369 catalog row + a valley behavior section, same PR; check-dw-codes.py fully green (191 codes documented + covered).
• spec-0026 acceptance criterion 2 fixtures by code: DW0366 (valley ratio: 5 → validation exit 1), DW0367 (walk_y stripped → build exit 3), DW0364 (the feat(dsl,compiler): map editor L2 massing verbs — swap/insert/remove/rewire/reseed-piece (spec-0017 PR 3) #149 shape — a lying walk_y: 5 floods the interior with no waterline_y declared → build exit 3).

Visual parameters chosen (for the owner's 和谐 judgment — the vista shot + hollow-vigil round will show them)

• gap floor width 12, inner slope run 18 (2-block terraced, bare rock gradient upward), rim_height default 48, ridge floor 0.3 (min crest ≈ 14 at the ring's lowest saddle).
• tree spacing r=7 (≈ 360 trees around a 96×96 scene), crest band biased grassy so the tree line crowns the rim silhouette — for cherry, blossoms against the sky are exactly what the scene-edge vista frames.
• Reference-scene footprint (96×96, ratio 2.5): 31 tiles, ~3.9 MiB gzipped structures, generation < 1 s release.

Known limits (recorded in compiler.md)

• A scene too small for the ring to rise (annulus side < 30) legally yields a floor-only surround — no rim, no trees. The hello-world fixture is such a scene; the spec-0013 boundary clock (required for valley by DW0320) remains the enforcement, as for every horizon. The generator-level tests use full-size scenes.
• Snapshot manifests do not list surround tiles as pieces (the voxel model contains them; the manifest lists authored areas). Flag if the reviewer-medium round wants them named.
• check-world-settings.sh needed no valley case: valley ships the existing void superflat literal, already covered.

Stack sync + amendment (post-rebase onto the finished foundation, 370a45b)

• Rebased onto the foundation's final tip; where both branches had independently fixed the same WIP debts (version bump test, datum tests — both converged on the same walk_y: 0 cliff fixture for the ocean-breach stranding test — DW catalog rows, fmt), the foundation's versions win and this branch's duplicates were dropped.
• The foundation's reserved-bases test now pins both directions: summit/sky still DW0141; valley/cherry-valley landed and NOT reserved.
• spec-0026 amendment (PR docs(specs): spec-0026 amendment — vista_radius definition + blend_width range #261) rides this PR (planner ruling; it already touches horizon_rules): summit.vista_radius is defined as measured outward from the scene bounding-box edge, floor 192 (shipped summit view-distance 12 × 16), default 208 (was 176 — the foundation had escalated the default/floor contradiction rather than resolve it by invention); flatland.blend_width range 1..=16 (0 is the forbidden hard material wall), default 6 unchanged. Both DW0366, with code-asserting range tests.

Machine red→green for the motivating scenario: worker/spec-0026-foundation alone refuses horizon:"valley" with DW0141 (red); with this branch the same campaign builds green with the surround shipped, and the doctored-staircase test is the DW0369 red→green pair.

🤖 Generated with Claude Code

[stellarfeline]

CI attribution (verified by reproducing each red at the foundation tip, 4599ad2, with this slice absent — all four fail there identically):

• rust (fmt, clippy, test): (a) cargo fmt --check diffs in crates/dsl/src/lib.rs + stages.rs — unformatted foundation WIP (this branch deliberately does not format another slice's files); (b) cli::version_line asserts dsl 0.8.0 while the foundation bumped SUPPORTED_DSL_VERSION to 0.9.0.
• prefab generators: tidal-keep-generator fmt — the foundation's walk_y emission commit.
• docs (link check / DW gate): DW0364/DW0366/DW0367 catalog rows missing — the foundation's declared 'docs follow' debt. This slice's DW0369 row and behavior section are in.

Nothing in this slice's own surface is red: clippy -D warnings clean, the full workspace suite green locally except the inherited version_line, and the two new process gates (v09_valley double-build byte-identity, check-flora-parity.py) pass. This PR is stacked on worker/spec-0026-foundation and cannot merge before it; when the foundation lands its tests/docs commit, a rebase makes this PR's CI green with no changes here. Merge gate beyond CI: the owner's viewing of the hollow-vigil cherry-valley round (player-experienceable).

[stellarfeline]

Task #176 — measured, root-caused, fixed, and gated

The owner's verdict was that the cherry valley "reads as a quarry". Measured on the hello-room valley fixture rather than eyeballed:

clause	columns
in the annulus	4920
surface is grass	3140 (64%)
whole 5×5 canopy clears the crest line	147 (3.0%)
both	147 — identical, so grass never constrained anything
crest Poisson returned	0
inner-slope Poisson returned	7
canopy coverage	10.1%

Seven trees in an entire valley, and the trees themselves were fine — 4–5 block trunks, ~44 leaves each. Never malformation, and never the density constant.

Root cause

Bridson grows from its active list by jumps in [r, 2r), so a run seeded from one point samples only what those jumps reach. Both tree domains break that twice over: the annulus is a ring (a frontier cannot wrap it) and eligibility is speckle (grass noise ∧ a keep hash), so the frontier dies within a few steps. The crest pass never started at all — its single lattice scan found no in-domain column across a 3% speckle, and the sampler returned before its first jump.

Seeding from every in-domain lattice column costs one domain evaluation per lattice cell, is exactly as deterministic (positional order, far_enough still enforces spacing, seeds consume no RNG), and preserves blue-noise character.

The defect degrades with scale, which is why review missed it. On the 96×96 test scene the single-seed sampler still produced 1050 trees / 42.9%. It collapses on a narrow, speckled annulus — a small campaign, which is what was played.

Density — measured, and a proposal, not a decision

With the sampler fixed, TREE_SPACING is the only knob. Sweep recorded on the constant itself:

radius	trees	canopy
7.0 (was)	10	14.8%
5.0	25	32.0%
4.0 (now)	47	50.1%
3.0	80	61.9%
2.5	100	67.4%

4.0 is half-covered, so the crest silhouette still reads and the grove still has gaps to walk through. Density is an aesthetic call and belongs to the owner — say a number and it changes. What bounds it mechanically is DW_VALLEY_CLIMB, green across the whole range (the nav flood over the emitted world proves per build that a denser canopy grows no standable staircase).

The regression gate took two attempts to bind

blossom_reaches_the_inner_slope was green throughout and could not have caught this: it asserts inner blossom exists, and seven trees exist. The new test binds quantity — and, written first against the 96×96 scene, it passed with the defect deliberately restored. Moved to a 24×24 scene, where the same code gives 25 trees / 7.5% against 63 / 16.6% with the fix, and the floor sits between the two measurements.

---

Also on this branch

• The foundation + the flood verb (spec-0030) merged in: the foundation alone reds DW0364 on 26 standable cells at world y=62 — the ocean line — in already released island content. Island now builds green in both languages, DW0364/DW0394/DW0395 all 0.
• Three clean-but-broken merges fixed, none of which git flagged: a doc comment spliced through write_cell; a scene-file rename (<shot>.json → <campaign>_<shot>.json) merged against a test written for the old name; and DW0185 (i18n v2) versus fix(compiler,harness): the wave countdown is a liveness census, not a kill tally (task #178) #268's PackTest header interpolating world.title raw where every sibling used artifact_title.

Full workspace green: tests, clippy -D warnings, fmt, and every static checker.