@open-mercato/cli 0.6.6-develop.5509.1.006f4d4f24 → 0.6.6-develop.5531.1.ab1959dfae

package/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
-[build:cli] found 87 entry points
+[build:cli] found 89 entry points
 Copied create-app/agentic/ → dist/agentic/
 Discovered 16 standalone guides → dist/agentic/guides/
 [build:cli] built successfully

package/dist/agentic/shared/ai/skills/om-troubleshooter/SKILL.md

@@ -39,7 +39,7 @@ When the developer reports a problem, follow this order:
 
 ### Step 2: Check Generated Files
 
-Run these commands first — they fix 60%+ of issues:
+These commands fix 60%+ of issues, so they are usually the first fix to propose (they are mutating — propose, then run after confirmation per [Step 4](#step-4-propose-before-fixing)):
 
 ```bash
 yarn generate          # Regenerate module discovery files
@@ -61,6 +61,28 @@ ls .mercato/generated/
 yarn typecheck
 ```
 
+### Step 4: Propose Before Fixing
+
+Once you have diagnosed the root cause, **do not apply the fix immediately**. First present:
+
+1. The **root cause** — what is actually broken and why.
+2. The **proposed fix** — the exact commands and/or code changes you intend to apply.
+
+Then **wait for explicit user confirmation** before applying any **mutating** change. This keeps the developer in control and avoids surprise edits, migrations, or restarts.
+
+**Read-only diagnostics may run without asking** — they only gather information and change nothing:
+
+| Allowed without confirmation (read-only) | Requires confirmation (mutating) |
+|------------------------------------------|----------------------------------|
+| `yarn typecheck` | `yarn generate` |
+| `grep` / file reads / `ls` | `yarn db:generate` |
+| log / browser-console inspection | `yarn db:migrate` |
+| `docker compose ps` | editing files |
+| `curl` against a running endpoint (GET) | restarting the dev server (`yarn dev`) |
+| | `docker compose up` |
+
+When in doubt about whether an action mutates state, treat it as mutating and ask first. Once the user confirms, apply the fix and verify it.
+
 ---
 
 ## 2. Module Issues
@@ -76,24 +98,24 @@ yarn typecheck
    // Must have this entry:
    { id: '<module_id>', from: '@app' }
    ```
-   Fix: Add the entry and run `yarn generate`.
+   Proposed fix: Add the entry and run `yarn generate`.
 
 2. **Did you run `yarn generate`?**
    Check if `.mercato/generated/` contains your module's entries.
-   Fix: Run `yarn generate`.
+   Proposed fix: Run `yarn generate`.
 
 3. **Is the module folder named correctly?**
    Must be plural, snake_case: `src/modules/<module_id>/`
-   Fix: Rename folder to match module ID.
+   Proposed fix: Rename folder to match module ID.
 
 4. **Does `index.ts` export `metadata`?**
    ```typescript
    export const metadata: ModuleInfo = { name: '<module_id>', ... }
    ```
-   Fix: Add the metadata export.
+   Proposed fix: Add the metadata export.
 
 5. **Is the dev server running with latest changes?**
-   Fix: Restart with `yarn dev`.
+   Proposed fix: Restart with `yarn dev`.
 
 ### Module loads but pages 404
 
@@ -104,17 +126,17 @@ yarn typecheck
 1. **Are backend page files in the right location?**
    - List page: `backend/page.tsx` (not `backend/index.tsx`)
    - Detail page: `backend/<entities>/[id].tsx` (bracket notation)
-   Fix: Rename to match auto-discovery convention.
+   Proposed fix: Rename to match auto-discovery convention.
 
 2. **Do pages export `metadata` with `requireAuth`?**
    ```typescript
    export const metadata = { requireAuth: true, features: ['<module_id>.view'] }
    ```
-   Fix: Add metadata export.
+   Proposed fix: Add metadata export.
 
 3. **Does the user have the required ACL features?**
    Check `setup.ts` has `defaultRoleFeatures` for the user's role.
-   Fix: Add features to role defaults, re-run setup.
+   Proposed fix: Add features to role defaults, re-run setup.
 
 ---
 
@@ -130,22 +152,22 @@ yarn typecheck
    ```bash
    yarn db:generate     # Probes/creates migration file
    ```
-   Fix: Run `yarn db:generate` to inspect the required migration, then keep only the scoped SQL for your module and update `src/modules/<module_id>/migrations/.snapshot-open-mercato.json`.
+   Proposed fix: Run `yarn db:generate` to inspect the required migration, then keep only the scoped SQL for your module and update `src/modules/<module_id>/migrations/.snapshot-open-mercato.json`.
 
 2. **Is the entity declared in the right file with the right imports?**
    Entity classes belong in `src/modules/<module_id>/data/entities.ts` and decorators must come from `@mikro-orm/decorators/legacy`.
-   Fix: move stale `entities/<Entity>.ts` patterns into `data/entities.ts` and fix the imports before regenerating the migration.
+   Proposed fix: move stale `entities/<Entity>.ts` patterns into `data/entities.ts` and fix the imports before regenerating the migration.
 
 3. **Did you apply the migration?**
    ```bash
    yarn db:migrate      # Applies pending migrations
    ```
-   Fix: Run `yarn db:migrate`.
+   Proposed fix: Run `yarn db:migrate`.
 
 4. **Is the migration file correct?**
    Check `src/modules/<module_id>/migrations/` for the latest migration.
    Verify it has the expected columns and types.
-   Fix: If wrong, delete the migration file, fix the entity, and regenerate.
+   Proposed fix: If wrong, delete the migration file, fix the entity, and regenerate.
 
 ### Migration generation creates unexpected changes
 
@@ -160,11 +182,11 @@ yarn typecheck
 
 2. **Did you modify a core module entity without ejecting?**
    Never edit `node_modules/@open-mercato/*`.
-   Fix: Revert changes to node_modules. Use UMES extensions instead, or eject the module.
+   Proposed fix: Revert changes to node_modules. Use UMES extensions instead, or eject the module.
 
 3. **Is a module snapshot stale?**
    Check whether the generated SQL recreates a table or column that already has a committed migration.
-   Fix: update that module's `migrations/.snapshot-open-mercato.json` to include the already-migrated schema, then re-run `yarn db:generate` and expect `no changes`.
+   Proposed fix: update that module's `migrations/.snapshot-open-mercato.json` to include the already-migrated schema, then re-run `yarn db:generate` and expect `no changes`.
 
 ### Entity changes not reflected
 
@@ -443,9 +465,10 @@ yarn dev               # 5. Restart dev server
 
 ## Rules
 
-- **ALWAYS** run `yarn generate` as first diagnostic step
+- **ALWAYS** present the diagnosed root cause and the proposed fix (commands/code), then **wait for explicit user confirmation before applying any mutating change** (see [Step 4](#step-4-propose-before-fixing)). Only read-only diagnostics may run without asking.
 - **ALWAYS** check server logs / browser console for actual error messages
 - **NEVER** edit files in `.mercato/generated/` or `node_modules/`
 - **NEVER** assume the issue — verify with actual error output
+- Treat `yarn generate` as the most likely first fix, but propose it before running — it regenerates files and is a mutating action
 - Fix the root cause, not the symptom — temporary workarounds become permanent bugs
-- When suggesting a fix, include the exact command or code change needed
+- When proposing a fix, include the exact command or code change needed

package/dist/lib/single-instance-strategy-guard.js

@@ -0,0 +1,89 @@
+import { parseBooleanWithDefault } from "@open-mercato/shared/lib/boolean";
+import { resolveQueueStrategy } from "@open-mercato/queue";
+const MULTI_INSTANCE_SAFE_STRATEGIES = {
+  cache: ["redis"],
+  queue: ["async"],
+  rateLimit: ["redis"]
+};
+const COMPONENT_ENV_VARS = {
+  cache: "CACHE_STRATEGY",
+  queue: "QUEUE_STRATEGY",
+  rateLimit: "RATE_LIMIT_STRATEGY"
+};
+class SingleInstanceStrategyError extends Error {
+  constructor(result) {
+    super(
+      `Refusing to start: single-instance infrastructure strategies (${result.offenders.map((offender) => `${offender.envVar}=${offender.configured}`).join(", ")}) are configured under a declared multi-instance topology. Switch to a multi-instance-safe strategy or set OM_ALLOW_SINGLE_INSTANCE_STRATEGIES=1 to override.`
+    );
+    this.name = "SingleInstanceStrategyError";
+    this.offenders = result.offenders;
+  }
+}
+function readInfraStrategySnapshot(env = process.env) {
+  return {
+    cacheStrategy: env.CACHE_STRATEGY?.trim() || "memory",
+    queueStrategy: resolveQueueStrategy(),
+    rateLimitStrategy: env.RATE_LIMIT_STRATEGY?.trim() || "memory"
+  };
+}
+function resolveMultiInstanceHint(env) {
+  if (parseBooleanWithDefault(env.OM_MULTI_INSTANCE, false)) return true;
+  const instanceCount = Number.parseInt(env.OM_INSTANCE_COUNT ?? "", 10);
+  return Number.isFinite(instanceCount) && instanceCount > 1;
+}
+function evaluateSingleInstanceGuard(snapshot, env = process.env) {
+  const configured = {
+    cache: snapshot.cacheStrategy,
+    queue: snapshot.queueStrategy,
+    rateLimit: snapshot.rateLimitStrategy
+  };
+  const offenders = [];
+  for (const component of Object.keys(configured)) {
+    const safeValues = MULTI_INSTANCE_SAFE_STRATEGIES[component];
+    if (!safeValues.includes(configured[component])) {
+      offenders.push({
+        component,
+        envVar: COMPONENT_ENV_VARS[component],
+        configured: configured[component],
+        safeValues
+      });
+    }
+  }
+  const production = (env.NODE_ENV ?? "").trim() === "production";
+  const multiInstance = resolveMultiInstanceHint(env);
+  const overridden = parseBooleanWithDefault(env.OM_ALLOW_SINGLE_INSTANCE_STRATEGIES, false);
+  let action = "ok";
+  if (offenders.length > 0 && production) {
+    action = multiInstance && !overridden ? "fail" : "warn";
+  }
+  return { action, offenders, production, multiInstance, overridden };
+}
+function formatSingleInstanceGuardMessage(result) {
+  const offenderLines = result.offenders.map(
+    (offender) => `  - ${offender.envVar}=${offender.configured} (multi-instance-safe: ${offender.safeValues.join(", ")})`
+  );
+  const header = result.action === "fail" ? "[server] Refusing to start: single-instance infrastructure strategies under a multi-instance topology." : "[server] WARNING: single-instance infrastructure strategies detected in production.";
+  const guidance = result.action === "fail" ? "[server] Switch each strategy above to a multi-instance-safe value, or set OM_ALLOW_SINGLE_INSTANCE_STRATEGIES=1 to override (accepting duplicate jobs, stale ACLs, and weakened rate limits)." : result.multiInstance ? "[server] OM_ALLOW_SINGLE_INSTANCE_STRATEGIES=1 is set \u2014 proceeding despite the risks above (duplicate jobs, stale ACLs, weakened rate limits)." : "[server] Running multiple instances against these strategies will cause duplicate jobs, stale ACLs, and weakened rate limits. Set OM_MULTI_INSTANCE=1 to make this a hard failure once you scale out.";
+  return [header, ...offenderLines, guidance];
+}
+function assertSingleInstanceStrategies(env = process.env, options) {
+  const snapshot = options?.snapshot ?? readInfraStrategySnapshot(env);
+  const result = evaluateSingleInstanceGuard(snapshot, env);
+  const logger = options?.logger ?? console;
+  if (result.action === "fail") {
+    for (const line of formatSingleInstanceGuardMessage(result)) logger.error(line);
+    throw new SingleInstanceStrategyError(result);
+  }
+  if (result.action === "warn") {
+    for (const line of formatSingleInstanceGuardMessage(result)) logger.warn(line);
+  }
+  return result;
+}
+export {
+  SingleInstanceStrategyError,
+  assertSingleInstanceStrategies,
+  evaluateSingleInstanceGuard,
+  formatSingleInstanceGuardMessage,
+  readInfraStrategySnapshot
+};
+//# sourceMappingURL=single-instance-strategy-guard.js.map

package/dist/lib/single-instance-strategy-guard.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/lib/single-instance-strategy-guard.ts"],
+  "sourcesContent": ["import { parseBooleanWithDefault } from '@open-mercato/shared/lib/boolean'\nimport { resolveQueueStrategy } from '@open-mercato/queue'\n\n/**\n * Boot-time guard that refuses to start (or warns) when an infrastructure\n * strategy that is only safe for a single process/instance is configured under\n * a declared multi-instance topology.\n *\n * Background: `CACHE_STRATEGY`, `RATE_LIMIT_STRATEGY` and `QUEUE_STRATEGY` all\n * default to single-instance modes (`memory`/`memory`/`local`). Running more\n * than one app instance against those defaults silently breaks three\n * correctness invariants at once \u2014 stale RBAC caches after a privilege\n * revocation, rate limits multiplied by the instance count, and duplicate job\n * processing from the leaderless local file queue. None of them warn.\n *\n * Only strategies that coordinate across processes via shared external state\n * are considered multi-instance safe. Everything else (the in-process memory\n * strategies, the local file queue, and disk-backed caches that are not shared\n * across hosts) is treated as single-instance.\n */\nconst MULTI_INSTANCE_SAFE_STRATEGIES = {\n  cache: ['redis'],\n  queue: ['async'],\n  rateLimit: ['redis'],\n} as const\n\nexport type SingleInstanceGuardComponent = 'cache' | 'queue' | 'rateLimit'\n\nexport type SingleInstanceGuardOffender = {\n  component: SingleInstanceGuardComponent\n  envVar: string\n  configured: string\n  safeValues: readonly string[]\n}\n\nexport type SingleInstanceGuardAction = 'ok' | 'warn' | 'fail'\n\nexport type SingleInstanceGuardResult = {\n  action: SingleInstanceGuardAction\n  offenders: SingleInstanceGuardOffender[]\n  production: boolean\n  multiInstance: boolean\n  overridden: boolean\n}\n\nexport type InfraStrategySnapshot = {\n  cacheStrategy: string\n  queueStrategy: string\n  rateLimitStrategy: string\n}\n\nconst COMPONENT_ENV_VARS: Record<SingleInstanceGuardComponent, string> = {\n  cache: 'CACHE_STRATEGY',\n  queue: 'QUEUE_STRATEGY',\n  rateLimit: 'RATE_LIMIT_STRATEGY',\n}\n\nexport class SingleInstanceStrategyError extends Error {\n  readonly offenders: SingleInstanceGuardOffender[]\n\n  constructor(result: SingleInstanceGuardResult) {\n    super(\n      `Refusing to start: single-instance infrastructure strategies (${result.offenders\n        .map((offender) => `${offender.envVar}=${offender.configured}`)\n        .join(', ')}) are configured under a declared multi-instance topology. ` +\n        'Switch to a multi-instance-safe strategy or set OM_ALLOW_SINGLE_INSTANCE_STRATEGIES=1 to override.',\n    )\n    this.name = 'SingleInstanceStrategyError'\n    this.offenders = result.offenders\n  }\n}\n\n/**\n * Read the configured infrastructure strategies. Queue resolution reuses the\n * canonical `resolveQueueStrategy()` so the default stays single-sourced; cache\n * and rate-limit values are read directly with their documented defaults\n * (`packages/cache/src/service.ts`, `packages/shared/src/lib/ratelimit/config.ts`)\n * because the guard's safe-set policy \u2014 not the resolver default \u2014 decides what\n * counts as single-instance.\n */\nexport function readInfraStrategySnapshot(env: NodeJS.ProcessEnv = process.env): InfraStrategySnapshot {\n  return {\n    cacheStrategy: env.CACHE_STRATEGY?.trim() || 'memory',\n    queueStrategy: resolveQueueStrategy(),\n    rateLimitStrategy: env.RATE_LIMIT_STRATEGY?.trim() || 'memory',\n  }\n}\n\nfunction resolveMultiInstanceHint(env: NodeJS.ProcessEnv): boolean {\n  if (parseBooleanWithDefault(env.OM_MULTI_INSTANCE, false)) return true\n  const instanceCount = Number.parseInt(env.OM_INSTANCE_COUNT ?? '', 10)\n  return Number.isFinite(instanceCount) && instanceCount > 1\n}\n\nexport function evaluateSingleInstanceGuard(\n  snapshot: InfraStrategySnapshot,\n  env: NodeJS.ProcessEnv = process.env,\n): SingleInstanceGuardResult {\n  const configured: Record<SingleInstanceGuardComponent, string> = {\n    cache: snapshot.cacheStrategy,\n    queue: snapshot.queueStrategy,\n    rateLimit: snapshot.rateLimitStrategy,\n  }\n\n  const offenders: SingleInstanceGuardOffender[] = []\n  for (const component of Object.keys(configured) as SingleInstanceGuardComponent[]) {\n    const safeValues: readonly string[] = MULTI_INSTANCE_SAFE_STRATEGIES[component]\n    if (!safeValues.includes(configured[component])) {\n      offenders.push({\n        component,\n        envVar: COMPONENT_ENV_VARS[component],\n        configured: configured[component],\n        safeValues,\n      })\n    }\n  }\n\n  const production = (env.NODE_ENV ?? '').trim() === 'production'\n  const multiInstance = resolveMultiInstanceHint(env)\n  const overridden = parseBooleanWithDefault(env.OM_ALLOW_SINGLE_INSTANCE_STRATEGIES, false)\n\n  let action: SingleInstanceGuardAction = 'ok'\n  if (offenders.length > 0 && production) {\n    action = multiInstance && !overridden ? 'fail' : 'warn'\n  }\n\n  return { action, offenders, production, multiInstance, overridden }\n}\n\nexport function formatSingleInstanceGuardMessage(result: SingleInstanceGuardResult): string[] {\n  const offenderLines = result.offenders.map(\n    (offender) =>\n      `  - ${offender.envVar}=${offender.configured} (multi-instance-safe: ${offender.safeValues.join(', ')})`,\n  )\n  const header =\n    result.action === 'fail'\n      ? '[server] Refusing to start: single-instance infrastructure strategies under a multi-instance topology.'\n      : '[server] WARNING: single-instance infrastructure strategies detected in production.'\n  const guidance =\n    result.action === 'fail'\n      ? '[server] Switch each strategy above to a multi-instance-safe value, or set OM_ALLOW_SINGLE_INSTANCE_STRATEGIES=1 to override (accepting duplicate jobs, stale ACLs, and weakened rate limits).'\n      : result.multiInstance\n        ? '[server] OM_ALLOW_SINGLE_INSTANCE_STRATEGIES=1 is set \u2014 proceeding despite the risks above (duplicate jobs, stale ACLs, weakened rate limits).'\n        : '[server] Running multiple instances against these strategies will cause duplicate jobs, stale ACLs, and weakened rate limits. Set OM_MULTI_INSTANCE=1 to make this a hard failure once you scale out.'\n  return [header, ...offenderLines, guidance]\n}\n\nexport type SingleInstanceGuardLogger = Pick<Console, 'warn' | 'error'>\n\n/**\n * Evaluate the guard and enforce it: throw on `fail`, log prominently on\n * `warn`, and stay silent on `ok`. Safe to call on every `start`; it never\n * fires for dev boots or single-instance production deployments.\n */\nexport function assertSingleInstanceStrategies(\n  env: NodeJS.ProcessEnv = process.env,\n  options?: { snapshot?: InfraStrategySnapshot; logger?: SingleInstanceGuardLogger },\n): SingleInstanceGuardResult {\n  const snapshot = options?.snapshot ?? readInfraStrategySnapshot(env)\n  const result = evaluateSingleInstanceGuard(snapshot, env)\n  const logger = options?.logger ?? console\n\n  if (result.action === 'fail') {\n    for (const line of formatSingleInstanceGuardMessage(result)) logger.error(line)\n    throw new SingleInstanceStrategyError(result)\n  }\n  if (result.action === 'warn') {\n    for (const line of formatSingleInstanceGuardMessage(result)) logger.warn(line)\n  }\n\n  return result\n}\n"],
+  "mappings": "AAAA,SAAS,+BAA+B;AACxC,SAAS,4BAA4B;AAmBrC,MAAM,iCAAiC;AAAA,EACrC,OAAO,CAAC,OAAO;AAAA,EACf,OAAO,CAAC,OAAO;AAAA,EACf,WAAW,CAAC,OAAO;AACrB;AA2BA,MAAM,qBAAmE;AAAA,EACvE,OAAO;AAAA,EACP,OAAO;AAAA,EACP,WAAW;AACb;AAEO,MAAM,oCAAoC,MAAM;AAAA,EAGrD,YAAY,QAAmC;AAC7C;AAAA,MACE,iEAAiE,OAAO,UACrE,IAAI,CAAC,aAAa,GAAG,SAAS,MAAM,IAAI,SAAS,UAAU,EAAE,EAC7D,KAAK,IAAI,CAAC;AAAA,IAEf;AACA,SAAK,OAAO;AACZ,SAAK,YAAY,OAAO;AAAA,EAC1B;AACF;AAUO,SAAS,0BAA0B,MAAyB,QAAQ,KAA4B;AACrG,SAAO;AAAA,IACL,eAAe,IAAI,gBAAgB,KAAK,KAAK;AAAA,IAC7C,eAAe,qBAAqB;AAAA,IACpC,mBAAmB,IAAI,qBAAqB,KAAK,KAAK;AAAA,EACxD;AACF;AAEA,SAAS,yBAAyB,KAAiC;AACjE,MAAI,wBAAwB,IAAI,mBAAmB,KAAK,EAAG,QAAO;AAClE,QAAM,gBAAgB,OAAO,SAAS,IAAI,qBAAqB,IAAI,EAAE;AACrE,SAAO,OAAO,SAAS,aAAa,KAAK,gBAAgB;AAC3D;AAEO,SAAS,4BACd,UACA,MAAyB,QAAQ,KACN;AAC3B,QAAM,aAA2D;AAAA,IAC/D,OAAO,SAAS;AAAA,IAChB,OAAO,SAAS;AAAA,IAChB,WAAW,SAAS;AAAA,EACtB;AAEA,QAAM,YAA2C,CAAC;AAClD,aAAW,aAAa,OAAO,KAAK,UAAU,GAAqC;AACjF,UAAM,aAAgC,+BAA+B,SAAS;AAC9E,QAAI,CAAC,WAAW,SAAS,WAAW,SAAS,CAAC,GAAG;AAC/C,gBAAU,KAAK;AAAA,QACb;AAAA,QACA,QAAQ,mBAAmB,SAAS;AAAA,QACpC,YAAY,WAAW,SAAS;AAAA,QAChC;AAAA,MACF,CAAC;AAAA,IACH;AAAA,EACF;AAEA,QAAM,cAAc,IAAI,YAAY,IAAI,KAAK,MAAM;AACnD,QAAM,gBAAgB,yBAAyB,GAAG;AAClD,QAAM,aAAa,wBAAwB,IAAI,qCAAqC,KAAK;AAEzF,MAAI,SAAoC;AACxC,MAAI,UAAU,SAAS,KAAK,YAAY;AACtC,aAAS,iBAAiB,CAAC,aAAa,SAAS;AAAA,EACnD;AAEA,SAAO,EAAE,QAAQ,WAAW,YAAY,eAAe,WAAW;AACpE;AAEO,SAAS,iCAAiC,QAA6C;AAC5F,QAAM,gBAAgB,OAAO,UAAU;AAAA,IACrC,CAAC,aACC,OAAO,SAAS,MAAM,IAAI,SAAS,UAAU,0BAA0B,SAAS,WAAW,KAAK,IAAI,CAAC;AAAA,EACzG;AACA,QAAM,SACJ,OAAO,WAAW,SACd,2GACA;AACN,QAAM,WACJ,OAAO,WAAW,SACd,mMACA,OAAO,gBACL,wJACA;AACR,SAAO,CAAC,QAAQ,GAAG,eAAe,QAAQ;AAC5C;AASO,SAAS,+BACd,MAAyB,QAAQ,KACjC,SAC2B;AAC3B,QAAM,WAAW,SAAS,YAAY,0BAA0B,GAAG;AACnE,QAAM,SAAS,4BAA4B,UAAU,GAAG;AACxD,QAAM,SAAS,SAAS,UAAU;AAElC,MAAI,OAAO,WAAW,QAAQ;AAC5B,eAAW,QAAQ,iCAAiC,MAAM,EAAG,QAAO,MAAM,IAAI;AAC9E,UAAM,IAAI,4BAA4B,MAAM;AAAA,EAC9C;AACA,MAAI,OAAO,WAAW,QAAQ;AAC5B,eAAW,QAAQ,iCAAiC,MAAM,EAAG,QAAO,KAAK,IAAI;AAAA,EAC/E;AAEA,SAAO;AACT;",
+  "names": []
+}

package/dist/lib/worker-job-handler.js

@@ -0,0 +1,20 @@
+function createPerJobWorkerHandler(workers, createContainer) {
+  return async (job, ctx) => {
+    const container = await createContainer();
+    try {
+      for (const worker of workers) {
+        await worker.handler(job, { ...ctx, resolve: container.resolve.bind(container) });
+      }
+    } finally {
+      try {
+        const em = container.resolve("em");
+        em?.clear?.();
+      } catch {
+      }
+    }
+  };
+}
+export {
+  createPerJobWorkerHandler
+};
+//# sourceMappingURL=worker-job-handler.js.map

package/dist/lib/worker-job-handler.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/lib/worker-job-handler.ts"],
+  "sourcesContent": ["import type { JobContext, JobHandler } from '@open-mercato/queue'\nimport type { ModuleWorker } from '@open-mercato/shared/modules/registry'\n\nexport type WorkerJobContainer = {\n  resolve: <T = unknown>(name: string) => T\n}\n\nexport type WorkerJobContainerFactory = () => Promise<WorkerJobContainer>\n\ntype ClearableEntityManager = {\n  clear?: () => void\n}\n\n/**\n * Builds a queue job handler that isolates every job in its own request\n * container, instead of sharing a single process-wide `EntityManager` fork\n * across all concurrent jobs.\n *\n * Under the async (BullMQ) strategy jobs run with real concurrency, so a\n * shared EM would interleave unit-of-work flushes between unrelated jobs and\n * never release its identity map. Creating one container per job removes both\n * the cross-job flush race and the unbounded identity-map growth, while\n * keeping the `ctx.resolve` contract and DI keys unchanged. See issue #2970.\n */\nexport function createPerJobWorkerHandler(\n  workers: ModuleWorker[],\n  createContainer: WorkerJobContainerFactory,\n): JobHandler {\n  return async (job, ctx: JobContext) => {\n    const container = await createContainer()\n    try {\n      for (const worker of workers) {\n        await worker.handler(job, { ...ctx, resolve: container.resolve.bind(container) })\n      }\n    } finally {\n      try {\n        const em = container.resolve('em') as ClearableEntityManager | null\n        em?.clear?.()\n      } catch {\n        // Best-effort: clearing the identity map is a memory optimization and\n        // must never mask a job's own outcome.\n      }\n    }\n  }\n}\n"],
+  "mappings": "AAwBO,SAAS,0BACd,SACA,iBACY;AACZ,SAAO,OAAO,KAAK,QAAoB;AACrC,UAAM,YAAY,MAAM,gBAAgB;AACxC,QAAI;AACF,iBAAW,UAAU,SAAS;AAC5B,cAAM,OAAO,QAAQ,KAAK,EAAE,GAAG,KAAK,SAAS,UAAU,QAAQ,KAAK,SAAS,EAAE,CAAC;AAAA,MAClF;AAAA,IACF,UAAE;AACA,UAAI;AACF,cAAM,KAAK,UAAU,QAAQ,IAAI;AACjC,YAAI,QAAQ;AAAA,MACd,QAAQ;AAAA,MAGR;AAAA,IACF;AAAA,EACF;AACF;",
+  "names": []
+}

package/dist/mercato.js

@@ -10,6 +10,7 @@ import {
   resolveLazyRestart
 } from "./lib/auto-spawn-workers.js";
 import { startLazyWorkerSupervisor } from "./lib/queue-worker-supervisor.js";
+import { createPerJobWorkerHandler } from "./lib/worker-job-handler.js";
 import {
   resolveAutoSpawnSchedulerMode,
   resolveLazySchedulerPollMs,
@@ -25,6 +26,7 @@ import {
 import { parseModuleInstallArgs } from "./lib/module-install-args.js";
 import { resolveNextBuildIdCandidate } from "./lib/next-build-id.js";
 import { acquireServerStartLock } from "./lib/server-start-lock.js";
+import { assertSingleInstanceStrategies } from "./lib/single-instance-strategy-guard.js";
 import { createDevEnvReloader, watchDevEnvFiles } from "./lib/dev-env-reload.js";
 const lazyIntegration = () => import("./lib/testing/integration.js");
 import path from "node:path";
@@ -1224,7 +1226,6 @@ async function run(argv = process.argv) {
               return;
             }
             const { createRequestContainer } = await import("@open-mercato/shared/lib/di/container");
-            const container = await createRequestContainer();
             console.log(`[worker] Starting workers for all queues: ${discoveredQueues.join(", ")}`);
             const workerPromises = discoveredQueues.map(async (queue) => {
               const queueWorkers = allWorkers.filter((w) => w.queue === queue);
@@ -1236,11 +1237,7 @@ async function run(argv = process.argv) {
                 connection: queueRedisUrl ? { url: queueRedisUrl } : void 0,
                 concurrency,
                 background: true,
-                handler: async (job, ctx) => {
-                  for (const worker of queueWorkers) {
-                    await worker.handler(job, { ...ctx, resolve: container.resolve.bind(container) });
-                  }
-                }
+                handler: createPerJobWorkerHandler(queueWorkers, createRequestContainer)
               });
             });
             await Promise.all(workerPromises);
@@ -1251,7 +1248,6 @@ async function run(argv = process.argv) {
             const queueWorkers = allWorkers.filter((w) => w.queue === queueName);
             if (queueWorkers.length > 0) {
               const { createRequestContainer } = await import("@open-mercato/shared/lib/di/container");
-              const container = await createRequestContainer();
               const concurrency = concurrencyOverride ?? Math.max(...queueWorkers.map((w) => w.concurrency), 1);
               console.log(`[worker] Found ${queueWorkers.length} worker(s) for queue "${queueName}"`);
               const queueRedisUrl = getRedisUrl("QUEUE");
@@ -1259,11 +1255,7 @@ async function run(argv = process.argv) {
                 queueName,
                 connection: queueRedisUrl ? { url: queueRedisUrl } : void 0,
                 concurrency,
-                handler: async (job, ctx) => {
-                  for (const worker of queueWorkers) {
-                    await worker.handler(job, { ...ctx, resolve: container.resolve.bind(container) });
-                  }
-                }
+                handler: createPerJobWorkerHandler(queueWorkers, createRequestContainer)
               });
             } else {
               console.error(`No workers found for queue "${queueName}"`);
@@ -1781,6 +1773,7 @@ async function run(argv = process.argv) {
           const autoSpawnSchedulerMode = resolveAutoSpawnSchedulerMode(process.env);
           const queueStrategy = process.env.QUEUE_STRATEGY || "local";
           const runtimeEnv = buildServerProcessEnvironment(process.env);
+          assertSingleInstanceStrategies(runtimeEnv);
           const schedulerCommand = lookupModuleCommand(getCliModules(), "scheduler", "start");
           const serverStartLock = acquireServerStartLock(appDir, {
             port: runtimeEnv.PORT ?? process.env.PORT ?? null