stitchkit 0.44.1 → 0.46.0

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,wBAAwB,EACxB,YAAY,EACZ,aAAa,EACb,mBAAmB,EACnB,uBAAuB,EACvB,gBAAgB,EAChB,iBAAiB,EACjB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,wBAAwB,EAC7B,KAAK,gBAAgB,GACtB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,QAAQ,EACR,KAAK,QAAQ,EACb,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,gBAAgB,EAChB,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,mBAAmB,GACzB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EACV,cAAc,EACd,cAAc,EACd,oBAAoB,GACrB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,KAAK,eAAe,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAClE,cAAc,YAAY,CAAC;AAG3B,OAAO,EACL,SAAS,EACT,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,KAAK,YAAY,GAClB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,oBAAoB,EAAE,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,wBAAwB,EACxB,YAAY,EACZ,aAAa,EACb,mBAAmB,EACnB,uBAAuB,EACvB,gBAAgB,EAChB,iBAAiB,EACjB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,wBAAwB,EAC7B,KAAK,gBAAgB,GACtB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,QAAQ,EACR,KAAK,QAAQ,EACb,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,gBAAgB,EAChB,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,mBAAmB,GACzB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EACV,cAAc,EACd,qBAAqB,EACrB,cAAc,EACd,cAAc,EACd,oBAAoB,GACrB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AACjF,OAAO,EAAE,KAAK,eAAe,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAClE,cAAc,YAAY,CAAC;AAC3B,YAAY,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAG7C,OAAO,EACL,SAAS,EACT,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,KAAK,YAAY,GAClB,MAAM,uBAAuB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,oBAAoB,EAAE,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -17,12 +17,13 @@ import {
   parseTrailingWildcard,
   rateLimited,
   unauthorized
-} from "./index-r6czv7yt.js";
+} from "./index-pwyedf7b.js";
 import {
   isRecord,
   mapObject,
+  transportResult,
   typedEntries
-} from "./index-s4qsmgwe.js";
+} from "./index-tss6bk5c.js";
 
 // src/browser/client-multipart.ts
 function isFileDescriptor(value) {
@@ -211,7 +212,7 @@ function joinClientBaseUrl(baseUrl, relativeUrl) {
 import ky, { isHTTPError } from "ky";
 
 // src/observability/trace.ts
-var TRACEPARENT_RE = /^00-([0-9a-f]{32})-([0-9a-f]{16})-[0-9a-f]{2}$/i;
+var TRACEPARENT_RE = /^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})(.*)$/i;
 function randomHex(bytes) {
   const arr = new Uint8Array(bytes);
   crypto.getRandomValues(arr);
@@ -227,16 +228,24 @@ function parseTraceparent(header) {
   if (!header)
     return null;
   const match = TRACEPARENT_RE.exec(header.trim());
-  if (!match?.[1] || !match[2])
+  if (!match?.[1] || !match[2] || !match[3] || !match[4] || match[5] === undefined)
     return null;
-  const traceId = match[1].toLowerCase();
-  const parentSpanId = match[2].toLowerCase();
+  const version = match[1].toLowerCase();
+  if (version === "ff")
+    return null;
+  const suffix = match[5];
+  if (version === "00" ? suffix !== "" : suffix !== "" && !/^(?:-[0-9a-f]{2,})+$/i.test(suffix)) {
+    return null;
+  }
+  const traceId = match[2].toLowerCase();
+  const parentSpanId = match[3].toLowerCase();
+  const traceFlags = match[4].toLowerCase();
   if (/^0+$/.test(traceId) || /^0+$/.test(parentSpanId))
     return null;
-  return { traceId, spanId: randomHex(8), parentSpanId };
+  return { traceId, spanId: randomHex(8), parentSpanId, traceFlags };
 }
 function formatTraceparent(ctx) {
-  return `00-${ctx.traceId}-${ctx.spanId}-01`;
+  return `00-${ctx.traceId}-${ctx.spanId}-${ctx.traceFlags ?? "01"}`;
 }
 function childSpan(parent) {
   return {
@@ -244,7 +253,8 @@ function childSpan(parent) {
     spanId: randomHex(8),
     parentSpanId: parent.spanId,
     ...parent.tracestate !== undefined && { tracestate: parent.tracestate },
-    ...parent.baggage !== undefined && { baggage: parent.baggage }
+    ...parent.baggage !== undefined && { baggage: parent.baggage },
+    ...parent.traceFlags !== undefined && { traceFlags: parent.traceFlags }
   };
 }
 var encoder = new TextEncoder;
@@ -376,10 +386,10 @@ function createHttpClient(config) {
     }
     try {
       if (options.responseType === "blob") {
-        return client[method](url, kyOptions).blob();
+        return transportResult(await client[method](url, kyOptions).blob());
       }
       if (options.responseType === "response") {
-        return await client[method](url, kyOptions);
+        return transportResult(await client[method](url, kyOptions));
       }
       const response = await client[method](url, kyOptions);
       if (options.responseType === "void") {
@@ -389,9 +399,9 @@ function createHttpClient(config) {
         }
       }
       if (options.responseType === "void" || response.status === 204 || response.headers.get("content-length") === "0") {
-        return;
+        return transportResult(undefined);
       }
-      return response.json();
+      return await response.json();
     } catch (error) {
       if (ApiError.is(error))
         throw error;
@@ -646,6 +656,201 @@ function createUrlBuilders(contracts, source, contractConfig) {
 function createScopedUrlBuilders(contracts, source, scopeConfigs) {
   return buildScopedRegistry(contracts, scopeConfigs, "URL builder", (contract, config) => createUrlBuilder(contract, source, config));
 }
+// src/realtime/rejection.ts
+import { z as z2 } from "zod";
+
+// src/internal/errors.ts
+import { z } from "zod";
+function issuePath(path) {
+  return path.length > 0 ? path.map(String).join(".") : "(root)";
+}
+function zodIssues(error) {
+  return error.issues.map((issue) => ({
+    path: issuePath(issue.path),
+    code: issue.code,
+    message: issue.message
+  }));
+}
+
+// src/realtime/rejection.ts
+function realtimeContractViolation(options) {
+  const issues = options.cause instanceof z2.ZodError ? zodIssues(options.cause) : undefined;
+  const reason = options.reason.replaceAll("-", " ");
+  const error = new AppError("REALTIME_CONTRACT_VIOLATION", `Realtime event "${options.event}" (${options.direction}, ${options.phase}): ${reason}`, 500, {
+    event: options.event,
+    direction: options.direction,
+    phase: options.phase,
+    reason: options.reason,
+    fault: options.fault,
+    ...issues !== undefined && { issues }
+  });
+  if (options.cause !== undefined)
+    error.cause = options.cause;
+  return { ...options, error };
+}
+
+// src/realtime/socket.ts
+function method(target, name) {
+  const value = Reflect.get(target, name);
+  if (typeof value !== "function") {
+    throw new Error(`Realtime target does not implement ${name}()`);
+  }
+  return (...args) => Reflect.apply(value, target, args);
+}
+function splitWireArguments(definition, args) {
+  if (!definition.ack)
+    return { values: args };
+  const acknowledgement = args.at(-1);
+  if (typeof acknowledgement !== "function")
+    return { values: args };
+  return {
+    values: args.slice(0, -1),
+    acknowledgement: (...callbackArgs) => Reflect.apply(acknowledgement, undefined, callbackArgs)
+  };
+}
+function eventDefinition(registry, event, direction) {
+  const definition = registry[event];
+  if (!definition) {
+    throw realtimeContractViolation({
+      event,
+      direction,
+      phase: "arguments",
+      reason: "unknown-event",
+      fault: "local"
+    }).error;
+  }
+  return definition;
+}
+function reportRejected(rejected, hook, logger) {
+  if (!hook) {
+    if (logger) {
+      logger.warn(rejected.error.message, rejected.error.details);
+      return;
+    }
+    console.warn(`[stitchkit] rejected realtime ${rejected.direction} event "${rejected.event}" (${rejected.phase})`, rejected.error);
+    return;
+  }
+  Promise.resolve(hook(rejected)).catch((error) => {
+    console.error("[stitchkit] realtime rejection hook failed", error);
+  });
+}
+function createValidatedRealtimeSocket({
+  target,
+  inbound,
+  outbound,
+  inboundDirection,
+  outboundDirection,
+  onRejected,
+  logger,
+  subscribe
+}) {
+  const emitTarget = method(target, "emit");
+  return {
+    on: (event, handler) => {
+      const definition = eventDefinition(inbound, event, inboundDirection);
+      const wrapped = (...wireArgs) => {
+        const { values, acknowledgement } = splitWireArguments(definition, wireArgs);
+        const parsed = definition.args.safeParse(values);
+        if (!parsed.success) {
+          reportRejected(realtimeContractViolation({
+            event,
+            direction: inboundDirection,
+            phase: "arguments",
+            reason: "invalid-arguments",
+            fault: "peer",
+            cause: parsed.error
+          }), onRejected, logger);
+          return;
+        }
+        if (definition.ack && !acknowledgement) {
+          reportRejected(realtimeContractViolation({
+            event,
+            direction: inboundDirection,
+            phase: "acknowledgement",
+            reason: "missing-acknowledgement",
+            fault: "peer"
+          }), onRejected, logger);
+          return;
+        }
+        const applicationArgs = [...parsed.data];
+        if (definition.ack) {
+          applicationArgs.push((value) => {
+            const ack = definition.ack?.safeParse(value);
+            if (!ack?.success) {
+              if (ack) {
+                reportRejected(realtimeContractViolation({
+                  event,
+                  direction: outboundDirection,
+                  phase: "acknowledgement",
+                  reason: "invalid-acknowledgement-value",
+                  fault: "local",
+                  cause: ack.error
+                }), onRejected, logger);
+              }
+              return;
+            }
+            acknowledgement?.(ack.data);
+          });
+        }
+        Reflect.apply(handler, undefined, applicationArgs);
+      };
+      if (subscribe)
+        return subscribe(event, wrapped);
+      const onTarget = method(target, "on");
+      const offTarget = method(target, "off");
+      onTarget(event, wrapped);
+      return () => {
+        offTarget(event, wrapped);
+      };
+    },
+    emit: (event, ...args) => {
+      const definition = eventDefinition(outbound, event, outboundDirection);
+      const { values, acknowledgement } = splitWireArguments(definition, args);
+      const parsed = definition.args.safeParse(values);
+      if (!parsed.success) {
+        throw realtimeContractViolation({
+          event,
+          direction: outboundDirection,
+          phase: "arguments",
+          reason: "invalid-arguments",
+          fault: "local",
+          cause: parsed.error
+        }).error;
+      }
+      if (definition.ack && !acknowledgement) {
+        throw realtimeContractViolation({
+          event,
+          direction: outboundDirection,
+          phase: "acknowledgement",
+          reason: "missing-acknowledgement",
+          fault: "local"
+        }).error;
+      }
+      const wireArgs = [...parsed.data];
+      if (definition.ack && acknowledgement) {
+        wireArgs.push((value) => {
+          const ack = definition.ack?.safeParse(value);
+          if (!ack?.success) {
+            if (ack) {
+              reportRejected(realtimeContractViolation({
+                event,
+                direction: inboundDirection,
+                phase: "acknowledgement",
+                reason: "invalid-acknowledgement-value",
+                fault: "peer",
+                cause: ack.error
+              }), onRejected, logger);
+            }
+            return;
+          }
+          acknowledgement(ack.data);
+        });
+      }
+      emitTarget(event, ...wireArgs);
+    }
+  };
+}
+
 // src/retained.ts
 function createRetainedTopics() {
   const last = {};
@@ -691,6 +896,40 @@ function toIoAuth(auth) {
     Promise.resolve().then(auth).then(cb, () => cb({}));
   };
 }
+function createRealtimeClient(contract, { onRejected, logger, ...config }) {
+  const transport = createSocketIOClient(config);
+  const events = createValidatedRealtimeSocket({
+    target: transport,
+    inbound: contract.serverToClient,
+    outbound: contract.clientToServer,
+    inboundDirection: "client-inbound",
+    outboundDirection: "client-outbound",
+    onRejected,
+    logger,
+    subscribe: (event, handler) => {
+      const subscribe = Reflect.get(transport, "on");
+      if (typeof subscribe !== "function") {
+        throw new Error("Socket.IO client does not implement on()");
+      }
+      const unsubscribe = Reflect.apply(subscribe, transport, [event, handler]);
+      if (typeof unsubscribe !== "function") {
+        throw new Error("Socket.IO client on() did not return an unsubscribe function");
+      }
+      return () => {
+        Reflect.apply(unsubscribe, undefined, []);
+      };
+    }
+  });
+  return {
+    ...events,
+    connect: transport.connect,
+    disconnect: transport.disconnect,
+    get connected() {
+      return transport.connected;
+    },
+    onConnectionChange: transport.onConnectionChange
+  };
+}
 function createSocketIOClient(config) {
   let socket = null;
   let desiredConnected = false;
@@ -741,6 +980,9 @@ function createSocketIOClient(config) {
         }, serverDisconnectDelay);
       }
     });
+    socket.io.on("reconnect_failed", () => {
+      desiredConnected = false;
+    });
     if (retained) {
       for (const name of retainNames) {
         socket.on(name, (payload) => retained.record(name, payload));
@@ -755,9 +997,13 @@ function createSocketIOClient(config) {
       return socket?.connected ?? false;
     },
     connect() {
-      if (socket || desiredConnected)
+      if (socket?.connected || desiredConnected)
         return;
       desiredConnected = true;
+      if (socket) {
+        socket.connect();
+        return;
+      }
       loadIo().then(openSocket);
     },
     disconnect() {
@@ -801,9 +1047,6 @@ function createSocketIOClient(config) {
     }
   };
 }
-// src/internal/errors.ts
-import { z } from "zod";
-
 // src/server/stream.ts
 async function* parseSSE(response, options) {
   const reader = response.body?.getReader();
@@ -838,6 +1081,10 @@ async function* parseSSE(response, options) {
     reader.releaseLock();
   }
 }
+// src/realtime/contract.ts
+function defineRealtimeContract(contract) {
+  return contract;
+}
 export {
   unauthorized,
   rateLimited,
@@ -849,6 +1096,7 @@ export {
   formatTraceparent,
   forbidden,
   encodeCursor,
+  defineRealtimeContract,
   defineErrors,
   defineContract,
   decodeCursor,
@@ -859,6 +1107,7 @@ export {
   createScopedUrlBuilders,
   createScopedClients,
   createRetainedTopics,
+  createRealtimeClient,
   createHttpClient,
   createContractFactory,
   createClients,

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;AAQvC,wBAAgB,cAAc,CAAC,KAAK,EAAE,CAAC,CAAC,QAAQ,GAAG,MAAM,CAMxD;AAED,qFAAqF;AACrF,MAAM,WAAW,eAAe;IAC9B,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAC;IACb,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,CAAC,CAAC,QAAQ,GAAG,eAAe,EAAE,CAM9D;AAKD;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAI1D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,eAAe,EAAE,MAAM,GAAG,SAAS,EACnC,MAAM,EAAE,OAAO,GACd,MAAM,GAAG,SAAS,CAMpB;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,QAAQ,CAgBrD;AA4BD;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,OAAO,EACf,IAAI,EAAE,OAAO,EACb,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,IAAI,GACrC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAe9D;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,OAAO,GAAG,SAAS,EAC3B,IAAI,EAAE,OAAO,EACb,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,IAAI,GACrC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAe9D"}
+{"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;AAQvC,wBAAgB,cAAc,CAAC,KAAK,EAAE,CAAC,CAAC,QAAQ,GAAG,MAAM,CAMxD;AAED,qFAAqF;AACrF,MAAM,WAAW,eAAe;IAC9B,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAC;IACb,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,CAAC,CAAC,QAAQ,GAAG,eAAe,EAAE,CAM9D;AAKD;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAI1D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,eAAe,EAAE,MAAM,GAAG,SAAS,EACnC,MAAM,EAAE,OAAO,GACd,MAAM,GAAG,SAAS,CAYpB;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,QAAQ,CAyBrD;AA4BD;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,OAAO,EACf,IAAI,EAAE,OAAO,EACb,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,IAAI,GACrC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAe9D;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,OAAO,GAAG,SAAS,EAC3B,IAAI,EAAE,OAAO,EACb,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,IAAI,GACrC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAe9D"}

package/dist/internal/secure-fetch.d.ts

@@ -4,9 +4,13 @@ export declare function isPrivateIp(ip: string): boolean;
  * Refuse a URL that is not `http(s)`, has no host, or whose host is — or
  * resolves to — a private/internal address. Called on the initial URL and on
  * every redirect hop, so a public host cannot `302` to an internal address or
- * to a `file:` / `gopher:` / `data:` scheme.
+ * to a `file:` / `gopher:` / `data:` scheme. The DNS lookup honours `signal`,
+ * so a slow resolver cannot outlive the caller's deadline.
+ *
+ * This is the single host-validation implementation — `fetchGuarded` and
+ * `fetchPinnedDocument` both go through `resolvePublicAddress`.
  */
-export declare function assertPublicUrl(url: URL): Promise<void>;
+export declare function assertPublicUrl(url: URL, signal?: AbortSignal): Promise<void>;
 /**
  * Fetch a URL with the SSRF guard enforced on the initial URL and on every
  * redirect hop — a public host can otherwise `302` to an internal address or a
@@ -17,7 +21,23 @@ export declare function assertPublicUrl(url: URL): Promise<void>;
  * per-hop re-check is the larger and fully-closed hole; a static private DNS
  * record is rejected outright.
  */
-export declare function fetchGuarded(start: URL, allowPrivate: boolean): Promise<Response>;
+export interface GuardedFetchOptions {
+    /**
+     * Deadline for producing the FINAL response headers — DNS, connects and every
+     * redirect hop share this single budget, so a redirect chain cannot multiply
+     * it. Default 15 seconds.
+     */
+    timeoutMs?: number;
+    /**
+     * Separate deadline for consuming the body once headers have arrived — a slow
+     * LARGE download must not be killed by the connection budget, but a drip-feed
+     * body must still end. Default 120 seconds.
+     */
+    bodyTimeoutMs?: number;
+    /** Optional caller cancellation, combined with both deadlines. */
+    signal?: AbortSignal;
+}
+export declare function fetchGuarded(start: URL, allowPrivate: boolean, options?: GuardedFetchOptions): Promise<Response>;
 export interface PinnedDocumentFetchOptions {
     maxBytes: number;
     timeoutMs: number;

package/dist/internal/secure-fetch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"secure-fetch.d.ts","sourceRoot":"","sources":["../../src/internal/secure-fetch.ts"],"names":[],"mappings":"AAiEA,iFAAiF;AACjF,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CA8D/C;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CA0B7D;AAED;;;;;;;;;GASG;AACH,wBAAsB,YAAY,CAAC,KAAK,EAAE,GAAG,EAAE,YAAY,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CAavF;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,6DAA6D;IAC7D,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,UAAU,CAAC;IACjB,GAAG,EAAE,GAAG,CAAC;CACV;AAoCD;;;;GAIG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,GAAG,EACV,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,sBAAsB,CAAC,CAgFjC;AAED;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAoBnF"}
+{"version":3,"file":"secure-fetch.d.ts","sourceRoot":"","sources":["../../src/internal/secure-fetch.ts"],"names":[],"mappings":"AAiEA,iFAAiF;AACjF,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CA8D/C;AA4BD;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAEnF;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kEAAkE;IAClE,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,wBAAsB,YAAY,CAChC,KAAK,EAAE,GAAG,EACV,YAAY,EAAE,OAAO,EACrB,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,QAAQ,CAAC,CAiDnB;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,6DAA6D;IAC7D,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,UAAU,CAAC;IACjB,GAAG,EAAE,GAAG,CAAC;CACV;AAsCD;;;;GAIG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,GAAG,EACV,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,sBAAsB,CAAC,CAkFjC;AAED;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAoBnF"}

package/dist/internal/typed.d.ts

@@ -3,6 +3,13 @@ export declare function typedEntries<T extends object>(value: T): Array<{
 }[keyof T]>;
 /** Narrow an unknown value to a plain object — not `null`, not an array. */
 export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/** Invoke a runtime-discovered handler after a fail-first function check. */
+export declare function callRuntimeHandler(handler: unknown, context: unknown): unknown;
+/**
+ * Isolated loose-to-typed adapter boundary for transports whose decoder is
+ * selected at runtime while the contract fixes the generic result type.
+ */
+export declare function transportResult<T>(value: unknown): T;
 export declare function mapObject<TSource extends object, TResult extends {
     [K in keyof TSource]?: unknown;
 }>(source: TSource, mapper: <K extends keyof TSource>(key: K, value: TSource[K]) => TResult[K] | undefined): TResult;

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

@@ -1 +1 @@
-{"version":3,"file":"typed.d.ts","sourceRoot":"","sources":["../../src/internal/typed.ts"],"names":[],"mappings":"AAAA,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,EAC3C,KAAK,EAAE,CAAC,GACP,KAAK,CAAC;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;CAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAE/C;AAED,4EAA4E;AAC5E,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEzE;AAED,wBAAgB,SAAS,CACvB,OAAO,SAAS,MAAM,EACtB,OAAO,SAAS;KAAG,CAAC,IAAI,MAAM,OAAO,CAAC,CAAC,EAAE,OAAO;CAAE,EAElD,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,CAAC,CAAC,SAAS,MAAM,OAAO,EAAE,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,SAAS,GACrF,OAAO,CAOT;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,SAAS,MAAM,EACtB,OAAO,SAAS;KAAG,CAAC,IAAI,MAAM,OAAO,CAAC,CAAC,EAAE,OAAO;CAAE,EAElD,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,OAAO,EAAE,KAAK,EAAE,OAAO,CAAC,MAAM,OAAO,CAAC,KAAK,OAAO,GACrE,OAAO,CAKT"}
+{"version":3,"file":"typed.d.ts","sourceRoot":"","sources":["../../src/internal/typed.ts"],"names":[],"mappings":"AAAA,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,EAC3C,KAAK,EAAE,CAAC,GACP,KAAK,CAAC;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;CAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAE/C;AAED,4EAA4E;AAC5E,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEzE;AAED,6EAA6E;AAC7E,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAK9E;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,GAAG,CAAC,CAEpD;AAED,wBAAgB,SAAS,CACvB,OAAO,SAAS,MAAM,EACtB,OAAO,SAAS;KAAG,CAAC,IAAI,MAAM,OAAO,CAAC,CAAC,EAAE,OAAO;CAAE,EAElD,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,CAAC,CAAC,SAAS,MAAM,OAAO,EAAE,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,SAAS,GACrF,OAAO,CAOT;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,SAAS,MAAM,EACtB,OAAO,SAAS;KAAG,CAAC,IAAI,MAAM,OAAO,CAAC,CAAC,EAAE,OAAO;CAAE,EAElD,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,OAAO,EAAE,KAAK,EAAE,OAAO,CAAC,MAAM,OAAO,CAAC,KAAK,OAAO,GACrE,OAAO,CAKT"}

package/dist/internal/within-dir.d.ts

@@ -4,4 +4,10 @@
  * check behind `staticRoute` and `view_file`'s local-file branch.
  */
 export declare function isWithinDir(root: string, target: string): boolean;
+/**
+ * Resolve both paths through the filesystem and return the real target only
+ * when it remains inside the real root. The lexical check must run first at a
+ * URL boundary; this second check closes symlink escapes.
+ */
+export declare function realPathWithinDir(root: string, target: string): Promise<string | null>;
 //# sourceMappingURL=within-dir.d.ts.map

package/dist/internal/within-dir.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"within-dir.d.ts","sourceRoot":"","sources":["../../src/internal/within-dir.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAQjE"}
+{"version":3,"file":"within-dir.d.ts","sourceRoot":"","sources":["../../src/internal/within-dir.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAQjE;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAO5F"}

package/dist/logger.d.ts

@@ -0,0 +1,8 @@
+/** Minimal structured logger shared by browser-safe and server entrypoints. */
+export interface StitchLogger {
+    info(msg: string, data?: Record<string, unknown>): void;
+    warn(msg: string, data?: Record<string, unknown>): void;
+    error(msg: string, data?: Record<string, unknown>): void;
+    debug(msg: string, data?: Record<string, unknown>): void;
+}
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACxD,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACxD,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACzD,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC1D"}

package/dist/node.d.ts

@@ -9,6 +9,7 @@ export { createHandler } from './server/create';
 export { createImplement, implement } from './server/implement';
 export type { LogFormat } from './server/logger';
 export { type NodeServerConfig, type NodeServerHandle, serveNode } from './server/node';
+export { bindRealtimeServer, type RealtimeServer, type RealtimeServerConnection, type RealtimeServerHandle, } from './server/realtime';
 export { createNodeSocketIOServer as createSocketIOServer, type NodeSocketIOServerHandle as SocketIOServerHandle, type SocketIOServerConfig, } from './server/socket-io-node';
 export type { FetchComposition, FetchHandler, HandlerConfig, LoggingConfig, LogOutcome, RawRoute, RawRouteContext, ServiceDef, } from './server/types';
 //# sourceMappingURL=node.d.ts.map

package/dist/node.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EACL,QAAQ,EACR,QAAQ,EACR,UAAU,EACV,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,WAAW,EACX,YAAY,GACb,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAChE,YAAY,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAAE,KAAK,gBAAgB,EAAE,KAAK,gBAAgB,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AACxF,OAAO,EACL,wBAAwB,IAAI,oBAAoB,EAChD,KAAK,wBAAwB,IAAI,oBAAoB,EACrD,KAAK,oBAAoB,GAC1B,MAAM,yBAAyB,CAAC;AACjC,YAAY,EACV,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,aAAa,EACb,UAAU,EACV,QAAQ,EACR,eAAe,EACf,UAAU,GACX,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EACL,QAAQ,EACR,QAAQ,EACR,UAAU,EACV,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,WAAW,EACX,YAAY,GACb,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAChE,YAAY,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAAE,KAAK,gBAAgB,EAAE,KAAK,gBAAgB,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AACxF,OAAO,EACL,kBAAkB,EAClB,KAAK,cAAc,EACnB,KAAK,wBAAwB,EAC7B,KAAK,oBAAoB,GAC1B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,wBAAwB,IAAI,oBAAoB,EAChD,KAAK,wBAAwB,IAAI,oBAAoB,EACrD,KAAK,oBAAoB,GAC1B,MAAM,yBAAyB,CAAC;AACjC,YAAY,EACV,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,aAAa,EACb,UAAU,EACV,QAAQ,EACR,eAAe,EACf,UAAU,GACX,MAAM,gBAAgB,CAAC"}

package/dist/node.js

@@ -1,11 +1,11 @@
 import {
+  bindRealtimeServer,
   createHandler,
   createImplement,
   createSocketIOServer,
   implement
-} from "./index-4fyn9f09.js";
-import"./index-6jypn22c.js";
-import"./index-x3fcszf8.js";
+} from "./index-zwqty9zf.js";
+import"./index-r1qp4rve.js";
 import {
   AppError,
   appError,
@@ -15,7 +15,7 @@ import {
   notFound,
   rateLimited,
   unauthorized
-} from "./index-yh0p5ddn.js";
+} from "./index-5s8b7z6q.js";
 // src/server/node.ts
 import { serve } from "srvx";
 async function serveNode(config) {
@@ -55,6 +55,7 @@ export {
   createImplement,
   createHandler,
   conflict,
+  bindRealtimeServer,
   badRequest,
   appError,
   AppError

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;AAClE,OAAO,EAAqB,KAAK,cAAc,EAAE,MAAM,WAAW,CAAC;AACnE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,EAAe,KAAK,eAAe,EAAmB,MAAM,YAAY,CAAC;AAGhF,kEAAkE;AAClE,MAAM,WAAW,sBAAsB;IACrC;;;;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,MAAM,WAAW,0BAA2B,SAAQ,sBAAsB;IACxE,2DAA2D;IAC3D,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,CAAC,EAAE,0BAA0B,CAAC;IACrC,KAAK,CAAC,EAAE,sBAAsB,CAAC;CAChC;AAED,gEAAgE;AAChE,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,cAAc,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;CAC5B;AAED,0EAA0E;AAC1E,MAAM,WAAW,mBAAmB;IAClC,cAAc,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,qBAAqB,GAAG,IAAI,CAAC;CACnD;AAED,iFAAiF;AACjF,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,EAAE,mBAAmB,CAAC;IAC9B,QAAQ,EAAE,aAAa,CAAC;CACzB;AAkFD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,mBAAmB,GAAG,aAAa,CA4G9E"}
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../../src/observability/audit.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,aAAa,EAAc,MAAM,kBAAkB,CAAC;AAClE,OAAO,EAAqB,KAAK,cAAc,EAAE,MAAM,WAAW,CAAC;AACnE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,EAAe,KAAK,eAAe,EAAmB,MAAM,YAAY,CAAC;AAGhF,kEAAkE;AAClE,MAAM,WAAW,sBAAsB;IACrC;;;;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,MAAM,WAAW,0BAA2B,SAAQ,sBAAsB;IACxE,2DAA2D;IAC3D,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,CAAC,EAAE,0BAA0B,CAAC;IACrC,KAAK,CAAC,EAAE,sBAAsB,CAAC;CAChC;AAED,gEAAgE;AAChE,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,cAAc,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;CAC5B;AAED,0EAA0E;AAC1E,MAAM,WAAW,mBAAmB;IAClC,cAAc,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,qBAAqB,GAAG,IAAI,CAAC;CACnD;AAED,iFAAiF;AACjF,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,EAAE,mBAAmB,CAAC;IAC9B,QAAQ,EAAE,aAAa,CAAC;CACzB;AAkFD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,mBAAmB,GAAG,aAAa,CAwH9E"}

package/dist/observability/event.d.ts

@@ -36,6 +36,8 @@ export interface RequestEvent {
     dimensions?: Record<string, string>;
     /** Tool name — tool calls only. */
     toolName?: string;
+    /** Distinguishes a completed operation from an MRTR input-gating round. */
+    toolPhase?: 'operation' | 'input-round';
     /** Validated MCP transport attribution, available only on MCP tool calls. */
     mcp?: {
         era: 'modern' | 'legacy';
@@ -81,6 +83,11 @@ export interface RequestEvent {
     resultSize: number | null;
     /** Serialised byte length of the result. */
     responseBytes: number;
+    /**
+     * Set when the result could not be serialised at all (bigint, a cycle) —
+     * distinguishes `responseBytes: 0` "nothing returned" from "unmeasurable".
+     */
+    resultUnserializable?: boolean;
     /** Resolved user id, when authenticated. */
     userId?: string;
     /** How the caller authenticated, when the app records it on the context. */

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,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,6EAA6E;IAC7E,GAAG,CAAC,EAAE;QACJ,GAAG,EAAE,QAAQ,GAAG,QAAQ,CAAC;QACzB,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,kFAAkF;QAClF,UAAU,CAAC,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAA;SAAE,CAAC;QAC/C,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;QACjB,4CAA4C;QAC5C,OAAO,CAAC,EAAE,gBAAgB,GAAG,UAAU,GAAG,WAAW,GAAG,SAAS,GAAG,UAAU,CAAC;QAC/E,8CAA8C;QAC9C,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,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"}
+{"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,2EAA2E;IAC3E,SAAS,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC;IACxC,6EAA6E;IAC7E,GAAG,CAAC,EAAE;QACJ,GAAG,EAAE,QAAQ,GAAG,QAAQ,CAAC;QACzB,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,kFAAkF;QAClF,UAAU,CAAC,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAA;SAAE,CAAC;QAC/C,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;QACjB,4CAA4C;QAC5C,OAAO,CAAC,EAAE,gBAAgB,GAAG,UAAU,GAAG,WAAW,GAAG,SAAS,GAAG,UAAU,CAAC;QAC/E,8CAA8C;QAC9C,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,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;;;OAGG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,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"}