import { ChunkCollection } from './chunk-utils.js';
import { EncoderOptions } from './encoder.js';

type DecoderAPI = {
    /**
     * Stage an available chunk inside the decoder workspace.
     *
     * `idx` must reference a chunk that survived (i.e. *not* flagged as erased) and the
     * buffer size should equal `chunkSizeBytes`. The data is copied into wasm memory so
     * the input array may be reused immediately.
     */
    setChunk(idx: number, data: Uint8Array): void;
    /**
     * Execute the Clay recovery algorithm using the staged chunks.
     *
     * At least `k` distinct chunks (across data and parity) must be provided before
     * invoking this; on success the decoder will have reconstructed every erased chunk.
     */
    run(): void;
    /**
     * Materialise a chunk after recovery as a detached copy from wasm memory.
     *
     * The index can reference either a previously staged chunk or one that was repaired.
     */
    getChunk(idx: number): Uint8Array;
    /**
     * Reset decoder state to prepare for a new decode operation.
     *
     * Clears internal decode state to allow reusing the decoder.
     * Does NOT reset decoder configuration or erasure pattern.
     *
     * Safe to call at any time, idempotent.
     */
    reset(): void;
    /**
     * Decode available chunks and recover all erased chunks.
     *
     * The decoder automatically reconfigures for the given erasure pattern,
     * stages the provided chunks, runs recovery, and returns all chunks.
     *
     * @param available - Array of available (non-erased) chunks
     * @param erasurePattern - Description of which chunks are missing
     * @returns Collection containing all recovered chunks (systematic + parity)
     */
    decode(available: Uint8Array[] | Uint8Array, erasurePattern: DecoderReconfigureOptions): ChunkCollection;
    /**
     * Get an array of the chunk merkle tree roots, calculated by processing the samples as leaves of a binary merkle tree.
     */
    getChunkMerkleRoots(): Uint8Array[];
    /**
     * Placeholder for a potential explicit teardown hook should the wasm side gain one.
     */
    free?(): void;
};
/**
 * Erasure pattern specified as a bit mask.
 *
 * The `erasedChunksMask` is a bit mask where each bit position corresponds to
 * a chunk index, and a 1 bit means that chunk is erased (missing/unavailable).
 * For MDS codes, the mask is limited to 32 bits (4 bytes), supporting up to 32 chunks.
 *
 * Example: If chunks 1, 3, and 5 are erased (out of 8 total):
 *
 * ```bash
 *   erasedChunksMask = 0b00101010  // binary
 *                    = 0x2A        // hex
 *                    = 42          // decimal
 * ```
 *
 *   Breaking it down by bit position:
 *
 * ```bash
 *   Bit 0 (chunk 0): 0 → available
 *   Bit 1 (chunk 1): 1 → ERASED
 *   Bit 2 (chunk 2): 0 → available
 *   Bit 3 (chunk 3): 1 → ERASED
 *   Bit 4 (chunk 4): 0 → available
 *   Bit 5 (chunk 5): 1 → ERASED
 *   Bit 6 (chunk 6): 0 → available
 *   Bit 7 (chunk 7): 0 → available
 * ```
 */
type ErasurePatternMask = {
    erasedChunksMask: number;
};
/**
 * Erasure pattern specified as a list of erased chunk indexes.
 */
type ErasurePatternErasedIndexes = {
    erasedChunkIndexes: readonly number[];
};
/**
 * Erasure pattern specified as a list of available chunk indexes.
 */
type ErasurePatternAvailableIndexes = {
    availableChunkIndexes: readonly number[];
};
/**
 * Narrow view over the inputs needed to retarget a decoder instance.
 * Callers can provide the erasure pattern in whichever format is most convenient:
 * a bit mask, erased chunk indexes, or available chunk indexes.
 *
 * Note: Regardless of which format you provide, `configure()` always returns
 * available chunk indexes in sorted order [0, 2, 4, ...]. Any ordering information
 * from `availableChunkIndexes` is not preserved.
 *
 * These are all equivalent:
 *
 * ```ts
 *   decoder.configure({ erasedChunksMask: 42 })
 *   decoder.configure({ erasedChunkIndexes: [1, 3, 5] })
 *   decoder.configure({ availableChunkIndexes: [0, 2, 4, 6, 7] })
 * ```
 */
type DecoderReconfigureOptions = ErasurePatternMask | ErasurePatternErasedIndexes | ErasurePatternAvailableIndexes;
/**
 * Options for configuring a Clay decoder instance.
 *
 * The decoder shares the same Clay parameters as the encoder and additionally
 * requires knowledge of which chunks are unavailable for recovery.
 */
type DecoderOptions = EncoderOptions & DecoderReconfigureOptions;
/**
 * Maximum number of chunks supported by the bit mask representation.
 *
 * MDS (Maximum Distance Separable) decoder uses a 32-bit integer to represent
 * which chunks are erased, limiting support to 32 chunks total.
 * For larger erasure codes, use the index-based configuration instead.
 */
declare const MAX_WASM_MASK_BITS = 32;
/**
 * Full bitmask with all MAX_WASM_MASK_BITS bits set to 1.
 * Equals 2^32 - 1 = 4,294,967,295 in decimal.
 */
declare const FULL_WASM_MASK = 4294967295;
/**
 * Converts any supported erasure pattern format to a bit mask.
 *
 * @param options - Erasure pattern in any supported format
 * @param totalChunks - Total number of chunks = n = k + m
 * @returns Bit mask where 1 indicates an erased chunk
 */
declare function convertToErasedMask(options: DecoderReconfigureOptions, totalChunks: number): number;
/**
 * ### Builds the JS facade for the Clay decoder.
 *
 * The wasm side only needs a handful of monotonic, long-lived allocations
 * (params, encoder instance, staging buffer), so we lean on a simple bump allocator rooted at
 * `__heap_base` rather than shipping a heavier malloc/free pair.
 *
 * **Important:** Coding parameters (n, k, d, chunkSizeBytes) are fixed for the lifetime of
 * the decoder instance. These parameters determine WASM memory layout and buffer sizes. Only
 * the erasure pattern can be reconfigured via `configure()`. To use different coding parameters,
 * create a new decoder instance.
 *
 * For more info @see {@link import("./encoder").makeEncoderAPI}
 */
declare function makeDecoderAPI(instance: WebAssembly.Instance, opts: DecoderOptions): DecoderAPI;

export { type DecoderAPI, type DecoderOptions, type DecoderReconfigureOptions, type ErasurePatternAvailableIndexes, type ErasurePatternErasedIndexes, type ErasurePatternMask, FULL_WASM_MASK, MAX_WASM_MASK_BITS, convertToErasedMask, makeDecoderAPI };