@danceiny/gotry 0.0.1-rc.21 → 0.0.1-rc.24

package/dist/scripts/z3-lifecycle-fault-tests.js

@@ -0,0 +1,188 @@
+/** Poison/overflow edge contracts for the local Z3 cleanup queue (#227).
+ *
+ * Each scenario runs in a child process because a poisoned Z3 instance must refuse
+ * further solves for that process by design.
+ */
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { getZ3LifecycleStats, initZ3Context, withZ3 } from '../src/z3-shared.js';
+function makeFakeApi(Z3) {
+    Z3.enable_concurrent_dec_ref ??= () => undefined;
+    return {
+        Context(name) {
+            assert.equal(name, 'main');
+            return { ptr: { fake: 'ctx' } };
+        },
+        Z3,
+    };
+}
+async function gcCleanupDoesNotThrow() {
+    const fakeZ3 = {
+        dec_ref() {
+            throw new Error('injected gc cleanup failure');
+        },
+    };
+    await initZ3Context(async () => makeFakeApi(fakeZ3));
+    assert.doesNotThrow(() => fakeZ3.dec_ref('ctx', 'ast'), 'cleanup wrapper must not throw into a FinalizationRegistry call-site');
+    const stats = getZ3LifecycleStats();
+    assert.match(stats.poisoned ?? '', /injected gc cleanup failure/);
+    assert.equal(stats.currentDeferredQueueDepth, 0);
+    await assert.rejects(withZ3('z3-fault.after-gc-cleanup-failure', async () => null), /Z3 context is poisoned/);
+}
+async function overflowKeepsCleanupReferences() {
+    let resolveCheck;
+    let nativeDecRefs = 0;
+    const fakeZ3 = {
+        solver_check_assumptions() {
+            return new Promise(resolve => { resolveCheck = resolve; });
+        },
+        dec_ref() {
+            nativeDecRefs += 1;
+        },
+    };
+    await initZ3Context(async () => makeFakeApi(fakeZ3));
+    const pending = fakeZ3.solver_check_assumptions();
+    assert.equal(getZ3LifecycleStats().activeNativeCalls, 1, 'controlled native call must be active before cleanup is queued');
+    const total = Number(process.env.GOTRY_Z3_CLEANUP_QUEUE_LIMIT ?? '16') + 1;
+    for (let i = 0; i < total; i++)
+        fakeZ3.dec_ref('ctx', `ast-${i}`);
+    const queued = getZ3LifecycleStats();
+    assert.equal(queued.currentDeferredQueueDepth, total, 'overflow must retain every cleanup reference');
+    assert.match(queued.poisoned ?? '', /cleanup queue overflow/);
+    assert.equal(nativeDecRefs, 0, 'cleanup must not run while a native async call is pending');
+    resolveCheck('sat');
+    await pending;
+    const drained = getZ3LifecycleStats();
+    assert.equal(drained.currentDeferredQueueDepth, 0, 'non-fatal overflow queue must still be drainable');
+    assert.equal(nativeDecRefs, total, 'overflow must not drop any cleanup');
+    await assert.rejects(withZ3('z3-fault.after-overflow', async () => null), /Z3 context is poisoned/);
+}
+async function drainStopsOnFatalCleanup() {
+    let nativeDecRefAttempts = 0;
+    const fakeZ3 = {
+        dec_ref() {
+            nativeDecRefAttempts += 1;
+            throw new Error('memory access out of bounds during cleanup');
+        },
+    };
+    await initZ3Context(async () => makeFakeApi(fakeZ3));
+    await assert.rejects(withZ3('z3-fault.drain-fatal-stop', async () => {
+        fakeZ3.dec_ref('ctx', 'ast-a');
+        fakeZ3.dec_ref('ctx', 'ast-b');
+    }), /memory access out of bounds/);
+    const stats = getZ3LifecycleStats();
+    assert.match(stats.poisoned ?? '', /memory access out of bounds/);
+    assert.equal(nativeDecRefAttempts, 1, 'drain must stop after first fatal cleanup');
+    assert.equal(stats.currentDeferredQueueDepth, 2, 'fatal drain must retain failed and remaining cleanup references');
+}
+async function syncFatalPoisonsBeforeFinish() {
+    let nativeDecRefs = 0;
+    const fakeZ3 = {
+        solver_check_assumptions() {
+            fakeZ3.dec_ref('ctx', 'queued-before-sync-fatal');
+            throw new Error('RuntimeError: Aborted(Runtime error: The application has corrupted its heap memory area (address zero)!)');
+        },
+        dec_ref() {
+            nativeDecRefs += 1;
+        },
+    };
+    await initZ3Context(async () => makeFakeApi(fakeZ3));
+    assert.throws(() => fakeZ3.solver_check_assumptions(), /corrupted its heap memory/);
+    const stats = getZ3LifecycleStats();
+    assert.match(stats.poisoned ?? '', /corrupted its heap memory/);
+    assert.equal(stats.currentDeferredQueueDepth, 1, 'sync fatal must quarantine queued cleanup before finish wakes drain');
+    assert.equal(nativeDecRefs, 0, 'finishNativeCall must not drain after a synchronous fatal native error');
+}
+async function nativeBarrierWaitsBeforeSettling() {
+    let resolveCheck;
+    let nativeDecRefs = 0;
+    let entered;
+    let markEntered;
+    entered = new Promise(resolve => { markEntered = resolve; });
+    const fakeZ3 = {
+        solver_check_assumptions() {
+            return new Promise(resolve => { resolveCheck = resolve; });
+        },
+        dec_ref() {
+            nativeDecRefs += 1;
+        },
+    };
+    await initZ3Context(async () => makeFakeApi(fakeZ3));
+    const session = withZ3('z3-fault.native-barrier', async () => {
+        const pending = fakeZ3.solver_check_assumptions();
+        assert.equal(getZ3LifecycleStats().activeNativeCalls, 1, 'native barrier must be active before session error is injected');
+        fakeZ3.dec_ref('ctx', 'queued-during-native');
+        markEntered();
+        void pending;
+        throw new Error('injected domain failure after native start');
+    });
+    await entered;
+    assert.equal(getZ3LifecycleStats().activeNativeCalls, 1);
+    assert.equal(getZ3LifecycleStats().currentDeferredQueueDepth, 1);
+    assert.equal(nativeDecRefs, 0);
+    const raced = await Promise.race([session.then(() => 'settled', () => 'rejected'), new Promise(resolve => setTimeout(() => resolve('pending'), 20))]);
+    assert.equal(raced, 'pending', 'withZ3 must not settle before the active native Promise settles');
+    resolveCheck('sat');
+    await assert.rejects(session, /injected domain failure/);
+    const stats = getZ3LifecycleStats();
+    assert.equal(stats.activeNativeCalls, 0);
+    assert.equal(stats.currentDeferredQueueDepth, 0);
+    assert.equal(nativeDecRefs, 1);
+    assert.equal(await withZ3('z3-fault.after-domain-failure', async () => 'healthy'), 'healthy');
+}
+async function fatalSkipsNativeCleanupAndRefusesNewSolve() {
+    const before = getZ3LifecycleStats();
+    await assert.rejects(withZ3('z3-fault.fatal-session', async (z3) => {
+        const solver = new z3.Solver();
+        solver.add(z3.Bool.val(true));
+        solver.release();
+        throw new Error('RuntimeError: Aborted(Runtime error: The application has corrupted its heap memory area (address zero)!)');
+    }), /corrupted its heap memory/);
+    const after = getZ3LifecycleStats();
+    assert.match(after.poisoned ?? '', /corrupted its heap memory/);
+    assert.ok(after.currentDeferredQueueDepth > 0, 'fatal context must quarantine queued cleanup references instead of touching native heap');
+    assert.equal(after.drainedCleanupCalls['solver_dec_ref'] ?? 0, before.drainedCleanupCalls['solver_dec_ref'] ?? 0);
+    await assert.rejects(withZ3('z3-fault.after-fatal', async () => null), /Z3 context is poisoned/);
+}
+async function childMain(scenario) {
+    if (scenario === 'gc-cleanup')
+        await gcCleanupDoesNotThrow();
+    else if (scenario === 'overflow')
+        await overflowKeepsCleanupReferences();
+    else if (scenario === 'drain-fatal-stop')
+        await drainStopsOnFatalCleanup();
+    else if (scenario === 'sync-fatal')
+        await syncFatalPoisonsBeforeFinish();
+    else if (scenario === 'native-barrier')
+        await nativeBarrierWaitsBeforeSettling();
+    else if (scenario === 'fatal')
+        await fatalSkipsNativeCleanupAndRefusesNewSolve();
+    else
+        throw new Error(`unknown scenario: ${scenario}`);
+    console.log(`Z3 LIFECYCLE FAULT CHILD OK(${scenario})`);
+}
+const child = process.argv.find(arg => arg.startsWith('--child='))?.slice('--child='.length);
+if (child) {
+    await childMain(child);
+}
+else {
+    const tsRoot = process.cwd();
+    const tsxCli = join(tsRoot, 'node_modules', 'tsx', 'dist', 'cli.mjs');
+    assert.ok(existsSync(tsxCli), `tsx CLI not found: ${tsxCli}`);
+    for (const scenario of ['gc-cleanup', 'overflow', 'drain-fatal-stop', 'sync-fatal', 'native-barrier', 'fatal']) {
+        const result = spawnSync(process.execPath, [tsxCli, 'scripts/z3-lifecycle-fault-tests.ts', `--child=${scenario}`], {
+            cwd: tsRoot,
+            env: {
+                ...process.env,
+                ...(scenario === 'overflow' ? { GOTRY_Z3_CLEANUP_QUEUE_LIMIT: '16' } : {}),
+            },
+            encoding: 'utf8',
+            maxBuffer: 16 * 1024 * 1024,
+        });
+        assert.equal(result.status, 0, `${scenario} failed\nSTDOUT:\n${result.stdout}\nSTDERR:\n${result.stderr}`);
+        assert.match(result.stdout ?? '', new RegExp(`Z3 LIFECYCLE FAULT CHILD OK\\(${scenario}\\)`));
+    }
+    console.log('Z3 LIFECYCLE FAULT TESTS OK(gc cleanup no-throw / overflow keeps refs / drain fatal stop / sync fatal quarantine / native barrier / fatal quarantine)');
+}

package/dist/scripts/z3-lifecycle-tests.js

@@ -0,0 +1,170 @@
+/**
+ * Z3 lifecycle contract for issue #227.
+ *
+ * Runtime proof, not source-regex proof: it uses the real shared z3-solver
+ * Context, low-level wrapper stats, and live objects crossing withZ3 sessions.
+ */
+import assert from 'node:assert/strict';
+import { getZ3, getZ3LifecycleStats, initZ3Context, withZ3 } from '../src/z3-shared.js';
+function counter(stats, bucket, name) {
+    return stats[bucket][name] ?? 0;
+}
+const NativeFinalizationRegistry = globalThis.FinalizationRegistry;
+const registryEvents = [];
+const fakePtr = { fake: 'ctx' };
+const fakeCtx = await initZ3Context(async () => {
+    assert.equal(globalThis.FinalizationRegistry, NativeFinalizationRegistry, 'init await window must not replace global FinalizationRegistry');
+    const registry = new FinalizationRegistry(() => registryEvents.push('unrelated-cleanup'));
+    registry.register({ unrelated: true }, 'held');
+    await Promise.resolve();
+    assert.equal(globalThis.FinalizationRegistry, NativeFinalizationRegistry, 'global FinalizationRegistry identity must stay stable after await');
+    return {
+        Context(name) {
+            assert.equal(name, 'main');
+            return { ptr: fakePtr };
+        },
+        Z3: {
+            enable_concurrent_dec_ref(ptr) {
+                assert.equal(ptr, fakePtr);
+            },
+        },
+    };
+});
+assert.equal(fakeCtx.ptr, fakePtr);
+assert.deepEqual(registryEvents, [], 'unrelated FinalizationRegistry must keep normal non-forced semantics');
+assert.equal(globalThis.FinalizationRegistry, NativeFinalizationRegistry);
+await assert.rejects(initZ3Context(async () => ({
+    Context() { return { ptr: {} }; },
+    Z3: {},
+})), /missing enable_concurrent_dec_ref/);
+const beforeCold = getZ3LifecycleStats();
+const contexts = await Promise.all(Array.from({ length: 8 }, () => getZ3()));
+assert.equal(new Set(contexts).size, 1, 'concurrent cold getZ3 must return the exact same Context object');
+const afterCold = getZ3LifecycleStats();
+assert.equal(afterCold.contextsCreated - beforeCold.contextsCreated, 1, 'cold start must create exactly one real Context');
+assert.equal(afterCold.concurrentDecRefEnabled - beforeCold.concurrentDecRefEnabled, 1, 'concurrent dec-ref hook must run once for the real Context');
+assert.ok(afterCold.cleanupWrappedFunctions.includes('dec_ref'), 'AST cleanup entry must be wrapped locally');
+assert.ok(afterCold.cleanupWrappedFunctions.includes('solver_dec_ref'), 'Solver cleanup entry must be wrapped locally');
+assert.ok(afterCold.cleanupWrappedFunctions.includes('model_dec_ref'), 'Model cleanup entry must be wrapped locally');
+assert.ok(afterCold.cleanupWrappedFunctions.includes('optimize_dec_ref'), 'Optimize cleanup entry must be wrapped locally');
+assert.ok(afterCold.cleanupWrappedFunctions.includes('ast_vector_dec_ref'), 'AstVector cleanup entry must be wrapped locally');
+assert.ok(afterCold.asyncWrappedFunctions.includes('solver_check_assumptions'), 'Solver.check native async entry must be tracked');
+assert.ok(afterCold.asyncWrappedFunctions.includes('optimize_check'), 'Optimize.check native async entry must be tracked');
+const beforeDefer = getZ3LifecycleStats();
+const queued = await withZ3('z3-lifecycle.defer-explicit-release', async (z3) => {
+    const s = new z3.Solver();
+    s.add(z3.Bool.val(true));
+    s.release();
+    const stats = getZ3LifecycleStats();
+    assert.ok(stats.currentDeferredQueueDepth > 0, 'release during active withZ3 must be queued, not run inline');
+    return stats.currentDeferredQueueDepth;
+});
+assert.ok(queued > 0);
+const afterDefer = getZ3LifecycleStats();
+assert.equal(afterDefer.currentDeferredQueueDepth, 0, 'queued cleanup must drain after withZ3 settles');
+assert.ok(counter(afterDefer, 'deferredCleanupCalls', 'solver_dec_ref') > counter(beforeDefer, 'deferredCleanupCalls', 'solver_dec_ref'));
+assert.ok(counter(afterDefer, 'drainedCleanupCalls', 'solver_dec_ref') > counter(beforeDefer, 'drainedCleanupCalls', 'solver_dec_ref'));
+const retained = await withZ3('z3-lifecycle.retain-live-owner', async (z3) => {
+    const x = z3.Int.const('life_retained_x');
+    const solver = new z3.Solver();
+    solver.add(x.eq(7));
+    assert.equal(await solver.check(), 'sat');
+    const model = solver.model();
+    return { x, solver, model };
+});
+const afterRetain = getZ3LifecycleStats();
+assert.equal(afterRetain.currentDeferredQueueDepth, 0, 'withZ3 must not force-free live returned owners');
+await withZ3('z3-lifecycle.use-retained-owner', async () => {
+    assert.equal(String(await retained.model.eval(retained.x, true)), '7', 'live returned Model/Ast must remain usable in a later session');
+    retained.model.release();
+    retained.solver.release();
+});
+const afterRetainedRelease = getZ3LifecycleStats();
+assert.ok(counter(afterRetainedRelease, 'drainedCleanupCalls', 'model_dec_ref') > counter(afterRetain, 'drainedCleanupCalls', 'model_dec_ref'));
+assert.ok(counter(afterRetainedRelease, 'drainedCleanupCalls', 'solver_dec_ref') > counter(afterRetain, 'drainedCleanupCalls', 'solver_dec_ref'));
+let releaseFirst;
+let firstPromise;
+const firstEntered = new Promise(resolve => {
+    firstPromise = withZ3('z3-lifecycle.barrier-first', async (z3) => {
+        resolve();
+        await new Promise(r => { releaseFirst = r; });
+        const s = new z3.Solver();
+        try {
+            s.add(z3.Bool.val(true));
+            assert.equal(await s.check(), 'sat');
+            return 'first';
+        }
+        finally {
+            s.release();
+        }
+    });
+});
+await firstEntered;
+let secondRan = false;
+const second = withZ3('z3-lifecycle.barrier-second', async (z3) => {
+    secondRan = true;
+    const s = new z3.Solver();
+    try {
+        s.add(z3.Bool.val(true));
+        assert.equal(await s.check(), 'sat');
+        return 'second';
+    }
+    finally {
+        s.release();
+    }
+});
+const raced = await Promise.race([second.then(() => 'settled'), new Promise(resolve => setTimeout(() => resolve('queued'), 20))]);
+assert.equal(raced, 'queued', 'independent second withZ3 call must queue while first session awaits');
+assert.equal(secondRan, false);
+releaseFirst();
+assert.equal(await firstPromise, 'first');
+assert.equal(await second, 'second');
+assert.equal(secondRan, true);
+await assert.rejects(withZ3('z3-lifecycle.nested-outer', async () => withZ3('z3-lifecycle.nested-inner', async () => null)), /nested withZ3 is forbidden/);
+let caughtFalsy = false;
+try {
+    await withZ3('z3-lifecycle.falsy-rejection', async () => Promise.reject(undefined));
+}
+catch (error) {
+    caughtFalsy = true;
+    assert.equal(error, undefined);
+}
+assert.equal(caughtFalsy, true, 'withZ3 must preserve falsy rejection values');
+assert.equal(await withZ3('z3-lifecycle.after-falsy-rejection', async (z3) => {
+    const s = new z3.Solver();
+    try {
+        s.add(z3.Bool.val(true));
+        return await s.check();
+    }
+    finally {
+        s.release();
+    }
+}), 'sat');
+const beforeOptimize = getZ3LifecycleStats();
+const optValue = await withZ3('z3-lifecycle.optimize', async (z3) => {
+    const x = z3.Int.const('life_opt_x');
+    const opt = new z3.Optimize();
+    try {
+        opt.add(x.ge(2), x.le(5));
+        const obj = opt.minimize(x);
+        assert.equal(await opt.check(), 'sat');
+        assert.equal(String(await opt.getLower(obj)), '2');
+        const model = opt.model();
+        try {
+            return String(await model.eval(x, true));
+        }
+        finally {
+            model.release();
+        }
+    }
+    finally {
+        opt.release();
+    }
+});
+assert.equal(optValue, '2');
+const afterOptimize = getZ3LifecycleStats();
+assert.ok(counter(afterOptimize, 'drainedCleanupCalls', 'optimize_dec_ref') > counter(beforeOptimize, 'drainedCleanupCalls', 'optimize_dec_ref'));
+assert.equal(afterOptimize.sessionsStarted, afterOptimize.sessionsSettled);
+assert.equal(afterOptimize.currentDeferredQueueDepth, 0);
+assert.equal(afterOptimize.poisoned, null);
+console.log(`Z3 LIFECYCLE TESTS OK(contexts=1, cleanup=${afterOptimize.cleanupWrappedFunctions.length}, async=${afterOptimize.asyncWrappedFunctions.length}, maxQueue=${afterOptimize.maxDeferredQueueDepth})`);

package/dist/scripts/z3-race-repeat-tests.js

@@ -0,0 +1,39 @@
+/** Multi-process Z3 race repeat proof for issue #227. */
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+function parsePositiveInt(name, fallback) {
+    const raw = process.env[name];
+    if (!raw)
+        return fallback;
+    const value = Number(raw);
+    assert.ok(Number.isInteger(value) && value > 0, `${name} must be a positive integer`);
+    return value;
+}
+const repeats = parsePositiveInt('GOTRY_Z3_RACE_REPEAT_PROCESSES', 3);
+const rounds = parsePositiveInt('GOTRY_Z3_RACE_REPEAT_ROUNDS', parsePositiveInt('GOTRY_Z3_RACE_ROUNDS', 12));
+const artifactDir = process.env.GOTRY_Z3_RACE_ARTIFACT_DIR ?? mkdtempSync(join(tmpdir(), 'gotry-z3-race-repeat-'));
+mkdirSync(artifactDir, { recursive: true });
+const tsRoot = process.cwd();
+const tsxCli = join(tsRoot, 'node_modules', 'tsx', 'dist', 'cli.mjs');
+assert.ok(existsSync(tsxCli), `tsx CLI not found: ${tsxCli}`);
+for (let i = 1; i <= repeats; i++) {
+    const result = spawnSync(process.execPath, [tsxCli, 'scripts/z3-race-tests.ts'], {
+        cwd: tsRoot,
+        env: {
+            ...process.env,
+            GOTRY_Z3_RACE_ROUNDS: String(rounds),
+        },
+        encoding: 'utf8',
+        maxBuffer: 16 * 1024 * 1024,
+    });
+    const outFile = join(artifactDir, `${String(i).padStart(2, '0')}.out`);
+    const errFile = join(artifactDir, `${String(i).padStart(2, '0')}.err`);
+    writeFileSync(outFile, result.stdout ?? '');
+    writeFileSync(errFile, result.stderr ?? '');
+    assert.equal(result.status, 0, `repeat ${i} failed; stdout=${outFile} stderr=${errFile}`);
+    assert.match(result.stdout ?? '', /Z3 RACE TESTS OK/, `repeat ${i} did not report success; stdout=${outFile}`);
+}
+console.log(`Z3 RACE REPEAT TESTS OK(processes=${repeats}, rounds=${rounds}, artifactDir=${artifactDir})`);

package/dist/scripts/z3-race-tests.js

@@ -1,3 +1,14 @@
+/**
+ * Z3 WASM race 回归(README Known limitations 根治项):
+ * 三形态(engine 候选 / journey 航班链 / unified)在单进程内并发求解 × 12 轮。
+ * 修复前形态:engine.solve 的 Promise.all 多候选并发 + 三模块各自 init() 的
+ * WASM 实例并存 → z3 async 会话交错偶发 `memory access out of bounds`
+ * (run-all §1 重试止血与 release-notes rc.2-rc.4 的实录根因)。
+ * 修复(z3-shared.ts):单一 WASM 实例 + 单一 Context + 会话级互斥门。
+ *
+ * 断言:① 并发轮次无 unified WASM 降级(wasm_runtime_error);② 判定与顺序基线一致。
+ * 运行(在 ts/ 下):npx tsx scripts/z3-race-tests.ts
+ */
 import assert from 'node:assert/strict';
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
@@ -10,18 +21,16 @@ const pack = JSON.parse(await readFile(join('..', 'data', 'flights_2026.json'),
 const req = parseRequest(erhai['request']);
 const candidates = erhai['candidates'].map(parseCandidate);
 const legs = parseFlightPackLegs(pack);
+// 顺序基线(同时预热 WASM 实例)
 const baseEngine = await solve(req, candidates);
-const baseJourney = await solveJourney({
-    legs
-});
-const ROUNDS = 12;
-for(let round = 0; round < ROUNDS; round++){
+const baseJourney = await solveJourney({ legs });
+const ROUNDS = Number(process.env.GOTRY_Z3_RACE_ROUNDS ?? '12');
+assert.ok(Number.isInteger(ROUNDS) && ROUNDS > 0, 'GOTRY_Z3_RACE_ROUNDS must be a positive integer');
+for (let round = 0; round < ROUNDS; round++) {
     const [eng, jny, uni] = await Promise.all([
         solve(req, candidates),
-        solveJourney({
-            legs
-        }),
-        solveUnified(parseFlightPackToSpec(pack))
+        solveJourney({ legs }),
+        solveUnified(parseFlightPackToSpec(pack)),
     ]);
     void jny;
     assert.equal(eng['recommended'], baseEngine['recommended'], `r${round}: engine recommended 漂移`);
@@ -30,6 +39,3 @@ for(let round = 0; round < ROUNDS; round++){
     assert.equal(uni['feasible'], true, `r${round}: unified 判定漂移(基线应为可行)`);
 }
 console.log(`Z3 RACE TESTS OK(进程内三形态并发 ×${ROUNDS}:判定与顺序基线一致,零 WASM 降级)`);
-
-
-//# sourceURL=ts/scripts/z3-race-tests.ts