@fibscope/agent 0.1.0

package/lib/observe/collector.mjs

@@ -0,0 +1,1039 @@
+#!/usr/bin/env node
+
+import { EventEmitter } from "node:events";
+import { pathToFileURL } from "node:url";
+import path from "node:path";
+
+export class FiberObservabilityError extends Error {
+  constructor(message, code = "FIBER_OBSERVABILITY_ERROR", details = undefined) {
+    super(message);
+    this.name = "FiberObservabilityError";
+    this.code = code;
+    this.details = details;
+  }
+}
+
+export class TelemetryCollector extends EventEmitter {
+  constructor(options = {}) {
+    super();
+    this.options = {
+      intervalMs: options.intervalMs ?? 10000,
+      timeoutMs: options.timeoutMs ?? 8000,
+      maxSnapshots: options.maxSnapshots ?? 100,
+      maxEvents: options.maxEvents ?? options.maxLog ?? 1000,
+      maxReliabilityEntries: options.maxReliabilityEntries ?? options.maxReliabilityLog ?? options.maxMetricsLog ?? options.maxLog ?? 1000,
+      maxAlerts: options.maxAlerts ?? options.maxAlertLog ?? options.maxLog ?? 1000,
+      ...options,
+    };
+    this.snapshots = [];
+    this.events = [];
+    this.reliabilityEntries = [];
+    this.alerts = [];
+    this.timer = undefined;
+    this.running = false;
+  }
+
+  async collect() {
+    const timestamp = Date.now();
+    try {
+      const state = await collectFiberState(this.options);
+      const payments = await collectPaymentSummaries(this.options, state);
+      const snapshot = normalizeTelemetrySnapshot({ timestamp, ...state, payments });
+      this.record(snapshot);
+      this.emit("snapshot", snapshot);
+      return snapshot;
+    } catch (error) {
+      const snapshot = offlineSnapshot(timestamp, error);
+      this.record(snapshot);
+      this.emit("snapshot", snapshot);
+      this.emit("collector-error", error, snapshot);
+      return snapshot;
+    }
+  }
+
+  start() {
+    if (this.running) return this;
+    this.running = true;
+    this.collect();
+    this.timer = setInterval(() => {
+      this.collect();
+    }, this.options.intervalMs);
+    this.emit("started", { intervalMs: this.options.intervalMs });
+    return this;
+  }
+
+  stop() {
+    if (this.timer) clearInterval(this.timer);
+    this.timer = undefined;
+    this.running = false;
+    this.emit("stopped");
+    return this;
+  }
+
+  record(snapshot) {
+    const previous = this.latest();
+    this.snapshots.push(snapshot);
+    while (this.snapshots.length > this.options.maxSnapshots) {
+      this.snapshots.shift();
+    }
+    const events = deriveFiberEvents(previous, snapshot);
+    for (const event of events) {
+      this.events.push(event);
+      this.emit("event", event);
+    }
+    while (this.events.length > this.options.maxEvents) {
+      this.events.shift();
+    }
+    const entries = deriveReliabilityEntries(previous, snapshot, events);
+    for (const entry of entries) {
+      this.reliabilityEntries.push(entry);
+      this.emit("reliability-entry", entry);
+    }
+    while (this.reliabilityEntries.length > this.options.maxReliabilityEntries) {
+      this.reliabilityEntries.shift();
+    }
+    const alerts = generateAlerts(snapshot, events, this.health(), this.diagnoses(), this.reliability());
+    for (const alert of alerts) {
+      if (this.alerts.some((existing) => alertKey(existing) === alertKey(alert))) continue;
+      this.alerts.push(alert);
+      this.emit("alert", alert);
+    }
+    while (this.alerts.length > this.options.maxAlerts) {
+      this.alerts.shift();
+    }
+    return events;
+  }
+
+  latest() {
+    return this.snapshots.at(-1);
+  }
+
+  history() {
+    return [...this.snapshots];
+  }
+
+  eventLog() {
+    return [...this.events];
+  }
+
+  health() {
+    return analyzeHealth(this.latest(), this.eventLog());
+  }
+
+  diagnoses() {
+    return analyzeRootCauses(this.latest(), this.eventLog(), this.reliabilityLog());
+  }
+
+  reliabilityLog() {
+    return [...this.reliabilityEntries];
+  }
+
+  reliability() {
+    return analyzeReliability(this.reliabilityLog(), this.eventLog());
+  }
+
+  alertLog() {
+    return [...this.alerts];
+  }
+
+  replay(timestamp) {
+    return replayHistory(timestamp, this.history(), this.eventLog(), this.reliabilityLog());
+  }
+}
+
+export function createTelemetryCollector(options = {}) {
+  return new TelemetryCollector(options);
+}
+
+export async function collectTelemetrySnapshot(options = {}) {
+  const collector = createTelemetryCollector({ ...options, maxSnapshots: 1 });
+  return collector.collect();
+}
+
+export function deriveFiberEvents(previous, current) {
+  if (!current) return [];
+  const events = [];
+  if (!previous) {
+    events.push(fiberEvent(current.timestamp, "node", current.node.online ? "NODE_ONLINE" : "NODE_OFFLINE", current.node));
+    for (const peer of current.peers) {
+      events.push(fiberEvent(current.timestamp, "peer", peer.connected ? "PEER_CONNECTED" : "PEER_DISCONNECTED", peer));
+    }
+    for (const channel of current.channels) {
+      events.push(fiberEvent(current.timestamp, "channel", channel.status === "open" ? "CHANNEL_OPENED" : "CHANNEL_SEEN", channel));
+    }
+    for (const payment of current.payments) {
+      events.push(fiberEvent(payment.timestamp ?? current.timestamp, "payment", paymentEventType(payment), payment));
+    }
+    return events;
+  }
+
+  if (previous.node.online !== current.node.online) {
+    events.push(fiberEvent(current.timestamp, "node", current.node.online ? "NODE_ONLINE" : "NODE_OFFLINE", current.node));
+  }
+  if (previous.node.peerCount !== current.node.peerCount) {
+    events.push(fiberEvent(current.timestamp, "node", "PEER_COUNT_CHANGED", {
+      before: previous.node.peerCount,
+      after: current.node.peerCount,
+    }));
+  }
+  if (previous.node.channelCount !== current.node.channelCount) {
+    events.push(fiberEvent(current.timestamp, "node", "CHANNEL_COUNT_CHANGED", {
+      before: previous.node.channelCount,
+      after: current.node.channelCount,
+    }));
+  }
+
+  diffById(previous.peers, current.peers, "peerId", {
+    added: (peer) => events.push(fiberEvent(current.timestamp, "peer", peer.connected ? "PEER_CONNECTED" : "PEER_SEEN", peer)),
+    removed: (peer) => events.push(fiberEvent(current.timestamp, "peer", "PEER_REMOVED", peer)),
+    changed: (before, after) => {
+      if (before.connected !== after.connected) {
+        events.push(fiberEvent(current.timestamp, "peer", after.connected ? "PEER_CONNECTED" : "PEER_DISCONNECTED", { before, after }));
+      }
+    },
+  });
+
+  diffById(previous.channels, current.channels, "channelId", {
+    added: (channel) => events.push(fiberEvent(current.timestamp, "channel", channel.status === "open" ? "CHANNEL_OPENED" : "CHANNEL_SEEN", channel)),
+    removed: (channel) => events.push(fiberEvent(current.timestamp, "channel", "CHANNEL_REMOVED", channel)),
+    changed: (before, after) => {
+      if (before.status !== after.status) {
+        events.push(fiberEvent(current.timestamp, "channel", channelStatusEvent(after.status), { before, after }));
+      }
+      if (before.localBalance !== after.localBalance || before.remoteBalance !== after.remoteBalance) {
+        events.push(fiberEvent(current.timestamp, "channel", "CHANNEL_LIQUIDITY_CHANGED", { before, after }));
+      }
+    },
+  });
+
+  diffById(previous.payments, current.payments, "paymentId", {
+    added: (payment) => events.push(fiberEvent(payment.timestamp ?? current.timestamp, "payment", paymentEventType(payment), payment)),
+    changed: (before, after) => {
+      if (before.status !== after.status) {
+        events.push(fiberEvent(after.timestamp ?? current.timestamp, "payment", paymentEventType(after), { before, after }));
+      }
+    },
+  });
+
+  return events;
+}
+
+export function analyzeHealth(snapshot, events = []) {
+  if (!snapshot) {
+    return {
+      node: healthScore(0, "critical"),
+      peers: healthScore(0, "critical"),
+      channels: healthScore(0, "critical"),
+      overall: healthScore(0, "critical"),
+    };
+  }
+  const node = analyzeNodeHealth(snapshot, events);
+  const peers = analyzePeerHealth(snapshot, events);
+  const channels = analyzeChannelHealth(snapshot, events);
+  const overallScore = Math.round((node.score * 0.4) + (peers.score * 0.25) + (channels.score * 0.35));
+  return {
+    node,
+    peers,
+    channels,
+    overall: healthScore(overallScore),
+  };
+}
+
+export function analyzeRootCauses(snapshot, events = [], reliabilityEntries = []) {
+  const diagnoses = [];
+  if (!snapshot) {
+    diagnoses.push(rootCause("UNKNOWN", "No telemetry snapshot is available.", 0.5, [], "Collect telemetry before diagnosing node health."));
+    return diagnoses;
+  }
+
+  if (!snapshot.node.online) {
+    diagnoses.push(rootCause(
+      "TIMEOUT",
+      "The Fiber node is offline or unreachable.",
+      0.95,
+      evidenceFromSnapshot(snapshot, "node"),
+      "Verify FNN is running, reachable, and listening on the configured RPC endpoint."
+    ));
+  }
+
+  for (const peer of snapshot.peers.filter((item) => !item.connected)) {
+    diagnoses.push(rootCause(
+      "PEER_OFFLINE",
+      `Peer ${short(peer.peerId)} is disconnected.`,
+      0.9,
+      [{ category: "peer", type: "PEER_DISCONNECTED", payload: peer }],
+      "Reconnect the peer or route around it."
+    ));
+  }
+
+  for (const channel of snapshot.channels.filter((item) => item.status !== "open")) {
+    diagnoses.push(rootCause(
+      "CHANNEL_CLOSED",
+      `Channel ${short(channel.channelId)} is ${channel.status}.`,
+      0.92,
+      [{ category: "channel", type: channelStatusEvent(channel.status), payload: channel }],
+      "Wait for the channel to open, reopen it, or select a different route."
+    ));
+  }
+
+  for (const channel of snapshot.channels.filter((item) => item.status === "open" && item.capacity > 0n && (item.localBalance * 100n / item.capacity) < 10n)) {
+    diagnoses.push(rootCause(
+      "INSUFFICIENT_LIQUIDITY",
+      `Channel ${short(channel.channelId)} has low outbound liquidity.`,
+      0.86,
+      [{ category: "channel", type: "LOW_LOCAL_LIQUIDITY", payload: channel }],
+      "Rebalance the channel, add outbound liquidity, or route payments through another channel."
+    ));
+  }
+
+  if (snapshot.node.online && snapshot.channels.length === 0) {
+    diagnoses.push(rootCause(
+      "NO_ROUTE",
+      "The node has no known channels, so it cannot route payments.",
+      0.88,
+      evidenceFromSnapshot(snapshot, "channel"),
+      "Open a channel or connect to peers with usable route graph data."
+    ));
+  }
+
+  const failedPayments = reliabilityEntries.filter((entry) => entry.status === "failed");
+  for (const entry of failedPayments.slice(-5)) {
+    diagnoses.push(diagnosisForFailedPayment(entry, snapshot, events));
+  }
+
+  const highFeeEntries = reliabilityEntries.filter((entry) => entry.fee > 0n && entry.amount > 0n && (entry.fee * 100n / entry.amount) >= 5n);
+  if (highFeeEntries.length > 0) {
+    diagnoses.push(rootCause(
+      "HIGH_ROUTING_FEES",
+      "Recent payment attempts have high fees relative to amount.",
+      0.72,
+      highFeeEntries.slice(-3).map((entry) => ({ category: "payment", type: "HIGH_FEE", payload: entry })),
+      "Try alternate routes, smaller route length, or peers with lower advertised fees."
+    ));
+  }
+
+  return dedupeRootCauses(diagnoses);
+}
+
+export function analyzeReliability(entries = [], events = []) {
+  const paymentEntries = entries.filter((entry) => entry.category === "payment");
+  const attempted = paymentEntries.length || countRecent(events, "payment", "PAYMENT_STARTED");
+  const succeeded = paymentEntries.filter((entry) => entry.status === "succeeded").length || countRecent(events, "payment", "PAYMENT_SUCCEEDED");
+  const failed = paymentEntries.filter((entry) => entry.status === "failed").length || countRecent(events, "payment", "PAYMENT_FAILED");
+  const completed = succeeded + failed;
+  const feeSamples = paymentEntries.filter((entry) => entry.fee !== undefined);
+  const latencySamples = paymentEntries.filter((entry) => entry.latencyMs !== undefined);
+  const routeSamples = paymentEntries.filter((entry) => entry.routeLength !== undefined);
+  return {
+    paymentsAttempted: attempted,
+    paymentsSucceeded: succeeded,
+    paymentsFailed: failed,
+    successRate: completed === 0 ? 0 : succeeded / completed,
+    failureRate: completed === 0 ? 0 : failed / completed,
+    averageFee: averageBigIntAsNumber(feeSamples.map((entry) => entry.fee)),
+    averageLatency: averageNumber(latencySamples.map((entry) => entry.latencyMs)),
+    averageRouteLength: averageNumber(routeSamples.map((entry) => entry.routeLength)),
+    failureFrequency: attempted === 0 ? 0 : failed / attempted,
+  };
+}
+
+export function generateAlerts(snapshot, events = [], health = analyzeHealth(snapshot, events), diagnoses = [], reliability = analyzeReliability([], events)) {
+  const alerts = [];
+  if (!snapshot) {
+    alerts.push(alert("critical", "No telemetry snapshot", "No Fiber telemetry is available for alert analysis.", "Start the telemetry collector and verify the configured state source."));
+    return alerts;
+  }
+
+  if (!snapshot.node.online) {
+    alerts.push(alert("critical", "Node offline", "The Fiber node is offline or unreachable.", "Verify FNN is running and the RPC endpoint is reachable."));
+  }
+  const connectedPeers = snapshot.peers.filter((peer) => peer.connected).length;
+  if (connectedPeers === 0) {
+    alerts.push(alert("critical", "No peers connected", "The node currently has no connected Fiber peers.", "Connect to a Fiber peer or inspect network connectivity."));
+  }
+  for (const channel of snapshot.channels) {
+    if (channel.status !== "open") {
+      alerts.push(alert("critical", "Channel not open", `Channel ${short(channel.channelId)} is ${channel.status}.`, "Wait for the channel to open or route around it."));
+      continue;
+    }
+    if (channel.capacity > 0n) {
+      const outboundPercent = Number((channel.localBalance * 10000n) / channel.capacity) / 100;
+      if (outboundPercent < 15) {
+        alerts.push(alert("warning", "Outbound liquidity below 15%", `Channel ${short(channel.channelId)} has ${outboundPercent.toFixed(2)}% outbound liquidity.`, "Rebalance the channel or add outbound liquidity."));
+      }
+    }
+  }
+  for (const event of events) {
+    if (event.type === "PEER_CONNECTED") {
+      alerts.push(alert("info", "New peer connected", `Peer ${short(event.payload?.peerId ?? event.payload?.after?.peerId)} connected.`, "No action required."));
+    } else if (event.type === "PEER_DISCONNECTED") {
+      alerts.push(alert("warning", "Peer disconnected", `Peer ${short(event.payload?.peerId ?? event.payload?.after?.peerId)} disconnected.`, "Monitor peer stability or reconnect manually if needed."));
+    } else if (event.type === "PAYMENT_FAILED") {
+      alerts.push(alert("warning", "Payment failed", "A payment failure was observed in the telemetry stream.", "Inspect root-cause diagnoses and route/liquidity history around the failure."));
+    }
+  }
+  if (health.overall?.status === "critical") {
+    alerts.push(alert("critical", "Node health critical", `Overall health score is ${health.overall.score}.`, "Inspect node, peer, and channel health factors immediately."));
+  } else if (health.overall?.status === "warning") {
+    alerts.push(alert("warning", "Node health degraded", `Overall health score is ${health.overall.score}.`, "Review health factors and recent events."));
+  }
+  for (const diagnosis of diagnoses.slice(0, 3)) {
+    const severity = diagnosis.confidence >= 0.9 ? "critical" : "warning";
+    alerts.push(alert(severity, `Root cause: ${diagnosis.code}`, diagnosis.explanation, diagnosis.suggestedAction));
+  }
+  if (reliability.paymentsAttempted > 0 && reliability.failureRate >= 0.5) {
+    alerts.push(alert("warning", "High payment failure rate", `Payment failure rate is ${(reliability.failureRate * 100).toFixed(1)}%.`, "Inspect failed payment diagnoses and route around unstable peers/channels."));
+  }
+  return dedupeAlerts(alerts);
+}
+
+export function replayHistory(timestamp, snapshots = [], events = [], reliabilityEntries = []) {
+  const point = Number(timestamp);
+  const snapshot = latestAtOrBefore(snapshots, point);
+  const replayEvents = events.filter((event) => event.timestamp <= point);
+  const replayReliability = reliabilityEntries.filter((entry) => entry.timestamp <= point);
+  const health = analyzeHealth(snapshot, replayEvents);
+  const reliability = analyzeReliability(replayReliability, replayEvents);
+  const diagnoses = analyzeRootCauses(snapshot, replayEvents, replayReliability);
+  return {
+    timestamp: point,
+    snapshot,
+    counts: {
+      payments: replayReliability.length,
+      failures: reliability.paymentsFailed,
+      peers: snapshot?.peers.length ?? 0,
+      connectedPeers: snapshot?.peers.filter((peer) => peer.connected).length ?? 0,
+      channels: snapshot?.channels.length ?? 0,
+      openChannels: snapshot?.channels.filter((channel) => channel.status === "open").length ?? 0,
+    },
+    health,
+    reliability,
+    diagnoses,
+    events: replayEvents,
+  };
+}
+
+export function normalizeTelemetrySnapshot(input = {}) {
+  return {
+    timestamp: numberOrNow(input.timestamp),
+    node: normalizeNode(input.node),
+    peers: (input.peers ?? []).map(normalizePeer),
+    channels: (input.channels ?? []).map(normalizeChannel),
+    payments: (input.payments ?? []).map(normalizePaymentSummary),
+    diagnostics: (input.diagnostics ?? []).map(normalizeDiagnostic),
+  };
+}
+
+async function collectFiberState(options) {
+  if (options.stateProvider) {
+    return options.stateProvider();
+  }
+  const pulseUrl = options.pulseUrl;
+  const pulseModule = options.pulseModule;
+  if (pulseUrl) {
+    return fetchPulseState(pulseUrl, options);
+  }
+  if (pulseModule) {
+    const imported = await import(resolveImportSpecifier(pulseModule));
+    if (typeof imported.collectFiberStateReport !== "function") {
+      throw new FiberObservabilityError("pulseModule must export collectFiberStateReport().", "INVALID_PULSE_MODULE");
+    }
+    return imported.collectFiberStateReport({
+      rpcUrl: options.rpcUrl,
+      timeoutMs: options.timeoutMs,
+      rpcHeaders: options.rpcHeaders,
+    });
+  }
+  if (options.rpcUrl) {
+    const imported = await import(resolveImportSpecifier(options.defaultPulseModule ?? "../pulse/index.mjs"));
+    return imported.collectFiberStateReport({
+      rpcUrl: options.rpcUrl,
+      timeoutMs: options.timeoutMs,
+      rpcHeaders: options.rpcHeaders,
+    });
+  }
+  throw new FiberObservabilityError("A state source is required: stateProvider, pulseUrl, pulseModule, or rpcUrl.", "NO_STATE_SOURCE");
+}
+
+async function fetchPulseState(pulseUrl, options) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), options.timeoutMs ?? 8000);
+  try {
+    const response = await fetch(`${pulseUrl.replace(/\/$/, "")}/state`, { signal: controller.signal });
+    if (!response.ok) {
+      throw new FiberObservabilityError(`Pulse /state failed with HTTP ${response.status}.`, "PULSE_STATE_FAILED");
+    }
+    return response.json();
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function collectPaymentSummaries(options, state) {
+  if (typeof options.paymentProvider === "function") {
+    const payments = await options.paymentProvider(state);
+    return payments ?? [];
+  }
+  if (Array.isArray(state.payments)) {
+    return state.payments;
+  }
+  if (options.rpcUrl) {
+    return collectPaymentSummariesFromRpc(options);
+  }
+  return [];
+}
+
+async function collectPaymentSummariesFromRpc(options) {
+  const candidates = [
+    ["list_payments", [{}]],
+    ["get_payment", [{}]],
+  ];
+  for (const [method, params] of candidates) {
+    try {
+      const result = await rpc(options.rpcUrl, method, params, options);
+      const items = extractList(result, "payments");
+      if (items.length > 0) return items.map(normalizePaymentSummary);
+    } catch {
+      // FNN versions differ here; absence of payment APIs should not break telemetry.
+    }
+  }
+  return [];
+}
+
+async function rpc(rpcUrl, method, params = [], options = {}) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), options.timeoutMs ?? 8000);
+  try {
+    const response = await fetch(rpcUrl, {
+      method: "POST",
+      headers: { "content-type": "application/json", ...(options.rpcHeaders ?? {}) },
+      body: JSON.stringify({ id: 1, jsonrpc: "2.0", method, params }),
+      signal: controller.signal,
+    });
+    const payload = await response.json();
+    if (payload.error) throw new FiberObservabilityError(payload.error.message ?? "Fiber RPC error", "FIBER_RPC_ERROR", payload.error);
+    return payload.result;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function offlineSnapshot(timestamp, error) {
+  return normalizeTelemetrySnapshot({
+    timestamp,
+    node: {
+      nodeId: "unknown",
+      version: "unknown",
+      online: false,
+      peerCount: 0,
+      channelCount: 0,
+      lastUpdated: timestamp,
+      error: error instanceof Error ? error.message : String(error),
+    },
+    peers: [],
+    channels: [],
+    payments: [],
+  });
+}
+
+function normalizeNode(node = {}) {
+  return {
+    nodeId: stringValue(node.nodeId ?? node.node_id ?? node.pubkey, "unknown"),
+    version: stringValue(node.version, "unknown"),
+    online: Boolean(node.online),
+    peerCount: numberValue(node.peerCount ?? node.peer_count, 0),
+    channelCount: numberValue(node.channelCount ?? node.channel_count, 0),
+    lastUpdated: numberValue(node.lastUpdated ?? node.last_updated, Date.now()),
+    error: node.error,
+  };
+}
+
+function normalizePeer(peer = {}) {
+  return {
+    peerId: stringValue(peer.peerId ?? peer.peer_id ?? peer.nodeId ?? peer.pubkey, "unknown"),
+    connected: Boolean(peer.connected ?? peer.online),
+    address: peer.address,
+    lastSeen: peer.lastSeen ?? peer.last_seen,
+  };
+}
+
+function normalizeChannel(channel = {}) {
+  return {
+    channelId: stringValue(channel.channelId ?? channel.channel_id ?? channel.channel_outpoint, "unknown"),
+    peerId: stringValue(channel.peerId ?? channel.peer_id ?? channel.counterparty, "unknown"),
+    status: stringValue(channel.status ?? channel.state, "unknown"),
+    capacity: amountMaybe(channel.capacity) ?? 0n,
+    localBalance: amountMaybe(channel.localBalance ?? channel.local_balance) ?? 0n,
+    remoteBalance: amountMaybe(channel.remoteBalance ?? channel.remote_balance) ?? 0n,
+    assetType: stringValue(channel.assetType ?? channel.asset_type, "CKB"),
+  };
+}
+
+function normalizePaymentSummary(payment = {}) {
+  return {
+    paymentId: stringValue(payment.paymentId ?? payment.payment_id ?? payment.id ?? payment.hash, "unknown"),
+    status: stringValue(payment.status ?? payment.state, "unknown"),
+    amount: amountMaybe(payment.amount ?? payment.value) ?? 0n,
+    assetType: stringValue(payment.assetType ?? payment.asset_type, "CKB"),
+    direction: payment.direction,
+    route: payment.route ?? payment.hops ?? [],
+    fee: amountMaybe(payment.fee ?? payment.routingFee ?? payment.routing_fee ?? payment.totalFee ?? payment.total_fee),
+    latencyMs: numberMaybe(payment.latencyMs ?? payment.latency_ms ?? payment.durationMs ?? payment.duration_ms),
+    error: payment.error ?? payment.failure_reason,
+    timestamp: numberValue(payment.timestamp ?? payment.created_at ?? payment.updated_at, Date.now()),
+  };
+}
+
+function normalizeDiagnostic(diagnostic = {}) {
+  return {
+    code: stringValue(diagnostic.code, "UNKNOWN"),
+    severity: stringValue(diagnostic.severity, "info"),
+    title: stringValue(diagnostic.title, diagnostic.code ?? "Diagnostic"),
+    description: stringValue(diagnostic.description, ""),
+    recommendation: diagnostic.recommendation,
+  };
+}
+
+function deriveReliabilityEntries(previous, current, events) {
+  const entries = [];
+  for (const event of events) {
+    if (event.category !== "payment") continue;
+    const payment = event.payload?.after ?? event.payload;
+    entries.push(reliabilityEntryFromPaymentEvent(event, payment));
+  }
+  if (!previous && current?.payments?.length) {
+    for (const payment of current.payments) {
+      entries.push(reliabilityEntryFromPaymentEvent(fiberEvent(payment.timestamp ?? current.timestamp, "payment", paymentEventType(payment), payment), payment));
+    }
+  }
+  return dedupeReliabilityEntries(entries);
+}
+
+function reliabilityEntryFromPaymentEvent(event, payment = {}) {
+  return {
+    id: event.id,
+    timestamp: event.timestamp,
+    category: "payment",
+    paymentId: payment.paymentId ?? "unknown",
+    status: reliabilityStatus(payment.status ?? event.type),
+    amount: amountMaybe(payment.amount) ?? 0n,
+    fee: amountMaybe(payment.fee ?? payment.routingFee ?? payment.routing_fee ?? payment.totalFee ?? payment.total_fee) ?? 0n,
+    routeLength: Array.isArray(payment.route) ? payment.route.length : undefined,
+    latencyMs: numberMaybe(payment.latencyMs ?? payment.latency_ms ?? payment.durationMs ?? payment.duration_ms),
+    error: payment.error,
+  };
+}
+
+function reliabilityStatus(status) {
+  const text = String(status ?? "").toLowerCase();
+  if (text.includes("fail") || text.includes("reject")) return "failed";
+  if (text.includes("success") || text.includes("sent") || text.includes("complete") || text.includes("succeed")) return "succeeded";
+  return "attempted";
+}
+
+function diagnosisForFailedPayment(entry, snapshot, events) {
+  const recentPeerOffline = lastEvent(events, "peer", "PEER_DISCONNECTED");
+  if (recentPeerOffline) {
+    return rootCause(
+      "PEER_OFFLINE",
+      "A payment failed near a peer disconnect event.",
+      0.76,
+      [{ category: "payment", type: "PAYMENT_FAILED", payload: entry }, recentPeerOffline],
+      "Reconnect the peer or use a route that avoids the unstable peer."
+    );
+  }
+  const lowLiquidity = snapshot.channels.find((channel) => channel.capacity > 0n && (channel.localBalance * 100n / channel.capacity) < 10n);
+  if (lowLiquidity) {
+    return rootCause(
+      "INSUFFICIENT_LIQUIDITY",
+      "A payment failed while at least one channel has low outbound liquidity.",
+      0.74,
+      [{ category: "payment", type: "PAYMENT_FAILED", payload: entry }, { category: "channel", type: "LOW_LOCAL_LIQUIDITY", payload: lowLiquidity }],
+      "Rebalance low-liquidity channels or use alternate routes."
+    );
+  }
+  if (!snapshot.node.online) {
+    return rootCause(
+      "TIMEOUT",
+      "A payment failed while the node was offline.",
+      0.82,
+      [{ category: "payment", type: "PAYMENT_FAILED", payload: entry }, { category: "node", type: "NODE_OFFLINE", payload: snapshot.node }],
+      "Stabilize the node and retry after it is online."
+    );
+  }
+  return rootCause(
+    "UNKNOWN",
+    "A payment failed, but available telemetry does not identify a more specific cause.",
+    0.45,
+    [{ category: "payment", type: "PAYMENT_FAILED", payload: entry }],
+    "Collect more Fiber RPC payment details, route data, and peer/channel events around the failure."
+  );
+}
+
+function rootCause(code, explanation, confidence, evidence, suggestedAction) {
+  const affected = affectedFromEvidence(evidence);
+  return {
+    code,
+    explanation,
+    confidence,
+    evidence,
+    suggestedAction,
+    affectedChannel: affected.channel,
+    affectedPeer: affected.peer,
+  };
+}
+
+function affectedFromEvidence(evidence = []) {
+  let channel;
+  let peer;
+  for (const item of evidence) {
+    const payload = item.payload?.after ?? item.payload ?? {};
+    channel ??= payload.channelId;
+    peer ??= payload.peerId ?? payload.fromNode ?? payload.toNode;
+  }
+  return { channel, peer };
+}
+
+function evidenceFromSnapshot(snapshot, category) {
+  if (category === "node") return [{ category: "node", type: snapshot.node.online ? "NODE_ONLINE" : "NODE_OFFLINE", payload: snapshot.node }];
+  if (category === "channel") return snapshot.channels.map((channel) => ({ category: "channel", type: channelStatusEvent(channel.status), payload: channel }));
+  if (category === "peer") return snapshot.peers.map((peer) => ({ category: "peer", type: peer.connected ? "PEER_CONNECTED" : "PEER_DISCONNECTED", payload: peer }));
+  return [];
+}
+
+function dedupeRootCauses(diagnoses) {
+  const seen = new Set();
+  const deduped = [];
+  for (const diagnosis of diagnoses) {
+    const key = `${diagnosis.code}:${diagnosis.affectedChannel ?? ""}:${diagnosis.affectedPeer ?? ""}:${diagnosis.explanation}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    deduped.push(diagnosis);
+  }
+  return deduped.sort((left, right) => right.confidence - left.confidence);
+}
+
+function dedupeReliabilityEntries(entries) {
+  const seen = new Set();
+  return entries.filter((entry) => {
+    if (seen.has(entry.id)) return false;
+    seen.add(entry.id);
+    return true;
+  });
+}
+
+function alert(severity, title, description, recommendation) {
+  return {
+    id: `${Date.now()}:${severity}:${title}`,
+    timestamp: Date.now(),
+    severity,
+    title,
+    description,
+    recommendation,
+  };
+}
+
+function dedupeAlerts(alerts) {
+  const seen = new Set();
+  return alerts.filter((item) => {
+    const key = alertKey(item);
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+function alertKey(item) {
+  return `${item.severity}:${item.title}:${item.description}`;
+}
+
+function latestAtOrBefore(items, timestamp) {
+  return [...items]
+    .filter((item) => item.timestamp <= timestamp)
+    .sort((left, right) => right.timestamp - left.timestamp)[0];
+}
+
+function fiberEvent(timestamp, category, type, payload) {
+  return {
+    id: `${timestamp}:${category}:${type}:${stableEventKey(payload)}`,
+    timestamp,
+    category,
+    type,
+    payload,
+  };
+}
+
+function stableEventKey(payload) {
+  if (!payload || typeof payload !== "object") return "event";
+  return payload.channelId
+    ?? payload.peerId
+    ?? payload.paymentId
+    ?? payload.nodeId
+    ?? payload.after?.channelId
+    ?? payload.after?.peerId
+    ?? payload.after?.paymentId
+    ?? payload.before?.channelId
+    ?? payload.before?.peerId
+    ?? payload.before?.paymentId
+    ?? "event";
+}
+
+function diffById(previousItems, currentItems, key, handlers) {
+  const previousById = new Map(previousItems.map((item) => [item[key], item]));
+  const currentById = new Map(currentItems.map((item) => [item[key], item]));
+  for (const [id, item] of currentById) {
+    if (!previousById.has(id)) {
+      handlers.added?.(item);
+    } else {
+      handlers.changed?.(previousById.get(id), item);
+    }
+  }
+  for (const [id, item] of previousById) {
+    if (!currentById.has(id)) handlers.removed?.(item);
+  }
+}
+
+function channelStatusEvent(status) {
+  if (status === "open") return "CHANNEL_OPENED";
+  if (status === "closed") return "CHANNEL_CLOSED";
+  if (status === "closing") return "CHANNEL_CLOSING";
+  if (status === "pending") return "CHANNEL_PENDING";
+  return "CHANNEL_STATUS_CHANGED";
+}
+
+function paymentEventType(payment) {
+  const status = String(payment.status ?? "unknown").toLowerCase();
+  if (status.includes("fail") || status.includes("reject")) return "PAYMENT_FAILED";
+  if (status.includes("success") || status.includes("sent") || status.includes("complete")) return "PAYMENT_SUCCEEDED";
+  if (status.includes("pending") || status.includes("created") || status.includes("started")) return "PAYMENT_STARTED";
+  return "PAYMENT_SEEN";
+}
+
+function analyzeNodeHealth(snapshot, events) {
+  let score = 100;
+  const factors = [];
+  if (!snapshot.node.online) {
+    score -= 70;
+    factors.push("Node is offline.");
+  }
+  if (snapshot.node.peerCount === 0 && snapshot.peers.length === 0) {
+    score -= 20;
+    factors.push("Node has no connected peers.");
+  }
+  if (snapshot.node.channelCount === 0 && snapshot.channels.length === 0) {
+    score -= 10;
+    factors.push("Node has no channels.");
+  }
+  const offlineEvents = countRecent(events, "node", "NODE_OFFLINE");
+  if (offlineEvents > 0) {
+    score -= Math.min(20, offlineEvents * 5);
+    factors.push(`Recent offline events: ${offlineEvents}.`);
+  }
+  return healthScore(score, undefined, factors);
+}
+
+function analyzePeerHealth(snapshot, events) {
+  let score = 100;
+  const factors = [];
+  const total = snapshot.peers.length;
+  const connected = snapshot.peers.filter((peer) => peer.connected).length;
+  if (total === 0) {
+    score -= 60;
+    factors.push("No peers are known.");
+  } else {
+    const connectedRatio = connected / total;
+    score -= Math.round((1 - connectedRatio) * 50);
+    if (connectedRatio < 1) factors.push(`${total - connected} peer(s) disconnected.`);
+  }
+  const disconnects = countRecent(events, "peer", "PEER_DISCONNECTED");
+  if (disconnects > 0) {
+    score -= Math.min(30, disconnects * 10);
+    factors.push(`Recent peer disconnects: ${disconnects}.`);
+  }
+  return healthScore(score, undefined, factors);
+}
+
+function analyzeChannelHealth(snapshot, events) {
+  let score = 100;
+  const factors = [];
+  if (snapshot.channels.length === 0) {
+    score -= 70;
+    factors.push("No channels are known.");
+  }
+  const nonOpen = snapshot.channels.filter((channel) => channel.status !== "open").length;
+  if (nonOpen > 0) {
+    score -= Math.min(50, nonOpen * 20);
+    factors.push(`${nonOpen} channel(s) are not open.`);
+  }
+  const lowLiquidity = snapshot.channels.filter((channel) => channel.status === "open" && channel.capacity > 0n && (channel.localBalance * 100n / channel.capacity) < 10n).length;
+  if (lowLiquidity > 0) {
+    score -= Math.min(30, lowLiquidity * 10);
+    factors.push(`${lowLiquidity} channel(s) have low local liquidity.`);
+  }
+  const failures = countRecent(events, "payment", "PAYMENT_FAILED");
+  if (failures > 0) {
+    score -= Math.min(25, failures * 8);
+    factors.push(`Recent payment failures: ${failures}.`);
+  }
+  return healthScore(score, undefined, factors);
+}
+
+function healthScore(score, status = undefined, factors = []) {
+  const normalized = clamp(Math.round(score), 0, 100);
+  return {
+    score: normalized,
+    status: status ?? statusForScore(normalized),
+    factors,
+  };
+}
+
+function statusForScore(score) {
+  if (score >= 80) return "healthy";
+  if (score >= 50) return "warning";
+  return "critical";
+}
+
+function countRecent(events, category, type) {
+  return events.filter((event) => event.category === category && event.type === type).length;
+}
+
+function lastEvent(events, category, type) {
+  return [...events].reverse().find((event) => event.category === category && event.type === type);
+}
+
+function averageBigIntAsNumber(values) {
+  if (values.length === 0) return 0;
+  return Number(values.reduce((sum, value) => sum + value, 0n)) / values.length;
+}
+
+function averageNumber(values) {
+  if (values.length === 0) return 0;
+  return values.reduce((sum, value) => sum + value, 0) / values.length;
+}
+
+function clamp(value, min, max) {
+  return Math.min(max, Math.max(min, value));
+}
+
+function extractList(value, key) {
+  if (Array.isArray(value)) return value;
+  if (Array.isArray(value?.[key])) return value[key];
+  return [];
+}
+
+function amountMaybe(value) {
+  if (value === undefined || value === null || value === "") return undefined;
+  if (typeof value === "bigint") return value;
+  if (typeof value === "number" && Number.isFinite(value)) return BigInt(Math.trunc(value));
+  if (typeof value === "string" && /^0x[0-9a-fA-F]+$/.test(value)) return BigInt(value);
+  if (typeof value === "string" && /^[0-9]+$/.test(value)) return BigInt(value);
+  return undefined;
+}
+
+function stringValue(value, fallback) {
+  return value === undefined || value === null || value === "" ? fallback : String(value);
+}
+
+function short(value) {
+  const text = String(value ?? "");
+  return text.length <= 14 ? text : `${text.slice(0, 8)}...${text.slice(-6)}`;
+}
+
+function numberValue(value, fallback) {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : fallback;
+}
+
+function numberMaybe(value) {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+function numberOrNow(value) {
+  return numberValue(value, Date.now());
+}
+
+function resolveImportSpecifier(specifier) {
+  if (/^(file|data|node|https?):/.test(specifier)) return specifier;
+  if (specifier.startsWith(".") || specifier.includes("\\") || specifier.includes("/")) {
+    return pathToFileURL(path.resolve(process.cwd(), specifier)).href;
+  }
+  return specifier;
+}
+
+function stringify(value) {
+  return JSON.stringify(value, (_, nested) => typeof nested === "bigint" ? nested.toString() : nested, 2);
+}
+
+function parseCliArgs(argv) {
+  const options = {};
+  let command = argv[0]?.startsWith("--") ? "collect" : (argv.shift() ?? "help");
+  for (let index = 0; index < argv.length; index += 1) {
+    const raw = argv[index];
+    const [flag, inline] = raw.split("=", 2);
+    const value = () => inline ?? argv[++index];
+    if (flag === "--rpc") options.rpcUrl = value();
+    else if (flag === "--pulse-url") options.pulseUrl = value();
+    else if (flag === "--pulse-module") options.pulseModule = value();
+    else if (flag === "--interval") options.intervalMs = Number(value());
+    else if (flag === "--samples") options.samples = Number(value());
+    else if (flag === "--max-snapshots") options.maxSnapshots = Number(value());
+    else if (flag === "--max-events" || flag === "--max-log") options.maxEvents = Number(value());
+    else if (flag === "--max-reliability-entries" || flag === "--max-reliability-log" || flag === "--max-metrics-log") options.maxReliabilityEntries = Number(value());
+    else if (flag === "--max-alerts" || flag === "--max-alert-log") options.maxAlerts = Number(value());
+    else if (flag === "--json") options.json = true;
+    else if (flag === "--help" || flag === "-h") command = "help";
+    else throw new FiberObservabilityError(`Unknown option ${flag}`, "CLI_USAGE_ERROR");
+  }
+  return { command, options };
+}
+
+function help() {
+  return [
+    "Fiber Observability Telemetry Collector",
+    "",
+    "Usage:",
+    "  node collector.mjs collect --rpc http://127.0.0.1:8227 --pulse-module ../pulse/index.mjs --json",
+    "  node collector.mjs watch --rpc http://127.0.0.1:8227 --pulse-module ../pulse/index.mjs --interval 5000 --samples 3 --max-events 1000 --max-reliability-log 1000 --max-alerts 1000 --json",
+  ].join("\n");
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const { command, options } = parseCliArgs(process.argv.slice(2));
+  if (command === "help") {
+    console.log(help());
+  } else if (command === "collect") {
+    collectTelemetrySnapshot(options)
+      .then((snapshot) => console.log(options.json ? stringify(snapshot) : summarizeSnapshot(snapshot)))
+      .catch((error) => {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+      });
+  } else if (command === "watch") {
+    const target = options.samples ?? 0;
+    let count = 0;
+    const collector = createTelemetryCollector(options);
+    collector.on("snapshot", (snapshot) => {
+      count += 1;
+      console.log(options.json ? stringify(snapshot) : summarizeSnapshot(snapshot));
+      if (target > 0 && count >= target) {
+        collector.stop();
+        process.exitCode = 0;
+      }
+    });
+    collector.start();
+  } else {
+    console.error(`Unknown command ${command}`);
+    process.exitCode = 1;
+  }
+}
+
+function summarizeSnapshot(snapshot) {
+  return [
+    `timestamp=${snapshot.timestamp}`,
+    `online=${snapshot.node.online}`,
+    `peers=${snapshot.peers.length}`,
+    `channels=${snapshot.channels.length}`,
+    `payments=${snapshot.payments.length}`,
+  ].join(" ");
+}