/*

 * ZXC - High-performance lossless compression

 *

 * Copyright (c) 2025-2026 Bertrand Lebonnois and contributors.

 * SPDX-License-Identifier: BSD-3-Clause

 */

/**

 * @file zxc_dispatch.c

 * @brief Runtime CPU feature detection and SIMD dispatch layer.

 *

 * Detects AVX2/AVX512 (x86-64) and NEON (32-bit ARM) at runtime and routes

 * compress/decompress calls to the best available implementation via

 * lazy-initialised function pointers. SSE2 on x86-64 and NEON on AArch64 are

 * baseline ISA guarantees, so the _default variant already covers those tiers.

 * Also contains the public one-shot buffer API (@ref zxc_compress,

 * @ref zxc_decompress, @ref zxc_get_decompressed_size).

 */

#include "../../include/zxc_dict.h"

#include "../../include/zxc_error.h"

#include "../../include/zxc_seekable.h"

#include "zxc_internal.h"

/*

 * ZXC_DISABLE_SIMD => force ZXC_ONLY_DEFAULT so the dispatcher never selects

 * an AVX2/AVX512/NEON variant.

 */

#if defined(ZXC_DISABLE_SIMD) && !defined(ZXC_ONLY_DEFAULT)

#define ZXC_ONLY_DEFAULT

#endif

#if defined(_MSC_VER)

#include <intrin.h>

#if defined(_M_X64)

#include <immintrin.h>  // _xgetbv (x86-specific header; x64 AVX state check)

#endif

#endif

#if (defined(__x86_64__) || defined(_M_X64)) && !defined(_MSC_VER) && !defined(ZXC_ONLY_DEFAULT)

#include <cpuid.h>  // __cpuid_count: CPUID probes in zxc_detect_cpu_features

#endif

#if defined(__linux__) && (defined(__arm__) || defined(_M_ARM))

#include <asm/hwcap.h>

#include <sys/auxv.h>

#endif

/*

 * ============================================================================

 * PROTOTYPES FOR MULTI-VERSIONED VARIANTS

 * ============================================================================

 * These are compiled in separate translation units with different flags.

 */

// Decompression Prototypes

int zxc_decompress_chunk_wrapper_default(const zxc_cctx_t* RESTRICT ctx,

                                         const uint8_t* RESTRICT src, const size_t src_sz,

                                         uint8_t* RESTRICT dst, const size_t dst_cap);

int zxc_decompress_chunk_wrapper_dict_default(const zxc_cctx_t* RESTRICT ctx,

                                              const uint8_t* RESTRICT src, const size_t src_sz,

                                              uint8_t* RESTRICT dst, const size_t dst_cap);

int zxc_decompress_chunk_wrapper_safe_default(const zxc_cctx_t* RESTRICT ctx,

                                              const uint8_t* RESTRICT src, const size_t src_sz,

                                              uint8_t* RESTRICT dst, const size_t dst_cap);

#ifndef ZXC_ONLY_DEFAULT

#if defined(__x86_64__) || defined(_M_X64)

int zxc_decompress_chunk_wrapper_avx2(const zxc_cctx_t* RESTRICT ctx, const uint8_t* RESTRICT src,

                                      const size_t src_sz, uint8_t* RESTRICT dst,

                                      const size_t dst_cap);

int zxc_decompress_chunk_wrapper_dict_avx2(const zxc_cctx_t* RESTRICT ctx,

                                           const uint8_t* RESTRICT src, const size_t src_sz,

                                           uint8_t* RESTRICT dst, const size_t dst_cap);

int zxc_decompress_chunk_wrapper_avx512(const zxc_cctx_t* RESTRICT ctx, const uint8_t* RESTRICT src,

                                        const size_t src_sz, uint8_t* RESTRICT dst,

                                        const size_t dst_cap);

int zxc_decompress_chunk_wrapper_dict_avx512(const zxc_cctx_t* RESTRICT ctx,

                                             const uint8_t* RESTRICT src, const size_t src_sz,

                                             uint8_t* RESTRICT dst, const size_t dst_cap);

int zxc_decompress_chunk_wrapper_safe_avx2(const zxc_cctx_t* RESTRICT ctx,

                                           const uint8_t* RESTRICT src, const size_t src_sz,

                                           uint8_t* RESTRICT dst, const size_t dst_cap);

int zxc_decompress_chunk_wrapper_safe_avx512(const zxc_cctx_t* RESTRICT ctx,

                                             const uint8_t* RESTRICT src, const size_t src_sz,

                                             uint8_t* RESTRICT dst, const size_t dst_cap);

#elif defined(__arm__) || defined(_M_ARM)

int zxc_decompress_chunk_wrapper_neon32(const zxc_cctx_t* RESTRICT ctx, const uint8_t* RESTRICT src,

                                        const size_t src_sz, uint8_t* RESTRICT dst,

                                        const size_t dst_cap);

int zxc_decompress_chunk_wrapper_dict_neon32(const zxc_cctx_t* RESTRICT ctx,

                                             const uint8_t* RESTRICT src, const size_t src_sz,

                                             uint8_t* RESTRICT dst, const size_t dst_cap);

int zxc_decompress_chunk_wrapper_safe_neon32(const zxc_cctx_t* RESTRICT ctx,

                                             const uint8_t* RESTRICT src, const size_t src_sz,

                                             uint8_t* RESTRICT dst, const size_t dst_cap);

#endif

#endif

// Compression Prototypes

int zxc_compress_chunk_wrapper_default(zxc_cctx_t* RESTRICT ctx, const uint8_t* RESTRICT src,

                                       const size_t src_sz, uint8_t* RESTRICT dst,

                                       const size_t dst_cap);

// Huffman prototypes (variant TUs of zxc_huffman.c). Compressor and decompressor

// variants bind to the matching suffixed symbol at compile time, so the hot path

// pays no dispatch; the wrappers below expose un-suffixed names to callers.

int zxc_huf_build_code_lengths_default(const uint32_t* RESTRICT freq, uint8_t* RESTRICT code_len,

                                       void* RESTRICT scratch, int max_code_len);

size_t zxc_huf_calc_size_default(const uint32_t* RESTRICT freq, const uint8_t* RESTRICT code_len,

                                 int with_header);

int zxc_huf_encode_section_default(const uint8_t* RESTRICT literals, size_t n_literals,

                                   const uint32_t* RESTRICT freq, const uint8_t* RESTRICT code_len,

                                   uint8_t* RESTRICT dst, size_t dst_cap);

int zxc_huf_decode_section_default(const uint8_t* RESTRICT payload, size_t payload_size,

                                   uint8_t* RESTRICT dst, size_t n, uint8_t* RESTRICT scratch);

int zxc_huf_encode_section_dict_default(const uint8_t* RESTRICT literals, size_t n_literals,

                                        const uint32_t* RESTRICT freq,

                                        const uint8_t* RESTRICT code_len,

                                        const zxc_pivco_tree_t* RESTRICT tree,

                                        const uint32_t* RESTRICT codes, uint8_t* RESTRICT dst,

                                        size_t dst_cap);

int zxc_huf_decode_section_dict_default(const uint8_t* RESTRICT payload, size_t payload_size,

                                        uint8_t* RESTRICT dst, size_t n,

                                        const zxc_pivco_tree_t* RESTRICT tree,

                                        const zxc_pivco_decode_aux_t* RESTRICT aux,

                                        uint8_t* RESTRICT scratch);

size_t zxc_huf_calc_size_dict_default(const uint32_t* RESTRICT freq,

                                      const uint8_t* RESTRICT code_len,

                                      const zxc_pivco_tree_t* RESTRICT tree);

void zxc_huf_pack_lengths_default(const uint8_t* RESTRICT code_len, uint8_t* RESTRICT out);

int zxc_huf_unpack_lengths_default(const uint8_t* RESTRICT in, uint8_t* RESTRICT code_len);

#if defined(__x86_64__) || defined(_M_X64)

int zxc_compress_chunk_wrapper_avx2(zxc_cctx_t* RESTRICT ctx, const uint8_t* RESTRICT src,

                                    const size_t src_sz, uint8_t* RESTRICT dst,

                                    const size_t dst_cap);

int zxc_compress_chunk_wrapper_avx512(zxc_cctx_t* RESTRICT ctx, const uint8_t* RESTRICT src,

                                      const size_t src_sz, uint8_t* RESTRICT dst,

                                      const size_t dst_cap);

#elif defined(__arm__) || defined(_M_ARM)

int zxc_compress_chunk_wrapper_neon32(zxc_cctx_t* RESTRICT ctx, const uint8_t* RESTRICT src,

                                      const size_t src_sz, uint8_t* RESTRICT dst,

                                      const size_t dst_cap);

#endif

/*

 * ============================================================================

 * CPU DETECTION LOGIC

 * ============================================================================

 */

#if (defined(__x86_64__) || defined(_M_X64)) && !defined(ZXC_ONLY_DEFAULT)

/** @brief Reads CPUID leaf @p leaf, subleaf @p sub into @p regs (EAX,EBX,ECX,EDX). */

static inline void zxc_cpuid(const uint32_t leaf, const uint32_t sub, uint32_t regs[4]) {

#if defined(_MSC_VER)

    int r[4];

    __cpuidex(r, (int)leaf, (int)sub);

    regs[0] = (uint32_t)r[0];

    regs[1] = (uint32_t)r[1];

    regs[2] = (uint32_t)r[2];

    regs[3] = (uint32_t)r[3];

#else

    __cpuid_count(leaf, sub, regs[0], regs[1], regs[2], regs[3]);

#endif

}

/** @brief Reads XCR0 (@c XGETBV with ECX=0). Callers must check OSXSAVE first. */

static inline uint64_t zxc_xgetbv0(void) {

#if defined(_MSC_VER)

    return _xgetbv(0);

#else

    /* Raw encoding: the xgetbv intrinsic needs -mxsave, which the baseline

     * translation unit is not compiled with. */

    uint32_t lo, hi;

    __asm__ volatile(".byte 0x0f, 0x01, 0xd0" : "=a"(lo), "=d"(hi) : "c"(0));

    return ((uint64_t)hi << 32) | lo;

#endif

}

#endif /* x86-64 && !ZXC_ONLY_DEFAULT */

/**

 * @enum zxc_cpu_feature_t

 * @brief Detected CPU SIMD capability level.

 */

typedef enum {

    ZXC_CPU_GENERIC = 0, /**< @brief Scalar-only fallback.   */

    ZXC_CPU_AVX2 = 1,    /**< @brief x86-64 AVX2 available.  */

    ZXC_CPU_AVX512 = 2,  /**< @brief x86-64 AVX-512F+BW available. */

    ZXC_CPU_NEON = 3,    /**< @brief ARM NEON available (dedicated variant on 32-bit ARM only;

                          *          AArch64 baseline, served by _default there). */

    ZXC_CPU_SSE2 = 4     /**< @brief x86 SSE2 available (no AVX2); x86-64 baseline,

                          *          served by _default (no dedicated variant). */

} zxc_cpu_feature_t;

/**

 * @brief Probes the running CPU for SIMD support.

 *

 * Uses CPUID on x86-64 (MSVC and GCC/Clang paths), `getauxval` on

 * 32-bit ARM Linux, and compile-time constants on AArch64.

 *

 * @return The highest @ref zxc_cpu_feature_t level supported.

 */

// LCOV_EXCL_START

static zxc_cpu_feature_t zxc_detect_cpu_features(void) {

#ifdef ZXC_ONLY_DEFAULT

    return ZXC_CPU_GENERIC;

#else

    zxc_cpu_feature_t features = ZXC_CPU_GENERIC;

#if defined(__x86_64__) || defined(_M_X64)

    // AVX2/AVX512 need OS-enabled YMM/ZMM state: gate on OSXSAVE + XGETBV/XCR0,

    // not CPUID alone (else a VEX/EVEX op faults #UD when the OS hasn't enabled it).

    uint32_t regs[4];

    int sse2 = 0;

    int avx2 = 0;

    int avx512 = 0;

    int bmi_lzcnt = 0;

    zxc_cpuid(0, 0, regs);

    const uint32_t max_leaf = regs[0];

    zxc_cpuid(1, 0, regs);

    if (regs[3] & (1U << 26)) sse2 = 1;             // CPUID.1:EDX[26]

    if ((regs[2] & (1U << 27)) && max_leaf >= 7) {  // OSXSAVE, and leaf 7 is real

        const uint64_t xcr0 = zxc_xgetbv0();

        if ((xcr0 & 0x6) == 0x6) {  // SSE+YMM enabled

            zxc_cpuid(7, 0, regs);

            const int bmi1 = (regs[1] >> 3) & 1;  // CPUID.7.0:EBX[3]

            const int bmi2 = (regs[1] >> 8) & 1;  // CPUID.7.0:EBX[8]

            if (regs[1] & (1U << 5)) avx2 = 1;

            // AVX512 also needs XCR0[5..7] (opmask/ZMM)

            if ((regs[1] & (1U << 16)) && (regs[1] & (1U << 30)) && (regs[2] & (1U << 6)) &&

                (xcr0 & 0xE0) == 0xE0)

                avx512 = 1; /* AVX512 tier = F+BW+VBMI2 (variant built with -mavx512vbmi2) */

            // The AVX2/AVX512 variants are compiled with BMI1/BMI2/LZCNT enabled,

            // so both gates must prove those bits too. LZCNT (ABM) lives in

            // CPUID.80000001H:ECX[5]; that leaf is architectural on x86-64.

            zxc_cpuid(0x80000001U, 0, regs);

            bmi_lzcnt = bmi1 && bmi2 && ((regs[2] >> 5) & 1);

        }

    }

    if (avx512 && bmi_lzcnt) {

        features = ZXC_CPU_AVX512;

    } else if (avx2 && bmi_lzcnt) {

        features = ZXC_CPU_AVX2;

    } else if (sse2) {

        features = ZXC_CPU_SSE2;

    }

#elif defined(__aarch64__) || defined(_M_ARM64)

    // ARM64 usually guarantees NEON

    features = ZXC_CPU_NEON;

#elif defined(__arm__) || defined(_M_ARM)

    // ARM32 Runtime detection for Linux

#if defined(__linux__)

    const unsigned long hwcaps = getauxval(AT_HWCAP);

    if (hwcaps & HWCAP_NEON) {

        features = ZXC_CPU_NEON;

    }

#else

// Fallback for non-Linux: rely on compiler flags.

// If compiled with -mfpu=neon, we assume target supports it.

// Otherwise, safe default is GENERIC.

#if defined(__ARM_NEON)

    features = ZXC_CPU_NEON;

#endif

#endif

#endif

    return features;

#endif

}

// LCOV_EXCL_STOP

/*

 * ============================================================================

 * DISPATCHERS

 * ============================================================================

 * We use a function pointer initialized on first use (lazy initialization).

 */

/** @brief Function pointer type for the chunk decompressor. */

typedef int (*zxc_decompress_func_t)(const zxc_cctx_t* RESTRICT, const uint8_t* RESTRICT,

                                     const size_t, uint8_t* RESTRICT, const size_t);

/** @brief Function pointer type for the chunk compressor. */

typedef int (*zxc_compress_func_t)(zxc_cctx_t* RESTRICT, const uint8_t* RESTRICT, const size_t,

                                   uint8_t* RESTRICT, const size_t);

/** @brief Lazily-resolved pointer to the best decompression variant. */

static ZXC_ATOMIC zxc_decompress_func_t zxc_decompress_ptr = (zxc_decompress_func_t)0;

/** @brief Lazily-resolved pointer to the best dict-decompression variant. */

static ZXC_ATOMIC zxc_decompress_func_t zxc_decompress_dict_ptr = (zxc_decompress_func_t)0;

/** @brief Lazily-resolved pointer to the best safe-decompression variant. */

static ZXC_ATOMIC zxc_decompress_func_t zxc_decompress_safe_ptr = (zxc_decompress_func_t)0;

/** @brief Lazily-resolved pointer to the best compression variant. */

static ZXC_ATOMIC zxc_compress_func_t zxc_compress_ptr = (zxc_compress_func_t)0;

/**

 * @brief First-call initialiser for the decompression dispatcher.

 *

 * Detects CPU features, selects the best implementation, stores the

 * pointer atomically, then tail-calls into it.

 *

 * @param[in]  ctx      Decompression context (its @c dict_size picks the dict variant).

 * @param[in]  src      Compressed input chunk.

 * @param[in]  src_sz   Size of @p src in bytes.

 * @param[out] dst      Destination buffer for decompressed data.

 * @param[in]  dst_cap  Capacity of @p dst in bytes.

 * @return Result of the selected variant: decompressed size, or negative

 *         @ref zxc_error_t.

 */

// LCOV_EXCL_START

static int zxc_decompress_dispatch_init(const zxc_cctx_t* RESTRICT ctx, const uint8_t* RESTRICT src,

                                        const size_t src_sz, uint8_t* RESTRICT dst,

                                        const size_t dst_cap) {

    const zxc_cpu_feature_t cpu = zxc_detect_cpu_features();

    zxc_decompress_func_t zxc_decompress_ptr_local = NULL;

    zxc_decompress_func_t zxc_decompress_dict_ptr_local = NULL;

#ifndef ZXC_ONLY_DEFAULT

#if defined(__x86_64__) || defined(_M_X64)

    if (cpu == ZXC_CPU_AVX512) {

        zxc_decompress_ptr_local = zxc_decompress_chunk_wrapper_avx512;

        zxc_decompress_dict_ptr_local = zxc_decompress_chunk_wrapper_dict_avx512;

    } else if (cpu == ZXC_CPU_AVX2) {

        zxc_decompress_ptr_local = zxc_decompress_chunk_wrapper_avx2;

        zxc_decompress_dict_ptr_local = zxc_decompress_chunk_wrapper_dict_avx2;

    } else {

        zxc_decompress_ptr_local = zxc_decompress_chunk_wrapper_default;

        zxc_decompress_dict_ptr_local = zxc_decompress_chunk_wrapper_dict_default;

    }

#elif defined(__arm__) || defined(_M_ARM)

    // 32-bit ARM: the only arch with a real runtime NEON probe (getauxval).

    // cppcheck-suppress knownConditionTrueFalse

    if (cpu == ZXC_CPU_NEON) {

        zxc_decompress_ptr_local = zxc_decompress_chunk_wrapper_neon32;

        zxc_decompress_dict_ptr_local = zxc_decompress_chunk_wrapper_dict_neon32;

    } else {

        zxc_decompress_ptr_local = zxc_decompress_chunk_wrapper_default;

        zxc_decompress_dict_ptr_local = zxc_decompress_chunk_wrapper_dict_default;

    }

#else

    (void)cpu;

    zxc_decompress_ptr_local = zxc_decompress_chunk_wrapper_default;

    zxc_decompress_dict_ptr_local = zxc_decompress_chunk_wrapper_dict_default;

#endif

#else

    (void)cpu;

    zxc_decompress_ptr_local = zxc_decompress_chunk_wrapper_default;

    zxc_decompress_dict_ptr_local = zxc_decompress_chunk_wrapper_dict_default;

#endif

#if ZXC_USE_C11_ATOMICS

    atomic_store_explicit(&zxc_decompress_ptr, zxc_decompress_ptr_local, memory_order_release);

    atomic_store_explicit(&zxc_decompress_dict_ptr, zxc_decompress_dict_ptr_local,

                          memory_order_release);

#else

    zxc_decompress_ptr = zxc_decompress_ptr_local;

    zxc_decompress_dict_ptr = zxc_decompress_dict_ptr_local;

#endif

    return (ctx->dict_size ? zxc_decompress_dict_ptr_local : zxc_decompress_ptr_local)(

        ctx, src, src_sz, dst, dst_cap);

}

// LCOV_EXCL_STOP

/**

 * @brief First-call initialiser for the safe-decompression dispatcher.

 *

 * Mirrors @ref zxc_decompress_dispatch_init but selects the `_safe_*`

 * decoder variants used by @ref zxc_decompress_block_safe.

 *

 * @param[in]  ctx      Decompression context.

 * @param[in]  src      Compressed input chunk.

 * @param[in]  src_sz   Size of @p src in bytes.

 * @param[out] dst      Destination buffer (strict: exact uncompressed size).

 * @param[in]  dst_cap  Capacity of @p dst in bytes.

 * @return Result of the selected variant: decompressed size, or negative

 *         @ref zxc_error_t.

 */

// LCOV_EXCL_START

static int zxc_decompress_safe_dispatch_init(const zxc_cctx_t* RESTRICT ctx,

                                             const uint8_t* RESTRICT src, const size_t src_sz,

                                             uint8_t* RESTRICT dst, const size_t dst_cap) {

    const zxc_cpu_feature_t cpu = zxc_detect_cpu_features();

    zxc_decompress_func_t zxc_decompress_safe_ptr_local = NULL;

#ifndef ZXC_ONLY_DEFAULT

#if defined(__x86_64__) || defined(_M_X64)

    if (cpu == ZXC_CPU_AVX512)

        zxc_decompress_safe_ptr_local = zxc_decompress_chunk_wrapper_safe_avx512;

    else if (cpu == ZXC_CPU_AVX2)

        zxc_decompress_safe_ptr_local = zxc_decompress_chunk_wrapper_safe_avx2;

    else

        zxc_decompress_safe_ptr_local = zxc_decompress_chunk_wrapper_safe_default;

#elif defined(__arm__) || defined(_M_ARM)

    // cppcheck-suppress knownConditionTrueFalse

    if (cpu == ZXC_CPU_NEON)

        zxc_decompress_safe_ptr_local = zxc_decompress_chunk_wrapper_safe_neon32;

    else

        zxc_decompress_safe_ptr_local = zxc_decompress_chunk_wrapper_safe_default;

#else

    (void)cpu;

    zxc_decompress_safe_ptr_local = zxc_decompress_chunk_wrapper_safe_default;

#endif

#else

    (void)cpu;

    zxc_decompress_safe_ptr_local = zxc_decompress_chunk_wrapper_safe_default;

#endif

#if ZXC_USE_C11_ATOMICS

    atomic_store_explicit(&zxc_decompress_safe_ptr, zxc_decompress_safe_ptr_local,

                          memory_order_release);

#else

    zxc_decompress_safe_ptr = zxc_decompress_safe_ptr_local;

#endif

    return zxc_decompress_safe_ptr_local(ctx, src, src_sz, dst, dst_cap);

}

// LCOV_EXCL_STOP

/**

 * @brief First-call initialiser for the compression dispatcher.

 *

 * Detects CPU features, selects the best implementation, stores the

 * pointer atomically, then tail-calls into it.

 *

 * @param[in,out] ctx      Compression context.

 * @param[in]     src      Uncompressed input chunk.

 * @param[in]     src_sz   Size of @p src in bytes.

 * @param[out]    dst      Destination buffer for the compressed chunk.

 * @param[in]     dst_cap  Capacity of @p dst in bytes.

 * @return Result of the selected variant: compressed size, or negative

 *         @ref zxc_error_t.

 */

// LCOV_EXCL_START

static int zxc_compress_dispatch_init(zxc_cctx_t* RESTRICT ctx, const uint8_t* RESTRICT src,

                                      const size_t src_sz, uint8_t* RESTRICT dst,

                                      const size_t dst_cap) {

    const zxc_cpu_feature_t cpu = zxc_detect_cpu_features();

    zxc_compress_func_t zxc_compress_ptr_local = NULL;

#ifndef ZXC_ONLY_DEFAULT

#if defined(__x86_64__) || defined(_M_X64)

    if (cpu == ZXC_CPU_AVX512)

        zxc_compress_ptr_local = zxc_compress_chunk_wrapper_avx512;

    else if (cpu == ZXC_CPU_AVX2)

        zxc_compress_ptr_local = zxc_compress_chunk_wrapper_avx2;

    else

        zxc_compress_ptr_local = zxc_compress_chunk_wrapper_default;

#elif defined(__arm__) || defined(_M_ARM)

    // cppcheck-suppress knownConditionTrueFalse

    if (cpu == ZXC_CPU_NEON)

        zxc_compress_ptr_local = zxc_compress_chunk_wrapper_neon32;

    else

        zxc_compress_ptr_local = zxc_compress_chunk_wrapper_default;

#else

    (void)cpu;

    zxc_compress_ptr_local = zxc_compress_chunk_wrapper_default;

#endif

#else

    (void)cpu;

    zxc_compress_ptr_local = zxc_compress_chunk_wrapper_default;

#endif

#if ZXC_USE_C11_ATOMICS

    atomic_store_explicit(&zxc_compress_ptr, zxc_compress_ptr_local, memory_order_release);

#else

    zxc_compress_ptr = zxc_compress_ptr_local;

#endif

    return zxc_compress_ptr_local(ctx, src, src_sz, dst, dst_cap);

}

// LCOV_EXCL_STOP

/**

 * @brief Public decompression dispatcher (calls lazily-resolved implementation).

 *

 * @param[in,out] ctx    Decompression context.

 * @param[in]     src    Compressed input chunk (header + payload + optional checksum).

 * @param[in]     src_sz Size of @p src in bytes.

 * @param[out]    dst    Destination buffer for decompressed data.

 * @param[in]     dst_cap Capacity of @p dst.

 * @return Decompressed size in bytes, or a negative @ref zxc_error_t code.

 */

int zxc_decompress_chunk_wrapper(const zxc_cctx_t* RESTRICT ctx, const uint8_t* RESTRICT src,

                                 const size_t src_sz, uint8_t* RESTRICT dst, const size_t dst_cap) {

    /* dict_size is constant for a stream; this per-block branch (outside the decode

     * loop) routes to the dict variant only when a dictionary is active, so the

     * no-dict path runs the dict-free chunk wrapper (identical codegen to main). */

#if ZXC_USE_C11_ATOMICS

    const zxc_decompress_func_t func = atomic_load_explicit(

        ctx->dict_size ? &zxc_decompress_dict_ptr : &zxc_decompress_ptr, memory_order_acquire);

#else

    const zxc_decompress_func_t func =

        ctx->dict_size ? zxc_decompress_dict_ptr : zxc_decompress_ptr;

#endif

    if (UNLIKELY(!func)) return zxc_decompress_dispatch_init(ctx, src, src_sz, dst, dst_cap);

    return func(ctx, src, src_sz, dst, dst_cap);

}

/**

 * @brief Internal safe-decompression dispatcher (strict dst_capacity == uncompressed_size).

 *

 * Calls the lazily-resolved `_safe_*` variant, running first-call init if needed.

 *

 * @param[in]  ctx      Decompression context.

 * @param[in]  src      Compressed input chunk.

 * @param[in]  src_sz   Size of @p src in bytes.

 * @param[out] dst      Destination buffer (capacity == exact uncompressed size).

 * @param[in]  dst_cap  Capacity of @p dst in bytes.

 * @return Decompressed size in bytes, or a negative @ref zxc_error_t.

 */

static int zxc_decompress_chunk_wrapper_safe_public(const zxc_cctx_t* RESTRICT ctx,

                                                    const uint8_t* RESTRICT src,

                                                    const size_t src_sz, uint8_t* RESTRICT dst,

                                                    const size_t dst_cap) {

#if ZXC_USE_C11_ATOMICS

    const zxc_decompress_func_t func =

        atomic_load_explicit(&zxc_decompress_safe_ptr, memory_order_acquire);

#else

    const zxc_decompress_func_t func = zxc_decompress_safe_ptr;

#endif

    if (UNLIKELY(!func)) return zxc_decompress_safe_dispatch_init(ctx, src, src_sz, dst, dst_cap);

    return func(ctx, src, src_sz, dst, dst_cap);

}

/**

 * @brief Public compression dispatcher (calls lazily-resolved implementation).

 *

 * @param[in,out] ctx    Compression context.

 * @param[in]     src    Uncompressed input chunk.

 * @param[in]     src_sz Size of @p src in bytes.

 * @param[out]    dst    Destination buffer for compressed data.

 * @param[in]     dst_cap Capacity of @p dst.

 * @return Compressed size in bytes, or a negative @ref zxc_error_t code.

 */

int zxc_compress_chunk_wrapper(zxc_cctx_t* RESTRICT ctx, const uint8_t* RESTRICT src,

                               const size_t src_sz, uint8_t* RESTRICT dst, const size_t dst_cap) {

#if ZXC_USE_C11_ATOMICS

    const zxc_compress_func_t func = atomic_load_explicit(&zxc_compress_ptr, memory_order_acquire);

#else

    const zxc_compress_func_t func = zxc_compress_ptr;

#endif

    if (UNLIKELY(!func)) return zxc_compress_dispatch_init(ctx, src, src_sz, dst, dst_cap);

    return func(ctx, src, src_sz, dst, dst_cap);

}

/*

 * ============================================================================

 * HUFFMAN TRAMPOLINES

 * ============================================================================

 * The Huffman codec is built per-variant (default / avx2 / avx512, plus neon32

 * on 32-bit ARM)

 * alongside zxc_compress.c and zxc_decompress.c, so the LZ77 stages and the

 * Huffman stage in a given variant share the same ISA flags (e.g. -mbmi2 on

 * the AVX2/AVX512 variants). The compress/decompress variant TUs resolve

 * their Huffman calls to the matching suffixed symbol at compile time, so

 * the production hot path has zero dispatch overhead.

 *

 * These thin wrappers exist only for tests and external callers that link

 * against the un-suffixed names. They forward to the default (scalar) variant.

 */

/**

 * @brief Build length-limited per-symbol Huffman code lengths from frequencies.

 *

 * Un-suffixed entry forwarding to @ref zxc_huf_build_code_lengths_default; full

 * contract in @c zxc_internal.h.

 *

 * @param[in]  freq      Per-symbol frequency counts.

 * @param[out] code_len  Per-symbol code lengths.

 * @param[in]  scratch   Caller-provided build scratch buffer.

 * @return `ZXC_OK` on success, negative `zxc_error_t` on failure.

 */

int zxc_huf_build_code_lengths(const uint32_t* RESTRICT freq, uint8_t* RESTRICT code_len,

                               void* RESTRICT scratch, const int max_code_len) {

    return zxc_huf_build_code_lengths_default(freq, code_len, scratch, max_code_len);

}

/** @brief Un-suffixed forwarders for the PivCo section codec (tests, tools). */

size_t zxc_huf_calc_size(const uint32_t* RESTRICT freq, const uint8_t* RESTRICT code_len,

                         const int with_header) {

    return zxc_huf_calc_size_default(freq, code_len, with_header);

}

int zxc_huf_encode_section(const uint8_t* RESTRICT literals, const size_t n_literals,

                           const uint32_t* RESTRICT freq, const uint8_t* RESTRICT code_len,

                           uint8_t* RESTRICT dst, const size_t dst_cap) {

    return zxc_huf_encode_section_default(literals, n_literals, freq, code_len, dst, dst_cap);

}

int zxc_huf_decode_section(const uint8_t* RESTRICT payload, const size_t payload_size,

                           uint8_t* RESTRICT dst, const size_t n, uint8_t* RESTRICT scratch) {

    return zxc_huf_decode_section_default(payload, payload_size, dst, n, scratch);

}

int zxc_huf_encode_section_dict(const uint8_t* RESTRICT literals, const size_t n_literals,

                                const uint32_t* RESTRICT freq, const uint8_t* RESTRICT code_len,

                                const zxc_pivco_tree_t* RESTRICT tree,

                                const uint32_t* RESTRICT codes, uint8_t* RESTRICT dst,

                                const size_t dst_cap) {

    return zxc_huf_encode_section_dict_default(literals, n_literals, freq, code_len, tree, codes,

                                               dst, dst_cap);

}

int zxc_huf_decode_section_dict(const uint8_t* RESTRICT payload, const size_t payload_size,

                                uint8_t* RESTRICT dst, const size_t n,

                                const zxc_pivco_tree_t* RESTRICT tree,

                                const zxc_pivco_decode_aux_t* RESTRICT aux,

                                uint8_t* RESTRICT scratch) {

    return zxc_huf_decode_section_dict_default(payload, payload_size, dst, n, tree, aux, scratch);

}

size_t zxc_huf_calc_size_dict(const uint32_t* RESTRICT freq, const uint8_t* RESTRICT code_len,

                              const zxc_pivco_tree_t* RESTRICT tree) {

    return zxc_huf_calc_size_dict_default(freq, code_len, tree);

}

/**

 * @brief Pack per-symbol code lengths into the 128-byte nibble header.

 *

 * Un-suffixed entry forwarding to @ref zxc_huf_pack_lengths_default; full

 * contract in @c zxc_internal.h.

 *

 * @param[in]  code_len  Per-symbol code lengths (one byte each).

 * @param[out] out       Destination 128-byte packed header.

 */

void zxc_huf_pack_lengths(const uint8_t* RESTRICT code_len, uint8_t* RESTRICT out) {

    zxc_huf_pack_lengths_default(code_len, out);

}

/**

 * @brief Unpack and validate a 128-byte packed lengths header.

 *

 * Un-suffixed entry forwarding to @ref zxc_huf_unpack_lengths_default; full

 * contract in @c zxc_internal.h.

 *

 * @param[in]  in        128-byte packed lengths header.

 * @param[out] code_len  Destination per-symbol code lengths.

 * @return `ZXC_OK` on success, `ZXC_ERROR_CORRUPT_DATA` on invalid lengths.

 */

int zxc_huf_unpack_lengths(const uint8_t* RESTRICT in, uint8_t* RESTRICT code_len) {

    return zxc_huf_unpack_lengths_default(in, code_len);

}

/*

 * ============================================================================

 * PUBLIC UTILITY API

 * ============================================================================

 * These wrapper functions provide a simplified interface by managing context

 * allocation and looping over blocks. They call the dispatched wrappers above.

 */

/**

 * @brief Compresses an entire buffer in one call.

 *

 * Manages context allocation internally, loops over blocks, writes the

 * file header / EOF block / footer, and accumulates the global checksum.

 *

 * @param[in]  src              Uncompressed input data.

 * @param[in]  src_size         Size of @p src in bytes.

 * @param[out] dst              Destination buffer (use zxc_compress_bound() to size).

 * @param[in]  dst_capacity     Capacity of @p dst.

 * @param[in]  opts             Compression options (level, block size, checksum,

 *                              dictionary, seekable, threads), or NULL for defaults.

 * @return Total compressed size in bytes, or a negative @ref zxc_error_t code.

 */

// cppcheck-suppress unusedFunction

int64_t zxc_compress(const void* RESTRICT src, const size_t src_size, void* RESTRICT dst,

                     const size_t dst_capacity, const zxc_compress_opts_t* opts) {

    if (UNLIKELY(!dst || dst_capacity == 0 || (src_size > 0 && !src))) return ZXC_ERROR_NULL_INPUT;

    const int checksum_enabled = opts ? opts->checksum_enabled : 0;

    const int seekable = opts ? opts->seekable : 0;

    const int level = zxc_level_clamp((opts && opts->level > 0) ? opts->level : ZXC_LEVEL_DEFAULT);

    const size_t block_size =

        (opts && opts->block_size > 0) ? opts->block_size : ZXC_BLOCK_SIZE_DEFAULT;

    const uint8_t* dict = opts ? (const uint8_t*)opts->dict : NULL;

    const size_t dict_size = (opts && opts->dict) ? opts->dict_size : 0;

    const uint8_t* dict_huf = (opts && opts->dict) ? (const uint8_t*)opts->dict_huf : NULL;

    if (UNLIKELY(dict_size > ZXC_DICT_SIZE_MAX)) return ZXC_ERROR_DICT_TOO_LARGE;

    if (UNLIKELY(!zxc_validate_block_size(block_size))) return ZXC_ERROR_BAD_BLOCK_SIZE;

    const uint32_t did = (dict && dict_size > 0) ? zxc_dict_id(dict, dict_size, dict_huf) : 0;

    const uint8_t* ip = (const uint8_t*)src;

    uint8_t* op = (uint8_t*)dst;

    const uint8_t* op_start = op;

    const uint8_t* op_end = op + dst_capacity;

    uint32_t global_hash = 0;

    zxc_cctx_t ctx;

    const size_t eff_chunk =

        dict_size > 0 ? zxc_block_size_ceil(dict_size + block_size) : block_size;

    // LCOV_EXCL_START

    if (UNLIKELY(zxc_cctx_init(&ctx, eff_chunk, 1, level, checksum_enabled, dict_size) != ZXC_OK))

        return ZXC_ERROR_MEMORY;

    // LCOV_EXCL_STOP

    if (UNLIKELY(zxc_cctx_attach_dict_huf(&ctx, dict_huf) != ZXC_OK)) {

        // LCOV_EXCL_START

        zxc_cctx_free(&ctx);

        return ZXC_ERROR_CORRUPT_DATA;

        // LCOV_EXCL_STOP

    }

    /* Dict input buffer: [dict_content | block_data] for the encoder, carved

     * into the cctx workspace (NULL when no dictionary is active). */

    uint8_t* const dict_input = ctx.dict_buffer;

    if (dict_input) ZXC_MEMCPY(dict_input, dict, dict_size);

    const int h_val =

        zxc_write_file_header(op, (size_t)(op_end - op), block_size, checksum_enabled, did);

    // LCOV_EXCL_START

    if (UNLIKELY(h_val < 0)) {

        zxc_cctx_free(&ctx);

        return h_val;

    }

    // LCOV_EXCL_STOP

    op += h_val;

    /* Seekable: dynamic array for per-block compressed sizes */

    uint32_t* seek_comp = NULL;

    uint32_t seek_count = 0;

    uint32_t seek_cap = 0;

    if (seekable) {

        const size_t block_count = src_size / block_size;

        if (UNLIKELY(block_count > (size_t)UINT32_MAX - 2)) {

            // LCOV_EXCL_START

            zxc_cctx_free(&ctx);

            return ZXC_ERROR_BAD_BLOCK_SIZE;

            // LCOV_EXCL_STOP

        }

        seek_cap = (uint32_t)(block_count + 2);

        seek_comp = (uint32_t*)ZXC_MALLOC(seek_cap * sizeof(uint32_t));

        // LCOV_EXCL_START

        if (UNLIKELY(!seek_comp)) {

            zxc_cctx_free(&ctx);

            return ZXC_ERROR_MEMORY;

        }

        // LCOV_EXCL_STOP

    }

    size_t pos = 0;

    while (pos < src_size) {

        const size_t chunk_len = (src_size - pos > block_size) ? block_size : (src_size - pos);

        const size_t rem_cap = (size_t)(op_end - op);

        int res;

        if (dict_input) {

            ZXC_MEMCPY(dict_input + dict_size, ip + pos, chunk_len);

            res = zxc_compress_chunk_wrapper(&ctx, dict_input, dict_size + chunk_len, op, rem_cap);

        } else {

            res = zxc_compress_chunk_wrapper(&ctx, ip + pos, chunk_len, op, rem_cap);

        }

        if (UNLIKELY(res < 0)) {

            ZXC_FREE(seek_comp);

            zxc_cctx_free(&ctx);

            return res;

        }

        if (checksum_enabled) {

            // Update Global Hash (Rotation + XOR)

            // Block checksum is at the end of the written block data

            if (LIKELY(res >= ZXC_GLOBAL_CHECKSUM_SIZE)) {

                const uint32_t block_hash = zxc_le32(op + res - ZXC_GLOBAL_CHECKSUM_SIZE);

                global_hash = zxc_hash_combine_rotate(global_hash, block_hash);

            }

        }

        /* Seekable: record compressed block size */

        if (seekable) {

            // LCOV_EXCL_START

            if (UNLIKELY(seek_count >= seek_cap)) {

                seek_cap = seek_cap * 2;

                uint32_t* nc = (uint32_t*)ZXC_REALLOC(seek_comp, seek_cap * sizeof(uint32_t));

                if (UNLIKELY(!nc)) {

                    ZXC_FREE(seek_comp);

                    zxc_cctx_free(&ctx);

                    return ZXC_ERROR_MEMORY;

                }

                seek_comp = nc;

            }

            // LCOV_EXCL_STOP

            seek_comp[seek_count] = (uint32_t)res;

            seek_count++;

        }

        op += res;

        pos += chunk_len;

    }

    zxc_cctx_free(&ctx);

    // Write EOF Block

    const size_t rem_cap = (size_t)(op_end - op);

    const zxc_block_header_t eof_bh = {

        .block_type = ZXC_BLOCK_EOF, .block_flags = 0, .reserved = 0, .comp_size = 0};

    const int eof_val = zxc_write_block_header(op, rem_cap, &eof_bh);

    // LCOV_EXCL_START

    if (UNLIKELY(eof_val < 0)) {

        ZXC_FREE(seek_comp);

        return eof_val;

    }

    // LCOV_EXCL_STOP

    op += eof_val;

    /* Seekable: write seek table between EOF block and footer */

    if (seekable && seek_count > 0) {

        const size_t st_cap = (size_t)(op_end - op);

        const int64_t st_val = zxc_write_seek_table(op, st_cap, seek_comp, seek_count);

        ZXC_FREE(seek_comp);

        if (UNLIKELY(st_val < 0)) return st_val;  // LCOV_EXCL_LINE

        op += st_val;

    } else {

        ZXC_FREE(seek_comp);

    }

    if (UNLIKELY((size_t)(op_end - op) < ZXC_FILE_FOOTER_SIZE))

        return ZXC_ERROR_DST_TOO_SMALL;  // LCOV_EXCL_LINE

    // Write 12-byte Footer: [Source Size (8)] + [Global Hash (4)]

    const int footer_val =

        zxc_write_file_footer(op, (size_t)(op_end - op), src_size, global_hash, checksum_enabled);

    if (UNLIKELY(footer_val < 0)) return footer_val;  // LCOV_EXCL_LINE

    op += footer_val;

    return (int64_t)(op - op_start);

}

/* Shared frame decode body for zxc_decompress and zxc_decompress_inplace. No

 * RESTRICT between src and dst, so the overlapping case stays defined; the

 * in-place margin still gives each block disjoint regions, and the per-block

 * wrappers keep their own RESTRICT. */

static int64_t zxc_decompress_frame(const uint8_t* src, size_t src_size, uint8_t* dst,

                                    size_t dst_capacity, const zxc_decompress_opts_t* opts);

/**

 * @brief Decompresses an entire buffer in one call.

 *

 * Validates the file header and footer, loops over compressed blocks,

 * and verifies the global checksum when enabled.

 *

 * @param[in]  src              Compressed input data.

 * @param[in]  src_size         Size of @p src in bytes.

 * @param[out] dst              Destination buffer for decompressed data.

 * @param[in]  dst_capacity     Capacity of @p dst.

 * @param[in]  opts             Decompression options (checksum verification,

 *                              dictionary, threads), or NULL for defaults.

 * @return Total decompressed size in bytes, or a negative @ref zxc_error_t code.

 */

// cppcheck-suppress unusedFunction

int64_t zxc_decompress(const void* RESTRICT src, const size_t src_size, void* RESTRICT dst,

                       const size_t dst_capacity, const zxc_decompress_opts_t* opts) {

    if (UNLIKELY(!src || src_size < ZXC_FILE_HEADER_SIZE + ZXC_FILE_FOOTER_SIZE ||

                 (!dst && dst_capacity != 0)))

        return ZXC_ERROR_NULL_INPUT;

    if (UNLIKELY(!dst || dst_capacity == 0)) {

        /* Empty-frame case (stored size == 0). */

        if (UNLIKELY(zxc_le32(src) != ZXC_MAGIC_WORD)) return ZXC_ERROR_NULL_INPUT;

        const uint8_t* footer = (const uint8_t*)src + src_size - ZXC_FILE_FOOTER_SIZE;

        return (zxc_le64(footer) == 0) ? 0 : (int64_t)ZXC_ERROR_DST_TOO_SMALL;

    }

    return zxc_decompress_frame((const uint8_t*)src, src_size, (uint8_t*)dst, dst_capacity, opts);

}

static int64_t zxc_decompress_frame(const uint8_t* src, const size_t src_size, uint8_t* dst,

                                    const size_t dst_capacity, const zxc_decompress_opts_t* opts) {

    const int checksum_enabled = opts ? opts->checksum_enabled : 0;

    const uint8_t* dict = opts ? (const uint8_t*)opts->dict : NULL;

    const size_t dict_size = (opts && opts->dict) ? opts->dict_size : 0;

    const uint8_t* dict_huf = (opts && opts->dict) ? (const uint8_t*)opts->dict_huf : NULL;

    const uint8_t* ip = src;

    const uint8_t* ip_end = ip + src_size;

    uint8_t* op = dst;

    const uint8_t* op_start = op;

    const uint8_t* op_end = op + dst_capacity;

    size_t runtime_chunk_size = 0;

    zxc_cctx_t ctx;

    int file_has_checksums = 0;

    uint32_t header_dict_id = 0;

    if (UNLIKELY(zxc_read_file_header(ip, src_size, &runtime_chunk_size, &file_has_checksums,

                                      &header_dict_id) != ZXC_OK ||

                 zxc_cctx_init(&ctx, runtime_chunk_size, 0, 0,

                               file_has_checksums && checksum_enabled, dict_size) != ZXC_OK)) {

        return ZXC_ERROR_BAD_HEADER;

    }

    /* Dictionary validation */

    if (header_dict_id != 0) {

        if (UNLIKELY(!dict || dict_size == 0)) {

            zxc_cctx_free(&ctx);

            return ZXC_ERROR_DICT_REQUIRED;

        }

        if (UNLIKELY(zxc_dict_id(dict, dict_size, dict_huf) != header_dict_id)) {

            zxc_cctx_free(&ctx);

            return ZXC_ERROR_DICT_MISMATCH;

        }

    }

    if (UNLIKELY(zxc_cctx_attach_dict_huf(&ctx, dict_huf) != ZXC_OK)) {

        // LCOV_EXCL_START

        zxc_cctx_free(&ctx);

        return ZXC_ERROR_CORRUPT_DATA;

        // LCOV_EXCL_STOP

    }

    ip += ZXC_FILE_HEADER_SIZE;

    const size_t work_sz = runtime_chunk_size + ZXC_DECOMPRESS_TAIL_PAD;

    /* Dict decode buffer: [dict_content | decode_space + PAD], carved into the

     * cctx workspace (NULL when no dictionary is active). */

    uint8_t* const dict_dec = ctx.dict_buffer;

    if (dict_dec) ZXC_MEMCPY(dict_dec, dict, dict_size);

    // Block decompression loop

    uint32_t global_hash = 0;

    while (ip < ip_end) {

        const size_t rem_src = (size_t)(ip_end - ip);

        zxc_block_header_t bh;

        // Read the block header to determine the compressed size

        if (UNLIKELY(zxc_read_block_header(ip, rem_src, &bh) != ZXC_OK)) {

            zxc_cctx_free(&ctx);

            return ZXC_ERROR_BAD_HEADER;

        }

        // Handle EOF block separately (not a real chunk to decompress)

        if (UNLIKELY(bh.block_type == ZXC_BLOCK_EOF)) {

            // EOF carries no payload; a non-zero comp_size is a malformed header.

            if (UNLIKELY(bh.comp_size != 0)) {

                zxc_cctx_free(&ctx);

                return ZXC_ERROR_BAD_HEADER;

            }

            // Footer is always the last ZXC_FILE_FOOTER_SIZE bytes of the source,

            // even when a seek table is inserted between EOF block and footer.

            // LCOV_EXCL_START

            if (UNLIKELY(src_size < ZXC_FILE_FOOTER_SIZE)) {

                zxc_cctx_free(&ctx);

                return ZXC_ERROR_SRC_TOO_SMALL;

            }

            // LCOV_EXCL_STOP

            const uint8_t* const footer = src + src_size - ZXC_FILE_FOOTER_SIZE;

            // Validate source size matches what we decompressed

            const uint64_t stored_size = zxc_le64(footer);

            if (UNLIKELY(stored_size != (uint64_t)(op - op_start))) {

                zxc_cctx_free(&ctx);

                return ZXC_ERROR_CORRUPT_DATA;

            }

            // Validate global checksum if enabled and file has checksums

            if (checksum_enabled && file_has_checksums) {

                const uint32_t stored_hash = zxc_le32(footer + sizeof(uint64_t));

                if (UNLIKELY(stored_hash != global_hash)) {

                    zxc_cctx_free(&ctx);

                    return ZXC_ERROR_BAD_CHECKSUM;

                }

            }

            break;  // EOF reached, exit loop

        }

        int res;

        const size_t rem_cap = (size_t)(op_end - op);

        if (dict_dec) {

            /* Dict path: decode into bounce buffer with dict prefix so match

             * copies that reference dict content resolve naturally. */

            res = zxc_decompress_chunk_wrapper(&ctx, ip, rem_src, dict_dec + dict_size, work_sz);

            if (LIKELY(res > 0)) {

                if (UNLIKELY((size_t)res > rem_cap)) {

                    // LCOV_EXCL_START

                    zxc_cctx_free(&ctx);

                    return ZXC_ERROR_DST_TOO_SMALL;

                    // LCOV_EXCL_STOP

                }

                ZXC_MEMCPY(op, dict_dec + dict_size, (size_t)res);

            }

        } else if (LIKELY(rem_cap >= work_sz)) {

            // Fast path: decode directly into dst. Cap dst_cap to chunk_size + PAD

            res = zxc_decompress_chunk_wrapper(&ctx, ip, rem_src, op, work_sz);

        } else {

            // Safe path: decode into bounce buffer, then copy exact result.

            res = zxc_decompress_chunk_wrapper(&ctx, ip, rem_src, ctx.work_buf, ctx.work_buf_cap);

            if (LIKELY(res > 0)) {

                // LCOV_EXCL_START

                if (UNLIKELY((size_t)res > rem_cap)) {

                    zxc_cctx_free(&ctx);

                    return ZXC_ERROR_DST_TOO_SMALL;

                }

                // LCOV_EXCL_STOP

                ZXC_MEMCPY(op, ctx.work_buf, (size_t)res);

            }

        }

        if (UNLIKELY(res < 0)) {

            zxc_cctx_free(&ctx);

            return res;

        }

        // Update global hash from block checksum

        if (checksum_enabled && file_has_checksums) {

            const uint32_t block_hash = zxc_le32(ip + ZXC_BLOCK_HEADER_SIZE + bh.comp_size);

            global_hash = zxc_hash_combine_rotate(global_hash, block_hash);

        }

        ip += ZXC_BLOCK_HEADER_SIZE + bh.comp_size +

              (file_has_checksums ? ZXC_BLOCK_CHECKSUM_SIZE : 0);

        op += res;

    }

    zxc_cctx_free(&ctx);

    return (int64_t)(op - op_start);

}

/**

 * @brief Bytes an in-place decode needs on top of the decompressed size.

 *

 * Flush-right placement puts block 0 at `capacity - comp_size`, so the read

 * cursor before block k sits at `capacity - sum_{j>=k} (c_j + H) - trailing`,

 * and the no-overtake invariant `sum_{j<=k} o_j + PAD <= R_k` requires

 *

 *     capacity >= max_k [ sum_{j<=k} o_j + sum_{j>=k} (c_j + H) ] + PAD + trailing

 *

 * Incompressible input (all RAW, `c_j = o_j`) maximises the bracket at

 * `dsize + chunk_size + nblocks * H`: the margin carries the whole accumulated

 * per-block overhead, not just one block's.

 *

 * `trailing` is everything written after the last data block: EOF header, footer

 * and seek table. The latter is always reserved at its worst case (4 bytes per

 * block, <= 0.1% of the payload) because no header flag announces one; omitting

 * it used to push the bound *below* comp_size for a seekable archive of

 * incompressible data in small blocks.

 *

 * @param[in] dsize      Decompressed size, in bytes.

 * @param[in] chunk_size Block size from the file header (0 = no blocks).

 * @param[in] has_cs     Non-zero if blocks carry checksums.

 * @return Bytes to reserve beyond @p dsize.

 */

static uint64_t zxc_inplace_margin(const uint64_t dsize, const size_t chunk_size,

                                   const int has_cs) {

    const uint64_t nblocks =

        chunk_size ? (dsize + (uint64_t)chunk_size - 1) / (uint64_t)chunk_size : 0;

    const uint64_t per_block =

        (uint64_t)ZXC_BLOCK_HEADER_SIZE + (has_cs ? (uint64_t)ZXC_BLOCK_CHECKSUM_SIZE : 0);

    const uint64_t trailing =

        (uint64_t)ZXC_BLOCK_HEADER_SIZE +  // EOF block header

        ((uint64_t)ZXC_BLOCK_HEADER_SIZE +

         nblocks * (uint64_t)ZXC_SEEK_ENTRY_SIZE) +  // Seek table (worst case)

        (uint64_t)ZXC_FILE_FOOTER_SIZE;

    return (uint64_t)chunk_size + nblocks * per_block + trailing +

           (uint64_t)ZXC_DECOMPRESS_TAIL_PAD;

}

/**

 * @brief Shared archive probe for the in-place entry points: validates the

 *        magic + file header, then reads the footer's decompressed size and

 *        derives the in-place margin.

 *

 * Keeping this parse in one place guarantees @ref zxc_decompress_inplace_bound