@tangle-network/traces 0.23.1 → 1.0.1

package/dist/chunk-YAX72TST.js

@@ -0,0 +1,259 @@
+import {
+  TRACE_ID_MINTED_ATTR,
+  toOpenInferenceSpan
+} from "./chunk-CQ6UYZG6.js";
+
+// src/conformance.ts
+import {
+  validateTraceSpans
+} from "@tangle-network/agent-trace-contract";
+var SPAN_ID_SAMPLE = 5;
+var ISSUE_SAMPLE = 10;
+var SEVERITY_BADGE = {
+  error: "\u{1F534} ERROR",
+  warn: "\u{1F7E0} WARN",
+  info: "\u2139\uFE0F  INFO"
+};
+var CAPABILITY_ANALYSES = {
+  "token-accounting": "execution facts \u2192 Direct model usage (input/output/reasoning/cache token totals)",
+  "cost-attribution": "execution facts \u2192 Cost coverage (observed vs estimated USD)",
+  "tool-usage": "tool-usage table + per-tool duplicate/retry/error rates + stuck-loop detection",
+  "loop-convergence": "round-over-round convergence (did round N+1 improve on N)",
+  "tree-comparison": "arm-vs-arm comparison: `traces diff <file>#branch=<a> <file>#branch=<b>` marks where two arms first diverge",
+  "steering-chain": "steering chain (which verdict caused which retry)",
+  "latency-analysis": "latency + critical-path timing distributions"
+};
+function summarizeSpanStructure(spans) {
+  const ids = new Set(spans.map((span) => JSON.stringify([span.trace_id, span.span_id])));
+  const rootsByTrace = /* @__PURE__ */ new Map();
+  let rootless = 0;
+  let orphans = 0;
+  let links = 0;
+  for (const span of spans) {
+    links += span.links?.length ?? 0;
+    if (!rootsByTrace.has(span.trace_id)) rootsByTrace.set(span.trace_id, 0);
+    if (span.parent_span_id === null) {
+      rootless += 1;
+      rootsByTrace.set(span.trace_id, (rootsByTrace.get(span.trace_id) ?? 0) + 1);
+    } else if (!ids.has(JSON.stringify([span.trace_id, span.parent_span_id]))) orphans += 1;
+  }
+  let extraRoots = 0;
+  let tracesWithoutRoot = 0;
+  for (const roots of rootsByTrace.values()) {
+    if (roots === 0) tracesWithoutRoot += 1;
+    else extraRoots += roots - 1;
+  }
+  return {
+    spans: spans.length,
+    traces: rootsByTrace.size,
+    rootless,
+    extraRoots,
+    tracesWithoutRoot,
+    orphans,
+    links
+  };
+}
+function renderStructure(lines, structure) {
+  const share = structure.spans === 0 ? 0 : structure.rootless / structure.spans * 100;
+  lines.push(
+    `**Span structure:** ${structure.spans} spans across ${structure.traces} trace(s); ${structure.rootless}/${structure.spans} (${share.toFixed(1)}%) carry no parent edge (${structure.traces} of those are the trace roots); ${structure.orphans} name a parent absent from the export; ${structure.links} causal link(s).`
+  );
+  lines.push("");
+  if (structure.extraRoots === structure.spans - structure.traces && structure.extraRoots > 0) {
+    lines.push(
+      "> Every span is its own root. Nothing rolls up: there is no run, round or session to attribute cost, tokens or outcomes to, only a list of events."
+    );
+    lines.push("");
+  } else if (structure.extraRoots > 0) {
+    lines.push(
+      `> ${structure.extraRoots} span(s) attribute to nothing: beyond the one root each trace is entitled to, their model calls, tool calls and verdicts roll up to no enclosing unit of work, so only the ${structure.spans - structure.extraRoots} attached span(s) can be charged to the run that caused them.`
+    );
+    lines.push("");
+  }
+  if (structure.tracesWithoutRoot > 0) {
+    lines.push(
+      `> ${structure.tracesWithoutRoot} trace(s) have no root at all: every span names a parent, and the top of the tree is absent from the export, so nothing in them can be charged to a run.`
+    );
+    lines.push("");
+  }
+  if (structure.links === 0) {
+    lines.push(
+      "> No causal links. Containment (`parent_span_id`) was recorded; causality (round N's verdict CAUSING round N+1) was not, so a steering or retry chain cannot be followed."
+    );
+    lines.push("");
+  }
+}
+function conformanceOfSpans(spans) {
+  return validateTraceSpans(spans.map(toOpenInferenceSpan));
+}
+function skippedAnalyses(validation) {
+  return validation.capabilities.filter((capability) => !capability.available).map((capability) => ({
+    capability: capability.name,
+    analysis: CAPABILITY_ANALYSES[capability.name] ?? "analyses keyed off this capability",
+    reason: capability.reason ?? "no reason recorded"
+  }));
+}
+function tableCell(value) {
+  return value.replace(/\s+/g, " ").replaceAll("|", "\\|").trim();
+}
+function spanIdSample(finding) {
+  const ids = finding.spanIds ?? [];
+  if (ids.length === 0) return "";
+  const shown = ids.slice(0, SPAN_ID_SAMPLE).map((id) => `\`${tableCell(id)}\``).join(", ");
+  return ids.length > SPAN_ID_SAMPLE ? `${shown} +${ids.length - SPAN_ID_SAMPLE} more` : shown;
+}
+function capabilityRow(capability) {
+  const analysis = CAPABILITY_ANALYSES[capability.name] ?? "\u2014";
+  return capability.available ? `| \`${capability.name}\` | \u2705 available | ${tableCell(analysis)} | \u2014 |` : `| \`${capability.name}\` | \u274C unavailable | ${tableCell(analysis)} | ${tableCell(capability.reason ?? "no reason recorded")} |`;
+}
+function renderInheritedLoss(lines, unreadable) {
+  if (unreadable === void 0 || unreadable.inherited === 0) return;
+  lines.push(
+    `**${unreadable.inherited} row(s) of the ORIGINAL source are not in this file.** It is a re-export: ${unreadable.kinds.join(", ")} row(s) could not be represented as spans and were left behind by an earlier hop, so nothing below is a finding about them. The findings here describe what survived, and this file is NOT a substitute for validating the source.`
+  );
+  lines.push("");
+}
+function renderMintedFields(lines, spans) {
+  const minted = spans?.filter((span) => span.attributes[TRACE_ID_MINTED_ATTR] === true) ?? [];
+  if (minted.length === 0) return;
+  const ids = [...new Set(minted.map((span) => span.trace_id))];
+  lines.push(
+    `**${minted.length} span(s) carry a trace_id this tool minted** (${ids.slice(0, 3).map((id) => `\`${tableCell(id)}\``).join(", ")}${ids.length > 3 ? `, +${ids.length - 3} more` : ""}): their producer wrote none, and a file whose rows carry no trace id cannot be read back at all. So \`missing-trace-id\` is NOT reported below even though the source earns it \u2014 the minted id is recorded per span under \`traces.raw_attribute.trace_id\` / \`traces.substituted_fields\`, and this file is NOT a substitute for validating the source.`
+  );
+  lines.push("");
+}
+function renderIngest(lines, files, skipped, issues, withheld) {
+  if (files && files.length > 0) {
+    const rows = files.reduce((total, file) => total + file.rows, 0);
+    const spans = files.reduce((total, file) => total + file.spans, 0);
+    const repeats = files.reduce((total, file) => total + file.repeats, 0);
+    lines.push(
+      `**Ingested:** ${spans} span(s) from ${rows} row(s) across ${files.length} OTLP file(s)` + (repeats > 0 ? `; ${repeats} row(s) re-declared a span already read, identically.` : ".")
+    );
+    lines.push("");
+    lines.push("| File | Rows | Spans | Identical repeats |");
+    lines.push("|---|---:|---:|---:|");
+    for (const file of files) {
+      lines.push(`| \`${tableCell(file.path)}\` | ${file.rows} | ${file.spans} | ${file.repeats} |`);
+    }
+    lines.push("");
+    if (repeats > 0) {
+      lines.push(
+        "> Identical repeats are not a defect. A multi-shot run writes one file per shot and each file re-declares the run and cell spans it hangs under, so every file is analysable on its own; reading them together collapses those back to one span. Only a repeat with DIFFERENT content is reported as a problem."
+      );
+      lines.push("");
+    }
+  }
+  if (skipped && skipped.length > 0) {
+    lines.push(
+      `**${skipped.length} JSONL file(s) in this directory are not OTLP** and were not read. Their lines are not counted above and produce no findings: they were never claimed to be spans.`
+    );
+    lines.push("");
+    lines.push("| File | What it holds |");
+    lines.push("|---|---|");
+    for (const file of skipped.slice(0, ISSUE_SAMPLE)) {
+      lines.push(`| \`${tableCell(file.path)}\` | ${tableCell(file.reason)} |`);
+    }
+    if (skipped.length > ISSUE_SAMPLE) {
+      lines.push(`| ... | ${skipped.length - ISSUE_SAMPLE} more omitted |`);
+    }
+    lines.push("");
+  }
+  if (issues && issues.length > 0) {
+    lines.push(
+      `**${issues.length} row(s) could not be analysed.** They are excluded from every count above rather than repaired, because a synthesized timestamp or id would put invented work into the totals.`
+    );
+    lines.push("");
+    lines.push("| Reason | File | Line | Detail |");
+    lines.push("|---|---|---:|---|");
+    for (const issue of issues.slice(0, ISSUE_SAMPLE)) {
+      lines.push(`| ${issue.kind} | \`${tableCell(issue.file)}\` | ${issue.line} | ${tableCell(issue.detail)} |`);
+    }
+    if (issues.length > ISSUE_SAMPLE) {
+      lines.push(`| ... | ${issues.length - ISSUE_SAMPLE} more omitted | - | - |`);
+    }
+    lines.push("");
+  }
+  if (withheld && withheld.length > 0) {
+    lines.push(
+      `**${withheld.length} span(s) were analysed with one field withheld.** They ARE counted above and in every table that does not read the named field: a span with an unusable timestamp still has a real identity, name, tool and status, and dropping it would delete real work from every total to avoid one wrong number. The field itself is withheld, never repaired.`
+    );
+    lines.push("");
+    lines.push("| Reason | Field | File | Line | Detail |");
+    lines.push("|---|---|---|---:|---|");
+    for (const entry of withheld.slice(0, ISSUE_SAMPLE)) {
+      lines.push(
+        `| ${entry.kind} | \`${tableCell(entry.field)}\` | \`${tableCell(entry.file)}\` | ${entry.line} | ${tableCell(entry.detail)} |`
+      );
+    }
+    if (withheld.length > ISSUE_SAMPLE) {
+      lines.push(`| ... | - | ${withheld.length - ISSUE_SAMPLE} more omitted | - | - |`);
+    }
+    lines.push("");
+  }
+}
+function conformanceBody(validation, opts) {
+  const heading = "#".repeat(opts.headingLevel ?? 2);
+  const lines = [];
+  const errors = validation.findings.filter((finding) => finding.severity === "error").length;
+  const warnings = validation.findings.filter((finding) => finding.severity === "warn").length;
+  const infos = validation.findings.filter((finding) => finding.severity === "info").length;
+  const unavailable = validation.capabilities.filter((capability) => !capability.available);
+  lines.push(
+    `${errors} error, ${warnings} warn, ${infos} info finding(s); ${validation.capabilities.length - unavailable.length}/${validation.capabilities.length} analysis capabilities available.`
+  );
+  lines.push("");
+  renderInheritedLoss(lines, opts.unreadable);
+  renderMintedFields(lines, opts.spans);
+  renderIngest(lines, opts.files, opts.skipped, opts.issues, opts.withheld);
+  if (opts.spans && opts.spans.length > 0) renderStructure(lines, summarizeSpanStructure(opts.spans));
+  if (validation.findings.length > 0) {
+    lines.push("| Severity | Code | Consequence | Blocks | Spans |");
+    lines.push("|---|---|---|---|---|");
+    for (const finding of validation.findings) {
+      const badge = SEVERITY_BADGE[finding.severity] ?? finding.severity;
+      const blocks = finding.blocks?.length ? finding.blocks.map((name) => `\`${name}\``).join(", ") : "\u2014";
+      lines.push(
+        `| ${badge} | \`${tableCell(finding.code)}\` | ${tableCell(finding.message)} | ${blocks} | ${spanIdSample(finding) || "\u2014"} |`
+      );
+    }
+    lines.push("");
+  } else {
+    lines.push("No conformance findings: the spans carry every field this analysis reads.");
+    lines.push("");
+  }
+  lines.push("| Capability | State | Analysis it drives | Why not |");
+  lines.push("|---|---|---|---|");
+  for (const capability of validation.capabilities) lines.push(capabilityRow(capability));
+  lines.push("");
+  const skipped = skippedAnalyses(validation);
+  if (skipped.length > 0) {
+    lines.push(`${heading}# analyses skipped, and why`);
+    lines.push("");
+    lines.push(
+      "These reported nothing because the trace never carried what they read \u2014 not because the run was uneventful. Every section they feed is marked at the table, not only here."
+    );
+    lines.push("");
+    for (const entry of skipped) {
+      lines.push(`- **${entry.analysis}** \u2014 skipped: ${entry.reason} (\`${entry.capability}\`).`);
+    }
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+function renderValidation(validation, opts) {
+  const errors = validation.findings.filter((finding) => finding.severity === "error");
+  const available = validation.capabilities.filter((capability) => capability.available);
+  const verdict = !validation.ok ? `NOT A TRACE \u2014 ${errors.length} error finding(s): not one entry in this export could be read as a span, so there is nothing to analyse and every capability below is unavailable. An empty export and one whose every line was unreadable both land here. This is the only state that exits non-zero.` : available.length === 0 ? `ANALYSABLE, WITH NOTHING TO ANALYSE \u2014 spans WERE read, so this is a trace, but 0/${validation.capabilities.length} capabilities are available: every analysis this package runs reads a field none of these spans carry. The rows below name what each one is missing. Exits 0, because the export is readable \u2014 a caller deciding whether to spend a run should read the capability table, not the exit code.` : "CONFORMS \u2014 analysable. Every finding below is a degradation of a readable trace, not a bar to reading it; each one names the capability it costs.";
+  return `# trace conformance \u2014 ${opts.subject}
+
+**${verdict}**
+
+${conformanceBody(validation, { ...opts, headingLevel: 2 })}`;
+}
+
+export {
+  conformanceOfSpans,
+  skippedAnalyses,
+  renderValidation
+};