@open-mercato/shared 0.6.8-develop.7015.1.af90a2ddc7 → 0.6.8-develop.7019.1.f4c01c4b5c

package/src/modules/events/factory.ts

@@ -65,17 +65,54 @@ export function getGlobalEventBus(): GlobalEventBus | null {
 // Event Registry for Validation
 // =============================================================================
 
-// Global set of all declared event IDs for runtime validation
-const allDeclaredEventIds = new Set<string>()
+type EventRegistryState = {
+  declaredEventIds: Set<string>
+  declaredEvents: EventDefinition[]
+  registeredEventConfigs: EventModuleConfig[] | null
+}
+
+const GLOBAL_EVENT_REGISTRY_KEY = '__openMercatoEventDefinitionRegistry__'
+
+const fallbackEventRegistryState: EventRegistryState = {
+  declaredEventIds: new Set<string>(),
+  declaredEvents: [],
+  registeredEventConfigs: null,
+}
+
+function isEventRegistryState(value: unknown): value is EventRegistryState {
+  if (!value || typeof value !== 'object') return false
+  const candidate = value as Partial<EventRegistryState>
+  return candidate.declaredEventIds instanceof Set
+    && Array.isArray(candidate.declaredEvents)
+    && (candidate.registeredEventConfigs === null || Array.isArray(candidate.registeredEventConfigs))
+}
 
-// Global registry of all declared events with their full definitions
-const allDeclaredEvents: EventDefinition[] = []
+function getEventRegistryState(): EventRegistryState {
+  try {
+    const globalScope = globalThis as Record<string, unknown>
+    const existing = globalScope[GLOBAL_EVENT_REGISTRY_KEY]
+    if (isEventRegistryState(existing)) return existing
+    globalScope[GLOBAL_EVENT_REGISTRY_KEY] = fallbackEventRegistryState
+    return fallbackEventRegistryState
+  } catch {
+    // Restricted runtimes may deny global access. Keep the previous
+    // module-local behavior as a safe fallback.
+    return fallbackEventRegistryState
+  }
+}
 
 function addDeclaredEvent(event: EventDefinition): void {
-  allDeclaredEventIds.add(event.id)
-  // Avoid duplicates if createModuleEvents/registerEventModuleConfigs is called multiple times (e.g., HMR)
-  if (!allDeclaredEvents.find(e => e.id === event.id)) {
-    allDeclaredEvents.push(event)
+  const state = getEventRegistryState()
+  state.declaredEventIds.add(event.id)
+  const existingIndex = state.declaredEvents.findIndex((candidate) => candidate.id === event.id)
+  if (existingIndex < 0) {
+    state.declaredEvents.push(event)
+    return
+  }
+  // Refresh a module's own definition in place during HMR without allowing a
+  // duplicate declaration from another module to take over the event id.
+  if (state.declaredEvents[existingIndex]?.module === event.module) {
+    state.declaredEvents[existingIndex] = event
   }
 }
 
@@ -84,7 +121,7 @@ function addDeclaredEvent(event: EventDefinition): void {
  * Used for runtime validation to ensure only declared events are emitted.
  */
 export function isEventDeclared(eventId: string): boolean {
-  return allDeclaredEventIds.has(eventId)
+  return getEventRegistryState().declaredEventIds.has(eventId)
 }
 
 /**
@@ -92,7 +129,7 @@ export function isEventDeclared(eventId: string): boolean {
  * Useful for debugging and introspection.
  */
 export function getAllDeclaredEventIds(): string[] {
-  return Array.from(allDeclaredEventIds)
+  return Array.from(getEventRegistryState().declaredEventIds)
 }
 
 /**
@@ -100,7 +137,7 @@ export function getAllDeclaredEventIds(): string[] {
  * Used by the API to return available events for workflow triggers.
  */
 export function getDeclaredEvents(): EventDefinition[] {
-  return [...allDeclaredEvents]
+  return [...getEventRegistryState().declaredEvents]
 }
 
 /**
@@ -108,16 +145,52 @@ export function getDeclaredEvents(): EventDefinition[] {
  * Used by the SSE endpoint to filter events for the DOM Event Bridge.
  */
 export function isBroadcastEvent(eventId: string): boolean {
-  const event = allDeclaredEvents.find(e => e.id === eventId)
+  const event = getEventRegistryState().declaredEvents.find(e => e.id === eventId)
   return event?.clientBroadcast === true
 }
 
+/**
+ * Check if an event should be published over the server-to-server event bridge.
+ * Browser-broadcast events remain eligible for backward compatibility, while
+ * crossProcessBroadcast supports private process coordination without SSE.
+ */
+export function isCrossProcessBroadcastEvent(eventId: string): boolean {
+  const event = getEventRegistryState().declaredEvents.find(e => e.id === eventId)
+  return event?.clientBroadcast === true || event?.crossProcessBroadcast === true
+}
+
+/**
+ * Check whether an event is reserved for private server-to-server
+ * coordination. Workflow-authored EMIT_EVENT activities must not emit these
+ * events because their payload and event id are tenant-managed input.
+ */
+export function isPrivateCrossProcessBroadcastEvent(eventId: string): boolean {
+  const event = getEventRegistryState().declaredEvents.find(e => e.id === eventId)
+  return event?.crossProcessBroadcast === true && event?.clientBroadcast !== true
+}
+
+/**
+ * Verify provenance for a private cross-process event. The module id is
+ * stamped by a declared module emitter or another trusted server-side seam;
+ * tenant-managed event payloads never participate in this decision.
+ */
+export function isPrivateCrossProcessEventEmitter(
+  eventId: string,
+  emitterModuleId: string | undefined,
+): boolean {
+  const event = getEventRegistryState().declaredEvents.find(e => e.id === eventId)
+  if (event?.crossProcessBroadcast !== true) return true
+  return typeof event.module === 'string'
+    && event.module.length > 0
+    && event.module === emitterModuleId
+}
+
 /**
  * Check if an event has portalBroadcast enabled.
  * Used by the portal SSE endpoint to filter events for the Portal Event Bridge.
  */
 export function isPortalBroadcastEvent(eventId: string): boolean {
-  const event = allDeclaredEvents.find(e => e.id === eventId)
+  const event = getEventRegistryState().declaredEvents.find(e => e.id === eventId)
   return event?.portalBroadcast === true
 }
 
@@ -125,17 +198,16 @@ export function isPortalBroadcastEvent(eventId: string): boolean {
 // Bootstrap Registration (similar to searchModuleConfigs pattern)
 // =============================================================================
 
-let _registeredEventConfigs: EventModuleConfig[] | null = null
-
 /**
  * Register event module configurations globally.
  * Called during app bootstrap with configs from events.generated.ts.
  */
 export function registerEventModuleConfigs(configs: EventModuleConfig[]): void {
-  if (_registeredEventConfigs !== null && process.env.NODE_ENV === 'development') {
+  const state = getEventRegistryState()
+  if (state.registeredEventConfigs !== null && process.env.NODE_ENV === 'development') {
     logger.debug('Event module configs re-registered (this may occur during HMR)')
   }
-  _registeredEventConfigs = configs
+  state.registeredEventConfigs = configs
   for (const config of configs) {
     for (const event of config.events) {
       addDeclaredEvent(event)
@@ -148,7 +220,7 @@ export function registerEventModuleConfigs(configs: EventModuleConfig[]): void {
  * Returns empty array if not registered.
  */
 export function getEventModuleConfigs(): EventModuleConfig[] {
-  return _registeredEventConfigs ?? []
+  return getEventRegistryState().registeredEventConfigs ?? []
 }
 
 // =============================================================================
@@ -239,7 +311,27 @@ export function createModuleEvents<
       return
     }
 
-    await eventBus.emit(eventId, payload, emitOptions)
+    const eventDefinition = fullEvents.find((event) => event.id === eventId)
+    const isClientBroadcast = eventDefinition?.clientBroadcast === true
+    const trustedOptions = eventDefinition?.crossProcessBroadcast === true || isClientBroadcast
+      ? {
+          ...emitOptions,
+          // Browser-broadcast module emitters historically accepted scope in
+          // their typed payload. Preserve that contract at the trusted module
+          // boundary while the event bus itself relies only on options.
+          ...(isClientBroadcast && emitOptions?.tenantId === undefined
+            ? { tenantId: payload.tenantId ?? null }
+            : {}),
+          ...(isClientBroadcast && emitOptions?.organizationId === undefined
+            ? { organizationId: payload.organizationId ?? null }
+            : {}),
+          ...(isClientBroadcast && emitOptions?.organizationIds === undefined && Array.isArray(payload.organizationIds)
+            ? { organizationIds: payload.organizationIds.filter((value): value is string => typeof value === 'string') }
+            : {}),
+          emitterModuleId: moduleId,
+        }
+      : emitOptions
+    await eventBus.emit(eventId, payload, trustedOptions)
   }
 
   return {

package/src/modules/events/types.ts

@@ -34,6 +34,8 @@ export interface EventDefinition {
   excludeFromTriggers?: boolean
   /** When true, this event is bridged to the browser via SSE (DOM Event Bridge). Default: false */
   clientBroadcast?: boolean
+  /** When true, this event is bridged between server processes without enabling browser delivery. Default: false */
+  crossProcessBroadcast?: boolean
   /** When true, this event is bridged to the customer portal via SSE (Portal Event Bridge). Default: false */
   portalBroadcast?: boolean
 }
@@ -66,6 +68,21 @@ export interface EmitOptions {
   tenantId?: string | null
   /** Trusted organization scope forwarded to subscribers separately from the payload */
   organizationId?: string | null
+  /**
+   * Trusted multi-organization audience forwarded to subscribers separately
+   * from the payload. Mirrors the documented SSE audience contract, where a
+   * clientBroadcast event may target several organizations at once; carried in
+   * trusted options so the receiver never falls back to payload scope.
+   */
+  organizationIds?: string[] | null
+  /**
+   * Module that emitted a private cross-process coordination event.
+   *
+   * This is stamped by `createModuleEvents`; application inputs must not set or
+   * derive it from event payloads.
+   * @internal
+   */
+  emitterModuleId?: string
 }
 
 // =============================================================================

package/src/modules/registry.ts

@@ -196,6 +196,14 @@ export type ModuleWorker = {
   concurrency: number
   lockDuration?: number
   maxStalledCount?: number
+  /**
+   * Reports a job the queue abandoned without running the handler.
+   *
+   * Present only for workers whose metadata declares it; the generator emits it as a lazy import
+   * beside the handler, because the registry serializes metadata as literals and a function cannot
+   * survive that.
+   */
+  onJobAbandoned?: (payload: unknown, info: { jobId: string | null; reason: string }) => void | Promise<void>
   handler: ModuleWorkerHandler
 }
 
@@ -554,3 +562,31 @@ export function createLazyModuleWorker(
     return handler(job, ctx)
   }
 }
+
+/**
+ * Resolves a worker's `metadata.onJobAbandoned` on first use.
+ *
+ * The generator serializes worker metadata as literals, so a function declared there cannot be
+ * emitted inline the way `concurrency` or `lockDuration` are. It is emitted as this thunk instead —
+ * the same lazy-import treatment the handler already gets — and only for workers whose metadata
+ * declares the callback, so no other queue acquires one (and with it, a sweep) by accident.
+ */
+export function createLazyModuleWorkerAbandonHook(
+  loadModule: () => Promise<unknown>,
+  id: string
+): (payload: unknown, info: { jobId: string | null; reason: string }) => Promise<void> {
+  let hookPromise: Promise<((payload: unknown, info: { jobId: string | null; reason: string }) => unknown) | null> | null = null
+  return async (payload, info) => {
+    hookPromise ??= loadModule().then((loaded) => {
+      const metadata = (loaded as { metadata?: { onJobAbandoned?: unknown } } | null)?.metadata
+      return typeof metadata?.onJobAbandoned === 'function'
+        ? (metadata.onJobAbandoned as (payload: unknown, info: { jobId: string | null; reason: string }) => unknown)
+        : null
+    })
+    const hook = await hookPromise
+    if (!hook) {
+      throw new Error(`[registry] Worker "${id}" was registered with an abandoned-job hook but its metadata no longer declares one`)
+    }
+    await hook(payload, info)
+  }
+}