@kaikybrofc/omnizap-system 2.2.4 → 2.2.6

package/app/modules/stickerPackModule/stickerPackEngagementRepository.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 normalizeEngagementRow = (row) => ({
   pack_id: row?.pack_id || null,
@@ -70,6 +72,20 @@ export async function incrementStickerPackOpen(packId, connection = null) {
     connection,
   );
 
+  await publishStickerDomainEvent(
+    {
+      eventType: STICKER_DOMAIN_EVENTS.ENGAGEMENT_RECORDED,
+      aggregateType: 'sticker_pack',
+      aggregateId: packId,
+      payload: {
+        action: 'open',
+        pack_id: packId,
+      },
+      priority: 55,
+    },
+    { connection },
+  );
+
   return getStickerPackEngagementByPackId(packId, connection);
 }
 
@@ -87,6 +103,20 @@ export async function incrementStickerPackLike(packId, connection = null) {
     connection,
   );
 
+  await publishStickerDomainEvent(
+    {
+      eventType: STICKER_DOMAIN_EVENTS.ENGAGEMENT_RECORDED,
+      aggregateType: 'sticker_pack',
+      aggregateId: packId,
+      payload: {
+        action: 'like',
+        pack_id: packId,
+      },
+      priority: 55,
+    },
+    { connection },
+  );
+
   return getStickerPackEngagementByPackId(packId, connection);
 }
 
@@ -104,5 +134,19 @@ export async function incrementStickerPackDislike(packId, connection = null) {
     connection,
   );
 
+  await publishStickerDomainEvent(
+    {
+      eventType: STICKER_DOMAIN_EVENTS.ENGAGEMENT_RECORDED,
+      aggregateType: 'sticker_pack',
+      aggregateId: packId,
+      payload: {
+        action: 'dislike',
+        pack_id: packId,
+      },
+      priority: 55,
+    },
+    { connection },
+  );
+
   return getStickerPackEngagementByPackId(packId, connection);
 }

package/app/modules/stickerPackModule/stickerPackItemRepository.js

@@ -207,6 +207,24 @@ export async function countStickerPackItemRefsByStickerId(stickerId, connection
   return Number(rows?.[0]?.total || 0);
 }
 
+/**
+ * Lista IDs de packs que referenciam um sticker.
+ *
+ * @param {string} stickerId ID do sticker/asset.
+ * @param {import('mysql2/promise').PoolConnection|null} [connection=null]
+ * @returns {Promise<string[]>}
+ */
+export async function listPackIdsByStickerId(stickerId, connection = null) {
+  const rows = await executeQuery(
+    `SELECT DISTINCT pack_id
+     FROM ${TABLES.STICKER_PACK_ITEM}
+     WHERE sticker_id = ?`,
+    [stickerId],
+    connection,
+  );
+  return (Array.isArray(rows) ? rows : []).map((row) => String(row?.pack_id || '')).filter(Boolean);
+}
+
 /**
  * Obtém a maior posição atualmente usada no pack.
  *

package/app/modules/stickerPackModule/stickerPackRepository.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 CATALOG_COMPLETE_PACK_TARGET = Math.max(1, Number(process.env.STICKER_PACK_MAX_ITEMS) || 30);
 
@@ -337,6 +339,24 @@ export async function createStickerPack(pack, connection = null) {
     connection,
   );
 
+  await publishStickerDomainEvent(
+    {
+      eventType: STICKER_DOMAIN_EVENTS.PACK_UPDATED,
+      aggregateType: 'sticker_pack',
+      aggregateId: pack.id,
+      payload: {
+        action: 'created',
+        pack_id: pack.id,
+        pack_key: pack.pack_key,
+        owner_jid: pack.owner_jid,
+        visibility: pack.visibility,
+      },
+      priority: 75,
+      idempotencyKey: `pack_created:${pack.id}`,
+    },
+    { connection },
+  );
+
   return findStickerPackById(pack.id, { includeDeleted: true, connection });
 }
 
@@ -389,6 +409,22 @@ export async function updateStickerPackFields(packId, fields, connection = null)
     connection,
   );
 
+  await publishStickerDomainEvent(
+    {
+      eventType: STICKER_DOMAIN_EVENTS.PACK_UPDATED,
+      aggregateType: 'sticker_pack',
+      aggregateId: packId,
+      payload: {
+        action: 'updated',
+        pack_id: packId,
+        fields: Object.keys(fields || {}).slice(0, 30),
+      },
+      priority: 70,
+      idempotencyKey: `pack_updated:${packId}:${Object.keys(fields || {}).sort().join(',')}`,
+    },
+    { connection },
+  );
+
   return findStickerPackById(packId, { includeDeleted: true, connection });
 }
 
@@ -438,5 +474,20 @@ export async function bumpStickerPackVersion(packId, connection = null) {
     connection,
   );
 
+  await publishStickerDomainEvent(
+    {
+      eventType: STICKER_DOMAIN_EVENTS.PACK_UPDATED,
+      aggregateType: 'sticker_pack',
+      aggregateId: packId,
+      payload: {
+        action: 'version_bumped',
+        pack_id: packId,
+      },
+      priority: 65,
+      idempotencyKey: `pack_version_bumped:${packId}`,
+    },
+    { connection },
+  );
+
   return findStickerPackById(packId, { includeDeleted: true, connection });
 }

package/app/modules/stickerPackModule/stickerPackScoreSnapshotRepository.js

@@ -0,0 +1,191 @@
+import { executeQuery, TABLES } from '../../../database/index.js';
+
+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 clampScore = (value) => {
+  const numeric = Number(value);
+  if (!Number.isFinite(numeric)) return 0;
+  return Number(numeric.toFixed(6));
+};
+
+const normalizeNsfwLevel = (value) => {
+  const normalized = String(value || '').trim().toLowerCase();
+  if (['safe', 'suggestive', 'explicit'].includes(normalized)) return normalized;
+  return 'safe';
+};
+
+const normalizeRow = (row) => {
+  if (!row) return null;
+  const scoresFromJson = parseJson(row.scores_json, {}) || {};
+  return {
+    pack_id: row.pack_id,
+    ranking_score: clampScore(row.ranking_score),
+    pack_score: clampScore(row.pack_score),
+    trend_score: clampScore(row.trend_score),
+    quality_score: clampScore(row.quality_score),
+    engagement_score: clampScore(row.engagement_score),
+    diversity_score: clampScore(row.diversity_score),
+    cohesion_score: clampScore(row.cohesion_score),
+    sensitive_content: row.sensitive_content === 1 || row.sensitive_content === true,
+    nsfw_level: normalizeNsfwLevel(row.nsfw_level),
+    sticker_count: Number(row.sticker_count || 0),
+    tags: Array.isArray(parseJson(row.tags, [])) ? parseJson(row.tags, []) : [],
+    source_version: row.source_version || 'v1',
+    refreshed_at: row.refreshed_at || null,
+    updated_at: row.updated_at || null,
+    signals: {
+      ...scoresFromJson,
+      quality_score: clampScore(row.quality_score),
+      engagement_score: clampScore(row.engagement_score),
+      diversity_score: clampScore(row.diversity_score),
+      cohesion_score: clampScore(row.cohesion_score),
+      trend_score: clampScore(row.trend_score),
+      pack_score: clampScore(row.pack_score),
+      ranking_score: clampScore(row.ranking_score),
+      nsfw_level: normalizeNsfwLevel(row.nsfw_level),
+      sensitive_content: row.sensitive_content === 1 || row.sensitive_content === true,
+    },
+  };
+};
+
+const normalizeSnapshotInput = (entry) => {
+  if (!entry?.pack_id) return null;
+  const signals = entry?.signals && typeof entry.signals === 'object' ? entry.signals : {};
+  return {
+    pack_id: String(entry.pack_id),
+    ranking_score: clampScore(signals.ranking_score),
+    pack_score: clampScore(signals.pack_score),
+    trend_score: clampScore(signals.trend_score),
+    quality_score: clampScore(signals.quality_score),
+    engagement_score: clampScore(signals.engagement_score),
+    diversity_score: clampScore(signals.diversity_score),
+    cohesion_score: clampScore(signals.cohesion_score),
+    sensitive_content: signals.sensitive_content === true || signals.sensitive_content === 1 ? 1 : 0,
+    nsfw_level: normalizeNsfwLevel(signals.nsfw_level),
+    sticker_count: Math.max(0, Number(entry.sticker_count || 0)),
+    tags: Array.isArray(entry.tags) ? entry.tags.slice(0, 30) : [],
+    source_version: String(entry.source_version || 'v1').trim().slice(0, 32) || 'v1',
+    scores_json: signals,
+  };
+};
+
+export async function upsertStickerPackScoreSnapshots(entries = [], connection = null) {
+  const normalized = (Array.isArray(entries) ? entries : [])
+    .map((entry) => normalizeSnapshotInput(entry))
+    .filter(Boolean);
+  if (!normalized.length) return 0;
+
+  let written = 0;
+  for (let offset = 0; offset < normalized.length; offset += 100) {
+    const chunk = normalized.slice(offset, offset + 100);
+    const placeholders = chunk.map(() => '(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, UTC_TIMESTAMP())').join(', ');
+    const params = chunk.flatMap((entry) => [
+      entry.pack_id,
+      entry.ranking_score,
+      entry.pack_score,
+      entry.trend_score,
+      entry.quality_score,
+      entry.engagement_score,
+      entry.diversity_score,
+      entry.cohesion_score,
+      entry.sensitive_content,
+      entry.nsfw_level,
+      entry.sticker_count,
+      JSON.stringify(entry.tags || []),
+      JSON.stringify(entry.scores_json || {}),
+      entry.source_version,
+    ]);
+    const result = await executeQuery(
+      `INSERT INTO ${TABLES.STICKER_PACK_SCORE_SNAPSHOT}
+        (
+          pack_id,
+          ranking_score,
+          pack_score,
+          trend_score,
+          quality_score,
+          engagement_score,
+          diversity_score,
+          cohesion_score,
+          sensitive_content,
+          nsfw_level,
+          sticker_count,
+          tags,
+          scores_json,
+          source_version,
+          refreshed_at
+        )
+       VALUES ${placeholders}
+       ON DUPLICATE KEY UPDATE
+        ranking_score = VALUES(ranking_score),
+        pack_score = VALUES(pack_score),
+        trend_score = VALUES(trend_score),
+        quality_score = VALUES(quality_score),
+        engagement_score = VALUES(engagement_score),
+        diversity_score = VALUES(diversity_score),
+        cohesion_score = VALUES(cohesion_score),
+        sensitive_content = VALUES(sensitive_content),
+        nsfw_level = VALUES(nsfw_level),
+        sticker_count = VALUES(sticker_count),
+        tags = VALUES(tags),
+        scores_json = VALUES(scores_json),
+        source_version = VALUES(source_version),
+        refreshed_at = UTC_TIMESTAMP(),
+        updated_at = CURRENT_TIMESTAMP`,
+      params,
+      connection,
+    );
+    written += Number(result?.affectedRows || 0);
+  }
+
+  return written;
+}
+
+export async function listStickerPackScoreSnapshotsByPackIds(packIds = [], connection = null) {
+  const ids = Array.from(new Set((Array.isArray(packIds) ? packIds : []).filter(Boolean)));
+  if (!ids.length) return new Map();
+  const placeholders = ids.map(() => '?').join(', ');
+  const rows = await executeQuery(
+    `SELECT *
+     FROM ${TABLES.STICKER_PACK_SCORE_SNAPSHOT}
+     WHERE pack_id IN (${placeholders})`,
+    ids,
+    connection,
+  );
+  const byPackId = new Map();
+  (Array.isArray(rows) ? rows : []).forEach((row) => {
+    const normalized = normalizeRow(row);
+    if (!normalized?.pack_id) return;
+    byPackId.set(normalized.pack_id, normalized);
+  });
+  return byPackId;
+}
+
+export async function removeSnapshotsForDeletedPacks(connection = null) {
+  const result = await executeQuery(
+    `DELETE s
+       FROM ${TABLES.STICKER_PACK_SCORE_SNAPSHOT} s
+       LEFT JOIN ${TABLES.STICKER_PACK} p ON p.id = s.pack_id
+      WHERE p.id IS NULL OR p.deleted_at IS NOT NULL`,
+    [],
+    connection,
+  );
+  return Number(result?.affectedRows || 0);
+}

package/app/modules/stickerPackModule/stickerPackScoreSnapshotRuntime.js

@@ -0,0 +1,301 @@
+import { executeQuery, TABLES } from '../../../database/index.js';
+import logger from '../../utils/logger/loggerModule.js';
+import {
+  getEmptyStickerPackEngagement,
+  getStickerPackEngagementByPackId,
+} from './stickerPackEngagementRepository.js';
+import { listStickerPackItems } from './stickerPackItemRepository.js';
+import { listStickerClassificationsByAssetIds } from './stickerAssetClassificationRepository.js';
+import { getPackClassificationSummaryByAssetIds } from './stickerClassificationService.js';
+import { listStickerPackInteractionStatsByPackIds } from './stickerPackInteractionEventRepository.js';
+import { getMarketplaceDriftSnapshot } from './stickerMarketplaceDriftService.js';
+import { computePackSignals } from './stickerPackMarketplaceService.js';
+import {
+  removeSnapshotsForDeletedPacks,
+  upsertStickerPackScoreSnapshots,
+} from './stickerPackScoreSnapshotRepository.js';
+import { setQueueDepth } from '../../observability/metrics.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 SNAPSHOT_ENABLED = parseEnvBool(process.env.STICKER_SCORE_SNAPSHOT_ENABLED, true);
+const SNAPSHOT_STARTUP_DELAY_MS = Math.max(
+  1_000,
+  Number(process.env.STICKER_SCORE_SNAPSHOT_STARTUP_DELAY_MS) || 20_000,
+);
+const SNAPSHOT_REFRESH_INTERVAL_MS = Math.max(
+  30_000,
+  Number(process.env.STICKER_SCORE_SNAPSHOT_REFRESH_INTERVAL_MS) || 5 * 60_000,
+);
+const SNAPSHOT_BATCH_SIZE = Math.max(
+  10,
+  Math.min(500, Number(process.env.STICKER_SCORE_SNAPSHOT_BATCH_SIZE) || 120),
+);
+const SNAPSHOT_TARGETED_BATCH_SIZE = Math.max(
+  5,
+  Math.min(200, Number(process.env.STICKER_SCORE_SNAPSHOT_TARGETED_BATCH_SIZE) || 60),
+);
+const SNAPSHOT_SOURCE_VERSION = String(process.env.STICKER_SCORE_SNAPSHOT_SOURCE_VERSION || 'v1').trim() || 'v1';
+const SNAPSHOT_MAX_PENDING_PACKS = Math.max(
+  20,
+  Math.min(20_000, Number(process.env.STICKER_SCORE_SNAPSHOT_MAX_PENDING_PACKS) || 2_000),
+);
+const SNAPSHOT_FULL_REBUILD_EVERY_CYCLES = Math.max(
+  1,
+  Math.min(500, Number(process.env.STICKER_SCORE_SNAPSHOT_FULL_REBUILD_EVERY_CYCLES) || 12),
+);
+
+let startupHandle = null;
+let cycleHandle = null;
+let running = false;
+let cycleCounter = 0;
+const pendingPackIds = new Set();
+
+const listPublishedCatalogPacks = async ({ limit = SNAPSHOT_BATCH_SIZE, offset = 0 } = {}) => {
+  const safeLimit = Math.max(1, Math.min(500, Number(limit) || SNAPSHOT_BATCH_SIZE));
+  const safeOffset = Math.max(0, Number(offset) || 0);
+  const rows = await executeQuery(
+    `SELECT id, owner_jid, name, publisher, description, pack_key, cover_sticker_id, visibility, status, pack_status, is_auto_pack, updated_at, created_at
+       FROM ${TABLES.STICKER_PACK}
+      WHERE deleted_at IS NULL
+        AND status = 'published'
+        AND COALESCE(pack_status, 'ready') = 'ready'
+        AND visibility IN ('public', 'unlisted')
+      ORDER BY updated_at DESC, id DESC
+      LIMIT ${safeLimit} OFFSET ${safeOffset}`,
+    [],
+  );
+  return Array.isArray(rows) ? rows : [];
+};
+
+const listPacksByIdsForSnapshot = async (packIds = []) => {
+  const ids = Array.from(new Set((Array.isArray(packIds) ? packIds : []).filter(Boolean)));
+  if (!ids.length) return [];
+  const placeholders = ids.map(() => '?').join(', ');
+  const rows = await executeQuery(
+    `SELECT id, owner_jid, name, publisher, description, pack_key, cover_sticker_id, visibility, status, pack_status, is_auto_pack, updated_at, created_at
+       FROM ${TABLES.STICKER_PACK}
+      WHERE id IN (${placeholders})
+        AND deleted_at IS NULL
+        AND status = 'published'
+        AND COALESCE(pack_status, 'ready') = 'ready'
+        AND visibility IN ('public', 'unlisted')`,
+    ids,
+  );
+  return Array.isArray(rows) ? rows : [];
+};
+
+const buildSnapshotForPack = async ({ pack, driftWeights }) => {
+  const items = await listStickerPackItems(pack.id);
+  const stickerIds = items.map((item) => item.sticker_id).filter(Boolean);
+  const [packClassification, itemClassifications, engagement, interactionStatsByPackId] = await Promise.all([
+    getPackClassificationSummaryByAssetIds(stickerIds),
+    stickerIds.length ? listStickerClassificationsByAssetIds(stickerIds) : Promise.resolve([]),
+    getStickerPackEngagementByPackId(pack.id),
+    listStickerPackInteractionStatsByPackIds([pack.id]),
+  ]);
+
+  const byAssetId = new Map((Array.isArray(itemClassifications) ? itemClassifications : []).map((entry) => [entry.asset_id, entry]));
+  const orderedClassifications = stickerIds.map((id) => byAssetId.get(id)).filter(Boolean);
+  const signals = computePackSignals({
+    pack: { ...pack, items },
+    engagement: engagement || getEmptyStickerPackEngagement(),
+    packClassification,
+    itemClassifications: orderedClassifications,
+    interactionStats: interactionStatsByPackId.get(pack.id) || null,
+    scoringWeights: driftWeights || null,
+  });
+
+  return {
+    pack_id: pack.id,
+    signals,
+    tags: Array.isArray(packClassification?.tags) ? packClassification.tags : [],
+    sticker_count: items.length,
+    source_version: SNAPSHOT_SOURCE_VERSION,
+  };
+};
+
+const rebuildSnapshotsForPacks = async (packs = []) => {
+  if (!packs.length) return { scanned: 0, written: 0 };
+  const driftSnapshot = await getMarketplaceDriftSnapshot();
+  const driftWeights = driftSnapshot?.weights || null;
+  const snapshots = [];
+  let scanned = 0;
+
+  for (const pack of packs) {
+    scanned += 1;
+    try {
+      const snapshot = await buildSnapshotForPack({ pack, driftWeights });
+      snapshots.push(snapshot);
+    } catch (error) {
+      logger.warn('Falha ao montar snapshot de score do pack.', {
+        action: 'sticker_pack_score_snapshot_build_failed',
+        pack_id: pack?.id || null,
+        error: error?.message,
+      });
+    }
+  }
+
+  const written = await upsertStickerPackScoreSnapshots(snapshots);
+  return { scanned, written };
+};
+
+const consumePendingPackIds = (limit = SNAPSHOT_TARGETED_BATCH_SIZE) => {
+  const consumed = [];
+  for (const packId of pendingPackIds) {
+    consumed.push(packId);
+    pendingPackIds.delete(packId);
+    if (consumed.length >= limit) break;
+  }
+  return consumed;
+};
+
+export const enqueuePackScoreSnapshotRefresh = (packIds = []) => {
+  const ids = Array.isArray(packIds) ? packIds : [packIds];
+  ids.forEach((packId) => {
+    const normalized = String(packId || '').trim();
+    if (!normalized) return;
+    if (pendingPackIds.size >= SNAPSHOT_MAX_PENDING_PACKS) return;
+    pendingPackIds.add(normalized);
+  });
+  setQueueDepth('sticker_pack_score_snapshot_pending', pendingPackIds.size);
+};
+
+export const runStickerPackScoreSnapshotCycle = async () => {
+  if (!SNAPSHOT_ENABLED) {
+    return {
+      executed: false,
+      reason: 'disabled',
+      pending_pack_ids: pendingPackIds.size,
+    };
+  }
+  if (running) {
+    return {
+      executed: false,
+      reason: 'already_running',
+      pending_pack_ids: pendingPackIds.size,
+    };
+  }
+
+  running = true;
+  const startedAt = Date.now();
+  let scanned = 0;
+  let written = 0;
+  let fullRebuildExecuted = false;
+
+  try {
+    const targetedPackIds = consumePendingPackIds(SNAPSHOT_TARGETED_BATCH_SIZE);
+    if (targetedPackIds.length) {
+      const targetedPacks = await listPacksByIdsForSnapshot(targetedPackIds);
+      const targetedResult = await rebuildSnapshotsForPacks(targetedPacks);
+      scanned += targetedResult.scanned;
+      written += targetedResult.written;
+    }
+
+    cycleCounter += 1;
+    fullRebuildExecuted =
+      cycleCounter % SNAPSHOT_FULL_REBUILD_EVERY_CYCLES === 0 || targetedPackIds.length === 0;
+
+    if (fullRebuildExecuted) {
+      let offset = 0;
+      while (true) {
+        const packs = await listPublishedCatalogPacks({
+          limit: SNAPSHOT_BATCH_SIZE,
+          offset,
+        });
+        if (!packs.length) break;
+        const result = await rebuildSnapshotsForPacks(packs);
+        scanned += result.scanned;
+        written += result.written;
+        offset += packs.length;
+        if (packs.length < SNAPSHOT_BATCH_SIZE) break;
+      }
+    }
+
+    const removed = await removeSnapshotsForDeletedPacks().catch(() => 0);
+    setQueueDepth('sticker_pack_score_snapshot_pending', pendingPackIds.size);
+
+    logger.info('Ciclo de snapshot de score de packs finalizado.', {
+      action: 'sticker_pack_score_snapshot_cycle',
+      scanned,
+      written,
+      removed,
+      pending_pack_ids: pendingPackIds.size,
+      full_rebuild_executed: fullRebuildExecuted,
+      full_rebuild_every_cycles: SNAPSHOT_FULL_REBUILD_EVERY_CYCLES,
+      duration_ms: Date.now() - startedAt,
+      batch_size: SNAPSHOT_BATCH_SIZE,
+      targeted_batch_size: SNAPSHOT_TARGETED_BATCH_SIZE,
+    });
+
+    return {
+      executed: true,
+      reason: 'ok',
+      scanned,
+      written,
+      removed,
+      pending_pack_ids: pendingPackIds.size,
+      full_rebuild_executed: fullRebuildExecuted,
+      duration_ms: Date.now() - startedAt,
+    };
+  } catch (error) {
+    logger.error('Falha no ciclo de snapshot de score de packs.', {
+      action: 'sticker_pack_score_snapshot_cycle_failed',
+      error: error?.message,
+    });
+    return {
+      executed: true,
+      reason: 'failed',
+      scanned,
+      written,
+      pending_pack_ids: pendingPackIds.size,
+      full_rebuild_executed: fullRebuildExecuted,
+      duration_ms: Date.now() - startedAt,
+    };
+  } finally {
+    running = false;
+  }
+};
+
+const scheduleNextCycle = () => {
+  if (!SNAPSHOT_ENABLED) return;
+  if (cycleHandle) {
+    clearTimeout(cycleHandle);
+    cycleHandle = null;
+  }
+  cycleHandle = setTimeout(() => {
+    cycleHandle = null;
+    void runStickerPackScoreSnapshotCycle().finally(() => {
+      scheduleNextCycle();
+    });
+  }, SNAPSHOT_REFRESH_INTERVAL_MS);
+  if (typeof cycleHandle?.unref === 'function') cycleHandle.unref();
+};
+
+export const startStickerPackScoreSnapshotRuntime = () => {
+  if (!SNAPSHOT_ENABLED) return;
+  if (startupHandle || cycleHandle) return;
+  startupHandle = setTimeout(() => {
+    startupHandle = null;
+    void runStickerPackScoreSnapshotCycle();
+    scheduleNextCycle();
+  }, SNAPSHOT_STARTUP_DELAY_MS);
+  if (typeof startupHandle?.unref === 'function') startupHandle.unref();
+};
+
+export const stopStickerPackScoreSnapshotRuntime = () => {
+  if (startupHandle) {
+    clearTimeout(startupHandle);
+    startupHandle = null;
+  }
+  if (cycleHandle) {
+    clearTimeout(cycleHandle);
+    cycleHandle = null;
+  }
+};