@zintrust/workers 0.1.31 → 0.1.52

package/dist/WorkerFactory.js

@@ -3,7 +3,7 @@
  * Central factory for creating workers with all advanced features
  * Sealed namespace for immutability
  */
-import { appConfig, createRedisConnection, databaseConfig, Env, ErrorFactory, getBullMQSafeQueueName, Logger, NodeSingletons, queueConfig, registerDatabasesFromRuntimeConfig, useEnsureDbConnected, workersConfig, ZintrustLang, } from '@zintrust/core';
+import { Cloudflare, createRedisConnection, databaseConfig, Env, ErrorFactory, generateUuid, getBullMQSafeQueueName, JobStateTracker, Logger, NodeSingletons, queueConfig, registerDatabasesFromRuntimeConfig, useEnsureDbConnected, workersConfig, ZintrustLang, } from '@zintrust/core';
 import { Worker } from 'bullmq';
 import { AutoScaler } from './AutoScaler';
 import { CanaryController } from './CanaryController';
@@ -21,8 +21,178 @@ import { ResourceMonitor } from './ResourceMonitor';
 import { WorkerMetrics } from './WorkerMetrics';
 import { WorkerRegistry } from './WorkerRegistry';
 import { WorkerVersioning } from './WorkerVersioning';
+import { keyPrefix } from './config/workerConfig';
 import { DbWorkerStore, InMemoryWorkerStore, RedisWorkerStore, } from './storage/WorkerStore';
 const path = NodeSingletons.path;
+const isNodeRuntime = () => typeof process !== 'undefined' && Boolean(process.versions?.node);
+const resolveProjectRoot = () => {
+    const envRoot = Env.get('ZINTRUST_PROJECT_ROOT', '').trim();
+    return envRoot.length > 0 ? envRoot : process.cwd();
+};
+const canUseProjectFileImports = () => 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, root) => {
+    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) => {
+    if (!canUseProjectFileImports())
+        return null;
+    for (const candidate of paths) {
+        if (NodeSingletons.fs.existsSync(candidate))
+            return candidate;
+    }
+    return null;
+};
+const resolveLocalPackageFallback = (specifier) => {
+    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) => {
+    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) => value.replaceAll(/[.*+?^${}()|[\]\\]/g, String.raw `\$&`);
+const rewriteProcessorImports = (code) => {
+    const replacements = [];
+    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 = () => {
+    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) => {
+    if (!isNodeRuntime())
+        return false;
+    const message = error instanceof Error ? error.message : String(error);
+    const code = error?.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) => {
+    const message = error instanceof Error ? error.message : String(error);
+    const code = error?.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) => {
+    const { code, normalized, cacheKey } = params;
+    const dataUrl = `data:text/javascript;base64,${toBase64(code)}`;
+    try {
+        return (await import(dataUrl));
+    }
+    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));
+        }
+        catch (fileError) {
+            if (isOptionalD1ProxyModuleMissing(fileError)) {
+                throw fileError;
+            }
+            Logger.debug(`Processor URL file fallback failed for ${normalized}`, fileError);
+            throw error;
+        }
+    }
+};
+const isCloudflareRuntime = () => Cloudflare.getWorkersEnv() !== null;
+const getDefaultStoreForRuntime = async () => {
+    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, persistenceOverride) => {
     if (persistenceOverride) {
         return resolveWorkerStoreForPersistence(persistenceOverride);
@@ -35,8 +205,7 @@ const getStoreForWorker = async (config, persistenceOverride) => {
         }
     }
     // Fallback to default/global store
-    await ensureWorkerStoreConfigured();
-    return workerStore;
+    return getDefaultStoreForRuntime();
 };
 const validateAndGetStore = async (name, config, persistenceOverride) => {
     const store = await getStoreForWorker(config, persistenceOverride);
@@ -153,7 +322,7 @@ const computeSha256 = async (value) => {
     if (typeof NodeSingletons.createHash === 'function') {
         return NodeSingletons.createHash('sha256').update(value).digest('hex');
     }
-    return String(Math.random()).slice(2);
+    return String(generateUuid()).slice(2);
 };
 const toBase64 = (value) => {
     if (typeof Buffer !== 'undefined') {
@@ -267,6 +436,18 @@ const sanitizeProcessorPath = (value) => {
 };
 const stripProcessorExtension = (value) => value.replace(/\.(ts|js)$/i, '');
 const normalizeModulePath = (value) => value.replaceAll('\\', '/');
+const filterExistingFileCandidates = (candidates) => {
+    if (!NodeSingletons?.fs?.existsSync)
+        return candidates;
+    return candidates.filter((candidate) => {
+        try {
+            return NodeSingletons.fs.existsSync(candidate);
+        }
+        catch {
+            return false;
+        }
+    });
+};
 const buildProcessorModuleCandidates = (modulePath, resolvedPath) => {
     const candidates = [];
     const normalized = normalizeModulePath(modulePath.trim());
@@ -286,6 +467,22 @@ const buildProcessorModuleCandidates = (modulePath, resolvedPath) => {
     }
     return Array.from(new Set(candidates));
 };
+const buildProcessorFilePathCandidates = (_modulePath, resolvedPath) => {
+    const candidates = [];
+    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, source) => {
     const candidate = mod?.['default'] ?? mod?.['processor'] ?? mod?.['handler'] ?? mod?.['handle'];
     if (typeof candidate !== 'function') {
@@ -328,9 +525,9 @@ const refreshCachedProcessor = (existing, config, cacheControl) => {
 };
 const cacheProcessorFromResponse = async (params) => {
     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, normalized);
     if (!processor) {
         throw ErrorFactory.createConfigError('INVALID_PROCESSOR_URL_EXPORT');
@@ -376,6 +573,10 @@ 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);
         }
@@ -415,9 +616,11 @@ const resolveProcessorFromUrl = async (spec) => {
     }
     if (parsed.protocol !== 'https:' && parsed.protocol !== 'file:') {
         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();
     const cacheKey = await computeSha256(normalized);
@@ -456,8 +659,11 @@ const resolveProcessorFromPath = async (modulePath) => {
             return undefined;
         const [candidatePath, ...rest] = candidates;
         try {
-            const mod = await import(candidatePath);
-            const candidate = pickProcessorFromModule(mod, candidatePath);
+            const importPath = candidatePath.startsWith('/') && !candidatePath.startsWith('//')
+                ? NodeSingletons.url.pathToFileURL(candidatePath).href
+                : candidatePath;
+            const mod = await import(importPath);
+            const candidate = pickProcessorFromModule(mod, importPath);
             if (candidate)
                 return candidate;
         }
@@ -473,10 +679,14 @@ const resolveProcessorFromPath = async (modulePath) => {
             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);
     }
     return undefined;
@@ -701,6 +911,56 @@ const handleFailure = async (params) => {
     await executeAllFailureHandlers(params);
     await executeFailurePlugins(workerName, job, error, features);
 };
+const toBackoffDelayMs = (backoff) => {
+    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.delay;
+        if (typeof raw === 'number' && Number.isFinite(raw)) {
+            return Math.max(0, Math.floor(raw));
+        }
+    }
+    return 0;
+};
+const trackJobStarted = async (input) => {
+    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) => {
+    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) => {
+    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
  */
@@ -719,8 +979,19 @@ const createEnhancedProcessor = (config) => {
         const startTime = Date.now();
         let result;
         let spanId = 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);
             const duration = Date.now() - startTime;
@@ -733,11 +1004,19 @@ const createEnhancedProcessor = (config) => {
                 spanId,
                 features,
             });
+            await trackJobCompleted({ queueName: config.queueName, job, duration, result });
             return result;
         }
         catch (err) {
             const error = err;
             const duration = Date.now() - startTime;
+            await trackJobFailed({
+                queueName: config.queueName,
+                job,
+                attempts,
+                maxAttempts,
+                error,
+            });
             await handleFailure({
                 workerName: name,
                 jobVersion,
@@ -801,12 +1080,22 @@ const resolveRedisConfigFromEnv = (config, context) => {
         password: password || undefined,
     };
 };
-const resolveRedisConfigFromDirect = (config, context) => ({
-    host: requireRedisHost(config.host, context),
-    port: config.port,
-    db: config.db,
-    password: config.password ?? Env.get('REDIS_PASSWORD', undefined),
-});
+const resolveRedisConfigFromDirect = (config, context) => {
+    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.database === 'number') {
+        normalizedDb = config.database;
+    }
+    return {
+        host: requireRedisHost(config.host, context),
+        port: config.port,
+        db: normalizedDb,
+        password: config.password ?? Env.get('REDIS_PASSWORD', undefined),
+    };
+};
 const resolveRedisConfig = (config, context) => isRedisEnvConfig(config)
     ? resolveRedisConfigFromEnv(config, context)
     : resolveRedisConfigFromDirect(config, context);
@@ -817,17 +1106,21 @@ const resolveRedisConfigWithFallback = (primary, fallback, errorMessage, context
     }
     return resolveRedisConfig(selected, context);
 };
+const logRedisPersistenceConfig = (redisConfig, key_prefix, source) => {
+    Logger.debug('Worker persistence redis config', {
+        source,
+        host: redisConfig.host,
+        port: redisConfig.port,
+        db: redisConfig.db,
+        key_prefix,
+    });
+};
 const normalizeEnvValue = (value) => {
     if (!value)
         return undefined;
     const trimmed = value.trim();
     return trimmed.length > 0 ? trimmed : undefined;
 };
-const normalizeAppName = (value) => {
-    const normalized = (value ?? '').trim().replaceAll(/\s+/g, '_');
-    return normalized.length > 0 ? normalized : 'zintrust';
-};
-const resolveDefaultRedisKeyPrefix = () => 'worker_' + normalizeAppName(appConfig.prefix);
 const resolveDefaultPersistenceTable = () => normalizeEnvValue(Env.get('WORKER_PERSISTENCE_TABLE', 'zintrust_workers')) ?? 'zintrust_workers';
 const resolveDefaultPersistenceConnection = () => normalizeEnvValue(Env.get('WORKER_PERSISTENCE_DB_CONNECTION', 'default')) ?? 'default';
 const resolveAutoStart = (config) => {
@@ -845,9 +1138,7 @@ const normalizeExplicitPersistence = (persistence) => {
         return {
             driver: 'redis',
             redis: persistence.redis,
-            keyPrefix: persistence.keyPrefix ??
-                normalizeEnvValue(Env.get('WORKER_PERSISTENCE_REDIS_KEY_PREFIX', '')) ??
-                resolveDefaultRedisKeyPrefix(),
+            keyPrefix: keyPrefix(),
         };
     }
     const clientIsConnection = typeof persistence.client === 'string';
@@ -875,11 +1166,15 @@ const resolvePersistenceConfig = (config) => {
     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(),
         };
     }
     if (driver === 'db' || driver === 'database') {
@@ -918,8 +1213,10 @@ const resolveWorkerStore = async (config) => {
     }
     else if (persistence.driver === 'redis') {
         const redisConfig = resolveRedisConfigWithFallback(persistence.redis, config.infrastructure?.redis, '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;
@@ -960,8 +1257,10 @@ const createWorkerStore = async (persistence) => {
     }
     if (persistence.driver === 'redis') {
         const redisConfig = resolveRedisConfigWithFallback(persistence.redis ?? { env: true }, undefined, '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
     const explicitConnection = typeof persistence.client === 'string' ? persistence.client : persistence.connection;
@@ -972,22 +1271,37 @@ const createWorkerStore = async (persistence) => {
 };
 const resolveWorkerStoreForPersistence = async (persistence) => {
     const cacheKey = generateCacheKey(persistence);
-    // Return cached instance if available
+    const isCloudflare = Cloudflare.getWorkersEnv() !== null;
+    // 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;
     }
     // Create new store instance
     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;
 };
 const getPersistedRecord = async (name, persistenceOverride) => {
     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);
     return store.get(name);
@@ -1359,6 +1673,35 @@ export const WorkerFactory = Object.freeze({
     registerProcessorSpec,
     resolveProcessorPath,
     resolveProcessorSpec,
+    /**
+     * Register a new worker configuration without starting it.
+     */
+    async register(config) {
+        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
      */
@@ -1727,9 +2070,25 @@ export const WorkerFactory = Object.freeze({
     async listPersistedRecords(persistenceOverride, options) {
         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);
         const records = await store.list(options);
@@ -1779,7 +2138,15 @@ export const WorkerFactory = Object.freeze({
     async getPersisted(name, persistenceOverride) {
         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();
+            }
+        }
     },
     /**
      * Remove worker