@mnemopay/sdk 0.9.1 → 0.9.3

package/dist/adaptive.d.ts

@@ -0,0 +1,256 @@
+/**
+ * MnemoPay Adaptive Engine
+ *
+ * Business philosophy encoded in code: a system that doesn't learn from its
+ * own operations is dead. MnemoPay adapts to what moves the business forward
+ * — securely, with guardrails, with a full audit trail.
+ *
+ * The engine observes:
+ *   - Agent behavior patterns (settlement rates, dispute frequency, charge velocity)
+ *   - Revenue signals (which fee tiers produce the most volume, where agents churn)
+ *   - Risk trends (emerging fraud patterns, anomaly drift, geographic shifts)
+ *   - Memory health (recall quality, consolidation rates, storage efficiency)
+ *
+ * It adapts:
+ *   - Fee tiers (within secure bounds) to maximize retention + revenue
+ *   - Risk thresholds (tighten on emerging threats, loosen on proven agents)
+ *   - Rate limits (reward trusted agents with higher throughput)
+ *   - Memory decay (faster for low-value agents, slower for high-value)
+ *
+ * It NEVER:
+ *   - Adapts below minimum security thresholds (floor on risk, max on limits)
+ *   - Changes without an audit record
+ *   - Overrides manual admin settings
+ *   - Makes jumps > 20% in any single adaptation cycle
+ *
+ * This is the Agent FICO thesis: the longer an agent operates, the smarter
+ * the system becomes about that agent. Trust is earned, never assumed.
+ */
+export interface AdaptiveConfig {
+    /** Enable adaptive optimization (default: true) */
+    enabled: boolean;
+    /** Minimum observations before adapting (default: 10) */
+    minObservations: number;
+    /** Maximum parameter change per cycle (0.2 = 20%) — used for AIMD increase */
+    maxDeltaPercent: number;
+    /** Multiplicative decrease factor for tightening (0.5 = halve on anomaly) */
+    decreaseFactor: number;
+    /** Additive increase per healthy cycle (0.02 = +2%) */
+    increaseFactor: number;
+    /** Minimum cycle interval in minutes (default: 60) */
+    cycleIntervalMinutes: number;
+    /** Lock specific parameters from adaptation */
+    lockedParams: string[];
+    /** Minimum days of consistent behavior for trust tier upgrade */
+    minTrustDurationDays: number;
+    /** Consecutive worsening cycles before circuit breaker trips */
+    circuitBreakerThreshold: number;
+    /** PSI threshold for severe drift detection (halt adaptation) */
+    psiHaltThreshold: number;
+    /** PSI threshold for moderate drift (log warning) */
+    psiWarnThreshold: number;
+}
+export declare const DEFAULT_ADAPTIVE_CONFIG: AdaptiveConfig;
+export interface AgentInsight {
+    agentId: string;
+    /** Settlement success rate (0-1) */
+    settlementRate: number;
+    /** Average charge amount */
+    avgChargeAmount: number;
+    /** Disputes filed against this agent */
+    disputeCount: number;
+    /** Total revenue generated */
+    totalRevenue: number;
+    /** Memory utilization efficiency (active memories / total) */
+    memoryEfficiency: number;
+    /** Recommended risk tier: trusted | standard | elevated | restricted */
+    riskTier: "trusted" | "standard" | "elevated" | "restricted";
+    /** Recommended fee tier override (null = use default) */
+    recommendedFeeRate: number | null;
+    /** Recommended rate limit multiplier (1.0 = default, 2.0 = double) */
+    rateLimitMultiplier: number;
+    /** Agent health score (0-100) */
+    healthScore: number;
+    /** Observations count */
+    observations: number;
+    /** Last analyzed */
+    analyzedAt: Date;
+}
+export interface AdaptationRecord {
+    id: string;
+    /** What was adapted */
+    parameter: string;
+    /** Previous value */
+    previousValue: number;
+    /** New value */
+    newValue: number;
+    /** Why it was adapted */
+    reason: string;
+    /** Evidence that triggered the adaptation */
+    evidence: Record<string, number>;
+    /** When the adaptation was applied */
+    appliedAt: Date;
+    /** Whether it was actually applied (false if locked or vetoed) */
+    applied: boolean;
+    /** Veto reason if not applied */
+    vetoReason?: string;
+}
+export interface BusinessMetrics {
+    /** Total platform revenue (from fees) */
+    totalRevenue: number;
+    /** Revenue this cycle */
+    cycleRevenue: number;
+    /** Total agents observed */
+    totalAgents: number;
+    /** Agents with settlement rate > 80% */
+    trustedAgents: number;
+    /** Agents with disputes */
+    disputedAgents: number;
+    /** Platform-wide settlement rate */
+    platformSettlementRate: number;
+    /** Average memory utilization across agents */
+    avgMemoryUtilization: number;
+    /** Fraud detection rate (blocked/total) */
+    fraudDetectionRate: number;
+    /** System health (0-100) */
+    systemHealth: number;
+    /** Computed at */
+    computedAt: Date;
+}
+export type AdaptiveEventType = "charge" | "settle" | "refund" | "dispute" | "memory_store" | "memory_recall" | "fraud_block" | "fraud_flag";
+export interface AdaptiveEvent {
+    type: AdaptiveEventType;
+    agentId: string;
+    amount?: number;
+    timestamp: number;
+    metadata?: Record<string, unknown>;
+}
+declare const SECURE_BOUNDS: {
+    readonly feeRate: {
+        readonly min: 0.005;
+        readonly max: 0.05;
+    };
+    readonly blockThreshold: {
+        readonly min: 0.3;
+        readonly max: 0.95;
+    };
+    readonly flagThreshold: {
+        readonly min: 0.1;
+        readonly max: 0.7;
+    };
+    readonly rateLimitMultiplier: {
+        readonly min: 0.5;
+        readonly max: 3;
+    };
+    readonly decayRate: {
+        readonly min: 0.001;
+        readonly max: 0.5;
+    };
+    readonly settlementHoldMinutes: {
+        readonly min: 5;
+        readonly max: 1440;
+    };
+};
+export declare class AdaptiveEngine {
+    private config;
+    private events;
+    private insights;
+    private adaptations;
+    private lastCycleAt;
+    /** Manual overrides set by admin — these are never auto-changed */
+    private adminOverrides;
+    private eventCounter;
+    /** Circuit breaker: consecutive cycles where metrics worsened */
+    private consecutiveWorseningCycles;
+    /** Circuit breaker: is the engine halted? */
+    private circuitBreakerTripped;
+    /** Snapshot of key metrics from previous cycle (for regression detection) */
+    private previousCycleMetrics;
+    /** PSI: distribution snapshot from previous cycle for drift detection */
+    private previousDistribution;
+    /** Track first event timestamp per agent for trust duration calculation */
+    private agentFirstSeen;
+    constructor(config?: Partial<AdaptiveConfig>);
+    /**
+     * Record an operational event. The engine learns from every operation.
+     */
+    observe(event: AdaptiveEvent): void;
+    /**
+     * Analyze an agent's behavioral pattern and produce an insight profile.
+     * This is the "Agent FICO score" — built from real operational data.
+     */
+    analyzeAgent(agentId: string): AgentInsight;
+    /**
+     * Compute platform-wide business intelligence.
+     */
+    computeMetrics(): BusinessMetrics;
+    /**
+     * Run an adaptation cycle. Uses asymmetric AIMD:
+     *   - Additive Increase: slow, gradual loosening on sustained good metrics
+     *   - Multiplicative Decrease: fast, aggressive tightening on anomalies
+     *
+     * Includes circuit breaker (halt after N consecutive worsening cycles)
+     * and PSI drift detection (halt if input distribution shifts too much).
+     */
+    runCycle(): AdaptationRecord[];
+    /** Reset the circuit breaker, allowing adaptation to resume. */
+    resetCircuitBreaker(): void;
+    /** Check if circuit breaker is currently tripped. */
+    get isCircuitBreakerTripped(): boolean;
+    /**
+     * Compute the event type distribution for drift detection.
+     */
+    private computeEventDistribution;
+    /**
+     * Compute Population Stability Index between two distributions.
+     * PSI > 0.1 = moderate drift, > 0.25 = severe drift.
+     */
+    private computePSI;
+    /**
+     * Lock a parameter from adaptive changes. Admin decisions override AI.
+     */
+    lockParam(param: string): void;
+    /**
+     * Unlock a parameter for adaptive changes.
+     */
+    unlockParam(param: string): void;
+    /**
+     * Set an admin override. This value will be used instead of adaptive suggestions.
+     */
+    setOverride(param: string, value: number): void;
+    /**
+     * Remove an admin override, allowing adaptive control.
+     */
+    removeOverride(param: string): void;
+    /**
+     * Get the effective value for a parameter (admin override > adaptation > default).
+     */
+    getEffectiveValue(param: string, defaultValue: number): number;
+    getInsight(agentId: string): AgentInsight | undefined;
+    getAdaptations(limit?: number): AdaptationRecord[];
+    get totalEvents(): number;
+    get secureBounds(): typeof SECURE_BOUNDS;
+    /** Backdate an agent's first-seen timestamp (for testing or data migration) */
+    setAgentFirstSeen(agentId: string, timestamp: number): void;
+    serialize(): {
+        config: AdaptiveConfig;
+        insights: [string, AgentInsight][];
+        adaptations: AdaptationRecord[];
+        overrides: [string, number][];
+        eventCount: number;
+        circuitBreakerTripped: boolean;
+        consecutiveWorsening: number;
+        agentFirstSeen: [string, number][];
+    };
+    static deserialize(data: ReturnType<AdaptiveEngine["serialize"]>): AdaptiveEngine;
+    private isLocked;
+    private clamp;
+    /**
+     * Limit how much a parameter can change in one cycle.
+     * Prevents wild swings — stability is a security property.
+     */
+    private limitDelta;
+    private createRecord;
+}
+export {};
+//# sourceMappingURL=adaptive.d.ts.map

package/dist/adaptive.d.ts.map

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