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(aot): the packaged host answers the interpreter too, on both its roads

yhhf64a34a5abb2
diff --git a/fixtures/aot-conformance/.gitignore b/fixtures/aot-conformance/.gitignore
new file mode 100644
index 000000000..5ef1a2358
--- /dev/null
+++ b/fixtures/aot-conformance/.gitignore
@@ -0,0 +1,3 @@
+node_modules/
+dist/
+.esengine/cache/
diff --git a/fixtures/aot-conformance/assets/scenes/main.esscene b/fixtures/aot-conformance/assets/scenes/main.esscene
new file mode 100644
index 000000000..cd5ad72b8
--- /dev/null
+++ b/fixtures/aot-conformance/assets/scenes/main.esscene
@@ -0,0 +1,30 @@
+{
+ "version": 4,
+ "name": "Main",
+ "entities": [
+ {
+ "id": 0,
+ "name": "Camera",
+ "parent": null,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": { "x": 0, "y": 0, "z": 10 }
+ }
+ },
+ {
+ "type": "Camera",
+ "data": {
+ "projectionType": 1,
+ "orthoSize": 300,
+ "isActive": true,
+ "priority": 0
+ }
+ }
+ ],
+ "visible": true
+ }
+ ]
+}
diff --git a/fixtures/aot-conformance/assets/scenes/main.esscene.meta b/fixtures/aot-conformance/assets/scenes/main.esscene.meta
new file mode 100644
index 000000000..f4af3b661
--- /dev/null
+++ b/fixtures/aot-conformance/assets/scenes/main.esscene.meta
@@ -0,0 +1,8 @@
+{
+ "uuid": "3f1c7a52-9d84-4c6b-b0e5-2a7f4d18c930",
+ "version": "2.0",
+ "type": "scene",
+ "importer": {
+ "autoMigrate": true
+ }
+}
diff --git a/fixtures/aot-conformance/project.esproject b/fixtures/aot-conformance/project.esproject
new file mode 100644
index 000000000..64278e2df
--- /dev/null
+++ b/fixtures/aot-conformance/project.esproject
@@ -0,0 +1,13 @@
+{
+ "formatVersion": "1",
+ "name": "AOT Conformance",
+ "tag": "Fixture",
+ "description": "The conformance fixture as a shipped game, so a native host runs the same source the suite does.",
+ "version": "0.1.0",
+ "defaultScene": "assets/scenes/main.esscene",
+ "designResolution": {
+ "width": 320,
+ "height": 240
+ },
+ "spineVersion": "none"
+}
diff --git a/fixtures/aot-conformance/src/main.ts b/fixtures/aot-conformance/src/main.ts
new file mode 100644
index 000000000..b7b0be396
--- /dev/null
+++ b/fixtures/aot-conformance/src/main.ts
@@ -0,0 +1,40 @@
+// The conformance fixture as a game: the same two systems, the same seed world.
+// The reporting is game code on purpose — a host-side dump would be a second
+// path nobody ships.
+import {
+ addStartupSystem, addSystemToSchedule, Commands, defineSystem,
+ Query, Res, Schedule, Time,
+} from 'esengine';
+
+import { Mover, driftSystem, clampSystem } from './systems.generated';
+import { SEED } from './seed.generated';
+
+/** Spawned in the order the trace records rows in, which is pool order. */
+const spawnSystem = defineSystem(
+ [Commands()],
+ (cmds) => {
+ for (const [x, speed] of SEED) cmds.spawn().insert(Mover, { x, speed, bounces: 0 });
+ },
+ { name: 'ConfSpawn' },
+);
+
+let frame = 0;
+
+/** Last in the schedule, and not `@compiled`: it reads what the two above left.
+ * The delta goes out with the rows because a road that stepped by another one
+ * is a different question from a road that computed the step wrong. */
+const reportSystem = defineSystem(
+ [Query(Mover), Res(Time)],
+ (query, time) => {
+ const rows: number[][] = [];
+ for (const [, m] of query) rows.push([m.x, m.speed, m.bounces]);
+ console.log(`CONF ${frame} ${time.delta} ${JSON.stringify(rows)}`);
+ frame++;
+ },
+ { name: 'ConfReport' },
+);
+
+addStartupSystem(spawnSystem);
+addSystemToSchedule(Schedule.Update, driftSystem);
+addSystemToSchedule(Schedule.Update, clampSystem);
+addSystemToSchedule(Schedule.Update, reportSystem);
diff --git a/fixtures/aot-conformance/src/seed.generated.ts b/fixtures/aot-conformance/src/seed.generated.ts
new file mode 100644
index 000000000..be88f25fc
--- /dev/null
+++ b/fixtures/aot-conformance/src/seed.generated.ts
@@ -0,0 +1,11 @@
+// GENERATED from sdk/tests/aot-conformance.test.ts — do not edit.
+// The world the checked-in trace was recorded over.
+
+export const SEED: readonly (readonly [number, number])[] = [
+ [0, 120],
+ [9.5, 60],
+ [-9.5, -60],
+ [3, -300],
+];
+
+export const FRAMES = 12;
diff --git a/fixtures/aot-conformance/src/systems.generated.ts b/fixtures/aot-conformance/src/systems.generated.ts
new file mode 100644
index 000000000..da2004746
--- /dev/null
+++ b/fixtures/aot-conformance/src/systems.generated.ts
@@ -0,0 +1,52 @@
+// GENERATED from sdk/tests/fixtures/conformance-systems.ts — do not edit.
+// The same systems, with the imports a PROJECT writes. Regenerate with
+// ESTELLA_AOT_WRITE=1 pnpm --filter @estella/sdk test aot-conformance.
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file conformance-systems.ts
+ * @brief One source, read twice: as closures, and as the module the compiler
+ * makes of it.
+ *
+ * @details Imported by relative path rather than through `esengine`, because
+ * the same file has to be importable by the suite AND lowerable by the
+ * compiler — which matches `defineSystem` by name, not by where it
+ * came from.
+ */
+import { defineComponent, defineSystem, Query, Mut, Res, Time } from 'esengine';
+
+export const Mover = defineComponent('ConfMover', { x: 0, speed: 0, bounces: 0 });
+
+/**
+ * @compiled
+ */
+export const driftSystem = defineSystem(
+ [Query(Mut(Mover)), Res(Time)],
+ (query, time) => {
+ for (const [, m] of query) {
+ m.x = m.x + m.speed * time.delta;
+ }
+ },
+ { name: 'ConfDrift' },
+);
+
+/**
+ * @compiled
+ */
+export const clampSystem = defineSystem(
+ [Query(Mut(Mover))],
+ (query) => {
+ for (const [, m] of query) {
+ if (m.x > 10) {
+ m.x = 10;
+ m.speed = -m.speed;
+ m.bounces = m.bounces + 1;
+ } else if (m.x < -10) {
+ m.x = -10;
+ m.speed = -m.speed;
+ m.bounces = m.bounces + 1;
+ }
+ }
+ },
+ { name: 'ConfClamp' },
+);
diff --git a/fixtures/aot-conformance/tsconfig.json b/fixtures/aot-conformance/tsconfig.json
new file mode 100644
index 000000000..1f11ff310
--- /dev/null
+++ b/fixtures/aot-conformance/tsconfig.json
@@ -0,0 +1,20 @@
+{
+ "compilerOptions": {
+ "target": "ES2020",
+ "module": "ESNext",
+ "moduleResolution": "bundler",
+ "strict": true,
+ "esModuleInterop": true,
+ "skipLibCheck": true,
+ "forceConsistentCasingInFileNames": true,
+ "declaration": false,
+ "outDir": "./dist",
+ "rootDir": ".",
+ "paths": {
+ "esengine": ["./.esengine/sdk/index.d.ts"],
+ "esengine/wasm": ["./.esengine/sdk/wasm.d.ts"]
+ }
+ },
+ "include": ["src/**/*"],
+ "exclude": ["node_modules"]
+}
diff --git a/sdk/tests/aot-conformance.test.ts b/sdk/tests/aot-conformance.test.ts
index 355c29bfa..212b65561 100644
--- a/sdk/tests/aot-conformance.test.ts
+++ b/sdk/tests/aot-conformance.test.ts
@@ -50,6 +50,8 @@ const SEEDS: readonly (readonly [number, number])[] =
* includes `estella_offsets.h` by that name and guards it by that name, so two
* fixtures cannot share one. */
const NATIVE_DIR = path.resolve(__dirname, '../../tests/aot/generated/conformance');
+/** The project a native host runs the same fixture as, scripts and all. */
+const PROJECT_DIR = path.resolve(__dirname, '../../fixtures/aot-conformance/src');
const WRITE = process.env['ESTELLA_AOT_WRITE'] === '1';
/** The artifact a build makes of the fixture: the module, and what it declares. */
@@ -166,12 +168,12 @@ function nativeArtifact(): ReturnType<typeof emitC> {
return emitC(lowered.module, packLayout(lowered.module.comps), inlined, 8);
}
-/** A checked-in input to the C++ harness. Regenerate them all with
+/** A checked-in file derived from the fixture. Regenerate them all with
* `ESTELLA_AOT_WRITE=1 pnpm --filter @estella/sdk test aot-conformance`. */
-function artifact(name: string, want: string): void {
- const at = path.join(NATIVE_DIR, name);
+function artifact(dir: string, name: string, want: string): void {
+ const at = path.join(dir, name);
if (WRITE) {
- mkdirSync(NATIVE_DIR, { recursive: true });
+ mkdirSync(dir, { recursive: true });
writeFileSync(at, want);
return;
}
@@ -182,6 +184,52 @@ function artifact(name: string, want: string): void {
expect(have, `${name} is stale — regenerate with ESTELLA_AOT_WRITE=1`).toBe(want);
}
+/**
+ * The fixture as a PROJECT imports it.
+ *
+ * A project's scripts import `esengine`; this file imports the SDK by relative
+ * path so the suite and the compiler can both read it. The bodies must not
+ * diverge, so the imports are rewritten and nothing else is touched.
+ */
+function projectSystems(): string {
+ const RELATIVE = /^import \{([^}]*)\} from '\.\.\/\.\.\/src\/[^']*';$/;
+ const names: string[] = [];
+ const out: string[] = [];
+ let at = -1;
+ for (const line of readFileSync(FIXTURE, 'utf8').replace(/\r\n/g, '\n').split('\n')) {
+ const m = RELATIVE.exec(line);
+ if (m === null) {
+ out.push(line);
+ continue;
+ }
+ for (const n of m[1]!.split(',')) if (n.trim() !== '') names.push(n.trim());
+ if (at === -1) at = out.push('') - 1;
+ }
+ expect(names.length, 'the fixture imports the SDK by relative path').toBeGreaterThan(0);
+ out[at] = `import { ${names.join(', ')} } from 'esengine';`;
+ return [
+ '// GENERATED from sdk/tests/fixtures/conformance-systems.ts — do not edit.',
+ '// The same systems, with the imports a PROJECT writes. Regenerate with',
+ '// ESTELLA_AOT_WRITE=1 pnpm --filter @estella/sdk test aot-conformance.',
+ ...out,
+ ].join('\n');
+}
+
+/** The seed world, where the project that plays it can read it. */
+function projectSeed(): string {
+ return [
+ '// GENERATED from sdk/tests/aot-conformance.test.ts — do not edit.',
+ '// The world the checked-in trace was recorded over.',
+ '',
+ 'export const SEED: readonly (readonly [number, number])[] = [',
+ ...SEEDS.map(([x, speed]) => ` [${x}, ${speed}],`),
+ '];',
+ '',
+ `export const FRAMES = ${FRAMES};`,
+ '',
+ ].join('\n');
+}
+
/** A double as C source. Shortest round-trip: both languages read a decimal to
* the NEAREST binary64, so what JS prints is the number C gets back. `-0` is
* the one value JS prints without its sign, and `-speed` can produce it. */
@@ -257,10 +305,10 @@ function traceHeader(run: { trace: Trace; delta: number }): string {
describe('the inputs a loading host builds against', () => {
it('the C the compiler makes of the fixture, at the loading width', () => {
const c = nativeArtifact();
- artifact('estella_offsets.h', c.offsets);
- artifact('systems.c', c.source);
- artifact('systems_decl.c', c.decls);
- artifact('handshake.h', handshakeHeader(c.handshake));
+ artifact(NATIVE_DIR, 'estella_offsets.h', c.offsets);
+ artifact(NATIVE_DIR, 'systems.c', c.source);
+ artifact(NATIVE_DIR, 'systems_decl.c', c.decls);
+ artifact(NATIVE_DIR, 'handshake.h', handshakeHeader(c.handshake));
});
it('and the answer the interpreter gives, for the harness to hold it against', async () => {
@@ -270,6 +318,23 @@ describe('the inputs a loading host builds against', () => {
const run = await play(null);
// A seed world that ends where it started proves nothing on any road.
expect(run.trace[FRAMES - 1]).not.toEqual(run.trace[0]);
- artifact('trace.h', traceHeader(run));
+ artifact(NATIVE_DIR, 'trace.h', traceHeader(run));
+ // The same answer for a reader that is not a C compiler: the native
+ // host road is driven from JS, and re-parsing the header there would be
+ // a second reading of one number rather than the number.
+ artifact(NATIVE_DIR, 'trace.json', `${JSON.stringify({
+ delta: run.delta,
+ fields: ['x', 'speed', 'bounces'],
+ seed: SEEDS.map(([x, speed]) => [x, speed, 0]),
+ frames: run.trace,
+ }, null, 2)}\n`);
+ });
+
+ // The third road runs the fixture as a shipped game, so it needs the source
+ // as a project holds one. Generated rather than copied: a hand-kept twin is
+ // the thing this whole differential exists to not have.
+ it('and the fixture as a project imports it', () => {
+ artifact(PROJECT_DIR, 'systems.generated.ts', projectSystems());
+ artifact(PROJECT_DIR, 'seed.generated.ts', projectSeed());
});
});
diff --git a/tests/aot/generated/conformance/trace.json b/tests/aot/generated/conformance/trace.json
new file mode 100644
index 000000000..f20dec108
--- /dev/null
+++ b/tests/aot/generated/conformance/trace.json
@@ -0,0 +1,296 @@
+{
+ "delta": 0.016666666666666666,
+ "fields": [
+ "x",
+ "speed",
+ "bounces"
+ ],
+ "seed": [
+ [
+ 0,
+ 120,
+ 0
+ ],
+ [
+ 9.5,
+ 60,
+ 0
+ ],
+ [
+ -9.5,
+ -60,
+ 0
+ ],
+ [
+ 3,
+ -300,
+ 0
+ ]
+ ],
+ "frames": [
+ [
+ [
+ 2,
+ 120,
+ 0
+ ],
+ [
+ 10,
+ -60,
+ 1
+ ],
+ [
+ -10,
+ 60,
+ 1
+ ],
+ [
+ -2,
+ -300,
+ 0
+ ]
+ ],
+ [
+ [
+ 4,
+ 120,
+ 0
+ ],
+ [
+ 9,
+ -60,
+ 1
+ ],
+ [
+ -9,
+ 60,
+ 1
+ ],
+ [
+ -7,
+ -300,
+ 0
+ ]
+ ],
+ [
+ [
+ 6,
+ 120,
+ 0
+ ],
+ [
+ 8,
+ -60,
+ 1
+ ],
+ [
+ -8,
+ 60,
+ 1
+ ],
+ [
+ -10,
+ 300,
+ 1
+ ]
+ ],
+ [
+ [
+ 8,
+ 120,
+ 0
+ ],
+ [
+ 7,
+ -60,
+ 1
+ ],
+ [
+ -7,
+ 60,
+ 1
+ ],
+ [
+ -5,
+ 300,
+ 1
+ ]
+ ],
+ [
+ [
+ 10,
+ 120,
+ 0
+ ],
+ [
+ 6,
+ -60,
+ 1
+ ],
+ [
+ -6,
+ 60,
+ 1
+ ],
+ [
+ 0,
+ 300,
+ 1
+ ]
+ ],
+ [
+ [
+ 10,
+ -120,
+ 1
+ ],
+ [
+ 5,
+ -60,
+ 1
+ ],
+ [
+ -5,
+ 60,
+ 1
+ ],
+ [
+ 5,
+ 300,
+ 1
+ ]
+ ],
+ [
+ [
+ 8,
+ -120,
+ 1
+ ],
+ [
+ 4,
+ -60,
+ 1
+ ],
+ [
+ -4,
+ 60,
+ 1
+ ],
+ [
+ 10,
+ 300,
+ 1
+ ]
+ ],
+ [
+ [
+ 6,
+ -120,
+ 1
+ ],
+ [
+ 3,
+ -60,
+ 1
+ ],
+ [
+ -3,
+ 60,
+ 1
+ ],
+ [
+ 10,
+ -300,
+ 2
+ ]
+ ],
+ [
+ [
+ 4,
+ -120,
+ 1
+ ],
+ [
+ 2,
+ -60,
+ 1
+ ],
+ [
+ -2,
+ 60,
+ 1
+ ],
+ [
+ 5,
+ -300,
+ 2
+ ]
+ ],
+ [
+ [
+ 2,
+ -120,
+ 1
+ ],
+ [
+ 1,
+ -60,
+ 1
+ ],
+ [
+ -1,
+ 60,
+ 1
+ ],
+ [
+ 0,
+ -300,
+ 2
+ ]
+ ],
+ [
+ [
+ 0,
+ -120,
+ 1
+ ],
+ [
+ 0,
+ -60,
+ 1
+ ],
+ [
+ 0,
+ 60,
+ 1
+ ],
+ [
+ -5,
+ -300,
+ 2
+ ]
+ ],
+ [
+ [
+ -2,
+ -120,
+ 1
+ ],
+ [
+ -1,
+ -60,
+ 1
+ ],
+ [
+ 1,
+ 60,
+ 1
+ ],
+ [
+ -10,
+ -300,
+ 2
+ ]
+ ]
+ ]
+}
diff --git a/tools/lib/contractFacts.mjs b/tools/lib/contractFacts.mjs
index 9bc00432a..dc5b148f0 100644
--- a/tools/lib/contractFacts.mjs
+++ b/tools/lib/contractFacts.mjs
@@ -140,10 +140,14 @@ export const FACTS = [
'tests/aot/generated/conformance/systems_decl.c',
'tests/aot/generated/conformance/handshake.h',
'tests/aot/generated/conformance/trace.h',
+ 'tests/aot/generated/conformance/trace.json',
+ 'fixtures/aot-conformance/src/systems.generated.ts',
+ 'fixtures/aot-conformance/src/seed.generated.ts',
],
verification: [
{ path: 'sdk/tests/aot-conformance.test.ts', how: 'test', probe: /interpreted and compiled/ },
{ path: 'tests/aot/test_aot_conformance.cpp', how: 'test', probe: /after every frame/ },
+ { path: 'tools/verify-native-conformance.mjs', how: 'test', probe: /both roads answer the interpreter/ },
],
digest: { name: 'engine-abi', path: 'tests/aot/generated/conformance/handshake.h', probe: /ES_CONF_EXPECTED_CONTRACT_HASH/ },
},
diff --git a/tools/releaseGate.mjs b/tools/releaseGate.mjs
index b4f3f7c25..e70b518b9 100644
--- a/tools/releaseGate.mjs
+++ b/tools/releaseGate.mjs
@@ -110,6 +110,19 @@ export const CRITERIA = [
'sdk/src/ecs/aot/installNativeAot.ts',
],
},
+ {
+ id: 'every-road-answers-the-same-world',
+ says: 'one source, run four ways, leaves the same world after every frame',
+ // Dispatching is not COMPUTING: the criterion above asks whether a packaged
+ // game REACHES a compiled system. A road that quietly fell back agrees with
+ // any trace, so the run must say a system was taken before agreement counts.
+ answeredBy: 'node tools/verify-native-conformance.mjs',
+ needs: [
+ 'tools/verify-native-conformance.mjs',
+ 'sdk/tests/fixtures/conformance-systems.ts',
+ 'tests/aot/test_aot_conformance.cpp',
+ ],
+ },
{
id: 'a-web-game-runs-its-systems-as-machine-code',
says: 'an exported web game loads its compiled systems and dispatches to them',
diff --git a/tools/verify-native-conformance.mjs b/tools/verify-native-conformance.mjs
new file mode 100644
index 000000000..b479ee2b9
--- /dev/null
+++ b/tools/verify-native-conformance.mjs
@@ -0,0 +1,186 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file verify-native-conformance.mjs — the native host answers the interpreter.
+ *
+ * The suite compares closures against a wasm module, and `test_aot_conformance`
+ * compares the emitted C against the same answer. Both run in a test process.
+ * Neither says what a PLAYER gets: a packaged game, on the host that embeds
+ * QuickJS and the engine, stepping frames the way a frame is stepped.
+ *
+ * So the fixture ships as a project and runs twice on this machine's runtime
+ * template — interpreted, and with its systems compiled — printing what the two
+ * systems left after every frame. Both roads are held against the trace the
+ * interpreter recorded in the suite: same source, same seeds, same delta, three
+ * executors and now a fourth.
+ *
+ * The two false greens are guarded rather than assumed. A compiled road that
+ * quietly fell back to the interpreter agrees with the trace perfectly, so the
+ * run has to SAY a system was dispatched to; and an interpreted road that
+ * dispatched to one would not be the twin it claims to be.
+ *
+ * node tools/verify-native-conformance.mjs
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { installedTemplateDir } from '../build-tools/utils/nativeTemplate.js';
+import { desktopExecutableIn } from '../build-tools/utils/desktopApp.js';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const PROJECT = path.join(ROOT, 'fixtures', 'aot-conformance');
+const TRACE = path.join(ROOT, 'tests', 'aot', 'generated', 'conformance', 'trace.json');
+
+/** Frames to run past the ones compared: a host is free to spend its first on
+ * boot, and a road that only agrees for as long as it is watched is a road
+ * that diverges on frame 13. */
+const EXTRA_FRAMES = 8;
+
+const version = JSON.parse(readFileSync(path.join(ROOT, 'package.json'), 'utf8')).version;
+// The template vocabulary, which is the OS a desktop app is BUILT as.
+const os = process.platform === 'darwin' ? 'macos'
+ : process.platform === 'win32' ? 'windows' : 'linux';
+
+const template = installedTemplateDir(version, os);
+if (!template || !existsSync(template)) {
+ // 2, not 0: a machine that cannot answer has not answered, and a criterion
+ // that reads as met on every runner without a template says nothing anywhere.
+ console.log(`native conformance: no ${os} runtime template for v${version} — did NOT run.`);
+ console.log(` build one with: node build-tools/cli.js native --target ${os}`);
+ process.exit(2);
+}
+if (!existsSync(TRACE)) {
+ console.log('native conformance: no interpreter trace — did NOT run.');
+ console.log(' record one with: ESTELLA_AOT_WRITE=1 pnpm --filter @estella/sdk test aot-conformance');
+ process.exit(2);
+}
+
+const want = JSON.parse(readFileSync(TRACE, 'utf8'));
+const FRAMES = want.frames.length;
+
+/** Export the fixture and run it, or `null` where this machine cannot compile. */
+function play(compiled) {
+ const out = mkdtempSync(path.join(tmpdir(), 'estella-conf-native-'));
+ try {
+ const args = [
+ path.join(ROOT, 'pipeline', 'bin', 'estella.mjs'), 'export', PROJECT,
+ '--platform', 'desktop', '--out', out, '--template', template,
+ ];
+ if (!compiled) args.push('--no-aot');
+ const exported = spawnSync(process.execPath, args, { encoding: 'utf8', cwd: ROOT });
+ if (exported.status !== 0) {
+ const said = `${exported.stdout ?? ''}${exported.stderr ?? ''}`;
+ // A machine with no host C compiler cannot build the compiled road. That
+ // is a missing toolchain, not a disagreement.
+ if (compiled && /no C compiler/.test(said)) return null;
+ fail('the export failed', said.trim().slice(-600));
+ }
+
+ const exe = desktopExecutableIn(out, os);
+ if (exe === null) fail(`the export assembled no app under ${out}`);
+
+ const run = spawnSync(exe, [], {
+ encoding: 'utf8',
+ cwd: path.dirname(exe),
+ env: {
+ ...process.env,
+ // The host's own fixed-delta loop, which is what makes two runs on two
+ // roads comparable at all. No warmup: frame 0 is one of the answers.
+ ESTELLA_BENCH_FRAMES: String(FRAMES + EXTRA_FRAMES),
+ ESTELLA_BENCH_WARMUP: '0',
+ ESTELLA_BENCH_DT: String(want.delta),
+ ESTELLA_BENCH_QUIT: '1',
+ ESTELLA_BENCH_LABEL: compiled ? 'conformance-aot' : 'conformance-interpreted',
+ },
+ });
+ return { log: `${run.stdout ?? ''}${run.stderr ?? ''}`, status: run.status };
+ } finally {
+ rmSync(out, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });
+ }
+}
+
+/** `CONF <frame> <delta> <rows>` — what the fixture's own reporting system says. */
+function framesIn(log) {
+ const out = [];
+ for (const line of log.split('\n')) {
+ const m = /CONF (\d+) (\S+) (\[.*\])\s*$/.exec(line);
+ if (m !== null) out.push({ at: Number(m[1]), delta: Number(m[2]), rows: JSON.parse(m[3]) });
+ }
+ return out;
+}
+
+function fail(what, detail) {
+ console.error(`✗ native conformance: ${what}`);
+ if (detail) console.error(detail.split('\n').map((l) => ` ${l}`).join('\n'));
+ process.exit(1);
+}
+
+/** Every field of every row, in the order the trace records them. */
+function compare(road, got) {
+ if (got.length < FRAMES) {
+ fail(`${road} reported ${got.length} frame(s), and the trace has ${FRAMES}`,
+ got.length === 0 ? 'the fixture printed nothing — did its reporting system run?' : '');
+ }
+ for (let f = 0; f < FRAMES; f++) {
+ const frame = got[f];
+ if (frame.at !== f) fail(`${road} skipped a frame: expected ${f}, got ${frame.at}`);
+ // A road that stepped by another delta is a different finding from one that
+ // computed the step wrong, and saying which is the point of printing it.
+ if (frame.delta !== want.delta) {
+ fail(`${road} stepped frame ${f} by ${frame.delta}, and the trace was recorded at ${want.delta}`);
+ }
+ const wantRows = want.frames[f];
+ if (frame.rows.length !== wantRows.length) {
+ fail(`${road} has ${frame.rows.length} row(s) at frame ${f}, and the trace has ${wantRows.length}`);
+ }
+ for (let i = 0; i < wantRows.length; i++) {
+ for (let k = 0; k < wantRows[i].length; k++) {
+ if (frame.rows[i][k] !== wantRows[i][k]) {
+ fail(`${road} disagrees at frame ${f}, entity ${i}, ${want.fields[k]}`,
+ `interpreter ${wantRows[i][k]}\nhost ${frame.rows[i][k]}`);
+ }
+ }
+ }
+ }
+}
+
+const RUNNING = /AOT: (\w+) is running compiled/;
+const RUNNING_ALL = /AOT: (\w+) is running compiled/g;
+const INSTALLED = /AOT: (\d+) compiled system\(s\) installed/;
+
+const interpreted = play(false);
+if (interpreted === null) fail('the interpreted export could not be built');
+compare('the interpreted host', framesIn(interpreted.log));
+// The twin has to be a twin: a road dispatching to a compiled system is not the
+// interpreter, and comparing it against the trace would prove the wrong thing.
+if (RUNNING.test(interpreted.log)) {
+ fail('the --no-aot build dispatched to a compiled system — it is not the interpreted road');
+}
+
+const compiled = play(true);
+if (compiled === null) {
+ console.log('✓ native conformance: the interpreted host answers the interpreter, '
+ + `frame for frame (${FRAMES} frames).`);
+ console.log(' the compiled road did NOT run: this machine has no host C compiler.');
+ process.exit(2);
+}
+compare('the compiled host', framesIn(compiled.log));
+// Installed is not running, and a fallback is silent by design: the closure that
+// would have run produces the same numbers, so the trace alone cannot see it.
+const ran = new Set([...compiled.log.matchAll(RUNNING_ALL)].map((m) => m[1]));
+if (ran.size === 0) fail('no system was ever dispatched to as compiled — the run proves nothing');
+// And EVERY system that installed has to be one of them. One twin taken and one
+// quietly interpreted matches the trace exactly, because the fallback is right.
+const installed = INSTALLED.exec(compiled.log);
+if (installed === null) fail('the run never said how many systems installed');
+if (ran.size !== Number(installed[1])) {
+ fail(`${installed[1]} system(s) installed and ${ran.size} were dispatched to`,
+ `compiled: ${[...ran].join(', ') || '(none)'}`);
+}
+
+console.log(`✓ native conformance: both roads answer the interpreter, frame for frame `
+ + `(${FRAMES} frames, ${want.frames[0].length} entities).`);
+console.log(` interpreted, and every one of ${installed[1]} compiled system(s) dispatched to `
+ + `on the packaged host: ${[...ran].join(', ')}.`);