@glasstrace/sdk 1.7.0 → 1.9.0

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-RQ5BIWDT.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-CTgSYxek.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';
 
 /**
@@ -190,7 +190,40 @@ declare class GlasstraceExporter implements SpanExporter {
     private pendingBatches;
     private pendingSpanCount;
     private overflowLogged;
+    /**
+     * Lazily-bound reference to the export-path circuit breaker
+     * (DISC-1568 / Wave 15C). Resolved on first export so this
+     * constructor stays side-effect-free. The breaker is a module-
+     * singleton — every `GlasstraceExporter` instance shares the same
+     * one so a rotation event observed in `init-client.ts` reaches
+     * every active exporter.
+     */
+    private circuitBreaker;
     constructor(options: GlasstraceExporterOptions);
+    /**
+     * Returns the export-path circuit breaker, lazily wiring it on
+     * first call. The breaker is a module-singleton so all exporter
+     * instances share state — a credential rotation observed once
+     * resets the breaker for every active exporter, and a single
+     * outage at the OTLP endpoint trips a single breaker rather than
+     * one per exporter copy.
+     *
+     * The wiring binds:
+     * - the lifecycle event sink to the SDK's lifecycle bus
+     *   (`emitLifecycleEvent`) so the `otel:circuit_*` events surface
+     *   to runtime-state, the CLI bridge, and any user-installed
+     *   subscribers.
+     * - the dropped-span counter to {@link recordSpansDropped} so OPEN-
+     *   state drops show up in the existing health surface.
+     * - the FSM hooks to {@link pushDegradationSource} /
+     *   {@link clearDegradationSource} keyed on `"export-circuit"`,
+     *   which routes the OPEN/CLOSED transitions through the
+     *   centralised `recomputeCoreFromDegradationSources()` helper.
+     *   That helper guards `ACTIVE ↔ ACTIVE_DEGRADED` so a circuit
+     *   recovery never clobbers an unrelated `OtelState.COEXISTENCE_FAILED`
+     *   degradation source.
+     */
+    private getCircuitBreaker;
     export(spans: ReadableSpan[], resultCallback: (result: ExportResult) => void): void;
     /**
      * Called when the API key transitions from "pending" to a resolved value.
@@ -234,6 +267,11 @@ declare class GlasstraceExporter implements SpanExporter {
      * Flushes all buffered spans through the delegate exporter.
      * Enriches spans at flush time (not buffer time) so that session IDs
      * are computed with the resolved API key instead of the "pending" sentinel.
+     *
+     * Honors the circuit breaker symmetrically with {@link export}: if the
+     * breaker is OPEN at flush time, every buffered batch is dropped via
+     * `recordSpansDropped` and its callback completed with `{ code: 0 }`,
+     * preserving the bounded-memory contract during outages.
      */
     private flushPending;
 }

package/dist/{capture-error-BmQz7xF6.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';
 
 /**
@@ -190,7 +190,40 @@ declare class GlasstraceExporter implements SpanExporter {
     private pendingBatches;
     private pendingSpanCount;
     private overflowLogged;
+    /**
+     * Lazily-bound reference to the export-path circuit breaker
+     * (DISC-1568 / Wave 15C). Resolved on first export so this
+     * constructor stays side-effect-free. The breaker is a module-
+     * singleton — every `GlasstraceExporter` instance shares the same
+     * one so a rotation event observed in `init-client.ts` reaches
+     * every active exporter.
+     */
+    private circuitBreaker;
     constructor(options: GlasstraceExporterOptions);
+    /**
+     * Returns the export-path circuit breaker, lazily wiring it on
+     * first call. The breaker is a module-singleton so all exporter
+     * instances share state — a credential rotation observed once
+     * resets the breaker for every active exporter, and a single
+     * outage at the OTLP endpoint trips a single breaker rather than
+     * one per exporter copy.
+     *
+     * The wiring binds:
+     * - the lifecycle event sink to the SDK's lifecycle bus
+     *   (`emitLifecycleEvent`) so the `otel:circuit_*` events surface
+     *   to runtime-state, the CLI bridge, and any user-installed
+     *   subscribers.
+     * - the dropped-span counter to {@link recordSpansDropped} so OPEN-
+     *   state drops show up in the existing health surface.
+     * - the FSM hooks to {@link pushDegradationSource} /
+     *   {@link clearDegradationSource} keyed on `"export-circuit"`,
+     *   which routes the OPEN/CLOSED transitions through the
+     *   centralised `recomputeCoreFromDegradationSources()` helper.
+     *   That helper guards `ACTIVE ↔ ACTIVE_DEGRADED` so a circuit
+     *   recovery never clobbers an unrelated `OtelState.COEXISTENCE_FAILED`
+     *   degradation source.
+     */
+    private getCircuitBreaker;
     export(spans: ReadableSpan[], resultCallback: (result: ExportResult) => void): void;
     /**
      * Called when the API key transitions from "pending" to a resolved value.
@@ -234,6 +267,11 @@ declare class GlasstraceExporter implements SpanExporter {
      * Flushes all buffered spans through the delegate exporter.
      * Enriches spans at flush time (not buffer time) so that session IDs
      * are computed with the resolved API key instead of the "pending" sentinel.
+     *
+     * Honors the circuit breaker symmetrically with {@link export}: if the
+     * breaker is OPEN at flush time, every buffered batch is dropped via
+     * `recordSpansDropped` and its callback completed with `{ code: 0 }`,
+     * preserving the bounded-memory contract during outages.
      */
     private flushPending;
 }

package/dist/chunk-CL3OVHPO.js

@@ -0,0 +1,23 @@
+// src/optional-lifecycle.ts
+var EMIT_BRIDGE = /* @__PURE__ */ Symbol.for("glasstrace.lifecycle.emit-bridge");
+function _registerLifecycleEmitForBridge(emit) {
+  try {
+    const slot = { emit };
+    globalThis[EMIT_BRIDGE] = slot;
+  } catch {
+  }
+}
+function tryEmitLifecycleEvent(event, payload) {
+  try {
+    const slot = globalThis[EMIT_BRIDGE];
+    if (!slot) return;
+    slot.emit(event, payload);
+  } catch {
+  }
+}
+
+export {
+  _registerLifecycleEmitForBridge,
+  tryEmitLifecycleEvent
+};
+//# sourceMappingURL=chunk-CL3OVHPO.js.map

package/dist/chunk-CL3OVHPO.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/optional-lifecycle.ts"],"sourcesContent":["/**\n * Edge-safe optional bridge to the SDK lifecycle event emitter.\n *\n * `./lifecycle.ts` imports `node:events` and is therefore excluded from\n * the F003 edge bundle (`packages/sdk/src/edge-entry.ts`,\n * `packages/sdk/scripts/check-edge-bundle.mjs`). Modules that need to\n * emit a lifecycle event AND need to ship in the edge bundle (e.g.,\n * `./middleware/index.ts`, `./async-context/index.ts`) cannot import\n * from `./lifecycle.ts` directly.\n *\n * This module is the bridge:\n *\n * - `lifecycle.ts` (Node-only) calls {@link _registerLifecycleEmitForBridge}\n *   inside `initLifecycle()`. The registration writes the typed\n *   `emitLifecycleEvent` reference to a `globalThis`-keyed slot.\n * - Edge-safe wrappers call {@link tryEmitLifecycleEvent}, which reads\n *   the slot. When unset (edge runtime, or SDK not yet initialized),\n *   the call is a clean no-op. When set, the call forwards to the\n *   real emitter.\n *\n * This file imports nothing from `node:*` and reads no `process`\n * globals; it is admissible to the edge bundle by the F003 contract.\n *\n * The slot key uses `Symbol.for()` so the bridge survives module\n * re-evaluation (Turbopack HMR rebuilds, Webpack `next dev` rebuilds,\n * vitest module isolation). The same pattern is used by the OTel\n * context-manager guard at `./context-manager.ts:28` and the exporter\n * brand at `./coexistence.ts:31` — all three are per-isolate by V8\n * semantics, which is the correct boundary for this contract (a Node\n * worker thread or `vm.Context` is logically a fresh process).\n *\n * **Why not pass the emitter through the public wrapper API?** The\n * emitter is an internal SDK signal, not a user-facing knob. Keeping\n * it on a global slot rather than as a wrapper option preserves the\n * documented public surface (`tracedRequestMiddleware(options,\n * handler)`) and lets the lifecycle module take ownership of the\n * emit-once / event-key invariants without exposing them.\n */\n\n/** Process-wide brand used to look up the registered emit function. */\nconst EMIT_BRIDGE = Symbol.for(\"glasstrace.lifecycle.emit-bridge\");\n\n/**\n * Type of the registered emit function. Mirrors the signature of\n * `emitLifecycleEvent` from `./lifecycle.ts` but typed as `unknown`\n * here to keep this module free of any cross-import that would couple\n * the edge bundle to `node:events`.\n *\n * The lifecycle module casts to/from this type at the registration\n * site; consumers of {@link tryEmitLifecycleEvent} use the typed\n * overload that re-imposes the `SdkLifecycleEvents` constraint via a\n * second parameter alias.\n */\nexport type LifecycleEmitFn = (\n  event: string,\n  payload: Record<string, unknown>,\n) => void;\n\ninterface BridgeSlot {\n  readonly emit: LifecycleEmitFn;\n}\n\n/**\n * INTERNAL — called by `./lifecycle.ts` during `initLifecycle()` to\n * register the emit function under the global slot. Calling twice is\n * idempotent: the latest registration wins. Never throws.\n */\nexport function _registerLifecycleEmitForBridge(\n  emit: LifecycleEmitFn,\n): void {\n  try {\n    const slot: BridgeSlot = { emit };\n    (globalThis as unknown as Record<symbol, BridgeSlot>)[EMIT_BRIDGE] = slot;\n  } catch {\n    // Defensive: writing to globalThis is observable; some constrained\n    // sandboxes freeze it. The bridge falls back to silent no-op.\n  }\n}\n\n/**\n * INTERNAL — called by `./lifecycle.ts` during\n * `resetLifecycleForTesting()` to clear the slot so a fresh test gets\n * a clean bridge state.\n */\nexport function _clearLifecycleEmitForBridge(): void {\n  try {\n    delete (globalThis as unknown as Record<symbol, unknown>)[EMIT_BRIDGE];\n  } catch {\n    // Defensive: see _registerLifecycleEmitForBridge.\n  }\n}\n\n/**\n * Attempt to emit a lifecycle event through the registered bridge.\n *\n * - When the lifecycle module has registered the bridge (Node runtime\n *   with `registerGlasstrace()` having run): forwards to\n *   `emitLifecycleEvent(event, payload)`.\n * - When the bridge is unset (edge runtime — `lifecycle.ts` not in\n *   closure; or pre-`initLifecycle()` race): no-op.\n *\n * Errors thrown by the registered emit function are swallowed —\n * instrumentation must never break a user request hook.\n */\nexport function tryEmitLifecycleEvent(\n  event: string,\n  payload: Record<string, unknown>,\n): void {\n  try {\n    const slot = (globalThis as unknown as Record<symbol, BridgeSlot | undefined>)[\n      EMIT_BRIDGE\n    ];\n    if (!slot) return;\n    slot.emit(event, payload);\n  } catch {\n    // Swallow — bridge failures are advisory, not fatal.\n  }\n}\n"],"mappings":";AAwCA,IAAM,cAAc,uBAAO,IAAI,kCAAkC;AA2B1D,SAAS,gCACd,MACM;AACN,MAAI;AACF,UAAM,OAAmB,EAAE,KAAK;AAChC,IAAC,WAAqD,WAAW,IAAI;AAAA,EACvE,QAAQ;AAAA,EAGR;AACF;AA2BO,SAAS,sBACd,OACA,SACM;AACN,MAAI;AACF,UAAM,OAAQ,WACZ,WACF;AACA,QAAI,CAAC,KAAM;AACX,SAAK,KAAK,OAAO,OAAO;AAAA,EAC1B,QAAQ;AAAA,EAER;AACF;","names":[]}

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

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

package/dist/{chunk-3PJP5Y3U.js → chunk-GWIEUBFR.js}

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

package/dist/{chunk-H57MQGNU.js → chunk-H6WJ63X2.js}

@@ -3,7 +3,7 @@ import {
 } from "./chunk-DQ25VOKK.js";
 import {
   GLASSTRACE_ATTRIBUTE_NAMES
-} from "./chunk-P45NZR4J.js";
+} from "./chunk-JHUNLPSS.js";
 
 // src/errors.ts
 var SdkError = class extends Error {
@@ -102,4 +102,4 @@ export {
   GlasstraceSpanProcessor,
   captureCorrelationId
 };
-//# sourceMappingURL=chunk-H57MQGNU.js.map
+//# sourceMappingURL=chunk-H6WJ63X2.js.map

package/dist/{chunk-NN5YCETI.js → chunk-HD6JIFKN.js}

@@ -1,6 +1,6 @@
 import {
   createBuildHash
-} from "./chunk-P45NZR4J.js";
+} from "./chunk-JHUNLPSS.js";
 
 // src/import-graph.ts
 import * as fs from "node:fs/promises";
@@ -175,4 +175,4 @@ export {
   extractImports,
   buildImportGraph
 };
-//# sourceMappingURL=chunk-NN5YCETI.js.map
+//# sourceMappingURL=chunk-HD6JIFKN.js.map

package/dist/{chunk-P45NZR4J.js → chunk-JHUNLPSS.js}

@@ -13894,6 +13894,40 @@ var GLASSTRACE_ATTRIBUTE_NAMES = {
   ELEMENT_FINGERPRINT: "glasstrace.element.fingerprint",
   ELEMENT_CONFIDENCE: "glasstrace.element.confidence",
   TAB_ID: "glasstrace.tab.id",
+  // Causal evidence (SDK-046 / DISC-1537 + DISC-1539).
+  //
+  // The SDK emits `glasstrace.causal.*` attributes on spans that
+  // carry instrumentation-time evidence about a span's relationship
+  // to its owning request trace. Two families are defined here:
+  //
+  //   - `MIDDLEWARE_FOR_REQUEST` — middleware-ownership marker. Set
+  //     on a middleware-only span by `tracedRequestMiddleware()` from
+  //     `@glasstrace/sdk/middleware`. Carries the originating
+  //     request's normalized path so the product-side trace-summary
+  //     transform can link the middleware span to the owning HTTP
+  //     request trace even when the middleware runs in an edge
+  //     runtime that does not propagate AsyncLocalStorage parents.
+  //
+  //   - `POST_RESPONSE_ASYNC` — post-response async marker. Set on a
+  //     span emitted from inside `withAsyncCausality()` from
+  //     `@glasstrace/sdk/async-context`. Carries the originating
+  //     request's trace ID (32-character hex) captured at the call
+  //     site so async work scheduled via Next.js `after()`, queues,
+  //     or webhooks can be linked back to its originating request.
+  //     Companion booleans `CAUSAL_AFFECTS_HTTP_STATUS` /
+  //     `CAUSAL_AFFECTS_HTTP_DURATION` document whether the async
+  //     work participates in the root request's outcome (default
+  //     `false` — non-outcome async work).
+  //
+  // Wire keys live under the `glasstrace.causal.*` namespace so they
+  // are namespace-distinct from `glasstrace.error.*`,
+  // `glasstrace.http.*`, `glasstrace.trpc.*`, and the side-effect
+  // family below. Adding these constants is a `@glasstrace/protocol`
+  // minor bump; existing entries are untouched.
+  CAUSAL_MIDDLEWARE_FOR_REQUEST: "glasstrace.causal.middleware_for_request",
+  CAUSAL_POST_RESPONSE_ASYNC: "glasstrace.causal.post_response_async",
+  CAUSAL_AFFECTS_HTTP_STATUS: "glasstrace.causal.affects_http_status",
+  CAUSAL_AFFECTS_HTTP_DURATION: "glasstrace.causal.affects_http_duration",
   // Side-effect evidence (SDK-049 / SCHEMA-036).
   // Top-level operation attributes attached to the active span when a
   // side-effect is recorded via `recordSideEffect()`. The wire-string
@@ -14258,4 +14292,4 @@ export {
   SIDE_EFFECT_OPERATION_STATUSES,
   SIDE_EFFECT_OPERATION_PHASES
 };
-//# sourceMappingURL=chunk-P45NZR4J.js.map
+//# sourceMappingURL=chunk-JHUNLPSS.js.map