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.

fix(bindings): a binding says what it is for, and the census holds both answers

esengined2ad0ff2764f
diff --git a/sdk/tests/binding-surface.test.ts b/sdk/tests/binding-surface.test.ts
index 11dc207df..84bf11056 100644
--- a/sdk/tests/binding-surface.test.ts
+++ b/sdk/tests/binding-surface.test.ts
@@ -33,6 +33,10 @@
import { describe, it, expect } from 'vitest';
import { readFileSync, existsSync } from 'node:fs';
import { resolve } from 'node:path';
+import {
+ DISPOSITIONS, TEST_PROBE_BINDINGS, PROBE_GUARD, PROBE_HEADER,
+ type TestProbeBinding,
+} from '../../tools/bindingDispositions.mjs';
const CPP = resolve(__dirname, '../../src/esengine');
const SDK = resolve(__dirname, '../src');
@@ -55,6 +59,21 @@ function stripComments(src: string): string {
// C++ side: emscripten registration parsing
// =============================================================================
+/**
+ * Registration names inside `#ifdef <macro>` … `#endif` blocks. What keeps a
+ * probe out of a release build is the guard, so a census row claiming one is
+ * checked against the preprocessor rather than against its own say-so.
+ */
+function parseGuardedRegistrations(cppSource: string, macro: string): Set<string> {
+ const src = stripComments(cppSource);
+ const out = new Set<string>();
+ const re = new RegExp(`#if(?:def)?\\s+${macro}\\b([\\s\\S]*?)#endif`, 'g');
+ for (let m = re.exec(src); m; m = re.exec(src)) {
+ for (const name of parseFunctionRegistrations(m[1])) out.add(name);
+ }
+ return out;
+}
+
/** All `emscripten::function("name", ...)` registration names in a file. */
function parseFunctionRegistrations(cppSource: string): Set<string> {
const out = new Set<string>();
@@ -282,6 +301,10 @@ const allDeclared = new Set([...moduleDeclared, ...tilemapDeclared]);
// Emscripten-runtime exports declared for ergonomics; not embind registrations.
const RUNTIME_EXPORTS = new Set(['_malloc', '_free']);
+/** The census: which registrations are deliberately not production. */
+const probeDeclared = new Set<string>(TEST_PROBE_BINDINGS.map((b: TestProbeBinding) => b.id));
+const probeGuarded = parseGuardedRegistrations(webSdkEntry, PROBE_GUARD);
+
describe('WASM binding surface: module functions (hand-written mirror handshake)', () => {
it('every TS-declared ESEngineModule function is a real registration (no phantom decls)', () => {
const phantom = missingFrom(
@@ -302,8 +325,50 @@ describe('WASM binding surface: module functions (hand-written mirror handshake)
});
it('every hand-registered binding is declared in the TS surface (no unmirrored bindings)', () => {
- const unmirrored = missingFrom(handRegistered, allDeclared);
- expect(unmirrored, `registered in WebSDKEntry/TilemapBindings but declared in no TS interface: ${unmirrored.join(', ')}`)
+ // Minus the ones a census declares are not production. `production` is the
+ // default, so an unlisted binding is still held to the strict rule.
+ const production = [...handRegistered].filter((n) => !probeDeclared.has(n));
+ const unmirrored = missingFrom(production, allDeclared);
+ expect(unmirrored, `registered in WebSDKEntry/TilemapBindings but declared in no TS interface`
+ + ` (and not declared a test-probe in tools/bindingDispositions.mjs): ${unmirrored.join(', ')}`)
+ .toEqual([]);
+ });
+
+ it('a test-probe binding stays OUT of the production TS surface', () => {
+ const leaked = [...probeDeclared].filter((n) => allDeclared.has(n));
+ expect(leaked, `declared test-probe in tools/bindingDispositions.mjs but present in the`
+ + ` shipping TS surface, which is a release ABI: ${leaked.join(', ')}`)
+ .toEqual([]);
+ });
+
+ it('a test-probe binding is registered behind the probe guard', () => {
+ const unguarded = [...probeDeclared].filter((n) => !probeGuarded.has(n));
+ expect(unguarded, `declared test-probe but registered outside #ifdef ${PROBE_GUARD},`
+ + ` so a release build would export it: ${unguarded.join(', ')}`)
+ .toEqual([]);
+ });
+
+ it('a test-probe binding is declared in the probe-only header', () => {
+ const probeHeader = read(resolve(CPP, PROBE_HEADER));
+ const misplaced = [...probeDeclared].filter((n) => !new RegExp(`\\b${n}\\s*\\(`).test(probeHeader));
+ expect(misplaced, `declared test-probe but not declared in ${PROBE_HEADER} — the header`
+ + ` tool reads the shipping ones and does not read #ifdef: ${misplaced.join(', ')}`)
+ .toEqual([]);
+ });
+
+ it('every declared test-probe still exists (no stale disposition)', () => {
+ const gone = [...probeDeclared].filter((n) => !handRegistered.has(n));
+ expect(gone, `declared test-probe in tools/bindingDispositions.mjs but registered nowhere;`
+ + ` a disposition outliving its binding reads as an answered question: ${gone.join(', ')}`)
+ .toEqual([]);
+ });
+
+ it('every disposition class the census uses is one this contract defines', () => {
+ const classes = Object.keys(DISPOSITIONS);
+ expect(classes, 'the census must define production and test-probe')
+ .toEqual(expect.arrayContaining(['production', 'test-probe']));
+ const unexplained = TEST_PROBE_BINDINGS.filter((b: TestProbeBinding) => !b.why);
+ expect(unexplained.map((b: TestProbeBinding) => b.id), 'a test-probe row owes a `why`')
.toEqual([]);
});
});
diff --git a/tools/bindingDispositions.d.mts b/tools/bindingDispositions.d.mts
new file mode 100644
index 000000000..7d5f2ce5d
--- /dev/null
+++ b/tools/bindingDispositions.d.mts
@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/** Types for bindingDispositions.mjs, which the SDK's binding handshake reads. */
+
+export declare const PROBE_GUARD: string;
+export declare const PROBE_HEADER: string;
+
+export interface BindingDisposition {
+ inProductionSurface: boolean;
+ means: string;
+}
+
+export declare const DISPOSITIONS: Record<string, BindingDisposition>;
+
+export interface TestProbeBinding {
+ id: string;
+ why: string;
+}
+
+export declare const TEST_PROBE_BINDINGS: TestProbeBinding[];
diff --git a/tools/bindingDispositions.mjs b/tools/bindingDispositions.mjs
new file mode 100644
index 000000000..f399b58e7
--- /dev/null
+++ b/tools/bindingDispositions.mjs
@@ -0,0 +1,65 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file bindingDispositions.mjs — what each hand-registered wasm binding is FOR.
+ *
+ * Two gates were each right and together impossible to satisfy. The binding
+ * handshake says every `emscripten::function` registration must be mirrored by a
+ * declaration in the production TS surface; the test-probe rule says an adapter
+ * that exists only to be measured must never reach a release ABI. A binding that
+ * is both — registered, and deliberately absent from `ESEngineModule` — had no
+ * legal shape, and the handshake simply failed.
+ *
+ * The census that resolves it is not a list of excused names. It is a class per
+ * binding, and each class owes obligations a gate can check:
+ *
+ * production must be declared in the production TS surface
+ * test-probe must NOT be; must be registered behind the probe guard, and
+ * must be declared in the probe-only header
+ *
+ * `production` is the DEFAULT, so nothing has to be listed to be held to the
+ * strict rule and a new binding cannot slip in unmirrored. Only the exception
+ * is enumerated, which is what keeps this from becoming a list of things
+ * somebody once wanted to stop failing.
+ */
+
+/** The guard a probe-only registration must sit behind, and the header its
+ * declaration must live in — both are what keep it out of a release build. */
+export const PROBE_GUARD = 'ES_ENABLE_TEST_PROBES';
+export const PROBE_HEADER = 'bindings/TestProbeBindings.hpp';
+
+export const DISPOSITIONS = {
+ production: {
+ inProductionSurface: true,
+ means: 'a capability the shipping SDK calls; the TS surface is its contract',
+ },
+ 'test-probe': {
+ inProductionSurface: false,
+ means: 'an adapter that exists to be measured or cross-checked, never shipped',
+ },
+};
+
+/**
+ * Every binding that is NOT production, and why.
+ *
+ * `why` is owed: a class alone is a label, and the sentence beside it says what
+ * a later reader checks it against — above all whether the thing it measures has
+ * acquired a production consumer, the moment a probe should stop being one.
+ */
+export const TEST_PROBE_BINDINGS = [
+ {
+ id: 'engine_prewarmMeshVariants',
+ why: 'the EQUIVALENCE oracle: it derives program requirements from live ECS'
+ + ' entities so a test can check them against what the prepared document'
+ + ' derived. Production never has entities at that moment — the whole point'
+ + ' of preparing a cell is that it is readied before it has any — so this'
+ + ' side exists only to be the independent judge of the other.',
+ },
+ {
+ id: 'engine_prewarmMeshVariantsFromDocument',
+ why: 'the document-side derivation, still probe-only while the residency'
+ + ' lifecycle calls it from nowhere. It is the half with a production'
+ + ' consumer coming, so when preparation starts requiring a readiness'
+ + ' stamp this row is what has to be removed rather than amended.',
+ },
+];