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.

test(spine): the five lifetime invariants, frozen with what proves each

esenginea9b16145e61d
diff --git a/tools/check-spine-lifetimes.mjs b/tools/check-spine-lifetimes.mjs
new file mode 100644
index 000000000..575ac483c
--- /dev/null
+++ b/tools/check-spine-lifetimes.mjs
@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file check-spine-lifetimes.mjs — the five spine lifetime invariants, frozen.
+ *
+ * Spine spent four cuts becoming one lifetime model instead of two: an era owns
+ * what its preparation acquired, a native skeleton retains the era it was parsed
+ * from, and a manager owns which runtime poses an entity. What each of those
+ * replaced was a PROTOCOL — "tear the entities down before the scene gives its
+ * assets back", "the ref is close enough to name a generation" — and a protocol
+ * is exactly what comes back silently.
+ *
+ * So each invariant is declared here with two things behind it: the judgment
+ * that proves it, and where one is cheap, the shape a regression would take. A
+ * change to any of them is allowed — with a counterexample, which means editing
+ * this file and the judgment it names, not letting either quietly stop meaning
+ * what it says.
+ *
+ * node tools/check-spine-lifetimes.mjs
+ */
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const read = (rel) => readFileSync(path.join(ROOT, rel), 'utf8');
+const RUNTIME = 'sdk/src/spine/SpineRuntime.ts';
+const MANAGER = 'sdk/src/spine/SpineManager.ts';
+const SRC = 'sdk/src';
+const TESTS = 'sdk/tests';
+
+const missing = [RUNTIME, MANAGER].filter((f) => !existsSync(path.join(ROOT, f)));
+if (missing.length) {
+ console.error(`check-spine-lifetimes is stale: ${missing.join(', ')} does not exist.`);
+ process.exit(1);
+}
+
+/** Comments out, so a rule reads code and not the prose describing it. */
+const strip = (text) => text
+ .replace(/\/\*[\s\S]*?\*\//g, '')
+ .replace(/\/\/[^\n]*/g, '');
+
+/** Every `it(...)`/`test(...)` title in the SDK's tests. A judgment named by an
+ * invariant below has to be one of these. */
+function judgments() {
+ const titles = new Set();
+ for (const file of readdirSync(path.join(ROOT, TESTS))) {
+ if (!file.endsWith('.test.ts')) continue;
+ const text = readFileSync(path.join(ROOT, TESTS, file), 'utf8');
+ for (const m of text.matchAll(/\b(?:it|test)\(\s*(['"`])((?:\\.|(?!\1).)*)\1/g)) {
+ titles.add(m[2].replace(/\\'/g, "'"));
+ }
+ }
+ return titles;
+}
+
+/** Files under sdk/src that name SpineRuntime, other than itself. */
+function runtimeHolders() {
+ const found = [];
+ const walk = (dir) => {
+ for (const entry of readdirSync(path.join(ROOT, dir), { withFileTypes: true })) {
+ const rel = `${dir}/${entry.name}`;
+ if (entry.isDirectory()) walk(rel);
+ else if (entry.name.endsWith('.ts') && rel !== RUNTIME) {
+ if (/\bSpineRuntime\b/.test(strip(read(rel)))) found.push(rel);
+ }
+ }
+ };
+ walk(SRC);
+ return found;
+}
+
+const runtime = strip(read(RUNTIME));
+const manager = strip(read(MANAGER));
+
+/**
+ * The five. `proof` is the judgment that fails when the invariant does; `holds`
+ * is the structural half, where a regression has a shape a reader can grep for.
+ */
+const INVARIANTS = [
+ {
+ rule: 'A native residency retains exactly the era it was derived from — never a fresh acquire by name, which after an invalidate resolves to another generation.',
+ proof: 'the scene giving its receipt back does not take the page being posed',
+ holds: () => (
+ !/\bacquire[A-Z]\w*\s*\(/.test(runtime)
+ ? /era\.retain\s*\(/.test(runtime)
+ ? null
+ : `${RUNTIME} no longer retains the era it parses from`
+ : `${RUNTIME} acquires an asset by name; a runtime must retain the exact era it was handed`
+ ),
+ },
+ {
+ rule: 'One residency owns one era retain, whatever the entity count — the refcount already knows when the native object is unneeded.',
+ proof: 'one claim per residency, however many entities share it',
+ holds: () => (/interface SkeletonResidency[\s\S]*?claim: SpineEraClaim/.test(runtime)
+ ? null
+ : `${RUNTIME}: the claim is no longer part of a residency`),
+ },
+ {
+ rule: 'An era binding is indivisible: id, value and the right to keep it alive travel together, so no caller can pair one generation\'s identity with another\'s bytes.',
+ proof: 'the same skeleton with another atlas is another asset',
+ holds: () => (/loadEntity\s*\(\s*entity: Entity,\s*era: SpineEraBinding\s*\)/.test(runtime)
+ ? null
+ : `${RUNTIME}.loadEntity no longer takes one indivisible era binding`),
+ },
+ {
+ rule: 'Rebinding an entity is commit-after-success: the candidate exists before what it replaces is retired.',
+ proof: 'a reload whose skeleton will not parse leaves the entity playing',
+ holds: () => {
+ const body = runtime.slice(runtime.indexOf('loadEntity('), runtime.indexOf('claimSkeleton_(era: SpineEraBinding)'));
+ const created = body.indexOf('createInstance(');
+ const retired = body.indexOf('this.removeEntity(entity)');
+ return created >= 0 && retired > created
+ ? null
+ : `${RUNTIME}.loadEntity retires the old binding before the new one exists`;
+ },
+ },
+ {
+ rule: 'SpineManager is the sole authority for which runtime poses an entity: a runtime can only see its own entities, so nothing else may hold one.',
+ proof: 'moving to another spine version leaves nothing behind in the old one',
+ holds: () => {
+ const holders = runtimeHolders().filter((f) => f !== MANAGER && !f.endsWith('/index.ts'));
+ return holders.length === 0
+ ? null
+ : `${holders.join(', ')} holds a SpineRuntime; entity binding is the manager's`;
+ },
+ },
+];
+
+const titles = judgments();
+if (titles.size < 100) {
+ console.error(`check-spine-lifetimes: found only ${titles.size} judgment title(s) — the parser no longer matches how they are written.`);
+ process.exit(1);
+}
+
+const findings = [];
+for (const { rule, proof, holds } of INVARIANTS) {
+ if (!titles.has(proof)) {
+ findings.push(`no judgment named "${proof}" — the invariant it proves is:\n ${rule}`);
+ }
+ const broken = holds();
+ if (broken) findings.push(`${broken}\n the invariant: ${rule}`);
+}
+
+if (findings.length === 0) {
+ console.log(`check-spine-lifetimes: ${INVARIANTS.length} frozen invariant(s), each with the judgment that proves it and the shape a regression would take.`);
+ process.exit(0);
+}
+for (const f of findings) console.error(f);
+console.error('\nChanging one of these is allowed — with a counterexample. Edit this file and the judgment it names.');
+process.exit(1);
diff --git a/tools/gates.mjs b/tools/gates.mjs
index e5fc78031..70780c077 100644
--- a/tools/gates.mjs
+++ b/tools/gates.mjs
@@ -118,6 +118,9 @@ export const GATES = [
// asset cache, an ownerless texture, an "active runtime" pointer, and
// World-local state on a plugin object several Apps share.
{ id: 'tilemap-realm', run: 'node tools/check-tilemap-realm.mjs' },
+ // The five spine lifetime invariants, each with the judgment that proves it:
+ // what they replaced were teardown protocols, and a protocol comes back quietly.
+ { id: 'spine-lifetimes', run: 'node tools/check-spine-lifetimes.mjs' },
// …and that each of them can be reached on a device, where the registry is
// assembled from ptr accessors rather than from embind.
{ id: 'native-components', run: 'node tools/check-native-components.mjs' },