a

1 files changed, 22 insertions, 0 deletions

diff --git a/docs/history/20-words/notes.md b/docs/history/20-words/notes.md
new file mode 100644
index 0000000..ae63b79
--- /dev/null
+++ b/docs/history/20-words/notes.md
@@ -0,0 +1,22 @@
+# 20 — 64-bit words
+
+the vm word went from 32 bits to 64. memory is still word-addressed, and the map (heap, frames, stacks, `GORG`, the syscall gate) is the same word indices. each cell is 8 bytes on the host. there is no dual-width flag.
+
+## what changed
+
+- the image is little-endian 64-bit words: `zc0`, `mkgenome` and `tools/build.zc` read and write 8 bytes per word. `genome.h` is `int64_t`.
+- a literal is still an odd word. `w >> 1` is a 63-bit signed immediate. the resident `lit` (`v + v + 1`) did not need a new formula. zero tests (`!`, `!!`, `==`, `!=`) shift by 63, in `zc0` and in the operator recipes.
+- the interpreter, the enhancement evaluator and the o3 region interpreter use 64-bit cells. shifts mask with 63. `mulhs` / `mulhu` are the high half of a 128-bit product. `clz` of 0 is 64. signed and unsigned division by a constant use the 64-bit magic-number sequence, and `INT64_MIN / -1` stays defined.
+- the arm64 jit loads and stores 8-byte cells, does alu in the x registers, and builds 64-bit immediates with up to four `movk` halfwords. the stack index is a byte offset shifted by 3. the llvm path uses i64 for vm values and i128 for the multiply-high. neither backend was executed here (no `aarch64` toolchain, no `llvm-config`); both were typechecked as far as this host allows, and the jit path compiles.
+- `zshl` and the software divider cover 64 bits. `putn` and `itoa` print the full magnitude, including the minimum word. the mandelbrot fixed-point multiply is a multiply and an arithmetic shift, which matches the old 16.16 picture. the popcount recipe uses 64-bit masks; `popcount(0xff00ff)` is still 16.
+- calling convention is unchanged: arguments are words, frame slots are word indices, and the signature packs the same small fields (`(ssig >> 1) & 31` is still the arity, not a shift width). the 6-word object header, buddy classes and the heap word counts are unchanged. `tests/buddy.zc` still expects `131072 262144 1 0`.
+
+## abi
+
+images, `genome.h` and any saved binary are not compatible with the 32-bit machine. source that fits in a 63-bit signed literal recompiles. the minimum word is not itself a literal.
+
+this is still not a C abi. a character is still one word, not one byte. the compiler's own source buffer still packs four characters into a word. calls do not match a host calling convention.
+
+## check
+
+`test.sh` on the interpreter: fixpoint at 91158 words, `genome.h` matches, 57 checks, 0 failed. that includes aliases, quarantine, memdebug, syscalls, `lib/std.zc`, o3, and `tests/wide.zc` (`1 << 40` and equality of that value).