chore(tools): sync bat syntax with current word set

Alternations diffed against live WORDS output (304 words) plus outer-interpreter tokens. Adds float transcendentals, double-cell ops, pictured numeric, conditional compilation, string ops, SEE/SEE-IR/DUMP/BYE/HELP, RP@/RDEPTH/.RS, REMEMBER/EMPTY/GILD, DECIMAL/HEX, INCLUDE/INCLUDED, WITHIN, DEFER!/DEFER@, C,.
build: add just install recipe
2026-08-06 12:23:20 +02:00 · 2026-08-06 12:23:02 +02:00 · 2026-08-06 12:03:29 +02:00 · 2026-08-06 11:18:03 +02:00
25 changed files with 1231 additions and 2902 deletions
@@ -3,6 +3,3 @@
 *.swp
 .DS_Store
 *.bk
 # Local planning notes — never tracked
 /plans/
@@ -1,346 +0,0 @@
 # Changelog
 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).
 ## [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
 - **The search order is now authoritative** (Forth 2012 §16.3.3): a word
  whose wordlist is not in the search order is no longer findable.
  Previously lookup fell back to the newest entry across all wordlists,
  making word hiding impossible. Verified against gforth and SwiftForth,
  and guarded by a cross-engine corpus program.
 - **Host words validate their stack arguments.** Around 40 host-implemented
  words (`RND-SEED`, `ACCEPT`, `RESIZE`, `ALLOCATE`, `FREE`, `SEARCH`,
  `SUBSTITUTE`, `ROLL`, `M*`, `UM/MOD`, `SF@ SF! DF@ DF!`, `F. FE. FS. F~`,
  `2R@`, and friends) performed raw stack-pointer arithmetic with no
  underflow check — calling them on an empty stack silently corrupted the
  stack pointer (the compiled-code guards from 0.2.0 do not cover host
  words). All argument-taking host words now fail with a clean, CATCHable
  underflow error, enforced by a class-wide regression test.
 ## [0.2.0] - 2026-08-06
 The usability release: introspection, source files, honest errors, and a
 safety net under every compiled word.
 ### Added
 - **Stack guards in compiled code**: under/overflow checks at the
  stack-pointer choke points of generated WASM. Faults THROW standard codes
  (`-3`..`-6`, `-44`, `-45`), are CATCHable, and print standard messages
  instead of silently corrupting memory. Default on; `wafer build` output
  stays unguarded; `WAFER_STACK_GUARDS=0|1` overrides.
 - **`SEE`**: source-level decompiler. Colon words (including everything in
  `boot.fth`) show their captured verbatim source; data words show
  synthesized definitions with current values (`9 VALUE X`,
  `DEFER D ( IS DUP )`); primitives fall back to a readable IR dump —
  `SEE` never dead-ends on a defined word.
 - **`SEE-IR`**: post-optimization IR view with resolved callee names and
  indented control flow — shows what the optimizer actually did.
 - **`HELP`**: stack effect + one-line description for **every** word in a
  fresh VM (dictionary words and outer-interpreter tokens alike); coverage
  is enforced by a unit test, so an undocumented new word fails the build.
  User words echo their leading `( n -- n )` comment.
 - **`INCLUDE` / `INCLUDED`**: nestable source-file loading with cycle
  detection, depth bound, paths relative to the including file, and
  per-level `SOURCE-ID`. The loader is injected (CLI: filesystem; web:
  defined error), so the core stays IO-free. `wafer prog.fth` now runs
  through the same machinery.
 - **`MARKER` extensions**: `REMEMBER` (re-runnable marker), `EMPTY` and
  `GILD` (boot-state rollback and re-baselining). Marker rollback now also
  restores search order, wordlists, `REPLACES` substitutions, `ABORT"`
  texts, and captured word sources — enabling the `REMEMBER` + `INCLUDE`
  edit-reload loop.
 - **`WORDS`**: optional substring filter (`WORDS FLOAT`), word count, and
  `WORDS ALL` — a grouped full view by wordlist plus internal words.
 - **Return-stack introspection**: `.RS`, `RDEPTH`, `RP@`.
 - **Tools**: `.S` honors `BASE`, `F.S`, `?`, bounds-checked `DUMP`, real
  `BYE`, named `ORDER` output.
 - **CLI REPL**: persistent history (XDG state dir, `0600`), dictionary-backed
  tab completion, prefix history search on Up/Down, Ctrl-C clears the line.
 - **Web REPL**: history persisted to localStorage, User Words palette,
  `BASE` indicator in the stack bar.
 - **Error reporting**: uncaught `THROW` codes map to standard messages;
  `ABORT"` text prints only when uncaught; errors inside included files
  carry `file.fth:line:` context; uncaught throws are typed
  (`WaferError::UncaughtThrow`) for embedding consumers; compiled words
  carry WASM name sections, so genuine traps name the faulting word
  (`in CRASHER: wasm trap: out of bounds memory access`).
 - **SwiftForth correctness lane**: the cross-engine program corpus can run
  against sf64 as an oracle (`just compare-correctness`), alongside the
  existing gforth lane and the sf64 performance lane.
 ### Fixed
 - Multi-line command output in the CLI REPL starts on its own line
  (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).
 - `SPACES` with a negative count now outputs nothing, per Forth 2012
  6.1.2230.
 ### Changed
 - `wafer prog.fth` reports errors with `file:line` context and resolves
  nested `INCLUDE`s relative to the file.
 - Internal words (`_`-prefixed) are flagged in the dictionary and hidden
  from `WORDS` and completion (`WORDS ALL` shows them).
 - Dependencies upgraded across the board: wasmtime 43 → 47,
  wasm-encoder/wasmparser 0.246 → 0.255, plus all semver-compatible
  updates.
 ## [0.1.0] - 2026-08-04
 Initial development line (untagged): Forth 2012 core with IR optimizer and
 WASM codegen via wasm-encoder/wasmtime, ~300 words across Core, Double,
 Float, String, Search-Order, Exception, and Tools word sets, Forth 2012
 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.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, 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, consolidation). Beats gforth on all benchmarks in release mode, and SwiftForth `sf64` on four of five. 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, 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.
 ## 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 601 unit + 1 benchmark + 12 compliance + 9 comparison + 5 crypto)
+- Run `cargo test --workspace` before committing (currently 542 unit + 1 benchmark + 11 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`
@@ -3,7 +3,7 @@ members = ["crates/*"]
 resolver = "2"
 [workspace.package]
-version = "0.2.7"
+version = "0.1.0"
 edition = "2024"
 license = "MIT OR Apache-2.0"
 repository = "https://github.com/ok2/wafer"
@@ -41,21 +41,13 @@ needless_collect = "warn"
 or_fun_call = "warn"
 [workspace.dependencies]
-wasm-encoder = "0.255"
+wasm-encoder = "0.246"
-wasmparser = "0.255"
+wasmparser = "0.246"
-wasmtime = "47"
+wasmtime = "43"
 anyhow = "1"
 thiserror = "2"
 proptest = "1"
 insta = "1"
-sha1 = "0.10"
+sha1 = "0.11"
-sha2 = "0.10"
+sha2 = "0.11"
 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,11 +7,10 @@ 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 (per region, so a hot loop keeps its registers even inside a word that does I/O; `DO` and `BEGIN` loops alike) + consolidation
+- **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)
 - **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
@@ -80,36 +79,23 @@ git submodule update --init
 ## Performance
-WAFER beats gforth (the GNU Forth reference implementation) on all benchmarks in release mode, and is within
+WAFER beats gforth (the GNU Forth reference implementation) on all benchmarks in release mode:
 reach of SwiftForth `sf64`, which compiles to native code:
 ```
-Benchmark                   WAFER     CONSOL     gforth       sf64    WAFER/gf   WAFER/sf
+Benchmark                   WAFER     CONSOL     gforth      WAFER/gf
-Fibonacci(25)                 356        361       3389        287       0.11x      1.24x
+Fibonacci(25)                1629       1535       3422        0.45x
-Factorial(12)x100K            479        495       6249       1650       0.08x      0.29x
+Factorial(12)x10K             340        339        638        0.53x
-GCD-bench(20K)                540        559       1801        801       0.30x      0.67x
+GCD-bench(500)                 18         15         30        0.50x
-NestedLoops(50)x1K            509        501       7023       1887       0.07x      0.27x
+NestedLoops(50)                84         73        720        0.10x
-Collatz(2K)                   185        213       3873        610       0.05x      0.30x
+Collatz(2K)                  1212       1202       3914        0.31x
 ```
 Times in microseconds. WAFER/gf < 1.0 means WAFER is faster. CONSOL = after `CONSOLIDATE`.
 Two caveats on the `sf64` column. The SwiftForth build here is x86-64 running under Rosetta 2
 while WAFER and gforth are native arm64, so it is a native-vs-emulated comparison; and sf64
 uses 64-bit cells to WAFER's 32-bit. WAFER is ahead on the four loop-heavy benchmarks and
 behind on Fibonacci, which is one call per node with no loop to promote.
 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.
 Call-heavy code is what this pays for -- Fibonacci went from 4.3x slower than `sf64` to 1.2x. Set
 `WAFER_TYPED_CALLS=0` to fall back to the memory-stack convention.
 ## Testing
 ```bash
-# All tests (~628 currently passing)
+# All tests (~570 currently passing)
 cargo test --workspace
 # Forth 2012 compliance suite
@@ -142,7 +128,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 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, and consolidation
+- **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
 - **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.7" }
+wafer-core = { path = "../core", version = "0.1.0" }
 wasmtime = { workspace = true }
 anyhow = { workspace = true }
 clap = { version = "4", features = ["derive"] }
@@ -263,8 +263,7 @@ 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() {
@@ -272,7 +271,6 @@ 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,11 +12,6 @@ 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.
@@ -43,7 +38,6 @@ impl WaferConfig {
            codegen: CodegenOpts {
                stack_to_local_promotion: true,
                stack_guards: true,
                typed_calls: true,
            },
        }
    }
@@ -62,7 +56,6 @@ impl WaferConfig {
            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, true);
+        let result = compile_consolidated_module(&words, &map, 16, None);
        // 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, true);
+        let result = compile_consolidated_module(&words, &map, 16, None);
        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, true);
+        let result = compile_consolidated_module(&words, &map, 16, None);
        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, true);
+        let result = compile_consolidated_module(&words, &map, 256, None);
        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, true);
+        let result = compile_consolidated_module(&words, &map, 16, None);
        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, true);
+        let result = compile_consolidated_module(&words, &map, 16, None);
        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, true);
+        let result = compile_consolidated_module(&words, &map, 16, None);
        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, true);
+        let result = compile_consolidated_module(&words, &map, 16, None);
        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, true);
+        let result = compile_consolidated_module(&words, &map, 16, None);
        assert!(result.is_ok());
    }
 }
@@ -192,9 +192,10 @@ impl Dictionary {
                    }
                }
            }
-            // In no wordlist of the search order: not findable
+            // Fallback: return newest entry across all wordlists
-            // (Forth 2012 §16.3.3 — the order is authoritative).
+            if let Some(&(_wid, word_addr, fn_index, is_immediate)) = entries.last() {
-            return None;
+                return Some((word_addr, WordId(fn_index), is_immediate));
            }
        }
        // Fallback: linked-list walk (for words not yet in the index)
@@ -126,7 +126,6 @@ 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,23 +108,6 @@ 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 {
@@ -166,9 +149,6 @@ 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);
@@ -53,12 +53,7 @@ pub fn optimize(
    // Phase 2: inline then simplify again
    if config.inline {
-        // A caller that can never leave the memory data stack would drag an
+        ir = inline(ir, bodies, 8);
        // 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.
        let keep_loops_out = !crate::codegen::promotable_modulo_calls(&ir);
        ir = inline(ir, bodies, 8, keep_loops_out);
    }
    if config.peephole {
        ir = peephole(ir);
@@ -501,12 +496,7 @@ 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(
+fn inline(ops: Vec<IrOp>, bodies: &HashMap<WordId, Vec<IrOp>>, max_size: usize) -> Vec<IrOp> {
    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 {
@@ -515,7 +505,6 @@ fn inline(
                    && 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).
@@ -528,7 +517,7 @@ fn inline(
            }
            _ => {
                out.push(apply_to_bodies(op, &|inner| {
-                    inline(inner, bodies, max_size, keep_loops_out)
+                    inline(inner, bodies, max_size)
                }));
            }
        }
@@ -1023,54 +1012,4 @@ mod tests {
        let result = optimize(vec![IrOp::Call(WordId(5))], &config, &bodies);
        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,16 +350,6 @@ 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 --
@@ -716,11 +706,6 @@ 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 -- )",
@@ -453,26 +453,6 @@ fn programs() -> Vec<Program> {
            expected: "99 \n",
            category: Category::Definitions,
        },
        Program {
            name: "search-order-hides",
            code: "WORDLIST CONSTANT MY-WL\n\
                   MY-WL SET-CURRENT\n\
                   : SECRET 42 ;\n\
                   FORTH-WORDLIST SET-CURRENT\n\
                   [UNDEFINED] SECRET . CR\n\
                   GET-ORDER MY-WL SWAP 1+ SET-ORDER\n\
                   [DEFINED] SECRET . CR\n\
                   SECRET . CR\n\
                   -1 SET-ORDER\n\
                   [UNDEFINED] SECRET . CR",
            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",
@@ -746,37 +726,37 @@ fn perf_benchmarks() -> Vec<PerfBenchmark> {
            verify: "25 FIB",
            expected: 75025,
            samples: 5,
-            max_ratio: 0.17,
+            max_ratio: 0.65,
        },
        PerfBenchmark {
-            name: "Factorial(12)x100K",
+            name: "Factorial(12)x10K",
            define: ": FACT 1 SWAP 1+ 1 ?DO I * LOOP ; \
-                     : FACT-BENCH 100000 0 DO 12 FACT DROP LOOP ;",
+                     : FACT-BENCH 10000 0 DO 12 FACT DROP LOOP ;",
            run_code: "FACT-BENCH",
            verify: "12 FACT",
            expected: 479001600,
            samples: 5,
-            max_ratio: 0.12,
+            max_ratio: 0.75,
        },
        PerfBenchmark {
-            name: "GCD-bench(20K)",
+            name: "GCD-bench(500)",
            define: ": GCD BEGIN DUP WHILE TUCK MOD REPEAT DROP ; \
                     : GCD-BENCH 0 DO 10000 I 1+ GCD DROP LOOP ;",
-            run_code: "20000 GCD-BENCH",
+            run_code: "500 GCD-BENCH",
            verify: "48 36 GCD",
            expected: 12,
            samples: 5,
-            max_ratio: 0.45,
+            max_ratio: 0.70,
        },
        PerfBenchmark {
-            name: "NestedLoops(50)x1K",
+            name: "NestedLoops(50)",
            define: ": NESTED 0 SWAP 0 DO I 0 ?DO I J + DROP LOOP LOOP ; \
-                     : NESTED-BENCH 1000 0 DO 50 NESTED DROP LOOP ;",
+                     : NESTED-BENCH 100 0 DO 50 NESTED DROP LOOP ;",
            run_code: "NESTED-BENCH",
            verify: "5 NESTED",
            expected: 0,
-            samples: 5,
+            samples: 3,
-            max_ratio: 0.11,
+            max_ratio: 0.20,
        },
        PerfBenchmark {
            name: "Collatz(2K)",
@@ -788,7 +768,7 @@ fn perf_benchmarks() -> Vec<PerfBenchmark> {
            verify: "27 COLLATZ",
            expected: 111,
            samples: 3,
-            max_ratio: 0.08,
+            max_ratio: 0.45,
        },
    ]
 }
@@ -344,32 +344,3 @@ 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.7", default-features = false, features = ["crypto"] }
+wafer-core = { path = "../core", version = "0.1.0", default-features = false, features = ["crypto"] }
 wasm-bindgen = "0.2"
 js-sys = "0.3"
 send_wrapper = { workspace = true }
@@ -38,23 +38,6 @@ 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());
@@ -151,7 +134,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| call_error(fn_index, &e))?;
+            .map_err(|e| anyhow::anyhow!("call_func({fn_index}) failed: {e:?}"))?;
        Ok(())
    }
 }
@@ -423,7 +406,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| call_error(fn_index, &e))?;
+            .map_err(|e| anyhow::anyhow!("call_func({fn_index}) failed: {e:?}"))?;
        Ok(())
    }
@@ -18,11 +18,11 @@ confidence-threshold = 0.8
 [bans]
 multiple-versions = "deny"
 wildcards = "deny"
-# Transitive duplicates from wasmtime v47 dependencies
+# Transitive duplicates from wasmtime v31 -- will resolve when upgrading
 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 4     | Highest |
+| 1  | Stack-to-Local Promotion   | Codegen      | Phase 2     | Highest |
 | 2  | Peephole Optimization      | IR pass      | Done        | High    |
 | 3  | Constant Folding           | IR pass      | Done        | High    |
 | 4  | Inlining                   | IR pass      | Done        | High    |
@@ -29,18 +29,12 @@ 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 |
 ## 1. 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`.
+**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`.
- **Phase 1** — straight-line code.
+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 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
@@ -458,59 +452,33 @@ 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 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 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.
 ## Current Performance vs Gforth
 All optimizations enabled, release mode, measured with UTIME:
 ```
-Benchmark                   WAFER     CONSOL     gforth       sf64    WAFER/gf   WAFER/sf
+Benchmark                   WAFER     CONSOL     gforth      WAFER/gf
-Fibonacci(25)                 356        361       3389        287       0.11x      1.24x
+Fibonacci(25)                1629       1535       3422        0.45x
-Factorial(12)x100K            479        495       6249       1650       0.08x      0.29x
+Factorial(12)x10K             340        339        638        0.53x
-GCD-bench(20K)                540        559       1801        801       0.30x      0.67x
+GCD-bench(500)                 18         15         30        0.50x
-NestedLoops(50)x1K            509        501       7023       1887       0.07x      0.27x
+NestedLoops(50)                84         73        720        0.10x
-Collatz(2K)                   185        213       3873        610       0.05x      0.30x
+Collatz(2K)                  1212       1202       3914        0.31x
 ```
-Times in microseconds. WAFER/gf < 1.0 means WAFER is faster. `sf64` is SwiftForth,
+Times in microseconds. WAFER/gf < 1.0 means WAFER is faster.
 which compiles to native code; two caveats on that column. The install here is an
 x86-64 binary under Rosetta 2 while WAFER and gforth are native arm64, so it is a
 native-vs-emulated comparison and a native SwiftForth would be faster than these
 numbers; and sf64 uses 64-bit cells to WAFER's 32-bit. WAFER is ahead on the four
 loop-heavy benchmarks and behind on Fibonacci, which is one call per node with no
 loop to promote.
 ## Remaining Opportunities
-| Optimization                     | Status              | Potential Impact                                                                                                                                                                                                                                                                                            |
+| Optimization                     | Status              | Potential Impact                                      |
-| -------------------------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| -------------------------------- | ------------------- | ----------------------------------------------------- |
-| Bounded self-inlining            | Not started         | Measured 1.33x on Fibonacci, the last benchmark behind sf64. Blocked on `EXIT`: the inliner refuses any body containing one, and a recursive Forth word is `... IF EXIT THEN ... RECURSE`. Needs either a scoped exit (compile an inlined `EXIT` as a branch to the end of a block) or guard-only expansion |
+| BEGIN loop promotion             | Not started         | Would speed up GCD-style tight loops further          |
-| BeginDoubleWhileRepeat promotion | Not started         | Rare pattern, low priority. Its promoted emitter exists but has no loop fixup and is unverified                                                                                                                                                                                                             |
+| BeginDoubleWhileRepeat promotion | Not started         | Rare pattern, low priority                            |
-| LEAVE as IR primitive            | Not started         | Would enable fast-path for loops with LEAVE                                                                                                                                                                                                                                                                 |
+| 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                                                                                                                                                                                                                                                                        |
+| 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                                                                                                                                                                                                                                                       |
+| WASM tail calls proposal         | Waiting on wasmtime | Would eliminate stack growth for tail-recursive words |
@@ -282,13 +282,11 @@ 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). When the word is also typed, that direct call goes to its fast entry -- see below.
+**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).
 **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.
+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.
 **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.
@@ -0,0 +1,230 @@
 # Plan: SEE / SEE-IR / HELP — Introspection Trio
 Status: implemented 2026-08-05 (all phases; HELP covers every word in a fresh VM, enforced by test)
 Scope: `SEE` (source-level decompile), `SEE-IR` (optimized-IR dump), `HELP` (per-word docs), shared lookup infrastructure.
 Each phase is self-contained and executable in a fresh context. Execute in order; every phase leaves the tree green (`cargo test --workspace` passes).
 ---
 ## Phase 0 — Consolidated Findings (read this first, do not re-derive)
 All references verified at commit `e31407a` (branch `usability`).
 ### The template to copy: WORDS
 `WORDS` is a **host primitive whose body runs Rust-side via the `pending_define` mechanism**. This is the exact pattern for SEE/SEE-IR/HELP because it gives a real dictionary entry (→ findable by `'`, listed by `WORDS`, tab-completable in the CLI via `crates/cli/src/main.rs:452-455`, exposed to web palette via `crates/web/src/lib.rs:61`) while the implementation can still call `next_token()` and write `self.output`.
 - Registration: `register_words()` at `crates/core/src/outer.rs:6301-6310` — host fn pushes code `40` into `pending_define`, called from `register_primitives()` at `outer.rs:2991` under the `// -- Programming-Tools word set --` header.
 - Dispatch: `handle_pending_define()` arm at `outer.rs:5328`: `40 => self.do_words(),`.
 - Body: `do_words()` at `outer.rs:6045-6074`. Note `outer.rs:6050-6052`: it reads an optional same-line argument with `self.next_token()` **gated on `self.state == 0`** — SEE must copy this gate.
 - **Used `pending_define` codes: 1–12, 20, 21, 25, 33, 40.** Free: **41 (SEE), 42 (SEE-IR), 43 (HELP)**. Legend comment at `outer.rs:232-233` must be extended.
 ### Allowed APIs (verified signatures)
 | API | Location | Notes |
 |---|---|---|
 | `Dictionary::find(&self, name: &str) -> Option<(u32, WordId, bool)>` | `dictionary.rs:182` | `(word_addr, WordId, is_immediate)`, case-insensitive |
 | `Dictionary::word_name(word_addr)` / `code_field(word_addr)` / `read_link` / `latest()` | `dictionary.rs:375/392/287/282` | manual entry walk |
 | `flags::IMMEDIATE = 0x80`, `HIDDEN = 0x40`, `INTERNAL = 0x20` | `dictionary.rs:16-27` | raw flags byte = `dict.memory()[(word_addr+4) as usize]` — no getter exists |
 | `ir_bodies: HashMap<WordId, Vec<IrOp>>` | `outer.rs:256` | **post-optimization** IR; populated for colon words AND all defining-word products AND IR primitives (see kind table below) |
 | `host_word_names: HashMap<WordId, String>` | `outer.rs:214` | only populated by `register_host_primitive` (`outer.rs:2702-2703`) |
 | `does_definitions: HashMap<WordId, DoesDefinition>` | `outer.rs:223` | DOES>-words |
 | `output: Arc<Mutex<String>>` | `outer.rs:208` | ALL text output goes here; `HostAccess` has **no** emit method (`runtime.rs:17-60`) |
 | `next_token()` | `outer.rs:690-704` | whitespace-delimited, advances `input_pos` |
 | `register_host_primitive(name, immediate, func) -> anyhow::Result<WordId>` | `outer.rs:2686-2691` | public |
 | `IrOp` enum, `#[derive(Debug, Clone, PartialEq)]` | `ir.rs:9-218` | **no `Display` impl exists anywhere in core** — formatter is net-new |
 | `eval_output(input) -> String` test helper | `outer.rs:7566` | fresh VM per call; multi-eval tests build VM inline like `outer.rs:9077-9080` |
 ### Word-kind classification (SEE must distinguish these)
 | Kind | Detectable via | SEE output strategy |
 |---|---|---|
 | Colon word / `:NONAME` | in `ir_bodies`, has captured source (Phase 3) | source (Phase 3) or IR (Phase 2) |
 | IR primitive (`DUP`…) | in `ir_bodies`, no source | IR body + "primitive" tag |
 | Host primitive (`.S`, `WORDS`…) | in `host_word_names` | `<built-in host word>` stub |
 | CONSTANT / VARIABLE / VALUE / CREATE / DEFER / SYNONYM / BUFFER: / 2\*/F\* | in `ir_bodies` with recognizable shape (e.g. CONSTANT = `[PushI32(v)]`, insert sites: `outer.rs:3194/3226/3263/3309/3351/3388/3440/6517/6547/6590/7344`) | synthesized definition, e.g. `42 CONSTANT ANSWER` (Phase 3) |
 | DOES>-defined word | key in `does_definitions` | show CREATE part + DOES> body IR |
 | Interpreter special token (`:`, `;`, `VARIABLE`, `'`, `CHAR`…) | hardcoded matches `outer.rs:755-820`, `927-992`; several have **no dictionary entry at all** | `<compiler word, handled by the outer interpreter>` stub |
 ### Hard constraints
 1. **Feature-free.** `outer.rs`, `ir.rs`, `dictionary.rs` compile without the `native` feature (`lib.rs:17-42`); web consumes core with `default-features = false` (`crates/web/Cargo.toml:15`). No `#[cfg(feature = "native")]` in any SEE code. Unit tests live in the existing `#[cfg(all(test, feature = "native"))]` module (`outer.rs:7553`) — that is fine and matches practice.
 2. **`ir_bodies` stores post-optimization IR** (`finish_colon_def`: optimize at `outer.rs:2297`, insert at `outer.rs:2298`; inlining threshold 8 at `optimizer.rs:56`). `: FOO SQ SQ ;` shows `SQ`'s body inlined. This is a *feature* for SEE-IR (shows what the optimizer did) and the *reason* SEE needs separate source capture (Phase 3).
 3. **Multi-line definitions**: compile state persists across `evaluate()` calls (`outer.rs:512-514` resets only `input_buffer`/`input_pos`); the driver (CLI `main.rs:411-416`) feeds lines. Source capture must accumulate across calls. On error, `evaluate()` wipes compile state (`outer.rs:523-535`) — capture state must be wiped there too.
 4. **Error house style** (`outer.rs:1294/3400/4057` precedents): `anyhow::bail!("SEE: unknown word: {name}")`, `anyhow::bail!("SEE: expected word name")`.
 5. **Compliance suite gives SEE zero coverage** — `toolstest.fth:38-39` explicitly excludes it. All coverage is hand-written unit tests. Adding SEE cannot break `compliance_tools`.
 6. **MARKER correctness**: any new per-word map (source text, docs) must be snapshotted/restored in `MarkerState` (`outer.rs:166-176`, snapshot `outer.rs:3462-3480`, restore `outer.rs:3484-3506`), mirroring how `ir_bodies` is handled there.
 ### Anti-patterns (verified NOT to exist — do not invent)
 - `HostAccess::emit(...)` / any output method on `HostAccess` — does not exist; capture `Arc::clone(&self.output)` instead.
 - `Display for IrOp` — does not exist; write the formatter.
 - A dictionary "entry struct" or kind tag — does not exist; classify via the VM-side maps above.
 - `Dictionary::flags(addr)` getter — does not exist; read the raw byte.
 - Refill-on-demand for a missing SEE argument — `REFILL`/`ACCEPT` are hardcoded to fail (`outer.rs:5824-5852`); `SEE` at end of line is an error, same as `'` (`outer.rs:4051-4053`).
 ---
 ## Phase 1 — IR pretty-printer (pure function, no VM changes)
 **Goal:** a feature-free formatter turning `&[IrOp]` into readable, indented text. Foundation for SEE-IR and the SEE fallback path.
 **What to implement:**
 1. New module `crates/core/src/see.rs`, registered unconditionally in `lib.rs` next to `pub mod outer;` (`lib.rs:30`). Public API:
   ```rust
   /// Format an IR body as indented, one-op-per-line text.
   pub fn format_ir(ops: &[IrOp]) -> String
   ```
 2. Exhaustive `match` over every `IrOp` variant (full list at `ir.rs:10-218`) — **no wildcard arm**, so adding a variant later forces a formatter update at compile time.
 3. Simple ops print as their Forth-ish name plus payload: `PushI32(7)` → `push 7`, `Call(WordId(12))` → `call #12`, `TailCall` → `tail-call #12`. Resolve `#12` to a word name at a higher level (Phase 2) — `format_ir` itself stays name-agnostic, but takes an optional resolver to keep it pure:
   ```rust
   pub fn format_ir_with(ops: &[IrOp], resolve: &dyn Fn(WordId) -> Option<String>) -> String
   ```
   (`format_ir` delegates with a `|_| None` resolver.)
 4. The six nested variants (`If`, `DoLoop`, `BeginUntil`, `BeginAgain`, `BeginWhileRepeat` at `ir.rs:78-99`, `BeginDoubleWhileRepeat` at `ir.rs:105-111`) print as Forth control words with 2-space indented bodies:
   ```
   if
     dup
     mul
   else
     drop
   then
   ```
 5. Flat branch ops (`Block`/`BranchIfFalse`/`EndBlock`, `ir.rs:118-124`) print literally (`block L3` etc.) — they have no clean Forth surface syntax; do not attempt reconstruction.
 **Verification checklist:**
 - [ ] Unit tests in `see.rs` (plain `#[cfg(test)]`, NOT feature-gated — the module has no runtime dependency): nested `If` inside `DoLoop` indents correctly; every-variant smoke test via a `Vec` containing one of each simple op.
 - [ ] `cargo check -p wafer-core --no-default-features` passes (proves feature-freedom).
 - [ ] `cargo test --workspace` green; `cargo fmt --all` + `cargo clippy --workspace` clean.
 **Anti-pattern guards:** no `impl Display for IrOp` (keep the formatter in `see.rs`, IrOp is data); no wildcard match arm; no `#[cfg(feature = "native")]`.
 ---## Phase 2 — SEE-IR word
 **Goal:** `SEE-IR name` prints the stored post-optimization IR for any word — the optimizer-debugging view. Ship this before source-SEE: it is nearly free and immediately useful.
 **What to implement:**
 1. Copy the WORDS registration pattern verbatim (`outer.rs:6301-6310`): `register_see_ir()` pushes pending code **42**; register in `register_primitives()` next to `self.register_words()?` (`outer.rs:2991`). Extend the legend comment at `outer.rs:232-233`.
 2. Dispatch arm in `handle_pending_define()` next to `outer.rs:5328`: `42 => self.do_see_ir(),`.
 3. `do_see_ir()` (place near `do_words()`, `outer.rs:6045`):
   - Parse name: `let Some(name) = self.next_token() else { bail!("SEE-IR: expected word name") }` — **no** interpret-mode gate here (unlike WORDS' optional filter, the argument is mandatory; compile-mode `SEE-IR` may simply also parse — matches `'`).
   - Lookup: `self.dictionary.find(&name)` → else `bail!("SEE-IR: unknown word: {name}")`.
   - Classify per the Phase 0 kind table, in this order: `ir_bodies` hit → header line + `see::format_ir_with(...)` with a resolver that maps `WordId` → name (build once from a dictionary walk: `latest()`/`read_link`/`word_name`/`code_field`, `dictionary.rs:282/287/375/392`); `host_word_names` hit → `SEE-IR: <name> is a built-in host word`; neither → `SEE-IR: <name> has no IR body`.
   - Header line format: `\ <NAME> — <n> ops (optimized IR)`, plus ` immediate` when the find() flag is set, plus `does>` info when `does_definitions` has the id.
   - Write everything into `self.output.lock().unwrap()`; end with `\n` (multi-line output convention from commit `2910884`).
 4. Special-token names (`:`, `VARIABLE`, `'`, …): after dictionary miss, check a small const list of known interpreter tokens (source: match arms at `outer.rs:755-820`, `927-992`) and print `SEE-IR: <name> is handled directly by the outer interpreter` instead of erroring.
 **Documentation references:** WORDS pattern `outer.rs:6301-6310`, `5328`, `6045-6074`; error style `outer.rs:4057`; output convention `outer.rs:6056-6073`.
 **Verification checklist:**
 - [ ] Tests (in `outer.rs` test module, `eval_output` style, cf. `outer.rs:9035-9041`):
  - `: SQ DUP * ; SEE-IR SQ` output contains `dup` and `mul`;
  - `: FOO SQ SQ ; SEE-IR FOO` shows the **inlined** body (contains two `mul`, no `call`) — locks in the "optimized view" semantics;
  - `SEE-IR DUP` works (IR primitive); `SEE-IR WORDS` prints host-word stub; `SEE-IR NOSUCHWORD` errors with `SEE-IR: unknown word: NOSUCHWORD`; bare `SEE-IR` errors with `expected word name`;
  - `SEE-IR :` prints the interpreter-token message.
 - [ ] `IF`/`ELSE`/`THEN` and `DO LOOP` bodies render indented (one structured-word test).
 - [ ] `cargo test --workspace` green; fmt + clippy clean; `cargo check -p wafer-core --no-default-features` passes.
 **Anti-pattern guards:** do not print via a nonexistent `HostAccess` emit; do not gate name parsing on `state == 0` (mandatory arg, not optional filter); do not `THROW -13` (plain `bail!` matches TO/SYNONYM precedent).
 ---
 ## Phase 3 — Source capture + SEE
 **Goal:** `SEE name` prints the original source text `: name … ;` for colon words, synthesized definitions for data words, graceful stubs otherwise. This is the user-facing SEE.
 **What to implement:**
 1. **Capture fields** on `ForthVM` (near `compiling_ir`, `outer.rs:204`):
   ```rust
   compiling_source: String,      // accumulated raw text of the definition in progress
   source_capture_from: Option<usize>,  // input_pos where capture started in the CURRENT buffer
   word_sources: HashMap<WordId, String>,
   ```
 2. **Capture protocol** (verbatim source, including comments and string literals — token-level reassembly would lose them):
   - `start_colon_def()` (`outer.rs:2097`): set `source_capture_from` to the position where `:` began. `interpret_token()` receives the token already consumed, so record the position **before** dispatch: in the `evaluate()` loop (`outer.rs:518-521`), remember `pos_before = self.input_pos` minus token — simplest correct form: capture `token_start` inside `next_token()` (`outer.rs:690-704`) into a new field `last_token_start: usize` as it skips whitespace; `start_colon_def` then does `self.source_capture_from = Some(self.last_token_start)`.
   - End of `evaluate()` (after the loop, `outer.rs:~536`): if still compiling and capture active, flush `input_buffer[from..]` + `'\n'` into `compiling_source`, reset `source_capture_from = Some(0)` so the next buffer continues capture from its start.
   - `finish_colon_def()` (`outer.rs:2266`): flush `input_buffer[from..=pos of ';']`, store `word_sources.insert(word_id, normalized)`, clear capture state. Normalize only trailing whitespace; keep interior verbatim.
   - Error path `outer.rs:523-535`: clear both capture fields alongside the existing compile-state wipe.
   - `:NONAME` and quotations (`outer.rs:759-761, 773-778`): skip capture (no name to SEE) — guard on `compiling_name.is_some()`.
 3. **MARKER integration**: add `word_sources` to `MarkerState` (`outer.rs:166-176`), snapshot (`outer.rs:3462-3480`) and restore (`outer.rs:3484-3506`) exactly as `ir_bodies` is handled there.
 4. **SEE word**: pending code **41**, same registration/dispatch shape as Phase 2. `do_see()` resolution order:
   1. `word_sources` hit → print stored source verbatim, append ` immediate` on its own line if flagged (cf. `set_immediate`, `dictionary.rs:404`).
   2. Recognizable data-word IR shape (Phase 0 kind table) → synthesized one-liner. CONSTANT `[PushI32(v)]` → `<v> CONSTANT <NAME>`; VARIABLE → `VARIABLE <NAME>  ( addr=<v> )`; VALUE `[PushI32(a), Fetch]` → `<cur> VALUE <NAME>` reading current value via `self.rt` memory read if cheap, else `VALUE <NAME>`; SYNONYM `[Call(id)]` → `SYNONYM <NAME> <OLD>`; DEFER → `DEFER <NAME>` plus current target name via `does`/pfa lookup when resolvable.
   3. `ir_bodies` hit (primitive or pre-capture colon word) → `\ <NAME> is a primitive; IR:` + `format_ir_with` output (reuse Phase 1/2 machinery — SEE never dead-ends).
   4. `host_word_names` hit → `<NAME> is a built-in host word`.
   5. Interpreter-token list → `<NAME> is handled by the outer interpreter (compiler word)`.
   6. Else → `bail!("SEE: unknown word: {name}")`.
 5. **Boot words get sources for free**: `boot.fth` definitions flow through the same `evaluate()`/`finish_colon_def` path, so `SEE NIP` etc. shows real boot source. Verify, don't assume — one test below.
 **Documentation references:** compile-state lifecycle `outer.rs:512-535`, `2097-2121`, `2266-2329`; multi-line REPL driver `main.rs:411-416`; MarkerState `outer.rs:166-176, 3462-3506`.
 **Verification checklist:**
 - [ ] `: SQ DUP * ; SEE SQ` prints `: SQ DUP * ;` (verbatim, one line).
 - [ ] Multi-line: inline-VM test (pattern `outer.rs:9077-9080`): `evaluate(": TRI\")` then `evaluate(\"  DUP DUP ;")`, then `SEE TRI` shows both lines.
 - [ ] Comment survives: `: C ( n -- n ) 1+ ; SEE C` output contains `( n -- n )`.
 - [ ] `42 CONSTANT A SEE A` → `42 CONSTANT A`; `VARIABLE V SEE V` → contains `VARIABLE V`.
 - [ ] `SEE NIP` (boot word) prints a colon definition, not an IR dump.
 - [ ] `SEE DUP` prints the primitive-IR fallback; `SEE WORDS` prints host stub; `SEE '` prints interpreter-token message; unknown word errors in house style.
 - [ ] MARKER round-trip: define word, set marker, redefine, execute marker, `SEE` shows the original — plus existing marker tests still green.
 - [ ] Immediate flag: `: I2 ; IMMEDIATE SEE I2` output contains `immediate`.
 - [ ] Error path: force `unknown word` mid-definition, then define a fresh word — its captured source must not contain debris from the aborted definition.
 - [ ] Full suite + fmt + clippy + `--no-default-features` check.
 **Anti-pattern guards:** do not reconstruct source from tokens (loses comments/strings/spacing); do not capture into `word_sources` for `:NONAME`; do not forget the error-path wipe (`outer.rs:523-535`) — stale capture corrupts the next definition's source; `evaluate()` resets `input_pos` per call (`outer.rs:512-514`) so `source_capture_from` is per-buffer, never carried across calls uncleared.
 ---
 ## Phase 4 — HELP word + doc table
 **Goal:** `HELP name` prints stack effect + one-line description; `HELP` alone prints usage. Shares lookup/classification with SEE.
 **What to implement:**
 1. New feature-free module `crates/core/src/wordhelp.rs`: a static table
   ```rust
   /// (NAME, stack effect, one-line description)
   pub const WORD_DOCS: &[(&str, &str, &str)] = &[
       ("DUP", "( x -- x x )", "Duplicate the top of the data stack."),
       ...
   ];
   pub fn lookup(name: &str) -> Option<(&'static str, &'static str)>  // case-insensitive
   ```
   Seed from the Forth 2012 glossary (stack effects are standardized). Cover, in priority order: core + core-ext words WAFER implements, then tools/double/float sets. Incomplete coverage is acceptable and expected — `HELP` says `no help for <name> (word exists)` when the word is defined but undocumented, which doubles as the TODO list.
 2. `HELP` word: pending code **43**, same registration/dispatch shape as Phase 2. Resolution: parse optional name (bare `HELP` → usage line `HELP <word>  — also try: WORDS, SEE <word>, SEE-IR <word>`); table hit → print `NAME  ( stack effect )  description`; miss but dictionary hit → `no help for <name>` + hint `try SEE <name>`; miss both → house-style unknown-word error.
 3. Cross-wiring (the "as useful as possible" part):
   - `SEE`/`SEE-IR` prepend the HELP line as a `\ ...` comment when the table has one.
   - `HELP` appends ` immediate` / `built-in` / `defined in boot.fth or user code` classification reusing the Phase 2/3 classifier — factor that classifier into a shared `fn classify_word(&self, name) -> WordClass` when Phase 4 lands (do NOT pre-build it in Phase 2; extract once there are two users, per smallest-change rule).
 4. User-defined words: optional docstring convention — if the captured source's first parenthesized comment looks like a stack effect (`( ... -- ... )`), `HELP` echoes it for user words. No new syntax, zero cost, rewards idiomatic Forth style.
 **Verification checklist:**
 - [ ] `HELP DUP` prints stack effect + description; `HELP dup` (lowercase) same.
 - [ ] `HELP` alone prints usage; `HELP NOSUCH` errors house-style; `HELP MYWORD` for undocumented-but-defined word prints the `no help` + `SEE` hint.
 - [ ] `: SQ ( n -- n^2 ) DUP * ; HELP SQ` echoes `( n -- n^2 )`.
 - [ ] Table lint test: iterate `WORD_DOCS`, assert every documented name resolves in a booted VM's dictionary (catches typos/renames mechanically).
 - [ ] Full suite + fmt + clippy + `--no-default-features`.
 **Anti-pattern guards:** no doc strings threaded through `register_primitive` call sites (200+ call-site churn, bloats outer.rs — the side table is deliberate); no partial-coverage panic — missing docs degrade gracefully.
 ---
 ## Phase 5 — Final verification + docs
 1. **Full gate:** `cargo fmt --all` && `cargo clippy --workspace` (zero warnings) && `cargo test --workspace` (expect baseline 431 unit + new SEE/SEE-IR/HELP tests, 1 benchmark, 11 compliance, 9 comparison — all green).
 2. **Feature-freedom proof:** `cargo check -p wafer-core --no-default-features` and web build `cd crates/web && wasm-pack build --target web --dev --out-dir www/pkg`.
 3. **Manual REPL pass** (CLI): `SEE SQ`, `SEE-IR FOO` with inlining, `HELP DUP`, multi-line definition then SEE, tab-complete `SE<tab>` — confirm multi-line output renders per commit `2910884` conventions (block output, ` ok` on own line).
 4. **Web REPL smoke:** serve `crates/web/www`, run the same commands — output flows through `take_output()` (`web/src/lib.rs:38-43`), no web-side changes expected.
 5. **Anti-pattern grep:** `grep -n "cfg(feature" crates/core/src/see.rs crates/core/src/wordhelp.rs` → empty; `grep -n "impl Display for IrOp" -r crates/core` → empty; `grep -rn "emit" crates/core/src/see.rs` → empty.
 6. **Docs:** `docs/FORTH.md:95` already lists SEE under Programming-Tools — verify claim now true; add SEE/SEE-IR/HELP to README feature list if words are enumerated there; extend CLAUDE.md test-count line.
 7. **Compliance untouched:** `cargo test -p wafer-core --test compliance` — must stay 11/11 (suite excludes SEE by design, `toolstest.fth:38-39`).
 ---
 ## Deliberate scope cuts (revisit later, not now)
 - **`SEE-WASM`** (disassemble compiled module via `wasmprinter`): compiled bytes are likely dropped after instantiation; `codegen.rs` unexamined. Separate plan if wanted.
 - **IR→Forth source reconstruction** for optimized bodies: lossy and misleading post-inlining; the source-capture path makes it unnecessary.
 - **`LOCATE` / editor integration**: needs file/line provenance in the dictionary; out of scope.
 - **Forth-side doc syntax (`:doc`)**: revisit after self-hosting work starts; the `( n -- n^2 )` echo in Phase 4 covers the 80% case with zero syntax.
Author	SHA1	Message	Date
Oleksandr Kozachuk	972c9544e4	chore(tools): sync bat syntax with current word set Alternations diffed against live WORDS output (304 words) plus outer-interpreter tokens. Adds float transcendentals, double-cell ops, pictured numeric, conditional compilation, string ops, SEE/SEE-IR/DUMP/BYE/HELP, RP@/RDEPTH/.RS, REMEMBER/EMPTY/GILD, DECIMAL/HEX, INCLUDE/INCLUDED, WITHIN, DEFER!/DEFER@, C,.	2026-08-06 12:23:20 +02:00
Oleksandr Kozachuk	5d40f32953	build: add just install recipe Installs bat Forth syntax, then cargo install --locked the CLI. CARGO_PROFILE_RELEASE_STRIP=none because Cargo's release default (strip = "debuginfo") emits dylibs macOS 27 dyld rejects with "mis-aligned LINKEDIT string pool"; proc macros then fail to load during the build.	2026-08-06 12:23:02 +02:00
Oleksandr Kozachuk	4ffa67e784	feat(core): INCLUDE, error overhaul, sf64 lane, WORDS ALL, .RS WS-012 -- INCLUDE/INCLUDED: - Injected source loader (core stays IO-free: CLI installs a filesystem reader, web leaves it unset -> defined error). Recursive include_file feeds files line-by-line through evaluate, so compile state and SEE capture span lines for free. Cycle detection, depth cap 16, paths relative to the including file, SOURCE-ID per nesting level, parent input restored on success/error/BYE. - CLI file mode now runs through the include machinery: `wafer x.fth` gets file:line error context and a base dir for nested INCLUDEs. - Unlocks the REMEMBER+INCLUDE reload loop. WS-008 -- error reporting remainder: - Errors inside included files carry `file.fth:12:` context (anyhow context chain; CLI prints {e:#}). - describe_uncaught now returns typed WaferError::UncaughtThrow { code, message } -- display text unchanged, THROW code reachable via downcast for CLI/web consumers. - compile_word emits a WASM name section; wasmtime trap backtraces name the faulting word and runtime_native prefixes "in <WORD>:". Batch/consolidated modules stay unnamed (no name plumbing there; boot primitives rarely trap). WS-003 -- SwiftForth correctness lane: - compare_all_programs_sf64 runs the program corpus with sf64 as oracle; whitespace-token comparison (sf64 prints numbers space-prefixed and echoes piped lines). 34/35 parity; dot-quote skipped (interpret-mode ." is a SwiftForth no-op). #[ignore]d like the gforth lane; `just compare-correctness` runs both. WS-011 leftovers: - WORDS ALL: grouped full view -- one section per wordlist (search order first), then internal words, each with counts. Backed by Dictionary::visible_entries (name, wid, internal); visible_words now derives from it. - .RS / RDEPTH: return-stack introspection in boot.fth over a new RP@ primitive (IrOp::RpFetch); BEGIN/WHILE walk so the walk never touches the stack it prints. SPACES clamped per 6.1.2230. 549 unit + 11 compliance + 9(+2) comparison + 5 crypto + 1 bench green; fmt/clippy clean; --no-default-features and wasm32 web checks pass.	2026-08-06 12:03:29 +02:00
Oleksandr Kozachuk	380250a641	feat(core): SEE, SEE-IR, HELP introspection trio (WS-010) Implements plans/01-see-introspection.md, all phases. - see.rs: feature-free IR pretty-printer (format_ir/format_ir_with), exhaustive over IrOp -- a new variant fails the build, not the output. - SEE-IR <name>: post-optimization IR view with resolved callee names, immediate/does> annotations; host-word and interpreter-token stubs. - SEE <name>: verbatim source capture for colon words (multi-line, comments preserved, EVALUATE-nesting safe, error-path wiped, MARKER/ REMEMBER/EMPTY roll word sources back too). Data definers (VARIABLE/ CONSTANT/CREATE/BUFFER:/2/F/SYNONYM) record synthesized one-liners at definition time; VALUE/2VALUE/FVALUE/DEFER synthesize at SEE time so current values and IS targets show. Fallback chain ends at IR dump or host-word stub -- SEE never dead-ends on a defined word. - HELP [<name>]: wordhelp.rs doc table with stack effect + one-line description for EVERY word in a fresh VM (300+ dictionary words plus all outer-interpreter tokens); a coverage test fails the build if a word is ever added undocumented. User words echo their leading ( ... -- ... ) comment. SEE/SEE-IR prepend the HELP line as a \ comment. Bare HELP prints usage. - boot.fth colon definitions get real sources for free (they flow through evaluate); INTERPRETER_TOKENS gained the missing ?DO. 524 unit + 11 compliance + 9 comparison + 5 crypto + 1 bench green; fmt/clippy clean; core still builds --no-default-features; web wasm-pack build unchanged.	2026-08-06 11:18:03 +02:00