anear-js-api 2.0.1 → 2.2.0

package/lib/state_machines/AnearParticipantMachine.js

@@ -1,765 +0,0 @@
-"use strict"
-/**
- * AnearParticipantMachine (APM)
- *
- * One AnearParticipantMachine instance is created per participant in a given
- * Anear Event. It is owned by the AnearEventMachine (AEM) and represents the
- * server-side lifecycle and realtime plumbing for a single participant.
- *
- * High-level responsibilities:
- *
- *  - Manage the participant’s event-scoped private Ably channel:
- *      - Creates and attaches to a participant-specific private channel
- *        (e.g. for per-player UI updates, prompts, and boot/shutdown messages).
- *      - Publishes PRIVATE_DISPLAY / FORCE_SHUTDOWN payloads to the client.
- *
- *  - Bridge between the AnearEventMachine and the app’s optional
- *    appParticipantMachine:
- *      - Receives ACTION / display-related events and presence events from the AEM.
- *      - Forwards ACTION and timeout signals into the appParticipantMachine
- *        when present, so the app can implement per-participant logic.
- *      - Notifies the AEM when this participant’s machine has completed
- *        (PARTICIPANT_MACHINE_EXIT).
- *
- *  - Enforce participant-level timeouts and activity rules:
- *      - Action timeouts:
- *          - After a RENDER_DISPLAY that expects input,
- *            starts a per-participant response timer.
- *          - If the timer fires before an ACTION arrives, emits PARTICIPANT_TIMEOUT
- *            back to the AEM and the appParticipantMachine.
- *      - Disconnect / reconnect:
- *          - On PARTICIPANT_DISCONNECT, enters a reconnect-grace window.
- *          - If the participant reconnects (PARTICIPANT_RECONNECT) in time,
- *            resumes either idle or the pending response state.
- *          - If not, either times out the current turn or exits the participant
- *            from the event.
- *      - Idle / cleanup:
- *          - Tracks lastSeen and can be used by the AEM/app logic to remove
- *            idle/non-responsive participants and keep the event “clean”.
- *
- *  - Handle participant exit / removal:
- *      - PARTICIPANT_EXIT:
- *          - Voluntary exit from the participant (e.g. closing the app, leaving).
- *          - Drives cleanup of the private channel and transitions to a final state.
- *      - BOOT_PARTICIPANT:
- *          - Involuntary removal (e.g. host kicks the player).
- *          - Publishes a shutdown/boot message and then proceeds to cleanup.
- *
- * Relationship to other Anear components:
- *
- *  - AnearEventMachine (AEM):
- *      - The AEM creates one APM per participant and passes:
- *          - `anearEvent`       → the parent event/state machine actor
- *          - `anearParticipant` → the participant model (ids, privateChannelName, etc.)
- *          - `appParticipantMachineFactory` (optional)
- *      - APM reports its termination back to the AEM via
- *        `PARTICIPANT_MACHINE_EXIT` so the AEM can clean up references.
- *
- *  - App-level participant state machine (appParticipantMachine):
- *      - Created only if `appParticipantMachineFactory` is provided.
- *      - Encapsulates app-specific per-participant state (roles, inventory,
- *        per-player storyline, etc.)
- *      - The APM routes ACTION and timeout-related events into this machine so
- *        the app developer can implement custom behavior without worrying about
- *        Ably wiring or lifecycle plumbing.
- *
- * Incoming events (from AEM / system) – high level:
- *  - RENDER_DISPLAY:
- *      - Prompt the participant with a new view or interaction on their private channel.
- *      - Optionally include an action timeout; APM transitions into a wait state.
- *
- *  - ACTION:
- *      - Participant’s response to a prompt (button click, answer, move, etc.).
- *      - APM clears any pending timeout, updates `lastSeen`, and forwards the event
- *        into the appParticipantMachine (if defined).
- *
- *  - PARTICIPANT_DISCONNECT / PARTICIPANT_RECONNECT:
- *      - Presence events indicating temporary loss or restoration of connection.
- *      - APM pauses/resumes any active action timeout and decides whether to
- *        time out the participant or allow them to continue.
- *
- *  - PARTICIPANT_EXIT / BOOT_PARTICIPANT:
- *      - Signals that the participant is done with the event (voluntarily or not).
- *      - Triggers cleanup, private channel detach, and notification back to the AEM.
- *
- * Lifecycle (condensed):
- *  1. APM is created by the AEM for a specific participant.
- *  2. It creates and attaches to the participant’s private Ably channel, then
- *     signals PARTICIPANT_MACHINE_READY back to the AEM.
- *  3. It enters the live state, handling:
- *       - RENDER_DISPLAY → publish UI, optionally start timeout.
- *       - ACTION → forward to appParticipantMachine, clear timeout, go idle.
- *       - DISCONNECT / RECONNECT → manage reconnect windows and possible timeouts.
- *       - EXIT / BOOT → send shutdown messaging and clean up.
- *  4. On final cleanup, it detaches from the private channel and notifies the AEM
- *     via PARTICIPANT_MACHINE_EXIT, then ignores any further incoming events.
- */
-const logger = require('../utils/Logger')
-const { assign, createMachine, createActor, fromPromise } = require('xstate')
-const C = require('../utils/Constants')
-
-const RealtimeMessaging = require('../utils/RealtimeMessaging')
-const EventStats = require('../utils/EventStats')
-
-const CurrentDateTimestamp = _ => new Date().getTime()
-
-const AnearParticipantMachineContext = (anearParticipant, anearEvent, appParticipantMachineFactory, eventStats = null) => ({
-  anearEvent,
-  anearParticipant,
-  privateChannel: null,
-  appParticipantMachineFactory,
-  appParticipantMachine: null,
-  actionTimeoutMsecs: null,
-  actionTimeoutStart: null,
-  capturedTimeoutMsecs: null, // Captured timeout value for logging before clearing
-  // If the AppM emits rapid successive RENDER_DISPLAY events (e.g. dealing animation),
-  // a participant may still be in the middle of publishing the prior PRIVATE_DISPLAY.
-  // Without buffering, any new RENDER_DISPLAY arriving while in `live.renderDisplay`
-  // would be dropped (no handler in that state). We keep the latest and flush it
-  // immediately after the current publish completes.
-  queuedRenderDisplay: null,
-  lastSeen: CurrentDateTimestamp(),
-  eventStats // AEM-only metering; optional for EventStats.recordPublish before publish
-})
-
-const AnearParticipantMachineConfig = participantId => ({
-  id: `AnearParticipantMachine_${participantId}`,
-  initial: 'active',
-  states: {
-    active: {
-      id: 'active',
-      initial: 'setup',
-      states: {
-        setup: {
-          id: 'setup',
-          initial: 'setupPrivateChannel',
-          states: {
-            setupPrivateChannel: {
-              entry: ['createPrivateChannel'],
-              invoke: {
-                src: 'attachToPrivateChannel',
-                input: ({ context, event }) => ({ context, event }),
-                onDone: {
-                  target: '.',
-                  // v5 note: internal transitions are the default (v4 had `internal: true`)
-                },
-                onError: {
-                  target: '#error'
-                }
-              },
-              on: {
-                ATTACHED: {
-                  actions: [
-                    'logAttached',
-                    'sendParticipantReady'
-                  ],
-                  target: '#setupAppMachine'
-                }
-              }
-            },
-            setupAppMachine: {
-              id: 'setupAppMachine',
-              entry: 'createAnyAppParticipantMachine',
-              always: '#live'
-            }
-          }
-        },
-        live: {
-          id: 'live',
-          entry: 'logLive',
-          initial: 'idle',
-          states: {
-            idle: {
-              entry: ['ensureTimerCleared'],
-              on: {
-                RENDER_DISPLAY: {
-                  target: '#renderDisplay'
-                },
-                CANCEL_TIMEOUT: {
-                  // Acknowledge CANCEL_TIMEOUT even when idle (no active timer).
-                  // This ensures the AEM's cancellation sequence completes for all participants.
-                  actions: ['sendTimerCanceled'],
-                  // v5 note: internal transitions are the default (v4 had `internal: true`)
-                },
-                PARTICIPANT_DISCONNECT: {
-                  target: 'waitReconnect'
-                },
-                PARTICIPANT_EXIT: {
-                  actions: 'logExit',
-                  target: '#cleanupAndExit'
-                },
-                PARTICIPANT_RECONNECT: {
-                  actions: 'logReconnected',
-                  // v5 note: internal transitions are the default (v4 had `internal: true`)
-                },
-                BOOT_PARTICIPANT: {
-                  actions: 'logBooted',
-                  target: '#cleanupAndExit'
-                }
-              }
-            },
-            waitReconnect: {
-              entry: 'logDisconnected',
-              after: {
-                dynamicReconnectTimeout: [
-                  {
-                    guard: 'wasMidTurnOnDisconnect',
-                    actions: 'logActionTimeoutWhileDisconnected',
-                    target: '#participantTimedOut'
-                  },
-                  {
-                    actions: 'logNeverReconnected',
-                    target: '#cleanupAndExit'
-                  }
-                ]
-              },
-              on: {
-                // Even while we're waiting for a reconnect, the AppM may
-                // re-trigger a display (e.g. a refreshed PlayableGameBoard).
-                // In that case, re-publish the view but keep the timeout
-                // semantics governed by the stored remaining time.
-                RENDER_DISPLAY: {
-                  target: '#renderDisplay'
-                },
-                PARTICIPANT_EXIT: {
-                  target: '#cleanupAndExit'
-                },
-                PARTICIPANT_RECONNECT: [
-                  {
-                    guard: 'wasMidTurnOnDisconnect',
-                    actions: 'logReconnected',
-                    target: 'waitParticipantResponse'
-                  },
-                  {
-                    actions: 'logReconnected',
-                    target: 'idle'
-                  }
-                ]
-              }
-            },
-            renderDisplay: {
-              id: 'renderDisplay',
-              invoke: {
-                src: 'publishPrivateDisplay',
-                input: ({ context, event }) => ({ context, event }),
-                onDone: [
-                  { guard: 'hasActionTimeout', actions: ['updateActionTimeout', 'sendQueuedRenderDisplayIfAny', 'clearQueuedRenderDisplay'], target: 'waitParticipantResponse' },
-                  // If this display does not configure a timeout, explicitly clear any
-                  // previously-running action timeout.
-                  { actions: ['nullActionTimeout', 'sendQueuedRenderDisplayIfAny', 'clearQueuedRenderDisplay'], target: 'idle' }
-                ],
-                onError: {
-                  target: '#error'
-                }
-              },
-              on: {
-                // Buffer the latest render request if we are currently publishing.
-                // (Otherwise, RENDER_DISPLAY is unhandled in this state and gets dropped.)
-                RENDER_DISPLAY: [
-                  {
-                    // If a display arrives while we're already publishing another display,
-                    // it's safe to buffer *visual-only* refreshes (no timeout). However,
-                    // buffering timed prompts can create timer/UI mismatches and indicates
-                    // an AppM/AEM sequencing bug.
-                    guard: 'incomingRenderHasTimeout',
-                    actions: 'logBlockedRenderDuringPublish'
-                  },
-                  {
-                    actions: 'queueRenderDisplay'
-                  }
-                ],
-                PARTICIPANT_EXIT: {
-                  actions: 'logExit',
-                  target: '#cleanupAndExit'
-                }
-              }
-            },
-            waitParticipantResponse: {
-              entry: 'logWaitParticipantResponseEntry',
-              always: {
-                guard: 'isTimeoutImmediate',
-                actions: 'logImmediateTimeout',
-                target: '#participantTimedOut'
-              },
-              after: {
-                // Note: This timer continues running even when in nested .rendering state.
-                // XState v5 handles this correctly - the timer fires from the parent state
-                // and can transition even during invoke processing.
-                actionTimeout: {
-                  actions: ['captureTimeoutForLogging', 'nullActionTimeout'],
-                  target: '#participantTimedOut'
-                }
-              },
-              initial: 'waiting',
-              states: {
-                waiting: {
-                  // Actual waiting state. RENDER_DISPLAY (including refreshes with timeout) is
-                  // allowed; updateActionTimeoutIfChanged / timer logic handles stop/reset.
-                },
-                rendering: {
-                  // Refreshes (e.g. PARTICIPANT_DISCONNECT/RECONNECT) are processed here while
-                  // the parent's `after: actionTimeout` timer continues running.
-                  invoke: {
-                    src: 'publishPrivateDisplay',
-                    input: ({ context, event }) => ({ context, event }),
-                    onDone: [
-                      {
-                        guard: 'hasActionTimeout',
-                        actions: 'updateActionTimeoutIfChanged',
-                        target: 'waiting'
-                      },
-                      {
-                        target: 'waiting'
-                      }
-                    ],
-                    onError: {
-                      target: '#error'
-                    }
-                  },
-                  on: {
-                    PARTICIPANT_EXIT: {
-                      actions: 'logExit',
-                      target: '#cleanupAndExit'
-                    }
-                  }
-                }
-              },
-              on: {
-                // Allow all RENDER_DISPLAY (refreshes, timeouts). Timer logic stops/resets as needed.
-                RENDER_DISPLAY: {
-                  target: '.rendering'
-                },
-                PARTICIPANT_EXIT: {
-                  actions: 'logExit',
-                  target: '#cleanupAndExit'
-                },
-                ACTION: {
-                  actions: [
-                    'updateLastSeen',
-                    'sendActionToAppParticipantMachine',
-                    'nullActionTimeout'
-                  ],
-                  target: 'idle'
-                },
-                CANCEL_TIMEOUT: {
-                  // Cancel the active timeout and transition to idle. This is used
-                  // when the AppM wants to immediately cancel all participant timeouts
-                  // (e.g., when a LIAR call interrupts the wait state).
-                  // Always send TIMER_CANCELED to acknowledge, even if no timer was active.
-                  actions: ['nullActionTimeout', 'sendTimerCanceled'],
-                  target: 'idle'
-                },
-                PARTICIPANT_DISCONNECT: {
-                  actions: 'updateRemainingTimeoutOnDisconnect',
-                  target: 'waitReconnect'
-                },
-                PARTICIPANT_RECONNECT: {
-                  actions: 'logReconnected',
-                  // v5 note: internal transitions are the default (v4 had `internal: true`)
-                }
-              }
-            },
-            participantTimedOut: {
-              id: 'participantTimedOut',
-              entry: ['logParticipantTimedOut', 'sendTimeoutEvents'],
-              always: 'idle'
-            },
-            cleanupAndExit: {
-              id: 'cleanupAndExit',
-              entry: 'nullActionTimeout',
-              // Ignore most events during cleanup, but allow exit displays
-              on: {
-                RENDER_DISPLAY: { actions: 'logIgnoringRenderDisplayCleanup' },
-                PARTICIPANT_EXIT: {
-                  actions: 'logIgnoringRedundantExit'
-                },
-                PARTICIPANT_RECONNECT: {
-                  actions: 'logIgnoringReconnectCleanup'
-                },
-                ACTION: {
-                  actions: 'logIgnoringActionCleanup'
-                }
-              },
-              invoke: {
-                src: 'detachPrivateChannel',
-                input: ({ context, event }) => ({ context, event }),
-                onDone: {
-                  actions: assign(() => ({
-                    privateChannel: null
-                  })),
-                  target: '#done'
-                },
-                onError: {
-                  target: '#error'
-                }
-              }
-            },
-            booting: {
-              initial: 'publishingShutdown',
-              states: {
-                publishingShutdown: {
-                  invoke: {
-                    id: 'publishBootMessage',
-                    src: 'publishBootMessageService',
-                    input: ({ context, event }) => ({ context, event }),
-                    onDone: 'waitingForClientExit',
-                    onError: '#cleanupAndExit'
-                  }
-                },
-                waitingForClientExit: {
-                  after: {
-                    bootCleanupTimeout: {
-                      target: '#cleanupAndExit'
-                    }
-                  },
-                  on: {
-                    PARTICIPANT_EXIT: '#cleanupAndExit',
-                    ACTION: {
-                      // v5 note: internal transitions are the default (v4 had `internal: true`)
-                    },
-                    PARTICIPANT_DISCONNECT: {
-                      // v5 note: internal transitions are the default (v4 had `internal: true`)
-                    }
-                  }
-                }
-              }
-            },
-            done: {
-              id: 'done',
-              entry: ['notifyEventMachineExit'],
-              // Final state - ignore all events except exit displays
-              on: {
-                RENDER_DISPLAY: { actions: 'logIgnoringRenderDisplayDone' },
-                '*': {
-                  actions: 'logIgnoringEventDone'
-                }
-              },
-              type: 'final'
-            }
-          } // end live states
-        } // end live
-      } // end active states
-    },
-    error: {
-      id: 'error',
-      entry: ['logErrorDetails', 'notifyEventMachineExit'],
-      type: 'final'
-    }
-  }
-})
-
-const AnearParticipantMachineFunctions = {
-  actions: {
-    createPrivateChannel: assign(({ context, self }) => {
-      const privateChannel = RealtimeMessaging.getChannel(
-        context.anearParticipant.privateChannelName,
-        self
-      )
-      return { privateChannel }
-    }),
-    sendParticipantReady: ({ context }) => {
-      context.anearEvent.send({
-        type: 'PARTICIPANT_MACHINE_READY',
-        data: { anearParticipant: context.anearParticipant }
-      })
-    },
-    createAnyAppParticipantMachine: assign({
-      appParticipantMachine: ({ context }) => {
-        if (!context.appParticipantMachineFactory) return null
-
-        const machineToStart = context.appParticipantMachineFactory(context.anearParticipant)
-        const actor = createActor(machineToStart)
-        actor.start()
-        return actor
-      }
-    }),
-    captureTimeoutForLogging: assign(({ context }) => {
-      // Capture timeout value before it's cleared by nullActionTimeout
-      return {
-        capturedTimeoutMsecs: context.actionTimeoutMsecs
-      }
-    }),
-    sendTimeoutEvents: ({ context }) => {
-      const timeoutMsecs = context.capturedTimeoutMsecs ?? context.actionTimeoutMsecs ?? 'unknown'
-      logger.info(`[APM] Timer expired participantId=${context.anearParticipant.id} timeout=${timeoutMsecs}ms, sending PARTICIPANT_TIMEOUT to AEM`)
-      // AEM currently expects `event.participantId` (not nested under `data`).
-      context.anearEvent.send({
-        type: 'PARTICIPANT_TIMEOUT',
-        participantId: context.anearParticipant.id
-      })
-      if (context.appParticipantMachine) context.appParticipantMachine.send({ type: 'PARTICIPANT_TIMEOUT' })
-    },
-    sendTimerCanceled: ({ context }) => {
-      logger.debug(`[APM] Sending TIMER_CANCELED to AEM for ${context.anearParticipant.id}`)
-      context.anearEvent.send({
-        type: 'TIMER_CANCELED',
-        participantId: context.anearParticipant.id
-      })
-    },
-    sendActionToAppParticipantMachine: ({ context, event }) => {
-      if (context.appParticipantMachine) context.appParticipantMachine.send(event)
-    },
-    updateLastSeen: assign({
-      lastSeen: (_args) => CurrentDateTimestamp()
-    }),
-    updateActionTimeout: assign(({ context, event }) => {
-      const timeoutFromEvent = event?.output?.timeout ?? event?.data?.timeout
-      const now = CurrentDateTimestamp()
-
-      // Start a new timer. This is only called when transitioning from idle to waitParticipantResponse.
-      // When RENDER_DISPLAY arrives during waitParticipantResponse, we transition to the nested
-      // .rendering state, which preserves the parent's after: timer (no resume needed).
-      const existingMsecs = context.actionTimeoutMsecs
-      const existingStart = context.actionTimeoutStart
-      if (existingMsecs != null || existingStart != null) {
-        logger.debug(`[APM] WARNING: Starting new timer for ${context.anearParticipant.id} but existing timer state found: msecs=${existingMsecs}, start=${existingStart}`)
-      }
-      logger.info(`[APM] Timer started participantId=${context.anearParticipant.id} timeout=${timeoutFromEvent}ms`)
-      return {
-        actionTimeoutMsecs: timeoutFromEvent,
-        actionTimeoutStart: now
-      }
-    }),
-    updateActionTimeoutIfChanged: assign(({ context, event }) => {
-      const timeoutFromEvent = event?.output?.timeout ?? event?.data?.timeout
-      const now = CurrentDateTimestamp()
-
-      // When RENDER_DISPLAY arrives during waitParticipantResponse, check if the timeout has changed.
-      // If it has, update the timer. This handles state transitions where a new timeout is needed.
-      const existingMsecs = context.actionTimeoutMsecs
-      const existingStart = context.actionTimeoutStart
-
-      if (timeoutFromEvent == null || timeoutFromEvent <= 0) {
-        // New display has no timeout - preserve existing timer (this is a visual status update)
-        // Don't clear it, as we're still waiting for the original ACTION
-        logger.debug(`[APM] Preserving existing timer for ${context.anearParticipant.id} (new display has no timeout, visual status update)`)
-        return {}
-      }
-
-      // If we already have an active timer and receive a new timeout, this is a bug (detected above).
-      // Preserve the existing timer to avoid conflicts. The AppM should cancel timers first.
-      if (existingMsecs != null && existingStart != null) {
-        logger.warn(`[APM] AppM BUG: Received timeout=${timeoutFromEvent}ms while timer already active (${existingMsecs}ms) for ${context.anearParticipant.id}. Preserving existing timer. AppM should cancel timers first.`)
-        return {}
-      }
-
-      // No existing timer - start a new one (shouldn't happen in waitParticipantResponse, but handle gracefully)
-      logger.info(`[APM] Timer started participantId=${context.anearParticipant.id} timeout=${timeoutFromEvent}ms`)
-      return {
-        actionTimeoutMsecs: timeoutFromEvent,
-        actionTimeoutStart: now
-      }
-    }),
-    nullActionTimeout: assign(({ context }) => {
-      if (context.actionTimeoutMsecs != null || context.actionTimeoutStart != null) {
-        logger.debug(`[APM] Cancelling timer for ${context.anearParticipant.id} (ACTION received or timeout cleared)`)
-      }
-      return {
-        actionTimeoutMsecs: null,
-        actionTimeoutStart: null
-      }
-    }),
-    ensureTimerCleared: assign(({ context }) => {
-      // Defensive: Ensure timer state is cleared when entering idle state.
-      // This prevents stale timer state from affecting new displays, especially
-      // if a RENDER_DISPLAY arrives before timeout cleanup completes.
-      if (context.actionTimeoutMsecs != null || context.actionTimeoutStart != null) {
-        logger.debug(`[APM] Clearing stale timer state for ${context.anearParticipant.id} on idle entry (msecs=${context.actionTimeoutMsecs}, start=${context.actionTimeoutStart})`)
-        return {
-          actionTimeoutMsecs: null,
-          actionTimeoutStart: null
-        }
-      }
-      return {}
-    }),
-    updateRemainingTimeoutOnDisconnect: assign(({ context }) => {
-      if (context.actionTimeoutStart) {
-        const now = CurrentDateTimestamp()
-        const elapsed = now - context.actionTimeoutStart
-        const remaining = context.actionTimeoutMsecs - elapsed
-        const remainingMsecs = remaining > 0 ? remaining : 0
-        logger.debug(`[APM] Participant disconnected mid-turn. Storing remaining timeout of ${remainingMsecs}ms`)
-        return {
-          actionTimeoutMsecs: remainingMsecs,
-          // Reset the start baseline to "now" so that subsequent resumptions
-          // measure elapsed time from the disconnect point forward.
-          actionTimeoutStart: now
-        }
-      }
-      return {}
-    }),
-    notifyEventMachineExit: ({ context }) => {
-      // AEM cleanup currently expects `event.participantId` (not nested under `data`).
-      context.anearEvent.send({
-        type: 'PARTICIPANT_MACHINE_EXIT',
-        participantId: context.anearParticipant.id
-      })
-    },
-    logErrorDetails: ({ event }) => {
-      // Log the entire error object.
-      const err = event?.error ?? event?.data
-      if (err && err.stack) {
-        logger.error("Stack trace:", err.stack);
-      } else {
-        logger.error("Error details:", err);
-      }
-    },
-    logAttached: ({ context }) => logger.debug(`[APM] Got ATTACHED for privateChannel for ${context.anearParticipant.id}`),
-    logLive: ({ context }) => logger.debug(`[APM] Participant ${context.anearParticipant.id} is LIVE!`),
-    logWaitParticipantResponseEntry: ({ context }) => logger.debug(`[APM] ENTERING waitParticipantResponse state for ${context.anearParticipant.id} - timer will be (re)started if context provides timeout`),
-    logParticipantTimedOut: ({ context }) => logger.debug(`[APM] ENTERING participantTimedOut state for ${context.anearParticipant.id} - timeout occurred, clearing timer and sending PARTICIPANT_TIMEOUT`),
-    logExit: (_args) => logger.debug('[APM] got PARTICIPANT_EXIT. Exiting...'),
-    logDisconnected: ({ context }) => logger.info(`[APM] Participant ${context.anearParticipant.id} has DISCONNECTED`),
-    logActionTimeoutWhileDisconnected: ({ context }) => logger.info(`[APM] Participant ${context.anearParticipant.id} timed out on action while disconnected.`),
-    logNeverReconnected: ({ context }) => logger.info(`[APM] Participant ${context.anearParticipant.id} never RECONNECTED. Exiting.`),
-    logReconnected: ({ context }) => logger.info(`[APM] Participant ${context.anearParticipant.id} has RECONNECTED`),
-    logImmediateTimeout: ({ context }) => logger.debug(`[APM] Timeout of ${context.actionTimeoutMsecs}ms is immediate for ${context.anearParticipant.id}.`),
-    logIgnoringRenderDisplayCleanup: (_args) => logger.debug('[APM] ignoring RENDER_DISPLAY during cleanup'),
-    logIgnoringRedundantExit: () => logger.debug('[APM] ignoring redundant PARTICIPIPANT_EXIT during cleanup'),
-    logIgnoringReconnectCleanup: () => logger.debug('[APM] ignoring PARTICIPANT_RECONNECT during cleanup - already timed out'),
-    logIgnoringActionCleanup: () => logger.debug('[APM] ignoring ACTION during cleanup'),
-    logIgnoringRenderDisplayDone: () => logger.debug('[APM] ignoring RENDER_DISPLAY in final state'),
-    logIgnoringEventDone: ({ event }) => logger.debug('[APM] ignoring event in final state: ', event.type),
-    logBlockedRenderDuringPublish: ({ context, event }) => {
-      const participantId = context?.anearParticipant?.id
-      const timeout = event?.timeout ?? event?.data?.timeout
-      logger.error(
-        `[APM] ⚠️  BLOCKED: RENDER_DISPLAY (timeout=${timeout}ms) received while already publishing PRIVATE_DISPLAY for participant ${participantId}. ` +
-        `This indicates an AppM/AEM sequencing bug (timed prompts must not overlap in publish).`,
-      )
-    }
-    ,
-    queueRenderDisplay: assign(({ context, event }) => {
-      // Keep only the latest queued render display.
-      // Event shape is already { type: 'RENDER_DISPLAY', content, timeout? }.
-      const participantId = context?.anearParticipant?.id
-      const replaced = !!context?.queuedRenderDisplay
-      logger.debug(`[APM] queueing RENDER_DISPLAY for ${participantId}${replaced ? ' (replacing prior queued render)' : ''}`)
-      return { queuedRenderDisplay: event }
-    }),
-    sendQueuedRenderDisplayIfAny: ({ context, self }) => {
-      const queued = context.queuedRenderDisplay
-      if (queued && queued.type === 'RENDER_DISPLAY') {
-        const participantId = context?.anearParticipant?.id
-        logger.debug(`[APM] flushing queued RENDER_DISPLAY for ${participantId}`)
-        try {
-          self.send(queued)
-        } catch (_e) {
-          // Best-effort; never interrupt the publish completion path.
-        }
-      }
-    },
-    clearQueuedRenderDisplay: assign(() => ({ queuedRenderDisplay: null }))
-  },
-  actors: {
-    publishPrivateDisplay: fromPromise(async ({ input }) => {
-      const { context, event } = input
-      let displayMessage
-      if (event.targets != null && typeof event.targets === 'object' && !Array.isArray(event.targets)) {
-        displayMessage = { targets: event.targets }
-      } else if (event.anchor != null && event.content !== undefined) {
-        const val = (event.type === 'replace' || event.type === 'append')
-          ? { content: event.content, type: event.type }
-          : event.content
-        displayMessage = { targets: { [event.anchor]: val } }
-      } else {
-        displayMessage = { content: event.content }
-      }
-      if (event.timeout != null) {
-        displayMessage.timeout = event.timeout
-      }
-      EventStats.recordPublish(context.eventStats, context.privateChannel, 'PRIVATE_DISPLAY', displayMessage)
-      await RealtimeMessaging.publish(context.privateChannel, 'PRIVATE_DISPLAY', displayMessage)
-      return { timeout: event.timeout }
-    }),
-    publishBootMessageService: fromPromise(async ({ input }) => {
-      const { context, event } = input
-      const { reason } = event.data
-      const payload = {
-        content: {
-          reason: reason || 'You have been removed from the event.'
-        }
-      }
-      EventStats.recordPublish(context.eventStats, context.privateChannel, 'FORCE_SHUTDOWN', payload)
-      await RealtimeMessaging.publish(context.privateChannel, 'FORCE_SHUTDOWN', payload)
-      return 'done'
-    }),
-    attachToPrivateChannel: fromPromise(async ({ input }) => {
-      const { context } = input
-      return await RealtimeMessaging.attachTo(context.privateChannel)
-    }),
-    detachPrivateChannel: fromPromise(async ({ input }) => {
-      const { context } = input
-      return context.privateChannel ? await RealtimeMessaging.detachAll([context.privateChannel]) : 'done'
-    })
-  },
-  guards: {
-    hasAppParticipantMachine: ({ context }) => context.appParticipantMachineFactory !== null,
-    incomingRenderHasTimeout: ({ event }) => {
-      // RENDER_DISPLAY events are sent directly as { type, content, timeout? }
-      // We only block when a *new* timeout is being asserted during an active wait.
-      const timeout = event?.timeout ?? event?.data?.timeout
-      return timeout != null && timeout > 0
-    },
-    hasActionTimeout: ({ event }) => {
-      const timeout = event?.output?.timeout ?? event?.data?.timeout
-      return timeout != null && timeout > 0
-    },
-    isTimeoutImmediate: ({ context }) => context.actionTimeoutMsecs !== null && context.actionTimeoutMsecs <= 0,
-    wasMidTurnOnDisconnect: ({ context }) => context.actionTimeoutMsecs !== null && context.actionTimeoutMsecs > 0
-  },
-  delays: {
-    bootCleanupTimeout: (_args) => C.TIMEOUT_MSECS.BOOT_EXIT,
-    actionTimeout: ({ context }) => context.actionTimeoutMsecs,
-    dynamicReconnectTimeout: ({ context }) => {
-      // If an action timeout is active, use its remaining time.
-      if (context.actionTimeoutMsecs !== null && context.actionTimeoutMsecs > 0) {
-        logger.debug(`[APM] Using remaining action timeout for reconnect window: ${context.actionTimeoutMsecs}ms`)
-        return context.actionTimeoutMsecs
-      }
-      // Otherwise, use the standard reconnect timeout.
-      logger.debug(`[APM] Using standard reconnect timeout: ${C.TIMEOUT_MSECS.RECONNECT}ms`)
-      return C.TIMEOUT_MSECS.RECONNECT
-    }
-  }
-}
-
-// The AnearParticipantMachine:
-//   1. maintains the presence and geo-location for a Participant in an Event
-//   2. instantiates the XState Machine return by the (optional) appParticipantMachineFactory
-//   3. creates a private display ChannelMachine to which any participant displayType messages get published
-//   4. handles activity state, response timeouts, idle state
-//   5. receives ACTION events relayed by the AnearEventMachine
-//   6. relays all relevant events to the participant XState Machine for Application-specific handling
-const AnearParticipantMachine = (anearParticipant, { anearEvent, appParticipantMachineFactory, eventStats }) => {
-  const anearParticipantMachine = createMachine(
-    {
-      ...AnearParticipantMachineConfig(anearParticipant.id),
-      // v5: context is derived from actor `input` (no machine.withContext).
-      context: ({ input }) => input
-    },
-    AnearParticipantMachineFunctions
-  )
-
-  const anearParticipantMachineContext = AnearParticipantMachineContext(
-    anearParticipant,
-    anearEvent,
-    appParticipantMachineFactory,
-    eventStats
-  )
-
-  const actor = createActor(anearParticipantMachine, { input: anearParticipantMachineContext })
-  actor.start()
-
-  anearParticipant.setMachine(actor)
-
-  actor.subscribe(state => {
-    logger.debug('─'.repeat(40))
-    logger.debug(`APM EVENT → ${state.event?.type ?? '(init)'}`)
-    logger.debug(`APM NEXT STATE → ${JSON.stringify(state.value)}`)
-  })
-
-  return actor
-}
-
-module.exports = AnearParticipantMachine