VM optimizations

notes/nested_loop_vm_state.md

@@ -37,6 +37,12 @@
 - 2026-02-15 baseline (fused int-compare jumps): 74 ms.
   - Command: `./gradlew :lynglib:jvmTest -Pbenchmarks=true --tests '*NestedRangeBenchmarkTest*'`
   - Notes: loop range checks use `JMP_IF_GTE_INT` (no CMP+bool temp).
+- 2026-02-15 experiment (fast non-suspend cmds in hot path): 57 ms.
+  - Command: `./gradlew :lynglib:jvmTest -Pbenchmarks=true --tests '*NestedRangeBenchmarkTest*'`
+  - Notes: fast path for local int ops + local JMP_IF_FALSE/TRUE in VM.
+- 2026-02-15 experiment (full fast-path sweep + capture-safe locals): 59 ms.
+  - Command: `./gradlew :lynglib:jvmTest -Pbenchmarks=true --tests '*NestedRangeBenchmarkTest*'`
+  - Notes: local numeric/bool/mixed-compare fast ops gated by non-captured locals.
 
 ### Hypothesis for Native slowdown
 - Suspend/virtual dispatch per opcode dominates on K/N, even with no allocations in int ops.

notes/vm_fastpath_plan.md

@@ -0,0 +1,49 @@
+# VM Fast-Path Plan (Non-Suspending Ops)
+
+## Goal
+Reduce suspend overhead by routing safe, local-only ops through non-suspending fast paths while preserving semantics for captured locals and dynamic objects.
+
+## Completed
+- [x] Local numeric/bool/conversion ops: add fast local variants and guard by non-captured locals.
+- [x] Local jumps: `JMP_IF_TRUE/FALSE` and fused int jumps fast path.
+- [x] **Object arithmetic ops** (`ADD_OBJ/SUB_OBJ/MUL_OBJ/DIV_OBJ/MOD_OBJ`): add fast-path for local numeric slots with fallback to slow path when non-numeric or captured.
+- [x] Full `:lynglib:jvmTest` green after changes.
+
+## In Progress / Next
+- [ ] Object comparisons (`CMP_*_OBJ`) fast-path on local numeric slots (guarded, fallback to slow path).
+- [ ] Local `MOVE_OBJ` safe fast-path (only if slot is not `FrameSlotRef`/`RecordSlotRef`, or add explicit unwrapping).
+- [ ] Address ops (`LOAD_*_ADDR` / `STORE_*_ADDR`) non-suspend variants when addr already resolved.
+- [ ] Confirm wasm/js behavior unchanged (if needed).
+
+## Guardrails
+- Never treat captured locals as fast locals; route them through slow path.
+- Fast path must only execute when slot types are primitive numeric/bool and stored directly in frame.
+- If fast-path preconditions fail, fall back to suspend `perform()`.
+
+## Test Gate
+- `./gradlew :lynglib:jvmTest`
+- Benchmarks optional: `./gradlew :lynglib:jvmTest -Pbenchmarks=true --tests '*NestedRangeBenchmarkTest*'`
+
+## A/B Benchmark (Representative)
+- Baseline (fast-path stashed): 194 ms
+- With fast-path changes: 186 ms
+- Command: `./gradlew :lynglib:jvmTest -Pbenchmarks=true --tests '*RepresentativeBenchmarkTest*'`
+
+## A/B Benchmark (Representative Object Ops)
+- Baseline (fast-path stashed): 106 ms
+- With fast-path changes: 108 ms
+- Command: `./gradlew :lynglib:jvmTest -Pbenchmarks=true --tests '*RepresentativeObjectBenchmarkTest*'`
+
+## A/B Benchmark (Representative Object Ops, extended comparisons)
+- Baseline (ObjString only): 141 ms
+- With ObjString + ObjInt/ObjReal compare ops: 137 ms
+- Command: `./gradlew :lynglib:jvmTest -Pbenchmarks=true --tests '*RepresentativeObjectBenchmarkTest*'`
+
+## A/B Benchmark (Representative Object Ops, object numeric compares)
+- Baseline (no Obj* compare ops): 153 ms
+- With ObjString + ObjInt/ObjReal compare ops: 149 ms
+- Command: `./gradlew :lynglib:jvmTest -Pbenchmarks=true --tests '*RepresentativeObjectBenchmarkTest*'`
+
+## A/B Benchmark (Trust type decls for Obj* compares)
+- With ObjString + ObjInt/ObjReal compare ops + type-decl trust: 157 ms
+- Command: `./gradlew :lynglib:jvmTest -Pbenchmarks=true --tests '*RepresentativeObjectBenchmarkTest*'`