path: root/TASKLIST.md

# TASKLIST — "Review and polish project code"

Complete inventory of every request made by the user in codex session
`01a12a7c-8c55-7873-a0ae-da32c723ce8c` (2026-10-11 → 2026-10-14, workspace
`~/Documents/Playground/tinyvm`).

Each item gives **the request in summary** followed by **the user's exact
message, verbatim** in a blockquote. Section 14 holds the complete raw
transcript with nothing removed.

---

## Follow-up: found after that session

Not part of the session transcript. These came out of the `src/` and history
cleanup that followed, and they are now blocking work.

### `make` cannot bootstrap from a clean checkout

**Written up in [`docs/BOOTSTRAP-OWNERSHIP.md`](docs/BOOTSTRAP-OWNERSHIP.md)**,
linked from `docs/BORROW.md`, with a TODO entry. Reproduce with
`bash src/tools/bootstrap-check.sh`.

The second bootstrap stage runs the lifetime checker over the compiler's own
source and reports 8 errors, so `bin/mkgenome` reads the diagnostics as if they
were an image:

```
mkgenome: input is not a genome for this map
```

Two ownership completeness limits are responsible:

1. **No move between two locals.** Every accepted move originates at a call
   (`m*rt.new(...)`, `m*inc_open(...)`, `chk_resize(...)`). An owned value held
   in a local can be disposed with `d*`, but cannot be handed to another local,
   and cannot replace one. The documented `rt.free(buffer); buffer =
   replacement;` rule only fires when the replacement comes from a call.
2. **A local cannot be lent to a global.** Redirecting the output stream at a
   scratch buffer is a borrow, but every spelling is a transfer, so the buffer
   must live at module scope — which costs reentrancy safety.

Neither limit accepts an unsafe program; both refuse correct ones. So it is a
completeness gap, not a soundness bug. A verified partial fix (promoting the
scratch buffer to a module global, the existing `sgb` idiom) removes 5 of the
8 errors.

Also found along the way: `lookup_raw` compared against `K_VAR`, a constant that
was never declared, so `make genome` could not run at all before that.

---

## 0. Standing instructions (apply to everything)

### Commands must be single-line

> When writing commands for the user, never write them as multi-line (with
> backslashes)

(from `AGENTS.md` injected into the session)

### Delegate mechanical work to subagents

> if you require busywork that you consider repetitive, easy to complete, but not
> suitable for a bash run, use a 6-luna subagent to do so.

### Small test intervals, not the full suite

> also, please run tests in small intervals. don't run the full suite repeatedly
> as it takes a good couple minutes

### Don't stop until done

> don't stop until the todo list is done.

> continue and don't stop

(repeatedly set and re-set as the session goal)

### Keep `TODO.md` current

> write your tasks to a TODO.md file

> make sure to add these to the todo file.

> add these to tasks and todo.md:

> don't forget to tick off tasks that you complete in TODO.md.

> don't forget to update the todo.md.

> re-order the todo file based on the order of tasks that you'll complete.

> did you update todo?

> ummm... if it's updated, why are there still headers... and, why aren't the
> crossed off tasks all at the start, since they've been implemented already? do
> you understand how sorting works?

> add these to todo.md

> update todo.md

> also, add a hint for when a function argument is never used in the body. add to
> todo.md

> also add a --help to the compiler, lsp, etc. put in todo

### Comment and doc style

> the comments and docs shouldnt have uppercase :( follow the writing style of the
> older comments

> keep the lowercase, just remove the informal ai slop and replace it with
> professional compiler docs and guidance prose

---

## 1. Code review, bugs, and polish

### Read the code first

> read the code and familiarize yourself.

### Find bugs and optimizations

> - find bugs and areas for optimizations.

### Clean up phrasing and dirty references

> - clean up the phrasing, there are leftover dirty references such as "task X"
> in the documentation and code.

### Consistent comment style

> - make the commenting style consistent, and avoid connecting comments to
> unrelated variables.

### Polish the learning documents

> - polish the learning documents and ensure they're clear, direct, properly
> sectioned, and easy to understand.

### Fix the hover-renders-as-plain-text bug

> - make sure this bug is fixed: hovering over something in vscode renders it as
> plain text, rather than formatted markdown and code. this was claimed to have
> been solved in the latest changes, but it's not a guarantee, so i need you to
> look at it again.

---

## 2. Memory limits, build, and run

### Dynamic memory limits, adjustable at build time and run time

> - ensure all memory map limits are dynamic and can be adjusted both at build
> time and also run time.

### Clarification: tables and stacks must grow too

> **Grow tables and stacks too** — for runtime-adjustable limits, should running
> programs be able to grow individual compiler tables and stacks, or is
> configurable total VM/heap memory at startup plus heap growth sufficient?
> Changing every region during execution requires replacing the genome's
> fixed-address layout.

### Unify Windows run files; add a Linux script

> - unify the windows run files into one interactive batch file.
> - create a similar shell script for linux.

### Remove CEILINGS.md

> - remove the CEILINGS.md file if it's not needed.

---

## 3. Project layout

> - the parent dir is a bit cluttered again, move source files into subdirs of
> src/, tests under subdirs of tests, docs and designs into a docs/, and so on.

> - run all core source files one by one through the lsp, and catch their errors.
> try to replicate an editor's context. i currently get errors in src/compiler.zc,
> for example.

> have you passed your own code into the lsp???

---

## 4. LSP / VS Code features

### Type hover text (built-ins mandatory)

> - add hover text for variable types, including arrays and structs and others.
> built-in type hover texts are mandatory

### `/**/` comments contribute to documentation

> - /**/ comments should contribute to documentation as well. they're very useful
> for defining comments for individual variables and arguments and the likes, in
> a multi-variable line or expression.

### Inferred types in hover

> - inferred types for untyped variables, function returns and arguments and
> other spots should be shown in hover previews in vscode.

### Hover value tips

> - add variable value tips when hovering. if a value is known at hover time (aka
> constants or variables assigned to literals, hovered on a section before they're
> modified to a non-literal), display it in the hint.

### Comment-to-variable association bugs

> - i still see sections starting with `--- header ---` (number of dashes can
> vary) or comments that are unrelated to the variable/function that comes after
> them but related to the section, with no new line in between, so they get marked
> as the hint of that variable, which is confusing and inaccurate. fix that. i
> also see comments coming after a variable, which are not detected and hinted
> properly by the lsp. either put those comments before the variable, or make the
> compiler recognize them and classify them as hints. a good example of this
> phenomenon starts at line 221 in compiler.zc.

### Code error detection too slow

> add task
> - code error detection is too slow. add streaming and context cancellation, to
> immediately halt old requests when there is a code change.

### Jump to definition / references, cross-file

> - add jump to definition / references support to the lsp. support cross-file
> references and jumps as well.

### Pretty-printer / formatter (lowest priority)

> - add a pretty-printer/formatter, close to how clang-format works. this is a
> minimum priority task and goes at the end of the todo list. even if all other
> tasks are completed, implementing this task is unnecessary.

### Quick fix support

> - add quick fix support, including automatically importing the relevant library
> and whatnot

### Namespace suggestions

> - add namespace suggestions too. `rt.` should bring up the fns under rt
> namesapce

### Hover for `include name;`

> - add hover info for the library name in `include name;`

### Lifetime hover with explanations

> - add inferred and described lifetimes to hover informations, with their
> explanations. also include hints such as "this variable is passed up on line X or
> passed down on line Y"

### Cross-file F12 on `s_to_n`

> - running f12 on s_to_n says no definition and does NOT bring up rt.zc

### Recursive type inference

> - add recursive inference. eg: in lists.zc, mklist knows cap is an int. then
> mklist is called with n in squares, so n is an int too. and squares returns l,
> and l is the retval of mklist. we know that's a word, so that's what's inferred
> as the ret type of squares too.

### Variable declaration hover must show the type

The user pasted a brainfuck compiler to demonstrate that it uses `put_s`,
`put_n`, and `evals` without any `include` and gets no errors:

```zc
// a brainfuck compiler. it turns a brainfuck program into zc source, hands
// that to the compiler that's sitting in memory, and runs the result, which on
// arm64 means native code. runs of + - < > fold into one statement each.
// give it a program after a backtick, or it runs the hello world below.
let out[30000], n, depth;
void emit(s) { let i = 0; while (s[i]) { out[n] = s[i]; n++; i++; } return; }
void emitn(int v) { if (v >= 10) emitn(v / 10); out[n] = '0' + v % 10; n++; return; }
// how many times does c repeat from s[i]
int run(s, int i, int c) { int k = 0; while (s[i + k] == c) k++; return k; }

fn translate(s) {
	int i = 0, k;
	n = 0; depth = 0;
	emit("let t[30000], p = 0;\n");
	while (s[i]) {
		switch (s[i]) {
		case '+', '-':
			k = run(s, i, s[i]);
			emit("t[p] = (t[p] "); emit(s[i] == '+' ? "+ " : "- "); emitn(k); emit(") & 255;\n");
			i = i + k; continue;
		case '>', '<':
			k = run(s, i, s[i]);
			emit("p "); emit(s[i] == '>' ? "+= " : "-= "); emitn(k); emit(";\n");
			i = i + k; continue;
		case '[': emit("while (t[p]) {\n"); depth++;
		case ']': emit("}\n"); depth--;
		case '.': emit("put_c(t[p]);\n");
		case ',': emit("t[p] = eof() ? 0 : get_c() & 255;\n");
		}
		i++;
	}
	emit("return 0;\n");
	out[n] = 0;
	return depth;
}
let hello = "++++++++[>++++[>++>+++>+++>+<<<<-]>+>+>->>+[<]<-]>>.>---.+++++++..+++.>>.<-.<.+++.------.--------.>>+.>++.";
let prog[20000];
fn main() {
	let src = hello, k = 0, lines = 0, i = 0;
	while (!eof() && k < 19999) { let c = get_c(); if (c != 10) { prog[k] = c; k++; } }
	prog[k] = 0;
	if (k) src = prog;
	if (translate(src)) { put_s("unbalanced brackets\n"); return 1; }
	while (out[i]) { if (out[i] == 10) lines++; i++; }
	put_s("compiled to "); put_n(lines); put_s(" lines of zc, running it:\n");
	evals(out);
	return 0;
}
```

> this doesnt use rt.put_s or compiler.evals (actually make the compiler
> namespace core, so it's core.evals) and doesn't even include core or rt. yet
> it has no errors???

and on the hover format itself:

> also wtf is this?
> ```
> let hello  // global; type char*
> ```
> hover info
> it's supposed to be
> ```
> (char*) let hello // global;
> ```
> !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! you have not implemented everything properly
> !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
> same with this
> ```
> let prog  // global; type word[20000]
> ```
> and many other places!! dude cmon!!! i asked for something and you didn't
> implement it fully!

---

## 5. Diagnostics / hints presentation

### Blue squiggly hints with per-file control

> - compiler hints should be displayed with those squiggly blue lines instead of
> tiny three dots. this can be turned back into the three dots at the start of the
> range with `hints small;` placed in the file (takes effect for lines below it).
> other values are `hints off;` which turns them off, and `hints on;` which turns
> them on into the blue squigglies (default)

### Magic-number hint escape hatch

> - add an escape hatch for magic number hints when there's a /**/ comment before
> it. so `return n + 0x40ff` gives a warning, whilst `return n + /* offset in
> memory */ 0x40ff` does not

> include the fact that an inline comment suppresses it

### Professional comment and hint prose

> make hints and comments more professional. when have you ever in your life seen
> clangd say "; a const says what it means"??? read actual compiler docs to know
> how to format documentation, comments and how to phrase things. keep the
> lowercase, just remove the informal ai slop and replace it with professional
> compiler docs and guidance prose

### Unused-argument hint

> also, add a hint for when a function argument is never used in the body. add to
> todo.md

### `_` as a discard name

> unused arguments, if they're named _, they can be discarded normally

> and there can be multiple _'s. they should also be usable in pattern matching
> and tagged enums

> and if a _ is used, that instead gets a warning

---

## 6. Naming / language semantics fixes

### Remove `scat`, rename builtins

> - please don't leave a function called scat in the code...

> - change puts to put_s, putn to put_n, scat to cat_s, and so on.

### Nested call returning `u`

> - when i write `puts(f(x))` when fn returns a u type, i get this error: `a new
> object can only go straight to a d parameter; bind it to a name first`. if it's
> intended, leave it be. otherwise, fix it.

### Global assignment from inside a function

> - assigning a value to global variable from inside a function requires that
> value to be m or u. once this assignment happens, the value is recasted
> automatically (can also be done manually) to u, and it is consumed immediately,
> meaning no other object can use it from that reference anymore. it can still be
> accessed from the global, though.

### Typed closure returns

> - typed return from closures, using `fn:type(args) { code }`. example: `let
> double = fn:int(int a) { return a * 2; }`

### `fixed` + `const` together

> - make fixed and const able to be used together

### String literals must never be `word`

> - string literals shouldnt be auto detected as a word when untyped. `let hello =
> b"hi";` is typed as word, which is incorrect and inaccurate.

> - in general, string literals, whether packed or not, must not be marked as
> word, ANYWHERE. find all occurrences of word in the code after you're done with
> removing them, and ensure none are referring to strings, either as input
> arguments, or variables, or return types.

### `case` indentation in the pretty printer

> - case should be on one indent more than switch, when pretty printing

### Multi-include syntax

> add multi-include syntax `include rt, run, core;` for example. continue with
> your tasks

---

## 7. Namespaces and includes (major structural change)

> i still see sooo many unchecked's in just the compiler...

> also, the stuff under rt should go into their own respective rt namespace
> and lsp too
> generally just everything in the toolchain should be in its own namespace. and
> require an explicit include to use them. like `include lsp;` or `include rt;`
> not just those, but the rest too. like builtin core functions should have an
> `include core;` and so on

> don't stop until the todo list is done.

> actually nvm, compiler is `run` instead of `core`. `core` is for the core
> itself

---

## 8. Analysis features

### Bounding + lifetime analysis

> - after everything else has been completed, add basic bounding+ilfetime analysis
> to detect array bounds and show warnings whenever the compiler is sure there's
> an OOB or UAF happening. also, hovering over an array or pointer should show its
> lifetime or size.

### BORROW.md plan

> - generally, i want the borrow checker and lifetime analyzer to be *less
> annoying* and *less intrusive* than rust's, whilst still being *more
> intelligent* than it. if you can achieve this, draft a plan in BORROW.md for me.

---

## 9. Libraries / stdlib

### 9.1 `icon.zc` — runtime self-modifying code

> spawn a subagent to write an std module in src/lib/ called icon.zc, which
> supports way more complex self-modifications for code. currently, the best
> we've got is a few functions to find literals. this new import `include icon;`
> will provide things such as `icon.find_replace(my_fn, ${ $int + $int}, ${ $int
> - $int }` and so on. it should be quite powerful, enough to mold and mix and
> match syntax. undeclare variables, change types, add new blocks, change
> expressions, calculate parts of an expression, step through code step by step
> and examine its locals and globals, all at run time, and all dynamically, from
> inside the language, using the help of the compiler.

> also the icon code is of subpar quality in some places (eg a variable that is
> never read), so relaunch the agent with 6.1 sol high to look through it
> and make the actor agent 6.1 sol high too

### 9.2 `actor` — actor semantics

> - subagent task: add a library called actor, which allows actor-like semantics,
> with async threads running in the background with separate contexts and internal
> state, so that you can spawn one: `let a = addTwo.spawn(); a.recv(fn (e) {
> putn(e); }); a.send(2); // prints 4` and whatnot. smalltalk or obj-c like
> semantics

> not just integer messages, actors can exchange any type. they get a generic
> with two types: one for input, one for output. `Actor<I,O>`

> also, isn't `this` implicit? if not, make it implicit and don't let people
> declare it as the first argument

> oh and btw, actors are async. they can run in parallel and there can be multiple
> of each instance. defining thems hould be syntax injected into the compiler at
> include time as immediate, including a keyword actor which is used in place of
> struct to declare an actor.

> important, the actor library should NOT be inside the compiler. it should
> INFLUENCE the compiler at INCLUDE TIME. it's not a "this include activates this
> syntax because the compiler has it bundled", it's a "this include activates this
> syntax because it's injected into the compiler's machinery at include time". if
> the compiler is lacking the extendability required for the task, then implement
> that inside the compiler to make it more flexible, instead of hardcoding actors
> into it. IMPORTANT: I DO NOT WANT TO SEE ANY ACTOR RELATED CODE IN compiler.zc
> OR ANY OTHER FILE THAT IT INCLUDES OR READS BY DEFAULT.

> update todo.md

### 9.3 Arrays as first-class

> - add support for push and pop and find and map and filter and other stuff to
> arrays

> - arrays should also be able to act like `x.push(4)` or `x.map(fn (e) { return
> e + 2 })`. this also comes with autocomplete support

### 9.4 Stdlib docs and documentation agent

> - add more docs to the stdlib using a subagent

> assign the polish docs agent to update the documentation, add new examples,
> update learn entries, nad history too.

---

## 10. CLI

> also add a --help to the compiler, lsp, etc. put in todo

---

## 11. Testing

### Write tests before doing the remaining work

> write tests, both ACCEPT tests and REJECT tests and regression tests, extensively
> for every unchecked item in the todo list, and only then should you start work,
> and to not stop until all those tests pass.

### Then extensive tests for the whole toolchain

> finish these tasks, and then write extensive tests for the lsp, compiler, and
> every other tool in the toolchain. it should not only conform FULLY to the specs
> and the todo requirements, but also be free of errors.

---

## 12. Additional todo items added later

> add task
> - code error detection is too slow. add streaming and context cancellation, to
> immediately halt old requests when there is a code change.

> add to todo
> - string literals shouldnt be auto detected as a word when untyped. `let hello =
> b"hi";` is typed as word, which is incorrect and inaccurate.
> - running f12 on s_to_n says no definition and does NOT bring up rt.zc
> - in general, string literals, whether packed or not, must not be marked as
> word, ANYWHERE. find all occurrences of word in the code after you're done with
> removing them, and ensure none are referring to strings, either as input
> arguments, or variables, or return types.

---

## 13. Process feedback and session management

> you have a background terminal running

> do some work yourself

> dude why do you keep not getting jack fucking shit done im crine

> oml bruh you did fuck all yourself all this time?? it's been two hours oml

> connection all good?

> continue working then :)

> progress update?

> continue!!!
> continue

> no. auto review failed DAYS AGO. now the usage limit is back. continue. and auto
> review is off, you're on full access.

> also

---

## 14. Grouped index (lookup)

| Area | Requests |
|---|---|
| Review & polish | find bugs, find optimizations, clean "task X" references, consistent comment style, polish learn docs |
| Hover bug | markdown/code hover renders as plain text — verify fixed |
| Memory/build | dynamic limits (build+runtime), grow tables & stacks, unify Windows batch file, Linux shell script, drop `CEILINGS.md` |
| TODO.md | maintain, tick off, reorder, completed-at-top, no leftover headers |
| Layout | `src/` subdirs, `tests/` subdirs, `docs/`; run every core source file through the LSP |
| LSP | type hovers (mandatory for built-ins), `/**/` doc comments, inferred types, value tips, comment-association bugs, `(char*) let hello // global;` format, streaming + cancellation, jump-to-def/refs cross-file, formatter (lowest priority), quick fixes + auto-import, namespace completion, hover for `include name;`, lifetime hover with explanations, array/pointer lifetime+size hover, F12 on `s_to_n` must open `rt.zc`, recursive inference |
| Hints | blue squigglies w/ `hints on/small/off`, magic-number suppression via `/**/`, unused-arg hint, `_` (multiple, pattern matching, tagged enums; warn on use), professional non-AI-slop phrasing |
| Renames | remove `scat`, `puts`→`put_s`, `putn`→`put_n`, `scat`→`cat_s` |
| Semantics | nested `u`-returning call, global assign from fn + recast to `u` + consume, string literals never `word` anywhere, `fixed`+`const` together, typed closures `fn:t(...)`, `case` indent under pretty printer, `include rt, run, core;` |
| Namespaces | `rt`, `lsp`, `run`, `core` namespaces + explicit includes everywhere; brainfuck sample must error without includes |
| Analysis | bounding + lifetime OOB/UAF warnings; `BORROW.md` plan (less intrusive than Rust, more intelligent) |
| Libs | `icon.zc` (runtime self-modification, subagent, 6.1 sol high review), `actor` (async, `Actor<I,O>`, implicit `this`, `actor` keyword injected at include time, **zero actor code in the compiler**), arrays `push/pop/find/map/filter` + method syntax + autocomplete, recursive inference, more stdlib docs |
| CLI | `--help` for compiler, LSP, etc. |
| Tests | ACCEPT + REJECT + regression for every unchecked todo item, written *before* the work; extensive LSP/compiler/toolchain tests afterward |
| Process | one-line commands, delegate busywork to 6-luna subagents, small test intervals, work it yourself, don't stop until done |
| **Post-session** | **bootstrap blocked: owned values can't move between locals, and locals can't be lent to globals — see `docs/BOOTSTRAP-OWNERSHIP.md`** |

---

## 15. Raw transcript — every user message, in order

Environment/context injections are marked. Session ran 2026-10-11T10:22 through
2026-10-14T03:00 (UTC timestamps as recorded).

---

**1.** `2026-10-11T10:28:39` — *environment injection (AGENTS.md + env context)*

> # AGENTS.md instructions
>
> <INSTRUCTIONS>
> When writing commands for the user, never write them as multi-line (with
> backslashes)
> </INSTRUCTIONS>
> <environment_context>
>   <cwd>/Users/moonflower/Documents/Playground/tinyvm</cwd>
>   <shell>zsh</shell>
>   <current_date>2026-10-11</current_date>
>   <timezone>Asia/Tehran</timezone>
>   <filesystem><workspace_roots><root>/Users/moonflower/Documents/Playground/tinyvm</root></workspace_roots><permission_profile type="managed">…</permission_profile></filesystem>
> </environment_context>

**2.** `2026-10-11T10:28:39`

> read the code and familiarize yourself.
> if you require busywork that you consider repetitive, easy to complete, but not
> suitable for a bash run, use a 6-luna subagent to do so.
> then, here are your tasks:
> - find bugs and areas for optimizations.
> - clean up the phrasing, there are leftover dirty references such as "task X" in
> the documentation and code.
> - make the commenting style consistent, and avoid connecting comments to
> unrelated variables.
> - polish the learning documents and ensure they're clear, direct, properly
> sectioned, and easy to understand.
> - make sure this bug is fixed: hovering over something in vscode renders it as
> plain text, rather than formatted markdown and code. this was claimed to have
> been solved in the latest changes, but it's not a guarantee, so i need you to
> look at it again.

**3.** `2026-10-11T10:31:36`

> another task:
> - ensure all memory map limits are dynamic and can be adjusted both at build
> time and also run time.
> - unify the windows run files into one interactive batch file.
> - create a similar shell script for linux.
> - remove the CEILINGS.md file if it's not needed.
>
> write your tasks to a TODO.md file

**4.** `2026-10-11T10:32:11` — *answer to a question prompt*

> **Grow tables and stacks too**

**5.** `2026-10-11T10:44:16`

> the comments and docs shouldnt have uppercase :( follow the writing style of the
> older comments

**6.** `2026-10-11T10:49:54`

> continue

**7.** `2026-10-11T10:53:32`

> also, please run tests in small intervals. don't run the full suite repeatedly as
> it takes a good couple minutes

**8.** `2026-10-11T10:58:26`

> - add hover text for variable types, including arrays and structs and others.
> built-in type hover texts are mandatory

**9.** `2026-10-11T10:59:26`

> - /**/ comments should contribute to documentation as well. they're very useful
> for defining comments for individual variables and arguments and the likes, in
> a multi-variable line or expression.

**10.** `2026-10-11T11:02:09`

> - inferred types for untyped variables, function returns and arguments and other
> spots should be shown in hover previews in vscode.

**11.** `2026-10-11T11:03:42`

> make sure to add these to the todo file.

**12.** `2026-10-11T11:08:17`

> - after everything else has been completed, add basic bounding+ilfetime analysis
> to detect array bounds and show warnings whenever the compiler is sure there's an
> OOB or UAF happening. also, hovering over an array or pointer should show its
> lifetime or size.

**13.** `2026-10-11T11:15:23`

> - please don't leave a function called scat in the code...
> - change puts to put_s, putn to put_n, scat to cat_s, and so on.

**14.** `2026-10-11T11:18:11`

> - when i write `puts(f(x))` when fn returns a u type, i get this error: `a new
> object can only go straight to a d parameter; bind it to a name first`. if it's
> intended, leave it be. otherwise, fix it.

**15.** `2026-10-11T11:19:03`

> - generally, i want the borrow checker and lifetime analyzer to be *less
> annoying* and *less intrusive* than rust's, whilst still being *more
> intelligent* than it. if you can achieve this, draft a plan in BORROW.md for me.

**16.** `2026-10-11T11:29:54`

> connection all good?

**17.** `2026-10-11T11:30:13`

> continue working then :)

**18.** `2026-10-11T12:12:39`

> add these to tasks and todo.md:
> - the parent dir is a bit cluttered again, move source files into subdirs of
> src/, tests under subdirs of tests, docs and designs into a docs/, and so on.
> - run all core source files one by one through the lsp, and catch their errors.
> try to replicate an editor's context. i currently get errors in src/compiler.zc,
> for example.

**19.** `2026-10-11T12:47:16`

> don't forget to tick off tasks that you complete in TODO.md.

**20.** `2026-10-11T15:42:56`

> continue

**21.** `2026-10-11T16:20:41`

> don't forget to update the todo.md.

**22.** `2026-10-11T16:28:52`

> re-order the todo file based on the order of tasks that you'll complete.

**23.** `2026-10-11T16:32:13`

> did you update todo?

**24.** `2026-10-11T16:33:07`

> ummm... if it's updated, why are there still headers... and, why aren't the
> crossed off tasks all at the start, since they've been implemented already? do
> you understand how sorting works?

**25.** `2026-10-11T16:57:02`

> continue

**26.** `2026-10-12T03:17:04` — *environment injection (date change, subagents)*

> continue

**27.** `2026-10-12T05:16:51`

> continue

**28.** `2026-10-12T05:27:11`

> 1. you have a background terminal running
> 2. add variable value tips when hovering. if a value is known at hover time (aka
> constants or variables assigned to literals, hovered on a section before they're
> modified to a non-literal), display it in the hint.

**29.** `2026-10-12T05:29:13`

> add task
> - code error detection is too slow. add streaming and context cancellation, to
> immediately halt old requests when there is a code change.

**30.** `2026-10-12T05:31:05`

> - i still see sections starting with `--- header ---` (number of dashes can
> vary) or comments that are unrelated to the variable/function that comes after
> them but related to the section, with no new line in between, so they get marked
> as the hint of that variable, which is confusing and inaccurate. fix that. i
> also see comments coming after a variable, which are not detected and hinted
> properly by the lsp. either put those comments before the variable, or make the
> compiler recognize them and classify them as hints. a good example of this
> phenomenon starts at line 221 in compiler.zc.

**31.** `2026-10-12T05:32:45`

> - add jump to definition / references support to the lsp. support cross-file
> references and jumps as well.

**32.** `2026-10-12T05:34:02`

> - add a pretty-printer/formatter, close to how clang-format works. this is a
> minimum priority task and goes at the end of the todo list. even if all other
> tasks are completed, implementing this task is unnecessary.

**33.** `2026-10-12T05:40:11`

> - assigning a value to global variable from inside a function requires that
> value to be m or u. once this assignment happens, the value is recasted
> automatically (can also be done manually) to u, and it is consumed immediately,
> meaning no other object can use it from that reference anymore. it can still be
> accessed from the global, though.

**34.** `2026-10-12T05:42:16`

> - typed return from closures, using `fn:type(args) { code }`. example: `let
> double = fn:int(int a) { return a * 2; }`

**35.** `2026-10-12T05:45:23`

> - compiler hints should be displayed with those squiggly blue lines instead of
> tiny three dots. this can be turned back into the three dots at the start of the
> range with `hints small;` placed in the file (takes effect for lines below it).
> other values are `hints off;` which turns them off, and `hints on;` which turns
> them on into the blue squigglies (default)

**36.** `2026-10-12T05:46:15`

> - add inferred and described lifetimes to hover informations, with their
> explanations. also include hints such as "this variable is passed up on line X or
> passed down on line Y"

**37.** `2026-10-12T05:46:24`

> add these to todo.md

**38.** `2026-10-13T06:33:41` — *environment injection (date change, subagents)*

**39.** `2026-10-13T06:33:41`

> i still see sooo many unchecked's in just the compiler...
> also, the stuff under rt should go into their own respective rt namespace
> and lsp too
> generally just everything in the toolchain should be in its own namespace. and
> require an explicit include to use them. like `include lsp;` or `include rt;`
> not just those, but the rest too. like builtin core functions should have an
> `include core;` and so on
> have you passed your own code into the lsp???
>
> ```
> // a brainfuck compiler. it turns a brainfuck program into zc source, hands
> // that to the compiler that's sitting in memory, and runs the result, which on
> // arm64 means native code. runs of + - < > fold into one statement each.
> // give it a program after a backtick, or it runs the hello world below.
> let out[30000], n, depth;
> void emit(s) { let i = 0; while (s[i]) { out[n] = s[i]; n++; i++; } return; }
> void emitn(int v) { if (v >= 10) emitn(v / 10); out[n] = '0' + v % 10; n++; return; }
> // how many times does c repeat from s[i]
> int run(s, int i, int c) { int k = 0; while (s[i + k] == c) k++; return k; }
>
> fn translate(s) {
> 	int i = 0, k;
> 	n = 0; depth = 0;
> 	emit("let t[30000], p = 0;\n");
> 	while (s[i]) {
> 		switch (s[i]) {
> 		case '+', '-':
> 			k = run(s, i, s[i]);
> 			emit("t[p] = (t[p] "); emit(s[i] == '+' ? "+ " : "- "); emitn(k); emit(") & 255;\n");
> 			i = i + k; continue;
> 		case '>', '<':
> 			k = run(s, i, s[i]);
> 			emit("p "); emit(s[i] == '>' ? "+= " : "-= "); emitn(k); emit(";\n");
> 			i = i + k; continue;
> 		case '[': emit("while (t[p]) {\n"); depth++;
> 		case ']': emit("}\n"); depth--;
> 		case '.': emit("put_c(t[p]);\n");
> 		case ',': emit("t[p] = eof() ? 0 : get_c() & 255;\n");
> 		}
> 		i++;
> 	}
> 	emit("return 0;\n");
> 	out[n] = 0;
> 	return depth;
> }
> let hello = "++++++++[>++++[>++>+++>+++>+<<<<-]>+>+>->>+[<]<-]>>.>---.+++++++..+++.>>.<-.<.+++.------.--------.>>+.>++.";
> let prog[20000];
> fn main() {
> 	let src = hello, k = 0, lines = 0, i = 0;
> 	while (!eof() && k < 19999) { let c = get_c(); if (c != 10) { prog[k] = c; k++; } }
> 	prog[k] = 0;
> 	if (k) src = prog;
> 	if (translate(src)) { put_s("unbalanced brackets\n"); return 1; }
> 	while (out[i]) { if (out[i] == 10) lines++; i++; }
> 	put_s("compiled to "); put_n(lines); put_s(" lines of zc, running it:\n");
> 	evals(out);
> 	return 0;
> }
> ```
>
> this doesnt use rt.put_s or compiler.evals (actually make the compiler
> namespace core, so it's core.evals) and doesn't even include core or rt. yet
> it has no errors???
> don't stop until the todo list is done.
> actually nvm, compiler is `run` instead of `core`. `core` is for the core
> itself
> also wtf is this?
> ```
> let hello  // global; type char*
> ```
> hover info
> it's supposed to be
> ```
> (char*) let hello // global;
> ```
> !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! you have not implemented everything properly
> !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
> same with this
> ```
> let prog  // global; type word[20000]
> ```
> and many other places!! dude cmon!!! i asked for something and you didn't
> implement it fully!
> also, add a hint for when a function argument is never used in the body. add to
> todo.md
> write tests, both ACCEPT tests and REJECT tests and regression tests, extensively
> for every unchecked item in the todo list, and only then should you start work,
> and to not stop until all those tests pass.
> add to todo
> - string literals shouldnt be auto detected as a word when untyped. `let hello =
> b"hi";` is typed as word, which is incorrect and inaccurate.
> - running f12 on s_to_n says no definition and does NOT bring up rt.zc
> - in general, string literals, whether packed or not, must not be marked as
> word, ANYWHERE. find all occurrences of word in the code after you're done with
> removing them, and ensure none are referring to strings, either as input
> arguments, or variables, or return types.

**40.** `2026-10-13T06:34:11`

> finish these tasks, and then write extensive tests for the lsp, compiler, and
> every other tool in the toolchain. it should not only conform FULLY to the specs
> and the todo requirements, but also be free of errors.

**41.** `2026-10-13T06:35:25` — *environment injection (full access enabled)*

**42.** `2026-10-13T06:35:25`

> no. auto review failed DAYS AGO. now the usage limit is back. continue. and auto
> review is off, you're on full access.

**43.** `2026-10-13T06:36:54`

> - add an escape hatch for magic number hints when there's a /**/ comment before
> it. so `return n + 0x40ff` gives a warning, whilst `return n + /* offset in
> memory */ 0x40ff` does not

**44.** `2026-10-13T06:42:08`

> include the fact that an inline comment suppresses it

**45.** `2026-10-13T06:42:11`

> also

**46.** `2026-10-13T06:43:28`

> make hints and comments more professional. when have you ever in your life seen
> clangd say "; a const says what it means"??? read actual compiler docs to know
> how to format documentation, comments and how to phrase things. keep the
> lowercase, just remove the informal ai slop and replace it with professional
> compiler docs and guidance prose

**47.** `2026-10-13T07:02:06`

> unused arguments, if they're named _, they can be discarded normally

**48.** `2026-10-13T07:05:27`

> and there can be multiple _'s. they should also be usable in pattern matching
> and tagged enums

**49.** `2026-10-13T07:05:45`

> and if a _ is used, that instead gets a warning

**50.** `2026-10-13T07:13:47`

> spawn a subagent to write an std module in src/lib/ called icon.zc, which
> supports way more complex self-modifications for code. currently, the best
> we've got is a few functions to find literals. this new import `include icon;`
> will provide things such as `icon.find_replace(my_fn, ${ $int + $int}, ${ $int
> - $int }` and so on. it should be quite powerful, enough to mold and mix and
> match syntax. undeclare variables, change types, add new blocks, change
> expressions, calculate parts of an expression, step through code step by step
> and examine its locals and globals, all at run time, and all dynamically, from
> inside the language, using the help of the compiler.

**51.** `2026-10-13T08:20:52`

> add multi-include syntax `include rt, run, core;` for example. continue with
> your tasks

**52.** `2026-10-13T08:26:25`

> continue

**53.** `2026-10-13T08:26:39` — *internal goal marker*

> User set the goal: "continue and don't stop"

**54.** `2026-10-13T09:12:02` — *internal goal marker: paused*

**55.** `2026-10-13T09:21:07`

> continue

**56.** `2026-10-13T09:38:22`

> progress update?

**57.** `2026-10-13T10:22:30`

> continue

**58.** `2026-10-13T10:37:58`

> continue

**59.** `2026-10-13T12:09:59` — *internal goal marker: active*

**60.** `2026-10-13T12:10:34`

> continue

**61.** `2026-10-13T12:17:33`

> - case should be on one indent more than switch, when pretty printing

**62.** `2026-10-13T12:18:20`

> - add quick fix support, including automatically importing the relevant library
> and whatnot

**63.** `2026-10-13T12:18:33`

> - add namespace suggestions too. `rt.` should bring up the fns under rt
> namesapce

**64.** `2026-10-13T12:20:15`

> - add more docs to the stdlib using a subagent

**65.** `2026-10-13T12:25:23`

> - add hover info for the library name in `include name;`

**66.** `2026-10-13T12:29:04`

> - add recursive inference. eg: in lists.zc, mklist knows cap is an int. then
> mklist is called with n in squares, so n is an int too. and squares returns l,
> and l is the retval of mklist. we know that's a word, so that's what's inferred
> as the ret type of squares too.

**67.** `2026-10-13T12:31:01`

> - make fixed and const able to be used together

**68.** `2026-10-13T12:32:14`

> - add support for push and pop and find and map and filter and other stuff to
> arrays

**69.** `2026-10-13T12:53:04`

> - arrays should also be able to act like `x.push(4)` or `x.map(fn (e) { return
> e + 2 })`. this also comes with autocomplete support

**70.** `2026-10-13T12:54:57`

> - subagent task: add a library called actor, which allows actor-like semantics,
> with async threads running in the background with separate contexts and internal
> state, so that you can spawn one: `let a = addTwo.spawn(); a.recv(fn (e) {
> putn(e); }); a.send(2); // prints 4` and whatnot. smalltalk or obj-c like
> semantics

**71.** `2026-10-13T13:33:03`

> not just integer messages, actors can exchange any type. they get a generic
> with two types: one for input, one for output. `Actor<I,O>`

**72.** `2026-10-13T13:34:02`

> also, isn't `this` implicit? if not, make it implicit and don't let people
> declare it as the first argument

**73.** `2026-10-13T13:35:17`

> oh and btw, actors are async. they can run in parallel and there can be multiple
> of each instance. defining thems hould be syntax injected into the compiler at
> include time as immediate, including a keyword actor which is used in place of
> struct to declare an actor.

**74.** `2026-10-13T13:37:15`

> important, the actor library should NOT be inside the compiler. it should
> INFLUENCE the compiler at INCLUDE TIME. it's not a "this include activates this
> syntax because the compiler has it bundled", it's a "this include activates this
> syntax because it's injected into the compiler's machinery at include time". if
> the compiler is lacking the extendability required for the task, then implement
> that inside the compiler to make it more flexible, instead of hardcoding actors
> into it. IMPORTANT: I DO NOT WANT TO SEE ANY ACTOR RELATED CODE IN compiler.zc
> OR ANY OTHER FILE THAT IT INCLUDES OR READS BY DEFAULT.

**75.** `2026-10-13T13:37:46`

> update todo.md

**76.** `2026-10-13T13:50:28`

> do some work yourself

**77.** `2026-10-13T13:51:39` — *internal goal marker: paused*

**78.** `2026-10-13T13:51:39`

> also the icon code is of subpar quality in some places (eg a variable that is
> never read), so relaunch the agent with 6.1 sol high to look through it
> and make the actor agent 6.1 sol high too

**79.** `2026-10-13T13:52:12` — *internal goal marker: active*

**80.** `2026-10-13T13:52:14`

> assign the polish docs agent to update the documentation, add new examples,
> update learn entries, nad history too.

**81.** `2026-10-13T14:20:14`

> continue

**82.** `2026-10-13T14:20:23`

> dude why do you keep not getting jack fucking shit done im crine

**83.** `2026-10-13T15:55:37`

> oml bruh you did fuck all yourself all this time?? it's been two hours oml

**84.** `2026-10-13T17:04:03`

> continue!!!

**85.** `2026-10-13T18:01:45`

> also add a --help to the compiler, lsp, etc. put in todo

**86.** `2026-10-14T02:57:56` — *environment injection (date change, subagents)*

**87.** `2026-10-14T02:57:56`

> continue

---

*End of transcript. 87 user turns recorded in the session (88 user-role messages
including the initial `AGENTS.md` injection).*