@zintrust/core 0.4.17 → 0.4.18

package/src/tools/queue/QueueExtensions.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Queue Extensions - Backward Compatible Extensions
+ * Extends existing Queue functionality without breaking changes
+ */
+import type { AdvancedJobOptions, QueueConfig } from '../../types/Queue';
+import { createDeduplicationBuilder } from './DeduplicationBuilder';
+import type { BullMQPayload } from './Queue';
+/**
+ * Extend existing Queue with advanced capabilities
+ * This provides a migration path for existing code
+ */
+export declare function extendQueue(config: QueueConfig): void;
+/**
+ * Enhanced enqueue method that supports advanced options
+ * This can be used as a drop-in replacement for Queue.enqueue
+ */
+export declare function enqueueAdvanced(name: string, payload: BullMQPayload, options?: AdvancedJobOptions): Promise<string>;
+/**
+ * Initialize default lock providers
+ */
+export declare function initializeDefaultLockProviders(): void;
+/**
+ * Get deduplication builder instance
+ */
+export declare function getDeduplicationBuilder(): ReturnType<typeof createDeduplicationBuilder>;
+/**
+ * Queue utilities for lock management
+ */
+export declare const QueueLocks: {
+    release: (key: string) => Promise<void>;
+    extend: (key: string, ttl: number) => Promise<boolean>;
+    status: (key: string) => Promise<boolean>;
+};
+/**
+ * Migration helpers for existing queue code
+ */
+export declare const MigrationHelpers: {
+    /**
+     * Convert existing job options to advanced options
+     */
+    toAdvancedOptions(existingOptions: Record<string, unknown>, uniqueId?: string): AdvancedJobOptions;
+    /**
+     * Add deduplication to existing job patterns
+     */
+    withDeduplication(existingOptions: Record<string, unknown>, deduplicationId: string, ttl?: number): AdvancedJobOptions;
+};
+//# sourceMappingURL=QueueExtensions.d.ts.map

package/src/tools/queue/QueueExtensions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"QueueExtensions.d.ts","sourceRoot":"","sources":["../../../../src/tools/queue/QueueExtensions.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAsB,WAAW,EAAE,MAAM,eAAe,CAAC;AAKzF,OAAO,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAC;AAEzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAKlD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAWrD;AAED;;;GAGG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,aAAa,EACtB,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,MAAM,CAAC,CAQjB;AAED;;GAEG;AACH,wBAAgB,8BAA8B,IAAI,IAAI,CAuBrD;AAED;;GAEG;AACH,wBAAgB,uBAAuB,IAAI,UAAU,CAAC,OAAO,0BAA0B,CAAC,CAEvF;AAED;;GAEG;AACH,eAAO,MAAM,UAAU,EAAE;IACvB,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACxC,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACvD,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAkC3C,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,gBAAgB;IAC3B;;OAEG;uCAEgB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,aAC7B,MAAM,GAChB,kBAAkB;IAOrB;;OAEG;uCAEgB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,mBACvB,MAAM,QACjB,MAAM,GACX,kBAAkB;CAStB,CAAC"}

package/src/tools/queue/QueueExtensions.js

@@ -0,0 +1,130 @@
+/**
+ * Queue Extensions - Backward Compatible Extensions
+ * Extends existing Queue functionality without breaking changes
+ */
+import { Logger } from '../../config/logger.js';
+import { createValidationError } from '../../exceptions/ZintrustError.js';
+import { ZintrustLang } from '../../lang/lang.js';
+import { createAdvancedQueue } from './AdvancedQueue.js';
+import { createDeduplicationBuilder } from './DeduplicationBuilder.js';
+import { createLockProvider, registerLockProvider } from './LockProvider.js';
+import { Queue } from './Queue.js';
+let advancedQueueRef = null;
+/**
+ * Extend existing Queue with advanced capabilities
+ * This provides a migration path for existing code
+ */
+export function extendQueue(config) {
+    try {
+        const advancedQueue = createAdvancedQueue(config);
+        advancedQueueRef = advancedQueue;
+        Logger.info(`Queue extended with advanced capabilities`, { queueName: config.name });
+    }
+    catch (error) {
+        Logger.error(`Failed to extend queue with advanced capabilities`, { error });
+        throw error;
+    }
+}
+/**
+ * Enhanced enqueue method that supports advanced options
+ * This can be used as a drop-in replacement for Queue.enqueue
+ */
+export async function enqueueAdvanced(name, payload, options = {}) {
+    if (advancedQueueRef === null) {
+        Logger.warn(`Advanced queue not initialized, falling back to standard enqueue`);
+        const getQueue = await Queue?.enqueue(name, payload);
+        return getQueue ?? '';
+    }
+    return advancedQueueRef.enqueue(name, payload, options);
+}
+/**
+ * Initialize default lock providers
+ */
+export function initializeDefaultLockProviders() {
+    // Register memory lock provider for sync driver
+    registerLockProvider(ZintrustLang.MEMORY, createLockProvider({
+        type: ZintrustLang.MEMORY,
+        prefix: ZintrustLang.ZINTRUST_LOCKS_PREFIX,
+        defaultTtl: ZintrustLang.ZINTRUST_LOCKS_TTL,
+    }));
+    // Register Redis lock provider if Redis is available
+    try {
+        const redisConfig = {
+            type: ZintrustLang.REDIS,
+            prefix: ZintrustLang.ZINTRUST_LOCKS_PREFIX,
+            defaultTtl: ZintrustLang.ZINTRUST_LOCKS_TTL,
+        };
+        registerLockProvider('redis', createLockProvider(redisConfig));
+        Logger.info(`Redis lock provider registered`);
+    }
+    catch (error) {
+        Logger.warn(`Redis lock provider registration failed, using memory provider`, { error });
+    }
+}
+/**
+ * Get deduplication builder instance
+ */
+export function getDeduplicationBuilder() {
+    return createDeduplicationBuilder();
+}
+/**
+ * Queue utilities for lock management
+ */
+export const QueueLocks = {
+    /**
+     * Release a lock by key
+     */
+    async release(key) {
+        if (advancedQueueRef !== null) {
+            return advancedQueueRef.releaseLock(key);
+        }
+        throw createValidationError('Advanced queue not initialized. Call extendQueue() first.');
+    },
+    /**
+     * Extend a lock's TTL
+     */
+    async extend(key, ttl) {
+        if (advancedQueueRef !== null) {
+            return advancedQueueRef.extendLock(key, ttl);
+        }
+        throw createValidationError('Advanced queue not initialized. Call extendQueue() first.');
+    },
+    /**
+     * Check lock status
+     */
+    async status(key) {
+        const { getLockProvider } = await import('../../tools/queue/LockProvider.js');
+        const lockProvider = getLockProvider(ZintrustLang.MEMORY);
+        if (lockProvider !== undefined) {
+            const status = await lockProvider.status(key);
+            return status.exists;
+        }
+        return false;
+    },
+};
+/**
+ * Migration helpers for existing queue code
+ */
+export const MigrationHelpers = {
+    /**
+     * Convert existing job options to advanced options
+     */
+    toAdvancedOptions(existingOptions, uniqueId) {
+        return {
+            ...existingOptions,
+            ...(uniqueId !== null && uniqueId !== undefined && uniqueId !== '' && { uniqueId }),
+        };
+    },
+    /**
+     * Add deduplication to existing job patterns
+     */
+    withDeduplication(existingOptions, deduplicationId, ttl) {
+        return {
+            ...existingOptions,
+            deduplication: createDeduplicationBuilder()
+                .id(deduplicationId)
+                .expireAfter(ttl ?? ZintrustLang.ZINTRUST_LOCKS_TTL)
+                .build(),
+        };
+    },
+};

package/src/tools/queue/QueueReliabilityMetrics.d.ts

@@ -0,0 +1,38 @@
+export type QueueReliabilitySnapshot = {
+    pending: number;
+    active: number;
+    completed: number;
+    failed: number;
+    stalled: number;
+    timeout: number;
+    pendingRecovery: number;
+    deadLetter: number;
+    manualReview: number;
+};
+export type QueueReliabilityAlertId = 'HighJobFailureRate' | 'StalledJobsAccumulating' | 'QueueDepthGrowing' | 'ManualReviewBacklog';
+export type QueueReliabilityAlert = {
+    id: QueueReliabilityAlertId;
+    severity: 'warning' | 'critical';
+    message: string;
+    value: number;
+    threshold: number;
+    runbook: string;
+};
+export type QueueReliabilityDashboardSnapshot = {
+    queueName: string;
+    generatedAt: string;
+    metrics: QueueReliabilitySnapshot & {
+        totalTracked: number;
+        queueDepth: number;
+        failureRate: number;
+    };
+    alerts: QueueReliabilityAlert[];
+    runbooks: Record<QueueReliabilityAlertId, string>;
+};
+export declare const QueueReliabilityMetrics: Readonly<{
+    snapshot(queueName?: string): QueueReliabilitySnapshot;
+    runbookMap(): Record<QueueReliabilityAlertId, string>;
+    dashboardSnapshot(queueName?: string): Promise<QueueReliabilityDashboardSnapshot>;
+}>;
+export default QueueReliabilityMetrics;
+//# sourceMappingURL=QueueReliabilityMetrics.d.ts.map

package/src/tools/queue/QueueReliabilityMetrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"QueueReliabilityMetrics.d.ts","sourceRoot":"","sources":["../../../../src/tools/queue/QueueReliabilityMetrics.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,wBAAwB,GAAG;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAC/B,oBAAoB,GACpB,yBAAyB,GACzB,mBAAmB,GACnB,qBAAqB,CAAC;AAE1B,MAAM,MAAM,qBAAqB,GAAG;IAClC,EAAE,EAAE,uBAAuB,CAAC;IAC5B,QAAQ,EAAE,SAAS,GAAG,UAAU,CAAC;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,iCAAiC,GAAG;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,wBAAwB,GAAG;QAClC,YAAY,EAAE,MAAM,CAAC;QACrB,UAAU,EAAE,MAAM,CAAC;QACnB,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;IACF,MAAM,EAAE,qBAAqB,EAAE,CAAC;IAChC,QAAQ,EAAE,MAAM,CAAC,uBAAuB,EAAE,MAAM,CAAC,CAAC;CACnD,CAAC;AAwFF,eAAO,MAAM,uBAAuB;yBACb,MAAM,GAAG,wBAAwB;kBAexC,MAAM,CAAC,uBAAuB,EAAE,MAAM,CAAC;kCAIjB,MAAM,GAAG,OAAO,CAAC,iCAAiC,CAAC;EA0CvF,CAAC;AAEH,eAAe,uBAAuB,CAAC"}

package/src/tools/queue/QueueReliabilityMetrics.js

@@ -0,0 +1,131 @@
+import { Env } from '../../config/env.js';
+import { JobStateTracker } from './JobStateTracker.js';
+import { Queue } from './Queue.js';
+const toNumber = (input, key) => input[key] ?? 0;
+const toRate = (failed, completed) => {
+    const denominator = failed + completed;
+    if (denominator <= 0)
+        return 0;
+    return failed / denominator;
+};
+const resolveRunbookBase = () => {
+    const base = Env.get('JOB_RUNBOOK_BASE_URL', '/docs/runbooks').trim();
+    if (base === '')
+        return '/docs/runbooks';
+    return base.endsWith('/') ? base.slice(0, -1) : base;
+};
+const getRunbookMap = () => {
+    const base = resolveRunbookBase();
+    return {
+        HighJobFailureRate: `${base}/high-job-failure-rate`,
+        StalledJobsAccumulating: `${base}/stalled-jobs-accumulating`,
+        QueueDepthGrowing: `${base}/queue-depth-growing`,
+        ManualReviewBacklog: `${base}/manual-review-backlog`,
+    };
+};
+const evaluateAlerts = (queueName, metrics) => {
+    const runbooks = getRunbookMap();
+    const alerts = [];
+    const failureThreshold = Math.max(0, Env.getFloat('JOB_ALERT_FAILURE_RATE_THRESHOLD', 0.1));
+    const stalledThreshold = Math.max(1, Env.getInt('JOB_ALERT_STALLED_THRESHOLD', 50));
+    const queueDepthThreshold = Math.max(1, Env.getInt('JOB_ALERT_QUEUE_DEPTH_THRESHOLD', 1000));
+    const manualReviewThreshold = Math.max(1, Env.getInt('JOB_ALERT_MANUAL_REVIEW_THRESHOLD', 10));
+    if (metrics.failureRate > failureThreshold) {
+        alerts.push({
+            id: 'HighJobFailureRate',
+            severity: 'critical',
+            message: `Queue ${queueName} failure rate is above threshold`,
+            value: Number(metrics.failureRate.toFixed(6)),
+            threshold: failureThreshold,
+            runbook: runbooks.HighJobFailureRate,
+        });
+    }
+    if (metrics.stalled > stalledThreshold) {
+        alerts.push({
+            id: 'StalledJobsAccumulating',
+            severity: 'critical',
+            message: `Queue ${queueName} stalled jobs exceed threshold`,
+            value: metrics.stalled,
+            threshold: stalledThreshold,
+            runbook: runbooks.StalledJobsAccumulating,
+        });
+    }
+    if (metrics.queueDepth > queueDepthThreshold) {
+        alerts.push({
+            id: 'QueueDepthGrowing',
+            severity: 'warning',
+            message: `Queue ${queueName} depth is above threshold`,
+            value: metrics.queueDepth,
+            threshold: queueDepthThreshold,
+            runbook: runbooks.QueueDepthGrowing,
+        });
+    }
+    if (metrics.manualReview > manualReviewThreshold) {
+        alerts.push({
+            id: 'ManualReviewBacklog',
+            severity: 'warning',
+            message: `Queue ${queueName} manual-review backlog is above threshold`,
+            value: metrics.manualReview,
+            threshold: manualReviewThreshold,
+            runbook: runbooks.ManualReviewBacklog,
+        });
+    }
+    return alerts;
+};
+export const QueueReliabilityMetrics = Object.freeze({
+    snapshot(queueName) {
+        const summary = JobStateTracker.getSummary(queueName);
+        return {
+            pending: toNumber(summary, 'pending'),
+            active: toNumber(summary, 'active'),
+            completed: toNumber(summary, 'completed'),
+            failed: toNumber(summary, 'failed'),
+            stalled: toNumber(summary, 'stalled'),
+            timeout: toNumber(summary, 'timeout'),
+            pendingRecovery: toNumber(summary, 'pending_recovery'),
+            deadLetter: toNumber(summary, 'dead_letter'),
+            manualReview: toNumber(summary, 'manual_review'),
+        };
+    },
+    runbookMap() {
+        return getRunbookMap();
+    },
+    async dashboardSnapshot(queueName) {
+        const normalizedQueueName = typeof queueName === 'string' ? queueName.trim() : '';
+        const resolvedQueueName = normalizedQueueName === ''
+            ? Env.get('JOB_DASHBOARD_DEFAULT_QUEUE', 'default')
+            : normalizedQueueName;
+        const metrics = this.snapshot(resolvedQueueName);
+        let queueDepth = 0;
+        try {
+            queueDepth = await Queue.length(resolvedQueueName);
+        }
+        catch {
+            queueDepth = 0;
+        }
+        const totalTracked = metrics.pending +
+            metrics.active +
+            metrics.completed +
+            metrics.failed +
+            metrics.stalled +
+            metrics.timeout +
+            metrics.pendingRecovery +
+            metrics.deadLetter +
+            metrics.manualReview;
+        const failureRate = toRate(metrics.failed + metrics.deadLetter, metrics.completed);
+        const derivedMetrics = {
+            ...metrics,
+            totalTracked,
+            queueDepth,
+            failureRate,
+        };
+        return {
+            queueName: resolvedQueueName,
+            generatedAt: new Date().toISOString(),
+            metrics: derivedMetrics,
+            alerts: evaluateAlerts(resolvedQueueName, derivedMetrics),
+            runbooks: getRunbookMap(),
+        };
+    },
+});
+export default QueueReliabilityMetrics;

package/src/tools/queue/QueueReliabilityOrchestrator.d.ts

@@ -0,0 +1,7 @@
+export declare const QueueReliabilityOrchestrator: Readonly<{
+    isEnabled(): boolean;
+    start(): void;
+    stop(): void;
+}>;
+export default QueueReliabilityOrchestrator;
+//# sourceMappingURL=QueueReliabilityOrchestrator.d.ts.map

package/src/tools/queue/QueueReliabilityOrchestrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"QueueReliabilityOrchestrator.d.ts","sourceRoot":"","sources":["../../../../src/tools/queue/QueueReliabilityOrchestrator.ts"],"names":[],"mappings":"AAmDA,eAAO,MAAM,4BAA4B;iBAC1B,OAAO;aAIX,IAAI;YA4BL,IAAI;EAUZ,CAAC;AAEH,eAAe,4BAA4B,CAAC"}

package/src/tools/queue/QueueReliabilityOrchestrator.js

@@ -0,0 +1,71 @@
+import { Env } from '../../config/env.js';
+import { Logger } from '../../config/logger.js';
+import { JobReconciliationRunner } from './JobReconciliationRunner.js';
+import { JobRecoveryDaemon } from './JobRecoveryDaemon.js';
+import { StalledJobMonitor } from './StalledJobMonitor.js';
+const isUnrefableTimer = (timer) => {
+    return (typeof timer === 'object' &&
+        timer !== null &&
+        'unref' in timer &&
+        typeof timer.unref === 'function');
+};
+const state = {
+    started: false,
+};
+const clearTimer = (timer) => {
+    if (timer === undefined)
+        return;
+    clearInterval(timer);
+};
+const startInterval = (handler, intervalMs) => {
+    const timer = setInterval(() => {
+        handler().catch((error) => {
+            Logger.warn('Queue reliability interval failed', {
+                error: error instanceof Error ? error : String(error),
+            });
+        });
+    }, intervalMs);
+    if (isUnrefableTimer(timer)) {
+        timer.unref();
+    }
+    return timer;
+};
+export const QueueReliabilityOrchestrator = Object.freeze({
+    isEnabled() {
+        return Env.getBool('JOB_RELIABILITY_ENABLED', true);
+    },
+    start() {
+        if (!this.isEnabled())
+            return;
+        if (state.started)
+            return;
+        const reconciliationMs = Math.max(5000, Env.getInt('JOB_RECONCILIATION_INTERVAL_MS', 60000));
+        const recoveryMs = Math.max(5000, Env.getInt('JOB_RECOVERY_INTERVAL_MS', 30000));
+        const stalledMs = Math.max(5000, Env.getInt('STALLED_JOB_CHECK_INTERVAL_MS', 30000));
+        state.reconciliationTimer = startInterval(async () => {
+            await JobReconciliationRunner.runOnce();
+        }, reconciliationMs);
+        state.recoveryTimer = startInterval(async () => {
+            await JobRecoveryDaemon.runOnce();
+        }, recoveryMs);
+        state.stalledTimer = startInterval(async () => {
+            await StalledJobMonitor.scanOnce();
+        }, stalledMs);
+        state.started = true;
+        Logger.info('Queue reliability orchestrator started', {
+            reconciliationMs,
+            recoveryMs,
+            stalledMs,
+        });
+    },
+    stop() {
+        clearTimer(state.reconciliationTimer);
+        clearTimer(state.recoveryTimer);
+        clearTimer(state.stalledTimer);
+        state.reconciliationTimer = undefined;
+        state.recoveryTimer = undefined;
+        state.stalledTimer = undefined;
+        state.started = false;
+    },
+});
+export default QueueReliabilityOrchestrator;

package/src/tools/queue/QueueRuntimeRegistration.d.ts

@@ -0,0 +1,3 @@
+import type { QueueConfig } from '../../config/queue';
+export declare function registerQueuesFromRuntimeConfig(config: QueueConfig): Promise<void>;
+//# sourceMappingURL=QueueRuntimeRegistration.d.ts.map

package/src/tools/queue/QueueRuntimeRegistration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"QueueRuntimeRegistration.d.ts","sourceRoot":"","sources":["../../../../src/tools/queue/QueueRuntimeRegistration.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAoFjD,wBAAsB,+BAA+B,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAyCxF"}

package/src/tools/queue/QueueRuntimeRegistration.js

@@ -0,0 +1,96 @@
+import { Logger } from '../../config/logger.js';
+import { Env } from '../../config/env.js';
+import { ErrorFactory } from '../../exceptions/ZintrustError.js';
+import { ZintrustLang } from '../../lang/lang.js';
+import { existsSync } from '../../node-singletons/fs.js';
+import * as path from '../../node-singletons/path.js';
+import { pathToFileURL } from '../../node-singletons/url.js';
+import { detectRuntime } from '../../runtime/detectRuntime.js';
+import { DatabaseQueue } from '../queue/drivers/Database.js';
+import { autoRegisterJobStateTrackerPersistenceFromEnv } from '../queue/JobStateTrackerDbPersistence.js';
+import { QueueReliabilityOrchestrator } from '../queue/QueueReliabilityOrchestrator.js';
+import { InMemoryQueue } from '../queue/drivers/InMemory.js';
+import { Queue } from '../queue/Queue.js';
+/**
+ * Register queue drivers from runtime config.
+ *
+ * This follows the framework's config-driven availability pattern:
+ * - Built-in drivers are registered so `QUEUE_DRIVER=sync|inmemory|redis` works out of the box.
+ * - If the configured default is registered, it is ALSO registered as 'default'.
+ * - Unknown/unregistered driver names still throw when selected.
+ */
+const registerRedisDriverIfAvailable = async () => {
+    try {
+        const mod = (await import('@zintrust/queue-redis'));
+        if (mod.RedisQueue !== undefined) {
+            Queue.register('redis', mod.RedisQueue);
+            return true;
+        }
+        if (mod.BullMQRedisQueue !== undefined) {
+            Queue.register('redis', mod.BullMQRedisQueue);
+            return true;
+        }
+    }
+    catch {
+        // Fall back to local dist build output when running inside the core repo Docker image.
+        // In that environment, `@zintrust/queue-redis` is not installed in node_modules,
+        // but the compiled package is available at `dist/packages/queue-redis`.
+        try {
+            const cwd = typeof process !== 'undefined' && typeof process.cwd === 'function' ? process.cwd() : '';
+            if (cwd.trim() === '')
+                return false;
+            const localEntry = path.join(cwd, 'dist', 'packages', 'queue-redis', 'src', 'index.js');
+            if (!existsSync(localEntry))
+                return false;
+            const url = pathToFileURL(localEntry).href;
+            const localMod = (await import(url));
+            if (localMod.RedisQueue !== undefined) {
+                Queue.register('redis', localMod.RedisQueue);
+                return true;
+            }
+            if (localMod.BullMQRedisQueue !== undefined) {
+                Queue.register('redis', localMod.BullMQRedisQueue);
+                return true;
+            }
+        }
+        catch {
+            // ignore
+        }
+        return false;
+    }
+    return false;
+};
+export async function registerQueuesFromRuntimeConfig(config) {
+    autoRegisterJobStateTrackerPersistenceFromEnv();
+    // Built-in drivers (core)
+    Queue.register('inmemory', InMemoryQueue);
+    Queue.register(ZintrustLang.DATABASE, DatabaseQueue);
+    // Project templates use QUEUE_DRIVER=sync; treat this as an alias of in-memory.
+    Queue.register('sync', InMemoryQueue);
+    const defaultName = (config.default ?? '').toString().trim().toLowerCase();
+    if (defaultName.length === 0) {
+        throw ErrorFactory.createConfigError('Queue default driver is not configured');
+    }
+    if (defaultName === 'redis') {
+        const registered = await registerRedisDriverIfAvailable();
+        if (!registered) {
+            throw ErrorFactory.createConfigError('Redis queue driver is not registered. Install queue:redis via zin plugin install.');
+        }
+    }
+    try {
+        const drv = Queue.get(defaultName);
+        Queue.register('default', drv);
+        if (Env.getBool('JOB_RELIABILITY_AUTOSTART', false)) {
+            QueueReliabilityOrchestrator.start();
+        }
+    }
+    catch (error) {
+        const { isCloudflare } = detectRuntime();
+        if (isCloudflare) {
+            Logger.warn(`[queue] Default driver '${defaultName}' is unavailable in Cloudflare runtime; falling back to 'sync'.`);
+            Queue.register('default', Queue.get('sync'));
+            return;
+        }
+        throw ErrorFactory.createConfigError('Queue default driver is not available', error);
+    }
+}

package/src/tools/queue/QueueTracing.d.ts

@@ -0,0 +1,32 @@
+export type QueueTraceOperation = 'enqueue' | 'dequeue' | 'ack' | 'length' | 'drain';
+export type QueueTraceStatus = 'ok' | 'error';
+export type QueueTraceEvent = {
+    traceId: string;
+    spanId: string;
+    queueName: string;
+    operation: QueueTraceOperation;
+    status: QueueTraceStatus;
+    startedAt: string;
+    endedAt: string;
+    durationMs: number;
+    error?: string;
+    attributes?: Record<string, unknown>;
+};
+export type QueueTraceExporter = (events: ReadonlyArray<QueueTraceEvent>) => void | Promise<void>;
+export declare const QueueTracing: Readonly<{
+    isEnabled: () => boolean;
+    registerExporter(exporter: QueueTraceExporter): void;
+    unregisterExporter(exporter: QueueTraceExporter): void;
+    flush(): Promise<number>;
+    snapshot(limit?: number): QueueTraceEvent[];
+    prune(): void;
+    reset(): void;
+    traceOperation<T>(input: {
+        queueName: string;
+        operation: QueueTraceOperation;
+        attributes?: Record<string, unknown>;
+        execute: () => Promise<T>;
+    }): Promise<T>;
+}>;
+export default QueueTracing;
+//# sourceMappingURL=QueueTracing.d.ts.map

package/src/tools/queue/QueueTracing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"QueueTracing.d.ts","sourceRoot":"","sources":["../../../../src/tools/queue/QueueTracing.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,mBAAmB,GAAG,SAAS,GAAG,SAAS,GAAG,KAAK,GAAG,QAAQ,GAAG,OAAO,CAAC;AAErF,MAAM,MAAM,gBAAgB,GAAG,IAAI,GAAG,OAAO,CAAC;AAE9C,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,mBAAmB,CAAC;IAC/B,MAAM,EAAE,gBAAgB,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,eAAe,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAiFlG,eAAO,MAAM,YAAY;qBArEH,OAAO;+BAwEA,kBAAkB,GAAG,IAAI;iCAIvB,kBAAkB,GAAG,IAAI;aAIvC,OAAO,CAAC,MAAM,CAAC;8BAuBP,eAAe,EAAE;aAO/B,IAAI;aAIJ,IAAI;mBAMQ,CAAC,SAAS;QAC7B,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,mBAAmB,CAAC;QAC/B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACrC,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,CAAC;KAC3B,GAAG,OAAO,CAAC,CAAC,CAAC;EAiDd,CAAC;AAEH,eAAe,YAAY,CAAC"}