@glasstrace/sdk 1.9.0 → 1.10.0

package/dist/{chunk-RQ5BIWDT.js → chunk-OXM2BZMF.js}

@@ -8,7 +8,7 @@ import {
 } from "./chunk-DQ25VOKK.js";
 import {
   GLASSTRACE_ATTRIBUTE_NAMES
-} from "./chunk-JHUNLPSS.js";
+} from "./chunk-6RKS3DNA.js";
 
 // src/async-context/index.ts
 var ATTR = GLASSTRACE_ATTRIBUTE_NAMES;
@@ -42,10 +42,15 @@ function withAsyncCausality(options, fn) {
   })();
   return async () => {
     const tracer = trace.getTracer(TRACER_NAME);
-    const span = tracer.startSpan(options.name, {
-      root: true,
-      links: capturedContext !== void 0 ? [{ context: capturedContext }] : void 0
-    });
+    let span;
+    try {
+      span = tracer.startSpan(options.name, {
+        root: true,
+        links: capturedContext !== void 0 ? [{ context: capturedContext }] : void 0
+      });
+    } catch {
+      return Promise.resolve(fn());
+    }
     if (isNoopSpan(span)) {
       if (!_skippedUninstalledEmitted) {
         _skippedUninstalledEmitted = true;
@@ -116,4 +121,4 @@ export {
   _resetForTesting,
   withAsyncCausality
 };
-//# sourceMappingURL=chunk-RQ5BIWDT.js.map
+//# sourceMappingURL=chunk-OXM2BZMF.js.map

package/dist/{chunk-RQ5BIWDT.js.map → chunk-OXM2BZMF.js.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/async-context/index.ts"],"sourcesContent":["/**\n * Post-response async causality instrumentation for Glasstrace.\n *\n * Subpath: `@glasstrace/sdk/async-context`\n *\n * This module exposes {@link withAsyncCausality}, a continuation-\n * passing wrapper that captures the active OTel `SpanContext` at call\n * time and binds it to a callback. When the callback runs later\n * (Next.js `after()`, queue dispatchers, webhook fire-and-forget),\n * the wrapper opens a span linked to the originating trace via two\n * channels:\n *\n *   - An OTel `Link` to the captured `SpanContext` — the OTel-native\n *     pointer between two spans in different traces. Surfaces in\n *     standard OTel-aware UIs (Jaeger, Honeycomb, etc.) as a\n *     \"follows from\" relationship.\n *   - A `glasstrace.causal.post_response_async` attribute carrying\n *     the captured trace ID (32-char hex). Used by the product-side\n *     trace-summary transform (per DISC-1539's product handoff) to\n *     reconstruct ownership without resolving the Link. Two\n *     companion booleans\n *     (`glasstrace.causal.affects_http_status` and\n *     `glasstrace.causal.affects_http_duration`) document that the\n *     async work does NOT participate in the root request's outcome.\n *\n * Both channels are emitted together so the SDK is robust to\n * downstream transforms that resolve causality through either form.\n *\n * Edge-runtime safety\n * -------------------\n * The wrapper is included in the SDK's edge bundle\n * (`packages/sdk/src/edge-entry.ts`). Its closure imports only the\n * OTel API, the protocol constants, and the\n * `./optional-lifecycle.js` bridge — none of which reach into\n * `node:*` built-ins or the `process` global. The F003 closure scan\n * (`packages/sdk/scripts/check-edge-bundle.mjs`) enforces this on\n * every build.\n *\n * Strategy: continuation-passing, NOT global ALS propagation\n * ---------------------------------------------------------\n * Per the SDK-046 brief §2.3: ALS continuity across Next.js `after()`\n * is uncertain (the framework may schedule via `queueMicrotask`\n * (preserves ALS) or via cross-tick scheduling (drops ALS)). Relying\n * on ALS would couple the SDK to Next internals. Continuation-passing\n * makes the causality explicit — the user wraps the callback they\n * pass to `after()` / their queue, and the captured `SpanContext`\n * travels with the closure regardless of how the framework schedules\n * it.\n *\n * @module @glasstrace/sdk/async-context\n */\n\nimport {\n  trace,\n  context,\n  SpanStatusCode,\n  type AttributeValue,\n  type SpanContext,\n} from \"@opentelemetry/api\";\nimport { GLASSTRACE_ATTRIBUTE_NAMES } from \"@glasstrace/protocol\";\nimport { tryEmitLifecycleEvent } from \"../optional-lifecycle.js\";\n\nconst ATTR = GLASSTRACE_ATTRIBUTE_NAMES;\n\n/**\n * Module-level OTel tracer name for the async-context subpath.\n * Resolves through the global `ProxyTracerProvider` so the wrapper\n * picks up whatever provider the SDK has registered. Re-resolved on\n * every call site rather than cached at module top level so test\n * harnesses can install a provider after this module is imported.\n * Mirrors the tRPC subpath at `packages/sdk/src/trpc/index.ts:128`.\n */\nconst TRACER_NAME = \"@glasstrace/sdk/async-context\";\n\n/**\n * The W3C-spec-defined invalid trace ID. The OTel API noop tracer\n * returns this value from `Span.spanContext().traceId`. We use this\n * to detect both (a) the SDK-not-registered case via the\n * noop-tracer probe and (b) the no-active-span case via the\n * captured `SpanContext`.\n */\nconst INVALID_TRACE_ID = \"00000000000000000000000000000000\";\n\n/**\n * Module-level once-flags for lifecycle events. Cleared via\n * {@link _resetForTesting}.\n */\nlet _skippedUninstalledEmitted = false;\nlet _noOriginatingContextEmitted = false;\n\n/**\n * INTERNAL — clears once-flags for unit tests; not part of the\n * public surface.\n */\nexport function _resetForTesting(): void {\n  _skippedUninstalledEmitted = false;\n  _noOriginatingContextEmitted = false;\n}\n\n/**\n * Options for {@link withAsyncCausality}.\n *\n * @example\n * ```ts\n * import { withAsyncCausality } from \"@glasstrace/sdk/async-context\";\n * import { after } from \"next/server\";\n *\n * export async function POST(req: Request) {\n *   const result = await processRequest(req);\n *   after(\n *     withAsyncCausality(\n *       { name: \"send-confirmation-email\" },\n *       async () => sendEmail(result.userId),\n *     ),\n *   );\n *   return Response.json({ ok: true });\n * }\n * ```\n */\nexport interface WithAsyncCausalityOptions {\n  /**\n   * Span name for the async work. Required, non-empty string. Used as\n   * the OTel span name and appears in trace timelines. Names should\n   * be stable across runs (e.g., \"send-confirmation-email\",\n   * \"enqueue-webhook-dispatch\"); avoid embedding payload data in the\n   * name.\n   */\n  name: string;\n  /**\n   * Optional attributes attached to the span before the wrapped\n   * callback runs. Forwarded to OTel as-is via `span.setAttributes()`.\n   * The SDK does not redact, sanitize, or scan values here — callers\n   * MUST avoid placing tokens, credentials, or other sensitive data\n   * in `attributes`.\n   */\n  attributes?: Record<string, AttributeValue>;\n}\n\n/**\n * Capture the active OTel `SpanContext` at call time, bind it to a\n * callback, and return a continuation that will emit a\n * causally-linked span when invoked.\n *\n * The returned continuation:\n *\n *   1. Detects the SDK's registration state. When the OTel API is\n *      still on the noop tracer, runs the wrapped callback directly\n *      and emits an `async:skipped_uninstalled` lifecycle event (at\n *      most once per process). No span is opened.\n *   2. Otherwise opens a span named `options.name` as a NEW root\n *      span (not parented to the captured context — `after()` /\n *      queue dispatchers run outside the originating request's OTel\n *      context, so the async work belongs to a separate trace).\n *   3. When a captured `SpanContext` exists with a valid trace ID,\n *      attaches:\n *        - an OTel `Link` to that `SpanContext` (the OTel-native\n *          form),\n *        - the `glasstrace.causal.post_response_async` attribute\n *          carrying the trace ID (the transform-readable form),\n *        - `glasstrace.causal.affects_http_status = false` and\n *          `glasstrace.causal.affects_http_duration = false`\n *          documenting that the async work does NOT participate in\n *          the root request's outcome.\n *      When no valid `SpanContext` was captured, none of these are\n *      emitted (per SDK-046's \"missing or unknown evidence is\n *      preferable to guessed evidence\" rule) and an\n *      `async:no_originating_context` lifecycle event fires (at\n *      most once per process).\n *   4. Awaits the wrapped callback.\n *   5. On a thrown error: normalizes the throwable; sets `ERROR`\n *      status with `recordException`; rethrows the original error\n *      verbatim.\n *   6. On a successful return: leaves status `UNSET`.\n *   7. Always ends the span.\n *\n * The continuation returns a Promise resolving to the callback's\n * return value (Promise-or-value semantics: a sync callback's value\n * is wrapped in `Promise.resolve()`).\n *\n * @param options - Span name and optional pre-start attributes.\n * @param fn - The async callback to run later. May be sync or async;\n *   the wrapper always returns a Promise to give a consistent\n *   continuation shape regardless of `fn`'s synchronicity.\n * @returns A continuation `() => Promise<T>` that, when invoked,\n *   emits the causally-linked span and runs `fn`.\n *\n * @example Next.js after() — typical use\n * ```ts\n * import { withAsyncCausality } from \"@glasstrace/sdk/async-context\";\n * import { after } from \"next/server\";\n *\n * export async function POST(req: Request) {\n *   const result = await processRequest(req);\n *   after(\n *     withAsyncCausality(\n *       { name: \"send-confirmation-email\" },\n *       async () => sendEmail(result.userId),\n *     ),\n *   );\n *   return Response.json({ ok: true });\n * }\n * ```\n *\n * @example Queue dispatcher — capture before enqueue\n * ```ts\n * const dispatch = withAsyncCausality(\n *   { name: \"process-webhook\" },\n *   async () => handler(payload),\n * );\n * await queue.enqueue(dispatch);\n * ```\n */\nexport function withAsyncCausality<T>(\n  options: WithAsyncCausalityOptions,\n  fn: () => Promise<T> | T,\n): () => Promise<T> {\n  if (typeof options.name !== \"string\" || options.name.length === 0) {\n    throw new TypeError(\n      \"withAsyncCausality: options.name must be a non-empty string\",\n    );\n  }\n  if (typeof fn !== \"function\") {\n    throw new TypeError(\"withAsyncCausality: fn must be a function\");\n  }\n\n  // Capture-time: snapshot the active SpanContext, if any. The\n  // capture happens synchronously in the wrapper-construction call,\n  // BEFORE the user passes the continuation to `after()` /\n  // `queue.enqueue()`. Reading via `trace.getActiveSpan()` rather\n  // than `context.active()` mirrors `captureCorrelationId()` at\n  // `packages/sdk/src/correlation-id.ts:83` — the active-span API is\n  // the public OTel surface for this.\n  const capturedContext: SpanContext | undefined = (() => {\n    try {\n      const active = trace.getActiveSpan();\n      if (!active) return undefined;\n      const ctx = active.spanContext();\n      // Reject the noop-tracer's invalid trace ID. Treating it as\n      // captured would emit a Link to all-zeros, which is misleading.\n      if (ctx.traceId === INVALID_TRACE_ID) return undefined;\n      return ctx;\n    } catch {\n      return undefined;\n    }\n  })();\n\n  return async (): Promise<T> => {\n    const tracer = trace.getTracer(TRACER_NAME);\n    // The async span is a NEW root: post-response work runs outside\n    // the originating request's OTel context, so parenting to the\n    // captured context would put two unrelated runtime executions in\n    // the same trace tree. Causality is communicated via the Link +\n    // attribute pair instead.\n    const span = tracer.startSpan(options.name, {\n      root: true,\n      links:\n        capturedContext !== undefined\n          ? [{ context: capturedContext }]\n          : undefined,\n    });\n\n    // SDK-not-registered fast path. The public `isRecording()` probe\n    // returns `false` on noop spans without producing an exported\n    // span; this avoids emitting a useless probe span on every\n    // continuation when a real provider is registered.\n    if (isNoopSpan(span)) {\n      if (!_skippedUninstalledEmitted) {\n        _skippedUninstalledEmitted = true;\n        tryEmitLifecycleEvent(\"async:skipped_uninstalled\", {});\n      }\n      endSpanSafely(span);\n      return Promise.resolve(fn());\n    }\n\n    if (capturedContext === undefined && !_noOriginatingContextEmitted) {\n      _noOriginatingContextEmitted = true;\n      tryEmitLifecycleEvent(\"async:no_originating_context\", {});\n    }\n\n    try {\n      if (options.attributes) {\n        span.setAttributes(options.attributes);\n      }\n      if (capturedContext !== undefined) {\n        span.setAttribute(\n          ATTR.CAUSAL_POST_RESPONSE_ASYNC,\n          capturedContext.traceId,\n        );\n        span.setAttribute(ATTR.CAUSAL_AFFECTS_HTTP_STATUS, false);\n        span.setAttribute(ATTR.CAUSAL_AFFECTS_HTTP_DURATION, false);\n      }\n    } catch {\n      // Attribute failures are advisory; do not block fn().\n    }\n\n    try {\n      // Activate the span as the current OTel context during fn()\n      // execution so any nested spans (auto-instrumented OR manual)\n      // are parented under this span. Without `context.with`, the\n      // started span exists but is not in the active context, so\n      // child spans become orphan roots (Copilot review 2026-05-08).\n      // We use `context.with` rather than `tracer.startActiveSpan`\n      // so the existing setup (Link/attribute application above)\n      // can run pre-activation; the existing setup is small but\n      // not trivial to reorder.\n      const value = await context.with(\n        trace.setSpan(context.active(), span),\n        fn,\n      );\n      return value;\n    } catch (error) {\n      recordSpanError(span, error);\n      throw error;\n    } finally {\n      endSpanSafely(span);\n    }\n  };\n}\n\n/**\n * Type guard for OTel noop spans. Mirrors the same check in\n * `../middleware/index.ts`. The OTel API's noop tracer\n * (`@opentelemetry/api`'s `NonRecordingSpan`) returns the all-zeros\n * sentinel trace ID `00000000000000000000000000000000` from\n * `Span.spanContext().traceId`. Real SDK-emitted spans — including\n * spans that a sampler chose to DROP (which legitimately return\n * `isRecording() === false`) — return a valid 32-char hex trace ID\n * because the SDK assigns a trace ID before sampler invocation for\n * propagation purposes. Using the SpanContext discriminator keeps\n * the SDK-not-registered fast path from misfiring under normal head\n * sampling configurations (Copilot review 2026-05-08).\n */\nfunction isNoopSpan(\n  span: ReturnType<ReturnType<typeof trace.getTracer>[\"startSpan\"]>,\n): boolean {\n  try {\n    return span.spanContext().traceId === INVALID_TRACE_ID;\n  } catch {\n    return false;\n  }\n}\n\n/**\n * See {@link ../middleware/index.ts} — duplicated here rather than\n * shared because the OTel `Span` type is structural and importing\n * a helper from a sibling module would force the modules to share a\n * deeper dependency. Both copies are exactly two non-throwing\n * `try`/`catch` blocks; the duplication is intentional and trivial.\n */\nfunction recordSpanError(\n  span: ReturnType<ReturnType<typeof trace.getTracer>[\"startSpan\"]>,\n  error: unknown,\n): void {\n  const normalized: Error | string =\n    error instanceof Error\n      ? error\n      : typeof error === \"string\"\n        ? error\n        : new Error(String(error));\n  const statusMessage =\n    normalized instanceof Error ? normalized.message : normalized;\n  try {\n    span.recordException(normalized);\n  } catch {\n    /* swallow */\n  }\n  try {\n    span.setStatus({ code: SpanStatusCode.ERROR, message: statusMessage });\n  } catch {\n    /* swallow */\n  }\n}\n\n/** See {@link ../middleware/index.ts}. */\nfunction endSpanSafely(\n  span: ReturnType<ReturnType<typeof trace.getTracer>[\"startSpan\"]>,\n): void {\n  try {\n    span.end();\n  } catch {\n    /* swallow */\n  }\n}\n"],"mappings":";;;;;;;;;;;;;AA8DA,IAAM,OAAO;AAUb,IAAM,cAAc;AASpB,IAAM,mBAAmB;AAMzB,IAAI,6BAA6B;AACjC,IAAI,+BAA+B;AAM5B,SAAS,mBAAyB;AACvC,+BAA6B;AAC7B,iCAA+B;AACjC;AAmHO,SAAS,mBACd,SACA,IACkB;AAClB,MAAI,OAAO,QAAQ,SAAS,YAAY,QAAQ,KAAK,WAAW,GAAG;AACjE,UAAM,IAAI;AAAA,MACR;AAAA,IACF;AAAA,EACF;AACA,MAAI,OAAO,OAAO,YAAY;AAC5B,UAAM,IAAI,UAAU,2CAA2C;AAAA,EACjE;AASA,QAAM,mBAA4C,MAAM;AACtD,QAAI;AACF,YAAM,SAAS,MAAM,cAAc;AACnC,UAAI,CAAC,OAAQ,QAAO;AACpB,YAAM,MAAM,OAAO,YAAY;AAG/B,UAAI,IAAI,YAAY,iBAAkB,QAAO;AAC7C,aAAO;AAAA,IACT,QAAQ;AACN,aAAO;AAAA,IACT;AAAA,EACF,GAAG;AAEH,SAAO,YAAwB;AAC7B,UAAM,SAAS,MAAM,UAAU,WAAW;AAM1C,UAAM,OAAO,OAAO,UAAU,QAAQ,MAAM;AAAA,MAC1C,MAAM;AAAA,MACN,OACE,oBAAoB,SAChB,CAAC,EAAE,SAAS,gBAAgB,CAAC,IAC7B;AAAA,IACR,CAAC;AAMD,QAAI,WAAW,IAAI,GAAG;AACpB,UAAI,CAAC,4BAA4B;AAC/B,qCAA6B;AAC7B,8BAAsB,6BAA6B,CAAC,CAAC;AAAA,MACvD;AACA,oBAAc,IAAI;AAClB,aAAO,QAAQ,QAAQ,GAAG,CAAC;AAAA,IAC7B;AAEA,QAAI,oBAAoB,UAAa,CAAC,8BAA8B;AAClE,qCAA+B;AAC/B,4BAAsB,gCAAgC,CAAC,CAAC;AAAA,IAC1D;AAEA,QAAI;AACF,UAAI,QAAQ,YAAY;AACtB,aAAK,cAAc,QAAQ,UAAU;AAAA,MACvC;AACA,UAAI,oBAAoB,QAAW;AACjC,aAAK;AAAA,UACH,KAAK;AAAA,UACL,gBAAgB;AAAA,QAClB;AACA,aAAK,aAAa,KAAK,4BAA4B,KAAK;AACxD,aAAK,aAAa,KAAK,8BAA8B,KAAK;AAAA,MAC5D;AAAA,IACF,QAAQ;AAAA,IAER;AAEA,QAAI;AAUF,YAAM,QAAQ,MAAM,QAAQ;AAAA,QAC1B,MAAM,QAAQ,QAAQ,OAAO,GAAG,IAAI;AAAA,QACpC;AAAA,MACF;AACA,aAAO;AAAA,IACT,SAAS,OAAO;AACd,sBAAgB,MAAM,KAAK;AAC3B,YAAM;AAAA,IACR,UAAE;AACA,oBAAc,IAAI;AAAA,IACpB;AAAA,EACF;AACF;AAeA,SAAS,WACP,MACS;AACT,MAAI;AACF,WAAO,KAAK,YAAY,EAAE,YAAY;AAAA,EACxC,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AASA,SAAS,gBACP,MACA,OACM;AACN,QAAM,aACJ,iBAAiB,QACb,QACA,OAAO,UAAU,WACf,QACA,IAAI,MAAM,OAAO,KAAK,CAAC;AAC/B,QAAM,gBACJ,sBAAsB,QAAQ,WAAW,UAAU;AACrD,MAAI;AACF,SAAK,gBAAgB,UAAU;AAAA,EACjC,QAAQ;AAAA,EAER;AACA,MAAI;AACF,SAAK,UAAU,EAAE,MAAM,eAAe,OAAO,SAAS,cAAc,CAAC;AAAA,EACvE,QAAQ;AAAA,EAER;AACF;AAGA,SAAS,cACP,MACM;AACN,MAAI;AACF,SAAK,IAAI;AAAA,EACX,QAAQ;AAAA,EAER;AACF;","names":[]}
+{"version":3,"sources":["../src/async-context/index.ts"],"sourcesContent":["/**\n * Post-response async causality instrumentation for Glasstrace.\n *\n * Subpath: `@glasstrace/sdk/async-context`\n *\n * This module exposes {@link withAsyncCausality}, a continuation-\n * passing wrapper that captures the active OTel `SpanContext` at call\n * time and binds it to a callback. When the callback runs later\n * (Next.js `after()`, queue dispatchers, webhook fire-and-forget),\n * the wrapper opens a span linked to the originating trace via two\n * channels:\n *\n *   - An OTel `Link` to the captured `SpanContext` — the OTel-native\n *     pointer between two spans in different traces. Surfaces in\n *     standard OTel-aware UIs (Jaeger, Honeycomb, etc.) as a\n *     \"follows from\" relationship.\n *   - A `glasstrace.causal.post_response_async` attribute carrying\n *     the captured trace ID (32-char hex). Used by the product-side\n *     trace-summary transform (per DISC-1539's product handoff) to\n *     reconstruct ownership without resolving the Link. Two\n *     companion booleans\n *     (`glasstrace.causal.affects_http_status` and\n *     `glasstrace.causal.affects_http_duration`) document that the\n *     async work does NOT participate in the root request's outcome.\n *\n * Both channels are emitted together so the SDK is robust to\n * downstream transforms that resolve causality through either form.\n *\n * Edge-runtime safety\n * -------------------\n * The wrapper is included in the SDK's edge bundle\n * (`packages/sdk/src/edge-entry.ts`). Its closure imports only the\n * OTel API, the protocol constants, and the\n * `./optional-lifecycle.js` bridge — none of which reach into\n * `node:*` built-ins or the `process` global. The F003 closure scan\n * (`packages/sdk/scripts/check-edge-bundle.mjs`) enforces this on\n * every build.\n *\n * Strategy: continuation-passing, NOT global ALS propagation\n * ---------------------------------------------------------\n * Per the SDK-046 brief §2.3: ALS continuity across Next.js `after()`\n * is uncertain (the framework may schedule via `queueMicrotask`\n * (preserves ALS) or via cross-tick scheduling (drops ALS)). Relying\n * on ALS would couple the SDK to Next internals. Continuation-passing\n * makes the causality explicit — the user wraps the callback they\n * pass to `after()` / their queue, and the captured `SpanContext`\n * travels with the closure regardless of how the framework schedules\n * it.\n *\n * @module @glasstrace/sdk/async-context\n */\n\nimport {\n  trace,\n  context,\n  SpanStatusCode,\n  type AttributeValue,\n  type SpanContext,\n} from \"@opentelemetry/api\";\nimport { GLASSTRACE_ATTRIBUTE_NAMES } from \"@glasstrace/protocol\";\nimport { tryEmitLifecycleEvent } from \"../optional-lifecycle.js\";\n\nconst ATTR = GLASSTRACE_ATTRIBUTE_NAMES;\n\n/**\n * Module-level OTel tracer name for the async-context subpath.\n * Resolves through the global `ProxyTracerProvider` so the wrapper\n * picks up whatever provider the SDK has registered. Re-resolved on\n * every call site rather than cached at module top level so test\n * harnesses can install a provider after this module is imported.\n * Mirrors the tRPC subpath at `packages/sdk/src/trpc/index.ts:128`.\n */\nconst TRACER_NAME = \"@glasstrace/sdk/async-context\";\n\n/**\n * The W3C-spec-defined invalid trace ID. The OTel API noop tracer\n * returns this value from `Span.spanContext().traceId`. We use this\n * to detect both (a) the SDK-not-registered case via the\n * noop-tracer probe and (b) the no-active-span case via the\n * captured `SpanContext`.\n */\nconst INVALID_TRACE_ID = \"00000000000000000000000000000000\";\n\n/**\n * Module-level once-flags for lifecycle events. Cleared via\n * {@link _resetForTesting}.\n */\nlet _skippedUninstalledEmitted = false;\nlet _noOriginatingContextEmitted = false;\n\n/**\n * INTERNAL — clears once-flags for unit tests; not part of the\n * public surface.\n */\nexport function _resetForTesting(): void {\n  _skippedUninstalledEmitted = false;\n  _noOriginatingContextEmitted = false;\n}\n\n/**\n * Options for {@link withAsyncCausality}.\n *\n * @example\n * ```ts\n * import { withAsyncCausality } from \"@glasstrace/sdk/async-context\";\n * import { after } from \"next/server\";\n *\n * export async function POST(req: Request) {\n *   const result = await processRequest(req);\n *   after(\n *     withAsyncCausality(\n *       { name: \"send-confirmation-email\" },\n *       async () => sendEmail(result.userId),\n *     ),\n *   );\n *   return Response.json({ ok: true });\n * }\n * ```\n */\nexport interface WithAsyncCausalityOptions {\n  /**\n   * Span name for the async work. Required, non-empty string. Used as\n   * the OTel span name and appears in trace timelines. Names should\n   * be stable across runs (e.g., \"send-confirmation-email\",\n   * \"enqueue-webhook-dispatch\"); avoid embedding payload data in the\n   * name.\n   */\n  name: string;\n  /**\n   * Optional attributes attached to the span before the wrapped\n   * callback runs. Forwarded to OTel as-is via `span.setAttributes()`.\n   * The SDK does not redact, sanitize, or scan values here — callers\n   * MUST avoid placing tokens, credentials, or other sensitive data\n   * in `attributes`.\n   */\n  attributes?: Record<string, AttributeValue>;\n}\n\n/**\n * Capture the active OTel `SpanContext` at call time, bind it to a\n * callback, and return a continuation that will emit a\n * causally-linked span when invoked.\n *\n * The returned continuation:\n *\n *   1. Detects the SDK's registration state. When the OTel API is\n *      still on the noop tracer, runs the wrapped callback directly\n *      and emits an `async:skipped_uninstalled` lifecycle event (at\n *      most once per process). No span is opened.\n *   2. Otherwise opens a span named `options.name` as a NEW root\n *      span (not parented to the captured context — `after()` /\n *      queue dispatchers run outside the originating request's OTel\n *      context, so the async work belongs to a separate trace).\n *   3. When a captured `SpanContext` exists with a valid trace ID,\n *      attaches:\n *        - an OTel `Link` to that `SpanContext` (the OTel-native\n *          form),\n *        - the `glasstrace.causal.post_response_async` attribute\n *          carrying the trace ID (the transform-readable form),\n *        - `glasstrace.causal.affects_http_status = false` and\n *          `glasstrace.causal.affects_http_duration = false`\n *          documenting that the async work does NOT participate in\n *          the root request's outcome.\n *      When no valid `SpanContext` was captured, none of these are\n *      emitted (per SDK-046's \"missing or unknown evidence is\n *      preferable to guessed evidence\" rule) and an\n *      `async:no_originating_context` lifecycle event fires (at\n *      most once per process).\n *   4. Awaits the wrapped callback.\n *   5. On a thrown error: normalizes the throwable; sets `ERROR`\n *      status with `recordException`; rethrows the original error\n *      verbatim.\n *   6. On a successful return: leaves status `UNSET`.\n *   7. Always ends the span.\n *\n * The continuation returns a Promise resolving to the callback's\n * return value (Promise-or-value semantics: a sync callback's value\n * is wrapped in `Promise.resolve()`).\n *\n * @param options - Span name and optional pre-start attributes.\n * @param fn - The async callback to run later. May be sync or async;\n *   the wrapper always returns a Promise to give a consistent\n *   continuation shape regardless of `fn`'s synchronicity.\n * @returns A continuation `() => Promise<T>` that, when invoked,\n *   emits the causally-linked span and runs `fn`.\n *\n * @example Next.js after() — typical use\n * ```ts\n * import { withAsyncCausality } from \"@glasstrace/sdk/async-context\";\n * import { after } from \"next/server\";\n *\n * export async function POST(req: Request) {\n *   const result = await processRequest(req);\n *   after(\n *     withAsyncCausality(\n *       { name: \"send-confirmation-email\" },\n *       async () => sendEmail(result.userId),\n *     ),\n *   );\n *   return Response.json({ ok: true });\n * }\n * ```\n *\n * @example Queue dispatcher — capture before enqueue\n * ```ts\n * const dispatch = withAsyncCausality(\n *   { name: \"process-webhook\" },\n *   async () => handler(payload),\n * );\n * await queue.enqueue(dispatch);\n * ```\n */\nexport function withAsyncCausality<T>(\n  options: WithAsyncCausalityOptions,\n  fn: () => Promise<T> | T,\n): () => Promise<T> {\n  if (typeof options.name !== \"string\" || options.name.length === 0) {\n    throw new TypeError(\n      \"withAsyncCausality: options.name must be a non-empty string\",\n    );\n  }\n  if (typeof fn !== \"function\") {\n    throw new TypeError(\"withAsyncCausality: fn must be a function\");\n  }\n\n  // Capture-time: snapshot the active SpanContext, if any. The\n  // capture happens synchronously in the wrapper-construction call,\n  // BEFORE the user passes the continuation to `after()` /\n  // `queue.enqueue()`. Reading via `trace.getActiveSpan()` rather\n  // than `context.active()` mirrors `captureCorrelationId()` at\n  // `packages/sdk/src/correlation-id.ts:83` — the active-span API is\n  // the public OTel surface for this.\n  const capturedContext: SpanContext | undefined = (() => {\n    try {\n      const active = trace.getActiveSpan();\n      if (!active) return undefined;\n      const ctx = active.spanContext();\n      // Reject the noop-tracer's invalid trace ID. Treating it as\n      // captured would emit a Link to all-zeros, which is misleading.\n      if (ctx.traceId === INVALID_TRACE_ID) return undefined;\n      return ctx;\n    } catch {\n      return undefined;\n    }\n  })();\n\n  return async (): Promise<T> => {\n    const tracer = trace.getTracer(TRACER_NAME);\n    // The async span is a NEW root: post-response work runs outside\n    // the originating request's OTel context, so parenting to the\n    // captured context would put two unrelated runtime executions in\n    // the same trace tree. Causality is communicated via the Link +\n    // attribute pair instead.\n    //\n    // Defensive wrap around `tracer.startSpan` itself. OTel's noop\n    // tracer never throws; a real provider's startSpan could throw\n    // under a misbehaving custom processor in coexistence. If the\n    // tracer call throws, instrumentation must not break the user's\n    // continuation — fall back to running fn() directly.\n    let span: ReturnType<typeof tracer.startSpan>;\n    try {\n      span = tracer.startSpan(options.name, {\n        root: true,\n        links:\n          capturedContext !== undefined\n            ? [{ context: capturedContext }]\n            : undefined,\n      });\n    } catch {\n      return Promise.resolve(fn());\n    }\n\n    // SDK-not-registered fast path. The public `isRecording()` probe\n    // returns `false` on noop spans without producing an exported\n    // span; this avoids emitting a useless probe span on every\n    // continuation when a real provider is registered.\n    if (isNoopSpan(span)) {\n      if (!_skippedUninstalledEmitted) {\n        _skippedUninstalledEmitted = true;\n        tryEmitLifecycleEvent(\"async:skipped_uninstalled\", {});\n      }\n      endSpanSafely(span);\n      return Promise.resolve(fn());\n    }\n\n    if (capturedContext === undefined && !_noOriginatingContextEmitted) {\n      _noOriginatingContextEmitted = true;\n      tryEmitLifecycleEvent(\"async:no_originating_context\", {});\n    }\n\n    try {\n      if (options.attributes) {\n        span.setAttributes(options.attributes);\n      }\n      if (capturedContext !== undefined) {\n        span.setAttribute(\n          ATTR.CAUSAL_POST_RESPONSE_ASYNC,\n          capturedContext.traceId,\n        );\n        span.setAttribute(ATTR.CAUSAL_AFFECTS_HTTP_STATUS, false);\n        span.setAttribute(ATTR.CAUSAL_AFFECTS_HTTP_DURATION, false);\n      }\n    } catch {\n      // Attribute failures are advisory; do not block fn().\n    }\n\n    try {\n      // Activate the span as the current OTel context during fn()\n      // execution so any nested spans (auto-instrumented OR manual)\n      // are parented under this span. Without `context.with`, the\n      // started span exists but is not in the active context, so\n      // child spans become orphan roots (Copilot review 2026-05-08).\n      // We use `context.with` rather than `tracer.startActiveSpan`\n      // so the existing setup (Link/attribute application above)\n      // can run pre-activation; the existing setup is small but\n      // not trivial to reorder.\n      const value = await context.with(\n        trace.setSpan(context.active(), span),\n        fn,\n      );\n      return value;\n    } catch (error) {\n      recordSpanError(span, error);\n      throw error;\n    } finally {\n      endSpanSafely(span);\n    }\n  };\n}\n\n/**\n * Type guard for OTel noop spans. Mirrors the same check in\n * `../middleware/index.ts`. The OTel API's noop tracer\n * (`@opentelemetry/api`'s `NonRecordingSpan`) returns the all-zeros\n * sentinel trace ID `00000000000000000000000000000000` from\n * `Span.spanContext().traceId`. Real SDK-emitted spans — including\n * spans that a sampler chose to DROP (which legitimately return\n * `isRecording() === false`) — return a valid 32-char hex trace ID\n * because the SDK assigns a trace ID before sampler invocation for\n * propagation purposes. Using the SpanContext discriminator keeps\n * the SDK-not-registered fast path from misfiring under normal head\n * sampling configurations (Copilot review 2026-05-08).\n */\nfunction isNoopSpan(\n  span: ReturnType<ReturnType<typeof trace.getTracer>[\"startSpan\"]>,\n): boolean {\n  try {\n    return span.spanContext().traceId === INVALID_TRACE_ID;\n  } catch {\n    return false;\n  }\n}\n\n/**\n * See {@link ../middleware/index.ts} — duplicated here rather than\n * shared because the OTel `Span` type is structural and importing\n * a helper from a sibling module would force the modules to share a\n * deeper dependency. Both copies are exactly two non-throwing\n * `try`/`catch` blocks; the duplication is intentional and trivial.\n */\nfunction recordSpanError(\n  span: ReturnType<ReturnType<typeof trace.getTracer>[\"startSpan\"]>,\n  error: unknown,\n): void {\n  const normalized: Error | string =\n    error instanceof Error\n      ? error\n      : typeof error === \"string\"\n        ? error\n        : new Error(String(error));\n  const statusMessage =\n    normalized instanceof Error ? normalized.message : normalized;\n  try {\n    span.recordException(normalized);\n  } catch {\n    /* swallow */\n  }\n  try {\n    span.setStatus({ code: SpanStatusCode.ERROR, message: statusMessage });\n  } catch {\n    /* swallow */\n  }\n}\n\n/** See {@link ../middleware/index.ts}. */\nfunction endSpanSafely(\n  span: ReturnType<ReturnType<typeof trace.getTracer>[\"startSpan\"]>,\n): void {\n  try {\n    span.end();\n  } catch {\n    /* swallow */\n  }\n}\n"],"mappings":";;;;;;;;;;;;;AA8DA,IAAM,OAAO;AAUb,IAAM,cAAc;AASpB,IAAM,mBAAmB;AAMzB,IAAI,6BAA6B;AACjC,IAAI,+BAA+B;AAM5B,SAAS,mBAAyB;AACvC,+BAA6B;AAC7B,iCAA+B;AACjC;AAmHO,SAAS,mBACd,SACA,IACkB;AAClB,MAAI,OAAO,QAAQ,SAAS,YAAY,QAAQ,KAAK,WAAW,GAAG;AACjE,UAAM,IAAI;AAAA,MACR;AAAA,IACF;AAAA,EACF;AACA,MAAI,OAAO,OAAO,YAAY;AAC5B,UAAM,IAAI,UAAU,2CAA2C;AAAA,EACjE;AASA,QAAM,mBAA4C,MAAM;AACtD,QAAI;AACF,YAAM,SAAS,MAAM,cAAc;AACnC,UAAI,CAAC,OAAQ,QAAO;AACpB,YAAM,MAAM,OAAO,YAAY;AAG/B,UAAI,IAAI,YAAY,iBAAkB,QAAO;AAC7C,aAAO;AAAA,IACT,QAAQ;AACN,aAAO;AAAA,IACT;AAAA,EACF,GAAG;AAEH,SAAO,YAAwB;AAC7B,UAAM,SAAS,MAAM,UAAU,WAAW;AAY1C,QAAI;AACJ,QAAI;AACF,aAAO,OAAO,UAAU,QAAQ,MAAM;AAAA,QACpC,MAAM;AAAA,QACN,OACE,oBAAoB,SAChB,CAAC,EAAE,SAAS,gBAAgB,CAAC,IAC7B;AAAA,MACR,CAAC;AAAA,IACH,QAAQ;AACN,aAAO,QAAQ,QAAQ,GAAG,CAAC;AAAA,IAC7B;AAMA,QAAI,WAAW,IAAI,GAAG;AACpB,UAAI,CAAC,4BAA4B;AAC/B,qCAA6B;AAC7B,8BAAsB,6BAA6B,CAAC,CAAC;AAAA,MACvD;AACA,oBAAc,IAAI;AAClB,aAAO,QAAQ,QAAQ,GAAG,CAAC;AAAA,IAC7B;AAEA,QAAI,oBAAoB,UAAa,CAAC,8BAA8B;AAClE,qCAA+B;AAC/B,4BAAsB,gCAAgC,CAAC,CAAC;AAAA,IAC1D;AAEA,QAAI;AACF,UAAI,QAAQ,YAAY;AACtB,aAAK,cAAc,QAAQ,UAAU;AAAA,MACvC;AACA,UAAI,oBAAoB,QAAW;AACjC,aAAK;AAAA,UACH,KAAK;AAAA,UACL,gBAAgB;AAAA,QAClB;AACA,aAAK,aAAa,KAAK,4BAA4B,KAAK;AACxD,aAAK,aAAa,KAAK,8BAA8B,KAAK;AAAA,MAC5D;AAAA,IACF,QAAQ;AAAA,IAER;AAEA,QAAI;AAUF,YAAM,QAAQ,MAAM,QAAQ;AAAA,QAC1B,MAAM,QAAQ,QAAQ,OAAO,GAAG,IAAI;AAAA,QACpC;AAAA,MACF;AACA,aAAO;AAAA,IACT,SAAS,OAAO;AACd,sBAAgB,MAAM,KAAK;AAC3B,YAAM;AAAA,IACR,UAAE;AACA,oBAAc,IAAI;AAAA,IACpB;AAAA,EACF;AACF;AAeA,SAAS,WACP,MACS;AACT,MAAI;AACF,WAAO,KAAK,YAAY,EAAE,YAAY;AAAA,EACxC,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AASA,SAAS,gBACP,MACA,OACM;AACN,QAAM,aACJ,iBAAiB,QACb,QACA,OAAO,UAAU,WACf,QACA,IAAI,MAAM,OAAO,KAAK,CAAC;AAC/B,QAAM,gBACJ,sBAAsB,QAAQ,WAAW,UAAU;AACrD,MAAI;AACF,SAAK,gBAAgB,UAAU;AAAA,EACjC,QAAQ;AAAA,EAER;AACA,MAAI;AACF,SAAK,UAAU,EAAE,MAAM,eAAe,OAAO,SAAS,cAAc,CAAC;AAAA,EACvE,QAAQ;AAAA,EAER;AACF;AAGA,SAAS,cACP,MACM;AACN,MAAI;AACF,SAAK,IAAI;AAAA,EACX,QAAQ;AAAA,EAER;AACF;","names":[]}

package/dist/{chunk-M6EWJCAT.js → chunk-QVTONMVZ.js}

@@ -5,7 +5,7 @@ import {
   PresignedUploadResponseSchema,
   SourceMapManifestResponseSchema,
   SourceMapUploadResponseSchema
-} from "./chunk-JHUNLPSS.js";
+} from "./chunk-6RKS3DNA.js";
 
 // src/source-map-uploader.ts
 import * as fs from "node:fs/promises";
@@ -331,4 +331,4 @@ export {
   uploadSourceMapsPresigned,
   uploadSourceMapsAuto
 };
-//# sourceMappingURL=chunk-M6EWJCAT.js.map
+//# sourceMappingURL=chunk-QVTONMVZ.js.map

package/dist/{chunk-DKV53A2C.js → chunk-RL43PU2X.js}

@@ -2,7 +2,7 @@ import {
   AnonApiKeySchema,
   DevApiKeySchema,
   createAnonApiKey
-} from "./chunk-JHUNLPSS.js";
+} from "./chunk-6RKS3DNA.js";
 import {
   __require
 } from "./chunk-NSBPE2FW.js";
@@ -659,4 +659,4 @@ export {
   writeMcpMarker,
   refreshGenericMcpConfigAtRuntime
 };
-//# sourceMappingURL=chunk-DKV53A2C.js.map
+//# sourceMappingURL=chunk-RL43PU2X.js.map

package/dist/{chunk-GWIEUBFR.js → chunk-UMGZJYC4.js}

@@ -5,10 +5,10 @@ import {
   isDevApiKey,
   readEnvLocalApiKey,
   writeAndFsyncTempSync
-} from "./chunk-DKV53A2C.js";
+} from "./chunk-RL43PU2X.js";
 import {
   AnonApiKeySchema
-} from "./chunk-JHUNLPSS.js";
+} from "./chunk-6RKS3DNA.js";
 import {
   NEXT_CONFIG_NAMES
 } from "./chunk-NB7GJE4S.js";
@@ -917,4 +917,4 @@ export {
   writeShutdownMarker,
   runUninit
 };
-//# sourceMappingURL=chunk-GWIEUBFR.js.map
+//# sourceMappingURL=chunk-UMGZJYC4.js.map

package/dist/{chunk-QXITSNYM.js → chunk-XG6WR2KS.js}

@@ -2,12 +2,12 @@ import {
   atomicWriteFile,
   refreshGenericMcpConfigAtRuntime,
   resolveEffectiveMcpCredential
-} from "./chunk-DKV53A2C.js";
+} from "./chunk-RL43PU2X.js";
 import {
   DEFAULT_CAPTURE_CONFIG,
   SdkCachedConfigSchema,
   SdkInitResponseSchema
-} from "./chunk-JHUNLPSS.js";
+} from "./chunk-6RKS3DNA.js";
 import {
   __require
 } from "./chunk-NSBPE2FW.js";
@@ -692,4 +692,4 @@ export {
   didLastInitSucceed,
   verifyInitReachable
 };
-//# sourceMappingURL=chunk-QXITSNYM.js.map
+//# sourceMappingURL=chunk-XG6WR2KS.js.map

package/dist/cli/init.cjs

@@ -16994,7 +16994,7 @@ async function mcpAdd(options) {
   const bearer = resolved.effective.key;
   for (const agent of targetAgents) {
     const name = formatAgentName(agent.name);
-    const sdkVersion = true ? "1.9.0" : "0.0.0-dev";
+    const sdkVersion = true ? "1.10.0" : "0.0.0-dev";
     if (agent.name !== "generic") {
       const cliSuccess = await registerViaCli(agent, bearer);
       if (cliSuccess) {
@@ -17262,7 +17262,7 @@ async function runUpgradeInstructions(options) {
     );
     return { exitCode: 1, refreshed, skipped, warnings, errors };
   }
-  const sdkVersion = true ? "1.9.0" : "0.0.0-dev";
+  const sdkVersion = true ? "1.10.0" : "0.0.0-dev";
   for (const agent of agents) {
     if (agent.infoFilePath === null) {
       continue;
@@ -18902,7 +18902,7 @@ Then add this as the first statement in your register() function:
           }
           anyConfigWritten = true;
           anyConfigRewrittenWithBearer = true;
-          const sdkVersionForInject = true ? "1.9.0" : "0.0.0-dev";
+          const sdkVersionForInject = true ? "1.10.0" : "0.0.0-dev";
           const infoContent = generateInfoSection(
             agent,
             MCP_ENDPOINT,
@@ -19008,7 +19008,7 @@ async function verifyAnonKeyRegistration(projectRoot) {
   }
   const baseConfig = resolveConfig({ apiKey: devKey });
   const config2 = { ...baseConfig, apiKey: devKey };
-  const sdkVersion = true ? "1.9.0" : "0.0.0-dev";
+  const sdkVersion = true ? "1.10.0" : "0.0.0-dev";
   const result = await verifyInitReachable(config2, anonKey, sdkVersion);
   if (result.ok) {
     return { outcome: "verified" };