instar 1.3.710 → 1.3.711

package/dist/monitoring/RopeHealthMonitor.js

@@ -0,0 +1,659 @@
+/**
+ * RopeHealthMonitor — U4.5 rope-health alerts
+ * (docs/specs/u4-5-rope-health-alerts.md).
+ *
+ * Mesh transport degradation was silent: a Tailscale key expiry dropped a rope
+ * with no warning; a persistently-down rope was visible only to someone who
+ * went looking; an all-transports-down partition — the precondition for silent
+ * message loss — had no prompt alert at all. This monitor is the productized,
+ * in-server detector: it runs its OWN bounded 30s evaluation loop (constructed
+ * and torn down by the real server boot — R-r2-2), reads the U4.3
+ * `PeerEndpointResolver.snapshot()` seam (the HARD data dependency; no interim
+ * fallback exists), and classifies each peer deterministically:
+ *
+ *   ok           — silence (no digest line, nothing).
+ *   degraded     — a rope down while ≥1 other rope is healthy, or a Tailscale
+ *                  key expiring within `keyExpiryWarnDays`. Digest-only.
+ *   peer-offline — ALL ropes down AND the peer's git-synced coarse heartbeat
+ *                  has STOPPED advancing (or the registry already marks it
+ *                  offline). Digest-only — a lid-close is NEVER urgent.
+ *   urgent       — ALL ropes down to a peer whose git-synced coarse heartbeat
+ *                  is still ADVANCING — advancement-since-onset semantics
+ *                  (R-r3-1): a beat NEWER than the all-down onset, observed
+ *                  after the onset. Freshness-window semantics are REJECTED
+ *                  (a just-lid-closed peer's last beat looks fresh for up to
+ *                  an hour). ONE HIGH attention item per episode.
+ *
+ * The urgent tier's honest detection latency is bounded by the heartbeat
+ * interval plus up to two git-sync cadences (~30-90 min); `urgentDebounceMs`
+ * is only the short-term flap filter on the all-down condition itself.
+ *
+ * Episode semantics: episodeKey = sorted machine pair + the onset quantized to
+ * 15 min — deterministically computable on BOTH sides without coordination;
+ * post-heal grouping matches ADJACENT quantization windows (R-r2-5). An episode
+ * ends only after `clearSustainMs` of continuous health (a blip cannot
+ * clear-then-re-fire). At most ONE item per side per episode; if a split-brain
+ * item is already open for the same peer, the monitor does not raise a second.
+ *
+ * Durable state (`state/rope-health.json`): transition-only writes with a short
+ * debounce (R-r2-4) — a steady-state evaluation never touches disk; counters
+ * lost to a restart are accepted (the safe direction: a restart re-debounces,
+ * never fabricates an episode).
+ *
+ * Content scrub (hard rule): alert/digest text carries rope KIND + machine
+ * NICKNAME + relative times ONLY — never raw IPs, URLs, tunnel hostnames,
+ * tailnet names, or account emails (the tailscale JSON's identifying fields
+ * never leave `parseTailscaleStatus`).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+import { parseTailscaleStatus, soonestKeyExpiry, } from '../core/tailscaleStatusParser.js';
+export const ROPE_HEALTH_DEFAULTS = {
+    urgentEnabled: true,
+    urgentDebounceMs: 60_000,
+    clearSustainMs: 600_000,
+    keyExpiryWarnDays: 14,
+    evaluateIntervalMs: 30_000,
+    keyExpiryCheckIntervalMs: 3_600_000,
+    wakeGraceMaxMs: 300_000,
+    episodeQuantumMs: 900_000,
+    writeDebounceMs: 2_000,
+};
+/**
+ * Deterministic shared episode key: both sides compute the same value from the
+ * sorted machine pair + the onset's quantization window (spec §2).
+ */
+export function computeEpisodeKey(machineA, machineB, onsetMs, quantumMs = ROPE_HEALTH_DEFAULTS.episodeQuantumMs) {
+    const pair = [machineA, machineB].sort().join('+');
+    const win = Math.floor(onsetMs / quantumMs) * quantumMs;
+    return `${pair}:${win}`;
+}
+/**
+ * Post-heal grouping (R-r2-5): two episode keys group when they name the same
+ * machine pair and their quantization windows are ADJACENT (±1 quantum) — the
+ * two sides detect at different instants, so an onset straddling a boundary
+ * yields adjacent window keys. Beyond one quantum the keys honestly show as
+ * two groups (declared best-effort display degradation).
+ */
+export function episodeKeysGroup(a, b, quantumMs = ROPE_HEALTH_DEFAULTS.episodeQuantumMs) {
+    const pa = a.lastIndexOf(':');
+    const pb = b.lastIndexOf(':');
+    if (pa <= 0 || pb <= 0)
+        return false;
+    if (a.slice(0, pa) !== b.slice(0, pb))
+        return false;
+    const wa = Number(a.slice(pa + 1));
+    const wb = Number(b.slice(pb + 1));
+    if (!Number.isFinite(wa) || !Number.isFinite(wb))
+        return false;
+    return Math.abs(wa - wb) <= quantumMs;
+}
+/** Candidate tailscale CLI paths (same set as MeshUrlAdvertiser Decision 16). */
+const TAILSCALE_CANDIDATES = [
+    '/opt/homebrew/bin/tailscale',
+    '/usr/local/bin/tailscale',
+    '/Applications/Tailscale.app/Contents/MacOS/Tailscale',
+    'tailscale',
+];
+/** Default bounded exec: 5s hard timeout; absent CLI / any failure ⇒ null. */
+export function defaultExecTailscaleStatusJson() {
+    return new Promise((resolve) => {
+        const tryNext = (i) => {
+            if (i >= TAILSCALE_CANDIDATES.length) {
+                resolve(null);
+                return;
+            }
+            const file = TAILSCALE_CANDIDATES[i];
+            if (file !== 'tailscale' && !fs.existsSync(file)) {
+                tryNext(i + 1);
+                return;
+            }
+            execFile(file, ['status', '--json'], { timeout: 5_000, maxBuffer: 4 * 1024 * 1024 }, (err, stdout) => {
+                if (err || !stdout) {
+                    tryNext(i + 1);
+                    return;
+                }
+                resolve(String(stdout));
+            });
+        };
+        tryNext(0);
+    });
+}
+export class RopeHealthMonitor {
+    d;
+    cfg;
+    peers = new Map();
+    timer = null;
+    lastEvaluatedAt = null;
+    evaluations = 0;
+    evaluating = false;
+    // Self-wake grace (bounded — see wakeGraceMaxMs hazard note / P1-A7).
+    ownWakeAt = null;
+    // Key-expiry tier state.
+    keyExpiryLastCheckedAt = null;
+    keyExpiryAvailable = false;
+    keyExpirySoonest = null;
+    keyExpiryAbsentLogged = false;
+    keyExpiryInFlight = false;
+    // Counters (observability only).
+    urgentEpisodes = 0;
+    suppressedBySleepGate = 0;
+    suppressedBySplitBrain = 0;
+    notNotifiedRetries = 0;
+    // Transition-only durable writes (R-r2-4).
+    writePending = false;
+    writeTimer = null;
+    constructor(deps, cfg) {
+        this.d = deps;
+        this.cfg = { ...ROPE_HEALTH_DEFAULTS, ...cfg };
+        this.loadState();
+    }
+    now() {
+        return (this.d.now ?? Date.now)();
+    }
+    log(m) {
+        this.d.logger?.(`[rope-health] ${m}`);
+    }
+    metric(e) {
+        try {
+            this.d.recordMetric?.(e);
+        }
+        catch {
+            // @silent-fallback-ok: metrics are observability, never authority — a
+            // recorder fault must not break the evaluation loop.
+        }
+    }
+    /** Start the monitor's OWN bounded evaluation loop (R-r2-2). */
+    start() {
+        if (this.timer)
+            return;
+        this.evaluate();
+        this.timer = setInterval(() => this.evaluate(), this.cfg.evaluateIntervalMs);
+        if (typeof this.timer.unref === 'function')
+            this.timer.unref();
+    }
+    /** Torn down at server shutdown (R-r2-2). Flushes any pending state write. */
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        if (this.writeTimer) {
+            clearTimeout(this.writeTimer);
+            this.writeTimer = null;
+        }
+        if (this.writePending)
+            this.writeStateNow();
+    }
+    /** Is the evaluation loop currently armed? (e2e wiring-integrity read.) */
+    running() {
+        return this.timer !== null;
+    }
+    /**
+     * Own-machine wake note (SleepWakeDetector 'wake' — the ONE thing it can
+     * tell us). Post-wake, all snapshots are stale; urgent is suppressed until
+     * each (peer, kind) is re-observed post-wake — BOUNDED by wakeGraceMaxMs
+     * (P1-A7: false wake events must never become an open-ended veto).
+     */
+    noteOwnWake(atMs) {
+        this.ownWakeAt = atMs ?? this.now();
+    }
+    /** One evaluation pass. Public for tests; the loop calls it on cadence. */
+    evaluate() {
+        if (this.evaluating)
+            return;
+        this.evaluating = true;
+        try {
+            this.evaluateInner();
+        }
+        catch (err) {
+            // Fail toward silence, never a crashed loop (signal, not authority).
+            this.log(`evaluation error: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        finally {
+            this.evaluating = false;
+        }
+    }
+    evaluateInner() {
+        const nowMs = this.now();
+        this.lastEvaluatedAt = nowMs;
+        this.evaluations += 1;
+        this.metric('evaluation');
+        const rows = this.safeSnapshot();
+        const rowsByPeer = new Map();
+        for (const r of rows) {
+            const list = rowsByPeer.get(r.peer) ?? [];
+            list.push(r);
+            rowsByPeer.set(r.peer, list);
+        }
+        for (const peer of this.safePeers()) {
+            const st = this.peers.get(peer.machineId) ?? freshPeerState();
+            this.peers.set(peer.machineId, st);
+            const peerRows = rowsByPeer.get(peer.machineId) ?? [];
+            const prev = st.condition;
+            // Absent-record semantics (R-r2-minor): a peer with NO snapshot rows is
+            // UNKNOWN, not down — fails toward NOT-urgent.
+            if (peerRows.length === 0) {
+                this.settleHealthy(st, nowMs);
+                st.condition = 'unknown';
+                this.recordTransition(prev, st.condition);
+                continue;
+            }
+            const deadRows = peerRows.filter((r) => r.dead);
+            const allDown = deadRows.length === peerRows.length;
+            if (!allDown) {
+                this.settleHealthy(st, nowMs);
+                st.condition = deadRows.length > 0 ? 'degraded' : 'ok';
+                this.recordTransition(prev, st.condition);
+                continue;
+            }
+            // ── ALL ropes down. ──
+            st.healthySince = null;
+            if (st.allDownSince === null) {
+                st.allDownSince = nowMs;
+                st.consecutiveObservations = 1;
+                st.episodeKey = computeEpisodeKey(this.d.selfMachineId, peer.machineId, nowMs, this.cfg.episodeQuantumMs);
+                st.postOnsetBeatObservedAt = null;
+                this.log(`all-down onset for ${peer.nickname} (episode ${st.episodeKey})`);
+            }
+            else {
+                st.consecutiveObservations += 1;
+            }
+            // The R-r3-1 discriminator: advancement-since-onset — a heartbeat NEWER
+            // than the onset, observed after the onset. Freshness-window semantics
+            // are rejected (a just-lid-closed peer's pre-sleep beat looks fresh).
+            const hbAt = this.safeHeartbeat(peer.machineId);
+            if (hbAt !== null && st.allDownSince !== null && hbAt > st.allDownSince && st.postOnsetBeatObservedAt === null) {
+                st.postOnsetBeatObservedAt = nowMs;
+            }
+            if (!peer.registryOnline) {
+                // WS4.2 'offline since <t>' — expected. Never urgent.
+                st.condition = 'peer-offline';
+                this.recordTransition(prev, st.condition);
+                continue;
+            }
+            if (st.postOnsetBeatObservedAt === null) {
+                // Heartbeat stopped (peer likely asleep/off) or no post-onset beat has
+                // landed YET — late-but-honest: a later post-onset beat upgrades this.
+                st.condition = 'peer-offline';
+                this.recordTransition(prev, st.condition);
+                continue;
+            }
+            // ── Urgent candidate: all-down + advancing heartbeat. ──
+            st.condition = 'urgent';
+            this.recordTransition(prev, st.condition);
+            if (!this.cfg.urgentEnabled)
+                continue;
+            // Time-pinned debounce (R-r2-2) + ≥2 consecutive observations: a spurious
+            // single-evaluation blip (or a spurious SLEEP signal coinciding with a
+            // real rope failure — the P1-A7 hazard test) never fires alone, and a
+            // REAL sustained partition always fires once the debounce elapses.
+            if (nowMs - (st.allDownSince ?? nowMs) < this.cfg.urgentDebounceMs)
+                continue;
+            if (st.consecutiveObservations < 2)
+                continue;
+            // Self-wake grace (BOUNDED — P1-A7): suppress only while (a) inside the
+            // wakeGraceMaxMs cap AND (b) some rope of this peer has not been
+            // re-observed since the wake. A false wake event therefore delays an
+            // urgent item by AT MOST wakeGraceMaxMs, never vetoes it.
+            if (this.sleepGateSuppresses(peerRows, nowMs)) {
+                this.suppressedBySleepGate += 1;
+                this.metric('suppressed-by-sleep-gate');
+                continue;
+            }
+            if (st.urgentRaisedAt !== null && !st.detectedNotNotified)
+                continue; // one item per episode
+            if (this.safeSplitBrainOpen(peer.machineId)) {
+                // One episode, one ask — the already-open split-brain item wins.
+                this.suppressedBySplitBrain += 1;
+                this.metric('suppressed-by-split-brain');
+                continue;
+            }
+            this.raiseUrgent(peer, st, nowMs);
+        }
+        // ── Key-expiry tier (own cadence, R-r2-3). ──
+        if (this.keyExpiryLastCheckedAt === null ||
+            nowMs - this.keyExpiryLastCheckedAt >= this.cfg.keyExpiryCheckIntervalMs) {
+            this.checkKeyExpiry(nowMs);
+        }
+    }
+    settleHealthy(st, nowMs) {
+        if (st.allDownSince === null)
+            return;
+        // Episode still open: sustained-clear gate (a blip cannot clear-then-re-fire).
+        if (st.healthySince === null)
+            st.healthySince = nowMs;
+        if (nowMs - st.healthySince >= this.cfg.clearSustainMs) {
+            this.log(`episode ${st.episodeKey ?? '?'} ended after sustained health`);
+            st.allDownSince = null;
+            st.consecutiveObservations = 0;
+            st.episodeKey = null;
+            st.urgentRaisedAt = null;
+            st.detectedNotNotified = false;
+            st.postOnsetBeatObservedAt = null;
+            st.healthySince = null;
+            this.scheduleWrite();
+        }
+    }
+    sleepGateSuppresses(peerRows, nowMs) {
+        if (this.ownWakeAt === null)
+            return false;
+        if (nowMs - this.ownWakeAt > this.cfg.wakeGraceMaxMs)
+            return false; // bounded (P1-A7)
+        // Suppress only while some rope has NOT been re-observed post-wake.
+        return peerRows.some((r) => Math.max(r.lastOkAt, r.lastFailAt) <= this.ownWakeAt);
+    }
+    raiseUrgent(peer, st, nowMs) {
+        // The urgent-episode counter fires on the FIRST successful delivery for
+        // this episode (a delivery that only succeeded on a retry still counts once).
+        const firstDelivery = st.urgentRaisedAt === null;
+        const sinceMin = st.allDownSince ? Math.round((nowMs - st.allDownSince) / 60_000) : 0;
+        // Content scrub: kind + nickname + relative time ONLY.
+        const kinds = 'every mesh rope';
+        const item = {
+            id: `rope-health-urgent:${st.episodeKey ?? peer.machineId}`,
+            title: `Mesh partition: ${peer.nickname} unreachable but alive`,
+            body: `ALL mesh ropes (${kinds}) to ${peer.nickname} have been down for ~${sinceMin} min, ` +
+                `but its machine heartbeat is still advancing — it is alive yet unreachable (a genuine partition, ` +
+                `not a sleeping machine). Messages routed to it may be delayed until a rope recovers. ` +
+                `Episode ${st.episodeKey ?? 'n/a'}; this is the ONE alert for this episode.`,
+        };
+        try {
+            const r = this.d.raiseAttention(item);
+            if (r && typeof r.then === 'function') {
+                void r.then(() => this.settleNotified(st, nowMs, firstDelivery), () => this.markNotNotified(st));
+            }
+            else {
+                this.settleNotified(st, nowMs, firstDelivery);
+            }
+        }
+        catch {
+            // Detected-but-silent must be impossible to lose silently: the failure is
+            // recorded and the next evaluation retries (spec "alert delivery honesty").
+            this.markNotNotified(st);
+        }
+    }
+    settleNotified(st, nowMs, firstDelivery) {
+        st.urgentRaisedAt = nowMs;
+        st.detectedNotNotified = false;
+        if (firstDelivery) {
+            this.urgentEpisodes += 1;
+            this.metric('urgent-episode');
+        }
+        this.scheduleWrite();
+    }
+    markNotNotified(st) {
+        if (st.detectedNotNotified) {
+            this.notNotifiedRetries += 1;
+            this.metric('detected-not-notified-retry');
+        }
+        st.detectedNotNotified = true;
+        if (st.urgentRaisedAt === null)
+            st.urgentRaisedAt = null; // stays unraised — retried next evaluation
+        this.scheduleWrite();
+    }
+    checkKeyExpiry(nowMs) {
+        if (this.keyExpiryInFlight)
+            return;
+        this.keyExpiryInFlight = true;
+        this.keyExpiryLastCheckedAt = nowMs;
+        const exec = this.d.execTailscaleStatusJson ?? defaultExecTailscaleStatusJson;
+        void Promise.resolve()
+            .then(() => exec())
+            .then((raw) => {
+            if (raw === null) {
+                // Absent CLI ⇒ the expiry tier is silently absent (ONE debug line).
+                this.keyExpiryAvailable = false;
+                this.keyExpirySoonest = null;
+                if (!this.keyExpiryAbsentLogged) {
+                    this.keyExpiryAbsentLogged = true;
+                    this.log('tailscale CLI absent/unavailable — key-expiry tier silently absent');
+                }
+                return;
+            }
+            const parse = parseTailscaleStatus(raw);
+            if (!parse.parsed) {
+                this.keyExpiryAvailable = false;
+                this.keyExpirySoonest = null;
+                return;
+            }
+            this.keyExpiryAvailable = true;
+            this.keyExpirySoonest = soonestKeyExpiry(parse, this.now());
+            if (this.keyExpiryWarn())
+                this.metric('key-expiry-warning');
+        })
+            .catch((err) => {
+            // @silent-fallback-ok: the expiry tier degrades to absent on any exec
+            // fault (the rest of the monitor is unaffected — spec R-r2-3).
+            this.log(`key-expiry check failed: ${err instanceof Error ? err.message : String(err)}`);
+            this.keyExpiryAvailable = false;
+        })
+            .finally(() => {
+            this.keyExpiryInFlight = false;
+        });
+    }
+    keyExpiryWarn() {
+        return (this.keyExpiryAvailable &&
+            this.keyExpirySoonest !== null &&
+            this.keyExpirySoonest.inDays <= this.cfg.keyExpiryWarnDays);
+    }
+    /** The GET /mesh/rope-health read surface (content-scrubbed). */
+    status() {
+        const rows = this.safeSnapshot();
+        const rowsByPeer = new Map();
+        for (const r of rows) {
+            const list = rowsByPeer.get(r.peer) ?? [];
+            list.push(r);
+            rowsByPeer.set(r.peer, list);
+        }
+        const peers = [];
+        for (const p of this.safePeers()) {
+            const st = this.peers.get(p.machineId);
+            peers.push({
+                machineId: p.machineId,
+                nickname: p.nickname,
+                condition: st?.condition ?? 'unknown',
+                kinds: (rowsByPeer.get(p.machineId) ?? []).map((r) => ({
+                    kind: r.kind,
+                    dead: r.dead,
+                    consecutiveFailures: r.consecutiveFailures,
+                })),
+                allDownSince: st?.allDownSince ?? null,
+                episodeKey: st?.episodeKey ?? null,
+                urgentRaisedAt: st?.urgentRaisedAt ?? null,
+                detectedNotNotified: st?.detectedNotNotified ?? false,
+            });
+        }
+        return {
+            lastEvaluatedAt: this.lastEvaluatedAt,
+            evaluations: this.evaluations,
+            peers,
+            keyExpiry: {
+                available: this.keyExpiryAvailable,
+                ...(this.keyExpirySoonest
+                    ? { soonest: { ...this.keyExpirySoonest, inDays: Math.round(this.keyExpirySoonest.inDays * 10) / 10 } }
+                    : {}),
+                warn: this.keyExpiryWarn(),
+                lastCheckedAt: this.keyExpiryLastCheckedAt,
+            },
+            digest: this.composeDigest(),
+            counters: {
+                urgentEpisodes: this.urgentEpisodes,
+                suppressedBySleepGate: this.suppressedBySleepGate,
+                suppressedBySplitBrain: this.suppressedBySplitBrain,
+                notNotifiedRetries: this.notNotifiedRetries,
+            },
+        };
+    }
+    /**
+     * The consolidated daily-digest section (≤3 sentences, clamped,
+     * machine-named), or null when everything is ok — the rope-health-digest
+     * job's content source. Deterministic; content-scrubbed by construction.
+     */
+    composeDigest() {
+        const nowMs = this.now();
+        const sentences = [];
+        for (const p of this.safePeers()) {
+            const st = this.peers.get(p.machineId);
+            if (!st)
+                continue;
+            if (st.condition === 'urgent') {
+                const min = st.allDownSince ? Math.round((nowMs - st.allDownSince) / 60_000) : 0;
+                sentences.push(`ALL mesh ropes to ${p.nickname} are down (~${min} min) while its heartbeat still advances — alive but unreachable.`);
+            }
+            else if (st.condition === 'peer-offline') {
+                const min = st.allDownSince ? Math.round((nowMs - st.allDownSince) / 60_000) : 0;
+                sentences.push(`${p.nickname} is offline (~${min} min) — expected (its heartbeat stopped).`);
+            }
+            else if (st.condition === 'degraded') {
+                const rows = this.safeSnapshot().filter((r) => r.peer === p.machineId && r.dead);
+                const kinds = rows.map((r) => r.kind).join(', ') || 'a rope';
+                sentences.push(`The ${kinds} rope to ${p.nickname} is down; another rope is carrying traffic.`);
+            }
+        }
+        if (this.keyExpiryWarn() && this.keyExpirySoonest) {
+            const who = this.keyExpirySoonest.role === 'self' ? 'this machine' : 'a peer machine';
+            sentences.push(`A Tailscale key (${who}) expires in ${Math.max(0, Math.floor(this.keyExpirySoonest.inDays))} days — re-authenticate before it drops the rope.`);
+        }
+        if (sentences.length === 0)
+            return null;
+        return sentences.slice(0, 3).join(' ');
+    }
+    /** Record a digest emission (the digest job calls the route with ?digest=1). */
+    recordDigestEmission() {
+        this.metric('digest-emission');
+    }
+    // ── Safe dep reads (fail toward silence). ──
+    safeSnapshot() {
+        try {
+            return this.d.snapshot();
+        }
+        catch {
+            // @silent-fallback-ok: a throwing snapshot source yields an empty view this
+            // pass (UNKNOWN, fails toward NOT-urgent) — the next pass re-reads.
+            return [];
+        }
+    }
+    safePeers() {
+        try {
+            return this.d.listPeers().filter((p) => p.machineId !== this.d.selfMachineId);
+        }
+        catch {
+            // @silent-fallback-ok: same posture as safeSnapshot.
+            return [];
+        }
+    }
+    safeHeartbeat(machineId) {
+        try {
+            return this.d.readHeartbeatAtMs(machineId);
+        }
+        catch {
+            // @silent-fallback-ok: an unreadable heartbeat is "no evidence" — the
+            // classifier then reads peer-offline (fails toward NOT-urgent).
+            return null;
+        }
+    }
+    safeSplitBrainOpen(machineId) {
+        try {
+            return this.d.splitBrainItemOpen?.(machineId) ?? false;
+        }
+        catch {
+            // @silent-fallback-ok: an unreadable episode registry must not block the
+            // urgent item (the failure direction here is a possible duplicate ask,
+            // never a silent partition).
+            return false;
+        }
+    }
+    recordTransition(prev, next) {
+        if (prev === next)
+            return;
+        const evt = `transition-${next}`;
+        if (next !== 'unknown')
+            this.metric(evt);
+        this.scheduleWrite();
+    }
+    // ── Durable state (R-r2-4: transition-only writes + short debounce). ──
+    scheduleWrite() {
+        this.writePending = true;
+        if (this.writeTimer)
+            return;
+        if (this.cfg.writeDebounceMs <= 0) {
+            this.writeStateNow();
+            return;
+        }
+        this.writeTimer = setTimeout(() => {
+            this.writeTimer = null;
+            if (this.writePending)
+                this.writeStateNow();
+        }, this.cfg.writeDebounceMs);
+        if (typeof this.writeTimer.unref === 'function')
+            this.writeTimer.unref();
+    }
+    writeStateNow() {
+        this.writePending = false;
+        try {
+            const out = {};
+            for (const [id, st] of this.peers) {
+                out[id] = {
+                    condition: st.condition,
+                    allDownSince: st.allDownSince,
+                    consecutiveObservations: st.consecutiveObservations,
+                    episodeKey: st.episodeKey,
+                    urgentRaisedAt: st.urgentRaisedAt,
+                    detectedNotNotified: st.detectedNotNotified,
+                };
+            }
+            fs.mkdirSync(path.dirname(this.d.stateFilePath), { recursive: true });
+            const tmp = `${this.d.stateFilePath}.tmp`;
+            fs.writeFileSync(tmp, JSON.stringify({ version: 1, peers: out }, null, 2));
+            fs.renameSync(tmp, this.d.stateFilePath);
+        }
+        catch (err) {
+            // @silent-fallback-ok: state persistence is debounce memory, never
+            // authority — a failed write means a restart re-debounces (the declared
+            // safe direction); the alert path is unaffected.
+            this.log(`state write failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    loadState() {
+        try {
+            if (!fs.existsSync(this.d.stateFilePath))
+                return;
+            const raw = JSON.parse(fs.readFileSync(this.d.stateFilePath, 'utf-8'));
+            for (const [id, p] of Object.entries(raw.peers ?? {})) {
+                this.peers.set(id, {
+                    ...freshPeerState(),
+                    condition: isCondition(p.condition) ? p.condition : 'unknown',
+                    allDownSince: typeof p.allDownSince === 'number' ? p.allDownSince : null,
+                    // Intra-episode counters lost to a restart are ACCEPTED (a restart
+                    // re-debounces; it never fabricates an episode) — R-r2-4.
+                    consecutiveObservations: 0,
+                    episodeKey: typeof p.episodeKey === 'string' ? p.episodeKey : null,
+                    urgentRaisedAt: typeof p.urgentRaisedAt === 'number' ? p.urgentRaisedAt : null,
+                    detectedNotNotified: p.detectedNotNotified === true,
+                });
+            }
+        }
+        catch {
+            // @silent-fallback-ok: a corrupt state file is a missing one (the safe
+            // direction: re-debounce from scratch) — never a boot failure.
+        }
+    }
+}
+function freshPeerState() {
+    return {
+        condition: 'unknown',
+        allDownSince: null,
+        consecutiveObservations: 0,
+        episodeKey: null,
+        urgentRaisedAt: null,
+        detectedNotNotified: false,
+        healthySince: null,
+        postOnsetBeatObservedAt: null,
+    };
+}
+function isCondition(v) {
+    return v === 'ok' || v === 'degraded' || v === 'peer-offline' || v === 'urgent' || v === 'unknown';
+}
+//# sourceMappingURL=RopeHealthMonitor.js.map