@elaraai/east-web-std 1.0.85

package/dist/src/random.js

@@ -0,0 +1,992 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * Random number generation for East programs in a browser.
+ *
+ * Ported from east-node-std's src/random.ts
+ * (libs/east-node/packages/east-node-std/src/random.ts): the same platform
+ * functions, types and algorithms, so a seed gives the stream east-node-std
+ * gives, bit for bit (test/random.spec.ts checks it). One thing differs:
+ * east-node-std keeps one generator for its process, and a browser keeps the
+ * generator in the implementation, so each {@link createRandomImpl} starts
+ * unseeded, as a new east-node process does.
+ *
+ * @packageDocumentation
+ */
+import { East, FloatType, IntegerType, NullType } from "@elaraai/east";
+import { EastError } from "@elaraai/east/internal";
+import CryptoRNG from "./random/crypto-rng.js";
+import XorShift128RNG from "./random/xorshift128.js";
+import uniformDist from "./random/distributions/uniform.js";
+import uniformIntDist from "./random/distributions/uniform-int.js";
+import normalDist from "./random/distributions/normal.js";
+import exponentialDist from "./random/distributions/exponential.js";
+import bernoulliDist from "./random/distributions/bernoulli.js";
+import binomialDist from "./random/distributions/binomial.js";
+import geometricDist from "./random/distributions/geometric.js";
+import poissonDist from "./random/distributions/poisson.js";
+import paretoDist from "./random/distributions/pareto.js";
+import logNormalDist from "./random/distributions/log-normal.js";
+import irwinHallDist from "./random/distributions/irwin-hall.js";
+import batesDist from "./random/distributions/bates.js";
+// Platform Function Definitions
+/**
+ * Generates a uniform random float in the range [0.0, 1.0).
+ *
+ * Returns a uniformly distributed random floating-point number greater than or equal to 0.0
+ * and strictly less than 1.0. Uses cryptographically secure random number generation by default.
+ *
+ * This is a platform function for the East language, enabling secure random number generation
+ * in East programs running in a browser.
+ *
+ * @returns A random float in [0.0, 1.0)
+ *
+ * @example
+ * ```ts
+ * const generateRandom = East.function([], FloatType, $ => {
+ *     return Random.uniform();
+ * });
+ * ```
+ *
+ * @remarks
+ * - Uses the web-standard crypto.getRandomValues for cryptographic security
+ * - Uniform distribution across the range
+ * - Never returns exactly 1.0
+ */
+export const random_uniform = East.platform("random_uniform", [], FloatType);
+/**
+ * Generates a random float from a standard normal distribution (mean=0, standard deviation=1).
+ *
+ * Returns a random floating-point number drawn from a normal (Gaussian) distribution
+ * with mean 0.0 and standard deviation 1.0. Uses the Marsaglia polar method for
+ * high-quality normal distribution sampling.
+ *
+ * This is a platform function for the East language, enabling normal distribution sampling
+ * in East programs running in a browser.
+ *
+ * @returns A random float from N(0, 1)
+ *
+ * @example
+ * ```ts
+ * const generateNormal = East.function([], FloatType, $ => {
+ *     const z = $.let(Random.normal());
+ *     // Scale and shift: z * stddev + mean
+ *     return z.multiply(2.5).add(10.0);  // N(10, 2.5)
+ * });
+ * ```
+ *
+ * @remarks
+ * - Uses Marsaglia polar method for high-quality normal distribution
+ * - Mean: 0.0, Standard deviation: 1.0
+ * - Can return any real number (unbounded range)
+ * - Use `.multiply(stddev).add(mean)` to scale/shift distribution
+ */
+export const random_normal = East.platform("random_normal", [], FloatType);
+/**
+ * Generates a random integer in the range [min, max] (both endpoints inclusive).
+ *
+ * Returns a uniformly distributed random integer between min and max (both inclusive).
+ * Uses cryptographically secure random number generation. The range must be valid (min ≤ max).
+ *
+ * This is a platform function for the East language, enabling random integer generation
+ * in East programs running in a browser.
+ *
+ * @param min - The minimum value (inclusive)
+ * @param max - The maximum value (inclusive)
+ * @returns A random integer in [min, max]
+ *
+ * @throws {EastError} When min > max
+ *
+ * @example
+ * ```ts
+ * const rollDice = East.function([], IntegerType, $ => {
+ *     return Random.range(1n, 6n);  // 1-6 inclusive
+ * });
+ * ```
+ *
+ * @remarks
+ * - Both min and max are inclusive
+ * - Uniform distribution across the range
+ * - Uses floor method to avoid modulo bias
+ */
+export const random_range = East.platform("random_range", [IntegerType, IntegerType], IntegerType);
+/**
+ * Generates a random float from an exponential distribution.
+ *
+ * Returns a random floating-point number drawn from an exponential distribution
+ * with rate parameter lambda (λ). The mean of the distribution is 1/λ.
+ * Commonly used for modeling time between events in a Poisson process.
+ *
+ * This is a platform function for the East language, enabling exponential distribution sampling
+ * in East programs running in a browser.
+ *
+ * @param lambda - Rate parameter (λ > 0), default 1.0. Mean = 1/λ
+ * @returns A random float from Exp(λ)
+ *
+ * @throws {EastError} When lambda ≤ 0
+ *
+ * @example
+ * ```ts
+ * const waitTime = East.function([], FloatType, $ => {
+ *     // Average wait time of 5 minutes (lambda = 0.2)
+ *     return Random.exponential(0.2);
+ * });
+ * ```
+ *
+ * @remarks
+ * - Uses inverse transform sampling: -ln(U) / λ
+ * - Always returns positive values
+ * - Mean = 1/λ, Variance = 1/λ²
+ * - Memoryless property: P(X > s + t | X > s) = P(X > t)
+ */
+export const random_exponential = East.platform("random_exponential", [FloatType], FloatType);
+/**
+ * Generates a random float from a Weibull distribution.
+ *
+ * Returns a random floating-point number drawn from a Weibull distribution
+ * with shape parameter k. Uses exponential distribution transformation.
+ * Commonly used for modeling failure rates and lifetime distributions.
+ *
+ * This is a platform function for the East language, enabling Weibull distribution sampling
+ * in East programs running in a browser.
+ *
+ * @param shape - Shape parameter (k > 0). k=1 gives exponential, k>1 increases failure rate
+ * @returns A random float from Weibull(k, 1)
+ *
+ * @throws {EastError} When shape ≤ 0
+ *
+ * @example
+ * ```ts
+ * const lifetime = East.function([], FloatType, $ => {
+ *     // Shape=2 models wear-out failures
+ *     return Random.weibull(2.0);
+ * });
+ * ```
+ *
+ * @remarks
+ * - Uses transformation: exponential() ^ (1/shape)
+ * - Shape < 1: decreasing failure rate
+ * - Shape = 1: constant failure rate (exponential)
+ * - Shape > 1: increasing failure rate
+ */
+export const random_weibull = East.platform("random_weibull", [FloatType], FloatType);
+/**
+ * Generates a binary random outcome (0 or 1).
+ *
+ * Returns 0 or 1 based on success probability p. This models a single
+ * Bernoulli trial, like a biased coin flip.
+ *
+ * This is a platform function for the East language, enabling binary random outcomes
+ * in East programs running in a browser.
+ *
+ * @param p - Success probability (0 ≤ p < 1), default 0.5
+ * @returns 0 or 1 (as integer)
+ *
+ * @throws {EastError} When p < 0 or p ≥ 1
+ *
+ * @example
+ * ```ts
+ * const coinFlip = East.function([], IntegerType, $ => {
+ *     // Fair coin: 50% chance of 1
+ *     return Random.bernoulli(0.5);
+ * });
+ * ```
+ *
+ * @remarks
+ * - Returns 1 with probability p, 0 with probability (1-p)
+ * - Mean = p, Variance = p(1-p)
+ * - Special case of binomial with n=1
+ */
+export const random_bernoulli = East.platform("random_bernoulli", [FloatType], IntegerType);
+/**
+ * Generates the number of successes in n independent Bernoulli trials.
+ *
+ * Returns an integer count of successes when performing n independent trials,
+ * each with success probability p. Models scenarios like coin flips, pass/fail tests.
+ *
+ * This is a platform function for the East language, enabling binomial distribution sampling
+ * in East programs running in a browser.
+ *
+ * @param n - Number of trials (integer > 0)
+ * @param p - Success probability per trial (0 ≤ p < 1), default 0.5
+ * @returns Number of successes (integer in [0, n])
+ *
+ * @throws {EastError} When n ≤ 0, not an integer, or p < 0 or p ≥ 1
+ *
+ * @example
+ * ```ts
+ * const heads = East.function([], IntegerType, $ => {
+ *     // Number of heads in 10 coin flips
+ *     return Random.binomial(10n, 0.5);
+ * });
+ * ```
+ *
+ * @remarks
+ * - Mean = n × p, Variance = n × p × (1-p)
+ * - Returns value in range [0, n]
+ * - Sum of n independent Bernoulli(p) trials
+ */
+export const random_binomial = East.platform("random_binomial", [IntegerType, FloatType], IntegerType);
+/**
+ * Generates the number of trials until the first success.
+ *
+ * Returns an integer representing the number of independent Bernoulli trials
+ * needed to get the first success, where each trial has success probability p.
+ * Models scenarios like "how many attempts until success?"
+ *
+ * This is a platform function for the East language, enabling geometric distribution sampling
+ * in East programs running in a browser.
+ *
+ * @param p - Success probability per trial (0 < p < 1), default 0.5
+ * @returns Number of trials until first success (integer ≥ 1)
+ *
+ * @throws {EastError} When p ≤ 0 or p ≥ 1
+ *
+ * @example
+ * ```ts
+ * const attempts = East.function([], IntegerType, $ => {
+ *     // Rolls until getting a 6 (p = 1/6)
+ *     return Random.geometric(1.0 / 6.0);
+ * });
+ * ```
+ *
+ * @remarks
+ * - Mean = 1/p, Variance = (1-p)/p²
+ * - Always returns integer ≥ 1
+ * - Memoryless property like exponential distribution
+ * - Uses inverse transform sampling
+ */
+export const random_geometric = East.platform("random_geometric", [FloatType], IntegerType);
+/**
+ * Generates the number of events in a fixed interval from a Poisson process.
+ *
+ * Returns an integer count of events occurring in a fixed interval,
+ * where events occur independently at a constant average rate λ (lambda).
+ * Commonly used for modeling rare events, arrivals, or counts.
+ *
+ * This is a platform function for the East language, enabling Poisson distribution sampling
+ * in East programs running in a browser.
+ *
+ * @param lambda - Average rate of events (λ > 0), default 1.0
+ * @returns Number of events (integer ≥ 0)
+ *
+ * @throws {EastError} When lambda ≤ 0
+ *
+ * @example
+ * ```ts
+ * const customers = East.function([], IntegerType, $ => {
+ *     // Average 3 customers per hour
+ *     return Random.poisson(3.0);
+ * });
+ * ```
+ *
+ * @remarks
+ * - Mean = λ, Variance = λ
+ * - Always returns non-negative integer
+ * - Uses inversion method for λ < 10, generative method for λ ≥ 10
+ * - Approximates binomial when n is large and p is small
+ */
+export const random_poisson = East.platform("random_poisson", [FloatType], IntegerType);
+/**
+ * Generates a random float from a Pareto distribution (power law).
+ *
+ * Returns a random floating-point number drawn from a Pareto distribution
+ * with shape parameter α (alpha). Models phenomena following power laws,
+ * like wealth distribution, city sizes, or word frequencies.
+ *
+ * This is a platform function for the East language, enabling Pareto distribution sampling
+ * in East programs running in a browser.
+ *
+ * @param alpha - Shape parameter (α ≥ 0), default 1.0. Smaller α = heavier tail
+ * @returns A random float from Pareto(α) (value ≥ 1.0)
+ *
+ * @throws {EastError} When alpha < 0
+ *
+ * @example
+ * ```ts
+ * const wealth = East.function([], FloatType, $ => {
+ *     // Heavy-tailed distribution (80/20 rule)
+ *     return Random.pareto(1.16);
+ * });
+ * ```
+ *
+ * @remarks
+ * - Always returns value ≥ 1.0
+ * - Mean = α/(α-1) for α > 1, infinite otherwise
+ * - Heavier tail as α decreases
+ * - Models "80/20 rule" and power law phenomena
+ */
+export const random_pareto = East.platform("random_pareto", [FloatType], FloatType);
+/**
+ * Generates a random float whose logarithm is normally distributed.
+ *
+ * Returns a random floating-point number from a log-normal distribution,
+ * where ln(X) ~ N(μ, σ²). Commonly used for modeling multiplicative processes,
+ * stock prices, or quantities that can't be negative.
+ *
+ * This is a platform function for the East language, enabling log-normal distribution sampling
+ * in East programs running in a browser.
+ *
+ * @param mu - Mean of underlying normal distribution, default 0.0
+ * @param sigma - Standard deviation of underlying normal, default 1.0
+ * @returns A random float from LogNormal(μ, σ) (always positive)
+ *
+ * @example
+ * ```ts
+ * const stockPrice = East.function([], FloatType, $ => {
+ *     // Log-normal with ln(X) ~ N(0, 0.2)
+ *     return Random.logNormal(0.0, 0.2);
+ * });
+ * ```
+ *
+ * @remarks
+ * - Always returns positive values
+ * - If ln(X) ~ N(μ, σ²), then X ~ LogNormal(μ, σ)
+ * - Median = exp(μ), Mean = exp(μ + σ²/2)
+ * - Right-skewed distribution
+ */
+export const random_log_normal = East.platform("random_log_normal", [FloatType, FloatType], FloatType);
+/**
+ * Generates the sum of n independent uniform random variables.
+ *
+ * Returns the sum of n independent uniform(0,1) random variables.
+ * This is the Irwin-Hall distribution. As n increases, approaches
+ * normal distribution by Central Limit Theorem.
+ *
+ * This is a platform function for the East language, enabling Irwin-Hall distribution sampling
+ * in East programs running in a browser.
+ *
+ * @param n - Number of uniform variables to sum (integer ≥ 0), default 1
+ * @returns Sum of n uniform(0,1) random variables (float in [0, n])
+ *
+ * @throws {EastError} When n < 0 or not an integer
+ *
+ * @example
+ * ```ts
+ * const irwinHall = East.function([], FloatType, $ => {
+ *     // Sum of 12 uniform variables
+ *     return Random.irwinHall(12n);
+ * });
+ * ```
+ *
+ * @remarks
+ * - Range: [0, n]
+ * - Mean = n/2, Variance = n/12
+ * - Approximates N(n/2, n/12) for large n
+ * - Related to Bates distribution (divided by n)
+ */
+export const random_irwin_hall = East.platform("random_irwin_hall", [IntegerType], FloatType);
+/**
+ * Generates the average of n independent uniform random variables.
+ *
+ * Returns the average of n independent uniform(0,1) random variables.
+ * This is the Bates distribution. Approaches normal distribution as
+ * n increases (Central Limit Theorem).
+ *
+ * This is a platform function for the East language, enabling Bates distribution sampling
+ * in East programs running in a browser.
+ *
+ * @param n - Number of uniform variables to average (integer > 0), default 1
+ * @returns Average of n uniform(0,1) random variables (float in [0, 1])
+ *
+ * @throws {EastError} When n ≤ 0 or not an integer
+ *
+ * @example
+ * ```ts
+ * const bates = East.function([], FloatType, $ => {
+ *     // Average of 12 uniform variables (smoother than single uniform)
+ *     return Random.bates(12n);
+ * });
+ * ```
+ *
+ * @remarks
+ * - Range: [0, 1]
+ * - Mean = 0.5, Variance = 1/(12n)
+ * - Approximates N(0.5, 1/(12n)) for large n
+ * - More concentrated around 0.5 as n increases
+ */
+export const random_bates = East.platform("random_bates", [IntegerType], FloatType);
+/**
+ * Seeds the random number generator.
+ *
+ * Sets the seed for the random number generator, allowing reproducible random sequences.
+ * All subsequent random operations will use this seeded RNG until a new seed is set.
+ *
+ * This is a platform function for the East language, enabling reproducible randomness
+ * in East programs running in a browser.
+ *
+ * @param seed - Seed value (integer)
+ * @returns null
+ *
+ * @example
+ * ```ts
+ * const seedAndGenerate = East.function([], FloatType, $ => {
+ *     $(Random.seed(12345n));
+ *     return Random.uniform();  // Will be reproducible
+ * });
+ * ```
+ *
+ * @remarks
+ * - IMPORTANT: Seeding switches from cryptographically secure random to a deterministic
+ *   PRNG (xorshift128+). This is essential for reproducible simulations but should not
+ *   be used when cryptographic security is required.
+ * - Same seed produces same sequence of random numbers, and the same sequence
+ *   east-node-std produces for it
+ * - The seed holds for the implementation that was seeded: each
+ *   {@link createRandomImpl} (and so each `createWebPlatform()`) starts unseeded
+ */
+export const random_seed = East.platform("random_seed", [IntegerType], NullType);
+/**
+ * The Random platform functions, drawing from `state`.
+ *
+ * Each implementation is east-node-std's, with `state.rng` where
+ * east-node-std reads its process-wide generator.
+ */
+function implementRandom(state) {
+    return [
+        random_uniform.implement(() => {
+            return uniformDist(state.rng, 0, 1)();
+        }),
+        random_normal.implement(() => {
+            return normalDist(state.rng, 0, 1)();
+        }),
+        random_range.implement((min, max) => {
+            if (min > max) {
+                throw new EastError(`Invalid range: min (${min}) > max (${max})`, {
+                    location: [{ filename: "random_range", line: 0n, column: 0n }],
+                });
+            }
+            try {
+                return BigInt(uniformIntDist(state.rng, min, max)());
+            }
+            catch (err) {
+                throw new EastError(`Random range generation failed: ${err.message}`, {
+                    location: [{ filename: "random_range", line: 0n, column: 0n }],
+                    cause: err
+                });
+            }
+        }),
+        random_exponential.implement((lambda) => {
+            try {
+                return exponentialDist(state.rng, lambda)();
+            }
+            catch (err) {
+                throw new EastError(`Random exponential generation failed: ${err.message}`, {
+                    location: [{ filename: "random_exponential", line: 0n, column: 0n }],
+                    cause: err
+                });
+            }
+        }),
+        random_weibull.implement((shape) => {
+            try {
+                // Weibull = exponential() ^ (1/shape)
+                const exp = exponentialDist(state.rng, 1);
+                return Math.pow(exp(), 1 / shape);
+            }
+            catch (err) {
+                throw new EastError(`Random Weibull generation failed: ${err.message}`, {
+                    location: [{ filename: "random_weibull", line: 0n, column: 0n }],
+                    cause: err
+                });
+            }
+        }),
+        random_bernoulli.implement((p) => {
+            try {
+                return BigInt(bernoulliDist(state.rng, p)());
+            }
+            catch (err) {
+                throw new EastError(`Random Bernoulli generation failed: ${err.message}`, {
+                    location: [{ filename: "random_bernoulli", line: 0n, column: 0n }],
+                    cause: err
+                });
+            }
+        }),
+        random_binomial.implement((n, p) => {
+            try {
+                return BigInt(binomialDist(state.rng, n, p)());
+            }
+            catch (err) {
+                throw new EastError(`Random binomial generation failed: ${err.message}`, {
+                    location: [{ filename: "random_binomial", line: 0n, column: 0n }],
+                    cause: err
+                });
+            }
+        }),
+        random_geometric.implement((p) => {
+            try {
+                return BigInt(geometricDist(state.rng, p)());
+            }
+            catch (err) {
+                throw new EastError(`Random geometric generation failed: ${err.message}`, {
+                    location: [{ filename: "random_geometric", line: 0n, column: 0n }],
+                    cause: err
+                });
+            }
+        }),
+        random_poisson.implement((lambda) => {
+            try {
+                return BigInt(poissonDist(state.rng, lambda)());
+            }
+            catch (err) {
+                throw new EastError(`Random Poisson generation failed: ${err.message}`, {
+                    location: [{ filename: "random_poisson", line: 0n, column: 0n }],
+                    cause: err
+                });
+            }
+        }),
+        random_pareto.implement((alpha) => {
+            try {
+                return paretoDist(state.rng, alpha)();
+            }
+            catch (err) {
+                throw new EastError(`Random Pareto generation failed: ${err.message}`, {
+                    location: [{ filename: "random_pareto", line: 0n, column: 0n }],
+                    cause: err
+                });
+            }
+        }),
+        random_log_normal.implement((mu, sigma) => {
+            try {
+                return logNormalDist(state.rng, mu, sigma)();
+            }
+            catch (err) {
+                throw new EastError(`Random log-normal generation failed: ${err.message}`, {
+                    location: [{ filename: "random_log_normal", line: 0n, column: 0n }],
+                    cause: err
+                });
+            }
+        }),
+        random_irwin_hall.implement((n) => {
+            try {
+                return irwinHallDist(state.rng, n)();
+            }
+            catch (err) {
+                throw new EastError(`Random Irwin-Hall generation failed: ${err.message}`, {
+                    location: [{ filename: "random_irwin_hall", line: 0n, column: 0n }],
+                    cause: err
+                });
+            }
+        }),
+        random_bates.implement((n) => {
+            try {
+                return batesDist(state.rng, n)();
+            }
+            catch (err) {
+                throw new EastError(`Random Bates generation failed: ${err.message}`, {
+                    location: [{ filename: "random_bates", line: 0n, column: 0n }],
+                    cause: err
+                });
+            }
+        }),
+        random_seed.implement((seed) => {
+            // Switch to seedable PRNG (xorshift128+) and set the seed
+            // IMPORTANT: This disables cryptographic security for reproducible simulations
+            state.rng = new XorShift128RNG(seed);
+        }),
+    ];
+}
+/**
+ * Creates a Random implementation with its own generator, unseeded.
+ *
+ * Every Random platform function in the returned array draws from one
+ * generator that no other implementation shares: it is cryptographically
+ * secure until the program calls {@link Random.seed}. A host running one
+ * program after another in the same worker creates one per program, so a
+ * seed one program set never reaches the next — as each east-node process
+ * starts unseeded.
+ *
+ * @returns The Random platform functions, drawing from a new generator
+ *
+ * @example
+ * ```ts
+ * import { East, FloatType } from "@elaraai/east";
+ * import { Random, createRandomImpl } from "@elaraai/east-web-std";
+ *
+ * const draw = East.function([], FloatType, $ => {
+ *     $(Random.seed(42n));
+ *     return Random.uniform();
+ * });
+ *
+ * const compiled = East.compile(draw, createRandomImpl());
+ * compiled();  // The value east-node-std draws for seed 42
+ * ```
+ */
+export function createRandomImpl() {
+    return implementRandom({ rng: new CryptoRNG() });
+}
+/** The generator {@link RandomImpl} draws from. */
+const defaultState = { rng: new CryptoRNG() };
+/**
+ * Reset {@link RandomImpl}'s generator to cryptographically secure mode.
+ * Primarily for testing to avoid test pollution.
+ */
+export function resetToCryptoRNG() {
+    defaultState.rng = new CryptoRNG();
+}
+/**
+ * Browser implementation of the random platform functions, sharing one
+ * generator between every program compiled with it.
+ *
+ * Pass this array to {@link East.compile} to enable random operations, or
+ * use {@link createRandomImpl} for a generator of the program's own.
+ */
+const RandomImpl = implementRandom(defaultState);
+/**
+ * Grouped random platform functions.
+ *
+ * Provides random number generation and sampling operations for East programs,
+ * including multiple probability distributions and collection sampling.
+ *
+ * @example
+ * ```ts
+ * import { East, FloatType, IntegerType } from "@elaraai/east";
+ * import { Random } from "@elaraai/east-web-std";
+ *
+ * const rollDice = East.function([], IntegerType, $ => {
+ *     return Random.range(1n, 6n);
+ * });
+ *
+ * const compiled = East.compile(rollDice, Random.Implementation);
+ * const result = compiled();  // Random integer from 1 to 6
+ * ```
+ */
+export const Random = {
+    /**
+     * Generates a uniform random float in the range [0.0, 1.0).
+     *
+     * Returns a uniformly distributed random floating-point number greater than or equal to 0.0
+     * and strictly less than 1.0. Uses cryptographically secure random number generation.
+     *
+     * @returns A random float in [0.0, 1.0)
+     *
+     * @example
+     * ```ts
+     * const generateRandom = East.function([], FloatType, $ => {
+     *     return Random.uniform();
+     * });
+     *
+     * const compiled = East.compile(generateRandom, Random.Implementation);
+     * const result = compiled();  // e.g., 0.7234891234
+     * ```
+     */
+    uniform: random_uniform,
+    /**
+     * Generates a random float from a standard normal distribution (mean=0, standard deviation=1).
+     *
+     * Returns a random floating-point number drawn from a normal (Gaussian) distribution
+     * with mean 0.0 and standard deviation 1.0. Use multiplication and addition to scale
+     * and shift to different mean/standard deviation.
+     *
+     * @returns A random float from N(0, 1)
+     *
+     * @example
+     * ```ts
+     * const generateNormal = East.function([], FloatType, $ => {
+     *     const z = $.let(Random.normal());
+     *     // Scale and shift: z * stddev + mean
+     *     return z.multiply(2.5).add(10.0);  // N(10, 2.5)
+     * });
+     *
+     * const compiled = East.compile(generateNormal, Random.Implementation);
+     * const result = compiled();  // e.g., 9.234 (from N(10, 2.5))
+     * ```
+     */
+    normal: random_normal,
+    /**
+     * Generates a random integer in the range [min, max] (both endpoints inclusive).
+     *
+     * Returns a uniformly distributed random integer between min and max (both inclusive).
+     * Uses cryptographically secure random number generation.
+     *
+     * @param min - The minimum value (inclusive)
+     * @param max - The maximum value (inclusive, must be >= min)
+     * @returns A random integer in [min, max]
+     *
+     * @throws {EastError} When min > max
+     *
+     * @example
+     * ```ts
+     * const rollDice = East.function([], IntegerType, $ => {
+     *     return Random.range(1n, 6n);  // 1-6 inclusive
+     * });
+     *
+     * const compiled = East.compile(rollDice, Random.Implementation);
+     * const result = compiled();  // e.g., 4n
+     * ```
+     */
+    range: random_range,
+    /**
+     * Generates a random float from an exponential distribution.
+     *
+     * Returns a random floating-point number drawn from an exponential distribution
+     * with rate parameter lambda (λ). The mean of the distribution is 1/λ.
+     * Commonly used for modeling time between events in a Poisson process.
+     *
+     * @param lambda - Rate parameter (λ > 0), where mean = 1/λ
+     * @returns A random float from Exp(λ)
+     *
+     * @throws {EastError} When lambda <= 0
+     *
+     * @example
+     * ```ts
+     * const waitTime = East.function([], FloatType, $ => {
+     *     // Average wait time of 5 minutes (lambda = 0.2)
+     *     return Random.exponential(0.2);
+     * });
+     *
+     * const compiled = East.compile(waitTime, Random.Implementation);
+     * const result = compiled();  // e.g., 3.7 minutes
+     * ```
+     */
+    exponential: random_exponential,
+    /**
+     * Generates a random float from a Weibull distribution.
+     *
+     * Returns a random floating-point number drawn from a Weibull distribution
+     * with shape parameter k. Commonly used for modeling failure rates and lifetime distributions.
+     *
+     * @param shape - Shape parameter (k > 0). k=1 gives exponential, k>1 increases failure rate
+     * @returns A random float from Weibull(k, 1)
+     *
+     * @throws {EastError} When shape <= 0
+     *
+     * @example
+     * ```ts
+     * const lifetime = East.function([], FloatType, $ => {
+     *     // Shape=2 models wear-out failures
+     *     return Random.weibull(2.0);
+     * });
+     *
+     * const compiled = East.compile(lifetime, Random.Implementation);
+     * const result = compiled();  // e.g., 1.23
+     * ```
+     */
+    weibull: random_weibull,
+    /**
+     * Generates a binary random outcome (0 or 1).
+     *
+     * Returns 0 or 1 based on success probability p. This models a single
+     * Bernoulli trial, like a biased coin flip.
+     *
+     * @param p - Success probability (0 <= p < 1)
+     * @returns 0 or 1 (as integer)
+     *
+     * @throws {EastError} When p < 0 or p >= 1
+     *
+     * @example
+     * ```ts
+     * const coinFlip = East.function([], IntegerType, $ => {
+     *     // Fair coin: 50% chance of 1
+     *     return Random.bernoulli(0.5);
+     * });
+     *
+     * const compiled = East.compile(coinFlip, Random.Implementation);
+     * const result = compiled();  // e.g., 1n or 0n
+     * ```
+     */
+    bernoulli: random_bernoulli,
+    /**
+     * Generates the number of successes in n independent Bernoulli trials.
+     *
+     * Returns an integer count of successes when performing n independent trials,
+     * each with success probability p. Models scenarios like coin flips, pass/fail tests.
+     *
+     * @param n - Number of trials (integer > 0)
+     * @param p - Success probability per trial (0 <= p < 1)
+     * @returns Number of successes (integer in [0, n])
+     *
+     * @throws {EastError} When n <= 0, not an integer, or p < 0 or p >= 1
+     *
+     * @example
+     * ```ts
+     * const heads = East.function([], IntegerType, $ => {
+     *     // Number of heads in 10 coin flips
+     *     return Random.binomial(10n, 0.5);
+     * });
+     *
+     * const compiled = East.compile(heads, Random.Implementation);
+     * const result = compiled();  // e.g., 6n
+     * ```
+     */
+    binomial: random_binomial,
+    /**
+     * Generates the number of trials until the first success.
+     *
+     * Returns an integer representing the number of independent Bernoulli trials
+     * needed to get the first success, where each trial has success probability p.
+     * Models scenarios like "how many attempts until success?"
+     *
+     * @param p - Success probability per trial (0 < p < 1)
+     * @returns Number of trials until first success (integer >= 1)
+     *
+     * @throws {EastError} When p <= 0 or p >= 1
+     *
+     * @example
+     * ```ts
+     * const attempts = East.function([], IntegerType, $ => {
+     *     // Rolls until getting a 6 (p = 1/6)
+     *     return Random.geometric(1.0 / 6.0);
+     * });
+     *
+     * const compiled = East.compile(attempts, Random.Implementation);
+     * const result = compiled();  // e.g., 4n
+     * ```
+     */
+    geometric: random_geometric,
+    /**
+     * Generates the number of events in a fixed interval from a Poisson process.
+     *
+     * Returns an integer count of events occurring in a fixed interval,
+     * where events occur independently at a constant average rate λ (lambda).
+     * Commonly used for modeling rare events, arrivals, or counts.
+     *
+     * @param lambda - Average rate of events (λ > 0)
+     * @returns Number of events (integer >= 0)
+     *
+     * @throws {EastError} When lambda <= 0
+     *
+     * @example
+     * ```ts
+     * const customers = East.function([], IntegerType, $ => {
+     *     // Average 3 customers per hour
+     *     return Random.poisson(3.0);
+     * });
+     *
+     * const compiled = East.compile(customers, Random.Implementation);
+     * const result = compiled();  // e.g., 2n
+     * ```
+     */
+    poisson: random_poisson,
+    /**
+     * Generates a random float from a Pareto distribution (power law).
+     *
+     * Returns a random floating-point number drawn from a Pareto distribution
+     * with shape parameter α (alpha). Models phenomena following power laws,
+     * like wealth distribution, city sizes, or word frequencies.
+     *
+     * @param alpha - Shape parameter (α >= 0). Smaller α = heavier tail
+     * @returns A random float from Pareto(α) (value >= 1.0)
+     *
+     * @throws {EastError} When alpha < 0
+     *
+     * @example
+     * ```ts
+     * const wealth = East.function([], FloatType, $ => {
+     *     // Heavy-tailed distribution (80/20 rule)
+     *     return Random.pareto(1.16);
+     * });
+     *
+     * const compiled = East.compile(wealth, Random.Implementation);
+     * const result = compiled();  // e.g., 2.45
+     * ```
+     */
+    pareto: random_pareto,
+    /**
+     * Generates a random float whose logarithm is normally distributed.
+     *
+     * Returns a random floating-point number from a log-normal distribution,
+     * where ln(X) ~ N(μ, σ²). Commonly used for modeling multiplicative processes,
+     * stock prices, or quantities that can't be negative.
+     *
+     * @param mu - Mean of underlying normal distribution
+     * @param sigma - Standard deviation of underlying normal (must be > 0)
+     * @returns A random float from LogNormal(μ, σ) (always positive)
+     *
+     * @example
+     * ```ts
+     * const stockPrice = East.function([], FloatType, $ => {
+     *     // Log-normal with ln(X) ~ N(0, 0.2)
+     *     return Random.logNormal(0.0, 0.2);
+     * });
+     *
+     * const compiled = East.compile(stockPrice, Random.Implementation);
+     * const result = compiled();  // e.g., 1.15
+     * ```
+     */
+    logNormal: random_log_normal,
+    /**
+     * Generates the sum of n independent uniform random variables.
+     *
+     * Returns the sum of n independent uniform(0,1) random variables.
+     * This is the Irwin-Hall distribution. As n increases, approaches
+     * normal distribution by Central Limit Theorem.
+     *
+     * @param n - Number of uniform variables to sum (integer >= 0)
+     * @returns Sum of n uniform(0,1) random variables (float in [0, n])
+     *
+     * @throws {EastError} When n < 0 or not an integer
+     *
+     * @example
+     * ```ts
+     * const irwinHall = East.function([], FloatType, $ => {
+     *     // Sum of 12 uniform variables
+     *     return Random.irwinHall(12n);
+     * });
+     *
+     * const compiled = East.compile(irwinHall, Random.Implementation);
+     * const result = compiled();  // e.g., 6.234 (approximately N(6, 1))
+     * ```
+     */
+    irwinHall: random_irwin_hall,
+    /**
+     * Generates the average of n independent uniform random variables.
+     *
+     * Returns the average of n independent uniform(0,1) random variables.
+     * This is the Bates distribution. Approaches normal distribution as
+     * n increases (Central Limit Theorem).
+     *
+     * @param n - Number of uniform variables to average (integer > 0)
+     * @returns Average of n uniform(0,1) random variables (float in [0, 1])
+     *
+     * @throws {EastError} When n <= 0 or not an integer
+     *
+     * @example
+     * ```ts
+     * const bates = East.function([], FloatType, $ => {
+     *     // Average of 12 uniform variables (smoother than single uniform)
+     *     return Random.bates(12n);
+     * });
+     *
+     * const compiled = East.compile(bates, Random.Implementation);
+     * const result = compiled();  // e.g., 0.523 (approximately N(0.5, 1/144))
+     * ```
+     */
+    bates: random_bates,
+    /**
+     * Seeds the random number generator.
+     *
+     * Sets the seed for the random number generator, allowing reproducible random sequences.
+     * All subsequent random operations will use this seeded RNG until a new seed is set.
+     *
+     * @param seed - Seed value (integer)
+     * @returns null
+     *
+     * @example
+     * ```ts
+     * const seedAndGenerate = East.function([], FloatType, $ => {
+     *     $(Random.seed(12345n));
+     *     return Random.uniform();  // Will be reproducible
+     * });
+     *
+     * const compiled = East.compile(seedAndGenerate, Random.Implementation);
+     * const result = compiled();  // Same result every time with same seed
+     * ```
+     *
+     * @remarks
+     * IMPORTANT: Seeding switches from cryptographically secure random to a deterministic
+     * PRNG (xorshift128+). Essential for reproducible simulations. A seed gives the
+     * sequence east-node-std gives for it.
+     */
+    seed: random_seed,
+    /**
+     * Browser implementation of random platform functions.
+     *
+     * Pass this to {@link East.compile} to enable random operations.
+     */
+    Implementation: RandomImpl,
+};
+// Exported beside `Random.Implementation`, as east-node-std exports them
+export { RandomImpl, XorShift128RNG };
+//# sourceMappingURL=random.js.map