@vorionsys/atsf-core 0.2.2 → 0.2.3

package/dist/trust-engine/index.js

@@ -6,9 +6,11 @@
  *
  * @packageDocumentation
  */
-import { EventEmitter } from 'events';
-import { createLogger } from '../common/logger.js';
-const logger = createLogger({ component: 'trust-engine' });
+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" });
 /**
  * Trust level thresholds (8 tiers T0-T7) - per BASIS specification
  */
@@ -26,14 +28,14 @@ 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",
 };
 /**
  * Signal weights for score calculation
@@ -44,6 +46,25 @@ 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
  */
@@ -70,20 +91,26 @@ 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 ?? 3.0;
+        this._acceleratedDecayMultiplier = config.acceleratedDecayMultiplier ?? 1.0;
         this._failureWindowMs = config.failureWindowMs ?? 3600000; // 1 hour
         this._minFailuresForAcceleration = config.minFailuresForAcceleration ?? 2;
         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;
@@ -91,9 +118,219 @@ 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
@@ -164,10 +401,14 @@ 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");
         }
     }
     /**
@@ -252,14 +493,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;
     }
     /**
@@ -267,14 +508,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;
     }
     /**
@@ -299,8 +540,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
@@ -308,8 +549,9 @@ 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);
+        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 +
@@ -319,7 +561,7 @@ export class TrustEngine extends EventEmitter {
         const clampedScore = Math.max(0, Math.min(1000, score));
         const level = this.scoreToLevel(clampedScore);
         const factors = this.getSignificantFactors(components);
-        logger.debug({ entityId, score: clampedScore, level, components }, 'Trust calculated');
+        logger.debug({ entityId, score: clampedScore, level, components }, "Trust calculated");
         return {
             score: clampedScore,
             level,
@@ -386,7 +628,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,
@@ -399,10 +641,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]}`,
@@ -411,10 +653,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`,
@@ -423,10 +665,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}`,
@@ -438,7 +680,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)
@@ -448,6 +690,10 @@ export class TrustEngine extends EventEmitter {
         if (record) {
             // Clean up old failures
             this.cleanupFailures(record);
+            if (this._readinessMode === "checkpoint_schedule") {
+                await this.applyScheduledReadinessAdjustment(record);
+                return record;
+            }
             // Apply decay if stale
             const staleness = Date.now() - new Date(record.lastCalculatedAt).getTime();
             if (staleness > this._decayIntervalMs) {
@@ -469,7 +715,7 @@ 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,
@@ -481,14 +727,14 @@ export class TrustEngine extends EventEmitter {
                     // 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
@@ -519,7 +765,7 @@ export class TrustEngine extends EventEmitter {
             record.consecutiveSuccesses = 0;
             const acceleratedDecayActive = this.hasAcceleratedDecay(record);
             this.emitTrustEvent({
-                type: 'trust:failure_detected',
+                type: "trust:failure_detected",
                 entityId: signal.entityId,
                 timestamp: new Date().toISOString(),
                 signal,
@@ -532,7 +778,7 @@ export class TrustEngine extends EventEmitter {
                 signalValue: signal.value,
                 failureCount: record.recentFailures.length,
                 acceleratedDecayActive,
-            }, 'Failure signal detected');
+            }, "Failure signal detected");
         }
         // Detect success signals and apply recovery
         if (signal.value >= this._successThreshold) {
@@ -550,7 +796,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);
@@ -565,6 +811,12 @@ export class TrustEngine extends EventEmitter {
         record.level = calculation.level;
         record.components = calculation.components;
         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({
@@ -580,7 +832,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,
@@ -590,7 +842,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,
@@ -602,14 +854,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
@@ -618,7 +870,7 @@ export class TrustEngine extends EventEmitter {
             entityId: signal.entityId,
             signalType: signal.type,
             newScore: calculation.score,
-        }, 'Signal recorded');
+        }, "Signal recorded");
     }
     /**
      * Initialize trust for a new entity
@@ -641,7 +893,7 @@ export class TrustEngine extends EventEmitter {
                 {
                     score,
                     level: initialLevel,
-                    reason: 'Initial registration',
+                    reason: "Initial registration",
                     timestamp: new Date().toISOString(),
                 },
             ],
@@ -649,19 +901,25 @@ export class TrustEngine extends EventEmitter {
             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;
     }
     /**
@@ -690,23 +948,23 @@ export class TrustEngine extends EventEmitter {
     /**
      * Calculate component scores from signals
      */
-    calculateComponents(signals) {
+    calculateComponents(signals, currentLevel) {
         // 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),
-            compliance: this.averageSignalValue(compliance, 0.5),
-            identity: this.averageSignalValue(identity, 0.5),
-            context: this.averageSignalValue(context, 0.5),
+            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),
         };
     }
     /**
      * Calculate average signal value with default
      */
-    averageSignalValue(signals, defaultValue) {
+    averageSignalValue(signals, defaultValue, currentLevel) {
         if (signals.length === 0)
             return defaultValue;
         // Weight recent signals more heavily
@@ -716,27 +974,66 @@ 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
-            weightedSum += signal.value * weight;
+            const adjustedValue = this.adjustSignalValueForTier(signal, defaultValue, currentLevel);
+            weightedSum += adjustedValue * 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;
     }
@@ -762,7 +1059,67 @@ export class TrustEngine extends EventEmitter {
             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