stitchkit 0.27.0 → 0.28.0

package/dist/{index-y4132gqh.js → index-17jpjnhd.js}

@@ -2,7 +2,7 @@ import {
   assertCorsConfig,
   corsHeaders,
   corsPreflightResponse
-} from "./index-zfscdskj.js";
+} from "./index-czmqks7r.js";
 import {
   AppError,
   badRequest,
@@ -15,13 +15,15 @@ import {
 import {
   extractIp,
   getClientInfo,
+  getRequestContext,
   parseQueryParams,
   resolveSocketIp,
   resolveTraceId,
   setRequestEndpoint
-} from "./index-dzx781tm.js";
+} from "./index-9g9d6r1h.js";
 import {
   __require,
+  isRecord,
   isUnsafeKey,
   safeJsonParse,
   typedEntries
@@ -426,7 +428,7 @@ function levelForStatus(status) {
   return "info";
 }
 function buildLogFields(method, path, status, durationMs, traceId, errorCode2) {
-  return { traceId, method, path, status, durationMs, ...errorCode2 && { errorCode: errorCode2 } };
+  return { traceId, method, path, status, durationMs, errorCode: errorCode2 };
 }
 function formatMs(ms) {
   if (ms >= 1000)
@@ -470,16 +472,25 @@ function logIncoming(req, pathname, traceId, ipAddress) {
   }
   return log;
 }
-function logOutgoing(req, pathname, status, log, ipAddress, errorCode2) {
+function structuredLine(own, extra) {
+  try {
+    return JSON.stringify({ ...extra, ...own });
+  } catch {
+    return JSON.stringify(own);
+  }
+}
+function logOutgoing(entry) {
+  const { req, pathname, status, log, ipAddress, errorCode: errorCode2, durationMs, extra } = entry;
   const ms = elapsedMs(log.startTime);
   if (isProd) {
-    console.log(JSON.stringify({
+    const own = {
       ts: new Date().toISOString(),
       level: levelForStatus(status),
       msg: `${req.method} ${pathname} ${status}`,
-      ...buildLogFields(req.method, pathname, status, Math.round(ms), log.traceId, errorCode2),
+      ...buildLogFields(req.method, pathname, status, durationMs, log.traceId, errorCode2),
       ip: ipAddress
-    }));
+    };
+    console.log(structuredLine(own, extra));
     return;
   }
   const mc = METHOD_COLOR[req.method] ?? c.dim;
@@ -487,14 +498,65 @@ function logOutgoing(req, pathname, status, log, ipAddress, errorCode2) {
   console.log(`${c.gray}[${timestamp()}]${c.reset} ${mc}${req.method}${c.reset} ${c.dim}${log.traceId}${c.reset} ${c.cyan}←${c.reset} ${safePath(pathname)} ${statusColor(status)}${status}${c.reset}${code} ${durationColor(ms)}${formatMs(ms)}${c.reset} ${ipLabel(ipAddress ?? "")}`);
 }
 
+// src/server/logging.ts
+var LOGGER_METHODS = ["info", "warn", "error", "debug"];
+function isBareLogger(value) {
+  if (value.logger !== undefined || value.skip !== undefined || value.enrich !== undefined) {
+    return false;
+  }
+  return LOGGER_METHODS.every((method) => typeof value[method] === "function");
+}
+function resolveLoggingConfig(logging) {
+  if (logging === false)
+    return null;
+  if (logging === true)
+    return {};
+  if (isRecord(logging) && isBareLogger(logging)) {
+    throw new Error("[stitchkit] `logging` no longer takes a StitchLogger directly — nest it: " + "`logging: { logger: myLogger }`.");
+  }
+  return logging;
+}
+function shouldSkipLog(config, req, url) {
+  if (!config.skip)
+    return false;
+  try {
+    return config.skip(req, url);
+  } catch {
+    return false;
+  }
+}
+function collectExtraLogFields(config, req, url, outcome) {
+  const fields = {};
+  const ctx = getRequestContext();
+  if (ctx) {
+    if (ctx.userId)
+      fields.userId = ctx.userId;
+    if (ctx.serviceName)
+      fields.serviceName = ctx.serviceName;
+    if (ctx.action)
+      fields.action = ctx.action;
+    if (ctx.dimensions)
+      fields.dimensions = ctx.dimensions;
+  }
+  if (config.enrich) {
+    try {
+      const extra = config.enrich(req, url, outcome);
+      if (extra)
+        Object.assign(fields, extra);
+    } catch {}
+  }
+  return fields;
+}
+
 // src/server/create.ts
 function createHandler(config) {
   const { cors, hooks, logging = false, trustProxy = false } = config;
   if (cors)
     assertCorsConfig(cors);
-  const customLogger = typeof logging === "object" ? logging : null;
-  const useDefaultLog = logging === true;
-  const resolveId = config.traceId ?? resolveTraceId;
+  const logConfig = resolveLoggingConfig(logging);
+  const customLogger = logConfig?.logger ?? null;
+  const useDefaultLog = logConfig !== null && !logConfig.logger;
+  const customTraceId = config.traceId;
   const routeMap = buildRouteMap(normalizeGroups(config));
   validateRoutes(routeMap);
   for (const shadow of findShadowedRoutes(routeMap, config.rawRoutes)) {
@@ -506,31 +568,56 @@ function createHandler(config) {
       console.warn(line);
   }
   async function dispatch(req, url, traceId, server, clientIp) {
-    const shouldLogRequest = logging && shouldLog(url.pathname, req.method);
+    const shouldLogRequest = logConfig !== null && shouldLog(url.pathname, req.method) && !shouldSkipLog(logConfig, req, url);
     const ipAddress = extractIp(req, clientIp) || undefined;
     let reqLog;
     if (shouldLogRequest && useDefaultLog) {
       reqLog = logIncoming(req, url.pathname, traceId, ipAddress);
     }
     if (shouldLogRequest && customLogger) {
-      customLogger.debug(`${req.method} ${url.pathname}`, {
-        traceId,
-        method: req.method,
-        path: url.pathname,
-        ip: ipAddress
-      });
       reqLog = { traceId, startTime: performance.now() };
+      try {
+        customLogger.debug(`${req.method} ${url.pathname}`, {
+          traceId,
+          method: req.method,
+          path: url.pathname,
+          ip: ipAddress
+        });
+      } catch {}
     }
+    let logged = false;
     const logDone = (status, errorCode2) => {
-      if (!reqLog)
+      if (!reqLog || logged || !logConfig)
         return;
-      if (useDefaultLog)
-        logOutgoing(req, url.pathname, status, reqLog, ipAddress, errorCode2);
-      if (customLogger) {
+      logged = true;
+      try {
         const durationMs = Math.round(elapsedMs(reqLog.startTime));
-        const level = levelForStatus(status);
-        customLogger[level](`${req.method} ${url.pathname} ${status}${errorCode2 ? ` ${errorCode2}` : ""} ${durationMs}ms`, buildLogFields(req.method, url.pathname, status, durationMs, reqLog.traceId, errorCode2));
-      }
+        const extra = collectExtraLogFields(logConfig, req, url, {
+          status,
+          durationMs,
+          errorCode: errorCode2
+        });
+        if (useDefaultLog) {
+          logOutgoing({
+            req,
+            pathname: url.pathname,
+            status,
+            log: reqLog,
+            ipAddress,
+            errorCode: errorCode2,
+            durationMs,
+            extra
+          });
+        }
+        if (customLogger) {
+          const level = levelForStatus(status);
+          customLogger[level](`${req.method} ${url.pathname} ${status}${errorCode2 ? ` ${errorCode2}` : ""} ${durationMs}ms`, {
+            ...extra,
+            ...buildLogFields(req.method, url.pathname, status, durationMs, reqLog.traceId, errorCode2),
+            ip: ipAddress
+          });
+        }
+      } catch {}
     };
     const respondError = async (err, errCtx, endpoint) => {
       if (hooks?.onError) {
@@ -548,9 +635,7 @@ function createHandler(config) {
       return json(appErr.toJSON(), appErr.status, cors, req);
     };
     if (cors && req.method === "OPTIONS") {
-      const res = corsPreflightResponse(cors, req);
-      logDone(204);
-      return res;
+      return corsPreflightResponse(cors, req);
     }
     if (hooks?.onRequest) {
       const earlyResponse = await hooks.onRequest(req);
@@ -623,10 +708,12 @@ function createHandler(config) {
       if (method.outputSchema) {
         const checked = validateHandlerOutput(method.outputSchema, result, config.warnOnOutputStrip ? (paths) => {
           const line = `[stitchkit] output strip ${method.serviceName}.${method.key}: ${paths.join(", ")}`;
-          if (customLogger)
-            customLogger.warn(line);
-          else
-            console.warn(line);
+          try {
+            if (customLogger)
+              customLogger.warn(line);
+            else
+              console.warn(line);
+          } catch {}
         } : undefined);
         if (!checked.ok) {
           throw new AppError("INTERNAL_SERVER_ERROR", checked.message, 500);
@@ -634,18 +721,20 @@ function createHandler(config) {
         result = checked.data;
       }
       if (result === undefined || result === null) {
+        const empty = new Response(null, { status: 204, headers: corsHeaders2(cors, req) });
         logDone(204);
-        return new Response(null, { status: 204, headers: corsHeaders2(cors, req) });
+        return empty;
       }
+      const body = json(result, 200, cors, req);
       logDone(200);
-      return json(result, 200, cors, req);
+      return body;
     } catch (err) {
       return respondError(err, ctx, method);
     }
   }
   return async (req, server) => {
     const url = new URL(req.url, "http://localhost");
-    const traceId = resolveId(req);
+    const traceId = customTraceId?.(req) ?? resolveTraceId(req);
     const clientIp = {
       trustProxy,
       socketIp: resolveSocketIp(req, server)
@@ -659,7 +748,8 @@ function createHandler(config) {
 }
 function createServer(config) {
   const { routes, websocket, development, bun: bunExtra, port = 3000, hostname } = config;
-  const fetch = createHandler(config);
+  const handler = createHandler(config);
+  const fetch = config.wrapFetch ? config.wrapFetch(handler) : handler;
   return websocket ? Bun.serve({
     ...bunExtra,
     ...routes && { routes },

package/dist/{index-dzx781tm.js → index-9g9d6r1h.js}

@@ -1,6 +1,3 @@
-import {
-  resolveTraceContext
-} from "./index-khwedj16.js";
 import {
   isRecord,
   isUnsafeKey
@@ -58,6 +55,45 @@ function parseQueryParams(url) {
   return query;
 }
 
+// src/observability/trace.ts
+var TRACEPARENT_RE = /^00-([0-9a-f]{32})-([0-9a-f]{16})-[0-9a-f]{2}$/i;
+function randomHex(bytes) {
+  const arr = new Uint8Array(bytes);
+  crypto.getRandomValues(arr);
+  let hex = "";
+  for (const byte of arr)
+    hex += byte.toString(16).padStart(2, "0");
+  return hex;
+}
+function createTraceContext() {
+  return { traceId: randomHex(16), spanId: randomHex(8) };
+}
+function parseTraceparent(header) {
+  if (!header)
+    return null;
+  const match = TRACEPARENT_RE.exec(header.trim());
+  if (!match?.[1] || !match[2])
+    return null;
+  const traceId = match[1].toLowerCase();
+  const parentSpanId = match[2].toLowerCase();
+  if (/^0+$/.test(traceId) || /^0+$/.test(parentSpanId))
+    return null;
+  return { traceId, spanId: randomHex(8), parentSpanId };
+}
+function formatTraceparent(ctx) {
+  return `00-${ctx.traceId}-${ctx.spanId}-01`;
+}
+function resolveTraceContext(req) {
+  return parseTraceparent(req.headers.get("traceparent")) ?? createTraceContext();
+}
+function childSpan(parent) {
+  return {
+    traceId: parent.traceId,
+    spanId: randomHex(8),
+    parentSpanId: parent.spanId
+  };
+}
+
 // src/observability/context.ts
 import { AsyncLocalStorage } from "node:async_hooks";
 var storage = new AsyncLocalStorage;
@@ -112,4 +148,4 @@ function wrapInRequestContext(handler, options = {}) {
   };
 }
 
-export { generateTraceId, resolveTraceId, resolveSocketIp, extractIp, getClientInfo, parseQueryParams, runWithRequestContext, getRequestContext, getTraceId, getUserId, setRequestUser, setRequestEndpoint, setRequestDimensions, setRequestError, wrapInRequestContext };
+export { generateTraceId, resolveTraceId, resolveSocketIp, extractIp, getClientInfo, parseQueryParams, createTraceContext, parseTraceparent, formatTraceparent, resolveTraceContext, childSpan, runWithRequestContext, getRequestContext, getTraceId, getUserId, setRequestUser, setRequestEndpoint, setRequestDimensions, setRequestError, wrapInRequestContext };

package/dist/{index-zfscdskj.js → index-czmqks7r.js}

@@ -1,6 +1,6 @@
 // src/server/middleware/cors.ts
 var DEFAULT_CORS_ALLOW_HEADERS = "Content-Type, Authorization, X-Trace-Id, traceparent, tracestate";
-var DEFAULT_CORS_EXPOSE_HEADERS = "Content-Disposition, Content-Length, Content-Range, Accept-Ranges, ETag, Last-Modified, X-Trace-Id";
+var DEFAULT_CORS_EXPOSE_HEADERS = "Content-Disposition, Content-Length, Content-Range, Accept-Ranges, ETag, Last-Modified, X-Request-Id";
 function assertCorsConfig(config) {
   if (config.credentials && (config.origin === undefined || config.origin === "*")) {
     throw new Error("[stitchkit] cors: `credentials: true` cannot be combined with a wildcard origin. " + "Set `origin` to an explicit string or list.");

package/dist/node.d.ts

@@ -9,5 +9,5 @@ export { createHandler } from './server/create';
 export { createImplement, implement } from './server/implement';
 export { type NodeServerConfig, type NodeServerHandle, serveNode } from './server/node';
 export { createSocketIOServer, type SocketIOServerConfig, type SocketIOServerHandle, } from './server/socket-io';
-export type { HandlerConfig, RawRoute, RawRouteContext, ServiceDef, } from './server/types';
+export type { FetchComposition, FetchHandler, HandlerConfig, LoggingConfig, LogOutcome, RawRoute, RawRouteContext, ServiceDef, } from './server/types';
 //# sourceMappingURL=node.d.ts.map

package/dist/node.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EACL,QAAQ,EACR,QAAQ,EACR,UAAU,EACV,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,WAAW,EACX,YAAY,GACb,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,EAAE,KAAK,gBAAgB,EAAE,KAAK,gBAAgB,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AACxF,OAAO,EACL,oBAAoB,EACpB,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,GAC1B,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,aAAa,EACb,QAAQ,EACR,eAAe,EACf,UAAU,GACX,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EACL,QAAQ,EACR,QAAQ,EACR,UAAU,EACV,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,WAAW,EACX,YAAY,GACb,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,EAAE,KAAK,gBAAgB,EAAE,KAAK,gBAAgB,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AACxF,OAAO,EACL,oBAAoB,EACpB,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,GAC1B,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,aAAa,EACb,UAAU,EACV,QAAQ,EACR,eAAe,EACf,UAAU,GACX,MAAM,gBAAgB,CAAC"}

package/dist/node.js

@@ -3,8 +3,8 @@ import {
   createImplement,
   createSocketIOServer,
   implement
-} from "./index-y4132gqh.js";
-import"./index-zfscdskj.js";
+} from "./index-17jpjnhd.js";
+import"./index-czmqks7r.js";
 import {
   AppError,
   appError,
@@ -15,15 +15,15 @@ import {
   rateLimited,
   unauthorized
 } from "./index-zza375qp.js";
-import"./index-dzx781tm.js";
-import"./index-khwedj16.js";
+import"./index-9g9d6r1h.js";
 import"./index-c7nyw0yt.js";
 // src/server/node.ts
 import { serve } from "srvx";
 async function serveNode(config) {
-  const { port = 3000, hostname, socket, ...handlerConfig } = config;
+  const { port = 3000, hostname, socket, wrapFetch, ...handlerConfig } = config;
   const handler = createHandler(handlerConfig);
-  const server = serve({ port, hostname, fetch: handler });
+  const fetch = wrapFetch ? wrapFetch(handler) : handler;
+  const server = serve({ port, hostname, fetch });
   await server.ready();
   if (socket) {
     const nodeServer = server.node?.server;

package/dist/observability/context.d.ts

@@ -97,10 +97,14 @@ export interface WrapRequestContextOptions {
  * (the inbound `traceparent` continued, or freshly minted), timing and client
  * info.
  *
- * Compose it as the OUTERMOST wrapper of the server's fetch handler. To make
- * the framework router reuse this trace id (so request logs and application
- * logs share one id), pass `traceId: getTraceId` to `createServer` /
- * `createHandler`.
+ * Compose it as the OUTERMOST wrapper of the server's fetch handler — with raw
+ * `Bun.serve`, or through `wrapFetch` on `createServer` / `serveNode`, which own
+ * their own `fetch`.
+ *
+ * To make the framework router reuse this trace id (so request logs and
+ * application logs share one id), pass `traceId: getTraceId` to `createServer` /
+ * `createHandler`: outside an active context it yields `undefined` and the
+ * framework falls back to its own resolver.
  */
 export declare function wrapInRequestContext<S>(handler: (req: Request, server: S) => Promise<Response>, options?: WrapRequestContextOptions): (req: Request, server: S) => Promise<Response>;
 //# sourceMappingURL=context.d.ts.map

package/dist/observability/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/observability/context.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD,OAAO,EAAuB,KAAK,YAAY,EAAE,MAAM,SAAS,CAAC;AAEjE,oDAAoD;AACpD,MAAM,WAAW,cAAc;IAC7B,sCAAsC;IACtC,KAAK,EAAE,YAAY,CAAC;IACpB,4CAA4C;IAC5C,MAAM,EAAE,eAAe,CAAC;IACxB,iBAAiB;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,oBAAoB;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,SAAS,EAAE,MAAM,CAAC;IAClB,kCAAkC;IAClC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uCAAuC;IACvC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC;8EAC0E;IAC1E,KAAK,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;CAChE;AAID,yDAAyD;AACzD,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,GAAG,EAAE,cAAc,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAE5E;AAED,sEAAsE;AACtE,wBAAgB,iBAAiB,IAAI,cAAc,GAAG,SAAS,CAE9D;AAED,mEAAmE;AACnE,wBAAgB,UAAU,IAAI,MAAM,GAAG,SAAS,CAE/C;AAED,qDAAqD;AACrD,wBAAgB,SAAS,IAAI,MAAM,GAAG,SAAS,CAE9C;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAGnD;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAM5E;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAG7E;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE;IACrC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,GAAG,IAAI,CAGP;AAED,0CAA0C;AAC1C,MAAM,WAAW,yBAAyB;IACxC;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EACpC,OAAO,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,KAAK,OAAO,CAAC,QAAQ,CAAC,EACvD,OAAO,GAAE,yBAA8B,GACtC,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,KAAK,OAAO,CAAC,QAAQ,CAAC,CAiBhD"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/observability/context.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD,OAAO,EAAuB,KAAK,YAAY,EAAE,MAAM,SAAS,CAAC;AAEjE,oDAAoD;AACpD,MAAM,WAAW,cAAc;IAC7B,sCAAsC;IACtC,KAAK,EAAE,YAAY,CAAC;IACpB,4CAA4C;IAC5C,MAAM,EAAE,eAAe,CAAC;IACxB,iBAAiB;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,oBAAoB;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,SAAS,EAAE,MAAM,CAAC;IAClB,kCAAkC;IAClC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uCAAuC;IACvC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC;8EAC0E;IAC1E,KAAK,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;CAChE;AAID,yDAAyD;AACzD,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,GAAG,EAAE,cAAc,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAE5E;AAED,sEAAsE;AACtE,wBAAgB,iBAAiB,IAAI,cAAc,GAAG,SAAS,CAE9D;AAED,mEAAmE;AACnE,wBAAgB,UAAU,IAAI,MAAM,GAAG,SAAS,CAE/C;AAED,qDAAqD;AACrD,wBAAgB,SAAS,IAAI,MAAM,GAAG,SAAS,CAE9C;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAGnD;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAM5E;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAG7E;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE;IACrC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,GAAG,IAAI,CAGP;AAED,0CAA0C;AAC1C,MAAM,WAAW,yBAAyB;IACxC;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EACpC,OAAO,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,KAAK,OAAO,CAAC,QAAQ,CAAC,EACvD,OAAO,GAAE,yBAA8B,GACtC,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,KAAK,OAAO,CAAC,QAAQ,CAAC,CAiBhD"}

package/dist/observability/index.js

@@ -1,21 +1,19 @@
 import {
+  childSpan,
+  createTraceContext,
+  formatTraceparent,
   getRequestContext,
   getTraceId,
   getUserId,
+  parseTraceparent,
+  resolveTraceContext,
   runWithRequestContext,
   setRequestDimensions,
   setRequestEndpoint,
   setRequestError,
   setRequestUser,
   wrapInRequestContext
-} from "../index-dzx781tm.js";
-import {
-  childSpan,
-  createTraceContext,
-  formatTraceparent,
-  parseTraceparent,
-  resolveTraceContext
-} from "../index-khwedj16.js";
+} from "../index-9g9d6r1h.js";
 import {
   isRecord,
   isUnsafeKey

package/dist/server/create.d.ts

@@ -1,4 +1,4 @@
-import type { BunServerConfig, HandlerConfig } from './types';
-export declare function createHandler(config: HandlerConfig): (req: Request) => Promise<Response>;
+import type { BunServerConfig, FetchHandler, HandlerConfig } from './types';
+export declare function createHandler(config: HandlerConfig): FetchHandler;
 export declare function createServer(config: BunServerConfig): Bun.Server<unknown>;
 //# sourceMappingURL=create.d.ts.map

package/dist/server/create.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../../src/server/create.ts"],"names":[],"mappings":"AAgCA,OAAO,KAAK,EAEV,eAAe,EACf,aAAa,EAGd,MAAM,SAAS,CAAC;AAEjB,wBAAgB,aAAa,CAAC,MAAM,EAAE,aAAa,GAAG,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAyRxF;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,eAAe,uBAsBnD"}
+{"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../../src/server/create.ts"],"names":[],"mappings":"AAiCA,OAAO,KAAK,EAEV,eAAe,EACf,YAAY,EACZ,aAAa,EAGd,MAAM,SAAS,CAAC;AAEjB,wBAAgB,aAAa,CAAC,MAAM,EAAE,aAAa,GAAG,YAAY,CAoVjE;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,eAAe,uBAuBnD"}

package/dist/server/index.d.ts

@@ -20,6 +20,6 @@ export { staticRoute } from './router';
 export type { SocketIOServerConfig, SocketIOServerHandle } from './socket-io';
 export { createSocketIOServer, socketIoLane } from './socket-io';
 export { type ParseSSEOptions, parseSSE, streamSSE } from './stream';
-export type { BunServer, BunServerConfig, HandlerConfig, Handlers, LifecycleHooks, MethodDef, RawRoute, RawRouteContext, RouteGroup, ServerPassthrough, ServiceDef, StitchLogger, } from './types';
+export type { BunServer, BunServerConfig, FetchComposition, FetchHandler, HandlerConfig, Handlers, LifecycleHooks, LoggingConfig, LogOutcome, MethodDef, RawRoute, RawRouteContext, RouteGroup, ServerPassthrough, ServiceDef, StitchLogger, } from './types';
 export { type ComposedLane, composeWebSocketHandlers, type WebSocketComposeConfig, type WebSocketLane, webSocketLane, } from './websocket';
 //# sourceMappingURL=index.d.ts.map

package/dist/server/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,QAAQ,EACR,QAAQ,EACR,UAAU,EACV,QAAQ,EACR,SAAS,EACT,iBAAiB,EACjB,QAAQ,EACR,WAAW,EACX,mBAAmB,EACnB,KAAK,eAAe,EACpB,YAAY,GACb,MAAM,aAAa,CAAC;AAIrB,OAAO,EACL,SAAS,EACT,cAAc,EACd,cAAc,EACd,KAAK,eAAe,EACpB,SAAS,GACV,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACvD,OAAO,EACL,eAAe,EACf,KAAK,eAAe,EACpB,KAAK,aAAa,GACnB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,cAAc,EAAE,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,EACL,KAAK,SAAS,EACd,cAAc,EACd,KAAK,gBAAgB,EACrB,SAAS,EACT,QAAQ,GACT,MAAM,QAAQ,CAAC;AAChB,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EACL,KAAK,QAAQ,EACb,KAAK,cAAc,EACnB,KAAK,QAAQ,EACb,KAAK,oBAAoB,EACzB,cAAc,EACd,oBAAoB,EACpB,YAAY,EACZ,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,OAAO,EACP,SAAS,GACV,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,YAAY,EACZ,YAAY,EACZ,eAAe,GAChB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,KAAK,UAAU,EACf,WAAW,EACX,qBAAqB,EACrB,0BAA0B,EAC1B,2BAA2B,GAC5B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,mBAAmB,EAAE,KAAK,UAAU,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACrF,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EACL,uBAAuB,EACvB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,YAAY,GACb,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,iBAAiB,EAAE,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AACvE,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AAC9D,OAAO,EACL,KAAK,eAAe,EACpB,SAAS,EACT,eAAe,EACf,aAAa,EACb,eAAe,EACf,cAAc,GACf,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,YAAY,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAC9E,OAAO,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACjE,OAAO,EAAE,KAAK,eAAe,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrE,YAAY,EACV,SAAS,EACT,eAAe,EACf,aAAa,EACb,QAAQ,EACR,cAAc,EACd,SAAS,EACT,QAAQ,EACR,eAAe,EACf,UAAU,EACV,iBAAiB,EACjB,UAAU,EACV,YAAY,GACb,MAAM,SAAS,CAAC;AACjB,OAAO,EACL,KAAK,YAAY,EACjB,wBAAwB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,aAAa,EAClB,aAAa,GACd,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,QAAQ,EACR,QAAQ,EACR,UAAU,EACV,QAAQ,EACR,SAAS,EACT,iBAAiB,EACjB,QAAQ,EACR,WAAW,EACX,mBAAmB,EACnB,KAAK,eAAe,EACpB,YAAY,GACb,MAAM,aAAa,CAAC;AAIrB,OAAO,EACL,SAAS,EACT,cAAc,EACd,cAAc,EACd,KAAK,eAAe,EACpB,SAAS,GACV,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACvD,OAAO,EACL,eAAe,EACf,KAAK,eAAe,EACpB,KAAK,aAAa,GACnB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,cAAc,EAAE,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,EACL,KAAK,SAAS,EACd,cAAc,EACd,KAAK,gBAAgB,EACrB,SAAS,EACT,QAAQ,GACT,MAAM,QAAQ,CAAC;AAChB,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EACL,KAAK,QAAQ,EACb,KAAK,cAAc,EACnB,KAAK,QAAQ,EACb,KAAK,oBAAoB,EACzB,cAAc,EACd,oBAAoB,EACpB,YAAY,EACZ,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,OAAO,EACP,SAAS,GACV,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,YAAY,EACZ,YAAY,EACZ,eAAe,GAChB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,KAAK,UAAU,EACf,WAAW,EACX,qBAAqB,EACrB,0BAA0B,EAC1B,2BAA2B,GAC5B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,mBAAmB,EAAE,KAAK,UAAU,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACrF,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EACL,uBAAuB,EACvB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,YAAY,GACb,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,iBAAiB,EAAE,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AACvE,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AAC9D,OAAO,EACL,KAAK,eAAe,EACpB,SAAS,EACT,eAAe,EACf,aAAa,EACb,eAAe,EACf,cAAc,GACf,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,YAAY,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAC9E,OAAO,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACjE,OAAO,EAAE,KAAK,eAAe,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrE,YAAY,EACV,SAAS,EACT,eAAe,EACf,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,QAAQ,EACR,cAAc,EACd,aAAa,EACb,UAAU,EACV,SAAS,EACT,QAAQ,EACR,eAAe,EACf,UAAU,EACV,iBAAiB,EACjB,UAAU,EACV,YAAY,GACb,MAAM,SAAS,CAAC;AACjB,OAAO,EACL,KAAK,YAAY,EACjB,wBAAwB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,aAAa,EAClB,aAAa,GACd,MAAM,aAAa,CAAC"}

package/dist/server/index.js

@@ -10,7 +10,7 @@ import {
   socketIoLane,
   staticRoute,
   webSocketLane
-} from "../index-y4132gqh.js";
+} from "../index-17jpjnhd.js";
 import {
   createAuthHook,
   createBearerResolver,
@@ -29,7 +29,7 @@ import {
   DEFAULT_CORS_EXPOSE_HEADERS,
   corsHeaders,
   corsPreflightResponse
-} from "../index-zfscdskj.js";
+} from "../index-czmqks7r.js";
 import {
   jsonSchemaFields,
   toJsonSchema
@@ -58,8 +58,7 @@ import {
   getTraceId,
   resolveSocketIp,
   resolveTraceId
-} from "../index-dzx781tm.js";
-import"../index-khwedj16.js";
+} from "../index-9g9d6r1h.js";
 import {
   isRecord
 } from "../index-c7nyw0yt.js";

package/dist/server/logger.d.ts

@@ -2,14 +2,19 @@
 export declare function elapsedMs(startTime: number): number;
 /** Map an HTTP status to a log level. */
 export declare function levelForStatus(status: number): 'error' | 'warn' | 'info';
-/** The structured fields shared by every completed-request log line. */
+/**
+ * The structured fields shared by every completed-request log line. `errorCode`
+ * is always present, `undefined` on success — a conditional key would let an
+ * `enrich` value survive on a 200, and these fields must always win the merge.
+ * `JSON.stringify` drops the undefined, so the production line is unchanged.
+ */
 export declare function buildLogFields(method: string, path: string, status: number, durationMs: number, traceId: string, errorCode?: string): {
     traceId: string;
     method: string;
     path: string;
     status: number;
     durationMs: number;
-    errorCode?: string;
+    errorCode: string | undefined;
 };
 export interface RequestLog {
     traceId: string;
@@ -18,6 +23,33 @@ export interface RequestLog {
 export declare function shouldLog(pathname: string, method: string): boolean;
 /** Open the timing window for a request. Development prints a `→` line. */
 export declare function logIncoming(req: Request, pathname: string, traceId: string, ipAddress?: string): RequestLog;
-/** Close a request. Development: `←` line. Production: one structured JSON line. */
-export declare function logOutgoing(req: Request, pathname: string, status: number, log: RequestLog, ipAddress?: string, errorCode?: string): void;
+/**
+ * Serialise one structured line: consumer fields under the framework's own. A
+ * value `JSON.stringify` refuses (a cycle, a `BigInt`) costs the consumer
+ * fields for that line — never the record, which is re-emitted alone.
+ */
+export declare function structuredLine(own: Record<string, unknown>, extra?: Record<string, unknown>): string;
+/** One finished request, as the formatter needs it. */
+export interface CompletedRequest {
+    req: Request;
+    pathname: string;
+    status: number;
+    log: RequestLog;
+    ipAddress?: string;
+    errorCode?: string;
+    /** Duration the caller already measured — the one `enrich` was shown. */
+    durationMs: number;
+    /**
+     * Consumer-supplied fields for the structured line — request-context
+     * identity and whatever `enrich` returned. Spread *first* so the framework's
+     * own fields overwrite anything that collides with them.
+     */
+    extra?: Record<string, unknown>;
+}
+/**
+ * Close a request. Development: `←` line — deliberately unchanged by `extra`,
+ * it is a line to read, not a record to query. Production: one structured JSON
+ * line, enriched.
+ */
+export declare function logOutgoing(entry: CompletedRequest): void;
 //# sourceMappingURL=logger.d.ts.map

package/dist/server/logger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/server/logger.ts"],"names":[],"mappings":"AAwCA,6DAA6D;AAC7D,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEnD;AAoBD,yCAAyC;AACzC,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAIxE;AAED,wEAAwE;AACxE,wBAAgB,cAAc,CAC5B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,EACf,SAAS,CAAC,EAAE,MAAM,GACjB;IACD,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAEA;AA0BD,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAID,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAGnE;AAED,2EAA2E;AAC3E,wBAAgB,WAAW,CACzB,GAAG,EAAE,OAAO,EACZ,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,SAAS,CAAC,EAAE,MAAM,GACjB,UAAU,CASZ;AAED,oFAAoF;AACpF,wBAAgB,WAAW,CACzB,GAAG,EAAE,OAAO,EACZ,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,UAAU,EACf,SAAS,CAAC,EAAE,MAAM,EAClB,SAAS,CAAC,EAAE,MAAM,GACjB,IAAI,CA4BN"}
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/server/logger.ts"],"names":[],"mappings":"AAwCA,6DAA6D;AAC7D,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEnD;AAoBD,yCAAyC;AACzC,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAIxE;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,EACf,SAAS,CAAC,EAAE,MAAM,GACjB;IACD,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;CAC/B,CAEA;AA0BD,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAID,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAGnE;AAED,2EAA2E;AAC3E,wBAAgB,WAAW,CACzB,GAAG,EAAE,OAAO,EACZ,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,SAAS,CAAC,EAAE,MAAM,GACjB,UAAU,CASZ;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,MAAM,CAMR;AAED,uDAAuD;AACvD,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,OAAO,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,UAAU,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yEAAyE;IACzE,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,IAAI,CAwBzD"}

package/dist/server/logging.d.ts

@@ -0,0 +1,20 @@
+import type { LoggingConfig, LogOutcome } from './types';
+/**
+ * Normalise `logging` into either a config or `null` (off). `true` is shorthand
+ * for `{}`: any object turns logging on, and `logger` decides which sink writes.
+ */
+export declare function resolveLoggingConfig(logging: boolean | LoggingConfig): LoggingConfig | null;
+/** Consult the consumer's noise filter. A throw means "do not skip". */
+export declare function shouldSkipLog(config: LoggingConfig, req: Request, url: URL): boolean;
+/**
+ * The fields a completion line carries beyond the framework's own — the active
+ * request context first (free identity: who, which operation, which tenant),
+ * then whatever `enrich` returns, which may override it. Both are merged
+ * *under* the framework fields by the caller, so neither can corrupt the record.
+ *
+ * Returns an empty object when no context is active and no `enrich` is set —
+ * the cost of observability that was never wired is one `AsyncLocalStorage`
+ * lookup.
+ */
+export declare function collectExtraLogFields(config: LoggingConfig, req: Request, url: URL, outcome: LogOutcome): Record<string, unknown>;
+//# sourceMappingURL=logging.d.ts.map

package/dist/server/logging.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logging.d.ts","sourceRoot":"","sources":["../../src/server/logging.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAmBzD;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,aAAa,GAAG,aAAa,GAAG,IAAI,CAU3F;AAED,wEAAwE;AACxE,wBAAgB,aAAa,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,GAAG,OAAO,CAQpF;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,aAAa,EACrB,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,GAAG,EACR,OAAO,EAAE,UAAU,GAClB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAyBzB"}

package/dist/server/middleware/cors.d.ts

@@ -34,8 +34,14 @@ export declare const DEFAULT_CORS_ALLOW_HEADERS = "Content-Type, Authorization,
  * the request carries credentials — exactly the authenticated download case.
  * These are headers the server already chose to send; exposing them reveals
  * nothing new. Opt out with `exposeHeaders: []`.
+ *
+ * `X-Request-Id` is the trace id every response carries — the id a browser
+ * client needs to quote in a bug report and the one a reverse proxy logs.
+ * Note the deliberate asymmetry with {@link DEFAULT_CORS_ALLOW_HEADERS}:
+ * inbound the id may arrive as `X-Trace-Id`, outbound it is always
+ * `X-Request-Id` — one name on the wire out, no alias.
  */
-export declare const DEFAULT_CORS_EXPOSE_HEADERS = "Content-Disposition, Content-Length, Content-Range, Accept-Ranges, ETag, Last-Modified, X-Trace-Id";
+export declare const DEFAULT_CORS_EXPOSE_HEADERS = "Content-Disposition, Content-Length, Content-Range, Accept-Ranges, ETag, Last-Modified, X-Request-Id";
 /**
  * Reject an unsafe CORS config at construction. `credentials: true` with a
  * wildcard origin would reflect *any* caller's `Origin` with

package/dist/server/middleware/cors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cors.d.ts","sourceRoot":"","sources":["../../../src/server/middleware/cors.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,UAAU;IACzB,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC3B,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;CACnC;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,0BAA0B,qEAC6B,CAAC;AAErE;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,2BAA2B,uGAC8D,CAAC;AAEvG;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CAOzD;AAoBD,wBAAgB,WAAW,CACzB,MAAM,EAAE,UAAU,EAClB,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,GAC5B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA2BxB;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,EAAE,OAAO,GAAG,QAAQ,CAKhF"}
+{"version":3,"file":"cors.d.ts","sourceRoot":"","sources":["../../../src/server/middleware/cors.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,UAAU;IACzB,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC3B,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;CACnC;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,0BAA0B,qEAC6B,CAAC;AAErE;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,2BAA2B,yGACgE,CAAC;AAEzG;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CAOzD;AAoBD,wBAAgB,WAAW,CACzB,MAAM,EAAE,UAAU,EAClB,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,GAC5B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA2BxB;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,EAAE,OAAO,GAAG,QAAQ,CAKhF"}

package/dist/server/node.d.ts

@@ -1,6 +1,6 @@
 import type { Server as HttpServer } from 'node:http';
-import type { HandlerConfig } from './types';
-export interface NodeServerConfig extends HandlerConfig {
+import type { FetchComposition, HandlerConfig } from './types';
+export interface NodeServerConfig extends HandlerConfig, FetchComposition {
     port?: number;
     hostname?: string;
     /**

package/dist/server/node.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../../src/server/node.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,WAAW,CAAC;AAGtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C,MAAM,WAAW,gBAAiB,SAAQ,aAAa;IACrD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,MAAM,CAAC,EAAE;QAAE,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CAAA;KAAE,CAAC;CAC/C;AAED,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,WAAW,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7C;AAED,wBAAsB,SAAS,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA6BnF"}
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../../src/server/node.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,WAAW,CAAC;AAGtD,OAAO,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE/D,MAAM,WAAW,gBAAiB,SAAQ,aAAa,EAAE,gBAAgB;IACvE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,MAAM,CAAC,EAAE;QAAE,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CAAA;KAAE,CAAC;CAC/C;AAED,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,WAAW,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7C;AAED,wBAAsB,SAAS,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA8BnF"}

package/dist/server/types.d.ts

@@ -154,6 +154,63 @@ export interface StitchLogger {
     error(msg: string, data?: Record<string, unknown>): void;
     debug(msg: string, data?: Record<string, unknown>): void;
 }
+/** How a request finished — what `LoggingConfig.enrich` gets to react to. */
+export interface LogOutcome {
+    status: number;
+    durationMs: number;
+    errorCode?: string;
+}
+/**
+ * Request-logging configuration. `logging: true` is shorthand for `logging: {}`
+ * — **any** object turns request logging on; `logger` replaces the built-in
+ * sink, and `skip` / `enrich` apply to whichever sink is active.
+ */
+export interface LoggingConfig {
+    /** Send lines here instead of to the built-in formatter. */
+    logger?: StitchLogger;
+    /**
+     * Silence a request. Consulted *after* the built-in noise filter (framework
+     * assets, `favicon`, preflights), so it can only quieten more, never restore
+     * a line the framework drops — `/_bun/` assets are served by the runtime
+     * before `fetch` sees them, so un-skipping would be a promise the router
+     * cannot keep. A throw is swallowed and treated as "do not skip".
+     *
+     * The case this exists for: a monitoring probe on a path that 404s every
+     * cycle, and Socket.IO's polling transport, which logs a line per poll.
+     */
+    skip?: (req: Request, url: URL) => boolean;
+    /**
+     * Extra fields for the completion line. Runs once per request, at close —
+     * not on the development `→` breadcrumb — and its keys are merged **under**
+     * the framework's own, which always win: `traceId`, `method`, `path`,
+     * `status`, `durationMs`, `errorCode` and `ip` in both sinks, plus `ts`,
+     * `level` and `msg` on the built-in production line.
+     *
+     * Four things to know:
+     * - It reaches the structured output only: the production JSON line and a
+     *   custom logger's `data`. The development `←` line stays as it is — it is a
+     *   human-readable line, not a record — so **enriched fields are invisible in
+     *   development**, which is exactly where they get written.
+     * - Values must survive `JSON.stringify` on the built-in line. One that does
+     *   not (a cycle, a `BigInt`) costs the extra fields for that line; the
+     *   framework's own are re-emitted alone rather than losing the record.
+     * - It is synchronous and the request body is **already consumed** by the
+     *   time it runs. Anything body-derived belongs in `createAuditHook`, which
+     *   clones the request before the handler.
+     * - Its values reach the sink as given. A header echoed straight into a
+     *   text-based logger can inject line breaks — sanitise anything
+     *   caller-controlled, as the framework does for the request path.
+     *
+     * A throw is swallowed; the line is still written without the extra fields.
+     */
+    enrich?: (req: Request, url: URL, outcome: LogOutcome) => Record<string, unknown> | undefined;
+}
+/**
+ * A fetch handler — what `createHandler` returns and what the servers hand to
+ * the runtime. The optional second argument is the runtime's server handle:
+ * Bun passes one (raw routes need it for upgrades), Node adapters never do.
+ */
+export type FetchHandler = (req: Request, server?: BunServer) => Promise<Response>;
 /**
  * Runtime-neutral handler config — everything `createHandler` needs.
  * No Bun globals, no Bun types. This is the portability seam.
@@ -181,7 +238,7 @@ export interface HandlerConfig {
     maxUploadBytes?: number;
     cors?: CorsConfig;
     hooks?: LifecycleHooks;
-    logging?: boolean | StitchLogger;
+    logging?: boolean | LoggingConfig;
     /**
      * Report handler-output keys the contract schema removed, as dot-paths, through
      * the configured logger. **Off by default** — the strip itself is correct (the
@@ -195,7 +252,14 @@ export interface HandlerConfig {
      * → ADR 0037.
      */
     warnOnOutputStrip?: boolean;
-    traceId?: (req: Request) => string;
+    /**
+     * Resolve the trace id for a request. Returning `undefined` falls back to
+     * {@link resolveTraceId} (a trusted inbound `x-request-id` / `x-trace-id`,
+     * else a fresh id) — which is what makes `traceId: getTraceId` work: outside
+     * an active observability context it yields `undefined`, and the framework
+     * mints one instead of stamping the string `"undefined"`.
+     */
+    traceId?: (req: Request) => string | undefined;
     /**
      * Trust the `x-forwarded-for` / `x-real-ip` headers for the client IP.
      * These are client-controllable — enable only when the server runs behind a
@@ -215,11 +279,29 @@ type BunDevelopmentOptions = BunServeOptions extends {
     development?: infer T;
 } ? T : never;
 export type ServerPassthrough = Omit<BunServeOptions, 'fetch' | 'port' | 'hostname' | 'unix' | 'routes' | 'websocket' | 'development'>;
+/**
+ * The composition seam shared by the servers that own their own `fetch`.
+ *
+ * `wrapInRequestContext` and `createAuditHook` must sit **outside** the
+ * handler, which used to mean building the server by hand — `createServer` and
+ * `serveNode` construct `fetch` internally, so neither could reach the
+ * observability layer at all. `wrapFetch` is where those wrappers go.
+ *
+ * Order is the consumer's, and it matters: `wrapInRequestContext` outermost,
+ * the audit wrapper inside it, because the audit hook reads that context.
+ *
+ * ```ts
+ * createServer({ services, wrapFetch: (h) => wrapInRequestContext(audit.http(h)) })
+ * ```
+ */
+export interface FetchComposition {
+    wrapFetch?: (fetch: FetchHandler) => FetchHandler;
+}
 /**
  * Full config for `createServer` — extends `HandlerConfig` with Bun-specific
  * options (`Bun.serve` routes, websocket, development, passthrough).
  */
-export interface BunServerConfig extends HandlerConfig {
+export interface BunServerConfig extends HandlerConfig, FetchComposition {
     port?: number;
     hostname?: string;
     routes?: BunRoutes;

package/dist/server/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/server/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/server/types.ts"],"names":[],"mappings":"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"}

package/dist/tools/tool-logger.d.ts

@@ -15,6 +15,13 @@ export interface ToolCallRecord {
     durationMs: number;
     /** Transport tag the call came in on (`ctx.source`). */
     source: string;
+    /**
+     * The active trace id, when an observability context is running — the key
+     * that joins this line to the HTTP request that triggered the tool call.
+     * Absent when nothing established a context (`wrapInRequestContext`, or a
+     * server's `wrapFetch`).
+     */
+    traceId?: string;
 }
 /** Config for `createToolLogger`. */
 export interface ToolLoggerConfig {

package/dist/tools/tool-logger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-logger.d.ts","sourceRoot":"","sources":["../../src/tools/tool-logger.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAE/C,kFAAkF;AAClF,MAAM,WAAW,cAAc;IAC7B,6BAA6B;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,+CAA+C;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,MAAM,EAAE,MAAM,CAAC;IACf,kCAAkC;IAClC,EAAE,EAAE,OAAO,CAAC;IACZ,4CAA4C;IAC5C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mDAAmD;IACnD,UAAU,EAAE,MAAM,CAAC;IACnB,wDAAwD;IACxD,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,qCAAqC;AACrC,MAAM,WAAW,gBAAgB;IAC/B,2DAA2D;IAC3D,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7B,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,cAAc,KAAK,IAAI,CAAC;CAC7C;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,GAAE,gBAAqB,GAAG,aAAa,CAoB7E"}
+{"version":3,"file":"tool-logger.d.ts","sourceRoot":"","sources":["../../src/tools/tool-logger.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAE/C,kFAAkF;AAClF,MAAM,WAAW,cAAc;IAC7B,6BAA6B;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,+CAA+C;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,MAAM,EAAE,MAAM,CAAC;IACf,kCAAkC;IAClC,EAAE,EAAE,OAAO,CAAC;IACZ,4CAA4C;IAC5C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mDAAmD;IACnD,UAAU,EAAE,MAAM,CAAC;IACnB,wDAAwD;IACxD,MAAM,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,qCAAqC;AACrC,MAAM,WAAW,gBAAgB;IAC/B,2DAA2D;IAC3D,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7B,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,cAAc,KAAK,IAAI,CAAC;CAC7C;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,GAAE,gBAAqB,GAAG,aAAa,CAqB7E"}

package/dist/tools.js

@@ -5,7 +5,7 @@ import {
 } from "./index-jvescqgr.js";
 import {
   DEFAULT_CORS_ALLOW_HEADERS
-} from "./index-zfscdskj.js";
+} from "./index-czmqks7r.js";
 import {
   assertToolName,
   assertUniqueToolName,
@@ -30,7 +30,9 @@ import {
   isWithinDir,
   mergeMeta
 } from "./index-zza375qp.js";
-import"./index-khwedj16.js";
+import {
+  getTraceId
+} from "./index-9g9d6r1h.js";
 import {
   isRecord,
   typedEntries
@@ -1223,7 +1225,8 @@ function createToolLogger(config = {}) {
         ok: result.ok,
         code: result.ok ? undefined : result.code,
         durationMs: Math.round(durationMs),
-        source: String(context.source)
+        source: String(context.source),
+        traceId: getTraceId()
       };
       const codePart = result.ok ? "" : ` ${result.code}`;
       log(`[tool] ${result.ok ? "ok" : "warn"} ${toolName} (${endpoint.serviceName}.${endpoint.key})${codePart} ${record.durationMs}ms`);

package/llms-full.txt

@@ -620,11 +620,47 @@ server. See [Testing & deployment](./testing-and-deployment.md).
 | `port` / `hostname` | listen address — port defaults to `3000` |
 | `cors` | CORS policy — `{ origin, credentials, methods, headers, exposeHeaders }` |
 | `hooks` | lifecycle hooks (see below) |
-| `logging` | `true` for built-in request logs, or a custom `StitchLogger` |
-| `traceId` | override per-request trace-id resolution |
+| `logging` | `true` for built-in request logs, or a `LoggingConfig` (see below) |
+| `traceId` | override per-request trace-id resolution — may return `undefined` to fall back |
+| `wrapFetch` | compose wrappers around the finished handler (request context, audit) |
 | `websocket` | Bun WebSocket handlers — e.g. from `createSocketIOServer` |
 | `routes` / `development` / `bun` | passthrough to `Bun.serve` |
 
+### Request logging
+
+`logging: true` is shorthand for `logging: {}` — **any object turns logging
+on**, and the fields tune it:
+
+```ts
+createServer({
+  services,
+  logging: {
+    // Route lines into your stack instead of the built-in formatter.
+    logger: myLogger,
+    // Silence noise. Runs after the built-in filter (framework assets,
+    // favicon, preflights), so it can only quieten more.
+    skip: (_req, url) => url.pathname === '/health' || url.pathname.startsWith('/socket.io/'),
+    // Extra fields on the completion line.
+    enrich: (req, _url, { status }) => ({
+      userAgent: req.headers.get('user-agent') ?? undefined,
+      cacheable: status === 200,
+    }),
+  },
+})
+```
+
+Three things worth knowing about `enrich`: it reaches the **structured** output
+only (the production JSON line and a custom logger's `data`) — the development
+`←` line stays human-readable, so enriched fields are invisible in dev; it runs
+at close, when the request body is already consumed; and framework fields
+(`traceId`, `status`, `path`, …) always win a key collision. A throw in `skip`
+or `enrich` is swallowed — neither can fail a request.
+
+With an observability context active, the line also carries `userId`,
+`serviceName`, `action` and `dimensions` for free — and, like `enrich`'s fields,
+only in the structured output, never on the development `←` line. See
+[Observability](./observability.md).
+
 ## Route groups
 
 A group gives a set of services a shared path prefix and its own hooks:
@@ -1752,7 +1788,10 @@ mountMcp(server, services, { hooks: createToolLogger() })
 ```
 
 Pass `log` to redirect the line, or `onRecord` to feed a metrics sink the
-structured `ToolCallRecord`. For a boot-time picture of what is exposed where,
+structured `ToolCallRecord`. That record carries `traceId` whenever an
+observability context is active, so a tool call made inside an HTTP request
+joins that request's log line on one key — see
+[Observability](./observability.md). For a boot-time picture of what is exposed where,
 `summarizeTransports(services)` returns per-transport operation counts (HTTP /
 MCP / AGENT / CLI) for you to log.
 
@@ -2790,6 +2829,16 @@ Bun.serve({
 })
 ```
 
+`createServer` and `serveNode` build their own `fetch`, so compose through
+**`wrapFetch`** instead — same order, the context outermost:
+
+```ts
+createServer({
+  services,
+  wrapFetch: (fetch) => wrapInRequestContext(audit.http(fetch)),
+})
+```
+
 Some fields are filled in late. Set them from the hooks that know:
 
 ```ts
@@ -2829,8 +2878,51 @@ application logs carry one id — by passing `getTraceId` as the resolver:
 createHandler({ /* … */ traceId: getTraceId })
 ```
 
+`getTraceId` returns `undefined` outside an active context, and the framework
+falls back to its own resolver — a trusted inbound `x-request-id` / `x-trace-id`,
+else a fresh id — so the line never carries the string `"undefined"`.
+
 `getRequestContext()` / `getTraceId()` then return the active values from
 anywhere in the call — stamp `getTraceId()` onto every line your logger writes.
+The **request log picks the context up on its own**: with a context active, each
+completion line carries `userId`, `serviceName`, `action` and `dimensions`
+without any configuration.
+
+⚠️ In the **structured** output only — the production JSON line and a custom
+`logger`'s `data`. The development `←` line is a line to read, not a record to
+query, and never carries them (nor `enrich`'s fields). On `logging: true` in
+development you will see no difference; check with `NODE_ENV=production` or a
+custom `logger`.
+
+### Correlating with a reverse proxy
+
+Every response the stitchkit handler produces carries the resolved id as
+**`x-request-id`**. With `cors` configured it is in the default
+`Access-Control-Expose-Headers`, so a browser client can read it and quote it in
+a bug report. Note the deliberate asymmetry: inbound the id may arrive as
+`X-Trace-Id` *or* `X-Request-Id`; outbound there is one name and no alias.
+
+Log the same id from nginx and the two logs join on one key. `log_format` and
+`map` are `http {}`-context directives — put the block there, not inside
+`server {}`:
+
+```nginx
+log_format  stitch  '$remote_addr $status $request_time rid=$rid "$request"';
+
+# Fall back to nginx's own id for responses stitchkit never produced — Bun's
+# native `routes`, a throwing `onRequest` (which escapes before any response
+# exists), a redirect whose headers are immutable.
+map $upstream_http_x_request_id $rid {
+    ""      $request_id;
+    default $upstream_http_x_request_id;
+}
+
+access_log /var/log/nginx/access.log stitch;
+```
+
+`grep rid=<id>` across both logs then reconstructs the whole request. Tool calls
+join too: `createToolLogger`'s record carries `traceId`, so an MCP or agent call
+made inside a request lines up with it.
 
 ### Trace context
 
@@ -3076,10 +3168,13 @@ Notes for a Node host:
 
 - **CORS** — set `cors.origin` to your real front-end origin(s). Do not ship
   `origin: '*'` with credentials.
-- **Logging** — `logging: true` for built-in request logs, or pass a
-  `StitchLogger` to route them into your logging stack.
+- **Logging** — `logging: true` for built-in request logs, or
+  `logging: { logger, skip, enrich }` to route them into your logging stack,
+  drop probe noise and add your own fields.
 - **Trace ids** — override `traceId` to reuse an id your platform already
-  assigns, so request logs and application logs share one id.
+  assigns, so request logs and application logs share one id. Every response
+  carries it as `x-request-id`; log `$upstream_http_x_request_id` at the proxy
+  to join the two logs.
 - **Rate limiting** — `createRateLimiter` in `onRequest` for a global limit;
   per-route limits belong in `beforeHandle`.
 - **Auth** — a `createAuthHook` `beforeHandle` guards every transport at once;
@@ -3509,6 +3604,10 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | `BunServer` | _type_ | the `Bun.serve` instance type |
 | `ServerPassthrough` | _type_ | extra `Bun.serve` options |
 | `StitchLogger` | _type_ | the custom-logger interface |
+| `LoggingConfig` | _type_ | the `logging` object — `logger` / `skip` / `enrich` |
+| `LogOutcome` | _type_ | how a request finished, as `enrich` sees it |
+| `FetchHandler` | _type_ | what `createHandler` returns |
+| `FetchComposition` | _type_ | the `wrapFetch` seam shared by the servers |
 
 ### Auth
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "description": "Contract-first backend framework — one defineContract() into an HTTP API, MCP tools, AI-agent tools and a typed client. Bun and Node.",
   "keywords": [
     "bun",

package/dist/index-khwedj16.js

@@ -1,40 +0,0 @@
-// src/observability/trace.ts
-var TRACEPARENT_RE = /^00-([0-9a-f]{32})-([0-9a-f]{16})-[0-9a-f]{2}$/i;
-function randomHex(bytes) {
-  const arr = new Uint8Array(bytes);
-  crypto.getRandomValues(arr);
-  let hex = "";
-  for (const byte of arr)
-    hex += byte.toString(16).padStart(2, "0");
-  return hex;
-}
-function createTraceContext() {
-  return { traceId: randomHex(16), spanId: randomHex(8) };
-}
-function parseTraceparent(header) {
-  if (!header)
-    return null;
-  const match = TRACEPARENT_RE.exec(header.trim());
-  if (!match?.[1] || !match[2])
-    return null;
-  const traceId = match[1].toLowerCase();
-  const parentSpanId = match[2].toLowerCase();
-  if (/^0+$/.test(traceId) || /^0+$/.test(parentSpanId))
-    return null;
-  return { traceId, spanId: randomHex(8), parentSpanId };
-}
-function formatTraceparent(ctx) {
-  return `00-${ctx.traceId}-${ctx.spanId}-01`;
-}
-function resolveTraceContext(req) {
-  return parseTraceparent(req.headers.get("traceparent")) ?? createTraceContext();
-}
-function childSpan(parent) {
-  return {
-    traceId: parent.traceId,
-    spanId: randomHex(8),
-    parentSpanId: parent.spanId
-  };
-}
-
-export { createTraceContext, parseTraceparent, formatTraceparent, resolveTraceContext, childSpan };