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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
feat(compiler): EIR becomes C, and the same bytes come back
yhhed1dbce7ab24
diff --git a/compiler/src/abi.ts b/compiler/src/abi.tsindex 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 thediff --git a/compiler/src/builtins.ts b/compiler/src/builtins.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.mjsindex 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' },