export interface CurrencyDefinition<TCurrencyId extends string = string> {
    id: TCurrencyId;
    name: string;
    /** Fractional digits in major-unit amounts; defaults to 0. */
    decimals?: number;
    /** Prepended when formatting amounts (e.g. "$"). */
    symbol?: string;
    /** Appended when formatting amounts (e.g. "tokens"). */
    unit?: string;
}
export type CurrencyOperation = "add" | "deduct";
export type CurrencyAdjustment = {
    success: true;
    newBalance: number;
    appliedDelta: number;
} | {
    success: false;
    reason: string;
};
/** @internal */
export declare function sanitizeCurrencyAmount(amount: number, currency?: CurrencyDefinition): number;
/** Convert major units to integer minor units, rounding once at the write boundary.
 * @capability currency-minor-units round decimal currency into safe integer minor units
 */
export declare function toMinorUnits(currency: Pick<CurrencyDefinition, "decimals"> | undefined, value: number): number;
/** Convert stored integer minor units to major units for display or existing balance records.
 * @capability currency-major-units convert safe minor-unit integers into currency amounts
 */
export declare function fromMinorUnits(currency: Pick<CurrencyDefinition, "decimals"> | undefined, value: number): number;
/** Format a major-unit value using the currency's declared precision.
 * @capability currency-precision-format display a currency using its declared decimal precision
 */
export declare function formatCurrency(currency: CurrencyDefinition, value: number): string;
/**
 * Format a currency amount with its symbol and grouping for HUD display.
 *
 * @capability currency-format format a currency amount with its symbol for display
  * @internal
  */
export declare function formatCurrencyAmount(currency: CurrencyDefinition, amount: number): string;
/** @internal */
export declare function insufficientCurrencyReason(currency: CurrencyDefinition, needed: number, current: number): string;
/** @internal */
export declare function applyCurrencyOperation(currency: CurrencyDefinition, current: number, operation: CurrencyOperation, amount: number): CurrencyAdjustment;
/** Deducts clamp to the available balance (a delta can never overdraw); adds apply in full.
 * @internal
 */
export declare function resolveCurrencyDelta(current: number, delta: number, currency?: CurrencyDefinition): {
    operation: CurrencyOperation;
    amount: number;
};