Skip to content

Commit b38654d

Browse files
hyperpolymathclaude
hyperpolymath
and
claude
authored
compiler: string-wall slice 7 — int_to_string (decimal rendering) (#573)
## Phase F slice 7 — variable-string backend wall (int_to_string) Seventh slice of the **variable-string backend** wall (`proposals/MIGRATION-PLAN.adoc` §"The two walls"), and **the last clean name-dispatched string op**. Adds the wasm-backend lowering for `int_to_string(n)` over the slice-3 allocation idiom, matching the interp oracle `string_of_int`. `int_to_string` was already wired in resolve/typecheck/interp; only codegen was absent. ### The lowering (`lib/codegen.ml`) 1. `neg = n < 0`. 2. `m = neg ? n : -n` (via `Select`) — the **non-positive magnitude**. For `INT_MIN`, `m = n` (no negation), so the un-representable positive magnitude is never formed. 3. **Digit count** — a do-while loop dividing a copy of `m` by 10 until 0 (runs ≥ once, so `n = 0` → one `'0'`, no special case). 4. `len = dc + neg`; allocate `4 + len`; store `len`. 5. **Write digits backwards** — a do-while loop emitting `48 - (m % 10)` per digit (i32 `rem_s` truncates toward zero, so `m % 10 ≤ 0` and `48 - (m%10) = '0' + digit`), then `m /= 10`. 6. Leading `'-'` for negatives (the `If`'s else-branch is a single `Nop` — no empty-else). **INT_MIN-safe:** `m / 10` (`div_s`) never traps (divisor 10 ≠ 0; the only trapping case `INT_MIN / -1` never occurs). ### Parity (wasm vs interp oracle) The wasm string was read back from linear memory and compared to `String(n)`; the interp oracle confirmed against the real library. Both agree across: | n | result | note | |---|---|---| | 0 | "0" | do-while yields one '0' | | 42 / -5 / -123 / 100 | "42" / "-5" / "-123" / "100" | sign, trailing zeros | | 2147483647 | "2147483647" | INT_MAX | | **-2147483648** | **"-2147483648"** | **INT_MIN — negative-space extraction** | ### Tests - `test/test_e2e.ml` — new `eval_string_fn` helper + group **"E2E String-wall slice 7 (int_to_string)"** — five full-string cases (0, 42, -123, INT_MAX, INT_MIN). Runs under `dune runtest`. - `tests/codegen/string_int_to_string.affine` + `tests/codegen/test_string_int_to_string.mjs` — executable wasm parity via `tools/run_codegen_wasm_tests.sh` (CI). Local verification: full `run_codegen_wasm_tests.sh` green (all seven string harnesses, slices 1–7; no sibling regressions); both backends confirmed against the real library; wasm string read back from memory. `dune runtest` couldn't run in-sandbox (no `alcotest`), but the new tests' logic + API usage was validated against the real `affinescript` library. ### Scope — the clean lane is closed **Every name-dispatched string builtin with a faithful trap-free wasm analogue is now lowered** (`string_length`, `string_char_code_at`, `char_to_int`, `string_from_char_code`, `string_sub`, `to_lowercase`, `to_uppercase`, `trim`, `string_find`, `int_to_string`). What remains needs **your direction**: - **concat (`++`) / polymorphic `slice`** — the highest-value remaining string work, **blocked on a type-access architectural decision**: codegen has no per-expression type info and `++` already lowers to *list* concat. Options: thread typecheck's types into codegen, or add a dedicated `string_concat` builtin (a language-surface addition). I'll write up both with a recommendation on request. - **`float_to_string`** — stays host-side under the float-wall. - **`string_get` / `int_to_char`** — deferred (raise on out-of-range). After this, the other half of the migration's compiler work is the **effect wall** (module-state / `Date.now` / `Console.log`). Evidence: `proposals/EVIDENCE-stringwall-slice7.adoc`. https://claude.ai/code/session_01WoKhFQePiRsAj7aqnxbG8s --- _Generated by [Claude Code](https://claude.ai/code/session_01WoKhFQePiRsAj7aqnxbG8s)_ Co-authored-by: Claude <noreply@anthropic.com>
1 parent 57eb667 commit b38654d

6 files changed

Lines changed: 331 additions & 7 deletions

File tree

‎lib/codegen.ml‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1238,6 +1238,79 @@ let rec gen_expr (ctx : context) (expr : expr) : (context * instr list) result =
12381238
in
12391239
Ok (c10, code)
12401240

1241+
| ExprVar id when id.name = "int_to_string"
1242+
&& List.length args = 1 ->
1243+
(* PHASE-F string-wall slice 7: decimal rendering. `int_to_string(n)`
1244+
produces the base-10 text of an i32 — matching the interp oracle
1245+
(`string_of_int`). Built on the slice-3 allocation idiom.
1246+
1247+
INT_MIN safety: the magnitude of `INT_MIN` (-2147483648) is not
1248+
representable as a positive i32, so we never negate into positive
1249+
space. Instead we work with the *non-positive* magnitude
1250+
`m = (n < 0) ? n : -n` (m <= 0 for all inputs incl. INT_MIN), and
1251+
each digit is `48 - (m % 10)` (i32 `rem_s` truncates toward zero,
1252+
so `m % 10 <= 0`, and `48 - (m%10) = '0' + digit`). `m / 10`
1253+
(`div_s`) never traps here (divisor 10 != 0, and the only trapping
1254+
`div_s` case, INT_MIN / -1, never occurs).
1255+
1256+
Both loops are *do-while* (`Loop [ body; cond; BrIf 0 ]`), so they
1257+
run at least once — giving `n = 0` the digit count 1 and the single
1258+
byte '0' with no special case. Digits come out least-significant
1259+
first, so they are written *backwards* from the last byte. *)
1260+
let* (ctx1, n_code) = gen_expr ctx (List.hd args) in
1261+
let (ctx2, heap_idx) = ensure_heap_ptr ctx1 in
1262+
let (c3, n) = alloc_local ctx2 "__i2s_n" in
1263+
let (c4, neg) = alloc_local c3 "__i2s_neg" in
1264+
let (c5, m) = alloc_local c4 "__i2s_m" in
1265+
let (c6, dc) = alloc_local c5 "__i2s_dc" in
1266+
let (c7, tmp) = alloc_local c6 "__i2s_tmp" in
1267+
let (c8, len) = alloc_local c7 "__i2s_len" in
1268+
let (c9, dst) = alloc_local c8 "__i2s_dst" in
1269+
let (c10, wpos) = alloc_local c9 "__i2s_wpos" in
1270+
let code =
1271+
n_code @ [LocalSet n] @
1272+
[ (* neg = n < 0 *)
1273+
LocalGet n; I32Const 0l; I32LtS; LocalSet neg;
1274+
(* m = neg ? n : (0 - n) — non-positive magnitude (INT_MIN-safe) *)
1275+
LocalGet n;
1276+
I32Const 0l; LocalGet n; I32Sub;
1277+
LocalGet n; I32Const 0l; I32LtS;
1278+
Select; LocalSet m;
1279+
(* dc = decimal digit count (do-while: >= 1, so 0 -> one digit) *)
1280+
LocalGet m; LocalSet tmp;
1281+
I32Const 0l; LocalSet dc;
1282+
Loop (BtEmpty, [
1283+
LocalGet dc; I32Const 1l; I32Add; LocalSet dc;
1284+
LocalGet tmp; I32Const 10l; I32DivS; LocalSet tmp;
1285+
LocalGet tmp; BrIf 0 ]);
1286+
(* len = dc + neg *)
1287+
LocalGet dc; LocalGet neg; I32Add; LocalSet len;
1288+
(* dst = heap; heap += 4 + len *)
1289+
GlobalGet heap_idx; LocalSet dst;
1290+
GlobalGet heap_idx; I32Const 4l; LocalGet len; I32Add; I32Add;
1291+
GlobalSet heap_idx;
1292+
(* dst[0] = len *)
1293+
LocalGet dst; LocalGet len; I32Store (2, 0);
1294+
(* write digits backwards: wpos = dst + 4 + len - 1 (absolute) *)
1295+
LocalGet dst; I32Const 4l; I32Add; LocalGet len; I32Add;
1296+
I32Const 1l; I32Sub; LocalSet wpos;
1297+
Loop (BtEmpty, [
1298+
(* [wpos] = '0' + digit = 48 - (m % 10) *)
1299+
LocalGet wpos;
1300+
I32Const 48l; LocalGet m; I32Const 10l; I32RemS; I32Sub;
1301+
I32Store8 (0, 0);
1302+
LocalGet m; I32Const 10l; I32DivS; LocalSet m;
1303+
LocalGet wpos; I32Const 1l; I32Sub; LocalSet wpos;
1304+
LocalGet m; BrIf 0 ]);
1305+
(* leading '-' at dst+4 when negative (else-branch is a no-op) *)
1306+
LocalGet neg;
1307+
If (BtEmpty,
1308+
[ LocalGet dst; I32Const 45l; I32Store8 (0, 4) ],
1309+
[ Nop ]);
1310+
LocalGet dst ]
1311+
in
1312+
Ok (c10, code)
1313+
12411314
| ExprVar id when (id.name = "env_at" || id.name = "arg_at")
12421315
&& List.length args = 1 ->
12431316
(* ADR-015 S5 (#180): env_at(i) / arg_at(i) — fetch the i-th

‎proposals/EVIDENCE-stringwall-slice7.adoc‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
// SPDX-License-Identifier: MPL-2.0
2+
// SPDX-FileCopyrightText: 2025-2026 hyperpolymath
3+
= Phase F — string-wall slice 7: int_to_string (evidence)
4+
:toc: macro
5+
6+
[IMPORTANT]
7+
====
8+
*Slice landed: decimal rendering.* `int_to_string(n)` — already wired in
9+
resolve/typecheck/interp — gained a wasm-backend lowering producing the
10+
base-10 text of an i32, matching the interp oracle (`string_of_int`). Built on
11+
the slice-3 allocation idiom.
12+
13+
*INT_MIN-safe:* the magnitude of `INT_MIN` (-2147483648) is not a representable
14+
positive i32, so the lowering never negates into positive space — it works
15+
with the *non-positive* magnitude and extracts digits as `48 - (m % 10)`.
16+
17+
Seventh slice of the *variable-string backend* wall
18+
(`proposals/MIGRATION-PLAN.adoc` §"The two walls", Phase F). This is the *last
19+
clean name-dispatched* string op; what remains needs a design decision (below).
20+
====
21+
22+
toc::[]
23+
24+
== What was missing
25+
26+
`int_to_string` was wired in resolve/typecheck/interp; only the wasm codegen
27+
was absent (fell through `gen_call`'s dispatch -> `UnboundVariable`).
28+
29+
== The lowering (lib/codegen.ml)
30+
31+
Interp oracle: `string_of_int n`.
32+
33+
. `neg = n < 0`.
34+
. `m = neg ? n : -n` (via `Select`) — the *non-positive* magnitude. For
35+
`INT_MIN`, `neg` is true and `m = n` (no negation), so the un-representable
36+
positive magnitude is never formed.
37+
. *Digit count* `dc` — a *do-while* loop dividing a copy of `m` by 10 until 0.
38+
Because it runs at least once, `n = 0` yields `dc = 1` (the single '0') with
39+
no special case.
40+
. `len = dc + neg`; allocate `4 + len`; store `len`.
41+
. *Write digits backwards* — a *do-while* loop from the last byte:
42+
`[wpos] = 48 - (m % 10)` (i32 `rem_s` truncates toward zero, so `m % 10 <= 0`
43+
and `48 - (m%10) = '0' + digit`), then `m = m / 10`, `wpos--`, until `m = 0`.
44+
. If `neg`, write `'-'` (45) at `dst + 4`.
45+
46+
`m / 10` (`div_s`) never traps: the divisor is 10 (not 0), and the only
47+
trapping `div_s` case (`INT_MIN / -1`) never occurs. The leading-`'-'` write
48+
uses an `If` whose else-branch is a single `Nop` (no empty-else).
49+
50+
== Gate evidence
51+
52+
=== Gate 1 — builds
53+
54+
`dune build bin/main.exe` exit 0.
55+
56+
=== Gate 2 — parity (wasm vs interpreter oracle)
57+
58+
The wasm string was read back from linear memory (`[len][utf8]`) and compared
59+
to `String(n)`; the interp oracle (`string_of_int`) was confirmed against the
60+
real library API. Both agree across zero, single digit, multi-digit, negative,
61+
powers of ten, `INT_MAX`, and `INT_MIN`:
62+
63+
[cols="2,2,2",options="header"]
64+
|===
65+
| n | interp / wasm | note
66+
| 0 | "0" | do-while yields one '0'
67+
| 7 | "7" | single digit
68+
| 42 | "42" |
69+
| -5 | "-5" | sign
70+
| -123 | "-123" |
71+
| 100 | "100" | trailing zeros
72+
| 2147483647 | "2147483647" | INT_MAX (10 digits)
73+
| -2147483648 | "-2147483648" | *INT_MIN — negative-space extraction*
74+
|===
75+
76+
The packed fixture `tests/codegen/string_int_to_string.affine` returns
77+
`3485103` (three positional bytes + INT_MIN/INT_MAX content/length probes);
78+
both backends produce it.
79+
80+
== Tests added
81+
82+
* `test/test_e2e.ml` — new `eval_string_fn` helper + group *"E2E String-wall
83+
slice 7 (int_to_string)"*: five full-string interp-oracle cases (0, 42, -123,
84+
INT_MAX, INT_MIN). Runs under `dune runtest`.
85+
* `tests/codegen/string_int_to_string.affine` +
86+
`tests/codegen/test_string_int_to_string.mjs` — executable wasm parity, run
87+
by `tools/run_codegen_wasm_tests.sh` (CI).
88+
89+
Full `tools/run_codegen_wasm_tests.sh` run: *all* codegen WASM tests pass
90+
(slices 1-7 string harnesses), no sibling regressions.
91+
92+
== Corpus impact
93+
94+
Integer-to-text rendering — one of the most common string-building operations,
95+
explicitly called out in the migration recipe as a "hand-ladder int rendering"
96+
workaround — now lowers to wasm. This *closes the clean lane*: every
97+
name-dispatched string builtin with a faithful trap-free wasm analogue is
98+
lowered (`string_length`, `string_char_code_at`, `char_to_int`,
99+
`string_from_char_code`, `string_sub`, `to_lowercase`, `to_uppercase`, `trim`,
100+
`string_find`, `int_to_string`).
101+
102+
== What remains — a design decision (NOT done autonomously)
103+
104+
* *Concatenation (`++` / `OpConcat`) and polymorphic `slice`* — the remaining
105+
high-value string ops, *blocked on a type-access decision*: `lib/codegen.ml`
106+
has no per-expression type information (`ExprBinary` is an untyped AST node;
107+
no type environment is threaded into codegen), and `++` already lowers to
108+
*list* concatenation. Lowering them for strings requires either (a) threading
109+
typecheck's inferred types into the AST / a side table consumed by codegen,
110+
or (b) adding a dedicated `string_concat` builtin (name-dispatched, sidesteps
111+
the operator overload) — a language-surface decision. Both are owner calls.
112+
* *`float_to_string`* — needs the float story; stays host-side under the
113+
float-wall convention.
114+
* *`string_get` / `int_to_char`* — deferred (raise on out-of-range; no
115+
trap-free wasm analogue without a declared-clamp convention).
116+
117+
== Next
118+
119+
. *Concatenation / `slice`* — gated on the type-access design decision above.
120+
. Otherwise, the *effect-codegen wall* (module-state / `Date.now` /
121+
`Console.log`) is the other half of the migration's compiler work.

‎proposals/MIGRATION-PLAN.adoc‎

Lines changed: 9 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -42,12 +42,13 @@ toc::[]
4242
(`string_char_code_at` / `char_to_int`, slice 1), single-byte *construction*
4343
(`string_from_char_code`, slice 2), *runtime-length substring* (`string_sub`,
4444
slice 3), *ASCII case-folding* (`to_lowercase` / `to_uppercase`, slice 4),
45-
*whitespace trimming* (`trim`, slice 5), and *substring search*
46-
(`string_find` — flat-safe nested scan, slice 6) now lower to wasm (Phase F,
47-
see Ledger); `int_to_string`, concat / `++`, and polymorphic `slice` do not
48-
yet (the last two are gated on a type-access design decision — see Ledger
49-
F+). Gates every STRING-GATED kernel (e.g. `Kernel_IO`, `DeviceType`, i18n)
50-
whose work is building/transforming strings rather than scanning them. Lives
45+
*whitespace trimming* (`trim`, slice 5), *substring search* (`string_find`,
46+
slice 6), and *decimal rendering* (`int_to_string`, slice 7) now lower to
47+
wasm (Phase F, see Ledger) — *the clean lane is closed*; only concat / `++`
48+
and polymorphic `slice` remain, gated on a type-access design decision (see
49+
Ledger F+). Gates every STRING-GATED kernel (e.g. `Kernel_IO`, `DeviceType`,
50+
i18n) whose work is building/transforming strings rather than scanning them.
51+
Lives
5152
in *this* repo's compiler, so it is
5253
attackable here.
5354
. *Effect codegen* — module-level mutable state / `Date.now` / `Console.log`
@@ -214,7 +215,8 @@ Heuristic:
214215
| F (string slice 4) | DONE | String-wall slice 4 — *ASCII case-folding landed in the wasm backend* (2026-06-13, Opus). `to_lowercase` / `to_uppercase` (already wired in resolve/typecheck/interp) gained wasm lowerings as a *copy-with-transform* over the slice-3 runtime-length idiom: allocate `4 + slen`, copy each byte through a *branchless* ASCII case shift (`c ± 32*((c>=lo)&(c<=hi))`, an `I32And` 0/1 product — no per-byte `If`). Matches the interp oracle (`String.{lowercase,uppercase}_ascii`): only `'A'..'Z'`/`'a'..'z'` shift; digits, punctuation, and bytes ≥128 pass through. *Gates:* G1 builds; G2 parity 7/7 (interp vs wasm), incl. the exclusive `@`(64)/`[`(91) boundary probes + length preservation. Tests: `test/test_e2e.ml` group "E2E String-wall slice 4 (case-fold)" (interp, `dune runtest`) + `tests/codegen/string_case.{affine,…mjs}` (executable wasm parity; full `run_codegen_wasm_tests.sh` green, no regressions). Evidence: `proposals/EVIDENCE-stringwall-slice4.adoc`. Proves the alloc+copy idiom carries per-byte transforms. NEXT: concat (`++`/`string_concat`), then `string_find`/`trim`/`slice`.
215216
| F (string slice 5) | DONE | String-wall slice 5 — *whitespace trimming landed in the wasm backend* (2026-06-13, Opus). `trim` (already wired in resolve/typecheck/interp) gained a wasm lowering: two flat scans bracket the non-whitespace core (front for `lo`, back for `hi` exclusive; whitespace set `{32,9,10,12,13}` via an `is_ws` `I32Or` chain), then a slice-3-style byte copy of `[lo, hi)`. Matches `String.trim`: internal whitespace preserved, all-whitespace -> empty. *Gates:* G1 builds; G2 parity 7/7 (interp vs wasm: both-end/leading/trailing, all-ws, empty, internal-space preservation, tab+newline). Tests: `test/test_e2e.ml` group "E2E String-wall slice 5 (trim)" (interp, `dune runtest`) + `tests/codegen/string_trim.{affine,…mjs}` (executable wasm parity; full `run_codegen_wasm_tests.sh` green, no regressions). Evidence: `proposals/EVIDENCE-stringwall-slice5.adoc`. *The clean name-dispatched builtins (read/write/copy/transform/scan) are now done.* NEXT decision point — see F+ row.
216217
| F (string slice 6) | DONE | String-wall slice 6 — *substring search landed in the wasm backend + an interp bugfix* (2026-06-13, Opus). `string_find(haystack, needle)` (already wired in resolve/typecheck/interp) gained a wasm lowering: a *flat-safe* nested scan (inner AND-accumulates a match over `nlen` bytes with no early break; outer exits at top on `res != -1` or `i > hlen - nlen`; result update is a branchless `Select`) returning the first-occurrence index or -1, no allocation. *Also fixed a latent interp bug:* `string_find` called `String.get needle 0` before its `nlen = 0` guard, so an empty needle crashed the interpreter (uncaught `Invalid_argument`); the guard is reordered so an empty needle returns `0`, making both backends agree. *Gates:* G1 builds; G2 parity 8/8 (found/not-found/first-occurrence/needle-longer/empty-needle/empty-haystack/both-empty). Tests: `test/test_e2e.ml` group "E2E String-wall slice 6 (string_find)" (interp, incl. the formerly-crashing empty-needle case, `dune runtest`) + `tests/codegen/string_find.{affine,…mjs}` (executable wasm parity; full `run_codegen_wasm_tests.sh` green, no regressions). Evidence: `proposals/EVIDENCE-stringwall-slice6.adoc`. *All name-dispatched string builtins with a trap-free wasm analogue are now lowered.* NEXT: `int_to_string` (last clean op), then the gated concat/`slice` decision.
217-
| F+ | TODO (design decision) | Remaining string ops: (a) *`int_to_string`/`float_to_string`* — `int_to_string` is the last clean autonomous slice (decimal digit loop + sign; handle `INT_MIN` by extracting digits in negative space); `float_to_string` stays host-side under the float-wall. (b) *concat `++` / polymorphic `slice`* — **blocked on an architectural decision**: codegen has *no per-expression type access* (`ExprBinary` is untyped, no type env threaded in), so string `++` (vs the existing list `OpConcat`) and `slice` (array|string) need either typed-AST threading or a dedicated `string_concat` builtin (language-surface call). (c) *`string_get`/`int_to_char`* — deferred (raise on out-of-range; no trap-free wasm analogue). Then the *effect-codegen wall* (module-state / `Date.now` / `Console.log`). See `proposals/EVIDENCE-stringwall-slice6.adoc` §"what remains". *Cluster migration complete; string slices 1-6 landed (read + single-byte write + runtime-length copy + per-byte transform + scan-and-copy + substring search).*
218+
| F (string slice 7) | DONE | String-wall slice 7 — *decimal rendering landed in the wasm backend* (2026-06-13, Opus). `int_to_string(n)` (already wired in resolve/typecheck/interp) gained a wasm lowering over the slice-3 allocation idiom: `neg = n<0`; `m = neg ? n : -n` (non-positive magnitude via `Select`); a do-while digit-count loop (so `n=0` yields one '0' with no special case); allocate `4 + dc + neg`; a do-while backward-write loop emitting `48 - (m%10)` per digit; leading `'-'` when negative. *INT_MIN-safe* — the un-representable positive magnitude is never formed; `div_s`/`rem_s` by 10 never trap. *Gates:* G1 builds; G2 parity over 0/single/multi-digit/negative/powers-of-ten/INT_MAX/INT_MIN (wasm string read back from memory vs `string_of_int`). Tests: `test/test_e2e.ml` new `eval_string_fn` + group "E2E String-wall slice 7 (int_to_string)" (5 full-string cases incl. INT_MIN, `dune runtest`) + `tests/codegen/string_int_to_string.{affine,…mjs}` (executable wasm parity; full `run_codegen_wasm_tests.sh` green, no regressions). Evidence: `proposals/EVIDENCE-stringwall-slice7.adoc`. *Clean lane CLOSED — every name-dispatched string builtin with a trap-free wasm analogue is lowered.* NEXT: the gated concat/`slice` decision, or the effect wall.
219+
| F+ | TODO (design decision) | The *clean* string slices are done (1-7). What remains: (a) *concat `++` / polymorphic `slice`* — **blocked on an architectural decision**: codegen has *no per-expression type access* (`ExprBinary` is untyped, no type env threaded in), so string `++` (vs the existing list `OpConcat`) and `slice` (array|string) need either typed-AST threading or a dedicated `string_concat` builtin (language-surface call). *This is the highest-value remaining string work and needs owner direction.* (b) *`float_to_string`* — stays host-side under the float-wall. (c) *`string_get`/`int_to_char`* — deferred (raise on out-of-range; no trap-free wasm analogue). Then the *effect-codegen wall* (module-state / `Date.now` / `Console.log`) — the migration's other compiler half. See `proposals/EVIDENCE-stringwall-slice7.adoc` §"what remains". *Cluster migration complete; string slices 1-7 landed (read + single-byte write + runtime-length copy + per-byte transform + scan-and-copy + substring search + decimal rendering).*
218220
| Ω | TODO (access-gated) | Cutover + ReScript extinction.
219221
|===
220222

0 commit comments

Comments
 (0)