refactor(core): let the trace context manager mark the run boundary

Detecting the run boundary by reference-identity of the trace context was
a heuristic, and guarding it against the noop manager's fresh `{}` meant
testing the context for emptiness. That traded an unreachable bug for a
reachable one: `traceContext` is `z.record(z.unknown())`, so a run whose
context is empty would stop reminting and silently merge back into the
previous run's trace.

Replace the inference with a fact. `StandardTraceContextManager.traceContext`
becomes an accessor pair that advances an epoch whenever the context is
replaced, which is exactly what starting a run does, so no call site
changes. The noop manager reports a constant epoch, so with no manager
registered there are no boundaries to react to and nothing churns.

Drops the emptiness heuristic entirely, and covers the case it would have
broken. Also renames `get()` to `forCurrentRun()` and the shared instance
to `fallbackTraceId`, since the old name read as a string, and exports the
log wrapper so a test can prove a run's spans and logs stay on one id.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: NERLOE

packages/core/src/v3/otel/tracingSDK.ts

@@ -163,12 +163,12 @@ export class TracingSDK {
     );
 
     // Shared by every wrapper below so a run's spans and logs agree on the id.
-    const externalTraceId = new FallbackExternalTraceId(idGenerator.generateTraceId());
+    const fallbackTraceId = new FallbackExternalTraceId(idGenerator.generateTraceId());
 
     for (const exporter of config.exporters ?? []) {
       spanProcessors.push(
         getEnvVar("TRIGGER_OTEL_BATCH_PROCESSING_ENABLED") === "1"
-          ? new BatchSpanProcessor(new ExternalSpanExporterWrapper(exporter, externalTraceId), {
+          ? new BatchSpanProcessor(new ExternalSpanExporterWrapper(exporter, fallbackTraceId), {
               maxExportBatchSize: parseInt(
                 getEnvVar("TRIGGER_OTEL_SPAN_MAX_EXPORT_BATCH_SIZE") ?? "64"
               ),
@@ -180,7 +180,7 @@ export class TracingSDK {
               ),
               maxQueueSize: parseInt(getEnvVar("TRIGGER_OTEL_SPAN_MAX_QUEUE_SIZE") ?? "512"),
             })
-          : new SimpleSpanProcessor(new ExternalSpanExporterWrapper(exporter, externalTraceId))
+          : new SimpleSpanProcessor(new ExternalSpanExporterWrapper(exporter, fallbackTraceId))
       );
     }
 
@@ -232,7 +232,7 @@ export class TracingSDK {
       logProcessors.push(
         getEnvVar("TRIGGER_OTEL_BATCH_PROCESSING_ENABLED") === "1"
           ? new BatchLogRecordProcessor(
-              new ExternalLogRecordExporterWrapper(externalLogExporter, externalTraceId),
+              new ExternalLogRecordExporterWrapper(externalLogExporter, fallbackTraceId),
               {
                 maxExportBatchSize: parseInt(
                   getEnvVar("TRIGGER_OTEL_LOG_MAX_EXPORT_BATCH_SIZE") ?? "64"
@@ -247,7 +247,7 @@ export class TracingSDK {
               }
             )
           : new SimpleLogRecordProcessor(
-              new ExternalLogRecordExporterWrapper(externalLogExporter, externalTraceId)
+              new ExternalLogRecordExporterWrapper(externalLogExporter, fallbackTraceId)
             )
       );
     }
@@ -394,55 +394,41 @@ function setLogLevel(level: TracingDiagnosticLogLevel) {
   diag.setLogger(new DiagConsoleLogger(), diagLogLevel);
 }
 
-/**
- * Identity of the current run's trace context, or undefined when no run is
- * active.
- *
- * An empty context is not a run: the noop manager returns a fresh `{}` on every
- * call, so treating it as a run would mint a new id on every export.
- */
-function currentRunTraceContext(): object | undefined {
-  const current = traceContext.getTraceContext();
-
-  return current && Object.keys(current).length > 0 ? current : undefined;
-}
-
 /**
  * The external trace id used by runs that carry no external trace context,
  * minted once per run.
  *
  * It has to change per run for the same reason the wrappers read the external
  * context live: with `processKeepAlive` the `TracingSDK` — and so the wrappers
  * — outlive the run, so an id captured at construction merges every run on the
- * process into one trace. The manager's trace context object is reassigned per
- * run, which makes its identity the run boundary.
+ * process into one trace.
  *
  * One instance is shared by every wrapper, so a run's spans and logs still
  * agree on the id after a remint.
  */
 export class FallbackExternalTraceId {
   private traceId: string;
-  private seenTraceContext: object | undefined;
+  private seenEpoch: number;
 
   constructor(
     private seed: string,
     private traceIdGenerator: Pick<RandomIdGenerator, "generateTraceId"> = idGenerator
   ) {
     this.traceId = seed;
-    this.seenTraceContext = currentRunTraceContext();
+    this.seenEpoch = traceContext.getTraceContextEpoch();
   }
 
-  get(): string {
+  forCurrentRun(): string {
     // An empty seed means external export is disabled — leave it that way
     // rather than minting an id and switching the feature on.
     if (!this.seed) {
       return this.seed;
     }
 
-    const current = currentRunTraceContext();
+    const epoch = traceContext.getTraceContextEpoch();
 
-    if (current && current !== this.seenTraceContext) {
-      this.seenTraceContext = current;
+    if (epoch !== this.seenEpoch) {
+      this.seenEpoch = epoch;
       this.traceId = this.traceIdGenerator.generateTraceId();
     }
 
@@ -461,7 +447,7 @@ export class ExternalSpanExporterWrapper {
     // standardTraceContextManager.traceContext is honoured on warm-started
     // workers that reuse a single TracingSDK across runs.
     const externalTraceContext = traceContext.getExternalTraceContext();
-    const fallbackTraceId = this.fallback.get();
+    const fallbackTraceId = this.fallback.forCurrentRun();
 
     const isExternallySampled = externalTraceContext
       ? isTraceFlagSampled(externalTraceContext.traceFlags)
@@ -533,15 +519,15 @@ export class ExternalSpanExporterWrapper {
   }
 }
 
-class ExternalLogRecordExporterWrapper {
+export class ExternalLogRecordExporterWrapper {
   constructor(
     private underlyingExporter: LogRecordExporter,
     private fallback: FallbackExternalTraceId
   ) {}
 
   export(logs: any[], resultCallback: (result: any) => void): void {
     const externalTraceContext = traceContext.getExternalTraceContext();
-    const fallbackTraceId = this.fallback.get();
+    const fallbackTraceId = this.fallback.forCurrentRun();
 
     const isExternallySampled = externalTraceContext
       ? isTraceFlagSampled(externalTraceContext.traceFlags)

packages/core/src/v3/traceContext/api.ts

@@ -10,6 +10,11 @@ class NoopTraceContextManager implements TraceContextManager {
     return {};
   }
 
+  // Never advances: with no manager registered there are no runs to separate.
+  getTraceContextEpoch() {
+    return 0;
+  }
+
   reset() {}
 
   getExternalTraceContext() {
@@ -57,6 +62,10 @@ export class TraceContextAPI implements TraceContextManager {
     return this.#getManager().getTraceContext();
   }
 
+  public getTraceContextEpoch() {
+    return this.#getManager().getTraceContextEpoch();
+  }
+
   public getExternalTraceContext() {
     return this.#getManager().getExternalTraceContext();
   }

packages/core/src/v3/traceContext/manager.ts

@@ -4,12 +4,29 @@ import { parseTraceParent } from "@opentelemetry/core";
 import type { TraceContextManager } from "./types.js";
 
 export class StandardTraceContextManager implements TraceContextManager {
-  public traceContext: Record<string, unknown> = {};
+  #traceContext: Record<string, unknown> = {};
+  #epoch = 0;
+
+  // An accessor rather than a plain field so that replacing the context, which
+  // is what starting a run does, is what advances the epoch. Call sites are
+  // unchanged.
+  get traceContext(): Record<string, unknown> {
+    return this.#traceContext;
+  }
+
+  set traceContext(value: Record<string, unknown>) {
+    this.#traceContext = value;
+    this.#epoch++;
+  }
 
   getTraceContext() {
     return this.traceContext;
   }
 
+  getTraceContextEpoch() {
+    return this.#epoch;
+  }
+
   reset() {
     this.traceContext = {};
   }

packages/core/src/v3/traceContext/types.ts

@@ -2,6 +2,12 @@ import type { Context } from "@opentelemetry/api";
 
 export interface TraceContextManager {
   getTraceContext(): Record<string, unknown>;
+  /**
+   * Increments every time the trace context is replaced, which on a worker that
+   * reuses one process across runs is the run boundary. Long-lived consumers
+   * compare it to tell "still the same run" from "a new run started".
+   */
+  getTraceContextEpoch(): number;
   extractContext(): Context;
   reset(): void;
   getExternalTraceContext():