Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

test(cache): terminate real updates before atomic commits

yhh9f018ab3b179
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index 8036e1c75..5b76a1904 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -798,6 +798,10 @@ jobs:
if: ${{ !cancelled() && matrix.shard == 3 }}
run: pnpm run verify:cache-budget
+ - name: Check interrupted cache and manifest commits survive a new process
+ if: ${{ !cancelled() && matrix.shard == 3 }}
+ run: node tools/cache-budget-demo.mjs
+
- name: Keep cache cleanup and offline restart evidence
if: ${{ !cancelled() && matrix.shard == 3 }}
uses: actions/upload-artifact@v7
diff --git a/docs/CACHE_BUDGET.md b/docs/CACHE_BUDGET.md
index 15229598c..f7b23b2a5 100644
--- a/docs/CACHE_BUDGET.md
+++ b/docs/CACHE_BUDGET.md
@@ -72,9 +72,13 @@ node tools/cache-budget-demo.mjs
```
It serves three eight-byte resource versions over a local HTTP server, applies
-two updates, removes the oldest version, closes the server and starts a new
-process with network access rejected. The new process must read both current and
-rollback bytes. Node's default key/value storage is session-local, so the fixture
+two updates and removes the oldest version. Two additional update processes are
+terminated at resource-rename and manifest-rename checkpoints after real temporary
+bytes reach disk. The server then closes and a new process starts with network
+access rejected. It must read both current and rollback bytes, reclaim the complete
+uncommitted version, and preserve the interrupted resource temporary. The checkpoints
+pause the production adapter at pre-commit boundaries; termination is a real
+`SIGKILL`, not a simulated exception. Node's default key/value storage is session-local, so the fixture
explicitly supplies a durable host store for the active manifest. Mini-game and
native hosts already supply their own persistent key/value storage.
diff --git a/docs/CACHE_BUDGET_REVIEW_2026-10-13.md b/docs/CACHE_BUDGET_REVIEW_2026-10-13.md
index 05ea71f5d..ee30e24c5 100644
--- a/docs/CACHE_BUDGET_REVIEW_2026-10-13.md
+++ b/docs/CACHE_BUDGET_REVIEW_2026-10-13.md
@@ -1,9 +1,12 @@
# v0.78.0 card review and cache-budget verification — 2026-10-13
-The verified branch is based on engine `4e32ff5cc4ab06b33267a2333293ed69b19c83bc`
-and editor `ba95cde5127b5a6c8c24f2860f365397b20a0071`. Draft reviews are
+The current combined branch includes engine `8f1641e9e` and both v0.78.0 card
+implementations. Cache draft reviews are
[engine #95](https://github.com/esengine/estella/pull/95) and
[editor #20](https://github.com/esengine/estella-editor/pull/20).
+The subsequent incremental-baking drafts, [engine #96](https://github.com/esengine/estella/pull/96)
+and [editor #21](https://github.com/esengine/estella-editor/pull/21), are stacked
+on those cache branches so both workflows remain in the combined tree.
The initial review used engine `acdc5ded8cc939d81cbb2128d12e93609c0b3da1`
and editor `53e998badfa4dfce0d377c0c29b6107502bb893d`, before the rebase below.
[v0.78.0](https://github.com/esengine/estella/releases/tag/v0.78.0) was published
@@ -197,3 +200,24 @@ not inferred from local passes. A final fetch brought in two mainline commits fo
golden output paths and authored audio playback; the branch rebased cleanly onto
`4e32ff5cc`. Those commits change example/test/changelog files, with no C++ or SDK
runtime change. The existing compiled runtime artifacts still match their source.
+
+## Real process-interruption acceptance
+
+`node tools/cache-budget-demo.mjs` now launches two real update processes for v4.
+The production adapter is paused after temporary bytes have been written but
+before resource rename (8 B) and before durable active-manifest rename (399 B).
+Each child is actually terminated with `SIGKILL`; this is a deterministic
+pre-commit checkpoint, not an exception pretending the process disappeared.
+
+After both interruptions the HTTP server is closed, network access is rejected,
+and another process restores v3 current and v2 rollback, eight correct bytes
+each. Missing protected resources = 0. Cleanup releases eight bytes of the
+uncommitted complete v4 resource and keeps the eight-byte interrupted resource
+temporary protected. The final 24 B cannot meet a 16 B resource budget because
+the unknown temporary remains protected; the report does not claim success.
+The durable host-store temporary is outside the resource-cache accounting.
+
+The same demonstration now runs in golden CI shard 3. Local output is
+`output/cache-crash.log` in the combined worktree. This strengthens crash/restart
+evidence for the Node filesystem contract; physical WeChat acceptance remains
+pending and is not substituted by this run.
diff --git a/tools/fixtures/cache-budget-demo.ts b/tools/fixtures/cache-budget-demo.ts
index 53a8b98e9..e76d35bb8 100644
--- a/tools/fixtures/cache-budget-demo.ts
+++ b/tools/fixtures/cache-budget-demo.ts
@@ -4,10 +4,13 @@ import { createServer } from 'node:http';
import { mkdirSync, readFileSync, writeFileSync, renameSync } from 'node:fs';
import { join } from 'node:path';
import { execFileSync } from 'node:child_process';
+import { fork } from 'node:child_process';
+import { createRequire, syncBuiltinESMExports } from 'node:module';
import { Assets } from '../../sdk/src/asset/Assets';
import { HttpBackend } from '../../sdk/src/asset/Backend';
import { contentHashHex } from '../../sdk/src/asset/contentHash';
import { nodeAdapter } from '../../sdk/src/platform/node';
+import { cacheEntryName } from '../../sdk/src/platform/cacheEntryName';
import { setPlatform, platformWriteCacheFile } from '../../sdk/src/platform/base';
import type { AddressableManifest } from '../../sdk/src/asset/AddressableManifest';
@@ -44,8 +47,77 @@ async function offline(scratch: string, root: string) {
const current = new Uint8Array(await backend.fetchBinary(assetUrl(root, 3)));
const rollback = new Uint8Array(await backend.fetchBinary(assetUrl(root, 2)));
if (a.updateStatus().revision !== 'v3' || current.some(b => b !== 3) || rollback.some(b => b !== 2)) throw Error('offline verification failed');
+ const report = await a.diskCacheReport();
+ const cleanup = await a.cleanDiskCache(16, true);
+ if (report.versions.some(v => v.reason && v.missing) || cleanup.releaseBytes !== 8
+ || cleanup.report.entries.filter(e => e.name.endsWith('.tmp')).length !== 1
+ || cleanup.report.entries.some(e => e.name.endsWith('.tmp') && !e.protection.includes('unindexed'))) {
+ throw Error('crash recovery did not preserve protected versions and the interrupted temporary');
+ }
return { revision: a.updateStatus().revision, currentBytes: current.byteLength,
- rollbackBytes: rollback.byteLength, networkAllowed: false, freshProcess: true };
+ rollbackBytes: rollback.byteLength, networkAllowed: false, freshProcess: true,
+ protectedMissing: 0, releasedUncommittedBytes: cleanup.releaseBytes,
+ interruptedTemporaryProtected: true, remainingBytes: cleanup.remainingBytes };
+}
+
+type CrashPhase = 'resource-rename' | 'manifest-rename';
+
+async function interrupted(scratch: string, root: string, phase: CrashPhase) {
+ host(scratch, false);
+ const require = createRequire(import.meta.url);
+ const fs = require('node:fs') as typeof import('node:fs');
+ const asyncFs = require('node:fs/promises') as typeof import('node:fs/promises');
+ if (phase === 'resource-rename') {
+ const rename = asyncFs.rename;
+ asyncFs.rename = async (from, to) => {
+ if (String(to) === join(scratch, 'cache', cacheEntryName(assetUrl(root, 4)))) {
+ process.send!({ phase, temporaryBytes: readFileSync(from).byteLength });
+ await new Promise(() => {});
+ }
+ await rename(from, to);
+ };
+ } else {
+ const rename = fs.renameSync;
+ fs.renameSync = (from, to) => {
+ if (String(to) === join(scratch, 'state', 'active.json')) {
+ process.send!({ phase, temporaryBytes: readFileSync(from).byteLength });
+ Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0);
+ }
+ rename(from, to);
+ };
+ }
+ // Hold the production adapter at the pre-commit boundary after real bytes
+ // reached disk; the parent then terminates this process, not a mocked write.
+ syncBuiltinESMExports();
+ const a = assets(root);
+ await a.checkForUpdate({ manifestUrl: `${root}/manifest.json` });
+ await a.applyUpdate();
+ throw Error('the update committed before the crash checkpoint');
+}
+
+function crash(scratch: string, bundle: string, root: string, phase: CrashPhase): Promise<object> {
+ return new Promise((resolve, reject) => {
+ const child = fork(bundle, ['--crash', scratch, root, phase],
+ { silent: true, windowsHide: true, execArgv: [] });
+ let marker: { phase: CrashPhase; temporaryBytes: number } | null = null;
+ let failure = '', stderr = '';
+ child.stderr!.on('data', bytes => { stderr = (stderr + String(bytes)).slice(-2000); });
+ const timeout = setTimeout(() => {
+ failure = 'the crash checkpoint was not reached'; child.kill('SIGKILL');
+ }, 10_000);
+ child.once('error', error => { clearTimeout(timeout); reject(error); });
+ child.on('message', message => {
+ const point = message as typeof marker;
+ if (point?.phase === phase && point.temporaryBytes > 0) {
+ marker = point; child.kill('SIGKILL');
+ }
+ });
+ child.once('exit', (code, signal) => {
+ clearTimeout(timeout);
+ if (failure || !marker || code === 0) reject(Error(`${failure || 'unexpected child exit'}: ${stderr}`));
+ else resolve({ ...marker, exitCode: code, signal, terminated: true });
+ });
+ });
}
export async function run(scratch: string, bundle: string) {
@@ -69,11 +141,17 @@ export async function run(scratch: string, bundle: string) {
const before = await a.diskCacheReport();
const preview = await a.cleanDiskCache(16);
const cleaned = await a.cleanDiskCache(16, true);
+ revision = 4;
+ const crashes = [];
+ for (const phase of ['resource-rename', 'manifest-rename'] as const)
+ crashes.push(await crash(scratch, bundle, root, phase));
await new Promise<void>(resolve => server.close(() => resolve()));
const restarted = JSON.parse(execFileSync(process.execPath, [bundle, '--offline', scratch, root], { encoding: 'utf8' }));
return { stages, before: { bytes: before.usedBytes, protected: before.protectedBytes, reclaimable: before.reclaimableBytes },
preview: { files: preview.candidates.length, releaseBytes: preview.releaseBytes },
- cleanup: { releaseBytes: cleaned.releaseBytes, remaining: cleaned.remainingBytes, budgetMet: cleaned.budgetMet }, offline: restarted };
+ cleanup: { releaseBytes: cleaned.releaseBytes, remaining: cleaned.remainingBytes, budgetMet: cleaned.budgetMet },
+ crashes, offline: restarted };
} finally { if (server.listening) server.close(); }
}
if (process.argv[2] === '--offline') console.log(JSON.stringify(await offline(process.argv[3], process.argv[4])));
+if (process.argv[2] === '--crash') await interrupted(process.argv[3], process.argv[4], process.argv[5] as CrashPhase);