@revclamp/google-ads-transparency-mcp-actor 0.0.0-stage → 1.0.0

package/src/apify_actor.mjs

@@ -0,0 +1,1714 @@
+/**
+ * Apify Pay-per-Event Execution, Native Platform Adapter & Crash-Safe Billing State Machine (src/apify_actor.mjs)
+ *
+ * Enforces deterministic Pay-per-Event billing and delivery invariants:
+ *   1. Explicit Accounting Separation: Tracks `extractedCount`, `deliveredCount`,
+ *      `billableCount` (simulated unit-economics count), and confirmed `chargedEventCount`
+ *      (`0` in local/MCP unbilled mode; strictly validated integer in Apify billing mode).
+ *   2. Native Zero-Dependency Apify Platform Adapter (`createApifyPlatformHooks` & `loadApifyActorInput`):
+ *      Wires Apify Key-Value Store (`INPUT` & `ADPULSE_BILLING_CHECKPOINT`), Dataset (`pushData`),
+ *      and Pay-per-Event Charging (`POST /v2/actor-runs/:runId/charge` with `Idempotency-Key`)
+ *      when running on Apify (`APIFY_IS_AT_HOME=1` / `APIFY_TOKEN` + `APIFY_ACTOR_RUN_ID`) or local storage.
+ *   3. Crash-Safe KVS Checkpoint State Machine (`inFlightIds` -> `chargedIds` -> `deliveredIds`
+ *      or `unknownOutcomeIds`), deterministic prefix delivery when `eventChargeLimitReached` returns
+ *      partial `chargedCount`, cursor rewind on mid-stream halt/limit, and honest zero-event telemetry.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import {
+  resolveAdvertiserEntities,
+  fetchAdvertiserCreatives,
+  getCreativeDetailsById,
+  createEmptyUntrustedAdContent,
+  computeRewoundCursorForDeliveredPrefix,
+  verifyEgressUrlSsrfSafe,
+  CREATIVE_ID_RE,
+  ADVERTISER_ID_RE,
+  DEFAULT_RUN_DEADLINE_MS,
+} from './rpc_client.mjs';
+
+export const ACTOR_PRICING_CONTRACT = Object.freeze({
+  eventName: 'ad-creative-scraped',
+  actorStartFeeUsdc: 0.001,
+  priceUsdc: 0.0012,
+  costCeilingUsdc: 0.0001,
+  platformFeeRate: 0.2,
+  netPriceUsdc: 0.00096,
+  minMarginMultiplier: 2.5,
+  computeRatePerGbHourUsdc: 0.3,
+  maxMemoryMb: 256,
+  maxTimeoutSec: 25,
+  chunkSize: 25,
+  checkpointKey: 'ADPULSE_BILLING_CHECKPOINT',
+});
+
+/**
+ * Computes content-addressed batch idempotency key (`sha256(runId + '\x1f' + sortedChunkIds)`).
+ *
+ * @param {string} runId
+ * @param {string[]} creativeIds
+ * @returns {string}
+ */
+export function computeChunkIdempotencyKey(runId, creativeIds) {
+  const safeRunId = String(runId || 'default_run');
+  const sortedIds = [...creativeIds].map((id) => String(id)).sort();
+  return crypto
+    .createHash('sha256')
+    .update(`${safeRunId}\x1f${sortedIds.join('\x1f')}`, 'utf8')
+    .digest('hex');
+}
+
+/**
+ * Computes unit-economics and margin telemetry for a single Actor/MCP execution run.
+ * Uses Apify's standard `$0.30 / GB-hour` compute rate (`0.25 GB` at `256MB`).
+ * When `billableCount === 0`, returns `economicsStatus: 'NO_BILLABLE_EVENTS'` with
+ * `withinCostCeiling: false` and `marginPositive: false`.
+ *
+ * @param {object} params
+ * @param {number} params.billableCount
+ * @param {number} [params.chargedEventCount=0]
+ * @param {number} params.durationMs
+ * @param {number} [params.memoryMb=256]
+ * @param {number} [params.requestCount=1]
+ * @returns {object}
+ */
+export function computeRunEconomicsTelemetry({
+  billableCount = 0,
+  chargedEventCount = 0,
+  durationMs = 100,
+  memoryMb =
+    Number(process.env.ACTOR_MEMORY_MBYTES || process.env.APIFY_MEMORY_MBYTES) ||
+    ACTOR_PRICING_CONTRACT.maxMemoryMb,
+  requestCount = 1,
+} = {}) {
+  const safeCount = Math.max(0, Math.floor(Number(billableCount) || 0));
+  const safeChargedCount = Math.max(0, Math.floor(Number(chargedEventCount) || 0));
+  const safeDurationMs = Math.max(1, Number(durationMs) || 1);
+  const safeMemoryMb = Math.min(1024, Math.max(64, Number(memoryMb) || 256));
+  const safeRequests = Math.max(1, Math.floor(Number(requestCount) || 1));
+
+  // Apify compute rate: $0.30 per GB-hour; 256MB = 0.25 GB -> $0.075/hour -> $0.00002083/sec
+  const computeHours = safeDurationMs / 3600000;
+  const computeCostUsdc =
+    (safeMemoryMb / 1024) * computeHours * ACTOR_PRICING_CONTRACT.computeRatePerGbHourUsdc;
+  const networkOverheadUsdc = safeRequests * 0.0000002;
+  const totalRunCostUsdc = Number((computeCostUsdc + networkOverheadUsdc).toFixed(8));
+  const actorStartFeeUsdc = ACTOR_PRICING_CONTRACT.actorStartFeeUsdc;
+
+  const configuredFloorMultiplier = Number(
+    (ACTOR_PRICING_CONTRACT.netPriceUsdc / ACTOR_PRICING_CONTRACT.costCeilingUsdc).toFixed(2)
+  );
+
+  if (safeCount === 0) {
+    return {
+      economicsStatus: 'NO_BILLABLE_EVENTS',
+      billableCount: 0,
+      chargedEventCount: safeChargedCount,
+      durationMs: safeDurationMs,
+      memoryMb: safeMemoryMb,
+      requestCount: safeRequests,
+      actorStartFeeUsdc,
+      totalRunCostUsdc,
+      actualCostPerEventUsdc: 0,
+      costCeilingUsdc: ACTOR_PRICING_CONTRACT.costCeilingUsdc,
+      withinCostCeiling: false,
+      grossRevenueUsdc: 0,
+      netRevenueUsdc: 0,
+      configuredFloorMultiplier,
+      effectiveMarginMultiplier: 0,
+      marginPositive: false,
+    };
+  }
+
+  const actualCostPerEventUsdc = Number((totalRunCostUsdc / safeCount).toFixed(8));
+  const grossRevenueUsdc = Number((safeCount * ACTOR_PRICING_CONTRACT.priceUsdc).toFixed(6));
+  const netRevenueUsdc = Number((safeCount * ACTOR_PRICING_CONTRACT.netPriceUsdc).toFixed(6));
+  const effectiveMarginMultiplier =
+    actualCostPerEventUsdc > 0
+      ? Number((ACTOR_PRICING_CONTRACT.netPriceUsdc / actualCostPerEventUsdc).toFixed(2))
+      : configuredFloorMultiplier;
+
+  const withinCostCeiling = actualCostPerEventUsdc <= ACTOR_PRICING_CONTRACT.costCeilingUsdc;
+  const marginPositive =
+    withinCostCeiling &&
+    configuredFloorMultiplier >= ACTOR_PRICING_CONTRACT.minMarginMultiplier;
+
+  return {
+    economicsStatus: marginPositive ? 'PROFITABLE' : 'COST_CEILING_EXCEEDED',
+    billableCount: safeCount,
+    chargedEventCount: safeChargedCount,
+    durationMs: safeDurationMs,
+    memoryMb: safeMemoryMb,
+    requestCount: safeRequests,
+    actorStartFeeUsdc,
+    totalRunCostUsdc,
+    actualCostPerEventUsdc,
+    costCeilingUsdc: ACTOR_PRICING_CONTRACT.costCeilingUsdc,
+    withinCostCeiling,
+    grossRevenueUsdc,
+    netRevenueUsdc,
+    configuredFloorMultiplier,
+    effectiveMarginMultiplier,
+    marginPositive,
+  };
+}
+
+/**
+ * Validates that an Apify API base URL is safe (`https://api.apify.com` by default).
+ * When `rawApiBaseUrl` is an internal HTTP endpoint on Apify Cloud and a valid HTTPS
+ * `fallbackPublicBaseUrl` (`APIFY_API_PUBLIC_BASE_URL`) is provided, uses the HTTPS public URL.
+ *
+ * @param {string} [rawApiBaseUrl]
+ * @param {string} [fallbackPublicBaseUrl]
+ * @returns {string}
+ */
+function resolveSafeApifyApiBaseUrl(rawApiBaseUrl, fallbackPublicBaseUrl = undefined) {
+  const candidate = String(rawApiBaseUrl || fallbackPublicBaseUrl || 'https://api.apify.com')
+    .trim()
+    .replace(/\/+$/, '');
+  const ssrf = verifyEgressUrlSsrfSafe(candidate);
+  if (!ssrf.safe) {
+    if (fallbackPublicBaseUrl) {
+      const publicCandidate = String(fallbackPublicBaseUrl).trim().replace(/\/+$/, '');
+      const publicSsrf = verifyEgressUrlSsrfSafe(publicCandidate);
+      if (publicSsrf.safe) {
+        return publicCandidate;
+      }
+    }
+    throw new Error(`Invalid or unsafe APIFY_API_BASE_URL '${candidate}': ${ssrf.reason}`);
+  }
+  return candidate;
+}
+
+/**
+ * Loads Actor input JSON from CLI `--input-json`, `APIFY_INPUT_PATH`, local Apify storage
+ * (`$ACTOR_STORAGE_DIR` / `$APIFY_LOCAL_STORAGE_DIR/key_value_stores/default/INPUT.json`),
+ * or Apify Platform KVS REST API.
+ *
+ * @param {string[]} [cliArgs=[]]
+ * @param {object} [env=process.env]
+ * @param {Function} [fetchImpl=globalThis.fetch]
+ * @returns {Promise<object>}
+ */
+export async function loadApifyActorInput(
+  cliArgs = [],
+  env = process.env,
+  fetchImpl = globalThis.fetch
+) {
+  const inputIdx = Array.isArray(cliArgs) ? cliArgs.indexOf('--input-json') : -1;
+  if (inputIdx !== -1 && cliArgs[inputIdx + 1]) {
+    const raw = fs.readFileSync(cliArgs[inputIdx + 1], 'utf8');
+    return JSON.parse(raw);
+  }
+
+  if (env?.APIFY_INPUT_PATH && fs.existsSync(env.APIFY_INPUT_PATH)) {
+    const raw = fs.readFileSync(env.APIFY_INPUT_PATH, 'utf8');
+    return JSON.parse(raw);
+  }
+
+  const localStorageDir =
+    env?.ACTOR_STORAGE_DIR || env?.APIFY_LOCAL_STORAGE_DIR || env?.CRAWLEE_STORAGE_DIR;
+  if (localStorageDir) {
+    const kvsId =
+      env?.ACTOR_DEFAULT_KEY_VALUE_STORE_ID ||
+      env?.APIFY_DEFAULT_KEY_VALUE_STORE_ID ||
+      'default';
+    const inputKey = env?.ACTOR_INPUT_KEY || env?.APIFY_INPUT_KEY || 'INPUT';
+    for (const candidateName of [`${inputKey}.json`, inputKey]) {
+      const localInputPath = path.join(
+        localStorageDir,
+        'key_value_stores',
+        kvsId,
+        candidateName
+      );
+      if (fs.existsSync(localInputPath)) {
+        return JSON.parse(fs.readFileSync(localInputPath, 'utf8'));
+      }
+    }
+  }
+
+  const kvsId =
+    env?.ACTOR_DEFAULT_KEY_VALUE_STORE_ID || env?.APIFY_DEFAULT_KEY_VALUE_STORE_ID;
+  const token = env?.APIFY_TOKEN;
+  if (kvsId && token && typeof fetchImpl === 'function') {
+    const apiBase = resolveSafeApifyApiBaseUrl(
+      env?.APIFY_API_BASE_URL,
+      env?.APIFY_API_PUBLIC_BASE_URL
+    );
+    const inputKey = encodeURIComponent(
+      env?.ACTOR_INPUT_KEY || env?.APIFY_INPUT_KEY || 'INPUT'
+    );
+    const url = `${apiBase}/v2/key-value-stores/${encodeURIComponent(kvsId)}/records/${inputKey}`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 4000);
+    try {
+      const res = await fetchImpl(url, {
+        method: 'GET',
+        headers: {
+          authorization: `Bearer ${token}`,
+          accept: 'application/json',
+        },
+        signal: controller.signal,
+      });
+      if (res.status === 200) {
+        const text = await res.text();
+        if (text && text.trim()) {
+          return JSON.parse(text);
+        }
+      }
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  return {};
+}
+
+/**
+ * Creates native zero-dependency Apify Platform runtime hooks (`runId`, `isAtHome`,
+ * `loadCheckpoint`, `saveCheckpoint`, `listDeliveredIds`, `pushData`, `chargeEvent`, `saveOutput`)
+ * when Apify environment variables (`ACTOR_*` primary, `APIFY_*` fallback) or local
+ * storage directories are configured. Returns `{}` in pure local CLI/MCP mode.
+ *
+ * @param {object} [env=process.env]
+ * @param {Function} [fetchImpl=globalThis.fetch]
+ * @returns {object}
+ */
+export function createApifyPlatformHooks(env = process.env, fetchImpl = globalThis.fetch) {
+  const rawRunId = env?.ACTOR_RUN_ID || env?.APIFY_ACTOR_RUN_ID;
+  const runId = rawRunId ? String(rawRunId).trim() : undefined;
+  const token = env?.APIFY_TOKEN ? String(env.APIFY_TOKEN).trim() : undefined;
+  const rawDatasetId = env?.ACTOR_DEFAULT_DATASET_ID || env?.APIFY_DEFAULT_DATASET_ID;
+  const datasetId = rawDatasetId ? String(rawDatasetId).trim() : undefined;
+  const rawKvsId =
+    env?.ACTOR_DEFAULT_KEY_VALUE_STORE_ID || env?.APIFY_DEFAULT_KEY_VALUE_STORE_ID;
+  const kvsId = rawKvsId ? String(rawKvsId).trim() : undefined;
+  const localStorageDir =
+    env?.ACTOR_STORAGE_DIR || env?.APIFY_LOCAL_STORAGE_DIR || env?.CRAWLEE_STORAGE_DIR;
+  const isAtHome = env?.APIFY_IS_AT_HOME === '1' || env?.APIFY_IS_AT_HOME === 'true';
+
+  const hasCloudApi = Boolean((isAtHome || runId) && token && typeof fetchImpl === 'function');
+  if (!hasCloudApi && !localStorageDir) {
+    if (isAtHome) {
+      return { isAtHome: true, ...(runId ? { runId } : {}) };
+    }
+    return runId ? { runId } : {};
+  }
+
+  const hooks = {};
+  if (runId) {
+    hooks.runId = runId;
+  }
+  if (isAtHome || hasCloudApi) {
+    hooks.isAtHome = true;
+  }
+
+  if (hasCloudApi) {
+    const apiBase = resolveSafeApifyApiBaseUrl(
+      env?.APIFY_API_BASE_URL,
+      env?.APIFY_API_PUBLIC_BASE_URL
+    );
+    const rawMaxChargeStr =
+      env?.ACTOR_MAX_TOTAL_CHARGE_USD !== undefined && env?.ACTOR_MAX_TOTAL_CHARGE_USD !== null
+        ? String(env.ACTOR_MAX_TOTAL_CHARGE_USD).trim()
+        : '';
+    const maxTotalChargeUsdRaw = rawMaxChargeStr !== '' ? Number(rawMaxChargeStr) : NaN;
+    const hasMaxChargeUsd = Number.isFinite(maxTotalChargeUsdRaw) && maxTotalChargeUsdRaw >= 0;
+    const includeStartFeeFlag = String(env?.ACTOR_INCLUDE_START_FEE ?? '1')
+      .trim()
+      .toLowerCase();
+    const includeStartFee = includeStartFeeFlag !== '0' && includeStartFeeFlag !== 'false';
+    const explicitStartFeeUsd =
+      env?.ACTOR_START_FEE_USD !== undefined &&
+      env?.ACTOR_START_FEE_USD !== null &&
+      String(env.ACTOR_START_FEE_USD).trim() !== ''
+        ? Number(env.ACTOR_START_FEE_USD)
+        : ACTOR_PRICING_CONTRACT.actorStartFeeUsdc;
+    const startFeeMicros =
+      includeStartFee && Number.isFinite(explicitStartFeeUsd) && explicitStartFeeUsd >= 0
+        ? Math.round(explicitStartFeeUsd * 1_000_000)
+        : 0;
+    const unitPriceMicros = Math.round(ACTOR_PRICING_CONTRACT.priceUsdc * 1_000_000);
+    const maxBudgetMicros = hasMaxChargeUsd ? Math.round(maxTotalChargeUsdRaw * 1_000_000) : 0;
+    const maxPayableEvents = hasMaxChargeUsd
+      ? Math.floor(Math.max(0, maxBudgetMicros - startFeeMicros) / unitPriceMicros)
+      : Infinity;
+    let cumulativeChargedInAdapter = 0;
+    let adapterChargeLimitLatched = false;
+
+    if (kvsId) {
+      const checkpointRecordUrl = `${apiBase}/v2/key-value-stores/${encodeURIComponent(kvsId)}/records/${ACTOR_PRICING_CONTRACT.checkpointKey}`;
+      const outputRecordUrl = `${apiBase}/v2/key-value-stores/${encodeURIComponent(kvsId)}/records/OUTPUT`;
+
+      hooks.loadCheckpoint = async () => {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), 250);
+        try {
+          const res = await fetchImpl(checkpointRecordUrl, {
+            method: 'GET',
+            headers: {
+              authorization: `Bearer ${token}`,
+              accept: 'application/json',
+            },
+            signal: controller.signal,
+          });
+          if (res.status === 404 || res.status === 204) {
+            return null;
+          }
+          if (res.status >= 200 && res.status < 300) {
+            const text = await res.text();
+            const loaded = text && text.trim() ? JSON.parse(text) : null;
+            if (loaded && Array.isArray(loaded.chargedIds)) {
+              cumulativeChargedInAdapter = loaded.chargedIds.length;
+            }
+            return loaded;
+          }
+          throw new Error(`Apify KVS loadCheckpoint failed with HTTP ${res.status}`);
+        } finally {
+          clearTimeout(timer);
+        }
+      };
+
+      hooks.saveCheckpoint = async (snapshot) => {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), 250);
+        try {
+          const res = await fetchImpl(checkpointRecordUrl, {
+            method: 'PUT',
+            headers: {
+              authorization: `Bearer ${token}`,
+              'content-type': 'application/json; charset=utf-8',
+            },
+            body: JSON.stringify(snapshot),
+            signal: controller.signal,
+          });
+          if (res.status < 200 || res.status >= 300) {
+            throw new Error(`Apify KVS saveCheckpoint HTTP ${res.status}`);
+          }
+        } finally {
+          clearTimeout(timer);
+        }
+      };
+
+      hooks.saveOutput = async (outputRecord) => {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), 250);
+        try {
+          const res = await fetchImpl(outputRecordUrl, {
+            method: 'PUT',
+            headers: {
+              authorization: `Bearer ${token}`,
+              'content-type': 'application/json; charset=utf-8',
+            },
+            body: JSON.stringify(outputRecord),
+            signal: controller.signal,
+          });
+          if (res.status < 200 || res.status >= 300) {
+            throw new Error(`Apify KVS saveOutput HTTP ${res.status}`);
+          }
+        } finally {
+          clearTimeout(timer);
+        }
+      };
+    }
+
+    if (datasetId) {
+      const datasetItemsUrl = `${apiBase}/v2/datasets/${encodeURIComponent(datasetId)}/items`;
+      hooks.listDeliveredIds = async () => {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), 500);
+        try {
+          const res = await fetchImpl(`${datasetItemsUrl}?fields=creativeId&clean=1`, {
+            method: 'GET',
+            headers: {
+              authorization: `Bearer ${token}`,
+              accept: 'application/json',
+            },
+            signal: controller.signal,
+          });
+          if (res.status >= 200 && res.status < 300) {
+            const text = await res.text();
+            const parsed = text && text.trim() ? JSON.parse(text) : [];
+            const arr = Array.isArray(parsed)
+              ? parsed
+              : Array.isArray(parsed?.data?.items)
+                ? parsed.data.items
+                : [];
+            return arr
+              .map((row) => (typeof row?.creativeId === 'string' ? row.creativeId : null))
+              .filter(Boolean);
+          }
+          throw new Error(`Apify Dataset listDeliveredIds failed with HTTP ${res.status}`);
+        } finally {
+          clearTimeout(timer);
+        }
+      };
+
+      hooks.pushData = async (items) => {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), 500);
+        try {
+          const res = await fetchImpl(datasetItemsUrl, {
+            method: 'POST',
+            headers: {
+              authorization: `Bearer ${token}`,
+              'content-type': 'application/json; charset=utf-8',
+            },
+            body: JSON.stringify(items),
+            signal: controller.signal,
+          });
+          if (res.status < 200 || res.status >= 300) {
+            throw new Error(`Apify Dataset pushData HTTP ${res.status}`);
+          }
+        } finally {
+          clearTimeout(timer);
+        }
+      };
+    }
+
+    if (runId) {
+      const chargeUrl = `${apiBase}/v2/actor-runs/${encodeURIComponent(runId)}/charge`;
+      hooks.chargeEvent = async (receipt) => {
+        const requestedCount = Math.max(0, Number(receipt?.count) || 0);
+        if (adapterChargeLimitLatched) {
+          return {
+            chargedCount: 0,
+            eventChargeLimitReached: true,
+            chargedCreativeIds: [],
+          };
+        }
+        const remainingAllowance = Number.isFinite(maxPayableEvents)
+          ? Math.max(0, maxPayableEvents - cumulativeChargedInAdapter)
+          : requestedCount;
+        const countToCharge = Math.min(requestedCount, remainingAllowance);
+        const limitReached =
+          Number.isFinite(maxPayableEvents) &&
+          cumulativeChargedInAdapter + countToCharge >= maxPayableEvents &&
+          countToCharge < requestedCount;
+
+        if (countToCharge === 0) {
+          return {
+            chargedCount: 0,
+            eventChargeLimitReached: Number.isFinite(maxPayableEvents),
+            chargedCreativeIds: [],
+          };
+        }
+
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), 600);
+        try {
+          const res = await fetchImpl(chargeUrl, {
+            method: 'POST',
+            headers: {
+              authorization: `Bearer ${token}`,
+              'content-type': 'application/json; charset=utf-8',
+              'idempotency-key': receipt.idempotencyKey,
+            },
+            body: JSON.stringify({
+              eventName: receipt.eventName,
+              count: countToCharge,
+            }),
+            signal: controller.signal,
+          });
+          if (res.status === 402) {
+            // Platform enforced spending ceiling (HTTP 402 Payment Required): latch so no further charge POSTs occur
+            adapterChargeLimitLatched = true;
+            return {
+              chargedCount: 0,
+              eventChargeLimitReached: true,
+              chargedCreativeIds: [],
+            };
+          }
+          if (res.status < 200 || res.status >= 300) {
+            throw new Error(`Apify Pay-per-Event charge HTTP ${res.status}`);
+          }
+          const rawText = await res.text();
+          const parsed = rawText && rawText.trim() ? JSON.parse(rawText) : {};
+          const dataObj = parsed?.data && typeof parsed.data === 'object' ? parsed.data : parsed;
+          // Apify REST `POST /v2/actor-runs/{runId}/charge` returns HTTP 201 Created with `{}` on success.
+          // Only fallback to `countToCharge` when `chargedCount` is genuinely omitted; if present but invalid, throw fail-closed.
+          const hasExplicitChargedCount =
+            Boolean(dataObj) &&
+            typeof dataObj === 'object' &&
+            Object.prototype.hasOwnProperty.call(dataObj, 'chargedCount') &&
+            dataObj.chargedCount !== undefined;
+          if (
+            hasExplicitChargedCount &&
+            (!Number.isInteger(dataObj.chargedCount) ||
+              dataObj.chargedCount < 0 ||
+              dataObj.chargedCount > countToCharge)
+          ) {
+            throw new Error(
+              `Apify Pay-per-Event charge response contained invalid chargedCount: ${String(dataObj.chargedCount)}`
+            );
+          }
+          const resolvedChargedCount = hasExplicitChargedCount
+            ? dataObj.chargedCount
+            : countToCharge;
+          cumulativeChargedInAdapter += resolvedChargedCount;
+          const resolvedLimitReached =
+            Boolean(dataObj?.eventChargeLimitReached) ||
+            limitReached ||
+            (Number.isFinite(maxPayableEvents) && cumulativeChargedInAdapter >= maxPayableEvents);
+          const subsetIds = Array.isArray(dataObj?.chargedCreativeIds)
+            ? dataObj.chargedCreativeIds
+            : Array.isArray(receipt?.creativeIds)
+              ? receipt.creativeIds.slice(0, resolvedChargedCount)
+              : undefined;
+          return {
+            chargedCount: resolvedChargedCount,
+            eventChargeLimitReached: resolvedLimitReached,
+            ...(subsetIds ? { chargedCreativeIds: subsetIds } : {}),
+          };
+        } finally {
+          clearTimeout(timer);
+        }
+      };
+    }
+
+    return hooks;
+  }
+
+  // Local Apify storage directory mode (`APIFY_LOCAL_STORAGE_DIR`)
+  const storeName = kvsId || 'default';
+  const dsName = datasetId || 'default';
+  const kvsDir = path.join(localStorageDir, 'key_value_stores', storeName);
+  const dsDir = path.join(localStorageDir, 'datasets', dsName);
+  const checkpointPath = path.join(kvsDir, `${ACTOR_PRICING_CONTRACT.checkpointKey}.json`);
+  const outputPath = path.join(kvsDir, 'OUTPUT.json');
+
+  hooks.loadCheckpoint = async () => {
+    if (!fs.existsSync(checkpointPath)) return null;
+    return JSON.parse(fs.readFileSync(checkpointPath, 'utf8'));
+  };
+
+  hooks.saveCheckpoint = async (snapshot) => {
+    fs.mkdirSync(kvsDir, { recursive: true });
+    fs.writeFileSync(checkpointPath, JSON.stringify(snapshot, null, 2), 'utf8');
+  };
+
+  hooks.saveOutput = async (outputRecord) => {
+    fs.mkdirSync(kvsDir, { recursive: true });
+    fs.writeFileSync(outputPath, JSON.stringify(outputRecord, null, 2), 'utf8');
+  };
+
+  hooks.listDeliveredIds = async () => {
+    if (!fs.existsSync(dsDir)) return [];
+    const existingFiles = fs.readdirSync(dsDir).filter((f) => f.endsWith('.json'));
+    const ids = [];
+    for (const file of existingFiles) {
+      try {
+        const parsed = JSON.parse(fs.readFileSync(path.join(dsDir, file), 'utf8'));
+        if (typeof parsed?.creativeId === 'string') {
+          ids.push(parsed.creativeId);
+        }
+      } catch {
+        // Ignore unreadable partial files
+      }
+    }
+    return ids;
+  };
+
+  hooks.pushData = async (items) => {
+    fs.mkdirSync(dsDir, { recursive: true });
+    const existingSeqs = fs
+      .readdirSync(dsDir)
+      .map((f) => {
+        const m = /^(\d+)\.json$/.exec(f);
+        return m ? Number(m[1]) : 0;
+      })
+      .filter((n) => Number.isInteger(n) && n > 0);
+    let nextSeq = existingSeqs.length > 0 ? Math.max(...existingSeqs) + 1 : 1;
+    const list = Array.isArray(items) ? items : [items];
+    for (const item of list) {
+      const fileName = `${String(nextSeq++).padStart(9, '0')}.json`;
+      fs.writeFileSync(path.join(dsDir, fileName), JSON.stringify(item, null, 2), 'utf8');
+    }
+  };
+
+  return hooks;
+}
+
+/**
+ * Normalizes a persisted KVS billing checkpoint object.
+ * If the checkpoint belongs to a different `runId`, discards stale state and starts fresh.
+ *
+ * @param {unknown} rawState
+ * @param {string} runId
+ * @returns {object}
+ */
+function normalizeBillingCheckpointState(rawState, runId) {
+  const s = rawState && typeof rawState === 'object' && !Array.isArray(rawState) ? rawState : {};
+  if (s.runId && String(s.runId).trim() !== String(runId).trim()) {
+    return {
+      runId: String(runId || 'default_run'),
+      chargedIds: [],
+      deliveredIds: [],
+      inFlightIds: [],
+      unknownOutcomeIds: [],
+      stagedItemsById: {},
+    };
+  }
+
+  const toUniqueIdArray = (arr) =>
+    Array.isArray(arr)
+      ? Array.from(new Set(arr.map((x) => String(x || '').trim()).filter((x) => CREATIVE_ID_RE.test(x))))
+      : [];
+
+  const stagedItemsById = {};
+  if (s.stagedItemsById && typeof s.stagedItemsById === 'object' && !Array.isArray(s.stagedItemsById)) {
+    for (const [k, v] of Object.entries(s.stagedItemsById)) {
+      if (CREATIVE_ID_RE.test(k) && v && typeof v === 'object') {
+        stagedItemsById[k] = v;
+      }
+    }
+  }
+
+  return {
+    runId: String(s.runId || runId || 'default_run'),
+    chargedIds: toUniqueIdArray(s.chargedIds),
+    deliveredIds: toUniqueIdArray(s.deliveredIds),
+    inFlightIds: toUniqueIdArray(s.inFlightIds),
+    unknownOutcomeIds: toUniqueIdArray(s.unknownOutcomeIds),
+    stagedItemsById,
+  };
+}
+
+/**
+ * Executes the end-to-end Google Ads Transparency Actor workflow with crash-safe billing
+ * checkpointing, strict `ChargeResult` validation, deterministic partial-limit prefix delivery,
+ * mid-stream cursor rewind, and fail-closed zero-charge protection.
+ *
+ * @param {object} input
+ * @param {object} [hooks]
+ * @param {Function} [hooks.pushData]
+ * @param {Function} [hooks.chargeEvent]
+ * @param {Function} [hooks.loadCheckpoint]
+ * @param {Function} [hooks.saveCheckpoint]
+ * @param {Function} [hooks.fetchImpl]
+ * @param {Function} [hooks.nowMs]
+ * @param {string} [hooks.runId]
+ * @returns {Promise<object>}
+ */
+export async function runGoogleAdsTransparencyActor(input = {}, hooks = {}) {
+  const nowMs = typeof hooks.nowMs === 'function' ? hooks.nowMs : () => Date.now();
+  const startedAtMs = nowMs();
+  // Authoritative runId precedence: hooks.runId -> ACTOR_RUN_ID -> APIFY_ACTOR_RUN_ID -> input.runId -> 'default_run'
+  const runId = String(
+    hooks.runId ||
+      process.env.ACTOR_RUN_ID ||
+      process.env.APIFY_ACTOR_RUN_ID ||
+      input?.runId ||
+      'default_run'
+  );
+  const hasChargeHook = typeof hooks.chargeEvent === 'function';
+  const billingMode =
+    hasChargeHook || hooks.isAtHome === true ? 'APIFY_PAY_PER_EVENT' : 'LOCAL_UNBILLED';
+
+  const maxRunDurationMs = Math.min(
+    DEFAULT_RUN_DEADLINE_MS,
+    Math.max(1000, Number(input?.maxRunDurationMs) || DEFAULT_RUN_DEADLINE_MS)
+  );
+  const deadlineAtMs = startedAtMs + maxRunDurationMs;
+  const billingReserveMs =
+    maxRunDurationMs >= 6000 ? 2500 : Math.min(1000, Math.floor(maxRunDurationMs * 0.25));
+  const rpcDeadlineAtMs = hasChargeHook
+    ? Math.max(startedAtMs + 500, deadlineAtMs - billingReserveMs)
+    : deadlineAtMs;
+  const step4ReserveMs = hasChargeHook
+    ? Math.min(2100, Math.floor(billingReserveMs * 0.85))
+    : 0;
+
+  const finalizeActorReturn = async (finalResult) => {
+    if (typeof hooks.saveOutput === 'function' && nowMs() < deadlineAtMs) {
+      try {
+        await hooks.saveOutput({
+          ok: finalResult.ok,
+          status: finalResult.status,
+          reason: finalResult.reason || null,
+          billingMode: finalResult.billingMode,
+          extractedCount: finalResult.extractedCount,
+          deliveredCount: finalResult.deliveredCount,
+          billableCount: finalResult.billableCount,
+          chargedEventCount: finalResult.chargedEventCount,
+          pagination: finalResult.pagination,
+          ...(Array.isArray(finalResult.warnings) && finalResult.warnings.length > 0
+            ? { warnings: finalResult.warnings }
+            : {}),
+          queryMeta: finalResult.queryMeta,
+          selectedEntities: finalResult.selectedEntities,
+          telemetry: finalResult.telemetry,
+        });
+      } catch {
+        // Non-fatal KVS summary write
+      }
+    }
+    return finalResult;
+  };
+
+  const pushDataWithRetry = async (itemsToPush) => {
+    if (
+      typeof hooks.pushData !== 'function' ||
+      !Array.isArray(itemsToPush) ||
+      itemsToPush.length === 0
+    ) {
+      return { ok: true };
+    }
+    let pendingItems = [...itemsToPush];
+    let lastErr = null;
+    for (let attempt = 1; attempt <= 2; attempt += 1) {
+      try {
+        await hooks.pushData(pendingItems);
+        return { ok: true };
+      } catch (err) {
+        lastErr = err;
+        if (attempt < 2) {
+          if (nowMs() + 1500 >= deadlineAtMs || typeof hooks.listDeliveredIds !== 'function') {
+            return { ok: false, error: lastErr };
+          }
+          try {
+            const committedIds = new Set(await hooks.listDeliveredIds());
+            pendingItems = pendingItems.filter((it) => !committedIds.has(it.creativeId));
+            if (pendingItems.length === 0) {
+              return { ok: true };
+            }
+          } catch (reconcileErr) {
+            return { ok: false, error: reconcileErr || lastErr };
+          }
+        }
+      }
+    }
+    return { ok: false, error: lastErr };
+  };
+
+  // Step 0.0: Fail-Closed At-Home Cloud Hook Completeness Gate
+  // In Apify Cloud (`hooks.isAtHome === true`), require all 4 platform hooks (`chargeEvent`,
+  // `pushData`, `loadCheckpoint`, `saveCheckpoint`) before any RPC fetch or billing occurs.
+  if (
+    hooks.isAtHome === true &&
+    (typeof hooks.chargeEvent !== 'function' ||
+      typeof hooks.pushData !== 'function' ||
+      typeof hooks.loadCheckpoint !== 'function' ||
+      typeof hooks.saveCheckpoint !== 'function')
+  ) {
+    const durationMs = Math.max(1, nowMs() - startedAtMs);
+    return finalizeActorReturn({
+      ok: false,
+      status: 'PARTIAL_BILLING_HALT',
+      reason:
+        'Incomplete Apify Cloud runtime hooks (missing chargeEvent, pushData, loadCheckpoint, or saveCheckpoint in at-home mode)',
+      billingMode,
+      queryMeta: null,
+      selectedEntities: [],
+      items: [],
+      extractedCount: 0,
+      deliveredCount: 0,
+      billableCount: 0,
+      chargedEventCount: 0,
+      unknownOutcomeIds: [],
+      chargeReceipts: [],
+      pagination: {
+        nextPageToken: input?.pageToken || null,
+        paginationStatus: 'PARTIAL_BILLING_HALT',
+        paginationIncompleteReason: 'CLOUD_HOOKS_INCOMPLETE',
+      },
+      telemetry: computeRunEconomicsTelemetry({
+        billableCount: 0,
+        chargedEventCount: 0,
+        durationMs,
+        requestCount: 1,
+      }),
+    });
+  }
+
+  // Step 0: Load & Reconcile Crash-Safe Billing Checkpoint (fail-closed if loadCheckpoint throws)
+  let rawLoadedCheckpoint = null;
+  if (typeof hooks.loadCheckpoint === 'function') {
+    try {
+      rawLoadedCheckpoint = await hooks.loadCheckpoint();
+    } catch (cpErr) {
+      const durationMs = Math.max(1, nowMs() - startedAtMs);
+      return finalizeActorReturn({
+        ok: false,
+        status: 'PARTIAL_BILLING_HALT',
+        reason: `Failed to load billing checkpoint fail-closed: ${cpErr?.message || String(cpErr)}`,
+        billingMode,
+        queryMeta: null,
+        selectedEntities: [],
+        items: [],
+        extractedCount: 0,
+        deliveredCount: 0,
+        billableCount: 0,
+        chargedEventCount: 0,
+        unknownOutcomeIds: [],
+        chargeReceipts: [],
+        pagination: {
+          nextPageToken: input?.pageToken || null,
+          paginationStatus: 'PARTIAL_BILLING_HALT',
+          paginationIncompleteReason: 'CHECKPOINT_LOAD_FAILED',
+        },
+        telemetry: computeRunEconomicsTelemetry({
+          billableCount: 0,
+          chargedEventCount: 0,
+          durationMs,
+          requestCount: 1,
+        }),
+      });
+    }
+  }
+  const checkpoint = normalizeBillingCheckpointState(rawLoadedCheckpoint, runId);
+
+  const chargedSet = new Set(checkpoint.chargedIds);
+  const deliveredSet = new Set(checkpoint.deliveredIds);
+  const unknownOutcomeSet = new Set(checkpoint.unknownOutcomeIds);
+  let inFlightSet = new Set(checkpoint.inFlightIds);
+  const stagedItemsById = { ...checkpoint.stagedItemsById };
+
+  const persistCheckpoint = async () => {
+    const snapshot = {
+      runId,
+      chargedIds: Array.from(chargedSet),
+      deliveredIds: Array.from(deliveredSet),
+      inFlightIds: Array.from(inFlightSet),
+      unknownOutcomeIds: Array.from(unknownOutcomeSet),
+      stagedItemsById,
+    };
+    if (typeof hooks.saveCheckpoint === 'function') {
+      await hooks.saveCheckpoint(snapshot);
+    }
+    return snapshot;
+  };
+
+  const reconciledItems = [];
+  let deliveredCount = deliveredSet.size;
+
+  // Step 0a: Reconcile any already-paid items (`chargedIds \ deliveredIds`) without re-charging.
+  // First check `hooks.listDeliveredIds()` if available so items already committed to dataset before a lost ACK
+  // are marked delivered without duplicate dataset POSTs. Fail closed if dataset listing throws.
+  const paidUndeliveredIds = Array.from(chargedSet).filter((id) => !deliveredSet.has(id));
+  if (paidUndeliveredIds.length > 0) {
+    let alreadyInDatasetSet = new Set();
+    if (typeof hooks.listDeliveredIds === 'function') {
+      try {
+        const existingDsIds = await hooks.listDeliveredIds();
+        if (Array.isArray(existingDsIds)) {
+          alreadyInDatasetSet = new Set(existingDsIds);
+        }
+      } catch (dsListErr) {
+        const durationMs = Math.max(1, nowMs() - startedAtMs);
+        return finalizeActorReturn({
+          ok: false,
+          status: 'PARTIAL_BILLING_HALT',
+          reason: `Failed to verify delivered dataset IDs during reconciliation: ${dsListErr?.message || String(dsListErr)}`,
+          billingMode,
+          queryMeta: null,
+          selectedEntities: [],
+          items: [],
+          extractedCount: 0,
+          deliveredCount,
+          billableCount: 0,
+          chargedEventCount: chargedSet.size,
+          unknownOutcomeIds: Array.from(unknownOutcomeSet),
+          chargeReceipts: [],
+          pagination: {
+            nextPageToken: input?.pageToken || null,
+            paginationStatus: 'PARTIAL_BILLING_HALT',
+            paginationIncompleteReason: 'DATASET_RECONCILIATION_FAILED',
+          },
+          telemetry: computeRunEconomicsTelemetry({
+            billableCount: 0,
+            chargedEventCount: chargedSet.size,
+            durationMs,
+            requestCount: 1,
+          }),
+        });
+      }
+    }
+
+    const deliverablePairs = [];
+    for (const id of paidUndeliveredIds) {
+      const staged = stagedItemsById[id];
+      if (alreadyInDatasetSet.has(id)) {
+        deliveredSet.add(id);
+        if (staged && typeof staged === 'object' && staged.creativeId === id) {
+          reconciledItems.push(staged);
+        }
+      } else if (staged && typeof staged === 'object' && staged.creativeId === id) {
+        deliverablePairs.push({ id, item: staged });
+      } else {
+        unknownOutcomeSet.add(id);
+      }
+    }
+
+    if (deliverablePairs.length > 0) {
+      const itemsToDeliver = deliverablePairs.map((p) => p.item);
+      const pushRes = await pushDataWithRetry(itemsToDeliver);
+      if (!pushRes.ok) {
+        await persistCheckpoint();
+        const durationMs = Math.max(1, nowMs() - startedAtMs);
+        return finalizeActorReturn({
+          ok: false,
+          status: 'PARTIAL_BILLING_HALT',
+          reason: `Dataset pushData failed during reconciliation: ${pushRes.error?.message || String(pushRes.error)}`,
+          billingMode,
+          queryMeta: null,
+          selectedEntities: [],
+          items: reconciledItems,
+          extractedCount: 0,
+          deliveredCount,
+          billableCount: reconciledItems.length,
+          chargedEventCount: chargedSet.size,
+          unknownOutcomeIds: Array.from(unknownOutcomeSet),
+          chargeReceipts: [],
+          pagination: {
+            nextPageToken: input?.pageToken || null,
+            paginationStatus: 'PARTIAL_BILLING_HALT',
+            paginationIncompleteReason: 'DATASET_PUSH_FAILED',
+          },
+          telemetry: computeRunEconomicsTelemetry({
+            billableCount: reconciledItems.length,
+            chargedEventCount: chargedSet.size,
+            durationMs,
+            requestCount: 1,
+          }),
+        });
+      }
+      for (const { id, item } of deliverablePairs) {
+        deliveredSet.add(id);
+        reconciledItems.push(item);
+      }
+    }
+    deliveredCount = deliveredSet.size;
+    await persistCheckpoint();
+  }
+
+  // Step 0b: Any leftover `inFlightIds` from a prior interrupted run transition to `unknownOutcomeIds`
+  if (inFlightSet.size > 0) {
+    for (const id of inFlightSet) {
+      unknownOutcomeSet.add(id);
+    }
+    inFlightSet = new Set();
+    await persistCheckpoint();
+  }
+
+  if (unknownOutcomeSet.size > 0 && input?.strictBillingResume !== false) {
+    const durationMs = Math.max(1, nowMs() - startedAtMs);
+    return finalizeActorReturn({
+      ok: false,
+      status: 'PARTIAL_BILLING_HALT',
+      reason: `Halted due to ${unknownOutcomeSet.size} unreconciled creative(s) in UNKNOWN_CHARGE_OUTCOME state`,
+      billingMode,
+      queryMeta: null,
+      selectedEntities: [],
+      items: reconciledItems,
+      extractedCount: 0,
+      deliveredCount,
+      billableCount: reconciledItems.length,
+      chargedEventCount: chargedSet.size,
+      unknownOutcomeIds: Array.from(unknownOutcomeSet),
+      chargeReceipts: [],
+      pagination: {
+        nextPageToken: input?.pageToken || null,
+        paginationStatus: 'PARTIAL_BILLING_HALT',
+        paginationIncompleteReason: 'UNKNOWN_CHARGE_OUTCOME',
+      },
+      telemetry: computeRunEconomicsTelemetry({
+        billableCount: reconciledItems.length,
+        chargedEventCount: chargedSet.size,
+        durationMs,
+        requestCount: 1,
+      }),
+    });
+  }
+
+  const sleepFn =
+    typeof hooks.sleepFn === 'function'
+      ? hooks.sleepFn
+      : typeof input?.sleepFn === 'function'
+        ? input.sleepFn
+        : undefined;
+  const randomFn =
+    typeof hooks.randomFn === 'function'
+      ? hooks.randomFn
+      : typeof input?.randomFn === 'function'
+        ? input.randomFn
+        : undefined;
+
+  // Step 1: Resolve Advertiser Entities
+  const entityRes = await resolveAdvertiserEntities({
+    query: input?.query,
+    advertiserId: input?.advertiserId,
+    advertiserName: input?.advertiserName,
+    countryCode: input?.countryCode,
+    includeSubsidiaries: input?.includeSubsidiaries,
+    maxEntities: input?.maxEntities,
+    fetchImpl: hooks.fetchImpl,
+    nowFn: nowMs,
+    sleepFn,
+    randomFn,
+    timeoutMs: input?.timeoutMs,
+    maxRetries: input?.maxRetries,
+    deadlineAtMs: rpcDeadlineAtMs,
+  });
+
+  if (!entityRes.ok) {
+    const durationMs = Math.max(1, nowMs() - startedAtMs);
+    const isPreChargeDeadline =
+      hasChargeHook &&
+      nowMs() >= rpcDeadlineAtMs &&
+      /deadline exceeded/i.test(String(entityRes.reason || ''));
+    return finalizeActorReturn({
+      ok: false,
+      status: isPreChargeDeadline ? 'DEADLINE_EXCEEDED_BEFORE_CHARGE' : entityRes.status,
+      reason: entityRes.reason,
+      billingMode,
+      queryMeta: entityRes.queryMeta,
+      selectedEntities: [],
+      items: reconciledItems,
+      extractedCount: 0,
+      deliveredCount,
+      billableCount: reconciledItems.length,
+      chargedEventCount: hasChargeHook ? chargedSet.size : 0,
+      unknownOutcomeIds: Array.from(unknownOutcomeSet),
+      chargeReceipts: [],
+      pagination: {
+        nextPageToken: input?.pageToken || null,
+        paginationStatus: isPreChargeDeadline ? 'DEADLINE_EXCEEDED_HAS_MORE' : entityRes.status,
+        paginationIncompleteReason: isPreChargeDeadline
+          ? 'DEADLINE_EXCEEDED_BEFORE_CHARGE'
+          : entityRes.reason || null,
+      },
+      telemetry: computeRunEconomicsTelemetry({
+        billableCount: reconciledItems.length,
+        chargedEventCount: hasChargeHook ? chargedSet.size : 0,
+        durationMs,
+        requestCount: Math.max(1, entityRes.rpcAttempts),
+      }),
+    });
+  }
+
+  if (entityRes.status === 'EMPTY_RESULT' || entityRes.selectedEntities.length === 0) {
+    const durationMs = Math.max(1, nowMs() - startedAtMs);
+    return finalizeActorReturn({
+      ok: true,
+      status: 'EMPTY_RESULT',
+      billingMode,
+      queryMeta: entityRes.queryMeta,
+      selectedEntities: [],
+      items: reconciledItems,
+      extractedCount: 0,
+      deliveredCount,
+      billableCount: reconciledItems.length,
+      chargedEventCount: hasChargeHook ? chargedSet.size : 0,
+      unknownOutcomeIds: Array.from(unknownOutcomeSet),
+      chargeReceipts: [],
+      pagination: {
+        nextPageToken: null,
+        paginationStatus: 'EXHAUSTED',
+        paginationIncompleteReason: null,
+      },
+      telemetry: computeRunEconomicsTelemetry({
+        billableCount: reconciledItems.length,
+        chargedEventCount: hasChargeHook ? chargedSet.size : 0,
+        durationMs,
+        requestCount: Math.max(1, entityRes.rpcAttempts),
+      }),
+    });
+  }
+
+  // Step 2: Fetch Creatives across selected verified advertiser entities
+  const advertiserIds = entityRes.selectedEntities.map((e) => e.advertiserId);
+  const creativesRes = await fetchAdvertiserCreatives({
+    advertiserIds,
+    entities: entityRes.selectedEntities,
+    maxResults: input?.maxResults,
+    maxPages: input?.maxPages,
+    pageSize: input?.pageSize,
+    pageToken: input?.pageToken,
+    countryCode: input?.countryCode,
+    formatFilter: input?.formatFilter,
+    fetchImpl: hooks.fetchImpl,
+    nowFn: nowMs,
+    sleepFn,
+    randomFn,
+    timeoutMs: input?.timeoutMs,
+    maxRetries: input?.maxRetries,
+    deadlineAtMs: rpcDeadlineAtMs,
+  });
+
+  let totalRpcRequests = entityRes.rpcAttempts + creativesRes.rpcAttempts;
+
+  if (!creativesRes.ok) {
+    const durationMs = Math.max(1, nowMs() - startedAtMs);
+    const isPreChargeDeadline =
+      hasChargeHook &&
+      nowMs() >= rpcDeadlineAtMs &&
+      /deadline exceeded/i.test(String(creativesRes.reason || ''));
+    return finalizeActorReturn({
+      ok: false,
+      status: isPreChargeDeadline ? 'DEADLINE_EXCEEDED_BEFORE_CHARGE' : creativesRes.status,
+      reason: creativesRes.reason,
+      billingMode,
+      queryMeta: entityRes.queryMeta,
+      selectedEntities: entityRes.selectedEntities,
+      items: reconciledItems,
+      extractedCount: 0,
+      deliveredCount,
+      billableCount: reconciledItems.length,
+      chargedEventCount: hasChargeHook ? chargedSet.size : 0,
+      unknownOutcomeIds: Array.from(unknownOutcomeSet),
+      chargeReceipts: [],
+      pagination: {
+        nextPageToken: input?.pageToken || null,
+        paginationStatus: isPreChargeDeadline
+          ? 'DEADLINE_EXCEEDED_HAS_MORE'
+          : creativesRes.paginationStatus || creativesRes.status,
+        paginationIncompleteReason: isPreChargeDeadline
+          ? 'DEADLINE_EXCEEDED_BEFORE_CHARGE'
+          : creativesRes.paginationIncompleteReason || creativesRes.reason || null,
+      },
+      telemetry: computeRunEconomicsTelemetry({
+        billableCount: reconciledItems.length,
+        chargedEventCount: hasChargeHook ? chargedSet.size : 0,
+        durationMs,
+        requestCount: Math.max(1, totalRpcRequests),
+      }),
+    });
+  }
+
+  const maxResultsCap = Math.min(200, Math.max(1, Number(input?.maxResults) || 40));
+
+  // Step 3: Strict Deduplication & Validation Gate before emitting Pay-per-Event charges
+  const uniqueExtractedItems = [];
+  const seenInRunIds = new Set();
+
+  for (const item of creativesRes.creatives) {
+    if (
+      !item ||
+      !ADVERTISER_ID_RE.test(String(item.advertiserId || '')) ||
+      !CREATIVE_ID_RE.test(String(item.creativeId || ''))
+    ) {
+      const durationMs = Math.max(1, nowMs() - startedAtMs);
+      return finalizeActorReturn({
+        ok: false,
+        status: 'SCHEMA_DRIFT_HALT',
+        reason: 'Normalized creative record failed AR.../CR... identifier gate prior to billing',
+        billingMode,
+        queryMeta: entityRes.queryMeta,
+        selectedEntities: entityRes.selectedEntities,
+        items: reconciledItems,
+        extractedCount: 0,
+        deliveredCount,
+        billableCount: reconciledItems.length,
+        chargedEventCount: hasChargeHook ? chargedSet.size : 0,
+        unknownOutcomeIds: Array.from(unknownOutcomeSet),
+        chargeReceipts: [],
+        pagination: {
+          nextPageToken: null,
+          paginationStatus: 'SCHEMA_DRIFT_HALT',
+          paginationIncompleteReason: 'INVALID_CREATIVE_IDENTIFIER',
+        },
+        telemetry: computeRunEconomicsTelemetry({
+          billableCount: reconciledItems.length,
+          chargedEventCount: hasChargeHook ? chargedSet.size : 0,
+          durationMs,
+          requestCount: Math.max(1, totalRpcRequests),
+        }),
+      });
+    }
+
+    if (!seenInRunIds.has(item.creativeId)) {
+      seenInRunIds.add(item.creativeId);
+      uniqueExtractedItems.push(item);
+      if (uniqueExtractedItems.length >= maxResultsCap) {
+        break;
+      }
+    }
+  }
+
+  // Optional Step 3b: Enrich up to 10 creatives (default 5) via LookupService/GetCreativeById when includeCreativeDetails === true
+  if (input?.includeCreativeDetails === true && uniqueExtractedItems.length > 0) {
+    const requestedEnrichCap = Number(input?.maxEnrichItems ?? 5);
+    const enrichCap = Math.min(
+      10,
+      Math.max(1, Number.isFinite(requestedEnrichCap) ? Math.floor(requestedEnrichCap) : 5),
+      uniqueExtractedItems.length
+    );
+    let rateLimitedInEnrich = false;
+    for (let i = 0; i < enrichCap; i += 1) {
+      const targetItem = uniqueExtractedItems[i];
+      if (rateLimitedInEnrich) {
+        targetItem.untrustedAdContent = createEmptyUntrustedAdContent(
+          'NOT_ATTEMPTED_RATE_LIMITED'
+        );
+        continue;
+      }
+      if (nowMs() >= rpcDeadlineAtMs) {
+        targetItem.untrustedAdContent = createEmptyUntrustedAdContent(
+          'NOT_ATTEMPTED_DEADLINE'
+        );
+        continue;
+      }
+      const detailRes = await getCreativeDetailsById({
+        advertiserId: targetItem.advertiserId,
+        creativeId: targetItem.creativeId,
+        includeAdCopy: Boolean(input?.includeAdCopy),
+        fetchImpl: hooks.fetchImpl,
+        nowFn: nowMs,
+        sleepFn,
+        randomFn,
+        timeoutMs: input?.timeoutMs,
+        maxRetries: input?.maxRetries !== undefined ? input.maxRetries : 1,
+        deadlineAtMs: rpcDeadlineAtMs,
+      });
+      totalRpcRequests += detailRes.rpcAttempts;
+      if (detailRes.status === 'UPSTREAM_RATE_LIMITED') {
+        rateLimitedInEnrich = true;
+        targetItem.untrustedAdContent = createEmptyUntrustedAdContent(
+          'NOT_ATTEMPTED_RATE_LIMITED'
+        );
+        continue;
+      }
+      if (detailRes.ok && detailRes.detail) {
+        targetItem.creativeDetail = detailRes.detail;
+        if (detailRes.detail.untrustedAdContent) {
+          targetItem.untrustedAdContent = detailRes.detail.untrustedAdContent;
+          if (
+            detailRes.detail.untrustedAdContent.extractionStatus === 'UPSTREAM_RATE_LIMITED' ||
+            detailRes.detail.untrustedAdContent.contentJsFetchStatus === 'UPSTREAM_RATE_LIMITED'
+          ) {
+            rateLimitedInEnrich = true;
+          }
+        }
+      }
+    }
+  }
+
+  const extractedCount = uniqueExtractedItems.length;
+
+  // Filter out items already charged, delivered, or marked unknown in prior checkpoint
+  const newBillableCandidates = uniqueExtractedItems.filter(
+    (item) =>
+      !chargedSet.has(item.creativeId) &&
+      !deliveredSet.has(item.creativeId) &&
+      !unknownOutcomeSet.has(item.creativeId)
+  );
+
+  if (newBillableCandidates.length === 0 && reconciledItems.length === 0) {
+    const durationMs = Math.max(1, nowMs() - startedAtMs);
+    return finalizeActorReturn({
+      ok: true,
+      status: 'EMPTY_RESULT',
+      billingMode,
+      queryMeta: entityRes.queryMeta,
+      selectedEntities: entityRes.selectedEntities,
+      items: [],
+      extractedCount,
+      deliveredCount,
+      billableCount: 0,
+      chargedEventCount: hasChargeHook ? chargedSet.size : 0,
+      unknownOutcomeIds: Array.from(unknownOutcomeSet),
+      chargeReceipts: [],
+      pagination: {
+        nextPageToken: creativesRes.nextPageToken,
+        paginationStatus: creativesRes.paginationStatus,
+        paginationIncompleteReason: creativesRes.paginationIncompleteReason,
+        pagesFetched: creativesRes.pagesFetched,
+      },
+      cursorResumeContext: creativesRes.cursorResumeContext,
+      telemetry: computeRunEconomicsTelemetry({
+        billableCount: 0,
+        chargedEventCount: hasChargeHook ? chargedSet.size : 0,
+        durationMs,
+        requestCount: Math.max(1, totalRpcRequests),
+      }),
+    });
+  }
+
+  // Step 4: Chunked Dataset Push (25 items/chunk) & Crash-Safe Event Charging
+  const chunkSize = ACTOR_PRICING_CONTRACT.chunkSize;
+  const chargeReceipts = [];
+  const newlyDeliveredItems = [];
+  let chargedEventCount = hasChargeHook ? chargedSet.size : 0;
+  let finalStatus = 'OK';
+  let finalOk = true;
+  let haltReason = undefined;
+  const runtimeWarnings = Array.isArray(creativesRes.warnings) ? [...creativesRes.warnings] : [];
+  const persistCheckpointPostCharge = async () => {
+    try {
+      await persistCheckpoint();
+    } catch (cpErr) {
+      runtimeWarnings.push(
+        `Post-charge checkpoint write warning: ${cpErr?.message || String(cpErr)}`
+      );
+    }
+  };
+
+  for (let offset = 0; offset < newBillableCandidates.length; offset += chunkSize) {
+    const effectiveChunkDeadlineMs = hasChargeHook
+      ? deadlineAtMs - step4ReserveMs
+      : deadlineAtMs;
+    if (nowMs() >= effectiveChunkDeadlineMs) {
+      finalOk = newlyDeliveredItems.length > 0 || reconciledItems.length > 0;
+      finalStatus = 'DEADLINE_EXCEEDED_BEFORE_CHARGE';
+      haltReason = 'Run deadline reserve reached prior to charging next chunk; halted cleanly before billing';
+      break;
+    }
+
+    const unchargedChunk = newBillableCandidates
+      .slice(offset, offset + chunkSize)
+      .filter(
+        (c) =>
+          !chargedSet.has(c.creativeId) &&
+          !deliveredSet.has(c.creativeId) &&
+          !unknownOutcomeSet.has(c.creativeId)
+      );
+
+    if (unchargedChunk.length === 0) {
+      continue;
+    }
+
+    const chunkIds = unchargedChunk.map((c) => c.creativeId);
+    const idempotencyKey = computeChunkIdempotencyKey(runId, chunkIds);
+
+    if (!hasChargeHook) {
+      // Local / MCP unbilled execution mode: deliver items with chargedEventCount = 0
+      const pushRes = await pushDataWithRetry(unchargedChunk);
+      if (!pushRes.ok) {
+        await persistCheckpointPostCharge();
+        finalOk = false;
+        finalStatus = 'PARTIAL_BILLING_HALT';
+        haltReason = `Dataset pushData failed in local mode: ${pushRes.error?.message || String(pushRes.error)}`;
+        break;
+      }
+      for (const c of unchargedChunk) {
+        deliveredSet.add(c.creativeId);
+        newlyDeliveredItems.push(c);
+      }
+      deliveredCount = deliveredSet.size;
+      await persistCheckpointPostCharge();
+      continue;
+    }
+
+    // Step 4.1: Persist inFlightIds and stagedItemsById BEFORE invoking chargeEvent
+    inFlightSet = new Set(chunkIds);
+    for (const c of unchargedChunk) {
+      stagedItemsById[c.creativeId] = c;
+    }
+    try {
+      await persistCheckpoint();
+    } catch (preCpErr) {
+      inFlightSet = new Set();
+      finalOk = false;
+      finalStatus = 'PARTIAL_BILLING_HALT';
+      haltReason = `Pre-charge checkpoint write failed before billing: ${preCpErr?.message || String(preCpErr)}`;
+      break;
+    }
+
+    if (nowMs() >= effectiveChunkDeadlineMs) {
+      inFlightSet = new Set();
+      await persistCheckpointPostCharge();
+      finalOk = newlyDeliveredItems.length > 0 || reconciledItems.length > 0;
+      finalStatus = 'DEADLINE_EXCEEDED_BEFORE_CHARGE';
+      haltReason =
+        'Run deadline reserve reached immediately after pre-charge checkpoint write; cleared inFlightIds and halted before billing';
+      break;
+    }
+
+    const receipt = {
+      idempotencyKey,
+      eventName: ACTOR_PRICING_CONTRACT.eventName,
+      count: unchargedChunk.length,
+      unitPriceUsdc: ACTOR_PRICING_CONTRACT.priceUsdc,
+      chunkAmountUsdc: Number(
+        (unchargedChunk.length * ACTOR_PRICING_CONTRACT.priceUsdc).toFixed(6)
+      ),
+      creativeIds: chunkIds,
+    };
+
+    let chargeResult;
+    try {
+      chargeResult = await hooks.chargeEvent(receipt);
+    } catch (chargeErr) {
+      for (const id of chunkIds) {
+        unknownOutcomeSet.add(id);
+      }
+      inFlightSet = new Set();
+      await persistCheckpointPostCharge();
+      finalOk = false;
+      finalStatus = 'PARTIAL_BILLING_HALT';
+      haltReason = `chargeEvent threw error: ${chargeErr?.message || String(chargeErr)}`;
+      break;
+    }
+
+    // Step 4.2: Strict ChargeResult validation (never fallback to ?? unchargedChunk.length)
+    const chargedCount = chargeResult?.chargedCount;
+    const eventChargeLimitReached = Boolean(chargeResult?.eventChargeLimitReached);
+
+    if (
+      !chargeResult ||
+      typeof chargeResult !== 'object' ||
+      !Number.isInteger(chargedCount) ||
+      chargedCount < 0 ||
+      chargedCount > unchargedChunk.length
+    ) {
+      for (const id of chunkIds) {
+        unknownOutcomeSet.add(id);
+      }
+      inFlightSet = new Set();
+      await persistCheckpointPostCharge();
+      finalOk = false;
+      finalStatus = 'PARTIAL_BILLING_HALT';
+      haltReason =
+        'chargeEvent returned invalid or missing integer chargedCount (transitioned chunk to UNKNOWN_CHARGE_OUTCOME)';
+      break;
+    }
+
+    // Step 4.3: Branch on validated chargedCount
+    if (chargedCount === unchargedChunk.length) {
+      // Full chunk charged: persist chargedIds immediately BEFORE pushData (best-effort so KVS glitch never blocks delivery)
+      for (const id of chunkIds) {
+        chargedSet.add(id);
+      }
+      inFlightSet = new Set();
+      chargedEventCount = chargedSet.size;
+      await persistCheckpointPostCharge();
+
+      const pushRes = await pushDataWithRetry(unchargedChunk);
+      if (!pushRes.ok) {
+        chargeReceipts.push({
+          ...receipt,
+          chargedCount,
+          eventChargeLimitReached,
+        });
+        finalOk = false;
+        finalStatus = 'PARTIAL_BILLING_HALT';
+        haltReason = `Dataset pushData failed after charge (paid items preserved in KVS checkpoint stagedItemsById): ${pushRes.error?.message || String(pushRes.error)}`;
+        break;
+      }
+      for (const c of unchargedChunk) {
+        deliveredSet.add(c.creativeId);
+        newlyDeliveredItems.push(c);
+      }
+      deliveredCount = deliveredSet.size;
+      await persistCheckpointPostCharge();
+
+      chargeReceipts.push({
+        ...receipt,
+        chargedCount,
+        eventChargeLimitReached,
+      });
+
+      if (eventChargeLimitReached) {
+        finalStatus = 'CHARGE_LIMIT_REACHED';
+        break;
+      }
+    } else if (chargedCount === 0) {
+      inFlightSet = new Set();
+      await persistCheckpointPostCharge();
+      chargeReceipts.push({
+        ...receipt,
+        chargedCount: 0,
+        eventChargeLimitReached,
+      });
+      if (eventChargeLimitReached) {
+        finalOk = true;
+        finalStatus = 'CHARGE_LIMIT_REACHED';
+      } else {
+        finalOk = false;
+        finalStatus = 'PARTIAL_BILLING_HALT';
+        haltReason = 'chargeEvent returned chargedCount = 0 without eventChargeLimitReached';
+      }
+      break;
+    } else {
+      // Partial chunk charge (0 < chargedCount < unchargedChunk.length)
+      const explicitChargedIds = Array.isArray(chargeResult.chargedCreativeIds)
+        ? chargeResult.chargedCreativeIds.filter((id) => chunkIds.includes(id))
+        : null;
+
+      if (explicitChargedIds && explicitChargedIds.length === chargedCount) {
+        for (const id of explicitChargedIds) {
+          chargedSet.add(id);
+        }
+        inFlightSet = new Set();
+        chargedEventCount = chargedSet.size;
+        await persistCheckpointPostCharge();
+
+        const paidSubset = unchargedChunk.filter((c) => explicitChargedIds.includes(c.creativeId));
+        const pushRes = await pushDataWithRetry(paidSubset);
+        if (!pushRes.ok) {
+          chargeReceipts.push({
+            ...receipt,
+            chargedCount,
+            chargedCreativeIds: explicitChargedIds,
+            eventChargeLimitReached,
+          });
+          finalOk = false;
+          finalStatus = 'PARTIAL_BILLING_HALT';
+          haltReason = `Dataset pushData failed after partial charge (paid items preserved in KVS checkpoint stagedItemsById): ${pushRes.error?.message || String(pushRes.error)}`;
+          break;
+        }
+        for (const c of paidSubset) {
+          deliveredSet.add(c.creativeId);
+          newlyDeliveredItems.push(c);
+        }
+        deliveredCount = deliveredSet.size;
+        await persistCheckpointPostCharge();
+
+        chargeReceipts.push({
+          ...receipt,
+          chargedCount,
+          chargedCreativeIds: explicitChargedIds,
+          eventChargeLimitReached,
+        });
+
+        finalOk = eventChargeLimitReached;
+        finalStatus = eventChargeLimitReached ? 'CHARGE_LIMIT_REACHED' : 'PARTIAL_BILLING_HALT';
+        if (!eventChargeLimitReached) {
+          haltReason = `Partial chunk charge (${chargedCount}/${unchargedChunk.length}) without charge limit flag`;
+        }
+        break;
+      } else if (eventChargeLimitReached) {
+        // Standard Apify SDK ChargeResult when hitting user's max charge ceiling:
+        // Attribute charge deterministically to the ordered prefix `unchargedChunk.slice(0, chargedCount)`
+        // so the customer receives every item they paid for, and leave the remaining tail uncharged.
+        const paidPrefix = unchargedChunk.slice(0, chargedCount);
+        const paidPrefixIds = paidPrefix.map((c) => c.creativeId);
+        for (const id of paidPrefixIds) {
+          chargedSet.add(id);
+        }
+        inFlightSet = new Set();
+        chargedEventCount = chargedSet.size;
+        await persistCheckpointPostCharge();
+
+        const pushRes = await pushDataWithRetry(paidPrefix);
+        if (!pushRes.ok) {
+          chargeReceipts.push({
+            ...receipt,
+            chargedCount,
+            chargedCreativeIds: paidPrefixIds,
+            eventChargeLimitReached: true,
+          });
+          finalOk = false;
+          finalStatus = 'PARTIAL_BILLING_HALT';
+          haltReason = `Dataset pushData failed after charge limit prefix (paid items preserved in KVS checkpoint stagedItemsById): ${pushRes.error?.message || String(pushRes.error)}`;
+          break;
+        }
+        for (const c of paidPrefix) {
+          deliveredSet.add(c.creativeId);
+          newlyDeliveredItems.push(c);
+        }
+        deliveredCount = deliveredSet.size;
+        await persistCheckpointPostCharge();
+
+        chargeReceipts.push({
+          ...receipt,
+          chargedCount,
+          chargedCreativeIds: paidPrefixIds,
+          eventChargeLimitReached: true,
+        });
+
+        finalOk = true;
+        finalStatus = 'CHARGE_LIMIT_REACHED';
+        break;
+      } else {
+        // Unexpected partial count without eventChargeLimitReached and without explicit IDs ->
+        // move chunk to unknownOutcomeIds and halt fail-closed
+        for (const id of chunkIds) {
+          unknownOutcomeSet.add(id);
+        }
+        inFlightSet = new Set();
+        chargedEventCount = chargedSet.size + chargedCount;
+        await persistCheckpointPostCharge();
+
+        chargeReceipts.push({
+          ...receipt,
+          chargedCount,
+          eventChargeLimitReached: false,
+        });
+
+        finalOk = false;
+        finalStatus = 'PARTIAL_BILLING_HALT';
+        haltReason = `Ambiguous partial chunk charge (${chargedCount}/${unchargedChunk.length}) without chargedCreativeIds attribution or eventChargeLimitReached`;
+        break;
+      }
+    }
+  }
+
+  // Step 5: Rewind pagination cursor if billing halted or reached charge limit before delivering all extracted items
+  let effectiveNextPageToken = creativesRes.nextPageToken;
+  let effectivePaginationStatus = creativesRes.paginationStatus;
+  let effectiveIncompleteReason = creativesRes.paginationIncompleteReason;
+  const undeliveredCount = Math.max(0, newBillableCandidates.length - newlyDeliveredItems.length);
+
+  if (undeliveredCount > 0) {
+    const firstUndeliveredItem = newBillableCandidates.find((c) => !deliveredSet.has(c.creativeId));
+    const firstUndeliveredExtractedIdx = Array.isArray(creativesRes.creatives)
+      ? creativesRes.creatives.findIndex((c) => c.creativeId === firstUndeliveredItem?.creativeId)
+      : -1;
+    const effectiveDeliveredPrefixLen =
+      firstUndeliveredExtractedIdx >= 0 ? firstUndeliveredExtractedIdx : newlyDeliveredItems.length;
+    effectiveNextPageToken = computeRewoundCursorForDeliveredPrefix(
+      creativesRes.cursorResumeContext,
+      effectiveDeliveredPrefixLen,
+      creativesRes.nextPageToken
+    );
+    effectivePaginationStatus =
+      finalStatus === 'CHARGE_LIMIT_REACHED'
+        ? 'CHARGE_LIMIT_REACHED_HAS_MORE'
+        : finalStatus === 'DEADLINE_EXCEEDED_BEFORE_CHARGE'
+          ? 'DEADLINE_EXCEEDED_HAS_MORE'
+          : 'PARTIAL_BILLING_HALT';
+    effectiveIncompleteReason = finalStatus;
+  }
+
+  const paginationMeta = {
+    nextPageToken: effectiveNextPageToken,
+    paginationStatus: effectivePaginationStatus,
+    paginationIncompleteReason: effectiveIncompleteReason,
+    pagesFetched: creativesRes.pagesFetched,
+    ...(runtimeWarnings.length > 0 ? { warnings: runtimeWarnings } : {}),
+    ...(undeliveredCount > 0 ? { undeliveredCount } : {}),
+  };
+
+  // Merge reconciled items + newly delivered items with strict creativeId deduplication
+  const allOutputItems = [];
+  const outputSeenIds = new Set();
+  for (const item of [...reconciledItems, ...newlyDeliveredItems]) {
+    if (item?.creativeId && !outputSeenIds.has(item.creativeId)) {
+      outputSeenIds.add(item.creativeId);
+      allOutputItems.push(item);
+    }
+  }
+
+  const simulatedBillableCount = hasChargeHook ? chargedEventCount : allOutputItems.length;
+  const durationMs = Math.max(1, nowMs() - startedAtMs);
+  const telemetry = computeRunEconomicsTelemetry({
+    billableCount: simulatedBillableCount,
+    chargedEventCount,
+    durationMs,
+    requestCount: Math.max(1, totalRpcRequests),
+  });
+
+  return finalizeActorReturn({
+    ok: finalOk,
+    status: finalStatus,
+    reason: haltReason,
+    billingMode,
+    queryMeta: entityRes.queryMeta,
+    selectedEntities: entityRes.selectedEntities,
+    items: allOutputItems,
+    extractedCount,
+    deliveredCount,
+    billableCount: simulatedBillableCount,
+    chargedEventCount,
+    unknownOutcomeIds: Array.from(unknownOutcomeSet),
+    chargeReceipts,
+    pagination: paginationMeta,
+    ...(runtimeWarnings.length > 0 ? { warnings: runtimeWarnings } : {}),
+    cursorResumeContext: creativesRes.cursorResumeContext,
+    telemetry,
+  });
+}