@sovr/engine 3.5.0 → 3.6.0

package/dist/index.d.ts

@@ -1870,6 +1870,419 @@ declare class ContextAccelerator {
     private evictLRU;
 }
 
+/**
+ * trendAlertEngine.ts — 趋势触发告警与 Kill-Switch 对接引擎
+ *
+ * 覆盖 PDF5: 人工智能痛点执行方案(1) — 趋势触发告警与 Kill-Switch 对接
+ *
+ * 核心能力:
+ * - Block Rate 突增检测: 拦截率相对基线大幅上升
+ * - Override Rate 突增检测: 人工强制通过率飙升
+ * - 未知原因码检测: 出现未定义的 reason_code
+ * - 人工审批队列积压检测: 审核队列任务大量堆积
+ * - 自动降级 (Degrade): 进入降级模式
+ * - 自动提高门槛: 提升安全阈值
+ * - 触发 Kill-Switch: 全局紧急停止
+ * - 告警事件持久化: 写入 sovr_system_events
+ * - DegradeEvaluator Cron: 定时评估趋势
+ */
+type AlertSeverity = 'INFO' | 'WARN' | 'CRITICAL' | 'EMERGENCY';
+type AlertType = 'BLOCK_RATE_SURGE' | 'OVERRIDE_RATE_SURGE' | 'UNKNOWN_REASON_CODE' | 'APPROVAL_QUEUE_BACKLOG' | 'CONFIDENCE_DROP' | 'LATENCY_SPIKE' | 'ERROR_RATE_SURGE';
+type ProtectiveAction = 'DEGRADE' | 'TIGHTEN_THRESHOLD' | 'KILL_SWITCH' | 'NOTIFY_ONLY' | 'FORCE_HUMAN_GATE';
+interface AlertThreshold {
+    alert_type: AlertType;
+    metric_name: string;
+    baseline_window_hours: number;
+    surge_multiplier: number;
+    absolute_threshold: number;
+    severity: AlertSeverity;
+    protective_actions: ProtectiveAction[];
+    cooldown_seconds: number;
+    enabled: boolean;
+}
+interface TrendMetric {
+    metric_name: string;
+    current_value: number;
+    baseline_value: number;
+    window_start: number;
+    window_end: number;
+    sample_count: number;
+}
+interface AlertEvent {
+    alert_id: string;
+    alert_type: AlertType;
+    severity: AlertSeverity;
+    metric_name: string;
+    current_value: number;
+    baseline_value: number;
+    threshold_value: number;
+    surge_ratio: number;
+    protective_actions_taken: ProtectiveAction[];
+    message: string;
+    tenant_id: string;
+    created_at: number;
+    acknowledged: boolean;
+    acknowledged_by: string | null;
+    acknowledged_at: number | null;
+}
+interface KillSwitchState {
+    enabled: boolean;
+    reason: string | null;
+    enabled_at: number | null;
+    enabled_by: string;
+    auto_triggered: boolean;
+}
+interface DegradeState {
+    active: boolean;
+    level: 'LIGHT' | 'MODERATE' | 'SEVERE';
+    reason: string;
+    activated_at: number | null;
+    auto_recover_at: number | null;
+}
+interface SystemState {
+    kill_switch: KillSwitchState;
+    degrade: DegradeState;
+    tightened_threshold_multiplier: number;
+    force_human_gate: boolean;
+}
+declare class TrendAlertEngine {
+    private thresholds;
+    private alertHistory;
+    private lastAlertTime;
+    private systemState;
+    private metricsBuffer;
+    constructor(customThresholds?: AlertThreshold[]);
+    evaluate(metrics: TrendMetric[], tenantId?: string): AlertEvent[];
+    cronEvaluate(getMetrics: () => TrendMetric[], tenantId?: string): {
+        alerts: AlertEvent[];
+        state: SystemState;
+    };
+    private executeProtectiveAction;
+    private activateDegrade;
+    private tightenThreshold;
+    private activateKillSwitch;
+    private checkThreshold;
+    private checkAutoRecover;
+    acknowledgeAlert(alertId: string, acknowledgedBy: string): boolean;
+    disableKillSwitch(reason: string, actor: string): boolean;
+    resetDegrade(): void;
+    getSystemState(): SystemState;
+    getAlertHistory(limit?: number): AlertEvent[];
+    getActiveAlerts(): AlertEvent[];
+    getMetricsBuffer(): TrendMetric[];
+    private formatAlertMessage;
+}
+
+/**
+ * selfConstraintEngine.ts — 自我约束机制引擎
+ *
+ * 覆盖 PDF10: 人工智能痛点自我约束机制实施计划
+ *
+ * 核心能力:
+ * - 风险密度监测: 持续跟踪风险密度指标
+ * - 规则冲突率监测: 检测规则之间的冲突
+ * - 决策置信度监测: 跟踪决策置信度下降趋势
+ * - Auto Tightening Thresholds: 自动收紧阈值
+ * - Capability Downgrade Flags: 功能降级标志
+ * - Forced Human Gate: 强制人工门禁
+ * - tightening_thresholds 配置: 可配置化阈值策略
+ * - capability_flags 配置: 功能开关控制
+ *
+ * 三种退让模式:
+ * 1. 降低能力 — 自动缩小可执行操作范围
+ * 2. 降低速度 — 延后决策等待更多证据
+ * 3. 降低权限 — 交由人工介入
+ */
+type ConstraintMode = 'CAPABILITY_DOWN' | 'SPEED_DOWN' | 'PERMISSION_DOWN';
+type ConstraintLevel = 'NORMAL' | 'CAUTIOUS' | 'RESTRICTED' | 'LOCKDOWN';
+interface TighteningThresholds {
+    risk_density: number;
+    conflict_rate: number;
+    confidence_drop: number;
+    error_rate: number;
+    latency_p99_ms: number;
+    consecutive_failures: number;
+}
+interface CapabilityFlags {
+    enable_advanced_features: boolean;
+    enable_auto_approve: boolean;
+    enable_batch_operations: boolean;
+    enable_external_api_calls: boolean;
+    enable_write_operations: boolean;
+    require_human_gate: boolean;
+    require_dual_review: boolean;
+    max_concurrent_decisions: number;
+    decision_delay_ms: number;
+}
+interface ConstraintConfig {
+    thresholds: TighteningThresholds;
+    flags: CapabilityFlags;
+    auto_recover_after_minutes: number;
+    evaluation_interval_seconds: number;
+}
+interface MonitoringMetrics {
+    risk_density: number;
+    conflict_rate: number;
+    avg_confidence: number;
+    prev_avg_confidence: number;
+    error_rate: number;
+    latency_p99_ms: number;
+    consecutive_failures: number;
+    pending_approval_count: number;
+    system_pressure: number;
+}
+interface ConstraintDecision {
+    decision_id: string;
+    timestamp: number;
+    level: ConstraintLevel;
+    modes_activated: ConstraintMode[];
+    triggers: ConstraintTrigger[];
+    flags_applied: Partial<CapabilityFlags>;
+    reason_code: string;
+    auto_recover_at: number | null;
+}
+interface ConstraintTrigger {
+    metric_name: string;
+    current_value: number;
+    threshold_value: number;
+    exceeded: boolean;
+}
+interface ConstraintState {
+    current_level: ConstraintLevel;
+    active_modes: ConstraintMode[];
+    flags: CapabilityFlags;
+    activated_at: number | null;
+    auto_recover_at: number | null;
+    last_evaluation_at: number;
+    evaluation_count: number;
+    constraint_history: ConstraintDecision[];
+}
+declare class SelfConstraintEngine {
+    private config;
+    private state;
+    constructor(config?: Partial<ConstraintConfig>);
+    evaluate(metrics: MonitoringMetrics): ConstraintDecision;
+    private calculateLevel;
+    private applyConstraint;
+    checkAutoRecover(): boolean;
+    reset(): void;
+    forceLevel(level: ConstraintLevel): void;
+    preDecisionCheck(action: string, resource: string): {
+        allowed: boolean;
+        delay_ms: number;
+        requires_human: boolean;
+        requires_dual_review: boolean;
+        reason: string;
+    };
+    getState(): ConstraintState;
+    getCurrentLevel(): ConstraintLevel;
+    getFlags(): CapabilityFlags;
+    isConstrained(): boolean;
+    private isWriteAction;
+    private isExternalAction;
+    private isBatchAction;
+}
+
+/**
+ * contributionSettlement.ts — 贡献结算引擎
+ *
+ * 覆盖 PDF3: 人工智能痛点上下文总结(3) — 激励对齐方案
+ *
+ * 核心能力:
+ * - 四维贡献打分: Risk / Cost / Human / Stability
+ * - 归因引擎: 对 rule/model/tool/agent/human/system 各参与者计分
+ * - 窗口聚合: 按时间窗口聚合贡献事件为分数
+ * - 反作弊机制: 硬性门槛 + 惩罚机制 + 审计抽查
+ * - 评分公式: Score_total = w_R*Score_risk + w_C*Score_cost + w_H*Score_human + w_S*Score_stability - Penalties
+ * - 与控制面联动: 贡献分数→权限/资源分配
+ */
+type ContributionDimension = 'RISK' | 'COST' | 'HUMAN' | 'STABILITY';
+type EntityType = 'rule' | 'model' | 'tool' | 'agent' | 'human' | 'system';
+interface ContributionEvent {
+    event_id: string;
+    trace_id: string;
+    decision_id: string;
+    tenant_id: string;
+    entity_type: EntityType;
+    entity_id: string;
+    dimension: ContributionDimension;
+    delta_value: number;
+    delta_confidence: number;
+    baseline_ref: string;
+    evidence_bundle_hash: string;
+    created_at: number;
+}
+interface ContributionScore {
+    score_id: string;
+    window_start: number;
+    window_end: number;
+    tenant_id: string;
+    entity_type: EntityType;
+    entity_id: string;
+    score_risk: number;
+    score_cost: number;
+    score_human: number;
+    score_stability: number;
+    score_total: number;
+    penalty_total: number;
+    confidence: number;
+    score_config_version: string;
+    created_at: number;
+}
+interface ScoreConfigVersion {
+    version: string;
+    weight_risk: number;
+    weight_cost: number;
+    weight_human: number;
+    weight_stability: number;
+    weight_penalty: number;
+    caps: {
+        max_single_event: number;
+        max_risk_positive_when_risk_up: boolean;
+    };
+    guardrails: string[];
+    approved_by: string;
+    approved_at: number;
+}
+interface AttributionRule {
+    condition: string;
+    target_entity_type: EntityType;
+    target_entity_field: string;
+    weight: number;
+}
+interface PenaltyCheck {
+    name: string;
+    detect: (events: ContributionEvent[], context: SettlementContext) => number;
+}
+interface SettlementContext {
+    tenant_id: string;
+    window_start: number;
+    window_end: number;
+    override_count_delta: number;
+    replay_fail_delta: number;
+    risk_regression: boolean;
+    evidence_downgrade: boolean;
+}
+declare class ContributionSettlementEngine {
+    private config;
+    private attributionRules;
+    private penaltyChecks;
+    private eventStore;
+    private scoreStore;
+    constructor(config?: Partial<ScoreConfigVersion>, customRules?: AttributionRule[], customPenalties?: PenaltyCheck[]);
+    recordEvent(event: ContributionEvent): ContributionEvent;
+    attribute(traceId: string, condition: string, entityType: EntityType, entityId: string): ContributionEvent | null;
+    settle(context: SettlementContext): ContributionScore[];
+    getResourceAllocation(entityType: EntityType, entityId: string): {
+        token_budget_multiplier: number;
+        concurrency_quota_multiplier: number;
+        auto_approve_eligible: boolean;
+        requires_dual_review: boolean;
+    };
+    auditSample(entityType: EntityType, entityId: string, sampleSize?: number): ContributionEvent[];
+    private inferDimension;
+    getConfig(): ScoreConfigVersion;
+    getEventCount(): number;
+    getScoreCount(): number;
+}
+
+/**
+ * overrideDriftAnalyzer.ts — Override 漂移分析器
+ *
+ * 覆盖 PDF1/2: 对抗防护闭环 — Override Drift 检测
+ *
+ * 核心能力:
+ * - 周期统计: 按时间窗口统计 override 频率/分布
+ * - drift_index 计算: 量化 override 偏离基线的程度
+ * - 告警生成: 当 drift_index 超过阈值时触发告警
+ * - 模式识别: 识别 override 的时间/用户/规则模式
+ * - 与 trendAlertEngine / selfConstraintEngine 联动
+ */
+interface OverrideEvent {
+    event_id: string;
+    decision_id: string;
+    trace_id: string;
+    tenant_id: string;
+    actor_id: string;
+    actor_type: 'human' | 'agent' | 'system';
+    rule_id: string;
+    original_outcome: 'BLOCK' | 'WARN';
+    override_outcome: 'ALLOW';
+    override_reason: string;
+    risk_level: 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';
+    created_at: number;
+}
+interface DriftWindow {
+    window_start: number;
+    window_end: number;
+    total_decisions: number;
+    total_overrides: number;
+    override_rate: number;
+    by_actor: Map<string, number>;
+    by_rule: Map<string, number>;
+    by_risk_level: Record<string, number>;
+    by_hour: number[];
+}
+interface DriftIndex {
+    value: number;
+    rate_drift: number;
+    concentration_drift: number;
+    risk_drift: number;
+    temporal_drift: number;
+    trend: 'STABLE' | 'RISING' | 'FALLING' | 'VOLATILE';
+}
+interface DriftAlert {
+    alert_id: string;
+    drift_index: DriftIndex;
+    severity: 'INFO' | 'WARN' | 'CRITICAL';
+    message: string;
+    patterns_detected: DriftPattern[];
+    recommendations: string[];
+    created_at: number;
+}
+interface DriftPattern {
+    pattern_type: 'ACTOR_CONCENTRATION' | 'RULE_BYPASS' | 'TIME_ANOMALY' | 'RISK_ESCALATION' | 'RATE_SPIKE';
+    description: string;
+    evidence: Record<string, unknown>;
+    confidence: number;
+}
+interface DriftAnalyzerConfig {
+    baseline_window_hours: number;
+    analysis_window_hours: number;
+    rate_drift_threshold: number;
+    concentration_threshold: number;
+    risk_drift_threshold: number;
+    temporal_drift_threshold: number;
+    composite_alert_threshold: number;
+    min_sample_size: number;
+}
+declare class OverrideDriftAnalyzer {
+    private config;
+    private events;
+    private baselineWindow;
+    private alerts;
+    constructor(config?: Partial<DriftAnalyzerConfig>);
+    recordOverride(event: OverrideEvent): void;
+    computeWindow(start: number, end: number, totalDecisions?: number): DriftWindow;
+    updateBaseline(totalDecisions?: number): DriftWindow;
+    calculateDriftIndex(currentWindow?: DriftWindow, totalDecisions?: number): DriftIndex;
+    analyze(totalDecisions?: number): DriftAlert | null;
+    private detectPatterns;
+    private generateRecommendations;
+    private calculateConcentration;
+    private calculateTemporalDrift;
+    private determineTrend;
+    getAlerts(limit?: number): DriftAlert[];
+    getEventCount(): number;
+    getLatestDriftIndex(totalDecisions?: number): DriftIndex;
+    getStats(): {
+        total_events: number;
+        total_alerts: number;
+        baseline_override_rate: number;
+        current_override_rate: number;
+    };
+}
+
 /**
  * @sovr/engine — Unified Policy Engine
  *
@@ -2086,4 +2499,4 @@ declare class PolicyEngine {
     }): void;
 }
 
-export { type ABTestConfig, AdaptiveThresholdManager, type AdaptiveThresholdOptions, type AdjustmentResult, type AggregateSnapshot, type AggregationResult, type AggregationType, type AggregationWindow, type AssembledContext, type AuditEvent, AutoHardenEngine, type BudgetAlert, type BudgetLevel, type BudgetNode, type CacheEntry, type Channel, type CircuitBreakerState, type CircuitState, type ComparableInput, type ComparableResult, type ComparisonNode, type CompiledExpression, type ConsistencyMismatch, type ConsistencyResult, ContextAccelerator, type ContextAcceleratorConfig, type ContextFragment, type ContextPriority, type CostAuditEvent, type CostCategory, type CostEstimate, type CostEstimateRequest, type CostGateEnhancedConfig, CostGateEnhancedEngine, type CostRecord, type CostReport, type CostSummary, type DCFInput, type DCFResult, DEFAULT_CA_CONFIG, DEFAULT_GE_CONFIG, DEFAULT_HARD_RULES, DEFAULT_RULES, DEFAULT_SCORING_WEIGHTS, DEFAULT_TSA_CONFIG, type DataPoint, type DecisionFeedback, type DegradationLevel, type DriftConfig, type DriftResult, type EligibilityResult, type EngineConfig, type EngineTier, type EngineTierLimits, type EstimateAccuracy, type EvalContext, type EvalRequest, type EvalResult, EvolutionChannelEngine, type EvolutionConfig, type EvolutionEvent, type ExecContext, type ExprTreePolicyRule, type ExpressionNode, type FeatureSwitchDef, type FeatureSwitchState, FeatureSwitchesManager, type FeatureSwitchesOptions, type FunctionNode, type PolicyVersion as GovPolicyVersion, type GovernanceDecision, GovernanceEnhancer, type GovernanceEnhancerConfig, type GovernanceRule, type HardRule, type HardenConfig, type HardenEvent, type HardenLevel, type HardenMeasure, type HardenMeasureType, type HardenState, type HttpContext, type LiteralNode, type LogicalNode, type MarketSize, type McpContext, type ModelCandidate, type ModelPricing, type ModelTier, type MultiLevelBudgetConfig, MultiLevelBudgetEngine, type NetworkEffectInput, type NetworkEffectResult, type NotNode, PolicyEngine, type PolicyRule, type PolicySnapshot, type PolicyVersion$1 as PolicyVersion, type PrefetchRule, type PricingEvalRequest, type PricingEvalResult, type PricingRule, PricingRulesEngine, type ReasonCode, type RecalcEngineConfig, type RecalcGranularity, type RecalcHandler, type RecalcTask, type RecalcTaskStatus, type RecalcTriggerType, RecalculationEngine, type RiskLevel, type RoutingDecision, type RoutingRequest, type RuleCondition, type RuleEvalResult, SOVR_FEATURE_SWITCHES, type ScoringResult, type ScoringWeights, SemanticDriftDetectorEngine, type SemanticFingerprint, type SensitivityResult, type SqlContext, type ThresholdConfig, TimeSeriesAggregator, type TimeSeriesAggregatorConfig, type ToolPricing, TwoPhaseRouter, type TwoPhaseRouterConfig, type UnitEconomics, ValuationModel, type ValuationModelConfig, type VariableNode, type Verdict, type WindowType, compileFromJSON, compileRuleSet, createAutoHardenEngine, createCostGateEnhanced, createEvolutionChannel, createMultiLevelBudget, createRecalculationEngine, createSemanticDriftDetector, PolicyEngine as default, estimateCost, evaluateRules, getAccuracyStats, getModelPricingTable, getToolPricingTable, recordActualCost, registerFunction, updateModelPricing, updateToolPricing };
+export { type ABTestConfig, AdaptiveThresholdManager, type AdaptiveThresholdOptions, type AdjustmentResult, type AggregateSnapshot, type AggregationResult, type AggregationType, type AggregationWindow, type AlertEvent, type AlertSeverity, type AlertThreshold, type AlertType, type AssembledContext, type AttributionRule, type AuditEvent, AutoHardenEngine, type BudgetAlert, type BudgetLevel, type BudgetNode, type CacheEntry, type CapabilityFlags, type Channel, type CircuitBreakerState, type CircuitState, type ComparableInput, type ComparableResult, type ComparisonNode, type CompiledExpression, type ConsistencyMismatch, type ConsistencyResult, type ConstraintConfig, type ConstraintDecision, type ConstraintLevel, type ConstraintMode, type ConstraintState, type ConstraintTrigger, ContextAccelerator, type ContextAcceleratorConfig, type ContextFragment, type ContextPriority, type ContributionDimension, type ContributionEvent, type ContributionScore, ContributionSettlementEngine, type CostAuditEvent, type CostCategory, type CostEstimate, type CostEstimateRequest, type CostGateEnhancedConfig, CostGateEnhancedEngine, type CostRecord, type CostReport, type CostSummary, type DCFInput, type DCFResult, DEFAULT_CA_CONFIG, DEFAULT_GE_CONFIG, DEFAULT_HARD_RULES, DEFAULT_RULES, DEFAULT_SCORING_WEIGHTS, DEFAULT_TSA_CONFIG, type DataPoint, type DecisionFeedback, type DegradationLevel, type DegradeState, type DriftAlert, type DriftAnalyzerConfig, type DriftConfig, type DriftIndex, type DriftPattern, type DriftResult, type DriftWindow, type EligibilityResult, type EngineConfig, type EngineTier, type EngineTierLimits, type EntityType, type EstimateAccuracy, type EvalContext, type EvalRequest, type EvalResult, EvolutionChannelEngine, type EvolutionConfig, type EvolutionEvent, type ExecContext, type ExprTreePolicyRule, type ExpressionNode, type FeatureSwitchDef, type FeatureSwitchState, FeatureSwitchesManager, type FeatureSwitchesOptions, type FunctionNode, type PolicyVersion as GovPolicyVersion, type GovernanceDecision, GovernanceEnhancer, type GovernanceEnhancerConfig, type GovernanceRule, type HardRule, type HardenConfig, type HardenEvent, type HardenLevel, type HardenMeasure, type HardenMeasureType, type HardenState, type HttpContext, type KillSwitchState, type LiteralNode, type LogicalNode, type MarketSize, type McpContext, type ModelCandidate, type ModelPricing, type ModelTier, type MonitoringMetrics, type MultiLevelBudgetConfig, MultiLevelBudgetEngine, type NetworkEffectInput, type NetworkEffectResult, type NotNode, OverrideDriftAnalyzer, type OverrideEvent, type PenaltyCheck, PolicyEngine, type PolicyRule, type PolicySnapshot, type PolicyVersion$1 as PolicyVersion, type PrefetchRule, type PricingEvalRequest, type PricingEvalResult, type PricingRule, PricingRulesEngine, type ProtectiveAction, type ReasonCode, type RecalcEngineConfig, type RecalcGranularity, type RecalcHandler, type RecalcTask, type RecalcTaskStatus, type RecalcTriggerType, RecalculationEngine, type RiskLevel, type RoutingDecision, type RoutingRequest, type RuleCondition, type RuleEvalResult, SOVR_FEATURE_SWITCHES, type ScoreConfigVersion, type ScoringResult, type ScoringWeights, SelfConstraintEngine, SemanticDriftDetectorEngine, type SemanticFingerprint, type SensitivityResult, type SettlementContext, type SqlContext, type SystemState, type ThresholdConfig, type TighteningThresholds, TimeSeriesAggregator, type TimeSeriesAggregatorConfig, type ToolPricing, TrendAlertEngine, type TrendMetric, TwoPhaseRouter, type TwoPhaseRouterConfig, type UnitEconomics, ValuationModel, type ValuationModelConfig, type VariableNode, type Verdict, type WindowType, compileFromJSON, compileRuleSet, createAutoHardenEngine, createCostGateEnhanced, createEvolutionChannel, createMultiLevelBudget, createRecalculationEngine, createSemanticDriftDetector, PolicyEngine as default, estimateCost, evaluateRules, getAccuracyStats, getModelPricingTable, getToolPricingTable, recordActualCost, registerFunction, updateModelPricing, updateToolPricing };