a

1 files changed, 50 insertions, 0 deletions

diff --git a/docs/history/README.md b/docs/history/README.md
new file mode 100644
index 0000000..b38f981
--- /dev/null
+++ b/docs/history/README.md
@@ -0,0 +1,50 @@
+# history
+
+the scrapbook. one folder per stage, each with notes.md: what was asked, what got built, and the working notes from the time, kept as written and only added to. stages that still have their code keep a frozen copy in code/:
+
+- 01-golf, 02-hardware, 04-darwin-compiler, 05-hybrid, 06-choosing: notes only, their code wasn't kept
+- 07-zygote: notes and code (the asm genome and the arm64-only core, as packed in stages 8 and 9)
+- 08-packaging: notes only
+- 10-zc: notes and code (zc, u m d, the collector, the self-hosting compiler)
+- 11-types-enhancements: notes and code (types, generics, reflection, the typechecker, virtual enhancements, the llvm backend)
+- 13-gap-fixes: notes and code (joins with fixup frees, the buddy heap, stack checks, error recovery, the prescan, ?: and switch)
+- 15-o3: notes and code (the examples, c-style return types, growable and fixed arrays, the o3 optimizing tier, literal-specialized enhancements, the release fix)
+- 17-o3-boundaries: notes and code (generics after the name, fattening o3 data on the way out, registers by scope, cached fixed arrays)
+- 18-aliases: notes only (borrowed-from marks on derived pointers, quarantine on free)
+- 19-tools: notes only (memory debug, do/while, enum, casts, include, syscalls, lib/std.zc)
+- 20-words: notes only (the vm word widened from 32 bits to 64)
+- 21-micro: notes only (a portable microcore for the same genome)
+- 22-size: notes only (a build-time memory map, a 1.31 mb compiler, a 256 kb run-only image)
+- 23-baremetal: notes only (the microcore booting on qemu-system, riscv and aarch64 virt, UART in and out)
+- 24-backends: notes only (the arm64 jit under qemu-user, and the llvm backend, run against the interpreter)
+- 25-genmap: notes only (one layout for every memory size)
+- 26-bareapi: notes only (syscall gate on the virt boards: console, clock, exit, files)
+- 27-float: notes only (IEEE binary64 on the interpreter, both jits, the microcore and both virt boards)
+- 28-bytes: notes only (byte addresses beside word addresses, opcodes 612..617)
+- 29-strings: notes only (packed byte strings, `b"..."`, length, slice, concat, and byte syscalls)
+- 30-sharing: notes only (shared cons cells and strings, collected by the existing sweep)
+- 31-fpu: notes only (hardware float ops where an FPU exists, and a soft-float fallback)
+- 32-ftype: notes only (float is a type: calls, globals, fields, parameters, returns; -0.0 is false; 1.field is a field)
+- 33-fo3: notes only (o3 lifts float ops: IEEE-safe folds, FP registers, no x-x rewrite)
+- 34-ftext: notes only (libc-free print and parse of the full double range)
+- 35-bench: notes only (a word sieve and a binary tree, timed against C)
+- 36-alloc: notes only (recycle onto the size-class list, a 5-word header, a bump arena)
+- 37-call: notes only (o3 calls o3 by entering the region, and fatten only at a real boundary)
+- 38-bounds: notes only (a proved index stays in a register, and a +1 loop drops the check)
+- 39-blocks: notes only (empty jumps folded, a straight loop rotated to one block)
+- 40-fatten: notes only (typed new stamps the header, and a child store writes the owner in the region)
+- 41-obytes: notes only (ld8 through st32 lift inside an o3 region)
+- 42-roots: notes only (the collector marks from the live stack index, and scrub clears the rest)
+- 43-stdlib: notes only (u, m and d are names, an arena and a packed byte buffer, and untyped new inside o3 is zeroed)
+- 44-check-mode: notes only (the language server is the compiler in check mode, struct methods and closures, postfix pointer types, same-line braces, a webassembly build)
+- 45-fast-alloc: notes only (no prefix pointers, constant-size allocation fast path, maps sized to their program, a makefile, the core sources formatted and explained)
+- 46-c-abi: notes only (the backtick is lexical, a parse word must read, lexer speed-ups, llvm target info, extern and cfunc native calls, a default map with a bigger genome slot)
+- 47-limits: notes only (a heap that grows to the host's memory, host fill/copy/scan, native calls the optimizer sees, sized integers and f32 with packed arrays, ctz popcnt bswap rotl rotr f2s s2f)
+
+the code folders are snapshots. they're not built or tested from here, the top level is the live tree.
+- 48 landing: packed fields, []sized, f32 extern, page-indexed invalidation, llvm trackers, faster o3 calls
+- 49 generics: monomorphized multi-parameter generics and generic methods, llvm inline calls, global const-prop in o3, bigger default map
+- 50 adt: tagged enums with fields, constructors, `case member(a, b):` matching, and a coverage warning
+- 51 llvm-inline-stdlib: llvm inlining of o3 calls, stdlib text and num helpers, host syscalls through SYS_RAW, and the fuzz campaign's findings
+- 52 closures: closure calls work (the block is never run; a call into a heap closure goes through its entry word), captures chain through enclosing closures, and the closure test joins the suite
+- 53 typed source: every function, local and global in the compiler, the runtime and the language server is typed (zc0's image does not change), and the extension caches diagnostics by a sha256 of the tree they cover