mergen-server 1.4.0

package/dist/sensor/redis-store.js

@@ -0,0 +1,191 @@
+import net from "net";
+import logger from "./logger.js";
+const REDIS_KEY = "mergen:events";
+const MAX_STORED = 5e4;
+function parseRedisUrl(url) {
+  const u = new URL(url);
+  return {
+    host: u.hostname || "127.0.0.1",
+    port: parseInt(u.port || "6379", 10),
+    password: u.password || void 0,
+    db: parseInt(u.pathname.slice(1) || "0", 10) || 0
+  };
+}
+function buildRespCommand(args) {
+  const lines = [`*${args.length}\r
+`];
+  for (const arg of args) {
+    const s = String(arg);
+    lines.push(`$${Buffer.byteLength(s, "utf8")}\r
+${s}\r
+`);
+  }
+  return Buffer.from(lines.join(""), "utf8");
+}
+async function createRespClient(url) {
+  const { host, port, password, db } = parseRedisUrl(url);
+  const socket = new net.Socket();
+  let buf = "";
+  const pending = [];
+  await new Promise((resolve, reject) => {
+    socket.once("error", reject);
+    socket.connect(port, host, () => resolve());
+  });
+  socket.on("data", (chunk) => {
+    buf += chunk.toString("utf8");
+    while (pending.length > 0) {
+      const nl = buf.indexOf("\r\n");
+      if (nl === -1) break;
+      const line = buf.slice(0, nl);
+      buf = buf.slice(nl + 2);
+      const resolve = pending.shift();
+      if (line[0] === "+" || line[0] === ":" || line[0] === "-") {
+        resolve([line.slice(1)]);
+      } else if (line[0] === "$") {
+        const len = parseInt(line.slice(1), 10);
+        if (len === -1) {
+          resolve([""]);
+          continue;
+        }
+        const end = len + 2;
+        if (buf.length < end) {
+          buf = line + "\r\n" + buf;
+          pending.unshift(resolve);
+          break;
+        }
+        resolve([buf.slice(0, len)]);
+        buf = buf.slice(end);
+      } else if (line[0] === "*") {
+        const count = parseInt(line.slice(1), 10);
+        if (count <= 0) {
+          resolve([]);
+          continue;
+        }
+        const items = [];
+        let ok = true;
+        for (let i = 0; i < count; i++) {
+          const lnl = buf.indexOf("\r\n");
+          if (lnl === -1) {
+            ok = false;
+            break;
+          }
+          const lline = buf.slice(0, lnl);
+          buf = buf.slice(lnl + 2);
+          if (lline[0] === "$") {
+            const llen = parseInt(lline.slice(1), 10);
+            if (llen === -1) {
+              items.push("");
+              continue;
+            }
+            const lend = llen + 2;
+            if (buf.length < lend) {
+              ok = false;
+              break;
+            }
+            items.push(buf.slice(0, llen));
+            buf = buf.slice(lend);
+          }
+        }
+        if (!ok) {
+          buf = line + "\r\n" + buf;
+          pending.unshift(resolve);
+          break;
+        }
+        resolve(items);
+      }
+    }
+  });
+  function send(args) {
+    return new Promise((resolve) => {
+      pending.push(resolve);
+      socket.write(buildRespCommand(args));
+    });
+  }
+  if (password) await send(["AUTH", password]);
+  if (db !== 0) await send(["SELECT", db]);
+  return {
+    async zadd(key, score, member) {
+      await send(["ZADD", key, score, member]);
+    },
+    async zrangebyscore(key, min, max, limit) {
+      if (limit !== void 0) return send(["ZRANGEBYSCORE", key, min, max, "LIMIT", 0, limit]);
+      return send(["ZRANGEBYSCORE", key, min, max]);
+    },
+    async zremrangebyrank(key, start, stop) {
+      await send(["ZREMRANGEBYRANK", key, start, stop]);
+    },
+    async del(key) {
+      await send(["DEL", key]);
+    },
+    quit() {
+      socket.destroy();
+    }
+  };
+}
+let _client = null;
+async function wrapWithRedisPersistence(store) {
+  const redisUrl = process.env.MERGEN_REDIS_URL;
+  if (!redisUrl) return store;
+  try {
+    _client = await createRespClient(redisUrl);
+    logger.info({ url: redisUrl.replace(/:\/\/.*@/, "://***@") }, "redis-store: connected");
+  } catch (err) {
+    logger.warn({ err }, "redis-store: could not connect \u2014 falling back to in-memory only");
+    return store;
+  }
+  try {
+    const raw = await _client.zrangebyscore(REDIS_KEY, "-inf", "+inf", MAX_STORED);
+    if (raw.length > 0) {
+      const events = [];
+      for (const item of raw) {
+        try {
+          events.push(JSON.parse(item));
+        } catch {
+        }
+      }
+      if (events.length > 0) {
+        store.rehydrate(events);
+        logger.info({ count: events.length }, "redis-store: rehydrated from Redis");
+      }
+    }
+  } catch (err) {
+    logger.warn({ err }, "redis-store: rehydration failed \u2014 continuing without restore");
+  }
+  const client = _client;
+  return new Proxy(store, {
+    get(target, prop) {
+      if (prop === "push") {
+        return (event, tenantId) => {
+          target.push(event, tenantId);
+          const score = typeof event.timestamp === "number" ? event.timestamp : Date.now();
+          void client.zadd(REDIS_KEY, score, JSON.stringify(event)).then(
+            () => client.zremrangebyrank(REDIS_KEY, 0, -(MAX_STORED + 1))
+          ).catch((err) => {
+            logger.debug({ err }, "redis-store: write failed");
+          });
+        };
+      }
+      if (prop === "clear") {
+        return (tenantId) => {
+          target.clear(tenantId);
+          if (!tenantId) {
+            void client.del(REDIS_KEY).catch((err) => {
+              logger.debug({ err }, "redis-store: clear failed");
+            });
+          }
+        };
+      }
+      return target[prop];
+    }
+  });
+}
+function stopRedisStore() {
+  if (_client) {
+    _client.quit();
+    _client = null;
+  }
+}
+export {
+  stopRedisStore,
+  wrapWithRedisPersistence
+};

package/dist/sensor/route-reachability.js

@@ -0,0 +1,64 @@
+const STALE_AFTER_MS = 24 * 60 * 60 * 1e3;
+class RouteReachabilityRegistry {
+  _routes = /* @__PURE__ */ new Map();
+  /** Normalise a raw path by replacing UUIDs, numeric IDs, and hash-like segments. */
+  normalise(rawPath) {
+    try {
+      const parsed = new URL(rawPath.startsWith("http") ? rawPath : `http://x${rawPath}`);
+      rawPath = parsed.pathname;
+    } catch {
+    }
+    return rawPath.replace(/\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi, "/:uuid").replace(/\/\d{4,}/g, "/:id").replace(/\/[a-f0-9]{24,}/gi, "/:hash").replace(/\/\d+/g, "/:id");
+  }
+  /** Record an observed route from a SERVER span. */
+  record(rawPath, isError) {
+    const canonical = this.normalise(rawPath);
+    const existing = this._routes.get(canonical);
+    if (existing) {
+      existing.callCount++;
+      existing.lastSeenAt = Date.now();
+      if (isError) existing.errorCount++;
+    } else {
+      this._routes.set(canonical, {
+        callCount: 1,
+        lastSeenAt: Date.now(),
+        errorCount: isError ? 1 : 0
+      });
+    }
+  }
+  /**
+   * Returns true if the given path (or a prefix of it) has been observed in
+   * live OTLP traces within the staleness window.
+   *
+   * Matching is intentionally loose: a hypothesis mentioning "/api/auth" will
+   * match any recorded route that starts with "/api/auth".
+   */
+  isReachable(path) {
+    if (this._routes.size === 0) return true;
+    const cutoff = Date.now() - STALE_AFTER_MS;
+    const canonical = this.normalise(path);
+    for (const [route, entry] of this._routes) {
+      if (entry.lastSeenAt < cutoff) continue;
+      if (route.startsWith(canonical) || canonical.startsWith(route)) return true;
+    }
+    return false;
+  }
+  /** All non-stale routes with their stats, for the /route-reachability endpoint. */
+  toJSON() {
+    const cutoff = Date.now() - STALE_AFTER_MS;
+    const routes = [];
+    for (const [route, entry] of this._routes) {
+      if (entry.lastSeenAt < cutoff) continue;
+      routes.push({ route, ...entry });
+    }
+    routes.sort((a, b) => b.callCount - a.callCount);
+    return { totalRoutes: routes.length, routes };
+  }
+  get size() {
+    return this._routes.size;
+  }
+}
+const routeReachability = new RouteReachabilityRegistry();
+export {
+  routeReachability
+};

package/dist/sensor/security-utils.js

@@ -0,0 +1,18 @@
+import crypto from "crypto";
+const COMPARISON_WIDTH = 128;
+function timingSafeSecretEqual(presented, expected) {
+  if (typeof presented !== "string") return false;
+  const p = Buffer.allocUnsafe(COMPARISON_WIDTH).fill(0);
+  const e = Buffer.allocUnsafe(COMPARISON_WIDTH).fill(0);
+  Buffer.from(presented, "utf8").copy(p, 0, 0, Math.min(presented.length, COMPARISON_WIDTH));
+  Buffer.from(expected, "utf8").copy(e, 0, 0, Math.min(expected.length, COMPARISON_WIDTH));
+  return crypto.timingSafeEqual(p, e) && presented.length === expected.length;
+}
+function timingSafeSecretEqualAny(presented, expected) {
+  const secrets = expected.split(",").map((s) => s.trim()).filter(Boolean);
+  return secrets.some((s) => timingSafeSecretEqual(presented, s));
+}
+export {
+  timingSafeSecretEqual,
+  timingSafeSecretEqualAny
+};

package/dist/sensor/service-graph.js

@@ -0,0 +1,170 @@
+import fs from "fs";
+import { TOPOLOGY_FILE, DATA_DIR, zeroRetentionMode } from "./paths.js";
+import logger from "./logger.js";
+const MAX_EDGE_AGE_MS = (() => {
+  const days = parseInt(process.env.MERGEN_TOPOLOGY_MAX_EDGE_AGE_DAYS ?? "7", 10);
+  return (Number.isFinite(days) && days > 0 ? Math.min(days, 365) : 7) * 24 * 60 * 60 * 1e3;
+})();
+class ServiceGraph {
+  _nodes = /* @__PURE__ */ new Map();
+  _lastUpdated = 0;
+  _saveTimer = null;
+  _node(service) {
+    if (!this._nodes.has(service)) {
+      this._nodes.set(service, { calls: /* @__PURE__ */ new Map(), calledBy: /* @__PURE__ */ new Set() });
+    }
+    return this._nodes.get(service);
+  }
+  // ── Persistence ─────────────────────────────────────────────────────────────
+  /** Restore graph from TOPOLOGY_FILE. Called once at server startup. */
+  loadPersisted() {
+    if (zeroRetentionMode() || !fs.existsSync(TOPOLOGY_FILE)) return;
+    try {
+      const raw = JSON.parse(fs.readFileSync(TOPOLOGY_FILE, "utf8"));
+      if (raw?.version !== 1 || !Array.isArray(raw.edges)) return;
+      const cutoff = Date.now() - MAX_EDGE_AGE_MS;
+      let loaded = 0;
+      for (const e of raw.edges) {
+        if (!e.source || !e.target || e.lastSeenAt < cutoff) continue;
+        this._restoreEdge(e.source, e.target, e.callCount, e.errorCount, e.lastSeenAt);
+        loaded++;
+      }
+      this._lastUpdated = raw.savedAt;
+      logger.debug({ loaded, file: TOPOLOGY_FILE }, "service-graph: topology restored");
+    } catch (err) {
+      logger.warn({ err }, "service-graph: failed to load persisted topology");
+    }
+  }
+  _restoreEdge(source, target, callCount, errorCount, lastSeenAt) {
+    const node = this._node(source);
+    node.calls.set(target, { callCount, errorCount, lastSeenAt });
+    this._node(target).calledBy.add(source);
+  }
+  _scheduleSave() {
+    if (zeroRetentionMode()) return;
+    if (this._saveTimer) clearTimeout(this._saveTimer);
+    this._saveTimer = setTimeout(() => {
+      this._saveTimer = null;
+      this._save();
+    }, 3e4);
+  }
+  _save() {
+    try {
+      fs.mkdirSync(DATA_DIR, { recursive: true });
+      const edges = [];
+      for (const [source, node] of this._nodes) {
+        for (const [target, stats] of node.calls) {
+          edges.push({ source, target, ...stats });
+        }
+      }
+      const payload = { version: 1, savedAt: Date.now(), edges };
+      const tmp = `${TOPOLOGY_FILE}.tmp.${process.pid}`;
+      fs.writeFileSync(tmp, JSON.stringify(payload), "utf8");
+      fs.renameSync(tmp, TOPOLOGY_FILE);
+    } catch (err) {
+      logger.warn({ err }, "service-graph: persist failed");
+    }
+  }
+  /** Flush any pending save immediately — call on graceful shutdown. */
+  flushSync() {
+    if (this._saveTimer) {
+      clearTimeout(this._saveTimer);
+      this._saveTimer = null;
+    }
+    this._save();
+  }
+  /** Record an observed call from `caller` to `callee`. */
+  recordCall(caller, callee, isError) {
+    if (!caller || !callee || caller === callee) return;
+    const node = this._node(caller);
+    const callerCallee = node.calls.get(callee);
+    if (callerCallee) {
+      callerCallee.callCount++;
+      if (isError) callerCallee.errorCount++;
+      callerCallee.lastSeenAt = Date.now();
+    } else {
+      node.calls.set(callee, {
+        callCount: 1,
+        errorCount: isError ? 1 : 0,
+        lastSeenAt: Date.now()
+      });
+    }
+    this._node(callee).calledBy.add(caller);
+    this._lastUpdated = Date.now();
+    this._scheduleSave();
+  }
+  /** Returns all services that directly depend on (call) `service`. */
+  getCallers(service) {
+    return [...this._nodes.get(service)?.calledBy ?? []];
+  }
+  /** Returns all services that `service` calls. */
+  getCallees(service) {
+    return [...this._nodes.get(service)?.calls.keys() ?? []];
+  }
+  /** Returns all services that transitively depend on `service` (BFS, depth ≤ 3). */
+  getUpstreamImpact(service, maxDepth = 3) {
+    const visited = /* @__PURE__ */ new Set();
+    const queue = [{ s: service, depth: 0 }];
+    while (queue.length > 0) {
+      const { s, depth } = queue.shift();
+      if (depth >= maxDepth) continue;
+      for (const caller of this.getCallers(s)) {
+        if (!visited.has(caller)) {
+          visited.add(caller);
+          queue.push({ s: caller, depth: depth + 1 });
+        }
+      }
+    }
+    return [...visited];
+  }
+  /**
+   * Risk multiplier for hypothesis execution:
+   * if a failing service has many upstream dependents, fixes are higher risk.
+   *   0–2 callers  → 'low'
+   *   3–5 callers  → 'medium'
+   *   6+ callers   → 'high'
+   */
+  getBlastRisk(service) {
+    const impacted = this.getUpstreamImpact(service).length;
+    if (impacted >= 6) return "high";
+    if (impacted >= 3) return "medium";
+    return "low";
+  }
+  /** Serialise for the /service-graph endpoint. */
+  toJSON() {
+    const edges = [];
+    for (const [source, node] of this._nodes) {
+      for (const [target, stats] of node.calls) {
+        edges.push({ source, target, ...stats });
+      }
+    }
+    return {
+      services: [...this._nodes.keys()],
+      edges,
+      lastUpdated: this._lastUpdated
+    };
+  }
+  get size() {
+    return this._nodes.size;
+  }
+}
+const serviceGraph = new ServiceGraph();
+function extractCalleeService(attrs, spanName) {
+  if (attrs["peer.service"]) return attrs["peer.service"];
+  if (attrs["net.peer.name"]) return attrs["net.peer.name"].split(":")[0];
+  const url = attrs["http.url"] ?? attrs["url.full"] ?? attrs["http.target"] ?? "";
+  if (url) {
+    try {
+      const host = new URL(url.startsWith("http") ? url : `http://${url}`).hostname;
+      return host.replace(/\.(svc\.cluster\.local|internal|local)$/, "").split(".")[0];
+    } catch {
+    }
+  }
+  if (attrs["db.system"]) return attrs["db.system"];
+  if (spanName && !/^(GET|POST|PUT|DELETE|PATCH)\s/.test(spanName)) return spanName;
+  return "";
+}
+export {
+  extractCalleeService,
+  serviceGraph
+};

package/dist/sensor/service-topology.js

@@ -0,0 +1,227 @@
+import fs from "fs";
+import { DATA_DIR, TOPOLOGY_FILE } from "./paths.js";
+import logger from "./logger.js";
+const MAX_DURATION_SAMPLES = 100;
+const MAX_SAMPLE_TRACE_IDS = 5;
+const DB_PATTERN = /postgres|mysql|mongo|redis|elastic|cassandra|dynamo|sqlite|cockroach|clickhouse|snowflake|bigquery|db$/i;
+const QUEUE_PATTERN = /kafka|rabbit|sqs|pubsub|nats|celery|queue|broker|worker$/i;
+const CACHE_PATTERN = /redis|memcache|cache$/i;
+const INFRA_PATTERN = /nginx|haproxy|envoy|istio|k8s|kubernetes|docker|gateway|proxy|lb$/i;
+function inferServiceType(name) {
+  if (name === "browser") return "browser";
+  if (CACHE_PATTERN.test(name)) return "cache";
+  if (DB_PATTERN.test(name)) return "database";
+  if (QUEUE_PATTERN.test(name)) return "queue";
+  if (INFRA_PATTERN.test(name)) return "infra";
+  return "api";
+}
+function p99(samples) {
+  if (samples.length === 0) return 0;
+  const sorted = [...samples].sort((a, b) => a - b);
+  const idx = Math.max(0, Math.floor(sorted.length * 0.99) - 1);
+  return sorted[idx] ?? 0;
+}
+function avg(samples) {
+  if (samples.length === 0) return 0;
+  return Math.round(samples.reduce((s, v) => s + v, 0) / samples.length);
+}
+class ServiceTopologyModel {
+  nodes = /* @__PURE__ */ new Map();
+  edges = /* @__PURE__ */ new Map();
+  constructor() {
+    this.load();
+  }
+  // ── Ingestion ─────────────────────────────────────────────────────────────
+  updateFromSpan(span) {
+    this.upsertNode(span.service, {
+      sdk: span.sdk,
+      duration: span.durationMs,
+      isError: span.statusCode >= 500 || !!span.error,
+      ts: span.timestamp
+    });
+  }
+  /** Called when a browser NetworkEvent's traceId matches a BackendSpanEvent. */
+  updateFromTraceJoin(browserUrl, targetService, durationMs, isError, traceId, ts) {
+    this.upsertNode("browser", { duration: durationMs, isError, ts });
+    this.upsertEdge("browser", targetService, { durationMs, isError, traceId, ts });
+  }
+  /**
+   * Resolve service-to-service edges from a set of spans sharing a traceId.
+   * Called after grouping all BackendSpanEvents by traceId in the ring buffer.
+   */
+  updateFromTraceGroup(spans) {
+    if (spans.length < 2) return;
+    const spanToService = /* @__PURE__ */ new Map();
+    for (const s of spans) {
+      if (s.spanId) spanToService.set(s.spanId, s.service);
+    }
+    for (const span of spans) {
+      if (!span.parentSpanId) continue;
+      const caller = spanToService.get(span.parentSpanId);
+      if (!caller || caller === span.service) continue;
+      this.upsertEdge(caller, span.service, {
+        durationMs: span.durationMs,
+        isError: span.statusCode >= 500 || !!span.error,
+        traceId: span.traceId,
+        ts: span.timestamp
+      });
+    }
+  }
+  // ── Read ──────────────────────────────────────────────────────────────────
+  snapshot() {
+    const nodes = Array.from(this.nodes.values()).map((n) => ({
+      id: n.id,
+      type: n.type,
+      name: n.name,
+      sdk: n.sdk,
+      spanCount: n.spanCount,
+      errorCount: n.errorCount,
+      avgDurationMs: avg(n.recentDurationsMs),
+      p99DurationMs: p99(n.recentDurationsMs),
+      firstSeenAt: n.firstSeenAt,
+      lastSeenAt: n.lastSeenAt
+    }));
+    const edges = Array.from(this.edges.values()).map((e) => ({
+      from: e.from,
+      to: e.to,
+      callCount: e.callCount,
+      errorCount: e.errorCount,
+      avgDurationMs: e.callCount > 0 ? Math.round(e.totalDurationMs / e.callCount) : 0,
+      lastSeenAt: e.lastSeenAt,
+      sampleTraceIds: e.sampleTraceIds
+    }));
+    return {
+      capturedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      nodes,
+      edges,
+      summary: this.buildSummary(nodes, edges)
+    };
+  }
+  size() {
+    return { nodes: this.nodes.size, edges: this.edges.size };
+  }
+  // ── Private helpers ───────────────────────────────────────────────────────
+  upsertNode(id, opts) {
+    const existing = this.nodes.get(id);
+    if (existing) {
+      existing.spanCount++;
+      if (opts.isError) existing.errorCount++;
+      if (opts.sdk && !existing.sdk) existing.sdk = opts.sdk;
+      if (opts.duration !== void 0) {
+        existing.recentDurationsMs.push(opts.duration);
+        if (existing.recentDurationsMs.length > MAX_DURATION_SAMPLES) {
+          existing.recentDurationsMs.shift();
+        }
+      }
+      existing.lastSeenAt = Math.max(existing.lastSeenAt, opts.ts);
+    } else {
+      this.nodes.set(id, {
+        id,
+        type: inferServiceType(id),
+        name: id,
+        sdk: opts.sdk,
+        spanCount: 1,
+        errorCount: opts.isError ? 1 : 0,
+        recentDurationsMs: opts.duration !== void 0 ? [opts.duration] : [],
+        firstSeenAt: opts.ts,
+        lastSeenAt: opts.ts
+      });
+    }
+    this.schedulePersist();
+  }
+  upsertEdge(from, to, opts) {
+    const key = `${from}\u2192${to}`;
+    const existing = this.edges.get(key);
+    if (existing) {
+      existing.callCount++;
+      if (opts.isError) existing.errorCount++;
+      existing.totalDurationMs += opts.durationMs;
+      existing.lastSeenAt = Math.max(existing.lastSeenAt, opts.ts);
+      if (!existing.sampleTraceIds.includes(opts.traceId)) {
+        existing.sampleTraceIds.push(opts.traceId);
+        if (existing.sampleTraceIds.length > MAX_SAMPLE_TRACE_IDS) {
+          existing.sampleTraceIds.shift();
+        }
+      }
+    } else {
+      this.edges.set(key, {
+        from,
+        to,
+        callCount: 1,
+        errorCount: opts.isError ? 1 : 0,
+        totalDurationMs: opts.durationMs,
+        lastSeenAt: opts.ts,
+        sampleTraceIds: [opts.traceId]
+      });
+      if (!this.nodes.has(from)) {
+        this.upsertNode(from, { ts: opts.ts });
+      }
+      if (!this.nodes.has(to)) {
+        this.upsertNode(to, { ts: opts.ts });
+      }
+    }
+  }
+  buildSummary(nodes, edges) {
+    const errorHotspot = nodes.length > 0 ? nodes.sort((a, b) => b.errorCount - a.errorCount)[0]?.id ?? null : null;
+    const slowestEdge = edges.length > 0 ? edges.sort((a, b) => b.avgDurationMs - a.avgDurationMs)[0] ?? null : null;
+    const criticalPath = [];
+    const browserNode = nodes.find((n) => n.id === "browser");
+    if (browserNode) {
+      let current = "browser";
+      const visited = /* @__PURE__ */ new Set();
+      while (!visited.has(current)) {
+        criticalPath.push(current);
+        visited.add(current);
+        const outgoing = edges.filter((e) => e.from === current).sort((a, b) => b.callCount - a.callCount);
+        if (outgoing.length === 0) break;
+        current = outgoing[0].to;
+      }
+    }
+    return {
+      totalServices: nodes.length,
+      totalEdges: edges.length,
+      errorHotspot: errorHotspot && nodes.find((n) => n.id === errorHotspot)?.errorCount ? errorHotspot : null,
+      slowestEdge: slowestEdge ? { from: slowestEdge.from, to: slowestEdge.to, avgDurationMs: slowestEdge.avgDurationMs } : null,
+      criticalPath
+    };
+  }
+  // ── Persistence ───────────────────────────────────────────────────────────
+  persistTimer = null;
+  schedulePersist() {
+    if (this.persistTimer) return;
+    this.persistTimer = setTimeout(() => {
+      this.persistTimer = null;
+      this.persist();
+    }, 2e3);
+  }
+  persist() {
+    try {
+      fs.mkdirSync(DATA_DIR, { recursive: true });
+      const payload = {
+        nodes: Object.fromEntries(this.nodes),
+        edges: Object.fromEntries(this.edges),
+        updatedAt: Date.now()
+      };
+      const tmp = TOPOLOGY_FILE + ".tmp";
+      fs.writeFileSync(tmp, JSON.stringify(payload), "utf8");
+      fs.renameSync(tmp, TOPOLOGY_FILE);
+    } catch (err) {
+      logger.warn({ err }, "service-topology: persist failed");
+    }
+  }
+  load() {
+    try {
+      if (!fs.existsSync(TOPOLOGY_FILE)) return;
+      const raw = fs.readFileSync(TOPOLOGY_FILE, "utf8");
+      const data = JSON.parse(raw);
+      for (const [k, v] of Object.entries(data.nodes ?? {})) this.nodes.set(k, v);
+      for (const [k, v] of Object.entries(data.edges ?? {})) this.edges.set(k, v);
+    } catch (err) {
+      logger.warn({ err }, "service-topology: failed to load persisted data \u2014 starting fresh");
+    }
+  }
+}
+const serviceTopology = new ServiceTopologyModel();
+export {
+  serviceTopology
+};