code-native 2.18.3

/* Runtime support linked into every compiled program. Mirrors src/value.rs's
 * `Value` (the six JSON-shaped kinds) so a compiled program manipulates values
 * identically to the interpreter. Programs themselves are silent unless they
 * emit through a linked module (such as `terminal`, which writes straight to
 * stdout) — there is no bindings dump anymore, so nothing here renders values
 * for display; the only text this file produces is error messages on stderr.
 *
 * Every constructor writes into a caller-owned `CodeValue*` (rather than
 * returning by value) specifically to sidestep C-struct-by-value calling-
 * convention/ABI matching between this file and the LLVM IR that calls it.
 * codegen.rs passes pointers, and reads only three fields itself — `tag` at
 * 0, `number` at 8 and `boolean` after `str` (ticket 113, see its
 * `bool_offset`). See codegen.rs's VALUE_SIZE comment for the size contract.
 */
#define _GNU_SOURCE
#ifdef CODE_WASM
#include "wasm_shim.h"
#else
#include <dlfcn.h>
#include <fcntl.h>
#include <sys/mman.h>
#include <unistd.h>
#include <math.h>
#include <pthread.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <time.h>
#ifdef __GLIBC__
#include <malloc.h>
#endif
#endif

#include "code_abi.h"

/* A list's or object's count, slots and keys (`code_abi.h`). */
#define LEN(v) code_list_len(v)
#define ITEMS(v) code_list_items(v)
#define KEYS(v) code_list_keys(v)

/* See `code_most_live`. */
#define CODE_MOST_LIVE 64

/* `CodeTag`/`CodeValue`/`CODE_VALUE_SLOT_SIZE` now live in code_abi.h — it's
 * the native-module ABI, so runtime.c and every module built against it (see
 * that header) share one definition instead of two that could drift apart.
 *
 * Must match codegen.rs's VALUE_SIZE exactly. The assert below is the only
 * thing standing between a struct that outgrew the stride and codegen
 * silently reading the wrong slot, so keep it. */
_Static_assert(sizeof(CodeValue) <= CODE_VALUE_SLOT_SIZE,
               "CodeValue outgrew codegen.rs's VALUE_SIZE stride");

static CodeValue *slot_at(void *base, long long index) {
    return (CodeValue *)((char *)base + index * CODE_VALUE_SLOT_SIZE);
}

/* Mirrors what `code run` does on an interpreter `Err(String)`
 * (src/main.rs: `eprintln!("error: {e}"); ExitCode::FAILURE`) — operand
 * types are only known once the program is actually running, so a type
 * mismatch/division-by-zero can only ever be caught here, not at compile
 * time (unlike `verify_defined`'s undefined-variable check).
 *
 * Not `static`: a `.a` static module (see the "Native modules" section
 * below) links directly against the host's own copy of this runtime rather
 * than bringing its own, so it needs this externally visible to raise its
 * own fatal errors the same way `core`'s handlers do. */
_Noreturn void code_runtime_error(const char *message) {
#ifdef CODE_WASM
    code_host_error(message, (unsigned int)strlen(message));
    __builtin_trap();
#else
    fprintf(stderr, "error: %s\n", message);
    exit(1);
#endif
}

/* ---- The failure channel -------------------------------------------------
 *
 * `code_runtime_error` is `_Noreturn`: a helper that reaches it cannot tell
 * its caller anything, because there is no caller left. That is the whole
 * reason a `.code` program can never respond to its own runtime errors —
 * `10 / 0` ends the process from inside `code_div`, so no `if r is Exception`
 * downstream ever runs.
 *
 * This is the way back. A helper that cannot do its work calls `fail` and
 * returns normally; `code_failed` is left set, and the generated code checks
 * it after every call that can set it (codegen.rs's `check_failed`, which is
 * the only way those helpers are ever called — see `call_fallible`). The
 * failing operation therefore reaches a landing block the caller chose,
 * instead of taking the process with it.
 *
 * Phase 3 of docs/todo/errors-as-particles.md builds *only* the channel:
 * every landing block still ends in `code_abort_failure`, so behaviour is
 * byte-for-byte what it was. Phases 4 and 5 change what those blocks do —
 * write an Exception into the frame's `out` and branch to its exit — without
 * touching anything here.
 *
 * Deliberately NOT in code_abi.h. A `.so` module carries its own copy of this
 * runtime, so a flag set inside one would be set on the *module's* copy and
 * the host would never look at it — a silently swallowed failure. Modules
 * report trouble by returning `code_make_exception`, which needs no channel
 * because a return value already is one. */
int code_failed = 0;
/* Wide enough for the longest diagnostic anywhere in this file — a refusal
 * quoting a rooted module path is the one that sets the size. Sized to match
 * so that copying into it is not a truncation the compiler has to warn
 * about: a warning nobody can act on is noise, and noise is how the ones
 * that matter get missed. */
static char failure_message[1024];

/* Where the top-level statement now running came from, as the rendered
 * `--> file:line:col` block `span.rs`'s `location_block` produces — or NULL
 * when the program has no source to point into (a `Program` built by hand,
 * or an entry module the loader kept no text for).
 *
 * Written by generated code before each top-level statement (see codegen.rs)
 * and read only by `code_abort_failure`, which is the single place a
 * compiled program reports anything. That single place is what made this
 * cheap: before phases 3 and 4 an error could leave from any of `runtime.c`'s
 * `_Noreturn` helpers, and giving each of them a location would have meant
 * threading one through every call site in the generated IR. Now a failure
 * inside a handler is a value, so only the top level ever prints. */
const char *code_location = NULL;

/* First failure wins: with a check after every fallible call there is never a
 * second one to lose, but if that ever slips the original cause is the one
 * worth keeping. Copied into a fixed buffer rather than retained by pointer —
 * most callers build their message in a stack buffer. */
static void fail(const char *message) {
    if (!code_failed) {
        snprintf(failure_message, sizeof failure_message, "%s", message);
        code_failed = 1;
    }
}

/* What a landing block ends in at the *top level*, where there is no frame to
 * return into: a failure there ends the program with a non-zero status, which
 * is the same thing `return Exception` from the outermost call means. Routed
 * through `code_runtime_error` rather than duplicating its body so the wasm
 * build (which reports through `code_host_error` instead of stderr) keeps
 * working without this file knowing there are two ways to report. */
_Noreturn void code_abort_failure(void) {
    const char *message = code_failed ? failure_message : "unknown runtime error";
    if (code_location) {
        /* Joined in exactly the order `span::render` joins them, so the two
         * output modes produce byte-identical stderr. Heap rather than a
         * fixed buffer because the block quotes a source line of any length,
         * and a truncated location would be a silent divergence; the
         * allocation is never freed, which is correct for a function that
         * ends the process on its next statement. Not `heap_alloc`: this is
         * not a `CodeValue` block and must not move the leak counter. */
        size_t n = strlen(message) + 1 + strlen(code_location) + 1;
        char *located = malloc(n);
        if (located) {
            snprintf(located, n, "%s\n%s", message, code_location);
            code_runtime_error(located);
        }
    }
    code_runtime_error(message);
}

/* What a landing block ends in *inside a handler*: the frame's result becomes
 * an `Exception`, and the flag is cleared so the caller carries on. The
 * caller is under no obligation to look — a returned Exception is an ordinary
 * value, not a signal that keeps propagating (decided 2026-08-28: "C geriye
 * Exception döner, B bakmazsa kaldığı yerden devam"). Only the frame where
 * the failure actually happened unwinds.
 *
 * `source` is "core" because that is the language's own name for what runs a
 * program's own statements; a module's exceptions name the module instead. */
void code_take_failure(CodeValue *out) {
    code_make_exception(out, "core",
                        code_failed ? failure_message : "unknown runtime error", NULL);
    code_failed = 0;
}

/* ---- Reference counting -------------------------------------------------
 *
 * Compound values (non-empty arrays/objects, concatenated strings) live in
 * refcounted heap blocks; every `CodeValue` slot that names one owns exactly
 * one reference to it. Plain refcounting with NO cycle collector is enough
 * here, and always will be: a cycle can only be built by mutating an
 * already-constructed value to point back at something that reaches it, and
 * this language has no mutation at all — values are only ever built bottom
 * up and read afterwards (see memory `new-code-memory-management`).
 *
 * Every reference is created and destroyed inside this file, never by
 * codegen: each constructor below releases whatever its `out` slot held
 * before overwriting it, so a slot reused across loop iterations drops the
 * previous iteration's value automatically. That is what lets codegen.rs
 * hoist all of its allocas into the entry block and reuse them — see
 * `gen_loop`'s comment for why that in turn is what keeps a long loop's
 * memory bounded by program size rather than by iteration count.
 *
 * Codegen then releases every slot as the program's last act, so a finished
 * program owns nothing at all — not because the OS wouldn't reclaim it
 * anyway, but because "owns nothing" is a property `code_check_leaks` can
 * actually test. */

typedef struct {
    long long rc;
    /* A string block's byte length plus one in its low 58 bits, with a
     * capacity exponent in its high six bits (see `remember_text`), 0
     * until then (`text_length`). An object block's *shape*: the address of
     * the compiler's key list the object was built from, while its keys are
     * still exactly those (`code_object_literal`, ticket 122 stage B), 0
     * otherwise. Also what keeps the payload 16-byte aligned, like malloc's. */
    long long text_length;
} CodeHeader;

/* Large objects reuse the shape word for a tagged pointer. The compiler's
 * shape arrays are pointer-aligned, so their low bit is clear. Generated
 * shape checks simply take their generic path for an indexed object. The
 * last two header words and the module ABI remain exactly as before. */
typedef struct {
    long long shape;
    size_t mask;
    long long positions[]; /* position + 1; zero is an empty bucket */
} ObjectIndex;

static CodeHeader *header_of(const void *payload);

static ObjectIndex *object_index(const CodeValue *v) {
    if (!v->heap) return NULL;
    size_t word = (size_t)header_of(v->list)->text_length;
    return (word & 1) ? (ObjectIndex *)(word & ~(size_t)1) : NULL;
}

static long long object_shape(const CodeValue *v) {
    ObjectIndex *index = object_index(v);
    return index ? index->shape : header_of(v->list)->text_length;
}
#define SHAPE_OF(v) object_shape(v)

static void drop_object_index(const CodeValue *v);

/* Blocks currently allocated. Exists only so `code_check_leaks` can turn
 * "the refcounting is correct" into something a test can actually observe —
 * without it, a missing release and a correct release produce identical
 * program output.
 *
 * Bumped atomically because a module with a thread of its own allocates from
 * that thread — `code_emit_inbound` deep-copies the pushed particle on
 * whichever thread pushed it (see the "Inbound" section). A plain `++` there
 * is a data race, and a lost increment would make `CODE_CHECK_LEAKS` report
 * a leak that never happened, or miss one that did. Relaxed ordering is
 * enough: nothing is published through this counter, it is only read once at
 * exit, after every thread that could touch it has been shut out
 * (`code_native_close`). */
static long long live_blocks = 0;

#define code_blocks_add(n) (void)__atomic_add_fetch(&live_blocks, (n), __ATOMIC_RELAXED)
#define code_blocks_read() __atomic_load_n(&live_blocks, __ATOMIC_RELAXED)

static void *heap_alloc(size_t bytes) {
    CodeHeader *h = malloc(sizeof(CodeHeader) + bytes);
    if (!h) {
        code_runtime_error("out of memory");
    }
    h->rc = 1;
    h->text_length = 0;
    code_blocks_add(1);
    return (char *)h + sizeof(CodeHeader);
}

static CodeHeader *header_of(const void *payload) {
    return (CodeHeader *)((char *)payload - sizeof(CodeHeader));
}

static void drop_object_index(const CodeValue *v) {
    ObjectIndex *index = object_index(v);
    if (index) {
        header_of(v->list)->text_length = index->shape;
        free(index);
        code_blocks_add(-1);
    }
}

/* The single block a heap-owning value refers to. A list's or an object's
 * is its `CodeList`: the count, then the slots, then (an object's) its keys
 * — one allocation, so one refcount covers it all. */
static void *heap_block(const CodeValue *v) {
    switch (v->tag) {
    case CODE_STR:
        return (void *)v->str;
    case CODE_ARRAY:
    case CODE_OBJECT:
        return v->list;
    default:
        return NULL;
    }
}

/* A list block for `len` elements (left for the caller to fill), with
 * `extra` bytes after the slots: an object's key pointers and characters. */
static CodeList *list_alloc(long long len, size_t extra) {
    CodeList *list = heap_alloc(sizeof(CodeList) + (size_t)len * CODE_VALUE_SLOT_SIZE + extra);
    list->len = len;
    list->keys = NULL;
    return list;
}

void code_retain(const CodeValue *v) {
    if (v->heap) {
        header_of(heap_block(v))->rc++;
    }
}

/* ---- Iterative traversal --------------------------------------------------
 *
 * `code_release` and `code_values_equal` both walk a value's children, and
 * both used to recurse. Nesting depth is bounded only by a loop's iteration
 * count (`loop x over xs { a = [a] }`), not by how many brackets the source
 * contains, so one stack frame per level segfaults at around 131k deep — see
 * `tests/stress_deep_nesting.code`, and `value.rs` for the interpreter's
 * equivalents, which have the same shape for the same reason. Each keeps an
 * explicit work stack in heap memory instead.
 *
 * The stacks grow on demand and never shrink: neither can re-enter itself
 * now that they don't recurse, so one buffer each is enough — per thread.
 *
 * `code_release`'s is thread-local, because the release path is reachable
 * from a module's own thread: `code_emit_inbound` deep-copies onto a ring
 * that is full, and dropping the oldest entry releases it. A shared buffer
 * would then be walked by two threads at once, which is heap corruption
 * rather than a wrong answer. One buffer per thread costs a few KB for the
 * one or two threads a program has, and is never freed — the same bargain
 * the single shared one already made. `code_values_equal`'s stays plain
 * static: comparison is only ever reached from program code, which runs on
 * the program's own thread. */
#ifdef CODE_WASM
/* No threads in a wasm build, and the freestanding shim has no TLS. */
#define CODE_THREAD_LOCAL
#else
#define CODE_THREAD_LOCAL __thread
#endif

static void *grow(void *buf, size_t *cap, size_t needed, size_t item_size) {
    if (*cap >= needed) {
        return buf;
    }
    size_t next = *cap ? *cap * 2 : 64;
    while (next < needed) {
        next *= 2;
    }
    void *bigger = realloc(buf, next * item_size);
    if (!bigger) {
        code_runtime_error("out of memory");
    }
    *cap = next;
    return bigger;
}

static CODE_THREAD_LOCAL CodeValue *dead = NULL; /* values whose block is owed a free() */
static CODE_THREAD_LOCAL size_t dead_cap = 0;

/* Does NOT clear `v->heap` afterwards: every caller overwrites the slot
 * immediately, and leaving the field alone is what makes `code_copy`'s
 * self-assignment case (`x = x`) work — see its comment. */
void code_release(CodeValue *v) {
    if (!v->heap) {
        return;
    }
    if (--header_of(heap_block(v))->rc != 0) {
        return;
    }

    size_t len = 0;
    dead = grow(dead, &dead_cap, len + 1, sizeof(CodeValue));
    dead[len++] = *v;

    while (len > 0) {
        CodeValue current = dead[--len];
        /* Children are read out *before* the block is freed, and only the
         * ones whose own count reaches zero are queued. */
        if (current.tag == CODE_ARRAY || current.tag == CODE_OBJECT) {
            for (long long i = 0; i < LEN(&current); i++) {
                const CodeValue *child = slot_at(ITEMS(&current), i);
                if (child->heap && --header_of(heap_block(child))->rc == 0) {
                    dead = grow(dead, &dead_cap, len + 1, sizeof(CodeValue));
                    dead[len++] = *child;
                }
            }
        }
        if (current.tag == CODE_OBJECT) drop_object_index(&current);
        free(header_of(heap_block(&current)));
        code_blocks_add(-1);
    }
}

/* `code_release`, plus blanking the slot afterwards.
 *
 * Every other release is immediately followed by a write to the same slot,
 * which is why `code_release` can leave `heap` alone (see its comment). One
 * caller is different: a compiled statement releases its temporaries the
 * moment the statement ends, and then leaves those slots sitting there —
 * for the next execution of the same statement to overwrite, or for the
 * exit sweep to release again. Either would be a second release of a block
 * already freed. Blanking closes both: an all-zero slot is a payload-less
 * number, exactly what a slot looks like before its first write, so
 * releasing it again is a no-op and writing to it is safe.
 *
 * Not in `code_abi.h`, unlike the constructors: no module ever calls this.
 * It exists for `gen_stmt` in `src/codegen.rs`. */
void code_clear(CodeValue *v) {
    code_release(v);
    memset(v, 0, sizeof *v);
}

/* The last thing a compiled program does, after codegen has released every
 * slot it allocated. Silent unless CODE_CHECK_LEAKS is set, so it costs a
 * normal run one getenv and never changes its behaviour — the test harness
 * sets it for every fixture, which is what makes a lost reference a *failing
 * test* rather than an invisible difference. */
void code_check_leaks(void) {
    if (!getenv("CODE_CHECK_LEAKS")) {
        return;
    }
    long long leaked = code_blocks_read();
    if (leaked != 0) {
        char msg[96];
        snprintf(msg, sizeof msg, "%lld heap block(s) leaked", leaked);
        code_runtime_error(msg);
    }
}

void code_number(CodeValue *out, double n) {
    code_release(out);
    out->tag = CODE_NUMBER;
    out->heap = 0;
    out->number = n;
}

/* `s` is a string literal in the program's read-only data, so the value
 * borrows it rather than owning a block — only `code_add`'s concatenation
 * produces an owned string. */
void code_str(CodeValue *out, const char *s) {
    code_release(out);
    out->tag = CODE_STR;
    out->heap = 0;
    out->str = s;
}

void code_bool(CodeValue *out, int b) {
    code_release(out);
    out->tag = CODE_BOOL;
    out->heap = 0;
    out->boolean = b;
}

void code_null(CodeValue *out) {
    code_release(out);
    out->tag = CODE_NULL;
    out->heap = 0;
}

/* `items` is codegen's scratch buffer, not the array's storage: the elements
 * are copied (and retained) into a fresh heap block here, so the scratch
 * slots are free to be rewritten by the next iteration. An empty array owns
 * no block at all. */
void code_array(CodeValue *out, void *items, long long len) {
    CodeList *list = NULL;
    if (len > 0) {
        list = list_alloc(len, 0);
        void *buf = list + 1;
        for (long long i = 0; i < len; i++) {
            const CodeValue *src = slot_at(items, i);
            code_retain(src);
            *slot_at(buf, i) = *src;
        }
    }
    code_release(out);
    out->tag = CODE_ARRAY;
    out->heap = len > 0;
    out->list = list;
}

/* ---- Finding a field by its fingerprint (2026-10-11) ----------------------
 *
 * Every key an object holds is stored with a 32-bit hash of its characters
 * just before them — `[hash][characters\0]`, `keys[i]` still pointing at the
 * characters, so anything reading keys as C strings (a module, `code-native`)
 * sees nothing different. Finding a field then compares hashes and calls
 * `strcmp` only on a match, instead of once per key; a literal field name's
 * hash is worked out by the compiler (`codegen.rs`'s `key_hash`, the same
 * FNV-1a), and each `.field` read in the program also remembers the position
 * it found the field at last (`code_field_ref`).
 *
 * Only for objects this program's own runtime built — which is every object
 * the compiled code meets: a module's results and pushes are rebuilt here by
 * `code_object` on the way in. `find_field` itself stays a plain scan,
 * because the functions a module can call reach it, and a module carries its
 * own copy of this runtime, possibly older, whose objects have no hashes. */
#define KEY_HASH_BYTES 4

static unsigned int key_hash(const char *key) {
    unsigned int hash = 2166136261u;
    for (const unsigned char *c = (const unsigned char *)key; *c; c++) {
        hash = (hash ^ *c) * 16777619u;
    }
    return hash;
}

static unsigned int stored_hash(const char *key) {
    unsigned int hash;
    memcpy(&hash, key - KEY_HASH_BYTES, sizeof hash);
    return hash;
}

/* Where `key` (whose hash is `hash`) is in `obj`, or -1. */
static long long scan_field_position(const CodeValue *obj, const char *key, unsigned int hash) {
    /* Read once: `strcmp` is a call, and the count and keys sit behind the
     * value's block pointer. */
    long long len = LEN(obj);
    const char **keys = KEYS(obj);
    for (long long i = 0; i < len; i++) {
        if (stored_hash(keys[i]) == hash && strcmp(keys[i], key) == 0) {
            return i;
        }
    }
    return -1;
}

/* Lookup runs on the program thread. Inbound workers only copy and release
 * values, so they never build an index or touch these settings. */
static long long object_index_threshold = 0;
static int object_index_check;

static long long field_position(const CodeValue *obj, const char *key, unsigned int hash) {
    if (LEN(obj) <= 8 || !obj->heap) return scan_field_position(obj, key, hash);
    if (!object_index_threshold) {
        const char *setting = getenv("CODE_OBJECT_INDEX_THRESHOLD");
        object_index_threshold = setting ? strtol(setting, NULL, 10) : 16;
        if (object_index_threshold < 1) object_index_threshold = 16;
        object_index_check = getenv("CODE_OBJECT_INDEX_CHECK") != NULL;
    }
    if (LEN(obj) <= object_index_threshold) return scan_field_position(obj, key, hash);
    ObjectIndex *index = object_index(obj);
    const char **keys = KEYS(obj);
    if (!index) {
        size_t buckets = 32;
        while (buckets < (size_t)LEN(obj) * 2) buckets *= 2;
        index = calloc(1, sizeof *index + buckets * sizeof(long long));
        if (!index) code_runtime_error("out of memory");
        code_blocks_add(1);
        index->shape = SHAPE_OF(obj);
        index->mask = buckets - 1;
        for (long long i = 0; i < LEN(obj); i++) {
            size_t bucket = stored_hash(keys[i]) & index->mask;
            while (index->positions[bucket]) {
                long long at = index->positions[bucket] - 1;
                /* Duplicate keys retain the scan's first-match semantics. */
                if (strcmp(keys[at], keys[i]) == 0) break;
                bucket = (bucket + 1) & index->mask;
            }
            if (!index->positions[bucket]) index->positions[bucket] = i + 1;
        }
        header_of(obj->list)->text_length = (long long)((size_t)index | 1);
    }
    size_t bucket = hash & index->mask;
    long long found = -1;
    while (index->positions[bucket]) {
        long long at = index->positions[bucket] - 1;
        if (stored_hash(keys[at]) == hash && strcmp(keys[at], key) == 0) {
            found = at;
            break;
        }
        bucket = (bucket + 1) & index->mask;
    }
    if (object_index_check && found != scan_field_position(obj, key, hash)) __builtin_trap();
    return found;
}

/* `find_field` for an object this runtime built. */
static const CodeValue *own_field(const CodeValue *obj, const char *key) {
    long long at = field_position(obj, key, key_hash(key));
    return at < 0 ? NULL : slot_at(ITEMS(obj), at);
}

/* `own_field` for a key that is itself one of an object's own keys, so its
 * hash is already stored. */
static const CodeValue *own_field_of_key(const CodeValue *obj, const char *key) {
    long long at = field_position(obj, key, stored_hash(key));
    return at < 0 ? NULL : slot_at(ITEMS(obj), at);
}

/* Appends `key`'s characters (a NULL key reads as empty, the same answer
 * `code_object` has always given it) to the block's own character run and
 * answers where they landed, advancing the cursor past them. Shared by the
 * two places that build an object: the constructor and `+`'s merge. */
static const char *copy_key(char **chars, const char *key) {
    const char *text = key ? key : "";
    size_t n = strlen(text) + 1;
    unsigned int hash = key_hash(text);
    memcpy(*chars, &hash, KEY_HASH_BYTES);
    memcpy(*chars + KEY_HASH_BYTES, text, n);
    const char *placed = *chars + KEY_HASH_BYTES;
    *chars += KEY_HASH_BYTES + n;
    return placed;
}

/* `copy_key` for a key that already has its hash in front — another
 * object's, or a literal the compiler wrote that way: hash and characters
 * copied as they are. */
static const char *copy_own_key(char **chars, const char *key) {
    size_t n = KEY_HASH_BYTES + strlen(key) + 1;
    memcpy(*chars, key - KEY_HASH_BYTES, n);
    const char *placed = *chars + KEY_HASH_BYTES;
    *chars += n;
    return placed;
}

/* One allocation for both arrays: `[keys...][values...]`. The key pointers
 * themselves are string literals in read-only data, so only the array of
 * pointers is copied, never the characters. */
/* Owns its key *characters*, not just the pointers, since 2026-08-29.
 *
 * They used to be borrowed, which made every field name in a value something
 * that had to outlive it — fine while keys were only ever program literals,
 * and the reason `code-native`'s `object()` demanded `&'static CStr`. Two
 * things wanted otherwise at once: `{ "$name" = v }` builds a key at run
 * time, and a module that wants to hand back HTTP headers has names that
 * arrived over a socket. Copying is one path instead of two, costs a few
 * bytes and one `memcpy` per field, and deletes the restriction rather than
 * documenting an exception to it.
 *
 * The bytes live in the same allocation as the key pointers and the value
 * slots — [pointers][slots][characters] — so an object is still one block,
 * one refcount, one free. */
static void build_object(CodeValue *out, const char **keys, void *values, long long len,
                         int keys_hashed);

void code_object(CodeValue *out, const char **keys, void *values, long long len) {
    build_object(out, keys, values, len, 0);
}

/* `code_object` for an object literal whose every key the compiler wrote
 * down with its hash in front (`[hash][characters\0]`, `keys[i]` at the
 * characters), so building one does not hash its keys again. `keys` is one
 * constant per distinct key list in the program, so its address is the
 * object's shape: a `.field` read the compiler knows the shape of checks the
 * object still has it and reads the slot directly (codegen's `gen_peek`). */
void code_object_literal(CodeValue *out, const char **keys, void *values, long long len) {
    build_object(out, keys, values, len, 1);
    if (len > 0) {
        header_of(out->list)->text_length = (long long)(size_t)keys;
    }
}

/* A hot literal's key run is a compiler-built template: u32 character
 * offsets, then [hash][characters\0] for every key. Copy the run once and
 * relocate its pointers; neither strlen nor hashing is needed per object.
 *
 * The values are taken, not copied: `values` is the literal's own scratch,
 * which the compiler fills and does not clear afterwards, so each value's
 * reference moves into the object and its scratch slot is left zeroed
 * (ticket 126: a retain here and a release of the scratch per field). */
void code_object_template(CodeValue *out, const char **shape, void *values, long long len,
                          const unsigned char *data, long long bytes) {
    CodeList *list = NULL;
    if (len > 0) {
        size_t offsets = (size_t)len * sizeof(unsigned int);
        size_t chars_bytes = (size_t)bytes - offsets;
        list = list_alloc(len, (size_t)len * sizeof(const char *) + chars_bytes);
        void *items = list + 1;
        list->keys = (const char **)((char *)items + (size_t)len * CODE_VALUE_SLOT_SIZE);
        char *chars = (char *)(list->keys + len);
        memcpy(chars, data + offsets, chars_bytes);
        for (long long i = 0; i < len; i++) {
            unsigned int offset;
            memcpy(&offset, data + (size_t)i * sizeof offset, sizeof offset);
            list->keys[i] = chars + offset;
            CodeValue *src = slot_at(values, i);
            *slot_at(items, i) = *src;
            memset(src, 0, sizeof *src);
        }
        header_of(list)->text_length = (long long)(size_t)shape;
    }
    code_release(out);
    out->tag = CODE_OBJECT;
    out->heap = len > 0;
    out->list = list;
}

static void build_object(CodeValue *out, const char **keys, void *values, long long len,
                         int keys_hashed) {
    CodeList *list = NULL;
    if (len > 0) {
        size_t keys_bytes = (size_t)len * sizeof(const char *);
        size_t chars_bytes = 0;
        for (long long i = 0; i < len; i++) {
            chars_bytes += KEY_HASH_BYTES + (keys[i] ? strlen(keys[i]) : 0) + 1;
        }
        list = list_alloc(len, keys_bytes + chars_bytes);
        void *value_buf = list + 1;
        const char **key_buf = (const char **)((char *)value_buf + (size_t)len * CODE_VALUE_SLOT_SIZE);
        list->keys = key_buf;
        char *chars = (char *)key_buf + keys_bytes;
        for (long long i = 0; i < len; i++) {
            key_buf[i] = keys_hashed ? copy_own_key(&chars, keys[i]) : copy_key(&chars, keys[i]);
            const CodeValue *src = slot_at(values, i);
            code_retain(src);
            *slot_at(value_buf, i) = *src;
        }
    }
    code_release(out);
    out->tag = CODE_OBJECT;
    out->heap = len > 0;
    out->list = list;
}

/* The characters of a Str, for use as an object key by generated code.
 *
 * Infallible on purpose: the only thing that reaches it is a computed key
 * (`{ "$name" = v }`), which is an interpolation, and interpolation renders
 * every value — so it is always a Str. A non-Str would be a codegen bug
 * rather than a program error, and answering "" says so without inventing a
 * failure path for a case that cannot happen. */
const char *code_str_text(const CodeValue *v) {
    return v->tag == CODE_STR && v->str ? v->str : "";
}

/* Retain before release, never the other way round. The two can name the
 * same block — `x = x`, or overwriting a loop variable with the next element
 * of the very array the previous element came from — and releasing first
 * would drop the last reference and free the block this is about to read. */
void code_copy(CodeValue *out, const CodeValue *src) {
    /* Read before `out` is released: `src` may live inside `out`'s own
     * block (`o = o.inner`, read without a copy since ticket 120), and
     * releasing `out` can free that block. */
    CodeValue value = *src;
    code_retain(&value);
    code_release(out);
    *out = value;
}

/* `out` takes over `src`'s value, reference and all, and `src` is left
 * zeroed: what `code_copy` then `code_clear` of a temporary nothing else
 * holds did, in one call and without touching the count (ticket 117). */
void code_move(CodeValue *out, CodeValue *src) {
    if (out == src) {
        return;
    }
    code_release(out);
    *out = *src;
    memset(src, 0, sizeof *src);
}

/* The wrong *kind* of operand for `.`/`[]` is a runtime error; a member
 * that simply isn't there is still null. Must match interpreter.rs's
 * `Expr::Field`/`Expr::Index` eval rules — and their message text — exactly. */
/* Mirrors interpreter.rs's `type_name` exactly — the two backends' error
 * messages are meant to read identically, not merely to both fail. */
static const char *article_for(const CodeValue *v) {
    return (v->tag == CODE_ARRAY || v->tag == CODE_OBJECT) ? "an" : "a";
}

static const char *type_name(const CodeValue *v) {
    switch (v->tag) {
    case CODE_NUMBER: return "number";
    case CODE_STR:    return "string";
    case CODE_BOOL:   return "boolean";
    case CODE_NULL:   return "null";
    case CODE_ARRAY:  return "array";
    case CODE_OBJECT: return "object";
    }
    return "value";
}

/* The two shapes every operand-type message in this file is built from.
 *
 * They exist so the wording lives in one place per shape rather than at each
 * `fail` site, because it has to match `interpreter.rs` *exactly*:
 * `Exception.message` is a value a program can read, so two backends wording
 * the same failure differently is a difference in what a program computes,
 * not a cosmetic one. `tests/message_parity.rs` runs both backends over the
 * same failing programs and compares the text. */
static void operand_message(char *buf, size_t n, const char *requirement, const CodeValue *v) {
    snprintf(buf, n, "%s, found %s %s", requirement, article_for(v), type_name(v));
}

static void fail_operand(const char *requirement, const CodeValue *v) {
    char msg[192];
    operand_message(msg, sizeof msg, requirement, v);
    fail(msg);
}

static void fail_binary(const char *op, const CodeValue *a, const CodeValue *b) {
    char msg[192];
    snprintf(msg, sizeof msg, "cannot apply '%s' to %s %s and %s %s", op, article_for(a),
             type_name(a), article_for(b), type_name(b));
    fail(msg);
}

void code_field(CodeValue *out, const CodeValue *obj, const char *field) {
    if (obj->tag != CODE_OBJECT) {
        char msg[128];
        snprintf(msg, sizeof msg,
                 "cannot read field '%s' of %s %s — '.' requires an object", field,
                 article_for(obj), type_name(obj));
        fail(msg);
        return;
    }
    for (long long i = 0; i < LEN(obj); i++) {
        if (strcmp(KEYS(obj)[i], field) == 0) {
            /* `code_copy`, not a bare struct assignment: the extracted
             * value now lives in a second slot and so needs its own
             * reference — otherwise `let inner = obj.k` would dangle the
             * moment `obj` was overwritten. */
            code_copy(out, slot_at(ITEMS(obj), i));
            return;
        }
    }
    /* A *missing* field is still null: only the wrong operand kind errors
     * (see interpreter.rs's `Expr::Field`). */
    code_null(out);
}

/* `obj[key]` — a *computed* field read, the thing `code_field` can never
 * offer since its `field` argument is always a literal baked in at the call
 * site. Same absent-is-null rule as `code_field`; a non-`CODE_STR` key is
 * also just null, not an error, matching the array branch's non-`CODE_NUMBER`
 * case below. See interpreter.rs's `Expr::Index` — this must match it
 * exactly. */
/* The byte offset of character `n` in a UTF-8 string, or the offset of the
 * terminator when the string is shorter. Characters, not bytes, everywhere a
 * string is measured or cut — `strlen` reported 6 for "héllo", and text Length
 * has counted codepoints since it shipped. */
static size_t char_offset(const char *s, long long n) {
    size_t i = 0;
    long long seen = 0;
    while (s[i] && seen < n) {
        i++;
        while ((s[i] & 0xC0) == 0x80) {
            i++;
        }
        seen++;
    }
    return i;
}

/* `n` bytes of `s` as a fresh owned string. `code_str_owned` cannot serve:
 * it takes a NUL-terminated whole, and a slice's end is in the middle. */
static void str_owned_n(CodeValue *out, const char *s, size_t n) {
    char *buf = heap_alloc(n + 1);
    memcpy(buf, s, n);
    buf[n] = '\0';
    code_release(out);
    out->tag = CODE_STR;
    out->heap = 1;
    out->str = buf;
}

/* How many elements a value has — the `length` an index may name. Must match
 * interpreter.rs's `Expr::LengthOf` arm, kinds and message alike. */
void code_length_of(CodeValue *out, const CodeValue *value) {
    if (value->tag == CODE_ARRAY || value->tag == CODE_OBJECT) {
        code_number(out, (double)LEN(value));
        return;
    }
    if (value->tag == CODE_STR) {
        /* Characters, not bytes — the same continuation-byte count text Length
         * uses, and for the same reason. */
        long long chars = 0;
        for (const char *p = value->str; *p; p++) {
            if (((unsigned char)*p & 0xC0) != 0x80) {
                chars++;
            }
        }
        code_number(out, (double)chars);
        return;
    }
    char msg[160];
    snprintf(msg, sizeof msg,
             "cannot take the length of %s %s — 'length' needs an array, an object or a string",
             article_for(value), type_name(value));
    fail(msg);
}

/* `value[from, to]` — half-open, both bounds clamped. A single index past the
 * end already answers null, so a range past the end answers the part that is
 * there; `from` at or after `to` is the empty array. Must match
 * interpreter.rs's `Expr::Slice` arm. */
void code_slice(CodeValue *out, const CodeValue *value, const CodeValue *from,
                const CodeValue *to) {
    if (from->tag != CODE_NUMBER) {
        char msg[128];
        snprintf(msg, sizeof msg, "a range's start must be a number, found %s %s",
                 article_for(from), type_name(from));
        fail(msg);
        return;
    }
    if (to->tag != CODE_NUMBER) {
        char msg[128];
        snprintf(msg, sizeof msg, "a range's end must be a number, found %s %s",
                 article_for(to), type_name(to));
        fail(msg);
        return;
    }
    if (value->tag == CODE_STR) {
        /* Characters, not bytes, and the same clamping an array gets. */
        double chars = 0;
        for (const char *p = value->str; *p; p++) {
            if (((unsigned char)*p & 0xC0) != 0x80) {
                chars++;
            }
        }
        double slo = from->number < 0 ? 0 : (from->number > chars ? chars : from->number);
        double shi = to->number < 0 ? 0 : (to->number > chars ? chars : to->number);
        if (slo >= shi) {
            code_str(out, "");
            return;
        }
        size_t begin = char_offset(value->str, (long long)slo);
        size_t end = char_offset(value->str, (long long)shi);
        str_owned_n(out, value->str + begin, end - begin);
        return;
    }
    if (value->tag != CODE_ARRAY) {
        char msg[160];
        snprintf(msg, sizeof msg,
                 "cannot take a range of %s %s — '[from, to]' requires an array or a string",
                 article_for(value), type_name(value));
        fail(msg);
        return;
    }
    double len = (double)LEN(value);
    double lo = from->number < 0 ? 0 : (from->number > len ? len : from->number);
    double hi = to->number < 0 ? 0 : (to->number > len ? len : to->number);
    long long start = (long long)lo;
    long long stop = (long long)hi;
    if (start >= stop) {
        code_array(out, NULL, 0);
        return;
    }
    /* `code_array` copies out of a strided buffer, and the array's own
     * `items` is one, so the run starts at `start` with nothing to build. */
    code_array(out, (char *)ITEMS(value) + (size_t)start * CODE_VALUE_SLOT_SIZE, stop - start);
}

void code_index(CodeValue *out, const CodeValue *arr, const CodeValue *index) {
    if (arr->tag == CODE_ARRAY) {
        if (index->tag == CODE_NUMBER) {
            double n = index->number;
            long long i = (long long)n;
            if ((double)i == n && i >= 0 && i < LEN(arr)) {
                code_copy(out, slot_at(ITEMS(arr), i));
                return;
            }
        }
        /* An out-of-range or non-integer index is still null, for the same
         * reason a missing field is. */
        code_null(out);
        return;
    }
    if (arr->tag == CODE_OBJECT) {
        const CodeValue *found = index->tag == CODE_STR ? own_field(arr, index->str) : NULL;
        if (found) {
            code_copy(out, found);
            return;
        }
        code_null(out);
        return;
    }
    if (arr->tag == CODE_STR) {
        /* One character, as a one-character string — there is no character
         * kind here, and there are only six. Out of range is null, like an
         * array's. */
        if (index->tag == CODE_NUMBER) {
            double n = index->number;
            long long i = (long long)n;
            if ((double)i == n && i >= 0) {
                size_t begin = char_offset(arr->str, i);
                if (arr->str[begin]) {
                    size_t end = char_offset(arr->str, i + 1);
                    str_owned_n(out, arr->str + begin, end - begin);
                    return;
                }
            }
        }
        code_null(out);
        return;
    }
    char msg[112];
    snprintf(msg, sizeof msg,
             "cannot index %s %s — '[]' requires an array, an object or a string",
             article_for(arr), type_name(arr));
    fail(msg);
}

/* `emit <particle> to core [get <name>]`. `class_name` is read from the
 * particle's own "_class" field at runtime, never resolved to a fixed call
 * at compile time — even when the particle is a literal `ClassName { ... }`
 * right at the call site, because it can just as easily be a value that was
 * built earlier, stored, and passed around (see memory `new-code-particle`
 * for why particles carry `_class` with them at all). Must match
 * interpreter.rs's `dispatch_core` exactly — same handler set, same
 * operand-type rules.
 *
 * A future handler that returns *part of* its input (rather than a fresh
 * Number/Str/Array/Object, as index-context length does) would need to
 * `code_retain` that piece before it can safely end up in `out` — nothing
 * here does that today, so this is a note for whoever adds the next one,
 * not a currently-exercised path. */
static const CodeValue *find_field(const CodeValue *obj, const char *key) {
    long long len = LEN(obj);
    const char **keys = KEYS(obj);
    for (long long i = 0; i < len; i++) {
        if (strcmp(keys[i], key) == 0) {
            return slot_at(ITEMS(obj), i);
        }
    }
    return NULL;
}

/* ---- Reading without copying (ticket 120) ---------------------------------
 *
 * `fish.x + 1` used to copy `fish.x` into a temporary (a retain), use it once
 * and release it at the end of the statement. These answer a pointer to the
 * value where it already is instead. Codegen uses them only where the value
 * is looked at and let go within the expression — arithmetic, comparison, a
 * condition, the right side of an assignment (`code_copy` reads before it
 * releases) — never where it is stored or handed on, because nothing
 * guarantees the container outlives a later statement. Same rules and
 * messages as `code_field` and `code_index`, which they fall back on. */
static const CodeValue no_value = { CODE_NULL, 0, { 0 } };

/* `hash` is `field`'s, worked out by the compiler; `*guess` is this read's
 * own memory of where it found the field last, tried first — the objects one
 * `.x` in a program meets are almost always built the same way. */
const CodeValue *code_field_ref(const CodeValue *obj, const char *field, unsigned int hash,
                                long long *guess) {
    if (obj->tag != CODE_OBJECT) {
        CodeValue unused;
        memset(&unused, 0, sizeof unused);
        code_field(&unused, obj, field); /* the error */
        return &no_value;
    }
    long long at = *guess;
    if (at < LEN(obj) && stored_hash(KEYS(obj)[at]) == hash && strcmp(KEYS(obj)[at], field) == 0) {
        return slot_at(ITEMS(obj), at);
    }
    at = field_position(obj, field, hash);
    if (at < 0) {
        return &no_value;
    }
    *guess = at;
    return slot_at(ITEMS(obj), at);
}

/* `scratch` is a temporary of the statement, for the one read that has to
 * build its answer: a string's character. */
const CodeValue *code_index_ref(CodeValue *scratch, const CodeValue *arr, const CodeValue *index) {
    if (arr->tag == CODE_ARRAY) {
        if (index->tag == CODE_NUMBER) {
            double n = index->number;
            long long i = (long long)n;
            if ((double)i == n && i >= 0 && i < LEN(arr)) {
                return slot_at(ITEMS(arr), i);
            }
        }
        return &no_value;
    }
    if (arr->tag == CODE_OBJECT) {
        const CodeValue *found = index->tag == CODE_STR ? own_field(arr, index->str) : NULL;
        return found ? found : &no_value;
    }
    code_index(scratch, arr, index); /* a character, or the error */
    return scratch;
}

/* Builds `{ "_class": class_name, "value": *value }` — the shape every core
 * handler's result takes, matching the old language's `<Name>Result`
 * convention: what goes into `emit` is a particle, so what comes back out
 * is one too, not a bare scalar.
 *
 * `slots` is a scratch buffer shaped exactly like the ones codegen.rs builds
 * for an object literal (`CODE_VALUE_SLOT_SIZE`-strided, addressed only via
 * `slot_at`) — zero-initialized before anything writes into it, which
 * matters here specifically: `code_str`/`code_copy` both call
 * `code_release` on their `out` first, and `code_release` reads `out->heap`
 * — on an *uninitialized* local that's garbage, not a real flag, so it has
 * to start at all-zero (reading as a payload-less number, `heap = 0`) for
 * that first release to be the no-op it's supposed to be. `code_copy`
 * rather than a raw struct copy for `value` for the same reason the doc
 * comment above `find_field` flags: a future handler whose result owns a
 * heap block needs it retained, and `code_copy` does that for free even
 * though the clock queries here never do. */
static void code_make_result(CodeValue *out, const char *class_name, const CodeValue *value) {
    const char *keys[2] = {"_class", "value"};
    _Alignas(8) char slots[2 * CODE_VALUE_SLOT_SIZE] = {0};
    code_str(slot_at(slots, 0), class_name);
    code_copy(slot_at(slots, 1), value);
    code_object(out, keys, slots, 2);
    /* `code_object` retained its own copy of each slot; these scratch ones
     * are done being needed the moment it returns. Harmless no-ops for
     * the clock queries (`slots[0]` is a literal, `slots[1]` a Number — neither is ever
     * `heap`), but load-bearing the moment a handler's `value` argument (see
     * this function's doc comment above `code_core_dispatch`) is itself
     * heap-owned: without this, that caller's own reference to `value`
     * would double-count against the fresh copy `code_object` just made. */
    code_release(slot_at(slots, 0));
    code_release(slot_at(slots, 1));
}

/* Builds `Exception { source, message, innerException }` — how a module (and,
 * once the C runtime has an error channel, the language itself) reports that
 * it could not do the work. `inner` may be NULL for the common case of a
 * failure with nothing beneath it.
 *
 * `message` is copied, not borrowed: callers build it into a stack buffer.
 * See docs/todo/errors-as-particles.md for the model. */
void code_make_exception(CodeValue *out, const char *source, const char *message,
                         const CodeValue *inner) {
    const char *keys[4] = {"_class", "source", "message", "innerException"};
    _Alignas(8) char slots[4 * CODE_VALUE_SLOT_SIZE] = {0};
    code_str(slot_at(slots, 0), "Exception");
    code_str_owned(slot_at(slots, 1), source);
    code_str_owned(slot_at(slots, 2), message);
    if (inner) {
        code_copy(slot_at(slots, 3), inner);
    } else {
        code_null(slot_at(slots, 3));
    }
    code_object(out, keys, slots, 4);
    for (int i = 0; i < 4; i++) {
        code_release(slot_at(slots, i));
    }
}

/* Whether this run is a linked module rather than a program of its own —
 * what `Linked` answers, just above.
 *
 * Set once, from the generated start-up of a `--target shared` build, before
 * a single statement of it runs (see codegen.rs's `lazy_init_fn`). Nothing
 * else writes it, and nothing ever clears it: what a build *is* does not
 * change while it runs. Zero for a program and for the interpreter, which is
 * the right answer for both. */
static int code_linked = 0;

void code_set_linked(void) { code_linked = 1; }

void code_core_dispatch(CodeValue *out, const CodeValue *particle) {
    /* `code_check_emittable` ran at the emit site, so a `_class` is here. A
     * non-Str one is not a class core knows, and core answers null like any
     * other recipient. */
    if (particle->tag != CODE_OBJECT) {
        code_null(out);
        return;
    }
    const CodeValue *class_val = find_field(particle, "_class");
    if (!class_val || class_val->tag != CODE_STR) {
        code_null(out);
        return;
    }

    if (strcmp(class_val->str, "Linked") == 0) {
        /* Whether this run is a module another program linked, rather than a
         * program of its own.
         *
         * Answered from the build, not from anything at runtime: `--target
         * shared` produces something to be linked and says so in its own
         * start-up, and no other target does. Nobody has to install
         * anything, tell it anything, or be present for it to be right.
         *
         * What it is for: the same source can be built both ways, and a few
         * things are only correct in one of them. Opening a listening socket
         * of your own is the usual one — a module that leaves a thread
         * running past its release point can never be unloaded, so a module
         * that may be linked reaches for a door its linker stands behind
         * instead. Reading command-line arguments and ending the process are
         * the same kind of thing: correct for a program, wrong for a part of
         * one.
         *
         * What it deliberately does *not* say is whether anyone is standing
         * behind you. That is not this layer's question, and a module asks
         * it of the thing that would need an answer.
         *
         * `code run` always says no: an interpreted run is a program.
         *
         * Must match interpreter.rs's `dispatch_core`. */
        CodeValue answer = {0};
        code_bool(&answer, code_linked != 0);
        code_make_result(out, "LinkedResult", &answer);
        code_release(&answer);
        return;
    }

    if (strcmp(class_val->str, "Timestamp") == 0) {
        /* Whole seconds since the Unix epoch — must match
         * interpreter.rs's `dispatch_core` exactly. Takes no operands,
         * so there is nothing to validate beyond the particle shape.
         * Zero-initialized for the same reason `code_make_result`'s
         * `slots` is: `code_number` releases `out` before setting it. */
        CodeValue ts = {0};
    #ifdef CODE_WASM
        code_number(&ts, code_host_now());
    #else
        code_number(&ts, (double)time(NULL));
    #endif
        code_make_result(out, "TimestampResult", &ts);
        return;
    }

    if (strcmp(class_val->str, "TimezoneOffset") == 0) {
        /* Minutes to add to UTC to get the reader's own clock — must match
         * interpreter.rs's `dispatch_core` exactly, sign included. JavaScript
         * counts it the other way round, which is where the negation in the
         * wasm host lives rather than here. */
        CodeValue off = {0};
    #ifdef CODE_WASM
        code_number(&off, code_host_tz_offset());
    #else
        time_t now = time(NULL);
        struct tm local;
        if (localtime_r(&now, &local) == NULL) {
            code_number(&off, 0.0);
        } else {
            code_number(&off, (double)local.tm_gmtoff / 60.0);
        }
    #endif
        code_make_result(out, "TimezoneOffsetResult", &off);
        code_release(&off);
        return;
    }

    /* Not a core class. Null rather than an error: sending a particle is not
     * a demand, and whether to act on one is the recipient's business — the
     * same answer `to this` and a native module give (decided 2026-08-28,
     * see docs/todo/errors-as-particles.md). */
    code_null(out);
}

/* ---- Native modules (`link "x.so" as x`, `emit ... to x [get n]`) --------
 *
 * See code_abi.h for the contract every module implements. Loading is
 * dlopen/dlsym-based here, exactly as in the interpreter (native.rs) — never
 * cc-time static linking, so multiple linked modules that all export the
 * identically-named `code_module_dispatch` never collide: dlsym resolves
 * within one module's own handle, never the whole process.
 *
 * A module's result is never adopted directly — `code_native_dispatch`
 * always deep-copies it into a fresh, host-allocated value
 * (`code_native_copy_in`), then calls the module's *own* copy of
 * `code_release` (looked up from the same handle) to free whatever it
 * allocated. That is what keeps `CODE_CHECK_LEAKS` meaningful on both sides
 * of a dlopen boundary: two separate copies of this runtime, two separate
 * static `live_blocks` counters, each only ever freeing blocks it itself
 * allocated.
 *
 * A `.a` static module (`link "x.a" as x`, `code build` only — see
 * `docs/todo/native-module-linking.md`) is a different story, handled
 * entirely by codegen.rs rather than by a `NativeHandle` here: it is linked
 * straight into the same binary as this very runtime, so it calls
 * `code_number`/`code_array`/... directly rather than bringing its own copy,
 * and its result needs no deep copy — it was built with the host's own
 * allocator to begin with. `code_static_module_check` and
 * `code_static_vars_object` below are the two bits of that path still
 * shared here rather than duplicated in generated IR. */

/* The ring below is touched from two threads once a module has one of its
 * own, so it is locked. Under CODE_WASM there are no native modules at all
 * (`code_native_open` refuses one) and the freestanding shim has no pthreads,
 * so the lock compiles away to nothing there. */
#ifdef CODE_WASM
typedef int CodeMutex;
#define code_mutex_init(m) ((void)(m))
#define code_mutex_lock(m) ((void)(m))
#define code_mutex_unlock(m) ((void)(m))
#else
typedef pthread_mutex_t CodeMutex;
#define code_mutex_init(m) pthread_mutex_init((m), NULL)
#define code_mutex_lock(m) pthread_mutex_lock(m)
#define code_mutex_unlock(m) pthread_mutex_unlock(m)
#endif

typedef struct {
    void (*dispatch)(CodeValue *out, const CodeValue *particle);
    void (*release)(CodeValue *v);
    /* Optional: what the module wants told about the answer to a particle
     * it pushed — the program's handler's return value. NULL when the module
     * does not export `code_module_inbound_reply`, which is most of them: a
     * module that only announces things has no use for the answer. */
    CodeInboundReplyFn reply;
    /* Optional: the module's exported variables (constants). NULL when the
     * module doesn't export `code_module_vars` (a Phase 1, handlers-only
     * module) — in which case `code_native_vars_object` binds an empty
     * object. Unlike the two required symbols above, a missing one is not an
     * error. */
    const CodeVarList *(*vars)(void);
    /* Particles this module has pushed and the program hasn't handled yet —
     * see `code_emit_inbound`. A bounded ring: a module that runs away must
     * not grow the host's memory without bound, so the oldest entry is
     * dropped rather than the allocation growing. */
    CodeValue inbound[CODE_INBOUND_CAPACITY];
    int inbound_head;
    int inbound_count;
    /* Guards the three fields above and the deep copy that fills a slot.
     * Held for the whole of a push so a poll can never see a half-built
     * value. */
    CodeMutex lock;
    /* Optional `code_module_serving`: non-zero while this module still
     * expects to speak, which is what holds the program open after its last
     * statement (see `code_host_park`). NULL for a module that exports none,
     * and for every `.a` — a static module's exports are called by their
     * prefixed names from generated code, so there is no pointer to keep. */
    int (*serving)(void);
    /* Whether the module took the inbound channel — i.e. whether anything
     * but this thread can ever reach the ring. Decides what
     * `code_native_close` may do with the handle. */
    int has_inbound;
    /* The in-memory image this instance was loaded from, or -1. Held open
     * for the module's whole life: the loader identifies an object by the
     * file behind it, so closing this early would let a later instance be
     * handed the same identity and deduplicated into this one. */
    int image_fd;
    /* The `dlopen` result, kept only so a runtime-linked module can be
     * unloaded again (`code_runtime_unlink`). NULL for a `.a`, which was
     * never opened. A top-level `link` never reads it: that module stays
     * mapped for the life of the process, which is what lets an exported
     * value's key strings be borrowed rather than copied (see
     * `code_native_vars_object`). */
    void *lib;
    /* Set when this module was supplied by a host rather than opened from
     * a file (`code_abi.h` item 10). Every crossing below — dispatch,
     * exported values, whether it is still serving — goes through `host`
     * instead of the `dlsym`'d pointers above, which are all NULL then. */
    int from_host;
    CodeHostModule host;
    /* `code_abi.h` item 13: a module opened once and instantiated per link.
     * Set, every call goes to `instance_dispatch` with this link's
     * `instance` instead of to `dispatch`. NULL for every other module. */
    void *instance;
    void (*instance_dispatch)(void *instance, CodeValue *out, const CodeValue *particle);
    /* Optional `code_module_release` — `code_abi.h` item 9, the point at
     * which the module gives up the top-level values it otherwise owns for
     * its whole lifetime. NULL for every module that has none, which is all
     * of them except a `.code` library. */
    void (*module_release)(void);
    /* Optional `code_module_drain` — runs this module's own inbound drain
     * once. A library has queues but no loop of its own to empty them, so a
     * host calls this when the guest's modules have pushed something. */
    void (*module_drain)(void);
    /* Set at cleanup: the program is done, and a push arriving after it is
     * dropped rather than queued. Without it a module thread still running
     * at exit would allocate into a ring nobody will drain, and
     * `code_check_leaks` would report those blocks as a leak — a race
     * between two threads showing up as a flaky failure in an unrelated
     * test. */
    int closed;
} NativeHandle;

/* Shared by both native-module paths (`.so` here, `.a` in codegen's direct
 * calls — see `code_static_vars_object` below): aborts with a consistent
 * message if `version` (whatever a module's `code_module_abi_version`
 * reported) doesn't match this runtime's `CODE_ABI_VERSION`. `what` names
 * the module in the error (a path for `.so`, the module's chosen prefix for
 * `.a`). */
void code_static_module_check(uint32_t version, const char *what) {
    if (version != CODE_ABI_VERSION) {
        char msg[256];
        snprintf(msg, sizeof msg, "native module '%s' has ABI version %u (expected %u)", what,
                 (unsigned)version, (unsigned)CODE_ABI_VERSION);
        code_runtime_error(msg);
    }
}

/* Defined below, next to `code_poll_inbound` — forward-declared so
 * `code_native_open` can hand its address to a module. */
void code_emit_inbound(void *queue, const CodeValue *value);

/* ---- Being hosted -------------------------------------------------------
 *
 * `code_abi.h` item 10, from the guest's side. Installed by whoever opened
 * this module while their program was running; NULL in a program running on
 * its own, which is what keeps every existing application working unchanged.
 *
 * One pair per loaded module, not per link: a `.so` carries its own copy of
 * this runtime, so these statics are private to it and there is exactly one
 * host for it. */
static const CodeHostVtable *code_host = NULL;
static void *code_host_ctx = NULL;

void code_module_set_host(const CodeHostVtable *host, void *host_ctx) {
    code_host = host;
    code_host_ctx = host_ctx;
}

/* Builds a handle around a module the host supplied. No `dlopen`, no
 * symbols, no mapping of its own: everything this handle can do, it does by
 * calling back through the host. */
static NativeHandle *host_native(const CodeHostModule *supplied, char *err, size_t errlen) {
    if (!supplied->dispatch || !supplied->release) {
        snprintf(err, errlen, "the host offered a module with no dispatch");
        return NULL;
    }
    NativeHandle *nh = malloc(sizeof(NativeHandle));
    if (!nh) {
        code_runtime_error("out of memory");
    }
    memset(nh, 0, sizeof *nh);
    nh->from_host = 1;
    nh->host = *supplied;
    /* A host-supplied module never pushes. It cannot: the queue and its
     * drain belong to *this* module's runtime, while the thing actually
     * doing the work lives in the host's. Anything that has to speak first
     * is the host's own module, spoken for on the host's side. */
    nh->has_inbound = 0;
    code_mutex_init(&nh->lock);
    return nh;
}

/* Opens `path` and builds the handle around it, or returns NULL with the
 * reason written into `err`.
 *
 * Split out of `code_native_open` because the two ways a link can fail have
 * to differ. A top-level `link` names a module in the source and the program
 * cannot run without it, so failing there ends the process. A `link` that
 * runs inside a handler is opening something the program worked out at run
 * time — a host loading a guest — and there the failure has to be a value
 * the program can answer, not the end of the host. Same opening, two
 * reporting rules, one implementation. */
/* Opens `path` as an object of its own, distinct from every other load of
 * the same file.
 *
 * **A name is a module, and two names are two modules.** A module has
 * state — its settings, its connection — so linking one twice is not two
 * views of one thing, it is two things. The loader does not see it that way:
 * asked for a file it already has, it hands back what it already loaded, and
 * both names end up sharing one set of statics. Measured, and it is not a
 * subtlety — configuring the second alias silently changed what the first
 * one signs with.
 *
 * So each load gets its own image of the same file, in memory, which the
 * loader has no reason to associate with any other. Nothing is written
 * anywhere: the file on disk stays the single copy, and there is no limit
 * beyond ordinary memory. (The loader's own namespaces would also work and
 * cost no copy, but glibc allows fifteen of them in a process — measured —
 * which is few enough to run out of while holding a handful of
 * applications.)
 *
 * Returns -1 where this is not available, and the caller falls back to an
 * ordinary open — one instance, shared, as before.
 *
 * While copying it looks for the names `code_module_stateless` (`code_abi.h`
 * item 12, ticket 177) and `code_module_instance_new` (item 13, ticket 178)
 * in the file and says which it found in `*marked`: such a module can be
 * opened once and shared by every link — as it is, or with an instance of
 * its own per link — which `open_native` then checks properly. Looked for
 * in the bytes rather than by opening the file first, because opening a
 * `.code` library runs its top level. */
#define STATELESS_EXPORT "code_module_stateless"
#define INSTANCE_EXPORT "code_module_instance_new"
enum { MARKED_STATELESS = 1, MARKED_INSTANCES = 2 };
static int module_image(const char *path, int *marked) {
    *marked = 0;
#if defined(__linux__) && !defined(CODE_WASM)
    int src = open(path, O_RDONLY | O_CLOEXEC);
    if (src < 0) {
        return -1;
    }
    int image = memfd_create("code-module", MFD_CLOEXEC);
    if (image < 0) {
        close(src);
        return -1;
    }
    /* The tail of the previous read goes in front of the next, so a name
     * that straddles two reads is still found. */
    enum {
        CARRY = sizeof INSTANCE_EXPORT > sizeof STATELESS_EXPORT ? sizeof INSTANCE_EXPORT - 1
                                                                 : sizeof STATELESS_EXPORT - 1
    };
    char buf[CARRY + 65536];
    size_t carried = 0;
    for (;;) {
        ssize_t n = read(src, buf + carried, sizeof buf - carried);
        if (n == 0) {
            break;
        }
        if (n < 0 || write(image, buf + carried, (size_t)n) != n) {
            close(src);
            close(image);
            return -1;
        }
        size_t have = carried + (size_t)n;
        if (memmem(buf, have, STATELESS_EXPORT, sizeof STATELESS_EXPORT - 1)) {
            *marked |= MARKED_STATELESS;
        }
        if (memmem(buf, have, INSTANCE_EXPORT, sizeof INSTANCE_EXPORT - 1)) {
            *marked |= MARKED_INSTANCES;
        }
        carried = have < CARRY ? have : CARRY;
        memmove(buf, buf + have - carried, carried);
    }
    close(src);
    return image;
#else
    (void)path;
    return -1;
#endif
}

#ifndef CODE_WASM
/* Whether the library `lib` declares that it keeps no state and has nothing
 * that would make one instance per link matter: no queue it pushes into,
 * nothing holding the program open, no top-level values to give up. Only
 * then is one instance shared (`code_abi.h` item 12). */
static int has_no_life_of_its_own(void *lib) {
    return !dlsym(lib, "code_module_set_inbound") && !dlsym(lib, "code_module_serving")
           && !dlsym(lib, "code_module_release") && !dlsym(lib, "code_module_drain");
}

static int shares_one_instance(void *lib) {
    int (*stateless)(void) = (int (*)(void))dlsym(lib, STATELESS_EXPORT);
    return stateless && stateless() && has_no_life_of_its_own(lib);
}

/* Whether `lib` offers an instance per link (`code_abi.h` item 13), with
 * nothing that would tie it to one: no serving, release or drain, and a
 * module that pushes takes its queue per instance
 * (`code_module_instance_set_inbound`, ticket 178). */
static int offers_instances(void *lib) {
    int pushes = dlsym(lib, "code_module_set_inbound") != NULL;
    return dlsym(lib, INSTANCE_EXPORT) && dlsym(lib, "code_module_instance_dispatch")
           && (!pushes || dlsym(lib, "code_module_instance_set_inbound"))
           && !dlsym(lib, "code_module_serving") && !dlsym(lib, "code_module_release")
           && !dlsym(lib, "code_module_drain");
}
#endif

static NativeHandle *open_native(const char *path, char *err, size_t errlen) {
    /* A host, once installed, is the only way out. Not a fallback to opening
     * the file: a guest that could quietly reach past its host is a guest
     * whose memory cannot be reclaimed and whose reach cannot be bounded —
     * see `code_abi.h` item 10. */
    if (code_host && code_host->resolve) {
        CodeHostModule supplied = {0};
        if (code_host->resolve(code_host_ctx, path, &supplied)) {
            return host_native(&supplied, err, errlen);
        }
        /* The host did not furnish this one, so this module opens it itself
         * — its own file, its own settings. A host that wants a say answers;
         * one that does not, does not, and the guest is none the wiser. */
    }
#ifdef CODE_WASM
    (void)path;
    snprintf(err, errlen, "native modules are not available in a wasm build");
    return NULL;
#else
    /* Its own image, so this instance is nobody else's — see
     * `module_image`. A failure there is not fatal: the ordinary open still
     * works, it just shares with any other link of the same file. */
    int marked = 0;
    int image = module_image(path, &marked);
    void *handle = NULL;
    if (marked) {
        /* The ordinary open, which the loader shares between every link of
         * the file — what a module that keeps no state wants. */
        void *shared = dlopen(path, RTLD_NOW);
        int fits = shared && (((marked & MARKED_INSTANCES) && offers_instances(shared))
                              || ((marked & MARKED_STATELESS) && shares_one_instance(shared)));
        if (fits) {
            handle = shared;
            if (image >= 0) {
                close(image);
                image = -1;
            }
        } else if (shared) {
            dlclose(shared);
        }
    }
    if (!handle && image >= 0) {
        char proc[64];
        snprintf(proc, sizeof proc, "/proc/self/fd/%d", image);
        handle = dlopen(proc, RTLD_NOW);
        if (!handle) {
            close(image);
            image = -1;
        }
    }
    if (!handle) {
        handle = dlopen(path, RTLD_NOW);
    }
    if (!handle) {
        snprintf(err, errlen, "cannot load native module '%s': %s", path, dlerror());
        return NULL;
    }

    uint32_t (*version_fn)(void) = (uint32_t (*)(void))dlsym(handle, "code_module_abi_version");
    if (!version_fn) {
        snprintf(err, errlen, "native module '%s' missing 'code_module_abi_version'", path);
        dlclose(handle);
        return NULL;
    }
    uint32_t version = version_fn();
    if (version != CODE_ABI_VERSION) {
        snprintf(err, errlen, "native module '%s' has ABI version %u (expected %u)", path,
                 (unsigned)version, (unsigned)CODE_ABI_VERSION);
        dlclose(handle);
        return NULL;
    }

    NativeHandle *nh = malloc(sizeof(NativeHandle));
    if (!nh) {
        code_runtime_error("out of memory");
    }
    /* Zeroed whole, not field by field. Every field below is assigned, but
     * that is exactly the promise that broke: a field added to this struct
     * later was set on the other two construction paths and missed here, so
     * a freshly opened module inherited whatever the last freed handle had
     * left in that byte. It read as "this module was supplied by a host",
     * and the module was never called at all — the program dispatched into
     * the wrong thing entirely, only when the allocator happened to hand
     * back a dirty block, which made it look like a layout-sensitive
     * corruption for a long time. Starting from zero costs nothing and
     * cannot be forgotten. */
    memset(nh, 0, sizeof *nh);
    nh->image_fd = image;
    nh->lib = handle;
    nh->dispatch = (void (*)(CodeValue *, const CodeValue *))dlsym(handle, "code_module_dispatch");
    nh->release = (void (*)(CodeValue *))dlsym(handle, "code_release");
    if (!nh->dispatch || !nh->release) {
        snprintf(err, errlen, "native module '%s' missing 'code_module_dispatch' or 'code_release'",
                 path);
        free(nh);
        dlclose(handle);
        if (image >= 0) {
            close(image);
        }
        return NULL;
    }
    /* Optional — a module without it simply has no exported variables. */
    nh->vars = (const CodeVarList *(*)(void))dlsym(handle, "code_module_vars");
    /* Also optional: only a module that wants an answer to what it pushed. */
    nh->reply = (CodeInboundReplyFn)dlsym(handle, "code_module_inbound_reply");
    /* Optional too: a module that holds the program open while it works. */
    nh->serving = (int (*)(void))dlsym(handle, "code_module_serving");
    /* Optional as well, and only a `.code` library has one: the point at
     * which this module may let go of its top-level values (item 9). */
    nh->module_release = (void (*)(void))dlsym(handle, "code_module_release");
    /* And the point at which it hands out what its own modules pushed.
     * Only a `.code` library has one, and only a host ever calls it. */
    nh->module_drain = (void (*)(void))dlsym(handle, "code_module_drain");

    /* Opened once for every link (above), so this link gets an instance of
     * its own: its own settings, its own connection (`code_abi.h` item 13).
     * Never freed, like the handle: a module is not unloaded. */
    if (image < 0 && offers_instances(handle)) {
        void *(*make)(void) = (void *(*)(void))dlsym(handle, INSTANCE_EXPORT);
        nh->instance = make();
        nh->instance_dispatch = (void (*)(void *, CodeValue *, const CodeValue *))dlsym(
            handle, "code_module_instance_dispatch");
        if (!nh->instance) {
            snprintf(err, errlen, "native module '%s' could not make an instance", path);
            free(nh);
            return NULL;
        }
    }

    /* Also optional: a module that never speaks first doesn't export it.
     * The pusher handed across is *this* runtime's, not the module's own
     * copy — see code_abi.h for why that distinction matters. */
    memset(nh->inbound, 0, sizeof nh->inbound);
    nh->inbound_head = 0;
    nh->inbound_count = 0;
    nh->closed = 0;
    code_mutex_init(&nh->lock);
    void (*set_inbound)(void *, CodeEmitFn) =
        (void (*)(void *, CodeEmitFn))dlsym(handle, "code_module_set_inbound");
    nh->has_inbound = set_inbound != NULL;
    /* A link with an instance of its own gets a queue of its own: handed to
     * that instance, never to the module-wide export another link's queue
     * would replace (ticket 178). */
    void (*instance_set_inbound)(void *, void *, CodeEmitFn) =
        nh->instance ? (void (*)(void *, void *, CodeEmitFn))dlsym(
                           handle, "code_module_instance_set_inbound")
                     : NULL;
    if (instance_set_inbound) {
        instance_set_inbound(nh->instance, nh, code_emit_inbound);
    } else if (set_inbound) {
        set_inbound(nh, code_emit_inbound);
    }
    return nh;
#endif
}

void *code_native_open(const char *path) {
    char err[256];
    NativeHandle *nh = open_native(path, err, sizeof err);
    if (!nh) {
        code_runtime_error(err);
    }
    return nh;
}

/* A queue for a `.a` static module, and nothing else.
 *
 * A `.so` gets its ring as part of the `NativeHandle` that `code_native_open`
 * builds around a `dlopen` result. A `.a` has no such thing — it is linked
 * straight into this binary, so codegen calls its `<prefix>_code_module_*`
 * functions directly and never needed a handle at all. Which is why static
 * modules could not speak first: there was nowhere to queue *into*, not a
 * decision that they shouldn't.
 *
 * So this allocates the same struct with only the ring live. The three
 * function pointers stay NULL and are never read: dispatch goes direct, there
 * is no per-module `code_release` (one runtime, the host's), and exported
 * variables come through `code_static_vars_object`. `code_native_close` frees
 * it and drains whatever is still queued, exactly as for a `.so`. */
void *code_static_open(void) {
    NativeHandle *nh = malloc(sizeof(NativeHandle));
    if (!nh) {
        code_runtime_error("out of memory");
    }
    /* See `open_native` for why this is a whole-struct zero. */
    memset(nh, 0, sizeof *nh);
    nh->image_fd = -1;
    nh->dispatch = NULL;
    nh->release = NULL;
    nh->vars = NULL;
    /* A `.a`'s reply export is called directly by generated code, by its
     * prefixed name, exactly as its dispatch is — there is no pointer to
     * keep here. */
    nh->reply = NULL;
    nh->serving = NULL;
    /* A `.a` was linked into this binary, not opened, so there is nothing to
     * unload and no separate release point — its cleanup is the program's. */
    nh->lib = NULL;
    nh->module_release = NULL;
    nh->from_host = 0;
    memset(&nh->host, 0, sizeof nh->host);
    memset(nh->inbound, 0, sizeof nh->inbound);
    nh->inbound_head = 0;
    nh->inbound_count = 0;
    nh->closed = 0;
    /* A `.a` is only given a handle at all because it declared an inbound
     * export — that is what `loader.rs` looks for before emitting the call. */
    nh->has_inbound = 1;
    code_mutex_init(&nh->lock);
    return nh;
}

/* Builds a fresh heap-owned string value by copying `s`'s bytes — unlike
 * `code_str`, whose caller always passes a program literal it doesn't own.
 * Needed here because a module's own string may become dangling the moment
 * its `code_release` runs.
 *
 * Part of the module-facing ABI since 2026-08-28, when modules started
 * returning `Exception` particles: an exception message is built at runtime,
 * usually into a stack buffer, and handing that to `code_str` — which only
 * borrows the pointer — leaves a dangling read the moment the handler
 * returns. See code_abi.h. */
void code_str_owned(CodeValue *out, const char *s) {
    size_t n = strlen(s);
    char *buf = heap_alloc(n + 1);
    memcpy(buf, s, n + 1);
    code_release(out);
    out->tag = CODE_STR;
    out->heap = 1;
    out->str = buf;
}

/* Deep-copies a value produced by a *different* copy of this runtime (a
 * dlopen'd module) into a fresh, host-owned value — see the section comment
 * above for why this can never be a plain assignment or retain. */
static void code_native_copy_in(CodeValue *out, const CodeValue *from) {
    switch (from->tag) {
    case CODE_NUMBER:
        code_number(out, from->number);
        return;
    case CODE_STR:
        code_str_owned(out, from->str);
        return;
    case CODE_BOOL:
        code_bool(out, from->boolean);
        return;
    case CODE_NULL:
        code_null(out);
        return;
    case CODE_ARRAY: {
        // Zero-initialized (calloc, not malloc): each recursive
        // code_native_copy_in call below may write a CODE_STR/CODE_ARRAY/
        // CODE_OBJECT result via a constructor that calls code_release(out)
        // *first* (see code_str_owned) — that reads out->heap, which has to
        // start real rather than garbage, same hazard code_make_result's
        // doc comment already flags.
        void *slots = LEN(from) > 0 ? calloc((size_t)LEN(from), CODE_VALUE_SLOT_SIZE) : NULL;
        for (long long i = 0; i < LEN(from); i++) {
            code_native_copy_in(slot_at(slots, i), slot_at(ITEMS(from), i));
        }
        code_array(out, slots, LEN(from));
        for (long long i = 0; i < LEN(from); i++) {
            code_release(slot_at(slots, i));
        }
        free(slots);
        return;
    }
    case CODE_OBJECT: {
        const char **keys = LEN(from) > 0 ? malloc((size_t)LEN(from) * sizeof(const char *)) : NULL;
        // Zero-initialized for the same reason the CODE_ARRAY case above is.
        void *slots = LEN(from) > 0 ? calloc((size_t)LEN(from), CODE_VALUE_SLOT_SIZE) : NULL;
        for (long long i = 0; i < LEN(from); i++) {
            keys[i] = KEYS(from)[i];
            code_native_copy_in(slot_at(slots, i), slot_at(ITEMS(from), i));
        }
        code_object(out, keys, slots, LEN(from));
        for (long long i = 0; i < LEN(from); i++) {
            code_release(slot_at(slots, i));
        }
        free(keys);
        free(slots);
        return;
    }
    }
}

/* ---- Inbound: a module speaking first --------------------------------------
 *
 * The other direction across the boundary. `code_module_dispatch` answers a
 * question; this lets a module raise one — a `terminal` pushing `Key`
 * particles as they arrive, say — which is what an event loop is made of.
 *
 * Deep-copied on the way in, exactly like a dispatch result: the value
 * belongs to the module's allocator until this returns, so nothing may be
 * retained. See `code_native_copy_in`.
 *
 * Callable from a thread the program knows nothing about: a module that
 * spawns one (a timer, a socket accept loop) pushes from there, which is what
 * makes an event loop more than polling. Everything that costs is inside the
 * lock — the ring's three fields *and* the deep copy that fills a slot, so a
 * poll never sees a half-built value. The copy allocates, which is why
 * `live_blocks` is atomic and `code_release`'s work stack is thread-local;
 * see both.
 *
 * The rest of the runtime stays single-threaded and unlocked. That holds
 * because a pushed value is only ever reachable from one thread at a time:
 * the pusher builds it alone, the ring holds it under this lock, and the
 * program owns it alone once `code_poll_inbound` hands it over. */

/* How long `code_host_park` sleeps before re-asking whether anything is still
 * serving. **Not a poll interval** — delivery is exact, since every push
 * signals below. This only bounds how long it takes to notice a module that
 * *stopped* serving without pushing on its way out. `interpreter.rs`'s
 * `SERVING_RECHECK` is the same number, because the two output modes have to
 * idle the same way. */
#define CODE_SERVING_RECHECK_SECONDS 1

#ifndef CODE_WASM
/* Raised by every push, waited on by `code_host_park`.
 *
 * One signal for every module rather than one per ring: the program waits for
 * *something* to arrive, not for a particular module to speak, and a condvar
 * per ring would mean choosing which one to sleep on. `interpreter.rs` keeps a
 * single pair for exactly the same reason.
 *
 * A count, not a bare signal, because the two sides race by design: a push can
 * land between the drain that emptied the rings and the park that follows it.
 * A signal sent in that window would be sent to nobody. A count survives the
 * gap — the parker sees it is already non-zero and returns without sleeping. */
static pthread_mutex_t code_wakeup_lock = PTHREAD_MUTEX_INITIALIZER;
static pthread_cond_t code_wakeup_cond = PTHREAD_COND_INITIALIZER;
static unsigned long code_wakeups = 0;
#endif

void code_emit_inbound(void *queue, const CodeValue *value) {
    if (!queue || !value) {
        return;
    }
    NativeHandle *nh = (NativeHandle *)queue;
    code_mutex_lock(&nh->lock);
    if (nh->closed) {
        /* The program has finished and drained. Nothing would ever read this,
         * and allocating it would read as a leak. */
        code_mutex_unlock(&nh->lock);
        return;
    }
    int slot;
    if (nh->inbound_count == CODE_INBOUND_CAPACITY) {
        /* Full: drop the oldest so a runaway module costs bounded memory
         * rather than unbounded. */
        slot = nh->inbound_head;
        code_release(&nh->inbound[slot]);
        memset(&nh->inbound[slot], 0, sizeof(CodeValue));
        nh->inbound_head = (nh->inbound_head + 1) % CODE_INBOUND_CAPACITY;
    } else {
        slot = (nh->inbound_head + nh->inbound_count) % CODE_INBOUND_CAPACITY;
        nh->inbound_count++;
    }
    code_native_copy_in(&nh->inbound[slot], value);
    code_mutex_unlock(&nh->lock);
#ifndef CODE_WASM
    /* After the ring's own lock is released, never while holding it: the
     * parker wakes into a drain, and waking it inside that critical section
     * only means it blocks again on the way out. */
    pthread_mutex_lock(&code_wakeup_lock);
    code_wakeups++;
    pthread_cond_broadcast(&code_wakeup_cond);
    pthread_mutex_unlock(&code_wakeup_lock);
#endif
    /* And the host's, when this program is a guest. Its own wakeup above is
     * signalled either way but nobody waits on it: a library's stream ran
     * once and returned, so the loop that would drain this queue belongs to
     * whoever opened it. */
    if (code_host && code_host->wake) {
        code_host->wake(code_host_ctx);
    }
}

/* Whether one linked module still expects to speak. Generated code asks this
 * of every `.so` handle it holds; the answer decides whether the program stays
 * up past its last statement. A module exporting no `code_module_serving`
 * holds nothing open, which is what keeps every program that ever worked
 * ending exactly when it used to. */
int code_native_serving(void *handle) {
    if (!handle) {
        return 0;
    }
    NativeHandle *nh = (NativeHandle *)handle;
    return nh->serving ? nh->serving() : 0;
}

/* Sleep until something is pushed, or until it is time to re-ask who is still
 * serving. Called once per iteration of the keep-alive loop generated at the
 * end of `main` (see codegen.rs's `gen_keep_alive`).
 *
 * This is why an application writes no keep-alive loop of its own, and why
 * that loop could never have been a plain `join`: a pushed particle is
 * dispatched to the program's own handlers, which run on *this* thread
 * between statements. A thread blocked in `join` is not between statements,
 * and every request would time out one frame below the handler that should
 * have answered it. So: park, wake on a push, drain, park again. */
void code_host_park(void) {
#ifndef CODE_WASM
    struct timespec deadline;
    clock_gettime(CLOCK_REALTIME, &deadline);
    deadline.tv_sec += CODE_SERVING_RECHECK_SECONDS;

    pthread_mutex_lock(&code_wakeup_lock);
    while (code_wakeups == 0) {
        /* Non-zero is a timeout (or an error we treat as one): stop waiting
         * and let the caller re-ask whether anything is still serving. */
        if (pthread_cond_timedwait(&code_wakeup_cond, &code_wakeup_lock, &deadline) != 0) {
            break;
        }
    }
    /* Consumed whole: the drain that follows hands over everything queued in
     * one pass, so one park answers every push that led to it. */
    code_wakeups = 0;
    pthread_mutex_unlock(&code_wakeup_lock);
#endif
}

/* Pops the oldest queued particle into `out`, or returns 0 when the queue is
 * empty (including for a module that never pushes at all, and for a handle
 * that hasn't been linked yet — the generated drain loop runs over every
 * module global, some of which may still be null). */
int code_poll_inbound(void *queue, CodeValue *out) {
    if (!queue) {
        return 0;
    }
    NativeHandle *nh = (NativeHandle *)queue;
    code_mutex_lock(&nh->lock);
    if (nh->inbound_count == 0) {
        code_mutex_unlock(&nh->lock);
        return 0;
    }
    int slot = nh->inbound_head;
    code_copy(out, &nh->inbound[slot]);
    code_release(&nh->inbound[slot]);
    memset(&nh->inbound[slot], 0, sizeof(CodeValue));
    nh->inbound_head = (nh->inbound_head + 1) % CODE_INBOUND_CAPACITY;
    nh->inbound_count--;
    code_mutex_unlock(&nh->lock);
    return 1;
}

/* Hands a module the answer to a particle it pushed: whatever the program's
 * handler returned, or null when nothing handled it. Called by the generated
 * drain after each dispatch (see codegen.rs's `gen_drain_body`), and a no-op
 * for the modules — most of them — that export no
 * `code_module_inbound_reply`.
 *
 * `particle` and `result` stay the host's. The module reads what it needs
 * during the call and copies it out; nothing is retained across the return,
 * which is the same boundary rule every other crossing here follows. */
void code_native_reply(void *handle, const CodeValue *particle, const CodeValue *result) {
    if (!handle) {
        return;
    }
    NativeHandle *nh = (NativeHandle *)handle;
    if (nh->reply) {
        nh->reply(particle, result);
    }
}

/* Frees the small `NativeHandle` `code_native_open` allocated — called once
 * per linked module as part of the program's end-of-run cleanup (see
 * codegen.rs's `emit_cleanup`), the same "owns nothing when it exits" rule
 * `code_check_leaks` already holds every `CodeValue` slot to. Does not
 * `dlclose` the module itself: nothing depends on unloading it before the
 * process exits anyway, and dlclose has its own sharp edges (a module with
 * `__attribute__((destructor))` running at an unexpected time, symbols still
 * live on a stack frame mid-unwind) that aren't worth taking on for no
 * actual benefit here. */
void code_native_close(void *handle) {
    if (!handle) {
        return;
    }
    NativeHandle *nh = (NativeHandle *)handle;
    /* Anything still queued at exit is this runtime's to free — the
     * "owns nothing when it exits" rule `code_check_leaks` enforces. */
    code_mutex_lock(&nh->lock);
    for (int i = 0; i < nh->inbound_count; i++) {
        code_release(&nh->inbound[(nh->inbound_head + i) % CODE_INBOUND_CAPACITY]);
    }
    nh->inbound_count = 0;
    nh->closed = 1;
    int has_inbound = nh->has_inbound;
    code_mutex_unlock(&nh->lock);
    if (has_inbound) {
        /* Deliberately not freed. A module that took the inbound channel may
         * still have a thread holding this pointer, and there is no way to
         * ask it to stop — the ABI has no shutdown call, on purpose (a module
         * that must be asked politely before the program may exit is a module
         * that can hang it). Leaving the struct mapped, with `closed` set,
         * turns a late push into a no-op instead of a use-after-free. It is
         * one small malloc per linked module, and `code_check_leaks` doesn't
         * see it: this is not a refcounted block. */
        return;
    }
    free(nh);
}

/* `emit <particle> to <alias> [get <name>]` for a linked native module.
 * `handle` is whatever `code_native_open` returned for that alias. */
void code_native_dispatch(void *handle, CodeValue *out, const CodeValue *particle) {
    code_null(out);
    if (handle && ((NativeHandle *)handle)->from_host) {
        /* Answered through the host, and the deep copy still happens: the
         * answer was built by the host's copy of this runtime, so it is no
         * more ours to keep than a `.so`'s would be. */
        NativeHandle *nh = (NativeHandle *)handle;
        CodeValue result = {0};
        nh->host.dispatch(nh->host.ctx, &result, particle);
        code_native_copy_in(out, &result);
        nh->host.release(nh->host.ctx, &result);
        return;
    }
    if (!handle) {
        /* Only reachable through a stale alias: a library that was released
         * and then dispatched to without being initialised again. Saying so
         * beats dereferencing the closed handle. */
        fail("this module was released");
        return;
    }
    NativeHandle *nh = (NativeHandle *)handle;
    CodeValue result = {0};
    if (nh->instance_dispatch) {
        nh->instance_dispatch(nh->instance, &result, particle);
    } else {
        nh->dispatch(&result, particle);
    }
    code_native_copy_in(out, &result);
    nh->release(&result);
}

/* ---- How deep one handler may go -------------------------------------
 *
 * A handler may be on the call stack more than once — a base module asks a
 * linked module, which asks its base back, which asks on — but not without
 * bound: past this many live invocations of one handler the emit answers
 * an `Exception`, which is a loop being caught rather than the stack being
 * overflowed. The compiled prologue (`codegen.rs`) counts against this; the
 * interpreter's `MOST_LIVE` is the same number, on purpose. */
int code_most_live(void) { return CODE_MOST_LIVE; }

/* The other side of the same rule, for a module written in `code`. Its
 * exported `code_module_dispatch` (generated — see `define_library_exports`
 * in codegen.rs) is handed a particle built by *another* copy of this
 * runtime: the program that linked it. That particle is the caller's, and
 * the caller frees it when the call returns. A handler that kept a piece
 * of it — `last = particle._class` — kept a pointer into memory that was
 * never counted in this module's bookkeeping, and read noise, or worse,
 * on the next call.
 *
 * So a particle is copied in before a single handler sees it, exactly as
 * the module's answer is copied out by `code_native_dispatch` on the way
 * back. Values never cross this boundary by shared ownership, in either
 * direction. `chain` is the module's own `_code_dispatch_this`; the copy is
 * released once it has answered, having by then retained whatever a
 * handler chose to keep. */
#ifndef CODE_WASM
static int flows_hosted;
long long code_flow_begin(const char *target, const CodeValue *particle, const char *root_from);
void code_flow_finish(long long id, const CodeValue *answer);
#endif
void code_dispatch_copied(void (*chain)(CodeValue *out, const CodeValue *particle), CodeValue *out,
                          const CodeValue *particle) {
    CodeValue own = {0};
    code_native_copy_in(&own, particle);
#ifndef CODE_WASM
    /* A call from whoever holds this library is where an interaction of its
     * starts, seen from inside: a root from `host`, which the host splices
     * under the step that called. Only once the host asked for it
     * (`code_module_flows`), and against this library's own copy of the
     * particle — the host's belongs to the host's allocator. */
    long long flow = flows_hosted ? code_flow_begin("this", &own, "host") : -1;
#endif
    chain(out, &own);
#ifndef CODE_WASM
    code_flow_finish(flow, out);
#endif
    code_release(&own);
}

/* ---- Modules linked while the program is running ---------------------
 *
 * `link <expr> as <name>` inside a handler (see `ast::Stmt::LinkRuntime`).
 * Everything below exists because such a module has no alias to be found
 * by: the program holds it as an ordinary value and may pass it around, so
 * this table is the only thing that outlives the binding.
 *
 * Rows are appended and never reused, even after `unlink` empties one. Reuse
 * would turn a stale address into a *live* one naming an unrelated
 * module — the exact failure this table exists to prevent — and an
 * ever-growing array of NULLs is much the cheaper problem.
 *
 * Not locked. Every one of these runs on the thread executing the program's
 * statements, the same thread that drains the inbound ring, and a module
 * that could speak from a thread of its own is refused at link time. */
typedef struct HostedGuest HostedGuest;
typedef struct {
    NativeHandle *handle;
    /* The path this row was opened from, owned here — what a second `link`
     * of the same file is matched against. NULL once the row is empty. */
    char *path;

    /* Which guest row this program keeps for it, or -1 for a module that
     * cannot be hosted. A row, not a pointer — see the hosting tables. */
    long long guest;

    /* The name it was linked as — a codegen literal, never freed. Where a
     * trace says a particle this module pushed came from. */
    const char *name;

    /* Its `code_module_flows_take`, when this program defines `Trace` and the
     * library can record — NULL otherwise. */
    void (*flows_take)(CodeValue *out);
} RuntimeModule;

static RuntimeModule *runtime_modules = NULL;
static long long runtime_module_count = 0;
static long long runtime_module_cap = 0;

/* The field an address value carries, kept in step with
 * `interpreter::MODULE_FIELD` — the two backends mint the same value. */
#define CODE_MODULE_FIELD "_module"

/* The row an address names, or -1 with the reason failed. Strict about the
 * shape on purpose: an address is something the runtime minted, so anything
 * else is a program mistake worth naming precisely rather than a lookup that
 * quietly finds nothing. */
static long long module_row(const CodeValue *address) {
    if (address->tag != CODE_OBJECT) {
        fail("expected a module address (from a 'link' inside a handler)");
        return -1;
    }
    const CodeValue *row = find_field(address, CODE_MODULE_FIELD);
    if (!row || row->tag != CODE_NUMBER || row->number < 0) {
        fail("expected a module address (from a 'link' inside a handler)");
        return -1;
    }
    return (long long)row->number;
}

/* The module a valid address names, or NULL with the reason failed. Both
 * readings of "nothing here" — a row past the end and a row `unlink` emptied
 * — are the same mistake seen from the program's side, so they read alike. */
static NativeHandle *module_at(const CodeValue *address) {
    long long row = module_row(address);
    if (row < 0) {
        return NULL;
    }
    if (row >= runtime_module_count || !runtime_modules[row].handle) {
        fail("this module has been unlinked");
        return NULL;
    }
    return runtime_modules[row].handle;
}

/* Writes the address value for `row` into `out`. */
static void module_address(CodeValue *out, long long row) {
    const char *keys[1] = {CODE_MODULE_FIELD};
    _Alignas(8) char slots[CODE_VALUE_SLOT_SIZE] = {0};
    code_number(slot_at(slots, 0), (double)row);
    code_object(out, keys, slots, 1);
    code_release(slot_at(slots, 0));
}

/* ---- Hosting (debug build) ---------------------------------------------- */
struct HostedGuest {
    char *app;
};

typedef struct {
    long long guest;
    char *name;
    int offered;
} HostedModule;

static HostedGuest *hosted_guests = NULL;
static long long hosted_guest_count = 0;
static long long hosted_guest_cap = 0;
static HostedModule *hosted_modules = NULL;
static long long hosted_module_count = 0;
static long long hosted_module_cap = 0;

static void *row_handle(long long row) { return (void *)(uintptr_t)(row + 1); }
static long long handle_row(void *handle) { return (long long)(uintptr_t)handle - 1; }

/* The program's own dispatch chain — what `emit ... to this` calls. Filled
 * in at startup by generated code, because only codegen knows the chain's
 * name; NULL in a program with no handlers at all, which then offers
 * nothing. */
static void (*code_program_dispatch)(CodeValue *out, const CodeValue *particle) = NULL;

void code_set_program_dispatch(void (*fn)(CodeValue *out, const CodeValue *particle)) {
    code_program_dispatch = fn;
}

#ifndef CODE_WASM
/* ---- Flows — what one interaction did, for the program's `Trace` --------
 *
 * The compiled half of `src/flows.rs`, which this must match field for field
 * and rule for rule; the design is `docs/todo/trace-handler.md`. Only a
 * program that defines `Trace` calls any of this — codegen emits the calls
 * for no one else — and it is switched on by `code_flow_on` at the start of
 * `main`.
 *
 * Nothing here is `heap_alloc`ed: a step's class name is `malloc`ed and freed
 * again when the trace is delivered, so the leak check sees only the Trace
 * value itself, which the program owns once it is handed over. The root's
 * particle is retained, not copied, and released on delivery. */
#define FLOW_MOST_STEPS 500
typedef struct {
    long long parent;
    char *target, *class_name;
    /* Which held program it ran in, or NULL for this program's own step. */
    char *program;
    double at, ms;
    int ok;
} FlowStep;
static int flows_on, flows_delivering, flow_running;
static FlowStep flow_steps[FLOW_MOST_STEPS];
static long long flow_open[FLOW_MOST_STEPS];
static long long flow_len, flow_depth, flow_dropped;
static double flow_started, flow_clock;
static char *flow_from;
static CodeValue flow_particle;
static const char **flow_handled;
static size_t flow_handled_len, flow_handled_cap;
/* Held by a host that asked for this library's steps (`code_module_flows`),
 * `flows_hosted` (declared above `code_dispatch_copied`) sends a finished
 * interaction to the outbox for the host to collect, rather than to a
 * `Trace` handler of its own. */
static CodeValue *flow_outbox;
static size_t flow_outbox_len, flow_outbox_cap;
/* Whole interactions a held program had on its own, waiting to be handed
 * to `Trace` the moment nothing of this program's is running. */
static CodeValue *flow_pending;
static size_t flow_pending_len, flow_pending_cap;

static double flow_mono_ms(void) {
    struct timespec t;
    clock_gettime(CLOCK_MONOTONIC, &t);
    return (double)t.tv_sec * 1000.0 + (double)t.tv_nsec / 1e6;
}
static double flow_unix_ms(void) {
    struct timespec t;
    clock_gettime(CLOCK_REALTIME, &t);
    return (double)t.tv_sec * 1000.0 + (double)t.tv_nsec / 1e6;
}
static const char *flow_class(const CodeValue *particle) {
    if (particle->tag != CODE_OBJECT) return "";
    const CodeValue *c = find_field(particle, "_class");
    return c && c->tag == CODE_STR && c->str ? c->str : "";
}
static double flow_round(double ms) { return floor(ms * 1000.0 + 0.5) / 1000.0; }

void code_flow_on(void) { flows_on = 1; }

/* A class the program answers. A pushed particle nobody answers is dropped
 * rather than handled, so it is no interaction — the interpreter asks its
 * handler table the same question. */
void code_flow_handles(const char *class_name) {
    flow_handled = grow(flow_handled, &flow_handled_cap, flow_handled_len + 1, sizeof(const char *));
    flow_handled[flow_handled_len++] = class_name;
}
static int flow_is_handled(const CodeValue *particle) {
    const char *class_name = flow_class(particle);
    for (size_t i = 0; i < flow_handled_len; i++) {
        if (strcmp(flow_handled[i], class_name) == 0) return 1;
    }
    return 0;
}

/* Opens a boundary; answers the step to close, or a negative number when
 * nothing was opened (-1: not recording, -2: past the cap, only counted).
 * `root_from` is where a root came from, NULL when something is already
 * running. The root is always step 0 — that is how `code_flow_finish` knows
 * the interaction is over. */
long long code_flow_begin(const char *target, const CodeValue *particle, const char *root_from) {
    if (!flows_on || flows_delivering) return -1;
    if (!flow_running) {
        if (!root_from) return -1;
        flow_running = 1;
        flow_started = flow_unix_ms();
        flow_clock = flow_mono_ms();
        flow_from = strdup(root_from);
        memset(&flow_particle, 0, sizeof flow_particle);
        code_copy(&flow_particle, particle);
        flow_len = flow_depth = flow_dropped = 0;
    }
    if (flow_len >= FLOW_MOST_STEPS) {
        flow_dropped++;
        return -2;
    }
    long long id = flow_len++;
    flow_steps[id] = (FlowStep){
        flow_depth ? flow_open[flow_depth - 1] : -1,
        strdup(target),
        strdup(flow_class(particle)),
        NULL,
        flow_mono_ms() - flow_clock,
        0.0,
        1,
    };
    flow_open[flow_depth++] = id;
    return id;
}

/* The same, for a particle a module pushed: a root from `from`, but only
 * when the program answers its class. */
long long code_flow_begin_push(const char *from, const CodeValue *particle) {
    if (!flows_on || flow_running || !flow_is_handled(particle)) return -1;
    return code_flow_begin("this", particle, from);
}

/* Where a finished trace goes: to the host that asked for it, when this is a
 * held library, otherwise to this program's own `Trace` — run with nothing
 * recording, so the handler's own work is never another trace. Takes the
 * value over either way. */
static void flow_hand_over(CodeValue trace) {
    if (flows_hosted) {
        flow_outbox = grow(flow_outbox, &flow_outbox_cap, flow_outbox_len + 1, sizeof(CodeValue));
        flow_outbox[flow_outbox_len++] = trace;
        return;
    }
    if (code_program_dispatch) {
        CodeValue answer = {0};
        flows_delivering = 1;
        code_program_dispatch(&answer, &trace);
        flows_delivering = 0;
        code_release(&answer);
    }
    code_release(&trace);
}

static void flow_deliver_pending(void) {
    size_t next = 0;
    while (!flow_running && next < flow_pending_len) {
        flow_hand_over(flow_pending[next++]);
    }
    if (next == flow_pending_len) {
        flow_pending_len = 0;
    } else {
        memmove(flow_pending, flow_pending + next, (flow_pending_len - next) * sizeof(CodeValue));
        flow_pending_len -= next;
    }
}

static const CodeValue *flow_field(const CodeValue *v, const char *name) {
    return v && v->tag == CODE_OBJECT ? find_field(v, name) : NULL;
}
static double flow_number(const CodeValue *v) { return v && v->tag == CODE_NUMBER ? v->number : 0.0; }
static const char *flow_text(const CodeValue *v) {
    return v && v->tag == CODE_STR && v->str ? v->str : "";
}

/* `obj` with a null `program` field filled in — how a held program's own
 * interaction says which one it was. */
static void flow_stamped(CodeValue *out, const CodeValue *obj, const char *program) {
    if (obj->tag != CODE_OBJECT) {
        code_copy(out, obj);
        return;
    }
    char *values = calloc((size_t)(LEN(obj) ? LEN(obj) : 1), CODE_VALUE_SLOT_SIZE);
    if (!values) code_runtime_error("out of memory");
    for (long long i = 0; i < LEN(obj); i++) {
        const CodeValue *v = slot_at(ITEMS(obj), i);
        if (strcmp(KEYS(obj)[i], "program") == 0 && v->tag == CODE_NULL)
            code_str_owned(slot_at(values, i), program);
        else
            code_copy(slot_at(values, i), v);
    }
    code_object(out, KEYS(obj), values, LEN(obj));
    for (long long i = 0; i < LEN(obj); i++) code_release(slot_at(values, i));
    free(values);
}

/* Adds a held program's steps under `parent`, renumbered into this
 * interaction and placed from the step that made the call — the `started`
 * times are whole milliseconds, and a guest's steps are often a fraction of
 * one. Past the cap they are counted. Must match `flows.rs`'s `splice`. */
static void flow_splice(long long parent, const CodeValue *trace, const char *program) {
    const CodeValue *steps = flow_field(trace, "steps");
    double offset = flow_steps[parent].at;
    long long base = flow_len;
    for (long long i = 0; steps && steps->tag == CODE_ARRAY && i < LEN(steps); i++) {
        const CodeValue *step = slot_at(ITEMS(steps), i);
        if (flow_len >= FLOW_MOST_STEPS) {
            flow_dropped++;
            continue;
        }
        const CodeValue *own_parent = flow_field(step, "parent");
        const CodeValue *own_program = flow_field(step, "program");
        const CodeValue *ok = flow_field(step, "ok");
        flow_steps[flow_len++] = (FlowStep){
            own_parent && own_parent->tag == CODE_NUMBER ? base + (long long)own_parent->number : parent,
            strdup(flow_text(flow_field(step, "target"))),
            strdup(flow_text(flow_field(step, "class"))),
            strdup(own_program && own_program->tag == CODE_STR ? flow_text(own_program) : program),
            offset + flow_number(flow_field(step, "at")),
            flow_number(flow_field(step, "ms")),
            ok && ok->tag == CODE_BOOL && ok->boolean,
        };
    }
    flow_dropped += (long long)flow_number(flow_field(trace, "dropped"));
}

/* What a held program reported: the one whose root came from `host` is this
 * program's own call seen from inside, spliced under the innermost step
 * still open — the emit that made the call, which closes only after this.
 * Anything else it did on its own, and waits in `flow_pending`. Must match
 * `flows.rs`'s `absorb`. */
static void flow_absorb(const CodeValue *traces, const char *program, int called) {
    for (long long i = 0; traces->tag == CODE_ARRAY && i < LEN(traces); i++) {
        const CodeValue *trace = slot_at(ITEMS(traces), i);
        int from_host = strcmp(flow_text(flow_field(flow_field(trace, "root"), "from")), "host") == 0;
        if (from_host && called && flow_running && flow_depth > 0) {
            flow_splice(flow_open[flow_depth - 1], trace, program);
            continue;
        }
        /* A call this program made while it was not recording — the `Trace`
         * handler itself, shipping a trace to a held library — is dropped.
         * Queued, it would come back as a trace, be shipped, and make
         * another, forever. */
        if (from_host) continue;
        /* Stamped: the root, and every step that does not already say. */
        const char *keys[7];
        char *fields = calloc((size_t)(LEN(trace) ? LEN(trace) : 1), CODE_VALUE_SLOT_SIZE);
        if (!fields) code_runtime_error("out of memory");
        for (long long f = 0; f < LEN(trace) && f < 7; f++) {
            const CodeValue *v = slot_at(ITEMS(trace), f);
            keys[f] = KEYS(trace)[f];
            if (strcmp(KEYS(trace)[f], "root") == 0) {
                flow_stamped(slot_at(fields, f), v, program);
            } else if (strcmp(KEYS(trace)[f], "steps") == 0 && v->tag == CODE_ARRAY) {
                char *items = calloc((size_t)(LEN(v) ? LEN(v) : 1), CODE_VALUE_SLOT_SIZE);
                if (!items) code_runtime_error("out of memory");
                for (long long s = 0; s < LEN(v); s++)
                    flow_stamped(slot_at(items, s), slot_at(ITEMS(v), s), program);
                code_array(slot_at(fields, f), items, LEN(v));
                for (long long s = 0; s < LEN(v); s++) code_release(slot_at(items, s));
                free(items);
            } else {
                code_copy(slot_at(fields, f), v);
            }
        }
        CodeValue stamped = {0};
        long long n = LEN(trace) < 7 ? LEN(trace) : 7;
        code_object(&stamped, keys, fields, n);
        for (long long f = 0; f < n; f++) code_release(slot_at(fields, f));
        free(fields);
        flow_pending = grow(flow_pending, &flow_pending_cap, flow_pending_len + 1, sizeof(CodeValue));
        flow_pending[flow_pending_len++] = stamped;
    }
}

/* Asks one held library for what it recorded, copied into this runtime's
 * heap and released in its own. `take` is its `code_module_flows_take`. */
static void flow_collect(void (*take)(CodeValue *), void (*release)(CodeValue *),
                         const char *program, int called) {
    if (!flows_on || !take) return;
    CodeValue theirs = {0};
    take(&theirs);
    CodeValue ours = {0};
    code_native_copy_in(&ours, &theirs);
    release(&theirs);
    if (ours.tag == CODE_ARRAY && LEN(&ours) > 0) flow_absorb(&ours, program, called);
    code_release(&ours);
}

static void flow_deliver(void) {
    long long n = flow_len;
    char *items = calloc((size_t)(n ? n : 1), CODE_VALUE_SLOT_SIZE);
    if (!items) code_runtime_error("out of memory");
    for (long long i = 0; i < n; i++) {
        FlowStep *step = &flow_steps[i];
        const char *keys[8] = {"id", "parent", "target", "class", "at", "ms", "ok", "program"};
        char fields[8 * CODE_VALUE_SLOT_SIZE] = {0};
        code_number(slot_at(fields, 0), (double)i);
        if (step->parent < 0) code_null(slot_at(fields, 1));
        else code_number(slot_at(fields, 1), (double)step->parent);
        code_str_owned(slot_at(fields, 2), step->target);
        code_str_owned(slot_at(fields, 3), step->class_name);
        code_number(slot_at(fields, 4), flow_round(step->at));
        code_number(slot_at(fields, 5), flow_round(step->ms));
        code_bool(slot_at(fields, 6), step->ok);
        if (step->program) code_str_owned(slot_at(fields, 7), step->program);
        else code_null(slot_at(fields, 7));
        code_object(slot_at(items, i), keys, fields, 8);
        for (int f = 0; f < 8; f++) code_release(slot_at(fields, f));
        free(step->target);
        free(step->class_name);
        free(step->program);
    }
    char root_fields[4 * CODE_VALUE_SLOT_SIZE] = {0};
    const char *root_keys[4] = {"from", "class", "particle", "program"};
    code_str_owned(slot_at(root_fields, 0), flow_from);
    code_str_owned(slot_at(root_fields, 1), flow_class(&flow_particle));
    code_copy(slot_at(root_fields, 2), &flow_particle);
    code_null(slot_at(root_fields, 3));

    const char *keys[7] = {"_class", "root", "started", "ms", "ok", "steps", "dropped"};
    char fields[7 * CODE_VALUE_SLOT_SIZE] = {0};
    code_str(slot_at(fields, 0), "Trace");
    code_object(slot_at(fields, 1), root_keys, root_fields, 4);
    code_number(slot_at(fields, 2), floor(flow_started));
    code_number(slot_at(fields, 3), n ? flow_round(flow_steps[0].ms) : 0.0);
    code_bool(slot_at(fields, 4), n ? flow_steps[0].ok : 1);
    code_array(slot_at(fields, 5), items, n);
    code_number(slot_at(fields, 6), (double)flow_dropped);
    CodeValue trace = {0};
    code_object(&trace, keys, fields, 7);
    for (int f = 0; f < 7; f++) code_release(slot_at(fields, f));
    for (int f = 0; f < 4; f++) code_release(slot_at(root_fields, f));
    for (long long i = 0; i < n; i++) code_release(slot_at(items, i));
    free(items);

    /* Handed over with nothing recording, so the handler's own work is never
     * another trace; what it answers is nobody's business. */
    free(flow_from);
    flow_from = NULL;
    code_release(&flow_particle);
    memset(&flow_particle, 0, sizeof flow_particle);
    flow_running = 0;
    flow_len = flow_depth = flow_dropped = 0;
    flow_hand_over(trace);
    flow_deliver_pending();
}

/* A host that wants this library's steps in its own traces says so, once,
 * right after linking it. Optional, like every hosting export: a host that
 * never asks leaves recording off, and a library built before this existed
 * simply has no such symbol. */
void code_module_flows(void) {
    flows_on = 1;
    flows_hosted = 1;
}

/* Every interaction finished since the last call, as an array of `Trace`
 * particles, oldest first. The host calls it right after each call into
 * this library and after each drain of it, so nothing waits here long. */
void code_module_flows_take(CodeValue *out) {
    char *items = calloc(flow_outbox_len ? flow_outbox_len : 1, CODE_VALUE_SLOT_SIZE);
    if (!items) code_runtime_error("out of memory");
    for (size_t i = 0; i < flow_outbox_len; i++) *slot_at(items, (long long)i) = flow_outbox[i];
    memset(out, 0, sizeof *out);
    code_array(out, items, (long long)flow_outbox_len);
    for (size_t i = 0; i < flow_outbox_len; i++) code_release(slot_at(items, (long long)i));
    free(items);
    flow_outbox_len = 0;
}

/* Closes a boundary opened by `code_flow_begin`. A step a failure jumped past
 * (its frame ended before it could close) is closed here too, as not ok —
 * whatever is still open above `id` ended when this did. Closing the root
 * ends the interaction and hands its `Trace` to the program. */
void code_flow_finish(long long id, const CodeValue *answer) {
    if (id < 0 || !flow_running) return;
    double now = flow_mono_ms() - flow_clock;
    while (flow_depth > 0) {
        long long top = flow_open[--flow_depth];
        FlowStep *step = &flow_steps[top];
        step->ms = now - step->at;
        if (top == id) {
            step->ok = strcmp(flow_class(answer), "Exception") != 0;
            break;
        }
        step->ok = 0;
    }
    if (id == 0) flow_deliver();
}
#endif

/* ---- Events — a whole particle, built where the event happens ------------
 *
 * What a browser needs and a socket does not: the page fires back. While it
 * is drawing, the program says what an event should *mean* — a click on this
 * button is a `Remove { id = 7 }`, a keystroke in this box is a `Typed`. When
 * it happens the host sends that back, with whatever it learned in the
 * meantime, and the program's own handlers answer it. Nothing is kept
 * between the drawing and the firing: there is no table of live listeners to
 * grow, go stale, or be swept.
 *
 * It arrives as JSON, because the host is a page and that is the page's own
 * way of writing a value down. A whole particle, not a class and one string:
 * an event is an event *about* something, and `Remove { id = 7, confirmed =
 * true }` is what the program wants to receive, not two fields it has to
 * reassemble.
 *
 * The text is read out of a buffer of ours, and the host is told how much
 * room it has, so that nothing here ever trusts an address or a length that
 * came from outside: the read stays inside this program's own array, bounded
 * by a capacity this program set.
 *
 * That is containment, not protection, and the difference is worth being
 * exact about. A page and the module it loaded share one linear memory, and
 * the page can read and write all of it whenever it likes — there is no
 * boundary between them and there cannot be one. What this buys is that an
 * honest host's mistake stops here instead of becoming a corrupt value the
 * program then works with. Whatever protects a program from the page it runs
 * in lives somewhere else entirely: on the other side of the network, where
 * the two really are separate.
 *
 * One buffer, refilled per event, because events are handled one at a time —
 * `code_event_fire` has returned before the next can be sent.
 *
 * It grows to what an event needs and never shrinks. A fixed 64 KB was
 * enough for a click and not for a recording: a page that wrote more than
 * fit was cut off mid-JSON, the reader refused it, and the program heard
 * nothing — a microphone's answer lost on the doorstep, with nothing to say
 * so. So a host asks for the room first (`code_event_text_reserve`), and the
 * buffer may move when it grows, which is why the host takes the pointer
 * back from that call each time rather than holding one.
 *
 * Not the inbound queue (`code_module_set_inbound`), on purpose. That is for
 * a module speaking on its own initiative into a program that is running a
 * loop. This is the host calling *in*, already inside a call. */

#define CODE_EVENT_MIN 65536
static char *code_event_buf = NULL;
static long long code_event_cap = 0;

/* Room for `n` bytes, and the buffer's address — which may have changed.
 * A host that cannot get the room it asked for is told through the
 * capacity, which is why it reads that after reserving. */
char *code_event_text_reserve(long long n) {
    if (n < CODE_EVENT_MIN) {
        n = CODE_EVENT_MIN;
    }
    if (n > code_event_cap) {
        char *grown = realloc(code_event_buf, (size_t)n + 1);
        if (grown) {
            code_event_buf = grown;
            code_event_cap = n;
        }
    }
    return code_event_buf;
}

char *code_event_text(void) { return code_event_text_reserve(0); }

long long code_event_text_capacity(void) {
    code_event_text_reserve(0);
    return code_event_cap;
}

/* ---- A JSON reader, for that one job -------------------------------------
 *
 * Small on purpose. It reads what `JSON.stringify` writes and nothing more:
 * no comments, no trailing commas, no NaN. What it does not understand it
 * refuses, and a refused event is one the program never hears about — better
 * than a particle assembled out of a guess.
 *
 * Numbers go through the same `number_parse` the language itself uses — which
 * on a freestanding build is a question asked of the host — so a number
 * spelled by a page and one spelled by the language agree. */

static double number_parse(const char *text, size_t len);

typedef struct {
    const char *at;
    const char *end;
    int failed;
} JsonReader;

static int json_value(JsonReader *r, CodeValue *out);

static void json_space(JsonReader *r) {
    while (r->at < r->end && (*r->at == ' ' || *r->at == '\t' || *r->at == '\n' || *r->at == '\r')) {
        r->at++;
    }
}

static int json_char(JsonReader *r, char c) {
    json_space(r);
    if (r->at < r->end && *r->at == c) {
        r->at++;
        return 1;
    }
    return 0;
}

/* Writes one code point out as UTF-8. The only place this reader builds
 * bytes the input did not already contain — `\uXXXX` is how JSON spells
 * anything above ASCII, and a page will produce it for a name with an accent
 * in it. */
static void json_utf8(char **w, unsigned int cp) {
    if (cp < 0x80) {
        *(*w)++ = (char)cp;
    } else if (cp < 0x800) {
        *(*w)++ = (char)(0xC0 | (cp >> 6));
        *(*w)++ = (char)(0x80 | (cp & 0x3F));
    } else {
        *(*w)++ = (char)(0xE0 | (cp >> 12));
        *(*w)++ = (char)(0x80 | ((cp >> 6) & 0x3F));
        *(*w)++ = (char)(0x80 | (cp & 0x3F));
    }
}

static unsigned int json_hex4(JsonReader *r) {
    unsigned int n = 0;
    for (int i = 0; i < 4; i++) {
        if (r->at >= r->end) {
            r->failed = 1;
            return 0;
        }
        char c = *r->at++;
        n <<= 4;
        if (c >= '0' && c <= '9') {
            n |= (unsigned int)(c - '0');
        } else if (c >= 'a' && c <= 'f') {
            n |= (unsigned int)(c - 'a' + 10);
        } else if (c >= 'A' && c <= 'F') {
            n |= (unsigned int)(c - 'A' + 10);
        } else {
            r->failed = 1;
            return 0;
        }
    }
    return n;
}

/* Reads a string into freshly allocated bytes. The caller owns them and
 * frees them; every escape shrinks the text or leaves it the same length, so
 * the input's own length is always enough room. */
static char *json_string(JsonReader *r) {
    if (!json_char(r, '"')) {
        r->failed = 1;
        return NULL;
    }
    char *text = malloc((size_t)(r->end - r->at) + 1);
    if (!text) {
        r->failed = 1;
        return NULL;
    }
    char *w = text;
    while (r->at < r->end) {
        char c = *r->at++;
        if (c == '"') {
            *w = 0;
            return text;
        }
        if (c != '\\') {
            *w++ = c;
            continue;
        }
        if (r->at >= r->end) {
            break;
        }
        char esc = *r->at++;
        switch (esc) {
        case '"': *w++ = '"'; break;
        case '\\': *w++ = '\\'; break;
        case '/': *w++ = '/'; break;
        case 'b': *w++ = '\b'; break;
        case 'f': *w++ = '\f'; break;
        case 'n': *w++ = '\n'; break;
        case 'r': *w++ = '\r'; break;
        case 't': *w++ = '\t'; break;
        case 'u': {
            unsigned int cp = json_hex4(r);
            if (r->failed) {
                free(text);
                return NULL;
            }
            /* A surrogate pair is two escapes for one character; anything
             * else that looks like half a pair is passed through as itself
             * rather than refused, since it is text either way. */
            if (cp >= 0xD800 && cp <= 0xDBFF && r->end - r->at >= 6 && r->at[0] == '\\' &&
                r->at[1] == 'u') {
                const char *save = r->at;
                r->at += 2;
                unsigned int low = json_hex4(r);
                if (!r->failed && low >= 0xDC00 && low <= 0xDFFF) {
                    cp = 0x10000 + ((cp - 0xD800) << 10) + (low - 0xDC00);
                    *w++ = (char)(0xF0 | (cp >> 18));
                    *w++ = (char)(0x80 | ((cp >> 12) & 0x3F));
                    *w++ = (char)(0x80 | ((cp >> 6) & 0x3F));
                    *w++ = (char)(0x80 | (cp & 0x3F));
                    break;
                }
                r->failed = 0;
                r->at = save;
            }
            json_utf8(&w, cp);
            break;
        }
        default:
            free(text);
            r->failed = 1;
            return NULL;
        }
    }
    free(text);
    r->failed = 1;
    return NULL;
}

/* Compared byte by byte rather than with `memcmp`, which the freestanding
 * build does not have — and for three words of four or five letters, a loop
 * is the whole of it. */
static int json_literal(JsonReader *r, const char *word) {
    size_t n = strlen(word);
    if ((size_t)(r->end - r->at) < n) {
        return 0;
    }
    for (size_t i = 0; i < n; i++) {
        if (r->at[i] != word[i]) {
            return 0;
        }
    }
    r->at += n;
    return 1;
}

/* An array or an object, both of which are a list of values with the same
 * bookkeeping — grown by doubling, released as one on failure. */
typedef struct {
    void *values;
    const char **keys;
    long long len;
    long long cap;
} JsonList;

static int json_list_room(JsonList *list, int with_keys) {
    if (list->len < list->cap) {
        return 1;
    }
    long long cap = list->cap ? list->cap * 2 : 8;
    void *values = realloc(list->values, (size_t)cap * CODE_VALUE_SLOT_SIZE);
    if (!values) {
        return 0;
    }
    list->values = values;
    memset((char *)list->values + (size_t)list->len * CODE_VALUE_SLOT_SIZE, 0,
           (size_t)(cap - list->len) * CODE_VALUE_SLOT_SIZE);
    if (with_keys) {
        const char **keys = realloc(list->keys, (size_t)cap * sizeof(const char *));
        if (!keys) {
            return 0;
        }
        list->keys = keys;
    }
    list->cap = cap;
    return 1;
}

static void json_list_free(JsonList *list, int with_keys) {
    for (long long i = 0; i < list->len; i++) {
        code_release(slot_at(list->values, i));
        if (with_keys) {
            free((void *)list->keys[i]);
        }
    }
    free(list->values);
    free(list->keys);
}

static int json_array(JsonReader *r, CodeValue *out) {
    JsonList list = {0};
    if (json_char(r, ']')) {
        code_array(out, NULL, 0);
        return 1;
    }
    for (;;) {
        if (!json_list_room(&list, 0)) {
            r->failed = 1;
            break;
        }
        if (!json_value(r, slot_at(list.values, list.len))) {
            break;
        }
        list.len++;
        if (json_char(r, ',')) {
            continue;
        }
        if (json_char(r, ']')) {
            code_array(out, list.values, list.len);
            json_list_free(&list, 0);
            return 1;
        }
        r->failed = 1;
        break;
    }
    json_list_free(&list, 0);
    return 0;
}

static int json_object(JsonReader *r, CodeValue *out) {
    JsonList list = {0};
    if (json_char(r, '}')) {
        code_object(out, NULL, NULL, 0);
        return 1;
    }
    for (;;) {
        if (!json_list_room(&list, 1)) {
            r->failed = 1;
            break;
        }
        json_space(r);
        char *key = json_string(r);
        if (!key) {
            break;
        }
        list.keys[list.len] = key;
        if (!json_char(r, ':') || !json_value(r, slot_at(list.values, list.len))) {
            free(key);
            r->failed = 1;
            break;
        }
        list.len++;
        if (json_char(r, ',')) {
            continue;
        }
        if (json_char(r, '}')) {
            code_object(out, list.keys, list.values, list.len);
            json_list_free(&list, 1);
            return 1;
        }
        r->failed = 1;
        break;
    }
    json_list_free(&list, 1);
    return 0;
}

static int json_value(JsonReader *r, CodeValue *out) {
    json_space(r);
    if (r->at >= r->end) {
        r->failed = 1;
        return 0;
    }
    char c = *r->at;
    if (c == '{') {
        r->at++;
        return json_object(r, out);
    }
    if (c == '[') {
        r->at++;
        return json_array(r, out);
    }
    if (c == '"') {
        char *text = json_string(r);
        if (!text) {
            return 0;
        }
        code_str_owned(out, text);
        free(text);
        return 1;
    }
    if (json_literal(r, "true")) {
        code_bool(out, 1);
        return 1;
    }
    if (json_literal(r, "false")) {
        code_bool(out, 0);
        return 1;
    }
    if (json_literal(r, "null")) {
        code_null(out);
        return 1;
    }
    if (c == '-' || (c >= '0' && c <= '9')) {
        /* The extent is found here rather than left to the parser, which is
         * handed a length: the buffer is not a C string past `end`, and a
         * number is the one value whose end is not marked by a character of
         * its own. */
        const char *start = r->at;
        if (*r->at == '-') {
            r->at++;
        }
        while (r->at < r->end && *r->at >= '0' && *r->at <= '9') {
            r->at++;
        }
        if (r->at < r->end && *r->at == '.') {
            r->at++;
            while (r->at < r->end && *r->at >= '0' && *r->at <= '9') {
                r->at++;
            }
        }
        if (r->at < r->end && (*r->at == 'e' || *r->at == 'E')) {
            const char *exp = r->at;
            r->at++;
            if (r->at < r->end && (*r->at == '+' || *r->at == '-')) {
                r->at++;
            }
            if (r->at < r->end && *r->at >= '0' && *r->at <= '9') {
                while (r->at < r->end && *r->at >= '0' && *r->at <= '9') {
                    r->at++;
                }
            } else {
                r->at = exp;
            }
        }
        if (r->at == start || (r->at == start + 1 && *start == '-')) {
            r->failed = 1;
            return 0;
        }
        code_number(out, number_parse(start, (size_t)(r->at - start)));
        return 1;
    }
    r->failed = 1;
    return 0;
}

/* Reads the buffer into a particle, or answers zero.
 *
 * Refused rather than guessed at, on every path where the answer is not
 * clear: text that is not JSON, JSON that is not an object, an object with no
 * `_class` string. A refused event is one the program never hears about,
 * which is what the program would want — a handler is written for a particle,
 * and half of one is not it. */
static int code_event_read(long long len, CodeValue *out) {
    if (!code_program_dispatch) {
        return 0;
    }
    if (len <= 0) {
        return 0;
    }
    if (!code_event_buf) {
        return 0;
    }
    if (len > code_event_cap) {
        len = code_event_cap;
    }
    code_event_buf[len] = 0;

    JsonReader reader = {code_event_buf, code_event_buf + len, 0};
    CodeValue particle = {0};
    if (!json_value(&reader, &particle) || reader.failed) {
        code_release(&particle);
        return 0;
    }
    if (particle.tag != CODE_OBJECT) {
        code_release(&particle);
        return 0;
    }
    for (long long i = 0; i < LEN(&particle); i++) {
        if (strcmp(KEYS(&particle)[i], "_class") == 0 &&
            slot_at(ITEMS(&particle), i)->tag == CODE_STR) {
            *out = particle;
            return 1;
        }
    }
    code_release(&particle);
    return 0;
}

/* "This happened." The buffer holds the particle as JSON; `len` says how much
 * of it the host wrote.
 *
 * The answer a handler returns is released rather than given back: an event
 * is told, not asked. `code_event_ask` is the other one. */
void code_event_fire(long long len) {
    CodeValue particle = {0};
    if (!code_event_read(len, &particle)) {
        return;
    }
    CodeValue answer = {0};
    code_program_dispatch(&answer, &particle);
    code_release(&answer);
    code_release(&particle);
}

/* "What should I do about this?" The same particle in, and the handler's own
 * answer back — written over the buffer as JSON, with its length returned.
 * Zero when nothing answered, or when the answer did not fit.
 *
 * The difference from `code_event_fire` is the whole of it, and it is a
 * difference in kind rather than in degree. An event is told: a click has
 * happened whether or not the program has an opinion, and a handler that
 * returns something has simply finished. A question cannot proceed without
 * the answer — the caller is waiting inside its own call, and what it does
 * next depends on what comes back.
 *
 * That is what lets a page put a program in the middle of something. A shell
 * hosting another application can be *asked* whether the guest may draw
 * there, or store that, and answer in the language rather than in the page.
 *
 * One at a time, like `code_event_fire`, and for a sharper reason: the answer
 * is written into the same buffer the question came in on. A handler that
 * caused another question before returning would be overwriting the one it
 * was still being asked — which cannot happen, because dispatch is one
 * thread and a handler cannot re-enter one that is already running. */
long long code_event_ask(long long len) {
    CodeValue particle = {0};
    if (!code_event_read(len, &particle)) {
        return 0;
    }
    CodeValue answer = {0};
    code_program_dispatch(&answer, &particle);
    long long written = code_json_write(&answer, code_event_buf, code_event_cap);
    code_release(&answer);
    code_release(&particle);
    return written > 0 ? written : 0;
}

/* ---- JSON, for a module with a world on the other side of a wire ---------
 *
 * A module speaks particles — that is the whole of its contract with the
 * language, in both directions. But a module whose world is a page, or a
 * socket, has to put a particle into bytes and read one back out, and every
 * module doing that for itself is the same code five times, each with its own
 * ideas about what a fraction looks like.
 *
 * So the runtime does it. `code_json_write` is what `to text` already does to
 * a value; `code_json_read` is the reader the event path already needed. Both
 * were here, neither was reachable.
 *
 * A module that never leaves the machine has no use for either — `mongodb`
 * and `jwt` speak to libraries, not to bytes. */

/* Defined further down, with the rest of value-to-text: `to text` and this
 * write the same bytes, which is the point of borrowing it. */
void code_to_text(CodeValue *out, const CodeValue *v);

/* Writes `v` as JSON into `out`, and answers how many bytes that took, or a
 * negative number when it would not fit. `cap` includes room for the
 * terminating zero this writes. */
long long code_json_write(const CodeValue *v, char *out, long long cap) {
    if (!out || cap <= 0) {
        return -1;
    }
    CodeValue text = {0};
    code_to_text(&text, v);
    if (text.tag != CODE_STR || !text.str) {
        code_release(&text);
        return -1;
    }
    long long len = (long long)strlen(text.str);
    if (len >= cap) {
        code_release(&text);
        return -1;
    }
    memcpy(out, text.str, (size_t)len + 1);
    code_release(&text);
    return len;
}

/* ---- The two buffers a browser module asks its page through -------------
 *
 * A browser module is `no_std` and brings no allocator, so its half used to
 * carry two fixed arrays of its own — and a `Send` with a recording inside
 * was bigger than either, and answered null without a word. The runtime has
 * an allocator, so it keeps the buffers now and grows them: the module asks
 * for the question to be written (`code_web_asked_write`), the page asks
 * for room to write the answer (`code_web_answer_reserve`), and neither
 * ever shrinks. One question at a time, as before — a half answers before
 * the next call can start. */

static char *code_web_grow(char **buf, long long *cap, long long n) {
    if (n < CODE_EVENT_MIN) {
        n = CODE_EVENT_MIN;
    }
    if (n > *cap) {
        char *grown = realloc(*buf, (size_t)n + 1);
        if (grown) {
            *buf = grown;
            *cap = n;
        }
    }
    return *buf;
}

static char *code_web_asked_buf = NULL;
static long long code_web_asked_cap = 0;
static char *code_web_answer_buf = NULL;
static long long code_web_answer_cap = 0;

/* Writes `v` as JSON into the question buffer and answers its length, or a
 * negative number when it could not. */
long long code_web_asked_write(const CodeValue *v) {
    CodeValue text = {0};
    code_to_text(&text, v);
    if (text.tag != CODE_STR || !text.str) {
        code_release(&text);
        return -1;
    }
    long long len = (long long)strlen(text.str);
    char *buf = code_web_grow(&code_web_asked_buf, &code_web_asked_cap, len);
    if (!buf || len > code_web_asked_cap) {
        code_release(&text);
        return -1;
    }
    memcpy(buf, text.str, (size_t)len + 1);
    code_release(&text);
    return len;
}

char *code_web_asked_text(void) { return code_web_asked_buf; }

/* Room for an answer of `n` bytes, and where to write it — which may have
 * moved. The page reads `code_web_answer_capacity` after, in case the room
 * could not be had. */
char *code_web_answer_reserve(long long n) {
    return code_web_grow(&code_web_answer_buf, &code_web_answer_cap, n);
}

long long code_web_answer_capacity(void) {
    code_web_grow(&code_web_answer_buf, &code_web_answer_cap, 0);
    return code_web_answer_cap;
}

char *code_web_answer_text(void) { return code_web_answer_buf; }

/* Reads `len` bytes of JSON into `out`. Non-zero when it was JSON, zero when
 * it was not — and then `out` is untouched, because half a value is worse
 * than none.
 *
 * What `JSON.stringify` writes and nothing more: no comments, no trailing
 * commas. Numbers go through the same reader the language uses, so one
 * spelled by a page and one spelled here agree. */
int code_json_read(const char *text, long long len, CodeValue *out) {
    if (!text || len <= 0 || !out) {
        return 0;
    }
    JsonReader reader = {text, text + len, 0};
    CodeValue value = {0};
    if (!json_value(&reader, &value) || reader.failed) {
        code_release(&value);
        return 0;
    }
    code_release(out);
    *out = value;
    return 1;
}

/* The module's *name*, from whatever path the guest was compiled with.
 *
 * A host's handler wants to say `if name = "net_server"`. What arrives is a
 * path, and which path depends on how the guest was built: a bare
 * `net_server.so` in one, a resolved
 * `.code/modules/net_server/1.5.1/net_server-linux-x86_64.so` in another,
 * because the module resolver rewrites the tidy spelling into the real
 * release asset before the guest is compiled. A handler matching on any of
 * that would be matching on someone else's deployment.
 *
 * So: last path segment, drop `.so`, stop at the first `-`. That last step
 * has a premise worth stating — module names never contain a hyphen (they
 * use `_`: `net_server`, `json_store`, `blob_storage`), while the release
 * asset convention appends `-<os>-<arch>`. So a hyphen is always the start
 * of the platform suffix and never part of the name. If that convention
 * changes, this is where it breaks. */
static void module_stem(const char *ref, char *out, size_t outlen) {
    const char *start = ref;
    for (const char *c = ref; *c; c++) {
        if (*c == '/') start = c + 1;
    }
    size_t n = strlen(start);
    if (n > 3 && strcmp(start + n - 3, ".so") == 0) n -= 3;
    for (size_t i = 0; i < n; i++) {
        if (start[i] == '-') {
            n = i;
            break;
        }
    }
    if (n >= outlen) n = outlen - 1;
    memcpy(out, start, n);
    out[n] = '\0';
}

static void ask_program(CodeValue *out, const char *class_name, const char *app, const char *name,
                        const CodeValue *extra) {
    code_null(out);
    if (!code_program_dispatch) return;
    const char *keys[4] = {"_class", "app", "name", "particle"};
    _Alignas(8) char slots[4 * CODE_VALUE_SLOT_SIZE] = {0};
    code_str(slot_at(slots, 0), class_name);
    code_str_owned(slot_at(slots, 1), app);
    code_str_owned(slot_at(slots, 2), name);
    long long len = 3;
    if (extra) {
        /* `code_native_copy_in`, not `code_copy`. `extra` is the particle a
         * *guest* sent, built by the guest's own copy of this runtime with
         * its own refcounts — retaining it here would count it in the host's
         * bookkeeping and free it in the guest's. Values never cross this
         * boundary by shared ownership. */
        code_native_copy_in(slot_at(slots, 3), extra);
        len = 4;
    }
    CodeValue particle = {0};
    code_object(&particle, keys, slots, len);
    for (long long i = 0; i < len; i++) code_release(slot_at(slots, i));
    code_program_dispatch(out, &particle);
    code_release(&particle);
}

static int is_class(const CodeValue *v, const char *class_name) {
    if (v->tag != CODE_OBJECT) return 0;
    const CodeValue *cls = find_field(v, "_class");
    return cls && cls->tag == CODE_STR && cls->str && strcmp(cls->str, class_name) == 0;
}

/* What a guest's `emit ... to <module>` becomes: an `Module` particle
 * asked of the host's own handlers, on the host's thread, as an ordinary
 * nested handler call.
 *
 * Nested rather than queued, and that is the whole reason it works. A queue
 * is drained between the program's statements, and this call happens *during*
 * one — the host is inside the emit that reached the guest in the first
 * place. `code_abi.h` item 8 describes that trap from the other side. The
 * existing re-entry guard still applies, so a host whose answer loops back
 * into the same guest gets an `Exception` rather than a hang. */
static void hosted_dispatch(void *ctx, CodeValue *out, const CodeValue *particle) {
    long long row = handle_row(ctx);
    if (row < 0 || row >= hosted_module_count || !hosted_modules[row].name) {
        code_make_exception(out, "host", "this module's application has been stopped", NULL);
        return;
    }
    HostedModule *o = &hosted_modules[row];
    if (!o->offered) {
        char msg[256];
        snprintf(msg, sizeof msg, "module '%s' is not offered by the host", o->name);
        code_make_exception(out, "host", msg, NULL);
        return;
    }
    const char *app = hosted_guests[o->guest].app;
    ask_program(out, "Module", app ? app : "", o->name, particle);
}

static void hosted_release(void *ctx, CodeValue *v) {
    (void)ctx;
    code_release(v);
}

/* A guest is asking for a module. The program decides. */
static int hosted_resolve(void *host_ctx, const char *ref, CodeHostModule *out) {
    long long guest = handle_row(host_ctx);
    if (guest < 0 || guest >= hosted_guest_count || !hosted_guests[guest].app) return 0;
    char name[128];
    module_stem(ref, name, sizeof name);
    /* **A host furnishes only what it says it furnishes.** If the program
     * has no `Offer` handler at all, nothing answers and the guest opens its
     * own module, exactly as it would running alone — its own file, its
     * own settings, isolated. That is the ordinary case: an application's
     * modules are its own business, and a host that wants no say has to
     * write nothing to get none.
     *
     * A program that *does* answer is taking that say, and then `Offered` or
     * anything else decides. Silence and refusal are different answers, and
     * this is the line between them. */
    CodeValue answer = {0};
    ask_program(&answer, "Offer", hosted_guests[guest].app, name, NULL);
    if (answer.tag == CODE_NULL) {
        code_release(&answer);
        return 0;
    }
    int offered = is_class(&answer, "Offered");
    code_release(&answer);

    /* A refusal is never a *failure to resolve*, and this is the one place
     * that distinction decides whether a host survives its guests.
     *
     * The ABI lets a host answer "I do not offer that", and the guest's
     * `link` then fails. But a guest's top-level `link` failing ends the
     * guest — and a fatal error inside a module ends the process it was
     * loaded into. So a host that refused a module would be killed by
     * its own policy, by a guest it deliberately said no to. Measured, and
     * exactly backwards.
     *
     * So a refused module is handed over as a module that refuses:
     * the guest links it, and every particle it sends gets an `Exception`.
     * That is the language's own rule everywhere else — trouble is a value,
     * not the end of the program. */
    if (hosted_module_count == hosted_module_cap) {
        long long cap = hosted_module_cap ? hosted_module_cap * 2 : 8;
        HostedModule *grown = realloc(hosted_modules, (size_t)cap * sizeof(HostedModule));
        if (!grown) code_runtime_error("out of memory");
        hosted_modules = grown;
        hosted_module_cap = cap;
    }
    char *kept = malloc(strlen(name) + 1);
    if (!kept) code_runtime_error("out of memory");
    memcpy(kept, name, strlen(name) + 1);
    long long row = hosted_module_count++;
    hosted_modules[row].guest = guest;
    hosted_modules[row].name = kept;
    hosted_modules[row].offered = offered;
    out->dispatch = hosted_dispatch;
    out->release = hosted_release;
    /* No exported values and nothing held open. A stand-in is reached only
     * by `emit`, and what actually holds the program up is the host's own
     * module, which the host holds directly. */
    out->vars = NULL;
    out->serving = NULL;
    out->ctx = row_handle(row);
    return 1;
}

/* A guest's module pushed something. Wake this program the same way its
 * own modules do, so the one park/drain loop covers guests too — no
 * polling, and nothing at all while everyone is idle. */
static void hosted_wake(void *host_ctx) {
    (void)host_ctx;
#ifndef CODE_WASM
    pthread_mutex_lock(&code_wakeup_lock);
    code_wakeups++;
    pthread_cond_broadcast(&code_wakeup_cond);
    pthread_mutex_unlock(&code_wakeup_lock);
#endif
}

static const CodeHostVtable hosted_vtable = {hosted_resolve, hosted_wake};

static long long open_hosted_guest(const char *path) {
    if (hosted_guest_count == hosted_guest_cap) {
        long long cap = hosted_guest_cap ? hosted_guest_cap * 2 : 8;
        HostedGuest *grown = realloc(hosted_guests, (size_t)cap * sizeof(HostedGuest));
        if (!grown) code_runtime_error("out of memory");
        hosted_guests = grown;
        hosted_guest_cap = cap;
    }
    char *kept = malloc(strlen(path) + 1);
    if (!kept) code_runtime_error("out of memory");
    memcpy(kept, path, strlen(path) + 1);
    long long row = hosted_guest_count++;
    hosted_guests[row].app = kept;
    return row;
}

/* Empties a guest's row and every stand-in handed out on its behalf. Their
 * handles stay valid *as handles* — they simply name nothing now, and answer
 * so. */
static void close_hosted_guest(long long guest) {
    if (guest < 0 || guest >= hosted_guest_count) return;
    for (long long i = 0; i < hosted_module_count; i++) {
        if (hosted_modules[i].name && hosted_modules[i].guest == guest) {
            free(hosted_modules[i].name);
            hosted_modules[i].name = NULL;
        }
    }
    free(hosted_guests[guest].app);
    hosted_guests[guest].app = NULL;
}

/* `link <path> as <name>` inside a handler: opens the module and answers
 * with the address value naming it. On any failure `out` is null and the
 * frame's landing block turns the failure into an `Exception` — a host must
 * survive a guest it cannot load. */
void code_runtime_link(CodeValue *out, const CodeValue *path, const char *name) {
    code_null(out);
    if (path->tag != CODE_STR) {
        fail("'link' needs a path");
        return;
    }
    const char *text = path->str ? path->str : "";
    /* Only a `.so`. A `.code` source would mean adding handlers while the
     * program runs — deliberately out of scope — and a `.a` is already part
     * of this binary and has nothing to open. Checked on the value rather
     * than in the parser because there is no value until now. */
    size_t n = strlen(text);
    if (n < 3 || strcmp(text + n - 3, ".so") != 0) {
        char msg[256];
        snprintf(msg, sizeof msg,
                 "'link %s' inside a handler can only open a module ('.so')", text);
        fail(msg);
        return;
    }

    /* `dlopen` only treats its argument as a *path* when it contains a
     * slash; a bare name it looks for the way it looks for a shared library,
     * along the loader's search paths — so `link "guest.so"` would quietly
     * miss the file sitting right there and report it as absent. A top-level
     * `link` never runs into this because `loader.rs` has already turned the
     * spelling into a real path before the runtime sees it. Here there is no
     * such pass, so "taken as written" has to be made to mean "as a path",
     * which is what a program that just built a path out of a directory and
     * a name meant by it. */
    char rooted[512];
    int has_slash = 0;
    /* A loop rather than `strchr`: the freestanding wasm shim declares only
     * the handful of string functions this file actually needed, and one
     * more would be a header change for a single character search. */
    for (const char *c = text; *c; c++) {
        if (*c == '/') {
            has_slash = 1;
            break;
        }
    }
    if (!has_slash) {
        snprintf(rooted, sizeof rooted, "./%s", text);
        text = rooted;
    }

    char err[256];
    NativeHandle *nh = open_native(text, err, sizeof err);
    if (!nh) {
        fail(err);
        return;
    }
    /* A module that speaks first used to be refused here, because the
     * generated drain ran only over the modules known when the program
     * started and a queue appearing later would never be read. It is
     * listened to now: `code_runtime_drain_speakers` empties these queues
     * from the same loop, and `code_runtime_any_serving` keeps the program
     * up while one of them is still working. So a door can be chosen while
     * the program runs — which is the point, since an application that may
     * be held cannot know at build time whether it is opening a port or
     * being given a membrane. */

    if (runtime_module_count == runtime_module_cap) {
        long long cap = runtime_module_cap ? runtime_module_cap * 2 : 8;
        RuntimeModule *grown =
            realloc(runtime_modules, (size_t)cap * sizeof(RuntimeModule));
        if (!grown) {
            code_runtime_error("out of memory");
        }
        runtime_modules = grown;
        runtime_module_cap = cap;
    }
    long long row = runtime_module_count++;
    /* Become its host, if it can be hosted. From here on every `link` inside
     * this module asks this program's handlers instead of the
     * filesystem — which is what lets a guest share what the host already
     * has rather than opening its own. A module built before this
     * existed has no such symbol and is simply left to open its own; it can
     * still be linked and talked to, it just cannot be furnished. */
    long long guest = -1;
#ifndef CODE_WASM
    void (*set_host)(const CodeHostVtable *, void *) =
        (void (*)(const CodeHostVtable *, void *))dlsym(nh->lib, "code_module_set_host");
    if (set_host) {
        guest = open_hosted_guest(text);
        /* Before anything else touches the module. A `.code` library runs
         * its top level lazily, on the first dispatch or the first read of
         * its values, and its own `link`s run with it — installing this
         * afterwards would be too late for exactly the statements it exists
         * to intercept. */
        set_host(&hosted_vtable, row_handle(guest));
    }
#endif
    /* Not `heap_alloc`: this is bookkeeping, not a `CodeValue` block, and
     * must not move the leak counter. */
    size_t kept_len = strlen(text);
    char *kept = malloc(kept_len + 1);
    if (!kept) {
        code_runtime_error("out of memory");
    }
    memcpy(kept, text, kept_len + 1);
    runtime_modules[row].handle = nh;
    runtime_modules[row].path = kept;
    runtime_modules[row].guest = guest;
    runtime_modules[row].name = name;
    runtime_modules[row].flows_take = NULL;
#ifndef CODE_WASM
    /* A program that answers `Trace` wants to see inside what it holds too:
     * asked once, before anything runs in it. */
    if (flows_on) {
        void (*record)(void) = (void (*)(void))dlsym(nh->lib, "code_module_flows");
        if (record) {
            record();
            runtime_modules[row].flows_take =
                (void (*)(CodeValue *))dlsym(nh->lib, "code_module_flows_take");
        }
    }
#endif

    module_address(out, row);
}

/* Releases and unloads one module. Shared by `code_runtime_unlink` and the
 * end-of-program sweep, which differ only in how they find the row. */
static void release_module(long long row) {
    RuntimeModule *slot = &runtime_modules[row];
    NativeHandle *nh = slot->handle;
    /* Order is the whole of it: the module's own release point runs while
     * its code is still mapped, and only then is the mapping dropped.
     * Reversed, the release would be a call into unmapped memory. */
    if (nh->module_release) {
        nh->module_release();
    }
    void *lib = nh->lib;
    int image = nh->image_fd;
    /* Frees the handle and drains anything still queued. Safe to free here
     * because the only caller that can reach a live module refuses while
     * it is still serving, and the end-of-program sweep skips those: an
     * module that answers no to `code_native_serving` has no thread left
     * to hold this pointer. */
    code_native_close(nh);
    close_hosted_guest(slot->guest);
    free(slot->path);
    slot->handle = NULL;
    slot->path = NULL;
#ifndef CODE_WASM
    if (lib) {
        dlclose(lib);
    }
    /* After the unmapping, not before: the image is this object's identity
     * to the loader, and releasing it while the object is still mapped would
     * let the number be reused for the next one. */
    if (image >= 0) {
        close(image);
    }
#else
    (void)lib;
    (void)image;
#endif
}

/* `unlink <address>` — the symmetric half.
 *
 * Order is the whole of it: the module's own release point runs *first*,
 * while its code is still mapped, and only then is the mapping dropped.
 * Reversed, the release would be a call into unmapped memory. */
void code_runtime_unlink(const CodeValue *address) {
    NativeHandle *nh = module_at(address);
    if (!nh) {
        return;
    }
    /* **Refused while anything it holds is still working.** Unmapping code a
     * thread is running in is not a risk to weigh, it is a crash; and an
     * module that still answers "yes" to `code_native_serving` has one.
     *
     * The answer is an observation, not a promise: a door turns its own to
     * no as the last act of its accepting thread, after that loop has
     * exited, and counts requests taken but not yet answered separately. So
     * a refusal here means something is genuinely still running.
     *
     * A failure rather than a silent skip, because the caller has to know.
     * Told it did not happen, a host can say so and leave the application
     * listed as running; told nothing, it would mark something stopped that
     * is still answering on its own port. */
    if (code_native_serving(nh)) {
        fail("this module is still working — stop what it holds before unlinking it");
        return;
    }
    release_module(module_row(address));
}

/* Closes whatever is still linked when the program ends — the same "owns
 * nothing when it exits" rule every `CodeValue` slot is already held to, and
 * for the same reason: a guest still holding its world at exit is a guest
 * whose release point never ran, which is exactly the thing `unlink` exists
 * to guarantee. Called from the sweep generated at the end of `main`, before
 * `code_check_leaks` looks. */
void code_runtime_unlink_all(void) {
    for (long long i = 0; i < runtime_module_count; i++) {
        /* Left alone while it is still working, for the same reason `unlink`
         * refuses: releasing its values and unmapping its code out from
         * under a running thread is a crash on the way out. The process is
         * ending anyway, so what is skipped costs nothing. */
        if (runtime_modules[i].handle && code_native_serving(runtime_modules[i].handle)) {
            continue;
        }
        while (runtime_modules[i].handle) {
            release_module(i);
        }
    }
    free(runtime_modules);
    runtime_modules = NULL;
    runtime_module_count = 0;
    runtime_module_cap = 0;
}

/* Hands every module linked while running a turn to deliver whatever its
 * own modules pushed.
 *
 * Called from the program's own drain, so it happens exactly where the
 * program already handles its own queues — between statements, and on
 * waking. A guest with nothing queued costs a lock and a comparison per
 * module it holds; an idle program never gets here at all, because
 * nothing woke it.
 *
 * Modules that are not `.code` libraries have no drain of their own and
 * are skipped. */
void code_runtime_drain_guests(void) {
    for (long long i = 0; i < runtime_module_count; i++) {
        NativeHandle *nh = runtime_modules[i].handle;
        if (nh && nh->module_drain) {
            nh->module_drain();
#ifndef CODE_WASM
            /* What it did on its own — a timer of its own firing — is an
             * interaction of its own, handed to `Trace` below. */
            if (runtime_modules[i].flows_take) {
                flow_collect(runtime_modules[i].flows_take, nh->release, runtime_modules[i].path, 0);
            }
#endif
        }
    }
#ifndef CODE_WASM
    flow_deliver_pending();
#endif
}

/* Empties the inbound queues of modules linked while the program ran, the
 * way the generated drain empties the ones linked at the top level.
 *
 * Same three steps, in the same order: take the oldest particle, ask the
 * program's handlers for an answer, hand that answer back to the module
 * that pushed. A class the program has no handler for is *dropped* rather
 * than made an error — the rule top-level modules already live under, and
 * for the same reason: a module speaks on its own initiative, and a
 * diagnostic nobody asked to hear is not a mistake by the program.
 *
 * Loops until every queue is empty, because answering one particle commonly
 * produces another.
 *
 * Without `code_program_dispatch` there is nothing to ask, and every
 * particle is answered with null. That is the honest answer rather than a
 * dropped one — a door has to turn "nobody replied" into a status either
 * way. */
void code_runtime_drain_speakers(void) {
    int more = 1;
    while (more) {
        more = 0;
        for (long long i = 0; i < runtime_module_count; i++) {
            NativeHandle *nh = runtime_modules[i].handle;
            if (!nh || !nh->has_inbound) {
                continue;
            }
            CodeValue particle = {0};
            while (code_poll_inbound(nh, &particle)) {
                more = 1;
                CodeValue answer = {0};
#ifndef CODE_WASM
                long long flow = code_flow_begin_push(
                    runtime_modules[i].name ? runtime_modules[i].name : "", &particle);
#endif
                if (code_program_dispatch) {
                    code_program_dispatch(&answer, &particle);
                } else {
                    code_null(&answer);
                }
#ifndef CODE_WASM
                code_flow_finish(flow, &answer);
#endif
                code_native_reply(nh, &particle, &answer);
                code_release(&answer);
                code_release(&particle);
                memset(&particle, 0, sizeof particle);
            }
        }
    }
}

/* Whether any module linked while the program ran still expects to speak
 * — the runtime-linked half of the condition that holds a program open past
 * its last statement.
 *
 * A program that chose its door while running has no compile-time handle to
 * ask, so without this it would reach the end of `main` and exit while its
 * own listener was still accepting. */
int code_runtime_any_serving(void) {
    for (long long i = 0; i < runtime_module_count; i++) {
        NativeHandle *nh = runtime_modules[i].handle;
        if (nh && code_native_serving(nh)) {
            return 1;
        }
    }
    return 0;
}

/* `emit <particle> to <address>` — the runtime-linked half of
 * `code_native_dispatch`, which takes an alias's handle directly. */
void code_runtime_dispatch(CodeValue *out, const CodeValue *address, const CodeValue *particle) {
    code_null(out);
    NativeHandle *nh = module_at(address);
    if (!nh) {
        return;
    }
    code_native_dispatch(nh, out, particle);
#ifndef CODE_WASM
    /* A call into a program this one holds: what it did inside is part of
     * this interaction, under the step that called. */
    for (long long i = 0; i < runtime_module_count; i++) {
        if (runtime_modules[i].handle == nh && runtime_modules[i].flows_take) {
            flow_collect(runtime_modules[i].flows_take, nh->release, runtime_modules[i].path, 1);
        }
    }
#endif
}

/* `link "x.so" as x` — build the object of the module's exported variables
 * (constants), bound under `alias` so `alias.name` is ordinary field access.
 * Reads the module's optional `code_module_vars` export and deep-copies each
 * value out (the same boundary rule as `code_native_dispatch`), then calls
 * the module's own `code_release` on each. A module with no such export
 * yields an empty object. The key *strings* are borrowed from the module
 * (like every object's keys in this runtime — `code_object` copies the
 * pointers, never the characters); that is safe because the module owns them
 * for its whole lifetime and `code_native_close` never `dlclose`s it, so they
 * outlive the object. `handle` is whatever `code_native_open` returned. */
void code_native_vars_object(void *handle, CodeValue *out) {
    NativeHandle *nh = (NativeHandle *)handle;
    const CodeVarList *list = nh->vars ? nh->vars() : NULL;
    long long count = list ? list->count : 0;
    if (count < 0) {
        code_runtime_error("native module reports a negative variable count");
    }
    const char **keys = NULL;
    void *values = NULL;
    if (count > 0) {
        keys = (const char **)malloc((size_t)count * sizeof(const char *));
        // Zero-initialized (calloc, not malloc): each code_native_copy_in
        // below may write a result via a constructor that calls
        // code_release(out) first (see code_str_owned) — that reads
        // out->heap, which has to start real rather than garbage.
        values = calloc((size_t)count, CODE_VALUE_SLOT_SIZE);
        for (long long i = 0; i < count; i++) {
            keys[i] = list->names[i];
            code_native_copy_in(slot_at(values, i), slot_at(list->values, i));
        }
    }
    code_object(out, keys, values, count);
    // code_object retained each scratch value into the fresh object block;
    // drop the scratch copies now (and the module's own copies are the
    // module's to keep — we never release its name strings, only the values
    // we copied out of its buffer).
    if (count > 0) {
        for (long long i = 0; i < count; i++) {
            code_release(slot_at(values, i));
        }
        free(values);
    }
    free(keys);
}

/* `link "x.a" as x`'s equivalent of `code_native_vars_object` above, for a
 * module whose `code_module_vars` (if it exports one — `list` is NULL
 * otherwise) already returns host-allocated values: no `code_native_copy_in`
 * needed, just `code_retain` into a fresh object, exactly like building an
 * object literal from existing bindings. Key strings are borrowed exactly
 * as `code_native_vars_object` borrows them — the module's static storage
 * outlives the program, there being no `.a` equivalent of `dlclose` to worry
 * about at all. */
void code_static_vars_object(const CodeVarList *list, CodeValue *out) {
    long long count = list ? list->count : 0;
    if (count < 0) {
        code_runtime_error("native module reports a negative variable count");
    }
    const char **keys = NULL;
    void *values = NULL;
    if (count > 0) {
        keys = (const char **)malloc((size_t)count * sizeof(const char *));
        values = malloc((size_t)count * CODE_VALUE_SLOT_SIZE);
        for (long long i = 0; i < count; i++) {
            keys[i] = list->names[i];
            CodeValue *slot = slot_at(values, i);
            *slot = *slot_at(list->values, i);
            code_retain(slot);
        }
    }
    code_object(out, keys, values, count);
    if (count > 0) {
        for (long long i = 0; i < count; i++) {
            code_release(slot_at(values, i));
        }
        free(values);
    }
    free(keys);
}

/* `loop [k,] v over <expr>` support. Three calls instead of one combined
 * "iterate" entry point because the loop's control flow lives in the
 * generated IR, not here: codegen emits the counter, the bounds check and
 * the back-edge itself (see codegen.rs's `gen_loop`), and only calls into
 * the runtime for the things that need to inspect a `CodeValue`. Must match
 * interpreter.rs's `Stmt::Loop` eval rule: the iterable must be an array or
 * object — anything else aborts rather than iterating zero times. An
 * object's `items` is laid out parallel to its `keys` (see `code_object`),
 * which is what lets `code_iter_at` serve both container kinds unchanged. */
long long code_iter_len(const CodeValue *v) {
    if (v->tag != CODE_ARRAY && v->tag != CODE_OBJECT) {
        fail_operand("loop requires an array or object", v);
        return 0;
    }
    return LEN(v);
}

/* `i` is always in range: the only caller is the loop header codegen emits,
 * which already compared it against `code_iter_len`'s result. */
void code_iter_at(CodeValue *out, const CodeValue *arr, long long i) {
    code_copy(out, slot_at(ITEMS(arr), i));
}

/* The `key` half of `loop k, v over <expr>` — see `Stmt::Loop`'s doc comment
 * for the law (`X[k] = v`) this exists to satisfy. `code_str_owned`, not a
 * borrowed pointer into `keys`: a key can outlive the loop (assigned to a
 * `get` accumulator), and for an object built by a *different* copy of this
 * runtime (a dlopen'd module) the key bytes aren't even ours to hand back a
 * pointer into. `i` is always in range, same as `code_iter_at`. */
void code_iter_key(CodeValue *out, const CodeValue *v, long long i) {
    if (v->tag == CODE_OBJECT) {
        code_str_owned(out, KEYS(v)[i]);
        return;
    }
    code_number(out, (double)i);
}

/* ---- Handlers written in the language itself -------------------------------
 *
 * The one check the compiled backend needs that nothing else did. Its
 * interpreter counterpart lives in `interpreter.rs`'s `dispatch_handler`, so
 * a handler behaves identically whichever backend runs it. */

/* A handler's result must be a particle, so every `get` binding has a class
 * to test with `is`. Same rule the core handlers follow. */
/* Whether `v` can be emitted at all: emitting is dispatch by `_class`, so a
 * value carrying none is not a particle and there is nothing to dispatch on.
 * Deliberately *not* the same question as "does anyone handle this class" —
 * that one answers null, because sending a particle is not a demand.
 *
 * Called once by generated code before the target is chosen (codegen.rs's
 * `gen_emit`), which is why `code_core_dispatch` below no longer asks: a
 * non-particle `emit` is the emitting frame's own mistake, not something a
 * recipient did, and a module could never have asked at all — it reads
 * `_class`, finds none, and cannot tell "not a particle" from "a class I
 * don't handle". Must match interpreter.rs's `check_emittable` exactly. */
void code_check_emittable(const CodeValue *v) {
    if (v->tag == CODE_OBJECT) {
        for (long long i = 0; i < LEN(v); i++) {
            if (strcmp(KEYS(v)[i], "_class") == 0) {
                return;
            }
        }
    }
    char msg[160];
    snprintf(msg, sizeof msg,
             "emit requires a particle — an object with a '_class' field — found %s %s",
             article_for(v), type_name(v));
    fail(msg);
}

void code_check_particle(const CodeValue *v) {
    if (v->tag == CODE_OBJECT) {
        for (long long i = 0; i < LEN(v); i++) {
            if (strcmp(KEYS(v)[i], "_class") == 0) {
                return;
            }
        }
    }
    char msg[128];
    snprintf(msg, sizeof msg,
             "a handler must return a particle — an object with a '_class' field — found %s %s",
             article_for(v), type_name(v));
    fail(msg);
}

/* ---- Rendering a value as text -------------------------------------------
 *
 * The compiled side of string interpolation (`"hi $name"`), and the first
 * place either runtime had to turn a value back into characters — so this
 * has to agree with `value.rs`'s `Display` byte for byte, or the same
 * fixture would assert differently under `code run` than under `code build`.
 *
 * Same split as `Expr::Interpolated`'s doc comment: a string at the *top*
 * level renders bare, everything else as compact JSON — which means a string
 * nested inside an array or object does keep its quotes. Iterative, for the
 * reason the traversal section above gives. */

/* Strings alone use this encoding; object shapes/index pointers are unchanged.
 * A power-of-two lower bound remembers capacity without enlarging the header.
 * 58 length bits exceed any addressable allocation on the supported targets. */
#define TEXT_LENGTH_MASK ((1ULL << 58) - 1)
static void *room_for(void *payload, size_t bytes);
static size_t block_room(void *block);

static void remember_text(char *buf, size_t len, size_t cap) {
    unsigned long long exponent = 0;
    while (cap) { exponent++; cap >>= 1; }
    header_of(buf)->text_length = (long long)((exponent << 58) | (len + 1));
}

static size_t text_capacity(const CodeValue *v) {
    unsigned long long word = (unsigned long long)header_of(v->str)->text_length;
    unsigned int exponent = (unsigned int)(word >> 58);
    if (!exponent) {
        size_t cap = block_room(header_of(v->str));
        cap = cap > sizeof(CodeHeader) ? cap - sizeof(CodeHeader) : 0;
        size_t len = word ? (size_t)(word - 1) : strlen(v->str);
        remember_text((char *)v->str, len, cap);
        word = (unsigned long long)header_of(v->str)->text_length;
        exponent = (unsigned int)(word >> 58);
    }
    return exponent ? (size_t)(1ULL << (exponent - 1)) : 0;
}

typedef struct {
    char *buf;
    size_t len;
    size_t cap;
} TextBuf;

static void text_push(TextBuf *t, const char *s, size_t n) {
    if (t->len + n + 1 > t->cap) {
        size_t next = t->cap ? t->cap : 64;
        while (next < t->len + n + 1) {
            next *= 2;
        }
        char *bigger = t->buf ? room_for(t->buf, next) : heap_alloc(next);
        if (!bigger) {
            code_runtime_error("out of memory");
        }
        t->buf = bigger;
        t->cap = next;
    }
    memcpy(t->buf + t->len, s, n);
    t->len += n;
}

static void text_push_str(TextBuf *t, const char *s) { text_push(t, s, strlen(s)); }

/* Rust's `{}` for f64 is the shortest decimal that round-trips, laid out
 * positionally (never in exponent form). Reproduced here digit by digit,
 * because the obvious shortcut — let `printf("%.*e")` do the rounding and
 * just move the point — disagrees on exact ties: glibc rounds those to even
 * (2181495296738027.25 -> "...27.2") while Rust rounds away from zero
 * ("...27.3"). So `printf` is used only for the *exact* expansion, and the
 * rounding to the shortest round-tripping length happens below. Verified
 * against Rust's own output over 205k values, random bit patterns included.
 *
 * Integral values short-circuit through a digit loop: it is the overwhelmingly
 * common case, and it is exact.
 *
 * The fractional path needs exactly two things a freestanding build cannot
 * compute for itself — the exact expansion, and reading a candidate back —
 * and they are the two helpers below. Everything between them, the rounding
 * rule included, is the same code on every target, so wasm and native agree
 * by construction rather than by two implementations happening to match.
 * Until 2026-08-29 wasm had no answer for either and a fractional number was
 * a loud error there; see docs/todo/wasm-fractional-number-text.md. */

/* The exact decimal expansion, to 41 significant digits. */
static void number_exact(char *out, size_t cap, double d) {
#ifdef CODE_WASM
    int written = code_host_number_exact(d, out, (unsigned int)cap);
    if (written < 0 || (size_t)written >= cap) {
        code_runtime_error("the host could not render a number as text");
    }
    out[written] = '\0';
#else
    snprintf(out, cap, "%.40e", d);
#endif
}

/* The page's own shortest spelling of `d`, as its significant digits
 * (`toExponential()` with no argument, sign, point and exponent removed);
 * answers how many, or 0 when there is no such help. On wasm every candidate
 * the search below tries is checked by a call out to the page, which made a
 * fraction cost up to eighteen calls. These digits change nothing it decides:
 * no shorter decimal of any rounding reads back as `d`, so the search starts
 * at their length; and when its own candidate there is the same digits, that
 * candidate is known to read back without asking. Natively `strtod` is cheap,
 * and the search starts at one, as it always has. */
static int number_shortest(double d, char *digits, unsigned int cap) {
#ifdef CODE_WASM
    int n = code_host_number_shortest(d, digits, cap);
    return (n >= 1 && n <= 17) ? n : 0;
#else
    (void)d;
    (void)digits;
    (void)cap;
    return 0;
#endif
}

/* Reading one back — the round-trip half of "shortest that round-trips". */
static double number_parse(const char *text, size_t len) {
#ifdef CODE_WASM
    return code_host_number_parse(text, (unsigned int)len);
#else
    (void)len;
    return strtod(text, NULL);
#endif
}

static void text_push_number(TextBuf *t, double d) {
    char tmp[512];
    if (d != d) { text_push_str(t, "NaN"); return; }
    if (d > 1.7976931348623157e308) { text_push_str(t, "inf"); return; }
    if (d < -1.7976931348623157e308) { text_push_str(t, "-inf"); return; }
    if (d >= -9007199254740992.0 && d <= 9007199254740992.0 && d == (double)(long long)d) {
        /* `(long long)-0.0` is 0, which would print an unsigned zero — but
         * Rust's `Display` keeps the sign. Tested by dividing rather than
         * with `signbit`, so the wasm build needs no `math.h`. */
        if (d == 0.0 && 1.0 / d < 0.0) {
            text_push_str(t, "-0");
            return;
        }
        unsigned long long magnitude = (unsigned long long)(d < 0 ? -d : d);
        char *end = tmp + sizeof tmp;
        char *at = end;
        do {
            *--at = (char)('0' + magnitude % 10);
            magnitude /= 10;
        } while (magnitude);
        if (d < 0) *--at = '-';
        text_push(t, at, (size_t)(end - at));
        return;
    }
    /* 41 significant digits: more than the 17 any double needs to round-trip,
     * so `full` is the exact expansion as far as the rounding below can care. */
    char exact[80];
    number_exact(exact, sizeof exact, d);
    const char *p = exact;
    int negative = (*p == '-');
    if (negative) {
        p++;
    }
    char full[48];
    size_t nfull = 0;
    for (; *p && *p != 'e'; p++) {
        if (*p != '.') {
            full[nfull++] = *p;
        }
    }
    int fullexp = (int)strtol(p + 1, NULL, 10);

    /* Shortest length whose correctly-rounded form reads back bit-identically.
     * 17 always does, so the loop always terminates with a usable answer. */
    char m[48];
    size_t n = 1;
    int exp10 = fullexp;
    char shortest[24];
    int nshort = number_shortest(d, shortest, sizeof shortest);
    for (int len = nshort > 0 ? nshort : 1; len <= 17; len++) {
        n = (size_t)len;
        exp10 = fullexp;
        memcpy(m, full, n);
        if (nfull > n && full[n] >= '5') {
            size_t i = n;
            while (i > 0) {
                if (m[i - 1] == '9') {
                    m[i - 1] = '0';
                    i--;
                } else {
                    m[i - 1]++;
                    break;
                }
            }
            /* Carried off the front (999... -> 1000...): one more digit, one
             * higher power of ten. */
            if (i == 0) {
                memmove(m + 1, m, n);
                m[0] = '1';
                exp10++;
            }
        }
        char sci[64];
        size_t o = 0;
        if (negative) {
            sci[o++] = '-';
        }
        sci[o++] = m[0];
        if (n > 1) {
            sci[o++] = '.';
            memcpy(sci + o, m + 1, n - 1);
            o += n - 1;
        }
        o += (size_t)snprintf(sci + o, sizeof sci - o, "e%d", exp10);
        sci[o] = '\0';
        if (len == nshort) {
            /* byte by byte: the freestanding build has no `memcmp` */
            size_t same = 0;
            while (same < n && m[same] == shortest[same]) {
                same++;
            }
            if (same == n) {
                break;
            }
        }
        if (number_parse(sci, o) == d) {
            break;
        }
    }
    while (n > 1 && m[n - 1] == '0') {
        n--;
    }

    /* Exponent form was only ever the intermediate — lay the digits out
     * positionally, which is the one form Rust's `Display` ever prints. */
    size_t out = 0;
    if (negative) {
        tmp[out++] = '-';
    }
    if (exp10 >= (int)n - 1) {
        /* Whole number: every digit, then zeros out to the decimal point. */
        memcpy(tmp + out, m, n);
        out += n;
        for (int i = 0; i < exp10 - (int)n + 1; i++) {
            tmp[out++] = '0';
        }
    } else if (exp10 >= 0) {
        /* Point falls inside the digit run. */
        memcpy(tmp + out, m, (size_t)exp10 + 1);
        out += (size_t)exp10 + 1;
        tmp[out++] = '.';
        memcpy(tmp + out, m + exp10 + 1, n - (size_t)exp10 - 1);
        out += n - (size_t)exp10 - 1;
    } else {
        /* Leading `0.` and however many zeros before the first digit. */
        tmp[out++] = '0';
        tmp[out++] = '.';
        for (int i = 0; i < -exp10 - 1; i++) {
            tmp[out++] = '0';
        }
        memcpy(tmp + out, m, n);
        out += n;
    }
    text_push(t, tmp, out);
}

static void text_push_json_string(TextBuf *t, const char *s) {
    text_push(t, "\"", 1);
    for (const char *p = s; *p; p++) {
        switch (*p) {
        case '"':  text_push(t, "\\\"", 2); break;
        case '\\': text_push(t, "\\\\", 2); break;
        case '\n': text_push(t, "\\n", 2); break;
        case '\t': text_push(t, "\\t", 2); break;
        default:   text_push(t, p, 1); break;
        }
    }
    text_push(t, "\"", 1);
}

/* One entry of the render work stack. `value` is a value still to write;
 * otherwise `punct` is literal text to emit (a bracket, a comma, or a key
 * that has already been quoted into the buffer's own storage). */
typedef struct {
    const CodeValue *value;
    const char *punct;
    int is_key;
} TextStep;

static TextStep *steps = NULL;
static size_t steps_cap = 0;

static void render_text(TextBuf *t, const CodeValue *v) {
    size_t len = 0;

    steps = grow(steps, &steps_cap, len + 1, sizeof(TextStep));
    steps[len++] = (TextStep){v, NULL, 0};
    int top_level = 1;

    while (len > 0) {
        TextStep step = steps[--len];
        if (!step.value) {
            if (step.is_key) {
                text_push_json_string(t, step.punct);
                text_push(t, ":", 1);
            } else {
                text_push_str(t, step.punct);
            }
            continue;
        }
        const CodeValue *current = step.value;
        switch (current->tag) {
        case CODE_NUMBER:
            text_push_number(t, current->number);
            break;
        case CODE_STR:
            if (top_level) {
                text_push_str(t, current->str);
            } else {
                text_push_json_string(t, current->str);
            }
            break;
        case CODE_BOOL:
            text_push_str(t, current->boolean ? "true" : "false");
            break;
        case CODE_NULL:
            text_push_str(t, "null");
            break;
        /* Pushed in reverse so they pop in source order, with the closing
         * bracket pushed first and therefore popped last — mirroring
         * `value.rs`'s `Display`. */
        case CODE_ARRAY:
            text_push(t, "[", 1);
            steps = grow(steps, &steps_cap, len + 1, sizeof(TextStep));
            steps[len++] = (TextStep){NULL, "]", 0};
            for (long long i = LEN(current) - 1; i >= 0; i--) {
                steps = grow(steps, &steps_cap, len + 2, sizeof(TextStep));
                steps[len++] = (TextStep){slot_at(ITEMS(current), i), NULL, 0};
                if (i > 0) {
                    steps[len++] = (TextStep){NULL, ",", 0};
                }
            }
            break;
        case CODE_OBJECT:
            text_push(t, "{", 1);
            steps = grow(steps, &steps_cap, len + 1, sizeof(TextStep));
            steps[len++] = (TextStep){NULL, "}", 0};
            for (long long i = LEN(current) - 1; i >= 0; i--) {
                steps = grow(steps, &steps_cap, len + 3, sizeof(TextStep));
                steps[len++] = (TextStep){slot_at(ITEMS(current), i), NULL, 0};
                steps[len++] = (TextStep){NULL, KEYS(current)[i], 1};
                if (i > 0) {
                    steps[len++] = (TextStep){NULL, ",", 0};
                }
            }
            break;
        }
        top_level = 0;
    }
}

static void finish_text(CodeValue *out, TextBuf *t, int reused) {
    text_push(t, "", 0);
    t->buf[t->len] = '\0';
    remember_text(t->buf, t->len, t->cap);
    if (!reused) code_release(out);
    out->tag = CODE_STR;
    out->heap = 1;
    out->str = t->buf;
}

void code_to_text(CodeValue *out, const CodeValue *v) {
    TextBuf t = {NULL, 0, 0};
    render_text(&t, v);
    finish_text(out, &t, 0);
}

/* All expressions are evaluated before rendering or changing the destination.
 * A single builder replaces per-part strings and repeated concatenation. */
void code_text_parts(CodeValue *out, const CodeValue *const *parts, long long count) {
    TextBuf t = {NULL, 0, 0};
    for (long long i = 0; i < count; i++) render_text(&t, parts[i]);
    finish_text(out, &t, 0);
}

/* Operand-type rules below must match ast.rs's `BinOp`/`UnOp` doc comment
 * and interpreter.rs's `apply_binop`/`eval` exactly — this is the compiled
 * side of the same decisions, not an independent design. */

void code_add(CodeValue *out, const CodeValue *a, const CodeValue *b) {
    if (a->tag == CODE_NUMBER && b->tag == CODE_NUMBER) {
        code_number(out, a->number + b->number);
        return;
    }
    if (a->tag == CODE_STR && b->tag == CODE_STR) {
        /* Unlike `code_str`'s literal, a concatenation result is a value
         * this runtime owns, so it gets a refcounted block. Built before
         * `out` is released, because `out` may be one of the operands
         * (`s = s + s`). */
        size_t la = strlen(a->str);
        size_t lb = strlen(b->str);
        char *buf = heap_alloc(la + lb + 1);
        memcpy(buf, a->str, la);
        memcpy(buf + la, b->str, lb);
        buf[la + lb] = '\0';
        code_release(out);
        out->tag = CODE_STR;
        out->heap = 1;
        out->str = buf;
        return;
    }
    /* One array operand is enough: the other is then a single *element* to
     * append or prepend, and only two arrays concatenate. Written as one
     * case rather than three because "how many elements does this operand
     * contribute, and where do they come from" is the only difference —
     * see interpreter.rs's matching arms. */
    if (a->tag == CODE_ARRAY || b->tag == CODE_ARRAY) {
        long long na = (a->tag == CODE_ARRAY) ? LEN(a) : 1;
        long long nb = (b->tag == CODE_ARRAY) ? LEN(b) : 1;
        long long total = na + nb;
        CodeList *list = NULL;
        if (total > 0) {
            list = list_alloc(total, 0);
            void *buf = list + 1;
            for (long long i = 0; i < na; i++) {
                const CodeValue *src = (a->tag == CODE_ARRAY) ? slot_at(ITEMS(a), i) : a;
                code_retain(src);
                *slot_at(buf, i) = *src;
            }
            for (long long i = 0; i < nb; i++) {
                const CodeValue *src = (b->tag == CODE_ARRAY) ? slot_at(ITEMS(b), i) : b;
                code_retain(src);
                *slot_at(buf, na + i) = *src;
            }
        }
        /* Same ordering point as the string case: the elements are already
         * retained, so releasing `out` here can't free anything `buf` now
         * refers to even when `out` was `a` or `b` (`x = x + x`). */
        code_release(out);
        out->tag = CODE_ARRAY;
        out->heap = total > 0;
        out->list = list;
        return;
    }
    /* Two objects merge, the way two arrays concatenate — see
     * interpreter.rs's matching arm for the rule this implements. A field
     * both sides name takes b's value in a's position; b's remaining fields
     * follow in b's own order. Checked *after* the array case above, so one
     * array operand still makes the object a single element rather than
     * something to merge into.
     *
     * `find_field` compares key text, never pointers: two literals spelling
     * the same name are separate objects in read-only data, and a module's
     * keys live in its own storage entirely. Layout and key ownership match
     * `code_object` exactly — one allocation holding
     * `[keys...][values...][characters...]`, with the key characters copied
     * in rather than borrowed from the operand that supplied them.
     *
     * Copied, not borrowed, since 2026-08-29: this used to keep the
     * operand's pointers, on the reasoning that a key's storage outlives the
     * program. That was true while every key was a program literal in
     * read-only data, and stopped being true the day `{ "$name" = v }` began
     * building one at run time — `code_object` started copying then, and
     * this was missed. What it cost: `acc = acc + { "$k" = v }` in a loop
     * left `acc` naming characters inside the literal's block, which the
     * next iteration released, so the merged object's field names were read
     * out of freed memory. It survived on borrowed time, reading bytes that
     * happened not to have been handed out again yet. */
    if (a->tag == CODE_OBJECT && b->tag == CODE_OBJECT) {
        long long total = LEN(a);
        for (long long j = 0; j < LEN(b); j++) {
            if (own_field_of_key(a, KEYS(b)[j]) == NULL) {
                total++;
            }
        }
        CodeList *list = NULL;
        if (total > 0) {
            size_t keys_bytes = (size_t)total * sizeof(const char *);
            size_t chars_bytes = 0;
            for (long long i = 0; i < LEN(a); i++) {
                chars_bytes += KEY_HASH_BYTES + (KEYS(a)[i] ? strlen(KEYS(a)[i]) : 0) + 1;
            }
            for (long long j = 0; j < LEN(b); j++) {
                if (own_field_of_key(a, KEYS(b)[j]) == NULL) {
                    chars_bytes += KEY_HASH_BYTES + (KEYS(b)[j] ? strlen(KEYS(b)[j]) : 0) + 1;
                }
            }
            list = list_alloc(total, keys_bytes + chars_bytes);
            void *value_buf = list + 1;
            const char **key_buf =
                (const char **)((char *)value_buf + (size_t)total * CODE_VALUE_SLOT_SIZE);
            list->keys = key_buf;
            char *chars = (char *)key_buf + keys_bytes;
            long long n = 0;
            for (long long i = 0; i < LEN(a); i++) {
                const CodeValue *override_val = own_field_of_key(b, KEYS(a)[i]);
                const CodeValue *src = override_val ? override_val : slot_at(ITEMS(a), i);
                key_buf[n] = copy_own_key(&chars, KEYS(a)[i]);
                code_retain(src);
                *slot_at(value_buf, n) = *src;
                n++;
            }
            for (long long j = 0; j < LEN(b); j++) {
                if (own_field_of_key(a, KEYS(b)[j]) != NULL) {
                    continue;
                }
                key_buf[n] = copy_own_key(&chars, KEYS(b)[j]);
                const CodeValue *src = slot_at(ITEMS(b), j);
                code_retain(src);
                *slot_at(value_buf, n) = *src;
                n++;
            }
        }
        /* Same ordering point as the two cases above: every value is
         * retained already, so releasing `out` here cannot free anything the
         * new block refers to, even when `out` is `a` or `b` (`x = x + x`). */
        /* No field added: the keys are `a`'s, in `a`'s order — so is the
         * shape. Read before `out` (which may be `a`) is released. */
        long long shape = (total == LEN(a) && a->heap) ? SHAPE_OF(a) : 0;
        code_release(out);
        out->tag = CODE_OBJECT;
        out->heap = total > 0;
        out->list = list;
        if (total > 0) {
            header_of(out->list)->text_length = shape;
        }
        return;
    }
    /* A string on either side makes `+` string concatenation: the other
     * operand is rendered exactly as `code_to_text` (string interpolation)
     * renders it. The array branch above already returned for every
     * string-and-array pairing, and string-and-object stays a type error —
     * both container kinds are excluded here and fall through to
     * `fail_binary`. Mirrors interpreter.rs's `Str`-on-either-side arms. */
    if ((a->tag == CODE_STR || b->tag == CODE_STR)
        && a->tag != CODE_ARRAY && b->tag != CODE_ARRAY
        && a->tag != CODE_OBJECT && b->tag != CODE_OBJECT) {
        CodeValue ta = {0};
        CodeValue tb = {0};
        code_to_text(&ta, a);
        code_to_text(&tb, b);
        size_t la = strlen(ta.str);
        size_t lb = strlen(tb.str);
        char *buf = heap_alloc(la + lb + 1);
        memcpy(buf, ta.str, la);
        memcpy(buf + la, tb.str, lb);
        buf[la + lb] = '\0';
        code_release(&ta);
        code_release(&tb);
        /* `ta`/`tb` are independent copies, so `buf` holds no reference into
         * the operands — releasing `out` here is safe even when `out` is `a`
         * or `b` (`s = s + 1`), the same ordering point as the cases above. */
        code_release(out);
        out->tag = CODE_STR;
        out->heap = 1;
        out->str = buf;
        return;
    }
    fail_binary("+", a, b);
}

/* Only generated for a last-element read immediately followed by trimming
 * that same array, inside a loop (no inbound drain between the statements).
 * A shared array keeps its contents until the usual copy/slice finishes. */
void code_take_last(CodeValue *out, CodeValue *array) {
    if (array->tag == CODE_ARRAY && array->heap && header_of(array->list)->rc == 1
        && LEN(array) > 0) {
        code_move(out, slot_at(ITEMS(array), LEN(array) - 1));
        return;
    }
    CodeValue length = {0};
    code_length_of(&length, array);
    if (code_failed) return;
    CodeValue index = {0};
    index.number = length.number - 1;
    code_index(out, array, &index);
}

/* ---- Growing a value nothing else holds (ticket 121) -----------------------
 *
 * `xs += x`, `s = s + "…"` and `counts = counts + { k = v }` used to build a
 * whole new value and drop the old one, so growing anything one piece at a
 * time was n² work: 1,000 appends copied half a million slots. Values never
 * change in place — but when the variable being assigned is the only holder
 * of its block (a count of 1), nobody can tell the difference, so the block
 * is grown where it is, with room doubling the way every growable buffer's
 * does — a list's slots, a text's characters, an object's fields, new
 * ones included. Anything else — a shared block, a literal list or object, an
 * operand that is the value itself — takes `code_add`, exactly as before. The idea is Lean's and Koka's reuse of unique cells, done at run
 * time like Swift's `isKnownUniquelyReferenced`.
 *
 * The room a block has is the allocator's own figure, so the header and the
 * module ABI stay as they are. */
#ifdef CODE_WASM
static size_t block_room(void *block) {
    return code_wasm_size_of(block);
}
#elif defined(__GLIBC__)
static size_t block_room(void *block) {
    return malloc_usable_size(block);
}
#else
static size_t block_room(void *block) {
    (void)block;
    return 0; /* unknown: grow by exactly what is needed */
}
#endif

/* Whether `v` owns a heap block nothing else holds. */
static int held_alone(const CodeValue *v) {
    return v->heap && header_of(heap_block(v))->rc == 1;
}

/* The block behind `payload`, able to hold `bytes`: unchanged when it has the
 * room, otherwise reallocated at least twice as big. Only for a block held
 * alone — it may move. */
static void *room_for(void *payload, size_t bytes) {
    CodeHeader *h = header_of(payload);
    size_t want = sizeof(CodeHeader) + bytes;
    size_t have = block_room(h);
    if (have >= want) {
        return payload;
    }
    size_t next = have * 2 > want ? have * 2 : want;
    CodeHeader *bigger = realloc(h, next);
    if (!bigger) {
        code_runtime_error("out of memory");
    }
    return (char *)bigger + sizeof(CodeHeader);
}

/* `*dst = *dst + *b` for an array: `b`'s elements (or `b` itself) appended. */
static int append_in_place(CodeValue *dst, const CodeValue *b) {
    long long nb = (b->tag == CODE_ARRAY) ? LEN(b) : 1;
    if (nb == 0) {
        return 1;
    }
    long long had = LEN(dst);
    long long total = had + nb;
    CodeList *list;
    if (dst->heap) {
        list = room_for(dst->list, sizeof(CodeList) + (size_t)total * CODE_VALUE_SLOT_SIZE);
    } else {
        /* Empty, so there is nothing to copy — a fresh block with room. */
        long long room = total < 4 ? 4 : total;
        list = list_alloc(room, 0);
    }
    for (long long i = 0; i < nb; i++) {
        const CodeValue *src = (b->tag == CODE_ARRAY) ? slot_at(ITEMS(b), i) : b;
        code_retain(src);
        *slot_at(list + 1, had + i) = *src;
    }
    list->len = total;
    dst->list = list;
    dst->heap = 1;
    return 1;
}

/* `*dst = *dst + *b` for two strings, `dst` held alone or a literal. */
/* How many bytes `v`'s text is. A heap string's is measured once and kept
 * in its header, so appending to a long text one piece at a time does not
 * walk all of it again each time (string_build: ~70% `strlen`). Written
 * only from the program's own thread, like everything else that reads a
 * value the program holds. */
static size_t text_length(const CodeValue *v) {
    if (!v->heap) {
        return strlen(v->str);
    }
    CodeHeader *h = header_of(v->str);
    unsigned long long word = (unsigned long long)h->text_length;
    if (!(word & TEXT_LENGTH_MASK)) {
        word |= strlen(v->str) + 1;
        h->text_length = (long long)word;
    }
    return (size_t)((word & TEXT_LENGTH_MASK) - 1);
}

/* Start by keeping an owned text, or copying a literal once. */
static TextBuf append_buffer(CodeValue *dst) {
    size_t len = text_length(dst);
    if (dst->heap) return (TextBuf){(char *)dst->str, len, text_capacity(dst)};
    size_t cap = len + 64;
    char *buf = heap_alloc(cap);
    memcpy(buf, dst->str, len);
    return (TextBuf){buf, len, cap};
}

static void join_in_place(CodeValue *dst, const CodeValue *b) {
    TextBuf t = append_buffer(dst);
    text_push(&t, b->str, text_length(b));
    finish_text(dst, &t, 1);
}

/* `*dst = *dst + *b` for two objects, `dst` held alone: fields `b` shares
 * with `dst` get their new values where they stand, and fields that are new
 * go on the end — the same answer and the same order `code_add` gives.
 *
 * An object is one block, `[count][value slots][key pointers][key
 * characters]`, and its key pointers point into its own characters. A block
 * that has grown has room in all three: `keys - items` says how many slots
 * and pointers fit, and
 * the characters run in key order, so the last key's end is where the next
 * one goes. When the room runs out the object moves to a block twice the
 * size, its values moved rather than copied. Reports 0 (changing nothing)
 * only when `b` names a field twice, which `code_add` answers its own way. */
static int grow_object_in_place(CodeValue *dst, const CodeValue *b) {
    long long extra = 0;
    size_t extra_chars = 0;
    long long local_positions[16];
    long long *positions = LEN(b) <= 16 ? local_positions : malloc((size_t)LEN(b) * sizeof(long long));
    if (!positions) code_runtime_error("out of memory");
    for (long long j = 0; j < LEN(b); j++) {
        for (long long k = 0; k < j; k++) {
            if (strcmp(KEYS(b)[k], KEYS(b)[j]) == 0) {
                if (positions != local_positions) free(positions);
                return 0;
            }
        }
        positions[j] = field_position(dst, KEYS(b)[j], stored_hash(KEYS(b)[j]));
        if (positions[j] < 0) {
            extra++;
            extra_chars += KEY_HASH_BYTES + strlen(KEYS(b)[j]) + 1;
        }
    }
    if (extra > 0) {
        /* Positions survive a move, but a new key invalidates the index. */
        drop_object_index(dst);
        CodeList *base = dst->list;
        long long fits = ((char *)base->keys - (char *)(base + 1)) / CODE_VALUE_SLOT_SIZE;
        const char *last = base->keys[base->len - 1];
        char *used = (char *)last + strlen(last) + 1;
        long long room = (long long)block_room(header_of(base)) - (long long)sizeof(CodeHeader)
            - (used - (char *)base);
        if (base->len + extra > fits || room < (long long)extra_chars) {
            /* Move to a bigger block: slots, pointers and characters all
             * with room to spare. */
            long long total = base->len + extra;
            long long cap = total < 4 ? 4 : 2 * total;
            size_t chars = (size_t)(used - (char *)(base->keys + fits));
            size_t char_room = 2 * (chars + extra_chars) + 16;
            CodeList *moved = heap_alloc(sizeof(CodeList)
                + (size_t)cap * (CODE_VALUE_SLOT_SIZE + sizeof(const char *)) + char_room);
            void *items = moved + 1;
            const char **keys = (const char **)((char *)items + (size_t)cap * CODE_VALUE_SLOT_SIZE);
            char *cursor = (char *)(keys + cap);
            for (long long i = 0; i < base->len; i++) {
                keys[i] = copy_own_key(&cursor, base->keys[i]);
                *slot_at(items, i) = *slot_at(base + 1, i);
            }
            moved->len = base->len;
            moved->keys = keys;
            free(header_of(base));
            code_blocks_add(-1);
            dst->list = moved;
        }
    }
    long long n = LEN(dst);
    char *cursor = NULL;
    if (extra > 0) {
        const char *last = KEYS(dst)[n - 1];
        cursor = (char *)last + strlen(last) + 1;
    }
    for (long long j = 0; j < LEN(b); j++) {
        const CodeValue *src = slot_at(ITEMS(b), j);
        CodeValue *slot = positions[j] < 0 ? NULL : slot_at(ITEMS(dst), positions[j]);
        code_retain(src);
        if (slot) {
            code_release(slot);
            *slot = *src;
        } else {
            dst->list->keys[n] = copy_own_key(&cursor, KEYS(b)[j]);
            *slot_at(ITEMS(dst), n) = *src;
            n++;
        }
    }
    if (extra > 0) {
        header_of(dst->list)->text_length = 0; /* a key list of its own now */
    }
    dst->list->len = n;
    if (positions != local_positions) free(positions);
    return 1;
}

/* What `name = name + value` and `name += value` compile to. Same answer as
 * `code_add(dst, dst, b)`, which is what it falls back to. */
void code_add_into(CodeValue *dst, const CodeValue *b) {
    if (b != dst) {
        if (dst->tag == CODE_ARRAY && (held_alone(dst) || !dst->heap)) {
            if (append_in_place(dst, b)) {
                return;
            }
        }
        if (dst->tag == CODE_STR && b->tag == CODE_STR && (held_alone(dst) || !dst->heap)) {
            join_in_place(dst, b);
            return;
        }
        if (dst->tag == CODE_OBJECT && b->tag == CODE_OBJECT && held_alone(dst)) {
            if (grow_object_in_place(dst, b)) {
                return;
            }
        }
    }
    code_add(dst, dst, b);
}

/* `name += part` where `part` is a temporary of this statement and nothing
 * else holds it: what `code_add_into` then clearing the temporary does,
 * except that one element appended to a list held alone moves in, so
 * neither the retain nor the temporary's release is paid (ticket 126:
 * binary_trees' `level += { … }` and `stack += node.l`). `part` is left
 * zeroed either way. */
void code_add_take(CodeValue *dst, CodeValue *part) {
    if (part != dst && dst->tag == CODE_ARRAY && part->tag != CODE_ARRAY
        && (held_alone(dst) || !dst->heap)) {
        long long had = LEN(dst);
        long long total = had + 1;
        CodeList *list = dst->heap
            ? room_for(dst->list, sizeof(CodeList) + (size_t)total * CODE_VALUE_SLOT_SIZE)
            : list_alloc(4, 0);
        *slot_at(list + 1, had) = *part;
        memset(part, 0, sizeof *part);
        list->len = total;
        dst->list = list;
        dst->heap = 1;
        return;
    }
    code_add_into(dst, part);
    code_clear(part);
}

/* Fused `name += "...$part..."`. Every borrowed part must stay readable
 * until rendering ends. Self-interpolation takes the ordinary render-then-add
 * path, as do shared texts and every non-text destination. */
void code_append_text(CodeValue *dst, const CodeValue *const *parts, long long count) {
    int can_append = dst->tag == CODE_STR && (!dst->heap || held_alone(dst));
    for (long long i = 0; can_append && i < count; i++) {
        if (parts[i] == dst || (parts[i]->tag == CODE_STR && parts[i]->str == dst->str))
            can_append = 0;
    }
    if (can_append) {
        TextBuf t = append_buffer(dst);
        for (long long i = 0; i < count; i++) render_text(&t, parts[i]);
        finish_text(dst, &t, 1);
    } else {
        CodeValue text = {0};
        code_text_parts(&text, parts, count);
        code_add_into(dst, &text);
        code_release(&text);
    }
}

/* What `name = name[from, to)` compiles to — popping a stack, dropping a
 * queue's head: the list cut where it stands when nothing else holds it,
 * the elements outside the range let go, the rest moved to the front. The
 * same answer as `code_slice`, which everything else (a shared list, a
 * string, a wrong kind) still goes to. */
void code_slice_into(CodeValue *dst, const CodeValue *from, const CodeValue *to) {
    if (dst->tag == CODE_ARRAY && held_alone(dst) && from->tag == CODE_NUMBER
        && to->tag == CODE_NUMBER) {
        double len = (double)LEN(dst);
        double lo = from->number < 0 ? 0 : (from->number > len ? len : from->number);
        double hi = to->number < 0 ? 0 : (to->number > len ? len : to->number);
        long long start = (long long)lo;
        long long stop = (long long)hi;
        if (start < stop) {
            for (long long i = 0; i < start; i++) {
                code_release(slot_at(ITEMS(dst), i));
            }
            for (long long i = stop; i < LEN(dst); i++) {
                code_release(slot_at(ITEMS(dst), i));
            }
            if (start > 0) {
                memmove(ITEMS(dst), slot_at(ITEMS(dst), start),
                        (size_t)(stop - start) * CODE_VALUE_SLOT_SIZE);
            }
            dst->list->len = stop - start;
            return;
        }
        /* Empty: an empty list owns no block. */
        CodeValue empty;
        memset(&empty, 0, sizeof empty);
        code_array(&empty, NULL, 0);
        code_move(dst, &empty);
        return;
    }
    CodeValue cut;
    memset(&cut, 0, sizeof cut);
    code_slice(&cut, dst, from, to);
    if (code_failed) {
        return; /* `cut` was never written, and `dst` keeps its value */
    }
    code_move(dst, &cut);
}

/* `fishes[5].x = v`: the part of `*target` at `keys` (a slot buffer, one key
 * per step) replaced by `*value`. What `Expr::SetAt` compiles to, and the
 * same rules as interpreter.rs's `set_at`, messages included.
 *
 * Each level on the way down is made the target's own first (`own_level`):
 * held alone, it is changed where it stands; held by anything else too, that
 * one level is copied and the other holder keeps the old one. `value` is
 * held before any of that, so `xs[0] = xs` copies `xs` rather than putting it
 * inside itself. On a failure nothing has visibly changed: a level copied on
 * the way down has the same contents as the one it replaced. */
static void own_level(CodeValue *v) {
    void *block = v->heap ? heap_block(v) : NULL;
    if (!block || header_of(block)->rc == 1) {
        return;
    }
    CodeValue copy;
    memset(&copy, 0, sizeof copy);
    if (v->tag == CODE_ARRAY) {
        code_array(&copy, ITEMS(v), LEN(v));
    } else {
        build_object(&copy, KEYS(v), ITEMS(v), LEN(v), 1);
        header_of(copy.list)->text_length = SHAPE_OF(v); /* the same keys, in the same order */
    }
    code_release(v);
    *v = copy;
}

/* `keys` points at each step's key where it already is. `hashes[step]` is
 * a literal field name's hash with bit 32 set, or 0 for a key known only
 * when the program runs; `guesses` is this assignment's own memory of where
 * each field was last (see `code_field_ref`). `shapes[step]`, when not 0, is
 * the shape the compiler expects the object at that step to have, and
 * `slots[step]` the field's slot in it (ticket 122 stage B). */
void code_set_at(CodeValue *target, const CodeValue *const *keys, long long count,
                 const CodeValue *value, const long long *hashes, long long *guesses,
                 const void *const *shapes, const long long *slots) {
    char msg[320];
    CodeValue v = *value;
    code_retain(&v);
    CodeValue *current = target;
    for (long long step = 0; step < count; step++) {
        const CodeValue *key = keys[step];
        if (current->tag == CODE_ARRAY) {
            if (key->tag != CODE_NUMBER) {
                snprintf(msg, sizeof msg,
                         "cannot set an array element by %s %s — an array's index is a number",
                         article_for(key), type_name(key));
                goto failed;
            }
            long long at = (long long)key->number;
            if (!((double)at == key->number && at >= 0 && at < LEN(current))) {
                snprintf(msg, sizeof msg,
                         "cannot set that element — an index to set is a whole number below the "
                         "array's length, %lld",
                         LEN(current));
                goto failed;
            }
            own_level(current);
            current = slot_at(ITEMS(current), at);
        } else if (current->tag == CODE_OBJECT) {
            if (key->tag != CODE_STR) {
                snprintf(msg, sizeof msg,
                         "cannot set an object field by %s %s — a field is named by a string",
                         article_for(key), type_name(key));
                goto failed;
            }
            long long at;
            if (shapes[step] && current->heap
                && SHAPE_OF(current) == (long long)(size_t)shapes[step]) {
                /* Built the way the program builds it: the slot is known. */
                at = slots[step];
            } else {
                unsigned int hash = (hashes[step] >> 32) ? (unsigned int)hashes[step]
                                                          : key_hash(key->str);
                at = guesses[step];
                if (!(at < LEN(current) && stored_hash(KEYS(current)[at]) == hash
                      && strcmp(KEYS(current)[at], key->str) == 0)) {
                    at = field_position(current, key->str, hash);
                }
            }
            if (at < 0) {
                if (step + 1 < count) {
                    snprintf(msg, sizeof msg,
                             "cannot set inside field '%s' — the object has no such field",
                             key->str);
                    goto failed;
                }
                /* A new field goes on the end, the way a merge adds one. */
                own_level(current);
                CodeValue one;
                memset(&one, 0, sizeof one);
                const char *name = key->str;
                code_object(&one, &name, &v, 1);
                code_add_into(current, &one);
                code_release(&one);
                code_release(&v);
                return;
            }
            guesses[step] = at;
            own_level(current);
            current = slot_at(ITEMS(current), at);
        } else {
            snprintf(msg, sizeof msg,
                     "cannot set a part of %s %s — only an array's elements and an object's "
                     "fields can be set",
                     article_for(current), type_name(current));
            goto failed;
        }
    }
    code_release(current);
    *current = v;
    return;
failed:
    code_release(&v);
    fail(msg);
}

/* Every failing branch below leaves `out` exactly as it found it, rather than
 * writing a placeholder. That is safe and deliberate: `out` is either a
 * zero-initialized slot or still holds its previous value, so it is a valid
 * `CodeValue` that the frame's cleanup sweep can release exactly once — and
 * writing null instead would have to reason about `out` aliasing `a` or `b`
 * (`x = x / x`) for no gain, since the caller branches away without reading
 * it. */
void code_sub(CodeValue *out, const CodeValue *a, const CodeValue *b) {
    if (a->tag == CODE_NUMBER && b->tag == CODE_NUMBER) {
        code_number(out, a->number - b->number);
        return;
    }
    fail_binary("-", a, b);
}

void code_mul(CodeValue *out, const CodeValue *a, const CodeValue *b) {
    if (a->tag == CODE_NUMBER && b->tag == CODE_NUMBER) {
        code_number(out, a->number * b->number);
        return;
    }
    fail_binary("*", a, b);
}

void code_div(CodeValue *out, const CodeValue *a, const CodeValue *b) {
    if (a->tag == CODE_NUMBER && b->tag == CODE_NUMBER) {
        if (b->number == 0.0) {
            /* Not Infinity: the value model is JSON, which has no way to
             * represent that (see ast.rs's BinOp doc comment). */
            fail("division by zero");
            return;
        }
        code_number(out, a->number / b->number);
        return;
    }
    fail_binary("/", a, b);
}

/* The number in `v`, for an operator whose operands must both be numbers
 * (`-`, `*`, `/`, `<` and the rest of ordering): what lets codegen do the
 * arithmetic itself when it already holds the other side as a plain number,
 * instead of boxing that number to call `code_mul` (ticket 120). `other` is
 * the operand on the other side, or NULL for one codegen knows is a number;
 * `v_on_left` says which side `v` is, so the message is `code_mul`'s,
 * operands in the order written. The 0 on failure is not an answer: the
 * caller checks `code_failed` first. */
double code_operand_number(const CodeValue *v, const CodeValue *other, int v_on_left,
                           const char *op) {
    if (v->tag == CODE_NUMBER) {
        return v->number;
    }
    CodeValue number;
    memset(&number, 0, sizeof number);
    number.tag = CODE_NUMBER;
    const CodeValue *rest = other ? other : &number;
    fail_binary(op, v_on_left ? v : rest, v_on_left ? rest : v);
    return 0;
}

void code_neg(CodeValue *out, const CodeValue *a) {
    if (a->tag == CODE_NUMBER) {
        code_number(out, -a->number);
        return;
    }
    char msg[96];
    snprintf(msg, sizeof msg, "cannot negate %s %s", article_for(a), type_name(a));
    fail(msg);
}

void code_not(CodeValue *out, const CodeValue *a) {
    if (a->tag == CODE_BOOL) {
        code_bool(out, !a->boolean);
        return;
    }
    fail_operand("'not' requires a boolean", a);
}

/* `expr is ClassName` — the type test (see ast.rs's `Expr::Is`): 1 when
 * `a` is an object whose `"_class"` field holds the string `name`, 0 for
 * everything else. Total by design — a missing `_class` or a non-object
 * operand simply answers 0, mirroring how `find_field` reports absence as
 * null and equality turns that into false. Must match interpreter.rs's
 * `Expr::Is` arm exactly. */
/* `x is String` and its five siblings. The kinds are exactly `CodeTag`, so
 * this is one integer compare — codegen passes the tag rather than a name,
 * since which six exist is settled at compile time and a string comparison
 * would be answering a question nobody asked. A particle is an Object, so
 * `p is Object` and `p is Reply` are both true of the same value. */
int code_is_kind(const CodeValue *a, int tag) {
    return a->tag == (CodeTag)tag ? 1 : 0;
}

int code_is_particle(const CodeValue *a, const char *name) {
    if (a->tag != CODE_OBJECT) {
        return 0;
    }
    const CodeValue *class_val = find_field(a, "_class");
    if (!class_val || class_val->tag != CODE_STR) {
        return 0;
    }
    return strcmp(class_val->str, name) == 0 ? 1 : 0;
}

/* ---- `∈` a data type (ticket 123) ---------------------------------------
 *
 * A type is a set of values, described by the compiler as a graph of these
 * nodes (`codegen.rs`'s `type_node`): a type that contains itself — an
 * element whose children are elements — points back at its own node. Not in
 * `code_abi.h`: only generated code asks. Must answer as `types.rs`'s
 * `Types::contains` does: null is in `Null` and `Any` only, but a part that
 * is null (a field left out) fits whatever its label is. */
enum {
    CODE_TYPE_ANY,
    CODE_TYPE_KIND,   /* `number` is the tag */
    CODE_TYPE_STR,    /* `text` is the value */
    CODE_TYPE_NUMBER, /* `number` is the value */
    CODE_TYPE_BOOL,   /* `number` is 0 or 1 */
    CODE_TYPE_UNION,  /* `count` members in `children` */
    CODE_TYPE_ARRAY_OF,
    CODE_TYPE_OBJECT_OF, /* `children[0]` is the element's type */
    CODE_TYPE_FIELDS, /* `count` fields: `names`, `children`; no others */
    CODE_TYPE_OPEN,   /* the same, and others allowed */
    CODE_TYPE_CLASS   /* a particle whose `_class` is `text` */
};

typedef struct CodeTypeNode {
    int op;
    int count;
    const struct CodeTypeNode *const *children;
    const char *const *names;
    const char *text;
    double number;
} CodeTypeNode;

static int type_holds(const CodeValue *v, const CodeTypeNode *t, int part) {
    if (part && v->tag == CODE_NULL) {
        return 1;
    }
    switch (t->op) {
    case CODE_TYPE_ANY:
        return 1;
    case CODE_TYPE_KIND:
        return v->tag == (CodeTag)(int)t->number;
    case CODE_TYPE_STR:
        return v->tag == CODE_STR && strcmp(v->str, t->text) == 0;
    case CODE_TYPE_NUMBER:
        return v->tag == CODE_NUMBER && v->number == t->number;
    case CODE_TYPE_BOOL:
        return v->tag == CODE_BOOL && (v->boolean != 0) == (t->number != 0);
    case CODE_TYPE_UNION:
        for (int i = 0; i < t->count; i++) {
            if (type_holds(v, t->children[i], part)) {
                return 1;
            }
        }
        return 0;
    case CODE_TYPE_ARRAY_OF:
    case CODE_TYPE_OBJECT_OF: {
        CodeTag tag = t->op == CODE_TYPE_ARRAY_OF ? CODE_ARRAY : CODE_OBJECT;
        if (v->tag != tag) {
            return 0;
        }
        for (long long i = 0; i < LEN(v); i++) {
            if (!type_holds(slot_at(ITEMS(v), i), t->children[0], 1)) {
                return 0;
            }
        }
        return 1;
    }
    case CODE_TYPE_FIELDS:
    case CODE_TYPE_OPEN:
        if (v->tag != CODE_OBJECT) {
            return 0;
        }
        /* A label that names `_class` is about particles: an object
         * without one is not one (a field left out is otherwise null, which
         * fits). */
        for (int f = 0; f < t->count; f++) {
            if (strcmp(t->names[f], "_class") == 0) {
                const CodeValue *class_val = find_field(v, "_class");
                if (!class_val || class_val->tag == CODE_NULL) {
                    return 0;
                }
            }
        }
        for (long long i = 0; i < LEN(v); i++) {
            const char *key = KEYS(v)[i];
            int found = -1;
            for (int f = 0; f < t->count; f++) {
                if (strcmp(t->names[f], key) == 0) {
                    found = f;
                    break;
                }
            }
            if (found >= 0) {
                if (!type_holds(slot_at(ITEMS(v), i), t->children[found], 1)) {
                    return 0;
                }
            } else if (t->op == CODE_TYPE_FIELDS && strcmp(key, "_class") != 0) {
                return 0;
            }
        }
        return 1;
    case CODE_TYPE_CLASS:
        return code_is_particle(v, t->text);
    default:
        return 0;
    }
}

int code_is_type(const CodeValue *v, const CodeTypeNode *t) {
    return type_holds(v, t, 0);
}

/* Used by `and`/`or`/`if` codegen to check an operand is actually a bool
 * before branching on it. `requirement` is the whole clause, not just the
 * operator name — `if` is not an operator and wants "if requires a boolean",
 * not "'if' requires booleans". codegen.rs passes exactly what
 * interpreter.rs's matching arm formats. */
int code_bool_value(const CodeValue *v, const char *requirement) {
    if (v->tag != CODE_BOOL) {
        fail_operand(requirement, v);
        return 0;
    }
    return v->boolean;
}

/* Deep structural equality, matching Rust's derived `PartialEq` on `Value`
 * exactly — objects included, which compare by field name rather than by
 * position (see value.rs's `PartialEq`). Used for `==`/`!=`,
 * which (unlike every other operator here) are well-defined for *any* two
 * values, including mismatched kinds — never calls code_runtime_error. */
typedef struct {
    const CodeValue *a;
    const CodeValue *b;
} Pair;

static Pair *pending = NULL; /* value pairs still to compare */
static size_t pending_cap = 0;

int code_values_equal(const CodeValue *a, const CodeValue *b) {
    size_t len = 0;
    pending = grow(pending, &pending_cap, len + 1, sizeof(Pair));
    pending[len].a = a;
    pending[len].b = b;
    len++;

    while (len > 0) {
        Pair pair = pending[--len];
        const CodeValue *x = pair.a;
        const CodeValue *y = pair.b;
        if (x->tag != y->tag) {
            return 0;
        }
        switch (x->tag) {
        case CODE_NUMBER:
            if (x->number != y->number) {
                return 0;
            }
            break;
        case CODE_STR:
            if (strcmp(x->str, y->str) != 0) {
                return 0;
            }
            break;
        case CODE_BOOL:
            if (x->boolean != y->boolean) {
                return 0;
            }
            break;
        case CODE_NULL:
            break;
        case CODE_ARRAY:
            if (LEN(x) != LEN(y)) {
                return 0;
            }
            pending = grow(pending, &pending_cap, len + (size_t)LEN(x), sizeof(Pair));
            for (long long i = 0; i < LEN(x); i++) {
                pending[len].a = slot_at(ITEMS(x), i);
                pending[len].b = slot_at(ITEMS(y), i);
                len++;
            }
            break;
        case CODE_OBJECT:
            if (LEN(x) != LEN(y)) {
                return 0;
            }
            pending = grow(pending, &pending_cap, len + (size_t)LEN(x), sizeof(Pair));
            for (long long i = 0; i < LEN(x); i++) {
                /* By name, not by position — matching value.rs's `PartialEq`
                 * exactly (see its comment for why). A name may appear more
                 * than once, so the nth occurrence on the left is matched
                 * with the nth on the right. */
                long long seen = 0;
                for (long long p = 0; p < i; p++) {
                    if (strcmp(KEYS(x)[p], KEYS(x)[i]) == 0) {
                        seen++;
                    }
                }
                long long found = -1;
                for (long long q = 0; q < LEN(y); q++) {
                    if (strcmp(KEYS(y)[q], KEYS(x)[i]) == 0) {
                        if (seen == 0) {
                            found = q;
                            break;
                        }
                        seen--;
                    }
                }
                if (found < 0) {
                    return 0;
                }
                pending[len].a = slot_at(ITEMS(x), i);
                pending[len].b = slot_at(ITEMS(y), found);
                len++;
            }
            break;
        }
    }
    return 1;
}

/* Silent on success (no output, no return value). Must match
 * interpreter.rs's `Stmt::Assert` eval rule exactly: `v` must be
 * CODE_BOOL, and its value must be true — anything else goes down the
 * failure channel, same as every other operator error here. */
void code_assert(const CodeValue *v) {
    if (v->tag != CODE_BOOL) {
        fail_operand("assert requires a boolean", v);
        return;
    }
    if (!v->boolean) {
        fail("assertion failed");
    }
}

#ifndef CODE_WASM
/* Opt-in executable tracing. Only instrumented objects call these functions.
 * Snapshot JSON at the boundary: no retained runtime values survive the normal
 * leak check. IDs are preorder positions; answers fill those positions later.
 * The CLI canonicalizes this private transport through trace::render_trace. */
typedef struct {
    long long depth;
    char *target, *particle, *answer;
} CodeTraceEvent;
static CodeTraceEvent *trace_events;
static size_t trace_len, trace_cap;
static long long trace_depth;
static FILE *trace_file;

static char *trace_json(const CodeValue *v) {
    if (v->tag == CODE_STR) {
        TextBuf t = {NULL, 0, 0};
        text_push_json_string(&t, v->str);
        t.buf[t.len] = '\0';
        char *result = strdup(t.buf);
        CodeValue text = {0};
        finish_text(&text, &t, 0);
        code_release(&text);
        if (!result) code_runtime_error("cannot allocate execution trace");
        return result;
    }
    CodeValue text = {0};
    code_to_text(&text, v);
    char *result = strdup(text.str);
    code_release(&text);
    if (!result) code_runtime_error("cannot allocate execution trace");
    return result;
}

static void trace_write(void) {
    fputs("{\"schema_version\":1,\"entry\":\"\",\"events\":[", trace_file);
    for (size_t i = 0; i < trace_len; i++) {
        CodeTraceEvent *event = &trace_events[i];
        fprintf(trace_file, "%s{\"sequence\":%zu,\"depth\":%lld,\"target\":%s,"
                "\"particle_class\":\"\",\"particle\":%s,\"answer\":%s}",
                i ? "," : "", i, event->depth, event->target,
                event->particle, event->answer ? event->answer : "null");
        free(event->target);
        free(event->particle);
        free(event->answer);
    }
    fputs("]}", trace_file);
    int failed = ferror(trace_file);
    if (fclose(trace_file)) failed = 1;
    free(trace_events);
    if (failed) {
        fputs("error: cannot write execution trace\n", stderr);
        _Exit(1);
    }
}
void code_trace_init(void) {
    const char *path = getenv("CODE_TRACE_FILE");
    if (!path || !(trace_file = fopen(path, "w")))
        code_runtime_error("cannot open execution trace");
    if (atexit(trace_write)) code_runtime_error("cannot register execution trace writer");
}
void code_trace_enter(void) { trace_depth++; }
void code_trace_leave(void) { trace_depth--; }
long long code_trace_begin(const char *target, const CodeValue *particle) {
    trace_events = grow(trace_events, &trace_cap, trace_len + 1, sizeof(CodeTraceEvent));
    CodeValue name = {0};
    name.tag = CODE_STR;
    name.str = (char *)target;
    trace_events[trace_len] = (CodeTraceEvent){trace_depth, trace_json(&name), trace_json(particle), NULL};
    return (long long)trace_len++;
}
void code_trace_finish(long long sequence, const CodeValue *answer) {
    trace_events[sequence].answer = trace_json(answer);
}
#endif