bigint (#3526)

Adds the `bigint` primitive type, which represents an
arbitrary-precision signed integer with sign-extended two's complement
bitwise semantics. Like `string`, it is an immutable heap-allocated
object.

- Includes `bigint` literals: like other popular languages with built-in
arbitrary-size integers, we use the `n` suffix as in `123n` or
`9999999999999999999999999n`
- `int` can always be safely widened into `bigint`. We only do this
implicitly for binary ops: `1n + 2 == 3n`
- Operations that can produce very large `bigint`s (such as left shift)
may throw an `AllocFailure` panic if the size of the `bigint` would
exceed `1 << 28` bits (about 33.6MB). For example: `1n << (1n << 29n)`
will panic. This allows programs to recover in BAML instead of crashing
from an out-of-memory error or other allocation problems.
- Helpful diagnostics for malformed `bigint` literals like `123N` or
`1.23n`

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
- Added Bigint primitive with literal syntax (e.g. 42n), int→bigint
widening, full arithmetic/bitwise/shift ops, comparisons, and typed
bytecode/VM support.
- Bigint standard library: parse, to_json,
abs/min/max/clamp/isqrt/pow/ilog/random.

* **Runtime / VM**
- Heap/object representation, allocation paths, serializers, and new
panics (negative-bit-shift, alloc failure) for bigint.

* **FFI / SDK / Protobuf**
- End-to-end bigint round‑trip support in bridges and SDKs (Python,
Node, protobufs).

* **Tests**
- Extensive new and updated tests covering syntax, coercion, ops,
serialization, edge cases.

* **Chores**
- Workspace dependencies and codegen/type mappings added for bigint
support.

<!-- review_stack_entry_start -->

[![Review Change
Stack](https://storage.googleapis.com/coderabbit_public_assets/review-stack-in-coderabbit-ui.svg)](https://app.coderabbit.ai/change-stack/BoundaryML/baml/pull/3526)

<!-- review_stack_entry_end -->
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: 2kai2kai2

baml_language/Cargo.lock

@@ -195,7 +195,7 @@ salsa = { version = "0.26", default-features = false, features = [
 ] }
 serde = { version = "1.0.197", features = [ "derive" ] }
 serde-wasm-bindgen = "0.6"
-serde_json = { version = "1.0.113", features = [ "preserve_order" ] }
+serde_json = { version = "1.0.113", features = [ "arbitrary_precision", "preserve_order" ] }
 serde_yaml = "0.9"
 similar = { version = "2.4.0", features = [ "inline" ] }
 smol_str = { version = "0.3", features = [ "serde" ] }
@@ -244,6 +244,7 @@ vfs = "0.12"
 wasm-logger = "0.2.0"
 web-time = "1.1.0"
 getrandom = { version = "0.2" }
+num-bigint = { version = "0.4", features = [ "rand", "serde" ] }
 rsa = { version = "0.9", default-features = false, features = [ "std", "pem" ] }
 sha2 = { version = "0.10", features = [ "oid" ] }
 

baml_language/Cargo.toml

@@ -18,6 +18,7 @@ workspace = true
 
 [dependencies]
 ariadne = { workspace = true }
+num-bigint = { workspace = true }
 salsa = { workspace = true }
 serde = { workspace = true }
 smol_str = { workspace = true }

baml_language/crates/baml_base/Cargo.toml

@@ -241,6 +241,7 @@ impl fmt::Display for MediaKind {
 #[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
 pub enum Literal {
     Int(i64),
+    Bigint(num_bigint::BigInt),
     Float(String),
     String(String),
     Bool(bool),
@@ -251,6 +252,7 @@ impl fmt::Display for Literal {
         match self {
             Literal::String(s) => write!(f, "{s:?}"),
             Literal::Int(i) => write!(f, "{i}"),
+            Literal::Bigint(n) => write!(f, "{n}n"),
             Literal::Float(s) => write!(f, "{s}"),
             Literal::Bool(b) => write!(f, "{b}"),
         }

baml_language/crates/baml_base/src/core_types.rs

@@ -0,0 +1,188 @@
+/// Arbitrary-precision signed integer.
+///
+/// # Bitwise on negatives
+///
+/// `&`, `|`, `^` use two's-complement semantics — bigints are treated as if
+/// they had an infinite sign-extended bit string. So `(-1n) & 1n == 1n`,
+/// `(-1n) | 0n == -1n`, `(-1n) ^ 0n == -1n`. This matches JavaScript `BigInt`
+/// and Python `int`.
+///
+/// # Panics
+///
+/// Bigint operators and methods can raise the following unrecoverable
+/// panics. These are not declared via `throws` because they signal that
+/// the program tried to do something invalid (rather than a recoverable
+/// runtime condition):
+///
+/// - `baml.panics.DivisionByZero` — `a / 0n` or `a % 0n`.
+/// - `baml.panics.NegativeBitShift` — `a << -1n` or `a >> -1n`. The shift
+///   count must be non-negative.
+/// - `baml.panics.AllocFailure` — the operand or result would require
+///   more than ~268M bits (`bigint`'s workspace cap). Sources:
+///     * `a * b`, `a << n`, `a.pow(n)` where the predicted result exceeds
+///       the cap.
+///     * `bigint.parse(s)` where `s` carries more decimal digits than the
+///       cap permits.
+class Bigint {
+  //baml:mut_vm
+  function to_json(self) -> baml.json.json {
+    $rust_function
+  }
+  // ─── Comparisons / clamping ───────────────────────────────────────────────
+
+  /// Returns the absolute value of `self`.
+  /// # Examples
+  /// ```
+  /// (-7n).abs()         // 7n
+  /// (3n).abs()          // 3n
+  /// (0n).abs()          // 0n
+  /// ```
+  function abs(self) -> bigint {
+    $rust_function
+  }
+
+  /// Returns the smaller of `self` and `other`.
+  ///
+  /// # Examples
+  /// ```
+  /// (3n).min(5n)   // 3n
+  /// (3n).min(3)   // 3n (note we cast up from `int` to `bigint` here)
+  /// (-2n).min(0n)  // -2n
+  /// ```
+  function min(self, other: bigint) -> bigint {
+    $rust_function
+  }
+
+  /// Returns the larger of `self` and `other`.
+  ///
+  /// # Examples
+  /// ```
+  /// (3n).max(5n)   // 5n
+  /// (3n).max(3)   // 3n (note we cast up from `int` to `bigint` here)
+  /// (-2n).max(0n)  // 0n
+  /// ```
+  function max(self, other: bigint) -> bigint {
+    $rust_function
+  }
+
+  /// Clamps `self` into the range `[min, max]`.
+  ///
+  /// Equivalent to `self.min(max).max(min)`. Callers should pass `min <= max`;
+  /// if `min > max` the result is always `min` (the lower-clamp wins because
+  /// it runs after the upper-clamp).
+  ///
+  /// # Examples
+  /// ```
+  /// (5n).clamp(0n, 10n)    // 5n
+  /// (-3n).clamp(0, 10)   // 0n (note we cast up from `int` to `bigint` here)
+  /// (15n).clamp(0n, 10n)   // 10n
+  /// ```
+  function clamp(self, min: bigint, max: bigint) -> bigint {
+    $rust_function
+  }
+
+  // ─── Math ─────────────────────────────────────────────────────────────────
+
+  /// Returns the integer square root of `self` — that is, the largest `bigint`
+  /// `r` such that `r * r <= self`.
+  ///
+  /// Throws `InvalidArgument` if `self` is negative.
+  ///
+  /// # Examples
+  /// ```
+  /// (10n).isqrt()   // 3n
+  /// (16n).isqrt()   // 4n
+  /// (0n).isqrt()    // 0n
+  /// (-1n).isqrt()   // throws
+  /// ```
+  function isqrt(self) -> bigint throws root.errors.InvalidArgument {
+    $rust_function
+  }
+
+  /// Returns `self ** exp`.
+  ///
+  /// `0 ** 0` returns `1`, by convention.
+  ///
+  /// If `exp` is negative the result is `0`, since the mathematical value
+  /// `self ** -n = 1 / self ** n` is in `(-1, 1)` for `|self| > 1` and rounds
+  /// to zero. (For `self == 1` or `self == -1` the value is `±1` which rounds
+  /// to itself; this implementation still returns `0` for negative exponents
+  /// uniformly.)
+  ///
+  /// # Examples
+  /// ```
+  /// (2n).pow(10n)      // 1024n
+  /// (2n).pow(0n)       // 1n
+  /// (0n).pow(0n)       // 1n   (convention)
+  /// (2n).pow(-1n)      // 0n
+  /// (10n).pow(100n)    // a very large number
+  /// (-2n).pow(3n)      // -8n
+  /// ```
+  function pow(self, exp: bigint) -> bigint {
+    $rust_function
+  }
+
+  /// Returns the integer logarithm of `self` in the given `base`, rounded
+  /// down — i.e. the largest `n` such that `base ** n <= self`.
+  ///
+  /// Throws `InvalidArgument` if `self <= 0` or `base < 2`.
+  ///
+  /// # Examples
+  /// ```
+  /// (1000n).ilog(10n)   // 3n
+  /// (1024n).ilog(2n)    // 10n
+  /// (1n).ilog(10n)      // 0n
+  /// (0n).ilog(10n)      // throws
+  /// (10n).ilog(1n)      // throws
+  /// ```
+  function ilog(self, base: bigint) -> bigint throws root.errors.InvalidArgument {
+    $rust_function
+  }
+
+  // ─── Parsing ──────────────────────────────────────────────────────────────
+
+  /// Parses `text` as a base-ten signed integer.
+  ///
+  /// Accepts an optional leading `+` or `-` sign followed by one or more
+  /// ASCII digits. No surrounding whitespace, no underscore separators,
+  /// no hex / octal / binary prefix (`0x` / `0o` / `0b`), no Unicode digits,
+  /// no scientific notation. Callers needing those should preprocess the
+  /// string.
+  ///
+  /// Throws `ParseError` if `text` is empty or contains a non-digit character.
+  ///
+  /// # Examples
+  /// ```
+  /// bigint.parse("42")       // 42n
+  /// bigint.parse("-7")       // -7n
+  /// bigint.parse("+0")       // 0n
+  /// bigint.parse("")         // throws — empty
+  /// bigint.parse("12a")      // throws — non-digit
+  /// bigint.parse("0x2a")     // throws — hex prefix not accepted
+  /// bigint.parse("1_000")    // throws — underscores not accepted
+  /// bigint.parse(" 5 ")      // throws — whitespace not allowed; trim first
+  /// bigint.parse("99999999999999999999")  // 99999999999999999999n
+  /// ```
+  function parse(text: string) -> bigint throws root.errors.ParseError {
+    $rust_function
+  }
+
+  /// Returns a uniformly distributed random integer in the half-open range
+  /// `[lower, upper)`.
+  ///
+  /// Throws `InvalidArgument` if `lower >= upper` (the range would be empty).
+  /// Uses the host's cryptographic entropy source — no user-supplied RNG
+  /// handle.
+  ///
+  /// # Examples
+  /// ```
+  /// bigint.random(0n, 10n)         // some value in {0, 1, ..., 9}
+  /// bigint.random(-5n, 5n)         // some value in {-5, -4, ..., 4}
+  /// bigint.random(0n, 1n)          // always 0  (single-element range)
+  /// bigint.random(5n, 5n)          // throws — empty range
+  /// bigint.random(10n, 0n)         // throws — lower > upper
+  /// ```
+  function random(lower: bigint, upper: bigint) -> bigint throws root.errors.InvalidArgument {
+    $rust_function
+  }
+}

baml_language/crates/baml_builtins2/baml_std/baml/bigint.baml

@@ -63,4 +63,11 @@ class HostUnavailable {
   message string
 }
 
-type Panic = DivisionByZero | IndexOutOfBounds | MapKeyNotFound | StackOverflow | AssertionFailed | Unreachable | Cancelled | UserPanic | Exit | AllocFailure | HostUnavailable
+/// The right operand of a bigint shift (`<<` / `>>`) was negative.
+/// The type system can't rule this out because the shift count is a
+/// runtime `bigint` value.
+class NegativeBitShift {
+  message string
+}
+
+type Panic = DivisionByZero | IndexOutOfBounds | MapKeyNotFound | StackOverflow | AssertionFailed | Unreachable | Cancelled | UserPanic | Exit | AllocFailure | HostUnavailable | NegativeBitShift

baml_language/crates/baml_builtins2/baml_std/baml/ns_panics/panics.baml

@@ -84,6 +84,7 @@ pub const ALL: &[BuiltinFile] = &[
     builtin!("baml", "containers.baml"),
     builtin!("baml", "core.baml"),
     builtin!("baml", "int.baml"),
+    builtin!("baml", "bigint.baml"),
     builtin!("baml", "float.baml"),
     builtin!("baml", "bool.baml"),
     builtin!("baml", "null.baml"),