writeonce/compiler/src/CODE-LOGIC.md

compiler/src — how woc is put together

Written 2026-08-14, when the front end grew the language surface that compiles docs/examples/log-watcher. The normative contracts it emits against are docs/plan/oop-vm/00-wob-format.md and 08-builtin-surface.md; the diagnostic codes are catalogued in 01-error-catalog.md.

The pipeline

lexer.ml   →  parser.ml  →  types.ml  →  gcinfer.ml  →  owner.ml   →  emit.ml  →  .wob
tokens        AST           symbols      traced set     move/drop     bytecode
                            typecheck      tables

bin/main.ml drives it: discover files (a directory is one program), parse each, collect declarations per file, check module edges, merge symbols, typecheck, run the owner pass per file, then emit one image from every unit. diag.ml accumulates every stage's diagnostics and sorts them by (file, line, col), so ordering never depends on discovery order. dump.ml renders the stable text dumps the golden tests diff; disasm.ml reads an image back.

Four things are worth knowing before editing any of it.

1. Two type derivers, deliberately

types.ml's confident_typ and emit.ml's ty_of_expr both answer "what type is this expression?", in different languages (Types.typ vs Ast.field_ty) and for different purposes: the first gates diagnostics, the second picks instructions (EQ vs EQS, a container's element kinds, whether a value is owned). They are kept in sync by hand, and both follow one rule: stay silent when underivable. confident_typ returns None; the emitter falls back to Int. That is why a check built on typecheck_expr's .typ (which reports Int for anything unresolved) produces false positives, and every new check should read confident_typ instead.

A third table pair follows the same discipline: Types.builtin_confident_ret and emit.ml's builtin_ret give each builtin's return type. An omission there is not a lost type — it is a leak, because the owner pass classifies a binding as owned from exactly that answer.

2. Contextual values need a destination

[], [a, b], {} and nil have no type of their own. They take it from, in order: a written let annotation, the field/parameter they are built into, the enclosing method's declared return type (fstate.f_ret), or — for a non-empty list — their own first element. With none of those, emission is a diagnostic, never guessed bytecode: a container's element kinds are its runtime drop plan, so a wrong guess leaks or double-frees. nil is the zero word for every ?T (the format doc's own rule), which is also why a comparison against nil must lower to EQ and never EQS.

3. The owner pass hands the emitter tables, not decisions

owner.ml computes moves, scope-end drops, branch-join drops and residual borrow guards, keyed by node id and label (rc sites are gone since iteration 7b — reference counting no longer exists; gcinfer.ml classifies each class owned/traced first, structurally via SCC over the class-reference graph plus demand promotion at escape sites, and Types.is_gc_class answers from that set). emit.ml looks them up by the same keys. When a construct has arms — switch, if, try — both files must agree on the label strings and on the arm ORDER (switch_lowering_order moves default last in both). A silent mismatch means a drop that never runs.

try's shape: the catch arm is an alternate flow joining the try arm, so analyze_try snapshots the entry state, walks the body, restores, walks the handler with e declared as an owned local, and then makes each arm drop what the other moved. The handler starts from the entry state on purpose — a trap can be raised after any prefix of the body, and claiming the body's moves happened would drop values the VM already released.

4. Statics, modules and the stdlib all arrive as Ident.member calls

A qualified call's head can be four things, resolved in this order: a value with a type (an ordinary method call), a class with a static method (Flock.held(x) — static_method), a reserved stdlib module (fs.stat(path) — Types.stdlib_members), or a use alias for a project module. Adding a fifth kind means extending that chain in both emit_call and ty_of_expr, and confident_typ for the diagnostic side.

The stdlib table is data: module, member, source arity, builtin id, return type, and the predeclared record whose class id gets appended as the call's last argument. json.encode/json.decode are the two exceptions with bespoke lowering — encode needs its argument's static kind, and decode has no type at all until an as names one, which is why json.decode(t) as T is one instruction and a bare json.decode(t) is an error.

Predeclared records

Error (a catch arm's error), Stat, TimeParts, Proc (stdlib results) are declared by types.ml, not by any source file. They join the merged symbol table only — one copy per file would read as a cross-file duplicate — and they enter the class table only when a program actually needs one, so images that predate the surface keep their exact class tables. Their field ORDER is the contract with the runtime, which writes those fields by index.

Emitting the class table (a trap to remember)

Field-name constants must be interned with every other constant, before the constant pool is serialized. Interning during class-table serialization appends constants the pool has already been written past: the image then references constants it does not contain, and the loader rejects every class. That bug cost a debugging round; the interning now happens beside class_name_k.

Register discipline in emit.ml

Locals live below f_nlocals, temporaries from f_temp upward, and a statement resets f_temp to f_nlocals. Any construct that writes into a dst which might itself be a temp (switch, try, a ctor, a container literal) must reserve dst before allocating more temps, or an arm-local let can be handed the same register and clobber a live value before its drop runs. emit_switch carries the comment explaining the ASan-confirmed leak that taught this.

Who owns a value nobody named

The drop tables (owner.ml) track bindings. Everything a statement builds and never binds is the emitter's problem, and the workload found six of them: an operand of a comparison (if parse_expr(s) == nil), an argument a callee only borrows, a container read's copy (c[i] is the one place expression whose register holds a copy, so it needs no second copy at a boundary and does need a drop), a loop's iterable, the record a projection reads a field of, and any of those escaped by a return from inside the statement that built them.

The soak (Task 6) widened the list with four more, all the same sentence: a !='s operands (its lowering is separate from =='s and missed the reap); an Int-typed interpolation segment ("${resp.status}" LOOKS like a place wrapped in Interp, but lowers to a fresh int_to_text — is_borrowed_value_t asks the type); the argument of json.encode (its bespoke lowering bypassed the stdlib-member drop); and a discarded expression statement (pop(lines); REMOVES the element — the caller owns what it then ignores). The finding tool was an arena size-class census plus a pointer trace, not ASan: an in-arena leak is invisible to LeakSanitizer, because the arena is one allocation.

The framework-v1 slice (2026-08-20) found the copy-side mirror of the Int-segment lesson: copy_place_text matched only bare Ident/Field/Index, so a Text-typed SINGLE-SEGMENT interpolation of a place (allow = "${r.method}" with r a loop borrow) passed the place's own register through a let/assignment boundary uncopied — the binding aliased the row's field and its overwrite freed it (release-build crash the arena hid from ASan). It now asks is_borrowed_value_t && not is_container_read, exactly drop_fresh_text's place test. The RETURN boundary had the same hole (return "${p.content}" handed the caller the part's own string — the multipart slice's arena corruption, two requests removed from the crash): emit_return's place test now sees through Interp the same way, while bare Ident/Field/Index behavior there is unchanged. Both flavors pinned by tests/corpus/run/interp-borrowed-field.

The iteration-5 strictness closeout (2026-08-20) added three seams worth knowing: pub(read) rides the field annotation list as a synthetic "pub_read" marker and is enforced in the Assign case that already resolves the target's class (WO-E219, current_self names the checking class — class-owned writes, sibling instances included); using extensions are a TYPECHECK-TIME rewrite — types.ml records (file, call-id) → fn name in using_rewrites and apply_using_rewrites rewrites recv.ext(a) to ext(recv, a) before owner/emit, which therefore carry zero using-awareness (collision with a real method is WO-E220 — never a silent win either way); #if is a token-stream filter at the end of Lexer.tokenize (Lexer.defines filled by woc -D, WO-E003 for misuse) — the parser never sees a directive.

Two rules the measurements imposed, both easy to get backwards:

• Never drop an argument register after a CALL. The callee's frame overlaps those registers (vm.c's window overlap), so after it returns they hold the callee's leftovers. Copy the value into a stash slot allocated below the call window before the call — call_window's temp_idx — and drop the stash.
• A statement-owned temporary must live in a local slot, not a temp. A statement that opens a scope resets f_temp to f_nlocals for its body, so a loop reuses the register; the end-of-statement DROP then releases a loop counter and the value leaks. f_stmt_drops holds locals; f_esc_drops is the same registers seen from a return.

Verifying a change

• just woc-test — unit assertions plus the golden suite (token/AST/owner/bc dumps and an OCaml re-implementation of the loader's validation). WOC_BLESS=1 regenerates goldens; read the diff before blessing, it is a contract change.
• just oop-e2e — the conformance corpus: run/ byte-exact stdout, compile-fail/ exact diagnostic code, trap/ exact trap code, gc/ exact collector trace, plus the single-binary smoke.
• ./compiler/_build/default/bin/woc --emit docs/examples/log-watcher -o /tmp/lw.wob — the acceptance workload. It must compile with zero diagnostics, and runtime/wovm /tmp/lw.wob watch <file> 2 1 must tail a live file and alert.

Float and Bytes (iteration 19)

• A digit run is an Int unless a fraction or an exponent follows. The lexer requires a DIGIT after . before committing to a Float, which is what keeps 0..10 a range rather than Float 0. followed by .10, and checks the exponent form (e, optional sign, at least one digit) before consuming anything, so 2eggs is still Int 2 then an ident. c in that branch is PEEKED, not consumed — the scan loop reads it, and adding it to the buffer first double-counts the leading digit (a real bug this went through).
• The no-mixing rule lives in the typechecker, not the emitter. The emitter picks the arithmetic opcode from whether EITHER side is a Float, so an unreported 1 + 2.5 would lower to integer ADD over f64 bits and produce a plausible wrong number with no diagnostic. check_numeric_mix reports the mix (WO-E201) off confident types only, keeping this file's stay-silent-when- underivable contract; % on a Float is rejected outright.
• Float/Bytes are builtin scalars but not Int-shaped. is_scalar_shaped excludes both by name alongside Text, or print_int(price) prints f64 bits as a huge integer and trunc(digest) reinterprets a pointer — the representation mismatch that predicate exists for.
• Bytes is a heap-owned scalar, so every ownership rule that named Text by string had to name a predicate instead. Types.is_heap_scalar is that predicate (owner.ml's four sites) and is_heap_kind is its emitter twin (kind 3 or 7, six sites). Miss one and a Bytes temp never drops, or a Bytes stored into a container aliases where a Text would copy.
• ?Float needs its own nil constant. nil_const_for picks it, and the bit pattern is emitted as a FLOAT pool constant because it is far outside OCaml's 63-bit native int — const_int cannot express it at all. Float constants dedupe on BITS, since 0.0 and -0.0 are =-equal in OCaml but must stay distinct, and NaN is not =-equal to itself.
• A Float order by key uses float_cmp, not op_lt. Raw-bit ordering puts negatives backwards (the sign bit makes -1.0 compare greater than 1.0 as an integer) and leaves NaN wherever the comparison sequence drops it. float-table-column in the corpus pins the ascending order that a bit compare gets wrong.
• Three parallel builtin tables must agree: Types.builtin_signatures (arity + arg kinds), Types.builtin_confident_ret and its emitter twin builtin_ret (a missing entry for a fresh-heap result is a LEAK, not just a lost type), and is_builtin_name plus the id mapping. The loader's arity table and the OCaml twin in compiler/test/runner.ml are a fourth and fifth.

Library kind and the internal/ boundary (iteration 17)

Every part of this lives in the driver (compiler/bin/main.ml). No lexer, parser, typechecker, VM, .wob, or GC change — internal is a path shape, not a keyword, and visibility is name resolution at compile time.

• kind is declared, not inferred. wo.toml's top-level kind is "program" (the default, so every existing manifest is byte-identical) or "library"; anything else is WO-E109 at exit 2. Go infers library-ness from the absence of main, which makes "you forgot the entry" and "this is a library" the same error — the whole reason to spend a manifest key here.
• Check mode reuses compile_image whole. The library branch resolves [deps], enforces the [runtime] constraint, runs the full pipeline, and discards the in-memory image; no target/ is created and no file is written. An entry-less image was already legal on that path (the --emit precedent), so "checks clean" means what "builds clean" means.
• manifest_parse was RELOCATED above build_mode so the no-entry error can read the manifest and say "this project declares itself a library" instead of only "no main". OCaml has no forward reference across top-level lets; types.ml solved the same problem the same way. woc build <dir> -o <out> never goes through manifest_build, so reading it inside build_mode is the only placement that covers the explicit-build path.
• WO-E108 is consumer-only, and keys on the FIRST segment naming a dep. That single condition is what makes the root project's own internal/ directories immune, and the dep-owned branch (which prefixes use internal to <dep>/internal) is untouched, so a library imports its own interior freely. The match is on a whole path SEGMENT — a module named internals is ordinary public surface.
• The offending use is left in the AST, not dropped. The collector's has-error path already stops emission; removing the use would replace one clear diagnostic with a cascade of unknown-type errors from the same file.
• Exit-code bands stay split: WO-E108 is a diagnostic through the normal collector path (exit 1); WO-E106/E107/E109 are manifest errors printed directly (exit 2).

Operator parity (iteration 36 — .wob v6)

• Precedence went INTO existing rungs, not new ones. |/^ joined parse_additive, &/<</>> joined parse_multiplicative — exactly Go's table (token.go Precedence), which exists to fix C's trap: x & mask == 0 groups the AND first here. The ladder doc in parser.ml carries the worked examples.
• not is a keyword at the unary level (Lua placement). not a == b groups (not a) == b. Chosen over Python's looser placement because the grammar's ordering is already anchored to Lua by name and because Bool-only typing turns almost every misread into a compile error. It lowers on the existing EQ against a zero constant — no new opcode, the same doctrine as and/or's JZ lowering.
• Compound assigns are parse-time sugar via rewind-and-reparse. x += e IS x = x + e, the documented contract — including an index expression evaluating twice, exactly as the written-out form would. The parser re-parses the place by resetting st.pos (no expression rung consumes a compound token, so the second parse stops where the first did); every re-parsed node draws a fresh id, so owner/emit see two honest reads, never one node in two roles. +=/-= had been lexed since haxe-parity Task 2 but no rule consumed them — dead tokens, x += 1 died as a generic WO-E101 until this iteration.
• Bitwise is Int-only on BOTH sides (WO-E201 family) — no F-twin exists, so a Float operand would have become a garbage word operation with no diagnostic. A LITERAL shift count outside 0..63 is WO-E223 at the operand's position (a negative literal arrives as Unary(Neg, IntLit) — both shapes are caught); a variable count is the VM's WO_T_SHIFT.
• Hex/binary literals accumulate in OCaml's native int (63-bit). A full-width 64-bit literal like 0xFFFFFFFFFFFFFFFF is out of reach — all-ones is spelled -1 (and complement is -1 ^ x; there is no ~). The 0x/0b prefix commits only when a real base digit follows, so 0xg stays Int 0 + Ident — a parse error at its own position, no new lexer diagnostic. _ separators are consumed only BETWEEN digits.

The raw text literal (iteration 37)

Multi-line markup used to be impossible to write: a statement ends at a newline, so a page was one h = h .. "<...>" statement per line, every attribute single-quoted to dodge \", and every piece of data wrapped in a hand-written esc() call. Backtick literals replace all three. Things worth knowing before editing them:

• It is a LEXER form, not a node. A backtick literal emits exactly the Token.Str (no holes) or Token.InterpStr (holes) a "..." string emits, so types.ml, owner.ml, emit.ml, the .wob format and the VM are all untouched — nothing downstream can tell the two spellings apart. That is the whole reason the feature is small. A design that introduced a Markup/Element AST variant instead would have had to teach five files about it.
• No escape processing at all inside. Quotes and backslashes are content, which is the point. The cost is that the form cannot express a literal backtick, a literal ${, or a literal {{ — those are written by concatenating an ordinary "..." string with ... One greppable door beats inventing an escape character for the one form whose selling point is not having any. (docs/examples/site/content.wo keeps two code_block samples as escaped "..." strings for exactly this reason: they contain \${.)
• The margin is stripped at LEX time, so the constant pool holds the dedented text and there is no runtime cost. Java's text-block rule: one newline right after the opening backtick is dropped, the smallest leading whitespace run across non-blank lines is removed from every line, and a whitespace-only closing line loses its whitespace but keeps its newline. A literal with no newline is left alone — eating the leading spaces of ` hi` would be a surprise, not a service. The measuring pass runs over a SHADOW string where each hole is one non-whitespace sentinel byte, so {{ x }} counts as indent 4 and as a non-blank line.
• {{ e }} desugars to esc(${e}), resolved by ordinary name lookup. desugar_interp in parser.ml builds a Call on an Ident "esc" — precisely what a developer wrote by hand before. The compiler learns nothing about HTML, esc stays writeonce-view's ordinary pub fn, a typo'd field inside the hole is a normal name/type error, and a locally defined esc shadows deliberately (a custom escaper is a feature). ${ } inside the same literal stays raw — that is the greppable door for markup you built yourself. The one place the desugar leaks: with no esc in scope the program fails on a name it never typed, so emit.ml's WO-E403 message carries a hint for that one name.
• {{ is special ONLY inside a backtick literal. Inside "..." it is still two braces, so CSS and JS text in existing samples lexes byte-identically.
• WO-E005 closed a real hole. The string scanner's catch-all used to append a raw newline like any other byte, so a forgotten closing quote silently swallowed the rest of the file with no diagnostic. Now the scan stops at the newline WITHOUT consuming it — the Newline token still terminates the statement, so recovery costs one line instead of the file. The rt-parity silence for a plain unterminated string with no newline is untouched, and runner.ml still pins it.
• The .. line continuation stays. A line ending in .. still swallows its newline. Raw literals took over the multi-line-markup job that motivated it, but it remains the general way to spread a long concatenation over several lines and has its own corpus fixture.