@glasstrace/sdk 1.8.0 → 1.9.1

package/dist/async-context/index.d.cts

@@ -0,0 +1,174 @@
+import { AttributeValue } from './common/Attributes';
+
+/**
+ * Post-response async causality instrumentation for Glasstrace.
+ *
+ * Subpath: `@glasstrace/sdk/async-context`
+ *
+ * This module exposes {@link withAsyncCausality}, a continuation-
+ * passing wrapper that captures the active OTel `SpanContext` at call
+ * time and binds it to a callback. When the callback runs later
+ * (Next.js `after()`, queue dispatchers, webhook fire-and-forget),
+ * the wrapper opens a span linked to the originating trace via two
+ * channels:
+ *
+ *   - An OTel `Link` to the captured `SpanContext` — the OTel-native
+ *     pointer between two spans in different traces. Surfaces in
+ *     standard OTel-aware UIs (Jaeger, Honeycomb, etc.) as a
+ *     "follows from" relationship.
+ *   - A `glasstrace.causal.post_response_async` attribute carrying
+ *     the captured trace ID (32-char hex). Used by the product-side
+ *     trace-summary transform (per DISC-1539's product handoff) to
+ *     reconstruct ownership without resolving the Link. Two
+ *     companion booleans
+ *     (`glasstrace.causal.affects_http_status` and
+ *     `glasstrace.causal.affects_http_duration`) document that the
+ *     async work does NOT participate in the root request's outcome.
+ *
+ * Both channels are emitted together so the SDK is robust to
+ * downstream transforms that resolve causality through either form.
+ *
+ * Edge-runtime safety
+ * -------------------
+ * The wrapper is included in the SDK's edge bundle
+ * (`packages/sdk/src/edge-entry.ts`). Its closure imports only the
+ * OTel API, the protocol constants, and the
+ * `./optional-lifecycle.js` bridge — none of which reach into
+ * `node:*` built-ins or the `process` global. The F003 closure scan
+ * (`packages/sdk/scripts/check-edge-bundle.mjs`) enforces this on
+ * every build.
+ *
+ * Strategy: continuation-passing, NOT global ALS propagation
+ * ---------------------------------------------------------
+ * Per the SDK-046 brief §2.3: ALS continuity across Next.js `after()`
+ * is uncertain (the framework may schedule via `queueMicrotask`
+ * (preserves ALS) or via cross-tick scheduling (drops ALS)). Relying
+ * on ALS would couple the SDK to Next internals. Continuation-passing
+ * makes the causality explicit — the user wraps the callback they
+ * pass to `after()` / their queue, and the captured `SpanContext`
+ * travels with the closure regardless of how the framework schedules
+ * it.
+ *
+ * @module @glasstrace/sdk/async-context
+ */
+
+/**
+ * INTERNAL — clears once-flags for unit tests; not part of the
+ * public surface.
+ */
+declare function _resetForTesting(): void;
+/**
+ * Options for {@link withAsyncCausality}.
+ *
+ * @example
+ * ```ts
+ * import { withAsyncCausality } from "@glasstrace/sdk/async-context";
+ * import { after } from "next/server";
+ *
+ * export async function POST(req: Request) {
+ *   const result = await processRequest(req);
+ *   after(
+ *     withAsyncCausality(
+ *       { name: "send-confirmation-email" },
+ *       async () => sendEmail(result.userId),
+ *     ),
+ *   );
+ *   return Response.json({ ok: true });
+ * }
+ * ```
+ */
+interface WithAsyncCausalityOptions {
+    /**
+     * Span name for the async work. Required, non-empty string. Used as
+     * the OTel span name and appears in trace timelines. Names should
+     * be stable across runs (e.g., "send-confirmation-email",
+     * "enqueue-webhook-dispatch"); avoid embedding payload data in the
+     * name.
+     */
+    name: string;
+    /**
+     * Optional attributes attached to the span before the wrapped
+     * callback runs. Forwarded to OTel as-is via `span.setAttributes()`.
+     * The SDK does not redact, sanitize, or scan values here — callers
+     * MUST avoid placing tokens, credentials, or other sensitive data
+     * in `attributes`.
+     */
+    attributes?: Record<string, AttributeValue>;
+}
+/**
+ * Capture the active OTel `SpanContext` at call time, bind it to a
+ * callback, and return a continuation that will emit a
+ * causally-linked span when invoked.
+ *
+ * The returned continuation:
+ *
+ *   1. Detects the SDK's registration state. When the OTel API is
+ *      still on the noop tracer, runs the wrapped callback directly
+ *      and emits an `async:skipped_uninstalled` lifecycle event (at
+ *      most once per process). No span is opened.
+ *   2. Otherwise opens a span named `options.name` as a NEW root
+ *      span (not parented to the captured context — `after()` /
+ *      queue dispatchers run outside the originating request's OTel
+ *      context, so the async work belongs to a separate trace).
+ *   3. When a captured `SpanContext` exists with a valid trace ID,
+ *      attaches:
+ *        - an OTel `Link` to that `SpanContext` (the OTel-native
+ *          form),
+ *        - the `glasstrace.causal.post_response_async` attribute
+ *          carrying the trace ID (the transform-readable form),
+ *        - `glasstrace.causal.affects_http_status = false` and
+ *          `glasstrace.causal.affects_http_duration = false`
+ *          documenting that the async work does NOT participate in
+ *          the root request's outcome.
+ *      When no valid `SpanContext` was captured, none of these are
+ *      emitted (per SDK-046's "missing or unknown evidence is
+ *      preferable to guessed evidence" rule) and an
+ *      `async:no_originating_context` lifecycle event fires (at
+ *      most once per process).
+ *   4. Awaits the wrapped callback.
+ *   5. On a thrown error: normalizes the throwable; sets `ERROR`
+ *      status with `recordException`; rethrows the original error
+ *      verbatim.
+ *   6. On a successful return: leaves status `UNSET`.
+ *   7. Always ends the span.
+ *
+ * The continuation returns a Promise resolving to the callback's
+ * return value (Promise-or-value semantics: a sync callback's value
+ * is wrapped in `Promise.resolve()`).
+ *
+ * @param options - Span name and optional pre-start attributes.
+ * @param fn - The async callback to run later. May be sync or async;
+ *   the wrapper always returns a Promise to give a consistent
+ *   continuation shape regardless of `fn`'s synchronicity.
+ * @returns A continuation `() => Promise<T>` that, when invoked,
+ *   emits the causally-linked span and runs `fn`.
+ *
+ * @example Next.js after() — typical use
+ * ```ts
+ * import { withAsyncCausality } from "@glasstrace/sdk/async-context";
+ * import { after } from "next/server";
+ *
+ * export async function POST(req: Request) {
+ *   const result = await processRequest(req);
+ *   after(
+ *     withAsyncCausality(
+ *       { name: "send-confirmation-email" },
+ *       async () => sendEmail(result.userId),
+ *     ),
+ *   );
+ *   return Response.json({ ok: true });
+ * }
+ * ```
+ *
+ * @example Queue dispatcher — capture before enqueue
+ * ```ts
+ * const dispatch = withAsyncCausality(
+ *   { name: "process-webhook" },
+ *   async () => handler(payload),
+ * );
+ * await queue.enqueue(dispatch);
+ * ```
+ */
+declare function withAsyncCausality<T>(options: WithAsyncCausalityOptions, fn: () => Promise<T> | T): () => Promise<T>;
+
+export { type WithAsyncCausalityOptions, _resetForTesting, withAsyncCausality };

package/dist/async-context/index.d.ts

@@ -0,0 +1,174 @@
+import { AttributeValue } from './common/Attributes';
+
+/**
+ * Post-response async causality instrumentation for Glasstrace.
+ *
+ * Subpath: `@glasstrace/sdk/async-context`
+ *
+ * This module exposes {@link withAsyncCausality}, a continuation-
+ * passing wrapper that captures the active OTel `SpanContext` at call
+ * time and binds it to a callback. When the callback runs later
+ * (Next.js `after()`, queue dispatchers, webhook fire-and-forget),
+ * the wrapper opens a span linked to the originating trace via two
+ * channels:
+ *
+ *   - An OTel `Link` to the captured `SpanContext` — the OTel-native
+ *     pointer between two spans in different traces. Surfaces in
+ *     standard OTel-aware UIs (Jaeger, Honeycomb, etc.) as a
+ *     "follows from" relationship.
+ *   - A `glasstrace.causal.post_response_async` attribute carrying
+ *     the captured trace ID (32-char hex). Used by the product-side
+ *     trace-summary transform (per DISC-1539's product handoff) to
+ *     reconstruct ownership without resolving the Link. Two
+ *     companion booleans
+ *     (`glasstrace.causal.affects_http_status` and
+ *     `glasstrace.causal.affects_http_duration`) document that the
+ *     async work does NOT participate in the root request's outcome.
+ *
+ * Both channels are emitted together so the SDK is robust to
+ * downstream transforms that resolve causality through either form.
+ *
+ * Edge-runtime safety
+ * -------------------
+ * The wrapper is included in the SDK's edge bundle
+ * (`packages/sdk/src/edge-entry.ts`). Its closure imports only the
+ * OTel API, the protocol constants, and the
+ * `./optional-lifecycle.js` bridge — none of which reach into
+ * `node:*` built-ins or the `process` global. The F003 closure scan
+ * (`packages/sdk/scripts/check-edge-bundle.mjs`) enforces this on
+ * every build.
+ *
+ * Strategy: continuation-passing, NOT global ALS propagation
+ * ---------------------------------------------------------
+ * Per the SDK-046 brief §2.3: ALS continuity across Next.js `after()`
+ * is uncertain (the framework may schedule via `queueMicrotask`
+ * (preserves ALS) or via cross-tick scheduling (drops ALS)). Relying
+ * on ALS would couple the SDK to Next internals. Continuation-passing
+ * makes the causality explicit — the user wraps the callback they
+ * pass to `after()` / their queue, and the captured `SpanContext`
+ * travels with the closure regardless of how the framework schedules
+ * it.
+ *
+ * @module @glasstrace/sdk/async-context
+ */
+
+/**
+ * INTERNAL — clears once-flags for unit tests; not part of the
+ * public surface.
+ */
+declare function _resetForTesting(): void;
+/**
+ * Options for {@link withAsyncCausality}.
+ *
+ * @example
+ * ```ts
+ * import { withAsyncCausality } from "@glasstrace/sdk/async-context";
+ * import { after } from "next/server";
+ *
+ * export async function POST(req: Request) {
+ *   const result = await processRequest(req);
+ *   after(
+ *     withAsyncCausality(
+ *       { name: "send-confirmation-email" },
+ *       async () => sendEmail(result.userId),
+ *     ),
+ *   );
+ *   return Response.json({ ok: true });
+ * }
+ * ```
+ */
+interface WithAsyncCausalityOptions {
+    /**
+     * Span name for the async work. Required, non-empty string. Used as
+     * the OTel span name and appears in trace timelines. Names should
+     * be stable across runs (e.g., "send-confirmation-email",
+     * "enqueue-webhook-dispatch"); avoid embedding payload data in the
+     * name.
+     */
+    name: string;
+    /**
+     * Optional attributes attached to the span before the wrapped
+     * callback runs. Forwarded to OTel as-is via `span.setAttributes()`.
+     * The SDK does not redact, sanitize, or scan values here — callers
+     * MUST avoid placing tokens, credentials, or other sensitive data
+     * in `attributes`.
+     */
+    attributes?: Record<string, AttributeValue>;
+}
+/**
+ * Capture the active OTel `SpanContext` at call time, bind it to a
+ * callback, and return a continuation that will emit a
+ * causally-linked span when invoked.
+ *
+ * The returned continuation:
+ *
+ *   1. Detects the SDK's registration state. When the OTel API is
+ *      still on the noop tracer, runs the wrapped callback directly
+ *      and emits an `async:skipped_uninstalled` lifecycle event (at
+ *      most once per process). No span is opened.
+ *   2. Otherwise opens a span named `options.name` as a NEW root
+ *      span (not parented to the captured context — `after()` /
+ *      queue dispatchers run outside the originating request's OTel
+ *      context, so the async work belongs to a separate trace).
+ *   3. When a captured `SpanContext` exists with a valid trace ID,
+ *      attaches:
+ *        - an OTel `Link` to that `SpanContext` (the OTel-native
+ *          form),
+ *        - the `glasstrace.causal.post_response_async` attribute
+ *          carrying the trace ID (the transform-readable form),
+ *        - `glasstrace.causal.affects_http_status = false` and
+ *          `glasstrace.causal.affects_http_duration = false`
+ *          documenting that the async work does NOT participate in
+ *          the root request's outcome.
+ *      When no valid `SpanContext` was captured, none of these are
+ *      emitted (per SDK-046's "missing or unknown evidence is
+ *      preferable to guessed evidence" rule) and an
+ *      `async:no_originating_context` lifecycle event fires (at
+ *      most once per process).
+ *   4. Awaits the wrapped callback.
+ *   5. On a thrown error: normalizes the throwable; sets `ERROR`
+ *      status with `recordException`; rethrows the original error
+ *      verbatim.
+ *   6. On a successful return: leaves status `UNSET`.
+ *   7. Always ends the span.
+ *
+ * The continuation returns a Promise resolving to the callback's
+ * return value (Promise-or-value semantics: a sync callback's value
+ * is wrapped in `Promise.resolve()`).
+ *
+ * @param options - Span name and optional pre-start attributes.
+ * @param fn - The async callback to run later. May be sync or async;
+ *   the wrapper always returns a Promise to give a consistent
+ *   continuation shape regardless of `fn`'s synchronicity.
+ * @returns A continuation `() => Promise<T>` that, when invoked,
+ *   emits the causally-linked span and runs `fn`.
+ *
+ * @example Next.js after() — typical use
+ * ```ts
+ * import { withAsyncCausality } from "@glasstrace/sdk/async-context";
+ * import { after } from "next/server";
+ *
+ * export async function POST(req: Request) {
+ *   const result = await processRequest(req);
+ *   after(
+ *     withAsyncCausality(
+ *       { name: "send-confirmation-email" },
+ *       async () => sendEmail(result.userId),
+ *     ),
+ *   );
+ *   return Response.json({ ok: true });
+ * }
+ * ```
+ *
+ * @example Queue dispatcher — capture before enqueue
+ * ```ts
+ * const dispatch = withAsyncCausality(
+ *   { name: "process-webhook" },
+ *   async () => handler(payload),
+ * );
+ * await queue.enqueue(dispatch);
+ * ```
+ */
+declare function withAsyncCausality<T>(options: WithAsyncCausalityOptions, fn: () => Promise<T> | T): () => Promise<T>;
+
+export { type WithAsyncCausalityOptions, _resetForTesting, withAsyncCausality };

package/dist/async-context/index.js

@@ -0,0 +1,13 @@
+import {
+  _resetForTesting,
+  withAsyncCausality
+} from "../chunk-QEXRCXSY.js";
+import "../chunk-CL3OVHPO.js";
+import "../chunk-DQ25VOKK.js";
+import "../chunk-JHUNLPSS.js";
+import "../chunk-NSBPE2FW.js";
+export {
+  _resetForTesting,
+  withAsyncCausality
+};
+//# sourceMappingURL=index.js.map

package/dist/{capture-error-Dzz7_-v4.d.ts → capture-error-BeuEXXJO.d.cts}

@@ -1,8 +1,8 @@
-import { G as GlasstraceEnvVars, f as GlasstraceOptions, A as AnonApiKey, g as SdkInitResponse, C as CaptureConfig, h as SdkHealthReport, I as ImportGraphPayload, i as SdkDiagnosticCode } from './index.d-Dq33YwFT.js';
+import { G as GlasstraceEnvVars, h as GlasstraceOptions, A as AnonApiKey, i as SdkInitResponse, C as CaptureConfig, j as SdkHealthReport, I as ImportGraphPayload, f as SdkDiagnosticCode } from './index.d-CkTf_boH.cjs';
 import { ReadableSpan } from './export/ReadableSpan';
 import { SpanExporter } from './export/SpanExporter';
 import { ExportResult } from './ExportResult';
-import { a as SessionManager } from './edge-entry-AWO70gje.js';
+import { a as SessionManager } from './correlation-id-NAapJ5jn.cjs';
 import { SpanProcessor } from './SpanProcessor';
 
 /**

package/dist/{capture-error-C95zvSvF.d.cts → capture-error-D02pzB7q.d.ts}

@@ -1,8 +1,8 @@
-import { G as GlasstraceEnvVars, f as GlasstraceOptions, A as AnonApiKey, g as SdkInitResponse, C as CaptureConfig, h as SdkHealthReport, I as ImportGraphPayload, i as SdkDiagnosticCode } from './index.d-Dq33YwFT.cjs';
+import { G as GlasstraceEnvVars, h as GlasstraceOptions, A as AnonApiKey, i as SdkInitResponse, C as CaptureConfig, j as SdkHealthReport, I as ImportGraphPayload, f as SdkDiagnosticCode } from './index.d-CkTf_boH.js';
 import { ReadableSpan } from './export/ReadableSpan';
 import { SpanExporter } from './export/SpanExporter';
 import { ExportResult } from './ExportResult';
-import { a as SessionManager } from './edge-entry-DaeG7D7S.cjs';
+import { a as SessionManager } from './correlation-id-B_K8adD6.js';
 import { SpanProcessor } from './SpanProcessor';
 
 /**

package/dist/{chunk-JJL2M64Z.js → chunk-2F2MGFLO.js}

@@ -1,3 +1,6 @@
+import {
+  _registerLifecycleEmitForBridge
+} from "./chunk-CL3OVHPO.js";
 import {
   DiagLogLevel,
   INVALID_SPAN_CONTEXT,
@@ -33,7 +36,7 @@ import {
   performInit,
   recordSpansDropped,
   recordSpansExported
-} from "./chunk-M2TLX6NM.js";
+} from "./chunk-QXITSNYM.js";
 import {
   isAnonymousMode,
   isProductionDisabled,
@@ -44,11 +47,11 @@ import {
   getOrCreateAnonKey,
   isSyncFsAvailable,
   readAnonKey
-} from "./chunk-WL6BXEJ5.js";
+} from "./chunk-DKV53A2C.js";
 import {
   GLASSTRACE_ATTRIBUTE_NAMES,
   deriveSessionId
-} from "./chunk-P45NZR4J.js";
+} from "./chunk-JHUNLPSS.js";
 import {
   isEndMarkerLine,
   parseStartMarkerLine
@@ -249,6 +252,12 @@ function initLifecycle(options) {
   }
   _logger = options.logger;
   _initialized = true;
+  _registerLifecycleEmitForBridge((event, payload) => {
+    emitLifecycleEvent(
+      event,
+      payload
+    );
+  });
 }
 function warnIfNotInitialized() {
   if (!_initialized && !_initWarned) {
@@ -4968,11 +4977,11 @@ function registerGlasstrace(options) {
     setCoreState(CoreState.REGISTERING);
     maybeWarnStaleAgentInstructions({
       projectRoot: process.cwd(),
-      sdkVersion: "1.8.0"
+      sdkVersion: "1.9.1"
     });
     startRuntimeStateWriter({
       projectRoot: process.cwd(),
-      sdkVersion: "1.8.0"
+      sdkVersion: "1.9.1"
     });
     const config = resolveConfig(options);
     if (config.verbose) {
@@ -5139,8 +5148,8 @@ async function backgroundInit(config, anonKeyForInit, generation) {
   if (config.verbose) {
     console.info("[glasstrace] Background init firing.");
   }
-  const healthReport = collectHealthReport("1.8.0");
-  const initResult = await performInit(config, anonKeyForInit, "1.8.0", healthReport);
+  const healthReport = collectHealthReport("1.9.1");
+  const initResult = await performInit(config, anonKeyForInit, "1.9.1", healthReport);
   if (generation !== registrationGeneration) return;
   const currentState = getCoreState();
   if (currentState === CoreState.SHUTTING_DOWN || currentState === CoreState.SHUTDOWN) {
@@ -5163,7 +5172,7 @@ async function backgroundInit(config, anonKeyForInit, generation) {
   }
   maybeInstallConsoleCapture();
   if (didLastInitSucceed()) {
-    startHeartbeat(config, anonKeyForInit, "1.8.0", generation, (newApiKey, accountId) => {
+    startHeartbeat(config, anonKeyForInit, "1.9.1", generation, (newApiKey, accountId) => {
       setAuthState(AuthState.CLAIMING);
       emitLifecycleEvent("auth:claim_started", { accountId });
       setResolvedApiKey(newApiKey);
@@ -5460,7 +5469,7 @@ async function handleSourceMapUpload(distDir) {
       );
       return;
     }
-    const { discoverSourceMapFiles, computeBuildHash, uploadSourceMaps } = await import("./source-map-uploader-XFUEVV7I.js");
+    const { discoverSourceMapFiles, computeBuildHash, uploadSourceMaps } = await import("./source-map-uploader-MMJ2WCL4.js");
     const files = await discoverSourceMapFiles(distDir);
     if (files.length === 0) {
       console.info("[glasstrace] No source map files found. Skipping upload.");
@@ -5563,4 +5572,4 @@ export {
   withGlasstraceConfig,
   captureError
 };
-//# sourceMappingURL=chunk-JJL2M64Z.js.map
+//# sourceMappingURL=chunk-2F2MGFLO.js.map