@woosh/meep-engine 3.1.0 → 3.2.0

package/src/REVIEW_2026_08_06/core-science.md

@@ -1,223 +1,223 @@
-# Correctness review — `core/science` + `core/color`
-
-Scope: every non-spec source file under
-`meep/src/core/science/` (40 files) and `meep/src/core/color/` (47 files).
-`editor/`, `prototype*.js`, `*.spec.js` (evidence only) and `.d.ts` excluded.
-
-All findings below were reproduced by executing the actual modules under node
-(`type: module`, direct file-URL imports). Numbers quoted are measured, not derived.
-
----
-
-## Verified-correct (no findings)
-
-Checked against the cited standard/reference and found exact:
-
-* **`science/units`** — all 7 base + 19 derived SI exponent vectors match the SI Brochure
-  (F, H, Ω, S, Wb, T, V, W, Pa, J, N, C, Hz, Bq, Gy, Sv, lm, lx, kat all correct).
-  `UnitMatrix` composition/inverse/power algebra correct and alias-safe.
-  `magnitude_prefix_index` verified exact at every one of the 21 decade boundaries
-  (`Math.log10` returns exact integers for all of 1e-30…1e30, so no off-by-one).
-  `unit_matrix_to_string` decomposition terminates and produces the documented strings;
-  `compute_scalar_power` correctly rejects fractional powers (`m/s` does not render as `Gy^0.5`).
-* **`sRGB_to_linear` / `linear_to_sRGB`** — threshold 0.04045 / 0.0031308, `1/12.92 = 0.0773993808`,
-  `1/1.055 = 0.9478672986`, `0.055/1.055 = 0.0521327014`, exponent `1/2.4 = 0.4166666666666667`.
-  All correct to ≥1e-10 relative.
-* **`rgb_to_xyz` / `xyz_to_rgb`** — exact sRGB↔XYZ D65 matrices; measured `rgb(1,1,1) → XYZ
-  (0.950456, 1.000000, 1.089058)` and an exact round trip.
-* **`xyz_cmf_tabulated` × `D65_spd_tabulated`** integrated over 360–830 nm gives
-  chromaticity **xy = (0.31273, 0.32902)** vs the standard D65 (0.31272, 0.32903) — both tables
-  are correct and correctly indexed/interpolated. `D65_spd_tabulated(560) === 100` exactly.
-* **`xyz_cmf_wyman`** — all 7 lobe amplitudes/centres/σL/σR match Wyman–Sloan–Shirley 2013 exactly;
-  integrated white point xy = (0.31264, 0.32923).
-* **`planckian_radiance`** — `c2 = 1.438776877e-2 m·K` matches CODATA; the `exponent > 80`
-  early-out discards at most ~1e-26 of the peak, so it is numerically free.
-* **`xyz_to_hpe`** — exact Hunt-Pointer-Estévez (D65-normalised) matrix.
-* **`tonemap_aces`** — input/output matrices and the RRT+ODT rational fit match Stephen Hill's
-  `ACES.hlsl` exactly; the fit denominator has negative discriminant so there is no pole.
-* **`oklab/*`** — `linear_srgb_to_oklab`, `oklab_to_linear_srgb`, `toe`/`toe_inv`,
-  `compute_max_saturation` (all three coefficient sets + Halley step), `find_cusp`,
-  `find_gamut_intersection`, `linear_srgb_to_okhsv`, `okhsv_to_linear_srgb`,
-  `xyz_to_oklab`, `oklab_to_xyz` — all match Björn Ottosson's reference term for term.
-* **`YCbCr`** — Rec.709 full-range coefficients verified algebraically
-  (0.5/(1−Kb) = 0.53891, 0.5/(1−Kr) = 0.635 and their inverses 1.5748 / 1.8556 / 0.1873 / 0.4681).
-* **`Color.setHSL`** — matches the Wikipedia `f(n)` formulation bit-for-bit on 6 test hues.
-* **`Color.setHCL` / `setHSI`** — match the Wikipedia luma-chroma-hue and HSI formulations
-  (aside from SCI-6 below).
-* **`color_lerp`** — shortest-arc hue wrap `((h1-h0)%1 + 1.5)%1 - 0.5` is correct in both
-  directions; alpha is interpolated.
-* `rgb_to_luminance` (Rec.709), `YCoCg`, `rgb2uint24`, `int2rgb`, `hex/*`, `rgb_to_rgbe9995`,
-  `rgbe9995_to_rgb`, `sRGB_cmf`, `D65_spd_analytical` — no defects found.
-
----
-
-## Findings
-
-### SCI-1 `color_darken` / `color_lighten` / `color_saturate` / `color_desaturate` silently drop the alpha channel
-- **Severity**: MAJOR
-- **File**:
-  `H:/git/moh/app/src/mir-engine/meep/src/core/color/operations/color_darken.js:24-32`,
-  `.../color_lighten.js:24-32`,
-  `.../color_saturate.js:24-32`,
-  `.../color_desaturate.js:24-32`
-- **Defect**: each function builds `const r = new Color();` (whose constructor default is `a = 1`)
-  and then writes only R, G, B into it via `okhsv_to_linear_srgb(r, ...hsv)`. The input's alpha is
-  never copied, so every returned colour is fully opaque.
-- **Failure scenario**:
-  `color_darken(new Color(1, 0, 0, 0.25), 0.5).a` → **produced `1`**, expected `0.25`.
-  Measured identically for `color_lighten`, `color_saturate`, `color_desaturate`.
-  The reference for "expected" is this module family's own convention: the sibling
-  `color_lerp.js:44` does `r.a = lerp(color_0.a, color_1.a, _t)` and `color_lerp.spec.js:86`
-  asserts it ("alpha is interpolated linearly"). It is also self-inconsistent: the
-  `amount === 0` fast path (`color_darken.js:19-22`) returns `input` itself, so
-  `color_darken(c, 0).a === 0.25` while `color_darken(c, 1e-9).a === 1` — a discontinuity in
-  alpha at `amount → 0` that cannot be intentional.
-- **Fix**: add `r.a = input.a;` before the `return r;` in all four functions.
-- **Confidence**: Confirmed
-
----
-
-### SCI-2 `Color.prototype.parse` writes alpha outside `set()`, suppressing / corrupting the `onChanged` signal
-- **Severity**: MAJOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/color/Color.js:666-676`
-- **Defect**: `parse()` assigns `this.a = c[3]` directly and only afterwards calls
-  `setRGB(...)`, which forwards `this.a` (already the *new* value) into `set()`. `set()`
-  therefore (a) sees `_a === a` and can take the "no change" early-out, and (b) when it does
-  fire, reports the new alpha as the old alpha in the `send8(r,g,b,a,_r,_g,_b,_a)` payload.
-- **Failure scenario**: with a live listener attached (this is not hypothetical —
-  `engine/graphics/ecs/light/binding/LightBinding.js:56` and
-  `engine/graphics/ecs/decal/v2/FPDecalSystem.js:180` both subscribe to `color.onChanged`,
-  and `Light.js:105`, `Decal.js:74`, `TubePathStyle.js:180` all call `color.parse(...)`):
-
-  1. Alpha-only change is lost entirely.
-     ```js
-     const c = Color.parse('rgba(0,0,0,1)');
-     c.onChanged.add(() => fired++);
-     c.parse('rgba(0,0,0,0.5)');
-     ```
-     → `c.a === 0.5` (state did change) but **`fired === 0`**; expected `fired === 1`.
-     The bound decal/light is never rebuilt and keeps rendering at the old opacity.
-  2. Old-value payload is wrong even when RGB does change.
-     `new Color(0,0,0,1).parse('#FF000080')` fires
-     `onChanged(1, 0, 0, 0.50196, 0, 0, 0, **0.50196**)`; the 8th argument (previous alpha)
-     should be `1`, not `0.50196`.
-- **Fix**: don't touch `this.a` directly; compute the alpha locally and issue one call —
-  `const a = typeof c[3] === 'number' ? c[3] : 1; this.set(c[0]/255, c[1]/255, c[2]/255, a);`
-- **Confidence**: Confirmed
-
----
-
-### SCI-3 `rgb_to_kelvin` collapses the whole 1000–2000 K range to 1000 K
-- **Severity**: MAJOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/color/kelvin/rgb_to_kelvin.js:43-71`
-- **Defect**: the bisection solves only on the blue/red ratio `b / r`. In the forward model
-  (`kelvin_to_rgb`) blue is identically `0` for every `t <= 20` (i.e. T ≤ 2000 K) and red is
-  pinned to `1` below 6500 K, so `b/r === 0` over the entire lower fifth of the supported range.
-  The objective is flat, the bisection always takes the `br >= expected` branch, and the search
-  walks the upper bound all the way down to `minTemperature`. The green channel, which *does*
-  vary monotonically there (0.2293 at 1000 K → 0.4195 at 1500 K → 0.5441 at 2000 K), is never read.
-- **Failure scenario** (round-tripping this module's own forward function, the only defensible
-  reference for an inverse):
-  | input T | `kelvin_to_rgb` output | `rgb_to_kelvin` result | expected |
-  |---|---|---|---|
-  | 1500 K | `[1, 0.419469, 0]` | **1000** | ≈1500 (−33.3 %) |
-  | 1900 K | `[1, 0.522401, 0]` | **1000** | ≈1900 (−47.4 %) |
-  | 2000 K | `[1, 0.544074, 0]` | **1000** | ≈2000 (−50.0 %) |
-
-  Also against the vendian.org black-body table the file's sibling spec cites:
-  `rgb_to_kelvin(Color.parse('#ff4500'))` (the table's 1100 K entry) → **1000**, expected 1100.
-  Everything at 3000 K and above round-trips exactly, so this is specifically the b === 0 band.
-  `rgb_to_kelvin.spec.js` does not catch it: its only low-temperature case is the 1000 K entry.
-- **Fix**: when the target `b` is 0 (or, more uniformly, always) bisect on a residual that
-  includes green — e.g. minimise `(r_t − r)² + (g_t − g)² + (b_t − b)²` over the same bracket, or
-  bisect on `g / r` whenever `b === 0`. `g/r` is strictly monotonic over 1000–6500 K, so the
-  existing bisection structure works unchanged.
-- **Confidence**: Confirmed
-
----
-
-### SCI-4 `kelvin_to_rgb` blue cut-off is at t ≤ 20 instead of the cited fit's t ≤ 19, zeroing blue over 1900–2000 K
-- **Severity**: MINOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/color/kelvin/kelvin_to_rgb.js:23`
-- **Defect**: `const b = t <= 20 ? 0 : clamp01(...)`. Every other constant in this file is an
-  exact /255 transcription of the Bartlett fit at the cited
-  `https://www.zombieprototypes.com/?p=210` (verified: `-254.76935184120902/255 = -0.9990954974165059`,
-  `0.8274096064007395/255 = 0.0032447435545127036`, `115.67994401066147/255 = 0.453646839257496`),
-  but that source gates the blue lobe at `t <= 19`, not `t <= 20`. The extra decade of clamping
-  both suppresses real signal and enlarges the step where the lobe switches on.
-- **Failure scenario**: `kelvin_to_rgb(out, 0, 2000)` → `out[2] = 0.000000`; the cited fit gives
-  `(-254.76935 + 0.82741·10 + 115.67994·ln 10)/255 = 0.077912` (19.9/255). The vendian.org
-  black-body table that `kelvin_to_rgb.spec.js:20` cites as the fit's source data lists 2000 K as
-  `#ff8d0b`, i.e. blue = 11/255 = 0.0431 — also non-zero.
-  The visible consequence is a hard step from a 1 K input change:
-  `T = 2000 → b = 0.000000`, `T = 2001 → b = 0.078398`, a 20/255 discontinuity in the middle of any
-  colour-temperature ramp. (The file already blends the 6500/6700 K regime boundary specifically
-  "to avoid discontinuity", so continuity is an intended property here.)
-- **Fix**: change the guard to `t <= 19` to match the cited fit; or, for full continuity, clamp at
-  the fit's own zero crossing (`t ≈ 18.51`, i.e. `T ≈ 1851 K`) so the lobe starts from 0.
-- **Confidence**: Confirmed
-
----
-
-### SCI-5 `rgb2uint32` returns a *signed* int32 — negative for every colour with red ≥ 128
-- **Severity**: MINOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/color/rgb2uint32.js:17`
-  (surfaced via `Color.toUint32()`, `Color.js:489-491`)
-- **Defect**: `return (partial << 8) | (_a & 0xFF);` — `<<` coerces to int32, so as soon as the red
-  byte reaches 0x80 the shifted value sets the sign bit and the expression evaluates negative.
-  The JSDoc and the function name both promise a uint32, and the two sibling packers in the same
-  package do force unsignedness (`YCbCr_to_rgb_uint24.js:24` and `rgb_to_rgbe9995.js:57` both end
-  in `>>> 0`).
-- **Failure scenario**:
-  `new Color(1, 0, 0, 1).toUint32()` → **`-16776961`**, expected `4278190335` (`0xFF0000FF`).
-  `new Color(1, 1, 1, 1).toUint32()` → **`-1`**, expected `4294967295`.
-  Bit pattern is right, the numeric value is not: `color.toUint32() === 0xFF0000FF` is `false`,
-  and the value serialises to JSON / compares / hashes as a negative number.
-- **Fix**: `return ((partial << 8) | (_a & 0xFF)) >>> 0;`
-- **Note**: `Color.spec.js:47-66` currently encodes the present behaviour (it normalises with
-  `>>> 0` at every assertion and comments on it), so this is a deliberate-looking wart rather
-  than an unnoticed one — but it still contradicts the published contract, and the fix would let
-  those `>>> 0`s be dropped from the spec.
-- **Confidence**: Confirmed
-
----
-
-### SCI-6 `Color.setHCL` / `Color.setHSI` produce NaN for infinitesimally negative hues
-- **Severity**: MINOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/color/Color.js:332-383` (`setHCL`)
-  and `Color.js:393-447` (`setHSI`)
-- **Defect**: both normalise hue as `_h = h % 1; if (_h < 0) _h += Math.ceil(Math.abs(_h));`
-  — the modulo happens *before* the shift. For `-1.1e-16 < h < 0` the addition rounds to exactly
-  `1.0`, so `h_face = 6`, `Math.floor(h_face) === 6`, and the `switch` (cases 0–5, no `default`)
-  leaves `r`, `g`, `b` as `undefined`. `undefined + m` is `NaN`.
-  `hsv/hsv2rgb_float.js:11-17` does the same normalisation in the opposite order (shift, then
-  `% 1`) and is immune, which shows the correct ordering is already known in this package.
-- **Failure scenario**: `new Color().setHCL(-1e-17, 1, 0.5)` →
-  in a production build (asserts stripped) sets `r = g = b = NaN`; expected `(1.2, 0.2, 0.2)`,
-  the value produced for `h = 0`. Identical for `setHSI(-1e-17, 1, 0.5)`
-  (expected `(1.5, 0, 0)`). Confirmed at `h ∈ {-1e-17, -1e-18, -5e-17}`; `h = -1e-16` and larger
-  magnitudes are unaffected.
-- **Fix**: apply the modulo last, exactly as `hsv2rgb_float` does:
-  `let _h = h; if (_h < 0) { _h += Math.ceil(Math.abs(_h)); } _h = _h % 1;`
-- **Confidence**: Confirmed
-
----
-
-### SCI-7 3-digit / 4-digit CSS hex shorthand silently yields a NaN channel
-- **Severity**: MINOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/color/hex/hex2rgb.js:12-14`
-  (reached via `parse_color.js:53-61` and `Color.parse`, `Color.js:774-780`)
-- **Defect**: `hex2rgb` slices fixed byte pairs at offsets 1/3/5 and never checks the string
-  length, so for a 4-character input the blue slice is `""` and `parseInt("", 16)` is `NaN`.
-  `parse_color`'s `#`-branch has no length validation either, so it neither expands the
-  shorthand nor falls through to its `throw new Error('Failed to decode color string ...')`.
-- **Failure scenario**: `parse_color('#fff')` → **`[255, 15, NaN, 1]`**, expected `[255, 255, 255, 1]`.
-  `Color.parse('#fff')` therefore yields `r = 1, g = 0.0588, b = NaN` in a production build
-  (in a dev build `Color.set`'s `assert.notNaN` throws instead, which is why this has gone
-  unnoticed). `hex2rgb('#fff8')` → `{r: 255, g: 248, b: NaN, a: 255}`.
-  `Color.parse` documents `@throws Error if format could not be parsed` and advertises "most CSS
-  color representations", so both silent-NaN and no-throw violate the stated contract.
-- **Fix**: in `hex2rgb`, branch on `hex.length`: for 4/5-character input expand each nibble
-  (`c → cc`) before `hex2dec`; otherwise keep the current 7/9-character path. Anything else should
-  reach `parse_color`'s existing `throw`.
-- **Confidence**: Confirmed
+# Correctness review — `core/science` + `core/color`
+
+Scope: every non-spec source file under
+`meep/src/core/science/` (40 files) and `meep/src/core/color/` (47 files).
+`editor/`, `prototype*.js`, `*.spec.js` (evidence only) and `.d.ts` excluded.
+
+All findings below were reproduced by executing the actual modules under node
+(`type: module`, direct file-URL imports). Numbers quoted are measured, not derived.
+
+---
+
+## Verified-correct (no findings)
+
+Checked against the cited standard/reference and found exact:
+
+* **`science/units`** — all 7 base + 19 derived SI exponent vectors match the SI Brochure
+  (F, H, Ω, S, Wb, T, V, W, Pa, J, N, C, Hz, Bq, Gy, Sv, lm, lx, kat all correct).
+  `UnitMatrix` composition/inverse/power algebra correct and alias-safe.
+  `magnitude_prefix_index` verified exact at every one of the 21 decade boundaries
+  (`Math.log10` returns exact integers for all of 1e-30…1e30, so no off-by-one).
+  `unit_matrix_to_string` decomposition terminates and produces the documented strings;
+  `compute_scalar_power` correctly rejects fractional powers (`m/s` does not render as `Gy^0.5`).
+* **`sRGB_to_linear` / `linear_to_sRGB`** — threshold 0.04045 / 0.0031308, `1/12.92 = 0.0773993808`,
+  `1/1.055 = 0.9478672986`, `0.055/1.055 = 0.0521327014`, exponent `1/2.4 = 0.4166666666666667`.
+  All correct to ≥1e-10 relative.
+* **`rgb_to_xyz` / `xyz_to_rgb`** — exact sRGB↔XYZ D65 matrices; measured `rgb(1,1,1) → XYZ
+  (0.950456, 1.000000, 1.089058)` and an exact round trip.
+* **`xyz_cmf_tabulated` × `D65_spd_tabulated`** integrated over 360–830 nm gives
+  chromaticity **xy = (0.31273, 0.32902)** vs the standard D65 (0.31272, 0.32903) — both tables
+  are correct and correctly indexed/interpolated. `D65_spd_tabulated(560) === 100` exactly.
+* **`xyz_cmf_wyman`** — all 7 lobe amplitudes/centres/σL/σR match Wyman–Sloan–Shirley 2013 exactly;
+  integrated white point xy = (0.31264, 0.32923).
+* **`planckian_radiance`** — `c2 = 1.438776877e-2 m·K` matches CODATA; the `exponent > 80`
+  early-out discards at most ~1e-26 of the peak, so it is numerically free.
+* **`xyz_to_hpe`** — exact Hunt-Pointer-Estévez (D65-normalised) matrix.
+* **`tonemap_aces`** — input/output matrices and the RRT+ODT rational fit match Stephen Hill's
+  `ACES.hlsl` exactly; the fit denominator has negative discriminant so there is no pole.
+* **`oklab/*`** — `linear_srgb_to_oklab`, `oklab_to_linear_srgb`, `toe`/`toe_inv`,
+  `compute_max_saturation` (all three coefficient sets + Halley step), `find_cusp`,
+  `find_gamut_intersection`, `linear_srgb_to_okhsv`, `okhsv_to_linear_srgb`,
+  `xyz_to_oklab`, `oklab_to_xyz` — all match Björn Ottosson's reference term for term.
+* **`YCbCr`** — Rec.709 full-range coefficients verified algebraically
+  (0.5/(1−Kb) = 0.53891, 0.5/(1−Kr) = 0.635 and their inverses 1.5748 / 1.8556 / 0.1873 / 0.4681).
+* **`Color.setHSL`** — matches the Wikipedia `f(n)` formulation bit-for-bit on 6 test hues.
+* **`Color.setHCL` / `setHSI`** — match the Wikipedia luma-chroma-hue and HSI formulations
+  (aside from SCI-6 below).
+* **`color_lerp`** — shortest-arc hue wrap `((h1-h0)%1 + 1.5)%1 - 0.5` is correct in both
+  directions; alpha is interpolated.
+* `rgb_to_luminance` (Rec.709), `YCoCg`, `rgb2uint24`, `int2rgb`, `hex/*`, `rgb_to_rgbe9995`,
+  `rgbe9995_to_rgb`, `sRGB_cmf`, `D65_spd_analytical` — no defects found.
+
+---
+
+## Findings
+
+### SCI-1 `color_darken` / `color_lighten` / `color_saturate` / `color_desaturate` silently drop the alpha channel
+- **Severity**: MAJOR
+- **File**:
+  `H:/git/moh/app/src/mir-engine/meep/src/core/color/operations/color_darken.js:24-32`,
+  `.../color_lighten.js:24-32`,
+  `.../color_saturate.js:24-32`,
+  `.../color_desaturate.js:24-32`
+- **Defect**: each function builds `const r = new Color();` (whose constructor default is `a = 1`)
+  and then writes only R, G, B into it via `okhsv_to_linear_srgb(r, ...hsv)`. The input's alpha is
+  never copied, so every returned colour is fully opaque.
+- **Failure scenario**:
+  `color_darken(new Color(1, 0, 0, 0.25), 0.5).a` → **produced `1`**, expected `0.25`.
+  Measured identically for `color_lighten`, `color_saturate`, `color_desaturate`.
+  The reference for "expected" is this module family's own convention: the sibling
+  `color_lerp.js:44` does `r.a = lerp(color_0.a, color_1.a, _t)` and `color_lerp.spec.js:86`
+  asserts it ("alpha is interpolated linearly"). It is also self-inconsistent: the
+  `amount === 0` fast path (`color_darken.js:19-22`) returns `input` itself, so
+  `color_darken(c, 0).a === 0.25` while `color_darken(c, 1e-9).a === 1` — a discontinuity in
+  alpha at `amount → 0` that cannot be intentional.
+- **Fix**: add `r.a = input.a;` before the `return r;` in all four functions.
+- **Confidence**: Confirmed
+
+---
+
+### SCI-2 `Color.prototype.parse` writes alpha outside `set()`, suppressing / corrupting the `onChanged` signal
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/color/Color.js:666-676`
+- **Defect**: `parse()` assigns `this.a = c[3]` directly and only afterwards calls
+  `setRGB(...)`, which forwards `this.a` (already the *new* value) into `set()`. `set()`
+  therefore (a) sees `_a === a` and can take the "no change" early-out, and (b) when it does
+  fire, reports the new alpha as the old alpha in the `send8(r,g,b,a,_r,_g,_b,_a)` payload.
+- **Failure scenario**: with a live listener attached (this is not hypothetical —
+  `engine/graphics/ecs/light/binding/LightBinding.js:56` and
+  `engine/graphics/ecs/decal/v2/FPDecalSystem.js:180` both subscribe to `color.onChanged`,
+  and `Light.js:105`, `Decal.js:74`, `TubePathStyle.js:180` all call `color.parse(...)`):
+
+  1. Alpha-only change is lost entirely.
+     ```js
+     const c = Color.parse('rgba(0,0,0,1)');
+     c.onChanged.add(() => fired++);
+     c.parse('rgba(0,0,0,0.5)');
+     ```
+     → `c.a === 0.5` (state did change) but **`fired === 0`**; expected `fired === 1`.
+     The bound decal/light is never rebuilt and keeps rendering at the old opacity.
+  2. Old-value payload is wrong even when RGB does change.
+     `new Color(0,0,0,1).parse('#FF000080')` fires
+     `onChanged(1, 0, 0, 0.50196, 0, 0, 0, **0.50196**)`; the 8th argument (previous alpha)
+     should be `1`, not `0.50196`.
+- **Fix**: don't touch `this.a` directly; compute the alpha locally and issue one call —
+  `const a = typeof c[3] === 'number' ? c[3] : 1; this.set(c[0]/255, c[1]/255, c[2]/255, a);`
+- **Confidence**: Confirmed
+
+---
+
+### SCI-3 `rgb_to_kelvin` collapses the whole 1000–2000 K range to 1000 K
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/color/kelvin/rgb_to_kelvin.js:43-71`
+- **Defect**: the bisection solves only on the blue/red ratio `b / r`. In the forward model
+  (`kelvin_to_rgb`) blue is identically `0` for every `t <= 20` (i.e. T ≤ 2000 K) and red is
+  pinned to `1` below 6500 K, so `b/r === 0` over the entire lower fifth of the supported range.
+  The objective is flat, the bisection always takes the `br >= expected` branch, and the search
+  walks the upper bound all the way down to `minTemperature`. The green channel, which *does*
+  vary monotonically there (0.2293 at 1000 K → 0.4195 at 1500 K → 0.5441 at 2000 K), is never read.
+- **Failure scenario** (round-tripping this module's own forward function, the only defensible
+  reference for an inverse):
+  | input T | `kelvin_to_rgb` output | `rgb_to_kelvin` result | expected |
+  |---|---|---|---|
+  | 1500 K | `[1, 0.419469, 0]` | **1000** | ≈1500 (−33.3 %) |
+  | 1900 K | `[1, 0.522401, 0]` | **1000** | ≈1900 (−47.4 %) |
+  | 2000 K | `[1, 0.544074, 0]` | **1000** | ≈2000 (−50.0 %) |
+
+  Also against the vendian.org black-body table the file's sibling spec cites:
+  `rgb_to_kelvin(Color.parse('#ff4500'))` (the table's 1100 K entry) → **1000**, expected 1100.
+  Everything at 3000 K and above round-trips exactly, so this is specifically the b === 0 band.
+  `rgb_to_kelvin.spec.js` does not catch it: its only low-temperature case is the 1000 K entry.
+- **Fix**: when the target `b` is 0 (or, more uniformly, always) bisect on a residual that
+  includes green — e.g. minimise `(r_t − r)² + (g_t − g)² + (b_t − b)²` over the same bracket, or
+  bisect on `g / r` whenever `b === 0`. `g/r` is strictly monotonic over 1000–6500 K, so the
+  existing bisection structure works unchanged.
+- **Confidence**: Confirmed
+
+---
+
+### SCI-4 `kelvin_to_rgb` blue cut-off is at t ≤ 20 instead of the cited fit's t ≤ 19, zeroing blue over 1900–2000 K
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/color/kelvin/kelvin_to_rgb.js:23`
+- **Defect**: `const b = t <= 20 ? 0 : clamp01(...)`. Every other constant in this file is an
+  exact /255 transcription of the Bartlett fit at the cited
+  `https://www.zombieprototypes.com/?p=210` (verified: `-254.76935184120902/255 = -0.9990954974165059`,
+  `0.8274096064007395/255 = 0.0032447435545127036`, `115.67994401066147/255 = 0.453646839257496`),
+  but that source gates the blue lobe at `t <= 19`, not `t <= 20`. The extra decade of clamping
+  both suppresses real signal and enlarges the step where the lobe switches on.
+- **Failure scenario**: `kelvin_to_rgb(out, 0, 2000)` → `out[2] = 0.000000`; the cited fit gives
+  `(-254.76935 + 0.82741·10 + 115.67994·ln 10)/255 = 0.077912` (19.9/255). The vendian.org
+  black-body table that `kelvin_to_rgb.spec.js:20` cites as the fit's source data lists 2000 K as
+  `#ff8d0b`, i.e. blue = 11/255 = 0.0431 — also non-zero.
+  The visible consequence is a hard step from a 1 K input change:
+  `T = 2000 → b = 0.000000`, `T = 2001 → b = 0.078398`, a 20/255 discontinuity in the middle of any
+  colour-temperature ramp. (The file already blends the 6500/6700 K regime boundary specifically
+  "to avoid discontinuity", so continuity is an intended property here.)
+- **Fix**: change the guard to `t <= 19` to match the cited fit; or, for full continuity, clamp at
+  the fit's own zero crossing (`t ≈ 18.51`, i.e. `T ≈ 1851 K`) so the lobe starts from 0.
+- **Confidence**: Confirmed
+
+---
+
+### SCI-5 `rgb2uint32` returns a *signed* int32 — negative for every colour with red ≥ 128
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/color/rgb2uint32.js:17`
+  (surfaced via `Color.toUint32()`, `Color.js:489-491`)
+- **Defect**: `return (partial << 8) | (_a & 0xFF);` — `<<` coerces to int32, so as soon as the red
+  byte reaches 0x80 the shifted value sets the sign bit and the expression evaluates negative.
+  The JSDoc and the function name both promise a uint32, and the two sibling packers in the same
+  package do force unsignedness (`YCbCr_to_rgb_uint24.js:24` and `rgb_to_rgbe9995.js:57` both end
+  in `>>> 0`).
+- **Failure scenario**:
+  `new Color(1, 0, 0, 1).toUint32()` → **`-16776961`**, expected `4278190335` (`0xFF0000FF`).
+  `new Color(1, 1, 1, 1).toUint32()` → **`-1`**, expected `4294967295`.
+  Bit pattern is right, the numeric value is not: `color.toUint32() === 0xFF0000FF` is `false`,
+  and the value serialises to JSON / compares / hashes as a negative number.
+- **Fix**: `return ((partial << 8) | (_a & 0xFF)) >>> 0;`
+- **Note**: `Color.spec.js:47-66` currently encodes the present behaviour (it normalises with
+  `>>> 0` at every assertion and comments on it), so this is a deliberate-looking wart rather
+  than an unnoticed one — but it still contradicts the published contract, and the fix would let
+  those `>>> 0`s be dropped from the spec.
+- **Confidence**: Confirmed
+
+---
+
+### SCI-6 `Color.setHCL` / `Color.setHSI` produce NaN for infinitesimally negative hues
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/color/Color.js:332-383` (`setHCL`)
+  and `Color.js:393-447` (`setHSI`)
+- **Defect**: both normalise hue as `_h = h % 1; if (_h < 0) _h += Math.ceil(Math.abs(_h));`
+  — the modulo happens *before* the shift. For `-1.1e-16 < h < 0` the addition rounds to exactly
+  `1.0`, so `h_face = 6`, `Math.floor(h_face) === 6`, and the `switch` (cases 0–5, no `default`)
+  leaves `r`, `g`, `b` as `undefined`. `undefined + m` is `NaN`.
+  `hsv/hsv2rgb_float.js:11-17` does the same normalisation in the opposite order (shift, then
+  `% 1`) and is immune, which shows the correct ordering is already known in this package.
+- **Failure scenario**: `new Color().setHCL(-1e-17, 1, 0.5)` →
+  in a production build (asserts stripped) sets `r = g = b = NaN`; expected `(1.2, 0.2, 0.2)`,
+  the value produced for `h = 0`. Identical for `setHSI(-1e-17, 1, 0.5)`
+  (expected `(1.5, 0, 0)`). Confirmed at `h ∈ {-1e-17, -1e-18, -5e-17}`; `h = -1e-16` and larger
+  magnitudes are unaffected.
+- **Fix**: apply the modulo last, exactly as `hsv2rgb_float` does:
+  `let _h = h; if (_h < 0) { _h += Math.ceil(Math.abs(_h)); } _h = _h % 1;`
+- **Confidence**: Confirmed
+
+---
+
+### SCI-7 3-digit / 4-digit CSS hex shorthand silently yields a NaN channel
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/color/hex/hex2rgb.js:12-14`
+  (reached via `parse_color.js:53-61` and `Color.parse`, `Color.js:774-780`)
+- **Defect**: `hex2rgb` slices fixed byte pairs at offsets 1/3/5 and never checks the string
+  length, so for a 4-character input the blue slice is `""` and `parseInt("", 16)` is `NaN`.
+  `parse_color`'s `#`-branch has no length validation either, so it neither expands the
+  shorthand nor falls through to its `throw new Error('Failed to decode color string ...')`.
+- **Failure scenario**: `parse_color('#fff')` → **`[255, 15, NaN, 1]`**, expected `[255, 255, 255, 1]`.
+  `Color.parse('#fff')` therefore yields `r = 1, g = 0.0588, b = NaN` in a production build
+  (in a dev build `Color.set`'s `assert.notNaN` throws instead, which is why this has gone
+  unnoticed). `hex2rgb('#fff8')` → `{r: 255, g: 248, b: NaN, a: 255}`.
+  `Color.parse` documents `@throws Error if format could not be parsed` and advertises "most CSS
+  color representations", so both silent-NaN and no-throw violate the stated contract.
+- **Fix**: in `hex2rgb`, branch on `hex.length`: for 4/5-character input expand each nibble
+  (`c → cc`) before `hex2dec`; otherwise keep the current 7/9-character path. Anything else should
+  reach `parse_color`'s existing `throw`.
+- **Confidence**: Confirmed