stitchkit 0.68.10 → 0.68.11

package/dist/browser/socket-io.d.ts

@@ -1,6 +1,6 @@
 import type { StitchLogger } from '../logger.js';
 import type { RealtimeAcknowledgedEvent, RealtimeAcknowledgement, RealtimeContract, RealtimeEventRegistry, RealtimeRejectedEventHook, RealtimeRequestArguments } from '../realtime/contract.js';
-import { type RealtimeRequestOptions } from '../realtime/request.js';
+import { type RealtimeRequestOptions, type RealtimeRequestPhaseHook } from '../realtime/request.js';
 import { type ValidatedRealtimeSocket } from '../realtime/socket.js';
 /**
  * How this project loads the optional Socket.IO **client** peer.
@@ -207,9 +207,15 @@ export interface BindRealtimeClientOptions {
 export interface RealtimeClientOptions<TServerToClient extends RealtimeEventRegistry> extends BindRealtimeClientOptions, SocketIOClientConfig<{
     [TEvent in keyof TServerToClient]: (...args: unknown[]) => void;
 }> {
+    /**
+     * Observe bounded metadata-only phases of acknowledged requests. Engine.IO
+     * phases are local encoder/decoder boundaries, not remote send time or RTT.
+     * Observer failures are isolated from request lifecycle.
+     */
+    onRequestPhase?: RealtimeRequestPhaseHook;
 }
 /** Add contract validation and typed acknowledgements without owning the transport lifecycle. */
 export declare function bindRealtimeClient<const TServerToClient extends RealtimeEventRegistry, const TClientToServer extends RealtimeEventRegistry>(contract: RealtimeContract<TServerToClient, TClientToServer>, transport: RealtimeClientTransport, { onRejected, logger }?: BindRealtimeClientOptions): BoundRealtimeClient<TServerToClient, TClientToServer>;
-export declare function createRealtimeClient<const TServerToClient extends RealtimeEventRegistry, const TClientToServer extends RealtimeEventRegistry>(contract: RealtimeContract<TServerToClient, TClientToServer>, { onRejected, logger, ...config }: RealtimeClientOptions<TServerToClient>): RealtimeClient<TServerToClient, TClientToServer>;
+export declare function createRealtimeClient<const TServerToClient extends RealtimeEventRegistry, const TClientToServer extends RealtimeEventRegistry>(contract: RealtimeContract<TServerToClient, TClientToServer>, { onRejected, logger, onRequestPhase, ...config }: RealtimeClientOptions<TServerToClient>): RealtimeClient<TServerToClient, TClientToServer>;
 export declare function createSocketIOClient<TServerEvents extends SocketEventMap, TClientEvents extends SocketEventMap>(config: SocketIOClientConfig<TServerEvents>): SocketIOClient<TServerEvents, TClientEvents>;
 //# sourceMappingURL=socket-io.d.ts.map

package/dist/browser/socket-io.d.ts.map

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

package/dist/{index-557by2db.js → index-7b188kmz.js}

@@ -1,4 +1,19 @@
 // src/realtime/request.ts
+import { z } from "zod";
+var RealtimeRequestPhaseSchema = z.enum([
+  "engine-handoff",
+  "engine-ack-received",
+  "settled",
+  "timeout",
+  "disconnected"
+]);
+var RealtimeRequestPhaseEventSchema = z.object({
+  requestId: z.string().min(1),
+  event: z.string().min(1),
+  phase: RealtimeRequestPhaseSchema,
+  elapsedMs: z.number().finite().nonnegative()
+}).strict();
+
 class RealtimeRequestTimeoutError extends Error {
   code = "REALTIME_REQUEST_TIMEOUT";
   event;

package/dist/index.js

@@ -1099,6 +1099,21 @@ function isModuleNotFound(error) {
 }
 
 // src/realtime/request.ts
+import { z as z2 } from "zod";
+var RealtimeRequestPhaseSchema = z2.enum([
+  "engine-handoff",
+  "engine-ack-received",
+  "settled",
+  "timeout",
+  "disconnected"
+]);
+var RealtimeRequestPhaseEventSchema = z2.object({
+  requestId: z2.string().min(1),
+  event: z2.string().min(1),
+  phase: RealtimeRequestPhaseSchema,
+  elapsedMs: z2.number().finite().nonnegative()
+}).strict();
+
 class RealtimeRequestTimeoutError extends Error {
   code = "REALTIME_REQUEST_TIMEOUT";
   event;
@@ -1186,9 +1201,9 @@ function parseIssues(value) {
 }
 
 // src/realtime/rejection.ts
-import { z as z2 } from "zod";
+import { z as z3 } from "zod";
 function realtimeContractViolation(options) {
-  const issues = options.cause instanceof z2.ZodError ? zodIssues(options.cause) : undefined;
+  const issues = options.cause instanceof z3.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,
@@ -1469,6 +1484,63 @@ function createRetainedTopics() {
 }
 
 // src/browser/socket-io.ts
+var realtimeRequestTraces = new WeakMap;
+function observeRealtimeRequestPhase(trace, phase) {
+  const observation = {
+    requestId: trace.requestId,
+    event: trace.event,
+    phase,
+    elapsedMs: performance.now() - trace.startedAt
+  };
+  try {
+    const result = trace.observe(observation);
+    if (result)
+      Promise.resolve(result).catch(() => {
+        return;
+      });
+  } catch {}
+}
+function socketIoPacketIdentity(data, expected) {
+  if (typeof data !== "string")
+    return null;
+  const type = data.charAt(0);
+  const binary = type === (expected === "event" ? "5" : "6");
+  if (type !== (expected === "event" ? "2" : "3") && !binary)
+    return null;
+  let offset = 1;
+  if (binary) {
+    const separator = data.indexOf("-", offset);
+    if (separator < 0)
+      return null;
+    for (let index = offset;index < separator; index += 1) {
+      const code = data.charCodeAt(index);
+      if (code < 48 || code > 57)
+        return null;
+    }
+    offset = separator + 1;
+  }
+  let namespace = "/";
+  if (data.charAt(offset) === "/") {
+    const separator = data.indexOf(",", offset);
+    if (separator < 0)
+      return null;
+    namespace = data.slice(offset, separator);
+    offset = separator + 1;
+  }
+  const start = offset;
+  while (offset < data.length) {
+    const code = data.charCodeAt(offset);
+    if (code < 48 || code > 57)
+      break;
+    offset += 1;
+  }
+  if (offset === start)
+    return null;
+  return { namespace, id: data.slice(start, offset) };
+}
+function packetIdentityKey(identity) {
+  return `${identity.namespace}:${identity.id}`;
+}
 var SOCKET_IO_CLIENT = "socket.io-client";
 var ioLoader = null;
 function loadIo() {
@@ -1564,8 +1636,20 @@ function bindRealtimeClient(contract, transport, { onRejected, logger } = {}) {
     if (!definition?.ack) {
       throw new Error(`Realtime request "${event}" has no acknowledgement schema`);
     }
-    const value = await transport.emitWithAck(event, parsedArgs, { timeoutMs });
-    const acknowledgement = parseRealtimeRequestAcknowledgement(definition.ack, event, "client-inbound", value, onRejected, logger);
+    const pending = transport.emitWithAck(event, parsedArgs, { timeoutMs });
+    const trace = realtimeRequestTraces.get(pending);
+    if (trace)
+      realtimeRequestTraces.delete(pending);
+    const value = await pending;
+    let acknowledgement;
+    try {
+      acknowledgement = parseRealtimeRequestAcknowledgement(definition.ack, event, "client-inbound", value, onRejected, logger);
+    } finally {
+      if (trace && !trace.closed) {
+        trace.closed = true;
+        observeRealtimeRequestPhase(trace, "settled");
+      }
+    }
     return acknowledgement;
   }
   return {
@@ -1577,8 +1661,8 @@ function bindRealtimeClient(contract, transport, { onRejected, logger } = {}) {
     onConnectionChange: (listener) => transport.onConnectionChange(listener)
   };
 }
-function createRealtimeClient(contract, { onRejected, logger, ...config }) {
-  const transport = createSocketIOClient(config);
+function createRealtimeClient(contract, { onRejected, logger, onRequestPhase, ...config }) {
+  const transport = createSocketIOClientInternal(config, onRequestPhase);
   const bound = bindRealtimeClient(contract, transport, { onRejected, logger });
   return {
     ...bound,
@@ -1590,12 +1674,17 @@ function createRealtimeClient(contract, { onRejected, logger, ...config }) {
   };
 }
 function createSocketIOClient(config) {
+  return createSocketIOClientInternal(config);
+}
+function createSocketIOClientInternal(config, onRequestPhase) {
   let socket = null;
   const resolveIo = createIoResolver(config.peers?.client);
   let desiredConnected = false;
   let loadingPeer = false;
   let reconnectTimer = null;
   const pendingRequestDisconnects = new Set;
+  const requestTracesByNativeKey = new Map;
+  let startingRequestTrace = null;
   const serverDisconnectDelay = config.reconnectOnServerDisconnect ?? 1000;
   const connectionListeners = new Set;
   const subscriptions = new Set;
@@ -1629,6 +1718,37 @@ function createSocketIOClient(config) {
       reconnectionDelayMax: config.reconnectionDelayMax ?? 5000,
       timeout: config.timeout ?? 20000
     });
+    if (onRequestPhase) {
+      socket.io.on("open", () => {
+        const engine = socket?.io.engine;
+        if (!engine)
+          return;
+        engine.on("packetCreate", (packet) => {
+          if (!startingRequestTrace || packet.type !== "message")
+            return;
+          const identity = socketIoPacketIdentity(packet.data, "event");
+          if (!identity)
+            return;
+          const key = packetIdentityKey(identity);
+          startingRequestTrace.nativeKey = key;
+          requestTracesByNativeKey.set(key, startingRequestTrace);
+          observeRealtimeRequestPhase(startingRequestTrace, "engine-handoff");
+        });
+        engine.on("packet", (packet) => {
+          if (packet.type !== "message")
+            return;
+          const identity = socketIoPacketIdentity(packet.data, "ack");
+          if (!identity)
+            return;
+          const key = packetIdentityKey(identity);
+          const trace = requestTracesByNativeKey.get(key);
+          if (!trace || trace.closed)
+            return;
+          observeRealtimeRequestPhase(trace, "engine-ack-received");
+          requestTracesByNativeKey.delete(key);
+        });
+      });
+    }
     socket.on("connect", () => notifyConnection(true));
     socket.on("disconnect", (reason) => {
       notifyConnection(false, reason);
@@ -1738,11 +1858,30 @@ function createSocketIOClient(config) {
       return true;
     },
     emitWithAck(event, args, options) {
+      const trace = onRequestPhase ? {
+        requestId: crypto.randomUUID(),
+        event,
+        startedAt: performance.now(),
+        observe: onRequestPhase,
+        closed: false
+      } : undefined;
+      const closeTrace = (phase) => {
+        if (!trace || trace.closed)
+          return;
+        trace.closed = true;
+        if (trace.nativeKey)
+          requestTracesByNativeKey.delete(trace.nativeKey);
+        observeRealtimeRequestPhase(trace, phase);
+      };
       const active = socket;
       if (!active?.connected) {
-        return Promise.reject(new RealtimeRequestDisconnectedError(event));
+        const pending2 = Promise.reject(new RealtimeRequestDisconnectedError(event));
+        closeTrace("disconnected");
+        if (trace)
+          realtimeRequestTraces.set(pending2, trace);
+        return pending2;
       }
-      return new Promise((resolve, reject) => {
+      const pending = new Promise((resolve, reject) => {
         let settled = false;
         const finish = (result) => {
           if (settled)
@@ -1753,14 +1892,31 @@ function createSocketIOClient(config) {
           result();
         };
         const onDisconnect = () => {
-          finish(() => reject(new RealtimeRequestDisconnectedError(event)));
+          finish(() => {
+            closeTrace("disconnected");
+            reject(new RealtimeRequestDisconnectedError(event));
+          });
         };
         pendingRequestDisconnects.add(onDisconnect);
         active.on("disconnect", onDisconnect);
-        active.timeout(options.timeoutMs).emitWithAck(event, ...args).then((value) => finish(() => resolve(value)), () => {
-          finish(() => reject(active.connected ? new RealtimeRequestTimeoutError(event, options.timeoutMs) : new RealtimeRequestDisconnectedError(event)));
+        let acknowledgement;
+        startingRequestTrace = trace ?? null;
+        try {
+          acknowledgement = active.timeout(options.timeoutMs).emitWithAck(event, ...args);
+        } finally {
+          startingRequestTrace = null;
+        }
+        acknowledgement.then((value) => finish(() => resolve(value)), () => {
+          finish(() => {
+            const connected = active.connected;
+            closeTrace(connected ? "timeout" : "disconnected");
+            reject(connected ? new RealtimeRequestTimeoutError(event, options.timeoutMs) : new RealtimeRequestDisconnectedError(event));
+          });
         });
       });
+      if (trace)
+        realtimeRequestTraces.set(pending, trace);
+      return pending;
     },
     onConnectionChange(listener) {
       connectionListeners.add(listener);
@@ -1783,6 +1939,8 @@ export {
   REALTIME_REJECTION_KEY,
   RealtimeRequestDisconnectedError,
   RealtimeRequestInvalidAcknowledgementError,
+  RealtimeRequestPhaseEventSchema,
+  RealtimeRequestPhaseSchema,
   RealtimeRequestRejectedError,
   RealtimeRequestTimeoutError,
   STITCH_ERROR_STATUS,

package/dist/node.js

@@ -16,7 +16,7 @@ import {
   implementRegistry
 } from "./index-hxh98zbm.js";
 import"./index-f24xg2cw.js";
-import"./index-557by2db.js";
+import"./index-7b188kmz.js";
 import {
   ShutdownOptionsSchema,
   ShutdownResultSchema,

package/dist/realtime/index.d.ts

@@ -1,5 +1,5 @@
 export { defineRealtimeContract, type InferRealtimeEventMap, type RealtimeAcknowledgedEvent, type RealtimeAcknowledgement, type RealtimeContract, type RealtimeEmitArguments, type RealtimeEventArguments, type RealtimeEventDefinition, type RealtimeEventHandler, type RealtimeEventRegistry, type RealtimeRejectDirection, type RealtimeRejectedEvent, type RealtimeRejectedEventHook, type RealtimeRequestArguments, } from './contract.js';
 export { asRealtimeRejection, REALTIME_REJECTION_KEY, type RealtimeRejectionEnvelope, type RealtimeRejectionIssue, type RealtimeRejectionReport, } from './rejected-frame.js';
-export { RealtimeRequestDisconnectedError, RealtimeRequestInvalidAcknowledgementError, type RealtimeRequestOptions, RealtimeRequestRejectedError, RealtimeRequestTimeoutError, } from './request.js';
+export { RealtimeRequestDisconnectedError, RealtimeRequestInvalidAcknowledgementError, type RealtimeRequestOptions, type RealtimeRequestPhase, type RealtimeRequestPhaseEvent, RealtimeRequestPhaseEventSchema, type RealtimeRequestPhaseHook, RealtimeRequestPhaseSchema, RealtimeRequestRejectedError, RealtimeRequestTimeoutError, } from './request.js';
 export type { ValidatedRealtimeSocket } from './socket.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/realtime/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,yBAAyB,EAC9B,KAAK,uBAAuB,EAC5B,KAAK,gBAAgB,EACrB,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,KAAK,uBAAuB,EAC5B,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,uBAAuB,EAC5B,KAAK,qBAAqB,EAC1B,KAAK,yBAAyB,EAC9B,KAAK,wBAAwB,GAC9B,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,mBAAmB,EACnB,sBAAsB,EACtB,KAAK,yBAAyB,EAC9B,KAAK,sBAAsB,EAC3B,KAAK,uBAAuB,GAC7B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,gCAAgC,EAChC,0CAA0C,EAC1C,KAAK,sBAAsB,EAC3B,4BAA4B,EAC5B,2BAA2B,GAC5B,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,uBAAuB,EAAE,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/realtime/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,yBAAyB,EAC9B,KAAK,uBAAuB,EAC5B,KAAK,gBAAgB,EACrB,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,KAAK,uBAAuB,EAC5B,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,uBAAuB,EAC5B,KAAK,qBAAqB,EAC1B,KAAK,yBAAyB,EAC9B,KAAK,wBAAwB,GAC9B,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,mBAAmB,EACnB,sBAAsB,EACtB,KAAK,yBAAyB,EAC9B,KAAK,sBAAsB,EAC3B,KAAK,uBAAuB,GAC7B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,gCAAgC,EAChC,0CAA0C,EAC1C,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,EACzB,KAAK,yBAAyB,EAC9B,+BAA+B,EAC/B,KAAK,wBAAwB,EAC7B,0BAA0B,EAC1B,4BAA4B,EAC5B,2BAA2B,GAC5B,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,uBAAuB,EAAE,MAAM,UAAU,CAAC"}

package/dist/realtime/request.d.ts

@@ -1,4 +1,29 @@
+import { z } from 'zod';
 import type { RealtimeRejectionIssue } from './rejected-frame.js';
+/** Closed lifecycle reported by an opt-in acknowledged-request observer. */
+export declare const RealtimeRequestPhaseSchema: z.ZodEnum<{
+    disconnected: "disconnected";
+    "engine-ack-received": "engine-ack-received";
+    "engine-handoff": "engine-handoff";
+    settled: "settled";
+    timeout: "timeout";
+}>;
+/** Metadata-only observation: no arguments, acknowledgement or packet bytes. */
+export declare const RealtimeRequestPhaseEventSchema: z.ZodObject<{
+    requestId: z.ZodString;
+    event: z.ZodString;
+    phase: z.ZodEnum<{
+        disconnected: "disconnected";
+        "engine-ack-received": "engine-ack-received";
+        "engine-handoff": "engine-handoff";
+        settled: "settled";
+        timeout: "timeout";
+    }>;
+    elapsedMs: z.ZodNumber;
+}, z.core.$strict>;
+export type RealtimeRequestPhase = z.infer<typeof RealtimeRequestPhaseSchema>;
+export type RealtimeRequestPhaseEvent = z.infer<typeof RealtimeRequestPhaseEventSchema>;
+export type RealtimeRequestPhaseHook = (event: RealtimeRequestPhaseEvent) => void | Promise<void>;
 export interface RealtimeRequestOptions {
     /** Maximum acknowledgement wait in milliseconds. Must be finite and > 0. */
     timeoutMs: number;

package/dist/realtime/request.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"request.d.ts","sourceRoot":"","sources":["../../src/realtime/request.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAE/D,MAAM,WAAW,sBAAsB;IACrC,4EAA4E;IAC5E,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,qBAAa,2BAA4B,SAAQ,KAAK;IACpD,QAAQ,CAAC,IAAI,8BAA8B;IAC3C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B,YAAY,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAK3C;CACF;AAED,qBAAa,gCAAiC,SAAQ,KAAK;IACzD,QAAQ,CAAC,IAAI,mCAAmC;IAChD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB,YAAY,KAAK,EAAE,MAAM,EAIxB;CACF;AAED,qBAAa,0CAA2C,SAAQ,KAAK;IACnE,QAAQ,CAAC,IAAI,8CAA8C;IAC3D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB,YAAY,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAIxC;CACF;AAED;;;;;;;;;GASG;AACH,qBAAa,4BAA6B,SAAQ,KAAK;IACrD,QAAQ,CAAC,IAAI,+BAA+B;IAC5C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,6EAA6E;IAC7E,QAAQ,CAAC,MAAM,EAAE,sBAAsB,EAAE,GAAG,SAAS,CAAC;IAEtD,YACE,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,sBAAsB,EAAE,EAOlC;CACF"}
+{"version":3,"file":"request.d.ts","sourceRoot":"","sources":["../../src/realtime/request.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAE/D,4EAA4E;AAC5E,eAAO,MAAM,0BAA0B;;;;;;EAMrC,CAAC;AAEH,gFAAgF;AAChF,eAAO,MAAM,+BAA+B;;;;;;;;;;;kBAOjC,CAAC;AAEZ,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAC9E,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,+BAA+B,CAAC,CAAC;AACxF,MAAM,MAAM,wBAAwB,GAAG,CACrC,KAAK,EAAE,yBAAyB,KAC7B,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE1B,MAAM,WAAW,sBAAsB;IACrC,4EAA4E;IAC5E,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,qBAAa,2BAA4B,SAAQ,KAAK;IACpD,QAAQ,CAAC,IAAI,8BAA8B;IAC3C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B,YAAY,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAK3C;CACF;AAED,qBAAa,gCAAiC,SAAQ,KAAK;IACzD,QAAQ,CAAC,IAAI,mCAAmC;IAChD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB,YAAY,KAAK,EAAE,MAAM,EAIxB;CACF;AAED,qBAAa,0CAA2C,SAAQ,KAAK;IACnE,QAAQ,CAAC,IAAI,8CAA8C;IAC3D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB,YAAY,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAIxC;CACF;AAED;;;;;;;;;GASG;AACH,qBAAa,4BAA6B,SAAQ,KAAK;IACrD,QAAQ,CAAC,IAAI,+BAA+B;IAC5C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,6EAA6E;IAC7E,QAAQ,CAAC,MAAM,EAAE,sBAAsB,EAAE,GAAG,SAAS,CAAC;IAEtD,YACE,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,sBAAsB,EAAE,EAOlC;CACF"}

package/dist/server/index.js

@@ -53,7 +53,7 @@ import {
   isWithinDir,
   realPathWithinDir
 } from "../index-sbdmyz75.js";
-import"../index-557by2db.js";
+import"../index-7b188kmz.js";
 import {
   ShutdownOptionsSchema,
   ShutdownResultSchema,

package/dist/testing.js

@@ -11,7 +11,7 @@ import {
   RealtimeRequestDisconnectedError,
   RealtimeRequestInvalidAcknowledgementError,
   RealtimeRequestTimeoutError
-} from "./index-557by2db.js";
+} from "./index-7b188kmz.js";
 import"./index-dk6e56g0.js";
 import {
   mcpProjectionCandidate,

package/llms-full.txt

@@ -6161,6 +6161,7 @@ const socket = createRealtimeClient(realtimeContract, {
   url: 'https://api.example.com',
   retain: ['note:created'],
   onRejected: (event) => reportClientError(event),
+  onRequestPhase: (event) => metrics.realtimeRequestPhase(event),
 })
 
 socket.connect()
@@ -6215,6 +6216,48 @@ or resumable delivery should use separate correlated events or the async
 operation protocol; keeping one acknowledgement open is not a durable RPC/job
 transport.
 
+### Acknowledged-request phases
+
+`createRealtimeClient` can expose the local boundary that a single Promise
+normally hides:
+
+```ts
+const socket = createRealtimeClient(realtimeContract, {
+  url,
+  onRequestPhase: ({ requestId, event, phase, elapsedMs }) => {
+    requestPhaseHistogram.record(elapsedMs, { requestId, event, phase })
+  },
+})
+```
+
+The hook is opt-in and each record has exactly four metadata fields: an opaque,
+Kit-owned `requestId`, the contract event name, monotonic `elapsedMs`, and one
+closed phase:
+
+| Phase | Exact local boundary |
+|-------|----------------------|
+| `engine-handoff` | Engine.IO created the outbound message packet and accepted it into its write path |
+| `engine-ack-received` | Engine.IO decoded the inbound acknowledgement message, before Socket.IO invokes the acknowledgement callback |
+| `settled` | the acknowledgement callback ran and Stitchkit finished acknowledgement validation |
+| `timeout` | the existing native acknowledgement timeout won |
+| `disconnected` | the request began disconnected or an in-flight disconnect won |
+
+Engine handoff is not proof of a physical network write. Engine acknowledgement
+receipt is not a remote clock, end-to-end RTT or proof that application
+validation has run. The useful interval is local and monotonic:
+`engine-ack-received → settled` isolates callback scheduling plus validation
+from transport waiting.
+
+Records never contain request arguments, acknowledgement values, raw packets,
+credentials, URLs or query data. Concurrent requests are correlated internally
+with Socket.IO acknowledgement ids, but those ids are never exposed. A timeout
+or disconnect is terminal, a late packet cannot reopen the identity, and sync
+or async observer failures are ignored so telemetry cannot change request
+correctness. With no hook, no request identity, Engine.IO listener or correlation
+map entry is created. The low-level `createSocketIOClient` and non-owning
+`bindRealtimeClient` remain unchanged; this phase surface belongs to the
+canonical composed client that owns both transport and validation.
+
 ## Low-level transport
 
 `createSocketIOClient` remains the low-level Socket.IO transport wrapper for
@@ -11248,7 +11291,7 @@ The browser-and-server entrypoint. Re-exports everything from
 | `SocketIOClientConfig` | _type_ | config for `createSocketIOClient` (incl. `retain`, `onConnectError`, `onDroppedEmit`) |
 | `SocketEventMap` | _type_ | the shape of an event map |
 | `RealtimeClient` | _type_ | validated client inferred from a realtime contract |
-| `RealtimeClientOptions` | _type_ | transport options and the rejected-event hook for `createRealtimeClient` |
+| `RealtimeClientOptions` | _type_ | transport options plus rejected-event and metadata-only acknowledged-request phase hooks for `createRealtimeClient` |
 | `BoundRealtimeClient` | _type_ | validated non-owning `on`/`emit`/`request` client with no `connect`/`disconnect` |
 | `RealtimeClientTransport` | _type_ | minimal existing transport capability accepted by `bindRealtimeClient` |
 | `BindRealtimeClientOptions` | _type_ | rejection/logger options for a bound existing transport |
@@ -11256,6 +11299,9 @@ The browser-and-server entrypoint. Re-exports everything from
 | `RealtimeAcknowledgement` | _type_ | validated acknowledgement output inferred from an event definition |
 | `RealtimeRequestArguments` | _type_ | request arguments inferred from an acknowledged event tuple |
 | `RealtimeRequestOptions` | _type_ | finite positive native acknowledgement `timeoutMs` |
+| `RealtimeRequestPhaseSchema` / `RealtimeRequestPhase` | schema / _type_ | closed `engine-handoff` / `engine-ack-received` / `settled` / `timeout` / `disconnected` lifecycle |
+| `RealtimeRequestPhaseEventSchema` / `RealtimeRequestPhaseEvent` | schema / _type_ | strict metadata-only `{ requestId, event, phase, elapsedMs }` observation |
+| `RealtimeRequestPhaseHook` | _type_ | isolated sync/async observer accepted by `RealtimeClientOptions.onRequestPhase` |
 | `RealtimeRequestTimeoutError` | class | stable `REALTIME_REQUEST_TIMEOUT` rejection |
 | `RealtimeRequestDisconnectedError` | class | stable `REALTIME_REQUEST_DISCONNECTED` rejection, including an immediate disconnected call |
 | `RealtimeRequestInvalidAcknowledgementError` | class | invalid ack was reported through `onRejected` and the request rejected |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.68.10",
+  "version": "0.68.11",
   "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",