refactor: Replace handleInternalMessage with mutually exclusive options

Replace the union type parameter with discriminated union options:
- `handler`: Direct handler function (for tests)
- `handlerPromise`: Promise-based handler (for async initialization)

This addresses the anti-pattern of accepting either a value or a promise
of that value, making the API more explicit and easier to understand.

Co-authored-by: Erik Marks <rekmarks@users.noreply.github.com>

Author: github-actions[bot]

packages/kernel-browser-runtime/src/internal-comms/internal-connections.test.ts

@@ -183,7 +183,7 @@ describe('internal-connections', () => {
 
     it('should handle new internal process connections', async () => {
       receiveInternalConnections({
-        handleInternalMessage: mockHandleMessage,
+        handler: mockHandleMessage,
         logger,
       });
 
@@ -208,7 +208,7 @@ describe('internal-connections', () => {
 
     it('should handle valid message', async () => {
       receiveInternalConnections({
-        handleInternalMessage: mockHandleMessage,
+        handler: mockHandleMessage,
         logger,
       });
 
@@ -257,7 +257,7 @@ describe('internal-connections', () => {
 
     it('should handle JSON-RPC notifications', async () => {
       receiveInternalConnections({
-        handleInternalMessage: mockHandleMessage,
+        handler: mockHandleMessage,
         logger,
       });
 
@@ -300,7 +300,7 @@ describe('internal-connections', () => {
 
     it('should handle multiple simultaneous connections', async () => {
       receiveInternalConnections({
-        handleInternalMessage: mockHandleMessage,
+        handler: mockHandleMessage,
         logger,
       });
 
@@ -335,7 +335,7 @@ describe('internal-connections', () => {
 
     it('should forget ids of closed channels', async () => {
       receiveInternalConnections({
-        handleInternalMessage: mockHandleMessage,
+        handler: mockHandleMessage,
         logger,
       });
       const controlChannel = MockBroadcastChannel.channels.get(
@@ -376,7 +376,7 @@ describe('internal-connections', () => {
 
     it('should reject duplicate connections', () => {
       receiveInternalConnections({
-        handleInternalMessage: mockHandleMessage,
+        handler: mockHandleMessage,
         logger,
       });
       const controlChannel = MockBroadcastChannel.channels.get(
@@ -401,7 +401,7 @@ describe('internal-connections', () => {
 
     it('should reject invalid control commands', () => {
       receiveInternalConnections({
-        handleInternalMessage: mockHandleMessage,
+        handler: mockHandleMessage,
         logger,
       });
       const controlChannel = MockBroadcastChannel.channels.get(
@@ -425,7 +425,7 @@ describe('internal-connections', () => {
 
     it('should handle comms channel message errors', async () => {
       receiveInternalConnections({
-        handleInternalMessage: mockHandleMessage,
+        handler: mockHandleMessage,
         logger,
       });
 

packages/kernel-browser-runtime/src/internal-comms/internal-connections.ts

@@ -102,39 +102,50 @@ const connectToInternalProcess = async (
   return stream;
 };
 
-type ReceiveConnectionsOptions = Omit<Options, 'label'> & {
-  handleInternalMessage: HandleInternalMessage | Promise<HandleInternalMessage>;
-};
+type ReceiveConnectionsOptions = Omit<Options, 'label'> &
+  (
+    | {
+        handler: HandleInternalMessage;
+        handlerPromise?: never;
+      }
+    | {
+        handler?: never;
+        handlerPromise: Promise<HandleInternalMessage>;
+      }
+  );
 
 /**
  * Listens for connections between the kernel and an internal process, e.g. a UI instance.
  * Should be called exactly once in the kernel, during initialization, before any internal
  * processes have attempted to connect.
  *
  * @param options - The options for the connection.
- * @param options.handleInternalMessage - The function to handle the internal message,
- * or a promise that resolves to such a function. If a promise is provided, messages will
- * be buffered until the handler is ready, then subsequent messages are handled directly.
+ * @param options.handler - The function to handle internal messages. Mutually exclusive
+ * with `handlerPromise`.
+ * @param options.handlerPromise - A promise that resolves to the handler function.
+ * Messages will be buffered until the handler is ready, then subsequent messages are
+ * handled directly. Mutually exclusive with `handler`.
  * @param options.logger - The logger instance.
  * @param options.controlChannelName - The name of the control channel. Must match
  * the name used by {@link connectToKernel} on the other end.
  */
 export const receiveInternalConnections = ({
-  handleInternalMessage,
+  handler: directHandler,
+  handlerPromise,
   logger,
   controlChannelName = COMMS_CONTROL_CHANNEL_NAME,
 }: ReceiveConnectionsOptions): void => {
   // Support both direct handler and promise-based handler
   let handler: HandleInternalMessage | null = null;
   let handlerReady: Promise<HandleInternalMessage>;
 
-  if (typeof handleInternalMessage === 'function') {
+  if (directHandler !== undefined) {
     // Direct handler - use immediately
-    handler = handleInternalMessage;
-    handlerReady = Promise.resolve(handleInternalMessage);
+    handler = directHandler;
+    handlerReady = Promise.resolve(directHandler);
   } else {
     // Promise-based handler - cache once resolved
-    handlerReady = handleInternalMessage.then((resolvedHandler) => {
+    handlerReady = handlerPromise.then((resolvedHandler) => {
       handler = resolvedHandler;
       return resolvedHandler;
     });

packages/kernel-browser-runtime/src/kernel-worker/kernel-worker.ts

@@ -65,7 +65,7 @@ async function main(): Promise<void> {
   });
 
   receiveInternalConnections({
-    handleInternalMessage: handlerP,
+    handlerPromise: handlerP,
     logger,
   });