@tangle-network/traces 0.23.1 → 1.0.0

package/dist/chunk-O52XK7OB.js

@@ -0,0 +1,19 @@
+// src/ask-defaults.ts
+var DEFAULT_ANALYST_MODEL = "gpt-5.6-luna";
+var DEFAULT_QUESTION_MAX_COST_USD = 2;
+var DEFAULT_QUESTION_TIMEOUT_MS = 18e5;
+var DEFAULT_ASK_CONCURRENCY = 4;
+var QUESTION_FIELD_MAX_CHARS = 900;
+var ASK_QUESTION_HEADER = "Answer QUESTION with the trace tools and follow TRACES ASK RULES in analyst_instructions. The trace list is JSON after PREPARED CONTEXT: there. Cite trace://<trace_id>/span/<span_id>.";
+var QUESTION_LABEL = "\n\nQUESTION: ";
+var MAX_TRACE_QUESTION_CHARS = QUESTION_FIELD_MAX_CHARS - ASK_QUESTION_HEADER.length - QUESTION_LABEL.length;
+
+export {
+  DEFAULT_ANALYST_MODEL,
+  DEFAULT_QUESTION_MAX_COST_USD,
+  DEFAULT_QUESTION_TIMEOUT_MS,
+  DEFAULT_ASK_CONCURRENCY,
+  ASK_QUESTION_HEADER,
+  QUESTION_LABEL,
+  MAX_TRACE_QUESTION_CHARS
+};

package/dist/chunk-PYH3PL3N.js

@@ -0,0 +1,62 @@
+// src/finding-rejections.ts
+var REJECTION_MESSAGE = /^(?:\[([^\]]+)\] )?finding rejected: (.+)$/;
+function findingRejection(message, fields) {
+  const match = REJECTION_MESSAGE.exec(message);
+  if (!match) return void 0;
+  const kind = match[2].trim();
+  const reason = kind === "unresolved evidence" && typeof fields?.reason === "string" && fields.reason ? fields.reason : kind;
+  return match[1] ? { analystId: match[1], reason } : { reason };
+}
+function rejectionCause(fields) {
+  if (typeof fields?.reason === "string" && fields.reason) return fields.reason;
+  const issues = fields?.issues;
+  if (typeof issues === "string" && issues) return issues;
+  if (Array.isArray(issues) && issues.length > 0) return issues.map((issue) => String(issue)).join("; ");
+  return void 0;
+}
+function findingRejectionDetail(message, fields) {
+  const rejection = findingRejection(message, fields);
+  if (!rejection) return void 0;
+  const lead = rejectionCause(fields) ?? rejection.reason;
+  const parts = message.endsWith(lead) ? [] : [lead];
+  if (typeof fields?.uri === "string" && fields.uri) parts.push(`uri ${fields.uri}`);
+  if (typeof fields?.required === "number" && typeof fields?.distinct === "number") {
+    parts.push(`${fields.distinct} of ${fields.required} required distinct citation(s)`);
+  }
+  if (typeof fields?.subject === "string" && fields.subject) parts.push(`subject ${fields.subject}`);
+  return parts.join("; ");
+}
+function createFindingRejectionTally(defaultAnalystId = "unknown") {
+  const byAnalyst = /* @__PURE__ */ new Map();
+  return {
+    record(message, fields) {
+      const rejection = findingRejection(message, fields);
+      if (!rejection) return;
+      const analystId = rejection.analystId ?? defaultAnalystId;
+      const reasons = byAnalyst.get(analystId) ?? /* @__PURE__ */ new Map();
+      reasons.set(rejection.reason, (reasons.get(rejection.reason) ?? 0) + 1);
+      byAnalyst.set(analystId, reasons);
+    },
+    counts() {
+      return Object.fromEntries(
+        [...byAnalyst].map(([analystId, reasons]) => [analystId, Object.fromEntries(reasons)])
+      );
+    }
+  };
+}
+function totalFindingRejections(reasons) {
+  return Object.values(reasons ?? {}).reduce((sum, count) => sum + count, 0);
+}
+function formatFindingRejections(reasons) {
+  const total = totalFindingRejections(reasons);
+  if (total === 0) return "";
+  const ordered = Object.entries(reasons ?? {}).filter(([, count]) => count > 0).sort(([a, left], [b, right]) => right - left || a.localeCompare(b)).map(([reason, count]) => `${reason} \xD7${count}`);
+  return `${total} finding(s) rejected: ${ordered.join("; ")}`;
+}
+
+export {
+  findingRejectionDetail,
+  createFindingRejectionTally,
+  totalFindingRejections,
+  formatFindingRejections
+};

package/dist/chunk-RZL5GAWH.js

@@ -0,0 +1,60 @@
+import {
+  normalizeToolIoAttributes,
+  stripSourceAttributes
+} from "./chunk-DU534HAX.js";
+
+// src/redact.ts
+import {
+  assessShareSafety,
+  combineVerdicts,
+  redact
+} from "@tangle-network/agent-eval/traces";
+function redactSpans(spans, options = {}) {
+  const parts = spans.map((span) => ({
+    name: span.name,
+    attributes: stripSourceAttributes(span.attributes),
+    message: span.status.message,
+    links: span.links?.map((link) => ({
+      ...link,
+      ...link.attributes ? { attributes: stripSourceAttributes(link.attributes) } : {}
+    }))
+  }));
+  const { value, report } = redact(parts, options);
+  const out = spans.map((span, index) => {
+    const part = value[index];
+    normalizeToolIoAttributes(part.attributes);
+    const status = part.message !== void 0 && part.message !== span.status.message ? { ...span.status, message: part.message } : span.status;
+    return {
+      ...span,
+      name: part.name,
+      attributes: part.attributes,
+      status,
+      ...part.links ? { links: part.links } : {}
+    };
+  });
+  return { spans: out, report };
+}
+function assessSpans(spans, profile = "default") {
+  return combineVerdicts(
+    profile,
+    spans.map((span) => {
+      const verdict = assessShareSafety(
+        { name: span.name, attributes: span.attributes, status: span.status, links: span.links },
+        { profile }
+      );
+      return {
+        ...verdict,
+        findings: verdict.findings.map((finding) => ({
+          ...finding,
+          paths: finding.paths.map((path) => `span:${span.span_id}${path}`)
+        })),
+        unreadable: verdict.unreadable.map((entry) => `span:${span.span_id}${entry}`)
+      };
+    })
+  );
+}
+
+export {
+  redactSpans,
+  assessSpans
+};

package/dist/chunk-TR6O4S4T.js

@@ -0,0 +1,208 @@
+import {
+  span
+} from "./chunk-NZ5Y7UEL.js";
+
+// src/attributes.ts
+var ATTR = {
+  /** = the trace/session id. Wire contract (dedup linkage). */
+  SESSION_ID: "tangle.sessionId",
+  /** "cli" marks a CLI upload so the platform can drop a re-upload of a session
+   *  that also streamed live. Wire contract. */
+  INGEST_SOURCE: "tangle.ingest_source",
+  HARNESS: "tangle.harness",
+  CWD: "tangle.cwd",
+  /** THE per-session grouping key the spine derives subjects from
+   *  (`deriveSubjectKey` reads `tangle.subject.key` first). Resolves to the git
+   *  remote (host/owner/repo) when readable, else the cwd path basename. */
+  SUBJECT_KEY: "tangle.subject.key",
+  /** Normalized git remote (e.g. `github.com/tangle-network/agent-container`). */
+  GIT_REPOSITORY: "git.repository",
+  /** Current branch at conversion time. */
+  GIT_BRANCH_NAME: "git.branch",
+  /** HEAD short sha at conversion time. */
+  GIT_COMMIT: "git.commit",
+  /** How traces resolved the session cwd: recorded cwd, repaired cwd, or span path. */
+  REPO_RESOLUTION_SOURCE: "traces.repo_resolution_source",
+  GIT_BRANCH: "tangle.git_branch",
+  HOST: "tangle.host",
+  /** Basename of the session file. (Renamed from the ambiguous `tangle.source`,
+   *  which collided with `tangle.ingest_source`.) */
+  SESSION_FILE: "tangle.session_file",
+  UPLOADED_AT: "tangle.uploaded_at",
+  UPLOADER: "tangle.uploader",
+  REDACTION_VERSION: "redaction.version",
+  REDACTION_COUNT: "redaction.count",
+  /** Upload contract: bounded root summary plus location-only receipt child spans.
+   *  Receipt hashes are deliberate integrity evidence; raw malformed bytes never upload. */
+  SESSION_INTEGRITY: "traces.session.integrity",
+  CORRUPTION_COUNT: "traces.session.corruption_count",
+  CORRUPTION_DIGEST: "traces.session.corruption_digest",
+  CORRUPTION_RECEIPT_VERSION: "traces.session.corruption.receipt_version",
+  CORRUPTION_RECEIPT_KIND: "traces.session.corruption.kind",
+  CORRUPTION_SOURCE_PATH: "traces.session.corruption.source_path",
+  CORRUPTION_LINE_NUMBER: "traces.session.corruption.line_number",
+  CORRUPTION_BYTE_OFFSET: "traces.session.corruption.byte_offset",
+  CORRUPTION_BYTE_LENGTH: "traces.session.corruption.byte_length",
+  CORRUPTION_SHA256: "traces.session.corruption.sha256",
+  RAW_SOURCE_RETENTION: "traces.session.raw_source_retention",
+  /** Container image reference the session executed in (OTel semconv key). */
+  CONTAINER_IMAGE: "container.image.name",
+  /** Immutable image digest (`sha256:…`) — the replay-grade environment pin. */
+  CONTAINER_IMAGE_DIGEST: "container.image.digest",
+  /** Sandbox/container instance id that executed the session. */
+  SANDBOX_ID: "tangle.sandbox.id",
+  /** Recorded execution cwd, verbatim. Unlike `tangle.cwd` it is never
+   *  repaired against the host filesystem — replay verification needs the
+   *  in-container path even when no such path exists on this host. */
+  ENVIRONMENT_CWD: "tangle.environment.cwd"
+};
+var SESSION_CWD_ATTR = "traces.session.cwd";
+var SESSION_TOTAL_TOKENS_ATTR = "traces.session.total_tokens";
+var SESSION_TOTAL_INPUT_ATTR = "traces.session.total_input_tokens";
+var SESSION_TOTAL_OUTPUT_ATTR = "traces.session.total_output_tokens";
+var SESSION_TOTAL_CACHED_INPUT_ATTR = "traces.session.total_cached_input_tokens";
+var SESSION_TOTAL_CACHE_WRITE_ATTR = "traces.session.total_cache_write_input_tokens";
+var SESSION_TOTAL_REASONING_ATTR = "traces.session.total_reasoning_tokens";
+var INGEST_SOURCE_CLI = "cli";
+function environmentAttributes(environment) {
+  if (!environment) return {};
+  const attrs = {};
+  if (environment.image) attrs[ATTR.CONTAINER_IMAGE] = environment.image;
+  if (environment.imageDigest) attrs[ATTR.CONTAINER_IMAGE_DIGEST] = environment.imageDigest;
+  if (environment.sandboxId) attrs[ATTR.SANDBOX_ID] = environment.sandboxId;
+  if (environment.cwd) attrs[ATTR.ENVIRONMENT_CWD] = environment.cwd;
+  if (environment.gitCommit) attrs[ATTR.GIT_COMMIT] = environment.gitCommit;
+  return attrs;
+}
+function stampEnvironmentAttrs(spans, environment) {
+  const attrs = environmentAttributes(environment);
+  const keys = Object.keys(attrs);
+  if (keys.length === 0) return;
+  for (const span2 of spans) {
+    for (const key of keys) {
+      if (span2.attributes[key] === void 0) span2.attributes[key] = attrs[key];
+    }
+  }
+}
+var SESSION_ID_ATTRIBUTE_KEYS = [ATTR.SESSION_ID, "session.id", "traces.session.id"];
+function sessionIdFromAttributes(attributes) {
+  return SESSION_ID_ATTRIBUTE_KEYS.map((key) => attributes[key]).find(
+    (value) => typeof value === "string" && value.length > 0
+  );
+}
+function indexSessionIdsByTrace(spans) {
+  const candidatesByTrace = /* @__PURE__ */ new Map();
+  for (const span2 of spans) {
+    const candidates = candidatesByTrace.get(span2.trace_id) ?? /* @__PURE__ */ new Set();
+    for (const key of SESSION_ID_ATTRIBUTE_KEYS) {
+      const value = span2.attributes[key];
+      if (typeof value === "string" && value.length > 0) candidates.add(value);
+    }
+    if (candidates.size > 0) candidatesByTrace.set(span2.trace_id, candidates);
+  }
+  const sessionByTrace = /* @__PURE__ */ new Map();
+  const conflicts = [];
+  for (const [traceId, candidates] of candidatesByTrace) {
+    const sessionIds = [...candidates].sort();
+    if (sessionIds.length === 1) {
+      sessionByTrace.set(traceId, sessionIds[0]);
+    } else {
+      conflicts.push({ traceId, sessionIds });
+    }
+  }
+  conflicts.sort((a, b) => a.traceId.localeCompare(b.traceId));
+  return { sessionByTrace, conflicts };
+}
+function stampSessionIdentity(spans, fallbackSessionId) {
+  const { sessionByTrace, conflicts } = indexSessionIdsByTrace(spans);
+  const conflictingTraceIds = new Set(conflicts.map((conflict) => conflict.traceId));
+  const traceIds = new Set(spans.map((span2) => span2.trace_id));
+  const singleTraceId = traceIds.size === 1 ? traceIds.values().next().value : void 0;
+  for (const span2 of spans) {
+    if (conflictingTraceIds.has(span2.trace_id)) continue;
+    const sessionId = sessionByTrace.get(span2.trace_id) ?? singleTraceId ?? fallbackSessionId;
+    if (!sessionIdFromAttributes(span2.attributes)) {
+      span2.attributes[ATTR.SESSION_ID] = sessionId;
+    }
+  }
+}
+
+// src/adapters/conversation.ts
+var CONTENT_CAP = 8e3;
+function capText(raw, limit = CONTENT_CAP) {
+  const t = raw.trim();
+  if (t.length <= limit) return t;
+  return `${t.slice(0, limit)}\u2026 [+${t.length - limit} chars]`;
+}
+var ACTOR_ATTR = "tangle.actor";
+function userPromptSpan(o) {
+  return span({
+    traceId: o.traceId,
+    spanId: o.spanId,
+    parentSpanId: o.parentSpanId,
+    name: "user.prompt",
+    kind: "CHAIN",
+    startTime: o.startTime,
+    service: o.service ?? null,
+    agent: o.agent ?? null,
+    step: o.step,
+    content: o.content,
+    contentSource: o.contentSource,
+    extra: { [ACTOR_ATTR]: o.actor ?? "human" }
+  });
+}
+
+// src/adapters/provenance.ts
+var SYNTHESIZED_SPAN_ATTR = "traces.span.synthesized";
+var SYNTHESIZED_SOURCE_ATTR = "traces.span.synthesized_from";
+var INHERITED_SPAN_ATTR = "traces.session.inherited";
+var INHERITED_SOURCE_ATTR = "traces.session.inherited_source";
+var INHERITED_SPAN_COUNT_ATTR = "traces.session.inherited_span_count";
+var INHERITED_SPANS_OMITTED_ATTR = "traces.session.inherited_spans_omitted";
+var SUBAGENT_SPAN_ATTR = "traces.span.subagent";
+var SUBAGENT_TASK_ATTR = "traces.span.subagent_task";
+var SUBAGENT_SPAN_COUNT_ATTR = "traces.session.subagent_span_count";
+var SUBAGENT_SPAWN_ATTR = "traces.agent.spawn";
+var SUBAGENT_SPAWN_TASK_ATTR = "traces.agent.spawn_task";
+function isSynthesizedSpan(attributes) {
+  return attributes[SYNTHESIZED_SPAN_ATTR] === true;
+}
+function isInheritedSpan(attributes) {
+  return attributes[INHERITED_SPAN_ATTR] === true;
+}
+function isSubagentSpan(attributes) {
+  return attributes[SUBAGENT_SPAN_ATTR] === true;
+}
+
+export {
+  ATTR,
+  SESSION_CWD_ATTR,
+  SESSION_TOTAL_TOKENS_ATTR,
+  SESSION_TOTAL_INPUT_ATTR,
+  SESSION_TOTAL_OUTPUT_ATTR,
+  SESSION_TOTAL_CACHED_INPUT_ATTR,
+  SESSION_TOTAL_CACHE_WRITE_ATTR,
+  SESSION_TOTAL_REASONING_ATTR,
+  INGEST_SOURCE_CLI,
+  stampEnvironmentAttrs,
+  sessionIdFromAttributes,
+  indexSessionIdsByTrace,
+  stampSessionIdentity,
+  capText,
+  ACTOR_ATTR,
+  userPromptSpan,
+  SYNTHESIZED_SPAN_ATTR,
+  SYNTHESIZED_SOURCE_ATTR,
+  INHERITED_SPAN_ATTR,
+  INHERITED_SOURCE_ATTR,
+  INHERITED_SPAN_COUNT_ATTR,
+  INHERITED_SPANS_OMITTED_ATTR,
+  SUBAGENT_SPAN_ATTR,
+  SUBAGENT_TASK_ATTR,
+  SUBAGENT_SPAN_COUNT_ATTR,
+  SUBAGENT_SPAWN_ATTR,
+  SUBAGENT_SPAWN_TASK_ATTR,
+  isSynthesizedSpan,
+  isInheritedSpan,
+  isSubagentSpan
+};

package/dist/chunk-TW43MR5D.js

@@ -0,0 +1,259 @@
+import {
+  TRACE_ID_MINTED_ATTR,
+  toOpenInferenceSpan
+} from "./chunk-NZ5Y7UEL.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
+};