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.

refactor(comments): a comment says what it means, not where to read it

esenginecf9012157032
diff --git a/bench/aot-stage0/bench.cpp b/bench/aot-stage0/bench.cpp
index a36578cf6..61459f1d4 100644
--- a/bench/aot-stage0/bench.cpp
+++ b/bench/aot-stage0/bench.cpp
@@ -4,11 +4,11 @@
* @file bench.cpp
* @brief Stage 0 of the AOT proposal: is compiling the system loop worth it?
*
- * @details `docs/REARCH_AOT.md` §10 makes Stage 0 a go/no-go, and §11 names the
- * risk it exists to retire: the speedup may be mostly the BOUNDARY COPY,
- * not the interpreter — and the copy has a fix that costs 5% of a
- * compiler (§12.B). A benchmark that reports one number cannot tell
- * those apart, so this one runs the same system four ways:
+ * @details Stage 0 is a go/no-go, and the risk it exists to retire is that the
+ * speedup may be mostly the BOUNDARY COPY rather than the interpreter —
+ * the copy has an SDK-side fix (variant B below) that costs 5% of a
+ * compiler. A benchmark that reports one number cannot tell those
+ * apart, so this one runs the same system four ways:
*
* A today's SDK path — fillTransform, body, writeTransform
* B in-place view — accessors onto the bytes, nothing copied
@@ -294,7 +294,7 @@ int main() {
const bool thick = strEnvIs("BENCH_BODY", "thick");
std::printf("================================================================\n");
- std::printf("Estella AOT — Stage 0 loop benchmark (REARCH_AOT.md §10)\n");
+ std::printf("Estella AOT — Stage 0 loop benchmark\n");
std::printf(" interpreter : QuickJS %d.%d.%d (no JIT, on any platform)\n",
QJS_VERSION_MAJOR, QJS_VERSION_MINOR, QJS_VERSION_PATCH);
std::printf(" entities : %d\n", ENTITIES);
@@ -402,7 +402,7 @@ int main() {
};
runJs("A", "SDK today (fill + body + write-back)", thick ? "variantA_thick" : "variantA");
- runJs("B", "in-place view (SDK fix, §12.B)", thick ? "variantB_thick" : "variantB");
+ runJs("B", "in-place view (the SDK-side fix)", thick ? "variantB_thick" : "variantB");
runJs("B2", "raw indexing (interpreted floor)", thick ? "variantB2_thick" : "variantB2");
runNative("C", "native C++ (the AOT ceiling)");
@@ -441,14 +441,14 @@ int main() {
std::printf("\n where the speedup actually comes from\n");
std::printf(" ------------------------------------------------------------\n");
- std::printf(" A -> B %6.2fx what a pure SDK change buys (§12.B)\n", sdkFix);
+ std::printf(" A -> B %6.2fx what a pure SDK change buys\n", sdkFix);
std::printf(" B -> B2 %6.2fx what the accessor layer costs\n", viewCost);
std::printf(" B -> C %6.2fx what COMPILING buys <-- the Stage 0 question\n", compiled);
std::printf(" A -> C %6.2fx total AOT ceiling\n", total);
std::printf(" throughput A %.2f C %.2f M entity-updates/s\n",
ENTITIES * (1000.0 / A) / 1e6, ENTITIES * (1000.0 / C) / 1e6);
- // REARCH_AOT §10: >= 5x total, and at least half of it must NOT be the copy.
+ // The bar: >= 5x total, and at least half of it must NOT be the copy.
// "Half" in a ratio is geometric: sqrt(5) on each side.
const double NEED_TOTAL = 5.0;
const double NEED_COMPILED = 2.2360679775; // sqrt(5)
@@ -461,7 +461,7 @@ int main() {
std::printf(" B -> C >= %.2fx %6.2fx %s\n", NEED_COMPILED, compiled, passCompiled ? "PASS" : "FAIL");
std::printf("\n VERDICT: %s\n", (passTotal && passCompiled)
? "GO — compiling buys more than the SDK fix alone. Proceed to Stage 1."
- : "STOP — take REARCH_AOT.md §12 instead, starting with B. Re-read the split above.");
+ : "STOP — the SDK-side fix (variant B) buys most of it. Re-read the split above.");
std::printf("================================================================\n");
JS_FreeContext(ctx);
diff --git a/bench/aot-stage0/frame-share-rendered.mjs b/bench/aot-stage0/frame-share-rendered.mjs
index 35683298c..32f96d0a0 100644
--- a/bench/aot-stage0/frame-share-rendered.mjs
+++ b/bench/aot-stage0/frame-share-rendered.mjs
@@ -2,7 +2,7 @@
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file frame-share-rendered.mjs
- * @brief `c` — the C++ share of a REAL rendered frame (docs/REARCH_AOT.md §14).
+ * @brief `c` — the C++ share of a REAL rendered frame.
*
* @details frame-share.mjs runs headless, so the renderer is missing and the TS
* share it reports is an upper bound. This drives the pixel-gate host
@@ -124,7 +124,7 @@ const c = cpu > 0 ? cpp / cpu : 0;
const gpu = median(frames.map((f) => (typeof f.gpuMs === 'number' ? f.gpuMs : -1)));
console.log('\n' + '='.repeat(70));
-console.log('Estella AOT — `c` from a rendered frame (REARCH_AOT.md §14)');
+console.log('Estella AOT — `c` from a rendered frame');
console.log(` frames : ${n} recorded, ${result.entityCount} entities, ${result.drawCalls} draw call(s)`);
console.log(` runtime : wasm under V8 — see the header for which way that biases c`);
console.log('='.repeat(70));
@@ -168,7 +168,7 @@ console.log('');
console.log(` compiled TS merely matches a JIT ........ ${floorX.toFixed(1)}x <- floor`);
console.log(` compiled TS runs at native speed ........ ${ceilX.toFixed(1)}x <- ceiling`);
console.log(`
- gate (REARCH_AOT §13.4): >= 3x opens Stage 1 -> ${floorX >= 3 ? 'OPEN' : 'HOLD'}`);
+ gate: >= 3x opens Stage 1 -> ${floorX >= 3 ? 'OPEN' : 'HOLD'}`);
// This scene carries no game logic (VelocitySystem ~0.01 ms — the copies have no
// Velocity), so c is at its RENDERING end; headless is the other end at ~4%. The
diff --git a/bench/aot-stage0/frame-share.mjs b/bench/aot-stage0/frame-share.mjs
index 277475687..98de0a5df 100644
--- a/bench/aot-stage0/frame-share.mjs
+++ b/bench/aot-stage0/frame-share.mjs
@@ -2,7 +2,7 @@
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file frame-share.mjs
- * @brief Amdahl's denominator for the AOT proposal (docs/REARCH_AOT.md §14).
+ * @brief Amdahl's denominator for the AOT proposal.
*
* @details Stage 0 measured that compiling a system LOOP is worth 154-385x
* under a no-JIT interpreter. That decides nothing alone: a loop 400x
@@ -104,7 +104,7 @@ async function main() {
}
console.log('='.repeat(70));
- console.log("Estella AOT — Amdahl's denominator (REARCH_AOT.md §10, Stage 0 follow-up)");
+ console.log("Estella AOT — Amdahl's denominator (Stage 0 follow-up)");
console.log(' runtime : node', process.versions.node, '(V8, WITH jit)');
console.log(' entities :', ENTITIES);
console.log(' frames :', FRAMES, `(+${WARMUP} warmup)`);
diff --git a/bench/aot-stage0/variants.js b/bench/aot-stage0/variants.js
index ee2e5e5f1..34cf79baa 100644
--- a/bench/aot-stage0/variants.js
+++ b/bench/aot-stage0/variants.js
@@ -9,7 +9,7 @@
//
// A today's SDK path .... fillTransform -> user body -> writeTransform
// B in-place view ....... a reused view object whose fields are accessors
-// straight onto the component bytes (REARCH_AOT §12.B)
+// straight onto the component bytes
// B2 raw indexing ........ the interpreted floor: no object layer at all
// C native .............. in bench.cpp, the AOT ceiling
//
@@ -111,7 +111,7 @@ globalThis.variantA = function (dt) {
};
// ---------------------------------------------------------------------------
-// B — in-place view (REARCH_AOT §12.B).
+// B — in-place view.
//
// The game author's code is UNCHANGED: still `t.position.x += v.linear.x * dt`.
// What changed is that `t.position` is a reused object whose x/y/z are accessors
diff --git a/compiler/package.json b/compiler/package.json
index e12b86ded..614ac48bd 100644
--- a/compiler/package.json
+++ b/compiler/package.json
@@ -3,7 +3,7 @@
"version": "0.0.0",
"private": true,
"type": "module",
- "description": "Estella AOT — TypeScript to Estella IR (docs/REARCH_AOT.md)",
+ "description": "Estella AOT — TypeScript to Estella IR",
"main": "src/index.ts",
"scripts": {
"test": "vitest run",
diff --git a/compiler/src/abi.ts b/compiler/src/abi.ts
index 6553ae720..8c51651d6 100644
--- a/compiler/src/abi.ts
+++ b/compiler/src/abi.ts
@@ -2,7 +2,7 @@
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file abi.ts
- * @brief The Estella ABI, as an EirHost (docs/REARCH_AOT_ABI.md).
+ * @brief The Estella ABI, as an EirHost.
*
* @details Runs a system with nothing but what SysCtx provides: a packed row
* array, resource pointers, a command buffer, and shared linear memory
@@ -99,9 +99,9 @@ export class AbiMemory {
}
/**
- * Reset the arena the host refills each call. §2.2 gives row arrays and the
- * SysCtx a one-call lifetime, and a region thrown away each time ENFORCES
- * that rather than restating it. It grows down from the end of the image
+ * Reset the arena the host refills each call. A row array and a SysCtx have
+ * a one-call lifetime, and a region thrown away each time ENFORCES that
+ * rather than restating it. It grows down from the end of the image
* while world data grows up, so an overlap is caught by `alloc`, not silent.
*/
beginCall(): void {
@@ -189,8 +189,8 @@ function store(mem: AbiMemory, at: number, enc: LeafEnc, v: number | boolean): v
/**
* Which slot of `SysCtx` each of a system's parameters is. The order is the
- * declaration order of `_params`, and §2.1 says it is burned into the handshake
- * hash — so this function, not a convention, is what both the host and the code
+ * declaration order of `_params`, and the manifest is what drives it at run
+ * time — so this function, not a convention, is what both the host and the code
* generator ask. Two readers of one answer; not two answers.
*/
export interface SysPlan {
@@ -238,7 +238,7 @@ export interface AbiCall {
}
/**
- * The host's half of §2.1: pack the rows, resolve the resource addresses, zero
+ * The host's half of the contract: pack the rows, resolve the resources, zero
* the count, write the SysCtx. When it returns, linear memory holds everything
* the compiled code reads and nothing else it may reach. Rows are materialised
* the way `View.hpp` already does — existing strategy, not a second one.
@@ -363,7 +363,7 @@ export function runOnAbi(sys: EirSystem, mem: AbiMemory, layout: AbiLayout, fns:
}
/**
- * The §2.5 handshake, as TWO numbers because the fixes differ: `engineAbi` means
+ * The handshake, as TWO numbers because the fixes differ: `engineAbi` means
* rebuild the module against this engine, `projectShapes` means rebuild the
* project. Parameter order is in neither — the manifest DRIVES the layout at run
* time, so it is followed rather than compared.
diff --git a/compiler/src/builtins.ts b/compiler/src/builtins.ts
index 5fd4b4f7d..cfe8323e1 100644
--- a/compiler/src/builtins.ts
+++ b/compiler/src/builtins.ts
@@ -7,7 +7,7 @@
* @details PTR_LAYOUTS is generated from the C++ structs and is what the SDK's
* accessors and the ABI hash already agree on. The compiler consumes it
* for the same reason: a component's fields must have exactly one
- * author (docs/REARCH_AOT.md §1.2).
+ * author.
*
* Resources have no such table yet — `Time` is spelled out below and
* marked, because a shape with no generator is exactly the drift this
@@ -92,7 +92,7 @@ export function resourceNames(): readonly string[] {
}
/**
- * EHT's table, flattened for the §2.5 handshake. It stamps the OFFSETS rather
+ * EHT's table, flattened for the handshake. It stamps the OFFSETS rather
* than importing `ABI_LAYOUT_HASH`: that constant lives in
* `component.generated.ts`, whose imports reach the whole SDK runtime. The raw
* table is more information than a hash of it, and changes for the same reason.
diff --git a/compiler/src/eir.ts b/compiler/src/eir.ts
index 151b3a576..3bf41a83f 100644
--- a/compiler/src/eir.ts
+++ b/compiler/src/eir.ts
@@ -2,7 +2,7 @@
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file eir.ts
- * @brief Estella IR, high level — typed, and ECS-aware (docs/REARCH_AOT.md §4).
+ * @brief Estella IR, high level — typed, and ECS-aware.
*
* @details The reason this layer exists rather than lowering the TS AST straight
* to LLVM: by LLVM IR a query is an opaque call, and the optimisations
@@ -75,7 +75,7 @@ export type Expr =
| { readonly e: 'call'; readonly target: CallTarget; readonly args: readonly Expr[]; readonly type: EirType };
export type CallTarget =
- /** Only the exactly-specified Math operations (§3.3). */
+ /** Only the Math operations ECMAScript specifies exactly. */
| { readonly k: 'math'; readonly fn: MathFn }
| { readonly k: 'fn'; readonly name: string };
diff --git a/compiler/src/frontend.ts b/compiler/src/frontend.ts
index 57dd401c8..62707fc89 100644
--- a/compiler/src/frontend.ts
+++ b/compiler/src/frontend.ts
@@ -2,7 +2,7 @@
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file frontend.ts
- * @brief TypeScript AST -> EIR-high (docs/REARCH_AOT.md §4.1, §3.3).
+ * @brief TypeScript AST -> EIR-high.
*
* @details Uses the real `typescript` program and checker. Re-implementing TS
* inference is the one decision that would sink this project.
@@ -21,8 +21,8 @@
*
* Nothing here throws on code it cannot handle. Anything outside the
* subset produces a Diagnostic naming the line and the reason, and its
- * system is simply not compiled — §3.2's no-cliff rule, which is what
- * lets this ship before it is finished.
+ * system is simply not compiled. Falling back rather than failing is
+ * what lets this ship before it is finished.
*/
import { sep } from 'node:path';
import ts from 'typescript';
@@ -85,7 +85,8 @@ function marksCompiled(node: ts.Node): boolean {
/**
* The promises this program did not keep: every marked system that refused, plus
* any that vanished without a diagnostic. A build fails on this list; an unmarked
- * refusal stays a note, because §3.2's fallback is a design and not a defect.
+ * refusal stays a note, because falling back to the interpreter is a design
+ * and not a defect.
*/
export function brokenPromises(result: LowerResult): readonly Diagnostic[] {
const compiled = new Set(result.module.systems.map((s) => s.name));
@@ -177,7 +178,7 @@ function annotatedType(node: ts.TypeNode): EirType | null {
}
/**
- * `permanent` = the contract has no place for it (REARCH_AOT_ABI.md §4), not a
+ * `permanent` = the contract has no place for it, not a
* todo. `pending` = the contract admits it, nobody lowered it yet. Default is
* `pending`; every `permanent` below names what is missing.
*/
@@ -590,8 +591,8 @@ class SystemLowerer {
}
if (!ts.isPropertyAccessExpression(callee) || !ts.isIdentifier(callee.expression)
|| callee.expression.text !== 'Math') {
- // A method on a RESOURCE is pending: §2.3 says a service should be
- // memory, so `input.isKeyDown('KeyW')` is a bit at a known offset.
+ // A method on a RESOURCE is pending: a service is meant to be read
+ // as memory, so `input.isKeyDown('KeyW')` is a bit at a known offset.
// On anything else it needs an object model, which there is none of.
const recv = ts.isPropertyAccessExpression(callee) && ts.isIdentifier(callee.expression)
? this.tryLookup(callee.expression.text)
@@ -680,7 +681,7 @@ class SystemLowerer {
return { e: 'read', place: this.place(node), type: this.placeType(node) };
}
// String, array, object, new, await: each needs a heap, and the contract
- // has no allocation (docs/REARCH_AOT_ABI.md §3).
+ // has no allocation.
throw new NotInSubset(node, `${ts.SyntaxKind[node.kind]} is not an expression this subset lowers`, 'permanent');
}
}
diff --git a/compiler/src/inline.ts b/compiler/src/inline.ts
index 51959d4d7..3d1f36f83 100644
--- a/compiler/src/inline.ts
+++ b/compiler/src/inline.ts
@@ -5,8 +5,8 @@
* @brief The first EIR -> EIR pass: calls to pure functions become their bodies.
*
* @details A helper called once per row must not still be a call by the time the
- * backend sees it — §4.2's optimisations need the body visible, and a
- * call boundary hides it.
+ * backend sees it — copy elimination and archetype specialisation need
+ * the body visible, and a call boundary hides it.
*
* It is a PASS, not something the frontend does, and that is the point.
* The frontend lowers faithfully; every optimisation after it is an
diff --git a/compiler/src/interp.ts b/compiler/src/interp.ts
index 12f14b8e7..e5f841dd9 100644
--- a/compiler/src/interp.ts
+++ b/compiler/src/interp.ts
@@ -2,7 +2,7 @@
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file interp.ts
- * @brief A reference interpreter for EIR-high (docs/REARCH_AOT.md §8.1).
+ * @brief A reference interpreter for EIR-high.
*
* @details Written before any code generation, for two reasons. It proves the IR
* means something on its own, and it is the third implementation a
diff --git a/compiler/src/verify.ts b/compiler/src/verify.ts
index ee363f8b8..98a82d584 100644
--- a/compiler/src/verify.ts
+++ b/compiler/src/verify.ts
@@ -4,10 +4,9 @@
* @file verify.ts
* @brief Re-prove an EIR system's types, without looking at the TypeScript.
*
- * @details docs/REARCH_AOT.md §4.1 asks for this because tsc's types are not
- * sound — structural typing, method bivariance and `any` leak through
- * generics — so a pass has to prove, on the IR, that every value is the
- * type it claims.
+ * @details tsc's types are not sound — structural typing, method bivariance and
+ * `any` all leak through generics — so a pass has to prove, on the IR,
+ * that every value is the type it claims.
*
* It reads only EIR, never the AST. That is the point: re-running the
* frontend's own reasoning would agree with the frontend's own bugs,
diff --git a/compiler/tests/abi.test.ts b/compiler/tests/abi.test.ts
index e8e08d72e..6c8d01a49 100644
--- a/compiler/tests/abi.test.ts
+++ b/compiler/tests/abi.test.ts
@@ -2,7 +2,7 @@
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file abi.test.ts
- * @brief Is the ABI SUFFICIENT? (docs/REARCH_AOT_ABI.md)
+ * @brief Is the ABI SUFFICIENT?
*
* @details The same interpreter runs the same system twice: once over JS objects
* and once over flat memory reached only through what SysCtx carries.
@@ -161,6 +161,6 @@ describe('the ABI is sufficient for the systems the subset compiles', () => {
});
// "Zero calls into the engine" is not asserted here: it is a property of the
- // shipped artifact (an empty wasm import section) that the build checks,
- // per docs/REARCH_AOT_ABI.md §6.5.
+ // shipped artifact — an empty wasm import section — and wasm.test.ts asks it
+ // of the artifact itself.
});
diff --git a/compiler/tests/commands.test.ts b/compiler/tests/commands.test.ts
index 861663d29..c2f4d57d3 100644
--- a/compiler/tests/commands.test.ts
+++ b/compiler/tests/commands.test.ts
@@ -2,7 +2,7 @@
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file commands.test.ts
- * @brief A per-frame system that despawns, run both ways (§8.2).
+ * @brief A per-frame system that despawns, run both ways.
*
* @details The oracle is examples/ecs-basics/src/systems/lifetime.ts — a real
* per-frame Commands user, which is the shape AOT is for. Most of the
diff --git a/compiler/tests/conformance.test.ts b/compiler/tests/conformance.test.ts
index 3215b777f..782d6826a 100644
--- a/compiler/tests/conformance.test.ts
+++ b/compiler/tests/conformance.test.ts
@@ -2,7 +2,7 @@
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file conformance.test.ts
- * @brief Every subset feature run BOTH ways and compared (§8.2).
+ * @brief Every subset feature run BOTH ways and compared.
*
* @details move-system.test.ts covers the one shape a shipped system happens to
* use. This covers what the subset gained after it — locals, if /
diff --git a/compiler/tests/coverage.test.ts b/compiler/tests/coverage.test.ts
index 9ae8adf34..62e375e7d 100644
--- a/compiler/tests/coverage.test.ts
+++ b/compiler/tests/coverage.test.ts
@@ -4,8 +4,8 @@
* @file coverage.test.ts
* @brief How much of the shipped corpus compiles — a number that may only rise.
*
- * @details §8.2's coverage gate. Without it the subset can quietly stop growing,
- * or shrink under a refactor, and nothing says so: every other test here
+ * @details Without this the subset can quietly stop growing, or shrink under a
+ * refactor, and nothing says so: every other test here
* passes just as well on a compiler that lowers one system.
*
* It counts PER-FRAME systems. A startup system runs once, so compiling
diff --git a/compiler/tests/fixtures/dynamic-component.ts b/compiler/tests/fixtures/dynamic-component.ts
index 034d022d0..067a3e42b 100644
--- a/compiler/tests/fixtures/dynamic-component.ts
+++ b/compiler/tests/fixtures/dynamic-component.ts
@@ -4,8 +4,8 @@
* @file dynamic-component.ts
* @brief A defineComponent whose shape is not a literal.
*
- * @details §3.3 makes it an intrinsic, so a shape the compiler cannot read at
- * compile time is a fallback, not a guess.
+ * @details `defineComponent` is an intrinsic, so a shape the compiler cannot
+ * read at compile time is a fallback, not a guess.
*/
import { defineComponent } from 'esengine';
diff --git a/compiler/tests/fixtures/outside-subset.ts b/compiler/tests/fixtures/outside-subset.ts
index 5e40c2106..69eb7f280 100644
--- a/compiler/tests/fixtures/outside-subset.ts
+++ b/compiler/tests/fixtures/outside-subset.ts
@@ -4,7 +4,7 @@
* @file outside-subset.ts
* @brief Systems that must NOT compile.
*
- * @details Each names a rule from REARCH_AOT §3; subset.test.ts asserts the
+ * @details Each names one rule of the subset; subset.test.ts asserts the
* diagnostic points at the line and says why.
*/
import { defineComponent, defineSystem, Query, Mut, Res, Camera, Time, Transform } from 'esengine';
diff --git a/compiler/tests/move-system.test.ts b/compiler/tests/move-system.test.ts
index 309eb2494..a12bc1418 100644
--- a/compiler/tests/move-system.test.ts
+++ b/compiler/tests/move-system.test.ts
@@ -2,7 +2,7 @@
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file move-system.test.ts
- * @brief Stage 1's exit criterion, end to end (docs/REARCH_AOT.md §10).
+ * @brief A shipped system, lowered and run — end to end.
*
* @details Takes a real system out of examples/, lowers it to EIR, and holds
* the interpreter's result against node's.
diff --git a/compiler/tests/subset.test.ts b/compiler/tests/subset.test.ts
index cdac60f82..9b3ec0047 100644
--- a/compiler/tests/subset.test.ts
+++ b/compiler/tests/subset.test.ts
@@ -4,9 +4,9 @@
* @file subset.test.ts
* @brief What the subset must REFUSE, and how it says so.
*
- * @details A checker that accepts everything is not a checker. Each case pins a
- * rule from §3 and asserts the refusal names a line and a reason —
- * §11's "coverage stalls low" is a diagnostics problem first.
+ * @details A checker that accepts everything is not a checker. Each case pins
+ * one rule of the subset and asserts the refusal names a line and a
+ * reason — coverage that stalls low is a diagnostics problem first.
*/
import { describe, it, expect } from 'vitest';
import { resolve } from 'node:path';
@@ -72,7 +72,7 @@ describe('the subset refuses, and says why', () => {
/**
* `@compiled` does not change what the subset takes; it changes who has to act.
- * An unmarked refusal is §3.2's design. A marked one is a build error.
+ * An unmarked refusal is the design. A marked one is a build error.
*/
describe('a promise the author wrote down', () => {
it('sees the marker, and only where it was written', () => {
diff --git a/docs/CODE_COMMENTS.md b/docs/CODE_COMMENTS.md
index f8585367d..d5bccee64 100644
--- a/docs/CODE_COMMENTS.md
+++ b/docs/CODE_COMMENTS.md
@@ -15,7 +15,8 @@
- **不留注释掉的死代码** —— 删就删(git 记得住)。
- **不留"墓碑"注释。** 删/移代码时**不要**再加一句注释说明"某某被删除了/移到哪了/曾经是什么"(如 `// (X was removed ...)`)——git 历史记得住,这种注释只会变噪音 + 过时信息。直接删干净。
- **自包含**:注释把"为什么"直接讲清楚,**能独立看懂**。
-- **不要在注释里写内部/临时的流程代号**(审计编号如 `A20`、工单号、私有缩写)——代码读者查不到、而且会过时(那些文档常常根本没进仓库)。确需指向长期存在的**已提交**文档时,写**真实路径**,如 `docs/REARCH_EDITOR_REALM.md`;`file.ts:123` 这种可定位的引用可以。
+- **不要在注释里写内部/临时的流程代号**(审计编号如 `A20`、工单号、章节号如 `§4.2`、私有缩写)——代码读者查不到、而且会过时。
+- **不要引用读者打不开的文档。** 指向文档时那份文档必须是**仓库里已提交的文件**(`docs/CODE_COMMENTS.md`、`README.md` 这类);`docs/REARCH_*.md` 全都在 `.gitignore` 里,指向它们等于指向别人机器上的文件。注释要**自己把话说完**:把章节里那句判断直接写下来,而不是让读者去取一份他没有的文档。`file.ts:123` 这种可定位的引用可以。由 `tools/check-comment-style.mjs` 的 `unreachable-doc` 规则按 git 索引判,只看新增行。
## 1. 文件头 `@file` / `@brief`
@@ -117,4 +118,4 @@ i++;
- [ ] 新增/改动的导出 API 有 `/** */`,且讲的是 why/契约而非签名?
- [ ] 内联注释解释的是"为什么",没有复述代码?
- [ ] 没有注释掉的死代码、没有裸 TODO?
-- [ ] 注释**自包含**,没有内部流程代号(如 `audit A20`、工单号)?指向文档时用的是已提交文件的真实路径?
+- [ ] 注释**自包含**,没有内部流程代号(如 `audit A20`、工单号、`§4.2`)?指向文档时那份文档确实已提交?
diff --git a/examples/ecs-basics/src/systems/move.ts b/examples/ecs-basics/src/systems/move.ts
index 2b87f63d7..d05b7972f 100644
--- a/examples/ecs-basics/src/systems/move.ts
+++ b/examples/ecs-basics/src/systems/move.ts
@@ -8,7 +8,7 @@ import { Mover } from '../components';
*
* @compiled
* A promise, not a hint: anything the subset cannot lower is a build error here
- * rather than a silent fall back to the interpreter (REARCH_AOT_ABI.md §4.1).
+ * rather than a silent fall back to the interpreter.
*/
export const moveSystem = defineSystem(
[Query(Mut(Transform), Mover), Res(Time)],
diff --git a/pipeline/src/bundle/buildScripts.ts b/pipeline/src/bundle/buildScripts.ts
index a95d6d239..68a549a49 100644
--- a/pipeline/src/bundle/buildScripts.ts
+++ b/pipeline/src/bundle/buildScripts.ts
@@ -1,7 +1,7 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
- * @file Project-script bundler (REARCH_EDITOR_REALM.md Phase P1 / RC12 §E8-1).
+ * @file Project-script bundler.
*
* Bundles a project's `src/main.ts` into a single ESM with `esengine` left
* EXTERNAL, written to `.esengine/cache/`. The bundle's bare `import ... from
diff --git a/sdk/src/ecs/ScriptPool.ts b/sdk/src/ecs/ScriptPool.ts
index b7de8315c..5e722a1fd 100644
--- a/sdk/src/ecs/ScriptPool.ts
+++ b/sdk/src/ecs/ScriptPool.ts
@@ -31,7 +31,7 @@ export interface PoolField {
readonly kind: PoolKind;
}
-/** One f64 per field: what the ABI gives a host record (REARCH_AOT_ABI §2.4). */
+/** One f64 per field: what the ABI gives a host record. */
export const POOL_SLOT_BYTES = 8;
/** A byte range the pool was given, and where it starts in the host's memory. */
@@ -131,7 +131,7 @@ export class ScriptPool {
* a constant stride, and a sparse table saying which slot an entity is in.
* Every address is in the memory the pool allocated from.
*
- * Valid until the next growth, which is per call anyway (§2.2).
+ * Valid until the next growth, which is per call anyway.
*/
span(): { rows: number; stride: number; sparse: number; sparseCount: number } {
return {
@@ -191,7 +191,7 @@ export class ScriptPool {
* The address a host hands to compiled code: the row's offset in the memory
* the pool allocated from, not in the pool's own view. The two differ by
* `byteOffset` once the rows are carved out of a larger block. Valid until
- * the next growth, which §2.2 requires anyway.
+ * the next growth, which a one-call lifetime requires anyway.
*/
address(entity: Entity): number | undefined {
const base = this.baseOf(entity);
diff --git a/sdk/src/ecs/ScriptStorage.ts b/sdk/src/ecs/ScriptStorage.ts
index ac8329f59..3d5daad54 100644
--- a/sdk/src/ecs/ScriptStorage.ts
+++ b/sdk/src/ecs/ScriptStorage.ts
@@ -24,7 +24,7 @@ export class ScriptStorage {
* Components held as rows rather than objects, by id. A component qualifies
* when its defaults are all scalars, which is exactly the set a compiled
* system can reach — a compiled system addresses a component, and a JS
- * object has no address (docs/REARCH_AOT_ABI.md §2.4).
+ * object has no address.
*/
private pools_ = new Map<symbol, ScriptPool>();
private poolMemory_: PoolMemory = HEAP_MEMORY;
diff --git a/sdk/src/ecs/aot/AotContext.ts b/sdk/src/ecs/aot/AotContext.ts
index 4a907de61..e2569243b 100644
--- a/sdk/src/ecs/aot/AotContext.ts
+++ b/sdk/src/ecs/aot/AotContext.ts
@@ -4,9 +4,8 @@
* @file AotContext.ts
* @brief The host half of the ABI, in the language that owns the maps.
*
- * @details docs/REARCH_AOT_ABI.md §2.1 gives the host four jobs: pack the rows,
- * resolve the resource addresses, ready the command buffer, and fill a
- * SysCtx. On web that host is TypeScript rather than C++, and not by
+ * @details The ABI gives the host four jobs: pack the rows, resolve the resource
+ * addresses, ready the command buffer, and fill a SysCtx. On web that host is TypeScript rather than C++, and not by
* preference — the query's candidate set and the script pools' slot
* maps are both here, so anything else would have to call back across
* the boundary once per entity per frame, which is the cost AOT exists
@@ -14,8 +13,8 @@
*
* Everything it writes goes into the ENGINE's linear memory, because
* that is where the compiled code reads. The arena is rebuilt per call:
- * §2.2 gives a row array a one-call lifetime, and reusing the block
- * rather than the contents is what keeps that free.
+ * a row array has a one-call lifetime, and reusing the block rather
+ * than the contents is what keeps that free.
*/
import type { PoolBlock, PoolMemory } from '../ScriptPool';
@@ -28,7 +27,7 @@ export {
SYSCTX_WORDS, QUERYROWS_WORDS, CMD_WORDS, CMD_DESPAWN, CMD_REMOVE,
} from './abiDigest';
-/** One record the compiled code appended (§2.3). */
+/** One record the compiled code appended. */
export interface AotCommand {
readonly kind: number;
readonly a: number;
@@ -37,7 +36,7 @@ export interface AotCommand {
/**
* The per-call scratch, in engine memory. One instance per system is enough —
- * a call is over before the next begins, and §2.2 says nothing may outlive it.
+ * a call is over before the next begins, and nothing may outlive it.
*/
export class AotContext {
private block: PoolBlock | null = null;
diff --git a/sdk/src/ecs/aot/AotRuntime.ts b/sdk/src/ecs/aot/AotRuntime.ts
index fd4c8d3dc..78272e994 100644
--- a/sdk/src/ecs/aot/AotRuntime.ts
+++ b/sdk/src/ecs/aot/AotRuntime.ts
@@ -33,8 +33,7 @@ export interface AotAddresses {
/**
* Installed by a shipping build, absent everywhere else. That absence is the
* whole of the mode policy: with no twins there is nothing to dispatch to, so
- * the editor and dev builds need no flag and take no branch worth measuring
- * (docs/REARCH_AOT.md §9).
+ * the editor and dev builds need no flag and take no branch worth measuring.
*/
export interface AotRuntime {
readonly systems: AotSystems;
diff --git a/sdk/src/ecs/aot/AotSystems.ts b/sdk/src/ecs/aot/AotSystems.ts
index 9c1ab7e3a..dc38f9a47 100644
--- a/sdk/src/ecs/aot/AotSystems.ts
+++ b/sdk/src/ecs/aot/AotSystems.ts
@@ -4,12 +4,12 @@
* @file AotSystems.ts
* @brief The compiled twins a build produced, and how a system finds its own.
*
- * @details `REARCH_AOT.md` §9 settles when a twin is used: the editor's preview
- * always interprets, and AOT is a shipping mode. So the runner has one
- * rule — call the twin if there IS one — and the decision lives in who
+ * @details When a twin is used is settled: the editor's preview always
+ * interprets, and AOT is a shipping mode. So the runner has one rule —
+ * call the twin if there IS one — and the decision lives in who
* installs, which is the build, once, at load.
*
- * Installing verifies the handshake first (§2.5). A module whose
+ * Installing verifies the handshake first. A module whose
* contract hash disagrees is REFUSED, not warned about: mismatched
* offsets do not produce an error, they produce a read of a different
* field.
diff --git a/sdk/src/ecs/aot/abiDigest.ts b/sdk/src/ecs/aot/abiDigest.ts
index 7a336070d..5eb8db462 100644
--- a/sdk/src/ecs/aot/abiDigest.ts
+++ b/sdk/src/ecs/aot/abiDigest.ts
@@ -30,7 +30,7 @@
import { PTR_LAYOUTS } from '../../wasm/ptrLayouts.generated';
import { RESOURCE_SHAPES } from '../resourceShapes';
-/** Sizes of the three ABI structs, in address-wide words (§2.1–2.3). */
+/** Sizes of the three ABI structs, in address-wide words. */
export const SYSCTX_WORDS = 6;
export const QUERYROWS_WORDS = 2;
/** A command is four u32 at every address width. */
diff --git a/sdk/src/ecs/aot/installAot.ts b/sdk/src/ecs/aot/installAot.ts
index 3c315f457..ab4b364bf 100644
--- a/sdk/src/ecs/aot/installAot.ts
+++ b/sdk/src/ecs/aot/installAot.ts
@@ -10,8 +10,8 @@
* wiring that was waiting for the handshake to be decided.
*
* The module IMPORTS the engine's memory, so there is nothing to link
- * and no engine change: it reads the components where they already are
- * (docs/REARCH_AOT.md §6.1).
+ * and no engine change: it reads the components where they already
+ * are.
*
* Refuses rather than degrades. A module built for other offsets does
* not produce a wrong answer, it produces a read of a different field,
diff --git a/sdk/src/ecs/bridge/BuiltinBridge.ts b/sdk/src/ecs/bridge/BuiltinBridge.ts
index 08f3479af..160acfc4c 100644
--- a/sdk/src/ecs/bridge/BuiltinBridge.ts
+++ b/sdk/src/ecs/bridge/BuiltinBridge.ts
@@ -683,7 +683,7 @@ export class BuiltinBridge {
/**
* Where `cppName`'s bytes are for an entity: what compiled code adds an EHT
- * offset to (§2.4). Through the {@link MemoryProvider}, the seam the fast
+ * offset to. Through the {@link MemoryProvider}, the seam the fast
* accessors already use — an address resolved a second way can disagree.
* Null where this backend serves no flat memory.
*/
diff --git a/sdk/src/ecs/component.ts b/sdk/src/ecs/component.ts
index eb989080e..0e8170ff5 100644
--- a/sdk/src/ecs/component.ts
+++ b/sdk/src/ecs/component.ts
@@ -283,7 +283,7 @@ function classifyKeys(obj: object): { flatKeys: string[]; objectKeys: string[];
// component storage instead of minting a fresh identity that silently misses every
// existing entity. Component DATA stays isolated per-App at the World/storage layer,
// not at the id, so sharing ids by name across contexts is safe — the same reason
-// builtins share one global id across every App. See docs/REARCH_HOT_RELOAD.md §3.
+// builtins share one global id across every App.
const componentIdRegistry = new Map<string, symbol>();
function componentId(name: string): symbol {
let id = componentIdRegistry.get(name);
diff --git a/sdk/src/ecs/resourceShapes.ts b/sdk/src/ecs/resourceShapes.ts
index 6f6023072..16ad3b392 100644
--- a/sdk/src/ecs/resourceShapes.ts
+++ b/sdk/src/ecs/resourceShapes.ts
@@ -7,7 +7,7 @@
* @details A compiled system reaches a resource by ADDRESS, so its fields need a
* layout, and a layout needs exactly one author. This is that author:
* `resource.ts` builds the resource from it, and the AOT compiler reads
- * it for the offsets (docs/REARCH_AOT_ABI.md §2.4).
+ * it for the offsets.
*
* A resource belongs here when every field is a number or a boolean —
* the same bar `defineComponent` shapes meet, and for the same reason:
diff --git a/sdk/src/ecs/system.ts b/sdk/src/ecs/system.ts
index 2c12ff0c1..181ff281a 100644
--- a/sdk/src/ecs/system.ts
+++ b/sdk/src/ecs/system.ts
@@ -408,7 +408,7 @@ export class SystemRunner {
/**
* Compiled twins, when a shipping build installed them. Absent in the editor
* and in dev, which is the whole of the mode policy — with nothing installed
- * there is nothing to dispatch to (docs/REARCH_AOT.md §9).
+ * there is nothing to dispatch to.
*/
private aot_: AotRuntime | null = null;
/** The compiled half of this runner: everything a twin needs around its call
diff --git a/sdk/src/ecs/world.ts b/sdk/src/ecs/world.ts
index 954a77795..f97535a98 100644
--- a/sdk/src/ecs/world.ts
+++ b/sdk/src/ecs/world.ts
@@ -1168,7 +1168,7 @@ export class World {
/**
* @internal Where script-component rows are allocated from. A wasm runtime
* installs linear memory here BEFORE any component is added, because
- * compiled code cannot reach a JS-heap array (docs/REARCH_AOT_ABI.md §2.4).
+ * compiled code cannot reach a JS-heap array.
*/
useScriptPoolMemory(memory: PoolMemory): void {
this.scripts_.usePoolMemory(memory);
diff --git a/src/esengine/aot/AotHost.hpp b/src/esengine/aot/AotHost.hpp
index 19bfafff3..bf3633b90 100644
--- a/src/esengine/aot/AotHost.hpp
+++ b/src/esengine/aot/AotHost.hpp
@@ -2,7 +2,7 @@
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file AotHost.hpp
- * @brief The host half of the Estella ABI (docs/REARCH_AOT_ABI.md §2.1).
+ * @brief The host half of the Estella ABI.
*
* @details A compiled system calls the engine ZERO times, which means everything
* it reads has to be in memory before the call. This puts it there:
@@ -15,8 +15,8 @@
* without linking the engine.
*
* The arena is reused across calls and rebuilt in each one, because
- * §2.2 gives a row array a one-call lifetime. Nothing here allocates
- * per row after the first frame at a given size.
+ * a row array has a one-call lifetime. Nothing here allocates per row
+ * after the first frame at a given size.
*/
#pragma once
@@ -173,8 +173,8 @@ struct BoundSystem {
/**
* Resolve `decl` against this host. A component or resource the host cannot
- * name leaves `fn` null: the system is simply not run, which is §3.2's fallback
- * arriving one layer down rather than a crash at the first row.
+ * name leaves `fn` null: the system is simply not run, which is the interpreter
+ * fallback arriving one layer down rather than a crash at the first row.
*/
inline BoundSystem bind(const EsSystemDecl& decl,
const ComponentLookup& components,
@@ -212,7 +212,7 @@ inline std::span<const EsCmd> runBound(const BoundSystem& bound,
/**
* The constant a compiled artifact exports, as this host computes it. The
* contract half comes from the artifact; the width is ours, and mixing it here
- * is what stops a 32-bit artifact loading into a 64-bit host (§2.5).
+ * is what stops a 32-bit artifact loading into a 64-bit host.
*/
inline std::uint64_t abiHash(std::uint64_t contract) {
return contract ^ (0x9e3779b97f4a7c15ULL * sizeof(es_addr_t));
diff --git a/src/esengine/aot/estella_abi.h b/src/esengine/aot/estella_abi.h
index ca92c3de5..04d6a0aa0 100644
--- a/src/esengine/aot/estella_abi.h
+++ b/src/esengine/aot/estella_abi.h
@@ -1,5 +1,5 @@
/* GENERATED by @estella/compiler — do not edit. */
-/* The Estella ABI, C side. docs/REARCH_AOT_ABI.md */
+/* The Estella ABI, C side. */
#ifndef ESTELLA_ABI_H
#define ESTELLA_ABI_H
@@ -21,7 +21,7 @@
mixed into the handshake so a 32-bit artifact cannot load into a 64-bit host.
ES_ADDR_BASE is the other model: a host that owns one block and addresses it
- by offset. A wasm2c deployment (§5) is one, and so is the differential
+ by offset. A wasm2c deployment is one, and so is the differential
harness. Same structs, same offsets, one word wider or narrower. */
#if defined(ES_ADDR_BASE)
typedef uint32_t es_addr_t;
@@ -32,14 +32,14 @@ typedef uintptr_t es_addr_t;
#define ES_PTR(a) ((unsigned char *)(a))
#endif
-/* §2.2 — the packed rows the host materialised: for each row, the entity and
+/* The packed rows the host materialised: for each row, the entity and
then one base address per component the query named, in that order. */
typedef struct EsQueryRows {
es_addr_t rows;
es_addr_t count;
} EsQueryRows;
-/* §2.3 — four u32, sixteen bytes, at every address width. */
+/* A command: four u32, sixteen bytes, at every address width. */
typedef struct EsCmd {
uint32_t kind;
uint32_t a;
@@ -50,7 +50,7 @@ typedef struct EsCmd {
#define ES_CMD_DESPAWN 1u
#define ES_CMD_REMOVE 2u
-/* §2.1 — 6 addresses. §6.3 makes that a number needing a reason to grow. */
+/* 6 addresses, and a number that needs a reason to grow. */
typedef struct EsSysCtx {
es_addr_t queries;
es_addr_t resources;
@@ -60,7 +60,7 @@ typedef struct EsSysCtx {
es_addr_t events;
} EsSysCtx;
-/* §6: what a host needs in order to CALL a system without glue written by hand.
+/* What a host needs in order to CALL a system without glue written by hand.
The compiler knows a system's queries and resources -- that is what _params
is -- so it says so here rather than leaving each host to be told twice. */
typedef struct EsQueryDecl {
@@ -78,8 +78,8 @@ typedef struct EsSystemDecl {
uint32_t resourceCount;
} EsSystemDecl;
-/* §6.1 asks that the C and TS sides of these structs have ONE author, and that a
- hand-written side fail to compile. The numbers below are written by that author
+/* The C and TS sides of these structs have ONE author, and a side that drifts
+ from it must fail to compile. The numbers below are written by that author
(compiler/src/abi.ts) into this file; these three declarations are how C says
no if a struct above ever stops matching them. */
typedef char es_check_sysctx[sizeof(EsSysCtx) == 6 * sizeof(es_addr_t) ? 1 : -1];
diff --git a/tests/aot/test_aot_host.cpp b/tests/aot/test_aot_host.cpp
index 18de7e237..2c0bba32e 100644
--- a/tests/aot/test_aot_host.cpp
+++ b/tests/aot/test_aot_host.cpp
@@ -209,8 +209,8 @@ TEST_CASE("a system naming something this host cannot is simply not bound") {
World w = makeWorld();
const EsSystemDecl* decl = declOf("MoveSystem");
REQUIRE(decl != nullptr);
- // §3.2's fallback, one layer down: a host missing a component does not get
- // a system that reads null, it gets no system.
+ // The interpreter fallback, one layer down: a host missing a component does
+ // not get a system that reads null, it gets no system.
const aot::BoundSystem none = aot::bind(
*decl, [](const char*) { return aot::ComponentAt{}; }, resourcesOf(w));
CHECK(none.fn == nullptr);
diff --git a/tools/check-comment-style.mjs b/tools/check-comment-style.mjs
index 242575115..016de420f 100644
--- a/tools/check-comment-style.mjs
+++ b/tools/check-comment-style.mjs
@@ -47,8 +47,45 @@ const RULES = [
test: /\b(RC\d+|P[0-3]\b|Phase \d|Batch [A-Z]\b|gap \d|audit [A-Z]\d)/,
say: 'internal stage/roadmap codename — name the thing, not the plan it came from',
},
+ {
+ id: 'unreachable-doc',
+ // A pointer the reader cannot follow: a section sign is a codename wearing a
+ // number, and an uncommitted markdown path names a file on somebody else's
+ // disk — which the gitignored design docs here have always been.
+ test: (text) => /§/.test(text) || docRefs(text).some((d) => !isTracked(d)),
+ say: 'points at something the reader cannot open — say what it says, or cite a committed path',
+ },
];
+/** Markdown paths named in a comment, as written. */
+function docRefs(text) {
+ return [...text.matchAll(/[\w./-]+\.md\b/g)].map((m) => m[0]);
+}
+
+/**
+ * Every path git has, plus their basenames, because a comment cites a document
+ * by bare filename as often as by its full path and both mean one file. Empty
+ * means the question could not be asked, and a scan that cannot ask must not
+ * answer green.
+ */
+const TRACKED = (() => {
+ let out = '';
+ try {
+ out = execFileSync('git', ['ls-files'], { cwd: ROOT, encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 });
+ } catch { /* reported below */ }
+ const files = out.split('\n').filter(Boolean);
+ if (files.length === 0) {
+ console.error('check-comment-style: `git ls-files` gave nothing — cannot judge doc references.');
+ process.exit(2);
+ }
+ return new Set([...files, ...files.map((f) => f.slice(f.lastIndexOf('/') + 1))]);
+})();
+
+function isTracked(ref) {
+ const clean = ref.replace(/^\.\//, '');
+ return TRACKED.has(clean) || TRACKED.has(clean.slice(clean.lastIndexOf('/') + 1));
+}
+
/** Added lines per file, as [lineNumber, text]. */
function addedLines() {
let base = '';
@@ -173,7 +210,8 @@ function scan(byFile) {
block.push([n, text]);
prev = n;
for (const rule of RULES) {
- if (rule.test.test(text)) findings.push({ file, line: n, id: rule.id, say: rule.say, text: text.trim() });
+ const hit = typeof rule.test === 'function' ? rule.test(text) : rule.test.test(text);
+ if (hit) findings.push({ file, line: n, id: rule.id, say: rule.say, text: text.trim() });
}
}
flushBlock();
diff --git a/tools/check-pipeline-boundary.mjs b/tools/check-pipeline-boundary.mjs
index f091bde81..0bfddbc2f 100644
--- a/tools/check-pipeline-boundary.mjs
+++ b/tools/check-pipeline-boundary.mjs
@@ -26,7 +26,7 @@ const SOURCE = /\.(ts|mts|js|mjs)$/;
/** Repo areas the pipeline is allowed to read: the engine it packages, the
* format writers it packages with, and the AOT compiler — which is a thing that
* BUILDS a project, the same category as build-tools, not a thing that edits
- * one (docs/REARCH_AOT.md Stage 4). */
+ * one. */
const REACHABLE = ['sdk/src', 'build-tools', 'tools', 'compiler/src'];
/** Packages that only exist inside a running editor. */
diff --git a/tools/gates.mjs b/tools/gates.mjs
index cb0cd97b0..938ca5e84 100644
--- a/tools/gates.mjs
+++ b/tools/gates.mjs
@@ -82,7 +82,7 @@ export const GATES = [
// until the editor split, where a checkout without the editor ran none of them.
{ id: 'engine-tests', run: 'pnpm run test' },
// The AOT compiler carries its own oracle: a real example system lowered to
- // EIR must move a world exactly the way node moves it (docs/REARCH_AOT.md §8.1).
+ // EIR must move a world exactly the way node moves it.
// It also compiles the emitted C and requires the same bytes back: natively
// with any C compiler, and as wasm where emsdk is unpacked. Without either it
// still passes and PRINTS that the differential did not run — read the log.