solve-engine 1.0.0-beta.0 → 1.0.0-beta.2

package/dist/BytecodeBuilder-3egMyuDi.d.cts

@@ -0,0 +1,274 @@
+/**
+ * The VM's bytecode instruction set.
+ *
+ * Emitted by parselets (via {@link BytecodeBuilder}) during parsing and
+ * consumed by the VM's dispatch loop during execution. Values are grouped
+ * into numeric bands by category (0-9 stack ops, 10-19 push-literal, 20-29
+ * arithmetic, ...) purely for readability, the VM dispatches on the exact
+ * numeric value, not the band.
+ *
+ * Third-party packages emit `CALL_PLUGIN` (with a plugin-function index
+ * from {@link allocatePluginFunctionIndex}) to invoke their own logic
+ * see `IEnginePackage.pluginFunctions`. The other opcodes are used
+ * internally by the built-in packages' parselets.
+ */
+declare enum OpCode {
+    NOP = 0,
+    HALT = 1,
+    SWAP = 2,
+    DUP = 3,
+    PUSH_NUMBER = 10,
+    PUSH_BIGINT = 11,
+    PUSH_HEX = 12,
+    PUSH_STRING = 13,
+    PUSH_BOOLEAN = 14,
+    PUSH_VARIABLE = 15,
+    ADD = 20,
+    SUB = 21,
+    MUL = 22,
+    DIV = 23,
+    MOD = 24,
+    EXP = 25,
+    NEG = 26,
+    POS = 27,
+    LSHIFT = 30,
+    RSHIFT = 31,
+    URSHIFT = 32,
+    BIT_AND = 33,
+    BIT_OR = 34,
+    BIT_XOR = 35,
+    BIT_NOT = 36,
+    EQ = 40,
+    NEQ = 41,
+    LT = 42,
+    LTE = 43,
+    GT = 44,
+    GTE = 45,
+    CALL_PLUGIN = 50,// Plugin-registered functions (may be async — pre-resolved by orchestrator)
+    CALL_BUILTIN = 51,// Sync built-in functions (sqrt, sin, diceRoll, matmul)
+    RETURN = 52,// Reserved for future user-defined functions
+    LOAD_VAR = 60,
+    STORE_VAR = 61,
+    LOAD_GLOBAL_VAR = 62,// Reads from the process-wide GlobalVariableStore, not the VM's local scope
+    STORE_GLOBAL_VAR = 63,// Writes to the process-wide GlobalVariableStore, visible to every document
+    TO_NUMBER = 70,
+    TO_HEX = 71,
+    TO_PERCENTAGE = 74,
+    UOM_CONVERT = 80,
+    UOM_CONVERT_TO = 81,
+    UOM_GET_VALUE = 82,
+    UOM_BEST = 83,
+    UOM_CONVERT_IN = 84,
+    UOM_POSSIBILITIES = 85,// "sourceUnit to ?" — list units convertible from sourceUnit
+    DATE_NOW = 90,
+    DATE_ADD = 91,
+    DATE_SUB = 92,
+    DATE_NEXT_WEEKDAY = 93,// "next <Weekday>" — the next occurrence strictly after now
+    DATE_LAST_WEEKDAY = 94,// "last <Weekday>" — the previous occurrence strictly before now
+    DATE_LITERAL = 95,// Push a datetime literal whose epoch-ms was already resolved at parse time (see DateLiteralParselet)
+    RATE_DIV = 110,// Uom ÷ Uom (different measures) -> Rate — the construction op
+    RATE_MUL = 111,// Rate × Uom (same measure as denominator) -> plain Uom (denominator cancels)
+    RATE_CONVERT = 112,// Rate -> Rate with a rescaled denominator unit (keeps the same real-world rate)
+    CLOCK_TIME_TODAY = 120,// minutes-since-midnight -> Datetime anchored to today's calendar date
+    LOGICAL_AND = 130,// Boolean && Boolean -> Boolean
+    LOGICAL_OR = 131,// Boolean || Boolean -> Boolean
+    SELECT = 132,// (thenVal, elseVal, condition) -> thenVal if condition else elseVal — EAGER (both
+    TO_FRACTION = 140,// Number -> String, simplified fraction ("0.5" -> "1/2")
+    TO_MULTIPLIER = 141,// Number -> String, "1 + n" growth multiplier ("0.5" -> "1.5x")
+    TO_SCI = 142,// Number -> String, scientific notation ("1500000" -> "1.5e+6")
+    TO_BINARY = 143,// Number -> String, base-2 display ("10" -> "0b1010")
+    TO_OCTAL = 144,// Number -> String, base-8 display ("10" -> "0o12")
+    CALL_AS_CONVERTER = 145,// (value, name) -> runtime asConverterRegistry lookup + call
+    DEFINE_USER_FUNCTION = 150,// (operand = index into bytecode.userFunctionBodies) -> register name/params/program into vm.userFunctions. Registration happens at VM-EXECUTION time, not parse time, so a diagnostic/lookahead parse that compiles but never executes a definition line has no side effect on the shared registry.
+    CALL_USER_FUNCTION = 151,// (N arg values already on stack) -> pop N args, bind by NAME into a new call frame, execute the named function's stored body (reentrant executeBytecode), push its result
+    MAT_NEW = 152,// (rows, cols operands; rows*cols values already on stack, ROW-MAJOR push order) -> pop rows*cols values, transpose to column-major, push a Matrix
+    MAT_INDEX1 = 153,// (matrix, index already on stack) -> column-major single-index read `a[i]`
+    MAT_INDEX2 = 154,// (matrix, row, col already on stack) -> `a[row, col]` read
+    MAT_SLICE = 155,// (matrix, rowRange, colRange already on stack) -> sub-matrix via two Range values
+    RANGE_NEW = 156,// (min, max already on stack) -> push a Range value `min:max`
+    MAP_INVOKE = 157,// map(...) — see parser/BytecodeBuilder.ts's `anonymousBodies` side-table
+    REDUCE_INVOKE = 158
+}
+/**
+ * Gets the name of an OpCode as a string.
+ * @param op The OpCode value
+ * @returns The enum name as a string, or "UNKNOWN_<value>" if not found
+ */
+declare function getOpCodeName(op: number): string;
+
+/**
+ * Compiled bytecode program produced by {@link BytecodeBuilder}.
+ * Ready for consumption by {@link executeBytecode} without further processing.
+ */
+interface BytecodeProgram {
+    opcodes: Uint8Array;
+    numbers: Float64Array;
+    strings: string[];
+    constants?: Map<number, number>;
+    /**
+     * Whether the program contains any async opcodes (CALL_PLUGIN, etc.).
+     * Set during compilation by the BytecodeBuilder. Allows the engine
+     * to skip the O(n) resolver preflight check in O(1) for purely
+     * synchronous expressions like `2 + 2`.
+     */
+    hasAsync: boolean;
+    /**
+     * User-defined-function bodies compiled alongside this program (one
+     * entry per `name(params) = body` definition on this line). See
+     * {@link BytecodeBuilder.emitUserFunctionBody}. `OpCode.DEFINE_USER_FUNCTION`'s
+     * operand is an index into this array, resolved at VM-execution time
+     * (not parse time) so a diagnostic/lookahead parse that never actually
+     * executes the definition line has no side effect on `vm.userFunctions`.
+     */
+    userFunctionBodies?: UserFunctionDef[];
+    /**
+     * Anonymous function bodies compiled alongside this program, one entry
+     * per `map`/`reduce` inline transform expression (e.g. the `10*x` in
+     * `map(10*x, [0,1,500])`). See {@link BytecodeBuilder.emitAnonymousBody}.
+     * Deliberately a SEPARATE side-table from `userFunctionBodies`, not
+     * routed through `vm.userFunctions` at all: an inline body has no name
+     * and must never leak into the persistent name-keyed registry the way
+     * a real `f(x) = ...` definition does.
+     */
+    anonymousBodies?: AnonymousBodyDef[];
+}
+/**
+ * An anonymous transform body for `map`/`reduce`'s inline-expression form
+ * (e.g. `10*x` in `map(10*x, [0,1,500])`, or `acc+x` in `reduce(acc+x,
+ * [1,2,3])`). Structurally identical to {@link UserFunctionDef} minus the
+ * `name`. See `OpCode.MAP_INVOKE`/`REDUCE_INVOKE` and
+ * `vm/VM.ts`'s handlers, which build a call frame from `params`/`args`
+ * exactly like `CALL_USER_FUNCTION` does, just without ever registering
+ * the body in `vm.userFunctions`.
+ */
+interface AnonymousBodyDef {
+    params: string[];
+    program: BytecodeProgram;
+}
+/**
+ * A user-defined, parameterized, reusable function's compiled form
+ * (`f(x) = 2*x + 1`). See `OpCode.DEFINE_USER_FUNCTION`/`CALL_USER_FUNCTION`
+ * and `vm/VM.ts`'s `VM.defineUserFunction`/`getUserFunction`.
+ *
+ * `program` is the body compiled to its OWN independent `BytecodeProgram`,
+ * not a fragment of the definition line's own bytecode. Parameter names
+ * inside the body compile to ORDINARY `LOAD_VAR <name>` opcodes, no
+ * parse-time rewriting, because parameter resolution happens dynamically
+ * at the VM level: `CALL_USER_FUNCTION` pushes a name-keyed call frame
+ * (`Map<string, Value>`) before re-executing `program`, and `VM.getVar()`
+ * checks the innermost call frame before falling back to the flat
+ * document-variable store. This is why a `UNIT`-collision parameter name
+ * (e.g. `h` in `area(w, h) = w * h`, which lexes as the "hour" unit) needs
+ * no special handling anywhere, it's just another `LOAD_VAR "h"`, resolved
+ * the same way as any other name.
+ */
+interface UserFunctionDef {
+    name: string;
+    params: string[];
+    program: BytecodeProgram;
+}
+/**
+ * Direct-to-bytecode compiler for the Pratt parser.
+ *
+ * Accumulates opcodes, numeric constants, and string references during parsing,
+ * then produces a {@link BytecodeProgram} for VM execution. Supports:
+ * - Standard build via {@link build}
+ * - Zero-copy build into pre-allocated buffers via {@link buildInto}
+ * - In-place reset for reuse without reallocation
+ */
+declare class BytecodeBuilder {
+    private opcodes;
+    private numbers;
+    private strings;
+    private stringIndex;
+    private _hasAsync;
+    private userFunctionBodies;
+    private anonymousBodies;
+    /** Emit an {@link OpCode} instruction. */
+    emitOpcode(op: OpCode): void;
+    /**
+     * Emit a numeric literal: appends `n` to the program's constant pool and
+     * writes its index into the opcode stream (read back by the VM as e.g.
+     * `PUSH_NUMBER <idx>`).
+     *
+     * Numeric constants are NOT deduplicated (unlike {@link emitString})
+     * every call appends a new entry, so an expression with more than
+     * {@link MAX_CONSTANT_POOL_INDEX}+1 distinct numeric-literal occurrences
+     * throws rather than silently wrapping the index (see
+     * `MAX_CONSTANT_POOL_INDEX`'s doc for what that would otherwise do).
+     *
+     * @throws If the constant pool would exceed 256 entries.
+     */
+    emitNumber(n: number): void;
+    /**
+     * Emit a string literal: interns `s` into the program's string pool
+     * (deduplicated via `stringIndex`) and writes its index into the opcode
+     * stream. Subject to the same constant-pool bound as {@link emitNumber},
+     * but since strings ARE deduplicated, only distinct string values count
+     * against the limit.
+     *
+     * @throws If the string pool would exceed 256 distinct entries.
+     */
+    emitString(s: string): void;
+    /**
+     * Emit a raw numeric operand (0-255) following an opcode, e.g. a
+     * plugin-function index for `CALL_PLUGIN`, or an argument count. Unlike
+     * {@link emitOpcode}, this does not go through the `OpCode` enum, so
+     * package authors use this (not an unsafe cast to `OpCode`) to push
+     * operands their own opcode handler expects to read positionally.
+     */
+    emitIndex(idx: number): void;
+    /** Emit a raw byte (0-255), used for fixed small operands like argument counts. */
+    emitByte(b: number): void;
+    /** Number of opcodes/operands emitted so far, used to compute jump targets before {@link patchJump}. */
+    get currentLength(): number;
+    /**
+     * Register a compiled user-defined-function body, returning its index
+     * into this program's `userFunctionBodies` side-table, the caller emits
+     * that index as `DEFINE_USER_FUNCTION`'s operand via {@link emitIndex}.
+     * Subject to the same {@link MAX_CONSTANT_POOL_INDEX} bound as
+     * {@link emitNumber}/{@link emitString} (the index itself is a single
+     * opcode-stream byte), in practice a single line defines at most a
+     * handful of functions, so this limit is never realistically reached.
+     *
+     * @throws If more than 256 function bodies are registered on one program.
+     */
+    emitUserFunctionBody(name: string, params: string[], program: BytecodeProgram): number;
+    /**
+     * Register a compiled `map`/`reduce` anonymous transform body, returning
+     * its index into this program's `anonymousBodies` side-table, the
+     * caller emits that index as `MAP_INVOKE`/`REDUCE_INVOKE`'s operand via
+     * {@link emitIndex}. Same {@link MAX_CONSTANT_POOL_INDEX} bound as
+     * {@link emitUserFunctionBody}.
+     *
+     * @throws If more than 256 anonymous bodies are registered on one program.
+     */
+    emitAnonymousBody(params: string[], program: BytecodeProgram): number;
+    /** Overwrite a previously-emitted placeholder operand at `position` with the real jump `target`, once known. */
+    patchJump(position: number, target: number): void;
+    /**
+     * Build the accumulated opcodes/numbers/strings into a BytecodeProgram.
+     * Creates new TypedArrays, the builder can be reused after this call.
+     */
+    build(): BytecodeProgram;
+    /**
+     * Build directly into a pre-allocated buffer for zero-copy VM consumption.
+     *
+     * When `buf` is provided and large enough, writes into it and returns
+     * subarray **views** (not copies), the returned TypedArrays share the
+     * buffer's underlying ArrayBuffer. The caller MUST NOT mutate the buffer
+     * until the returned BytecodeProgram is no longer needed.
+     *
+     * If the caller intends to cache the result, they must copy the TypedArrays
+     * (e.g. `new Uint8Array(program.opcodes)`) before reusing the buffer pool.
+     *
+     * When `buf` is omitted or too small, allocates fresh TypedArrays.
+     */
+    buildInto(buf?: {
+        opcodes: Uint8Array;
+        numbers: Float64Array;
+    }): BytecodeProgram;
+    reset(): void;
+}
+
+export { type AnonymousBodyDef as A, BytecodeBuilder as B, OpCode as O, type UserFunctionDef as U, type BytecodeProgram as a, getOpCodeName as g };

package/dist/BytecodeBuilder-3egMyuDi.d.ts

@@ -0,0 +1,274 @@
+/**
+ * The VM's bytecode instruction set.
+ *
+ * Emitted by parselets (via {@link BytecodeBuilder}) during parsing and
+ * consumed by the VM's dispatch loop during execution. Values are grouped
+ * into numeric bands by category (0-9 stack ops, 10-19 push-literal, 20-29
+ * arithmetic, ...) purely for readability, the VM dispatches on the exact
+ * numeric value, not the band.
+ *
+ * Third-party packages emit `CALL_PLUGIN` (with a plugin-function index
+ * from {@link allocatePluginFunctionIndex}) to invoke their own logic
+ * see `IEnginePackage.pluginFunctions`. The other opcodes are used
+ * internally by the built-in packages' parselets.
+ */
+declare enum OpCode {
+    NOP = 0,
+    HALT = 1,
+    SWAP = 2,
+    DUP = 3,
+    PUSH_NUMBER = 10,
+    PUSH_BIGINT = 11,
+    PUSH_HEX = 12,
+    PUSH_STRING = 13,
+    PUSH_BOOLEAN = 14,
+    PUSH_VARIABLE = 15,
+    ADD = 20,
+    SUB = 21,
+    MUL = 22,
+    DIV = 23,
+    MOD = 24,
+    EXP = 25,
+    NEG = 26,
+    POS = 27,
+    LSHIFT = 30,
+    RSHIFT = 31,
+    URSHIFT = 32,
+    BIT_AND = 33,
+    BIT_OR = 34,
+    BIT_XOR = 35,
+    BIT_NOT = 36,
+    EQ = 40,
+    NEQ = 41,
+    LT = 42,
+    LTE = 43,
+    GT = 44,
+    GTE = 45,
+    CALL_PLUGIN = 50,// Plugin-registered functions (may be async — pre-resolved by orchestrator)
+    CALL_BUILTIN = 51,// Sync built-in functions (sqrt, sin, diceRoll, matmul)
+    RETURN = 52,// Reserved for future user-defined functions
+    LOAD_VAR = 60,
+    STORE_VAR = 61,
+    LOAD_GLOBAL_VAR = 62,// Reads from the process-wide GlobalVariableStore, not the VM's local scope
+    STORE_GLOBAL_VAR = 63,// Writes to the process-wide GlobalVariableStore, visible to every document
+    TO_NUMBER = 70,
+    TO_HEX = 71,
+    TO_PERCENTAGE = 74,
+    UOM_CONVERT = 80,
+    UOM_CONVERT_TO = 81,
+    UOM_GET_VALUE = 82,
+    UOM_BEST = 83,
+    UOM_CONVERT_IN = 84,
+    UOM_POSSIBILITIES = 85,// "sourceUnit to ?" — list units convertible from sourceUnit
+    DATE_NOW = 90,
+    DATE_ADD = 91,
+    DATE_SUB = 92,
+    DATE_NEXT_WEEKDAY = 93,// "next <Weekday>" — the next occurrence strictly after now
+    DATE_LAST_WEEKDAY = 94,// "last <Weekday>" — the previous occurrence strictly before now
+    DATE_LITERAL = 95,// Push a datetime literal whose epoch-ms was already resolved at parse time (see DateLiteralParselet)
+    RATE_DIV = 110,// Uom ÷ Uom (different measures) -> Rate — the construction op
+    RATE_MUL = 111,// Rate × Uom (same measure as denominator) -> plain Uom (denominator cancels)
+    RATE_CONVERT = 112,// Rate -> Rate with a rescaled denominator unit (keeps the same real-world rate)
+    CLOCK_TIME_TODAY = 120,// minutes-since-midnight -> Datetime anchored to today's calendar date
+    LOGICAL_AND = 130,// Boolean && Boolean -> Boolean
+    LOGICAL_OR = 131,// Boolean || Boolean -> Boolean
+    SELECT = 132,// (thenVal, elseVal, condition) -> thenVal if condition else elseVal — EAGER (both
+    TO_FRACTION = 140,// Number -> String, simplified fraction ("0.5" -> "1/2")
+    TO_MULTIPLIER = 141,// Number -> String, "1 + n" growth multiplier ("0.5" -> "1.5x")
+    TO_SCI = 142,// Number -> String, scientific notation ("1500000" -> "1.5e+6")
+    TO_BINARY = 143,// Number -> String, base-2 display ("10" -> "0b1010")
+    TO_OCTAL = 144,// Number -> String, base-8 display ("10" -> "0o12")
+    CALL_AS_CONVERTER = 145,// (value, name) -> runtime asConverterRegistry lookup + call
+    DEFINE_USER_FUNCTION = 150,// (operand = index into bytecode.userFunctionBodies) -> register name/params/program into vm.userFunctions. Registration happens at VM-EXECUTION time, not parse time, so a diagnostic/lookahead parse that compiles but never executes a definition line has no side effect on the shared registry.
+    CALL_USER_FUNCTION = 151,// (N arg values already on stack) -> pop N args, bind by NAME into a new call frame, execute the named function's stored body (reentrant executeBytecode), push its result
+    MAT_NEW = 152,// (rows, cols operands; rows*cols values already on stack, ROW-MAJOR push order) -> pop rows*cols values, transpose to column-major, push a Matrix
+    MAT_INDEX1 = 153,// (matrix, index already on stack) -> column-major single-index read `a[i]`
+    MAT_INDEX2 = 154,// (matrix, row, col already on stack) -> `a[row, col]` read
+    MAT_SLICE = 155,// (matrix, rowRange, colRange already on stack) -> sub-matrix via two Range values
+    RANGE_NEW = 156,// (min, max already on stack) -> push a Range value `min:max`
+    MAP_INVOKE = 157,// map(...) — see parser/BytecodeBuilder.ts's `anonymousBodies` side-table
+    REDUCE_INVOKE = 158
+}
+/**
+ * Gets the name of an OpCode as a string.
+ * @param op The OpCode value
+ * @returns The enum name as a string, or "UNKNOWN_<value>" if not found
+ */
+declare function getOpCodeName(op: number): string;
+
+/**
+ * Compiled bytecode program produced by {@link BytecodeBuilder}.
+ * Ready for consumption by {@link executeBytecode} without further processing.
+ */
+interface BytecodeProgram {
+    opcodes: Uint8Array;
+    numbers: Float64Array;
+    strings: string[];
+    constants?: Map<number, number>;
+    /**
+     * Whether the program contains any async opcodes (CALL_PLUGIN, etc.).
+     * Set during compilation by the BytecodeBuilder. Allows the engine
+     * to skip the O(n) resolver preflight check in O(1) for purely
+     * synchronous expressions like `2 + 2`.
+     */
+    hasAsync: boolean;
+    /**
+     * User-defined-function bodies compiled alongside this program (one
+     * entry per `name(params) = body` definition on this line). See
+     * {@link BytecodeBuilder.emitUserFunctionBody}. `OpCode.DEFINE_USER_FUNCTION`'s
+     * operand is an index into this array, resolved at VM-execution time
+     * (not parse time) so a diagnostic/lookahead parse that never actually
+     * executes the definition line has no side effect on `vm.userFunctions`.
+     */
+    userFunctionBodies?: UserFunctionDef[];
+    /**
+     * Anonymous function bodies compiled alongside this program, one entry
+     * per `map`/`reduce` inline transform expression (e.g. the `10*x` in
+     * `map(10*x, [0,1,500])`). See {@link BytecodeBuilder.emitAnonymousBody}.
+     * Deliberately a SEPARATE side-table from `userFunctionBodies`, not
+     * routed through `vm.userFunctions` at all: an inline body has no name
+     * and must never leak into the persistent name-keyed registry the way
+     * a real `f(x) = ...` definition does.
+     */
+    anonymousBodies?: AnonymousBodyDef[];
+}
+/**
+ * An anonymous transform body for `map`/`reduce`'s inline-expression form
+ * (e.g. `10*x` in `map(10*x, [0,1,500])`, or `acc+x` in `reduce(acc+x,
+ * [1,2,3])`). Structurally identical to {@link UserFunctionDef} minus the
+ * `name`. See `OpCode.MAP_INVOKE`/`REDUCE_INVOKE` and
+ * `vm/VM.ts`'s handlers, which build a call frame from `params`/`args`
+ * exactly like `CALL_USER_FUNCTION` does, just without ever registering
+ * the body in `vm.userFunctions`.
+ */
+interface AnonymousBodyDef {
+    params: string[];
+    program: BytecodeProgram;
+}
+/**
+ * A user-defined, parameterized, reusable function's compiled form
+ * (`f(x) = 2*x + 1`). See `OpCode.DEFINE_USER_FUNCTION`/`CALL_USER_FUNCTION`
+ * and `vm/VM.ts`'s `VM.defineUserFunction`/`getUserFunction`.
+ *
+ * `program` is the body compiled to its OWN independent `BytecodeProgram`,
+ * not a fragment of the definition line's own bytecode. Parameter names
+ * inside the body compile to ORDINARY `LOAD_VAR <name>` opcodes, no
+ * parse-time rewriting, because parameter resolution happens dynamically
+ * at the VM level: `CALL_USER_FUNCTION` pushes a name-keyed call frame
+ * (`Map<string, Value>`) before re-executing `program`, and `VM.getVar()`
+ * checks the innermost call frame before falling back to the flat
+ * document-variable store. This is why a `UNIT`-collision parameter name
+ * (e.g. `h` in `area(w, h) = w * h`, which lexes as the "hour" unit) needs
+ * no special handling anywhere, it's just another `LOAD_VAR "h"`, resolved
+ * the same way as any other name.
+ */
+interface UserFunctionDef {
+    name: string;
+    params: string[];
+    program: BytecodeProgram;
+}
+/**
+ * Direct-to-bytecode compiler for the Pratt parser.
+ *
+ * Accumulates opcodes, numeric constants, and string references during parsing,
+ * then produces a {@link BytecodeProgram} for VM execution. Supports:
+ * - Standard build via {@link build}
+ * - Zero-copy build into pre-allocated buffers via {@link buildInto}
+ * - In-place reset for reuse without reallocation
+ */
+declare class BytecodeBuilder {
+    private opcodes;
+    private numbers;
+    private strings;
+    private stringIndex;
+    private _hasAsync;
+    private userFunctionBodies;
+    private anonymousBodies;
+    /** Emit an {@link OpCode} instruction. */
+    emitOpcode(op: OpCode): void;
+    /**
+     * Emit a numeric literal: appends `n` to the program's constant pool and
+     * writes its index into the opcode stream (read back by the VM as e.g.
+     * `PUSH_NUMBER <idx>`).
+     *
+     * Numeric constants are NOT deduplicated (unlike {@link emitString})
+     * every call appends a new entry, so an expression with more than
+     * {@link MAX_CONSTANT_POOL_INDEX}+1 distinct numeric-literal occurrences
+     * throws rather than silently wrapping the index (see
+     * `MAX_CONSTANT_POOL_INDEX`'s doc for what that would otherwise do).
+     *
+     * @throws If the constant pool would exceed 256 entries.
+     */
+    emitNumber(n: number): void;
+    /**
+     * Emit a string literal: interns `s` into the program's string pool
+     * (deduplicated via `stringIndex`) and writes its index into the opcode
+     * stream. Subject to the same constant-pool bound as {@link emitNumber},
+     * but since strings ARE deduplicated, only distinct string values count
+     * against the limit.
+     *
+     * @throws If the string pool would exceed 256 distinct entries.
+     */
+    emitString(s: string): void;
+    /**
+     * Emit a raw numeric operand (0-255) following an opcode, e.g. a
+     * plugin-function index for `CALL_PLUGIN`, or an argument count. Unlike
+     * {@link emitOpcode}, this does not go through the `OpCode` enum, so
+     * package authors use this (not an unsafe cast to `OpCode`) to push
+     * operands their own opcode handler expects to read positionally.
+     */
+    emitIndex(idx: number): void;
+    /** Emit a raw byte (0-255), used for fixed small operands like argument counts. */
+    emitByte(b: number): void;
+    /** Number of opcodes/operands emitted so far, used to compute jump targets before {@link patchJump}. */
+    get currentLength(): number;
+    /**
+     * Register a compiled user-defined-function body, returning its index
+     * into this program's `userFunctionBodies` side-table, the caller emits
+     * that index as `DEFINE_USER_FUNCTION`'s operand via {@link emitIndex}.
+     * Subject to the same {@link MAX_CONSTANT_POOL_INDEX} bound as
+     * {@link emitNumber}/{@link emitString} (the index itself is a single
+     * opcode-stream byte), in practice a single line defines at most a
+     * handful of functions, so this limit is never realistically reached.
+     *
+     * @throws If more than 256 function bodies are registered on one program.
+     */
+    emitUserFunctionBody(name: string, params: string[], program: BytecodeProgram): number;
+    /**
+     * Register a compiled `map`/`reduce` anonymous transform body, returning
+     * its index into this program's `anonymousBodies` side-table, the
+     * caller emits that index as `MAP_INVOKE`/`REDUCE_INVOKE`'s operand via
+     * {@link emitIndex}. Same {@link MAX_CONSTANT_POOL_INDEX} bound as
+     * {@link emitUserFunctionBody}.
+     *
+     * @throws If more than 256 anonymous bodies are registered on one program.
+     */
+    emitAnonymousBody(params: string[], program: BytecodeProgram): number;
+    /** Overwrite a previously-emitted placeholder operand at `position` with the real jump `target`, once known. */
+    patchJump(position: number, target: number): void;
+    /**
+     * Build the accumulated opcodes/numbers/strings into a BytecodeProgram.
+     * Creates new TypedArrays, the builder can be reused after this call.
+     */
+    build(): BytecodeProgram;
+    /**
+     * Build directly into a pre-allocated buffer for zero-copy VM consumption.
+     *
+     * When `buf` is provided and large enough, writes into it and returns
+     * subarray **views** (not copies), the returned TypedArrays share the
+     * buffer's underlying ArrayBuffer. The caller MUST NOT mutate the buffer
+     * until the returned BytecodeProgram is no longer needed.
+     *
+     * If the caller intends to cache the result, they must copy the TypedArrays
+     * (e.g. `new Uint8Array(program.opcodes)`) before reusing the buffer pool.
+     *
+     * When `buf` is omitted or too small, allocates fresh TypedArrays.
+     */
+    buildInto(buf?: {
+        opcodes: Uint8Array;
+        numbers: Float64Array;
+    }): BytecodeProgram;
+    reset(): void;
+}
+
+export { type AnonymousBodyDef as A, BytecodeBuilder as B, OpCode as O, type UserFunctionDef as U, type BytecodeProgram as a, getOpCodeName as g };