stitchkit 0.60.0 → 0.61.0

package/dist/browser/stream.d.ts

@@ -1,2 +1,25 @@
 export { type ParseSSEOptions, parseSSE } from '../server/stream';
+/** Options for `parseNDJSON`. */
+export interface ParseNDJSONOptions {
+    /** Called for a line that is not valid JSON — the alternative to throwing. */
+    onParseError?: (raw: string, error: Error) => void;
+}
+/**
+ * Parse a newline-delimited JSON response body — the client half of
+ * `ndjsonRoute`.
+ *
+ * **Blank lines are skipped**, and that is the contract rather than a
+ * convenience. A long-lived NDJSON stream has to send something while it is
+ * idle or intermediaries drop it, and the natural pulse for this framing is an
+ * empty line. Writing the skip down here is what stops it being a verbal
+ * agreement between the two halves of one project: the server's keep-alive and
+ * the reader's rule are one decision with two implementations.
+ *
+ * **To end a subscription, abort the request.** Leaving the loop cancels the
+ * body — which is right, and this does it — but a client-side cancel is not a
+ * reliable way to reach the server: measured against Bun today, the source on
+ * the other end stayed alive for seconds afterwards. An aborted request reaches
+ * the route's `context.signal` at once.
+ */
+export declare function parseNDJSON<T>(response: Response, options?: ParseNDJSONOptions): AsyncGenerator<T>;
 //# sourceMappingURL=stream.d.ts.map

package/dist/browser/stream.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../../src/browser/stream.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,eAAe,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../../src/browser/stream.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,eAAe,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAElE,iCAAiC;AACjC,MAAM,WAAW,kBAAkB;IACjC,8EAA8E;IAC9E,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CACpD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAuB,WAAW,CAAC,CAAC,EAClC,QAAQ,EAAE,QAAQ,EAClB,OAAO,CAAC,EAAE,kBAAkB,GAC3B,cAAc,CAAC,CAAC,CAAC,CAmDnB"}

package/dist/cli.js

@@ -5,17 +5,18 @@ import {
   emitResult,
   parseCliArgs,
   pollUntilDone
-} from "./index-8pc5s3pz.js";
-import"./index-2akar0rq.js";
+} from "./index-1pgeyyee.js";
+import"./index-wrhf06ak.js";
 import"./index-sbdmyz75.js";
 import"./index-vkk06pv1.js";
 import"./index-6djpbnda.js";
 import"./index-cby4ar3v.js";
-import"./index-6fbp58g8.js";
-import"./index-v6e8hnkx.js";
+import"./index-tvwcrx2d.js";
+import"./index-wd8g8z6e.js";
 import"./index-6k1937bx.js";
 import"./index-pzyt11ch.js";
 import"./index-smpbdg6k.js";
+import"./index-xxye8j3k.js";
 export {
   DEFAULT_EXIT_CODES,
   createCli,

package/dist/contract/errors.d.ts

@@ -82,6 +82,7 @@ export declare const STITCH_ERROR_STATUS: {
     FILE_EXISTS: number;
     REALTIME_CONTRACT_VIOLATION: number;
     APPLICATION_NOT_ACCEPTING: number;
+    GRAMMY_WEBHOOK_NOT_ACCEPTING: number;
     WAIT_TIMEOUT: number;
     WAIT_FAILED: number;
     DOWNLOAD_NOT_FOUND: number;

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

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/contract/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE;QACL,2CAA2C;QAC3C,IAAI,EAAE,MAAM,CAAC;QACb,8BAA8B;QAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,gCAAgC;QAChC,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,0BAA0B;QAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,CAAC;CACH;AAcD;;;;GAIG;AACH,qBAAa,QAAQ,CACnB,KAAK,SAAS,MAAM,GAAG,MAAM,EAC7B,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAC1F,SAAQ,KAAK;aAEK,IAAI,EAAE,KAAK;aAEX,MAAM,EAAE,MAAM;aACd,OAAO,CAAC,EAAE,QAAQ;aAClB,IAAI,CAAC,EAAE,MAAM;IAC7B;;;;OAIG;aACa,OAAO,CAAC,EAAE,MAAM;IAXlC,YACkB,IAAI,EAAE,KAAK,EAC3B,OAAO,CAAC,EAAE,MAAM,EACA,MAAM,GAAE,MAAY,EACpB,OAAO,CAAC,EAAE,QAAQ,YAAA,EAClB,IAAI,CAAC,EAAE,MAAM,YAAA;IAC7B;;;;OAIG;IACa,OAAO,CAAC,EAAE,MAAM,YAAA,EAQjC;IAED,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,QAAQ,CAEvC;IAED,MAAM,IAAI,aAAa,CAStB;CACF;AAED,qCAAqC;AACrC,wBAAgB,QAAQ,CAAC,OAAO,SAAc,GAAG,KAAK,CAErD;AAED,6EAA6E;AAC7E,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,KAAK,CAEpF;AAED,wCAAwC;AACxC,wBAAgB,YAAY,CAAC,OAAO,SAAiB,GAAG,KAAK,CAE5D;AAED,qCAAqC;AACrC,wBAAgB,SAAS,CAAC,OAAO,SAAc,GAAG,KAAK,CAEtD;AAED,0EAA0E;AAC1E,wBAAgB,QAAQ,CAAC,OAAO,SAAa,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,KAAK,CAEvF;AAED,wCAAwC;AACxC,wBAAgB,WAAW,CAAC,OAAO,SAAsB,GAAG,KAAK,CAEhE;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;CA8BE,CAAC;AAEnC,mFAAmF;AACnF,MAAM,MAAM,eAAe,GAAG,MAAM,OAAO,mBAAmB,CAAC;AAE/D,iEAAiE;AACjE,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,eAAe,CAEvE;AAED,+FAA+F;AAC/F,wBAAgB,QAAQ,CACtB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,KAAK,CAOP"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/contract/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE;QACL,2CAA2C;QAC3C,IAAI,EAAE,MAAM,CAAC;QACb,8BAA8B;QAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,gCAAgC;QAChC,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,0BAA0B;QAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,CAAC;CACH;AAcD;;;;GAIG;AACH,qBAAa,QAAQ,CACnB,KAAK,SAAS,MAAM,GAAG,MAAM,EAC7B,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAC1F,SAAQ,KAAK;aAEK,IAAI,EAAE,KAAK;aAEX,MAAM,EAAE,MAAM;aACd,OAAO,CAAC,EAAE,QAAQ;aAClB,IAAI,CAAC,EAAE,MAAM;IAC7B;;;;OAIG;aACa,OAAO,CAAC,EAAE,MAAM;IAXlC,YACkB,IAAI,EAAE,KAAK,EAC3B,OAAO,CAAC,EAAE,MAAM,EACA,MAAM,GAAE,MAAY,EACpB,OAAO,CAAC,EAAE,QAAQ,YAAA,EAClB,IAAI,CAAC,EAAE,MAAM,YAAA;IAC7B;;;;OAIG;IACa,OAAO,CAAC,EAAE,MAAM,YAAA,EAQjC;IAED,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,QAAQ,CAEvC;IAED,MAAM,IAAI,aAAa,CAStB;CACF;AAED,qCAAqC;AACrC,wBAAgB,QAAQ,CAAC,OAAO,SAAc,GAAG,KAAK,CAErD;AAED,6EAA6E;AAC7E,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,KAAK,CAEpF;AAED,wCAAwC;AACxC,wBAAgB,YAAY,CAAC,OAAO,SAAiB,GAAG,KAAK,CAE5D;AAED,qCAAqC;AACrC,wBAAgB,SAAS,CAAC,OAAO,SAAc,GAAG,KAAK,CAEtD;AAED,0EAA0E;AAC1E,wBAAgB,QAAQ,CAAC,OAAO,SAAa,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,KAAK,CAEvF;AAED,wCAAwC;AACxC,wBAAgB,WAAW,CAAC,OAAO,SAAsB,GAAG,KAAK,CAEhE;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;CA+BE,CAAC;AAEnC,mFAAmF;AACnF,MAAM,MAAM,eAAe,GAAG,MAAM,OAAO,mBAAmB,CAAC;AAE/D,iEAAiE;AACjE,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,eAAe,CAEvE;AAED,+FAA+F;AAC/F,wBAAgB,QAAQ,CACtB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,KAAK,CAOP"}

package/dist/contract/index.js

@@ -18,7 +18,7 @@ import {
   paginatedSchema,
   rateLimited,
   unauthorized
-} from "../index-9h1vba8n.js";
+} from "../index-413xk7ga.js";
 import"../index-tss6bk5c.js";
 export {
   ALL_TRANSPORTS,

package/dist/{index-8pc5s3pz.js → index-1pgeyyee.js}

@@ -2,7 +2,7 @@ import {
   coerceJsonArgs,
   executeToolMethod,
   toolResultFromError
-} from "./index-2akar0rq.js";
+} from "./index-wrhf06ak.js";
 import {
   isWithinDir
 } from "./index-sbdmyz75.js";
@@ -24,11 +24,11 @@ import {
 import {
   formatZodError,
   validateDeclaredOutput
-} from "./index-6fbp58g8.js";
+} from "./index-tvwcrx2d.js";
 import {
   isUnsafeKey,
   safeJsonParse
-} from "./index-v6e8hnkx.js";
+} from "./index-wd8g8z6e.js";
 import {
   isRecord
 } from "./index-smpbdg6k.js";

package/dist/{index-9h1vba8n.js → index-413xk7ga.js}

@@ -285,6 +285,7 @@ var STITCH_ERROR_STATUS = {
   FILE_EXISTS: 409,
   REALTIME_CONTRACT_VIOLATION: 500,
   APPLICATION_NOT_ACCEPTING: 503,
+  GRAMMY_WEBHOOK_NOT_ACCEPTING: 503,
   WAIT_TIMEOUT: 408,
   WAIT_FAILED: 409,
   DOWNLOAD_NOT_FOUND: 404,
@@ -426,4 +427,4 @@ function decodeCursor(cursor, schema) {
     return null;
   }
 }
-export { parseTrailingWildcard, AppError, notFound, badRequest, unauthorized, forbidden, conflict, rateLimited, STITCH_ERROR_STATUS, isStitchErrorCode, appError, ALL_TRANSPORTS, defineContract, defineErrors, createContractFactory, ManagedFilePathSchema, ManagedFileRefSchema, paginatedSchema, encodeCursor, decodeCursor };
+export { parseTrailingWildcard, ALL_TRANSPORTS, defineContract, AppError, notFound, badRequest, unauthorized, forbidden, conflict, rateLimited, STITCH_ERROR_STATUS, isStitchErrorCode, appError, defineErrors, createContractFactory, ManagedFilePathSchema, ManagedFileRefSchema, paginatedSchema, encodeCursor, decodeCursor };

package/dist/{index-8es1hrv4.js → index-6taryy00.js}

@@ -1,6 +1,6 @@
 import {
   isUnsafeKey
-} from "./index-v6e8hnkx.js";
+} from "./index-wd8g8z6e.js";
 import {
   isRecord
 } from "./index-smpbdg6k.js";

package/dist/{index-1zencgcb.js → index-eabpd4tb.js}

@@ -6,6 +6,9 @@ import {
 import {
   ShutdownOptionsSchema
 } from "./index-dk6e56g0.js";
+import {
+  AppError
+} from "./index-xxye8j3k.js";
 
 // src/application/graph.ts
 function resolveResourceGraph(resources) {
@@ -72,11 +75,14 @@ var ApplicationShutdownOptionsSchema = ShutdownOptionsSchema.pick({
   forceTimeoutMs: true,
   signal: true
 });
+var ApplicationShutdownBudgetSchema = ShutdownOptionsSchema.pick({
+  gracePeriodMs: true,
+  forceTimeoutMs: true
+});
 
-class ApplicationAdmissionError extends Error {
-  code = "APPLICATION_NOT_ACCEPTING";
+class ApplicationAdmissionError extends AppError {
   constructor() {
-    super("Application is not accepting new operations");
+    super("APPLICATION_NOT_ACCEPTING", "Application is not accepting new operations", 503);
     this.name = "ApplicationAdmissionError";
   }
 }
@@ -98,6 +104,7 @@ async function untilDeadline(work, signal) {
 function createApplication(config) {
   const id = ApplicationIdSchema.parse(config.id);
   const ordered = resolveResourceGraph(config.resources ?? []);
+  const shutdownBudget = ApplicationShutdownBudgetSchema.parse(config.shutdown ?? {});
   const reverse = [...ordered].reverse();
   const reportFailure = (resourceId, phase, error) => {
     if (!config.onResourceFailure)
@@ -114,6 +121,8 @@ function createApplication(config) {
       entry,
       state: "registered",
       health: "unknown",
+      healthReported: false,
+      everHealthy: false,
       attempted: false,
       activated: false,
       closeInvoked: false,
@@ -201,6 +210,9 @@ function createApplication(config) {
       if (record.state === "stopped")
         return;
       record.health = health;
+      record.healthReported = true;
+      if (health === "healthy")
+        record.everHealthy = true;
       accepting = activationComplete && !shutdownRequested && isReady();
       publish();
     }
@@ -219,6 +231,22 @@ function createApplication(config) {
   };
   const closeAttempted = async () => {
     const errors = [];
+    const rollbackStartedAt = performance.now();
+    const rollbackDeadlineAt = rollbackStartedAt + shutdownBudget.gracePeriodMs;
+    const rollbackForceDeadlineAt = rollbackDeadlineAt + shutdownBudget.forceTimeoutMs;
+    const rollbackAbort = new AbortController;
+    const rollbackTimer = setTimeout(() => rollbackAbort.abort(), Math.max(0, rollbackForceDeadlineAt - performance.now()));
+    try {
+      await closeEachAttempted(rollbackAbort.signal, errors, {
+        deadlineAt: rollbackDeadlineAt,
+        forceDeadlineAt: rollbackForceDeadlineAt
+      });
+    } finally {
+      clearTimeout(rollbackTimer);
+    }
+    return errors;
+  };
+  const closeEachAttempted = async (bound, errors, deadlines) => {
     for (const entry of reverse) {
       const record = records.get(entry.id);
       if (!record?.attempted || record.closed)
@@ -226,7 +254,18 @@ function createApplication(config) {
       record.state = "stopping";
       try {
         record.closeInvoked = true;
-        await entry.resource.close?.(contextFor(record, { signal: startupAbort.signal }));
+        const settled = await untilDeadline(Promise.resolve(entry.resource.close?.(contextFor(record, { signal: startupAbort.signal, ...deadlines }))), bound);
+        if (!settled.settled) {
+          record.failures.push("close");
+          record.state = "failed";
+          const timedOut = new Error(`[stitchkit] resource "${entry.id}" did not finish closing during rollback`);
+          reportFailure(entry.id, "close", timedOut);
+          errors.push(timedOut);
+          publish();
+          break;
+        }
+        if (settled.error !== undefined)
+          throw settled.error;
         record.closed = true;
         record.state = "stopped";
       } catch (error) {
@@ -237,7 +276,6 @@ function createApplication(config) {
       }
       publish();
     }
-    return errors;
   };
   const runStart = async () => {
     lifecycle = "starting";
@@ -305,7 +343,10 @@ function createApplication(config) {
             throw new ApplicationStartupInterruptedError;
           }
           record.state = "ready";
-          record.health = "healthy";
+          if (!record.healthReported) {
+            record.health = "healthy";
+            record.everHealthy = true;
+          }
           publish();
         } catch (error) {
           const interrupted = shutdownRequested || startupAbort.signal.aborted;
@@ -350,7 +391,8 @@ function createApplication(config) {
           }
           record.activated = true;
           if (entry.required && (record.state !== "ready" || record.health !== "healthy")) {
-            throw new Error(`[stitchkit] required resource "${entry.id}" lost readiness during activation`);
+            const observed = `${record.state}/${record.health}`;
+            throw new Error(record.everHealthy ? `[stitchkit] required resource "${entry.id}" lost readiness during activation (${observed})` : `[stitchkit] required resource "${entry.id}" is not healthy (${observed}). A required resource must be healthy for the application to be ready; a resource that is expected to start degraded belongs behind \`required: false\`.`);
           }
         } catch (error) {
           const interrupted = shutdownRequested || startupAbort.signal.aborted;
@@ -369,7 +411,11 @@ function createApplication(config) {
         throw new ApplicationStartupInterruptedError;
       }
       if (!isReady()) {
-        throw new Error("[stitchkit] a required resource lost readiness during startup");
+        const blocking = [...records.values()].filter((record) => record.entry.required && (record.state !== "ready" || record.health !== "healthy")).map((record) => `${record.entry.id} (${record.state}/${record.health})`);
+        if (blocking.length === 0)
+          blocking.push("(none identified)");
+        const chosen = [...records.values()].some((record) => record.entry.required && record.health !== "healthy" && !record.everHealthy);
+        throw new Error(`[stitchkit] the application is not ready after startup — required ${blocking.length === 1 ? "resource" : "resources"} ${blocking.join(", ")}. A required resource must be healthy for the application to be ready; ${chosen ? "a resource that is expected to start degraded belongs behind `required: false`." : "this one was healthy and stopped being so — read `onResourceFailure` for the cause."}`);
       }
       activationComplete = true;
       accepting = isReady();
@@ -445,7 +491,12 @@ function createApplication(config) {
   const shutdown = (options) => {
     if (shutdownPromise)
       return shutdownPromise;
-    const parsed = ApplicationShutdownOptionsSchema.parse(options ?? {});
+    const requested = options ?? {};
+    const parsed = ApplicationShutdownOptionsSchema.parse({
+      gracePeriodMs: requested.gracePeriodMs ?? shutdownBudget.gracePeriodMs,
+      forceTimeoutMs: requested.forceTimeoutMs ?? shutdownBudget.forceTimeoutMs,
+      ...requested.signal !== undefined && { signal: requested.signal }
+    });
     const startedAt = performance.now();
     const graceDeadlineAt = startedAt + parsed.gracePeriodMs;
     const forceDeadlineAt = graceDeadlineAt + parsed.forceTimeoutMs;
@@ -648,4 +699,4 @@ function createApplication(config) {
   };
 }
 
-export { ApplicationShutdownOptionsSchema, ApplicationAdmissionError, createApplication };
+export { ApplicationShutdownOptionsSchema, ApplicationShutdownBudgetSchema, ApplicationAdmissionError, createApplication };

package/dist/{index-3w74r08v.js → index-mfw1pec7.js}

@@ -2,18 +2,20 @@ import {
   contextContributionDelta,
   mergeContextContribution,
   prepareContextContribution
-} from "./index-3hn10n4c.js";
+} from "./index-y91zd0ch.js";
 import {
   base64UrlToBytes,
   bytesToBase64Url,
-  forbidden,
   isUnsafeKey,
-  safeJsonParse,
-  unauthorized
-} from "./index-v6e8hnkx.js";
+  safeJsonParse
+} from "./index-wd8g8z6e.js";
 import {
   isRecord
 } from "./index-smpbdg6k.js";
+import {
+  forbidden,
+  unauthorized
+} from "./index-xxye8j3k.js";
 
 // src/server/middleware/cookies.ts
 function parseCookies(header) {

package/dist/{index-f7521k0x.js → index-s1tywej8.js}

@@ -7,7 +7,7 @@ import {
   defaultSignalSource,
   guardSignalCallback,
   reportSignalError
-} from "./index-3hn10n4c.js";
+} from "./index-y91zd0ch.js";
 import {
   ShutdownOptionsSchema
 } from "./index-dk6e56g0.js";
@@ -26,13 +26,11 @@ import {
   setRequestError,
   validateDeclaredOutput,
   zodIssues
-} from "./index-6fbp58g8.js";
+} from "./index-tvwcrx2d.js";
 import {
-  AppError,
-  badRequest,
   isUnsafeKey,
   safeJsonParse
-} from "./index-v6e8hnkx.js";
+} from "./index-wd8g8z6e.js";
 import {
   joinRoutePath,
   parseTrailingWildcard,
@@ -42,6 +40,10 @@ import {
   isRecord,
   transportResult
 } from "./index-smpbdg6k.js";
+import {
+  AppError,
+  badRequest
+} from "./index-xxye8j3k.js";
 
 // src/server/multipart.ts
 var DEFAULT_MAX_REQUEST_BYTES = 25 * 1024 * 1024;
@@ -1561,6 +1563,46 @@ function bindProcessSignals(handle, options = {}) {
   return { promise, close };
 }
 
+// src/realtime/rejected-frame.ts
+var REALTIME_REJECTION_KEY = "@stitchkit/realtime-rejected";
+var MAX_REJECTION_ISSUES = 20;
+function realtimeRejectionEnvelope(report) {
+  return { [REALTIME_REJECTION_KEY]: report };
+}
+function asRealtimeRejection(value) {
+  if (typeof value !== "object" || value === null)
+    return null;
+  const report = Reflect.get(value, REALTIME_REJECTION_KEY);
+  if (typeof report !== "object" || report === null)
+    return null;
+  const event = Reflect.get(report, "event");
+  const reason = Reflect.get(report, "reason");
+  const message = Reflect.get(report, "message");
+  if (typeof event !== "string" || typeof reason !== "string" || typeof message !== "string") {
+    return null;
+  }
+  if (reason.length === 0)
+    return null;
+  const issues = parseIssues(Reflect.get(report, "issues"));
+  return { event, reason, message, ...issues !== undefined && { issues } };
+}
+function parseIssues(value) {
+  if (!Array.isArray(value))
+    return;
+  const issues = [];
+  for (const entry of value.slice(0, MAX_REJECTION_ISSUES)) {
+    if (typeof entry !== "object" || entry === null)
+      continue;
+    const path = Reflect.get(entry, "path");
+    const code = Reflect.get(entry, "code");
+    const message = Reflect.get(entry, "message");
+    if (typeof path === "string" && typeof code === "string" && typeof message === "string") {
+      issues.push({ path, code, message });
+    }
+  }
+  return issues.length > 0 ? issues : undefined;
+}
+
 // src/realtime/rejection.ts
 import { z } from "zod";
 function realtimeContractViolation(options) {
@@ -1588,15 +1630,11 @@ function method(target, 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)
-  };
+  const trailing = args.at(-1);
+  const replyTo = typeof trailing === "function" ? (...callbackArgs) => Reflect.apply(trailing, undefined, callbackArgs) : undefined;
+  if (!definition.ack || !replyTo)
+    return { values: args, ...replyTo && { replyTo } };
+  return { values: args.slice(0, -1), acknowledgement: replyTo, replyTo };
 }
 function eventDefinition(registry, event, direction) {
   const definition = registry[event];
@@ -1624,6 +1662,19 @@ function reportRejected(rejected, hook, logger) {
     console.error("[stitchkit] realtime rejection hook failed", error);
   });
 }
+function answerWithRejection(acknowledgement, report, logger) {
+  if (!acknowledgement)
+    return;
+  try {
+    acknowledgement(realtimeRejectionEnvelope(report));
+  } catch (error) {
+    const message = "[stitchkit] could not answer a rejected realtime frame";
+    if (logger)
+      logger.warn(message, { error });
+    else
+      console.warn(message, error);
+  }
+}
 function createValidatedRealtimeSocket({
   target,
   inbound,
@@ -1639,17 +1690,24 @@ function createValidatedRealtimeSocket({
     on: (event, handler) => {
       const definition = eventDefinition(inbound, event, inboundDirection);
       const wrapped = (...wireArgs) => {
-        const { values, acknowledgement } = splitWireArguments(definition, wireArgs);
+        const { values, acknowledgement, replyTo } = splitWireArguments(definition, wireArgs);
         const parsed = definition.args.safeParse(values);
         if (!parsed.success) {
-          reportRejected(realtimeContractViolation({
+          const rejected = realtimeContractViolation({
             event,
             direction: inboundDirection,
             phase: "arguments",
             reason: "invalid-arguments",
             fault: "peer",
             cause: parsed.error
-          }), onRejected, logger);
+          });
+          reportRejected(rejected, onRejected, logger);
+          answerWithRejection(replyTo, {
+            event,
+            reason: "invalid-arguments",
+            message: rejected.error.message,
+            issues: zodIssues(parsed.error).slice(0, MAX_REJECTION_ISSUES)
+          }, logger);
           return;
         }
         if (definition.ack && !acknowledgement) {
@@ -1719,6 +1777,17 @@ function createValidatedRealtimeSocket({
       const wireArgs = [...parsed.data];
       if (definition.ack && acknowledgement) {
         wireArgs.push((value) => {
+          const refusal = asRealtimeRejection(value);
+          if (refusal) {
+            reportRejected(realtimeContractViolation({
+              event,
+              direction: outboundDirection,
+              phase: "arguments",
+              reason: "rejected-by-peer",
+              fault: "local"
+            }), onRejected, logger);
+            return;
+          }
           const ack = definition.ack?.safeParse(value);
           if (!ack?.success) {
             if (ack) {
@@ -1839,17 +1908,19 @@ function composeWebSocketHandlers(lanes, config) {
   };
 }
 
+// src/internal/optional-peer.ts
+function isModuleNotFound(error) {
+  if (typeof error !== "object" || error === null)
+    return false;
+  const code = "code" in error ? error.code : undefined;
+  const message = "message" in error && typeof error.message === "string" ? error.message : "";
+  return code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND" || message.includes("Cannot find module") || message.includes("Cannot find package");
+}
+
 // src/server/socket-io.ts
 var SOCKET_IO_SERVER = "socket.io";
 var SOCKET_IO_BUN_ENGINE = "@socket.io/bun-engine";
 var noop = () => {};
-function isModuleNotFound(err) {
-  if (typeof err !== "object" || err === null)
-    return false;
-  const code = "code" in err ? err.code : undefined;
-  const message = "message" in err && typeof err.message === "string" ? err.message : "";
-  return code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND" || message.includes("Cannot find module") || message.includes("Cannot find package");
-}
 async function importPeer(load, pkg, injected) {
   try {
     return await load();

package/dist/{index-6fbp58g8.js → index-tvwcrx2d.js}

@@ -1,13 +1,15 @@
 import {
-  AppError,
   isUnsafeKey
-} from "./index-v6e8hnkx.js";
+} from "./index-wd8g8z6e.js";
 import {
   resolveTraceContext
 } from "./index-pzyt11ch.js";
 import {
   isRecord
 } from "./index-smpbdg6k.js";
+import {
+  AppError
+} from "./index-xxye8j3k.js";
 
 // src/internal/errors.ts
 import { z } from "zod";

package/dist/{index-v6e8hnkx.js → index-wd8g8z6e.js}

@@ -2,89 +2,6 @@ import {
   parseTrailingWildcard
 } from "./index-pzyt11ch.js";
 
-// src/contract/errors.ts
-var APP_ERROR_BRAND = Symbol.for("stitchkit.AppError");
-
-class AppError extends Error {
-  code;
-  status;
-  details;
-  hint;
-  traceId;
-  constructor(code, message, status = 500, details, hint, traceId) {
-    super(message ?? code);
-    this.code = code;
-    this.status = status;
-    this.details = details;
-    this.hint = hint;
-    this.traceId = traceId;
-    this.name = "AppError";
-    Object.defineProperty(this, APP_ERROR_BRAND, { value: true });
-  }
-  static is(err) {
-    return typeof err === "object" && err !== null && APP_ERROR_BRAND in err;
-  }
-  toJSON() {
-    return {
-      error: {
-        code: this.code,
-        message: this.message,
-        ...this.details && { details: this.details },
-        ...this.hint && { hint: this.hint }
-      }
-    };
-  }
-}
-function notFound(message = "Not found") {
-  throw new AppError("NOT_FOUND", message, 404);
-}
-function badRequest(message, details) {
-  throw new AppError("BAD_REQUEST", message, 400, details);
-}
-function unauthorized(message = "Unauthorized") {
-  throw new AppError("UNAUTHORIZED", message, 401);
-}
-function forbidden(message = "Forbidden") {
-  throw new AppError("FORBIDDEN", message, 403);
-}
-function conflict(message = "Conflict", details) {
-  throw new AppError("CONFLICT", message, 409, details);
-}
-function rateLimited(message = "Too many requests") {
-  throw new AppError("RATE_LIMITED", message, 429);
-}
-var STITCH_ERROR_STATUS = {
-  BAD_REQUEST: 400,
-  UNAUTHORIZED: 401,
-  FORBIDDEN: 403,
-  NOT_FOUND: 404,
-  METHOD_NOT_ALLOWED: 405,
-  CONFLICT: 409,
-  RATE_LIMITED: 429,
-  VALIDATION_ERROR: 400,
-  FILE_INVALID_PATH: 400,
-  FILE_OUTSIDE_ROOT: 400,
-  FILE_NOT_FOUND: 404,
-  FILE_NOT_REGULAR: 422,
-  FILE_INSPECTION_REJECTED: 422,
-  FILE_TOO_LARGE: 413,
-  FILE_EXISTS: 409,
-  REALTIME_CONTRACT_VIOLATION: 500,
-  APPLICATION_NOT_ACCEPTING: 503,
-  WAIT_TIMEOUT: 408,
-  WAIT_FAILED: 409,
-  DOWNLOAD_NOT_FOUND: 404,
-  VIEW_HTTP_ERROR: 502,
-  OPERATION_NOT_SUCCEEDED: 409,
-  INTERNAL_SERVER_ERROR: 500
-};
-function isStitchErrorCode(code) {
-  return Object.hasOwn(STITCH_ERROR_STATUS, code);
-}
-function appError(code, message, details) {
-  throw new AppError(code, message, isStitchErrorCode(code) ? STITCH_ERROR_STATUS[code] : 500, details);
-}
-
 // src/contract/define.ts
 import { z } from "zod";
 
@@ -286,4 +203,4 @@ function base64UrlToBytes(segment) {
   const padded = b64.padEnd(Math.ceil(b64.length / 4) * 4, "=");
   return Uint8Array.from(atob(padded), (c) => c.charCodeAt(0));
 }
-export { isUnsafeKey, safeJsonParse, defineContract, mergeMeta, AppError, notFound, badRequest, unauthorized, forbidden, conflict, rateLimited, STITCH_ERROR_STATUS, isStitchErrorCode, appError, bytesToBase64Url, base64UrlToBytes };
+export { isUnsafeKey, safeJsonParse, defineContract, mergeMeta, bytesToBase64Url, base64UrlToBytes };

package/dist/{index-2akar0rq.js → index-wrhf06ak.js}

@@ -7,17 +7,19 @@ import {
   normalizeError,
   runWithRequestContext,
   validateDeclaredOutput
-} from "./index-6fbp58g8.js";
+} from "./index-tvwcrx2d.js";
 import {
-  AppError,
-  STITCH_ERROR_STATUS,
-  isStitchErrorCode,
   isUnsafeKey,
   safeJsonParse
-} from "./index-v6e8hnkx.js";
+} from "./index-wd8g8z6e.js";
 import {
   isRecord
 } from "./index-smpbdg6k.js";
+import {
+  AppError,
+  STITCH_ERROR_STATUS,
+  isStitchErrorCode
+} from "./index-xxye8j3k.js";
 
 // src/tools/coerce.ts
 import { z } from "zod";