chore: main is 0.3.0-to-be

feat(core): >ORDER, -ORDER, VOCABULARY search-order extensions
release: 0.2.9
2026-08-12 11:02:13 +02:00 · 2026-08-12 11:01:49 +02:00 · 2026-08-11 17:24:04 +02:00 · 2026-08-11 17:23:52 +02:00 · 2026-08-11 17:23:38 +02:00 · 2026-08-11 17:23:25 +02:00
22 changed files with 3301 additions and 431 deletions
@@ -5,6 +5,360 @@ All notable changes to WAFER are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

+## [Unreleased]
+
+### Added
+
+- **Search-order conveniences from common practice** (none are Forth 2012;
+  all three exist in gforth and friends, and the semantics were checked
+  against gforth 0.7.3):
+  - `>ORDER ( wid -- )` pushes a wordlist on top of the search order --
+    the word the standard forgot when ANS replaced named vocabularies
+    with anonymous wid handles and left `ALSO` with nothing to name.
+  - `-ORDER ( wid -- )` removes a wordlist from the search order wherever
+    it sits (VFX/MPE extension, the inverse of `>ORDER`).
+  - `VOCABULARY <name>` creates a named wordlist; executing the name
+    replaces the top of the search order, the same semantics the standard
+    gives `FORTH`. `ORDER` and `WORDS ALL` now print vocabulary names
+    instead of `wid#N`, and `MARKER` rollback forgets them along with
+    the words.
+
+## [0.2.9] - 2026-08-10
+
+### Fixed
+
+- **A word that never recurses no longer gets a typed entry it cannot use.**
+  Every word with a statically known stack effect was given the typed
+  wrapper + fast-entry pair. In the JIT path the function-table slot holds
+  the wrapper and the only caller that can reach the fast entry is
+  `RECURSE`, so for any other word a cross-word call went
+  `call_indirect` -> wrapper -> fast entry: one hop more for exactly the
+  same memory traffic. On a 300k-iteration loop over a callee too big to
+  inline that cost **1569 µs against 1067 with the convention off** -- an
+  optimisation making things worse. It is now emitted only when the body
+  calls itself, which is where it is worth 4x (Fibonacci 242 µs typed
+  against 636 untyped). `CONSOLIDATE` and the AOT export are unaffected;
+  they solve their effects separately. Present in 0.2.7 and 0.2.8.
+
+- **The inliner's loop guard has never actually fired.** 0.2.7 added a rule
+  that a loop-bearing callee must not be inlined into a caller that can
+  never be promoted, since the loop then loses its registers -- a 7x
+  pessimisation applied by an optimisation pass. The check ran _before_
+  inlining, where the caller is nothing but calls: `DROP` is
+  `Call(WordId(2))`, `CR` is `Call(WordId(38))`. Since the check looks
+  through calls by design, it called nearly every caller promotable and
+  the guard did nothing. Inlining now happens in two passes -- loop-free
+  callees first, then the question, then the rest.
+
+### Added
+
+- **A sixth benchmark, `CrossCalls(300K)`, that measures what `CONSOLIDATE`
+  does.** The other five have no cross-word call left in their hot loop:
+  four have their callee inlined away and Fibonacci is self-recursive. So
+  the `CONSOL` column measured nothing, which is how both bugs above stayed
+  hidden. With a real call in the loop, consolidation is worth 2.8-4x.
+
+### Changed
+
+- **The benchmark harness stops reporting noise.** It took the median of three
+  timed repetitions inside one process, and a `samples` field that was never
+  read. Each measurement is now the mean of the three fastest of seven
+  repetitions, and that whole process runs three times with the fastest kept.
+  Benchmark noise is one-sided -- a scheduling hiccup or a busy SMT sibling can
+  only make a run slower -- so the fastest runs are the honest ones, and only a
+  fresh process resamples core placement and code layout. On a shared 16-vCPU
+  box the run-to-run spread went from 20-79% to 1-6%, and Fibonacci after
+  `CONSOLIDATE` stopped being bimodal (413-419 µs on three reports and 712-770
+  on two, with nothing in between; now 412-426 across four).
+
+- **Every benchmark is now sized to run about 10 ms**, from the 0.2-2 ms most
+  of them took. Not for the usual reason -- the timing wrapper already excludes
+  start-up and compilation, and in the measurements shorter benchmarks were if
+  anything the _steadier_ ones -- but it buys a comfortable margin over timer
+  resolution and first-iteration effects for nothing: the report still finishes
+  in under a minute, and gforth, 3-20x slower than WAFER, is what sets that
+  clock. Fibonacci went from 25 to 33 rather than into a loop, so it stays pure
+  recursion; Collatz repeats its 2000-value round 50 times instead of counting
+  higher, because past ~100000 the sequence peaks near 1.5 billion and `3 * 1+`
+  overflows WAFER's 32-bit cells while sf64's 64-bit cells carry on -- the two
+  engines would stop doing the same work. All three engines agree on the results
+  at the new sizes.
+
+### Explained
+
+- **Why `CONSOLIDATE` makes some promoted loops slower** (NestedLoops
+  1.7x on x86-64, 1.1x on arm64): not worse code -- the WASM is
+  byte-identical and the machine code instruction-identical modulo
+  registers -- but worse placement. A tight loop pays for straddling an
+  instruction-fetch window (16 bytes on the M1 at ~9%; 32 bytes on
+  Skylake at up to ~65%, where a fused `cmp+jcc` crossing the boundary
+  drops the loop out of the uop cache every iteration -- the JCC
+  erratum). Cranelift never aligns loop headers, and the per-word JIT
+  module's dead dsp-prologue bytes happen to shift its loops onto
+  luckier offsets. Verified by a padding sweep that reproduces the full
+  penalty range on both hosts, including placements where consolidated
+  code beats the JIT. Details in docs/OPTIMIZATIONS.md; native x86-64
+  reference numbers in the README re-taken at the new workload sizes.
+
+## [0.2.8] - 2026-08-10
+
+### Added
+
+- **A recursive word tests its base case at the call site.** A recursive Forth
+  word almost always opens with a guard that returns early --
+  `: FIB DUP 2 < IF EXIT THEN ... RECURSE ... ;` -- so every leaf of the
+  recursion costs a call whose entire body is that test. `Call(self)` now
+  compiles as `<guard> IF <what the guard returns> ELSE Call(self) THEN`,
+  which computes the same thing: the callee would have run the guard, taken
+  the branch and returned. In fib's tree the leaves are half of all nodes.
+
+  Fibonacci(25) 356 -> 237 µs on the arm64 development machine, where that
+  reads 1.24x -> 0.83x of SwiftForth `sf64`. Measured again with **both
+  engines native on x86-64** -- the macOS `sf64` build runs under Rosetta 2,
+  which flatters WAFER -- Fibonacci is 1.16x, so it remains the one benchmark
+  of the five that `sf64` wins. See the two tables in the README.
+
+  The guard runs twice along the recursive path, so it has to be small (at
+  most six operations) and free of effects -- no calls, no memory, no
+  branches. Words with more than four self-call sites are left alone to bound
+  the code growth, and a `TailCall` is never expanded.
+
+## [0.2.7] - 2026-08-09
+
+### Added
+
+- **A typed calling convention for words with a known stack effect.** Such a
+  word now compiles to two entry points: a fast one whose signature is
+  `(i32 x p) -> (i32 x q)`, carrying its stack items as WASM values, and the
+  usual `( -- )` wrapper that moves those items on and off the memory data
+  stack. The wrapper keeps the function-table slot, so `EXECUTE`, the outer
+  interpreter, host words and `CATCH` see exactly the ABI they saw before;
+  only direct calls inside a module take the fast entry.
+
+  This is what the SwiftForth gap was made of. sf64 keeps TOS in `RBX` and
+  the stack pointer in `RBP`, and both survive a `CALL` untouched, so its
+  `FIB` is 16 instructions and ~7 memory touches per node. WAFER kept the
+  whole stack in linear memory and flushed its cached `$dsp` to an imported
+  global before every call: ~36 memory touches per node. The stack simulator
+  that already promoted loop and `IF` bodies into WASM locals refused any
+  body containing a call or an `EXIT` -- exactly the words where the
+  convention cost the most. It now handles both.
+
+  Fibonacci(25) goes from 1035 to 366 µs, 4.3x slower than `sf64` to 1.2x.
+  Loop-heavy benchmarks are unchanged by this entry — see the region
+  promotion below for those. Words that keep the memory convention: anything
+  using `SP@`, `DEPTH`, `EXECUTE`, `>R`/`R>`, floats or locals; anything
+  calling a word that is itself untyped, which in the JIT path means every
+  call except `RECURSE`; mutually recursive words; and words whose effect is
+  not static -- branches that disagree on depth, `EXIT` at the wrong depth,
+  a non-neutral loop body, or a recursion that grows the stack per level.
+
+  `CONSOLIDATE` extends this across words, since it puts them all in one
+  module: the effects are solved to a fixpoint from the leaves outward, and
+  105 of 187 words in a booted dictionary end up typed.
+
+  Stack guards get cheap as a side effect -- they hang off the memory-stack
+  push/pop choke points, and a typed word barely has any. The default
+  guards-on configuration that the REPL and the web build use went from 1631
+  to 365 µs on the same benchmark.
+
+  `WAFER_TYPED_CALLS=0` falls back to the memory-stack convention.
+
+- **Promotion is now per region, not per word.** Stack-to-local promotion
+  used to be all-or-nothing: a single `.`, `CR`, `>R` or host call
+  anywhere in a definition put the _entire_ body on the memory data
+  stack, hot loops included. The stack simulator now runs over each
+  stretch of a word that can live in WASM locals, loading what the
+  region reads and writing back what it leaves, with the rest of the
+  word unchanged around it.
+
+  The cliff this removes was steep. The same loop, same build:
+
+  | `: L1 0 5000000 0 DO 1+ LOOP DROP ;` reached as | µs    | ns/iter |
+  | ----------------------------------------------- | ----- | ------- |
+  | its own word                                    | 1571  | 0.31    |
+  | inlined into a caller with a `.` in it (before) | 11100 | 2.22    |
+  | the same, after this change                     | 1572  | 0.31    |
+
+  7x, for one `i32.add`: on the memory path the accumulator is stored to
+  linear memory and reloaded next iteration, so the loop-carried
+  dependency runs through store-to-load forwarding instead of a
+  register.
+
+  A region may only use `I` / `J` when the DO loops naming them are
+  inside the region, since the simulator resolves them against its own
+  loop stack. Straight-line regions have to be at least three operations
+  to be worth the load and store either side; a loop always is.
+
+- **The inliner no longer drags a loop onto the memory stack.** It
+  inlined any callee of eight IR operations or fewer, so a small
+  loop-bearing word inlined into a caller that can never be promoted
+  lost its registers -- an optimisation pass applying the 7x
+  pessimisation above. Loop-bearing callees now stay put in that case:
+  one call is far cheaper than a loop's worth of memory traffic.
+  Straight-line words still inline everywhere.
+
+- **`BEGIN` loops promote as well.** `BEGIN..UNTIL`, `BEGIN..AGAIN` and
+  `BEGIN..WHILE..REPEAT` were rejected outright by the eligibility check,
+  so any word built on the idiomatic Forth loop kept the memory data
+  stack no matter how hot it was. They are promoted now when the
+  construct is stack-neutral: `UNTIL` consumes exactly the flag its body
+  leaves, `AGAIN`'s body is neutral, and for `WHILE..REPEAT` the test and
+  the body balance separately -- `WHILE` leaves the loop between the two,
+  so a net that only added up over the pair would give the two exits
+  different stack shapes. Bodies containing an `EXIT` stay out, the same
+  rule `DO`/`LOOP` follows. `BEGIN..WHILE..WHILE..REPEAT` is still
+  excluded.
+
+  GCD 994 -> 540 µs, Collatz 428 -> 185.
+
+  Together these four entries put four of the five cross-engine
+  benchmarks past SwiftForth `sf64`: Factorial 0.29x, Collatz 0.30x,
+  NestedLoops 0.27x, GCD 0.67x. Fibonacci stays at 1.24x, being pure
+  call overhead with no loop to promote.
+
+### Fixed
+
+- **A promoted loop or `IF` whose branch permutes the stack lost a value.**
+  At the bottom of a promoted loop the body's results are copied back into
+  the loop-top locals, and the join after a promoted `IF` copies one
+  branch's locals into the other's. Both did it one slot at a time in index
+  order, which is wrong as soon as a destination is also a later source:
+  `: C 3 4 2 0 DO SWAP LOOP . . ;` printed `4 4` where gforth and
+  SwiftForth print `4 3`, and `2 0 DO ROT LOOP` over three cells printed
+  `3 2 3` instead of `2 1 3`. The copies are now ordered so every source is
+  read before it is overwritten, with one scratch local to break a cycle.
+  Present since stack-to-local promotion was introduced; reachable from
+  any `DO` loop or `IF` whose body reorders cells it did not create.
+
+- The Forth 2012 Core suite now also runs against consolidated code
+  (`compliance_core_after_consolidate`). `CONSOLIDATE` had no correctness
+  test at all before -- only benchmarks.
+
+### Changed
+
+- **Three cross-engine benchmarks were too small to be measured.** GCD ran
+  in 14 µs, Factorial in 49 and NestedLoops in 51, where per-run scatter is
+  a good fraction of the total and fixed per-invocation costs in the other
+  engines dominate. Scaled to Factorial x100K, GCD-bench(20K) and
+  NestedLoops(50)x1K, all now around 0.5-1 ms.
+
+  This changed a result rather than just steadying it: GCD looked like a
+  win at 0.42x of `sf64` and was in fact a loss at 1.17x. That is what
+  pointed at `BEGIN` loops as the remaining gap -- GCD is the one benchmark
+  whose loop is a `BEGIN ... WHILE ... REPEAT` -- and with those promoted it
+  now reads 0.67x. The regression limits, which had drifted to 3-6x looser
+  than the measurements they guard, were retightened to ~45% above the
+  current ratios.
+
+## [0.2.6] - 2026-08-07
+
+### Fixed
+
+- **An uncaught `ABORT` no longer prints anything.** It used to report
+  `ABORT (throw -1)`, but the standard defines `ABORT` as "empty the data
+  stack and perform the function of `QUIT`", and `QUIT` displays no
+  message. gforth and SwiftForth are both silent here. `CATCH` still
+  reports -1 as before, and `ABORT"` still prints its text — that is a
+  different word with a different code (-2).
+- **Compile-only words used in interpretation state name the condition.**
+  `ABORT"`, `IF`, `THEN`, `LOOP`, `LITERAL`, `RECURSE` and the rest of
+  the compile-time constructs claimed to be an `unknown word`, which is
+  actively misleading for a word the system obviously knows. They now
+  report `interpreting a compile-only word: <name> (throw -14)`, the
+  standard condition both reference engines give. A genuine typo still
+  reports `unknown word`.
+
+## [0.2.5] - 2026-08-06
+
+### Added
+
+- **`QUIT`** ( -- ) ( R: i\*x -- ), the CORE word that was missing: empty
+  the return stack, enter interpretation state, hand the input source
+  back to the user input device and return to the interpreter without a
+  message. The data stack is deliberately left alone — that is the whole
+  difference to `ABORT`, which the standard defines as "empty the data
+  stack, then `QUIT`". It unwinds through nested `EVALUATE` and
+  `INCLUDE`, abandoning them, and `SOURCE-ID` is restored to 0.
+
+  `CATCH` does **not** report it: `QUIT` rides throw code -56, which the
+  interpreter treats as a return to the prompt rather than an exception.
+  Both behaviours were checked against gforth 0.7.3 and SwiftForth
+  `sf64`, which agree — `1 2 ' QUIT CATCH .` prints nothing and leaves
+  `1 2` on the stack in all three engines.
+
+  The gap had gone unnoticed because the Forth 2012 test suite skips it
+  by its own admission ("I HAVEN'T FIGURED OUT HOW TO TEST KEY, QUIT,
+  ABORT, OR ABORT\""), and because `HELP`'s coverage lint compares the
+  dictionary against the docs — a word absent from both looks complete.
+  `docs/wafer-anki.txt` had been documenting `QUIT` as if it existed.
+
+  Note that `ABORT` was already correct: executing it while a definition
+  is open does clear both stacks and return to interpretation state.
+  Typing `ABORT` (or `QUIT`) into an unfinished definition compiles it
+  rather than running it, exactly as in every other Forth; `[` is the
+  word that gets you out.
+
+## [0.2.4] - 2026-08-06
+
+### Fixed
+
+- **Errors from host words in the browser build read like Forth errors
+  again.** A host word signals failure by throwing across the JS
+  boundary, and the browser runtime reported the exception with its
+  `Debug` form, so an empty-stack `RESIZE` came back as
+  `call_func(134) failed: JsValue(Error: Stack underflow ...)` trailed by
+  an engine stack trace. The thrown message is the Forth message, so it
+  is now surfaced verbatim — `Stack underflow`, exactly what the native
+  CLI prints. Exceptions that carry no message keep the call context,
+  since those are genuine runtime faults rather than Forth throws.
+  `CATCH` was never affected: it reads the throw code from its own
+  channel, not from the message.
+
+## [0.2.3] - 2026-08-06
+
+### Fixed
+
+- **Release builds of `wafer-web` no longer fail on proc-macro loading.**
+  Cargo strips debuginfo from release artifacts by default, and on macOS
+  that also strips the metadata proc-macro dylibs need to be loadable, so
+  `wasm-pack build --release` died with `can't find crate` for
+  `rustversion`, `thiserror_impl` and every other proc-macro. Build
+  scripts and proc-macros gain nothing from stripping, so
+  `[profile.release.build-override]` now exempts them; release binaries
+  stay stripped. Debug builds were never affected, which is why the test
+  suite stayed green while the browser REPL could not be built for
+  production.
+- `wafer-web` and `wafer-cli` requested `wafer-core` version `0.2.1`
+  while the workspace had moved to `0.2.2`. The caret requirement still
+  resolved, so nothing broke, but the pin is now kept in step.
+
+## [0.2.2] - 2026-08-06
+
+### Added
+
+- **SwiftForth-style input number conversion.** Punctuation (`,` `.` `+`
+  `/` `:` and an embedded `-`) anywhere after the leftmost digit now forces
+  double-cell conversion, so `12.34`, `1,234`, `12:30:45` and `2026-08-06`
+  all convert as doubles without a custom parser. Previously only a
+  trailing `.` worked and `1.5` was an "unknown word" error. The
+  punctuation is a double-cell marker, not a fractional point: every
+  spelling of `1234` (`1234.`, `123.4`, `.1234`) yields the same value.
+- **`DPL`** ( -- addr ): digits to the right of the rightmost punctuation
+  character in the last converted number, negative when the token carried
+  none. Seeded at -1024 and bumped once per digit, matching `sf64`.
+  Together with `<# #>` this is how fixed-point input is scaled.
+- **`NH`** ( -- addr ): the high-order cell dropped by a single-cell
+  conversion, so a token that overflows a cell can be recovered as a
+  double (`4000000000 NH @ D.`).
+
+Verified token-for-token against SwiftForth `sf64`: DPL values, double
+promotion and sign handling agree on every probed form. One deliberate
+divergence — WAFER also accepts a sign before a base prefix (`-$FF`), which
+`sf64` rejects; the Forth 2012 spelling `$-FF` works in both. A leading `+`
+is punctuation rather than a sign in both engines, so `+7` is the double 7
+with `DPL` = 1.
+
 ## [0.2.1] - 2026-08-06

 ### Fixed
@@ -78,7 +432,7 @@ safety net under every compiled word.
 ### Fixed

 - Multi-line command output in the CLI REPL starts on its own line
-  (inline ` ok` echo only for single-line output).
+  (inline `ok` echo only for single-line output).
 - `.S` printed in decimal regardless of `BASE`.
 - A bare interpreted `R>` underflowed silently (exposed by the new stack
  guards; compliance baseline updated).
@@ -104,6 +458,9 @@ compliance suite, `CONSOLIDATE` whole-program recompilation, `wafer build`
 AOT export (WASM / native / JS loader), browser REPL, SHA-1/256/512 words,
 and cross-engine benchmark lanes against gforth and SwiftForth.

+[0.2.9]: https://github.com/ok2/wafer/compare/v0.2.8...v0.2.9
+[0.2.8]: https://github.com/ok2/wafer/compare/v0.2.7...v0.2.8
+[0.2.7]: https://github.com/ok2/wafer/compare/v0.2.6...v0.2.7
 [0.2.1]: https://github.com/ok2/wafer/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/ok2/wafer/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/ok2/wafer/releases/tag/v0.1.0
@@ -2,7 +2,7 @@

 ## What is WAFER?

-WAFER (WebAssembly Forth Engine in Rust) is an optimizing Forth 2012 compiler targeting WebAssembly. Currently a working Forth system with 200+ words, JIT compilation, 12 word sets at 100% compliance, and a full optimization pipeline (peephole, constant folding, inlining, strength reduction, DCE, tail calls, stack-to-local promotion with loop/IF support, self-recursive direct calls, consolidation). Beats gforth on all benchmarks in release mode. Includes a browser-based REPL via wasm-pack.
+WAFER (WebAssembly Forth Engine in Rust) is an optimizing Forth 2012 compiler targeting WebAssembly. Currently a working Forth system with 200+ words, JIT compilation, 12 word sets at 100% compliance, and a full optimization pipeline (peephole, constant folding, inlining, strength reduction, DCE, tail calls, per-region stack-to-local promotion with DO/BEGIN loop and IF support, self-recursive direct calls, a typed calling convention for words with a known stack effect, self-guard expansion for recursive words, consolidation). Beats gforth on every benchmark, and SwiftForth `sf64` on five of six (measured native-vs-native on x86-64; the macOS sf64 build is x86-64 under Rosetta and flatters WAFER). Includes a browser-based REPL via wasm-pack.

 ## Architecture

@@ -79,7 +79,7 @@ Handle in `interpret_token_immediate()` or `compile_token()` as a special case.

 ## Testing

- Run `cargo test --workspace` before committing (currently 542 unit + 1 benchmark + 11 compliance + 9 comparison + 5 crypto)
+- Run `cargo test --workspace` before committing (currently 611 unit + 1 benchmark + 12 compliance + 9 comparison + 5 crypto)
 - Forth 2012 compliance: `cargo test -p wafer-core --test compliance`
 - Cross-engine comparison (vs gforth): `cargo test -p wafer-core --test comparison`
 - Performance benchmarks (release mode): `cargo test -p wafer-core --test comparison -- --nocapture --ignored`
@@ -132,15 +132,6 @@ dependencies = [
 "generic-array",
 ]

-[[package]]
-name = "block-buffer"
-version = "0.12.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d2f6c7dbe95a6ed67ad9f18e57daf93a2f034c524b99fd2b76d18fdfeb6660aa"
-dependencies = [
- "hybrid-array",
-]
-
 [[package]]
 name = "bumpalo"
 version = "3.20.3"
@@ -182,9 +173,9 @@ checksum = "f079e83a288787bcd14a6aea84cee5c87a67c5a3e660c30f557a3d24761b3527"

 [[package]]
 name = "clap"
-version = "4.6.5"
+version = "4.6.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "301b56658598e48f3648647ac6fc887be7e7108eddfa4e9b63fcf3ec58c0cadf"
+checksum = "473c7e07f409a8d772161724aa8db6a765a2532a70f9667eeb7b49d3d02fbdca"
 dependencies = [
 "clap_builder",
 "clap_derive",
@@ -192,9 +183,9 @@ dependencies = [

 [[package]]
 name = "clap_builder"
-version = "4.6.5"
+version = "4.6.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "94a65403d1a1bd28f7dc68eb8506e8874808ee5eecb59298de588e2e1407a078"
+checksum = "7b48fea5a88e9ae728a2dcbedbfc0e730f7d60da42e1cb049a83c9fb8b789889"
 dependencies = [
 "anstream",
 "anstyle",
@@ -255,12 +246,6 @@ dependencies = [
 "windows-sys",
 ]

-[[package]]
-name = "const-oid"
-version = "0.10.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a6ef517f0926dd24a1582492c791b6a4818a4d94e789a334894aa15b0d12f55c"
-
 [[package]]
 name = "cpp_demangle"
 version = "0.5.1"
@@ -279,15 +264,6 @@ dependencies = [
 "libc",
 ]

-[[package]]
-name = "cpufeatures"
-version = "0.3.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8b2a41393f66f16b0823bb79094d54ac5fbd34ab292ddafb9a0456ac9f87d201"
-dependencies = [
- "libc",
-]
-
 [[package]]
 name = "cranelift-assembler-x64"
 version = "0.134.3"
@@ -352,7 +328,7 @@ dependencies = [
 "rustc-hash",
 "serde",
 "serde_derive",
- "sha2 0.10.9",
+ "sha2",
 "smallvec",
 "target-lexicon",
 "wasmtime-internal-core",
@@ -478,15 +454,6 @@ dependencies = [
 "typenum",
 ]

-[[package]]
-name = "crypto-common"
-version = "0.2.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ce6e4c961d6cd6c9a86db418387425e8bdeaf05b3c8bc1411e6dca4c252f1453"
-dependencies = [
- "hybrid-array",
-]
-
 [[package]]
 name = "debugid"
 version = "0.8.0"
@@ -502,19 +469,8 @@ version = "0.10.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9ed9a281f7bc9b7576e61468ba615a66a5c8cfdff42420a70aa82701a3b1e292"
 dependencies = [
- "block-buffer 0.10.4",
- "crypto-common 0.1.7",
-]
-
-[[package]]
-name = "digest"
-version = "0.11.3"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f1dd6dbb5841937940781866fa1281a1ff7bd3bf827091440879f9994983d5c2"
-dependencies = [
- "block-buffer 0.12.1",
- "const-oid",
- "crypto-common 0.2.2",
+ "block-buffer",
+ "crypto-common",
 ]

 [[package]]
@@ -795,15 +751,6 @@ dependencies = [
 "windows-sys",
 ]

-[[package]]
-name = "hybrid-array"
-version = "0.4.14"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "707114b52a152fa7bdb290cd7cd5912d9467273b6d74e21b8d81aca1f8533f6b"
-dependencies = [
- "typenum",
-]
-
 [[package]]
 name = "id-arena"
 version = "2.3.0"
@@ -1400,13 +1347,13 @@ dependencies = [

 [[package]]
 name = "sha1"
-version = "0.11.0"
+version = "0.10.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "aacc4cc499359472b4abe1bf11d0b12e688af9a805fa5e3016f9a386dc2d0214"
+checksum = "a978451301f4db1d02937a4ab3ccce137717b81826e79b7d49ffe3244a13c3b8"
 dependencies = [
 "cfg-if",
- "cpufeatures 0.3.0",
- "digest 0.11.3",
+ "cpufeatures",
+ "digest",
 ]

 [[package]]
@@ -1416,19 +1363,8 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a7507d819769d01a365ab707794a4084392c824f54a7a6a7862f8c3d0892b283"
 dependencies = [
 "cfg-if",
- "cpufeatures 0.2.17",
- "digest 0.10.7",
-]
-
-[[package]]
-name = "sha2"
-version = "0.11.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "446ba717509524cb3f22f17ecc096f10f4822d76ab5c0b9822c5f9c284e825f4"
-dependencies = [
- "cfg-if",
- "cpufeatures 0.3.0",
- "digest 0.11.3",
+ "cpufeatures",
+ "digest",
 ]

 [[package]]
@@ -1653,7 +1589,7 @@ checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a"

 [[package]]
 name = "wafer"
-version = "0.2.1"
+version = "0.3.0"
 dependencies = [
 "anyhow",
 "clap",
@@ -1664,13 +1600,13 @@ dependencies = [

 [[package]]
 name = "wafer-core"
-version = "0.2.1"
+version = "0.3.0"
 dependencies = [
 "anyhow",
 "insta",
 "proptest",
 "sha1",
- "sha2 0.11.0",
+ "sha2",
 "thiserror 2.0.19",
 "wasm-encoder 0.255.0",
 "wasmparser 0.255.0",
@@ -1679,7 +1615,7 @@ dependencies = [

 [[package]]
 name = "wafer-web"
-version = "0.2.1"
+version = "0.3.0"
 dependencies = [
 "anyhow",
 "js-sys",
@@ -1966,7 +1902,7 @@ dependencies = [
 "semver",
 "serde",
 "serde_derive",
- "sha2 0.10.9",
+ "sha2",
 "smallvec",
 "target-lexicon",
 "wasm-encoder 0.252.0",
@@ -1989,7 +1925,7 @@ dependencies = [
 "rustix",
 "serde",
 "serde_derive",
- "sha2 0.10.9",
+ "sha2",
 "toml",
 "wasmtime-environ",
 "windows-sys",
@@ -2239,18 +2175,18 @@ dependencies = [

 [[package]]
 name = "zerocopy"
-version = "0.8.55"
+version = "0.8.56"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b5a105cd7b140f6eeec8acff2ea38135d3cab283ada58540f629fe51e46696eb"
+checksum = "556764e583adb45a9f8d413c2a147fa7e8d821e48e12b14fd560b607998b75eb"
 dependencies = [
 "zerocopy-derive",
 ]

 [[package]]
 name = "zerocopy-derive"
-version = "0.8.55"
+version = "0.8.56"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0fe976fb70c78cd64cccfe3a6fc142244e8a77b70959b30faf9d0ac37ee228eb"
+checksum = "f2ab42fc20575779bd240faa45f94a74256f755c0fa9e89f0ede20d91d0cdfc1"
 dependencies = [
 "proc-macro2",
 "quote",
@@ -3,7 +3,7 @@ members = ["crates/*"]
 resolver = "2"

 [workspace.package]
-version = "0.2.1"
+version = "0.3.0"
 edition = "2024"
 license = "MIT OR Apache-2.0"
 repository = "https://github.com/ok2/wafer"
@@ -48,6 +48,14 @@ anyhow = "1"
 thiserror = "2"
 proptest = "1"
 insta = "1"
-sha1 = "0.11"
-sha2 = "0.11"
+sha1 = "0.10"
+sha2 = "0.10"
 send_wrapper = "0.6"
+
+# Cargo strips debuginfo from release artifacts by default, and on macOS that
+# also strips the metadata proc-macro dylibs need to be loadable — release
+# builds then fail with "can't find crate" for every proc-macro (rustversion,
+# thiserror_impl, ...). Build scripts and proc-macros gain nothing from
+# stripping, so exempt them; the release binaries stay stripped.
+[profile.release.build-override]
+strip = false
@@ -7,10 +7,11 @@ An optimizing Forth 2012 compiler targeting WebAssembly. WAFER JIT-compiles each
 ## Highlights

 - **200+ words** across 12 Forth 2012 word sets, all at **100% compliance**
- **Optimizing compiler** with 6 IR passes + stack-to-local promotion (loops + IF) + consolidation
- **Faster than gforth** on all benchmarks in release mode (2-10x faster)
+- **Optimizing compiler** with 6 IR passes + stack-to-local promotion (per region, so a hot loop keeps its registers even inside a word that does I/O; `DO` and `BEGIN` loops alike) + consolidation
+- **Faster than gforth** on every benchmark, and past SwiftForth `sf64` -- a native-code compiler -- on five of six
 - **JIT compilation** — each `:` definition compiles to its own WASM module
 - **Self-recursive direct calls** — RECURSE compiles to native `call` instead of `call_indirect`
+- **Typed calling convention** — a word with a statically known stack effect passes its stack items as WASM values, so a call keeps them in registers instead of round-tripping through memory
 - **Consolidation mode** — recompile all words into a single optimized WASM module
 - **Interactive REPL** with line editing (rustyline)
 - **Browser REPL** — runs entirely in the browser via wasm-pack + js-sys
@@ -79,38 +80,106 @@ git submodule update --init

 ## Performance

-WAFER beats gforth (the GNU Forth reference implementation) on all benchmarks in release mode:
+WAFER beats gforth (the GNU Forth reference implementation) on every benchmark by 3-20x, and
+SwiftForth `sf64` -- which compiles to native code -- on five of the six. Fibonacci is the one it
+loses: one call per node, no loop to promote, and `sf64` keeps its stack in registers across a call
+the way only a native code generator can.
+
+Measured on the development machine (M1 Ultra, arm64), median of three reports:

 ```
-Benchmark                   WAFER     CONSOL     gforth      WAFER/gf
-Fibonacci(25)                1629       1535       3422        0.45x
-Factorial(12)x10K             340        339        638        0.53x
-GCD-bench(500)                 18         15         30        0.50x
-NestedLoops(50)                84         73        720        0.10x
-Collatz(2K)                  1212       1202       3914        0.31x
+Benchmark                   WAFER     CONSOL     gforth       sf64    WAFER/gf   WAFER/sf
+Fibonacci(33)               11307      11407     157001      13053       0.07x      0.87x
+Factorial(12)x2M             9639       9599     123950      32091       0.08x      0.30x
+GCD-bench(400K)             11662      11580      38580      17001       0.30x      0.68x
+NestedLoops(50)x20K          8920       9852     140518      36828       0.06x      0.24x
+CrossCalls(3M)              10883       3769      87691       8240       0.04x      0.46x
+Collatz(2K)x50               8838       8715     189903      28657       0.05x      0.30x
 ```

-Times in microseconds. WAFER/gf < 1.0 means WAFER is faster. CONSOL = after `CONSOLIDATE`.
+Times in microseconds; the ratios use the better of `WAFER` and `CONSOL`. Below 1.0 means WAFER is
+faster.
+
+**The `sf64` column here flatters WAFER, and by enough to change an answer.** The only SwiftForth
+build for macOS is x86-64 running under Rosetta 2, while WAFER and gforth are native arm64 -- so
+that column compares native code against emulated code, and the penalty falls hardest on the
+call-heavy benchmark. Measured with all three engines native on x86-64 (Xeon Platinum 8124M,
+Ubuntu 22.04; two reports agreed within 1%), Fibonacci reads **1.21x** where the table above says
+0.87x; the other five keep their wins. That native comparison is what the "five of six" above
+rests on:
+
+```
+Benchmark                   WAFER     CONSOL     gforth       sf64    WAFER/gf   WAFER/sf
+Fibonacci(33)               19512      19511     129784      16076       0.15x      1.21x
+Factorial(12)x2M            22532      16601     137168      57986       0.12x      0.29x
+GCD-bench(400K)             34216      34089      66595      51680       0.51x      0.66x
+NestedLoops(50)x20K         10729      17827     126687      40469       0.08x      0.27x
+CrossCalls(3M)              20457       7412      81303      29264       0.09x      0.25x
+Collatz(2K)x50              18686      17328     188592      80857       0.09x      0.21x
+```
+
+A second caveat holds on any host: `sf64` uses 64-bit cells to WAFER's 32-bit, so WAFER does less
+work per operation.
+
+`CrossCalls` is the only benchmark with a cross-word call left in its hot loop -- the other five
+have their callee inlined away or are self-recursive -- so it is the only one that measures what
+`CONSOLIDATE` does, and there it is worth 2.9x. `NestedLoops` goes the other way: `CONSOLIDATE`
+makes it 1.1x _slower_ on the M1 and 1.7x on x86-64 -- not worse code but worse luck. Both paths
+emit identical WASM for the hot word; the delta is where the machine code lands. A tight loop
+pays for straddling an instruction-fetch window (16 bytes on the M1, 32 on Skylake, where a fused
+branch crossing the boundary drops the loop out of the uop cache -- the JCC erratum), Cranelift
+does not align loop headers, and dead prologue bytes in the per-word JIT module happen to shift
+its loops into luckier spots. Details in
+[docs/OPTIMIZATIONS.md](docs/OPTIMIZATIONS.md#8-consolidation).
+
+Every benchmark is sized to run about 10 ms. Not for the usual reason -- the timing wrapper already
+excludes start-up and compilation -- but to keep a comfortable margin over timer resolution and
+first-iteration effects without pushing the report past a minute. gforth is 3-20x slower than
+WAFER, so it sets the wall clock.
+
+A word whose stack effect is statically known gets a **typed entry point**: its stack items travel in and out
+as WASM values instead of through the memory data stack, so cranelift keeps them in registers across a call
+the way a native Forth keeps TOS in one. The word also keeps a `( -- )` wrapper, which is what the function
+table, `EXECUTE` and the outer interpreter reach, so nothing about the memory ABI changes from the outside.
+Only a caller inside the same module can use the fast entry -- `RECURSE` in the JIT path, every resolvable
+call after `CONSOLIDATE` -- so that is exactly when it is emitted. Set `WAFER_TYPED_CALLS=0` to fall back.
+
+Recursive words then get one more thing: their base-case guard is tested at the **call site**, so a
+leaf of the recursion costs a comparison instead of a call. `: FIB DUP 2 < IF EXIT THEN ... RECURSE`
+compiles its `RECURSE` as `DUP 2 < IF ELSE RECURSE THEN`, which is what the callee would have done
+on entry anyway. Half of fib's nodes are leaves, and that is worth 1.4x.

 ## Testing

+Everything below has a `just` target; the raw command is given where it is worth
+knowing what the target does.
+
 ```bash
-# All tests (~570 currently passing)
-cargo test --workspace
-
-# Forth 2012 compliance suite
-cargo test -p wafer-core --test compliance
-
-# Cross-engine comparison (WAFER vs gforth, requires gforth)
-cargo test -p wafer-core --test comparison -- --nocapture --ignored
-
-# Optimization benchmark report (WAFER-internal)
-cargo test -p wafer-core --test benchmark_report -- --nocapture --ignored
-
-# Lints
-cargo clippy --workspace
+just test            # all tests (~638 currently passing)
+just compliance      # Forth 2012 compliance suite
+just clippy          # lints
+just fmt             # formatting check (Rust + Markdown)
+just ci              # everything CI runs
 ```

+Benchmarks are separate, because they are `#[ignore]`d -- they take minutes, and
+a debug build would measure nothing useful:
+
+```bash
+just bench-compare       # WAFER vs gforth vs SwiftForth, the table in Performance
+just bench-opts          # WAFER against its own optimization settings
+just bench               # criterion micro-benchmarks
+just compare-correctness # same three engines, compared on output instead of time
+```
+
+`bench-compare` needs `gforth` and `sf64` on `PATH` -- a missing engine drops its
+column rather than failing. Each number in it is the best of three processes, and
+each process reports the mean of its three fastest of seven timed repetitions:
+benchmark noise is one-sided, so the fastest runs are the honest ones, and only a
+fresh process resamples core placement and code layout. Run it on an idle
+machine; a busy one produced 20-79% run-to-run spread where an idle one gives
+1-6%.
+
 ## Architecture

 ```
@@ -128,7 +197,7 @@ Forth Source -> Outer Interpreter -> IR -> [Optimize] -> WASM Codegen (wasm-enco
  - `WebRuntime` — browser WebAssembly API via js-sys, for the browser REPL
 - **Subroutine threading** via WASM function tables (`call_indirect` for cross-word, direct `call` for self-recursion)
 - **JIT mode**: each new word compiles to a separate WASM module linked to shared memory/globals/table
- **IR-based pipeline** with 6 optimization passes (peephole, constant folding, strength reduction, DCE, tail call detection, inlining) plus stack-to-local promotion (with loop and IF/ELSE support), DO/LOOP index locals, and consolidation
+- **IR-based pipeline** with 6 optimization passes (peephole, constant folding, strength reduction, DCE, tail call detection, inlining) plus per-region stack-to-local promotion (DO and BEGIN loops, IF/ELSE), DO/LOOP index locals, typed entry points for words with a known stack effect, self-guard expansion, and consolidation
 - **Dictionary**: linked-list word headers in simulated linear memory

 ## Project Structure
@@ -9,7 +9,7 @@ license.workspace = true
 workspace = true

 [dependencies]
-wafer-core = { path = "../core", version = "0.2.1" }
+wafer-core = { path = "../core", version = "0.3.0" }
 wasmtime = { workspace = true }
 anyhow = { workspace = true }
 clap = { version = "4", features = ["derive"] }
@@ -263,7 +263,8 @@ fn cmd_run(file: &str) -> anyhow::Result<()> {
 }

 /// `WaferConfig` for CLI-created VMs. `WAFER_STACK_GUARDS=0|1` overrides
-/// the per-command default (REPL/file execution on, build off).
+/// the per-command default (REPL/file execution on, build off);
+/// `WAFER_TYPED_CALLS=0` falls back to the memory-stack calling convention.
 fn vm_config(default_guards: bool) -> wafer_core::config::WaferConfig {
    let mut cfg = wafer_core::config::WaferConfig::all();
    cfg.codegen.stack_guards = match std::env::var("WAFER_STACK_GUARDS").ok().as_deref() {
@@ -271,6 +272,7 @@ fn vm_config(default_guards: bool) -> wafer_core::config::WaferConfig {
        Some(_) => true,
        None => default_guards,
    };
+    cfg.codegen.typed_calls = std::env::var("WAFER_TYPED_CALLS").ok().as_deref() != Some("0");
    cfg
 }

@@ -12,6 +12,11 @@ pub struct CodegenOpts {
    /// corrupting stack pointers. On by default; benchmarks and
    /// exported production modules turn it off.
    pub stack_guards: bool,
+    /// Compile words with a statically known stack effect to a typed entry
+    /// point that carries stack items in WASM values, so a call keeps them
+    /// in registers instead of round-tripping through the memory stack.
+    /// On by default; `WAFER_TYPED_CALLS=0` turns it off.
+    pub typed_calls: bool,
 }

 /// Master configuration for all WAFER optimizations.
@@ -34,10 +39,12 @@ impl WaferConfig {
                strength_reduce: true,
                dce: true,
                inline: true,
+                self_guard: true,
            },
            codegen: CodegenOpts {
                stack_to_local_promotion: true,
                stack_guards: true,
+                typed_calls: true,
            },
        }
    }
@@ -52,10 +59,12 @@ impl WaferConfig {
                strength_reduce: false,
                dce: false,
                inline: false,
+                self_guard: false,
            },
            codegen: CodegenOpts {
                stack_to_local_promotion: false,
                stack_guards: false,
+                typed_calls: false,
            },
        }
    }
@@ -21,7 +21,7 @@ mod tests {
        // Empty word list should produce nothing (but we guard against this at call site)
        let words = vec![];
        let map = HashMap::new();
-        let result = compile_consolidated_module(&words, &map, 16, None);
+        let result = compile_consolidated_module(&words, &map, 16, None, true);
        // Empty is valid -- should produce a valid module with no functions
        assert!(result.is_ok());
    }
@@ -31,7 +31,7 @@ mod tests {
        let words = vec![(WordId(1), vec![IrOp::PushI32(42)])];
        let mut map = HashMap::new();
        map.insert(WordId(1), 1u32); // function index 1 (after emit import)
-        let result = compile_consolidated_module(&words, &map, 16, None);
+        let result = compile_consolidated_module(&words, &map, 16, None, true);
        assert!(result.is_ok());
    }

@@ -49,7 +49,7 @@ mod tests {
        map.insert(WordId(1), 1u32);
        map.insert(WordId(2), 2u32);
        map.insert(WordId(3), 3u32);
-        let result = compile_consolidated_module(&words, &map, 16, None);
+        let result = compile_consolidated_module(&words, &map, 16, None, true);
        assert!(result.is_ok());
    }

@@ -59,7 +59,7 @@ mod tests {
        let words = vec![(WordId(3), vec![IrOp::Call(WordId(99))])];
        let mut map = HashMap::new();
        map.insert(WordId(3), 1u32);
-        let result = compile_consolidated_module(&words, &map, 256, None);
+        let result = compile_consolidated_module(&words, &map, 256, None, true);
        assert!(result.is_ok());
    }

@@ -72,7 +72,7 @@ mod tests {
        let mut map = HashMap::new();
        map.insert(WordId(1), 1u32);
        map.insert(WordId(2), 2u32);
-        let result = compile_consolidated_module(&words, &map, 16, None);
+        let result = compile_consolidated_module(&words, &map, 16, None, true);
        assert!(result.is_ok());
    }

@@ -95,7 +95,7 @@ mod tests {
        let mut map = HashMap::new();
        map.insert(WordId(1), 1u32);
        map.insert(WordId(2), 2u32);
-        let result = compile_consolidated_module(&words, &map, 16, None);
+        let result = compile_consolidated_module(&words, &map, 16, None, true);
        assert!(result.is_ok());
    }

@@ -120,7 +120,7 @@ mod tests {
        let mut map = HashMap::new();
        map.insert(WordId(1), 1u32);
        map.insert(WordId(2), 2u32);
-        let result = compile_consolidated_module(&words, &map, 16, None);
+        let result = compile_consolidated_module(&words, &map, 16, None, true);
        assert!(result.is_ok());
    }

@@ -141,7 +141,7 @@ mod tests {
        let mut map = HashMap::new();
        map.insert(WordId(1), 1u32);
        map.insert(WordId(2), 2u32);
-        let result = compile_consolidated_module(&words, &map, 16, None);
+        let result = compile_consolidated_module(&words, &map, 16, None, true);
        assert!(result.is_ok());
    }

@@ -163,7 +163,7 @@ mod tests {
        let mut map = HashMap::new();
        map.insert(WordId(1), 1u32);
        map.insert(WordId(2), 2u32);
-        let result = compile_consolidated_module(&words, &map, 16, None);
+        let result = compile_consolidated_module(&words, &map, 16, None, true);
        assert!(result.is_ok());
    }
 }
@@ -126,6 +126,7 @@ pub fn export_module(
        table_size,
        &export_sections,
        vm.stack_guard_param(),
+        vm.typed_calls(),
    )
    .map_err(|e| anyhow::anyhow!("export codegen error: {e}"))?;

@@ -108,6 +108,23 @@ pub const SYSVAR_HLD: u32 = SYSVAR_BASE + 28;
 pub const SYSVAR_LEAVE_FLAG: u32 = SYSVAR_BASE + 32;
 /// Throw code left by a compiled stack-guard fault for `_STACK_FAULT_`.
 pub const SYSVAR_FAULT_CODE: u32 = SYSVAR_BASE + 36;
+/// DPL: digits right of the rightmost punctuation in the last converted
+/// number; negative when the token carried no punctuation.
+pub const SYSVAR_DPL: u32 = SYSVAR_BASE + 40;
+/// NH: high-order cell of the last single-cell conversion, so an
+/// out-of-range token can be recovered as a double.
+pub const SYSVAR_NH: u32 = SYSVAR_BASE + 44;
+
+/// Seed for [`SYSVAR_DPL`] before conversion starts.
+///
+/// `SwiftForth` seeds DPL with a negative value and bumps it once per digit,
+/// so an unpunctuated token still ends up negative. Punctuation resets the
+/// counter to zero, which makes the final value the digit count right of the
+/// rightmost punctuation character.
+///
+/// The exact seed is observable: `sf64` reports DPL as -1020 after `1234`
+/// and -1023 after `-1`, both of which pin it to -1024.
+pub const DPL_INIT: i32 = -1024;

 #[cfg(test)]
 mod tests {
@@ -149,6 +166,9 @@ mod tests {
            SYSVAR_NUM_TIB,
            SYSVAR_HLD,
            SYSVAR_LEAVE_FLAG,
+            SYSVAR_FAULT_CODE,
+            SYSVAR_DPL,
+            SYSVAR_NH,
        ];
        for offset in all_offsets {
            assert!(offset + CELL_SIZE <= SYSVAR_BASE + SYSVAR_SIZE);
@@ -27,6 +27,9 @@ pub struct OptConfig {
    pub dce: bool,
    /// Enable inlining of small word bodies.
    pub inline: bool,
+    /// Expand a recursive word's base-case guard into its own call sites, so
+    /// the leaves of the recursion cost a test instead of a call.
+    pub self_guard: bool,
 }

 /// Run all enabled optimization passes.
@@ -34,6 +37,7 @@ pub fn optimize(
    ops: Vec<IrOp>,
    config: &OptConfig,
    bodies: &HashMap<WordId, Vec<IrOp>>,
+    self_id: Option<WordId>,
 ) -> Vec<IrOp> {
    let mut ir = ops;

@@ -53,7 +57,25 @@ pub fn optimize(

    // Phase 2: inline then simplify again
    if config.inline {
-        ir = inline(ir, bodies, 8);
+        // A caller that can never leave the memory data stack would drag an
+        // inlined loop down with it, so leave those callees where they are:
+        // as their own word the loop keeps its registers, and one call is far
+        // cheaper than a loop's worth of memory traffic.
+        //
+        // This takes two passes, because before the primitives are substituted
+        // the caller is nothing but `Call`s -- `DROP` and `CR` included -- and
+        // the promotability check deliberately looks through calls. Asked too
+        // early it says "promotable" about almost anything, which is how this
+        // guard managed to be a no-op. Inline the loop-free callees first, then
+        // ask, then let the loop-bearing ones in if the answer was yes.
+        ir = inline(ir, bodies, 8, true);
+        let keep_loops_out = !crate::codegen::promotable_modulo_calls(&ir);
+        ir = inline(ir, bodies, 8, keep_loops_out);
+    }
+    if config.self_guard
+        && let Some(id) = self_id
+    {
+        ir = expand_self_guard(ir, id);
    }
    if config.peephole {
        ir = peephole(ir);
@@ -496,7 +518,12 @@ fn dce(ops: Vec<IrOp>) -> Vec<IrOp> {

 /// Inline small word bodies: replaces `Call(id)` with the word's IR body
 /// if the body is small enough and not recursive.
-fn inline(ops: Vec<IrOp>, bodies: &HashMap<WordId, Vec<IrOp>>, max_size: usize) -> Vec<IrOp> {
+fn inline(
+    ops: Vec<IrOp>,
+    bodies: &HashMap<WordId, Vec<IrOp>>,
+    max_size: usize,
+    keep_loops_out: bool,
+) -> Vec<IrOp> {
    let mut out = Vec::new();
    for op in ops {
        match &op {
@@ -505,6 +532,7 @@ fn inline(ops: Vec<IrOp>, bodies: &HashMap<WordId, Vec<IrOp>>, max_size: usize)
                    && body.len() <= max_size
                    && !contains_call_to(body, *id)
                    && !contains_exit(body)
+                    && !(keep_loops_out && crate::codegen::contains_loop(body))
                {
                    // Inline the body, recursively converting TailCall back to Call
                    // (tail position in the callee is not tail position in the caller).
@@ -517,7 +545,7 @@ fn inline(ops: Vec<IrOp>, bodies: &HashMap<WordId, Vec<IrOp>>, max_size: usize)
            }
            _ => {
                out.push(apply_to_bodies(op, &|inner| {
-                    inline(inner, bodies, max_size)
+                    inline(inner, bodies, max_size, keep_loops_out)
                }));
            }
        }
@@ -574,6 +602,142 @@ fn detailcall(op: IrOp) -> IrOp {
 }

 /// Check if an IR body contains a direct call to the given word (recursion guard).
+/// Largest guard the expander is willing to run twice, in IR operations.
+const MAX_GUARD_OPS: usize = 6;
+/// Most self-call sites worth expanding, to bound the code growth.
+const MAX_GUARD_SITES: usize = 4;
+
+/// Expand a recursive word's base-case guard into its own call sites.
+///
+/// A recursive Forth word almost always opens with a guard that returns early
+/// -- `: FIB DUP 2 < IF EXIT THEN ... RECURSE ... ;` -- so every leaf of the
+/// recursion costs a call whose whole body is that test. Testing at the call
+/// site instead removes the call for the leaves, which in fib's tree is half
+/// of all nodes.
+///
+/// `Call(self)` becomes `<guard> IF <what the guard returns> ELSE Call(self)
+/// THEN`, which computes the same thing: the callee would have run the guard,
+/// taken the branch and returned. The price is that the guard runs twice along
+/// the recursive path, which is why it has to be small and free of effects.
+fn expand_self_guard(ops: Vec<IrOp>, self_id: WordId) -> Vec<IrOp> {
+    let Some((cond, base)) = split_guard(&ops) else {
+        return ops;
+    };
+    if count_self_calls(&ops, self_id) > MAX_GUARD_SITES {
+        return ops;
+    }
+    let (cond, base) = (cond.to_vec(), base.to_vec());
+    replace_self_calls(ops, self_id, &cond, &base)
+}
+
+/// Split a body into the condition of its leading base-case guard and what
+/// that guard leaves behind, or `None` if it does not open with one.
+fn split_guard(ops: &[IrOp]) -> Option<(&[IrOp], &[IrOp])> {
+    let at = ops.iter().position(|op| matches!(op, IrOp::If { .. }))?;
+    let cond = &ops[..at];
+    if at > MAX_GUARD_OPS || !cond.iter().all(is_duplicable) {
+        return None;
+    }
+    let IrOp::If {
+        then_body,
+        else_body: None,
+    } = &ops[at]
+    else {
+        return None;
+    };
+    // The guard is only a guard if it returns; what precedes the `EXIT` is
+    // the value it returns, and has to be as harmless as the condition.
+    let (IrOp::Exit, base) = then_body.split_last()? else {
+        return None;
+    };
+    if base.len() > MAX_GUARD_OPS || !base.iter().all(is_duplicable) {
+        return None;
+    }
+    Some((cond, base))
+}
+
+/// Can this operation be duplicated at every call site -- cheap, effect-free,
+/// and not itself a call or a branch?
+fn is_duplicable(op: &IrOp) -> bool {
+    matches!(
+        op,
+        IrOp::PushI32(_)
+            | IrOp::Drop
+            | IrOp::Dup
+            | IrOp::Swap
+            | IrOp::Over
+            | IrOp::Rot
+            | IrOp::Nip
+            | IrOp::Tuck
+            | IrOp::TwoDup
+            | IrOp::TwoDrop
+            | IrOp::Add
+            | IrOp::Sub
+            | IrOp::Mul
+            | IrOp::Negate
+            | IrOp::Abs
+            | IrOp::Eq
+            | IrOp::NotEq
+            | IrOp::Lt
+            | IrOp::Gt
+            | IrOp::LtUnsigned
+            | IrOp::ZeroEq
+            | IrOp::ZeroLt
+            | IrOp::And
+            | IrOp::Or
+            | IrOp::Xor
+            | IrOp::Invert
+            | IrOp::Lshift
+            | IrOp::Rshift
+            | IrOp::ArithRshift
+    )
+}
+
+fn count_self_calls(ops: &[IrOp], self_id: WordId) -> usize {
+    ops.iter()
+        .map(|op| match op {
+            IrOp::Call(id) if *id == self_id => 1,
+            IrOp::If {
+                then_body,
+                else_body,
+            } => {
+                count_self_calls(then_body, self_id)
+                    + else_body
+                        .as_deref()
+                        .map_or(0, |eb| count_self_calls(eb, self_id))
+            }
+            _ => 0,
+        })
+        .sum()
+}
+
+/// Wrap every `Call(self_id)` in the guard. Only plain calls: a `TailCall` is
+/// followed by a return, and leaving those alone keeps tail-call detection and
+/// this pass from having to agree about what tail position means.
+fn replace_self_calls(ops: Vec<IrOp>, self_id: WordId, cond: &[IrOp], base: &[IrOp]) -> Vec<IrOp> {
+    let mut out = Vec::with_capacity(ops.len());
+    for op in ops {
+        match op {
+            IrOp::Call(id) if id == self_id => {
+                out.extend_from_slice(cond);
+                out.push(IrOp::If {
+                    then_body: base.to_vec(),
+                    else_body: Some(vec![IrOp::Call(id)]),
+                });
+            }
+            IrOp::If {
+                then_body,
+                else_body,
+            } => out.push(IrOp::If {
+                then_body: replace_self_calls(then_body, self_id, cond, base),
+                else_body: else_body.map(|eb| replace_self_calls(eb, self_id, cond, base)),
+            }),
+            other => out.push(other),
+        }
+    }
+    out
+}
+
 fn contains_call_to(ops: &[IrOp], target: WordId) -> bool {
    for op in ops {
        match op {
@@ -735,8 +899,173 @@ mod tests {
            strength_reduce: true,
            dce: true,
            inline: false,
+            self_guard: false,
        };
-        optimize(ops, &config, &HashMap::new())
+        optimize(ops, &config, &HashMap::new(), None)
+    }
+
+    /// A body shaped like a recursive Forth word: a base-case guard, then the
+    /// recursive step. `SELF` is the word being compiled.
+    const SELF: WordId = WordId(9);
+
+    fn guarded_body(step: Vec<IrOp>) -> Vec<IrOp> {
+        let mut ops = vec![
+            IrOp::Dup,
+            IrOp::PushI32(2),
+            IrOp::Lt,
+            IrOp::If {
+                then_body: vec![IrOp::Exit],
+                else_body: None,
+            },
+        ];
+        ops.extend(step);
+        ops
+    }
+
+    #[test]
+    fn self_guard_moves_the_base_case_to_the_call_site() {
+        let out = expand_self_guard(guarded_body(vec![IrOp::Call(SELF)]), SELF);
+        assert_eq!(
+            out,
+            guarded_body(vec![
+                IrOp::Dup,
+                IrOp::PushI32(2),
+                IrOp::Lt,
+                IrOp::If {
+                    then_body: vec![],
+                    else_body: Some(vec![IrOp::Call(SELF)]),
+                },
+            ])
+        );
+    }
+
+    #[test]
+    fn self_guard_carries_the_value_the_guard_returns() {
+        // `: F DUP 2 < IF DROP 0 EXIT THEN RECURSE ;` -- the base case is not
+        // "leave the argument", it is "replace it with 0".
+        let body = vec![
+            IrOp::Dup,
+            IrOp::PushI32(2),
+            IrOp::Lt,
+            IrOp::If {
+                then_body: vec![IrOp::Drop, IrOp::PushI32(0), IrOp::Exit],
+                else_body: None,
+            },
+            IrOp::Call(SELF),
+        ];
+        let out = expand_self_guard(body, SELF);
+        let IrOp::If { then_body, .. } = &out[7] else {
+            panic!("expected the expanded guard at index 7, got {out:?}");
+        };
+        assert_eq!(then_body, &vec![IrOp::Drop, IrOp::PushI32(0)]);
+    }
+
+    #[test]
+    fn self_guard_leaves_a_body_without_a_guard_alone() {
+        // An `IF` with an `ELSE` is a branch, not an early return.
+        let body = vec![
+            IrOp::Dup,
+            IrOp::If {
+                then_body: vec![IrOp::Drop],
+                else_body: Some(vec![IrOp::Call(SELF)]),
+            },
+        ];
+        assert_eq!(expand_self_guard(body.clone(), SELF), body);
+
+        // No `EXIT` in the then-branch: also not a guard.
+        let body = guarded_body(vec![IrOp::Call(SELF)])
+            .into_iter()
+            .map(|op| match op {
+                IrOp::If { .. } => IrOp::If {
+                    then_body: vec![IrOp::Drop],
+                    else_body: None,
+                },
+                other => other,
+            })
+            .collect::<Vec<_>>();
+        assert_eq!(expand_self_guard(body.clone(), SELF), body);
+    }
+
+    #[test]
+    fn self_guard_refuses_a_condition_it_cannot_run_twice() {
+        // A guard reached through a call or a memory write would be evaluated
+        // once at the call site and again inside the callee.
+        let body = vec![
+            IrOp::Call(WordId(3)),
+            IrOp::If {
+                then_body: vec![IrOp::Exit],
+                else_body: None,
+            },
+            IrOp::Call(SELF),
+        ];
+        assert_eq!(expand_self_guard(body.clone(), SELF), body);
+
+        let body = vec![
+            IrOp::Dup,
+            IrOp::Fetch,
+            IrOp::If {
+                then_body: vec![IrOp::Exit],
+                else_body: None,
+            },
+            IrOp::Call(SELF),
+        ];
+        assert_eq!(expand_self_guard(body.clone(), SELF), body);
+    }
+
+    #[test]
+    fn self_guard_stops_at_the_call_site_budget() {
+        let step = std::iter::repeat_n(IrOp::Call(SELF), MAX_GUARD_SITES + 1).collect();
+        let body = guarded_body(step);
+        assert_eq!(expand_self_guard(body.clone(), SELF), body);
+    }
+
+    #[test]
+    fn self_guard_leaves_tail_calls_alone() {
+        let body = guarded_body(vec![IrOp::TailCall(SELF)]);
+        assert_eq!(expand_self_guard(body.clone(), SELF), body);
+    }
+
+    #[test]
+    fn a_loop_stays_out_of_a_caller_that_is_only_unpromotable_through_a_call() {
+        // The shape the benchmark harness uses, and the one that made this
+        // guard a no-op for its whole life: at the moment the guard runs, the
+        // caller's `CR` is still `Call(cr_word)`, not `IrOp::Cr`. A test built
+        // from `IrOp::Cr` directly passes even with the bug.
+        let cross = WordId(7);
+        let cr = WordId(9);
+        let mut bodies = HashMap::new();
+        bodies.insert(cr, vec![IrOp::Cr]);
+        bodies.insert(
+            cross,
+            vec![
+                IrOp::PushI32(0),
+                IrOp::Swap,
+                IrOp::PushI32(0),
+                IrOp::DoLoop {
+                    body: vec![IrOp::RFetch, IrOp::Call(WordId(8)), IrOp::Xor],
+                    is_plus_loop: false,
+                },
+            ],
+        );
+        let out = opt_with_inline(
+            vec![
+                IrOp::PushI32(300000),
+                IrOp::Call(cross),
+                IrOp::Drop,
+                IrOp::Call(cr),
+            ],
+            &bodies,
+        );
+        assert!(
+            out.iter()
+                .any(|op| matches!(op, IrOp::Call(id) if *id == cross)),
+            "a loop-bearing callee must not be inlined into a caller that cannot \
+             be promoted -- it would lose its registers: {out:?}"
+        );
+        assert!(
+            out.iter().any(|op| matches!(op, IrOp::Cr)),
+            "the loop-free callee should still have been inlined: {out:?}"
+        );
    }

    fn opt_with_inline(ops: Vec<IrOp>, bodies: &HashMap<WordId, Vec<IrOp>>) -> Vec<IrOp> {
@@ -747,8 +1076,9 @@ mod tests {
            strength_reduce: true,
            dce: true,
            inline: true,
+            self_guard: false,
        };
-        optimize(ops, &config, bodies)
+        optimize(ops, &config, bodies, None)
    }

    // Peephole tests
@@ -1008,8 +1338,59 @@ mod tests {
            strength_reduce: false,
            dce: false,
            inline: true,
+            self_guard: false,
        };
-        let result = optimize(vec![IrOp::Call(WordId(5))], &config, &bodies);
+        let result = optimize(vec![IrOp::Call(WordId(5))], &config, &bodies, None);
        assert_eq!(result, vec![IrOp::Call(WordId(5))]);
    }
+
+    #[test]
+    fn keeps_a_loop_out_of_a_caller_stuck_on_the_memory_stack() {
+        // The caller has a `.`, so it can never leave the memory data stack.
+        // Inlining the loop would drag it down too; as its own word the loop
+        // keeps its registers and the caller just pays one call.
+        let mut bodies = HashMap::new();
+        bodies.insert(
+            WordId(5),
+            vec![IrOp::DoLoop {
+                body: vec![IrOp::PushI32(1), IrOp::Add],
+                is_plus_loop: false,
+            }],
+        );
+        let result = opt_with_inline(vec![IrOp::Call(WordId(5)), IrOp::Dot], &bodies);
+        assert!(
+            matches!(result.first(), Some(IrOp::Call(WordId(5)))),
+            "loop should not have been inlined, got {result:?}"
+        );
+    }
+
+    #[test]
+    fn still_inlines_a_loop_into_a_caller_that_can_be_promoted() {
+        let mut bodies = HashMap::new();
+        bodies.insert(
+            WordId(5),
+            vec![IrOp::DoLoop {
+                body: vec![IrOp::PushI32(1), IrOp::Add],
+                is_plus_loop: false,
+            }],
+        );
+        let result = opt_with_inline(vec![IrOp::Call(WordId(5)), IrOp::Dup], &bodies);
+        assert!(
+            !result.iter().any(|op| matches!(op, IrOp::Call(_))),
+            "loop should have been inlined, got {result:?}"
+        );
+    }
+
+    #[test]
+    fn still_inlines_straight_line_words_anywhere() {
+        // Only loops are held back; a small straight-line word is still
+        // better off inlined even into an unpromotable caller.
+        let mut bodies = HashMap::new();
+        bodies.insert(WordId(5), vec![IrOp::Dup, IrOp::Mul]);
+        let result = opt_with_inline(vec![IrOp::Call(WordId(5)), IrOp::Dot], &bodies);
+        assert!(
+            !result.iter().any(|op| matches!(op, IrOp::Call(_))),
+            "straight-line word should still inline, got {result:?}"
+        );
+    }
 }
@@ -350,6 +350,16 @@ pub const WORD_DOCS: &[(&str, &str, &str)] = &[
        "Convert digits, accumulating into ud.",
    ),
    ("BASE", "( -- addr )", "Variable holding the number base."),
+    (
+        "DPL",
+        "( -- addr )",
+        "Variable: digits right of the last punctuation; negative if none.",
+    ),
+    (
+        "NH",
+        "( -- addr )",
+        "Variable: high cell dropped by the last single-cell conversion.",
+    ),
    ("HEX", "( -- )", "Set BASE to sixteen."),
    ("DECIMAL", "( -- )", "Set BASE to ten."),
    // -- Core: strings --
@@ -706,6 +716,11 @@ pub const WORD_DOCS: &[(&str, &str, &str)] = &[
        "Read a line of input (unsupported here).",
    ),
    ("ABORT", "( i*x -- )", "Empty the stacks and abort."),
+    (
+        "QUIT",
+        "( -- ) ( R: i*x -- )",
+        "Empty the return stack, return to the interpreter; data stack kept.",
+    ),
    (
        "ABORT\"",
        "( flag -- )",
@@ -989,6 +1004,21 @@ pub const WORD_DOCS: &[(&str, &str, &str)] = &[
        "New definitions go to the top wordlist.",
    ),
    ("ALSO", "( -- )", "Duplicate the top of the search order."),
+    (
+        ">ORDER",
+        "( wid -- )",
+        "Push wid on top of the search order (gforth extension).",
+    ),
+    (
+        "-ORDER",
+        "( wid -- )",
+        "Remove wid from the search order (VFX extension).",
+    ),
+    (
+        "VOCABULARY",
+        "( \"name\" -- )",
+        "Create a named wordlist; executing name replaces the top of the search order.",
+    ),
    ("ONLY", "( -- )", "Reset the search order to the minimum."),
    ("PREVIOUS", "( -- )", "Drop the top of the search order."),
    (
@@ -468,6 +468,11 @@ fn programs() -> Vec<Program> {
            expected: "-1 \n-1 \n42 \n-1 \n",
            category: Category::Definitions,
        },
+        // QUIT is deliberately absent from this corpus: what it abandons is
+        // "the input source", and each engine here is fed differently (wafer
+        // line by line, gforth from a file, sf64 from a prompting stdin), so
+        // a comparison would measure the harness. Its semantics are pinned by
+        // the QUIT tests in outer.rs, checked by hand against both engines.
        // -- Strings --
        Program {
            name: "s-quote-type",
@@ -726,7 +731,6 @@ struct PerfBenchmark {
    run_code: &'static str,
    verify: &'static str,
    expected: i32,
-    samples: u32, // Number of runs for WAFER median
    /// Maximum acceptable WAFER/gforth ratio (< 1.0 = WAFER faster).
    /// Test fails if ratio exceeds this. Set ~40-50% above measured baseline.
    max_ratio: f64,
@@ -735,55 +739,68 @@ struct PerfBenchmark {
 fn perf_benchmarks() -> Vec<PerfBenchmark> {
    vec![
        PerfBenchmark {
-            name: "Fibonacci(25)",
+            name: "Fibonacci(33)",
            define: ": FIB DUP 2 < IF EXIT THEN DUP 1- RECURSE SWAP 2 - RECURSE + ;",
-            run_code: "25 FIB DROP",
-            verify: "25 FIB",
-            expected: 75025,
-            samples: 5,
-            max_ratio: 0.65,
+            run_code: "33 FIB DROP",
+            verify: "33 FIB",
+            expected: 3524578,
+            max_ratio: 0.10,
        },
        PerfBenchmark {
-            name: "Factorial(12)x10K",
+            name: "Factorial(12)x2M",
            define: ": FACT 1 SWAP 1+ 1 ?DO I * LOOP ; \
-                     : FACT-BENCH 10000 0 DO 12 FACT DROP LOOP ;",
+                     : FACT-BENCH 2000000 0 DO 12 FACT DROP LOOP ;",
            run_code: "FACT-BENCH",
            verify: "12 FACT",
            expected: 479001600,
-            samples: 5,
-            max_ratio: 0.75,
+            max_ratio: 0.12,
        },
        PerfBenchmark {
-            name: "GCD-bench(500)",
+            name: "GCD-bench(400K)",
            define: ": GCD BEGIN DUP WHILE TUCK MOD REPEAT DROP ; \
                     : GCD-BENCH 0 DO 10000 I 1+ GCD DROP LOOP ;",
-            run_code: "500 GCD-BENCH",
+            run_code: "400000 GCD-BENCH",
            verify: "48 36 GCD",
            expected: 12,
-            samples: 5,
-            max_ratio: 0.70,
+            max_ratio: 0.45,
        },
        PerfBenchmark {
-            name: "NestedLoops(50)",
+            name: "NestedLoops(50)x20K",
            define: ": NESTED 0 SWAP 0 DO I 0 ?DO I J + DROP LOOP LOOP ; \
-                     : NESTED-BENCH 100 0 DO 50 NESTED DROP LOOP ;",
+                     : NESTED-BENCH 20000 0 DO 50 NESTED DROP LOOP ;",
            run_code: "NESTED-BENCH",
            verify: "5 NESTED",
            expected: 0,
-            samples: 3,
-            max_ratio: 0.20,
+            max_ratio: 0.11,
        },
        PerfBenchmark {
-            name: "Collatz(2K)",
+            // The only benchmark with a cross-word call left in its hot loop:
+            // WORK is over the inliner's eight-operation budget, so it stays a
+            // real call. That is what CONSOLIDATE exists to turn into a direct
+            // one, and without this the CONSOL column measures nothing -- every
+            // other benchmark has its callee inlined away or self-recursive.
+            name: "CrossCalls(3M)",
+            define: ": WORK DUP 3 * OVER XOR SWAP 2 / XOR DUP 7 AND XOR DUP 1 AND XOR ; \
+                     : CROSS-BENCH 0 SWAP 0 DO I WORK XOR LOOP ;",
+            run_code: "3000000 CROSS-BENCH DROP",
+            verify: "1000 CROSS-BENCH",
+            expected: 3176,
+            // Guards CONSOLIDATE as much as the engine: the ratio uses the
+            // better of the two columns, so a consolidation regression here
+            // pushes it from 0.04 to 0.12 and trips the limit.
+            max_ratio: 0.08,
+        },
+        PerfBenchmark {
+            name: "Collatz(2K)x50",
            define: ": COLLATZ 0 SWAP BEGIN DUP 1 > WHILE \
                     DUP 1 AND IF 3 * 1+ ELSE 2 / THEN \
                     SWAP 1+ SWAP REPEAT DROP ; \
-                     : COLLATZ-BENCH 0 DO I 1+ COLLATZ DROP LOOP ;",
-            run_code: "2000 COLLATZ-BENCH",
+                     : COLLATZ-BENCH 0 DO I 1+ COLLATZ DROP LOOP ; \
+                     : COLLATZ-REPEAT 50 0 DO 2000 COLLATZ-BENCH LOOP ;",
+            run_code: "COLLATZ-REPEAT",
            verify: "27 COLLATZ",
            expected: 111,
-            samples: 3,
-            max_ratio: 0.45,
+            max_ratio: 0.08,
        },
    ]
 }
@@ -828,15 +845,16 @@ fn measure_wafer_release(wafer: &str, bench: &PerfBenchmark) -> Option<u64> {
    let code = format!(
        "{define} {run} \
         : TIMED-BENCH UTIME {run} UTIME 2SWAP D- DROP . CR ; \
-         TIMED-BENCH TIMED-BENCH TIMED-BENCH",
+         {reps}",
        define = bench.define,
        run = bench.run_code,
+        reps = repeat_timed(" "),
    );
    let output = run_via_stdin(wafer, &code)?;
    if !output.status.success() {
        return None;
    }
-    median_printed_time(&output.stdout)
+    best_of_printed_times(&output.stdout)
 }

 /// Measure WAFER execution time after CONSOLIDATE (direct calls between all words).
@@ -844,31 +862,70 @@ fn measure_wafer_consolidated(wafer: &str, bench: &PerfBenchmark) -> Option<u64>
    let code = format!(
        "{define} CONSOLIDATE {run} \
         : TIMED-BENCH UTIME {run} UTIME 2SWAP D- DROP . CR ; \
-         TIMED-BENCH TIMED-BENCH TIMED-BENCH",
+         {reps}",
        define = bench.define,
        run = bench.run_code,
+        reps = repeat_timed(" "),
    );
    let output = run_via_stdin(wafer, &code)?;
    if !output.status.success() {
        return None;
    }
-    median_printed_time(&output.stdout)
+    best_of_printed_times(&output.stdout)
 }

-/// Parse the microsecond values printed by TIMED-BENCH (one per line) and
-/// return the median.
-fn median_printed_time(stdout: &[u8]) -> Option<u64> {
+/// How many separate process invocations each measurement takes the best of.
+///
+/// `REPS`/`BEST_OF` deal with noise *inside* one process. They do not touch
+/// the rest: whether a process lands on a core whose SMT sibling is busy, and
+/// where its code ends up in memory, are fixed for its lifetime, and they make
+/// some benchmarks frankly bimodal -- Fibonacci after CONSOLIDATE measured
+/// 413-419 us in three runs of the report and 712-770 in the other two, with
+/// nothing in between. Only a fresh process resamples that.
+const PROCESS_RUNS: usize = 3;
+/// How many timed repetitions each engine runs per benchmark.
+const REPS: usize = 7;
+/// How many of the fastest repetitions the reported time averages over.
+const BEST_OF: usize = 3;
+
+/// Run `measure` in `PROCESS_RUNS` fresh processes and keep the fastest.
+///
+/// The minimum, not a mean: process-level noise is one-sided too, so the
+/// fastest process is the one that ran closest to undisturbed.
+fn best_of_processes(mut measure: impl FnMut() -> Option<u64>) -> Option<u64> {
+    (0..PROCESS_RUNS).filter_map(|_| measure()).min()
+}
+
+/// `TIMED-BENCH` repeated `REPS` times, separated by `sep`.
+///
+/// sf64 needs one statement per line (it truncates input at ~256 characters);
+/// the others do not care.
+fn repeat_timed(sep: &str) -> String {
+    ["TIMED-BENCH"; REPS].join(sep)
+}
+
+/// Parse the microsecond values printed by `TIMED-BENCH` and reduce them to
+/// one number: the mean of the fastest `BEST_OF`.
+///
+/// Not the median, and not the mean of all of them. Benchmark noise on a
+/// shared machine is one-sided -- a scheduling hiccup, an SMT sibling or a
+/// migration can only ever make a run slower, never faster -- so the fastest
+/// repetitions are the ones closest to the cost we are trying to measure.
+/// Averaging a few of them rather than taking the single minimum keeps one
+/// lucky run from setting the result on its own.
+fn best_of_printed_times(stdout: &[u8]) -> Option<u64> {
    let stdout = String::from_utf8_lossy(stdout);
    let mut times: Vec<u64> = stdout
        .trim()
        .lines()
        .filter_map(|l| l.trim().parse::<u64>().ok())
        .collect();
-    times.sort();
    if times.is_empty() {
        return None;
    }
-    Some(times[times.len() / 2])
+    times.sort_unstable();
+    let n = times.len().min(BEST_OF);
+    Some(times[..n].iter().sum::<u64>() / n as u64)
 }

 /// Measure gforth execution time using Forth-level `utime` (excludes startup).
@@ -876,19 +933,19 @@ fn median_printed_time(stdout: &[u8]) -> Option<u64> {
 /// Returns microseconds, or None if gforth is unavailable.
 fn measure_gforth(gforth: &str, bench: &PerfBenchmark) -> Option<u64> {
    // The timing wrapper must be inside a word (DO/LOOP is compile-only in gforth).
-    // We take the median of 3 runs.
    let code = format!(
        "{define} {run} \
         : TIMED-BENCH utime {run} utime 2swap d- drop . CR ; \
-         TIMED-BENCH TIMED-BENCH TIMED-BENCH bye",
+         {reps} bye",
        define = bench.define,
        run = bench.run_code,
+        reps = repeat_timed(" "),
    );
    let output = Command::new(gforth).arg("-e").arg(&code).output().ok()?;
    if !output.status.success() {
        return None;
    }
-    median_printed_time(&output.stdout)
+    best_of_printed_times(&output.stdout)
 }

 /// Measure `SwiftForth` (`sf64`) execution time using Forth-level `ucounter`
@@ -901,15 +958,16 @@ fn measure_sf64(sf64: &str, bench: &PerfBenchmark) -> Option<u64> {
    let code = format!(
        "{define}\n{run}\n\
         : TIMED-BENCH ucounter {run} ucounter 2swap d- drop . cr ;\n\
-         TIMED-BENCH\nTIMED-BENCH\nTIMED-BENCH\nbye\n",
+         {reps}\nbye\n",
        define = bench.define,
        run = bench.run_code,
+        reps = repeat_timed("\n"),
    );
    let output = run_via_stdin(sf64, &code)?;
    if !output.status.success() {
        return None;
    }
-    median_printed_time(&output.stdout)
+    best_of_printed_times(&output.stdout)
 }

 #[test]
@@ -982,14 +1040,14 @@ fn performance_report() {

    for bench in &benchmarks {
        let wafer = wafer_release
-            .and_then(|w| measure_wafer_release(w, bench))
+            .and_then(|w| best_of_processes(|| measure_wafer_release(w, bench)))
            .unwrap_or(0);
        let consol = wafer_release
-            .and_then(|w| measure_wafer_consolidated(w, bench))
+            .and_then(|w| best_of_processes(|| measure_wafer_consolidated(w, bench)))
            .unwrap_or(0);
-        let gf = gforth.and_then(|g| measure_gforth(g, bench));
-        let gf_fast = gforth_fast.and_then(|g| measure_gforth(g, bench));
-        let sf = sf64.and_then(|s| measure_sf64(s, bench));
+        let gf = gforth.and_then(|g| best_of_processes(|| measure_gforth(g, bench)));
+        let gf_fast = gforth_fast.and_then(|g| best_of_processes(|| measure_gforth(g, bench)));
+        let sf = sf64.and_then(|s| best_of_processes(|| measure_sf64(s, bench)));

        let gf_str = gf.map_or_else(|| "-".to_string(), |v| format!("{v}"));
        let gf_fast_str = gf_fast.map_or_else(|| "-".to_string(), |v| format!("{v}"));
@@ -344,3 +344,32 @@ fn compliance_tools() {
    let errors = run_suite(&mut vm, "toolstest.fth");
    assert_eq!(errors, 0, "Programming-Tools: {errors} test failures");
 }
+
+/// The Forth 2012 Core suite against consolidated code.
+///
+/// `CONSOLIDATE` recompiles the whole dictionary into one WASM module, which
+/// is where cross-word typed calls live: a word with a known stack effect
+/// gets a fast entry taking and returning its stack items as WASM values,
+/// and its `() -> ()` wrapper keeps the table slot. Nothing else covers that
+/// path for correctness, so run the suite on top of it.
+#[test]
+fn compliance_core_after_consolidate() {
+    let mut vm = ForthVM::<NativeRuntime>::new().expect("Failed to create ForthVM");
+    let tester_path = format!("{SUITE_DIR}/tester.fr");
+    let f1 = load_file(&mut vm, &tester_path);
+    assert_load_fails_within_baseline(&tester_path, f1);
+
+    vm.evaluate("CONSOLIDATE").expect("CONSOLIDATE failed");
+    vm.take_output();
+
+    let core_path = format!("{SUITE_DIR}/core.fr");
+    let f2 = load_file(&mut vm, &core_path);
+    assert_load_fails_within_baseline(&core_path, f2);
+
+    let _ = vm.evaluate("DECIMAL #ERRORS @");
+    let errors = vm.data_stack().first().copied().unwrap_or(-1);
+    assert_eq!(
+        errors, 0,
+        "Core word set after CONSOLIDATE: {errors} failures"
+    );
+}
@@ -12,7 +12,7 @@ workspace = true
 crate-type = ["cdylib", "rlib"]

 [dependencies]
-wafer-core = { path = "../core", version = "0.2.1", default-features = false, features = ["crypto"] }
+wafer-core = { path = "../core", version = "0.3.0", default-features = false, features = ["crypto"] }
 wasm-bindgen = "0.2"
 js-sys = "0.3"
 send_wrapper = { workspace = true }
@@ -38,6 +38,23 @@ impl WebHostAccess {
    }
 }

+/// An exception on its way back out of compiled code. Host words rethrow the
+/// Forth message (`Stack underflow`, an `ABORT"` text, a `THROW` description),
+/// so surface exactly that and nothing else — the JS `Error` carries the whole
+/// engine stack in its message, which is noise to a Forth programmer. Anything
+/// without a message is a genuine runtime fault and keeps the call context.
+fn call_error(fn_index: u32, e: &JsValue) -> anyhow::Error {
+    match Reflect::get(e, &"message".into())
+        .ok()
+        .and_then(|m| m.as_string())
+        .and_then(|m| m.lines().next().map(str::trim).map(str::to_string))
+        .filter(|m| !m.is_empty())
+    {
+        Some(msg) => anyhow::anyhow!("{msg}"),
+        None => anyhow::anyhow!("call_func({fn_index}) failed: {e:?}"),
+    }
+}
+
 impl HostAccess for WebHostAccess {
    fn mem_read_i32(&mut self, addr: u32) -> i32 {
        let view = js_sys::Int32Array::new(&self.buffer());
@@ -134,7 +151,7 @@ impl HostAccess for WebHostAccess {
            .dyn_into()
            .map_err(|_| anyhow::anyhow!("table entry {fn_index} is not a function"))?;
        func.call0(&JsValue::NULL)
-            .map_err(|e| anyhow::anyhow!("call_func({fn_index}) failed: {e:?}"))?;
+            .map_err(|e| call_error(fn_index, &e))?;
        Ok(())
    }
 }
@@ -406,7 +423,7 @@ impl Runtime for WebRuntime {
            .dyn_into()
            .map_err(|_| anyhow::anyhow!("table entry {fn_index} is not callable"))?;
        func.call0(&JsValue::NULL)
-            .map_err(|e| anyhow::anyhow!("call_func({fn_index}) failed: {e:?}"))?;
+            .map_err(|e| call_error(fn_index, &e))?;
        Ok(())
    }

@@ -18,11 +18,11 @@ confidence-threshold = 0.8
 [bans]
 multiple-versions = "deny"
 wildcards = "deny"
-# Transitive duplicates from wasmtime v31 -- will resolve when upgrading
+# Transitive duplicates from wasmtime v47 dependencies
 skip = [
    "getrandom",
+    "syn",
    "hashbrown",
-    "r-efi",
    "thiserror",
    "thiserror-impl",
    "wasm-encoder",
@@ -14,7 +14,7 @@ This document describes every optimization that makes sense for WAFER, why it ma

 | #  | Optimization               | Level        | Status      | Impact  |
 | -- | -------------------------- | ------------ | ----------- | ------- |
-| 1  | Stack-to-Local Promotion   | Codegen      | Phase 2     | Highest |
+| 1  | Stack-to-Local Promotion   | Codegen      | Phase 4     | Highest |
 | 2  | Peephole Optimization      | IR pass      | Done        | High    |
 | 3  | Constant Folding           | IR pass      | Done        | High    |
 | 4  | Inlining                   | IR pass      | Done        | High    |
@@ -29,12 +29,19 @@ This document describes every optimization that makes sense for WAFER, why it ma
 | 13 | Startup Batching           | Architecture | Done        | Low     |
 | 14 | Self-Recursive Direct Call | Codegen      | Done        | High    |
 | 15 | Float / Double-Cell        | Codegen      | Not started | Future  |
+| 16 | Typed Calling Convention   | Codegen      | Done        | Highest |
+| 17 | Self-Guard Expansion       | IR pass      | Done        | Medium  |

 ## 1. Stack-to-Local Promotion

-**Status: Phase 2 done.** Words with straight-line code, DO/LOOP, and IF/ELSE use WASM locals instead of memory stack. Stack manipulation ops (Swap, Rot, Nip, Tuck, Dup, Drop) emit zero WASM instructions. Loop index/limit kept in WASM locals (zero return stack traffic). Switchable via `WaferConfig::codegen.stack_to_local_promotion`.
+**Status: Phase 4 done.** Straight-line code, DO/LOOP, IF/ELSE and the BEGIN loop family use WASM locals instead of the memory stack, per region rather than per word. Stack manipulation ops (Swap, Rot, Nip, Tuck, Dup, Drop) emit zero WASM instructions. Loop index/limit stay in WASM locals (zero return stack traffic). Switchable via `WaferConfig::codegen.stack_to_local_promotion`.

-Phase 1 covered straight-line code only. Phase 2 extends to DO/LOOP (with stack-neutrality check) and IF/ELSE/THEN (with equal-branch-effect check). BEGIN loops and BeginDoubleWhileRepeat are not yet promoted.
+- **Phase 1** — straight-line code.
+- **Phase 2** — DO/LOOP (stack-neutrality check) and IF/ELSE/THEN (equal-branch-effect check).
+- **Phase 3** — _per region instead of per word_. Promotion used to be all-or-nothing: one `.`, `CR`, `>R` or host call anywhere in a definition put the entire body on the memory stack, hot loops included, which costs 2.2 ns per loop-carried add instead of 0.31 — the accumulator round-trips through store-to-load forwarding rather than staying in a register. `emit_body` now partitions a body into maximal promotable stretches and runs the simulator over each, loading what a region reads and writing back what it leaves. A region may only use `I` / `J` when the DO loops naming them are inside it, and a straight-line region needs at least three operations to pay for its prologue and epilogue; a loop always does.
+- **Phase 4** — `BEGIN..UNTIL`, `BEGIN..AGAIN` and `BEGIN..WHILE..REPEAT`, when the construct is provably stack-neutral: UNTIL's body nets +1 (the flag it consumes), AGAIN's nets 0, and for WHILE..REPEAT the test and the body must balance _separately_, because WHILE leaves the loop between them and a net that only added up over the pair would give the two exits different stack shapes. Bodies containing an `EXIT` stay out, the same rule DO/LOOP follows.
+
+Still not promoted: `BeginDoubleWhileRepeat`, `>R`/`R>`, floats, `{: :}` locals, `SP@`/`DEPTH`/`EXECUTE`, and the flat forward-block IR ops.

 ### The Problem

@@ -301,6 +308,28 @@ After interactive development, `CONSOLIDATE` recompiles all defined words into a
 | JIT (current) | Interactive development | Per-word modules, `call_indirect`, fast redefine |
 | Consolidated  | After `CONSOLIDATE`     | Single module, direct `call`, no redefine        |

+### Why the CONSOL column can lose to the JIT column
+
+`NestedLoops` runs 1.1x slower after `CONSOLIDATE` on the M1 and 1.7x slower on a Skylake Xeon,
+with **byte-identical WASM** for the hot word in both modes (verified via `WAFER_DUMP_WASM` +
+`wasm-tools print`) and instruction-identical machine code modulo register names (verified via
+`Engine::precompile_module` + objdump). The whole delta is code placement:
+
+- A tight loop pays for straddling an instruction-fetch window: ~9% for a 16-byte window on the
+  M1, up to ~65% on Skylake when the fused `cmp+jcc` crosses a 32-byte boundary and the loop
+  falls out of the uop cache every iteration (the JCC erratum, post-microcode).
+- Cranelift never aligns loop headers (`align_basic_block` is an identity default, no ISA
+  overrides it), so where a loop lands is whatever the code before it leaves behind.
+- The per-word JIT module keeps a dead dsp load in its prologue (the store-back is DCE'd, the
+  load survives), which happens to shift its loops onto luckier offsets than the consolidated
+  module's cleaner function bodies. A padding experiment that moves the same loop across offsets
+  reproduces the full penalty range on both hosts, including placements where the consolidated
+  code **beats** the JIT code.
+
+So the column difference on loop-only benchmarks is an alignment lottery, not an emitter defect;
+divider-bound benchmarks (`GCD`) mask it entirely. Fixing it for real means loop-header alignment
+upstream in Cranelift.
+
 ## 9. Compound IR Operations

 **Status: Done.** `TwoDup` and `TwoDrop` IrOp variants with optimized codegen. Peephole converts `Over, Over -> TwoDup` and `Drop, Drop -> TwoDrop`.
@@ -452,33 +481,97 @@ Fibonacci(25) with ~243K recursive calls:

 The optimization is implemented in `emit_op` for `IrOp::Call`: when `ctx.self_word_id == Some(word_id)`, emit `call WORD_FUNC` (function index 1 in the word's own module). The `self_word_id` is derived from `CodegenConfig::base_fn_index`.

+The numbers above are the state before section 16: they measure the call instruction, and what dominated turned out to be the calling _convention_ around it. A self-recursive word that is also typed now calls its own fast entry instead, and Fibonacci(25) is 356 microseconds rather than 1.6 ms.
+
 ## 15. Float and Double-Cell Stack

 **Status: Not started.** `PushI64` and `PushF64` exist as IR ops but are stubs in codegen. Float stack operations are currently all host functions.

 The float stack lives in its own memory region (0x2540--0x2D40). Float operations will have the same memory-based overhead as integer operations, but worse: `f64` values are 8 bytes, doubling the memory traffic per push/pop. Stack-to-local promotion (section 1) is even more impactful for floats because WASM has native `f64` locals and operand stack support.

+## 16. Typed Calling Convention
+
+**Status: Done.** A word that calls itself and whose stack effect is statically known compiles to two entry points: a fast one with signature `(i32 x p) -> (i32 x q)`, carrying its stack items as WASM values, and the usual `( -- )` wrapper that moves those items on and off the memory data stack. The wrapper keeps the function-table slot, so `EXECUTE`, the outer interpreter, host words and `CATCH` see exactly the ABI they saw before; only direct calls inside a module take the fast entry. `WAFER_TYPED_CALLS=0` falls back. The self-recursion condition matters: the table slot holds the wrapper, so in the JIT path nothing but `RECURSE` can reach the fast entry, and emitting it for any other word just puts a wrapper hop in front of every call through the table -- measured at +47% before that was fixed in 0.2.9.
+
+### The Problem
+
+This is what the SwiftForth gap was made of. sf64 keeps TOS in `RBX` and the stack pointer in `RBP`, and both survive a `CALL` untouched, so its `FIB` is 16 instructions and about 7 memory touches per node. WAFER kept the whole stack in linear memory and flushed its cached `$dsp` to an imported global before every call: about 36 touches. Section 1's simulator, which already promoted loop and `IF` bodies into locals, refused any body containing a call or an `EXIT` -- exactly the words where the convention cost the most.
+
+### The Effect Fixpoint
+
+Self-recursion makes the stack-effect equation circular (`d = k + m*d`), so the effect is solved by iterating a guess until it reproduces itself: `FIB` settles on `(1,1)` in two rounds, while `: F 1 RECURSE ;` never settles and stays untyped. `CONSOLIDATE` extends this across words, since it puts them all in one module: the effects are solved from the leaves outward, and 105 of 187 words in a booted dictionary end up typed.
+
+### Impact
+
+Fibonacci(25) went from 1035 to 366 microseconds, 4.3x slower than `sf64` to 1.2x. Stack guards became nearly free as a side effect -- they hang off the memory-stack push/pop choke points, and a typed word barely has any -- so the default guards-on configuration that the REPL and the web build use went from 1631 to 365 microseconds on the same benchmark.
+
+Untyped by design: anything using `SP@`, `DEPTH`, `EXECUTE`, `>R`/`R>`, floats or locals; anything calling a word that is itself untyped, which in the JIT path means every call except `RECURSE`; mutually recursive words; and words whose effect is not static -- branches that disagree on depth, `EXIT` at the wrong depth, a non-neutral loop body, or a recursion that grows the stack per level.
+
+## 17. Self-Guard Expansion
+
+**Status: Done.** A recursive word's base-case guard is duplicated into its own call sites, so the leaves of the recursion cost a test instead of a call. Implemented in `optimizer.rs::expand_self_guard`, gated on `OptConfig::self_guard`, and applied after inlining so the later passes still run over the result.
+
+### The Shape
+
+A recursive Forth word almost always opens with a guard that returns early:
+
+```forth
+: FIB DUP 2 < IF EXIT THEN DUP 1- RECURSE SWAP 2 - RECURSE + ;
+```
+
+Every leaf of the recursion is then a call whose entire body is `DUP 2 <`. The pass rewrites each `Call(self)` as
+
+```forth
+DUP 2 < IF ( leave it ) ELSE RECURSE THEN
+```
+
+which computes the same thing -- the callee would have run the guard, taken the branch and returned. When the guard returns a value rather than its argument (`IF DROP 0 EXIT THEN`), that value moves into the then-branch with it.
+
+### Why It Is Bounded
+
+The guard runs twice along the recursive path: once at the call site, once inside the callee. So it must be small and free of effects -- `MAX_GUARD_OPS` is six, and the operations are restricted to stack shuffles, arithmetic and comparisons; a call, a memory access or a branch disqualifies it. `MAX_GUARD_SITES` caps the expansion at four call sites, since each one replicates the guard. A `TailCall` is never expanded, which keeps this pass and tail-call detection from having to agree about what tail position means.
+
+### Impact
+
+Fibonacci(25): 356 to 237 microseconds on the arm64 development machine. In fib's tree half of all nodes are leaves, which is where the factor comes from. It does not take Fibonacci past `sf64`, though the arm64 table below says otherwise: with both engines native on x86-64, Fibonacci reads 1.16x and stays the one benchmark `sf64` wins.
+
 ## Current Performance vs Gforth

 All optimizations enabled, release mode, measured with UTIME:

+Development machine (M1 Ultra, arm64), median of three reports, every
+benchmark sized to about 10 ms:
+
 ```
-Benchmark                   WAFER     CONSOL     gforth      WAFER/gf
-Fibonacci(25)                1629       1535       3422        0.45x
-Factorial(12)x10K             340        339        638        0.53x
-GCD-bench(500)                 18         15         30        0.50x
-NestedLoops(50)                84         73        720        0.10x
-Collatz(2K)                  1212       1202       3914        0.31x
+Benchmark                   WAFER     CONSOL     gforth       sf64    WAFER/gf   WAFER/sf
+Fibonacci(33)               11307      11407     157001      13053       0.07x      0.87x
+Factorial(12)x2M             9639       9599     123950      32091       0.08x      0.30x
+GCD-bench(400K)             11662      11580      38580      17001       0.30x      0.68x
+NestedLoops(50)x20K          8920       9852     140518      36828       0.06x      0.24x
+CrossCalls(3M)              10883       3769      87691       8240       0.04x      0.46x
+Collatz(2K)x50               8838       8715     189903      28657       0.05x      0.30x
 ```

-Times in microseconds. WAFER/gf < 1.0 means WAFER is faster.
+Times in microseconds; ratios take the better of WAFER and CONSOL. The `sf64`
+column flatters WAFER: the only SwiftForth build for macOS is x86-64 under
+Rosetta 2 while WAFER and gforth are native arm64. Measured with all three
+native on x86-64, Fibonacci reads 1.23x rather than 0.87x -- the emulation
+penalty lands hardest on the call-heavy benchmark -- while the other five keep
+their ratios. One caveat holds on both: sf64 uses 64-bit cells to WAFER's
+32-bit. (The native table is being re-taken at these workload sizes.)
+
+`CrossCalls` is the only benchmark with a cross-word call left in its hot loop,
+so it is the only one that measures section 8 at all -- the other five have
+their callee inlined away or are self-recursive. Note that `CONSOLIDATE` makes
+NestedLoops and Collatz _slower_; see the open item below.

 ## Remaining Opportunities

-| Optimization                     | Status              | Potential Impact                                      |
-| -------------------------------- | ------------------- | ----------------------------------------------------- |
-| BEGIN loop promotion             | Not started         | Would speed up GCD-style tight loops further          |
-| BeginDoubleWhileRepeat promotion | Not started         | Rare pattern, low priority                            |
-| LEAVE as IR primitive            | Not started         | Would enable fast-path for loops with LEAVE           |
-| Float stack-to-local             | Not started         | Eliminate float stack memory traffic                  |
-| WASM tail calls proposal         | Waiting on wasmtime | Would eliminate stack growth for tail-recursive words |
+| Optimization                      | Status              | Potential Impact                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| --------------------------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Explain CONSOLIDATE on pure loops | Open defect         | Isolated on an idle box: NestedLoops 540 -> 905 us (1.68x) and Collatz 310 -> 360 (1.16x) on x86-64, against 1.07x and 1.05x for the same probes on arm64 -- so the magnitude is strongly architecture-dependent, which points at code size or branch density rather than a gross codegen error. Not the promotion logic (same code path), not inlining (no call left), not the harness (CONSOLIDATE is outside the timed window). Next step is to diff the emitted wat for NESTED-BENCH between the two paths |
+| Scoped exit for the inliner       | Not started         | The inliner still refuses any body containing an `EXIT`, because an inlined one would return from the caller. Compiling it as a branch to the end of a block would unlock inlining for every word with an early return, not just the guard shape section 17 handles                                                                                                                                                                                                                                            |
+| BeginDoubleWhileRepeat promotion  | Not started         | Rare pattern, low priority. Its promoted emitter exists but has no loop fixup and is unverified                                                                                                                                                                                                                                                                                                                                                                                                                |
+| LEAVE as IR primitive             | Not started         | Would enable fast-path for loops with LEAVE                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| Float stack-to-local              | Not started         | Eliminate float stack memory traffic                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| WASM tail calls proposal          | Waiting on wasmtime | Would eliminate stack growth for tail-recursive words                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
@@ -282,11 +282,13 @@ When the compiler encounters a word reference during compilation, it emits:
 (call_indirect (type $void) (table 0))    ;; indirect call through the table
 ```

-**Self-recursive optimization**: When a word calls itself (RECURSE), the codegen detects this and emits a direct `call` instead of `call_indirect`, eliminating the table lookup and signature check (~3x faster for recursive words like Fibonacci).
+**Self-recursive optimization**: When a word calls itself (RECURSE), the codegen detects this and emits a direct `call` instead of `call_indirect`, eliminating the table lookup and signature check (~3x faster for recursive words like Fibonacci). When the word is also typed, that direct call goes to its fast entry -- see below.

 **After CONSOLIDATE**: All `call_indirect` between words in the consolidated module are replaced with direct `call` instructions, giving similar benefits for cross-word calls.

-At runtime, wasmtime resolves the table entry and calls the target function. Because all functions share the same memory, globals, and table, state passes between words through the data stack in linear memory. There are no function parameters or return values at the WASM level -- everything goes through the stack.
+At runtime, wasmtime resolves the table entry and calls the target function. Because all functions share the same memory, globals, and table, state passes between words through the data stack in linear memory.
+
+**Typed entry points**: that last sentence is the default, not the whole story. A word whose stack effect is statically known also gets a _fast_ entry with signature `(i32 x p) -> (i32 x q)`, which takes its arguments as WASM values and returns its results the same way, so they stay in registers across the call instead of round-tripping through linear memory. The `( -- )` function above is then a wrapper around it, and it is the wrapper that keeps the table slot -- so `EXECUTE`, the outer interpreter, host words and `CATCH` see the memory ABI unchanged. Only a direct call inside the same module takes the fast entry: `RECURSE` in the JIT path, and every resolvable call after `CONSOLIDATE`. See [OPTIMIZATIONS.md](OPTIMIZATIONS.md) section 16.

 This is subroutine threading: each word is a subroutine, and calling a word is an indirect function call.
Author	SHA1	Message	Date
Oleksandr Kozachuk	b4a28f342d	chore: main is 0.3.0-to-be CI / check (push) Has been cancelled Details	2026-08-12 11:02:13 +02:00
Oleksandr Kozachuk	0a0f1e9e95	feat(core): >ORDER, -ORDER, VOCABULARY search-order extensions	2026-08-12 11:01:49 +02:00
Oleksandr Kozachuk	94a0566ce3	release: 0.2.9 CI / check (push) Has been cancelled Details	2026-08-11 17:24:04 +02:00
Oleksandr Kozachuk	35da69cf7b	bench: CrossCalls lane, best-of sampling, 10ms sizes	2026-08-11 17:23:52 +02:00
Oleksandr Kozachuk	392f2d0136	fix(core): inline loop-free callees first so the loop guard can fire The guard ran before inlining and only ever saw calls.	2026-08-11 17:23:38 +02:00
Oleksandr Kozachuk	b1cc93edc6	fix(core): typed entry only for a self-recursive word Non-recursive words paid an extra wrapper hop. Adds the WAFER_DUMP_WASM dump hook.	2026-08-11 17:23:25 +02:00
Oleksandr Kozachuk	4f96f8860a	release: 0.2.8 CI / check (push) Has been cancelled Details Ships the self-guard expansion, and corrects what the benchmark tables claim. Measured with wafer, gforth and SwiftForth all native on x86-64 -- the macOS sf64 build runs under Rosetta 2 and flatters us -- Fibonacci is 1.16x rather than 0.83x, so sf64 still wins it and wafer takes the other four. README and OPTIMIZATIONS now carry both tables.	2026-08-10 12:48:33 +02:00
Oleksandr Kozachuk	e963e636d3	perf(core): test a recursive word's base case at the call site CI / check (push) Has been cancelled Details A recursive Forth word almost always opens with a guard that returns early, so every leaf of the recursion costs a call whose whole body is that test. `Call(self)` now compiles as `<guard> IF <what the guard returns> ELSE Call(self) THEN`, which is what the callee would have done on entry anyway. Half of fib's nodes are leaves: Fibonacci(25) 356 -> 237 us, 1.24x sf64 -> 0.83x, so all five benchmarks now beat it. The guard runs twice along the recursive path, hence the bounds: at most six effect-free operations, at most four call sites, never a tail call. WS-018.	2026-08-09 18:27:25 +02:00
Oleksandr Kozachuk	645c2dadd7	Merge pull request from ok2/perf/typed-calls CI / check (push) Has been cancelled Details 0.2.7: typed calling convention, per-region and BEGIN loop promotion, and a fix for a promoted loop/IF that reordered the stack.	2026-08-09 17:53:00 +02:00
Oleksandr Kozachuk	3bb613ece0	release: 0.2.7 Version bump plus a doc sweep: the benchmark tables in README and docs/OPTIMIZATIONS.md were still from before the typed calling convention, OPTIMIZATIONS listed BEGIN loop promotion as not started, and the subroutine-threading section of docs/WAFER.md described the memory ABI as the only one.	2026-08-09 17:36:52 +02:00
Oleksandr Kozachuk	b8dcc021a2	perf(core): promote per region, promote BEGIN loops, keep loops off the memory stack Promotion was all-or-nothing per word, so one `.` or one host call put the whole body -- hot loops included -- on the memory data stack, where a loop-carried add costs 2.2 ns/iteration instead of 0.31. The stack simulator now runs over each promotable stretch of a word; BEGIN/UNTIL, BEGIN/AGAIN and BEGIN/WHILE/REPEAT join DO/LOOP as promotable when the construct is provably stack-neutral; and the inliner no longer moves a loop-bearing callee into a caller that can never be promoted. Fixes a bug the BEGIN work uncovered, present since promotion was introduced and shipped in 0.2.6: the loop fixup and the IF join copied locals one slot at a time in index order, so a body that permutes the stack lost a value -- `: C 3 4 2 0 DO SWAP LOOP . . ;` printed `4 4` where gforth prints `4 3`. Four of five benchmarks now beat sf64: Factorial 0.29x, Collatz 0.30x, NestedLoops 0.27x, GCD 0.67x. Only Fibonacci is behind, at 1.24x. Also scale GCD, Factorial and NestedLoops, which ran in 14-51 us where scatter and fixed costs dominated -- that is what exposed GCD as a loss and pointed at BEGIN. WS-014, WS-015, WS-016, WS-019.	2026-08-09 17:25:21 +02:00
Oleksandr Kozachuk	fc34bd9b24	perf(core): typed calling convention for words with a known stack effect Such a word now compiles to a fast entry (i32 x p) -> (i32 x q) carrying its stack items as WASM values, plus the usual ( -- ) wrapper that keeps the table slot, so EXECUTE / interpreter / host words / CATCH see the unchanged memory ABI. Fib(25) 1035 -> 366 us, 4.3x slower than sf64 -> 1.2x; the default guards-on config 1740 -> 361 us. WS-006.	2026-08-09 09:20:10 +02:00
Oleksandr Kozachuk	e6c10a6fa1	Merge pull request #6 from ok2/fix/abort-reporting CI / check (push) Has been cancelled Details fix(core): silent ABORT, and name the compile-only condition	2026-08-07 13:11:50 +02:00
Oleksandr Kozachuk	e110ca9516	fix(core): silent ABORT, and name the compile-only condition Two reporting bugs found from the browser shell. An uncaught ABORT printed 'ABORT (throw -1)'. The standard defines ABORT as 'empty the data stack and perform the function of QUIT', and QUIT displays no message; gforth and SwiftForth are both silent. It now takes the same silent path QUIT got in 0.2.5. CATCH still reports -1 and still restores the stack depth, and ABORT" still prints its text -- different word, different code (-2). Compile-only constructs used in interpretation state claimed to be an 'unknown word', which is misleading for a word the system obviously knows: ABORT", IF, THEN, LOOP, LITERAL, RECURSE and friends. They now report 'interpreting a compile-only word: <name> (throw -14)', the standard condition both reference engines give. The check reuses the existing INTERPRETER_TOKENS table at the point where interpretation has already failed, so a genuine typo still reports 'unknown word'. Ships as v0.2.6.	2026-08-07 13:10:42 +02:00
Oleksandr Kozachuk	8e2fd0d7d4	Merge pull request #5 from ok2/feature/quit CI / check (push) Has been cancelled Details feat(core): QUIT	2026-08-07 12:34:05 +02:00
Oleksandr Kozachuk	69309006a2	feat(core): QUIT The CORE word was missing. QUIT empties the return stack, enters interpretation state, restores SOURCE-ID to the user input device and returns to the interpreter without a message, leaving the data stack untouched -- that last part is the whole difference to ABORT, which the standard defines as 'empty the data stack, then QUIT'. Implemented on the throw plumbing with the standard code -56, so nested EVALUATE / INCLUDE frames unwind and are abandoned on the way out. Two places treat -56 specially: CATCH lets it through (QUIT is a return to the prompt, not an exception) and evaluate() turns it into a silent Ok after the compile-state wipe it already performs. Semantics checked against gforth 0.7.3 and SwiftForth sf64, which agree: the data stack survives, nothing is printed, the rest of the input is abandoned, and '1 2 ' QUIT CATCH .' prints nothing while leaving 1 2. Six tests in outer.rs pin it. Deliberately NOT added to the cross-engine corpus: what QUIT abandons is the input source, and the three engines are fed differently there, so a comparison would measure the harness. The gap survived because the Forth 2012 suite skips QUIT by its own admission, and HELP's coverage lint compares dictionary against docs -- a word missing from both looks complete. docs/wafer-anki.txt had been documenting QUIT as if it existed. ABORT itself was already correct: executed while a definition is open it clears both stacks and returns to interpretation state. Ships as v0.2.5.	2026-08-07 12:28:11 +02:00
Oleksandr Kozachuk	9b10723a95	Merge pull request #4 from ok2/fix/web-error-messages CI / check (push) Has been cancelled Details fix(web): surface Forth messages from host-word throws	2026-08-06 20:46:11 +02:00
Oleksandr Kozachuk	15f8005b6d	Merge pull request #3 from ok2/fix/release-strip-breaks-proc-macros fix(build): exempt build scripts and proc-macros from release strip	2026-08-06 20:46:08 +02:00
Oleksandr Kozachuk	4769987b20	fix(web): surface Forth messages from host-word throws A host word signals failure by throwing across the JS boundary, and the browser runtime reported that exception with its Debug form, so an empty-stack RESIZE surfaced as call_func(134) failed: JsValue(Error: Stack underflow ...) with the engine's JS stack trace glued on. The thrown message IS the Forth message, so take it verbatim: 'Stack underflow', the same text the native CLI prints. Exceptions without a message keep the call context -- those are genuine runtime faults, not Forth throws. CATCH is unaffected: it reads the throw code from its own channel rather than parsing messages. Verified against a fresh VM in Node (initSync + WaferRepl): host-word underflow, compiled-guard underflow, THROW, unknown word and ' RESIZE CATCH . all match the native CLI. Ships as v0.2.4.	2026-08-06 20:45:27 +02:00
Oleksandr Kozachuk	d55a27873e	fix(build): exempt build scripts and proc-macros from release strip `wasm-pack build --release` died with "can't find crate" for rustversion, then thiserror_impl, then every other proc-macro. Cargo strips debuginfo from release artifacts by default and on macOS that takes the metadata proc-macro dylibs need to be loadable with it, so rustc could no longer open them. Debug builds are unstripped, which is why the whole test suite stayed green while the browser REPL could not be built for production at all. Stripping buys nothing for build scripts and proc-macros, so [profile.release.build-override] exempts them; release binaries stay stripped. Also pins wafer-core to 0.2.3 in wafer-web and wafer-cli — both still asked for 0.2.1. The caret requirement resolved, so nothing broke.	2026-08-06 20:16:41 +02:00
Oleksandr Kozachuk	645b00d6e8	Merge pull request #2 from ok2/feature/swiftforth-number-conversion feat(core): SwiftForth input number conversion, DPL and NH	2026-08-06 19:57:04 +02:00
Oleksandr Kozachuk	9efb92ddc8	docs(core): correct sign handling note in number conversion docs The doc comments still claimed a leading + binds as a sign. It does not: sf64 converts +7 as the double 7 with DPL 1, and the code follows that. Only a leading - is a sign.	2026-08-06 19:25:48 +02:00
Oleksandr Kozachuk	706c73ce2a	feat(core): SwiftForth input number conversion, DPL and NH Punctuation (`,` `.` `+` `/` `:` and an embedded `-`) after the leftmost digit now forces double-cell conversion, so `12.34`, `1,234`, `12:30:45` and `2026-08-06` convert as doubles. Only a trailing `.` worked before, and `1.5` was an "unknown word" error. The punctuation is a double-cell marker, not a fractional point, so the scale has to travel separately: DPL carries the digit count right of the rightmost punctuation character (negative when there was none), which is what lets `<# #>` place the point back on output. NH carries the high cell a single-cell conversion drops, so a token that overflows a cell is still recoverable as a double. parse_number and parse_double_number duplicated the prefix and sign handling and could not share a DPL counter, so they collapse into one parse_numeric_literal that reports which kind it converted. Verified token-for-token against sf64. One deliberate divergence: WAFER keeps accepting a sign before a base prefix (`-$FF`), which sf64 rejects.	2026-08-06 19:19:41 +02:00
Oleksandr Kozachuk	a89d7ca704	chore(ci): dprint-format changelog; dedupe sha crates; deny skips for wasmtime 47 CI / check (push) Has been cancelled Details	2026-08-06 16:15:02 +02:00