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

package/dist/chunk-SDGRK7EP.js

@@ -0,0 +1,774 @@
+import { DiagnosticEventType } from './chunk-G535KJEG.js';
+import { buildBindingPowerTable, BindingPower, BytecodeBuilder } from './chunk-5YEMOYSE.js';
+import { tokenTypeId, TokenTypes } from './chunk-RIN643A3.js';
+import { getLocale } from './chunk-GOLDJNMZ.js';
+import { ErrorFactory } from './chunk-6RDSQURE.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. */
+  getAllPrefix() {
+    const result = [];
+    for (const [tokenType, parselet] of this.prefixParselets) {
+      result.push({
+        tokenType,
+        bindingPower: bindingPowersOf(parselet).bindingPower ?? 0,
+        category: parselet.category
+      });
+    }
+    return result;
+  }
+  /** Iterate all registered infix parselets for diagnostic display. */
+  getAllInfix() {
+    const result = [];
+    for (const [tokenType, parselet] of this.infixParselets) {
+      result.push({
+        tokenType,
+        leftBindingPower: bindingPowersOf(parselet).leftBindingPower ?? 0,
+        rightBindingPower: bindingPowersOf(parselet).rightBindingPower ?? 0,
+        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 _PrecedenceParser = class _PrecedenceParser {
+  constructor(parseletRegistry, maxDepth = 50, localeCode = "en") {
+    this.tokens = [];
+    this.current = 0;
+    this.depth = 0;
+    this.currentExpression = "";
+    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`.
+   * @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 */);
+        } else if (typeId === _PrecedenceParser.CARET_ID && this.tryEmitMatrixCaretOp(builder)) ; else {
+          const rightBp = typeId === _PrecedenceParser.CARET_ID ? bp : 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);
+        }
+        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;
+        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);
+        }
+        builder.emitOpcode(10 /* PUSH_NUMBER */);
+        builder.emitNumber(v);
+        return;
+      }
+      case _PrecedenceParser.BIGINT_ID: {
+        let raw = token.value;
+        if (raw.endsWith("n")) raw = raw.slice(0, -1);
+        builder.emitOpcode(11 /* PUSH_BIGINT */);
+        builder.emitString(raw);
+        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.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.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-SDGRK7EP.js.map
+//# sourceMappingURL=chunk-SDGRK7EP.js.map