@cohortapp/agent-sdk 2.3.0

package/lib/diagnostics/otel.test.mjs

@@ -0,0 +1,196 @@
+/**
+ * otel.test.mjs — node:test coverage for the Claude Code OTLP env builder.
+ *
+ * Pure-function tests: env and identity are passed in, never read from the real
+ * process.env, so nothing leaks between cases. We assert the builder emits env
+ * ONLY when enabled, stamps service.name + agent id, and never throws.
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  buildOtelEnv,
+  otelEnabled,
+  deriveAgentId,
+  buildResourceAttributes,
+} from "./otel.mjs";
+
+// ---------------------------------------------------------------------------
+// otelEnabled
+// ---------------------------------------------------------------------------
+
+test("otelEnabled is false by default (empty env, no config)", () => {
+  assert.equal(otelEnabled({ env: {}, config: {} }), false);
+});
+
+test("otelEnabled honours MAESTRO_OTEL truthy values", () => {
+  for (const v of ["1", "true", "yes", "on", "TRUE", "On"]) {
+    assert.equal(otelEnabled({ env: { MAESTRO_OTEL: v }, config: {} }), true, v);
+  }
+  for (const v of ["0", "false", "no", "off", "", "nope"]) {
+    assert.equal(otelEnabled({ env: { MAESTRO_OTEL: v }, config: {} }), false, v);
+  }
+});
+
+test("config.enabled boolean overrides the env flag", () => {
+  // config wins both ways
+  assert.equal(otelEnabled({ env: { MAESTRO_OTEL: "1" }, config: { enabled: false } }), false);
+  assert.equal(otelEnabled({ env: { MAESTRO_OTEL: "0" }, config: { enabled: true } }), true);
+});
+
+// ---------------------------------------------------------------------------
+// buildOtelEnv — disabled => empty
+// ---------------------------------------------------------------------------
+
+test("buildOtelEnv returns an empty map when disabled", () => {
+  assert.deepEqual(buildOtelEnv({ env: {}, config: {} }), {});
+  assert.deepEqual(
+    buildOtelEnv({ env: { MAESTRO_OTEL: "0" }, config: {}, identity: { repoSlug: "alex-ai" } }),
+    {}
+  );
+});
+
+test("the empty map is safe to spread (no telemetry keys leak)", () => {
+  const merged = { PATH: "/usr/bin", ...buildOtelEnv({ env: {}, config: {} }) };
+  assert.deepEqual(Object.keys(merged), ["PATH"]);
+});
+
+// ---------------------------------------------------------------------------
+// buildOtelEnv — enabled => full block with sane defaults
+// ---------------------------------------------------------------------------
+
+test("buildOtelEnv emits the enabling block when MAESTRO_OTEL=1", () => {
+  const env = buildOtelEnv({
+    env: { MAESTRO_OTEL: "1" },
+    config: {},
+    identity: { repoSlug: "alex-ai" },
+  });
+  assert.equal(env.CLAUDE_CODE_ENABLE_TELEMETRY, "1");
+  assert.equal(env.OTEL_METRICS_EXPORTER, "otlp");
+  assert.equal(env.OTEL_LOGS_EXPORTER, "otlp");
+  assert.equal(env.OTEL_TRACES_EXPORTER, "otlp");
+  assert.equal(env.OTEL_EXPORTER_OTLP_PROTOCOL, "http/protobuf");
+});
+
+test("buildOtelEnv stamps service.name and agent id into resource attributes", () => {
+  const env = buildOtelEnv({
+    config: { enabled: true },
+    identity: { repoSlug: "alex-ai", maestroVersion: "0.15.2" },
+  });
+  const attrs = env.OTEL_RESOURCE_ATTRIBUTES;
+  assert.ok(attrs.includes("service.name=maestro-agent"), attrs);
+  assert.ok(attrs.includes("service.version=0.15.2"), attrs);
+  assert.ok(attrs.includes("service.instance.id=alex-ai"), attrs);
+  assert.ok(attrs.includes("agent.id=alex-ai"), attrs);
+});
+
+test("buildOtelEnv lets serviceName be overridden", () => {
+  const env = buildOtelEnv({
+    config: { enabled: true },
+    identity: { repoSlug: "robin-ai" },
+    serviceName: "claude-code-robin",
+  });
+  assert.ok(env.OTEL_RESOURCE_ATTRIBUTES.includes("service.name=claude-code-robin"));
+});
+
+// ---------------------------------------------------------------------------
+// buildOtelEnv — optional knobs only when present
+// ---------------------------------------------------------------------------
+
+test("endpoint/headers/intervals are emitted only when configured", () => {
+  const bare = buildOtelEnv({ config: { enabled: true }, identity: { repoSlug: "a" } });
+  assert.ok(!("OTEL_EXPORTER_OTLP_ENDPOINT" in bare));
+  assert.ok(!("OTEL_EXPORTER_OTLP_HEADERS" in bare));
+  assert.ok(!("OTEL_METRIC_EXPORT_INTERVAL" in bare));
+  assert.ok(!("OTEL_LOGS_EXPORT_INTERVAL" in bare));
+
+  const full = buildOtelEnv({
+    config: {
+      enabled: true,
+      endpoint: "https://otel.fleet.internal:4318",
+      headers: "Authorization=Bearer xyz",
+      protocol: "grpc",
+      metricExportIntervalMs: 60000,
+      logsExportIntervalMs: 5000,
+    },
+    identity: { repoSlug: "a" },
+  });
+  assert.equal(full.OTEL_EXPORTER_OTLP_ENDPOINT, "https://otel.fleet.internal:4318");
+  assert.equal(full.OTEL_EXPORTER_OTLP_HEADERS, "Authorization=Bearer xyz");
+  assert.equal(full.OTEL_EXPORTER_OTLP_PROTOCOL, "grpc");
+  assert.equal(full.OTEL_METRIC_EXPORT_INTERVAL, "60000");
+  assert.equal(full.OTEL_LOGS_EXPORT_INTERVAL, "5000");
+});
+
+test("config takes precedence over env for exporter knobs", () => {
+  const env = buildOtelEnv({
+    env: { MAESTRO_OTEL: "1", OTEL_EXPORTER_OTLP_ENDPOINT: "http://env-endpoint:4318" },
+    config: { endpoint: "http://config-endpoint:4318" },
+    identity: { repoSlug: "a" },
+  });
+  assert.equal(env.OTEL_EXPORTER_OTLP_ENDPOINT, "http://config-endpoint:4318");
+});
+
+test("env supplies the endpoint when config omits it", () => {
+  const env = buildOtelEnv({
+    env: { MAESTRO_OTEL: "1", OTEL_EXPORTER_OTLP_ENDPOINT: "http://env-endpoint:4318" },
+    config: {},
+    identity: { repoSlug: "a" },
+  });
+  assert.equal(env.OTEL_EXPORTER_OTLP_ENDPOINT, "http://env-endpoint:4318");
+});
+
+test("extra resource attributes from config are appended", () => {
+  const env = buildOtelEnv({
+    config: { enabled: true, resourceAttributes: { "deployment.environment": "prod" } },
+    identity: { repoSlug: "a" },
+  });
+  assert.ok(env.OTEL_RESOURCE_ATTRIBUTES.includes("deployment.environment=prod"));
+});
+
+// ---------------------------------------------------------------------------
+// deriveAgentId
+// ---------------------------------------------------------------------------
+
+test("deriveAgentId prefers explicit id, then repoSlug, then name", () => {
+  assert.equal(deriveAgentId({ agentId: "spiffe-007", repoSlug: "x" }), "spiffe-007");
+  assert.equal(deriveAgentId({ repoSlug: "Alex-AI" }), "alex-ai");
+  assert.equal(deriveAgentId({ fullName: "Robin Quist" }), "robin-quist");
+  assert.equal(deriveAgentId({}), "");
+});
+
+test("deriveAgentId slugifies unsafe characters", () => {
+  assert.equal(deriveAgentId({ fullName: "Señor  Tester!" }), "se-or-tester");
+});
+
+// ---------------------------------------------------------------------------
+// buildResourceAttributes — formatting + sanitization
+// ---------------------------------------------------------------------------
+
+test("buildResourceAttributes skips empty values (no dangling k=)", () => {
+  const attrs = buildResourceAttributes({ serviceName: "svc", serviceVersion: "", agentId: "" });
+  assert.equal(attrs, "service.name=svc");
+});
+
+test("buildResourceAttributes sanitizes comma/equals inside a value", () => {
+  const attrs = buildResourceAttributes({
+    serviceName: "svc",
+    agentId: "a=b,c",
+  });
+  // a=b,c would corrupt the k=v,k=v list; commas/equals stripped to spaces.
+  assert.ok(!attrs.includes("a=b,c"));
+  assert.ok(attrs.includes("agent.id=a b c"));
+});
+
+// ---------------------------------------------------------------------------
+// never throws
+// ---------------------------------------------------------------------------
+
+test("buildOtelEnv never throws on garbage input", () => {
+  let out;
+  assert.doesNotThrow(() => {
+    out = buildOtelEnv({ env: null, config: null, identity: null });
+  });
+  assert.equal(typeof out, "object");
+});

package/lib/diagnostics/trace.mjs

@@ -0,0 +1,216 @@
+/**
+ * lib/diagnostics/trace.mjs — trace/correlation IDs for the agent event spine.
+ *
+ * One user interaction touches many hops — poller item (or cadence tick) →
+ * classify → dispatch → session → send — but today there is no thread that ties
+ * those rows together; reconstructing a single interaction means fuzzy timestamp
+ * joins (gaps-enterprise-ops G7). This module mints ONE `trace_id` at the start
+ * of an interaction and gives the daemon a way to carry it (plus a span path)
+ * through every downstream hop so the diagnostic-event stream (events.mjs) and
+ * Claude Code's native OTLP export (otel.mjs) correlate to the same id. That is
+ * what makes the <2 min DM SLO measurable: first item_received → last sent,
+ * grouped by `trace_id`.
+ *
+ * The id is ULID-shaped: a 48-bit millisecond timestamp + 80 bits of
+ * randomness, Crockford-base32, 26 chars, monotonic-ish and lexicographically
+ * sortable by creation time. We do NOT pull in a ULID dependency — maestro is
+ * near-zero-dep — this is a self-contained encoder over `node:crypto`.
+ *
+ * Propagation is via `AsyncLocalStorage`: `withTrace(ctx, fn)` runs `fn` (sync
+ * or async) inside a context, and any code beneath — however deep the await
+ * chain — reads it with `currentTrace()`. Where an explicit hand-off is easier
+ * (a spawned sub-process, a serialized inbox item), `traceHeaders()` /
+ * `traceFromHeaders()` move the context across the boundary as plain fields, and
+ * `childSpan()` extends the span path one hop.
+ *
+ * Constraints (CLAUDE.md): ESM, Node built-ins only, pure/injectable (the clock
+ * and RNG are overridable so id minting is deterministic under test). Nothing
+ * here throws on a bad/missing context — a missing trace returns `null`, never
+ * an exception, so an un-instrumented call path degrades to "no correlation"
+ * rather than crashing the daemon.
+ *
+ * @module lib/diagnostics/trace
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+import { randomBytes } from "node:crypto";
+
+// Crockford base32 alphabet (ULID spec): no I, L, O, U to avoid ambiguity.
+const CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+const TIME_LEN = 10; // 48-bit ms timestamp → 10 base32 chars
+const RAND_LEN = 16; // 80-bit randomness → 16 base32 chars
+const ULID_LEN = TIME_LEN + RAND_LEN; // 26
+const ULID_RE = /^[0-9A-HJKMNP-TV-Z]{26}$/;
+
+/** The single ambient store for the current trace context. */
+const STORE = new AsyncLocalStorage();
+
+/**
+ * Encode `time` (epoch ms) as the 10-char timestamp head of a ULID.
+ * @param {number} time
+ * @returns {string}
+ */
+function encodeTime(time) {
+  let t = Math.floor(time);
+  let out = "";
+  for (let i = TIME_LEN - 1; i >= 0; i--) {
+    const mod = t % 32;
+    out = CROCKFORD[mod] + out;
+    t = (t - mod) / 32;
+  }
+  return out;
+}
+
+/**
+ * Encode 80 random bits as the 16-char tail of a ULID. We draw 10 bytes and
+ * map them 5-bits-at-a-time across the 16 output chars (10 * 8 = 80 = 16 * 5).
+ * @param {() => Buffer} rng returns at least 10 random bytes
+ * @returns {string}
+ */
+function encodeRandom(rng) {
+  const bytes = rng(10);
+  // Build the 80-bit value as a BigInt, then peel 5 bits per char.
+  let v = 0n;
+  for (let i = 0; i < 10; i++) v = (v << 8n) | BigInt(bytes[i] & 0xff);
+  let out = "";
+  for (let i = 0; i < RAND_LEN; i++) {
+    out = CROCKFORD[Number(v & 31n)] + out;
+    v >>= 5n;
+  }
+  return out;
+}
+
+/**
+ * Mint a fresh, sortable trace id (ULID-shaped, 26 chars).
+ *
+ * @param {object} [deps]
+ * @param {() => number} [deps.now] clock (default Date.now)
+ * @param {(n: number) => Buffer} [deps.rng] RNG (default crypto.randomBytes)
+ * @returns {string}
+ */
+export function mintTraceId(deps = {}) {
+  const now = typeof deps.now === "function" ? deps.now : Date.now;
+  const rng = typeof deps.rng === "function" ? deps.rng : randomBytes;
+  return encodeTime(now()) + encodeRandom(rng);
+}
+
+/**
+ * True if `id` is a syntactically valid ULID-shaped trace id.
+ * @param {unknown} id
+ * @returns {boolean}
+ */
+export function isTraceId(id) {
+  return typeof id === "string" && id.length === ULID_LEN && ULID_RE.test(id);
+}
+
+/**
+ * Normalise a context argument into a `{ trace_id, span }` shape. Accepts a bare
+ * id string, a partial context object, or null/undefined (mints a fresh trace).
+ * Always returns a valid context with a string `span` (defaults to "root").
+ *
+ * @param {string|{trace_id?:string, span?:string}|null|undefined} ctx
+ * @param {object} [deps] forwarded to mintTraceId when an id must be minted
+ * @returns {{trace_id: string, span: string}}
+ */
+export function toContext(ctx, deps = {}) {
+  if (typeof ctx === "string") {
+    return { trace_id: isTraceId(ctx) ? ctx : ctx, span: "root" };
+  }
+  if (ctx && typeof ctx === "object") {
+    const trace_id =
+      typeof ctx.trace_id === "string" && ctx.trace_id
+        ? ctx.trace_id
+        : mintTraceId(deps);
+    const span = typeof ctx.span === "string" && ctx.span ? ctx.span : "root";
+    return { trace_id, span };
+  }
+  return { trace_id: mintTraceId(deps), span: "root" };
+}
+
+/**
+ * Run `fn` with `ctx` as the ambient trace context. `ctx` may be a bare
+ * trace-id string or a `{trace_id, span}` object; it is normalised first, and
+ * the normalised context is passed to `fn` so callers that minted inline still
+ * see the canonical shape. Works for sync and async `fn` (AsyncLocalStorage
+ * propagates across awaits). The return value of `fn` is returned verbatim.
+ *
+ * @template T
+ * @param {string|{trace_id?:string, span?:string}} ctx
+ * @param {(ctx: {trace_id: string, span: string}) => T} fn
+ * @param {object} [deps]
+ * @returns {T}
+ */
+export function withTrace(ctx, fn, deps = {}) {
+  const normalized = toContext(ctx, deps);
+  return STORE.run(normalized, () => fn(normalized));
+}
+
+/**
+ * The current ambient trace context, or null when called outside any
+ * `withTrace`. Never throws.
+ * @returns {{trace_id: string, span: string}|null}
+ */
+export function currentTrace() {
+  return STORE.getStore() || null;
+}
+
+/**
+ * The current ambient `trace_id`, or null outside any `withTrace`.
+ * @returns {string|null}
+ */
+export function currentTraceId() {
+  const ctx = STORE.getStore();
+  return ctx ? ctx.trace_id : null;
+}
+
+/**
+ * Derive a child context one hop deeper in the span path, preserving the
+ * trace_id. `parent` defaults to the ambient context; if there is none, a fresh
+ * trace is minted so the child is still correlatable to itself.
+ *
+ * Span paths are dotted, e.g. "root" → "root.classify" → "root.classify.send",
+ * giving a cheap, human-readable parent/child lattice without an OTel SDK.
+ *
+ * @param {string} name span segment (e.g. "classify", "dispatch", "send")
+ * @param {{trace_id?:string, span?:string}|null} [parent]
+ * @param {object} [deps]
+ * @returns {{trace_id: string, span: string}}
+ */
+export function childSpan(name, parent = currentTrace(), deps = {}) {
+  const base = toContext(parent, deps);
+  const seg = String(name || "span").replace(/[^A-Za-z0-9_-]/g, "_");
+  return { trace_id: base.trace_id, span: `${base.span}.${seg}` };
+}
+
+/**
+ * Serialize a trace context into plain header fields for crossing a boundary
+ * (spawned sub-process env, a queued inbox item, an HTTP relay). Defaults to the
+ * ambient context. Returns an empty object when there is no context to carry, so
+ * callers can spread it unconditionally.
+ *
+ * @param {{trace_id?:string, span?:string}|null} [ctx]
+ * @returns {{trace_id?: string, span?: string}}
+ */
+export function traceHeaders(ctx = currentTrace()) {
+  if (!ctx || typeof ctx !== "object" || !ctx.trace_id) return {};
+  return { trace_id: ctx.trace_id, span: ctx.span || "root" };
+}
+
+/**
+ * Reconstruct a trace context from header-ish fields received across a boundary.
+ * Returns null when no usable trace id is present (caller may then mint a fresh
+ * one), so an un-propagated hop degrades to "new trace" rather than crashing.
+ *
+ * @param {{trace_id?: string, span?: string}|null|undefined} headers
+ * @returns {{trace_id: string, span: string}|null}
+ */
+export function traceFromHeaders(headers) {
+  if (!headers || typeof headers !== "object") return null;
+  const id = headers.trace_id;
+  if (typeof id !== "string" || !id) return null;
+  const span =
+    typeof headers.span === "string" && headers.span ? headers.span : "root";
+  return { trace_id: id, span };
+}
+
+export const TRACE_ID_LENGTH = ULID_LEN;

package/lib/diagnostics/trace.test.mjs

@@ -0,0 +1,251 @@
+/**
+ * trace.test.mjs — node:test coverage for the trace/correlation spine.
+ *
+ * Hermetic: the clock and RNG are injected so minted ids are deterministic, and
+ * AsyncLocalStorage propagation is exercised across real awaits.
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  mintTraceId,
+  isTraceId,
+  toContext,
+  withTrace,
+  currentTrace,
+  currentTraceId,
+  childSpan,
+  traceHeaders,
+  traceFromHeaders,
+  TRACE_ID_LENGTH,
+} from "./trace.mjs";
+
+// A deterministic 10-byte RNG.
+function fixedRng(byte) {
+  return () => Buffer.alloc(10, byte);
+}
+
+// ---------------------------------------------------------------------------
+// mintTraceId
+// ---------------------------------------------------------------------------
+
+test("mintTraceId returns a 26-char ULID-shaped id", () => {
+  const id = mintTraceId();
+  assert.equal(id.length, TRACE_ID_LENGTH);
+  assert.equal(id.length, 26);
+  assert.ok(isTraceId(id), `expected ${id} to be a valid trace id`);
+});
+
+test("mintTraceId is deterministic under injected clock + rng", () => {
+  const deps = { now: () => 1_700_000_000_000, rng: fixedRng(0x00) };
+  const a = mintTraceId(deps);
+  const b = mintTraceId(deps);
+  assert.equal(a, b, "same clock + rng must yield the same id");
+});
+
+test("mintTraceId is time-sortable: later timestamp sorts after earlier", () => {
+  const early = mintTraceId({ now: () => 1_000_000_000_000, rng: fixedRng(0xff) });
+  const late = mintTraceId({ now: () => 2_000_000_000_000, rng: fixedRng(0x00) });
+  assert.ok(early < late, "earlier-minted id should sort lexicographically first");
+});
+
+test("mintTraceId randomness varies the tail for the same clock", () => {
+  const now = () => 1_700_000_000_000;
+  const a = mintTraceId({ now, rng: fixedRng(0x01) });
+  const b = mintTraceId({ now, rng: fixedRng(0x02) });
+  assert.notEqual(a, b);
+  // Same timestamp head, different random tail.
+  assert.equal(a.slice(0, 10), b.slice(0, 10));
+  assert.notEqual(a.slice(10), b.slice(10));
+});
+
+test("two real mints are unique", () => {
+  const ids = new Set();
+  for (let i = 0; i < 1000; i++) ids.add(mintTraceId());
+  assert.equal(ids.size, 1000);
+});
+
+// ---------------------------------------------------------------------------
+// isTraceId
+// ---------------------------------------------------------------------------
+
+test("isTraceId rejects malformed inputs", () => {
+  assert.equal(isTraceId(""), false);
+  assert.equal(isTraceId(null), false);
+  assert.equal(isTraceId(undefined), false);
+  assert.equal(isTraceId(123), false);
+  assert.equal(isTraceId("short"), false);
+  assert.equal(isTraceId("a".repeat(26)), false); // lowercase not in alphabet
+  assert.equal(isTraceId("I".repeat(26)), false); // I is excluded from Crockford
+  assert.equal(isTraceId(mintTraceId()), true);
+});
+
+// ---------------------------------------------------------------------------
+// toContext
+// ---------------------------------------------------------------------------
+
+test("toContext normalizes a bare id string into {trace_id, span}", () => {
+  const id = mintTraceId();
+  const ctx = toContext(id);
+  assert.equal(ctx.trace_id, id);
+  assert.equal(ctx.span, "root");
+});
+
+test("toContext mints a fresh trace when given null/undefined", () => {
+  const a = toContext(null);
+  const b = toContext(undefined);
+  assert.ok(isTraceId(a.trace_id));
+  assert.ok(isTraceId(b.trace_id));
+  assert.notEqual(a.trace_id, b.trace_id);
+});
+
+test("toContext preserves a provided span", () => {
+  const ctx = toContext({ trace_id: "X", span: "root.classify" });
+  assert.equal(ctx.trace_id, "X");
+  assert.equal(ctx.span, "root.classify");
+});
+
+// ---------------------------------------------------------------------------
+// withTrace / currentTrace propagation
+// ---------------------------------------------------------------------------
+
+test("currentTrace is null outside any withTrace", () => {
+  assert.equal(currentTrace(), null);
+  assert.equal(currentTraceId(), null);
+});
+
+test("withTrace exposes the context to synchronous code", () => {
+  const id = mintTraceId();
+  const seen = withTrace(id, () => currentTraceId());
+  assert.equal(seen, id);
+});
+
+test("withTrace passes the normalized context to fn", () => {
+  const id = mintTraceId();
+  const ctx = withTrace(id, (c) => c);
+  assert.deepEqual(ctx, { trace_id: id, span: "root" });
+});
+
+test("withTrace propagates across awaits (async hooks)", async () => {
+  const id = mintTraceId();
+  const seen = await withTrace(id, async () => {
+    await new Promise((r) => setTimeout(r, 1));
+    await Promise.resolve();
+    return currentTraceId();
+  });
+  assert.equal(seen, id);
+  // Context does not leak after the run.
+  assert.equal(currentTrace(), null);
+});
+
+test("withTrace nests: inner context restores to outer on exit", () => {
+  const outer = mintTraceId();
+  const inner = mintTraceId();
+  withTrace(outer, () => {
+    assert.equal(currentTraceId(), outer);
+    withTrace(inner, () => {
+      assert.equal(currentTraceId(), inner);
+    });
+    assert.equal(currentTraceId(), outer);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// childSpan
+// ---------------------------------------------------------------------------
+
+test("childSpan extends the span path and keeps the trace_id", () => {
+  const id = mintTraceId();
+  withTrace(id, () => {
+    const c = childSpan("classify");
+    assert.equal(c.trace_id, id);
+    assert.equal(c.span, "root.classify");
+    const cc = childSpan("send", c);
+    assert.equal(cc.trace_id, id);
+    assert.equal(cc.span, "root.classify.send");
+  });
+});
+
+test("childSpan sanitizes unsafe segment chars", () => {
+  const c = childSpan("a/b c.d", { trace_id: "T", span: "root" });
+  assert.equal(c.span, "root.a_b_c_d");
+});
+
+test("childSpan with no ambient context mints a fresh trace", () => {
+  const c = childSpan("dispatch");
+  assert.ok(isTraceId(c.trace_id));
+  assert.equal(c.span, "root.dispatch");
+});
+
+// ---------------------------------------------------------------------------
+// traceHeaders / traceFromHeaders — boundary crossing
+// ---------------------------------------------------------------------------
+
+test("traceHeaders serializes the ambient context", () => {
+  const id = mintTraceId();
+  const headers = withTrace({ trace_id: id, span: "root.dispatch" }, () =>
+    traceHeaders()
+  );
+  assert.deepEqual(headers, { trace_id: id, span: "root.dispatch" });
+});
+
+test("traceHeaders returns {} when there is no context", () => {
+  assert.deepEqual(traceHeaders(), {});
+  assert.deepEqual(traceHeaders(null), {});
+});
+
+test("traceFromHeaders round-trips a serialized context", () => {
+  const id = mintTraceId();
+  const headers = { trace_id: id, span: "root.session" };
+  const ctx = traceFromHeaders(headers);
+  assert.deepEqual(ctx, { trace_id: id, span: "root.session" });
+});
+
+test("traceFromHeaders returns null on missing/garbage input", () => {
+  assert.equal(traceFromHeaders(null), null);
+  assert.equal(traceFromHeaders(undefined), null);
+  assert.equal(traceFromHeaders({}), null);
+  assert.equal(traceFromHeaders({ span: "root" }), null);
+  assert.equal(traceFromHeaders("nope"), null);
+});
+
+test("traceFromHeaders defaults span to root when absent", () => {
+  const id = mintTraceId();
+  const ctx = traceFromHeaders({ trace_id: id });
+  assert.equal(ctx.span, "root");
+});
+
+// ---------------------------------------------------------------------------
+// End-to-end: one trace_id carried item -> classify -> dispatch -> send
+// ---------------------------------------------------------------------------
+
+test("a single trace_id correlates a full interaction across hops", async () => {
+  const traceId = mintTraceId();
+  const spansSeen = [];
+
+  // item/tick mints the trace and opens the root context.
+  await withTrace(traceId, async () => {
+    spansSeen.push(currentTrace().span); // root
+
+    // classify (sync hop)
+    const classifyCtx = childSpan("classify");
+    await withTrace(classifyCtx, async () => {
+      spansSeen.push(currentTrace().span);
+      assert.equal(currentTraceId(), traceId);
+    });
+
+    // dispatch -> serialize across a (simulated) process boundary
+    const dispatchCtx = childSpan("dispatch");
+    const headers = traceHeaders(dispatchCtx);
+
+    // session: reconstruct from headers in the "child process"
+    const sessionCtx = traceFromHeaders(headers);
+    await withTrace(childSpan("send", sessionCtx), async () => {
+      spansSeen.push(currentTrace().span);
+      assert.equal(currentTraceId(), traceId);
+    });
+  });
+
+  assert.deepEqual(spansSeen, ["root", "root.classify", "root.dispatch.send"]);
+});