@elaraai/east 1.0.45 → 1.0.46

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

@@ -0,0 +1,213 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * Beast2 v5 codec — the single-pass, segment-terminated record stream.
+ *
+ * Blob layout:
+ *
+ *     magic[8]               0x89 "East" 0x0D 0x0A 0x05
+ *     type_section           well-known id + hash, or structural (v4 table)
+ *     source_map_section     varint(len) + stacks with inline filenames
+ *     value stream           frames carrying the logical value encoding
+ *     [index_section]        optional — segment offsets/counts (see stream.ts)
+ *     [footer]               u64-LE index offset + footer magic
+ *
+ * Logical value encoding (type-directed, positional):
+ * - immutable scalars encode as in v4, except strings are inline
+ *   (`varint(len) + utf8`) — there is no string table.
+ * - mutable containers (Array/Set/Dict/Ref) carry a tag byte: `0x00 NEW`
+ *   defines the container (registered in definition-start preorder) and is
+ *   followed by its content; `0x01 REF` + `varint(delta)` aliases the
+ *   container defined `delta` definitions ago. Relative deltas make decode
+ *   independent of segment scoping — a self-contained segment resolves the
+ *   same deltas with a fresh table that a sequential reader resolves with a
+ *   global one.
+ * - Array/Set/Dict content is segment-terminated:
+ *   `repeat[varint(n>0) + n elements] varint(0)` — no up-front totals.
+ * - Function values emit a source-map delta (`varint(n_new)` + stacks not yet
+ *   written to this stream), then their IR, then `varint(capture_count)` +
+ *   captures. Location ids inside IR stay plain integer data, so round-trips
+ *   preserve them exactly.
+ *
+ * See v5/SPEC.md for the full wire specification.
+ */
+import { type EastTypeValue } from "../../../type_of_type.js";
+import type { EastType } from "../../../types.js";
+import { BufferWriter, BufferReader } from "../../binary-utils.js";
+import { SourceMap } from "../../../location.js";
+import { type Beast2DecodeOptions, type PlatformDecodeContext } from "../shared.js";
+import { type Beast2Codec } from "./frames.js";
+/** The v5 container magic: the beast2 magic with version byte 0x05. */
+export declare const MAGIC_BYTES_V5: Uint8Array<ArrayBuffer>;
+/** Container tag: defines a new mutable container at this position. */
+export declare const TAG_NEW = 0;
+/** Container tag: aliases a previously defined container by relative delta. */
+export declare const TAG_REF = 1;
+/** Mutable state threaded through a v5 encode pass. */
+export interface V5EncodeContext {
+    /** Identity map: container object → definition index. Cleared per root
+     *  segment by self-contained writers. */
+    containerIndex: Map<any, number>;
+    /** Count of container definitions so far (the definition counter). */
+    containerCount: number;
+    /** Definition count at the start of the current root segment — REFs
+     *  reaching below this mark are cross-segment aliases. */
+    segmentBaseDef: number;
+    /** Whether any REF crossed a root-segment boundary. */
+    crossSegmentRef: boolean;
+    /** The stream's source map (header map, or adopted from the first function
+     *  value that carries one). */
+    sourceMap: SourceMap | null;
+    /** Number of source-map stacks already written (header + inline deltas),
+     *  including the index-0 empty sentinel. */
+    sourceMapEmitted: number;
+    /** Self-contained mode: inline source-map growth is forbidden (stacks
+     *  emitted mid-stream would be unreachable from later segments). */
+    selfContained: boolean;
+}
+/** Creates a fresh v5 encode context.
+ *
+ * @param sourceMap - the pre-resolved header source map, if any
+ * @param selfContained - whether the writer scopes aliasing per segment
+ * @returns the initialized context
+ */
+export declare function createV5EncodeContext(sourceMap: SourceMap | null, selfContained: boolean): V5EncodeContext;
+/** Mutable state threaded through a v5 decode pass. */
+export interface V5DecodeContext extends PlatformDecodeContext {
+    /** Every decoded container in definition order — REF deltas resolve from
+     *  the tail of this list. */
+    containers: any[];
+    /** The stream's source map, accumulated from the header section and inline
+     *  deltas. Attached to every decoded function. */
+    sourceMap: SourceMap;
+}
+/**
+ * Writes the v5 source_map_section: `varint(payload_len)` + `varint(count)` +
+ * stacks with inline filenames. Entry 0 (the empty sentinel) is implicit.
+ *
+ * @param sourceMap - the header source map, or `null` for an empty section
+ * @param writer - the wire-level writer
+ */
+export declare function writeSourceMapSectionV5(sourceMap: SourceMap | null, writer: BufferWriter): void;
+/**
+ * Reads the v5 source_map_section into a fresh {@link SourceMap}.
+ *
+ * @param reader - the wire-level reader positioned at the section start
+ * @returns the decoded source map (stack ids match encode-side ids)
+ */
+export declare function readSourceMapSectionV5(reader: BufferReader): SourceMap;
+type V5Encoder = (value: any, writer: BufferWriter, ctx: V5EncodeContext) => void;
+type V5Decoder = (reader: BufferReader, ctx: V5DecodeContext) => any;
+/**
+ * Builds a v5 value encoder closure tree for the given type.
+ *
+ * @param type - the type to encode
+ * @param typeCtx - recursive-type resolution context shared across the tree
+ * @returns the encoder closure
+ */
+export declare function buildV5Encoder(type: EastTypeValue, typeCtx?: Map<bigint, V5Encoder>): V5Encoder;
+/**
+ * Builds a v5 value decoder closure tree for the given type.
+ *
+ * @param type - the type to decode
+ * @param typeCtx - recursive-type resolution context shared across the tree
+ * @returns the decoder closure
+ */
+export declare function buildV5Decoder(type: EastTypeValue, typeCtx?: Map<bigint, V5Decoder>): V5Decoder;
+/** Options accepted by the v5 whole-value encoder. */
+export type Beast2V5EncodeOptions = {
+    /** Explicit source map to embed in the header section. */
+    sourceMap?: SourceMap | null;
+    /** Per-frame codec. Defaults to `"deflate"`. */
+    codec?: Beast2Codec;
+    /** Write the trailing index + footer (container roots only). Defaults to
+     *  `false` for whole-value encodes. */
+    index?: boolean;
+};
+/** Whether a root type takes the segmented container framing. */
+export declare function isSegmentedRoot(type: EastTypeValue): boolean;
+/**
+ * Builds a v5 whole-value encoder closure for the given type.
+ *
+ * @param type - the root East type (as `EastType` or `EastTypeValue`)
+ * @param options - encode options (source map, codec, index)
+ * @returns a reusable function encoding values of `type` to v5 beast2 bytes
+ */
+export declare function encodeBeast2V5For(type: EastTypeValue | EastType, options?: Beast2V5EncodeOptions): (value: any) => Uint8Array;
+/** The v5 footer magic: the beast2 magic family with terminal byte 0xF5. */
+export declare const FOOTER_MAGIC_V5: Uint8Array<ArrayBuffer>;
+/** Index flag bit: segments are independently decodable (no cross-segment
+ *  aliasing), so paging readers may seek. */
+export declare const INDEX_FLAG_SELF_CONTAINED = 1;
+/**
+ * Writes the index_section and footer.
+ *
+ * @param writer - the wire-level writer (its current size is the index offset)
+ * @param segments - per-segment absolute frame offsets and element counts
+ * @param selfContained - whether segments are independently decodable
+ */
+export declare function writeIndexAndFooter(writer: BufferWriter, segments: {
+    offset: number;
+    count: number;
+}[], selfContained: boolean): void;
+/** A parsed v5 index. */
+export interface Beast2Index {
+    selfContained: boolean;
+    /** Absolute wire offset of each segment's frame. */
+    offsets: number[];
+    /** Element count of each segment (pairs for Dict roots). */
+    counts: number[];
+    /** Sum of all segment counts. */
+    totalCount: number;
+}
+/**
+ * Reads the index_section + footer from the tail of a blob.
+ *
+ * @param data - the whole blob
+ * @returns the parsed index, or `null` when the blob carries no footer
+ * @throws {Error} When a footer is present but the index is malformed.
+ */
+export declare function readIndex(data: Uint8Array): Beast2Index | null;
+/**
+ * Builds a v5 decoder closure for the given type.
+ *
+ * @param type - the expected root East type (as `EastType` or `EastTypeValue`)
+ * @param options - decode options (platform functions for decoded functions)
+ * @returns a reusable function decoding v5 beast2 bytes to values of `type`
+ */
+export declare function decodeBeast2V5For(type: EastTypeValue | EastType, options?: Beast2DecodeOptions): (data: Uint8Array) => any;
+/**
+ * Builds an async v5 decoder closure — pre-inflates deflate frames with the
+ * platform's async decompressor, so it works in browsers without zlib.
+ *
+ * @param type - the expected root East type (as `EastType` or `EastTypeValue`)
+ * @param options - decode options (platform functions for decoded functions)
+ * @returns a reusable async function decoding v5 beast2 bytes
+ */
+export declare function decodeBeast2V5ForAsync(type: EastTypeValue | EastType, options?: Beast2DecodeOptions): (data: Uint8Array) => Promise<any>;
+/**
+ * Decodes a self-describing v5 blob using its embedded root type.
+ *
+ * @param data - a v5 beast2 blob
+ * @param options - decode options (platform functions for decoded functions)
+ * @returns the blob's root type and decoded value
+ */
+export declare function decodeBeast2V5(data: Uint8Array, options?: Beast2DecodeOptions): {
+    type: EastTypeValue;
+    value: any;
+};
+/**
+ * Decodes a v5 IRType blob and returns both the IR value and the decoded
+ * source map. Backs the version-agnostic `decodeEastIR` / `decodeAsyncEastIR`.
+ *
+ * @param data - a v5 beast2 blob whose root is a Function/AsyncFunction IR
+ * @returns the decoded IR value and the blob's source map
+ */
+export declare function decodeIRWithSourceMapV5(data: Uint8Array): {
+    ir: any;
+    sourceMap: SourceMap | null;
+};
+export {};
+//# sourceMappingURL=codec.d.ts.map

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

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