@goodandready/dsh-approval-gate 0.1.18 → 0.1.20

package/lib/compat.js

@@ -0,0 +1,124 @@
+// lib/compat.js
+// Host compatibility checks and polyfills across DeepSeek Harness minor versions (#106).
+
+/**
+ * Detects available runtime capabilities and services in the Cordis host context (#106).
+ *
+ * @param {any} ctx - Cordis / DSH host context
+ * @returns {{
+ *   hasContext: boolean,
+ *   hasToolsService: boolean,
+ *   hasPreExecuteHook: boolean,
+ *   hasProvideApi: boolean,
+ *   hasLocaleService: boolean,
+ *   harnessVersion: string | null
+ * }}
+ */
+export function detectHarnessCapabilities(ctx) {
+  if (!ctx || typeof ctx !== "object") {
+    return {
+      hasContext: false,
+      hasToolsService: false,
+      hasPreExecuteHook: false,
+      hasProvideApi: false,
+      hasLocaleService: false,
+      harnessVersion: null,
+    };
+  }
+
+  const getService = (name) => {
+    try {
+      if (typeof ctx.get === "function") return ctx.get(name);
+    } catch {
+      // ignore
+    }
+    return ctx[name];
+  };
+
+  const tools = getService("tools");
+  const locale = getService("locale");
+
+  const harnessVersion =
+    (typeof ctx.version === "string" && ctx.version) ||
+    (typeof process.env.DSH_VERSION === "string" && process.env.DSH_VERSION) ||
+    null;
+
+  return {
+    hasContext: true,
+    hasToolsService: Boolean(tools),
+    hasPreExecuteHook: typeof ctx.on === "function",
+    hasProvideApi: typeof ctx.provide === "function",
+    hasLocaleService: Boolean(locale && typeof locale.register === "function"),
+    harnessVersion,
+  };
+}
+
+/**
+ * Asserts host compatibility and identifies missing optional or required features (#106).
+ *
+ * @param {any} ctx
+ * @param {{ requireTools?: boolean }} [options]
+ * @returns {{ compatible: boolean, issues: string[], capabilities: ReturnType<typeof detectHarnessCapabilities> }}
+ */
+export function assertHarnessCompatibility(ctx, options = {}) {
+  const caps = detectHarnessCapabilities(ctx);
+  const issues = [];
+
+  if (!caps.hasContext) {
+    issues.push("Invalid or missing Cordis context object");
+  }
+
+  if (options.requireTools && !caps.hasToolsService) {
+    issues.push("Missing tools service in host context");
+  }
+
+  return {
+    compatible: issues.length === 0,
+    issues,
+    capabilities: caps,
+  };
+}
+
+/**
+ * Safely provides a service to the host context with backward-compatible polyfill (#106).
+ *
+ * @param {any} ctx
+ * @param {string} serviceName
+ * @param {any} serviceInstance
+ * @returns {boolean} True if successfully registered
+ */
+export function provideServicePolyfill(ctx, serviceName, serviceInstance) {
+  if (!ctx || typeof ctx !== "object" || !serviceName) return false;
+
+  if (typeof ctx.provide === "function") {
+    try {
+      ctx.provide(serviceName, serviceInstance);
+      return true;
+    } catch {
+      // fallback to property assignment below
+    }
+  }
+
+  ctx[serviceName] = serviceInstance;
+  return true;
+}
+
+/**
+ * Safely attaches an event hook to the host context with error boundary (#106).
+ *
+ * @param {any} ctx
+ * @param {string} event
+ * @param {(...args: any[]) => any} handler
+ * @returns {(() => void) | null} Unsubscribe dispose function or null
+ */
+export function registerHookPolyfill(ctx, event, handler) {
+  if (!ctx || typeof ctx.on !== "function" || typeof handler !== "function") {
+    return null;
+  }
+
+  try {
+    return ctx.on(event, handler);
+  } catch {
+    return null;
+  }
+}

package/lib/engine.js

@@ -1,11 +1,5 @@
 // lib/engine.js
-// 5-tier Security Decision Engine for dsh-approval-gate.
-// Waterfall:
-// P0: Hard Deny (Bands Band 0 + Declarative Rules Deny + inspectExecution hard denials + protected files + retry exhaustion + fail-closed audit)
-// P1: Session Grants & Declarative Allow (scoped temporary allowances and whitelists)
-// P2: Static Rules / Safe Allow (Bands Band 1 + safe read-only commands)
-// P3: Optional Semantic Classifier
-// P4: Human Ask Fallback (uncertain syntax / ambiguous commands / tripped breaker / declarative ask / lockedAsk)
+// 5-tier Security Decision Engine for dsh-approval-gate (P0-P4 Waterfall).
 
 import { BandsEngine } from "./bands.js";
 import { CircuitBreaker } from "./breaker.js";
@@ -20,6 +14,12 @@ import { BlockCounters } from "./counters.js";
 import { ContractGuard } from "./contract-guard.js";
 import { OverengineeringGuard } from "./overengineering.js";
 import { extractFilePath, DEFAULT_FILE_WRITE_TOOLS } from "./dispatcher.js";
+import { categorizeRiskBucket, extractRiskTags } from "./risk.js";
+import { ClassifierLatencyTracker } from "./latency.js";
+import { ArtifactRegistry } from "./artifacts.js";
+import { isRmCommand, extractRmTargets, suggestTrashAlternative } from "./trash.js";
+import { VersionGuard } from "./version-guard.js";
+import { loadAgentsRules, evaluateAgentsRules } from "./agents-parser.js";
 
 /**
  * Determine whether an operation belongs to a critical risk category requiring lockedAsk (#52).
@@ -71,26 +71,7 @@ export function isCriticalOperation(toolName, command, execution) {
 }
 
 export class SecurityEngine {
-  /**
-   * @param {{
-   *   bands?: BandsEngine,
-   *   breaker?: CircuitBreaker,
-   *   cache?: VerdictCache,
-   *   retryGuard?: RetryExhaustionGuard,
-   *   ledger?: QualityLedger,
-   *   auditLogger?: AuditLogger,
-   *   declarativeRules?: DeclarativeRulesEngine,
-   *   counters?: BlockCounters,
-   *   auditFailClosed?: boolean,
-   *   timeoutPolicy?: "strict" | "permissive",
-   *   inspectConfig?: { toolName?: string, fileWriteTools?: string[], workspaceDir?: string },
-   *   classifier?: ((execution: any, context?: any) => { verdict: "allow"|"deny", reason?: string }),
-   *   grantRegistry?: { decide: (tool: string, args: any, context?: any) => "allow"|"no-match" },
-   *   dryRun?: boolean,
-   *   shadowMode?: boolean,
-   *   defaultVerdict?: "allow" | "ask"
-   * }} [options]
-   */
+  /** @param {Record<string, any>} [options] */
   constructor(options = {}) {
     this.bands = options.bands || new BandsEngine(options);
     this.breaker = options.breaker || new CircuitBreaker(options);
@@ -123,6 +104,16 @@ export class SecurityEngine {
       : (options.maxFilesPerSession !== undefined || options.maxCreatedFilesPerSession !== undefined
           ? new OverengineeringGuard(options)
           : null);
+    this.latencyTracker = options.latencyTracker || new ClassifierLatencyTracker(options);
+    this.artifactRegistry = options.artifactRegistry !== undefined
+      ? options.artifactRegistry
+      : new ArtifactRegistry({ workspaceDir: this.inspectConfig?.workspaceDir });
+    this.versionGuard = options.versionGuard !== undefined
+      ? options.versionGuard
+      : new VersionGuard({ workspaceDir: this.inspectConfig?.workspaceDir });
+    this.agentsRules = options.agentsRules !== undefined
+      ? options.agentsRules
+      : (loadAgentsRules(this.inspectConfig?.workspaceDir)?.rules || null);
   }
 
   /**
@@ -152,9 +143,9 @@ export class SecurityEngine {
         if (this.auditLogger) this.auditLogger.appendAuditLine({ sessionId, execution, decision: exhDecision, dryRun: this.dryRun });
 
         if (this.dryRun) {
-          return { verdict: "allow", stage: "P0", dryRun: true, originalVerdict: "deny", reason: "retry-exhaustion", detail: exhHit.detail, hit: exhHit };
+          return this._enrichDecision({ verdict: "allow", stage: "P0", dryRun: true, originalVerdict: "deny", reason: "retry-exhaustion", detail: exhHit.detail, hit: exhHit }, execution, context);
         }
-        return exhDecision;
+        return this._enrichDecision(exhDecision, execution, context);
       }
 
       // Check Verdict Cache (#63, #119)
@@ -163,7 +154,7 @@ export class SecurityEngine {
         const cached = this.cache.get(cacheKey);
         if (cached) {
           if (this.dryRun && (cached.verdict === "deny" || cached.verdict === "ask")) {
-            return {
+            return this._enrichDecision({
               verdict: "allow",
               stage: cached.stage,
               dryRun: true,
@@ -172,14 +163,15 @@ export class SecurityEngine {
               detail: cached.detail,
               hit: cached.hit,
               cached: true,
-            };
+            }, execution, context);
           }
           if (this.counters) this.counters.record(cached, execution);
-          return cached;
+          return this._enrichDecision(cached, execution, context);
         }
       }
 
       let decision = this._evaluateWaterfall(execution, context, sessionId, toolName, command);
+      this._enrichDecision(decision, execution, context);
 
       // Post-decision hooks: ledger, retryGuard, cache
       if (decision.verdict === "deny") {
@@ -190,6 +182,10 @@ export class SecurityEngine {
         if (this.retryGuard) this.retryGuard.recordVerdict(sessionId, execution, "allow");
         if (this.ledger) this.ledger.record(sessionId, "allow", { reason: decision.reason, detail: decision.detail, tool: toolName });
         if (this.cache && cacheKey) this.cache.set(cacheKey, decision, { sessionId });
+        if (this.artifactRegistry) {
+          const targetPath = extractFilePath(execution && execution.arguments);
+          if (targetPath) this.artifactRegistry.recordArtifact(sessionId, targetPath);
+        }
       } else if (decision.verdict === "ask") {
         if (this.ledger) this.ledger.record(sessionId, "ask", { reason: decision.reason, detail: decision.detail, tool: toolName });
       }
@@ -212,6 +208,7 @@ export class SecurityEngine {
             hit: auditDenyHit,
             auditFailed: true,
           };
+          this._enrichDecision(decision, execution, context);
         }
       }
 
@@ -222,7 +219,7 @@ export class SecurityEngine {
 
       // Shadow Mode (#128)
       if (this.dryRun && (decision.verdict === "deny" || decision.verdict === "ask")) {
-        return {
+        return this._enrichDecision({
           verdict: "allow",
           stage: decision.stage,
           dryRun: true,
@@ -231,7 +228,7 @@ export class SecurityEngine {
           detail: decision.detail,
           hit: decision.hit,
           lockedAsk: decision.lockedAsk,
-        };
+        }, execution, context);
       }
 
       return decision;
@@ -244,12 +241,12 @@ export class SecurityEngine {
         hit: { ask: true, reason: "inspect-error", detail: String(err && err.message || err) },
       };
       if (this.counters) this.counters.record(errDecision, execution);
-      return errDecision;
+      return this._enrichDecision(errDecision, execution, context);
     }
   }
 
   /**
-   * Asynchronous evaluation supporting async classifiers (#129, #118).
+   * Asynchronous evaluation supporting async classifiers and latency SLA tracking (#129, #118, #57).
    *
    * @param {{ name: string, arguments?: any }} execution
    * @param {{ sessionId?: string, knobs?: any, cwd?: string }} [context]
@@ -259,15 +256,31 @@ export class SecurityEngine {
     if (this.classifier) {
       let resolvedVerdict = null;
       let caughtError = null;
-      try {
-        if (typeof this.classifier.classify === "function") {
-          resolvedVerdict = await this.classifier.classify(execution, context);
-        } else if (typeof this.classifier === "function") {
-          const res = this.classifier(execution, context);
-          resolvedVerdict = res && typeof res.then === "function" ? await res : res;
+
+      if (this.latencyTracker && this.latencyTracker.isDegraded()) {
+        resolvedVerdict = {
+          verdict: "ask",
+          reason: "classifier-sla-fallback",
+          detail: `Classifier latency p95 (${this.latencyTracker.getP95()}ms) exceeded SLA (${this.latencyTracker.slaMs}ms) (#57)`,
+        };
+      } else {
+        const start = Date.now();
+        try {
+          if (typeof this.classifier.classify === "function") {
+            resolvedVerdict = await this.classifier.classify(execution, context);
+          } else if (typeof this.classifier === "function") {
+            const res = this.classifier(execution, context);
+            resolvedVerdict = res && typeof res.then === "function" ? await res : res;
+          }
+          if (this.latencyTracker) {
+            this.latencyTracker.recordSample(Date.now() - start);
+          }
+        } catch (err) {
+          caughtError = err;
+          if (this.latencyTracker) {
+            this.latencyTracker.recordSample(Date.now() - start);
+          }
         }
-      } catch (err) {
-        caughtError = err;
       }
 
       const originalClassifier = this.classifier;
@@ -320,6 +333,16 @@ export class SecurityEngine {
       }
     }
 
+    // AGENTS.md rules (#91)
+    if (this.agentsRules) {
+      const ag = evaluateAgentsRules(this.agentsRules, execution, extractFilePath(execution && execution.arguments));
+      if (ag.match) {
+        this.breaker.countDeny(sessionId);
+        const agHit = { deny: true, reason: ag.reason, detail: ag.rule?.text, snippet: command || toolName };
+        return { verdict: "deny", stage: "P0", reason: ag.reason, detail: ag.rule?.text, hit: agHit };
+      }
+    }
+
     // Inspect execution for hard denials and syntax checks
     const hit = inspectExecution(execution, this.inspectConfig);
     if (hit.deny) {
@@ -363,6 +386,31 @@ export class SecurityEngine {
       }
     }
 
+    // VersionGuard: major version bump control (#95)
+    if (this.versionGuard && typeof toolName === "string" && fileTools.has(toolName)) {
+      const targetPath = extractFilePath(execution ? execution.arguments : undefined);
+      const content = execution?.arguments?.content || execution?.arguments?.code || execution?.arguments?.CodeContent || execution?.arguments?.text;
+      if (targetPath && content) {
+        const vg = this.versionGuard.inspectWrite(targetPath, content);
+        if (vg.majorBump) {
+          const vgHit = { ask: true, reason: "major-version-bump", detail: vg.detail, snippet: targetPath };
+          const res = { verdict: "ask", stage: "P4", reason: "major-version-bump", detail: vg.detail, hit: vgHit };
+          this._applyLockedAskIfCritical(res, toolName, command, execution);
+          return res;
+        }
+      }
+    }
+
+    // P1: Session Artifact Cleanup Whitelist (#100)
+    if (command && isRmCommand(command)) {
+      const targets = extractRmTargets(command);
+      if (targets.length > 0 && this.artifactRegistry && this.artifactRegistry.areAllSessionArtifacts(sessionId, targets)) {
+        this.breaker.resetConsecutive(sessionId);
+        const artHit = { allow: true, reason: "session-artifact-cleanup", snippet: command };
+        return { verdict: "allow", stage: "P1", reason: "session-artifact-cleanup", hit: artHit };
+      }
+    }
+
     // P1: Session Grants
     if (this.grantRegistry && typeof this.grantRegistry.decide === "function") {
       const grantMatch = this.grantRegistry.decide(toolName, execution.arguments, context);
@@ -509,4 +557,37 @@ export class SecurityEngine {
     if (this.cache) this.cache.clearSession(sessionId);
     return this.breaker.resume(sessionId, reason);
   }
+
+  /**
+   * Enriches decision with risk bucket (#58) and operational risk tags (#70).
+   * @private
+   */
+  _enrichDecision(decision, execution, context) {
+    if (!decision) return decision;
+    if (!decision.riskBucket) decision.riskBucket = categorizeRiskBucket(execution, context);
+    if (!decision.riskTags || !Array.isArray(decision.riskTags)) decision.riskTags = extractRiskTags(execution, context);
+    const command = execution && execution.arguments && execution.arguments.command;
+    if (command && isRmCommand(command)) {
+      decision.trashAlternative = suggestTrashAlternative(command, this.inspectConfig?.workspaceDir, context?.sessionId);
+    }
+    return decision;
+  }
+
+  getArtifacts(sessionId) {
+    return this.artifactRegistry ? this.artifactRegistry.getArtifacts(sessionId) : [];
+  }
+
+  clearArtifacts(sessionId) {
+    if (this.artifactRegistry) this.artifactRegistry.clearSession(sessionId);
+  }
+
+  getLatencyMetrics() {
+    return this.latencyTracker ? this.latencyTracker.getMetrics() : null;
+  }
+
+  resetLatencyTracker() {
+    if (this.latencyTracker) this.latencyTracker.reset();
+  }
 }
+
+

package/lib/index.js

@@ -3,6 +3,8 @@ import { BandsEngine } from "./bands.js";
 import { AuditLogger } from "./audit-log.js";
 import { DeclarativeRulesEngine } from "./rules-loader.js";
 import { LlmClassifier } from "./classifier.js";
+import { ClassifierLatencyTracker } from "./latency.js";
+import { assertHarnessCompatibility, provideServicePolyfill } from "./compat.js";
 import Schema from "@deepseek-ai/schemastery";
 
 if (typeof Schema.prototype?.volatile !== "function") {
@@ -236,8 +238,14 @@ export const Config = Schema.object({
   isolateTempRoots: Schema.boolean().default(true).volatile(),
   /** Maximum allowed created files per session to prevent overengineering (#89). */
   maxFilesPerSession: Schema.number().default(10).volatile(),
+  /** Maximum latency in ms before classifier degrades to deterministic rules (#57). */
+  classifierSlaMs: Schema.number().default(2000).volatile(),
   /** Task contract boundary rules (#87). */
   taskContract: Schema.any().volatile(),
+  /** Enforce project rules and constraints parsed from AGENTS.md (#91). */
+  agentsRules: Schema.boolean().default(true).volatile(),
+  /** Enforce human confirmation on breaking major dependency bumps in package.json (#95). */
+  versionGuard: Schema.boolean().default(true).volatile(),
   /** Security engine instance (internal/testing). */
   engine: Schema.any().hidden(),
 });
@@ -248,6 +256,7 @@ function logBlocked(ctx, hit, who) {
 }
 
 export function apply(ctx, config) {
+  const compat = assertHarnessCompatibility(ctx);
   const cfg = plainConfig(Config(plainConfig(config) || {}) || {});
   const toolName = cfg.toolName || DEFAULT_BASH_TOOL;
   const fileWriteTools = cfg.fileWriteTools || DEFAULT_FILE_WRITE_TOOLS.slice();
@@ -301,6 +310,9 @@ export function apply(ctx, config) {
     bands: new BandsEngine({ toolRegistry: ctx && ctx.tools }),
     classifier,
     timeoutPolicy: cfg.classifierTimeoutPolicy || "strict",
+    latencyTracker: new ClassifierLatencyTracker({
+      slaMs: cfg.classifierSlaMs !== undefined ? cfg.classifierSlaMs : 2000,
+    }),
     defaultVerdict: cfg.defaultVerdict || "allow",
     dryRun: Boolean(cfg.dryRun || cfg.shadowMode),
     auditFailClosed: Boolean(cfg.auditFailClosed),
@@ -326,6 +338,10 @@ export function apply(ctx, config) {
     getCounters: () => engine.getCounters(),
     resetCounters: () => engine.resetCounters(),
     getLedgerSummary: (sessionId) => engine.getLedgerSummary(sessionId),
+    getLatencyMetrics: () => (engine.getLatencyMetrics ? engine.getLatencyMetrics() : null),
+    resetLatencyTracker: () => (engine.resetLatencyTracker ? engine.resetLatencyTracker() : undefined),
+    getArtifacts: (sessionId) => (engine.getArtifacts ? engine.getArtifacts(sessionId) : []),
+    clearArtifacts: (sessionId) => (engine.clearArtifacts ? engine.clearArtifacts(sessionId) : undefined),
     getSnapshot: () => ({
       active: true,
       dryRun: Boolean(cfg.dryRun || cfg.shadowMode),
@@ -336,15 +352,11 @@ export function apply(ctx, config) {
       rulesCount: engine.declarativeRules ? engine.declarativeRules.count() : 0,
       cacheStats: engine.cache ? engine.cache.stats() : null,
       breakerState: engine.breaker ? engine.breaker.getState() : null,
+      latencyMetrics: engine.getLatencyMetrics ? engine.getLatencyMetrics() : null,
+      harnessCompat: compat.capabilities,
     }),
   };
-  if (ctx && typeof ctx === "object") {
-    if (typeof ctx.provide === "function") {
-      ctx.provide("approvalGate", gateService);
-    } else {
-      ctx.approvalGate = gateService;
-    }
-  }
+  provideServicePolyfill(ctx, "approvalGate", gateService);
 
   const hasPreExecute = ctx && typeof ctx.on === "function";
   if (hasPreExecute) {
@@ -536,42 +548,34 @@ export {
   DEFAULT_RETAIN_LINES,
   auditRotateContent,
 } from "./audit-log.js";
-export {
-  BlockCounters,
-  categorizeReason,
-} from "./counters.js";
-export {
-  isCriticalOperation,
-} from "./engine.js";
-export {
-  parseYaml,
-  parseScalar,
-  stripComment,
-} from "./yaml-parser.js";
-export {
-  matchConditionValue,
-  evaluateWhen,
-} from "./when-matcher.js";
-export {
-  HotwordsMatcher,
-  DEFAULT_HOTWORDS,
-  extractWords,
-} from "./hotwords.js";
-export {
-  DeclarativeRulesEngine,
-  BUILTIN_RULES_FILE,
-  WORKSPACE_RULES_REL,
-  USER_RULES_REL,
-} from "./rules-loader.js";
+export { BlockCounters, categorizeReason } from "./counters.js";
+export { isCriticalOperation } from "./engine.js";
+export { parseYaml, parseScalar, stripComment } from "./yaml-parser.js";
+export { matchConditionValue, evaluateWhen } from "./when-matcher.js";
+export { HotwordsMatcher, DEFAULT_HOTWORDS, extractWords } from "./hotwords.js";
+export { DeclarativeRulesEngine, BUILTIN_RULES_FILE, WORKSPACE_RULES_REL, USER_RULES_REL } from "./rules-loader.js";
 export {
   normalizeChatCompletionsUrl,
   withLlmRetry,
   sanitizeClassifierInput,
   truncateClassifierContext,
   isLowRiskExecution,
+  isShapeRejectError,
+  extractJsonPayload,
+  ClassifierVerdictSchema,
+  validateClassifierResponse,
   LlmClassifier,
 } from "./classifier.js";
 export { ContractGuard } from "./contract-guard.js";
 export { OverengineeringGuard, DEFAULT_MAX_FILES_PER_SESSION } from "./overengineering.js";
 export { resolveTempRoot, isGlobalTempPath, checkTempIsolation } from "./paths.js";
 export { computePayloadSize, scanPromptInjection } from "./inspect.js";
+export { RISK_BUCKETS, RISK_TAGS, categorizeRiskBucket, extractRiskTags } from "./risk.js";
+export { ClassifierLatencyTracker, DEFAULT_CLASSIFIER_SLA_MS } from "./latency.js";
+export { resolveTrashDir, isRmCommand, extractRmTargets, buildTrashCommand, suggestTrashAlternative } from "./trash.js";
+export { ArtifactRegistry, normalizeArtifactPath } from "./artifacts.js";
+export { parseAgentsSecurityRules, loadAgentsRules, evaluateAgentsRules } from "./agents-parser.js";
+export { detectHarnessCapabilities, assertHarnessCompatibility, provideServicePolyfill, registerHookPolyfill } from "./compat.js";
+export { parseSemver, isMajorBump, inspectPackageJsonDiff, VersionGuard } from "./version-guard.js";
+
+

package/lib/latency.js

@@ -0,0 +1,137 @@
+// lib/latency.js
+// Classifier latency tracking and SLA-based fallback on deterministic rules (#57).
+
+export const DEFAULT_CLASSIFIER_SLA_MS = 2000;
+export const DEFAULT_LATENCY_WINDOW_SIZE = 50;
+export const DEFAULT_DEGRADE_THRESHOLD_COUNT = 3;
+export const DEFAULT_RECOVERY_THRESHOLD_COUNT = 2;
+
+/**
+ * Tracks external semantic classifier latency with sliding window statistics and SLA health (#57).
+ */
+export class ClassifierLatencyTracker {
+  /**
+   * @param {{
+   *   slaMs?: number,
+   *   windowSize?: number,
+   *   degradeThresholdCount?: number,
+   *   recoveryThresholdCount?: number
+   * }} [options]
+   */
+  constructor(options = {}) {
+    this.slaMs = typeof options.slaMs === "number" && options.slaMs > 0
+      ? options.slaMs
+      : DEFAULT_CLASSIFIER_SLA_MS;
+    this.windowSize = typeof options.windowSize === "number" && options.windowSize > 0
+      ? options.windowSize
+      : DEFAULT_LATENCY_WINDOW_SIZE;
+    this.degradeThresholdCount = typeof options.degradeThresholdCount === "number" && options.degradeThresholdCount > 0
+      ? options.degradeThresholdCount
+      : DEFAULT_DEGRADE_THRESHOLD_COUNT;
+    this.recoveryThresholdCount = typeof options.recoveryThresholdCount === "number" && options.recoveryThresholdCount > 0
+      ? options.recoveryThresholdCount
+      : DEFAULT_RECOVERY_THRESHOLD_COUNT;
+
+    this._samples = [];
+    this._consecutiveSlow = 0;
+    this._consecutiveFast = 0;
+    this._degraded = false;
+  }
+
+  /**
+   * Records a latency observation in milliseconds.
+   *
+   * @param {number} durationMs
+   * @returns {{ degraded: boolean, p95Ms: number, avgMs: number }}
+   */
+  recordSample(durationMs) {
+    const val = Math.max(0, Number(durationMs) || 0);
+    this._samples.push(val);
+    if (this._samples.length > this.windowSize) {
+      this._samples.shift();
+    }
+
+    if (val > this.slaMs) {
+      this._consecutiveSlow += 1;
+      this._consecutiveFast = 0;
+      if (this._consecutiveSlow >= this.degradeThresholdCount) {
+        this._degraded = true;
+      }
+    } else {
+      this._consecutiveFast += 1;
+      this._consecutiveSlow = 0;
+      if (this._consecutiveFast >= this.recoveryThresholdCount) {
+        this._degraded = false;
+      }
+    }
+
+    if (!this._degraded && this._samples.length >= 5 && this.getP95() > this.slaMs && this._consecutiveSlow > 0) {
+      this._degraded = true;
+    }
+
+    return {
+      degraded: this.isDegraded(),
+      p95Ms: this.getP95(),
+      avgMs: this.getAvg(),
+    };
+  }
+
+  /**
+   * Calculates 95th percentile latency from the current sliding window.
+   * @returns {number}
+   */
+  getP95() {
+    if (this._samples.length === 0) return 0;
+    const sorted = this._samples.slice().sort((a, b) => a - b);
+    const idx = Math.min(sorted.length - 1, Math.max(0, Math.ceil(sorted.length * 0.95) - 1));
+    return Math.round(sorted[idx] * 10) / 10;
+  }
+
+  /**
+   * Calculates mean latency from current window.
+   * @returns {number}
+   */
+  getAvg() {
+    if (this._samples.length === 0) return 0;
+    const sum = this._samples.reduce((acc, v) => acc + v, 0);
+    return Math.round((sum / this._samples.length) * 10) / 10;
+  }
+
+  /**
+   * Checks whether the classifier is currently marked degraded due to SLA violations.
+   * @returns {boolean}
+   */
+  isDegraded() {
+    return this._degraded;
+  }
+
+  /**
+   * Resets all tracked samples and returns to healthy state.
+   */
+  reset() {
+    this._samples = [];
+    this._consecutiveSlow = 0;
+    this._consecutiveFast = 0;
+    this._degraded = false;
+  }
+
+  /**
+   * Returns a snapshot of current latency metrics.
+   * @returns {{ count: number, avgMs: number, p95Ms: number, minMs: number, maxMs: number, degraded: boolean, slaMs: number, consecutiveSlow: number }}
+   */
+  getMetrics() {
+    const count = this._samples.length;
+    const minMs = count > 0 ? Math.min(...this._samples) : 0;
+    const maxMs = count > 0 ? Math.max(...this._samples) : 0;
+    return {
+      count,
+      avgMs: this.getAvg(),
+      p95Ms: this.getP95(),
+      minMs,
+      maxMs,
+      degraded: this.isDegraded(),
+      slaMs: this.slaMs,
+      consecutiveSlow: this._consecutiveSlow,
+    };
+  }
+}