Scripts get five types: int, byte, bool, fixed and string

.github/workflows/release.yml

@@ -29,6 +29,10 @@ on:
       - 'test/**'
       - 'esp32/**'
       - 'moondeck/build/**'
+      # package_desktop.py builds and packages the three desktop jobs; without this line a
+      # packaging fix cannot trigger the jobs that run it (the NSIS-escape fix needed a
+      # manual dispatch because only moondeck/ci changed).
+      - 'moondeck/ci/**'
       - 'CMakeLists.txt'
       - 'library.json'
       - '.github/workflows/release.yml'

CLAUDE.md

@@ -33,7 +33,7 @@ fix, keeping main clean) — creating one silently moves work somewhere the PO i
 
 1. **Pick.** One module/effect/driver/capability — the product owner picks what to build next.
 2. **Spec.** Specs before code: the module spec and the UI spec sufficient to implement from (a draft may sit in the backlog until it ships); when in doubt, ask.
-3. **Plan.** Plan mode before every feature; save the approved plan to `docs/history/plans/` as `Plan-YYYYMMDD - <title>.md` — a temporary document: it ends up as the PR description and the file is deleted once the plan is realized; the merged PR is the design record. **Deleting a plan is the product owner's call — never the agent's.** "The code is written" is not "the plan is realized": a plan is realized when its *verification* is done too, including the judgement steps (thresholds tuned, results read together, the bench check). Ask; do not infer it from a green build. For a restructure ("make it simpler/cleaner"): enumerate 2–4 end states, name what each gains and loses, pick the leanest that solves the actual problem; propose as a question, implement only what's picked; surface follow-ups before starting so it's one coherent refactor.
+3. **Plan.** Plan mode before every feature; save the approved plan to `docs/history/plans/` as `Plan-YYYYMMDD - <title>.md` — a temporary document: it ends up as the PR description and the file is archived once the plan is realized; the merged PR is the design record. **Archiving a plan is the product owner's call — never the agent's.** "The code is written" is not "the plan is realized": a plan is realized when its *verification* is done too, including the judgement steps (thresholds tuned, results read together, the bench check). Ask; do not infer it from a green build. For a restructure ("make it simpler/cleaner"): enumerate 2–4 end states, name what each gains and loses, pick the leanest that solves the actual problem; propose as a question, implement only what's picked; surface follow-ups before starting so it's one coherent refactor.
 
 ### Build
 

docs/backlog/moonlive-language-roadmap.md

@@ -35,7 +35,7 @@ Five hard limits, all found by hitting them:
 | script state | **64 bytes** shared by all members | `kCtrlBytes`, `MoonLiveBuiltins.h:132` |
 | distinct members | **8** | `kMaxCtrls`, same file |
 | branch labels | **16** (an `if` or `for` takes up to 2) | `kIrLabels`, `MoonLiveIr.h:201` |
-| numeric types | `uint8_t`, `uint16_t`, `int16_t` | no float |
+| ~~numeric types~~ | ~~`uint8_t`, `uint16_t`, `int16_t`~~ → **`int`, `byte`, `bool`, `fixed`, `string`** ✅ | still no float: `fixed` is Q16.16 |
 | ~~builtin table~~ | ~~16, and 16 used~~ → **64** ✅ | `BuiltinTable::kMax` — raised, with an overflow assert |
 
 The branch budget was binary-searched with generated scripts: **6 `if`/`else` + 2 `for` compiles,
@@ -102,6 +102,31 @@ Item 5 is worth noting against the arena work below: a particle pool as a HANDLE
 does not spend its own 64 bytes on particle state at all. That is a better answer than widening
 the arena, and it is already designed.
 
+## The type system: ✅ *shipped*
+
+Shipped as designed, with three things worth carrying forward that the design did not anticipate:
+
+- **`fixed` needed three new assembler primitives**, not the one the design implied. A Q16.16
+  multiply is `mulhi` + `mul` + two shifts, and the JIT had no shift instruction and no
+  multiply-high at all — `mulReg` is a plain 32-bit multiply. `shlImm`, `sarImm`, `shrImm` and
+  `mulhi` went into all four backends, every encoding checked byte-for-byte against the real
+  assembler. Worth it: the alternative made every fixed multiply a host call inside a per-pixel
+  loop, and made `int`↔`fixed` conversion — one shift — a function call.
+- **An integer literal ADOPTS fixed at a meet point.** The design said any mix is an error; that
+  made `v * 2` and `if (v < 0)` unwritable. A bare literal now converts at compile time by
+  patching its own `Const` (free at run time), while a *variable* still names its conversion,
+  because a literal's meaning is visible at the site and a variable's scaling is not.
+- **`movImm` truncated above 16 bits on arm64 and Xtensa.** A latent bug the whole time, masked
+  `& 0xffff` under a comment warning about exactly that failure mode: invisible while literals
+  capped at 65535, and fatal the moment a Q16.16 literal (2.0 is 131072) rode a `Const`. Both
+  backends now materialize the full 32 bits.
+
+`bool` truncates rather than normalizing (`flag = 256` reads false), because normalizing needs a
+compare-and-select the IR has no op for — there is no `Sub` and no bitwise op. Waiting for a script
+that writes a non-boolean expression into a bool.
+
+The design as agreed follows, unchanged.
+
 ## The type system: the settled design (2026-08-23)
 
 Decided with the product owner after the signed-values work, whose four bugs were all

docs/history/lessons.md

@@ -590,3 +590,17 @@ evidence which *looks* most authoritative here is the evidence that lies.
   next one reporting a stale runner, a self-inflicted loop that reads exactly like a real staleness
   failure. **Generated build metadata is not source**, and a guard that cannot tell them apart
   teaches people to ignore it.
+
+- **An ISA-guarded test is not run by the machine that wrote it, and a JIT's bytes are only true
+  where they execute.** The MoonLive backends are `#if`-guarded per architecture, so an arm64 bench
+  compiles neither the x86-64 encoder tests nor the x86-64 emitted code — a whole backend can be
+  wrong while the local suite is green and confident. A Q16.16 multiply that borrowed a register the
+  allocator hands out returned garbage on every x86-64 desktop; 1458 local tests passed, and CI is
+  where it surfaced. Two smaller defects hid in the same blind spot: a one-byte arena where the code
+  now does a 32-bit load, and an unmigrated type keyword in a test file arm64 never compiles.
+
+  **On an Apple Silicon machine that blind spot is one command wide:** `cmake -B build/x86
+  -DCMAKE_OSX_ARCHITECTURES=x86_64` then `arch -x86_64 ./build/x86/test/mm_tests`. Rosetta runs the
+  emitted x86-64 instructions for real, so the tests that only exist on that host actually execute.
+  Worth doing on any change to a backend, an encoder, or the register allocator — it is minutes,
+  and it is the difference between finding these locally and finding them in CI.

docs/history/plans/Plan-20260823 - Five types for MoonLive scripts.md

@@ -0,0 +1,105 @@
+# Plan, five types for MoonLive scripts
+
+## Context
+
+MoonLive scripts spelled C storage widths: `uint8_t`, `uint16_t`, `int16_t`. That convention produced
+four shipped bugs of one family, each presenting as "the effect renders nothing" or "the effect
+renders wrong" and never as an error:
+
+- `sin(a) - 32768` wrapped the sine's negative half to ~4.29 billion.
+- `(uvX(...) - 32768) * zoom` did the same on the left half of a grid, tearing the plane into blocks.
+- A `d = 60000` sentinel read back as -5536 through a 16-bit window, so every light stayed black.
+- A one-byte store into a two-byte member collapsed a whole shader to one flat colour.
+
+Not one was a mistake in a script. Each was a script author choosing a storage width and the engine
+silently disagreeing. The product owner and the agent settled the replacement in
+[moonlive-language-roadmap.md](../../backlog/moonlive-language-roadmap.md): **five types — `int`,
+`byte`, `bool`, `fixed`, `string` — each usable as scalar or array. Every scalar occupies one uniform
+4-byte slot; arrays pack by element.** A type becomes a semantic rather than a width, which deletes
+the machinery instead of patching it a fifth time.
+
+The timing was the argument: MoonLive is unlaunched, `MIGRATING.md:9` exempts it explicitly, and the
+26 shipped scripts were ours to rewrite. After launch it becomes a compatibility program forever.
+
+Approved scope: all five types in one branch, including `fixed` and `string`.
+
+## Approach
+
+### Storage: one slot, whatever the type
+
+| Type | Scalar | Array element | Control |
+|---|---|---|---|
+| `int` | 4 bytes | 4 bytes | `Int32` (new) |
+| `byte` | 4-byte slot, narrowed by the store | 1 byte | `Uint8` (a 0..255 slider) |
+| `bool` | 4-byte slot, narrowed by the store | 1 byte | `Bool` |
+| `fixed` | 4 bytes, Q16.16 | (refused, see below) | none |
+| `string` | 4 bytes (pool offset) | not allowed | none |
+
+The width question survives only in arrays, where it pays for itself: a `byte[]` heat map costs a
+quarter of an `int[]` one, and the classic ESP32 has no PSRAM to absorb the difference.
+
+### Typing without an AST
+
+The compiler is single-pass with no tree, so a type rides alongside the value: every parse function
+sets `exprIsFixed` before returning, and the places where two values meet compare it. `byte` and
+`bool` decay to `int` on read — they are semantics on storage, not on arithmetic — so the question is
+only ever "is this Q16.16 or a plain integer".
+
+Mixing is a compile error naming the conversion, because at run time the two are the same 32 bits.
+The exception is an integer **literal**, which adopts the fixed side by patching its own already
+emitted `Const` (free at run time), so `v * 2`, `if (v < 0)` and `c = 5;` read naturally while a
+*variable* keeps the explicit rule: a literal's meaning is visible at the site, a variable's is not.
+
+### `fixed` gets real instructions
+
+The JIT had no shift primitive and no multiply-high — `mulReg` is a plain 32-bit multiply and `/` was
+already a host call. Routing `fixed` through host builtins would have put a call in every per-pixel
+multiply and made `int`↔`fixed` conversion — one shift — a function call. So four primitives went
+into all four backends: `mulhi`, `shlImm`, `shrImm`, `sarImm`, plus 32-bit slot access.
+
+A fixed multiply is `Mulhi + Mul + two shifts`. A fixed divide goes through a **host** call (`fdiv`)
+that widens in int64: any 32-bit pre-shift wraps past |128.0|, which is exactly the range shaders use.
+
+### One control declaration
+
+`addUint8`/`addUint16` collapse into `addControl(name, member, min, max)`, which reads the widget from
+the member's declared type — so a call and a declaration can no longer disagree. A `byte` control's
+descriptor points at its slot's low byte, which is only sound because the store narrows: the upper
+three bytes are always zero.
+
+## Verification
+
+- The unit suite and 20 scenario tests, all 11 pre-commit gates, on arm64 AND on x86-64
+  under Rosetta — the x86-only tests no arm64 run compiles are where two defects hid.
+- Every shipped script compiles, on the host backend and on both device ISAs.
+- `disasm.py` on all four backends, reading the emitted sequences by eye.
+- On hardware: desktop and an ESP32-S3 (shiffy), with the product owner's eyes on metal, fractal,
+  ripples, plasma and ember.
+
+## What the design did not anticipate
+
+Recorded because the plan was wrong about them, and the next reader should not re-derive them:
+
+- **`fixed` needed four assembler primitives, not zero.** The design assumed the shifts existed.
+- **Literal adoption had to be added.** The design said any mix is an error; that made `v * 2`
+  unwritable, and the language would have been unusable for shaders.
+- **Two latent bugs surfaced that predate the branch**: `movImm` silently masked constants to 16 bits
+  on arm64 and Xtensa (invisible until a Q16.16 literal rode one), and arena seeding wrote a single
+  byte (so `int neg = -100` seeded as 156).
+- **`fixed[]` is refused, not shipped.** Element type-tracking needs the array's type to reach both
+  the read and the write; scalars get that from their declaration, elements would need it per array.
+  Parity with `string[]`, deferred until a script needs it.
+- **`bool` truncates on store rather than normalizing** (`flag = 256` reads false): normalizing in
+  the emitted code needs a compare-and-select the IR has no op for, and a branch would spend two of
+  the script's sixteen labels. The byte IS normalized where it matters — at publish time, before
+  the UI binding reads it through a `bool*`, which would otherwise be undefined behaviour.
+- **`string` is declared but inert** — a string member cannot be initialized yet, and says so.
+
+## The lesson that cost the most
+
+Every hand-built Xtensa encoding was byte-reversed. The two ESP toolchain objdumps print different
+conventions — `esp32-elf` shows the 24-bit word, `esp32s3-elf` shows memory bytes — so verifying
+against the wrong one "matched" while emitting every instruction backwards. The reversed `slli`
+decoded as `l32r a1`, a stack-pointer clobber that hung the board with no panic text while all 1400+
+host tests stayed green. Encoders now build words and emit through `emit3`/`emit2`, as the
+pre-existing ones always did.

docs/metrics/repo-health.json

@@ -1,137 +1,78 @@
 {
-<<<<<<< HEAD
-  "commit": "4c91f700",
-=======
-  "commit": "ab508402",
->>>>>>> main
+  "commit": "f985a366",
   "flash": {
+    "esp32s3-n16r8": 1820752,
+    "desktop": 1231192,
     "esp32": 1764416,
     "esp32p4rev1-eth": 1653696,
     "esp32p4rev1-eth-wifi": 1933472,
-<<<<<<< HEAD
-    "esp32s3-n16r8": 1804944,
-=======
-    "esp32s3-n16r8": 1813456,
->>>>>>> main
     "esp32s3-n8r8": 1753232,
     "esp32s31": 2079904,
     "esp32-16mb": 1714608,
     "esp32-eth": 1324816,
     "esp32-wrover": 1765504,
     "qemu": 1318160,
-    "esp32p4rev3-eth": 1643760,
-<<<<<<< HEAD
-    "desktop": 1214976
+    "esp32p4rev3-eth": 1643760
   },
   "perf": {
     "desktop": {
-      "tick_us": 356,
-      "fps": 2808
-=======
-    "desktop": 1230168
-  },
-  "perf": {
-    "desktop": {
-      "tick_us": 182,
-      "fps": 5494
->>>>>>> main
+      "tick_us": 259,
+      "fps": 3861
     },
     "esp32": {
       "tick_us": 2151,
       "fps": 464
     }
   },
   "loc": {
-<<<<<<< HEAD
-    "core": 19600,
-    "light": 25712,
-    "platform": 14900,
-    "ui": 7023,
-    "test": 45720,
-    "moondeck": 21801
+    "core": 20117,
+    "light": 25873,
+    "platform": 15128,
+    "ui": 7047,
+    "test": 46792,
+    "moondeck": 21847
   },
   "comments": {
     "core": {
-      "lines": 7693,
-      "ratio": 0.425
-=======
-    "core": 19684,
-    "light": 25824,
-    "platform": 14891,
-    "ui": 7028,
-    "test": 45902,
-    "moondeck": 21626
-  },
-  "comments": {
-    "core": {
-      "lines": 7746,
+      "lines": 7929,
       "ratio": 0.426
->>>>>>> main
     },
     "light": {
-      "lines": 10237,
+      "lines": 10271,
       "ratio": 0.438
     },
     "platform": {
-<<<<<<< HEAD
-      "lines": 5306,
-      "ratio": 0.391
-    },
-    "ui": {
-      "lines": 1857,
-      "ratio": 0.281
-    },
-    "test": {
-      "lines": 8377,
-      "ratio": 0.21
-    },
-    "moondeck": {
-      "lines": 3507,
-      "ratio": 0.184
-    }
-  },
-  "tests": {
-    "cases": 1493,
-    "scenarios": 23
-  },
-  "docs": {
-    "md_files": 191,
-    "md_lines": 27684,
-    "plans_files": 97,
-    "backlog_lines": 4319,
-=======
-      "lines": 5303,
-      "ratio": 0.391
+      "lines": 5379,
+      "ratio": 0.39
     },
     "ui": {
-      "lines": 1861,
-      "ratio": 0.281
+      "lines": 1874,
+      "ratio": 0.282
     },
     "test": {
-      "lines": 8438,
-      "ratio": 0.211
+      "lines": 8658,
+      "ratio": 0.212
     },
     "moondeck": {
-      "lines": 3504,
+      "lines": 3529,
       "ratio": 0.185
     }
   },
   "tests": {
-    "cases": 1511,
+    "cases": 1565,
     "scenarios": 23
   },
   "docs": {
-    "md_files": 189,
-    "md_lines": 27631,
-    "plans_files": 96,
-    "backlog_lines": 4341,
->>>>>>> main
-    "lessons_lines": 576,
+    "md_files": 192,
+    "md_lines": 28089,
+    "plans_files": 98,
+    "backlog_lines": 4451,
+    "lessons_lines": 592,
     "claude_md_lines": 136
   },
   "complexity": {
-    "functions": 2716,
-    "over_threshold": 165,
+    "functions": 2745,
+    "over_threshold": 168,
     "worst_ccn": 108
   }
 }