@kaikybrofc/omnizap-system 2.2.4 → 2.2.5

package/app/modules/stickerPackModule/domainEventOutboxRepository.js

@@ -0,0 +1,243 @@
+import { randomUUID } from 'node:crypto';
+
+import { executeQuery, TABLES } from '../../../database/index.js';
+import { normalizeDomainEventPayload } from './domainEvents.js';
+
+const normalizeStatus = (value) => {
+  const normalized = String(value || '').trim().toLowerCase();
+  if (['pending', 'processing', 'completed', 'failed'].includes(normalized)) return normalized;
+  return null;
+};
+
+const parseJson = (value, fallback = null) => {
+  if (value === null || value === undefined) return fallback;
+  if (typeof value === 'object') return value;
+  if (Buffer.isBuffer(value)) {
+    try {
+      return JSON.parse(value.toString('utf8'));
+    } catch {
+      return fallback;
+    }
+  }
+  if (typeof value === 'string') {
+    try {
+      return JSON.parse(value);
+    } catch {
+      return fallback;
+    }
+  }
+  return fallback;
+};
+
+const clampInt = (value, fallback, min, max) => {
+  const numeric = Number(value);
+  if (!Number.isFinite(numeric)) return fallback;
+  return Math.max(min, Math.min(max, Math.floor(numeric)));
+};
+
+const CLAIM_LOCK_TIMEOUT_SECONDS = clampInt(
+  process.env.DOMAIN_EVENT_OUTBOX_LOCK_TIMEOUT_SECONDS,
+  15 * 60,
+  30,
+  24 * 60 * 60,
+);
+
+const normalizeRow = (row) => {
+  if (!row) return null;
+  return {
+    id: Number(row.id),
+    event_type: row.event_type,
+    aggregate_type: row.aggregate_type,
+    aggregate_id: row.aggregate_id,
+    payload: parseJson(row.payload, {}),
+    status: row.status,
+    priority: Number(row.priority || 0),
+    idempotency_key: row.idempotency_key || null,
+    available_at: row.available_at || null,
+    attempts: Number(row.attempts || 0),
+    max_attempts: Number(row.max_attempts || 0),
+    worker_token: row.worker_token || null,
+    last_error: row.last_error || null,
+    locked_at: row.locked_at || null,
+    processed_at: row.processed_at || null,
+    created_at: row.created_at || null,
+    updated_at: row.updated_at || null,
+  };
+};
+
+export async function enqueueDomainEvent(eventPayload, connection = null) {
+  const normalized = normalizeDomainEventPayload(eventPayload);
+  if (!normalized) return false;
+
+  await executeQuery(
+    `INSERT INTO ${TABLES.DOMAIN_EVENT_OUTBOX}
+      (
+        event_type,
+        aggregate_type,
+        aggregate_id,
+        payload,
+        status,
+        priority,
+        idempotency_key,
+        available_at,
+        attempts,
+        max_attempts
+      )
+     VALUES (?, ?, ?, ?, 'pending', ?, ?, COALESCE(?, UTC_TIMESTAMP()), 0, ?)
+     ON DUPLICATE KEY UPDATE
+      priority = GREATEST(priority, VALUES(priority)),
+      available_at = LEAST(available_at, VALUES(available_at)),
+      updated_at = CURRENT_TIMESTAMP`,
+    [
+      normalized.event_type,
+      normalized.aggregate_type,
+      normalized.aggregate_id,
+      JSON.stringify(normalized.payload ?? {}),
+      normalized.priority,
+      normalized.idempotency_key,
+      normalized.available_at,
+      normalized.max_attempts,
+    ],
+    connection,
+  );
+  return true;
+}
+
+export async function claimDomainEvent(
+  {
+    eventTypes = [],
+    allowRetryFailed = true,
+  } = {},
+  connection = null,
+) {
+  const workerToken = randomUUID();
+  const statusClause = allowRetryFailed
+    ? `(status = 'pending'
+      OR (status = 'failed' AND attempts < max_attempts)
+      OR (status = 'processing' AND locked_at <= (UTC_TIMESTAMP() - INTERVAL ${CLAIM_LOCK_TIMEOUT_SECONDS} SECOND)))`
+    : `(status = 'pending'
+      OR (status = 'processing' AND locked_at <= (UTC_TIMESTAMP() - INTERVAL ${CLAIM_LOCK_TIMEOUT_SECONDS} SECOND)))`;
+
+  const normalizedTypes = Array.from(
+    new Set((Array.isArray(eventTypes) ? eventTypes : [])
+      .map((type) => String(type || '').trim().toUpperCase())
+      .filter(Boolean)),
+  );
+
+  let eventTypeClause = '';
+  let params = [workerToken];
+  if (normalizedTypes.length) {
+    eventTypeClause = `AND event_type IN (${normalizedTypes.map(() => '?').join(', ')})`;
+    params = [workerToken, ...normalizedTypes];
+  }
+
+  await executeQuery(
+    `UPDATE ${TABLES.DOMAIN_EVENT_OUTBOX}
+     SET status = 'processing',
+         worker_token = ?,
+         locked_at = UTC_TIMESTAMP(),
+         attempts = attempts + 1,
+         updated_at = UTC_TIMESTAMP()
+     WHERE id = (
+       SELECT id FROM (
+         SELECT id
+         FROM ${TABLES.DOMAIN_EVENT_OUTBOX}
+         WHERE ${statusClause}
+           ${eventTypeClause}
+           AND available_at <= UTC_TIMESTAMP()
+         ORDER BY priority DESC, available_at ASC, id ASC
+         LIMIT 1
+       ) picked
+     )`,
+    params,
+    connection,
+  );
+
+  const rows = await executeQuery(
+    `SELECT *
+     FROM ${TABLES.DOMAIN_EVENT_OUTBOX}
+     WHERE worker_token = ?
+       AND status = 'processing'
+     ORDER BY id DESC
+     LIMIT 1`,
+    [workerToken],
+    connection,
+  );
+
+  return normalizeRow(rows?.[0] || null);
+}
+
+export async function completeDomainEvent(eventId, connection = null) {
+  if (!eventId) return false;
+  await executeQuery(
+    `UPDATE ${TABLES.DOMAIN_EVENT_OUTBOX}
+     SET status = 'completed',
+         processed_at = UTC_TIMESTAMP(),
+         worker_token = NULL,
+         locked_at = NULL,
+         last_error = NULL,
+         updated_at = CURRENT_TIMESTAMP
+     WHERE id = ?`,
+    [eventId],
+    connection,
+  );
+  return true;
+}
+
+export async function failDomainEvent(
+  eventId,
+  {
+    error = null,
+    retryDelaySeconds = 0,
+  } = {},
+  connection = null,
+) {
+  if (!eventId) return false;
+
+  const safeDelay = clampInt(retryDelaySeconds, 0, 0, 86400 * 7);
+  const message = String(error || '').trim().slice(0, 255) || null;
+
+  await executeQuery(
+    `UPDATE ${TABLES.DOMAIN_EVENT_OUTBOX}
+     SET status = IF(attempts >= max_attempts, 'failed', 'pending'),
+         worker_token = NULL,
+         locked_at = NULL,
+         last_error = ?,
+         available_at = IF(attempts >= max_attempts, available_at, UTC_TIMESTAMP() + INTERVAL ${safeDelay} SECOND),
+         updated_at = CURRENT_TIMESTAMP,
+         processed_at = IF(attempts >= max_attempts, UTC_TIMESTAMP(), processed_at)
+     WHERE id = ?`,
+    [message, eventId],
+    connection,
+  );
+
+  await executeQuery(
+    `INSERT INTO ${TABLES.DOMAIN_EVENT_OUTBOX_DLQ}
+      (outbox_event_id, event_type, aggregate_type, aggregate_id, payload, attempts, max_attempts, last_error)
+     SELECT id, event_type, aggregate_type, aggregate_id, payload, attempts, max_attempts, last_error
+       FROM ${TABLES.DOMAIN_EVENT_OUTBOX}
+      WHERE id = ?
+        AND status = 'failed'
+     ON DUPLICATE KEY UPDATE
+      last_error = VALUES(last_error),
+      attempts = VALUES(attempts),
+      max_attempts = VALUES(max_attempts),
+      failed_at = CURRENT_TIMESTAMP`,
+    [eventId],
+    connection,
+  ).catch(() => null);
+  return true;
+}
+
+export async function countDomainEventsByStatus(status = 'pending', connection = null) {
+  const normalized = normalizeStatus(status);
+  if (!normalized) return 0;
+  const rows = await executeQuery(
+    `SELECT COUNT(*) AS total
+     FROM ${TABLES.DOMAIN_EVENT_OUTBOX}
+     WHERE status = ?`,
+    [normalized],
+    connection,
+  );
+  return Number(rows?.[0]?.total || 0);
+}

package/app/modules/stickerPackModule/domainEvents.js

@@ -0,0 +1,61 @@
+export const STICKER_DOMAIN_EVENTS = Object.freeze({
+  STICKER_ASSET_CREATED: 'STICKER_ASSET_CREATED',
+  STICKER_CLASSIFIED: 'STICKER_CLASSIFIED',
+  PACK_UPDATED: 'PACK_UPDATED',
+  ENGAGEMENT_RECORDED: 'ENGAGEMENT_RECORDED',
+});
+
+export const STICKER_DOMAIN_EVENT_TYPES = new Set(Object.values(STICKER_DOMAIN_EVENTS));
+
+const normalizeType = (value) =>
+  String(value || '')
+    .trim()
+    .toUpperCase()
+    .replace(/[^A-Z0-9_]/g, '')
+    .slice(0, 96);
+
+const normalizeAggregateType = (value) =>
+  String(value || '')
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9_:-]/g, '')
+    .slice(0, 96);
+
+const normalizeAggregateId = (value) =>
+  String(value || '')
+    .trim()
+    .slice(0, 128);
+
+const normalizeIdempotencyKey = (value) =>
+  String(value || '')
+    .trim()
+    .replace(/[^a-zA-Z0-9_:-]/g, '')
+    .slice(0, 180);
+
+export const normalizeDomainEventPayload = ({
+  eventType,
+  aggregateType,
+  aggregateId,
+  payload = null,
+  priority = 50,
+  availableAt = null,
+  idempotencyKey = '',
+  maxAttempts = 10,
+} = {}) => {
+  const normalizedType = normalizeType(eventType);
+  if (!normalizedType) return null;
+  const normalizedAggregateType = normalizeAggregateType(aggregateType);
+  const normalizedAggregateId = normalizeAggregateId(aggregateId);
+  if (!normalizedAggregateType || !normalizedAggregateId) return null;
+
+  return {
+    event_type: normalizedType,
+    aggregate_type: normalizedAggregateType,
+    aggregate_id: normalizedAggregateId,
+    payload: payload && typeof payload === 'object' ? payload : payload ?? null,
+    priority: Math.max(1, Math.min(100, Number(priority) || 50)),
+    available_at: availableAt ? new Date(availableAt) : null,
+    idempotency_key: normalizeIdempotencyKey(idempotencyKey) || null,
+    max_attempts: Math.max(1, Math.min(30, Number(maxAttempts) || 10)),
+  };
+};

package/app/modules/stickerPackModule/stickerAssetClassificationRepository.js

@@ -1,4 +1,6 @@
 import { executeQuery, TABLES } from '../../../database/index.js';
+import { STICKER_DOMAIN_EVENTS } from './domainEvents.js';
+import { publishStickerDomainEvent } from './stickerDomainEventBus.js';
 
 const parseJson = (value, fallback = null) => {
   if (value === null || value === undefined) return fallback;
@@ -163,6 +165,25 @@ export async function upsertStickerAssetClassification(payload, connection = nul
     connection,
   );
 
+  await publishStickerDomainEvent(
+    {
+      eventType: STICKER_DOMAIN_EVENTS.STICKER_CLASSIFIED,
+      aggregateType: 'sticker_asset',
+      aggregateId: payload.asset_id,
+      payload: {
+        asset_id: payload.asset_id,
+        category: payload.category || null,
+        confidence: payload.confidence ?? null,
+        nsfw_score: payload.nsfw_score ?? null,
+        is_nsfw: Boolean(payload.is_nsfw),
+        classification_version: payload.classification_version || 'v1',
+      },
+      priority: 80,
+      idempotencyKey: `sticker_classified:${payload.asset_id}:${payload.classification_version || 'v1'}`,
+    },
+    { connection },
+  );
+
   return findStickerClassificationByAssetId(payload.asset_id, connection);
 }
 

package/app/modules/stickerPackModule/stickerAssetRepository.js

@@ -1,4 +1,6 @@
 import { executeQuery, TABLES } from '../../../database/index.js';
+import { STICKER_DOMAIN_EVENTS } from './domainEvents.js';
+import { publishStickerDomainEvent } from './stickerDomainEventBus.js';
 
 /**
  * Converte valores numéricos/booleanos vindos do banco para booleano.
@@ -358,6 +360,23 @@ export async function createStickerAsset(asset, connection = null) {
     connection,
   );
 
+  await publishStickerDomainEvent(
+    {
+      eventType: STICKER_DOMAIN_EVENTS.STICKER_ASSET_CREATED,
+      aggregateType: 'sticker_asset',
+      aggregateId: asset.id,
+      payload: {
+        asset_id: asset.id,
+        owner_jid: asset.owner_jid,
+        sha256: asset.sha256,
+        mimetype: asset.mimetype,
+      },
+      priority: 85,
+      idempotencyKey: `sticker_asset_created:${asset.id}`,
+    },
+    { connection },
+  );
+
   return findStickerAssetById(asset.id, connection);
 }
 

package/app/modules/stickerPackModule/stickerClassificationBackgroundRuntime.js

@@ -2,7 +2,7 @@ import fs from 'node:fs/promises';
 import os from 'node:os';
 
 import logger from '../../utils/logger/loggerModule.js';
-import { setQueueDepth } from '../../observability/metrics.js';
+import { recordStickerClassificationCycle, setQueueDepth } from '../../observability/metrics.js';
 import { listStickerAssetsPendingClassification, findStickerAssetById } from './stickerAssetRepository.js';
 import { classifierConfig, ensureStickerAssetClassified } from './stickerClassificationService.js';
 import {
@@ -351,30 +351,70 @@ export const runStickerClassificationCycle = async ({
   processReprocess = true,
   processDeterministic = true,
 } = {}) => {
+  const startedAt = Date.now();
   const shouldProcessClassifier = classifierConfig.enabled;
   const shouldProcessDeterministic = deterministicReclassificationConfig.enabled;
 
   if (!BACKGROUND_ENABLED || (!shouldProcessClassifier && !shouldProcessDeterministic)) {
+    recordStickerClassificationCycle({
+      status: 'skipped',
+      durationMs: Date.now() - startedAt,
+      processed: 0,
+      classified: 0,
+      failed: 0,
+    });
     return {
       skipped: true,
       reason: !BACKGROUND_ENABLED ? 'background_disabled' : 'no_active_processors',
     };
   }
 
-  const startedAt = Date.now();
-  const reprocessStats = processReprocess && shouldProcessClassifier ? await processReprocessQueue() : null;
-  const pendingStats = processPending && shouldProcessClassifier ? await processPendingAssets() : null;
-  const deterministicStats = processDeterministic
-    ? await processDeterministicReclassification()
-    : null;
-
-  return {
-    skipped: false,
-    duration_ms: Date.now() - startedAt,
-    pending: pendingStats,
-    reprocess: reprocessStats,
-    deterministic_reclassification: deterministicStats,
-  };
+  try {
+    const reprocessStats = processReprocess && shouldProcessClassifier ? await processReprocessQueue() : null;
+    const pendingStats = processPending && shouldProcessClassifier ? await processPendingAssets() : null;
+    const deterministicStats = processDeterministic
+      ? await processDeterministicReclassification()
+      : null;
+
+    const processed =
+      Number(pendingStats?.processed || 0)
+      + Number(reprocessStats?.processed || 0)
+      + Number(deterministicStats?.processed || 0);
+    const classified =
+      Number(pendingStats?.classified || 0)
+      + Number(reprocessStats?.classified || 0)
+      + Number(deterministicStats?.updated || 0);
+    const failed =
+      Number(pendingStats?.failed || 0)
+      + Number(reprocessStats?.failed || 0)
+      + Number(deterministicStats?.failed || 0);
+    const durationMs = Date.now() - startedAt;
+
+    recordStickerClassificationCycle({
+      status: 'ok',
+      durationMs,
+      processed,
+      classified,
+      failed,
+    });
+
+    return {
+      skipped: false,
+      duration_ms: durationMs,
+      pending: pendingStats,
+      reprocess: reprocessStats,
+      deterministic_reclassification: deterministicStats,
+    };
+  } catch (error) {
+    recordStickerClassificationCycle({
+      status: 'failed',
+      durationMs: Date.now() - startedAt,
+      processed: 0,
+      classified: 0,
+      failed: 1,
+    });
+    throw error;
+  }
 };
 
 const clearCycleHandle = () => {

package/app/modules/stickerPackModule/stickerDedicatedTaskWorkerRuntime.js

@@ -0,0 +1,238 @@
+import logger from '../../utils/logger/loggerModule.js';
+import { setQueueDepth } from '../../observability/metrics.js';
+import { isFeatureEnabled } from '../../services/featureFlagService.js';
+import { runStickerClassificationCycle } from './stickerClassificationBackgroundRuntime.js';
+import { runStickerAutoPackByTagsCycle } from './stickerAutoPackByTagsRuntime.js';
+import {
+  claimWorkerTask,
+  completeWorkerTask,
+  countWorkerTasksByStatus,
+  failWorkerTask,
+} from './stickerWorkerTaskQueueRepository.js';
+
+const parseEnvBool = (value, fallback) => {
+  if (value === undefined || value === null || value === '') return fallback;
+  const normalized = String(value).trim().toLowerCase();
+  if (['1', 'true', 'yes', 'y', 'on'].includes(normalized)) return true;
+  if (['0', 'false', 'no', 'n', 'off'].includes(normalized)) return false;
+  return fallback;
+};
+
+const clampInt = (value, fallback, min, max) => {
+  const numeric = Number(value);
+  if (!Number.isFinite(numeric)) return fallback;
+  return Math.max(min, Math.min(max, Math.floor(numeric)));
+};
+
+const DEDICATED_WORKERS_ENABLED = parseEnvBool(process.env.STICKER_DEDICATED_WORKERS_ENABLED, true);
+const DEDICATED_WORKERS_FORCE_ENABLED = parseEnvBool(process.env.STICKER_DEDICATED_WORKERS_FORCE_ENABLED, false);
+const DEDICATED_WORKER_RETRY_DELAY_SECONDS = clampInt(
+  process.env.STICKER_DEDICATED_WORKER_RETRY_DELAY_SECONDS,
+  60,
+  5,
+  3600,
+);
+const DEDICATED_WORKER_POLL_INTERVAL_MS = clampInt(
+  process.env.STICKER_DEDICATED_WORKER_POLL_INTERVAL_MS,
+  2500,
+  250,
+  60_000,
+);
+const DEDICATED_WORKER_MAX_TASKS_PER_TICK = clampInt(
+  process.env.STICKER_DEDICATED_WORKER_MAX_TASKS_PER_TICK,
+  1,
+  1,
+  25,
+);
+const DEDICATED_WORKER_COHORT_KEY =
+  String(process.env.STICKER_DEDICATED_WORKER_COHORT_KEY || process.env.HOSTNAME || process.pid).trim()
+  || 'worker';
+
+const SUPPORTED_TASK_TYPES = new Set([
+  'classification_cycle',
+  'curation_cycle',
+  'rebuild_cycle',
+]);
+
+const normalizeTaskType = (value) => {
+  const normalized = String(value || '').trim().toLowerCase();
+  return SUPPORTED_TASK_TYPES.has(normalized) ? normalized : null;
+};
+
+const runTaskHandler = async (taskType, payload = {}) => {
+  if (taskType === 'classification_cycle') {
+    return runStickerClassificationCycle({
+      processPending: true,
+      processReprocess: true,
+      processDeterministic: true,
+      ...payload,
+    });
+  }
+  if (taskType === 'curation_cycle') {
+    return runStickerAutoPackByTagsCycle({
+      enableAdditions: true,
+      enableRebuild: false,
+      ...payload,
+    });
+  }
+  if (taskType === 'rebuild_cycle') {
+    return runStickerAutoPackByTagsCycle({
+      enableAdditions: false,
+      enableRebuild: true,
+      ...payload,
+    });
+  }
+  throw new Error(`unsupported_task_type:${taskType}`);
+};
+
+const refreshQueueDepthMetrics = async () => {
+  const [pending, processing, failed] = await Promise.all([
+    countWorkerTasksByStatus('pending'),
+    countWorkerTasksByStatus('processing'),
+    countWorkerTasksByStatus('failed'),
+  ]);
+  setQueueDepth('sticker_worker_tasks_pending', pending);
+  setQueueDepth('sticker_worker_tasks_processing', processing);
+  setQueueDepth('sticker_worker_tasks_failed', failed);
+};
+
+const canRunDedicatedWorkers = async (taskType) => {
+  if (!DEDICATED_WORKERS_ENABLED) return false;
+  if (DEDICATED_WORKERS_FORCE_ENABLED) return true;
+  return isFeatureEnabled('enable_worker_dedicated_processes', {
+    fallback: false,
+    subjectKey: `worker:${taskType}:${DEDICATED_WORKER_COHORT_KEY}`,
+  });
+};
+
+export const isSupportedStickerWorkerTaskType = (taskType) => Boolean(normalizeTaskType(taskType));
+
+export const runDedicatedStickerWorkerTick = async (
+  {
+    taskType,
+    maxTasks = DEDICATED_WORKER_MAX_TASKS_PER_TICK,
+    retryDelaySeconds = DEDICATED_WORKER_RETRY_DELAY_SECONDS,
+  } = {},
+) => {
+  const normalizedTaskType = normalizeTaskType(taskType);
+  if (!normalizedTaskType) {
+    return { executed: false, reason: 'invalid_task_type', task_type: taskType || null };
+  }
+
+  const enabled = await canRunDedicatedWorkers(normalizedTaskType);
+  if (!enabled) {
+    return { executed: false, reason: 'feature_disabled', task_type: normalizedTaskType };
+  }
+
+  const safeMaxTasks = clampInt(maxTasks, DEDICATED_WORKER_MAX_TASKS_PER_TICK, 1, 25);
+  const stats = {
+    executed: true,
+    task_type: normalizedTaskType,
+    claimed: 0,
+    completed: 0,
+    failed: 0,
+  };
+
+  for (let i = 0; i < safeMaxTasks; i += 1) {
+    const task = await claimWorkerTask({ taskType: normalizedTaskType });
+    if (!task) break;
+
+    stats.claimed += 1;
+
+    try {
+      await runTaskHandler(normalizedTaskType, task.payload || {});
+      await completeWorkerTask(task.id);
+      stats.completed += 1;
+    } catch (error) {
+      stats.failed += 1;
+      await failWorkerTask(task.id, {
+        error: error?.message || 'dedicated_worker_task_failed',
+        retryDelaySeconds,
+      });
+
+      logger.warn('Task falhou no worker dedicado.', {
+        action: 'sticker_dedicated_worker_task_failed',
+        task_type: normalizedTaskType,
+        task_id: task.id,
+        attempts: task.attempts,
+        error: error?.message,
+      });
+    }
+  }
+
+  if (stats.claimed > 0) {
+    await refreshQueueDepthMetrics().catch(() => null);
+  }
+
+  return stats;
+};
+
+export const startDedicatedStickerWorker = ({
+  taskType,
+  pollIntervalMs = DEDICATED_WORKER_POLL_INTERVAL_MS,
+  maxTasksPerTick = DEDICATED_WORKER_MAX_TASKS_PER_TICK,
+  retryDelaySeconds = DEDICATED_WORKER_RETRY_DELAY_SECONDS,
+  label = '',
+} = {}) => {
+  const normalizedTaskType = normalizeTaskType(taskType);
+  if (!normalizedTaskType) {
+    throw new Error(`invalid_task_type:${taskType}`);
+  }
+
+  const safePollIntervalMs = clampInt(pollIntervalMs, DEDICATED_WORKER_POLL_INTERVAL_MS, 250, 60_000);
+  let tickInFlight = false;
+  let stopped = false;
+
+  const runTick = async () => {
+    if (stopped || tickInFlight) return;
+    tickInFlight = true;
+    try {
+      await runDedicatedStickerWorkerTick({
+        taskType: normalizedTaskType,
+        maxTasks: maxTasksPerTick,
+        retryDelaySeconds,
+      });
+    } catch (error) {
+      if (error?.code !== 'ER_NO_SUCH_TABLE') {
+        logger.error('Falha no worker dedicado de sticker.', {
+          action: 'sticker_dedicated_worker_tick_failed',
+          task_type: normalizedTaskType,
+          error: error?.message,
+        });
+      }
+    } finally {
+      tickInFlight = false;
+    }
+  };
+
+  const intervalHandle = setInterval(() => {
+    void runTick();
+  }, safePollIntervalMs);
+  if (typeof intervalHandle?.unref === 'function') {
+    intervalHandle.unref();
+  }
+
+  void runTick();
+
+  logger.info('Worker dedicado de sticker iniciado.', {
+    action: 'sticker_dedicated_worker_started',
+    task_type: normalizedTaskType,
+    poll_interval_ms: safePollIntervalMs,
+    max_tasks_per_tick: maxTasksPerTick,
+    label: label || null,
+  });
+
+  return {
+    taskType: normalizedTaskType,
+    stop: () => {
+      if (stopped) return;
+      stopped = true;
+      clearInterval(intervalHandle);
+      logger.info('Worker dedicado de sticker encerrado.', {
+        action: 'sticker_dedicated_worker_stopped',
+        task_type: normalizedTaskType,
+        label: label || null,
+      });
+    },
+  };
+};