/**
 * @fileoverview Effective Permission Calculation
 *
 * Provides types and functions for calculating effective permissions based on
 * multiple inputs including certification tier, competence level, runtime tier,
 * observability ceiling, and context policy ceiling.
 *
 * The effective permission is the minimum of all applicable ceilings, ensuring
 * that agents can never exceed the most restrictive constraint in any dimension.
 *
 * @module @vorionsys/contracts/car/effective-permission
 */
import { z } from 'zod';
import { CapabilityLevel } from './levels.js';
import { CertificationTier, RuntimeTier } from './tiers.js';
/**
 * Supervision elevation for effective permission calculation.
 *
 * When an agent operates under a higher-tier supervisor, it can be
 * granted temporary tier elevation of up to +2 tiers above its base
 * certification tier. The effective elevation is always capped at
 * (supervisorTier - 1) and T7_AUTONOMOUS.
 */
export interface SupervisionElevation {
    /** Certification tier of the supervisor */
    supervisorTier: CertificationTier;
    /** Number of elevation tiers granted (0 to MAX_SUPERVISION_ELEVATION) */
    grantedElevation: number;
}
/**
 * Zod schema for SupervisionElevation.
 */
export declare const supervisionElevationSchema: z.ZodObject<{
    supervisorTier: z.ZodNativeEnum<typeof CertificationTier>;
    grantedElevation: z.ZodNumber;
}, "strip", z.ZodTypeAny, {
    supervisorTier: CertificationTier;
    grantedElevation: number;
}, {
    supervisorTier: CertificationTier;
    grantedElevation: number;
}>;
/**
 * Context for calculating effective permissions.
 *
 * This combines all factors that influence what an agent is permitted to do:
 * - certificationTier: External attestation status
 * - competenceLevel: Agent's declared capability level
 * - runtimeTier: Deployment-specific autonomy level
 * - observabilityCeiling: Maximum level based on observability requirements
 * - contextPolicyCeiling: Maximum level based on current context policy
 * - supervisionElevation: Optional tier boost from supervisor (max +2)
 */
export interface EffectivePermissionContext {
    /** CAR ID certification tier (external attestation status) */
    certificationTier: CertificationTier;
    /** Agent's competence/capability level */
    competenceLevel: CapabilityLevel;
    /** Vorion runtime tier (deployment autonomy) */
    runtimeTier: RuntimeTier;
    /** Maximum level based on observability requirements (0-7) */
    observabilityCeiling: number;
    /** Maximum level based on context policy (0-7) */
    contextPolicyCeiling: number;
    /** Optional supervision elevation (can raise effective tier by up to +2) */
    supervisionElevation?: SupervisionElevation;
}
/**
 * Zod schema for EffectivePermissionContext.
 */
export declare const effectivePermissionContextSchema: z.ZodObject<{
    certificationTier: z.ZodNativeEnum<typeof CertificationTier>;
    competenceLevel: z.ZodNativeEnum<typeof CapabilityLevel>;
    runtimeTier: z.ZodNativeEnum<typeof RuntimeTier>;
    observabilityCeiling: z.ZodNumber;
    contextPolicyCeiling: z.ZodNumber;
    supervisionElevation: z.ZodOptional<z.ZodObject<{
        supervisorTier: z.ZodNativeEnum<typeof CertificationTier>;
        grantedElevation: z.ZodNumber;
    }, "strip", z.ZodTypeAny, {
        supervisorTier: CertificationTier;
        grantedElevation: number;
    }, {
        supervisorTier: CertificationTier;
        grantedElevation: number;
    }>>;
}, "strip", z.ZodTypeAny, {
    certificationTier: CertificationTier;
    runtimeTier: RuntimeTier;
    competenceLevel: CapabilityLevel;
    observabilityCeiling: number;
    contextPolicyCeiling: number;
    supervisionElevation?: {
        supervisorTier: CertificationTier;
        grantedElevation: number;
    } | undefined;
}, {
    certificationTier: CertificationTier;
    runtimeTier: RuntimeTier;
    competenceLevel: CapabilityLevel;
    observabilityCeiling: number;
    contextPolicyCeiling: number;
    supervisionElevation?: {
        supervisorTier: CertificationTier;
        grantedElevation: number;
    } | undefined;
}>;
/**
 * Result of effective permission calculation.
 */
export interface EffectivePermission {
    /** The effective permission level (minimum of all ceilings) */
    level: CapabilityLevel;
    /** Whether the effective level was constrained */
    constrained: boolean;
    /** The factor that caused the constraint (if constrained) */
    constrainingFactor?: ConstrainingFactor;
    /** Details about each ceiling that was applied */
    ceilings: PermissionCeilings;
    /** Recommendations for increasing effective permission */
    recommendations?: string[];
}
/**
 * Factors that can constrain effective permission.
 */
export type ConstrainingFactor = 'certification_tier' | 'competence_level' | 'runtime_tier' | 'observability_ceiling' | 'context_policy_ceiling' | 'supervision_elevation' | 'multiple';
/**
 * Individual ceiling values applied to permission calculation.
 */
export interface PermissionCeilings {
    /** Ceiling from certification tier */
    certificationCeiling: CapabilityLevel;
    /** Ceiling from competence level */
    competenceCeiling: CapabilityLevel;
    /** Ceiling from runtime tier */
    runtimeCeiling: CapabilityLevel;
    /** Ceiling from observability requirements */
    observabilityCeiling: CapabilityLevel;
    /** Ceiling from context policy */
    contextPolicyCeiling: CapabilityLevel;
}
/**
 * Zod schema for ConstrainingFactor.
 */
export declare const constrainingFactorSchema: z.ZodEnum<["certification_tier", "competence_level", "runtime_tier", "observability_ceiling", "context_policy_ceiling", "supervision_elevation", "multiple"]>;
/**
 * Zod schema for PermissionCeilings.
 */
export declare const permissionCeilingsSchema: z.ZodObject<{
    certificationCeiling: z.ZodNativeEnum<typeof CapabilityLevel>;
    competenceCeiling: z.ZodNativeEnum<typeof CapabilityLevel>;
    runtimeCeiling: z.ZodNativeEnum<typeof CapabilityLevel>;
    observabilityCeiling: z.ZodNativeEnum<typeof CapabilityLevel>;
    contextPolicyCeiling: z.ZodNativeEnum<typeof CapabilityLevel>;
}, "strip", z.ZodTypeAny, {
    observabilityCeiling: CapabilityLevel;
    contextPolicyCeiling: CapabilityLevel;
    certificationCeiling: CapabilityLevel;
    competenceCeiling: CapabilityLevel;
    runtimeCeiling: CapabilityLevel;
}, {
    observabilityCeiling: CapabilityLevel;
    contextPolicyCeiling: CapabilityLevel;
    certificationCeiling: CapabilityLevel;
    competenceCeiling: CapabilityLevel;
    runtimeCeiling: CapabilityLevel;
}>;
/**
 * Zod schema for EffectivePermission.
 */
export declare const effectivePermissionSchema: z.ZodObject<{
    level: z.ZodNativeEnum<typeof CapabilityLevel>;
    constrained: z.ZodBoolean;
    constrainingFactor: z.ZodOptional<z.ZodEnum<["certification_tier", "competence_level", "runtime_tier", "observability_ceiling", "context_policy_ceiling", "supervision_elevation", "multiple"]>>;
    ceilings: z.ZodObject<{
        certificationCeiling: z.ZodNativeEnum<typeof CapabilityLevel>;
        competenceCeiling: z.ZodNativeEnum<typeof CapabilityLevel>;
        runtimeCeiling: z.ZodNativeEnum<typeof CapabilityLevel>;
        observabilityCeiling: z.ZodNativeEnum<typeof CapabilityLevel>;
        contextPolicyCeiling: z.ZodNativeEnum<typeof CapabilityLevel>;
    }, "strip", z.ZodTypeAny, {
        observabilityCeiling: CapabilityLevel;
        contextPolicyCeiling: CapabilityLevel;
        certificationCeiling: CapabilityLevel;
        competenceCeiling: CapabilityLevel;
        runtimeCeiling: CapabilityLevel;
    }, {
        observabilityCeiling: CapabilityLevel;
        contextPolicyCeiling: CapabilityLevel;
        certificationCeiling: CapabilityLevel;
        competenceCeiling: CapabilityLevel;
        runtimeCeiling: CapabilityLevel;
    }>;
    recommendations: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
}, "strip", z.ZodTypeAny, {
    level: CapabilityLevel;
    constrained: boolean;
    ceilings: {
        observabilityCeiling: CapabilityLevel;
        contextPolicyCeiling: CapabilityLevel;
        certificationCeiling: CapabilityLevel;
        competenceCeiling: CapabilityLevel;
        runtimeCeiling: CapabilityLevel;
    };
    constrainingFactor?: "certification_tier" | "competence_level" | "runtime_tier" | "observability_ceiling" | "context_policy_ceiling" | "supervision_elevation" | "multiple" | undefined;
    recommendations?: string[] | undefined;
}, {
    level: CapabilityLevel;
    constrained: boolean;
    ceilings: {
        observabilityCeiling: CapabilityLevel;
        contextPolicyCeiling: CapabilityLevel;
        certificationCeiling: CapabilityLevel;
        competenceCeiling: CapabilityLevel;
        runtimeCeiling: CapabilityLevel;
    };
    constrainingFactor?: "certification_tier" | "competence_level" | "runtime_tier" | "observability_ceiling" | "context_policy_ceiling" | "supervision_elevation" | "multiple" | undefined;
    recommendations?: string[] | undefined;
}>;
/**
 * Calculates the effective permission from the context.
 *
 * The effective permission is the minimum of all applicable ceilings:
 * - Certification tier ceiling
 * - Competence level (agent's declared capability)
 * - Runtime tier ceiling
 * - Observability ceiling
 * - Context policy ceiling
 *
 * @param ctx - Permission context
 * @returns Effective permission result
 *
 * @example
 * ```typescript
 * const result = calculateEffectivePermission({
 *   certificationTier: CertificationTier.T3_MONITORED,
 *   competenceLevel: CapabilityLevel.L4_STANDARD,
 *   runtimeTier: RuntimeTier.T3_MONITORED,
 *   observabilityCeiling: 4,
 *   contextPolicyCeiling: 3,
 * });
 * // result.level === CapabilityLevel.L3_EXECUTE
 * // result.constrained === true
 * // result.constrainingFactor === 'context_policy_ceiling'
 * ```
 */
export declare function calculateEffectivePermission(ctx: EffectivePermissionContext): EffectivePermission;
/**
 * Checks if an effective permission allows a specific capability level.
 *
 * @param permission - Effective permission
 * @param requiredLevel - Required capability level
 * @returns True if the permission allows the required level
 */
export declare function permissionAllowsLevel(permission: EffectivePermission, requiredLevel: CapabilityLevel): boolean;
/**
 * Checks if a context allows a specific capability level.
 *
 * @param ctx - Permission context
 * @param requiredLevel - Required capability level
 * @returns True if the context allows the required level
 */
export declare function contextAllowsLevel(ctx: EffectivePermissionContext, requiredLevel: CapabilityLevel): boolean;
/**
 * Result of a permission check with detailed information.
 */
export interface PermissionCheckResult {
    /** Whether the requested level is allowed */
    allowed: boolean;
    /** The effective permission level */
    effectiveLevel: CapabilityLevel;
    /** The requested level */
    requestedLevel: CapabilityLevel;
    /** Gap between requested and effective (0 if allowed) */
    levelGap: number;
    /** Full effective permission details */
    permission: EffectivePermission;
}
/**
 * Performs a detailed permission check.
 *
 * @param ctx - Permission context
 * @param requiredLevel - Required capability level
 * @returns Detailed permission check result
 */
export declare function checkPermission(ctx: EffectivePermissionContext, requiredLevel: CapabilityLevel): PermissionCheckResult;
/**
 * Zod schema for PermissionCheckResult.
 */
export declare const permissionCheckResultSchema: z.ZodObject<{
    allowed: z.ZodBoolean;
    effectiveLevel: z.ZodNativeEnum<typeof CapabilityLevel>;
    requestedLevel: z.ZodNativeEnum<typeof CapabilityLevel>;
    levelGap: z.ZodNumber;
    permission: z.ZodObject<{
        level: z.ZodNativeEnum<typeof CapabilityLevel>;
        constrained: z.ZodBoolean;
        constrainingFactor: z.ZodOptional<z.ZodEnum<["certification_tier", "competence_level", "runtime_tier", "observability_ceiling", "context_policy_ceiling", "supervision_elevation", "multiple"]>>;
        ceilings: z.ZodObject<{
            certificationCeiling: z.ZodNativeEnum<typeof CapabilityLevel>;
            competenceCeiling: z.ZodNativeEnum<typeof CapabilityLevel>;
            runtimeCeiling: z.ZodNativeEnum<typeof CapabilityLevel>;
            observabilityCeiling: z.ZodNativeEnum<typeof CapabilityLevel>;
            contextPolicyCeiling: z.ZodNativeEnum<typeof CapabilityLevel>;
        }, "strip", z.ZodTypeAny, {
            observabilityCeiling: CapabilityLevel;
            contextPolicyCeiling: CapabilityLevel;
            certificationCeiling: CapabilityLevel;
            competenceCeiling: CapabilityLevel;
            runtimeCeiling: CapabilityLevel;
        }, {
            observabilityCeiling: CapabilityLevel;
            contextPolicyCeiling: CapabilityLevel;
            certificationCeiling: CapabilityLevel;
            competenceCeiling: CapabilityLevel;
            runtimeCeiling: CapabilityLevel;
        }>;
        recommendations: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
    }, "strip", z.ZodTypeAny, {
        level: CapabilityLevel;
        constrained: boolean;
        ceilings: {
            observabilityCeiling: CapabilityLevel;
            contextPolicyCeiling: CapabilityLevel;
            certificationCeiling: CapabilityLevel;
            competenceCeiling: CapabilityLevel;
            runtimeCeiling: CapabilityLevel;
        };
        constrainingFactor?: "certification_tier" | "competence_level" | "runtime_tier" | "observability_ceiling" | "context_policy_ceiling" | "supervision_elevation" | "multiple" | undefined;
        recommendations?: string[] | undefined;
    }, {
        level: CapabilityLevel;
        constrained: boolean;
        ceilings: {
            observabilityCeiling: CapabilityLevel;
            contextPolicyCeiling: CapabilityLevel;
            certificationCeiling: CapabilityLevel;
            competenceCeiling: CapabilityLevel;
            runtimeCeiling: CapabilityLevel;
        };
        constrainingFactor?: "certification_tier" | "competence_level" | "runtime_tier" | "observability_ceiling" | "context_policy_ceiling" | "supervision_elevation" | "multiple" | undefined;
        recommendations?: string[] | undefined;
    }>;
}, "strip", z.ZodTypeAny, {
    allowed: boolean;
    permission: {
        level: CapabilityLevel;
        constrained: boolean;
        ceilings: {
            observabilityCeiling: CapabilityLevel;
            contextPolicyCeiling: CapabilityLevel;
            certificationCeiling: CapabilityLevel;
            competenceCeiling: CapabilityLevel;
            runtimeCeiling: CapabilityLevel;
        };
        constrainingFactor?: "certification_tier" | "competence_level" | "runtime_tier" | "observability_ceiling" | "context_policy_ceiling" | "supervision_elevation" | "multiple" | undefined;
        recommendations?: string[] | undefined;
    };
    effectiveLevel: CapabilityLevel;
    requestedLevel: CapabilityLevel;
    levelGap: number;
}, {
    allowed: boolean;
    permission: {
        level: CapabilityLevel;
        constrained: boolean;
        ceilings: {
            observabilityCeiling: CapabilityLevel;
            contextPolicyCeiling: CapabilityLevel;
            certificationCeiling: CapabilityLevel;
            competenceCeiling: CapabilityLevel;
            runtimeCeiling: CapabilityLevel;
        };
        constrainingFactor?: "certification_tier" | "competence_level" | "runtime_tier" | "observability_ceiling" | "context_policy_ceiling" | "supervision_elevation" | "multiple" | undefined;
        recommendations?: string[] | undefined;
    };
    effectiveLevel: CapabilityLevel;
    requestedLevel: CapabilityLevel;
    levelGap: number;
}>;
/**
 * Creates a new context with a modified ceiling.
 *
 * @param ctx - Original context
 * @param factor - Factor to modify
 * @param newValue - New value for the factor
 * @returns New context with modified value
 */
export declare function modifyContextCeiling(ctx: EffectivePermissionContext, factor: Exclude<ConstrainingFactor, 'multiple'>, newValue: number): EffectivePermissionContext;
/**
 * Calculates what context changes would be needed to achieve a target level.
 *
 * @param ctx - Current context
 * @param targetLevel - Desired capability level
 * @returns Map of factors to required values
 */
export declare function calculateRequiredChanges(ctx: EffectivePermissionContext, targetLevel: CapabilityLevel): Map<Exclude<ConstrainingFactor, 'multiple'>, number>;
/**
 * Creates a default permission context.
 *
 * @param overrides - Optional overrides
 * @returns Default context with any overrides applied
 */
export declare function createDefaultContext(overrides?: Partial<EffectivePermissionContext>): EffectivePermissionContext;
/**
 * Creates a maximally permissive context.
 *
 * @returns Context with all ceilings at maximum
 */
export declare function createMaxPermissionContext(): EffectivePermissionContext;
/**
 * Type guard for EffectivePermissionContext.
 */
export declare function isEffectivePermissionContext(value: unknown): value is EffectivePermissionContext;
/**
 * Type guard for EffectivePermission.
 */
export declare function isEffectivePermission(value: unknown): value is EffectivePermission;