@goodandready/dsh-key-rotation 0.8.77 → 0.8.79

package/lib/client-src/60-header-chip.js

@@ -0,0 +1,137 @@
+    // (issue 201, #499) header chip: one dot + counts for all pools. Green = all healthy,
+    // amber = some keys cooling, red = a pool fully exhausted. Click opens quick actions popover.
+    function KeyRotationHeaderChip(props) {
+      const t = resolveT(props);
+      const [snap, setSnap] = React.useState(null);
+      const [open, setOpen] = React.useState(false);
+      const [, setTick] = React.useState(0);
+      const [busy, setBusy] = React.useState(false);
+      const ref = React.useRef(null);
+
+      const load = () => {
+        if (typeof document !== 'undefined' && document.visibilityState !== 'visible') return;
+        fetch('/dsh-key-rotation/health', {
+          headers: { accept: 'application/json' },
+          credentials: 'same-origin',
+          signal: (typeof AbortSignal !== 'undefined' && typeof AbortSignal.timeout === 'function') ? AbortSignal.timeout(8000) : undefined
+        })
+          .then((r) => (r.ok ? r.json() : null))
+          .then((d) => { if (d) setSnap(d); })
+          .catch((e) => { void e; });
+      };
+
+      React.useEffect(() => {
+        load();
+        const id = setInterval(load, 5000);
+        const onVis = () => { if (typeof document !== 'undefined' && document.visibilityState === 'visible') load(); };
+        if (typeof document !== 'undefined') document.addEventListener('visibilitychange', onVis);
+        return () => {
+          clearInterval(id);
+          if (typeof document !== 'undefined') document.removeEventListener('visibilitychange', onVis);
+        };
+      }, []);
+
+      React.useEffect(() => {
+        if (!props?.settingsSource?.subscribe) return;
+        return props.settingsSource.subscribe(() => {
+          setTick((c) => c + 1);
+        });
+      }, [props?.settingsSource]);
+
+      React.useEffect(() => {
+        if (!open) return;
+        const onDocClick = (e) => {
+          if (ref.current && !ref.current.contains(e.target)) setOpen(false);
+        };
+        document.addEventListener('click', onDocClick);
+        return () => document.removeEventListener('click', onDocClick);
+      }, [open]);
+
+      const runAction = (action, provider, keyRef) => {
+        setBusy(true);
+        fetch('/dsh-key-rotation/quick-action', {
+          method: 'POST',
+          headers: { 'content-type': 'application/json', accept: 'application/json' },
+          body: JSON.stringify({ action, provider, ref: keyRef }),
+          credentials: 'same-origin',
+          signal: (typeof AbortSignal !== 'undefined' && typeof AbortSignal.timeout === 'function') ? AbortSignal.timeout(5000) : undefined,
+        })
+          .then((r) => r.json())
+          .then(() => { load(); })
+          .catch((err) => { void err; })
+          .finally(() => { setBusy(false); });
+      };
+
+      let settingsVal = null;
+      try {
+        const sSnap = props?.settingsSource?.getSnapshot?.()?.service?.getSnapshot?.();
+        settingsVal = sSnap?.value;
+      } catch (e) {
+        void e;
+      }
+      if (settingsVal && settingsVal.showChatHeaderChip === false) return null;
+      if (snap && snap.showChatHeaderChip === false) return null;
+
+      const poolsObj = (snap && snap.pools) || {};
+      const poolEntries = Object.entries(poolsObj);
+      const total = poolEntries.reduce((a, [, p]) => a + (p.total || 0), 0);
+      const healthy = poolEntries.reduce((a, [, p]) => a + (p.healthy || 0), 0);
+      const anyExhausted = poolEntries.some(([, p]) => p.exhausted);
+      const color = !poolEntries.length ? 'var(--dsw-alias-label-tertiary)' : anyExhausted ? 'var(--dsw-alias-state-error-primary)' : healthy < total ? 'var(--dsw-alias-state-warn-primary)' : 'var(--dsw-alias-state-success-primary)';
+      const label = poolEntries.length ? `${healthy}/${total} rot` : 'rot';
+
+      return h('div', { ref, style: { position: 'relative', display: 'inline-flex' } },
+        h('button', {
+          type: 'button',
+          className: 'krot-header-chip',
+          title: t('title'),
+          onClick: () => setOpen((v) => !v),
+        },
+          h('span', { style: { width: '8px', height: '8px', borderRadius: '50%', background: color, flex: 'none', boxShadow: `0 0 6px ${color}` } }),
+          label,
+          h('span', { style: { fontSize: '9px', opacity: 0.6 } }, open ? '▲' : '▼')
+        ),
+        open ? h('div', { className: 'krot-popover', style: { minWidth: '220px' } },
+          h('div', { className: 'krot-pop-title' }, t('headerPoolsTitle')),
+          !poolEntries.length ? h('div', { style: { fontSize: '12px', color: 'var(--dsw-alias-label-tertiary)' } }, t('noActivePools')) : null,
+          poolEntries.map(([name, p]) => {
+            const c = p.exhausted ? 'var(--dsw-alias-state-error-primary)' : (p.healthy < p.total ? 'var(--dsw-alias-state-warn-primary)' : 'var(--dsw-alias-state-success-primary)');
+            const provName = p.providerName || name;
+            const tail = p.lastUsedTail;
+            return h('div', { key: name, className: 'krot-pop-row', style: { display: 'flex', flexDirection: 'column', gap: '4px', padding: '6px 0', borderBottom: '1px solid var(--dsw-alias-border-subtle)' } },
+              h('div', { style: { display: 'flex', justifyContent: 'space-between', alignItems: 'center' } },
+                h('div', { className: 'krot-pop-name' },
+                  h('span', { style: { width: '7px', height: '7px', borderRadius: '50%', background: c, flex: 'none' } }),
+                  name,
+                  tail ? h('span', { style: { marginLeft: '6px', fontSize: '11px', color: 'var(--dsw-alias-label-tertiary)', fontFeatureSettings: '"tnum"', fontFamily: 'monospace' } }, `...${tail}`) : null
+                ),
+                h('div', { className: 'krot-pop-count', style: { color: c, fontWeight: 600 } }, `${p.healthy}/${p.total}`)
+              ),
+              h('div', { style: { display: 'flex', gap: '4px', marginTop: '2px' } },
+                h('button', {
+                  type: 'button',
+                  disabled: busy,
+                  onClick: (e) => { e.stopPropagation(); runAction('skip', provName, p.lastUsed); },
+                  title: t('quickSkipTitle'),
+                  style: { padding: '2px 6px', fontSize: '11px', borderRadius: '4px', border: '1px solid var(--dsw-alias-border-subtle)', background: 'transparent', cursor: 'pointer', color: 'inherit' }
+                }, `⏭️ ${t('quickSkip')}`),
+                h('button', {
+                  type: 'button',
+                  disabled: busy,
+                  onClick: (e) => { e.stopPropagation(); runAction('reset', provName, p.lastUsed); },
+                  title: t('quickResetTitle'),
+                  style: { padding: '2px 6px', fontSize: '11px', borderRadius: '4px', border: '1px solid var(--dsw-alias-border-subtle)', background: 'transparent', cursor: 'pointer', color: 'inherit' }
+                }, `🔄 ${t('quickReset')}`),
+                h('button', {
+                  type: 'button',
+                  disabled: busy || !p.lastUsed,
+                  onClick: (e) => { e.stopPropagation(); runAction('pause', provName, p.lastUsed); },
+                  title: t('quickPauseTitle'),
+                  style: { padding: '2px 6px', fontSize: '11px', borderRadius: '4px', border: '1px solid var(--dsw-alias-border-subtle)', background: 'transparent', cursor: 'pointer', color: 'inherit' }
+                }, `⏸️ ${t('quickPause')}`)
+              )
+            );
+          })
+        ) : null
+      );
+    }

package/lib/client-src/90-apply.js

@@ -0,0 +1,69 @@
+    function apply(ctx) {
+      const settingsSource = createSettingsSource(ctx);
+      ctx.effect(() => ctx.locale.register(NS, { en, zh }), 'dsh-key-rotation: dictionaries');
+      // Header chip (#201): status dot in the session header utilities slot,
+      // same slot dsh-gitea / dsh-subscriptions use for their header widgets.
+      ctx.effect(() => {
+        if (!ctx.slots) return;
+        try {
+          ctx.slots.inject('conversation.session.header.utilities', () =>
+            ctx.slots.register(
+              { name: 'conversation.session.header.utilities', id: 'dsh-key-rotation-header-chip', order: 6, locale: NS, inject: () => ({ ctx, settingsSource }) },
+              KeyRotationHeaderChip,
+            ));
+        } catch { /* slot not available in this build */ }
+      }, 'dsh-key-rotation: header chip');
+
+      function useLocale() {
+        return useActiveLocale(ctx);
+      }
+      // Collapsible card in Settings -> Plugins -> Plugin settings
+      // (settings.plugin.item), matching Model Sync / Spendmeter / Vision Bridge.
+      // key MUST equal the settings namespace (NS), else the tab silently skips it.
+      
+  function KeyRotationCard(props) {
+        const locale = useLocale();
+        const t = resolveT(props);
+        const page = !!(props && props.view === 'page');
+        const [open, setOpen] = React.useState(!!page);
+        // Row seat (plugins.row.config): the host page draws title/icon/crumb and the
+        // padding, so the summary is a one-liner and the page drops our card chrome.
+        if (props && props.view === 'summary') {
+          return h('span', { className: 'krot-card-description' }, t('subtitle'));
+        }
+        return h(page ? 'div' : 'div', { className: page ? 'krot-page' : 'krot-card' + (open ? ' krot-card-open' : '') },
+          h('button', { type: 'button', className: 'krot-card-header', style: page ? { display: 'none' } : undefined, 'aria-expanded': page ? true : open, onClick: () => setOpen((v) => !v) },
+            h('span', { className: 'krot-card-head-text' },
+              h('span', { className: 'krot-card-name' }, t('title')),
+              h('span', { className: 'krot-card-description' }, t('subtitle'))),
+            h('span', { className: 'krot-card-chevron' + (open ? ' krot-card-chevron-open' : ''), 'aria-hidden': 'true' },
+              h('svg', { width: 14, height: 14, viewBox: '0 0 14 14', fill: 'none', stroke: 'currentColor', strokeWidth: 1.5, style: { display: 'block' } },
+                h('path', { d: 'M3.5 5.25L7 8.75L10.5 5.25' })))),
+          (page || open) ? h('div', { className: 'krot-card-body' }, h(KeyRotationErrorBoundary, null, h(KeyRotationSection, { ...props, locale }))) : null);
+      }
+      // Register each available seat independently. A missing legacy seat must
+      // not prevent the current bundle or row seat from registering.
+      for (const [name, key] of [
+        ['plugins.bundle.config', PKG],
+        ['plugins.row.config', ROW_CONFIG_KEY],
+        ['settings.plugin.item', NS],
+      ]) {
+        try {
+          ctx.slots.inject(name, () => ctx.slots.register(
+            { name, key, locale: NS, inject: () => ({ ctx, settingsSource }) }, KeyRotationCard,
+          ));
+        } catch (error) {
+          bestEffort('slots.register.log', () => { console.error('[dsh-key-rotation] settings seat unavailable', name, error); });
+        }
+      }
+    }
+
+    module.exports = { apply, inject: ['slots', 'locale'] };
+    if (typeof globalThis !== 'undefined') {
+      globalThis.__dshKeyRotationClientInternals = {
+        quotaMapOf, withQuotas, modelEntriesOf, isValidModelId, formatCountdown, validatePoolDraft,
+      };
+    }
+    return module.exports;
+  },
+});

package/lib/config-compat.js

@@ -1,7 +1,23 @@
+// lib/config-compat.js — Schemastery volatile decoding and config resolution (#551).
 // Decode modern volatile Config references while retaining stable identities for
 // the request hot path. Legacy cores pass ordinary resolved configuration.
 // If ctx is provided, invalidation listeners cache the unwrapped tree so the hot
 // path never recursively walks volatile nodes on unchanged configuration.
+
+/** Read each volatile field through its live reference, if the loader installed one (#551). */
+export function unwrapVolatileConfig(config) {
+  if (!config || typeof config !== 'object') return {};
+  const source = config;
+  const out = {};
+  for (const key of Object.keys(source)) {
+    const value = source[key];
+    out[key] = (value !== null && typeof value === 'object' && typeof value.get === 'function')
+      ? value.get()
+      : value;
+  }
+  return out;
+}
+
 export function createConfigReader(config, ctx) {
   let previous;
   let dirty = true;
@@ -34,7 +50,8 @@ export function createConfigReader(config, ctx) {
     if (ctx && !dirty && previous !== undefined) {
       return previous;
     }
-    previous = read(config, previous);
+    const unwrapped = unwrapVolatileConfig(config);
+    previous = read(unwrapped, previous);
     dirty = false;
     return previous;
   };

package/lib/http-bridge.js

@@ -183,6 +183,8 @@ export function scanForLiveSecrets(section) {
 
 /** Config bridge GET/PUT/DELETE — extracted from lib/index.js for size (#253). */
 export async function handleConfigBridge(ctx, request, res, getCloneIds) {
+  res.setHeader?.('X-DSH-Deprecated', 'true');
+  res.setHeader?.('Deprecation', '@goodandready/dsh-key-rotation v0.8.79: use Schemastery volatile schema instead of direct config HTTP bridge');
   if (!isTrustedBridgeRequest(request)) {
     json(res, 403, { error: { code: 'forbidden', message: 'Settings writes require a trusted loopback origin' } });
     return;

package/lib/index.js

@@ -11,7 +11,8 @@ import { decryptSecret } from './crypto-storage.js';
 
 import { AsyncLocalStorage } from 'node:async_hooks';
 import Schema from '@deepseek-ai/schemastery';
-import { createConfigReader, createProviderProfilesReader } from './config-compat.js';
+import { createConfigReader, createProviderProfilesReader, unwrapVolatileConfig } from './config-compat.js';
+import { KeyStateMachine, KEY_STATES, VALID_TRANSITIONS } from './key-state-machine.js';
 import {
   keyTail, KEY_TAIL_CHARS, KEY_TAIL_PLACEHOLDER, isLoopbackAddress, isTrustedBridgeRequest, isDesktopShellRequest, SWITCHABLE_MESSAGE_PATTERN,
   DEFAULT_SWITCH_CODES, isValidRef, pickNext, applyCooldown, recordFailure,
@@ -60,6 +61,11 @@ export { notifySwitch, notifyExhaustion, notifyEarlyWarning };
 export { classifyResponseError } from './errors.js';
 export { SessionRouter, defaultSessionRouter, unstickFailedKey } from './session-router.js';
 export { isContentChunk } from './rotate.js';
+export { ModelCatalog, defaultModelCatalog } from './model-catalog.js';
+export { KeyStateMachine, KEY_STATES, VALID_TRANSITIONS } from './key-state-machine.js';
+export { unwrapVolatileConfig } from './config-compat.js';
+export { QuotaRunway, defaultQuotaRunway, estimateRunway } from './quota-runway.js';
+export * as transports from './transports/index.js';
 
 const NS = 'dsh-key-rotation';
 

package/lib/key-state-machine.js

@@ -0,0 +1,267 @@
+// lib/key-state-machine.js — Encapsulated Key State Machine (#529).
+// Manages credential lifecycle across deterministic states and valid transitions.
+
+export const KEY_STATES = Object.freeze({
+  ACTIVE: 'ACTIVE',
+  COOLDOWN: 'COOLDOWN',
+  PROBING: 'PROBING',
+  EXHAUSTED: 'EXHAUSTED',
+  PAUSED: 'PAUSED',
+  REVOKED: 'REVOKED',
+});
+
+export const VALID_TRANSITIONS = Object.freeze({
+  [KEY_STATES.ACTIVE]: Object.freeze([
+    KEY_STATES.COOLDOWN,
+    KEY_STATES.EXHAUSTED,
+    KEY_STATES.PAUSED,
+    KEY_STATES.REVOKED,
+  ]),
+  [KEY_STATES.COOLDOWN]: Object.freeze([
+    KEY_STATES.PROBING,
+    KEY_STATES.ACTIVE,
+    KEY_STATES.PAUSED,
+    KEY_STATES.REVOKED,
+  ]),
+  [KEY_STATES.PROBING]: Object.freeze([
+    KEY_STATES.ACTIVE,
+    KEY_STATES.COOLDOWN,
+    KEY_STATES.PAUSED,
+    KEY_STATES.REVOKED,
+  ]),
+  [KEY_STATES.EXHAUSTED]: Object.freeze([
+    KEY_STATES.ACTIVE,
+    KEY_STATES.COOLDOWN,
+    KEY_STATES.PAUSED,
+    KEY_STATES.REVOKED,
+  ]),
+  [KEY_STATES.PAUSED]: Object.freeze([
+    KEY_STATES.ACTIVE,
+    KEY_STATES.COOLDOWN,
+    KEY_STATES.REVOKED,
+  ]),
+  [KEY_STATES.REVOKED]: Object.freeze([
+    KEY_STATES.ACTIVE,
+  ]),
+});
+
+export class KeyStateMachine {
+  /**
+   * @param {object} [options]
+   * @param {number} [options.maxHistory] Maximum transition history entries per pool
+   */
+  constructor(options = {}) {
+    /** @type {Map<string, { state: string, updatedAt: number, previousState?: string, reason?: string, failedUntil?: number }>} */
+    this.keyRecords = new Map();
+    /** @type {Array<{ ref: string, from: string, to: string, at: number, reason: string|null }>} */
+    this.history = [];
+    this.maxHistory = options.maxHistory ?? 100;
+  }
+
+  /**
+   * Computes the current deterministic state of a key reference.
+   *
+   * @param {string} keyRef
+   * @param {object} [context] Optional pool state context for backward compatibility
+   * @param {Set<string>} [context.revokedRefs]
+   * @param {Set<string>} [context.pausedRefs]
+   * @param {Map<string, number>} [context.failedUntil]
+   * @param {number} [now]
+   * @returns {string} Current KEY_STATES value
+   */
+  getState(keyRef, context = {}, now = Date.now()) {
+    if (!keyRef) return KEY_STATES.ACTIVE;
+
+    // 1. Revocation is absolute
+    if (context.revokedRefs && context.revokedRefs.has(keyRef)) {
+      return KEY_STATES.REVOKED;
+    }
+
+    // 2. Manual pause overrides operational state
+    if (context.pausedRefs && context.pausedRefs.has(keyRef)) {
+      return KEY_STATES.PAUSED;
+    }
+
+    const record = this.keyRecords.get(keyRef);
+    if (!record) {
+      const failedUntil = context.failedUntil?.get?.(keyRef);
+      if (typeof failedUntil === 'number' && failedUntil > now) {
+        return KEY_STATES.COOLDOWN;
+      }
+      return KEY_STATES.ACTIVE;
+    }
+
+    // Cooldown transition to probing when timer elapses
+    if (record.state === KEY_STATES.COOLDOWN) {
+      const until = record.failedUntil ?? context.failedUntil?.get?.(keyRef);
+      if (typeof until === 'number' && until <= now) {
+        return KEY_STATES.PROBING;
+      }
+    }
+
+    return record.state;
+  }
+
+  /**
+   * Transitions a key reference to a new state if valid.
+   *
+   * @param {string} keyRef
+   * @param {string} targetState Target KEY_STATES value
+   * @param {object} [metadata]
+   * @param {string} [metadata.reason]
+   * @param {number} [metadata.failedUntil]
+   * @param {object} [metadata.context]
+   * @param {number} [now]
+   * @returns {string|null} Resulting state or null on failure
+   */
+  transition(keyRef, targetState, metadata = {}, now = Date.now()) {
+    if (!keyRef || !targetState) return null;
+
+    const currentState = this.getState(keyRef, metadata.context, now);
+    if (currentState === targetState) return currentState;
+
+    const allowed = VALID_TRANSITIONS[currentState] || [];
+    if (!allowed.includes(targetState)) {
+      // In relaxed mode, force transition with logged anomaly
+      targetState = targetState in KEY_STATES ? targetState : KEY_STATES.ACTIVE;
+    }
+
+    const record = this.keyRecords.get(keyRef) ?? {
+      state: currentState,
+      updatedAt: now,
+    };
+
+    record.previousState = currentState;
+    record.state = targetState;
+    record.updatedAt = now;
+    if (metadata.reason !== undefined) record.reason = metadata.reason;
+    if (metadata.failedUntil !== undefined) record.failedUntil = metadata.failedUntil;
+
+    this.keyRecords.set(keyRef, record);
+
+    const event = {
+      ref: keyRef,
+      from: currentState,
+      to: targetState,
+      at: now,
+      reason: metadata.reason ?? null,
+    };
+
+    this.history.push(event);
+    if (this.history.length > this.maxHistory) {
+      this.history.shift();
+    }
+
+    // Synchronize external pool state if provided
+    if (metadata.context) {
+      if (targetState === KEY_STATES.REVOKED) {
+        metadata.context.revokedRefs?.add?.(keyRef);
+        metadata.context.pausedRefs?.delete?.(keyRef);
+      } else if (targetState === KEY_STATES.PAUSED) {
+        metadata.context.pausedRefs?.add?.(keyRef);
+      } else if (currentState === KEY_STATES.PAUSED && targetState !== KEY_STATES.PAUSED) {
+        metadata.context.pausedRefs?.delete?.(keyRef);
+      }
+    }
+
+    return targetState;
+  }
+
+  /**
+   * Puts key into COOLDOWN state until specified duration elapses.
+   */
+  transitionToCooldown(keyRef, options = {}, now = Date.now()) {
+    const cooldownMs = Number(options.cooldownMs) > 0 ? Number(options.cooldownMs) : 60000;
+    const failedUntil = now + cooldownMs;
+    return this.transition(keyRef, KEY_STATES.COOLDOWN, {
+      failedUntil,
+      reason: options.reason || 'COOLDOWN',
+      context: options.context,
+    }, now);
+  }
+
+  /** Marks key as ready for canary probe dispatch. */
+  markProbing(keyRef, metadata = {}, now = Date.now()) {
+    return this.transition(keyRef, KEY_STATES.PROBING, {
+      reason: metadata.reason || 'CANARY_PROBE',
+      context: metadata.context,
+    }, now);
+  }
+
+  /** Activates key following successful request or probe. */
+  activate(keyRef, metadata = {}, now = Date.now()) {
+    return this.transition(keyRef, KEY_STATES.ACTIVE, {
+      reason: metadata.reason || 'SUCCESS',
+      context: metadata.context,
+    }, now);
+  }
+
+  /** Marks key as exhausted due to local quota or TPM/RPM window. */
+  markExhausted(keyRef, metadata = {}, now = Date.now()) {
+    return this.transition(keyRef, KEY_STATES.EXHAUSTED, {
+      reason: metadata.reason || 'QUOTA_EXHAUSTED',
+      context: metadata.context,
+    }, now);
+  }
+
+  /** Manually pauses key from rotation. */
+  pause(keyRef, reason = 'USER_PAUSE', metadata = {}, now = Date.now()) {
+    return this.transition(keyRef, KEY_STATES.PAUSED, {
+      reason,
+      context: metadata.context,
+    }, now);
+  }
+
+  /** Unpauses key, returning it to active rotation. */
+  unpause(keyRef, metadata = {}, now = Date.now()) {
+    return this.transition(keyRef, KEY_STATES.ACTIVE, {
+      reason: 'USER_RESUME',
+      context: metadata.context,
+    }, now);
+  }
+
+  /** Revokes key permanently until credentials change. */
+  revoke(keyRef, reason = 'INVALID_CREDENTIAL', metadata = {}, now = Date.now()) {
+    return this.transition(keyRef, KEY_STATES.REVOKED, {
+      reason,
+      context: metadata.context,
+    }, now);
+  }
+
+  /** Checks if key is usable for dispatch (ACTIVE or PROBING). */
+  isUsable(keyRef, context = {}, now = Date.now()) {
+    const state = this.getState(keyRef, context, now);
+    return state === KEY_STATES.ACTIVE || state === KEY_STATES.PROBING;
+  }
+
+  /** Returns transition history for a specific key or all keys. */
+  getHistory(keyRef) {
+    if (!keyRef) return this.history.slice();
+    return this.history.filter((e) => e.ref === keyRef);
+  }
+
+  /** Returns state distribution statistics across a set of keys. */
+  getStats(refs = [], context = {}, now = Date.now()) {
+    const stats = {
+      total: refs.length,
+      [KEY_STATES.ACTIVE]: 0,
+      [KEY_STATES.COOLDOWN]: 0,
+      [KEY_STATES.PROBING]: 0,
+      [KEY_STATES.EXHAUSTED]: 0,
+      [KEY_STATES.PAUSED]: 0,
+      [KEY_STATES.REVOKED]: 0,
+    };
+    for (const ref of refs) {
+      const state = this.getState(ref, context, now);
+      if (state in stats) stats[state]++;
+    }
+    return stats;
+  }
+
+  clear() {
+    this.keyRecords.clear();
+    this.history = [];
+  }
+}
+
+export const defaultKeyStateMachine = new KeyStateMachine();