From 744d6b61d52fbc6926669dda644822c3c0590669 Mon Sep 17 00:00:00 2001
From: Horizontal42 <75383519+Horizontal42@users.noreply.github.com>
Date: Wed, 12 Aug 2026 20:07:02 +0300
Subject: [PATCH] document why evalRandom/formatFraction use native float

These two are the only intentional exceptions to the decimal.js-only
rule in the engine; leaving that unstated made them look like bugs
during review.
---
 src/engine/evaluator.ts | 3 +++
 src/engine/formatter.ts | 3 +++
 2 files changed, 6 insertions(+)

diff --git a/src/engine/evaluator.ts b/src/engine/evaluator.ts
index 02de873..67df2c4 100644
--- a/src/engine/evaluator.ts
+++ b/src/engine/evaluator.ts
@@ -547,6 +547,9 @@ function evalCall(name: string, args: Value[], ctx: EvalCtx): Value {
   }
 }
 
+// Native float, not Decimal: this is a PRNG (mulberry32/strHash bit-twiddling
+// over 32-bit ints), not arithmetic on user quantities — decimal.js has no
+// bitwise ops and would add nothing but overhead here.
 function evalRandom(args: Value[], ctx: EvalCtx): Value {
   const seed = strHash(ctx.line.lineText) ^ (ctx.line.index * 0x9e3779b9);
   const rand = mulberry32(seed);
diff --git a/src/engine/formatter.ts b/src/engine/formatter.ts
index b6a4cf0..d188eb4 100644
--- a/src/engine/formatter.ts
+++ b/src/engine/formatter.ts
@@ -109,6 +109,9 @@ function withUnit(num: string, f: string): string {
 }
 
 /** Best rational approximation via continued fractions: 0.75 -> "3/4". */
+// Native float, not Decimal: the continued-fraction algorithm is tuned to
+// float epsilon by design, and this is display formatting, not arithmetic
+// carried forward into the result.
 function formatFraction(v: Decimal): string {
   const neg = v.isNegative();
   const x = v.abs().toNumber();