@tangle-network/traces 0.15.5 → 0.16.0

package/README.md

@@ -23,6 +23,7 @@ Emitting the contract is the supported way to integrate a new system. The adapte
 
 - [Install](#install)
 - [Quick start](#quick-start)
+- [Gate CI on a trace contract](#gate-ci-on-a-trace-contract)
 - [Integrate your own system](#integrate-your-own-system)
 - [What it finds](#what-it-finds)
 - [Supported harnesses](#supported-harnesses)
@@ -64,6 +65,7 @@ Requires Node ≥ 22.
 traces validate spans.otlp.jsonl                  # what can this trace answer?
 traces analyze  --otlp spans.otlp.jsonl           # analyse it, no adapter involved
 traces analyze --harness claude-code --last 1     # or read a coding agent's own log
+traces check session.jsonl --contract contract.json # gate CI on the path the run took
 traces improve --harness claude-code --last 5 --dir .traces/improvement
 traces watch --all
 traces stream --all --mode findings
@@ -84,6 +86,48 @@ See [Trace analysts](#trace-analysts).
 It writes one typed result, one report, flattened evidence rows, and the canonical OTLP trace.
 Each finding already contains the claim, evidence, recommended action, confidence, and validation plan.
 
+## Gate CI on a trace contract
+
+Two runs can give the same answer while one of them calls a forbidden tool.
+An output check passes both; a trace contract fails the wrong one.
+
+```json
+{
+  "name": "refund-desk",
+  "run": { "requireCompleted": true, "maxDurationMs": 300000 },
+  "tools": { "required": ["Read"], "forbidden": ["Bash"], "allowed": ["Read", "Grep"], "maxCalls": 10, "enforced": true },
+  "retries": { "reads": ["Read", "Grep"] },
+  "llm": { "maxCalls": 10 }
+}
+```
+
+```bash
+claude -p "$TASK" --tools Read,Grep --strict-mcp-config --output-format stream-json --verbose > run.jsonl
+traces check run.jsonl --contract refund-desk.json --junit contract.xml
+```
+
+`tools.enforced` fails when the harness offered the model a tool the contract does not allow, which a flag such as `--tools` does not prove.
+Without `--strict-mcp-config`, the run above is also offered every MCP server the account or project configures.
+`retries` fails when a tool repeats a call with the same arguments and nothing proves the repeat is safe.
+
+The trace is `claude -p --output-format stream-json` output, a Claude Code or Codex session file, OTLP spans (a file or a directory), or trace evidence; `--format` names it when the file could be read as more than one.
+Only stream-json output records the offered tools and the run's own result.
+**A saved interactive session file carries no run status at all** (the `result` record above only exists in `-p` mode), so `run.requireCompleted`/`run.allowedStatuses` always fail on one — write a contract for a session file with no `run` key, like the `refund-desk` example above running against `run.jsonl`.
+Every rule prints `pass`, `fail`, `error`, or `skipped` (a rule of an alternative path that did not decide the result).
+
+| Exit | Meaning |
+|---|---|
+| 0 | Every rule passed. |
+| 1 | A rule failed. |
+| 2 | The contract is malformed or contradicts itself, or a rule could not be evaluated. |
+| 3 | The trace could not be read. |
+| 4 | The trace reference is ambiguous. |
+
+`--junit` writes one test case per rule, and GitHub annotations print under `GITHUB_ACTIONS=true` or `--annotations`.
+`traces check --contract <file> --explain` prints what each compiled rule checks and reads no trace.
+For a trace that does not pass, the verdict, the contract, its plain-language statement, and the redacted spans the violations cite go to `--evidence` (default `.traces/check`).
+The contract keys and rule semantics are in [agent-eval's trace-contract guide](https://github.com/tangle-network/agent-eval/blob/main/docs/trace-contracts.md).
+
 ## Integrate your own system
 
 No adapter, no plugin. Emit the span contract and point `--otlp` at the file.
@@ -253,6 +297,7 @@ traces facts --harness codex --session <id>        # the deterministic facts she
 traces diff  run-a.otlp.jsonl run-b.otlp.jsonl      # where two runs of one task first diverge
 traces mcp   --otlp spans.otlp.jsonl                # read-only trace tools for an MCP client
 traces analyze  --all --since 2026-06-18 --out report.md
+traces check   spans.otlp.jsonl --contract c.json --junit c.xml  # exit 0 pass, 1 fail, 2 bad contract, 3 unreadable, 4 ambiguous
 traces validate spans.otlp.jsonl                   # conformance; exit 1 only when it is not a trace
 traces validate results/sessions --out conformance.md  # a whole directory of exports
 traces analyze  --otlp spans.otlp.jsonl            # analyse foreign OTLP, no adapter
@@ -303,7 +348,11 @@ See [Replay verification](./docs/replay-verify.md) for setup, semantics, and hon
 | `--since <t>` | `upload`: window, `30m`/`2h`/`7d` or ISO (default 24h); `analyze`: ISO cutoff |
 | `--out <path>` | Write the report to a file |
 | `--dir <path>` | `improve`: write the full artifact pack to this directory; `ask`: write `answers.json` + `report.md` there |
-| `--otlp <file\|dir>` | **READ** OTLP-JSONL from any system, skipping the adapters; a directory reads the OTLP files under it (only `otlp/` when the producer made one) and names the JSONL that is not OTLP. `validate`, `analyze`, `investigate`, `improve`, `ask`, `stream` |
+| `--otlp <file\|dir>` | **READ** OTLP-JSONL from any system, skipping the adapters; a directory reads the OTLP files under it (only `otlp/` when the producer made one) and names the JSONL that is not OTLP. `validate`, `check`, `analyze`, `investigate`, `improve`, `ask`, `stream` |
+| `--contract <file>` | `check`: the declarative trace contract (JSON) |
+| `--junit <file>` | `check`: write JUnit XML, one test case per rule |
+| `--evidence <dir>` | `check`: where evidence for a trace that did not pass goes (default `.traces/check`) |
+| `--annotations` | `check`: print GitHub workflow annotations (on by default under `GITHUB_ACTIONS=true`) |
 | `--otlp-out <path>` | **WRITE** the OTLP artifact here (also evidence provenance / dry-run upload preview) |
 | `--format <kind>` | File `analyze`, `export`, or `stream`: `auto`, `policy-evidence`, `sandbox-events`, `openinference`, `intelligence-spans`, or `chat-trajectory` |
 | `--source-bundle <dir>` | `analyze` / `investigate` / `improve` / `ask`: read a retained full bundle and explicitly grant source-field reads |

package/dist/{chunk-RERVIGLH.js → chunk-G5KKIQZ6.js}

@@ -19483,6 +19483,7 @@ function formatVerdict(result) {
 
 export {
   SOURCE_ATTRIBUTE_PREFIX,
+  toolArgumentsFromAttributes,
   SYNTHESIZED_SPAN_ATTR,
   SYNTHESIZED_SOURCE_ATTR,
   INHERITED_SPAN_ATTR,

package/dist/cli.js

@@ -38,11 +38,13 @@ import {
   mergeTracesConfig,
   normalizeTraceQuestions,
   openAgenticTraceStore,
+  parseIsoToEpochMs,
   parseSession,
   parseSince,
   planUpload,
   primeAnalyzer,
   projectSessionBundle,
+  readJsonl,
   readOtlpInput,
   readSessionIndexFile,
   redactSpans,
@@ -63,6 +65,7 @@ import {
   serializeTraceStreamEvent,
   sessionReportSource,
   streamSessions,
+  toolArgumentsFromAttributes,
   totalAgenticFailureMessage,
   traceStreamEventsFromSpans,
   tracesVersion,
@@ -80,13 +83,13 @@ import {
   writeSessionIndexFile,
   writeTraceEvidenceExportFile,
   writeTraceQuestionsArtifacts
-} from "./chunk-RERVIGLH.js";
+} from "./chunk-G5KKIQZ6.js";
 
 // src/cli.ts
 import { readFileSync } from "fs";
-import { mkdir, mkdtemp, readFile, stat, writeFile } from "fs/promises";
+import { mkdir as mkdir2, mkdtemp, readFile as readFile2, stat, writeFile as writeFile2 } from "fs/promises";
 import { tmpdir } from "os";
-import { basename, join, resolve } from "path";
+import { basename, join as join2, resolve } from "path";
 import {
   parseCorpusFlag,
   renderVerifiedFindingsSection
@@ -152,6 +155,252 @@ async function serveTraceMcp(options) {
   }
 }
 
+// src/cli.ts
+import { explainTraceContract as explainTraceContract2 } from "@tangle-network/agent-eval";
+
+// src/check.ts
+import { mkdir, readFile, writeFile } from "fs/promises";
+import { join } from "path";
+import {
+  compileTraceContractSpec,
+  evaluateTraceContract,
+  explainTraceContract,
+  lintTraceContractSpec
+} from "@tangle-network/agent-eval";
+var CHECK_EXIT = Object.freeze({
+  pass: 0,
+  fail: 1,
+  /** The contract is malformed or contradicts itself, or a rule could not run. */
+  badContract: 2,
+  unreadable: 3,
+  ambiguous: 4
+});
+var AmbiguousTraceInputError = class extends Error {
+  name = "AmbiguousTraceInputError";
+};
+var ContractFileError = class extends Error {
+  name = "ContractFileError";
+};
+async function loadContract(path) {
+  let text;
+  try {
+    text = await readFile(path, "utf8");
+  } catch (error) {
+    throw new ContractFileError(`cannot read contract ${path}: ${errorText(error)}`);
+  }
+  let json;
+  try {
+    json = JSON.parse(text);
+  } catch (error) {
+    throw new ContractFileError(`contract ${path} is not JSON: ${errorText(error)}`);
+  }
+  try {
+    const findings = lintTraceContractSpec(json);
+    const errors = findings.filter((f) => f.level === "error");
+    if (errors.length > 0) {
+      throw new ContractFileError(
+        `contract ${path} contradicts itself:
+${errors.map((f) => `  ${f.path}: ${f.message} [${f.code}]`).join("\n")}`
+      );
+    }
+    return {
+      contract: compileTraceContractSpec(json),
+      warnings: findings.map((f) => `${f.path}: ${f.message} [${f.code}]`)
+    };
+  } catch (error) {
+    if (error instanceof ContractFileError) throw error;
+    throw new ContractFileError(`contract ${path}: ${errorText(error)}`);
+  }
+}
+var SNIFF_ROWS = 20;
+async function sniffCheckInput(path) {
+  const rows = [];
+  for await (const row of readJsonl(path)) {
+    rows.push(row);
+    if (rows.length >= SNIFF_ROWS) break;
+  }
+  const objects = rows.filter(isObject);
+  if (objects.length === 0) throw new Error(`${path} holds no JSON rows`);
+  const kinds = [];
+  if (objects.every((r) => typeof r.trace_id === "string" && typeof r.span_id === "string")) kinds.push("otlp");
+  if (objects.some((r) => (typeof r.sessionId === "string" || typeof r.session_id === "string") && typeof r.type === "string") && !objects.some(hasSpanId)) {
+    kinds.push("claude-code");
+  }
+  if (objects.some((r) => CODEX_LINE_TYPES.has(String(r.type)) && isObject(r.payload))) kinds.push("codex");
+  if (objects.every(isEvidenceRow)) kinds.push("evidence");
+  if (kinds.length === 1) return kinds[0];
+  if (kinds.length === 0) {
+    throw new Error(`${path} is not a trace this command reads (OTLP spans, a Claude Code or Codex session, or trace evidence)`);
+  }
+  throw new AmbiguousTraceInputError(
+    `${path} reads as ${kinds.join(" and ")}; pass --format ${kinds.join(" or --format ")}`
+  );
+}
+var CODEX_LINE_TYPES = /* @__PURE__ */ new Set(["session_meta", "response_item", "event_msg", "turn_context"]);
+function hasSpanId(row) {
+  return typeof row.span_id === "string";
+}
+function isEvidenceRow(row) {
+  if (hasSpanId(row)) return false;
+  if (row.kind === "traces.policy_evidence.session") return true;
+  if (Array.isArray(row.messages) || typeof row.role === "string" && "content" in row) return true;
+  return typeof row.trace_id === "string" && typeof row.name === "string" && isObject(row.attributes);
+}
+function contractSpansFromOtlp(spans) {
+  return spans.map((span) => {
+    const startedAt = epochMs(span.start_time);
+    const endedAt = epochMs(span.end_time);
+    const args = toolArgumentsFromAttributes(span.attributes);
+    const truncated = span.attributes["traces.input.truncated"] === true;
+    return {
+      spanId: span.span_id,
+      parentSpanId: span.parent_span_id,
+      name: span.name,
+      ...startedAt === void 0 ? {} : { startedAt },
+      ...endedAt === void 0 ? {} : { endedAt },
+      ...span.status.code === "ERROR" ? { status: "error" } : span.status.code === "OK" ? { status: "ok" } : {},
+      // A truncated argument capture is not the call's arguments.
+      ...args.argsCaptured && !truncated ? { args: args.args } : { argsCaptured: false },
+      attributes: span.attributes
+    };
+  });
+}
+function epochMs(value) {
+  try {
+    return parseIsoToEpochMs(value);
+  } catch {
+    return void 0;
+  }
+}
+function groupByTrace(spans) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const span of spans) {
+    const list = groups.get(span.trace_id) ?? [];
+    list.push(span);
+    groups.set(span.trace_id, list);
+  }
+  return [...groups].map(([traceId, list]) => ({ traceId, spans: list }));
+}
+async function runCheck(contract, spans, opts) {
+  const traces = [];
+  for (const group of groupByTrace(spans)) {
+    const verdict = evaluateTraceContract(contract, contractSpansFromOtlp(group.spans));
+    const check = { traceId: group.traceId, spanCount: group.spans.length, verdict };
+    if (verdict.status !== "pass") {
+      check.evidenceDir = await writeEvidence(opts.evidenceRoot, contract, group.traceId, group.spans, verdict);
+    }
+    traces.push(check);
+  }
+  const status = traces.some((t) => t.verdict.status === "error") ? "error" : traces.every((t) => t.verdict.status === "pass") ? "pass" : "fail";
+  const exitCode = status === "pass" ? CHECK_EXIT.pass : status === "fail" ? CHECK_EXIT.fail : CHECK_EXIT.badContract;
+  return { contract: contract.name, status, exitCode, traces };
+}
+async function writeEvidence(root, contract, traceId, spans, verdict) {
+  const dir = join(root, `${safeName(contract.name)}-${safeName(traceId).slice(0, 40)}`);
+  await mkdir(dir, { recursive: true });
+  const cited = new Set(verdict.violations.map((v) => v.spanId).filter((id) => id !== void 0));
+  const redacted = redactSpans(spans.filter((s) => cited.has(s.span_id)));
+  await writeFile(join(dir, "verdict.json"), `${JSON.stringify({ traceId, verdict }, null, 2)}
+`);
+  await writeFile(join(dir, "contract.json"), `${JSON.stringify(contract, null, 2)}
+`);
+  await writeFile(join(dir, "explain.txt"), `${explainTraceContract(contract)}
+`);
+  await writeFile(join(dir, "cited-spans.jsonl"), redacted.spans.map((s) => JSON.stringify(s)).join("\n") + (redacted.spans.length ? "\n" : ""));
+  return dir;
+}
+function safeName(value) {
+  return value.replace(/[^A-Za-z0-9._-]+/g, "_");
+}
+function ruleLines(verdict) {
+  const branchPassed = /* @__PURE__ */ new Map();
+  for (const e of verdict.ruleExecutions) {
+    if (e.alternative === void 0) continue;
+    branchPassed.set(e.alternative, (branchPassed.get(e.alternative) ?? true) && e.status === "pass");
+  }
+  const anyBranchPassed = [...branchPassed.values()].some(Boolean);
+  return verdict.ruleExecutions.map((e) => {
+    const rule = e.alternative ? `${e.alternative}/${e.rule}` : e.rule;
+    const status = e.alternative && anyBranchPassed && !branchPassed.get(e.alternative) ? "skipped" : e.status;
+    return {
+      rule,
+      status,
+      ...e.error === void 0 ? {} : { error: e.error },
+      details: verdict.violations.filter((x) => x.rule === rule).map((x) => x.detail)
+    };
+  });
+}
+function renderCheckText(report) {
+  const lines = [];
+  for (const t of report.traces) {
+    const v = t.verdict;
+    lines.push(`${v.status.toUpperCase()}  contract ${report.contract}  trace ${t.traceId}  (${t.spanCount} spans, ${v.notes})`);
+    for (const r of ruleLines(v)) {
+      lines.push(`  ${r.status.padEnd(7)} ${r.rule}${r.error ? `  ${r.error}` : ""}`);
+      if (r.status === "fail") for (const detail of r.details.slice(0, 5)) lines.push(`          ${detail}`);
+    }
+    if (t.evidenceDir) lines.push(`  evidence \u2192 ${t.evidenceDir}`);
+  }
+  return lines.join("\n");
+}
+function renderJUnit(report) {
+  const suites = report.traces.map((t) => {
+    const rules = ruleLines(t.verdict);
+    const count = (status) => rules.filter((r) => r.status === status).length;
+    const cases = rules.map((r) => {
+      const open = `    <testcase classname="${xml(report.contract)}" name="${xml(r.rule)}">`;
+      if (r.status === "pass") return `${open}</testcase>`;
+      if (r.status === "skipped") return `${open}
+      <skipped message="another alternative passed"/>
+    </testcase>`;
+      if (r.status === "error") {
+        return `${open}
+      <error message="${xml(r.error ?? "rule could not be evaluated")}"/>
+    </testcase>`;
+      }
+      return `${open}
+      <failure message="${xml(r.details[0] ?? "rule failed")}">${xml(r.details.join("\n"))}</failure>
+    </testcase>`;
+    });
+    return [
+      `  <testsuite name="${xml(`${report.contract} @ ${t.traceId}`)}" tests="${rules.length}" failures="${count("fail")}" errors="${count("error")}" skipped="${count("skipped")}">`,
+      ...cases,
+      "  </testsuite>"
+    ].join("\n");
+  });
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<testsuites name="traces check">
+${suites.join("\n")}
+</testsuites>
+`;
+}
+function renderGithubAnnotations(report) {
+  const lines = [];
+  for (const t of report.traces) {
+    for (const r of ruleLines(t.verdict)) {
+      if (r.status === "pass" || r.status === "skipped") continue;
+      const detail = r.status === "error" ? `could not be evaluated: ${r.error ?? "unknown"}` : r.details.join("\n");
+      lines.push(`::error title=${ghProperty(`${report.contract}: ${r.rule}`)}::${ghData(`trace ${t.traceId}: ${detail}`)}`);
+    }
+  }
+  return lines.join("\n");
+}
+function xml(value) {
+  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F]/g, "");
+}
+function ghData(value) {
+  return value.replace(/%/g, "%25").replace(/\r/g, "%0D").replace(/\n/g, "%0A");
+}
+function ghProperty(value) {
+  return ghData(value).replace(/:/g, "%3A").replace(/,/g, "%2C");
+}
+function isObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function errorText(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
 // src/cli.ts
 function parseArgs(argv) {
   const a = {
@@ -182,7 +431,9 @@ function parseArgs(argv) {
     concurrency: 4,
     verifyFindings: false,
     replayCorpora: [],
-    questions: []
+    questions: [],
+    annotations: false,
+    explain: false
   };
   for (let i = 1; i < argv.length; i++) {
     const arg = argv[i];
@@ -339,6 +590,21 @@ function parseArgs(argv) {
       case "--format":
         a.format = next();
         break;
+      case "--contract":
+        a.contract = next();
+        break;
+      case "--junit":
+        a.junit = next();
+        break;
+      case "--evidence":
+        a.evidence = next();
+        break;
+      case "--annotations":
+        a.annotations = true;
+        break;
+      case "--explain":
+        a.explain = true;
+        break;
       case "--help":
       case "-h":
         a.help = true;
@@ -355,7 +621,17 @@ function parseArgs(argv) {
   }
   return a;
 }
-var OTLP_INPUT_COMMANDS = /* @__PURE__ */ new Set(["analyze", "facts", "investigate", "improve", "ask", "stream", "validate", "mcp"]);
+var OTLP_INPUT_COMMANDS = /* @__PURE__ */ new Set([
+  "analyze",
+  "check",
+  "facts",
+  "investigate",
+  "improve",
+  "ask",
+  "stream",
+  "validate",
+  "mcp"
+]);
 function validateOtlpSelection(args) {
   if (args.otlp === void 0) return args;
   if (!OTLP_INPUT_COMMANDS.has(args.command)) {
@@ -499,7 +775,7 @@ async function resolveSelectedSession(args) {
       `no ${args.all ? "selected" : adapter.harness} session with ID "${args.session}"; run \`traces list\` to select an ID, or pass an explicit session path`
     );
   }
-  throw new Error(
+  throw new AmbiguousTraceInputError(
     `session ID "${args.session}" is ambiguous across ${matches.length} files; select one harness or pass its explicit session path`
   );
 }
@@ -582,7 +858,7 @@ async function collectSpans(args) {
     for (const output of [args.out, args.dir, args.otlpOut]) {
       if (output) await assertOutsideSourceBundle(args.sourceBundle, output);
     }
-    return collectOtlpSpans(join(args.sourceBundle, "derived", "trace.otlp.jsonl"));
+    return collectOtlpSpans(join2(args.sourceBundle, "derived", "trace.otlp.jsonl"));
   }
   if (args.otlp) return collectOtlpSpans(args.otlp);
   if (args.input) {
@@ -634,6 +910,62 @@ async function cmdValidate(args) {
   }
   process.exitCode = validationExitCode(validation);
 }
+var EVIDENCE_FORMATS = /* @__PURE__ */ new Set(["policy-evidence", "sandbox-events", "openinference", "intelligence-spans", "chat-trajectory"]);
+async function checkInputArgs(args) {
+  if (!args.input) return args;
+  if (args.otlp || args.session) throw new Error("name the trace once: a positional path, --otlp, or --session");
+  const info = await stat(args.input);
+  let kind;
+  if (args.format && EVIDENCE_FORMATS.has(args.format)) kind = "evidence";
+  else if (args.format === "otlp" || args.format === "claude-code" || args.format === "codex") kind = args.format;
+  else if (args.format) throw new Error(`unknown --format "${args.format}" (otlp, claude-code, codex, or an evidence format)`);
+  else kind = info.isDirectory() ? "otlp" : await sniffCheckInput(args.input);
+  if (kind === "otlp") return { ...args, otlp: args.input, input: void 0 };
+  if (kind === "evidence") return args;
+  return { ...args, harness: kind, harnessExplicit: true, session: args.input, input: void 0 };
+}
+async function cmdCheck(args) {
+  if (!args.contract) {
+    process.stderr.write("error: check needs --contract <contract.json>\n");
+    process.exitCode = CHECK_EXIT.badContract;
+    return;
+  }
+  let loaded;
+  try {
+    loaded = await loadContract(args.contract);
+  } catch (error) {
+    process.stderr.write(`error: ${error instanceof Error ? error.message : String(error)}
+`);
+    process.exitCode = CHECK_EXIT.badContract;
+    return;
+  }
+  for (const warning of loaded.warnings) process.stderr.write(`warning: ${warning}
+`);
+  if (args.explain) {
+    console.log(explainTraceContract2(loaded.contract));
+    return;
+  }
+  let spans;
+  try {
+    spans = (await collectSpans(await checkInputArgs(args))).spans;
+    if (spans.length === 0) throw new Error("the trace holds no spans");
+  } catch (error) {
+    process.stderr.write(`error: ${error instanceof Error ? error.message : String(error)}
+`);
+    process.exitCode = error instanceof AmbiguousTraceInputError ? CHECK_EXIT.ambiguous : CHECK_EXIT.unreadable;
+    return;
+  }
+  const report = await runCheck(loaded.contract, spans, { evidenceRoot: args.evidence ?? join2(".traces", "check") });
+  console.log(renderCheckText(report));
+  if (args.junit) await writeFile2(args.junit, renderJUnit(report), "utf8");
+  if (args.out) await writeFile2(args.out, `${JSON.stringify(report, null, 2)}
+`, "utf8");
+  if (args.annotations || process.env.GITHUB_ACTIONS === "true") {
+    const annotations = renderGithubAnnotations(report);
+    if (annotations) console.log(annotations);
+  }
+  process.exitCode = report.exitCode;
+}
 async function cmdConvert(args) {
   const { spans, workflow } = await collectSpans(args);
   if (spans.length === 0) throw new Error("no spans found for the given selection");
@@ -872,7 +1204,7 @@ async function cmdFacts(args) {
   const rendered = format === "json" ? `${JSON.stringify(report, null, 2)}
 ` : renderSessionFacts(report);
   if (args.out) {
-    await writeFile(args.out, rendered, "utf8");
+    await writeFile2(args.out, rendered, "utf8");
     console.log(`session facts \u2192 ${args.out}  (${report.sessions.length} session(s), $0, no model call)`);
     return;
   }
@@ -968,7 +1300,7 @@ function parseAttributeValue(raw) {
 async function loadExportAttributes(args) {
   const attributes = {};
   if (args.metadata) {
-    const parsed = JSON.parse(await readFile(args.metadata, "utf8"));
+    const parsed = JSON.parse(await readFile2(args.metadata, "utf8"));
     if (parsed == null || typeof parsed !== "object" || Array.isArray(parsed)) {
       throw new Error("--metadata must point to a JSON object");
     }
@@ -1193,8 +1525,8 @@ async function cmdAsk(args) {
   const collected = await collectSpans(args);
   if (collected.spans.length === 0) throw new Error("no spans found for the given selection");
   warnIncompleteWorkflow(collected.workflow);
-  const directory = resolve(args.dir ?? await mkdtemp(join(tmpdir(), "traces-ask-")));
-  await mkdir(directory, { recursive: true });
+  const directory = resolve(args.dir ?? await mkdtemp(join2(tmpdir(), "traces-ask-")));
+  await mkdir2(directory, { recursive: true });
   const controller = new AbortController();
   const interrupt = () => controller.abort(new Error("ask interrupted"));
   process.once("SIGINT", interrupt);
@@ -1208,7 +1540,7 @@ async function cmdAsk(args) {
       concurrency: args.concurrency,
       ...args.budget !== void 0 ? { budgetUsd: args.budget } : {},
       ...args.sourceBundle ? { sourceBundle: { path: args.sourceBundle } } : {},
-      otlpOutPath: args.otlpOut ?? join(directory, "traces.otlp.jsonl"),
+      otlpOutPath: args.otlpOut ?? join2(directory, "traces.otlp.jsonl"),
       signal: controller.signal,
       log: analystLog
     });
@@ -1622,6 +1954,14 @@ Two ways in:
 
 Commands:
   validate  Report what a trace can and cannot answer (exit 1 on error findings)
+  check     Gate a run on a trace contract: check <trace> --contract <file.json>
+            [--junit out.xml] [--out report.json] [--evidence dir] [--annotations].
+            check --contract <file.json> --explain prints what the contract checks.
+            <trace> is claude -p stream-json output, OTLP spans (file or dir),
+            a Claude Code or Codex session file, or trace evidence; --format
+            names it when the sniff cannot.
+            Exit 0 pass, 1 fail, 2 bad contract or a rule could not run,
+            3 unreadable trace, 4 ambiguous trace reference
   list      List discovered sessions
   analyze   Run analyst suite + loop/waste pipelines over OTLP (--otlp), sessions,
             or an input file; names every analysis the spans could not support
@@ -1852,6 +2192,9 @@ async function main() {
     case "validate":
       await cmdValidate(args);
       break;
+    case "check":
+      await cmdCheck(args);
+      break;
     case "investigate":
       await cmdInvestigate(args);
       break;
@@ -1904,5 +2247,5 @@ async function main() {
 main().catch((err) => {
   process.stderr.write(`error: ${err instanceof Error ? err.message : String(err)}
 `);
-  process.exitCode = 1;
+  process.exitCode = process.argv[2] === "check" ? CHECK_EXIT.badContract : 1;
 });

package/dist/index.js

@@ -267,7 +267,7 @@ import {
   writeTraceQuestionsArtifacts,
   zaiChatCaller,
   zeroPricedCost
-} from "./chunk-RERVIGLH.js";
+} from "./chunk-G5KKIQZ6.js";
 
 // src/collect.ts
 async function collectSessions(opts = {}) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/traces",
-  "version": "0.15.5",
+  "version": "0.16.0",
   "description": "Point it at your coding-agent session traces (Claude Code, Codex, OpenCode, Gemini, Pi, …) and get failure-mode + efficiency findings. CLI + SDK over the @tangle-network/agent-eval analyst suite — observe live sessions, run your own analysts, redact, and upload to the Tangle Intelligence Platform.",
   "type": "module",
   "license": "MIT",
@@ -57,6 +57,7 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
+    "verify:contracts-corpus": "tsx tests/contracts-corpus/verify.mjs",
     "prepublishOnly": "pnpm check:source && pnpm build && pnpm check:package"
   },
   "dependencies": {