@sovr/engine 3.2.0 → 3.4.0

package/dist/index.d.mts

@@ -1,3 +1,1204 @@
+/**
+ * @sovr/engine — Expression Tree Engine
+ *
+ * Compiles SOVR Policy DSL rules into an AST (Abstract Syntax Tree),
+ * supporting complex condition composition, short-circuit evaluation,
+ * and high-performance cached execution.
+ *
+ * Features:
+ * - Nested AND/OR/NOT logic
+ * - Comparison operators: ==, !=, >, <, >=, <=, in, not_in, contains, starts_with, ends_with, matches
+ * - Variable references (dot-separated paths from context)
+ * - Built-in functions (now_hour, risk_level, is_business_hours, etc.)
+ * - Compile once, evaluate many times
+ *
+ * @since 3.3.0
+ */
+type ExpressionNode = LogicalNode | ComparisonNode | NotNode | LiteralNode | VariableNode | FunctionNode;
+interface LogicalNode {
+    type: 'AND' | 'OR';
+    children: ExpressionNode[];
+}
+interface NotNode {
+    type: 'NOT';
+    child: ExpressionNode;
+}
+interface ComparisonNode {
+    type: 'COMPARE';
+    operator: '==' | '!=' | '>' | '<' | '>=' | '<=' | 'in' | 'not_in' | 'contains' | 'starts_with' | 'ends_with' | 'matches';
+    left: ExpressionNode;
+    right: ExpressionNode;
+}
+interface LiteralNode {
+    type: 'LITERAL';
+    value: string | number | boolean | string[] | number[];
+}
+interface VariableNode {
+    type: 'VARIABLE';
+    path: string;
+}
+interface FunctionNode {
+    type: 'FUNCTION';
+    name: string;
+    args: ExpressionNode[];
+}
+interface EvalContext {
+    [key: string]: any;
+}
+interface CompiledExpression {
+    ast: ExpressionNode;
+    evaluate: (ctx: EvalContext) => boolean;
+    toString: () => string;
+    variables: string[];
+}
+/**
+ * Compile a JSON rule definition into an expression tree.
+ *
+ * Supported JSON formats:
+ * ```json
+ * { "and": [...conditions] }
+ * { "or": [...conditions] }
+ * { "not": condition }
+ * { "field": "action.type", "op": "==", "value": "delete" }
+ * { "field": "risk_score", "op": ">", "value": 0.8 }
+ * { "field": "user.role", "op": "in", "value": ["admin", "owner"] }
+ * { "fn": "now_hour", "op": ">=", "value": 22 }
+ * ```
+ */
+declare function compileFromJSON(rule: any): CompiledExpression;
+/**
+ * Register a custom function for use in expression trees.
+ */
+declare function registerFunction(name: string, fn: (args: any[], ctx: EvalContext) => any): void;
+interface ExprTreePolicyRule {
+    id: string;
+    name: string;
+    priority: number;
+    condition: any;
+    action: 'ALLOW' | 'DENY' | 'REQUIRE_APPROVAL' | 'LOG';
+    metadata?: Record<string, any>;
+}
+interface RuleEvalResult {
+    ruleId: string;
+    ruleName: string;
+    matched: boolean;
+    action: string;
+    evaluationTimeMs: number;
+}
+declare function compileRuleSet(rules: ExprTreePolicyRule[]): void;
+/**
+ * Evaluate all rules against a context (sorted by priority, first match wins).
+ */
+declare function evaluateRules(rules: ExprTreePolicyRule[], ctx: EvalContext): {
+    matched: ExprTreePolicyRule | null;
+    results: RuleEvalResult[];
+};
+
+/**
+ * @sovr/engine — Adaptive Threshold Module
+ *
+ * Automatically adjusts risk-control thresholds based on historical decision data:
+ * - Sliding window statistics (false positive rate, false negative rate, pass rate)
+ * - EWMA (Exponentially Weighted Moving Average) threshold self-adjustment
+ * - Safety boundary protection (thresholds never exceed [min, max] range)
+ * - Change audit (every adjustment is logged via callback)
+ *
+ * This module is database-agnostic — it uses in-memory storage and emits
+ * adjustment events via a configurable callback for external persistence.
+ *
+ * @since 3.3.0
+ */
+interface ThresholdConfig {
+    /** Threshold name (e.g., risk_score, cost_limit, latency_p99) */
+    name: string;
+    /** Current value */
+    currentValue: number;
+    /** Minimum allowed value (safety lower bound) */
+    minValue: number;
+    /** Maximum allowed value (safety upper bound) */
+    maxValue: number;
+    /** EWMA smoothing factor (0 < alpha < 1), higher = more responsive */
+    alpha: number;
+    /** Maximum adjustment step per cycle (percentage) */
+    maxStepPercent: number;
+    /** Last adjustment timestamp */
+    lastAdjustedAt: number;
+    /** Direction lock (prevents oscillation) */
+    directionLock: 'up' | 'down' | null;
+    /** Consecutive same-direction adjustment count */
+    consecutiveAdjustments: number;
+}
+interface DecisionFeedback {
+    /** Decision ID */
+    decisionId: string;
+    /** Threshold name */
+    thresholdName: string;
+    /** Threshold value at decision time */
+    thresholdAtDecision: number;
+    /** Actual risk score */
+    actualScore: number;
+    /** Decision outcome */
+    outcome: 'true_positive' | 'true_negative' | 'false_positive' | 'false_negative';
+    /** Timestamp */
+    timestamp: number;
+}
+interface AdjustmentResult {
+    thresholdName: string;
+    previousValue: number;
+    newValue: number;
+    reason: string;
+    metrics: {
+        falsePositiveRate: number;
+        falseNegativeRate: number;
+        totalSamples: number;
+        windowHours: number;
+    };
+}
+interface AdaptiveThresholdOptions {
+    /** Custom threshold configurations (overrides defaults) */
+    thresholds?: ThresholdConfig[];
+    /** Maximum feedback buffer size */
+    maxBufferSize?: number;
+    /** Cooldown between adjustments in milliseconds */
+    adjustmentCooldownMs?: number;
+    /** Callback for audit trail (called on every adjustment) */
+    onAdjustment?: (result: AdjustmentResult) => void | Promise<void>;
+}
+declare class AdaptiveThresholdManager {
+    private thresholds;
+    private feedbackBuffer;
+    private maxBufferSize;
+    private cooldownMs;
+    private onAdjustment?;
+    constructor(options?: AdaptiveThresholdOptions);
+    /** Get a threshold by name */
+    getThreshold(name: string): ThresholdConfig | undefined;
+    /** Get all thresholds */
+    getAllThresholds(): ThresholdConfig[];
+    /** Record a decision feedback sample */
+    recordFeedback(feedback: DecisionFeedback): void;
+    /**
+     * Adjust a single threshold based on feedback (EWMA algorithm).
+     * Returns null if no adjustment is needed (cooldown, insufficient samples, etc.).
+     */
+    adjustThreshold(thresholdName: string, windowHours?: number): Promise<AdjustmentResult | null>;
+    /** Adjust all thresholds */
+    adjustAll(windowHours?: number): Promise<AdjustmentResult[]>;
+    /** Manually override a threshold value */
+    setThresholdManual(name: string, value: number): boolean;
+    /** Get feedback statistics for a threshold (or all) */
+    getFeedbackStats(thresholdName?: string, windowHours?: number): {
+        total: number;
+        truePositive: number;
+        trueNegative: number;
+        falsePositive: number;
+        falseNegative: number;
+        accuracy: number;
+        precision: number;
+        recall: number;
+    };
+    /** Clear the feedback buffer */
+    clearFeedback(): void;
+}
+
+/**
+ * @sovr/engine — Feature Switches Module
+ *
+ * Manages 4 core feature switches for the SOVR decision plane:
+ * - USE_NEW_RISK_ENGINE: Enable expression tree + adaptive threshold engine
+ * - ENFORCE_COST_CAP: Hard-reject when agent cost exceeds budget
+ * - ENABLE_PROMPT_GUARD: Enable prompt injection scanning for all LLM calls
+ * - DISABLE_EVIDENCE_PAUSE: Keep evidence chain writing even under high load
+ *
+ * All switches are stored in-memory with configurable persistence callbacks.
+ * Supports multi-tenant isolation and TTL-based caching.
+ *
+ * @since 3.3.0
+ */
+interface FeatureSwitchDef {
+    key: string;
+    description: string;
+    defaultValue: boolean;
+    category: 'risk' | 'cost' | 'security' | 'evidence';
+    impactLevel: 'high' | 'medium' | 'low';
+}
+interface FeatureSwitchState {
+    key: string;
+    value: boolean;
+    description: string;
+    category: string;
+    impactLevel: string;
+    isDefault: boolean;
+}
+interface FeatureSwitchesOptions {
+    /** Cache TTL in milliseconds (default: 30000) */
+    cacheTtlMs?: number;
+    /** Callback to load switch value from external storage */
+    onLoad?: (key: string, tenantId: string) => Promise<boolean | null>;
+    /** Callback to save switch value to external storage */
+    onSave?: (key: string, value: boolean, tenantId: string) => Promise<void>;
+}
+declare const SOVR_FEATURE_SWITCHES: Record<string, FeatureSwitchDef>;
+declare class FeatureSwitchesManager {
+    private cache;
+    private cacheTtlMs;
+    private onLoad?;
+    private onSave?;
+    constructor(options?: FeatureSwitchesOptions);
+    /**
+     * Get a switch value (with cache + optional external load).
+     */
+    getValue(key: string, tenantId?: string): Promise<boolean>;
+    /**
+     * Set a switch value (updates cache + optional external save).
+     */
+    setValue(key: string, value: boolean, tenantId?: string): Promise<void>;
+    /**
+     * Get all switch states.
+     */
+    getAll(tenantId?: string): Promise<Record<string, FeatureSwitchState>>;
+    /** Clear the cache (for testing or forced refresh) */
+    clearCache(): void;
+    isNewRiskEngineEnabled(tenantId?: string): Promise<boolean>;
+    isCostCapEnforced(tenantId?: string): Promise<boolean>;
+    isPromptGuardEnabled(tenantId?: string): Promise<boolean>;
+    isEvidencePauseDisabled(tenantId?: string): Promise<boolean>;
+}
+
+/**
+ * @sovr/engine — Pricing Rules Engine
+ *
+ * Evaluates pricing rules for SOVR-governed actions.
+ * Supports tiered pricing, volume discounts, time-based multipliers,
+ * and cost-cap enforcement.
+ *
+ * Schema reference (sovr_pricing_rules table):
+ *   id, rule_name, tier, action_pattern, base_cost_usd, multiplier,
+ *   volume_discount_threshold, volume_discount_percent, time_window_start,
+ *   time_window_end, is_active, priority, created_at, updated_at
+ *
+ * This module is database-agnostic — rules are loaded into memory
+ * and evaluated purely in-process.
+ *
+ * @since 3.3.0
+ */
+interface PricingRule {
+    id: string;
+    ruleName: string;
+    /** Which tier this rule applies to (empty string = all tiers) */
+    tier: string;
+    /** Glob pattern for action names */
+    actionPattern: string;
+    /** Base cost in USD */
+    baseCostUsd: number;
+    /** Cost multiplier (default 1.0) */
+    multiplier: number;
+    /** Volume discount threshold (number of actions) */
+    volumeDiscountThreshold: number;
+    /** Volume discount percentage (0-100) */
+    volumeDiscountPercent: number;
+    /** Time window start hour (0-23, -1 = no time restriction) */
+    timeWindowStart: number;
+    /** Time window end hour (0-23, -1 = no time restriction) */
+    timeWindowEnd: number;
+    /** Whether this rule is active */
+    isActive: boolean;
+    /** Priority (higher = evaluated first) */
+    priority: number;
+}
+interface PricingEvalRequest {
+    /** Action being performed */
+    action: string;
+    /** Actor's tier */
+    tier: string;
+    /** Number of actions already performed in current period */
+    currentVolume: number;
+    /** Current hour (0-23), defaults to now */
+    currentHour?: number;
+}
+interface PricingEvalResult {
+    /** Final computed cost in USD */
+    costUsd: number;
+    /** Base cost before adjustments */
+    baseCostUsd: number;
+    /** Applied multiplier */
+    multiplier: number;
+    /** Volume discount applied (0-100) */
+    volumeDiscountPercent: number;
+    /** Whether a time-based rule was applied */
+    timeWindowActive: boolean;
+    /** Which rule was matched */
+    matchedRuleId: string | null;
+    /** Human-readable breakdown */
+    breakdown: string;
+}
+declare class PricingRulesEngine {
+    private rules;
+    constructor(rules?: PricingRule[]);
+    /** Load rules (sorted by priority descending) */
+    loadRules(rules: PricingRule[]): void;
+    /** Add a single rule */
+    addRule(rule: PricingRule): void;
+    /** Get all loaded rules */
+    getRules(): readonly PricingRule[];
+    /**
+     * Evaluate pricing for an action.
+     * Returns the computed cost and breakdown.
+     */
+    evaluate(request: PricingEvalRequest): PricingEvalResult;
+    private globMatch;
+}
+
+/**
+ * @sovr/engine — Recalculation Engine (Pure Memory Mode)
+ *
+ * Aggregation layer recalculation capabilities:
+ * - G3: Recalculation triggers (manual/automatic)
+ * - G4: Consistency verification (compare pre/post values)
+ * - G5: Incremental recalculation (from checkpoint)
+ * - G6: Recalculation audit (via onAudit callback)
+ *
+ * Zero external dependencies. Audit via callback injection.
+ */
+type RecalcTaskStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
+type RecalcTriggerType = 'manual' | 'scheduled' | 'drift_detected' | 'data_correction' | 'policy_change';
+type RecalcGranularity = '5m' | '1h' | '1d' | 'all';
+interface RecalcTask {
+    id: string;
+    tenantId: string;
+    triggerType: RecalcTriggerType;
+    triggeredBy: string;
+    reason: string;
+    fromTs: number;
+    toTs: number;
+    granularity: RecalcGranularity;
+    incremental: boolean;
+    incrementalCheckpoint?: string;
+    status: RecalcTaskStatus;
+    startedAt?: number;
+    completedAt?: number;
+    progress: number;
+    bucketsProcessed: number;
+    rowsUpserted: number;
+    consistencyResult?: ConsistencyResult;
+    error?: string;
+    createdAt: number;
+    traceId: string;
+}
+interface ConsistencyResult {
+    id: string;
+    taskId: string;
+    status: 'consistent' | 'inconsistent' | 'partial';
+    totalComparisons: number;
+    matchCount: number;
+    mismatchCount: number;
+    consistencyRate: number;
+    mismatches: ConsistencyMismatch[];
+    verifiedAt: number;
+    verificationHash: string;
+}
+interface ConsistencyMismatch {
+    metric: string;
+    bucket: string;
+    currentValue: number;
+    recalculatedValue: number;
+    deviation: number;
+    deviationPercent: number;
+    severity: 'low' | 'medium' | 'high' | 'critical';
+}
+interface AggregateSnapshot {
+    id: string;
+    tenantId: string;
+    snapshotType: 'pre_recalc' | 'post_recalc' | 'scheduled';
+    taskId?: string;
+    metrics: Record<string, number>;
+    hash: string;
+    createdAt: number;
+}
+type RecalcHandler = (task: RecalcTask) => Promise<{
+    bucketsProcessed: number;
+    rowsUpserted: number;
+    metrics: Record<string, number>;
+}>;
+interface RecalcEngineConfig {
+    maxRangeDays: number;
+    onAudit?: (event: {
+        type: string;
+        details: Record<string, unknown>;
+        timestamp: number;
+    }) => void;
+}
+declare class RecalculationEngine {
+    private tasks;
+    private consistencyResults;
+    private snapshots;
+    private handlers;
+    private config;
+    constructor(config?: Partial<RecalcEngineConfig>);
+    /** G3: Trigger recalculation */
+    triggerRecalculation(input: {
+        tenantId: string;
+        triggerType: RecalcTriggerType;
+        triggeredBy: string;
+        reason: string;
+        fromTs: number;
+        toTs: number;
+        granularity?: RecalcGranularity;
+        incremental?: boolean;
+        incrementalCheckpoint?: string;
+    }): RecalcTask;
+    /** Execute recalculation task */
+    executeTask(taskId: string): Promise<RecalcTask>;
+    /** G4: Verify consistency */
+    verifyConsistency(taskId: string, preSnapshot: AggregateSnapshot, postSnapshot: AggregateSnapshot, recalculatedMetrics?: Record<string, number>): ConsistencyResult;
+    /** G5: Incremental recalculation */
+    triggerIncremental(input: {
+        tenantId: string;
+        triggeredBy: string;
+        reason: string;
+        granularity?: RecalcGranularity;
+    }): RecalcTask;
+    /** Create aggregate snapshot */
+    createSnapshot(tenantId: string, snapshotType: AggregateSnapshot['snapshotType'], taskId?: string, metrics?: Record<string, number>): AggregateSnapshot;
+    /** Register recalculation handler */
+    registerHandler(granularity: RecalcGranularity, handler: RecalcHandler): void;
+    /** Query functions */
+    getTask(taskId: string): RecalcTask | undefined;
+    getTasks(tenantId: string, limit?: number): RecalcTask[];
+    getConsistencyResult(taskId: string): ConsistencyResult | undefined;
+    getSnapshot(snapshotId: string): AggregateSnapshot | undefined;
+    cancelTask(taskId: string): boolean;
+    private audit;
+}
+declare function createRecalculationEngine(config?: Partial<RecalcEngineConfig>): RecalculationEngine;
+
+/**
+ * @sovr/engine — AutoHarden Module (Pure Memory Mode)
+ *
+ * Automatic security hardening when adversarial threats detected:
+ * - B7: Auto-harden capability
+ * - Gate level upgrade, rate limit reduction, enhanced audit
+ * - Configurable measures with auto-rollback
+ *
+ * Zero external dependencies. Audit via callback injection.
+ */
+type HardenLevel = 'normal' | 'elevated' | 'hardened' | 'lockdown';
+type HardenMeasureType = 'gate_level_upgrade' | 'rate_limit_reduce' | 'enhanced_audit' | 'ip_block' | 'session_invalidate' | 'feature_disable' | 'alert_admin';
+interface HardenMeasure {
+    id: string;
+    type: HardenMeasureType;
+    description: string;
+    applied: boolean;
+    appliedAt?: number;
+    rolledBackAt?: number;
+}
+interface HardenEvent {
+    id: string;
+    tenantId: string;
+    triggeredBy: string;
+    reason: string;
+    previousLevel: HardenLevel;
+    newLevel: HardenLevel;
+    measures: HardenMeasure[];
+    createdAt: number;
+    rolledBack: boolean;
+    rolledBackAt?: number;
+    traceId: string;
+}
+interface HardenConfig {
+    enabled: boolean;
+    levelMeasures: Record<HardenLevel, HardenMeasureType[]>;
+    autoRollbackMs: number;
+    rateLimitReductionFactor: number;
+    notifyAdmin: boolean;
+    onNotifyAdmin?: (event: HardenEvent) => Promise<void>;
+    onAudit?: (event: {
+        type: string;
+        details: Record<string, unknown>;
+        timestamp: number;
+    }) => void;
+}
+interface HardenState {
+    currentLevel: HardenLevel;
+    lastEvent?: HardenEvent;
+    activeMeasures: HardenMeasure[];
+    hardenedSince?: number;
+    expectedRollbackAt?: number;
+}
+declare class AutoHardenEngine {
+    private states;
+    private history;
+    private config;
+    private rollbackTimers;
+    private maxHistory;
+    constructor(config?: Partial<HardenConfig>);
+    /** Get tenant harden state */
+    getState(tenantId: string): HardenState;
+    /** Get current harden level */
+    getLevel(tenantId: string): HardenLevel;
+    /** Auto-harden (main entry) */
+    harden(input: {
+        tenantId: string;
+        triggeredBy: string;
+        reason: string;
+        targetLevel?: HardenLevel;
+        manipulationScore?: number;
+        reasonCodes?: string[];
+    }): Promise<HardenEvent>;
+    /** Manual rollback */
+    rollback(tenantId: string, rolledBackBy: string, reason?: string): Promise<HardenEvent>;
+    /** Update config */
+    updateConfig(config: Partial<HardenConfig>): HardenConfig;
+    /** Get config */
+    getConfig(): HardenConfig;
+    /** Get history */
+    getHistory(tenantId?: string, limit?: number): HardenEvent[];
+    /** Get all active hardened states */
+    getActiveStates(): Array<{
+        tenantId: string;
+        state: HardenState;
+    }>;
+    /** Cleanup timers */
+    destroy(): void;
+    private determineLevel;
+    private applyMeasures;
+    private getMeasureDescription;
+    private scheduleAutoRollback;
+    private audit;
+}
+declare function createAutoHardenEngine(config?: Partial<HardenConfig>): AutoHardenEngine;
+
+/**
+ * SOVR Cost Estimator
+ * 成本预估精确化引擎 — 补齐 F3 缺口
+ *
+ * 功能：
+ * 1. Token 级成本预估（基于模型定价表）
+ * 2. 工具调用成本预估
+ * 3. 人工审批成本预估（基于费率）
+ * 4. 总成本预估（模型 + 工具 + 人工）
+ * 5. 预估准确度追踪
+ *
+ * 设计原则:
+ * - 模型定价表可配置、可更新
+ * - 支持多种计费模式（按 token、按调用、按时间）
+ * - 预估结果包含置信区间
+ * - 与 CostGate 协作
+ */
+/** 模型定价 */
+interface ModelPricing {
+    /** 模型 ID */
+    modelId: string;
+    /** 模型名称 */
+    modelName: string;
+    /** 输入 token 单价（美元/1K tokens） */
+    inputPricePerKToken: number;
+    /** 输出 token 单价（美元/1K tokens） */
+    outputPricePerKToken: number;
+    /** 缓存 token 单价（如有） */
+    cachedInputPricePerKToken?: number;
+    /** 最大上下文长度 */
+    maxContextLength: number;
+    /** 最后更新 */
+    updatedAt: Date;
+}
+/** 工具定价 */
+interface ToolPricing {
+    /** 工具 ID */
+    toolId: string;
+    /** 工具名称 */
+    toolName: string;
+    /** 每次调用成本（美元） */
+    costPerCall: number;
+    /** 乘算因子（如有额外成本） */
+    multiplier: number;
+    /** 最后更新 */
+    updatedAt: Date;
+}
+/** 成本预估请求 */
+interface CostEstimateRequest {
+    /** 模型 ID */
+    modelId: string;
+    /** 预估输入 token 数 */
+    estimatedInputTokens: number;
+    /** 预估输出 token 数 */
+    estimatedOutputTokens: number;
+    /** 工具调用列表 */
+    toolCalls?: Array<{
+        toolId: string;
+        estimatedCalls: number;
+    }>;
+    /** 是否需要人工审批 */
+    requiresHumanReview?: boolean;
+    /** 人工审批级别 */
+    humanReviewLevel?: 'standard' | 'senior' | 'executive';
+}
+/** 成本预估结果 */
+interface CostEstimate {
+    /** 预估 ID */
+    id: string;
+    /** 模型成本 */
+    modelCost: {
+        inputCost: number;
+        outputCost: number;
+        total: number;
+    };
+    /** 工具成本 */
+    toolCost: {
+        items: Array<{
+            toolId: string;
+            calls: number;
+            costPerCall: number;
+            total: number;
+        }>;
+        total: number;
+    };
+    /** 人工审批成本 */
+    humanCost: {
+        level: string;
+        hourlyRate: number;
+        estimatedMinutes: number;
+        total: number;
+    } | null;
+    /** 总成本 */
+    totalCost: number;
+    /** 置信区间 */
+    confidence: {
+        low: number;
+        high: number;
+        level: number;
+    };
+    /** 预估时间 */
+    estimatedAt: Date;
+}
+/** 预估准确度记录 */
+interface EstimateAccuracy {
+    estimateId: string;
+    estimatedCost: number;
+    actualCost: number;
+    deviation: number;
+    deviationPercent: number;
+    recordedAt: Date;
+}
+/**
+ * 预估成本
+ */
+declare function estimateCost(request: CostEstimateRequest): CostEstimate;
+/**
+ * 记录实际成本（用于准确度追踪）
+ */
+declare function recordActualCost(estimateId: string, actualCost: number): EstimateAccuracy | null;
+/**
+ * 更新模型定价
+ */
+declare function updateModelPricing(pricing: ModelPricing): void;
+/**
+ * 更新工具定价
+ */
+declare function updateToolPricing(pricing: ToolPricing): void;
+/**
+ * 获取模型定价表
+ */
+declare function getModelPricingTable(): ModelPricing[];
+/**
+ * 获取工具定价表
+ */
+declare function getToolPricingTable(): ToolPricing[];
+/**
+ * 获取预估准确度统计
+ */
+declare function getAccuracyStats(): {
+    totalRecords: number;
+    avgDeviation: number;
+    avgDeviationPercent: number;
+    confidenceLevel: number;
+};
+
+/**
+ * server/sovr/semanticDriftDetector.ts
+ *
+ * 语义漂移检测器 — 补齐 K10 缺口
+ *
+ * 功能：
+ * - 策略语义指纹计算（基于规则结构的哈希）
+ * - 版本间语义差异检测
+ * - 漂移评分（0-1，0=完全一致，1=完全不同）
+ * - 漂移告警（超过阈值时触发）
+ * - 漂移审计链
+ *
+ * 设计原则：纯逻辑模块，无外部依赖
+ */
+interface SemanticFingerprint {
+    version: string;
+    hash: string;
+    ruleCount: number;
+    allowCount: number;
+    denyCount: number;
+    reviewCount: number;
+    resourceSet: string[];
+    actionSet: string[];
+    conditionDepth: number;
+    timestamp: number;
+}
+interface DriftResult {
+    fromVersion: string;
+    toVersion: string;
+    driftScore: number;
+    ruleCountDelta: number;
+    addedRules: string[];
+    removedRules: string[];
+    modifiedRules: string[];
+    decisionChanges: {
+        ruleId: string;
+        from: string;
+        to: string;
+    }[];
+    newResources: string[];
+    removedResources: string[];
+    severity: 'none' | 'low' | 'medium' | 'high' | 'critical';
+    timestamp: number;
+}
+interface PolicySnapshot {
+    version: string;
+    rules: PolicyRuleForDrift[];
+    metadata?: Record<string, unknown>;
+}
+interface PolicyRuleForDrift {
+    id: string;
+    action: string;
+    resource: string;
+    decision: 'ALLOW' | 'DENY' | 'REVIEW';
+    conditions?: Record<string, unknown>;
+    priority: number;
+}
+interface DriftConfig {
+    lowThreshold: number;
+    mediumThreshold: number;
+    highThreshold: number;
+    criticalThreshold: number;
+    onDriftDetected?: (result: DriftResult) => void;
+    onAudit?: (event: {
+        type: string;
+        details: Record<string, unknown>;
+        timestamp: number;
+    }) => void;
+}
+declare class SemanticDriftDetectorEngine {
+    private fingerprints;
+    private history;
+    private config;
+    constructor(config?: Partial<DriftConfig>);
+    /**
+     * 计算策略语义指纹
+     */
+    computeFingerprint(snapshot: PolicySnapshot): SemanticFingerprint;
+    /**
+     * 检测两个版本间的语义漂移
+     */
+    detectDrift(from: PolicySnapshot, to: PolicySnapshot): DriftResult;
+    /**
+     * 获取漂移历史
+     */
+    getDriftHistory(): DriftResult[];
+    /**
+     * 获取指纹
+     */
+    getFingerprint(version: string): SemanticFingerprint | null;
+    /**
+     * 获取漂移趋势
+     */
+    getDriftTrend(): {
+        version: string;
+        driftScore: number;
+        timestamp: number;
+    }[];
+    private hashRules;
+    private ruleChanged;
+    private maxConditionDepth;
+    private objectDepth;
+}
+declare function createSemanticDriftDetector(config?: Partial<DriftConfig>): SemanticDriftDetectorEngine;
+
+/**
+ * server/sovr/costGateEnhanced.ts
+ *
+ * 经济约束层增强 — 补齐 E2/E4/E5/E6/E7/E9/E10 缺口
+ *
+ * 功能：
+ * - E2: 成本汇总表（1h/24h/7d 滑动窗口）
+ * - E4: BUDGET_EXCEEDED 标准原因码
+ * - E5: 成本超限审计事件
+ * - E6: Cockpit 成本仪表板数据源
+ * - E7: getDailyCostStats API
+ * - E9: 工具调用成本代理（按工具计费）
+ * - E10: 人工审批时成本计算
+ *
+ * 设计原则：纯逻辑模块，审计通过回调注入
+ */
+interface CostRecord {
+    id: string;
+    tenantId: string;
+    agentId: string;
+    action: string;
+    toolName?: string;
+    costUsd: number;
+    tokenCount?: number;
+    modelName?: string;
+    timestamp: number;
+    category: CostCategory;
+    metadata?: Record<string, unknown>;
+}
+type CostCategory = 'llm_inference' | 'tool_call' | 'human_review' | 'storage' | 'network' | 'compute' | 'other';
+interface CostSummary {
+    period: '1h' | '24h' | '7d' | '30d';
+    totalCostUsd: number;
+    byCategory: Record<CostCategory, number>;
+    byAgent: Record<string, number>;
+    byTool: Record<string, number>;
+    recordCount: number;
+    avgCostPerAction: number;
+    peakHour?: number;
+    startTime: number;
+    endTime: number;
+}
+interface DailyCostStats {
+    date: string;
+    totalCostUsd: number;
+    byCategory: Record<CostCategory, number>;
+    actionCount: number;
+    uniqueAgents: number;
+    budgetUtilization: number;
+}
+interface BudgetExceededEvent {
+    code: 'BUDGET_EXCEEDED';
+    tenantId: string;
+    agentId: string;
+    action: string;
+    currentCostUsd: number;
+    budgetLimitUsd: number;
+    overage: number;
+    period: string;
+    timestamp: number;
+    severity: 'warning' | 'critical' | 'blocked';
+}
+interface ToolCostConfig {
+    toolName: string;
+    baseCostUsd: number;
+    perCallCostUsd: number;
+    perTokenCostUsd?: number;
+    maxCostPerCallUsd?: number;
+}
+interface HumanReviewCost {
+    reviewId: string;
+    reviewerType: 'human' | 'escalated';
+    waitTimeMs: number;
+    reviewTimeMs: number;
+    costUsd: number;
+    hourlyRateUsd: number;
+}
+interface CostGateEnhancedConfig {
+    defaultBudgetUsd: number;
+    warningThreshold: number;
+    criticalThreshold: number;
+    humanReviewHourlyRateUsd: number;
+    toolCosts: ToolCostConfig[];
+    onAudit?: (event: CostAuditEvent) => void;
+    onBudgetExceeded?: (event: BudgetExceededEvent) => void;
+}
+interface CostAuditEvent {
+    type: 'cost_recorded' | 'budget_warning' | 'budget_critical' | 'budget_exceeded' | 'summary_generated';
+    tenantId: string;
+    details: Record<string, unknown>;
+    timestamp: number;
+}
+declare class CostGateEnhancedEngine {
+    private records;
+    private budgets;
+    private config;
+    private toolCostMap;
+    constructor(config?: Partial<CostGateEnhancedConfig>);
+    /**
+     * E2: 记录成本并生成汇总
+     */
+    recordCost(record: CostRecord): BudgetExceededEvent | null;
+    /**
+     * E2: 获取成本汇总（滑动窗口）
+     */
+    getCostSummary(tenantId: string, period: CostSummary['period']): CostSummary;
+    /**
+     * E7: getDailyCostStats — 按天统计
+     */
+    getDailyCostStats(tenantId: string, days?: number): DailyCostStats[];
+    /**
+     * E9: 计算工具调用成本
+     */
+    calculateToolCost(toolName: string, tokenCount?: number): number;
+    /**
+     * E10: 计算人工审批成本
+     */
+    calculateHumanReviewCost(waitTimeMs: number, reviewTimeMs: number): HumanReviewCost;
+    /**
+     * 设置租户预算
+     */
+    setBudget(tenantId: string, budgetUsd: number): void;
+    /**
+     * 获取租户预算使用率
+     */
+    getBudgetUtilization(tenantId: string): {
+        used: number;
+        limit: number;
+        utilization: number;
+    };
+    private checkBudget;
+    private audit;
+}
+declare function createCostGateEnhanced(config?: Partial<CostGateEnhancedConfig>): CostGateEnhancedEngine;
+
+/**
+ * server/sovr/budgetMultiLevel.ts
+ *
+ * 多层预算引擎 — 补齐 F6/F7/F8 缺口
+ *
+ * 功能：
+ * - F6: 多层预算（组织 → 团队 → 项目 → Agent 四级）
+ * - F7: 预算告警（阈值触发 + 趋势预测）
+ * - F8: 成本报告（多维度分析 + 导出）
+ *
+ * 设计原则：纯逻辑模块，告警通过回调注入
+ */
+type BudgetLevel = 'organization' | 'team' | 'project' | 'agent';
+interface BudgetNode {
+    id: string;
+    name: string;
+    level: BudgetLevel;
+    parentId: string | null;
+    budgetUsd: number;
+    spentUsd: number;
+    children: string[];
+    alertRules: AlertRule[];
+    metadata?: Record<string, unknown>;
+}
+interface AlertRule {
+    id: string;
+    threshold: number;
+    severity: 'info' | 'warning' | 'critical';
+    action: 'notify' | 'throttle' | 'block';
+    cooldownMs: number;
+    lastTriggeredAt?: number;
+}
+interface BudgetAlert {
+    ruleId: string;
+    nodeId: string;
+    nodeName: string;
+    level: BudgetLevel;
+    severity: AlertRule['severity'];
+    action: AlertRule['action'];
+    utilization: number;
+    budgetUsd: number;
+    spentUsd: number;
+    remainingUsd: number;
+    predictedExhaustionDate?: string;
+    timestamp: number;
+}
+interface CostReport {
+    reportId: string;
+    generatedAt: number;
+    period: {
+        start: number;
+        end: number;
+    };
+    totalBudgetUsd: number;
+    totalSpentUsd: number;
+    utilization: number;
+    byLevel: Record<BudgetLevel, {
+        budget: number;
+        spent: number;
+        count: number;
+    }>;
+    topSpenders: {
+        id: string;
+        name: string;
+        level: BudgetLevel;
+        spent: number;
+    }[];
+    alerts: BudgetAlert[];
+    trend: {
+        date: string;
+        spent: number;
+    }[];
+}
+interface MultiLevelBudgetConfig {
+    defaultAlertRules: AlertRule[];
+    trendWindowDays: number;
+    onAlert?: (alert: BudgetAlert) => void;
+    onAudit?: (event: {
+        type: string;
+        details: Record<string, unknown>;
+        timestamp: number;
+    }) => void;
+}
+declare class MultiLevelBudgetEngine {
+    private nodes;
+    private spendHistory;
+    private config;
+    constructor(config?: Partial<MultiLevelBudgetConfig>);
+    /**
+     * F6: 创建预算节点
+     */
+    createNode(node: Omit<BudgetNode, 'spentUsd' | 'children' | 'alertRules'> & {
+        alertRules?: AlertRule[];
+    }): BudgetNode;
+    /**
+     * F6: 记录支出（向上冒泡到所有父级）
+     */
+    recordSpend(nodeId: string, amount: number): BudgetAlert[];
+    /**
+     * F6: 获取节点预算状态（含子节点汇总）
+     */
+    getNodeStatus(nodeId: string): {
+        node: BudgetNode;
+        utilization: number;
+        childrenSpent: number;
+        remaining: number;
+    } | null;
+    /**
+     * F7: 预测预算耗尽日期
+     */
+    predictExhaustion(nodeId: string): string | null;
+    /**
+     * F8: 生成成本报告
+     */
+    generateReport(rootNodeId?: string): CostReport;
+    /**
+     * 获取所有节点
+     */
+    listNodes(level?: BudgetLevel): BudgetNode[];
+    private checkAlerts;
+    private getChildrenSpent;
+    private getSubtree;
+    private generateTrend;
+}
+declare function createMultiLevelBudget(config?: Partial<MultiLevelBudgetConfig>): MultiLevelBudgetEngine;
+
+/**
+ * server/sovr/evolutionChannel.ts
+ *
+ * 受控演化通道 — 补齐 B8 缺口
+ *
+ * 功能：
+ * - 策略版本管理（版本化策略发布）
+ * - 灰度发布（canary release for policies）
+ * - A/B 测试策略（双策略并行评估）
+ * - 回滚机制（一键回退到上一版本）
+ * - 演化审计（所有策略变更记录）
+ *
+ * 设计原则：纯逻辑模块，无数据库依赖
+ */
+interface PolicyVersion {
+    id: string;
+    version: string;
+    name: string;
+    rules: PolicyRule$1[];
+    createdAt: number;
+    createdBy: string;
+    status: 'draft' | 'canary' | 'active' | 'deprecated' | 'rollback';
+    canaryPercent: number;
+    metadata?: Record<string, unknown>;
+}
+interface PolicyRule$1 {
+    id: string;
+    action: string;
+    resource: string;
+    decision: 'ALLOW' | 'DENY' | 'REVIEW';
+    conditions?: Record<string, unknown>;
+    priority: number;
+}
+interface EvolutionEvent {
+    type: 'publish' | 'canary_start' | 'canary_promote' | 'canary_rollback' | 'deprecate' | 'ab_test_start' | 'ab_test_end';
+    policyId: string;
+    version: string;
+    timestamp: number;
+    actor: string;
+    details?: Record<string, unknown>;
+}
+interface ABTestConfig {
+    id: string;
+    controlVersionId: string;
+    treatmentVersionId: string;
+    trafficSplit: number;
+    startedAt: number;
+    metrics: ABTestMetrics;
+    status: 'running' | 'completed' | 'aborted';
+}
+interface ABTestMetrics {
+    controlDecisions: number;
+    treatmentDecisions: number;
+    controlAllowRate: number;
+    treatmentAllowRate: number;
+    controlAvgLatencyMs: number;
+    treatmentAvgLatencyMs: number;
+}
+interface EvolutionConfig {
+    maxVersions: number;
+    canaryMinDurationMs: number;
+    autoPromoteThreshold: number;
+    onAudit?: (event: EvolutionEvent) => void;
+}
+declare class EvolutionChannelEngine {
+    private versions;
+    private activeVersionId;
+    private canaryVersionId;
+    private abTests;
+    private config;
+    constructor(config?: Partial<EvolutionConfig>);
+    /**
+     * 发布新策略版本
+     */
+    publish(version: PolicyVersion): PolicyVersion;
+    /**
+     * 启动灰度发布
+     */
+    startCanary(versionId: string, percent: number, actor: string): boolean;
+    /**
+     * 灰度晋升为正式版本
+     */
+    promoteCanary(actor: string): boolean;
+    /**
+     * 灰度回滚
+     */
+    rollbackCanary(actor: string): boolean;
+    /**
+     * 路由决策：根据灰度百分比选择策略版本
+     */
+    resolveVersion(requestHash?: number): PolicyVersion | null;
+    /**
+     * 启动 A/B 测试
+     */
+    startABTest(testId: string, controlId: string, treatmentId: string, trafficSplit: number, actor: string): ABTestConfig | null;
+    /**
+     * A/B 测试路由
+     */
+    resolveABTest(testId: string, requestHash?: number): {
+        version: PolicyVersion;
+        group: 'control' | 'treatment';
+    } | null;
+    /**
+     * 结束 A/B 测试
+     */
+    endABTest(testId: string, actor: string): ABTestConfig | null;
+    /**
+     * 获取所有版本
+     */
+    listVersions(): PolicyVersion[];
+    /**
+     * 获取当前 active 版本
+     */
+    getActiveVersion(): PolicyVersion | null;
+    private cleanupOldVersions;
+    private audit;
+}
+declare function createEvolutionChannel(config?: Partial<EvolutionConfig>): EvolutionChannelEngine;
+
 /**
  * @sovr/engine — Unified Policy Engine
  *
@@ -214,4 +1415,4 @@ declare class PolicyEngine {
     }): void;
 }
 
-export { type AuditEvent, type Channel, DEFAULT_RULES, type EngineConfig, type EngineTier, type EngineTierLimits, type EvalRequest, type EvalResult, type ExecContext, type HttpContext, type McpContext, PolicyEngine, type PolicyRule, type RiskLevel, type RuleCondition, type SqlContext, type Verdict, PolicyEngine as default };
+export { type ABTestConfig, AdaptiveThresholdManager, type AdaptiveThresholdOptions, type AdjustmentResult, type AggregateSnapshot, type AuditEvent, AutoHardenEngine, type BudgetAlert, type BudgetLevel, type BudgetNode, type Channel, type ComparisonNode, type CompiledExpression, type ConsistencyMismatch, type ConsistencyResult, type CostAuditEvent, type CostCategory, type CostEstimate, type CostEstimateRequest, type CostGateEnhancedConfig, CostGateEnhancedEngine, type CostRecord, type CostReport, type CostSummary, DEFAULT_RULES, type DecisionFeedback, type DriftConfig, type DriftResult, 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 HardenConfig, type HardenEvent, type HardenLevel, type HardenMeasure, type HardenMeasureType, type HardenState, type HttpContext, type LiteralNode, type LogicalNode, type McpContext, type ModelPricing, type MultiLevelBudgetConfig, MultiLevelBudgetEngine, type NotNode, PolicyEngine, type PolicyRule, type PolicySnapshot, type PolicyVersion, type PricingEvalRequest, type PricingEvalResult, type PricingRule, PricingRulesEngine, type RecalcEngineConfig, type RecalcGranularity, type RecalcHandler, type RecalcTask, type RecalcTaskStatus, type RecalcTriggerType, RecalculationEngine, type RiskLevel, type RuleCondition, type RuleEvalResult, SOVR_FEATURE_SWITCHES, SemanticDriftDetectorEngine, type SemanticFingerprint, type SqlContext, type ThresholdConfig, type ToolPricing, type VariableNode, type Verdict, compileFromJSON, compileRuleSet, createAutoHardenEngine, createCostGateEnhanced, createEvolutionChannel, createMultiLevelBudget, createRecalculationEngine, createSemanticDriftDetector, PolicyEngine as default, estimateCost, evaluateRules, getAccuracyStats, getModelPricingTable, getToolPricingTable, recordActualCost, registerFunction, updateModelPricing, updateToolPricing };