solve-engine 1.2.0 → 2.0.0

package/dist/chunk-AOH6UR2L.js

@@ -1,825 +0,0 @@
-import { DiagnosticEventType } from './chunk-UF6JG5SG.js';
-import { buildBindingPowerTable, BindingPower, bigIntLiteralDigits, BytecodeBuilder } from './chunk-IQJGDZOP.js';
-import { tokenTypeId, TokenTypes } from './chunk-NAWZATKT.js';
-import { getLocale } from './chunk-XBTEO4OB.js';
-import { ErrorFactory } from './chunk-N7OA4WPJ.js';
-
-// src/parser/registry/ParseletRegistry.ts
-function bindingPowersOf(parselet) {
-  return parselet;
-}
-var ParseletRegistry = class {
-  constructor() {
-    // String-keyed maps (kept for diagnostics + backwards compat)
-    this.prefixParselets = /* @__PURE__ */ new Map();
-    this.infixParselets = /* @__PURE__ */ new Map();
-    // Integer-keyed maps for parser hot path
-    this.prefixById = /* @__PURE__ */ new Map();
-    this.infixById = /* @__PURE__ */ new Map();
-  }
-  /**
-   * 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, parselet) {
-    const existing = this.prefixParselets.get(tokenType);
-    if (existing && existing !== parselet) {
-      console.warn(
-        `[ParseletRegistry] Prefix parselet for token "${tokenType}" is already registered (category: "${existing.category ?? "unknown"}"). Overwriting with a new parselet (category: "${parselet.category ?? "unknown"}") \u2014 the previous parselet is now unreachable. Two packages may be claiming the same token type.`
-      );
-    }
-    this.prefixParselets.set(tokenType, parselet);
-    this.prefixById.set(tokenTypeId(tokenType), parselet);
-  }
-  /** Register an infix parselet for `tokenType`. See {@link registerPrefix} for the collision-warning behavior this mirrors. */
-  registerInfix(tokenType, parselet) {
-    const existing = this.infixParselets.get(tokenType);
-    if (existing && existing !== parselet) {
-      console.warn(
-        `[ParseletRegistry] Infix parselet for token "${tokenType}" is already registered (category: "${existing.category ?? "unknown"}"). Overwriting with a new parselet (category: "${parselet.category ?? "unknown"}") \u2014 the previous parselet is now unreachable. Two packages may be claiming the same token type.`
-      );
-    }
-    this.infixParselets.set(tokenType, parselet);
-    this.infixById.set(tokenTypeId(tokenType), parselet);
-  }
-  /**
-   * Iterate all registered prefix parselets for diagnostic display.
-   *
-   * `PrefixParselet` declares no binding power, and this used to read a field
-   * of that name and report 0 for every one of them. 0 is not a neutral
-   * wrong answer: it is the value that means "not an operator, stop the
-   * expression", so a host drawing a table from this was told none of them
-   * bind at all. A prefix parselet in this parser has no per-parselet power
-   * to report, they all bind at the prefix level and each chooses for itself
-   * at what power to parse its own operand, so that level is what is
-   * reported. A parselet that does carry its own `bindingPower` still wins.
-   */
-  getAllPrefix() {
-    const result = [];
-    for (const [tokenType, parselet] of this.prefixParselets) {
-      result.push({
-        tokenType,
-        bindingPower: bindingPowersOf(parselet).bindingPower ?? BindingPower.Prefix,
-        category: parselet.category
-      });
-    }
-    return result;
-  }
-  /**
-   * Iterate all registered infix parselets for diagnostic display.
-   *
-   * The field an `InfixParselet` actually declares is `bindingPower`. This
-   * used to read `leftBindingPower` and `rightBindingPower`, which no
-   * parselet in this codebase declares, so both reads were `undefined`, both
-   * fell to the `?? 0` default, and the public `getParseletRegistry()`
-   * reported a binding power of 0 for every one of the ~60 infix operators.
-   * A host building a precedence table from it was told `*` and `+` bind
-   * equally, and that neither binds at all.
-   *
-   * The left/right split: `bindingPower` is the LEFT power, and the right is
-   * one higher. That is the standard encoding for a left-associative
-   * operator, and it is what the parser itself does, see
-   * `PrecedenceParser.parseExpression()`'s `bp + 1` for the right operand.
-   * Every operator is reported that way, `^` included. Associativity is not
-   * something a parselet declares, it is a property of how each one calls
-   * `parseExpression`, so this API cannot report it without a new field on
-   * the interface. See {@link ParseletBindingPowers} for why scraping a
-   * plausible-looking one off the parselet is worse than not reporting it.
-   */
-  getAllInfix() {
-    const result = [];
-    for (const [tokenType, parselet] of this.infixParselets) {
-      const left = bindingPowersOf(parselet).bindingPower ?? 0;
-      result.push({
-        tokenType,
-        leftBindingPower: left,
-        rightBindingPower: left + 1,
-        category: parselet.category
-      });
-    }
-    return result;
-  }
-  /** Number of registered prefix parselets. */
-  get prefixCount() {
-    return this.prefixParselets.size;
-  }
-  /** Number of registered infix parselets. */
-  get infixCount() {
-    return this.infixParselets.size;
-  }
-  /**
-   * 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) {
-    if (typeof tokenType === "number") return this.prefixById.get(tokenType);
-    return this.prefixParselets.get(tokenType);
-  }
-  /**
-   * Get infix parselet by string token type OR integer typeId.
-   * Fast path for integer IDs (Parser hot path), fallback for strings.
-   */
-  getInfix(tokenType) {
-    if (typeof tokenType === "number") return this.infixById.get(tokenType);
-    return this.infixParselets.get(tokenType);
-  }
-  hasPrefix(tokenType) {
-    return this.prefixParselets.has(tokenType);
-  }
-  hasInfix(tokenType) {
-    return this.infixParselets.has(tokenType);
-  }
-  clear() {
-    this.prefixParselets.clear();
-    this.infixParselets.clear();
-    this.prefixById.clear();
-    this.infixById.clear();
-  }
-};
-var sharedParseletRegistry = new ParseletRegistry();
-
-// src/parser/PrecedenceParser.ts
-var CHAINED_DOT_THOUSANDS_GROUPS = /^\d{1,3}(\.\d{3}){2,}$/;
-var PLAIN_DECIMAL = /^\d*\.\d*$/;
-var _PrecedenceParser = class _PrecedenceParser {
-  constructor(parseletRegistry, maxDepth = 50, localeCode = "en") {
-    this.tokens = [];
-    this.current = 0;
-    this.depth = 0;
-    this.currentExpression = "";
-    /**
-     * The binding power the current infix parselet is being invoked at, i.e. the
-     * `minBp` of the expression it sits inside. Set immediately before each Tier-2
-     * parselet runs. A parselet that decides whether to swallow a following
-     * loose operator (UomLiteralParselet with a trailing `in`/`to`) reads this to
-     * respect precedence it cannot otherwise see: `120 km / 2 hours in kph` must
-     * group as `(120 km / 2 hours) in kph`, not `120 km / (2 hours in kph)`.
-     */
-    this.infixMinBindingPower = 0;
-    this.registry = parseletRegistry;
-    this.maxDepth = maxDepth;
-    this.localeCode = localeCode;
-  }
-  /** Get locale code for NumberParselet to normalize separators */
-  getLocaleCode() {
-    return this.localeCode;
-  }
-  /**
-   * Set the diagnostic pipeline for parselet matching events.
-   * Cleared after each non-cached parse to avoid holding refs.
-   */
-  setDiagnosticPipeline(pipeline, expression) {
-    this.diagnosticPipeline = pipeline;
-    this.currentExpression = expression ?? "";
-  }
-  /**
-   * Load tokens for parsing. Identical to Parser.load().
-   *
-   * @param hasParens - if false, skips the O(n) paren balance scan (~90% of expressions)
-   */
-  load(tokens, hasParens) {
-    if (hasParens === false) {
-      this.tokens = tokens;
-      this.current = 0;
-      this.depth = 0;
-      return;
-    }
-    const LPAREN_ID = tokenTypeId(TokenTypes.LPAREN);
-    const RPAREN_ID = tokenTypeId(TokenTypes.RPAREN);
-    let openCount = 0;
-    for (let i = 0; i < tokens.length; i++) {
-      if (tokens[i].typeId === LPAREN_ID) openCount++;
-      else if (tokens[i].typeId === RPAREN_ID) openCount--;
-    }
-    this.tokens = openCount === 0 ? tokens : this.balanceParens(tokens, openCount);
-    this.current = 0;
-    this.depth = 0;
-  }
-  /**
-   * Auto-balance unmatched parentheses.
-   */
-  balanceParens(tokens, openCount) {
-    const result = tokens.slice();
-    if (openCount > 0) {
-      const RPAREN_ID = tokenTypeId(TokenTypes.RPAREN);
-      for (let i = 0; i < openCount; i++) {
-        const lastToken = tokens[tokens.length - 1];
-        result.push({
-          type: TokenTypes.RPAREN,
-          typeId: RPAREN_ID,
-          value: ")",
-          text: ")",
-          offset: lastToken ? lastToken.offset + lastToken.text.length : 0,
-          lineBreaks: 0,
-          line: lastToken ? lastToken.line : 1,
-          col: lastToken ? lastToken.col + lastToken.text.length : 1
-        });
-      }
-    } else if (openCount < 0) {
-      const LPAREN_ID = tokenTypeId(TokenTypes.LPAREN);
-      for (let i = 0; i < -openCount; i++) {
-        result.unshift({
-          type: TokenTypes.LPAREN,
-          typeId: LPAREN_ID,
-          value: "(",
-          text: "(",
-          offset: 0,
-          lineBreaks: 0,
-          line: 1,
-          col: 1
-        });
-      }
-    }
-    return result;
-  }
-  // ═══════════════════════════════════════════════════════════════════════════════
-  // Main entry point: precedence climbing parse expression
-  // ═══════════════════════════════════════════════════════════════════════════════
-  /**
-   * 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 - 1`.
-   * @param _builder - accepted for parselet API compatibility; always uses `this.builder`.
-   */
-  parseExpression(minBp = 0, _builder) {
-    if (_builder) {
-      this.builder = _builder;
-    }
-    this.depth++;
-    if (this.depth > this.maxDepth) {
-      this.depth--;
-      throw ErrorFactory.parsing(
-        "NESTING_DEPTH_EXCEEDED",
-        `Parse nesting depth ${this.depth} exceeds maximum of ${this.maxDepth}`,
-        { maxDepth: this.maxDepth, currentDepth: this.depth }
-      );
-    }
-    const token = this.consume();
-    if (!token) {
-      this.depth--;
-      throw ErrorFactory.parsing("UNEXPECTED_END", "Unexpected end of expression");
-    }
-    this.parsePrefix(token);
-    const tokens = this.tokens;
-    const len = tokens.length;
-    const bpTable = _PrecedenceParser.BP_TABLE;
-    const registry = this.registry;
-    const builder = this.builder;
-    let idx = this.current;
-    while (idx < len) {
-      const lookahead = tokens[idx];
-      if (!lookahead) break;
-      const bp = bpTable[lookahead.typeId];
-      if (bp > 0) {
-        if (bp <= minBp) break;
-        if (this.diagnosticPipeline) {
-          const infixParselet = registry.getInfix(lookahead.typeId);
-          if (infixParselet) {
-            this.fireParseletMatched(infixParselet, lookahead, false, bp);
-          }
-        }
-        this.current = ++idx;
-        const typeId = lookahead.typeId;
-        if (typeId === _PrecedenceParser.PERCENT_ID) {
-          builder.emitOpcode(10 /* PUSH_NUMBER */);
-          builder.emitNumber(100);
-          builder.emitOpcode(23 /* DIV */);
-          builder.emitOpcode(74 /* TO_PERCENTAGE */);
-        } else if (typeId === _PrecedenceParser.CARET_ID && this.tryEmitMatrixCaretOp(builder)) ; else {
-          const rightBp = typeId === _PrecedenceParser.CARET_ID ? bp - 1 : bp + 1;
-          this.parseExpression(rightBp, builder);
-          builder.emitOpcode(_PrecedenceParser.INFIX_OPCODE[typeId]);
-        }
-      } else {
-        const infixParselet = registry.getInfix(lookahead.typeId);
-        if (!infixParselet) break;
-        if (infixParselet.bindingPower <= minBp) break;
-        this.current = ++idx;
-        if (this.diagnosticPipeline) {
-          this.fireParseletMatched(infixParselet, lookahead, false, infixParselet.bindingPower);
-        }
-        this.infixMinBindingPower = minBp;
-        infixParselet.parse(this, token, lookahead, builder);
-      }
-      idx = this.current;
-    }
-    this.current = idx;
-    this.depth--;
-  }
-  // ═══════════════════════════════════════════════════════════════════════════════
-  // Prefix dispatch: inline switch for built-ins, parselet registry for plugins
-  // ═══════════════════════════════════════════════════════════════════════════════
-  /**
-   * 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).
-   */
-  parsePrefix(token) {
-    const builder = this.builder;
-    const typeId = token.typeId;
-    if (this.diagnosticPipeline) {
-      const parselet = this.registry.getPrefix(typeId);
-      if (parselet) {
-        this.fireParseletMatched(parselet, token, true);
-      }
-    }
-    switch (typeId) {
-      // ── Numeric literals ──────────────────────────────────────────────────
-      case _PrecedenceParser.NUMBER_ID: {
-        let v;
-        let decimalText = null;
-        const raw = token.value;
-        if (raw.startsWith("0x") || raw.startsWith("0X")) {
-          v = parseInt(raw, 16);
-          if (Number.isNaN(v)) {
-            throw ErrorFactory.parsing("INVALID_NUMBER_LITERAL", `Invalid hex literal: "${raw}"`, { raw });
-          }
-        } else if (raw.startsWith("0b") || raw.startsWith("0B")) {
-          v = parseInt(raw.slice(2), 2);
-          if (Number.isNaN(v)) {
-            throw ErrorFactory.parsing("INVALID_NUMBER_LITERAL", `Invalid binary literal: "${raw}"`, { raw });
-          }
-        } else if (raw.startsWith("0o") || raw.startsWith("0O")) {
-          v = parseInt(raw.slice(2), 8);
-          if (Number.isNaN(v)) {
-            throw ErrorFactory.parsing("INVALID_NUMBER_LITERAL", `Invalid octal literal: "${raw}"`, { raw });
-          }
-        } else if (CHAINED_DOT_THOUSANDS_GROUPS.test(raw)) {
-          v = parseFloat(raw.split(".").join(""));
-        } else {
-          const locale = getLocale(this.localeCode);
-          const decimalSep = locale.display.decimalSeparator;
-          const thousandsSep = locale.display.thousandsSeparator;
-          let normalized = raw;
-          if (thousandsSep) {
-            normalized = normalized.split(thousandsSep).join("");
-          }
-          if (decimalSep && decimalSep !== ".") {
-            normalized = normalized.replace(decimalSep, ".");
-          }
-          v = parseFloat(normalized);
-          if (PLAIN_DECIMAL.test(normalized)) decimalText = normalized;
-        }
-        if (decimalText !== null) {
-          builder.emitOpcode(16 /* PUSH_DECIMAL */);
-          builder.emitString(decimalText);
-          return;
-        }
-        builder.emitOpcode(10 /* PUSH_NUMBER */);
-        builder.emitNumber(v);
-        return;
-      }
-      case _PrecedenceParser.BIGINT_ID: {
-        builder.emitOpcode(11 /* PUSH_BIGINT */);
-        builder.emitString(bigIntLiteralDigits(token.value, this.localeCode));
-        return;
-      }
-      case _PrecedenceParser.STRING_ID: {
-        builder.emitOpcode(13 /* PUSH_STRING */);
-        builder.emitString(token.value);
-        return;
-      }
-      // ── Identifiers (variables) ────────────────────────────────────────────
-      case _PrecedenceParser.IDENT_ID: {
-        if (this.peek()?.typeId === _PrecedenceParser.LPAREN_ID) {
-          this.parseUserFunctionDefOrCall(token, builder);
-          return;
-        }
-        builder.emitOpcode(60 /* LOAD_VAR */);
-        builder.emitString(token.value);
-        return;
-      }
-      // ── Grouping / bare-tuple vector literal ─────────────────────────────────
-      // `(expr)` groups for precedence; `(x, y[, z[, w]])` is the bare-tuple
-      // vector literal documented as an alternative to vec2/vec3/vec4(...)
-      // (wiki: Arithmetic/Vector). This Tier-1 case is what actually runs for
-      // every LPAREN in production parsing, GroupParselet.ts mirrors this
-      // logic for registry-introspection/diagnostic-listing purposes, but a
-      // package can never override LPAREN's dispatch here (Tier 1 always
-      // wins over the ParseletRegistry fallback below), so both must be kept
-      // in sync by hand.
-      case _PrecedenceParser.LPAREN_ID: {
-        this.parseExpression(0, builder);
-        let count = 1;
-        while (this.match(TokenTypes.COMMA)) {
-          this.parseExpression(0, builder);
-          count++;
-        }
-        this.consume(TokenTypes.RPAREN);
-        if (count > 1) {
-          builder.emitOpcode(152 /* MAT_NEW */);
-          builder.emitIndex(1);
-          builder.emitIndex(count);
-        }
-        return;
-      }
-      // ── Unary operators ───────────────────────────────────────────────────
-      case _PrecedenceParser.MINUS_ID: {
-        this.parseExpression(BindingPower.Prefix, builder);
-        builder.emitOpcode(26 /* NEG */);
-        return;
-      }
-      case _PrecedenceParser.PLUS_ID: {
-        this.parseExpression(BindingPower.Prefix, builder);
-        builder.emitOpcode(27 /* POS */);
-        return;
-      }
-      // ── Keyword constants ─────────────────────────────────────────────────
-      case _PrecedenceParser.KEYWORD_ID:    }
-    const prefixParselet = this.registry.getPrefix(typeId);
-    if (!prefixParselet) {
-      throw ErrorFactory.parsing(
-        "NO_PREFIX_PARSELET",
-        `No prefix parselet found for token: ${token.type} ("${token.value}")`,
-        { tokenType: token.type, tokenValue: token.value }
-      );
-    }
-    prefixParselet.parse(this, token, builder);
-  }
-  /**
-   * 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.
-   */
-  tryEmitMatrixCaretOp(builder) {
-    for (const rule of _PrecedenceParser.CARET_SUFFIX_RULES) {
-      if (rule.matches(this)) {
-        rule.emit(this, builder);
-        return true;
-      }
-    }
-    return false;
-  }
-  // ═══════════════════════════════════════════════════════════════════════════════
-  // User-defined, parameterized, reusable functions (f(x) = 2*x + 1, then f(5))
-  // ═══════════════════════════════════════════════════════════════════════════════
-  /**
-   * 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.
-   */
-  findMatchingRParen(openIdx) {
-    let depth = 0;
-    for (let i = openIdx; i < this.tokens.length; i++) {
-      const t = this.tokens[i];
-      if (t.typeId === _PrecedenceParser.LPAREN_ID) depth++;
-      else if (t.typeId === _PrecedenceParser.RPAREN_ID) {
-        depth--;
-        if (depth === 0) return i;
-      }
-    }
-    return null;
-  }
-  /**
-   * 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).
-   */
-  parseUserFunctionDefOrCall(nameToken, builder) {
-    const closeIdx = this.findMatchingRParen(this.current);
-    if (closeIdx === null) {
-      builder.emitOpcode(60 /* LOAD_VAR */);
-      builder.emitString(nameToken.value);
-      return;
-    }
-    const afterClose = this.tokens[closeIdx + 1];
-    if (afterClose?.type === TokenTypes.EQUALS) {
-      this.parseUserFunctionDefinition(nameToken, builder);
-    } else {
-      this.parseUserFunctionCall(nameToken, builder);
-    }
-  }
-  /**
-   * 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`.
-   */
-  consumeParamName() {
-    const token = this.peek();
-    if (token?.type === TokenTypes.IDENT || token?.type === TokenTypes.UNIT) {
-      this.consume();
-      return token.value;
-    }
-    throw ErrorFactory.parsing(
-      "USER_FUNCTION_INVALID_PARAM_NAME",
-      `Expected a parameter name but got "${token?.type ?? "end of input"}"${token ? ` ("${token.value}")` : ""}`,
-      { actualType: token?.type }
-    );
-  }
-  parseUserFunctionDefinition(nameToken, builder) {
-    this.consume(TokenTypes.LPAREN);
-    const params = [];
-    if (this.peek()?.type !== TokenTypes.RPAREN) {
-      params.push(this.consumeParamName());
-      while (this.match(TokenTypes.COMMA)) {
-        params.push(this.consumeParamName());
-      }
-    }
-    this.consume(TokenTypes.RPAREN);
-    this.consume(TokenTypes.EQUALS);
-    if (params.length === 0) {
-      throw ErrorFactory.parsing(
-        "USER_FUNCTION_NO_PARAMS",
-        `"${nameToken.value}()" has no parameters -- user-defined functions need at least one (a zero-argument definition is indistinguishable from a plain function CALL with no args, which this grammar doesn't otherwise support)`,
-        { name: nameToken.value }
-      );
-    }
-    const bodyBuilder = new BytecodeBuilder();
-    this.parseExpression(BindingPower.Lowest, bodyBuilder);
-    this.setBuilder(builder);
-    const bodyProgram = bodyBuilder.build();
-    if (bodyProgram.hasAsync) {
-      throw ErrorFactory.parsing(
-        "FUNCTION_BODY_MUST_BE_SYNCHRONOUS",
-        `"${nameToken.value}(...)"'s body calls an async operation (weather, stocks, currency, ...) \u2014 user-defined function bodies must be synchronous`,
-        { name: nameToken.value }
-      );
-    }
-    const bodyIdx = builder.emitUserFunctionBody(nameToken.value, params, bodyProgram);
-    builder.emitOpcode(150 /* DEFINE_USER_FUNCTION */);
-    builder.emitIndex(bodyIdx);
-    builder.emitOpcode(13 /* PUSH_STRING */);
-    builder.emitString(`${nameToken.value}(${params.join(", ")}) defined`);
-  }
-  parseUserFunctionCall(nameToken, builder) {
-    this.consume(TokenTypes.LPAREN);
-    let argCount = 0;
-    if (this.peek()?.type !== TokenTypes.RPAREN) {
-      this.parseExpression(BindingPower.Lowest, builder);
-      argCount++;
-      while (this.match(TokenTypes.COMMA)) {
-        this.parseExpression(BindingPower.Lowest, builder);
-        argCount++;
-      }
-    }
-    this.consume(TokenTypes.RPAREN);
-    builder.emitOpcode(151 /* CALL_USER_FUNCTION */);
-    builder.emitString(nameToken.value);
-    builder.emitByte(argCount);
-  }
-  // ═══════════════════════════════════════════════════════════════════════════════
-  // Token stream navigation (identical API to Parser)
-  // ═══════════════════════════════════════════════════════════════════════════════
-  consume(expectedType) {
-    const token = this.tokens[this.current];
-    if (!token) {
-      throw ErrorFactory.parsing(
-        "UNEXPECTED_END_OF_INPUT",
-        "Unexpected end of input"
-      );
-    }
-    if (expectedType !== void 0) {
-      const expectedId = tokenTypeId(expectedType);
-      if (token.typeId !== expectedId) {
-        throw ErrorFactory.parsing(
-          "UNEXPECTED_TOKEN_TYPE",
-          `Expected token type "${expectedType}" but got "${token.type}" ("${token.value}")`,
-          { expectedType, actualType: token.type, actualValue: token.value }
-        );
-      }
-    }
-    this.current++;
-    return token;
-  }
-  match(expectedType) {
-    const token = this.peek();
-    if (token && token.typeId === tokenTypeId(expectedType)) {
-      this.advance();
-      return true;
-    }
-    return false;
-  }
-  peek() {
-    return this.tokens[this.current];
-  }
-  /**
-   * 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) {
-    return this.tokens[this.current + offset];
-  }
-  previous() {
-    return this.current > 0 ? this.tokens[this.current - 1] : void 0;
-  }
-  advance() {
-    this.current++;
-  }
-  // ═══════════════════════════════════════════════════════════════════════════════
-  // Builder access, set before parse, read by inline prefix handlers
-  // ═══════════════════════════════════════════════════════════════════════════════
-  /** Set the builder to use for the current parse. Called by ExpressionEngine. */
-  setBuilder(builder) {
-    this.builder = builder;
-  }
-  // ═══════════════════════════════════════════════════════════════════════════════
-  // Diagnostics
-  // ═══════════════════════════════════════════════════════════════════════════════
-  fireParseletMatched(parselet, token, isPrefix, bindingPower) {
-    const pipeline = this.diagnosticPipeline;
-    const event = {
-      type: DiagnosticEventType.ParseletMatched,
-      elapsedNs: 0,
-      expression: this.currentExpression,
-      tokenType: token.type,
-      tokenValue: token.value,
-      parseletCategory: parselet.category,
-      parseletType: parselet.constructor?.name ?? "unknown",
-      isPrefix,
-      bindingPower,
-      tokenOffset: token.offset || 0
-    };
-    pipeline.fireParseletMatched(event);
-  }
-};
-/**
- * Static binding power table, built once at module load, shared across all instances.
- * Index = tokenTypeId, value = binding power (0 = not a built-in infix).
- */
-_PrecedenceParser.BP_TABLE = buildBindingPowerTable();
-// ── Pre-computed token type IDs for inline dispatch ────────────────────────
-// Prefix built-ins
-_PrecedenceParser.NUMBER_ID = tokenTypeId(TokenTypes.NUMBER);
-_PrecedenceParser.BIGINT_ID = tokenTypeId(TokenTypes.BIGINT);
-_PrecedenceParser.STRING_ID = tokenTypeId(TokenTypes.STRING);
-_PrecedenceParser.IDENT_ID = tokenTypeId(TokenTypes.IDENT);
-_PrecedenceParser.LPAREN_ID = tokenTypeId(TokenTypes.LPAREN);
-_PrecedenceParser.RPAREN_ID = tokenTypeId(TokenTypes.RPAREN);
-_PrecedenceParser.MINUS_ID = tokenTypeId(TokenTypes.MINUS);
-_PrecedenceParser.PLUS_ID = tokenTypeId(TokenTypes.PLUS);
-_PrecedenceParser.KEYWORD_ID = tokenTypeId(TokenTypes.KEYWORD);
-// Infix built-ins (Tier 1, full inline emission)
-_PrecedenceParser.STAR_ID = tokenTypeId(TokenTypes.STAR);
-_PrecedenceParser.SLASH_ID = tokenTypeId(TokenTypes.SLASH);
-_PrecedenceParser.MOD_ID = tokenTypeId(TokenTypes.MOD);
-_PrecedenceParser.CARET_ID = tokenTypeId(TokenTypes.CARET);
-_PrecedenceParser.LSHIFT_ID = tokenTypeId(TokenTypes.LSHIFT);
-_PrecedenceParser.RSHIFT_ID = tokenTypeId(TokenTypes.RSHIFT);
-_PrecedenceParser.URSHIFT_ID = tokenTypeId(TokenTypes.URSHIFT);
-_PrecedenceParser.BIT_AND_ID = tokenTypeId(TokenTypes.BIT_AND);
-_PrecedenceParser.BIT_OR_ID = tokenTypeId(TokenTypes.BIT_OR);
-_PrecedenceParser.BIT_XOR_ID = tokenTypeId(TokenTypes.BIT_XOR);
-_PrecedenceParser.PERCENT_ID = tokenTypeId(TokenTypes.PERCENT);
-_PrecedenceParser.OF_ID = tokenTypeId(TokenTypes.OF);
-/**
- * Inline opcode map for Tier 1 infix operators.
- * tokenTypeId → OpCode. PERCENT and CARET are handled specially (not in this map).
- */
-_PrecedenceParser.INFIX_OPCODE = {
-  [tokenTypeId(TokenTypes.PLUS)]: 20 /* ADD */,
-  [tokenTypeId(TokenTypes.MINUS)]: 21 /* SUB */,
-  [tokenTypeId(TokenTypes.STAR)]: 22 /* MUL */,
-  [tokenTypeId(TokenTypes.SLASH)]: 23 /* DIV */,
-  [tokenTypeId(TokenTypes.MOD)]: 24 /* MOD */,
-  [tokenTypeId(TokenTypes.CARET)]: 25 /* EXP */,
-  [tokenTypeId(TokenTypes.LSHIFT)]: 30 /* LSHIFT */,
-  [tokenTypeId(TokenTypes.RSHIFT)]: 31 /* RSHIFT */,
-  [tokenTypeId(TokenTypes.URSHIFT)]: 32 /* URSHIFT */,
-  [tokenTypeId(TokenTypes.BIT_AND)]: 33 /* BIT_AND */,
-  [tokenTypeId(TokenTypes.BIT_OR)]: 34 /* BIT_OR */,
-  [tokenTypeId(TokenTypes.BIT_XOR)]: 35 /* BIT_XOR */,
-  [tokenTypeId(TokenTypes.OF)]: 22 /* MUL */
-};
-// ═══════════════════════════════════════════════════════════════════════════════
-// The "Tier-1 shape-exception" pattern
-// ═══════════════════════════════════════════════════════════════════════════════
-//
-// Tier 1 exists purely for performance, avoid a Map lookup + parselet call
-// on ~95% of tokens (see this file's own module doc comment above). A
-// recurring consequence: any grammar shape tied to a Tier-1 token type can
-// ONLY be implemented by hand-editing this switch, since a package-
-// registered ParseletRegistry parselet for that same token type would
-// simply never run in production (Tier 1 always wins over the registry
-// fallback). Five confirmed instances of this tension exist in this file
-// (plus one that had to move OUTSIDE it entirely):
-//   1. NUMBER_ID, the full locale-aware number-literal parsing (hex/
-//      binary/octal, chained-dot thousands grouping, decimal-separator
-//      normalization) is inlined in parsePrefix() above; NumberParselet.ts's
-//      own copy is dead code for real evaluation, kept registered only for
-//      the "matched parselets" diagnostic view.
-//   2. IDENT_ID, parseUserFunctionDefOrCall's lookahead (below) disambig-
-//      uates a function DEFINITION from a CALL from a plain variable load.
-//   3. LPAREN_ID, the bare-tuple vector-literal sugar ("(x,y[,z[,w]])" ->
-//      MAT_NEW) is inlined in parsePrefix() above; GroupParselet.ts mirrors
-//      it for introspection only and must be kept in sync by hand.
-//   4. CARET_ID, the transpose/inverse suffix table just below.
-//   5. PLUS_ID, the locale word "and" lexes as PLUS (Tier-1, fixed Sum
-//      binding power), so a registry parselet can never intercept it the
-//      way LogicalParselet.ts intercepts "or"/&&/||; unlike the other four,
-//      there's no SHAPE to special-case on here (the token itself IS the
-//      operator), so the workaround lives entirely outside this file, as a
-//      runtime Boolean/Boolean type-check inside vm/VM.ts's OpCode.ADD
-//      handler instead.
-//
-// Deliberate non-goal: none of this is exposed as an IEnginePackage
-// extension point (unlike prefixParselets/infixParselets). Letting
-// third-party packages register their own Tier-1 shape-matchers would put
-// per-package matcher iteration on a genuinely hot path (every CARET/
-// NUMBER/IDENT/LPAREN/PLUS token, matched or not), a materially bigger
-// separate product decision than "make this one table more concise," and
-// not one this pattern write-up makes.
-/**
- * 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.
- */
-_PrecedenceParser.CARET_SUFFIX_RULES = [
-  {
-    name: "transpose (^T)",
-    matches: (p) => {
-      const next = p.peek();
-      return next?.type === TokenTypes.IDENT && next.value === "T";
-    },
-    emit: (p, builder) => {
-      p.advance();
-      builder.emitOpcode(51 /* CALL_BUILTIN */);
-      builder.emitIndex(63);
-      builder.emitIndex(1);
-    }
-  },
-  {
-    name: "inverse (^-1)",
-    matches: (p) => {
-      const next = p.peek();
-      if (next?.typeId !== _PrecedenceParser.MINUS_ID) return false;
-      const afterMinus = p.peekAt(1);
-      return afterMinus?.type === TokenTypes.NUMBER && afterMinus.value === "1";
-    },
-    emit: (p, builder) => {
-      p.advance();
-      p.advance();
-      builder.emitOpcode(51 /* CALL_BUILTIN */);
-      builder.emitIndex(65);
-      builder.emitIndex(1);
-    }
-  }
-];
-var PrecedenceParser = _PrecedenceParser;
-
-export { ParseletRegistry, PrecedenceParser, sharedParseletRegistry };
-//# sourceMappingURL=chunk-AOH6UR2L.js.map
-//# sourceMappingURL=chunk-AOH6UR2L.js.map