@ngockhoale/ukit 3.0.5 → 3.0.7

package/src/core/observability/analytics/opportunities.js

@@ -0,0 +1,329 @@
+/**
+ * opportunities.js (TASK-012, SPEC §5 DF-FR09/DF-FR12, §8) — hypothesis backlog.
+ *
+ *   detectOpportunities(summaries): Opportunity[]
+ *
+ * Groups TraceSummaries by structural fingerprint, stratifies each cluster
+ * into cohorts, and ranks optimization CANDIDATES by measured critical-path
+ * impact — never by largest standalone duration. Output is a hypothesis
+ * backlog for human/evaluator review (TASK-013 persists it); nothing here
+ * may auto-modify router, memory, or runtime config.
+ *
+ * Opportunity = {
+ *   id, fingerprint, frequency, cohorts[],
+ *   estimated_savings: { value, method },
+ *   quality_risk, coverage, evidence_refs[], trace_refs[],
+ *   confounded, status: 'hypothesis' | 'inconclusive'
+ * }
+ *
+ * Honesty rules (SPEC §7/§12):
+ *   - Savings are measured, not asserted: only the critical-path-attributable
+ *     duration of pattern spans is claimed, and the `method` field says how.
+ *   - A cluster below MIN_COHORT_TRACES or containing any trace with
+ *     telemetry_complete=false is `inconclusive`: no improvement claim is
+ *     populated and it never ranks above a conclusive item.
+ *   - A cluster mixing cohort keys (model/version) is `confounded: true` —
+ *     Simpson's-paradox guard: only per-cohort numbers are trustworthy, the
+ *     aggregate is flagged, and it ranks below unconfounded items.
+ *   - Every evidence ref must resolve to a real record ID carried by the
+ *     input summaries; a pattern span with no resolvable refs is a contract
+ *     violation → TypeError, never a dangling citation.
+ */
+
+import { computeFingerprint } from './fingerprints.js';
+
+export const MIN_COHORT_TRACES = 3;
+
+const QUALITY_RISK = Object.freeze({
+  dropped: 'high',
+  failure: 'high',
+  retry: 'medium',
+  'cache-miss': 'medium',
+  clean: 'low',
+});
+
+const SAVINGS_METHOD = 'critical_path_attributed_ms';
+const NO_CLAIM_METHOD = 'none — insufficient coverage';
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function num(value) {
+  return typeof value === 'number' && Number.isFinite(value) ? value : 0;
+}
+
+/**
+ * Recompute the causal critical path over a summary's spans (same rules as
+ * summarizeTrace) and return the set of span_ids that lie on it. A node is
+ * on the path when its own measured duration is the winning contribution,
+ * or when the winning contribution flows through one of its children.
+ */
+function criticalPathSpanIds(summary) {
+  const spans = summary.spans.filter(isPlainObject);
+  const byId = new Map(spans.map((s) => [s.span_id, s]));
+  const children = new Map();
+  const roots = [];
+  for (const span of spans) {
+    if (typeof span.parent_span_id === 'string' && byId.has(span.parent_span_id)) {
+      const list = children.get(span.parent_span_id) || [];
+      list.push(span);
+      children.set(span.parent_span_id, list);
+    } else {
+      roots.push(span);
+    }
+  }
+
+  const memo = new Map();
+  function pathOf(span) {
+    if (memo.has(span.span_id)) return memo.get(span.span_id);
+    let best = typeof span.duration_ms === 'number' ? span.duration_ms : null;
+    let minStart = Infinity;
+    let maxEnd = -Infinity;
+    for (const kid of children.get(span.span_id) || []) {
+      const kidPath = pathOf(kid);
+      if (kidPath !== null && (best === null || kidPath > best)) best = kidPath;
+      if (typeof kid.start_ns === 'number' && typeof kid.end_ns === 'number') {
+        if (kid.start_ns < minStart) minStart = kid.start_ns;
+        if (kid.end_ns > maxEnd) maxEnd = kid.end_ns;
+      }
+    }
+    if (maxEnd >= minStart) {
+      const extent = (maxEnd - minStart) / 1e6;
+      if (best === null || extent > best) best = extent;
+    }
+    memo.set(span.span_id, best);
+    return best;
+  }
+
+  const onPath = new Set();
+  function mark(span) {
+    const kids = children.get(span.span_id) || [];
+    const own = typeof span.duration_ms === 'number' ? span.duration_ms : null;
+    let bestKid = null;
+    let bestKidPath = null;
+    let minStart = Infinity;
+    let maxEnd = -Infinity;
+    for (const kid of kids) {
+      const kidPath = pathOf(kid);
+      if (kidPath !== null && (bestKidPath === null || kidPath > bestKidPath)) {
+        bestKidPath = kidPath;
+        bestKid = kid;
+      }
+      if (typeof kid.start_ns === 'number' && typeof kid.end_ns === 'number') {
+        if (kid.start_ns < minStart) minStart = kid.start_ns;
+        if (kid.end_ns > maxEnd) maxEnd = kid.end_ns;
+      }
+    }
+    const extent = maxEnd >= minStart ? (maxEnd - minStart) / 1e6 : null;
+    const winner = pathOf(span);
+    if (winner === null) return;
+    onPath.add(span.span_id);
+    // Deterministic precedence on ties: own duration, then child path,
+    // then wall-clock extent (which marks every measured child).
+    if (own !== null && own === winner) return;
+    if (bestKid !== null && bestKidPath === winner) {
+      mark(bestKid);
+      return;
+    }
+    if (extent !== null && extent === winner) {
+      for (const kid of kids) {
+        if (typeof kid.start_ns === 'number' && typeof kid.end_ns === 'number') mark(kid);
+      }
+    }
+  }
+
+  for (const root of roots) mark(root);
+  return onPath;
+}
+
+/** The single largest measured NON-ROOT span — the candidate for patterns
+ *  that are not attributable to a specific span kind (clean, cache-miss,
+ *  dropped). A root span's duration is the trace's own denominator: claiming
+ *  it as savings would double-count its children and assert the whole
+ *  episode is waste. Falls back to the dominant root only when the trace
+ *  has no measured child spans at all. */
+function dominantSpan(summary) {
+  let best = null;
+  let bestRoot = null;
+  for (const span of summary.spans) {
+    if (!isPlainObject(span) || typeof span.duration_ms !== 'number') continue;
+    if (typeof span.parent_span_id === 'string' && span.parent_span_id.length > 0) {
+      if (best === null || span.duration_ms > best.duration_ms) best = span;
+    } else if (bestRoot === null || span.duration_ms > bestRoot.duration_ms) {
+      bestRoot = span;
+    }
+  }
+  return best || bestRoot;
+}
+
+
+/**
+ * Spans that embody the fingerprint's pattern. Savings are claimed only for
+ * pattern spans that also lie on the critical path — an expensive parallel
+ * branch contributes zero.
+ */
+function patternSpans(summary, kind) {
+  const spans = summary.spans.filter(isPlainObject);
+  switch (kind) {
+    case 'retry':
+      return spans.filter((s) => Number.isInteger(s.attempt_index) && s.attempt_index > 1);
+    case 'failure':
+      return spans.filter((s) => s.status === 'failed');
+    default: {
+      const dominant = dominantSpan(summary);
+      return dominant ? [dominant] : [];
+    }
+  }
+}
+
+function recordRefsOf(span) {
+  const refs = [];
+  if (typeof span.start_record_id === 'string' && span.start_record_id.length > 0) {
+    refs.push(span.start_record_id);
+  }
+  if (typeof span.end_record_id === 'string' && span.end_record_id.length > 0) {
+    refs.push(span.end_record_id);
+  }
+  return refs;
+}
+
+/** Cohort key: model-span operation (the version axis adapters emit) plus
+ *  the metric version that produced the summary. */
+function cohortKeyOf(summary) {
+  const modelOps = new Set();
+  for (const span of summary.spans) {
+    if (isPlainObject(span) && span.family === 'model' && typeof span.operation === 'string') {
+      modelOps.add(span.operation);
+    }
+  }
+  const model = modelOps.size === 1 ? [...modelOps][0] : modelOps.size === 0 ? 'unknown' : 'mixed';
+  const version = typeof summary.metric_version === 'string' ? summary.metric_version : 'unknown';
+  return `${model}|${version}`;
+}
+
+function savingsOf(summary, kind, onPath) {
+  let total = 0;
+  for (const span of patternSpans(summary, kind)) {
+    if (onPath.has(span.span_id) && typeof span.duration_ms === 'number') {
+      total += span.duration_ms;
+    }
+  }
+  return total;
+}
+
+export function detectOpportunities(summaries) {
+  if (!Array.isArray(summaries)) {
+    throw new TypeError('detectOpportunities: summaries must be an array of TraceSummary');
+  }
+  for (const summary of summaries) {
+    if (!isPlainObject(summary) || !Array.isArray(summary.spans)) {
+      throw new TypeError('detectOpportunities: each summary must be a TraceSummary object with a spans array');
+    }
+  }
+
+  // Cluster by structural fingerprint.
+  const clusters = new Map();
+  for (const summary of summaries) {
+    const fingerprint = computeFingerprint(summary);
+    let cluster = clusters.get(fingerprint.hash);
+    if (!cluster) {
+      cluster = { fingerprint, summaries: [] };
+      clusters.set(fingerprint.hash, cluster);
+    }
+    cluster.summaries.push(summary);
+  }
+
+  const opportunities = [];
+  for (const cluster of clusters.values()) {
+    const { fingerprint } = cluster;
+    const kind = fingerprint.kind;
+
+    const traceRefs = [];
+    const evidenceRefs = [];
+    const cohortsByKey = new Map();
+    let sampled = 0;
+    let totalSavings = 0;
+
+    for (const summary of cluster.summaries) {
+      if (typeof summary.trace_id === 'string') traceRefs.push(summary.trace_id);
+      if (summary.telemetry_complete !== true) sampled += 1;
+
+      const onPath = criticalPathSpanIds(summary);
+      const savings = savingsOf(summary, kind, onPath);
+      totalSavings += savings;
+
+      const refs = [];
+      for (const span of patternSpans(summary, kind)) {
+        refs.push(...recordRefsOf(span));
+      }
+      if (refs.length === 0) {
+        throw new TypeError(
+          `detectOpportunities: dangling evidence — pattern spans of trace ` +
+            `${summary.trace_id ?? 'unknown'} carry no resolvable record IDs`
+        );
+      }
+      evidenceRefs.push(...refs);
+
+      const key = cohortKeyOf(summary);
+      let cohort = cohortsByKey.get(key);
+      if (!cohort) {
+        cohort = { key, traces: 0, sampled: 0, estimated_savings: { value: 0, method: SAVINGS_METHOD } };
+        cohortsByKey.set(key, cohort);
+      }
+      cohort.traces += 1;
+      if (summary.telemetry_complete !== true) cohort.sampled += 1;
+      cohort.estimated_savings.value += savings;
+    }
+
+    const cohorts = [...cohortsByKey.values()].sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+    const confounded = cohorts.length > 1;
+    const inconclusive = cluster.summaries.length < MIN_COHORT_TRACES || sampled > 0;
+
+    const coverage = {
+      traces: cluster.summaries.length,
+      telemetry_complete: cluster.summaries.length - sampled,
+      sampled,
+      min_traces: MIN_COHORT_TRACES,
+    };
+
+    const estimated_savings = inconclusive
+      ? { value: null, method: NO_CLAIM_METHOD }
+      : { value: totalSavings, method: SAVINGS_METHOD };
+    if (inconclusive) {
+      for (const cohort of cohorts) {
+        cohort.estimated_savings = { value: null, method: NO_CLAIM_METHOD };
+      }
+    }
+
+    opportunities.push({
+      id: `opp-${fingerprint.hash}`,
+      fingerprint,
+      frequency: cluster.summaries.length,
+      cohorts,
+      estimated_savings,
+      quality_risk: QUALITY_RISK[kind] || 'low',
+      coverage,
+      evidence_refs: [...new Set(evidenceRefs)].sort(),
+      trace_refs: traceRefs.sort(),
+      confounded,
+      status: inconclusive ? 'inconclusive' : 'hypothesis',
+      metric_version: fingerprint.metric_version,
+    });
+  }
+
+  // Rank: conclusive first, then confounded, then inconclusive; within a
+  // tier by measured savings (null last), then id for determinism.
+  const rank = (opp) => (opp.status === 'inconclusive' ? 2 : opp.confounded ? 1 : 0);
+  opportunities.sort((a, b) => {
+    const dr = rank(a) - rank(b);
+    if (dr !== 0) return dr;
+    const av = a.estimated_savings.value;
+    const bv = b.estimated_savings.value;
+    const ds = (bv === null ? -1 : bv) - (av === null ? -1 : av);
+    if (ds !== 0) return ds;
+    return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+  });
+
+  return opportunities;
+}

package/src/core/observability/analytics/rebuild.js

@@ -0,0 +1,56 @@
+/**
+ * rebuild.js (TASK-008, SPEC §5 DF-FR05/DF-FR09, §8) — derived index rebuild.
+ *
+ *   rebuildIndex(root): { summaries, coverage, ok }
+ *
+ * Streams every retained record through readSegments (TASK-006), groups by
+ * trace_id, and re-derives each TraceSummary from facts alone. Rebuild is
+ * recovery, not mutation: it writes nothing and is byte-deterministic over
+ * the same retained segments — read order is sealed-seq then active, and
+ * summaries are emitted sorted by trace_id.
+ *
+ * Coverage is the honest denominator: records read, untraced records,
+ * traces summarized, plus the reader's own gap counters (corrupt lines,
+ * partial tail bytes, quarantined/expired segments, degraded entries).
+ * A future schema_version never reaches this layer — the reader rejects it
+ * as a corrupt line and the gap shows up in coverage, never in a summary.
+ */
+
+import { readSegments } from '../segments/readSegments.js';
+import { summarizeTrace } from './summary.js';
+
+export async function rebuildIndex(root, opts = {}) {
+  const byTrace = new Map();
+  let recordsRead = 0;
+  let untraced = 0;
+
+  const stream = readSegments(root, opts);
+  for await (const record of stream) {
+    recordsRead += 1;
+    const traceId = typeof record.trace_id === 'string' && record.trace_id.length > 0
+      ? record.trace_id
+      : null;
+    if (traceId === null) {
+      untraced += 1;
+      continue;
+    }
+    const list = byTrace.get(traceId);
+    if (list) list.push(record);
+    else byTrace.set(traceId, [record]);
+  }
+
+  const summaries = [...byTrace.keys()]
+    .sort()
+    .map((traceId) => summarizeTrace(byTrace.get(traceId)));
+
+  return {
+    summaries,
+    coverage: {
+      records_read: recordsRead,
+      untraced_records: untraced,
+      traces: summaries.length,
+      ...stream.coverage,
+    },
+    ok: stream.ok,
+  };
+}

package/src/core/observability/analytics/summary.js

@@ -0,0 +1,298 @@
+/**
+ * summary.js (TASK-008, SPEC §5 DF-FR09 / §8) — deterministic trace analyzer.
+ *
+ *   summarizeTrace(records): TraceSummary
+ *
+ * Pure function over the retained facts of ONE trace. No IO, no clock, no
+ * randomness — the same records always produce a byte-identical summary.
+ *
+ * TraceSummary shape (SPEC §8):
+ *   { trace_id, spans[], durations{}, critical_path_ms, retries, drops,
+ *     cache{}, resource{}, telemetry_complete, coverage{}, metric_version }
+ *
+ * Rules that make this a flight recorder and not a dashboard:
+ *   - critical_path_ms is CAUSAL: a span contributes its own measured
+ *     duration_ms; children contribute the max single-branch path and the
+ *     wall-clock extent they span. Parallel branches are never summed.
+ *   - Percentiles are reported only when the sample can support them
+ *     (min n = ceil(1/(1-p/100)): p50→2, p95→20, p99→100). Below the
+ *     minimum the value is null — never a fabricated number.
+ *   - Missing host data stays unknown: resource totals are null when no
+ *     numeric value was reported; cache.hit_rate is null when no cache
+ *     records exist; telemetry_complete=false on any drop/gap/UNKNOWN.
+ */
+
+export const METRIC_VERSION = 'df-m1';
+
+const STARTED = new Set(['execution.started', 'tool.started', 'model.started']);
+const ENDED_STATUS = Object.freeze({
+  'execution.completed': 'completed',
+  'execution.failed': 'failed',
+  'execution.blocked': 'blocked',
+  'tool.completed': 'completed',
+  'tool.failed': 'failed',
+  'model.completed': 'completed',
+  'model.failed': 'failed',
+});
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function familyOf(semanticName) {
+  const dot = String(semanticName).indexOf('.');
+  return dot > 0 ? String(semanticName).slice(0, dot) : 'unknown';
+}
+
+/** Deterministic record order: causal clock first, then writer identity. */
+function compareRecords(a, b) {
+  const an = typeof a.monotonic_ns === 'number' ? a.monotonic_ns : Infinity;
+  const bn = typeof b.monotonic_ns === 'number' ? b.monotonic_ns : Infinity;
+  if (an !== bn) return an - bn;
+  const boot = String(a.boot_id).localeCompare(String(b.boot_id));
+  if (boot !== 0) return boot;
+  const writer = String(a.writer_id).localeCompare(String(b.writer_id));
+  if (writer !== 0) return writer;
+  if (a.sequence !== b.sequence) return a.sequence - b.sequence;
+  return String(a.record_id).localeCompare(String(b.record_id));
+}
+
+function compareSpans(a, b) {
+  const an = typeof a.start_ns === 'number' ? a.start_ns : Infinity;
+  const bn = typeof b.start_ns === 'number' ? b.start_ns : Infinity;
+  if (an !== bn) return an - bn;
+  return a.span_id.localeCompare(b.span_id);
+}
+
+/**
+ * Nearest-rank percentile with a minimum sample size. Below the minimum the
+ * percentile does not exist statistically — return null, never invent one.
+ */
+export function percentileOf(sorted, p) {
+  const minN = Math.ceil(1 / (1 - p / 100));
+  if (!Array.isArray(sorted) || sorted.length < minN) return null;
+  const idx = Math.min(sorted.length - 1, Math.ceil((p / 100) * sorted.length) - 1);
+  return sorted[Math.max(0, idx)];
+}
+
+function durationStats(values) {
+  const sorted = values.slice().sort((a, b) => a - b);
+  return {
+    count: sorted.length,
+    min: sorted.length ? sorted[0] : null,
+    max: sorted.length ? sorted[sorted.length - 1] : null,
+    p50: percentileOf(sorted, 50),
+    p95: percentileOf(sorted, 95),
+    p99: percentileOf(sorted, 99),
+  };
+}
+
+export function summarizeTrace(records) {
+  const input = Array.isArray(records) ? records.filter(isPlainObject) : [];
+  const ordered = input.slice().sort(compareRecords);
+
+  const traceIds = new Set();
+  const spansById = new Map();
+  const durationsByFamily = { execution: [], tool: [], model: [] };
+  const allDurations = [];
+
+  const drops = { events: 0, dropped_count: 0, by_reason: {}, redacted: 0, recovered: 0 };
+  const cache = { observed: false, hits: 0, misses: 0, hit_rate: null };
+  const resource = { total_value: null, numeric_count: 0, unknown_count: 0, sources: {} };
+  const retries = { model_attempts: 0, retries: 0, failed_spans: 0 };
+  const coverage = {
+    records: ordered.length,
+    records_with_trace: 0,
+    spans: 0,
+    open_spans: 0,
+    orphan_spans: 0,
+    duplicate_ends: 0,
+    trace_ids: 0,
+  };
+
+  let explicitIncomplete = false;
+
+  const spanFor = (spanId) => {
+    let span = spansById.get(spanId);
+    if (!span) {
+      span = {
+        span_id: spanId,
+        parent_span_id: null,
+        family: 'unknown',
+        operation: null,
+        status: 'open',
+        attempt_index: null,
+        start_ns: null,
+        end_ns: null,
+        duration_ms: null,
+        start_record_id: null,
+        end_record_id: null,
+      };
+      spansById.set(spanId, span);
+    }
+    return span;
+  };
+
+  for (const record of ordered) {
+    if (typeof record.trace_id === 'string' && record.trace_id.length > 0) {
+      traceIds.add(record.trace_id);
+      coverage.records_with_trace += 1;
+    }
+    const payload = isPlainObject(record.payload) ? record.payload : {};
+    const name = record.semantic_name;
+
+    if (payload.telemetry_complete === false) explicitIncomplete = true;
+
+    // Typed resource usage (DF-FR08): reported on completed/failed records
+    // only — counting started records would double-count the same attempt.
+    if (ENDED_STATUS[name] && isPlainObject(payload.resource)) {
+      const source = typeof payload.resource.source === 'string' ? payload.resource.source : 'UNKNOWN';
+      resource.sources[source] = (resource.sources[source] || 0) + 1;
+      if (typeof payload.resource.value === 'number' && Number.isFinite(payload.resource.value)) {
+        resource.numeric_count += 1;
+        resource.total_value = (resource.total_value || 0) + payload.resource.value;
+      } else {
+        resource.unknown_count += 1;
+      }
+    }
+
+    if (name === 'cache.hit') cache.hits += 1;
+    if (name === 'cache.miss') cache.misses += 1;
+    if (name === 'telemetry.dropped') {
+      drops.events += 1;
+      const count = typeof payload.dropped_count === 'number' ? payload.dropped_count : 1;
+      drops.dropped_count += count;
+      const reason = typeof payload.reason_code === 'string' ? payload.reason_code : 'UNSPECIFIED';
+      drops.by_reason[reason] = (drops.by_reason[reason] || 0) + count;
+    }
+    if (name === 'telemetry.redacted') drops.redacted += 1;
+    if (name === 'telemetry.recovered') drops.recovered += 1;
+
+    if (typeof record.span_id !== 'string' || record.span_id.length === 0) continue;
+
+    if (STARTED.has(name)) {
+      const span = spanFor(record.span_id);
+      span.family = familyOf(name);
+      if (typeof record.parent_span_id === 'string') span.parent_span_id = record.parent_span_id;
+      if (typeof record.monotonic_ns === 'number') span.start_ns = record.monotonic_ns;
+      if (typeof payload.operation === 'string') span.operation = payload.operation;
+      else if (typeof payload.tool === 'string') span.operation = payload.tool;
+      if (Number.isInteger(payload.attempt_index)) span.attempt_index = payload.attempt_index;
+      span.start_record_id = record.record_id;
+      if (span.family === 'model') retries.model_attempts += 1;
+    } else if (ENDED_STATUS[name]) {
+      const span = spanFor(record.span_id);
+      if (span.family === 'unknown') span.family = familyOf(name);
+      if (span.parent_span_id === null && typeof record.parent_span_id === 'string') {
+        span.parent_span_id = record.parent_span_id;
+      }
+      if (span.status !== 'open') coverage.duplicate_ends += 1;
+      else {
+        span.status = ENDED_STATUS[name];
+        if (typeof record.monotonic_ns === 'number') span.end_ns = record.monotonic_ns;
+        if (typeof payload.duration_ms === 'number' && Number.isFinite(payload.duration_ms)) {
+          span.duration_ms = payload.duration_ms;
+        }
+        if (span.attempt_index === null && Number.isInteger(payload.attempt_index)) {
+          span.attempt_index = payload.attempt_index;
+          if (span.family === 'model') retries.model_attempts += 1;
+        }
+        span.end_record_id = record.record_id;
+        if (span.status === 'failed') retries.failed_spans += 1;
+        if (span.duration_ms !== null) {
+          allDurations.push(span.duration_ms);
+          if (durationsByFamily[span.family]) durationsByFamily[span.family].push(span.duration_ms);
+        }
+      }
+    }
+  }
+
+  const spans = [...spansById.values()].sort(compareSpans);
+  coverage.spans = spans.length;
+  coverage.trace_ids = traceIds.size;
+
+  // Causality tree: a parent link that points nowhere is a typed gap.
+  const children = new Map();
+  const roots = [];
+  for (const span of spans) {
+    if (span.status === 'open') coverage.open_spans += 1;
+    if (typeof span.attempt_index === 'number' && span.attempt_index > 1) {
+      retries.retries += 1;
+    }
+    if (span.parent_span_id && spansById.has(span.parent_span_id)) {
+      const list = children.get(span.parent_span_id) || [];
+      list.push(span);
+      children.set(span.parent_span_id, list);
+    } else {
+      if (span.parent_span_id) coverage.orphan_spans += 1;
+      roots.push(span);
+    }
+  }
+
+  /**
+   * Causal critical path (DF-FR09): a node's path weight is the max of
+   *   - its own measured duration_ms (explicit only — never derived),
+   *   - the longest single child branch (parallel children → max, not sum),
+   *   - the wall-clock extent its children span (sequential children
+   *     accumulate through their measured intervals, gaps included).
+   * A span with no measured duration and no measured children contributes
+   * nothing — unknown stays unknown.
+   */
+  function criticalPath(span) {
+    const kids = children.get(span.span_id) || [];
+    let best = typeof span.duration_ms === 'number' ? span.duration_ms : null;
+    let minStart = Infinity;
+    let maxEnd = -Infinity;
+    for (const kid of kids) {
+      const kidPath = criticalPath(kid);
+      if (kidPath !== null && (best === null || kidPath > best)) best = kidPath;
+      if (typeof kid.start_ns === 'number' && typeof kid.end_ns === 'number') {
+        if (kid.start_ns < minStart) minStart = kid.start_ns;
+        if (kid.end_ns > maxEnd) maxEnd = kid.end_ns;
+      }
+    }
+    if (maxEnd >= minStart) {
+      const extent = (maxEnd - minStart) / 1e6;
+      if (best === null || extent > best) best = extent;
+    }
+    return best;
+  }
+
+  let critical_path_ms = null;
+  for (const root of roots) {
+    const path = criticalPath(root);
+    if (path !== null && (critical_path_ms === null || path > critical_path_ms)) {
+      critical_path_ms = path;
+    }
+  }
+
+  const lookups = cache.hits + cache.misses;
+  cache.observed = lookups > 0;
+  cache.hit_rate = lookups > 0 ? cache.hits / lookups : null;
+
+  const telemetry_complete =
+    !explicitIncomplete &&
+    drops.events === 0 &&
+    resource.unknown_count === 0 &&
+    coverage.open_spans === 0 &&
+    coverage.orphan_spans === 0;
+
+  return {
+    trace_id: traceIds.size ? [...traceIds].sort()[0] : null,
+    spans,
+    durations: {
+      overall: durationStats(allDurations),
+      execution: durationStats(durationsByFamily.execution),
+      tool: durationStats(durationsByFamily.tool),
+      model: durationStats(durationsByFamily.model),
+    },
+    critical_path_ms,
+    retries,
+    drops,
+    cache,
+    resource,
+    telemetry_complete,
+    coverage,
+    metric_version: METRIC_VERSION,
+  };
+}