Promote measured Release-only Wasm size optimizations

Author: CryZe

Cargo.toml

@@ -25,7 +25,8 @@ splitscript-syntax = { path = "crates/splitscript-syntax" }
 serde = { version = "1.0.229", features = ["derive"] }
 serde_json = "1.0.151"
 gimli = { version = "0.33.0", default-features = false, features = ["write"] }
-wasm-encoder = "0.254.0"
+wasm-encoder = { version = "0.254.0", default-features = false, features = ["std", "wasmparser"] }
+wasmparser = { version = "0.254.0", default-features = false, features = ["std"] }
 
 [target.'cfg(not(target_arch = "wasm32"))'.dependencies]
 clap = { version = "4.6", features = ["derive"] }

TODO.md

@@ -978,15 +978,18 @@ concepts rather than maintaining a parallel inventory.
 
 ## P1 — reduce generated Wasm size with Release-only compiler optimizations
 
-Schedule this as a separate compiler project after the current Unity goal is
-finished. It is not part of Unity parity or a prerequisite for fixing the size
-regressions introduced by that work. Optimize final Wasm byte size; leave
-execution-speed optimization to the WebAssembly engine. Keep Debug builds out
-of these passes so stepping and source correspondence remain straightforward.
+The [promoted size pipeline](docs/WASM_SIZE_OPTIMIZATION.md) performs bounded
+Release-only instruction, integer-constant, dead-code, local and control-flow
+cleanup, shared returns, and sharing of bodies differing in integer constants.
+It saves 7.0% / 7.2% on Minish Cap / Lunistice. Debug bypasses all passes.
+Inlining, temporary sinking and propagation remain on the experimental branch;
+their remaining real-script benefit does not yet justify promotion. Prefer
+measured savings on real scripts over large synthetic fixtures. Direct emitter
+fixes that add no analysis may apply to both profiles.
 
 Implement in this order:
 
-1. [ ] Establish a representative Release size corpus, including small native
+1. [x] Establish a representative Release size corpus, including small native
    scripts, explicit-profile and automatic-profile Unity scripts, nested managed
    collections, and async code. Record final module bytes and section sizes
    under one fixed emission pipeline, with optimization enabled and disabled.
@@ -998,10 +1001,10 @@ Implement in this order:
    and observable effects. Reuse existing constant evaluation where its
    semantics match runtime evaluation; never evaluate process reads or other
    host effects at compile time.
-3. [ ] Add size-driven inlining, beginning with non-recursive functions that
-   have one reachable call site. Inline only when the estimated total module
-   cost falls, accounting for removal of the original function, call overhead,
-   locals, and any retained dependencies. Treat recursive calls and suspension
+3. [ ] Establish useful additional savings from size-driven inlining before
+   promoting the existing experiment. Account for removal of the original
+   function, call overhead, locals, retained dependencies, and cleanup already
+   performed by the promoted pipeline. Treat recursion and suspension
    boundaries conservatively. Do not use hotness or runtime-speed heuristics.
 4. [ ] Recompute reachability after simplification and inlining so newly unused
    functions, runtime helpers, imports, types, static data, and scratch regions

docs/WASM_SIZE_OPTIMIZATION.md

@@ -0,0 +1,96 @@
+# Release Wasm size optimization
+
+Release compilation runs a bounded size optimizer after emission. Debug and hot
+reload bypass all optimizer scans. The objective is a smaller complete Wasm
+file; execution-speed optimization remains the engine's job. Binaryen is not a
+compiler dependency.
+
+## Promoted pipeline
+
+Two cleanup sweeps simplify integer instructions, fold adjacent integer
+constants, remove unreachable code and unused locals, simplify structured
+control flow, and share identical return sequences. The second sweep handles
+patterns exposed by the first. Compilation does not iterate to a fixed point,
+and it stops early when a sweep does not shrink the module.
+
+Function sharing then merges bodies that differ only in integer constants.
+Each original function remains a small wrapper passing its constants to a
+shared helper. Existing indices, signatures, exports and references remain
+intact. Reports retain the original functions and add the shared helpers.
+
+Every cleanup body and complete module must shrink. Function-sharing costs
+include wrappers, helper bodies, new signatures/declarations, and section
+encoding overhead. The implementation preserves integer overflow and traps,
+does not fold floating-point operations, and retains effects of discarded
+values. Control-flow changes remap branch targets. Shared return sequences
+exclude bodies with non-defaultable locals; function sharing excludes tail
+calls and exception/continuation constructs. The tests cover those boundaries,
+GC/reference values, multi-value returns, large indices, and observable effects.
+
+## Selection from the experimental branch
+
+The promotion was measured against `master` at `1b65a40` and the full pipeline
+at `3ecf397` on `experiment/wasm-size-optimizations`. The experiment and its
+Binaryen comparisons remain on that branch. Commit `3f3c9be` records a
+reproducible comparison with individual passes disabled.
+
+| Real script | Previous master | Promoted Release | Saved | Reduction |
+| --- | ---: | ---: | ---: | ---: |
+| Minish Cap | 35,111 | 32,648 | 2,463 | 7.0% |
+| Lunistice | 31,413 | 29,163 | 2,250 | 7.2% |
+| Neon White | 5,073 | 4,768 | 305 | 6.0% |
+| A Hat in Time | 50,205 | 48,536 | 1,669 | 3.3% |
+
+The selected passes retain 98.2% / 98.4% of the full experimental savings on
+Minish Cap / Lunistice. Inlining and temporary sinking stay experimental:
+together, they save only another 46 / 36 bytes compared with this pipeline.
+Temporary sinking alone contributes 36 / 17 bytes in the two-sweep configuration.
+The remaining size benefit does not justify promoting that additional analysis
+and maintenance surface yet. The disabled propagation experiment also stays off
+master. Redundant null rewriting is omitted because direct emitter fixes already
+provide its savings in both profiles.
+
+Integer constant folding stays because it saves 113 bytes on Minish Cap and
+fits into the existing instruction scan. A second cleanup sweep saves another
+282 / 41 bytes on the primary scripts when measured with temporary sinking
+enabled; it exposes useful simplifications without introducing another analysis.
+Pass savings interact and must not be added together as independent totals.
+
+## Validation and reproduction
+
+The promoted pipeline has focused instruction/control/function-sharing tests
+and a source-level behavioral test covering evaluation order, GC values,
+fallible results and suspension. The real-script regression checks module
+validation, size reduction, unchanged original function indices and report
+metadata, and identical output with or without requesting a report.
+
+The opt-in nine-fixture corpus records complete module bytes and section payload
+sizes, validates baseline and optimized modules, and checks Debug equivalence.
+DWARF `.debug_info` variable entries already have nondeterministic ordering in
+unoptimized builds, so that comparison excludes only this section; executable
+code, names, source maps and line tables must match. A smaller deterministic
+fixture also checks the entire Debug binary byte for byte. No Debug emitter
+changes are part of this promotion.
+
+Validation passes: 494 library, 696 compiler, 20 binary and four example tests;
+Clippy; formatting/diff checks; and the browser compiler's wasm32 target check.
+All 176 maintained modules validate, all 211 runtime scenarios and the
+Debug/Release profile check pass. The size-corpus runner additionally passes
+36 behavioral invocations comparing unoptimized and promoted output.
+
+```powershell
+$env:CARGO_PROFILE_DEV_DEBUG = '0'
+$env:CARGO_PROFILE_TEST_DEBUG = '0'
+$env:CARGO_INCREMENTAL = '0'
+cargo test --lib --test compiler --bin splitc --bin splitls --examples --offline
+cargo clippy --all-targets --offline -- -D warnings
+cargo check -p splitscript-vscode-wasm --target wasm32-unknown-unknown --offline
+cargo test --lib write_size_corpus --offline -- --ignored --nocapture
+node scripts/wasm-size-runtime.mjs
+cargo test --profile max-opt --lib measure_optimization_overhead --offline -- --ignored --nocapture
+```
+
+Artifacts stay under `target/size-check`. Timing uses seven warmed, alternating
+samples per mode, excludes parsing/type checking, and includes lowering and
+emission. The maintained runtime runner compares baseline and optimized output
+through the existing behavioral scenarios rather than checking bytes alone.

scripts/wasm-size-runtime.mjs

@@ -0,0 +1,28 @@
+// Run maintained behavioral scenarios against baseline and optimized artifacts.
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+
+const directory = path.resolve("target/size-check");
+const corpus = JSON.parse(fs.readFileSync(path.join(directory, "corpus.json"), "utf8"));
+const fixtures = [...fs.readFileSync("src/bin/xtask.rs", "utf8").matchAll(
+    /RuntimeFixture\s*\{\s*source:\s*"([^"]+)",\s*output:\s*"([^"]+)",\s*profile:\s*"([^"]+)",\s*harness:\s*"([^"]+)",\s*extra_arguments:\s*&\[([^\]]*)\]/g,
+)];
+const variants = process.argv.slice(2);
+if (!variants.length) variants.push("baseline", "release");
+let scenarios = 0;
+for (const row of corpus) {
+    let selected = fixtures.filter(match => match[1] === row.source && match[3] === "release");
+    if (!selected.length) selected = fixtures.filter(match => match[1] === row.source);
+    if (!selected.length) throw new Error(`No maintained scenarios for ${row.source}`);
+    for (const variant of variants) {
+        for (const fixture of selected) {
+            const args = [...fixture[5].matchAll(/"([^"]*)"/g)].map(match => match[1]);
+            const result = spawnSync(process.execPath, [fixture[4], path.join(directory, `${row.name}.${variant}.wasm`), ...args], { encoding: "utf8" });
+            if (result.status !== 0) throw new Error(`${row.name}/${variant}/${args.join(" ")}: ${result.stdout}\n${result.stderr}`);
+            scenarios++;
+        }
+        console.log(`${row.name}/${variant}: ${selected.length} scenarios passed`);
+    }
+}
+console.log(`${scenarios} maintained runtime scenarios passed`);

src/codegen.rs

@@ -53,8 +53,13 @@ mod managed_references;
 mod managed_snapshots;
 mod managed_state_reads;
 mod memory_plan;
+mod merging;
 mod module_assembly;
 mod module_start;
+mod optimization;
+#[cfg(test)]
+mod optimization_tests;
+mod peephole;
 mod pointer_prefixes;
 mod reachability;
 mod runtime_helper_registry;
@@ -398,7 +403,7 @@ impl std::ops::Deref for BackendProgram<'_> {
 }
 
 pub fn compile(inputs: BackendProgram<'_>) -> Vec<u8> {
-    compile_internal(inputs, None)
+    compile_internal(inputs, None, OptimizationMode::Size)
 }
 
 /// Sidecar information from the same plan that emitted the module. Requesting
@@ -417,11 +422,22 @@ pub struct CodegenReport {
 
 pub(crate) fn compile_with_report(inputs: BackendProgram<'_>) -> (Vec<u8>, CodegenReport) {
     let mut report = CodegenReport::default();
-    let wasm = compile_internal(inputs, Some(&mut report));
+    let wasm = compile_internal(inputs, Some(&mut report), OptimizationMode::Size);
     (wasm, report)
 }
 
-fn compile_internal(inputs: BackendProgram<'_>, report: Option<&mut CodegenReport>) -> Vec<u8> {
+#[derive(Clone, Copy)]
+enum OptimizationMode {
+    #[cfg(test)]
+    None,
+    Size,
+}
+
+fn compile_internal(
+    inputs: BackendProgram<'_>,
+    mut report: Option<&mut CodegenReport>,
+    optimizations: OptimizationMode,
+) -> Vec<u8> {
     // These contracts describe immutable compiler-owned tables, independent of
     // the source, profile, or injected standard-library graph.
     static VALIDATED_CONTRACTS: std::sync::OnceLock<()> = std::sync::OnceLock::new();
@@ -1167,7 +1183,7 @@ fn compile_internal(inputs: BackendProgram<'_>, report: Option<&mut CodegenRepor
         })
     });
 
-    if let Some(report) = report {
+    if let Some(report) = report.as_deref_mut() {
         let memory = static_data.layout();
         *report = CodegenReport {
             functions: function_debug_names,
@@ -1183,7 +1199,7 @@ fn compile_internal(inputs: BackendProgram<'_>, report: Option<&mut CodegenRepor
         };
     }
 
-    module_assembly::finish(
+    let wasm = module_assembly::finish(
         module_assembly::Sections {
             types,
             imports,
@@ -1206,7 +1222,16 @@ fn compile_internal(inputs: BackendProgram<'_>, report: Option<&mut CodegenRepor
         start_function,
         update_function,
         debug_artifacts.as_ref(),
-    )
+    );
+    // Debug/hot-reload compilation bypasses every optimizer scan.
+    if wasm_ir.profile() != crate::BuildProfile::Release {
+        return wasm;
+    }
+    match optimizations {
+        #[cfg(test)]
+        OptimizationMode::None => wasm,
+        OptimizationMode::Size => optimization::optimize(wasm, report),
+    }
 }
 
 fn resolved_intrinsic(target: &wasm_ir::CallTarget) -> Option<IntrinsicId> {