/**
 * @fileoverview CAR Capability Levels (L0-L7)
 *
 * Defines the autonomy/capability levels used in CAR strings. Levels represent
 * what actions an agent is permitted to perform, ranging from read-only
 * observation (L0) to full autonomy (L7).
 *
 * The 8-tier system (L0-L7) maps to trust bands:
 * - L0: Observe - Read-only access (Sandbox tier)
 * - L1: Advise - Suggest and recommend (Observed tier)
 * - L2: Draft - Prepare changes for review (Provisional tier)
 * - L3: Execute - Execute with approval (Monitored tier)
 * - L4: Autonomous - Self-directed within bounds (Standard tier)
 * - L5: Trusted - Expanded autonomy (Trusted tier)
 * - L6: Certified - Independent operation (Certified tier)
 * - L7: Sovereign - Full autonomy (Autonomous tier)
 *
 * @module @vorionsys/contracts/car/levels
 */
import { z } from 'zod';
/**
 * Capability levels defining agent autonomy.
 *
 * Levels form a hierarchy where higher levels include the capabilities
 * of all lower levels:
 *
 * - L0: Read-only access, monitoring, observation
 * - L1: Can suggest and recommend, but not modify
 * - L2: Can prepare drafts and stage changes for review
 * - L3: Can execute operations with human approval
 * - L4: Self-directed operation within defined bounds
 * - L5: Expanded autonomy with minimal oversight
 * - L6: Independent operation with comprehensive audit trail
 * - L7: Full autonomy for mission-critical operations
 */
export declare enum CapabilityLevel {
    /** Read-only, monitoring - Can observe but not interact */
    L0_OBSERVE = 0,
    /** Advisory - Can suggest and recommend actions */
    L1_ADVISE = 1,
    /** Drafting - Can prepare changes for human review */
    L2_DRAFT = 2,
    /** Execute - Can execute with human approval */
    L3_EXECUTE = 3,
    /** Autonomous - Self-directed within bounds */
    L4_AUTONOMOUS = 4,
    /** Trusted - Expanded autonomy with minimal oversight */
    L5_TRUSTED = 5,
    /** Certified - Independent operation with audit trail */
    L6_CERTIFIED = 6,
    /** Autonomous - Full autonomy for mission-critical operations */
    L7_AUTONOMOUS = 7
}
/**
 * Array of all capability levels in ascending order.
 */
export declare const CAPABILITY_LEVELS: readonly [CapabilityLevel.L0_OBSERVE, CapabilityLevel.L1_ADVISE, CapabilityLevel.L2_DRAFT, CapabilityLevel.L3_EXECUTE, CapabilityLevel.L4_AUTONOMOUS, CapabilityLevel.L5_TRUSTED, CapabilityLevel.L6_CERTIFIED, CapabilityLevel.L7_AUTONOMOUS];
/**
 * Zod schema for CapabilityLevel enum validation.
 */
export declare const capabilityLevelSchema: z.ZodNativeEnum<typeof CapabilityLevel>;
/**
 * Human-readable names for capability levels.
 */
export declare const CAPABILITY_LEVEL_NAMES: Readonly<Record<CapabilityLevel, string>>;
/**
 * Short codes for capability levels (without the L prefix).
 */
export declare const CAPABILITY_LEVEL_CODES: Readonly<Record<CapabilityLevel, string>>;
/**
 * Detailed descriptions for each capability level.
 */
export declare const CAPABILITY_LEVEL_DESCRIPTIONS: Readonly<Record<CapabilityLevel, string>>;
/**
 * Capabilities granted at each level (cumulative).
 */
export declare const CAPABILITY_LEVEL_ABILITIES: Readonly<Record<CapabilityLevel, readonly string[]>>;
/**
 * Configuration for a capability level.
 */
export interface CapabilityLevelConfig {
    /** The capability level */
    readonly level: CapabilityLevel;
    /** Short code (L0-L7) */
    readonly code: string;
    /** Human-readable name */
    readonly name: string;
    /** Detailed description */
    readonly description: string;
    /** Abilities granted at this level */
    readonly abilities: readonly string[];
    /** Whether human approval is required for actions */
    readonly requiresApproval: boolean;
    /** Whether this level can operate autonomously */
    readonly canOperateAutonomously: boolean;
    /** Minimum certification tier typically required */
    readonly minCertificationTier: number;
}
/**
 * Complete configuration for all capability levels.
 */
export declare const CAPABILITY_LEVEL_CONFIGS: Readonly<Record<CapabilityLevel, CapabilityLevelConfig>>;
/**
 * Checks if one level is higher than another.
 *
 * @param level - The level to check
 * @param other - The level to compare against
 * @returns True if level is higher than other
 *
 * @example
 * ```typescript
 * isLevelHigher(CapabilityLevel.L3_EXECUTE, CapabilityLevel.L2_DRAFT);  // true
 * isLevelHigher(CapabilityLevel.L1_ADVISE, CapabilityLevel.L3_EXECUTE); // false
 * ```
 */
export declare function isLevelHigher(level: CapabilityLevel, other: CapabilityLevel): boolean;
/**
 * Checks if one level is at least as high as another.
 *
 * @param level - The level to check
 * @param minLevel - The minimum level required
 * @returns True if level meets or exceeds minLevel
 *
 * @example
 * ```typescript
 * meetsLevel(CapabilityLevel.L3_EXECUTE, CapabilityLevel.L2_DRAFT);     // true
 * meetsLevel(CapabilityLevel.L2_DRAFT, CapabilityLevel.L2_DRAFT);       // true
 * meetsLevel(CapabilityLevel.L1_ADVISE, CapabilityLevel.L3_EXECUTE);    // false
 * ```
 */
export declare function meetsLevel(level: CapabilityLevel, minLevel: CapabilityLevel): boolean;
/**
 * Compares two capability levels.
 *
 * @param a - First level
 * @param b - Second level
 * @returns -1 if a < b, 0 if equal, 1 if a > b
 */
export declare function compareLevels(a: CapabilityLevel, b: CapabilityLevel): -1 | 0 | 1;
/**
 * Gets the minimum of two capability levels.
 *
 * @param a - First level
 * @param b - Second level
 * @returns The lower level
 */
export declare function minLevel(a: CapabilityLevel, b: CapabilityLevel): CapabilityLevel;
/**
 * Gets the maximum of two capability levels.
 *
 * @param a - First level
 * @param b - Second level
 * @returns The higher level
 */
export declare function maxLevel(a: CapabilityLevel, b: CapabilityLevel): CapabilityLevel;
/**
 * Clamps a level to a range.
 *
 * @param level - The level to clamp
 * @param min - Minimum allowed level
 * @param max - Maximum allowed level
 * @returns The clamped level
 */
export declare function clampLevel(level: CapabilityLevel, min?: CapabilityLevel, max?: CapabilityLevel): CapabilityLevel;
/**
 * Gets the configuration for a capability level.
 *
 * @param level - The capability level
 * @returns Level configuration
 */
export declare function getLevelConfig(level: CapabilityLevel): CapabilityLevelConfig;
/**
 * Gets the human-readable name for a capability level.
 *
 * @param level - The capability level
 * @returns Level name
 */
export declare function getLevelName(level: CapabilityLevel): string;
/**
 * Gets the short code (L0-L7) for a capability level.
 *
 * @param level - The capability level
 * @returns Level code
 */
export declare function getLevelCode(level: CapabilityLevel): string;
/**
 * Gets the description for a capability level.
 *
 * @param level - The capability level
 * @returns Level description
 */
export declare function getLevelDescription(level: CapabilityLevel): string;
/**
 * Checks if a level has a specific ability.
 *
 * @param level - The capability level
 * @param ability - The ability to check
 * @returns True if the level grants this ability
 */
export declare function hasAbility(level: CapabilityLevel, ability: string): boolean;
/**
 * Checks if a level requires approval for actions.
 *
 * @param level - The capability level
 * @returns True if approval is required
 */
export declare function requiresApproval(level: CapabilityLevel): boolean;
/**
 * Checks if a level can operate autonomously.
 *
 * @param level - The capability level
 * @returns True if autonomous operation is allowed
 */
export declare function canOperateAutonomously(level: CapabilityLevel): boolean;
/**
 * Parses a level string (e.g., "L3" or "3") to a CapabilityLevel.
 *
 * @param levelStr - Level string to parse
 * @returns Parsed CapabilityLevel
 * @throws Error if the string is not a valid level
 *
 * @example
 * ```typescript
 * parseLevel('L3');  // CapabilityLevel.L3_EXECUTE
 * parseLevel('3');   // CapabilityLevel.L3_EXECUTE
 * parseLevel('L0');  // CapabilityLevel.L0_OBSERVE
 * ```
 */
export declare function parseLevel(levelStr: string): CapabilityLevel;
/**
 * Safely parses a level string, returning null on failure.
 *
 * @param levelStr - Level string to parse
 * @returns Parsed CapabilityLevel or null
 */
export declare function tryParseLevel(levelStr: string): CapabilityLevel | null;
/**
 * Type guard to check if a value is a valid CapabilityLevel.
 *
 * @param value - Value to check
 * @returns True if value is a valid CapabilityLevel
 */
export declare function isCapabilityLevel(value: unknown): value is CapabilityLevel;
/**
 * Zod schema for level configuration.
 */
export declare const capabilityLevelConfigSchema: z.ZodObject<{
    level: z.ZodNativeEnum<typeof CapabilityLevel>;
    code: z.ZodString;
    name: z.ZodString;
    description: z.ZodString;
    abilities: z.ZodReadonly<z.ZodArray<z.ZodString, "many">>;
    requiresApproval: z.ZodBoolean;
    canOperateAutonomously: z.ZodBoolean;
    minCertificationTier: z.ZodNumber;
}, "strip", z.ZodTypeAny, {
    name: string;
    code: string;
    description: string;
    level: CapabilityLevel;
    requiresApproval: boolean;
    abilities: readonly string[];
    canOperateAutonomously: boolean;
    minCertificationTier: number;
}, {
    name: string;
    code: string;
    description: string;
    level: CapabilityLevel;
    requiresApproval: boolean;
    abilities: readonly string[];
    canOperateAutonomously: boolean;
    minCertificationTier: number;
}>;
/**
 * Zod schema for parsing level strings.
 */
export declare const levelStringSchema: z.ZodEffects<z.ZodString, CapabilityLevel, string>;