@dcyfr/ai 1.0.4 → 2.1.0

package/dist/ai/src/delegation/liability-firebreak.d.ts

@@ -0,0 +1,303 @@
+/**
+ * Liability Firebreak Enforcement for DCYFR Delegation Framework
+ * TLP:AMBER - Internal Use Only
+ *
+ * Implements accountability boundaries in delegation chains to prevent
+ * unlimited delegation and ensure clear liability assignment. Includes
+ * manual override capabilities and escalation procedures.
+ *
+ * Key accountability mechanisms:
+ * - Delegation chain depth limits with liability boundaries
+ * - Responsibility tracking through chain hierarchy
+ * - Manual override and emergency escalation procedures
+ * - Liability assignment and audit trail maintenance
+ *
+ * @module delegation/liability-firebreak
+ * @version 1.0.0
+ * @date 2026-02-14
+ */
+import type { DelegationContract } from '../types/delegation-contracts.js';
+/**
+ * Liability assignment levels for delegation chains
+ */
+export type LiabilityLevel = 'full' | 'shared' | 'limited' | 'none';
+/**
+ * Firebreak enforcement actions
+ */
+export type FirebreakAction = 'allow' | 'require_approval' | 'escalate' | 'block' | 'terminate_chain';
+/**
+ * Override authority levels
+ */
+export type OverrideAuthority = 'agent' | 'supervisor' | 'manager' | 'executive' | 'emergency';
+/**
+ * Liability firebreak validation result
+ */
+export interface FirebreakResult {
+    /** Whether all firebreaks passed */
+    firebreaks_passed: boolean;
+    /** List of blocking firebreak violations */
+    blocking_firebreaks: string[];
+    /** Assigned liability level for this delegation */
+    liability_level: LiabilityLevel;
+    /** Length of delegation chain */
+    chain_length: number;
+    /** Whether manual override is available */
+    manual_override_available: boolean;
+    /** Required authority level for override */
+    required_authority: OverrideAuthority;
+    /** Validation timestamp */
+    validation_timestamp: string;
+    /** Whether firebreak enforcement allows the delegation */
+    allowed?: boolean;
+    /** Action to take based on firebreak rules */
+    action?: FirebreakAction;
+    /** Reason for the firebreak decision */
+    reason?: string;
+    /** Chain accountability information */
+    chain_accountability?: {
+        /** Current chain depth */
+        depth: number;
+        /** Maximum allowed depth */
+        max_depth: number;
+        /** Chain liability distribution */
+        liability_distribution: Array<{
+            agent_id: string;
+            liability_level: LiabilityLevel;
+            scope: string[];
+        }>;
+        /** Accountability boundaries hit */
+        boundaries_hit: string[];
+    };
+    /** Escalation path if required */
+    escalation_path?: Array<{
+        level: OverrideAuthority;
+        required_clearance?: string;
+        contact_method?: string;
+    }>;
+}
+/**
+ * Context for firebreak validation
+ */
+export interface FirebreakValidationContext {
+    /** Current depth in delegation chain */
+    delegation_depth: number;
+    /** Estimated financial or operational value */
+    estimated_value: number;
+    /** Whether delegation involves critical systems */
+    involves_critical_systems: boolean;
+    /** Whether delegating to external entity */
+    is_external_delegation: boolean;
+    /** Chain of agents in delegation path */
+    chain_agents: string[];
+}
+/**
+ * Manual override request
+ */
+export interface OverrideRequest {
+    /** Override request ID */
+    override_id?: string;
+    /** Authority level of the override */
+    authority?: OverrideAuthority;
+    authority_level?: OverrideAuthority;
+    /** Agent requesting the override */
+    requesting_agent_id?: string;
+    requesting_agent?: string;
+    /** Target agent being delegated to */
+    target_agent?: string;
+    /** Contract being overridden */
+    contract_id?: string;
+    /** Justification for the override */
+    justification?: string;
+    reason?: string;
+    /** Context for the delegation being overridden */
+    context?: FirebreakValidationContext;
+    /** Business impact if override is denied */
+    business_impact?: 'low' | 'medium' | 'high' | 'critical';
+    /** Time-sensitive nature */
+    urgency?: 'routine' | 'urgent' | 'emergency';
+    /** Approval status */
+    status?: 'pending' | 'approved' | 'denied' | 'rejected' | 'expired';
+    /** Expiration timestamp */
+    expires_at?: string;
+    /** Creation timestamp */
+    created_at?: string;
+    /** Approved by (if approved) */
+    approved_by?: string;
+    /** Approval timestamp */
+    approved_at?: string;
+}
+/**
+ * Escalation procedure configuration
+ */
+interface EscalationConfig {
+    /** Chain depth thresholds for escalation */
+    depth_thresholds: {
+        supervisor: number;
+        manager: number;
+        executive: number;
+    };
+    /** Liability threshold enforcement */
+    liability_thresholds: {
+        high_value_limit: number;
+        critical_system_approval: boolean;
+        external_delegation_approval: boolean;
+    };
+    /** Emergency procedures */
+    emergency_procedures: {
+        max_emergency_depth: number;
+        emergency_contacts: Array<{
+            authority: OverrideAuthority;
+            contact_id: string;
+            response_time_sla_minutes: number;
+        }>;
+    };
+}
+/**
+ * Liability Firebreak Enforcement Engine
+ */
+export declare class LiabilityFirebreakEnforcer {
+    private config;
+    private overrideRequests;
+    private chainAccountability;
+    private stats;
+    constructor(config?: Partial<EscalationConfig>);
+    /**
+     * Enforce liability firebreaks for delegation
+     */
+    enforceFirebreaks(primaryAgent: string, secondaryAgent: string, context: FirebreakValidationContext): FirebreakResult;
+    /**
+     * Assign liability level based on delegation context
+     */
+    private assignLiabilityLevel;
+    /**
+     * Check depth limits
+     */
+    private checkDepthLimits;
+    /**
+     * Get required authority for given depth
+     */
+    private getAuthorityForDepth;
+    /**
+     * Escalate authority level
+     */
+    private escalateAuthority;
+    /**
+     * Process emergency escalation
+     */
+    processEmergencyEscalation(escalationData: any): Promise<any>;
+    /**
+     * Get pending override requests
+     */
+    /**
+     * Calculate chain accountability and tracking
+     */
+    private calculateChainAccountability;
+    /**
+     * Check depth-based firebreaks
+     */
+    private checkDepthFirebreaks;
+    /**
+     * Check liability-based firebreaks
+     */
+    private checkLiabilityFirebreaks;
+    /**
+     * Check for active manual overrides
+     */
+    private checkActiveOverrides;
+    /**
+     * Get scope for agent in contract context
+     */
+    private getScopeForAgent;
+    /**
+     * Build escalation path for required authority
+     */
+    private buildEscalationPath;
+    /**
+     * Request manual override for blocked delegation
+     */
+    /** Normalize positional or object-based requestOverride params into a canonical shape */
+    private normalizeOverrideParams;
+    /** Determine required override authority based on delegation context */
+    private determineRequiredAuthority;
+    requestOverride(contractIdOrRequest: string | {
+        requesting_agent?: string;
+        requesting_agent_id?: string;
+        target_agent?: string;
+        authority_level?: OverrideAuthority;
+        authority?: OverrideAuthority;
+        reason?: string;
+        justification?: string;
+        context?: FirebreakValidationContext;
+        expires_at?: string;
+        business_impact?: OverrideRequest['business_impact'];
+        urgency?: OverrideRequest['urgency'];
+        contract_id?: string;
+    }, requesting_agent_id?: string, authority?: OverrideAuthority, justification?: string, business_impact?: OverrideRequest['business_impact'], urgency?: OverrideRequest['urgency']): Promise<OverrideRequest & {
+        rejection_reason?: string;
+        required_approvals?: string[];
+        auto_approved?: boolean;
+    }>;
+    /**
+     * Approve manual override
+     */
+    approveOverride(override_id: string, approving_authority: string, approver_clearance: OverrideAuthority): Promise<OverrideRequest>;
+    /**
+     * Emergency escalation bypass (highest authority override)
+     */
+    emergencyEscalation(contract_id: string, emergency_contact: string, justification: string): Promise<OverrideRequest>;
+    /**
+     * Get liability firebreak statistics
+     */
+    getFirebreakStatistics(): {
+        total_evaluations: number;
+        blocked_delegations: number;
+        escalations_required: number;
+        overrides_requested: number;
+        overrides_approved: number;
+        chain_depth_violations: number;
+        liability_threshold_violations: number;
+    };
+    /**
+     * Get pending override requests
+     */
+    getPendingOverrides(): OverrideRequest[];
+    /**
+     * Update chain accountability tracking
+     */
+    updateChainAccountability(chain_id: string, agent_id: string, liability_level: LiabilityLevel, depth: number): void;
+    /**
+     * Clean up expired override requests
+     */
+    cleanupExpiredOverrides(): number;
+    /**
+     * Evaluate a contract for firebreak requirements
+     * Wrapper method for test compatibility - converts contract to context and calls enforceFirebreaks
+     */
+    evaluateContract(contract: DelegationContract | any): {
+        requires_firebreak: boolean;
+        risk_level?: string;
+        firebreak_conditions?: string[];
+        reason?: string;
+    };
+    /**
+     * Get firebreak enforcement statistics
+     */
+    getStats(): {
+        total_validations: number;
+        firebreaks_passed: number;
+        firebreaks_blocked: number;
+        block_reasons: Record<string, number>;
+        block_reason_distribution: Record<string, number>;
+        liability_distribution: Record<LiabilityLevel, number>;
+        pending_overrides: number;
+        override_requests_summary: {
+            total: number;
+            pending: number;
+            approved: number;
+            rejected: number;
+            expired: number;
+        };
+    };
+}
+export {};
+//# sourceMappingURL=liability-firebreak.d.ts.map

package/dist/ai/src/delegation/liability-firebreak.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"liability-firebreak.d.ts","sourceRoot":"","sources":["../../../../packages/ai/src/delegation/liability-firebreak.ts"],"names":[],"mappings":"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"}