@elaraai/east 1.0.76 → 1.0.77

package/dist/src/serialization/beast2/v5/deflate.spec.js

@@ -0,0 +1,237 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * The deterministic DEFLATE encoder, held to the bit-at-a-time original.
+ *
+ * e3 content-addresses beast2 bytes, so this encoder's output is part of the
+ * wire format: a byte that moves re-keys every stored collection. The
+ * word-packed rewrite (#762) changed only how bits reach the buffer, so the
+ * gate is a differential one — {@link referenceDeflateRaw} below is the
+ * pre-#762 implementation, kept verbatim as the oracle, and every input here
+ * must compress to exactly the same bytes under both. The inflate check on top
+ * proves the shared answer is really RFC 1951.
+ */
+import { describe, test } from "node:test";
+import assert from "node:assert/strict";
+import { deterministicDeflateRaw } from "./deflate.js";
+import { inflateRawPure } from "./inflate.js";
+// ===================================================================
+//  The oracle: the encoder exactly as it stood before #762.
+// ===================================================================
+const WINDOW = 32768;
+const MIN_MATCH = 3;
+const MAX_MATCH = 258;
+const HASH_SIZE = 1 << 15;
+const HASH_MASK = HASH_SIZE - 1;
+const MAX_CHAIN = 32;
+const LEN_BASE = [3, 4, 5, 6, 7, 8, 9, 10, 11, 13, 15, 17, 19, 23, 27, 31, 35, 43, 51, 59, 67, 83, 99, 115, 131, 163, 195, 227, 258];
+const LEN_EXTRA = [0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 2, 2, 2, 2, 3, 3, 3, 3, 4, 4, 4, 4, 5, 5, 5, 5, 0];
+const DIST_BASE = [1, 2, 3, 4, 5, 7, 9, 13, 17, 25, 33, 49, 65, 97, 129, 193, 257, 385, 513, 769, 1025, 1537, 2049, 3073, 4097, 6145, 8193, 12289, 16385, 24577];
+const DIST_EXTRA = [0, 0, 0, 0, 1, 1, 2, 2, 3, 3, 4, 4, 5, 5, 6, 6, 7, 7, 8, 8, 9, 9, 10, 10, 11, 11, 12, 12, 13, 13];
+/** The pre-#762 bit sink: one bit at a time, a byte at a time out. */
+class ReferenceBitWriter {
+    buf;
+    len = 0;
+    cur = 0;
+    bit = 0;
+    constructor(capacity) {
+        this.buf = new Uint8Array(Math.max(64, capacity));
+    }
+    push(byte) {
+        if (this.len === this.buf.length) {
+            const grown = new Uint8Array(this.buf.length * 2);
+            grown.set(this.buf);
+            this.buf = grown;
+        }
+        this.buf[this.len++] = byte;
+    }
+    writeBits(value, count) {
+        for (let i = 0; i < count; i++) {
+            this.cur |= ((value >> i) & 1) << this.bit;
+            if (++this.bit === 8) {
+                this.push(this.cur);
+                this.cur = 0;
+                this.bit = 0;
+            }
+        }
+    }
+    writeCode(code, bits) {
+        for (let i = bits - 1; i >= 0; i--)
+            this.writeBits((code >> i) & 1, 1);
+    }
+    finish() {
+        if (this.bit > 0)
+            this.push(this.cur);
+        return this.buf.subarray(0, this.len);
+    }
+}
+function referenceWriteLitLen(bw, sym) {
+    if (sym <= 143)
+        bw.writeCode(0x30 + sym, 8);
+    else if (sym <= 255)
+        bw.writeCode(0x190 + sym - 144, 9);
+    else if (sym <= 279)
+        bw.writeCode(sym - 256, 7);
+    else
+        bw.writeCode(0xC0 + sym - 280, 8);
+}
+/** The encoder as it stood before #762 — the byte-identity oracle. */
+function referenceDeflateRaw(src) {
+    const bw = new ReferenceBitWriter(Math.max(64, src.length >> 1));
+    bw.writeBits(1, 1);
+    bw.writeBits(1, 2);
+    const head = new Int32Array(HASH_SIZE).fill(-1);
+    const prev = new Int32Array(src.length > 0 ? src.length : 1).fill(-1);
+    const n = src.length;
+    const hashAt = (i) => ((src[i] << 10) ^ (src[i + 1] << 5) ^ src[i + 2]) & HASH_MASK;
+    const insert = (i) => {
+        if (i + MIN_MATCH > n)
+            return;
+        const h = hashAt(i);
+        prev[i] = head[h];
+        head[h] = i;
+    };
+    let pos = 0;
+    while (pos < n) {
+        let bestLen = 0;
+        let bestDist = 0;
+        if (pos + MIN_MATCH <= n) {
+            let cand = head[hashAt(pos)];
+            let chain = 0;
+            const maxLen = Math.min(MAX_MATCH, n - pos);
+            while (cand >= 0 && chain++ < MAX_CHAIN) {
+                const dist = pos - cand;
+                if (dist > WINDOW)
+                    break;
+                let len = 0;
+                while (len < maxLen && src[cand + len] === src[pos + len])
+                    len++;
+                if (len > bestLen) {
+                    bestLen = len;
+                    bestDist = dist;
+                    if (len === maxLen)
+                        break;
+                }
+                cand = prev[cand];
+            }
+        }
+        if (bestLen >= MIN_MATCH) {
+            let lc = 0;
+            while (lc < 28 && LEN_BASE[lc + 1] <= bestLen)
+                lc++;
+            referenceWriteLitLen(bw, 257 + lc);
+            bw.writeBits(bestLen - LEN_BASE[lc], LEN_EXTRA[lc]);
+            let dc = 0;
+            while (dc < 29 && DIST_BASE[dc + 1] <= bestDist)
+                dc++;
+            bw.writeCode(dc, 5);
+            bw.writeBits(bestDist - DIST_BASE[dc], DIST_EXTRA[dc]);
+            for (let i = 0; i < bestLen; i++)
+                insert(pos + i);
+            pos += bestLen;
+        }
+        else {
+            referenceWriteLitLen(bw, src[pos]);
+            insert(pos);
+            pos++;
+        }
+    }
+    referenceWriteLitLen(bw, 256);
+    return bw.finish();
+}
+// ===================================================================
+//  Inputs
+// ===================================================================
+/** xorshift32 — a fixed stream, so a failure reproduces exactly. */
+function rng(seed) {
+    let s = seed >>> 0 || 1;
+    return () => {
+        s ^= s << 13;
+        s >>>= 0;
+        s ^= s >>> 17;
+        s ^= s << 5;
+        s >>>= 0;
+        return s;
+    };
+}
+function randomBytes(n, seed) {
+    const next = rng(seed);
+    const out = new Uint8Array(n);
+    for (let i = 0; i < n; i++)
+        out[i] = next() & 0xff;
+    return out;
+}
+/** Rows of a plausible table: repeated field names, drifting numbers. */
+function structuredBytes(rows, seed) {
+    const next = rng(seed);
+    const parts = [];
+    for (let i = 0; i < rows; i++) {
+        parts.push(`{"id":${i},"site":"site-${i % 40}","region":"R${i % 7}",` +
+            `"f1":${(next() % 100000) / 1000},"n1":${i % 1000},"flag":${(next() & 1) === 1}}`);
+    }
+    return new TextEncoder().encode(parts.join("\n"));
+}
+function cases() {
+    const out = [];
+    // Degenerate lengths around the 3-byte minimum match and the word compare.
+    for (const n of [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 15, 16, 17, 31, 32, 33]) {
+        out.push({ name: `random ${n}B`, bytes: randomBytes(n, 0x5eed + n) });
+        out.push({ name: `one byte x${n}`, bytes: new Uint8Array(n).fill(0x41) });
+    }
+    // A run of one byte: the longest possible matches, back to back.
+    out.push({ name: "one byte x100k", bytes: new Uint8Array(100_000).fill(0) });
+    // Every byte distinct, then every byte distinct twice: no match, then a
+    // match at exactly the window's far edge.
+    const distinct = new Uint8Array(256);
+    for (let i = 0; i < 256; i++)
+        distinct[i] = i;
+    out.push({ name: "all distinct bytes", bytes: distinct });
+    const twice = new Uint8Array(512);
+    twice.set(distinct, 0);
+    twice.set(distinct, 256);
+    out.push({ name: "all distinct bytes, twice", bytes: twice });
+    // A block repeated at exactly WINDOW distance, and just past it.
+    for (const gap of [WINDOW - 1, WINDOW, WINDOW + 1]) {
+        const bytes = randomBytes(gap + 64, 0xc0ffee);
+        bytes.set(bytes.subarray(0, 64), gap);
+        out.push({ name: `64B repeated at ${gap}`, bytes });
+    }
+    // Incompressible and compressible bulk.
+    out.push({ name: "random 1 MiB", bytes: randomBytes(1 << 20, 0xabcdef) });
+    out.push({ name: "structured 4 MiB", bytes: structuredBytes(60_000, 0x1234) });
+    return out;
+}
+// ===================================================================
+describe("beast2 v5 deterministic deflate", () => {
+    test("is byte-identical to the pre-#762 encoder", () => {
+        for (const { name, bytes } of cases()) {
+            const actual = deterministicDeflateRaw(bytes);
+            const expected = referenceDeflateRaw(bytes);
+            assert.deepEqual(Array.from(actual), Array.from(expected), `${name}: the word-packed encoder must reproduce the original's bytes`);
+        }
+    });
+    test("round-trips through inflate", () => {
+        for (const { name, bytes } of cases()) {
+            const round = inflateRawPure(deterministicDeflateRaw(bytes), bytes.length);
+            assert.deepEqual(Array.from(round), Array.from(bytes), `${name}: inflate(deflate(x)) === x`);
+        }
+    });
+    test("compresses a byte run hard, and never expands a frame beyond its literals", () => {
+        const run = new Uint8Array(100_000).fill(0x7f);
+        assert.ok(deterministicDeflateRaw(run).length < run.length / 100);
+        // Incompressible input still goes out as fixed-Huffman literals, which cost
+        // at most 9 bits each. The frame writer is what falls back to codec `none`.
+        const noise = randomBytes(64 * 1024, 0x99);
+        assert.ok(deterministicDeflateRaw(noise).length <= Math.ceil((noise.length * 9) / 8) + 16);
+    });
+    test("respects a subarray's bounds", () => {
+        // The word compare loads through a DataView, which must be built on the
+        // view's own window rather than the whole backing buffer.
+        const backing = randomBytes(4096, 0x777);
+        const middle = backing.subarray(1000, 3000);
+        assert.deepEqual(Array.from(deterministicDeflateRaw(middle)), Array.from(referenceDeflateRaw(middle)));
+    });
+});
+//# sourceMappingURL=deflate.spec.js.map

package/dist/src/serialization/beast2/v5/deflate.spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deflate.spec.js","sourceRoot":"","sources":["../../../../../src/serialization/beast2/v5/deflate.spec.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,MAAM,MAAM,oBAAoB,CAAC;AACxC,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C,sEAAsE;AACtE,4DAA4D;AAC5D,sEAAsE;AAEtE,MAAM,MAAM,GAAG,KAAK,CAAC;AACrB,MAAM,SAAS,GAAG,CAAC,CAAC;AACpB,MAAM,SAAS,GAAG,GAAG,CAAC;AACtB,MAAM,SAAS,GAAG,CAAC,IAAI,EAAE,CAAC;AAC1B,MAAM,SAAS,GAAG,SAAS,GAAG,CAAC,CAAC;AAChC,MAAM,SAAS,GAAG,EAAE,CAAC;AAErB,MAAM,QAAQ,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;AACrI,MAAM,SAAS,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;AAC1G,MAAM,SAAS,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;AACjK,MAAM,UAAU,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC;AAEtH,sEAAsE;AACtE,MAAM,kBAAkB;IACd,GAAG,CAAa;IAChB,GAAG,GAAG,CAAC,CAAC;IACR,GAAG,GAAG,CAAC,CAAC;IACR,GAAG,GAAG,CAAC,CAAC;IAEhB,YAAY,QAAgB;QAC1B,IAAI,CAAC,GAAG,GAAG,IAAI,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC,CAAC;IACpD,CAAC;IAEO,IAAI,CAAC,IAAY;QACvB,IAAI,IAAI,CAAC,GAAG,KAAK,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC;YACjC,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;YAClD,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACpB,IAAI,CAAC,GAAG,GAAG,KAAK,CAAC;QACnB,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC;IAC9B,CAAC;IAED,SAAS,CAAC,KAAa,EAAE,KAAa;QACpC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC;YAC/B,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC;YAC3C,IAAI,EAAE,IAAI,CAAC,GAAG,KAAK,CAAC,EAAE,CAAC;gBAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;gBAAC,IAAI,CAAC,GAAG,GAAG,CAAC,CAAC;gBAAC,IAAI,CAAC,GAAG,GAAG,CAAC,CAAC;YAAC,CAAC;QAC5E,CAAC;IACH,CAAC;IAED,SAAS,CAAC,IAAY,EAAE,IAAY;QAClC,KAAK,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE;YAAE,IAAI,CAAC,SAAS,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;IACzE,CAAC;IAED,MAAM;QACJ,IAAI,IAAI,CAAC,GAAG,GAAG,CAAC;YAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACtC,OAAO,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;IACxC,CAAC;CACF;AAED,SAAS,oBAAoB,CAAC,EAAsB,EAAE,GAAW;IAC/D,IAAI,GAAG,IAAI,GAAG;QAAE,EAAE,CAAC,SAAS,CAAC,IAAI,GAAG,GAAG,EAAE,CAAC,CAAC,CAAC;SACvC,IAAI,GAAG,IAAI,GAAG;QAAE,EAAE,CAAC,SAAS,CAAC,KAAK,GAAG,GAAG,GAAG,GAAG,EAAE,CAAC,CAAC,CAAC;SACnD,IAAI,GAAG,IAAI,GAAG;QAAE,EAAE,CAAC,SAAS,CAAC,GAAG,GAAG,GAAG,EAAE,CAAC,CAAC,CAAC;;QAC3C,EAAE,CAAC,SAAS,CAAC,IAAI,GAAG,GAAG,GAAG,GAAG,EAAE,CAAC,CAAC,CAAC;AACzC,CAAC;AAED,sEAAsE;AACtE,SAAS,mBAAmB,CAAC,GAAe;IAC1C,MAAM,EAAE,GAAG,IAAI,kBAAkB,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC;IACjE,EAAE,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACnB,EAAE,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAEnB,MAAM,IAAI,GAAG,IAAI,UAAU,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IAChD,MAAM,IAAI,GAAG,IAAI,UAAU,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IACtE,MAAM,CAAC,GAAG,GAAG,CAAC,MAAM,CAAC;IAErB,MAAM,MAAM,GAAG,CAAC,CAAS,EAAU,EAAE,CACnC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAE,IAAI,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAE,IAAI,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAE,CAAC,GAAG,SAAS,CAAC;IAEnE,MAAM,MAAM,GAAG,CAAC,CAAS,EAAQ,EAAE;QACjC,IAAI,CAAC,GAAG,SAAS,GAAG,CAAC;YAAE,OAAO;QAC9B,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;QACpB,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAE,CAAC;QACnB,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACd,CAAC,CAAC;IAEF,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,OAAO,GAAG,GAAG,CAAC,EAAE,CAAC;QACf,IAAI,OAAO,GAAG,CAAC,CAAC;QAChB,IAAI,QAAQ,GAAG,CAAC,CAAC;QAEjB,IAAI,GAAG,GAAG,SAAS,IAAI,CAAC,EAAE,CAAC;YACzB,IAAI,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAE,CAAC;YAC9B,IAAI,KAAK,GAAG,CAAC,CAAC;YACd,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC;YAC5C,OAAO,IAAI,IAAI,CAAC,IAAI,KAAK,EAAE,GAAG,SAAS,EAAE,CAAC;gBACxC,MAAM,IAAI,GAAG,GAAG,GAAG,IAAI,CAAC;gBACxB,IAAI,IAAI,GAAG,MAAM;oBAAE,MAAM;gBACzB,IAAI,GAAG,GAAG,CAAC,CAAC;gBACZ,OAAO,GAAG,GAAG,MAAM,IAAI,GAAG,CAAC,IAAI,GAAG,GAAG,CAAC,KAAK,GAAG,CAAC,GAAG,GAAG,GAAG,CAAC;oBAAE,GAAG,EAAE,CAAC;gBACjE,IAAI,GAAG,GAAG,OAAO,EAAE,CAAC;oBAClB,OAAO,GAAG,GAAG,CAAC;oBACd,QAAQ,GAAG,IAAI,CAAC;oBAChB,IAAI,GAAG,KAAK,MAAM;wBAAE,MAAM;gBAC5B,CAAC;gBACD,IAAI,GAAG,IAAI,CAAC,IAAI,CAAE,CAAC;YACrB,CAAC;QACH,CAAC;QAED,IAAI,OAAO,IAAI,SAAS,EAAE,CAAC;YACzB,IAAI,EAAE,GAAG,CAAC,CAAC;YACX,OAAO,EAAE,GAAG,EAAE,IAAI,QAAQ,CAAC,EAAE,GAAG,CAAC,CAAE,IAAI,OAAO;gBAAE,EAAE,EAAE,CAAC;YACrD,oBAAoB,CAAC,EAAE,EAAE,GAAG,GAAG,EAAE,CAAC,CAAC;YACnC,EAAE,CAAC,SAAS,CAAC,OAAO,GAAG,QAAQ,CAAC,EAAE,CAAE,EAAE,SAAS,CAAC,EAAE,CAAE,CAAC,CAAC;YAEtD,IAAI,EAAE,GAAG,CAAC,CAAC;YACX,OAAO,EAAE,GAAG,EAAE,IAAI,SAAS,CAAC,EAAE,GAAG,CAAC,CAAE,IAAI,QAAQ;gBAAE,EAAE,EAAE,CAAC;YACvD,EAAE,CAAC,SAAS,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;YACpB,EAAE,CAAC,SAAS,CAAC,QAAQ,GAAG,SAAS,CAAC,EAAE,CAAE,EAAE,UAAU,CAAC,EAAE,CAAE,CAAC,CAAC;YAEzD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,EAAE,CAAC,EAAE;gBAAE,MAAM,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC;YAClD,GAAG,IAAI,OAAO,CAAC;QACjB,CAAC;aAAM,CAAC;YACN,oBAAoB,CAAC,EAAE,EAAE,GAAG,CAAC,GAAG,CAAE,CAAC,CAAC;YACpC,MAAM,CAAC,GAAG,CAAC,CAAC;YACZ,GAAG,EAAE,CAAC;QACR,CAAC;IACH,CAAC;IAED,oBAAoB,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;IAC9B,OAAO,EAAE,CAAC,MAAM,EAAE,CAAC;AACrB,CAAC;AAED,sEAAsE;AACtE,UAAU;AACV,sEAAsE;AAEtE,oEAAoE;AACpE,SAAS,GAAG,CAAC,IAAY;IACvB,IAAI,CAAC,GAAG,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC;IACxB,OAAO,GAAG,EAAE;QACV,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;QAAC,CAAC,MAAM,CAAC,CAAC;QACvB,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;QACd,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAAC,CAAC,MAAM,CAAC,CAAC;QACtB,OAAO,CAAC,CAAC;IACX,CAAC,CAAC;AACJ,CAAC;AAED,SAAS,WAAW,CAAC,CAAS,EAAE,IAAY;IAC1C,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC,CAAC;IACvB,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,CAAC,CAAC,CAAC;IAC9B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE;QAAE,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,EAAE,GAAG,IAAI,CAAC;IACnD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,yEAAyE;AACzE,SAAS,eAAe,CAAC,IAAY,EAAE,IAAY;IACjD,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC,CAAC;IACvB,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC;QAC9B,KAAK,CAAC,IAAI,CACR,SAAS,CAAC,iBAAiB,CAAC,GAAG,EAAE,gBAAgB,CAAC,GAAG,CAAC,IAAI;YAC1D,QAAQ,CAAC,IAAI,EAAE,GAAG,MAAM,CAAC,GAAG,IAAI,SAAS,CAAC,GAAG,IAAI,WAAW,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAClF,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;AACpD,CAAC;AAED,SAAS,KAAK;IACZ,MAAM,GAAG,GAA0C,EAAE,CAAC;IACtD,2EAA2E;IAC3E,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC;QACvE,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,UAAU,CAAC,GAAG,EAAE,KAAK,EAAE,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC;QACtE,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,aAAa,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,UAAU,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC5E,CAAC;IACD,iEAAiE;IACjE,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,gBAAgB,EAAE,KAAK,EAAE,IAAI,UAAU,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAC7E,wEAAwE;IACxE,0CAA0C;IAC1C,MAAM,QAAQ,GAAG,IAAI,UAAU,CAAC,GAAG,CAAC,CAAC;IACrC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,EAAE,CAAC,EAAE;QAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAC9C,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,oBAAoB,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC;IAC1D,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,GAAG,CAAC,CAAC;IAClC,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC;IACvB,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IACzB,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,2BAA2B,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IAC9D,iEAAiE;IACjE,KAAK,MAAM,GAAG,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,MAAM,EAAE,MAAM,GAAG,CAAC,CAAC,EAAE,CAAC;QACnD,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,GAAG,EAAE,EAAE,QAAQ,CAAC,CAAC;QAC9C,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC;QACtC,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,mBAAmB,GAAG,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;IACtD,CAAC;IACD,wCAAwC;IACxC,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,WAAW,CAAC,CAAC,IAAI,EAAE,EAAE,QAAQ,CAAC,EAAE,CAAC,CAAC;IAC1E,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,kBAAkB,EAAE,KAAK,EAAE,eAAe,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;IAC/E,OAAO,GAAG,CAAC;AACb,CAAC;AAED,sEAAsE;AAEtE,QAAQ,CAAC,iCAAiC,EAAE,GAAG,EAAE;IAC/C,IAAI,CAAC,2CAA2C,EAAE,GAAG,EAAE;QACrD,KAAK,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,KAAK,EAAE,EAAE,CAAC;YACtC,MAAM,MAAM,GAAG,uBAAuB,CAAC,KAAK,CAAC,CAAC;YAC9C,MAAM,QAAQ,GAAG,mBAAmB,CAAC,KAAK,CAAC,CAAC;YAC5C,MAAM,CAAC,SAAS,CACd,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,EAClB,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,EACpB,GAAG,IAAI,+DAA+D,CACvE,CAAC;QACJ,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,6BAA6B,EAAE,GAAG,EAAE;QACvC,KAAK,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,KAAK,EAAE,EAAE,CAAC;YACtC,MAAM,KAAK,GAAG,cAAc,CAAC,uBAAuB,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;YAC3E,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,IAAI,6BAA6B,CAAC,CAAC;QAC/F,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,2EAA2E,EAAE,GAAG,EAAE;QACrF,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC/C,MAAM,CAAC,EAAE,CAAC,uBAAuB,CAAC,GAAG,CAAC,CAAC,MAAM,GAAG,GAAG,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC;QAClE,4EAA4E;QAC5E,4EAA4E;QAC5E,MAAM,KAAK,GAAG,WAAW,CAAC,EAAE,GAAG,IAAI,EAAE,IAAI,CAAC,CAAC;QAC3C,MAAM,CAAC,EAAE,CAAC,uBAAuB,CAAC,KAAK,CAAC,CAAC,MAAM,IAAI,IAAI,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC;IAC7F,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,8BAA8B,EAAE,GAAG,EAAE;QACxC,wEAAwE;QACxE,0DAA0D;QAC1D,MAAM,OAAO,GAAG,WAAW,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QACzC,MAAM,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAC5C,MAAM,CAAC,SAAS,CACd,KAAK,CAAC,IAAI,CAAC,uBAAuB,CAAC,MAAM,CAAC,CAAC,EAC3C,KAAK,CAAC,IAAI,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAC,CACxC,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/src/serialization/beast2/v5/frame-pool.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * Beast2 v5 frame pool — deflating frames on worker threads (issue #763).
+ *
+ * v5 frames are independent (one segment per frame, each decoded standalone),
+ * so a writer can deflate them in parallel with no format change, provided it
+ * puts them on the wire in submission order. The pool is only the parallel
+ * half: {@link Beast2Writer} submits each segment's logical bytes and appends
+ * the resulting frames in order, assigning index offsets as they land.
+ *
+ * The writer's API is synchronous — {@link Beast2Writer.write} is called from
+ * inside compiled East bodies (the emit sink) — so results cannot come back as
+ * messages the main thread would have to yield to receive. Each job instead
+ * carries three `SharedArrayBuffer`s: the logical bytes in, the frame bytes
+ * out, and a status cell the worker flips and `Atomics.notify`s. The main
+ * thread polls the cell to append what is done and `Atomics.wait`s on it only
+ * when it must (back-pressure, a settle, `finish`).
+ *
+ * Node-only and optional: without `worker_threads`, `SharedArrayBuffer` or a
+ * second CPU, {@link framePool} returns `null` and the writer frames inline,
+ * which yields the same bytes. Node's modules are reached through
+ * `process.getBuiltinModule` — as `frames.ts` reaches zlib — so browser
+ * bundles never see a `node:` import.
+ *
+ * A worker can die without flipping a status cell — a worker-thread OOM ends
+ * its isolate before its `catch` runs — and the main thread cannot receive the
+ * worker's `exit` event while it is blocked waiting on that worker's frame. So
+ * every wait is bounded: a frame pending past the wait timeout fails, the pool
+ * is abandoned, and the process frames inline from then on.
+ *
+ * The pool is process-wide and outlives the write that started it, so a
+ * long-lived process — an API server, a terminal UI — would otherwise keep one
+ * idle V8 isolate per CPU for good. A pool with no frame outstanding and no
+ * activity for the idle limit terminates its workers, and the next pooled
+ * write starts a new pool. A writer abandoned mid-flight never takes its
+ * frames, so it keeps the pool alive; the idle check is `unref`'d, so process
+ * exit is unaffected either way.
+ */
+import type { Beast2Codec } from "./frames.js";
+/** An upper bound on a frame's header: varint(codec) + varint(uncompressed
+ *  length) + varint(payload length). A frame's payload never exceeds its
+ *  logical bytes (`writeFrame` stores codec `none` when deflate does not
+ *  shrink), so logical + this bounds a frame not yet written. */
+export declare const FRAME_HEADER_MAX = 21;
+/** A frame being deflated on a worker. */
+export interface PendingFrame {
+    /** The logical bytes the frame carries — its payload's upper bound. */
+    readonly logicalLength: number;
+    /** Whether the frame is ready, without blocking. */
+    ready(): boolean;
+    /**
+     * The frame's wire bytes, blocking until the worker has written them.
+     *
+     * @returns the frame bytes
+     * @throws {Error} When the worker failed to build the frame, or stopped
+     *   responding — the frame was still pending when the wait timed out, or its
+     *   pool had already lost a worker. A lost worker abandons the pool: the
+     *   process frames inline from then on.
+     */
+    take(): Uint8Array;
+}
+/** A process-wide set of frame workers. */
+export interface FramePool {
+    /** Worker count — the writer queues at most two frames per worker. */
+    readonly workers: number;
+    /**
+     * Hands a segment's logical bytes to a worker.
+     *
+     * @param logical - the segment's logical bytes (copied; the caller may reuse them)
+     * @param codec - the requested frame codec
+     * @returns the frame, pending
+     */
+    submit(logical: Uint8Array, codec: Beast2Codec): PendingFrame;
+    /**
+     * Terminates every worker thread. A frame still pending on one never
+     * completes, so its {@link PendingFrame.take} fails once the wait times out.
+     *
+     * @returns a promise that settles once every thread has exited
+     * @internal
+     */
+    terminateWorkers(): Promise<void>;
+}
+/** The frame pool's tunable timeouts — see {@link configureFramePool}. */
+export interface FramePoolSettings {
+    /** How long {@link PendingFrame.take} waits for one frame before it presumes
+     *  the worker's thread lost, in milliseconds. */
+    waitTimeoutMs?: number;
+    /** How long a pool with no frame outstanding keeps its workers before it
+     *  terminates them, in milliseconds. */
+    idleMs?: number;
+}
+/**
+ * The process's frame pool, created on first use — and again after an idle
+ * pool retired its workers.
+ *
+ * @returns the pool, or `null` when frames must be written inline — no Node
+ *   `worker_threads`, no `SharedArrayBuffer`, a single CPU, not the main thread
+ *   (a pool per worker would only oversubscribe), worker start-up failed, or
+ *   an earlier pool lost a worker
+ */
+export declare function framePool(): FramePool | null;
+/**
+ * Changes the frame pool's timeouts, for tests that cannot wait them out.
+ *
+ * @param options - the settings to change; an omitted one keeps its value
+ * @returns every setting as it was before, to restore afterwards
+ * @internal
+ */
+export declare function configureFramePool(options: FramePoolSettings): Required<FramePoolSettings>;
+/** Status cell values, for the worker. @internal */
+export declare const FRAME_STATUS: {
+    readonly PENDING: 0;
+    readonly DONE: 1;
+    readonly FAILED: 2;
+};
+//# sourceMappingURL=frame-pool.d.ts.map

package/dist/src/serialization/beast2/v5/frame-pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame-pool.d.ts","sourceRoot":"","sources":["../../../../../src/serialization/beast2/v5/frame-pool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C;;;iEAGiE;AACjE,eAAO,MAAM,gBAAgB,KAAK,CAAC;AAOnC,0CAA0C;AAC1C,MAAM,WAAW,YAAY;IAC3B,uEAAuE;IACvE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,oDAAoD;IACpD,KAAK,IAAI,OAAO,CAAC;IACjB;;;;;;;;OAQG;IACH,IAAI,IAAI,UAAU,CAAC;CACpB;AAED,2CAA2C;AAC3C,MAAM,WAAW,SAAS;IACxB,sEAAsE;IACtE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;;;;OAMG;IACH,MAAM,CAAC,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,WAAW,GAAG,YAAY,CAAC;IAC9D;;;;;;OAMG;IACH,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACnC;AAED,0EAA0E;AAC1E,MAAM,WAAW,iBAAiB;IAChC;qDACiD;IACjD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;4CACwC;IACxC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAuDD;;;;;;;;GAQG;AACH,wBAAgB,SAAS,IAAI,SAAS,GAAG,IAAI,CAM5C;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,iBAAiB,GAAG,QAAQ,CAAC,iBAAiB,CAAC,CAM1F;AA2JD,oDAAoD;AACpD,eAAO,MAAM,YAAY;;;;CAAqC,CAAC"}

package/dist/src/serialization/beast2/v5/frame-pool.js

@@ -0,0 +1,235 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/** An upper bound on a frame's header: varint(codec) + varint(uncompressed
+ *  length) + varint(payload length). A frame's payload never exceeds its
+ *  logical bytes (`writeFrame` stores codec `none` when deflate does not
+ *  shrink), so logical + this bounds a frame not yet written. */
+export const FRAME_HEADER_MAX = 21;
+/** Status cell values. */
+const PENDING = 0;
+const DONE = 1;
+const FAILED = 2;
+/** How long pool creation waits for every worker to report it loaded. A
+ *  worker boots in tens of milliseconds; this only bounds a broken install. */
+const STARTUP_TIMEOUT_MS = 10_000;
+/** The most workers the pool starts. A writer keeps two frames per worker in
+ *  flight, so memory scales with the worker count, while deflate throughput
+ *  flattens well before this (#763 measured 254 MB/s at 32 threads). east-c's
+ *  writer caps its threads the same (`B2V5_POOL_MAX_THREADS`). */
+const FRAME_POOL_MAX_WORKERS = 32;
+/** How long {@link PendingFrame.take} waits for one frame before it presumes
+ *  the worker's thread lost. A 4 MiB segment deflates in well under a second,
+ *  so this fires only when the worker is gone. */
+const FRAME_WAIT_TIMEOUT_MS = 60_000;
+/** The slices a blocked {@link PendingFrame.take} waits in, checking its
+ *  deadline between them. */
+const FRAME_WAIT_SLICE_MS = 1_000;
+/** How long a pool with no frame outstanding keeps its workers. Starting a
+ *  pool costs tens of milliseconds, so a busy process never pays it twice;
+ *  an idle one does not hold an isolate per CPU for its whole life. */
+const FRAME_POOL_IDLE_MS = 30_000;
+/** How often the live pool is checked for idleness (more often only when the
+ *  idle limit is shorter). */
+const IDLE_CHECK_INTERVAL_MS = 10_000;
+/** The timeouts in force; {@link configureFramePool} changes them. */
+const settings = {
+    waitTimeoutMs: FRAME_WAIT_TIMEOUT_MS,
+    idleMs: FRAME_POOL_IDLE_MS,
+};
+/** `undefined` until first asked for, and again once an idle pool retires;
+ *  `null` when this runtime cannot pool, or once a pool has lost a worker. */
+let shared;
+/** The live pool's idle check; `undefined` while no pool is live. */
+let idleCheck;
+/**
+ * The process's frame pool, created on first use — and again after an idle
+ * pool retired its workers.
+ *
+ * @returns the pool, or `null` when frames must be written inline — no Node
+ *   `worker_threads`, no `SharedArrayBuffer`, a single CPU, not the main thread
+ *   (a pool per worker would only oversubscribe), worker start-up failed, or
+ *   an earlier pool lost a worker
+ */
+export function framePool() {
+    if (shared === undefined) {
+        shared = createPool();
+        armIdleCheck();
+    }
+    return shared;
+}
+/**
+ * Changes the frame pool's timeouts, for tests that cannot wait them out.
+ *
+ * @param options - the settings to change; an omitted one keeps its value
+ * @returns every setting as it was before, to restore afterwards
+ * @internal
+ */
+export function configureFramePool(options) {
+    const previous = { ...settings };
+    if (options.waitTimeoutMs !== undefined)
+        settings.waitTimeoutMs = options.waitTimeoutMs;
+    if (options.idleMs !== undefined)
+        settings.idleMs = options.idleMs;
+    armIdleCheck();
+    return previous;
+}
+/**
+ * Gives up on a pool that lost a worker: terminates its threads and makes the
+ * process frame inline from then on — the same bytes, on the calling thread.
+ * Every frame still pending on the pool fails at once rather than waiting out
+ * its own timeout.
+ */
+function abandonPool(pool) {
+    pool.lost = true;
+    void pool.terminateWorkers();
+    shared = null;
+    armIdleCheck();
+}
+/** Starts, restarts or stops the idle check so it runs exactly while a pool
+ *  is live, at a period no longer than the idle limit. */
+function armIdleCheck() {
+    if (idleCheck !== undefined)
+        clearInterval(idleCheck);
+    idleCheck = undefined;
+    if (!(shared instanceof WorkerFramePool))
+        return;
+    idleCheck = setInterval(retireIfIdle, Math.max(1, Math.min(IDLE_CHECK_INTERVAL_MS, settings.idleMs)));
+    // Never keeps a finished process alive.
+    idleCheck.unref?.();
+}
+/** Terminates the live pool's workers once no frame is outstanding and none
+ *  has moved for the idle limit; the next {@link framePool} starts a new one. */
+function retireIfIdle() {
+    const pool = shared;
+    if (pool instanceof WorkerFramePool && pool.outstanding === 0 && Date.now() - pool.lastActivity > settings.idleMs) {
+        void pool.terminateWorkers();
+        shared = undefined;
+    }
+    if (!(shared instanceof WorkerFramePool))
+        armIdleCheck();
+}
+/** The worker-thread pool {@link framePool} hands out. */
+class WorkerFramePool {
+    workers;
+    /** Set once a worker stopped responding; every pending frame then fails. */
+    lost = false;
+    /** Frames submitted and not yet taken — a pool with any is never idle. */
+    outstanding = 0;
+    /** When a frame was last submitted or taken, or the pool started. */
+    lastActivity = Date.now();
+    threads;
+    next = 0;
+    constructor(threads) {
+        this.threads = threads;
+        this.workers = threads.length;
+    }
+    submit(logical, codec) {
+        const input = new SharedArrayBuffer(Math.max(1, logical.length));
+        new Uint8Array(input).set(logical);
+        const output = new SharedArrayBuffer(logical.length + FRAME_HEADER_MAX);
+        const status = new Int32Array(new SharedArrayBuffer(8));
+        this.threads[this.next].postMessage({ input, length: logical.length, output, status: status.buffer, codec });
+        this.next = (this.next + 1) % this.threads.length;
+        this.outstanding++;
+        this.lastActivity = Date.now();
+        let taken = false;
+        return {
+            logicalLength: logical.length,
+            ready: () => Atomics.load(status, 0) !== PENDING,
+            take: () => {
+                try {
+                    const deadline = Date.now() + settings.waitTimeoutMs;
+                    while (Atomics.load(status, 0) === PENDING) {
+                        const remaining = deadline - Date.now();
+                        if (this.lost || remaining <= 0) {
+                            abandonPool(this);
+                            throw new Error("beast2 v5: a frame worker stopped responding — its thread was lost");
+                        }
+                        Atomics.wait(status, 0, PENDING, Math.min(FRAME_WAIT_SLICE_MS, remaining));
+                    }
+                    if (Atomics.load(status, 0) === FAILED) {
+                        throw new Error("beast2 v5: a frame worker failed to build a frame");
+                    }
+                    return new Uint8Array(output, 0, Atomics.load(status, 1)).slice();
+                }
+                finally {
+                    // Taken once, however it ended: a failed frame is not outstanding.
+                    if (!taken) {
+                        taken = true;
+                        this.outstanding--;
+                    }
+                    this.lastActivity = Date.now();
+                }
+            },
+        };
+    }
+    async terminateWorkers() {
+        await Promise.all(this.threads.map((worker) => worker.terminate()));
+    }
+}
+function createPool() {
+    if (typeof SharedArrayBuffer === "undefined" || typeof Atomics === "undefined")
+        return null;
+    const getBuiltin = globalThis
+        .process?.getBuiltinModule;
+    if (typeof getBuiltin !== "function")
+        return null;
+    const threads = getBuiltin("node:worker_threads");
+    const os = getBuiltin("node:os");
+    const fs = getBuiltin("node:fs");
+    if (!threads || !os || !fs || !threads.isMainThread)
+        return null;
+    const cpus = Math.min(FRAME_POOL_MAX_WORKERS, os.availableParallelism?.() ?? os.cpus().length);
+    if (cpus < 2)
+        return null;
+    // Bundled into a single file (or loaded as CommonJS), this module has no
+    // worker script beside it — frame inline rather than fail.
+    let script;
+    try {
+        script = new URL("./frame-worker.js", import.meta.url);
+        if (!fs.existsSync(script))
+            return null;
+    }
+    catch {
+        return null;
+    }
+    // Each worker reports it has LOADED through a shared cell before the pool
+    // is handed out. A worker that fails to load reports only through an
+    // `error` event — which the main thread cannot receive while it is blocked
+    // in `Atomics.wait` on that worker's first job. So a pool is only ever
+    // returned once every worker has proven it runs.
+    const ready = new Int32Array(new SharedArrayBuffer(4 * cpus));
+    const workers = [];
+    const abandon = () => {
+        for (const worker of workers)
+            void worker.terminate();
+        return null;
+    };
+    try {
+        for (let i = 0; i < cpus; i++) {
+            const worker = new threads.Worker(script, { workerData: { ready: ready.buffer, index: i } });
+            // Idle workers must not keep a finished process alive; a writer that
+            // is waiting on one is blocked on the main thread anyway.
+            worker.unref();
+            workers.push(worker);
+        }
+    }
+    catch {
+        return abandon();
+    }
+    const deadline = Date.now() + STARTUP_TIMEOUT_MS;
+    for (let i = 0; i < workers.length; i++) {
+        while (Atomics.load(ready, i) === 0) {
+            const remaining = deadline - Date.now();
+            if (remaining <= 0)
+                return abandon();
+            Atomics.wait(ready, i, 0, remaining);
+        }
+    }
+    return new WorkerFramePool(workers);
+}
+/** Status cell values, for the worker. @internal */
+export const FRAME_STATUS = { PENDING, DONE, FAILED };
+//# sourceMappingURL=frame-pool.js.map

package/dist/src/serialization/beast2/v5/frame-pool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame-pool.js","sourceRoot":"","sources":["../../../../../src/serialization/beast2/v5/frame-pool.ts"],"names":[],"mappings":"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"}

package/dist/src/serialization/beast2/v5/frame-pool.spec.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+export {};
+//# sourceMappingURL=frame-pool.spec.d.ts.map

package/dist/src/serialization/beast2/v5/frame-pool.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame-pool.spec.d.ts","sourceRoot":"","sources":["../../../../../src/serialization/beast2/v5/frame-pool.spec.ts"],"names":[],"mappings":"AAAA;;;GAGG"}