stitchkit 0.10.0 → 0.12.0

package/dist/cli.js

@@ -4,9 +4,9 @@ import {
   emitResult,
   parseCliArgs,
   pollUntilDone
-} from "./index-f39j6twc.js";
+} from "./index-eyc38rgc.js";
 import"./index-0ed3bx43.js";
-import"./index-jgpsd7dy.js";
+import"./index-fq89tdex.js";
 import"./index-tm7dqzxc.js";
 export {
   pollUntilDone,

package/dist/{index-f39j6twc.js → index-eyc38rgc.js}

@@ -7,7 +7,7 @@ import {
   isWithinDir,
   normalizeError,
   validateHandlerOutput
-} from "./index-jgpsd7dy.js";
+} from "./index-fq89tdex.js";
 import {
   isRecord,
   isUnsafeKey,

package/dist/{index-jgpsd7dy.js → index-fq89tdex.js}

@@ -76,6 +76,13 @@ function formatZodError(error) {
   return lines.join(`
 `) + suffix;
 }
+function errorCode(err) {
+  if (AppError.is(err))
+    return err.code;
+  if (err instanceof z2.ZodError)
+    return "VALIDATION_ERROR";
+  return;
+}
 function normalizeError(err) {
   if (AppError.is(err))
     return err;
@@ -102,4 +109,4 @@ function isWithinDir(root, target) {
   return target === root || target === base || target.startsWith(base + sep);
 }
 
-export { AppError, notFound, badRequest, unauthorized, forbidden, conflict, rateLimited, STITCH_ERROR_STATUS, isStitchErrorCode, appError, formatZodError, normalizeError, validateHandlerOutput, isWithinDir };
+export { AppError, notFound, badRequest, unauthorized, forbidden, conflict, rateLimited, STITCH_ERROR_STATUS, isStitchErrorCode, appError, formatZodError, errorCode, normalizeError, validateHandlerOutput, isWithinDir };

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-kb7wxdq0.js}

@@ -1,17 +1,19 @@
 import {
   AppError,
   badRequest,
+  errorCode,
   isWithinDir,
   normalizeError,
   validateHandlerOutput
-} from "./index-jgpsd7dy.js";
+} from "./index-fq89tdex.js";
 import {
   extractIp,
   getClientInfo,
   parseQueryParams,
   resolveSocketIp,
-  resolveTraceId
-} from "./index-p9m9c0jw.js";
+  resolveTraceId,
+  setRequestEndpoint
+} from "./index-fwqnkc90.js";
 import {
   __require,
   isUnsafeKey,
@@ -445,8 +447,8 @@ function levelForStatus(status) {
     return "warn";
   return "info";
 }
-function buildLogFields(method, path, status, durationMs, traceId, errorCode) {
-  return { traceId, method, path, status, durationMs, ...errorCode && { errorCode } };
+function buildLogFields(method, path, status, durationMs, traceId, errorCode2) {
+  return { traceId, method, path, status, durationMs, ...errorCode2 && { errorCode: errorCode2 } };
 }
 function formatMs(ms) {
   if (ms >= 1000)
@@ -490,20 +492,20 @@ function logIncoming(req, pathname, traceId, ipAddress) {
   }
   return log;
 }
-function logOutgoing(req, pathname, status, log, ipAddress, errorCode) {
+function logOutgoing(req, pathname, status, log, ipAddress, errorCode2) {
   const ms = elapsedMs(log.startTime);
   if (isProd) {
     console.log(JSON.stringify({
       ts: new Date().toISOString(),
       level: levelForStatus(status),
       msg: `${req.method} ${pathname} ${status}`,
-      ...buildLogFields(req.method, pathname, status, Math.round(ms), log.traceId, errorCode),
+      ...buildLogFields(req.method, pathname, status, Math.round(ms), log.traceId, errorCode2),
       ip: ipAddress
     }));
     return;
   }
   const mc = METHOD_COLOR[req.method] ?? c.dim;
-  const code = errorCode ? ` ${c.red}${errorCode}${c.reset}` : "";
+  const code = errorCode2 ? ` ${c.red}${errorCode2}${c.reset}` : "";
   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 ?? "")}`);
 }
 
@@ -533,15 +535,15 @@ function createHandler(config) {
       });
       reqLog = { traceId, startTime: performance.now() };
     }
-    const logDone = (status, errorCode) => {
+    const logDone = (status, errorCode2) => {
       if (!reqLog)
         return;
       if (useDefaultLog)
-        logOutgoing(req, url.pathname, status, reqLog, ipAddress, errorCode);
+        logOutgoing(req, url.pathname, status, reqLog, ipAddress, errorCode2);
       if (customLogger) {
         const durationMs = Math.round(elapsedMs(reqLog.startTime));
         const level = levelForStatus(status);
-        customLogger[level](`${req.method} ${url.pathname} ${status}${errorCode ? ` ${errorCode}` : ""} ${durationMs}ms`, buildLogFields(req.method, url.pathname, status, durationMs, reqLog.traceId, errorCode));
+        customLogger[level](`${req.method} ${url.pathname} ${status}${errorCode2 ? ` ${errorCode2}` : ""} ${durationMs}ms`, buildLogFields(req.method, url.pathname, status, durationMs, reqLog.traceId, errorCode2));
       }
     };
     const respondError = async (err, errCtx, endpoint) => {
@@ -550,7 +552,7 @@ function createHandler(config) {
           const response = await hooks.onError(errCtx ?? buildErrorContext(req, url, traceId, clientIp), err, endpoint);
           if (response instanceof Response) {
             const withCors = applyCors(response, cors, req);
-            logDone(withCors.status);
+            logDone(withCors.status, errorCode(err));
             return withCors;
           }
         } catch {}
@@ -600,6 +602,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/{index-9zrq8x5z.js → index-msmy8ydw.js}

@@ -1,7 +1,7 @@
 import {
   forbidden,
   unauthorized
-} from "./index-jgpsd7dy.js";
+} from "./index-fq89tdex.js";
 import {
   isRecord,
   isUnsafeKey,

package/dist/internal/errors.d.ts

@@ -1,6 +1,13 @@
 import { type ZodType, z } from 'zod';
 import { AppError } from '../contract';
 export declare function formatZodError(error: z.ZodError): string;
+/**
+ * The stable error code for a thrown value — `AppError.code`, `VALIDATION_ERROR`
+ * for a `ZodError`, else `undefined`. Side-effect-free (unlike `normalizeError`,
+ * it never logs): for access-log attribution on a path where the response is
+ * produced elsewhere — a custom `onError` hook that returns its own `Response`.
+ */
+export declare function errorCode(err: unknown): string | undefined;
 export declare function normalizeError(err: unknown): AppError;
 /**
  * Validate a handler's return value against the contract `output` schema. A

package/dist/internal/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/internal/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACtC,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC,wBAAgB,cAAc,CAAC,KAAK,EAAE,CAAC,CAAC,QAAQ,GAAG,MAAM,CASxD;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,QAAQ,CAYrD;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,OAAO,EACf,IAAI,EAAE,OAAO,GACZ;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAO9D"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/internal/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACtC,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC,wBAAgB,cAAc,CAAC,KAAK,EAAE,CAAC,CAAC,QAAQ,GAAG,MAAM,CASxD;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAI1D;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,QAAQ,CAYrD;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,OAAO,EACf,IAAI,EAAE,OAAO,GACZ;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAO9D"}

package/dist/node.js

@@ -3,7 +3,7 @@ import {
   createImplement,
   createSocketIOServer,
   implement
-} from "./index-s8gtzt8w.js";
+} from "./index-kb7wxdq0.js";
 import {
   AppError,
   appError,
@@ -13,8 +13,8 @@ import {
   notFound,
   rateLimited,
   unauthorized
-} from "./index-jgpsd7dy.js";
-import"./index-p9m9c0jw.js";
+} from "./index-fq89tdex.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,CA6G9D"}

package/dist/observability/context.d.ts

@@ -1,5 +1,4 @@
 import type { TransportSource } from '../contract';
-import type { JsonValue } from './sanitize';
 import { type TraceContext } from './trace';
 /** Everything known about the request in flight. */
 export interface RequestContext {
@@ -19,11 +18,26 @@ export interface RequestContext {
     userAgent?: string;
     /** Resolved user id — set late, once auth has run. */
     userId?: string;
-    /** Error outcome — set late, by the error handler. */
+    /**
+     * 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. `details` is sanitised into
+     *  `RequestEvent.errorDetail` at emit, so it is accepted loosely here. */
     error?: {
         code?: string;
         message?: string;
-        details?: JsonValue;
+        details?: unknown;
     };
 }
 /** Run `fn` with `ctx` as the active request context. */
@@ -40,16 +54,35 @@ 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
- * `details` carries structure the message string flattens (e.g. the failing
- * Zod issues) onto `RequestEvent.errorDetail`.
+ * `details` carries the structure the message string flattens (e.g. the failing
+ * Zod issues, or an `AppError.details`); it is accepted as `unknown` and
+ * **sanitised** into `RequestEvent.errorDetail` at emit — pass it raw, no need to
+ * pre-launder the type.
  */
 export declare function setRequestError(error: {
     code?: string;
     message?: string;
-    details?: JsonValue;
+    details?: unknown;
 }): void;
 /** Options for `wrapInRequestContext`. */
 export interface WrapRequestContextOptions {

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,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"}

package/dist/observability/event.d.ts

@@ -1,4 +1,4 @@
-import type { TransportSource } from '../contract';
+import type { HttpMethod, TransportSource } from '../contract';
 import type { JsonValue } from './sanitize';
 /**
  * A normalised audit event — one shape for a completed call on any surface
@@ -11,8 +11,29 @@ export interface RequestEvent {
     source: TransportSource;
     /** HTTP verb, or `TOOL` for a tool call. */
     method: string;
+    /**
+     * The operation's contract verb (`GET` / `POST` / …). Set on **tool** events
+     * (whose `method` is `TOOL`) so a single filter can tell a read from a write
+     * across HTTP and tool calls — `(event.httpMethod ?? event.method) !== 'GET'`.
+     * Omitted on HTTP events, where `method` already is the verb. → ADR 0030.
+     */
+    httpMethod?: HttpMethod;
     /** 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. */
@@ -32,9 +53,10 @@ export interface RequestEvent {
     /** Error message — failures only. */
     errorMessage?: string;
     /**
-     * Structured error detail — failures only, when the error handler recorded it
-     * via `setRequestError({ details })` (e.g. the failing validation issues the
-     * `errorMessage` string flattens). HTTP path only.
+     * Structured error detail — failures only. On HTTP, what the error handler
+     * recorded via `setRequestError({ details })` (e.g. the failing validation
+     * issues the `errorMessage` string flattens); on a tool call, the failed
+     * `ToolResult.details` (sanitised).
      */
     errorDetail?: JsonValue;
     /** Sanitised request payload — the HTTP body or the tool arguments. */

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,UAAU,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC/D,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;;;;;OAKG;IACH,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,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;;;;;OAKG;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,
@@ -148,7 +152,9 @@ function createAuditHook(config) {
             durationMs,
             errorCode: ctx.error?.code,
             errorMessage: ctx.error?.message,
-            ...ctx.error?.details !== undefined && { errorDetail: ctx.error.details },
+            ...ctx.error?.details !== undefined && {
+              errorDetail: sanitizePayload(ctx.error.details, sanitize)
+            },
             payload: sanitizePayload(body, sanitize),
             resultSize: null,
             responseBytes: 0,
@@ -163,14 +169,18 @@ 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",
+        httpMethod: endpoint.method,
         path: `/${context.source}/${toolName}`,
+        serviceName: endpoint.serviceName,
+        action: endpoint.key,
+        ...requestCtx?.dimensions !== undefined && { dimensions: requestCtx.dimensions },
         toolName,
         traceId: span.traceId,
         spanId: span.spanId,
@@ -180,6 +190,9 @@ function createAuditHook(config) {
         durationMs,
         errorCode: result.ok ? undefined : result.code,
         errorMessage: result.ok ? undefined : toolErrorMessage(result),
+        ...!result.ok && result.details !== undefined && {
+          errorDetail: sanitizePayload(result.details, sanitize)
+        },
         payload: sanitizePayload(args, sanitize),
         resultSize: measure.resultSize,
         responseBytes: measure.responseBytes,
@@ -199,6 +212,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,CAyNxF;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-kb7wxdq0.js";
 import {
   createAuthHook,
   createBearerResolver,
@@ -25,7 +25,7 @@ import {
   signJwt,
   verifyJwt,
   verifyPkce
-} from "../index-9zrq8x5z.js";
+} from "../index-msmy8ydw.js";
 import {
   jsonSchemaFields,
   toJsonSchema
@@ -42,17 +42,15 @@ import {
   notFound,
   rateLimited,
   unauthorized
-} from "../index-jgpsd7dy.js";
-import {
-  getTraceId
-} from "../index-031q8xmx.js";
+} from "../index-fq89tdex.js";
 import {
   extractIp,
   generateTraceId,
   getClientInfo,
+  getTraceId,
   resolveSocketIp,
   resolveTraceId
-} from "../index-p9m9c0jw.js";
+} from "../index-fwqnkc90.js";
 import {
   isRecord
 } from "../index-tm7dqzxc.js";

package/dist/tools.js

@@ -2,7 +2,7 @@ import {
   inputIsQuery,
   signJwt,
   verifyPkce
-} from "./index-9zrq8x5z.js";
+} from "./index-msmy8ydw.js";
 import {
   coerceJsonArgs,
   collectTools,
@@ -14,14 +14,14 @@ import {
   pollUntil,
   readCapped,
   toolResultFromError
-} from "./index-f39j6twc.js";
+} from "./index-eyc38rgc.js";
 import {
   toJsonSchema
 } from "./index-0ed3bx43.js";
 import {
   AppError,
   isWithinDir
-} from "./index-jgpsd7dy.js";
+} from "./index-fq89tdex.js";
 import {
   isRecord,
   typedEntries

package/llms-full.txt

@@ -2256,11 +2256,14 @@ 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 |
+| `httpMethod` | the contract verb on **tool** events (their `method` is `TOOL`) — filter reads vs writes across both surfaces with `(event.httpMethod ?? event.method) !== 'GET'` |
+| `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 +2282,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 +2402,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.12.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 };