stitchkit 0.10.0 → 0.11.0

package/dist/index-fwqnkc90.js

@@ -0,0 +1,151 @@
+import {
+  isRecord,
+  isUnsafeKey
+} from "./index-tm7dqzxc.js";
+
+// src/server/request.ts
+function generateTraceId() {
+  return `${Date.now().toString(36)}-${crypto.randomUUID().slice(0, 8)}`;
+}
+function resolveTraceId(req) {
+  const header = req.headers.get("x-request-id") ?? req.headers.get("x-trace-id");
+  const trimmed = header?.trim();
+  if (trimmed && trimmed.length <= 128 && /^[\w.-]+$/.test(trimmed)) {
+    return trimmed;
+  }
+  return generateTraceId();
+}
+function resolveSocketIp(req, server) {
+  if (typeof server === "object" && server !== null && "requestIP" in server && typeof server.requestIP === "function") {
+    const addr = server.requestIP(req);
+    if (isRecord(addr) && typeof addr.address === "string" && addr.address) {
+      return addr.address;
+    }
+  }
+  if ("ip" in req && typeof req.ip === "string" && req.ip)
+    return req.ip;
+  return;
+}
+function extractIp(req, options = {}) {
+  if (options.trustProxy) {
+    const forwarded = req.headers.get("x-forwarded-for");
+    if (forwarded)
+      return (forwarded.split(",")[0] ?? "").trim().replace(/^::ffff:/, "");
+    const realIp = req.headers.get("x-real-ip");
+    if (realIp)
+      return realIp.trim().replace(/^::ffff:/, "");
+  }
+  return (options.socketIp ?? "").replace(/^::ffff:/, "");
+}
+function getClientInfo(req, options = {}) {
+  return {
+    ipAddress: extractIp(req, options) || undefined,
+    userAgent: req.headers.get("user-agent") ?? undefined
+  };
+}
+function parseQueryParams(url) {
+  const query = {};
+  for (const key of new Set(url.searchParams.keys())) {
+    if (isUnsafeKey(key))
+      continue;
+    const values = url.searchParams.getAll(key);
+    const [first] = values;
+    query[key] = values.length === 1 && first !== undefined ? first : values;
+  }
+  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;
+function runWithRequestContext(ctx, fn) {
+  return storage.run(ctx, fn);
+}
+function getRequestContext() {
+  return storage.getStore();
+}
+function getTraceId() {
+  return storage.getStore()?.trace.traceId;
+}
+function getUserId() {
+  return storage.getStore()?.userId;
+}
+function setRequestUser(userId) {
+  const ctx = storage.getStore();
+  if (ctx)
+    ctx.userId = userId;
+}
+function setRequestEndpoint(serviceName, action) {
+  const ctx = storage.getStore();
+  if (ctx) {
+    ctx.serviceName = serviceName;
+    ctx.action = action;
+  }
+}
+function setRequestDimensions(dimensions) {
+  const ctx = storage.getStore();
+  if (ctx)
+    ctx.dimensions = { ...ctx.dimensions, ...dimensions };
+}
+function setRequestError(error) {
+  const ctx = storage.getStore();
+  if (ctx)
+    ctx.error = error;
+}
+function wrapInRequestContext(handler, options = {}) {
+  return (req, server) => {
+    const ctx = {
+      trace: resolveTraceContext(req),
+      source: "http",
+      method: req.method,
+      path: new URL(req.url, "http://localhost").pathname,
+      startedAt: process.hrtime.bigint(),
+      ...getClientInfo(req, {
+        trustProxy: options.trustProxy,
+        socketIp: resolveSocketIp(req, server)
+      })
+    };
+    return runWithRequestContext(ctx, () => handler(req, server));
+  };
+}
+
+export { generateTraceId, resolveTraceId, resolveSocketIp, extractIp, getClientInfo, parseQueryParams, createTraceContext, parseTraceparent, formatTraceparent, resolveTraceContext, childSpan, runWithRequestContext, getRequestContext, getTraceId, getUserId, setRequestUser, setRequestEndpoint, setRequestDimensions, setRequestError, wrapInRequestContext };

package/dist/{index-s8gtzt8w.js → index-renxz7c2.js}

@@ -10,8 +10,9 @@ import {
   getClientInfo,
   parseQueryParams,
   resolveSocketIp,
-  resolveTraceId
-} from "./index-p9m9c0jw.js";
+  resolveTraceId,
+  setRequestEndpoint
+} from "./index-fwqnkc90.js";
 import {
   __require,
   isUnsafeKey,
@@ -600,6 +601,7 @@ function createHandler(config) {
     }
     const { method, pathParams, groupHooks } = match;
     const ctx = buildBaseContext(req, url, pathParams, traceId, clientIp);
+    setRequestEndpoint(method.serviceName, method.key);
     try {
       await parseRequestInto(ctx, req, url, method, config.maxUploadBytes);
       if (hooks?.beforeHandle) {

package/dist/node.js

@@ -3,7 +3,7 @@ import {
   createImplement,
   createSocketIOServer,
   implement
-} from "./index-s8gtzt8w.js";
+} from "./index-renxz7c2.js";
 import {
   AppError,
   appError,
@@ -14,7 +14,7 @@ import {
   rateLimited,
   unauthorized
 } from "./index-jgpsd7dy.js";
-import"./index-p9m9c0jw.js";
+import"./index-fwqnkc90.js";
 import"./index-tm7dqzxc.js";
 // src/server/node.ts
 import { serve } from "srvx";

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

@@ -1 +1 @@
-{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../../src/observability/audit.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,aAAa,EAAc,MAAM,kBAAkB,CAAC;AAElE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,EAAe,KAAK,eAAe,EAAmB,MAAM,YAAY,CAAC;AAGhF,oCAAoC;AACpC,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,KAAK,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD,iFAAiF;IACjF,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,OAAO,CAAC;IAC1C,yEAAyE;IACzE,QAAQ,CAAC,EAAE,eAAe,CAAC;CAC5B;AAED,qEAAqE;AACrE,MAAM,WAAW,SAAS;IACxB;;;;OAIG;IACH,IAAI,EAAE,CAAC,CAAC,EACN,OAAO,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,KAAK,OAAO,CAAC,QAAQ,CAAC,KACpD,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IACpD;;;OAGG;IACH,QAAQ,EAAE,aAAa,CAAC;CACzB;AAmBD,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,CAgG9D"}
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../../src/observability/audit.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,aAAa,EAAc,MAAM,kBAAkB,CAAC;AAElE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,EAAe,KAAK,eAAe,EAAmB,MAAM,YAAY,CAAC;AAGhF,oCAAoC;AACpC,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,KAAK,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD,iFAAiF;IACjF,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,OAAO,CAAC;IAC1C,yEAAyE;IACzE,QAAQ,CAAC,EAAE,eAAe,CAAC;CAC5B;AAED,qEAAqE;AACrE,MAAM,WAAW,SAAS;IACxB;;;;OAIG;IACH,IAAI,EAAE,CAAC,CAAC,EACN,OAAO,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,KAAK,OAAO,CAAC,QAAQ,CAAC,KACpD,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IACpD;;;OAGG;IACH,QAAQ,EAAE,aAAa,CAAC;CACzB;AAmBD,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,CAsG9D"}

package/dist/observability/context.d.ts

@@ -19,6 +19,20 @@ export interface RequestContext {
     userAgent?: string;
     /** Resolved user id — set late, once auth has run. */
     userId?: string;
+    /**
+     * Stable endpoint identity — `(serviceName, action)` of the matched contract
+     * route. Written by the HTTP pipeline when the route matches, *before*
+     * validation, so even a failed request is attributed to the operation it
+     * targeted. → ADR 0022.
+     */
+    serviceName?: string;
+    action?: string;
+    /**
+     * App-defined domain dimensions (a tenant / project / entity id, …) — an
+     * opaque bag the core attaches no meaning to (→ ADR 0021), surfaced on
+     * `RequestEvent.dimensions`. Set via `setRequestDimensions`.
+     */
+    dimensions?: Record<string, string>;
     /** Error outcome — set late, by the error handler. */
     error?: {
         code?: string;
@@ -40,6 +54,23 @@ export declare function getUserId(): string | undefined;
  * from the auth hook.
  */
 export declare function setRequestUser(userId: string): void;
+/**
+ * Attach the matched endpoint's stable `(serviceName, action)` identity to the
+ * active context. The framework's HTTP pipeline calls this when a contract route
+ * matches — *before* validation — so the audit event for a request carries the
+ * operation it targeted even when the request fails pre-handler. No-op outside a
+ * request context. → ADR 0022.
+ */
+export declare function setRequestEndpoint(serviceName: string, action: string): void;
+/**
+ * Merge app-defined domain dimensions (a tenant / project / entity id, …) onto
+ * the active context — an opaque bag the core gives no meaning to (→ ADR 0021),
+ * surfaced on `RequestEvent.dimensions`. Resolve them cheaply from `ctx.params` /
+ * headers in `beforeHandle` (success) or `onError` (a pre-handler failure) and
+ * they land on the audit event for the request, success or failure alike. Merges
+ * across calls; no-op outside a request context.
+ */
+export declare function setRequestDimensions(dimensions: Record<string, string>): void;
 /**
  * Record the error outcome on the active context. Call this from the error
  * handler — the audit hook reads it when the request completes. Optional

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

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/observability/context.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,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,sDAAsD;IACtD,KAAK,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,SAAS,CAAA;KAAE,CAAC;CAClE;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;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE;IACrC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,SAAS,CAAC;CACrB,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,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,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,sDAAsD;IACtD,KAAK,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,SAAS,CAAA;KAAE,CAAC;CAClE;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;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE;IACrC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,SAAS,CAAC;CACrB,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"}

package/dist/observability/event.d.ts

@@ -13,6 +13,20 @@ export interface RequestEvent {
     method: string;
     /** Request path — `/api/...` for HTTP, `/{source}/{tool}` for a tool call. */
     path: string;
+    /**
+     * Stable owning-contract identity of the matched operation — the "service"
+     * (contract prefix) and "action" (endpoint key) halves. Set on every surface
+     * (HTTP, MCP, agent) from the contract, not parsed from `path`. → ADR 0022.
+     */
+    serviceName?: string;
+    action?: string;
+    /**
+     * App-defined domain dimensions for the call — e.g. a tenant / project /
+     * entity id. An opaque bag the core attaches no meaning to (→ ADR 0021);
+     * populated by `setRequestDimensions`. The sink maps it onto its own columns
+     * instead of re-deriving identity from the path.
+     */
+    dimensions?: Record<string, string>;
     /** Tool name — tool calls only. */
     toolName?: string;
     /** W3C trace id — correlates every span of one logical request. */

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

@@ -1 +1 @@
-{"version":3,"file":"event.d.ts","sourceRoot":"","sources":["../../src/observability/event.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,mCAAmC;IACnC,MAAM,EAAE,eAAe,CAAC;IACxB,4CAA4C;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,8EAA8E;IAC9E,IAAI,EAAE,MAAM,CAAC;IACb,mCAAmC;IACnC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mEAAmE;IACnE,OAAO,EAAE,MAAM,CAAC;IAChB,yCAAyC;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,8DAA8D;IAC9D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kCAAkC;IAClC,EAAE,EAAE,OAAO,CAAC;IACZ,6EAA6E;IAC7E,UAAU,EAAE,MAAM,CAAC;IACnB,2BAA2B;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,kCAAkC;IAClC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qCAAqC;IACrC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,WAAW,CAAC,EAAE,SAAS,CAAC;IACxB,uEAAuE;IACvE,OAAO,EAAE,SAAS,GAAG,IAAI,CAAC;IAC1B,mDAAmD;IACnD,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,4CAA4C;IAC5C,aAAa,EAAE,MAAM,CAAC;IACtB,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iBAAiB;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yBAAyB;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6BAA6B;IAC7B,SAAS,EAAE,IAAI,CAAC;CACjB"}
+{"version":3,"file":"event.d.ts","sourceRoot":"","sources":["../../src/observability/event.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,mCAAmC;IACnC,MAAM,EAAE,eAAe,CAAC;IACxB,4CAA4C;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,8EAA8E;IAC9E,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,mCAAmC;IACnC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mEAAmE;IACnE,OAAO,EAAE,MAAM,CAAC;IAChB,yCAAyC;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,8DAA8D;IAC9D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kCAAkC;IAClC,EAAE,EAAE,OAAO,CAAC;IACZ,6EAA6E;IAC7E,UAAU,EAAE,MAAM,CAAC;IACnB,2BAA2B;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,kCAAkC;IAClC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qCAAqC;IACrC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,WAAW,CAAC,EAAE,SAAS,CAAC;IACxB,uEAAuE;IACvE,OAAO,EAAE,SAAS,GAAG,IAAI,CAAC;IAC1B,mDAAmD;IACnD,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,4CAA4C;IAC5C,aAAa,EAAE,MAAM,CAAC;IACtB,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iBAAiB;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yBAAyB;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6BAA6B;IAC7B,SAAS,EAAE,IAAI,CAAC;CACjB"}

package/dist/observability/index.d.ts

@@ -7,7 +7,7 @@
  * function — nothing else.
  */
 export { type AuditConfig, type AuditHook, createAuditHook } from './audit';
-export { getRequestContext, getTraceId, getUserId, type RequestContext, runWithRequestContext, setRequestError, setRequestUser, wrapInRequestContext, } from './context';
+export { getRequestContext, getTraceId, getUserId, type RequestContext, runWithRequestContext, setRequestDimensions, setRequestEndpoint, setRequestError, setRequestUser, wrapInRequestContext, } from './context';
 export type { RequestEvent } from './event';
 export { type JsonValue, measureSize, redact, type SanitizeOptions, type SizeMeasure, sanitizePayload, truncatePreview, } from './sanitize';
 export { childSpan, createTraceContext, formatTraceparent, parseTraceparent, resolveTraceContext, type TraceContext, } from './trace';

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/observability/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,SAAS,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC5E,OAAO,EACL,iBAAiB,EACjB,UAAU,EACV,SAAS,EACT,KAAK,cAAc,EACnB,qBAAqB,EACrB,eAAe,EACf,cAAc,EACd,oBAAoB,GACrB,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,EACL,KAAK,SAAS,EACd,WAAW,EACX,MAAM,EACN,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,eAAe,EACf,eAAe,GAChB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,SAAS,EACT,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,mBAAmB,EACnB,KAAK,YAAY,GAClB,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/observability/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,SAAS,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC5E,OAAO,EACL,iBAAiB,EACjB,UAAU,EACV,SAAS,EACT,KAAK,cAAc,EACnB,qBAAqB,EACrB,oBAAoB,EACpB,kBAAkB,EAClB,eAAe,EACf,cAAc,EACd,oBAAoB,GACrB,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,EACL,KAAK,SAAS,EACd,WAAW,EACX,MAAM,EACN,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,eAAe,EACf,eAAe,GAChB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,SAAS,EACT,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,mBAAmB,EACnB,KAAK,YAAY,GAClB,MAAM,SAAS,CAAC"}

package/dist/observability/index.js

@@ -8,11 +8,12 @@ import {
   parseTraceparent,
   resolveTraceContext,
   runWithRequestContext,
+  setRequestDimensions,
+  setRequestEndpoint,
   setRequestError,
   setRequestUser,
   wrapInRequestContext
-} from "../index-031q8xmx.js";
-import"../index-p9m9c0jw.js";
+} from "../index-fwqnkc90.js";
 import {
   isRecord,
   isUnsafeKey
@@ -140,6 +141,9 @@ function createAuditHook(config) {
             source: ctx.source,
             method: ctx.method,
             path: ctx.path,
+            ...ctx.serviceName !== undefined && { serviceName: ctx.serviceName },
+            ...ctx.action !== undefined && { action: ctx.action },
+            ...ctx.dimensions !== undefined && { dimensions: ctx.dimensions },
             traceId: ctx.trace.traceId,
             spanId: ctx.trace.spanId,
             parentSpanId: ctx.trace.parentSpanId,
@@ -163,14 +167,17 @@ function createAuditHook(config) {
     };
   };
   const toolCall = {
-    afterToolCall: (toolName, args, result, durationMs, context) => {
-      const parent = getRequestContext()?.trace;
-      const span = parent ? childSpan(parent) : createTraceContext();
+    afterToolCall: (toolName, args, result, durationMs, context, endpoint) => {
+      const requestCtx = getRequestContext();
+      const span = requestCtx ? childSpan(requestCtx.trace) : createTraceContext();
       const measure = result.ok ? measureSize(result.data) : { resultSize: null, responseBytes: 0 };
       emit({
         source: context.source,
         method: "TOOL",
         path: `/${context.source}/${toolName}`,
+        serviceName: endpoint.serviceName,
+        action: endpoint.key,
+        ...requestCtx?.dimensions !== undefined && { dimensions: requestCtx.dimensions },
         toolName,
         traceId: span.traceId,
         spanId: span.spanId,
@@ -199,6 +206,8 @@ export {
   truncatePreview,
   setRequestUser,
   setRequestError,
+  setRequestEndpoint,
+  setRequestDimensions,
   sanitizePayload,
   runWithRequestContext,
   resolveTraceContext,

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

@@ -1 +1 @@
-{"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../../src/server/create.ts"],"names":[],"mappings":"AA8BA,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,CAkNxF;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,eAAe,uBAsBnD"}
+{"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../../src/server/create.ts"],"names":[],"mappings":"AA+BA,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,CAsNxF;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,eAAe,uBAsBnD"}

package/dist/server/index.js

@@ -12,7 +12,7 @@ import {
   socketIoLane,
   staticRoute,
   webSocketLane
-} from "../index-s8gtzt8w.js";
+} from "../index-renxz7c2.js";
 import {
   createAuthHook,
   createBearerResolver,
@@ -43,16 +43,14 @@ import {
   rateLimited,
   unauthorized
 } from "../index-jgpsd7dy.js";
-import {
-  getTraceId
-} from "../index-031q8xmx.js";
 import {
   extractIp,
   generateTraceId,
   getClientInfo,
+  getTraceId,
   resolveSocketIp,
   resolveTraceId
-} from "../index-p9m9c0jw.js";
+} from "../index-fwqnkc90.js";
 import {
   isRecord
 } from "../index-tm7dqzxc.js";

package/llms-full.txt

@@ -2256,11 +2256,13 @@ queryable across all three:
 |-------|-------|
 | `source` | `http` \| `mcp` \| `agent` |
 | `method` / `path` | the verb + path, or `TOOL` + `/{source}/{tool}` |
+| `serviceName` / `action` | stable contract identity of the operation (→ ADR 0022) — from the contract, not parsed from `path`; set on every surface, present even on a pre-handler 400 |
 | `toolName` | tool calls only |
+| `dimensions` | app-defined domain dimensions (tenant / project / entity id) — see [request context](#request-context) |
 | `traceId` / `spanId` / `parentSpanId` | [W3C trace context](#trace-context) |
 | `ok` / `statusCode` | outcome — real HTTP status, or `200`/`400` for a tool |
 | `durationMs` / `startedAt` | timing |
-| `errorCode` / `errorMessage` | failures only |
+| `errorCode` / `errorMessage` / `errorDetail` | failures only — `errorDetail` carries the structure the message flattens (e.g. Zod issues) |
 | `payload` | the request body / tool arguments — sanitised |
 | `resultSize` / `responseBytes` | result item count + serialised size |
 | `userId` / `ipAddress` / `userAgent` | identity |
@@ -2279,15 +2281,36 @@ Bun.serve({
 })
 ```
 
-Two fields are filled in late — the resolved user, and the error outcome. Set
-them from the hooks that know:
+Some fields are filled in late. Set them from the hooks that know:
 
 ```ts
-import { setRequestError, setRequestUser } from 'stitchkit/observability'
+import {
+  setRequestDimensions,
+  setRequestError,
+  setRequestUser,
+} from 'stitchkit/observability'
 
 createAuthHook({ /* … */ inject: (ctx, user) => user && setRequestUser(user.id) })
 // in your onError hook:
-setRequestError({ code: err.code, message: err.message })
+setRequestError({ code: err.code, message: err.message, details: err.issues })
+```
+
+**Endpoint identity is automatic.** The framework writes the matched operation's
+`(serviceName, action)` into the context at route-match, *before* validation — so
+`event.serviceName` / `event.action` are present on every event, including a
+pre-handler 400. Nothing to wire.
+
+**Domain dimensions** — attach your own tenant / project / entity id with
+`setRequestDimensions`. It is an opaque `Record<string, string>` the core gives no
+meaning to (→ ADR 0021). Resolve it cheaply from `ctx.params` / headers in
+`beforeHandle` (success) or `onError` (a pre-handler failure — `ctx.params` /
+`ctx.req` are available there) and it lands on `event.dimensions` for the request
+either way, so your sink reads it as a column instead of re-parsing the path:
+
+```ts
+// beforeHandle (success) and onError (failure) alike:
+const projectId = ctx.req?.headers.get('x-project') ?? String(ctx.params?.projectId ?? '')
+if (projectId) setRequestDimensions({ projectId })
 ```
 
 Make the framework router share this trace id — so request logs and your
@@ -2378,14 +2401,15 @@ outcome and the duration, neither of which exists before the handler runs.
 
 ### Keying a row on (service, action)
 
-For a per-endpoint audit row keyed by **service** and **action**, read the
-endpoint identity off the `MethodDef` the hook receives — `endpoint.serviceName`
-(the contract prefix) and `endpoint.key` (the endpoint key, e.g. `updatePartial`).
-They are stable and always present (→ ADR 0022); the action is not in the URL and
-`toolName` is absent on HTTP-only endpoints, so this is the only reliable pair.
-`afterHandle` also gives you the handler `result` — so it, not `createAuditHook`'s
-HTTP wrapper (which never sees the response body), is the home for a rich mutation
-audit that records output:
+`createAuditHook` already keys every event by **service** and **action**
+(`event.serviceName` / `event.action`, → ADR 0029) — reach for the raw hook only
+when you also need the handler **output**, which the audit wrapper never sees. For
+that, read the endpoint identity off the `MethodDef` the hook receives —
+`endpoint.serviceName` (the contract prefix) and `endpoint.key` (the endpoint key,
+e.g. `updatePartial`). They are stable and always present (→ ADR 0022); the action
+is not in the URL and `toolName` is absent on HTTP-only endpoints, so this is the
+only reliable pair. `afterHandle` also gives you the handler `result` — so it is
+the home for a rich mutation audit that records output:
 
 ```ts
 hooks: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.10.0",
+  "version": "0.11.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-031q8xmx.js

@@ -1,87 +0,0 @@
-import {
-  getClientInfo,
-  resolveSocketIp
-} from "./index-p9m9c0jw.js";
-
-// 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;
-function runWithRequestContext(ctx, fn) {
-  return storage.run(ctx, fn);
-}
-function getRequestContext() {
-  return storage.getStore();
-}
-function getTraceId() {
-  return storage.getStore()?.trace.traceId;
-}
-function getUserId() {
-  return storage.getStore()?.userId;
-}
-function setRequestUser(userId) {
-  const ctx = storage.getStore();
-  if (ctx)
-    ctx.userId = userId;
-}
-function setRequestError(error) {
-  const ctx = storage.getStore();
-  if (ctx)
-    ctx.error = error;
-}
-function wrapInRequestContext(handler, options = {}) {
-  return (req, server) => {
-    const ctx = {
-      trace: resolveTraceContext(req),
-      source: "http",
-      method: req.method,
-      path: new URL(req.url, "http://localhost").pathname,
-      startedAt: process.hrtime.bigint(),
-      ...getClientInfo(req, {
-        trustProxy: options.trustProxy,
-        socketIp: resolveSocketIp(req, server)
-      })
-    };
-    return runWithRequestContext(ctx, () => handler(req, server));
-  };
-}
-
-export { createTraceContext, parseTraceparent, formatTraceparent, resolveTraceContext, childSpan, runWithRequestContext, getRequestContext, getTraceId, getUserId, setRequestUser, setRequestError, wrapInRequestContext };

package/dist/index-p9m9c0jw.js

@@ -1,58 +0,0 @@
-import {
-  isRecord,
-  isUnsafeKey
-} from "./index-tm7dqzxc.js";
-
-// src/server/request.ts
-function generateTraceId() {
-  return `${Date.now().toString(36)}-${crypto.randomUUID().slice(0, 8)}`;
-}
-function resolveTraceId(req) {
-  const header = req.headers.get("x-request-id") ?? req.headers.get("x-trace-id");
-  const trimmed = header?.trim();
-  if (trimmed && trimmed.length <= 128 && /^[\w.-]+$/.test(trimmed)) {
-    return trimmed;
-  }
-  return generateTraceId();
-}
-function resolveSocketIp(req, server) {
-  if (typeof server === "object" && server !== null && "requestIP" in server && typeof server.requestIP === "function") {
-    const addr = server.requestIP(req);
-    if (isRecord(addr) && typeof addr.address === "string" && addr.address) {
-      return addr.address;
-    }
-  }
-  if ("ip" in req && typeof req.ip === "string" && req.ip)
-    return req.ip;
-  return;
-}
-function extractIp(req, options = {}) {
-  if (options.trustProxy) {
-    const forwarded = req.headers.get("x-forwarded-for");
-    if (forwarded)
-      return (forwarded.split(",")[0] ?? "").trim().replace(/^::ffff:/, "");
-    const realIp = req.headers.get("x-real-ip");
-    if (realIp)
-      return realIp.trim().replace(/^::ffff:/, "");
-  }
-  return (options.socketIp ?? "").replace(/^::ffff:/, "");
-}
-function getClientInfo(req, options = {}) {
-  return {
-    ipAddress: extractIp(req, options) || undefined,
-    userAgent: req.headers.get("user-agent") ?? undefined
-  };
-}
-function parseQueryParams(url) {
-  const query = {};
-  for (const key of new Set(url.searchParams.keys())) {
-    if (isUnsafeKey(key))
-      continue;
-    const values = url.searchParams.getAll(key);
-    const [first] = values;
-    query[key] = values.length === 1 && first !== undefined ? first : values;
-  }
-  return query;
-}
-
-export { generateTraceId, resolveTraceId, resolveSocketIp, extractIp, getClientInfo, parseQueryParams };