todo: one sorted list of open work; library suggestions without naming libraries

TODO.md ticks the items verified done (namespaces, actor and icon libraries
and their coverage, the genome embed, the bootstrap ownership limits, the
docs and fixtures sweep) and lists everything still open, including the
newly requested language features, sorted easiest first.

the compiler no longer names actor: file libraries for suggestions come from
src/lib/modules.txt, and lib.name before its include reports the missing
include. icon gains fixtures for reading globals while stepping and for
begin_function on a non-function, and the suite checks that nothing the
compiler reads by default mentions actors. bf.zc, the web sample and std's
capture example use qualified runtime names; LEARN.md uses build/bin paths.

1 files changed, 36 insertions, 12 deletions

diff --git a/TODO.md b/TODO.md
index ee308e8..4731675 100644
--- a/TODO.md
+++ b/TODO.md
@@ -132,16 +132,40 @@
 - [x] verify collector-growth accounting relative to existing allocations and investigate conservative roots retained after clearing large global arrays.
 - [x] allow repeated `_` discard placeholders in parameters and patterns, including tagged-enum payloads and catch-all cases; warn when a bound discard value is read.
 - [x] add generic native and hosted microcore thread contexts with isolated vm state, channels, cancellation and cleanup; verify 14 native and 12 microcore fixtures while keeping actor-specific code in its library.
-- [ ] give core built-ins and every other toolchain module their own namespace and require an explicit include to access qualified exports: `include core;` enables `core.name`, with the same rule for all other modules. remove implicit toolchain imports, migrate maintained sources and generated code, and verify missing-include diagnostics, completions, hovers and navigation before expanding the standard library.
-- [ ] add a generic include-time syntax-extension interface so imported libraries can extend compiler parsing and lowering without module-specific compiler code; keep all extension hooks generic and inactive unless the corresponding library is included.
-- [ ] continue removing `unchecked` from the remaining runtime boundaries by teaching the analyzer the missing ownership and drop contracts; document any irreducible low-level escapes. The compiler, standard library and LSP no longer disable checking for their functions.
-- [ ] continue fuzzing the compiler, analyzer, runtime, standard library, LSP, build tools and generated artifacts, including analyzer properties, memory-limit edges, compiler image mutation and long-running LSP memory use; fix discovered bugs and performance regressions. Current coverage includes malformed parser inputs, source immutability across runtime compilation, allocation/GC leak deltas, configured-memory growth, and available native, microcore, JavaScript and WebAssembly execution hosts.
-- [ ] after the compiler namespace and fuzzing work, add more general functionality to the standard library.
-- [ ] implement `include actor;` as a library that injects actor syntax into the compiler through the generic include-time extension interface: `actor` declarations in place of `struct`, implicit `this`, and generic `Actor<I,O>` input/output types. Provide asynchronous parallel execution with independent state and multiple instances; keep actor-specific code out of `compiler.zc` and every file it includes or reads by default, and cover syntax activation, execution, messaging and type safety with tests.
-- [ ] document the public standard-library APIs with concise descriptions of behavior, parameters, ownership and return values where applicable; update reference and learning entries, add executable examples and record implemented changes in history; keep prose lowercase and verify docs appear in hovers.
+- [x] give core built-ins and every other toolchain module their own namespace and require an explicit include to access qualified exports: `include core;` enables `core.name`, with the same rule for all other modules. remove implicit toolchain imports, migrate maintained sources and generated code, and verify missing-include diagnostics, completions, hovers and navigation before expanding the standard library.
+- [x] add a generic include-time syntax-extension interface so imported libraries can extend compiler parsing and lowering without module-specific compiler code; keep all extension hooks generic and inactive unless the corresponding library is included.
+- [x] implement `include actor;` as a library that injects actor syntax into the compiler through the generic include-time extension interface: `actor` declarations in place of `struct`, implicit `this`, and generic `Actor<I,O>` input/output types. Provide asynchronous parallel execution with independent state and multiple instances; keep actor-specific code out of `compiler.zc` and every file it includes or reads by default, and cover syntax activation, execution, messaging and type safety with tests.
+- [x] implement and integrate `src/lib/icon.zc` with structured runtime syntax transformations, template matching, execution inspection and stepping, with explicit contracts and comprehensive tests.
+- [x] change the producer of the genome header (`build/core/genome.h`) to emit a c translation unit that embeds the compiler, core and runtime zc sources with a `#embed` directive instead of concatenating them into a 1.5 mb generated header; keep the `.zc` sources as the single source of truth and extend the fixpoint check in `make genome` so it still verifies the emitted genome without materializing a header at all.
+- [x] close the two ownership completeness limits that stop the compiler compiling itself, so `make genome` completes from a clean checkout: allow an owned value held in a local to move into another local when the destination's previous owner is released in the same statement list, and allow a global to hold a bounded borrow of a local so an output stream can be redirected at a scratch buffer without a module-level variable. also give `rt.code_blocks = m*block;` a supported spelling and fix the `only a named owned object can be recast` diagnostic, which does not describe the real constraint. written up in `docs/BOOTSTRAP-OWNERSHIP.md`, which also records a verified partial fix that removes five of the eight current errors.
+- [x] bring documentation, examples, learn entries, history notes and test fixtures in line with the include and namespace format and the other language changes made alongside it: qualify runtime built-ins as `rt.put_s`, `rt.put_n`, `rt.put_c`, `rt.eof` and `rt.get_c`, require the explicit `include` each module needs, and remove the remaining bare builtin names so every shipped sample, every documented snippet and every expected-output fixture compiles and runs against the current compiler. the learn guide and `README.md` snippets are checked by the suite, so they are the gate, but the prose and the non-exercised samples are not.
+- [x] add accept, reject and regression coverage for the actor and icon libraries once each is finished: for actors, syntax activation through the include-time extension, spawn/recv/send across input and output types, multiple instances of one actor, parallel execution, implicit `this`, and confirmation that no actor code is reachable from the compiler or anything it reads by default; for icon, find/replace over real syntax, undeclaring names, changing types, adding and rewriting blocks, evaluating parts of an expression, and stepping execution while reading locals and globals, including the failure cases for each.
+
+## open, easiest first
+
+every item still to do, including the ones added after the list above. sorted
+by how hard each is to implement, so the large language features come last.
+the final full suite stays at the very end whatever its size.
+
+- [ ] remove temporary markdown files: decide on `TASKLIST.md` (a record of an earlier session's requests), `docs/BOOTSTRAP-OWNERSHIP.md` (its problem is resolved) and `docs/design/handoff.md`, keeping anything still referenced from `README.md` or `ONBOARD.md`.
+- [ ] verify every command in `ONBOARD.md` from a clean checkout and fix the ones that drifted.
+- [ ] add `string` as a built-in alias of `char*`, in types, hovers and completions.
+- [ ] untyped constants inside structs: `struct Text { const MAX = 24; }`, reached as `std.Text.MAX`, with the same rules as a local or top-level `const k = 5;`.
+- [ ] typo suggestions for field and method names: `p.lenght` and `std.Text.itao` suggest the closest member, with the language server's change-to quick fix.
+- [ ] a `make parity` runner that compiles the zc0-compatible programs (and the genome sources) with zc0 and with the self-hosted compiler, runs both images and compares output, so the two front ends can't disagree silently again (the `&&`/`||` precedence bug).
+- [ ] c typedefs: `typedef T name;` declares a type alias, including pointer, array and function types, usable everywhere a type is, shown in hovers.
+- [ ] continue removing `unchecked` from the remaining runtime boundaries by teaching the analyzer the missing ownership and drop contracts; document any irreducible low-level escapes. the compiler, standard library and lsp no longer disable checking for their functions. status: `copy_w`, `fill_w`, `cons`, `triple`, `dnew`, `dgrow` and `dpush` compile checked after small rewrites (uncommitted in `src/runtime/rt.zc`, bootstrap reaches its fixpoint, runtime tests not yet run). `free`, `recycle`, `recycle_leaf` and `gc` are the allocator and collector that the analyzer's own cleanup calls, so they stay unchecked and need to be documented as the irreducible escapes. `src/lib/actor.zc` has about 20 more.
+- [ ] document the public standard-library apis with concise descriptions of behavior, parameters, ownership and return values where applicable; update reference and learning entries, add executable examples and record implemented changes in history; keep prose lowercase and verify docs appear in hovers.
 - [ ] revise diagnostics, comments and learning/reference prose using professional compiler documentation guidance, preserving lowercase and adding message regressions.
-- [ ] implement and integrate `src/lib/icon.zc` with structured runtime syntax transformations, template matching, execution inspection and stepping, with explicit contracts and comprehensive tests.
-- [ ] change the producer of the genome header (`build/core/genome.h`) to emit a c translation unit that embeds the compiler, core and runtime zc sources with a `#embed` directive instead of concatenating them into a 1.5 mb generated header; keep the `.zc` sources as the single source of truth and extend the fixpoint check in `make genome` so it still verifies the emitted genome without materializing a header at all.
-- [ ] close the two ownership completeness limits that stop the compiler compiling itself, so `make genome` completes from a clean checkout: allow an owned value held in a local to move into another local when the destination's previous owner is released in the same statement list, and allow a global to hold a bounded borrow of a local so an output stream can be redirected at a scratch buffer without a module-level variable. also give `rt.code_blocks = m*block;` a supported spelling and fix the `only a named owned object can be recast` diagnostic, which does not describe the real constraint. written up in `docs/BOOTSTRAP-OWNERSHIP.md`, which also records a verified partial fix that removes five of the eight current errors.
-- [ ] bring documentation, examples, learn entries, history notes and test fixtures in line with the include and namespace format and the other language changes made alongside it: qualify runtime built-ins as `rt.put_s`, `rt.put_n`, `rt.put_c`, `rt.eof` and `rt.get_c`, require the explicit `include` each module needs, and remove the remaining bare builtin names so every shipped sample, every documented snippet and every expected-output fixture compiles and runs against the current compiler. the learn guide and `README.md` snippets are checked by the suite, so they are the gate, but the prose and the non-exercised samples are not.
-- [ ] add accept, reject and regression coverage for the actor and icon libraries once each is finished: for actors, syntax activation through the include-time extension, spawn/recv/send across input and output types, multiple instances of one actor, parallel execution, implicit `this`, and confirmation that no actor code is reachable from the compiler or anything it reads by default; for icon, find/replace over real syntax, undeclaring names, changing types, adding and rewriting blocks, evaluating parts of an expression, and stepping execution while reading locals and globals, including the failure cases for each.
+- [ ] `defer` statement: `defer expr;` or `defer { ... }` runs when the enclosing block ends, on every exit path (fall-through, `return`, `break`, `continue`), in reverse order of declaration, with the values its expressions name at the time the block ends. follows the c defer proposal (n3199 style) with ownership awareness: a deferred call that consumes an owner counts as its transfer, so the analyzer neither frees it twice nor reports it leaked.
+- [ ] test blocks: `test "name" { ... }` with `expect(cond)`, compiled only by `zy --test file.zc`, which runs each block and prints one line per test with the position of the first failed `expect`; skipped at parse time otherwise. built as a library through `run.syntax` and `run.statement_hook`, like actors.
+- [ ] bounds checking on by default for indexing heap pointers (checked against the block header's payload size) and typed arrays (`T[n]`, `T[?]`), stopping with the index, the length and the source line. a keyword `unbounded`, used like `unchecked` (function, block, or top-level for the rest of the unit), turns it off. `o3` implies `unbounded`, so o3 code never pays for bounds checks. constant indexes into fixed arrays are checked at compile time and emit nothing.
+- [ ] after the compiler namespace and fuzzing work, add more general functionality to the standard library.
+- [ ] struct destructors: a struct may declare `fn drop()`, which the compiler calls wherever it frees an owned value of that type (scope end, reassignment, `rt.free`), before the memory is released. use it for file descriptors in `std.Host` and processes in `actor.zc`. decide and document what happens when an owner with a `drop` passes into unchecked code.
+- [ ] runtime source positions: a line table per function (code offset to source position) stored in the image, behind a `lines on;` switch like `docs on;`. faults, failed bounds checks and a new `rt.trace()` print `file:line in function` for every frame on the interpreter, microcore and javascript vm; the jit and llvm backends map native addresses back to vm code.
+- [ ] borrow returns tied to an argument, with syntax that stays out of the way: a function can return a pointer into one of its parameters (`find`, `skip_space`, `first`), the caller's analyzer treats the result as a borrow of whatever was passed, and freeing or moving that argument while the result is live is an error. the callee is checked to return only borrows of that parameter. prefer inference from the body over annotation; when a spelling is needed, keep it to the parameter's name.
+- [ ] variadic arguments and `std.print`. variadics know their count, keep each argument's type, allow several packs per function when their element types differ (`void test(...int a, ...char b)`), and allow a mixed pack of any types (`...any args`). `...*any args` makes the call comma-free: `std.print("x = " name ", and they are " age " years old.\n");`. `std.print` is a global, javascript-like print that takes any number of arguments and formats each by its type (numbers, floats, strings, byte strings, pointers).
+- [ ] continue fuzzing the compiler, analyzer, runtime, standard library, lsp, build tools and generated artifacts, including analyzer properties, memory-limit edges, compiler image mutation and long-running lsp memory use; fix discovered bugs and performance regressions. current coverage includes malformed parser inputs, source immutability across runtime compilation, allocation/gc leak deltas, configured-memory growth, and available native, microcore, javascript and webassembly execution hosts.
+- [ ] keep improving the borrow checker: fewer annotations in ordinary code, clearer messages naming both the owner and the conflicting use, and new fixtures for each rule that changes.
+- [ ] run the full suite once everything above is done, fix what it finds, and only then tick this item.
+