@open-mercato/cli 0.6.6-develop.5586.1.c9ed1d68a8 → 0.6.6-develop.5594.1.30cd738303

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/cli",
-  "version": "0.6.6-develop.5586.1.c9ed1d68a8",
+  "version": "0.6.6-develop.5594.1.30cd738303",
   "type": "module",
   "main": "./dist/index.js",
   "exports": {
@@ -59,8 +59,8 @@
     "@mikro-orm/decorators": "^7.1.4",
     "@mikro-orm/migrations": "^7.1.4",
     "@mikro-orm/postgresql": "^7.1.4",
-    "@open-mercato/queue": "0.6.6-develop.5586.1.c9ed1d68a8",
-    "@open-mercato/shared": "0.6.6-develop.5586.1.c9ed1d68a8",
+    "@open-mercato/queue": "0.6.6-develop.5594.1.30cd738303",
+    "@open-mercato/shared": "0.6.6-develop.5594.1.30cd738303",
     "cross-spawn": "^7.0.6",
     "pg": "8.21.0",
     "semver": "^7.8.4",
@@ -70,10 +70,10 @@
     "typescript": "^6.0.3"
   },
   "peerDependencies": {
-    "@open-mercato/shared": "0.6.6-develop.5586.1.c9ed1d68a8"
+    "@open-mercato/shared": "0.6.6-develop.5594.1.30cd738303"
   },
   "devDependencies": {
-    "@open-mercato/shared": "0.6.6-develop.5586.1.c9ed1d68a8",
+    "@open-mercato/shared": "0.6.6-develop.5594.1.30cd738303",
     "@types/jest": "^30.0.0",
     "jest": "^30.4.2",
     "ts-jest": "^29.4.11"

package/src/__tests__/mercato.test.ts

@@ -642,6 +642,8 @@ describe('server dev managed process exits', () => {
   const originalLazy = process.env.OM_AUTO_SPAWN_WORKERS_LAZY
   const originalLazyScheduler = process.env.OM_AUTO_SPAWN_SCHEDULER_LAZY
   const originalGenerateWatchMode = process.env.OM_DEV_GENERATE_WATCH_MODE
+  const originalSingleDelivery = process.env.OM_EVENTS_SINGLE_DELIVERY
+  const originalExternalWorker = process.env.OM_EVENTS_EXTERNAL_WORKER
 
   beforeEach(() => {
     jest.restoreAllMocks()
@@ -650,6 +652,12 @@ describe('server dev managed process exits', () => {
     process.env.AUTO_SPAWN_WORKERS = 'true'
     delete process.env.OM_AUTO_SPAWN_WORKERS_LAZY
     delete process.env.OM_AUTO_SPAWN_SCHEDULER_LAZY
+    // These tests toggle AUTO_SPAWN_WORKERS to exercise scheduler/Next exits, not
+    // the events single-delivery guard. Acknowledge an external events worker so
+    // the (default-on) guard stays quiet, and start each test from a clean
+    // single-delivery env since the guard rewrites it in place.
+    delete process.env.OM_EVENTS_SINGLE_DELIVERY
+    process.env.OM_EVENTS_EXTERNAL_WORKER = 'true'
     // These tests stub the resolver to an empty object; the in-process
     // generate watcher's default checksum function would error on the
     // missing methods. Force the legacy out-of-process mode so the
@@ -680,6 +688,10 @@ describe('server dev managed process exits', () => {
     else process.env.OM_AUTO_SPAWN_WORKERS_LAZY = originalLazy
     if (originalLazyScheduler === undefined) delete process.env.OM_AUTO_SPAWN_SCHEDULER_LAZY
     else process.env.OM_AUTO_SPAWN_SCHEDULER_LAZY = originalLazyScheduler
+    if (originalSingleDelivery === undefined) delete process.env.OM_EVENTS_SINGLE_DELIVERY
+    else process.env.OM_EVENTS_SINGLE_DELIVERY = originalSingleDelivery
+    if (originalExternalWorker === undefined) delete process.env.OM_EVENTS_EXTERNAL_WORKER
+    else process.env.OM_EVENTS_EXTERNAL_WORKER = originalExternalWorker
   })
 
   it('skips scheduler auto-start when the module is not enabled', async () => {
@@ -909,6 +921,8 @@ describe('server start managed process exits', () => {
   const originalAutoSpawnWorkers = process.env.AUTO_SPAWN_WORKERS
   const originalLazy = process.env.OM_AUTO_SPAWN_WORKERS_LAZY
   const originalLazyScheduler = process.env.OM_AUTO_SPAWN_SCHEDULER_LAZY
+  const originalSingleDelivery = process.env.OM_EVENTS_SINGLE_DELIVERY
+  const originalExternalWorker = process.env.OM_EVENTS_EXTERNAL_WORKER
 
   beforeEach(() => {
     jest.restoreAllMocks()
@@ -917,6 +931,11 @@ describe('server start managed process exits', () => {
     process.env.AUTO_SPAWN_WORKERS = 'true'
     delete process.env.OM_AUTO_SPAWN_WORKERS_LAZY
     delete process.env.OM_AUTO_SPAWN_SCHEDULER_LAZY
+    // Not exercising the events single-delivery guard here — acknowledge an
+    // external worker so the default-on guard stays quiet, and reset the
+    // guard-rewritten single-delivery env between tests.
+    delete process.env.OM_EVENTS_SINGLE_DELIVERY
+    process.env.OM_EVENTS_EXTERNAL_WORKER = 'true'
   })
 
   afterEach(() => {
@@ -938,6 +957,10 @@ describe('server start managed process exits', () => {
     else process.env.OM_AUTO_SPAWN_WORKERS_LAZY = originalLazy
     if (originalLazyScheduler === undefined) delete process.env.OM_AUTO_SPAWN_SCHEDULER_LAZY
     else process.env.OM_AUTO_SPAWN_SCHEDULER_LAZY = originalLazyScheduler
+    if (originalSingleDelivery === undefined) delete process.env.OM_EVENTS_SINGLE_DELIVERY
+    else process.env.OM_EVENTS_SINGLE_DELIVERY = originalSingleDelivery
+    if (originalExternalWorker === undefined) delete process.env.OM_EVENTS_EXTERNAL_WORKER
+    else process.env.OM_EVENTS_EXTERNAL_WORKER = originalExternalWorker
   })
 
   it('skips scheduler auto-start when the module is not enabled', async () => {

package/src/lib/__tests__/events-single-delivery.test.ts

@@ -0,0 +1,68 @@
+import {
+  applyEventsSingleDeliveryGuard,
+  reconcileEventsSingleDelivery,
+} from '../events-single-delivery'
+
+describe('reconcileEventsSingleDelivery', () => {
+  it('keeps single-delivery on when workers auto-spawn (default request)', () => {
+    expect(reconcileEventsSingleDelivery({}, 'eager')).toEqual({ effective: true })
+    expect(reconcileEventsSingleDelivery({}, 'lazy')).toEqual({ effective: true })
+  })
+
+  it('falls back to inline dual-dispatch (with a warning) when no worker runs', () => {
+    const result = reconcileEventsSingleDelivery({}, 'off')
+    expect(result.effective).toBe(false)
+    expect(result.warning).toContain('OM_EVENTS_SINGLE_DELIVERY')
+    expect(result.warning).toContain('OM_EVENTS_EXTERNAL_WORKER')
+  })
+
+  it('keeps single-delivery on with no auto-spawn when an external worker is acknowledged', () => {
+    expect(
+      reconcileEventsSingleDelivery({ OM_EVENTS_EXTERNAL_WORKER: 'true' }, 'off'),
+    ).toEqual({ effective: true })
+  })
+
+  it('respects an explicit legacy opt-out regardless of worker availability', () => {
+    expect(
+      reconcileEventsSingleDelivery({ OM_EVENTS_SINGLE_DELIVERY: 'false' }, 'eager'),
+    ).toEqual({ effective: false })
+  })
+})
+
+describe('applyEventsSingleDeliveryGuard', () => {
+  it('writes the reconciled value into both process and runtime env', () => {
+    const processEnv: NodeJS.ProcessEnv = {}
+    const runtimeEnv: NodeJS.ProcessEnv = {}
+    const errorSpy = jest.spyOn(console, 'error').mockImplementation(() => {})
+
+    const result = applyEventsSingleDeliveryGuard({
+      processEnv,
+      runtimeEnv,
+      autoSpawnWorkersMode: 'off',
+    })
+
+    expect(result.effective).toBe(false)
+    expect(processEnv.OM_EVENTS_SINGLE_DELIVERY).toBe('false')
+    expect(runtimeEnv.OM_EVENTS_SINGLE_DELIVERY).toBe('false')
+    expect(errorSpy).toHaveBeenCalledTimes(1)
+    errorSpy.mockRestore()
+  })
+
+  it('writes true (and stays quiet) when workers are available', () => {
+    const processEnv: NodeJS.ProcessEnv = {}
+    const runtimeEnv: NodeJS.ProcessEnv = {}
+    const errorSpy = jest.spyOn(console, 'error').mockImplementation(() => {})
+
+    const result = applyEventsSingleDeliveryGuard({
+      processEnv,
+      runtimeEnv,
+      autoSpawnWorkersMode: 'eager',
+    })
+
+    expect(result.effective).toBe(true)
+    expect(processEnv.OM_EVENTS_SINGLE_DELIVERY).toBe('true')
+    expect(runtimeEnv.OM_EVENTS_SINGLE_DELIVERY).toBe('true')
+    expect(errorSpy).not.toHaveBeenCalled()
+    errorSpy.mockRestore()
+  })
+})

package/src/lib/__tests__/worker-connection-budget.test.ts

@@ -0,0 +1,115 @@
+import {
+  planWorkerConcurrency,
+  resolveWorkerConnectionBudget,
+} from '../worker-connection-budget'
+
+describe('resolveWorkerConnectionBudget', () => {
+  it('defaults to the pool max when no override is set', () => {
+    expect(resolveWorkerConnectionBudget({} as NodeJS.ProcessEnv, 20)).toBe(20)
+  })
+
+  it('honors a positive OM_WORKERS_DB_CONNECTION_BUDGET override', () => {
+    expect(
+      resolveWorkerConnectionBudget(
+        { OM_WORKERS_DB_CONNECTION_BUDGET: '8' } as unknown as NodeJS.ProcessEnv,
+        20,
+      ),
+    ).toBe(8)
+  })
+
+  it('falls back to the pool max for non-numeric or non-positive overrides', () => {
+    for (const value of ['0', '-3', 'abc', '']) {
+      expect(
+        resolveWorkerConnectionBudget(
+          { OM_WORKERS_DB_CONNECTION_BUDGET: value } as unknown as NodeJS.ProcessEnv,
+          16,
+        ),
+      ).toBe(16)
+    }
+  })
+
+  it('clamps an invalid pool max to at least 1', () => {
+    expect(resolveWorkerConnectionBudget({} as NodeJS.ProcessEnv, 0)).toBe(1)
+    expect(resolveWorkerConnectionBudget({} as NodeJS.ProcessEnv, Number.NaN)).toBe(1)
+  })
+})
+
+describe('planWorkerConcurrency', () => {
+  it('passes concurrency through untouched when it fits the budget', () => {
+    const plan = planWorkerConcurrency(
+      [
+        { queue: 'events', concurrency: 5 },
+        { queue: 'vector-indexing', concurrency: 2 },
+        { queue: 'fulltext-indexing', concurrency: 2 },
+      ],
+      20,
+    )
+    expect(plan.clamped).toBe(false)
+    expect(plan.totalEffective).toBe(9)
+    expect(plan.entries.map((entry) => entry.effective)).toEqual([5, 2, 2])
+  })
+
+  it('scales down to exactly the budget when over-subscribed', () => {
+    const plan = planWorkerConcurrency(
+      [
+        { queue: 'events', concurrency: 10 },
+        { queue: 'vector-indexing', concurrency: 10 },
+        { queue: 'fulltext-indexing', concurrency: 10 },
+      ],
+      12,
+    )
+    expect(plan.clamped).toBe(true)
+    expect(plan.belowQueueFloor).toBe(false)
+    expect(plan.totalEffective).toBe(12)
+    for (const entry of plan.entries) {
+      expect(entry.effective).toBeGreaterThanOrEqual(1)
+      expect(entry.effective).toBeLessThanOrEqual(entry.requested)
+    }
+  })
+
+  it('keeps a floor of 1 per queue and never exceeds the request', () => {
+    const plan = planWorkerConcurrency(
+      [
+        { queue: 'events', concurrency: 16 },
+        { queue: 'vector-indexing', concurrency: 2 },
+        { queue: 'fulltext-indexing', concurrency: 2 },
+      ],
+      6,
+    )
+    const byQueue = Object.fromEntries(plan.entries.map((entry) => [entry.queue, entry.effective]))
+    expect(byQueue['vector-indexing']).toBeGreaterThanOrEqual(1)
+    expect(byQueue['fulltext-indexing']).toBeGreaterThanOrEqual(1)
+    // The largest requester absorbs most of the remaining budget.
+    expect(byQueue['events']).toBeGreaterThan(byQueue['vector-indexing'])
+    expect(plan.totalEffective).toBe(6)
+  })
+
+  it('flags belowQueueFloor when the budget is smaller than the queue count', () => {
+    const plan = planWorkerConcurrency(
+      [
+        { queue: 'a', concurrency: 4 },
+        { queue: 'b', concurrency: 4 },
+        { queue: 'c', concurrency: 4 },
+      ],
+      2,
+    )
+    expect(plan.clamped).toBe(true)
+    expect(plan.belowQueueFloor).toBe(true)
+    // Floor of 1 wins even though it exceeds the budget.
+    expect(plan.entries.every((entry) => entry.effective === 1)).toBe(true)
+    expect(plan.totalEffective).toBe(3)
+  })
+
+  it('treats zero/negative requested concurrency as a floor of 1', () => {
+    const plan = planWorkerConcurrency(
+      [
+        { queue: 'events', concurrency: 0 },
+        { queue: 'vector-indexing', concurrency: -5 },
+      ],
+      20,
+    )
+    expect(plan.entries.map((entry) => entry.requested)).toEqual([1, 1])
+    expect(plan.totalEffective).toBe(2)
+    expect(plan.clamped).toBe(false)
+  })
+})

package/src/lib/events-single-delivery.ts

@@ -0,0 +1,69 @@
+import { parseBooleanWithDefault } from '@open-mercato/shared/lib/boolean'
+import type { AutoSpawnWorkersMode } from './auto-spawn-workers'
+
+// Keep these env names in sync with the runtime source of truth,
+// `@open-mercato/events/single-delivery`. The CLI cannot import the events
+// package (no dependency edge), so the reconcile logic is mirrored here for the
+// server-bootstrap guard only; the bus and worker own the runtime behavior.
+const EVENTS_SINGLE_DELIVERY_ENV = 'OM_EVENTS_SINGLE_DELIVERY'
+const EVENTS_EXTERNAL_WORKER_ENV = 'OM_EVENTS_EXTERNAL_WORKER'
+
+type EnvSource = NodeJS.ProcessEnv | Record<string, string | undefined>
+
+export type SingleDeliveryReconciliation = {
+  effective: boolean
+  warning?: string
+}
+
+/**
+ * Server-bootstrap guard for the default-on single-delivery dispatch.
+ *
+ * With single-delivery on, persistent subscribers are skipped inline and ONLY
+ * the events worker dispatches them. A process that runs NO events worker
+ * (auto-spawn off and no acknowledged external worker) would skip those
+ * subscribers with nothing to drain the queue — silently dropping notifications,
+ * queued emails, and indexing. This fails safe by disabling single-delivery for
+ * such a process (back to inline dual-dispatch) and returning a loud warning.
+ *
+ * Transient worker downtime is NOT this guard's concern: the durable queue holds
+ * the job until a worker returns. Only the "no worker at all" config is guarded.
+ */
+export function reconcileEventsSingleDelivery(
+  env: EnvSource,
+  autoSpawnWorkersMode: AutoSpawnWorkersMode,
+): SingleDeliveryReconciliation {
+  const requested = parseBooleanWithDefault(env[EVENTS_SINGLE_DELIVERY_ENV], true)
+  if (!requested) return { effective: false }
+  const externalWorker = parseBooleanWithDefault(env[EVENTS_EXTERNAL_WORKER_ENV], false)
+  const workersAvailable = autoSpawnWorkersMode !== 'off' || externalWorker
+  if (workersAvailable) return { effective: true }
+  return {
+    effective: false,
+    warning:
+      `[events] ${EVENTS_SINGLE_DELIVERY_ENV} is on (default) but this process auto-spawns no events worker ` +
+      `(AUTO_SPAWN_WORKERS=off) and ${EVENTS_EXTERNAL_WORKER_ENV} is not set. Persistent subscribers would be ` +
+      `skipped inline with nothing to drain the queue, silently dropping notifications, queued emails, and ` +
+      `indexing. Falling back to legacy inline dual-dispatch for safety. To keep single-delivery, run an events ` +
+      `worker (\`mercato queue worker events\`) and set ${EVENTS_EXTERNAL_WORKER_ENV}=true, or enable ` +
+      `AUTO_SPAWN_WORKERS.`,
+  }
+}
+
+/**
+ * Applies {@link reconcileEventsSingleDelivery} and writes the effective value
+ * into both the current process env (for the in-process app/bus) and the spawned
+ * worker/child env (so a child worker reads the same value the bus does). Logs
+ * the warning once when single-delivery is disabled for safety.
+ */
+export function applyEventsSingleDeliveryGuard(args: {
+  processEnv: NodeJS.ProcessEnv
+  runtimeEnv: NodeJS.ProcessEnv
+  autoSpawnWorkersMode: AutoSpawnWorkersMode
+}): SingleDeliveryReconciliation {
+  const result = reconcileEventsSingleDelivery(args.processEnv, args.autoSpawnWorkersMode)
+  if (result.warning) console.error(result.warning)
+  const value = result.effective ? 'true' : 'false'
+  args.processEnv[EVENTS_SINGLE_DELIVERY_ENV] = value
+  args.runtimeEnv[EVENTS_SINGLE_DELIVERY_ENV] = value
+  return result
+}

package/src/lib/worker-connection-budget.ts

@@ -0,0 +1,131 @@
+/**
+ * Bound the DB-connection demand of background queue workers.
+ *
+ * Since #2970/#3011 each worker job builds its own request container, so its own
+ * `EntityManager` checks out a dedicated pooled DB connection for the job's
+ * duration. The peak connection demand of `worker --all` is therefore the sum of
+ * every queue's concurrency. Nothing previously bounded that sum against the DB
+ * pool (`DB_POOL_MAX`) or the database's global `max_connections`, so a storm of
+ * slow/failing jobs could over-subscribe connections — thrashing on the worker's
+ * own acquire timeout and, across the worker + web processes, starving the
+ * request/onboarding path that shares the same database.
+ *
+ * These helpers derive a per-queue effective-concurrency plan whose total never
+ * exceeds a connection budget (defaulting to the resolved pool max), while
+ * guaranteeing every queue keeps at least one worker.
+ */
+
+export type WorkerQueueConcurrency = {
+  queue: string
+  concurrency: number
+}
+
+export type WorkerConcurrencyPlanEntry = {
+  queue: string
+  requested: number
+  effective: number
+}
+
+export type WorkerConcurrencyPlan = {
+  /** Connection budget the plan was fitted to. */
+  budget: number
+  /** Sum of requested concurrency across all queues. */
+  totalRequested: number
+  /** Sum of effective concurrency the plan grants. */
+  totalEffective: number
+  /** True when any queue's concurrency was reduced to fit the budget. */
+  clamped: boolean
+  /**
+   * True when the budget is smaller than the number of queues, so the per-queue
+   * floor of 1 forces the total above the budget. The caller should surface this
+   * as a misconfiguration (raise `DB_POOL_MAX` or the budget).
+   */
+  belowQueueFloor: boolean
+  entries: WorkerConcurrencyPlanEntry[]
+}
+
+function toPositiveInt(value: number | undefined, fallback: number): number {
+  if (value === undefined || !Number.isFinite(value)) return fallback
+  const floored = Math.floor(value)
+  return floored > 0 ? floored : fallback
+}
+
+/**
+ * Resolve the connection budget for background workers. Defaults to the resolved
+ * DB pool max so the worker never tries to use more connections than its own pool
+ * can hand out; override with `OM_WORKERS_DB_CONNECTION_BUDGET` (positive int).
+ */
+export function resolveWorkerConnectionBudget(
+  env: NodeJS.ProcessEnv,
+  poolMax: number,
+): number {
+  const safePoolMax = toPositiveInt(poolMax, 1)
+  const raw = env.OM_WORKERS_DB_CONNECTION_BUDGET
+  if (!raw) return safePoolMax
+  const parsed = Number.parseInt(raw, 10)
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : safePoolMax
+}
+
+/**
+ * Fit per-queue concurrency to a connection budget.
+ *
+ * - Every queue keeps a floor of 1 worker (no queue is starved).
+ * - No queue exceeds its requested concurrency.
+ * - When the sum exceeds the budget, leftover capacity is distributed greedily to
+ *   the queues furthest below their request, so the total matches the budget
+ *   exactly (when `budget >= queueCount`) and the allocation is deterministic.
+ */
+export function planWorkerConcurrency(
+  queues: WorkerQueueConcurrency[],
+  budget: number,
+): WorkerConcurrencyPlan {
+  const safeBudget = toPositiveInt(budget, 1)
+  const requested = queues.map((entry) => ({
+    queue: entry.queue,
+    requested: toPositiveInt(entry.concurrency, 1),
+  }))
+  const totalRequested = requested.reduce((sum, entry) => sum + entry.requested, 0)
+
+  if (totalRequested <= safeBudget) {
+    return {
+      budget: safeBudget,
+      totalRequested,
+      totalEffective: totalRequested,
+      clamped: false,
+      belowQueueFloor: false,
+      entries: requested.map((entry) => ({ ...entry, effective: entry.requested })),
+    }
+  }
+
+  // Floor every queue at 1, then water-fill the remaining budget to the queues
+  // with the largest unmet request first.
+  const effective = requested.map(() => 1)
+  let used = effective.length
+  while (used < safeBudget) {
+    let bestIndex = -1
+    let bestDeficit = 0
+    for (let index = 0; index < requested.length; index += 1) {
+      const deficit = requested[index].requested - effective[index]
+      if (deficit > bestDeficit) {
+        bestDeficit = deficit
+        bestIndex = index
+      }
+    }
+    if (bestIndex === -1) break
+    effective[bestIndex] += 1
+    used += 1
+  }
+
+  const totalEffective = effective.reduce((sum, value) => sum + value, 0)
+  return {
+    budget: safeBudget,
+    totalRequested,
+    totalEffective,
+    clamped: true,
+    belowQueueFloor: requested.length > safeBudget,
+    entries: requested.map((entry, index) => ({
+      ...entry,
+      effective: effective[index],
+    })),
+  }
+}

package/src/mercato.ts

@@ -15,7 +15,13 @@ import {
   resolveLazyRestart,
 } from './lib/auto-spawn-workers'
 import { startLazyWorkerSupervisor } from './lib/queue-worker-supervisor'
+import { applyEventsSingleDeliveryGuard } from './lib/events-single-delivery'
 import { createPerJobWorkerHandler } from './lib/worker-job-handler'
+import {
+  planWorkerConcurrency,
+  resolveWorkerConnectionBudget,
+  type WorkerConcurrencyPlan,
+} from './lib/worker-connection-budget'
 import {
   resolveAutoSpawnSchedulerMode,
   resolveLazySchedulerPollMs,
@@ -525,6 +531,46 @@ function formatQueueWorkerLabel(queueNames: string[]): string {
   return `Queue worker (${preview})`
 }
 
+/**
+ * Fit the requested per-queue worker concurrency to the worker process's DB
+ * connection budget and log the resolved plan. Since each job runs in its own
+ * request container (one pooled connection per in-flight job), the sum of worker
+ * concurrency is the worker's peak connection demand — it MUST stay within the
+ * pool so background jobs cannot starve the request/onboarding path that shares
+ * the same database.
+ */
+async function resolveWorkerBudgetPlan(
+  requestedByQueue: { queue: string; concurrency: number }[],
+): Promise<WorkerConcurrencyPlan> {
+  const { resolvePoolConfig } = await import('@open-mercato/shared/lib/db/mikro')
+  const poolMax = resolvePoolConfig(process.env).poolMax
+  const budget = resolveWorkerConnectionBudget(process.env, poolMax)
+  const plan = planWorkerConcurrency(requestedByQueue, budget)
+
+  console.log(
+    `[worker] DB connection budget: ${plan.budget} (pool max ${poolMax}); ` +
+      `requested Σconcurrency ${plan.totalRequested}, effective ${plan.totalEffective}`,
+  )
+  if (plan.clamped) {
+    const perQueue = plan.entries
+      .map((entry) => `${entry.queue}=${entry.effective}/${entry.requested}`)
+      .join(', ')
+    console.warn(
+      `[worker] Worker concurrency clamped to fit the DB connection budget (${plan.budget}): ${perQueue}. ` +
+        `Raise DB_POOL_MAX or set OM_WORKERS_DB_CONNECTION_BUDGET to change this. ` +
+        `Keep web_pool_max + worker_pool_max + overhead <= Postgres max_connections.`,
+    )
+  }
+  if (plan.belowQueueFloor) {
+    console.warn(
+      `[worker] DB connection budget (${plan.budget}) is smaller than the number of queues ` +
+        `(${requestedByQueue.length}); every queue runs at concurrency 1 and total demand ` +
+        `(${plan.totalEffective}) still exceeds the budget. Raise DB_POOL_MAX.`,
+    )
+  }
+  return plan
+}
+
 function lookupModuleCommand(
   allModules: Module[],
   moduleName: string,
@@ -1520,12 +1566,31 @@ export async function run(argv = process.argv) {
             }
 
             const { createRequestContainer } = await import('@open-mercato/shared/lib/di/container')
+
+            // Fit Σconcurrency to the worker's DB connection budget before
+            // starting any worker, so the per-job containers (one connection each)
+            // can never over-subscribe the pool the request path shares.
+            const requestedByQueue = discoveredQueues.map((queue) => {
+              const queueWorkers = allWorkers.filter((w) => w.queue === queue)
+              return {
+                queue,
+                concurrency: concurrencyOverride ?? Math.max(...queueWorkers.map((w) => w.concurrency), 1),
+              }
+            })
+            const budgetPlan = await resolveWorkerBudgetPlan(requestedByQueue)
+            const effectiveByQueue = new Map(
+              budgetPlan.entries.map((entry) => [entry.queue, entry.effective]),
+            )
+
             console.log(`[worker] Starting workers for all queues: ${discoveredQueues.join(', ')}`)
 
             // Start all queue workers in background mode
             const workerPromises = discoveredQueues.map(async (queue) => {
               const queueWorkers = allWorkers.filter((w) => w.queue === queue)
-              const concurrency = concurrencyOverride ?? Math.max(...queueWorkers.map((w) => w.concurrency), 1)
+              const concurrency =
+                effectiveByQueue.get(queue) ??
+                concurrencyOverride ??
+                Math.max(...queueWorkers.map((w) => w.concurrency), 1)
 
               console.log(`[worker] Starting "${queue}" with ${queueWorkers.length} handler(s), concurrency: ${concurrency}`)
 
@@ -1552,7 +1617,11 @@ export async function run(argv = process.argv) {
             if (queueWorkers.length > 0) {
               // Use discovered workers
               const { createRequestContainer } = await import('@open-mercato/shared/lib/di/container')
-              const concurrency = concurrencyOverride ?? Math.max(...queueWorkers.map((w) => w.concurrency), 1)
+              const requested = concurrencyOverride ?? Math.max(...queueWorkers.map((w) => w.concurrency), 1)
+              // Bound a single-queue run to the connection budget too, so it can
+              // never check out more pooled connections than the worker pool holds.
+              const budgetPlan = await resolveWorkerBudgetPlan([{ queue: queueName!, concurrency: requested }])
+              const concurrency = budgetPlan.entries[0]?.effective ?? requested
 
               console.log(`[worker] Found ${queueWorkers.length} worker(s) for queue "${queueName}"`)
 
@@ -1993,6 +2062,12 @@ export async function run(argv = process.argv) {
               envReloader.reload()
               const runtimeEnv = buildServerProcessEnvironment(process.env)
               const autoSpawnWorkersMode = resolveAutoSpawnWorkersMode(process.env)
+              // Guard the default-on events single-delivery: if this process runs
+              // no events worker, fall back to safe inline dual-dispatch so
+              // persistent side effects are never silently dropped. Mutates both
+              // process.env (in-process bus) and runtimeEnv (spawned workers) so
+              // they agree.
+              applyEventsSingleDeliveryGuard({ processEnv: process.env, runtimeEnv, autoSpawnWorkersMode })
               const autoSpawnSchedulerMode = resolveAutoSpawnSchedulerMode(process.env)
               const queueStrategy = process.env.QUEUE_STRATEGY || 'local'
               const schedulerCommand = lookupModuleCommand(getCliModules(), 'scheduler', 'start')
@@ -2146,6 +2221,10 @@ export async function run(argv = process.argv) {
           const autoSpawnSchedulerMode = resolveAutoSpawnSchedulerMode(process.env)
           const queueStrategy = process.env.QUEUE_STRATEGY || 'local'
           const runtimeEnv = buildServerProcessEnvironment(process.env)
+          // Guard the default-on events single-delivery (see the dev `server`
+          // command): fall back to safe inline dual-dispatch when this process
+          // runs no events worker, keeping process.env and runtimeEnv in sync.
+          applyEventsSingleDeliveryGuard({ processEnv: process.env, runtimeEnv, autoSpawnWorkersMode })
           // Throws on single-instance strategies under a multi-instance topology,
           // aborting before the start lock is acquired or any process is spawned.
           assertSingleInstanceStrategies(runtimeEnv)