lib.rs

#![no_std]
#![allow(
    dead_code,
    unused_imports,
    unused_variables,
    unused_comparisons,
    deprecated,
    clippy::too_many_arguments,
    clippy::doc_overindented_list_items,
    clippy::absurd_extreme_comparisons,
    clippy::needless_range_loop,
    clippy::manual_checked_ops,
    clippy::collapsible_match,
    clippy::let_unit_value,
    clippy::needless_borrow,
    clippy::match_like_matches_macro,
    clippy::needless_return,
    clippy::disallowed_methods
)]

pub use crate::errors::QuickLendXError;

extern crate alloc;

#[cfg(all(test, feature = "legacy-tests"))]
mod scratch_events;
#[cfg(test)]
mod test_concurrent_default_overlap;
#[cfg(test)]
mod test_multisig;
#[cfg(all(test, feature = "legacy-tests"))]
mod test_default;
#[cfg(all(test, feature = "legacy-tests"))]
mod test_default_finality;
#[cfg(all(test, feature = "legacy-tests"))]
mod test_default_finality_matrix;
#[cfg(all(test, feature = "legacy-tests"))]
mod test_emergency_withdraw_props;
#[cfg(all(test, feature = "legacy-tests"))]
mod test_escrow;
#[cfg(all(test, feature = "legacy-tests"))]
mod test_escrow_uniqueness;
#[cfg(all(test, feature = "legacy-tests"))]
mod test_fees;
#[cfg(all(test, feature = "legacy-tests"))]
mod test_maintenance;
#[cfg(all(test, feature = "legacy-tests"))]
mod test_maintenance_write_matrix;
#[cfg(test)]
mod test_settlement_capacity_stress;
#[cfg(test)]
mod test_settlement_history_reconstruction;
// Issue #1920 — confirm require_regulatory_ok is truly a no-op by default.
#[cfg(test)]
mod test_regulatory_gate;
// Issue #1902 — investor freeze reason typed enum
#[cfg(test)]
mod test_investor_freeze_reason;
use crate::idempotency::{idempotency_exists, idempotency_key, store_idempotency};
use crate::verification::require_business_active;
use soroban_sdk::{contract, contractimpl, symbol_short, Address, BytesN, Env, Map, String, Vec};

pub mod address_summary;
pub mod admin;
pub mod analytics;
pub mod arbiter;
pub mod audit;
pub mod backpressure;
pub mod backup;
pub mod backup_v1;
#[cfg(any(test, feature = "testutils"))]
pub mod bench;
pub mod bid;
pub mod currency;
pub mod defaults;
pub mod diagnostics;
pub mod dispute;
pub mod dispute_timeline;
pub mod emergency;
pub mod errors;
pub mod escrow;
pub mod events;
pub mod fees;
pub mod freshness;
pub mod governance;
pub mod multisig;
pub mod health;
pub mod idempotency;
pub mod incident;
pub mod init;
pub mod invariants;
pub mod investment;
pub mod investment_queries;
pub mod invoice;
pub mod invoice_search;
pub mod maintenance;
pub mod monitor;
pub mod notifications;
pub mod operational_limits;
pub mod pagination;
pub mod panic_handler;
pub mod pause;
pub mod payments;
pub mod profits;
pub mod protocol_limits;
pub mod reentrancy;
pub mod regulatory;
pub mod settlement;
pub mod storage;
#[cfg(any(test, feature = "testutils"))]
pub mod test_utils;
#[cfg(all(test, feature = "legacy-tests"))]
mod test_accept_bid_instruction_budget;
#[cfg(all(test, feature = "legacy-tests"))]
mod test_accept_bid_race;
#[cfg(test)]
mod test_panic_handler;
#[cfg(test)]
mod test_due_date_guard;
#[cfg(test)]
mod test_lock_time_limit;
mod test_auto_resolution_boundary;
#[cfg(test)]
mod test_cancel_invoice_matrix;
#[cfg(test)]
mod test_governance;
#[cfg(all(test, feature = "legacy-tests"))]
mod test_admin;
#[cfg(all(test, feature = "legacy-tests"))]
mod test_admin_simple;
#[cfg(all(test, feature = "legacy-tests"))]
mod test_admin_standalone;
#[cfg(all(test, feature = "legacy-tests"))]
mod test_admin_two_step;
#[cfg(all(test, feature = "legacy-tests"))]
mod test_audit;
#[cfg(test)]
mod test_audit_config;
#[cfg(all(test, feature = "legacy-tests"))]
mod test_backup;
#[cfg(all(test, feature = "legacy-tests"))]
mod test_backup_restore_reindex;
#[cfg(all(test, feature = "legacy-tests"))]
mod test_backup_retention_enforcement;
#[cfg(all(test, feature = "legacy-tests"))]
mod test_backup_safety;
#[cfg(test)]
mod test_bid_cancel_accept_race;
#[cfg(all(test, feature = "legacy-tests"))]
mod test_bid_expiry_boundary;
#[cfg(test)]
mod test_bid_expiry_grace;
#[cfg(all(test, feature = "legacy-tests"))]
mod test_bid_ttl;
#[cfg(test)]
mod test_require_business_active;
#[cfg(test)]
mod test_require_valid_business_kyc_tier;
#[cfg(test)]
mod test_cancel_invoice_matrix;
#[cfg(all(test, feature = "legacy-tests"))]
mod test_cleanup_pagination;
#[cfg(test)]
mod test_config_bounds_matrix;
#[cfg(all(test, feature = "legacy-tests"))]
mod test_currency;
// Issue #2092 — currency-precision helper boundary tests; runs on every CI
// matrix entry (no feature gate). Covers matching (decimals=0, 7, 18),
// over-precision (decimals=19, 20, u32::MAX), and malformed cases
// (unregistered address, wrong return type).
#[cfg(test)]
mod test_currency_precision;
#[cfg(test)]
mod test_currency_batch;
#[cfg(all(test, feature = "legacy-tests"))]
mod test_currency_match_funding;
#[cfg(all(test, feature = "legacy-tests"))]
mod test_dispute;
#[cfg(test)]
mod test_dispute_refund_flow;
#[cfg(test)]
mod test_dispute_history_guard;
#[cfg(test)]
mod test_evidence_size_cap;
#[cfg(test)]
mod test_evidence_hash_format;
// Issue #1975 — evidence-kind guard matrix; no feature gate (runs on every CI
// matrix entry). Also the regression test for the fix landed alongside it:
// `create_dispute` was not calling `validate_dispute_evidence` /
// `validate_dispute_eligibility` at all.
#[cfg(test)]
mod test_evidence_kind_guard_matrix;
#[cfg(all(test, feature = "legacy-tests"))]
mod test_dispute_timeline_props;
#[cfg(test)]
mod test_due_date_guard;
#[cfg(test)]
mod test_lock_time_limit_guard;
#[cfg(test)]
// mod test_dispute_event_invariant;
#[cfg(test)]
mod test_dust_transfer;
// Issue #1840 — arbiter guard on dispute resolution (no feature gate: every
// CI matrix entry must exercise the negative test path).
#[cfg(test)]
mod test_dispute_arbiter;
// Issue #1847 — backfill guard against WASM upgrades (no feature gate).
#[cfg(test)]
mod test_backfill_guard;
// Issue #1820/#1821 — early_payment_discount_bps per-invoice config and
// boundary tests.
#[cfg(test)]
mod test_early_payment_discount_bps;
#[cfg(test)]
mod test_escrow_early_release;
#[cfg(all(test, feature = "legacy-tests"))]
mod test_escrow_event_completeness;
#[cfg(all(test, feature = "legacy-tests"))]
mod test_escrow_invariant_model;
#[cfg(all(test, feature = "legacy-tests"))]
mod test_escrow_refund_after_expiry;
#[cfg(all(test, feature = "legacy-tests"))]
mod test_expired_bids_cleanup;
#[cfg(test)]
mod test_freshness;
#[cfg(all(test, feature = "legacy-tests"))]
mod test_freshness_bounds;
#[cfg(test)]
mod test_investor_kyc;
#[cfg(test)]
mod test_payments;
#[cfg(test)]
mod test_queries;
#[cfg(test)]
mod test_rating_override;
#[cfg(all(test, feature = "legacy-tests"))]
mod test_self_call_rejection;
// Issue #1541 — lag at zero, lag at positive, lag during pause.
#[cfg(all(test, feature = "legacy-tests"))]
mod test_freshness_lag;
#[cfg(all(test, feature = "legacy-tests"))]
mod test_health_status;
#[cfg(all(test, feature = "legacy-tests"))]
mod test_init;
#[cfg(all(test, feature = "legacy-tests"))]
mod test_invariant_self_check;
#[cfg(all(test, feature = "legacy-tests"))]
mod test_investment_consistency;
#[cfg(test)]
mod test_operational_limits;
#[cfg(test)]
mod test_regulatory;
#[cfg(all(test, feature = "legacy-tests"))]
mod test_withdraw_bid_matrix;
// #[cfg(test)]
#[cfg(test)]
#[path = "test/test_investment_queries.rs"]
mod test_investment_queries;
// #[cfg(all(test, feature = "legacy-tests"))]
// mod test_overflow;
// #[cfg(all(test, feature = "legacy-tests"))]
// mod test_pause;
// #[cfg(all(test, feature = "legacy-tests"))]
// mod test_profit_fee;
// #[cfg(all(test, feature = "legacy-tests"))]
#[cfg(all(test, feature = "legacy-tests"))]
mod test_backpressure_shedding;
#[cfg(all(test, feature = "legacy-tests"))]
mod test_profit_fee;
#[cfg(all(test, feature = "legacy-tests"))]
mod test_protocol_health;
#[cfg(all(test, feature = "legacy-tests"))]
mod test_protocol_limits_boundary;
#[cfg(all(test, feature = "legacy-tests"))]
// mod test_refund;
// #[cfg(all(test, feature = "legacy-tests"))]
// mod test_storage;
#[cfg(all(test, feature = "legacy-tests"))]
mod test_reentrancy;
#[cfg(all(test, feature = "legacy-tests"))]
mod test_reentrancy_fault_injection;
#[cfg(test)]
mod test_settlement_accounting_identity;
// Issue #1908 — per-invoice settlement currency whitelist (defence-in-depth).
// Negative test: settlement blocked when whitelist does not match invoice currency.
#[cfg(test)]
mod test_settlement_currency_whitelist;
#[cfg(test)]
mod test_fuzz_settlement_currency_whitelist;
#[cfg(test)]
mod test_settle_during_dispute;
#[cfg(test)]
mod test_string_limits;
#[cfg(all(test, feature = "legacy-tests"))]
mod test_string_limits;
// #[cfg(all(test, feature = "legacy-tests"))]
// mod test_types;
#[cfg(all(test, feature = "legacy-tests"))]
mod test_analytics_consistency;
// Issue snapshot-tests — clean snapshot and snapshot with open dispute.
// No feature gate: runs on every CI matrix entry.
#[cfg(test)]
mod test_snapshot;
#[cfg(test)]
mod test_bid_capacity_stress;
// Issue #1891 — min-partial-fill amount boundary: at limit, one below, one above.
#[cfg(test)]
mod test_min_partial_fill_boundary;
// Issue #1858 — per-invoice per_investor_position_cap whale defence.
#[cfg(test)]
mod test_per_investor_position_cap;
#[cfg(all(test, feature = "fuzz-tests"))]
mod test_bid_compare_order_props;
#[cfg(all(test, feature = "legacy-tests"))]
mod test_bid_ranking;
// Issue #2083 — bid-match helper tests; runs on every CI matrix entry
// (no feature gate, since `legacy-tests` is OFF in CI). Covers
// `compare_bids`, `get_best_bid`, and `rank_bids`.
#[cfg(test)]
mod test_bid_match_helper;
// Issue #2089 — max-invoice-tags helper boundary tests; runs on every CI
// matrix entry (no feature gate). Locks in below/at/over-cap behaviour for
// `Invoice::add_tag`, the bulk ctor `Invoice::new`, and the pure validator
// `validate_invoice_tags`. Assertive names and deterministic inputs only.
#[cfg(test)]
mod test_max_invoice_tags_boundary;
#[cfg(test)]
mod test_require_valid_invoice_category;
#[cfg(test)]
mod test_verify_bid_match;
#[cfg(test)]
mod test_expired_escrow;
#[cfg(test)]
mod test_vesting;
#[cfg(test)]
mod test_vesting_summary;
// Issue #1551 — determinism tests for bid_ranking; no feature gate, runs on
// every CI matrix entry.
// #[cfg(test)]
// mod test_bid_ranking_determinism;
#[cfg(all(test, feature = "legacy-tests"))]
mod test_business_invoices_paged_ordering;
#[cfg(all(test, feature = "legacy-tests"))]
mod test_category_breakdown;
#[cfg(all(test, feature = "legacy-tests"))]
mod test_clock_rollover;
#[cfg(all(test, feature = "fuzz-tests"))]
mod test_compute_yield_props;
#[cfg(all(test, feature = "legacy-tests"))]
mod test_default_grace_boundary;
#[cfg(test)]
mod test_diagnostics;
#[cfg(all(test, feature = "legacy-tests"))]
mod test_events;
#[cfg(all(test, feature = "fuzz-tests"))]
mod test_fuzz_cancelled_noop;
#[cfg(all(test, feature = "legacy-tests", feature = "fuzz-tests"))]
mod test_fuzz_distribute_revenue;
#[cfg(test)]
mod test_fuzz_default_counter;
#[cfg(all(test, feature = "legacy-tests", feature = "fuzz-tests"))]
mod test_fuzz_invoice_metadata;
#[cfg(all(test, feature = "fuzz-tests"))]
mod test_fuzz_partial_payment;
#[cfg(all(test, feature = "fuzz-tests"))]
mod test_profits_props;
#[cfg(all(test, feature = "legacy-tests"))]
mod test_incident;
#[cfg(test)]
mod test_init_debug;
#[cfg(test)]
mod test_init_invariants;
#[cfg(test)]
mod test_input_matrix;
#[cfg(all(test, feature = "legacy-tests"))]
mod test_insurance_claim_payout;
#[cfg(test)]
mod test_insurance_optin_lifecycle;
#[cfg(test)]
mod test_invoice;
#[cfg(all(test, feature = "fuzz-tests"))]
mod test_insurance_premium_props;
#[cfg(all(test, feature = "legacy-tests"))]
mod test_investment_transitions;
// Issue #1949 — full InvestmentStatus transition matrix (CI-ungated).
#[cfg(test)]
mod test_investment_state_matrix;
#[cfg(all(test, feature = "legacy-tests"))]
mod test_investment_withdrawal;
#[cfg(all(test, feature = "legacy-tests"))]
mod test_invoice_metadata;
#[cfg(all(test, feature = "legacy-tests"))]
mod test_invoice_search_ranking;
#[cfg(all(test, feature = "legacy-tests"))]
mod test_line_item_consistency;
#[cfg(test)]
mod test_max_invoices_per_business;
#[cfg(all(test, feature = "legacy-tests"))]
mod test_notifications;
#[cfg(all(test, feature = "legacy-tests"))]
mod test_pause_reads_available;
#[cfg(all(test, feature = "legacy-tests"))]
mod test_pause_reason;
mod test_platform_metrics_reconciliation;
#[cfg(all(test, feature = "legacy-tests"))]
mod test_rebuild_indexes;
#[cfg(all(test, feature = "fuzz-tests"))]
mod test_seed;
#[cfg(all(test, feature = "legacy-tests", feature = "fuzz-tests"))]
mod test_treasury_split_overflow_props;
#[cfg(all(test, feature = "fuzz-tests"))]
mod test_twa_props;
#[cfg(all(test, feature = "fuzz-tests"))]
mod test_volume_tier_props;
// Issue #1482 — "cannot withdraw more than deposited" invariant: hard-coded sad
// path (always runs) + proptest property (requires fuzz-tests feature).
#[cfg(test)]
mod test_cannot_withdraw_more_than_deposited;
#[cfg(test)]
mod test_store_invoice_auth;
// Issue #1880 — batch-create boundary tests; no feature gate (runs on every CI matrix entry).
// Covers 0, 1, MAX_BATCH, MAX_BATCH+1, active-invoice cap, KYC gating, and atomicity.
#[cfg(test)]
mod test_store_invoices_batch;
// Issue #1881 — batch-cancel boundary tests; no feature gate (runs on every CI matrix entry).
// Covers 0, 1, MAX_BATCH, MAX_BATCH+1, KYC gating, frozen items, non-existent items, unauthorized items, and atomicity.
#[cfg(test)]
mod test_invoice_batch_cancel;
#[cfg(test)]
mod test_tier_boundary;
// Issue — symmetric pause/maintenance state-change tests (both directions); no
// feature gate so this runs on every CI matrix entry.
#[cfg(test)]
mod test_pause_toggle_symmetry;
#[cfg(test)]
mod test_verification_matrix;
pub mod types;
pub use types::*;
pub mod upgrade;
pub mod verification;
pub mod vesting;
use admin::require_not_self;
use admin::AdminStorage;
use defaults::{
    handle_default as do_handle_default, mark_invoice_defaulted as do_mark_invoice_defaulted,
};
use escrow::{
    accept_bid_and_fund as do_accept_bid_and_fund, refund_escrow_funds as do_refund_escrow_funds,
    withdraw_investment as do_withdraw_investment,
};
use events::{
    emit_bid_accepted, emit_bid_placed, emit_bid_withdrawn, emit_dispute_created,
    emit_dispute_rejected, emit_dispute_resolved, emit_dispute_under_review, emit_escrow_created,
    emit_escrow_released, emit_insurance_added, emit_insurance_premium_collected,
    emit_investor_verified, emit_invoice_cancelled, emit_invoice_metadata_cleared,
    emit_invoice_metadata_updated, emit_invoice_uploaded, emit_invoice_verified,
};
use investment::InvestmentStorage;
use invoice_search::InvoiceSearch;
use payments::{create_escrow, release_escrow, require_matching_currency_precision, EscrowStorage};
use profits::{calculate_profit as do_calculate_profit, PlatformFee};
use settlement::{
    process_partial_payment as do_process_partial_payment, settle_invoice as do_settle_invoice,
};
use verification::{
    calculate_investment_limit, calculate_investor_risk_score, compute_investor_tier,
    determine_investor_tier, get_investor_verification as do_get_investor_verification,
    normalize_tag, recompute_investor_tier, reject_business, reject_investor as do_reject_investor,
    require_business_not_pending, require_investor_not_frozen, require_investor_not_pending,
    revoke_investor_kyc as do_revoke_investor_kyc, submit_investor_kyc as do_submit_investor_kyc,
    submit_kyc_application, validate_bid, validate_dispute_eligibility, validate_dispute_evidence,
    validate_dispute_reason, validate_dispute_resolution, validate_investor_investment,
    validate_invoice_metadata, verify_business,
    verify_investor as do_verify_investor, verify_invoice_data, BusinessVerificationStatus,
    BusinessVerificationStorage, InvestorRiskLevel, InvestorTier, InvestorVerification,
    InvestorVerificationStorage,
};

use crate::storage::{BidStorage, InvoiceStorage};

/// Render a 1-5 rating score as a decimal `String` for audit-log serialization.
fn fmt_rating(env: &Env, value: u32) -> String {
    let mut buf = [0u8; 10];
    let len = audit::write_u64_to_buf(&mut buf, value as u64);
    String::from_str(env, core::str::from_utf8(&buf[..len]).unwrap_or("0"))
}

#[contract]
pub struct QuickLendXContract;

/// Maximum number of records returned by paginated query endpoints.
pub const MAX_QUERY_LIMIT: u32 = pagination::MAX_QUERY_LIMIT;

/// @notice Validates and caps query limit to prevent resource abuse
/// @param limit The requested limit value
/// @return The capped limit value, never exceeding MAX_QUERY_LIMIT
/// @dev Returns 0 if limit is 0, enforcing empty result behavior
#[inline]
fn cap_query_limit(limit: u32) -> u32 {
    pagination::cap_query_limit(limit)
}

/// @notice Validates query parameters for security and resource protection
/// @param offset The pagination offset
/// @param limit The requested result limit
/// @return Result indicating validation success or failure
/// @dev Prevents potential overflow and ensures reasonable query bounds
fn validate_query_params(offset: u32, limit: u32) -> Result<(), QuickLendXError> {
    pagination::validate_query_params(offset, limit)
}

/// Defence-in-depth guard: reject any write when the target invoice is frozen.
///
/// An invoice can be frozen via `freeze_invoice` (admin action, compliance hold,
/// KYC revocation, etc.). While frozen, **all** state-mutating operations on that
/// invoice must be blocked — otherwise an attacker (or a compromised admin path)
/// could still drain escrow, alter metadata, or advance the lifecycle despite an
/// active hold.
///
/// Returns `Err(QuickLendXError::InvoiceFrozen)` when the invoice lock is active.
fn require_no_active_freeze(env: &Env, invoice_id: &BytesN<32>) -> Result<(), QuickLendXError> {
    if InvoiceStorage::is_frozen(env, invoice_id) {
        return Err(QuickLendXError::InvoiceFrozen);
    }
    Ok(())
}

/// Load an invoice and assert that the business caller has write access.
///
/// Consolidates the common preamble shared by `cancel_invoice`,
/// `update_invoice_metadata`, and `clear_invoice_metadata`:
/// - Protocol is not paused
/// - Invoice exists
/// - Invoice is not frozen
/// - Transaction is authorized by the invoice's business address
/// - Business is active (not deleted/frozen)
///
/// Returns the loaded `Invoice` so callers can proceed with their
/// specific logic without repeating these five guards.
fn require_invoice_writable_by_business(
    env: &Env,
    invoice_id: &BytesN<32>,
) -> Result<Invoice, QuickLendXError> {
    pause::PauseControl::require_not_paused(env)?;
    let invoice = InvoiceStorage::get_invoice(env, invoice_id)
        .ok_or(QuickLendXError::InvoiceNotFound)?;
    require_no_active_freeze(env, invoice_id)?;
    invoice.business.require_auth();
    require_business_active(env, &invoice.business)?;
    Ok(invoice)
}

/// Write a `u32` as ASCII decimal into `buf`, return byte length.
#[inline]
fn u32_to_ascii_lib(mut value: u32, buf: &mut [u8; 10]) -> usize {
    if value == 0 {
        buf[0] = b'0';
        return 1;
    }
    let mut tmp = [0u8; 10];
    let mut len = 0usize;
    while value > 0 {
        tmp[len] = b'0' + (value % 10) as u8;
        value /= 10;
        len += 1;
    }
    for i in 0..len {
        buf[i] = tmp[len - 1 - i];
    }
    len
}

/// Convert a `u32` to a soroban `String` using stack-allocated ASCII.
#[inline]
pub(crate) fn u32_to_string_lib(env: &Env, value: u32) -> String {
    let mut buf = [0u8; 10];
    let n = u32_to_ascii_lib(value, &mut buf);
    let s = core::str::from_utf8(&buf[..n]).unwrap_or("0");
    String::from_str(env, s)
}

/// Convert an `i64` to a soroban `String` using stack-allocated ASCII.
#[inline]
pub(crate) fn i64_to_string_lib(env: &Env, value: i64) -> String {
    // "-9223372036854775808" = 20 chars
    let mut buf = [0u8; 21];
    let mut tmp = [0u8; 20];
    let (negative, abs_val) = if value < 0 {
        (true, (value as i128).unsigned_abs() as u64)
    } else {
        (false, value as u64)
    };
    let n = u64_to_ascii_20(abs_val, &mut tmp);
    let start = if negative {
        buf[0] = b'-';
        buf[1..1 + n].copy_from_slice(&tmp[..n]);
        1 + n
    } else {
        buf[..n].copy_from_slice(&tmp[..n]);
        n
    };
    let s = core::str::from_utf8(&buf[..start]).unwrap_or("0");
    String::from_str(env, s)
}

#[inline]
fn u64_to_ascii_20(mut value: u64, buf: &mut [u8; 20]) -> usize {
    if value == 0 {
        buf[0] = b'0';
        return 1;
    }
    let mut tmp = [0u8; 20];
    let mut len = 0usize;
    while value > 0 {
        tmp[len] = b'0' + (value % 10) as u8;
        value /= 10;
        len += 1;
    }
    for i in 0..len {
        buf[i] = tmp[len - 1 - i];
    }
    len
}

fn early_release_approval_key(
    invoice_id: &BytesN<32>,
    approver: &Address,
) -> (soroban_sdk::Symbol, BytesN<32>, Address) {
    (symbol_short!("er_appr"), invoice_id.clone(), approver.clone())
}

fn has_early_release_approval(env: &Env, invoice_id: &BytesN<32>, approver: &Address) -> bool {
    env.storage()
        .persistent()
        .get(&early_release_approval_key(invoice_id, approver))
        .unwrap_or(false)
}

#[contractimpl]
impl QuickLendXContract {
    // ============================================================================
    // Admin Management Functions
    // ============================================================================

    /// Initialize the protocol with all required configuration (one-time setup)
    pub fn initialize(env: Env, params: init::InitializationParams) -> Result<(), QuickLendXError> {
        init::ProtocolInitializer::initialize(&env, &params)
    }

    /// Check if the protocol has been initialized
    pub fn is_initialized(env: Env) -> bool {
        init::ProtocolInitializer::is_initialized(&env)
    }

    /// Get the protocol/contract version
    ///
    /// Returns the version written during initialization, or the current
    /// PROTOCOL_VERSION constant if the contract has not been initialized yet.
    ///
    /// # Returns
    /// * `u32` - The protocol version number
    ///
    /// # Version Format
    /// Version is a simple integer increment (e.g., 1, 2, 3...)
    /// Major versions indicate breaking changes that require migration.
    pub fn get_version(env: Env) -> u32 {
        init::ProtocolInitializer::get_version(&env)
    }

    /// Get current protocol limits
    pub fn get_protocol_limits(env: Env) -> protocol_limits::ProtocolLimits {
        protocol_limits::ProtocolLimitsContract::get_protocol_limits(env)
    }

    /// Admin-only: update the absolute minimum bid amount.
    pub fn update_minimum_bid(
        env: Env,
        admin: Address,
        amount: i128,
    ) -> Result<i128, QuickLendXError> {
        protocol_limits::ProtocolLimitsContract::update_minimum_bid(env, admin, amount)
    }

    /// Admin-only: extends the TTL for all major persistent storage indexes.
    pub fn extend_protocol_ttl(
        env: Env,
        admin: Address,
    ) -> Result<maintenance::ExtendReport, QuickLendXError> {
        maintenance::MaintenanceControl::extend_protocol_ttl(&env, &admin)
    }

    /// Admin-gated protocol heartbeat. Authenticates `admin` as the stored protocol
    /// admin, then runs every composed invariant check read-only.
    pub fn invariant_self_check(
        env: Env,
        admin: Address,
    ) -> Result<invariants::InvariantReport, QuickLendXError> {
        invariants::invariant_self_check(&env, &admin)
    }

    /// Initialize the admin address (deprecated: use initialize)
    pub fn initialize_admin(env: Env, admin: Address) -> Result<(), QuickLendXError> {
        AdminStorage::initialize(&env, &admin)
    }

    /// Transfer admin role to a new address
    ///
    /// # Arguments
    /// * `env` - The contract environment
    /// * `new_admin` - The new admin address
    ///
    /// # Returns
    /// * `Ok(())` if transfer succeeds
    /// * `Err(QuickLendXError::NotAdmin)` if caller is not current admin
    ///
    /// # Security
    /// - Requires authorization from current admin
    pub fn transfer_admin(env: Env, new_admin: Address) -> Result<(), QuickLendXError> {
        let admin = AdminStorage::get_admin(&env).ok_or(QuickLendXError::NotAdmin)?;
        AdminStorage::transfer_admin(&env, &admin, &new_admin)
    }

    /// Initiate a two-step admin transfer.
    pub fn initiate_admin_transfer(
        env: Env,
        admin: Address,
        new_admin: Address,
    ) -> Result<(), QuickLendXError> {
        AdminStorage::initiate_admin_transfer(&env, &admin, &new_admin)
    }

    /// Get the current admin address
    ///
    /// # Returns
    /// * `Some(Address)` if admin is set
    /// * `None` if admin has not been initialized
    pub fn get_current_admin(env: Env) -> Option<Address> {
        AdminStorage::get_admin(&env)
    }

    /// Enable or disable two-step admin transfers.
    pub fn set_two_step_enabled(
        env: Env,
        admin: Address,
        enabled: bool,
    ) -> Result<(), QuickLendXError> {
        AdminStorage::set_two_step_enabled(&env, &admin, enabled)
    }

    /// Set protocol configuration (admin only)
    pub fn set_protocol_config(
        env: Env,
        admin: Address,
        min_invoice_amount: i128,
        max_due_date_days: u64,
        grace_period_seconds: u64,
        backfill_max_batch_size: u32,
    ) -> Result<(), QuickLendXError> {
        init::ProtocolInitializer::set_protocol_config(
            &env,
            &admin,
            min_invoice_amount,
            max_due_date_days,
            grace_period_seconds,
            backfill_max_batch_size,
        )
    }

    /// Set fee configuration (admin only)
    pub fn set_fee_config(env: Env, admin: Address, fee_bps: u32) -> Result<(), QuickLendXError> {
        init::ProtocolInitializer::set_fee_config(&env, &admin, fee_bps)
    }

    /// Dry-run preview for `set_protocol_config` and `set_fee_config` (admin-gated, read-only).
    ///
    /// Returns a [`init::ProtocolConfigDiff`] showing projected before/after values and
    /// validation metadata for the proposed `params`, **without mutating any contract state**.
    ///
    /// # Security
    /// - Requires admin authorization.
    /// - No storage writes occur; safe for use in monitoring and governance tooling.
    ///
    /// # Returns
    /// * `Ok(ProtocolConfigDiff)` — before/after diff with `would_succeed` and `is_noop` flags.
    /// * `Err(QuickLendXError::NotAdmin)` — caller is not the current admin.
    /// * `Err(QuickLendXError::OperationNotAllowed)` — admin subsystem not initialized.
    pub fn preview_protocol_config(
        env: Env,
        admin: Address,
        params: init::ProtocolConfigParams,
    ) -> Result<init::ProtocolConfigDiff, QuickLendXError> {
        init::ProtocolInitializer::preview_protocol_config(&env, &admin, params)
    }

    /// Set treasury address (admin only)
    pub fn set_treasury(
        env: Env,
        admin: Address,
        treasury: Address,
    ) -> Result<(), QuickLendXError> {
        init::ProtocolInitializer::set_treasury(&env, &admin, &treasury)
    }

    /// Admin-only: cancel a pending treasury address rotation before it executes.
    ///
    /// # Arguments
    /// * `admin` - The address of the caller, must be the current admin.
    pub fn cancel_treasury_rotation(env: Env, admin: Address) -> Result<(), QuickLendXError> {
        admin::cancel_treasury_rotation(&env, &admin)
    }

    /// Get the pending treasury address and its execution timestamp, if any.
    /// This is a view-only function for UI and testing purposes.
    pub fn get_pending_treasury(env: Env) -> Option<(Address, u64)> {
        storage::get_pending_treasury(&env)
    }

    /// Get current fee in basis points
    pub fn get_fee_bps(env: Env) -> u32 {
        init::ProtocolInitializer::get_fee_bps(&env)
    }

    /// Expose the current fee schedule
    pub fn get_fee_schedule(env: Env) -> Vec<crate::fees::FeeStructure> {
        crate::fees::FeeManager::get_fee_schedule(&env)
    }

    /// Get treasury address
    pub fn get_treasury(env: Env) -> Option<Address> {
        init::ProtocolInitializer::get_treasury(&env)
    }

    /// Get minimum invoice amount
    pub fn get_min_invoice_amount(env: Env) -> i128 {
        init::ProtocolInitializer::get_min_invoice_amount(&env)
    }

    /// Get maximum due date days
    pub fn get_max_due_date_days(env: Env) -> u64 {
        init::ProtocolInitializer::get_max_due_date_days(&env)
    }

    /// Get grace period in seconds
    pub fn get_grace_period_seconds(env: Env) -> u64 {
        init::ProtocolInitializer::get_grace_period_seconds(&env)
    }

    /// Get the corridor list (approved counterparty addresses for cross-invoice operations)
    pub fn get_corridors(env: Env) -> Vec<Address> {
        init::ProtocolInitializer::get_corridors(&env)
    }

    /// Admin-only: configure default bid TTL (days). Bounds: 1..=30.
    pub fn set_bid_ttl_days(env: Env, days: u64) -> Result<u64, QuickLendXError> {
        pause::PauseControl::require_not_paused(&env)?;
        let admin = AdminStorage::get_admin(&env).ok_or(QuickLendXError::NotAdmin)?;
        bid::BidStorage::set_bid_ttl_days(&env, &admin, days)
    }

    /// Get configured bid TTL in days (returns default 7 if not set)
    pub fn get_bid_ttl_days(env: Env) -> u64 {
        bid::BidStorage::get_bid_ttl_days(&env)
    }

    /// Get current bid TTL configuration snapshot
    pub fn get_bid_ttl_config(env: Env) -> bid::BidTtlConfig {
        bid::BidStorage::get_bid_ttl_config(&env)
    }

    /// Reset bid TTL to the compile-time default
    pub fn reset_bid_ttl_to_default(env: Env) -> Result<u64, QuickLendXError> {
        let admin = AdminStorage::get_admin(&env).ok_or(QuickLendXError::NotAdmin)?;
        bid::BidStorage::reset_bid_ttl_to_default(&env, &admin)
    }

    /// Admin-only: configure the bid expiry grace period (seconds). Bounds: 0..=2_592_000 (30 days).
    ///
    /// This is the additional buffer, on top of a bid's expiration timestamp,
    /// that must elapse before the permissionless cleanup entrypoints
    /// (`cleanup_expired_bids` / `cleanup_expired_bids_paged`) will transition
    /// it from `Placed` to `Expired`. Defaults to `0`, matching the
    /// pre-existing behaviour of cleaning up immediately at raw expiry.
    pub fn set_bid_expiry_grace_seconds(env: Env, seconds: u64) -> Result<u64, QuickLendXError> {
        pause::PauseControl::require_not_paused(&env)?;
        let admin = AdminStorage::get_admin(&env).ok_or(QuickLendXError::NotAdmin)?;
        bid::BidStorage::set_bid_expiry_grace_seconds(&env, &admin, seconds)
    }

    /// Get the configured bid expiry grace period in seconds (returns default 0 if not set)
    pub fn get_bid_expiry_grace_seconds(env: Env) -> u64 {
        bid::BidStorage::get_bid_expiry_grace_seconds(&env)
    }

    /// Get the current bid expiry grace-period configuration snapshot
    pub fn get_bid_expiry_grace_config(env: Env) -> bid::BidExpiryGraceConfig {
        bid::BidStorage::get_bid_expiry_grace_config(&env)
    }

    /// Reset the bid expiry grace period to the compile-time default (0)
    pub fn reset_bid_grace_to_default(env: Env, admin: Address) -> Result<u64, QuickLendXError> {
        admin.require_auth();
        bid::BidStorage::reset_bid_expiry_grace_to_default(&env, &admin)
    }

    /// Get maximum active bids allowed per investor
    pub fn get_max_active_bids_per_investor(env: Env) -> u32 {
        bid::BidStorage::get_max_active_bids_per_investor(&env)
    }

    /// Set maximum active bids allowed per investor (admin only).
    ///
    /// Pass `0` to disable the limit (any number of concurrent bids allowed).
    pub fn set_max_active_bids_per_investor(env: Env, limit: u32) -> Result<u32, QuickLendXError> {
        let admin = AdminStorage::get_admin(&env).ok_or(QuickLendXError::NotAdmin)?;
        bid::BidStorage::set_max_active_bids_per_investor(&env, &admin, limit)
    }

    /// Reset the per-investor active-bid limit to the compile-time default (20).
    ///
    /// Removes the stored override so [`get_bid_limit_config`] reports
    /// `is_custom = false` and `is_disabled = false`.  Useful for reverting a
    /// previous [`set_max_active_bids_per_investor(0)`] call.
    pub fn reset_investor_bid_limit(env: Env) -> Result<u32, QuickLendXError> {
        let admin = AdminStorage::get_admin(&env).ok_or(QuickLendXError::NotAdmin)?;
        bid::BidStorage::reset_max_active_bids_per_investor(&env, &admin)
    }

    /// Initiate emergency withdraw for stuck funds (admin only). Timelock applies before execute.
    /// See docs/contracts/emergency-recovery.md. Last-resort only.
    pub fn initiate_emergency_withdraw(
        env: Env,
        admin: Address,
        token: Address,
        amount: i128,
        target_address: Address,
    ) -> Result<(), QuickLendXError> {
        emergency::EmergencyWithdraw::initiate(&env, &admin, token, amount, target_address)
    }

    /// Execute emergency withdraw after timelock has elapsed (admin only).
    /// Protected by payment reentrancy guard.
    pub fn execute_emergency_withdraw(env: Env, admin: Address) -> Result<(), QuickLendXError> {
        reentrancy::with_payment_guard(&env, || emergency::EmergencyWithdraw::execute(&env, &admin))
    }

    /// Get pending emergency withdrawal if any.
    pub fn get_pending_emergency_withdraw(
        env: Env,
    ) -> Option<emergency::PendingEmergencyWithdrawal> {
        emergency::EmergencyWithdraw::get_pending(&env)
    }

    /// Check if the pending emergency withdrawal can be executed.
    ///
    /// Returns true if the withdrawal exists, is not cancelled, timelock has elapsed,
    /// has not expired, and does not exceed the same-token non-escrow surplus.
    pub fn can_exec_emergency(env: Env) -> bool {
        emergency::EmergencyWithdraw::can_execute(&env).unwrap_or(false)
    }

    /// Get time remaining until the emergency withdrawal can be executed.
    ///
    /// Returns seconds until unlock (0 if already unlocked).
    pub fn emg_time_until_unlock(env: Env) -> u64 {
        emergency::EmergencyWithdraw::time_until_unlock(&env).unwrap_or(0)
    }

    /// Get time remaining until the emergency withdrawal expires.
    ///
    /// Returns seconds until expiration (0 if already expired).
    pub fn emg_time_until_expire(env: Env) -> u64 {
        emergency::EmergencyWithdraw::time_until_expiration(&env).unwrap_or(0)
    }

    /// Add a token address to the currency whitelist (admin only).
    pub fn add_currency(
        env: Env,
        admin: Address,
        currency: Address,
    ) -> Result<(), QuickLendXError> {
        pause::PauseControl::require_not_paused(&env)?;
        currency::CurrencyWhitelist::add_currency(&env, &admin, &currency)
    }

    /// Remove a token address from the currency whitelist (admin only).
    pub fn remove_currency(
        env: Env,
        admin: Address,
        currency: Address,
    ) -> Result<(), QuickLendXError> {
        pause::PauseControl::require_not_paused(&env)?;
        currency::CurrencyWhitelist::remove_currency(&env, &admin, &currency)
    }

    /// Add multiple token addresses to the currency whitelist in one admin call.
    ///
    /// Returns a per-item `Vec<bool>`: `true` = newly added, `false` = already present.
    /// Empty input returns an empty result. Admin auth is required before any mutation.
    pub fn add_currencies_batch(
        env: Env,
        admin: Address,
        currencies: Vec<Address>,
    ) -> Result<Vec<bool>, QuickLendXError> {
        pause::PauseControl::require_not_paused(&env)?;
        currency::CurrencyWhitelist::add_currencies_batch(&env, &admin, &currencies)
    }

    /// Remove multiple token addresses from the currency whitelist in one admin call.
    ///
    /// Returns a per-item `Vec<bool>`: `true` = was present and removed, `false` = was not present.
    /// Empty input returns an empty result. Admin auth is required before any mutation.
    pub fn remove_currencies_batch(
        env: Env,
        admin: Address,
        currencies: Vec<Address>,
    ) -> Result<Vec<bool>, QuickLendXError> {
        pause::PauseControl::require_not_paused(&env)?;
        currency::CurrencyWhitelist::remove_currencies_batch(&env, &admin, &currencies)
    }

    /// Check if a token is allowed for invoice currency.
    pub fn is_allowed_currency(env: Env, currency: Address) -> bool {
        currency::CurrencyWhitelist::is_allowed_currency(&env, &currency)
    }

    /// Get all whitelisted token addresses.
    pub fn get_whitelisted_currencies(env: Env) -> Vec<Address> {
        currency::CurrencyWhitelist::get_whitelisted_currencies(&env)
    }

    /// Replace the entire currency whitelist atomically (admin only).
    pub fn set_currencies(
        env: Env,
        admin: Address,
        currencies: Vec<Address>,
    ) -> Result<(), QuickLendXError> {
        pause::PauseControl::require_not_paused(&env)?;
        currency::CurrencyWhitelist::set_currencies(&env, &admin, &currencies)
    }

    /// Clear the entire currency whitelist (admin only).
    /// After this call all currencies are allowed (empty-list backward-compat rule).
    pub fn clear_currencies(env: Env, admin: Address) -> Result<(), QuickLendXError> {
        pause::PauseControl::require_not_paused(&env)?;
        currency::CurrencyWhitelist::clear_currencies(&env, &admin)
    }

    /// Return the number of whitelisted currencies.
    pub fn currency_count(env: Env) -> u32 {
        currency::CurrencyWhitelist::currency_count(&env)
    }

    /// Return a paginated slice of the whitelist with metadata.
    ///
    /// Returns [`PaginatedCurrencies`] bundling the page of currency addresses together
    /// with `total_count` and `has_more` so consumers do not need a separate count query.
    pub fn get_whitelisted_currencies_paged(
        env: Env,
        offset: u32,
        limit: u32,
    ) -> PaginatedCurrencies {
        currency::CurrencyWhitelist::get_whitelisted_currencies_paged(&env, offset, limit)
    }

    /// Cancel a pending emergency withdrawal (admin only).
    pub fn cancel_emergency_withdraw(env: Env, admin: Address) -> Result<(), QuickLendXError> {
        emergency::EmergencyWithdraw::cancel(&env, &admin)
    }

    // ── Dispute arbiter registry (#1840) ─────────────────────────────────────

    /// Register a dispute arbiter (admin only).
    ///
    /// Splits dispute-adjudication authority from protocol-configuration
    /// authority. Once registered, only the registered arbiter(s) may
    /// resolve disputes (see `require_dispute_arbiter`). Idempotent — calling
    /// twice with the same address is a no-op.
    pub fn register_arbiter(
        env: Env,
        admin: Address,
        arbiter: Address,
    ) -> Result<(), QuickLendXError> {
        crate::arbiter::ArbiterStorage::register_arbiter(&env, &admin, &arbiter)
    }

    /// Revoke a previously registered dispute arbiter (admin only).
    ///
    /// Returns `Err(OperationNotAllowed)` if the address was never registered,
    /// so accidental no-op revocations surface to monitoring rather than
    /// slipping through as silent successes.
    pub fn unregister_arbiter(
        env: Env,
        admin: Address,
        arbiter: Address,
    ) -> Result<(), QuickLendXError> {
        crate::arbiter::ArbiterStorage::unregister_arbiter(&env, &admin, &arbiter)
    }

    /// Membership test: returns `true` when `address` is a registered arbiter.
    pub fn is_arbiter(env: Env, address: Address) -> bool {
        crate::arbiter::ArbiterStorage::is_arbiter(&env, &address)
    }

    /// List every currently registered arbiter.
    pub fn list_arbiters(env: Env) -> Vec<Address> {
        crate::arbiter::ArbiterStorage::list_arbiters(&env)
    }

    // ── Migration / backfill guard (#1847) ───────────────────────────────────

    /// Return whether a destructive backfill (e.g. `restore_from_backup`) is
    /// currently mutating invoice state.
    pub fn is_pending_backfill(env: Env) -> bool {
        crate::backup::BackupStorage::is_pending_backfill(&env)
    }

    /// Pause the contract (admin only). When paused, mutating operations fail with ContractPaused; getters succeed.
    pub fn pause(env: Env, admin: Address) -> Result<(), QuickLendXError> {
        pause::PauseControl::set_paused(&env, &admin, true)
    }

    /// Unpause the contract (admin only).
    pub fn unpause(env: Env, admin: Address) -> Result<(), QuickLendXError> {
        pause::PauseControl::set_paused(&env, &admin, false)
    }

    /// Return whether the contract is currently paused.
    pub fn is_paused(env: Env) -> bool {
        pause::PauseControl::is_paused(&env)
    }

    /// Return why guarded entrypoints are currently blocked, or `None`
    /// if the contract is not blocked.
    pub fn pause_reason(env: Env) -> Option<pause::PauseReason> {
        pause::PauseControl::pause_reason(&env)
    }

    /// Return whether a specific guarded entrypoint is currently blocked by pause.
    ///
    /// Accepts one of the stable pause entrypoint symbols from `pause.rs` and
    /// returns `true` only when the protocol is paused and the symbol refers to a
    /// guarded write entrypoint.
    pub fn is_entrypoint_paused(env: Env, entrypoint: String) -> bool {
        pause::PauseControl::is_entrypoint_paused(&env, entrypoint)
    }

    /// Return whether the contract is currently in maintenance mode.
    pub fn is_maintenance_mode(env: Env) -> bool {
        maintenance::MaintenanceControl::is_maintenance_mode(&env)
    }

    /// Return the current maintenance reason string, or `None` if not in maintenance.
    pub fn get_maintenance_reason(env: Env) -> Option<String> {
        maintenance::MaintenanceControl::get_maintenance_reason(&env)
    }

    /// Enable or disable maintenance mode (admin only).
    pub fn set_maintenance_mode(
        env: Env,
        admin: Address,
        enabled: bool,
        reason: String,
    ) -> Result<(), QuickLendXError> {
        maintenance::MaintenanceControl::set_maintenance_mode(&env, &admin, enabled, &reason)
    }

    /// Atomically enter incident mode: hard pause plus maintenance with reason.
    ///
    /// Coordinates [`pause::PauseControl`] and [`maintenance::MaintenanceControl`]
    /// in a single admin-gated invocation and returns an [`incident::IncidentSnapshot`]
    /// for runbook/audit tooling.
    pub fn enter_incident_mode(
        env: Env,
        admin: Address,
        reason: String,
    ) -> Result<incident::IncidentSnapshot, QuickLendXError> {
        incident::IncidentControl::enter_incident_mode(&env, &admin, &reason)
    }

    /// Atomically exit incident mode: unpause and disable maintenance.
    pub fn exit_incident_mode(
        env: Env,
        admin: Address,
    ) -> Result<incident::IncidentSnapshot, QuickLendXError> {
        incident::IncidentControl::exit_incident_mode(&env, &admin)
    }

    /// Consolidated operational health snapshot for write-gating and degraded banners.
    ///
    /// Composes pause, maintenance, backpressure, and freshness signals in a single
    /// ledger-consistent read. No new state is stored; all fields are read-through
    /// aggregates of existing flags.
    ///
    /// # `writes_allowed`
    /// `true` only when the protocol is not paused, not in maintenance, and not
    /// shedding load via backpressure. Freshness (`data_is_stale`) is advisory for
    /// indexed off-chain reads and does not affect `writes_allowed`.
    pub fn get_health_status(env: Env) -> monitor::HealthStatus {
        monitor::get_health_status(&env)
    }

    /// Consolidated operational limits snapshot: max batch size, max query limit,
    /// and max fee (bps) in a single read.
    ///
    /// Replaces the previous workaround of probing `get_overdue_scan_batch_limit_max`,
    /// the pagination cap, and the fee ceiling via separate calls (the fee ceiling
    /// previously had no getter at all). All fields are read-through aggregates of
    /// existing protocol constants; no new state is stored.
    pub fn get_operational_limits(_env: Env) -> operational_limits::OperationalLimits {
        operational_limits::get_operational_limits()
    }

    /// Get a snapshot of the protocol's current health status.
    ///
    /// This is a read-only canonical endpoint returning a single struct aggregating
    /// all critical protocol state for off-chain dashboards, monitoring systems,
    /// and governance tooling.
    ///
    /// # Returns
    /// * `health::ProtocolHealth` - A snapshot containing:
    ///   - `version`: Protocol version from initialization
    ///   - `initialized`: Whether protocol setup is complete
    ///   - `paused`: Current pause state
    ///   - `emergency_withdraw_pending`: Optional pending emergency withdrawal
    ///   - `treasury`: Configured treasury address (may be None)
    ///   - `fee_bps`: Current fee basis points (0-1000)
    ///   - `total_invoice_count`: Sum of all invoices across all statuses
    ///   - `currency_count`: Number of whitelisted currencies
    ///
    /// # Security
    /// - No authentication required
    /// - Read-only (no state mutations)
    /// - Contains only aggregate counts and system configuration (no PII)
    /// - Remains available even when protocol is paused
    ///
    /// # Usage
    /// Designed as the heartbeat endpoint for real-time protocol dashboards:
    ///
    /// ```ignore
    /// let health = get_protocol_health(&env);
    /// if !health.initialized {
    ///     log!("Protocol not initialized");
    ///     return;
    /// }
    /// if health.paused {
    ///     log!("Protocol paused - incident mode active");
    /// }
    /// if health.emergency_withdraw_pending.is_some() {
    ///     log!("Emergency withdrawal in timelock");
    /// }
    /// log!("Invoices: {}, Currencies: {}", health.total_invoice_count, health.currency_count);
    /// ```
    ///
    /// # Note
    /// This endpoint is purely advisory. The returned snapshot reflects the state
    /// at the moment of execution; subsequent transactions may change protocol state
    /// before callers can react to this data.
    pub fn get_protocol_health(env: Env) -> health::ProtocolHealth {
        health::ProtocolHealth::new(&env)
    }

    // ============================================================================
    // Invoice Management Functions
    // ============================================================================

    /// Store an invoice in the contract.
    ///
    /// Requires explicit authorization from the `business` address **and** a
    /// `Verified` KYC record. Only KYC-verified ("tier-N") businesses may write
    /// invoice data on-chain. This is the primary anti-spam gate: it prevents
    /// unvetted addresses from polluting on-chain storage and misleading investors
    /// with fraudulent invoice listings.
    ///
    /// # Arguments
    /// * `business` - Address of the business that owns the invoice (must sign)
    /// * `amount` - Invoice amount in smallest currency unit (e.g. cents)
    /// * `currency` - Token contract address for the invoice currency
    /// * `due_date` - Unix timestamp when the invoice is due
    /// * `description` - Human-readable description
    /// * `category` - Invoice category (e.g. Services, Goods)
    /// * `tags` - Optional tags for filtering
    ///
    /// # Returns
    /// * `Ok(BytesN<32>)` - The new invoice ID
    ///
    /// # Errors
    /// * `BusinessNotVerified` (1600) if the business has no KYC record or is rejected
    /// * `KYCAlreadyPending`   (1601) if the business KYC is awaiting admin review
    /// * `InvalidAmount` if amount <= 0
    /// * `InvoiceDueDateInvalid` if due_date is not in the future
    /// * `InvalidDescription` if description is empty
    /// * `ContractPaused` if the protocol is paused (checked first)
    ///
    /// Pause-gated: rejects with `ContractPaused` when the emergency circuit
    /// breaker is engaged, before any invoice state is created.
    pub fn store_invoice(
        env: Env,
        business: Address,
        amount: i128,
        currency: Address,
        due_date: u64,
        description: String,
        category: InvoiceCategory,
        tags: Vec<String>,
        origination_fee_bps: Option<u32>,
        late_payment_penalty_bps: Option<u32>,
        early_payment_discount_bps: Option<u32>,
    ) -> Result<BytesN<32>, QuickLendXError> {
        pause::PauseControl::require_not_paused(&env)?;
        require_not_self(&env, &business)?;

        // SECURITY LAYER 1: Require explicit authorization from the business address.
        // This ensures only the business itself can create invoices — not the admin,
        // not a third party. Prevents impersonation and unauthorized storage writes.
        business.require_auth();

        // SECURITY LAYER 2: KYC gate — only Verified ("tier-N") businesses may
        // create invoices. Pending → KYCAlreadyPending; Rejected/unknown →
        // BusinessNotVerified. This is the primary anti-spam control and enforces
        // the invariant documented in docs/KYC.md.
        require_business_not_pending(&env, &business)?;

        // Validate input parameters
        if amount <= 0 || amount > protocol_limits::MAX_INVOICE_AMOUNT {
            return Err(QuickLendXError::InvalidAmount);
        }

        let current_timestamp = env.ledger().timestamp();
        if due_date <= current_timestamp {
            return Err(QuickLendXError::InvoiceDueDateInvalid);
        }

        // Validate amount and due date using protocol limits
        // Validate due date is not too far in the future using protocol limits
        protocol_limits::ProtocolLimitsContract::validate_invoice(env.clone(), amount, due_date)?;

        protocol_limits::check_string_length(
            &description,
            protocol_limits::MAX_DESCRIPTION_LENGTH,
        )?;

        if description.is_empty() {
            return Err(QuickLendXError::InvalidDescription);
        }

        // Enforcement: reject invoices whose currency is not whitelisted (when whitelist is non-empty).
        currency::CurrencyWhitelist::require_allowed_currency(&env, &currency)?;

        // Defence-in-depth: ensure the amount is compatible with the token's
        // declared decimal precision before any state is written.
        require_matching_currency_precision(&env, &currency, amount)?;

        // Validate category and tags
        verification::validate_invoice_category(&category)?;
        verification::validate_invoice_tags(&env, &tags)?;

        // Regulatory compliance gate (reserved seam — no-op today).
        // Replace the body of `require_regulatory_ok` in `regulatory.rs` to add
        // jurisdiction-specific or on-chain oracle-based compliance checks without
        // touching this call site.
        crate::regulatory::require_regulatory_ok(&env, &business)?;

        // Create new invoice
        let invoice = Invoice::new(
            &env,
            business.clone(),
            amount,
            currency.clone(),
            due_date,
            description,
            category,
            tags,
            origination_fee_bps,
            late_payment_penalty_bps,
            early_payment_discount_bps,
        )?;

        // Store the invoice
        InvoiceStorage::store_invoice(&env, &invoice);

        // Per-invoice settlement currency whitelist (defence-in-depth)
        let mut settlement_currencies: Vec<Address> = Vec::new(&env);
        settlement_currencies.push_back(currency.clone());
        crate::settlement::store_settlement_currencies(
            &env,
            &invoice.id,
            &settlement_currencies,
        );

        // Emit event
        env.events().publish(
            (symbol_short!("created"),),
            (invoice.id.clone(), business, amount, currency, due_date),
        );

        Ok(invoice.id)
    }

    /// Upload an invoice (business only)
    pub fn upload_invoice(
        env: Env,
        business: Address,
        amount: i128,
        currency: Address,
        due_date: u64,
        description: String,
        category: InvoiceCategory,
        tags: Vec<String>,
        origination_fee_bps: Option<u32>,
        late_payment_penalty_bps: Option<u32>,
        early_payment_discount_bps: Option<u32>,
    ) -> Result<BytesN<32>, QuickLendXError> {
        pause::PauseControl::require_not_paused(&env)?;
        // Only the business can upload their own invoice
        business.require_auth();

        // Enforce business is active (not deleted/frozen).
        require_business_active(&env, &business)?;

        // Enforce KYC: reject pending and unverified/rejected businesses with distinct errors.
        // Pending businesses get KYCAlreadyPending; unverified/rejected get BusinessNotVerified.
        require_business_not_pending(&env, &business)?;

        // Basic validation
        verify_invoice_data(&env, &business, amount, &currency, due_date, &description)?;
        // Enforcement: reject invoices whose currency is not whitelisted (when whitelist is non-empty).
        currency::CurrencyWhitelist::require_allowed_currency(&env, &currency)?;

        // Defence-in-depth: ensure the amount is compatible with the token's
        // declared decimal precision before any state is written.
        require_matching_currency_precision(&env, &currency, amount)?;

        // Validate category and tags
        verification::validate_invoice_category(&category)?;
        verification::validate_invoice_tags(&env, &tags)?;

        // Check max invoices per business limit
        let limits = protocol_limits::ProtocolLimitsContract::get_protocol_limits(env.clone());
        if limits.max_invoices_per_business > 0 {
            let active_count = InvoiceStorage::count_active_business_invoices(&env, &business);
            if active_count >= limits.max_invoices_per_business {
                return Err(QuickLendXError::MaxInvoicesPerBusinessExceeded);
            }
        }

        // Create and store invoice
        let invoice = Invoice::new(
            &env,
            business.clone(),
            amount,
            currency.clone(),
            due_date,
            description.clone(),
            category,
            tags,
            origination_fee_bps,
            late_payment_penalty_bps,
            // Batch endpoint currently does not surface per-invoice early
            // payment discount; callers can post-batch-update via store_invoice
            // if a per-invoice discount is required.
            None,
        )?;
        InvoiceStorage::store_invoice(&env, &invoice);

        // Per-invoice settlement currency whitelist (defence-in-depth)
        let mut settlement_currencies: Vec<Address> = Vec::new(&env);
        settlement_currencies.push_back(currency.clone());
        crate::settlement::store_settlement_currencies(
            &env,
            &invoice.id,
            &settlement_currencies,
        );

        emit_invoice_uploaded(&env, &invoice);

        Ok(invoice.id)
    }

    /// Upload multiple invoices for the same business in a single transaction.
    ///
    /// Businesses commonly create N invoices per billing cycle. Without this
    /// entrypoint they must submit N separate transactions, each paying a
    /// separate resource fee and incurring an extra round-trip latency.
    /// `store_invoices_batch` fixes that: one auth, one transaction, up to
    /// `MAX_BATCH_INVOICES` invoices created atomically.
    ///
    /// # Authentication & KYC Policy
    ///
    /// Identical to [`upload_invoice`]:
    /// 1. **Business signature** — `business.require_auth()` is called once for
    ///    the whole batch.
    /// 2. **Verified KYC** — the business must hold a `Verified` KYC record.
    ///
    /// # Atomicity
    ///
    /// Either **all** invoices in the batch are stored, or **none** are
    /// (Soroban's transaction semantics roll back on any error).
    ///
    /// # Arguments
    /// * `env`      — The contract environment.
    /// * `business` — The address of the invoice-issuing business (must sign).
    /// * `inputs`   — A `Vec<InvoiceInput>` of length 1 ..= `MAX_BATCH_INVOICES`.
    ///
    /// # Returns
    /// * `Ok(Vec<BytesN<32>>)` — Ordered list of newly assigned invoice IDs, one
    ///   per input entry.
    ///
    /// # Errors
    /// * `ContractPaused`                  — protocol is paused.
    /// * `BatchSizeExceeded`               — `inputs` is empty or exceeds
    ///   `MAX_BATCH_INVOICES` (= 10).
    /// * `BusinessNotVerified`  (1600)     — business has no KYC record or was rejected.
    /// * `KYCAlreadyPending`    (1601)     — business KYC is still pending review.
    /// * `MaxInvoicesPerBusinessExceeded`  — the batch would push the business over
    ///   its active-invoice cap.
    /// * Any per-invoice validation error (propagated immediately, aborting the batch).
    pub fn store_invoices_batch(
        env: Env,
        business: Address,
        inputs: Vec<InvoiceInput>,
    ) -> Result<Vec<BytesN<32>>, QuickLendXError> {
        // ── Pause gate ────────────────────────────────────────────────────────
        pause::PauseControl::require_not_paused(&env)?;

        // ── Auth ──────────────────────────────────────────────────────────────
        require_not_self(&env, &business)?;
        business.require_auth();

        // ── KYC gate ──────────────────────────────────────────────────────────
        require_business_not_pending(&env, &business)?;

        // ── Batch size guard ──────────────────────────────────────────────────
        let batch_len = inputs.len();
        if batch_len == 0 || batch_len > protocol_limits::MAX_BATCH_INVOICES {
            return Err(QuickLendXError::BatchSizeExceeded);
        }

        // ── Per-business active-invoice cap ───────────────────────────────────
        // Pre-flight: the entire batch must fit within the remaining headroom.
        let limits = protocol_limits::ProtocolLimitsContract::get_protocol_limits(env.clone());
        if limits.max_invoices_per_business > 0 {
            let active_count = InvoiceStorage::count_active_business_invoices(&env, &business);
            let remaining = limits
                .max_invoices_per_business
                .saturating_sub(active_count);
            if batch_len > remaining {
                return Err(QuickLendXError::MaxInvoicesPerBusinessExceeded);
            }
        }

        // ── Validate every input before writing any storage ───────────────────
        // Two-pass approach: validate all, then write all. This makes the
        // atomicity guarantee easier to reason about and avoids partial writes.
        for input in inputs.iter() {
            verify_invoice_data(
                &env,
                &business,
                input.amount,
                &input.currency,
                input.due_date,
                &input.description,
            )?;
            currency::CurrencyWhitelist::require_allowed_currency(&env, &input.currency)?;

            // Defence-in-depth: ensure the amount is compatible with the
            // token's declared decimal precision before any state is written.
            require_matching_currency_precision(&env, &input.currency, input.amount)?;
            verification::validate_invoice_category(&input.category)?;
            verification::validate_invoice_tags(&env, &input.tags)?;
        }

        // ── Create & store invoices ───────────────────────────────────────────
        let mut ids: Vec<BytesN<32>> = Vec::new(&env);
        for input in inputs.iter() {
            let invoice = Invoice::new(
                &env,
                business.clone(),
                input.amount,
                input.currency.clone(),
                input.due_date,
                input.description.clone(),
                input.category,
                input.tags.clone(),
                None, // origination_fee_bps
                input.late_payment_penalty_bps,
                None, // early_payment_discount_bps
            )?;
            let id = invoice.id.clone();
            InvoiceStorage::store_invoice(&env, &invoice);

            // Per-invoice settlement currency whitelist (defence-in-depth)
            let mut settlement_currencies: Vec<Address> = Vec::new(&env);
            settlement_currencies.push_back(input.currency.clone());
            crate::settlement::store_settlement_currencies(
                &env,
                &invoice.id,
                &settlement_currencies,
            );

            emit_invoice_uploaded(&env, &invoice);
            ids.push_back(id);
        }

        Ok(ids)
    }

    /// Accept a bid and fund the invoice using escrow (transfer in from investor).
    ///
    /// Business must be authorized. Invoice must be Verified and bid Placed.
    /// Protected by reentrancy guard (see docs/contracts/security.md).
    ///
    /// # Returns
    /// * `Ok(BytesN<32>)` - The new escrow ID
    ///
    /// # Errors
    /// * `InvoiceNotFound`, `StorageKeyNotFound`, `InvalidStatus`, `InvoiceAlreadyFunded`, `InvoiceNotAvailableForFunding`, `Unauthorized`
    /// * `OperationNotAllowed` if reentrancy is detected
    /// * `ContractPaused` if the protocol is paused (checked first)
    ///
    /// Pause-gated: rejects with `ContractPaused` when the emergency circuit
    /// breaker is engaged, before funds are escrowed.
    pub fn accept_bid_and_fund(
        env: Env,
        invoice_id: BytesN<32>,
        bid_id: BytesN<32>,
    ) -> Result<BytesN<32>, QuickLendXError> {
        pause::PauseControl::require_not_paused(&env)?;
        reentrancy::with_payment_guard(&env, || do_accept_bid_and_fund(&env, &invoice_id, &bid_id))
    }

    /// Verify an invoice (admin or automated process)
    pub fn verify_invoice(env: Env, invoice_id: BytesN<32>) -> Result<(), QuickLendXError> {
        pause::PauseControl::require_not_paused(&env)?;
        let admin = AdminStorage::get_admin(&env).ok_or(QuickLendXError::NotAdmin)?;
        admin.require_auth();

        let mut invoice = InvoiceStorage::get_invoice(&env, &invoice_id)
            .ok_or(QuickLendXError::InvoiceNotFound)?;

        require_no_active_freeze(&env, &invoice_id)?;

        // When invoice is already funded, verify_invoice triggers release_escrow_funds (Issue #300)
        if invoice.status == InvoiceStatus::Funded {
            return Self::release_escrow_funds(env, invoice_id);
        }

        // Only allow verification if pending
        if invoice.status != InvoiceStatus::Pending {
            return Err(QuickLendXError::InvalidStatus);
        }

        // Remove from pending status list
        InvoiceStorage::remove_from_status_invoices(&env, InvoiceStatus::Pending, &invoice_id);

        invoice.verify(&env, admin.clone());
        InvoiceStorage::update_invoice(&env, &invoice);

        // Add to verified status list
        InvoiceStorage::add_to_status_invoices(&env, InvoiceStatus::Verified, &invoice_id);

        emit_invoice_verified(&env, &invoice);

        // If invoice is funded (has escrow), release escrow funds to business
        if invoice.status == InvoiceStatus::Funded {
            Self::release_escrow_funds(env.clone(), invoice_id)?;
        }

        Ok(())
    }

    /// Cancel an invoice (business only, before funding)
    pub fn cancel_invoice(env: Env, invoice_id: BytesN<32>) -> Result<(), QuickLendXError> {
        let mut invoice = require_invoice_writable_by_business(&env, &invoice_id)?;

        // Enforce KYC: a pending business must not cancel invoices.
        require_business_not_pending(&env, &invoice.business)?;

        // Remove from old status list
        InvoiceStorage::remove_from_status_invoices(&env, invoice.status, &invoice_id);

        // Cancel the invoice (only works if Pending or Verified)
        invoice.cancel(&env, invoice.business.clone())?;

        // Update storage
        InvoiceStorage::update_invoice(&env, &invoice);

        // Add to cancelled status list
        InvoiceStorage::add_to_status_invoices(&env, InvoiceStatus::Cancelled, &invoice_id);

        // Emit event
        emit_invoice_cancelled(&env, &invoice);

        Ok(())
    }

    /// Cancel a batch of invoices (business only, before funding)
    ///
    /// # Authentication & KYC Policy
    /// 1. **Business signature** — `business.require_auth()` is called once for
    ///    the whole batch.
    /// 2. **Active & Verified KYC** — business must be active and not pending.
    ///
    /// # Atomicity
    /// Either **all** invoices in the batch are cancelled, or **none** are.
    ///
    /// # Arguments
    /// * `env`         — The contract environment.
    /// * `business`    — Address of the invoice-issuing business (must sign).
    /// * `invoice_ids` — `Vec<BytesN<32>>` of length 1 ..= `MAX_BATCH_INVOICES`.
    ///
    /// # Errors
    /// * `ContractPaused`     — protocol is paused.
    /// * `BatchSizeExceeded`  — `invoice_ids` is empty or exceeds `MAX_BATCH_INVOICES` (= 10).
    /// * `SelfCallNotAllowed` — business is contract address.
    /// * `InvoiceNotFound`    — an invoice in the batch does not exist.
    /// * `InvoiceFrozen`      — an invoice in the batch is frozen.
    /// * `Unauthorized`       — an invoice in the batch does not belong to `business`.
    pub fn invoice_batch_cancel(
        env: Env,
        business: Address,
        invoice_ids: Vec<BytesN<32>>,
    ) -> Result<(), QuickLendXError> {
        // ── Pause gate ────────────────────────────────────────────────────────
        pause::PauseControl::require_not_paused(&env)?;

        // ── Auth ──────────────────────────────────────────────────────────────
        require_not_self(&env, &business)?;
        business.require_auth();

        // ── Business status & KYC gates ──────────────────────────────────────
        require_business_active(&env, &business)?;
        require_business_not_pending(&env, &business)?;

        // ── Batch size guard ──────────────────────────────────────────────────
        let batch_len = invoice_ids.len();
        if batch_len == 0 || batch_len > protocol_limits::MAX_BATCH_INVOICES {
            return Err(QuickLendXError::BatchSizeExceeded);
        }

        // ── Pre-flight pass: validate all invoices before mutating storage ────
        for id in invoice_ids.iter() {
            let invoice = InvoiceStorage::get_invoice(&env, &id)
                .ok_or(QuickLendXError::InvoiceNotFound)?;

            require_no_active_freeze(&env, &id)?;

            if invoice.business != business {
                return Err(QuickLendXError::Unauthorized);
            }
        }

        // ── Execution pass: cancel invoices, update storage, emit events ─────
        for id in invoice_ids.iter() {
            let mut invoice = InvoiceStorage::get_invoice(&env, &id)
                .ok_or(QuickLendXError::InvoiceNotFound)?;

            // Remove from old status list
            InvoiceStorage::remove_from_status_invoices(&env, invoice.status, &id);

            // Cancel invoice
            invoice.cancel(&env, business.clone())?;

            // Update storage
            InvoiceStorage::update_invoice(&env, &invoice);

            // Add to cancelled status list
            InvoiceStorage::add_to_status_invoices(&env, InvoiceStatus::Cancelled, &id);

            // Emit event
            emit_invoice_cancelled(&env, &invoice);
        }

        Ok(())
    }

    // ============================================================================
    // Invoice Freeze Management
    // ============================================================================

    /// Freeze an invoice with a specific reason (admin only).
    ///
    /// When frozen, the following operations are blocked:
    /// - `place_bid` → `InvoiceFrozen`
    /// - `accept_bid` → `InvoiceFrozen`
    /// - `process_partial_payment` → `InvoiceFrozen`
    /// - `settle_invoice` → `InvoiceFrozen`
    ///
    /// The freeze reason and metadata (who froze it, when) are stored alongside
    /// the frozen flag and are queryable via `get_invoice_freeze_info`.
    ///
    /// # Arguments
    /// * `admin`      - Must be the current protocol admin.
    /// * `invoice_id` - The invoice to freeze.
    /// * `reason`     - A `BusinessFreezeReason` variant describing why.
    ///
    /// # Errors
    /// * `NotAdmin` if the caller is not the current admin.
    /// * `InvoiceNotFound` if no invoice exists with that ID.
    pub fn freeze_invoice(
        env: Env,
        admin: Address,
        invoice_id: BytesN<32>,
        reason: BusinessFreezeReason,
    ) -> Result<(), QuickLendXError> {
        AdminStorage::require_admin(&env, &admin)?;
        // Validate that the invoice exists before freezing.
        InvoiceStorage::get_invoice(&env, &invoice_id).ok_or(QuickLendXError::InvoiceNotFound)?;

        let info = FreezeInfo {
            reason,
            frozen_by: admin.clone(),
            frozen_at: env.ledger().timestamp(),
        };
        InvoiceStorage::set_freeze_info(&env, &invoice_id, &info);
        InvoiceStorage::set_frozen(&env, &invoice_id, true, Some(reason));
        Ok(())
    }

    /// Unfreeze a previously frozen invoice (admin only).
    ///
    /// Removes the frozen flag and clears the stored freeze info.
    /// After unfreezing, all operations resume normal behaviour.
    ///
    /// # Errors
    /// * `NotAdmin` if the caller is not the current admin.
    pub fn unfreeze_invoice(
        env: Env,
        admin: Address,
        invoice_id: BytesN<32>,
    ) -> Result<(), QuickLendXError> {
        AdminStorage::require_admin(&env, &admin)?;
        InvoiceStorage::remove_freeze_info(&env, &invoice_id);
        InvoiceStorage::set_frozen(&env, &invoice_id, false, None);
        Ok(())
    }

    /// Return the stored freeze info for an invoice, if any.
    ///
    /// Returns `None` when the invoice is not frozen or does not exist.
    pub fn get_invoice_freeze_info(env: Env, invoice_id: BytesN<32>) -> Option<FreezeInfo> {
        InvoiceStorage::get_freeze_info(&env, &invoice_id)
    }

    /// Freeze an investor with a specific reason (admin only).
    ///
    /// When frozen, the following operations are blocked:
    /// - `place_bid` → `InvestorFrozen`
    /// - `withdraw_bid` → `InvestorFrozen`
    ///
    /// The freeze reason and metadata are stored alongside the frozen flag
    /// and are queryable via `get_investor_freeze_info`.
    ///
    /// # Arguments
    /// * `admin`    - Must be the current protocol admin.
    /// * `investor` - The investor to freeze.
    /// * `reason`   - An `InvestorFreezeReason` variant describing why.
    ///
    /// # Errors
    /// * `NotAdmin` if the caller is not the current admin.
    /// * `KYCNotFound` if no investor KYC record exists.
    pub fn freeze_investor(
        env: Env,
        admin: Address,
        investor: Address,
        reason: InvestorFreezeReason,
    ) -> Result<(), QuickLendXError> {
        AdminStorage::require_admin(&env, &admin)?;
        // Verify the investor has a KYC record before freezing.
        InvestorVerificationStorage::get(&env, &investor)
            .ok_or(QuickLendXError::KYCNotFound)?;

        let info = InvestorFreezeInfo {
            reason,
            frozen_by: admin.clone(),
            frozen_at: env.ledger().timestamp(),
        };
        InvoiceStorage::set_investor_freeze_info(&env, &investor, &info);
        Ok(())
    }

    /// Unfreeze a previously frozen investor (admin only).
    ///
    /// Removes the stored investor freeze info.
    /// After unfreezing, all operations resume normal behaviour.
    ///
    /// # Errors
    /// * `NotAdmin` if the caller is not the current admin.
    pub fn unfreeze_investor(
        env: Env,
        admin: Address,
        investor: Address,
    ) -> Result<(), QuickLendXError> {
        AdminStorage::require_admin(&env, &admin)?;
        InvoiceStorage::remove_investor_freeze_info(&env, &investor);
        Ok(())
    }

    /// Return the stored freeze info for an investor, if any.
    ///
    /// Returns `None` when the investor is not frozen.
    pub fn get_investor_freeze_info(env: Env, investor: Address) -> Option<InvestorFreezeInfo> {
        InvoiceStorage::get_investor_freeze_info(&env, &investor)
    }

    /// Get an invoice by ID.
    ///
    /// # Returns
    /// * `Ok(Invoice)` - The invoice data
    /// * `Err(InvoiceNotFound)` if the ID does not exist
    pub fn get_invoice(env: Env, invoice_id: BytesN<32>) -> Result<Invoice, QuickLendXError> {
        InvoiceStorage::get_invoice(&env, &invoice_id).ok_or(QuickLendXError::InvoiceNotFound)
    }

    /// Set or clear the absolute per-investor position cap for an invoice.
    ///
    /// Business-only. Prevents a single whale from cornering funding by bidding
    /// the full face value when their KYC aggregate limit would otherwise allow it.
    ///
    /// * `cap = Some(x)` requires `0 < x <= invoice.amount`
    /// * `cap = None` clears the cap (uncapped)
    ///
    /// # Errors
    /// * `InvoiceNotFound` — unknown invoice
    /// * `NotBusinessOwner` — caller is not the invoice business
    /// * `InvalidAmount` — cap is non-positive or above invoice amount
    /// * `InvalidStatus` — invoice is already funded / terminal
    /// * `ContractPaused` — protocol pause engaged
    pub fn set_per_investor_position_cap(
        env: Env,
        business: Address,
        invoice_id: BytesN<32>,
        cap: Option<i128>,
    ) -> Result<(), QuickLendXError> {
        pause::PauseControl::require_not_paused(&env)?;
        business.require_auth();

        let invoice = InvoiceStorage::get_invoice(&env, &invoice_id)
            .ok_or(QuickLendXError::InvoiceNotFound)?;
        if invoice.business != business {
            return Err(QuickLendXError::NotBusinessOwner);
        }
        require_no_active_freeze(&env, &invoice_id)?;

        // Cap may only be configured while the invoice is still open for bidding.
        if invoice.status != InvoiceStatus::Pending && invoice.status != InvoiceStatus::Verified {
            return Err(QuickLendXError::InvalidStatus);
        }

        if let Some(value) = cap {
            if value <= 0 || value > invoice.amount {
                return Err(QuickLendXError::InvalidAmount);
            }
        }

        InvoiceStorage::set_per_investor_position_cap(&env, &invoice_id, cap);
        env.events().publish(
            (symbol_short!("pos_cap"),),
            (invoice_id, business, cap),
        );
        Ok(())
    }

    /// Read the optional per-investor position cap for an invoice (`None` = uncapped).
    pub fn get_per_investor_position_cap(env: Env, invoice_id: BytesN<32>) -> Option<i128> {
        InvoiceStorage::get_per_investor_position_cap(&env, &invoice_id)
    }

    /// Get all invoices for a business
    pub fn get_invoice_by_business(env: Env, business: Address) -> Vec<BytesN<32>> {
        InvoiceStorage::get_business_invoices(&env, &business)
    }

    /// Get all invoices for a specific business
    pub fn get_business_invoices(env: Env, business: Address) -> Vec<BytesN<32>> {
        InvoiceStorage::get_business_invoices(&env, &business)
    }

    /// Update structured metadata for an invoice
    pub fn update_invoice_metadata(
        env: Env,
        invoice_id: BytesN<32>,
        metadata: InvoiceMetadata,
    ) -> Result<(), QuickLendXError> {
        let mut invoice = require_invoice_writable_by_business(&env, &invoice_id)?;
        validate_invoice_metadata(&metadata, invoice.amount)?;

        if let Some(existing) = invoice.metadata() {
            InvoiceStorage::remove_metadata_indexes(&env, &existing, &invoice.id);
        }

        invoice.set_metadata(&env, Some(metadata.clone()))?;
        InvoiceStorage::update_invoice(&env, &invoice);
        InvoiceStorage::add_metadata_indexes(&env, &invoice);

        emit_invoice_metadata_updated(&env, &invoice, &metadata);
        Ok(())
    }

    /// Clear metadata attached to an invoice
    pub fn clear_invoice_metadata(env: Env, invoice_id: BytesN<32>) -> Result<(), QuickLendXError> {
        pause::PauseControl::require_not_paused(&env)?;
        crate::governance::require_no_open_governance_proposal(&env)?;
        let mut invoice = InvoiceStorage::get_invoice(&env, &invoice_id)
            .ok_or(QuickLendXError::InvoiceNotFound)?;

        require_no_active_freeze(&env, &invoice_id)?;

        invoice.business.require_auth();
        require_business_active(&env, &invoice.business)?;

        if let Some(existing) = invoice.metadata() {
            InvoiceStorage::remove_metadata_indexes(&env, &existing, &invoice.id);
            invoice.set_metadata(&env, None)?;
            InvoiceStorage::update_invoice(&env, &invoice);
            emit_invoice_metadata_cleared(&env, &invoice);
        }

        Ok(())
    }

    /// Get invoices indexed by customer name
    pub fn get_invoices_by_customer(env: Env, customer_name: String) -> Vec<BytesN<32>> {
        InvoiceStorage::get_invoices_by_customer(&env, &customer_name)
    }

    /// Get invoices indexed by tax id
    pub fn get_invoices_by_tax_id(env: Env, tax_id: String) -> Vec<BytesN<32>> {
        InvoiceStorage::get_invoices_by_tax_id(&env, &tax_id)
    }

    /// Search invoices with relevance ranking
    ///
    /// Performs a full-text search across invoice descriptions and customer names
    /// with ranking based on match quality and recency.
    ///
    /// # Arguments
    /// * `query` - Search query string (sanitized automatically)
    ///
    /// # Returns
    /// * `Vec<SearchResult>` - Ranked search results (max 50 results)
    ///
    /// # Ranking Logic
    /// 1. Exact invoice ID matches (highest priority)
    /// 2. Partial matches in description/customer name
    /// 3. Sorted by created_at timestamp (newest first) within same rank
    ///
    /// # Security Notes
    /// - Input sanitization prevents injection attacks
    /// - Memory-safe: bounded result set prevents DoS
    /// - Case-insensitive search
    pub fn search_invoices(env: Env, query: String) -> Result<Vec<SearchResult>, QuickLendXError> {
        InvoiceSearch::search_invoices(&env, query)
    }

    /// Get all invoices by status
    pub fn get_invoices_by_status(env: Env, status: InvoiceStatus) -> Vec<BytesN<32>> {
        InvoiceStorage::get_invoices_by_status(&env, status)
    }

    /// Get all available invoices (verified and not funded)
    pub fn get_available_invoices(env: Env) -> Vec<BytesN<32>> {
        InvoiceStorage::get_invoices_by_status(&env, InvoiceStatus::Verified)
    }

    /// Update invoice status (admin function)
    pub fn update_invoice_status(
        env: Env,
        invoice_id: BytesN<32>,
        new_status: InvoiceStatus,
    ) -> Result<(), QuickLendXError> {
        pause::PauseControl::require_not_paused(&env)?;
        let admin = AdminStorage::get_admin(&env).ok_or(QuickLendXError::NotAdmin)?;

        require_no_active_freeze(&env, &invoice_id)?;

        if new_status == InvoiceStatus::Defaulted {
            // Route every default transition through the defaults module so settlement finality,
            // escrow finality, grace checks, and duplicate-default guards stay centralized.
            return do_mark_invoice_defaulted(&env, &invoice_id, None);
        }

        let mut invoice = InvoiceStorage::get_invoice(&env, &invoice_id)
            .ok_or(QuickLendXError::InvoiceNotFound)?;

        // Remove from old status list
        InvoiceStorage::remove_from_status_invoices(&env, invoice.status, &invoice_id);

        // Update status and emit canonical events matching the lifecycle
        match new_status {
            InvoiceStatus::Verified => {
                invoice.verify(&env, admin.clone());
                InvoiceStorage::update_invoice(&env, &invoice);
                InvoiceStorage::add_to_status_invoices(&env, invoice.status, &invoice_id);
                emit_invoice_verified(&env, &invoice);
            }
            InvoiceStatus::Funded => {
                // For testing purposes - normally funding happens via accept_bid
                invoice.mark_as_funded(
                    &env,
                    admin.clone(),
                    invoice.amount,
                    env.ledger().timestamp(),
                );
                InvoiceStorage::update_invoice(&env, &invoice);
                InvoiceStorage::add_to_status_invoices(&env, invoice.status, &invoice_id);
                // Emit canonical InvoiceFunded event
                events::emit_invoice_funded(&env, &invoice_id, &admin, invoice.amount);
            }
            InvoiceStatus::Paid => {
                invoice.mark_as_paid(&env, invoice.business.clone(), env.ledger().timestamp());
                InvoiceStorage::update_invoice(&env, &invoice);
                InvoiceStorage::add_to_status_invoices(&env, invoice.status, &invoice_id);
                // Emit canonical InvoiceSettled event
                let investor = invoice.investor.clone().unwrap_or(admin.clone());
                events::emit_invoice_settled(&env, &invoice, 0, 0);
                let _ = investor;
            }
            _ => return Err(QuickLendXError::InvalidStatus),
        }

        Ok(())
    }

    /// Get invoice count by status
    pub fn get_invoice_count_by_status(env: Env, status: InvoiceStatus) -> u32 {
        let invoices = InvoiceStorage::get_invoices_by_status(&env, status);
        invoices.len()
    }

    /// Get the total number of defaulted invoices for a business.
    pub fn get_business_default_history(env: Env, business: Address) -> u32 {
        let key = crate::storage::StorageKeys::business_default_history(&business);
        env.storage().persistent().get(&key).unwrap_or(0)
    }

    /// Get the total number of defaulted investments for an investor.
    ///
    /// Increments each time an invoice funded by this investor transitions to
    /// `Defaulted` (see `defaults::handle_default`). Mirrors
    /// `get_business_default_history` on the investor side.
    pub fn get_investor_default_history(env: Env, investor: Address) -> u32 {
        let key = crate::storage::StorageKeys::investor_default_history(&investor);
        env.storage().persistent().get(&key).unwrap_or(0)
    }

    /// Get total invoice count
    pub fn get_total_invoice_count(env: Env) -> u32 {
        let pending = Self::get_invoice_count_by_status(env.clone(), InvoiceStatus::Pending);
        let verified = Self::get_invoice_count_by_status(env.clone(), InvoiceStatus::Verified);
        let funded = Self::get_invoice_count_by_status(env.clone(), InvoiceStatus::Funded);
        let paid = Self::get_invoice_count_by_status(env.clone(), InvoiceStatus::Paid);
        let defaulted = Self::get_invoice_count_by_status(env.clone(), InvoiceStatus::Defaulted);
        let cancelled = Self::get_invoice_count_by_status(env.clone(), InvoiceStatus::Cancelled);
        let refunded = Self::get_invoice_count_by_status(env.clone(), InvoiceStatus::Refunded);

        pending
            .saturating_add(verified)
            .saturating_add(funded)
            .saturating_add(paid)
            .saturating_add(defaulted)
            .saturating_add(cancelled)
            .saturating_add(refunded)
    }

    /// Get a lightweight breakdown of invoice counts by category.
    ///
    /// Returns a `CategoryBreakdown` containing per-category invoice counts, suitable for
    /// dashboard pie charts and analytics. This is more efficient than computing full
    /// `FinancialMetrics` when only category distribution is needed.
    ///
    /// # Behavior
    /// - Iterates through all 9 invoice categories (Services, Goods, Consulting, Logistics,
    ///   Products, Manufacturing, Technology, Healthcare, Other)
    /// - For each category, counts invoices using the pre-built category index
    /// - Categories with zero invoices are **omitted** from the result to minimize response size
    /// - The result is bounded by the category enum size (9 entries maximum)
    ///
    /// # Returns
    /// A `CategoryBreakdown` struct containing `Vec<(InvoiceCategory, u32)>` with counts
    /// per category, sorted by iteration order of the category enum.
    ///
    /// # Performance
    /// - Read-only operation with no authorization required
    /// - Uses the persistent category index directly (no full-map rescan)
    /// - Bounded execution: O(number of categories) = O(9)
    ///
    /// # Example
    /// If platform has 10 Services invoices and 5 Products invoices:
    /// ```ignore
    /// CategoryBreakdown(vec![
    ///     (Services, 10),
    ///     (Products, 5),
    /// ])
    /// ```
    pub fn get_category_breakdown(env: Env) -> analytics::CategoryBreakdown {
        let mut breakdown = Vec::new(&env);
        let categories = InvoiceStorage::get_all_categories(&env);

        for category in categories.iter() {
            let count = InvoiceStorage::get_invoice_count_by_category_from_index(&env, &category);
            if count > 0 {
                breakdown.push_back((category, count));
            }
        }

        analytics::CategoryBreakdown(breakdown)
    }

    /// Clear all invoices from storage (admin only, used for restore operations)
    pub fn clear_all_invoices(env: Env) -> Result<(), QuickLendXError> {
        pause::PauseControl::require_not_paused(&env)?;
        use crate::storage::InvoiceStorage;
        InvoiceStorage::clear_all(&env);
        Ok(())
    }

    /// Get a bid by ID
    pub fn get_bid(env: Env, bid_id: BytesN<32>) -> Option<Bid> {
        BidStorage::get_bid(&env, &bid_id)
    }

    /// Get the highest ranked bid for an invoice
    pub fn get_best_bid(env: Env, invoice_id: BytesN<32>) -> Option<Bid> {
        BidStorage::get_best_bid(&env, &invoice_id)
    }

    /// Get all bids for an invoice sorted using the platform ranking rules
    pub fn get_ranked_bids(env: Env, invoice_id: BytesN<32>) -> Vec<Bid> {
        BidStorage::rank_bids(&env, &invoice_id)
    }

    /// Get bids filtered by status
    pub fn get_bids_by_status(env: Env, invoice_id: BytesN<32>, status: BidStatus) -> Vec<Bid> {
        BidStorage::get_bids_by_status(&env, &invoice_id, status)
    }

    /// Get bids filtered by investor
    pub fn get_bids_by_investor(env: Env, invoice_id: BytesN<32>, investor: Address) -> Vec<Bid> {
        BidStorage::get_bids_by_investor(&env, &invoice_id, &investor)
    }

    /// Get all bids for an invoice
    /// Returns a list of all bid records (including expired, withdrawn, etc.)
    /// Use get_bids_by_status to filter by status if needed
    pub fn get_bids_for_invoice(env: Env, invoice_id: BytesN<32>) -> Vec<Bid> {
        BidStorage::get_bid_records_for_invoice(&env, &invoice_id)
    }

    /// Remove bids that have passed their expiration window
    pub fn cleanup_expired_bids(env: Env, invoice_id: BytesN<32>) -> u32 {
        BidStorage::cleanup_expired_bids(&env, &invoice_id)
    }

    /// Remove expired bids with pagination support for large bid lists.
    ///
    /// # Purpose
    /// Provides paginated cleanup to prevent instruction budget exhaustion when processing
    /// invoices with many expired bids (up to MAX_BIDS_PER_INVOICE = 50).
    ///
    /// # Parameters
    /// - `offset`: Starting position in the bid list (0-indexed)
    /// - `limit`: Maximum number of bids to process (capped at MAX_BIDS_PER_INVOICE)
    ///
    /// # Returns
    /// A tuple (cleaned_count, total_remaining) where:
    /// - `cleaned_count`: Number of bids cleaned in this call
    /// - `total_remaining`: Total number of bids on invoice after cleanup
    ///
    /// # Operator Workflow
    /// For an invoice with 50 bids at maximum capacity:
    /// 1. Call with offset=0, limit=25 → processes first 25 bids
    /// 2. Call with offset=25, limit=25 → processes remaining 25 bids
    /// 3. Repeat until cleaned_count = 0 (all expired bids removed)
    ///
    /// # Gas Safety
    /// Each call processes at most `limit` bids, keeping instruction usage predictable:
    /// - limit=10: ~100-200 instructions (very safe)
    /// - limit=25: ~250-500 instructions (safe)
    /// - limit=50: ~500-1000 instructions (worst-case, may approach budget)
    pub fn cleanup_expired_bids_paged(
        env: Env,
        invoice_id: BytesN<32>,
        offset: u32,
        limit: u32,
    ) -> (u32, u32) {
        BidStorage::cleanup_expired_bids_paged(&env, &invoice_id, offset, limit)
    }

    /// Cancel a placed bid (investor only, Placed --- Cancelled).
    ///
    /// # Race Safety
    /// Uses a read-check-write pattern that validates the bid is still in `Placed`
    /// status before transitioning. Terminal statuses (`Withdrawn`, `Accepted`,
    /// `Expired`, `Cancelled`) are immutable --- a bid that has already left `Placed`
    /// will cause this function to return `false` without any state mutation,
    /// preventing double-action execution regardless of call ordering.
    pub fn cancel_bid(env: Env, bid_id: BytesN<32>) -> bool {
        pause::PauseControl::require_not_paused(&env).is_ok()
            && bid::BidStorage::cancel_bid(&env, &bid_id)
    }

    /// Withdraw a bid (investor only, Placed --- Withdrawn).
    ///
    /// # Race Safety
    /// Validates `BidStatus::Placed` atomically before transitioning. If a
    /// concurrent `cancel_bid` or expiry has already moved the bid to a terminal
    /// status, this call returns `OperationNotAllowed` without mutating state,
    /// preventing double-action execution.
    pub fn withdraw_bid(env: Env, bid_id: BytesN<32>) -> Result<(), QuickLendXError> {
        pause::PauseControl::require_not_paused(&env)?;
        let mut bid = BidStorage::get_bid(&env, &bid_id).unwrap();
        bid.investor.require_auth();
        require_investor_not_frozen(&env, &bid.investor)?;
        require_investor_not_pending(&env, &bid.investor)?;
        // Re-read status after auth to guard against concurrent transitions.
        let bid_fresh = BidStorage::get_bid(&env, &bid_id).unwrap();
        if bid_fresh.status != BidStatus::Placed {
            return Err(QuickLendXError::OperationNotAllowed);
        }
        bid.status = BidStatus::Withdrawn;
        BidStorage::update_bid(&env, &bid);
        crate::qlx_log!(&env, "bid", "Bid withdrawn");
        emit_bid_withdrawn(&env, &bid);
        Ok(())
    }

    /// Get all bids placed by an investor across all invoices.
    pub fn get_all_bids_by_investor(env: Env, investor: Address) -> Vec<Bid> {
        bid::BidStorage::get_all_bids_by_investor(&env, &investor)
    }

    /// Place a bid on an invoice
    ///
    /// Validates:
    /// - Invoice exists and is verified
    /// - Bid amount is positive
    /// - Investor is authorized and verified
    /// - Creates and stores the bid
    ///
    /// Pause-gated: rejects with `ContractPaused` when the emergency circuit
    /// @deprecated salt is no longer used for idempotency
    /// breaker is engaged, before the bid is validated or stored.
    pub fn place_bid(
        env: Env,
        investor: Address,
        invoice_id: BytesN<32>,
        bid_amount: i128,
        expected_return: i128,
        salt: BytesN<32>,
    ) -> Result<BytesN<32>, QuickLendXError> {
        pause::PauseControl::require_not_paused(&env)?;
        require_not_self(&env, &investor)?;
        // Regulatory compliance gate (reserved seam — no-op today).
        // Replace the body of `require_regulatory_ok` in `regulatory.rs` to add
        // jurisdiction-specific or on-chain oracle-based compliance checks without
        // touching this call site.
        crate::regulatory::require_regulatory_ok(&env, &investor)?;
        // Reject bids from frozen investors.
        require_investor_not_frozen(&env, &investor)?;
        // Idempotency check
        let idem_key = idempotency_key(&invoice_id, &investor, &salt, &env);
        if idempotency_exists(&env, &idem_key) {
            return Err(QuickLendXError::DuplicateBid);
        }
        // Authorization check: Only the investor can place their own bid
        investor.require_auth();

        // Validate bid amount is positive
        if bid_amount <= 0 {
            return Err(QuickLendXError::InvalidAmount);
        }

        // Validate expected_return fits safely in i128 arithmetic.
        // Without the upper bound an attacker could submit i128::MAX,
        // causing compare_bids to saturate silently and distort ranking.
        if expected_return > crate::protocol_limits::MAX_INVOICE_AMOUNT {
            return Err(QuickLendXError::InvalidAmount);
        }

        // Validate invoice exists and is verified
        let invoice = InvoiceStorage::get_invoice(&env, &invoice_id)
            .ok_or(QuickLendXError::InvoiceNotFound)?;
        if InvoiceStorage::is_frozen(&env, &invoice_id) {
            InvoiceStorage::require_lock_within_time_limit(&env, &invoice_id)?;
            return Err(QuickLendXError::InvoiceFrozen);
        }
        require_no_active_freeze(&env, &invoice_id)?;
        if invoice.status != InvoiceStatus::Verified {
            return Err(QuickLendXError::InvalidStatus);
        }
        // Enforcement: reject bids on invoices whose currency was removed from the whitelist after creation.
        currency::CurrencyWhitelist::require_allowed_currency(&env, &invoice.currency)?;

        // Defence-in-depth: ensure the bid amount is compatible with the
        // invoice currency's declared decimal precision.
        require_matching_currency_precision(&env, &invoice.currency, bid_amount)?;

        let verification = do_get_investor_verification(&env, &investor)
            .ok_or(QuickLendXError::InvestorNotVerified)?; // Changed error to InvestorNotVerified
        match verification.status {
            BusinessVerificationStatus::Verified => {
                if bid_amount > verification.investment_limit {
                    return Err(QuickLendXError::InvalidAmount);
                }
                crate::verification::require_tier_min_investment_amount(&verification.tier, bid_amount)?;
            }
            BusinessVerificationStatus::Pending => return Err(QuickLendXError::KYCAlreadyPending),
            BusinessVerificationStatus::Rejected => {
                // This is for BusinessVerificationStatus, but used for InvestorVerification.
                return Err(QuickLendXError::InvestorNotVerified); // Changed error to InvestorNotVerified
            }
        }

        BidStorage::cleanup_expired_bids(&env, &invoice_id);
        // Check if maximum bids per invoice limit is reached
        let active_bid_count = BidStorage::get_active_bid_count(&env, &invoice_id);
        if active_bid_count >= bid::MAX_BIDS_PER_INVOICE {
            return Err(QuickLendXError::MaxBidsPerInvoiceExceeded);
        }

        if BidStorage::investor_has_reached_bid_limit(&env, &investor) {
            return Err(QuickLendXError::MaxActiveBidsPerInvestorExceeded);
        }
        validate_bid(&env, &invoice, bid_amount, expected_return, &investor)?;
        // Create bid
        let bid_id = BidStorage::generate_unique_bid_id(&env);
        let current_timestamp = env.ledger().timestamp();
        let bid = Bid {
            bid_id: bid_id.clone(),
            invoice_id: invoice_id.clone(),
            investor: investor.clone(),
            bid_amount,
            expected_return,
            timestamp: current_timestamp,
            status: BidStatus::Placed,
            expiration_timestamp: Bid::default_expiration_with_env(&env, current_timestamp),
        };
        BidStorage::store_bid(&env, &bid);
        // Track bid for this invoice
        BidStorage::add_bid_to_invoice(&env, &invoice_id, &bid_id);
        // Store idempotency marker
        store_idempotency(&env, &idem_key);

        crate::qlx_log!(
            &env,
            "bid",
            "Bid placed: amount={} expected_return={}",
            bid_amount,
            expected_return
        );

        // Emit bid placed event
        emit_bid_placed(&env, &bid);

        Ok(bid_id)
    }

    /// Accept a bid (business only).
    /// Protected by payment reentrancy guard.
    pub fn accept_bid(
        env: Env,
        invoice_id: BytesN<32>,
        bid_id: BytesN<32>,
    ) -> Result<(), QuickLendXError> {
        pause::PauseControl::require_not_paused(&env)?;
        reentrancy::with_payment_guard(&env, || {
            Self::accept_bid_impl(env.clone(), invoice_id.clone(), bid_id.clone())
        })
    }

    fn accept_bid_impl(
        env: Env,
        invoice_id: BytesN<32>,
        bid_id: BytesN<32>,
    ) -> Result<(), QuickLendXError> {
        BidStorage::cleanup_expired_bids(&env, &invoice_id);
        let mut invoice = InvoiceStorage::get_invoice(&env, &invoice_id)
            .ok_or(QuickLendXError::InvoiceNotFound)?;
        if InvoiceStorage::is_frozen(&env, &invoice_id) {
            InvoiceStorage::require_lock_within_time_limit(&env, &invoice_id)?;
            return Err(QuickLendXError::InvoiceFrozen);
        }
        require_no_active_freeze(&env, &invoice_id)?;
        let bid = BidStorage::get_bid(&env, &bid_id).unwrap();
        let invoice_id = bid.invoice_id.clone();
        BidStorage::cleanup_expired_bids(&env, &invoice_id);
        let mut bid = BidStorage::get_bid(&env, &bid_id).unwrap();
        require_investor_not_frozen(&env, &bid.investor)?;
        invoice.business.require_auth();

        // Enforce business is active (not deleted/frozen).
        require_business_active(&env, &invoice.business)?;

        // Enforce KYC: a pending business must not accept bids.
        require_business_not_pending(&env, &invoice.business)?;

        if invoice.status != InvoiceStatus::Verified || bid.status != BidStatus::Placed {
            return Err(QuickLendXError::InvalidStatus);
        }

        let escrow_id = create_escrow(
            &env,
            &invoice_id,
            &bid.investor,
            &invoice.business,
            bid.bid_amount,
            &invoice.currency,
        )?;
        bid.status = BidStatus::Accepted;
        BidStorage::update_bid(&env, &bid);
        // Remove from old status list before changing status
        InvoiceStorage::remove_from_status_invoices(&env, InvoiceStatus::Verified, &invoice_id);

        invoice.mark_as_funded(
            &env,
            bid.investor.clone(),
            bid.bid_amount,
            env.ledger().timestamp(),
        );
        InvoiceStorage::update_invoice(&env, &invoice);

        // Add to new status list after status change
        InvoiceStorage::add_to_status_invoices(&env, InvoiceStatus::Funded, &invoice_id);
        let investment_id = InvestmentStorage::generate_unique_investment_id(&env);
        let investment = Investment {
            investment_id: investment_id.clone(),
            invoice_id: invoice_id.clone(),
            investor: bid.investor.clone(),
            amount: bid.bid_amount,
            funded_at: env.ledger().timestamp(),
            status: InvestmentStatus::Active,
            insurance: Vec::new(&env),
        };
        InvestmentStorage::store_investment(&env, &investment);

        let escrow = EscrowStorage::get_escrow(&env, &escrow_id).unwrap();
        emit_escrow_created(&env, &escrow);
        emit_bid_accepted(&env, &bid, &invoice_id, &invoice.business);

        Ok(())
    }

    /// Add insurance coverage to an active investment (investor only).
    ///
    /// # Arguments
    /// * `investment_id` - The investment to insure
    /// * `provider` - Insurance provider address
    /// * `coverage_percentage` - Coverage as a percentage (e.g. 80 for 80%)
    ///
    /// # Returns
    /// * `Ok(())` on success
    ///
    /// # Errors
    /// * `StorageKeyNotFound` if investment does not exist
    /// * `InvalidStatus` if investment is not Active
    /// * `InsuranceClaimWindowClosed` if the invoice due date has already passed
    /// * `InvalidAmount` if computed premium is zero
    ///
    /// # Security
    /// Insurance opt-in is only permitted while the invoice due date is in the
    /// future (`ledger.timestamp() < invoice.due_date`). Allowing opt-in after
    /// the due date would let an attacker insure a position that is already
    /// certain to default, then immediately trigger the default to collect the
    /// coverage payout — an adverse-selection exploit with zero economic risk
    /// to the attacker and unbounded liability for the insurance provider.
    pub fn add_investment_insurance(
        env: Env,
        investment_id: BytesN<32>,
        provider: Address,
        coverage_percentage: u32,
    ) -> Result<(), QuickLendXError> {
        pause::PauseControl::require_not_paused(&env)?;
        let mut investment = InvestmentStorage::get_investment(&env, &investment_id).unwrap();

        investment.investor.require_auth();

        if investment.status != InvestmentStatus::Active {
            return Err(QuickLendXError::InvalidStatus);
        }

        // Security: reject opt-in after the invoice due date.
        //
        // Once the due date has passed the invoice is overdue and default is
        // imminent. An investor who opts in at that point bears zero timing
        // risk yet receives the full coverage payout — a classic adverse-
        // selection exploit (insuring a burning building). The claim window
        // must close no later than the due date.
        let invoice = InvoiceStorage::get_invoice(&env, &investment.invoice_id)
            .ok_or(QuickLendXError::InvoiceNotFound)?;
        if env.ledger().timestamp() >= invoice.due_date {
            return Err(QuickLendXError::InsuranceClaimWindowClosed);
        }

        let premium = Investment::calculate_premium(investment.amount, coverage_percentage);
        if premium <= 0 {
            return Err(QuickLendXError::InvalidAmount);
        }

        let coverage_amount =
            investment.add_insurance(provider.clone(), coverage_percentage, premium)?;

        InvestmentStorage::update_investment(&env, &investment);

        emit_insurance_added(
            &env,
            &investment_id,
            &investment.invoice_id,
            &investment.investor,
            &provider,
            coverage_percentage,
            coverage_amount,
            premium,
        );
        emit_insurance_premium_collected(&env, &investment_id, &provider, premium);

        Ok(())
    }

    /// Settle an invoice (business or automated process)
    ///
    /// Pause-gated: rejects with `ContractPaused` when the emergency circuit
    /// breaker is engaged, before settlement payout is computed.
    pub fn settle_invoice(
        env: Env,
        invoice_id: BytesN<32>,
        payment_amount: i128,
        snap: crate::types::Investment,
    ) -> Result<(), QuickLendXError> {
        pause::PauseControl::require_not_paused(&env)?;
        let _investment = InvestmentStorage::get_investment_by_invoice(&env, &invoice_id);

        let result = reentrancy::with_payment_guard(&env, || {
            do_settle_invoice(&env, &invoice_id, payment_amount, &snap)
        });

        if result.is_ok() {
            // Success
        }

        result
    }

    /// Get the investment record for a funded invoice.
    ///
    /// # Returns
    /// * `Ok(Investment)` - The investment tied to the invoice
    /// * `Err(StorageKeyNotFound)` if the invoice has no investment
    pub fn get_invoice_investment(
        env: Env,
        invoice_id: BytesN<32>,
    ) -> Result<Investment, QuickLendXError> {
        InvestmentStorage::get_investment_by_invoice(&env, &invoice_id)
            .ok_or(QuickLendXError::StorageKeyNotFound)
    }

    /// Get an investment by ID.
    ///
    /// # Returns
    /// * `Ok(Investment)` - The investment record
    /// * `Err(StorageKeyNotFound)` if the ID does not exist
    pub fn get_investment(
        env: Env,
        investment_id: BytesN<32>,
    ) -> Result<Investment, QuickLendXError> {
        InvestmentStorage::get_investment(&env, &investment_id)
            .ok_or(QuickLendXError::StorageKeyNotFound)
    }

    /// Return all active investment IDs.
    pub fn get_active_investment_ids(env: Env) -> Vec<BytesN<32>> {
        InvestmentStorage::get_active_investment_ids(&env)
    }

    /// Validate that no terminal investments remain in the active index.
    pub fn validate_no_orphan_investments(env: Env) -> bool {
        storage::StorageIntegrityAudit::audit_investment_integrity(&env).is_ok()
    }

    /// Query insurance coverage for an investment.
    ///
    /// # Arguments
    /// * `investment_id` - The investment to query
    ///
    /// # Returns
    /// * `Ok(Vec<InsuranceCoverage>)` - All insurance records for the investment
    /// * `Err(StorageKeyNotFound)` if the investment does not exist
    ///
    /// # Security Notes
    /// - Returns all insurance records (active and inactive)
    /// - No authorization required for queries
    pub fn query_investment_insurance(
        env: Env,
        investment_id: BytesN<32>,
    ) -> Result<Vec<InsuranceCoverage>, QuickLendXError> {
        let investment = InvestmentStorage::get_investment(&env, &investment_id).unwrap();
        Ok(investment.insurance)
    }

    /// Process a partial payment towards an invoice.
    /// Protected by payment reentrancy guard.
    ///
    /// Pause-gated: rejects with `ContractPaused` when the emergency circuit
    /// breaker is engaged, before any payment state is mutated.
    pub fn process_partial_payment(
        env: Env,
        invoice_id: BytesN<32>,
        payment_amount: i128,
        transaction_id: String,
    ) -> Result<(), QuickLendXError> {
        pause::PauseControl::require_not_paused(&env)?;
        reentrancy::with_payment_guard(&env, || {
            do_process_partial_payment(&env, &invoice_id, payment_amount, transaction_id.clone())
        })
    }

    /// Make a payment towards an invoice (alias for process_partial_payment).
    /// Protected by payment reentrancy guard.
    ///
    /// Convenience entry point used by tests and off-chain clients.
    /// Delegates to `process_partial_payment` with identical semantics.
    ///
    /// Pause-gated: rejects with `ContractPaused` when the emergency circuit
    /// breaker is engaged, before any payment state is mutated.
    pub fn make_payment(
        env: Env,
        invoice_id: BytesN<32>,
        payment_amount: i128,
        transaction_id: String,
    ) -> Result<(), QuickLendXError> {
        pause::PauseControl::require_not_paused(&env)?;
        reentrancy::with_payment_guard(&env, || {
            do_process_partial_payment(&env, &invoice_id, payment_amount, transaction_id.clone())
        })
    }

    /// Expire an invoice that has passed its due date without being funded.
    ///
    /// Emits `InvoiceExpired` and transitions the invoice to `Defaulted` if funded,
    /// or marks it as expired otherwise.
    pub fn expire_invoice(env: Env, invoice_id: BytesN<32>) -> Result<(), QuickLendXError> {
        pause::PauseControl::require_not_paused(&env)?;
        let invoice = InvoiceStorage::get_invoice(&env, &invoice_id)
            .ok_or(QuickLendXError::InvoiceNotFound)?;
        let current_ts = env.ledger().timestamp();
        if current_ts <= invoice.due_date {
            return Err(QuickLendXError::OperationNotAllowed);
        }
        // Emit the InvoiceExpired event
        events::emit_invoice_expired(&env, &invoice);
        Ok(())
    }

    /// Refund escrow funds to the investor (alias for refund_escrow_funds with admin/business auth).
    ///
    /// Convenience entry point used by tests and off-chain clients.
    pub fn refund_escrow(env: Env, invoice_id: BytesN<32>) -> Result<(), QuickLendXError> {
        pause::PauseControl::require_not_paused(&env)?;
        let admin = AdminStorage::get_admin(&env).ok_or(QuickLendXError::NotAdmin)?;
        reentrancy::with_payment_guard(&env, || do_refund_escrow_funds(&env, &invoice_id, &admin))
    }

    /// Clean up expired bids for an invoice (alias for cleanup_expired_bids).
    ///
    /// Convenience entry point used by tests and off-chain clients.
    pub fn clean_expired_bids(env: Env, invoice_id: BytesN<32>) -> u32 {
        BidStorage::cleanup_expired_bids(&env, &invoice_id)
    }

    /// Handle invoice default (admin only)
    /// This is the internal handler - use mark_invoice_defaulted for public API
    pub fn handle_default(env: Env, invoice_id: BytesN<32>) -> Result<(), QuickLendXError> {
        pause::PauseControl::require_not_paused(&env)?;
        let admin = AdminStorage::get_admin(&env).ok_or(QuickLendXError::NotAdmin)?;
        admin.require_auth();

        // Get the investment to track investor analytics
        let _investment = InvestmentStorage::get_investment_by_invoice(&env, &invoice_id);

        do_handle_default(&env, &invoice_id)
    }

    /// Mark an invoice as defaulted (admin only)
    /// Checks due date + grace period before marking as defaulted.
    /// Requires admin authorization to prevent unauthorized default marking.
    ///
    /// # Arguments
    /// * `invoice_id` - The invoice ID to mark as defaulted
    /// * `grace_period` - Optional grace period in seconds (defaults to 7 days)
    ///
    /// # Returns
    /// * `Ok(())` if the invoice was successfully marked as defaulted
    /// * `Err(QuickLendXError)` if the operation fails
    ///
    /// # Errors
    /// * `NotAdmin` - No admin configured or caller is not admin
    /// * `InvoiceNotFound` - Invoice does not exist
    /// * `InvoiceAlreadyDefaulted` - Invoice is already defaulted
    /// * `InvoiceNotAvailableForFunding` - Invoice is not in Funded status
    /// * `OperationNotAllowed` - Grace period has not expired yet
    pub fn mark_invoice_defaulted(
        env: Env,
        invoice_id: BytesN<32>,
        grace_period: Option<u64>,
    ) -> Result<(), QuickLendXError> {
        pause::PauseControl::require_not_paused(&env)?;
        let admin = AdminStorage::get_admin(&env).ok_or(QuickLendXError::NotAdmin)?;
        admin.require_auth();

        // Get the investment to track investor analytics
        let _investment = InvestmentStorage::get_investment_by_invoice(&env, &invoice_id);

        do_mark_invoice_defaulted(&env, &invoice_id, grace_period)
    }

    /// Calculate profit and platform fee
    pub fn calculate_profit(
        env: Env,
        investment_amount: i128,
        payment_amount: i128,
    ) -> (i128, i128) {
        do_calculate_profit(&env, investment_amount, payment_amount)
    }

    /// Retrieve the current platform fee configuration
    pub fn get_platform_fee(env: Env) -> types::PlatformFeeConfig {
        PlatformFee::get_config(&env)
    }

    /// Update the platform fee basis points (admin only)
    pub fn set_platform_fee(env: Env, new_fee_bps: i128) -> Result<(), QuickLendXError> {
        pause::PauseControl::require_not_paused(&env)?;
        let admin = AdminStorage::get_admin(&env).ok_or(QuickLendXError::NotAdmin)?;
        PlatformFee::set_config(&env, &admin, new_fee_bps)?;
        Ok(())
    }

    // Business KYC/Verification Functions (from main)

    /// Submit KYC application (business only)
    pub fn submit_kyc_application(
        env: Env,
        business: Address,
        kyc_data: String,
    ) -> Result<(), QuickLendXError> {
        pause::PauseControl::require_not_paused(&env)?;
        require_not_self(&env, &business)?;
        submit_kyc_application(&env, &business, kyc_data)
    }

    /// Submit investor verification request
    pub fn submit_investor_kyc(
        env: Env,
        investor: Address,
        kyc_data: String,
    ) -> Result<(), QuickLendXError> {
        pause::PauseControl::require_not_paused(&env)?;
        require_not_self(&env, &investor)?;
        do_submit_investor_kyc(&env, &investor, kyc_data)
    }

    /// Verify an investor and set an investment limit
    pub fn verify_investor(
        env: Env,
        investor: Address,
        investment_limit: i128,
    ) -> Result<(), QuickLendXError> {
        pause::PauseControl::require_not_paused(&env)?;
        let admin =
            BusinessVerificationStorage::get_admin(&env).ok_or(QuickLendXError::NotAdmin)?;
        let verification = do_verify_investor(&env, &admin, &investor, investment_limit)?;
        emit_investor_verified(&env, &verification);
        Ok(())
    }

    /// Get all verified businesses
    pub fn get_verified_businesses(env: Env) -> Vec<Address> {
        BusinessVerificationStorage::get_verified_businesses(&env)
    }

    /// Reject an investor verification request
    pub fn reject_investor(
        env: Env,
        investor: Address,
        reason: String,
    ) -> Result<(), QuickLendXError> {
        pause::PauseControl::require_not_paused(&env)?;
        let admin = AdminStorage::get_admin(&env).ok_or(QuickLendXError::NotAdmin)?;
        do_reject_investor(&env, &admin, &investor, reason)
    }

    /// Revoke a verified investor's KYC (admin only).
    ///
    /// Moves the investor from `Verified` back to `Rejected`, emits a
    /// `kyc_revoke` event, and blocks all further bids (via
    /// `validate_investor_investment`) until the investor re-submits KYC and is
    /// re-verified.
    pub fn revoke_investor_kyc(
        env: Env,
        investor: Address,
        reason: String,
    ) -> Result<(), QuickLendXError> {
        pause::PauseControl::require_not_paused(&env)?;
        let admin = AdminStorage::get_admin(&env).ok_or(QuickLendXError::NotAdmin)?;
        do_revoke_investor_kyc(&env, &admin, &investor, reason)
    }

    /// Get investor verification record if available
    pub fn get_investor_verification(env: Env, investor: Address) -> Option<InvestorVerification> {
        do_get_investor_verification(&env, &investor)
    }

    /// Set investment limit for a verified investor (admin only).
    pub fn set_investment_limit(
        env: Env,
        investor: Address,
        new_limit: i128,
    ) -> Result<(), QuickLendXError> {
        pause::PauseControl::require_not_paused(&env)?;
        let admin =
            BusinessVerificationStorage::get_admin(&env).ok_or(QuickLendXError::NotAdmin)?;
        verification::set_investment_limit(&env, &admin, &investor, new_limit)
    }

    /// Recompute investor tier from tracked investment performance.
    pub fn recompute_investor_tier(
        env: Env,
        admin: Address,
        investor: Address,
    ) -> Result<(), QuickLendXError> {
        pause::PauseControl::require_not_paused(&env)?;
        recompute_investor_tier(&env, &admin, &investor)
    }

    /// Recompute investor rating from on-chain history deterministically.
    ///
    /// Recalculates the risk score, tier, risk level, and investment limit from
    /// the investor's accumulated performance counters and KYC data, then
    /// updates the stored verification record in place.
    ///
    /// # Arguments
    /// * `admin` - The admin address (must be authorized)
    /// * `investor` - The investor address to recompute the rating for
    ///
    /// # Returns
    /// * `Ok(InvestorVerification)` - The updated verification record with the new rating
    ///
    /// # Errors
    /// * `NotAdmin` if the caller is not the current admin
    /// * `KYCNotFound` if the investor has no verification record
    /// * `InvalidKYCStatus` if the investor is not verified
    pub fn investor_rating_recompute(
        env: Env,
        admin: Address,
        investor: Address,
    ) -> Result<InvestorVerification, QuickLendXError> {
        pause::PauseControl::require_not_paused(&env)?;
        verification::investor_rating_recompute(&env, &admin, &investor)
    }

    /// Verify business (admin only)
    pub fn verify_business(
        // This function is already defined in verification module
        env: Env,
        admin: Address,
        business: Address,
    ) -> Result<(), QuickLendXError> {
        pause::PauseControl::require_not_paused(&env)?;
        verify_business(&env, &admin, &business)
    }

    /// Reject business (admin only)
    pub fn reject_business(
        // This function is already defined in verification module
        env: Env,
        admin: Address,
        business: Address,
        reason: String,
    ) -> Result<(), QuickLendXError> {
        pause::PauseControl::require_not_paused(&env)?;
        reject_business(&env, &admin, &business, reason)
    }

    /// Get business verification status
    pub fn get_business_verification_status(
        // This function is already defined in verification module
        env: Env,
        business: Address,
    ) -> Option<verification::BusinessVerification> {
        verification::get_business_verification_status(&env, &business)
    }

    /// Set admin address (initialization function)
    pub fn set_admin(env: Env, admin: Address) -> Result<(), QuickLendXError> {
        if let Some(current_admin) = BusinessVerificationStorage::get_admin(&env) {
            current_admin.require_auth();
        } else {
            admin.require_auth();
        }
        BusinessVerificationStorage::set_admin(&env, &admin);
        Ok(())
    }

    /// Get admin address // This function is already defined in admin module
    pub fn get_admin(env: Env) -> Option<Address> {
        BusinessVerificationStorage::get_admin(&env)
    }

    /// Initialize protocol limits (admin only). Sets min amount, max due date days, grace period.
    ///
    /// `min_bid_amount` and `min_bid_bps` are preserved at their current/default values.
    /// Use [`set_protocol_limits_full`] to set every limit in a single call.
    pub fn initialize_protocol_limits(
        env: Env,
        admin: Address,
        min_invoice_amount: i128,
        max_due_date_days: u64,
        grace_period_seconds: u64,
    ) -> Result<(), QuickLendXError> {
        let _ = protocol_limits::ProtocolLimitsContract::initialize(env.clone(), admin.clone());
        let existing = protocol_limits::ProtocolLimitsContract::get_protocol_limits(env.clone());
        protocol_limits::ProtocolLimitsContract::set_protocol_limits_authed(
            &env,
            &admin,
            min_invoice_amount,
            existing.min_bid_amount,
            existing.min_bid_bps,
            max_due_date_days,
            grace_period_seconds,
            existing.max_invoices_per_business,
            existing.min_investor_tier,
        )
    }

    /// Update protocol limits (admin only).
    ///
    /// `min_bid_amount`, `min_bid_bps`, and `max_invoices_per_business` are
    /// preserved at their current values.  Use [`set_protocol_limits_full`] to
    /// update every limit in a single call.
    pub fn set_protocol_limits(
        env: Env,
        admin: Address,
        min_invoice_amount: i128,
        max_due_date_days: u64,
        grace_period_seconds: u64,
    ) -> Result<(), QuickLendXError> {
        pause::PauseControl::require_not_paused(&env)?;
        // Preserve current bid limits; fall back to compile-time defaults if not yet set.
        let existing = protocol_limits::ProtocolLimitsContract::get_protocol_limits(env.clone());
        protocol_limits::ProtocolLimitsContract::set_protocol_limits(
            env,
            admin,
            min_invoice_amount,
            existing.min_bid_amount,
            existing.min_bid_bps,
            max_due_date_days,
            grace_period_seconds,
            existing.max_invoices_per_business,
            existing.min_investor_tier,
        )
    }

    /// Update protocol limits (admin only).
    ///
    /// `min_bid_amount`, `min_bid_bps`, and `max_invoices_per_business` are
    /// preserved at their current values.  Use [`set_protocol_limits_full`] to
    /// update every limit in a single call.
    pub fn update_protocol_limits(
        env: Env,
        admin: Address,
        min_invoice_amount: i128,
        max_due_date_days: u64,
        grace_period_seconds: u64,
    ) -> Result<(), QuickLendXError> {
        pause::PauseControl::require_not_paused(&env)?;
        // Preserve current bid limits; fall back to compile-time defaults if not yet set.
        let existing = protocol_limits::ProtocolLimitsContract::get_protocol_limits(env.clone());
        protocol_limits::ProtocolLimitsContract::set_protocol_limits(
            env,
            admin,
            min_invoice_amount,
            existing.min_bid_amount,
            existing.min_bid_bps,
            max_due_date_days,
            grace_period_seconds,
            existing.max_invoices_per_business,
            existing.min_investor_tier,
        )
    }

    /// Update protocol limits with max invoices per business (admin only).
    ///
    /// `min_bid_amount` and `min_bid_bps` are preserved at their current values.
    /// Use [`set_protocol_limits_full`] to update every limit in a single call.
    pub fn update_limits_max_invoices(
        env: Env,
        admin: Address,
        min_invoice_amount: i128,
        max_due_date_days: u64,
        grace_period_seconds: u64,
        max_invoices_per_business: u32,
    ) -> Result<(), QuickLendXError> {
        pause::PauseControl::require_not_paused(&env)?;
        // Preserve current bid limits; fall back to compile-time defaults if not yet set.
        let existing = protocol_limits::ProtocolLimitsContract::get_protocol_limits(env.clone());
        protocol_limits::ProtocolLimitsContract::set_protocol_limits(
            env,
            admin,
            min_invoice_amount,
            existing.min_bid_amount,
            existing.min_bid_bps,
            max_due_date_days,
            grace_period_seconds,
            max_invoices_per_business,
            existing.min_investor_tier,
        )
    }

    /// Update **all** protocol limits in a single call (admin only).
    ///
    /// This is the preferred entrypoint when operators need to configure
    /// `min_bid_amount` or `min_bid_bps` alongside the other limits.  The
    /// narrower helpers (`set_protocol_limits`, `update_protocol_limits`,
    /// `update_limits_max_invoices`) preserve the current bid-limit values for
    /// backwards compatibility.
    ///
    /// # Parameters
    /// - `min_invoice_amount`       – minimum invoice face value (inclusive).
    /// - `min_bid_amount`           – minimum absolute bid amount (inclusive).
    ///                                Pass [`DEFAULT_MIN_BID_AMOUNT`] (10) to
    ///                                keep the compile-time default.
    /// - `min_bid_bps`              – minimum bid rate in basis points (inclusive).
    ///                                Pass [`DEFAULT_MIN_BID_BPS`] (100) to keep
    ///                                the compile-time default.
    /// - `max_due_date_days`        – maximum invoice horizon in days (1..=730).
    /// - `grace_period_seconds`     – grace period after due date (0..=2_592_000).
    /// - `max_invoices_per_business`– per-business active-invoice cap; 0 = unlimited.
    ///
    /// # Errors
    /// Delegates to `ProtocolLimitsContract::set_protocol_limits` for all
    /// parameter validation; see that function's docs for error codes.
    pub fn set_protocol_limits_full(
        env: Env,
        admin: Address,
        min_invoice_amount: i128,
        min_bid_amount: i128,
        min_bid_bps: u32,
        max_due_date_days: u64,
        grace_period_seconds: u64,
        max_invoices_per_business: u32,
        min_investor_tier: crate::verification::InvestorTier,
    ) -> Result<(), QuickLendXError> {
        pause::PauseControl::require_not_paused(&env)?;
        protocol_limits::ProtocolLimitsContract::set_protocol_limits(
            env,
            admin,
            min_invoice_amount,
            min_bid_amount,
            min_bid_bps,
            max_due_date_days,
            grace_period_seconds,
            max_invoices_per_business,
            min_investor_tier,
        )
    }

    /// Get all pending businesses
    pub fn get_pending_businesses(env: Env) -> Vec<Address> {
        BusinessVerificationStorage::get_pending_businesses(&env)
    }

    /// Get all rejected businesses
    pub fn get_rejected_businesses(env: Env) -> Vec<Address> {
        BusinessVerificationStorage::get_rejected_businesses(&env)
    }

    // ========================================
    // Enhanced Investor Verification Functions
    // ========================================

    /// Get all verified investors
    pub fn get_verified_investors(env: Env) -> Vec<Address> {
        InvestorVerificationStorage::get_verified_investors(&env)
    }

    /// Get all pending investors
    pub fn get_pending_investors(env: Env) -> Vec<Address> {
        InvestorVerificationStorage::get_pending_investors(&env)
    }

    /// Get all rejected investors
    pub fn get_rejected_investors(env: Env) -> Vec<Address> {
        InvestorVerificationStorage::get_rejected_investors(&env)
    }

    /// Update investor analytics (test helper)
    pub fn update_investor_analytics(
        env: Env,
        investor: Address,
        amount: i128,
        is_success: bool,
    ) -> Result<(), QuickLendXError> {
        verification::update_investor_analytics(&env, &investor, amount, is_success)
    }

    /// Get investor analytics
    pub fn get_investor_analytics(
        env: Env,
        investor: Address,
    ) -> Option<analytics::InvestorAnalytics> {
        analytics::AnalyticsStorage::get_investor_analytics(&env, &investor)
    }

    /// Get investors by tier
    pub fn get_investors_by_tier(env: Env, tier: InvestorTier) -> Vec<Address> {
        InvestorVerificationStorage::get_investors_by_tier(&env, tier)
    }

    /// Get investors by risk level
    pub fn get_investors_by_risk_level(env: Env, risk_level: InvestorRiskLevel) -> Vec<Address> {
        InvestorVerificationStorage::get_investors_by_risk_level(&env, risk_level)
    }

    /// Calculate investor risk score
    pub fn calculate_investor_risk_score(
        env: Env,
        investor: Address,
        kyc_data: String,
    ) -> Result<u32, QuickLendXError> {
        // This function is already defined in verification module
        calculate_investor_risk_score(&env, &investor, &kyc_data)
    }

    /// Determine investor tier
    pub fn compute_investor_tier(
        env: Env,
        investor: Address,
        risk_score: u32,
    ) -> Result<InvestorTier, QuickLendXError> {
        determine_investor_tier(&env, &investor, risk_score)
    }

    /// Calculate investment limit for investor
    pub fn calculate_investment_limit(
        _env: Env,
        tier: InvestorTier,
        risk_level: InvestorRiskLevel,
        base_limit: i128,
    ) -> i128 {
        // This function is already defined in verification module
        calculate_investment_limit(&tier, &risk_level, base_limit)
    }

    /// Validate investor investment
    pub fn validate_investor_investment(
        env: Env,
        investor: Address,
        investment_amount: i128,
    ) -> Result<(), QuickLendXError> {
        // This function is already defined in verification module
        validate_investor_investment(&env, &investor, investment_amount)
    }

    /// Check if investor is verified
    pub fn is_investor_verified(env: Env, investor: Address) -> bool {
        InvestorVerificationStorage::is_investor_verified(&env, &investor)
    }

    /// Get escrow details for an invoice
    pub fn get_escrow_details(
        env: Env,
        invoice_id: BytesN<32>,
    ) -> Result<payments::Escrow, QuickLendXError> {
        EscrowStorage::get_escrow_by_invoice(&env, &invoice_id)
            .ok_or(QuickLendXError::StorageKeyNotFound)
    }

    /// Get escrow status for an invoice
    pub fn get_escrow_status(
        env: Env,
        invoice_id: BytesN<32>,
    ) -> Result<payments::EscrowStatus, QuickLendXError> {
        let escrow = EscrowStorage::get_escrow_by_invoice(&env, &invoice_id)
            .ok_or(QuickLendXError::StorageKeyNotFound)?;
        Ok(escrow.status)
    }

    /// Admin-only: Get escrow record by escrow ID for support and inspection.
    ///
    /// Returns the full escrow record including all fields (id, invoice_id, investor,
    /// business, amount, currency, created_at, status). This is a read-only operation
    /// intended for support teams to inspect escrow state without requiring invoice_id.
    ///
    /// # Arguments
    /// * `env` - The contract environment
    /// * `admin` - The admin address (must be authenticated and authorized)
    /// * `escrow_id` - The escrow ID to inspect
    ///
    /// # Returns
    /// * `Ok(Escrow)` - The full escrow record
    /// * `Err(QuickLendXError::NotAdmin)` - Caller is not the current admin
    /// * `Err(QuickLendXError::StorageKeyNotFound)` - No escrow record exists for this escrow_id
    ///
    /// # Security
    /// - Requires admin authorization
    /// - Read-only (no state mutations)
    /// - Safe for use in monitoring and support tooling
    pub fn admin_get_escrow(
        env: Env,
        admin: Address,
        escrow_id: BytesN<32>,
    ) -> Result<payments::Escrow, QuickLendXError> {
        AdminStorage::require_admin_auth(&env, &admin)?;
        EscrowStorage::get_escrow(&env, &escrow_id).ok_or(QuickLendXError::StorageKeyNotFound)
    }

    /// Approve an early escrow release before normal settlement finalization.
    ///
    /// The invoice business and accepted investor must both approve before
    /// `execute_early_escrow_release` can release held escrow funds.
    pub fn approve_early_escrow_release(
        env: Env,
        invoice_id: BytesN<32>,
        approver: Address,
    ) -> Result<(), QuickLendXError> {
        pause::PauseControl::require_not_paused(&env)?;
        approver.require_auth();

        let invoice = InvoiceStorage::get_invoice(&env, &invoice_id)
            .ok_or(QuickLendXError::InvoiceNotFound)?;
        if invoice.status != InvoiceStatus::Funded {
            return Err(QuickLendXError::InvalidStatus);
        }

        let investor = invoice.investor.clone().ok_or(QuickLendXError::InvoiceNotFunded)?;
        if approver != invoice.business && approver != investor {
            return Err(QuickLendXError::Unauthorized);
        }

        let escrow = EscrowStorage::get_escrow_by_invoice(&env, &invoice_id)
            .ok_or(QuickLendXError::StorageKeyNotFound)?;
        if escrow.status != payments::EscrowStatus::Held {
            return Err(QuickLendXError::InvalidStatus);
        }

        env.storage()
            .persistent()
            .set(&early_release_approval_key(&invoice_id, &approver), &true);
        Ok(())
    }

    /// Revoke the caller's early escrow release approval while escrow is still held.
    pub fn revoke_early_escrow_release(
        env: Env,
        invoice_id: BytesN<32>,
        approver: Address,
    ) -> Result<(), QuickLendXError> {
        pause::PauseControl::require_not_paused(&env)?;
        approver.require_auth();

        let invoice = InvoiceStorage::get_invoice(&env, &invoice_id)
            .ok_or(QuickLendXError::InvoiceNotFound)?;
        if invoice.status != InvoiceStatus::Funded {
            return Err(QuickLendXError::InvalidStatus);
        }

        let investor = invoice.investor.clone().ok_or(QuickLendXError::InvoiceNotFunded)?;
        if approver != invoice.business && approver != investor {
            return Err(QuickLendXError::Unauthorized);
        }

        let escrow = EscrowStorage::get_escrow_by_invoice(&env, &invoice_id)
            .ok_or(QuickLendXError::StorageKeyNotFound)?;
        if escrow.status != payments::EscrowStatus::Held {
            return Err(QuickLendXError::InvalidStatus);
        }

        env.storage()
            .persistent()
            .set(&early_release_approval_key(&invoice_id, &approver), &false);
        Ok(())
    }

    /// Execute early escrow release after both the business and investor approve.
    pub fn execute_early_escrow_release(
        env: Env,
        invoice_id: BytesN<32>,
    ) -> Result<(), QuickLendXError> {
        pause::PauseControl::require_not_paused(&env)?;
        reentrancy::with_payment_guard(&env, || {
            let invoice = InvoiceStorage::get_invoice(&env, &invoice_id)
                .ok_or(QuickLendXError::InvoiceNotFound)?;
            if invoice.status != InvoiceStatus::Funded {
                return Err(QuickLendXError::InvalidStatus);
            }
            let investor = invoice.investor.clone().ok_or(QuickLendXError::InvoiceNotFunded)?;
            if !has_early_release_approval(&env, &invoice_id, &invoice.business)
                || !has_early_release_approval(&env, &invoice_id, &investor)
            {
                return Err(QuickLendXError::OperationNotAllowed);
            }

            let escrow = EscrowStorage::get_escrow_by_invoice(&env, &invoice_id)
                .ok_or(QuickLendXError::StorageKeyNotFound)?;
            release_escrow(&env, &invoice_id)?;
            emit_escrow_released(
                &env,
                &escrow.escrow_id,
                &invoice_id,
                &escrow.business,
                escrow.amount,
            );
            Ok(())
        })
    }

    /// Release escrow funds to business upon invoice verification
    pub fn release_escrow_funds(env: Env, invoice_id: BytesN<32>) -> Result<(), QuickLendXError> {
        pause::PauseControl::require_not_paused(&env)?;
        reentrancy::with_payment_guard(&env, || {
            let invoice = InvoiceStorage::get_invoice(&env, &invoice_id)
                .ok_or(QuickLendXError::InvoiceNotFound)?;

            // Strictly enforce that escrow can only be released for Funded invoices.
            // This prevents premature release even if an escrow object exists (e.g. from tests).
            if invoice.status != InvoiceStatus::Funded {
                return Err(QuickLendXError::InvalidStatus);
            }

            let escrow = EscrowStorage::get_escrow_by_invoice(&env, &invoice_id).unwrap();

            release_escrow(&env, &invoice_id)?;

            emit_escrow_released(
                &env,
                &escrow.escrow_id,
                &invoice_id,
                &escrow.business,
                escrow.amount,
            );

            Ok(())
        })
    }

    /// Refund escrow funds to investor if verification fails or as an explicit manual refund.
    ///
    /// Can be triggered by Admin or Business owner. Invoice must be Funded.
    /// Protected by payment reentrancy guard.
    pub fn refund_escrow_funds(
        env: Env,
        invoice_id: BytesN<32>,
        caller: Address,
    ) -> Result<(), QuickLendXError> {
        pause::PauseControl::require_not_paused(&env)?;
        reentrancy::with_payment_guard(&env, || do_refund_escrow_funds(&env, &invoice_id, &caller))
    }

    /// Withdraw an active investment, refunding escrowed funds to the investor.
    ///
    /// Only the investor may call this. The investment must be in `Active` status
    /// and the associated escrow must still be `Held` (funds not yet released to
    /// the business). On success the investment transitions `Active → Withdrawn`,
    /// the invoice is restored to a fundable state, and the accepted bid is cancelled.
    ///
    /// Protected by payment reentrancy guard (see docs/contracts/security.md).
    ///
    /// # Returns
    /// * `Ok(())` on successful withdrawal
    ///
    /// # Errors
    /// * `Unauthorized` — caller is not the investment's investor
    /// * `InvalidStatus` — investment is not Active, or escrow is not Held
    /// * `InvoiceNotFound`, `StorageKeyNotFound`
    /// * `ContractPaused` if the protocol is paused
    /// * `OperationNotAllowed` if reentrancy is detected
    ///
    /// Pause-gated: rejects with `ContractPaused` when the emergency circuit
    /// breaker is engaged, before any funds move.
    pub fn withdraw_investment(
        env: Env,
        invoice_id: BytesN<32>,
        investor: Address,
    ) -> Result<(), QuickLendXError> {
        pause::PauseControl::require_not_paused(&env)?;
        reentrancy::with_payment_guard(&env, || {
            do_withdraw_investment(&env, &invoice_id, &investor)
        })
    }

    /// Check for overdue invoices and send notifications (admin or automated process)
    ///
    /// @notice Scans a bounded funded-invoice window for overdue/default handling.
    /// @dev This entry point uses the default rotating batch limit to keep per-call work bounded.
    ///      Repeated invocations eventually cover the full funded set as the stored cursor advances.
    /// @param env The contract environment.
    /// @return Number of overdue funded invoices found within the scanned window.
    pub fn check_overdue_invoices(env: Env) -> Result<u32, QuickLendXError> {
        let grace_period = defaults::resolve_grace_period(&env, None)?;
        Self::check_overdue_invoices_grace(env, grace_period)
    }

    /// Check for overdue invoices with a custom grace period (in seconds)
    ///
    /// @notice Scans a bounded funded-invoice window using a caller-supplied grace period.
    /// @dev The scan size is capped by protocol constants to keep execution deterministic.
    /// @param env The contract environment.
    /// @param grace_period Grace period in seconds applied to each funded invoice in the window.
    /// @return Number of overdue funded invoices found within the scanned window.
    pub fn check_overdue_invoices_grace(
        env: Env,
        grace_period: u64,
    ) -> Result<u32, QuickLendXError> {
        Ok(defaults::scan_funded_invoice_expirations(&env, grace_period, None)?.overdue_count)
    }

    /// Legacy compatibility wrapper for overdue processing.
    pub fn handle_overdue_invoices(env: Env, grace_period: u32) -> Result<u32, QuickLendXError> {
        Self::check_overdue_invoices_grace(env, grace_period as u64)
    }

    /// @notice Returns the current funded-invoice overdue scan cursor.
    /// @param env The contract environment.
    /// @return Zero-based index of the next funded invoice to inspect.
    pub fn get_overdue_scan_cursor(env: Env) -> u32 {
        defaults::get_overdue_scan_cursor(&env)
    }

    /// @notice Returns the default funded-invoice overdue scan batch size.
    /// @return Default number of funded invoices processed by `check_overdue_invoices*`.
    pub fn get_overdue_scan_batch_limit(_env: Env) -> u32 {
        defaults::default_overdue_scan_batch_limit()
    }

    /// @notice Returns the maximum funded-invoice overdue scan batch size.
    /// @return Hard upper bound accepted by `scan_overdue_invoices`.
    pub fn get_overdue_scan_batch_limit_max(_env: Env) -> u32 {
        defaults::max_overdue_scan_batch_limit()
    }

    /// @notice Returns the suggested default page size for settlement/payment record queries.
    /// @dev This is a soft hint for off-chain indexers. Actual query limits are enforced by
    ///      the contract's MAX_QUERY_LIMIT. Indexers should use this value as a starting point
    ///      for pagination to balance efficiency and memory usage.
    /// @return Default settlement batch size (25) — recommended number of payment records per page.
    pub fn get_settlement_batch_soft_cap(_env: Env) -> u32 {
        settlement::default_settlement_batch_size_soft_cap()
    }

    /// @notice Returns the maximum page size for settlement/payment record queries.
    /// @dev This represents the hard upper bound enforced by the contract. Query requests
    ///      exceeding this limit will be automatically clamped to this value by `get_payment_records`.
    /// @return Maximum settlement batch size (50) — hard cap for payment records per query.
    pub fn get_settlement_batch_max_cap(_env: Env) -> u32 {
        settlement::max_settlement_batch_size_soft_cap()
    }

    /// Check whether a specific invoice has expired and trigger default handling when necessary
    pub fn check_invoice_expiration(
        env: Env,
        invoice_id: BytesN<32>,
        grace_period: Option<u64>,
    ) -> Result<bool, QuickLendXError> {
        pause::PauseControl::require_not_paused(&env)?;
        let invoice = InvoiceStorage::get_invoice(&env, &invoice_id)
            .ok_or(QuickLendXError::InvoiceNotFound)?;
        let grace = defaults::resolve_grace_period(&env, grace_period)?;
        invoice.check_and_handle_expiration(&env, grace)
    }

    // Category and Tag Management Functions

    // Get invoices by category
    /*
        pub fn get_invoices_by_category(
            env: Env,
            category: InvoiceCategory,
        ) -> Vec<BytesN<32>> {
            InvoiceStorage::get_invoices_by_category(&env, &category)
        }
    */

    /*
        /// Get invoices by category and status
        pub fn get_invoices_by_cat_status(
            env: Env,
            category: InvoiceCategory,
            status: InvoiceStatus,
        ) -> Vec<BytesN<32>> {
            InvoiceStorage::get_invoices_by_category_and_status(&env, category, status)
        }
    */

    /// Get invoices by tag
    pub fn get_invoices_by_tag(env: Env, tag: String) -> Vec<BytesN<32>> {
        InvoiceStorage::get_invoices_by_tag(&env, &tag)
    }

    /// Get invoices by multiple tags (AND logic)
    pub fn get_invoices_by_tags(env: Env, tags: Vec<String>) -> Vec<BytesN<32>> {
        InvoiceStorage::get_invoices_by_tags(&env, &tags)
    }

    /// Get invoice count by category
    pub fn get_invoice_count_by_category(env: Env, category: InvoiceCategory) -> u32 {
        InvoiceStorage::get_invoice_count_by_category(&env, &category)
    }

    /// Get invoice count by tag
    pub fn get_invoice_count_by_tag(env: Env, tag: String) -> u32 {
        InvoiceStorage::get_invoice_count_by_tag(&env, &tag)
    }

    /// Update invoice category (business owner only)
    pub fn update_invoice_category(
        env: Env,
        invoice_id: BytesN<32>,
        new_category: InvoiceCategory,
    ) -> Result<(), QuickLendXError> {
        pause::PauseControl::require_not_paused(&env)?;
        let mut invoice = InvoiceStorage::get_invoice(&env, &invoice_id)
            .ok_or(QuickLendXError::InvoiceNotFound)?;

        require_no_active_freeze(&env, &invoice_id)?;

        // Only the business owner can update the category
        invoice.business.require_auth();
        require_business_active(&env, &invoice.business)?;

        let old_category = invoice.category;
        invoice.update_category(new_category);

        // Validate the new category
        verification::validate_invoice_category(&new_category)?;

        // Update the invoice
        InvoiceStorage::update_invoice(&env, &invoice);

        // Emit event
        events::emit_invoice_category_updated(
            &env,
            &invoice_id,
            &invoice.business,
            &old_category,
            &new_category,
        );

        // Update indexes
        InvoiceStorage::remove_category_index(&env, &old_category, &invoice_id);
        InvoiceStorage::add_category_index(&env, &new_category, &invoice_id);

        Ok(())
    }

    /// Add tag to invoice (business owner only)
    pub fn add_invoice_tag(
        env: Env,
        invoice_id: BytesN<32>,
        tag: String,
    ) -> Result<(), QuickLendXError> {
        pause::PauseControl::require_not_paused(&env)?;
        let mut invoice = InvoiceStorage::get_invoice(&env, &invoice_id)
            .ok_or(QuickLendXError::InvoiceNotFound)?;

        require_no_active_freeze(&env, &invoice_id)?;

        // Authorization: Ensure the stored business owner authorizes the change
        invoice.business.require_auth();
        require_business_active(&env, &invoice.business)?;

        // Tag Normalization: Synchronize with protocol requirements
        let normalized_tag = normalize_tag(&env, &tag)?;
        invoice.add_tag(&env, normalized_tag.clone())?;

        // Update the invoice
        InvoiceStorage::update_invoice(&env, &invoice);

        // Emit event with normalized data
        events::emit_invoice_tag_added(&env, &invoice_id, &invoice.business, &normalized_tag);

        // Update index with normalized form
        InvoiceStorage::add_tag_index(&env, &normalized_tag, &invoice_id);

        Ok(())
    }

    /// Remove tag from invoice (business owner only)
    pub fn remove_invoice_tag(
        env: Env,
        invoice_id: BytesN<32>,
        tag: String,
    ) -> Result<(), QuickLendXError> {
        pause::PauseControl::require_not_paused(&env)?;
        let mut invoice = InvoiceStorage::get_invoice(&env, &invoice_id)
            .ok_or(QuickLendXError::InvoiceNotFound)?;

        require_no_active_freeze(&env, &invoice_id)?;

        // Authorization: Ensure the stored business owner authorizes the removal
        invoice.business.require_auth();
        require_business_active(&env, &invoice.business)?;

        // Normalize tag for removal lookup
        let normalized_tag = normalize_tag(&env, &tag)?;
        invoice.remove_tag(normalized_tag.clone())?;

        // Update the invoice
        InvoiceStorage::update_invoice(&env, &invoice);

        // Emit event with normalized data
        events::emit_invoice_tag_removed(&env, &invoice_id, &invoice.business, &normalized_tag);

        // Update index using normalized form
        InvoiceStorage::remove_tag_index(&env, &normalized_tag, &invoice_id);

        Ok(())
    }

    /// Get all tags for an invoice
    pub fn get_invoice_tags(
        env: Env,
        invoice_id: BytesN<32>,
    ) -> Result<Vec<String>, QuickLendXError> {
        let invoice = InvoiceStorage::get_invoice(&env, &invoice_id)
            .ok_or(QuickLendXError::InvoiceNotFound)?;
        Ok(invoice.get_tags())
    }

    /// Check if invoice has a specific tag
    pub fn invoice_has_tag(
        env: Env,
        invoice_id: BytesN<32>,
        tag: String,
    ) -> Result<bool, QuickLendXError> {
        let invoice = InvoiceStorage::get_invoice(&env, &invoice_id)
            .ok_or(QuickLendXError::InvoiceNotFound)?;
        Ok(invoice.has_tag(tag))
    }

    // ========================================
    // Fee and Revenue Management Functions
    // ========================================

    /// Initialize fee management system
    pub fn initialize_fee_system(env: Env, admin: Address) -> Result<(), QuickLendXError> {
        fees::FeeManager::initialize(&env, &admin)
    }

    /// Configure treasury address for platform fee routing (admin only)
    pub fn configure_treasury(env: Env, treasury_address: Address) -> Result<(), QuickLendXError> {
        let admin =
            BusinessVerificationStorage::get_admin(&env).ok_or(QuickLendXError::NotAdmin)?;

        let _treasury_config =
            fees::FeeManager::configure_treasury(&env, &admin, treasury_address.clone())?;

        // Emit event
        events::emit_treasury_configured(&env, &treasury_address, &admin);

        Ok(())
    }

    /// Update platform fee basis points (admin only)
    pub fn update_platform_fee_bps(env: Env, new_fee_bps: u32) -> Result<(), QuickLendXError> {
        let admin =
            BusinessVerificationStorage::get_admin(&env).ok_or(QuickLendXError::NotAdmin)?;

        let old_config = fees::FeeManager::get_platform_fee_config(&env)?;
        let old_fee_bps = old_config.fee_bps;

        let _new_config = fees::FeeManager::update_platform_fee(&env, &admin, new_fee_bps)?;

        // Emit event
        events::emit_platform_fee_config_updated(&env, old_fee_bps, new_fee_bps, &admin);

        Ok(())
    }

    /// Get current platform fee configuration
    pub fn get_platform_fee_config(env: Env) -> Result<fees::PlatformFeeConfig, QuickLendXError> {
        fees::FeeManager::get_platform_fee_config(&env)
    }

    /// Get treasury address if configured
    pub fn get_treasury_address(env: Env) -> Option<Address> {
        fees::FeeManager::get_treasury_address(&env)
    }

    /// Update fee structure for a specific fee type
    pub fn update_fee_structure(
        env: Env,
        admin: Address,
        fee_type: fees::FeeType,
        base_fee_bps: u32,
        min_fee: i128,
        max_fee: i128,
        is_active: bool,
    ) -> Result<fees::FeeStructure, QuickLendXError> {
        fees::FeeManager::update_fee_structure(
            &env,
            &admin,
            fee_type,
            base_fee_bps,
            min_fee,
            max_fee,
            is_active,
        )
    }

    /// Get fee structure for a fee type
    pub fn get_fee_structure(
        env: Env,
        fee_type: fees::FeeType,
    ) -> Result<fees::FeeStructure, QuickLendXError> {
        fees::FeeManager::get_fee_structure(&env, &fee_type)
    }

    /// Calculate total fees for a transaction
    pub fn calculate_transaction_fees(
        env: Env,
        user: Address,
        transaction_amount: i128,
        is_early_payment: bool,
        is_late_payment: bool,
        late_payment_penalty_bps: Option<u32>,
    ) -> Result<i128, QuickLendXError> {
        fees::FeeManager::calculate_total_fees(
            &env,
            &user,
            transaction_amount,
            is_early_payment,
            is_late_payment,
            late_payment_penalty_bps,
        )
    }

    /// Get user volume data and tier
    pub fn get_user_volume_data(env: Env, user: Address) -> fees::UserVolumeData {
        fees::FeeManager::get_user_volume(&env, &user)
    }

    /// Update user volume (called internally after transactions)
    pub fn update_user_transaction_volume(
        env: Env,
        user: Address,
        transaction_amount: i128,
    ) -> Result<fees::UserVolumeData, QuickLendXError> {
        fees::FeeManager::update_user_volume(&env, &user, transaction_amount)
    }

    /// Configure revenue distribution
    pub fn configure_revenue_distribution(
        env: Env,
        admin: Address,
        treasury_address: Address,
        treasury_share_bps: u32,
        developer_share_bps: u32,
        platform_share_bps: u32,
        auto_distribution: bool,
        min_distribution_amount: i128,
    ) -> Result<(), QuickLendXError> {
        // Verify admin
        let stored_admin =
            BusinessVerificationStorage::get_admin(&env).ok_or(QuickLendXError::NotAdmin)?;
        if admin != stored_admin {
            return Err(QuickLendXError::NotAdmin);
        }

        let config = fees::RevenueConfig {
            treasury_address,
            treasury_share_bps,
            developer_share_bps,
            platform_share_bps,
            auto_distribution,
            min_distribution_amount,
        };
        fees::FeeManager::configure_revenue_distribution(&env, &admin, config)
    }

    /// Get current revenue split configuration
    pub fn get_revenue_split_config(env: Env) -> Result<fees::RevenueConfig, QuickLendXError> {
        fees::FeeManager::get_revenue_split_config(&env)
    }

    /// Distribute revenue for a period
    pub fn distribute_revenue(
        env: Env,
        admin: Address,
        period: u64,
    ) -> Result<(i128, i128, i128), QuickLendXError> {
        fees::FeeManager::distribute_revenue(&env, &admin, period)
    }

    /// Get fee analytics for a period
    pub fn get_fee_analytics(env: Env, period: u64) -> Result<fees::FeeAnalytics, QuickLendXError> {
        fees::FeeManager::get_analytics(&env, period)
    }

    /// Collect fees (internal function called after fee calculation)
    pub fn collect_transaction_fees(
        env: Env,
        user: Address,
        fees_by_type: Map<fees::FeeType, i128>,
        total_amount: i128,
    ) -> Result<(), QuickLendXError> {
        fees::FeeManager::collect_fees(&env, &user, fees_by_type, total_amount)
    }

    /// Validate fee parameters
    pub fn validate_fee_parameters(
        _env: Env,
        base_fee_bps: u32,
        min_fee: i128,
        max_fee: i128,
    ) -> Result<(), QuickLendXError> {
        fees::FeeManager::validate_fee_params(base_fee_bps, min_fee, max_fee)
    }

    // ========================================
    // Query Functions for Frontend Integration
    // ========================================

    /// Get invoices by business with optional status filter and pagination
    /// @notice Get business invoices with pagination and optional status filtering
    /// @param business The business address to query invoices for
    /// @param status_filter Optional status filter (None returns all statuses)
    /// @param offset Starting index for pagination (0-based)
    /// @param limit Maximum number of results to return (capped at MAX_QUERY_LIMIT)
    /// @return Vector of invoice IDs matching the criteria
    /// @dev Enforces MAX_QUERY_LIMIT hard cap for security and performance.
    ///      Results are sorted by `created_at` descending (newest first).
    pub fn get_business_invoices_paged(
        env: Env,
        business: Address,
        status_filter: Option<InvoiceStatus>,
        offset: u32,
        limit: u32,
    ) -> PaginatedBytes32Vec {
        // Validate query parameters for security
        if validate_query_params(offset, limit).is_err() {
            // Return empty result on validation failure
            return PaginatedBytes32Vec {
                items: Vec::new(&env),
                total_count: 0,
                has_more: false,
            };
        }

        let all_invoices = InvoiceStorage::get_business_invoices(&env, &business);

        // Collect (created_at, invoice_id) pairs for sorting.
        let mut pairs: alloc::vec::Vec<(u64, BytesN<32>)> = alloc::vec::Vec::new();
        for invoice_id in all_invoices.iter() {
            if let Some(invoice) = InvoiceStorage::get_invoice(&env, &invoice_id) {
                let include = match &status_filter {
                    Some(status) => invoice.status == *status,
                    None => true,
                };
                if include {
                    pairs.push((invoice.created_at, invoice_id));
                }
            }
        }

        let total_count = pairs.len() as u32;

        // Sort descending by created_at (newest first).
        pairs.sort_by_key(|b| core::cmp::Reverse(b.0));

        // Apply pagination (overflow-safe) and collect into Soroban Vec.
        let len_u32 = pairs.len() as u32;
        let start = offset.min(len_u32) as usize;
        let capped_limit = cap_query_limit(limit);
        let end = (offset.saturating_add(capped_limit).min(len_u32)) as usize;
        let mut result = Vec::new(&env);
        for (_, id) in &pairs[start..end] {
            result.push_back(id.clone());
        }

        let (_, has_more) = pagination::pagination_metadata(offset, limit, total_count);
        PaginatedBytes32Vec {
            items: result,
            total_count,
            has_more,
        }
    }

    /// Get investments by investor with optional status filter and pagination
    /// Retrieves paginated investments for a specific investor with enhanced boundary checking.
    ///
    /// This function provides overflow-safe pagination with comprehensive boundary validation
    /// to prevent arithmetic overflow and ensure consistent behavior across all edge cases.
    ///
    /// # Arguments
    /// * `env` - Soroban environment
    /// * `investor` - Address of the investor to query
    /// * `status_filter` - Optional filter by investment status
    /// * `offset` - Starting position (0-based, will be capped to available data)
    /// * `limit` - Maximum records to return (capped to MAX_QUERY_LIMIT)
    ///
    /// # Returns
    /// * Vector of investment IDs matching the criteria
    ///
    /// # Security Notes
    /// - Uses saturating arithmetic throughout to prevent overflow attacks
    /// - Validates all array bounds before access
    /// - Caps query limit to prevent DoS via large requests
    /// - Handles edge cases like offset >= total_count gracefully
    ///
    /// # Examples
    /// ```ignore
    /// // Get first 10 active investments
    /// let investments = contract.get_investor_investments_paged(
    ///     env, investor, Some(InvestmentStatus::Active), 0, 10
    /// );
    ///
    /// // Get next page with offset
    /// let next_page = contract.get_investor_investments_paged(
    ///     env, investor, Some(InvestmentStatus::Active), 10, 10
    /// );
    /// ```
    pub fn get_investor_investments_paged(
        env: Env,
        investor: Address,
        status_filter: Option<InvestmentStatus>,
        offset: u32,
        limit: u32,
    ) -> PaginatedBytes32Vec {
        investment_queries::InvestmentQueries::get_investor_investments_paginated(
            &env,
            &investor,
            status_filter,
            offset,
            limit,
        )
    }

    /// Get available invoices with pagination and optional filters
    /// @notice Get available invoices with pagination and optional filters
    /// @param min_amount Optional minimum invoice amount filter
    /// @param max_amount Optional maximum invoice amount filter
    /// @param category_filter Optional category filter
    /// @param offset Starting index for pagination (0-based)
    /// @param limit Maximum number of results to return (capped at MAX_QUERY_LIMIT)
    /// @return Vector of verified invoice IDs matching the criteria
    /// @dev Enforces MAX_QUERY_LIMIT hard cap for security and performance
    pub fn get_available_invoices_paged(
        env: Env,
        min_amount: Option<i128>,
        max_amount: Option<i128>,
        category_filter: Option<InvoiceCategory>,
        offset: u32,
        limit: u32,
    ) -> PaginatedBytes32Vec {
        // Validate query parameters for security
        if validate_query_params(offset, limit).is_err() {
            return PaginatedBytes32Vec {
                items: Vec::new(&env),
                total_count: 0,
                has_more: false,
            };
        }

        let verified_invoices =
            InvoiceStorage::get_invoices_by_status(&env, InvoiceStatus::Verified);
        let mut filtered = Vec::new(&env);

        for invoice_id in verified_invoices.iter() {
            if let Some(invoice) = InvoiceStorage::get_invoice(&env, &invoice_id) {
                // Filter by amount range
                if let Some(min) = min_amount {
                    if invoice.amount < min {
                        continue;
                    }
                }
                if let Some(max) = max_amount {
                    if invoice.amount > max {
                        continue;
                    }
                }
                // Filter by category
                if let Some(category) = &category_filter {
                    if invoice.category != *category {
                        continue;
                    }
                }
                filtered.push_back(invoice_id);
            }
        }

        let total_count = filtered.len();

        // Apply pagination (overflow-safe)
        let mut result = Vec::new(&env);
        let (start, end) = pagination::calculate_safe_bounds(offset, limit, total_count);
        let mut idx = start;
        while idx < end {
            if let Some(invoice_id) = filtered.get(idx) {
                result.push_back(invoice_id);
            }
            idx += 1;
        }

        let (_, has_more) = pagination::pagination_metadata(offset, limit, total_count);
        PaginatedBytes32Vec {
            items: result,
            total_count,
            has_more,
        }
    }

    /// Get bid history for an invoice with pagination
    /// @notice Get bid history for an invoice with pagination and optional status filtering
    /// @param invoice_id The invoice ID to query bids for
    /// @param status_filter Optional status filter (None returns all statuses)
    /// @param offset Starting index for pagination (0-based)
    /// @param limit Maximum number of results to return (capped at MAX_QUERY_LIMIT)
    /// @return Vector of bids matching the criteria
    /// @dev Enforces MAX_QUERY_LIMIT hard cap for security and performance
    pub fn get_bid_history_paged(
        env: Env,
        invoice_id: BytesN<32>,
        status_filter: Option<BidStatus>,
        offset: u32,
        limit: u32,
    ) -> PaginatedBids {
        // Validate query parameters for security
        if validate_query_params(offset, limit).is_err() {
            return PaginatedBids {
                items: Vec::new(&env),
                total_count: 0,
                has_more: false,
            };
        }

        let all_bids = BidStorage::get_bid_records_for_invoice(&env, &invoice_id);
        let mut filtered = Vec::new(&env);

        for bid in all_bids.iter() {
            if let Some(status) = &status_filter {
                if bid.status == *status {
                    filtered.push_back(bid);
                }
            } else {
                filtered.push_back(bid);
            }
        }

        let total_count = filtered.len();

        // Apply pagination (overflow-safe)
        let mut result = Vec::new(&env);
        let (start, end) = pagination::calculate_safe_bounds(offset, limit, total_count);
        let mut idx = start;
        while idx < end {
            if let Some(bid) = filtered.get(idx) {
                result.push_back(bid);
            }
            idx += 1;
        }

        let (_, has_more) = pagination::pagination_metadata(offset, limit, total_count);
        PaginatedBids {
            items: result,
            total_count,
            has_more,
        }
    }

    /// Get bid history for an investor with pagination
    /// @notice Get bid history for an investor with pagination and optional status filtering
    /// @param investor The investor address to query bids for
    /// @param status_filter Optional status filter (None returns all statuses)
    /// @param offset Starting index for pagination (0-based)
    /// @param limit Maximum number of results to return (capped at MAX_QUERY_LIMIT)
    /// @return Vector of bids matching the criteria
    /// @dev Enforces MAX_QUERY_LIMIT hard cap for security and performance
    pub fn get_investor_bids_paged(
        env: Env,
        investor: Address,
        status_filter: Option<BidStatus>,
        offset: u32,
        limit: u32,
    ) -> PaginatedBids {
        // Validate query parameters for security
        if validate_query_params(offset, limit).is_err() {
            return PaginatedBids {
                items: Vec::new(&env),
                total_count: 0,
                has_more: false,
            };
        }

        let all_bid_ids = BidStorage::get_bids_by_investor_all(&env, &investor);
        let mut filtered = Vec::new(&env);

        for bid_id in all_bid_ids.iter() {
            if let Some(bid) = BidStorage::get_bid(&env, &bid_id) {
                if let Some(status) = &status_filter {
                    if bid.status == *status {
                        filtered.push_back(bid);
                    }
                } else {
                    filtered.push_back(bid);
                }
            }
        }

        let total_count = filtered.len();

        // Apply pagination (overflow-safe)
        let mut result = Vec::new(&env);
        let (start, end) = pagination::calculate_safe_bounds(offset, limit, total_count);
        let mut idx = start;
        while idx < end {
            if let Some(bid) = filtered.get(idx) {
                result.push_back(bid);
            }
            idx += 1;
        }

        let (_, has_more) = pagination::pagination_metadata(offset, limit, total_count);
        PaginatedBids {
            items: result,
            total_count,
            has_more,
        }
    }

    /// Get investments by investor (simple version without pagination for backward compatibility)
    pub fn get_investments_by_investor(env: Env, investor: Address) -> Vec<BytesN<32>> {
        InvestmentStorage::get_investments_by_investor(&env, &investor)
    }

    /// Return an aggregate portfolio snapshot for `investor` in a single
    /// bounded read.
    ///
    /// Delegates to [`investment_queries::InvestmentQueries::investor_portfolio_summary`].
    /// No auth is required because every individual investment record is
    /// already publicly queryable.
    pub fn get_investor_portfolio_summary(
        env: Env,
        investor: Address,
    ) -> Result<investment_queries::InvestorPortfolioSummary, QuickLendXError> {
        investment_queries::InvestmentQueries::investor_portfolio_summary(&env, &investor)
    }

    /// Return a canonical best-effort address summary across all supported roles.
    ///
    /// Mirrors [`get_investor_portfolio_summary`] style: no auth required and
    /// returns a stable shape even if an address only has data for a subset of
    /// roles.
    pub fn get_address_summary(
        env: Env,
        addr: Address,
    ) -> Result<address_summary::AddressSummary, QuickLendXError> {
        address_summary::summarize_address(&env, &addr)
    }

    /// Get bid history for an invoice (simple version without pagination)
    pub fn get_bid_history(env: Env, invoice_id: BytesN<32>) -> Vec<Bid> {
        BidStorage::get_bid_records_for_invoice(&env, &invoice_id)
    }

    // =========================================================================
    // Backup
    // =========================================================================

    /// Create a backup of all invoice data (admin only).
    pub fn create_backup(env: Env, admin: Address) -> Result<BytesN<32>, QuickLendXError> {
        pause::PauseControl::require_not_paused(&env)?;
        AdminStorage::require_admin(&env, &admin)?;
        let backup_id = backup::BackupStorage::generate_backup_id(&env);
        let invoices = backup::BackupStorage::get_all_invoices(&env);
        let b = backup::Backup {
            backup_id: backup_id.clone(),
            timestamp: env.ledger().timestamp(),
            description: String::from_str(&env, "Manual Backup"),
            invoice_count: invoices.len(),
            status: backup::BackupStatus::Active,
            format_version: 2,
        };
        backup::BackupStorage::store_backup(&env, &b, Some(&invoices))?;
        backup::BackupStorage::store_backup_data(&env, &backup_id, &invoices);
        backup::BackupStorage::add_to_backup_list(&env, &backup_id);
        let _ = backup::BackupStorage::cleanup_old_backups(&env);
        Ok(backup_id)
    }

    /// Restore invoice data from a backup (admin only).
    pub fn restore_backup(
        env: Env,
        admin: Address,
        backup_id: BytesN<32>,
    ) -> Result<(), QuickLendXError> {
        pause::PauseControl::require_not_paused(&env)?;
        AdminStorage::require_admin(&env, &admin)?;
        backup::BackupStorage::restore_from_backup(&env, &backup_id)?;
        Ok(())
    }

    /// Archive a backup (admin only).
    pub fn archive_backup(
        env: Env,
        admin: Address,
        backup_id: BytesN<32>,
    ) -> Result<(), QuickLendXError> {
        pause::PauseControl::require_not_paused(&env)?;
        AdminStorage::require_admin(&env, &admin)?;
        let mut b = backup::BackupStorage::get_backup(&env, &backup_id).unwrap();
        b.status = backup::BackupStatus::Archived;
        backup::BackupStorage::update_backup(&env, &b)?;
        backup::BackupStorage::remove_from_backup_list(&env, &backup_id);
        Ok(())
    }

    /// Validate a backup's integrity.
    pub fn validate_backup(env: Env, backup_id: BytesN<32>) -> bool {
        backup::BackupStorage::validate_backup(&env, &backup_id).is_ok()
    }

    /// Get backup details by ID.
    pub fn get_backup_details(env: Env, backup_id: BytesN<32>) -> Option<backup::Backup> {
        backup::BackupStorage::get_backup(&env, &backup_id)
    }

    /// Get list of all active backup IDs.
    pub fn get_backups(env: Env) -> Vec<BytesN<32>> {
        backup::BackupStorage::get_all_backups(&env)
    }

    /// Manually trigger cleanup of old backups (admin only).
    pub fn cleanup_backups(env: Env, admin: Address) -> Result<u32, QuickLendXError> {
        pause::PauseControl::require_not_paused(&env)?;
        AdminStorage::require_admin(&env, &admin)?;
        backup::BackupStorage::cleanup_old_backups(&env)
    }

    /// Preview which backups cleanup_backups would purge without mutating state.
    pub fn preview_cleanup_backups(env: Env) -> backup::BackupCleanupDryRunReport {
        backup::BackupStorage::preview_cleanup_old_backups(&env)
    }

    /// Configure backup retention policy (admin only).
    pub fn set_backup_retention_policy(
        env: Env,
        admin: Address,
        max_backups: u32,
        max_age_seconds: u64,
        auto_cleanup_enabled: bool,
    ) -> Result<(), QuickLendXError> {
        pause::PauseControl::require_not_paused(&env)?;
        AdminStorage::require_admin(&env, &admin)?;
        let policy = backup::BackupRetentionPolicy {
            max_backups,
            max_age_seconds,
            auto_cleanup_enabled,
        };
        backup::BackupStorage::set_retention_policy(&env, &policy);
        Ok(())
    }

    /// Get current backup retention policy.
    pub fn get_backup_retention_policy(env: Env) -> backup::BackupRetentionPolicy {
        backup::BackupStorage::get_retention_policy(&env)
    }

    // ============================================================================
    // Vesting Functions
    // ============================================================================

    /// Create a new vesting schedule funded from `admin`'s token balance.
    ///
    /// # Cliff/slope semantics
    /// Tokens accrue linearly from `start_time` to `end_time`. No tokens are
    /// releasable before `cliff_time = start_time + cliff_seconds`. At the cliff
    /// the full elapsed proportion since `start_time` is immediately claimable;
    /// additional tokens unlock each second until `end_time`, when the complete
    /// `total_amount` is vested.
    ///
    /// # Security
    /// - Requires admin authorization via [`AdminStorage::require_admin`].
    /// - Transfers `total_amount` of `token` from `admin` into contract custody atomically.
    /// - Protected by the payment reentrancy guard because this performs a token transfer.
    pub fn create_vesting_schedule(
        env: Env,
        admin: Address,
        token: Address,
        beneficiary: Address,
        total_amount: i128,
        start_time: u64,
        cliff_seconds: u64,
        end_time: u64,
    ) -> Result<u64, QuickLendXError> {
        pause::PauseControl::require_not_paused(&env)?;
        reentrancy::with_payment_guard(&env, || {
            vesting::Vesting::create_schedule(
                &env,
                &admin,
                token,
                beneficiary,
                total_amount,
                start_time,
                cliff_seconds,
                end_time,
            )
        })
    }

    /// Return the vesting schedule for `id`, or `None` if it does not exist.
    pub fn get_vesting_schedule(env: Env, id: u64) -> Option<vesting::VestingSchedule> {
        vesting::Vesting::get_schedule(&env, id)
    }

    /// Return the total vested amount for schedule `id` at the current ledger timestamp.
    ///
    /// Returns `None` if the schedule does not exist or arithmetic overflows.
    pub fn get_vesting_vested(env: Env, id: u64) -> Option<i128> {
        let schedule = vesting::Vesting::get_schedule(&env, id)?;
        vesting::Vesting::vested_amount(&env, &schedule).ok()
    }

    /// Return the immediately releasable amount for schedule `id`.
    ///
    /// Returns `None` if the schedule does not exist or arithmetic overflows.
    pub fn get_vesting_releasable(env: Env, id: u64) -> Option<i128> {
        let schedule = vesting::Vesting::get_schedule(&env, id)?;
        vesting::Vesting::releasable_amount(&env, &schedule).ok()
    }

    /// Release vested tokens for schedule `id` to the beneficiary.
    ///
    /// # Security
    /// - Requires beneficiary authorization (`beneficiary.require_auth()`).
    /// - Returns `Err(InvalidTimestamp)` if called before `cliff_time`.
    /// - Returns `Ok(0)` (idempotent) when nothing new has vested since the last release.
    /// - Protected by the payment reentrancy guard because this performs a SAC token transfer.
    pub fn release_vested_tokens(
        env: Env,
        beneficiary: Address,
        id: u64,
    ) -> Result<i128, QuickLendXError> {
        pause::PauseControl::require_not_paused(&env)?;
        reentrancy::with_payment_guard(&env, || vesting::Vesting::release(&env, &beneficiary, id))
    }

    /// Distribute accumulated period revenue then vest the developer share on-chain.
    ///
    /// The standard [`distribute_revenue`] entrypoint computes treasury / developer /
    /// platform splits and updates the period accounting record. This wrapper
    /// additionally locks the developer share in a new on-chain vesting schedule,
    /// giving the developer a time-locked claim rather than an immediate credit.
    ///
    /// # Arguments
    /// * `admin`                 - Admin address; must match the stored protocol admin.
    /// * `period`                - Revenue accounting period to distribute.
    /// * `developer`             - Beneficiary address for the developer vesting schedule.
    /// * `token`                 - Token address used for the vesting schedule.
    /// * `vesting_start`         - Unix timestamp when linear vesting begins (must be >= now).
    /// * `vesting_cliff_seconds` - Seconds after `vesting_start` before any tokens unlock.
    /// * `vesting_end`           - Unix timestamp when all developer tokens are fully vested.
    ///
    /// # Returns
    /// `(treasury_amount, schedule_id, platform_amount)` where `schedule_id` is the
    /// newly created developer vesting schedule ID (0 when `developer_amount` is 0).
    ///
    /// # Emits
    /// - `VestingEvent::NewSchedule` via the `(vesting, created)` event topic when a schedule
    ///   is created.
    ///
    /// # Security
    /// Protected by the payment reentrancy guard because vesting schedule creation
    /// transfers `developer_amount` tokens from `admin` into contract custody.
    pub fn distribute_revenue_vested(
        env: Env,
        admin: Address,
        period: u64,
        developer: Address,
        token: Address,
        vesting_start: u64,
        vesting_cliff_seconds: u64,
        vesting_end: u64,
    ) -> Result<(i128, u64, i128), QuickLendXError> {
        pause::PauseControl::require_not_paused(&env)?;
        reentrancy::with_payment_guard(&env, || {
            let (treasury_amount, developer_amount, platform_amount) =
                fees::FeeManager::distribute_revenue(&env, &admin, period)?;

            let schedule_id = if developer_amount > 0 {
                vesting::Vesting::create_schedule(
                    &env,
                    &admin,
                    token,
                    developer,
                    developer_amount,
                    vesting_start,
                    vesting_cliff_seconds,
                    vesting_end,
                )?
            } else {
                0
            };

            Ok((treasury_amount, schedule_id, platform_amount))
        })
    }

    pub fn get_vesting_summary(env: Env, user: Address) -> vesting::VestingSummary {
        vesting::Vesting::get_summary_for_user(&env, &user)
    }

    // ============================================================================
    // Analytics Functions
    // ============================================================================

    /// Get user behavior metrics
    pub fn get_user_behavior_metrics(
        env: Env,
        user: Address,
    ) -> Result<analytics::UserBehaviorMetrics, QuickLendXError> {
        analytics::AnalyticsCalculator::calculate_user_behavior_metrics(&env, &user)
    }

    /// Add a rating to an invoice.
    pub fn add_invoice_rating(
        env: Env,
        invoice_id: BytesN<32>,
        rating: u32,
        feedback: String,
        rater: Address,
    ) -> Result<(), QuickLendXError> {
        pause::PauseControl::require_not_paused(&env)?;
        let mut invoice = InvoiceStorage::get_invoice(&env, &invoice_id)
            .ok_or(QuickLendXError::InvoiceNotFound)?;

        require_no_active_freeze(&env, &invoice_id)?;

        let ts = env.ledger().timestamp();
        invoice.add_rating(rating, feedback, rater, ts)?;
        InvoiceStorage::update_invoice(&env, &invoice);
        Ok(())
    }

    /// Admin-only: override an invoice's computed average rating.
    ///
    /// A one-off manual override for correcting a fraudulent or erroneous
    /// rating discovered off-chain. Every use is recorded in the append-only
    /// audit trail together with the caller-supplied `reason`.
    ///
    /// # Threat model
    /// Without a mandatory, logged reason, an admin could silently rewrite an
    /// invoice's displayed rating — e.g. to bury a legitimate bad-faith
    /// complaint or inflate a business's track record — leaving investors who
    /// rely on that score with no way to detect or attribute the change after
    /// the fact. Requiring a non-empty, length-bounded reason and routing the
    /// mutation through the tamper-evident audit trail (see `audit.rs`) closes
    /// that accountability gap; the reason check happens before the storage
    /// write so an override can never be applied without a corresponding
    /// audit entry.
    ///
    /// # Errors
    /// * `NotAdmin` / `OperationNotAllowed` — caller is not the current admin.
    /// * `InvalidRatingOverrideReason` — `reason` is empty or exceeds
    ///   `protocol_limits::MAX_RATING_OVERRIDE_REASON_LENGTH`.
    /// * `InvoiceNotFound` — `invoice_id` does not exist.
    /// * `InvalidRating` — `new_rating` is not in `1..=5`.
    pub fn rating_override(
        env: Env,
        admin: Address,
        invoice_id: BytesN<32>,
        new_rating: u32,
        reason: String,
    ) -> Result<(), QuickLendXError> {
        AdminStorage::require_admin_auth(&env, &admin)?;

        if reason.is_empty() || reason.len() > protocol_limits::MAX_RATING_OVERRIDE_REASON_LENGTH {
            return Err(QuickLendXError::InvalidRatingOverrideReason);
        }

        require_no_active_freeze(&env, &invoice_id)?;

        let mut invoice = InvoiceStorage::get_invoice(&env, &invoice_id)
            .ok_or(QuickLendXError::InvoiceNotFound)?;

        let old_value = invoice.average_rating.map(|r| fmt_rating(&env, r));

        invoice.override_rating(new_rating)?;
        InvoiceStorage::update_invoice(&env, &invoice);

        audit::log_operation(
            &env,
            invoice_id,
            audit::AuditOperation::RatingOverridden,
            admin,
            old_value,
            Some(fmt_rating(&env, new_rating)),
            None,
            Some(reason),
        );

        Ok(())
    }

    // =========================================================================
    // Analytics (contract-exported)
    // =========================================================================

    pub fn get_platform_metrics(env: Env) -> analytics::PlatformMetrics {
        analytics::AnalyticsStorage::get_platform_metrics(&env).unwrap_or_else(|| {
            analytics::AnalyticsCalculator::calculate_platform_metrics(&env).unwrap_or(
                analytics::PlatformMetrics {
                    total_invoices: 0,
                    total_investments: 0,
                    total_volume: 0,
                    total_fees_collected: 0,
                    active_investors: 0,
                    verified_businesses: 0,
                    average_invoice_amount: 0,
                    average_investment_amount: 0,
                    platform_fee_rate: 0,
                    default_rate: 0,
                    success_rate: 0,
                    timestamp: env.ledger().timestamp(),
                },
            )
        })
    }

    /// Export a versioned, JSON-shaped analytics snapshot for off-chain indexers.
    ///
    /// Schema version `analytics::ANALYTICS_SCHEMA_VERSION` identifies the
    /// stable snapshot shape. The platform and performance metrics are composed
    /// within one read-only host call so indexers receive values from the same
    /// ledger close without storage writes or auth. Internal iteration is bounded
    /// by the existing invoice status indexes and protocol invoice limits used by
    /// the reused analytics calculators.
    ///
    /// Fails with `QuickLendXError::ActiveDisputeExists` while any invoice has
    /// an unresolved dispute, so a snapshot is never published mid-dispute.
    pub fn export_analytics_snapshot(
        env: Env,
    ) -> Result<analytics::AnalyticsSnapshot, QuickLendXError> {
        analytics::AnalyticsCalculator::export_analytics_snapshot(&env)
    }

    /// Return a frozen snapshot of an invoice's ratings for downstream use.
    pub fn ratings_snapshot(
        env: Env,
        invoice_id: BytesN<32>,
    ) -> Result<RatingsSnapshot, QuickLendXError> {
        let invoice = crate::storage::InvoiceStorage::get_invoice(&env, &invoice_id)
            .ok_or(QuickLendXError::InvoiceNotFound)?;

        Ok(RatingsSnapshot {
            schema_version: crate::types::RATINGS_SNAPSHOT_SCHEMA_VERSION,
            invoice_id,
            average_rating: invoice.average_rating,
            total_ratings: invoice.total_ratings,
            highest_rating: invoice.get_highest_rating(),
            lowest_rating: invoice.get_lowest_rating(),
            ledger_sequence: env.ledger().sequence(),
        })
    }

    pub fn get_performance_metrics(env: Env) -> analytics::PerformanceMetrics {
        analytics::AnalyticsStorage::get_performance_metrics(&env).unwrap_or_else(|| {
            analytics::AnalyticsCalculator::calculate_performance_metrics(&env).unwrap_or(
                analytics::PerformanceMetrics {
                    platform_uptime: env.ledger().timestamp(),
                    average_settlement_time: 0,
                    average_verification_time: 0,
                    dispute_resolution_time: 0,
                    system_response_time: 0,
                    transaction_success_rate: 0,
                    error_rate: 0,
                    user_satisfaction_score: 0,
                    platform_efficiency: 0,
                },
            )
        })
    }

    /// Generate a business report for a specific period
    pub fn generate_business_report(
        env: Env,
        business: Address,
        period: analytics::TimePeriod,
    ) -> Result<analytics::BusinessReport, QuickLendXError> {
        let report =
            analytics::AnalyticsCalculator::generate_business_report(&env, &business, period)?;
        analytics::AnalyticsStorage::store_business_report(&env, &report);
        Ok(report)
    }

    /// Retrieve a stored business report by ID
    pub fn get_business_report(
        env: Env,
        report_id: BytesN<32>,
    ) -> Option<analytics::BusinessReport> {
        analytics::AnalyticsStorage::get_business_report(&env, &report_id)
    }

    /// Generate an investor report for a specific period
    pub fn generate_investor_report(
        env: Env,
        investor: Address,
        period: analytics::TimePeriod,
    ) -> Result<analytics::InvestorReport, QuickLendXError> {
        let report =
            analytics::AnalyticsCalculator::generate_investor_report(&env, &investor, period)?;
        Ok(report)
    }

    // =========================================================================
    // Dispute
    // =========================================================================

    pub fn create_dispute(
        env: Env,
        invoice_id: BytesN<32>,
        creator: Address,
        reason: String,
        evidence: String,
    ) -> Result<(), QuickLendXError> {
        pause::PauseControl::require_not_paused(&env)?;
        creator.require_auth();
        let mut invoice = InvoiceStorage::get_invoice(&env, &invoice_id)
            .ok_or(QuickLendXError::InvoiceNotFound)?;

        require_no_active_freeze(&env, &invoice_id)?;

        if invoice.dispute_status != DisputeStatus::None {
            return Err(QuickLendXError::DisputeAlreadyExists);
        }
        validate_dispute_reason(&reason)?;
        validate_dispute_evidence(&evidence)?;
        validate_dispute_eligibility(&invoice, &creator)?;
        dispute_timeline::clear_under_review_timestamp(&env, &invoice_id);
        invoice.dispute_status = DisputeStatus::Disputed;
        invoice.dispute = crate::types::Dispute {
            created_by: creator.clone(),
            created_at: env.ledger().timestamp(),
            reason: reason.clone(),
            evidence,
            resolution: String::from_str(&env, ""),
            resolved_by: Address::from_str(
                &env,
                "GAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAWHF",
            ),
            resolved_at: 0,
            resolution_outcome: DisputeResolution::None,
        };
        InvoiceStorage::update_invoice(&env, &invoice);
        dispute::track_dispute_invoice(&env, &invoice_id);
        // Emit DisputeCreated / DisputeOpened event immediately after state mutation.
        emit_dispute_created(&env, &invoice_id, &creator, &reason);
        if let Some(updated_invoice) = InvoiceStorage::get_invoice(&env, &invoice_id) {
            // Lifecycle trigger: dispute-opened notifications for business and investor.
            let _ =
                notifications::NotificationSystem::notify_dispute_opened(&env, &updated_invoice);
        }
        Ok(())
    }

    /// @notice Update dispute evidence while a dispute is still open.
    /// @dev Only the original dispute creator can update evidence, and only in the
    ///      `Disputed` state (before admin review starts).
    /// @param invoice_id The disputed invoice.
    /// @param creator The original dispute creator.
    /// @param evidence Replacement evidence payload (1–2000 chars).
    /// @return Ok(()) on success.
    pub fn update_dispute_evidence(
        env: Env,
        invoice_id: BytesN<32>,
        creator: Address,
        evidence: String,
    ) -> Result<(), QuickLendXError> {
        pause::PauseControl::require_not_paused(&env)?;
        creator.require_auth();
        validate_dispute_evidence(&evidence)?;

        let mut invoice = InvoiceStorage::get_invoice(&env, &invoice_id)
            .ok_or(QuickLendXError::InvoiceNotFound)?;

        require_no_active_freeze(&env, &invoice_id)?;

        if invoice.dispute_status != DisputeStatus::Disputed {
            return Err(QuickLendXError::InvalidStatus);
        }
        if invoice.dispute.created_by != creator {
            return Err(QuickLendXError::DisputeNotAuthorized);
        }

        invoice.dispute.evidence = evidence;
        InvoiceStorage::update_invoice(&env, &invoice);
        dispute::track_dispute_invoice(&env, &invoice_id);
        Ok(())
    }

    pub fn get_invoice_dispute_status(
        env: Env,
        invoice_id: BytesN<32>,
    ) -> Result<DisputeStatus, QuickLendXError> {
        let invoice = InvoiceStorage::get_invoice(&env, &invoice_id)
            .ok_or(QuickLendXError::InvoiceNotFound)?;
        Ok(invoice.dispute_status)
    }

    pub fn get_dispute_details(
        env: Env,
        invoice_id: BytesN<32>,
    ) -> Result<Option<crate::types::Dispute>, QuickLendXError> {
        let invoice = InvoiceStorage::get_invoice(&env, &invoice_id)
            .ok_or(QuickLendXError::InvoiceNotFound)?;
        if invoice.dispute_status == DisputeStatus::None {
            return Ok(None);
        }
        Ok(Some(invoice.dispute))
    }

    pub fn put_dispute_under_review(
        env: Env,
        invoice_id: BytesN<32>,
        admin: Address,
    ) -> Result<(), QuickLendXError> {
        AdminStorage::require_admin(&env, &admin)?;
        let mut invoice = InvoiceStorage::get_invoice(&env, &invoice_id)
            .ok_or(QuickLendXError::InvoiceNotFound)?;

        require_no_active_freeze(&env, &invoice_id)?;

        match invoice.dispute_status {
            DisputeStatus::None => return Err(QuickLendXError::DisputeNotFound),
            DisputeStatus::Disputed => {}
            DisputeStatus::UnderReview | DisputeStatus::Resolved => {
                return Err(QuickLendXError::InvalidStatus);
            }
        }

        invoice.dispute_status = DisputeStatus::UnderReview;
        InvoiceStorage::update_invoice(&env, &invoice);
        dispute::track_dispute_invoice(&env, &invoice_id);
        dispute_timeline::set_under_review_timestamp(&env, &invoice_id, env.ledger().timestamp());
        // Emit DisputeUnderReview event immediately after state mutation.
        emit_dispute_under_review(&env, &invoice_id, &admin);
        Ok(())
    }

    pub fn resolve_dispute(
        env: Env,
        invoice_id: BytesN<32>,
        admin: Address,
        resolution: String,
    ) -> Result<(), QuickLendXError> {
        AdminStorage::require_admin(&env, &admin)?;
        validate_dispute_resolution(&resolution)?;
        let mut invoice = InvoiceStorage::get_invoice(&env, &invoice_id)
            .ok_or(QuickLendXError::InvoiceNotFound)?;

        require_no_active_freeze(&env, &invoice_id)?;

        if invoice.dispute_status != DisputeStatus::UnderReview {
            return Err(QuickLendXError::DisputeNotUnderReview);
        }

        invoice.dispute_status = DisputeStatus::Resolved;
        invoice.dispute.resolution = resolution.clone();
        invoice.dispute.resolved_by = admin.clone();
        invoice.dispute.resolved_at = env.ledger().timestamp();
        invoice.dispute.resolution_outcome = DisputeResolution::None;
        InvoiceStorage::update_invoice(&env, &invoice);
        dispute::track_dispute_invoice(&env, &invoice_id);
        // Emit DisputeResolved event immediately after state mutation.
        emit_dispute_resolved(&env, &invoice_id, &admin, &resolution);
        if let Some(updated_invoice) = InvoiceStorage::get_invoice(&env, &invoice_id) {
            // Lifecycle trigger: dispute-resolved notifications for business and investor.
            let _ =
                notifications::NotificationSystem::notify_dispute_resolved(&env, &updated_invoice);
        }
        Ok(())
    }

    pub fn resolve_dispute_structured(
        env: Env,
        invoice_id: BytesN<32>,
        admin: Address,
        outcome: DisputeResolution,
        note: String,
    ) -> Result<(), QuickLendXError> {
        AdminStorage::require_admin(&env, &admin)?;
        validate_dispute_resolution(&note)?;
        let mut invoice = InvoiceStorage::get_invoice(&env, &invoice_id)
            .ok_or(QuickLendXError::InvoiceNotFound)?;

        require_no_active_freeze(&env, &invoice_id)?;

        if invoice.dispute_status != DisputeStatus::UnderReview {
            return Err(QuickLendXError::DisputeNotUnderReview);
        }

        invoice.dispute_status = DisputeStatus::Resolved;
        invoice.dispute.resolution = note.clone();
        invoice.dispute.resolution_outcome = outcome;
        invoice.dispute.resolved_by = admin.clone();
        invoice.dispute.resolved_at = env.ledger().timestamp();
        InvoiceStorage::update_invoice(&env, &invoice);
        dispute::track_dispute_invoice(&env, &invoice_id);
        // Emit exactly one event: DisputeRejected for dismissed disputes,
        // DisputeResolved for all other outcomes. Never both.
        if outcome == DisputeResolution::Dismissed {
            emit_dispute_rejected(&env, &invoice_id, &admin, &note);
        } else {
            emit_dispute_resolved(&env, &invoice_id, &admin, &note);
        }
        if let Some(updated_invoice) = InvoiceStorage::get_invoice(&env, &invoice_id) {
            // Lifecycle trigger: dispute-resolved notifications for business and investor.
            let _ =
                notifications::NotificationSystem::notify_dispute_resolved(&env, &updated_invoice);
        }
        Ok(())
    }

    pub fn get_invoices_with_disputes(env: Env) -> Vec<BytesN<32>> {
        let mut result = Vec::new(&env);
        for status in [
            InvoiceStatus::Pending,
            InvoiceStatus::Verified,
            InvoiceStatus::Funded,
            InvoiceStatus::Paid,
        ] {
            for id in InvoiceStorage::get_invoices_by_status(&env, status).iter() {
                if let Some(inv) = InvoiceStorage::get_invoice(&env, &id) {
                    if inv.dispute_status != DisputeStatus::None {
                        result.push_back(id);
                    }
                }
            }
        }
        result
    }

    pub fn get_dispute_timeline(
        env: Env,
        invoice_id: BytesN<32>,
        offset: u32,
        limit: u32,
    ) -> Result<dispute_timeline::DisputeTimeline, QuickLendXError> {
        dispute_timeline::get_dispute_timeline(&env, &invoice_id, offset, limit)
    }

    pub fn get_invoices_by_dispute_status(
        env: Env,
        dispute_status: DisputeStatus,
    ) -> Vec<BytesN<32>> {
        let mut result = Vec::new(&env);
        for status in [
            InvoiceStatus::Pending,
            InvoiceStatus::Verified,
            InvoiceStatus::Funded,
            InvoiceStatus::Paid,
        ] {
            for id in InvoiceStorage::get_invoices_by_status(&env, status).iter() {
                if let Some(inv) = InvoiceStorage::get_invoice(&env, &id) {
                    if inv.dispute_status == dispute_status {
                        result.push_back(id);
                    }
                }
            }
        }
        result
    }

    // =========================================================================
    // Audit
    // =========================================================================

    pub fn get_invoice_audit_trail(env: Env, invoice_id: BytesN<32>) -> Vec<BytesN<32>> {
        audit::AuditStorage::get_invoice_audit_trail(&env, &invoice_id)
    }

    pub fn get_audit_entry(env: Env, audit_id: BytesN<32>) -> Option<audit::AuditLogEntry> {
        audit::AuditStorage::get_audit_entry(&env, &audit_id)
    }

    /// Get all audit entry IDs for a given operation type.
    pub fn get_audit_entries_by_operation(
        env: Env,
        operation: audit::AuditOperation,
    ) -> Vec<BytesN<32>> {
        audit::AuditStorage::get_audit_entries_by_operation(&env, &operation)
    }

    /// Get all audit entry IDs attributed to a given actor address.
    pub fn get_audit_entries_by_actor(env: Env, actor: Address) -> Vec<BytesN<32>> {
        audit::AuditStorage::get_audit_entries_by_actor(&env, &actor)
    }

    pub fn query_audit_logs(
        env: Env,
        filter: audit::AuditQueryFilter,
        limit: u32,
    ) -> Vec<audit::AuditLogEntry> {
        audit::AuditStorage::query_audit_logs(&env, &filter, limit)
    }

    pub fn get_audit_stats(env: Env) -> audit::AuditStats {
        audit::AuditStorage::get_audit_stats(&env)
    }

    pub fn validate_invoice_audit_integrity(
        env: Env,
        invoice_id: BytesN<32>,
    ) -> Result<bool, QuickLendXError> {
        audit::AuditStorage::validate_invoice_audit_integrity(&env, &invoice_id)
    }

    /// Verify that the invoice-local audit hash chain has no divergence.
    pub fn verify_audit_chain(env: Env, invoice_id: BytesN<32>) -> bool {
        audit::AuditStorage::verify_audit_chain(&env, &invoice_id)
    }

    /// Return the zero-based first audit-chain divergence point, if any.
    pub fn first_audit_chain_divergence(env: Env, invoice_id: BytesN<32>) -> Option<u32> {
        audit::AuditStorage::first_audit_chain_divergence(&env, &invoice_id)
    }

    // =========================================================================
    // Notifications
    // =========================================================================

    pub fn get_notification(
        env: Env,
        notification_id: BytesN<32>,
    ) -> Option<notifications::Notification> {
        notifications::NotificationSystem::get_notification(&env, &notification_id)
    }

    pub fn get_user_notifications(env: Env, user: Address) -> Vec<BytesN<32>> {
        notifications::NotificationSystem::get_user_notifications(&env, &user)
    }

    pub fn get_notification_preferences(
        env: Env,
        user: Address,
    ) -> notifications::NotificationPreferences {
        notifications::NotificationSystem::get_user_preferences(&env, &user)
    }

    pub fn update_notification_preferences(
        env: Env,
        user: Address,
        preferences: notifications::NotificationPreferences,
    ) {
        user.require_auth();
        notifications::NotificationSystem::update_user_preferences(&env, &user, preferences);
    }

    pub fn update_notification_status(
        env: Env,
        notification_id: BytesN<32>,
        status: notifications::NotificationDeliveryStatus,
    ) -> Result<(), QuickLendXError> {
        notifications::NotificationSystem::update_notification_status(
            &env,
            &notification_id,
            status,
        )
    }

    pub fn get_user_notification_stats(
        env: Env,
        user: Address,
    ) -> notifications::NotificationStats {
        notifications::NotificationSystem::get_user_notification_stats(&env, &user)
    }

    /// Return the unread notification count for `investor` in O(n) without loading full bodies.
    pub fn get_notification_unread_count(env: Env, investor: Address) -> u32 {
        notifications::NotificationSystem::get_notification_unread_count(&env, &investor)
    }

    pub fn get_financial_metrics(
        env: Env,
        period: analytics::TimePeriod,
    ) -> Result<analytics::FinancialMetrics, QuickLendXError> {
        analytics::AnalyticsCalculator::calculate_financial_metrics(&env, period)
    }

    /// Retrieve a stored investor report by ID
    pub fn get_investor_report(
        env: Env,
        report_id: BytesN<32>,
    ) -> Option<analytics::InvestorReport> {
        analytics::AnalyticsStorage::get_investor_report(&env, &report_id)
    }

    /// Get a summary of platform and performance metrics
    pub fn get_analytics_summary(
        env: Env,
    ) -> (analytics::PlatformMetrics, analytics::PerformanceMetrics) {
        let platform = analytics::AnalyticsCalculator::calculate_platform_metrics(&env).unwrap_or(
            analytics::PlatformMetrics {
                total_invoices: 0,
                total_investments: 0,
                total_volume: 0,
                total_fees_collected: 0,
                active_investors: 0,
                verified_businesses: 0,
                average_invoice_amount: 0,
                average_investment_amount: 0,
                platform_fee_rate: 0,
                default_rate: 0,
                success_rate: 0,
                timestamp: env.ledger().timestamp(),
            },
        );
        let performance = analytics::AnalyticsCalculator::calculate_performance_metrics(&env)
            .unwrap_or(analytics::PerformanceMetrics {
                platform_uptime: env.ledger().timestamp(),
                average_settlement_time: 0,
                average_verification_time: 0,
                dispute_resolution_time: 0,
                system_response_time: 0,
                transaction_success_rate: 0,
                error_rate: 0,
                user_satisfaction_score: 0,
                platform_efficiency: 0,
            });
        (platform, performance)
    }

    /// Build API freshness metadata as string key/value pairs.
    ///
    /// # Errors
    ///
    /// Returns [] when
    /// . Stellar/Soroban ledger sequences start at 1;
    /// a value of 0 indicates an uninitialised or default-constructed caller
    /// argument and must be rejected at the entrypoint boundary to prevent
    /// stale or misleading freshness data from reaching downstream consumers.
    ///
    /// **Threat model**: accepting sequence 0 would allow a caller to supply a
    /// sentinel "not-yet-indexed" value and receive a freshness response that
    /// appears valid but represents no real ledger state. Downstream consumers
    /// that cache the cursor  could serve permanently stale data.
    ///
    /// See `quicklendx-contracts/docs/freshness.md` for the documented
    /// freshness drift bound and client handling guidance.
    pub fn get_freshness(
        env: Env,
        indexed_ledger_seq: u32,
        indexed_ledger_timestamp: u64,
        offset: u32,
    ) -> Result<Map<String, String>, QuickLendXError> {
        // Guard: ledger sequences start at 1 in Soroban; 0 is never a valid
        // on-chain ledger sequence and indicates a caller bug or an attempt to
        // inject a sentinel that bypasses freshness checks.
        if indexed_ledger_seq == 0 {
            return Err(QuickLendXError::InvalidLedgerSequence);
        }

        let meta = freshness::FreshnessMetadata::from_env(
            &env,
            indexed_ledger_seq,
            indexed_ledger_timestamp,
            offset,
        );

        let mut result = Map::new(&env);
        result.set(
            String::from_str(&env, "last_indexed_ledger"),
            u32_to_string_lib(&env, meta.last_indexed_ledger),
        );
        result.set(
            String::from_str(&env, "index_lag_seconds"),
            i64_to_string_lib(&env, meta.index_lag_seconds),
        );
        result.set(
            String::from_str(&env, "last_updated_at"),
            meta.last_updated_at,
        );
        result.set(String::from_str(&env, "cursor"), meta.cursor);
        Ok(result)
    }

    // ============================================================================
    // Admin Recovery
    // ============================================================================

    /// Rebuild secondary invoice indexes from canonical `Invoice` records.
    ///
    /// Secondary indexes (`invoices_by_customer`, `invoices_by_tax_id`,
    /// `invoices_by_tag`, `invoices_by_category`) can drift from primary records
    /// after a backup restore, a partial migration, or a past bug. This function
    /// recomputes them for a page of invoices without touching primary records.
    ///
    /// # Resumability
    /// The operation is paginated. On each call pass the `next_offset` from the
    /// previous `RebuildReport` as `offset` until `report.next_offset` stops
    /// advancing (last page). A `limit` of 0 returns an empty report immediately.
    ///
    /// # Idempotency
    /// Every index write is a dedup-guarded append. Running the full sequence
    /// twice leaves indexes in exactly the same state as running it once.
    ///
    /// # Arguments
    /// * `admin`  - Must be the current protocol admin (authorization required).
    /// * `offset` - Zero-based start position in the full invoice ID list.
    /// * `limit`  - Max invoices to process per call (capped at 100).
    pub fn rebuild_invoice_indexes(
        env: Env,
        admin: Address,
        offset: u32,
        limit: u32,
    ) -> Result<RebuildReport, QuickLendXError> {
        admin.require_auth();
        AdminStorage::require_admin(&env, &admin)?;
        let config = init::ProtocolInitializer::get_protocol_config(&env)
            .ok_or(QuickLendXError::OperationNotAllowed)?;
        if limit > config.backfill_max_batch_size {
            return Err(QuickLendXError::BatchSizeExceeded);
        }
        let report = InvoiceStorage::rebuild_indexes_page(&env, offset, limit);
        Ok(report)
    }

    /// Prune terminal-state invoices whose terminal timestamp is older than
    /// `older_than_secs` from the current ledger timestamp.
    ///
    /// Only invoices in a terminal status (`Paid`, `Defaulted`, `Cancelled`,
    /// `Refunded`) are eligible. For `Paid` invoices the terminal timestamp
    /// is `settled_at`; for other terminal statuses it falls back to
    /// `created_at`. Invoices in `Pending`, `Verified`, or `Funded` status
    /// are never pruned regardless of age.
    ///
    /// Each pruned invoice is removed from all secondary indexes (status,
    /// business, customer, tax_id, tag, category) and from primary persistent
    /// storage. This operation is **irreversible** — there is no undo.
    ///
    /// # Resumability
    /// The operation is paginated and resumable. Pass the `next_offset` from the
    /// returned `PruneReport` as `offset` on the next call. Stop when
    /// `next_offset` stops advancing (last page reached).
    ///
    /// # Arguments
    /// * `admin`           - Must be the current protocol admin (auth required).
    /// * `older_than_secs` - Retention window in seconds. Only invoices whose
    ///                       terminal timestamp is older than this are pruned.
    /// * `offset`          - Zero-based start position in the full invoice list.
    /// * `limit`           - Max invoices to scan per call (capped at 100).
    pub fn prune_terminal_invoices(
        env: Env,
        admin: Address,
        older_than_secs: u64,
        offset: u32,
        limit: u32,
    ) -> Result<PruneReport, QuickLendXError> {
        admin.require_auth();
        AdminStorage::require_admin(&env, &admin)?;
        let config = init::ProtocolInitializer::get_protocol_config(&env)
            .ok_or(QuickLendXError::OperationNotAllowed)?;
        if limit > config.backfill_max_batch_size {
            return Err(QuickLendXError::BatchSizeExceeded);
        }
        let report =
            InvoiceStorage::prune_terminal_invoices_page(&env, older_than_secs, offset, limit);
        Ok(report)
    }

    /// Repair missing held escrow reserve entries for one token from indexed invoice records.
    ///
    /// The first call (`offset = 0`) snapshots the current status-derived
    /// invoice ID list, subject to an invoice-count cap, so later pages are not
    /// shifted by status-index mutations. Scanning/summing then proceeds in
    /// bounded pages. Emergency execution for the token remains closed until a
    /// full sequence completes. Continue with each returned `next_offset` while
    /// `next_offset != 0`. A returned `next_offset` of 0 means the reserve is
    /// complete and emergency withdrawal for that token may pass the
    /// reserve-completeness gate. Starting again at `offset = 0` recomputes the
    /// reserve from scratch. During a multi-page repair, same-token escrow
    /// create/release/refund reject with `InvalidStatus` until the final page
    /// completes.
    pub fn repair_held_escrow_reserve(
        env: Env,
        admin: Address,
        currency: Address,
        offset: u32,
        limit: u32,
    ) -> Result<RebuildReport, QuickLendXError> {
        admin.require_auth();
        AdminStorage::require_admin(&env, &admin)?;
        let config = init::ProtocolInitializer::get_protocol_config(&env)
            .ok_or(QuickLendXError::OperationNotAllowed)?;
        if limit > config.backfill_max_batch_size {
            return Err(QuickLendXError::BatchSizeExceeded);
        }
        EscrowStorage::repair_held_reserve_page(&env, &currency, offset, limit)
    }

    pub fn extend_escrow_expiry(
        env: Env,
        admin: Address,
        invoice_id: BytesN<32>,
        new_due_date: u64,
    ) -> Result<(), QuickLendXError> {
        pause::PauseControl::require_not_paused(&env)?;
        admin.require_auth();
        admin::AdminStorage::require_admin(&env, &admin)?;

        let mut invoice = storage::InvoiceStorage::get_invoice(&env, &invoice_id)
            .ok_or(QuickLendXError::InvoiceNotFound)?;

        let escrow = payments::EscrowStorage::get_escrow_by_invoice(&env, &invoice_id)
            .ok_or(QuickLendXError::OperationNotAllowed)?;

        if escrow.status != payments::EscrowStatus::Held {
            return Err(QuickLendXError::InvalidStatus);
        }

        let ext_key = storage::DataKey::EscrowExtension(invoice_id.clone());
        if env.storage().persistent().has(&ext_key) {
            return Err(QuickLendXError::OperationNotAllowed);
        }

        if new_due_date <= invoice.due_date {
            return Err(QuickLendXError::InvoiceDueDateInvalid);
        }

        let limits = protocol_limits::ProtocolLimitsContract::get_protocol_limits(env.clone());
        let max_horizon = limits.max_due_date_days.saturating_mul(86_400);
        let max_allowed = env.ledger().timestamp().saturating_add(max_horizon);
        if new_due_date > max_allowed {
            return Err(QuickLendXError::InvoiceDueDateInvalid);
        }

        env.storage().persistent().set(&ext_key, &true);
        storage::extend_persistent_ttl(&env, &ext_key);

        invoice.due_date = new_due_date;
        storage::InvoiceStorage::update_invoice(&env, &invoice);

        Ok(())
    }

    /// Query the total locked escrow value across a caller-supplied bounded list of currencies.
    ///
    /// At most `max_currencies` entries from `currencies` are aggregated in one call.
    /// Use this to stay within Soroban resource limits when many currencies exist.
    pub fn get_total_locked_escrow(
        env: Env,
        currencies: Vec<Address>,
        max_currencies: u32,
    ) -> i128 {
        EscrowStorage::get_total_locked_escrow_bounded(&env, &currencies, max_currencies)
    }
}

// ── Upgrade control entrypoints ─────────────────────────────────────────────

#[contractimpl]
impl QuickLendXContract {
    pub fn schedule_upgrade(env: Env, admin: Address, wasm_hash: BytesN<32>) -> Result<(), QuickLendXError> {
        upgrade::UpgradeControl::schedule_upgrade(&env, &admin, &wasm_hash)
    }

    pub fn cancel_upgrade(env: Env, admin: Address) -> Result<(), QuickLendXError> {
        upgrade::UpgradeControl::cancel_upgrade(&env, &admin)
    }

    pub fn execute_upgrade(env: Env, admin: Address) -> Result<(), QuickLendXError> {
        upgrade::UpgradeControl::execute_upgrade(&env, &admin)
    }
}

// =============================================================================
// Feature-gated contract entrypoints
// =============================================================================
//
// get_protocol_diagnostics is intentionally NOT inside the main contractimpl block.
// The soroban-sdk contractimpl macro unconditionally emits export stubs for every
// pub fn, ignoring cfg(...) on the method itself. Gating the entire impl block
// prevents stub generation in non-diagnostics builds.

#[cfg(feature = "diagnostics")]
#[contractimpl]
impl QuickLendXContract {
    pub fn get_protocol_diagnostics(env: Env) -> diagnostics::ProtocolDiagnostics {
        diagnostics::get_protocol_diagnostics(&env)
    }
}

#[cfg(all(test, feature = "legacy-tests"))]
mod test_emergency_escrow_protection;
#[cfg(all(test, feature = "legacy-tests"))]
mod test_escrow_settle_refund_race;
#[cfg(test)]
// mod test_escrow_mutual_exclusion;
#[cfg(all(test, feature = "legacy-tests"))]
mod test_id_collision_cross_domain;
#[cfg(all(test, feature = "legacy-tests"))]
mod test_id_stability;

#[cfg(test)]
mod test_settlement_auto_release;

#[cfg(all(test, feature = "legacy-tests"))]
mod test_settlement_dispute_interaction;

#[cfg(test)]
mod test_prune_terminal_invoices;
#[cfg(test)]
mod test_view_only;

#[cfg(test)]
mod test_business_freeze_reason;

#[cfg(test)]
mod test_freeze_guard_writes;

#[cfg(test)]
mod test_freeze_event;

// Issue #1960 — serialisation stability for freeze_appeal_channel field.
#[cfg(test)]
mod test_freeze_appeal_channel;

#[cfg(all(test, feature = "fuzz-tests"))]
mod test_fuzz_accounting;

#[cfg(all(test, feature = "fuzz-tests"))]
mod test_fuzz_default_flow;
#[cfg(feature = "diagnostics")]
#[contractimpl]
impl QuickLendXContract {
    /// Return a rich internal diagnostic snapshot.
    ///
    /// Intended for operator tooling, support dashboards, and integration tests
    /// that need per-status invoice counts, bid counters, and subsystem flags in
    /// a single call without having to fan out across multiple read entry-points.
    ///
    /// # Returns
    /// A [`diagnostics::ProtocolDiagnostics`] snapshot (see `diagnostics.rs`).
    ///
    /// # Security
    /// - No authentication required (read-only, no PII).
    /// - State is never mutated.
    pub fn get_protocol_diagnostics(env: Env) -> diagnostics::ProtocolDiagnostics {
        diagnostics::get_protocol_diagnostics(&env)
    }
}