@tangle-network/traces 0.23.0 → 1.0.0

package/dist/chunk-B62DOFGI.js

@@ -0,0 +1,273 @@
+import {
+  isMetadataAttribute,
+  metadataOnly
+} from "./chunk-V2OCGX57.js";
+import {
+  scanSessions
+} from "./chunk-3T62R7ON.js";
+import {
+  ATTR,
+  INGEST_SOURCE_CLI
+} from "./chunk-TR6O4S4T.js";
+import {
+  writeOtlpFile
+} from "./chunk-NZ5Y7UEL.js";
+import {
+  redactSpans
+} from "./chunk-RZL5GAWH.js";
+import {
+  parseIsoToEpochMs
+} from "./chunk-DU534HAX.js";
+
+// src/upload.ts
+import { readFile as readFile2 } from "fs/promises";
+import { createRequire } from "module";
+import { hostname } from "os";
+import { basename, join as join2 } from "path";
+import { hostedClientFromEnv } from "@tangle-network/agent-eval/hosted";
+import { assessShareSafety, combineVerdicts, REDACTION_VERSION, redact, shareAllowed } from "@tangle-network/agent-eval/traces";
+
+// src/upload-state.ts
+import { mkdir, readFile, writeFile } from "fs/promises";
+import { homedir } from "os";
+import { dirname, join } from "path";
+import { contentHash } from "@tangle-network/agent-eval";
+function stateHome() {
+  return process.env.XDG_STATE_HOME ?? join(homedir(), ".local", "state");
+}
+function stateFile() {
+  return join(stateHome(), "traces", "uploaded.json");
+}
+function legacyStateFile() {
+  return join(stateHome(), "tangle-traces", "uploaded.json");
+}
+function uploadKey(harness, sessionId) {
+  return `${harness}:${sessionId}`;
+}
+function sessionHash(spans) {
+  return contentHash(spans).slice(0, 32);
+}
+function outboundHash(events, identity) {
+  return contentHash({ events, identity }).slice(0, 32);
+}
+async function loadState() {
+  for (const file of [stateFile(), legacyStateFile()]) {
+    try {
+      return JSON.parse(await readFile(file, "utf8"));
+    } catch {
+    }
+  }
+  return {};
+}
+async function saveState(state) {
+  const f = stateFile();
+  await mkdir(dirname(f), { recursive: true });
+  await writeFile(f, `${JSON.stringify(state, null, 2)}
+`, "utf8");
+}
+function alreadyUploaded(state, harness, sessionId, hash) {
+  return state[uploadKey(harness, sessionId)]?.hash === hash;
+}
+
+// src/upload.ts
+var require2 = createRequire(import.meta.url);
+var TRACES_VERSION = require2("../package.json").version;
+async function planUpload(opts = {}) {
+  return { ...await planUploadFrom(scanSessions(opts)), sinceMs: opts.sinceMs };
+}
+async function planUploadFrom(sessions) {
+  const state = await loadState();
+  const items = [];
+  for await (const { ref, spans: raw } of sessions) {
+    const { spans, report } = redactSpans(raw);
+    const hash = sessionHash(spans);
+    items.push({
+      ref,
+      spans,
+      redaction: report,
+      hash,
+      isNew: true
+    });
+  }
+  return { items, state };
+}
+async function gitBranch(cwd) {
+  if (!cwd) return void 0;
+  try {
+    const head = await readFile2(join2(cwd, ".git", "HEAD"), "utf8");
+    const m = head.match(/^ref:\s*refs\/heads\/(.+)$/m);
+    return m?.[1]?.trim();
+  } catch {
+    return void 0;
+  }
+}
+async function sessionMeta(item) {
+  const meta = {
+    [ATTR.HARNESS]: item.ref.harness,
+    [ATTR.SESSION_FILE]: basename(item.ref.path),
+    [ATTR.HOST]: hostname(),
+    [ATTR.UPLOADER]: `tangle-traces@${TRACES_VERSION}`,
+    [ATTR.REDACTION_VERSION]: REDACTION_VERSION,
+    [ATTR.REDACTION_COUNT]: item.redaction.redactionCount
+  };
+  if (item.ref.cwd) meta[ATTR.CWD] = item.ref.cwd;
+  const branch = await gitBranch(item.ref.cwd);
+  if (branch) meta[ATTR.GIT_BRANCH] = branch;
+  return redact(meta).value;
+}
+var msToNano = (epochMs) => (BigInt(epochMs) * 1000000n).toString();
+function toTraceSpanEvents(spans, rootMeta) {
+  return spans.map((s) => {
+    const attributes = {};
+    for (const [k, v] of Object.entries(s.attributes)) {
+      if (typeof v === "string" || typeof v === "number" || typeof v === "boolean") attributes[k] = v;
+      else if (v != null) attributes[k] = JSON.stringify(v);
+    }
+    attributes[ATTR.SESSION_ID] = s.trace_id;
+    attributes[ATTR.INGEST_SOURCE] = INGEST_SOURCE_CLI;
+    if (s.parent_span_id === null) Object.assign(attributes, rootMeta);
+    const startMs = parseIsoToEpochMs(s.start_time);
+    const endMs = Math.max(startMs, parseIsoToEpochMs(s.end_time));
+    return {
+      traceId: s.trace_id,
+      spanId: s.span_id,
+      ...s.parent_span_id ? { parentSpanId: s.parent_span_id } : {},
+      name: s.name,
+      startTimeUnixNano: msToNano(startMs),
+      endTimeUnixNano: msToNano(endMs),
+      attributes,
+      ...s.status.code === "UNSET" ? {} : { status: { code: s.status.code, ...s.status.message ? { message: s.status.message } : {} } }
+    };
+  });
+}
+var PartialUploadError = class extends Error {
+  sessionKey;
+  accepted;
+  expected;
+  constructor(sessionKey, accepted, expected) {
+    super(`upload: backend accepted ${accepted} of ${expected} spans for ${sessionKey}`);
+    this.name = "PartialUploadError";
+    this.sessionKey = sessionKey;
+    this.accepted = accepted;
+    this.expected = expected;
+  }
+};
+async function prepareOutbound(plan, opts, uploadedAt) {
+  let candidates = plan.items;
+  if (opts.stripContent) {
+    candidates = candidates.map((item) => ({ ...item, spans: metadataOnly(item.spans).spans }));
+  }
+  const identity = {
+    stripContent: opts.stripContent === true,
+    redactor: null,
+    redactionVersion: REDACTION_VERSION
+  };
+  const items = [];
+  const refused = [];
+  const verdicts = [];
+  for (const item of candidates) {
+    const key = uploadKey(item.ref.harness, item.ref.sessionId);
+    const previous = plan.state[key];
+    const meta = await sessionMeta(item);
+    if (opts.stripContent) {
+      for (const [key2, value] of Object.entries(meta)) if (!isMetadataAttribute(key2, value)) delete meta[key2];
+    }
+    const eventsAt = (timestamp) => toTraceSpanEvents(item.spans, { ...meta, [ATTR.UPLOADED_AT]: timestamp });
+    let eventTimestamp = previous?.uploadedAt ?? uploadedAt;
+    let events = eventsAt(eventTimestamp);
+    let hash = outboundHash(events, identity);
+    if (alreadyUploaded(plan.state, item.ref.harness, item.ref.sessionId, hash)) continue;
+    if (eventTimestamp !== uploadedAt) {
+      eventTimestamp = uploadedAt;
+      events = eventsAt(eventTimestamp);
+      hash = outboundHash(events, identity);
+    }
+    const verdict = assessShareSafety(events);
+    verdicts.push(verdict);
+    if (!shareAllowed(verdict)) {
+      refused.push({ harness: item.ref.harness, sessionId: item.ref.sessionId, verdict });
+      continue;
+    }
+    items.push({ item, events, hash });
+  }
+  return {
+    items,
+    skipped: plan.items.length - items.length - refused.length,
+    refused,
+    ...verdicts.length > 0 ? { verdict: combineVerdicts("default", verdicts) } : {}
+  };
+}
+async function executeUpload(plan, opts = {}) {
+  const uploadedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const { items, skipped, refused, verdict } = await prepareOutbound(plan, opts, uploadedAt);
+  const redactionCount = items.reduce((n, { item }) => n + item.redaction.redactionCount, 0);
+  if (opts.dryRun) {
+    const path = opts.otlpOut === void 0 ? void 0 : await writeOtlpFile(items.flatMap(({ item }) => item.spans), opts.otlpOut);
+    return {
+      uploadedSessions: 0,
+      skippedSessions: skipped,
+      acceptedSpans: 0,
+      redactionCount,
+      dryRun: true,
+      ...path === void 0 ? {} : { otlpPath: path },
+      refused,
+      ...verdict ? { verdict } : {}
+    };
+  }
+  if (items.length === 0) {
+    return {
+      uploadedSessions: 0,
+      skippedSessions: skipped,
+      acceptedSpans: 0,
+      redactionCount,
+      dryRun: false,
+      refused,
+      ...verdict ? { verdict } : {}
+    };
+  }
+  const client = opts.backend ?? hostedClientFromEnv();
+  if (!client) {
+    throw new Error(
+      "upload: no backend. Pass opts.backend, or configure the hosted Tangle Intelligence client via TANGLE_INGEST_URL (or TANGLE_ORCHESTRATOR_URL), TANGLE_INGEST_API_KEY (or TANGLE_API_KEY), and TANGLE_TENANT_ID. Use --dry-run to preview without uploading."
+    );
+  }
+  const state = plan.state;
+  let acceptedSpans = 0;
+  const completed = [];
+  for (const outbound of items) {
+    const { item, events, hash } = outbound;
+    const key = uploadKey(item.ref.harness, item.ref.sessionId);
+    const idempotencyKey = `${key}:${hash}`;
+    const res = await client.ingestTraces(events, idempotencyKey);
+    if (res.accepted !== events.length) throw new PartialUploadError(key, res.accepted, events.length);
+    acceptedSpans += res.accepted;
+    completed.push({ key, item, hash, spanCount: events.length });
+    opts.log?.(`uploaded ${item.ref.harness} ${item.ref.sessionId.slice(0, 8)} \u2014 ${res.accepted} spans`);
+  }
+  for (const { key, item, hash, spanCount } of completed) {
+    state[key] = {
+      hash,
+      uploadedAt,
+      harness: item.ref.harness,
+      spanCount
+    };
+  }
+  await saveState(state);
+  return {
+    uploadedSessions: items.length,
+    skippedSessions: skipped,
+    acceptedSpans,
+    redactionCount,
+    dryRun: false,
+    refused,
+    ...verdict ? { verdict } : {}
+  };
+}
+
+export {
+  planUpload,
+  planUploadFrom,
+  toTraceSpanEvents,
+  PartialUploadError,
+  executeUpload
+};

package/dist/chunk-CL3OQOWX.js

@@ -0,0 +1,407 @@
+import {
+  detectEvidenceFormat,
+  exportTraceEvidenceFile
+} from "./chunk-6CLC7DKP.js";
+import {
+  isCodexExecRecord,
+  listAdapters,
+  parseSession,
+  readsStoreRoots,
+  resolveAdapter
+} from "./chunk-3T62R7ON.js";
+import {
+  isOtlpJsonFile,
+  isStandardOtlpRow,
+  readJsonl,
+  readOtlpInput
+} from "./chunk-NZ5Y7UEL.js";
+
+// src/refs.ts
+import { readFile, stat } from "fs/promises";
+import { homedir } from "os";
+import { join, resolve, sep } from "path";
+import { CODEX_HOME_RULE, STORES, codexHomes, isCodexHome } from "@tangle-network/harness-sessions";
+import { ATTR } from "@tangle-network/agent-trace-contract";
+var MIN_REF_CHARS = 8;
+var RefError = class extends Error {
+  code;
+  candidates;
+  constructor(message, code, candidates = []) {
+    super(message);
+    this.name = "RefError";
+    this.code = code;
+    this.candidates = candidates;
+  }
+};
+function isObject(value) {
+  return value != null && typeof value === "object" && !Array.isArray(value);
+}
+function errorText(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+async function statOf(path) {
+  try {
+    return await stat(path);
+  } catch (error) {
+    const code = error.code;
+    if (code === "ENOENT" || code === "ENOTDIR") return null;
+    throw error;
+  }
+}
+async function isDirectory(path) {
+  return (await statOf(path))?.isDirectory() ?? false;
+}
+async function isFile(path) {
+  return (await statOf(path))?.isFile() ?? false;
+}
+function ownHome() {
+  return process.env.HOME || homedir();
+}
+var HEAD_ROWS = 20;
+var MAX_WHOLE_JSON_BYTES = 256 * 1024 * 1024;
+var CODEX_ROLLOUT_TYPES = /* @__PURE__ */ new Set(["session_meta", "response_item", "event_msg", "turn_context"]);
+var STORE_PATHS = [
+  { harness: "claude-code", root: STORES["claude-code.projects-jsonl"].root },
+  { harness: "pi", root: STORES["pi.session-jsonl"].root },
+  { harness: "kimi", root: STORES["kimi.session-dir"].root },
+  { harness: "factory", root: STORES["factory.session-jsonl"].root }
+];
+function harnessOfStorePath(path) {
+  const absolute = resolve(path);
+  for (const { harness, root } of STORE_PATHS) {
+    if (absolute.includes(`${sep}${root.split("/").join(sep)}${sep}`)) return harness;
+  }
+  const segments = absolute.split(sep);
+  for (let i = 1; i < segments.length - 1; i += 1) {
+    if (!CODEX_HOME_RULE.sessionDirs.includes(segments[i + 1])) continue;
+    if (isCodexHome(segments.slice(0, i + 1).join(sep))) return "codex";
+  }
+  return void 0;
+}
+async function headRows(path) {
+  const rows = [];
+  let unparsed = 0;
+  for await (const row of readJsonl(path, { mode: "recover", onCorruption: () => {
+    unparsed += 1;
+  } })) {
+    rows.push(row);
+    if (rows.length >= HEAD_ROWS) return rows;
+    if (unparsed > HEAD_ROWS && rows.length === 0) break;
+  }
+  if (rows.length > 0 && unparsed === 0) {
+    const only = rows.length === 1 ? rows[0] : void 0;
+    if (Array.isArray(only)) return only;
+    if (isObject(only) && Array.isArray(only.events)) return only.events;
+    return rows;
+  }
+  const info = await stat(path);
+  if (info.size > MAX_WHOLE_JSON_BYTES) return rows;
+  let parsed;
+  try {
+    parsed = JSON.parse(await readFile(path, "utf8"));
+  } catch {
+    return rows;
+  }
+  if (Array.isArray(parsed)) return parsed;
+  if (isObject(parsed) && Array.isArray(parsed.events)) return parsed.events;
+  return [parsed];
+}
+function isClaudeRecord(row) {
+  return isObject(row) && (typeof row.sessionId === "string" || typeof row.session_id === "string") && typeof row.type === "string" && ("message" in row || "uuid" in row || "subtype" in row);
+}
+async function sniffTraceFile(path) {
+  const stored = harnessOfStorePath(path);
+  if (stored) return { kind: "session", harness: stored };
+  if (await isOtlpJsonFile(path)) return { kind: "spans", reader: "otlp" };
+  const rows = await headRows(path);
+  if (rows.some(isCodexExecRecord)) return { kind: "session", harness: "codex-exec" };
+  if (rows.length > 0 && rows.every((row) => isObject(row) && typeof row.trace_id === "string" && typeof row.span_id === "string")) {
+    return { kind: "spans", reader: "otlp" };
+  }
+  if (rows.length > 0 && rows.every(isStandardOtlpRow)) return { kind: "spans", reader: "otlp" };
+  if (!rows.some((row) => isObject(row) && typeof row.span_id === "string")) {
+    if (rows.some(isClaudeRecord)) return { kind: "session", harness: "claude-code" };
+    if (rows.some((row) => isObject(row) && CODEX_ROLLOUT_TYPES.has(String(row.type)) && isObject(row.payload))) {
+      return { kind: "session", harness: "codex" };
+    }
+    const first = rows[0];
+    if (isObject(first) && first.type === "session" && typeof first.id === "string") return { kind: "session", harness: "pi" };
+    if (rows.some((row) => isObject(row) && row.type === "session_start")) return { kind: "session", harness: "factory" };
+  }
+  const evidence = detectEvidenceFormat(rows);
+  if (evidence === "sandbox-events") {
+    for await (const row of readJsonl(path, { mode: "recover", onCorruption: () => {
+    } })) {
+      if (isCodexExecRecord(row)) return { kind: "session", harness: "codex-exec" };
+    }
+  }
+  if (evidence) return { kind: "spans", reader: evidence };
+  return { kind: "spans", reader: "otlp" };
+}
+function adapterFor(harness) {
+  const adapter = resolveAdapter(harness);
+  if (!adapter) {
+    throw new RefError(`unknown harness "${harness}"; known: ${listAdapters().map((a) => a.harness).join(", ")}`, "usage");
+  }
+  return adapter;
+}
+async function fileRef(path, ref, selector, options) {
+  if (options.format) return { kind: "spans", ref, path, reader: options.format, ...selector ? { selector } : {} };
+  const sniffed = options.harness ? { kind: "session", harness: options.harness } : await sniffTraceFile(path);
+  if (sniffed.kind === "spans") return { kind: "spans", ref, path, reader: sniffed.reader, ...selector ? { selector } : {} };
+  if (selector) throw new RefError(`${ref}: a #selector picks a run from a span file; ${path} is a ${sniffed.harness} session`, "usage");
+  const adapter = adapterFor(sniffed.harness);
+  const info = await stat(path);
+  return {
+    kind: "session",
+    ref,
+    adapter,
+    session: { harness: adapter.harness, sessionId: ref, path, cwd: null, mtimeMs: info.mtimeMs }
+  };
+}
+var HOME_STORES = [
+  STORES["claude-code.projects-jsonl"].root,
+  STORES["opencode.sqlite"].root,
+  STORES["pi.session-jsonl"].root,
+  STORES["kimi.session-dir"].root,
+  STORES["factory.session-jsonl"].root
+];
+async function isStoreRoot(dir) {
+  for (const root of HOME_STORES) if (await isDirectory(join(dir, root))) return true;
+  for (const home of await codexHomes(dir)) {
+    for (const sessions of CODEX_HOME_RULE.sessionDirs) if (await isDirectory(join(home, sessions))) return true;
+  }
+  return false;
+}
+var BUNDLE_SPAN_FILES = ["spans.otlp.jsonl", join("derived", "trace.otlp.jsonl")];
+async function directoryRef(path, ref) {
+  if (await isFile(join(path, "manifest.json"))) {
+    for (const file of BUNDLE_SPAN_FILES) {
+      if (await isFile(join(path, file))) return { kind: "spans", ref, path: join(path, file), reader: "otlp" };
+    }
+    throw new RefError(`${ref} has a manifest.json but no spans.otlp.jsonl; it is not a traces bundle`, "unreadable");
+  }
+  const { findSupervisorRunDirs, isRuntimeSupervisorRunDir } = await import("@tangle-network/agent-eval/supervisor-run");
+  if (await isRuntimeSupervisorRunDir(path)) return { kind: "run-dir", ref, path };
+  if (await isStoreRoot(path)) return { kind: "store-root", ref, path: resolve(path) };
+  if ((await findSupervisorRunDirs(path)).length > 0) return { kind: "run-dir", ref, path };
+  return { kind: "spans", ref, path, reader: "otlp" };
+}
+function looksLikePath(ref) {
+  return ref.includes("/") || ref.startsWith(".") || ref.startsWith("~") || /\.(?:jsonl|ndjson|json|db)$/iu.test(ref);
+}
+function candidate({ adapter, session }) {
+  return { harness: adapter.harness, sessionId: session.sessionId, path: session.path };
+}
+var COMPLETE_ID_CHARS = 20;
+async function lookupSession(query, options, storeRoot) {
+  const short = query.length < MIN_REF_CHARS;
+  const home = storeRoot ?? ownHome();
+  const selected = options.harness ? [adapterFor(options.harness)] : listAdapters();
+  const adapters = storeRoot === void 0 ? selected : selected.filter(readsStoreRoots);
+  const failures = /* @__PURE__ */ new Map();
+  const listed = /* @__PURE__ */ new Map();
+  const sessionsOf = (adapter, exact) => {
+    if (readsStoreRoots(adapter) && exact) return adapter.locateIn(home, { nativeSessionId: query });
+    let all = listed.get(adapter);
+    if (!all) {
+      all = readsStoreRoots(adapter) ? adapter.locateIn(home) : adapter.locate();
+      listed.set(adapter, all);
+    }
+    return all;
+  };
+  const search = async (exact) => {
+    const found2 = /* @__PURE__ */ new Map();
+    for (const adapter of adapters) {
+      let sessions;
+      try {
+        sessions = await sessionsOf(adapter, exact);
+      } catch (error) {
+        failures.set(adapter.harness, errorText(error));
+        continue;
+      }
+      for (const session of sessions) {
+        const id = session.sessionId;
+        if (id === query || !exact && (id.startsWith(query) || id.endsWith(query))) {
+          found2.set(`${adapter.harness}\0${session.path}\0${id}`, { adapter, session });
+        }
+      }
+    }
+    return [...found2.values()].sort((a, b) => b.session.mtimeMs - a.session.mtimeMs);
+  };
+  let found = query.length >= COMPLETE_ID_CHARS || short ? await search(true) : [];
+  if (found.length === 0 && short) {
+    throw new RefError(
+      `"${query}" is not a file, a directory or a session id, and a session id prefix or suffix needs at least ${MIN_REF_CHARS} characters`,
+      "usage"
+    );
+  }
+  if (found.length === 0) {
+    const matched = await search(false);
+    const exact = matched.filter(({ session }) => session.sessionId === query);
+    found = exact.length > 0 ? exact : matched;
+  }
+  if (found.length === 1) return { kind: "session", ref: query, adapter: found[0].adapter, session: found[0].session };
+  const where = storeRoot === void 0 ? "" : ` under ${storeRoot}`;
+  if (found.length === 0) {
+    const unread = failures.size > 0 ? `; could not read ${[...failures].map(([harness, reason]) => `${harness}: ${reason}`).join("; ")}` : "";
+    throw new RefError(
+      `no session id is, starts with or ends with "${query}"${where} (${adapters.map((a) => a.harness).join(", ")})${unread}; \`traces list\` shows ids`,
+      "unreadable"
+    );
+  }
+  const shown = found.slice(0, 5).map((item) => `${item.adapter.harness} ${item.session.sessionId}`);
+  const more = found.length > shown.length ? ` and ${found.length - shown.length} more` : "";
+  throw new RefError(
+    `"${query}" matches ${found.length} sessions${where} (${shown.join(", ")}${more}); pass more of the id`,
+    "ambiguous",
+    found.map(candidate)
+  );
+}
+function shortestRefs(ids) {
+  const unique = [...new Set(ids)];
+  const reverse = (text) => [...text].reverse().join("");
+  const forward = [...unique].sort();
+  const backward = unique.map(reverse).sort();
+  const starting = (sorted, prefix) => {
+    let low = 0;
+    let high = sorted.length;
+    while (low < high) {
+      const mid = low + high >> 1;
+      if (sorted[mid] < prefix) low = mid + 1;
+      else high = mid;
+    }
+    const found = [];
+    for (let i = low; i < sorted.length && found.length < 2 && sorted[i].startsWith(prefix); i += 1) found.push(sorted[i]);
+    return found;
+  };
+  const alone = (id, form) => {
+    const matches = /* @__PURE__ */ new Set([...starting(forward, form), ...starting(backward, reverse(form)).map(reverse)]);
+    return matches.size === 1 && matches.has(id);
+  };
+  const shortest = /* @__PURE__ */ new Map();
+  for (const id of unique) {
+    let best = id;
+    for (let length = MIN_REF_CHARS; length < id.length; length += 1) {
+      const prefix = id.slice(0, length);
+      const suffix = id.slice(-length);
+      if (alone(id, prefix)) {
+        best = prefix;
+        break;
+      }
+      if (alone(id, suffix)) {
+        best = suffix;
+        break;
+      }
+    }
+    shortest.set(id, best);
+  }
+  return shortest;
+}
+async function splitSelector(ref) {
+  const hash = ref.lastIndexOf("#");
+  if (hash <= 0 || hash === ref.length - 1 || await statOf(ref) !== null) return { path: ref };
+  const path = ref.slice(0, hash);
+  return await statOf(path) === null ? { path: ref } : { path, selector: ref.slice(hash + 1) };
+}
+async function pathRef(ref, options) {
+  const { path, selector } = await splitSelector(ref);
+  const info = await statOf(path);
+  if (info === null) {
+    if (looksLikePath(ref)) throw new RefError(`no such file or directory: ${ref}`, "unreadable");
+    return void 0;
+  }
+  if (info.isDirectory()) {
+    if (selector) throw new RefError(`${ref}: a #selector picks a run from a span file, not a directory`, "usage");
+    return directoryRef(path, ref);
+  }
+  if (!info.isFile()) throw new RefError(`${ref} is neither a file nor a directory`, "unreadable");
+  return fileRef(path, ref, selector, options);
+}
+async function resolveRefs(refs, options = {}) {
+  const byPath = await Promise.all(refs.map((ref) => pathRef(ref, options)));
+  const roots = byPath.filter((ref) => ref?.kind === "store-root");
+  if (roots.length > 1) {
+    throw new RefError(`name one store root per command, not ${roots.length}: ${roots.map((root) => root.ref).join(", ")}`, "usage");
+  }
+  const resolved = [];
+  for (const [index, ref] of refs.entries()) {
+    resolved.push(byPath[index] ?? await lookupSession(ref, options, roots[0]?.path));
+  }
+  return resolved;
+}
+function branchSpans(spans, branch) {
+  const byId = /* @__PURE__ */ new Map();
+  for (const span of spans) byId.set(span.span_id, span);
+  const children = /* @__PURE__ */ new Map();
+  for (const span of spans) {
+    if (!span.parent_span_id) continue;
+    const list = children.get(span.parent_span_id);
+    if (list) list.push(span);
+    else children.set(span.parent_span_id, [span]);
+  }
+  const matched = spans.filter(
+    (span) => span.attributes[ATTR.branchId] === branch || span.attributes[ATTR.branchArm] === branch
+  );
+  const matchedIds = new Set(matched.map((span) => span.span_id));
+  const hasMatchedAncestor = (span) => {
+    let current = span;
+    while (current.parent_span_id) {
+      const parent = byId.get(current.parent_span_id);
+      if (!parent) return false;
+      if (matchedIds.has(parent.span_id)) return true;
+      current = parent;
+    }
+    return false;
+  };
+  const roots = matched.filter((span) => !hasMatchedAncestor(span));
+  if (roots.length > 1) {
+    const named = roots.map((span) => `${span.span_id} (${ATTR.branchId}=${JSON.stringify(span.attributes[ATTR.branchId] ?? null)})`).join(", ");
+    throw new Error(
+      `"${branch}" matches ${roots.length} separate subtrees, not one arm: ${named} \u2014 sibling arms can share a branch id; select by span id, or narrow the input to one arm first`
+    );
+  }
+  const selected = /* @__PURE__ */ new Set();
+  const stack = [...matched];
+  while (stack.length > 0) {
+    const span = stack.pop();
+    if (selected.has(span)) continue;
+    selected.add(span);
+    stack.push(...children.get(span.span_id) ?? []);
+  }
+  return spans.filter((span) => selected.has(span));
+}
+function selectSpans(spans, selector, path) {
+  if (selector.startsWith("branch=")) {
+    const branch = selector.slice("branch=".length);
+    const picked2 = branchSpans(spans, branch);
+    if (picked2.length === 0) throw new RefError(`${path} holds no span with ${ATTR.branchId} or ${ATTR.branchArm} "${branch}"`, "unreadable");
+    return picked2;
+  }
+  const picked = spans.filter((span) => span.trace_id === selector);
+  if (picked.length === 0) throw new RefError(`${path} holds no run with trace id ${selector}`, "unreadable");
+  return picked;
+}
+async function readRefSpans(ref, options = {}) {
+  const resolved = (await resolveRefs([ref], options))[0];
+  switch (resolved.kind) {
+    case "session":
+      return parseSession(resolved.adapter, resolved.session);
+    case "run-dir":
+      return [...(await readOtlpInput(resolved.path)).spans];
+    case "store-root":
+      throw new RefError(`${ref} is a store root, which holds many sessions; name one session in it`, "usage");
+    case "spans": {
+      const spans = resolved.reader === "otlp" ? [...(await readOtlpInput(resolved.path)).spans] : (await exportTraceEvidenceFile(resolved.path, { format: resolved.reader })).spans;
+      return resolved.selector ? selectSpans(spans, resolved.selector, resolved.path) : spans;
+    }
+  }
+}
+
+export {
+  RefError,
+  shortestRefs,
+  resolveRefs,
+  selectSpans,
+  readRefSpans
+};