iobroker.nexowatt-ui 1.0.0 → 1.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  NexoWatt EOS is the local platform for energy, charging and building control, including the responsive customer cockpit and installer workspace.
4
4
 
5
- **Current stable release:** `1.0.0` (2026-09-06)
5
+ **Current stable release:** `1.0.2` (2026-09-09)
6
6
 
7
7
  It provides live energy-flow visualization, historical analysis, SmartHome visualization, installer-controlled EMS applications, and selected customer controls for desktop, tablet, and smartphone use.
8
8
 
@@ -42,7 +42,7 @@ write() meldet Backpressure
42
42
  - Heartbeat alle 15 Sekunden;
43
43
  - Trennung bei Request-, Response- oder Socketfehler;
44
44
  - vollständige Listener- und Clientbereinigung beim Adapter-Unload;
45
- - kurze Reconnect-Sperre bei Heap-Druck, damit EventSource-Verbindungen nicht sofort als Reconnect-Sturm zurückkehren.
45
+ - keine globale Reconnect-Sperre bei normalem Heap-Druck; bei wirklich kritischem Heap-Druck maximal zehn Sekunden Sperre.
46
46
 
47
47
  Die Werte besitzen konservative interne Grenzen. Nicht mehr lesende Browser, VPN-Tunnel oder Reverse-Proxys können daher keinen unbegrenzt wachsenden Sendepuffer im Adapter erzeugen.
48
48
 
@@ -71,9 +71,9 @@ Die Heapüberwachung ist an die reale Adapterinstanz gebunden und läuft alle 30
71
71
 
72
72
  | Stufe | Standardreaktion |
73
73
  |---|---|
74
- | ab 65 % Heap oder sehr schnellem Wachstum | gedrosselte Diagnosewarnung |
75
- | ab 75 % | Backpressure-/Puffer-Clients schließen und disponiblen SSE-Patch verwerfen |
76
- | ab 82 % | alle SSE-Verbindungen trennen; Browser verbinden sich automatisch neu |
74
+ | ab 65 % Heap | gedrosselte Diagnosewarnung; schneller Wachstumstrend bleibt nur Telemetrie |
75
+ | ab 75 % | nur wirklich blockierte oder stark gepufferte Clients schließen; keine globale Reconnect-Sperre |
76
+ | ab 82 % | alle SSE-Verbindungen trennen; kritische Reconnect-Sperre maximal zehn Sekunden |
77
77
  | ab 86 % über zwei Messungen | kontrollierter Adapterneustart als letzte Notbremse |
78
78
  | ab 92 % | sofortige kontrollierte Notbremse vor V8-`SIGABRT` |
79
79
 
@@ -111,3 +111,8 @@ Geändert werden ausschließlich der LIVE-Transport, der asynchrone Watchdog-Lif
111
111
  - Der EMS-Regeltick läuft für die übrigen Module weiter.
112
112
  - Bei einem seltenen Heapdruckereignis bleibt die Regelung während der ersten Druckentlastung unverändert; nur LIVE-Browser verbinden sich neu.
113
113
  - Ein V8-Hartabsturz bei rund 2 GiB soll durch die frühe Entlastung beziehungsweise die letzte kontrollierte Notbremse vermieden werden.
114
+
115
+
116
+ ## Stable-Patch 1.0.1
117
+
118
+ Der Feldfall mit 11,1 % Heap und 141 MiB Wachstum in zehn Minuten darf keine Druckentlastung mehr auslösen. Ein 32-KiB-Socketpuffer und ein frischer 1-MiB-Initialsnapshot gelten nicht als ungesunde Verbindung. Die automatisierten Tests sichern diese Fälle sowie die weiterhin wirksame Trennung echter Backpressure-Clients ab.
@@ -0,0 +1,62 @@
1
+ # NexoWatt EOS 1.0.1 – offizielle Stable-Version
2
+
3
+ **Veröffentlichungsdatum:** 2026-09-09
4
+ **Status:** Official Stable Patch / produktiver Verkaufsstand
5
+
6
+ ## Zweck des Patches
7
+
8
+ NexoWatt EOS 1.0.1 beseitigt zwei zusammenhängende Fehldiagnosen aus 1.0.0: Der Speicherwächter wertete ein schnelles Heap-Wachstum auch bei sehr niedriger absoluter Auslastung als Speicherdruck. Daraufhin konnten gesunde Server-Sent-Events-Verbindungen geschlossen und für 30 Sekunden an der Wiederverbindung gehindert werden. Die EOS-Übersicht markierte ihre Live-Daten bereits nach ungefähr 20 Sekunden als veraltet und zeigte deshalb kurzzeitig „Offline / Veraltet“, obwohl Adapter, EMS-Regeltakt und Anlage weiterliefen.
9
+
10
+ ## Korrigierte Speicherklassifizierung
11
+
12
+ Die Schutzstufen richten sich nun ausschließlich nach der realen Heap-Auslastung:
13
+
14
+ | Heap-Auslastung | Reaktion |
15
+ |---:|---|
16
+ | unter 65 % | keine Speicherwarnung und keine Druckentlastung |
17
+ | ab 65 % | gedrosselte Diagnosewarnung |
18
+ | ab 75 % | selektive Entlastung wirklich ungesunder SSE-Clients |
19
+ | ab 86 % über zwei Messungen | kontrollierter Adapterneustart als letzte Notbremse |
20
+ | ab 92 % | sofortige kontrollierte Notbremse vor V8-OOM |
21
+
22
+ Der Zehn-Minuten-Trend bleibt in der Diagnose erhalten, kann aber allein weder Warnung noch Entlastung auslösen. Der konkrete Feldfall mit 233 MiB von 2096 MiB, 11,1 % Heap und 141 MiB Wachstum wird daher als `fastGrowth=true`, aber `warn=false` und `pressure=false` klassifiziert.
23
+
24
+ ## Korrigierter SSE-Livekanal
25
+
26
+ Bei normaler Speicherdruckbehandlung gilt jetzt:
27
+
28
+ - keine globale Reconnect-Sperre;
29
+ - ein kleiner normaler HTTP-/Socketpuffer ist kein Fehler;
30
+ - ein frischer Initial- oder Resync-Snapshot erhält bis zum bestehenden Backpressure-Timeout Zeit zum `drain`;
31
+ - getrennt werden nur tatsächlich blockierte oder stark gepufferte Clients;
32
+ - nach einer selektiven Trennung kann EventSource sofort neu verbinden.
33
+
34
+ Bei wirklich kritischem Speicherdruck werden weiterhin alle SSE-Verbindungen geschlossen. Die globale Reconnect-Sperre ist dort auf maximal zehn Sekunden begrenzt. Damit bleibt die Schutzwirkung erhalten, ohne das 20-Sekunden-Frischefenster der EOS-Übersicht regelmäßig zu überschreiten.
35
+
36
+ ## Betriebliche Logmeldungen
37
+
38
+ Laufzeitmeldungen verwenden versionsneutrale Präfixe:
39
+
40
+ ```text
41
+ [memory-guard]
42
+ [sse-guard]
43
+ ```
44
+
45
+ Eine Meldung erscheint nur bei einer realen Schwellenverletzung beziehungsweise einer tatsächlich ungesunden SSE-Verbindung. Historische RC88-Bezeichnungen bleiben ausschließlich in Tests, Dokumentation und internen Kompatibilitätsmarkern bestehen.
46
+
47
+ ## Unveränderte Regelungsfunktionen
48
+
49
+ Der Patch verändert keine fachliche Anlagenregelung. Unverändert bleiben insbesondere:
50
+
51
+ - signierter NVP und Netzanschlussgrenzen;
52
+ - Lade- und Lastmanagement;
53
+ - Speicher- und Multi-Use-Regelung;
54
+ - Netzlimit, feste Einspeisebegrenzung und Nulleinspeisung;
55
+ - Export Guard und Single-Writer-Struktur;
56
+ - §14a, Tarife und Prognosen;
57
+ - EZA-/Parkregler-Priorität und deren Fallbacks;
58
+ - sämtliche produktiven Hardware-Writer.
59
+
60
+ ## Feldprüfung nach Update
61
+
62
+ Nach Installation aus einem frischen Ordner ist der Adapter vollständig neu zu starten. Die EOS-Übersicht sollte mindestens 30 Minuten geöffnet bleiben. Bei niedriger Heap-Auslastung dürfen weder wiederkehrende Speicherwarnungen noch druckbedingte SSE-Trennungen auftreten. Ein echter Adapterausfall, veralteter EMS-Regeltakt oder realer kritischer Speicherdruck bleibt weiterhin sichtbar und wird nicht künstlich als online dargestellt.
@@ -0,0 +1,72 @@
1
+ # NexoWatt EOS 1.0.2 – offizielle Stable-Version
2
+
3
+ **Veröffentlichungsdatum:** 2026-09-09
4
+ **Status:** Official Stable Patch / produktiver Verkaufsstand
5
+
6
+ ## Zweck des Patches
7
+
8
+ NexoWatt EOS 1.0.2 beseitigt die nach 1.0.1 weiterhin beobachtete zyklische Anzeige „Offline / veraltet“ in der EOS-Admin-Übersicht. Der Fehler lag nicht mehr im RC88-Speicherwächter oder im SSE-Livekanal. Es bestand ein eigenständiger Timing-Konflikt zwischen dem ungefähr 20 Sekunden großen Frischefenster der Oberfläche, dem bisherigen 30-Sekunden-Heartbeat von `info.connection` und EMS-/Diagnosezyklen, die innerhalb ihrer Watchdoggrenzen länger als 20 Sekunden laufen dürfen.
9
+
10
+ Der Feldfall zeigte gleichzeitig einen erreichbaren Adapter, einen 25 Sekunden alten Tick-Start und eine vorherige Zyklusdauer von 2608 ms. Ein noch laufender, nicht festhängender Zyklus wurde dabei irrtümlich wie ein nicht erreichbarer Adapter dargestellt.
11
+
12
+ ## Neuer Zustandsvertrag
13
+
14
+ Die Übersicht unterscheidet jetzt vier technisch getrennte Signale:
15
+
16
+ | Signal | Takt / Grenze | Bedeutung |
17
+ |---|---:|---|
18
+ | Adapter-/HTTP-Erreichbarkeit | 4 s | `info.connection` wird aus dem realen Serverzustand bestätigt |
19
+ | EMS-Scheduler-Liveness | 4 s | Schedulerprozess lebt unabhängig vom vollständigen Regelzyklus |
20
+ | EMS-Regelzyklus | Watchdog 30 s, konfigurierbar | laufend, aktuell oder tatsächlich festhängend |
21
+ | Diagnose-Publisher | 4 s Liveness, 5 s Vollsnapshot | Übersichtspfad lebt; vollständige Diagnose kann separat verzögert sein |
22
+
23
+ ### Normalbetrieb
24
+
25
+ Adapter, Scheduler und Regelzyklus sind aktuell. Die Übersicht bleibt online und wechselt nicht aufgrund eines 20–30 Sekunden laufenden Zyklus auf „veraltet“.
26
+
27
+ ### Verzögerter Regelzyklus
28
+
29
+ Ist der Adapter erreichbar und der Scheduler-Heartbeat frisch, läuft der aktuelle Regelzyklus aber länger als die Watchdoggrenze, erscheint eine Warnung:
30
+
31
+ ```text
32
+ Adapter online – EMS-Regelzyklus überschreitet Zeitlimit
33
+ ```
34
+
35
+ Dies ist ausdrücklich kein Adapter-Offlinezustand.
36
+
37
+ ### Tatsächlicher Offlinefall
38
+
39
+ Meldet der reale HTTP-Server nicht mehr `listening`, wird `info.connection=false` geschrieben. Bei Prozessabbruch enden alle Heartbeats und überschreiten das Frischefenster. Beide Fälle werden weiterhin zuverlässig als offline erkannt. Ein frischer Scheduler- oder alter Summary-Wert darf `info.connection=false` nicht überdecken.
40
+
41
+ ## Last- und Ressourcenverhalten
42
+
43
+ Der vollständige Diagnose-Snapshot bleibt im Fünf-Sekunden-Takt. Der unabhängige Liveness-Timer aktualisiert kleine Health-States alle vier Sekunden. `summaryJson` wird vom Zusatzheartbeat nur dann erneuert, wenn der normale Vollsnapshot bereits länger ausbleibt; dadurch wird die übliche Snapshotlast nicht verdoppelt. Alle Timer werden beim Adapter-Unload explizit beendet.
44
+
45
+ ## Regressionstests
46
+
47
+ Die Stable-Prüfung enthält folgende Szenarien:
48
+
49
+ - 25 Sekunden laufender Regelzyklus, frischer Scheduler, vorherige Zyklusdauer 2608 ms: online, kein Stall, keine Veraltet-Anzeige;
50
+ - 35 Sekunden laufender Regelzyklus bei frischem Scheduler: Warnung `tick-stalled`, aber Adapter online;
51
+ - Scheduler-Heartbeat älter als seine Grenze bei weiterhin verbundenem Adapter: Scheduler-Warnung, nicht Adapter offline;
52
+ - `info.connection=false` trotz frischer anderer Werte: sofortiger echter Offlinezustand;
53
+ - unabhängiger Vier-Sekunden-Heartbeat während eines laufenden vollständigen Diagnosezyklus;
54
+ - korrekter Shutdown aller neuen Timer;
55
+ - Auswahl des neuesten statt des ersten vorhandenen Aktivitätszeitstempels.
56
+
57
+ ## Unveränderte Regelungsfunktionen
58
+
59
+ Der Patch betrifft ausschließlich Statusermittlung, Heartbeats und Diagnosepublikation. Unverändert bleiben insbesondere:
60
+
61
+ - signierter NVP und Netzanschlussgrenzen;
62
+ - Lade- und Lastmanagement;
63
+ - Speicher- und Multi-Use-Regelung;
64
+ - Netzlimit, feste Einspeisebegrenzung und Nulleinspeisung;
65
+ - Export Guard und Single-Writer-Struktur;
66
+ - §14a, Tarife und Prognosen;
67
+ - EZA-/Parkregler-Priorität und deren Fallbacks;
68
+ - sämtliche produktiven Hardware-Writer.
69
+
70
+ ## Feldprüfung nach Update
71
+
72
+ Nach Installation aus einem frischen Ordner ist der Adapter vollständig neu zu starten und der Browser einmal mit `Strg+F5` zu laden. Die EOS-Übersicht sollte mindestens 30 Minuten geöffnet bleiben. Im Normalbetrieb darf sie nicht mehr rhythmisch zwischen online und „Offline / veraltet“ wechseln. Für einen Gegencheck kann die Adapterinstanz kontrolliert gestoppt werden; nach dem Frischefenster muss die Übersicht eindeutig offline anzeigen.
package/ems/engine.js CHANGED
@@ -2,7 +2,7 @@
2
2
  * AUTO-GENERATED RUNTIME FILE - NICHT MANUELL BEARBEITEN.
3
3
  *
4
4
  * Quelle: src-ts/runtime-executables/ems/engine.ts
5
- * Quell-Hash: sha256:39e9a577a619aebd1cda1e43ddb58f9cc7d647d71b568b8e6a06e04f272c0543
5
+ * Quell-Hash: sha256:d8f7bab38ff19e7fa52d306e498c09f5fbe229bf47f12bb425c7e2ba8c5c8951
6
6
  * Erzeugung: npm run sync:ts-runtime-executables
7
7
  *
8
8
  * Zweck:
@@ -107,6 +107,13 @@ class EmsEngine {
107
107
  this.mm = null;
108
108
  this._timer = null;
109
109
  this._intervalMs = 1000;
110
+ // Independent scheduler liveness. It is deliberately separate from the
111
+ // complete EMS tick, because a legitimate long-running module must not make
112
+ // EOS Admin classify the whole adapter as offline.
113
+ this._schedulerHeartbeatTimer = null;
114
+ this._schedulerHeartbeatRunning = false;
115
+ this._schedulerHeartbeatIntervalMs = 4000;
116
+ this._schedulerHeartbeatSequence = 0;
110
117
  // Reaktionspfad für Bedienänderungen: Ein Moduswechsel im Kundenfrontend
111
118
  // soll nicht bis zum nächsten regulären Scheduler-Tick warten. Der kurze
112
119
  // Debounce fasst API-Write und nachfolgenden StateChange zu genau einem
@@ -333,6 +340,42 @@ class EmsEngine {
333
340
  },
334
341
  native: {},
335
342
  });
343
+ await a.setObjectNotExistsAsync('ems.core.schedulerHeartbeatAt', {
344
+ type: 'state',
345
+ common: {
346
+ name: 'Independent EMS scheduler heartbeat (ts)',
347
+ type: 'number',
348
+ role: 'value.time',
349
+ read: true,
350
+ write: false,
351
+ def: 0,
352
+ },
353
+ native: {},
354
+ });
355
+ await a.setObjectNotExistsAsync('ems.core.schedulerHeartbeatSequence', {
356
+ type: 'state',
357
+ common: {
358
+ name: 'Independent EMS scheduler heartbeat sequence',
359
+ type: 'number',
360
+ role: 'value',
361
+ read: true,
362
+ write: false,
363
+ def: 0,
364
+ },
365
+ native: {},
366
+ });
367
+ await a.setObjectNotExistsAsync('ems.core.schedulerAlive', {
368
+ type: 'state',
369
+ common: {
370
+ name: 'EMS scheduler process alive',
371
+ type: 'boolean',
372
+ role: 'indicator.connected',
373
+ read: true,
374
+ write: false,
375
+ def: false,
376
+ },
377
+ native: {},
378
+ });
336
379
  await a.setObjectNotExistsAsync('ems.core.tickSkipCount', {
337
380
  type: 'state',
338
381
  common: {
@@ -987,6 +1030,55 @@ class EmsEngine {
987
1030
  catch (_e) { }
988
1031
  return { anyControl, chargingCfg, stationGroups, stationGroupMap };
989
1032
  }
1033
+ /**
1034
+ * Publishes scheduler liveness independently from a full EMS control cycle.
1035
+ * The local process object is updated even if a previous ioBroker state write
1036
+ * is delayed, so the co-located Admin overview can still distinguish a live
1037
+ * scheduler from a stalled regulation tick.
1038
+ */
1039
+ async _publishSchedulerHeartbeat(reason = 'timer') {
1040
+ if (!this.adapter || this.adapter._nwShuttingDown)
1041
+ return;
1042
+ const now = Date.now();
1043
+ const configuredStaleMs = clampNumber(this.adapter?.config?.diagnostics?.emsTickStaleAfterMs, 15000, 300000, this._tickStaleAfterMs);
1044
+ const activeTickAgeMs = this._tickRunning && this._lastTickStartMs > 0
1045
+ ? Math.max(0, now - this._lastTickStartMs)
1046
+ : 0;
1047
+ const tickStalled = this._tickRunning && activeTickAgeMs > configuredStaleMs;
1048
+ this._schedulerHeartbeatSequence += 1;
1049
+ this.adapter._nwEmsSchedulerHealth = {
1050
+ heartbeatAt: now,
1051
+ sequence: this._schedulerHeartbeatSequence,
1052
+ reason: String(reason || 'timer'),
1053
+ tickRunning: this._tickRunning === true,
1054
+ activeTickAgeMs,
1055
+ tickStalled,
1056
+ tickStaleAfterMs: configuredStaleMs,
1057
+ lastTickStartMs: this._lastTickStartMs,
1058
+ lastTickEndMs: this._lastTickEndMs,
1059
+ };
1060
+ if (this._schedulerHeartbeatRunning)
1061
+ return;
1062
+ this._schedulerHeartbeatRunning = true;
1063
+ try {
1064
+ await Promise.allSettled([
1065
+ this.adapter.setStateAsync('ems.core.schedulerHeartbeatAt', { val: now, ack: true }),
1066
+ this.adapter.setStateAsync('ems.core.schedulerHeartbeatSequence', { val: Math.round(this._schedulerHeartbeatSequence), ack: true }),
1067
+ this.adapter.setStateAsync('ems.core.schedulerAlive', { val: true, ack: true }),
1068
+ ]);
1069
+ }
1070
+ finally {
1071
+ this._schedulerHeartbeatRunning = false;
1072
+ }
1073
+ }
1074
+ _startSchedulerHeartbeat() {
1075
+ if (!this.adapter || this.adapter._nwShuttingDown || this._schedulerHeartbeatTimer)
1076
+ return;
1077
+ this._publishSchedulerHeartbeat('startup').catch(() => { });
1078
+ this._schedulerHeartbeatTimer = this._setInterval(() => {
1079
+ this._publishSchedulerHeartbeat('timer').catch(() => { });
1080
+ }, this._schedulerHeartbeatIntervalMs);
1081
+ }
990
1082
  /**
991
1083
  * Code-Teil: Methode `init`
992
1084
  * Zweck: initialisiert UI/Modul, bindet Events oder bereitet Startzustände vor.
@@ -1002,6 +1094,7 @@ class EmsEngine {
1002
1094
  async init() {
1003
1095
  const adapter = this.adapter;
1004
1096
  await this._ensureInternalStates();
1097
+ this._startSchedulerHeartbeat();
1005
1098
  // Scheduler interval from config (Admin UI / jsonConfig)
1006
1099
  const cfgInterval = adapter.config && adapter.config.schedulerIntervalMs;
1007
1100
  // Aktor- und Speicher-Watchdogs muessen spaetestens sekündlich erneuert werden.
@@ -1238,6 +1331,7 @@ class EmsEngine {
1238
1331
  this._activeTickId = tickId;
1239
1332
  const tickStart = Date.now();
1240
1333
  this._lastTickStartMs = tickStart;
1334
+ this._publishSchedulerHeartbeat('tick-start').catch(() => { });
1241
1335
  try {
1242
1336
  try {
1243
1337
  await this.adapter.setStateAsync('ems.core.tickRunning', { val: true, ack: true });
@@ -1366,6 +1460,7 @@ class EmsEngine {
1366
1460
  }
1367
1461
  const dur = Date.now() - tickStart;
1368
1462
  this._lastTickEndMs = Date.now();
1463
+ this._publishSchedulerHeartbeat('tick-end').catch(() => { });
1369
1464
  try {
1370
1465
  if (ownsTickLock)
1371
1466
  await this.adapter.setStateAsync('ems.core.tickRunning', { val: false, ack: true });
@@ -1397,6 +1492,20 @@ class EmsEngine {
1397
1492
  * TypeScript: Parameter, Rückgabewert und verwendete Config-/State-Objekte später explizit typisieren.
1398
1493
  */
1399
1494
  stop() {
1495
+ if (this._schedulerHeartbeatTimer) {
1496
+ this._clearInterval(this._schedulerHeartbeatTimer);
1497
+ this._schedulerHeartbeatTimer = null;
1498
+ }
1499
+ this._schedulerHeartbeatRunning = false;
1500
+ try {
1501
+ this.adapter._nwEmsSchedulerHealth = {
1502
+ ...(this.adapter._nwEmsSchedulerHealth || {}),
1503
+ heartbeatAt: Date.now(),
1504
+ alive: false,
1505
+ reason: 'stopped',
1506
+ };
1507
+ }
1508
+ catch (_error) { }
1400
1509
  if (this._timer) {
1401
1510
  this._clearInterval(this._timer);
1402
1511
  this._timer = null;
@@ -2,7 +2,7 @@
2
2
  * AUTO-GENERATED RUNTIME FILE - NICHT MANUELL BEARBEITEN.
3
3
  *
4
4
  * Quelle: src-ts/runtime-executables/ems/rc85-runtime-hardening.ts
5
- * Quell-Hash: sha256:2e5cbd3d062cfb1ab94e5e455028046a9d9c028046bf7c848303a05bf49479d0
5
+ * Quell-Hash: sha256:77b6ae16d241c077964a527174f3226e3d94a66a84126d3b0d9eb1abb7d83d8c
6
6
  * Erzeugung: npm run sync:ts-runtime-executables
7
7
  *
8
8
  * Zweck:
@@ -27,6 +27,7 @@ exports.rc85IsSoftEconomicReason = rc85IsSoftEconomicReason;
27
27
  exports.rc85GridEnvelope = rc85GridEnvelope;
28
28
  exports.rc86GridBinding = rc86GridBinding;
29
29
  exports.rc85OfflineReserveW = rc85OfflineReserveW;
30
+ exports.rc88ClassifyHeapPressure = rc88ClassifyHeapPressure;
30
31
  exports.startRc85HeapMonitor = startRc85HeapMonitor;
31
32
  exports.stopRc85HeapMonitor = stopRc85HeapMonitor;
32
33
  /* RC85: shared stability and charging-control hardening. */
@@ -432,6 +433,32 @@ function clampRatio(value, fallback, min, max) {
432
433
  const n = Number(value);
433
434
  return Number.isFinite(n) ? Math.max(min, Math.min(max, n)) : fallback;
434
435
  }
436
+ /**
437
+ * Classifies one heap sample without side effects.
438
+ *
439
+ * A rapid ten-minute increase remains useful telemetry, but is deliberately not
440
+ * a pressure signal on its own. V8 may grow a young process, caches and compiled
441
+ * code quickly while the absolute heap ratio is still low. Treating that normal
442
+ * warm-up as pressure used to close healthy SSE clients and made the overview
443
+ * appear stale although the adapter and EMS loop were running normally.
444
+ */
445
+ function rc88ClassifyHeapPressure(input) {
446
+ const ratio = Math.max(0, Number(input.ratio) || 0);
447
+ const growthBytes = Number(input.growthBytes) || 0;
448
+ const warnRatio = clampRatio(input.warnRatio, 0.65, 0.4, 0.9);
449
+ const pressureRatio = clampRatio(input.pressureRatio, 0.75, warnRatio, 0.92);
450
+ const restartRatio = clampRatio(input.restartRatio, 0.86, pressureRatio, 0.95);
451
+ const emergencyRatio = clampRatio(input.emergencyRatio, 0.92, restartRatio, 0.98);
452
+ return {
453
+ ratio,
454
+ growthBytes,
455
+ fastGrowth: growthBytes >= 128 * 1048576,
456
+ warn: ratio >= warnRatio,
457
+ pressure: ratio >= pressureRatio,
458
+ restart: ratio >= restartRatio,
459
+ emergency: ratio >= emergencyRatio,
460
+ };
461
+ }
435
462
  function safeDiagnosticsJson() {
436
463
  try {
437
464
  const diagnostics = heapMonitorOptions.getDiagnostics?.();
@@ -450,7 +477,7 @@ function scheduleControlledRestart(sample, reason) {
450
477
  heapMonitorOptions.onBeforeRestart?.(sample);
451
478
  }
452
479
  catch (_error) { }
453
- heapMonitorLog.error?.(`[RC88 heap] ${reason}; controlled adapter restart requested before V8 OOM. `
480
+ heapMonitorLog.error?.(`[memory-guard] ${reason}; controlled adapter restart requested before V8 OOM. `
454
481
  + `heap=${(sample.heapUsed / 1048576).toFixed(0)}/${(sample.heapLimit / 1048576).toFixed(0)} MiB `
455
482
  + `rss=${(sample.rss / 1048576).toFixed(0)} MiB diagnostics=${safeDiagnosticsJson()}`);
456
483
  heapRestartTimer = setTimeout(() => process.exit(11), 1500);
@@ -482,24 +509,31 @@ function runHeapMonitorSample() {
482
509
  const restartRatio = clampRatio(heapMonitorOptions.restartRatio, 0.86, pressureRatio, 0.95);
483
510
  const emergencyRatio = clampRatio(heapMonitorOptions.emergencyRatio, 0.92, restartRatio, 0.98);
484
511
  const sustainedSamples = Math.max(1, Math.min(5, Math.round(Number(heapMonitorOptions.sustainedSamples) || 2)));
485
- const fastGrowth = growthBytes >= 128 * 1048576;
486
- if ((ratio >= warnRatio || fastGrowth) && now - lastHeapWarnAt >= 5 * 60000) {
512
+ const classification = rc88ClassifyHeapPressure({
513
+ ratio,
514
+ growthBytes,
515
+ warnRatio,
516
+ pressureRatio,
517
+ restartRatio,
518
+ emergencyRatio,
519
+ });
520
+ if (classification.warn && now - lastHeapWarnAt >= 5 * 60000) {
487
521
  lastHeapWarnAt = now;
488
- heapMonitorLog.warn?.(`[RC88 heap] ${(memory.heapUsed / 1048576).toFixed(0)} MiB / ${(heapLimit / 1048576).toFixed(0)} MiB `
522
+ heapMonitorLog.warn?.(`[memory-guard] ${(memory.heapUsed / 1048576).toFixed(0)} MiB / ${(heapLimit / 1048576).toFixed(0)} MiB `
489
523
  + `(${(ratio * 100).toFixed(1)}%), rss ${(memory.rss / 1048576).toFixed(0)} MiB, `
490
524
  + `10-min growth ${(growthBytes / 1048576).toFixed(0)} MiB; diagnostics=${safeDiagnosticsJson()}`);
491
525
  }
492
- if ((ratio >= pressureRatio || fastGrowth) && now - lastPressureActionAt >= 30000) {
526
+ if (classification.pressure && now - lastPressureActionAt >= 30000) {
493
527
  lastPressureActionAt = now;
494
528
  try {
495
529
  heapMonitorOptions.onPressure?.(sample);
496
530
  }
497
531
  catch (error) {
498
- heapMonitorLog.warn?.(`[RC88 heap] pressure mitigation failed: ${error instanceof Error ? error.message : String(error)}`);
532
+ heapMonitorLog.warn?.(`[memory-guard] pressure mitigation failed: ${error instanceof Error ? error.message : String(error)}`);
499
533
  }
500
534
  }
501
- criticalHeapSamples = ratio >= restartRatio ? criticalHeapSamples + 1 : 0;
502
- if (ratio >= emergencyRatio) {
535
+ criticalHeapSamples = classification.restart ? criticalHeapSamples + 1 : 0;
536
+ if (classification.emergency) {
503
537
  scheduleControlledRestart(sample, `emergency heap pressure ${(ratio * 100).toFixed(1)}%`);
504
538
  }
505
539
  else if (criticalHeapSamples >= sustainedSamples) {