@elaraai/east 1.0.79 → 1.0.80

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

@@ -0,0 +1,118 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * The merge of sorted collections: a key several inputs hold folds in input
+ * order; the output is the canonical blob of the merged value, whatever the
+ * inputs' segments; a key range merges just its keys; and every refusal names
+ * the input it is about.
+ */
+import { describe, test } from "node:test";
+import assert from "node:assert/strict";
+import { ArrayType, DictType, IntegerType, SetType, StringType } from "../../../types.js";
+import { compareFor } from "../../../comparison.js";
+import { toEastTypeValue } from "../../../type_of_type.js";
+import { SortedMap, SortedSet } from "../../../index.js";
+import { COLLECTION_MANIFEST_KIND, carveBeast2, decodeBeast2For, encodeBeast2FenceFor, encodeBeast2For, encodeBeast2PagedFor, encodeBeast2SegmentsFor, mergeBeast2For, openBeast2PagesFor, readBeast2Extents, segmentRuleFor, } from "../index.js";
+const DictSS = DictType(StringType, StringType);
+const DictSI = DictType(StringType, IntegerType);
+/** A sorted Dict from `[key, value]` pairs. */
+const dict = (entries) => new SortedMap(entries, compareFor(StringType));
+/** Merges `sources` and returns the output blob and what the merge came to. */
+function mergeInto(type, sources, options) {
+    const chunks = [];
+    const stats = mergeBeast2For(type, options)(sources, (bytes) => chunks.push(bytes));
+    return { blob: new Uint8Array(Buffer.concat(chunks)), stats };
+}
+describe("beast2 v5 merge of sorted collections", () => {
+    const concat = { merge: (_key, acc, value) => acc + value };
+    test("folds a key several inputs hold, in input order", () => {
+        const inputs = [
+            encodeBeast2PagedFor(DictSS)(dict([["a", "1"], ["b", "x"]])),
+            encodeBeast2PagedFor(DictSS)(dict([["a", "2"]])),
+            encodeBeast2PagedFor(DictSS)(dict([["a", "3"], ["c", "y"]])),
+        ];
+        const { blob, stats } = mergeInto(DictSS, inputs, concat);
+        assert.deepEqual([...decodeBeast2For(DictSS)(blob)], [["a", "123"], ["b", "x"], ["c", "y"]]);
+        assert.deepEqual(stats, { inputs: 3, entries: 3, folds: 2 });
+    });
+    test("writes the canonical blob of the merged value, whatever the inputs' segments", () => {
+        // Inputs cut into segments of the test's own size: the output is still the
+        // bytes a writer of the merged value writes.
+        const evens = dict(Array.from({ length: 6_000 }, (_, i) => [`k${String(2 * i).padStart(6, "0")}`, BigInt(i)]));
+        const odds = dict(Array.from({ length: 6_000 }, (_, i) => [`k${String(2 * i + 1).padStart(6, "0")}`, BigInt(-i)]));
+        const inSegmentsOf = (value, size) => {
+            const entries = [...value];
+            const batches = [];
+            for (let i = 0; i < entries.length; i += size)
+                batches.push(dict(entries.slice(i, i + size)));
+            return encodeBeast2SegmentsFor(DictSI)(batches);
+        };
+        const { blob } = mergeInto(DictSI, [inSegmentsOf(evens, 700), inSegmentsOf(odds, 1_300)]);
+        assert.deepEqual(blob, encodeBeast2PagedFor(DictSI)(dict([...evens, ...odds])));
+    });
+    test("merges just the keys of a range", () => {
+        const value = dict(Array.from({ length: 5_000 }, (_, i) => [`k${String(i).padStart(6, "0")}`, BigInt(i)]));
+        const blob = encodeBeast2PagedFor(DictSI)(value);
+        const inRange = (from, to) => dict([...value].filter(([k]) => (from === undefined || k >= from) && (to === undefined || k < to)));
+        for (const [from, to] of [["k001000", "k003500"], ["k004000", undefined], [undefined, "k000010"], ["k002500", "k002500"]]) {
+            const { blob: merged } = mergeInto(DictSI, [blob], { from, to });
+            assert.deepEqual(merged, encodeBeast2PagedFor(DictSI)(inRange(from, to)), `[${from}, ${to})`);
+        }
+    });
+    test("keeps a Set's shared element once under union", () => {
+        const type = SetType(IntegerType);
+        const set = (xs) => new SortedSet(xs, compareFor(IntegerType));
+        const { blob, stats } = mergeInto(type, [encodeBeast2PagedFor(type)(set([1n, 3n])), encodeBeast2PagedFor(type)(set([2n, 3n]))], { union: true });
+        assert.deepEqual([...decodeBeast2For(type)(blob)], [1n, 2n, 3n]);
+        assert.equal(stats.folds, 1);
+    });
+    test("refuses a key several inputs hold without a fold, naming the key", () => {
+        const inputs = [encodeBeast2PagedFor(DictSS)(dict([["a", "1"]])), encodeBeast2PagedFor(DictSS)(dict([["a", "2"]]))];
+        assert.throws(() => mergeInto(DictSS, inputs), { message: `beast2 v5: duplicate Dict key emitted: "a" — Dict keys must be unique` });
+    });
+    test("reads inputs through ranged access and through manifests", () => {
+        const value = dict(Array.from({ length: 3_000 }, (_, i) => [`k${String(i).padStart(6, "0")}`, `v${i}`]));
+        const entries = [...value];
+        const batches = [];
+        for (let i = 0; i < entries.length; i += 400)
+            batches.push(dict(entries.slice(i, i + 400)));
+        const blob = encodeBeast2SegmentsFor(DictSS)(batches);
+        const extents = readBeast2Extents(blob);
+        const pages = openBeast2PagesFor(DictSS)(blob);
+        const fence = encodeBeast2FenceFor(StringType);
+        const segments = extents.offsets.map((_, i) => carveBeast2(blob, i, i + 1, extents));
+        const manifest = {
+            manifest: {
+                kind: COLLECTION_MANIFEST_KIND,
+                level: 0n,
+                type: toEastTypeValue(DictSS),
+                rule: segmentRuleFor(DictSS),
+                header: "",
+                entries: segments.map((segment, i) => ({ hash: `${i}`, fence: fence(pages.fence(i)), count: BigInt(extents.counts[i]), bytes: BigInt(segment.length) })),
+            },
+            segment: (i) => segments[i],
+        };
+        const reader = { size: blob.length, read: (offset, length) => blob.subarray(offset, offset + length) };
+        const expected = encodeBeast2PagedFor(DictSS)(value);
+        assert.deepEqual(mergeInto(DictSS, [reader]).blob, expected);
+        assert.deepEqual(mergeInto(DictSS, [manifest]).blob, expected);
+        assert.deepEqual(mergeInto(DictSS, [manifest], { from: "k001234", to: "k002345" }).blob, encodeBeast2PagedFor(DictSS)(dict(entries.filter(([k]) => k >= "k001234" && k < "k002345"))));
+    });
+    test("names the input a refusal is about", () => {
+        const good = encodeBeast2PagedFor(DictSS)(dict([["a", "1"]]));
+        const otherType = encodeBeast2PagedFor(DictSI)(dict([["a", 1n]]));
+        assert.throws(() => mergeInto(DictSS, [good, otherType], { labels: ["a.beast2", "b.beast2"] }), (err) => err.message.startsWith("merge: input 1 (b.beast2) has type ") && err.message.includes(", expected "));
+        // An input without an index cannot be read by segment.
+        const whole = encodeBeast2For(DictSS)(dict([["a", "1"]]));
+        assert.throws(() => mergeInto(DictSS, [whole]), { message: "merge: input 0: beast2 v5: blob carries no index — carve/splice need one (write with the index enabled, the default)" });
+    });
+    test("refuses no inputs, a root it cannot merge, and a fold that does not fit the root", () => {
+        assert.throws(() => mergeInto(DictSS, []), { message: "merge: at least one input is needed" });
+        assert.throws(() => mergeBeast2For(ArrayType(IntegerType)), { message: "merge: inputs must be Set or Dict blobs, got Array" });
+        assert.throws(() => mergeBeast2For(SetType(IntegerType), { merge: (_k, a) => a }), /folds a Dict/);
+        assert.throws(() => mergeBeast2For(DictSS, { union: true }), /collapses a Set/);
+    });
+});
+//# sourceMappingURL=merge.spec.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"merge.spec.js","sourceRoot":"","sources":["../../../../../src/serialization/beast2/v5/merge.spec.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;GAKG;AAEH,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,MAAM,MAAM,oBAAoB,CAAC;AACxC,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,WAAW,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC1F,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EACL,wBAAwB,EAIxB,WAAW,EACX,eAAe,EACf,oBAAoB,EACpB,eAAe,EACf,oBAAoB,EACpB,uBAAuB,EACvB,cAAc,EACd,kBAAkB,EAClB,iBAAiB,EACjB,cAAc,GACf,MAAM,aAAa,CAAC;AAErB,MAAM,MAAM,GAAG,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;AAChD,MAAM,MAAM,GAAG,QAAQ,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC;AAEjD,+CAA+C;AAC/C,MAAM,IAAI,GAAG,CAAI,OAAsB,EAAwB,EAAE,CAAC,IAAI,SAAS,CAAC,OAAO,EAAE,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC;AAEjH,+EAA+E;AAC/E,SAAS,SAAS,CAAC,IAA0C,EAAE,OAAqC,EAAE,OAA4B;IAChI,MAAM,MAAM,GAAiB,EAAE,CAAC;IAChC,MAAM,KAAK,GAAG,cAAc,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IACpF,OAAO,EAAE,IAAI,EAAE,IAAI,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC;AAChE,CAAC;AAED,QAAQ,CAAC,uCAAuC,EAAE,GAAG,EAAE;IACrD,MAAM,MAAM,GAAG,EAAE,KAAK,EAAE,CAAC,IAAY,EAAE,GAAW,EAAE,KAAa,EAAE,EAAE,CAAC,GAAG,GAAG,KAAK,EAAE,CAAC;IAEpF,IAAI,CAAC,iDAAiD,EAAE,GAAG,EAAE;QAC3D,MAAM,MAAM,GAAG;YACb,oBAAoB,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC;YAC5D,oBAAoB,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC;YAChD,oBAAoB,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC;SAC7D,CAAC;QACF,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;QAC1D,MAAM,CAAC,SAAS,CAAC,CAAC,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC;QAC7F,MAAM,CAAC,SAAS,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC;IAC/D,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,8EAA8E,EAAE,GAAG,EAAE;QACxF,2EAA2E;QAC3E,6CAA6C;QAC7C,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC,CAAC,CAAqB,CAAC,CAAC,CAAC;QACnI,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAqB,CAAC,CAAC,CAAC;QACvI,MAAM,YAAY,GAAG,CAAC,KAAgC,EAAE,IAAY,EAAc,EAAE;YAClF,MAAM,OAAO,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC;YAC3B,MAAM,OAAO,GAAgC,EAAE,CAAC;YAChD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,IAAI,IAAI;gBAAE,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;YAC9F,OAAO,uBAAuB,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,CAAC;QAClD,CAAC,CAAC;QACF,MAAM,EAAE,IAAI,EAAE,GAAG,SAAS,CAAC,MAAM,EAAE,CAAC,YAAY,CAAC,KAAK,EAAE,GAAG,CAAC,EAAE,YAAY,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;QAC1F,MAAM,CAAC,SAAS,CAAC,IAAI,EAAE,oBAAoB,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,KAAK,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IAClF,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,iCAAiC,EAAE,GAAG,EAAE;QAC3C,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC,CAAC,CAAqB,CAAC,CAAC,CAAC;QAC/H,MAAM,IAAI,GAAG,oBAAoB,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC;QACjD,MAAM,OAAO,GAAG,CAAC,IAAwB,EAAE,EAAsB,EAA6B,EAAE,CAC9F,IAAI,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,KAAK,SAAS,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,EAAE,KAAK,SAAS,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC;QACtG,KAAK,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,SAAS,CAAC,EAAE,CAAC,SAAS,EAAE,SAAS,CAAC,EAAE,CAAC,SAAS,EAAE,SAAS,CAAC,EAAE,CAAC,SAAS,EAAE,SAAS,CAAC,CAAU,EAAE,CAAC;YACnI,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;YACjE,MAAM,CAAC,SAAS,CAAC,MAAM,EAAE,oBAAoB,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,IAAI,KAAK,EAAE,GAAG,CAAC,CAAC;QAChG,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,+CAA+C,EAAE,GAAG,EAAE;QACzD,MAAM,IAAI,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;QAClC,MAAM,GAAG,GAAG,CAAC,EAAY,EAAqB,EAAE,CAAC,IAAI,SAAS,CAAC,EAAE,EAAE,UAAU,CAAC,WAAW,CAAC,CAAC,CAAC;QAC5F,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,SAAS,CAAC,IAAI,EAAE,CAAC,oBAAoB,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,oBAAoB,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACjJ,MAAM,CAAC,SAAS,CAAC,CAAC,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;QACjE,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IAC/B,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,kEAAkE,EAAE,GAAG,EAAE;QAC5E,MAAM,MAAM,GAAG,CAAC,oBAAoB,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,oBAAoB,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACpH,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,EAAE,OAAO,EAAE,uEAAuE,EAAE,CAAC,CAAC;IACvI,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,0DAA0D,EAAE,GAAG,EAAE;QACpE,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,EAAE,IAAI,CAAC,EAAE,CAAqB,CAAC,CAAC,CAAC;QAC7H,MAAM,OAAO,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC;QAC3B,MAAM,OAAO,GAAgC,EAAE,CAAC;QAChD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,IAAI,GAAG;YAAE,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;QAC5F,MAAM,IAAI,GAAG,uBAAuB,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,CAAC;QACtD,MAAM,OAAO,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC;QACxC,MAAM,KAAK,GAAG,kBAAkB,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC;QAC/C,MAAM,KAAK,GAAG,oBAAoB,CAAC,UAAU,CAAC,CAAC;QAC/C,MAAM,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;QACrF,MAAM,QAAQ,GAAyB;YACrC,QAAQ,EAAE;gBACR,IAAI,EAAE,wBAAwB;gBAC9B,KAAK,EAAE,EAAE;gBACT,IAAI,EAAE,eAAe,CAAC,MAAM,CAAC;gBAC7B,IAAI,EAAE,cAAc,CAAC,MAAM,CAAC;gBAC5B,MAAM,EAAE,EAAE;gBACV,OAAO,EAAE,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,EAAE,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAE,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;aAC1J;YACD,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAE;SAC7B,CAAC;QACF,MAAM,MAAM,GAAG,EAAE,IAAI,EAAE,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,MAAc,EAAE,MAAc,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;QACvH,MAAM,QAAQ,GAAG,oBAAoB,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC;QACrD,MAAM,CAAC,SAAS,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QAC7D,MAAM,CAAC,SAAS,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QAC/D,MAAM,CAAC,SAAS,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC,IAAI,EACrF,oBAAoB,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,SAAS,IAAI,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;IAClG,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,oCAAoC,EAAE,GAAG,EAAE;QAC9C,MAAM,IAAI,GAAG,oBAAoB,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QAC9D,MAAM,SAAS,GAAG,oBAAoB,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;QAClE,MAAM,CAAC,MAAM,CACX,GAAG,EAAE,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,CAAC,UAAU,EAAE,UAAU,CAAC,EAAE,CAAC,EAChF,CAAC,GAAU,EAAE,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,UAAU,CAAC,qCAAqC,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,CACrH,CAAC;QACF,uDAAuD;QACvD,MAAM,KAAK,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QAC1D,MAAM,CAAC,MAAM,CACX,GAAG,EAAE,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,CAAC,EAChC,EAAE,OAAO,EAAE,sHAAsH,EAAE,CACpI,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,kFAAkF,EAAE,GAAG,EAAE;QAC5F,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,MAAM,EAAE,EAAE,CAAC,EAAE,EAAE,OAAO,EAAE,qCAAqC,EAAE,CAAC,CAAC;QAC/F,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,cAAc,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC,EAAE,EAAE,OAAO,EAAE,oDAAoD,EAAE,CAAC,CAAC;QAC/H,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,cAAc,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,cAAc,CAAC,CAAC;QACnG,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,cAAc,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,EAAE,iBAAiB,CAAC,CAAC;IAClF,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/src/serialization/beast2/v5/recut.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * Re-cutting — a collection's pieces in, in order, and the canonical whole out,
+ * segment by segment.
+ *
+ * The cut rule decides where a segment starts from the elements since the last
+ * boundary and nothing else. So a piece the Writer wrote — a partition's
+ * output, the segments of a record around an edit — cuts where the whole cuts
+ * from the first boundary the two share: once the whole starts a segment where
+ * the piece started one, every later segment of the piece is a segment of the
+ * whole, byte for byte, and is carried over without being read. Only where the
+ * two can disagree is anything re-cut: at a seam, where a piece's last segment
+ * ended only because the piece did, and through elements given one by one — an
+ * edited region — until the whole starts a segment where a piece does again.
+ *
+ * What comes out is what the Writer writes for the whole value, segment for
+ * segment; nothing in it records where the pieces were cut.
+ */
+import { type EastTypeValue } from "../../../type_of_type.js";
+import type { EastType } from "../../../types.js";
+import { type Beast2ElementOf, type Beast2ElementWriterOptions, type Beast2Segment } from "./stream.js";
+/**
+ * A segment of a collection the Writer wrote, as {@link recutBeast2For} takes
+ * it: what a manifest entry records of it, and a way to read it.
+ *
+ * A re-cut reads a segment only where it has to look inside — at a seam, or to
+ * re-cut through it — so a segment it carries over is never read at all.
+ */
+export interface Beast2SegmentRef {
+    /** Elements (pairs, for a Dict) in the segment; at least one. */
+    readonly count: number;
+    /** Set/Dict: the segment's first key in its canonical bare encoding
+     *  (`encodeBeast2FenceFor`) — a manifest entry's fence. Array: empty, and
+     *  the first element is read when a seam needs it. */
+    readonly fence: Uint8Array;
+    /** The segment's logical size, when the caller knows it; otherwise it is
+     *  read from the segment's frame when a seam after it needs it. */
+    readonly logicalBytes?: number;
+    /** Set/Dict: the fence of the segment that followed this one in the
+     *  collection it was written in. The rule started a segment at that key
+     *  after this one, so a seam where the same key follows again is decided
+     *  without reading anything. */
+    readonly nextFence?: Uint8Array;
+    /**
+     * Reads the segment.
+     *
+     * @returns the segment as a standalone blob holding exactly it
+     */
+    read(): Uint8Array | Promise<Uint8Array>;
+}
+/**
+ * A piece of a collection, as {@link recutBeast2For} takes it: a run of
+ * consecutive segments of a collection the Writer wrote, under the header the
+ * re-cut writes, or elements.
+ */
+export type Beast2RecutPiece<T extends EastType = EastType, R extends Beast2SegmentRef = Beast2SegmentRef> = {
+    readonly segments: Iterable<R> | AsyncIterable<R>;
+} | {
+    readonly elements: Iterable<Beast2ElementOf<T>> | AsyncIterable<Beast2ElementOf<T>>;
+};
+/** Where {@link recutBeast2For} puts the whole's segments, in order. */
+export interface Beast2RecutSink<R extends Beast2SegmentRef = Beast2SegmentRef> {
+    /**
+     * Receives a segment the re-cut wrote.
+     *
+     * @param segment - the segment, as a standalone blob
+     */
+    written(segment: Beast2Segment): void | Promise<void>;
+    /**
+     * Receives a segment of a piece that is a segment of the whole as it
+     * stands, never read.
+     *
+     * @param segment - the reference it came as
+     */
+    carried(segment: R): void | Promise<void>;
+}
+/** Options accepted by {@link recutBeast2For}: those of the Writer the
+ *  written segments go through. `headerPrefix` is the header the carried
+ *  segments are under, when that is not the one the Writer builds for the
+ *  type. */
+export type Beast2RecutOptions = Beast2ElementWriterOptions;
+/** What a re-cut came to. */
+export type Beast2RecutStats = {
+    /** The header every segment of the whole is under — what a manifest of it
+     *  names. */
+    header: Uint8Array;
+    /** Segments carried over from the pieces. */
+    carried: number;
+    /** Segments written. */
+    written: number;
+};
+/**
+ * Builds a re-cut: `recut(pieces, sink)` writes the canonical whole of a
+ * collection given as pieces in order, segment by segment.
+ *
+ * A piece is either a run of consecutive segments of a collection the Writer
+ * wrote — given by reference, and read only where the re-cut must look inside
+ * one — or elements. A segment of a piece that is a segment of the whole is
+ * carried over as it came; everything else is written, cut by the rule. The
+ * segments are exactly those the Writer writes for the whole value, so an edit
+ * is a re-cut of the edited elements between the segments around them, and
+ * costs what the edit touched plus at most a segment or two each side.
+ *
+ * @param type - the collection type (Array/Set/Dict)
+ * @param options - the Writer's options for the written segments; its
+ *   `headerPrefix` is the header the carried segments are under
+ * @returns a function taking the pieces, in order, and the sink the whole's
+ *   segments go to, and resolving to what the re-cut came to
+ * @throws {TypeError} When `type` is not an Array, Set or Dict type.
+ *
+ * @remarks
+ * The pieces' segments must be the Writer's own — cut by the current rule,
+ * with aliasing scoped per element and the same codec — or they are carried
+ * over as something the Writer would not write; a collection stored some other
+ * way is given as its elements. Elements in one piece must ascend in East
+ * order (a Set's elements, a Dict's keys), which the re-cut checks; the order
+ * across pieces is the caller's. The returned function rejects, having written
+ * part of the whole, when a piece is out of order, a segment's blob is not the
+ * one segment its reference describes, or the sink rejects.
+ *
+ * @example
+ * ```ts
+ * const type = ArrayType(IntegerType);
+ * const blob = encodeBeast2PagedFor(type)(values);
+ * const extents = readBeast2Extents(blob);
+ * const segments = extents.counts.map((count, i) => ({
+ *   count,
+ *   fence: new Uint8Array(0),
+ *   read: () => carveBeast2(blob, i, i + 1, extents),
+ * }));
+ * const parts: Uint8Array[] = [];
+ * await recutBeast2For(type)([{ segments }, { elements: [42n] }], {
+ *   written: (segment) => { parts.push(segment.blob); },
+ *   carried: (segment) => { parts.push(segment.read() as Uint8Array); },
+ * });
+ * spliceBeast2(parts);  // encodeBeast2PagedFor(type)([...values, 42n])
+ * ```
+ */
+export declare function recutBeast2For<T extends EastType, R extends Beast2SegmentRef = Beast2SegmentRef>(type: T | EastTypeValue, options?: Beast2RecutOptions): (pieces: Iterable<Beast2RecutPiece<T, R>> | AsyncIterable<Beast2RecutPiece<T, R>>, sink: Beast2RecutSink<R>) => Promise<Beast2RecutStats>;
+//# sourceMappingURL=recut.d.ts.map

package/dist/src/serialization/beast2/v5/recut.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recut.d.ts","sourceRoot":"","sources":["../../../../../src/serialization/beast2/v5/recut.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,KAAK,aAAa,EAAuC,MAAM,0BAA0B,CAAC;AACnG,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAUlD,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,0BAA0B,EAC/B,KAAK,aAAa,EACnB,MAAM,aAAa,CAAC;AAErB;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,iEAAiE;IACjE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;0DAEsD;IACtD,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B;uEACmE;IACnE,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;;;oCAGgC;IAChC,QAAQ,CAAC,SAAS,CAAC,EAAE,UAAU,CAAC;IAChC;;;;OAIG;IACH,IAAI,IAAI,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CAC1C;AAED;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,SAAS,QAAQ,GAAG,QAAQ,EAAE,CAAC,SAAS,gBAAgB,GAAG,gBAAgB,IACrG;IAAE,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAAA;CAAE,GACrD;IAAE,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAAA;CAAE,CAAC;AAE5F,wEAAwE;AACxE,MAAM,WAAW,eAAe,CAAC,CAAC,SAAS,gBAAgB,GAAG,gBAAgB;IAC5E;;;;OAIG;IACH,OAAO,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD;;;;;OAKG;IACH,OAAO,CAAC,OAAO,EAAE,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3C;AAED;;;YAGY;AACZ,MAAM,MAAM,kBAAkB,GAAG,0BAA0B,CAAC;AAE5D,6BAA6B;AAC7B,MAAM,MAAM,gBAAgB,GAAG;IAC7B;iBACa;IACb,MAAM,EAAE,UAAU,CAAC;IACnB,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,wBAAwB;IACxB,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AA4PF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,gBAAgB,GAAG,gBAAgB,EAC9F,IAAI,EAAE,CAAC,GAAG,aAAa,EACvB,OAAO,CAAC,EAAE,kBAAkB,GAC3B,CAAC,MAAM,EAAE,QAAQ,CAAC,gBAAgB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,gBAAgB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,eAAe,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,gBAAgB,CAAC,CAwC3I"}

package/dist/src/serialization/beast2/v5/recut.js

@@ -0,0 +1,365 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * Re-cutting — a collection's pieces in, in order, and the canonical whole out,
+ * segment by segment.
+ *
+ * The cut rule decides where a segment starts from the elements since the last
+ * boundary and nothing else. So a piece the Writer wrote — a partition's
+ * output, the segments of a record around an edit — cuts where the whole cuts
+ * from the first boundary the two share: once the whole starts a segment where
+ * the piece started one, every later segment of the piece is a segment of the
+ * whole, byte for byte, and is carried over without being read. Only where the
+ * two can disagree is anything re-cut: at a seam, where a piece's last segment
+ * ended only because the piece did, and through elements given one by one — an
+ * edited region — until the whole starts a segment where a piece does again.
+ *
+ * What comes out is what the Writer writes for the whole value, segment for
+ * segment; nothing in it records where the pieces were cut.
+ */
+import { EastTypeValueType, isTypeValueEqual } from "../../../type_of_type.js";
+import { printFor } from "../../east.js";
+import { compareFor } from "../../../comparison.js";
+import { BufferReader, BufferWriter } from "../../binary-utils.js";
+import { buildPlatformContext } from "../shared.js";
+import { asTypeValue, readTypeSection } from "./type-section.js";
+import { MAGIC_BYTES_V5, buildV5Decoder, isSegmentedRoot, readSourceMapSectionV5 } from "./codec.js";
+import { FrameReader } from "./frames.js";
+import { readBeast2Extents } from "./geometry.js";
+import { startsSegmentAfter } from "./boundary.js";
+import { Beast2ElementWriter, elementEncoderFor, } from "./stream.js";
+function elementParserFor(typeValue) {
+    const typeCtx = new Map();
+    if (typeValue.type === "Dict") {
+        const key = buildV5Decoder(typeValue.value.key, typeCtx);
+        const value = buildV5Decoder(typeValue.value.value, typeCtx);
+        return (reader, ctx) => {
+            const start = reader.offset;
+            key(reader, ctx);
+            const keyLength = reader.offset - start;
+            value(reader, ctx);
+            return keyLength;
+        };
+    }
+    const elem = buildV5Decoder(typeValue.value, typeCtx);
+    const keyed = typeValue.type === "Set";
+    return (reader, ctx) => {
+        const start = reader.offset;
+        elem(reader, ctx);
+        return keyed ? reader.offset - start : 0;
+    };
+}
+/** A segment read for a re-cut: its frame's logical bytes, and where its
+ *  elements lie in them. */
+class SegmentContent {
+    logical;
+    start;
+    count;
+    parse;
+    context;
+    constructor(
+    /** The frame's logical bytes: the element count, then the elements. */
+    logical, 
+    /** Where the first element starts. */
+    start, count, parse, 
+    /** A decode context with an empty definition table. */
+    context) {
+        this.logical = logical;
+        this.start = start;
+        this.count = count;
+        this.parse = parse;
+        this.context = context;
+    }
+    /** The elements' canonical bytes before compression — what the cut rule
+     *  measures a segment by. */
+    get logicalBytes() {
+        return this.logical.length - this.start;
+    }
+    /**
+     * Each element's bytes and the length of its key, in order.
+     *
+     * Every element decodes against an empty definition table, so one that
+     * refers to a container outside itself — a segment written before aliasing
+     * was scoped per element — fails here, rather than being moved by byte copy
+     * away from what it refers to.
+     */
+    *elements() {
+        const reader = new BufferReader(this.logical, this.start);
+        for (let i = 0; i < this.count; i++) {
+            const start = reader.offset;
+            const keyLength = this.parse(reader, this.context());
+            yield [this.logical.subarray(start, reader.offset), keyLength];
+        }
+        if (reader.offset !== this.logical.length) {
+            throw new Error(`beast2 v5: ${this.logical.length - reader.offset} logical bytes after a segment's last element`);
+        }
+    }
+}
+/** One re-cut in progress. */
+class Recutter {
+    typeValue;
+    parse;
+    sink;
+    carried = 0;
+    written = 0;
+    keyed;
+    writer;
+    encodeElement;
+    platform = buildPlatformContext();
+    /** Segments the writer has written that the sink has not been given yet. */
+    queue = [];
+    /** A segment that starts where the whole starts one, held until what
+     *  follows says whether the whole ends one where it ends: then it is carried
+     *  over whole, and otherwise its elements join what follows. The writer's
+     *  open segment is empty while one is held. */
+    pending = null;
+    /** What has been read of the segments in hand, so each is read once. */
+    contents = new Map();
+    scratch = new BufferWriter();
+    constructor(typeValue, parse, sink, options) {
+        this.typeValue = typeValue;
+        this.parse = parse;
+        this.sink = sink;
+        this.keyed = typeValue.type !== "Array";
+        this.writer = new Beast2ElementWriter(typeValue, { segment: (segment) => { this.queue.push(segment); } }, options);
+        this.encodeElement = elementEncoderFor(typeValue, options?.sourceMap ?? null);
+    }
+    /**
+     * Takes the next segment of a piece.
+     *
+     * @param ref - the segment
+     * @param continues - whether the segment before it came from the same piece,
+     *   whose writer cut between them
+     */
+    async segment(ref, continues) {
+        if (!Number.isInteger(ref.count) || ref.count < 1) {
+            throw new Error(`beast2 v5: recut: a segment holds at least one element, and a reference says ${ref.count}`);
+        }
+        const pending = this.pending;
+        if (pending !== null) {
+            // The whole started `pending` where its piece did, so it cuts after it
+            // wherever the piece did.
+            if (continues || await this.cutsAfter(pending, await this.hashInputOf(ref))) {
+                await this.carry(pending);
+                this.pending = ref;
+                return;
+            }
+            this.pending = null;
+            await this.dissolve(pending);
+            await this.dissolve(ref);
+            return;
+        }
+        if (this.writer.openCount === 0) {
+            // The whole's first element opens its first segment.
+            this.pending = ref;
+            return;
+        }
+        if (startsSegmentAfter(this.writer.openCount, this.writer.openBytes, await this.hashInputOf(ref))) {
+            this.writer.closeSegment();
+            await this.drain();
+            this.pending = ref;
+            return;
+        }
+        await this.dissolve(ref);
+    }
+    /**
+     * Takes the next element.
+     *
+     * @param element - an Array or Set element, or a Dict's `[key, value]` pair
+     */
+    async element(element) {
+        // An encode that threw left its bytes behind; this one starts clean.
+        this.scratch.pop();
+        const keyLength = this.encodeElement(element, this.scratch);
+        const bytes = this.scratch.toUint8Array();
+        const pending = this.pending;
+        if (pending !== null) {
+            this.pending = null;
+            if (await this.cutsAfter(pending, this.keyed ? bytes.subarray(0, keyLength) : bytes))
+                await this.carry(pending);
+            else
+                await this.dissolve(pending);
+        }
+        this.writer.addEncoded(bytes, keyLength);
+        if (this.queue.length > 0)
+            await this.drain();
+    }
+    /**
+     * Writes what is left and hands the last segments to the sink.
+     *
+     * @returns what the re-cut came to
+     */
+    async finish() {
+        const pending = this.pending;
+        this.pending = null;
+        // The whole's last segment holds whatever is left, so a held segment ends
+        // one wherever it ends.
+        if (pending !== null)
+            await this.carry(pending);
+        this.writer.finish();
+        await this.drain();
+        return { header: this.writer.header, carried: this.carried, written: this.written };
+    }
+    /** Whether the cut rule starts a segment after `held` at an element whose
+     *  hash input is `hashInput`. */
+    async cutsAfter(held, hashInput) {
+        const next = held.nextFence;
+        if (this.keyed && next !== undefined && next.length === hashInput.length && next.every((byte, i) => byte === hashInput[i])) {
+            return true;
+        }
+        return startsSegmentAfter(held.count, held.logicalBytes ?? (await this.content(held)).logicalBytes, hashInput);
+    }
+    /** The bytes the cut rule hashes for a segment's first element: its fence
+     *  for a Set or Dict, the element itself for an Array. */
+    async hashInputOf(ref) {
+        if (this.keyed)
+            return ref.fence;
+        const first = (await this.content(ref)).elements().next();
+        return first.value[0];
+    }
+    /** Hands a segment to the sink as it stands, after every segment written
+     *  before it. */
+    async carry(ref) {
+        this.writer.settle();
+        await this.drain();
+        this.contents.delete(ref);
+        this.carried++;
+        await this.sink.carried(ref);
+    }
+    /** Gives a segment's elements to the writer one by one: the whole does not
+     *  start a segment where it starts, so the writer cuts them. */
+    async dissolve(ref) {
+        const content = await this.content(ref);
+        this.contents.delete(ref);
+        for (const [bytes, keyLength] of content.elements()) {
+            this.writer.addEncoded(bytes, keyLength);
+            if (this.queue.length > 0)
+                await this.drain();
+        }
+    }
+    async drain() {
+        while (this.queue.length > 0) {
+            this.written++;
+            await this.sink.written(this.queue.shift());
+        }
+    }
+    /** Reads a segment once: its standalone blob, checked to hold exactly the
+     *  one segment its reference describes, of this collection's type. */
+    async content(ref) {
+        const held = this.contents.get(ref);
+        if (held !== undefined)
+            return held;
+        const blob = await ref.read();
+        const extents = readBeast2Extents(blob);
+        if (!isTypeValueEqual(extents.typeValue, this.typeValue)) {
+            const printType = printFor(EastTypeValueType);
+            throw new Error(`beast2 v5: recut: a segment holds ${printType(extents.typeValue)}, not ${printType(this.typeValue)}`);
+        }
+        if (extents.offsets.length !== 1 || extents.counts[0] !== ref.count) {
+            const holds = extents.offsets.length === 1 ? `${extents.counts[0]} elements` : `${extents.offsets.length} segments`;
+            throw new Error(`beast2 v5: recut: a segment's reference says ${ref.count} elements, and its blob holds ${holds}`);
+        }
+        const head = new BufferReader(blob, MAGIC_BYTES_V5.length);
+        readTypeSection(head);
+        const sourceMap = readSourceMapSectionV5(head);
+        const reader = new FrameReader(blob, extents.offsets[0]).next();
+        const count = reader.readVarint();
+        if (count !== ref.count) {
+            throw new Error(`beast2 v5: recut: a segment's frame declares ${count} elements, its index ${ref.count}`);
+        }
+        const platform = this.platform;
+        const content = new SegmentContent(reader.buffer, reader.offset, count, this.parse, () => ({ containers: [], sourceMap, frozen: false, ...platform }));
+        this.contents.set(ref, content);
+        return content;
+    }
+}
+/**
+ * Builds a re-cut: `recut(pieces, sink)` writes the canonical whole of a
+ * collection given as pieces in order, segment by segment.
+ *
+ * A piece is either a run of consecutive segments of a collection the Writer
+ * wrote — given by reference, and read only where the re-cut must look inside
+ * one — or elements. A segment of a piece that is a segment of the whole is
+ * carried over as it came; everything else is written, cut by the rule. The
+ * segments are exactly those the Writer writes for the whole value, so an edit
+ * is a re-cut of the edited elements between the segments around them, and
+ * costs what the edit touched plus at most a segment or two each side.
+ *
+ * @param type - the collection type (Array/Set/Dict)
+ * @param options - the Writer's options for the written segments; its
+ *   `headerPrefix` is the header the carried segments are under
+ * @returns a function taking the pieces, in order, and the sink the whole's
+ *   segments go to, and resolving to what the re-cut came to
+ * @throws {TypeError} When `type` is not an Array, Set or Dict type.
+ *
+ * @remarks
+ * The pieces' segments must be the Writer's own — cut by the current rule,
+ * with aliasing scoped per element and the same codec — or they are carried
+ * over as something the Writer would not write; a collection stored some other
+ * way is given as its elements. Elements in one piece must ascend in East
+ * order (a Set's elements, a Dict's keys), which the re-cut checks; the order
+ * across pieces is the caller's. The returned function rejects, having written
+ * part of the whole, when a piece is out of order, a segment's blob is not the
+ * one segment its reference describes, or the sink rejects.
+ *
+ * @example
+ * ```ts
+ * const type = ArrayType(IntegerType);
+ * const blob = encodeBeast2PagedFor(type)(values);
+ * const extents = readBeast2Extents(blob);
+ * const segments = extents.counts.map((count, i) => ({
+ *   count,
+ *   fence: new Uint8Array(0),
+ *   read: () => carveBeast2(blob, i, i + 1, extents),
+ * }));
+ * const parts: Uint8Array[] = [];
+ * await recutBeast2For(type)([{ segments }, { elements: [42n] }], {
+ *   written: (segment) => { parts.push(segment.blob); },
+ *   carried: (segment) => { parts.push(segment.read() as Uint8Array); },
+ * });
+ * spliceBeast2(parts);  // encodeBeast2PagedFor(type)([...values, 42n])
+ * ```
+ */
+export function recutBeast2For(type, options) {
+    const typeValue = asTypeValue(type);
+    if (!isSegmentedRoot(typeValue)) {
+        throw new TypeError(`beast2 v5: recut addresses Array, Set or Dict values, not ${typeValue.type}`);
+    }
+    const parse = elementParserFor(typeValue);
+    const dict = typeValue.type === "Dict";
+    const keyType = typeValue.type === "Array" ? null
+        : dict ? typeValue.value.key : typeValue.value;
+    const cmp = keyType === null ? null : compareFor(keyType);
+    const printKey = keyType === null ? null : printFor(keyType);
+    return async (pieces, sink) => {
+        const recut = new Recutter(typeValue, parse, sink, options);
+        for await (const piece of pieces) {
+            if ("segments" in piece) {
+                let continues = false;
+                for await (const segment of piece.segments) {
+                    await recut.segment(segment, continues);
+                    continues = true;
+                }
+                continue;
+            }
+            let prev;
+            let has = false;
+            for await (const element of piece.elements) {
+                if (cmp !== null) {
+                    const key = dict ? element[0] : element;
+                    if (has && cmp(prev, key) >= 0) {
+                        const noun = dict ? "Dict keys" : "Set elements";
+                        throw new Error(`beast2 v5: recut: a piece's ${noun} must ascend strictly in East order, and ${printKey(key)} follows ${printKey(prev)}`);
+                    }
+                    prev = key;
+                    has = true;
+                }
+                await recut.element(element);
+            }
+        }
+        return recut.finish();
+    };
+}
+//# sourceMappingURL=recut.js.map