A MoonLive script is a class, with functions it can call

[ewowi]

A MoonLive script was a bag of statements that did not resemble the compiled module it stands
in for. It is a class now: it declares a name, defines the functions the host calls, and can
define functions of its own and call them, including calling itself.

Three commits, in the order they had to happen:

1. One lowering for every backend, one vocabulary for every script, the subtraction that
   made the rest affordable.
2. A MoonLive script is a class, the grammar's only top-level form, with named entry points
   per role.
3. A script calls its own functions, and itself: real calls with a frame per activation, and
   a runtime depth guard.

One lowering, every backend

src/core/moonlive/moonlive_lower.h holds the IR walk as a template over the assembler. 537
lines of triplicated algorithm became 190 shared plus 62 of adapter, and the three
moonlive_lower_*.cpp files lost 495 lines between them.

What is genuinely per-target turned out to be only the encodings, and those already lived behind
the assembler: no frame constant, register name or instruction appears in any of the three
backend files. The host's apparent differences (a Mov that added zero, a two-instruction
branch, a FillElems using a third scratch register) were free choices rather than ISA facts, so
it gained movReg/branchGeU/branchNe and adopted the devices' FillElems.

Evidence it preserved behavior: all four boards emitted byte-identical exec blocks to the
three-file version. Rose 1880 B, ripples 2372 B, plasma 1124 B, unchanged on S3, classic ESP32,
P4 and S31.

One vocabulary, every script

lightSysVars() serves all three roles; the role-named accessors remain as aliases, so no call
site changed.

The split it replaces prevented no mistake, since a layout reading width got a compile error,
which is the same outcome as reading a value that is always zero. What it did create was a trap:
the tables were different vocabularies rather than nested ones, so disasm.py compiled against
the widest and refused grid.mlv, the shipped default layout, as "name is a system variable". A
modifier's coordinate is xPos/yPos/zPos now, which frees x/y/z as the loop counters
an author reaches for.

A script is a class

class CrosshairEffect {
  uint8_t bpm = 30;   // @control 1..240

  column() { for (y = 0; y < height; y = y + 1) { setRGB(y * width + scale(beat(bpm, t), width), 255, 40, 0); } }
  tick()   { fill(0, 0, 0); column(); }
}

Mandatory, not optional. Keeping a bare statement list would mean a second parse path, a
second set of rules to document and a second thing to test, permanently, so that a handful of
two-line scripts can stay two lines. Nothing is released yet, so the cost is rewriting the
shipped scripts once. All 17 are converted.

The moment model. A function is called when it is present and its moment arrives: tick for
an effect, placeLights for a layout, modifyLogical for a modifier. Role is not inferred from
the class name, and nothing forbids a class defining several: the script author is in control and
responsible. This is what makes step 5's "which kind is this binding" question a dispatch
question rather than an inheritance one.

forEachCoord is renamed placeLights, in scripted and compiled code, because a scripted
effect and a compiled one should look as alike as possible. The old name described the mechanism
(a loop over coordinates) rather than the moment (place your lights).

A script calls its own functions, and itself

Real calls, not text pasted in by the compiler: the callee allocates its own frame when it runs,
which is what lets one helper call another and what makes recursion work. A function takes no
arguments and returns nothing yet, so a helper does a whole job rather than computing a value.
Helpers must be declared above their callers; a function can always call itself.

Recursion is bounded at run time. A render task has a fixed stack, so unbounded recursion
would reset the device, which the robustness rule forbids. The guard lives in the callee's
prologue and refuses by returning, so there is no branch-around at the call site and no counter
to restore across a call. It is one arena byte, and it is emitted only for a script that actually
contains a call, so every shipped script is byte-identical to before.

The classic ESP32 ran a deliberately non-terminating script for 110 seconds at 109 fps without
resetting. The deepest calls do nothing; the picture is wrong where the recursion stopped.

Four defects behind this, every one invisible to a green test suite:

• IrProgram::swap() did not swap the function table, so the spill pass's remapped boundaries
  went into the discarded half and the lowering opened a frame two ops early, mid-statement.
• CallScript carried an IR index, which the spill pass invalidates: it inserts a Reload
  before a read, so every index past the first insertion shifts. It carries a function number now,
  which survives any rewrite.
• Xtensa function entries were not 4-byte aligned. The toolchain rejects an unaligned entry
  outright (Error: unaligned entry instruction) and CALLn encodes its target in 4-byte units, so
  an unaligned callee is not expressible at all. Instructions are 2 or 3 bytes, so a function
  following another lands anywhere. alignForEntry() pads, which is what .align 4 does in
  hand-written assembly.
• A local call passed no arguments. Each prologue parks buf/nLights/cpl/t/ctrls out of the
  argument registers into its own frame, so a bare call left the callee parking garbage and its
  first control read faulted at EXCVADDR 0x9. On Xtensa they go in a10..a14, since call8
  rotates the window by 8.

Performance

Flash	classic ESP32 1723295 to 1726027 bytes, +2732 (+0.16%)
Calling script	crosshair.mlv 204 to 219 us on the classic (~5-10%)
Non-calling script	unchanged, no guard code emitted
Compile-path stack	lowerWith 480 to 1120 bytes (17% of the 12 KB main task)
Desktop tick	150 to 133 us across the cycle

The flash figure is measured by building at the branch point and again with the work, not read
off a metrics diff. It is ~20 bytes per net line of source, which is high because nearly all of
it is emitter code instantiated once per backend: one line of the shared lowering becomes three
copies of emitted-instruction sequences in the image.

The stack growth is kAsmLabels/kAsmFixups going 16/32 to 48/96, because a class allocates a
label per function and crosshair.mlv exhausted the old table. Both constants moved into core,
so the three backends can no longer disagree about which scripts compile.

Tests

Argument passing one and two calls deep, an empty function not consuming the recursion budget,
unbounded recursion that must return and be runnable again at full depth, an over-long function
name refused rather than truncated, and per-ISA "every function in a class starts where a call can
reach it". Each was control-checked by reverting its fix and confirming it fails.

The structural checker gained a calling class and a recursive one, so every prologue it walks now
carries the argument reload and the depth guard. Control-checked by dropping the window reserve
from the frame calculation.

One honest limitation, written into the tests: the host backend cannot pin the
argument-passing contract. Its R0..R4 map onto the arm64 ABI argument registers and bl leaves
them alone, so removing the fix fails nothing there while crashing an S3. The boards are the only
check for that class of defect.

Review

This branch is 104 files, past the size where CodeRabbit declines to review, so the Reviewer
agent over the whole branch diff is the only review layer it gets. It returned 9 findings; all are
applied:

• The blocker: two test names were wrapped in mmScript(...) by a mechanical sweep, so doctest
  reported them as multi-line class T { tick() { ... } } blocks. Worse, mmScript returns a
  pointer into a rotating buffer, so a failing test could report another test's script text.
• The scratch-register comment described a conditional reservation the code does not do.
  Investigating it showed the clamp is now load-bearing: the depth guard uses both shared registers
  in a script that may contain no inline op. The code was right, the comment was wrong, and the
  dead ternary is gone.
• kEntryForEachCoord still carried the deleted name while holding "placeLights".
• Test comments still taught the abolished per-role vocabulary.
• A robustness gap: function names over 23 characters truncated silently, so two sharing a
  prefix collided into one entry and entry() returned the first: wrong-function dispatch with no
  error. Refused at parse time now, where a control name already is.
• Entry-lookup double-scanning, plan text naming the old function, a stray blank line, and two
  backlog items filed under ## HTTP and OTA that belong under ## Architecture.

One finding deferred with a reason: the bindings scan the entry table twice per call
(hasEntry then run). Today that is the cold rebuild path and costs little, but it becomes a
real hot-path cost when modifyLogicalTick arrives. Caching the CtrlFn at compile success is the
fix, and it belongs with that step rather than here.

Also

• A prose check, moondeck/check/check_prose.py: em-dashes and British spellings in ADDED
  lines. Both rules were written down and then broken repeatedly, including in the commits that
  swept them out of other files, so they needed a check that fails rather than an intention to do
  better. Not yet registered in the gate table: it reports pre-existing instances that are a
  separate sweep from this branch.
• MIGRATING is exempt for MoonLive until it launches. Nobody runs scripts on a device yet, so
  an entry documents an upgrade path no user can take. The two pre-launch entries are removed and
  the policy is written down.
• CLAUDE.md: running a gate script to check work in progress is still starting a gate list,
  which is the product owner's to fire.
• Catalog pages corrected: MoonLiveLayout.md and MoonLiveModifier.md still showed tick()
  as the entry point after the rename, so they taught scripts that do not work.
• lessons.md gains the branch's methodological traps, the sharpest being that a tidier
  emitted block can be the broken one: removing the spill pass's boundary remap makes
  crosshair.mlv disassemble better and keeps every host test green, and boot-loops an S3.

Plans

Plan-20260813 is closed and marked (shipped). Step 5 was dropped ("delete the allocator"
assumed the stack machine makes spilling unreachable; it does not) and step 7 superseded (a shared
binding base needs virtual inheritance and would change the layout of every module in the system to
serve three of them).

Plan-20260817 takes over and stays open: step 1 and verification items 1, 2 and 5 are done;
steps 2, 3 and 5-10 remain (typed members, defineControls(), if/else, reading a light back,
arrays, wider-than-a-byte values, the editing loop).

One item is done with a caveat. Verification item 5 asked that a runaway recursion report an
error. It does not: the refusal is silent. Reporting it needs a diagnostic channel from the emitted
block back to the binding, which does not exist yet.

Verification

All nine mechanical pre-merge gates green. All three ISAs build clean; all four firmware variants
rebuilt. crosshair.mlv verified running on S3, S31, classic ESP32 and P4.

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 8f0f9c38-ed79-41cf-82d8-ad5410c17c8e

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[MoonModules]

@coderabbitai, can you review 22ae7f5 and report your findings in copy pastable content for agents