A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
test(cache): terminate real updates before atomic commits
yhh9f018ab3b179
diff --git a/.github/workflows/build.yml b/.github/workflows/build.ymlindex 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 evidenceif: ${{ !cancelled() && matrix.shard == 3 }}uses: actions/upload-artifact@v7diff --git a/docs/CACHE_BUDGET.md b/docs/CACHE_BUDGET.mdindex 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 fixtureexplicitly supplies a durable host store for the active manifest. Mini-game andnative 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.mdindex 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 fogolden output paths and authored audio playback; the branch rebased cleanly onto`4e32ff5cc`. Those commits change example/test/changelog files, with no C++ or SDKruntime 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.tsindex 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);