/**
 * @fileoverview Canonical RiskLevel type definitions for the Vorion Platform.
 *
 * This file provides the authoritative definition for risk levels, unifying
 * the various representations found across packages (enum, string union, numeric)
 * into a single canonical source with conversion utilities.
 *
 * Risk levels classify the potential impact or severity of actions, decisions,
 * and events within the platform.
 *
 * @module @vorionsys/contracts/canonical/risk-level
 */
import { z } from 'zod';
/**
 * Canonical risk level type.
 *
 * Uses lowercase string union as the authoritative format.
 * This provides good developer experience while being easily
 * serializable and human-readable.
 *
 * Levels (in ascending severity):
 * - `low`: Minimal risk, standard operation
 * - `medium`: Moderate risk, enhanced monitoring recommended
 * - `high`: Significant risk, requires additional safeguards
 * - `critical`: Severe risk, may require human intervention
 *
 * @example
 * ```typescript
 * const risk: RiskLevel = 'medium';
 * ```
 */
export type RiskLevel = 'low' | 'medium' | 'high' | 'critical';
/**
 * Array of all risk levels in ascending severity order.
 *
 * Useful for iteration, validation, and UI components.
 */
export declare const RISK_LEVELS: readonly RiskLevel[];
/**
 * Numeric values for risk levels (0-3 scale).
 *
 * Enables numeric comparisons and calculations while maintaining
 * the string type as the canonical representation.
 *
 * @example
 * ```typescript
 * RISK_LEVEL_VALUES['critical']; // 3
 * RISK_LEVEL_VALUES['low'];      // 0
 * ```
 */
export declare const RISK_LEVEL_VALUES: Readonly<Record<RiskLevel, number>>;
/**
 * Human-readable labels for risk levels.
 *
 * Useful for display in UIs and reports.
 */
export declare const RISK_LEVEL_LABELS: Readonly<Record<RiskLevel, string>>;
/**
 * Detailed descriptions for each risk level.
 *
 * Provides guidance on what each level means and when to use it.
 */
export declare const RISK_LEVEL_DESCRIPTIONS: Readonly<Record<RiskLevel, string>>;
/**
 * Color codes for risk levels (for UI display).
 *
 * Uses common color conventions: green for low, yellow/orange for medium,
 * red for high, and dark red for critical.
 */
export declare const RISK_LEVEL_COLORS: Readonly<Record<RiskLevel, string>>;
/**
 * Default risk level for unclassified items.
 */
export declare const DEFAULT_RISK_LEVEL: RiskLevel;
/**
 * Converts a numeric value to a RiskLevel.
 *
 * Handles the 5-level numeric system (0-4) used by some packages
 * by mapping level 4 to 'critical' (same as level 3).
 *
 * @param n - Numeric value (0-4)
 * @returns Corresponding RiskLevel
 *
 * @example
 * ```typescript
 * riskLevelFromNumber(0); // 'low'
 * riskLevelFromNumber(2); // 'high'
 * riskLevelFromNumber(4); // 'critical' (Council's L4 maps to critical)
 * ```
 */
export declare function riskLevelFromNumber(n: number): RiskLevel;
/**
 * Converts a RiskLevel to its numeric value.
 *
 * @param level - RiskLevel to convert
 * @returns Numeric value (0-3)
 *
 * @example
 * ```typescript
 * riskLevelToNumber('low');      // 0
 * riskLevelToNumber('critical'); // 3
 * ```
 */
export declare function riskLevelToNumber(level: RiskLevel): number;
/**
 * Safely parses a value to RiskLevel.
 *
 * Handles various input formats:
 * - String values (case-insensitive)
 * - Numeric values (0-4)
 * - Enum-style uppercase strings
 *
 * @param value - Value to parse
 * @returns RiskLevel or null if unparseable
 *
 * @example
 * ```typescript
 * parseRiskLevel('LOW');     // 'low'
 * parseRiskLevel('MEDIUM');  // 'medium'
 * parseRiskLevel(2);         // 'high'
 * parseRiskLevel('invalid'); // null
 * ```
 */
export declare function parseRiskLevel(value: unknown): RiskLevel | null;
/**
 * Parses a value to RiskLevel with a default fallback.
 *
 * @param value - Value to parse
 * @param defaultLevel - Default level if parsing fails
 * @returns RiskLevel (parsed or default)
 *
 * @example
 * ```typescript
 * parseRiskLevelOrDefault('high', 'low');    // 'high'
 * parseRiskLevelOrDefault('invalid', 'low'); // 'low'
 * ```
 */
export declare function parseRiskLevelOrDefault(value: unknown, defaultLevel?: RiskLevel): RiskLevel;
/**
 * Compares two risk levels.
 *
 * @param a - First risk level
 * @param b - Second risk level
 * @returns -1 if a < b, 0 if equal, 1 if a > b
 *
 * @example
 * ```typescript
 * compareRiskLevels('low', 'high');     // -1
 * compareRiskLevels('high', 'medium');  // 1
 * compareRiskLevels('medium', 'medium'); // 0
 * ```
 */
export declare function compareRiskLevels(a: RiskLevel, b: RiskLevel): -1 | 0 | 1;
/**
 * Checks if a risk level is at least as severe as another.
 *
 * @param level - Level to check
 * @param threshold - Minimum threshold
 * @returns True if level meets or exceeds threshold
 *
 * @example
 * ```typescript
 * isRiskAtLeast('high', 'medium');     // true
 * isRiskAtLeast('low', 'medium');      // false
 * isRiskAtLeast('medium', 'medium');   // true
 * ```
 */
export declare function isRiskAtLeast(level: RiskLevel, threshold: RiskLevel): boolean;
/**
 * Checks if a risk level is more severe than another.
 *
 * @param level - Level to check
 * @param other - Level to compare against
 * @returns True if level is more severe than other
 *
 * @example
 * ```typescript
 * isRiskHigherThan('high', 'medium');   // true
 * isRiskHigherThan('medium', 'high');   // false
 * isRiskHigherThan('high', 'high');     // false
 * ```
 */
export declare function isRiskHigherThan(level: RiskLevel, other: RiskLevel): boolean;
/**
 * Gets the maximum (most severe) risk level from an array.
 *
 * @param levels - Array of risk levels
 * @returns Most severe risk level, or 'low' if array is empty
 *
 * @example
 * ```typescript
 * maxRiskLevel(['low', 'medium', 'high']); // 'high'
 * maxRiskLevel(['low', 'low']);            // 'low'
 * maxRiskLevel([]);                        // 'low'
 * ```
 */
export declare function maxRiskLevel(levels: RiskLevel[]): RiskLevel;
/**
 * Gets the minimum (least severe) risk level from an array.
 *
 * @param levels - Array of risk levels
 * @returns Least severe risk level, or 'critical' if array is empty
 *
 * @example
 * ```typescript
 * minRiskLevel(['low', 'medium', 'high']); // 'low'
 * minRiskLevel(['high', 'critical']);      // 'high'
 * ```
 */
export declare function minRiskLevel(levels: RiskLevel[]): RiskLevel;
/**
 * Escalates a risk level by one step (if possible).
 *
 * @param level - Current risk level
 * @returns Escalated risk level (or same if already critical)
 *
 * @example
 * ```typescript
 * escalateRiskLevel('low');      // 'medium'
 * escalateRiskLevel('high');     // 'critical'
 * escalateRiskLevel('critical'); // 'critical'
 * ```
 */
export declare function escalateRiskLevel(level: RiskLevel): RiskLevel;
/**
 * De-escalates a risk level by one step (if possible).
 *
 * @param level - Current risk level
 * @returns De-escalated risk level (or same if already low)
 *
 * @example
 * ```typescript
 * deescalateRiskLevel('critical'); // 'high'
 * deescalateRiskLevel('medium');   // 'low'
 * deescalateRiskLevel('low');      // 'low'
 * ```
 */
export declare function deescalateRiskLevel(level: RiskLevel): RiskLevel;
/**
 * Type guard to check if a value is a valid RiskLevel.
 *
 * @param value - Value to check
 * @returns True if value is a valid RiskLevel
 *
 * @example
 * ```typescript
 * isRiskLevel('high');    // true
 * isRiskLevel('severe');  // false
 * isRiskLevel(2);         // false
 * ```
 */
export declare function isRiskLevel(value: unknown): value is RiskLevel;
/**
 * Type guard to check if a risk level requires elevated attention.
 *
 * Returns true for 'high' and 'critical' levels.
 *
 * @param level - Risk level to check
 * @returns True if level requires elevated attention
 */
export declare function requiresElevatedAttention(level: RiskLevel): boolean;
/**
 * Type guard to check if a risk level is critical.
 *
 * @param level - Risk level to check
 * @returns True if level is critical
 */
export declare function isCriticalRisk(level: RiskLevel): boolean;
/**
 * Gets the human-readable label for a risk level.
 *
 * @param level - Risk level
 * @returns Human-readable label
 */
export declare function getRiskLevelLabel(level: RiskLevel): string;
/**
 * Gets the description for a risk level.
 *
 * @param level - Risk level
 * @returns Description string
 */
export declare function getRiskLevelDescription(level: RiskLevel): string;
/**
 * Gets the color code for a risk level.
 *
 * @param level - Risk level
 * @returns Hex color code
 */
export declare function getRiskLevelColor(level: RiskLevel): string;
/**
 * Zod schema for RiskLevel validation.
 *
 * Validates that a value is one of the canonical risk level strings.
 *
 * @example
 * ```typescript
 * riskLevelSchema.parse('medium'); // Success
 * riskLevelSchema.parse('severe'); // Throws ZodError
 * ```
 */
export declare const riskLevelSchema: z.ZodEnum<["low", "medium", "high", "critical"]>;
/**
 * Zod schema that accepts numeric input and transforms to RiskLevel.
 *
 * @example
 * ```typescript
 * riskLevelFromNumberSchema.parse(2); // 'high'
 * ```
 */
export declare const riskLevelFromNumberSchema: z.ZodEffects<z.ZodNumber, "low" | "medium" | "high" | "critical", number>;
/**
 * Zod schema that accepts string input (case-insensitive) and transforms to RiskLevel.
 *
 * @example
 * ```typescript
 * riskLevelFlexibleSchema.parse('HIGH'); // 'high'
 * riskLevelFlexibleSchema.parse('Medium'); // 'medium'
 * ```
 */
export declare const riskLevelFlexibleSchema: z.ZodPipeline<z.ZodEffects<z.ZodString, string, string>, z.ZodEnum<["low", "medium", "high", "critical"]>>;
/**
 * Zod schema that accepts multiple input formats and normalizes to RiskLevel.
 *
 * Accepts: lowercase strings, uppercase strings, numbers (0-4).
 */
export declare const riskLevelUnionSchema: z.ZodUnion<[z.ZodEnum<["low", "medium", "high", "critical"]>, z.ZodPipeline<z.ZodEffects<z.ZodString, string, string>, z.ZodEnum<["low", "medium", "high", "critical"]>>, z.ZodEffects<z.ZodNumber, "low" | "medium" | "high" | "critical", number>]>;
/**
 * Enum-style representation for compatibility with older code.
 *
 * @deprecated Use RiskLevel string type directly. This is for migration only.
 */
export declare const RiskLevelEnum: {
    readonly LOW: RiskLevel;
    readonly MEDIUM: RiskLevel;
    readonly HIGH: RiskLevel;
    readonly CRITICAL: RiskLevel;
};
/**
 * Maps legacy uppercase enum values to canonical RiskLevel.
 *
 * @deprecated Use RiskLevel string type directly. This is for migration only.
 */
export declare const LEGACY_RISK_LEVEL_MAP: Readonly<Record<string, RiskLevel>>;