stitchkit 0.9.0 → 0.11.0

package/dist/cli.js

@@ -4,7 +4,7 @@ import {
   emitResult,
   parseCliArgs,
   pollUntilDone
-} from "./index-13psnhhe.js";
+} from "./index-f39j6twc.js";
 import"./index-0ed3bx43.js";
 import"./index-jgpsd7dy.js";
 import"./index-tm7dqzxc.js";

package/dist/contract/define.d.ts

@@ -5,9 +5,9 @@ export type Transport = (typeof ALL_TRANSPORTS)[number];
 /**
  * The transport tag on `ctx.source`. The four built-ins keep autocomplete, but
  * the union is **open** (`string & {}`) so a bring-your-own transport — e.g. a
- * raw-WebSocket lane driving a contract through `createContractDispatcher` — can
- * tag its own calls (`source: 'local-ws'`). `source` is transport-only and
- * carries no framework behaviour (→ ADR 0002 / ADR 0027).
+ * raw-WebSocket lane that runs a contract through the app's own dispatch loop —
+ * can tag its own calls (`source: 'local-ws'`). `source` is transport-only and
+ * carries no framework behaviour (→ ADR 0002).
  */
 export type TransportSource = 'http' | 'mcp' | 'agent' | 'cli' | (string & {});
 interface EndpointDefBase {
@@ -40,10 +40,10 @@ interface EndpointDefBase {
      * The core attaches **no** behaviour to it (it stays generic — ADR 0002): it
      * rides through to `MethodDef.idempotent`, where a transport that can retry
      * reads it. A reliable bring-your-own-transport lane (e.g. a raw-WebSocket
-     * client over `createContractDispatcher`) replays an `idempotent` call after a
-     * reconnect — that is the durability guarantee — while a non-idempotent one is
-     * rejected rather than re-sent (a duplicate would be a second side effect).
-     * Unset means "unknown" — a careful transport treats it as non-idempotent.
+     * client) replays an `idempotent` call after a reconnect — that is the
+     * durability guarantee — while a non-idempotent one is rejected rather than
+     * re-sent (a duplicate would be a second side effect). Unset means "unknown" —
+     * a careful transport treats it as non-idempotent.
      */
     idempotent?: boolean;
     /**
@@ -129,6 +129,17 @@ export interface RuntimeContext {
     input: unknown;
     file?: File;
     source: TransportSource;
+    /**
+     * The raw Web `Request`, its parsed `URL` and `Headers` — set on the HTTP
+     * transport (and reachable in every lifecycle hook, including `onError` on a
+     * validation failure). Absent on the non-HTTP transports (MCP / agent / CLI /
+     * a bring-your-own lane), which carry no `Request`, so they are optional and a
+     * reader narrows them. Web Fetch types only — the core stays Fetch-clean
+     * (→ ADR 0013).
+     */
+    req?: Request;
+    url?: URL;
+    headers?: Headers;
     traceId?: string;
     spanId?: string;
     ipAddress?: string;
@@ -140,6 +151,11 @@ export interface HandlerContext<TParams = undefined, TInput = undefined> {
     input: TInput;
     file?: File;
     source: TransportSource;
+    /** Raw Web `Request` / `URL` / `Headers` — set on the HTTP transport, absent
+     *  on the tool transports (see {@link RuntimeContext}). */
+    req?: Request;
+    url?: URL;
+    headers?: Headers;
     traceId?: string;
     spanId?: string;
     ipAddress?: string;

package/dist/contract/define.d.ts.map

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

package/dist/{index-13psnhhe.js → index-f39j6twc.js}

@@ -1000,4 +1000,4 @@ function safeInputSchema(tool) {
   }
 }
 
-export { coerceJsonArgs, toolResultFromError, executeToolMethod, flattenDiscriminatedUnion, collectTools, createToolRunner, formatToolError, fetchGuarded, readCapped, parseCliArgs, DEFAULT_EXIT_CODES, emitResult, pollUntil, pollUntilDone, createCli };
+export { coerceJsonArgs, toolResultFromError, flattenDiscriminatedUnion, collectTools, createToolRunner, formatToolError, fetchGuarded, readCapped, parseCliArgs, DEFAULT_EXIT_CODES, emitResult, pollUntil, pollUntilDone, createCli };

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-zshrc6kx.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,
@@ -343,38 +344,15 @@ async function readJsonBody(req) {
     badRequest("Invalid JSON body");
   }
 }
-async function buildContext(req, url, method, pathParams, traceId, clientIp, maxUploadBytes) {
-  const parsedParams = method.paramsSchema ? method.paramsSchema.parse(pathParams) : undefined;
-  let parsedInput;
-  let file;
-  if (method.multipart) {
-    const cap = method.maxUploadBytes ?? maxUploadBytes;
-    const multipart = await parseMultipart(req, method.multipart, method.inputSchema, cap);
-    parsedInput = multipart.fields;
-    file = multipart.file;
-  } else if (method.inputSchema) {
-    if (req.method === "GET") {
-      parsedInput = method.inputSchema.parse(parseQueryParams(url));
-    } else if (req.method === "DELETE") {
-      const ct = req.headers.get("content-type");
-      if (ct?.includes("application/json")) {
-        parsedInput = method.inputSchema.parse(await readJsonBody(req));
-      } else {
-        parsedInput = method.inputSchema.parse(parseQueryParams(url));
-      }
-    } else {
-      parsedInput = method.inputSchema.parse(await readJsonBody(req));
-    }
-  }
+function buildBaseContext(req, url, pathParams, traceId, clientIp) {
   const safePathParams = {};
   for (const [k, v] of Object.entries(pathParams)) {
     if (!RESERVED_KEYS.has(k) && !isUnsafeKey(k))
       safePathParams[k] = v;
   }
   return {
-    params: parsedParams,
-    input: parsedInput,
-    ...file && { file },
+    params: pathParams,
+    input: undefined,
     source: "http",
     req,
     url,
@@ -384,6 +362,27 @@ async function buildContext(req, url, method, pathParams, traceId, clientIp, max
     ...getClientInfo(req, clientIp)
   };
 }
+async function parseRequestInto(ctx, req, url, method, maxUploadBytes) {
+  if (method.paramsSchema) {
+    ctx.params = method.paramsSchema.parse(ctx.params);
+  }
+  if (method.multipart) {
+    const cap = method.maxUploadBytes ?? maxUploadBytes;
+    const multipart = await parseMultipart(req, method.multipart, method.inputSchema, cap);
+    ctx.input = multipart.fields;
+    if (multipart.file)
+      ctx.file = multipart.file;
+  } else if (method.inputSchema) {
+    if (req.method === "GET") {
+      ctx.input = method.inputSchema.parse(parseQueryParams(url));
+    } else if (req.method === "DELETE") {
+      const ct = req.headers.get("content-type");
+      ctx.input = ct?.includes("application/json") ? method.inputSchema.parse(await readJsonBody(req)) : method.inputSchema.parse(parseQueryParams(url));
+    } else {
+      ctx.input = method.inputSchema.parse(await readJsonBody(req));
+    }
+  }
+}
 function buildErrorContext(req, url, traceId, clientIp) {
   return {
     params: undefined,
@@ -447,8 +446,8 @@ function levelForStatus(status) {
     return "warn";
   return "info";
 }
-function buildLogFields(method, path, status, durationMs, traceId) {
-  return { traceId, method, path, status, durationMs };
+function buildLogFields(method, path, status, durationMs, traceId, errorCode) {
+  return { traceId, method, path, status, durationMs, ...errorCode && { errorCode } };
 }
 function formatMs(ms) {
   if (ms >= 1000)
@@ -492,20 +491,21 @@ function logIncoming(req, pathname, traceId, ipAddress) {
   }
   return log;
 }
-function logOutgoing(req, pathname, status, log, ipAddress) {
+function logOutgoing(req, pathname, status, log, ipAddress, errorCode) {
   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),
+      ...buildLogFields(req.method, pathname, status, Math.round(ms), log.traceId, errorCode),
       ip: ipAddress
     }));
     return;
   }
   const mc = METHOD_COLOR[req.method] ?? c.dim;
-  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} ${durationColor(ms)}${formatMs(ms)}${c.reset} ${ipLabel(ipAddress ?? "")}`);
+  const code = errorCode ? ` ${c.red}${errorCode}${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 ?? "")}`);
 }
 
 // src/server/create.ts
@@ -534,15 +534,15 @@ function createHandler(config) {
       });
       reqLog = { traceId, startTime: performance.now() };
     }
-    const logDone = (status) => {
+    const logDone = (status, errorCode) => {
       if (!reqLog)
         return;
       if (useDefaultLog)
-        logOutgoing(req, url.pathname, status, reqLog, ipAddress);
+        logOutgoing(req, url.pathname, status, reqLog, ipAddress, errorCode);
       if (customLogger) {
         const durationMs = Math.round(elapsedMs(reqLog.startTime));
         const level = levelForStatus(status);
-        customLogger[level](`${req.method} ${url.pathname} ${status} ${durationMs}ms`, buildLogFields(req.method, url.pathname, status, durationMs, reqLog.traceId));
+        customLogger[level](`${req.method} ${url.pathname} ${status}${errorCode ? ` ${errorCode}` : ""} ${durationMs}ms`, buildLogFields(req.method, url.pathname, status, durationMs, reqLog.traceId, errorCode));
       }
     };
     const respondError = async (err, errCtx, endpoint) => {
@@ -557,7 +557,7 @@ function createHandler(config) {
         } catch {}
       }
       const appErr = normalizeError(err);
-      logDone(appErr.status);
+      logDone(appErr.status, appErr.code);
       return json(appErr.toJSON(), appErr.status, cors, req);
     };
     if (cors && req.method === "OPTIONS") {
@@ -600,9 +600,10 @@ function createHandler(config) {
       return respondError(new AppError("NOT_FOUND", "Not found", 404));
     }
     const { method, pathParams, groupHooks } = match;
-    let ctx;
+    const ctx = buildBaseContext(req, url, pathParams, traceId, clientIp);
+    setRequestEndpoint(method.serviceName, method.key);
     try {
-      ctx = await buildContext(req, url, method, pathParams, traceId, clientIp, config.maxUploadBytes);
+      await parseRequestInto(ctx, req, url, method, config.maxUploadBytes);
       if (hooks?.beforeHandle) {
         await hooks.beforeHandle(ctx, method);
       }

package/dist/node.js

@@ -3,7 +3,7 @@ import {
   createImplement,
   createSocketIOServer,
   implement
-} from "./index-zshrc6kx.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,CA+F9D"}
+{"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

@@ -1,4 +1,5 @@
 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 {
@@ -18,10 +19,25 @@ 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;
         message?: string;
+        details?: JsonValue;
     };
 }
 /** Run `fn` with `ctx` as the active request context. */
@@ -38,13 +54,33 @@ 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.
+ * 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`.
  */
 export declare function setRequestError(error: {
     code?: string;
     message?: string;
+    details?: JsonValue;
 }): 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,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,CAAA;KAAE,CAAC;CAC7C;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;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAGhF;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. */
@@ -31,6 +45,12 @@ export interface RequestEvent {
     errorCode?: string;
     /** 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.
+     */
+    errorDetail?: JsonValue;
     /** Sanitised request payload — the HTTP body or the tool arguments. */
     payload: JsonValue | null;
     /** Item count of the result, when it is a list. */

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,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,
@@ -148,6 +152,7 @@ function createAuditHook(config) {
             durationMs,
             errorCode: ctx.error?.code,
             errorMessage: ctx.error?.message,
+            ...ctx.error?.details !== undefined && { errorDetail: ctx.error.details },
             payload: sanitizePayload(body, sanitize),
             resultSize: null,
             responseBytes: 0,
@@ -162,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,
@@ -198,6 +206,8 @@ export {
   truncatePreview,
   setRequestUser,
   setRequestError,
+  setRequestEndpoint,
+  setRequestDimensions,
   sanitizePayload,
   runWithRequestContext,
   resolveTraceContext,

package/dist/retained.d.ts

@@ -9,7 +9,7 @@
  *
  * Transport-agnostic: wrap it around any pub/sub. `createSocketIOClient`'s
  * `retain` option uses it internally, and a bring-your-own-transport lane (a raw
- * WebSocket driving a contract through `createContractDispatcher`) can use it
+ * WebSocket driving a contract through the app's own dispatch loop) can use it
  * directly for its own event channel. Browser-safe — no Node built-ins.
  */
 export interface RetainedTopics<Events extends Record<string, unknown>> {

package/dist/server/context.d.ts

@@ -5,6 +5,23 @@
 import { type RuntimeContext } from '../contract';
 import { type ClientIpOptions } from './request';
 import type { MethodDef } from './types';
-export declare function buildContext(req: Request, url: URL, method: MethodDef, pathParams: Record<string, string>, traceId: string, clientIp: ClientIpOptions, maxUploadBytes?: number): Promise<RuntimeContext>;
+/**
+ * Assemble everything knowable from the URL alone — path params, the request,
+ * trace id and client info — **before** any schema parsing. Bound first so a
+ * later validation failure still hands `onError` the path params and the
+ * request (an empty context loses both); `parseRequestInto` then enriches it
+ * with the schema-validated `params` / `input`.
+ *
+ * `params` starts as the raw matched path params (a property of the URL, known
+ * the moment the route matched) and is replaced by the validated value when the
+ * endpoint declares a `paramsSchema`.
+ */
+export declare function buildBaseContext(req: Request, url: URL, pathParams: Record<string, string>, traceId: string, clientIp: ClientIpOptions): RuntimeContext;
+/**
+ * Parse `params` / `input` against the endpoint schemas and write them onto an
+ * already-assembled base context. A validation failure throws a `ZodError`
+ * here — the base context (path params, request) is preserved for `onError`.
+ */
+export declare function parseRequestInto(ctx: RuntimeContext, req: Request, url: URL, method: MethodDef, maxUploadBytes?: number): Promise<void>;
 export declare function buildErrorContext(req: Request, url: URL, traceId: string, clientIp: ClientIpOptions): RuntimeContext;
 //# sourceMappingURL=context.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/server/context.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAc,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAG9D,OAAO,EAAE,KAAK,eAAe,EAAmC,MAAM,WAAW,CAAC;AAClF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAmCzC,wBAAsB,YAAY,CAChC,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,GAAG,EACR,MAAM,EAAE,SAAS,EACjB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAClC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,eAAe,EACzB,cAAc,CAAC,EAAE,MAAM,GACtB,OAAO,CAAC,cAAc,CAAC,CA8CzB;AAED,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,GAAG,EACR,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,eAAe,GACxB,cAAc,CAWhB"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/server/context.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAc,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAG9D,OAAO,EAAE,KAAK,eAAe,EAAmC,MAAM,WAAW,CAAC;AAClF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAmCzC;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,GAAG,EACR,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAClC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,eAAe,GACxB,cAAc,CAmBhB;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,cAAc,EACnB,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,GAAG,EACR,MAAM,EAAE,SAAS,EACjB,cAAc,CAAC,EAAE,MAAM,GACtB,OAAO,CAAC,IAAI,CAAC,CAwBf;AAED,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,GAAG,EACR,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,eAAe,GACxB,cAAc,CAWhB"}

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,CAgNxF;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-zshrc6kx.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/dist/server/logger.d.ts

@@ -3,12 +3,13 @@ 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. */
-export declare function buildLogFields(method: string, path: string, status: number, durationMs: number, traceId: string): {
+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;
 };
 export interface RequestLog {
     traceId: string;
@@ -18,5 +19,5 @@ 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): void;
+export declare function logOutgoing(req: Request, pathname: string, status: number, log: RequestLog, ipAddress?: string, errorCode?: string): 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,GACd;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAEvF;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,GACjB,IAAI,CAoBN"}
+{"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"}

package/dist/tools.d.ts

@@ -4,7 +4,6 @@ export { type CliConfig, createCli } from './tools/cli';
 export type { ExitCodeMap } from './tools/cli-format';
 export type { CliWaitConfig } from './tools/cli-wait';
 export { coerceJsonArgs } from './tools/coerce';
-export { type ContractDispatcher, type ContractDispatcherConfig, createContractDispatcher, } from './tools/dispatch';
 export type { ToolCallHooks, ToolLifecycle, ToolResult } from './tools/execute';
 export { flattenDiscriminatedUnion } from './tools/flatten';
 export { buildToolManifest, type ToolManifestEntry } from './tools/manifest';

package/dist/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,gBAAgB,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AACrF,OAAO,EAAE,KAAK,SAAS,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxD,YAAY,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,YAAY,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,wBAAwB,EAC7B,wBAAwB,GACzB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAChF,OAAO,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAE,KAAK,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAC7E,OAAO,EACL,cAAc,EACd,KAAK,wBAAwB,EAC7B,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,QAAQ,EACR,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,2BAA2B,EAC3B,kBAAkB,EAClB,KAAK,SAAS,EACd,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,kBAAkB,GACnB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,gBAAgB,EAAE,KAAK,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC9E,OAAO,EAAE,oBAAoB,EAAE,KAAK,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACpF,OAAO,EAAE,YAAY,EAAE,KAAK,aAAa,EAAE,KAAK,UAAU,EAAE,MAAM,eAAe,CAAC;AAClF,OAAO,EAAE,KAAK,kBAAkB,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAChF,OAAO,EAAE,WAAW,EAAE,KAAK,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC1E,OAAO,EAAE,SAAS,EAAE,KAAK,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpE,OAAO,EACL,2BAA2B,EAC3B,uBAAuB,EACvB,KAAK,uBAAuB,EAC5B,4BAA4B,EAC5B,qBAAqB,GACtB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,kBAAkB,EAClB,KAAK,mBAAmB,EACxB,KAAK,WAAW,EAChB,KAAK,gBAAgB,GACtB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,KAAK,sBAAsB,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAC9E,OAAO,EAAE,aAAa,EAAE,KAAK,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAC9D,OAAO,EAAE,KAAK,eAAe,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,gBAAgB,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AACrF,OAAO,EAAE,KAAK,SAAS,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxD,YAAY,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,YAAY,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAChF,OAAO,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAE,KAAK,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAC7E,OAAO,EACL,cAAc,EACd,KAAK,wBAAwB,EAC7B,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,QAAQ,EACR,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,2BAA2B,EAC3B,kBAAkB,EAClB,KAAK,SAAS,EACd,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,kBAAkB,GACnB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,gBAAgB,EAAE,KAAK,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC9E,OAAO,EAAE,oBAAoB,EAAE,KAAK,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACpF,OAAO,EAAE,YAAY,EAAE,KAAK,aAAa,EAAE,KAAK,UAAU,EAAE,MAAM,eAAe,CAAC;AAClF,OAAO,EAAE,KAAK,kBAAkB,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAChF,OAAO,EAAE,WAAW,EAAE,KAAK,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC1E,OAAO,EAAE,SAAS,EAAE,KAAK,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpE,OAAO,EACL,2BAA2B,EAC3B,uBAAuB,EACvB,KAAK,uBAAuB,EAC5B,4BAA4B,EAC5B,qBAAqB,GACtB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,kBAAkB,EAClB,KAAK,mBAAmB,EACxB,KAAK,WAAW,EAChB,KAAK,gBAAgB,GACtB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,KAAK,sBAAsB,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAC9E,OAAO,EAAE,aAAa,EAAE,KAAK,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAC9D,OAAO,EAAE,KAAK,eAAe,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/tools.js

@@ -8,14 +8,13 @@ import {
   collectTools,
   createCli,
   createToolRunner,
-  executeToolMethod,
   fetchGuarded,
   flattenDiscriminatedUnion,
   formatToolError,
   pollUntil,
   readCapped,
   toolResultFromError
-} from "./index-13psnhhe.js";
+} from "./index-f39j6twc.js";
 import {
   toJsonSchema
 } from "./index-0ed3bx43.js";
@@ -69,30 +68,6 @@ function mountAgent(services, config = {}) {
   }
   return tools;
 }
-// src/tools/dispatch.ts
-function createContractDispatcher(services, config) {
-  const list = Array.isArray(services) ? services : [services];
-  const index = new Map;
-  for (const service of list) {
-    for (const [name, method] of Object.entries(service.methods)) {
-      if (index.has(name)) {
-        throw new Error(`createContractDispatcher: duplicate method "${name}" across services`);
-      }
-      index.set(name, method);
-    }
-  }
-  return {
-    methods: [...index.keys()],
-    dispatch(method, args, context) {
-      const target = index.get(method);
-      if (!target) {
-        return Promise.resolve(toolResultFromError(new AppError("NOT_FOUND", `Unknown method: ${method}`, 404)));
-      }
-      const ctx = { ...config.context, ...context, source: config.source };
-      return executeToolMethod(target, method, args, ctx, config.hooks, config.lifecycle, config.coerceJsonArgs ?? false);
-    }
-  };
-}
 // src/tools/manifest.ts
 function buildToolManifest(tools) {
   return tools.map((t) => {
@@ -1311,7 +1286,6 @@ export {
   createToolkit,
   createStdioMcpServer,
   createMcpHandler,
-  createContractDispatcher,
   createCli,
   collectTools,
   coerceJsonArgs,

package/llms-full.txt

@@ -1876,37 +1876,20 @@ Notes:
 
 Sometimes the transport is neither HTTP nor Socket.IO — a desktop app whose UI
 webview talks to its own local Bun sidecar over a raw WebSocket, an IPC channel,
-a queue worker. You still want one contract: a `defineContract` with typed
-client/server, Zod validation and a typed error envelope, not a hand-rolled
-method registry alongside it.
+a queue worker. You can still drive it from one `defineContract`: share the
+contract's Zod schemas to validate each inbound frame, run your handlers, and
+reuse the contract metadata below. You own **both** the wire (framing,
+handshake, reconnect) *and* the per-call validate-run loop — stitchkit ships the
+contract and its metadata, not a transport engine. A reliable-RPC-over-raw-
+WebSocket engine would be a competing WebSocket transport
+([ADR 0008](../decisions/0008-thin-wrappers.md)); the wire stays yours.
 
-stitchkit ships the **executor**, not the transport. `createContractDispatcher`
-runs a contract method by its key through the *same* core as the MCP / agent
-mounts — same validation, the same `{ ok, data } | { ok: false, code, … }`
-envelope, the same hooks and `beforeHandle` scope gate. You own the wire (framing,
-handshake, reconnect) and call `dispatch` per inbound frame.
+Two pieces of the contract carry straight over to a bring-your-own lane:
 
-```ts
-import { createContractDispatcher } from 'stitchkit/tools'
-import { implement } from 'stitchkit/server'
-
-const service = implement(runtimeContract, { 'tasks.setDone': (ctx) => doIt(ctx.input), … })
-
-const dispatcher = createContractDispatcher(service, { source: 'local-ws' })
-
-// In your raw-WebSocket server, per `{ id, method, params }` frame:
-ws.onmessage = async (frame) => {
-  const { id, method, params } = JSON.parse(frame.data)
-  const result = await dispatcher.dispatch(method, params)   // validates + runs
-  ws.send(JSON.stringify({ id, ...result }))                 // { ok, data } | { ok:false, code, … }
-}
-```
-
-`dispatch` never throws for a normal call — a handler error becomes a failed
-result, and an unknown method is a `NOT_FOUND` result. Pass `hooks`
-(`beforeToolCall` / `afterToolCall`) and `lifecycle.beforeHandle` to audit and
-scope-guard exactly like the other transports. Tag calls with your own
-`source` — `TransportSource` is an open union.
+- **`source` is an open tag.** `TransportSource` is `'http' | 'mcp' | 'agent' |
+  'cli' | (string & {})`, so a handler or hook can tell your transport's calls
+  apart — tag them `source: 'local-ws'` and read `ctx.source`.
+- **`idempotent` drives replay-on-reconnect** — see below.
 
 ### Durability — `idempotent` + replay
 
@@ -1932,8 +1915,9 @@ also catches up on the latest pushed state.
 
 This is deliberately *not* a reliable-RPC engine — that would be a competing
 WebSocket transport ([ADR 0008](../decisions/0008-thin-wrappers.md)). stitchkit
-gives you the executor and the metadata; the wire stays yours. See
-[ADR 0027](../decisions/0027-transport-neutral-contract-execution.md).
+gives you the contract and the metadata (`idempotent`, the open `source` tag,
+`createRetainedTopics`); the wire and the per-call execution stay yours. See
+[ADR 0028](../decisions/0028-revert-contract-dispatcher.md).
 
 
 ==============================================================================
@@ -2272,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 |
@@ -2295,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
@@ -2394,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: {
@@ -3058,7 +3066,6 @@ Server-only. Turns contracts into MCP and AI-agent tools. Needs the
 | `mountMcp` | function | add contract tools to an existing `McpServer` — [guide](../guide/mcp-and-agents.md#mountmcp) |
 | `implementRemote` | function | bind a contract to a remote HTTP API — [guide](../guide/mcp-and-agents.md#proxying-a-remote-api--implementremote) |
 | `mountAgent` | function | a Vercel AI SDK `ToolSet` from a service — [guide](../guide/mcp-and-agents.md#ai-agents--mountagent) |
-| `createContractDispatcher` | function | run a contract over a bring-your-own transport — [guide](../guide/realtime.md#bring-your-own-transport) |
 | `createCli` | function | a command-line program from contracts — [guide](../guide/cli.md) (also on `stitchkit/cli`) |
 | `createToolkit` | function | context-typed tool mounts — [guide](../guide/cli.md#typed-context) |
 | `mountViewFile` | function | a native multimodal "view file" MCP tool |
@@ -3070,8 +3077,6 @@ Server-only. Turns contracts into MCP and AI-agent tools. Needs the
 | `ImplementRemoteOptions` | _type_ | options for `implementRemote` |
 | `McpMountConfig` | _type_ | config for `mountMcp` |
 | `AgentMountConfig` | _type_ | config for `mountAgent` |
-| `ContractDispatcher` | _type_ | the `createContractDispatcher` handle |
-| `ContractDispatcherConfig` | _type_ | config for `createContractDispatcher` |
 | `AgentContext` | _type_ | the context merged into agent tool handlers |
 | `CliConfig` | _type_ | config for `createCli` |
 | `CliWaitConfig` | _type_ | `--wait` polling config |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.9.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",
@@ -155,8 +155,8 @@
     "@tanstack/react-query": "5.101.0",
     "@types/bun": "^1.3.14",
     "@types/json-schema": "^7.0.15",
-    "@types/react": "^19.2.16",
-    "ai": "^6.0.196",
+    "@types/react": "^19.2.17",
+    "ai": "^6.0.207",
     "react": "^19.2.7",
     "react-query-kit": "^3.3.4",
     "socket.io": "^4.8.3",

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 };

package/dist/tools/dispatch.d.ts

@@ -1,65 +0,0 @@
-/**
- * Drive a contract over a **bring-your-own transport**.
- *
- * The HTTP server, the MCP mount and the agent mount all run a contract method
- * the same way: slice the flat args, validate `params` / `input` against the Zod
- * schemas, run the handler, validate the output, and return a typed result
- * envelope. `createContractDispatcher` exposes exactly that core for a transport
- * stitchkit does not own — a raw WebSocket lane (webview ↔ a local sidecar), an
- * IPC channel, a queue worker. The transport owns the wire (framing, handshake,
- * reconnect); the dispatcher owns "given a method name and args, run it safely."
- *
- * This is the same execution path as `mountMcp` / `mountAgent` (it shares
- * `executeToolMethod`), so a bespoke transport gets identical validation and the
- * identical `{ ok, code, details, hint }` error envelope for free, instead of a
- * hand-rolled method registry. → ADR 0027. Upholds ADR 0008 (no competing
- * engine — the transport is the app's) and ADR 0002 (the core stays generic —
- * `source` is a free tag, `idempotent` carries no built-in behaviour).
- */
-import { type TransportSource } from '../contract';
-import type { ServiceDef } from '../server/types';
-import { type ToolCallHooks, type ToolLifecycle, type ToolResult } from './execute';
-export interface ContractDispatcherConfig {
-    /** Transport tag written to every call's `ctx.source` — e.g. `'local-ws'`. */
-    source: TransportSource;
-    /** Static context merged into every call (overridden by per-call context). */
-    context?: Record<string, unknown>;
-    /**
-     * Observability hooks — the same `beforeToolCall` / `afterToolCall` the MCP and
-     * agent mounts fire, so a bespoke transport audits calls the same way.
-     */
-    hooks?: ToolCallHooks;
-    /**
-     * Auth / scope gate and result transform run for every call — pass a
-     * `createAuthHook` result as `beforeHandle` to scope-guard the transport like
-     * an HTTP route.
-     */
-    lifecycle?: ToolLifecycle;
-    /**
-     * Coerce JSON-stringified array / object arguments before validation. Off by
-     * default — a structured transport (WebSocket JSON) sends real types; only an
-     * LLM-style flat-string transport needs it.
-     */
-    coerceJsonArgs?: boolean;
-}
-export interface ContractDispatcher {
-    /**
-     * Run one contract method by its endpoint key (e.g. `'transcriptions.list'`)
-     * with a flat argument object. Returns the `{ ok: true, data } | { ok: false,
-     * code, details?, hint? }` envelope the MCP / agent transports use — it does
-     * not throw for a normal call; a handler error becomes a failed result, and an
-     * unknown method is a `NOT_FOUND` result. Per-call `context` is merged after
-     * the static `config.context` (neither can shadow `source`).
-     */
-    dispatch(method: string, args: Record<string, unknown>, context?: Record<string, unknown>): Promise<ToolResult>;
-    /** Every method key this dispatcher can run, across the given services. */
-    readonly methods: readonly string[];
-}
-/**
- * Build a {@link ContractDispatcher} from one or more `implement()` services.
- * Every method of every service is dispatchable by its key — exposure is the
- * transport's choice (which services it dispatches), not the contract's `expose`
- * (that gates the built-in HTTP / MCP / agent / CLI transports).
- */
-export declare function createContractDispatcher(services: ServiceDef | ServiceDef[], config: ContractDispatcherConfig): ContractDispatcher;
-//# sourceMappingURL=dispatch.d.ts.map

package/dist/tools/dispatch.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../../src/tools/dispatch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAY,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,KAAK,EAAa,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7D,OAAO,EAGL,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,UAAU,EAEhB,MAAM,WAAW,CAAC;AAEnB,MAAM,WAAW,wBAAwB;IACvC,8EAA8E;IAC9E,MAAM,EAAE,eAAe,CAAC;IACxB,8EAA8E;IAC9E,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC;;;OAGG;IACH,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB;;;;OAIG;IACH,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,kBAAkB;IACjC;;;;;;;OAOG;IACH,QAAQ,CACN,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,OAAO,CAAC,UAAU,CAAC,CAAC;IACvB,2EAA2E;IAC3E,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,UAAU,GAAG,UAAU,EAAE,EACnC,MAAM,EAAE,wBAAwB,GAC/B,kBAAkB,CAqCpB"}