writeonce/docs/plan/oop-vm/08-builtin-surface.md

Milestone-1 source surface the emitter lowers — normative reference

What a .wo program may say and have woc produce bytecode for. The .wob format doc (00-wob-format.md) names the BUILTIN ids; this names their source spellings and the handful of rules that have no other home. Landed with the emitter (compiler/src/emit.ml, plan 3 task 1). Diagnostics referenced here are catalogued in 01-error-catalog.md.

Anything on this page is a contract for corpus fixtures and for every later sub-project's .wo code — not an emitter implementation detail.

Builtins

Containers and runtime services are free functions, never methods. Each maps to one BUILTIN id of the format doc.

source	.wob builtin	arity	meaning
now()	now	0	wall-clock milliseconds (Int)
print(t)	print	1	a Text, newline-terminated
print_int(n)	print_int	1	an Int, newline-terminated
words(t)	words	1	whitespace token count of a Text
multi_new()	multi_new	0	a fresh multi T — see the destination rule below
map_new()	map_new	0	a fresh map<K, V> — see the destination rule below
push(m, v)	multi_push	2	append to a multi
count(c)	count	1	length of a multi or a map
latest(m)	latest	1	last element of a multi (traps BOUNDS when empty)
get(c, k)	multi_get / map_get	2	element by index, or value by key (a missing key traps KEY)
set(m, k, v)	map_set	3	insert or replace in a map
has(m, k)	map_has	2	1/0
int_to_text(n)	int_to_text	1	decimal rendering of an Int, as a fresh owned Text — haxe-parity Task 2's one fenced VM addition, the type-directed half of string interpolation (below); also directly callable

get, set, push, count and has resolve on the container they are given, so one source name covers the multi and map ids the runtime keeps apart.

Sugar. c[i] is exactly get(c, i) and m[k] = v is exactly set(m, k, v). There is no element write into a multi — v1 has multi_push and multi_get and no element store — so m[i] = v on a multi is WO-E403.

Shadowing. A user-declared free fn of the same name always wins. A declared name is never silently replaced by a builtin.

push and @gc elements. push(m, v)'s value argument is never a resolved callee parameter (push has no declared signature), so the owner pass's ordinary Take-gated transfer never reaches it; a @gc value pushed into a multi is special-cased in owner.ml's analyze_call (the value escapes into the container exactly like a ctor field, RC_INC included) specifically so a multi-mediated @gc cycle can be built and later collected (tests/corpus/gc/, plan 3 task 5). set(m, k, v) has no equivalent special case — a @gc key or value handed to set is not retained, so a map<_, SomeGcClass> (or a @gc-keyed map) built this way will under-count its element's refcount and the collector will free it while the map still points at it. Nothing in the corpus exercises this yet; treat it as an open gap, not a proven-safe pattern, until set gets the same fix push did.

A fresh container needs a destination of declared type

multi_new() and map_new() carry their element (and key/value) kinds as an instruction immediate, and those kinds are the container's drop plan at runtime (runtime/src/gc.c). They cannot be guessed: assuming SCALAR for a multi Item leaks every element, and for a map<Text, _> leaks every key. Milestone-1 let has no container type annotation — its optional annotation is a bare identifier — so a fresh container must be created where its type is declared:

class Store {
  items:   multi Item
  by_name: map<Text, Int>
}

fn main() {
  let s = Store { items: multi_new(), by_name: map_new() }   -- kinds from the fields
  push(s.items, Item { n: 7 })
  set(s.by_name, "seven", 7)
}

A bare let m = map_new() is WO-E403, reported at the creation site. The same rule applies to a take/mut parameter of declared container type, which is also a typed destination.

Calls

• Argument count must match the callee's parameter count (WO-E403). Nothing upstream checks arity — types.ml declares WO-E203 and never raises it — and a mismatched call reserves a register window the callee does not read, which the loader rejects outright.
• A method is called as receiver.method(args). When the receiver's declared type is an interface, the call is dispatched by vtable (ICALL); satisfaction is structural (same method name, same parameter count), Go-style, with no implements keyword.
• self occupies the callee's r0, so a method's argument count is 1 + parameters.

Modules (haxe-parity Task 1)

A .wo file's module is its directory — no manifest, no declared module name. Every file sharing a directory sees every other same- directory file's declarations unconditionally (Task 8's existing multi-file discovery, unchanged); a name declared in a different directory needs use to become visible at all, and even then only if it is marked pub.

• pub on a top-level class/type/interface/fn exports it outside its own module. Default is private-to-module — visible to every file in the same directory, invisible to every other module regardless of use (WO-E217 if referenced anyway). pub on a class/interface method, or the pub(read) field-accessor marker (Haxe's (default, null)), is a different, later feature — not this one.
• use fs (a bare, single-segment name) is a reserved stdlib namespace: exactly fs, proc, net, time, json, env, no others, and always stdlib even if a same-named project directory exists. A call through one (fs.stat(...)) typechecks as UNKNOWN-BUT-RESERVED — no E207/E225/arity check, since the six namespaces' members arrive in plan 9 — and is WO-E406 only if such a call survives all the way to emission; an unused use fs compiles clean (modulo WO-W202, below).
• use shared/util (slash-separated segments) is project- relative: it must name a directory this program's own discovery actually finds, or WO-E216. The alias a call site uses is always the path's last segment (util.fn(...), not shared.fn(...)).
• Resolution order for a bare (unqualified) name: this file's own module, unconditionally; then every used module's pub surface. If more than one used module exports the same pub name, that is WO-E218 — collisions diagnose rather than silently pick a winner. A qualified reference (alias.name(...)) skips straight to its named module; WO-E217 if name exists there but isn't pub.
• A use clause never referenced (bare or qualified) anywhere in its own file is WO-W202 — a warning, so it does not fail the build.

Program entry

The entry point is the zero-argument free fn main. A main that takes parameters is not an entry (the format's own rule is a zero-argument free fn), and wovm will report module has no entry method.

Operators with no dedicated opcode

Lowered by the emitter, not added to the format:

source	lowering
a % b	a - (a / b) * b — exact for the VM's truncating DIV, which traps on 0 and on INT64_MIN / -1, both correct for % too
a != b	(a == b) == 0
a > b, a >= b	LT / LE with the operands swapped
a == b on Text	EQS (content equality); EQ otherwise
a .. b	CONCAT — + is arithmetic only, never string addition
a and b	evaluate a; JZ past evaluating b (result stays a's value); else evaluate b into the same register (haxe-parity Task 2)
a or b	evaluate a; JZ + JMP past evaluating b when a is already true; else evaluate b (haxe-parity Task 2)

Not lowerable in milestone 1

Each is WO-E403 at the offending site, never invented bytecode:

• an element write into a multi (no element-store instruction);
• for over a map (v1 exposes no key enumeration);
• a name that is neither a local, a parameter, self, a declared fn, nor a builtin;
• a field or method on a type that is not a declared class — including a class named only inside multi T / ref T, which types.ml's unknown-type check (WO-E225) does not look inside.
• break/continue outside any loop (haxe-parity Task 2) — nothing upstream tracks loop nesting to reject it earlier, so the emitter's own "no legal jump target" gate is the only one.
• interpolating ("${expr}") a value that is neither Text nor Int (haxe-parity Task 2) — the brief's own scope; a class, multi, map, or other scalar has no defined textification here.

Small control surface (haxe-parity Task 2)

break/continue/do...while, const, and/or, and string interpolation — the haxe keyword verdict table's low-risk batch, added 2026-08-11.

• break/continue reuse the owner pass's own return-drop machinery, bounded to the nearest enclosing loop instead of the whole function: an owned value still alive in the loop body is dropped at the break/continue site itself, not left to leak (proven under ASan, tests/corpus/run/lang-break-owned-drop/). continue's actual jump target depends on loop shape — while's own condition check, for's increment step, or do...while's condition check — but the drop-set computation is identical either way.
• do { body } while cond — the body always runs at least once; lowered onto the same JZ/JMP pair while/for already use, just reordered.
• const NAME = <literal> (top-level, or bare — no static — class-level) is resolved entirely by parser.ml, before typecheck ever runs: every unshadowed reference is replaced by the literal it names, so nothing downstream (types/owner/emit) has any const-specific code at all. A local/parameter/self of the same name always shadows it. static const is Task 7's own syntax (static), not recognized here.
• and/or are real keywords (never &&/||), one precedence level below comparison (or loosest, then and, then comparison — so a == 1 and b == 2 needs no parens). Bool-typed operands only, no truthiness: a confidently-non-Bool operand is WO-E201. Short- circuit, lowered to compare-and-jump above — no new opcode.
• String interpolation ("${expr}") desugars at parse time to a .. (Concat) chain of text segments and embedded expressions; each embedded expression's textification is decided at emit time, once its type is known: Text passes through untouched, Int is wrapped in int_to_text (above), anything else is WO-E403 (see "Not lowerable in milestone 1"). \$ is a literal $ (so \${x} stays literal, never interpolates); a lone $ not followed by { is also literal, unconditionally.

?T

A nullable field stores exactly what T stores and spells nil as 0. The v1 format has no kind byte for it (field kinds run 0..5; the loader rejects 6), and it needs none: every per-kind drop plan already ignores a zero slot. ?T's field kind is therefore T's. Note the consequence for @gc: ?SomeGcClass is a GCREF field like any other, so it participates in refcounting and cycle detection normally.