arbitrary-numbers 1.1.0 → 2.0.0

package/dist/index.d.cts

@@ -1,17 +1,3 @@
-/**
- * A number stored in normalised scientific notation as `coefficient * 10^exponent`,
- * where `1 <= |coefficient| < 10` (or `coefficient === 0`).
- *
- * @example
- * const n: NormalizedNumber = { coefficient: 1.5, exponent: 3 }; // 1500
- * const z: NormalizedNumber = { coefficient: 0,   exponent: 0 }; // 0
- */
-interface NormalizedNumber {
-    /** The significand, always in `[1, 10)` or `0`. */
-    coefficient: number;
-    /** The power of 10 by which the coefficient is scaled. */
-    exponent: number;
-}
 /** The result of a three-way comparison: negative, zero, or positive. */
 type Signum = -1 | 0 | 1;
 /** Remainder after dividing an exponent by 3 - the within-tier offset. */
@@ -224,504 +210,415 @@ interface UnitNotationOptions extends SuffixNotationPluginOptions {
 }
 
 /**
- * An immutable number with effectively unlimited range, stored as `coefficient * 10^exponent`
+ * Global tunables for `ArbitraryNumber`.
+ *
+ * Mutating these is a process-level change — not per-instance.
+ */
+interface ArbitraryNumberDefaults {
+    /**
+     * Exponent-difference threshold below which the smaller operand is negligible
+     * and silently skipped during addition/subtraction.
+     *
+     * Default: 15 (matches float64 coefficient precision of ~15.95 significant digits).
+     */
+    scaleCutoff: number;
+    /** Default decimal places used by `toString()` when no argument is supplied. */
+    notationDecimals: number;
+}
+/**
+ * A mutable number with effectively unlimited range, stored as `coefficient * 10^exponent`
  * in normalised scientific notation.
  *
- * The coefficient is always in `[1, 10)` (or `0`). Addition short-circuits when the exponent
- * difference between operands exceeds {@link PrecisionCutoff} - the smaller value is below
- * the precision floor of the larger and is silently discarded.
+ * The coefficient is always in `[1, 10)` (or `0`). Arithmetic methods **mutate `this`** and
+ * return `this` — enabling zero-allocation chaining on the hot path:
+ *
+ * ```ts
+ * gold.add(drop).sub(cost).mul(multiplier);
+ * ```
+ *
+ * Call `.clone()` before any operation where you need to preserve the original value.
+ *
+ * Addition short-circuits when the exponent difference between operands exceeds
+ * {@link ArbitraryNumber.defaults.scaleCutoff} — the smaller value is below the precision
+ * floor and is silently discarded.
+ *
+ * **Static = allocate. Instance = mutate.**
+ * Static arithmetic methods (`ArbitraryNumber.add`, etc.) always return a new instance.
+ * Instance methods (`a.add(b)`) mutate `a` and return `a`.
  *
  * @example
- * const a = new ArbitraryNumber(1.5, 3);  // 1,500
- * const b = new ArbitraryNumber(2.5, 3);  // 2,500
- * a.add(b).toString(); // "4.00e+3"
- * a.mul(b).toString(); // "3.75e+6"
+ * const gold = new ArbitraryNumber(1.5, 3);  // 1_500
+ * gold.add(drop).sub(cost).mul(multiplier);  // mutates gold
+ * const snapshot = gold.clone();             // safe copy
  */
-declare class ArbitraryNumber implements NormalizedNumber {
+declare class ArbitraryNumber {
     /** The significand, always in `[1, 10)` or `0`. */
-    readonly coefficient: number;
+    coefficient: number;
     /** The power of 10 by which the coefficient is scaled. */
-    readonly exponent: number;
+    exponent: number;
+    /** Global tunables. Mutating these is a process-level change. */
+    static readonly defaults: ArbitraryNumberDefaults;
+    /** The additive identity: `0`. Frozen — calling mutating methods throws. */
+    static readonly Zero: FrozenArbitraryNumber;
+    /** The multiplicative identity: `1`. Frozen — calling mutating methods throws. */
+    static readonly One: FrozenArbitraryNumber;
+    /** `10`. Frozen — calling mutating methods throws. */
+    static readonly Ten: FrozenArbitraryNumber;
     /**
-     * Precision cutoff: exponent-difference threshold below which the smaller operand
-     * is negligible and silently skipped during addition/subtraction.
+     * Constructs a new `ArbitraryNumber` and immediately normalises it so that
+     * `1 <= |coefficient| < 10` (or `coefficient === 0`).
      *
-     * When |exponent_diff| > PrecisionCutoff, the smaller operand contributes less than
-     * 10^-PrecisionCutoff of the result - below float64 coefficient precision for the default of 15.
+     * Always two numeric arguments — this keeps the constructor monomorphic so V8
+     * locks in a hidden class on first use (~5 ns allocation).
      *
-     * Default: 15 (matches float64 coefficient precision of ~15.95 significant digits).
-     * Game patterns: diffs 0-8 (exact), prestige 15-25 (loss <0.0001%), idle 20-50 (~0.1% loss).
+     * @example
+     * new ArbitraryNumber(15, 3); // stored as { coefficient: 1.5, exponent: 4 }
      *
-     * Override globally via assignment, or use {@link withPrecision} for a scoped block.
+     * @throws `ArbitraryNumberInputError` for `NaN`/`Infinity` coefficient or exponent.
      */
-    static PrecisionCutoff: number;
-    /** The additive identity: `0`. */
-    static readonly Zero: ArbitraryNumber;
-    /** The multiplicative identity: `1`. */
-    static readonly One: ArbitraryNumber;
-    /** `10`. */
-    static readonly Ten: ArbitraryNumber;
+    constructor(coefficient: number, exponent: number);
+    /**
+     * @internal Fast-path factory for already-normalised values. Not exported from `index.ts`.
+     *
+     * Allocates a new instance and writes the two fields directly — bypasses validation
+     * and normalisation. Only valid when `|coefficient|` is already in `[1, 10)` (or 0)
+     * and `exponent` is correct.
+     */
+    static unsafe(coefficient: number, exponent: number): ArbitraryNumber;
+    /** @internal Normalise an arbitrary `(c, e)` pair into a new instance. */
+    private static _normalizeNew;
+    /** @internal Normalise `(c, e)` into `this` (mutates). Returns `this`. */
+    private _normalizeInto;
+    /**
+     * Returns a fresh, unfrozen copy of this number. The canonical way to preserve
+     * a value before mutating it:
+     *
+     * ```ts
+     * const before = gold.clone();
+     * gold.add(drop);
+     * ```
+     */
+    clone(): ArbitraryNumber;
     /**
      * Creates an `ArbitraryNumber` from a plain JavaScript `number`.
      *
-     * Prefer this over `new ArbitraryNumber(value, 0)` when working with
-     * ordinary numeric literals - it reads clearly at the call site and
-     * validates the input.
+     * @throws `ArbitraryNumberInputError` for `NaN`, `Infinity`, or `-Infinity`.
      *
      * @example
-     * ArbitraryNumber.from(1500);   // { coefficient: 1.5, exponent: 3 }
-     * ArbitraryNumber.from(0.005);  // { coefficient: 5,   exponent: -3 }
-     * ArbitraryNumber.from(0);      // ArbitraryNumber.Zero
-     * ArbitraryNumber.from(-0);     // ArbitraryNumber.Zero  (signed zero is normalised to +0)
-     *
-     * @param value - Any finite number. Signed zero (`-0`) is treated as `0`.
-     * @throws `"ArbitraryNumber.from: value must be finite"` for `NaN`, `Infinity`, or `-Infinity`.
+     * ArbitraryNumber.from(1500);  // { coefficient: 1.5, exponent: 3 }
      */
     static from(value: number): ArbitraryNumber;
     /**
-     * Constructs a new `ArbitraryNumber` and immediately normalises it so that
-     * `1 <= |coefficient| < 10` (or `coefficient === 0`).
+     * Like `from`, but returns `null` instead of throwing for non-finite inputs.
+     *
+     * Use at system boundaries (form inputs, external APIs) where bad input should
+     * be handled gracefully.
      *
      * @example
-     * new ArbitraryNumber(15, 3); // stored as { coefficient: 1.5, exponent: 4 }
+     * ArbitraryNumber.tryFrom(Infinity) // null
+     * ArbitraryNumber.tryFrom(1500)     // ArbitraryNumber { coefficient: 1.5, exponent: 3 }
+     */
+    static tryFrom(value: number): Nullable<ArbitraryNumber>;
+    /**
+     * Returns a **new** instance equal to `a + b`.
      *
-     * @param coefficient - The significand. Must be a finite number; will be normalised.
-     * @param exponent - The power of 10. Must be a finite number.
-     * @throws `"ArbitraryNumber: coefficient must be finite"` for `NaN`, `Infinity`, or `-Infinity`.
-     * @throws `"ArbitraryNumber: exponent must be finite"` for non-finite exponents.
+     * Static methods always allocate — use instance `.add()` on hot paths.
      */
-    constructor(coefficient: number, exponent: number);
+    static add(a: ArbitraryNumber, b: ArbitraryNumber): ArbitraryNumber;
+    /**
+     * Returns a **new** instance equal to `a - b`.
+     */
+    static sub(a: ArbitraryNumber, b: ArbitraryNumber): ArbitraryNumber;
+    /**
+     * Returns a **new** instance equal to `a * b`.
+     */
+    static mul(a: ArbitraryNumber, b: ArbitraryNumber): ArbitraryNumber;
     /**
-     * @internal Fast-path factory for already-normalised values.
+     * Returns a **new** instance equal to `a / b`.
      *
-     * Uses Object.create() to bypass the constructor (zero normalisation cost).
-     * Only valid when |coefficient| is already in [1, 10) and exponent is correct.
-     * Do NOT use for unnormalised inputs - call new ArbitraryNumber(c, e) instead.
+     * @throws `"Division by zero"` when `b` is zero.
      */
-    private static createNormalized;
-    private static normalizeFrom;
+    static div(a: ArbitraryNumber, b: ArbitraryNumber): ArbitraryNumber;
     /**
-     * Returns `this + other`.
+     * Adds `other` to this number in-place.
      *
-     * When the exponent difference exceeds {@link PrecisionCutoff}, the smaller
-     * operand has no effect and the larger is returned as-is.
+     * When the exponent difference exceeds `defaults.scaleCutoff`, the smaller
+     * operand has no effect and `this` is returned unchanged.
+     *
+     * **Mutates `this`. Returns `this`.**
      *
      * @example
-     * new ArbitraryNumber(1.5, 3).add(new ArbitraryNumber(2.5, 3)); // 4*10^3
+     * gold.add(drop); // gold is mutated
      */
-    add(other: ArbitraryNumber): ArbitraryNumber;
+    add(other: ArbitraryNumber): this;
     /**
-     * Returns `this - other`.
+     * Subtracts `other` from this number in-place.
      *
-     * @example
-     * new ArbitraryNumber(3.5, 3).sub(new ArbitraryNumber(1.5, 3)); // 2*10^3
+     * **Mutates `this`. Returns `this`.**
      */
-    sub(other: ArbitraryNumber): ArbitraryNumber;
+    sub(other: ArbitraryNumber): this;
     /**
-     * Returns `this * other`.
+     * Multiplies this number by `other` in-place.
      *
-     * @example
-     * new ArbitraryNumber(2, 3).mul(new ArbitraryNumber(3, 4)); // 6*10^7
+     * **Mutates `this`. Returns `this`.**
      */
-    mul(other: ArbitraryNumber): ArbitraryNumber;
+    mul(other: ArbitraryNumber): this;
     /**
-     * Returns `this / other`.
+     * Divides this number by `other` in-place.
      *
-     * @example
-     * new ArbitraryNumber(6, 7).div(new ArbitraryNumber(3, 4)); // 2*10^3
+     * **Mutates `this`. Returns `this`.**
      *
      * @throws `"Division by zero"` when `other` is zero.
      */
-    div(other: ArbitraryNumber): ArbitraryNumber;
+    div(other: ArbitraryNumber): this;
     /**
-     * Returns the arithmetic negation of this number (`-this`).
+     * Negates this number in-place.
      *
-     * @example
-     * new ArbitraryNumber(1.5, 3).negate(); // -1.5*10^3
+     * **Mutates `this`. Returns `this`.**
      */
-    negate(): ArbitraryNumber;
+    negate(): this;
     /**
-     * Returns the absolute value of this number (`|this|`).
-     *
-     * Returns `this` unchanged when the number is already non-negative.
+     * Sets this number to its absolute value in-place.
      *
-     * @example
-     * new ArbitraryNumber(-1.5, 3).abs(); // 1.5*10^3
+     * **Mutates `this`. Returns `this`.**
      */
-    abs(): ArbitraryNumber;
+    abs(): this;
     /**
-     * Returns `this^n`.
+     * Raises this number to the power `n` in-place.
      *
      * Supports integer, fractional, and negative exponents.
-     * `x^0` always returns {@link One}, including `0^0` (by convention).
+     * `x^0` always sets `this` to `1`, including `0^0` (by convention).
      *
-     * @example
-     * new ArbitraryNumber(2, 3).pow(2);  // 4*10^6
-     * new ArbitraryNumber(2, 0).pow(-1); // 5*10^-1  (= 0.5)
+     * **Mutates `this`. Returns `this`.**
      *
-     * @param n - The exponent to raise this number to.
      * @throws `"Zero cannot be raised to a negative power"` when this is zero and `n < 0`.
      */
-    pow(n: number): ArbitraryNumber;
+    pow(n: number): this;
     /**
-     * Fused multiply-add: `(this * multiplier) + addend`.
-     *
-     * Faster than `.mul(multiplier).add(addend)` because it avoids allocating an
-     * intermediate ArbitraryNumber for the product. One normalisation pass total.
+     * Fused multiply-add in-place: `this = (this * multiplier) + addend`.
      *
-     * Common pattern - prestige loop: `value = value.mulAdd(prestigeMultiplier, prestigeBoost)`
+     * Faster than `.mul(multiplier).add(addend)` — one normalisation pass total, no
+     * intermediate allocation.
      *
-     * @example
-     * // Equivalent to value.mul(mult).add(boost) but ~35-50% faster
-     * const prestiged = currentValue.mulAdd(multiplier, boost);
+     * **Mutates `this`. Returns `this`.**
      */
-    mulAdd(multiplier: ArbitraryNumber, addend: ArbitraryNumber): ArbitraryNumber;
+    mulAdd(multiplier: ArbitraryNumber, addend: ArbitraryNumber): this;
     /**
-     * Fused add-multiply: `(this + addend) * multiplier`.
-     *
-     * Faster than `.add(addend).mul(multiplier)` because it avoids allocating an
-     * intermediate ArbitraryNumber for the sum. One normalisation pass total.
-     *
-     * Common pattern - upgrade calculation: `newValue = baseValue.addMul(bonus, multiplier)`
+     * @internal
+     * Computes `(this + sign * addendC * 10^addendE)` and writes the normalised
+     * result back into `this`. Used by `addMul` and `subMul` to share the alignment
+     * logic without duplication.
      *
-     * @example
-     * // Equivalent to base.add(bonus).mul(multiplier) but ~20-25% faster
-     * const upgraded = baseValue.addMul(bonus, multiplier);
+     * Returns the sign-adjusted addend coefficient so callers can detect the
+     * zero-result case. Writes the intermediate normalised sum into `this.coefficient`
+     * / `this.exponent` ready for the subsequent multiply step.
      */
-    addMul(addend: ArbitraryNumber, multiplier: ArbitraryNumber): ArbitraryNumber;
+    private _addScaledInto;
     /**
-     * Fused multiply-subtract: `(this * multiplier) - subtrahend`.
-     *
-     * Avoids one intermediate allocation vs `.mul(multiplier).sub(subtrahend)`.
+     * Fused add-multiply in-place: `this = (this + addend) * multiplier`.
      *
-     * Common pattern - resource drain: `income.mulSub(rate, upkeepCost)`
+     * **Mutates `this`. Returns `this`.**
      */
-    mulSub(multiplier: ArbitraryNumber, subtrahend: ArbitraryNumber): ArbitraryNumber;
+    addMul(addend: ArbitraryNumber, multiplier: ArbitraryNumber): this;
     /**
-     * Fused subtract-multiply: `(this - subtrahend) * multiplier`.
-     *
-     * Avoids one intermediate allocation vs `.sub(subtrahend).mul(multiplier)`.
+     * Fused multiply-subtract in-place: `this = (this * multiplier) - subtrahend`.
      *
-     * Common pattern - upgrade after penalty: `health.subMul(damage, multiplier)`
+     * **Mutates `this`. Returns `this`.**
      */
-    subMul(subtrahend: ArbitraryNumber, multiplier: ArbitraryNumber): ArbitraryNumber;
+    mulSub(multiplier: ArbitraryNumber, subtrahend: ArbitraryNumber): this;
     /**
-     * Fused divide-add: `(this / divisor) + addend`.
+     * Fused subtract-multiply in-place: `this = (this - subtrahend) * multiplier`.
      *
-     * Avoids one intermediate allocation vs `.div(divisor).add(addend)`.
+     * **Mutates `this`. Returns `this`.**
+     */
+    subMul(subtrahend: ArbitraryNumber, multiplier: ArbitraryNumber): this;
+    /**
+     * Fused divide-add in-place: `this = (this / divisor) + addend`.
      *
-     * Common pattern - efficiency bonus: `damage.divAdd(armor, flat)`
+     * **Mutates `this`. Returns `this`.**
      *
      * @throws `"Division by zero"` when divisor is zero.
      */
-    divAdd(divisor: ArbitraryNumber, addend: ArbitraryNumber): ArbitraryNumber;
+    divAdd(divisor: ArbitraryNumber, addend: ArbitraryNumber): this;
     /**
-     * Fused multiply-divide: `(this * multiplier) / divisor`.
+     * Fused multiply-divide in-place: `this = (this * multiplier) / divisor`.
      *
-     * Avoids one intermediate allocation vs `.mul(multiplier).div(divisor)`.
-     * The divisor zero-check is performed before the multiply to avoid unnecessary work.
-     *
-     * Common pattern - idle-tick math: `(production * deltaTime) / cost`
-     *
-     * @example
-     * // Equivalent to production.mul(deltaTime).div(cost) but ~30-40% faster
-     * const consumed = production.mulDiv(deltaTime, cost);
+     * **Mutates `this`. Returns `this`.**
      *
      * @throws `"Division by zero"` when divisor is zero.
      */
-    mulDiv(multiplier: ArbitraryNumber, divisor: ArbitraryNumber): ArbitraryNumber;
+    mulDiv(multiplier: ArbitraryNumber, divisor: ArbitraryNumber): this;
     /**
-     * Efficiently sums an array of ArbitraryNumbers in a single normalisation pass.
-     *
-     * **Why it's fast:** standard chained `.add()` normalises after every element (N log10 calls).
-     * `sumArray` aligns all coefficients to the largest exponent (pivot), sums them,
-     * then normalises once - regardless of array size.
-     *
-     * For 50 elements: chained add ~ 50 log10 calls + 50 allocations;
-     * sumArray ~ 50 divisions + 1 log10 call + 1 allocation -> ~9* faster.
+     * Efficiently sums an array of `ArbitraryNumber`s in a single pass.
      *
-     * Common pattern - income aggregation: `total = ArbitraryNumber.sumArray(incomeSourcesPerTick)`
+     * Maintains a running pivot exponent and rescales the accumulator when a larger
+     * exponent is encountered — one pass, no pre-scan needed.
      *
-     * @example
-     * const total = ArbitraryNumber.sumArray(incomeSources); // far faster than .reduce((a, b) => a.add(b))
-     *
-     * @param numbers - Array to sum. Empty array returns {@link Zero}. Single element returned as-is.
+     * Empty array returns `Zero`. Single element returned as-is (no clone).
      */
     static sumArray(numbers: ArbitraryNumber[]): ArbitraryNumber;
     /**
      * Multiplies an array of `ArbitraryNumber`s in a single pass.
      *
-     * Coefficients are multiplied together with intermediate normalisation after each step
-     * to keep values in [1, 10). Exponents are summed. One total normalisation at the end.
-     *
-     * Empty array returns {@link One}. Single element returned as-is.
-     *
-     * @example
-     * ArbitraryNumber.productArray([an(2), an(3), an(4)]); // 24
+     * Empty array returns `One`. Single element returned as-is.
      */
     static productArray(numbers: ArbitraryNumber[]): ArbitraryNumber;
     /**
-     * Returns the largest value in an array.
-     *
-     * Empty array returns {@link Zero}. Single element returned as-is.
-     *
-     * @example
-     * ArbitraryNumber.maxOfArray([an(1), an(3), an(2)]); // an(3)
+     * Returns the largest value in an array. Empty array returns `Zero`.
      */
     static maxOfArray(numbers: ArbitraryNumber[]): ArbitraryNumber;
     /**
-     * Returns the smallest value in an array.
-     *
-     * Empty array returns {@link Zero}. Single element returned as-is.
-     *
-     * @example
-     * ArbitraryNumber.minOfArray([an(3), an(1), an(2)]); // an(1)
+     * Returns the smallest value in an array. Empty array returns `Zero`.
      */
     static minOfArray(numbers: ArbitraryNumber[]): ArbitraryNumber;
     /**
-     * Compares this number to `other`.
-     *
-     * @returns `1` if `this > other`, `-1` if `this < other`, `0` if equal.
+     * Rounds down to the nearest integer in-place (floor toward −∞).
      *
-     * @example
-     * new ArbitraryNumber(1, 4).compareTo(new ArbitraryNumber(9, 3)); // 1  (10000 > 9000)
-     * new ArbitraryNumber(-1, 4).compareTo(new ArbitraryNumber(1, 3)); // -1 (-10000 < 1000)
+     * **Mutates `this`. Returns `this`.**
      */
-    compareTo(other: ArbitraryNumber): number;
-    /** Returns `true` if `this > other`. */
-    greaterThan(other: ArbitraryNumber): boolean;
-    /** Returns `true` if `this < other`. */
-    lessThan(other: ArbitraryNumber): boolean;
-    /** Returns `true` if `this >= other`. */
-    greaterThanOrEqual(other: ArbitraryNumber): boolean;
-    /** Returns `true` if `this <= other`. */
-    lessThanOrEqual(other: ArbitraryNumber): boolean;
-    /** Returns `true` if `this === other` in value. */
-    equals(other: ArbitraryNumber): boolean;
+    floor(): this;
     /**
-     * Returns the largest integer less than or equal to this number (floor toward -Infinity).
+     * Rounds up to the nearest integer in-place (ceil toward +∞).
      *
-     * Numbers with `exponent >= PrecisionCutoff` are already integers at that scale
-     * and are returned unchanged.
-     *
-     * @example
-     * new ArbitraryNumber(1.7, 0).floor();  // 1
-     * new ArbitraryNumber(-1.7, 0).floor(); // -2
+     * **Mutates `this`. Returns `this`.**
      */
-    floor(): ArbitraryNumber;
+    ceil(): this;
     /**
-     * Returns the smallest integer greater than or equal to this number (ceil toward +Infinity).
+     * Rounds to the nearest integer in-place.
      *
-     * Numbers with `exponent >= PrecisionCutoff` are already integers at that scale
-     * and are returned unchanged.
+     * Uses `Math.round` semantics: half-values round toward positive infinity
+     * (`0.5 → 1`, `-0.5 → 0`). This matches JavaScript's built-in convention.
      *
-     * @example
-     * new ArbitraryNumber(1.2, 0).ceil();  // 2
-     * new ArbitraryNumber(-1.7, 0).ceil(); // -1
+     * **Mutates `this`. Returns `this`.**
      */
-    ceil(): ArbitraryNumber;
+    round(): this;
     /**
-     * Clamps `value` to the inclusive range `[min, max]`.
-     *
-     * @example
-     * ArbitraryNumber.clamp(new ArbitraryNumber(5, 2), new ArbitraryNumber(1, 3), new ArbitraryNumber(2, 3)); // 1*10^3  (500 clamped to [1000, 2000])
+     * Truncates toward zero in-place.
      *
-     * @param value - The value to clamp.
-     * @param min - Lower bound (inclusive).
-     * @param max - Upper bound (inclusive).
+     * **Mutates `this`. Returns `this`.**
      */
-    static clamp(value: ArbitraryNumber, min: ArbitraryNumber, max: ArbitraryNumber): ArbitraryNumber;
+    trunc(): this;
     /**
-     * Returns the smaller of `a` and `b`.
-     * @example ArbitraryNumber.min(a, b)
-     */
-    static min(a: ArbitraryNumber, b: ArbitraryNumber): ArbitraryNumber;
-    /**
-     * Returns the larger of `a` and `b`.
-     * @example ArbitraryNumber.max(a, b)
-     */
-    static max(a: ArbitraryNumber, b: ArbitraryNumber): ArbitraryNumber;
-    /**
-     * Linear interpolation: `a + (b - a) * t` where `t in [0, 1]` is a plain number.
+     * Returns √this in-place.
      *
-     * Used for smooth animations and tweening in game UIs.
-     * `t = 0` returns `a`; `t = 1` returns `b`.
+     * **Mutates `this`. Returns `this`.**
      *
-     * @param t - Interpolation factor as a plain `number`. Values outside [0, 1] are allowed (extrapolation).
-     * @example
-     * ArbitraryNumber.lerp(an(100), an(200), 0.5); // 150
+     * @throws `"Square root of negative number"` when this is negative.
      */
-    static lerp(a: ArbitraryNumber, b: ArbitraryNumber, t: number): ArbitraryNumber;
+    sqrt(): this;
     /**
-     * Runs `fn` with `PrecisionCutoff` temporarily set to `cutoff`, then restores the previous value.
-     *
-     * Useful when one section of code needs different precision than the rest.
+     * Returns ∛this in-place.
      *
-     * @example
-     * // Run financial calculation with higher precision
-     * const result = ArbitraryNumber.withPrecision(50, () => a.add(b));
+     * **Mutates `this`. Returns `this`.**
      */
-    static withPrecision<T>(cutoff: number, fn: () => T): T;
+    cbrt(): this;
     /**
-     * Returns `log10(this)` as a plain JavaScript `number`.
-     *
-     * Because the number is stored as `c * 10^e`, this is computed exactly as
-     * `log10(c) + e` - no precision loss from the exponent.
-     *
-     * @example
-     * new ArbitraryNumber(1, 6).log10();    // 6
-     * new ArbitraryNumber(1.5, 3).log10();  // log10(1.5) + 3  ~ 3.176
+     * Returns `log10(this)` as a plain `number`.
      *
      * @throws `"Logarithm of zero is undefined"` when this is zero.
      * @throws `"Logarithm of a negative number is undefined"` when this is negative.
      */
     log10(): number;
     /**
-     * Returns √this.
-     *
-     * Computed as pure coefficient math - no `Math.log10` call. Cost: one `Math.sqrt`.
-     * For even exponents: `sqrt(c) * 10^(e/2)`.
-     * For odd exponents: `sqrt(c * 10) * 10^((e-1)/2)`.
-     *
-     * @throws `"Square root of negative number"` when this is negative.
-     * @example
-     * new ArbitraryNumber(4, 0).sqrt();   // 2
-     * new ArbitraryNumber(1, 4).sqrt();   // 1*10^2  (= 100)
-     */
-    sqrt(): ArbitraryNumber;
-    /**
-     * Returns the cube root of this number: `∛this`.
-     *
-     * Computed without `Math.log10`. For exponents divisible by 3: `cbrt(c) * 10^(e/3)`.
-     * For remainder 1: `cbrt(c * 10) * 10^((e-1)/3)`.
-     * For remainder 2: `cbrt(c * 100) * 10^((e-2)/3)`.
-     *
-     * Supports negative numbers (cube root of a negative is negative).
-     *
-     * @example
-     * new ArbitraryNumber(8, 0).cbrt();   // 2
-     * new ArbitraryNumber(1, 9).cbrt();   // 1*10^3  (= 1,000)
-     * new ArbitraryNumber(-8, 0).cbrt();  // -2
-     */
-    cbrt(): ArbitraryNumber;
-    /**
-     * Returns `log_base(this)` as a plain JavaScript `number`.
-     *
-     * Computed as `log10(this) / log10(base)`. The numerator is exact due to the
-     * stored `coefficient × 10^exponent` form.
+     * Returns `log_base(this)` as a plain `number`.
      *
-     * @param base - The logarithm base. Must be positive and not 1.
-     * @throws `"Logarithm of zero is undefined"` when this is zero.
-     * @throws `"Logarithm of a negative number is undefined"` when this is negative.
+     * @param base - Must be positive and not 1.
      * @throws `"Logarithm base must be positive and not 1"` for invalid base.
-     *
-     * @example
-     * new ArbitraryNumber(8, 0).log(2);    // 3
-     * new ArbitraryNumber(1, 6).log(10);   // 6
      */
     log(base: number): number;
     /**
-     * Returns `ln(this)` — the natural logarithm — as a plain JavaScript `number`.
-     *
-     * Computed as `log10(this) / log10(e)`.
-     *
-     * @throws `"Logarithm of zero is undefined"` when this is zero.
-     * @throws `"Logarithm of a negative number is undefined"` when this is negative.
-     *
-     * @example
-     * new ArbitraryNumber(1, 0).ln();  // 0
+     * Returns `ln(this)` as a plain `number`.
      */
     ln(): number;
     /**
-     * Returns `10^n` as an `ArbitraryNumber`, where `n` is a plain JS `number`.
-     *
-     * This is the inverse of {@link log10}. Useful for converting a log10 result
-     * back into an `ArbitraryNumber`.
-     *
-     * @example
-     * ArbitraryNumber.exp10(6);    // 1*10^6  (= 1,000,000)
-     * ArbitraryNumber.exp10(3.5);  // 10^3.5 ≈ 3162.3
+     * Returns `10^n` as a new `ArbitraryNumber`.
      *
      * @throws `"ArbitraryNumber.exp10: n must be finite"` for non-finite `n`.
      */
     static exp10(n: number): ArbitraryNumber;
     /**
-     * Returns the nearest integer value (rounds half-up).
-     *
-     * Numbers with `exponent >= PrecisionCutoff` are already integers at that scale
-     * and are returned unchanged.
+     * Compares this number to `other`.
      *
-     * @example
-     * new ArbitraryNumber(1.5, 0).round();  // 2
-     * new ArbitraryNumber(1.4, 0).round();  // 1
-     * new ArbitraryNumber(-1.5, 0).round(); // -1 (half-up toward positive infinity)
+     * @returns `1` if `this > other`, `-1` if `this < other`, `0` if equal.
      */
-    round(): ArbitraryNumber;
+    compareTo(other: ArbitraryNumber): number;
+    /** Returns `true` if `this > other`. */
+    greaterThan(other: ArbitraryNumber): boolean;
+    /** Returns `true` if `this < other`. */
+    lessThan(other: ArbitraryNumber): boolean;
+    /** Returns `true` if `this >= other`. */
+    greaterThanOrEqual(other: ArbitraryNumber): boolean;
+    /** Returns `true` if `this <= other`. */
+    lessThanOrEqual(other: ArbitraryNumber): boolean;
+    /** Returns `true` if `this === other` in value. */
+    equals(other: ArbitraryNumber): boolean;
     /**
-     * Returns the integer part of this number, truncating toward zero.
-     *
-     * Unlike `floor()`, which rounds toward −∞, `trunc()` always rounds toward 0:
-     * - `trunc(1.7)  = 1`  (same as floor)
-     * - `trunc(-1.7) = -1` (different from floor, which gives -2)
-     *
-     * Numbers with `exponent >= PrecisionCutoff` are already integers and returned unchanged.
+     * Clamps `value` to the inclusive range `[min, max]`. Returns one of the three
+     * inputs (no allocation).
+     */
+    static clamp(value: ArbitraryNumber, min: ArbitraryNumber, max: ArbitraryNumber): ArbitraryNumber;
+    /** Returns the smaller of `a` and `b`. */
+    static min(a: ArbitraryNumber, b: ArbitraryNumber): ArbitraryNumber;
+    /** Returns the larger of `a` and `b`. */
+    static max(a: ArbitraryNumber, b: ArbitraryNumber): ArbitraryNumber;
+    /**
+     * Linear interpolation: `a + (b - a) * t`.
      *
-     * @example
-     * new ArbitraryNumber(1.7, 0).trunc();   //  1
-     * new ArbitraryNumber(-1.7, 0).trunc();  // -1
+     * Returns `a` unchanged when `t === 0`, `b` unchanged when `t === 1`.
+     * All other values of `t` allocate and return a fresh instance.
      */
-    trunc(): ArbitraryNumber;
+    static lerp(a: ArbitraryNumber, b: ArbitraryNumber, t: number): ArbitraryNumber;
+    /**
+     * Runs `fn` with `defaults.scaleCutoff` temporarily set to `cutoff`, then restores it.
+     */
+    static withPrecision<T>(cutoff: number, fn: () => T): T;
+    /** Returns `true` when this number is zero. */
+    isZero(): boolean;
+    /** Returns `true` when this number is strictly positive. */
+    isPositive(): boolean;
+    /** Returns `true` when this number is strictly negative. */
+    isNegative(): boolean;
+    /**
+     * Returns `true` when this number has no fractional part.
+     * Numbers with `exponent >= scaleCutoff` are always considered integers.
+     */
+    isInteger(): boolean;
     /**
      * Returns `1` if positive, `-1` if negative, `0` if zero.
-     *
-     * @example
-     * new ArbitraryNumber(1.5, 3).sign();  // 1
-     * new ArbitraryNumber(-1.5, 3).sign(); // -1
-     * ArbitraryNumber.Zero.sign();         // 0
      */
     sign(): Signum;
     /**
-     * Converts to a plain JavaScript `number`.
+     * Returns a `FrozenArbitraryNumber` wrapping the same value.
      *
-     * Precision is limited to float64 (~15 significant digits).
-     * Returns `Infinity` for exponents beyond the float64 range (>=308).
-     * Returns `0` for exponents below the float64 range (<=-324).
+     * Mutating methods on the frozen instance throw `ArbitraryNumberMutationError`.
+     * Call `.clone()` on the frozen instance to get a fresh, mutable copy.
+     */
+    freeze(): FrozenArbitraryNumber;
+    /**
+     * Converts to a plain JavaScript `number`.
      *
-     * @example
-     * new ArbitraryNumber(1.5, 3).toNumber();  // 1500
-     * new ArbitraryNumber(1, 400).toNumber();  // Infinity
+     * Returns `Infinity` for exponents beyond float64 range (>=308).
+     * Returns `0` for exponents below float64 range (<=-324).
      */
     toNumber(): number;
     /**
      * Returns a stable, minimal JSON representation: `{ c: number, e: number }`.
      *
-     * The keys `c` and `e` are intentionally short to keep save-game blobs small.
-     * Reconstruct via {@link ArbitraryNumber.fromJSON}.
-     *
      * Round-trip guarantee: `ArbitraryNumber.fromJSON(x.toJSON()).equals(x)` is always `true`.
-     *
-     * @example
-     * JSON.stringify(an(1.5, 6)); // '{"c":1.5,"e":6}'
      */
     toJSON(): ArbitraryNumberJson;
     /**
-     * Returns a raw string representation: `"<coefficient>|<exponent>"`.
+     * Returns a compact string representation: `"<coefficient>|<exponent>"`.
      *
-     * Useful for compact textual serialization. Reconstruct via {@link ArbitraryNumber.parse}.
+     * Shorter than JSON for save-game serialisation. Reconstruct via `ArbitraryNumber.parse`.
      *
      * @example
-     * an(1.5, 3).toRaw();  // "1.5|3"
-     * an(-2, 6).toRaw();   // "-2|6"
+     * an(1500).toRawString() // "1.5|3"
      */
-    toRaw(): string;
+    toRawString(): string;
     /**
      * Reconstructs an `ArbitraryNumber` from a `toJSON()` blob.
      *
-     * @example
-     * const n = an(1.5, 6);
-     * ArbitraryNumber.fromJSON(n.toJSON()).equals(n); // true
-     *
-     * @param obj - Object with numeric `c` (coefficient) and `e` (exponent) fields.
      * @throws `ArbitraryNumberInputError` when the object shape is invalid or values are non-finite.
      */
     static fromJSON(obj: unknown): ArbitraryNumber;
@@ -729,52 +626,61 @@ declare class ArbitraryNumber implements NormalizedNumber {
      * Parses a string into an `ArbitraryNumber`.
      *
      * Accepted formats:
-     * - Raw pipe format (exact round-trip): `"1.5|3"`, `"-2.5|-6"`
-     * - Standard scientific notation: `"1.5e+3"`, `"1.5e-3"`, `"1.5E3"`, `"1.5e3"`
+     * - Raw pipe format: `"1.5|3"`, `"-2.5|-6"`
+     * - Scientific notation: `"1.5e+3"`, `"1.5E3"`
      * - Plain decimal: `"1500"`, `"-0.003"`, `"0"`
      *
-     * @example
-     * ArbitraryNumber.parse("1.5|3");    // same as an(1.5, 3)
-     * ArbitraryNumber.parse("1.5e+3");   // same as ArbitraryNumber.from(1500)
-     * ArbitraryNumber.parse("1500");     // same as ArbitraryNumber.from(1500)
-     *
-     * @throws `ArbitraryNumberInputError` when the string cannot be parsed or produces a non-finite value.
+     * @throws `ArbitraryNumberInputError` for invalid or non-finite input.
      */
     static parse(s: string): ArbitraryNumber;
-    /** Returns `true` when this number is zero. */
-    isZero(): boolean;
-    /** Returns `true` when this number is strictly positive. */
-    isPositive(): boolean;
-    /** Returns `true` when this number is strictly negative. */
-    isNegative(): boolean;
-    /**
-     * Returns `true` when this number has no fractional part.
-     * Numbers with `exponent >= PrecisionCutoff` are always considered integers.
-     */
-    isInteger(): boolean;
     /**
      * Allows implicit coercion via `+an(1500)` (returns `toNumber()`) and
      * template literals / string concatenation (returns `toString()`).
-     *
-     * `hint === "number"` → `toNumber()`; all other hints → `toString()`.
      */
     [Symbol.toPrimitive](hint: string): number | string;
     /**
      * Formats this number as a string using the given notation plugin.
      *
-     * Defaults to {@link scientificNotation} when no plugin is provided.
-     * `decimals` controls the number of decimal places passed to the plugin and defaults to `2`.
-     *
-     * @example
-     * new ArbitraryNumber(1.5, 3).toString();                  // "1.50e+3"
-     * new ArbitraryNumber(1.5, 3).toString(unitNotation);       // "1.50 K"
-     * new ArbitraryNumber(1.5, 3).toString(unitNotation, 4);    // "1.5000 K"
-     *
-     * @param notation - The formatting plugin to use.
-     * @param decimals - Number of decimal places to render. Defaults to `2`.
+     * Defaults to `scientificNotation` when no plugin is provided.
+     * `decimals` controls decimal places and defaults to `defaults.notationDecimals`.
      */
     toString(notation?: NotationPlugin, decimals?: number): string;
 }
+/**
+ * An immutable wrapper around `ArbitraryNumber`.
+ *
+ * Created via `number.freeze()`. All mutating methods throw `ArbitraryNumberMutationError`.
+ * Call `.clone()` to get a fresh, mutable `ArbitraryNumber`.
+ *
+ * @example
+ * const frozen = gold.freeze();
+ * frozen.add(drop);  // throws ArbitraryNumberMutationError
+ * const mutable = frozen.clone(); // fresh mutable copy
+ */
+declare class FrozenArbitraryNumber extends ArbitraryNumber {
+    /** @internal */
+    constructor(coefficient: number, exponent: number);
+    private _throwMutation;
+    add(_other: ArbitraryNumber): never;
+    sub(_other: ArbitraryNumber): never;
+    mul(_other: ArbitraryNumber): never;
+    div(_other: ArbitraryNumber): never;
+    negate(): never;
+    abs(): never;
+    pow(_n: number): never;
+    mulAdd(_m: ArbitraryNumber, _a: ArbitraryNumber): never;
+    addMul(_a: ArbitraryNumber, _m: ArbitraryNumber): never;
+    mulSub(_m: ArbitraryNumber, _s: ArbitraryNumber): never;
+    subMul(_s: ArbitraryNumber, _m: ArbitraryNumber): never;
+    divAdd(_d: ArbitraryNumber, _a: ArbitraryNumber): never;
+    mulDiv(_m: ArbitraryNumber, _d: ArbitraryNumber): never;
+    floor(): never;
+    ceil(): never;
+    round(): never;
+    trunc(): never;
+    sqrt(): never;
+    cbrt(): never;
+}
 
 /**
  * Base class for all errors thrown by the arbitrary-numbers library.
@@ -818,111 +724,38 @@ declare class ArbitraryNumberDomainError extends ArbitraryNumberError {
     readonly context: Record<string, number>;
     constructor(message: string, context: Record<string, number>);
 }
-
-declare const an: AnFunction;
-
 /**
- * Fluent builder for multi-step `ArbitraryNumber` expressions.
- *
- * Each method mutates the accumulated value in-place and returns `this`,
- * enabling a readable left-to-right pipeline with no expression-tree
- * overhead.  Every step delegates directly to the underlying
- * `ArbitraryNumber` method - fused variants (`mulAdd`, `mulSub`, etc.)
- * are available here too.
+ * Thrown when a mutating method is called on a frozen `ArbitraryNumber`.
  *
  * @example
- * // Damage formula: ((base - armour) * mult) + flatBonus
- * const result = chain(base)
- *     .subMul(armour, multiplier)
- *     .add(flatBonus)
- *     .done();
- *
- * @remarks
- * No deferred execution - each call runs immediately.  Overhead vs direct
- * method chaining is a single extra method call + `return this` per step
- * (~1-2 ns).  Use fused ops for hot inner loops; the builder is optimised
- * for readability in complex multi-step formulas.
+ * try {
+ *     frozen.add(other);
+ * } catch (e) {
+ *     if (e instanceof ArbitraryNumberMutationError) { ... }
+ * }
  */
-declare class AnChain {
-    private value;
-    private constructor();
-    /** Creates an `AnChain` from an `ArbitraryNumber` or a plain `number`. */
-    static from(value: ArbitraryNumber | number): AnChain;
-    /** Adds `other` to the accumulated value. */
-    add(other: ArbitraryNumber): this;
-    /** Subtracts `other` from the accumulated value. */
-    sub(other: ArbitraryNumber): this;
-    /** Multiplies the accumulated value by `other`. */
-    mul(other: ArbitraryNumber): this;
-    /** Divides the accumulated value by `other`. */
-    div(other: ArbitraryNumber): this;
-    /** Raises the accumulated value to `exp`. */
-    pow(exp: number): this;
-    /** `(this * mult) + add` */
-    mulAdd(mult: ArbitraryNumber, add: ArbitraryNumber): this;
-    /** `(this + add) * mult` */
-    addMul(add: ArbitraryNumber, mult: ArbitraryNumber): this;
-    /** `(this * mult) - sub` */
-    mulSub(mult: ArbitraryNumber, sub: ArbitraryNumber): this;
-    /** `(this - sub) * mult` */
-    subMul(sub: ArbitraryNumber, mult: ArbitraryNumber): this;
-    /** `(this / div) + add` */
-    divAdd(div: ArbitraryNumber, add: ArbitraryNumber): this;
-    /** Absolute value. */
-    abs(): this;
-    /** Negates the accumulated value. */
-    neg(): this;
-    /** Square root of the accumulated value. */
-    sqrt(): this;
-    /** Rounds down to the nearest integer. */
-    floor(): this;
-    /** Rounds up to the nearest integer. */
-    ceil(): this;
-    /** Rounds to the nearest integer. */
-    round(): this;
-    /** Returns the accumulated `ArbitraryNumber` result. */
-    done(): ArbitraryNumber;
+declare class ArbitraryNumberMutationError extends ArbitraryNumberDomainError {
+    constructor(message: string);
 }
-/**
- * Creates an {@link AnChain} builder starting from `value`.
- *
- * Mirrors the `an` factory shorthand.
- *
- * @example
- * import { chain, an } from 'arbitrary-numbers';
- *
- * const result = chain(an(1.5, 6))
- *     .mulAdd(multiplier, bonus)
- *     .floor()
- *     .done();
- */
-declare function chain(value: ArbitraryNumber | number): AnChain;
 
-type FormulaStep = (value: ArbitraryNumber) => ArbitraryNumber;
+declare const an: AnFunction;
+
+type FormulaStep = (value: ArbitraryNumber) => void;
 /**
  * A reusable, named pipeline of `ArbitraryNumber` operations.
  *
- * Unlike {@link AnChain}, which executes each step immediately against an
- * accumulated value, `AnFormula` stores the operations as a list of closures
- * and runs them only when {@link apply} is called.  The same formula can be
- * applied to any number of values without re-defining the pipeline.
- *
- * Each builder method returns a **new** `AnFormula` - the original is
- * unchanged.  This makes branching and composition safe:
+ * `AnFormula` stores operations as closures and runs them on `.apply()` or `.applyInPlace()`.
+ * The same formula can be applied to any number of values without re-defining the pipeline.
  *
- * @example
- * const base      = formula().mul(an(2));
- * const withFloor = base.floor();   // new formula - base is unchanged
- * const withCeil  = base.ceil();    // another branch from base
+ * Each builder method returns a **new** `AnFormula` — the original is unchanged.
  *
  * @example
- * // Define once, apply to many values
  * const armorReduction = formula("Armor Reduction")
  *     .subMul(armor, an(0.75))
  *     .floor();
  *
- * const physDamage = armorReduction.apply(physBase);
- * const magDamage  = armorReduction.apply(magBase);
+ * const physDamage = armorReduction.apply(physBase);   // physBase unchanged
+ * armorReduction.applyInPlace(enemyAtk);               // enemyAtk mutated
  *
  * @example
  * // Compose formulas
@@ -933,21 +766,12 @@ type FormulaStep = (value: ArbitraryNumber) => ArbitraryNumber;
 declare class AnFormula {
     private readonly _name;
     private readonly steps;
-    /**
-     * Prefer the {@link formula} factory function over calling this directly.
-     */
+    /** Prefer the {@link formula} factory function over calling this directly. */
     constructor(name?: Maybe<string>, steps?: ReadonlyArray<FormulaStep>);
     /** The name passed to {@link formula}, if any. */
     get name(): Maybe<string>;
     /**
      * Returns a copy of this formula with a new name, leaving the original unchanged.
-     *
-     * @param name - The new name.
-     * @example
-     * const base  = formula().mul(an(2));
-     * const named = base.named("Double");
-     * named.name   // "Double"
-     * base.name    // undefined
      */
     named(name: string): AnFormula;
     private step;
@@ -973,7 +797,7 @@ declare class AnFormula {
     divAdd(div: ArbitraryNumber, add: ArbitraryNumber): AnFormula;
     /** Appends `abs()` to the pipeline. */
     abs(): AnFormula;
-    /** Appends `neg()` to the pipeline. */
+    /** Appends `negate()` to the pipeline. */
     neg(): AnFormula;
     /** Appends `sqrt()` to the pipeline. */
     sqrt(): AnFormula;
@@ -987,50 +811,42 @@ declare class AnFormula {
      * Returns a new formula that first applies `this`, then applies `next`.
      *
      * Neither operand is mutated.
-     *
-     * @param next - The formula to apply after `this`.
-     * @example
-     * const full   = armorReduction.then(critBonus);
-     * const result = full.apply(baseDamage);
      */
     then(next: AnFormula): AnFormula;
     /**
-     * Runs this formula's pipeline against `value` and returns the result.
+     * Clones `value` once, runs the pipeline against the clone, and returns it.
      *
-     * The formula itself is unchanged - call `apply` as many times as needed.
+     * The original `value` is never mutated.
      *
-     * @param value - The starting value. Plain `number` is coerced via `ArbitraryNumber.from`.
-     * @throws `"ArbitraryNumber.from: value must be finite"` when a plain `number` is non-finite.
      * @example
-     * const damage = damageFormula.apply(baseDamage);
-     * const scaled = damageFormula.apply(boostedBase);
+     * const damage = damageFormula.apply(playerAtk); // playerAtk unchanged
      */
     apply(value: ArbitraryNumber | number): ArbitraryNumber;
+    /**
+     * Runs the pipeline directly against `value`, mutating it in-place.
+     *
+     * Use on hot paths where you don't need to preserve the original value.
+     *
+     * @example
+     * damageFormula.applyInPlace(enemyAtk); // enemyAtk is mutated
+     */
+    applyInPlace(value: ArbitraryNumber): void;
 }
 /**
  * Creates an {@link AnFormula} pipeline, optionally named.
  *
- * Build the pipeline by chaining methods - each returns a new `AnFormula`
- * so the original is always safe to branch or reuse.  Call {@link AnFormula.apply}
- * to run the pipeline against a value.
+ * Build the pipeline by chaining methods — each returns a new `AnFormula`.
+ * Call {@link AnFormula.apply} or {@link AnFormula.applyInPlace} to run it.
  *
- * @param name - Optional label, available via {@link AnFormula.name} for debugging.
  * @example
  * import { formula, an } from 'arbitrary-numbers';
  *
  * const armorReduction = formula("Armor Reduction")
- *     .subMul(armor, an(0.75))   // (base - armor) * 0.75
+ *     .subMul(armor, an(0.75))
  *     .floor();
  *
- * const critBonus = formula("Crit Bonus").mul(critMult).ceil();
- *
- * // Reuse across many values
  * const physDmg = armorReduction.apply(physBase);
- * const magDmg  = armorReduction.apply(magBase);
- *
- * // Compose
- * const full   = armorReduction.then(critBonus);
- * const result = full.apply(baseDamage);
+ * armorReduction.applyInPlace(tempValue);
  */
 declare function formula(name?: Maybe<string>): AnFormula;
 
@@ -1276,18 +1092,15 @@ declare class ArbitraryNumberGuard {
      */
     static isArbitraryNumber(obj: unknown): obj is ArbitraryNumber;
     /**
-     * Returns `true` if `obj` has the shape of a {@link NormalizedNumber}
-     * (i.e. has numeric `coefficient` and `exponent` properties).
+     * Returns `true` if `obj` has the shape `{ coefficient: number; exponent: number }`.
      *
-     * Note: both `ArbitraryNumber` instances and plain objects with the right
-     * shape will pass this check. Use {@link isArbitraryNumber} when you need
-     * to distinguish between the two.
-     *
-     * @param obj - The value to test.
-     * @returns `true` when `obj` has `typeof coefficient === "number"` and
-     *   `typeof exponent === "number"`.
+     * Both `ArbitraryNumber` instances and plain objects with the right shape pass this
+     * check. Use {@link isArbitraryNumber} to distinguish the two.
      */
-    static isNormalizedNumber(obj: unknown): obj is NormalizedNumber;
+    static isNormalizedNumber(obj: unknown): obj is {
+        coefficient: number;
+        exponent: number;
+    };
     /**
      * Returns `true` if `obj` is an {@link ArbitraryNumber} with a value of zero.
      *
@@ -1297,114 +1110,10 @@ declare class ArbitraryNumberGuard {
     static isZero(obj: unknown): boolean;
 }
 
-/**
- * Convenience helpers for mixed `number | ArbitraryNumber` inputs.
- *
- * Each method accepts either type and coerces plain `number` values via
- * {@link ArbitraryNumber.from} before delegating to the corresponding instance method.
- *
- * Prefer `ArbitraryNumber` instance methods directly on hot paths - this class is
- * intended for system boundaries (event handlers, serialisation, UI callbacks) where
- * the input type is unknown.
- *
- * @example
- * import { ArbitraryNumberOps as ops } from "arbitrary-numbers";
- * ops.add(1500, 2500)              // ArbitraryNumber (4000)
- * ops.mul(an(2, 0), 5)            // ArbitraryNumber (10)
- * ops.from(1_500_000)             // ArbitraryNumber { coefficient: 1.5, exponent: 6 }
- */
-declare class ArbitraryNumberOps {
-    /**
-     * Converts `value` to an `ArbitraryNumber`, returning it unchanged if it already is one.
-     *
-     * @param value - A plain `number` or an existing `ArbitraryNumber`.
-     * @returns The corresponding `ArbitraryNumber`.
-     * @throws `ArbitraryNumberInputError` when `value` is `NaN`, `Infinity`, or `-Infinity`.
-     */
-    static from(value: ArbitraryNumberish): ArbitraryNumber;
-    /**
-     * Converts `value` to an `ArbitraryNumber`, returning `null` for non-finite inputs
-     * instead of throwing.
-     *
-     * Use this at system boundaries (form inputs, external APIs) where you want to handle
-     * bad input gracefully rather than catching an exception.
-     *
-     * @param value - A plain `number` or an existing `ArbitraryNumber`.
-     * @returns The `ArbitraryNumber`, or `null` if the input is `NaN`, `Infinity`, or `-Infinity`.
-     *
-     * @example
-     * ops.tryFrom(1500)      // ArbitraryNumber { coefficient: 1.5, exponent: 3 }
-     * ops.tryFrom(Infinity)  // null
-     * ops.tryFrom(NaN)       // null
-     */
-    static tryFrom(value: ArbitraryNumberish): Nullable<ArbitraryNumber>;
-    /**
-     * Returns `left + right`, coercing both operands as needed.
-     *
-     * @param left - The augend.
-     * @param right - The addend.
-     * @example
-     * ops.add(1500, 2500) // ArbitraryNumber (4000)
-     */
-    static add(left: ArbitraryNumberish, right: ArbitraryNumberish): ArbitraryNumber;
-    /**
-     * Returns `left - right`, coercing both operands as needed.
-     *
-     * @param left - The minuend.
-     * @param right - The subtrahend.
-     * @example
-     * ops.sub(5000, 1500) // ArbitraryNumber (3500)
-     */
-    static sub(left: ArbitraryNumberish, right: ArbitraryNumberish): ArbitraryNumber;
-    /**
-     * Returns `left * right`, coercing both operands as needed.
-     *
-     * @param left - The multiplicand.
-     * @param right - The multiplier.
-     * @example
-     * ops.mul(an(1, 3), 5) // ArbitraryNumber (5000)
-     */
-    static mul(left: ArbitraryNumberish, right: ArbitraryNumberish): ArbitraryNumber;
-    /**
-     * Returns `left / right`, coercing both operands as needed.
-     *
-     * @param left - The dividend.
-     * @param right - The divisor.
-     * @throws `"Division by zero"` when `right` is zero.
-     * @example
-     * ops.div(an(1, 6), 1000) // ArbitraryNumber (1000)
-     */
-    static div(left: ArbitraryNumberish, right: ArbitraryNumberish): ArbitraryNumber;
-    /**
-     * Compares `left` to `right`.
-     *
-     * @param left - The left operand.
-     * @param right - The right operand.
-     * @returns `1` if `left > right`, `-1` if `left < right`, `0` if equal.
-     * @example
-     * ops.compare(5000, 1500) // 1
-     */
-    static compare(left: ArbitraryNumberish, right: ArbitraryNumberish): number;
-    /**
-     * Clamps `value` to the inclusive range `[min, max]`, coercing all inputs as needed.
-     *
-     * @param value - The value to clamp.
-     * @param min - The lower bound (inclusive).
-     * @param max - The upper bound (inclusive).
-     * @example
-     * ops.clamp(500, 1000, 2000) // ArbitraryNumber (1000)  - below min, returns min
-     */
-    static clamp(value: ArbitraryNumberish, min: ArbitraryNumberish, max: ArbitraryNumberish): ArbitraryNumber;
-}
-
 /**
  * Domain-level helpers for common game and simulation patterns.
  *
- * These sit above the core arithmetic layer - each method accepts
- * mixed input (`number | ArbitraryNumber`) via
- * {@link ArbitraryNumberOps.from} so they work at system boundaries
- * where you may receive raw numbers.
- *
+ * Accepts mixed input (`number | ArbitraryNumber`) via `ArbitraryNumber.from`.
  * For hot-path code, use `ArbitraryNumber` methods directly.
  */
 declare class ArbitraryNumberHelpers {
@@ -1412,9 +1121,6 @@ declare class ArbitraryNumberHelpers {
     /**
      * Returns `true` when `value >= threshold`.
      *
-     * @param value - The value to test.
-     * @param threshold - The minimum required value.
-     * @returns `true` when `value >= threshold`.
      * @example
      * ArbitraryNumberHelpers.meetsOrExceeds(gold, upgradeCost)
      */
@@ -1424,9 +1130,6 @@ declare class ArbitraryNumberHelpers {
      *
      * Equivalent to `floor(total / step)`.
      *
-     * @param total - The total available amount.
-     * @param step - The cost or size of one unit. Must be greater than zero.
-     * @returns The number of whole units that fit, as an `ArbitraryNumber`.
      * @throws `"step must be greater than zero"` when `step <= 0`.
      * @example
      * const canBuy = ArbitraryNumberHelpers.wholeMultipleCount(gold, upgradeCost);
@@ -1435,14 +1138,10 @@ declare class ArbitraryNumberHelpers {
     /**
      * Returns `value - delta`, clamped to a minimum of `floor` (default `0`).
      *
-     * @param value - The starting value.
-     * @param delta - The amount to subtract.
-     * @param floor - The minimum result. Defaults to `ArbitraryNumber.Zero`.
-     * @returns `max(value - delta, floor)`.
      * @example
      * health = ArbitraryNumberHelpers.subtractWithFloor(health, damage);
      */
     static subtractWithFloor(value: ArbitraryNumberish, delta: ArbitraryNumberish, floor?: ArbitraryNumberish): ArbitraryNumber;
 }
 
-export { AlphabetNotation, type AlphabetNotationOptions, AnChain, AnFormula, type AnFunction, ArbitraryNumber, ArbitraryNumberDomainError, ArbitraryNumberError, ArbitraryNumberGuard, ArbitraryNumberHelpers, ArbitraryNumberInputError, type ArbitraryNumberJson, ArbitraryNumberOps, type ArbitraryNumberish, CLASSIC_UNITS, COMPACT_UNITS, type Maybe, type Mod3, type NormalizedNumber, type NotationPlugin, type Nullable, ScientificNotation, type Signum, SuffixNotationBase, type SuffixNotationPlugin, type SuffixNotationPluginOptions, type SuffixProvider, type Unit, type UnitArray, UnitNotation, type UnitNotationOptions, alphabetSuffix, an, chain, formula, ArbitraryNumberGuard as guard, ArbitraryNumberHelpers as helpers, letterNotation, ArbitraryNumberOps as ops, scientificNotation, unitNotation };
+export { AlphabetNotation, type AlphabetNotationOptions, AnFormula, type AnFunction, ArbitraryNumber, type ArbitraryNumberDefaults, ArbitraryNumberDomainError, ArbitraryNumberError, ArbitraryNumberGuard, ArbitraryNumberHelpers, ArbitraryNumberInputError, type ArbitraryNumberJson, ArbitraryNumberMutationError, type ArbitraryNumberish, CLASSIC_UNITS, COMPACT_UNITS, FrozenArbitraryNumber, type Maybe, type Mod3, type NotationPlugin, type Nullable, ScientificNotation, type Signum, SuffixNotationBase, type SuffixNotationPlugin, type SuffixNotationPluginOptions, type SuffixProvider, type Unit, type UnitArray, UnitNotation, type UnitNotationOptions, alphabetSuffix, an, formula, ArbitraryNumberGuard as guard, ArbitraryNumberHelpers as helpers, letterNotation, scientificNotation, unitNotation };