@glasstrace/sdk 1.8.0 → 1.9.1

package/dist/middleware/index.d.cts

@@ -0,0 +1,191 @@
+import { AttributeValue } from './common/Attributes';
+
+/**
+ * Request-middleware-ownership instrumentation for Glasstrace.
+ *
+ * Subpath: `@glasstrace/sdk/middleware`
+ *
+ * This module exposes {@link tracedRequestMiddleware}, a wrapper that
+ * turns a Next.js `middleware.ts` function (or any generic
+ * `Request → Response`-shaped handler) into a span-emitting middleware
+ * function. Each invocation opens a child span and tags it with the
+ * `glasstrace.causal.middleware_for_request` causal-evidence attribute
+ * carrying the originating request's normalized path so the
+ * product-side trace-summary transform can link the middleware span
+ * to the owning HTTP request trace (DISC-1537 / SDK-046).
+ *
+ * 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.
+ *
+ * Causal-evidence form
+ * --------------------
+ * The wrapper attaches the originating request path as a span
+ * attribute (`glasstrace.causal.middleware_for_request`). It does NOT
+ * emit an OTel `Link`. Reasons:
+ *
+ *   1. The Next.js Edge runtime does not propagate AsyncLocalStorage
+ *      into `middleware.ts`, so there is no in-process
+ *      `SpanContext` to link to in that environment. Attribute-only
+ *      causality works in both Node and Edge runtimes; a Link would
+ *      degrade to a no-op (no parent context) on Edge.
+ *   2. The product-side trace-summary transform reconstructs
+ *      ownership from `glasstrace.causal.*` attributes per
+ *      DISC-1539 §51-58; it does not require a Link.
+ *
+ * Invariants
+ * ----------
+ *
+ *   - The wrapped function preserves the user's call-site type so
+ *     Next.js's `middleware` export contract (`(req: NextRequest) =>
+ *     NextResponse | Response`) flows through unchanged.
+ *   - The middleware span MUST NOT overwrite `glasstrace.route`,
+ *     `glasstrace.http.status_code`, or `glasstrace.http.duration_ms`
+ *     on the parent HTTP span — root-request semantics are owned by
+ *     the enriching exporter (`packages/sdk/src/enriching-exporter.ts`).
+ *   - On a thrown handler error: span ends with `ERROR` status +
+ *     `recordException`; rethrows. The exception is normalized to
+ *     `Error | string` first so non-Error throwables (number, plain
+ *     object) do not crash `recordException`.
+ *   - Always ends the span (`finally`), even on `throw`.
+ *
+ * @module @glasstrace/sdk/middleware
+ */
+
+/**
+ * INTERNAL — clears the once-flag for the
+ * `middleware:skipped_uninstalled` lifecycle event. Invoked by
+ * Vitest fixtures only; not part of the public surface.
+ */
+declare function _resetForTesting(): void;
+/**
+ * Permissive structural bound for a request-middleware function. The
+ * shape is the intersection of Next.js's `middleware.ts` export
+ * (`(req: NextRequest, event?: NextFetchEvent) => NextResponse |
+ * Response | Promise<NextResponse | Response> | undefined`) and the
+ * generic Web Fetch API (`(req: Request, ...rest: any[]) => Response
+ * | Promise<Response>`). The parameter list is typed with `any[]` for
+ * the rest position so any caller-narrowed signature is assignable
+ * without the wrapper having to import `next/server` types.
+ *
+ * Exported so consumers can reference it for type-inference assertions
+ * (e.g., proving a strongly-typed handler fits the bound). The
+ * runtime contract is fixed by the Web Fetch API: the first argument
+ * is a `Request`-shaped object and the return is a `Response`-shaped
+ * value (or a Promise of one).
+ */
+type RequestMiddlewareFunction = (req: any, ...rest: any[]) => unknown;
+/**
+ * Options for {@link tracedRequestMiddleware}.
+ *
+ * @example
+ * ```ts
+ * import { tracedRequestMiddleware } from "@glasstrace/sdk/middleware";
+ * import type { NextRequest } from "next/server";
+ *
+ * export const middleware = tracedRequestMiddleware(
+ *   { name: "auth-middleware", attributes: { "auth.required": true } },
+ *   async (req: NextRequest) => {
+ *     // … your auth logic here …
+ *     return NextResponse.next();
+ *   },
+ * );
+ * ```
+ */
+interface TracedRequestMiddlewareOptions {
+    /**
+     * Span name. Required, non-empty string. Used as the OTel span name
+     * and appears in trace timelines. Names should be stable across
+     * runs so the product-side transform can reason about middleware
+     * identity (e.g., "auth-middleware", "rate-limiter"); avoid
+     * embedding request data in the name.
+     */
+    name: string;
+    /**
+     * Optional attributes attached to the span before the wrapped
+     * handler 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`.
+     *
+     * Sensitive request/response data is captured through gated SDK
+     * paths (e.g., `glasstrace.error.response_body`), not through this
+     * surface.
+     */
+    attributes?: Record<string, AttributeValue>;
+}
+/**
+ * Wrap a Next.js / generic-fetch request-middleware function in an
+ * OTel span tagged with `glasstrace.causal.middleware_for_request`.
+ *
+ * **Privacy:** the value of
+ * `glasstrace.causal.middleware_for_request` is the raw URL
+ * pathname. Pathnames can carry user-controlled data (IDs, emails,
+ * opaque keys). The SDK does NOT redact this attribute. Callers MUST
+ * NOT place secrets, tokens, or other sensitive data in URL paths;
+ * the same general HTTP best practice that keeps secrets out of
+ * server logs keeps them out of Glasstrace trace evidence.
+ *
+ * Each call to the returned function:
+ *
+ *   1. Detects the SDK's registration state. When the OTel API is
+ *      still on the noop tracer (SDK not registered, or
+ *      `OtelState.UNCONFIGURED`), runs the wrapped handler directly
+ *      and emits a `middleware:skipped_uninstalled` lifecycle event
+ *      (at most once per process). No span is opened.
+ *   2. Otherwise opens a span named `options.name` under the active
+ *      OTel context (typically the HTTP server span on Node;
+ *      detached on Edge where AsyncLocalStorage is not available).
+ *      Sets `options.attributes` first, then attaches the originating
+ *      request's path (via {@link extractRequestPath}) as
+ *      `glasstrace.causal.middleware_for_request`. The path is
+ *      omitted when extraction returns `undefined` so absent evidence
+ *      is preferred over guessed evidence.
+ *   3. Awaits the wrapped handler.
+ *   4. On a thrown error: normalizes the throwable to `Error | string`
+ *      so `recordException` does not throw on non-Error values; sets
+ *      `span.status` to `ERROR` with the error's message; rethrows the
+ *      original (un-normalized) error verbatim.
+ *   5. On a successful return: leaves the span status `UNSET` per OTel
+ *      instrumentation-library guidance (explicit `OK` would shadow
+ *      downstream consumers' error transitions).
+ *   6. Always ends the span, even on `throw` or `return`.
+ *
+ * Type-inference: the returned function preserves the input function's
+ * type `H`, so caller-narrowed signatures (e.g., `(req: NextRequest)
+ * => NextResponse`) flow through unchanged.
+ *
+ * @param options - Span name and optional pre-start attributes.
+ * @param handler - The user's middleware handler. Must accept a
+ *   request-shaped object as its first argument and return (or
+ *   resolve to) a response-shaped value.
+ * @returns The wrapped handler with the same call signature and
+ *   return type as `handler`.
+ *
+ * @example Next.js middleware.ts
+ * ```ts
+ * import { tracedRequestMiddleware } from "@glasstrace/sdk/middleware";
+ * import { NextResponse, type NextRequest } from "next/server";
+ *
+ * export const middleware = tracedRequestMiddleware(
+ *   { name: "auth-middleware" },
+ *   async (req: NextRequest) => {
+ *     if (!req.cookies.get("session")) {
+ *       return NextResponse.redirect(new URL("/login", req.url));
+ *     }
+ *     return NextResponse.next();
+ *   },
+ * );
+ *
+ * export const config = { matcher: ["/dashboard/:path*"] };
+ * ```
+ */
+declare function tracedRequestMiddleware<H extends RequestMiddlewareFunction>(options: TracedRequestMiddlewareOptions, handler: H): H;
+
+export { type RequestMiddlewareFunction, type TracedRequestMiddlewareOptions, _resetForTesting, tracedRequestMiddleware };

package/dist/middleware/index.d.ts

@@ -0,0 +1,191 @@
+import { AttributeValue } from './common/Attributes';
+
+/**
+ * Request-middleware-ownership instrumentation for Glasstrace.
+ *
+ * Subpath: `@glasstrace/sdk/middleware`
+ *
+ * This module exposes {@link tracedRequestMiddleware}, a wrapper that
+ * turns a Next.js `middleware.ts` function (or any generic
+ * `Request → Response`-shaped handler) into a span-emitting middleware
+ * function. Each invocation opens a child span and tags it with the
+ * `glasstrace.causal.middleware_for_request` causal-evidence attribute
+ * carrying the originating request's normalized path so the
+ * product-side trace-summary transform can link the middleware span
+ * to the owning HTTP request trace (DISC-1537 / SDK-046).
+ *
+ * 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.
+ *
+ * Causal-evidence form
+ * --------------------
+ * The wrapper attaches the originating request path as a span
+ * attribute (`glasstrace.causal.middleware_for_request`). It does NOT
+ * emit an OTel `Link`. Reasons:
+ *
+ *   1. The Next.js Edge runtime does not propagate AsyncLocalStorage
+ *      into `middleware.ts`, so there is no in-process
+ *      `SpanContext` to link to in that environment. Attribute-only
+ *      causality works in both Node and Edge runtimes; a Link would
+ *      degrade to a no-op (no parent context) on Edge.
+ *   2. The product-side trace-summary transform reconstructs
+ *      ownership from `glasstrace.causal.*` attributes per
+ *      DISC-1539 §51-58; it does not require a Link.
+ *
+ * Invariants
+ * ----------
+ *
+ *   - The wrapped function preserves the user's call-site type so
+ *     Next.js's `middleware` export contract (`(req: NextRequest) =>
+ *     NextResponse | Response`) flows through unchanged.
+ *   - The middleware span MUST NOT overwrite `glasstrace.route`,
+ *     `glasstrace.http.status_code`, or `glasstrace.http.duration_ms`
+ *     on the parent HTTP span — root-request semantics are owned by
+ *     the enriching exporter (`packages/sdk/src/enriching-exporter.ts`).
+ *   - On a thrown handler error: span ends with `ERROR` status +
+ *     `recordException`; rethrows. The exception is normalized to
+ *     `Error | string` first so non-Error throwables (number, plain
+ *     object) do not crash `recordException`.
+ *   - Always ends the span (`finally`), even on `throw`.
+ *
+ * @module @glasstrace/sdk/middleware
+ */
+
+/**
+ * INTERNAL — clears the once-flag for the
+ * `middleware:skipped_uninstalled` lifecycle event. Invoked by
+ * Vitest fixtures only; not part of the public surface.
+ */
+declare function _resetForTesting(): void;
+/**
+ * Permissive structural bound for a request-middleware function. The
+ * shape is the intersection of Next.js's `middleware.ts` export
+ * (`(req: NextRequest, event?: NextFetchEvent) => NextResponse |
+ * Response | Promise<NextResponse | Response> | undefined`) and the
+ * generic Web Fetch API (`(req: Request, ...rest: any[]) => Response
+ * | Promise<Response>`). The parameter list is typed with `any[]` for
+ * the rest position so any caller-narrowed signature is assignable
+ * without the wrapper having to import `next/server` types.
+ *
+ * Exported so consumers can reference it for type-inference assertions
+ * (e.g., proving a strongly-typed handler fits the bound). The
+ * runtime contract is fixed by the Web Fetch API: the first argument
+ * is a `Request`-shaped object and the return is a `Response`-shaped
+ * value (or a Promise of one).
+ */
+type RequestMiddlewareFunction = (req: any, ...rest: any[]) => unknown;
+/**
+ * Options for {@link tracedRequestMiddleware}.
+ *
+ * @example
+ * ```ts
+ * import { tracedRequestMiddleware } from "@glasstrace/sdk/middleware";
+ * import type { NextRequest } from "next/server";
+ *
+ * export const middleware = tracedRequestMiddleware(
+ *   { name: "auth-middleware", attributes: { "auth.required": true } },
+ *   async (req: NextRequest) => {
+ *     // … your auth logic here …
+ *     return NextResponse.next();
+ *   },
+ * );
+ * ```
+ */
+interface TracedRequestMiddlewareOptions {
+    /**
+     * Span name. Required, non-empty string. Used as the OTel span name
+     * and appears in trace timelines. Names should be stable across
+     * runs so the product-side transform can reason about middleware
+     * identity (e.g., "auth-middleware", "rate-limiter"); avoid
+     * embedding request data in the name.
+     */
+    name: string;
+    /**
+     * Optional attributes attached to the span before the wrapped
+     * handler 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`.
+     *
+     * Sensitive request/response data is captured through gated SDK
+     * paths (e.g., `glasstrace.error.response_body`), not through this
+     * surface.
+     */
+    attributes?: Record<string, AttributeValue>;
+}
+/**
+ * Wrap a Next.js / generic-fetch request-middleware function in an
+ * OTel span tagged with `glasstrace.causal.middleware_for_request`.
+ *
+ * **Privacy:** the value of
+ * `glasstrace.causal.middleware_for_request` is the raw URL
+ * pathname. Pathnames can carry user-controlled data (IDs, emails,
+ * opaque keys). The SDK does NOT redact this attribute. Callers MUST
+ * NOT place secrets, tokens, or other sensitive data in URL paths;
+ * the same general HTTP best practice that keeps secrets out of
+ * server logs keeps them out of Glasstrace trace evidence.
+ *
+ * Each call to the returned function:
+ *
+ *   1. Detects the SDK's registration state. When the OTel API is
+ *      still on the noop tracer (SDK not registered, or
+ *      `OtelState.UNCONFIGURED`), runs the wrapped handler directly
+ *      and emits a `middleware:skipped_uninstalled` lifecycle event
+ *      (at most once per process). No span is opened.
+ *   2. Otherwise opens a span named `options.name` under the active
+ *      OTel context (typically the HTTP server span on Node;
+ *      detached on Edge where AsyncLocalStorage is not available).
+ *      Sets `options.attributes` first, then attaches the originating
+ *      request's path (via {@link extractRequestPath}) as
+ *      `glasstrace.causal.middleware_for_request`. The path is
+ *      omitted when extraction returns `undefined` so absent evidence
+ *      is preferred over guessed evidence.
+ *   3. Awaits the wrapped handler.
+ *   4. On a thrown error: normalizes the throwable to `Error | string`
+ *      so `recordException` does not throw on non-Error values; sets
+ *      `span.status` to `ERROR` with the error's message; rethrows the
+ *      original (un-normalized) error verbatim.
+ *   5. On a successful return: leaves the span status `UNSET` per OTel
+ *      instrumentation-library guidance (explicit `OK` would shadow
+ *      downstream consumers' error transitions).
+ *   6. Always ends the span, even on `throw` or `return`.
+ *
+ * Type-inference: the returned function preserves the input function's
+ * type `H`, so caller-narrowed signatures (e.g., `(req: NextRequest)
+ * => NextResponse`) flow through unchanged.
+ *
+ * @param options - Span name and optional pre-start attributes.
+ * @param handler - The user's middleware handler. Must accept a
+ *   request-shaped object as its first argument and return (or
+ *   resolve to) a response-shaped value.
+ * @returns The wrapped handler with the same call signature and
+ *   return type as `handler`.
+ *
+ * @example Next.js middleware.ts
+ * ```ts
+ * import { tracedRequestMiddleware } from "@glasstrace/sdk/middleware";
+ * import { NextResponse, type NextRequest } from "next/server";
+ *
+ * export const middleware = tracedRequestMiddleware(
+ *   { name: "auth-middleware" },
+ *   async (req: NextRequest) => {
+ *     if (!req.cookies.get("session")) {
+ *       return NextResponse.redirect(new URL("/login", req.url));
+ *     }
+ *     return NextResponse.next();
+ *   },
+ * );
+ *
+ * export const config = { matcher: ["/dashboard/:path*"] };
+ * ```
+ */
+declare function tracedRequestMiddleware<H extends RequestMiddlewareFunction>(options: TracedRequestMiddlewareOptions, handler: H): H;
+
+export { type RequestMiddlewareFunction, type TracedRequestMiddlewareOptions, _resetForTesting, tracedRequestMiddleware };

package/dist/middleware/index.js

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

package/dist/middleware/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/node-entry.cjs

@@ -14686,6 +14686,40 @@ var init_dist = __esm({
       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
@@ -18932,6 +18966,16 @@ function getCoexistenceState() {
   return coexistenceState;
 }
 
+// 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 {
+  }
+}
+
 // src/lifecycle.ts
 var CoreState = {
   IDLE: "IDLE",
@@ -19026,6 +19070,12 @@ function initLifecycle(options) {
   }
   _logger = options.logger;
   _initialized = true;
+  _registerLifecycleEmitForBridge((event, payload) => {
+    emitLifecycleEvent(
+      event,
+      payload
+    );
+  });
 }
 function warnIfNotInitialized() {
   if (!_initialized && !_initWarned) {
@@ -23509,11 +23559,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 config2 = resolveConfig(options);
     if (config2.verbose) {
@@ -23680,8 +23730,8 @@ async function backgroundInit(config2, anonKeyForInit, generation) {
   if (config2.verbose) {
     console.info("[glasstrace] Background init firing.");
   }
-  const healthReport = collectHealthReport("1.8.0");
-  const initResult = await performInit(config2, anonKeyForInit, "1.8.0", healthReport);
+  const healthReport = collectHealthReport("1.9.1");
+  const initResult = await performInit(config2, anonKeyForInit, "1.9.1", healthReport);
   if (generation !== registrationGeneration) return;
   const currentState = getCoreState();
   if (currentState === CoreState.SHUTTING_DOWN || currentState === CoreState.SHUTDOWN) {
@@ -23704,7 +23754,7 @@ async function backgroundInit(config2, anonKeyForInit, generation) {
   }
   maybeInstallConsoleCapture();
   if (didLastInitSucceed()) {
-    startHeartbeat(config2, anonKeyForInit, "1.8.0", generation, (newApiKey, accountId) => {
+    startHeartbeat(config2, anonKeyForInit, "1.9.1", generation, (newApiKey, accountId) => {
       setAuthState(AuthState.CLAIMING);
       emitLifecycleEvent("auth:claim_started", { accountId });
       setResolvedApiKey(newApiKey);