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))
+  }
+}
+```