@elaraai/east 1.0.44 → 1.0.46

package/dist/src/serialization/beast2/v4/container.js

@@ -0,0 +1,727 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * Beast2 v4 container codec — the globally-sectioned format.
+ *
+ * File layout: magic(8) + type_table_section + string_table_section +
+ * source_map_section + value_table_section + value_stream.
+ * Type table: flat array of unique types, referenced by varint index.
+ * String table: flat array of unique strings, referenced by varint index.
+ * Value stream: type-driven positional encoding, no inline type tags.
+ * Functions: IR encoded directly — EastTypeType values are regular variants.
+ *
+ * See v4/SPEC.md for the wire specification. Version-agnostic entry points
+ * (magic dispatch across v4/v5) live in `../index.ts`.
+ */
+import { toEastTypeValue } from "../../../type_of_type.js";
+import { isVariant, variant } from "../../../containers/variant.js";
+import { BufferWriter, BufferReader } from "../../binary-utils.js";
+import { ref } from "../../../containers/ref.js";
+import { SortedSet } from "../../../containers/sortedset.js";
+import { SortedMap } from "../../../containers/sortedmap.js";
+import { compareFor } from "../../../comparison.js";
+import { matrix } from "../../../containers/matrix.js";
+import { EAST_IR_SYMBOL, EAST_CAPTURES_SYMBOL, EAST_SOURCE_MAP_SYMBOL } from "../../../compile.js";
+import { InternalError } from "../../../error.js";
+import { TypeTableBuilder, writeTypeTableSection, readTypeTableSection } from "./type-table.js";
+import { writeStringTableSection, readStringTableSection } from "./string-table.js";
+import { writeSourceMapSection, readSourceMapSection } from "./sourcemap-table.js";
+import { buildValueTable, buildIndexMap, isMutableType, TAG_ARRAY, TAG_DICT, TAG_SET, TAG_REF } from "./value-table.js";
+import { buildPlatformContext, describeNoIrValue, finishDecodedFunction, irTypeValue } from "../shared.js";
+// v4: EastTypeType values are encoded as regular variants (no special type-table-index encoding).
+// This ensures uniform encoding across value stream and value table, and simplifies multi-runtime implementations.
+// =============================================================================
+// Magic bytes (v4: last byte = 0x04)
+// =============================================================================
+export const MAGIC_BYTES = new Uint8Array([0x89, 0x45, 0x61, 0x73, 0x74, 0x0D, 0x0A, 0x04]);
+function verifyMagic(data) {
+    if (data.length < 8) {
+        throw new Error(`Data too short for Beast2 format: ${data.length} bytes`);
+    }
+    for (let i = 0; i < 8; i++) {
+        if (data[i] !== MAGIC_BYTES[i]) {
+            if (i < 7)
+                throw new Error(`Invalid Beast2 magic at offset ${i}: expected 0x${MAGIC_BYTES[i].toString(16)}, got 0x${data[i].toString(16)}`);
+            throw new Error(`Unknown Beast2 version: 0x${data[i].toString(16)}`);
+        }
+    }
+}
+// =============================================================================
+// Value encoder factory
+// =============================================================================
+/**
+ * Build a value encoder closure tree for the given type.
+ * The tree is built once and reused for every encode call.
+ */
+function buildEncoder(type, typeCtx = new Map()) {
+    switch (type.type) {
+        case "Never":
+            return () => { throw new Error("Cannot encode value of type Never"); };
+        case "Null":
+            return () => { };
+        case "Boolean":
+            return (value, writer) => writer.writeUint8(value ? 1 : 0);
+        case "Integer":
+            return (value, writer) => writer.writeZigzag(value);
+        case "Float":
+            return (value, writer) => writer.writeFloat64LE(value);
+        case "String":
+            return (value, writer, ctx) => {
+                let idx = ctx.stringTable.get(value);
+                if (idx === undefined) {
+                    idx = ctx.stringTable.size;
+                    ctx.stringTable.set(value, idx);
+                }
+                writer.writeVarint(idx);
+            };
+        case "DateTime":
+            return (value, writer) => writer.writeZigzag(BigInt(value.valueOf()));
+        case "Blob":
+            return (value, writer) => {
+                writer.writeVarint(value.length);
+                writer.writeBytes(value);
+            };
+        case "Ref":
+        case "Array":
+        case "Set":
+        case "Dict": {
+            // v4: all mutable containers are in the value table, encoded as varint(index)
+            return (value, writer, ctx) => {
+                const idx = ctx.indexMap.get(value);
+                if (idx === undefined)
+                    throw new InternalError(`Mutable ${type.type} not found in value table during encode`);
+                writer.writeVarint(idx);
+            };
+        }
+        case "Struct": {
+            const fieldEncoders = [];
+            const ret = (value, writer, ctx) => {
+                for (const [name, enc] of fieldEncoders)
+                    enc(value[name], writer, ctx);
+            };
+            for (const { name, type: fieldType } of type.value) {
+                fieldEncoders.push([name, buildEncoder(fieldType, typeCtx)]);
+            }
+            return ret;
+        }
+        case "Variant": {
+            const caseEncoders = {};
+            const caseTags = {};
+            const ret = (value, writer, ctx) => {
+                writer.writeVarint(caseTags[value.type]);
+                caseEncoders[value.type](value.value, writer, ctx);
+            };
+            for (let i = 0; i < type.value.length; i++) {
+                const { name, type: caseType } = type.value[i];
+                caseTags[name] = i;
+                caseEncoders[name] = buildEncoder(caseType, typeCtx);
+            }
+            return ret;
+        }
+        case "Recursive": {
+            if (type.value.type === "wrapper") {
+                let inner;
+                const ret = (value, writer, ctx) => inner(value, writer, ctx);
+                typeCtx.set(type.value.value.id, ret);
+                inner = buildEncoder(type.value.value.inner, typeCtx);
+                return ret;
+            }
+            const target = typeCtx.get(type.value.value);
+            if (!target)
+                throw new InternalError("Recursive type context not found during encoder build");
+            return target;
+        }
+        case "Function":
+        case "AsyncFunction": {
+            // Build IR encoder in the same typeCtx so recursive types resolve correctly
+            const fnIrEncoder = buildEncoder(irTypeValue, typeCtx);
+            const captureEncoderCache = new Map();
+            return (value, writer, ctx) => {
+                const ir = value[EAST_IR_SYMBOL];
+                if (!ir)
+                    throw new Error(`Cannot serialize function: no IR attached (${describeNoIrValue(value)})`);
+                fnIrEncoder(ir, writer, ctx);
+                const captures = value[EAST_CAPTURES_SYMBOL];
+                const captureList = ir.value.captures;
+                writer.writeVarint(captureList.length);
+                for (const captureVar of captureList) {
+                    const name = captureVar.value.name;
+                    const captureType = captureVar.value.type;
+                    if (!captures)
+                        throw new InternalError("Function has captures but no EAST_CAPTURES_SYMBOL");
+                    const entry = captures[name];
+                    if (!entry)
+                        throw new InternalError(`Capture '${name}' not found`);
+                    let enc = captureEncoderCache.get(captureType);
+                    if (!enc) {
+                        enc = buildEncoder(captureType, typeCtx);
+                        captureEncoderCache.set(captureType, enc);
+                    }
+                    enc(entry.value, writer, ctx);
+                }
+            };
+        }
+        case "Vector":
+            return (value, writer) => {
+                writer.writeVarint(value.length);
+                writer.writeBytes(new Uint8Array(value.buffer, value.byteOffset, value.byteLength));
+            };
+        case "Matrix":
+            return (value, writer) => {
+                writer.writeVarint(value.rows);
+                writer.writeVarint(value.cols);
+                writer.writeBytes(new Uint8Array(value.data.buffer, value.data.byteOffset, value.data.byteLength));
+            };
+        default:
+            throw new Error(`Unknown type: ${type.type}`);
+    }
+}
+// =============================================================================
+// Value decoder factory
+// =============================================================================
+/**
+ * Build a value decoder closure tree for the given type.
+ * The tree is built once and reused for every decode call.
+ */
+function buildDecoder(type, typeCtx = new Map()) {
+    switch (type.type) {
+        case "Never":
+            return () => { throw new Error("Cannot decode value of type Never"); };
+        case "Null":
+            return () => null;
+        case "Boolean":
+            return (reader) => reader.readBoolean();
+        case "Integer":
+            return (reader) => reader.readZigzag();
+        case "Float":
+            return (reader) => reader.readFloat64LE();
+        case "String":
+            return (reader, ctx) => {
+                const idx = reader.readVarint();
+                if (idx >= ctx.stringTable.length)
+                    throw new Error(`String table index ${idx} out of bounds (table has ${ctx.stringTable.length} entries)`);
+                return ctx.stringTable[idx];
+            };
+        case "DateTime":
+            return (reader) => new Date(Number(reader.readZigzag()));
+        case "Blob":
+            return (reader) => reader.readBytes(reader.readVarint());
+        case "Ref":
+        case "Array":
+        case "Set":
+        case "Dict": {
+            // v4: mutable containers are read as varint(table_index) — the actual
+            // content was decoded from the mutable_value_table_section.
+            return (reader, ctx) => {
+                const idx = reader.readVarint();
+                if (idx >= ctx.mutableValues.length)
+                    throw new Error(`Invalid mutable value table index ${idx} (table has ${ctx.mutableValues.length} entries)`);
+                return ctx.mutableValues[idx];
+            };
+        }
+        case "Struct": {
+            const fields = type.value;
+            const names = [];
+            const decoders = [];
+            const ret = (reader, ctx) => {
+                const result = {};
+                for (let i = 0; i < names.length; i++)
+                    result[names[i]] = decoders[i](reader, ctx);
+                return result;
+            };
+            for (const { name, type: fieldType } of fields) {
+                names.push(name);
+                decoders.push(buildDecoder(fieldType, typeCtx));
+            }
+            return ret;
+        }
+        case "Variant": {
+            const caseDecoders = [];
+            const ret = (reader, ctx) => {
+                const tagIndex = reader.readVarint();
+                if (tagIndex >= caseDecoders.length)
+                    throw new Error(`Invalid variant tag ${tagIndex}`);
+                const [caseName, caseDec] = caseDecoders[tagIndex];
+                return variant(caseName, caseDec(reader, ctx));
+            };
+            for (const { name, type: caseType } of type.value) {
+                caseDecoders.push([name, buildDecoder(caseType, typeCtx)]);
+            }
+            return ret;
+        }
+        case "Recursive": {
+            if (type.value.type === "wrapper") {
+                let inner;
+                const ret = (reader, ctx) => inner(reader, ctx);
+                typeCtx.set(type.value.value.id, ret);
+                inner = buildDecoder(type.value.value.inner, typeCtx);
+                return ret;
+            }
+            const target = typeCtx.get(type.value.value);
+            if (!target)
+                throw new InternalError("Recursive type context not found during decoder build");
+            return target;
+        }
+        case "Function":
+        case "AsyncFunction": {
+            const isAsync = type.type === "AsyncFunction";
+            const fnType = type;
+            const fnIrDecoder = buildDecoder(irTypeValue, typeCtx);
+            const captureDecoderCache = new Map();
+            return (reader, ctx) => {
+                const ir = fnIrDecoder(reader, ctx);
+                if (ir.type !== (isAsync ? "AsyncFunction" : "Function")) {
+                    throw new Error(`Expected ${fnType.type} IR, got ${ir.type}`);
+                }
+                // Decode captures
+                const captureCount = reader.readVarint();
+                if (captureCount !== ir.value.captures.length) {
+                    throw new Error(`Capture count mismatch: IR has ${ir.value.captures.length}, data has ${captureCount}`);
+                }
+                const captureContext = {};
+                const typeContext = {};
+                for (const captureVar of ir.value.captures) {
+                    const name = captureVar.value.name;
+                    const captureType = captureVar.value.type;
+                    // Get or build cached decoder for this capture type
+                    let dec = captureDecoderCache.get(captureType);
+                    if (!dec) {
+                        dec = buildDecoder(captureType, typeCtx);
+                        captureDecoderCache.set(captureType, dec);
+                    }
+                    const captureValue = dec(reader, ctx);
+                    captureContext[name] = captureVar.value.mutable
+                        ? variant("boxed", captureValue)
+                        : variant("value", captureValue);
+                    typeContext[name] = captureType;
+                }
+                return finishDecodedFunction(ir, isAsync, captureContext, typeContext, ctx, ctx.sourceMap);
+            };
+        }
+        case "Vector": {
+            const elemType = type.value.type;
+            const bpe = elemType === "Float" ? 8 : elemType === "Integer" ? 8 : 1;
+            return (reader) => {
+                const len = reader.readVarint();
+                const raw = new Uint8Array(reader.readBytesView(len * bpe));
+                if (elemType === "Float")
+                    return new Float64Array(raw.buffer, 0, len);
+                if (elemType === "Integer")
+                    return new BigInt64Array(raw.buffer, 0, len);
+                return new Uint8ClampedArray(raw.buffer, 0, len);
+            };
+        }
+        case "Matrix": {
+            const elemType = type.value.type;
+            const bpe = elemType === "Float" ? 8 : elemType === "Integer" ? 8 : 1;
+            return (reader) => {
+                const rows = reader.readVarint();
+                const cols = reader.readVarint();
+                const raw = new Uint8Array(reader.readBytesView(rows * cols * bpe));
+                if (elemType === "Float")
+                    return matrix(new Float64Array(raw.buffer, 0, rows * cols), rows, cols);
+                if (elemType === "Integer")
+                    return matrix(new BigInt64Array(raw.buffer, 0, rows * cols), rows, cols);
+                return matrix(new Uint8ClampedArray(raw.buffer, 0, rows * cols), rows, cols);
+            };
+        }
+        default:
+            throw new Error(`Unknown type: ${type.type}`);
+    }
+}
+// =============================================================================
+// Mutable value table section (v4)
+// =============================================================================
+function writeValueTableEntry(entry, writer, ctx, encTypeCtx) {
+    const type = entry.type;
+    const value = entry.value;
+    // Write kind tag
+    writer.writeUint8(entry.kind);
+    // Element encoder — handles both inline (non-mutable) and table-ref (mutable) cases
+    const encodeElem = (elemType, val, w, c) => {
+        if (isMutableType(elemType)) {
+            const idx = c.indexMap.get(val);
+            if (idx === undefined)
+                throw new InternalError("Nested mutable value not in value table");
+            w.writeVarint(idx);
+        }
+        else {
+            buildEncoder(elemType, encTypeCtx)(val, w, c);
+        }
+    };
+    switch (type.type) {
+        case "Array": {
+            if (!ctx.typeTable.has(type.value))
+                ctx.typeTable.addETV(type.value);
+            writer.writeVarint(ctx.typeTable.indexOf(type.value));
+            writer.writeVarint(value.length);
+            for (const item of value)
+                encodeElem(type.value, item, writer, ctx);
+            break;
+        }
+        case "Set": {
+            if (!ctx.typeTable.has(type.value))
+                ctx.typeTable.addETV(type.value);
+            writer.writeVarint(ctx.typeTable.indexOf(type.value));
+            writer.writeVarint(value.size);
+            for (const key of value)
+                encodeElem(type.value, key, writer, ctx);
+            break;
+        }
+        case "Dict": {
+            if (!ctx.typeTable.has(type.value.key))
+                ctx.typeTable.addETV(type.value.key);
+            if (!ctx.typeTable.has(type.value.value))
+                ctx.typeTable.addETV(type.value.value);
+            writer.writeVarint(ctx.typeTable.indexOf(type.value.key));
+            writer.writeVarint(ctx.typeTable.indexOf(type.value.value));
+            writer.writeVarint(value.size);
+            for (const [k, v] of value) {
+                encodeElem(type.value.key, k, writer, ctx);
+                encodeElem(type.value.value, v, writer, ctx);
+            }
+            break;
+        }
+        case "Ref": {
+            if (!ctx.typeTable.has(type.value))
+                ctx.typeTable.addETV(type.value);
+            writer.writeVarint(ctx.typeTable.indexOf(type.value));
+            encodeElem(type.value, value.value, writer, ctx);
+            break;
+        }
+    }
+}
+/** Built decoder trees, keyed on the decoded type table itself.
+ *
+ * These trees were rebuilt on EVERY decode, which for a large recursive
+ * schema is the dominant cost of decoding at all: a UIComponentType blob
+ * (1127 type-table entries, 5 recursive wrappers) spent ~200 ms per decode
+ * with 86% of it in buildDecoder plus the GC churn from the closures it
+ * allocates — while east-c, whose decoder is a switch over types and
+ * allocates nothing, decoded the same blob in 0.04 ms.
+ *
+ * Decoders take their DecodeContext as a parameter and close over nothing
+ * per-decode, so they are safe to share. The key is the type-table array,
+ * which the section skip-cache (#417) returns as one frozen instance per
+ * distinct schema — so repeat decodes of a schema hit this cache, and a
+ * genuinely new schema simply builds once. */
+const tableDecoderCache = new WeakMap();
+function decodersForTypeTable(typeTable) {
+    const cached = tableDecoderCache.get(typeTable);
+    if (cached)
+        return cached;
+    const decTypeCtx = new Map();
+    for (const t of typeTable) {
+        if (t.type === "Recursive" && t.value?.type === "wrapper") {
+            buildDecoder(t, decTypeCtx);
+        }
+    }
+    const entry = { decTypeCtx, decoderCache: new Map() };
+    tableDecoderCache.set(typeTable, entry);
+    return entry;
+}
+function readMutableValueTableSection(reader, ctx) {
+    const sectionByteLength = reader.readVarint();
+    const sectionEnd = reader.offset + sectionByteLength;
+    const entryCount = reader.readVarint();
+    if (entryCount === 0) {
+        if (reader.offset !== sectionEnd)
+            throw new Error(`Value table section size mismatch`);
+        return;
+    }
+    // Two-pass decode: pre-allocate all containers, then fill elements.
+    // Each entry is prefixed with varint(byte_length), enabling trivial skip in pass 1.
+    // Pass 1: read entry headers, pre-allocate empty containers, skip element data by byte length
+    const entryOffsets = new Array(entryCount);
+    const entryLengths = new Array(entryCount);
+    for (let i = 0; i < entryCount; i++) {
+        const entryByteLength = reader.readVarint();
+        const entryStart = reader.offset;
+        const kindTag = reader.readUint8();
+        switch (kindTag) {
+            case TAG_ARRAY: {
+                reader.readVarint(); // elem type idx (skip)
+                const count = reader.readVarint();
+                ctx.mutableValues.push(new Array(count));
+                break;
+            }
+            case TAG_SET: {
+                // Sets and Dicts are ORDERED by East's total order — a decoded one
+                // must be a SortedSet/SortedMap, not a plain Set/Map. A plain
+                // container preserves wire order instead, which (a) violates the
+                // ordering invariant every East-created collection holds (see
+                // compile.ts) and (b) made TS re-encode a value to different bytes
+                // than east-c, whose btrees always sort. That broke cross-runtime
+                // byte parity, and with it content-addressing.
+                const setElemIdx = reader.readVarint();
+                reader.readVarint(); // count (skip — SortedSet doesn't pre-allocate)
+                ctx.mutableValues.push(new SortedSet(undefined, compareFor(ctx.typeTable[setElemIdx])));
+                break;
+            }
+            case TAG_DICT: {
+                const dictKeyIdx = reader.readVarint();
+                reader.readVarint(); // val type idx (skip)
+                reader.readVarint(); // count (skip)
+                ctx.mutableValues.push(new SortedMap(undefined, compareFor(ctx.typeTable[dictKeyIdx])));
+                break;
+            }
+            case TAG_REF: {
+                reader.readVarint(); // inner type idx (skip)
+                ctx.mutableValues.push(ref(undefined));
+                break;
+            }
+            default:
+                throw new Error(`Unknown value table kind tag 0x${kindTag.toString(16)}`);
+        }
+        entryOffsets[i] = entryStart;
+        entryLengths[i] = entryByteLength;
+        // Skip to next entry using byte length
+        reader.offset = entryStart + entryByteLength;
+    }
+    if (reader.offset !== sectionEnd) {
+        throw new Error(`Value table section size mismatch: expected ${sectionEnd}, got ${reader.offset}`);
+    }
+    // Decoder trees for the decoded type table, shared across decodes of the
+    // same schema (see decodersForTypeTable).
+    const { decTypeCtx, decoderCache } = decodersForTypeTable(ctx.typeTable);
+    const getCachedDecoder = (typeIdx) => {
+        let dec = decoderCache.get(typeIdx);
+        if (!dec) {
+            dec = buildDecoder(ctx.typeTable[typeIdx], decTypeCtx);
+            decoderCache.set(typeIdx, dec);
+        }
+        return dec;
+    };
+    // Pass 2: fill elements in REVERSE order — children (higher indices) before parents.
+    // The walker produces parents-before-children, so reversing ensures a parent's
+    // element decoders (e.g., Function compilers) see fully-populated child entries.
+    for (let i = entryCount - 1; i >= 0; i--) {
+        const r = new BufferReader(reader.buffer, entryOffsets[i]);
+        const kindTag = r.readUint8();
+        switch (kindTag) {
+            case TAG_ARRAY: {
+                const elemTypeIdx = r.readVarint();
+                const elemType = ctx.typeTable[elemTypeIdx];
+                const count = r.readVarint();
+                const arr = ctx.mutableValues[i];
+                const isMut = isMutableType(elemType);
+                const dec = isMut ? null : getCachedDecoder(elemTypeIdx);
+                for (let j = 0; j < count; j++) {
+                    arr[j] = isMut ? ctx.mutableValues[r.readVarint()] : dec(r, ctx);
+                }
+                break;
+            }
+            case TAG_SET: {
+                const elemTypeIdx = r.readVarint();
+                const elemType = ctx.typeTable[elemTypeIdx];
+                const count = r.readVarint();
+                const set = ctx.mutableValues[i];
+                const isMut = isMutableType(elemType);
+                const dec = isMut ? null : getCachedDecoder(elemTypeIdx);
+                for (let j = 0; j < count; j++) {
+                    set.add(isMut ? ctx.mutableValues[r.readVarint()] : dec(r, ctx));
+                }
+                break;
+            }
+            case TAG_DICT: {
+                const keyTypeIdx = r.readVarint();
+                const valTypeIdx = r.readVarint();
+                const keyType = ctx.typeTable[keyTypeIdx];
+                const valType = ctx.typeTable[valTypeIdx];
+                const count = r.readVarint();
+                const map = ctx.mutableValues[i];
+                const keyMut = isMutableType(keyType);
+                const valMut = isMutableType(valType);
+                const keyDec = keyMut ? null : getCachedDecoder(keyTypeIdx);
+                const valDec = valMut ? null : getCachedDecoder(valTypeIdx);
+                for (let j = 0; j < count; j++) {
+                    const k = keyMut ? ctx.mutableValues[r.readVarint()] : keyDec(r, ctx);
+                    const v = valMut ? ctx.mutableValues[r.readVarint()] : valDec(r, ctx);
+                    map.set(k, v);
+                }
+                break;
+            }
+            case TAG_REF: {
+                const innerTypeIdx = r.readVarint();
+                const innerType = ctx.typeTable[innerTypeIdx];
+                const rv = ctx.mutableValues[i];
+                if (isMutableType(innerType)) {
+                    rv.value = ctx.mutableValues[r.readVarint()];
+                }
+                else {
+                    rv.value = getCachedDecoder(innerTypeIdx)(r, ctx);
+                }
+                break;
+            }
+        }
+    }
+}
+const baseTypeTableCache = new WeakMap();
+function baseTypeTableFor(type, eastType, typeValue) {
+    const cached = baseTypeTableCache.get(type);
+    if (cached)
+        return cached;
+    const builder = new TypeTableBuilder();
+    const rootIdx = eastType ? builder.add(eastType) : builder.add(typeValue);
+    const sw = new BufferWriter();
+    writeTypeTableSection(rootIdx, builder.entries, sw);
+    const entry = { builder, rootIdx, sectionBytes: sw.toUint8Array() };
+    baseTypeTableCache.set(type, entry);
+    return entry;
+}
+export function encodeBeast2V4For(type, options) {
+    const eastType = isVariant(type) ? undefined : type;
+    const typeValue = isVariant(type) ? type : toEastTypeValue(type);
+    // Build encoder tree once at setup — save the typeCtx for reuse by value table entries
+    const setupTypeCtx = new Map();
+    const valueEncoder = buildEncoder(typeValue, setupTypeCtx);
+    // Root-closure type table (stable across encode calls AND closures — #417).
+    const base = baseTypeTableFor(type, eastType, typeValue);
+    const baseRootIdx = base.rootIdx;
+    const baseEntryCount = base.builder.entries.length;
+    return (value) => {
+        const builder = base.builder.clone();
+        const stringTable = new Map();
+        // Build the mutable value table by walking the value graph.
+        // The walk also discovers the source map from any function in the value graph.
+        const vtResult = buildValueTable(value, typeValue, builder);
+        const vtEntries = vtResult.entries;
+        const indexMap = buildIndexMap(vtEntries);
+        // Source map: explicit option > root value > discovered during walk > null
+        const sourceMap = options?.sourceMap
+            ?? value?.[EAST_SOURCE_MAP_SYMBOL]
+            ?? vtResult.sourceMap
+            ?? null;
+        const ctx = { indexMap, typeTable: builder, stringTable };
+        // Encode value table entries FIRST — this discovers types and strings
+        // from inside mutable containers (which are varint refs in the value stream)
+        const vtWriter = new BufferWriter();
+        vtWriter.writeVarint(vtEntries.length);
+        for (const entry of vtEntries) {
+            // Buffer each entry, then write varint(byte_length) + entry bytes
+            const entryWriter = new BufferWriter();
+            writeValueTableEntry(entry, entryWriter, ctx, setupTypeCtx);
+            const entryBytes = entryWriter.toUint8Array();
+            vtWriter.writeVarint(entryBytes.length);
+            vtWriter.writeBytes(entryBytes);
+        }
+        // Encode the value stream (mutable containers are written as varint indices)
+        const valueWriter = new BufferWriter();
+        valueEncoder(value, valueWriter, ctx);
+        // Source map filenames must be added to stringTable before writing string table section
+        const smWriter = new BufferWriter();
+        writeSourceMapSection(sourceMap, stringTable, smWriter);
+        // Write the final blob: magic + type table + string table + source map + value table + value data
+        const writer = new BufferWriter();
+        writer.writeBytes(MAGIC_BYTES);
+        if (builder.entries.length === baseEntryCount) {
+            // The value walk added no types — the section is the cached root
+            // closure, byte for byte (#417).
+            writer.writeBytes(base.sectionBytes);
+        }
+        else {
+            writeTypeTableSection(baseRootIdx, builder.entries, writer);
+        }
+        writeStringTableSection(stringTable, writer);
+        writer.writeBytes(smWriter.toUint8Array());
+        // Write value table section with byte-length prefix
+        const vtBytes = vtWriter.toUint8Array();
+        writer.writeVarint(vtBytes.length);
+        writer.writeBytes(vtBytes);
+        writer.writeBytes(valueWriter.toUint8Array());
+        return writer.toUint8Array();
+    };
+}
+export function decodeBeast2V4For(type, options) {
+    if (!isVariant(type))
+        type = toEastTypeValue(type);
+    const typeValue = type;
+    // Pre-build value decoder once (reused on every decode call)
+    const valueDecoder = buildDecoder(typeValue);
+    const platformCtx = buildPlatformContext(options);
+    return (data) => {
+        verifyMagic(data);
+        const reader = new BufferReader(data, MAGIC_BYTES.length);
+        const { typeTable } = readTypeTableSection(reader);
+        const stringTable = readStringTableSection(reader);
+        const sourceMap = readSourceMapSection(reader, stringTable);
+        const ctx = {
+            mutableValues: [],
+            typeTable,
+            stringTable,
+            sourceMap,
+            ...platformCtx,
+        };
+        readMutableValueTableSection(reader, ctx);
+        const value = valueDecoder(reader, ctx);
+        if (reader.offset !== data.length) {
+            throw new Error(`${data.length - reader.offset} trailing bytes at offset ${reader.offset}`);
+        }
+        return value;
+    };
+}
+// =============================================================================
+// Public API — IR + source map (v4 container)
+// =============================================================================
+/**
+ * Decodes a v4 IRType blob and returns both the IR value and the decoded
+ * source map. Backs the version-agnostic `decodeEastIR` / `decodeAsyncEastIR`.
+ *
+ * @param data - a v4 beast2 blob whose root is a Function/AsyncFunction IR
+ * @returns the decoded IR value and the blob's source map (or `null`)
+ */
+export function decodeIRWithSourceMapV4(data) {
+    verifyMagic(data);
+    const reader = new BufferReader(data, MAGIC_BYTES.length);
+    const { typeTable } = readTypeTableSection(reader);
+    const stringTable = readStringTableSection(reader);
+    const sourceMap = readSourceMapSection(reader, stringTable);
+    const valueDecoder = buildDecoder(irTypeValue);
+    const ctx = {
+        mutableValues: [],
+        typeTable,
+        stringTable,
+        sourceMap,
+        ...buildPlatformContext(),
+    };
+    readMutableValueTableSection(reader, ctx);
+    const ir = valueDecoder(reader, ctx);
+    if (reader.offset !== data.length) {
+        throw new Error(`${data.length - reader.offset} trailing bytes at offset ${reader.offset}`);
+    }
+    return { ir, sourceMap };
+}
+// =============================================================================
+// Public API — Decode (v4 container, self-describing)
+// =============================================================================
+/**
+ * Decodes a self-describing v4 blob using its embedded root type.
+ *
+ * @param data - a v4 beast2 blob
+ * @param options - decode options (platform functions for decoded functions)
+ * @returns the blob's root type and decoded value
+ */
+export function decodeBeast2V4(data, options) {
+    verifyMagic(data);
+    const reader = new BufferReader(data, MAGIC_BYTES.length);
+    const { rootType, typeTable } = readTypeTableSection(reader);
+    const stringTable = readStringTableSection(reader);
+    const sourceMap = readSourceMapSection(reader, stringTable);
+    const valueDecoder = buildDecoder(rootType);
+    const ctx = {
+        mutableValues: [],
+        typeTable,
+        stringTable,
+        sourceMap,
+        ...buildPlatformContext(options),
+    };
+    readMutableValueTableSection(reader, ctx);
+    const value = valueDecoder(reader, ctx);
+    if (reader.offset !== data.length) {
+        throw new Error(`${data.length - reader.offset} trailing bytes at offset ${reader.offset}`);
+    }
+    return { type: rootType, value };
+}
+//# sourceMappingURL=container.js.map