@elaraai/east 1.0.45 → 1.0.46

package/dist/src/serialization/beast2/index.js

@@ -3,696 +3,101 @@
  * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
  */
 /**
- * Beast2 v2 — complete encoder and decoder.
+ * Beast2 container — version-agnostic public entry points.
  *
- * File layout: magic(8) + type_table_section + string_table_section + value_data
- * Type table: flat array of unique types, referenced by varint index.
- * String table: flat array of unique strings, referenced by varint index.
- * Value data: type-driven positional encoding, no inline type tags.
- * Functions: IR encoded directly — EastTypeType schema positions auto-emit type table indices.
- *
- * See devdocs/BEAST2.md for the full specification.
+ * Decoders dispatch on the magic's version byte (`v4` = 0x04, `v5` = 0x05) so
+ * every entry point accepts blobs of either container version. Encoders write
+ * the v4 container by default. See `SPEC.md` for the magic registry and
+ * version policy, `v4/SPEC.md` and `v5/SPEC.md` for the wire formats.
  */
 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 { matrix } from "../../containers/matrix.js";
-import { EAST_IR_SYMBOL, EAST_CAPTURES_SYMBOL, EAST_SOURCE_MAP_SYMBOL, ReturnException, compile_internal } from "../../compile.js";
-import { InternalError } from "../../error.js";
+import { isVariant } from "../../containers/variant.js";
 import { IRType } from "../../ir.js";
 import { EastIR, AsyncEastIR } from "../../eastir.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";
-// 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.
-// Shared empty set for compile_internal's compilingNodes parameter (avoids per-call allocation)
-const EMPTY_SET = new Set();
+import {} from "./shared.js";
+import { MAGIC_BYTES, encodeBeast2V4For, decodeBeast2V4For, decodeBeast2V4, decodeIRWithSourceMapV4, } from "./v4/container.js";
+import { encodeBeast2V5For, decodeBeast2V5For, decodeBeast2V5ForAsync, decodeBeast2V5, decodeIRWithSourceMapV5, } from "./v5/codec.js";
+import { BEAST2_WRITE_VERSION } from "./version.js";
+export { MAGIC_BYTES } from "./v4/container.js";
+export { MAGIC_BYTES_V5 } from "./v5/codec.js";
+export { Beast2Writer, encodeBeast2SegmentsFor, iterBeast2SegmentsFor, Beast2Pages, openBeast2PagesFor, } from "./v5/stream.js";
+// =============================================================================
+// Magic dispatch
+// =============================================================================
+export { BEAST2_WRITE_VERSION, BEAST2_READ_VERSIONS } from "./version.js";
 /**
- * Build a safe, bounded description of a value that reached the Function encoder
- * with no compiled IR, for the "no IR attached" diagnostic.
+ * Sniffs the container version from a blob's magic bytes.
  *
- * The encoder expects a function carrying {@link EAST_IR_SYMBOL}; when that symbol
- * is absent the *value itself* is suspect (it may not even be a function — a
- * non-function in a `FunctionType` slot lands here too — and it may be a Proxy or
- * carry a throwing `toString`). Every inspection is therefore either total
- * (`typeof`, `Object.prototype.toString`) or guarded, so the diagnostic can never
- * throw and mask the real failure.
- *
- * @param value - the value found where an East function with IR was expected
- * @returns a single-line, length-bounded description
+ * @param data - the blob to inspect
+ * @returns the container version (4 or 5)
+ * @throws {Error} When the data is too short, the magic prefix is wrong, or
+ *   the version byte is unknown.
  */
-function describeNoIrValue(value) {
-    const kind = typeof value; // total — never throws
-    const tag = Object.prototype.toString.call(value); // safe [[Class]]; no user code
-    const parts = [`typeof=${kind}`, `tag=${tag}`];
-    try {
-        if (kind === "function") {
-            const name = value.name;
-            if (typeof name === "string" && name)
-                parts.push(`name=${name}`);
-            // Built-in toString (not the possibly-overridden value.toString) → the source text.
-            const src = Function.prototype.toString.call(value).replace(/\s+/g, " ");
-            parts.push(`source=${src.length > 160 ? `${src.slice(0, 160)}…` : src}`);
-            parts.push(`hasCaptures=${value[EAST_CAPTURES_SYMBOL] !== undefined}`);
-            parts.push(`hasSourceMap=${value[EAST_SOURCE_MAP_SYMBOL] !== undefined}`);
-        }
-        else if (value !== null && value !== undefined) {
-            const ctorName = value.constructor?.name;
-            if (typeof ctorName === "string")
-                parts.push(`constructor=${ctorName}`);
-        }
-    }
-    catch {
-        parts.push("(preview unavailable)");
-    }
-    return parts.join(" ");
-}
-// =============================================================================
-// Magic bytes (v2: last byte = 0x02)
-// =============================================================================
-export const MAGIC_BYTES = new Uint8Array([0x89, 0x45, 0x61, 0x73, 0x74, 0x0D, 0x0A, 0x04]);
-function verifyMagic(data) {
+function sniffVersion(data) {
     if (data.length < 8) {
         throw new Error(`Data too short for Beast2 format: ${data.length} bytes`);
     }
-    for (let i = 0; i < 8; i++) {
+    for (let i = 0; i < 7; 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;
+            throw new Error(`Invalid Beast2 magic at offset ${i}: expected 0x${MAGIC_BYTES[i].toString(16)}, got 0x${data[i].toString(16)}`);
         }
-        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}`);
     }
+    const version = data[7];
+    if (version === 0x04)
+        return 4;
+    if (version === 0x05)
+        return 5;
+    throw new Error(`Unknown Beast2 version: 0x${version.toString(16)}`);
 }
-// =============================================================================
-// 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;
-                }
-                // Compile IR to callable function — mutate in place to avoid object spread allocations
-                ir.value.isAsync = isAsync;
-                const compiled = compile_internal(ir, typeContext, ctx.platformFns, ctx.asyncPlatformFns, ctx.platform, true, EMPTY_SET);
-                const rawFn = compiled(captureContext);
-                const fn = isAsync
-                    ? async (...inputs) => {
-                        try {
-                            return await rawFn(...inputs);
-                        }
-                        catch (e) {
-                            if (e instanceof ReturnException)
-                                return e.value;
-                            throw e;
-                        }
-                    }
-                    : (...inputs) => {
-                        try {
-                            return rawFn(...inputs);
-                        }
-                        catch (e) {
-                            if (e instanceof ReturnException)
-                                return e.value;
-                            throw e;
-                        }
-                    };
-                // Attach IR, captures, and source map for re-serialization
-                Object.defineProperty(fn, EAST_IR_SYMBOL, { value: ir, writable: false, enumerable: false, configurable: false });
-                Object.defineProperty(fn, EAST_CAPTURES_SYMBOL, { value: captureContext, writable: false, enumerable: false, configurable: false });
-                if (ctx.sourceMap) {
-                    Object.defineProperty(fn, EAST_SOURCE_MAP_SYMBOL, { value: ctx.sourceMap, writable: false, enumerable: false, configurable: false });
-                }
-                return fn;
-            };
-        }
-        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}`);
-    }
-}
-// =============================================================================
-// String table section
-// =============================================================================
-// String table functions extracted to beast2-string-table.ts
-// =============================================================================
-// IR encoder/decoder (module-level singletons)
-// =============================================================================
-const irTypeValue = toEastTypeValue(IRType);
-// =============================================================================
-// 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;
-        }
+export function encodeBeast2For(type, options) {
+    if ((options?.version ?? BEAST2_WRITE_VERSION) === 4) {
+        return encodeBeast2V4For(type, options);
     }
+    return encodeBeast2V5For(type, options);
 }
-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: {
-                reader.readVarint(); // elem type idx (skip)
-                reader.readVarint(); // count (skip — Set doesn't pre-allocate by count)
-                ctx.mutableValues.push(new Set());
-                break;
-            }
-            case TAG_DICT: {
-                reader.readVarint(); // key type idx (skip)
-                reader.readVarint(); // val type idx (skip)
-                reader.readVarint(); // count (skip)
-                ctx.mutableValues.push(new Map());
-                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}`);
-    }
-    // Pre-build decoders for ALL recursive types in the decoded type table into
-    // a shared typeCtx. This ensures cross-type references resolve correctly
-    // (e.g., IR arrays inside Functions reference both IRType and EastTypeType).
-    const decTypeCtx = new Map();
-    for (const t of ctx.typeTable) {
-        if (t.type === "Recursive" && t.value?.type === "wrapper") {
-            buildDecoder(t, decTypeCtx);
-        }
-    }
-    // Cache decoders by element type index — most entries share the same type
-    const decoderCache = new Map();
-    const getCachedDecoder = (typeIdx) => {
-        let dec = decoderCache.get(typeIdx);
-        if (!dec) {
-            dec = buildDecoder(ctx.typeTable[typeIdx], decTypeCtx);
-            decoderCache.set(typeIdx, dec);
+export function decodeBeast2For(type, options) {
+    const typeValue = toTypeValue(type);
+    // Version decoders are built lazily on first use — most call sites only ever
+    // see one container version.
+    let v4;
+    let v5;
+    return (data) => {
+        if (sniffVersion(data) === 5) {
+            v5 ??= decodeBeast2V5For(typeValue, options);
+            return v5(data);
         }
-        return dec;
+        v4 ??= decodeBeast2V4For(typeValue, options);
+        return v4(data);
     };
-    // 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;
-            }
-        }
-    }
 }
-export function encodeBeast2For(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);
-    // Pre-build the type table for the root type (stable across encode calls).
-    const baseBuilder = new TypeTableBuilder();
-    const baseRootIdx = eastType ? baseBuilder.add(eastType) : baseBuilder.add(typeValue);
-    return (value) => {
-        const builder = baseBuilder.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);
-        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 decodeBeast2ForAsync(type, options) {
+    const typeValue = toTypeValue(type);
+    let v4;
+    let v5;
+    return async (data) => {
+        if (sniffVersion(data) === 5) {
+            v5 ??= decodeBeast2V5ForAsync(typeValue, options);
+            return v5(data);
+        }
+        v4 ??= decodeBeast2V4For(typeValue, options);
+        return v4(data);
     };
 }
-export function decodeBeast2For(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 platform = options?.platform ?? [];
-    const platformFns = Object.fromEntries(platform.map(fn => [fn.name, fn.fn]));
-    const asyncPlatformFns = new Set(platform.filter(fn => fn.type === 'async').map(fn => fn.name));
-    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,
-            platform,
-            platformFns,
-            asyncPlatformFns,
-        };
-        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 — Decode (self-describing)
+// =============================================================================
+/**
+ * Decodes a self-describing blob using its embedded root type.
+ *
+ * @param data - a beast2 blob of any supported container version
+ * @param options - decode options (platform functions for decoded functions)
+ * @returns the blob's root type and decoded value
+ */
+export function decodeBeast2(data, options) {
+    if (sniffVersion(data) === 5) {
+        return decodeBeast2V5(data, options);
+    }
+    return decodeBeast2V4(data, options);
 }
 // =============================================================================
 // Public API — EastIR bundle (IR + source map travelling together)
@@ -705,8 +110,8 @@ export function decodeBeast2For(type, options) {
 /** Encode an EastIR (or AsyncEastIR) as a beast2 blob that carries both the
  *  IR and its source map. Prefer this over `encodeBeast2For(IRType)(ir)` when
  *  encoding a program rather than opaque IR data. */
-export function encodeEastIR(eastIR) {
-    return encodeBeast2For(IRType, { sourceMap: eastIR.source_map })(eastIR.ir);
+export function encodeEastIR(eastIR, options) {
+    return encodeBeast2For(IRType, { ...options, sourceMap: eastIR.source_map })(eastIR.ir);
 }
 /** Decode a beast2 blob whose root is a Function IR into an EastIR. The
  *  returned wrapper has its source_map populated from the blob's source_map
@@ -730,58 +135,13 @@ export function decodeAsyncEastIR(data) {
     result.source_map = sourceMap;
     return result;
 }
-/** Internal: decode IRType blob and return both the IR value and the decoded
- *  source map. Shared by decodeEastIR / decodeAsyncEastIR. */
+/** Internal: decode an IRType blob of any container version and return both
+ *  the IR value and the decoded source map. */
 function decodeIRWithSourceMap(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 irTypeValue = toEastTypeValue(IRType);
-    const valueDecoder = buildDecoder(irTypeValue);
-    const ctx = {
-        mutableValues: [],
-        typeTable,
-        stringTable,
-        sourceMap,
-        platform: [],
-        platformFns: {},
-        asyncPlatformFns: new Set(),
-    };
-    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}`);
+    if (sniffVersion(data) === 5) {
+        return decodeIRWithSourceMapV5(data);
     }
-    return { ir, sourceMap };
-}
-// =============================================================================
-// Public API — Decode (self-describing)
-// =============================================================================
-export function decodeBeast2(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 platform = options?.platform ?? [];
-    const ctx = {
-        mutableValues: [],
-        typeTable,
-        stringTable,
-        sourceMap,
-        platform,
-        platformFns: Object.fromEntries(platform.map(fn => [fn.name, fn.fn])),
-        asyncPlatformFns: new Set(platform.filter(fn => fn.type === 'async').map(fn => fn.name)),
-    };
-    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 };
+    return decodeIRWithSourceMapV4(data);
 }
 // =============================================================================
 // Re-exports
@@ -793,4 +153,11 @@ export function compileFunctionIR(ir, platform) {
 export function compileAsyncFunctionIR(ir, platform) {
     return new AsyncEastIR(ir).compile(platform);
 }
+// =============================================================================
+// Internal helpers
+// =============================================================================
+/** Normalizes an `EastType | EastTypeValue` to `EastTypeValue`. */
+function toTypeValue(type) {
+    return isVariant(type) ? type : toEastTypeValue(type);
+}
 //# sourceMappingURL=index.js.map