a

1 files changed, 25 insertions, 0 deletions

diff --git a/docs/history/19-tools/notes.md b/docs/history/19-tools/notes.md
new file mode 100644
index 0000000..6989b80
--- /dev/null
+++ b/docs/history/19-tools/notes.md
@@ -0,0 +1,25 @@
+# memory debug, a bit more c, and a small host surface
+
+stage 18 tracks an alias that is still a name in the analyzer, and quarantines a block so a stale exact pointer reads intact bytes. this stage is the next layer: diagnostics you turn on, syntax people reach for, and enough of a host to write a small tool.
+
+## memory debug
+
+`memdebug on` (or `mem_set(1|4)`) records the source line of each `new` in a 64-slot table. the slot stores `p ^ MAGIC`, so the collector does not treat the table as a root. `memreport` prints `leak: line N W words` for slots whose block is still live and returns the count. W is the buddy payload, header included in the block but not in the count.
+
+checks walk at most 64 words back from a heap address to a header whose payload covers it. a dead header is `zy: use after free from line N` and the program stops. `free` of a block that is already quarantined prints `zy: double free from line N` and returns. the site stays until the storage is reused, which is why the second free still knows the line.
+
+bit 2 fills the payload with 57005 after children are released. bit 4 teaches the mark to accept an interior pointer the same way, so `p + k` keeps the block. it is off by default: a stale integer in that window would pin a block and the self-compile doesn't want that. programs that never say `memdebug` compile and run as before.
+
+`gc` zeros its own locals before scanning frames. an uninitialized slot was a root, and a leftover pointer from `free` was enough to keep a buddy chunk from merging.
+
+## syntax
+
+`do`/`while`, `enum` constants (the name is an int type), and `(T)e` for a simple type. `include "path"` reads a file with `readfile` and compiles it on the source stack the compiler already had, signatures first. `u`, `m` and `d` stay reserved.
+
+## host
+
+a store of an op to word `0xA0002` is a syscall: open, close, read, write, getenv, time. arguments are the next three words. `lib/std.zc` is not in the genome. it has atoi, itoa, strcat, starts, env, now and writefile. `examples/cli.zc` prints the length and first character of `$ZC_FILE`.
+
+## left alone
+
+the collector still scans the whole data stack, because the vm can't read its stack pointer. an alias that leaves a function, or an untyped index, is still not a compile-time borrow. interior pinning is opt-in and only 64 words deep. `include` is a path the host can open, not a search path. o3 stores don't hit the syscall gate. casts the parser can't see in a few tokens stay on `as`.