Math Engine Reference: Finance Fixed

typedef enum math_engine_finance_rate_kind {
    MATH_ENGINE_FINANCE_RATE_INVALID = 0, /**< 초기화되지 않았거나 알려지지 않은 rate-kind sentinel이다. */
    MATH_ENGINE_FINANCE_RATE_GENERIC = 1, /**< 별도 percentage/period 의미를 강제하지 않는 무차원 multiplier rate다. */
    MATH_ENGINE_FINANCE_RATE_PERCENTAGE = 2, /**< Fee 또는 tax에 적용하는 무차원 percentage rate다. 7.5%는 0.075다. */
    MATH_ENGINE_FINANCE_RATE_PER_PERIOD = 3 /**< 단리·복리의 한 기간마다 적용하는 무차원 rate다. */
} math_engine_finance_rate_kind_t;

typedef enum math_engine_finance_fx_direction {
    MATH_ENGINE_FINANCE_FX_INVALID = 0, /**< 초기화되지 않았거나 알려지지 않은 FX direction sentinel이다. */
    /** quote.rate는 target currency / source currency다. */
    MATH_ENGINE_FINANCE_FX_TARGET_PER_SOURCE = 1,
    /** quote.rate는 source currency / target currency다. */
    MATH_ENGINE_FINANCE_FX_SOURCE_PER_TARGET = 2
} math_engine_finance_fx_direction_t;

typedef enum math_engine_finance_operation {
    MATH_ENGINE_FINANCE_OPERATION_INVALID = 0, /**< Audit record가 초기화 상태이거나 provenance가 없음을 나타낸다. */
    MATH_ENGINE_FINANCE_OPERATION_QUANTIZE = 1, /**< Money amount를 currency minor-unit scale로 한 번 양자화했다. */
    MATH_ENGINE_FINANCE_OPERATION_FEE = 2, /**< 한 money value에 percentage fee rate를 적용했다. */
    MATH_ENGINE_FINANCE_OPERATION_TAX = 3, /**< 한 money value에 percentage tax rate를 적용했다. */
    MATH_ENGINE_FINANCE_OPERATION_SIMPLE_INTEREST = 4, /**< Principal에 기간 수를 곱한 단리 interest를 계산했다. */
    MATH_ENGINE_FINANCE_OPERATION_COMPOUND_INTEREST = 5, /**< 각 기간에 booking/rounding하는 복리 balance를 계산했다. */
    MATH_ENGINE_FINANCE_OPERATION_FX_MULTIPLY = 6, /**< TARGET_PER_SOURCE quote rate를 source amount에 곱했다. */
    MATH_ENGINE_FINANCE_OPERATION_FX_DIVIDE = 7, /**< SOURCE_PER_TARGET quote rate로 source amount를 나눴다. */
    MATH_ENGINE_FINANCE_OPERATION_AGGREGATE = 8, /**< 같은 통화 money 배열을 순서 독립적으로 합산했다. */
    MATH_ENGINE_FINANCE_OPERATION_PROPORTIONAL_ALLOCATION = 9, /**< Booked minor units를 largest-remainder 방식으로 보존 배분했다. */
    MATH_ENGINE_FINANCE_OPERATION_BATCH_FEE = 10, /**< Money 배열에 fee rate를 deterministic block 순서로 적용했다. */
    MATH_ENGINE_FINANCE_OPERATION_BATCH_TAX = 11 /**< Money 배열에 tax rate를 deterministic block 순서로 적용했다. */
} math_engine_finance_operation_t;

typedef struct math_engine_finance_currency {
    char code[4]; /**< 세 자리 uppercase ASCII currency code와 네 번째 NUL byte다. 외부 catalog를 참조하지 않는다. */
    uint32_t minor_unit; /**< Booked amount의 decimal scale이며 inclusive 0..18 범위다. */
} math_engine_finance_currency_t;

typedef struct math_engine_finance_money {
    math_engine_decimal_fixed_t amount; /**< 통화 단위의 decimal 금액이다. 성공한 booking 결과 scale은 =currency.minor_unit=이다. */
    math_engine_finance_currency_t currency; /**< Amount의 통화 code와 minor-unit quantum이다. */
    uint64_t reserved; /**< 향후 ABI 확장용이다. Caller와 producer 모두 0을 기록해야 한다. */
} math_engine_finance_money_t;

typedef struct math_engine_finance_rate {
    math_engine_decimal_fixed_t value; /**< 무차원 decimal rate다. Percentage 7.5%는 정확히 0.075로 표현한다. */
    uint32_t kind; /**< Rate의 소비 계약을 정하는 =math_engine_finance_rate_kind_t= 값이다. */
    uint32_t reserved; /**< 향후 ABI 확장용이다. Caller와 producer 모두 0을 기록해야 한다. */
} math_engine_finance_rate_t;

typedef struct math_engine_finance_fx_quote {
    math_engine_finance_currency_t source_currency; /**< Conversion input amount가 사용해야 하는 통화다. */
    math_engine_finance_currency_t target_currency; /**< Conversion output amount가 사용하는 서로 다른 통화다. */
    math_engine_decimal_fixed_t rate; /**< Source/target 관계를 =direction=에 따라 해석하는 strictly positive decimal quote rate다. */
    uint32_t direction; /**< Rate를 곱할지 나눌지 정하는 =math_engine_finance_fx_direction_t= 값이다. */
    uint32_t reserved; /**< 향후 ABI 확장용이다. Caller와 producer 모두 0을 기록해야 한다. */
} math_engine_finance_fx_quote_t;

typedef struct math_engine_finance_policy {
    uint32_t struct_size; /**< Caller가 =sizeof(math_engine_finance_policy_t)=로 설정하는 byte 크기다. */
    uint32_t struct_version; /**< =MATH_ENGINE_FINANCE_POLICY_VERSION_1=인 policy ABI version이다. */
    uint32_t rounding; /**< 모든 minor-unit 양자화에 적용하는 =math_engine_decimal_rounding_t= 값이다. */
    uint32_t requested_thread_count; /**< Batch worker 수다. 0이면 hardware와 ceiling 안에서 자동 선택한다. */
    uint64_t maximum_periods; /**< Interest operation이 허용하는 inclusive period-count ceiling이다. */
    uint64_t memory_budget_bytes; /**< Caller workspace와 내부 임시 bookkeeping에 허용한 byte ceiling이다. */
    uint32_t flags; /**< Version 1 finance-policy flag bitset이다. 정의되지 않은 bit는 0이어야 한다. */
    uint32_t reserved; /**< 향후 ABI 확장용이다. Caller는 0으로 설정해야 하며 nonzero policy는 INVALID_ARGUMENT로 거부된다. */
} math_engine_finance_policy_t;

typedef struct math_engine_finance_audit {
    uint32_t struct_size; /**< Caller가 =sizeof(math_engine_finance_audit_t)=로 설정하는 byte 크기다. */
    uint32_t struct_version; /**< =MATH_ENGINE_FINANCE_AUDIT_VERSION_1=인 audit ABI version이다. */
    math_engine_finance_money_t value; /**< Operation이 최종 booking한 통화 minor-unit 금액이다. */
    uint32_t operation; /**< Booked value를 만든 =math_engine_finance_operation_t= 값이다. */
    uint32_t rounding; /**< Booking에 적용한 =math_engine_decimal_rounding_t= 값이다. */
    int32_t input_scale; /**< 주 입력 decimal amount의 원래 scale이다. */
    int32_t output_scale; /**< =value.amount.scale=과 같은 booked minor-unit scale이다. */
    uint32_t flags; /**< =MATH_ENGINE_FINANCE_AUDIT_FLAG_*= provenance bit의 조합이다. */
    uint32_t selected_thread_count; /**< 실제 batch 실행에 선택한 worker 수다. Scalar operation은 1이다. */
    uint64_t operand_count; /**< Aggregate/batch/allocation에 소비한 money 또는 weight 원소 수다. */
    uint64_t period_count; /**< Interest calculation에 적용한 기간 수다. 다른 operation은 0이다. */
    int64_t remainder_units; /**< Allocation/rounding에서 결정적으로 배분하거나 버린 signed minor-unit 수다. */
    uint64_t decimal_operation_fingerprint; /**< 하위 decimal calculation의 scale·rounding·operand provenance fingerprint다. */
    uint64_t replay_fingerprint; /**< Operation input 순서와 canonical block/remainder 결정을 재현하는 audit fingerprint다. */
    uint64_t reserved[3]; /**< 향후 ABI 확장용 세 slot이다. Producer는 모두 0을 기록하고 consumer는 무시한다. */
} math_engine_finance_audit_t;

#define MATH_ENGINE_FINANCE_AUDIT_FLAG_CONSERVED (UINT32_C(1) << 2u)

#define MATH_ENGINE_FINANCE_AUDIT_FLAG_EXACT (UINT32_C(1) << 0u)

#define MATH_ENGINE_FINANCE_AUDIT_FLAG_PARALLEL (UINT32_C(1) << 3u)

#define MATH_ENGINE_FINANCE_AUDIT_FLAG_PERIODIC_ROUNDING (UINT32_C(1) << 4u)

#define MATH_ENGINE_FINANCE_AUDIT_FLAG_ROUNDED (UINT32_C(1) << 1u)

#define MATH_ENGINE_FINANCE_AUDIT_VERSION_1 UINT32_C(1)

#define MATH_ENGINE_FINANCE_AUDIT_WIRE_SIZE UINT64_C(128)

#define MATH_ENGINE_FINANCE_AUDIT_WIRE_VERSION_1 UINT32_C(1)

#define MATH_ENGINE_FINANCE_BATCH_BLOCK_ITEMS UINT32_C(256)

#define MATH_ENGINE_FINANCE_MAX_THREADS MATH_ENGINE_DESKTOP_THREAD_COUNT_LIMIT

#define MATH_ENGINE_FINANCE_POLICY_VERSION_1 UINT32_C(1)

MATH_ENGINE_API math_engine_status_t math_engine_finance_currency_validate(
    const math_engine_finance_currency_t* currency);

MATH_ENGINE_API math_engine_status_t math_engine_finance_money_validate(
    const math_engine_finance_money_t* money);

MATH_ENGINE_API math_engine_status_t math_engine_finance_rate_validate(
    const math_engine_finance_rate_t* rate);

MATH_ENGINE_API math_engine_status_t math_engine_finance_fx_quote_validate(
    const math_engine_finance_fx_quote_t* quote);

MATH_ENGINE_API math_engine_status_t math_engine_finance_workspace_size(
    uint64_t count,
    uint64_t* out_size);

MATH_ENGINE_API math_engine_status_t math_engine_finance_money_quantize(
    math_engine_finance_money_t money,
    const math_engine_context_t* context,
    const math_engine_finance_policy_t* policy,
    math_engine_finance_audit_t* out_audit);

MATH_ENGINE_API math_engine_status_t math_engine_finance_money_apply_rate(
    math_engine_finance_money_t money,
    math_engine_finance_rate_t rate,
    math_engine_finance_operation_t operation,
    const math_engine_context_t* context,
    const math_engine_finance_policy_t* policy,
    math_engine_finance_audit_t* out_audit);

MATH_ENGINE_API math_engine_status_t math_engine_finance_simple_interest(
    math_engine_finance_money_t principal,
    math_engine_finance_rate_t per_period_rate,
    uint64_t periods,
    const math_engine_context_t* context,
    const math_engine_finance_policy_t* policy,
    math_engine_finance_audit_t* out_audit);

MATH_ENGINE_API math_engine_status_t math_engine_finance_compound_interest(
    math_engine_finance_money_t principal,
    math_engine_finance_rate_t per_period_rate,
    uint64_t periods,
    const math_engine_context_t* context,
    const math_engine_finance_policy_t* policy,
    math_engine_finance_audit_t* out_audit);

MATH_ENGINE_API math_engine_status_t math_engine_finance_fx_convert(
    math_engine_finance_money_t source,
    math_engine_finance_fx_quote_t quote,
    const math_engine_context_t* context,
    const math_engine_finance_policy_t* policy,
    math_engine_finance_audit_t* out_audit);

MATH_ENGINE_API math_engine_status_t math_engine_finance_aggregate(
    const math_engine_finance_money_t* values,
    uint64_t count,
    const math_engine_context_t* context,
    const math_engine_finance_policy_t* policy,
    math_engine_finance_audit_t* out_audit);

MATH_ENGINE_API math_engine_status_t math_engine_finance_allocate_proportional(
    math_engine_finance_money_t amount,
    const uint64_t* weights,
    uint64_t count,
    const math_engine_context_t* context,
    const math_engine_finance_policy_t* policy,
    math_engine_mutable_byte_span_t workspace,
    math_engine_finance_money_t* outputs,
    math_engine_finance_audit_t* out_audit);

MATH_ENGINE_API math_engine_status_t math_engine_finance_batch_apply_rate(
    const math_engine_finance_money_t* values,
    uint64_t count,
    math_engine_finance_rate_t rate,
    math_engine_finance_operation_t operation,
    const math_engine_context_t* context,
    const math_engine_finance_policy_t* policy,
    math_engine_mutable_byte_span_t workspace,
    math_engine_finance_money_t* outputs,
    math_engine_finance_audit_t* out_audit);

MATH_ENGINE_API math_engine_status_t math_engine_finance_audit_encode(
    const math_engine_finance_audit_t* audit,
    uint8_t* buffer,
    uint64_t capacity);