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): a shipped system is lowered to EIR and moves a world like node

yhh96cccdfe0862
diff --git a/compiler/package.json b/compiler/package.json
new file mode 100644
index 000000000..e12b86ded
--- /dev/null
+++ b/compiler/package.json
@@ -0,0 +1,17 @@
+{
+ "name": "@estella/compiler",
+ "version": "0.0.0",
+ "private": true,
+ "type": "module",
+ "description": "Estella AOT — TypeScript to Estella IR (docs/REARCH_AOT.md)",
+ "main": "src/index.ts",
+ "scripts": {
+ "test": "vitest run",
+ "typecheck": "tsc --noEmit -p tsconfig.json"
+ },
+ "devDependencies": {
+ "@types/node": "^22.0.0",
+ "typescript": "^5.6.0",
+ "vitest": "^2.1.9"
+ }
+}
diff --git a/compiler/src/builtins.ts b/compiler/src/builtins.ts
new file mode 100644
index 000000000..ad5ef6210
--- /dev/null
+++ b/compiler/src/builtins.ts
@@ -0,0 +1,67 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file builtins.ts
+ * @brief Engine component shapes, from EHT's table rather than a second copy.
+ *
+ * @details PTR_LAYOUTS is generated from the C++ structs and is what the SDK's
+ * accessors and the ABI hash already agree on. The compiler consumes it
+ * for the same reason: a component's fields must have exactly one
+ * author (docs/REARCH_AOT.md §1.2).
+ *
+ * Resources have no such table yet — `Time` is spelled out below and
+ * marked, because a shape with no generator is exactly the drift this
+ * file exists to avoid.
+ */
+import { PTR_LAYOUTS } from '../../sdk/src/wasm/ptrLayouts.generated';
+import { BOOL, F64, type CompShape, type EirType } from './eir';
+
+/** Leaf member names per composite field, in memory order. */
+const MEMBERS: Record<string, readonly string[]> = {
+ vec2: ['x', 'y'],
+ vec3: ['x', 'y', 'z'],
+ vec4: ['x', 'y', 'z', 'w'],
+ quat: ['x', 'y', 'z', 'w'],
+ color: ['r', 'g', 'b', 'a'],
+};
+
+function leafType(t: string): EirType {
+ return t === 'bool' ? BOOL : F64;
+}
+
+/**
+ * Every engine component EHT emits a layout for, flattened to leaf paths.
+ * `Transform` becomes `position.x`, `position.y`, … so a place's path is the
+ * key, which is what lets a later pass fold it to a constant offset.
+ */
+export function builtinShapes(): Map<string, CompShape> {
+ const out = new Map<string, CompShape>();
+ for (const [name, layout] of Object.entries(PTR_LAYOUTS)) {
+ const fields = new Map<string, EirType>();
+ for (const f of layout.fields) {
+ const members = MEMBERS[f.type];
+ if (members) {
+ for (const m of members) fields.set(`${f.name}.${m}`, F64);
+ } else if (f.type === 'struct') {
+ for (const m of f.members ?? []) fields.set(`${f.name}.${m.name}`, leafType(m.type));
+ } else {
+ fields.set(f.name, leafType(f.type));
+ }
+ }
+ out.set(name, { name, fields });
+ }
+ out.set('Time', TIME);
+ return out;
+}
+
+// NOT generated. Resources have no EHT table, so this is a hand-written shape and
+// will drift the moment Time gains a field. Generating it is owed before the
+// compiler reads any resource beyond this one.
+const TIME: CompShape = {
+ name: 'Time',
+ fields: new Map<string, EirType>([
+ ['delta', F64], ['elapsed', F64], ['frameCount', F64],
+ ['fixedDelta', F64], ['fixedAlpha', F64], ['fixedTick', F64],
+ ['scale', F64], ['unscaledDelta', F64],
+ ]),
+};
diff --git a/compiler/src/eir.ts b/compiler/src/eir.ts
new file mode 100644
index 000000000..afb6614b5
--- /dev/null
+++ b/compiler/src/eir.ts
@@ -0,0 +1,154 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file eir.ts
+ * @brief Estella IR, high level — typed, and ECS-aware (docs/REARCH_AOT.md §4).
+ *
+ * @details The reason this layer exists rather than lowering the TS AST straight
+ * to LLVM: by LLVM IR a query is an opaque call, and the optimisations
+ * that pay — copy-in/copy-out elimination, archetype specialisation,
+ * query fusion, change-detection sinking — need to see that a system
+ * walks rows of components. Once that is gone it cannot be recovered.
+ *
+ * So `RowLoop` is a first-class statement here and `CompField` a
+ * first-class place, instead of both being calls.
+ *
+ * Statement tree, not a CFG. The doc puts SSA and explicit memory at
+ * EIR-low; making this one a CFG too would buy nothing a Stage 1
+ * interpreter can use, and the split is where RC insertion and
+ * bounds-check elimination will live.
+ */
+
+/** Every value in EIR carries one of these; there is no `any` to fall back to. */
+export type EirType =
+ | { readonly k: 'f64' }
+ | { readonly k: 'bool' }
+ | { readonly k: 'entity' }
+ /** A component row — its fields come from the component's declared shape. */
+ | { readonly k: 'comp'; readonly name: string }
+ /** A resource, addressed by field like a component. */
+ | { readonly k: 'res'; readonly name: string }
+ | { readonly k: 'query'; readonly args: readonly QueryArg[] };
+
+export const F64: EirType = { k: 'f64' };
+export const BOOL: EirType = { k: 'bool' };
+export const ENTITY: EirType = { k: 'entity' };
+
+/** One component a query asks for, and whether the system may write it. */
+export interface QueryArg {
+ readonly comp: string;
+ readonly mut: boolean;
+}
+
+export type BinOp = '+' | '-' | '*' | '/' | '%' | '<' | '<=' | '>' | '>=' | '==' | '!=';
+
+/**
+ * A place a value can be read from or written to. `Field` addresses a component
+ * or resource by a path of names — `position.x` — which is what lets a later
+ * pass turn it into one load at a constant offset.
+ */
+export type Place =
+ | { readonly p: 'local'; readonly id: number }
+ | { readonly p: 'field'; readonly base: Place; readonly path: readonly string[] };
+
+export type Expr =
+ | { readonly e: 'const'; readonly value: number | boolean; readonly type: EirType }
+ | { readonly e: 'read'; readonly place: Place; readonly type: EirType }
+ | { readonly e: 'bin'; readonly op: BinOp; readonly l: Expr; readonly r: Expr; readonly type: EirType }
+ | { readonly e: 'neg'; readonly v: Expr; readonly type: EirType };
+
+export type Stmt =
+ /**
+ * Walk every row the query matches, binding the entity and one local per
+ * component. The op that must survive to EIR-low as a strided walk.
+ */
+ | {
+ readonly s: 'rowLoop';
+ readonly query: Place;
+ readonly entity: number | null;
+ readonly binds: readonly number[];
+ readonly body: readonly Stmt[];
+ }
+ | { readonly s: 'assign'; readonly target: Place; readonly value: Expr }
+ | { readonly s: 'let'; readonly id: number; readonly value: Expr };
+
+/** A local's name and type; the name is for diagnostics and printing only. */
+export interface Local {
+ readonly id: number;
+ readonly name: string;
+ readonly type: EirType;
+}
+
+export interface EirSystem {
+ readonly name: string;
+ /** Locals bound to the system's declared parameters, in declaration order. */
+ readonly params: readonly Local[];
+ readonly locals: readonly Local[];
+ readonly body: readonly Stmt[];
+}
+
+/** A component's field shape, flattened to leaf paths of one scalar each. */
+export interface CompShape {
+ readonly name: string;
+ /** `position.x` -> f64. Order is the declaration order EHT would give. */
+ readonly fields: ReadonlyMap<string, EirType>;
+}
+
+export interface EirModule {
+ readonly systems: readonly EirSystem[];
+ readonly comps: ReadonlyMap<string, CompShape>;
+}
+
+// =============================================================================
+// printing — an EIR dump is the first thing anyone debugging this will read
+// =============================================================================
+
+export function typeName(t: EirType): string {
+ switch (t.k) {
+ case 'comp': return `comp<${t.name}>`;
+ case 'res': return `res<${t.name}>`;
+ case 'query': return `query<${t.args.map((a) => (a.mut ? `mut ${a.comp}` : a.comp)).join(', ')}>`;
+ default: return t.k;
+ }
+}
+
+function placeName(p: Place, locals: ReadonlyMap<number, Local>): string {
+ if (p.p === 'local') return locals.get(p.id)?.name ?? `%${p.id}`;
+ return `${placeName(p.base, locals)}.${p.path.join('.')}`;
+}
+
+function exprText(e: Expr, locals: ReadonlyMap<number, Local>): string {
+ switch (e.e) {
+ case 'const': return String(e.value);
+ case 'read': return placeName(e.place, locals);
+ case 'bin': return `(${exprText(e.l, locals)} ${e.op} ${exprText(e.r, locals)})`;
+ case 'neg': return `-${exprText(e.v, locals)}`;
+ }
+}
+
+function stmtText(s: Stmt, locals: ReadonlyMap<number, Local>, indent: string): string[] {
+ switch (s.s) {
+ case 'rowLoop': {
+ const names = s.binds.map((b) => locals.get(b)?.name ?? `%${b}`);
+ const ent = s.entity === null ? '_' : (locals.get(s.entity)?.name ?? `%${s.entity}`);
+ const head = `${indent}rowLoop ${placeName(s.query, locals)} -> (${ent}, ${names.join(', ')}) {`;
+ const body = s.body.flatMap((b) => stmtText(b, locals, `${indent} `));
+ return [head, ...body, `${indent}}`];
+ }
+ case 'assign':
+ return [`${indent}${placeName(s.target, locals)} = ${exprText(s.value, locals)}`];
+ case 'let':
+ return [`${indent}let ${locals.get(s.id)?.name ?? `%${s.id}`} = ${exprText(s.value, locals)}`];
+ }
+}
+
+export function printSystem(sys: EirSystem): string {
+ const byId = new Map<number, Local>();
+ for (const l of [...sys.params, ...sys.locals]) byId.set(l.id, l);
+ const params = sys.params.map((p) => `${p.name}: ${typeName(p.type)}`).join(', ');
+ return [
+ `system ${sys.name}(${params}) {`,
+ ...sys.body.flatMap((s) => stmtText(s, byId, ' ')),
+ '}',
+ ].join('\n');
+}
diff --git a/compiler/src/frontend.ts b/compiler/src/frontend.ts
new file mode 100644
index 000000000..d84a26bf9
--- /dev/null
+++ b/compiler/src/frontend.ts
@@ -0,0 +1,407 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file frontend.ts
+ * @brief TypeScript AST -> EIR-high (docs/REARCH_AOT.md §4.1, §3.3).
+ *
+ * @details Uses the real `typescript` program and checker. Re-implementing TS
+ * inference is the one decision that would sink this project.
+ *
+ * The SDK entry points are INTRINSICS, not calls: `defineSystem`,
+ * `Query`, `Mut`, `Res`, `defineComponent`. `defineComponent('Mover',
+ * {...})` is runtime reflection, and AOT needs it to be a compile-time
+ * declaration — so both arguments must be literals or the file falls
+ * back to the interpreter.
+ *
+ * Nothing here throws on code it cannot handle. Anything outside the
+ * subset produces a Diagnostic naming the line and the reason, and its
+ * system is simply not compiled — §3.2's no-cliff rule, which is what
+ * lets this ship before it is finished.
+ */
+import { sep } from 'node:path';
+import ts from 'typescript';
+import {
+ BOOL, ENTITY, F64,
+ type CompShape, type EirModule, type EirSystem, type EirType,
+ type Expr, type Local, type Place, type QueryArg, type Stmt, type BinOp,
+} from './eir';
+
+export interface Diagnostic {
+ readonly file: string;
+ readonly line: number;
+ readonly message: string;
+ /** The system this killed, when the failure happened inside one. */
+ readonly system?: string;
+}
+
+export interface LowerResult {
+ readonly module: EirModule;
+ readonly diagnostics: readonly Diagnostic[];
+ /** Systems seen, whether or not they compiled — the coverage gate's denominator. */
+ readonly seen: readonly string[];
+}
+
+const BIN_OPS: ReadonlyMap<ts.SyntaxKind, BinOp> = new Map([
+ [ts.SyntaxKind.PlusToken, '+'], [ts.SyntaxKind.MinusToken, '-'],
+ [ts.SyntaxKind.AsteriskToken, '*'], [ts.SyntaxKind.SlashToken, '/'],
+ [ts.SyntaxKind.PercentToken, '%'],
+ [ts.SyntaxKind.LessThanToken, '<'], [ts.SyntaxKind.LessThanEqualsToken, '<='],
+ [ts.SyntaxKind.GreaterThanToken, '>'], [ts.SyntaxKind.GreaterThanEqualsToken, '>='],
+ [ts.SyntaxKind.EqualsEqualsEqualsToken, '=='], [ts.SyntaxKind.ExclamationEqualsEqualsToken, '!='],
+] as const);
+
+const COMPOUND: ReadonlyMap<ts.SyntaxKind, BinOp> = new Map([
+ [ts.SyntaxKind.PlusEqualsToken, '+'], [ts.SyntaxKind.MinusEqualsToken, '-'],
+ [ts.SyntaxKind.AsteriskEqualsToken, '*'], [ts.SyntaxKind.SlashEqualsToken, '/'],
+] as const);
+
+/** Thrown internally to abandon one system; never escapes lowerProgram. */
+class NotInSubset extends Error {
+ constructor(readonly node: ts.Node, message: string) { super(message); }
+}
+
+class SystemLowerer {
+ private readonly locals: Local[] = [];
+ private next = 0;
+ private readonly scope = new Map<string, Local>();
+
+ constructor(
+ private readonly comps: Map<string, CompShape>,
+ /** `const Speed = defineComponent('FixtureSpeed', …)` — a query names the
+ * BINDING, and the shape is filed under the declared name. */
+ private readonly bindings: ReadonlyMap<string, string>,
+ ) {}
+
+ private compName(binding: string): string {
+ return this.bindings.get(binding) ?? binding;
+ }
+
+ private define(name: string, type: EirType): Local {
+ const l: Local = { id: this.next++, name, type };
+ this.locals.push(l);
+ this.scope.set(name, l);
+ return l;
+ }
+
+ private lookup(node: ts.Node, name: string): Local {
+ const l = this.scope.get(name);
+ if (!l) throw new NotInSubset(node, `'${name}' is not a value this system declared`);
+ return l;
+ }
+
+ /** `[Query(Mut(Transform), Mover), Res(Time)]` -> one param type each. */
+ private paramTypes(node: ts.Expression): EirType[] {
+ if (!ts.isArrayLiteralExpression(node)) {
+ throw new NotInSubset(node, "defineSystem's parameter list must be an array literal");
+ }
+ return node.elements.map((el) => {
+ if (!ts.isCallExpression(el) || !ts.isIdentifier(el.expression)) {
+ throw new NotInSubset(el, 'each parameter must be Query(...) or Res(...)');
+ }
+ const kind = el.expression.text;
+ if (kind === 'Res') {
+ const arg = el.arguments[0];
+ if (!arg || !ts.isIdentifier(arg)) throw new NotInSubset(el, 'Res(...) needs a named resource');
+ return { k: 'res', name: this.compName(arg.text) } as EirType;
+ }
+ if (kind !== 'Query') throw new NotInSubset(el, `'${kind}' is not a parameter intrinsic`);
+ const args: QueryArg[] = el.arguments.map((a) => this.queryArg(a));
+ return { k: 'query', args } as EirType;
+ });
+ }
+
+ private queryArg(node: ts.Expression): QueryArg {
+ if (ts.isCallExpression(node) && ts.isIdentifier(node.expression)) {
+ if (node.expression.text !== 'Mut') {
+ throw new NotInSubset(node, `'${node.expression.text}(...)' is not a query argument this subset lowers`);
+ }
+ const inner = node.arguments[0];
+ if (!inner || !ts.isIdentifier(inner)) throw new NotInSubset(node, 'Mut(...) needs a named component');
+ return { comp: this.compName(inner.text), mut: true };
+ }
+ if (!ts.isIdentifier(node)) throw new NotInSubset(node, 'a query argument must be a named component');
+ return { comp: this.compName(node.text), mut: false };
+ }
+
+ lower(name: string, params: ts.Expression, fn: ts.ArrowFunction): EirSystem {
+ const types = this.paramTypes(params);
+ if (fn.parameters.length !== types.length) {
+ throw new NotInSubset(fn, `the callback takes ${fn.parameters.length} parameters but ${types.length} were declared`);
+ }
+ const bound: Local[] = fn.parameters.map((p, i) => {
+ if (!ts.isIdentifier(p.name)) throw new NotInSubset(p, 'a system parameter must be a plain name');
+ return this.define(p.name.text, types[i]!);
+ });
+ const body = ts.isBlock(fn.body)
+ ? fn.body.statements.flatMap((s) => this.stmt(s))
+ : (() => { throw new NotInSubset(fn, 'the callback must have a block body'); })();
+ const paramIds = new Set(bound.map((b) => b.id));
+ return {
+ name,
+ params: bound,
+ locals: this.locals.filter((l) => !paramIds.has(l.id)),
+ body,
+ };
+ }
+
+ private stmt(node: ts.Statement): Stmt[] {
+ if (ts.isForOfStatement(node)) return [this.rowLoop(node)];
+ if (ts.isExpressionStatement(node)) return [this.assignment(node.expression)];
+ if (ts.isBlock(node)) return node.statements.flatMap((s) => this.stmt(s));
+ throw new NotInSubset(node, `${ts.SyntaxKind[node.kind]} is not a statement this subset lowers`);
+ }
+
+ /** `for (const [e, a, b] of query) { ... }` — the shape a system iterates rows in. */
+ private rowLoop(node: ts.ForOfStatement): Stmt {
+ if (!ts.isIdentifier(node.expression)) {
+ throw new NotInSubset(node.expression, 'a row loop must iterate a declared query');
+ }
+ const q = this.lookup(node.expression, node.expression.text);
+ const qt = q.type;
+ if (qt.k !== 'query') throw new NotInSubset(node.expression, `'${q.name}' is not a query`);
+
+ const decl = ts.isVariableDeclarationList(node.initializer) ? node.initializer.declarations[0] : undefined;
+ if (!decl || !decl.name || !ts.isArrayBindingPattern(decl.name)) {
+ throw new NotInSubset(node, 'a row loop must destructure [entity, ...components]');
+ }
+ const elements = decl.name.elements;
+ if (elements.length !== qt.args.length + 1) {
+ throw new NotInSubset(node, `the row binds ${elements.length} names but the query yields ${qt.args.length + 1}`);
+ }
+
+ let entity: number | null = null;
+ const binds: number[] = [];
+ elements.forEach((el, i) => {
+ if (!ts.isBindingElement(el) || !ts.isIdentifier(el.name)) {
+ throw new NotInSubset(el, 'a row binding must be a plain name');
+ }
+ const nm = el.name.text;
+ if (i === 0) {
+ const l = this.define(nm, ENTITY);
+ // A row's entity is bound whether or not the body reads it; the
+ // leading underscore convention only says the author expects not to.
+ entity = l.id;
+ return;
+ }
+ const arg = qt.args[i - 1]!;
+ binds.push(this.define(nm, { k: 'comp', name: arg.comp }).id);
+ });
+
+ const body = ts.isBlock(node.statement)
+ ? node.statement.statements.flatMap((s) => this.stmt(s))
+ : this.stmt(node.statement);
+ return { s: 'rowLoop', query: { p: 'local', id: q.id }, entity, binds, body };
+ }
+
+ private assignment(node: ts.Expression): Stmt {
+ if (!ts.isBinaryExpression(node)) {
+ throw new NotInSubset(node, 'only assignments are statements in this subset');
+ }
+ const compound = COMPOUND.get(node.operatorToken.kind);
+ const target = this.place(node.left);
+ if (compound) {
+ const type = this.placeType(node.left);
+ const read: Expr = { e: 'read', place: target, type };
+ const r = this.expr(node.right);
+ return { s: 'assign', target, value: { e: 'bin', op: compound, l: read, r, type } };
+ }
+ if (node.operatorToken.kind !== ts.SyntaxKind.EqualsToken) {
+ throw new NotInSubset(node, `'${node.operatorToken.getText()}' is not an assignment this subset lowers`);
+ }
+ return { s: 'assign', target, value: this.expr(node.right) };
+ }
+
+ /** A place is a local, or a dotted path from one. Nothing else is addressable. */
+ private place(node: ts.Expression): Place {
+ if (ts.isIdentifier(node)) return { p: 'local', id: this.lookup(node, node.text).id };
+ if (!ts.isPropertyAccessExpression(node)) {
+ throw new NotInSubset(node, 'only a name or a dotted path can be read or assigned here');
+ }
+ const path: string[] = [];
+ let cur: ts.Expression = node;
+ while (ts.isPropertyAccessExpression(cur)) {
+ path.unshift(cur.name.text);
+ cur = cur.expression;
+ }
+ if (!ts.isIdentifier(cur)) throw new NotInSubset(node, 'a dotted path must start at a declared name');
+ return { p: 'field', base: { p: 'local', id: this.lookup(cur, cur.text).id }, path };
+ }
+
+ /**
+ * The type a place reads as. A component or resource field must exist in the
+ * declared shape — this is where a typo stops being a runtime undefined.
+ */
+ private placeType(node: ts.Expression): EirType {
+ const place = this.place(node);
+ if (place.p === 'local') {
+ return this.locals.find((l) => l.id === place.id)!.type;
+ }
+ const base = this.locals.find((l) => l.id === (place.base as { p: 'local'; id: number }).id)!;
+ const key = place.path.join('.');
+ if (base.type.k === 'comp') {
+ const shape = this.comps.get(base.type.name);
+ if (!shape) throw new NotInSubset(node, `no declared shape for component '${base.type.name}'`);
+ const t = shape.fields.get(key);
+ if (!t) throw new NotInSubset(node, `'${base.type.name}' has no field '${key}'`);
+ return t;
+ }
+ if (base.type.k === 'res') {
+ const shape = this.comps.get(base.type.name);
+ const t = shape?.fields.get(key);
+ if (!t) throw new NotInSubset(node, `resource '${base.type.name}' has no field '${key}'`);
+ return t;
+ }
+ throw new NotInSubset(node, `'${base.name}' has no fields to read`);
+ }
+
+ private expr(node: ts.Expression): Expr {
+ if (ts.isParenthesizedExpression(node)) return this.expr(node.expression);
+ if (ts.isNumericLiteral(node)) return { e: 'const', value: Number(node.text), type: F64 };
+ if (node.kind === ts.SyntaxKind.TrueKeyword) return { e: 'const', value: true, type: BOOL };
+ if (node.kind === ts.SyntaxKind.FalseKeyword) return { e: 'const', value: false, type: BOOL };
+ if (ts.isPrefixUnaryExpression(node) && node.operator === ts.SyntaxKind.MinusToken) {
+ const v = this.expr(node.operand);
+ return { e: 'neg', v, type: v.type };
+ }
+ if (ts.isBinaryExpression(node)) {
+ const op = BIN_OPS.get(node.operatorToken.kind);
+ if (!op) throw new NotInSubset(node, `operator '${node.operatorToken.getText()}' is not in this subset`);
+ const l = this.expr(node.left);
+ const r = this.expr(node.right);
+ const type = op === '<' || op === '<=' || op === '>' || op === '>=' || op === '==' || op === '!='
+ ? BOOL : F64;
+ return { e: 'bin', op, l, r, type };
+ }
+ if (ts.isIdentifier(node) || ts.isPropertyAccessExpression(node)) {
+ return { e: 'read', place: this.place(node), type: this.placeType(node) };
+ }
+ throw new NotInSubset(node, `${ts.SyntaxKind[node.kind]} is not an expression this subset lowers`);
+ }
+}
+
+/** `defineComponent('Mover', { speed: 100 })` -> a shape, or null if not literal. */
+function componentShape(call: ts.CallExpression): CompShape | null {
+ const [nameArg, defaults] = call.arguments;
+ if (!nameArg || !ts.isStringLiteral(nameArg)) return null;
+ if (!defaults || !ts.isObjectLiteralExpression(defaults)) return null;
+ const fields = new Map<string, EirType>();
+ for (const prop of defaults.properties) {
+ if (!ts.isPropertyAssignment(prop) || !ts.isIdentifier(prop.name)) return null;
+ const init = prop.initializer;
+ if (ts.isNumericLiteral(init)) fields.set(prop.name.text, F64);
+ else if (init.kind === ts.SyntaxKind.TrueKeyword || init.kind === ts.SyntaxKind.FalseKeyword) {
+ fields.set(prop.name.text, BOOL);
+ } else return null;
+ }
+ return { name: nameArg.text, fields };
+}
+
+function normalizePath(p: string): string {
+ return p.split(sep).join('/').toLowerCase();
+}
+
+/**
+ * The source file is passed in rather than taken from the node: `getSourceFile()`
+ * walks parent pointers, which only exist once the program has bound — a side
+ * effect of calling getTypeChecker(), and not something to depend on.
+ */
+function lineOf(sf: ts.SourceFile, node: ts.Node): number {
+ return sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1;
+}
+
+/**
+ * Lower every `defineSystem` in `files`. Builtin component and resource shapes
+ * come in from the caller — EHT is their authority, and inventing a second copy
+ * here is exactly the drift the ABI hash exists to prevent.
+ */
+export function lowerProgram(files: readonly string[], builtins: ReadonlyMap<string, CompShape>): LowerResult {
+ const program = ts.createProgram([...files], {
+ target: ts.ScriptTarget.ES2022, module: ts.ModuleKind.ESNext,
+ strict: true, noEmit: true, skipLibCheck: true, allowJs: false,
+ });
+ const comps = new Map<string, CompShape>(builtins);
+ // A component's declared name and the const it is bound to are two different
+ // things; move.ts happens to use one word for both, which is why this was
+ // missing until a fixture used two.
+ const bindings = new Map<string, string>();
+ const systems: EirSystem[] = [];
+ const diagnostics: Diagnostic[] = [];
+ const seen: string[] = [];
+
+ // ts normalises fileName to forward slashes; a caller on Windows will not
+ // have. Comparing them raw lowers nothing and reports no error at all.
+ const wanted = new Set(files.map(normalizePath));
+ const sources = program.getSourceFiles()
+ .filter((sf) => wanted.has(normalizePath(sf.fileName)) && !sf.isDeclarationFile);
+
+ // Both scans carry the enclosing `const` name down instead of reading
+ // node.parent: parent pointers exist only once the program has bound, which
+ // is a side effect of getTypeChecker() and not a thing to depend on.
+ type Visit = (node: ts.Node, binding: string | null) => void;
+ const walkTop = (sf: ts.SourceFile, visit: Visit): void => {
+ const go = (node: ts.Node, binding: string | null): void => {
+ visit(node, binding);
+ if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer) {
+ go(node.initializer, node.name.text);
+ return;
+ }
+ ts.forEachChild(node, (c) => go(c, null));
+ };
+ ts.forEachChild(sf, (c) => go(c, null));
+ };
+
+ // Components first: a system in one file names a component declared in another.
+ for (const sf of sources) {
+ walkTop(sf, (node, binding) => {
+ if (!ts.isCallExpression(node) || !ts.isIdentifier(node.expression)) return;
+ if (node.expression.text !== 'defineComponent') return;
+ const shape = componentShape(node);
+ if (!shape) {
+ diagnostics.push({
+ file: sf.fileName, line: lineOf(sf, node),
+ message: 'defineComponent needs a string literal name and an object literal of literal defaults',
+ });
+ return;
+ }
+ comps.set(shape.name, shape);
+ if (binding) bindings.set(binding, shape.name);
+ });
+ }
+
+ for (const sf of sources) {
+ walkTop(sf, (node, binding) => {
+ if (!ts.isCallExpression(node) || !ts.isIdentifier(node.expression)) return;
+ if (node.expression.text !== 'defineSystem') return;
+ const name = systemName(node, binding);
+ seen.push(name);
+ try {
+ const [params, fn] = node.arguments;
+ if (!params || !fn || !ts.isArrowFunction(fn)) {
+ throw new NotInSubset(node, 'defineSystem takes a parameter array and an arrow function');
+ }
+ systems.push(new SystemLowerer(comps, bindings).lower(name, params, fn));
+ } catch (e) {
+ if (!(e instanceof NotInSubset)) throw e;
+ diagnostics.push({
+ file: sf.fileName, line: lineOf(sf, e.node), message: e.message, system: name,
+ });
+ }
+ });
+ }
+
+ return { module: { systems, comps }, diagnostics, seen };
+}
+
+/** `{ name: 'MoveSystem' }` if given, else the const it is assigned to. */
+function systemName(call: ts.CallExpression, binding: string | null): string {
+ const opts = call.arguments[2];
+ if (opts && ts.isObjectLiteralExpression(opts)) {
+ for (const p of opts.properties) {
+ if (ts.isPropertyAssignment(p) && ts.isIdentifier(p.name) && p.name.text === 'name'
+ && ts.isStringLiteral(p.initializer)) {
+ return p.initializer.text;
+ }
+ }
+ }
+ return binding ?? '<anonymous>';
+}
diff --git a/compiler/src/index.ts b/compiler/src/index.ts
new file mode 100644
index 000000000..d7ccd8a52
--- /dev/null
+++ b/compiler/src/index.ts
@@ -0,0 +1,11 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file index.ts
+ * @brief Estella AOT compiler — public surface (docs/REARCH_AOT.md Stage 1).
+ */
+export * from './eir';
+export { lowerProgram, type Diagnostic, type LowerResult } from './frontend';
+export { verifySystem, type VerifyError } from './verify';
+export { runSystem, type EirWorld, type Row } from './interp';
+export { builtinShapes } from './builtins';
diff --git a/compiler/src/interp.ts b/compiler/src/interp.ts
new file mode 100644
index 000000000..c5bb17cf7
--- /dev/null
+++ b/compiler/src/interp.ts
@@ -0,0 +1,138 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file interp.ts
+ * @brief A reference interpreter for EIR-high (docs/REARCH_AOT.md §8.1).
+ *
+ * @details Written before any code generation, for two reasons. It proves the IR
+ * means something on its own, and it is the third implementation a
+ * differential test needs: when compiled output and node disagree, an
+ * oracle that is neither says which one is wrong.
+ *
+ * Deliberately dumb — a tree walk with no caching. Its job is to be
+ * obviously correct, not fast; anything clever here would be a second
+ * place for a bug to hide from the backend it exists to check.
+ */
+import type { EirSystem, Expr, Local, Place, QueryArg, Stmt } from './eir';
+
+/** One component instance, nested exactly as a system reads it. */
+export type Row = Record<string, unknown>;
+
+export interface EirWorld {
+ /** Entity ids in the order a query walks them. */
+ readonly entities: readonly number[];
+ /** component name -> entity -> its row. An absent entity simply has none. */
+ readonly comps: ReadonlyMap<string, Map<number, Row>>;
+ readonly resources: ReadonlyMap<string, Row>;
+}
+
+class Frame {
+ private readonly slots = new Map<number, unknown>();
+ set(id: number, v: unknown): void { this.slots.set(id, v); }
+ get(id: number): unknown {
+ if (!this.slots.has(id)) throw new Error(`EIR: local %${id} read before it was bound`);
+ return this.slots.get(id);
+ }
+}
+
+function walk(root: unknown, path: readonly string[]): { owner: Record<string, unknown>; key: string } {
+ let cur = root as Record<string, unknown>;
+ for (let i = 0; i < path.length - 1; i++) {
+ const next = cur[path[i]!];
+ if (next === null || typeof next !== 'object') {
+ throw new Error(`EIR: '${path.slice(0, i + 1).join('.')}' is not a value with fields`);
+ }
+ cur = next as Record<string, unknown>;
+ }
+ return { owner: cur, key: path[path.length - 1]! };
+}
+
+function readPlace(p: Place, frame: Frame): unknown {
+ if (p.p === 'local') return frame.get(p.id);
+ const base = readPlace(p.base, frame);
+ const { owner, key } = walk(base, p.path);
+ return owner[key];
+}
+
+function writePlace(p: Place, frame: Frame, value: unknown): void {
+ if (p.p === 'local') { frame.set(p.id, value); return; }
+ const base = readPlace(p.base, frame);
+ const { owner, key } = walk(base, p.path);
+ owner[key] = value;
+}
+
+function evalExpr(e: Expr, frame: Frame): number | boolean {
+ switch (e.e) {
+ case 'const': return e.value;
+ case 'read': return readPlace(e.place, frame) as number | boolean;
+ case 'neg': return -(evalExpr(e.v, frame) as number);
+ case 'bin': {
+ const l = evalExpr(e.l, frame) as number;
+ const r = evalExpr(e.r, frame) as number;
+ switch (e.op) {
+ case '+': return l + r;
+ case '-': return l - r;
+ case '*': return l * r;
+ case '/': return l / r;
+ case '%': return l % r;
+ case '<': return l < r;
+ case '<=': return l <= r;
+ case '>': return l > r;
+ case '>=': return l >= r;
+ case '==': return l === r;
+ case '!=': return l !== r;
+ }
+ }
+ }
+}
+
+/** Entities carrying every component the query names, in world order. */
+function matching(world: EirWorld, args: readonly QueryArg[]): number[] {
+ return world.entities.filter((e) => args.every((a) => world.comps.get(a.comp)?.has(e)));
+}
+
+function exec(stmts: readonly Stmt[], frame: Frame, world: EirWorld): void {
+ for (const s of stmts) {
+ switch (s.s) {
+ case 'let':
+ frame.set(s.id, evalExpr(s.value, frame));
+ break;
+ case 'assign':
+ writePlace(s.target, frame, evalExpr(s.value, frame));
+ break;
+ case 'rowLoop': {
+ const q = readPlace(s.query, frame) as { args: readonly QueryArg[] };
+ for (const entity of matching(world, q.args)) {
+ if (s.entity !== null) frame.set(s.entity, entity);
+ s.binds.forEach((id, i) => {
+ frame.set(id, world.comps.get(q.args[i]!.comp)!.get(entity)!);
+ });
+ exec(s.body, frame, world);
+ }
+ break;
+ }
+ }
+ }
+}
+
+/**
+ * Run `sys` against `world`, mutating it in place. Parameters are bound from
+ * their declared types: a query becomes its own argument list, a resource its
+ * row — the same two things the SDK's runner resolves.
+ */
+export function runSystem(sys: EirSystem, world: EirWorld): void {
+ const frame = new Frame();
+ for (const p of sys.params) bindParam(p, frame, world);
+ exec(sys.body, frame, world);
+}
+
+function bindParam(p: Local, frame: Frame, world: EirWorld): void {
+ if (p.type.k === 'query') { frame.set(p.id, { args: p.type.args }); return; }
+ if (p.type.k === 'res') {
+ const row = world.resources.get(p.type.name);
+ if (!row) throw new Error(`EIR: no resource '${p.type.name}' in the world`);
+ frame.set(p.id, row);
+ return;
+ }
+ throw new Error(`EIR: '${p.name}' has no parameter binding for ${p.type.k}`);
+}
diff --git a/compiler/src/verify.ts b/compiler/src/verify.ts
new file mode 100644
index 000000000..b8061b138
--- /dev/null
+++ b/compiler/src/verify.ts
@@ -0,0 +1,161 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file verify.ts
+ * @brief Re-prove an EIR system's types, without looking at the TypeScript.
+ *
+ * @details docs/REARCH_AOT.md §4.1 asks for this because tsc's types are not
+ * sound — structural typing, method bivariance and `any` leak through
+ * generics — so a pass has to prove, on the IR, that every value is the
+ * type it claims.
+ *
+ * It reads only EIR, never the AST. That is the point: re-running the
+ * frontend's own reasoning would agree with the frontend's own bugs,
+ * and the failure this catches is a frontend that lowered something
+ * wrong, not a source file that was outside the subset.
+ */
+import {
+ type CompShape, type EirSystem, type EirType, type Expr, type Local, type Place, type Stmt,
+ typeName,
+} from './eir';
+
+export interface VerifyError {
+ readonly system: string;
+ readonly message: string;
+}
+
+class Verifier {
+ private readonly byId = new Map<number, Local>();
+ readonly errors: VerifyError[] = [];
+
+ constructor(
+ private readonly sys: EirSystem,
+ private readonly comps: ReadonlyMap<string, CompShape>,
+ ) {
+ for (const l of [...sys.params, ...sys.locals]) {
+ if (this.byId.has(l.id)) this.fail(`local %${l.id} ('${l.name}') is declared twice`);
+ this.byId.set(l.id, l);
+ }
+ }
+
+ private fail(message: string): void {
+ this.errors.push({ system: this.sys.name, message });
+ }
+
+ private local(id: number): Local | null {
+ const l = this.byId.get(id);
+ if (!l) { this.fail(`local %${id} is used but never declared`); return null; }
+ return l;
+ }
+
+ /** The type a place reads as, or null when it does not resolve. */
+ placeType(p: Place): EirType | null {
+ if (p.p === 'local') return this.local(p.id)?.type ?? null;
+ const base = this.placeType(p.base);
+ if (!base) return null;
+ if (base.k !== 'comp' && base.k !== 'res') {
+ this.fail(`a ${typeName(base)} has no field '${p.path.join('.')}'`);
+ return null;
+ }
+ const shape = this.comps.get(base.name);
+ if (!shape) { this.fail(`no declared shape for '${base.name}'`); return null; }
+ const t = shape.fields.get(p.path.join('.'));
+ if (!t) { this.fail(`'${base.name}' has no field '${p.path.join('.')}'`); return null; }
+ return t;
+ }
+
+ exprType(e: Expr): EirType | null {
+ switch (e.e) {
+ case 'const':
+ if ((typeof e.value === 'boolean') !== (e.type.k === 'bool')) {
+ this.fail(`constant ${String(e.value)} is declared ${typeName(e.type)}`);
+ }
+ return e.type;
+ case 'read': {
+ const t = this.placeType(e.place);
+ if (t && t.k !== e.type.k) {
+ this.fail(`a read declared ${typeName(e.type)} resolves to ${typeName(t)}`);
+ }
+ return t;
+ }
+ case 'neg': {
+ const t = this.exprType(e.v);
+ if (t && t.k !== 'f64') this.fail(`negation of a ${typeName(t)}`);
+ return t;
+ }
+ case 'bin': {
+ const l = this.exprType(e.l);
+ const r = this.exprType(e.r);
+ for (const t of [l, r]) {
+ if (t && t.k !== 'f64') this.fail(`operator '${e.op}' applied to a ${typeName(t)}`);
+ }
+ return e.type;
+ }
+ }
+ }
+
+ stmt(s: Stmt): void {
+ switch (s.s) {
+ case 'let': {
+ const declared = this.local(s.id)?.type;
+ const actual = this.exprType(s.value);
+ if (declared && actual && declared.k !== actual.k) {
+ this.fail(`'${this.byId.get(s.id)?.name}' is ${typeName(declared)} but is bound to ${typeName(actual)}`);
+ }
+ break;
+ }
+ case 'assign': {
+ const target = this.placeType(s.target);
+ const value = this.exprType(s.value);
+ if (target && value && target.k !== value.k) {
+ this.fail(`assigning ${typeName(value)} into a ${typeName(target)}`);
+ }
+ break;
+ }
+ case 'rowLoop': {
+ const q = this.placeType(s.query);
+ if (!q) break;
+ if (q.k !== 'query') { this.fail(`rowLoop over a ${typeName(q)}`); break; }
+ if (q.args.length !== s.binds.length) {
+ this.fail(`rowLoop binds ${s.binds.length} components for a query of ${q.args.length}`);
+ }
+ s.binds.forEach((id, i) => {
+ const l = this.local(id);
+ const want = q.args[i];
+ if (!l || !want) return;
+ if (l.type.k !== 'comp' || l.type.name !== want.comp) {
+ this.fail(`row binds '${l.name}' as ${typeName(l.type)} for component '${want.comp}'`);
+ }
+ // A component the query did not ask to write must not be a
+ // target — the read-only half of Mut, proved here rather than
+ // trusted from the source.
+ if (!want.mut && this.writesTo(s.body, id)) {
+ this.fail(`'${l.name}' is written but the query asks for '${want.comp}' without Mut`);
+ }
+ });
+ if (s.entity !== null) {
+ const l = this.local(s.entity);
+ if (l && l.type.k !== 'entity') this.fail(`row entity bound as ${typeName(l.type)}`);
+ }
+ for (const b of s.body) this.stmt(b);
+ break;
+ }
+ }
+ }
+
+ private writesTo(body: readonly Stmt[], id: number): boolean {
+ const rootOf = (p: Place): number => (p.p === 'local' ? p.id : rootOf(p.base));
+ for (const s of body) {
+ if (s.s === 'assign' && rootOf(s.target) === id) return true;
+ if (s.s === 'rowLoop' && this.writesTo(s.body, id)) return true;
+ }
+ return false;
+ }
+}
+
+/** Every type claim in `sys`, re-proved. An empty array means it holds. */
+export function verifySystem(sys: EirSystem, comps: ReadonlyMap<string, CompShape>): VerifyError[] {
+ const v = new Verifier(sys, comps);
+ for (const s of sys.body) v.stmt(s);
+ return v.errors;
+}
diff --git a/compiler/tests/fixtures/dynamic-component.ts b/compiler/tests/fixtures/dynamic-component.ts
new file mode 100644
index 000000000..034d022d0
--- /dev/null
+++ b/compiler/tests/fixtures/dynamic-component.ts
@@ -0,0 +1,13 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file dynamic-component.ts
+ * @brief A defineComponent whose shape is not a literal.
+ *
+ * @details §3.3 makes it an intrinsic, so a shape the compiler cannot read at
+ * compile time is a fallback, not a guess.
+ */
+import { defineComponent } from 'esengine';
+
+const defaults = { hp: 100 };
+export const Dynamic = defineComponent('FixtureDynamic', defaults);
diff --git a/compiler/tests/fixtures/outside-subset.ts b/compiler/tests/fixtures/outside-subset.ts
new file mode 100644
index 000000000..2900a980e
--- /dev/null
+++ b/compiler/tests/fixtures/outside-subset.ts
@@ -0,0 +1,58 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file outside-subset.ts
+ * @brief Systems that must NOT compile.
+ *
+ * @details Each names a rule from REARCH_AOT §3; subset.test.ts asserts the
+ * diagnostic points at the line and says why.
+ */
+import { defineComponent, defineSystem, Query, Mut, Res, Time, Transform } from 'esengine';
+
+export const Speed = defineComponent('FixtureSpeed', { value: 100 });
+
+/** A branch: no control flow beyond the row loop is lowered yet. */
+export const branching = defineSystem(
+ [Query(Mut(Transform), Speed)],
+ (query) => {
+ for (const [_e, t, s] of query) {
+ if (s.value > 0) {
+ t.position.x += s.value;
+ }
+ }
+ },
+ { name: 'FixtureBranching' },
+);
+
+/** A field the component does not declare — a typo, caught at compile time. */
+export const typoField = defineSystem(
+ [Query(Mut(Transform), Speed)],
+ (query) => {
+ for (const [_e, t, s] of query) {
+ t.position.x += s.valeu;
+ }
+ },
+ { name: 'FixtureTypo' },
+);
+
+/** A call: nothing outside the intrinsics is reachable from a compiled system. */
+export const calling = defineSystem(
+ [Query(Mut(Transform), Speed), Res(Time)],
+ (query, time) => {
+ for (const [_e, t, s] of query) {
+ t.position.x += Math.sin(s.value) * time.delta;
+ }
+ },
+ { name: 'FixtureCalling' },
+);
+
+/** Writing a component the query did not ask to write. */
+export const writesReadOnly = defineSystem(
+ [Query(Transform, Speed)],
+ (query) => {
+ for (const [_e, t, s] of query) {
+ t.position.x += s.value;
+ }
+ },
+ { name: 'FixtureWritesReadOnly' },
+);
diff --git a/compiler/tests/move-system.test.ts b/compiler/tests/move-system.test.ts
new file mode 100644
index 000000000..cbd0916cf
--- /dev/null
+++ b/compiler/tests/move-system.test.ts
@@ -0,0 +1,139 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file move-system.test.ts
+ * @brief Stage 1's exit criterion, end to end (docs/REARCH_AOT.md §10).
+ *
+ * @details Takes a real system out of examples/, lowers it to EIR, and holds
+ * the interpreter's result against node's.
+ *
+ * Both sides read the SAME FILE — the oracle is move.ts imported through a
+ * stubbed `esengine`, not a copy re-typed here. A copy would agree with
+ * whatever the copy got wrong.
+ */
+import { describe, it, expect } from 'vitest';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { lowerProgram } from '../src/frontend';
+import { verifySystem } from '../src/verify';
+import { runSystem, type EirWorld, type Row } from '../src/interp';
+import { builtinShapes } from '../src/builtins';
+import { printSystem } from '../src/eir';
+
+import { moveSystem } from '../../examples/ecs-basics/src/systems/move';
+import type { StubSystem } from './stubs/esengine';
+
+const ROOT = resolve(fileURLToPath(new URL('../..', import.meta.url)));
+const FILES = [
+ resolve(ROOT, 'examples/ecs-basics/src/systems/move.ts'),
+ resolve(ROOT, 'examples/ecs-basics/src/components.ts'),
+];
+
+const ENTITIES = 64;
+
+/** Two identical worlds from one seed, so a difference can only be the system. */
+function makeWorld(): EirWorld {
+ let a = 0x2f6e2b1 >>> 0;
+ const rand = (): number => {
+ a = (a * 1664525 + 1013904223) >>> 0;
+ return (a >>> 8) / 16777216;
+ };
+ const transforms = new Map<number, Row>();
+ const movers = new Map<number, Row>();
+ const entities: number[] = [];
+ for (let e = 1; e <= ENTITIES; e++) {
+ entities.push(e);
+ transforms.set(e, {
+ position: { x: (rand() - 0.5) * 200, y: (rand() - 0.5) * 200, 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 },
+ });
+ // Every third entity has no Mover, so "the query matched the right rows"
+ // is part of what the comparison proves.
+ if (e % 3 !== 0) {
+ movers.set(e, { speed: 20 + rand() * 80, directionX: rand() * 2 - 1, directionY: rand() * 2 - 1 });
+ }
+ }
+ return {
+ entities,
+ comps: new Map([['Transform', transforms], ['Mover', movers]]),
+ resources: new Map<string, Row>([['Time', { delta: 1 / 60, elapsed: 0 }]]),
+ };
+}
+
+/** Run the real callback, handing it live rows the way a Mut query does. */
+function runNative(world: EirWorld): void {
+ const sys = moveSystem as unknown as StubSystem;
+ const transforms = world.comps.get('Transform')!;
+ const movers = world.comps.get('Mover')!;
+ const query = {
+ *[Symbol.iterator]() {
+ for (const e of world.entities) {
+ if (transforms.has(e) && movers.has(e)) yield [e, transforms.get(e)!, movers.get(e)!];
+ }
+ },
+ };
+ (sys.fn as unknown as (q: unknown, t: unknown) => void)(query, world.resources.get('Time'));
+}
+
+describe('Stage 1 — a real example system, end to end', () => {
+ const { module, diagnostics, seen } = lowerProgram(FILES, builtinShapes());
+ const moveEir = module.systems.find((s) => s.name === 'MoveSystem');
+
+ it('lowers MoveSystem out of examples/ecs-basics', () => {
+ expect(seen).toContain('MoveSystem');
+ expect(diagnostics.filter((d) => d.system === 'MoveSystem')).toEqual([]);
+ expect(moveEir).toBeDefined();
+ });
+
+ it('reads back as the loop it came from', () => {
+ expect(printSystem(moveEir!)).toMatchInlineSnapshot(`
+ "system MoveSystem(query: query<mut Transform, Mover>, time: res<Time>) {
+ rowLoop query -> (_entity, transform, mover) {
+ transform.position.x = (transform.position.x + ((mover.directionX * mover.speed) * time.delta))
+ transform.position.y = (transform.position.y + ((mover.directionY * mover.speed) * time.delta))
+ }
+ }"
+ `);
+ });
+
+ it('re-proves its own types without looking at the TypeScript', () => {
+ expect(verifySystem(moveEir!, module.comps)).toEqual([]);
+ });
+
+ it('picks up Mover from defineComponent as a compile-time declaration', () => {
+ expect([...module.comps.get('Mover')!.fields.keys()]).toEqual(['speed', 'directionX', 'directionY']);
+ });
+
+ it('moves the world exactly the way node does', () => {
+ const byNode = makeWorld();
+ const byEir = makeWorld();
+ expect(byEir).toEqual(byNode);
+
+ for (let frame = 0; frame < 30; frame++) {
+ runNative(byNode);
+ runSystem(moveEir!, byEir);
+ }
+
+ // Bit-for-bit: both sides are f64 doing the same operations in the same
+ // order, so "close enough" would hide a real divergence.
+ expect(byEir.comps.get('Transform')).toEqual(byNode.comps.get('Transform'));
+ expect(byEir.comps.get('Mover')).toEqual(byNode.comps.get('Mover'));
+ });
+
+ it('did something — a system that no-ops would also agree', () => {
+ const before = makeWorld();
+ const after = makeWorld();
+ for (let frame = 0; frame < 30; frame++) runSystem(moveEir!, after);
+ expect(after.comps.get('Transform')).not.toEqual(before.comps.get('Transform'));
+ // The entities without a Mover must NOT have moved.
+ for (const e of after.entities) {
+ if (e % 3 === 0) {
+ expect(after.comps.get('Transform')!.get(e)).toEqual(before.comps.get('Transform')!.get(e));
+ }
+ }
+ });
+});
diff --git a/compiler/tests/stubs/esengine.ts b/compiler/tests/stubs/esengine.ts
new file mode 100644
index 000000000..c1b9739ae
--- /dev/null
+++ b/compiler/tests/stubs/esengine.ts
@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file esengine.ts
+ * @brief Enough of the SDK for an example system file to be imported and run.
+ *
+ * @details The differential needs both sides reading one source, so the oracle
+ * has to be the real move.ts rather than a copy living in a test.
+ */
+export interface StubSystem {
+ readonly name: string;
+ readonly params: readonly unknown[];
+ readonly fn: (...args: any[]) => void;
+}
+
+export const Transform = { _name: 'Transform' };
+export const Time = { _name: 'Time' };
+
+export function defineComponent(name: string, defaults: Record<string, unknown>): unknown {
+ return { _name: name, defaults };
+}
+export function defineTag(name: string): unknown {
+ return { _name: name, defaults: {} };
+}
+export function Query(...args: unknown[]): unknown {
+ return { kind: 'query', args };
+}
+export function Mut(comp: unknown): unknown {
+ return { kind: 'mut', comp };
+}
+export function Res(resource: unknown): unknown {
+ return { kind: 'res', resource };
+}
+export function defineSystem(
+ params: readonly unknown[],
+ fn: (...args: any[]) => void,
+ opts?: { name?: string },
+): StubSystem {
+ return { name: opts?.name ?? '<anonymous>', params, fn };
+}
+export function addSystemToSchedule(): void { /* the example's main.ts calls this */ }
+export function addStartupSystem(): void { /* likewise */ }
+export const Schedule = { Update: 'Update' } as const;
diff --git a/compiler/tests/subset.test.ts b/compiler/tests/subset.test.ts
new file mode 100644
index 000000000..52aaddf6d
--- /dev/null
+++ b/compiler/tests/subset.test.ts
@@ -0,0 +1,66 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file subset.test.ts
+ * @brief What the subset must REFUSE, and how it says so.
+ *
+ * @details A checker that accepts everything is not a checker. Each case pins a
+ * rule from §3 and asserts the refusal names a line and a reason —
+ * §11's "coverage stalls low" is a diagnostics problem first.
+ */
+import { describe, it, expect } from 'vitest';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { lowerProgram } from '../src/frontend';
+import { verifySystem } from '../src/verify';
+import { builtinShapes } from '../src/builtins';
+
+const HERE = resolve(fileURLToPath(new URL('.', import.meta.url)));
+const OUTSIDE = resolve(HERE, 'fixtures/outside-subset.ts');
+const DYNAMIC = resolve(HERE, 'fixtures/dynamic-component.ts');
+
+const result = lowerProgram([OUTSIDE], builtinShapes());
+const diagOf = (system: string) => result.diagnostics.find((d) => d.system === system);
+const compiled = (system: string) => result.module.systems.some((s) => s.name === system);
+
+describe('the subset refuses, and says why', () => {
+ it('saw every system in the file, compiled or not', () => {
+ expect(result.seen).toEqual([
+ 'FixtureBranching', 'FixtureTypo', 'FixtureCalling', 'FixtureWritesReadOnly',
+ ]);
+ });
+
+ it.each([
+ ['FixtureBranching', /IfStatement is not a statement/],
+ ['FixtureTypo', /has no field 'valeu'/],
+ ['FixtureCalling', /CallExpression is not an expression/],
+ ])('refuses %s', (name, why) => {
+ const d = diagOf(name);
+ expect(d, `${name} compiled when it should not have`).toBeDefined();
+ expect(d!.message).toMatch(why);
+ expect(d!.line).toBeGreaterThan(0);
+ expect(d!.file).toContain('outside-subset');
+ expect(compiled(name)).toBe(false);
+ });
+
+ it('lowers a write to a component the query did not ask to write…', () => {
+ // The frontend has no reason to refuse this — it is well-formed TS and a
+ // well-formed place. Which is exactly why the verifier must catch it.
+ expect(diagOf('FixtureWritesReadOnly')).toBeUndefined();
+ expect(compiled('FixtureWritesReadOnly')).toBe(true);
+ });
+
+ it('…and the verifier refuses it on the IR alone', () => {
+ const sys = result.module.systems.find((s) => s.name === 'FixtureWritesReadOnly')!;
+ const errors = verifySystem(sys, result.module.comps);
+ expect(errors).toHaveLength(1);
+ expect(errors[0]!.message).toMatch(/is written but the query asks for 'Transform' without Mut/);
+ });
+
+ it('refuses a defineComponent whose shape is not a literal', () => {
+ const dyn = lowerProgram([DYNAMIC], builtinShapes());
+ expect(dyn.module.comps.has('FixtureDynamic')).toBe(false);
+ expect(dyn.diagnostics).toHaveLength(1);
+ expect(dyn.diagnostics[0]!.message).toMatch(/object literal of literal defaults/);
+ });
+});
diff --git a/compiler/tsconfig.json b/compiler/tsconfig.json
new file mode 100644
index 000000000..70474cfe8
--- /dev/null
+++ b/compiler/tsconfig.json
@@ -0,0 +1,17 @@
+{
+ "compilerOptions": {
+ "target": "ES2022",
+ "module": "ESNext",
+ "moduleResolution": "bundler",
+ "strict": true,
+ "noUncheckedIndexedAccess": true,
+ "exactOptionalPropertyTypes": true,
+ "noEmit": true,
+ "skipLibCheck": true,
+ "baseUrl": ".",
+ "paths": { "esengine": ["./tests/stubs/esengine.ts"] },
+ "types": []
+ },
+ "include": ["src/**/*.ts", "tests/**/*.ts"],
+ "exclude": ["tests/fixtures/**"]
+}
diff --git a/compiler/vitest.config.ts b/compiler/vitest.config.ts
new file mode 100644
index 000000000..863ac8f29
--- /dev/null
+++ b/compiler/vitest.config.ts
@@ -0,0 +1,13 @@
+import { defineConfig } from 'vitest/config';
+import { fileURLToPath } from 'node:url';
+
+export default defineConfig({
+ test: { include: ['tests/**/*.test.ts'], environment: 'node' },
+ resolve: {
+ alias: {
+ // So a test can import a real example system, whose own imports the
+ // stub answers. Without this the oracle would be a re-typed copy.
+ esengine: fileURLToPath(new URL('./tests/stubs/esengine.ts', import.meta.url)),
+ },
+ },
+});
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index f119cc895..d8362928a 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -34,6 +34,18 @@ importers:
specifier: ^2.1.9
+ compiler:
+ devDependencies:
+ '@types/node':
+ specifier: ^22.0.0
+ version: 22.20.1
+ typescript:
+ specifier: ^5.6.0
+ version: 5.9.3
+ vitest:
+ specifier: ^2.1.9
+
desktop:
dependencies:
'@anthropic-ai/sdk':
@@ -1255,6 +1267,9 @@ packages:
resolution: {integrity: sha512-F0KIgDJfy2nA3zMLmWGKxcH2ZVEtCZXHHdOQs2gSaQ27+lNeEfGxzkIw90aXswATX7AZ33tahPbzy6KAfUreVw==}
+ '@types/[email protected]':
+ resolution: {integrity: sha512-EANqOCF9QFyra+4pfxUcX9STKJpCLjMbObVzljIJomAWSnuSIEAvyzEU53GaajbXJEgdh0iEcPL+DGvpUd4k1Q==}
+
resolution: {integrity: sha512-fRa09kZTgu8o71KFcDjUFuc7F+dEbZYZmkI0mg5YBTRs0yMKjYHsq/c0urDKeDb+D5qVgXOdFcuu+DZPKOITwA==}
@@ -3474,6 +3489,9 @@ packages:
resolution: {integrity: sha512-JFNbkD1Svwe0KvGi8GOeLcP4kAWQ609twvCdcHxq1oSL8svv39ZuSvajcD8B+5D0eL4+s1Is2D/O6KN3qcTeRA==}
+ resolution: {integrity: sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==}
+
resolution: {integrity: sha512-AsuCzffGHJybSaRrmr5eHr81mwJU3kjw6M+uprWvCXiNeN9SOGwQ3Jn8jb8m3Z6izVgknn1R0FTCEAP2QrLY/w==}
@@ -4532,6 +4550,10 @@ snapshots:
'@types/[email protected]': {}
+ '@types/[email protected]':
+ dependencies:
+ undici-types: 6.21.0
+
dependencies:
undici-types: 7.18.2
@@ -4625,6 +4647,14 @@ snapshots:
chai: 5.3.3
tinyrainbow: 1.2.0
+ dependencies:
+ '@vitest/spy': 2.1.9
+ estree-walker: 3.0.3
+ magic-string: 0.30.21
+ optionalDependencies:
+
dependencies:
'@vitest/spy': 2.1.9
@@ -4661,7 +4691,7 @@ snapshots:
sirv: 3.0.2
tinyglobby: 0.2.15
tinyrainbow: 1.2.0
'@vitest/[email protected]':
dependencies:
@@ -7016,6 +7046,8 @@ snapshots:
+
@@ -7045,6 +7077,24 @@ snapshots:
+ dependencies:
+ cac: 6.7.14
+ debug: 4.4.3
+ es-module-lexer: 1.7.0
+ pathe: 1.1.2
+ transitivePeerDependencies:
+ - '@types/node'
+ - less
+ - lightningcss
+ - sass
+ - sass-embedded
+ - stylus
+ - sugarss
+ - supports-color
+ - terser
+
dependencies:
cac: 6.7.14
@@ -7071,6 +7121,17 @@ snapshots:
optionalDependencies:
vite-plugin-electron-renderer: 1.0.0
+ dependencies:
+ esbuild: 0.21.5
+ postcss: 8.5.6
+ rollup: 4.57.1
+ optionalDependencies:
+ '@types/node': 22.20.1
+ fsevents: 2.3.3
+ lightningcss: 1.32.0
+ terser: 5.46.0
+
dependencies:
esbuild: 0.21.5
@@ -7096,6 +7157,44 @@ snapshots:
jiti: 2.7.0
terser: 5.46.0
+ dependencies:
+ '@vitest/expect': 2.1.9
+ '@vitest/pretty-format': 2.1.9
+ '@vitest/runner': 2.1.9
+ '@vitest/snapshot': 2.1.9
+ '@vitest/spy': 2.1.9
+ '@vitest/utils': 2.1.9
+ chai: 5.3.3
+ debug: 4.4.3
+ expect-type: 1.3.0
+ magic-string: 0.30.21
+ pathe: 1.1.2
+ std-env: 3.10.0
+ tinybench: 2.9.0
+ tinyexec: 0.3.2
+ tinypool: 1.1.1
+ tinyrainbow: 1.2.0
+ why-is-node-running: 2.3.0
+ optionalDependencies:
+ '@types/node': 22.20.1
+ '@vitest/ui': 2.1.9([email protected])
+ happy-dom: 15.11.7
+ jsdom: 25.0.1
+ transitivePeerDependencies:
+ - less
+ - lightningcss
+ - msw
+ - sass
+ - sass-embedded
+ - stylus
+ - sugarss
+ - supports-color
+ - terser
+
dependencies:
'@vitest/expect': 2.1.9
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index 8912c87d9..bd77f70d9 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -1,6 +1,7 @@
packages:
- 'sdk'
- 'pipeline'
+ - 'compiler'
- 'desktop'
- 'editor-api'
- 'plugins/*'
diff --git a/tools/gates.mjs b/tools/gates.mjs
index 422b7a23e..984d6024c 100644
--- a/tools/gates.mjs
+++ b/tools/gates.mjs
@@ -77,6 +77,9 @@ export const GATES = [
// The engine's own TS suites (pipeline + tooling). They lived in desktop/tests
// until the editor split, where a checkout without the editor ran none of them.
{ 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).
+ { 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' },
// Same shape of rule, other direction: what builds a project may not need the