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.

fix(cache): repair legacy entries and verify release artifacts

yhh585d7a6607cc
diff --git a/build-tools/tasks/wasm.js b/build-tools/tasks/wasm.js
index aa50a328a..fe377dd66 100644
--- a/build-tools/tasks/wasm.js
+++ b/build-tools/tasks/wasm.js
@@ -1,8 +1,10 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import path from 'path';
-import { mkdir, cp, rm, stat, readFile } from 'fs/promises';
+import { mkdir, cp, rm, stat, readFile, rename } from 'fs/promises';
import { existsSync } from 'fs';
+import { fileURLToPath } from 'node:url';
+import { randomUUID } from 'node:crypto';
import config from '../build.config.js';
import * as logger from '../utils/logger.js';
import { runCommand, getCpuCount } from '../utils/emscripten.js';
@@ -51,12 +53,17 @@ async function computeWasmHash(target, targetConfig, debug) {
// changed — which is a wasm that does not match the flags it was asked for.
const toolchainHash = await hashDirectory(path.join(rootDir, 'cmake'), /\.cmake$/);
const configHash = await hashFiles([cmakeLists]);
+ // The post-link optimizer is part of what a cached build promises. A change
+ // to its transaction or optimization level must not reuse yesterday's output.
+ const builderHash = await hashFiles([fileURLToPath(import.meta.url)]);
const { createHash } = await import('crypto');
return createHash('md5')
.update(sourceHash)
.update(configHash)
.update(toolchainHash)
+ .update(builderHash)
+ .update(JSON.stringify(config.optimization[target] ?? {}))
.update(flagsKey)
.digest('hex');
}
@@ -205,31 +212,33 @@ async function executeWasmBuild(target, targetConfig, { debug, clean, buildDir,
await copyOutputs(buildDir, outputDir, targetConfig.outputs);
}
-async function optimizeWasmFiles(buildDir, outputs, optLevel = '-O2', env = undefined) {
+export async function optimizeWasmFiles(buildDir, outputs, optLevel = '-O2', env = undefined) {
const wasmFiles = Object.keys(outputs).filter(src => src.endsWith('.wasm'));
if (wasmFiles.length === 0) return;
- const warnings = [];
for (const src of wasmFiles) {
const wasmPath = path.join(buildDir, src);
if (!existsSync(wasmPath)) continue;
+ const optimizedPath = `${wasmPath}.opt-${randomUUID()}.wasm`;
try {
const before = (await stat(wasmPath)).size;
- await runCommand('wasm-opt', [optLevel, '--enable-bulk-memory', '--enable-nontrapping-float-to-int', '--enable-simd', '-o', wasmPath, wasmPath], { silent: true, env });
- const after = (await stat(wasmPath)).size;
+ await runCommand('wasm-opt', [optLevel, '--enable-bulk-memory', '--enable-nontrapping-float-to-int', '--enable-simd', '-o', optimizedPath, wasmPath], { silent: true, env });
+ const bytes = await readFile(optimizedPath);
+ if (!WebAssembly.validate(bytes)) throw new Error('optimizer produced invalid WASM');
+ const after = bytes.byteLength;
+ await rename(optimizedPath, wasmPath);
const reduction = ((1 - after / before) * 100).toFixed(1);
logger.debug(`wasm-opt ${optLevel}: ${src} ${(before / 1024).toFixed(0)}KB → ${(after / 1024).toFixed(0)}KB (-${reduction}%)`);
- } catch {
- const msg = `wasm-opt failed for ${src}, skipping optimization`;
- logger.warn(msg);
- warnings.push(msg);
+ } catch (error) {
+ // Keep the original artifact intact; never label a failed release
+ // stage successful or copy a partially overwritten file to the SDK.
+ throw new Error(`wasm-opt ${optLevel} failed for ${src}: ${error.stderr?.trim() || error.message}`, { cause: error });
+ } finally {
+ await rm(optimizedPath, { force: true, maxRetries: 10, retryDelay: 50 });
}
}
- if (warnings.length > 0) {
- logger.warn(`wasm-opt completed with ${warnings.length} warning(s)`);
- }
}
async function copyOutputs(buildDir, outputDir, outputs) {
diff --git a/docs/CACHE_BUDGET_REVIEW_2026-10-13.md b/docs/CACHE_BUDGET_REVIEW_2026-10-13.md
index 15cffaa08..497b5a6cc 100644
--- a/docs/CACHE_BUDGET_REVIEW_2026-10-13.md
+++ b/docs/CACHE_BUDGET_REVIEW_2026-10-13.md
@@ -139,3 +139,47 @@ shared-owner case; the final rerun is recorded with the PR validation.
`adb devices -l` returned no attached devices. Physical-device acceptance remains
an explicit gap; neither rendered simulation nor an eventual merged PR closes it.
+
+## Final branch validation and draft review
+
+The work was rebased onto engine `19f7ec25279717b874afcae87d2c5e047b458f7b`
+and editor `ba95cde5127b5a6c8c24f2860f365397b20a0071` after fetching another
+12 engine commits and one editor commit. Editor draft review is
+[#20](https://github.com/esengine/estella-editor/pull/20); it is not merged.
+
+Both current runtime targets were rebuilt with Emscripten 5.0.7, unchanged release
+optimization flags, `BINARYEN_CORES=1`, `EMCC_DEBUG=1` (intermediate-file diagnostics)
+and independent `EMCC_TEMP_DIR` directories. Earlier normal-link optimization
+assertions also occurred on 5.0.7; upgrading alone is not claimed to fix them.
+Standalone replay with the same optimizer flags succeeded. The final post-link
+optimization is now mandatory, uses a separate temporary output, validates it and
+commits it atomically instead of warning and copying an unoptimized/partial file.
+Build fingerprints include this transaction and the optimization level.
+
+The transactional optimizer has three passing regression cases: a crash after
+writing output preserves the original, successful-but-invalid output is rejected,
+and valid output commits without using the input file as the output destination.
+Final Web and WeChat build logs are local in `output/cache-budget/build-web-latest.log`
+and `build-wechat-latest.log`, with no skipped post-link optimization.
+
+The final targeted SDK run passed **168 tests across 14 files**. Editor interaction
+tests passed **3/3**, and optimizer tests passed **3/3**. The Web export/renderer
+verification passed again against the rebased current runtime. Optional side
+modules remain outside this targeted run; no full-engine suite pass is claimed.
+
+Rescan now recovers a referenced legacy resource's URL/hash from its manifest
+identity while retaining saves, orphan files and interrupted temporaries. A
+regression proves that a repaired legacy version can later be reclaimed. Cache
+writes also return unsupported when a host has adapter methods but no usable
+cache storage, preventing a false stored/cached result.
+
+The rendered verifier owns an isolated Electron user-data directory and exports
+packages in an asynchronous child, keeping Electron's service startup responsive.
+Profile isolation alone still failed with `ERR_FAILED (-2)`; the following run
+with asynchronous export passed. The synchronous export was a possible source of
+startup starvation, not a proven Electron root cause. Failed runs remain in
+`minigame-final.log` and `minigame-recheck.log`; the successful current run is in
+`minigame-async.log` and `output/cache-budget/render/verification.json`.
+It rendered green/red/blue, released 209 B while preserving 418 B of current and
+rollback resources, kept pixels identical, and restarted offline without a CDN
+request. This is contract-host evidence, not physical-device acceptance.
diff --git a/sdk/src/platform/base.ts b/sdk/src/platform/base.ts
index 2dab556a0..3bb2e6912 100644
--- a/sdk/src/platform/base.ts
+++ b/sdk/src/platform/base.ts
@@ -221,7 +221,7 @@ export async function platformReadCacheFile(key: string): Promise<ArrayBuffer |
export async function platformWriteCacheFile(key: string, bytes: ArrayBuffer): Promise<'stored' | 'failed' | 'unsupported'> {
if (!isPlatformInitialized()) return 'unsupported';
const p = getPlatform();
- if (!p.writeCacheFile) return 'unsupported';
+ if (!p.writeCacheFile || p.hasCacheStorage?.() === false) return 'unsupported';
try {
await contentCacheFor(p).write(key, bytes);
return 'stored';
diff --git a/sdk/src/platform/contentCache.ts b/sdk/src/platform/contentCache.ts
index c60e61ad8..d642b0cfa 100644
--- a/sdk/src/platform/contentCache.ts
+++ b/sdk/src/platform/contentCache.ts
@@ -156,13 +156,30 @@ export class ContentCache {
});
}
- private async scan_(): Promise<void> {
+ private async scan_(repair = false): Promise<void> {
const index = await this.load_();
const files = await this.platform_.listCacheFiles!();
const known = new Map(index.entries.map(e => [e.name, e]));
index.entries = files.filter(f => f.name !== INDEX_NAME).map(f => ({ ...known.get(f.name), ...f,
lastAccess: Math.max(known.get(f.name)?.lastAccess ?? 0, f.lastAccess) }));
this.indexBytes_ = files.find(f => f.name === INDEX_NAME)?.size ?? 0;
+ if (repair) {
+ // A surviving manifest gives an old file a resource identity even
+ // when its index was lost. Infer only exact URL-name matches; saves,
+ // orphan files and interrupted temporaries remain unindexed/pinned.
+ const referenced = new Map<string, string>();
+ for (const versions of Object.values(index.owners)) for (const version of versions)
+ for (const key of version.keys) referenced.set(cacheEntryName(key), key);
+ for (const entry of index.entries) {
+ const key = referenced.get(entry.name);
+ if (entry.key || !key) continue;
+ const bytes = await this.platform_.readCacheFile!(key).catch(() => null);
+ if (!bytes) continue;
+ entry.key = key;
+ entry.hash = contentHashHex(new Uint8Array(bytes));
+ entry.size = bytes.byteLength;
+ }
+ }
}
/** Explicit retention lives under its own owner, so advancing the automatic
@@ -228,7 +245,7 @@ export class ContentCache {
async report(rescan = false): Promise<ContentCacheReport> {
if (this.capability() !== 'managed') return this.report_();
return this.run_(async () => {
- await this.scan_();
+ await this.scan_(rescan);
if (rescan) await this.save_();
return this.report_();
});
diff --git a/sdk/tests/content-cache-budget.test.ts b/sdk/tests/content-cache-budget.test.ts
index efec4695c..cf4ca180c 100644
--- a/sdk/tests/content-cache-budget.test.ts
+++ b/sdk/tests/content-cache-budget.test.ts
@@ -148,6 +148,17 @@ describe('disk cache budget and offline versions', () => {
expect(await c.read(urls[0])).toEqual(bytes());
});
+ it('repairs a legacy resource from manifest references so retiring its version can reclaim it', async () => {
+ const c = await cache();
+ await nodeAdapter.writeCacheFile(urls[0], bytes()); // Pre-index build.
+ await c.protect('game', [{ revision: 'v1', reason: 'current', keys: [urls[0]] }]);
+ expect((await c.report()).entries[0].protection).toContain('unindexed');
+ const repaired = await c.report(true);
+ expect(repaired.entries[0]).toMatchObject({ key: urls[0], hash: expect.any(String), protection: ['game:current'] });
+ await c.protect('game', [{ revision: 'v2', reason: 'current', keys: [urls[1]] }]);
+ expect((await c.cleanup(0, true)).releaseBytes).toBe(8);
+ });
+
it('distinguishes unsupported management from an empty cache', async () => {
const noStorage = new ContentCache({} as PlatformAdapter);
expect(await noStorage.report()).toMatchObject({ capability: 'unavailable', usedBytes: null });
diff --git a/sdk/tests/content-cache.test.ts b/sdk/tests/content-cache.test.ts
index f7aa5f37b..0cb37fcb0 100644
--- a/sdk/tests/content-cache.test.ts
+++ b/sdk/tests/content-cache.test.ts
@@ -149,6 +149,12 @@ describe('node adapter disk cache (real filesystem)', () => {
});
describe('cache wrappers degrade on a platform with no cache (web)', () => {
+ it('does not claim storage when an adapter method exists but the host has no cache bindings', async () => {
+ const write = vi.fn(async () => {});
+ setPlatform(mockPlatform({ writeCacheFile: write, hasCacheStorage: () => false }));
+ expect(await platformWriteCacheFile('k', new ArrayBuffer(2))).toBe('unsupported');
+ expect(write).not.toHaveBeenCalled();
+ });
it('read returns null and write says unsupported when the adapter omits the methods', async () => {
setPlatform(mockPlatform({})); // no readCacheFile / writeCacheFile
expect(await platformReadCacheFile('k')).toBeNull();
diff --git a/sdk/tests/minigame-content-cache.test.ts b/sdk/tests/minigame-content-cache.test.ts
index f22260f94..9d5a927c9 100644
--- a/sdk/tests/minigame-content-cache.test.ts
+++ b/sdk/tests/minigame-content-cache.test.ts
@@ -58,9 +58,9 @@ describe('a mini-game content cache', () => {
expect(await platformWriteCacheFile(URL, new ArrayBuffer(4))).toBe('failed');
});
- it('reports a host with no user data directory as failed, not stored', async () => {
+ it('reports a host with no user data directory as unsupported, not stored', async () => {
host();
- expect(await platformWriteCacheFile(URL, new ArrayBuffer(4))).toBe('failed');
+ expect(await platformWriteCacheFile(URL, new ArrayBuffer(4))).toBe('unsupported');
expect(await platformReadCacheFile(URL)).toBeNull();
});
diff --git a/tools/launchers/cache-budget-render-verify.mjs b/tools/launchers/cache-budget-render-verify.mjs
index f1bafe4ea..920077716 100644
--- a/tools/launchers/cache-budget-render-verify.mjs
+++ b/tools/launchers/cache-budget-render-verify.mjs
@@ -5,9 +5,11 @@
import { app, BrowserWindow } from 'electron';
import http from 'node:http';
import { mkdir, readFile, writeFile, readdir, stat, rename, unlink } from 'node:fs/promises';
+import { mkdirSync } from 'node:fs';
import path from 'node:path';
import { createRequire } from 'node:module';
-import { execFileSync } from 'node:child_process';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
import { randomUUID, createHash } from 'node:crypto';
import { fileURLToPath } from 'node:url';
import { HOST_PAGE } from './minigameHost.mjs';
@@ -17,6 +19,11 @@ import { onRendererConsole } from '../lib/rendererConsole.mjs';
const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
const OUT = path.join(ROOT, 'output/cache-budget/render');
const STORE = path.join(OUT, `cache-${randomUUID()}`);
+// Other headless verifiers use Electron too. Sharing its default user-data
+// profile can race their network-service shutdown; this run owns its profile.
+const PROFILE = path.join(OUT, `profile-${randomUUID()}`);
+mkdirSync(PROFILE, { recursive: true });
+app.setPath('userData', PROFILE);
const { WebSocketServer } = createRequire(path.join(ROOT, 'sdk/package.json'))('ws');
app.commandLine.appendSwitch('enable-unsafe-swiftshader');
app.commandLine.appendSwitch('disable-gpu-sandbox');
@@ -65,8 +72,12 @@ app.whenReady().then(async () => {
await mkdir(STORE, { recursive: true });
channel = await createDebugChannelServer({ WebSocketServer, host: '127.0.0.1' });
// Generate actual game packages using the current SDK and compiled wasm.
- execFileSync('node', [path.join(ROOT, 'tools/cache-budget-render-fixture.mjs'), OUT, channel.urlFor('127.0.0.1')],
- { cwd: ROOT, stdio: 'inherit', windowsHide: true });
+ // Exporting can take seconds; keep Electron's main loop answering the
+ // network/GPU service startup while the child builds these packages.
+ const fixture = await promisify(execFile)('node', [path.join(ROOT, 'tools/cache-budget-render-fixture.mjs'), OUT, channel.urlFor('127.0.0.1')],
+ { cwd: ROOT, windowsHide: true, maxBuffer: 8 * 1024 * 1024 });
+ process.stdout.write(fixture.stdout);
+ process.stderr.write(fixture.stderr);
const cached = file => {
const name = String(file ?? '').replace(/^\/__cache\//, '');
if (!/^[A-Za-z0-9_.-]+$/.test(name) || name === '.' || name === '..') throw Error('invalid cache file');
diff --git a/tools/tests/wasm-opt-atomic.test.ts b/tools/tests/wasm-opt-atomic.test.ts
new file mode 100644
index 000000000..492778bfd
--- /dev/null
+++ b/tools/tests/wasm-opt-atomic.test.ts
@@ -0,0 +1,48 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+import { afterEach, beforeEach, expect, it, vi } from 'vitest';
+import { mkdtemp, mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+const mock = vi.hoisted(() => ({ run: vi.fn() }));
+vi.mock('../../build-tools/utils/emscripten.js', () => ({ runCommand: mock.run, getCpuCount: () => 1 }));
+import { optimizeWasmFiles } from '../../build-tools/tasks/wasm.js';
+const valid = new Uint8Array([0, 97, 115, 109, 1, 0, 0, 0]);
+let root: string, original: string;
+beforeEach(async () => {
+ root = await mkdtemp(path.join(tmpdir(), 'estella-wasm-opt-'));
+ await mkdir(path.join(root, 'sdk'));
+ original = path.join(root, 'sdk/engine.wasm');
+ await writeFile(original, valid);
+ mock.run.mockReset();
+});
+afterEach(async () => { await rm(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 }); });
+const outputs = { 'sdk/engine.wasm': 'wasm/web/engine.wasm' };
+
+it('leaves a valid linked artifact intact and fails the build when optimization crashes after writing output', async () => {
+ mock.run.mockImplementation(async (_cmd, args: string[]) => {
+ await writeFile(args[args.indexOf('-o') + 1], 'partial output');
+ throw Error('optimizer crashed');
+ });
+ await expect(optimizeWasmFiles(root, outputs)).rejects.toThrow('optimizer crashed');
+ expect(new Uint8Array(await readFile(original))).toEqual(valid);
+ expect(await readdir(path.join(root, 'sdk'))).toEqual(['engine.wasm']);
+});
+
+it('rejects invalid output even when the optimizer exits successfully', async () => {
+ mock.run.mockImplementation(async (_cmd, args: string[]) => { await writeFile(args[args.indexOf('-o') + 1], 'invalid'); });
+ await expect(optimizeWasmFiles(root, outputs)).rejects.toThrow('invalid WASM');
+ expect(new Uint8Array(await readFile(original))).toEqual(valid);
+});
+
+it('commits a validated optimization without making input and output the same file', async () => {
+ mock.run.mockImplementation(async (_cmd, args: string[]) => {
+ const output = args[args.indexOf('-o') + 1];
+ expect(output).not.toBe(original);
+ expect(args.at(-1)).toBe(original);
+ await writeFile(output, valid);
+ });
+ await optimizeWasmFiles(root, outputs);
+ expect(new Uint8Array(await readFile(original))).toEqual(valid);
+ expect(await readdir(path.join(root, 'sdk'))).toEqual(['engine.wasm']);
+});