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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/cli",
-  "version": "0.6.8-develop.7015.1.af90a2ddc7",
+  "version": "0.6.8-develop.7019.1.f4c01c4b5c",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -60,9 +60,9 @@
     "@mikro-orm/decorators": "^7.1.8",
     "@mikro-orm/migrations": "^7.1.8",
     "@mikro-orm/postgresql": "^7.1.8",
-    "@open-mercato/queue": "0.6.8-develop.7015.1.af90a2ddc7",
-    "@open-mercato/shared": "0.6.8-develop.7015.1.af90a2ddc7",
-    "@open-mercato/telemetry": "0.6.8-develop.7015.1.af90a2ddc7",
+    "@open-mercato/queue": "0.6.8-develop.7019.1.f4c01c4b5c",
+    "@open-mercato/shared": "0.6.8-develop.7019.1.f4c01c4b5c",
+    "@open-mercato/telemetry": "0.6.8-develop.7019.1.f4c01c4b5c",
     "cross-spawn": "^7.0.6",
     "pg": "8.22.0",
     "semver": "^7.8.5",
@@ -73,10 +73,10 @@
     "typescript-js": "npm:typescript@6.0.3"
   },
   "peerDependencies": {
-    "@open-mercato/shared": "0.6.8-develop.7015.1.af90a2ddc7"
+    "@open-mercato/shared": "0.6.8-develop.7019.1.f4c01c4b5c"
   },
   "devDependencies": {
-    "@open-mercato/shared": "0.6.8-develop.7015.1.af90a2ddc7",
+    "@open-mercato/shared": "0.6.8-develop.7019.1.f4c01c4b5c",
     "@types/jest": "^30.0.0",
     "jest": "^30.4.2",
     "ts-jest": "^29.4.12"

package/src/__tests__/resolve-queue-abandon-hook.test.ts

@@ -0,0 +1,39 @@
+import { resolveQueueAbandonHook } from '../mercato'
+
+/**
+ * Covers the CLI's per-queue pick, which is the last link between worker metadata and the queue the
+ * worker runs on. The warning exists because two handlers on one queue each expecting to report is a
+ * wiring mistake, and a silent first-wins would hide it.
+ */
+describe('resolveQueueAbandonHook', () => {
+  const hookA = jest.fn(async () => {})
+  const hookB = jest.fn(async () => {})
+
+  it('returns undefined when no worker declares one', () => {
+    const warn = jest.fn()
+    expect(resolveQueueAbandonHook('q', [{ id: 'a' }, { id: 'b' }], warn)).toBeUndefined()
+    expect(warn).not.toHaveBeenCalled()
+  })
+
+  it('returns the single declared callback without warning', () => {
+    const warn = jest.fn()
+    expect(resolveQueueAbandonHook('q', [{ id: 'a' }, { id: 'b', onJobAbandoned: hookA }], warn)).toBe(hookA)
+    expect(warn).not.toHaveBeenCalled()
+  })
+
+  it('keeps the first and warns, naming the queue and every declaring worker', () => {
+    const warn = jest.fn()
+    const picked = resolveQueueAbandonHook(
+      'data-sync-import',
+      [{ id: 'first', onJobAbandoned: hookA }, { id: 'second', onJobAbandoned: hookB }],
+      warn,
+    )
+
+    expect(picked).toBe(hookA)
+    expect(warn).toHaveBeenCalledTimes(1)
+    const message = warn.mock.calls[0][0] as string
+    expect(message).toContain('data-sync-import')
+    expect(message).toContain('first')
+    expect(message).toContain('second')
+  })
+})

package/src/lib/generators/__tests__/generated-registry-imports.test.ts

@@ -0,0 +1,128 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import os from 'node:os'
+import type { PackageResolver, ModuleEntry } from '../../resolver'
+import { generateModuleRegistry, generateModuleRegistryApp, generateModuleRegistryCli } from '../module-registry'
+
+/**
+ * The generator's output, not its helpers.
+ *
+ * A worker declaring `metadata.onJobAbandoned` makes the registry emit
+ * `createLazyModuleWorkerAbandonHook(...)`, and the import for it used to be opted into per render
+ * site. Forgetting it at one of the six sites produced a file referencing an undeclared name, which
+ * type-checks nowhere and surfaces only at `build:app` — every unit test stayed green because no
+ * fixture declared such a worker.
+ *
+ * These assertions are driven off the files the generators actually wrote, so a renderer added later
+ * is covered without anyone remembering to extend this test.
+ */
+
+let tmpDir: string
+
+function touchFile(filePath: string, content = ''): void {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true })
+  fs.writeFileSync(filePath, content)
+}
+
+function createMockResolver(dir: string, enabled: ModuleEntry[]): PackageResolver {
+  const outputDir = path.join(dir, 'output', 'generated')
+  fs.mkdirSync(outputDir, { recursive: true })
+  return {
+    isMonorepo: () => true,
+    getRootDir: () => dir,
+    getAppDir: () => path.join(dir, 'app'),
+    getOutputDir: () => outputDir,
+    getModulesConfigPath: () => path.join(dir, 'app', 'src', 'modules.ts'),
+    discoverPackages: () => [],
+    loadEnabledModules: () => enabled,
+    getModulePaths: (entry: ModuleEntry) => ({
+      appBase: path.join(dir, 'app', 'src', 'modules', entry.id),
+      pkgBase: path.join(dir, 'packages', 'core', 'src', 'modules', entry.id),
+    }),
+    getModuleImportBase: (entry: ModuleEntry) => ({
+      appBase: `@/modules/${entry.id}`,
+      pkgBase: `@open-mercato/core/modules/${entry.id}`,
+    }),
+    getPackageOutputDir: () => outputDir,
+    getPackageRoot: () => path.join(dir, 'packages', 'core'),
+  }
+}
+
+function scaffoldWorkerModule(dir: string, modId: string, workerSource: string): void {
+  touchFile(path.join(dir, 'packages', 'core', 'src', 'modules', modId, 'workers', 'sync.ts'), workerSource)
+}
+
+function generatedFiles(dir: string): Array<{ name: string; content: string }> {
+  const outputDir = path.join(dir, 'output', 'generated')
+  if (!fs.existsSync(outputDir)) return []
+  return fs.readdirSync(outputDir)
+    .filter((name) => name.endsWith('.ts'))
+    .map((name) => ({ name, content: fs.readFileSync(path.join(outputDir, name), 'utf8') }))
+}
+
+const ABANDON_HOOK_FACTORY = 'createLazyModuleWorkerAbandonHook'
+
+const WORKER_WITH_HOOK = `
+import { failAbandonedRun } from '../lib/abandoned-run'
+export const metadata = {
+  queue: 'demo-queue',
+  id: 'demo:worker',
+  concurrency: 2,
+  onJobAbandoned: failAbandonedRun,
+}
+export default async function handle() {}
+`
+
+const WORKER_WITHOUT_HOOK = `
+export const metadata = {
+  queue: 'demo-queue',
+  id: 'demo:worker',
+  concurrency: 2,
+}
+export default async function handle() {}
+`
+
+async function generateAll(resolver: PackageResolver): Promise<void> {
+  await generateModuleRegistry({ resolver, quiet: true })
+  await generateModuleRegistryApp({ resolver, quiet: true })
+  await generateModuleRegistryCli({ resolver, quiet: true })
+}
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'generated-registry-imports-'))
+})
+
+afterEach(() => {
+  fs.rmSync(tmpDir, { recursive: true, force: true })
+})
+
+describe('generated registries — emitted identifiers are imported', () => {
+  it('imports the abandon-hook helper in every file that calls it', async () => {
+    scaffoldWorkerModule(tmpDir, 'demo', WORKER_WITH_HOOK)
+    const resolver = createMockResolver(tmpDir, [{ id: 'demo', from: 'pkg' } as ModuleEntry])
+
+    await generateAll(resolver)
+
+    const files = generatedFiles(tmpDir)
+    const callers = files.filter(({ content }) => content.includes(`${ABANDON_HOOK_FACTORY}(`))
+    // The fixture must actually exercise the path, or this test passes vacuously — which is exactly
+    // how the missing import survived every existing suite.
+    expect(callers.length).toBeGreaterThan(0)
+
+    for (const { name, content } of callers) {
+      expect(`${name}: ${content.includes(`import { `) && new RegExp(`import \\{[^}]*\\b${ABANDON_HOOK_FACTORY}\\b[^}]*\\} from`, 's').test(content)}`)
+        .toBe(`${name}: true`)
+    }
+  })
+
+  it('leaves output untouched for a module set whose workers declare no hook', async () => {
+    scaffoldWorkerModule(tmpDir, 'demo', WORKER_WITHOUT_HOOK)
+    const resolver = createMockResolver(tmpDir, [{ id: 'demo', from: 'pkg' } as ModuleEntry])
+
+    await generateAll(resolver)
+
+    for (const { name, content } of generatedFiles(tmpDir)) {
+      expect(`${name}: ${content.includes(ABANDON_HOOK_FACTORY)}`).toBe(`${name}: false`)
+    }
+  })
+})

package/src/lib/generators/__tests__/metadata-extraction.test.ts

@@ -4,6 +4,7 @@ import os from 'node:os'
 import {
   extractNamedObjectLiteralExport,
   hasNamedExport,
+  namedObjectLiteralDeclaresProperty,
   resolveNamedObjectExport,
 } from '../module-registry'
 
@@ -218,3 +219,46 @@ describe('hasNamedExport', () => {
     expect(hasNamedExport(file, 'metadata')).toBe(false)
   })
 })
+
+describe('namedObjectLiteralDeclaresProperty', () => {
+  // A worker declaring `onJobAbandoned: someImportedFn` is the case that broke: the value resolvers
+  // cannot evaluate an imported identifier, so "is it declared" has to be answered from the syntax.
+  // Getting this wrong is silent — the generator simply never emits the hook.
+  it('sees a property whose value is an unresolvable identifier', () => {
+    const file = writeSource('worker.ts', `
+      import { failAbandonedRun } from '../lib/abandoned-run'
+      export const metadata = {
+        queue: 'data-sync-import',
+        concurrency: 5,
+        onJobAbandoned: failAbandonedRun,
+      }
+    `)
+    expect(namedObjectLiteralDeclaresProperty(file, 'metadata', 'onJobAbandoned')).toBe(true)
+    expect(extractNamedObjectLiteralExport(file, 'metadata')?.onJobAbandoned).toBeUndefined()
+  })
+
+  it('sees a property declared as an inline function', () => {
+    const file = writeSource('worker.ts', `
+      export const metadata = {
+        queue: 'q',
+        onJobAbandoned: async () => {},
+      }
+    `)
+    expect(namedObjectLiteralDeclaresProperty(file, 'metadata', 'onJobAbandoned')).toBe(true)
+  })
+
+  it('reports absence for a worker that declares no hook', () => {
+    const file = writeSource('worker.ts', `
+      export const metadata = { queue: 'q', concurrency: 1 }
+    `)
+    expect(namedObjectLiteralDeclaresProperty(file, 'metadata', 'onJobAbandoned')).toBe(false)
+  })
+
+  it('reports absence for a metadata export that is not an object literal', () => {
+    const file = writeSource('worker.ts', `
+      const base = buildMetadata()
+      export const metadata = base
+    `)
+    expect(namedObjectLiteralDeclaresProperty(file, 'metadata', 'onJobAbandoned')).toBe(false)
+  })
+})

package/src/lib/generators/__tests__/module-facts.bc-guard.test.ts

@@ -149,16 +149,20 @@ describe('module-facts BC resolve guard (T2)', () => {
     // wms, staff, integrations and checkout were therefore invisible to every fact
     // consumer — `integrations` published no contributions at all. Reading them costs
     // ~28KB, which is the fix working, not drift.
-    // The additive EUDR module contributes its real routes, ACL, events,
-    // entities, and extension surfaces without changing the extraction shape.
+    // The additive EUDR and Documents modules contribute their real routes, ACL,
+    // events, entities, and extension surfaces without changing the extraction
+    // shape.
     //
     // JSON cap raised a fifth time by the devices/push-notifications stack: the
     // `devices` and `push_notifications` modules plus the `channel-fcm`,
     // `channel-apns` and `channel-expo` provider packages add their own facts,
     // provenance entries and override targets to every render. The
-    // `warranty_claims` module (see above) lands alongside it, so the cap
-    // absorbs both additions.
-    expect(Buffer.byteLength(completeJson)).toBeLessThan(4_000_000)
+    // `warranty_claims` module (see above) and the additive Documents module
+    // land alongside it, so the cap absorbs all three additions. Both sides of
+    // that merge had raised the cap independently (3_950_000 for Documents,
+    // 4_000_000 for the rest); neither number covers the union, which measures
+    // ~4.09MB. Keep bounded headroom over the measured size only.
+    expect(Buffer.byteLength(completeJson)).toBeLessThan(4_150_000)
     expect(Buffer.byteLength(completeJson) - Buffer.byteLength(legacyJson)).toBeLessThan(1_800_000)
     // Markdown cap raised with the source-link contract: entities, events, ACL
     // features, DI tokens, search entities, notifications, UMES hosts and UMES

package/src/lib/generators/module-registry.ts

@@ -246,6 +246,15 @@ type SerializableWorkerMetadata = {
   concurrency?: number
   lockDuration?: number
   maxStalledCount?: number
+  /**
+   * Whether the worker's metadata declares an `onJobAbandoned` callback.
+   *
+   * A function cannot be serialized into the registry the way the scalar options are, so the flag is
+   * resolved here at build time and the callback itself is emitted as a lazy import beside the
+   * handler. Recorded only when the source module could actually be loaded — the object-literal
+   * fallback below cannot see whether a referenced identifier is a function.
+   */
+  hasJobAbandonedHook?: boolean
 }
 
 type PageMetadataManifestLoadResult = {
@@ -577,6 +586,55 @@ function extractObjectPropertiesFromAst(sourceFile: string, exportName: string):
   return Object.keys(result).length > 0 ? result : null
 }
 
+/**
+ * Whether an exported object literal declares a property, regardless of what it evaluates to.
+ *
+ * Needed for callbacks: the value resolvers above can read literals and local constants, but a
+ * property whose value is an imported function stays unresolvable, so "did the author declare it"
+ * cannot be answered by inspecting the extracted value. Answering it from the syntax instead is what
+ * lets the generator emit a lazy accessor for a hook it can see but cannot serialize.
+ */
+export function namedObjectLiteralDeclaresProperty(sourceFile: string, exportName: string, propertyName: string): boolean {
+  let source = ''
+  try {
+    source = fs.readFileSync(sourceFile, 'utf8')
+  } catch {
+    return false
+  }
+
+  const parsed = ts.createSourceFile(sourceFile, source, ts.ScriptTarget.Latest, true, inferScriptKind(sourceFile))
+  const exportedNames = new Set<string>()
+  for (const statement of parsed.statements) {
+    if (
+      ts.isExportDeclaration(statement)
+      && statement.exportClause
+      && ts.isNamedExports(statement.exportClause)
+      && !statement.moduleSpecifier
+    ) {
+      for (const element of statement.exportClause.elements) exportedNames.add(element.name.text)
+    }
+  }
+
+  for (const statement of parsed.statements) {
+    if (!ts.isVariableStatement(statement)) continue
+    const exportsDirectly = (ts.canHaveModifiers(statement) ? ts.getModifiers(statement) : undefined)
+      ?.some((modifier: ts.Modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword)
+    for (const declaration of statement.declarationList.declarations) {
+      if (!ts.isIdentifier(declaration.name) || declaration.name.text !== exportName) continue
+      if (!exportsDirectly && !exportedNames.has(exportName)) continue
+      const objectLiteral = unwrapObjectLiteralExpression(declaration.initializer)
+      if (!objectLiteral) return false
+      return objectLiteral.properties.some((property) => {
+        const name = property.name
+        if (!name) return false
+        const key = ts.isIdentifier(name) ? name.text : ts.isStringLiteral(name) ? name.text : null
+        return key === propertyName
+      })
+    }
+  }
+  return false
+}
+
 export function extractNamedObjectLiteralExport(sourceFile: string, exportName: string): Record<string, unknown> | null {
   const literal = extractNamedObjectLiteralSource(sourceFile, exportName)
   if (literal) {
@@ -1777,6 +1835,7 @@ function normalizeWorkerMetadata(raw: unknown): SerializableWorkerMetadata | nul
   if (typeof source.concurrency === 'number') normalized.concurrency = source.concurrency
   if (typeof source.lockDuration === 'number') normalized.lockDuration = source.lockDuration
   if (typeof source.maxStalledCount === 'number') normalized.maxStalledCount = source.maxStalledCount
+  if (typeof source.onJobAbandoned === 'function') normalized.hasJobAbandonedHook = true
   return Object.keys(normalized).length > 0 ? normalized : null
 }
 
@@ -1788,8 +1847,16 @@ async function loadSubscriberMetadata(sourceFile: string): Promise<SerializableS
 
 async function loadWorkerMetadata(sourceFile: string): Promise<SerializableWorkerMetadata | null> {
   const sourceModule = await loadModuleExportsFromSource<Record<string, unknown>>(sourceFile)
-  return normalizeWorkerMetadata(sourceModule?.metadata)
+  const metadata = normalizeWorkerMetadata(sourceModule?.metadata)
     ?? normalizeWorkerMetadata(extractNamedObjectLiteralExport(sourceFile, 'metadata'))
+  if (!metadata) return null
+  // Resolved from the syntax, not the extracted value: a worker module that cannot be imported at
+  // build time falls back to the literal extractor, which cannot tell an imported function from an
+  // unresolvable identifier. Missing this is silent — the hook is simply never installed.
+  if (!metadata.hasJobAbandonedHook && namedObjectLiteralDeclaresProperty(sourceFile, 'metadata', 'onJobAbandoned')) {
+    metadata.hasJobAbandonedHook = true
+  }
+  return metadata
 }
 
 async function discoverSubscribers(
@@ -2326,12 +2393,25 @@ function processSubscribers(discovered: DiscoveredSubscriber[]): string[] {
   return subscribers
 }
 
+/**
+ * Registry helper emitted for a worker that declares `metadata.onJobAbandoned`.
+ *
+ * Named once because two things must stay in step: the call the worker entry renders, and the import
+ * the file needs for it. A generated file that references this without importing it type-checks
+ * nowhere, and only fails at `build:app` — see `generated-registry-imports.test.ts`.
+ */
+const ABANDON_HOOK_FACTORY = 'createLazyModuleWorkerAbandonHook'
+
+function workersDeclareAbandonHook(discovered: DiscoveredWorker[]): boolean {
+  return discovered.some(({ metadata }) => metadata.hasJobAbandonedHook === true)
+}
+
 function processWorkers(discovered: DiscoveredWorker[]): string[] {
   const workers: string[] = []
   for (const { id, importPath, metadata } of discovered) {
     const workerId = metadata.id ?? id
     workers.push(
-      `{ id: ${toLiteral(workerId)}, queue: ${toLiteral(metadata.queue)}, concurrency: ${toLiteral(metadata.concurrency ?? 1)}${metadata.lockDuration === undefined ? '' : `, lockDuration: ${toLiteral(metadata.lockDuration)}`}${metadata.maxStalledCount === undefined ? '' : `, maxStalledCount: ${toLiteral(metadata.maxStalledCount)}`}, handler: createLazyModuleWorker(() => ${buildDynamicImportExpression(importPath)}, ${toLiteral(workerId)}) }`
+      `{ id: ${toLiteral(workerId)}, queue: ${toLiteral(metadata.queue)}, concurrency: ${toLiteral(metadata.concurrency ?? 1)}${metadata.lockDuration === undefined ? '' : `, lockDuration: ${toLiteral(metadata.lockDuration)}`}${metadata.maxStalledCount === undefined ? '' : `, maxStalledCount: ${toLiteral(metadata.maxStalledCount)}`}${metadata.hasJobAbandonedHook ? `, onJobAbandoned: ${ABANDON_HOOK_FACTORY}(() => ${buildDynamicImportExpression(importPath)}, ${toLiteral(workerId)})` : ''}, handler: createLazyModuleWorker(() => ${buildDynamicImportExpression(importPath)}, ${toLiteral(workerId)}) }`
     )
   }
   return workers
@@ -2567,6 +2647,7 @@ function renderAstModuleRegistryFile(options: {
   imports: string[]
   moduleEntries: WriterFunction[]
   includeCreateElementImport?: boolean
+  includeAbandonHookImport?: boolean
 }): string {
   const sourceFile = createGeneratedSourceFile(options.fileName)
   addAutoGeneratedComment(sourceFile, options.generator)
@@ -2582,6 +2663,7 @@ function renderAstModuleRegistryFile(options: {
     namedImports: [
       { name: 'createLazyModuleSubscriber' },
       { name: 'createLazyModuleWorker' },
+      ...(options.includeAbandonHookImport ? [{ name: ABANDON_HOOK_FACTORY }] : []),
       { name: 'Module', isTypeOnly: true },
     ],
   })
@@ -2694,10 +2776,18 @@ function renderAstLegacyModuleRegistryOutput(options: {
   imports: GeneratedImportStatement[]
   moduleEntries: string[]
   includeCreateElementImport?: boolean
+  includeAbandonHookImport?: boolean
 }): string {
+  // Derived from what is actually being written, not from a flag the caller has to remember: an
+  // import that must be opted into at every render site produces a file referencing an undeclared
+  // name the first time someone forgets, and the file only fails at `build:app`.
+  const needsAbandonHookImport = options.includeAbandonHookImport
+    || options.moduleEntries.some((entry) => entry.includes(ABANDON_HOOK_FACTORY))
   const importSection = [
     ...(options.includeCreateElementImport ? ["import { createElement } from 'react'"] : []),
-    "import { createLazyModuleSubscriber, createLazyModuleWorker, type Module } from '@open-mercato/shared/modules/registry'",
+    needsAbandonHookImport
+      ? "import { createLazyModuleSubscriber, createLazyModuleWorker, createLazyModuleWorkerAbandonHook, type Module } from '@open-mercato/shared/modules/registry'"
+      : "import { createLazyModuleSubscriber, createLazyModuleWorker, type Module } from '@open-mercato/shared/modules/registry'",
     ...options.imports.map((entry) => serializeGeneratedImport(entry)),
   ].join('\n')
 
@@ -3011,6 +3101,15 @@ function processWorkersAst(discovered: DiscoveredWorker[]): WriterFunction[] {
         { name: 'concurrency', value: metadata.concurrency ?? 1 },
         ...(metadata.lockDuration === undefined ? [] : [{ name: 'lockDuration', value: metadata.lockDuration }]),
         ...(metadata.maxStalledCount === undefined ? [] : [{ name: 'maxStalledCount', value: metadata.maxStalledCount }]),
+        ...(metadata.hasJobAbandonedHook
+          ? [{
+            name: 'onJobAbandoned',
+            value: callExpression(identifier(ABANDON_HOOK_FACTORY), [
+              arrowFunction({ body: importExpression(importPath) }),
+              workerId,
+            ]),
+          }]
+          : []),
         {
           name: 'handler',
           value: callExpression(identifier('createLazyModuleWorker'), [
@@ -3384,6 +3483,7 @@ async function generateModuleRegistryFromDiscovery(options: ModuleRegistryRender
   const requiresByModule = new Map<string, string[]>()
   const commandLoaderEntries: CommandLoaderGenerationEntry[] = []
   let hasRouteComponents = false
+  let hasAbandonHookWorkers = false
 
   // UMES conflict detection: collect file paths during module processing
   const umesConflictSources: Array<{
@@ -3635,7 +3735,9 @@ async function generateModuleRegistryFromDiscovery(options: ModuleRegistryRender
     subscribers.push(...processSubscribers(await discovered.getSubscribers()))
 
     // 18. Workers
-    workers.push(...processWorkers(await discovered.getWorkers()))
+    const discoveredWorkersForModule = await discovered.getWorkers()
+    if (workersDeclareAbandonHook(discoveredWorkersForModule)) hasAbandonHookWorkers = true
+    workers.push(...processWorkers(discoveredWorkersForModule))
 
     // Build combined customFieldSets expression
     {
@@ -3801,12 +3903,14 @@ async function generateModuleRegistryFromDiscovery(options: ModuleRegistryRender
     imports,
     moduleEntries: moduleDecls,
     includeCreateElementImport: hasRouteComponents,
+    includeAbandonHookImport: hasAbandonHookWorkers,
   })
   const runtimeOutput = renderAstLegacyModuleRegistryOutput({
     fileName: 'modules.runtime.generated.ts',
     imports: runtimeImports,
     moduleEntries: runtimeModuleDecls,
     includeCreateElementImport: true,
+    includeAbandonHookImport: hasAbandonHookWorkers,
   })
   const frontendRoutesOutput = renderAstLegacyManifestOutput({
     fileName: 'frontend-routes.generated.ts',
@@ -4010,6 +4114,7 @@ async function generateModuleRegistryAppFromDiscovery(options: ModuleRegistryRen
   const requiresByModule = new Map<string, string[]>()
   const commandLoaderEntries: CommandLoaderGenerationEntry[] = []
   let hasRouteComponents = false
+  let hasAbandonHookWorkers = false
   const seenBackendRoutePatterns = new Map<string, string>()
 
   for (const discovered of discovery.modules) {
@@ -4171,7 +4276,9 @@ async function generateModuleRegistryAppFromDiscovery(options: ModuleRegistryRen
 
     subscribers.push(...processSubscribersAst(await discovered.getSubscribers()))
 
-    workers.push(...processWorkersAst(await discovered.getWorkers()))
+    const discoveredWorkersForModule = await discovered.getWorkers()
+    if (workersDeclareAbandonHook(discoveredWorkersForModule)) hasAbandonHookWorkers = true
+    workers.push(...processWorkersAst(discoveredWorkersForModule))
 
     {
       dashboardWidgetsValue = buildModuleDashboardWidgetsValue(discovered.dashboardWidgetEntries)
@@ -4295,18 +4402,21 @@ async function generateModuleRegistryAppFromDiscovery(options: ModuleRegistryRen
     imports,
     moduleEntries: moduleDecls,
     includeCreateElementImport: hasRouteComponents,
+    includeAbandonHookImport: hasAbandonHookWorkers,
   })
   const bootstrapOutput = renderAstModuleRegistryFile({
     fileName: 'modules.bootstrap.generated.ts',
     generator: 'registry (bootstrap version)',
     imports: bootstrapImports,
     moduleEntries: bootstrapModuleDecls,
+    includeAbandonHookImport: hasAbandonHookWorkers,
   })
   const i18nOutput = renderAstModuleRegistryFile({
     fileName: 'modules.i18n.generated.ts',
     generator: 'registry (i18n version)',
     imports: i18nImports,
     moduleEntries: i18nModuleDecls,
+    includeAbandonHookImport: hasAbandonHookWorkers,
   })
   const legacyOutput = renderAstLegacyAliasFile({
     fileName: 'bootstrap-modules.generated.ts',
@@ -4397,6 +4507,7 @@ async function generateModuleRegistryAppFromDiscovery(options: ModuleRegistryRen
  * Excludes: frontend routes, backend routes, API handlers, injection widgets
  */
 async function generateModuleRegistryCliFromDiscovery(options: ModuleRegistryRenderOptions): Promise<GeneratorResult> {
+  let hasAbandonHookWorkers = false
   const { resolver, quiet = false } = options
   const { discovery } = options
   const result = createGeneratorResult()
@@ -4548,6 +4659,7 @@ async function generateModuleRegistryCliFromDiscovery(options: ModuleRegistryRen
     // Workers
     const discoveredWorkers = await discovered.getWorkers()
     const workerGenerationEntries = collectWorkerGenerationEntries(discoveredWorkers, modId)
+    if (workersDeclareAbandonHook(discoveredWorkers)) hasAbandonHookWorkers = true
     workers.push(...processWorkersAst(discoveredWorkers))
     devSupervisorWorkers.push(...workerGenerationEntries.map(({ importPath: _importPath, ...worker }) => worker))
 
@@ -4671,6 +4783,7 @@ async function generateModuleRegistryCliFromDiscovery(options: ModuleRegistryRen
     generator: 'registry (CLI version)',
     imports,
     moduleEntries: moduleDecls,
+    includeAbandonHookImport: hasAbandonHookWorkers,
   })
   const legacyOutput = renderAstLegacyAliasFile({
     fileName: 'cli-modules.generated.ts',

package/src/mercato.ts

@@ -78,6 +78,29 @@ function getRegisteredCliWorkers(modules: Module[] = getCliModules()): ModuleWor
   return allWorkers
 }
 
+/**
+ * Picks the abandoned-job callback for a queue from its workers.
+ *
+ * The numeric queue options merge across a queue's workers with `Math.max`; two callbacks cannot
+ * merge, so the first declared one wins. Silence there would make a genuine wiring mistake — two
+ * handlers on one queue each expecting to report its abandoned jobs — look like it works while one of
+ * them never runs.
+ */
+export function resolveQueueAbandonHook(
+  queueName: string,
+  queueWorkers: Array<Pick<ModuleWorker, 'id' | 'onJobAbandoned'>>,
+  warn: (message: string) => void = console.warn,
+): ModuleWorker['onJobAbandoned'] {
+  const declaring = queueWorkers.filter((worker) => worker.onJobAbandoned)
+  if (declaring.length > 1) {
+    warn(
+      `[worker] Queue "${queueName}" has ${declaring.length} workers declaring onJobAbandoned `
+      + `(${declaring.map((worker) => worker.id).join(', ')}); using the first and ignoring the rest.`,
+    )
+  }
+  return declaring[0]?.onJobAbandoned
+}
+
 function shouldEmbedLocalSchedulerInSharedWorker(env: NodeJS.ProcessEnv = process.env): boolean {
   return parseBooleanToken(env.OM_DEV_EMBED_SCHEDULER_IN_SHARED_WORKER) === true
 }
@@ -1678,6 +1701,7 @@ export async function run(argv = process.argv) {
                 Math.max(...queueWorkers.map((w) => w.concurrency), 1)
               const maxStalledCount = Math.max(...queueWorkers.map((w) => w.maxStalledCount ?? 1), 1)
               const lockDuration = Math.max(...queueWorkers.map((w) => w.lockDuration ?? 0), 0) || undefined
+              const onJobAbandoned = resolveQueueAbandonHook(queue, queueWorkers)
 
               console.log(`[worker] Starting "${queue}" with ${queueWorkers.length} handler(s), concurrency: ${concurrency}`)
 
@@ -1688,6 +1712,7 @@ export async function run(argv = process.argv) {
                 concurrency,
                 lockDuration,
                 maxStalledCount,
+                onJobAbandoned,
                 background: true,
                 handler: createPerJobWorkerHandler(queueWorkers, createRequestContainer),
               })
@@ -1733,6 +1758,7 @@ export async function run(argv = process.argv) {
               const concurrency = budgetPlan.entries[0]?.effective ?? requested
               const maxStalledCount = Math.max(...queueWorkers.map((w) => w.maxStalledCount ?? 1), 1)
               const lockDuration = Math.max(...queueWorkers.map((w) => w.lockDuration ?? 0), 0) || undefined
+              const onJobAbandoned = resolveQueueAbandonHook(queueName!, queueWorkers)
 
               console.log(`[worker] Found ${queueWorkers.length} worker(s) for queue "${queueName}"`)
 
@@ -1743,6 +1769,7 @@ export async function run(argv = process.argv) {
                 concurrency,
                 lockDuration,
                 maxStalledCount,
+                onJobAbandoned,
                 handler: createPerJobWorkerHandler(queueWorkers, createRequestContainer),
               })
             } else {