@umbra-privacy/sdk 1.0.0 → 2.0.1

package/dist/types-C_V_CaKK.d.ts

@@ -0,0 +1,2468 @@
+/**
+ * Branded Types Infrastructure
+ *
+ * Provides compile-time nominal typing for the SDK through a hierarchical branded type system.
+ * Branded types prevent accidental mixing of structurally identical values — for example,
+ * passing a `U64` where a `U128` is expected, or a `RcPlaintext` where a `RcCiphertext` is
+ * required. Because TypeScript uses structural typing, two types with the same underlying
+ * representation (e.g. both `bigint`) are otherwise interchangeable, which is a silent source
+ * of hard-to-detect bugs in cryptographic and protocol code.
+ *
+ * ## The Branded Type Pattern
+ *
+ * A branded type is formed by intersecting a base type `T` with an object carrying a unique
+ * phantom symbol property. The symbol is declared with `declare const ... : unique symbol`,
+ * which guarantees TypeScript treats it as distinct from every other symbol — the brand itself
+ * never exists at runtime and adds zero bytes to the value.
+ *
+ * ```
+ * type UserId = BrandedType<string, "UserId">;
+ * //            ^^^^^^^^^^ string — the runtime representation
+ * //                       ^^^^^^^^ "UserId" — the phantom brand
+ * ```
+ *
+ * ## Hierarchical Brands
+ *
+ * The module supports up to five levels of brand hierarchy through `SubBrandedType`,
+ * `SubSubBrandedType`, etc. A sub-brand inherits structural compatibility with its parent,
+ * allowing a more specific type to be used wherever the parent is accepted, but not vice versa.
+ * This mirrors subtype relationships (e.g. `U32LeBytes ⊆ LeBytes ⊆ Bytes`).
+ *
+ * ## Utility Types
+ *
+ * `UnwrapBrand` and `ExtractBrand` are provided for generic code that needs to inspect or
+ * strip the brand layer without discarding the base type information.
+ *
+ * @packageDocumentation
+ * @since 2.0.0
+ * @module common/branded
+ */
+/**
+ * Unique symbol used as the primary brand property key.
+ *
+ * @remarks
+ * Declared with `unique symbol` so TypeScript guarantees no two declarations of
+ * `BrandSymbol` can be the same symbol, making it impossible to accidentally collide
+ * with user-defined properties. The value never exists at runtime.
+ *
+ * @internal
+ */
+declare const BrandSymbol: unique symbol;
+/**
+ * Unique symbol used as the sub-brand property key.
+ *
+ * @remarks
+ * Attached to a branded type by `SubBrandedType` to create a second phantom dimension
+ * that distinguishes sub-types from their parent without breaking parent assignability.
+ *
+ * @internal
+ */
+declare const SubBrandSymbol: unique symbol;
+/**
+ * Unique symbol used as the sub-sub-brand property key.
+ *
+ * @remarks
+ * Attached by `SubSubBrandedType` to create a third phantom dimension.
+ *
+ * @internal
+ */
+declare const SubSubBrandSymbol: unique symbol;
+/**
+ * Unique symbol used as the sub-sub-sub-brand property key.
+ *
+ * @remarks
+ * Attached by `SubSubSubBrandedType` to create a fourth phantom dimension.
+ *
+ * @internal
+ */
+declare const SubSubSubBrandSymbol: unique symbol;
+/**
+ * Unique symbol used as the sub-sub-sub-sub-brand property key.
+ *
+ * @remarks
+ * Attached by `SubSubSubSubBrandedType` to create a fifth phantom dimension.
+ *
+ * @internal
+ */
+declare const SubSubSubSubBrandSymbol: unique symbol;
+/**
+ * Creates a branded (nominally typed) variant of a base type.
+ *
+ * @remarks
+ * The brand is encoded as a readonly phantom property keyed by `BrandSymbol` whose
+ * value type is the string literal `Brand`. Because `BrandSymbol` is a `unique symbol`,
+ * no two `BrandedType` declarations share the same property key unless they name the same
+ * `Brand` string. This makes cross-brand assignment a compile-time error.
+ *
+ * At runtime the intersection carries no extra data — branded values are stored and
+ * transmitted identically to their base type.
+ *
+ * Use `UnwrapBrand` to recover `Base` and `ExtractBrand` to recover `Brand` from a
+ * `BrandedType` in generic contexts.
+ *
+ * @typeParam Base - The underlying runtime type (e.g. `bigint`, `Uint8Array`, `string`).
+ * @typeParam Brand - A unique string literal that names this brand (e.g. `"U64"`, `"UserId"`).
+ *
+ * @example
+ * ```typescript
+ * // Define two distinct identifier types with the same underlying representation.
+ * type UserId = BrandedType<string, "UserId">;
+ * type PostId = BrandedType<string, "PostId">;
+ *
+ * // Values must be explicitly branded at the boundary.
+ * const userId: UserId = "user-123" as UserId;
+ * const postId: PostId = "post-456" as PostId;
+ *
+ * // TypeScript rejects accidental mixing:
+ * const invalid: PostId = userId; // Error: Type 'UserId' is not assignable to type 'PostId'.
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Numeric brands prevent silent precision loss in the SDK.
+ * type U64  = BrandedType<bigint, "U64">;
+ * type U128 = BrandedType<bigint, "U128">;
+ *
+ * function encryptU64(value: U64): void { ... }
+ * encryptU64(myU128Value); // Compile-time error — prevents protocol bugs.
+ * ```
+ *
+ * @public
+ */
+type BrandedType<Base, Brand extends string> = Base & {
+    readonly [BrandSymbol]: Brand;
+};
+/**
+ * Extracts the base (unbranded) type from a `BrandedType`.
+ *
+ * @remarks
+ * Useful in generic utilities that need to operate on the underlying representation
+ * without caring about the nominal layer. For non-branded types, `T` is returned
+ * unchanged, making this safe to apply unconditionally.
+ *
+ * @typeParam T - A `BrandedType` or plain type to unwrap.
+ *
+ * @example
+ * ```typescript
+ * type UserId = BrandedType<string, "UserId">;
+ * type Base = UnwrapBrand<UserId>; // string
+ *
+ * // Non-branded types pass through unchanged.
+ * type Plain = UnwrapBrand<number>; // number
+ * ```
+ *
+ * @public
+ */
+type UnwrapBrand<T> = T extends BrandedType<infer Base, string> ? Base : T;
+/**
+ * Extracts the brand string literal from a `BrandedType`.
+ *
+ * @remarks
+ * Returns `never` for types that are not `BrandedType` instances. Useful when building
+ * generic error messages or runtime assertions that need to name the expected brand.
+ *
+ * @typeParam T - A `BrandedType` from which to extract the brand name.
+ *
+ * @example
+ * ```typescript
+ * type UserId = BrandedType<string, "UserId">;
+ * type Name = ExtractBrand<UserId>; // "UserId"
+ *
+ * // Non-branded types yield never.
+ * type Nothing = ExtractBrand<string>; // never
+ * ```
+ *
+ * @public
+ */
+type ExtractBrand<T> = T extends BrandedType<unknown, infer Brand> ? Brand : never;
+/**
+ * Creates a sub-branded type that is a more specific variant of an existing `BrandedType`.
+ *
+ * @remarks
+ * A sub-branded type carries both the parent brand (via `[BrandSymbol]`) and its own
+ * sub-brand (via `[SubBrandSymbol]`). This means:
+ *
+ * - A `SubBrandedType<Parent, Sub>` is assignable to `Parent` (narrower types are compatible).
+ * - `Parent` is NOT assignable to `SubBrandedType<Parent, Sub>` (you cannot widen without
+ *   an explicit assertion).
+ *
+ * This is used in the SDK to model byte-array hierarchies such as:
+ * `Bytes` → `LeBytes` → `U32LeBytes`.
+ *
+ * @typeParam Parent - The parent `BrandedType` to extend. Must already be a `BrandedType`.
+ * @typeParam SubBrand - A unique string literal for the sub-brand (e.g. `"LeBytes"`).
+ *
+ * @example
+ * ```typescript
+ * type Bytes    = BrandedType<Uint8Array, "Bytes">;
+ * type LeBytes  = SubBrandedType<Bytes, "LeBytes">;
+ * type BeBytes  = SubBrandedType<Bytes, "BeBytes">;
+ *
+ * declare const le: LeBytes;
+ * declare const be: BeBytes;
+ *
+ * const asBytes: Bytes = le;  // OK — LeBytes ⊆ Bytes
+ * const invalid: BeBytes = le; // Error — LeBytes is not BeBytes
+ * ```
+ *
+ * @public
+ */
+type SubBrandedType<Parent extends BrandedType<unknown, string>, SubBrand extends string> = Parent & {
+    readonly [SubBrandSymbol]: SubBrand;
+};
+/**
+ * Creates a sub-sub-branded type for the third level of the brand hierarchy.
+ *
+ * @remarks
+ * Inherits both the parent brand and the sub-brand, adding a third phantom dimension via
+ * `[SubSubBrandSymbol]`. A `SubSubBrandedType` is assignable to its `SubBrandedType`
+ * parent and transitively to the root `BrandedType`, but nothing in the hierarchy can
+ * be widened to a `SubSubBrandedType` without an explicit assertion.
+ *
+ * Typical usage in the SDK:
+ * `Bytes` → `LeBytes` → `U32LeBytes`
+ *
+ * @typeParam Parent - The parent `SubBrandedType` to extend.
+ * @typeParam SubSubBrand - A unique string literal for this level (e.g. `"U32LeBytes"`).
+ *
+ * @example
+ * ```typescript
+ * type Bytes       = BrandedType<Uint8Array, "Bytes">;
+ * type LeBytes     = SubBrandedType<Bytes, "LeBytes">;
+ * type U32LeBytes  = SubSubBrandedType<LeBytes, "U32LeBytes">;
+ *
+ * declare const u32: U32LeBytes;
+ * const asLe: LeBytes = u32;  // OK
+ * const asBytes: Bytes = u32; // OK
+ * ```
+ *
+ * @public
+ */
+type SubSubBrandedType<Parent extends SubBrandedType<BrandedType<unknown, string>, string>, SubSubBrand extends string> = Parent & {
+    readonly [SubSubBrandSymbol]: SubSubBrand;
+};
+/**
+ * Creates a sub-sub-sub-branded type for the fourth level of the brand hierarchy.
+ *
+ * @remarks
+ * Adds a fourth phantom dimension via `[SubSubSubBrandSymbol]` on top of a
+ * `SubSubBrandedType` parent. Assignable to all ancestor levels.
+ *
+ * Typical usage in the SDK:
+ * `Bytes` → `LeBytes` → `U256LeBytes` → `Keccak256Hash`
+ *
+ * @typeParam Parent - The parent `SubSubBrandedType` to extend.
+ * @typeParam SubSubSubBrand - A unique string literal for this level (e.g. `"Keccak256Hash"`).
+ *
+ * @example
+ * ```typescript
+ * type Bytes          = BrandedType<Uint8Array, "Bytes">;
+ * type LeBytes        = SubBrandedType<Bytes, "LeBytes">;
+ * type U32LeBytes     = SubSubBrandedType<LeBytes, "U32LeBytes">;
+ * type ValidU32LeBytes = SubSubSubBrandedType<U32LeBytes, "ValidU32LeBytes">;
+ *
+ * declare const v: ValidU32LeBytes;
+ * const asU32: U32LeBytes = v; // OK
+ * const asLe: LeBytes     = v; // OK
+ * const asBytes: Bytes    = v; // OK
+ * ```
+ *
+ * @public
+ */
+type SubSubSubBrandedType<Parent extends SubSubBrandedType<SubBrandedType<BrandedType<unknown, string>, string>, string>, SubSubSubBrand extends string> = Parent & {
+    readonly [SubSubSubBrandSymbol]: SubSubSubBrand;
+};
+/**
+ * Creates a sub-sub-sub-sub-branded type for the fifth level of the brand hierarchy.
+ *
+ * @remarks
+ * Adds a fifth phantom dimension via `[SubSubSubSubBrandSymbol]` on top of a
+ * `SubSubSubBrandedType` parent. This is the deepest level of branding supported by the
+ * SDK. Assignable to all four ancestor levels.
+ *
+ * Example chain used in the SDK for master seed derivation:
+ * `Bytes` → `LeBytes` → `U512LeBytes` → `Keccak512Hash` → `MasterSeed`
+ *
+ * @typeParam Parent - The parent `SubSubSubBrandedType` to extend.
+ * @typeParam SubSubSubSubBrand - A unique string literal for this level (e.g. `"MasterSeed"`).
+ *
+ * @example
+ * ```typescript
+ * type Bytes          = BrandedType<Uint8Array, "Bytes">;
+ * type LeBytes        = SubBrandedType<Bytes, "LeBytes">;
+ * type U512LeBytes    = SubSubBrandedType<LeBytes, "U512LeBytes">;
+ * type Keccak512Hash  = SubSubSubBrandedType<U512LeBytes, "Keccak512Hash">;
+ * type MasterSeed     = SubSubSubSubBrandedType<Keccak512Hash, "MasterSeed">;
+ *
+ * // MasterSeed is assignable to every ancestor level.
+ * declare const seed: MasterSeed;
+ * const asHash: Keccak512Hash  = seed; // OK
+ * const asU512: U512LeBytes    = seed; // OK
+ * const asLe: LeBytes          = seed; // OK
+ * const asBytes: Bytes         = seed; // OK
+ * ```
+ *
+ * @public
+ */
+type SubSubSubSubBrandedType<Parent extends SubSubSubBrandedType<SubSubBrandedType<SubBrandedType<BrandedType<unknown, string>, string>, string>, string>, SubSubSubSubBrand extends string> = Parent & {
+    readonly [SubSubSubSubBrandSymbol]: SubSubSubSubBrand;
+};
+
+/**
+ * Mathematics Types Module
+ *
+ * This module provides a comprehensive set of branded types and runtime assertions
+ * for mathematical primitives used throughout the SDK. These types ensure compile-time
+ * safety by preventing accidental mixing of incompatible numeric representations.
+ *
+ * ## Overview
+ *
+ * The module is organized into several categories:
+ *
+ * ### Byte Array Types
+ * - **Base types**: `LeBytes` (little-endian), `BeBytes` (big-endian)
+ * - **Sized types**: `U8LeBytes`, `U16LeBytes`, ..., `U1024LeBytes` (and BE equivalents)
+ *
+ * ### Integer Types
+ * - **Unsigned**: `U8`, `U16`, `U32`, `U64`, `U128`, `U256`, `U512`, `U1024`
+ * - **Signed**: `I8`, `I16`, `I32`, `I64`, `I128`, `I256`, `I512`, `I1024`
+ *
+ * ### Constants
+ * - Maximum values for unsigned types (`U8_MAX`, `U16_MAX`, etc.)
+ * - Min/max values for signed types (`I8_MIN`, `I8_MAX`, etc.)
+ * - Byte lengths for sized arrays (`U8_BYTE_LENGTH`, etc.)
+ *
+ * ### Assertion Functions
+ * - Runtime validation functions that throw `MathematicsAssertionError` on failure
+ * - Return branded types on success for type-safe usage
+ *
+ * ## Usage Example
+ *
+ * ```typescript
+ * import { assertU256, assertU256LeBytes, U256, U256LeBytes } from "./mathematics";
+ *
+ * // Validate and brand a bigint as U256
+ * const value: U256 = assertU256(12345n);
+ *
+ * // Validate and brand a byte array
+ * const bytes: U256LeBytes = assertU256LeBytes(new Uint8Array(32));
+ *
+ * // Type errors are caught at compile time
+ * function processU256(value: U256): void { ... }
+ * processU256(12345n); // Error: bigint is not assignable to U256
+ * processU256(assertU256(12345n)); // OK
+ * ```
+ *
+ * @since 2.0.0
+ * @module types/mathematics
+ * @see {@link ./branded} for the underlying branded type utilities
+ * @packageDocumentation
+ */
+
+/**
+ * Generic branded byte array base type.
+ *
+ * This is the root type for all byte array types in the SDK.
+ * All specialized byte array types (LeBytes, BeBytes, X25519Bytes, etc.)
+ * derive from this type.
+ *
+ * Use this type when:
+ * - Endianness is not relevant to the operation
+ * - Endianness is handled externally
+ * - Working with raw binary data without numeric interpretation
+ *
+ * @example
+ * ```typescript
+ * function hashBytes(data: Bytes): Bytes {
+ *     // Endianness doesn't matter for hashing
+ *     return sha256(data);
+ * }
+ * ```
+ *
+ * @public
+ */
+type Bytes = BrandedType<Uint8Array, "Bytes">;
+/**
+ * Little-endian byte array base type.
+ *
+ * Little-endian format stores the **least significant byte first**.
+ * This is the native byte order for:
+ * - x86 and x64 processors (Intel, AMD)
+ * - ARM processors (in little-endian mode)
+ * - Most modern desktop and mobile CPUs
+ *
+ * @remarks
+ * Little-endian is often more efficient for arithmetic operations
+ * as the least significant bytes can be processed first.
+ *
+ * @example
+ * ```typescript
+ * // The 32-bit number 0x12345678 in little-endian:
+ * // Memory layout: [0x78, 0x56, 0x34, 0x12]
+ * //                 LSB                  MSB
+ * const leBytes = assertLeBytes(new Uint8Array([0x78, 0x56, 0x34, 0x12]));
+ *
+ * // Converting to number (conceptually):
+ * // 0x78 + (0x56 << 8) + (0x34 << 16) + (0x12 << 24) = 0x12345678
+ * ```
+ *
+ * @see {@link BeBytes} for big-endian representation
+ * @public
+ */
+type LeBytes = SubBrandedType<Bytes, "LeBytes">;
+/**
+ * Big-endian byte array base type.
+ *
+ * Big-endian format stores the **most significant byte first**.
+ * This is used in:
+ * - Network protocols (TCP/IP) - hence "network byte order"
+ * - Many file formats (JPEG, PNG headers)
+ * - Java's DataInputStream/DataOutputStream
+ * - Most cryptographic specifications
+ *
+ * @remarks
+ * Big-endian is often more human-readable as bytes appear in the
+ * same order as the hexadecimal representation.
+ *
+ * @example
+ * ```typescript
+ * // The 32-bit number 0x12345678 in big-endian:
+ * // Memory layout: [0x12, 0x34, 0x56, 0x78]
+ * //                 MSB                  LSB
+ * const beBytes = assertBeBytes(new Uint8Array([0x12, 0x34, 0x56, 0x78]));
+ *
+ * // The hex string "12345678" maps directly to bytes
+ * ```
+ *
+ * @see {@link LeBytes} for little-endian representation
+ * @public
+ */
+type BeBytes = SubBrandedType<Bytes, "BeBytes">;
+/**
+ * 8-bit (1 byte) little-endian byte array.
+ *
+ * Represents a single byte, which is endianness-agnostic.
+ * Included for API consistency with larger sizes.
+ *
+ * @remarks
+ * - Size: 1 byte
+ * - Value range: [0, 255] (0x00 to 0xFF)
+ *
+ * @example
+ * ```typescript
+ * const byte = assertU8LeBytes(new Uint8Array([0xFF]));
+ * // Represents the value 255
+ * ```
+ *
+ * @see {@link assertU8LeBytes}
+ * @public
+ */
+type U8LeBytes = SubSubBrandedType<LeBytes, "U8LeBytes">;
+/**
+ * 16-bit (2 bytes) little-endian byte array.
+ *
+ * @remarks
+ * - Size: 2 bytes
+ * - Value range: [0, 65,535] (0x0000 to 0xFFFF)
+ *
+ * @example
+ * ```typescript
+ * // Value 0x1234 in little-endian
+ * const bytes = assertU16LeBytes(new Uint8Array([0x34, 0x12]));
+ * ```
+ *
+ * @see {@link assertU16LeBytes}
+ * @public
+ */
+type U16LeBytes = SubSubBrandedType<LeBytes, "U16LeBytes">;
+/**
+ * 32-bit (4 bytes) little-endian byte array.
+ *
+ * @remarks
+ * - Size: 4 bytes
+ * - Value range: [0, 4,294,967,295] (0x00000000 to 0xFFFFFFFF)
+ * - Common use: IPv4 addresses, 32-bit hashes, timestamps
+ *
+ * @example
+ * ```typescript
+ * // Value 0x12345678 in little-endian
+ * const bytes = assertU32LeBytes(new Uint8Array([0x78, 0x56, 0x34, 0x12]));
+ * ```
+ *
+ * @see {@link assertU32LeBytes}
+ * @public
+ */
+type U32LeBytes = SubSubBrandedType<LeBytes, "U32LeBytes">;
+/**
+ * 64-bit (8 bytes) little-endian byte array.
+ *
+ * @remarks
+ * - Size: 8 bytes
+ * - Value range: [0, 2^64 - 1]
+ * - Common use: Timestamps with nanosecond precision, large counters
+ *
+ * @example
+ * ```typescript
+ * const bytes = assertU64LeBytes(new Uint8Array(8));
+ * ```
+ *
+ * @see {@link assertU64LeBytes}
+ * @public
+ */
+type U64LeBytes = SubSubBrandedType<LeBytes, "U64LeBytes">;
+/**
+ * 128-bit (16 bytes) little-endian byte array.
+ *
+ * @remarks
+ * - Size: 16 bytes
+ * - Value range: [0, 2^128 - 1]
+ * - Common use: UUIDs, AES block size
+ *
+ * @example
+ * ```typescript
+ * const bytes = assertU128LeBytes(new Uint8Array(16));
+ * ```
+ *
+ * @see {@link assertU128LeBytes}
+ * @public
+ */
+type U128LeBytes = SubSubBrandedType<LeBytes, "U128LeBytes">;
+/**
+ * 256-bit (32 bytes) little-endian byte array.
+ *
+ * @remarks
+ * - Size: 32 bytes
+ * - Value range: [0, 2^256 - 1]
+ * - Common use: SHA-256 hashes, elliptic curve scalars, private keys
+ *
+ * @example
+ * ```typescript
+ * // A 256-bit cryptographic scalar
+ * const scalar = assertU256LeBytes(new Uint8Array(32));
+ * ```
+ *
+ * @see {@link assertU256LeBytes}
+ * @public
+ */
+type U256LeBytes = SubSubBrandedType<LeBytes, "U256LeBytes">;
+/**
+ * 512-bit (64 bytes) little-endian byte array.
+ *
+ * @remarks
+ * - Size: 64 bytes
+ * - Value range: [0, 2^512 - 1]
+ * - Common use: SHA-512 hashes, extended keys
+ *
+ * @example
+ * ```typescript
+ * const bytes = assertU512LeBytes(new Uint8Array(64));
+ * ```
+ *
+ * @see {@link assertU512LeBytes}
+ * @public
+ */
+type U512LeBytes = SubSubBrandedType<LeBytes, "U512LeBytes">;
+/**
+ * 1024-bit (128 bytes) little-endian byte array.
+ *
+ * @remarks
+ * - Size: 128 bytes
+ * - Value range: [0, 2^1024 - 1]
+ * - Common use: RSA keys, large cryptographic values
+ *
+ * @example
+ * ```typescript
+ * const bytes = assertU1024LeBytes(new Uint8Array(128));
+ * ```
+ *
+ * @see {@link assertU1024LeBytes}
+ * @public
+ */
+type U1024LeBytes = SubSubBrandedType<LeBytes, "U1024LeBytes">;
+/**
+ * 8-bit (1 byte) big-endian byte array.
+ *
+ * Represents a single byte, which is endianness-agnostic.
+ * Included for API consistency with larger sizes.
+ *
+ * @remarks
+ * - Size: 1 byte
+ * - Value range: [0, 255] (0x00 to 0xFF)
+ *
+ * @example
+ * ```typescript
+ * const byte = assertU8BeBytes(new Uint8Array([0xFF]));
+ * ```
+ *
+ * @see {@link assertU8BeBytes}
+ * @public
+ */
+type U8BeBytes = SubSubBrandedType<BeBytes, "U8BeBytes">;
+/**
+ * 16-bit (2 bytes) big-endian byte array.
+ *
+ * @remarks
+ * - Size: 2 bytes
+ * - Value range: [0, 65,535]
+ * - Common use: Network port numbers, protocol headers
+ *
+ * @example
+ * ```typescript
+ * // Value 0x1234 in big-endian (network byte order)
+ * const bytes = assertU16BeBytes(new Uint8Array([0x12, 0x34]));
+ * ```
+ *
+ * @see {@link assertU16BeBytes}
+ * @public
+ */
+type U16BeBytes = SubSubBrandedType<BeBytes, "U16BeBytes">;
+/**
+ * 32-bit (4 bytes) big-endian byte array.
+ *
+ * @remarks
+ * - Size: 4 bytes
+ * - Value range: [0, 4,294,967,295]
+ * - Common use: Network addresses, protocol fields
+ *
+ * @example
+ * ```typescript
+ * // Value 0x12345678 in big-endian
+ * const bytes = assertU32BeBytes(new Uint8Array([0x12, 0x34, 0x56, 0x78]));
+ * ```
+ *
+ * @see {@link assertU32BeBytes}
+ * @public
+ */
+type U32BeBytes = SubSubBrandedType<BeBytes, "U32BeBytes">;
+/**
+ * 64-bit (8 bytes) big-endian byte array.
+ *
+ * @remarks
+ * - Size: 8 bytes
+ * - Value range: [0, 2^64 - 1]
+ *
+ * @example
+ * ```typescript
+ * const bytes = assertU64BeBytes(new Uint8Array(8));
+ * ```
+ *
+ * @see {@link assertU64BeBytes}
+ * @public
+ */
+type U64BeBytes = SubSubBrandedType<BeBytes, "U64BeBytes">;
+/**
+ * 128-bit (16 bytes) big-endian byte array.
+ *
+ * @remarks
+ * - Size: 16 bytes
+ * - Value range: [0, 2^128 - 1]
+ * - Common use: UUIDs in standard format, IPv6 addresses
+ *
+ * @example
+ * ```typescript
+ * const bytes = assertU128BeBytes(new Uint8Array(16));
+ * ```
+ *
+ * @see {@link assertU128BeBytes}
+ * @public
+ */
+type U128BeBytes = SubSubBrandedType<BeBytes, "U128BeBytes">;
+/**
+ * 256-bit (32 bytes) big-endian byte array.
+ *
+ * @remarks
+ * - Size: 32 bytes
+ * - Value range: [0, 2^256 - 1]
+ * - Common use: Ethereum addresses (20 bytes, but often padded), field elements
+ *
+ * @example
+ * ```typescript
+ * const bytes = assertU256BeBytes(new Uint8Array(32));
+ * ```
+ *
+ * @see {@link assertU256BeBytes}
+ * @public
+ */
+type U256BeBytes = SubSubBrandedType<BeBytes, "U256BeBytes">;
+/**
+ * 512-bit (64 bytes) big-endian byte array.
+ *
+ * @remarks
+ * - Size: 64 bytes
+ * - Value range: [0, 2^512 - 1]
+ *
+ * @example
+ * ```typescript
+ * const bytes = assertU512BeBytes(new Uint8Array(64));
+ * ```
+ *
+ * @see {@link assertU512BeBytes}
+ * @public
+ */
+type U512BeBytes = SubSubBrandedType<BeBytes, "U512BeBytes">;
+/**
+ * 1024-bit (128 bytes) big-endian byte array.
+ *
+ * @remarks
+ * - Size: 128 bytes
+ * - Value range: [0, 2^1024 - 1]
+ *
+ * @example
+ * ```typescript
+ * const bytes = assertU1024BeBytes(new Uint8Array(128));
+ * ```
+ *
+ * @see {@link assertU1024BeBytes}
+ * @public
+ */
+type U1024BeBytes = SubSubBrandedType<BeBytes, "U1024BeBytes">;
+/**
+ * Base type for all unsigned integers.
+ *
+ * Unsigned integers represent non-negative whole numbers (0, 1, 2, ...).
+ * All specific unsigned integer types (`U8`, `U16`, etc.) are sub-brands of this type.
+ *
+ * @remarks
+ * - Uses JavaScript's `BigInt` for arbitrary precision arithmetic
+ * - No upper bound at the base type level (bounds are enforced by sub-types)
+ * - Guaranteed to be non-negative (>= 0)
+ *
+ * ## Type Hierarchy
+ * ```
+ * bigint
+ *   └── UnsignedInteger (branded, value >= 0)
+ *         ├── U8   (0 to 255)
+ *         ├── U16  (0 to 65,535)
+ *         ├── U32  (0 to 4,294,967,295)
+ *         └── ...
+ * ```
+ *
+ * @example
+ * ```typescript
+ * const value = assertUnsignedInteger(12345n);
+ * // value is typed as UnsignedInteger
+ *
+ * // Can be assigned to functions expecting UnsignedInteger
+ * function processUnsigned(n: UnsignedInteger): void { ... }
+ * processUnsigned(value); // OK
+ * ```
+ *
+ * @see {@link assertUnsignedInteger}
+ * @public
+ */
+type UnsignedInteger = BrandedType<bigint, "UnsignedInteger">;
+/**
+ * Base type for all signed integers.
+ *
+ * Signed integers represent whole numbers including negatives (..., -2, -1, 0, 1, 2, ...).
+ * All specific signed integer types (`I8`, `I16`, etc.) are sub-brands of this type.
+ *
+ * @remarks
+ * - Uses JavaScript's `BigInt` for arbitrary precision arithmetic
+ * - No bounds at the base type level (bounds are enforced by sub-types)
+ * - Two's complement representation is assumed for negative values
+ *
+ * ## Two's Complement
+ * Two's complement is the standard way computers represent signed integers:
+ * - Positive numbers are represented normally
+ * - Negative numbers: invert all bits and add 1
+ * - Example (8-bit): -1 = 0xFF, -128 = 0x80
+ *
+ * ## Type Hierarchy
+ * ```
+ * bigint
+ *   └── SignedInteger (branded)
+ *         ├── I8   (-128 to 127)
+ *         ├── I16  (-32,768 to 32,767)
+ *         ├── I32  (-2,147,483,648 to 2,147,483,647)
+ *         └── ...
+ * ```
+ *
+ * @example
+ * ```typescript
+ * const value = assertSignedInteger(-12345n);
+ * // value is typed as SignedInteger
+ * ```
+ *
+ * @see {@link assertSignedInteger}
+ * @public
+ */
+type SignedInteger = BrandedType<bigint, "SignedInteger">;
+/**
+ * 8-bit unsigned integer.
+ *
+ * @remarks
+ * - Bit width: 8 bits (1 byte)
+ * - Range: [0, 255] or [0x00, 0xFF]
+ * - Max value: 2^8 - 1 = 255
+ *
+ * ## Common Uses
+ * - Single byte values
+ * - Color channel values (RGB)
+ * - Character codes (ASCII)
+ * - Small counters and flags
+ *
+ * @example
+ * ```typescript
+ * const red: U8 = assertU8(255n);   // Maximum red
+ * const green: U8 = assertU8(128n); // Medium green
+ * const blue: U8 = assertU8(0n);    // No blue
+ * ```
+ *
+ * @see {@link assertU8}
+ * @see {@link U8_MAX}
+ * @public
+ */
+type U8 = SubBrandedType<UnsignedInteger, "U8">;
+/**
+ * 16-bit unsigned integer.
+ *
+ * @remarks
+ * - Bit width: 16 bits (2 bytes)
+ * - Range: [0, 65,535] or [0x0000, 0xFFFF]
+ * - Max value: 2^16 - 1 = 65,535
+ *
+ * ## Common Uses
+ * - Port numbers (0-65535)
+ * - Unicode code points (BMP)
+ * - Audio samples (16-bit PCM)
+ * - Small array indices
+ *
+ * @example
+ * ```typescript
+ * const port: U16 = assertU16(443n);    // HTTPS port
+ * const sample: U16 = assertU16(32768n); // Audio sample
+ * ```
+ *
+ * @see {@link assertU16}
+ * @see {@link U16_MAX}
+ * @public
+ */
+type U16 = SubBrandedType<UnsignedInteger, "U16">;
+/**
+ * 32-bit unsigned integer.
+ *
+ * @remarks
+ * - Bit width: 32 bits (4 bytes)
+ * - Range: [0, 4,294,967,295] or [0x00000000, 0xFFFFFFFF]
+ * - Max value: 2^32 - 1 = 4,294,967,295 (~4.3 billion)
+ *
+ * ## Common Uses
+ * - IPv4 addresses
+ * - Unix timestamps (until 2038)
+ * - Array indices
+ * - Color values (RGBA packed)
+ * - CRC32 checksums
+ *
+ * @example
+ * ```typescript
+ * const timestamp: U32 = assertU32(1704067200n); // 2024-01-01 00:00:00 UTC
+ * const ipAddress: U32 = assertU32(0x7F000001n); // 127.0.0.1
+ * ```
+ *
+ * @see {@link assertU32}
+ * @see {@link U32_MAX}
+ * @public
+ */
+type U32 = SubBrandedType<UnsignedInteger, "U32">;
+/**
+ * 64-bit unsigned integer.
+ *
+ * @remarks
+ * - Bit width: 64 bits (8 bytes)
+ * - Range: [0, 18,446,744,073,709,551,615]
+ * - Max value: 2^64 - 1 (~18.4 quintillion)
+ *
+ * ## Common Uses
+ * - High-precision timestamps (nanoseconds)
+ * - File sizes
+ * - Database primary keys
+ * - Memory addresses
+ * - Large counters
+ *
+ * @example
+ * ```typescript
+ * const nanoTimestamp: U64 = assertU64(1704067200000000000n);
+ * const fileSize: U64 = assertU64(1099511627776n); // 1 TiB
+ * ```
+ *
+ * @see {@link assertU64}
+ * @see {@link U64_MAX}
+ * @public
+ */
+type U64 = SubBrandedType<UnsignedInteger, "U64">;
+/**
+ * 128-bit unsigned integer.
+ *
+ * @remarks
+ * - Bit width: 128 bits (16 bytes)
+ * - Range: [0, 2^128 - 1]
+ * - Max value: ~3.4 × 10^38
+ *
+ * ## Common Uses
+ * - UUIDs (128-bit identifiers)
+ * - IPv6 addresses
+ * - Cryptographic nonces
+ * - Very large counters
+ *
+ * @example
+ * ```typescript
+ * const uuid: U128 = assertU128(0x550e8400e29b41d4a716446655440000n);
+ * ```
+ *
+ * @see {@link assertU128}
+ * @see {@link U128_MAX}
+ * @public
+ */
+type U128 = SubBrandedType<UnsignedInteger, "U128">;
+/**
+ * 256-bit unsigned integer.
+ *
+ * @remarks
+ * - Bit width: 256 bits (32 bytes)
+ * - Range: [0, 2^256 - 1]
+ * - Max value: ~1.16 × 10^77
+ *
+ * ## Common Uses
+ * - Elliptic curve field elements (BN254, secp256k1)
+ * - Cryptographic scalars and private keys
+ * - SHA-256 hash outputs
+ * - Blockchain addresses and balances
+ *
+ * ## Cryptographic Significance
+ * 256 bits provides approximately 128 bits of security for symmetric
+ * operations and is the standard size for modern elliptic curves.
+ *
+ * @example
+ * ```typescript
+ * // A private key (256-bit scalar)
+ * const privateKey: U256 = assertU256(
+ *     0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdefn
+ * );
+ *
+ * // A SHA-256 hash interpreted as a number
+ * const hashValue: U256 = assertU256(hashAsNumber);
+ * ```
+ *
+ * @see {@link assertU256}
+ * @see {@link U256_MAX}
+ * @public
+ */
+type U256 = SubBrandedType<UnsignedInteger, "U256">;
+/**
+ * 512-bit unsigned integer.
+ *
+ * @remarks
+ * - Bit width: 512 bits (64 bytes)
+ * - Range: [0, 2^512 - 1]
+ *
+ * ## Common Uses
+ * - SHA-512 hash outputs
+ * - Extended cryptographic keys
+ * - Large field elements
+ *
+ * @example
+ * ```typescript
+ * const hash: U512 = assertU512(sha512HashValue);
+ * ```
+ *
+ * @see {@link assertU512}
+ * @see {@link U512_MAX}
+ * @public
+ */
+type U512 = SubBrandedType<UnsignedInteger, "U512">;
+/**
+ * 1024-bit unsigned integer.
+ *
+ * @remarks
+ * - Bit width: 1024 bits (128 bytes)
+ * - Range: [0, 2^1024 - 1]
+ *
+ * ## Common Uses
+ * - RSA key components
+ * - Very large cryptographic values
+ * - Pairing-based cryptography
+ *
+ * @example
+ * ```typescript
+ * const rsaModulus: U1024 = assertU1024(modulusValue);
+ * ```
+ *
+ * @see {@link assertU1024}
+ * @see {@link U1024_MAX}
+ * @public
+ */
+type U1024 = SubBrandedType<UnsignedInteger, "U1024">;
+/**
+ * 8-bit signed integer.
+ *
+ * @remarks
+ * - Bit width: 8 bits (1 byte)
+ * - Range: [-128, 127] or [-2^7, 2^7 - 1]
+ * - Uses two's complement representation
+ *
+ * ## Two's Complement Values
+ * - 0x00 = 0
+ * - 0x7F = 127 (maximum positive)
+ * - 0x80 = -128 (minimum negative)
+ * - 0xFF = -1
+ *
+ * @example
+ * ```typescript
+ * const positive: I8 = assertI8(127n);
+ * const negative: I8 = assertI8(-128n);
+ * const zero: I8 = assertI8(0n);
+ * ```
+ *
+ * @see {@link assertI8}
+ * @see {@link I8_MIN}
+ * @see {@link I8_MAX}
+ * @public
+ */
+type I8 = SubBrandedType<SignedInteger, "I8">;
+/**
+ * 16-bit signed integer.
+ *
+ * @remarks
+ * - Bit width: 16 bits (2 bytes)
+ * - Range: [-32,768, 32,767] or [-2^15, 2^15 - 1]
+ * - Uses two's complement representation
+ *
+ * ## Common Uses
+ * - Audio samples (16-bit signed PCM)
+ * - Small offsets and deltas
+ *
+ * @example
+ * ```typescript
+ * const audioSample: I16 = assertI16(-16384n);
+ * ```
+ *
+ * @see {@link assertI16}
+ * @see {@link I16_MIN}
+ * @see {@link I16_MAX}
+ * @public
+ */
+type I16 = SubBrandedType<SignedInteger, "I16">;
+/**
+ * 32-bit signed integer.
+ *
+ * @remarks
+ * - Bit width: 32 bits (4 bytes)
+ * - Range: [-2,147,483,648, 2,147,483,647] or [-2^31, 2^31 - 1]
+ * - Uses two's complement representation
+ *
+ * ## Common Uses
+ * - General-purpose integers
+ * - Array indices (with negative sentinel values)
+ * - Differences and offsets
+ *
+ * @example
+ * ```typescript
+ * const offset: I32 = assertI32(-1000n);
+ * const index: I32 = assertI32(42n);
+ * ```
+ *
+ * @see {@link assertI32}
+ * @see {@link I32_MIN}
+ * @see {@link I32_MAX}
+ * @public
+ */
+type I32 = SubBrandedType<SignedInteger, "I32">;
+/**
+ * 64-bit signed integer.
+ *
+ * @remarks
+ * - Bit width: 64 bits (8 bytes)
+ * - Range: [-9,223,372,036,854,775,808, 9,223,372,036,854,775,807]
+ * - Range: [-2^63, 2^63 - 1]
+ * - Uses two's complement representation
+ *
+ * ## Common Uses
+ * - Large offsets and differences
+ * - Signed timestamps
+ * - Financial calculations (with appropriate scaling)
+ *
+ * @example
+ * ```typescript
+ * const difference: I64 = assertI64(-1000000000000n);
+ * ```
+ *
+ * @see {@link assertI64}
+ * @see {@link I64_MIN}
+ * @see {@link I64_MAX}
+ * @public
+ */
+type I64 = SubBrandedType<SignedInteger, "I64">;
+/**
+ * 128-bit signed integer.
+ *
+ * @remarks
+ * - Bit width: 128 bits (16 bytes)
+ * - Range: [-2^127, 2^127 - 1]
+ * - Uses two's complement representation
+ *
+ * @example
+ * ```typescript
+ * const value: I128 = assertI128(-170141183460469231731687303715884105728n);
+ * ```
+ *
+ * @see {@link assertI128}
+ * @see {@link I128_MIN}
+ * @see {@link I128_MAX}
+ * @public
+ */
+type I128 = SubBrandedType<SignedInteger, "I128">;
+/**
+ * 256-bit signed integer.
+ *
+ * @remarks
+ * - Bit width: 256 bits (32 bytes)
+ * - Range: [-2^255, 2^255 - 1]
+ * - Uses two's complement representation
+ *
+ * ## Common Uses
+ * - Signed cryptographic values
+ * - Large signed arithmetic
+ *
+ * @example
+ * ```typescript
+ * const signedScalar: I256 = assertI256(-12345678901234567890n);
+ * ```
+ *
+ * @see {@link assertI256}
+ * @see {@link I256_MIN}
+ * @see {@link I256_MAX}
+ * @public
+ */
+type I256 = SubBrandedType<SignedInteger, "I256">;
+/**
+ * 512-bit signed integer.
+ *
+ * @remarks
+ * - Bit width: 512 bits (64 bytes)
+ * - Range: [-2^511, 2^511 - 1]
+ * - Uses two's complement representation
+ *
+ * @example
+ * ```typescript
+ * const value: I512 = assertI512(-1n);
+ * ```
+ *
+ * @see {@link assertI512}
+ * @see {@link I512_MIN}
+ * @see {@link I512_MAX}
+ * @public
+ */
+type I512 = SubBrandedType<SignedInteger, "I512">;
+/**
+ * 1024-bit signed integer.
+ *
+ * @remarks
+ * - Bit width: 1024 bits (128 bytes)
+ * - Range: [-2^1023, 2^1023 - 1]
+ * - Uses two's complement representation
+ *
+ * @example
+ * ```typescript
+ * const value: I1024 = assertI1024(0n);
+ * ```
+ *
+ * @see {@link assertI1024}
+ * @see {@link I1024_MIN}
+ * @see {@link I1024_MAX}
+ * @public
+ */
+type I1024 = SubBrandedType<SignedInteger, "I1024">;
+/**
+ * Maximum value for an 8-bit unsigned integer.
+ *
+ * @remarks
+ * - Value: 255 (0xFF)
+ * - Formula: 2^8 - 1
+ *
+ * @example
+ * ```typescript
+ * if (value > U8_MAX) {
+ *     throw new Error("Value exceeds U8 range");
+ * }
+ * ```
+ *
+ * @see {@link U8}
+ * @public
+ */
+declare const U8_MAX = 255n;
+/**
+ * Maximum value for a 16-bit unsigned integer.
+ *
+ * @remarks
+ * - Value: 65,535 (0xFFFF)
+ * - Formula: 2^16 - 1
+ *
+ * @example
+ * ```typescript
+ * if (portNumber > U16_MAX) {
+ *     throw new Error("Port number exceeds U16 range");
+ * }
+ * ```
+ *
+ * @see {@link U16}
+ * @public
+ */
+declare const U16_MAX = 65535n;
+/**
+ * Maximum value for a 32-bit unsigned integer.
+ *
+ * @remarks
+ * - Value: 4,294,967,295 (0xFFFFFFFF)
+ * - Formula: 2^32 - 1
+ *
+ * @example
+ * ```typescript
+ * if (timestamp > U32_MAX) {
+ *     throw new Error("Timestamp exceeds U32 range (Year 2038 problem)");
+ * }
+ * ```
+ *
+ * @see {@link U32}
+ * @public
+ */
+declare const U32_MAX = 4294967295n;
+/**
+ * Maximum value for a 64-bit unsigned integer.
+ *
+ * @remarks
+ * - Value: 18,446,744,073,709,551,615 (0xFFFFFFFFFFFFFFFF)
+ * - Formula: 2^64 - 1
+ *
+ * @example
+ * ```typescript
+ * if (counter > U64_MAX) {
+ *     throw new Error("Counter exceeds U64 range");
+ * }
+ * ```
+ *
+ * @see {@link U64}
+ * @public
+ */
+declare const U64_MAX = 18446744073709551615n;
+/**
+ * Maximum value for a 128-bit unsigned integer.
+ *
+ * @remarks
+ * - Value: 2^128 - 1
+ * - Approximately: 3.4 × 10^38
+ *
+ * @example
+ * ```typescript
+ * if (value > U128_MAX) {
+ *     throw new Error("Value exceeds U128 range");
+ * }
+ * ```
+ *
+ * @see {@link U128}
+ * @public
+ */
+declare const U128_MAX: bigint;
+/**
+ * Maximum value for a 256-bit unsigned integer.
+ *
+ * @remarks
+ * - Value: 2^256 - 1
+ * - Approximately: 1.16 × 10^77
+ * - This exceeds the estimated number of atoms in the observable universe
+ *
+ * @example
+ * ```typescript
+ * // Validate a field element is within BN254 range (BN254 prime < U256_MAX)
+ * if (fieldElement > U256_MAX) {
+ *     throw new Error("Field element exceeds U256 range");
+ * }
+ * ```
+ *
+ * @see {@link U256}
+ * @public
+ */
+declare const U256_MAX: bigint;
+/**
+ * Maximum value for a 512-bit unsigned integer.
+ *
+ * @remarks
+ * - Value: 2^512 - 1
+ *
+ * @example
+ * ```typescript
+ * if (value > U512_MAX) {
+ *     throw new Error("Value exceeds U512 range");
+ * }
+ * ```
+ *
+ * @see {@link U512}
+ * @public
+ */
+declare const U512_MAX: bigint;
+/**
+ * Maximum value for a 1024-bit unsigned integer.
+ *
+ * @remarks
+ * - Value: 2^1024 - 1
+ *
+ * @example
+ * ```typescript
+ * if (rsaModulus > U1024_MAX) {
+ *     throw new Error("RSA modulus exceeds U1024 range");
+ * }
+ * ```
+ *
+ * @see {@link U1024}
+ * @public
+ */
+declare const U1024_MAX: bigint;
+/**
+ * Minimum value for an 8-bit signed integer.
+ *
+ * @remarks
+ * - Value: -128 (0x80 in two's complement)
+ * - Formula: -2^7
+ *
+ * @see {@link I8}
+ * @public
+ */
+declare const I8_MIN: bigint;
+/**
+ * Maximum value for an 8-bit signed integer.
+ *
+ * @remarks
+ * - Value: 127 (0x7F)
+ * - Formula: 2^7 - 1
+ *
+ * @see {@link I8}
+ * @public
+ */
+declare const I8_MAX: bigint;
+/**
+ * Minimum value for a 16-bit signed integer.
+ *
+ * @remarks
+ * - Value: -32,768
+ * - Formula: -2^15
+ *
+ * @see {@link I16}
+ * @public
+ */
+declare const I16_MIN: bigint;
+/**
+ * Maximum value for a 16-bit signed integer.
+ *
+ * @remarks
+ * - Value: 32,767
+ * - Formula: 2^15 - 1
+ *
+ * @see {@link I16}
+ * @public
+ */
+declare const I16_MAX: bigint;
+/**
+ * Minimum value for a 32-bit signed integer.
+ *
+ * @remarks
+ * - Value: -2,147,483,648
+ * - Formula: -2^31
+ *
+ * @see {@link I32}
+ * @public
+ */
+declare const I32_MIN: bigint;
+/**
+ * Maximum value for a 32-bit signed integer.
+ *
+ * @remarks
+ * - Value: 2,147,483,647
+ * - Formula: 2^31 - 1
+ *
+ * @see {@link I32}
+ * @public
+ */
+declare const I32_MAX: bigint;
+/**
+ * Minimum value for a 64-bit signed integer.
+ *
+ * @remarks
+ * - Value: -9,223,372,036,854,775,808
+ * - Formula: -2^63
+ *
+ * @see {@link I64}
+ * @public
+ */
+declare const I64_MIN: bigint;
+/**
+ * Maximum value for a 64-bit signed integer.
+ *
+ * @remarks
+ * - Value: 9,223,372,036,854,775,807
+ * - Formula: 2^63 - 1
+ *
+ * @see {@link I64}
+ * @public
+ */
+declare const I64_MAX: bigint;
+/**
+ * Minimum value for a 128-bit signed integer.
+ *
+ * @remarks
+ * - Formula: -2^127
+ *
+ * @see {@link I128}
+ * @public
+ */
+declare const I128_MIN: bigint;
+/**
+ * Maximum value for a 128-bit signed integer.
+ *
+ * @remarks
+ * - Formula: 2^127 - 1
+ *
+ * @see {@link I128}
+ * @public
+ */
+declare const I128_MAX: bigint;
+/**
+ * Minimum value for a 256-bit signed integer.
+ *
+ * @remarks
+ * - Formula: -2^255
+ *
+ * @see {@link I256}
+ * @public
+ */
+declare const I256_MIN: bigint;
+/**
+ * Maximum value for a 256-bit signed integer.
+ *
+ * @remarks
+ * - Formula: 2^255 - 1
+ *
+ * @see {@link I256}
+ * @public
+ */
+declare const I256_MAX: bigint;
+/**
+ * Minimum value for a 512-bit signed integer.
+ *
+ * @remarks
+ * - Formula: -2^511
+ *
+ * @see {@link I512}
+ * @public
+ */
+declare const I512_MIN: bigint;
+/**
+ * Maximum value for a 512-bit signed integer.
+ *
+ * @remarks
+ * - Formula: 2^511 - 1
+ *
+ * @see {@link I512}
+ * @public
+ */
+declare const I512_MAX: bigint;
+/**
+ * Minimum value for a 1024-bit signed integer.
+ *
+ * @remarks
+ * - Formula: -2^1023
+ *
+ * @see {@link I1024}
+ * @public
+ */
+declare const I1024_MIN: bigint;
+/**
+ * Maximum value for a 1024-bit signed integer.
+ *
+ * @remarks
+ * - Formula: 2^1023 - 1
+ *
+ * @see {@link I1024}
+ * @public
+ */
+declare const I1024_MAX: bigint;
+/**
+ * Expected byte length for 8-bit values.
+ *
+ * @remarks Value: 1 byte
+ *
+ * @example
+ * ```typescript
+ * const bytes = new Uint8Array(U8_BYTE_LENGTH); // 1 byte
+ * ```
+ *
+ * @see {@link U8LeBytes}
+ * @see {@link U8BeBytes}
+ * @public
+ */
+declare const U8_BYTE_LENGTH = 1;
+/**
+ * Expected byte length for 16-bit values.
+ *
+ * @remarks Value: 2 bytes
+ *
+ * @example
+ * ```typescript
+ * const bytes = new Uint8Array(U16_BYTE_LENGTH); // 2 bytes
+ * ```
+ *
+ * @see {@link U16LeBytes}
+ * @see {@link U16BeBytes}
+ * @public
+ */
+declare const U16_BYTE_LENGTH = 2;
+/**
+ * Expected byte length for 32-bit values.
+ *
+ * @remarks Value: 4 bytes
+ *
+ * @example
+ * ```typescript
+ * const bytes = new Uint8Array(U32_BYTE_LENGTH); // 4 bytes
+ * ```
+ *
+ * @see {@link U32LeBytes}
+ * @see {@link U32BeBytes}
+ * @public
+ */
+declare const U32_BYTE_LENGTH = 4;
+/**
+ * Expected byte length for 64-bit values.
+ *
+ * @remarks Value: 8 bytes
+ *
+ * @example
+ * ```typescript
+ * const bytes = new Uint8Array(U64_BYTE_LENGTH); // 8 bytes
+ * ```
+ *
+ * @see {@link U64LeBytes}
+ * @see {@link U64BeBytes}
+ * @public
+ */
+declare const U64_BYTE_LENGTH = 8;
+/**
+ * Expected byte length for 128-bit values.
+ *
+ * @remarks Value: 16 bytes
+ *
+ * @example
+ * ```typescript
+ * const bytes = new Uint8Array(U128_BYTE_LENGTH); // 16 bytes
+ * ```
+ *
+ * @see {@link U128LeBytes}
+ * @see {@link U128BeBytes}
+ * @public
+ */
+declare const U128_BYTE_LENGTH = 16;
+/**
+ * Expected byte length for 256-bit values.
+ *
+ * @remarks Value: 32 bytes
+ *
+ * @example
+ * ```typescript
+ * // Allocate a buffer for a 256-bit cryptographic scalar
+ * const scalarBytes = new Uint8Array(U256_BYTE_LENGTH); // 32 bytes
+ * ```
+ *
+ * @see {@link U256LeBytes}
+ * @see {@link U256BeBytes}
+ * @public
+ */
+declare const U256_BYTE_LENGTH = 32;
+/**
+ * Expected byte length for 512-bit values.
+ *
+ * @remarks Value: 64 bytes
+ *
+ * @example
+ * ```typescript
+ * const bytes = new Uint8Array(U512_BYTE_LENGTH); // 64 bytes
+ * ```
+ *
+ * @see {@link U512LeBytes}
+ * @see {@link U512BeBytes}
+ * @public
+ */
+declare const U512_BYTE_LENGTH = 64;
+/**
+ * Expected byte length for 1024-bit values.
+ *
+ * @remarks Value: 128 bytes
+ *
+ * @example
+ * ```typescript
+ * const bytes = new Uint8Array(U1024_BYTE_LENGTH); // 128 bytes
+ * ```
+ *
+ * @see {@link U1024LeBytes}
+ * @see {@link U1024BeBytes}
+ * @public
+ */
+declare const U1024_BYTE_LENGTH = 128;
+/**
+ * Error thrown when a value fails a mathematical type assertion.
+ *
+ * This error provides detailed information about why an assertion failed,
+ * including the actual value, the expected type, and the constraint that
+ * was violated.
+ *
+ * @remarks
+ * All assertion functions in this module throw this error type on failure.
+ * You can catch this specific error type to handle assertion failures
+ * differently from other errors.
+ *
+ * ## Error Properties
+ * - `value`: The actual value that failed assertion
+ * - `expectedType`: The type that was expected (e.g., "U8", "U256LeBytes")
+ * - `constraint`: Optional description of the constraint that was violated
+ *
+ * @example
+ * ```typescript
+ * import { assertU8, MathematicsAssertionError } from "./mathematics";
+ *
+ * try {
+ *     const value = assertU8(256n); // Will throw
+ * } catch (error) {
+ *     if (error instanceof MathematicsAssertionError) {
+ *         console.error(`Assertion failed for ${error.expectedType}`);
+ *         console.error(`Value: ${error.value}`);
+ *         console.error(`Constraint: ${error.constraint}`);
+ *         // Output:
+ *         // Assertion failed for U8
+ *         // Value: 256
+ *         // Constraint: 0 <= value <= 255
+ *     }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Custom error handling
+ * function safeParseU8(value: bigint): U8 | null {
+ *     try {
+ *         return assertU8(value);
+ *     } catch (error) {
+ *         if (error instanceof MathematicsAssertionError) {
+ *             console.warn(`Invalid U8 value: ${value}`);
+ *             return null;
+ *         }
+ *         throw error; // Re-throw unexpected errors
+ *     }
+ * }
+ * ```
+ *
+ * @sealed
+ * @public
+ */
+declare class MathematicsAssertionError extends Error {
+    /**
+     * The actual value that failed the assertion.
+     *
+     * @remarks
+     * This can be any type depending on what was being asserted.
+     * For integer assertions, this will be a `bigint`.
+     * For byte array assertions, this will be a `Uint8Array`.
+     *
+     * @readonly
+     */
+    readonly value: unknown;
+    /**
+     * The type that was expected.
+     *
+     * @remarks
+     * This is the branded type name (e.g., "U8", "U256", "U32LeBytes").
+     *
+     * @readonly
+     */
+    readonly expectedType: string;
+    /**
+     * Description of the constraint that was violated.
+     *
+     * @remarks
+     * This is `undefined` if only a type check failed (e.g., expected bigint, got string).
+     * It contains a human-readable constraint description when a value is out of range.
+     *
+     * @example
+     * - "0 <= value <= 255" for U8 range violations
+     * - "length === 32" for U256LeBytes length violations
+     * - "value >= 0" for negative unsigned integer attempts
+     *
+     * @readonly
+     */
+    readonly constraint: string | undefined;
+    /**
+     * Creates a new MathematicsAssertionError.
+     *
+     * @param message - Human-readable error message
+     * @param options - Error details
+     * @param options.value - The value that failed assertion
+     * @param options.expectedType - The expected type name
+     * @param options.constraint - Optional constraint description
+     */
+    constructor(message: string, options: {
+        value: unknown;
+        expectedType: string;
+        constraint?: string;
+    });
+}
+/**
+ * Asserts that a value is a valid Uint8Array and narrows it to `Bytes`.
+ *
+ * This is the base assertion for all byte array types. It validates that
+ * the input is a `Uint8Array` instance.
+ *
+ * @param value - The Uint8Array to assert
+ * @throws {MathematicsAssertionError} If the value is not a Uint8Array
+ *
+ * @example
+ * ```typescript
+ * const rawBytes = new Uint8Array([0x01, 0x02, 0x03]);
+ * assertBytes(rawBytes);
+ * // rawBytes is now typed as Bytes
+ * ```
+ *
+ * @returns `void` — type narrowing is applied to the argument in-place.
+ * @see {@link Bytes}
+ * @public
+ */
+declare function assertBytes(value: Uint8Array): asserts value is Bytes;
+/**
+ * Asserts that a value is a valid Uint8Array and narrows it to `LeBytes`.
+ *
+ * This function validates that the input is a `Uint8Array` instance and
+ * uses TypeScript's type narrowing to treat it as a little-endian byte array.
+ * No length validation is performed.
+ *
+ * @param value - The Uint8Array to assert
+ * @throws {MathematicsAssertionError} If the value is not a Uint8Array
+ *
+ * @remarks
+ * This is the base assertion for little-endian byte arrays.
+ * For sized byte arrays, use the specific assertions like `assertU32LeBytes`.
+ *
+ * @example
+ * ```typescript
+ * // Brand a byte array as little-endian
+ * const rawBytes = new Uint8Array([0x78, 0x56, 0x34, 0x12]);
+ * assertLeBytes(rawBytes);
+ * // rawBytes is now typed as LeBytes
+ *
+ * // The branded type prevents mixing with big-endian
+ * function processLittleEndian(bytes: LeBytes): void { ... }
+ * processLittleEndian(rawBytes); // OK after assertion
+ * ```
+ *
+ * @returns `void` — type narrowing is applied to the argument in-place.
+ * @see {@link LeBytes}
+ * @public
+ */
+declare function assertLeBytes(value: Uint8Array): asserts value is LeBytes;
+/**
+ * Asserts that a value is a valid Uint8Array and narrows it to `BeBytes`.
+ *
+ * This function validates that the input is a `Uint8Array` instance and
+ * uses TypeScript's type narrowing to treat it as a big-endian byte array.
+ * No length validation is performed.
+ *
+ * @param value - The Uint8Array to assert
+ * @throws {MathematicsAssertionError} If the value is not a Uint8Array
+ *
+ * @remarks
+ * This is the base assertion for big-endian byte arrays.
+ * For sized byte arrays, use the specific assertions like `assertU32BeBytes`.
+ *
+ * @example
+ * ```typescript
+ * // Brand a byte array as big-endian (network byte order)
+ * const rawBytes = new Uint8Array([0x12, 0x34, 0x56, 0x78]);
+ * assertBeBytes(rawBytes);
+ * // rawBytes is now typed as BeBytes
+ *
+ * // Use for network protocol data
+ * function sendNetworkData(bytes: BeBytes): void { ... }
+ * sendNetworkData(rawBytes); // OK after assertion
+ * ```
+ *
+ * @returns `void` — type narrowing is applied to the argument in-place.
+ * @see {@link BeBytes}
+ * @public
+ */
+declare function assertBeBytes(value: Uint8Array): asserts value is BeBytes;
+/**
+ * Asserts that a value is a 1-byte little-endian byte array.
+ *
+ * @param value - The Uint8Array to assert (must be exactly 1 byte)
+ * @throws {MathematicsAssertionError} If not a Uint8Array or wrong length
+ *
+ * @example
+ * ```typescript
+ * const byte = new Uint8Array([0xFF]);
+ * assertU8LeBytes(byte);
+ * // byte is now typed as U8LeBytes
+ * ```
+ *
+ * @returns `void` — type narrowing is applied to the argument in-place.
+ * @see {@link U8LeBytes}
+ * @public
+ */
+declare function assertU8LeBytes(value: Uint8Array): asserts value is U8LeBytes;
+/**
+ * Asserts that a value is a 2-byte little-endian byte array.
+ *
+ * @param value - The Uint8Array to assert (must be exactly 2 bytes)
+ * @throws {MathematicsAssertionError} If not a Uint8Array or wrong length
+ *
+ * @example
+ * ```typescript
+ * // 0x1234 in little-endian
+ * const bytes = new Uint8Array([0x34, 0x12]);
+ * assertU16LeBytes(bytes);
+ * // bytes is now typed as U16LeBytes
+ * ```
+ *
+ * @returns `void` — type narrowing is applied to the argument in-place.
+ * @see {@link U16LeBytes}
+ * @public
+ */
+declare function assertU16LeBytes(value: Uint8Array): asserts value is U16LeBytes;
+/**
+ * Asserts that a value is a 4-byte little-endian byte array.
+ *
+ * @param value - The Uint8Array to assert (must be exactly 4 bytes)
+ * @throws {MathematicsAssertionError} If not a Uint8Array or wrong length
+ *
+ * @example
+ * ```typescript
+ * // 0x12345678 in little-endian
+ * const bytes = new Uint8Array([0x78, 0x56, 0x34, 0x12]);
+ * assertU32LeBytes(bytes);
+ * // bytes is now typed as U32LeBytes
+ * ```
+ *
+ * @returns `void` — type narrowing is applied to the argument in-place.
+ * @see {@link U32LeBytes}
+ * @public
+ */
+declare function assertU32LeBytes(value: Uint8Array): asserts value is U32LeBytes;
+/**
+ * Asserts that a value is an 8-byte little-endian byte array.
+ *
+ * @param value - The Uint8Array to assert (must be exactly 8 bytes)
+ * @throws {MathematicsAssertionError} If not a Uint8Array or wrong length
+ *
+ * @example
+ * ```typescript
+ * const bytes = new Uint8Array(8);
+ * assertU64LeBytes(bytes);
+ * // bytes is now typed as U64LeBytes
+ * ```
+ *
+ * @returns `void` — type narrowing is applied to the argument in-place.
+ * @see {@link U64LeBytes}
+ * @public
+ */
+declare function assertU64LeBytes(value: Uint8Array): asserts value is U64LeBytes;
+/**
+ * Asserts that a value is a 16-byte little-endian byte array.
+ *
+ * @param value - The Uint8Array to assert (must be exactly 16 bytes)
+ * @throws {MathematicsAssertionError} If not a Uint8Array or wrong length
+ *
+ * @example
+ * ```typescript
+ * const bytes = new Uint8Array(16);
+ * assertU128LeBytes(bytes);
+ * // bytes is now typed as U128LeBytes
+ * ```
+ *
+ * @returns `void` — type narrowing is applied to the argument in-place.
+ * @see {@link U128LeBytes}
+ * @public
+ */
+declare function assertU128LeBytes(value: Uint8Array): asserts value is U128LeBytes;
+/**
+ * Asserts that a value is a 32-byte little-endian byte array.
+ *
+ * @param value - The Uint8Array to assert (must be exactly 32 bytes)
+ * @throws {MathematicsAssertionError} If not a Uint8Array or wrong length
+ *
+ * @remarks
+ * 32-byte arrays are commonly used for:
+ * - SHA-256 hash outputs
+ * - Elliptic curve scalars
+ * - Private keys
+ *
+ * @example
+ * ```typescript
+ * // Create a 256-bit scalar representation
+ * const scalar = new Uint8Array(32);
+ * assertU256LeBytes(scalar);
+ * // scalar is now typed as U256LeBytes
+ * ```
+ *
+ * @returns `void` — type narrowing is applied to the argument in-place.
+ * @see {@link U256LeBytes}
+ * @public
+ */
+declare function assertU256LeBytes(value: Uint8Array): asserts value is U256LeBytes;
+/**
+ * Asserts that a value is a 64-byte little-endian byte array.
+ *
+ * @param value - The Uint8Array to assert (must be exactly 64 bytes)
+ * @throws {MathematicsAssertionError} If not a Uint8Array or wrong length
+ *
+ * @example
+ * ```typescript
+ * const bytes = new Uint8Array(64);
+ * assertU512LeBytes(bytes);
+ * // bytes is now typed as U512LeBytes
+ * ```
+ *
+ * @returns `void` — type narrowing is applied to the argument in-place.
+ * @see {@link U512LeBytes}
+ * @public
+ */
+declare function assertU512LeBytes(value: Uint8Array): asserts value is U512LeBytes;
+/**
+ * Asserts that a value is a 128-byte little-endian byte array.
+ *
+ * @param value - The Uint8Array to assert (must be exactly 128 bytes)
+ * @throws {MathematicsAssertionError} If not a Uint8Array or wrong length
+ *
+ * @example
+ * ```typescript
+ * const bytes = new Uint8Array(128);
+ * assertU1024LeBytes(bytes);
+ * // bytes is now typed as U1024LeBytes
+ * ```
+ *
+ * @returns `void` — type narrowing is applied to the argument in-place.
+ * @see {@link U1024LeBytes}
+ * @public
+ */
+declare function assertU1024LeBytes(value: Uint8Array): asserts value is U1024LeBytes;
+/**
+ * Asserts that a value is a 1-byte big-endian byte array.
+ *
+ * @param value - The Uint8Array to assert (must be exactly 1 byte)
+ * @throws {MathematicsAssertionError} If not a Uint8Array or wrong length
+ *
+ * @example
+ * ```typescript
+ * const byte = new Uint8Array([0xFF]);
+ * assertU8BeBytes(byte);
+ * // byte is now typed as U8BeBytes
+ * ```
+ *
+ * @returns `void` — type narrowing is applied to the argument in-place.
+ * @see {@link U8BeBytes}
+ * @public
+ */
+declare function assertU8BeBytes(value: Uint8Array): asserts value is U8BeBytes;
+/**
+ * Asserts that a value is a 2-byte big-endian byte array.
+ *
+ * @param value - The Uint8Array to assert (must be exactly 2 bytes)
+ * @throws {MathematicsAssertionError} If not a Uint8Array or wrong length
+ *
+ * @example
+ * ```typescript
+ * // Network port 443 in big-endian
+ * const portBytes = new Uint8Array([0x01, 0xBB]);
+ * assertU16BeBytes(portBytes);
+ * // portBytes is now typed as U16BeBytes
+ * ```
+ *
+ * @returns `void` — type narrowing is applied to the argument in-place.
+ * @see {@link U16BeBytes}
+ * @public
+ */
+declare function assertU16BeBytes(value: Uint8Array): asserts value is U16BeBytes;
+/**
+ * Asserts that a value is a 4-byte big-endian byte array.
+ *
+ * @param value - The Uint8Array to assert (must be exactly 4 bytes)
+ * @throws {MathematicsAssertionError} If not a Uint8Array or wrong length
+ *
+ * @example
+ * ```typescript
+ * // IP address 127.0.0.1 in big-endian
+ * const ipBytes = new Uint8Array([127, 0, 0, 1]);
+ * assertU32BeBytes(ipBytes);
+ * // ipBytes is now typed as U32BeBytes
+ * ```
+ *
+ * @returns `void` — type narrowing is applied to the argument in-place.
+ * @see {@link U32BeBytes}
+ * @public
+ */
+declare function assertU32BeBytes(value: Uint8Array): asserts value is U32BeBytes;
+/**
+ * Asserts that a value is an 8-byte big-endian byte array.
+ *
+ * @param value - The Uint8Array to assert (must be exactly 8 bytes)
+ * @throws {MathematicsAssertionError} If not a Uint8Array or wrong length
+ *
+ * @example
+ * ```typescript
+ * const bytes = new Uint8Array(8);
+ * assertU64BeBytes(bytes);
+ * // bytes is now typed as U64BeBytes
+ * ```
+ *
+ * @returns `void` — type narrowing is applied to the argument in-place.
+ * @see {@link U64BeBytes}
+ * @public
+ */
+declare function assertU64BeBytes(value: Uint8Array): asserts value is U64BeBytes;
+/**
+ * Asserts that a value is a 16-byte big-endian byte array.
+ *
+ * @param value - The Uint8Array to assert (must be exactly 16 bytes)
+ * @throws {MathematicsAssertionError} If not a Uint8Array or wrong length
+ *
+ * @example
+ * ```typescript
+ * // UUID bytes in big-endian format
+ * const uuidBytes = new Uint8Array(16);
+ * assertU128BeBytes(uuidBytes);
+ * // uuidBytes is now typed as U128BeBytes
+ * ```
+ *
+ * @returns `void` — type narrowing is applied to the argument in-place.
+ * @see {@link U128BeBytes}
+ * @public
+ */
+declare function assertU128BeBytes(value: Uint8Array): asserts value is U128BeBytes;
+/**
+ * Asserts that a value is a 32-byte big-endian byte array.
+ *
+ * @param value - The Uint8Array to assert (must be exactly 32 bytes)
+ * @throws {MathematicsAssertionError} If not a Uint8Array or wrong length
+ *
+ * @remarks
+ * Big-endian 256-bit arrays are common in cryptographic specifications
+ * and blockchain protocols.
+ *
+ * @example
+ * ```typescript
+ * // Hash output in standard big-endian format
+ * assertU256BeBytes(sha256Result);
+ * // sha256Result is now typed as U256BeBytes
+ * ```
+ *
+ * @returns `void` — type narrowing is applied to the argument in-place.
+ * @see {@link U256BeBytes}
+ * @public
+ */
+declare function assertU256BeBytes(value: Uint8Array): asserts value is U256BeBytes;
+/**
+ * Asserts that a value is a 64-byte big-endian byte array.
+ *
+ * @param value - The Uint8Array to assert (must be exactly 64 bytes)
+ * @throws {MathematicsAssertionError} If not a Uint8Array or wrong length
+ *
+ * @example
+ * ```typescript
+ * const bytes = new Uint8Array(64);
+ * assertU512BeBytes(bytes);
+ * // bytes is now typed as U512BeBytes
+ * ```
+ *
+ * @returns `void` — type narrowing is applied to the argument in-place.
+ * @see {@link U512BeBytes}
+ * @public
+ */
+declare function assertU512BeBytes(value: Uint8Array): asserts value is U512BeBytes;
+/**
+ * Asserts that a value is a 128-byte big-endian byte array.
+ *
+ * @param value - The Uint8Array to assert (must be exactly 128 bytes)
+ * @throws {MathematicsAssertionError} If not a Uint8Array or wrong length
+ *
+ * @example
+ * ```typescript
+ * const bytes = new Uint8Array(128);
+ * assertU1024BeBytes(bytes);
+ * // bytes is now typed as U1024BeBytes
+ * ```
+ *
+ * @returns `void` — type narrowing is applied to the argument in-place.
+ * @see {@link U1024BeBytes}
+ * @public
+ */
+declare function assertU1024BeBytes(value: Uint8Array): asserts value is U1024BeBytes;
+/**
+ * Asserts that a value is a non-negative bigint and narrows it to `UnsignedInteger`.
+ *
+ * This is the base assertion for all unsigned integer types.
+ * It validates that the value is a `bigint` and is non-negative (>= 0).
+ *
+ * @param value - The bigint to assert (must be >= 0)
+ * @throws {MathematicsAssertionError} If not a bigint or if negative
+ *
+ * @remarks
+ * Use this when you need to ensure a value is unsigned but don't need
+ * a specific bit-width constraint.
+ *
+ * @example
+ * ```typescript
+ * const value = 12345n;
+ * assertUnsignedInteger(value);
+ * // value is now typed as UnsignedInteger
+ *
+ * assertUnsignedInteger(-1n); // Throws: negative value
+ * ```
+ *
+ * @returns `void` — type narrowing is applied to the argument in-place.
+ * @see {@link UnsignedInteger}
+ * @public
+ */
+declare function assertUnsignedInteger(value: bigint): asserts value is UnsignedInteger;
+/**
+ * Asserts that a value is a bigint and narrows it to `SignedInteger`.
+ *
+ * This is the base assertion for all signed integer types.
+ * It only validates that the value is a `bigint` (no range constraints).
+ *
+ * @param value - The bigint to assert
+ * @throws {MathematicsAssertionError} If not a bigint
+ *
+ * @remarks
+ * Use this when you need to ensure a value is a bigint but don't need
+ * a specific bit-width constraint.
+ *
+ * @example
+ * ```typescript
+ * const value = -12345n;
+ * assertSignedInteger(value);
+ * // value is now typed as SignedInteger
+ * ```
+ *
+ * @returns `void` — type narrowing is applied to the argument in-place.
+ * @see {@link SignedInteger}
+ * @public
+ */
+declare function assertSignedInteger(value: bigint): asserts value is SignedInteger;
+/**
+ * Asserts that a value is a valid 8-bit unsigned integer (0 to 255).
+ *
+ * @param value - The bigint to assert (must be in range [0, 255])
+ * @throws {MathematicsAssertionError} If not a bigint or out of range
+ *
+ * @example
+ * ```typescript
+ * const value = 255n;
+ * assertU8(value);
+ * // value is now typed as U8
+ *
+ * assertU8(256n);  // Throws: exceeds maximum
+ * assertU8(-1n);   // Throws: below minimum
+ * ```
+ *
+ * @returns `void` — type narrowing is applied to the argument in-place.
+ * @see {@link U8}
+ * @public
+ */
+declare function assertU8(value: bigint): asserts value is U8;
+/**
+ * Asserts that a value is a valid 16-bit unsigned integer (0 to 65,535).
+ *
+ * @param value - The bigint to assert (must be in range [0, 65535])
+ * @throws {MathematicsAssertionError} If not a bigint or out of range
+ *
+ * @example
+ * ```typescript
+ * const port = 443n;
+ * assertU16(port);
+ * // port is now typed as U16
+ *
+ * assertU16(65536n);  // Throws: exceeds maximum
+ * ```
+ *
+ * @returns `void` — type narrowing is applied to the argument in-place.
+ * @see {@link U16}
+ * @public
+ */
+declare function assertU16(value: bigint): asserts value is U16;
+/**
+ * Asserts that a value is a valid 32-bit unsigned integer (0 to 4,294,967,295).
+ *
+ * @param value - The bigint to assert (must be in range [0, 4294967295])
+ * @throws {MathematicsAssertionError} If not a bigint or out of range
+ *
+ * @example
+ * ```typescript
+ * const timestamp = 1704067200n;
+ * assertU32(timestamp);
+ * // timestamp is now typed as U32
+ *
+ * assertU32(4294967296n);  // Throws: exceeds maximum (2^32)
+ * ```
+ *
+ * @returns `void` — type narrowing is applied to the argument in-place.
+ * @see {@link U32}
+ * @public
+ */
+declare function assertU32(value: bigint): asserts value is U32;
+/**
+ * Asserts that a value is a valid 64-bit unsigned integer.
+ *
+ * @param value - The bigint to assert (must be in range [0, 2^64 - 1])
+ * @param name - The name of the variable being asserted, used in error messages for context.
+ * @throws {MathematicsAssertionError} If not a bigint or out of range
+ *
+ * @defaultValue `name` defaults to `"value"`
+ *
+ * @example
+ * ```typescript
+ * const large = 18446744073709551615n;
+ * assertU64(large, "large");
+ * // large is now typed as U64
+ * ```
+ *
+ * @returns `void` — type narrowing is applied to the argument in-place.
+ * @see {@link U64}
+ * @public
+ */
+declare function assertU64(value: bigint, name?: string): asserts value is U64;
+/**
+ * Asserts that a value is a valid 128-bit unsigned integer.
+ *
+ * @param value - The bigint to assert (must be in range [0, 2^128 - 1])
+ * @param name - The name of the variable being asserted, used in error messages for context.
+ * @throws {MathematicsAssertionError} If not a bigint or out of range
+ *
+ * @defaultValue `name` defaults to `"value"`
+ *
+ * @example
+ * ```typescript
+ * const uuid = 0x550e8400e29b41d4a716446655440000n;
+ * assertU128(uuid, "uuid");
+ * // uuid is now typed as U128
+ * ```
+ *
+ * @returns `void` — type narrowing is applied to the argument in-place.
+ * @see {@link U128}
+ * @public
+ */
+declare function assertU128(value: bigint, name?: string): asserts value is U128;
+/**
+ * Asserts that a value is a valid 256-bit unsigned integer.
+ *
+ * @param value - The bigint to assert (must be in range [0, 2^256 - 1])
+ * @param name - The name of the variable being asserted, used in error messages for context.
+ * @throws {MathematicsAssertionError} If not a bigint or out of range
+ *
+ * @defaultValue `name` defaults to `"value"`
+ *
+ * @remarks
+ * This is commonly used for elliptic curve operations where scalars
+ * and field elements must be within the 256-bit range.
+ *
+ * @example
+ * ```typescript
+ * // Validate a private key is in valid range
+ * assertU256(secretKeyBigInt, "secretKeyBigInt");
+ * // secretKeyBigInt is now typed as U256
+ *
+ * // Validate a hash value
+ * assertU256(sha256AsBigInt, "sha256AsBigInt");
+ * // sha256AsBigInt is now typed as U256
+ * ```
+ *
+ * @returns `void` — type narrowing is applied to the argument in-place.
+ * @see {@link U256}
+ * @public
+ */
+declare function assertU256(value: bigint, name?: string): asserts value is U256;
+/**
+ * Asserts that a value is a valid 512-bit unsigned integer.
+ *
+ * @param value - The bigint to assert (must be in range [0, 2^512 - 1])
+ * @throws {MathematicsAssertionError} If not a bigint or out of range
+ *
+ * @example
+ * ```typescript
+ * assertU512(sha512AsBigInt);
+ * // sha512AsBigInt is now typed as U512
+ * ```
+ *
+ * @returns `void` — type narrowing is applied to the argument in-place.
+ * @see {@link U512}
+ * @public
+ */
+declare function assertU512(value: bigint): asserts value is U512;
+/**
+ * Asserts that a value is a valid 1024-bit unsigned integer.
+ *
+ * @param value - The bigint to assert (must be in range [0, 2^1024 - 1])
+ * @throws {MathematicsAssertionError} If not a bigint or out of range
+ *
+ * @example
+ * ```typescript
+ * assertU1024(modulusBigInt);
+ * // modulusBigInt is now typed as U1024
+ * ```
+ *
+ * @returns `void` — type narrowing is applied to the argument in-place.
+ * @see {@link U1024}
+ * @public
+ */
+declare function assertU1024(value: bigint): asserts value is U1024;
+/**
+ * Asserts that a value is a valid 8-bit signed integer (-128 to 127).
+ *
+ * @param value - The bigint to assert (must be in range [-128, 127])
+ * @throws {MathematicsAssertionError} If not a bigint or out of range
+ *
+ * @example
+ * ```typescript
+ * const value = 127n;
+ * assertI8(value);
+ * // value is now typed as I8
+ *
+ * assertI8(128n);   // Throws: exceeds maximum
+ * assertI8(-129n);  // Throws: below minimum
+ * ```
+ *
+ * @returns `void` — type narrowing is applied to the argument in-place.
+ * @see {@link I8}
+ * @public
+ */
+declare function assertI8(value: bigint): asserts value is I8;
+/**
+ * Asserts that a value is a valid 16-bit signed integer (-32,768 to 32,767).
+ *
+ * @param value - The bigint to assert (must be in range [-32768, 32767])
+ * @throws {MathematicsAssertionError} If not a bigint or out of range
+ *
+ * @example
+ * ```typescript
+ * const audioSample = -16384n;
+ * assertI16(audioSample);
+ * // audioSample is now typed as I16
+ * ```
+ *
+ * @returns `void` — type narrowing is applied to the argument in-place.
+ * @see {@link I16}
+ * @public
+ */
+declare function assertI16(value: bigint): asserts value is I16;
+/**
+ * Asserts that a value is a valid 32-bit signed integer.
+ *
+ * @param value - The bigint to assert (must be in range [-2147483648, 2147483647])
+ * @throws {MathematicsAssertionError} If not a bigint or out of range
+ *
+ * @example
+ * ```typescript
+ * const offset = -1000n;
+ * assertI32(offset);
+ * // offset is now typed as I32
+ * ```
+ *
+ * @returns `void` — type narrowing is applied to the argument in-place.
+ * @see {@link I32}
+ * @public
+ */
+declare function assertI32(value: bigint): asserts value is I32;
+/**
+ * Asserts that a value is a valid 64-bit signed integer.
+ *
+ * @param value - The bigint to assert (must be in range [-2^63, 2^63 - 1])
+ * @throws {MathematicsAssertionError} If not a bigint or out of range
+ *
+ * @example
+ * ```typescript
+ * const difference = -1000000000000n;
+ * assertI64(difference);
+ * // difference is now typed as I64
+ * ```
+ *
+ * @returns `void` — type narrowing is applied to the argument in-place.
+ * @see {@link I64}
+ * @public
+ */
+declare function assertI64(value: bigint): asserts value is I64;
+/**
+ * Asserts that a value is a valid 128-bit signed integer.
+ *
+ * @param value - The bigint to assert (must be in range [-2^127, 2^127 - 1])
+ * @throws {MathematicsAssertionError} If not a bigint or out of range
+ *
+ * @example
+ * ```typescript
+ * const value = -170141183460469231731687303715884105728n;
+ * assertI128(value);
+ * // value is now typed as I128
+ * ```
+ *
+ * @returns `void` — type narrowing is applied to the argument in-place.
+ * @see {@link I128}
+ * @public
+ */
+declare function assertI128(value: bigint): asserts value is I128;
+/**
+ * Asserts that a value is a valid 256-bit signed integer.
+ *
+ * @param value - The bigint to assert (must be in range [-2^255, 2^255 - 1])
+ * @throws {MathematicsAssertionError} If not a bigint or out of range
+ *
+ * @example
+ * ```typescript
+ * const signedScalar = -12345678901234567890n;
+ * assertI256(signedScalar);
+ * // signedScalar is now typed as I256
+ * ```
+ *
+ * @returns `void` — type narrowing is applied to the argument in-place.
+ * @see {@link I256}
+ * @public
+ */
+declare function assertI256(value: bigint): asserts value is I256;
+/**
+ * Asserts that a value is a valid 512-bit signed integer.
+ *
+ * @param value - The bigint to assert (must be in range [-2^511, 2^511 - 1])
+ * @throws {MathematicsAssertionError} If not a bigint or out of range
+ *
+ * @example
+ * ```typescript
+ * const value = -1n;
+ * assertI512(value);
+ * // value is now typed as I512
+ * ```
+ *
+ * @returns `void` — type narrowing is applied to the argument in-place.
+ * @see {@link I512}
+ * @public
+ */
+declare function assertI512(value: bigint): asserts value is I512;
+/**
+ * Asserts that a value is a valid 1024-bit signed integer.
+ *
+ * @param value - The bigint to assert (must be in range [-2^1023, 2^1023 - 1])
+ * @throws {MathematicsAssertionError} If not a bigint or out of range
+ *
+ * @example
+ * ```typescript
+ * const value = 0n;
+ * assertI1024(value);
+ * // value is now typed as I1024
+ * ```
+ *
+ * @returns `void` — type narrowing is applied to the argument in-place.
+ * @see {@link I1024}
+ * @public
+ */
+declare function assertI1024(value: bigint): asserts value is I1024;
+
+export { I64_MIN as $, type U8 as A, type Bytes as B, type I128 as C, type I16 as D, type I256 as E, type I32 as F, type I512 as G, type I64 as H, type I1024 as I, type I8 as J, type BeBytes as K, type ExtractBrand as L, I1024_MAX as M, I1024_MIN as N, I128_MAX as O, I128_MIN as P, I16_MAX as Q, I16_MIN as R, type SubSubBrandedType as S, I256_MAX as T, type U128 as U, I256_MIN as V, I32_MAX as W, I32_MIN as X, I512_MAX as Y, I512_MIN as Z, I64_MAX as _, type SubSubSubBrandedType as a, I8_MAX as a0, I8_MIN as a1, type LeBytes as a2, MathematicsAssertionError as a3, type SignedInteger as a4, U1024_BYTE_LENGTH as a5, U1024_MAX as a6, U128_BYTE_LENGTH as a7, U128_MAX as a8, U16_BYTE_LENGTH as a9, assertU1024BeBytes as aA, assertU1024LeBytes as aB, assertU128 as aC, assertU128BeBytes as aD, assertU128LeBytes as aE, assertU16 as aF, assertU16BeBytes as aG, assertU16LeBytes as aH, assertU256 as aI, assertU256BeBytes as aJ, assertU256LeBytes as aK, assertU32 as aL, assertU32BeBytes as aM, assertU32LeBytes as aN, assertU512 as aO, assertU512BeBytes as aP, assertU512LeBytes as aQ, assertU64 as aR, assertU64BeBytes as aS, assertU64LeBytes as aT, assertU8 as aU, assertU8BeBytes as aV, assertU8LeBytes as aW, assertUnsignedInteger as aX, U16_MAX as aa, U256_BYTE_LENGTH as ab, U256_MAX as ac, U32_BYTE_LENGTH as ad, U32_MAX as ae, U512_BYTE_LENGTH as af, U512_MAX as ag, U64_BYTE_LENGTH as ah, U64_MAX as ai, U8_BYTE_LENGTH as aj, U8_MAX as ak, type UnsignedInteger as al, type UnwrapBrand as am, assertBeBytes as an, assertBytes as ao, assertI1024 as ap, assertI128 as aq, assertI16 as ar, assertI256 as as, assertI32 as at, assertI512 as au, assertI64 as av, assertI8 as aw, assertLeBytes as ax, assertSignedInteger as ay, assertU1024 as az, type SubBrandedType as b, type SubSubSubSubBrandedType as c, type U512LeBytes as d, type U256LeBytes as e, type U256 as f, type BrandedType as g, type U512 as h, type U512BeBytes as i, type U32 as j, type U64 as k, type U128LeBytes as l, type U1024BeBytes as m, type U1024LeBytes as n, type U128BeBytes as o, type U16BeBytes as p, type U16LeBytes as q, type U256BeBytes as r, type U32BeBytes as s, type U32LeBytes as t, type U64BeBytes as u, type U64LeBytes as v, type U8BeBytes as w, type U8LeBytes as x, type U1024 as y, type U16 as z };