Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

47.2 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    codegen.ts
 * @brief   EIR -> C, against the SysCtx contract.
 *
 * @details The backend emits C rather than LLVM IR because the LLVM half is a
 *          solved problem someone else maintains, and one C output serves clang
 *          for aarch64 and emcc for wasm at once. What is NOT solved anywhere is
 *          the half above it — EIR, and this lowering.
 *
 *          Two properties are the whole point, and both are visible in the
 *          output rather than asserted about it:
 *
 *          - **Zero calls.** A generated system's only external names are the
 *            static inlines in the runtime header, so the wasm's import section
 *            is empty by construction rather than by trimming.
 *          - **Loads at constant offsets.** Every component field is
 *            `es_f32(base + ES_OFF_Comp_field)`, and the offset came from EHT.
 *            The offsets are macros so a debugger and a reader see the name.
 *
 *          Bit-for-bit agreement with node is a REQUIREMENT, not an aspiration,
 *          because the differential pixel gate compares frames. Three things
 *          here exist only for it: the Math shims (C's library disagrees with
 *          ECMAScript about `round`, `min` and `max` at zero and at ties), the
 *          storage width chosen by the shape rather than by the value, and
 *          `-ffp-contract=off` in CFLAGS — a fused multiply-add is more accurate
 *          than what JS computes, and more accurate is still different.
 */
import { resourceMethodBit } from '../../sdk/src/ecs/resourceShapes';
import { EXACT_COEFFICIENTS as EX } from '../../sdk/src/math/exact';
import {
    CMD_WORDS, QUERYROWS_WORDS, SYSCTX_WORDS, EVENT_OUT_WORDS, CMD_DESPAWN, CMD_REMOVE,
    abiHandshake, planFor,
    type AbiHandshake, type AbiLayout, type FieldOffsets, type Leaf, type SysPlan,
} from './abi';
import {
    BOOL, F64,
    type CompShape, type EirFn, type EirModule, type EirSystem, type EirType, type Expr, type Local,
    type LeafEnc, type MathFn, type Place, type Stmt,
} from './eir';

/**
 * Flags the generated C must be compiled with. Not advice: `-ffp-contract=off`
 * is load-bearing, and a build that omits it will disagree with the interpreter
 * in the last bit of a multiply-add and be very hard to explain.
 */
export const CFLAGS: readonly string[] = [
    '-std=c11', '-O2', '-ffp-contract=off', '-fexcess-precision=standard',
];

/**
 * What linking one of these into a wasm module takes. Load-bearing, not taste:
 * the module owns no memory and has no entry, and the memory it is handed is
 * the ENGINE's — which grows, so one declaring a smaller maximum does not run
 * slower, it fails to instantiate with a LinkError.
 */
export const WASM_LINK_FLAGS: readonly string[] = [
    '--no-entry', '-sSTANDALONE_WASM', '-sIMPORTED_MEMORY',
    '-sALLOW_MEMORY_GROWTH=1', '-sERROR_ON_UNDEFINED_SYMBOLS=1',
];

/** The odd constant the width is multiplied by before it is folded in. */
export const ADDR_MIX = '0x9e3779b97f4a7c15';

export interface CModule {
    /** `estella_abi.h` — the contract's C side, and the only thing the code calls. */
    readonly header: string;
    /**
     * `estella_offsets.h` — where each field this program touches lives, from
     * EHT. Its own header rather than part of the source, because the engine
     * side has to assert against the SAME numbers: an `offsetof` that disagrees
     * with one of these is a read of a different field.
     */
    readonly offsets: string;
    /**
     * The translation unit: module functions and systems, and NOTHING else. A
     * module that shares the engine's memory must have no data section — a
     * static of its own is written at a link-time address the engine already
     * owns, which silently overwrites whatever is there.
     */
    readonly source: string;
    /**
     * The handshake constant and the declaration table, as a second translation
     * unit. A host that links against the engine reads them out of the artifact;
     * a host that loads the wasm reads the manifest instead, and must not
     * compile this.
     */
    readonly decls: string;
    /** Exported symbols, one per compiled system. */
    readonly symbols: readonly string[];
    /**
     * The handshake: what this module baked in about the ENGINE and about the
     * PROJECT, each so a loader can say which one moved.
     */
    readonly handshake: AbiHandshake;
}

// =============================================================================
// the runtime header — memory access, and the Math ECMAScript actually specifies
// =============================================================================

/**
 * Everything the generated code is allowed to reach. All of it is `static
 * inline`, so the object file has no undefined symbol and the wasm has no
 * import — there was never anything to import.
 */
export const RUNTIME_H = `/* GENERATED by @estella/compiler — do not edit. */
/* The Estella ABI, C side. */
#ifndef ESTELLA_ABI_H
#define ESTELLA_ABI_H

#include <stddef.h>
#include <stdint.h>
#include <string.h>
#include <math.h>

/* A fused multiply-add is MORE accurate than the double rounding JS does, and
   more accurate is still a different number. GCC does not implement this pragma
   and warns about it, so the flag in CFLAGS is the one that has to be there. */
#if defined(__clang__)
#pragma STDC FP_CONTRACT OFF
#endif

/* An address is a POINTER, and on wasm32 a pointer IS a 32-bit offset into
   linear memory — which is why one emitted source serves both back ends. The
   OFFSETS below are the contract; the address width is the machine, and it is
   mixed into the handshake so a 32-bit artifact cannot load into a 64-bit host.

   ES_ADDR_BASE is the other model: a host that owns one block and addresses it
   by offset. A wasm2c deployment is one, and so is the differential
   harness. Same structs, same offsets, one word wider or narrower. */
#if defined(ES_ADDR_BASE)
typedef uint32_t es_addr_t;
extern unsigned char *es_memory;
#define ES_PTR(a) (es_memory + (a))
#else
typedef uintptr_t es_addr_t;
#define ES_PTR(a) ((unsigned char *)(a))
#endif

/* A host that LOADS this asks the platform for a symbol by name, and on
   Windows nothing is exported from a DLL unless it says so — the module
   builds, loads, and answers null to every lookup. A wasm link names its
   exports on the command line instead, so this is inert there. */
#if defined(_WIN32)
#define ES_EXPORT __declspec(dllexport)
#elif defined(__GNUC__)
#define ES_EXPORT __attribute__((visibility("default")))
#else
#define ES_EXPORT
#endif

/* The packed rows the host materialised: for each row, the entity and
   then one base address per component the query named, in that order. */
typedef struct EsQueryRows {
    es_addr_t rows;
    es_addr_t count;
} EsQueryRows;

/* A command: four u32, sixteen bytes, at every address width. */
typedef struct EsCmd {
    uint32_t kind;
    uint32_t a;
    uint32_t b;
    uint32_t c;
} EsCmd;

#define ES_CMD_DESPAWN ${CMD_DESPAWN}u
#define ES_CMD_REMOVE  ${CMD_REMOVE}u

/* ${SYSCTX_WORDS} addresses, and a number that needs a reason to grow. */
typedef struct EsSysCtx {
    es_addr_t queries;
    es_addr_t resources;
    es_addr_t cmdBuf;
    es_addr_t cmdCap;
    es_addr_t cmdCount;
    es_addr_t events;
} EsSysCtx;

/* What a host needs in order to CALL a system without glue written by hand.
   The compiler knows a system's queries and resources -- that is what _params
   is -- so it says so here rather than leaving each host to be told twice. */
/* Where a system APPENDS events: f64 records, because a payload is fields and
   not four words. A record is [writer slot, ...fields], and how long one is
   comes from the manifest — the host declared it.

   Its own queue rather than a wider EsCmd: fixed-width records and
   variable-width ones cannot share a buffer without stride guesswork.

   ${EVENT_OUT_WORDS} addresses. A host lays this block out from that same
   number, so a field appended here without it is a header one side walks past. */
typedef struct EsEventOut {
    es_addr_t buf;      /* double * */
    es_addr_t cap;      /* capacity, in doubles */
    es_addr_t count;    /* address of the used-doubles word */
} EsEventOut;

typedef struct EsQueryDecl {
    const char *const *comps;   /* component names, in the order the query names them */
    const unsigned char *mut;   /* 1 where the system may write that component */
    uint32_t count;
} EsQueryDecl;

typedef struct EsSystemDecl {
    const char *name;
    void (*fn)(es_addr_t);
    const EsQueryDecl *queries;
    const char *const *resources;
    /* 1 where the system declared ResMut: a host that MIRRORS a resource into
       the block has to write that block back, or the write is dropped. */
    const unsigned char *resourcesMut;
    uint32_t queryCount;
    uint32_t resourceCount;
} EsSystemDecl;

/* The C and TS sides of these structs have ONE author, and a side that drifts
   from it must fail to compile. The numbers below are written by that author
   (sdk/src/ecs/aot/abiDigest.ts, through compiler/src/abi.ts) into this file;
   these four declarations are how C says no if a struct above ever stops
   matching them. Every struct a host addresses by word owes one: EsEventOut
   went without for as long as it existed, and a fourth field would have been
   read as the next struct by whichever side had not been told. */
typedef char es_check_sysctx[sizeof(EsSysCtx) == ${SYSCTX_WORDS} * sizeof(es_addr_t) ? 1 : -1];
typedef char es_check_rows[sizeof(EsQueryRows) == ${QUERYROWS_WORDS} * sizeof(es_addr_t) ? 1 : -1];
typedef char es_check_cmd[sizeof(EsCmd) == ${CMD_WORDS} * 4 ? 1 : -1];
typedef char es_check_eventout[sizeof(EsEventOut) == ${EVENT_OUT_WORDS} * sizeof(es_addr_t) ? 1 : -1];

/* memcpy, not a cast through a typed pointer: a component base is whatever the
   host handed over, and a wider load through an under-aligned pointer is
   undefined even where the hardware would have allowed it. */
static inline double es_f32(const unsigned char *p) { float v; memcpy(&v, p, 4); return (double)v; }
static inline void es_set_f32(unsigned char *p, double v) { float f = (float)v; memcpy(p, &f, 4); }
static inline double es_f64(const unsigned char *p) { double v; memcpy(&v, p, 8); return v; }
static inline void es_set_f64(unsigned char *p, double v) { memcpy(p, &v, 8); }

/* A bool in the C++ structs is ONE byte. Reading it as a float would read three
   bytes of whatever follows it, which is a value rather than an error. */
static inline int es_bool(const unsigned char *p) { return *p != 0; }
/* One question of a service, as the host mirrored it: a byte and a mask. */
static inline int es_bit(const unsigned char *p, unsigned bit) { return (*p >> bit) & 1u; }
static inline void es_set_bool(unsigned char *p, int v) { *p = (unsigned char)(v ? 1 : 0); }

/* ---------------------------------------------------------------------------
   Math. Only the operations ECMAScript specifies EXACTLY are in the subset, but
   "exactly specified" is not the same as "what libm does" — three of them
   differ, and each difference is one bit of one pixel that would take a day to
   find. So each is written out rather than forwarded.
   --------------------------------------------------------------------------- */
static inline double es_abs(double x) { return fabs(x); }
static inline double es_floor(double x) { return floor(x); }
static inline double es_ceil(double x) { return ceil(x); }
static inline double es_trunc(double x) { return trunc(x); }
static inline double es_sqrt(double x) { return sqrt(x); }

/* ---------------------------------------------------------------------------
   Trigonometry, SPECIFIED. Math.sin is implementation-defined, so an
   interpreted build and a compiled one may both be right and disagree — which
   for a differential pixel gate is a red frame with no bug behind it.

   These are the same range reduction, the same polynomial and the same ORDER as
   sdk/src/math/exact.ts, line for line. Reordering either side is a change to
   the result, and a differential compares them bit for bit.

   The COEFFICIENTS come from that file, written in below: what is implemented
   twice here is the structure, which a differential can compare, and not
   fifteen decimals, which retyping only puts at risk.
   --------------------------------------------------------------------------- */
#define ES_PIO2_HI ${num(EX.PIO2_HI)}
#define ES_PIO2_LO ${num(EX.PIO2_LO)}
#define ES_TWO_OVER_PI ${num(EX.TWO_OVER_PI)}

static inline double es_kernel_sin(double x) {
    double z = x * x;
    double r = ${num(EX.S1)} + z * (${num(EX.S2)}
        + z * (${num(EX.S3)} + z * (${num(EX.S4)}
        + z * (${num(EX.S5)} + z * ${num(EX.S6)}))));
    return x + x * z * r;
}

static inline double es_kernel_cos(double x) {
    double z = x * x;
    double r = ${num(EX.C1)} + z * (${num(EX.C2)}
        + z * (${num(EX.C3)} + z * (${num(EX.C4)}
        + z * (${num(EX.C5)} + z * ${num(EX.C6)}))));
    return 1.0 - 0.5 * z + z * z * r;
}

/* Math.round's rule, as floor(x + 0.5) rather than es_round: the TS side
   reduces with that same expression, and the two must agree on a tie. */
static inline double es_trig_quadrant(double x, double *r) {
    double n = floor(x * ES_TWO_OVER_PI + 0.5);
    *r = (x - n * ES_PIO2_HI) - n * ES_PIO2_LO;
    double q = fmod(n, 4.0);
    if (q < 0.0) q += 4.0;
    return q;
}

static inline double es_exact_sin(double x) {
    if (!isfinite(x)) return (double)NAN;
    double r;
    double q = es_trig_quadrant(x, &r);
    if (q == 0.0) return es_kernel_sin(r);
    if (q == 1.0) return es_kernel_cos(r);
    if (q == 2.0) return -es_kernel_sin(r);
    return -es_kernel_cos(r);
}

static inline double es_exact_cos(double x) {
    if (!isfinite(x)) return (double)NAN;
    double r;
    double q = es_trig_quadrant(x, &r);
    if (q == 0.0) return es_kernel_cos(r);
    if (q == 1.0) return -es_kernel_sin(r);
    if (q == 2.0) return -es_kernel_cos(r);
    return es_kernel_sin(r);
}

/* Math.sign returns x itself for NaN and for both zeroes, so the sign of zero
   survives — and the sign of zero is a distinct bit pattern in the image. */
static inline double es_sign(double x) {
    if (isnan(x) || x == 0.0) return x;
    return x > 0.0 ? 1.0 : -1.0;
}

/* C's round() breaks ties AWAY from zero; ECMAScript breaks them toward +Inf.
   And floor(x + 0.5) — the usual fix — is wrong for the double just below 0.5,
   where the addition itself rounds up to 1. Subtracting the floor is exact for
   every finite x, so the comparison sees the true fraction. */
static inline double es_round(double x) {
    if (!isfinite(x) || x == 0.0) return x;
    double f = floor(x);
    double r = (x - f) < 0.5 ? f : f + 1.0;
    /* Math.round(-0.2) is -0, and -0 is not the same bytes as +0. */
    return (r == 0.0 && x < 0.0) ? -0.0 : r;
}

/* fmin/fmax return the non-NaN operand and are free to pick either zero;
   Math.min/max propagate NaN and distinguish -0 from +0. */
static inline double es_min(double a, double b) {
    if (isnan(a) || isnan(b)) return (double)NAN;
    if (a == b) return signbit(a) ? a : b;
    return a < b ? a : b;
}
static inline double es_max(double a, double b) {
    if (isnan(a) || isnan(b)) return (double)NAN;
    if (a == b) return signbit(a) ? b : a;
    return a > b ? a : b;
}

/* JS % on doubles is the truncated remainder, which is fmod. */
static inline double es_rem(double a, double b) { return fmod(a, b); }

#endif /* ESTELLA_ABI_H */
`;

// =============================================================================
// naming and types
// =============================================================================

/** A C identifier from an EIR name. The id keeps distinct locals distinct even
 *  after the inliner has minted two temporaries from the same parameter. */
function cName(l: Local): string {
    return `${l.name.replace(/[^A-Za-z0-9_]/g, '_')}_${l.id}`;
}

function cFn(name: string): string {
    return `es_fn_${name.replace(/[^A-Za-z0-9_]/g, '_')}`;
}

export function cSymbol(system: string): string {
    return `es_sys_${system.replace(/[^A-Za-z0-9_]/g, '_')}`;
}

function offsetMacro(owner: string, path: readonly string[]): string {
    return `ES_OFF_${owner}_${path.join('_')}`.replace(/[^A-Za-z0-9_]/g, '_');
}

/** `double x` but `unsigned char *x` — the star binds to the name, not the type. */
function decl(type: string, name: string): string {
    return type.endsWith('*') ? `${type}${name}` : `${type} ${name}`;
}

function cType(t: EirType): string {
    switch (t.k) {
        case 'f64': return 'double';
        case 'bool': return 'int';
        case 'entity': return 'uint32_t';
        // A component or resource base: the byte address the host handed over,
        // which every field access adds a constant EHT offset to.
        case 'comp': case 'res': return 'unsigned char *';
        default: throw new Error(`codegen: a ${t.k} is not a C value`);
    }
}

/** How a value is held, so a coercion is a lookup rather than a case tree. A
 *  base address is in the list only to be rejected: it is never an operand. */
type Repr = 'double' | 'int' | 'uint32_t' | 'address';

function repr(t: EirType): Repr {
    return t.k === 'comp' || t.k === 'res' ? 'address' : (cType(t) as Repr);
}

/** Convert `text` from one EIR type's representation to another's. */
function coerce(text: string, from: EirType, to: EirType): string {
    const a = repr(from);
    const b = repr(to);
    if (a === b) return text;
    if (a === 'address' || b === 'address') {
        throw new Error('codegen: a component base is an address, not a value to convert');
    }
    if (b === 'double') return `((double)(${text}))`;
    if (b === 'int') return a === 'double' ? `((${text}) != 0.0)` : `((${text}) != 0u)`;
    return `((uint32_t)(${text}))`;
}

/**
 * A double literal C parses back to the same bits. Two traps: an integer-valued
 * constant printed bare makes `(5 / 3)` INTEGER division in C, and `-0`
 * stringifies as "0" in JS while being a different bit pattern in the image.
 */
function num(v: number): string {
    if (Number.isNaN(v)) return '((double)NAN)';
    if (!Number.isFinite(v)) return v > 0 ? '((double)INFINITY)' : '(-(double)INFINITY)';
    if (Object.is(v, -0)) return '(-0.0)';
    // toString gives the shortest decimal that round-trips, and strtod is
    // correctly rounded, so the bits survive the trip through the source file.
    const s = v.toString();
    return /[.eE]/.test(s) ? s : `${s}.0`;
}

/**
 * One accessor per encoding the subset admits. The integer three are absent
 * because the frontend refuses those leaves; if one reaches here it is a
 * compiler bug, and an undefined index says so louder than a wrong load.
 */
const LOAD: Partial<Record<LeafEnc, string>> = { f32: 'es_f32', f64: 'es_f64', bool8: 'es_bool' };
const STORE: Partial<Record<LeafEnc, string>> = {
    f32: 'es_set_f32', f64: 'es_set_f64', bool8: 'es_set_bool',
};

const MATH_C: Record<MathFn, string> = {
    abs: 'es_abs', floor: 'es_floor', ceil: 'es_ceil', round: 'es_round',
    trunc: 'es_trunc', sqrt: 'es_sqrt', sign: 'es_sign', min: 'es_min', max: 'es_max',
    sin: 'es_exact_sin', cos: 'es_exact_cos',
};

// =============================================================================
// which locals are read — so the output has no variable the compiler warns about
// =============================================================================

function readsOf(stmts: readonly Stmt[], out: Set<number>): void {
    const place = (p: Place): void => {
        if (p.p === 'local') { out.add(p.id); return; }
        place(p.base);
    };
    const expr = (e: Expr): void => {
        switch (e.e) {
            case 'const': break;
            case 'read': place(e.place); break;
            case 'neg': case 'not': expr(e.v); break;
            case 'bin': case 'logic': expr(e.l); expr(e.r); break;
            case 'select': expr(e.cond); expr(e.then); expr(e.otherwise); break;
            // The receiver IS read: the bit is at an offset from its base.
            case 'svc': place(e.base); break;
            case 'call': for (const a of e.args) expr(a); break;
        }
    };
    for (const s of stmts) {
        switch (s.s) {
            case 'let': expr(s.value); break;
            case 'return': if (s.value) expr(s.value); break;
            case 'continue': case 'break': break;
            // A field target READS its base to compute the address; a local
            // target does not, which is exactly the distinction that decides
            // whether a bound row local is dead.
            case 'assign':
                if (s.target.p === 'field') place(s.target.base);
                expr(s.value);
                break;
            case 'emit': place(s.channel); for (const a of s.args) expr(a); break;
            case 'if': expr(s.cond); readsOf(s.then, out); readsOf(s.otherwise, out); break;
            case 'rowLoop': place(s.query); readsOf(s.body, out); break;
        }
    }
}

/** Locals a rowLoop binds; they are declared per iteration, not per function. */
function loopBound(stmts: readonly Stmt[], out: Set<number>): void {
    for (const s of stmts) {
        if (s.s === 'rowLoop') {
            if (s.entity !== null) out.add(s.entity);
            for (const b of s.binds) out.add(b);
            loopBound(s.body, out);
        } else if (s.s === 'if') {
            loopBound(s.then, out);
            loopBound(s.otherwise, out);
        }
    }
}

function hasEmit(stmts: readonly Stmt[]): boolean {
    return stmts.some((s) => s.s === 'emit'
        || (s.s === 'rowLoop' && hasEmit(s.body))
        || (s.s === 'if' && (hasEmit(s.then) || hasEmit(s.otherwise))));
}

function zeroOf(t: EirType): string {
    switch (repr(t)) {
        case 'double': return '0.0';
        case 'int': return '0';
        case 'address': return '0';
        default: return '0u';
    }
}

// =============================================================================
// the emitter
// =============================================================================

class Emitter {
    private readonly lines: string[] = [];
    private readonly byId = new Map<number, Local>();
    private readonly owners = new Map<number, string>();
    private depth = 0;

    constructor(
        private readonly layout: AbiLayout,
        /** Offset macros this translation unit turned out to need. */
        private readonly offsets: Map<string, number>,
        private readonly plan: SysPlan | null,
    ) {}

    get text(): string { return this.lines.join('\n'); }

    private bind(locals: readonly Local[]): void {
        for (const l of locals) {
            this.byId.set(l.id, l);
            if (l.type.k === 'comp' || l.type.k === 'res') this.owners.set(l.id, l.type.name);
        }
    }

    private line(indent: number, text: string): void {
        this.lines.push(`${'    '.repeat(indent)}${text}`);
    }

    private local(id: number): Local {
        const l = this.byId.get(id);
        if (!l) throw new Error(`codegen: local %${id} is used but never declared`);
        return l;
    }

    /** `base + ES_OFF_Comp_field` — one add against a constant, which is the point. */
    private address(base: Place, path: readonly string[]): { addr: string; leaf: Leaf } {
        if (base.p !== 'local') throw new Error('codegen: a field base must be a local');
        const owner = this.owners.get(base.id);
        if (!owner) throw new Error(`codegen: local %${base.id} owns no fields`);
        const shape: FieldOffsets | undefined =
            this.layout.comps.get(owner) ?? this.layout.resources.get(owner);
        const leaf = shape?.leaves.get(path.join('.'));
        if (!leaf) throw new Error(`codegen: '${owner}' has no field '${path.join('.')}'`);
        const macro = offsetMacro(owner, path);
        this.offsets.set(macro, leaf.byteOffset);
        return { addr: `${cName(this.local(base.id))} + ${macro}`, leaf };
    }

    /** Read a place; the result's C type is `cType(type)`. */
    private read(p: Place, type: EirType): string {
        if (p.p === 'local') return cName(this.local(p.id));
        const { addr, leaf } = this.address(p.base, p.path);
        // The read's C type follows the ENCODING, and the coercion after it
        // follows the EIR type: a bool byte reads as an int and never as 0.0f.
        const read = `${LOAD[leaf.enc]}(${addr})`;
        return coerce(read, leaf.enc === 'bool8' ? BOOL : F64, type);
    }

    /** An expression, parenthesised so composition never needs precedence rules. */
    expr(e: Expr): string {
        switch (e.e) {
            case 'const':
                return typeof e.value === 'boolean' ? (e.value ? '1' : '0') : num(e.value);
            case 'read':
                return this.read(e.place, e.type);
            case 'svc': {
                const at = e.base.p === 'local'
                    ? resourceMethodBit(this.owners.get(e.base.id) ?? '', e.method, e.key) : null;
                if (!at) throw new Error(`codegen: '${e.method}' is not a declared service question`);
                if (e.base.p !== 'local') throw new Error('codegen: a service receiver must be a local');
                return `es_bit(${cName(this.local(e.base.id))} + ${at.offset}u, ${at.bit}u)`;
            }
            case 'neg':
                return `(-${coerce(this.expr(e.v), e.v.type, F64)})`;
            case 'not':
                return `(!${coerce(this.expr(e.v), e.v.type, BOOL)})`;
            case 'logic':
                return `(${coerce(this.expr(e.l), e.l.type, BOOL)} ${e.op} `
                    + `${coerce(this.expr(e.r), e.r.type, BOOL)})`;
            case 'select':
                return `(${coerce(this.expr(e.cond), e.cond.type, BOOL)} ? `
                    + `${coerce(this.expr(e.then), e.then.type, e.type)} : `
                    + `${coerce(this.expr(e.otherwise), e.otherwise.type, e.type)})`;
            case 'bin': {
                const l = coerce(this.expr(e.l), e.l.type, F64);
                const r = coerce(this.expr(e.r), e.r.type, F64);
                // `%` is a call because C's % is integer-only; JS's is fmod.
                if (e.op === '%') return `es_rem(${l}, ${r})`;
                return `(${l} ${e.op} ${r})`;
            }
            case 'call': {
                const args = e.args.map((a) => coerce(this.expr(a), a.type, F64));
                if (e.target.k === 'math') return `${MATH_C[e.target.fn]}(${args.join(', ')})`;
                return `${cFn(e.target.name)}(${args.join(', ')})`;
            }
        }
    }

    stmts(list: readonly Stmt[], indent: number): void {
        for (const s of list) this.stmt(s, indent);
    }

    private stmt(s: Stmt, indent: number): void {
        switch (s.s) {
            case 'let': {
                const l = this.local(s.id);
                this.line(indent, `${cName(l)} = ${coerce(this.expr(s.value), s.value.type, l.type)};`);
                break;
            }
            case 'return':
                this.line(indent, s.value ? `return ${this.expr(s.value)};` : 'return;');
                break;
            // A row loop IS the C for-loop, so these need no translation.
            case 'continue': this.line(indent, 'continue;'); break;
            case 'break': this.line(indent, 'break;'); break;
            case 'assign': {
                if (s.target.p === 'local') {
                    const l = this.local(s.target.id);
                    this.line(indent, `${cName(l)} = ${coerce(this.expr(s.value), s.value.type, l.type)};`);
                    break;
                }
                const { addr, leaf } = this.address(s.target.base, s.target.path);
                const want = leaf.enc === 'bool8' ? BOOL : F64;
                this.line(indent,
                    `${STORE[leaf.enc]}(${addr}, ${coerce(this.expr(s.value), s.value.type, want)});`);
                break;
            }
            case 'if': {
                this.line(indent, `if (${coerce(this.expr(s.cond), s.cond.type, BOOL)}) {`);
                this.stmts(s.then, indent + 1);
                if (s.otherwise.length > 0) {
                    this.line(indent, '} else {');
                    this.stmts(s.otherwise, indent + 1);
                }
                this.line(indent, '}');
                break;
            }
            case 'emit':
                this.emitCommand(s, indent);
                break;
            case 'rowLoop':
                this.rowLoop(s, indent);
                break;
        }
    }

    /**
     * A command is four words written into the host's buffer and a counter
     * bumped — no call, and nothing read back. The `cap` guard is the
     * contract's: writing past it is forbidden, and the host is what sized it.
     */
    private emitCommand(s: Stmt & { s: 'emit' }, indent: number): void {
        const writer = s.channel.p === 'local'
            ? this.plan!.writers.find((w) => w.slot === this.plan!.slots.get(s.channel.p === 'local'
                ? s.channel.id : -1)?.slot)
            : undefined;
        if (writer) { this.emitEvent(s, writer.slot, indent); return; }
        const kind = s.record === 'despawn' ? 'ES_CMD_DESPAWN' : 'ES_CMD_REMOVE';
        const fields = ['a', 'b', 'c'];
        this.line(indent, 'if (es_cmd_n < es_cmd_cap) {');
        this.line(indent + 1, 'EsCmd *es_at = &es_cmd_buf[es_cmd_n];');
        this.line(indent + 1, `es_at->kind = ${kind}; /* ${s.record} */`);
        for (let i = 0; i < CMD_WORDS - 1; i++) {
            const a = s.args[i];
            const v = a ? coerce(this.expr(a), a.type, { k: 'entity' }) : '0u';
            this.line(indent + 1, `es_at->${fields[i]} = ${v};`);
        }
        this.line(indent + 1, 'es_cmd_n += 1u;');
        this.line(indent, '}');
    }

    /**
     * One payload appended: the writer's slot, then its fields in declared
     * order. Bounds-checked against the capacity the host set, and silent when
     * full for the same reason a command queue is — a system that overran would
     * otherwise write past a buffer it does not own.
     */
    private emitEvent(s: Stmt & { s: 'emit' }, slot: number, indent: number): void {
        const stride = s.args.length + 1;
        this.line(indent, `if (es_ev_n + ${stride}u <= es_ev_cap) {`);
        this.line(indent + 1, `double *es_rec = es_ev_buf + es_ev_n;`);
        this.line(indent + 1, `es_rec[0] = ${slot}.0;`);
        s.args.forEach((a, i) => {
            this.line(indent + 1, `es_rec[${i + 1}] = ${coerce(this.expr(a), a.type, F64)};`);
        });
        this.line(indent + 1, `es_ev_n += ${stride}u;`);
        this.line(indent, '}');
    }

    /**
     * The op EIR exists to keep: a strided walk of a packed row array.
     * One `es_u32` per component per row and no lookup — the host already did
     * the lookup once, in C++, which is where it is cheap.
     */
    private rowLoop(s: Stmt & { s: 'rowLoop' }, indent: number): void {
        if (s.query.p !== 'local') throw new Error('codegen: a rowLoop walks a query local');
        const slot = this.plan?.slots.get(s.query.id);
        if (!slot || slot.table !== 'query') throw new Error('codegen: that local is not a declared query');
        const q = this.plan!.queries[slot.slot]!;
        const d = this.depth++;
        const stride = 1 + q.length;
        const k = slot.slot;
        const reads = new Set<number>();
        readsOf(s.body, reads);
        this.line(indent, '{');
        this.line(indent + 1,
            `const es_addr_t *es_rows${d} = (const es_addr_t *)ES_PTR(es_queries[${k}].rows);`);
        this.line(indent + 1, `const es_addr_t es_n${d} = es_queries[${k}].count;`);
        this.line(indent + 1, `for (es_addr_t es_i${d} = 0; es_i${d} < es_n${d}; ++es_i${d}) {`);
        this.line(indent + 2, `const es_addr_t *es_row${d} = es_rows${d} + es_i${d} * ${stride}u;`);
        if (s.entity !== null && reads.has(s.entity)) {
            this.line(indent + 2,
                `const uint32_t ${cName(this.local(s.entity))} = (uint32_t)es_row${d}[0];`);
        }
        s.binds.forEach((id, i) => {
            // A bound component nobody reads is not loaded. The row is still
            // strided past it, because the row's shape is the query's, not the
            // body's — dropping the load is free, dropping the column is not.
            if (!reads.has(id)) return;
            this.line(indent + 2,
                `unsigned char *${cName(this.local(id))} = ES_PTR(es_row${d}[${i + 1}]);`);
        });
        this.stmts(s.body, indent + 2);
        this.line(indent + 1, '}');
        this.line(indent, '}');
        this.depth--;
    }

    /** A module-level pure function: numbers in, one number out, no world. */
    fn(f: EirFn): void {
        this.bind([...f.params, ...f.locals]);
        const params = f.params.map((p) => decl(cType(p.type), cName(p))).join(', ');
        this.line(0, `static ${cType(f.ret)} ${cFn(f.name)}(${params || 'void'}) {`);
        this.declare(f.locals, null, 1);
        this.stmts(f.body, 1);
        this.line(0, '}');
        this.line(0, '');
    }

    /** `void es_sys_<Name>(uint32_t ctx)` — the one exported symbol. */
    system(sys: EirSystem): void {
        const plan = this.plan!;
        this.bind([...sys.params, ...sys.locals]);
        const reads = new Set<number>();
        readsOf(sys.body, reads);
        const bound = new Set<number>();
        loopBound(sys.body, bound);

        this.line(0, `ES_EXPORT void ${cSymbol(sys.name)}(es_addr_t es_ctx) {`);
        this.line(1, 'const EsSysCtx *es_c = (const EsSysCtx *)ES_PTR(es_ctx);');
        if (plan.queries.length > 0) {
            this.line(1, 'const EsQueryRows *es_queries = (const EsQueryRows *)ES_PTR(es_c->queries);');
        }
        const usesRes = sys.params.some((p) => plan.slots.get(p.id)!.table === 'res' && reads.has(p.id));
        if (usesRes) {
            this.line(1, 'const es_addr_t *es_resources = (const es_addr_t *)ES_PTR(es_c->resources);');
        }
        const sends = plan.writers.length > 0 && hasEmit(sys.body);
        const emits = hasEmit(sys.body) && plan.channels.length > plan.writers.length;
        if (emits) {
            this.line(1, 'EsCmd *es_cmd_buf = (EsCmd *)ES_PTR(es_c->cmdBuf);');
            this.line(1, 'const uint32_t es_cmd_cap = (uint32_t)es_c->cmdCap;');
            this.line(1, 'uint32_t *es_cmd_at = (uint32_t *)ES_PTR(es_c->cmdCount);');
            this.line(1, 'uint32_t es_cmd_n = *es_cmd_at;');
        }
        if (sends) {
            this.line(1, 'const EsEventOut *es_ev = (const EsEventOut *)ES_PTR(es_c->events);');
            this.line(1, 'double *es_ev_buf = (double *)ES_PTR(es_ev->buf);');
            this.line(1, 'const uint32_t es_ev_cap = (uint32_t)es_ev->cap;');
            this.line(1, 'uint32_t *es_ev_at = (uint32_t *)ES_PTR(es_ev->count);');
            this.line(1, 'uint32_t es_ev_n = *es_ev_at;');
        }
        if (plan.queries.length === 0 && !usesRes && !emits && !sends) this.line(1, '(void)es_c;');
        // A resource base is one indirection, resolved once at entry rather than
        // per row: the host already put the address in the table.
        for (const p of sys.params) {
            const slot = plan.slots.get(p.id)!;
            if (slot.table !== 'res' || !reads.has(p.id)) continue;
            this.line(1, `unsigned char *${cName(p)} = ES_PTR(es_resources[${slot.slot}]);`);
        }
        this.declare(sys.locals.filter((l) => !bound.has(l.id)), reads, 1);
        this.stmts(sys.body, 1);
        if (emits) this.line(1, '*es_cmd_at = es_cmd_n;');
        if (sends) this.line(1, '*es_ev_at = es_ev_n;');
        this.line(0, '}');
        this.line(0, '');
    }

    /**
     * Function-scope locals. A declared local nobody reads would draw a warning,
     * and a warning in generated code is a warning nobody will ever read — so it
     * is spelled `(void)` here rather than silenced at the compiler.
     */
    private declare(locals: readonly Local[], reads: ReadonlySet<number> | null, indent: number): void {
        for (const l of locals) {
            this.line(indent, `${decl(cType(l.type), cName(l))} = ${zeroOf(l.type)};`);
            if (reads && !reads.has(l.id)) this.line(indent, `(void)${cName(l)};`);
        }
    }
}

// =============================================================================
// the module
// =============================================================================

/**
 * Emit C for the given systems. The caller decides which — `verifySystem` has to
 * have passed first, because this lowering is total over VALID EIR and its
 * reaction to invalid EIR is to throw, which is the right reaction to a compiler
 * bug and the wrong one to a source file outside the subset.
 */
export function emitC(
    module: EirModule,
    layout: AbiLayout,
    systems: readonly EirSystem[],
    /** `sizeof(es_addr_t)` where this artifact will run: 4 for a host owning one
     *  block it addresses by offset, 8 where an address is a pointer. The machine
     *  and not the contract, so it is mixed into the handshake and not into the
     *  offsets — the digest is what refuses a 32-bit module to a 64-bit host. */
    addressBytes: 4 | 8 = 4,
): CModule {
    const offsets = new Map<string, number>();
    const plans = systems.map((s) => planFor(s));
    const bodies: string[] = [];

    // Module functions first: a system may call one, and C wants it declared
    // before the call. Only the ones still reachable after the inliner ran are
    // emitted, because an unreferenced static would warn.
    for (const name of calledFns(module, systems)) {
        const e = new Emitter(layout, offsets, null);
        e.fn(module.fns.get(name)!);
        bodies.push(e.text);
    }
    systems.forEach((sys, i) => {
        const e = new Emitter(layout, offsets, plans[i]!);
        e.system(sys);
        bodies.push(e.text);
    });

    const manifest = emitManifest(systems, plans);
    const handshake = abiHandshake(module.comps, plans, addressBytes);
    const macros = [...offsets].sort(([a], [b]) => (a < b ? -1 : 1)).map(([k, v]) => `#define ${k} ${v}u`);
    const offsetsHeader = [
        '/* GENERATED by @estella/compiler — do not edit. */',
        '/* Field offsets from EHT, for the systems this program compiled. The',
        '   engine side asserts its own offsetof against these: a disagreement is',
        '   a read of a DIFFERENT FIELD, not an error. */',
        '#ifndef ESTELLA_OFFSETS_H',
        '#define ESTELLA_OFFSETS_H',
        '',
        ...macros,
        '',
        '#endif /* ESTELLA_OFFSETS_H */',
        '',
    ].join('\n');
    const source = [
        '/* GENERATED by @estella/compiler — do not edit. */',
        '/* This file calls the engine zero times, and holds no data of its own. */',
        '#include "estella_abi.h"',
        '#include "estella_offsets.h"',
        '',
        // Functions rather than a constant: a module sharing the engine's
        // memory may carry no data section, and both roads compile this file.
        '/* Which BUILD this is, for a loader holding the sidecar written beside',
        '   it. The two digests above answer "is this engine right" and "are the',
        '   project shapes right"; neither answers "are these two the same pair". */',
        `ES_EXPORT uint32_t es_module_contract_lo(void) { return 0x${handshake.moduleContract.slice(8)}u; }`,
        `ES_EXPORT uint32_t es_module_contract_hi(void) { return 0x${handshake.moduleContract.slice(0, 8)}u; }`,
        '',
        ...bodies,
    ].join('\n');
    const decls = [
        '/* GENERATED by @estella/compiler — do not edit. */',
        '/* The static half: what this module is, for a host that reads it out of',
        '   the artifact rather than out of a manifest beside it. Separate because',
        '   a wasm module sharing the ENGINE\'s memory must carry no data section —',
        '   its bytes would land at a link-time address the engine already owns. */',
        '#include "estella_abi.h"',
        '',
        '/* What this module baked in about the engine it was built for. A',
        '   host compares before it maps anything — a mismatch is not a wrong',
        '   answer, it is a read of a different field. The address width belongs',
        '   to the MACHINE, so it mixes in here rather than in the compiler and a',
        '   32-bit artifact cannot load into a 64-bit host. */',
        `#define ES_ABI_ENGINE_DIGEST 0x${handshake.engineAbi}ULL`,
        'ES_EXPORT const uint64_t es_abi_hash =',
        `    ES_ABI_ENGINE_DIGEST ^ (${ADDR_MIX}ULL * (uint64_t)sizeof(es_addr_t));`,
        '',
        ...systems.map((s) => `ES_EXPORT void ${cSymbol(s.name)}(es_addr_t es_ctx);`),
        '',
        ...manifest,
    ].join('\n');

    return {
        header: RUNTIME_H,
        offsets: offsetsHeader,
        source,
        decls,
        symbols: systems.map((s) => cSymbol(s.name)),
        handshake,
    };
}

/**
 * The table a host walks to call these systems: each one's symbol, and the
 * component and resource NAMES its ctx tables have to be filled from. Without it
 * every host writes the same list a second time, and the second list is the one
 * that goes stale.
 */
function emitManifest(systems: readonly EirSystem[], plans: readonly SysPlan[]): string[] {
    const out: string[] = ['/* The systems in this file, and what each one needs filled in. */'];
    const rows: string[] = [];
    systems.forEach((sys, i) => {
        const plan = plans[i]!;
        const tag = cSymbol(sys.name);
        plan.queries.forEach((args, k) => {
            out.push(`static const char *const ${tag}_q${k}_comps[] = { `
                + `${args.map((a) => JSON.stringify(a.comp)).join(', ')} };`);
            out.push(`static const unsigned char ${tag}_q${k}_mut[] = { `
                + `${args.map((a) => (a.mut ? '1u' : '0u')).join(', ')} };`);
        });
        if (plan.queries.length > 0) {
            const entries = plan.queries.map((args, k) =>
                `{ ${tag}_q${k}_comps, ${tag}_q${k}_mut, ${args.length}u }`);
            out.push(`static const EsQueryDecl ${tag}_queries[] = { ${entries.join(', ')} };`);
        }
        if (plan.resources.length > 0) {
            out.push(`static const char *const ${tag}_resources[] = { `
                + `${plan.resources.map((r) => JSON.stringify(r.name)).join(', ')} };`);
            out.push(`static const unsigned char ${tag}_resources_mut[] = { `
                + `${plan.resources.map((r) => (r.mut ? '1u' : '0u')).join(', ')} };`);
        }
        // C has no zero-length array, so an empty table is a null pointer and a
        // count of zero — which is also what a host would check anyway.
        rows.push(`    { ${JSON.stringify(sys.name)}, ${tag}, `
            + `${plan.queries.length > 0 ? `${tag}_queries` : 'NULL'}, `
            + `${plan.resources.length > 0 ? `${tag}_resources` : 'NULL'}, `
            + `${plan.resources.length > 0 ? `${tag}_resources_mut` : 'NULL'}, `
            + `${plan.queries.length}u, ${plan.resources.length}u },`);
    });
    out.push('');
    out.push('ES_EXPORT const EsSystemDecl es_systems[] = {');
    out.push(...rows);
    out.push('};');
    out.push(`ES_EXPORT const uint32_t es_system_count = ${systems.length}u;`);
    out.push('');
    return out;
}

/** Module functions still called after the inliner ran, in declaration order. */
function calledFns(module: EirModule, systems: readonly EirSystem[]): string[] {
    const want = new Set<string>();
    const visitExpr = (e: Expr): void => {
        switch (e.e) {
            case 'call':
                if (e.target.k === 'fn' && !want.has(e.target.name)) {
                    want.add(e.target.name);
                    const def = module.fns.get(e.target.name);
                    if (def) visit(def.body);
                }
                for (const a of e.args) visitExpr(a);
                break;
            case 'bin': case 'logic': visitExpr(e.l); visitExpr(e.r); break;
            case 'neg': case 'not': visitExpr(e.v); break;
            case 'select': visitExpr(e.cond); visitExpr(e.then); visitExpr(e.otherwise); break;
            default: break;
        }
    };
    const visit = (stmts: readonly Stmt[]): void => {
        for (const s of stmts) {
            switch (s.s) {
                case 'let': case 'assign': visitExpr(s.value); break;
                case 'return': if (s.value) visitExpr(s.value); break;
                case 'emit': for (const a of s.args) visitExpr(a); break;
                case 'if': visitExpr(s.cond); visit(s.then); visit(s.otherwise); break;
                case 'rowLoop': visit(s.body); break;
            }
        }
    };
    for (const sys of systems) visit(sys.body);
    // Declaration order, so a helper that calls a helper is defined first.
    return [...module.fns.keys()].filter((n) => want.has(n));
}


/**
 * What a module DECLARES, as a host or a runtime reads it — one mapping, where
 * there were two. Structurally typed rather than against the SDK's
 * `AotSystemDecl`: naming that type would pull the whole runtime in here.
 */
export interface ModuleDeclaration {
    readonly name: string;
    readonly symbol: string;
    readonly queries: { comp: string; mut: boolean }[][];
    readonly resources: { name: string; mut: boolean; fields?: string[] }[];
    readonly readers: { slot: number; event: string; fields: string[] }[];
    readonly writers: { slot: number; event: string; fields: string[] }[];
    /** Whether the body appends a command record, which a host has to flush. */
    readonly commands: boolean;
}

export function moduleDeclarations(
    module: EirModule,
    systems: readonly EirSystem[],
): ModuleDeclaration[] {
    const fieldsOf = (table: ReadonlyMap<string, CompShape>, name: string): string[] =>
        [...(table.get(name)?.fields.keys() ?? [])];
    return systems.map((sys) => {
        const plan = planFor(sys);
        return {
            name: sys.name,
            symbol: cSymbol(sys.name),
            queries: plan.queries.map((q) => q.map((a) => ({ comp: a.comp, mut: a.mut }))),
            // An ENGINE resource's shape is `engineAbi`'s; only a project's own
            // travels here, because only the build knows its field order.
            resources: plan.resources.map((r) => (module.userResources.has(r.name)
                ? { name: r.name, mut: r.mut, fields: fieldsOf(module.comps, r.name) }
                : { name: r.name, mut: r.mut })),
            readers: plan.readers.map((r) => ({
                slot: r.slot, event: r.event, fields: fieldsOf(module.events, r.event),
            })),
            writers: plan.writers.map((w) => ({
                slot: w.slot, event: w.event, fields: fieldsOf(module.events, w.event),
            })),
            commands: writesCommands(sys, plan),
        };
    });
}

/**
 * Whether this system appends a COMMAND record — an emit that is not an event.
 *
 * The BODY, not the declaration: taking `Commands()` and never despawning
 * writes nothing, and refusing on the channel would send a system back to the
 * interpreter for a promise it does not make.
 */
function writesCommands(sys: EirSystem, plan: SysPlan): boolean {
    const writerSlots = new Set(plan.writers.map((w) => w.slot));
    const isCommand = (channel: Place): boolean => {
        if (channel.p !== 'local') return true;
        const at = plan.slots.get(channel.id);
        return at === undefined || at.table !== 'channel' || !writerSlots.has(at.slot);
    };
    const walk = (body: readonly Stmt[]): boolean => body.some((s) => {
        if (s.s === 'emit') return isCommand(s.channel);
        if (s.s === 'rowLoop') return walk(s.body);
        if (s.s === 'if') return walk(s.then) || walk(s.otherwise);
        return false;
    });
    return walk(sys.body);
}