OperationStmt.cpp

/*
 * Copyright (c) 2024, Trail of Bits, Inc.
 *
 * This source code is licensed in accordance with the terms specified in
 * the LICENSE file found in the root directory of this source tree.
 */

#include <algorithm>
#include <optional>
#include <string>
#include <utility>

#include <clang/AST/ASTContext.h>
#include <clang/AST/Attr.h>
#include <clang/AST/Decl.h>
#include <clang/AST/DeclAccessPair.h>
#include <clang/AST/Expr.h>
#include <clang/AST/NestedNameSpecifier.h>
#include <clang/AST/OperationKinds.h>
#include <clang/AST/RecordLayout.h>
#include <clang/AST/Stmt.h>
#include <clang/AST/Type.h>
#include <clang/Basic/Builtins.h>
#include <clang/Basic/LLVM.h>
#include <clang/Basic/LangOptions.h>
#include <clang/Basic/SourceLocation.h>
#include <clang/Basic/Specifiers.h>
#include <clang/Sema/Lookup.h>
#include <clang/Sema/Sema.h>
#include <llvm/ADT/APInt.h>
#include <llvm/ADT/ArrayRef.h>
#include <llvm/ADT/SmallVector.h>
#include <llvm/Support/Casting.h>

#include <patchestry/AST/ASTConsumer.hpp>
#include <patchestry/AST/FunctionBuilder.hpp>
#include <patchestry/AST/IntrinsicHandlers.hpp>
#include <patchestry/AST/OperationBuilder.hpp>
#include <patchestry/AST/TypeBuilder.hpp>
#include <patchestry/AST/Utils.hpp>
#include <patchestry/Ghidra/Pcode.hpp>
#include <patchestry/Ghidra/PcodeOperations.hpp>
#include <patchestry/Util/Log.hpp>

namespace patchestry::ast {

    extern std::optional< Operation >
    operationFromKey(const Function &function, const std::string &lookup_key); // NOLINT

    namespace {

        // Simplify *(&expr) → expr.  When PTRADD produces &base[index] and
        // STORE/LOAD dereferences it, this cancels the redundant &/* pair so the
        // output reads base[index] instead of *(&base[index]).
        clang::Expr *simplify_deref_addrof(clang::Expr *expr) {
            if (auto *uo = clang::dyn_cast< clang::UnaryOperator >(expr)) {
                if (uo->getOpcode() == clang::UO_AddrOf) {
                    return uo->getSubExpr();
                }
            }
            return nullptr;
        }

        clang::VarDecl *create_variable_decl( // NOLINT
            clang::ASTContext &ctx, clang::DeclContext *dc, const std::string &name,
            clang::QualType type, clang::SourceLocation loc
        ) {
            auto *vd = clang::VarDecl::Create(
                ctx, dc, loc, loc, &ctx.Idents.get(name), type,
                ctx.getTrivialTypeSourceInfo(type), clang::SC_None
            );
            // CIRGen asserts every VarDecl referenced by a DeclRefExpr is
            // marked used. Patchestry bypasses Sema, so we mark it here.
            vd->setIsUsed();
            return vd;
        }

        clang::DeclStmt *create_decl_stmt( // NOLINT
            clang::ASTContext &ctx, clang::Decl *decl, clang::SourceLocation loc
        ) {
            auto decl_group = clang::DeclGroupRef(decl);
            return new (ctx) clang::DeclStmt(decl_group, loc, loc);
        }

        clang::Expr *createDefaultArgument(clang::ASTContext &ctx, clang::ParmVarDecl *param) {
            if (param == nullptr) {
                return nullptr;
            }

            auto param_type = param->getType();
            if (param_type->isIntegerType()) {
                // param_type may be _Bool/enum (crash StmtPrinter).
                return MakeIntLiteralPrintable(
                    ctx, 0, param_type, param_type->isSignedIntegerType(),
                    VirtualLoc(ctx)
                );
            } else if (param_type->isFloatingType()) {
                llvm::APFloat value(llvm::APFloat::IEEEsingle(), "0.0");
                return clang::FloatingLiteral::Create(
                    ctx, value, false, param_type, VirtualLoc(ctx)
                );
            } else if (param_type->isPointerType()) {
                // IntegerLiteral asserts on non-integer types; emit (T*)0 as
                // CK_NullToPointer over an int-typed 0 instead.  #226.
                auto *zero = new (ctx) clang::IntegerLiteral(
                    ctx, llvm::APInt(ctx.getIntWidth(ctx.IntTy), 0), ctx.IntTy,
                    VirtualLoc(ctx)
                );
                return clang::ImplicitCastExpr::Create(
                    ctx, param_type, clang::CK_NullToPointer, zero,
                    /*BasePath=*/nullptr, clang::VK_PRValue,
                    clang::FPOptionsOverride()
                );
            } else if (param_type->isBooleanType()) {
                return new (ctx)
                    clang::CXXBoolLiteralExpr(true, param_type, VirtualLoc(ctx));
            } else if (param_type->isEnumeralType()) {
                // IntegerLiteral asserts on non-integer types; emit (E)0 as an
                // integral cast over an int-typed 0.
                auto *zero = new (ctx) clang::IntegerLiteral(
                    ctx, llvm::APInt(ctx.getIntWidth(ctx.IntTy), 0), ctx.IntTy,
                    VirtualLoc(ctx)
                );
                return clang::ImplicitCastExpr::Create(
                    ctx, param_type, clang::CK_IntegralCast, zero,
                    /*BasePath=*/nullptr, clang::VK_PRValue, clang::FPOptionsOverride()
                );
            } else {
                LOG(ERROR) << "Failed to create default value for parameter of type '"
                           << param_type.getAsString() << "'\n";
                return nullptr;
            }
        }

        /**
         * Helper function to create a builtin call expression.
         */
        clang::Expr *create_builtin_call(
            const clang::ASTContext &ctx, clang::Sema &sema,
            const clang::Builtin::ID builtin_id, std::vector< clang::Expr * > &args,
            const clang::SourceLocation loc
        ) {
            // Get the builtin name and create a lookup result
            const auto name = ctx.BuiltinInfo.getName(builtin_id);
            const clang::LookupResult r(
                sema, &ctx.Idents.get(name), loc, clang::Sema::LookupOrdinaryName
            );
            auto *II = r.getLookupName().getAsIdentifierInfo();

            // Get the builtin type
            clang::ASTContext::GetBuiltinTypeError error{};
            const auto ty = ctx.GetBuiltinType(builtin_id, error);
            assert(!error && "Failed to get builtin type");

            // Create the builtin declaration
            auto *builtin_decl = sema.CreateBuiltin(II, ty, builtin_id, loc);

            // Create a DeclRefExpr for the builtin. ctx is const here, so we
            // can't allocate a virtual buffer; reuse the caller-provided loc
            // which is already valid by contract.
            auto *decl_ref = clang::DeclRefExpr::Create(
                ctx, clang::NestedNameSpecifierLoc(), loc, builtin_decl,
                false, loc, builtin_decl->getType(), clang::VK_PRValue
            );

            // Build the call expression
            auto result = sema.BuildCallExpr(nullptr, decl_ref, loc, args, loc);
            assert(!result.isInvalid() && "Failed to build builtin call expr");

            return result.getAs< clang::Expr >();
        }

        /**
         * @brief Look up or create an opaque external function placeholder in the TU.
         *
         * Used by create_userdefined to emit a best-effort call expression that
         * preserves operation inputs for downstream analysis.
         *
         * @param fn_name     Name of the placeholder function.
         * @param ret_type    Return type of the placeholder.
         * @param param_types Parameter types; must be non-empty (variadic with zero
         *                    fixed params violates "prototyped function must have at
         *                    least one non-variadic input").
         * @param op_loc      Source location for the declaration.
         */
        clang::FunctionDecl *lookup_or_create_opaque_fn( // NOLINT
            clang::ASTContext &ctx, const std::string &fn_name, clang::QualType ret_type,
            llvm::ArrayRef< clang::QualType > param_types, clang::SourceLocation op_loc
        ) {
            auto &ident = ctx.Idents.get(fn_name);
            auto lookup_result =
                ctx.getTranslationUnitDecl()->lookup(clang::DeclarationName(&ident));
            for (auto *d : lookup_result) {
                if (auto *fd = llvm::dyn_cast< clang::FunctionDecl >(d)) {
                    return fd;
                }
            }

            // Ensure at least one non-variadic param (LLVM/CIR requirement)
            llvm::SmallVector< clang::QualType, 4 > params(param_types.begin(), param_types.end());
            if (params.empty()) {
                params.push_back(ctx.VoidPtrTy);
            }

            clang::FunctionProtoType::ExtProtoInfo epi;
            epi.Variadic = false;
            auto fn_type = ctx.getFunctionType(ret_type, params, epi);

            auto *fn_decl = clang::FunctionDecl::Create(
                ctx, ctx.getTranslationUnitDecl(), op_loc, op_loc,
                clang::DeclarationName(&ident), fn_type,
                ctx.getTrivialTypeSourceInfo(fn_type), clang::SC_Extern
            );
            fn_decl->setDeclContext(ctx.getTranslationUnitDecl());
            ctx.getTranslationUnitDecl()->addDecl(fn_decl);
            return fn_decl;
        }

        // Bind a Stmt* to an Expr*, logging and returning nullptr on
        // null/non-Expr. Avoids `clang::dyn_cast<>(nullptr)`, which asserts.
        // Use the `AS_EXPR_OR_NULL` macro at call sites — it captures
        // `__FUNCTION__` at the caller, which a default argument cannot.
        inline clang::Expr *as_expr_or_null(
            clang::Stmt *stmt, const char *op_label, const std::string &key
        ) {
            if (!stmt) {
                LOG(ERROR) << op_label << ": varnode produced null Stmt. key: " << key;
                return nullptr;
            }
            auto *expr = clang::dyn_cast< clang::Expr >(stmt);
            if (!expr) {
                LOG(ERROR) << op_label << ": varnode is not an Expr. key: " << key;
                return nullptr;
            }
            return expr;
        }

    } // namespace

// Caller-context wrapper: `__FUNCTION__` expands at the call site so the
// log line names the enclosing OpBuilder::create_*, which is impossible
// to achieve with a default argument (it would name as_expr_or_null itself).
#define AS_EXPR_OR_NULL(stmt, key) as_expr_or_null((stmt), __FUNCTION__, (key))

    /**
     * Performs an implicit and explicit cast of an expression to a specified type,
     * falling back to a manual pointer-based cast if necessary.
     */
    clang::Expr *OpBuilder::make_cast(
        clang::ASTContext &ctx, clang::Expr *expr, const clang::QualType &to_type,
        clang::SourceLocation loc
    ) {
        if (expr == nullptr || to_type.isNull()) {
            LOG(ERROR) << "Invalid expr of type to perform explicit cast";
            return {};
        }

        auto from_type = expr->getType();
        if (ctx.hasSameUnqualifiedType(from_type, to_type)) {
            return expr;
        }

        // Widen a sub-pointer-width integer to uintptr first so the final
        // int->pointer cast is width-exact (avoids -Wint-to-pointer-cast).
        if (to_type->isPointerType() && from_type->isIntegerType()) {
            auto uintptr_ty = ctx.getUIntPtrType();
            if (ctx.getTypeSize(from_type) < ctx.getTypeSize(uintptr_ty)) {
                expr = make_cast(ctx, expr, uintptr_ty, loc);
                if (!expr) {
                    return nullptr;
                }
                from_type = expr->getType();
            }
        }

        // CIRGen's emitCallee rejects implicit BitCast on a callee;
        // emit an explicit CStyleCastExpr instead.
        if (to_type->isPointerType()
            && to_type->getPointeeType()->isFunctionType())
        {
            auto *cast_expr = make_explicit_cast(ctx, expr, to_type, loc);
            if (cast_expr) return cast_expr;
        }

        // When casting from an array type (e.g. string literal const char[N]) to a
        // pointer type, apply array-to-pointer decay first.
        if (from_type->isArrayType() && to_type->isPointerType()) {
            auto decayed = ctx.getDecayedType(from_type);
            expr = make_implicit_cast(
                ctx, expr, decayed, clang::CastKind::CK_ArrayToPointerDecay
            );
            if (expr) {
                from_type = expr->getType();
                if (ctx.hasSameUnqualifiedType(from_type, to_type)) {
                    return expr;
                }
            }
        }

        // Note: The exported high-pcode from ghidra may have types that can't be casted causing
        // diagnostics errors. For example:
        //   unsigned int -> struct
        //   void* -> struct
        //   struct -> unsigned int
        //   struct -> void*
        // Identify such cases early and make expression doing reinterpret cast.
        if (ShouldReinterpretCast(from_type, to_type)) {
            auto *cast_expr = make_reinterpret_cast(ctx, expr, to_type, loc);
            assert(cast_expr != nullptr && "Failed to create cast expression");
            return cast_expr;
        }

        if (expr->isPRValue()) {
            auto *cast_expr =
                make_implicit_cast(ctx, expr, to_type, GetCastKind(ctx, from_type, to_type));
            if (cast_expr != nullptr) {
                return cast_expr;
            }
        } else {
            auto *cast_expr = make_explicit_cast(ctx, expr, to_type, loc);
            if (cast_expr != nullptr) {
                return cast_expr;
            }
        }

        // For pointer-to-pointer casts (e.g. const char * → unsigned char *),
        // prefer a C-style cast over the reinterpret_cast pattern which produces
        // the ugly *(T**)&expr form.
        if (from_type->isPointerType() && to_type->isPointerType()) {
            return make_explicit_cast(ctx, expr, to_type, loc);
        }

        // Fallback to reinterpret cast like expression
        return make_reinterpret_cast(ctx, expr, to_type, loc);
    }

    clang::Expr *OpBuilder::make_explicit_cast(
        clang::ASTContext &ctx, clang::Expr *expr, clang::QualType to_type,
        clang::SourceLocation loc
    ) {
        auto cast =
            sema().BuildCStyleCastExpr(loc, ctx.getTrivialTypeSourceInfo(to_type), loc, expr);
        if (cast.isInvalid()) {
            LOG(ERROR) << "make_explicit_cast failed\n";
            return nullptr;
        }
        return cast.getAs< clang::Expr >();
    }

    clang::Expr *OpBuilder::make_implicit_cast(
        clang::ASTContext &ctx, clang::Expr *expr, clang::QualType to_type, clang::CastKind kind
    ) {
        if (expr == nullptr || to_type.isNull()) {
            LOG(ERROR) << "Invalid arguments: "
                       << (!expr ? "null expression" : "null target type");
            return nullptr;
        }

        if (!expr->isPRValue()) {
            switch (kind) {
                default:
                    LOG_FATAL(
                        "can't implicitly cast glvalue to prvalue with cast kind: {0}",
                        clang::CastExpr::getCastKindName(kind)
                    );
                case clang::CastKind::CK_Dependent:
                case clang::CastKind::CK_LValueToRValue:
                case clang::CastKind::CK_ArrayToPointerDecay:
                case clang::CastKind::CK_FunctionToPointerDecay:
                case clang::CastKind::CK_ToVoid:
                case clang::CastKind::CK_NonAtomicToAtomic:
                    break;
            }
        }

        // Handle CK_LValueToRValue differently because sema function does not do anything
        // if SrcTy and DestTy is same.
        if (kind == clang::CastKind::CK_LValueToRValue) {
            return clang::ImplicitCastExpr::Create(
                ctx, expr->getType(), clang::CastKind::CK_LValueToRValue, expr, nullptr,
                clang::VK_PRValue, sema().CurFPFeatureOverrides()
            );
        }

        auto result = sema().ImpCastExprToType(expr, to_type, kind);
        if (result.isInvalid()) {
            LOG(WARNING) << "make_implicit_cast failed, returning original expr\n";
            return expr;
        }
        return result.getAs< clang::Expr >();
    }

    clang::Expr *OpBuilder::make_reinterpret_cast(
        clang::ASTContext &ctx, clang::Expr *expr, clang::QualType to_type,
        clang::SourceLocation loc
    ) {
        if (expr == nullptr || to_type.isNull()) {
            LOG(ERROR) << "Invalid expr of type to perform reinterpret cast\n";
            return nullptr;
        }

        auto create_temporary_expr = [&](clang::ASTContext &ctx,
                                         clang::Expr *expr) -> clang::Expr * {
            if (expr->isPRValue()) {
                return sema().CreateMaterializeTemporaryExpr(expr->getType(), expr, true);
            }
            return expr;
            (void) ctx;
        };

        // A function designator (e.g. a VARNODE_FUNCTION operand used as a
        // value) has function type and cannot be materialized or addressed as
        // an object — doing so builds a function-typed lvalue temporary that
        // classifies as CL_Function and aborts CheckAddressOfOperand. Apply the
        // C function-to-pointer decay so we reinterpret the function *pointer*.
        if (expr->getType()->isFunctionType()) {
            expr = clang::ImplicitCastExpr::Create(
                ctx, ctx.getPointerType(expr->getType()),
                clang::CK_FunctionToPointerDecay, expr, /*BasePath=*/nullptr,
                clang::VK_PRValue, clang::FPOptionsOverride()
            );
        }

        auto *temp_expr  = create_temporary_expr(ctx, expr);
        auto addrof_expr = sema().CreateBuiltinUnaryOp(loc, clang::UO_AddrOf, temp_expr);
        if (addrof_expr.isInvalid()) {
            LOG(ERROR) << "make_reinterpret_cast: failed to create AddressOf expression\n";
            return nullptr;
        }

        auto to_pointer_type = ctx.getPointerType(to_type);
        auto casted_expr     = sema().BuildCStyleCastExpr(
            loc, ctx.getTrivialTypeSourceInfo(to_pointer_type), loc,
            addrof_expr.getAs< clang::Expr >()
        );
        if (casted_expr.isInvalid()) {
            LOG(ERROR) << "make_reinterpret_cast: failed to create CStyleCast expression\n";
            return nullptr;
        }

        auto deref_expr = sema().CreateBuiltinUnaryOp(
            loc, clang::UO_Deref, casted_expr.getAs< clang::Expr >()
        );
        if (deref_expr.isInvalid()) {
            LOG(ERROR) << "make_reinterpret_cast: failed to create Deref expression\n";
            return nullptr;
        }

        return deref_expr.getAs< clang::Expr >();
    }

    clang::Expr *OpBuilder::cast_pointer_to_int(
        clang::ASTContext &ctx, clang::Expr *ptr, clang::QualType target,
        clang::SourceLocation loc, PtrToIntExtension kind, std::string_view op_key
    ) {
        assert(ptr != nullptr && ptr->getType()->isPointerType()
               && "cast_pointer_to_int: requires a non-null pointer-typed expression");

        switch (kind) {
            case PtrToIntExtension::kZero: {
                // (target)ptr lowers to ptrtoint+zext — matches INT_ZEXT.
                auto *r = make_explicit_cast(ctx, ptr, target, loc);
                if (!r) {
                    LOG(ERROR) << "cast_pointer_to_int (zext): failed to cast to "
                               << target.getAsString() << ". key: " << op_key << "\n";
                }
                return r;
            }
            case PtrToIntExtension::kSign: {
                // (target)(intptr_t)(uintptr_t)ptr — forces sext at the widening
                // step.  A single (target)ptr would lower as ptrtoint+zext.
                auto *r = make_explicit_cast(ctx, ptr, ctx.getUIntPtrType(), loc);
                if (r) r = make_explicit_cast(ctx, r, ctx.getIntPtrType(), loc);
                if (r) r = make_explicit_cast(ctx, r, target, loc);
                if (!r) {
                    LOG(ERROR) << "cast_pointer_to_int (sext): failed to cast through "
                                  "intptr_t to " << target.getAsString()
                               << ". key: " << op_key << "\n";
                }
                return r;
            }
        }
        LOG_FATAL("cast_pointer_to_int: unhandled PtrToIntExtension value");
    }

    // INT_ZEXT/INT_SEXT produce integers, but Ghidra sometimes types the result
    // as a same-width record (e.g. a one-field `struct CRC32`); casting an
    // int/enum to it hard-fails Sema. Substitute a same-width unsigned integer
    // when the target is not arithmetic/pointer; the write side reinterprets
    // back to the record if needed. (Serializer #250 demotion also fixes this at
    // the source; this keeps already-captured JSON working.)
    clang::QualType OpBuilder::integer_target_for_int_ext(
        clang::ASTContext &ctx, clang::QualType target_type, unsigned op_bytes
    ) {
        if (target_type.isNull()) {
            return target_type;
        }
        if (target_type->isIntegerType() || target_type->isPointerType()
            || target_type->isEnumeralType() || target_type->isBooleanType())
        {
            return target_type;
        }
        unsigned bits = op_bytes ? op_bytes * 8u
                                 : static_cast< unsigned >(ctx.getTypeSize(target_type));
        auto widened = ctx.getIntTypeForBitwidth(bits, /*Signed=*/false);
        return widened.isNull() ? target_type : widened;
    }

    clang::Expr *OpBuilder::narrow_aggregate_to_integer(
        clang::ASTContext &ctx, clang::Expr *expr, clang::SourceLocation loc,
        unsigned target_bytes
    ) {
        if (!expr) {
            return nullptr;
        }
        auto from_type = expr->getType();
        if (!from_type->isRecordType() && !from_type->isArrayType()) {
            return nullptr;
        }

        auto storage_bits = static_cast< unsigned >(ctx.getTypeSize(from_type));

        // Prefer `expr[0]` over a whole-aggregate reinterpret when the
        // target width is exactly one element.  Require the array to have
        // at least one element so the literal `0` index is in-bounds.
        if (target_bytes != 0 && from_type->isArrayType()) {
            if (const auto *array_type = ctx.getAsArrayType(from_type)) {
                auto elem_type = array_type->getElementType();
                auto elem_bits = static_cast< unsigned >(ctx.getTypeSize(elem_type));
                if (elem_type->isIntegerType() && elem_bits == target_bytes * 8u
                    && elem_bits > 0 && storage_bits >= elem_bits)
                {
                    auto *zero = clang::IntegerLiteral::Create(
                        ctx,
                        llvm::APInt(ctx.getIntWidth(ctx.IntTy), 0),
                        ctx.IntTy, loc);
                    auto subscript = sema().CreateBuiltinArraySubscriptExpr(
                        expr, loc, zero, loc);
                    if (!subscript.isInvalid()) {
                        return subscript.getAs< clang::Expr >();
                    }
                }
            }
        }

        // Reinterpret-cast fallback at `target_bytes` (or the aggregate's
        // full size when target_bytes == 0).  Refuse when the requested
        // width exceeds the storage — `*(uintN_t*)&arr` would over-read
        // past the aggregate.  Caller should loud-refuse instead.
        auto size_bits = (target_bytes != 0)
            ? target_bytes * 8u
            : storage_bits;
        if (storage_bits > 0 && size_bits > storage_bits) {
            return nullptr;
        }
        clang::QualType int_type;
        switch (size_bits) {
            case 8:   int_type = ctx.UnsignedCharTy; break;
            case 16:  int_type = ctx.UnsignedShortTy; break;
            case 32:  int_type = ctx.UnsignedIntTy; break;
            case 64:  int_type = ctx.UnsignedLongLongTy; break;
            case 128:
                if (!ctx.UnsignedInt128Ty.isNull()) {
                    int_type = ctx.UnsignedInt128Ty;
                    break;
                }
                [[fallthrough]];
            default:
                return nullptr;
        }
        return make_reinterpret_cast(ctx, expr, int_type, loc);
    }

    // Coerce a record (struct/union) typed expression to an unsigned integer of
    // the same byte size so that it can participate in C arithmetic / bitwise
    // operations.  Returns the expression unchanged if it is not a record type.
    clang::Expr *OpBuilder::coerce_record_to_integer(
        clang::ASTContext &ctx, clang::Expr *expr, clang::SourceLocation loc,
        bool quiet_oversized
    ) {
        if (!expr || !expr->getType()->isRecordType()) {
            return expr;
        }
        auto size_bits = ctx.getTypeSize(expr->getType());
        clang::QualType int_type;
        if (size_bits <= 8) {
            int_type = ctx.UnsignedCharTy;
        } else if (size_bits <= 16) {
            int_type = ctx.UnsignedShortTy;
        } else if (size_bits <= 32) {
            int_type = ctx.UnsignedIntTy;
        } else if (size_bits <= 64) {
            int_type = ctx.UnsignedLongLongTy;
        } else if (size_bits <= 128 && !ctx.UnsignedInt128Ty.isNull()) {
            int_type = ctx.UnsignedInt128Ty;
        } else {
            // Too wide for any integer type — return unchanged. Callers that
            // don't need a scalar (e.g. ADDRESS_OF) pass quiet_oversized to mute
            // the otherwise-misleading warning.
            if (!quiet_oversized) {
                LOG(WARNING) << "coerce_record_to_integer: record is " << size_bits
                             << " bits, too large for integer coercion\n";
            }
            return expr;
        }
        return make_reinterpret_cast(ctx, expr, int_type, loc);
    }

    std::pair< clang::Stmt *, bool > OpBuilder::materialize_call_return(
        clang::ASTContext &ctx, clang::Expr *call_expr,
        clang::QualType ret_type, const Operation &op,
        clang::SourceLocation loc
    ) {
        auto var_name = "__call_ret_"
            + std::to_string(function_builder().call_ret_counter++);
        auto *var_decl = create_variable_decl(
            ctx, sema().CurContext, var_name, ret_type, loc);
        var_decl->setIsUsed();
        sema().CurContext->addDecl(var_decl);

        // Bare DeclStmt pushed to pending (will be hoisted with other decls)
        auto *decl_stmt = create_decl_stmt(ctx, var_decl, loc);
        function_builder().pending_materialized.push_back(decl_stmt);

        // Assignment: __call_ret_N = call_expr  (stays in-place)
        auto *ref = clang::DeclRefExpr::Create(
            ctx, clang::NestedNameSpecifierLoc(), clang::SourceLocation(),
            var_decl, false, loc, ret_type, clang::VK_LValue);
        auto *assign = create_assign_operation(ctx, call_expr, ref, loc);

        if (op.has_return_value.value_or(false)) {
            // Downstream op will consume via create_temporary.
            // Cache a DeclRefExpr so the consumer gets the temp var.
            auto *ref2 = clang::DeclRefExpr::Create(
                ctx, clang::NestedNameSpecifierLoc(), clang::SourceLocation(),
                var_decl, false, loc, ret_type, clang::VK_LValue);
            function_builder().operation_stmts.emplace(op.key, ref2);
            return std::make_pair(assign, false);
        }

        // No downstream consumer — emit assignment + (void)cast.
        auto *ref2 = clang::DeclRefExpr::Create(
            ctx, clang::NestedNameSpecifierLoc(), clang::SourceLocation(),
            var_decl, false, loc, ret_type, clang::VK_LValue);
        auto *void_cast = clang::CStyleCastExpr::Create(
            ctx, ctx.VoidTy, clang::VK_PRValue, clang::CK_ToVoid, ref2,
            nullptr, clang::FPOptionsOverride(),
            ctx.CreateTypeSourceInfo(ctx.VoidTy), loc, loc);
        function_builder().pending_materialized.push_back(assign);
        return std::make_pair(clang::dyn_cast< clang::Stmt >(void_cast), false);
    }

    clang::Stmt *OpBuilder::create_assign_operation(
        clang::ASTContext &ctx, clang::Expr *input_expr, clang::Expr *output_expr,
        clang::SourceLocation loc
    ) {
        if ((input_expr == nullptr) || (output_expr == nullptr)) {
            return {};
        }
        if (loc.isInvalid()) loc = VirtualLoc(ctx);

        clang::QualType input_type  = input_expr->getType();
        clang::QualType output_type = output_expr->getType();

        // A function designator is not an assignable lvalue (e.g. a
        // VARNODE_FUNCTION used as a store target).  Attempting `func = value`
        // makes CreateBuiltinBinOp emit a hard "expression is not assignable"
        // diagnostic that poisons codegen; bail loudly instead.
        if (output_type->isFunctionType()) {
            LOG(ERROR) << "create_assign_operation: assignment target has function "
                          "type '" << output_type.getAsString()
                       << "'; dropping non-assignable store\n";
            return nullptr;
        }

        // Scalar → array: lower as a pointer-cast partial store
        // `*(input_type *)&output[0] = input`.  Width-agnostic — the
        // overflow case (input wider than buffer) is preserved
        // faithfully for downstream transform passes.
        const bool output_is_array = output_type->isArrayType();
        const bool input_is_array  = input_type->isArrayType();
        if (output_is_array && !input_is_array
            && !ctx.hasSameUnqualifiedType(input_type, output_type)) {
            const auto *array_type = ctx.getAsArrayType(output_type);
            if (array_type != nullptr
                && (input_type->isIntegerType() || input_type->isPointerType())
                && ctx.getTypeSize(input_type) > 0)
            {
                auto elem_type = array_type->getElementType();
                auto *zero     = clang::IntegerLiteral::Create(
                    ctx,
                    llvm::APInt(ctx.getIntWidth(ctx.IntTy), 0),
                    ctx.IntTy, loc);
                auto subscript_res = sema().CreateBuiltinArraySubscriptExpr(
                    output_expr, loc, zero, loc);
                if (!subscript_res.isInvalid()) {
                    auto *first_elem = subscript_res.getAs< clang::Expr >();
                    if (first_elem != nullptr) {
                        // When the scalar exactly fills one element, emit a clean
                        // element assignment `output[0] = (elem)input` — what
                        // Ghidra's own HighVariable model recovers.  Otherwise the
                        // scalar is wider/narrower than the element, so fall back
                        // to a width-faithful pointer-cast partial store
                        // `*(input_type *)&output[0] = input`, which preserves the
                        // exact byte width (and any overflow into following
                        // elements) for downstream transform passes.
                        clang::Expr *lhs = first_elem;
                        clang::Expr *rhs = input_expr;
                        // The clean `output[0] = (elem)input` form is only valid
                        // when the element is a scalar.  For an aggregate element
                        // (e.g. a 2-D array or array-of-struct), `output[0]` is an
                        // array/record lvalue that cannot take a scalar assignment,
                        // so keep the width-faithful reinterpret partial store.
                        if (ctx.getTypeSize(input_type) == ctx.getTypeSize(elem_type)
                            && elem_type->isScalarType()) {
                            if (!ctx.hasSameUnqualifiedType(input_type, elem_type)) {
                                rhs = make_cast(ctx, input_expr, elem_type, loc);
                            }
                        } else {
                            lhs = make_reinterpret_cast(ctx, first_elem, input_type, loc);
                        }
                        if (lhs != nullptr && rhs != nullptr) {
                            auto assign_res = sema().CreateBuiltinBinOp(
                                loc, clang::BO_Assign, lhs, rhs);
                            if (!assign_res.isInvalid()) {
                                return assign_res.getAs< clang::Stmt >();
                            }
                        }
                    }
                }
            }

            // Residual: AST construction failed.  Real diag so
            // diag_errors bumps and main aborts codegen.
            auto &diags      = sema().getDiagnostics();
            unsigned diag_id = diags.getCustomDiagID(
                clang::DiagnosticsEngine::Error,
                "create_assign_operation: scalar→array lowering failed "
                "for '%0' → '%1'");
            diags.Report(loc, diag_id)
                << input_type.getAsString()
                << output_type.getAsString();
            return nullptr;
        }

        // Handle exact type match: no cast required
        if (ctx.hasSameUnqualifiedType(input_type, output_type)) {
            // Array types are not directly assignable in C; use element-wise copy
            if (output_type->isArrayType() || output_type->isConstantArrayType()) {
                return create_array_assignment_operation(ctx, input_expr, output_expr, loc);
            }
            auto assign_operation =
                sema().CreateBuiltinBinOp(loc, clang::BO_Assign, output_expr, input_expr);
            assert(!assign_operation.isInvalid());
            return assign_operation.getAs< clang::Stmt >();
        }

        // When the input is a string literal (array type) being assigned to a
        // pointer, apply array-to-pointer decay first.
        if (clang::isa< clang::StringLiteral >(input_expr)
            && input_type->isArrayType() && output_type->isPointerType()) {
            auto decayed = ctx.getDecayedType(input_type);
            auto *decayed_expr = make_implicit_cast(
                ctx, input_expr, decayed, clang::CastKind::CK_ArrayToPointerDecay
            );
            if (decayed_expr) {
                input_expr = decayed_expr;
                input_type = input_expr->getType();
            }
        }

        auto *cast_expr = make_cast(ctx, input_expr, output_type, loc);
        assert(cast_expr != nullptr && "Failed to create cast expressions!");

        if (output_type->isArrayType() || output_type->isConstantArrayType()) {
            return create_array_assignment_operation(ctx, cast_expr, output_expr, loc);
        }

        auto assign_operation =
            sema().CreateBuiltinBinOp(loc, clang::BO_Assign, output_expr, cast_expr);

        assert(!assign_operation.isInvalid());
        return assign_operation.getAs< clang::Stmt >();
    }

    clang::Stmt *OpBuilder::create_array_assignment_operation(
        clang::ASTContext &ctx, clang::Expr *input_expr, clang::Expr *output_expr,
        clang::SourceLocation loc
    ) {
        if ((input_expr == nullptr) || (output_expr == nullptr)) {
            return nullptr;
        }
        if (loc.isInvalid()) loc = VirtualLoc(ctx);

        auto to_type      = output_expr->getType();
        auto *elem_type   = to_type->getPointeeOrArrayElementType();
        auto num_elements = ctx.getTypeSize(to_type) / ctx.getTypeSize(elem_type);
        clang::SmallVector< clang::Stmt *, 4 > body;

        auto *index = clang::VarDecl::Create(
            ctx, sema().CurContext, loc, loc, &ctx.Idents.get("i"), ctx.IntTy, nullptr,
            clang::SC_None
        );
        index->setIsUsed();

        auto *index_init = clang::IntegerLiteral::Create(
            ctx, llvm::APInt(static_cast< unsigned >(ctx.getTypeSize(ctx.IntTy)), 0), ctx.IntTy,
            loc
        );
        index->setInit(index_init);
        auto *index_decl = new (ctx) clang::DeclStmt(clang::DeclGroupRef(index), loc, loc);

        auto *index_ref = clang::DeclRefExpr::Create(
            ctx, clang::NestedNameSpecifierLoc(), clang::SourceLocation(), index, false,
            VirtualLoc(ctx), index->getType(), clang::VK_LValue
        );

        auto *cond_expr = sema()
                              .BuildBinOp(
                                  sema().getCurScope(), loc, clang::BO_LT, index_ref,
                                  clang::IntegerLiteral::Create(
                                      ctx, llvm::APInt(32, num_elements), ctx.IntTy, loc
                                  )
                              )
                              .get();

        auto *inc_expr =
            sema().BuildUnaryOp(sema().getCurScope(), loc, clang::UO_PreInc, index_ref).get();

        // Array assignment: LHS[i] = RHS[i];
        auto *lhs_expr =
            sema().CreateBuiltinArraySubscriptExpr(output_expr, loc, index_ref, loc).get();

        auto *rhs_expr =
            sema().CreateBuiltinArraySubscriptExpr(input_expr, loc, index_ref, loc).get();

        auto *assign_expr =
            sema()
                .BuildBinOp(sema().getCurScope(), loc, clang::BO_Assign, lhs_expr, rhs_expr)
                .get();

        // Wrap assignment in a CompoundStmt (loop body)
        body.push_back(assign_expr);
        auto *loop_body =
            clang::CompoundStmt::Create(ctx, body, sema().CurFPFeatureOverrides(), loc, loc);

        // Set the condVar to nullptr to avoid redeclaration. The ForStmt redeclare the
        // conditional stmt causing conflit with init stmt.
        return new (ctx) clang::ForStmt(
            ctx, index_decl, cond_expr, nullptr, inc_expr, loop_body, loc, loc, loc
        );
    }

    std::optional< clang::QualType > OpBuilder::lookup_op_type(const Operation &op) {
        if (!op.type.has_value()) {
            LOG(ERROR) << "Operation missing type field. key: " << op.key;
            return std::nullopt;
        }
        auto it = type_builder().GetSerializedTypes().find(*op.type);
        if (it == type_builder().GetSerializedTypes().end()) {
            LOG(ERROR) << "Operation type not found in serialized types. key: " << op.key;
            return std::nullopt;
        }
        return it->second;
    }

    std::pair< clang::Stmt *, bool > OpBuilder::create_copy(
        clang::ASTContext &ctx, const Function &function, const Operation &op
    ) {
        if (op.inputs.empty()) {
            LOG(ERROR) << "Copy operation does not have input operand. key: " << op.key << "\n";
            return { nullptr, false };
        }

        auto *input_expr =
            AS_EXPR_OR_NULL(create_varnode(ctx, function, op.inputs.front()), op.key);
        if (!input_expr) {
            return { nullptr, false };
        }

        if (!op.output) {
            // if copy operation has no output, return input expression that will get merged
            // to next operation.
            return { input_expr, true };
        }

        auto *output_expr =
            AS_EXPR_OR_NULL(create_varnode(ctx, function, *op.output), op.key);
        if (!output_expr) {
            return { nullptr, false };
        }

        return { create_assign_operation(
                     ctx, input_expr, output_expr,
                     SourceLocation(ctx.getSourceManager(), op.key)
                 ),
                 false };
    }

    std::pair< clang::Stmt *, bool > OpBuilder::create_load(
        clang::ASTContext &ctx, const Function &function, const Operation &op
    ) {
        if (op.inputs.empty()) {
            LOG(ERROR) << "Load operation with no input operand. key: " << op.key << "\n";
            return { nullptr, false };
        }

        auto merge_to_next = !op.output.has_value();
        auto *input_expr =
            AS_EXPR_OR_NULL(create_varnode(ctx, function, op.inputs[0]), op.key);
        if (!input_expr) {
            return { nullptr, false };
        }

        auto op_loc = SourceLocation(ctx.getSourceManager(), op.key);

        // When the input is a string literal, the LOAD is semantically a no-op:
        // the string literal already IS the value.  Just let it decay from its
        // array type (const char[N]) to a pointer (const char *) via the standard
        // array-to-pointer implicit cast, avoiding the *(T**)&"..." pattern that
        // make_reinterpret_cast would otherwise produce.
        if (clang::isa< clang::StringLiteral >(input_expr)) {
            clang::Expr *result_expr = make_implicit_cast(
                ctx, input_expr, ctx.getDecayedType(input_expr->getType()),
                clang::CastKind::CK_ArrayToPointerDecay
            );
            if (!result_expr) {
                result_expr = input_expr;
            }
            if (merge_to_next) {
                return { result_expr, true };
            }
            auto *output_expr =
                AS_EXPR_OR_NULL(create_varnode(ctx, function, *op.output), op.key);
            if (!output_expr) {
                return { nullptr, false };
            }
            return { create_assign_operation(ctx, result_expr, output_expr, op_loc), false };
        }

        if (op.type) {
            auto op_type_opt = lookup_op_type(op);
            if (!op_type_opt) {
                return {};
            }
            auto pointer_type = ctx.getPointerType(*op_type_opt);
            auto *cast_expr   = make_cast(ctx, input_expr, pointer_type, op_loc);
            if (!cast_expr) {
                LOG(ERROR) << "Failed to make cast expression for LOAD. key: " << op.key;
                return {};
            }
            input_expr = cast_expr;
        }

        // Dereferencing a void* is ill-formed in C.  When no explicit op.type cast has been
        // applied above and the pointer is still void*, cast it to the output varnode's type
        // (if known) or uint8_t* as a last resort.
        if (input_expr->getType()->isVoidPointerType()) {
            clang::QualType pointee = op.output.has_value()
                                          ? get_varnode_type(ctx, *op.output)
                                          : ctx.UnsignedCharTy;
            input_expr = make_cast(ctx, input_expr, ctx.getPointerType(pointee), op_loc);
            assert(input_expr != nullptr && "Failed to cast void* for load");
        }

        // Cancel *(&expr) from PTRADD's &base[index] to produce base[index].
        clang::Expr *result_expr = simplify_deref_addrof(input_expr);
        if (!result_expr) {
            auto derefed_expr = sema().CreateBuiltinUnaryOp(
                SourceLocation(ctx.getSourceManager(), op.key), clang::UO_Deref,
                clang::dyn_cast< clang::Expr >(input_expr)
            );
            result_expr = derefed_expr.getAs< clang::Expr >();
        }

        if (merge_to_next) {
            return std::make_pair(result_expr, merge_to_next);
        }

        auto *output_expr =
            AS_EXPR_OR_NULL(create_varnode(ctx, function, *op.output), op.key);
        if (!output_expr) {
            return { nullptr, false };
        }

        return { create_assign_operation(
                     ctx, result_expr, output_expr,
                     SourceLocation(ctx.getSourceManager(), op.key)
                 ),
                 false };
    }

    // Ghidra can give a STORE a bare integer address or a void*, which fail
    // Sema's indirection check.  Cast those to a pointer of the value's type so
    // the store lowers to *(T *)addr = value; a real non-void pointer passes
    // through unchanged.  Returns nullptr if the cast cannot be built.
    clang::Expr *OpBuilder::coerce_store_address(
        clang::ASTContext &ctx, clang::Expr *addr, clang::Expr *value,
        const Operation &op, clang::SourceLocation op_loc
    ) {
        auto addr_type = addr->getType();
        if (addr_type->isPointerType() && !addr_type->isVoidPointerType()) {
            return addr;
        }

        clang::QualType pointee = value != nullptr ? value->getType() : clang::QualType();
        if (pointee.isNull() || pointee->isVoidType()) {
            pointee = ctx.UnsignedCharTy;
        }

        auto *casted = make_cast(ctx, addr, ctx.getPointerType(pointee), op_loc);
        if (!casted) {
            LOG(ERROR) << "Failed to cast STORE address to pointer. key: " << op.key;
            return nullptr;
        }
        return casted;
    }

    std::pair< clang::Stmt *, bool > OpBuilder::create_store(
        clang::ASTContext &ctx, const Function &function, const Operation &op
    ) {
        if (op.inputs.empty()) {
            LOG(ERROR) << "Store operation with zero input operand. key: " << op.key << "\n";
            return {};
        }

        if (op.inputs.size() == 2) {
            auto op_loc = SourceLocation(ctx.getSourceManager(), op.key);
            auto *lhs_expr =
                AS_EXPR_OR_NULL(create_varnode(ctx, function, op.inputs[0]), op.key);
            auto *rhs_expr =
                AS_EXPR_OR_NULL(create_varnode(ctx, function, op.inputs[1]), op.key);
            if (!lhs_expr || !rhs_expr) {
                return {};
            }

            // Cancel *(&expr) from PTRADD's &base[index].
            clang::Expr *deref_expr = simplify_deref_addrof(lhs_expr);
            if (!deref_expr) {
                lhs_expr = coerce_store_address(ctx, lhs_expr, rhs_expr, op, op_loc);
                if (!lhs_expr) {
                    return {};
                }
                // Parenthesize pointer arithmetic so the deref binds the whole
                // expression: *(ptr + offset) instead of *ptr + offset.
                if (clang::isa< clang::BinaryOperator >(lhs_expr)) {
                    lhs_expr = new (ctx) clang::ParenExpr(op_loc, op_loc, lhs_expr);
                }
                auto deref_result =
                    sema().CreateBuiltinUnaryOp(op_loc, clang::UO_Deref, lhs_expr);
                if (deref_result.isInvalid()) {
                    LOG(ERROR) << "Failed to create deref expression for STORE. key: "
                               << op.key;
                    return {};
                }
                deref_expr = deref_result.getAs< clang::Expr >();
            }

            return { create_assign_operation(ctx, rhs_expr, deref_expr, op_loc), false };
        }

        // 3-input form: input0 = address-space constant (not representable in C, ignored),
        //               input1 = pointer, input2 = value to store.
        // Semantic: *input1 = input2;  (same as the 2-input case, just different slot indices)
        if (op.inputs.size() >= 3) {
            auto op_loc = SourceLocation(ctx.getSourceManager(), op.key);
            auto *lhs_expr =
                AS_EXPR_OR_NULL(create_varnode(ctx, function, op.inputs[1]), op.key);
            auto *rhs_expr =
                AS_EXPR_OR_NULL(create_varnode(ctx, function, op.inputs[2]), op.key);
            if (!lhs_expr || !rhs_expr) {
                return {};
            }

            // Cancel *(&expr) from PTRADD's &base[index].
            clang::Expr *deref_expr = simplify_deref_addrof(lhs_expr);
            if (!deref_expr) {
                lhs_expr = coerce_store_address(ctx, lhs_expr, rhs_expr, op, op_loc);
                if (!lhs_expr) {
                    return {};
                }
                if (clang::isa< clang::BinaryOperator >(lhs_expr)) {
                    lhs_expr = new (ctx) clang::ParenExpr(op_loc, op_loc, lhs_expr);
                }
                auto deref_result =
                    sema().CreateBuiltinUnaryOp(op_loc, clang::UO_Deref, lhs_expr);
                if (deref_result.isInvalid()) {
                    LOG(ERROR) << "Failed to create deref expression for STORE. key: " << op.key;
                    return {};
                }
                deref_expr = deref_result.getAs< clang::Expr >();
            }

            return { create_assign_operation(ctx, rhs_expr, deref_expr, op_loc), false };
        }

        LOG(ERROR) << "Store operation with unexpected number of inputs. key: " << op.key
                   << "\n";
        return {};
    }

    std::pair< clang::Stmt *, bool >
    OpBuilder::create_branch(clang::ASTContext &ctx, const Operation &op) {
        (void) ctx;
        if (!op.target_block) {
            LOG(ERROR) << "Branch instruction with no target block. key: " << op.key << "\n";
            return {};
        }

        // BRANCH terminals are handled by CGraphBuilder which builds the
        // GotoStmt/IfStmt into CNode::terminal.  create_block_stmts skips
        // terminals, so this function just returns nullptr to suppress the
        // operation from the block's statement list.
        return { nullptr, false };
    }

    std::pair< clang::Stmt *, bool > OpBuilder::create_cbranch(
        clang::ASTContext &ctx, const Function &function, const Operation &op
    ) {
        if (!op.condition) {
            LOG(ERROR) << "Conditional branch with no condition operator. key: " << op.key
                       << "\n";
            return {};
        }

        auto loc = SourceLocation(ctx.getSourceManager(), op.key);
        auto *condition_expr =
            AS_EXPR_OR_NULL(create_varnode(ctx, function, *op.condition), op.key);
        if (!condition_expr) {
            return {};
        }

        clang::Stmt *taken_stmt     = nullptr;
        clang::Stmt *not_taken_stmt = nullptr;

        if (op.taken_block && !op.taken_block->empty()
            && function_builder().labels_declaration.contains(*op.taken_block))
        {
            auto ll    = SourceLocation(ctx.getSourceManager(), *op.taken_block);
            taken_stmt = new (ctx) clang::GotoStmt(
                function_builder().labels_declaration.at(*op.taken_block), loc, ll
            );
        } else {
            taken_stmt = new (ctx) clang::NullStmt(loc, false);
        }

        if (op.not_taken_block && !op.not_taken_block->empty()
            && function_builder().labels_declaration.contains(*op.not_taken_block))
        {
            auto ll        = SourceLocation(ctx.getSourceManager(), *op.not_taken_block);
            not_taken_stmt = new (ctx) clang::GotoStmt(
                function_builder().labels_declaration.at(*op.not_taken_block), loc, ll
            );
        } else {
            not_taken_stmt = new (ctx) clang::NullStmt(loc, false);
        }

        return std::make_pair(
            clang::IfStmt::Create(
                ctx, loc, clang::IfStatementKind::Ordinary, nullptr, nullptr,
                condition_expr, condition_expr->getBeginLoc(),
                taken_stmt->getBeginLoc(), taken_stmt, not_taken_stmt->getBeginLoc(),
                not_taken_stmt
            ),
            false
        );
    }

    std::pair< clang::Stmt *, bool > OpBuilder::create_branchind(
        clang::ASTContext &ctx, const Function &function, const Operation &op
    ) {
        if (op.inputs.size() != 1U) {
            LOG(ERROR) << "BRANCHIND operation with invalid input operand. key: " << op.key
                       << "\n";
            return {};
        }

        auto *input_expr =
            AS_EXPR_OR_NULL(create_varnode(ctx, function, op.inputs[0]), op.key);
        if (!input_expr) {
            return {};
        }
        auto loc       = SourceLocation(ctx.getSourceManager(), op.key);
        auto expr_type = input_expr->getType();
        if (!expr_type->isPointerType()) {
            auto *cast_expr = make_cast(ctx, input_expr, ctx.getPointerType(expr_type), loc);
            if (cast_expr == nullptr) {
                LOG(ERROR) << "BRANCHIND: failed to cast input to pointer type. key: " << op.key
                           << "\n";
                return {};
            }
            input_expr = cast_expr;
        }

        // Priority 1: switch_cases present — proper integer switch using per-case
        // integer values recovered from P-Code.  Prefer inputs[0] when it is a named
        // local variable or parameter (the most direct discriminant); otherwise
        // fall back to switch_input, which may resolve to an inlined call expression.
        if (!op.switch_cases.empty()) {
            clang::Expr *disc = nullptr;
            if (op.inputs[0].kind == Varnode::VARNODE_LOCAL
                || op.inputs[0].kind == Varnode::VARNODE_PARAM) {
                disc = AS_EXPR_OR_NULL(
                    create_varnode(ctx, function, op.inputs[0]), op.key);
            } else if (op.switch_input.has_value()) {
                disc = AS_EXPR_OR_NULL(
                    create_varnode(ctx, function, *op.switch_input), op.key);
            }
            if (!disc) {
                return {};
            }
            // C promotes switch conditions to at least int width.  If the
            // discriminant is narrower than int (e.g., unsigned char / short
            // from "undefined" types), widen it so the case value
            // bit widths match the CIR switch condition type.
            {
                auto disc_type = disc->getType();
                bool needs_cast = !disc_type->isIntegerType()
                    || ctx.getIntWidth(disc_type) < ctx.getIntWidth(ctx.IntTy);
                if (needs_cast) {
                    auto *cast_disc = make_cast(ctx, disc, ctx.IntTy, loc);
                    if (cast_disc == nullptr) {
                        LOG(ERROR) << "BRANCHIND: failed to cast switch discriminant to int. key: "
                                   << op.key << "\n";
                        return {};
                    }
                    disc = cast_disc;
                }
            }

            auto *switch_stmt =
                clang::SwitchStmt::Create(ctx, nullptr, nullptr, disc, loc, loc);

            // Resolve enum types to their underlying integer type for
            // IntegerLiteral width computation (getIntWidth crashes on enum).
            auto disc_type = disc->getType();
            if (disc_type->isEnumeralType()) {
                disc_type = disc_type->castAs< clang::EnumType >()
                    ->getDecl()->getIntegerType();
            }

            auto create_case = [&](const SwitchCase &sc) -> clang::CaseStmt * {
                // disc_type may be _Bool/char32_t (enum lowered above).
                auto *case_val = MakeIntLiteralPrintable(
                    ctx, static_cast< uint64_t >(sc.value), disc_type,
                    /*is_signed=*/true, loc
                );
                auto *case_stmt =
                    clang::CaseStmt::Create(ctx, case_val, nullptr, loc, loc, loc);
                auto target_loc = SourceLocation(ctx.getSourceManager(), sc.target_block);

                // Try to inline the target block body for has_exit cases.
                // Requirements: block exists, has ordered ops, terminal op is BRANCH,
                // and the block has only one predecessor (otherwise the label must
                // remain so other gotos can reach it).
                bool inlined = false;
                bool single_pred = false;  // legacy — switch inlining disabled
                if (sc.has_exit && single_pred
                    && function.basic_blocks.contains(sc.target_block)) {
                    const auto &tb = function.basic_blocks.at(sc.target_block);
                    if (!tb.ordered_operations.empty()) {
                        const auto &last_op_key = tb.ordered_operations.back();
                        bool terminal_is_branch =
                            tb.operations.contains(last_op_key)
                            && tb.operations.at(last_op_key).mnemonic == Mnemonic::OP_BRANCH;

                        if (terminal_is_branch) {
                            std::vector< clang::Stmt * > case_body;
                            for (const auto &op_key : tb.ordered_operations) {
                                if (!tb.operations.contains(op_key)) { continue; }
                                const auto &target_op = tb.operations.at(op_key);
                                // Skip the terminal BRANCH — break replaces it.
                                if (target_op.mnemonic == Mnemonic::OP_BRANCH) { continue; }
                                auto [stmt, merge] =
                                    function_builder().create_operation(ctx, target_op);
                                for (auto *p : function_builder().pending_materialized) {
                                    case_body.push_back(p);
                                }
                                function_builder().pending_materialized.clear();
                                if (stmt) {
                                    function_builder().operation_stmts.emplace(
                                        target_op.key, stmt
                                    );
                                    if (!merge) { case_body.push_back(stmt); }
                                }
                            }
                            // If the terminal BRANCH targets a block other than
                            // the fallback (i.e. a back-edge to a loop header),
                            // emit goto instead of break to preserve the edge.
                            const auto &branch_op = tb.operations.at(last_op_key);
                            if (branch_op.target_block.has_value()
                                && branch_op.target_block != op.fallback_block
                                && function_builder().labels_declaration.contains(
                                    *branch_op.target_block
                                ))
                            {
                                auto tgt_loc = SourceLocation(
                                    ctx.getSourceManager(), *branch_op.target_block
                                );
                                case_body.push_back(new (ctx) clang::GotoStmt(
                                    function_builder().labels_declaration.at(
                                        *branch_op.target_block
                                    ),
                                    loc, tgt_loc
                                ));
                            } else {
                                case_body.push_back(new (ctx) clang::BreakStmt(loc));
                            }
                            case_stmt->setSubStmt(clang::CompoundStmt::Create(
                                ctx, case_body, clang::FPOptionsOverride(), loc, loc
                            ));
                            inlined = true;
                        }
                    }
                }

                if (!inlined) {
                    auto *goto_stmt = new (ctx) clang::GotoStmt(
                        function_builder().labels_declaration.at(sc.target_block), loc,
                        target_loc
                    );
                    case_stmt->setSubStmt(goto_stmt);
                    if (sc.has_exit) {
                    }
                }

                return case_stmt;
            };

            std::vector< clang::Stmt * > sw_body;
            for (const auto &sc : op.switch_cases) {
                if (function_builder().labels_declaration.contains(sc.target_block)) {
                    sw_body.push_back(create_case(sc));
                }
            }

            // Emit a default: arm for the guard branch's out-of-bounds target.
            // When the decompiler folds a bounds-check CBRANCH, the "else" edge becomes
            // fallback_block — the path taken when no case matches.
            if (op.fallback_block.has_value()
                && function_builder().labels_declaration.contains(*op.fallback_block))
            {
                auto *default_stmt = new (ctx) clang::DefaultStmt(loc, loc, nullptr);
                auto target_loc = SourceLocation(ctx.getSourceManager(), *op.fallback_block);
                auto *goto_stmt = new (ctx) clang::GotoStmt(
                    function_builder().labels_declaration.at(*op.fallback_block), loc,
                    target_loc
                );
                default_stmt->setSubStmt(goto_stmt);
                sw_body.push_back(default_stmt);
            }

            switch_stmt->setBody(
                clang::CompoundStmt::Create(ctx, sw_body, clang::FPOptionsOverride(), loc, loc)
            );
            return { switch_stmt, false };
        }

        // Priority 2: successor_blocks only — address-based switch (existing logic).
        if (!op.successor_blocks.empty()) {
            // Helper: parse "ram:HEXADDR:NUM:basic" → HEXADDR as uint64.
            auto parse_block_addr = [](const std::string &key) -> std::optional< uint64_t > {
                auto p1 = key.find(':');
                if (p1 == std::string::npos) {
                    return std::nullopt;
                }
                auto p2 = key.find(':', p1 + 1U);
                if (p2 == std::string::npos) {
                    return std::nullopt;
                }
                const auto hex_str = key.substr(p1 + 1U, p2 - p1 - 1U);
                if (hex_str.empty()) {
                    return std::nullopt;
                }
                try {
                    return std::stoull(hex_str, nullptr, 16);
                } catch (...) {
                    return std::nullopt;
                }
            };

            const auto disc_type = ctx.getUIntPtrType();
            auto *disc_expr      = input_expr;
            if (!ctx.hasSameUnqualifiedType(disc_expr->getType(), disc_type)) {
                disc_expr = make_cast(ctx, disc_expr, disc_type, loc);
                if (!disc_expr) {
                    return { nullptr, false };
                }
            }

            auto *switch_stmt =
                clang::SwitchStmt::Create(ctx, nullptr, nullptr, disc_expr, loc, loc);

            std::vector< clang::Stmt * > sw_body;
            for (const auto &block_key : op.successor_blocks) {
                if (!function_builder().labels_declaration.contains(block_key)) {
                    continue;
                }
                auto maybe_addr = parse_block_addr(block_key);
                if (!maybe_addr) {
                    continue;
                }
                auto *case_val = MakeIntLiteralPrintable(
                    ctx, *maybe_addr, disc_type, /*is_signed=*/false, loc
                );
                auto *case_stmt =
                    clang::CaseStmt::Create(ctx, case_val, nullptr, loc, loc, loc);
                auto target_loc = SourceLocation(ctx.getSourceManager(), block_key);
                auto *goto_stmt = new (ctx) clang::GotoStmt(
                    function_builder().labels_declaration.at(block_key), loc, target_loc
                );
                case_stmt->setSubStmt(goto_stmt);
                sw_body.push_back(case_stmt);
            }
            switch_stmt->setBody(
                clang::CompoundStmt::Create(ctx, sw_body, clang::FPOptionsOverride(), loc, loc)
            );
            return { switch_stmt, false };
        }

        // Loud-fail: a constant BRANCHIND target in the ARM EXC_RETURN range is
        // an exception return InterruptAnalysis should have reclassified; a goto
        // to that unmapped address is junk. Read the raw constant varnode.
        if (op.inputs[0].kind == Varnode::VARNODE_CONSTANT && op.inputs[0].value
            && *op.inputs[0].value >= ghidra::kArmExcReturnLow)
        {
            LOG(ERROR)
                << "BRANCHIND target " << *op.inputs[0].value
                << " is an un-reclassified ARM EXC_RETURN value; InterruptAnalysis "
                << "should have rewritten this exception return. Refusing to emit a "
                << "goto to an unmapped address. key: " << op.key << "\n";
            return { nullptr, false };
        }

        // Priority 3: no successor info at all — emit IndirectGotoStmt as the only
        // fallback when there are no resolved successors.
        auto *result_stmt = new (ctx) clang::IndirectGotoStmt(loc, loc, input_expr);
        assert(result_stmt != nullptr && "Failed to create indirect goto statement");

        return { result_stmt, false };
    }

    bool OpBuilder::extend_callexpr_arguments(
        clang::ASTContext &ctx, clang::FunctionDecl *fndecl,
        std::vector< clang::Expr * > &arguments
    ) {
        auto minargs = fndecl->getMinRequiredArguments();
        for (auto i = static_cast< unsigned >(arguments.size()); i < minargs; i++) {
            auto *param       = fndecl->getParamDecl(i);
            auto *default_arg = createDefaultArgument(ctx, param);
            if (default_arg == nullptr) {
                // No representable default (e.g. a by-value record).  Signal
                // failure so the caller drops the call: a null arg would crash
                // Sema and a short list would emit a hard "too few arguments".
                LOG(ERROR) << "Cannot synthesize default argument " << i << " for '"
                           << fndecl->getNameAsString() << "'. key dropped\n";
                return false;
            }
            arguments.emplace_back(default_arg);
        }
        return true;
    }

    clang::Expr *OpBuilder::build_callexpr_from_function(
        clang::ASTContext &ctx, const Function &function, const Operation &op
    ) {
        if (!op.target || !op.target->function) {
            LOG(ERROR) << "Missing target function, can't build callexpr\n";
            return nullptr;
        }

        if (!function_builder().function_list.get().contains(*op.target->function)) {
            LOG(ERROR) << "Missing target function from list, can't build callexpr\n";
            return nullptr;
        }

        auto op_loc = SourceLocation(ctx.getSourceManager(), op.key);

        // get the callee and its prototy for creating function argument list
        const auto &callee = function_builder().function_list.get().at(*op.target->function);
        const auto *proto_type = callee->getType()->getAs< clang::FunctionProtoType >();
        auto num_params        = proto_type->getNumParams();

        // The callee return type may be missing or incorrect during representing high pcode
        // into JSON format. Double check the function return type with operation type and fix
        // if there is any mismatch.
        if (op.type) {
            auto op_type_opt = lookup_op_type(op);
            if (!op_type_opt) {
                return {};
            }
            const auto &op_type = *op_type_opt;
            if (callee->getReturnType() != op_type && callee->getReturnType()->isVoidType()) {
                auto param_types    = proto_type->getParamTypes();
                auto epi            = proto_type->getExtProtoInfo();
                auto new_proto_type = ctx.getFunctionType(op_type, param_types, epi);
                callee->setType(new_proto_type);
                for (auto *decl : callee->redecls()) {
                    decl->setType(new_proto_type);
                }
                // Refresh proto_type/num_params so downstream code sees the
                // updated return type instead of the stale void.
                proto_type = callee->getType()->getAs< clang::FunctionProtoType >();
                num_params = proto_type->getNumParams();
            }
        }

        auto get_argument_type = [&](const clang::FunctionDecl *callee, clang::Expr *arg,
                                     unsigned index) -> clang::QualType {
            const auto *proto = callee->getType()->getAs< clang::FunctionProtoType >();
            if (proto->isVariadic() && (index >= proto->getNumParams())) {
                return arg->getType();
            }
            return proto->getParamType(index);
        };

        // When the call-site arg count differs from the declaration, treat the
        // call-site as ground truth.  Rebuild the declaration type from
        // call-site input types.  If ParmVarDecls can't be reset (already set
        // on the FunctionDecl), keep existing fixed params and promote to
        // variadic so extra args are accepted.  When two call-sites disagree
        // on arg count the function is also promoted to variadic.
        if (op.inputs.size() > num_params && !proto_type->isVariadic()) {
            // Resolve QualTypes for every call-site input.
            llvm::SmallVector< clang::QualType, 8 > new_param_types;
            bool types_ok = true;
            for (const auto &input : op.inputs) {
                auto it = type_builder().GetSerializedTypes().find(input.type_key);
                if (it == type_builder().GetSerializedTypes().end()) {
                    LOG(ERROR)
                        << "Cannot rebuild call declaration for '"
                        << callee->getNameAsString()
                        << "': input type '" << input.type_key
                        << "' not found in serialized types. key: " << op.key << "\n";
                    types_ok = false;
                    break;
                }
                new_param_types.push_back(it->second);
            }

            if (types_ok) {
                auto epi = proto_type->getExtProtoInfo();

                if (callee->param_empty()) {
                    // Declaration had no ParmVarDecls (e.g. extern with empty
                    // parameter_types).  We can set the exact param list.
                    auto new_type = ctx.getFunctionType(
                        proto_type->getReturnType(), new_param_types, epi
                    );
                    callee->setType(new_type);
                    for (auto *decl : callee->redecls()) {
                        decl->setType(new_type);
                    }

                    // Create matching ParmVarDecls.
                    llvm::SmallVector< clang::ParmVarDecl *, 8 > new_params;
                    for (unsigned i = 0; i < new_param_types.size(); ++i) {
                        std::string pname = "param_" + std::to_string(i);
                        auto *pd = clang::ParmVarDecl::Create(
                            ctx, callee, VirtualLoc(ctx),
                            VirtualLoc(ctx), &ctx.Idents.get(pname),
                            new_param_types[i], nullptr, clang::SC_None, nullptr
                        );
                        pd->setIsUsed();
                        new_params.push_back(pd);
                    }
                    callee->setParams(new_params);

                    LOG(INFO)
                        << "Rebuilt declaration for '" << callee->getNameAsString()
                        << "' from call-site with " << new_param_types.size()
                        << " params (was " << num_params << "). key: " << op.key << "\n";
                } else {
                    // Declaration already has ParmVarDecls — we can't call
                    // setParams again.  Keep existing fixed params and promote
                    // to variadic so extra call-site args are accepted.
                    epi.Variadic = true;
                    auto new_type = ctx.getFunctionType(
                        proto_type->getReturnType(), proto_type->getParamTypes(), epi
                    );
                    callee->setType(new_type);
                    for (auto *decl : callee->redecls()) {
                        decl->setType(new_type);
                    }
                    LOG(WARNING)
                        << "Call to '" << callee->getNameAsString()
                        << "' has " << op.inputs.size()
                        << " args but declaration has " << num_params
                        << " params; promoting to variadic. key: " << op.key << "\n";
                }

                proto_type = callee->getType()->getAs< clang::FunctionProtoType >();
                num_params = proto_type->getNumParams();
            } else {
                LOG(WARNING)
                    << "Skipping declaration rebuild for '"
                    << callee->getNameAsString()
                    << "'; extra call-site args will be dropped. key: " << op.key << "\n";
            }
        }

        unsigned index = 0;
        std::vector< clang::Expr * > arguments;
        for (const auto &input : op.inputs) {
            if (index >= num_params && !proto_type->isVariadic()) {
                continue;
            }
            auto *vnode_stmt = create_varnode(ctx, function, input);
            if (!vnode_stmt) {
                LOG(ERROR)
                    << "Failed to create varnode for call argument " << index
                    << " of '" << callee->getNameAsString()
                    << "'. key: " << op.key << "\n";
                index++;
                continue;
            }
            auto *vnode_expr = clang::dyn_cast< clang::Expr >(vnode_stmt);
            if (!vnode_expr) {
                LOG(ERROR)
                    << "Varnode for call argument " << index
                    << " of '" << callee->getNameAsString()
                    << "' is not an expression. key: " << op.key << "\n";
                index++;
                continue;
            }
            auto arg_type = get_argument_type(callee, vnode_expr, index++);
            // Route through make_cast which handles L/R-value conversion,
            // array/function decay, ShouldReinterpretCast for record↔scalar,
            // and reinterpret-cast fallback for exotic pairs.
            auto *arg = make_cast(ctx, vnode_expr, arg_type, op_loc);
            if (!arg) {
                LOG(ERROR) << "Failed to cast call argument " << (index - 1)
                           << " of '" << callee->getNameAsString()
                           << "'. key: " << op.key << "\n";
                arg = vnode_expr; // use uncast expr as fallback
            }
            arguments.push_back(arg);
        }

        // Check if the number of arguments is less then minimum number of require arguments;
        // extend it with the default value.
        unsigned min_args = callee->getMinRequiredArguments();
        if (arguments.size() < min_args) {
            if (!extend_callexpr_arguments(ctx, callee, arguments)) {
                LOG(ERROR) << "Dropping under-applied call to '"
                           << callee->getNameAsString() << "'. key: " << op.key << "\n";
                return nullptr;
            }
        }

        // A null Expr* in the argument list dereferences to a crash inside
        // Sema::CheckArgsForPlaceholders.  Refuse loudly instead.
        if (llvm::is_contained(arguments, nullptr)) {
            LOG(ERROR) << "Null argument in call to '" << callee->getNameAsString()
                       << "'. key: " << op.key << "\n";
            return nullptr;
        }

        auto *refexpr = clang::DeclRefExpr::Create(
            ctx, clang::NestedNameSpecifierLoc(), clang::SourceLocation(), callee, false,
            op_loc, ctx.getPointerType(callee->getType()), clang::VK_PRValue
        );

        auto result = sema().BuildCallExpr(
            nullptr, clang::dyn_cast< clang::Expr >(refexpr), op_loc, arguments, op_loc
        );
        if (result.isInvalid()) {
            LOG(ERROR) << "Failed to build call expr for '"
                       << callee->getNameAsString() << "'. key: " << op.key << "\n";
            return nullptr;
        }
        return result.getAs< clang::Expr >();
    }

    std::pair< clang::Stmt *, bool > OpBuilder::create_call(
        clang::ASTContext &ctx, const Function &function, const Operation &op
    ) {
        if (!op.target || op.mnemonic != Mnemonic::OP_CALL) {
            LOG(ERROR) << "Call operation or call target is invalid. key: " << op.key << "\n";
            return {};
        }

        if (!op.target->function && !op.target->operation) {
            LOG(ERROR) << "Call target does not have function or operation associated. key: "
                       << op.key << "\n";
            return {};
        }

        auto op_loc            = SourceLocation(ctx.getSourceManager(), op.key);
        clang::Expr *call_expr = nullptr;

        if (op.target->function) {
            clang::QualType ret_type;

            if (!function_builder().function_list.get().contains(*op.target->function)) {
                std::string callee_id = *op.target->function;
                std::replace(callee_id.begin(), callee_id.end(), ':', '_');
                std::string reason = "missing_call_" + callee_id;

                LOG(ERROR) << "CALL: callee '" << *op.target->function
                           << "' not in function_list — emitting "
                              "__patchestry_error(\""
                           << reason << "\"). key: " << op.key << "\n";

                auto *err_expr = emit_patchestry_error(ctx, reason, op_loc);
                if (!err_expr) {
                    return {};
                }

                clang::QualType site_ret;
                if (op.has_return_value.value_or(false) && op.type) {
                    auto t = type_builder().GetSerializedType(*op.type);
                    if (!t.isNull() && !t->isVoidType()) {
                        site_ret = t;
                    }
                }

                if (site_ret.isNull()) {
                    return std::make_pair(
                        clang::dyn_cast< clang::Stmt >(err_expr), false
                    );
                }

                call_expr = make_explicit_cast(ctx, err_expr, site_ret, op_loc);
                if (!call_expr) {
                    LOG(ERROR) << "CALL: failed to cast __patchestry_error to "
                               << site_ret.getAsString() << ". key: " << op.key
                               << "\n";
                    return std::make_pair(
                        clang::dyn_cast< clang::Stmt >(err_expr), false
                    );
                }
                ret_type = site_ret;
            } else {
                const auto &callee =
                    function_builder().function_list.get().at(*op.target->function);

                call_expr = build_callexpr_from_function(ctx, function, op);
                if (!call_expr) {
                    LOG(ERROR) << "Failed to create call expression for '"
                               << callee->getNameAsString() << "'. key: " << op.key << "\n";
                    return {};
                }
                ret_type = callee->getReturnType();
            }

            if (ret_type->isVoidType()) {
                return std::make_pair(clang::dyn_cast< clang::Expr >(call_expr), false);
            }
            if (!op.output) {
                // Non-void return but no explicit output varnode.
                // Materialize into a temp var to avoid duplicate call output.
                return materialize_call_return(
                    ctx, call_expr, ret_type, op, op_loc);
            }

        } else if (op.target->operation) {
            // Get list of arguments for function call
            std::vector< clang::Expr * > arguments;
            for (const auto &input : op.inputs) {
                auto *arg_expr =
                    AS_EXPR_OR_NULL(create_varnode(ctx, function, input), op.key);
                if (!arg_expr) {
                    return {};
                }
                arguments.push_back(arg_expr);
            }

            auto operation = operationFromKey(function, *op.target->operation);
            if (!operation) {
                LOG(ERROR) << "CALL target operation not found. key: " << op.key << "\n";
                return {};
            }
            auto [stmt, _] = function_builder().create_operation(ctx, *operation);
            auto result    = sema().BuildCallExpr(
                nullptr, clang::dyn_cast< clang::Expr >(stmt), op_loc, arguments, op_loc
            );
            assert(!result.isInvalid());
            call_expr = result.getAs< clang::Expr >();
            if (!operation->output || call_expr->getType()->isVoidType()) {
                return std::make_pair(clang::dyn_cast< clang::Expr >(call_expr), false);
            }
        }

        auto *output_expr =
            AS_EXPR_OR_NULL(create_varnode(ctx, function, *op.output), op.key);
        if (!output_expr) {
            return {};
        }

        return { create_assign_operation(ctx, call_expr, output_expr, op_loc), false };
    }

    std::pair< clang::Stmt *, bool > OpBuilder::create_tail_call(
        clang::ASTContext &ctx, const Function &function, const Operation &op,
        clang::FunctionDecl *enclosing_decl
    ) {
        auto op_loc = SourceLocation(ctx.getSourceManager(), op.key);

        // Shared fallback: __patchestry_missing_tailcall_unresolved() +
        // `return (T)0;` (or bare `return;` for void enclosing). One
        // intrinsic per unresolved tail-call; AnnotateAttr carries
        // op.key and (when known) the original target address.
        auto emit_fallback_return = [&]() -> std::pair< clang::Stmt *, bool > {
            std::string label = "tail_call_unresolved";
            if (op.target.has_value() && op.target->address.has_value()) {
                label += " addr=" + *op.target->address;
            }
            auto [marker_stmt, _] = create_missing_intrinsic_call(
                ctx, function, op, "tailcall_unresolved", label
            );
            if (marker_stmt != nullptr) {
                function_builder().pending_materialized.push_back(marker_stmt);
            }

            clang::Expr *ret_expr = nullptr;
            const auto enclosing_ret = (enclosing_decl != nullptr)
                ? enclosing_decl->getReturnType()
                : ctx.VoidTy;
            if (!enclosing_ret->isVoidType()) {
                auto *zero = clang::IntegerLiteral::Create(
                    ctx, llvm::APInt(32, 0), ctx.IntTy, op_loc
                );
                auto cast_result = sema().BuildCStyleCastExpr(
                    op_loc, ctx.getTrivialTypeSourceInfo(enclosing_ret),
                    op_loc, zero
                );
                if (!cast_result.isInvalid()) {
                    ret_expr = cast_result.getAs< clang::Expr >();
                }
            }
            auto *ret_stmt = clang::ReturnStmt::Create(
                ctx, op_loc, ret_expr, nullptr
            );
            return { ret_stmt, false };
        };

        if (!op.target || op.mnemonic != Mnemonic::OP_TAIL_CALL) {
            LOG(ERROR) << "TAIL_CALL operation or target is invalid. key: "
                       << op.key << "\n";
            return emit_fallback_return();
        }
        if (!op.target->function) {
            LOG(ERROR) << "TAIL_CALL target missing function. key: " << op.key << "\n";
            return emit_fallback_return();
        }
        if (!function_builder().function_list.get().contains(*op.target->function)) {
            return emit_fallback_return();
        }

        const auto *callee =
            function_builder().function_list.get().at(*op.target->function);

        // Args not recovered: default-filling with zeros would silently
        // corrupt data flow, so emit __patchestry_missing_<callee> +
        // cast-zero return instead.
        if (callee->getMinRequiredArguments() > op.inputs.size()) {
            LOG(ERROR) << "TAIL_CALL: callee '" << callee->getNameAsString()
                       << "' expects " << callee->getMinRequiredArguments()
                       << " arg(s) but PcodeSerializer recovered "
                       << op.inputs.size()
                       << " (tail-call arg recovery NYI). key: " << op.key << "\n";

            auto [missing_stmt, _] = create_missing_intrinsic_call(
                ctx, function, op, callee->getNameAsString(),
                "tail_call_" + callee->getNameAsString()
            );
            if (missing_stmt != nullptr) {
                function_builder().pending_materialized.push_back(missing_stmt);
            }

            clang::Expr *ret_expr = nullptr;
            const auto enclosing_ret = (enclosing_decl != nullptr)
                ? enclosing_decl->getReturnType()
                : ctx.VoidTy;
            if (!enclosing_ret->isVoidType()) {
                auto *zero = clang::IntegerLiteral::Create(
                    ctx, llvm::APInt(32, 0), ctx.IntTy, op_loc
                );
                auto cast_result = sema().BuildCStyleCastExpr(
                    op_loc, ctx.getTrivialTypeSourceInfo(enclosing_ret),
                    op_loc, zero
                );
                if (!cast_result.isInvalid()) {
                    ret_expr = cast_result.getAs< clang::Expr >();
                }
            }
            auto *ret_stmt = clang::ReturnStmt::Create(ctx, op_loc, ret_expr, nullptr);
            return { ret_stmt, false };
        }

        auto *call_expr = build_callexpr_from_function(ctx, function, op);
        if (!call_expr) {
            return emit_fallback_return();
        }

        const auto enclosing_ret = (enclosing_decl != nullptr)
            ? enclosing_decl->getReturnType()
            : ctx.VoidTy;

        const bool callee_void     = call_expr->getType()->isVoidType();
        // FunctionDecl attr or call-site flag — either source authoritative.
        const bool callee_noreturn = callee->isNoReturn()
            || (op.target.has_value() && op.target->is_noreturn);
        const bool enclosing_void  = enclosing_ret->isVoidType();

        // No return-value contract can be satisfied here.
        if (callee_void && !callee_noreturn && !enclosing_void) {
            LOG(ERROR) << "TAIL_CALL: void non-noreturn callee in non-void enclosing "
                       << "function '" << enclosing_decl->getNameAsString()
                       << "'. key: " << op.key << "\n";
            return emit_fallback_return();
        }

        // Bare ReturnStmt (not CompoundStmt) keeps the structurer's
        // goto-to-return rewrite matching; non-void enclosing needs (T)0
        // to satisfy CIR even though textually unreachable after noreturn.
        if (callee_void || callee_noreturn || enclosing_void) {
            function_builder().pending_materialized.push_back(call_expr);

            clang::Expr *ret_expr = nullptr;
            if (!enclosing_void) {
                auto *zero = clang::IntegerLiteral::Create(
                    ctx, llvm::APInt(32, 0), ctx.IntTy, op_loc
                );
                auto cast_result = sema().BuildCStyleCastExpr(
                    op_loc, ctx.getTrivialTypeSourceInfo(enclosing_ret),
                    op_loc, zero
                );
                if (!cast_result.isInvalid()) {
                    ret_expr = cast_result.getAs< clang::Expr >();
                }
            }
            auto *ret_stmt = clang::ReturnStmt::Create(ctx, op_loc, ret_expr, nullptr);
            return { ret_stmt, false };
        }

        auto *casted = make_cast(ctx, call_expr, enclosing_ret, op_loc);
        if (casted == nullptr) {
            LOG(ERROR) << "TAIL_CALL: cannot cast callee return type to "
                       << "enclosing function's return type. key: " << op.key << "\n";
            return emit_fallback_return();
        }
        auto *ret_stmt = clang::ReturnStmt::Create(ctx, op_loc, casted, nullptr);
        return { ret_stmt, false };
    }

    std::pair< clang::Stmt *, bool > OpBuilder::create_callind(
        clang::ASTContext &ctx, const Function &function, const Operation &op
    ) {
        // 1. Validate operation
        if (!op.target || op.mnemonic != Mnemonic::OP_CALLIND) {
            LOG(ERROR) << "CALLIND operation or target is invalid. key: " << op.key << "\n";
            return {};
        }

        auto op_loc            = SourceLocation(ctx.getSourceManager(), op.key);
        clang::Expr *fn_ptr_expr = nullptr;

        // 2. Get function pointer expression from target
        if (op.target->global) {
            // Target is a global variable containing the function pointer
            if (!function_builder().global_var_list.get().contains(*op.target->global)) {
                LOG(ERROR) << "CALLIND target global not found: " << *op.target->global
                           << ". key: " << op.key << "\n";
                return {};
            }
            auto *var_decl = function_builder().global_var_list.get().at(*op.target->global);
            fn_ptr_expr    = clang::DeclRefExpr::Create(
                ctx, clang::NestedNameSpecifierLoc(), clang::SourceLocation(), var_decl, false,
                VirtualLoc(ctx), var_decl->getType(), clang::VK_LValue
            );
        } else if (op.target->operation) {
            // Target is a computed expression — resolve via create_varnode for varnode
            // kinds (temporary/local/param) so that DECLARE_* operations produce
            // DeclRefExprs rather than DeclStmts.
            // NOTE: op.target->operation is guaranteed non-nullopt by the guard above.
            if (op.target->kind == Varnode::VARNODE_TEMPORARY
                || op.target->kind == Varnode::VARNODE_LOCAL
                || op.target->kind == Varnode::VARNODE_PARAM) {
                Varnode target_vnode;
                target_vnode.kind      = op.target->kind;
                target_vnode.operation  = op.target->operation;
                target_vnode.type_key   = op.target->type_key.value_or("");
                target_vnode.size       = 0;
                fn_ptr_expr = clang::dyn_cast_or_null< clang::Expr >(
                    create_varnode(ctx, function, target_vnode)
                );
            } else {
                auto maybe_operation = operationFromKey(function, *op.target->operation);
                if (!maybe_operation) {
                    LOG(ERROR) << "CALLIND target operation not found. key: " << op.key << "\n";
                    return {};
                }
                auto [stmt, _] = function_builder().create_operation(ctx, *maybe_operation);
                fn_ptr_expr    = clang::dyn_cast_or_null< clang::Expr >(stmt);
            }
        } else {
            LOG(ERROR) << "CALLIND target missing global or operation. key: " << op.key << "\n";
            return {};
        }

        if (fn_ptr_expr == nullptr) {
            LOG(ERROR) << "Failed to create function pointer expression. key: " << op.key << "\n";
            return {};
        }

        // 3. Infer function pointer type and cast if needed
        auto expr_type = fn_ptr_expr->getType();

        // Check if we need to build an explicit function pointer type
        const bool needs_type_inference =
            !expr_type->isPointerType() || !expr_type->getPointeeType()->isFunctionType();

        if (needs_type_inference) {
            // Infer parameter types from inputs
            std::vector< clang::QualType > param_types;
            for (const auto &input : op.inputs) {
                if (type_builder().GetSerializedTypes().contains(input.type_key)) {
                    param_types.push_back(type_builder().GetSerializedType(input.type_key));
                } else {
                    param_types.push_back(ctx.IntTy); // Fallback
                }
            }

            // Infer return type from op.type
            clang::QualType return_type = ctx.VoidTy;
            if (op.type && type_builder().GetSerializedTypes().contains(*op.type)) {
                return_type = type_builder().GetSerializedType(*op.type);
            }

            // Build function type and pointer type
            const clang::FunctionProtoType::ExtProtoInfo epi;
            auto func_type     = ctx.getFunctionType(return_type, param_types, epi);
            auto func_ptr_type = ctx.getPointerType(func_type);

            // Cast callee to inferred function pointer type
            fn_ptr_expr = make_cast(ctx, fn_ptr_expr, func_ptr_type, op_loc);
            if (fn_ptr_expr == nullptr) {
                LOG(ERROR) << "Failed to cast to function pointer type. key: " << op.key << "\n";
                return {};
            }
        }

        // 4. Build argument list from inputs, casting each to the callee's
        //    declared parameter type.  A Ghidra-recovered argument expression can
        //    have a clang type that differs from the (inferred or prototyped)
        //    function-pointer parameter type — e.g. `&local` typed
        //    `unsigned short **` passed where the parameter is `undefined4 *` —
        //    which BuildCallExpr rejects as "incompatible pointer types".  Mirror
        //    the direct-call path (create_call), which already casts arguments.
        //    See FUN_000d1e6c (cve-2022-39173).
        const auto *fn_proto =
            fn_ptr_expr->getType()->getPointeeType()->getAs< clang::FunctionProtoType >();
        unsigned num_params = fn_proto ? fn_proto->getNumParams() : 0;

        std::vector< clang::Expr * > arguments;
        unsigned index = 0;
        for (const auto &input : op.inputs) {
            auto *arg_expr =
                AS_EXPR_OR_NULL(create_varnode(ctx, function, input), op.key);
            if (!arg_expr) {
                // Bail rather than drop the argument: silently skipping it would
                // shift every later argument into the wrong parameter slot (the
                // remaining args are still cast to getParamType(index)).
                LOG(ERROR) << "CALLIND: failed to build argument " << index
                           << ". key: " << op.key;
                return {};
            }
            // Variadic / trailing args (index >= num_params) pass through uncast.
            if (fn_proto && index < num_params) {
                auto param_type = fn_proto->getParamType(index);
                if (auto *cast_arg = make_cast(ctx, arg_expr, param_type, op_loc)) {
                    arg_expr = cast_arg;
                } else {
                    // Keep the uncast expr as a fallback (matches create_call).
                    LOG(ERROR) << "CALLIND: failed to cast argument " << index
                               << " to parameter type '" << param_type.getAsString()
                               << "'. key: " << op.key;
                }
            }
            arguments.push_back(arg_expr);
            index++;
        }

        // 5. Build the indirect call expression
        auto result = sema().BuildCallExpr(nullptr, fn_ptr_expr, op_loc, arguments, op_loc);
        if (result.isInvalid()) {
            LOG(ERROR) << "Failed to build CALLIND expression. key: " << op.key << "\n";
            return {};
        }
        auto *call_expr = result.getAs< clang::Expr >();

        // 6. Handle return value assignment if present
        if (!op.output) {
            if (!call_expr->getType()->isVoidType()) {
                return materialize_call_return(
                    ctx, call_expr, call_expr->getType(), op, op_loc);
            }
            return std::make_pair(call_expr, false);
        }

        auto *output_expr =
            AS_EXPR_OR_NULL(create_varnode(ctx, function, *op.output), op.key);
        if (!output_expr) {
            return {};
        }
        return { create_assign_operation(ctx, call_expr, output_expr, op_loc), false };
    }

    std::pair< clang::Stmt *, bool > OpBuilder::create_callother(
        clang::ASTContext &ctx, const Function &function, const Operation &op
    ) {
        if (!op.target || op.target->kind != Varnode::VARNODE_INTRINSIC || !op.target->function) {
            LOG(ERROR) << "Invalid CALLOTHER intrinsic target. key: " << op.key << "\n";
            return {};
        }

        const auto &label = *op.target->function;
        auto name         = parse_intrinsic_name(function_builder().program_arch(), label);

        // Custom-semantics handlers (volatile_read → *(volatile T*)addr
        // deref, etc.) take precedence so they can rewrite the op
        // instead of building a call.
        const auto &handlers = get_intrinsic_handlers();
        auto it              = handlers.find(name);
        if (it != handlers.end()) {
            return it->second(*this, ctx, function, op, name);
        }

        // Generic intrinsic: emit a direct call against the
        // FunctionDecl the Ghidra serialiser registered for this
        // intrinsic.  Variadic decl absorbs arg-type adjustments.
        if (function_builder().function_list.get().contains(label)) {
            return build_intrinsic_call_against_registered(ctx, function, op);
        }

        // Truly unknown: synthesise an annotated placeholder.
        return create_missing_intrinsic_call(ctx, function, op, name, label);
    }

    std::pair< clang::Stmt *, bool > OpBuilder::create_userdefined(
        clang::ASTContext &ctx, const Function &function, const Operation &op
    ) {
        // OP_USERDEFINED covers processor-specific semantics; handled identically to
        // OP_CALLOTHER: emit an opaque placeholder call so the operation is not silently lost.
        auto op_loc = SourceLocation(ctx.getSourceManager(), op.key);

        clang::QualType ret_type = ctx.VoidTy;
        if (op.output.has_value() && op.type.has_value()) {
            const auto &types = type_builder().GetSerializedTypes();
            auto it           = types.find(*op.type);
            if (it != types.end()) {
                ret_type = it->second;
            }
        }

        std::string fn_name = "__patchestry_userdefined_" + SanitizeKeyToIdent(op.key);

        llvm::SmallVector< clang::QualType, 4 > param_types;
        for (const auto &input : op.inputs) {
            param_types.push_back(get_varnode_type(ctx, input));
        }

        clang::FunctionDecl *fn_decl =
            lookup_or_create_opaque_fn(ctx, fn_name, ret_type, param_types, op_loc);

        std::vector< clang::Expr * > args;
        for (const auto &input : op.inputs) {
            auto *arg_expr =
                AS_EXPR_OR_NULL(create_varnode(ctx, function, input), op.key);
            if (arg_expr) {
                args.push_back(arg_expr);
            }
        }
        // When fn was created with void* placeholder (zero inputs), pass (void*)0
        if (args.empty() && op.inputs.empty()) {
            auto *zero = clang::IntegerLiteral::Create(
                ctx, llvm::APInt(32, 0), ctx.IntTy, op_loc
            );
            auto *null_expr = make_cast(ctx, zero, ctx.VoidPtrTy, op_loc);
            if (null_expr != nullptr) {
                args.push_back(null_expr);
            }
        }

        auto *ref_expr = clang::DeclRefExpr::Create(
            ctx, clang::NestedNameSpecifierLoc(), clang::SourceLocation(), fn_decl, false,
            op_loc, ctx.getPointerType(fn_decl->getType()), clang::VK_PRValue
        );

        auto call_result = sema().BuildCallExpr(nullptr, ref_expr, op_loc, args, op_loc);
        if (call_result.isInvalid()) {
            LOG(ERROR) << "Failed to build userdefined placeholder for: " << op.key << "\n";
            return {};
        }
        auto *call_expr = call_result.getAs< clang::Expr >();

        if (!op.output.has_value() || ret_type->isVoidType()) {
            return { call_expr, false };
        }

        auto *output_expr =
            AS_EXPR_OR_NULL(create_varnode(ctx, function, *op.output), op.key);
        if (!output_expr) {
            return {};
        }
        return { create_assign_operation(ctx, call_expr, output_expr, op_loc), false };
    }

    std::pair< clang::Stmt *, bool > OpBuilder::create_return(
        clang::ASTContext &ctx, const Function &function, const Operation &op
    ) {
        auto location = SourceLocation(ctx.getSourceManager(), op.key);
        if (!op.inputs.empty()) {
            // For multi-input RETURN, input[0] is the address-space constant; use input[1].
            // For single-input RETURN, use input[0] directly.
            size_t idx     = op.inputs.size() > 1 ? 1 : 0;
            auto *ret_stmt = create_varnode(ctx, function, op.inputs[idx]);
            auto *ret_expr = llvm::dyn_cast_or_null< clang::Expr >(ret_stmt);

            // Match the return expression's type to the function's declared
            // return type. Ghidra high-pcode operators like INT_EQUAL emit a
            // varnode whose width (e.g. 4 bytes from a promoted int result)
            // can exceed the function's narrower return type (e.g. `_Bool`
            // / i8). Without an implicit narrowing cast here, Clang's CIR
            // lowering stores the wider value into the narrower retval slot,
            // producing a `store i32 ..., ptr alloca_i8` that KLEE flags as
            // an out-of-bound access. `create_assign_operation` already does
            // the equivalent for ordinary assignments; return is the one
            // lift path that bypasses it.
            if (ret_expr != nullptr) {
                const auto &types = type_builder().GetSerializedTypes();
                auto ret_type_it  = types.find(function.prototype.rttype_key);
                if (ret_type_it != types.end()
                    && !ret_type_it->second.isNull()
                    && !ret_type_it->second->isVoidType()
                    && !ctx.hasSameUnqualifiedType(
                        ret_expr->getType(), ret_type_it->second))
                {
                    auto *cast_expr =
                        make_cast(ctx, ret_expr, ret_type_it->second, location);
                    if (cast_expr != nullptr) {
                        ret_expr = cast_expr;
                    }
                }
            }

            return std::make_pair(
                clang::ReturnStmt::Create(ctx, location, ret_expr, nullptr),
                false
            );
        }

        // When the enclosing function returns non-void, emit "return (T)0;"
        // instead of a bare "return;" to avoid a diagnostic on the (typically
        // unreachable) empty return after __stack_chk_fail or similar.
        const auto &types = type_builder().GetSerializedTypes();
        auto type_it      = types.find(function.prototype.rttype_key);
        if (type_it != types.end() && !type_it->second->isVoidType()) {
            auto ret_type = type_it->second;
            auto *zero    = clang::IntegerLiteral::Create(
                ctx, llvm::APInt(32, 0), ctx.IntTy, location
            );
            auto cast_result = sema().BuildCStyleCastExpr(
                location, ctx.getTrivialTypeSourceInfo(ret_type), location, zero
            );
            // `(T)0` is ill-formed when T is a record/reference/opaque type
            // (common for C++ by-value returns, e.g. a QString). Fall back to a
            // bare `return;` rather than aborting — this path is the typically
            // unreachable empty return after a noreturn call.
            if (cast_result.isInvalid()) {
                LOG(ERROR) << "create_return: cannot build (T)0 for return type '"
                           << ret_type.getAsString() << "'; emitting bare return. key: "
                           << op.key << "\n";
                return std::make_pair(
                    clang::ReturnStmt::Create(ctx, location, nullptr, nullptr), false
                );
            }
            return std::make_pair(
                clang::ReturnStmt::Create(
                    ctx, location, cast_result.getAs< clang::Expr >(), nullptr
                ),
                false
            );
        }

        return std::make_pair(
            clang::ReturnStmt::Create(ctx, location, nullptr, nullptr), false
        );
    }

    std::pair< clang::Stmt *, bool > OpBuilder::create_piece(
        clang::ASTContext &ctx, const Function &function, const Operation &op
    ) {
        if (op.inputs.size() != 2U || op.mnemonic != Mnemonic::OP_PIECE) {
            LOG(ERROR) << "PIECE Operation with invalid input operands or invalid "
                          "operation. key: "
                       << op.key;
            return {};
        }

        auto type_it = type_builder().GetSerializedTypes().find(*op.type);
        if (type_it == type_builder().GetSerializedTypes().end()) {
            LOG(ERROR) << "PIECE Operation type is not serialized. key: " << op.key;
            return {};
        }

        auto *input0_stmt = create_varnode(ctx, function, op.inputs[0]);
        auto *input1_stmt = create_varnode(ctx, function, op.inputs[1]);
        if (!input0_stmt || !input1_stmt) {
            LOG(ERROR) << "PIECE: input varnode produced null Stmt. key: " << op.key;
            return {};
        }
        auto *input0_expr = clang::dyn_cast< clang::Expr >(input0_stmt);
        auto *input1_expr = clang::dyn_cast< clang::Expr >(input1_stmt);
        if (!input0_expr || !input1_expr) {
            LOG(ERROR) << "PIECE: input varnode is not an Expr. key: " << op.key;
            return {};
        }
        auto location = SourceLocation(ctx.getSourceManager(), op.key);

        // #250 guard: PIECE is scalar — Array-typed operands trip Sema.
        if (input0_expr->getType()->isArrayType()
            || input1_expr->getType()->isArrayType()
            || type_it->second->isArrayType()) {
            LOG(ERROR) << "PIECE: array-typed operand/result (issue #250). "
                       << "input0='" << input0_expr->getType().getAsString()
                       << "' input1='" << input1_expr->getType().getAsString()
                       << "' op='" << type_it->second.getAsString()
                       << "' key: " << op.key;
            return {};
        }

        // Record (struct/union) types cannot participate in bitwise shift/or
        // arithmetic.  When PIECE involves a record type, emit a simple
        // assignment of the low part (input1) to the output.
        if (input0_expr->getType()->isRecordType()
            || input1_expr->getType()->isRecordType()
            || type_it->second->isRecordType()) {
            auto merge_to_next = !op.output.has_value();
            clang::Expr *result_expr = input1_expr;
            if (!ctx.hasSameUnqualifiedType(result_expr->getType(), type_it->second)) {
                result_expr = make_reinterpret_cast(ctx, result_expr, type_it->second, location);
                if (!result_expr) {
                    LOG(ERROR) << "PIECE: reinterpret-cast yielded null Expr. key: "
                               << op.key;
                    return {};
                }
            }
            if (merge_to_next) {
                return std::make_pair(static_cast< clang::Stmt * >(result_expr), merge_to_next);
            }
            auto *output_stmt = create_varnode(ctx, function, *op.output);
            if (!output_stmt) {
                LOG(ERROR) << "PIECE: record-type output varnode produced null Stmt. key: "
                           << op.key;
                return {};
            }
            auto *output_expr = clang::dyn_cast< clang::Expr >(output_stmt);
            if (!output_expr) {
                LOG(ERROR) << "PIECE: record-type output varnode is not an Expr. key: "
                           << op.key;
                return {};
            }
            return { create_assign_operation(ctx, result_expr, output_expr, location),
                     false };
        }

        // Shift the high part by the low part's bit width.  Prefer the varnode
        // byte size (* 8) over the clang type size: clang rounds non-power-of-two
        // widths (e.g. 3-byte uint3 -> 32 bits) up, which can push the shift
        // count >= the result width and trip a warning.  Fall back to the type
        // size only when the varnode size is absent.
        unsigned low_width = op.inputs[1].size * 8U;
        if (low_width == 0) {
            auto low_type_it =
                type_builder().GetSerializedTypes().find(op.inputs[1].type_key);
            if (low_type_it != type_builder().GetSerializedTypes().end()) {
                low_width = static_cast< unsigned >(ctx.getTypeSize(low_type_it->second));
            } else {
                LOG(ERROR) << "PIECE: low-part type not found for key '"
                           << op.inputs[1].type_key
                           << "'; cannot determine shift width. key: " << op.key;
                return {};
            }
        }

        auto merge_to_next = !op.output.has_value();

        // PIECE is a bit concatenation (high << low_width | low), so it must run
        // in the integer domain.  A non-integral result type (e.g. a float
        // register) would make the shift below 'float << int', which C rejects:
        // compute in an unsigned integer of the result width, then reinterpret
        // the bits (not value-convert) back to the result type.
        clang::QualType piece_result_type;
        bool reinterpret_result = false;
        if (op.type) {
            piece_result_type   = type_it->second;
            auto arith_type     = piece_result_type;
            if (!piece_result_type->isIntegerType()) {
                arith_type = ctx.getIntTypeForBitwidth(
                    static_cast< unsigned >(ctx.getTypeSize(piece_result_type)),
                    /*Signed=*/false
                );
                if (arith_type.isNull()) {
                    // No integer type matches the result width.  Falling back to
                    // a narrower int would make the later reinterpret read past
                    // the temporary (*(wide *)&narrow) — UB.  Skip the op.
                    LOG(ERROR) << "PIECE: no integer type for result width "
                               << ctx.getTypeSize(piece_result_type)
                               << "; skipping. key: " << op.key;
                    return {};
                }
                reinterpret_result = true;
            }
            auto *cast_expr_input0 = make_cast(ctx, input0_expr, arith_type, location);
            if (!cast_expr_input0) {
                LOG(ERROR) << "Failed to create cast expression for PIECE input0. key: "
                           << op.key;
                return {};
            }
            input0_expr            = cast_expr_input0;
            auto *cast_expr_input1 = make_cast(ctx, input1_expr, arith_type, location);
            if (!cast_expr_input1) {
                LOG(ERROR) << "Failed to create cast expression for PIECE input1. key: "
                           << op.key;
                return {};
            }
            input1_expr = cast_expr_input1;
        }

        // When low_width is 0, the shift is a no-op — skip it to avoid "<< 0".
        clang::Expr *high_expr = input0_expr;
        if (low_width > 0) {
            auto *shift_value = clang::IntegerLiteral::Create(
                ctx, llvm::APInt(ctx.getIntWidth(ctx.IntTy), low_width), ctx.IntTy, location
            );
            auto shifted_high_result = sema().CreateBuiltinBinOp(
                location, clang::BO_Shl, input0_expr, shift_value
            );
            if (shifted_high_result.isInvalid()) {
                LOG(ERROR) << "PIECE Operation invalid shifted high result.\n";
                return {};
            }
            high_expr = shifted_high_result.getAs< clang::Expr >();
            if (!high_expr) {
                LOG(ERROR) << "PIECE: shifted high result yielded null Expr. key: "
                           << op.key;
                return {};
            }
        }

        auto or_result = sema().CreateBuiltinBinOp(
            location, clang::BO_Or, high_expr, input1_expr
        );
        if (or_result.isInvalid()) {
            LOG(ERROR) << "PIECE Operation invalid OR result. key: " << op.key;
            return {};
        }
        auto *or_expr = or_result.getAs< clang::Expr >();
        if (!or_expr) {
            LOG(ERROR) << "PIECE: OR result yielded null Expr. key: " << op.key;
            return {};
        }

        // The concatenation was computed as an integer; reinterpret its bits as
        // the (non-integral) result type when one was requested.
        if (reinterpret_result) {
            or_expr = make_reinterpret_cast(ctx, or_expr, piece_result_type, location);
            if (!or_expr) {
                LOG(ERROR) << "PIECE: reinterpret to result type yielded null Expr. key: "
                           << op.key;
                return {};
            }
        }

        if (merge_to_next) {
            return std::make_pair(or_expr, merge_to_next);
        }

        auto *output_stmt = create_varnode(ctx, function, *op.output);
        if (!output_stmt) {
            LOG(ERROR) << "PIECE: output varnode produced null Stmt. key: " << op.key;
            return {};
        }
        auto *output_expr = clang::dyn_cast< clang::Expr >(output_stmt);
        if (!output_expr) {
            LOG(ERROR) << "PIECE: output varnode is not an Expr. key: " << op.key;
            return {};
        }
        return { create_assign_operation(
                     ctx, or_expr, output_expr,
                     SourceLocation(ctx.getSourceManager(), op.key)
                 ),
                 false };
    }

    std::pair< clang::Stmt *, bool > OpBuilder::create_subpiece(
        clang::ASTContext &ctx, const Function &function, const Operation &op
    ) {
        if (op.inputs.size() != 2U || op.mnemonic != Mnemonic::OP_SUBPIECE) {
            LOG(ERROR) << "SUBPIECE Operation with invalid input operands or invalid "
                          "operation. key: "
                       << op.key;
            return {};
        }

        auto type_it = type_builder().GetSerializedTypes().find(*op.type);
        if (type_it == type_builder().GetSerializedTypes().end()) {
            LOG(ERROR) << "SUBPIECE Operation type is not serialized. key: " << op.key;
            return {};
        }

        auto merge_to_next  = !op.output.has_value();
        const auto &op_type = type_it->second;
        auto op_location    = SourceLocation(ctx.getSourceManager(), op.key);

        // input[1] is the byte offset; the bit-shift amount is byte_offset * 8.
        uint32_t byte_offset = op.inputs[1].value.value_or(0);
        unsigned shift_bits  = byte_offset * 8;

        auto *input_stmt = create_varnode(ctx, function, op.inputs[0]);
        if (!input_stmt) {
            LOG(ERROR) << "SUBPIECE: input varnode produced null Stmt. key: " << op.key;
            return {};
        }
        auto *expr = clang::dyn_cast< clang::Expr >(input_stmt);
        if (!expr) {
            LOG(ERROR) << "SUBPIECE: input varnode is not an Expr. key: " << op.key;
            return {};
        }

        // #250 guard: SUBPIECE is scalar — Array-typed operands trip Sema.
        if (expr->getType()->isArrayType() || op_type->isArrayType()) {
            LOG(ERROR) << "SUBPIECE: array-typed operand/result (issue #250). "
                       << "input='" << expr->getType().getAsString()
                       << "' op='" << op_type.getAsString()
                       << "' key: " << op.key;
            return {};
        }

        // Record (struct/union) types cannot participate in bitwise shift/mask
        // arithmetic.  When SUBPIECE operates on a record type, emit a
        // reinterpret-cast to the output type and skip the arithmetic path.
        if (expr->getType()->isRecordType() || op_type->isRecordType()) {
            clang::Expr *result_expr = expr;
            if (!ctx.hasSameUnqualifiedType(expr->getType(), op_type)) {
                result_expr = make_reinterpret_cast(ctx, expr, op_type, op_location);
                if (!result_expr) {
                    LOG(ERROR) << "SUBPIECE: reinterpret-cast yielded null Expr. key: "
                               << op.key;
                    return std::make_pair(nullptr, false);
                }
            }
            if (merge_to_next) {
                return std::make_pair(static_cast< clang::Stmt * >(result_expr), merge_to_next);
            }
            auto *out_stmt_in = create_varnode(ctx, function, *op.output);
            if (!out_stmt_in) {
                LOG(ERROR) << "SUBPIECE: record-type output varnode produced null Stmt. key: "
                           << op.key;
                return std::make_pair(nullptr, false);
            }
            auto *out_expr = clang::dyn_cast< clang::Expr >(out_stmt_in);
            if (!out_expr) {
                LOG(ERROR) << "SUBPIECE: record-type output varnode is not an Expr. key: "
                           << op.key;
                return std::make_pair(nullptr, false);
            }
            auto out_result = sema().CreateBuiltinBinOp(
                op_location, clang::BO_Assign, out_expr, result_expr
            );
            if (out_result.isInvalid()) {
                LOG(ERROR) << "SUBPIECE record-type output assignment failed. key: " << op.key;
                return std::make_pair(nullptr, false);
            }
            auto *out_stmt = out_result.getAs< clang::Stmt >();
            if (!out_stmt) {
                LOG(ERROR) << "SUBPIECE: record-type output assignment yielded null Stmt. key: "
                           << op.key;
                return std::make_pair(nullptr, false);
            }
            return std::make_pair(out_stmt, merge_to_next);
        }

        // SUBPIECE is a bit-extraction: shift the source right by the byte
        // offset, then mask to the output width.  C/C++ define neither `>>` nor
        // `&` on pointer operands, so the arithmetic must run in an integer
        // domain.  Pick that domain (`arith_type`):
        //   * output is a pointer  -> a same-width unsigned integer surrogate,
        //     converting the final result back to the pointer type below.  This
        //     is the issue #264 case: Ghidra types the SUBPIECE result as a
        //     pointer while the source is an integer.
        //   * a pointer-typed source -> a same-width unsigned integer via
        //     cast_pointer_to_int (mirrors the INT_ZEXT pointer guard, #224).
        //   * otherwise              -> the output type (existing behaviour).
        bool output_is_pointer = op_type->isPointerType();
        clang::QualType arith_type = op_type;
        if (output_is_pointer) {
            auto ptr_width = static_cast< unsigned >(ctx.getTypeSize(op_type));
            arith_type     = ctx.getIntTypeForBitwidth(ptr_width, /*Signed=*/false);
            if (arith_type.isNull()) {
                arith_type = ctx.getUIntPtrType();
            }
        }

        if (expr->getType()->isPointerType()) {
            auto src_width = static_cast< unsigned >(ctx.getTypeSize(expr->getType()));
            auto src_int   = ctx.getIntTypeForBitwidth(src_width, /*Signed=*/false);
            if (src_int.isNull()) {
                src_int = ctx.getUIntPtrType();
            }
            expr = cast_pointer_to_int(
                ctx, expr, src_int, op_location, PtrToIntExtension::kZero, op.key
            );
            if (!expr) {
                LOG(ERROR) << "SUBPIECE: failed to cast pointer source to integer. key: "
                           << op.key;
                return {};
            }
        }

        if (!ctx.hasSameUnqualifiedType(expr->getType(), arith_type)) {
            auto *casted_expr = make_cast(ctx, expr, arith_type, op_location);
            if (!casted_expr) {
                // Loud-fail rather than shifting/masking an operand of the wrong
                // type, which would either trip Sema downstream or miscompile.
                LOG(ERROR) << "SUBPIECE: failed to cast operand to arithmetic type '"
                           << arith_type.getAsString() << "'. key: " << op.key;
                return {};
            }
            expr = casted_expr;
        }

        // SUBPIECE uses bitwise shift and mask which are invalid on floating-point
        // types.  Cast the expression to an unsigned integer of the same width first
        // so that the shift/mask operations are well-formed.
        if (expr->getType()->isFloatingType()) {
            auto float_size = static_cast< unsigned >(ctx.getTypeSize(expr->getType()));
            auto int_type   = ctx.getIntTypeForBitwidth(float_size, /*Signed=*/false);
            if (int_type.isNull()) {
                // No exact-width integer (e.g. 80-bit long double).
                // Use the smallest standard type that covers all bits.
                if (float_size <= 32) {
                    int_type = ctx.UnsignedIntTy;
                } else if (float_size <= 64) {
                    int_type = ctx.UnsignedLongLongTy;
                } else {
                    int_type = ctx.getIntTypeForBitwidth(128, /*Signed=*/false);
                    if (int_type.isNull()) {
                        int_type = ctx.UnsignedLongLongTy;
                    }
                }
            }
            expr = make_cast(ctx, expr, int_type, op_location);
            if (!expr) {
                LOG(ERROR) << "SUBPIECE failed to cast float to integer. key: " << op.key;
                return {};
            }
        }

        clang::Expr *result_expr = expr;
        // The byte offset selects the output-sized window starting `byte_offset`
        // bytes into the operand.  When that offset reaches or exceeds the
        // operand width, every selected bit lies past the value, so the result
        // is 0.  Emitting `x >> N` with N >= width would be UB in C and lower to
        // a poison `lshr` in LLVM, so synthesize the zero directly.
        // Use getIntWidth (not getTypeSize): they differ for _Bool (1 vs 8) and
        // _BitInt(N), and IntegerLiteral::Create asserts the APInt width equals
        // getIntWidth(type).
        unsigned operand_bits = ctx.getIntWidth(expr->getType());
        if (operand_bits != 0 && shift_bits >= operand_bits) {
            result_expr = MakeIntLiteralPrintable(
                ctx, 0, expr->getType(), /*is_signed=*/false, op_location
            );
        } else if (shift_bits != 0) {
            // Apply right-shift only when byte_offset > 0 (skip ">> 0").
            auto *expr_with_paren = new (ctx)
                clang::ParenExpr(op_location, op_location, expr);

            auto *shift_value = clang::IntegerLiteral::Create(
                ctx, llvm::APInt(ctx.getIntWidth(ctx.IntTy), shift_bits), ctx.IntTy,
                op_location
            );
            auto shifted_result = sema().CreateBuiltinBinOp(
                op_location, clang::BO_Shr, expr_with_paren, shift_value
            );
            if (shifted_result.isInvalid()) {
                LOG(ERROR) << "SUBPIECE invalid shifted result. key: " << op.key;
                return std::make_pair(nullptr, false);
            }
            result_expr = shifted_result.getAs< clang::Expr >();
            if (!result_expr) {
                LOG(ERROR) << "SUBPIECE: shifted result yielded null Expr. key: "
                           << op.key;
                return std::make_pair(nullptr, false);
            }
        }

        // Apply a bit-mask to extract only the output-sized bits.
        // Skip the mask when it covers all bits of the integer width (would be no-op).
        unsigned out_bits      = static_cast< unsigned >(ctx.getTypeSize(op_type));
        unsigned int_width     = ctx.getIntWidth(ctx.IntTy);
        if (out_bits > 0 && out_bits < int_width) {
            auto mask_value = llvm::APInt::getLowBitsSet(int_width, out_bits);
            auto *mask =
                clang::IntegerLiteral::Create(ctx, mask_value, ctx.IntTy, op_location);

            auto *paren_expr = new (ctx)
                clang::ParenExpr(op_location, op_location, result_expr);

            auto result = sema().CreateBuiltinBinOp(
                op_location, clang::BO_And, paren_expr, mask
            );

            if (result.isInvalid()) {
                LOG(ERROR) << "SUBPIECE invalid AND-mask result. key: " << op.key;
                return std::make_pair(nullptr, false);
            }

            result_expr = result.getAs< clang::Expr >();
            if (!result_expr) {
                LOG(ERROR) << "SUBPIECE: AND-mask result yielded null Expr. key: "
                           << op.key;
                return std::make_pair(nullptr, false);
            }
        }

        result_expr =
            new (ctx) clang::ParenExpr(op_location, op_location, result_expr);

        // The shift/mask ran in an integer surrogate domain.  When the SUBPIECE
        // output type is a pointer (issue #264), convert the integer result back
        // to that pointer type (CK_IntegralToPointer) so the merge/assignment
        // sees the declared type.
        if (output_is_pointer) {
            auto *as_ptr = make_cast(ctx, result_expr, op_type, op_location);
            if (!as_ptr) {
                LOG(ERROR) << "SUBPIECE: failed to cast integer result to pointer output. key: "
                           << op.key;
                return std::make_pair(nullptr, false);
            }
            result_expr = as_ptr;
        }

        if (merge_to_next) {
            return std::make_pair(result_expr, merge_to_next);
        }

        auto *out_stmt_in = create_varnode(ctx, function, *op.output);
        if (!out_stmt_in) {
            LOG(ERROR) << "SUBPIECE: output varnode produced null Stmt. key: " << op.key;
            return std::make_pair(nullptr, false);
        }
        auto *out_expr = clang::dyn_cast< clang::Expr >(out_stmt_in);
        if (!out_expr) {
            LOG(ERROR) << "SUBPIECE: output varnode is not an Expr. key: " << op.key;
            return std::make_pair(nullptr, false);
        }
        // Route through create_assign_operation for scalar → byte-array (#248).
        // The helper picks the right lowering: BO_Assign for same-type scalar,
        // element-wise copy for same-type array, pointer-cast partial store
        // for scalar → array.  SUBPIECE outputs are scalar in practice, but
        // the helper handles all shapes uniformly.
        auto *out_stmt = create_assign_operation(ctx, result_expr, out_expr, op_location);
        if (!out_stmt) {
            LOG(ERROR) << "SUBPIECE invalid output assignment. key: " << op.key;
            return std::make_pair(nullptr, false);
        }
        return std::make_pair(out_stmt, merge_to_next);
    }

    std::pair< clang::Stmt *, bool > OpBuilder::create_int_zext(
        clang::ASTContext &ctx, const Function &function, const Operation &op
    ) {
        if (op.inputs.size() != 1U || op.mnemonic != Mnemonic::OP_INT_ZEXT) {
            LOG(ERROR) << "INT_ZEXT operation is invalid or has invalid input operand. key: "
                       << op.key << "\n";
            return {};
        }

        auto merge_to_next = !op.output.has_value();
        auto op_loc        = SourceLocation(ctx.getSourceManager(), op.key);
        auto *input_expr =
            AS_EXPR_OR_NULL(create_varnode(ctx, function, op.inputs[0]), op.key);
        if (!input_expr) {
            return {};
        }

        auto target_type_opt = lookup_op_type(op);
        if (!target_type_opt) {
            return {};
        }
        auto target_type = *target_type_opt;
        target_type = integer_target_for_int_ext(ctx, target_type, op.output ? op.output->size : 0u);

        if (input_expr->getType()->isPointerType()) {
            // PerformImplicitConversion asserts inside clang 22 (SemaExprCXX.cpp:4681)
            // for pointer→int before returning Invalid, so the
            // BuildCStyleCastExpr fallback below would never run.  See #224.
            input_expr = cast_pointer_to_int(ctx, input_expr, target_type, op_loc,
                                             PtrToIntExtension::kZero, op.key);
            if (!input_expr) {
                return {};
            }
        } else {
            auto implicit_result = sema().PerformImplicitConversion(
                input_expr, target_type, clang::AssignmentAction::Converting, true
            );

            if (implicit_result.isInvalid()) {
                // If fail to perform implcit cast perform explicit cast
                auto result = sema().BuildCStyleCastExpr(
                    op_loc, ctx.getTrivialTypeSourceInfo(target_type), op_loc, input_expr
                );

                input_expr = result.getAs< clang::Expr >();
            } else {
                input_expr = implicit_result.getAs< clang::Expr >();
            }
        }

        if (merge_to_next) {
            return { input_expr, merge_to_next };
        }

        auto *output_expr =
            AS_EXPR_OR_NULL(create_varnode(ctx, function, *op.output), op.key);
        if (!output_expr) {
            return {};
        }

        return { create_assign_operation(ctx, input_expr, output_expr, op_loc), false };
    }

    std::pair< clang::Stmt *, bool > OpBuilder::create_int_sext(
        clang::ASTContext &ctx, const Function &function, const Operation &op
    ) {
        if (op.inputs.size() != 1U || op.mnemonic != Mnemonic::OP_INT_SEXT) {
            LOG(ERROR) << "INT_SEXT operation is invalid or has invalid input operand. key: "
                       << op.key << "\n";
            return {};
        }

        auto merge_to_next = !op.output.has_value();
        auto op_loc        = SourceLocation(ctx.getSourceManager(), op.key);

        auto *input_expr =
            AS_EXPR_OR_NULL(create_varnode(ctx, function, op.inputs[0]), op.key);
        if (!input_expr) {
            return {};
        }

        auto target_type_opt = lookup_op_type(op);
        if (!target_type_opt) {
            return {};
        }
        auto target_type = *target_type_opt;
        target_type = integer_target_for_int_ext(ctx, target_type, op.output ? op.output->size : 0u);

        if (input_expr->getType()->isPointerType()) {
            // Sign-extension over a pointer requires the intptr_t intermediate;
            // a single (target)ptr lowers as ptrtoint+zext.  See #224 follow-up.
            input_expr = cast_pointer_to_int(ctx, input_expr, target_type, op_loc,
                                             PtrToIntExtension::kSign, op.key);
            if (!input_expr) {
                return {};
            }
        } else {
            auto implicit_result = sema().PerformImplicitConversion(
                input_expr, target_type, clang::AssignmentAction::Converting, true
            );

            if (implicit_result.isInvalid()) {
                // If fail to perform implcit cast perform explicit cast
                auto result = sema().BuildCStyleCastExpr(
                    SourceLocation(ctx.getSourceManager(), op.key),
                    ctx.getTrivialTypeSourceInfo(target_type),
                    SourceLocation(ctx.getSourceManager(), op.key), input_expr
                );

                input_expr = result.getAs< clang::Expr >();
            } else {
                input_expr = implicit_result.getAs< clang::Expr >();
            }
        }

        if (merge_to_next) {
            return { input_expr, merge_to_next };
        }

        auto *output_expr =
            AS_EXPR_OR_NULL(create_varnode(ctx, function, *op.output), op.key);
        if (!output_expr) {
            return {};
        }

        return { create_assign_operation(ctx, input_expr, output_expr, op_loc), false };
    }

    std::pair< clang::Stmt *, bool > OpBuilder::create_int_carry(
        clang::ASTContext &ctx, const Function &function, const Operation &op
    ) {
        if (op.inputs.empty() || op.inputs.size() != 2U) {
            LOG(ERROR) << "Skipping, carry operation due to input operands. key: " << op.key
                       << "\n";
            return {};
        }

        auto op_loc = SourceLocation(ctx.getSourceManager(), op.key);
        auto *input0 =
            AS_EXPR_OR_NULL(create_varnode(ctx, function, op.inputs[0]), op.key);
        auto *input1 =
            AS_EXPR_OR_NULL(create_varnode(ctx, function, op.inputs[1]), op.key);
        if (!input0 || !input1) {
            return {};
        }

        auto sum =
            sema().BuildBinOp(sema().getCurScope(), op_loc, clang::BO_Add, input0, input1);
        assert(!sum.isInvalid() && "Failed to create add operation");

        auto carry = sema().BuildBinOp(
            sema().getCurScope(), op_loc, clang::BO_LT, sum.getAs< clang::Expr >(), input0
        );
        assert(!carry.isInvalid() && "Failed to create carry operation");

        if (!op.output.has_value()) {
            return { carry.getAs< clang::Stmt >(), true };
        }

        auto *output =
            AS_EXPR_OR_NULL(create_varnode(ctx, function, *op.output), op.key);
        if (!output) {
            return {};
        }

        return { create_assign_operation(ctx, carry.getAs< clang::Expr >(), output, op_loc),
                 false };
    }

    std::pair< clang::Stmt *, bool > OpBuilder::create_int_scarry(
        clang::ASTContext &ctx, const Function &function, const Operation &op
    ) {
        if (op.inputs.empty() || op.inputs.size() != 2U) {
            LOG(ERROR) << "Skipping, scarry operation due to input operands. key: " << op.key
                       << "\n";
            return {};
        }

        auto op_loc  = SourceLocation(ctx.getSourceManager(), op.key);
        auto *input0 =
            AS_EXPR_OR_NULL(create_varnode(ctx, function, op.inputs[0]), op.key);
        auto *input1 =
            AS_EXPR_OR_NULL(create_varnode(ctx, function, op.inputs[1]), op.key);
        if (!input0 || !input1) {
            return {};
        }

        // Compute sum = input0 + input1
        auto sum =
            sema().BuildBinOp(sema().getCurScope(), op_loc, clang::BO_Add, input0, input1);
        assert(!sum.isInvalid() && "Failed to create add operation");

        // Signed overflow on addition occurs when both inputs have the same sign AND
        // the result has a different sign from the inputs.
        // Formula: (~(input0 ^ input1)) & (input0 ^ sum) < 0

        // xor_inputs = input0 ^ input1
        auto xor_inputs =
            sema().BuildBinOp(sema().getCurScope(), op_loc, clang::BO_Xor, input0, input1);
        assert(!xor_inputs.isInvalid() && "Failed to create xor operation");

        // not_xor_inputs = ~(input0 ^ input1)
        // MSB is 1 when both inputs have the same sign
        auto not_xor_inputs = sema().BuildUnaryOp(
            sema().getCurScope(), op_loc, clang::UO_Not, xor_inputs.getAs< clang::Expr >()
        );
        assert(!not_xor_inputs.isInvalid() && "Failed to create bitwise not operation");

        // xor_result = input0 ^ sum
        // MSB is 1 when the sum's sign differs from input0
        auto xor_result = sema().BuildBinOp(
            sema().getCurScope(), op_loc, clang::BO_Xor, input0,
            sum.getAs< clang::Expr >()
        );
        assert(!xor_result.isInvalid() && "Failed to create xor operation");

        // and_result = not_xor_inputs & xor_result
        auto and_result = sema().BuildBinOp(
            sema().getCurScope(), op_loc, clang::BO_And, not_xor_inputs.getAs< clang::Expr >(),
            xor_result.getAs< clang::Expr >()
        );
        assert(!and_result.isInvalid() && "Failed to create and operation");

        // scarry = and_result < 0
        auto *zero = MakeIntLiteralPrintable(
            ctx, 0, input0->getType(), /*is_signed=*/true, op_loc
        );
        auto scarry = sema().BuildBinOp(
            sema().getCurScope(), op_loc, clang::BO_LT, and_result.getAs< clang::Expr >(),
            zero
        );
        assert(!scarry.isInvalid() && "Failed to create scarry comparison");

        if (!op.output.has_value()) {
            return { scarry.getAs< clang::Stmt >(), true };
        }

        auto *output =
            AS_EXPR_OR_NULL(create_varnode(ctx, function, *op.output), op.key);
        if (!output) {
            return {};
        }

        return { create_assign_operation(ctx, scarry.getAs< clang::Expr >(), output, op_loc),
                 false };
    }

    std::pair< clang::Stmt *, bool > OpBuilder::create_int_sborrow(
        clang::ASTContext &ctx, const Function &function, const Operation &op
    ) {
        if (op.inputs.empty() || op.inputs.size() != 2U) {
            LOG(ERROR) << "Skipping, sborrow operation due to input operands. key: " << op.key
                       << "\n";
            return {};
        }

        auto op_loc  = SourceLocation(ctx.getSourceManager(), op.key);
        auto *input0 =
            AS_EXPR_OR_NULL(create_varnode(ctx, function, op.inputs[0]), op.key);
        auto *input1 =
            AS_EXPR_OR_NULL(create_varnode(ctx, function, op.inputs[1]), op.key);
        if (!input0 || !input1) {
            return {};
        }

        // Compute diff = input0 - input1
        auto diff =
            sema().BuildBinOp(sema().getCurScope(), op_loc, clang::BO_Sub, input0, input1);
        assert(!diff.isInvalid() && "Failed to create sub operation");

        // Signed overflow occurs when input0 and input1 have different signs AND
        // input0 and diff have different signs.
        // Formula: ((input0 ^ input1) & (input0 ^ diff)) < 0

        // xor_inputs = input0 ^ input1
        auto xor_inputs =
            sema().BuildBinOp(sema().getCurScope(), op_loc, clang::BO_Xor, input0, input1);
        assert(!xor_inputs.isInvalid() && "Failed to create xor operation");

        // xor_result = input0 ^ diff
        auto xor_result = sema().BuildBinOp(
            sema().getCurScope(), op_loc, clang::BO_Xor, input0,
            diff.getAs< clang::Expr >()
        );
        assert(!xor_result.isInvalid() && "Failed to create xor operation");

        // and_result = xor_inputs & xor_result
        auto and_result = sema().BuildBinOp(
            sema().getCurScope(), op_loc, clang::BO_And, xor_inputs.getAs< clang::Expr >(),
            xor_result.getAs< clang::Expr >()
        );
        assert(!and_result.isInvalid() && "Failed to create and operation");

        // sborrow = and_result < 0
        auto *zero = MakeIntLiteralPrintable(
            ctx, 0, input0->getType(), /*is_signed=*/true, op_loc
        );
        auto sborrow = sema().BuildBinOp(
            sema().getCurScope(), op_loc, clang::BO_LT, and_result.getAs< clang::Expr >(),
            zero
        );
        assert(!sborrow.isInvalid() && "Failed to create sborrow comparison");

        if (!op.output.has_value()) {
            return { sborrow.getAs< clang::Stmt >(), true };
        }

        auto *output =
            AS_EXPR_OR_NULL(create_varnode(ctx, function, *op.output), op.key);
        if (!output) {
            return {};
        }

        return { create_assign_operation(ctx, sborrow.getAs< clang::Expr >(), output, op_loc),
                 false };
    }

    std::pair< clang::Stmt *, bool > OpBuilder::create_int_2comp(
        clang::ASTContext &ctx, const Function &function, const Operation &op
    ) {
        return create_unary_operation(ctx, function, op, clang::UnaryOperatorKind::UO_Minus);
    }

    std::pair< clang::Stmt *, bool > OpBuilder::create_unary_operation(
        clang::ASTContext &ctx, const Function &function, const Operation &op,
        clang::UnaryOperatorKind kind
    ) {
        if (op.inputs.empty() || op.inputs.size() > 1U) {
            LOG(ERROR
            ) << "Skipping, unary operation with more than one or zero input operand. key: "
              << op.key << "\n";
            return {};
        }

        auto op_loc = SourceLocation(ctx.getSourceManager(), op.key);
        // ADDRESS_OF wants the raw storage lvalue (#225); narrowing first
        // would emit `&*(T*)&arr` instead of `&arr`.
        bool narrow_input = (kind != clang::UO_AddrOf);
        auto *input_expr = AS_EXPR_OR_NULL(
            create_varnode(ctx, function, op.inputs[0], {}, narrow_input),
            op.key);
        if (!input_expr) {
            return {};
        }

        // Coerce record operands to integers for C scalar operators. The
        // reinterpret is load-bearing even for ADDRESS_OF (it normalizes the
        // operand into an addressable form), so it always runs; only mute the
        // oversized-record warning there — `&fd_set` / `&stat` are valid.
        input_expr = coerce_record_to_integer(
            ctx, input_expr, op_loc, /*quiet_oversized=*/kind == clang::UO_AddrOf);

        clang::Expr *result_expr = nullptr;
        // ADDRESS_OF on an array decays to pointer-to-element (Ghidra's `T*`
        // op type); `&arr` would yield `T(*)[N]` and break call-arg passing.
        if (kind == clang::UO_AddrOf && input_expr->getType()->isArrayType()) {
            auto decayed_type = ctx.getArrayDecayedType(input_expr->getType());
            result_expr = make_implicit_cast(
                ctx, input_expr, decayed_type, clang::CastKind::CK_ArrayToPointerDecay
            );
        }
        if (result_expr == nullptr) {
            auto unary_operation = sema().CreateBuiltinUnaryOp(op_loc, kind, input_expr);
            if (unary_operation.isInvalid()) {
                LOG(ERROR) << "Unary operation failed on operand. key: " << op.key << "\n";
                return std::make_pair(nullptr, false);
            }
            result_expr = unary_operation.getAs< clang::Expr >();
        }

        if (!op.output.has_value()) {
            return { result_expr, true };
        }

        auto *output_expr =
            AS_EXPR_OR_NULL(create_varnode(ctx, function, *op.output), op.key);
        if (!output_expr) {
            return {};
        }

        return { create_assign_operation(ctx, result_expr, output_expr, op_loc), false };
    }

    std::pair< clang::Stmt *, bool > OpBuilder::create_binary_operation(
        clang::ASTContext &ctx, const Function &function, const Operation &op,
        clang::BinaryOperatorKind kind
    ) {
        if (op.inputs.size() != 2U) {
            LOG(ERROR) << "Skipping, binary operation with insufficient input operand. key: "
                       << op.key << "\n";
            return {};
        }

        auto op_loc = SourceLocation(ctx.getSourceManager(), op.key);

        auto *lhs =
            AS_EXPR_OR_NULL(create_varnode(ctx, function, op.inputs[0]), op.key);
        auto *rhs =
            AS_EXPR_OR_NULL(create_varnode(ctx, function, op.inputs[1]), op.key);
        if (!lhs || !rhs) {
            return {};
        }

        // Coerce record (struct/union) operands to integers so that C
        // arithmetic and bitwise operators are valid.
        lhs = coerce_record_to_integer(ctx, lhs, op_loc);
        rhs = coerce_record_to_integer(ctx, rhs, op_loc);

        // The CIR backend can't lower void*/function-pointer arithmetic (and
        // crashes on the failed lowering). For additive ops, reinterpret such
        // operands as char* (byte arithmetic), as create_ptradd does for bases.
        if (kind == clang::BO_Add || kind == clang::BO_Sub) {
            auto char_ptr_ty = ctx.getPointerType(ctx.CharTy);
            auto to_byte_ptr = [&](clang::Expr *e) -> clang::Expr * {
                auto t = e->getType();
                if (t->isPointerType()
                    && (t->getPointeeType()->isVoidType()
                        || t->getPointeeType()->isFunctionType()))
                {
                    if (auto *c = make_cast(ctx, e, char_ptr_ty, op_loc)) { return c; }
                }
                return e;
            };
            lhs = to_byte_ptr(lhs);
            rhs = to_byte_ptr(rhs);
        }

        auto make_paren_expr = [&](clang::ASTContext &ctx, clang::Expr *expr,
                                   clang::SourceLocation loc) -> clang::Expr * {
            if (auto *uo = clang::dyn_cast< clang::UnaryOperator >(expr); uo) {
                auto *paren = new (ctx) clang::ParenExpr(loc, loc, expr);
                assert(paren != nullptr && "Failed to create paren expression.");
                return paren;
            }
            return expr;
        };

        // Suppress diagnostics for the initial attempt — if it fails on
        // oversized record types, we'll retry with a coerced fallback.
        // Suppressing prevents the error from being counted/printed,
        // avoiding the need to Reset() (which clears ALL accumulated state).
        auto &diags = sema().getDiagnostics();
        const bool prev_suppress = diags.getSuppressAllDiagnostics();
        diags.setSuppressAllDiagnostics(true);
        auto result = sema().CreateBuiltinBinOp(
            op_loc, kind, make_paren_expr(ctx, lhs, op_loc), make_paren_expr(ctx, rhs, op_loc)
        );
        diags.setSuppressAllDiagnostics(prev_suppress);

        if (result.isInvalid()) {
            // Fallback: force-coerce both operands to unsigned long long
            // (first 64 bits) and retry.  This handles oversized records
            // (e.g. 192-bit C++ basic_string unions) where
            // coerce_record_to_integer couldn't fit them into a scalar.

            auto *fallback_lhs = make_reinterpret_cast(ctx, lhs, ctx.UnsignedLongLongTy, op_loc);
            auto *fallback_rhs = make_reinterpret_cast(ctx, rhs, ctx.UnsignedLongLongTy, op_loc);
            if (fallback_lhs && fallback_rhs) {
                result = sema().CreateBuiltinBinOp(
                    op_loc, kind,
                    make_paren_expr(ctx, fallback_lhs, op_loc),
                    make_paren_expr(ctx, fallback_rhs, op_loc));
            }

            if (result.isInvalid()) {
                LOG(ERROR) << "Binary operation failed on operands (after fallback). key: "
                           << op.key << "\n";
                return std::make_pair(nullptr, false);
            }
            LOG(WARNING) << "Binary operation on oversized record coerced to u64. key: "
                         << op.key << "\n";
        }

        if (!op.output) {
            return std::make_pair(result.getAs< clang::Stmt >(), true);
        }

        auto *output_expr =
            AS_EXPR_OR_NULL(create_varnode(ctx, function, *op.output), op.key);
        if (!output_expr) {
            return {};
        }

        return {
            create_assign_operation(ctx, result.getAs< clang::Expr >(), output_expr, op_loc),
            false
        };
    }

    std::pair< clang::Stmt *, bool > OpBuilder::create_float_abs(
        clang::ASTContext &ctx, const Function &function, const Operation &op
    ) {
        if ((op.mnemonic != Mnemonic::OP_FLOAT_ABS) || (op.inputs.size() != 1U)) {
            LOG(ERROR) << "FLOAT_FLOOR operation is invalid or has invalid input operand. key: "
                       << op.key << "\n";
            return {};
        }

        if (!type_builder().GetSerializedTypes().contains(*op.type)) {
            LOG(ERROR) << "FLOAT_FLOOR operation type is not serialized. key: " << op.key
                       << "\n";
            return {};
        }

        return create_builtin_call_expr(ctx, function, op, clang::Builtin::BIabs);
    }

    std::pair< clang::Stmt *, bool > OpBuilder::create_float_sqrt(
        clang::ASTContext &ctx, const Function &function, const Operation &op
    ) {
        if ((op.mnemonic != Mnemonic::OP_FLOAT_SQRT) || (op.inputs.size() != 1U)) {
            LOG(ERROR) << "FLOAT_FLOOR operation is invalid or has invalid input operand. key: "
                       << op.key << "\n";
            return {};
        }

        if (!type_builder().GetSerializedTypes().contains(*op.type)) {
            LOG(ERROR) << "FLOAT_FLOOR operation type is not serialized. key: " << op.key
                       << "\n";
            return {};
        }

        return create_builtin_call_expr(ctx, function, op, clang::Builtin::BIsqrt);
    }

    std::pair< clang::Stmt *, bool > OpBuilder::create_float_floor(
        clang::ASTContext &ctx, const Function &function, const Operation &op
    ) {
        if ((op.mnemonic != Mnemonic::OP_FLOAT_FLOOR) || (op.inputs.size() != 1U)) {
            LOG(ERROR) << "FLOAT_FLOOR operation is invalid or has invalid input operand. key: "
                       << op.key << "\n";
            return {};
        }

        if (!type_builder().GetSerializedTypes().contains(*op.type)) {
            LOG(ERROR) << "FLOAT_FLOOR operation type is not serialized. key: " << op.key
                       << "\n";
            return {};
        }

        return create_builtin_call_expr(ctx, function, op, clang::Builtin::BIfloorf);
    }

    std::pair< clang::Stmt *, bool > OpBuilder::create_float_ceil(
        clang::ASTContext &ctx, const Function &function, const Operation &op
    ) {
        if ((op.mnemonic != Mnemonic::OP_FLOAT_CEIL) || (op.inputs.size() != 1U)) {
            LOG(ERROR) << "FLOAT_CEIL operation is invalid or has invalid input operand. key: "
                       << op.key << "\n";
            return {};
        }

        if (!type_builder().GetSerializedTypes().contains(*op.type)) {
            LOG(ERROR) << "FLOAT_CEIL operation type is not serialized. key: " << op.key
                       << "\n";
            return {};
        }

        return create_builtin_call_expr(ctx, function, op, clang::Builtin::BIceilf);
    }

    std::pair< clang::Stmt *, bool > OpBuilder::create_float_round(
        clang::ASTContext &ctx, const Function &function, const Operation &op
    ) {
        if ((op.mnemonic != Mnemonic::OP_FLOAT_ROUND) || (op.inputs.size() != 1U)) {
            LOG(ERROR) << "FLOAT_ROUND operation is invalid or has invalid input operand. key: "
                       << op.key << "\n";
            return {};
        }

        if (!type_builder().GetSerializedTypes().contains(*op.type)) {
            LOG(ERROR) << "FLOAT_ROUND operation type is not serialized. key: " << op.key
                       << "\n";
            return {};
        }

        return create_builtin_call_expr(ctx, function, op, clang::Builtin::BIroundf);
    }

    std::pair< clang::Stmt *, bool > OpBuilder::create_popcount(
        clang::ASTContext &ctx, const Function &function, const Operation &op
    ) {
        if (op.inputs.size() != 1U || op.mnemonic != Mnemonic::OP_POPCOUNT) {
            LOG(ERROR) << "POPCOUNT operation is invalid or has invalid input operand. key: "
                       << op.key << "\n";
            return {};
        }

        // Use __builtin_popcount for population count
        return create_builtin_call_expr(
            ctx, function, op, clang::Builtin::BI__builtin_popcount
        );
    }

    std::pair< clang::Stmt *, bool > OpBuilder::create_lzcount(
        clang::ASTContext &ctx, const Function &function, const Operation &op
    ) {
        if (op.inputs.size() != 1U || op.mnemonic != Mnemonic::OP_LZCOUNT) {
            LOG(ERROR) << "LZCOUNT operation is invalid or has invalid input operand. key: "
                       << op.key << "\n";
            return {};
        }

        // Use __builtin_clz for count leading zeros
        return create_builtin_call_expr(ctx, function, op, clang::Builtin::BI__builtin_clz);
    }

    std::pair< clang::Stmt *, bool > OpBuilder::create_builtin_call_expr(
        clang::ASTContext &ctx, const Function &function, const Operation &op,
        clang::Builtin::ID id
    ) {
        auto op_loc = SourceLocation(ctx.getSourceManager(), op.key);

        auto *input_expr =
            AS_EXPR_OR_NULL(create_varnode(ctx, function, op.inputs[0]), op.key);
        if (!input_expr) {
            return {};
        }

        std::vector args = { input_expr };
        auto *call_expr = create_builtin_call(ctx, sema(), id, args, op_loc);

        if (!op.output.has_value()) {
            return { call_expr, true };
        }

        auto *output_expr =
            AS_EXPR_OR_NULL(create_varnode(ctx, function, *op.output), op.key);
        if (!output_expr) {
            return {};
        }
        return { create_assign_operation(ctx, call_expr, output_expr), false };
    }

    std::pair< clang::Stmt *, bool > OpBuilder::create_int2float(
        clang::ASTContext &ctx, const Function &function, const Operation &op
    ) {
        if ((op.mnemonic != Mnemonic::OP_INT2FLOAT) || (op.inputs.size() != 1U)) {
            LOG(ERROR) << "INT2FLOAT operation is invalid or has invalid input operand. key: "
                       << op.key << "\n";
            return {};
        }

        auto op_type = type_builder().GetSerializedType(*op.type);
        if (op_type.isNull()) {
            LOG(ERROR) << "INT2FLOAT operation type is not serialized. key: " << op.key << "\n";
            return {};
        }

        auto op_loc         = SourceLocation(ctx.getSourceManager(), op.key);

        auto *input_expr =
            AS_EXPR_OR_NULL(create_varnode(ctx, function, op.inputs[0]), op.key);
        if (!input_expr) {
            return {};
        }

        if (!input_expr->isPRValue()) {
            input_expr = make_implicit_cast(
                ctx, input_expr, input_expr->getType(), clang::CastKind::CK_LValueToRValue
            );
        }

        auto *cast_expr =
            make_implicit_cast(ctx, input_expr, op_type, clang::CK_IntegralToFloating);
        if (!op.output.has_value()) {
            return { cast_expr, true };
        }

        auto *output_expr =
            AS_EXPR_OR_NULL(create_varnode(ctx, function, *op.output), op.key);
        if (!output_expr) {
            return {};
        }

        return { create_assign_operation(ctx, cast_expr, output_expr, op_loc), false };
    }

    std::pair< clang::Stmt *, bool > OpBuilder::create_float_nan(
        clang::ASTContext &ctx, const Function &function, const Operation &op
    ) {
        if ((op.inputs.size() != 1U) || (op.mnemonic != Mnemonic::OP_FLOAT_NAN)) {
            LOG(ERROR) << "FLOAT_NAN operation is invalid or has invalid input operand. key: "
                       << op.key << "\n";
            return {};
        }

        if (!type_builder().GetSerializedTypes().contains(*op.type)) {
            LOG(ERROR) << "FLOAT_NAN operation type is not serialized. key: " << op.key << "\n";
            return {};
        }

        auto nan_value = llvm::APFloat::getQNaN(llvm::APFloat::IEEEsingle());
        auto *nan_expr = clang::FloatingLiteral::Create(
            ctx, nan_value, true, ctx.FloatTy, VirtualLoc(ctx)
        );

        auto op_loc = SourceLocation(ctx.getSourceManager(), op.key);

        auto *input_expr =
            AS_EXPR_OR_NULL(create_varnode(ctx, function, op.inputs[0]), op.key);
        if (!input_expr) {
            return {};
        }

        auto nan_check =
            sema().BuildBinOp(sema().getCurScope(), op_loc, clang::BO_NE, input_expr, nan_expr);
        assert(!nan_check.isInvalid() && "Invalid nan check");
        if (!op.output.has_value()) {
            return { nan_check.getAs< clang::Stmt >(), true };
        }

        auto *output_expr =
            AS_EXPR_OR_NULL(create_varnode(ctx, function, *op.output), op.key);
        if (!output_expr) {
            return {};
        }

        return { create_assign_operation(ctx, nan_check.get(), output_expr, op_loc), false };
    }

    std::pair< clang::Stmt *, bool > OpBuilder::create_float2float(
        clang::ASTContext &ctx, const Function &function, const Operation &op
    ) {
        if ((op.mnemonic != Mnemonic::OP_FLOAT2FLOAT) || (op.inputs.size() != 1U)) {
            LOG(ERROR) << "FLOAT2FLOAT operation is invalid or has invalid input operand. key: "
                       << op.key << "\n";
            return {};
        }

        auto op_type = type_builder().GetSerializedType(*op.type);
        if (op_type.isNull()) {
            LOG(ERROR) << "FLOAT2FLOAT operation type is not serialized. key: " << op.key
                       << "\n";
            return {};
        }

        auto op_loc         = SourceLocation(ctx.getSourceManager(), op.key);

        auto *input_expr =
            AS_EXPR_OR_NULL(create_varnode(ctx, function, op.inputs[0]), op.key);
        if (!input_expr) {
            return {};
        }

        if (!input_expr->isPRValue()) {
            input_expr = make_implicit_cast(
                ctx, input_expr, input_expr->getType(), clang::CastKind::CK_LValueToRValue
            );
        }

        auto *cast_expr = make_implicit_cast(ctx, input_expr, op_type, clang::CK_FloatingCast);
        if (!op.output.has_value()) {
            return { cast_expr, true };
        }

        auto *output_expr =
            AS_EXPR_OR_NULL(create_varnode(ctx, function, *op.output), op.key);
        if (!output_expr) {
            return {};
        }

        return { create_assign_operation(ctx, cast_expr, output_expr, op_loc), false };
    }

    std::pair< clang::Stmt *, bool > OpBuilder::create_trunc(
        clang::ASTContext &ctx, const Function &function, const Operation &op
    ) {
        if (op.inputs.size() != 1U || op.mnemonic != Mnemonic::OP_TRUNC) {
            LOG(ERROR) << "TRUNC operation is invalid or has invalid input operand. key: "
                       << op.key << "\n";
            return { nullptr, false };
        }

        auto op_type = type_builder().GetSerializedType(*op.type);
        if (op_type.isNull()) {
            LOG(ERROR) << "TRUNC operation type is not serialized. key: " << op.key << "\n";
            return { nullptr, false };
        }

        auto merge_to_next = !op.output.has_value();

        auto op_loc         = SourceLocation(ctx.getSourceManager(), op.key);

        auto *input_expr =
            AS_EXPR_OR_NULL(create_varnode(ctx, function, op.inputs[0]), op.key);
        if (!input_expr) {
            return { nullptr, false };
        }

        auto implicit_cast_result = sema().PerformImplicitConversion(
            input_expr, op_type, clang::AssignmentAction::Converting
        );
        assert(!implicit_cast_result.isInvalid());

        auto *implicit_cast = implicit_cast_result.getAs< clang::Expr >();

        if (merge_to_next) {
            return std::make_pair(implicit_cast, true);
        }

        auto *output_expr =
            AS_EXPR_OR_NULL(create_varnode(ctx, function, *op.output), op.key);
        if (!output_expr) {
            return { nullptr, false };
        }

        return { create_assign_operation(ctx, implicit_cast, output_expr, op_loc), false };
    }

    clang::Expr *OpBuilder::make_member_expr(
        clang::ASTContext &ctx, clang::Expr *base, unsigned offset, clang::SourceLocation loc
    ) {
        auto base_type = base->getType();
        if (!base_type->isPointerType() || !base_type->getPointeeType()->isRecordType()) {
            LOG(ERROR) << "Can't make member expre, base type is not pointer of record decl!\n";
            return nullptr;
        }
        if (loc.isInvalid()) loc = VirtualLoc(ctx);

        // (&E)->field ==> E.field when the base is the address of a record
        // lvalue; otherwise PTRSUB chains stack &/-> pairs that print as &&&.
        clang::Expr *dot_base = nullptr;
        if (auto *uo =
                clang::dyn_cast< clang::UnaryOperator >(base->IgnoreParenImpCasts()))
        {
            if (uo->getOpcode() == clang::UO_AddrOf
                && uo->getSubExpr()->getType()->isRecordType()
                && uo->getSubExpr()->isLValue())
            {
                dot_base = uo->getSubExpr();
            }
        }

        auto find_field_decl = [&](clang::ASTContext &ctx, clang::RecordDecl *decl,
                                   unsigned int target_offset) -> clang::FieldDecl * {
            if (decl == nullptr || !decl->isCompleteDefinition()) {
                return nullptr;
            }

            const auto &layout = ctx.getASTRecordLayout(decl);
            for (auto *field : decl->fields()) {
                auto offset =
                    static_cast< unsigned int >(layout.getFieldOffset(field->getFieldIndex()));
                if (offset >= static_cast< uint64_t >(target_offset) * 8U) {
                    return field;
                }
            }

            LOG(ERROR) << "Failed to find field decl at offset " << target_offset
                       << " in record type\n";
            return nullptr;
        };

        // Convert to rvalue if not there
        auto convert_rvalue = [&](clang::ASTContext &ctx, clang::Expr *expr) -> clang::Expr * {
            if (!expr->isPRValue()) {
                return make_implicit_cast(
                    ctx, expr, expr->getType(), clang::CastKind::CK_LValueToRValue
                );
            }
            return expr;
        };

        auto *pointee    = base_type->getPointeeType()->getAs< clang::RecordType >();
        auto *decl       = pointee->getDecl();
        // get the definition of record decl
        auto *definition = decl->getDefinition();

        auto *field = find_field_decl(ctx, definition, offset);
        if (field == nullptr) {
            // Field not found — fall back to byte-offset pointer arithmetic:
            //   *(pointee_type*)((char*)base + offset)
            auto char_ptr_type = ctx.getPointerType(ctx.CharTy);
            auto *char_ptr     = make_cast(ctx, base, char_ptr_type, loc);
            if (!char_ptr) {
                return make_reinterpret_cast(
                    ctx, base, ctx.getPointerType(base_type->getPointeeType()), loc
                );
            }
            auto *offset_lit = clang::IntegerLiteral::Create(
                ctx, llvm::APInt(ctx.getIntWidth(ctx.IntTy), offset),
                ctx.IntTy, loc
            );
            auto add_result = sema().CreateBuiltinBinOp(loc, clang::BO_Add, char_ptr, offset_lit);
            if (add_result.isInvalid()) {
                return make_reinterpret_cast(
                    ctx, base, ctx.getPointerType(base_type->getPointeeType()), loc
                );
            }
            auto result_ptr_type = ctx.getPointerType(base_type->getPointeeType());
            return make_cast(ctx, add_result.getAs< clang::Expr >(), result_ptr_type, loc);
        }

        clang::DeclarationNameInfo member_name_info(field->getDeclName(), loc);
        return sema().BuildMemberExpr(
            dot_base ? dot_base : convert_rvalue(ctx, base),
            /*IsArrow=*/dot_base == nullptr, loc, clang::NestedNameSpecifierLoc(),
            /*TemplateKWLoc=*/clang::SourceLocation(), field,
            clang::DeclAccessPair::make(field, clang::AS_public), false, member_name_info,
            field->getType(), clang::VK_LValue, clang::OK_Ordinary
        );
    }

    std::pair< clang::Stmt *, bool > OpBuilder::create_ptrsub(
        clang::ASTContext &ctx, const Function &function, const Operation &op
    ) {
        if (op.inputs.size() != 2U && op.mnemonic != Mnemonic::OP_PTRSUB) {
            LOG(ERROR) << "PTRSUB operation is invalid or has invalid input operands. key: "
                       << op.key << "\n";
            return { nullptr, false };
        }

        auto op_type = type_builder().GetSerializedType(*op.type);
        if (op_type.isNull()) {
            LOG(ERROR) << "PTRSUB operation type is not serialized. key: " << op.key << "\n";
            return { nullptr, false };
        }

        auto merge_to_next = !op.output.has_value();

        auto op_loc         = SourceLocation(ctx.getSourceManager(), op.key);

        auto *input_expr = AS_EXPR_OR_NULL(
            create_varnode(ctx, function, op.inputs[0], op_loc), op.key);
        if (!input_expr) {
            return { nullptr, false };
        }

        clang::Expr *ptr_expr = nullptr;

        auto input_type = input_expr->getType();
        if (input_type->isPointerType() && input_type->getPointeeType()->isRecordType()) {
            auto *mem_expr = make_member_expr(ctx, input_expr, *op.inputs[1].value);
            if (mem_expr == nullptr) {
                LOG(ERROR) << "PTRSUB failed to build member access. key: " << op.key << "\n";
                return { nullptr, false };
            }
            // Array-typed member: decay to pointer-to-element, not `&member`
            // (which yields T(*)[N] and prints a spurious extra `&`).
            clang::Expr *field_ptr = nullptr;
            if (mem_expr->getType()->isArrayType()) {
                field_ptr = make_implicit_cast(
                    ctx, mem_expr, ctx.getArrayDecayedType(mem_expr->getType()),
                    clang::CastKind::CK_ArrayToPointerDecay
                );
            }
            if (field_ptr == nullptr) {
                field_ptr =
                    sema()
                        .BuildUnaryOp(sema().getCurScope(), op_loc, clang::UO_AddrOf, mem_expr)
                        .get();
            }
            ptr_expr = make_cast(ctx, field_ptr, op_type, op_loc);
        } else {
            auto *byte_offset = AS_EXPR_OR_NULL(
                create_varnode(ctx, function, op.inputs[1], op_loc), op.key);
            if (!byte_offset) {
                return { nullptr, false };
            }

            // Function/void* arithmetic is invalid in C / NYI in CIRGen (and
            // crashes); do the byte arithmetic in char* when op_type is one.
            auto arith_type = op_type;
            if (op_type->isPointerType()
                && (op_type->getPointeeType()->isFunctionType()
                    || op_type->getPointeeType()->isVoidType()))
            {
                arith_type = ctx.getPointerType(ctx.CharTy);
            }
            auto *arith_base = make_cast(ctx, input_expr, arith_type, op_loc);
            if (!arith_base) {
                LOG(ERROR) << "PTRSUB: failed to cast base for arithmetic. key: "
                           << op.key << "\n";
                return { nullptr, false };
            }
            auto add_result =
                sema().CreateBuiltinBinOp(op_loc, clang::BO_Add, arith_base, byte_offset);
            if (add_result.isInvalid()) {
                LOG(ERROR) << "PTRSUB: invalid add result. key: " << op.key << "\n";
                return { nullptr, false };
            }
            ptr_expr = add_result.getAs< clang::Expr >();
        }

        if (merge_to_next) {
            return { ptr_expr, true };
        }

        auto *output_expr =
            AS_EXPR_OR_NULL(create_varnode(ctx, function, *op.output), op.key);
        if (!output_expr) {
            return { nullptr, false };
        }
        return { create_assign_operation(ctx, ptr_expr, output_expr, op_loc), false };
    }

    std::pair< clang::Stmt *, bool > OpBuilder::create_ptradd(
        clang::ASTContext &ctx, const Function &function, const Operation &op
    ) {
        if (op.inputs.size() != 3U && op.mnemonic != Mnemonic::OP_PTRADD) {
            LOG(ERROR) << "Ptradd operation is invalid or has invalid input operands. key: "
                       << op.key << "\n";
            return { nullptr, false };
        }

        auto merge_to_next = !op.output.has_value();
        auto op_loc        = SourceLocation(ctx.getSourceManager(), op.key);

        auto *base =
            AS_EXPR_OR_NULL(create_varnode(ctx, function, op.inputs[0]), op.key);
        auto *index =
            AS_EXPR_OR_NULL(create_varnode(ctx, function, op.inputs[1]), op.key);
        auto *scale =
            AS_EXPR_OR_NULL(create_varnode(ctx, function, op.inputs[2]), op.key);
        if (!base || !index || !scale) {
            return { nullptr, false };
        }

        // When the base is a pointer type and the scale matches sizeof(*base),
        // emit &base[index] (array subscript) instead of raw arithmetic.
        // Otherwise fall back to base + index * scale to preserve correct
        // pointer arithmetic for mismatched scales.
        // Function/void pointee can't be subscripted; divert such bases to
        // the char* path below.
        clang::Expr *result_expr = nullptr;
        const bool base_is_arith_pointer =
            base->getType()->isPointerType()
            && !base->getType()->getPointeeType()->isFunctionType()
            && !base->getType()->getPointeeType()->isVoidType();
        if (base_is_arith_pointer) {
            bool scale_matches = false;
            if (auto *scale_lit = clang::dyn_cast< clang::IntegerLiteral >(scale)) {
                auto pointee_size = ctx.getTypeSizeInChars(
                    base->getType()->getPointeeType()
                );
                scale_matches =
                    scale_lit->getValue() == static_cast< uint64_t >(pointee_size.getQuantity());
            }

            if (scale_matches) {
                auto subscript =
                    sema().CreateBuiltinArraySubscriptExpr(base, op_loc, index, op_loc);
                if (!subscript.isInvalid()) {
                    result_expr = sema()
                        .CreateBuiltinUnaryOp(op_loc, clang::UO_AddrOf, subscript.get())
                        .getAs< clang::Expr >();
                }
            }
        }

        // Fallback to arithmetic when base is not a pointer, scale is not a
        // constant, scale does not match the pointee size, or the pointee is a
        // function/void type (diverted from the subscript path above).
        if (!result_expr) {
            auto mult_result = sema().CreateBuiltinBinOp(op_loc, clang::BO_Mul, index, scale);
            assert(!mult_result.isInvalid());

            // Record / function* / void* bases can't do C pointer arithmetic;
            // reinterpret as char* for well-defined byte arithmetic.
            clang::Expr *arith_base = base;
            auto char_ptr_ty        = ctx.getPointerType(ctx.CharTy);
            if (base->getType()->isRecordType()) {
                arith_base = make_reinterpret_cast(ctx, base, char_ptr_ty, op_loc);
            } else if (base->getType()->isPointerType()
                       && (base->getType()->getPointeeType()->isFunctionType()
                           || base->getType()->getPointeeType()->isVoidType()))
            {
                arith_base = make_cast(ctx, base, char_ptr_ty, op_loc);
            } else if (base->getType()->isArrayType()) {
                // An array base (e.g. a string-literal global) decays implicitly
                // inside the `+`, leaving a StringLiteral operand that trips
                // -Wstring-plus-int. An explicit char* cast (not looked through
                // by the diagnostic) keeps byte arithmetic well-defined.
                arith_base = make_explicit_cast(ctx, base, char_ptr_ty, op_loc);
            }
            if (!arith_base) {
                LOG(ERROR) << "PTRADD: failed to reinterpret base for "
                              "arithmetic. key: "
                           << op.key << "\n";
                return std::make_pair(nullptr, false);
            }

            auto add_result = sema().CreateBuiltinBinOp(
                op_loc, clang::BO_Add, arith_base, mult_result.getAs< clang::Expr >()
            );
            if (add_result.isInvalid()) {
                LOG(ERROR) << "PTRADD invalid add result. key: " << op.key;
                return std::make_pair(nullptr, false);
            }
            result_expr = add_result.getAs< clang::Expr >();
        }

        if (merge_to_next) {
            return std::make_pair(static_cast< clang::Stmt * >(result_expr), merge_to_next);
        }

        auto *output_stmt = create_varnode(ctx, function, *op.output);
        if (output_stmt->getStmtClass() == clang::Stmt::DeclStmtClass) {
            auto *decl     = clang::dyn_cast< clang::DeclStmt >(output_stmt)->getSingleDecl();
            auto *ref_expr = clang::DeclRefExpr::Create(
                ctx, clang::NestedNameSpecifierLoc(), clang::SourceLocation(),
                clang::dyn_cast< clang::VarDecl >(decl), false, op_loc,
                clang::dyn_cast< clang::VarDecl >(decl)->getType(), clang::VK_LValue
            );

            return { create_assign_operation(ctx, result_expr, ref_expr, op_loc), false };
        }

        auto *output_expr = clang::dyn_cast< clang::Expr >(output_stmt);
        return { create_assign_operation(ctx, result_expr, output_expr, op_loc), false };
    }

    std::pair< clang::Stmt *, bool > OpBuilder::create_cast(
        clang::ASTContext &ctx, const Function &function, const Operation &op
    ) {
        if (op.inputs.size() != 1U || op.mnemonic != Mnemonic::OP_CAST) {
            LOG(ERROR) << "Cast operation is invalid or has invalid input operand. key: "
                       << op.key << "\n";
            return {};
        }

        auto op_loc = SourceLocation(ctx.getSourceManager(), op.key);

        clang::QualType op_type;
        if (op.type.has_value()) {
            op_type = type_builder().GetSerializedType(*op.type);
        }

        auto emit_cast_error = [&](const char *reason)
            -> std::pair< clang::Stmt *, bool >
        {
            const std::string err_reason = std::string("missing_cast:") + reason;
            LOG(ERROR) << "CAST: " << reason << ", emitting __patchestry_error(\""
                       << err_reason << "\"). key: " << op.key;
            auto *err_expr = emit_patchestry_error(ctx, err_reason, op_loc);
            if (!err_expr) {
                return {};
            }
            clang::Expr *typed_err = nullptr;
            if (!op_type.isNull()) {
                typed_err = make_explicit_cast(ctx, err_expr, op_type, op_loc);
            }
            // No typed cast (op_type null, or cast rejected for
            // array/record/function targets): emit the bare marker.
            // Skipping the output assignment avoids re-triggering the
            // same rejection in create_assign_operation, which would
            // silently drop the result.
            if (!typed_err) {
                return std::make_pair(
                    clang::dyn_cast< clang::Stmt >(err_expr), false
                );
            }
            if (!op.output) {
                return std::make_pair(
                    clang::dyn_cast< clang::Stmt >(typed_err), false
                );
            }
            auto *out = AS_EXPR_OR_NULL(
                create_varnode(ctx, function, *op.output), op.key);
            if (!out) {
                return std::make_pair(
                    clang::dyn_cast< clang::Stmt >(typed_err), false
                );
            }
            auto *assign = create_assign_operation(ctx, typed_err, out, op_loc);
            if (!assign) {
                // create_assign_operation rejected the write (e.g. scalar→array
                // refusal from #227). Don't drop the marker — emit the bare
                // typed_err as a side-effect statement.
                return std::make_pair(
                    clang::dyn_cast< clang::Stmt >(typed_err), false
                );
            }
            return std::make_pair(assign, false);
        };

        if (!op.type.has_value()) {
            return emit_cast_error("op.type missing");
        }
        if (op_type.isNull()) {
            return emit_cast_error("op.type unresolved in serialized list");
        }

        auto *input_stmt    = create_varnode(ctx, function, op.inputs[0]);
        if (!input_stmt) {
            return emit_cast_error("input varnode produced null Stmt");
        }
        auto *input_expr = clang::dyn_cast< clang::Expr >(input_stmt);
        if (!input_expr) {
            return emit_cast_error("input varnode is not an Expr");
        }
        if (input_expr->getType()->isVoidType()) {
            // (T)<void expr> is invalid C; Sema would silently reject.
            return emit_cast_error("input expression has void type");
        }

        if (!op.output && ctx.hasSameUnqualifiedType(op_type, input_expr->getType())) {
            return { input_expr, true };
        }

        auto make_cast_expr = [&](clang::ASTContext &ctx, clang::Expr *expr,
                                  clang::QualType to_type,
                                  clang::SourceLocation loc) -> clang::Expr * {
            auto input_type = expr->getType();
            if (ShouldReinterpretCast(input_type, to_type)) {
                return make_reinterpret_cast(ctx, expr, to_type, loc);
            }

            return make_explicit_cast(ctx, expr, to_type, loc);
        };

        auto *cast = make_cast_expr(ctx, input_expr, op_type, op_loc);
        if (!cast) {
            return emit_cast_error("failed to create cast expression");
        }

        if (!op.output) {
            return { cast, true };
        }

        auto *output_stmt = create_varnode(ctx, function, *op.output);
        if (!output_stmt) {
            LOG(ERROR) << "CAST: output varnode produced null Stmt. key: " << op.key;
            return {};
        }
        auto *output_expr = clang::dyn_cast< clang::Expr >(output_stmt);
        if (!output_expr) {
            LOG(ERROR) << "CAST: output varnode is not an Expr. key: " << op.key;
            return {};
        }

        return { create_assign_operation(ctx, cast, output_expr, op_loc), false };
    }

    std::pair< clang::Stmt *, bool >
    OpBuilder::create_declare_local(clang::ASTContext &ctx, const Operation &op) {
        if (!op.name || !op.type) {
            LOG(ERROR) << "Local/temporary variable declaration has invalid name or types.\n";
            return {};
        }

        auto var_type = type_builder().GetSerializedType(*op.type);
        if (var_type.isNull()) {
            LOG(ERROR) << "Skipping, local/temporary variable type is not serialized. key: "
                       << op.key << "\n";
            return {};
        }
        auto op_loc          = SourceLocation(ctx.getSourceManager(), op.key);

        std::string var_name = *op.name;
        auto &name_counts    = function_builder().declared_name_counts;
        auto [it, inserted]  = name_counts.try_emplace(var_name, 0);
        if (!inserted) {
            // Variable coalescing (structural): when multiple SSA
            // versions of the same register have the same type, reuse
            // the existing VarDecl instead of creating x3_1, x3_2, etc.
            // This mirrors merge phase which coalesces variables
            // with non-overlapping lifetimes.
            auto first_it = function_builder().declared_first_var.find(var_name);
            if (first_it != function_builder().declared_first_var.end()) {
                auto *existing = first_it->second;
                if (existing->getType() == var_type) {
                    // Same type — reuse the existing VarDecl
                    function_builder().local_variables.emplace(op.key, existing);
                    return std::make_pair(nullptr, true);
                }
            }
            // Different type — create with suffix
            var_name += "_" + std::to_string(++(it->second));
        }

        auto *var_decl =
            create_variable_decl(ctx, sema().CurContext, var_name, var_type, op_loc);
        // Mark all local variable used to avoid warning about unused variable
        var_decl->setIsUsed();

        // Track the first VarDecl for each name (for coalescing)
        if (inserted) {
            function_builder().declared_first_var.emplace(var_name, var_decl);
        }

        // add variable declaration to list for future references
        function_builder().local_variables.emplace(op.key, var_decl);
        return std::make_pair(create_decl_stmt(ctx, var_decl, op_loc), false);
    }

    std::pair< clang::Stmt *, bool > OpBuilder::create_declare_parameter(
        clang::ASTContext &ctx, const Function &function, const Operation &op
    ) {
        (void) ctx, (void) function, (void) op;
        return std::make_pair(nullptr, true);
    }

    clang::FunctionDecl *OpBuilder::get_or_create_intrinsic_decl(
        clang::ASTContext &ctx, const std::string &name, clang::QualType return_type,
        llvm::ArrayRef< clang::QualType > param_types
    ) {
        // Cache key encodes everything that affects the FunctionDecl identity:
        // name, return type, and the full parameter list. Without the return
        // type, the same intrinsic called in both void and valued contexts
        // would collide and the second call would reuse a wrong-return-type
        // FunctionDecl. Without the full parameter list, two callers passing
        // differently-typed args would share a single decl whose prototype
        // matches only one of them, producing arity/type mismatches during
        // CIR -> LLVM lowering.
        std::string cache_key = name;
        cache_key += "|ret:";
        cache_key += return_type.getCanonicalType().getAsString();
        for (std::size_t i = 0; i < param_types.size(); ++i) {
            cache_key += "|param";
            cache_key += std::to_string(i);
            cache_key += ":";
            cache_key += param_types[i].getCanonicalType().getAsString();
        }

        auto it = intrinsic_decls().find(cache_key);
        if (it != intrinsic_decls().end()) {
            return it->second;
        }

        // Create a new intrinsic function declaration. A fully fixed-arity
        // prototype is used (epi.Variadic = false): ClangIR's CIRGen
        // occasionally drops the variadic flag for void-returning functions,
        // producing prototypes that mismatch the call site arity and abort
        // the lowering pass. For genuine zero-input CALLOTHER userops (e.g.
        // the AArch64 ClearExclusiveLocal SLEIGH emit), the prototype must
        // also be empty so that BuildCallExpr's `0 args -> 0 params` check
        // succeeds; synthesizing a void* placeholder here used to put us
        // back into a `0 args -> 1 param` mismatch.
        auto loc = VirtualLoc(ctx);
        clang::FunctionProtoType::ExtProtoInfo epi;
        epi.Variadic = false;

        llvm::SmallVector< clang::QualType, 4 > params(param_types.begin(), param_types.end());

        auto func_type = ctx.getFunctionType(return_type, params, epi);
        auto *func_decl = clang::FunctionDecl::Create(
            ctx, ctx.getTranslationUnitDecl(), loc, loc, &ctx.Idents.get(name), func_type,
            ctx.getTrivialTypeSourceInfo(func_type), clang::SC_Extern
        );

        if (func_decl == nullptr) {
            LOG(ERROR) << "Failed to create intrinsic function declaration for: " << name << "\n";
            return nullptr;
        }

        // Create ParmVarDecls so Sema can inspect fixed parameters while
        // performing call conversions.
        std::vector< clang::ParmVarDecl * > param_decls;
        param_decls.reserve(params.size());
        for (auto param_type : params) {
            auto *param = clang::ParmVarDecl::Create(
                ctx, func_decl, loc, loc, nullptr, param_type, nullptr, clang::SC_None, nullptr
            );
            param_decls.push_back(param);
        }
        func_decl->setParams(param_decls);

        // Add to translation unit
        ctx.getTranslationUnitDecl()->addDecl(func_decl);

        // Cache it
        intrinsic_decls()[cache_key] = func_decl;
        return func_decl;
    }

    std::pair< clang::Stmt *, bool > OpBuilder::create_intrinsic_call(
        clang::ASTContext &ctx, const Function &function, const Operation &op,
        const std::string &name
    ) {
        auto op_loc = SourceLocation(ctx.getSourceManager(), op.key);

        // Determine return type.  Prefer the typed output, fall back to
        // op.type for ops whose value flows through a temporary reference
        // rather than a named output (default-void otherwise corrupts
        // every downstream consumer).
        clang::QualType ret_type = ctx.VoidTy;
        if (op.output) {
            ret_type = get_varnode_type(ctx, *op.output);
        } else if (op.type) {
            auto t = type_builder().GetSerializedType(*op.type);
            if (!t.isNull()) ret_type = t;
        }

        // Build arguments from inputs
        std::vector< clang::Expr * > args;
        for (const auto &input : op.inputs) {
            auto *e =
                AS_EXPR_OR_NULL(create_varnode(ctx, function, input), op.key);
            if (e) {
                args.push_back(e);
            }
        }

        // Build the function prototype from the actual argument types so the
        // declared arity always matches the call site. Earlier revisions used
        // a variadic prototype keyed only on the first argument type, but
        // ClangIR's CIRGen intermittently dropped the variadic flag on
        // void-returning intrinsic declarations and produced cir.func types
        // with fewer fixed parameters than the call passed, aborting the
        // lowering pass with "incorrect number of operands for callee".
        llvm::SmallVector< clang::QualType, 4 > param_types;
        param_types.reserve(args.size());
        for (auto *arg : args) {
            param_types.push_back(arg->getType());
        }
        auto *fn_decl = get_or_create_intrinsic_decl(ctx, name, ret_type, param_types);
        if (fn_decl == nullptr) {
            LOG(ERROR) << "Failed to get intrinsic declaration. key: " << op.key << "\n";
            return {};
        }

        // Build call expression
        auto *fn_ref = clang::DeclRefExpr::Create(
            ctx, clang::NestedNameSpecifierLoc(), clang::SourceLocation(), fn_decl, false, op_loc,
            fn_decl->getType(), clang::VK_LValue
        );

        auto result = sema().BuildCallExpr(nullptr, fn_ref, op_loc, args, op_loc);
        if (result.isInvalid()) {
            LOG(ERROR) << "Failed to build intrinsic call expression. key: " << op.key << "\n";
            return {};
        }

        auto *call_expr = result.getAs< clang::Expr >();

        // If no output, just return the call
        if (!op.output) {
            return { call_expr, false };
        }

        // Assign result to output
        auto *out =
            AS_EXPR_OR_NULL(create_varnode(ctx, function, *op.output), op.key);
        if (!out) {
            return {};
        }
        return { create_assign_operation(ctx, call_expr, out, op_loc), false };
    }

    std::pair< clang::Stmt *, bool >
    OpBuilder::build_intrinsic_call_against_registered(
        clang::ASTContext &ctx, const Function &function, const Operation &op
    ) {
        if (!op.target || !op.target->function) {
            LOG(ERROR) << "build_intrinsic_call_against_registered: missing "
                       << "target. key: " << op.key << "\n";
            return {};
        }
        const auto &label = *op.target->function;
        auto      &fns    = function_builder().function_list.get();
        auto       it     = fns.find(label);
        if (it == fns.end() || it->second == nullptr) {
            LOG(ERROR) << "Registered intrinsic decl missing for '" << label
                       << "'. key: " << op.key << "\n";
            return {};
        }
        auto *callee = it->second;
        auto  op_loc = SourceLocation(ctx.getSourceManager(), op.key);

        auto *fn_ref = clang::DeclRefExpr::Create(
            ctx, clang::NestedNameSpecifierLoc(), clang::SourceLocation(),
            callee, false, op_loc,
            callee->getType(), clang::VK_LValue
        );

        std::vector< clang::Expr * > args;
        args.reserve(op.inputs.size());
        for (size_t i = 0; i < op.inputs.size(); ++i) {
            auto *e = AS_EXPR_OR_NULL(
                create_varnode(ctx, function, op.inputs[i]), op.key);
            if (!e) {
                LOG(ERROR) << "Failed to create varnode for intrinsic call "
                           << "argument " << i << " of '" << label
                           << "'. key: " << op.key << "\n";
                return {};
            }
            args.push_back(e);
        }

        auto result = sema().BuildCallExpr(nullptr, fn_ref, op_loc, args, op_loc);
        if (result.isInvalid()) {
            LOG(ERROR) << "Failed to build intrinsic call against registered "
                       << "decl '" << label << "'. key: " << op.key << "\n";
            return {};
        }
        auto *call_expr = result.getAs< clang::Expr >();

        if (op.output) {
            auto *out = AS_EXPR_OR_NULL(
                create_varnode(ctx, function, *op.output), op.key);
            if (!out) {
                return {};
            }
            return { create_assign_operation(ctx, call_expr, out, op_loc), false };
        }

        // No named output but non-void return: materialize via __call_ret_N
        // and cache a fresh DeclRefExpr so downstream uses don't share the
        // CallExpr* across parents. materialize_call_return can't be reused
        // — it gates on op.has_return_value, which Ghidra doesn't set on
        // CALLOTHER intrinsics.
        auto ret_type = callee->getReturnType();
        if (!ret_type->isVoidType()) {
            auto var_name = "__call_ret_"
                + std::to_string(function_builder().call_ret_counter++);
            auto *var_decl = create_variable_decl(
                ctx, sema().CurContext, var_name, ret_type, op_loc);
            var_decl->setIsUsed();
            sema().CurContext->addDecl(var_decl);

            auto *decl_stmt = create_decl_stmt(ctx, var_decl, op_loc);
            function_builder().pending_materialized.push_back(decl_stmt);

            auto *ref_lhs = clang::DeclRefExpr::Create(
                ctx, clang::NestedNameSpecifierLoc(), clang::SourceLocation(),
                var_decl, false, op_loc, ret_type, clang::VK_LValue);
            auto *assign = create_assign_operation(
                ctx, call_expr, ref_lhs, op_loc);

            auto *ref_cached = clang::DeclRefExpr::Create(
                ctx, clang::NestedNameSpecifierLoc(), clang::SourceLocation(),
                var_decl, false, op_loc, ret_type, clang::VK_LValue);
            function_builder().operation_stmts.emplace(op.key, ref_cached);

            return { assign, false };
        }
        return { call_expr, false };
    }

    std::pair< clang::Stmt *, bool > OpBuilder::create_missing_intrinsic_call(
        clang::ASTContext &ctx, const Function &function, const Operation &op,
        const std::string &original_name, const std::string &original_label
    ) {
        auto op_loc = SourceLocation(ctx.getSourceManager(), op.key);

        // Build descriptive function name: __patchestry_missing_<original_name>
        std::string func_name = "__patchestry_missing_" + original_name;
        (void) original_label; // debug metadata is currently dropped (see below)

        // Determine return type.  Prefer the typed output, fall back to
        // op.type for ops whose value flows through a temporary reference
        // rather than a named output.
        clang::QualType ret_type = ctx.VoidTy;
        if (op.output) {
            ret_type = get_varnode_type(ctx, *op.output);
        } else if (op.type) {
            auto t = type_builder().GetSerializedType(*op.type);
            if (!t.isNull()) ret_type = t;
        }

        // Build the fixed-arity prototype up front so the cache key encodes
        // both the return type and every parameter type, matching the
        // invariant in get_or_create_intrinsic_decl. Without the parameter
        // types in the key, the same unknown userop name appearing at two
        // call sites with different arities (possible with custom or
        // exotic SLEIGH processors that emit it as a CALLOTHER) would reuse
        // the first-seen FunctionDecl and produce an arity mismatch in
        // BuildCallExpr at the second call site.
        llvm::SmallVector< clang::QualType, 4 > param_types;
        for (const auto &input : op.inputs) {
            param_types.push_back(get_varnode_type(ctx, input));
        }

        std::string cache_key = func_name;
        cache_key += "|ret:";
        cache_key += ret_type.getCanonicalType().getAsString();
        for (std::size_t i = 0; i < param_types.size(); ++i) {
            cache_key += "|param";
            cache_key += std::to_string(i);
            cache_key += ":";
            cache_key += param_types[i].getCanonicalType().getAsString();
        }

        // Check cache for existing declaration
        auto cache_it = intrinsic_decls().find(cache_key);
        clang::FunctionDecl *fn_decl = nullptr;

        if (cache_it != intrinsic_decls().end()) {
            fn_decl = cache_it->second;
        } else {
            // A zero-input userop becomes a `()` prototype rather than a
            // `(void*)` placeholder so that the call (which also has zero
            // args) lines up; the earlier placeholder produced a 0-args vs
            // 1-param mismatch in Sema for genuine no-operand userops such
            // as AArch64 ClearExclusiveLocal.
            clang::FunctionProtoType::ExtProtoInfo epi;
            epi.Variadic = false;

            auto func_type = ctx.getFunctionType(ret_type, param_types, epi);

            fn_decl = clang::FunctionDecl::Create(
                ctx, ctx.getTranslationUnitDecl(), VirtualLoc(ctx),
                VirtualLoc(ctx), &ctx.Idents.get(func_name), func_type,
                ctx.getTrivialTypeSourceInfo(func_type), clang::SC_Extern
            );

            if (fn_decl == nullptr) {
                LOG(ERROR) << "Failed to create missing intrinsic declaration for: " << func_name
                           << "\n";
                return {};
            }

            // Create ParmVarDecls so Sema can access parameters during call conversion
            std::vector< clang::ParmVarDecl * > param_decls;
            for (std::size_t i = 0; i < param_types.size(); ++i) {
                auto *param = clang::ParmVarDecl::Create(
                    ctx, fn_decl, op_loc, op_loc, nullptr, param_types[i], nullptr,
                    clang::SC_None, nullptr
                );
                param->setIsUsed();
                param_decls.push_back(param);
            }
            fn_decl->setParams(param_decls);

            // Skip AnnotateAttr emission: ClangIR codegen on LLVM 22 errors
            // with "Not Yet Implemented: deferredAnnotations" when a function
            // declaration carries an AnnotateAttr, and the error aborts
            // emission of every TU function visited afterwards. The metadata
            // was only used for human debugging and has no in-tree consumer,
            // so dropping it is the safe interim fix until ClangIR implements
            // the deferred-annotation codegen path.

            // Add to translation unit and cache
            ctx.getTranslationUnitDecl()->addDecl(fn_decl);
            intrinsic_decls()[cache_key] = fn_decl;
        }

        // Build arguments from inputs
        std::vector< clang::Expr * > args;
        for (const auto &input : op.inputs) {
            auto *e = AS_EXPR_OR_NULL(
                create_varnode(ctx, function, input), op.key);
            if (e) {
                args.push_back(e);
            }
        }
        // Build call expression
        auto *fn_ref = clang::DeclRefExpr::Create(
            ctx, clang::NestedNameSpecifierLoc(), clang::SourceLocation(), fn_decl, false, op_loc,
            fn_decl->getType(), clang::VK_LValue
        );

        auto result = sema().BuildCallExpr(nullptr, fn_ref, op_loc, args, op_loc);
        if (result.isInvalid()) {
            LOG(ERROR) << "Failed to build missing intrinsic call expression. key: " << op.key
                       << "\n";
            return {};
        }

        auto *call_expr = result.getAs< clang::Expr >();

        // If no output, just return the call
        if (!op.output) {
            return { call_expr, false };
        }

        // Assign result to output
        auto *out = AS_EXPR_OR_NULL(
            create_varnode(ctx, function, *op.output), op.key);
        if (!out) {
            return {};
        }
        return { create_assign_operation(ctx, call_expr, out, op_loc), false };
    }

    clang::Expr *OpBuilder::emit_patchestry_error(
        clang::ASTContext &ctx, const std::string &reason, clang::SourceLocation loc
    ) {
        if (loc.isInvalid()) loc = VirtualLoc(ctx);

        const std::string func_name = "__patchestry_error";
        auto it = intrinsic_decls().find(func_name);
        clang::FunctionDecl *fn_decl =
            (it != intrinsic_decls().end()) ? it->second : nullptr;
        if (!fn_decl) {
            auto cstr_ty = ctx.getPointerType(ctx.CharTy.withConst());
            clang::FunctionProtoType::ExtProtoInfo epi;
            epi.Variadic = false;
            llvm::SmallVector< clang::QualType, 1 > param_tys{ cstr_ty };
            auto func_ty = ctx.getFunctionType(ctx.LongLongTy, param_tys, epi);

            fn_decl = clang::FunctionDecl::Create(
                ctx, ctx.getTranslationUnitDecl(), VirtualLoc(ctx),
                VirtualLoc(ctx), &ctx.Idents.get(func_name), func_ty,
                ctx.getTrivialTypeSourceInfo(func_ty), clang::SC_Extern
            );
            if (!fn_decl) {
                LOG(ERROR) << "Failed to declare __patchestry_error\n";
                return nullptr;
            }

            auto *param = clang::ParmVarDecl::Create(
                ctx, fn_decl, VirtualLoc(ctx), VirtualLoc(ctx), nullptr,
                cstr_ty, nullptr, clang::SC_None, nullptr
            );
            param->setIsUsed();
            std::vector< clang::ParmVarDecl * > params{ param };
            fn_decl->setParams(params);

            ctx.getTranslationUnitDecl()->addDecl(fn_decl);
            intrinsic_decls()[func_name] = fn_decl;
        }

        const std::size_t array_size = reason.size() + 1;
        auto reason_ty = ctx.getConstantArrayType(
            ctx.CharTy.withConst(), llvm::APInt(64, array_size), nullptr,
            clang::ArraySizeModifier::Normal, 0
        );
        auto *reason_lit = clang::StringLiteral::Create(
            ctx, reason, clang::StringLiteralKind::Ordinary, false, reason_ty, loc
        );

        auto *fn_ref = clang::DeclRefExpr::Create(
            ctx, clang::NestedNameSpecifierLoc(), clang::SourceLocation(),
            fn_decl, false, loc, fn_decl->getType(), clang::VK_LValue
        );
        std::vector< clang::Expr * > args{ reason_lit };
        auto call = sema().BuildCallExpr(nullptr, fn_ref, loc, args, loc);
        // Args (one StringLiteral) and signature (long long(const char *)) are
        // entirely lifter-controlled; Sema rejecting this is an invariant
        // violation, not a data-driven failure.
        LOG_FATAL_IF(call.isInvalid(),
            "emit_patchestry_error: Sema rejected the call (reason=\"{0}\")",
            reason);
        return call.getAs< clang::Expr >();
    }

} // namespace patchestry::ast