@sovr/engine 3.2.0 → 3.3.0

package/dist/index.d.ts

@@ -1,3 +1,354 @@
+/**
+ * @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 — Unified Policy Engine
  *
@@ -214,4 +565,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 { AdaptiveThresholdManager, type AdaptiveThresholdOptions, type AdjustmentResult, type AuditEvent, type Channel, type ComparisonNode, type CompiledExpression, DEFAULT_RULES, type DecisionFeedback, type EngineConfig, type EngineTier, type EngineTierLimits, type EvalContext, type EvalRequest, type EvalResult, type ExecContext, type ExprTreePolicyRule, type ExpressionNode, type FeatureSwitchDef, type FeatureSwitchState, FeatureSwitchesManager, type FeatureSwitchesOptions, type FunctionNode, type HttpContext, type LiteralNode, type LogicalNode, type McpContext, type NotNode, PolicyEngine, type PolicyRule, type PricingEvalRequest, type PricingEvalResult, type PricingRule, PricingRulesEngine, type RiskLevel, type RuleCondition, type RuleEvalResult, SOVR_FEATURE_SWITCHES, type SqlContext, type ThresholdConfig, type VariableNode, type Verdict, compileFromJSON, compileRuleSet, PolicyEngine as default, evaluateRules, registerFunction };