@goodandready/dsh-usage-guard 0.1.9 → 0.1.11

package/lib/client.js

@@ -58,6 +58,7 @@ window.__ModuleLoader__.load({
       badge_report_only: '仅审计',
       'settings.loading': '正在加载 Usage Guard 设置…',
       'settings.unavailable': '设置不可用（宿主命名空间尚未就绪）。',
+      'settings.unmonitored': '配置监听不可用。当前使用默认配置运行；变更需重启 DSH 生效。',
       'settings.retry': '重试',
       saved: '设置保存成功',
       save: '保存更改',
@@ -96,9 +97,13 @@ window.__ModuleLoader__.load({
 
     function getActiveLocale(c) {
       try {
-        const cur = (c?.locale && typeof c.locale.get === 'function' ? c.locale.get() : c?.locale?.current) || '';
+        const snap = (typeof c?.locale?.getLocale === 'function' ? c.locale.getLocale() : null)
+          || (typeof c?.locale?.getSnapshot === 'function' ? c.locale.getSnapshot() : null);
+        const cur = snap?.active || snap?.locale || '';
         if (typeof cur === 'string' && cur.toLowerCase().startsWith('zh')) return 'zh';
-      } catch (_) {}
+      } catch (err) {
+        void err;
+      }
       return 'en';
     }
 
@@ -127,7 +132,15 @@ window.__ModuleLoader__.load({
         })
       );
     }
-    const Chevron = FallbackChevron;
+
+    let ChevronIcon = null;
+    try {
+      const primitives = require('@deepseek-ai/dsh-client-ui-primitives');
+      ChevronIcon = primitives && primitives.IconChevronDownOutline14;
+    } catch (err) {
+      void err;
+    }
+    const Chevron = ChevronIcon || FallbackChevron;
 
     function ensureCss() {
       if (typeof document === 'undefined') return;
@@ -142,9 +155,9 @@ window.__ModuleLoader__.load({
 .ug-head-sub{font-size:13px;color:var(--dsw-alias-label-secondary);margin-top:2px}
 
 .ug-badge{font-size:12px;padding:3px 10px;border-radius:999px;border:1px solid var(--dsw-alias-border-l2);display:inline-flex;align-items:center;gap:5px;font-weight:500}
-.ug-badge-ok{border-color:var(--dsw-alias-state-success-primary);color:var(--dsw-alias-state-success-primary);background:rgba(16,185,129,0.08)}
-.ug-badge-warn{border-color:var(--dsw-alias-state-warning-primary);color:var(--dsw-alias-state-warning-primary);background:rgba(245,158,11,0.08)}
-.ug-badge-bad{border-color:var(--dsw-alias-state-error-primary);color:var(--dsw-alias-state-error-primary);background:rgba(239,68,68,0.08)}
+.ug-badge-ok{border-color:var(--dsw-alias-state-success-primary);color:var(--dsw-alias-state-success-primary);background:var(--dsw-alias-state-success-bg, var(--dsw-alias-bg-layer-2))}
+.ug-badge-warn{border-color:var(--dsw-alias-state-warning-primary);color:var(--dsw-alias-state-warning-primary);background:var(--dsw-alias-state-warning-bg, var(--dsw-alias-bg-layer-2))}
+.ug-badge-bad{border-color:var(--dsw-alias-state-error-primary);color:var(--dsw-alias-state-error-primary);background:var(--dsw-alias-state-error-bg, var(--dsw-alias-bg-layer-2))}
 
 .ug-body{display:flex;flex-direction:column;gap:14px;border-top:1px solid var(--dsw-alias-border-l2);padding-top:16px;margin-top:4px}
 .ug-field-card{border:1px solid var(--dsw-alias-border-l2);background:var(--dsw-alias-bg-layer-2);border-radius:8px;padding:12px 14px;display:flex;flex-direction:column;gap:6px}
@@ -167,12 +180,13 @@ window.__ModuleLoader__.load({
 .ug-btn-sm{padding:4px 10px;font-size:12px;border-radius:6px}
 .ug-btn-primary{background:var(--dsw-alias-label-primary);color:var(--dsw-alias-bg-layer-3);border-color:transparent}
 .ug-btn-primary:hover:not(:disabled){opacity:0.9}
-.ug-btn-accent{background:var(--dsw-alias-state-brand-primary);color:#ffffff;border-color:transparent}
+.ug-btn-accent{background:var(--dsw-alias-state-brand-primary);color:var(--dsw-alias-label-invert, var(--dsw-alias-bg-layer-3));border-color:transparent}
 .ug-btn-accent:hover:not(:disabled){opacity:0.9}
 .ug-btn:disabled{opacity:0.5;cursor:not-allowed}
 
-.ug-alert-ok{padding:10px 14px;border-radius:8px;background:rgba(16,185,129,0.1);color:var(--dsw-alias-state-success-primary);font-size:13px;border:1px solid rgba(16,185,129,0.2)}
-.ug-alert-bad{padding:10px 14px;border-radius:8px;background:rgba(239,68,68,0.1);color:var(--dsw-alias-state-error-primary);font-size:13px;border:1px solid rgba(239,68,68,0.2)}
+.ug-alert-ok{padding:10px 14px;border-radius:8px;background:var(--dsw-alias-state-success-bg, var(--dsw-alias-bg-layer-2));color:var(--dsw-alias-state-success-primary);font-size:13px;border:1px solid var(--dsw-alias-state-success-border, var(--dsw-alias-border-l2))}
+.ug-alert-bad{padding:10px 14px;border-radius:8px;background:var(--dsw-alias-state-error-bg, var(--dsw-alias-bg-layer-2));color:var(--dsw-alias-state-error-primary);font-size:13px;border:1px solid var(--dsw-alias-state-error-border, var(--dsw-alias-border-l2))}
+.ug-update-banner{margin-top:8px;display:flex;align-items:center;justify-content:space-between;padding:8px 12px;border-radius:6px;background:var(--dsw-alias-state-warning-bg, var(--dsw-alias-bg-layer-2));border:1px solid var(--dsw-alias-state-warning-border, var(--dsw-alias-border-l2))}
 .ug-incident-box{margin-top:6px;padding:8px 10px;border-radius:6px;background:var(--dsw-alias-bg-layer-3);border:1px solid var(--dsw-alias-border-l2);font-size:12px;font-family:monospace;color:var(--dsw-alias-label-secondary);overflow-x:auto}
 `;
       document.head.appendChild(style);
@@ -407,7 +421,7 @@ window.__ModuleLoader__.load({
         updateAvailable
           ? React.createElement(
               'div',
-              { style: { marginTop: '8px', display: 'flex', alignItems: 'center', justifyContent: 'space-between', padding: '8px 12px', background: 'rgba(245,158,11,0.08)', borderRadius: '6px', border: '1px solid rgba(245,158,11,0.2)' } },
+              { className: 'ug-update-banner' },
               React.createElement('span', { style: { fontSize: '12px', color: 'var(--dsw-alias-state-warning-primary)', fontWeight: 500 } }, `New release available: v${latestVer}`),
               React.createElement(
                 'button',
@@ -467,6 +481,9 @@ window.__ModuleLoader__.load({
             }
           };
           read();
+          if (typeof scope.watch !== 'function' && active) {
+            setSnap((prev) => ({ ...prev, unmonitored: true }));
+          }
           const unwatch = typeof scope.watch === 'function'
             ? scope.watch((next) => {
                 if (!active || !next || typeof next !== 'object') return;
@@ -482,7 +499,9 @@ window.__ModuleLoader__.load({
             : () => {};
           return () => {
             active = false;
-            try { unwatch(); } catch (_) {}
+            try { unwatch(); } catch (_) {
+              // Intentional cleanup catch: ignore errors if subscription was already disposed
+            }
           };
         } catch (_) {
           setSnap({ status: 'unavailable', value: {} });
@@ -570,6 +589,14 @@ window.__ModuleLoader__.load({
         'div',
         { className: 'ug-body' },
 
+        snap.unmonitored
+          ? React.createElement(
+              'div',
+              { className: 'ug-alert-bad', style: { marginBottom: '12px' } },
+              t('settings.unmonitored')
+            )
+          : null,
+
         // Telemetry / Protection status banner
         React.createElement(
           'div',
@@ -769,7 +796,11 @@ window.__ModuleLoader__.load({
         try {
           const s = (c?.get && c.get('lanSettings')) || c?.settingsScope;
           s?.describe?.()?.load?.();
-        } catch (_) {}
+        } catch (err) {
+          if (typeof console !== 'undefined' && console.warn) {
+            console.warn('[dsh-usage-guard] settings mirror load attempt failed:', err?.message || err);
+          }
+        }
       }, 1000);
       if (timer && typeof timer.unref === 'function') {
         timer.unref();

package/lib/index.js

@@ -1,14 +1,14 @@
-// dsh-usage-guard — заплатка на счёт токенов.
+// dsh-usage-guard — Token usage counter sanitizer and session history protector.
 //
-// Харнесс складывает расход в четыре ведра, и два из них берёт без оглядки:
+// DSH core aggregates token usage into four buckets, two of which are accessed without fallbacks:
 //
-//     uncachedInputTokens: usage.inputTokens,        // без подстраховки
-//     outputTokens:        usage.outputTokens,       // без подстраховки
+//     uncachedInputTokens: usage.inputTokens,        // unguarded
+//     outputTokens:        usage.outputTokens,       // unguarded
 //     cacheReadTokens:     usage.cacheReadTokens ?? 0,
 //     cacheWriteTokens:    usage.cacheWriteTokens ?? 0,
 //
-// Стоит провайдеру прислать порцию без первых двух, и сложение даёт NaN.
-// Дальше проверка схемы отвергает всю выжимку сессии.
+// If a provider returns a usage sample missing either of the first two, accumulation yields NaN.
+// Subsequent schema validation then rejects the entire session history projection.
 
 import z from '@deepseek-ai/schemastery'
 
@@ -17,7 +17,8 @@ import { telemetry } from './telemetry.js'
 import { registerPluginUpdater } from './updater.js'
 import { complaint, damage, healed, usageOf } from './usage.js'
 
-export const name = 'dsh-usage-guard'
+export const name = '@goodandready/dsh-usage-guard'
+export const NS = 'dsh-usage-guard'
 export const inject = ['sessionProjections']
 
 export const Config = z.object({
@@ -48,15 +49,43 @@ export function apply(ctx, config) {
 
   ctx.inject(['settings'], (sctx) => {
     try {
-      const scope = sctx.settings.register(name, Config, { base: config })
-      try {
-        const fresh = scope.get()
-        if (fresh && typeof fresh === 'object') live = fresh
-      } catch (_) {}
-      sctx.effect(() => scope.watch((next) => {
-        if (next && typeof next === 'object') live = next
-      }))
-    } catch (_) {}
+      const scope = sctx.settings?.register?.(NS, Config, { base: config })
+      if (!scope) {
+        const msg = `[dsh-usage-guard] settings service register() unavailable; running with default config`
+        if (typeof sctx.logger?.warn === 'function') sctx.logger.warn(msg)
+        else if (typeof ctx.logger?.warn === 'function') ctx.logger.warn(msg)
+        return
+      }
+
+      if (typeof scope.get === 'function') {
+        try {
+          const fresh = scope.get()
+          if (fresh && typeof fresh === 'object') live = fresh
+        } catch (readErr) {
+          const msg = `[dsh-usage-guard] failed to read current settings: ${readErr?.message || readErr}; running with initial config`
+          if (typeof sctx.logger?.warn === 'function') sctx.logger.warn(msg)
+          else if (typeof ctx.logger?.warn === 'function') ctx.logger.warn(msg)
+        }
+      } else {
+        const msg = `[dsh-usage-guard] settings scope has no get() method; running with default config`
+        if (typeof sctx.logger?.warn === 'function') sctx.logger.warn(msg)
+        else if (typeof ctx.logger?.warn === 'function') ctx.logger.warn(msg)
+      }
+
+      if (typeof scope.watch === 'function') {
+        sctx.effect(() => scope.watch((next) => {
+          if (next && typeof next === 'object') live = next
+        }))
+      } else {
+        const msg = `[dsh-usage-guard] settings scope has no watch() method; running with default config without live update subscription`
+        if (typeof sctx.logger?.warn === 'function') sctx.logger.warn(msg)
+        else if (typeof ctx.logger?.warn === 'function') ctx.logger.warn(msg)
+      }
+    } catch (err) {
+      const msg = `[dsh-usage-guard] failed to register settings subscription: ${err?.message || err}; running with default config`
+      if (typeof sctx.logger?.warn === 'function') sctx.logger.warn(msg)
+      else if (typeof ctx.logger?.warn === 'function') ctx.logger.warn(msg)
+    }
   })
 
   // Register one-click updater and telemetry endpoints if webServer is available
@@ -84,7 +113,11 @@ export function apply(ctx, config) {
           res.end()
         },
       }), 'dsh-usage-guard: telemetry route')
-    } catch (_) {}
+    } catch (err) {
+      const msg = `[dsh-usage-guard] failed to register routes on webServer: ${err?.message || err}`
+      if (typeof wctx.logger?.warn === 'function') wctx.logger.warn(msg)
+      else if (typeof ctx.logger?.warn === 'function') ctx.logger.warn(msg)
+    }
   })
 
   const told = new Set()
@@ -141,10 +174,13 @@ export function apply(ctx, config) {
       })
 
       if (live && live.report !== false) {
-        try {
+        const msg = `[dsh-usage-guard] ${complaint(found, bad, { maxStepTokens: live?.maxStepTokens })}`
+        if (typeof ctx.logger?.warn === 'function') {
+          ctx.logger.warn(msg)
+        } else {
           // eslint-disable-next-line no-console
-          console.warn(`[dsh-usage-guard] ${complaint(found, bad, { maxStepTokens: live?.maxStepTokens })}`)
-        } catch {}
+          console.warn(msg)
+        }
       }
     }
 
@@ -156,7 +192,7 @@ export function apply(ctx, config) {
   ctx.inject(['sessionProjections'], (pctx) => {
     pctx.effect(
       () => patchRegistry(pctx.sessionProjections, guard),
-      'dsh-usage-guard: обезвреживание порций расхода',
+      'dsh-usage-guard: sanitize usage counter samples',
     )
   })
 }

package/lib/patch.js

@@ -1,30 +1,27 @@
-// Как заплатка встаёт перед сложением.
+// How the patch intercepts before state reduction.
 //
-// Реестр проекций сессии — служба с открытой картой записей. Каждая запись
-// держит обезличенную копию того, что зарегистрировал владелец, и зовёт `apply`
-// именно у копии. Значит, подменять надо её, а не то, что владелец отдал при
-// регистрации.
+// The session projection registry is a service with an exposed registrations map. Each entry
+// holds a sanitized copy of what the owner registered, and calls `apply` on that copy.
+// Therefore, we patch the definition's apply method, not the original object passed at registration.
 //
-// Порядок загрузки не гарантирован, и на деле проекция ядра заводится позже
-// нас. Подменять при этом метод `register` у службы бесполезно: до неё
-// добираются через посредника, и замена, поставленная на посредника, до
-// настоящего вызова не доезжает. Поэтому цепляемся за саму карту записей —
-// обычный Map, один и тот же для всех, кто до него дотянулся.
+// Load order is not guaranteed, and in practice core projections may register later than our plugin.
+// Patching the service's `register` method is ineffective because callers go through an intermediary.
+// Hence, we hook into the registrations map itself — a standard Map instance shared by all participants.
 //
-// Оборачиваются все проекции, а не одна «нужная». Порцию расхода читает не
-// только счёт токенов: давление на контекст считает её своей формулой, разбор
-// занятости — своей, и каждая спотыкается об один и тот же пропущенный
-// счётчик. Список ключей пришлось бы держать в согласии с чужим кодом, а
-// обезвреживатель для здорового события возвращает ровно то же событие — тем,
-// кто расхода не касается, он обходится в одно сравнение.
+// All projections are wrapped, not just a single one. Token usage is consumed by multiple systems:
+// context pressure calculations, session token sums, and analytics. Each would fail on a missing
+// counter. Wrapping all projections with a guard that returns the exact object reference for healthy
+// events costs only a single reference comparison for events without usage.
 
-/** Метка на подменённой функции: второй раз оборачивать нечего. */
+/** Marker on patched functions to prevent double wrapping. */
 export const PATCHED = Symbol.for('dsh-usage-guard.patched')
 
 /**
- * Обернуть складывание одной записи реестра с сохранением контекста this.
+ * Wrap the apply method of a registry definition, preserving `this` context.
  *
- * @returns функция возврата к исходному состоянию.
+ * @param def - Projection definition entry.
+ * @param guard - Event sanitizer function.
+ * @returns Cleanup function restoring the original method.
  */
 export function wrapApply(def, guard) {
   if (!def || typeof def.apply !== 'function' || def.apply[PATCHED]) return () => {}
@@ -40,27 +37,23 @@ export function wrapApply(def, guard) {
 }
 
 /**
- * Поставить заплатку на реестр проекций.
+ * Patch the session projections registry.
  *
- * @param registry - служба `sessionProjections`.
- * @param guard - обезвреживатель события; получает событие, возвращает его же
- *                или исправленное.
- * @returns функция, снимающая всё поставленное, в обратном порядке.
+ * @param registry - `sessionProjections` service instance.
+ * @param guard - Event sanitizer function; receives an event and returns either the same event or a repaired copy.
+ * @returns Teardown function that removes all installed hooks in reverse order.
  */
 export function patchRegistry(registry, guard) {
   const undo = []
   const map = registry && typeof registry === 'object' ? registry.registrations : undefined
   if (!map || typeof map.set !== 'function' || typeof map.values !== 'function') return () => {}
 
-  // Успели завестись раньше нас — оборачиваем прямо сейчас.
+  // Wrap entries already registered before this patch
   for (const entry of map.values()) {
     if (entry && entry.def) undo.push(wrapApply(entry.def, guard))
   }
 
-  // Заведутся позже — поймаем на укладке в карту.
-  // Save the current map.set (may be the prototype method or a previous patched version).
-  // We restore via explicit assignment — relying on `delete` to restore the prototype method
-  // is fragile when the environment mutates Map.prototype.
+  // Intercept entries registered in the future when inserted into the map
   const originalSet = map.set
   if (!originalSet[PATCHED]) {
     const patched = function (key, value) {
@@ -78,4 +71,4 @@ export function patchRegistry(registry, guard) {
     for (const step of undo.reverse()) step()
     undo.length = 0
   }
-}
+}

package/lib/usage.js

@@ -9,12 +9,12 @@ export const FIELDS = [
 ]
 
 /**
- * Словарь привычных чужих имён для счётчиков токенов.
+ * Dictionary of common external provider naming variants for token counters.
  *
- * Каждый LLM-провайдер называет расход на свой лад. Харнесс ждёт camelCase, а
- * остальные для него — пустое место, хотя число лежит рядом. Прежде чем
- * подставлять ноль, стоит поискать его здесь: ноль — это признание поражения, а
- * не первый ход.
+ * Each LLM provider formats token usage differently. DSH core expects camelCase,
+ * and ignores other conventions even if the token count is present under a different key.
+ * Instead of immediately falling back to zero, we check known provider aliases first.
+ * Setting zero is a last resort to preserve arithmetic, not the primary choice.
  */
 export const ALIASES = {
   inputTokens: [
@@ -48,18 +48,18 @@ export const ALIASES = {
 }
 
 /**
- * Годное значение счётчика: конечное неотрицательное ЦЕЛОЕ число.
- * Значения меньше нуля (-1 и т.д.), нечисловые, а также дробные числа (floats)
- * не признаются годными, так как схема ядра DSH требует z.number().int().nonnegative().
+ * Valid counter value: a finite, non-negative integer.
+ * Negative values, non-numeric values, and floating point numbers are considered invalid
+ * as the DSH core schema expects integer counters.
  */
 export function sound(value) {
   return typeof value === 'number' && Number.isFinite(value) && value >= 0 && Number.isInteger(value)
 }
 
 /**
- * Безопасное приведение значения к корректному неотрицательному целому числу.
- * Округляет дробные числа и парсит числовые строки (в т.ч. с десятичной точкой).
- * Исключает NaN, Infinity, отрицательные величины и мусорные строки.
+ * Safely coerces a value to a valid non-negative integer.
+ * Rounds floating point numbers and parses numeric strings (including decimals).
+ * Filters out NaN, Infinity, negative numbers, and non-numeric strings.
  */
 export function coerceNumber(value) {
   if (typeof value === 'number') {
@@ -76,11 +76,10 @@ export function coerceNumber(value) {
 }
 
 /**
- * Достать порцию расхода из события сессии — по тем же двум местам, где её ищет
- * харнесс.
+ * Extracts the usage sample from a session event by checking both standard DSH locations.
  *
- * @returns `{ usage, turn, step, at }`, где `at` — путь до порции внутри
- *          события, или `null`, если расхода в событии нет.
+ * @returns `{ usage, turn, step, at }` where `at` indicates the path within the event ('chunk' or 'message'),
+ *          or `null` if the event carries no usage data.
  */
 export function usageOf(event) {
   if (!event || typeof event !== 'object') return null
@@ -97,12 +96,11 @@ export function usageOf(event) {
 }
 
 /**
- * Какие счётчики порции испорчены или превышают допустимый порог maxStepTokens.
+ * Detects which usage counters are malformed or exceed the maxStepTokens ceiling.
  *
- * Отсутствие кэш-полей нарушением не считается: их не присылает добрая половина
- * провайдеров, и харнесс сам подставляет там ноль. Ругаемся только на то, что
- * действительно ломает сложение, — на пропущенные, нечисловые, нецелые или
- * отрицательные значения.
+ * Omitted cache fields are not considered defects: many providers do not report them,
+ * and the harness automatically defaults them to zero. We only flag values that actually
+ * break arithmetic operations — missing required counters, non-numbers, non-integers, or negatives.
  */
 export function damage(usage, options = {}) {
   if (!usage || typeof usage !== 'object') return FIELDS.slice(0, 2)
@@ -125,33 +123,33 @@ export function damage(usage, options = {}) {
 }
 
 /**
- * Число под одним из привычных чужих имён, вложенных структур или числовых строк/дробей.
- * Возвращает валидное целое неотрицательное число или `undefined`, если его там нет.
+ * Attempts to borrow a valid counter number from known aliases, nested structures, or numeric strings.
+ * Returns a valid non-negative integer or `undefined` if none is found.
  */
 export function borrowed(usage, field) {
   if (!usage || typeof usage !== 'object') return undefined
 
-  // 1. Поиск по известным синонимам
+  // 1. Search known alias names
   for (const alias of ALIASES[field] ?? []) {
     const num = coerceNumber(usage[alias])
     if (num !== undefined) return num
   }
 
-  // 2. Поиск во вложенных деталях кэша (OpenAI-style: prompt_tokens_details.cached_tokens / cachedTokens)
+  // 2. Search nested cache details (OpenAI-style: prompt_tokens_details.cached_tokens / cachedTokens)
   if (field === 'cacheReadTokens' && usage.prompt_tokens_details && typeof usage.prompt_tokens_details === 'object') {
     const details = usage.prompt_tokens_details
     const num = coerceNumber(details.cached_tokens ?? details.cachedTokens ?? details.cache_read_tokens)
     if (num !== undefined) return num
   }
 
-  // 3. Поиск во вложенных деталях создания кэша (cache_creation_input_tokens)
+  // 3. Search nested cache creation details (cache_creation_input_tokens)
   if (field === 'cacheWriteTokens' && usage.prompt_tokens_details && typeof usage.prompt_tokens_details === 'object') {
     const details = usage.prompt_tokens_details
     const num = coerceNumber(details.cache_creation_tokens ?? details.cacheCreationTokens)
     if (num !== undefined) return num
   }
 
-  // 4. Само поле, если оно было передано валидной строкой или нецелым числом (напр. "123" или 15.4)
+  // 4. Check the field itself if passed as a string or float (e.g. "123" or 15.4)
   const selfNum = coerceNumber(usage[field])
   if (selfNum !== undefined) return selfNum
 
@@ -159,11 +157,11 @@ export function borrowed(usage, field) {
 }
 
 /**
- * Порция с обезвреженными счётчиками и опциональным ограничением maxStepTokens.
+ * Returns a usage object with sanitized counters and optional maxStepTokens clamping.
  *
- * Сначала ищем число под чужим именем или нормализуем само поле (округление float/string),
- * и только если его нет — ставим ноль.
- * Чиним арифметику, а не переписываем остальной ответ провайдера.
+ * We search for a value under known aliases or normalize the existing field first,
+ * and only substitute zero if no numeric value can be recovered.
+ * This restores arithmetic consistency without mutating unrelated provider response fields.
  */
 export function repaired(usage, bad, options = {}) {
   const fixed = usage && typeof usage === 'object' ? { ...usage } : {}
@@ -185,12 +183,10 @@ export function repaired(usage, bad, options = {}) {
 }
 
 /**
- * Событие с обезвреженной порцией — или то же самое событие, если чинить
- * нечего.
+ * Returns an event with sanitized usage, or the exact same event if no repair was needed.
  *
- * Копия поверхностная и ровно по тому пути, где лежит расход: складыванию
- * достаётся исправное событие, а всё остальное в нём — та же ссылка, что и
- * была.
+ * Performs a shallow copy only along the exact path holding usage data:
+ * state reduction receives the repaired counters while all other event references remain untouched.
  */
 export function healed(event, bad, options = {}) {
   const found = usageOf(event)
@@ -206,7 +202,7 @@ export function healed(event, bad, options = {}) {
   return { ...event, data: { ...event.data, usage } }
 }
 
-/** Безопасная сериализация для журнала: предотвращает сбои на циклических объектах и BigInt. */
+/** Safe JSON stringification for logging: guards against circular references and BigInt values. */
 function safeStringify(value) {
   try {
     return JSON.stringify(value)
@@ -219,7 +215,7 @@ function safeStringify(value) {
   }
 }
 
-/** Короткая строка для журнала: по ней видно, кого звать к ответу. */
+/** Formats a descriptive log line identifying the turn, step, raw payload, and applied repairs. */
 export function complaint(found, bad, options = {}) {
   const where = `turn ${String(found?.turn ?? '-')}, step ${String(found?.step ?? '-')}`
   const usage = found?.usage ?? found

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-usage-guard",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "Keeps a malformed token-usage sample from taking a whole session history down with it: a missing or non-numeric counter becomes zero before the harness adds it up, so the fold never yields NaN and already-broken sessions open again.",
   "keywords": [
     "deepseek-harness",