@zintrust/workers 0.4.4 → 0.4.34

package/README.md

@@ -659,6 +659,27 @@ registerWorkerRoutes(Router);
 Processor specs can be file paths or URL specs (recommended for production). Remote processors
 must export a named `ZinTrustProcessor` function.
 
+For file-backed worker discovery, export a `workerDefinition` object from the worker module. This
+lets fresh projects surface worker metadata before any persistence record exists.
+
+```typescript
+export const workerDefinition = Object.freeze({
+  name: 'example-worker',
+  queueName: 'example-worker',
+  version: '1.0.0',
+  autoStart: false,
+  activeStatus: true,
+  concurrency: 1,
+  processorSpec: 'app/Workers/ExampleWorker.ts',
+});
+
+export async function ZinTrustProcessor(payload: unknown): Promise<void> {
+  return undefined;
+}
+
+export default ZinTrustProcessor;
+```
+
 Workers support `activeStatus` to pause without deletion; inactive workers do not auto-start.
 
 See the [API Reference](#api-reference) section for all available endpoints.
@@ -683,6 +704,11 @@ await WorkerInit.initialize({
 });
 ```
 
+When `WORKER_AUTO_START=true`, ZinTrust first auto-starts persisted workers. If persisted discovery
+finds no auto-start candidates, `WorkerInit.autoStartPersistedWorkers()` falls back to file-backed
+worker definitions discovered from project files. This keeps existing persisted deployments stable
+while allowing fresh apps to boot workers from code-first definitions.
+
 ### Graceful Shutdown
 
 Shutdown workers gracefully:

package/dist/BroadcastWorker.d.ts

@@ -19,5 +19,10 @@ export declare const BroadcastWorker: Readonly<{
         signal?: AbortSignal;
         maxDurationMs?: number;
     }) => Promise<number>;
+    __zintrustQueueWorkerMeta?: Readonly<{
+        kindLabel: string;
+        defaultQueueName: string;
+        maxAttempts: number;
+    }>;
 }>;
 export default BroadcastWorker;

package/dist/NotificationWorker.d.ts

@@ -19,5 +19,10 @@ export declare const NotificationWorker: Readonly<{
         signal?: AbortSignal;
         maxDurationMs?: number;
     }) => Promise<number>;
+    __zintrustQueueWorkerMeta?: Readonly<{
+        kindLabel: string;
+        defaultQueueName: string;
+        maxAttempts: number;
+    }>;
 }>;
 export default NotificationWorker;

package/dist/WorkerFactory.d.ts

@@ -188,6 +188,14 @@ export declare const WorkerFactory: Readonly<{
      * Start a worker from persisted storage when it is not registered.
      */
     startFromPersisted(name: string, persistenceOverride?: WorkerPersistenceConfig): Promise<void>;
+    /**
+     * List worker definitions discovered from project files.
+     */
+    listFileBackedRecords(): Promise<WorkerRecord[]>;
+    /**
+     * Get a file-backed worker definition by name.
+     */
+    getFileBackedRecord(name: string): Promise<WorkerRecord | null>;
     /**
      * Get persisted worker record
      */

package/dist/WorkerFactory.js

@@ -3,7 +3,7 @@
  * Central factory for creating workers with all advanced features
  * Sealed namespace for immutability
  */
-import { Cloudflare, createRedisConnection, databaseConfig, Env, ErrorFactory, generateUuid, getBullMQSafeQueueName, JobStateTracker, Logger, NodeSingletons, queueConfig, registerDatabasesFromRuntimeConfig, useEnsureDbConnected, workersConfig, ZintrustLang, } from '@zintrust/core';
+import { Cloudflare, createRedisConnection, databaseConfig, Env, ErrorFactory, generateUuid, getBullMQSafeQueueName, isFunction, isNonEmptyString, isObject, JobStateTracker, Logger, NodeSingletons, queueConfig, registerDatabasesFromRuntimeConfig, useEnsureDbConnected, workersConfig, ZintrustLang, } from '@zintrust/core';
 import { Worker } from 'bullmq';
 import { AutoScaler } from './AutoScaler.js';
 import { CanaryController } from './CanaryController.js';
@@ -100,7 +100,6 @@ const resolvePackageSpecifierUrl = (specifier) => {
         return resolveLocalPackageFallback(specifier);
     }
 };
-const escapeRegExp = (value) => value.replaceAll(/[.*+?^${}()|[\]\\]/g, String.raw `\$&`);
 const rewriteProcessorImports = (code) => {
     const replacements = [];
     const coreUrl = resolvePackageSpecifierUrl('@zintrust/core');
@@ -113,8 +112,8 @@ const rewriteProcessorImports = (code) => {
         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`);
+        updated = updated.replaceAll(`'${from}'`, `'${to}'`);
+        updated = updated.replaceAll(`"${from}"`, `"${to}"`);
     }
     return updated;
 };
@@ -241,6 +240,24 @@ const processorRegistry = new Map();
 const processorPathRegistry = new Map();
 const processorResolvers = [];
 const processorSpecRegistry = new Map();
+const queueWorkerMetaKey = '__zintrustQueueWorkerMeta';
+const fileWorkerDefinitionExportKeys = Object.freeze([
+    'workerDefinition',
+    'workerConfig',
+    'zintrustWorker',
+    'ZinTrustWorker',
+    'worker',
+    'defaultWorkerDefinition',
+]);
+const workerDiscoveryDirectories = Object.freeze([
+    ['dist', 'app', 'Workers'],
+    ['dist', 'src', 'workers'],
+    ['dist', 'src', 'Workers'],
+    ['app', 'Workers'],
+    ['src', 'workers'],
+    ['src', 'Workers'],
+]);
+const workerDiscoveryExtensions = new Set(['.js', '.mjs', '.cjs', '.ts']);
 const processorCache = new Map();
 let processorCacheSize = 0;
 const buildPersistenceBootstrapConfig = () => {
@@ -311,6 +328,299 @@ const parseCacheControl = (value) => {
     return Number.isFinite(parsed) ? { maxAge: parsed } : {};
 };
 const getProcessorSpecConfig = () => workersConfig.processorSpec;
+const toPosixPath = (value) => value.split(path.sep).join('/');
+const isUpperAlpha = (value) => /^[A-Z]$/.test(value);
+const isLowerAlphaOrDigit = (value) => /^[a-z\d]$/.test(value);
+const isAlphaNumeric = (value) => /^[A-Za-z\d]$/.test(value);
+const shouldInsertWorkerNameDash = (previous, current, next) => {
+    if (!isAlphaNumeric(previous) || !isAlphaNumeric(current))
+        return false;
+    if (isLowerAlphaOrDigit(previous) && isUpperAlpha(current)) {
+        return true;
+    }
+    if (isUpperAlpha(previous) && isUpperAlpha(current) && isLowerAlphaOrDigit(next ?? '')) {
+        return true;
+    }
+    return false;
+};
+const toKebabWorkerName = (value) => {
+    if (!isNonEmptyString(value))
+        return value;
+    let normalized = '';
+    for (let index = 0; index < value.length; index += 1) {
+        const current = value[index] ?? '';
+        const previous = index > 0 ? (value[index - 1] ?? '') : '';
+        const next = value[index + 1];
+        if (current === ' ' || current === '_') {
+            if (!normalized.endsWith('-'))
+                normalized += '-';
+            continue;
+        }
+        if (shouldInsertWorkerNameDash(previous, current, next) && !normalized.endsWith('-')) {
+            normalized += '-';
+        }
+        normalized += current;
+    }
+    return normalized.replaceAll(/-+/g, '-');
+};
+const normalizeWorkerFileName = (fileName) => {
+    const baseName = fileName.replace(/\.[^.]+$/, '');
+    return toKebabWorkerName(baseName).toLowerCase();
+};
+const supportsWorkerFileDiscovery = () => {
+    return (isNodeRuntime() &&
+        canUseProjectFileImports() &&
+        typeof NodeSingletons.fs.readdirSync === 'function' &&
+        typeof NodeSingletons.fs.statSync === 'function');
+};
+const isSupportedWorkerModuleFile = (fileName) => {
+    if (!isNonEmptyString(fileName))
+        return false;
+    if (fileName.endsWith('.d.ts'))
+        return false;
+    if (fileName.includes('.test.') || fileName.includes('.spec.'))
+        return false;
+    return workerDiscoveryExtensions.has(path.extname(fileName));
+};
+const getWorkerDiscoveryDirectories = () => {
+    if (!supportsWorkerFileDiscovery())
+        return [];
+    const root = resolveProjectRoot();
+    return workerDiscoveryDirectories.map((segments) => path.join(root, ...segments));
+};
+const listWorkerDefinitionFiles = () => {
+    if (!supportsWorkerFileDiscovery())
+        return [];
+    const discovered = new Set();
+    for (const directory of getWorkerDiscoveryDirectories()) {
+        try {
+            if (!NodeSingletons.fs.existsSync(directory))
+                continue;
+            const stats = NodeSingletons.fs.statSync(directory);
+            if (!stats.isDirectory())
+                continue;
+            const entries = NodeSingletons.fs.readdirSync(directory, { withFileTypes: true });
+            for (const entry of entries) {
+                if (!entry.isFile() || !isSupportedWorkerModuleFile(entry.name))
+                    continue;
+                discovered.add(path.join(directory, entry.name));
+            }
+        }
+        catch (error) {
+            Logger.debug(`Worker file discovery failed for directory: ${directory}`, error);
+        }
+    }
+    return Array.from(discovered);
+};
+const getProjectRelativeWorkerSpec = (sourcePath) => {
+    const relativePath = path.relative(resolveProjectRoot(), sourcePath);
+    return isNonEmptyString(relativePath) ? toPosixPath(relativePath) : toPosixPath(sourcePath);
+};
+const isQueueWorkerMeta = (value) => {
+    return (isObject(value) &&
+        isNonEmptyString(value['kindLabel']) &&
+        isNonEmptyString(value['defaultQueueName']) &&
+        typeof value['maxAttempts'] === 'number');
+};
+const getExportedQueueWorkerMeta = (mod) => {
+    for (const value of Object.values(mod)) {
+        if (!isObject(value))
+            continue;
+        const meta = value[queueWorkerMetaKey];
+        if (isQueueWorkerMeta(meta))
+            return meta;
+    }
+    return undefined;
+};
+const assignStringDefinitionField = (definition, key, value) => {
+    if (isNonEmptyString(value)) {
+        definition[key] = value;
+    }
+};
+const assignBooleanDefinitionField = (definition, key, value) => {
+    if (typeof value === 'boolean') {
+        definition[key] = value;
+    }
+};
+const assignObjectDefinitionField = (definition, key, value) => {
+    if (isObject(value)) {
+        definition[key] = value;
+    }
+};
+const assignConcurrencyDefinitionField = (definition, value) => {
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        definition.concurrency = Math.max(1, Math.floor(value));
+    }
+};
+const assignProcessorDefinitionField = (definition, value) => {
+    if (isFunction(value)) {
+        definition.processor = value;
+    }
+};
+const normalizeFileWorkerDefinition = (value) => {
+    if (!isObject(value))
+        return undefined;
+    const definition = {};
+    assignStringDefinitionField(definition, 'name', value['name']);
+    assignStringDefinitionField(definition, 'queueName', value['queueName']);
+    assignStringDefinitionField(definition, 'version', value['version']);
+    assignStringDefinitionField(definition, 'status', value['status']);
+    assignStringDefinitionField(definition, 'region', value['region']);
+    assignStringDefinitionField(definition, 'processorSpec', value['processorSpec']);
+    assignBooleanDefinitionField(definition, 'autoStart', value['autoStart']);
+    assignBooleanDefinitionField(definition, 'activeStatus', value['activeStatus']);
+    assignObjectDefinitionField(definition, 'features', value['features']);
+    assignObjectDefinitionField(definition, 'infrastructure', value['infrastructure']);
+    assignObjectDefinitionField(definition, 'datacenter', value['datacenter']);
+    assignConcurrencyDefinitionField(definition, value['concurrency']);
+    assignProcessorDefinitionField(definition, value['processor']);
+    return definition;
+};
+const getExportedFileWorkerDefinition = (mod) => {
+    for (const key of fileWorkerDefinitionExportKeys) {
+        const normalized = normalizeFileWorkerDefinition(mod[key]);
+        if (normalized)
+            return normalized;
+    }
+    const defaultExport = mod['default'];
+    if (!isFunction(defaultExport)) {
+        const normalized = normalizeFileWorkerDefinition(defaultExport);
+        if (normalized)
+            return normalized;
+    }
+    return undefined;
+};
+const importWorkerDefinitionModule = async (sourcePath) => {
+    if (!supportsWorkerFileDiscovery())
+        return undefined;
+    try {
+        return (await import(NodeSingletons.url.pathToFileURL(sourcePath).href));
+    }
+    catch (error) {
+        Logger.debug(`Failed to import worker definition module: ${sourcePath}`, error);
+        return undefined;
+    }
+};
+const resolveDiscoveredWorkerProcessor = (definition, mod, sourcePath) => {
+    if (definition?.processor)
+        return definition.processor;
+    return extractZinTrustProcessor(mod, sourcePath) ?? pickProcessorFromModule(mod, sourcePath);
+};
+const resolveDiscoveredWorkerName = (definition, sourcePath) => {
+    return (definition?.name ?? normalizeWorkerFileName(path.basename(sourcePath, path.extname(sourcePath))));
+};
+const resolveDiscoveredQueueName = (definition, queueWorkerMeta, recordName) => {
+    if (definition?.queueName)
+        return definition.queueName;
+    if (queueWorkerMeta?.defaultQueueName)
+        return queueWorkerMeta.defaultQueueName;
+    return `${recordName}-queue`;
+};
+const resolveDiscoveredProcessorSpec = (definition, sourcePath) => {
+    return definition?.processorSpec ?? getProjectRelativeWorkerSpec(sourcePath);
+};
+const resolveDiscoveredVersion = (definition) => {
+    return definition?.version ?? '1.0.0';
+};
+const resolveDiscoveredStatus = (definition) => {
+    return definition?.status ?? WorkerCreationStatus.STOPPED;
+};
+const resolveDiscoveredAutoStart = (definition) => {
+    return definition?.autoStart ?? false;
+};
+const resolveDiscoveredConcurrency = (definition) => {
+    return definition?.concurrency ?? 1;
+};
+const resolveDiscoveredActiveStatus = (definition) => {
+    return definition?.activeStatus ?? true;
+};
+const buildDiscoveredWorkerRecord = (definition, queueWorkerMeta, sourcePath) => {
+    const recordName = resolveDiscoveredWorkerName(definition, sourcePath);
+    if (!isNonEmptyString(recordName))
+        return undefined;
+    return {
+        name: recordName,
+        queueName: resolveDiscoveredQueueName(definition, queueWorkerMeta, recordName),
+        version: resolveDiscoveredVersion(definition),
+        status: resolveDiscoveredStatus(definition),
+        autoStart: resolveDiscoveredAutoStart(definition),
+        concurrency: resolveDiscoveredConcurrency(definition),
+        region: definition?.region ?? null,
+        processorSpec: resolveDiscoveredProcessorSpec(definition, sourcePath),
+        activeStatus: resolveDiscoveredActiveStatus(definition),
+        features: definition?.features ?? null,
+        infrastructure: definition?.infrastructure ?? null,
+        datacenter: definition?.datacenter ?? null,
+        createdAt: new Date(),
+        updatedAt: new Date(),
+    };
+};
+const buildDiscoveredWorker = (mod, sourcePath) => {
+    const definition = getExportedFileWorkerDefinition(mod);
+    const queueWorkerMeta = getExportedQueueWorkerMeta(mod);
+    const processor = resolveDiscoveredWorkerProcessor(definition, mod, sourcePath);
+    const record = buildDiscoveredWorkerRecord(definition, queueWorkerMeta, sourcePath);
+    if (!record)
+        return undefined;
+    return {
+        record,
+        processor,
+        sourcePath,
+    };
+};
+const resolveStartFromPersistedRecord = async (name, persistenceOverride) => {
+    const persistedRecord = await getPersistedRecord(name, persistenceOverride);
+    const discovered = persistedRecord ? null : await getDiscoveredFileWorker(name);
+    const effectiveRecord = persistedRecord ?? discovered?.record ?? null;
+    if (!effectiveRecord) {
+        throw ErrorFactory.createNotFoundError(`Worker "${name}" not found in persistence store`);
+    }
+    return { record: effectiveRecord, discovered };
+};
+const resolveStartFromPersistedProcessor = async (name, record, discovered) => {
+    let processor = await resolveProcessor(name);
+    if (!processor && discovered?.processor) {
+        processor = discovered.processor;
+    }
+    const spec = record.processorSpec ?? undefined;
+    if (!processor && spec) {
+        try {
+            processor = await resolveProcessorSpec(spec);
+        }
+        catch (error) {
+            Logger.error(`Failed to resolve processor module for "${name}"`, error);
+        }
+    }
+    if (!processor) {
+        throw ErrorFactory.createConfigError(`Worker "${name}" processor is not registered or resolvable. Register the processor at startup or persist a processorSpec.`);
+    }
+    return processor;
+};
+const discoverFileBackedWorkers = async () => {
+    const files = listWorkerDefinitionFiles();
+    if (files.length === 0)
+        return [];
+    const discovered = new Map();
+    for (const filePath of files) {
+        // eslint-disable-next-line no-await-in-loop
+        const mod = await importWorkerDefinitionModule(filePath);
+        if (!mod)
+            continue;
+        const discoveredWorker = buildDiscoveredWorker(mod, filePath);
+        if (!discoveredWorker)
+            continue;
+        if (discovered.has(discoveredWorker.record.name)) {
+            Logger.warn(`Duplicate file-backed worker definition detected for "${discoveredWorker.record.name}". Keeping the first discovered module.`);
+            continue;
+        }
+        discovered.set(discoveredWorker.record.name, discoveredWorker);
+    }
+    return Array.from(discovered.values());
+};
+const getDiscoveredFileWorker = async (name) => {
+    const discovered = await discoverFileBackedWorkers();
+    return discovered.find((entry) => entry.record.name === name) ?? null;
+};
 const computeSha256 = async (value) => {
     if (typeof globalThis !== 'undefined' && globalThis.crypto?.subtle) {
         const data = new TextEncoder().encode(value);
@@ -384,7 +694,7 @@ const waitForWorkerConnection = async (worker, name, _queueName, timeoutMs) => {
         const checkConnection = async () => {
             try {
                 // Check if worker is actually running
-                const isRunning = await worker.isRunning();
+                const isRunning = await worker.isRunning(); // NOSONAR - BullMQ's isRunning method
                 if (!isRunning) {
                     throw ErrorFactory.createWorkerError('Worker not running');
                 }
@@ -1086,14 +1396,11 @@ const resolveRedisConfigFromDirect = (config, context) => {
     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),
+        password: config.password ?? Env.get('REDIS_PASSWORD'),
     };
 };
 const resolveRedisConfig = (config, context) => isRedisEnvConfig(config)
@@ -1398,12 +1705,8 @@ const resolveAutoScalerConfig = (input) => {
 };
 const resolveWorkerOptions = (config, autoStart) => {
     const options = config.options ? { ...config.options } : {};
-    if (options.prefix === undefined) {
-        options.prefix = getBullMQSafeQueueName();
-    }
-    if (options.autorun === undefined) {
-        options.autorun = autoStart;
-    }
+    options.prefix ??= getBullMQSafeQueueName();
+    options.autorun ??= autoStart;
     if (options.connection)
         return options;
     const redisConfig = resolveRedisConfigWithFallback(config.infrastructure?.redis, undefined, 'Worker requires a connection. Provide options.connection or infrastructure.redis config', 'infrastructure.redis');
@@ -2098,26 +2401,11 @@ export const WorkerFactory = Object.freeze({
      * Start a worker from persisted storage when it is not registered.
      */
     async startFromPersisted(name, persistenceOverride) {
-        const record = await getPersistedRecord(name, persistenceOverride);
-        if (!record) {
-            throw ErrorFactory.createNotFoundError(`Worker "${name}" not found in persistence store`);
-        }
+        const { record, discovered } = await resolveStartFromPersistedRecord(name, persistenceOverride);
         if (record.activeStatus === false) {
             throw ErrorFactory.createConfigError(`Worker "${name}" is inactive`);
         }
-        let processor = await resolveProcessor(name);
-        const spec = record.processorSpec ?? undefined;
-        if (!processor && spec) {
-            try {
-                processor = await resolveProcessorSpec(spec);
-            }
-            catch (error) {
-                Logger.error(`Failed to resolve processor module for "${name}"`, error);
-            }
-        }
-        if (!processor) {
-            throw ErrorFactory.createConfigError(`Worker "${name}" processor is not registered or resolvable. Register the processor at startup or persist a processorSpec.`);
-        }
+        const processor = await resolveStartFromPersistedProcessor(name, record, discovered);
         await WorkerFactory.create({
             name: record.name,
             queueName: record.queueName,
@@ -2132,6 +2420,20 @@ export const WorkerFactory = Object.freeze({
             datacenter: record.datacenter,
         });
     },
+    /**
+     * List worker definitions discovered from project files.
+     */
+    async listFileBackedRecords() {
+        const discovered = await discoverFileBackedWorkers();
+        return discovered.map((entry) => entry.record);
+    },
+    /**
+     * Get a file-backed worker definition by name.
+     */
+    async getFileBackedRecord(name) {
+        const discovered = await getDiscoveredFileWorker(name);
+        return discovered?.record ?? null;
+    },
     /**
      * Get persisted worker record
      */

package/dist/WorkerInit.d.ts

@@ -7,6 +7,7 @@
  * - Sets up auto-scaling and health checks
  * - Ensures graceful startup and shutdown
  */
+import type { WorkerPersistenceConfig } from './WorkerFactory';
 export interface IWorkerInitOptions {
     /**
      * Whether to start resource monitoring on initialization
@@ -42,6 +43,22 @@ interface IInitState {
     autoScaling: boolean;
     shutdownHandlersRegistered: boolean;
 }
+type AutoStartCandidate = {
+    name: string;
+    autoStart: boolean;
+    activeStatus?: boolean;
+};
+type PersistenceOverride = WorkerPersistenceConfig;
+type AutoStartTask = AutoStartCandidate & {
+    persistenceOverride: PersistenceOverride;
+    source: 'database' | 'redis' | 'memory' | 'file';
+};
+export declare const buildFileBackedAutoStartTasks: (records: AutoStartCandidate[], warn?: (message: string) => void) => AutoStartTask[];
+export declare const selectAutoStartTasks: (persistedTasks: AutoStartTask[], fileRecords: AutoStartCandidate[], warn?: (message: string) => void) => AutoStartTask[];
+export declare const selectAutoStartNames: (persistedRecords: AutoStartCandidate[], fileRecords: AutoStartCandidate[], warn?: (message: string) => void) => {
+    names: string[];
+    source: "persisted" | "file" | "none";
+};
 /**
  * Initialize the worker management system
  */

package/dist/WorkerInit.js

@@ -141,6 +141,54 @@ const collectAutoStartTasks = async () => {
     }
     return tasks;
 };
+export const buildFileBackedAutoStartTasks = (records, warn = Logger.warn) => {
+    const tasks = [];
+    const seenWorkerNames = new Set();
+    const candidates = resolveAutoStartCandidates(records);
+    for (const record of candidates) {
+        if (seenWorkerNames.has(record.name)) {
+            warn(`Worker ${record.name} appears multiple times in file-backed discovery; keeping the first definition and skipping duplicates.`);
+            continue;
+        }
+        seenWorkerNames.add(record.name);
+        tasks.push({
+            ...record,
+            persistenceOverride: { driver: 'memory' },
+            source: 'file',
+        });
+    }
+    return tasks;
+};
+export const selectAutoStartTasks = (persistedTasks, fileRecords, warn = Logger.warn) => {
+    if (persistedTasks.length > 0) {
+        return persistedTasks;
+    }
+    return buildFileBackedAutoStartTasks(fileRecords, warn);
+};
+export const selectAutoStartNames = (persistedRecords, fileRecords, warn = Logger.warn) => {
+    const persistedNames = resolveAutoStartCandidates(persistedRecords).map((record) => record.name);
+    if (persistedNames.length > 0) {
+        return { names: persistedNames, source: 'persisted' };
+    }
+    const fileNames = buildFileBackedAutoStartTasks(fileRecords, warn).map((record) => record.name);
+    return { names: fileNames, source: fileNames.length > 0 ? 'file' : 'none' };
+};
+const collectFileBackedAutoStartTasks = async () => {
+    try {
+        const records = await WorkerFactory.listFileBackedRecords();
+        const tasks = buildFileBackedAutoStartTasks(records);
+        Logger.debug('File-backed auto-start discovery', {
+            totalRecords: records.length,
+            candidateCount: tasks.length,
+        });
+        return tasks;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        Logger.warn(`File-backed auto-start discovery failed: ${message}`);
+    }
+    return [];
+};
 const isWorkerTrulyRunning = async (name) => {
     const existing = WorkerFactory.get(name);
     if (!existing)
@@ -238,14 +286,18 @@ async function autoStartPersistedWorkers() {
         return;
     }
     try {
-        const candidates = await collectAutoStartTasks();
+        let candidates = await collectAutoStartTasks();
+        if (candidates.length === 0) {
+            candidates = await collectFileBackedAutoStartTasks();
+        }
         const results = await Promise.all(candidates.map(async (record) => autoStartOneWorker(record)));
         const startedCount = results.filter((item) => item.started).length;
         const skippedCount = results.filter((item) => item.skipped).length;
-        Logger.info('Auto-started persisted workers', {
+        Logger.info('Auto-started workers', {
             total: candidates.length,
             started: startedCount,
             skipped: skippedCount,
+            source: candidates[0]?.source ?? 'none',
         });
     }
     catch (error) {

package/dist/WorkerShutdownDurableObject.d.ts

@@ -0,0 +1,12 @@
+type DurableObjectState = {
+    storage: {
+        get: (key: string) => Promise<unknown>;
+        put: (key: string, value: unknown) => Promise<void>;
+    };
+};
+export declare class ZinTrustWorkerShutdownDurableObject {
+    private readonly state;
+    constructor(state: DurableObjectState);
+    fetch(request: Request): Promise<Response>;
+}
+export {};

package/dist/WorkerShutdownDurableObject.js

@@ -0,0 +1,41 @@
+import { Logger } from '@zintrust/core';
+const loadState = async (state) => {
+    const stored = (await state.storage.get('shutdown'));
+    return stored ?? { shuttingDown: false };
+};
+const saveState = async (state, value) => {
+    await state.storage.put('shutdown', value);
+};
+// eslint-disable-next-line no-restricted-syntax
+export class ZinTrustWorkerShutdownDurableObject {
+    state;
+    constructor(state) {
+        this.state = state;
+    }
+    async fetch(request) {
+        const url = new URL(request.url);
+        const path = url.pathname;
+        if (request.method === 'GET' && path === '/status') {
+            const current = await loadState(this.state);
+            return new Response(JSON.stringify(current), {
+                status: 200,
+                headers: { 'content-type': 'application/json' },
+            });
+        }
+        if (request.method === 'POST' && path === '/shutdown') {
+            const payload = (await request.json().catch(() => ({})));
+            const next = {
+                shuttingDown: true,
+                startedAt: new Date().toISOString(),
+                reason: payload.reason ?? 'manual',
+            };
+            await saveState(this.state, next);
+            Logger.info('Worker shutdown requested via Durable Object', next);
+            return new Response(JSON.stringify({ ok: true }), {
+                status: 202,
+                headers: { 'content-type': 'application/json' },
+            });
+        }
+        return new Response('Not Found', { status: 404 });
+    }
+}