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
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.mdnew file mode 100644index 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.jsonindex 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.mjsnew file mode 100644index 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.mjsnew file mode 100644index 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);