@vorionsys/atsf-core 0.2.3 → 0.2.4

package/dist/trust-engine/index.js

@@ -2,15 +2,15 @@
  * Trust Engine - Behavioral Trust Scoring
  *
  * Calculates and maintains trust scores for entities based on behavioral signals.
- * Features 6-tier trust system with event emission for observability.
+ * Features 8-tier trust system (T0-T7) with event emission for observability.
  *
  * @packageDocumentation
  */
-import { EventEmitter } from "events";
-import { createLogger } from "../common/logger.js";
-import { READINESS_EXCEPTION_REASON_CODES, } from "./types.js";
-export * from "./types.js";
-const logger = createLogger({ component: "trust-engine" });
+import { EventEmitter } from 'events';
+import { createLogger } from '../common/logger.js';
+import { calculateDecayMultiplier } from './decay-profiles.js';
+import { FACTOR_CODE_LIST, DEFAULT_FACTOR_WEIGHTS, SIGNAL_PREFIX_TO_FACTORS as BASIS_SIGNAL_PREFIX_MAP, initialFactorScores, } from '@vorionsys/basis';
+const logger = createLogger({ component: 'trust-engine' });
 /**
  * Trust level thresholds (8 tiers T0-T7) - per BASIS specification
  */
@@ -28,16 +28,22 @@ export const TRUST_THRESHOLDS = {
  * Trust level names (8 tiers T0-T7) - per BASIS specification
  */
 export const TRUST_LEVEL_NAMES = {
-    0: "Sandbox",
-    1: "Observed",
-    2: "Provisional",
-    3: "Monitored",
-    4: "Standard",
-    5: "Trusted",
-    6: "Certified",
-    7: "Autonomous",
+    0: 'Sandbox',
+    1: 'Observed',
+    2: 'Provisional',
+    3: 'Monitored',
+    4: 'Standard',
+    5: 'Trusted',
+    6: 'Certified',
+    7: 'Autonomous',
 };
+// Re-export canonical factor constants from @vorionsys/basis
+export const FACTOR_CODES = FACTOR_CODE_LIST;
+export const FACTOR_WEIGHTS = DEFAULT_FACTOR_WEIGHTS;
+export const SIGNAL_PREFIX_TO_FACTORS = BASIS_SIGNAL_PREFIX_MAP;
+export { initialFactorScores };
 /**
+ * @deprecated Use FACTOR_WEIGHTS for 16-factor scoring. Kept for backwards compatibility.
  * Signal weights for score calculation
  */
 export const SIGNAL_WEIGHTS = {
@@ -46,36 +52,12 @@ export const SIGNAL_WEIGHTS = {
     identity: 0.2,
     context: 0.15,
 };
-const DEFAULT_READINESS_CHECKPOINT_DAYS = [
-    7, 14, 28, 42, 56, 84, 112, 140, 182,
-];
-const DEFAULT_READINESS_REDUCTIONS = [
-    0.06, 0.06, 0.06, 0.06, 0.06, 0.05, 0.05, 0.05, 0.05,
-];
-const DEFAULT_READINESS_EXCEPTION_MAX_DURATION_MS = 30 * 24 * 60 * 60 * 1000;
-function toMs(days) {
-    return days * 24 * 60 * 60 * 1000;
-}
-function clampReductionScale(value) {
-    if (value === undefined || Number.isNaN(value))
-        return 1;
-    if (value < 0)
-        return 0;
-    if (value > 1)
-        return 1;
-    return value;
-}
 /**
  * Trust Engine service with event emission and subscription limits
  */
 export class TrustEngine extends EventEmitter {
     records = new Map();
-    _decayRate;
-    _decayIntervalMs;
-    _failureThreshold;
-    _acceleratedDecayMultiplier;
-    _failureWindowMs;
-    _minFailuresForAcceleration;
+    _decayCheckIntervalMs;
     _persistence;
     _autoPersist;
     // Recovery configuration
@@ -91,26 +73,15 @@ export class TrustEngine extends EventEmitter {
     _listenerWarningThreshold;
     _listenerCounts = new Map();
     _totalListeners = 0;
-    _readinessMode;
-    _readinessCheckpointDays;
-    _readinessCheckpointReductions;
-    _allowedReadinessExceptionReasons;
-    _readinessExceptionMaxDurationMs;
     constructor(config = {}) {
         super();
-        this._decayRate = config.decayRate ?? 0.01;
-        this._decayIntervalMs = config.decayIntervalMs ?? 60000;
-        this._failureThreshold = config.failureThreshold ?? 0.3;
-        this._acceleratedDecayMultiplier = config.acceleratedDecayMultiplier ?? 1.0;
-        this._failureWindowMs = config.failureWindowMs ?? 3600000; // 1 hour
-        this._minFailuresForAcceleration = config.minFailuresForAcceleration ?? 2;
+        this._decayCheckIntervalMs = config.decayCheckIntervalMs ?? 60000;
         this._persistence = config.persistence;
-        this._autoPersist = config.autoPersist ?? config.persistence !== undefined;
+        this._autoPersist = config.autoPersist ?? (config.persistence !== undefined);
         // Recovery configuration
         this._successThreshold = config.successThreshold ?? 0.7;
         this._recoveryRate = config.recoveryRate ?? 0.02;
-        this._acceleratedRecoveryMultiplier =
-            config.acceleratedRecoveryMultiplier ?? 1.5;
+        this._acceleratedRecoveryMultiplier = config.acceleratedRecoveryMultiplier ?? 1.5;
         this._minSuccessesForAcceleration = config.minSuccessesForAcceleration ?? 3;
         this._successWindowMs = config.successWindowMs ?? 3600000; // 1 hour
         this._maxRecoveryPerSignal = config.maxRecoveryPerSignal ?? 50;
@@ -118,219 +89,9 @@ export class TrustEngine extends EventEmitter {
         this._maxListenersPerEvent = config.maxListenersPerEvent ?? 100;
         this._maxTotalListeners = config.maxTotalListeners ?? 1000;
         this._listenerWarningThreshold = config.listenerWarningThreshold ?? 0.8;
-        this._readinessMode =
-            config.readinessMode ??
-                config.freshnessMode ??
-                (config.decayIntervalMs !== undefined || config.decayRate !== undefined
-                    ? "legacy_interval"
-                    : "checkpoint_schedule");
-        this._readinessCheckpointDays = config.readinessCheckpointDays ??
-            config.freshnessCheckpointDays ?? [...DEFAULT_READINESS_CHECKPOINT_DAYS];
-        this._readinessCheckpointReductions =
-            config.readinessCheckpointReductions ??
-                config.freshnessCheckpointReductions ?? [
-                ...DEFAULT_READINESS_REDUCTIONS,
-            ];
-        if (this._readinessCheckpointDays.length !==
-            this._readinessCheckpointReductions.length) {
-            throw new Error("freshnessCheckpointDays and freshnessCheckpointReductions must have equal length");
-        }
-        this._allowedReadinessExceptionReasons = new Set(config.readinessExceptionAllowedReasons ??
-            config.freshnessExceptionAllowedReasons ?? [
-            ...READINESS_EXCEPTION_REASON_CODES,
-        ]);
-        this._readinessExceptionMaxDurationMs =
-            config.readinessExceptionMaxDurationMs ??
-                config.freshnessExceptionMaxDurationMs ??
-                DEFAULT_READINESS_EXCEPTION_MAX_DURATION_MS;
         // Set default max listeners on EventEmitter
         this.setMaxListeners(this._maxListenersPerEvent);
     }
-    validateReadinessExceptionOptions(options) {
-        if (!this._allowedReadinessExceptionReasons.has(options.reason)) {
-            throw new Error(`Unsupported readiness exception reason: ${options.reason}. ` +
-                `Allowed reasons: ${Array.from(this._allowedReadinessExceptionReasons).join(", ")}`);
-        }
-        const now = Date.now();
-        const expiresAtMs = new Date(options.expiresAt).getTime();
-        if (Number.isNaN(expiresAtMs)) {
-            throw new Error("Invalid expiresAt timestamp for readiness exception");
-        }
-        if (expiresAtMs <= now) {
-            throw new Error("Readiness exception expiresAt must be in the future");
-        }
-        if (expiresAtMs - now > this._readinessExceptionMaxDurationMs) {
-            throw new Error(`Readiness exception duration exceeds configured maximum (${this._readinessExceptionMaxDurationMs} ms)`);
-        }
-    }
-    getCheckpointIntervalMs(index) {
-        if (index <= 0) {
-            return toMs(this._readinessCheckpointDays[0] ?? 7);
-        }
-        const current = this._readinessCheckpointDays[index] ??
-            this._readinessCheckpointDays[this._readinessCheckpointDays.length - 1] ??
-            7;
-        const previous = this._readinessCheckpointDays[index - 1] ?? 0;
-        return toMs(Math.max(1, current - previous));
-    }
-    ensureReadinessState(record) {
-        record.readinessCheckpointIndex ??= record.freshnessCheckpointIndex ?? 0;
-        record.deferredReadinessMultiplier ??=
-            record.deferredFreshnessMultiplier ?? 1;
-        record.readinessBaselineScore ??=
-            record.freshnessBaselineScore ?? record.score;
-        record.freshnessCheckpointIndex = record.readinessCheckpointIndex;
-        record.deferredFreshnessMultiplier = record.deferredReadinessMultiplier;
-        record.freshnessBaselineScore = record.readinessBaselineScore;
-        record.freshnessException =
-            record.readinessException ?? record.freshnessException;
-    }
-    isUsingDefaultReadinessSchedule() {
-        if (this._readinessCheckpointDays.length !==
-            DEFAULT_READINESS_CHECKPOINT_DAYS.length) {
-            return false;
-        }
-        if (this._readinessCheckpointReductions.length !==
-            DEFAULT_READINESS_REDUCTIONS.length) {
-            return false;
-        }
-        return (this._readinessCheckpointDays.every((v, i) => v === DEFAULT_READINESS_CHECKPOINT_DAYS[i]) &&
-            this._readinessCheckpointReductions.every((v, i) => v === DEFAULT_READINESS_REDUCTIONS[i]));
-    }
-    isReadinessExceptionActive(record, now) {
-        const exception = record.readinessException ?? record.freshnessException;
-        if (!exception)
-            return false;
-        const issuedAt = new Date(exception.issuedAt).getTime();
-        const expiresAt = new Date(exception.expiresAt).getTime();
-        return now >= issuedAt && now < expiresAt;
-    }
-    async applyDeferredReadinessCatchupIfExpired(record) {
-        const exception = record.readinessException ?? record.freshnessException;
-        if (!exception)
-            return;
-        const now = Date.now();
-        const expiresAt = new Date(exception.expiresAt).getTime();
-        if (now < expiresAt)
-            return;
-        this.ensureReadinessState(record);
-        const deferredMultiplier = record.deferredReadinessMultiplier ?? 1;
-        if (deferredMultiplier < 1) {
-            const previousScore = record.score;
-            const adjustedScore = Math.max(0, Math.round(record.score * deferredMultiplier));
-            record.score = adjustedScore;
-            record.level = this.scoreToLevel(adjustedScore);
-            record.deferredReadinessMultiplier = 1;
-            record.deferredFreshnessMultiplier = 1;
-            this.emitReadinessAdjustmentEvents(record.entityId, {
-                previousScore,
-                newScore: record.score,
-                stalenessMs: 0,
-                accelerated: false,
-            });
-        }
-        delete record.readinessException;
-        delete record.freshnessException;
-    }
-    async applyScheduledReadinessAdjustment(record) {
-        this.ensureReadinessState(record);
-        await this.applyDeferredReadinessCatchupIfExpired(record);
-        while ((record.readinessCheckpointIndex ?? 0) <
-            this._readinessCheckpointDays.length) {
-            const checkpointIndex = record.readinessCheckpointIndex ?? 0;
-            const intervalMs = this.getCheckpointIntervalMs(checkpointIndex);
-            const stalenessMs = Date.now() - new Date(record.lastCalculatedAt).getTime();
-            if (stalenessMs < intervalMs) {
-                break;
-            }
-            const previousScore = record.score;
-            const previousLevel = record.level;
-            const fullReduction = this._readinessCheckpointReductions[checkpointIndex] ?? 0;
-            const activeException = this.isReadinessExceptionActive(record, Date.now());
-            const scale = activeException
-                ? clampReductionScale((record.readinessException ?? record.freshnessException)
-                    ?.reductionScale)
-                : 1;
-            const appliedReduction = fullReduction * scale;
-            const appliedMultiplier = 1 - appliedReduction;
-            const fullMultiplier = 1 - fullReduction;
-            record.score = Math.max(0, Math.round(record.score * appliedMultiplier));
-            const isFinalCheckpoint = checkpointIndex === this._readinessCheckpointDays.length - 1;
-            if (isFinalCheckpoint &&
-                !activeException &&
-                this.isUsingDefaultReadinessSchedule()) {
-                const baseline = record.readinessBaselineScore ??
-                    record.freshnessBaselineScore ??
-                    record.score;
-                record.score = Math.max(0, Math.round(baseline * 0.5));
-            }
-            record.level = this.scoreToLevel(record.score);
-            record.readinessCheckpointIndex = checkpointIndex + 1;
-            record.freshnessCheckpointIndex = record.readinessCheckpointIndex;
-            const lastCalculatedMs = new Date(record.lastCalculatedAt).getTime();
-            record.lastCalculatedAt = new Date(lastCalculatedMs + intervalMs).toISOString();
-            if (activeException && appliedMultiplier > 0 && fullMultiplier >= 0) {
-                const debtFactor = fullMultiplier / appliedMultiplier;
-                record.deferredReadinessMultiplier =
-                    (record.deferredReadinessMultiplier ?? 1) * debtFactor;
-                record.deferredFreshnessMultiplier = record.deferredReadinessMultiplier;
-            }
-            if (previousScore !== record.score) {
-                this.emitReadinessAdjustmentEvents(record.entityId, {
-                    previousScore,
-                    newScore: record.score,
-                    stalenessMs,
-                    accelerated: false,
-                });
-                if (previousLevel !== record.level) {
-                    this.emitTrustEvent({
-                        type: "trust:tier_changed",
-                        entityId: record.entityId,
-                        timestamp: new Date().toISOString(),
-                        previousLevel,
-                        newLevel: record.level,
-                        previousLevelName: TRUST_LEVEL_NAMES[previousLevel],
-                        newLevelName: TRUST_LEVEL_NAMES[record.level],
-                        direction: record.level < previousLevel ? "demoted" : "promoted",
-                    });
-                }
-                await this.autoPersistRecord(record);
-            }
-        }
-    }
-    emitReadinessAdjustmentEvents(entityId, details) {
-        const adjustmentAmount = details.previousScore - details.newScore;
-        this.emitTrustEvent({
-            type: "trust:readiness_adjusted",
-            entityId,
-            timestamp: new Date().toISOString(),
-            previousScore: details.previousScore,
-            newScore: details.newScore,
-            adjustmentAmount,
-            stalenessMs: details.stalenessMs,
-            accelerated: details.accelerated,
-        });
-        this.emitTrustEvent({
-            type: "trust:freshness_adjusted",
-            entityId,
-            timestamp: new Date().toISOString(),
-            previousScore: details.previousScore,
-            newScore: details.newScore,
-            adjustmentAmount,
-            stalenessMs: details.stalenessMs,
-            accelerated: details.accelerated,
-        });
-        this.emitTrustEvent({
-            type: "trust:decay_applied",
-            entityId,
-            timestamp: new Date().toISOString(),
-            previousScore: details.previousScore,
-            newScore: details.newScore,
-            decayAmount: adjustmentAmount,
-            stalenessMs: details.stalenessMs,
-            accelerated: details.accelerated,
-        });
-    }
     /**
      * Add event listener with subscription limits
      * @throws Error if listener limits are exceeded
@@ -401,14 +162,10 @@ export class TrustEngine extends EventEmitter {
         const eventThreshold = this._maxListenersPerEvent * this._listenerWarningThreshold;
         const totalThreshold = this._maxTotalListeners * this._listenerWarningThreshold;
         if (currentEventCount >= eventThreshold) {
-            logger.warn({
-                eventName,
-                current: currentEventCount,
-                max: this._maxListenersPerEvent,
-            }, `Approaching listener limit for event "${eventName}"`);
+            logger.warn({ eventName, current: currentEventCount, max: this._maxListenersPerEvent }, `Approaching listener limit for event "${eventName}"`);
         }
         if (this._totalListeners >= totalThreshold) {
-            logger.warn({ current: this._totalListeners, max: this._maxTotalListeners }, "Approaching total listener limit");
+            logger.warn({ current: this._totalListeners, max: this._maxTotalListeners }, 'Approaching total listener limit');
         }
     }
     /**
@@ -441,28 +198,10 @@ export class TrustEngine extends EventEmitter {
         };
     }
     /**
-     * Get the current decay rate
-     */
-    get decayRate() {
-        return this._decayRate;
-    }
-    /**
-     * Get the decay interval in milliseconds
-     */
-    get decayIntervalMs() {
-        return this._decayIntervalMs;
-    }
-    /**
-     * Get the failure threshold
-     */
-    get failureThreshold() {
-        return this._failureThreshold;
-    }
-    /**
-     * Get the accelerated decay multiplier
+     * Get the decay check interval in milliseconds
      */
-    get acceleratedDecayMultiplier() {
-        return this._acceleratedDecayMultiplier;
+    get decayCheckIntervalMs() {
+        return this._decayCheckIntervalMs;
     }
     /**
      * Get the persistence provider
@@ -493,14 +232,14 @@ export class TrustEngine extends EventEmitter {
      */
     async loadFromPersistence() {
         if (!this._persistence) {
-            throw new Error("No persistence provider configured");
+            throw new Error('No persistence provider configured');
         }
         const records = await this._persistence.query();
         this.records.clear();
         for (const record of records) {
             this.records.set(record.entityId, record);
         }
-        logger.info({ count: records.length }, "Loaded trust records from persistence");
+        logger.info({ count: records.length }, 'Loaded trust records from persistence');
         return records.length;
     }
     /**
@@ -508,14 +247,14 @@ export class TrustEngine extends EventEmitter {
      */
     async saveToPersistence() {
         if (!this._persistence) {
-            throw new Error("No persistence provider configured");
+            throw new Error('No persistence provider configured');
         }
         let count = 0;
         for (const record of this.records.values()) {
             await this._persistence.save(record);
             count++;
         }
-        logger.info({ count }, "Saved trust records to persistence");
+        logger.info({ count }, 'Saved trust records to persistence');
         return count;
     }
     /**
@@ -540,8 +279,8 @@ export class TrustEngine extends EventEmitter {
      */
     emitTrustEvent(event) {
         this.emit(event.type, event);
-        this.emit("trust:*", event); // Wildcard for all events
-        logger.debug({ event }, "Trust event emitted");
+        this.emit('trust:*', event); // Wildcard for all events
+        logger.debug({ event }, 'Trust event emitted');
     }
     /**
      * Calculate trust score for an entity
@@ -549,41 +288,34 @@ export class TrustEngine extends EventEmitter {
     async calculate(entityId) {
         const record = this.records.get(entityId);
         const signals = record?.signals ?? [];
-        const currentLevel = record?.level ?? 1;
-        // Calculate component scores
-        const components = this.calculateComponents(signals, currentLevel);
-        // Calculate weighted total
-        const score = Math.round(components.behavioral * SIGNAL_WEIGHTS.behavioral * 1000 +
-            components.compliance * SIGNAL_WEIGHTS.compliance * 1000 +
-            components.identity * SIGNAL_WEIGHTS.identity * 1000 +
-            components.context * SIGNAL_WEIGHTS.context * 1000);
+        // Calculate factor scores (16-factor model)
+        const factorScores = this.calculateFactorScores(signals);
+        // Calculate weighted total using factor weights
+        let score = 0;
+        for (const code of FACTOR_CODES) {
+            score += factorScores[code] * FACTOR_WEIGHTS[code] * 1000;
+        }
+        score = Math.round(score);
+        // Guard: if factor arithmetic produced NaN/Infinity, fall back to 0
+        if (!Number.isFinite(score)) {
+            logger.warn({ entityId, score }, 'Score computation produced non-finite value, defaulting to 0');
+            score = 0;
+        }
         // Clamp to valid range
         const clampedScore = Math.max(0, Math.min(1000, score));
         const level = this.scoreToLevel(clampedScore);
+        // Backwards compat: also compute legacy 4-bucket components
+        const components = this.calculateComponents(signals);
         const factors = this.getSignificantFactors(components);
-        logger.debug({ entityId, score: clampedScore, level, components }, "Trust calculated");
+        logger.debug({ entityId, score: clampedScore, level, factorScores }, 'Trust calculated');
         return {
             score: clampedScore,
             level,
             components,
+            factorScores,
             factors,
         };
     }
-    /**
-     * Check if an entity has accelerated decay active
-     */
-    hasAcceleratedDecay(record) {
-        const now = Date.now();
-        const recentFailures = record.recentFailures.filter((timestamp) => now - new Date(timestamp).getTime() < this._failureWindowMs);
-        return recentFailures.length >= this._minFailuresForAcceleration;
-    }
-    /**
-     * Clean up old failure timestamps outside the window
-     */
-    cleanupFailures(record) {
-        const now = Date.now();
-        record.recentFailures = record.recentFailures.filter((timestamp) => now - new Date(timestamp).getTime() < this._failureWindowMs);
-    }
     /**
      * Clean up old success timestamps outside the window
      */
@@ -628,7 +360,7 @@ export class TrustEngine extends EventEmitter {
         record.lastCalculatedAt = new Date().toISOString();
         // Emit recovery event
         this.emitTrustEvent({
-            type: "trust:recovery_applied",
+            type: 'trust:recovery_applied',
             entityId: record.entityId,
             timestamp: new Date().toISOString(),
             signal,
@@ -641,10 +373,10 @@ export class TrustEngine extends EventEmitter {
         // Check for milestones
         if (previousLevel !== record.level && record.level > previousLevel) {
             this.emitTrustEvent({
-                type: "trust:recovery_milestone",
+                type: 'trust:recovery_milestone',
                 entityId: record.entityId,
                 timestamp: new Date().toISOString(),
-                milestone: "tier_restored",
+                milestone: 'tier_restored',
                 previousScore,
                 newScore: record.score,
                 details: `Promoted from ${TRUST_LEVEL_NAMES[previousLevel]} to ${TRUST_LEVEL_NAMES[record.level]}`,
@@ -653,10 +385,10 @@ export class TrustEngine extends EventEmitter {
         // Check if accelerated recovery was just earned
         if (record.consecutiveSuccesses === this._minSuccessesForAcceleration) {
             this.emitTrustEvent({
-                type: "trust:recovery_milestone",
+                type: 'trust:recovery_milestone',
                 entityId: record.entityId,
                 timestamp: new Date().toISOString(),
-                milestone: "accelerated_recovery_earned",
+                milestone: 'accelerated_recovery_earned',
                 previousScore,
                 newScore: record.score,
                 details: `Earned accelerated recovery after ${this._minSuccessesForAcceleration} consecutive successes`,
@@ -665,10 +397,10 @@ export class TrustEngine extends EventEmitter {
         // Check for full recovery
         if (record.score >= record.peakScore && previousScore < record.peakScore) {
             this.emitTrustEvent({
-                type: "trust:recovery_milestone",
+                type: 'trust:recovery_milestone',
                 entityId: record.entityId,
                 timestamp: new Date().toISOString(),
-                milestone: "full_recovery",
+                milestone: 'full_recovery',
                 previousScore,
                 newScore: record.score,
                 details: `Fully recovered to peak score of ${record.peakScore}`,
@@ -680,7 +412,7 @@ export class TrustEngine extends EventEmitter {
             newScore: record.score,
             recoveryAmount,
             accelerated,
-        }, "Trust recovery applied");
+        }, 'Trust recovery applied');
     }
     /**
      * Get trust score for an entity (with automatic decay)
@@ -688,25 +420,14 @@ export class TrustEngine extends EventEmitter {
     async getScore(entityId) {
         const record = this.records.get(entityId);
         if (record) {
-            // Clean up old failures
-            this.cleanupFailures(record);
-            if (this._readinessMode === "checkpoint_schedule") {
-                await this.applyScheduledReadinessAdjustment(record);
-                return record;
-            }
-            // Apply decay if stale
+            // Apply decay if enough time has passed since last check
             const staleness = Date.now() - new Date(record.lastCalculatedAt).getTime();
-            if (staleness > this._decayIntervalMs) {
+            if (staleness > this._decayCheckIntervalMs) {
                 const previousScore = record.score;
                 const previousLevel = record.level;
-                // Check if accelerated decay should apply
-                const accelerated = this.hasAcceleratedDecay(record);
-                const effectiveDecayRate = accelerated
-                    ? this._decayRate * this._acceleratedDecayMultiplier
-                    : this._decayRate;
-                // Apply decay based on staleness
-                const decayPeriods = Math.floor(staleness / this._decayIntervalMs);
-                const decayMultiplier = Math.pow(1 - effectiveDecayRate, decayPeriods);
+                // Milestone-based decay: convert staleness to days, apply stepped multiplier
+                const daysSinceActivity = staleness / (24 * 60 * 60 * 1000);
+                const decayMultiplier = calculateDecayMultiplier(daysSinceActivity);
                 const decayedScore = Math.round(record.score * decayMultiplier);
                 const clampedScore = Math.max(0, decayedScore);
                 record.score = clampedScore;
@@ -715,26 +436,25 @@ export class TrustEngine extends EventEmitter {
                 // Emit decay event
                 if (previousScore !== record.score) {
                     this.emitTrustEvent({
-                        type: "trust:decay_applied",
+                        type: 'trust:decay_applied',
                         entityId,
                         timestamp: new Date().toISOString(),
                         previousScore,
                         newScore: record.score,
                         decayAmount: previousScore - record.score,
                         stalenessMs: staleness,
-                        accelerated,
                     });
                     // Emit tier change if applicable
                     if (previousLevel !== record.level) {
                         this.emitTrustEvent({
-                            type: "trust:tier_changed",
+                            type: 'trust:tier_changed',
                             entityId,
                             timestamp: new Date().toISOString(),
                             previousLevel,
                             newLevel: record.level,
                             previousLevelName: TRUST_LEVEL_NAMES[previousLevel],
                             newLevelName: TRUST_LEVEL_NAMES[record.level],
-                            direction: record.level < previousLevel ? "demoted" : "promoted",
+                            direction: record.level < previousLevel ? 'demoted' : 'promoted',
                         });
                     }
                     // Auto-persist after decay
@@ -744,10 +464,35 @@ export class TrustEngine extends EventEmitter {
         }
         return record;
     }
+    /**
+     * Validate a trust signal before ingestion.
+     * Rejects NaN, Infinity, out-of-range values, and missing required fields.
+     *
+     * @throws Error on invalid signal
+     */
+    validateSignal(signal) {
+        if (!signal) {
+            throw new Error('Signal is required');
+        }
+        if (!signal.entityId) {
+            throw new Error('Signal must have an entityId');
+        }
+        if (!signal.type || typeof signal.type !== 'string') {
+            throw new Error('Signal must have a non-empty string type');
+        }
+        if (!Number.isFinite(signal.value)) {
+            throw new Error(`Invalid signal value: ${signal.value} (must be a finite number)`);
+        }
+        if (signal.value < 0 || signal.value > 1) {
+            throw new Error(`Signal value out of range: ${signal.value} (must be 0.0–1.0)`);
+        }
+    }
     /**
      * Record a trust signal
+     * @throws Error if signal is invalid (NaN, out of range, missing fields)
      */
     async recordSignal(signal) {
+        this.validateSignal(signal);
         let record = this.records.get(signal.entityId);
         let isNewEntity = false;
         if (!record) {
@@ -757,28 +502,10 @@ export class TrustEngine extends EventEmitter {
         }
         const previousScore = record.score;
         const previousLevel = record.level;
-        // Detect failure signals
-        if (signal.value < this._failureThreshold) {
-            record.recentFailures.push(signal.timestamp);
-            this.cleanupFailures(record);
-            // Reset consecutive successes on failure
+        // Reset consecutive successes on low-value signals (below 0.3)
+        // Neutral signals (0.3-0.7) don't break the success streak
+        if (signal.value < 0.3) {
             record.consecutiveSuccesses = 0;
-            const acceleratedDecayActive = this.hasAcceleratedDecay(record);
-            this.emitTrustEvent({
-                type: "trust:failure_detected",
-                entityId: signal.entityId,
-                timestamp: new Date().toISOString(),
-                signal,
-                failureCount: record.recentFailures.length,
-                acceleratedDecayActive,
-            });
-            logger.warn({
-                entityId: signal.entityId,
-                signalType: signal.type,
-                signalValue: signal.value,
-                failureCount: record.recentFailures.length,
-                acceleratedDecayActive,
-            }, "Failure signal detected");
         }
         // Detect success signals and apply recovery
         if (signal.value >= this._successThreshold) {
@@ -796,7 +523,7 @@ export class TrustEngine extends EventEmitter {
                 signalValue: signal.value,
                 consecutiveSuccesses: record.consecutiveSuccesses,
                 recoveryAmount,
-            }, "Success signal detected");
+            }, 'Success signal detected');
         }
         // Add signal
         record.signals.push(signal);
@@ -810,13 +537,8 @@ export class TrustEngine extends EventEmitter {
         record.score = calculation.score;
         record.level = calculation.level;
         record.components = calculation.components;
+        record.factorScores = calculation.factorScores;
         record.lastCalculatedAt = new Date().toISOString();
-        record.readinessCheckpointIndex = 0;
-        record.deferredReadinessMultiplier = 1;
-        record.readinessBaselineScore = calculation.score;
-        record.freshnessCheckpointIndex = 0;
-        record.deferredFreshnessMultiplier = 1;
-        record.freshnessBaselineScore = calculation.score;
         // Record history if significant change
         if (Math.abs(calculation.score - previousScore) >= 10) {
             record.history.push({
@@ -832,7 +554,7 @@ export class TrustEngine extends EventEmitter {
         }
         // Emit signal recorded event
         this.emitTrustEvent({
-            type: "trust:signal_recorded",
+            type: 'trust:signal_recorded',
             entityId: signal.entityId,
             timestamp: new Date().toISOString(),
             signal,
@@ -842,7 +564,7 @@ export class TrustEngine extends EventEmitter {
         // Emit score changed event if significant
         if (Math.abs(calculation.score - previousScore) >= 5) {
             this.emitTrustEvent({
-                type: "trust:score_changed",
+                type: 'trust:score_changed',
                 entityId: signal.entityId,
                 timestamp: new Date().toISOString(),
                 previousScore,
@@ -854,14 +576,14 @@ export class TrustEngine extends EventEmitter {
         // Emit tier changed event if applicable
         if (previousLevel !== calculation.level && !isNewEntity) {
             this.emitTrustEvent({
-                type: "trust:tier_changed",
+                type: 'trust:tier_changed',
                 entityId: signal.entityId,
                 timestamp: new Date().toISOString(),
                 previousLevel,
                 newLevel: calculation.level,
                 previousLevelName: TRUST_LEVEL_NAMES[previousLevel],
                 newLevelName: TRUST_LEVEL_NAMES[calculation.level],
-                direction: calculation.level > previousLevel ? "promoted" : "demoted",
+                direction: calculation.level > previousLevel ? 'promoted' : 'demoted',
             });
         }
         // Auto-persist if enabled
@@ -870,13 +592,18 @@ export class TrustEngine extends EventEmitter {
             entityId: signal.entityId,
             signalType: signal.type,
             newScore: calculation.score,
-        }, "Signal recorded");
+        }, 'Signal recorded');
     }
     /**
      * Initialize trust for a new entity
      */
     async initializeEntity(entityId, initialLevel = 1) {
         const score = TRUST_THRESHOLDS[initialLevel].min;
+        // Initialize all 16 factors to 0.5
+        const initialFactorScores = {};
+        for (const code of FACTOR_CODES) {
+            initialFactorScores[code] = 0.5;
+        }
         const record = {
             entityId,
             score,
@@ -887,39 +614,33 @@ export class TrustEngine extends EventEmitter {
                 identity: 0.5,
                 context: 0.5,
             },
+            factorScores: initialFactorScores,
             signals: [],
             lastCalculatedAt: new Date().toISOString(),
             history: [
                 {
                     score,
                     level: initialLevel,
-                    reason: "Initial registration",
+                    reason: 'Initial registration',
                     timestamp: new Date().toISOString(),
                 },
             ],
-            recentFailures: [],
             recentSuccesses: [],
             peakScore: score,
             consecutiveSuccesses: 0,
-            readinessCheckpointIndex: 0,
-            deferredReadinessMultiplier: 1,
-            readinessBaselineScore: score,
-            freshnessCheckpointIndex: 0,
-            deferredFreshnessMultiplier: 1,
-            freshnessBaselineScore: score,
         };
         this.records.set(entityId, record);
         // Auto-persist if enabled
         await this.autoPersistRecord(record);
         // Emit initialized event
         this.emitTrustEvent({
-            type: "trust:initialized",
+            type: 'trust:initialized',
             entityId,
             timestamp: new Date().toISOString(),
             initialScore: score,
             initialLevel,
         });
-        logger.info({ entityId, initialLevel }, "Entity trust initialized");
+        logger.info({ entityId, initialLevel }, 'Entity trust initialized');
         return record;
     }
     /**
@@ -934,6 +655,76 @@ export class TrustEngine extends EventEmitter {
     getLevelName(level) {
         return TRUST_LEVEL_NAMES[level];
     }
+    /**
+     * Generate a human-readable explanation of an entity's current trust score.
+     *
+     * Provides full transparency into how the score was computed, including
+     * per-factor contributions, decay status, and what's needed to advance.
+     *
+     * @example
+     * ```ts
+     * const explanation = await engine.explainScore('agent-123');
+     * console.log(`Score: ${explanation.score} (${explanation.levelName})`);
+     * console.log(`Top factor: ${explanation.topPositiveFactors[0]}`);
+     * console.log(`Points to next tier: ${explanation.pointsToNextLevel}`);
+     * ```
+     */
+    async explainScore(entityId) {
+        const record = this.records.get(entityId);
+        if (!record) {
+            throw new Error(`Entity not found: ${entityId}`);
+        }
+        const signals = record.signals ?? [];
+        const factorScores = this.calculateFactorScores(signals);
+        // Build factor breakdown
+        const factorBreakdown = FACTOR_CODES.map((code) => {
+            const weight = FACTOR_WEIGHTS[code];
+            const rawScore = factorScores[code];
+            const contribution = Math.round(rawScore * weight * 1000 * 100) / 100;
+            return { code, weight, rawScore, contribution };
+        });
+        // Sort for top positive/negative
+        const sorted = [...factorBreakdown].sort((a, b) => b.contribution - a.contribution);
+        const midpoint = 0.5; // Neutral factor score
+        const topPositiveFactors = sorted
+            .filter((f) => f.rawScore > midpoint)
+            .slice(0, 5)
+            .map((f) => f.code);
+        const topNegativeFactors = sorted
+            .filter((f) => f.rawScore < midpoint)
+            .sort((a, b) => a.contribution - b.contribution)
+            .slice(0, 5)
+            .map((f) => f.code);
+        // Calculate decay
+        const lastSignalTime = signals.length > 0
+            ? Math.max(...signals.map((s) => new Date(s.timestamp).getTime()))
+            : null;
+        const daysSinceLastSignal = lastSignalTime !== null
+            ? (Date.now() - lastSignalTime) / (24 * 60 * 60 * 1000)
+            : null;
+        const decayMultiplier = daysSinceLastSignal !== null
+            ? calculateDecayMultiplier(daysSinceLastSignal)
+            : 1.0;
+        // Points to next level
+        const currentLevel = record.level;
+        const nextLevelThreshold = currentLevel < 7 ? TRUST_THRESHOLDS[(currentLevel + 1)] : null;
+        const pointsToNextLevel = nextLevelThreshold !== null ? nextLevelThreshold.min - record.score : null;
+        return {
+            entityId,
+            score: record.score,
+            level: currentLevel,
+            levelName: TRUST_LEVEL_NAMES[currentLevel],
+            levelRange: TRUST_THRESHOLDS[currentLevel],
+            pointsToNextLevel: pointsToNextLevel !== null && pointsToNextLevel > 0 ? pointsToNextLevel : null,
+            signalCount: signals.length,
+            factorBreakdown,
+            topPositiveFactors,
+            topNegativeFactors,
+            decayMultiplier: Math.round(decayMultiplier * 1000) / 1000,
+            daysSinceLastSignal: daysSinceLastSignal !== null ? Math.round(daysSinceLastSignal * 100) / 100 : null,
+            generatedAt: new Date().toISOString(),
+        };
+    }
     /**
      * Convert score to trust level
      */
@@ -946,25 +737,61 @@ export class TrustEngine extends EventEmitter {
         return 0;
     }
     /**
+     * @deprecated Use calculateFactorScores for 16-factor model. Kept for backwards compatibility.
      * Calculate component scores from signals
      */
-    calculateComponents(signals, currentLevel) {
+    calculateComponents(signals) {
         // Group signals by type
-        const behavioral = signals.filter((s) => s.type.startsWith("behavioral."));
-        const compliance = signals.filter((s) => s.type.startsWith("compliance."));
-        const identity = signals.filter((s) => s.type.startsWith("identity."));
-        const context = signals.filter((s) => s.type.startsWith("context."));
+        const behavioral = signals.filter((s) => s.type.startsWith('behavioral.'));
+        const compliance = signals.filter((s) => s.type.startsWith('compliance.'));
+        const identity = signals.filter((s) => s.type.startsWith('identity.'));
+        const context = signals.filter((s) => s.type.startsWith('context.'));
         return {
-            behavioral: this.averageSignalValue(behavioral, 0.5, currentLevel),
-            compliance: this.averageSignalValue(compliance, 0.5, currentLevel),
-            identity: this.averageSignalValue(identity, 0.5, currentLevel),
-            context: this.averageSignalValue(context, 0.5, currentLevel),
+            behavioral: this.averageSignalValue(behavioral, 0.5),
+            compliance: this.averageSignalValue(compliance, 0.5),
+            identity: this.averageSignalValue(identity, 0.5),
+            context: this.averageSignalValue(context, 0.5),
         };
     }
+    /**
+     * Calculate per-factor scores from signals.
+     * Signals can use either:
+     *   - Factor code prefix (e.g. 'CT-COMP.success')
+     *   - Legacy bucket prefix (e.g. 'behavioral.success') — mapped to factors via SIGNAL_PREFIX_TO_FACTORS
+     */
+    calculateFactorScores(signals) {
+        const factorSignals = {};
+        // Initialize all factors
+        for (const code of FACTOR_CODES) {
+            factorSignals[code] = [];
+        }
+        for (const signal of signals) {
+            const prefix = signal.type.split('.')[0];
+            // Check if it's a direct factor code
+            if (FACTOR_CODES.includes(prefix)) {
+                factorSignals[prefix].push(signal);
+                continue;
+            }
+            // Check if it's a legacy bucket prefix
+            const mappedFactors = SIGNAL_PREFIX_TO_FACTORS[prefix];
+            if (mappedFactors) {
+                // Distribute signal across mapped factors
+                for (const factorCode of mappedFactors) {
+                    factorSignals[factorCode].push(signal);
+                }
+            }
+        }
+        // Calculate average score for each factor
+        const scores = {};
+        for (const code of FACTOR_CODES) {
+            scores[code] = this.averageSignalValue(factorSignals[code], 0.5);
+        }
+        return scores;
+    }
     /**
      * Calculate average signal value with default
      */
-    averageSignalValue(signals, defaultValue, currentLevel) {
+    averageSignalValue(signals, defaultValue) {
         if (signals.length === 0)
             return defaultValue;
         // Weight recent signals more heavily
@@ -974,66 +801,27 @@ export class TrustEngine extends EventEmitter {
         for (const signal of signals) {
             const age = now - new Date(signal.timestamp).getTime();
             const weight = Math.exp(-age / (7 * 24 * 60 * 60 * 1000)); // 7-day half-life
-            const adjustedValue = this.adjustSignalValueForTier(signal, defaultValue, currentLevel);
-            weightedSum += adjustedValue * weight;
+            weightedSum += signal.value * weight;
             totalWeight += weight;
         }
         return totalWeight > 0 ? weightedSum / totalWeight : defaultValue;
     }
-    /**
-     * Human/manual positive approvals carry less upward impact at higher tiers.
-     */
-    adjustSignalValueForTier(signal, defaultValue, currentLevel) {
-        if (!this.isHumanApprovalSignal(signal) || signal.value <= defaultValue) {
-            return signal.value;
-        }
-        const assistFactor = this.getHumanApprovalAssistFactor(currentLevel);
-        return defaultValue + (signal.value - defaultValue) * assistFactor;
-    }
-    isHumanApprovalSignal(signal) {
-        const source = signal.source?.toLowerCase() ?? "";
-        return (source === "manual" ||
-            source === "human" ||
-            source === "human_review" ||
-            source === "human-approval");
-    }
-    getHumanApprovalAssistFactor(level) {
-        switch (level) {
-            case 0:
-            case 1:
-                return 1.0;
-            case 2:
-                return 0.85;
-            case 3:
-                return 0.7;
-            case 4:
-                return 0.55;
-            case 5:
-                return 0.4;
-            case 6:
-                return 0.3;
-            case 7:
-                return 0.2;
-            default:
-                return 1.0;
-        }
-    }
     /**
      * Get significant factors affecting the score
      */
     getSignificantFactors(components) {
         const factors = [];
         if (components.behavioral < 0.3) {
-            factors.push("Low behavioral trust");
+            factors.push('Low behavioral trust');
         }
         if (components.compliance < 0.3) {
-            factors.push("Low compliance score");
+            factors.push('Low compliance score');
         }
         if (components.identity < 0.3) {
-            factors.push("Weak identity verification");
+            factors.push('Weak identity verification');
         }
         if (components.context < 0.3) {
-            factors.push("Unusual context signals");
+            factors.push('Unusual context signals');
         }
         return factors;
     }
@@ -1042,6 +830,11 @@ export class TrustEngine extends EventEmitter {
      */
     createInitialRecord(entityId) {
         const initialScore = TRUST_THRESHOLDS[1].min;
+        // Initialize all 16 factors to 0.5
+        const initialFactorScores = {};
+        for (const code of FACTOR_CODES) {
+            initialFactorScores[code] = 0.5;
+        }
         return {
             entityId,
             score: initialScore, // Start at L1 (Provisional) minimum
@@ -1052,84 +845,15 @@ export class TrustEngine extends EventEmitter {
                 identity: 0.5,
                 context: 0.5,
             },
+            factorScores: initialFactorScores,
             signals: [],
             lastCalculatedAt: new Date().toISOString(),
             history: [],
-            recentFailures: [],
             recentSuccesses: [],
             peakScore: initialScore,
             consecutiveSuccesses: 0,
-            readinessCheckpointIndex: 0,
-            deferredReadinessMultiplier: 1,
-            readinessBaselineScore: initialScore,
-            freshnessCheckpointIndex: 0,
-            deferredFreshnessMultiplier: 1,
-            freshnessBaselineScore: initialScore,
         };
     }
-    /**
-     * Configure a time-bound Readiness Degree exception for an entity.
-     */
-    setReadinessException(entityId, options) {
-        const record = this.records.get(entityId);
-        if (!record) {
-            throw new Error(`Entity not found: ${entityId}`);
-        }
-        this.validateReadinessExceptionOptions(options);
-        this.ensureReadinessState(record);
-        record.readinessException = {
-            reason: options.reason,
-            issuedAt: new Date().toISOString(),
-            expiresAt: options.expiresAt,
-            reductionScale: clampReductionScale(options.reductionScale),
-        };
-        record.freshnessException = record.readinessException;
-    }
-    /**
-     * @deprecated Use setReadinessException.
-     */
-    setFreshnessException(entityId, options) {
-        this.setReadinessException(entityId, options);
-    }
-    /**
-     * Clear Readiness Degree exception for an entity.
-     */
-    clearReadinessException(entityId) {
-        const record = this.records.get(entityId);
-        if (!record) {
-            return;
-        }
-        delete record.readinessException;
-        delete record.freshnessException;
-    }
-    /**
-     * @deprecated Use clearReadinessException.
-     */
-    clearFreshnessException(entityId) {
-        this.clearReadinessException(entityId);
-    }
-    /**
-     * Get active Readiness Degree exception for an entity.
-     */
-    getReadinessException(entityId) {
-        const record = this.records.get(entityId);
-        return record?.readinessException ?? record?.freshnessException;
-    }
-    /**
-     * @deprecated Use getReadinessException.
-     */
-    getFreshnessException(entityId) {
-        return this.getReadinessException(entityId);
-    }
-    /**
-     * Check if accelerated decay is currently active for an entity
-     */
-    isAcceleratedDecayActive(entityId) {
-        const record = this.records.get(entityId);
-        if (!record)
-            return false;
-        return this.hasAcceleratedDecay(record);
-    }
     /**
      * Check if accelerated recovery is currently active for an entity
      */
@@ -1139,16 +863,6 @@ export class TrustEngine extends EventEmitter {
             return false;
         return this.hasAcceleratedRecovery(record);
     }
-    /**
-     * Get current failure count for an entity
-     */
-    getFailureCount(entityId) {
-        const record = this.records.get(entityId);
-        if (!record)
-            return 0;
-        this.cleanupFailures(record);
-        return record.recentFailures.length;
-    }
     /**
      * Get consecutive success count for an entity
      */