diff --git a/packages/core-shared/src/trpc/define-error-middleware.ts b/packages/core-shared/src/trpc/define-error-middleware.ts
index a9ef641..681b596 100644
--- a/packages/core-shared/src/trpc/define-error-middleware.ts
+++ b/packages/core-shared/src/trpc/define-error-middleware.ts
@@ -7,11 +7,16 @@ type ErrorCtor = new (...args: never[]) => Error;
 /**
  * Build a tRPC middleware that translates domain errors to TRPCError.
  *
- * Each tuple pairs a constructor with a TRPC error code. The middleware
- * runs the procedure body inside a try/catch; on `instanceof Ctor`,
- * it throws a TRPCError with the configured code and the original error
- * preserved as `.cause`. Unmapped errors propagate untouched (tRPC's
- * default INTERNAL_SERVER_ERROR handling applies).
+ * Each tuple pairs a constructor with a TRPC error code. tRPC v11
+ * middleware sees procedure throws as a returned `result` (not an
+ * exception): `next()` resolves to `{ ok: false, error: TRPCError }`
+ * where `error.cause` is the original domain error wrapped by
+ * `getTRPCErrorFromUnknown`. The middleware checks `result.ok`,
+ * matches `result.error.cause` against each `instanceof Ctor`, and
+ * on a hit throws a fresh TRPCError with the configured code and the
+ * original error preserved as `.cause`. Unmapped errors fall through
+ * unchanged — tRPC's default INTERNAL_SERVER_ERROR wrapping applies
+ * with the original error still reachable via `.cause`.
  *
  * Owned by features: each feature passes its own constructors in.
  * core-shared never enumerates feature-specific error classes.