@zintrust/workers 0.1.31 → 0.1.52

package/src/WorkerFactory.ts

@@ -5,12 +5,14 @@
  */
 
 import {
-  appConfig,
+  Cloudflare,
   createRedisConnection,
   databaseConfig,
   Env,
   ErrorFactory,
+  generateUuid,
   getBullMQSafeQueueName,
+  JobStateTracker,
   Logger,
   NodeSingletons,
   queueConfig,
@@ -39,6 +41,7 @@ import { ResourceMonitor } from './ResourceMonitor';
 import { WorkerMetrics } from './WorkerMetrics';
 import { WorkerRegistry, type WorkerInstance as RegistryWorkerInstance } from './WorkerRegistry';
 import { WorkerVersioning } from './WorkerVersioning';
+import { keyPrefix } from './config/workerConfig';
 import {
   DbWorkerStore,
   InMemoryWorkerStore,
@@ -49,6 +52,199 @@ import {
 
 const path = NodeSingletons.path;
 
+const isNodeRuntime = (): boolean =>
+  typeof process !== 'undefined' && Boolean(process.versions?.node);
+
+const resolveProjectRoot = (): string => {
+  const envRoot = Env.get('ZINTRUST_PROJECT_ROOT', '').trim();
+  return envRoot.length > 0 ? envRoot : process.cwd();
+};
+
+const canUseProjectFileImports = (): boolean =>
+  typeof NodeSingletons?.fs?.writeFileSync === 'function' &&
+  typeof NodeSingletons?.fs?.mkdirSync === 'function' &&
+  typeof NodeSingletons?.fs?.existsSync === 'function' &&
+  typeof NodeSingletons?.url?.pathToFileURL === 'function' &&
+  typeof NodeSingletons?.path?.join === 'function';
+
+const buildCandidatesForSpecifier = (specifier: string, root: string): string[] => {
+  if (specifier === '@zintrust/core') {
+    return [
+      path.join(root, 'dist', 'src', 'index.js'),
+      path.join(root, 'dist', 'index.js'),
+      path.join(root, 'node_modules', '@zintrust', 'core', 'dist', 'src', 'index.js'),
+      path.join(root, 'node_modules', '@zintrust', 'core', 'dist', 'index.js'),
+      path.join(root, 'node_modules', '@zintrust', 'core', 'src', 'index.js'),
+      path.join(root, 'node_modules', '@zintrust', 'core', 'index.js'),
+      path.join(root, 'src', 'index.ts'),
+    ];
+  }
+
+  if (specifier === '@zintrust/workers') {
+    return [
+      path.join(root, 'dist', 'packages', 'workers', 'src', 'index.js'),
+      path.join(root, 'node_modules', '@zintrust', 'workers', 'dist', 'src', 'index.js'),
+      path.join(root, 'node_modules', '@zintrust', 'workers', 'dist', 'index.js'),
+      path.join(root, 'node_modules', '@zintrust', 'workers', 'src', 'index.js'),
+      path.join(root, 'node_modules', '@zintrust', 'workers', 'index.js'),
+      path.join(root, 'packages', 'workers', 'src', 'index.ts'),
+    ];
+  }
+
+  return [];
+};
+
+const getProjectFileCandidates = (paths: string[]): string | null => {
+  if (!canUseProjectFileImports()) return null;
+  for (const candidate of paths) {
+    if (NodeSingletons.fs.existsSync(candidate)) return candidate;
+  }
+  return null;
+};
+
+const resolveLocalPackageFallback = (specifier: string): string | null => {
+  if (!canUseProjectFileImports()) return null;
+  const root = resolveProjectRoot();
+
+  const candidates = buildCandidatesForSpecifier(specifier, root);
+  const resolved = getProjectFileCandidates(candidates);
+  if (!resolved) return null;
+  return NodeSingletons.url.pathToFileURL(resolved).href;
+};
+
+const resolvePackageSpecifierUrl = (specifier: string): string | null => {
+  if (!isNodeRuntime() || !canUseProjectFileImports()) return null;
+  if (typeof NodeSingletons?.module?.createRequire !== 'function') {
+    return resolveLocalPackageFallback(specifier);
+  }
+
+  try {
+    const require = NodeSingletons.module.createRequire(import.meta.url);
+    const resolved = require.resolve(specifier);
+    if (
+      (specifier === '@zintrust/workers' &&
+        resolved.includes(
+          `${path.sep}node_modules${path.sep}@zintrust${path.sep}workers${path.sep}`
+        )) ||
+      (specifier === '@zintrust/core' &&
+        resolved.includes(`${path.sep}node_modules${path.sep}@zintrust${path.sep}core${path.sep}`))
+    ) {
+      const local = resolveLocalPackageFallback(specifier);
+      if (local) return local;
+    }
+    return NodeSingletons.url.pathToFileURL(resolved).href;
+  } catch {
+    return resolveLocalPackageFallback(specifier);
+  }
+};
+
+const escapeRegExp = (value: string): string =>
+  value.replaceAll(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`);
+
+const rewriteProcessorImports = (code: string): string => {
+  const replacements: Array<{ from: string; to: string }> = [];
+  const coreUrl = resolvePackageSpecifierUrl('@zintrust/core');
+  if (coreUrl) replacements.push({ from: '@zintrust/core', to: coreUrl });
+  const workersUrl = resolvePackageSpecifierUrl('@zintrust/workers');
+  if (workersUrl) replacements.push({ from: '@zintrust/workers', to: workersUrl });
+
+  if (replacements.length === 0) return code;
+
+  let updated = code;
+  for (const { from, to } of replacements) {
+    const pattern = new RegExp(String.raw`(['"])${escapeRegExp(from)}\1`, 'g');
+    updated = updated.replace(pattern, `$1${to}$1`);
+  }
+
+  return updated;
+};
+
+const ensureProcessorSpecDir = (): string | null => {
+  if (!isNodeRuntime() || !canUseProjectFileImports()) return null;
+  const dir = path.join(resolveProjectRoot(), '.zintrust', 'processor-specs');
+  try {
+    if (!NodeSingletons.fs.existsSync(dir)) {
+      NodeSingletons.fs.mkdirSync(dir, { recursive: true });
+    }
+    return dir;
+  } catch (error) {
+    Logger.debug('Failed to prepare processor spec cache directory', error);
+    return null;
+  }
+};
+
+const shouldFallbackToFileImport = (error: unknown): boolean => {
+  if (!isNodeRuntime()) return false;
+  const message = error instanceof Error ? error.message : String(error);
+  const code = (error as { code?: string } | undefined)?.code ?? '';
+  if (code === 'ERR_INVALID_URL' || code === 'ERR_UNSUPPORTED_ESM_URL_SCHEME') return true;
+  return (
+    message.includes('Invalid relative URL') ||
+    message.includes('base scheme is not hierarchical') ||
+    message.includes('Failed to resolve module specifier')
+  );
+};
+
+const isOptionalD1ProxyModuleMissing = (error: unknown): boolean => {
+  const message = error instanceof Error ? error.message : String(error);
+  const code = (error as { code?: string } | undefined)?.code ?? '';
+
+  if (code !== 'ERR_MODULE_NOT_FOUND') return false;
+
+  return (
+    message.includes('cloudflare-d1-proxy') ||
+    message.includes('/packages/cloudflare-d1-proxy/src/index.js')
+  );
+};
+
+const importModuleFromCode = async (params: {
+  code: string;
+  normalized: string;
+  cacheKey: string;
+}): Promise<Record<string, unknown>> => {
+  const { code, normalized, cacheKey } = params;
+  const dataUrl = `data:text/javascript;base64,${toBase64(code)}`;
+
+  try {
+    return (await import(dataUrl)) as Record<string, unknown>;
+  } catch (error) {
+    if (!shouldFallbackToFileImport(error)) throw error;
+    const dir = ensureProcessorSpecDir();
+    if (!dir) throw error;
+
+    try {
+      const codeHash = await computeSha256(code);
+      const filePath = path.join(dir, `${codeHash || cacheKey}.mjs`);
+      NodeSingletons.fs.writeFileSync(filePath, code, 'utf8');
+      const fileUrl = NodeSingletons.url.pathToFileURL(filePath).href;
+      return (await import(fileUrl)) as Record<string, unknown>;
+    } catch (fileError) {
+      if (isOptionalD1ProxyModuleMissing(fileError)) {
+        throw fileError;
+      }
+      Logger.debug(`Processor URL file fallback failed for ${normalized}`, fileError);
+      throw error;
+    }
+  }
+};
+
+const isCloudflareRuntime = (): boolean => Cloudflare.getWorkersEnv() !== null;
+
+const getDefaultStoreForRuntime = async (): Promise<WorkerStore> => {
+  if (!isCloudflareRuntime()) {
+    await ensureWorkerStoreConfigured();
+    return workerStore;
+  }
+
+  const bootstrapConfig = buildPersistenceBootstrapConfig();
+  const persistence = resolvePersistenceConfig(bootstrapConfig);
+  if (!persistence) {
+    return InMemoryWorkerStore.create();
+  }
+
+  return resolveWorkerStoreForPersistence(persistence);
+};
+
 const getStoreForWorker = async (
   config: WorkerFactoryConfig | undefined,
   persistenceOverride?: WorkerPersistenceConfig
@@ -66,8 +262,7 @@ const getStoreForWorker = async (
   }
 
   // Fallback to default/global store
-  await ensureWorkerStoreConfigured();
-  return workerStore;
+  return getDefaultStoreForRuntime();
 };
 
 const validateAndGetStore = async (
@@ -311,7 +506,7 @@ const computeSha256 = async (value: string): Promise<string> => {
     return NodeSingletons.createHash('sha256').update(value).digest('hex');
   }
 
-  return String(Math.random()).slice(2);
+  return String(generateUuid()).slice(2);
 };
 
 const toBase64 = (value: string): string => {
@@ -448,6 +643,17 @@ const stripProcessorExtension = (value: string): string => value.replace(/\.(ts|
 
 const normalizeModulePath = (value: string): string => value.replaceAll('\\', '/');
 
+const filterExistingFileCandidates = (candidates: string[]): string[] => {
+  if (!NodeSingletons?.fs?.existsSync) return candidates;
+  return candidates.filter((candidate) => {
+    try {
+      return NodeSingletons.fs.existsSync(candidate);
+    } catch {
+      return false;
+    }
+  });
+};
+
 const buildProcessorModuleCandidates = (modulePath: string, resolvedPath: string): string[] => {
   const candidates: string[] = [];
   const normalized = normalizeModulePath(modulePath.trim());
@@ -470,6 +676,31 @@ const buildProcessorModuleCandidates = (modulePath: string, resolvedPath: string
   return Array.from(new Set(candidates));
 };
 
+const buildProcessorFilePathCandidates = (_modulePath: string, resolvedPath: string): string[] => {
+  const candidates: string[] = [];
+  const normalizedResolved = normalizeModulePath(resolvedPath);
+  const projectRoot = normalizeModulePath(resolveProjectRoot());
+
+  const strippedResolved = stripProcessorExtension(resolvedPath);
+  candidates.push(`${strippedResolved}.js`, `${strippedResolved}.mjs`);
+
+  const appIndex = normalizedResolved.lastIndexOf('/app/');
+  if (appIndex !== -1) {
+    const relative = normalizedResolved.slice(appIndex + 5);
+    if (relative) {
+      const strippedRelative = stripProcessorExtension(relative);
+      candidates.push(
+        path.join(projectRoot, 'dist', 'app', `${strippedRelative}.js`),
+        path.join(projectRoot, 'app', relative),
+        path.join(projectRoot, 'app', `${strippedRelative}.js`),
+        path.join('/app', 'dist', 'app', `${strippedRelative}.js`)
+      );
+    }
+  }
+
+  return filterExistingFileCandidates(Array.from(new Set(candidates)));
+};
+
 const pickProcessorFromModule = (
   mod: Record<string, unknown> | undefined,
   source: string
@@ -544,9 +775,9 @@ const cacheProcessorFromResponse = async (params: {
   cacheKey: string;
 }): Promise<WorkerFactoryConfig['processor']> => {
   const { response, normalized, config, cacheKey } = params;
-  const code = await readResponseBody(response, config.fetchMaxSizeBytes);
-  const dataUrl = `data:text/javascript;base64,${toBase64(code)}`;
-  const mod = await import(dataUrl);
+  const rawCode = await readResponseBody(response, config.fetchMaxSizeBytes);
+  const code = rewriteProcessorImports(rawCode);
+  const mod = await importModuleFromCode({ code, normalized, cacheKey });
   const processor = extractZinTrustProcessor(mod as Record<string, unknown>, normalized);
   if (!processor) {
     throw ErrorFactory.createConfigError('INVALID_PROCESSOR_URL_EXPORT');
@@ -611,6 +842,13 @@ const fetchProcessorAttempt = async (params: {
 
     return await cacheProcessorFromResponse({ response, normalized, config, cacheKey });
   } catch (error) {
+    if (isOptionalD1ProxyModuleMissing(error)) {
+      Logger.warn(
+        'Processor URL skipped: optional cloudflare-d1-proxy module is unavailable in this runtime.'
+      );
+      return undefined;
+    }
+
     if (controller.signal.aborted) {
       Logger.error('Processor URL fetch timeout', error);
     } else {
@@ -656,10 +894,12 @@ const resolveProcessorFromUrl = async (
     Logger.warn(
       `Invalid processor URL protocol: ${parsed.protocol}. Only https:// and file:// are supported.`
     );
+    return undefined;
   }
 
   if (!isAllowedRemoteHost(parsed.host) && parsed.protocol !== 'file:') {
     Logger.warn(`Invalid processor URL host: ${parsed.host}. Host is not in the allowlist.`);
+    return undefined;
   }
 
   const config = getProcessorSpecConfig();
@@ -703,8 +943,12 @@ const resolveProcessorFromPath = async (
     if (candidates.length === 0) return undefined;
     const [candidatePath, ...rest] = candidates;
     try {
-      const mod = await import(candidatePath);
-      const candidate = pickProcessorFromModule(mod as Record<string, unknown>, candidatePath);
+      const importPath =
+        candidatePath.startsWith('/') && !candidatePath.startsWith('//')
+          ? NodeSingletons.url.pathToFileURL(candidatePath).href
+          : candidatePath;
+      const mod = await import(importPath);
+      const candidate = pickProcessorFromModule(mod as Record<string, unknown>, importPath);
       if (candidate) return candidate;
     } catch (candidateError) {
       Logger.debug(`Processor module candidate import failed: ${candidatePath}`, candidateError);
@@ -718,9 +962,13 @@ const resolveProcessorFromPath = async (
     const candidate = pickProcessorFromModule(mod as Record<string, unknown>, resolved);
     if (candidate) return candidate;
   } catch (err) {
-    const candidates = buildProcessorModuleCandidates(trimmed, resolved);
-    const resolvedCandidate = await importProcessorFromCandidates(candidates);
-    if (resolvedCandidate) return resolvedCandidate;
+    const fileCandidates = buildProcessorFilePathCandidates(trimmed, resolved);
+    const resolvedFileCandidate = await importProcessorFromCandidates(fileCandidates);
+    if (resolvedFileCandidate) return resolvedFileCandidate;
+
+    const moduleCandidates = buildProcessorModuleCandidates(trimmed, resolved);
+    const resolvedModuleCandidate = await importProcessorFromCandidates(moduleCandidates);
+    if (resolvedModuleCandidate) return resolvedModuleCandidate;
     Logger.error(`Failed to import processor from path: ${resolved}`, err);
   }
 
@@ -1096,6 +1344,76 @@ const handleFailure = async (params: {
   await executeFailurePlugins(workerName, job, error, features);
 };
 
+const toBackoffDelayMs = (backoff: unknown): number => {
+  if (typeof backoff === 'number' && Number.isFinite(backoff)) {
+    return Math.max(0, Math.floor(backoff));
+  }
+  if (backoff !== null && backoff !== undefined && typeof backoff === 'object') {
+    const raw = (backoff as { delay?: unknown }).delay;
+    if (typeof raw === 'number' && Number.isFinite(raw)) {
+      return Math.max(0, Math.floor(raw));
+    }
+  }
+  return 0;
+};
+
+const trackJobStarted = async (input: {
+  queueName: string;
+  job: Job;
+  attempts: number;
+  workerName: string;
+  workerVersion: string;
+}): Promise<void> => {
+  if (!input.job.id) return;
+  await JobStateTracker.started({
+    queueName: input.queueName,
+    jobId: input.job.id,
+    attempts: input.attempts,
+    timeoutMs: Math.max(1000, Env.getInt('QUEUE_JOB_TIMEOUT', 60) * 1000),
+    workerName: input.workerName,
+    workerVersion: input.workerVersion,
+  });
+};
+
+const trackJobCompleted = async (input: {
+  queueName: string;
+  job: Job;
+  duration: number;
+  result: unknown;
+}): Promise<void> => {
+  if (!input.job.id) return;
+  await JobStateTracker.completed({
+    queueName: input.queueName,
+    jobId: input.job.id,
+    processingTimeMs: input.duration,
+    result: input.result,
+  });
+};
+
+const trackJobFailed = async (input: {
+  queueName: string;
+  job: Job;
+  attempts: number;
+  maxAttempts?: number;
+  error: Error;
+}): Promise<void> => {
+  if (!input.job.id) return;
+  const isFinal = input.maxAttempts === undefined ? true : input.attempts >= input.maxAttempts;
+  const backoffDelayMs = toBackoffDelayMs(input.job.opts?.backoff);
+
+  await JobStateTracker.failed({
+    queueName: input.queueName,
+    jobId: input.job.id,
+    attempts: input.attempts,
+    isFinal,
+    retryAt:
+      !isFinal && backoffDelayMs > 0
+        ? new Date(Date.now() + backoffDelayMs).toISOString()
+        : undefined,
+    error: input.error,
+  });
+};
+
 /**
  * Helper: Create enhanced processor with all features
  */
@@ -1119,9 +1437,23 @@ const createEnhancedProcessor = (config: WorkerFactoryConfig): ((job: Job) => Pr
     let result: unknown;
     let spanId: string | null = null;
 
+    const maxAttempts =
+      typeof job.opts?.attempts === 'number' && Number.isFinite(job.opts.attempts)
+        ? Math.max(1, Math.floor(job.opts.attempts))
+        : undefined;
+    const attempts = Math.max(1, Math.floor((job.attemptsMade ?? 0) + 1));
+
     try {
       spanId = startProcessingSpan(name, jobVersion, job, config.queueName, features);
 
+      await trackJobStarted({
+        queueName: config.queueName,
+        job,
+        attempts,
+        workerName: name,
+        workerVersion: jobVersion,
+      });
+
       // Process the job
       result = await processor(job);
 
@@ -1136,11 +1468,21 @@ const createEnhancedProcessor = (config: WorkerFactoryConfig): ((job: Job) => Pr
         features,
       });
 
+      await trackJobCompleted({ queueName: config.queueName, job, duration, result });
+
       return result;
     } catch (err) {
       const error = err as Error;
       const duration = Date.now() - startTime;
 
+      await trackJobFailed({
+        queueName: config.queueName,
+        job,
+        attempts,
+        maxAttempts,
+        error,
+      });
+
       await handleFailure({
         workerName: name,
         jobVersion,
@@ -1226,12 +1568,23 @@ const resolveRedisConfigFromEnv = (config: RedisEnvConfig, context: string): Red
   };
 };
 
-const resolveRedisConfigFromDirect = (config: RedisConfig, context: string): RedisConfig => ({
-  host: requireRedisHost(config.host, context),
-  port: config.port,
-  db: config.db,
-  password: config.password ?? Env.get('REDIS_PASSWORD', undefined),
-});
+const resolveRedisConfigFromDirect = (config: RedisConfig, context: string): RedisConfig => {
+  const fallbackDb = Env.getInt('REDIS_QUEUE_DB', ZintrustLang.REDIS_DEFAULT_DB);
+
+  let normalizedDb = fallbackDb;
+  if (typeof config.db === 'number') {
+    normalizedDb = config.db;
+  } else if (typeof (config as { database?: number }).database === 'number') {
+    normalizedDb = (config as { database?: number }).database as number;
+  }
+
+  return {
+    host: requireRedisHost(config.host, context),
+    port: config.port,
+    db: normalizedDb,
+    password: config.password ?? Env.get('REDIS_PASSWORD', undefined),
+  };
+};
 
 const resolveRedisConfig = (config: RedisConfigInput, context: string): RedisConfig =>
   isRedisEnvConfig(config)
@@ -1252,18 +1605,26 @@ const resolveRedisConfigWithFallback = (
   return resolveRedisConfig(selected, context);
 };
 
+const logRedisPersistenceConfig = (
+  redisConfig: RedisConfig,
+  key_prefix: string,
+  source: string
+): void => {
+  Logger.debug('Worker persistence redis config', {
+    source,
+    host: redisConfig.host,
+    port: redisConfig.port,
+    db: redisConfig.db,
+    key_prefix,
+  });
+};
+
 const normalizeEnvValue = (value: string | undefined): string | undefined => {
   if (!value) return undefined;
   const trimmed = value.trim();
   return trimmed.length > 0 ? trimmed : undefined;
 };
 
-const normalizeAppName = (value: string | undefined): string => {
-  const normalized = (value ?? '').trim().replaceAll(/\s+/g, '_');
-  return normalized.length > 0 ? normalized : 'zintrust';
-};
-
-const resolveDefaultRedisKeyPrefix = (): string => 'worker_' + normalizeAppName(appConfig.prefix);
 const resolveDefaultPersistenceTable = (): string =>
   normalizeEnvValue(Env.get('WORKER_PERSISTENCE_TABLE', 'zintrust_workers')) ?? 'zintrust_workers';
 
@@ -1288,10 +1649,7 @@ const normalizeExplicitPersistence = (
     return {
       driver: 'redis',
       redis: persistence.redis,
-      keyPrefix:
-        persistence.keyPrefix ??
-        normalizeEnvValue(Env.get('WORKER_PERSISTENCE_REDIS_KEY_PREFIX', '')) ??
-        resolveDefaultRedisKeyPrefix(),
+      keyPrefix: keyPrefix(),
     };
   }
 
@@ -1326,11 +1684,16 @@ const resolvePersistenceConfig = (
   if (driver === 'memory') return { driver: 'memory' };
 
   if (driver === 'redis') {
-    const keyPrefix = normalizeEnvValue(Env.get('WORKER_PERSISTENCE_REDIS_KEY_PREFIX', ''));
+    const persistenceDbOverride = normalizeEnvValue(Env.get('WORKER_PERSISTENCE_REDIS_DB', ''));
+
     return {
       driver: 'redis',
-      redis: { env: true },
-      keyPrefix: `${keyPrefix}_worker_${appConfig.prefix}`,
+      // Optional override; otherwise defaults to REDIS_QUEUE_DB.
+      redis: {
+        env: true,
+        db: persistenceDbOverride ? 'WORKER_PERSISTENCE_REDIS_DB' : 'REDIS_QUEUE_DB',
+      },
+      keyPrefix: keyPrefix(),
     };
   }
 
@@ -1383,8 +1746,10 @@ const resolveWorkerStore = async (config: WorkerFactoryConfig): Promise<WorkerSt
       'Worker persistence requires redis config (persistence.redis or infrastructure.redis)',
       'infrastructure.persistence.redis'
     );
+    const key_prefix = persistence.keyPrefix ?? keyPrefix();
+    logRedisPersistenceConfig(redisConfig, key_prefix, 'resolveWorkerStore');
     const client = createRedisConnection(redisConfig);
-    next = RedisWorkerStore.create(client, persistence.keyPrefix ?? resolveDefaultRedisKeyPrefix());
+    next = RedisWorkerStore.create(client, key_prefix);
   } else if (persistence.driver === 'database') {
     const explicitConnection =
       typeof persistence.client === 'string' ? persistence.client : persistence.connection;
@@ -1435,8 +1800,10 @@ const createWorkerStore = async (persistence: WorkerPersistenceConfig): Promise<
       'Worker persistence requires redis config (persistence.redis or REDIS_* env values)',
       'persistence.redis'
     );
+    const key_prefix = persistence.keyPrefix ?? keyPrefix();
+    logRedisPersistenceConfig(redisConfig, key_prefix, 'createWorkerStore');
     const client = createRedisConnection(redisConfig);
-    return RedisWorkerStore.create(client, persistence.keyPrefix ?? resolveDefaultRedisKeyPrefix());
+    return RedisWorkerStore.create(client, key_prefix);
   }
 
   // Database driver
@@ -1453,10 +1820,12 @@ const resolveWorkerStoreForPersistence = async (
   persistence: WorkerPersistenceConfig
 ): Promise<WorkerStore> => {
   const cacheKey = generateCacheKey(persistence);
+  const isCloudflare = Cloudflare.getWorkersEnv() !== null;
 
-  // Return cached instance if available
+  // Return cached instance if available (disable cache for Cloudflare to assume cleanup)
+  // Or handle cleanup differently. For now, disable cache for Cloudflare to allow per-request connections.
   const cached = storeInstanceCache.get(cacheKey);
-  if (cached) {
+  if (cached && !isCloudflare) {
     return cached;
   }
 
@@ -1464,8 +1833,10 @@ const resolveWorkerStoreForPersistence = async (
   const store = await createWorkerStore(persistence);
   await store.init();
 
-  // Cache the store instance for reuse
-  storeInstanceCache.set(cacheKey, store);
+  // Cache the store instance for reuse only if not Cloudflare
+  if (!isCloudflare) {
+    storeInstanceCache.set(cacheKey, store);
+  }
 
   return store;
 };
@@ -1475,8 +1846,19 @@ const getPersistedRecord = async (
   persistenceOverride?: WorkerPersistenceConfig
 ): Promise<WorkerRecord | null> => {
   if (!persistenceOverride) {
-    await ensureWorkerStoreConfigured();
-    return workerStore.get(name);
+    if (!isCloudflareRuntime()) {
+      await ensureWorkerStoreConfigured();
+      return workerStore.get(name);
+    }
+
+    const store = await getDefaultStoreForRuntime();
+    try {
+      return await store.get(name);
+    } finally {
+      if (store.close) {
+        await store.close();
+      }
+    }
   }
 
   const store = await resolveWorkerStoreForPersistence(persistenceOverride);
@@ -1934,6 +2316,37 @@ export const WorkerFactory = Object.freeze({
   resolveProcessorPath,
   resolveProcessorSpec,
 
+  /**
+   * Register a new worker configuration without starting it.
+   */
+  async register(config: WorkerFactoryConfig): Promise<void> {
+    const { name } = config;
+    // Check in-memory first (though unlikely if we are just registering)
+    if (workers.has(name)) {
+      throw ErrorFactory.createWorkerError(`Worker "${name}" is already running locally`);
+    }
+
+    const store = await getStoreForWorker(config);
+    try {
+      const existing = await store.get(name);
+      if (existing) {
+        throw ErrorFactory.createWorkerError(`Worker "${name}" already exists in persistence`);
+      }
+
+      // Init features to validate config, but mainly we just want to save it.
+      // initializeWorkerFeatures might rely on being active or having resources, so we might skip it or do partial.
+      // For now, just save definition.
+      // Status should be STOPPED or CREATED.
+      await store.save(buildWorkerRecord(config, WorkerCreationStatus.STOPPED));
+      Logger.info(`Worker registered (persistence only): ${name}`);
+    } finally {
+      // If Cloudflare environment, try to close store connection to avoid zombie connections
+      if (Cloudflare.getWorkersEnv() !== null && store.close) {
+        await store.close();
+      }
+    }
+  },
+
   /**
    * Create new worker with full setup
    */
@@ -2398,9 +2811,25 @@ export const WorkerFactory = Object.freeze({
   ): Promise<WorkerRecord[]> {
     const includeInactive = options?.includeInactive === true;
     if (!persistenceOverride) {
-      await ensureWorkerStoreConfigured();
-      const records = await workerStore.list(options);
-      return includeInactive ? records : records.filter((record) => record.activeStatus !== false);
+      if (!isCloudflareRuntime()) {
+        await ensureWorkerStoreConfigured();
+        const records = await workerStore.list(options);
+        return includeInactive
+          ? records
+          : records.filter((record) => record.activeStatus !== false);
+      }
+
+      const store = await getDefaultStoreForRuntime();
+      try {
+        const records = await store.list(options);
+        return includeInactive
+          ? records
+          : records.filter((record) => record.activeStatus !== false);
+      } finally {
+        if (store.close) {
+          await store.close();
+        }
+      }
     }
 
     const store = await resolveWorkerStoreForPersistence(persistenceOverride);
@@ -2465,7 +2894,15 @@ export const WorkerFactory = Object.freeze({
   ): Promise<WorkerRecord | null> {
     const instance = workers.get(name);
     const store = await getStoreForWorker(instance?.config, persistenceOverride);
-    return store.get(name);
+
+    try {
+      const result = await store.get(name);
+      return result;
+    } finally {
+      if (Cloudflare.getWorkersEnv() !== null && store.close) {
+        await store.close();
+      }
+    }
   },
 
   /**