# mozz.arbitrary

> A module of mozz_mlake's API.

Typed random value generation for property-based testing.

The ``Fuzzable`` trait enables ``forall[T: Fuzzable](...)`` to generate
well-typed test cases.  Implementations for all primitive Mojo types ship
with the library.

Example:
    ```mojo
    var rng = Xoshiro256(seed=99)
    var u = FuzzableUInt16.generate(rng)   # random UInt16 (boundary-biased)
    var s = FuzzableString.generate(rng)   # random valid UTF-8 string
    var xs = FuzzableBytes.generate(rng)   # random List[UInt8]
    ```

Custom types:
    ```mojo
    struct Point:
        var x: Int
        var y: Int

        @staticmethod
        def generate(mut rng: Xoshiro256) -> Point:
            return Point(x=FuzzableInt.generate(rng), y=FuzzableInt.generate(rng))

        @staticmethod
        def minimize(value: Point) -> List[Point]:
            var out = List[Point]()
            if value.x != 0:
                out.append(Point(x=0, y=value.y))
            if value.y != 0:
                out.append(Point(x=value.x, y=0))
            return out^
    ```

## Structs

### `FuzzableBool`

```mojo
struct FuzzableBool
```

``Fuzzable`` implementation for ``Bool``.

Implements: `Movable`

#### `generate`

```mojo
def generate(mut rng: Xoshiro256) -> Bool
```

Generate a uniformly random boolean.

Args:

- `rng`: PRNG state (advanced in-place).

#### `minimize`

```mojo
def minimize(value: Bool) -> List[Bool]
```

Minimize: ``True`` → ``[False]``, ``False`` → ``[]``.

Args:

- `value`: The value to minimize.

### `FuzzableUInt8`

```mojo
struct FuzzableUInt8
```

``Fuzzable`` implementation for ``UInt8``.

Implements: `Movable`

#### `generate`

```mojo
def generate(mut rng: Xoshiro256) -> UInt8
```

Generate a random ``UInt8`` with 20% boundary bias.

Args:

- `rng`: PRNG state (advanced in-place).

#### `minimize`

```mojo
def minimize(value: UInt8) -> List[UInt8]
```

Minimize toward 0: ``v`` → ``[0, v/2]`` (if distinct).

Args:

- `value`: Value to minimize.

### `FuzzableUInt16`

```mojo
struct FuzzableUInt16
```

``Fuzzable`` implementation for ``UInt16``.

Implements: `Movable`

#### `generate`

```mojo
def generate(mut rng: Xoshiro256) -> UInt16
```

Generate a random ``UInt16`` with 20% boundary bias.

Args:

- `rng`: PRNG state (advanced in-place).

#### `minimize`

```mojo
def minimize(value: UInt16) -> List[UInt16]
```

Minimize toward 0.

Args:

- `value`: Value to minimize.

### `FuzzableUInt32`

```mojo
struct FuzzableUInt32
```

``Fuzzable`` implementation for ``UInt32``.

Implements: `Movable`

#### `generate`

```mojo
def generate(mut rng: Xoshiro256) -> UInt32
```

Generate a random ``UInt32`` with 20% boundary bias.

Args:

- `rng`: PRNG state (advanced in-place).

#### `minimize`

```mojo
def minimize(value: UInt32) -> List[UInt32]
```

Minimize toward 0.

Args:

- `value`: Value to minimize.

### `FuzzableUInt64`

```mojo
struct FuzzableUInt64
```

``Fuzzable`` implementation for ``UInt64``.

Implements: `Movable`

#### `generate`

```mojo
def generate(mut rng: Xoshiro256) -> UInt64
```

Generate a random ``UInt64`` with 20% boundary bias.

Args:

- `rng`: PRNG state (advanced in-place).

#### `minimize`

```mojo
def minimize(value: UInt64) -> List[UInt64]
```

Minimize toward 0.

Args:

- `value`: Value to minimize.

### `FuzzableInt`

```mojo
struct FuzzableInt
```

``Fuzzable`` implementation for ``Int``.

Implements: `Movable`

#### `generate`

```mojo
def generate(mut rng: Xoshiro256) -> Int
```

Generate a random ``Int`` with 20% boundary bias.

Generates values across the full signed range, including negative
integers.  Boundary values (0, ±1, ±2^7, ±2^31, etc.) are produced
with 20% probability to increase edge-case coverage.

Args:

- `rng`: PRNG state (advanced in-place).

#### `minimize`

```mojo
def minimize(value: Int) -> List[Int]
```

Minimize toward 0.

Args:

- `value`: Value to minimize.

### `FuzzableString`

```mojo
struct FuzzableString
```

``Fuzzable`` implementation for ``String``.

Generates valid UTF-8 strings with up to 256 code points.  The character
set is weighted: 70% ASCII printable, 15% ASCII control, 15% two-byte
UTF-8.  Because two-byte codepoints occupy 2 bytes each, the maximum byte
length is 512.

Implements: `Movable`

#### `generate`

```mojo
def generate(mut rng: Xoshiro256) -> String
```

Generate a random valid UTF-8 string.

Args:

- `rng`: PRNG state (advanced in-place).

#### `minimize`

```mojo
def minimize(value: String) -> List[String]
```

Minimize by dropping the second half or removing a character.

Args:

- `value`: String to minimize.

### `FuzzableBytes`

```mojo
struct FuzzableBytes
```

``Fuzzable`` implementation for raw bytes ``List[UInt8]``.

Generates length 0–256 byte sequences with no UTF-8 constraint.
Useful for raw byte fuzzing targets.

Implements: `Movable`

#### `generate`

```mojo
def generate(mut rng: Xoshiro256) -> List[UInt8]
```

Generate a random byte sequence of length 0–256.

Args:

- `rng`: PRNG state (advanced in-place).

#### `minimize`

```mojo
def minimize(value: List[UInt8]) -> List[List[UInt8]]
```

Minimize by halving or truncating.

Args:

- `value`: Bytes to minimize.

### `Gen`

```mojo
struct Gen[T: ImplicitlyCopyable]
```

Compile-time-dispatched generator and minimizer for built-in types.

Provides a unified parametric API so callers write ``Gen[UInt8].generate(rng)``
instead of ``FuzzableUInt8.generate(rng)``.  Supported type parameters:
``Bool``, ``UInt8``, ``UInt16``, ``UInt32``, ``UInt64``, ``Int``,
``String``.  For ``List[UInt8]`` use ``FuzzableBytes`` directly (generic
list instantiations are not yet dispatchable via ``comptime if``).

For user-defined types, write a companion ``FuzzableMyType`` struct
following the same ``generate`` / ``minimize`` static-method pattern and
pass it explicitly to ``forall()``.

Example:
```mojo
var rng = Xoshiro256(seed=1)
var v = Gen[UInt16].generate(rng)      # boundary-biased UInt16
var smaller = Gen[UInt16].minimize(v)   # simpler candidates
```

Implements: `Movable`

#### `generate`

```mojo
def generate(mut rng: Xoshiro256) -> T
```

Generate a random instance of ``T`` using boundary-biased sampling.

Args:

- `rng`: PRNG state (advanced in-place).

#### `minimize`

```mojo
def minimize(value: T) -> List[T]
```

Return simpler variants of ``value`` for counterexample minimization.

Args:

- `value`: The counterexample to simplify.

## Traits

### `Fuzzable`

```mojo
undefined
```

Trait for types that can generate random instances of themselves.

Implement ``generate(rng)`` to produce a random value and optionally
``minimize(value)`` to return simpler variants for counterexample
minimization.

Types implementing ``Fuzzable`` work automatically with ``forall[T]()``
and ``forall_bytes()``.

Note:
    Requires ``Copyable`` and ``Movable`` because ``minimize()`` returns
    ``List[Self]``, which requires ``Self: Copyable``.

Implements: `Copyable`, `Movable`

#### `generate`

```mojo
def generate(mut rng: Xoshiro256) -> Self
```

Generate a random instance of ``Self``.

Args:

- `rng`: PRNG state (advanced in-place).

#### `minimize`

```mojo
def minimize(value) -> List[_Self]
```

Return simpler variants of ``value`` for counterexample minimization.

The default implementation returns an empty list (no minimization).
Override to provide problem-specific simplifications.

Args:

- `value`: The counterexample to simplify.