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

package/dist/Parselet-CK8cQu2a.d.cts

@@ -0,0 +1,299 @@
+import { B as BytecodeBuilder } from './BytecodeBuilder-3egMyuDi.cjs';
+import { T as Token } from './Token-0jpvUdPY.cjs';
+import { D as DiagnosticPipeline } from './pipeline-DPUQt7yL.cjs';
+
+/**
+ * Dual-keyed ParseletRegistry, accepts both string token types and
+ * integer token type IDs for fast dispatch in the Parser hot path.
+ *
+ * Providers call registerPrefix("NUMBER", ...) with string token types.
+ * Internally, we populate both string-keyed and integer-keyed maps so
+ * Parser.parseExpression() can use token.typeId (integer) for lookup
+ * while diagnostics and error messages use token.type (string).
+ *
+ * Performance: Integer Map.get() avoids string hashing, saving ~2-5ns
+ * per dispatch. With ~10-15 dispatches per expression, that's ~20-75ns.
+ */
+declare class ParseletRegistry {
+    private prefixParselets;
+    private infixParselets;
+    private prefixById;
+    private infixById;
+    /**
+     * Register a prefix parselet for `tokenType`.
+     *
+     * If another parselet is already registered for this token type, it is
+     * silently overwritten by default (`Map.set()` semantics), the old
+     * parselet is simply unreachable from then on, with no error. This is
+     * a real footgun for third-party packages: two packages independently
+     * choosing the same custom token type will collide with zero signal
+     * about which one "won". Mirrors ResolverRegistry.register()'s and
+     * ExpressionEngine.registerPackage()'s existing "warn and replace"
+     * pattern for the same class of problem at the resolver-namespace and
+     * package-name levels.
+     *
+     * Note: this warns about registry-level collisions only. It does NOT
+     * detect the separate case where `tokenType` is one of PrecedenceParser's
+     * Tier-1 fast-path token types (NUMBER, STRING, IDENT, LPAREN, MINUS,
+     * PLUS, and the Tier-1 infix operators), those are deliberately kept
+     * registered here for introspection/diagnostics even though Tier-1
+     * always intercepts them before this registry is consulted (see
+     * PrecedenceParser.parsePrefix()'s docs), so warning there would
+     * misfire on that intentional, already-documented pattern.
+     */
+    registerPrefix(tokenType: string, parselet: PrefixParselet): void;
+    /** Register an infix parselet for `tokenType`. See {@link registerPrefix} for the collision-warning behavior this mirrors. */
+    registerInfix(tokenType: string, parselet: InfixParselet): void;
+    /** Iterate all registered prefix parselets for diagnostic display. */
+    getAllPrefix(): Array<{
+        tokenType: string;
+        bindingPower: number;
+        category?: string;
+    }>;
+    /** Iterate all registered infix parselets for diagnostic display. */
+    getAllInfix(): Array<{
+        tokenType: string;
+        leftBindingPower: number;
+        rightBindingPower: number;
+        category?: string;
+    }>;
+    /** Number of registered prefix parselets. */
+    get prefixCount(): number;
+    /** Number of registered infix parselets. */
+    get infixCount(): number;
+    /**
+     * Get prefix parselet by string token type OR integer typeId.
+     * Fast path for integer IDs (Parser hot path), fallback for strings
+     * (diagnostics, error messages, backwards compatibility).
+     */
+    getPrefix(tokenType: string | number): PrefixParselet | undefined;
+    /**
+     * Get infix parselet by string token type OR integer typeId.
+     * Fast path for integer IDs (Parser hot path), fallback for strings.
+     */
+    getInfix(tokenType: string | number): InfixParselet | undefined;
+    hasPrefix(tokenType: string): boolean;
+    hasInfix(tokenType: string): boolean;
+    clear(): void;
+}
+/**
+ * A process-wide parselet registry.
+ *
+ * @deprecated An engine builds its own registry and does not read this one, so
+ * registering here reaches nothing that evaluates. It survives for the
+ * deprecated {@link PackageRegistry} path only.
+ */
+declare const sharedParseletRegistry: ParseletRegistry;
+
+/**
+ * ── Hybrid Precedence Climbing Parser ─────────────────────────────────────────
+ *
+ * Two-tier dispatch strategy:
+ *
+ *   Tier 1 (Fast Path): Inline switch on token.typeId for built-in operators.
+ *     - Prefix: NUMBER, IDENT, LPAREN, MINUS, PLUS, STRING
+ *     - Infix:  checked via static BP_TABLE (Uint8Array indexed by typeId)
+ *     - No Map.get(), no parselet function call overhead for ~95% of tokens
+ *
+ *   Tier 2 (Plugin Path): ParseletRegistry fallback for custom/plugin tokens.
+ *     - Prefix: Map.get(tokenTypeId) for PrefixParselet
+ *     - Infix:  Map.get(tokenTypeId) for InfixParselet
+ *     - Full flexibility for custom syntax
+ *
+ * The parser emits directly to a BytecodeBuilder, no AST intermediate.
+ * Implements the same public API as the legacy Parser class so existing
+ * parselets continue to work without modification.
+ */
+declare class PrecedenceParser {
+    private tokens;
+    private current;
+    private depth;
+    private maxDepth;
+    /** Cached registry reference, avoids property chain in hot loop */
+    private registry;
+    /** BytecodeBuilder, set before each parseExpression call */
+    private builder;
+    /** Diagnostic pipeline for parselet-matched events */
+    private diagnosticPipeline;
+    private currentExpression;
+    private localeCode;
+    /**
+     * Static binding power table, built once at module load, shared across all instances.
+     * Index = tokenTypeId, value = binding power (0 = not a built-in infix).
+     */
+    static readonly BP_TABLE: Uint8Array;
+    private static readonly NUMBER_ID;
+    private static readonly BIGINT_ID;
+    private static readonly STRING_ID;
+    private static readonly IDENT_ID;
+    private static readonly LPAREN_ID;
+    private static readonly RPAREN_ID;
+    private static readonly MINUS_ID;
+    private static readonly PLUS_ID;
+    private static readonly KEYWORD_ID;
+    private static readonly STAR_ID;
+    private static readonly SLASH_ID;
+    private static readonly MOD_ID;
+    private static readonly CARET_ID;
+    private static readonly LSHIFT_ID;
+    private static readonly RSHIFT_ID;
+    private static readonly BIT_AND_ID;
+    private static readonly BIT_OR_ID;
+    private static readonly BIT_XOR_ID;
+    private static readonly PERCENT_ID;
+    private static readonly OF_ID;
+    /**
+     * Inline opcode map for Tier 1 infix operators.
+     * tokenTypeId → OpCode. PERCENT and CARET are handled specially (not in this map).
+     */
+    private static readonly INFIX_OPCODE;
+    constructor(parseletRegistry: ParseletRegistry, maxDepth?: number, localeCode?: string);
+    /** Get locale code for NumberParselet to normalize separators */
+    getLocaleCode(): string;
+    /**
+     * Set the diagnostic pipeline for parselet matching events.
+     * Cleared after each non-cached parse to avoid holding refs.
+     */
+    setDiagnosticPipeline(pipeline: DiagnosticPipeline | undefined, expression: string): void;
+    /**
+     * Load tokens for parsing. Identical to Parser.load().
+     *
+     * @param hasParens - if false, skips the O(n) paren balance scan (~90% of expressions)
+     */
+    load(tokens: Token[], hasParens?: boolean): void;
+    /**
+     * Auto-balance unmatched parentheses.
+     */
+    private balanceParens;
+    /**
+     * Parse a full expression starting at the current token position.
+     *
+     * @param minBp - minimum binding power (precedence climbing threshold).
+     *   For left-associative operators, the recursive call uses `bp + 1`.
+     *   For right-associative operators (^), it uses `bp`.
+     * @param _builder - accepted for parselet API compatibility; always uses `this.builder`.
+     */
+    parseExpression(minBp?: number, _builder?: BytecodeBuilder): void;
+    /**
+     * Parse a prefix token. Built-in tokens (NUMBER, IDENT, LPAREN, etc.) are
+     * handled inline with zero registry lookup. Everything else falls through
+     * to the parselet registry (Tier 2).
+     */
+    private parsePrefix;
+    /**
+     * A single `^`-suffix shape: `matches` peeks ahead (consuming nothing) to
+     * check whether this shape starts at the current position; `emit` is only
+     * called immediately after `matches` returned true for that SAME position,
+     * and is responsible for consuming that shape's own trailing tokens and
+     * emitting its bytecode.
+     */
+    private static readonly CARET_SUFFIX_RULES;
+    /**
+     * After a `^` token (already consumed by the Tier-1 infix loop above),
+     * checks {@link CARET_SUFFIX_RULES} in order for a shape that means
+     * something other than ordinary exponentiation: `^T` (transpose) and `^-1`
+     * (matrix inverse, LITERALLY the integer exponent `-1`; `^-2`, `^-1.5`
+     * etc. still mean ordinary exponentiation). On a match, the rule's `emit`
+     * consumes that shape's own tokens and this returns `true`. On no match,
+     * consumes NOTHING, returning `false` so the caller falls through to
+     * ordinary `EXP` parsing.
+     *
+     * Every rule dispatches purely on SHAPE, never on operand type (unknowable
+     * at parse time): `inv()`'s own handler (`VMBuiltins.ts` index 65) returns
+     * `1/x` for a plain Number, byte-identical to what `Math.pow(x, -1)`
+     * already computed for `x^-1` before this feature existed, and a real
+     * matrix inverse for a Matrix, so `5^-1` still means exactly what it always
+     * has; only a Matrix operand actually inverts.
+     *
+     * Adding a future `^`-suffix shape is a new table entry here, not a new
+     * if-block. See the "Tier-1 shape-exception" pattern write-up above for
+     * why this table can't instead be a package-registered parselet.
+     */
+    private tryEmitMatrixCaretOp;
+    /**
+     * From an LPAREN token index, scan forward tracking paren depth and
+     * return the index of the matching RPAREN, or `null` if the parens never
+     * balance before the token stream ends. No emission, no position
+     * advance. Same class of technique as {@link balanceParens}'s own
+     * pre-scan, just exposed mid-parse instead of only at `load()` time.
+     * `openIdx` must point AT the LPAREN itself.
+     */
+    private findMatchingRParen;
+    /**
+     * Disambiguates a bare `IDENT` immediately followed by `(` between three
+     * things, using ONLY a bracket-depth scan (no backtracking, nothing is
+     * consumed until the shape is known):
+     * - `f(x) = expr`, a DEFINITION: the matching `)` is followed by `=`.
+     * - `f(5)`, a CALL to a (possibly not-yet-defined) function: anything
+     *   else. This was never valid syntax before this feature (a bare
+     *   `IDENT` immediately before `(` has no pre-existing "plain variable
+     *   read + separately grouped `(...)`" meaning to preserve, confirmed
+     *   via `BuiltinNormalizerRules.ts`'s `implicitMultiplyRule()`, which
+     *   only inserts an implicit `*` for `NUMBER/RPAREN` immediately before
+     *   `IDENT/LPAREN`, never for a bare `IDENT` immediately before
+     *   `LPAREN`). Always commits to a CALL; an unregistered name produces a
+     *   clear `UNDEFINED_FUNCTION` error at VM-execution time, the same
+     *   forward-reference philosophy `LOAD_VAR`/`UNDEFINED_VARIABLE` already
+     *   uses, rather than any parse-time registry lookup.
+     * If the parens never balance, this falls through to the ordinary
+     * `LOAD_VAR` path (a malformed expression surfaces its own parse error
+     * shortly after, from the normal expression grammar).
+     */
+    private parseUserFunctionDefOrCall;
+    /**
+     * A parameter name, accepted as either `IDENT` or `UNIT`, matches this
+     * codebase's established `:name = value` variable-name policy
+     * (`VariableParselet.ts` explicitly accepts `UNIT`-typed tokens too, e.g.
+     * `:b = 5` for the "b" bits unit) since common short parameter names
+     * like `h`/`l`/`b`/`t`/`s`/`m` collide with real unit abbreviations
+     * (hour, liter, bits, ton, second, meter, ...) and lex as `UNIT`, not
+     * `IDENT`.
+     */
+    private consumeParamName;
+    private parseUserFunctionDefinition;
+    private parseUserFunctionCall;
+    consume(expectedType?: string): Token;
+    match(expectedType: string): boolean;
+    peek(): Token | undefined;
+    /**
+     * Read-only lookahead `offset` tokens past the current position, without
+     * consuming anything, `peekAt(0)` is equivalent to {@link peek}.
+     * `this.tokens` is a plain in-memory array (not a stream), so this is a
+     * simple, safe index read; no rewind/checkpoint mechanism is needed since
+     * nothing is consumed.
+     */
+    peekAt(offset: number): Token | undefined;
+    previous(): Token | undefined;
+    private advance;
+    /** Set the builder to use for the current parse. Called by ExpressionEngine. */
+    setBuilder(builder: BytecodeBuilder): void;
+    private fireParseletMatched;
+}
+
+/**
+ * Handles a token appearing where a value is expected.
+ *
+ * A literal, a prefix operator such as unary minus, or a function name. The
+ * parser calls this when the token opens an expression rather than continuing
+ * one.
+ */
+interface PrefixParselet {
+    /** Diagnostic category for this parselet (e.g. "Arithmetic", "Function", "Variable") */
+    readonly category: string;
+    parse(parser: PrecedenceParser, token: Token, builder: BytecodeBuilder): void;
+}
+/**
+ * Handles a token appearing after a value.
+ *
+ * A binary operator, or anything else that continues an expression already in
+ * progress. Its binding power decides how tightly it binds against neighbours.
+ */
+interface InfixParselet {
+    /** Diagnostic category for this parselet (e.g. "Arithmetic", "UoM") */
+    readonly category: string;
+    /** Binding power (precedence), property access avoids vtable dispatch in hot loop */
+    readonly bindingPower: number;
+    parse(parser: PrecedenceParser, left: Token, token: Token, builder: BytecodeBuilder): void;
+}
+
+export { type InfixParselet as I, ParseletRegistry as P, PrecedenceParser as a, type PrefixParselet as b, sharedParseletRegistry as s };

package/dist/Parselet-ConOIdRO.d.ts

@@ -0,0 +1,299 @@
+import { B as BytecodeBuilder } from './BytecodeBuilder-3egMyuDi.js';
+import { T as Token } from './Token-0jpvUdPY.js';
+import { D as DiagnosticPipeline } from './pipeline-CrsRPmsv.js';
+
+/**
+ * Dual-keyed ParseletRegistry, accepts both string token types and
+ * integer token type IDs for fast dispatch in the Parser hot path.
+ *
+ * Providers call registerPrefix("NUMBER", ...) with string token types.
+ * Internally, we populate both string-keyed and integer-keyed maps so
+ * Parser.parseExpression() can use token.typeId (integer) for lookup
+ * while diagnostics and error messages use token.type (string).
+ *
+ * Performance: Integer Map.get() avoids string hashing, saving ~2-5ns
+ * per dispatch. With ~10-15 dispatches per expression, that's ~20-75ns.
+ */
+declare class ParseletRegistry {
+    private prefixParselets;
+    private infixParselets;
+    private prefixById;
+    private infixById;
+    /**
+     * Register a prefix parselet for `tokenType`.
+     *
+     * If another parselet is already registered for this token type, it is
+     * silently overwritten by default (`Map.set()` semantics), the old
+     * parselet is simply unreachable from then on, with no error. This is
+     * a real footgun for third-party packages: two packages independently
+     * choosing the same custom token type will collide with zero signal
+     * about which one "won". Mirrors ResolverRegistry.register()'s and
+     * ExpressionEngine.registerPackage()'s existing "warn and replace"
+     * pattern for the same class of problem at the resolver-namespace and
+     * package-name levels.
+     *
+     * Note: this warns about registry-level collisions only. It does NOT
+     * detect the separate case where `tokenType` is one of PrecedenceParser's
+     * Tier-1 fast-path token types (NUMBER, STRING, IDENT, LPAREN, MINUS,
+     * PLUS, and the Tier-1 infix operators), those are deliberately kept
+     * registered here for introspection/diagnostics even though Tier-1
+     * always intercepts them before this registry is consulted (see
+     * PrecedenceParser.parsePrefix()'s docs), so warning there would
+     * misfire on that intentional, already-documented pattern.
+     */
+    registerPrefix(tokenType: string, parselet: PrefixParselet): void;
+    /** Register an infix parselet for `tokenType`. See {@link registerPrefix} for the collision-warning behavior this mirrors. */
+    registerInfix(tokenType: string, parselet: InfixParselet): void;
+    /** Iterate all registered prefix parselets for diagnostic display. */
+    getAllPrefix(): Array<{
+        tokenType: string;
+        bindingPower: number;
+        category?: string;
+    }>;
+    /** Iterate all registered infix parselets for diagnostic display. */
+    getAllInfix(): Array<{
+        tokenType: string;
+        leftBindingPower: number;
+        rightBindingPower: number;
+        category?: string;
+    }>;
+    /** Number of registered prefix parselets. */
+    get prefixCount(): number;
+    /** Number of registered infix parselets. */
+    get infixCount(): number;
+    /**
+     * Get prefix parselet by string token type OR integer typeId.
+     * Fast path for integer IDs (Parser hot path), fallback for strings
+     * (diagnostics, error messages, backwards compatibility).
+     */
+    getPrefix(tokenType: string | number): PrefixParselet | undefined;
+    /**
+     * Get infix parselet by string token type OR integer typeId.
+     * Fast path for integer IDs (Parser hot path), fallback for strings.
+     */
+    getInfix(tokenType: string | number): InfixParselet | undefined;
+    hasPrefix(tokenType: string): boolean;
+    hasInfix(tokenType: string): boolean;
+    clear(): void;
+}
+/**
+ * A process-wide parselet registry.
+ *
+ * @deprecated An engine builds its own registry and does not read this one, so
+ * registering here reaches nothing that evaluates. It survives for the
+ * deprecated {@link PackageRegistry} path only.
+ */
+declare const sharedParseletRegistry: ParseletRegistry;
+
+/**
+ * ── Hybrid Precedence Climbing Parser ─────────────────────────────────────────
+ *
+ * Two-tier dispatch strategy:
+ *
+ *   Tier 1 (Fast Path): Inline switch on token.typeId for built-in operators.
+ *     - Prefix: NUMBER, IDENT, LPAREN, MINUS, PLUS, STRING
+ *     - Infix:  checked via static BP_TABLE (Uint8Array indexed by typeId)
+ *     - No Map.get(), no parselet function call overhead for ~95% of tokens
+ *
+ *   Tier 2 (Plugin Path): ParseletRegistry fallback for custom/plugin tokens.
+ *     - Prefix: Map.get(tokenTypeId) for PrefixParselet
+ *     - Infix:  Map.get(tokenTypeId) for InfixParselet
+ *     - Full flexibility for custom syntax
+ *
+ * The parser emits directly to a BytecodeBuilder, no AST intermediate.
+ * Implements the same public API as the legacy Parser class so existing
+ * parselets continue to work without modification.
+ */
+declare class PrecedenceParser {
+    private tokens;
+    private current;
+    private depth;
+    private maxDepth;
+    /** Cached registry reference, avoids property chain in hot loop */
+    private registry;
+    /** BytecodeBuilder, set before each parseExpression call */
+    private builder;
+    /** Diagnostic pipeline for parselet-matched events */
+    private diagnosticPipeline;
+    private currentExpression;
+    private localeCode;
+    /**
+     * Static binding power table, built once at module load, shared across all instances.
+     * Index = tokenTypeId, value = binding power (0 = not a built-in infix).
+     */
+    static readonly BP_TABLE: Uint8Array;
+    private static readonly NUMBER_ID;
+    private static readonly BIGINT_ID;
+    private static readonly STRING_ID;
+    private static readonly IDENT_ID;
+    private static readonly LPAREN_ID;
+    private static readonly RPAREN_ID;
+    private static readonly MINUS_ID;
+    private static readonly PLUS_ID;
+    private static readonly KEYWORD_ID;
+    private static readonly STAR_ID;
+    private static readonly SLASH_ID;
+    private static readonly MOD_ID;
+    private static readonly CARET_ID;
+    private static readonly LSHIFT_ID;
+    private static readonly RSHIFT_ID;
+    private static readonly BIT_AND_ID;
+    private static readonly BIT_OR_ID;
+    private static readonly BIT_XOR_ID;
+    private static readonly PERCENT_ID;
+    private static readonly OF_ID;
+    /**
+     * Inline opcode map for Tier 1 infix operators.
+     * tokenTypeId → OpCode. PERCENT and CARET are handled specially (not in this map).
+     */
+    private static readonly INFIX_OPCODE;
+    constructor(parseletRegistry: ParseletRegistry, maxDepth?: number, localeCode?: string);
+    /** Get locale code for NumberParselet to normalize separators */
+    getLocaleCode(): string;
+    /**
+     * Set the diagnostic pipeline for parselet matching events.
+     * Cleared after each non-cached parse to avoid holding refs.
+     */
+    setDiagnosticPipeline(pipeline: DiagnosticPipeline | undefined, expression: string): void;
+    /**
+     * Load tokens for parsing. Identical to Parser.load().
+     *
+     * @param hasParens - if false, skips the O(n) paren balance scan (~90% of expressions)
+     */
+    load(tokens: Token[], hasParens?: boolean): void;
+    /**
+     * Auto-balance unmatched parentheses.
+     */
+    private balanceParens;
+    /**
+     * Parse a full expression starting at the current token position.
+     *
+     * @param minBp - minimum binding power (precedence climbing threshold).
+     *   For left-associative operators, the recursive call uses `bp + 1`.
+     *   For right-associative operators (^), it uses `bp`.
+     * @param _builder - accepted for parselet API compatibility; always uses `this.builder`.
+     */
+    parseExpression(minBp?: number, _builder?: BytecodeBuilder): void;
+    /**
+     * Parse a prefix token. Built-in tokens (NUMBER, IDENT, LPAREN, etc.) are
+     * handled inline with zero registry lookup. Everything else falls through
+     * to the parselet registry (Tier 2).
+     */
+    private parsePrefix;
+    /**
+     * A single `^`-suffix shape: `matches` peeks ahead (consuming nothing) to
+     * check whether this shape starts at the current position; `emit` is only
+     * called immediately after `matches` returned true for that SAME position,
+     * and is responsible for consuming that shape's own trailing tokens and
+     * emitting its bytecode.
+     */
+    private static readonly CARET_SUFFIX_RULES;
+    /**
+     * After a `^` token (already consumed by the Tier-1 infix loop above),
+     * checks {@link CARET_SUFFIX_RULES} in order for a shape that means
+     * something other than ordinary exponentiation: `^T` (transpose) and `^-1`
+     * (matrix inverse, LITERALLY the integer exponent `-1`; `^-2`, `^-1.5`
+     * etc. still mean ordinary exponentiation). On a match, the rule's `emit`
+     * consumes that shape's own tokens and this returns `true`. On no match,
+     * consumes NOTHING, returning `false` so the caller falls through to
+     * ordinary `EXP` parsing.
+     *
+     * Every rule dispatches purely on SHAPE, never on operand type (unknowable
+     * at parse time): `inv()`'s own handler (`VMBuiltins.ts` index 65) returns
+     * `1/x` for a plain Number, byte-identical to what `Math.pow(x, -1)`
+     * already computed for `x^-1` before this feature existed, and a real
+     * matrix inverse for a Matrix, so `5^-1` still means exactly what it always
+     * has; only a Matrix operand actually inverts.
+     *
+     * Adding a future `^`-suffix shape is a new table entry here, not a new
+     * if-block. See the "Tier-1 shape-exception" pattern write-up above for
+     * why this table can't instead be a package-registered parselet.
+     */
+    private tryEmitMatrixCaretOp;
+    /**
+     * From an LPAREN token index, scan forward tracking paren depth and
+     * return the index of the matching RPAREN, or `null` if the parens never
+     * balance before the token stream ends. No emission, no position
+     * advance. Same class of technique as {@link balanceParens}'s own
+     * pre-scan, just exposed mid-parse instead of only at `load()` time.
+     * `openIdx` must point AT the LPAREN itself.
+     */
+    private findMatchingRParen;
+    /**
+     * Disambiguates a bare `IDENT` immediately followed by `(` between three
+     * things, using ONLY a bracket-depth scan (no backtracking, nothing is
+     * consumed until the shape is known):
+     * - `f(x) = expr`, a DEFINITION: the matching `)` is followed by `=`.
+     * - `f(5)`, a CALL to a (possibly not-yet-defined) function: anything
+     *   else. This was never valid syntax before this feature (a bare
+     *   `IDENT` immediately before `(` has no pre-existing "plain variable
+     *   read + separately grouped `(...)`" meaning to preserve, confirmed
+     *   via `BuiltinNormalizerRules.ts`'s `implicitMultiplyRule()`, which
+     *   only inserts an implicit `*` for `NUMBER/RPAREN` immediately before
+     *   `IDENT/LPAREN`, never for a bare `IDENT` immediately before
+     *   `LPAREN`). Always commits to a CALL; an unregistered name produces a
+     *   clear `UNDEFINED_FUNCTION` error at VM-execution time, the same
+     *   forward-reference philosophy `LOAD_VAR`/`UNDEFINED_VARIABLE` already
+     *   uses, rather than any parse-time registry lookup.
+     * If the parens never balance, this falls through to the ordinary
+     * `LOAD_VAR` path (a malformed expression surfaces its own parse error
+     * shortly after, from the normal expression grammar).
+     */
+    private parseUserFunctionDefOrCall;
+    /**
+     * A parameter name, accepted as either `IDENT` or `UNIT`, matches this
+     * codebase's established `:name = value` variable-name policy
+     * (`VariableParselet.ts` explicitly accepts `UNIT`-typed tokens too, e.g.
+     * `:b = 5` for the "b" bits unit) since common short parameter names
+     * like `h`/`l`/`b`/`t`/`s`/`m` collide with real unit abbreviations
+     * (hour, liter, bits, ton, second, meter, ...) and lex as `UNIT`, not
+     * `IDENT`.
+     */
+    private consumeParamName;
+    private parseUserFunctionDefinition;
+    private parseUserFunctionCall;
+    consume(expectedType?: string): Token;
+    match(expectedType: string): boolean;
+    peek(): Token | undefined;
+    /**
+     * Read-only lookahead `offset` tokens past the current position, without
+     * consuming anything, `peekAt(0)` is equivalent to {@link peek}.
+     * `this.tokens` is a plain in-memory array (not a stream), so this is a
+     * simple, safe index read; no rewind/checkpoint mechanism is needed since
+     * nothing is consumed.
+     */
+    peekAt(offset: number): Token | undefined;
+    previous(): Token | undefined;
+    private advance;
+    /** Set the builder to use for the current parse. Called by ExpressionEngine. */
+    setBuilder(builder: BytecodeBuilder): void;
+    private fireParseletMatched;
+}
+
+/**
+ * Handles a token appearing where a value is expected.
+ *
+ * A literal, a prefix operator such as unary minus, or a function name. The
+ * parser calls this when the token opens an expression rather than continuing
+ * one.
+ */
+interface PrefixParselet {
+    /** Diagnostic category for this parselet (e.g. "Arithmetic", "Function", "Variable") */
+    readonly category: string;
+    parse(parser: PrecedenceParser, token: Token, builder: BytecodeBuilder): void;
+}
+/**
+ * Handles a token appearing after a value.
+ *
+ * A binary operator, or anything else that continues an expression already in
+ * progress. Its binding power decides how tightly it binds against neighbours.
+ */
+interface InfixParselet {
+    /** Diagnostic category for this parselet (e.g. "Arithmetic", "UoM") */
+    readonly category: string;
+    /** Binding power (precedence), property access avoids vtable dispatch in hot loop */
+    readonly bindingPower: number;
+    parse(parser: PrecedenceParser, left: Token, token: Token, builder: BytecodeBuilder): void;
+}
+
+export { type InfixParselet as I, ParseletRegistry as P, PrecedenceParser as a, type PrefixParselet as b, sharedParseletRegistry as s };