@typeberry/lib 0.9.0-3f2c45b → 0.9.0-6850f84

package/package.json

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

package/packages/core/collections/sorted-array.d.ts

@@ -56,7 +56,7 @@ export declare class SortedArray<V> implements ImmutableSortedArray<V> {
     findIndex(v: V): number;
     findExact(v: V): V | undefined;
     /** Remove one matching element from the collection. */
-    removeOne(v: V): void;
+    removeOne(v: V): V | undefined;
     has(v: V): boolean;
     get length(): number;
     /** Return a regular array that's a copy of this one. */

package/packages/core/collections/sorted-array.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sorted-array.d.ts","sourceRoot":"","sources":["../../../../../packages/core/collections/sorted-array.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAGtD,MAAM,WAAW,oBAAoB,CAAC,CAAC,CAAE,SAAQ,QAAQ,CAAC,CAAC,CAAC;IAC1D,wBAAwB;IACxB,IAAI,KAAK,IAAI,SAAS,CAAC,EAAE,CAAC;IAC1B,6BAA6B;IAC7B,IAAI,UAAU,IAAI,UAAU,CAAC,CAAC,CAAC,CAAC;IAEhC;;;OAGG;IACH,SAAS,CAAC,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC;IAExB;;;;;;;OAOG;IACH,SAAS,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC;IAE/B,qDAAqD;IACrD,GAAG,CAAC,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC;IAEnB,+CAA+C;IAC/C,IAAI,MAAM,IAAI,MAAM,CAAC;IAErB,wDAAwD;IACxD,KAAK,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,CAAC,EAAE,CAAC;CAC1C;AAED;;;;;;;GAOG;AACH,qBAAa,WAAW,CAAC,CAAC,CAAE,YAAW,oBAAoB,CAAC,CAAC,CAAC;aAgC1C,KAAK,EAAE,CAAC,EAAE;aACV,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC;IAhC3C;;OAEG;IACH,MAAM,CAAC,SAAS,CAAC,CAAC,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,KAAK,GAAE,SAAS,CAAC,EAAO;IAMvE;;OAEG;IACH,MAAM,CAAC,eAAe,CAAC,CAAC,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,KAAK,GAAE,SAAS,CAAC,EAAO;IAkB7E,SAAS,aACS,KAAK,EAAE,CAAC,EAAE,EACV,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC;IAG3C,4CAA4C;IACrC,MAAM,CAAC,CAAC,EAAE,CAAC;IAKlB;;;;OAIG;IACI,GAAG,IAAI,CAAC,GAAG,SAAS;IAIpB,SAAS,CAAC,CAAC,EAAE,CAAC;IASd,SAAS,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,SAAS;IASrC,uDAAuD;IAChD,SAAS,CAAC,CAAC,EAAE,CAAC;IAQd,GAAG,CAAC,CAAC,EAAE,CAAC;IAIf,IAAW,MAAM,IAAI,MAAM,CAE1B;IAED,wDAAwD;IACjD,KAAK,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,CAAC,EAAE;IAI/C,SAAS,CAAC,YAAY,CAAC,CAAC,EAAE,CAAC;;;;IA8B3B,4DAA4D;IAC5D,MAAM,CAAC,wBAAwB,CAAC,CAAC,EAAE,KAAK,EAAE,oBAAoB,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,oBAAoB,CAAC,CAAC,CAAC;IAqClG,kDAAkD;IACjD,CAAC,MAAM,CAAC,QAAQ,CAAC;CAKnB"}
+{"version":3,"file":"sorted-array.d.ts","sourceRoot":"","sources":["../../../../../packages/core/collections/sorted-array.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAGtD,MAAM,WAAW,oBAAoB,CAAC,CAAC,CAAE,SAAQ,QAAQ,CAAC,CAAC,CAAC;IAC1D,wBAAwB;IACxB,IAAI,KAAK,IAAI,SAAS,CAAC,EAAE,CAAC;IAC1B,6BAA6B;IAC7B,IAAI,UAAU,IAAI,UAAU,CAAC,CAAC,CAAC,CAAC;IAEhC;;;OAGG;IACH,SAAS,CAAC,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC;IAExB;;;;;;;OAOG;IACH,SAAS,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC;IAE/B,qDAAqD;IACrD,GAAG,CAAC,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC;IAEnB,+CAA+C;IAC/C,IAAI,MAAM,IAAI,MAAM,CAAC;IAErB,wDAAwD;IACxD,KAAK,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,CAAC,EAAE,CAAC;CAC1C;AAED;;;;;;;GAOG;AACH,qBAAa,WAAW,CAAC,CAAC,CAAE,YAAW,oBAAoB,CAAC,CAAC,CAAC;aAgC1C,KAAK,EAAE,CAAC,EAAE;aACV,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC;IAhC3C;;OAEG;IACH,MAAM,CAAC,SAAS,CAAC,CAAC,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,KAAK,GAAE,SAAS,CAAC,EAAO;IAMvE;;OAEG;IACH,MAAM,CAAC,eAAe,CAAC,CAAC,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,KAAK,GAAE,SAAS,CAAC,EAAO;IAkB7E,SAAS,aACS,KAAK,EAAE,CAAC,EAAE,EACV,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC;IAG3C,4CAA4C;IACrC,MAAM,CAAC,CAAC,EAAE,CAAC;IAKlB;;;;OAIG;IACI,GAAG,IAAI,CAAC,GAAG,SAAS;IAIpB,SAAS,CAAC,CAAC,EAAE,CAAC;IASd,SAAS,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,SAAS;IASrC,uDAAuD;IAChD,SAAS,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,SAAS;IAU9B,GAAG,CAAC,CAAC,EAAE,CAAC;IAIf,IAAW,MAAM,IAAI,MAAM,CAE1B;IAED,wDAAwD;IACjD,KAAK,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,CAAC,EAAE;IAI/C,SAAS,CAAC,YAAY,CAAC,CAAC,EAAE,CAAC;;;;IA8B3B,4DAA4D;IAC5D,MAAM,CAAC,wBAAwB,CAAC,CAAC,EAAE,KAAK,EAAE,oBAAoB,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,oBAAoB,CAAC,CAAC,CAAC;IAqClG,kDAAkD;IACjD,CAAC,MAAM,CAAC,QAAQ,CAAC;CAKnB"}

package/packages/core/collections/sorted-array.js

@@ -69,9 +69,11 @@ export class SortedArray {
     removeOne(v) {
         const findIdx = this.binarySearch(v);
         if (findIdx.isEqual) {
-            // remove the element
-            this.array.splice(findIdx.idx, 1);
+            // remove the element and return the stored one
+            const [removed] = this.array.splice(findIdx.idx, 1);
+            return removed;
         }
+        return undefined;
     }
     has(v) {
         return this.binarySearch(v).isEqual;

package/packages/core/collections/sorted-array.test.js

@@ -59,6 +59,16 @@ describe("SortedArray", { timeout: 10 }, () => {
         data.removeOne(2);
         assert.deepStrictEqual(data.slice(), [3]);
     });
+    it("should return the stored element that was removed", () => {
+        const byKey = (self, other) => cmp(self[0], other[0]);
+        const data = SortedArray.fromArray(byKey, [
+            [1, "a"],
+            [2, "b"],
+        ]);
+        const removed = data.removeOne([1, "x"]);
+        assert.deepStrictEqual(removed, [1, "a"]);
+        assert.strictEqual(data.removeOne([5, "z"]), undefined);
+    });
     it("should throw when using fromSortedArray and array is not sorted", () => {
         const data = [1, 3, 2];
         const tryToCreate = () => SortedArray.fromSortedArray(cmp, data);

package/packages/core/collections/sorted-set.d.ts

@@ -34,7 +34,7 @@ export declare class SortedSet<V> extends SortedArray<V> implements ImmutableSor
      *
      * Putting another value that's equal via comparator will replace the current one.
      */
-    replace(v: V): void;
+    replace(v: V): V | undefined;
     /** Create a new SortedSet from two sorted collections. */
     static fromTwoSortedCollections<V>(first: ImmutableSortedArray<V>, second: ImmutableSortedArray<V>): SortedSet<V>;
 }

package/packages/core/collections/sorted-set.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sorted-set.d.ts","sourceRoot":"","sources":["../../../../../packages/core/collections/sorted-set.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEtD,OAAO,EAAE,KAAK,oBAAoB,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAE3E,MAAM,WAAW,kBAAkB,CAAC,CAAC,CAAE,SAAQ,oBAAoB,CAAC,CAAC,CAAC;CAAG;AAEzE;;;;;;;GAOG;AACH,qBAAa,SAAS,CAAC,CAAC,CAAE,SAAQ,WAAW,CAAC,CAAC,CAAE,YAAW,kBAAkB,CAAC,CAAC,CAAC;IAC/E;;;OAGG;IACH,MAAM,CAAC,SAAS,CAAC,CAAC,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,KAAK,GAAE,SAAS,CAAC,EAAO;IAkBvE;;;OAGG;IACH,MAAM,CAAC,eAAe,CAAC,CAAC,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE;IAaxE;;;;OAIG;IACH,MAAM,CAAC,eAAe,CAAC,CAAC,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,KAAK,GAAE,SAAS,CAAC,EAAO;IAiB7E,wEAAwE;IACjE,MAAM,CAAC,CAAC,EAAE,CAAC;IAOlB;;;;OAIG;IACI,OAAO,CAAC,CAAC,EAAE,CAAC;IAMnB,0DAA0D;IAC1D,MAAM,CAAC,wBAAwB,CAAC,CAAC,EAAE,KAAK,EAAE,oBAAoB,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,oBAAoB,CAAC,CAAC,CAAC;CA0BnG"}
+{"version":3,"file":"sorted-set.d.ts","sourceRoot":"","sources":["../../../../../packages/core/collections/sorted-set.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEtD,OAAO,EAAE,KAAK,oBAAoB,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAE3E,MAAM,WAAW,kBAAkB,CAAC,CAAC,CAAE,SAAQ,oBAAoB,CAAC,CAAC,CAAC;CAAG;AAEzE;;;;;;;GAOG;AACH,qBAAa,SAAS,CAAC,CAAC,CAAE,SAAQ,WAAW,CAAC,CAAC,CAAE,YAAW,kBAAkB,CAAC,CAAC,CAAC;IAC/E;;;OAGG;IACH,MAAM,CAAC,SAAS,CAAC,CAAC,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,KAAK,GAAE,SAAS,CAAC,EAAO;IAkBvE;;;OAGG;IACH,MAAM,CAAC,eAAe,CAAC,CAAC,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE;IAaxE;;;;OAIG;IACH,MAAM,CAAC,eAAe,CAAC,CAAC,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,KAAK,GAAE,SAAS,CAAC,EAAO;IAiB7E,wEAAwE;IACjE,MAAM,CAAC,CAAC,EAAE,CAAC;IAOlB;;;;OAIG;IACI,OAAO,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,SAAS;IAUnC,0DAA0D;IAC1D,MAAM,CAAC,wBAAwB,CAAC,CAAC,EAAE,KAAK,EAAE,oBAAoB,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,oBAAoB,CAAC,CAAC,CAAC;CA0BnG"}

package/packages/core/collections/sorted-set.js

@@ -73,8 +73,12 @@ export class SortedSet extends SortedArray {
      */
     replace(v) {
         const findIdx = this.binarySearch(v);
-        const toRemove = findIdx.isEqual ? 1 : 0;
-        this.array.splice(findIdx.idx, toRemove, v);
+        if (findIdx.isEqual) {
+            const [displaced] = this.array.splice(findIdx.idx, 1, v);
+            return displaced;
+        }
+        this.array.splice(findIdx.idx, 0, v);
+        return undefined;
     }
     /** Create a new SortedSet from two sorted collections. */
     static fromTwoSortedCollections(first, second) {

package/packages/core/collections/sorted-set.test.js

@@ -65,6 +65,30 @@ describe("SortedSet", () => {
             assert.deepStrictEqual(data.length, 3);
         });
     });
+    describe("replace", () => {
+        const byKey = (self, other) => cmp(self[0], other[0]);
+        it("should return the displaced element when replacing an equal one", () => {
+            const data = SortedSet.fromArrayUnique(byKey, [
+                [1, "a"],
+                [2, "b"],
+            ]);
+            const displaced = data.replace([1, "c"]);
+            assert.deepStrictEqual(displaced, [1, "a"]);
+            assert.deepStrictEqual(data.slice(), [
+                [1, "c"],
+                [2, "b"],
+            ]);
+        });
+        it("should return undefined when inserting a fresh element", () => {
+            const data = SortedSet.fromArrayUnique(byKey, [[1, "a"]]);
+            const displaced = data.replace([2, "b"]);
+            assert.strictEqual(displaced, undefined);
+            assert.deepStrictEqual(data.slice(), [
+                [1, "a"],
+                [2, "b"],
+            ]);
+        });
+    });
     describe("fromTwoSortedCollections", () => {
         it("should merge two sorted sets without duplicates", () => {
             const arr1 = [1, 2, 3];

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/database/index.d.ts

@@ -4,4 +4,5 @@ export * from "./leaf-db-update.js";
 export * from "./root.js";
 export * from "./serialized-states-db.js";
 export * from "./states.js";
+export * from "./value-refs.js";
 //# sourceMappingURL=index.d.ts.map

package/packages/jam/database/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../packages/jam/database/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,qBAAqB,CAAC;AACpC,cAAc,WAAW,CAAC;AAC1B,cAAc,2BAA2B,CAAC;AAC1C,cAAc,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../packages/jam/database/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,qBAAqB,CAAC;AACpC,cAAc,WAAW,CAAC;AAC1B,cAAc,2BAA2B,CAAC;AAC1C,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC"}

package/packages/jam/database/index.js

@@ -4,3 +4,4 @@ export * from "./leaf-db-update.js";
 export * from "./root.js";
 export * from "./serialized-states-db.js";
 export * from "./states.js";
+export * from "./value-refs.js";

package/packages/jam/database/leaf-db-update.d.ts

@@ -5,6 +5,7 @@ import { StateEntryUpdateAction, type StateKey } from "#@typeberry/state-merklei
 import { type LeafNode, type ValueHash } from "#@typeberry/trie";
 export declare function updateLeafs(leafs: SortedSet<LeafNode>, blake2b: Blake2b, data: Iterable<[StateEntryUpdateAction, StateKey | TruncatedHash, BytesBlob]>): {
     values: [ValueHash, BytesBlob][];
+    removed: ValueHash[];
     leafs: SortedSet<LeafNode>;
 };
 //# sourceMappingURL=leaf-db-update.d.ts.map

package/packages/jam/database/leaf-db-update.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"leaf-db-update.d.ts","sourceRoot":"","sources":["../../../../../packages/jam/database/leaf-db-update.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAC9D,OAAO,EAAE,sBAAsB,EAAE,KAAK,QAAQ,EAAE,MAAM,gCAAgC,CAAC;AACvF,OAAO,EAAgB,KAAK,QAAQ,EAAE,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAI9E,wBAAgB,WAAW,CACzB,KAAK,EAAE,SAAS,CAAC,QAAQ,CAAC,EAC1B,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,QAAQ,CAAC,CAAC,sBAAsB,EAAE,QAAQ,GAAG,aAAa,EAAE,SAAS,CAAC,CAAC,GAC5E;IACD,MAAM,EAAE,CAAC,SAAS,EAAE,SAAS,CAAC,EAAE,CAAC;IACjC,KAAK,EAAE,SAAS,CAAC,QAAQ,CAAC,CAAC;CAC5B,CAwBA"}
+{"version":3,"file":"leaf-db-update.d.ts","sourceRoot":"","sources":["../../../../../packages/jam/database/leaf-db-update.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAC9D,OAAO,EAAE,sBAAsB,EAAE,KAAK,QAAQ,EAAE,MAAM,gCAAgC,CAAC;AACvF,OAAO,EAAgB,KAAK,QAAQ,EAAE,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAI9E,wBAAgB,WAAW,CACzB,KAAK,EAAE,SAAS,CAAC,QAAQ,CAAC,EAC1B,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,QAAQ,CAAC,CAAC,sBAAsB,EAAE,QAAQ,GAAG,aAAa,EAAE,SAAS,CAAC,CAAC,GAC5E;IACD,MAAM,EAAE,CAAC,SAAS,EAAE,SAAS,CAAC,EAAE,CAAC;IACjC,OAAO,EAAE,SAAS,EAAE,CAAC;IACrB,KAAK,EAAE,SAAS,CAAC,QAAQ,CAAC,CAAC;CAC5B,CAyCA"}

package/packages/jam/database/leaf-db-update.js

@@ -7,18 +7,34 @@ export function updateLeafs(leafs, blake2b, data) {
     const blake2bTrieHasher = getBlake2bTrieHasher(blake2b);
     // We will collect all values that don't fit directly into leaf nodes.
     const values = [];
+    // Value hashes that are no longer referenced by the leaf they were stored under.
+    // NOTE this does not yet mean they can be removed from the DB - the same value
+    // may still be referenced by another leaf or another state. It's up to value
+    // ref-counting to decide that.
+    const removed = [];
     for (const [action, key, value] of data) {
         if (action === StateEntryUpdateAction.Insert) {
             const leafNode = InMemoryTrie.constructLeaf(blake2bTrieHasher, key.asOpaque(), value);
-            leafs.replace(leafNode);
-            if (!leafNode.hasEmbeddedValue()) {
-                values.push([leafNode.getValueHash(), value]);
+            const displaced = leafs.replace(leafNode);
+            const newHash = leafNode.hasEmbeddedValue() ? null : leafNode.getValueHash();
+            const oldHash = displaced !== undefined && !displaced.hasEmbeddedValue() ? displaced.getValueHash() : null;
+            // Re-inserting the exact same value under the same key is a no-op for the DB.
+            if (newHash !== null && oldHash !== null && newHash.isEqualTo(oldHash)) {
+                continue;
+            }
+            if (newHash !== null) {
+                values.push([newHash, value]);
+            }
+            if (oldHash !== null) {
+                removed.push(oldHash);
             }
         }
         else if (action === StateEntryUpdateAction.Remove) {
             const leafNode = InMemoryTrie.constructLeaf(blake2bTrieHasher, key.asOpaque(), BytesBlob.empty());
-            leafs.removeOne(leafNode);
-            // TODO [ToDr] Handle ref-counting values or updating some header-hash-based references.
+            const removedLeaf = leafs.removeOne(leafNode);
+            if (removedLeaf !== undefined && !removedLeaf.hasEmbeddedValue()) {
+                removed.push(removedLeaf.getValueHash());
+            }
         }
         else {
             assertNever(action);
@@ -26,6 +42,7 @@ export function updateLeafs(leafs, blake2b, data) {
     }
     return {
         values,
+        removed,
         leafs,
     };
 }

package/packages/jam/database/leaf-db-update.test.d.ts

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

package/packages/jam/database/leaf-db-update.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"leaf-db-update.test.d.ts","sourceRoot":"","sources":["../../../../../packages/jam/database/leaf-db-update.test.ts"],"names":[],"mappings":""}

package/packages/jam/database/leaf-db-update.test.js

@@ -0,0 +1,81 @@
+import assert from "node:assert";
+import { before, describe, it } from "node:test";
+import { Bytes, BytesBlob } from "#@typeberry/bytes";
+import { SortedSet } from "#@typeberry/collections";
+import { Blake2b, HASH_SIZE } from "#@typeberry/hash";
+import { StateEntryUpdateAction } from "#@typeberry/state-merkleization";
+import { leafComparator } from "#@typeberry/trie";
+import { updateLeafs } from "./leaf-db-update.js";
+let blake2b;
+before(async () => {
+    blake2b = await Blake2b.createHasher();
+});
+function key(n) {
+    return Bytes.fill(HASH_SIZE, n).asOpaque();
+}
+/** A value larger than 32 bytes, so it does not fit into the leaf and is hash-referenced. */
+function bigValue(b) {
+    return Bytes.fill(64, b);
+}
+/** A value that fits directly into the leaf node. */
+function smallValue(b) {
+    return Bytes.fill(4, b);
+}
+function emptyLeafs() {
+    return SortedSet.fromArray(leafComparator, []);
+}
+function asStrings(hashes) {
+    return hashes.map((h) => h.toString());
+}
+describe("updateLeafs", () => {
+    it("collects a freshly inserted non-embedded value and removes nothing", () => {
+        const leafs = emptyLeafs();
+        const res = updateLeafs(leafs, blake2b, [[StateEntryUpdateAction.Insert, key(1), bigValue(0xaa)]]);
+        assert.strictEqual(res.values.length, 1);
+        assert.deepStrictEqual(res.removed, []);
+    });
+    it("collects nothing for an embedded value", () => {
+        const leafs = emptyLeafs();
+        const res = updateLeafs(leafs, blake2b, [[StateEntryUpdateAction.Insert, key(1), smallValue(0xaa)]]);
+        assert.deepStrictEqual(res.values, []);
+        assert.deepStrictEqual(res.removed, []);
+    });
+    it("emits the displaced value hash in `removed` when a leaf is replaced", () => {
+        const leafs = emptyLeafs();
+        const first = updateLeafs(leafs, blake2b, [[StateEntryUpdateAction.Insert, key(1), bigValue(0xaa)]]);
+        const oldHash = first.values[0][0];
+        const res = updateLeafs(leafs, blake2b, [[StateEntryUpdateAction.Insert, key(1), bigValue(0xbb)]]);
+        assert.strictEqual(res.values.length, 1);
+        assert.deepStrictEqual(asStrings(res.removed), asStrings([oldHash]));
+    });
+    it("cancels out when the same value is re-inserted at the same key", () => {
+        const leafs = emptyLeafs();
+        updateLeafs(leafs, blake2b, [[StateEntryUpdateAction.Insert, key(1), bigValue(0xaa)]]);
+        const res = updateLeafs(leafs, blake2b, [[StateEntryUpdateAction.Insert, key(1), bigValue(0xaa)]]);
+        assert.deepStrictEqual(res.values, []);
+        assert.deepStrictEqual(res.removed, []);
+    });
+    it("emits the old hash when a non-embedded value becomes embedded", () => {
+        const leafs = emptyLeafs();
+        const first = updateLeafs(leafs, blake2b, [[StateEntryUpdateAction.Insert, key(1), bigValue(0xaa)]]);
+        const oldHash = first.values[0][0];
+        const res = updateLeafs(leafs, blake2b, [[StateEntryUpdateAction.Insert, key(1), smallValue(0xbb)]]);
+        assert.deepStrictEqual(res.values, []);
+        assert.deepStrictEqual(asStrings(res.removed), asStrings([oldHash]));
+    });
+    it("emits the removed value hash when a non-embedded leaf is removed", () => {
+        const leafs = emptyLeafs();
+        const first = updateLeafs(leafs, blake2b, [[StateEntryUpdateAction.Insert, key(1), bigValue(0xaa)]]);
+        const oldHash = first.values[0][0];
+        const res = updateLeafs(leafs, blake2b, [[StateEntryUpdateAction.Remove, key(1), BytesBlob.empty()]]);
+        assert.deepStrictEqual(res.values, []);
+        assert.deepStrictEqual(asStrings(res.removed), asStrings([oldHash]));
+    });
+    it("removes nothing when an embedded leaf is removed", () => {
+        const leafs = emptyLeafs();
+        updateLeafs(leafs, blake2b, [[StateEntryUpdateAction.Insert, key(1), smallValue(0xaa)]]);
+        const res = updateLeafs(leafs, blake2b, [[StateEntryUpdateAction.Remove, key(1), BytesBlob.empty()]]);
+        assert.deepStrictEqual(res.values, []);
+        assert.deepStrictEqual(res.removed, []);
+    });
+});

package/packages/jam/database/serialized-states-db.d.ts

@@ -27,6 +27,7 @@ export declare class InMemorySerializedStates implements StatesDb<SerializedStat
     getStateRoot(state: SerializedState<LeafDb>): Promise<StateRootHash>;
     updateAndSetState(header: HeaderHash, state: SerializedState<LeafDb>, update: Partial<State & ServicesUpdate>): Promise<Result<OK, StateUpdateError>>;
     getState(header: HeaderHash): SerializedState<LeafDb> | null;
+    commitFinalized(_headers: HeaderHash[]): void;
     markUnused(header: HeaderHash): void;
     close(): Promise<void>;
 }