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.

feat(compiler): EIR becomes C, and the same bytes come back

yhhed1dbce7ab24
diff --git a/compiler/src/abi.ts b/compiler/src/abi.ts
index 3b79c91ec..5715c3988 100644
--- a/compiler/src/abi.ts
+++ b/compiler/src/abi.ts
@@ -18,14 +18,25 @@
* Field offsets come from PTR_LAYOUTS via builtins.ts — the same EHT
* table the engine and the SDK's accessors already agree on.
*/
-import type { CompShape, EirType, QueryArg } from './eir';
-import type { EirHost } from './interp';
+import { ehtStamp } from './builtins';
+import type { CompShape, EirSystem, EirType, QueryArg } from './eir';
+import { runSystemOn, type EirHost, type Fns } from './interp';
/** One command record: 16 bytes, four u32 (docs/REARCH_AOT_ABI.md §2.3). */
export const CMD_WORDS = 4;
export const CMD_DESPAWN = 1;
export const CMD_REMOVE = 2;
+/**
+ * Words in `SysCtx` and in `QueryRows` (docs/REARCH_AOT_ABI.md §2.1, §2.2).
+ * Exported because THREE things count them — the host below, the code generator,
+ * and the handshake hash — and a contract whose field count has three authors
+ * is the drift this file exists to prevent. §6.3 makes the first of these a
+ * number that needs a reason to grow.
+ */
+export const SYSCTX_WORDS = 6;
+export const QUERYROWS_WORDS = 2;
+
/**
* Where a field lives, and HOW WIDE it is. Component bytes are f32 because EHT
* says the C++ structs are; a resource is a host-side record and `Time.delta` is
@@ -67,23 +78,45 @@ export class AbiMemory {
readonly entities: number[] = [];
readonly cmdBuf: number;
readonly cmdCap = 256;
- cmdCount = 0;
+ /** The per-call arena's high-water mark; see `beginCall`. */
+ private scratchNext: number;
constructor(private readonly layout: AbiLayout, bytes = 1 << 20) {
this.buffer = new ArrayBuffer(bytes);
this.f32 = new Float32Array(this.buffer);
this.f64 = new Float64Array(this.buffer);
this.u32 = new Uint32Array(this.buffer);
+ this.scratchNext = bytes;
this.cmdBuf = this.alloc(this.cmdCap * CMD_WORDS * 4);
}
private alloc(size: number): number {
const at = this.next;
this.next += (size + 15) & ~15;
- if (this.next > this.buffer.byteLength) throw new Error('ABI image out of memory');
+ if (this.next > this.scratchNext) throw new Error('ABI image out of memory');
return at;
}
+ /**
+ * Reset the arena the host refills before every call. Row arrays and the
+ * SysCtx itself live here because §2.2 says they are valid for one call and
+ * the compiled code may not hold them; giving them a region that is thrown
+ * away each time is how that is enforced rather than merely stated.
+ *
+ * It grows DOWN from the end of the image while world data grows up, so the
+ * two allocators cannot silently overlap — they meet, and `alloc` says so.
+ */
+ beginCall(): void {
+ this.scratchNext = this.buffer.byteLength;
+ }
+
+ /** One block of the per-call arena. */
+ scratch(size: number): number {
+ this.scratchNext -= (size + 15) & ~15;
+ if (this.scratchNext < this.next) throw new Error('ABI image out of memory');
+ return this.scratchNext;
+ }
+
/** Give `entity` a row of `comp`, returning its base address. */
addComponent(comp: string, entity: number, fields: Record<string, number | boolean>): number {
const shape = this.layout.comps.get(comp);
@@ -147,24 +180,129 @@ function store(mem: AbiMemory, at: number, bits: 32 | 64, v: number | boolean):
}
/**
- * The host a compiled system would see. `rows` is the packed array SysCtx
- * carries; every field access below is a load or store at a declared offset,
- * and nothing here calls the engine.
+ * Which slot of `SysCtx` each of a system's parameters is. The order is the
+ * declaration order of `_params`, and §2.1 says it is burned into the handshake
+ * hash — so this function, not a convention, is what both the host and the code
+ * generator ask. Two readers of one answer; not two answers.
+ */
+export interface SysPlan {
+ readonly system: string;
+ /** One entry per declared `Query`, in declaration order. */
+ readonly queries: readonly (readonly QueryArg[])[];
+ /** One entry per declared `Res`, in declaration order. */
+ readonly resources: readonly string[];
+ /** One entry per declared channel (`Commands`, later an event reader). */
+ readonly channels: readonly string[];
+ /** A parameter's local id -> which of the three tables, and which slot. */
+ readonly slots: ReadonlyMap<number, { readonly table: 'query' | 'res' | 'channel'; readonly slot: number }>;
+}
+
+export function planFor(sys: EirSystem): SysPlan {
+ const queries: (readonly QueryArg[])[] = [];
+ const resources: string[] = [];
+ const channels: string[] = [];
+ const slots = new Map<number, { table: 'query' | 'res' | 'channel'; slot: number }>();
+ for (const p of sys.params) {
+ switch (p.type.k) {
+ case 'query':
+ slots.set(p.id, { table: 'query', slot: queries.length });
+ queries.push(p.type.args);
+ break;
+ case 'res':
+ slots.set(p.id, { table: 'res', slot: resources.length });
+ resources.push(p.type.name);
+ break;
+ case 'channel':
+ slots.set(p.id, { table: 'channel', slot: channels.length });
+ channels.push(p.type.name);
+ break;
+ default:
+ throw new Error(`ABI: '${p.name}' is a ${p.type.k}, which SysCtx has no table for`);
+ }
+ }
+ return { system: sys.name, queries, resources, channels, slots };
+}
+
+/** A materialised call: where the ctx is, and where its count word lives. */
+export interface AbiCall {
+ readonly ctx: number;
+ readonly cmdCount: number;
+}
+
+/**
+ * Do the host's half of §2.1: pack the rows, resolve the resource addresses,
+ * zero the count, and write the SysCtx. Everything the compiled code will read
+ * is in linear memory when this returns, and it is the ONLY thing there for it.
+ *
+ * Row materialisation follows the strategy `View.hpp` already uses — walk the
+ * entities, keep the ones carrying every named component. The ABI exposes the
+ * existing strategy rather than inventing a second one.
+ */
+export function materialize(mem: AbiMemory, plan: SysPlan): AbiCall {
+ mem.beginCall();
+ const queryTable = mem.scratch(Math.max(1, plan.queries.length) * QUERYROWS_WORDS * 4);
+ plan.queries.forEach((args, k) => {
+ const stride = 1 + args.length;
+ const matched: number[] = [];
+ for (const e of mem.entities) {
+ const binds = args.map((a) => mem.baseOf(a.comp, e));
+ if (binds.some((b) => b === undefined)) continue;
+ matched.push(e, ...(binds as number[]));
+ }
+ const rows = mem.scratch(Math.max(4, matched.length * 4));
+ for (let i = 0; i < matched.length; i++) mem.u32[(rows >> 2) + i] = matched[i]!;
+ mem.u32[(queryTable >> 2) + k * QUERYROWS_WORDS] = rows;
+ mem.u32[(queryTable >> 2) + k * QUERYROWS_WORDS + 1] = matched.length / stride;
+ });
+
+ const resTable = mem.scratch(Math.max(4, plan.resources.length * 4));
+ plan.resources.forEach((name, k) => { mem.u32[(resTable >> 2) + k] = mem.resourceBase(name); });
+
+ const cmdCount = mem.scratch(4);
+ mem.u32[cmdCount >> 2] = 0;
+
+ const ctx = mem.scratch(SYSCTX_WORDS * 4);
+ const w = ctx >> 2;
+ mem.u32[w] = queryTable;
+ mem.u32[w + 1] = resTable;
+ mem.u32[w + 2] = mem.cmdBuf;
+ mem.u32[w + 3] = mem.cmdCap;
+ mem.u32[w + 4] = cmdCount;
+ mem.u32[w + 5] = 0; // events: no channel in v1 carries one yet
+ return { ctx, cmdCount };
+}
+
+/**
+ * The host a compiled system sees, reaching the world through NOTHING but the
+ * ctx `materialize` wrote. Every field access below is a load or store at a
+ * declared offset, and there is no engine call to make.
+ *
+ * It reads the packed row array rather than re-deriving the rows, so that the
+ * interpreter and the generated C consume the same bytes. A host that walked
+ * `mem.entities` again would agree with the compiled code only by coincidence.
*/
-export function abiHost(mem: AbiMemory, layout: AbiLayout): EirHost {
+export function abiHost(mem: AbiMemory, layout: AbiLayout, plan: SysPlan, call: AbiCall): EirHost {
const leafAt = (owner: string, path: readonly string[]): Leaf => {
const shape = layout.comps.get(owner) ?? layout.resources.get(owner);
const leaf = shape?.leaves.get(path.join('.'));
if (!leaf) throw new Error(`ABI: '${owner}' has no field '${path.join('.')}'`);
return leaf;
};
+ const w = call.ctx >> 2;
+ const queryTable = mem.u32[w]!;
+ const resTable = mem.u32[w + 1]!;
+ const cmdBuf = mem.u32[w + 2]!;
+ const cmdCap = mem.u32[w + 3]!;
return {
*rows(args: readonly QueryArg[]) {
- // What the host materialises: [entity, base0, base1, …] per row.
- for (const e of mem.entities) {
- const binds = args.map((a) => mem.baseOf(a.comp, e));
- if (binds.some((b) => b === undefined)) continue;
- yield { entity: e, binds: binds as number[] };
+ const k = plan.queries.indexOf(args);
+ if (k < 0) throw new Error(`ABI: '${plan.system}' walks a query it did not declare`);
+ const rows = mem.u32[(queryTable >> 2) + k * QUERYROWS_WORDS]!;
+ const count = mem.u32[(queryTable >> 2) + k * QUERYROWS_WORDS + 1]!;
+ const stride = 1 + args.length;
+ for (let i = 0; i < count; i++) {
+ const at = (rows >> 2) + i * stride;
+ yield { entity: mem.u32[at]!, binds: args.map((_, j) => mem.u32[at + 1 + j]!) };
}
},
readField(base, owner, path) {
@@ -176,26 +314,94 @@ export function abiHost(mem: AbiMemory, layout: AbiLayout): EirHost {
store(mem, (base as number) + leaf.byteOffset, leaf.bits, v);
},
resource(name) {
- return mem.resourceBase(name);
+ const k = plan.resources.indexOf(name);
+ if (k < 0) throw new Error(`ABI: '${plan.system}' reads a resource it did not declare`);
+ return mem.u32[(resTable >> 2) + k]!;
},
emit(record, args) {
- if (mem.cmdCount >= mem.cmdCap) throw new Error('ABI: command buffer overflow');
- const at = (mem.cmdBuf >> 2) + mem.cmdCount * CMD_WORDS;
+ const n = mem.u32[call.cmdCount >> 2]!;
+ if (n >= cmdCap) throw new Error('ABI: command buffer overflow');
+ const at = (cmdBuf >> 2) + n * CMD_WORDS;
mem.u32[at] = record === 'despawn' ? CMD_DESPAWN : CMD_REMOVE;
mem.u32[at + 1] = args[0] as number;
- mem.cmdCount++;
+ mem.u32[at + 2] = 0;
+ mem.u32[at + 3] = 0;
+ mem.u32[call.cmdCount >> 2] = n + 1;
},
flush() {
- const at = mem.cmdBuf >> 2;
- for (let i = 0; i < mem.cmdCount; i++) {
- const kind = mem.u32[at + i * CMD_WORDS]!;
- if (kind === CMD_DESPAWN) mem.despawn(mem.u32[at + i * CMD_WORDS + 1]!);
- }
- mem.cmdCount = 0;
+ flushCommands(mem, call);
},
};
}
+/**
+ * The host's other half: apply what the call wrote. Shared by the interpreter
+ * and by whatever ran the compiled code, because the records are the same
+ * records — which is the whole reason they are records and not calls.
+ */
+export function flushCommands(mem: AbiMemory, call: AbiCall): void {
+ const n = mem.u32[call.cmdCount >> 2]!;
+ const at = mem.cmdBuf >> 2;
+ for (let i = 0; i < n; i++) {
+ const kind = mem.u32[at + i * CMD_WORDS]!;
+ if (kind === CMD_DESPAWN) mem.despawn(mem.u32[at + i * CMD_WORDS + 1]!);
+ }
+ mem.u32[call.cmdCount >> 2] = 0;
+}
+
+/**
+ * One system, one call, through the contract: materialise, run, flush. The
+ * generated code's runner does exactly these three steps with the middle one
+ * replaced — which is what makes the difference between them measurable.
+ */
+export function runOnAbi(sys: EirSystem, mem: AbiMemory, layout: AbiLayout, fns: Fns = new Map()): void {
+ const plan = planFor(sys);
+ const call = materialize(mem, plan);
+ runSystemOn(sys, abiHost(mem, layout, plan, call), fns);
+}
+
+/**
+ * The handshake constant of §2.5: EHT's component offsets, the shape of the
+ * three structs, and every system's parameter order, in one 64-bit number the
+ * loader compares before it maps anything. A mismatch is not a wrong answer —
+ * it is a read of a DIFFERENT FIELD — so this is refused, not warned about.
+ *
+ * FNV-1a, as `mkbc` and the asset hashes already use; not a new mechanism.
+ */
+export function abiHash(layout: AbiLayout, plans: readonly SysPlan[]): string {
+ const parts: string[] = [
+ `eht=${ehtStamp()}`,
+ `sysctx=${SYSCTX_WORDS} queryrows=${QUERYROWS_WORDS} cmd=${CMD_WORDS}`,
+ ];
+ const table = (kind: string, m: ReadonlyMap<string, FieldOffsets>): void => {
+ for (const [name, f] of m) {
+ const leaves = [...f.leaves].map(([p, l]) => `${p}@${l.byteOffset}:${l.bits}`).join(',');
+ parts.push(`${kind} ${name} stride=${f.stride} ${leaves}`);
+ }
+ };
+ table('comp', layout.comps);
+ table('res', layout.resources);
+ for (const p of plans) {
+ const qs = p.queries.map((q) => q.map((a) => (a.mut ? `mut ${a.comp}` : a.comp)).join('+')).join('|');
+ // The ORDER parameters were declared in, not just what they were: two
+ // systems taking a Query and a Res differ only here, and a loader that
+ // could not tell them apart would read the row array as the resource.
+ const order = [...p.slots.values()].map((s) => `${s.table}${s.slot}`).join(',');
+ parts.push(`sys ${p.system} order=${order} q=${qs} r=${p.resources.join('|')} c=${p.channels.join('|')}`);
+ }
+ return fnv1a64(parts.join('\n'));
+}
+
+function fnv1a64(text: string): string {
+ const MASK = (1n << 64n) - 1n;
+ let h = 0xcbf29ce484222325n;
+ for (let i = 0; i < text.length; i++) {
+ h = (h ^ BigInt(text.charCodeAt(i) & 0xff)) & MASK;
+ h = (h * 0x100000001b3n) & MASK;
+ }
+ return h.toString(16).padStart(16, '0');
+}
+
/**
* Byte offsets for every shape: leaves in declaration order, at the width the
* SHAPE declares. Nothing here asks what a name means — `engine` shapes are the
diff --git a/compiler/src/builtins.ts b/compiler/src/builtins.ts
index 68821b6e0..0ca23a6e0 100644
--- a/compiler/src/builtins.ts
+++ b/compiler/src/builtins.ts
@@ -66,3 +66,23 @@ const TIME: CompShape = {
['delta', 'elapsed', 'frameCount', 'fixedDelta', 'fixedAlpha', 'fixedTick', 'scale', 'unscaledDelta']
.map((k) => [k, { type: F64, bits: 64 }] as const)),
};
+
+/**
+ * A stamp over EHT's table, for the §2.5 handshake. It hashes the OFFSETS
+ * themselves rather than importing `ABI_LAYOUT_HASH`, for two reasons: that
+ * constant lives in `component.generated.ts`, whose imports reach the whole SDK
+ * runtime and would make the compiler depend on it; and the raw table is
+ * strictly more information than a hash of it. Same property either way — it
+ * changes when the C++ structs change, which is the only thing asked of it.
+ */
+export function ehtStamp(): string {
+ const parts: string[] = [];
+ for (const [name, layout] of Object.entries(PTR_LAYOUTS)) {
+ const fields = layout.fields
+ .map((f) => `${f.name}:${f.type}@${f.offset}`
+ + (f.members ? `{${f.members.map((m) => `${m.name}:${m.type}@${m.offset}`).join(',')}}` : ''))
+ .join(',');
+ parts.push(`${name}(${layout.ptrFn})=${fields}`);
+ }
+ return parts.join(';');
+}
diff --git a/compiler/src/codegen.ts b/compiler/src/codegen.ts
new file mode 100644
index 000000000..4f502385a
--- /dev/null
+++ b/compiler/src/codegen.ts
@@ -0,0 +1,620 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file codegen.ts
+ * @brief EIR -> C, against the SysCtx contract (docs/REARCH_AOT.md §10 Stage 2).
+ *
+ * @details The backend emits C rather than LLVM IR, and the reason is in §17:
+ * 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. That is §6.5's empty import
+ * section, arrived at 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 {
+ CMD_DESPAWN, CMD_REMOVE, CMD_WORDS, QUERYROWS_WORDS,
+ abiHash, planFor,
+ type AbiLayout, type FieldOffsets, type Leaf, type SysPlan,
+} from './abi';
+import {
+ BOOL, F64,
+ type EirFn, type EirModule, type EirSystem, type EirType, type Expr, type Local,
+ 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',
+];
+
+export interface CModule {
+ /** `estella_abi.h` — the contract's C side, and the only thing the code calls. */
+ readonly header: string;
+ /** The translation unit: offsets, module functions, systems. */
+ readonly source: string;
+ /** Exported symbols, one per compiled system. */
+ readonly symbols: readonly string[];
+ /** The §2.5 handshake constant, also emitted into the source. */
+ readonly hash: string;
+}
+
+// =============================================================================
+// 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 — §6.5 holds because there was never anything to import.
+ */
+export const RUNTIME_H = `/* GENERATED by @estella/compiler — do not edit. */
+/* The Estella ABI, C side. docs/REARCH_AOT_ABI.md */
+#ifndef ESTELLA_ABI_H
+#define ESTELLA_ABI_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;
+ this is belt and braces for the compiler that does honour it. */
+#if defined(__clang__)
+#pragma STDC FP_CONTRACT OFF
+#endif
+
+/* An address in the ABI is a u32 offset into one linear memory. On wasm that
+ memory starts at zero, so the offset already IS the pointer; natively the
+ host owns a block and hands us its base. Same offsets either way — which is
+ what lets one emitted source serve both back ends. */
+#if defined(__wasm__)
+#define ES_MEM ((unsigned char *)0)
+#else
+extern unsigned char *es_memory;
+#define ES_MEM es_memory
+#endif
+
+/* memcpy, not a cast: the image is a byte block, and a u32 read through an
+ aligned pointer is undefined if the host ever hands us an odd base. */
+static inline uint32_t es_u32(uint32_t a) { uint32_t v; memcpy(&v, ES_MEM + a, 4); return v; }
+static inline void es_set_u32(uint32_t a, uint32_t v) { memcpy(ES_MEM + a, &v, 4); }
+static inline double es_f32(uint32_t a) { float v; memcpy(&v, ES_MEM + a, 4); return (double)v; }
+static inline void es_set_f32(uint32_t a, double v) { float f = (float)v; memcpy(ES_MEM + a, &f, 4); }
+static inline double es_f64(uint32_t a) { double v; memcpy(&v, ES_MEM + a, 8); return v; }
+static inline void es_set_f64(uint32_t a, double v) { memcpy(ES_MEM + a, &v, 8); }
+
+/* ---------------------------------------------------------------------------
+ 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); }
+
+/* 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, '_');
+}
+
+function cType(t: EirType): string {
+ switch (t.k) {
+ case 'f64': return 'double';
+ case 'bool': return 'int';
+ case 'entity': return 'uint32_t';
+ case 'comp': case 'res': return 'uint32_t';
+ default: throw new Error(`codegen: a ${t.k} is not a C value`);
+ }
+}
+
+/** Three representations, so a coercion is a lookup rather than a case tree. */
+type Repr = 'double' | 'int' | 'uint32_t';
+
+function repr(t: EirType): Repr {
+ return 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 (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`;
+}
+
+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',
+};
+
+// =============================================================================
+// 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;
+ case 'call': for (const a of e.args) expr(a); break;
+ }
+ };
+ for (const s of stmts) {
+ switch (s.s) {
+ case 'let': case 'return': expr(s.value); 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';
+ 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);
+ const load = leaf.bits === 64 ? `es_f64(${addr})` : `es_f32(${addr})`;
+ return coerce(load, 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 '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, `return ${this.expr(s.value)};`);
+ 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 store = leaf.bits === 64 ? 'es_set_f64' : 'es_set_f32';
+ this.line(indent, `${store}(${addr}, ${coerce(this.expr(s.value), s.value.type, F64)});`);
+ 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: §3 forbids writing past it, and the host is what sized it.
+ */
+ private emitCommand(s: Stmt & { s: 'emit' }, indent: number): void {
+ const kind = s.record === 'despawn' ? CMD_DESPAWN : CMD_REMOVE;
+ this.line(indent, 'if (es_cmd_n < es_cmd_cap) {');
+ this.line(indent + 1, `const uint32_t es_at = es_cmd_buf + es_cmd_n * ${CMD_WORDS * 4}u;`);
+ this.line(indent + 1, `es_set_u32(es_at, ${kind}u); /* ${s.record} */`);
+ for (let i = 1; i < CMD_WORDS; i++) {
+ const a = s.args[i - 1];
+ const v = a ? coerce(this.expr(a), a.type, { k: 'entity' }) : '0u';
+ this.line(indent + 1, `es_set_u32(es_at + ${i * 4}u, ${v});`);
+ }
+ this.line(indent + 1, 'es_cmd_n += 1u;');
+ this.line(indent, '}');
+ }
+
+ /**
+ * The op EIR exists to keep (§4.2): 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 at = slot.slot * QUERYROWS_WORDS * 4;
+ const reads = new Set<number>();
+ readsOf(s.body, reads);
+ this.line(indent, '{');
+ this.line(indent + 1, `const uint32_t es_rows${d} = es_u32(es_queries + ${at}u);`);
+ this.line(indent + 1, `const uint32_t es_n${d} = es_u32(es_queries + ${at + 4}u);`);
+ this.line(indent + 1, `for (uint32_t es_i${d} = 0u; es_i${d} < es_n${d}; ++es_i${d}) {`);
+ this.line(indent + 2, `const uint32_t es_row${d} = es_rows${d} + es_i${d} * ${stride * 4}u;`);
+ if (s.entity !== null && reads.has(s.entity)) {
+ this.line(indent + 2, `const uint32_t ${cName(this.local(s.entity))} = es_u32(es_row${d});`);
+ }
+ 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,
+ `const uint32_t ${cName(this.local(id))} = es_u32(es_row${d} + ${(i + 1) * 4}u);`);
+ });
+ 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) => `${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)` — §2.1's 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, `void ${cSymbol(sys.name)}(uint32_t es_ctx) {`);
+ if (plan.queries.length > 0) this.line(1, 'const uint32_t es_queries = es_u32(es_ctx);');
+ const usesRes = sys.params.some((p) => plan.slots.get(p.id)!.table === 'res' && reads.has(p.id));
+ if (usesRes) this.line(1, 'const uint32_t es_resources = es_u32(es_ctx + 4u);');
+ const emits = hasEmit(sys.body);
+ if (emits) {
+ this.line(1, 'const uint32_t es_cmd_buf = es_u32(es_ctx + 8u);');
+ this.line(1, 'const uint32_t es_cmd_cap = es_u32(es_ctx + 12u);');
+ this.line(1, 'const uint32_t es_cmd_at = es_u32(es_ctx + 16u);');
+ this.line(1, 'uint32_t es_cmd_n = es_u32(es_cmd_at);');
+ }
+ // 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, `const uint32_t ${cName(p)} = es_u32(es_resources + ${slot.slot * 4}u);`);
+ }
+ this.declare(sys.locals.filter((l) => !bound.has(l.id)), reads, 1);
+ this.stmts(sys.body, 1);
+ if (emits) this.line(1, 'es_set_u32(es_cmd_at, es_cmd_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, `${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[]): 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 hash = abiHash(layout, plans);
+ const macros = [...offsets].sort(([a], [b]) => (a < b ? -1 : 1)).map(([k, v]) => `#define ${k} ${v}u`);
+ const source = [
+ '/* GENERATED by @estella/compiler — do not edit. */',
+ '/* docs/REARCH_AOT_ABI.md: this file calls the engine zero times. */',
+ '#include "estella_abi.h"',
+ '',
+ '/* §2.5: the loader compares this before it maps anything. A mismatch is',
+ ' not a wrong answer, it is a read of a different field. */',
+ `const uint64_t es_abi_hash = 0x${hash}ULL;`,
+ '',
+ '/* Component and resource field offsets, from EHT. */',
+ ...macros,
+ '',
+ ...bodies,
+ ].join('\n');
+
+ return { header: RUNTIME_H, source, symbols: systems.map((s) => cSymbol(s.name)), hash };
+}
+
+/** 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 'return': case 'assign': 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));
+}
diff --git a/compiler/src/index.ts b/compiler/src/index.ts
index 3a8bfbe61..ed48fec9e 100644
--- a/compiler/src/index.ts
+++ b/compiler/src/index.ts
@@ -2,11 +2,17 @@
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file index.ts
- * @brief Estella AOT compiler — public surface (docs/REARCH_AOT.md Stage 1).
+ * @brief Estella AOT compiler — public surface (docs/REARCH_AOT.md Stages 1-2).
*/
export * from './eir';
export { lowerProgram, type Diagnostic, type LowerResult } from './frontend';
export { verifySystem, type VerifyError } from './verify';
export { runSystem, type EirWorld, type Fns, type Row } from './interp';
export { inlineModule, inlineSystem } from './inline';
+export {
+ AbiMemory, abiHash, abiHost, flushCommands, materialize, packLayout, planFor, runOnAbi,
+ CMD_DESPAWN, CMD_REMOVE, CMD_WORDS, QUERYROWS_WORDS, SYSCTX_WORDS,
+ type AbiCall, type AbiLayout, type FieldOffsets, type Leaf, type SysPlan,
+} from './abi';
+export { CFLAGS, RUNTIME_H, cSymbol, emitC, type CModule } from './codegen';
export { builtinShapes } from './builtins';
diff --git a/compiler/tests/abi.test.ts b/compiler/tests/abi.test.ts
index c465918c0..e8e08d72e 100644
--- a/compiler/tests/abi.test.ts
+++ b/compiler/tests/abi.test.ts
@@ -17,9 +17,9 @@ import { resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
import { lowerProgram } from '../src/frontend';
import { verifySystem } from '../src/verify';
-import { runSystem, runSystemOn, type EirWorld, type Row } from '../src/interp';
+import { runSystem, type EirWorld, type Row } from '../src/interp';
import { builtinShapes } from '../src/builtins';
-import { AbiMemory, abiHost, packLayout } from '../src/abi';
+import { AbiMemory, packLayout, runOnAbi } from '../src/abi';
import { moveSystem } from '../../examples/ecs-basics/src/systems/move';
import { lifetimeSystem } from '../../examples/ecs-basics/src/systems/lifetime';
@@ -124,7 +124,6 @@ describe('the ABI is sufficient for the systems the subset compiles', () => {
const byNode = jsWorld();
const byJs = jsWorld();
const mem = abiWorld();
- const host = abiHost(mem, layout);
const sys = moveSystem as unknown as StubSystem;
for (let f = 0; f < 30; f++) {
@@ -136,7 +135,7 @@ describe('the ABI is sufficient for the systems the subset compiles', () => {
},
}, byNode.resources.get('Time'));
runSystem(move, byJs, module.fns);
- runSystemOn(move, host, module.fns);
+ runOnAbi(move, mem, layout, module.fns);
}
for (let i = 1; i <= N; i++) {
@@ -152,10 +151,9 @@ describe('the ABI is sufficient for the systems the subset compiles', () => {
it('LifetimeSystem: despawn through the command buffer removes the same entities', () => {
const byJs = jsWorld();
const mem = abiWorld();
- const host = abiHost(mem, layout);
for (let f = 0; f < 30; f++) {
runSystem(life, byJs, module.fns);
- runSystemOn(life, host, module.fns);
+ runOnAbi(life, mem, layout, module.fns);
expect(mem.entities, `frame ${f}`).toEqual(byJs.entities);
}
expect(byJs.entities.length).toBeLessThan(N);
diff --git a/compiler/tests/codegen.test.ts b/compiler/tests/codegen.test.ts
new file mode 100644
index 000000000..7149e565d
--- /dev/null
+++ b/compiler/tests/codegen.test.ts
@@ -0,0 +1,393 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file codegen.test.ts
+ * @brief The compiled code and the interpreter must produce the SAME BYTES.
+ *
+ * @details Stage 2's exit criterion in miniature (docs/REARCH_AOT.md §10). Up to
+ * here every test has compared an interpreter against node; both are
+ * JavaScript, and neither is what ships. This one compiles the emitted
+ * C with a real compiler and runs it in another process.
+ *
+ * The differential is over the IMAGE, not over selected fields. The
+ * host materialises a SysCtx, the bytes go to a program that knows
+ * nothing but `es_sys_*`, and what comes back is compared to what the
+ * interpreter produced from the identical starting bytes — memcmp, the
+ * whole world. A per-field check would pass while a system wrote one
+ * byte past a component, which is precisely the failure a contract made
+ * of offsets has.
+ *
+ * Two more properties are asserted because they are what make this a
+ * contract rather than a convention: the object file has no undefined
+ * symbol besides the memory base (§6.5's empty import section, as far
+ * as a native build can show it), and the generated C compiles with no
+ * warning at all.
+ *
+ * If no C compiler is on PATH the differential CANNOT run, and this
+ * file says so out loud rather than reporting green — a gate that never
+ * saw its subject is worse than a missing one, because it is counted.
+ */
+import { describe, it, expect } from 'vitest';
+import { execFileSync, spawnSync } from 'node:child_process';
+import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { lowerProgram } from '../src/frontend';
+import { verifySystem } from '../src/verify';
+import { inlineSystem } from '../src/inline';
+import { builtinShapes } from '../src/builtins';
+import { AbiMemory, flushCommands, materialize, packLayout, planFor, runOnAbi } from '../src/abi';
+import { CFLAGS, cSymbol, emitC, type CModule } from '../src/codegen';
+import type { AbiLayout } from '../src/abi';
+import type { EirSystem } from '../src/eir';
+import type { Row } from '../src/interp';
+
+import { moveSystem } from '../../examples/ecs-basics/src/systems/move';
+import { driftSystem } from './fixtures/in-subset';
+import { PROBE } from './probe';
+import type { StubSystem } from './stubs/esengine';
+
+const ROOT = resolve(fileURLToPath(new URL('../..', import.meta.url)));
+const FIXTURE = resolve(fileURLToPath(new URL('./fixtures/in-subset.ts', import.meta.url)));
+const N = 24;
+const FRAMES = 12;
+/** Small enough that a frame is one cheap pipe, big enough for the world above. */
+const IMAGE = 1 << 16;
+
+// =============================================================================
+// finding a C compiler
+// =============================================================================
+
+/**
+ * clang first because it is what Stage 2 ships with — emcc is clang and the
+ * aarch64 path is clang. gcc is accepted, and is arguably the better witness:
+ * agreeing with a SECOND independent implementation of C says more than
+ * agreeing with the one the lowering was written against.
+ */
+function findCC(): string | null {
+ for (const cc of ['clang', 'gcc', 'cc']) {
+ if (spawnSync(cc, ['--version'], { encoding: 'utf8' }).status === 0) return cc;
+ }
+ return null;
+}
+
+const CC = findCC();
+
+/** The harness: linear memory in on stdin, linear memory out on stdout. */
+const MAIN_C = `/* Test scaffolding, not compiler output. */
+#include <stdio.h>
+#include <stdlib.h>
+#if defined(_WIN32)
+#include <io.h>
+#include <fcntl.h>
+#endif
+#include "estella_abi.h"
+
+unsigned char *es_memory;
+
+void ES_ENTRY(uint32_t ctx);
+
+int main(int argc, char **argv) {
+ long n;
+ uint32_t ctx;
+ if (argc != 3) { fprintf(stderr, "usage: run <bytes> <ctx>\\n"); return 2; }
+ n = strtol(argv[1], NULL, 10);
+ ctx = (uint32_t)strtoul(argv[2], NULL, 10);
+ es_memory = (unsigned char *)malloc((size_t)n);
+ if (!es_memory) return 3;
+#if defined(_WIN32)
+ /* Text mode would insert a 0x0d before every 0x0a in the image. */
+ _setmode(_fileno(stdin), _O_BINARY);
+ _setmode(_fileno(stdout), _O_BINARY);
+#endif
+ if (fread(es_memory, 1, (size_t)n, stdin) != (size_t)n) return 4;
+ ES_ENTRY(ctx);
+ if (fwrite(es_memory, 1, (size_t)n, stdout) != (size_t)n) return 5;
+ return 0;
+}
+`;
+
+/** Build one executable per system; the entry symbol is a -D, so main is shared. */
+function build(dir: string, cModule: CModule, symbol: string): string {
+ mkdirSync(dir, { recursive: true });
+ writeFileSync(join(dir, 'estella_abi.h'), cModule.header);
+ writeFileSync(join(dir, 'systems.c'), cModule.source);
+ writeFileSync(join(dir, 'main.c'), MAIN_C);
+ const exe = join(dir, `${symbol}${process.platform === 'win32' ? '.exe' : ''}`);
+ const out = spawnSync(CC!, [
+ ...CFLAGS, '-Wall', '-Wextra',
+ `-DES_ENTRY=${symbol}`,
+ '-o', exe,
+ join(dir, 'main.c'), join(dir, 'systems.c'),
+ '-lm',
+ ], { encoding: 'utf8' });
+ if (out.status !== 0) throw new Error(`${CC} failed:\n${out.stderr}`);
+ // A warning in generated code is a warning nobody will ever read, so the bar
+ // is zero rather than "none that matter".
+ expect(out.stderr.trim(), 'the generated C must compile without a warning').toBe('');
+ return exe;
+}
+
+/** One call of the contract: materialise, run the compiled code, flush. */
+function frameOfC(exe: string, mem: AbiMemory, sys: EirSystem): void {
+ const call = materialize(mem, planFor(sys));
+ const image = Buffer.from(mem.buffer);
+ const out = execFileSync(exe, [String(image.length), String(call.ctx)], {
+ input: image,
+ maxBuffer: image.length * 2 + (1 << 16),
+ });
+ expect(out.length, 'the harness returned a different image').toBe(image.length);
+ image.set(out);
+ flushCommands(mem, call);
+}
+
+// =============================================================================
+// the corpus: one shipped system, and the fixtures covering the rest of the subset
+// =============================================================================
+
+const shipped = lowerProgram([
+ resolve(ROOT, 'examples/ecs-basics/src/systems/move.ts'),
+ resolve(ROOT, 'examples/ecs-basics/src/components.ts'),
+], builtinShapes());
+
+const fixtures = lowerProgram([FIXTURE], builtinShapes());
+
+function systemOf(result: typeof shipped, name: string): EirSystem {
+ const sys = result.module.systems.find((s) => s.name === name);
+ if (!sys) throw new Error(`no system '${name}': ${JSON.stringify(result.diagnostics)}`);
+ expect(verifySystem(sys, result.module.comps, result.module.fns), name).toEqual([]);
+ return inlineSystem(sys, result.module.fns);
+}
+
+/** Deterministic, and spread so every branch of every fixture is taken. */
+function seed(i: number): Record<string, number> {
+ return {
+ tx: (i % 7) * 13 - 40, ty: (i % 5) * 9 - 20,
+ dx: (i % 3) - 1, dy: ((i % 4) - 2) / 2,
+ speed: 40 + (i % 6) * 15,
+ rate: (i % 11) * 12,
+ };
+}
+
+/** Stores round through f32 for an engine pool; a JS world that did not would
+ * drift from the image by construction rather than by bug. */
+function f32Row(fields: Record<string, unknown>): Row {
+ const out: Record<string, unknown> = {};
+ for (const [k, v] of Object.entries(fields)) {
+ if (v !== null && typeof v === 'object') { out[k] = f32Row(v as Record<string, unknown>); continue; }
+ let held = Math.fround(v as number);
+ Object.defineProperty(out, k, {
+ enumerable: true,
+ get: () => held,
+ set: (n: number) => { held = Math.fround(n); },
+ });
+ }
+ return out;
+}
+
+function transformRow(tx: number, ty: number): Row {
+ return f32Row({
+ position: { x: tx, y: ty, z: 0 },
+ rotation: { x: 0, y: 0, z: 0, w: 1 }, scale: { x: 1, y: 1, z: 1 },
+ worldPosition: { x: 0, y: 0, z: 0 },
+ worldRotation: { x: 0, y: 0, z: 0, w: 1 }, worldScale: { x: 1, y: 1, z: 1 },
+ });
+}
+
+function movedWorld(layout: AbiLayout): AbiMemory {
+ const mem = new AbiMemory(layout, IMAGE);
+ mem.addResource('Time', { delta: 1 / 30 });
+ for (let i = 1; i <= N; i++) {
+ const s = seed(i);
+ mem.addComponent('Transform', i, { 'position.x': s['tx']!, 'position.y': s['ty']! });
+ mem.addComponent('Mover', i, { speed: s['speed']!, directionX: s['dx']!, directionY: s['dy']! });
+ }
+ return mem;
+}
+
+function fixtureWorld(layout: AbiLayout): AbiMemory {
+ const mem = new AbiMemory(layout, IMAGE);
+ mem.addResource('Time', { delta: 1 / 30, elapsed: 0 });
+ for (let i = 1; i <= N; i++) {
+ const s = seed(i);
+ mem.addComponent('Transform', i, { 'position.x': s['tx']!, 'position.y': s['ty']! });
+ mem.addComponent('FixtureDrift', i, { rate: s['rate']!, wrap: 100, enabled: i % 4 !== 0 });
+ mem.addComponent('FixtureClamp', i, { lo: -50, hi: 50, push: 30 });
+ // The probe values are the point of this component, not a default: they
+ // are where libm and ECMAScript disagree.
+ mem.addComponent('FixtureMathProbe', i, { v: PROBE[(i - 1) % PROBE.length]! });
+ }
+ return mem;
+}
+
+const same = (a: AbiMemory, b: AbiMemory): boolean =>
+ Buffer.from(a.buffer).equals(Buffer.from(b.buffer));
+
+// =============================================================================
+
+describe('the emitted C says what the interpreter says', () => {
+ it('reports whether this gate could run at all', () => {
+ // Not a skip: a missing compiler means the differential did not happen,
+ // and a suite that stays silent about that is reporting a green it did
+ // not earn.
+ if (CC) console.log(`[codegen] the differential ran against ${CC}`);
+ else console.warn('[codegen] NO C COMPILER ON PATH — the differential did NOT run.');
+ expect(true).toBe(true);
+ });
+
+ if (!CC) return;
+
+ const tmp = mkdtempSync(join(tmpdir(), 'estella-aot-'));
+
+ it('MoveSystem: the whole image agrees with the interpreter, and both with node', () => {
+ const move = systemOf(shipped, 'MoveSystem');
+ const layout = packLayout(shipped.module.comps);
+ const exe = build(join(tmp, 'move'), emitC(shipped.module, layout, [move]), cSymbol('MoveSystem'));
+
+ const byInterp = movedWorld(layout);
+ const byC = movedWorld(layout);
+ expect(same(byC, byInterp), 'the two runs did not start from the same bytes').toBe(true);
+
+ // node, over the same file the compiler read — a retyped copy would only
+ // ever agree with its own mistakes.
+ const transforms = new Map<number, Row>();
+ const movers = new Map<number, Row>();
+ const entities: number[] = [];
+ for (let i = 1; i <= N; i++) {
+ const s = seed(i);
+ entities.push(i);
+ transforms.set(i, transformRow(s['tx']!, s['ty']!));
+ movers.set(i, f32Row({ speed: s['speed']!, directionX: s['dx']!, directionY: s['dy']! }));
+ }
+ const time = { delta: 1 / 30 };
+ const stub = (moveSystem as unknown as StubSystem).fn as unknown as (q: unknown, t: unknown) => void;
+
+ for (let f = 0; f < FRAMES; f++) {
+ runOnAbi(move, byInterp, layout, shipped.module.fns);
+ frameOfC(exe, byC, move);
+ stub({
+ *[Symbol.iterator]() {
+ for (const e of entities) yield [e, transforms.get(e)!, movers.get(e)!];
+ },
+ }, time);
+
+ for (let i = 1; i <= N; i++) {
+ const want = transforms.get(i)!['position'] as Record<string, number>;
+ expect(byC.read('Transform', i, 'position.x'), `frame ${f} entity ${i}`).toBe(want['x']);
+ expect(byC.read('Transform', i, 'position.y'), `frame ${f} entity ${i}`).toBe(want['y']);
+ }
+ }
+
+ // The whole image, not the fields this test thought to look at.
+ expect(same(byC, byInterp), 'compiled and interpreted images differ somewhere').toBe(true);
+ expect(same(byC, movedWorld(layout)), 'nothing moved, so agreeing proves nothing').toBe(false);
+ });
+
+ // Every feature the subset gained after MoveSystem, each in a system that
+ // exercises it: branches and `&&`, ternaries and the exact half of Math,
+ // folded module constants with a shadowing local, an inlined helper, and the
+ // Math arguments where libm and ECMAScript give different answers.
+ for (const name of ['FixtureDrift', 'FixtureClampSys', 'FixtureTuned', 'FixtureHelpers', 'FixtureMathOps']) {
+ it(`${name}: the whole image agrees with the interpreter`, () => {
+ const sys = systemOf(fixtures, name);
+ const layout = packLayout(fixtures.module.comps);
+ const exe = build(join(tmp, name), emitC(fixtures.module, layout, [sys]), cSymbol(name));
+
+ const byInterp = fixtureWorld(layout);
+ const byC = fixtureWorld(layout);
+ for (let f = 0; f < FRAMES; f++) {
+ runOnAbi(sys, byInterp, layout, fixtures.module.fns);
+ frameOfC(exe, byC, sys);
+ expect(same(byC, byInterp), `${name}: images differ at frame ${f}`).toBe(true);
+ }
+ expect(same(byC, fixtureWorld(layout)), `${name} changed nothing`).toBe(false);
+ });
+ }
+
+ it('FixtureDrift also agrees with node, not only with the interpreter', () => {
+ const drift = systemOf(fixtures, 'FixtureDrift');
+ const layout = packLayout(fixtures.module.comps);
+ const exe = build(join(tmp, 'drift-node'), emitC(fixtures.module, layout, [drift]),
+ cSymbol('FixtureDrift'));
+
+ const mem = fixtureWorld(layout);
+ const transforms = new Map<number, Row>();
+ const drifts = new Map<number, Row>();
+ const entities: number[] = [];
+ for (let i = 1; i <= N; i++) {
+ const s = seed(i);
+ entities.push(i);
+ transforms.set(i, transformRow(s['tx']!, s['ty']!));
+ // A defineComponent shape is host-stored, so f64 — no fround here.
+ drifts.set(i, { rate: s['rate']!, wrap: 100, enabled: i % 4 !== 0 });
+ }
+ const time = { delta: 1 / 30, elapsed: 0 };
+ const stub = (driftSystem as unknown as StubSystem).fn as unknown as (q: unknown, t: unknown) => void;
+
+ for (let f = 0; f < FRAMES; f++) {
+ frameOfC(exe, mem, drift);
+ stub({
+ *[Symbol.iterator]() {
+ for (const e of entities) yield [e, transforms.get(e)!, drifts.get(e)!];
+ },
+ }, time);
+ }
+ for (const e of entities) {
+ const want = transforms.get(e)!['position'] as Record<string, number>;
+ expect(mem.read('Transform', e, 'position.x'), `entity ${e}`).toBe(want['x']);
+ expect(mem.read('Transform', e, 'position.y'), `entity ${e}`).toBe(want['y']);
+ }
+ });
+
+ it('the object file has nothing to import but the memory it lives in', () => {
+ const layout = packLayout(shipped.module.comps);
+ const cModule = emitC(shipped.module, layout, [systemOf(shipped, 'MoveSystem')]);
+ const dir = join(tmp, 'imports');
+ mkdirSync(dir, { recursive: true });
+ writeFileSync(join(dir, 'estella_abi.h'), cModule.header);
+ writeFileSync(join(dir, 'systems.c'), cModule.source);
+ const obj = join(dir, 'systems.o');
+ const out = spawnSync(CC!, [...CFLAGS, '-Wall', '-Wextra', '-c',
+ join(dir, 'systems.c'), '-o', obj], { encoding: 'utf8' });
+ expect(out.status, out.stderr).toBe(0);
+ expect(out.stderr.trim()).toBe('');
+
+ // §6.5 is about the wasm import section; natively the same property is
+ // "no undefined symbol". `es_memory` is the linear memory itself, which
+ // on wasm is not an import at all — it IS the module's memory.
+ const nm = spawnSync('nm', [obj], { encoding: 'utf8' });
+ if (nm.status !== 0) {
+ console.warn('[codegen] nm unavailable — the undefined-symbol check did NOT run.');
+ return;
+ }
+ const undef = nm.stdout.split(/\r?\n/)
+ .filter((l) => /\s[Uu]\s/.test(l))
+ .map((l) => l.trim().split(/\s+/).pop()!)
+ .filter((s) => s !== 'es_memory');
+ expect(undef, 'a compiled system may not call the engine').toEqual([]);
+ });
+
+ it('the handshake constant moves when the parameter order does', () => {
+ const layout = packLayout(shipped.module.comps);
+ const move = systemOf(shipped, 'MoveSystem');
+ const a = emitC(shipped.module, layout, [move]);
+ expect(a.source).toContain(`0x${a.hash}ULL`);
+
+ // The same system with its parameters swapped reads the ctx tables in
+ // the other order, so the loader has to refuse it. §2.5.
+ const swapped: EirSystem = { ...move, params: [...move.params].reverse() };
+ expect(emitC(shipped.module, layout, [swapped]).hash).not.toBe(a.hash);
+ });
+
+ it('a component field is one load at a constant offset', () => {
+ const layout = packLayout(shipped.module.comps);
+ const { source } = emitC(shipped.module, layout, [systemOf(shipped, 'MoveSystem')]);
+ // §4.2's whole reason for existing, readable in the output itself.
+ expect(source).toMatch(/es_f32\(\w+ \+ ES_OFF_Transform_position_x\)/);
+ expect(source).toMatch(/#define ES_OFF_Transform_position_x \d+u/);
+ // And the thing v0 had that v1 does not: a call back across the boundary.
+ expect(source).not.toMatch(/\bes_abi_\w+\(/);
+ });
+});
diff --git a/compiler/tests/conformance.test.ts b/compiler/tests/conformance.test.ts
index 86dc6b91d..3215b777f 100644
--- a/compiler/tests/conformance.test.ts
+++ b/compiler/tests/conformance.test.ts
@@ -22,7 +22,8 @@ import { inlineSystem } from '../src/inline';
import { builtinShapes } from '../src/builtins';
import { printSystem } from '../src/eir';
-import { driftSystem, clampSystem, tunedSystem, helperSystem } from './fixtures/in-subset';
+import { driftSystem, clampSystem, tunedSystem, helperSystem, mathSystem } from './fixtures/in-subset';
+import { PROBE, probeRow } from './probe';
import type { StubSystem } from './stubs/esengine';
const FIXTURE = resolve(fileURLToPath(new URL('./fixtures/in-subset.ts', import.meta.url)));
@@ -296,3 +297,61 @@ describe('conformance — pure helpers, called and inlined', () => {
expect(byInlined.comps.get('Transform')).toEqual(byNode.comps.get('Transform'));
});
});
+
+const math = module.systems.find((s) => s.name === 'FixtureMathOps');
+
+describe('conformance — the Math the subset admits', () => {
+ function probeWorld(): EirWorld {
+ const rows = new Map<number, Row>();
+ const entities: number[] = [];
+ PROBE.forEach((v, i) => {
+ entities.push(i + 1);
+ // defineComponent shapes are host-stored, so f64: no fround, and -0
+ // stays -0 all the way into the image.
+ rows.set(i + 1, probeRow(v));
+ });
+ return { entities, comps: new Map([['FixtureMathProbe', rows]]), resources: new Map() };
+ }
+
+ it('compiles, and lowers each operation to a call rather than a fallback', () => {
+ expect(diagnostics.filter((d) => d.system === 'FixtureMathOps')).toEqual([]);
+ expect(math).toBeDefined();
+ expect(verifySystem(math!, module.comps, module.fns)).toEqual([]);
+ });
+
+ it('agrees with node, including the sign of zero', () => {
+ const byNode = probeWorld();
+ const byEir = probeWorld();
+ const sys = mathSystem as unknown as StubSystem;
+ const rows = byNode.comps.get('FixtureMathProbe')!;
+ (sys.fn as unknown as (q: unknown) => void)({
+ *[Symbol.iterator]() {
+ for (const e of byNode.entities) yield [e, rows.get(e)!];
+ },
+ });
+ runSystem(math!, byEir);
+
+ for (const e of byNode.entities) {
+ const want = rows.get(e) as Record<string, number>;
+ const got = byEir.comps.get('FixtureMathProbe')!.get(e) as Record<string, number>;
+ for (const k of Object.keys(want)) {
+ // Object.is, not toBe on the number: -0 and +0 are equal and are
+ // not the same bytes, and the bytes are what ships.
+ expect(Object.is(got[k], want[k]), `entity ${e} field ${k}: ${got[k]} vs ${want[k]}`).toBe(true);
+ }
+ }
+ });
+
+ it('the probe actually reaches the cases the shims exist for', () => {
+ const w = probeWorld();
+ runSystem(math!, w);
+ const rows = [...w.comps.get('FixtureMathProbe')!.values()] as Record<string, number>[];
+ // A tie that rounds toward +Inf rather than away from zero.
+ expect(rows.some((r) => r['v'] === -2.5 && r['rounded'] === -2)).toBe(true);
+ // The double just below 0.5, where floor(x + 0.5) gives the wrong answer.
+ expect(rows.some((r) => r['v'] === 0.49999999999999994 && Object.is(r['rounded'], 0))).toBe(true);
+ // min picking the negative zero, which fmin is free not to do.
+ expect(rows.some((r) => Object.is(r['lo'], -0))).toBe(true);
+ expect(rows.some((r) => Object.is(r['signum'], -0))).toBe(true);
+ });
+});
diff --git a/compiler/tests/fixtures/in-subset.ts b/compiler/tests/fixtures/in-subset.ts
index 5b507bcf0..cb11f24e7 100644
--- a/compiler/tests/fixtures/in-subset.ts
+++ b/compiler/tests/fixtures/in-subset.ts
@@ -91,3 +91,28 @@ export const helperSystem = defineSystem(
},
{ name: 'FixtureHelpers' },
);
+
+// Every exactly-specified Math operation, on the arguments where the C library
+// and ECMAScript actually disagree: ties, and the sign of zero. Nothing else in
+// the corpus reaches them, and a shim nothing samples is a shim nobody checked.
+export const MathProbe = defineComponent('FixtureMathProbe', {
+ v: 0, rounded: 0, truncated: 0, ceiled: 0, floored: 0, signum: 0, lo: 0, hi: 0,
+});
+
+export const mathSystem = defineSystem(
+ [Query(Mut(MathProbe))],
+ (query) => {
+ for (const [, p] of query) {
+ p.rounded = Math.round(p.v);
+ p.truncated = Math.trunc(p.v);
+ p.ceiled = Math.ceil(p.v);
+ p.floored = Math.floor(p.v);
+ p.signum = Math.sign(p.v);
+ // min/max of a value and its negation: the only way to reach the
+ // -0 / +0 rule, which fmin and fmax do not follow.
+ p.lo = Math.min(p.v, -p.v);
+ p.hi = Math.max(p.v, -p.v);
+ }
+ },
+ { name: 'FixtureMathOps' },
+);
diff --git a/compiler/tests/probe.ts b/compiler/tests/probe.ts
new file mode 100644
index 000000000..7662d9c87
--- /dev/null
+++ b/compiler/tests/probe.ts
@@ -0,0 +1,22 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file probe.ts
+ * @brief The arguments where libm and ECMAScript disagree about Math.
+ *
+ * @details Ties, and the sign of zero, plus ordinary values so the shims are not
+ * only exercised at their edges. Shared because two differentials use
+ * it and they have to use the SAME one: conformance.test.ts settles
+ * what the right answer is (node against the interpreter), and
+ * codegen.test.ts settles that a real C compiler produces it.
+ */
+export const PROBE: readonly number[] = [
+ -2.5, 2.5, -0.5, 0.5, 0.49999999999999994, -0.49999999999999994,
+ -0.2, 0.2, 0, -0, 1.5, -1.5, 3.5, -3.5, -1, 1,
+ 100.5, -100.5, 1e-7, -1e-7, 7, -7, 2.675, -2.675,
+];
+
+/** A probe row as both worlds hold it; every output starts at zero. */
+export function probeRow(v: number): Record<string, number> {
+ return { v, rounded: 0, truncated: 0, ceiled: 0, floored: 0, signum: 0, lo: 0, hi: 0 };
+}
diff --git a/tools/gates.mjs b/tools/gates.mjs
index 984d6024c..882f80c64 100644
--- a/tools/gates.mjs
+++ b/tools/gates.mjs
@@ -79,6 +79,9 @@ export const GATES = [
{ id: 'engine-tests', run: 'pnpm run test' },
// The AOT compiler carries its own oracle: a real example system lowered to
// EIR must move a world exactly the way node moves it (docs/REARCH_AOT.md §8.1).
+ // It also compiles the emitted C and requires the same bytes back. That half
+ // needs clang or gcc on PATH; without one the suite still passes and PRINTS
+ // that the differential did not run, so read the log before believing it.
{ id: 'compiler-tests', run: 'pnpm --filter @estella/compiler test' },
// The plugins we ship prove the public API only if they are held to it.
{ id: 'plugin-boundary', run: 'node tools/check-plugin-boundary.mjs' },