A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
test(aot): the Changed a compiled system owes, on both compiled roads
esengine47281b43ad86
diff --git a/docs/MUTATION_CONTRACT.md b/docs/MUTATION_CONTRACT.mdindex 4ea15eacd..c0f9c81dc 100644--- a/docs/MUTATION_CONTRACT.md+++ b/docs/MUTATION_CONTRACT.md@@ -142,6 +142,39 @@ shadow scan 看得见,ChangeTracker 看不见。** 只要还有一条这样的`mutation-census` 已升级成门禁(`--gate`,注册为 `silent-writes`):**静默写恒为 0**。它对扫不到的 root(未检出的编辑器子模块)明说而不是静默缩小语料。+## 3.6 PR6c.4:`Mut → Changed` 在三条执行路上都成立++这一节没有新建判据——证据早就在仓库里,只是没人认领它证明了什么。++| `Query(Mut(C))` | 值 | Changed |+|---|---|---|+| JS 解释执行 | ✓ | ✓ |+| Web AOT(编译进 wasm) | ✓ | ✓ |+| Native AOT(打包宿主) | ✓ | ✓ |++两条编译路各有**独立的实现权威**,所以各有独立的证据,不能互相背书:++- **Web**:`sdk/tests/aot-conformance.test.ts` 是真编译(compiler → C → `emcc` → wasm),+ 末尾挂一个解释执行的 `Query(Changed(Mover))` watcher,逐帧比较两条路的 `ticks`,+ 并断言 `ticks.some(n => n > 0)`(watcher 匹配不到任何东西时两条路也会一致)。+ 实现在 `AotDispatch.markChanged_`,按 packed rows 标记。+- **Native**:`tools/verify-native-conformance.mjs` 把打包宿主 `CONF` 行里的 `ticked` 列+ 与解释器写下的 `trace.json.ticks` 逐帧比较。实现是**另一个** `markChanged_`+ (`installNativeAot.ts`),它在 native call 返回后重新查询匹配实体,而不是回传 packed rows。++**两次 sabotage 都做过**:分别删掉两个 `markChanged_` 调用,两条 conformance 各自变红,+且都红在 `ticks`(frame 1:0 vs 4),而值与资源的比较仍然相等——+证明这条 conformance 确实由变更观测这一职责撑住,且这个职责**在 world 的值里看不见**。++契约是「**只有声明为 `Mut` 的 projection 产生观测**」,不是「AOT 跑过的都变 dirty」。+两条 AOT 路都从同一份 manifest 声明里取 mutated 集合,而这条规则钉在+`sdk/tests/query.test.ts` 的 `Query(Mut(A), B)` → A Changed / B not。++**顺带修掉一个假绿机器**:runtime template **内嵌 SDK 的 QuickJS 字节码**,所以改了 SDK 却不+重建 template,native conformance 就在对着旧引擎报绿——sabotage 第一次跑正是这样通过的。+判据现在先查 `sdk/src → sdk/dist → template` 这条链,陈旧就报 `did NOT run`(exit 2)。+(`.generated.ts` 不计入,原生构建会在打包之后重写它们。)+## 4. 待裁定普查给出的结论是明确的:**`get`/`tryGet`/裸 `Query` 必须收成只读**,而且必须是@@ -154,9 +187,7 @@ shadow scan 看得见,ChangeTracker 看不见。** 只要还有一条这样的同时未判定、留给后续的两件:-- **AOT 写回**:`AotDispatch.markChanged_` 按 `q.mutated`(即声明了 `Mut` 的组件)逐行标记,- 语义上与 `Mut` 一致。但本轮 fixture 没有覆盖它——跑它需要编译产物,- 留作 conformance 那条线的一格,**不计入本文的「已实测」**。+- ~~**AOT 写回**~~:已实测,见 3.6。- **`cleanRemovedBuffer` 的归属权**:它是全局 destructive cleanup,而每个`RemovedQueryInstance` 各自持有 `lastRunTick`。复制层若替所有 `Removed()` 消费者删历史,会让 frontier 落后的消费者永久错过那段 removal。这是正确性契约而不是内存优化,diff --git a/sdk/tests/query.test.ts b/sdk/tests/query.test.tsindex 01d88d1df..1ef3c0906 100644--- a/sdk/tests/query.test.ts+++ b/sdk/tests/query.test.ts@@ -179,6 +179,24 @@ describe('Query System', () => {expect(updated.x).toBe(3);expect(updated.y).toBe(3);});++ // The contract is not "a query that ran dirties what it touched" — it is+ // that only a Mut projection reports. The AOT roads mark from the same+ // declaration, so this is where that rule is pinned.+ it('reports the Mut component and not the read-only one beside it', () => {+ const e1 = world.spawn();+ world.insert(e1, Position, { x: 1, y: 1 });+ world.insert(e1, Velocity, { dx: 2, dy: 2 });+ world.enableChangeTracking(Position);+ world.enableChangeTracking(Velocity);+ world.advanceTick();+ const since = world.getWorldTick() - 1;++ new QueryInstance(world, Query(Mut(Position), Velocity)).forEach(() => { /* reads */ });++ expect(world.isChangedSince(e1, Position, since)).toBe(true);+ expect(world.isChangedSince(e1, Velocity, since)).toBe(false);+ });});describe('complex queries', () => {diff --git a/tools/verify-native-conformance.mjs b/tools/verify-native-conformance.mjsindex 4a334c242..2bef3f29c 100644--- a/tools/verify-native-conformance.mjs+++ b/tools/verify-native-conformance.mjs@@ -22,7 +22,7 @@* node tools/verify-native-conformance.mjs*/import { spawnSync } from 'node:child_process';-import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';+import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync } from 'node:fs';import { tmpdir } from 'node:os';import path from 'node:path';import { fileURLToPath } from 'node:url';@@ -51,6 +51,41 @@ if (!template || !existsSync(template)) {console.log(` build one with: node build-tools/cli.js native --target ${os}`);process.exit(2);}+/**+ * The newest hand-written .ts under `dir`, in epoch ms. `.generated.ts` is+ * excluded: the native build rewrites those AFTER bundling, so counting them+ * would report every fresh template as stale.+ */+function newestSource(dir) {+ let newest = 0;+ for (const entry of readdirSync(dir, { withFileTypes: true })) {+ if (entry.name === 'node_modules' || entry.name === 'dist') continue;+ const full = path.join(dir, entry.name);+ newest = Math.max(newest, entry.isDirectory() ? newestSource(full)+ : entry.name.endsWith('.ts') && !entry.name.endsWith('.generated.ts')+ ? statSync(full).mtimeMs : 0);+ }+ return newest;+}++// The template EMBEDS the SDK as QuickJS bytecode, so a template built before an+// SDK edit runs the previous engine and answers for it — green on a defect the+// run was started to find. Exactly that happened while sabotaging markChanged_.+const bytecode = path.join(template, 'esengine.native.qjsbc');+const bundle = path.join(ROOT, 'sdk', 'dist', 'index.native.bundled.js');+const stale = !existsSync(bytecode) || !existsSync(bundle) ? null+ : newestSource(path.join(ROOT, 'sdk', 'src')) > statSync(bundle).mtimeMs+ ? { why: 'sdk/dist is older than sdk/src', fix: 'pnpm --filter ./sdk build' }+ : statSync(bundle).mtimeMs > statSync(bytecode).mtimeMs+ ? { why: `the ${os} template embeds an older SDK than sdk/dist`,+ fix: `node build-tools/cli.js native --target ${os}` }+ : null;+if (stale) {+ console.log(`native conformance: ${stale.why} — did NOT run.`);+ console.log(` ${stale.fix}`);+ 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');