@typeberry/lib 0.9.0-3f2c45b → 0.9.0-59ce083

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typeberry/lib",
-  "version": "0.9.0-3f2c45b",
+  "version": "0.9.0-59ce083",
   "description": "Typeberry Library",
   "main": "./bin/lib/index.js",
   "types": "./bin/lib/index.d.ts",

package/packages/core/utils/index.d.ts

@@ -18,5 +18,6 @@ export * from "./opaque.js";
 export { name, version } from "./package.js";
 export * from "./result.js";
 export * from "./safe-alloc-uint8array.js";
+export * from "./shutdown.js";
 export * from "./test.js";
 //# sourceMappingURL=index.d.ts.map

package/packages/core/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../packages/core/utils/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,cAAc,oBAAoB,CAAC;AACnC,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC7C,cAAc,aAAa,CAAC;AAC5B,cAAc,4BAA4B,CAAC;AAC3C,cAAc,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../packages/core/utils/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,cAAc,oBAAoB,CAAC;AACnC,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC7C,cAAc,aAAa,CAAC;AAC5B,cAAc,4BAA4B,CAAC;AAC3C,cAAc,eAAe,CAAC;AAC9B,cAAc,WAAW,CAAC"}

package/packages/core/utils/index.js

@@ -18,4 +18,5 @@ export * from "./opaque.js";
 export { name, version } from "./package.js";
 export * from "./result.js";
 export * from "./safe-alloc-uint8array.js";
+export * from "./shutdown.js";
 export * from "./test.js";

package/packages/core/utils/shutdown.d.ts

@@ -0,0 +1,18 @@
+export type Closer = () => Promise<void>;
+export type ShutdownSignal = string;
+export interface ShutdownLogger {
+    info: (msg: string) => void;
+    error: (msg: string) => void;
+}
+export interface ShutdownOptions {
+    /** Max ms allowed for `close` before forced exit(1). Default 10_000. */
+    timeoutMs?: number;
+    /** Signals to listen for. Default ["SIGTERM", "SIGINT"]. */
+    signals?: readonly ShutdownSignal[];
+    /** Logger; defaults to a no-op logger. */
+    log?: ShutdownLogger;
+    /** Test hook used instead of process.exit. */
+    exit?: (code: number) => never;
+}
+export declare function installShutdownHandlers(_close: Closer, _options?: ShutdownOptions): () => void;
+//# sourceMappingURL=shutdown.d.ts.map

package/packages/core/utils/shutdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shutdown.d.ts","sourceRoot":"","sources":["../../../../../packages/core/utils/shutdown.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;AAEzC,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC;AAEpC,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5B,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9B;AAED,MAAM,WAAW,eAAe;IAC9B,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4DAA4D;IAC5D,OAAO,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;IACpC,0CAA0C;IAC1C,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,8CAA8C;IAC9C,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,KAAK,CAAC;CAChC;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,GAAE,eAAoB,GAAG,MAAM,IAAI,CAElG"}

package/packages/core/utils/shutdown.js

@@ -0,0 +1,3 @@
+export function installShutdownHandlers(_close, _options = {}) {
+    return () => { };
+}

package/packages/core/utils/shutdown.node.d.ts

@@ -0,0 +1,5 @@
+import type { Closer, ShutdownOptions } from "./shutdown.js";
+export type { Closer, ShutdownLogger, ShutdownOptions, ShutdownSignal } from "./shutdown.js";
+/** Returns an uninstall function (used by tests). */
+export declare function installShutdownHandlers(close: Closer, options?: ShutdownOptions): () => void;
+//# sourceMappingURL=shutdown.node.d.ts.map

package/packages/core/utils/shutdown.node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shutdown.node.d.ts","sourceRoot":"","sources":["../../../../../packages/core/utils/shutdown.node.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAE7D,YAAY,EAAE,MAAM,EAAE,cAAc,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAK7F,qDAAqD;AACrD,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB,GAAG,MAAM,IAAI,CA+EhG"}

package/packages/core/utils/shutdown.node.js

@@ -0,0 +1,76 @@
+const DEFAULT_SIGNALS = ["SIGTERM", "SIGINT"];
+const DEFAULT_TIMEOUT_MS = 10_000;
+/** Returns an uninstall function (used by tests). */
+export function installShutdownHandlers(close, options = {}) {
+    const signals = (options.signals ?? DEFAULT_SIGNALS);
+    const exit = (options.exit ?? process.exit);
+    const log = options.log;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    let state = "idle";
+    const forceExit = (signal) => {
+        log?.error(`Received ${signal} during shutdown, forcing exit.`);
+        try {
+            exit(1);
+        }
+        catch {
+            // test-time exit throws; swallow.
+        }
+    };
+    const handler = (signal) => {
+        if (state === "closing" || state === "done") {
+            forceExit(signal);
+            return;
+        }
+        state = "closing";
+        log?.info(`Received ${signal}, draining...`);
+        void (async () => {
+            const TIMED_OUT = Symbol("timed-out");
+            let timeoutHandle;
+            const timeoutPromise = new Promise((resolve) => {
+                timeoutHandle = setTimeout(() => resolve(TIMED_OUT), timeoutMs);
+            });
+            timeoutHandle?.unref?.();
+            let code = 0;
+            try {
+                const outcome = await Promise.race([
+                    Promise.resolve()
+                        .then(close)
+                        .then(() => "ok", (e) => ({ err: e })),
+                    timeoutPromise,
+                ]);
+                if (outcome === TIMED_OUT) {
+                    code = 1;
+                    log?.error(`Shutdown cleanup exceeded ${timeoutMs}ms timeout, forcing exit.`);
+                }
+                else if (typeof outcome === "object" && "err" in outcome) {
+                    code = 1;
+                    const e = outcome.err;
+                    log?.error(`Shutdown close threw: ${e instanceof Error ? (e.stack ?? e.message) : String(e)}`);
+                }
+                else {
+                    log?.info("Shutdown complete.");
+                }
+            }
+            finally {
+                clearTimeout(timeoutHandle);
+                state = "done";
+            }
+            try {
+                exit(code);
+            }
+            catch {
+                // test-time exit throws; swallow.
+            }
+        })();
+    };
+    // Node passes the signal name to the listener, so a single handler works
+    // for every signal.
+    for (const sig of signals) {
+        process.on(sig, handler);
+    }
+    return () => {
+        for (const sig of signals) {
+            process.off(sig, handler);
+        }
+    };
+}

package/packages/core/utils/shutdown.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=shutdown.test.d.ts.map

package/packages/core/utils/shutdown.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shutdown.test.d.ts","sourceRoot":"","sources":["../../../../../packages/core/utils/shutdown.test.ts"],"names":[],"mappings":""}

package/packages/core/utils/shutdown.test.js

@@ -0,0 +1,164 @@
+import assert from "node:assert";
+import { afterEach, describe, it } from "node:test";
+import { installShutdownHandlers as installGenericShutdownHandlers } from "./shutdown.js";
+import { installShutdownHandlers } from "./shutdown.node.js";
+function makeExitRecorder() {
+    let resolveExited;
+    const exited = new Promise((resolve) => {
+        resolveExited = resolve;
+    });
+    const recorder = {
+        exitCode: null,
+        exited,
+        exit: ((code) => {
+            recorder.exitCode = code;
+            resolveExited();
+            // Satisfy `never` and abort the calling promise chain.
+            throw new Error(`__test_exit_${code}`);
+        }),
+    };
+    return recorder;
+}
+const silentLog = { info: () => { }, error: () => { } };
+describe("utils::installShutdownHandlers", () => {
+    const uninstallers = [];
+    afterEach(() => {
+        while (uninstallers.length > 0) {
+            uninstallers.pop()?.();
+        }
+    });
+    it("calls close and exits 0 on first SIGTERM", async () => {
+        const exitRec = makeExitRecorder();
+        let closeCalled = false;
+        uninstallers.push(installShutdownHandlers(async () => {
+            closeCalled = true;
+        }, { exit: exitRec.exit, log: silentLog }));
+        process.emit("SIGTERM", "SIGTERM");
+        await exitRec.exited;
+        assert.strictEqual(closeCalled, true);
+        assert.strictEqual(exitRec.exitCode, 0);
+    });
+    it("exits with code 1 when cleanup exceeds timeoutMs", async () => {
+        const exitRec = makeExitRecorder();
+        let closeStarted = false;
+        let errorLogged = null;
+        let releaseClose;
+        const closeReleased = new Promise((resolve) => {
+            releaseClose = resolve;
+        });
+        uninstallers.push(installShutdownHandlers(async () => {
+            closeStarted = true;
+            await closeReleased;
+        }, {
+            exit: exitRec.exit,
+            timeoutMs: 5,
+            log: {
+                info: () => { },
+                error: (msg) => {
+                    errorLogged = msg;
+                },
+            },
+        }));
+        process.emit("SIGTERM", "SIGTERM");
+        await exitRec.exited;
+        assert.strictEqual(closeStarted, true, "close should have been invoked");
+        assert.strictEqual(exitRec.exitCode, 1);
+        assert.ok(errorLogged !== null, "expected timeout to be logged");
+        assert.match(errorLogged, /timeout|exceed/i);
+        // Allow the in-flight close promise to settle so the test doesn't leak.
+        releaseClose();
+    });
+    it("forces exit 1 when a second signal arrives during cleanup", async () => {
+        const exitRec = makeExitRecorder();
+        let releaseClose;
+        const closeReleased = new Promise((resolve) => {
+            releaseClose = resolve;
+        });
+        let errorLogged = null;
+        uninstallers.push(installShutdownHandlers(async () => {
+            await closeReleased;
+        }, {
+            // Large timeout so this test can't pass via the timeout path.
+            timeoutMs: 60_000,
+            exit: exitRec.exit,
+            log: {
+                info: () => { },
+                error: (msg) => {
+                    errorLogged = msg;
+                },
+            },
+        }));
+        process.emit("SIGTERM", "SIGTERM");
+        await new Promise((resolve) => setImmediate(resolve));
+        process.emit("SIGINT", "SIGINT");
+        await exitRec.exited;
+        assert.strictEqual(exitRec.exitCode, 1);
+        assert.ok(errorLogged !== null, "expected force-exit message to be logged");
+        assert.match(errorLogged, /SIGINT/);
+        releaseClose();
+    });
+    it("does nothing after uninstall", async () => {
+        const exitRec = makeExitRecorder();
+        let closeCalled = false;
+        const uninstall = installShutdownHandlers(async () => {
+            closeCalled = true;
+        }, { exit: exitRec.exit, log: silentLog });
+        uninstall();
+        process.emit("SIGTERM", "SIGTERM");
+        // Give any (incorrectly registered) handler a tick to fire.
+        await new Promise((resolve) => setImmediate(resolve));
+        assert.strictEqual(closeCalled, false);
+        assert.strictEqual(exitRec.exitCode, null);
+    });
+    it("is a no-op from the generic shutdown module", async () => {
+        const exitRec = makeExitRecorder();
+        let closeCalled = false;
+        const uninstall = installGenericShutdownHandlers(async () => {
+            closeCalled = true;
+        }, { exit: exitRec.exit, log: silentLog });
+        uninstall();
+        assert.strictEqual(typeof uninstall, "function");
+        assert.strictEqual(closeCalled, false);
+        assert.strictEqual(exitRec.exitCode, null);
+    });
+    it("exits with code 1 when close rejects", async () => {
+        const exitRec = makeExitRecorder();
+        let errorLogged = null;
+        uninstallers.push(installShutdownHandlers(async () => {
+            throw new Error("boom");
+        }, {
+            exit: exitRec.exit,
+            log: {
+                info: () => { },
+                error: (msg) => {
+                    errorLogged = msg;
+                },
+            },
+        }));
+        process.emit("SIGTERM", "SIGTERM");
+        await exitRec.exited;
+        assert.strictEqual(exitRec.exitCode, 1);
+        assert.ok(errorLogged !== null, "expected error to be logged");
+        assert.match(errorLogged, /boom/);
+    });
+    it("exits with code 1 when close throws synchronously", async () => {
+        const exitRec = makeExitRecorder();
+        let errorLogged = null;
+        uninstallers.push(installShutdownHandlers(() => {
+            throw new Error("sync boom");
+        }, {
+            exit: exitRec.exit,
+            log: {
+                info: () => { },
+                error: (msg) => {
+                    errorLogged = msg;
+                },
+            },
+        }));
+        process.emit("SIGTERM", "SIGTERM");
+        await exitRec.exited;
+        assert.strictEqual(exitRec.exitCode, 1);
+        assert.ok(errorLogged !== null, "expected error to be logged");
+        assert.match(errorLogged, /sync boom/);
+    });
+});

package/packages/extensions/ipc/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../../../../packages/extensions/ipc/server.ts"],"names":[],"mappings":"AACA,OAAO,EAAgB,KAAK,MAAM,EAAE,MAAM,UAAU,CAAC;AAIrD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAIxD,4CAA4C;AAC5C,qBAAa,SAAS;IAKA,OAAO,CAAC,QAAQ,CAAC,MAAM;IAJ3C,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM;IAIzB,OAAO;IAEP,+CAA+C;IAC/C,IAAI,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI;IAI3B,wBAAwB;IACxB,KAAK,IAAI,IAAI;CAGd;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAC,MAAM,EAAE,SAAS,KAAK,UAAU,cAiFhG"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../../../../packages/extensions/ipc/server.ts"],"names":[],"mappings":"AACA,OAAO,EAAgB,KAAK,MAAM,EAAE,MAAM,UAAU,CAAC;AAIrD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAIxD,4CAA4C;AAC5C,qBAAa,SAAS;IAKA,OAAO,CAAC,QAAQ,CAAC,MAAM;IAJ3C,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM;IAIzB,OAAO;IAEP,+CAA+C;IAC/C,IAAI,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI;IAI3B,wBAAwB;IACxB,KAAK,IAAI,IAAI;CAGd;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAC,MAAM,EAAE,SAAS,KAAK,UAAU,cAuFhG"}

package/packages/extensions/ipc/server.js

@@ -87,6 +87,13 @@ export function startIpcServer(name, newMessageHandler) {
         controller.abort();
         // unrefing
         server.unref();
+        // Windows named pipes are cleaned up by the OS; Unix sockets are not.
+        if (!isWindows) {
+            try {
+                fs.unlinkSync(socketPath);
+            }
+            catch { }
+        }
     };
 }
 /**

package/packages/jam/node/main-fuzz.d.ts

@@ -1,5 +1,6 @@
 import { type FuzzVersion } from "#@typeberry/ext-ipc";
 import { v1 as fuzzV1 } from "#@typeberry/fuzz-proto";
+import { type Closer } from "#@typeberry/utils";
 import type { JamConfig } from "./jam-config.js";
 export type FuzzConfig = {
     version: FuzzVersion;
@@ -24,5 +25,7 @@ export declare function getFuzzDetails(): {
     nodeVersion: fuzzV1.Version;
     gpVersion: fuzzV1.Version;
 };
-export declare function mainFuzz(fuzzConfig: FuzzConfig, withRelPath: (v: string) => string): Promise<() => void>;
+export declare function mainFuzz(fuzzConfig: FuzzConfig, withRelPath: (v: string) => string): Promise<{
+    close: Closer;
+}>;
 //# sourceMappingURL=main-fuzz.d.ts.map

package/packages/jam/node/main-fuzz.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main-fuzz.d.ts","sourceRoot":"","sources":["../../../../../packages/jam/node/main-fuzz.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,KAAK,WAAW,EAAmB,MAAM,oBAAoB,CAAC;AACvE,OAAO,EAAE,EAAE,IAAI,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAOrD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAIjD,MAAM,MAAM,UAAU,GAAG;IACvB,OAAO,EAAE,WAAW,CAAC;IACrB,aAAa,EAAE,SAAS,CAAC;IACzB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,uBAAuB,EAAE,OAAO,CAAC;CAClC,CAAC;AAoBF;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CASpF;AAED,iFAAiF;AACjF,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE5D;AAED,wBAAgB,cAAc;;;;EAM7B;AAED,wBAAsB,QAAQ,CAAC,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,uBAuJxF"}
+{"version":3,"file":"main-fuzz.d.ts","sourceRoot":"","sources":["../../../../../packages/jam/node/main-fuzz.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,KAAK,WAAW,EAAmB,MAAM,oBAAoB,CAAC;AACvE,OAAO,EAAE,EAAE,IAAI,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAIrD,OAAO,EAAE,KAAK,MAAM,EAAoC,MAAM,kBAAkB,CAAC;AAGjF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAIjD,MAAM,MAAM,UAAU,GAAG;IACvB,OAAO,EAAE,WAAW,CAAC;IACrB,aAAa,EAAE,SAAS,CAAC;IACzB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,uBAAuB,EAAE,OAAO,CAAC;CAClC,CAAC;AAoBF;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CASpF;AAED,iFAAiF;AACjF,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE5D;AAED,wBAAgB,cAAc;;;;EAM7B;AAED,wBAAsB,QAAQ,CAAC,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,GAAG,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAgLrH"}

package/packages/jam/node/main-fuzz.js

@@ -75,6 +75,10 @@ export async function mainFuzz(fuzzConfig, withRelPath) {
     // every reset, because opening it is the slow part. Only the in-memory blocks
     // and leaf sets are rebuilt for each vector. fjall-hybrid only.
     let fjallSession = null;
+    // Set when close() starts. Guards resetState so a fuzz command arriving
+    // mid-shutdown can't build a fresh node that close() then orphans.
+    let isClosing = false;
+    let activeReset = null;
     const chainSpec = getChainSpec(config.node.flavor);
     const closeFuzzTarget = startFuzzTarget(fuzzConfig.version, fuzzConfig.socket, {
         ...getFuzzDetails(),
@@ -98,97 +102,122 @@ export async function mainFuzz(fuzzConfig, withRelPath) {
             }
             return runningNode.getStateEntries(hash);
         },
-        resetState: async (header, state, ancestry) => {
-            if (runningNode !== null) {
-                const finish = runningNode.close();
-                runningNode = null;
-                await finish;
-            }
-            const buildNode = (databaseBasePath) => {
-                const isPersistent = databaseBasePath !== undefined;
-                return mainImporter({
-                    ...config,
-                    node: {
-                        ...config.node,
-                        databaseBasePath,
-                        chainSpec: {
-                            ...config.node.chainSpec,
-                            genesisHeader: Encoder.encodeObject(Header.Codec, header, chainSpec),
-                            genesisState: new Map(state),
+        resetState: (header, state, ancestry) => {
+            const reset = (async () => {
+                if (isClosing) {
+                    return Bytes.zero(HASH_SIZE).asOpaque();
+                }
+                if (runningNode !== null) {
+                    const finish = runningNode.close();
+                    runningNode = null;
+                    await finish;
+                }
+                const buildNode = (databaseBasePath) => {
+                    const isPersistent = databaseBasePath !== undefined;
+                    return mainImporter({
+                        ...config,
+                        node: {
+                            ...config.node,
+                            databaseBasePath,
+                            chainSpec: {
+                                ...config.node.chainSpec,
+                                genesisHeader: Encoder.encodeObject(Header.Codec, header, chainSpec),
+                                genesisState: new Map(state),
+                            },
                         },
-                    },
-                    ancestry,
-                    network: null,
-                }, withRelPath, {
-                    initGenesisFromAncestry: fuzzConfig.initGenesisFromAncestry,
-                    // Hybrid keeps leaf sets in RAM, so they must be windowed exactly
-                    // like the in-memory backend; only the large values live on disk.
-                    dummyFinalityDepth: 20,
-                    pruneBlocks: true,
-                    // The on-disk fuzz db is throwaway (we wipe it), so open it ephemeral and
-                    // skip the fsync, we do not need durability here. On full spec ephemeral
-                    // also turns on compression further down, so the big values do not grow the
-                    // db too much. Tiny stays uncompressed, its db is small and speed matters more.
-                    ephemeral: isPersistent,
-                    stateBackend: isPersistent ? hybridStateBackend : "lmdb",
-                    // Reuse the session keyspace (fjall-hybrid only, other backends
-                    // ignore it). Nothing to pass for the in-memory fallback.
-                    sharedFjallSession: isPersistent ? (fjallSession ?? undefined) : undefined,
-                });
-            };
-            if (fuzzDbBase !== undefined) {
-                try {
-                    if (hybridStateBackend === FUZZ_DB_FJALL) {
-                        // fjall-hybrid: open the values keyspace once and reuse it on every
-                        // reset. The values partition is content-addressed and immutable, so
-                        // it is fine that values pile up across resets, the unreferenced ones
-                        // just sit there. `initializeDatabase` decides whether the db is
-                        // already initialized from the in-memory blocks, which we rebuild on
-                        // every reset, not from the values store, so reusing it does not
-                        // resume the previous run.
-                        if (fjallSession === null) {
-                            // Start from a clean slate once, then keep the keyspace open.
+                        ancestry,
+                        network: null,
+                    }, withRelPath, {
+                        initGenesisFromAncestry: fuzzConfig.initGenesisFromAncestry,
+                        // Hybrid keeps leaf sets in RAM, so they must be windowed exactly
+                        // like the in-memory backend; only the large values live on disk.
+                        dummyFinalityDepth: 20,
+                        pruneBlocks: true,
+                        // The on-disk fuzz db is throwaway (we wipe it), so open it ephemeral and
+                        // skip the fsync, we do not need durability here. On full spec ephemeral
+                        // also turns on compression further down, so the big values do not grow the
+                        // db too much. Tiny stays uncompressed, its db is small and speed matters more.
+                        ephemeral: isPersistent,
+                        stateBackend: isPersistent ? hybridStateBackend : "lmdb",
+                        // Reuse the session keyspace (fjall-hybrid only, other backends
+                        // ignore it). Nothing to pass for the in-memory fallback.
+                        sharedFjallSession: isPersistent ? (fjallSession ?? undefined) : undefined,
+                    });
+                };
+                if (fuzzDbBase !== undefined) {
+                    try {
+                        if (hybridStateBackend === FUZZ_DB_FJALL) {
+                            // fjall-hybrid: open the values keyspace once and reuse it on every
+                            // reset. The values partition is content-addressed and immutable, so
+                            // it is fine that values pile up across resets, the unreferenced ones
+                            // just sit there. `initializeDatabase` decides whether the db is
+                            // already initialized from the in-memory blocks, which we rebuild on
+                            // every reset, not from the values store, so reusing it does not
+                            // resume the previous run.
+                            if (fjallSession === null) {
+                                // Start from a clean slate once, then keep the keyspace open.
+                                await wipeFuzzDb(fuzzDbBase);
+                                fjallSession = await FjallValuesSession.open(`${withRelPath(fuzzDbBase)}/${FUZZ_FJALL_VALUES_SUBDIR}`, {
+                                    ephemeral: true,
+                                    cacheSizeBytes: FUZZ_FJALL_CACHE_BYTES,
+                                });
+                                logger.info `🗄️ Opened reusable fjall values session at ${withRelPath(fuzzDbBase)}/${FUZZ_FJALL_VALUES_SUBDIR}`;
+                            }
+                        }
+                        else {
+                            // lmdb-hybrid: keep the old behaviour, wipe and reopen on every
+                            // reset. A fresh db each reset makes `initializeDatabase` set up
+                            // genesis again instead of resuming the previous run.
                             await wipeFuzzDb(fuzzDbBase);
-                            fjallSession = await FjallValuesSession.open(`${withRelPath(fuzzDbBase)}/${FUZZ_FJALL_VALUES_SUBDIR}`, {
-                                ephemeral: true,
-                                cacheSizeBytes: FUZZ_FJALL_CACHE_BYTES,
-                            });
-                            logger.info `🗄️ Opened reusable fjall values session at ${withRelPath(fuzzDbBase)}/${FUZZ_FJALL_VALUES_SUBDIR}`;
                         }
+                        runningNode = await buildNode(fuzzDbBase);
+                        return await runningNode.getBestStateRootHash();
                     }
-                    else {
-                        // lmdb-hybrid: keep the old behaviour, wipe and reopen on every
-                        // reset. A fresh db each reset makes `initializeDatabase` set up
-                        // genesis again instead of resuming the previous run.
-                        await wipeFuzzDb(fuzzDbBase);
+                    catch (e) {
+                        // A partially-opened db may leak on failure; acceptable for this degraded fallback (proper cleanup belongs in mainImporter).
+                        logger.warn `Failed to open persistent fuzz db at ${fuzzDbBase}, falling back to in-memory: ${e}`;
+                        runningNode = null;
                     }
-                    runningNode = await buildNode(fuzzDbBase);
-                    return await runningNode.getBestStateRootHash();
                 }
-                catch (e) {
-                    // A partially-opened db may leak on failure; acceptable for this degraded fallback (proper cleanup belongs in mainImporter).
-                    logger.warn `Failed to open persistent fuzz db at ${fuzzDbBase}, falling back to in-memory: ${e}`;
-                    runningNode = null;
+                runningNode = await buildNode(undefined);
+                return await runningNode.getBestStateRootHash();
+            })();
+            activeReset = reset;
+            const clearActiveReset = () => {
+                if (activeReset === reset) {
+                    activeReset = null;
                 }
-            }
-            runningNode = await buildNode(undefined);
-            return await runningNode.getBestStateRootHash();
+            };
+            reset.then(clearActiveReset, clearActiveReset);
+            return reset;
         },
     });
-    return () => {
-        closeFuzzTarget();
-        // Close the reused fjall values session (if any) before wiping its files, so
-        // the keyspace handle is released first.
-        const closed = fjallSession?.close() ?? Promise.resolve();
-        fjallSession = null;
-        if (fuzzDbBase !== undefined) {
-            // best-effort cleanup on shutdown; ignore failures (dir may already be gone).
-            closed
-                .catch(() => { })
-                .finally(() => {
-                wipeFuzzDb(fuzzDbBase).catch(() => { });
-            });
-        }
+    return {
+        close: async () => {
+            isClosing = true;
+            // Stop accepting connections + unlink the socket.
+            closeFuzzTarget();
+            // Drain the active session (flush + close DB). Swallow errors so a
+            // failing close still lets the process exit 0; the db is wiped next.
+            // The node references the shared fjall session, so it must close first.
+            if (activeReset !== null) {
+                await activeReset.catch((e) => logger.error `Error waiting for fuzz reset: ${e}`);
+            }
+            if (runningNode !== null) {
+                const node = runningNode;
+                runningNode = null;
+                await node.close().catch((e) => logger.error `Error closing fuzz node: ${e}`);
+            }
+            // Release the reused fjall values keyspace before wiping its files.
+            if (fjallSession !== null) {
+                const session = fjallSession;
+                fjallSession = null;
+                await session.close().catch((e) => logger.error `Error closing fjall session: ${e}`);
+            }
+            if (fuzzDbBase !== undefined) {
+                await wipeFuzzDb(fuzzDbBase).catch(() => { });
+            }
+        },
     };
 }
 function isValidStateBackend(val) {