feat(types): BigInt + Decimal exact economy numbers (#52)

Types phase 2 — the "money problem". A splice-on-demand bignum engine
(runtime/native/bignum.ludic, self-contained, only intrinsics) exposed as
two namespaces:

- BigInt.* — arbitrary-precision integer (sign-magnitude, base-1e9 limbs):
  from/parse, add/sub/mul/pow, div/mod (by int), cmp/eq/is_zero, to_int, str.
  For idle counters and exact huge currencies that overflow a 32/64-bit int.
- Decimal.* — exact base-10 fixed point (BigInt mantissa + decimal scale):
  from/parse, exact add/sub/mul, cmp/eq, scale/rescale (truncate), str.
  So 0.10 + 0.20 is exactly 0.30 — no binary rounding.

Both exact => deterministic; no f32/f64. Wired: parser splice trigger
(g_uses_bignum), emit_call dispatch, reseeded seed, a self-asserting example
(examples/library/bignum.ludic + feat_case), and per-symbol docs + inventory.
All suites green incl. golden renders byte-identical and the bootstrap fixpoint.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs/language/bigint/_section.md

@@ -0,0 +1,7 @@
+---
+id: bigint
+title: BigInt
+order: 10
+---
+
+Arbitrary-precision integers with no upper bound, for idle/incremental counters, exact huge currencies, and score arithmetic that a 32- or 64-bit <code>int</code> would overflow. A <code>BigInt</code> is a sign-magnitude number stored as base-1e9 limbs, so every operation is <strong>exact</strong> and therefore deterministic — bit-identical on every platform, with no binary floating point. Build one with <code>BigInt.from</code> (an <code>int</code>) or <code>BigInt.parse</code> (decimal text), combine with <code>add</code> / <code>sub</code> / <code>mul</code> / <code>pow</code> / <code>div</code> / <code>mod</code>, compare with <code>cmp</code> / <code>eq</code> / <code>is_zero</code>, and render with <code>str</code>. Arguments are positional. The runtime is spliced in only when a program mentions <code>BigInt.*</code>.

docs/language/bigint/bigint-add.md

@@ -0,0 +1,22 @@
+---
+id: bigint-add
+name: BigInt.add
+category: bigint
+kind: namespace-method
+tokens: BigInt.add
+sig: BigInt.add(a, b) -> BigInt
+tip: Exact sum of two big integers.
+order: 2
+ns: BigInt
+member: add
+---
+
+Returns the exact sum <code>a + b</code>. There is no overflow — the result grows as many digits as it needs.
+
+```ludic
+program Demo {
+  handler Step phase Update {
+    let total = BigInt.add(score, reward)
+  }
+}
+```

docs/language/bigint/bigint-cmp.md

@@ -0,0 +1,22 @@
+---
+id: bigint-cmp
+name: BigInt.cmp
+category: bigint
+kind: namespace-method
+tokens: BigInt.cmp
+sig: BigInt.cmp(a, b) -> int
+tip: Compare two big integers: -1, 0, or 1.
+order: 9
+ns: BigInt
+member: cmp
+---
+
+Compares two big integers, returning <code>-1</code>, <code>0</code>, or <code>1</code> as <code>a</code> is less than, equal to, or greater than <code>b</code>.
+
+```ludic
+program Demo {
+  handler Step phase Update {
+    if BigInt.cmp(score, best) > 0 { best = score }
+  }
+}
+```

docs/language/bigint/bigint-div.md

@@ -0,0 +1,22 @@
+---
+id: bigint-div
+name: BigInt.div
+category: bigint
+kind: namespace-method
+tokens: BigInt.div
+sig: BigInt.div(a, d) -> BigInt
+tip: Divide a big integer by an int (toward zero).
+order: 7
+ns: BigInt
+member: div
+---
+
+Divides a <code>BigInt</code> by an <code>int</code> divisor, truncating toward zero. Handy for splitting an exact total into equal shares.
+
+```ludic
+program Demo {
+  handler Step phase Update {
+    let each = BigInt.div(pot, players)
+  }
+}
+```

docs/language/bigint/bigint-eq.md

@@ -0,0 +1,22 @@
+---
+id: bigint-eq
+name: BigInt.eq
+category: bigint
+kind: namespace-method
+tokens: BigInt.eq
+sig: BigInt.eq(a, b) -> bool
+tip: True when two big integers are equal.
+order: 10
+ns: BigInt
+member: eq
+---
+
+Returns true when two big integers have exactly the same value.
+
+```ludic
+program Demo {
+  handler Step phase Update {
+    if BigInt.eq(score, target) { win() }
+  }
+}
+```

docs/language/bigint/bigint-from.md

@@ -0,0 +1,22 @@
+---
+id: bigint-from
+name: BigInt.from
+category: bigint
+kind: namespace-method
+tokens: BigInt.from
+sig: BigInt.from(value) -> BigInt
+tip: Turn a plain int into a BigInt.
+order: 0
+ns: BigInt
+member: from
+---
+
+Lifts a plain <code>int</code> into a <code>BigInt</code>, the starting point for exact arbitrary-precision arithmetic that would overflow an ordinary integer.
+
+```ludic
+program Demo {
+  handler Step phase Update {
+    let n = BigInt.from(1000000)
+  }
+}
+```

docs/language/bigint/bigint-is_zero.md

@@ -0,0 +1,22 @@
+---
+id: bigint-is_zero
+name: BigInt.is_zero
+category: bigint
+kind: namespace-method
+tokens: BigInt.is_zero
+sig: BigInt.is_zero(a) -> bool
+tip: True when a big integer is zero.
+order: 11
+ns: BigInt
+member: is_zero
+---
+
+Returns true when the value is exactly zero — cheaper and clearer than comparing against <code>BigInt.from(0)</code>.
+
+```ludic
+program Demo {
+  handler Step phase Update {
+    if BigInt.is_zero(balance) { gameOver() }
+  }
+}
+```

docs/language/bigint/bigint-mod.md

@@ -0,0 +1,22 @@
+---
+id: bigint-mod
+name: BigInt.mod
+category: bigint
+kind: namespace-method
+tokens: BigInt.mod
+sig: BigInt.mod(a, d) -> int
+tip: Remainder of a big integer divided by an int.
+order: 8
+ns: BigInt
+member: mod
+---
+
+Returns the remainder of <code>a</code> divided by an <code>int</code> divisor, carrying the sign of <code>a</code>. Pairs with <code>BigInt.div</code>.
+
+```ludic
+program Demo {
+  handler Step phase Update {
+    let leftover = BigInt.mod(pot, players)
+  }
+}
+```

docs/language/bigint/bigint-mul.md

@@ -0,0 +1,22 @@
+---
+id: bigint-mul
+name: BigInt.mul
+category: bigint
+kind: namespace-method
+tokens: BigInt.mul
+sig: BigInt.mul(a, b) -> BigInt
+tip: Exact product of two big integers.
+order: 4
+ns: BigInt
+member: mul
+---
+
+Returns the exact product <code>a * b</code>. Multiplying two large counters never loses precision — the classic idle-game growth step.
+
+```ludic
+program Demo {
+  handler Step phase Update {
+    let next = BigInt.mul(count, multiplier)
+  }
+}
+```

docs/language/bigint/bigint-neg.md

@@ -0,0 +1,22 @@
+---
+id: bigint-neg
+name: BigInt.neg
+category: bigint
+kind: namespace-method
+tokens: BigInt.neg
+sig: BigInt.neg(a) -> BigInt
+tip: Negate a big integer.
+order: 5
+ns: BigInt
+member: neg
+---
+
+Returns <code>-a</code> — the same magnitude with the opposite sign.
+
+```ludic
+program Demo {
+  handler Step phase Update {
+    let debt = BigInt.neg(balance)
+  }
+}
+```

docs/language/bigint/bigint-parse.md

@@ -0,0 +1,22 @@
+---
+id: bigint-parse
+name: BigInt.parse
+category: bigint
+kind: namespace-method
+tokens: BigInt.parse
+sig: BigInt.parse(text) -> BigInt
+tip: Parse decimal text into a BigInt.
+order: 1
+ns: BigInt
+member: parse
+---
+
+Parses decimal text (an optional leading sign then digits) into a <code>BigInt</code> — the way to enter a value too large for an <code>int</code> literal.
+
+```ludic
+program Demo {
+  handler Step phase Update {
+    let huge = BigInt.parse("123456789012345678901234567890")
+  }
+}
+```

docs/language/bigint/bigint-pow.md

@@ -0,0 +1,22 @@
+---
+id: bigint-pow
+name: BigInt.pow
+category: bigint
+kind: namespace-method
+tokens: BigInt.pow
+sig: BigInt.pow(a, exp) -> BigInt
+tip: Raise a big integer to an int power.
+order: 6
+ns: BigInt
+member: pow
+---
+
+Raises <code>a</code> to the (non-negative) integer power <code>exp</code> by binary exponentiation — an exact way to reach astronomically large magnitudes.
+
+```ludic
+program Demo {
+  handler Step phase Update {
+    let googol = BigInt.pow(BigInt.from(10), 100)
+  }
+}
+```

docs/language/bigint/bigint-str.md

@@ -0,0 +1,22 @@
+---
+id: bigint-str
+name: BigInt.str
+category: bigint
+kind: namespace-method
+tokens: BigInt.str
+sig: BigInt.str(a) -> string
+tip: Render a big integer as decimal text.
+order: 13
+ns: BigInt
+member: str
+---
+
+Renders the full value as decimal text, with a leading <code>-</code> when negative. This is how you display or serialize a <code>BigInt</code>.
+
+```ludic
+program Demo {
+  handler Step phase Update {
+    Screen.draw_text(8, 8, BigInt.str(score), Color.White, 1)
+  }
+}
+```

docs/language/bigint/bigint-sub.md

@@ -0,0 +1,22 @@
+---
+id: bigint-sub
+name: BigInt.sub
+category: bigint
+kind: namespace-method
+tokens: BigInt.sub
+sig: BigInt.sub(a, b) -> BigInt
+tip: Exact difference of two big integers.
+order: 3
+ns: BigInt
+member: sub
+---
+
+Returns the exact difference <code>a - b</code>; the result is negative when <code>b</code> is larger.
+
+```ludic
+program Demo {
+  handler Step phase Update {
+    let remaining = BigInt.sub(bank, cost)
+  }
+}
+```

docs/language/bigint/bigint-to_int.md

@@ -0,0 +1,22 @@
+---
+id: bigint-to_int
+name: BigInt.to_int
+category: bigint
+kind: namespace-method
+tokens: BigInt.to_int
+sig: BigInt.to_int(a) -> int
+tip: Narrow a big integer to a plain int (clamped).
+order: 12
+ns: BigInt
+member: to_int
+---
+
+Returns the value as a plain <code>int</code> when it fits in 32 bits, clamping to the int min/max otherwise. Use it to feed a small big-integer back into ordinary code.
+
+```ludic
+program Demo {
+  handler Step phase Update {
+    let n = BigInt.to_int(BigInt.from(2024))
+  }
+}
+```

docs/language/decimal/_section.md

@@ -0,0 +1,7 @@
+---
+id: decimal
+title: Decimal
+order: 11
+---
+
+Exact base-10 fixed-point numbers for game economies — prices, balances and taxes on values like <code>0.10</code> that binary floating point cannot represent, so they always add up exactly. A <code>Decimal</code> is a <code>BigInt</code> mantissa with a decimal <code>scale</code> (the number of digits after the point), giving unbounded range and exact <code>add</code> / <code>sub</code> / <code>mul</code>. Build one with <code>Decimal.from</code> (an <code>int</code>) or <code>Decimal.parse</code> (text like <code>"19.99"</code>), compare with <code>cmp</code> / <code>eq</code>, change precision with <code>rescale</code> (truncates toward zero), read the current precision with <code>scale</code>, and render with <code>str</code>. Every operation is exact and deterministic. The runtime is spliced in only when a program mentions <code>Decimal.*</code> (or <code>BigInt.*</code>).

docs/language/decimal/decimal-add.md

@@ -0,0 +1,22 @@
+---
+id: decimal-add
+name: Decimal.add
+category: decimal
+kind: namespace-method
+tokens: Decimal.add
+sig: Decimal.add(a, b) -> Decimal
+tip: Exact sum of two decimals.
+order: 2
+ns: Decimal
+member: add
+---
+
+Returns the exact sum, aligning the two scales first so nothing is rounded. <code>0.10 + 0.20</code> is exactly <code>0.30</code>.
+
+```ludic
+program Demo {
+  handler Step phase Update {
+    let total = Decimal.add(subtotal, tax)
+  }
+}
+```

docs/language/decimal/decimal-cmp.md

@@ -0,0 +1,22 @@
+---
+id: decimal-cmp
+name: Decimal.cmp
+category: decimal
+kind: namespace-method
+tokens: Decimal.cmp
+sig: Decimal.cmp(a, b) -> int
+tip: Compare two decimals: -1, 0, or 1.
+order: 6
+ns: Decimal
+member: cmp
+---
+
+Compares two decimals regardless of their scales, returning <code>-1</code>, <code>0</code>, or <code>1</code>.
+
+```ludic
+program Demo {
+  handler Step phase Update {
+    if Decimal.cmp(balance, price) < 0 { deny() }
+  }
+}
+```

docs/language/decimal/decimal-eq.md

@@ -0,0 +1,22 @@
+---
+id: decimal-eq
+name: Decimal.eq
+category: decimal
+kind: namespace-method
+tokens: Decimal.eq
+sig: Decimal.eq(a, b) -> bool
+tip: True when two decimals are equal in value.
+order: 7
+ns: Decimal
+member: eq
+---
+
+Returns true when two decimals are equal in value even if written at different scales — <code>1.5</code> equals <code>1.50</code>.
+
+```ludic
+program Demo {
+  handler Step phase Update {
+    if Decimal.eq(paid, price) { accept() }
+  }
+}
+```

docs/language/decimal/decimal-from.md

@@ -0,0 +1,22 @@
+---
+id: decimal-from
+name: Decimal.from
+category: decimal
+kind: namespace-method
+tokens: Decimal.from
+sig: Decimal.from(value) -> Decimal
+tip: Turn a whole int into a Decimal.
+order: 0
+ns: Decimal
+member: from
+---
+
+Lifts a whole <code>int</code> into a <code>Decimal</code> with scale zero — a starting point for exact money arithmetic.
+
+```ludic
+program Demo {
+  handler Step phase Update {
+    let qty = Decimal.from(3)
+  }
+}
+```

docs/language/decimal/decimal-mul.md

@@ -0,0 +1,22 @@
+---
+id: decimal-mul
+name: Decimal.mul
+category: decimal
+kind: namespace-method
+tokens: Decimal.mul
+sig: Decimal.mul(a, b) -> Decimal
+tip: Exact product of two decimals.
+order: 4
+ns: Decimal
+member: mul
+---
+
+Returns the exact product; the result's scale is the sum of the operands' scales, so no precision is lost.
+
+```ludic
+program Demo {
+  handler Step phase Update {
+    let line = Decimal.mul(price, quantity)
+  }
+}
+```

docs/language/decimal/decimal-neg.md

@@ -0,0 +1,22 @@
+---
+id: decimal-neg
+name: Decimal.neg
+category: decimal
+kind: namespace-method
+tokens: Decimal.neg
+sig: Decimal.neg(a) -> Decimal
+tip: Negate a decimal.
+order: 5
+ns: Decimal
+member: neg
+---
+
+Returns <code>-a</code> at the same scale — the same magnitude with the opposite sign.
+
+```ludic
+program Demo {
+  handler Step phase Update {
+    let refund = Decimal.neg(charge)
+  }
+}
+```

docs/language/decimal/decimal-parse.md

@@ -0,0 +1,22 @@
+---
+id: decimal-parse
+name: Decimal.parse
+category: decimal
+kind: namespace-method
+tokens: Decimal.parse
+sig: Decimal.parse(text) -> Decimal
+tip: Parse decimal text like "19.99".
+order: 1
+ns: Decimal
+member: parse
+---
+
+Parses text like <code>"19.99"</code> or <code>"0.10"</code> into an exact <code>Decimal</code>, remembering how many digits followed the point. This is how you enter a price the way binary floating point never could.
+
+```ludic
+program Demo {
+  handler Step phase Update {
+    let price = Decimal.parse("19.99")
+  }
+}
+```

docs/language/decimal/decimal-rescale.md

@@ -0,0 +1,22 @@
+---
+id: decimal-rescale
+name: Decimal.rescale
+category: decimal
+kind: namespace-method
+tokens: Decimal.rescale
+sig: Decimal.rescale(d, places) -> Decimal
+tip: Change precision (truncates toward zero).
+order: 9
+ns: Decimal
+member: rescale
+---
+
+Changes the number of fractional digits. Increasing precision is exact; decreasing it truncates toward zero — how you round a computed price down to whole cents.
+
+```ludic
+program Demo {
+  handler Step phase Update {
+    let cents = Decimal.rescale(raw, 2)
+  }
+}
+```

docs/language/decimal/decimal-scale.md

@@ -0,0 +1,22 @@
+---
+id: decimal-scale
+name: Decimal.scale
+category: decimal
+kind: namespace-method
+tokens: Decimal.scale
+sig: Decimal.scale(d) -> int
+tip: The number of digits after the point.
+order: 8
+ns: Decimal
+member: scale
+---
+
+Returns the current scale — how many digits sit after the decimal point.
+
+```ludic
+program Demo {
+  handler Step phase Update {
+    let places = Decimal.scale(price)
+  }
+}
+```

docs/language/decimal/decimal-str.md

@@ -0,0 +1,22 @@
+---
+id: decimal-str
+name: Decimal.str
+category: decimal
+kind: namespace-method
+tokens: Decimal.str
+sig: Decimal.str(d) -> string
+tip: Render a decimal as text.
+order: 10
+ns: Decimal
+member: str
+---
+
+Renders the value as text with its decimal point in place (a leading <code>-</code> when negative). This is how you display or serialize money.
+
+```ludic
+program Demo {
+  handler Step phase Update {
+    Screen.draw_text(8, 8, Decimal.str(balance), Color.White, 1)
+  }
+}
+```

docs/language/decimal/decimal-sub.md

@@ -0,0 +1,22 @@
+---
+id: decimal-sub
+name: Decimal.sub
+category: decimal
+kind: namespace-method
+tokens: Decimal.sub
+sig: Decimal.sub(a, b) -> Decimal
+tip: Exact difference of two decimals.
+order: 3
+ns: Decimal
+member: sub
+---
+
+Returns the exact difference <code>a - b</code>, aligning scales so balances stay penny-accurate.
+
+```ludic
+program Demo {
+  handler Step phase Update {
+    let change = Decimal.sub(paid, price)
+  }
+}
+```