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.

chore(ecs): what writes through a read handle, counted before it is forbidden

esenginebddcaa7a17be
diff --git a/docs/MUTATION_CONTRACT.md b/docs/MUTATION_CONTRACT.md
new file mode 100644
index 000000000..d5ab3731c
--- /dev/null
+++ b/docs/MUTATION_CONTRACT.md
@@ -0,0 +1,130 @@
+# 变更观测契约(Mutation Observation Contract)
+
+> 目标读者:引擎维护者 / AI 协作代理。
+> 本文记录 **PR6c 第一刀的普查结果**:引擎当前允许哪些写法改变 World、其中哪些
+> ChangeTracker 观测得到、以及把读接口收紧成只读要付多少迁移成本。
+> 本文**不改任何实现**,它是拍板前的证据。
+
+## 0. 问题
+
+`bench/replication-dirty/` 的四臂实验(PR6b)在性能上给了 N1 一个可用的答案,但它的
+completeness probe 顺手证伪了一个前提:**合法代码拿到脚本组件的 live reference 后原地写,
+shadow scan 看得见,ChangeTracker 看不见。** 只要还有一条这样的路径,ChangeTracker 就不能
+充当权威的 candidate 来源——那部分状态会直接停止复制,而且没有任何地方会说一声。
+
+所以在测 crossover 之前,先要回答的是**语义**问题,而不是性能问题:
+
+> 引擎的「读」接口和「写」接口,边界到底在哪?
+
+## 1. 两台机器
+
+| 机器 | 问什么 | 怎么跑 |
+|---|---|---|
+| `tools/mutation-contract.mjs` | 每条访问路径**实际上**做了什么:值真的变了吗?tracker 看到了吗? | `node tools/mutation-contract.mjs` |
+| `tools/mutation-census.mjs` | 这个仓库**实际上**有多少代码在通过读句柄写 | `node tools/mutation-census.mjs` |
+
+两台都对自己做过标定:
+
+- contract fixture 被**三次 sabotage 验证**过:让 `tryGet` 返回拷贝、让 `tryGet` 记 changed、
+ 让 `Mut` 写回不再报告——每次都只红在它守的那几行,撤掉即回绿。
+ 第二次 sabotage 顺带暴露了 fixture 自己的一个洞:`snapshot()` 经由 `tryGet` 读,而它排在
+ observed 计算之前,读若有副作用就会污染判决。已改成先问 observed 再取快照。
+- census 有 `--self-test`:它声称能识别的每种形态都写成正样本并断言命中数,
+ 所以「零发现」永远不可能被误读成「仓库很干净」。标定过程中抓到过它自己两个缺陷:
+ `Object.assign` 被同时记成 write 和 escape;以及 **alias 链上的写回没被识别**
+ (`const p = t.position; p.x = 1; world.set(e, T, t)` 被误判为静默写——
+ multiplayer-arena 的移动函数正是这个形状)。
+
+## 2. 运行时契约:18 条路径的实测
+
+`node tools/mutation-contract.mjs`,wasm 与 SDK 均为当前 HEAD 构建:
+
+| 访问路径 | 值真的变了 | tracker 看到 | 判定 |
+|---|---|---|---|
+| `world.set` / `insert` / `remove` | 是 | 是 | 已报告 |
+| `world.set`(嵌套 shape / builtin) | 是 | 是 | 已报告 |
+| `world.markChanged` | 否 | 是 | 已报告 |
+| `Query(Mut(C))` 写回(脚本 / builtin) | 是 | 是 | 已报告 |
+| `world.get(e,C).f = v`(脚本) | **是** | **否** | **静默写** |
+| `world.tryGet(e,C).f = v`(脚本) | **是** | **否** | **静默写** |
+| `world.get/tryGet(e,C).nested.x = v`(脚本) | **是** | **否** | **静默写** |
+| 裸 `Query(C)` 行写入(脚本,两种 shape) | **是** | **否** | **静默写** |
+| 句柄跨 tick 持有后再写 | **是** | **否** | **静默写** |
+| `world.get/tryGet(e,C).nested.x = v`(builtin) | 否 | 否 | 惰性(写被丢弃) |
+| 裸 `Query(C)` 行写入(builtin) | 否 | 否 | 惰性(写被丢弃) |
+
+**18 条路径,7 条是静默写。**
+
+三个必须记下来的事实:
+
+1. **脚本组件的两种存储都是 live 的。** 全 scalar 的 shape 被 `ScriptStorage` 池化成 wasm 堆
+ 视图,带嵌套对象的 shape 是普通 JS 对象——两者 `get`/`tryGet`/裸 `Query` 交出去的都是
+ 存储里那个对象本身,写它就是写 World。PR6b 只证过池化那一种。
+2. **同一个 API 在 builtin 上是另一种错法。** `get`/`tryGet` 对 builtin 返回一次性投影,
+ 写它既不改 World 也不报告——不是「安全」,是**静默丢弃**。裸 `Query(C)` 对 builtin 更糟:
+ `resolvePtrGetter` 返回的是一个**跨行复用的 scratch 对象**,写入会被下一行的 fill 覆盖。
+ 于是同一行代码 `row.field = v` 在脚本组件上悄悄改了世界,在 builtin 上悄悄什么都没做。
+3. **`Query` 的文档承诺没有被执行层兑现。** 文档写的是「除非包在 `Mut` 里否则只读」,
+ 但裸 `Query(C)` 的 getter 对脚本组件就是 `storage.get(e)`。承诺只存在于类型注释里。
+
+## 3. 用量普查:收紧类型要付多少
+
+`node tools/mutation-census.mjs`,扫描 1694 个文件(`sdk/src`、`sdk/tests`、`examples`、
+`desktop/src`,编辑器子模块经其自身索引读取):
+
+```
+280 处经由读句柄的写
+237 处是「读—改—写回」(后面跟着 set/insert/markChanged,今天就正常报告)
+ 43 处是静默写(值变了,没有任何人观测到)
+109 处句柄逃逸出本普查的视野(传进了别的函数)
+```
+
+**这两个数字回答的是两个不同的问题,不能混用:**
+
+- **43** 是今天就存在的缺陷数量。
+- **280** 是把 `get`/`tryGet`/裸 `Query` 收成 `DeepReadonly` 的迁移面——
+ 因为那 237 处合法的读—改—写回**同样是在写一个读句柄**,类型收紧会一并挡住。
+
+### 43 处静默写的分布
+
+| 位置 | 处数 | 性质 |
+|---|---|---|
+| `sdk/src/ui/text/text-input-plugin.ts` | 15 | 引擎自身 |
+| `sdk/src/ui/input/drag.ts` | 12 | 引擎自身 |
+| `sdk/tests/*` | 13 | **测试固化了这个语义** |
+| `examples/celestial-heights/src/systems/combat.ts` | 3 | flagship 游戏的伤害结算 |
+
+三处定罪:
+
+- **`world.test.ts` 有一个 describe 块就叫 `component data mutations`**,其中两个用例名为
+ `should allow mutating component data` 和 `should reflect mutations immediately`,直接断言
+ `world.get(...).x = 100` 之后值确实变了。`scene.test.ts` 更直白,注释写着
+ “Mutate the LIVE component”。**这不是无意的疏漏,是有测试背书的既有公开语义**——
+ 收紧类型是推翻它,不是补上一个未定义行为。
+- **`text-input-plugin.ts` 写了 8 次 `ti.dirty = true`,而 `TextInputData.dirty` 全仓零读者。**
+ 这是同一个问题的化石:有人需要「这个组件变了」这个信号,而经 `world.get` 原地写不会让
+ tracker 报告,于是他在组件里自己加了一个 dirty 字段——然后这个字段从来没有被读过一次。
+- **`damageSystem` 的血量结算完全静默**:`world.get(target, Health)` 之后 `health.current -=
+ blow.amount`,没有任何写回。任何 `Changed(Health)` 消费者或 Health 的复制都收不到它。
+ 同一目录下 `layout.ts` 正在用 `world.anyChangedSince(UINode, ...)` 决定要不要重算布局——
+ 同一个 tracker,一边被当权威,一边被绕过。
+
+## 4. 待裁定
+
+普查给出的结论是明确的:**`get`/`tryGet`/裸 `Query` 必须收成只读**,而且必须是
+`DeepReadonly` 而不是浅 `Readonly`(`c.nested.x = 1` 这条路径已实测为静默写)。
+
+但 280 这个数字意味着**不能只收紧类型**。237 处读—改—写回是今天合法且报告正常的写法,
+把它们全部改成「自己复制整个组件再 set」既是无谓的迁移,也会让热路径多一次拷贝。
+所以收紧读接口必须与一个符合人体工学的单实体写接口同时落地
+(`world.update(e, C, draft => {...})` 之类),否则这一刀会把成本转嫁给所有调用方。
+
+同时未判定、留给后续的两件:
+
+- **AOT 写回**:`AotDispatch.markChanged_` 按 `q.mutated`(即声明了 `Mut` 的组件)逐行标记,
+ 语义上与 `Mut` 一致。但本轮 fixture 没有覆盖它——跑它需要编译产物,
+ 留作 conformance 那条线的一格,**不计入本文的「已实测」**。
+- **`cleanRemovedBuffer` 的归属权**:它是全局 destructive cleanup,而每个
+ `RemovedQueryInstance` 各自持有 `lastRunTick`。复制层若替所有 `Removed()` 消费者删历史,
+ 会让 frontier 落后的消费者永久错过那段 removal。这是正确性契约而不是内存优化,
+ 属于 PR6d(共享 retention watermark),本文只记录事实。
diff --git a/package.json b/package.json
index 4ac62a1f2..0d9e5e801 100644
--- a/package.json
+++ b/package.json
@@ -29,6 +29,8 @@
"gate": "node tools/check-release-gate.mjs --report",
"gate:run": "node tools/run-release-gate.mjs",
"render-host": "node tools/render-host/build.mjs",
+ "verify:mutation": "node tools/mutation-contract.mjs",
+ "census:mutation": "node tools/mutation-census.mjs",
"verify:render": "node tools/verify-render.mjs",
"test": "vitest run --config vitest.engine.config.ts",
"verify:aot": "rm -rf .aot-verify && node pipeline/bin/estella.mjs export examples/ecs-basics --out .aot-verify && node tools/run-electron.mjs tools/launchers/headless-aot-verify.mjs .aot-verify",
diff --git a/tools/mutation-census.mjs b/tools/mutation-census.mjs
new file mode 100644
index 000000000..4cef0f90b
--- /dev/null
+++ b/tools/mutation-census.mjs
@@ -0,0 +1,450 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file Who writes through a READ path — every place this repo mutates a value
+ * it obtained from `world.get` / `world.tryGet`, or from an unwrapped
+ * `Query(C)` row.
+ *
+ * `tools/mutation-contract.mjs` proves those writes really land and are never
+ * observed. This asks the other half of the question: what would it cost to
+ * make them illegal? A read surface cannot be typed read-only on the strength
+ * of the defect alone — the answer depends on how much code writes that way.
+ *
+ * Syntactic, by AST, with no type checker. A checker would need one program per
+ * root across the editor submodule boundary, and the shapes that matter are
+ * decidable without one: `World.get` takes TWO arguments where `Map.get` takes
+ * one, and a query row is reached through the system parameter it was declared
+ * on. What that trades away is stated in BLIND_SPOTS and printed with the
+ * result, because a census whose limits are unstated reads as an all-clear.
+ *
+ * node tools/mutation-census.mjs
+ * node tools/mutation-census.mjs --json
+ * node tools/mutation-census.mjs --self-test # calibrate on known-positive source
+ *
+ * Exit codes: 0 the census ran, 2 a declared root could not be read (an
+ * unchecked-out editor submodule scans as zero findings, which is a false
+ * all-clear, not a clean repo).
+ */
+import { readFileSync, existsSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+import { listTrackedSources, hasEditor } from './lib/sourceRoots.mjs';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const ts = createRequire(path.join(ROOT, 'sdk', '/'))('typescript');
+const JSON_OUT = process.argv.includes('--json');
+const SELF_TEST = process.argv.includes('--self-test');
+
+/** Where a game or the engine could write through a read handle. */
+const ROOTS = ['sdk/src', 'sdk/tests', 'examples', 'desktop/src'];
+
+/**
+ * Files that MUST be excluded: each one deliberately performs the mutation
+ * being counted, so a census including them reports its own fixtures as
+ * findings. (A gate reading source has to exclude itself; this repo has been
+ * caught by that before.)
+ */
+const EXCLUDED = new Set([
+ 'tools/mutation-census.mjs',
+ 'tools/mutation-contract.mjs',
+ 'bench/replication-dirty/completeness.mjs',
+]);
+
+const BLIND_SPOTS = [
+ 'a handle passed to another function, then written there (counted as `escapes`, not as a write)',
+ 'a write through a computed key whose value is not a literal',
+ 'reflection paths (setByPath and friends) that reach a component by string',
+ 'a row reached by `single()` / `toArray()` destructured across statements',
+];
+
+const unwrap = (n) => {
+ while (n && (ts.isNonNullExpression(n) || ts.isParenthesizedExpression(n)
+ || ts.isAsExpression(n) || ts.isTypeAssertionExpression?.(n))) n = n.expression;
+ return n;
+};
+
+/** The expression an access chain bottoms out in: `a!.b.c` → `a`, `f(x).y` → `f(x)`. */
+function accessRoot(node) {
+ let n = unwrap(node);
+ while (n && (ts.isPropertyAccessExpression(n) || ts.isElementAccessExpression(n))) {
+ n = unwrap(n.expression);
+ }
+ return n;
+}
+
+/**
+ * `get` / `tryGet` with TWO arguments — the World signature. `Map.get` takes
+ * one, which is what keeps this from drowning in false positives without a
+ * checker; a two-argument `.get` on something else is rare enough to be worth
+ * reporting and reading.
+ */
+function worldReadKind(node) {
+ const call = unwrap(node);
+ if (!call || !ts.isCallExpression(call)) return null;
+ const callee = unwrap(call.expression);
+ if (!callee || !ts.isPropertyAccessExpression(callee)) return null;
+ const name = callee.name.text;
+ if (name !== 'get' && name !== 'tryGet') return null;
+ if (call.arguments.length !== 2) return null;
+ return name;
+}
+
+const MUTATING_METHODS = new Set(['push', 'pop', 'shift', 'unshift', 'splice', 'sort', 'reverse', 'fill', 'copyWithin']);
+
+/** The nearest enclosing scope a local binding cannot outlive. */
+function scopeOf(node) {
+ let n = node;
+ while (n && !ts.isSourceFile(n) && !ts.isFunctionDeclaration(n) && !ts.isFunctionExpression(n)
+ && !ts.isArrowFunction(n) && !ts.isMethodDeclaration(n) && !ts.isConstructorDeclaration(n)
+ && !ts.isGetAccessorDeclaration(n) && !ts.isSetAccessorDeclaration(n)) n = n.parent;
+ return n;
+}
+
+function within(node, scope) {
+ for (let n = node; n; n = n.parent) if (n === scope) return true;
+ return false;
+}
+
+/** Every `Query(...)` argument that is NOT wrapped in `Mut(...)`, by position. */
+function queryMutFlags(call) {
+ return call.arguments.map((a) => {
+ const arg = unwrap(a);
+ return ts.isCallExpression(arg) && ts.isIdentifier(unwrap(arg.expression))
+ && unwrap(arg.expression).text === 'Mut';
+ });
+}
+
+function scanFile(rel, text) {
+ const sf = ts.createSourceFile(rel, text, ts.ScriptTarget.Latest, true,
+ /\.(tsx|jsx)$/.test(rel) ? ts.ScriptKind.TSX : undefined);
+ const findings = [];
+ const at = (n) => sf.getLineAndCharacterOfPosition(n.getStart(sf)).line + 1;
+
+ // Bindings that hold a value obtained from a read path, and everything
+ // derived from them by property access — `const p = c.inner` keeps p live.
+ const tracked = [];
+ const isTracked = (node) => {
+ const r = accessRoot(node);
+ if (!r) return null;
+ if (worldReadKind(r)) return { origin: worldReadKind(r), direct: true };
+ if (!ts.isIdentifier(r)) return null;
+ const hit = tracked.find((t) => t.name === r.text && within(node, t.scope));
+ return hit ? { origin: hit.origin, direct: false } : null;
+ };
+
+ const collectBindings = () => {
+ const visit = (node) => {
+ if (ts.isVariableDeclaration(node) && node.initializer && ts.isIdentifier(node.name)) {
+ const init = unwrap(node.initializer);
+ const kind = worldReadKind(init) ?? (isTracked(init)?.origin ?? null);
+ if (kind && !tracked.some((t) => t.name === node.name.text && t.scope === scopeOf(node))) {
+ // `const p = c.position` is handed back to the World as `c`,
+ // never as `p`. Carrying the chain's ROOT binding is what lets
+ // a write-back through the parent be recognised as one.
+ const parent = accessRoot(init);
+ const via = ts.isIdentifier(parent)
+ ? tracked.find((t) => t.name === parent.text && within(node, t.scope))
+ : null;
+ tracked.push({
+ name: node.name.text, scope: scopeOf(node), origin: kind,
+ root: via?.root ?? via?.name ?? node.name.text,
+ });
+ }
+ }
+ ts.forEachChild(node, visit);
+ };
+ visit(sf);
+ };
+ // Twice, so one level of `const a = read(); const b = a.inner;` settles.
+ collectBindings();
+ collectBindings();
+
+ // Query rows the system declared read-only.
+ const readonlyRows = [];
+ const visitQueries = (node) => {
+ if (ts.isCallExpression(node) && ts.isIdentifier(unwrap(node.expression))
+ && unwrap(node.expression).text === 'Query') {
+ const flags = queryMutFlags(node);
+ const arrayLit = node.parent;
+ if (ts.isArrayLiteralExpression(arrayLit) && ts.isCallExpression(arrayLit.parent)) {
+ const idx = arrayLit.elements.indexOf(node);
+ const fn = arrayLit.parent.arguments.find((a) =>
+ ts.isArrowFunction(unwrap(a)) || ts.isFunctionExpression(unwrap(a)));
+ const param = fn && unwrap(fn).parameters[idx];
+ if (param && ts.isIdentifier(param.name)) {
+ readonlyRows.push({ paramName: param.name.text, scope: unwrap(fn), flags });
+ }
+ }
+ }
+ ts.forEachChild(node, visitQueries);
+ };
+ visitQueries(sf);
+
+ // A row binding is read-only when its Query slot was not wrapped in Mut.
+ const rowBindings = [];
+ for (const row of readonlyRows) {
+ const visit = (node) => {
+ // for (const [entity, a, b] of query)
+ if (ts.isForOfStatement(node) && ts.isIdentifier(unwrap(node.expression))
+ && unwrap(node.expression).text === row.paramName) {
+ const decl = node.initializer;
+ const binding = ts.isVariableDeclarationList(decl) ? decl.declarations[0]?.name : null;
+ if (binding && ts.isArrayBindingPattern(binding)) {
+ binding.elements.forEach((el, j) => {
+ if (j === 0 || !ts.isBindingElement(el) || !ts.isIdentifier(el.name)) return;
+ if (row.flags[j - 1] === false) {
+ rowBindings.push({ name: el.name.text, scope: node });
+ }
+ });
+ }
+ }
+ // query.forEach((entity, a, b) => ...)
+ if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression)
+ && node.expression.name.text === 'forEach'
+ && ts.isIdentifier(unwrap(node.expression.expression))
+ && unwrap(node.expression.expression).text === row.paramName) {
+ const cb = unwrap(node.arguments[0]);
+ if (cb && (ts.isArrowFunction(cb) || ts.isFunctionExpression(cb))) {
+ cb.parameters.forEach((p, j) => {
+ if (j === 0 || !ts.isIdentifier(p.name)) return;
+ if (row.flags[j - 1] === false) rowBindings.push({ name: p.name.text, scope: cb });
+ });
+ }
+ }
+ ts.forEachChild(node, visit);
+ };
+ visit(row.scope);
+ }
+
+ const isRow = (node) => {
+ const r = accessRoot(node);
+ if (!r || !ts.isIdentifier(r)) return false;
+ return rowBindings.some((b) => b.name === r.text && within(node, b.scope));
+ };
+
+ const written = new Set();
+ /**
+ * Whether the handle rooted at `node` is handed back to the World in the
+ * same scope — `world.set(e, C, h)` / `insert` / an explicit `markChanged`.
+ *
+ * This is the distinction the whole census turns on. Read-modify-write-back
+ * is a LEGAL idiom today and reports normally; the same two lines without
+ * the third are the silent write. Counting them together would price the
+ * migration at every mutation in the repo rather than at the broken ones.
+ */
+ const storesBack = (node) => {
+ const r = accessRoot(node);
+ if (!r || !ts.isIdentifier(r)) return false;
+ const hit = tracked.find((t) => t.name === r.text && within(node, t.scope))
+ ?? rowBindings.find((b) => b.name === r.text && within(node, b.scope));
+ if (!hit) return false;
+ const names = new Set([r.text, hit.root].filter(Boolean));
+ let found = false;
+ const look = (n) => {
+ if (found) return;
+ if (ts.isCallExpression(n) && ts.isPropertyAccessExpression(n.expression)) {
+ const m = n.expression.name.text;
+ if (m === 'set' || m === 'insert') {
+ if (n.arguments.some((a) => {
+ const u = unwrap(a);
+ return ts.isIdentifier(u) && names.has(u.text);
+ })) found = true;
+ } else if (m === 'markChanged') found = true;
+ }
+ ts.forEachChild(n, look);
+ };
+ look(hit.scope);
+ return found;
+ };
+
+ const record = (node, category, origin, target = node) => {
+ written.add(node);
+ findings.push({
+ file: rel, line: at(node), category, origin,
+ storedBack: storesBack(target),
+ code: node.getText(sf).replace(/\s+/g, ' ').slice(0, 100),
+ });
+ };
+
+ const visitWrites = (node) => {
+ if (ts.isBinaryExpression(node)
+ && (node.operatorToken.kind === ts.SyntaxKind.EqualsToken
+ || (node.operatorToken.kind >= ts.SyntaxKind.FirstCompoundAssignment
+ && node.operatorToken.kind <= ts.SyntaxKind.LastCompoundAssignment))) {
+ const lhs = unwrap(node.left);
+ if (ts.isPropertyAccessExpression(lhs) || ts.isElementAccessExpression(lhs)) {
+ const t = isTracked(lhs);
+ if (t) record(node, t.direct ? 'direct-write' : 'alias-write', t.origin, lhs);
+ else if (isRow(lhs)) record(node, 'row-write', 'bare Query', lhs);
+ }
+ }
+ if ((ts.isPrefixUnaryExpression(node) || ts.isPostfixUnaryExpression(node))
+ && (node.operator === ts.SyntaxKind.PlusPlusToken || node.operator === ts.SyntaxKind.MinusMinusToken)) {
+ const op = unwrap(node.operand);
+ if (ts.isPropertyAccessExpression(op) || ts.isElementAccessExpression(op)) {
+ const t = isTracked(op);
+ if (t) record(node, t.direct ? 'direct-write' : 'alias-write', t.origin, op);
+ else if (isRow(op)) record(node, 'row-write', 'bare Query', op);
+ }
+ }
+ if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression)) {
+ const method = node.expression.name.text;
+ const recv = node.expression.expression;
+ if (MUTATING_METHODS.has(method)) {
+ const t = isTracked(recv);
+ if (t) record(node, 'method-write', t.origin, recv);
+ else if (isRow(recv)) record(node, 'method-write', 'bare Query', recv);
+ }
+ if (method === 'assign' && ts.isIdentifier(unwrap(recv)) && unwrap(recv).text === 'Object') {
+ const target = node.arguments[0];
+ if (target) {
+ const t = isTracked(target);
+ if (t) record(node, 'assign-write', t.origin, target);
+ else if (isRow(target)) record(node, 'assign-write', 'bare Query', target);
+ }
+ }
+ }
+ // A handle handed to someone else — not counted as a write, counted as
+ // a place this census stops being able to see.
+ if (ts.isCallExpression(node) && !written.has(node)) {
+ for (const arg of node.arguments) {
+ const a = unwrap(arg);
+ if (!ts.isIdentifier(a)) continue;
+ const callee = ts.isPropertyAccessExpression(node.expression) ? node.expression.name.text : '';
+ if (callee === 'set' || callee === 'insert') continue;
+ const hit = tracked.find((t) => t.name === a.text && within(node, t.scope));
+ if (hit && !ts.isPropertyAccessExpression(node.expression)) {
+ record(node, 'escapes', hit.origin);
+ } else if (hit && ts.isPropertyAccessExpression(node.expression)
+ && !MUTATING_METHODS.has(node.expression.name.text)) {
+ record(node, 'escapes', hit.origin);
+ }
+ }
+ }
+ ts.forEachChild(node, visitWrites);
+ };
+ visitWrites(sf);
+ return findings;
+}
+
+// --- calibration ------------------------------------------------------------
+
+/**
+ * The census is only believable if it is known to fire. Every shape it claims
+ * to detect is written out here and asserted, so a refactor that silently stops
+ * matching reports zero findings and FAILS instead of reading as a clean repo.
+ */
+const CALIBRATION = `
+ import { Query, Mut, defineSystem } from 'estella';
+ function a(world, e, C) { world.get(e, C).v = 1; }
+ function b(world, e, C) { world.tryGet(e, C).v = 1; }
+ function c(world, e, C) { const h = world.get(e, C); h.v += 1; }
+ function d(world, e, C) { const h = world.tryGet(e, C); const p = h.inner; p.x = 1; }
+ function f(world, e, C) { const h = world.get(e, C); h.list.push(1); }
+ function g(world, e, C) { const h = world.get(e, C); Object.assign(h, { v: 1 }); }
+ function h2(world, e, C) { const h = world.get(e, C); helper(h); }
+ const s = defineSystem([Query(Mut(A), B)], (q) => {
+ for (const [entity, ok, bad] of q) { ok.v = 1; bad.v = 1; }
+ });
+ const s2 = defineSystem([Query(B)], (q) => { q.forEach((entity, bad) => { bad.v = 1; }); });
+ function noise(map, k) { map.get(k).v = 1; }
+ function stored(world, e, C) { const h = world.get(e, C); h.v = 1; world.set(e, C, h); }
+ function silent(world, e, C) { const h = world.get(e, C); h.v = 1; }
+ function viaChild(world, e, C) { const h = world.tryGet(e, C); const p = h.position; p.x = 1; world.set(e, C, h); }
+`;
+
+if (SELF_TEST) {
+ const got = scanFile('calibration.ts', CALIBRATION);
+ const count = (c) => got.filter((f) => f.category === c).length;
+ const expected = {
+ 'direct-write': 2, 'alias-write': 5, 'method-write': 1,
+ 'assign-write': 1, 'escapes': 1, 'row-write': 2,
+ };
+ let bad = 0;
+ for (const [cat, n] of Object.entries(expected)) {
+ const actual = count(cat);
+ const ok = actual === n;
+ if (!ok) bad++;
+ console.log(` ${ok ? 'ok ' : 'FAIL'} ${cat.padEnd(13)} expected ${n}, got ${actual}`);
+ }
+ // The distinction the migration estimate rests on: read-modify-WRITE-BACK
+ // reports, the same edit without the write-back does not.
+ const inFn = (name) => got.filter((f) => CALIBRATION.split('\n')
+ .findIndex((l) => l.includes(`function ${name}(`)) + 1 === f.line);
+ for (const [fn, want] of [['stored', true], ['silent', false], ['viaChild', true]]) {
+ const hits = inFn(fn).filter((f) => f.category === 'alias-write');
+ const ok = hits.length === 1 && hits[0].storedBack === want;
+ if (!ok) bad++;
+ console.log(` ${ok ? 'ok ' : 'FAIL'} storedBack ${fn}(): expected ${want}, got ${hits.map((h) => h.storedBack).join(',') || 'no finding'}`);
+ }
+ const rows = got.filter((f) => f.category === 'row-write').map((f) => f.code);
+ console.log(` row-writes seen: ${JSON.stringify(rows)}`);
+ if (!rows.every((r) => r.startsWith('bad'))) {
+ console.log(' FAIL a Mut()-declared row was counted as read-only');
+ bad++;
+ }
+ process.exit(bad === 0 ? 0 : 1);
+}
+
+// --- the run ----------------------------------------------------------------
+
+const declaredRoots = ROOTS.filter((r) => !r.startsWith('desktop/') || hasEditor());
+const skippedRoots = ROOTS.filter((r) => !declaredRoots.includes(r));
+const { files, missing } = listTrackedSources(declaredRoots);
+const sources = files.filter((f) => /\.(ts|tsx|js|mjs|jsx)$/.test(f) && !EXCLUDED.has(f) && !f.endsWith('.d.ts'));
+
+const findings = [];
+for (const rel of sources) {
+ const full = path.join(ROOT, rel);
+ if (!existsSync(full)) continue;
+ try {
+ findings.push(...scanFile(rel, readFileSync(full, 'utf8')));
+ } catch (e) {
+ findings.push({ file: rel, line: 0, category: 'unparsed', origin: '', code: String(e.message).slice(0, 80) });
+ }
+}
+
+const writes = findings.filter((f) => f.category !== 'escapes' && f.category !== 'unparsed');
+const byRoot = (rel) => ROOTS.find((r) => rel.startsWith(r + '/')) ?? rel;
+
+if (JSON_OUT) {
+ console.log(JSON.stringify({ scanned: sources.length, findings, skippedRoots, missing }, null, 2));
+} else {
+ console.log('');
+ console.log(` ${sources.length} files scanned across ${declaredRoots.join(', ')}`);
+ if (skippedRoots.length) console.log(` NOT scanned (no checkout): ${skippedRoots.join(', ')}`);
+ if (missing.length) console.log(` NOT scanned (root missing): ${missing.join(', ')}`);
+ console.log('');
+ const cats = [...new Set(findings.map((f) => f.category))].sort();
+ for (const cat of cats) {
+ const hits = findings.filter((f) => f.category === cat);
+ const silent = hits.filter((f) => f.storedBack === false).length;
+ const suffix = cat === 'escapes' || cat === 'unparsed' ? ''
+ : ` (${hits.length - silent} stored back, ${silent} SILENT)`;
+ console.log(` ${cat} — ${hits.length}${suffix}`);
+ const roots = [...new Set(hits.map((h) => byRoot(h.file)))];
+ for (const r of roots) {
+ const inRoot = hits.filter((h) => byRoot(h.file) === r);
+ console.log(` ${r}: ${inRoot.length}`);
+ for (const h of inRoot.slice(0, 12)) {
+ const isWrite = h.category !== 'escapes' && h.category !== 'unparsed';
+ const tag = !isWrite ? '' : h.storedBack ? '[stored] ' : '[SILENT] ';
+ console.log(` ${h.file}:${h.line} ${tag}${h.code}`);
+ }
+ if (inRoot.length > 12) console.log(` … ${inRoot.length - 12} more`);
+ }
+ }
+ console.log('');
+ const silentWrites = writes.filter((f) => f.storedBack === false);
+ console.log(` ${writes.length} writes through a read handle.`);
+ console.log(` ${writes.length - silentWrites.length} are read-modify-write-back and report normally today.`);
+ console.log(` ${silentWrites.length} are SILENT — the value changes and nothing observes it.`);
+ console.log(` ${findings.filter((f) => f.category === 'escapes').length} handles escape this census.`);
+ console.log('');
+ console.log(' Not decidable by this census:');
+ for (const b of BLIND_SPOTS) console.log(` - ${b}`);
+ console.log('');
+}
+
+process.exit(skippedRoots.length || missing.length ? 2 : 0);
diff --git a/tools/mutation-contract.mjs b/tools/mutation-contract.mjs
new file mode 100644
index 000000000..7daaf0cf7
--- /dev/null
+++ b/tools/mutation-contract.mjs
@@ -0,0 +1,301 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file What the engine's access paths actually DO, and what the ChangeTracker
+ * actually SEES — asked of every path a game can reach, one row each.
+ *
+ * Two questions per path, answered independently:
+ *
+ * stored did the World's value really change? Read back from a value
+ * snapshot, never through the reference the path handed out, so a
+ * live alias cannot confirm itself.
+ * observed did the tracker emit anything a consumer could have seen?
+ *
+ * `stored && !observed` is a silent write: state that really changed with
+ * nothing anywhere saying so. Replication, `Changed()` filters and the UI
+ * layout all read the tracker, so such a path drops out of all three.
+ *
+ * The expectation on each row is this repo's CURRENT contract, not the one we
+ * want. Rows marked `defect: true` are the disagreement PR6c exists to close —
+ * they are expected so this file can be run for regressions today, and each is
+ * a compile-time negative fixture once the read surface is typed read-only.
+ *
+ * node tools/mutation-contract.mjs
+ * node tools/mutation-contract.mjs --json
+ *
+ * Exit codes: 0 the contract holds, 1 a row disagrees with it, 2 this machine
+ * could not answer (unbuilt or stale SDK, no engine binary).
+ */
+import { existsSync, statSync, readdirSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const DIST = path.join(ROOT, 'sdk', 'dist', 'index.node.js');
+const WASM_DIR = process.env.ESENGINE_WASM_DIR ?? path.join(ROOT, 'build', 'wasm', 'web');
+const JSON_OUT = process.argv.includes('--json');
+
+/** Exit 2, not 1: a question this machine cannot ask is not a failed answer. */
+function undetermined(why) {
+ console.log(`UNDETERMINED ${why}`);
+ process.exit(2);
+}
+
+/**
+ * A dist older than the sources it is built from answers for the previous
+ * commit. Three gates in this repo have reported green off a stale artifact;
+ * the check is cheap enough to be unconditional.
+ */
+function newestSourceTime(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);
+ if (entry.isDirectory()) newest = Math.max(newest, newestSourceTime(full));
+ else if (entry.name.endsWith('.ts')) newest = Math.max(newest, statSync(full).mtimeMs);
+ }
+ return newest;
+}
+
+if (!existsSync(DIST)) undetermined(`no SDK build at ${path.relative(ROOT, DIST)} — run \`pnpm --filter ./sdk build\``);
+const distTime = statSync(DIST).mtimeMs;
+const srcTime = newestSourceTime(path.join(ROOT, 'sdk', 'src'));
+if (srcTime > distTime) {
+ undetermined('sdk/dist is older than sdk/src — it would answer for the previous commit; run `pnpm --filter ./sdk build`');
+}
+
+const sdk = await import(pathToFileURL(DIST).href);
+
+const engineJs = path.join(WASM_DIR, 'esengine.js');
+if (!existsSync(engineJs)) {
+ undetermined(`no engine build at ${path.relative(ROOT, engineJs)} — builtin components cannot be reached; run \`node build-tools/cli.js build -t web\``);
+}
+const wasmModule = await (await import(pathToFileURL(engineJs).href)).default({
+ locateFile: (f) => path.join(WASM_DIR, f),
+});
+
+let seq = 0;
+const rows = [];
+
+/** Deep value copy — the point is that it does not alias whatever the path returned. */
+function snapshot(world, entity, component) {
+ const v = world.tryGet(entity, component);
+ return v === null || v === undefined ? null : JSON.parse(JSON.stringify(v));
+}
+
+/**
+ * One access path against a fresh world.
+ *
+ * `make` builds the component and its initial value, so a row can choose the
+ * storage it needs: an all-scalar script shape is pooled into the wasm heap, a
+ * shape with a nested object is a plain JS object, and a builtin lives in C++.
+ * Those are three different objects to hand a caller, and the whole question is
+ * whether they behave the same.
+ */
+async function probe({ name, kind, expect, defect = false, cpp = false, body }) {
+ const app = sdk.App.new();
+ if (cpp) app.connectCpp(new wasmModule.Registry(), wasmModule, { strict: false });
+ const world = app.world;
+ const { component, initial } = kind(sdk, seq++);
+ world.enableChangeTracking(component);
+
+ const e = world.spawn();
+ world.insert(e, component, initial);
+ world.advanceTick();
+ const before = snapshot(world, e, component);
+ const had = world.has(e, component);
+ const since = world.getWorldTick() - 1;
+
+ await body({ world, e, component, app, sdk });
+
+ // Observation is read FIRST: `snapshot` goes through `tryGet`, and whether a
+ // read reports as a write is one of the things under test here. Asking after
+ // the snapshot would let the fixture's own read answer the question.
+ const observed = world.anyChangedSince(component, since)
+ && (world.isChangedSince(e, component, since)
+ || world.getRemovedEntitiesSince(component, since).includes(e));
+ const after = snapshot(world, e, component);
+ const stored = had !== world.has(e, component) || JSON.stringify(before) !== JSON.stringify(after);
+
+ rows.push({
+ name, stored, observed, defect,
+ expected: expect,
+ holds: stored === expect.stored && observed === expect.observed,
+ });
+}
+
+// --- the three storages a component can live in -----------------------------
+
+/** All-scalar script shape: ScriptStorage pools it, and hands out a heap view. */
+const pooled = (s, n) => ({
+ component: s.defineComponent(`McPooled${n}`, { v: 0, w: 0 }),
+ initial: { v: 1, w: 1 },
+});
+
+/** Nested shape: not poolable, so storage holds a plain JS object. */
+const nested = (s, n) => ({
+ component: s.defineComponent(`McNested${n}`, { inner: { x: 0 }, tag: 'a' }),
+ initial: { inner: { x: 1 }, tag: 'a' },
+});
+
+/** Engine-backed: the value lives in C++ and every read crosses the boundary. */
+const builtin = (s) => ({ component: s.Transform, initial: {} });
+
+/** Run one system for a tick — the only way a Query argument is reached at all. */
+async function inSystem(app, sdk, queryArgs, fn) {
+ app.addSystemToSchedule(sdk.Schedule.Update, sdk.defineSystem([sdk.Query(...queryArgs)], fn));
+ await app.tick(1 / 60);
+}
+
+// --- declared write paths ---------------------------------------------------
+
+await probe({
+ name: 'world.set', kind: pooled, expect: { stored: true, observed: true },
+ body: ({ world, e, component }) => { world.set(e, component, { v: 2, w: 1 }); },
+});
+
+await probe({
+ name: 'world.set (nested shape)', kind: nested, expect: { stored: true, observed: true },
+ body: ({ world, e, component }) => { world.set(e, component, { inner: { x: 2 }, tag: 'a' }); },
+});
+
+await probe({
+ name: 'world.set (builtin)', kind: builtin, cpp: true, expect: { stored: true, observed: true },
+ body: ({ world, e, component }) => {
+ const v = world.get(e, component);
+ v.position.x = 2;
+ world.set(e, component, v);
+ },
+});
+
+await probe({
+ name: 'world.insert (replacing)', kind: pooled, expect: { stored: true, observed: true },
+ body: ({ world, e, component }) => { world.insert(e, component, { v: 3, w: 1 }); },
+});
+
+await probe({
+ name: 'world.remove', kind: pooled, expect: { stored: true, observed: true },
+ body: ({ world, e, component }) => { world.remove(e, component); },
+});
+
+await probe({
+ name: 'world.markChanged', kind: pooled, expect: { stored: false, observed: true },
+ body: ({ world, e, component }) => { world.markChanged(e, component); },
+});
+
+await probe({
+ name: 'Query(Mut(C)) write-back', kind: pooled, expect: { stored: true, observed: true },
+ body: ({ app, sdk: s, component }) =>
+ inSystem(app, s, [s.Mut(component)], (q) => { for (const [, d] of q) d.v = 4; }),
+});
+
+await probe({
+ name: 'Query(Mut(C)) write-back (builtin)', kind: builtin, cpp: true,
+ expect: { stored: true, observed: true },
+ body: ({ app, sdk: s, component }) =>
+ inSystem(app, s, [s.Mut(component)], (q) => { for (const [, d] of q) d.position.x = 4; }),
+});
+
+// --- read paths used as write paths -----------------------------------------
+
+await probe({
+ name: 'world.get(...).f = v', kind: pooled, defect: true,
+ expect: { stored: true, observed: false },
+ body: ({ world, e, component }) => { world.get(e, component).v = 5; },
+});
+
+await probe({
+ name: 'world.tryGet(...).f = v', kind: pooled, defect: true,
+ expect: { stored: true, observed: false },
+ body: ({ world, e, component }) => { world.tryGet(e, component).v = 5; },
+});
+
+await probe({
+ name: 'world.get(...).nested.x = v', kind: nested, defect: true,
+ expect: { stored: true, observed: false },
+ body: ({ world, e, component }) => { world.get(e, component).inner.x = 5; },
+});
+
+await probe({
+ name: 'world.tryGet(...).nested.x = v', kind: nested, defect: true,
+ expect: { stored: true, observed: false },
+ body: ({ world, e, component }) => { world.tryGet(e, component).inner.x = 5; },
+});
+
+await probe({
+ name: 'world.get(...).nested.x = v (builtin)', kind: builtin, cpp: true,
+ expect: { stored: false, observed: false },
+ body: ({ world, e, component }) => { world.get(e, component).position.x = 5; },
+});
+
+await probe({
+ name: 'world.tryGet(...).nested.x = v (builtin)', kind: builtin, cpp: true,
+ expect: { stored: false, observed: false },
+ body: ({ world, e, component }) => { world.tryGet(e, component).position.x = 5; },
+});
+
+await probe({
+ name: 'bare Query(C) row write', kind: pooled, defect: true,
+ expect: { stored: true, observed: false },
+ body: ({ app, sdk: s, component }) =>
+ inSystem(app, s, [component], (q) => { for (const [, d] of q) d.v = 6; }),
+});
+
+await probe({
+ name: 'bare Query(C) row write (nested shape)', kind: nested, defect: true,
+ expect: { stored: true, observed: false },
+ body: ({ app, sdk: s, component }) =>
+ inSystem(app, s, [component], (q) => { for (const [, d] of q) d.inner.x = 6; }),
+});
+
+await probe({
+ name: 'bare Query(C) row write (builtin)', kind: builtin, cpp: true,
+ expect: { stored: false, observed: false },
+ body: ({ app, sdk: s, component }) =>
+ inSystem(app, s, [component], (q) => { for (const [, d] of q) d.position.x = 6; }),
+});
+
+/**
+ * A reference kept past the tick it was taken on. If the alias is live, the
+ * write lands whenever it happens — the tracker is not merely late, it never
+ * hears about it at all.
+ */
+await probe({
+ name: 'reference held across ticks, written later', kind: pooled, defect: true,
+ expect: { stored: true, observed: false },
+ body: ({ world, e, component }) => {
+ const ref = world.get(e, component);
+ world.advanceTick();
+ world.advanceTick();
+ ref.v = 7;
+ },
+});
+
+// --- reporting --------------------------------------------------------------
+
+const broken = rows.filter((r) => !r.holds);
+
+if (JSON_OUT) {
+ console.log(JSON.stringify({ rows, broken: broken.length }, null, 2));
+} else {
+ const w = Math.max(...rows.map((r) => r.name.length));
+ console.log('');
+ console.log(` ${'access path'.padEnd(w)} stored observed verdict`);
+ console.log(` ${'-'.repeat(w)} ------ -------- -------`);
+ for (const r of rows) {
+ const mark = (b) => (b ? 'yes' : 'no ');
+ const verdict = !r.holds ? 'CONTRACT MOVED'
+ : r.defect ? 'silent write'
+ : r.stored || r.observed ? 'reported' : 'inert';
+ console.log(` ${r.name.padEnd(w)} ${mark(r.stored).padStart(6)} ${mark(r.observed).padStart(8)} ${verdict}`);
+ }
+ const silent = rows.filter((r) => r.stored && !r.observed).length;
+ console.log('');
+ console.log(` ${rows.length} paths, ${silent} of them silent writes (changed the World, told nobody).`);
+ for (const r of broken) {
+ console.log(` MOVED ${r.name}: expected stored=${r.expected.stored} observed=${r.expected.observed}, got stored=${r.stored} observed=${r.observed}`);
+ }
+ console.log('');
+}
+
+process.exit(broken.length === 0 ? 0 : 1);