Merge remote-tracking branch 'origin/main' into fix/2.1.15-exchange-format

Author: wormeyman

CLAUDE.md

@@ -578,6 +578,15 @@ loses_on_none` is 33s in the normal arm and **93s under poison**, taking the
   per 512x512 region, ~33s each in a debug build, and that grading lives on the
   TypeScript side instead. See the phase-5 notes below for the reasoning.
 
+  **Treat this job's cost as a RANGE, not a number: 1m44s to 2m48s.** #310
+  measured 1m44s on CI against the 2m48s recorded here from an earlier run, on
+  code whose Rust half did not change between them. That is the same spread the
+  test shards show (`one-ci-run-measures-the-runner` - identical spec files came
+  in anywhere from 294s to 469s), and the honest response is to widen the figure
+  rather than to replace it: a single run here measures the runner at least as
+  much as the job. Do not "correct" this to whichever number you last saw. If a
+  change to the Rust really does move this job, show it with more than one run.
+
 - **It runs `bash scripts/verify-rust.sh` directly**, the one deviation from
   "the YAML names only package.json scripts". That does not reopen the drift
   the rule guards against, because `verify:rust` _is_ that one line, so the
@@ -1611,7 +1620,26 @@ both sides and stay invisible. The sweep is the request's own pixel grid, swept
 rows-outer exactly as `render_vulcanus` sweeps it, so there is one geometry
 convention rather than two.
 
-**It found a real divergence on its first run, and the divergence is #309.**
+**The field SELECTOR lives in `fmw-noise`, not in the wasm crate, and copy that
+for Nauvis too.** `VulcanusParity` sits beside `VulcanusStack` in
+`expressions/vulcanus_stack.rs`; the wasm export builds the stack through the
+render helpers and then calls `parity.field(field, x, y)`. The reason is
+ownership of test-only API: the selector needs `elevation_fields` and
+`temperature`, which NO render path reads, and reaching them from another crate
+meant two `pub` methods on a library type that existed solely for a test - and a
+`pub` method cannot be `#[cfg(test)]`-gated, because the wasm crate calls it at
+build time. Keeping the selector in the same module makes both private again.
+The field count moved with it (`VulcanusParity::FIELD_COUNT`), so the count and
+the `match` it bounds cannot drift apart.
+
+The move is pure code motion and was checked as such rather than assumed: tier 2
+(74 fields) and tier 3 (byte-identical renders) both pass unchanged. It DOES
+move `engine.wasm` by 142 bytes, because the selector inlines differently once
+it is in the same crate as the layers it reads - which is a reminder that a
+wasm diff is not by itself evidence of a behaviour change.
+
+**It found a real divergence on its first run, and the divergence was #309 -
+now fixed, see below.**
 `basisNoiseExpr` forms its coordinate product in f64 and narrows once
 (`primitives.ts:66`); the Rust narrows `x` to f32 first and multiplies two f32s
 (`primitives.rs:87`). They agree at every f32-exact coordinate and differ
@@ -1643,25 +1671,67 @@ is worth more than the bug:
   same property that made `poison::index_result` necessary, and it is the
   standing answer to "tier 3 is byte-identical, so why build tier 2".
 
-**Which form is right is an internal-consistency argument, not a measurement**,
-which is why #309 is an issue rather than a fix that rode along. Both ports'
-multioctave path already narrows the incoming coordinate
-(`multioctaveNoise.ts:203`, `multioctave_noise.rs:137`) - which is exactly why
-the six `wobble_*` fields MATCHED off-grid in the same sweep where the plasma
-fields did not - and the game holds its noise variables at f32. Applying the
-narrowing was measured to leave the full gate green (**2140 passed, 0 failed**,
-`vulcanusPlasmaDecomposition` still 61/61 at worst residual exactly 0), because
-nothing in the suite scores off the f32 grid.
-
-**So the parity windows sweep ON the f32 grid, deliberately, and the divergence
-is PINNED rather than described.** `the two ports diverge off the f32 grid`
-freezes it at 32 fields and asserts the MECHANISM: `wobbleX` agrees,
-`hairlineCracks` does not, `resolvedTile` agrees. **That test goes red when #309
-is fixed**, which is the prompt to widen the windows back off the grid and delete
-the pin. A second test asserts the two parity windows really are on the grid and
-the pinning window really is not (20 of its 26 x-coordinates), so a step edited
-to something without an exact binary form fails as a window mistake rather than
-as a port bug.
+**#309 IS FIXED, and it was settled by measurement rather than by the
+internal-consistency argument this file used to record here.** That argument -
+both ports' multioctave already narrows (`multioctaveNoise.ts:203`,
+`multioctave_noise.rs:137`), the game holds its noise variables at f32 - pointed
+the right way but proved nothing, and this section previously said so.
+
+**The measurement came from a fixture already committed, not from a new
+capture.** `fulgora_basis` is a multioctave read at Fulgora's DERIVED coordinate
+`wx = ox + wobble_x * wobble_mask`, computed in f64 and therefore off the f32
+grid at **55 of that fixture's 101 positions**. Scored against the game:
+
+| `sumOctaves` incoming coordinate |       exact | worst residual |
+| -------------------------------- | ----------: | -------------- |
+| **narrowed** (what shipped)      | **101/101** | exactly 0      |
+| un-narrowed (planted)            |      81/101 | 7.0333e-6      |
+
+Twenty positions discriminate, so the game demonstrably narrows the incoming
+coordinate, and the Rust form was the right one. `basisNoiseExpr` now narrows
+`x` and `y` before the `input_scale` multiply.
+
+**That is also the measurement #191 asked for, in its own words** - "a caller
+that passes a derived coordinate" - and Fulgora has satisfied it since it
+landed, unnoticed for months. Two lessons, and the second is the transferable
+one:
+
+- **Fold the fixtures you already HAVE before capturing more.** The plan here
+  was a far-field capture at |x| >= 65536, where the 1/256 grid stops being a
+  subset of the f32 grid. It would have worked and it was unnecessary: a
+  DERIVED coordinate leaves the f32 grid right next to the origin, so the
+  evidence was sitting in `oracle-fulgora-elevation` the whole time.
+- **A "no fixture can grade this" claim is about the fixtures you looked at.**
+  It was true of every Vulcanus fixture and false of a Fulgora one.
+
+**#191 is two-thirds done and its issue text is stale.** Re-read the code, not
+the issue: `quickMultioctaveNoise` ALREADY narrows both coordinates
+(`quickMultioctaveNoise.ts:192-193`), so only one of its three ops was
+outstanding. `variablePersistenceMultioctaveNoise` narrowed `x` and NOT `y` - in
+**both** ports, which is why tier 2 could not see it: the two agreed with each
+other while both disagreed with the game. `x` was narrowed only as a side effect
+of the `f32(x + offset_x)` add; `y` had no add and so was silently multiplied in
+f64. Both ports now narrow it.
+
+The third op, `basisNoise` itself, was deliberately NOT changed. Its disciplined
+callers all narrow before calling, so narrowing inside would be a no-op for
+them - and its remaining direct callers (`nauvisShared.ts:133-134`,
+`startingPatches.ts:185`, `regularPatches.ts:164-165`) are unported NAUVIS
+chains where the whole expression is un-narrowed, not just the coordinate.
+Planting the internal narrowing leaves all 26 of their specs passing, so no
+committed fixture discriminates it. That belongs to #226, scored layer by layer
+under the greedy-accept rule, not to a change that cannot grade it.
+
+**The parity windows still sweep ON the f32 grid, and the pin has been
+INVERTED.** `the two ports agree off the f32 grid` now asserts **0 of 74**
+diverging where the pin froze 32, and reverting `primitives.ts` reproduces
+`[ 'hairlineCracks', ...(31) ]` - checked by planting, not assumed. Its
+anti-vacuity is not optional and is easy to get wrong: "nothing diverges" is
+exactly what a sweep evaluating nothing would report, so the test also asserts
+the off-grid window's folds differ from the on-grid window's on all 74 fields.
+The windows themselves are kept as they are because they are tuned for FIELD
+coverage (the `startingArea` range, all 19 tiles placed), not because the
+restriction is still load-bearing.
 
 Two anti-vacuity numbers, both frozen: the two windows differ on **all 74**
 fields, and each places **all 19** tiles, so every probability fold is graded

crates/fmw-noise/src/expressions/vulcanus_stack.rs

@@ -37,6 +37,7 @@
 //! Three lines rather than one, and they are honest about the ownership rather
 //! than hiding it behind an arena.
 
+use crate::cliffs::vulcanus_fields::CliffinessBasic;
 use crate::distance_from_nearest_point::distance_from_nearest_point;
 use crate::eval::ctx::EvalCtx;
 use crate::expressions::starting_spot_at_angle::AngleTrig;
@@ -47,7 +48,11 @@ use crate::expressions::vulcanus_elevation::{ElevationFields, VulcanusElevation}
 use crate::expressions::vulcanus_helpers::VulcanusHelpers;
 use crate::expressions::vulcanus_resources::{OreRegions, ResourceFields, VulcanusResources};
 use crate::expressions::vulcanus_spawn::VulcanusSpawn;
+use crate::expressions::vulcanus_spawn::WobbleSums;
 use crate::multioctave_noise::Prepared;
+use crate::resources::vulcanus_catalog::sulfuric_acid_geyser_probability;
+use crate::rocks::vulcanus_field::{vulcanus_decorative_knockout, VulcanusRockFields};
+use crate::tiles::vulcanus_catalog::TILE_ORDER;
 use crate::tiles::vulcanus_catalog::{
     resolve_tile, tile_probabilities, vulcanus_rock_noise, MountainLavaSpots, VulcanusTile,
     VulcanusTileFields,
@@ -248,8 +253,7 @@ impl<'a> VulcanusStack<'a> {
     /// port that dropped the `max` would score identically. The clamp's real
     /// test lives in `vulcanus_elevation`, constructing the case the fixture
     /// does not.
-    #[must_use]
-    pub fn elevation_fields(&self, x: f64, y: f64) -> ElevationFields {
+    fn elevation_fields(&self, x: f64, y: f64) -> ElevationFields {
         self.elevation.eval(x, y)
     }
 
@@ -260,8 +264,7 @@ impl<'a> VulcanusStack<'a> {
     /// byte-identical pixels say nothing about it. Tier 1 grades it against the
     /// game (244 of 434) and tier 2 is the only thing that would notice it
     /// diverging from the TypeScript.
-    #[must_use]
-    pub fn temperature(&self, x: f64, y: f64) -> f64 {
+    fn temperature(&self, x: f64, y: f64) -> f64 {
         self.elevation
             .temperature(x, y, self.base.ctx.temperature_bias)
     }
@@ -332,6 +335,149 @@ impl<'a> VulcanusStack<'a> {
     }
 }
 
+/// Tier 2's field selector for the Vulcanus graph: one named expression, by index.
+///
+/// **This lives here rather than in the wasm crate on purpose.** The selector
+/// needs `elevation_fields` and `temperature`, which nothing on a render path
+/// reads - temperature is not drawn at all, and `elev` versus its clamp is a
+/// distinction no fixture can make. Reaching them from another crate meant two
+/// `pub` methods on a library type that existed solely for a test, and a `pub`
+/// method cannot be `#[cfg(test)]`-gated because the wasm crate calls it at
+/// build time. Keeping the selector in this module makes both private again.
+///
+/// The layers it evaluates per point are deliberately NOT shared with each
+/// other - `tile_fields` re-evaluates the biome and resource layers, for
+/// instance. That is the point: each field is reached through its own entry
+/// point, the same one its consumer uses, so a field wired to the wrong layer
+/// shows up as a divergence rather than being smoothed over by a shared
+/// intermediate. It runs once in a test, so the redundancy is free.
+pub struct VulcanusParity<'a, 'b> {
+    stack: &'a VulcanusStack<'b>,
+    rocks: VulcanusRockFields<'a, 'b>,
+    knockout: Prepared,
+    cliffiness: CliffinessBasic,
+}
+
+impl<'a, 'b> VulcanusParity<'a, 'b> {
+    /// How many named fields [`Self::field`] can select, `0..FIELD_COUNT`.
+    ///
+    /// The order is the order the chain evaluates in: helpers, spawn, cracks,
+    /// climate, biomes, elevation, resources, the tile-support fields, the two
+    /// overlay fields, then the 19 tile probabilities and the argmax over them.
+    pub const FIELD_COUNT: u32 = 74;
+
+    #[must_use]
+    pub fn new(stack: &'a VulcanusStack<'b>, seed0: u32) -> Self {
+        Self {
+            stack,
+            // The overlay fields hang off the same stack rather than rebuilding
+            // the chain, which is what their own constructors are for.
+            rocks: VulcanusRockFields::new(stack, seed0),
+            knockout: vulcanus_decorative_knockout(seed0),
+            cliffiness: CliffinessBasic::for_vulcanus(seed0),
+        }
+    }
+
+    /// One named field at `(x, y)`. Out-of-range indices resolve to the argmax,
+    /// matching the exhaustive `match` this was lifted from.
+    #[must_use]
+    #[allow(clippy::too_many_lines)]
+    pub fn field(&self, field: u32, x: f64, y: f64) -> f64 {
+        let base = self.stack.base;
+        let sp = base.spawn.eval(x, y, WobbleSums::at(&base.helpers, x, y));
+        let cr = base.cracks.eval(x, y);
+        let cl = base.climate.eval(x, y, &cr);
+        let bi = self.stack.biomes.eval(x, y);
+        let el = self.stack.elevation_fields(x, y);
+        let res = self.stack.resources(x, y);
+        let tf = self.stack.tile_fields(x, y);
+        let rk = self.rocks.eval(x, y);
+
+        match field {
+            0 => base.helpers.wobble_x(x, y),
+            1 => base.helpers.wobble_y(x, y),
+            2 => base.helpers.wobble_large_x(x, y),
+            3 => base.helpers.wobble_large_y(x, y),
+            4 => base.helpers.wobble_huge_x(x, y),
+            5 => base.helpers.wobble_huge_y(x, y),
+            6 => sp.ashlands_start,
+            7 => sp.basalts_start,
+            8 => sp.mountains_start,
+            9 => sp.starting_area,
+            10 => sp.starting_circle,
+            11 => cr.hairline_cracks,
+            12 => cr.flood_cracks_a,
+            13 => cr.flood_cracks_b,
+            14 => cr.flood_paths,
+            15 => cr.flood_basalts_func,
+            16 => cl.aux,
+            17 => cl.moisture,
+            18 => bi.mountain_volcano_spots,
+            19 => bi.mountains_raw_volcano,
+            20 => bi.mountains_biome_full,
+            21 => bi.ashlands_biome_full,
+            22 => bi.basalts_biome_full,
+            23 => bi.mountains_biome,
+            24 => bi.ashlands_biome,
+            25 => bi.basalts_biome,
+            // The RAW `elev` and its clamp, graded separately. No fixture can
+            // tell them apart - see `VulcanusStack::elevation_fields`.
+            26 => el.elev,
+            27 => el.elevation,
+            // A genuinely different field, not a rounding of the one above:
+            // `multisample`'s offsets are in the CONSUMING program's grid units
+            // and the cliff lattice is 4 tiles wide (#83).
+            28 => self.stack.cliff_elevation(x, y),
+            // Read by no renderer at all, which is half the argument for this
+            // selector existing.
+            29 => self.stack.temperature(x, y),
+            30 => res.basalts_favorability,
+            31 => res.mountains_favorability,
+            32 => res.mountains_sulfur_favorability,
+            33 => res.ashlands_favorability,
+            34 => res.starting_tungsten,
+            35 => res.starting_coal,
+            36 => res.starting_calcite,
+            37 => res.starting_sulfur,
+            38 => res.tungsten_region,
+            39 => res.coal_region,
+            40 => res.calcite_region,
+            41 => res.sulfuric_acid_region,
+            42 => res.sulfuric_acid_patches,
+            43 => res.sulfuric_acid_region_patchy,
+            44 => res.metal_tile,
+            45 => sulfuric_acid_geyser_probability(res.sulfuric_acid_region_patchy),
+            46 => tf.mountain_lava_spots,
+            47 => tf.rock_noise,
+            48 => tf.distance,
+            49 => self.cliffiness.eval(x, y),
+            50 => f64::from(self.knockout.eval(x, y)),
+            51 => rk.rock_huge,
+            52 => rk.rock_big,
+            53 => rk.density,
+            // The 19 tile probabilities, in `TILE_ORDER`.
+            54..=72 => tile_probabilities(&tf)[(field - 54) as usize],
+            // The resolved tile, as its index in `TILE_ORDER`. A number so it
+            // rides the same comparator as the probabilities it derives from,
+            // and a DISCRETE one, which is why `resolve_tile` carries
+            // `poison::index_result` rather than a numeric hook.
+            _ => tile_index(resolve_tile(&tf)),
+        }
+    }
+}
+
+/// A resolved tile as its position in [`TILE_ORDER`].
+///
+/// A linear scan rather than a second table, so it cannot drift from the order
+/// the argmax resolves against.
+fn tile_index(tile: crate::tiles::vulcanus_catalog::VulcanusTile) -> f64 {
+    #[allow(clippy::cast_precision_loss)]
+    TILE_ORDER
+        .iter()
+        .position(|&t| t == tile)
+        .map_or(f64::NAN, |i| i as f64)
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;

crates/fmw-noise/src/variable_persistence_multioctave_noise.rs

@@ -86,11 +86,16 @@ pub fn eval(
     tables: &BasisNoiseTables,
 ) -> f32 {
     let xo = (x + terms.offset_x) as f32;
+    // `y` is narrowed for the same reason `x` is: the noise machine holds its
+    // coordinate values at f32, so the scale multiply is an f32 operation on
+    // both operands. `x` was always narrowed here through the `offset_x` add;
+    // `y` had no add to narrow it and so was silently multiplied in f64 (#191).
+    let yf = y as f32;
     let last = terms.scales.len().saturating_sub(1);
     let mut acc = 0.0f32;
     for (k, &scale) in terms.scales.iter().enumerate() {
         let xk = xo * scale;
-        let yk = (y * f64::from(scale)) as f32;
+        let yk = yf * scale;
         acc += basis_noise(f64::from(xk), f64::from(yk), tables);
         if k < last {
             acc *= persistence;