@open-mercato/core 0.7.1-develop.7203.1.9396450b78 → 0.8.1-develop.7204.1.83330e271e

package/src/modules/push_notifications/AGENTS.md

@@ -18,8 +18,12 @@ FCM/APNs/Expo channel packages). Spec: `.ai/specs/2026-04-28-push-notifications-
   transient failures with exponential backoff + jitter (3 attempts, shared
   `@open-mercato/shared/lib/delivery/retry`), records `next_retry_at`, and marks the row `expired` once
   retries are exhausted (vs `failed` for terminal errors); on the `unregistered` sentinel soft-deletes the device.
-- **Queue** (`lib/queue.ts`) mirrors the webhooks queue: `createModuleQueue` + `enqueuePushDelivery` +
-  a local-worker bootstrap for dev/test (`QUEUE_STRATEGY !== 'async'`).
+- **Queue** (`lib/queue.ts`) mirrors the webhooks queue: `createModuleQueue` + `enqueuePushDelivery`.
+  It is enqueue-only in BOTH strategies — the consumer is always `workers/send-push.worker.ts`, run by
+  a worker process (`async`) or the local worker runner / `drainIntegrationQueue` (local). Never boot a
+  consumer from the enqueue path: the local strategy's `process()` only returns after its first drain, so
+  awaiting it runs the send inside the enqueueing request, and a retryable send re-enqueues from within
+  that handler and deadlocks on its own bootstrap.
 - **Reaper** (`lib/push-reaper.ts` → `workers/reclaim-stuck.worker.ts`) recovers rows stranded in
   `sending` by a crashed worker — the send-path claim only matches `pending`, so such a row has no
   outstanding job and would never terminate. A per-tenant `@open-mercato/scheduler` interval entry
@@ -61,9 +65,9 @@ FCM/APNs/Expo channel packages). Spec: `.ai/specs/2026-04-28-push-notifications-
 - Never export `OM_PUSH_FAKE_PROVIDERS` by hand and point `TC-PUSH-004+` / `TC-CHANNEL-PUSH-005..007` at a
   live server that does not itself have it. Their `.meta.ts` gate skips them when the flag is absent from the
   test process, which is the protection you want; exporting it defeats that gate. The fake swaps the provider
-  SDK client in `di.ts` `register()`, so whichever process claims the delivery job must have the flag — a dev
-  server without it runs its in-process worker against the **real** provider, and on real credentials that
-  means a real push to the recipient's real devices. Start the server with `OM_PUSH_FAKE_PROVIDERS=1`, or use
+  SDK client in `di.ts` `register()`, so whichever process claims the delivery job must have the flag — a
+  worker without it sends against the **real** provider, and on real credentials that means a real push to
+  the recipient's real devices. Start the worker (and the server) with `OM_PUSH_FAKE_PROVIDERS=1`, or use
   the ephemeral harness, which sets it for both the app and the drain child.
 - Resolve cross-module entities (`UserDevice`, `CommunicationChannel`) via DI tokens (`ctx.resolve(...)`),
   not import-time references, to stay decoupled.

package/src/modules/push_notifications/lib/queue.ts

@@ -1,8 +1,4 @@
-import type { EntityManager } from '@mikro-orm/postgresql'
 import { createModuleQueue, type Queue } from '@open-mercato/queue'
-import { createLogger } from '@open-mercato/shared/lib/logger'
-
-const logger = createLogger('push_notifications')
 
 export interface PushDeliveryJob {
   deliveryId: string
@@ -17,7 +13,6 @@ export const PUSH_DELIVERIES_QUEUE = 'push-deliveries'
 export const PUSH_STUCK_RECLAIM_QUEUE = 'push-stuck-reclaim'
 
 const queues = new Map<string, Queue<PushDeliveryJob>>()
-const LOCAL_WORKER_PROMISE_KEY = '__openMercatoPushLocalWorkerPromise__'
 
 export function getPushQueue(queueName: string = PUSH_DELIVERIES_QUEUE): Queue<PushDeliveryJob> {
   const existing = queues.get(queueName)
@@ -30,45 +25,21 @@ export function getPushQueue(queueName: string = PUSH_DELIVERIES_QUEUE): Queue<P
   return created
 }
 
-// In local (dev/test) queue mode jobs are processed in-process. In async mode the
-// auto-discovered `workers/send-push.worker.ts` handles them, so this is a no-op there.
-async function ensureLocalPushQueueWorkerStarted(): Promise<void> {
-  if (process.env.QUEUE_STRATEGY === 'async') return
-
-  const globalStore = globalThis as typeof globalThis & {
-    [LOCAL_WORKER_PROMISE_KEY]?: Promise<void>
-  }
-
-  if (globalStore[LOCAL_WORKER_PROMISE_KEY]) {
-    await globalStore[LOCAL_WORKER_PROMISE_KEY]
-    return
-  }
-
-  globalStore[LOCAL_WORKER_PROMISE_KEY] = (async () => {
-    const queue = getPushQueue()
-
-    await queue.process(async (job) => {
-      const [{ createRequestContainer }, { processPushDeliveryJob }] = await Promise.all([
-        import('@open-mercato/shared/lib/di/container'),
-        import('./push-delivery'),
-      ])
-
-      const container = await createRequestContainer()
-      const em = (container.resolve('em') as EntityManager).fork()
-      await processPushDeliveryJob(em, job.payload, (name) => container.resolve(name))
-    })
-  })().catch((error) => {
-    delete globalStore[LOCAL_WORKER_PROMISE_KEY]
-    logger.error('Failed to start local delivery worker', { error })
-    throw error
-  })
-
-  await globalStore[LOCAL_WORKER_PROMISE_KEY]
-}
-
+/**
+ * Enqueue only. The send is owned by the auto-discovered `workers/send-push.worker.ts`
+ * in BOTH queue strategies — a worker process in `async` mode, the local worker runner
+ * (`yarn dev`, `drainIntegrationQueue`) in local mode.
+ *
+ * This deliberately never starts a consumer itself. Booting one from the request path
+ * deadlocked the caller: the local strategy's `process()` does not return until its
+ * first drain finishes, so awaiting it ran the send handler INSIDE the enqueueing
+ * request — and a retryable send re-enqueues from within that handler, which awaited
+ * the very bootstrap promise it was running under. The first push whose delivery failed
+ * retryably therefore wedged `POST /api/notifications` forever, and because the promise
+ * was cached on `globalThis` every later push in the process awaited it too. It also put
+ * a second consumer on a queue directory the local strategy documents as single-consumer.
+ */
 export async function enqueuePushDelivery(job: PushDeliveryJob, delayMs?: number): Promise<string> {
   const queue = getPushQueue()
-  const jobId = await queue.enqueue(job, delayMs && delayMs > 0 ? { delayMs } : undefined)
-  await ensureLocalPushQueueWorkerStarted()
-  return jobId
+  return queue.enqueue(job, delayMs && delayMs > 0 ? { delayMs } : undefined)
 }