@sellable/mcp 0.1.614 → 0.1.615-wip.121.2

package/dist/tools/refill-executors.js

@@ -44,6 +44,51 @@ const USABLE_PAID_INMAIL_REFRESH_RECEIPT_STATUSES = new Set([
     "refreshed",
     "below_threshold",
 ]);
+const PROVIDER_REFERENCE_ORIGINS = new Set([
+    "config_import_job",
+    "exact_table_job",
+    "find_leads_run",
+]);
+/**
+ * The sole compact provider-lineage decoder used at both the MCP packet and
+ * executor boundaries. Legacy loose searchId/provider fields never satisfy
+ * this contract.
+ */
+export function sanitizeProviderSearchReference(value) {
+    const reference = recordValue(value);
+    const owner = recordValue(reference?.owner);
+    const workspaceId = stringValue(reference?.workspaceId);
+    const provider = stringValue(reference?.provider);
+    const sourceTableId = stringValue(reference?.sourceTableId);
+    const searchId = stringValue(reference?.searchId);
+    const resolutionOrigin = stringValue(reference?.resolutionOrigin);
+    const ownerKind = stringValue(owner?.kind);
+    const ownerId = stringValue(owner?.id);
+    const basisFingerprint = stringValue(reference?.basisFingerprint);
+    if (!workspaceId ||
+        (provider !== "sales-nav" && provider !== "prospeo") ||
+        !sourceTableId ||
+        !searchId ||
+        !resolutionOrigin ||
+        !PROVIDER_REFERENCE_ORIGINS.has(resolutionOrigin) ||
+        (ownerKind !== "campaign" && ownerKind !== "find_leads_run") ||
+        !ownerId ||
+        !basisFingerprint) {
+        return null;
+    }
+    return {
+        workspaceId,
+        provider,
+        sourceTableId,
+        searchId,
+        resolutionOrigin: resolutionOrigin,
+        owner: {
+            kind: ownerKind,
+            id: ownerId,
+        },
+        basisFingerprint,
+    };
+}
 export function normalizeStrings(values) {
     if (!Array.isArray(values))
         return [];
@@ -1687,242 +1732,456 @@ export async function broadenSignalSearch(action, workspaceId) {
         },
     };
 }
-/**
- * Phase 110-05: bounded SAME-provider-source continuation for cold-outbound
- * Sales Nav / Prospeo campaigns. Mirrors continueSignalDiscoverySource's
- * guardrails (campaign + provider + selected-source match) and reuses the
- * EXISTING import_leads tool to add leads from the campaign's own saved
- * provider search (mode "add") once eligible/prepared rows are receipt-proven
- * exhausted. It never switches source families and never creates a campaign.
- * The add is bounded by the packet's existing sourceRowLimit cap; when the
- * packet carries no reusable provider search reference the add cannot start
- * autonomously and the executor refuses with a bounded reason so the run
- * records the attempt instead of looping on an unchanged mutation.
- */
-export async function continueProviderSource(action, workspaceId) {
-    const type = stringValue(action.type);
-    const campaignOfferId = actionCampaignId(action);
-    const sourceLeadListId = actionSourceLeadListId(action);
-    const sourceFingerprint = actionSourceFingerprint(action);
+function providerOutcomeAttempt(outcome, result = {}) {
+    return {
+        status: outcome.class === "executed" ? "executed_and_reread" : "refused",
+        ...(outcome.class === "executed"
+            ? {}
+            : { refusalReason: `${outcome.code}: ${outcome.detail}` }),
+        providerOutcome: outcome,
+        result: { ...result, providerOutcome: outcome },
+    };
+}
+function providerActionIdentity(action) {
     const toolInput = actionToolInput(action);
-    const packetProvider = stringValue(toolInput.provider);
-    // The owner directive authorizes cold same-source continuation for Sales Nav
-    // OR Prospeo only. continue_prospeo_source also spans apollo-sourced
-    // campaigns, which are NOT an authorized cold yolo source — refuse those.
-    const provider = type === "continue_sales_nav_source"
-        ? "sales-nav"
-        : type === "continue_prospeo_source" &&
-            packetProvider !== "apollo" &&
-            packetProvider !== "apollo-ai"
-            ? "prospeo"
-            : null;
-    if (!provider) {
-        return {
-            status: "refused",
-            refusalReason: "continue_provider_source only runs bounded same-source adds for Sales Nav or Prospeo cold campaigns",
-        };
-    }
-    if (!campaignOfferId || !sourceLeadListId || !sourceFingerprint) {
-        return {
-            status: "refused",
-            refusalReason: `${type} action is missing campaignOfferId, sourceLeadListId, or sourceFingerprint`,
-        };
-    }
-    const api = getApi();
-    const requestOptions = workspaceRequestOptions(workspaceId);
-    const campaign = await api.get(`/api/v2/campaign-offers/${campaignOfferId}`, requestOptions);
-    const campaignProvider = campaign.leadSourceProvider ?? null;
-    const providerMatches = provider === "sales-nav"
-        ? campaignProvider === "sales-nav"
-        : campaignProvider === "prospeo";
-    if (!providerMatches) {
+    return {
+        actionKey: stringValue(action.actionKey),
+        effectId: stringValue(action.effectId) ?? stringValue(toolInput.effectId),
+    };
+}
+function exactProviderReferenceFromAction(action) {
+    const rawReferences = [
+        action.providerSearchReference,
+        actionToolInput(action).providerSearchReference,
+        actionIds(action).providerSearchReference,
+    ].filter((value) => value !== undefined && value !== null);
+    if (rawReferences.length === 0)
+        return null;
+    const references = rawReferences.map(sanitizeProviderSearchReference);
+    if (references.some((reference) => !reference))
+        return null;
+    const [first, ...rest] = references;
+    const fingerprint = JSON.stringify(first);
+    return rest.every((reference) => JSON.stringify(reference) === fingerprint)
+        ? first
+        : null;
+}
+function providerFacts(params) {
+    return {
+        provider: params.provider,
+        workspaceId: params.workspaceId,
+        campaignOfferId: params.campaignOfferId,
+        sourceLeadListId: params.sourceLeadListId,
+        searchId: params.reference?.searchId ?? null,
+        resolutionOrigin: params.reference?.resolutionOrigin ?? null,
+        owner: params.reference?.owner ?? null,
+        basisFingerprint: params.reference?.basisFingerprint ?? null,
+        actionKey: params.actionKey,
+        effectId: params.effectId,
+    };
+}
+function authorizationOutcome(status, facts) {
+    return {
+        class: "authorization_blocker",
+        code: status === 401
+            ? "provider_authorization_global"
+            : "provider_authorization_workspace",
+        detail: status === 401
+            ? "Provider authorization is unavailable globally."
+            : "Provider authorization is unavailable for this workspace scope.",
+        scope: status === 401 ? "global" : "workspace",
+        status,
+        facts,
+    };
+}
+function numericFact(record, key) {
+    const value = numberValue(record[key]);
+    return value === null ? null : Math.max(0, value);
+}
+function classifyReconciledProviderJob(params) {
+    const status = params.status.toUpperCase();
+    const jobFacts = {
+        ...params.facts,
+        jobId: params.jobId,
+        jobStatus: status,
+        totalPages: numericFact(params.job, "totalPages"),
+        fetchedPages: numericFact(params.job, "fetchedPages"),
+        totalLeads: numericFact(params.job, "totalLeads"),
+        fetchedLeads: numericFact(params.job, "fetchedLeads"),
+        existingRows: numericFact(params.progress, "existingRows"),
+        requestedRows: numericFact(params.progress, "requestedRows"),
+        processed: numericFact(params.progress, "processed"),
+        leadsImported: numericFact(params.progress, "leadsImported"),
+        sourceRows: numericFact(params.progress, "sourceRows"),
+        uniqueRows: numericFact(params.progress, "uniqueRows"),
+        duplicateRowsSkipped: numericFact(params.progress, "duplicateRowsSkipped"),
+        invalidRows: numericFact(params.progress, "invalidRows"),
+    };
+    if (["PENDING", "FETCHING", "PROCESSING", "QUEUED", "RUNNING"].includes(status)) {
         return {
-            status: "refused",
-            refusalReason: `campaign leadSourceProvider (${String(campaignProvider)}) is not ${provider}; refusing same-source continuation`,
+            class: "executed",
+            code: "provider_job_reconciled_active",
+            detail: "An exact active provider job is attached to this source table.",
+            jobId: params.jobId,
+            facts: jobFacts,
         };
     }
-    if (campaign.selectedLeadListId &&
-        campaign.selectedLeadListId !== sourceLeadListId) {
+    if (["FAILED", "ERROR", "CANCELLED", "CANCELED"].includes(status)) {
         return {
-            status: "refused",
-            refusalReason: "campaign selectedLeadListId changed since the plan packet; rerun get_refill_target_plan before source continuation",
+            class: "transient",
+            code: "provider_job_terminal_failure",
+            detail: "The exact provider job ended without a successful import receipt.",
+            retryable: true,
+            facts: jobFacts,
         };
     }
-    // Bound the same-source add by the packet's existing sourceRowLimit cap.
-    const sourceRowLimit = Math.min(PROVIDER_SOURCE_CONTINUATION_MAX_ROWS, Math.max(1, Math.floor(numberValue(toolInput.sourceRowLimit) ??
-        numberValue(toolInput.targetLeadCount) ??
-        numberValue(toolInput.targetRows) ??
-        numberValue(action.targetRows) ??
-        PROVIDER_SOURCE_CONTINUATION_DEFAULT_ROWS)));
-    // Reuse the campaign's SAME saved provider search reference; never widen to a
-    // different source family. Without a reusable reference the same-source add
-    // cannot start autonomously.
-    const searchId = stringValue(toolInput.searchId);
-    if (!searchId) {
+    const completed = [
+        "COMPLETED",
+        "COMPLETE",
+        "SUCCESS",
+        "SUCCEEDED",
+        "DONE",
+    ].includes(status);
+    if (!completed) {
         return {
-            status: "refused",
-            refusalReason: `${provider} same-source continuation requires a reusable provider search reference on the packet; none was surfaced`,
-            result: {
-                provider,
-                campaignOfferId,
-                sourceLeadListId,
-                sourceFingerprint,
-            },
+            class: "uncertain_effect",
+            code: "provider_job_status_unknown",
+            detail: "The exact provider job exists but its status is not recognized.",
+            facts: jobFacts,
         };
     }
-    markProviderPromptLoaded({ provider, campaignOfferId });
-    const importResult = await importLeads({
-        campaignOfferId,
-        provider,
-        sourceLeadListId,
-        searchId,
-        mode: "add",
-        targetLeadCount: sourceRowLimit,
-        confirmed: true,
-        ...(workspaceId ? { workspaceId } : {}),
-    });
-    const importRecord = recordValue(importResult);
-    if (importRecord?.error || importRecord?.needsModeSelection === true) {
+    const totalPages = jobFacts.totalPages;
+    const fetchedPages = jobFacts.fetchedPages;
+    const totalLeads = jobFacts.totalLeads;
+    const fetchedLeads = jobFacts.fetchedLeads;
+    const existingRows = jobFacts.existingRows;
+    const leadsImported = jobFacts.leadsImported;
+    const processed = jobFacts.processed;
+    const sourceRows = jobFacts.sourceRows;
+    const uniqueRows = jobFacts.uniqueRows;
+    const duplicates = jobFacts.duplicateRowsSkipped;
+    const invalidRows = jobFacts.invalidRows;
+    const netNew = existingRows !== null && leadsImported !== null
+        ? Math.max(0, leadsImported - existingRows)
+        : null;
+    const paginationComplete = totalPages !== null && fetchedPages !== null && fetchedPages >= totalPages;
+    const processedNew = existingRows !== null && processed !== null
+        ? Math.max(0, processed - existingRows)
+        : null;
+    const zeroUniverse = totalLeads === 0 || fetchedLeads === 0;
+    const allRejected = (sourceRows !== null && uniqueRows === 0) ||
+        (processedNew !== null &&
+            processedNew > 0 &&
+            (duplicates ?? 0) + (invalidRows ?? 0) >= processedNew);
+    const zeroEligibleNetNew = netNew === 0 || zeroUniverse || allRejected;
+    if (paginationComplete && zeroEligibleNetNew) {
         return {
-            status: "refused",
-            refusalReason: stringValue(importRecord?.message) ??
-                `${provider} same-source import did not start a bounded add job`,
-            result: { provider, campaignOfferId, sourceLeadListId, importResult },
+            class: "source_terminal",
+            code: "provider_pagination_exhausted",
+            detail: "Completed provider pagination proved zero remaining eligible net-new yield.",
+            facts: { ...jobFacts, netNewRows: netNew ?? 0, paginationComplete: true },
         };
     }
     return {
-        status: "executed_and_reread",
-        result: {
-            provider,
-            campaignOfferId,
-            previousSourceLeadListId: sourceLeadListId,
-            sourceFingerprint,
-            searchId,
-            sourceRowLimit,
-            importResult,
-        },
+        class: "executed",
+        code: netNew !== null && netNew > 0
+            ? "provider_job_partial_or_positive_yield"
+            : "provider_job_completed_replan",
+        detail: netNew !== null && netNew > 0
+            ? "The provider job produced net-new rows; replan from the refreshed source."
+            : "The provider job completed without sufficient facts to prove source exhaustion; replan without consuming the source.",
+        jobId: params.jobId,
+        facts: { ...jobFacts, netNewRows: netNew, paginationComplete },
     };
 }
-/**
- * feat(110-23a): rung 3 of the automatic escalation ladder — bounded provider
- * search broadening. When rungs 1-2 (same-source refill + cold continuation) are
- * receipt-proven exhausted at the current search depth and schedulable capacity
- * remains, this re-runs the campaign's EXISTING provider saved search one bounded
- * notch wider. It does NOT invent provider filter semantics: the "notch" is a
- * deeper page/depth window on the SAME searchId, expressed as a larger bounded
- * targetLeadCount into the same saved search via the EXISTING import_leads path
- * continueProviderSource already uses (mode "add"). One notch per campaign per run
- * (the loop enforces the run-scoped bound). The receipt records prior depth, new
- * depth, and the widened window; the actual rows gained surface on the next replan.
- * Never switches source families, never creates a campaign, never sends.
- */
-export async function broadenProviderSearch(action, workspaceId) {
-    const campaignOfferId = actionCampaignId(action);
-    const sourceLeadListId = actionSourceLeadListId(action);
-    const sourceFingerprint = actionSourceFingerprint(action);
+async function reconcileExactProviderJob(params) {
+    const api = getApi();
+    const requestOptions = workspaceRequestOptions(params.workspaceId);
+    try {
+        const meta = await api.get(`/api/v3/workflow-tables/${encodeURIComponent(params.sourceLeadListId)}?mode=meta`, requestOptions);
+        const table = recordValue(meta.table);
+        const tableWorkspaceId = stringValue(table?.workspaceId);
+        const config = recordValue(table?.config) ?? {};
+        const jobId = stringValue(config.importJobId);
+        const importProvider = stringValue(config.importProvider);
+        if ((tableWorkspaceId && tableWorkspaceId !== params.workspaceId) ||
+            importProvider !== params.provider ||
+            !jobId ||
+            (params.candidateJobId && params.candidateJobId !== jobId)) {
+            return null;
+        }
+        const path = params.provider === "sales-nav"
+            ? `/api/v3/sales-nav/export?jobId=${encodeURIComponent(jobId)}`
+            : `/api/v3/lead-lists/${encodeURIComponent(params.sourceLeadListId)}/prospeo-import/status?jobId=${encodeURIComponent(jobId)}`;
+        const response = await api.get(path, requestOptions);
+        const job = recordValue(response.job) ?? response;
+        if (stringValue(job.id) !== jobId)
+            return null;
+        const status = stringValue(job.status);
+        if (!status)
+            return null;
+        if (params.activeOnly &&
+            !["PENDING", "FETCHING", "PROCESSING", "QUEUED", "RUNNING"].includes(status.toUpperCase())) {
+            return null;
+        }
+        return classifyReconciledProviderJob({
+            jobId,
+            status,
+            job,
+            progress: recordValue(config.importProgress) ?? {},
+            facts: params.facts,
+        });
+    }
+    catch {
+        return null;
+    }
+}
+function candidateJobIdFromError(error) {
+    const body = apiErrorBody(error);
+    if (!body)
+        return null;
+    try {
+        return stringValue(recordValue(JSON.parse(body))?.jobId);
+    }
+    catch {
+        return null;
+    }
+}
+/** Shared continuation/broadening saved-search executor and classifier. */
+export async function executeProviderSavedSearch(action, workspaceId, mode) {
+    const type = stringValue(action.type);
     const toolInput = actionToolInput(action);
     const packetProvider = stringValue(toolInput.provider);
-    // Broadening is only automatic for Sales Nav / Prospeo saved searches, mirroring
-    // the cold-continuation authority. apollo-sourced campaigns stay manual.
-    const provider = packetProvider === "sales-nav"
+    const provider = type === "continue_sales_nav_source" || packetProvider === "sales-nav"
         ? "sales-nav"
-        : packetProvider === "prospeo"
+        : type === "continue_prospeo_source" || packetProvider === "prospeo"
             ? "prospeo"
             : null;
     if (!provider) {
-        return {
-            status: "refused",
-            refusalReason: "broaden_provider_search only broadens Sales Nav or Prospeo saved searches",
+        const outcome = {
+            class: "source_terminal",
+            code: "provider_search_lineage_unusable",
+            detail: "The action does not identify a supported saved-search provider.",
+            facts: { actionType: type, provider: packetProvider },
         };
+        return providerOutcomeAttempt(outcome);
     }
-    if (!campaignOfferId || !sourceLeadListId || !sourceFingerprint) {
-        return {
-            status: "refused",
-            refusalReason: "broaden_provider_search action is missing campaignOfferId, sourceLeadListId, or sourceFingerprint",
-        };
+    const campaignOfferId = actionCampaignId(action);
+    const sourceLeadListId = actionSourceLeadListId(action);
+    const reference = exactProviderReferenceFromAction(action);
+    const identity = providerActionIdentity(action);
+    const facts = providerFacts({
+        provider,
+        workspaceId: workspaceId ?? null,
+        campaignOfferId,
+        sourceLeadListId,
+        reference,
+        ...identity,
+    });
+    const ownerMatches = reference
+        ? reference.owner.kind === "campaign"
+            ? reference.owner.id === campaignOfferId
+            : reference.owner.id === sourceLeadListId
+        : false;
+    if (!workspaceId ||
+        !campaignOfferId ||
+        !sourceLeadListId ||
+        !reference ||
+        !identity.actionKey ||
+        !identity.effectId ||
+        reference.provider !== provider ||
+        reference.sourceTableId !== sourceLeadListId ||
+        !ownerMatches) {
+        return providerOutcomeAttempt({
+            class: "source_terminal",
+            code: "provider_search_lineage_unusable",
+            detail: "Exact workspace/provider/source/search/owner lineage and actionKey/effectId are required before provider execution.",
+            facts,
+        });
     }
-    // Reuse the campaign's SAME saved provider search reference; never widen to a
-    // different source family. Without a reusable reference broadening cannot run.
-    const searchId = stringValue(toolInput.searchId);
-    if (!searchId) {
-        return {
-            status: "refused",
-            refusalReason: `${provider} search broadening requires a reusable provider saved-search reference on the packet; none was surfaced`,
-            result: {
-                provider,
-                campaignOfferId,
-                sourceLeadListId,
-                sourceFingerprint,
-            },
-        };
+    if (reference.workspaceId !== workspaceId) {
+        return providerOutcomeAttempt({
+            class: "stale_packet_replan",
+            code: "provider_workspace_changed",
+            detail: "The saved-search reference belongs to a different workspace.",
+            facts,
+        });
     }
     const api = getApi();
     const requestOptions = workspaceRequestOptions(workspaceId);
-    const campaign = await api.get(`/api/v2/campaign-offers/${campaignOfferId}`, requestOptions);
-    const campaignProvider = campaign.leadSourceProvider ?? null;
-    if (campaignProvider !== provider) {
-        return {
-            status: "refused",
-            refusalReason: `campaign leadSourceProvider (${String(campaignProvider)}) is not ${provider}; refusing search broadening`,
-        };
+    let campaign;
+    try {
+        campaign = await api.get(`/api/v2/campaign-offers/${campaignOfferId}`, requestOptions);
     }
-    if (campaign.selectedLeadListId &&
-        campaign.selectedLeadListId !== sourceLeadListId) {
-        return {
-            status: "refused",
-            refusalReason: "campaign selectedLeadListId changed since the plan packet; rerun get_refill_target_plan before broadening the provider search",
-        };
+    catch (error) {
+        const status = apiErrorStatus(error);
+        if (status === 401 || status === 403) {
+            return providerOutcomeAttempt(authorizationOutcome(status, facts));
+        }
+        if (status === 404) {
+            return providerOutcomeAttempt({
+                class: "stale_packet_replan",
+                code: "provider_campaign_missing",
+                detail: "The planned campaign no longer exists or is no longer visible.",
+                facts,
+            });
+        }
+        return providerOutcomeAttempt({
+            class: "transient",
+            code: "provider_preflight_unavailable",
+            detail: "Provider preflight could not read the current campaign.",
+            retryable: true,
+            facts: { ...facts, status },
+        });
     }
-    // Advance one depth notch: rung 2 consumed priorDepth (default 1); broadening
-    // requests the next deeper window (priorDepth + 1) into the SAME saved search.
-    const priorDepth = Math.max(1, Math.floor(numberValue(toolInput.priorSearchDepth) ?? 1));
-    const newDepth = priorDepth + 1;
-    const baseWindow = Math.max(1, Math.floor(numberValue(toolInput.targetLeadCount) ??
-        numberValue(toolInput.sourceRowLimit) ??
-        numberValue(action.targetRows) ??
-        PROVIDER_SOURCE_CONTINUATION_DEFAULT_ROWS));
-    // The wider notch reaches deeper into the same saved search's result window.
-    const broadenedTargetLeadCount = Math.min(PROVIDER_SEARCH_BROADEN_MAX_ROWS, baseWindow * newDepth);
-    markProviderPromptLoaded({ provider, campaignOfferId });
-    const importResult = await importLeads({
-        campaignOfferId,
+    if (campaign.leadSourceProvider !== provider ||
+        (campaign.selectedLeadListId &&
+            campaign.selectedLeadListId !== sourceLeadListId)) {
+        return providerOutcomeAttempt({
+            class: "stale_packet_replan",
+            code: "provider_source_changed",
+            detail: "The campaign provider or selected source changed after planning.",
+            facts: {
+                ...facts,
+                currentProvider: campaign.leadSourceProvider ?? null,
+                currentSourceLeadListId: campaign.selectedLeadListId ?? null,
+            },
+        });
+    }
+    const existing = await reconcileExactProviderJob({
         provider,
+        workspaceId,
         sourceLeadListId,
-        searchId,
-        mode: "add",
-        targetLeadCount: broadenedTargetLeadCount,
-        confirmed: true,
-        ...(workspaceId ? { workspaceId } : {}),
+        facts,
+        activeOnly: true,
     });
-    const importRecord = recordValue(importResult);
-    if (importRecord?.error || importRecord?.needsModeSelection === true) {
-        return {
-            status: "refused",
-            refusalReason: stringValue(importRecord?.message) ??
-                `${provider} search broadening did not start a bounded add job`,
-            result: { provider, campaignOfferId, sourceLeadListId, importResult },
-        };
+    if (existing)
+        return providerOutcomeAttempt(existing);
+    const baseTarget = Math.max(1, Math.floor(numberValue(toolInput.sourceRowLimit) ??
+        numberValue(toolInput.targetLeadCount) ??
+        numberValue(toolInput.targetRows) ??
+        numberValue(action.targetRows) ??
+        PROVIDER_SOURCE_CONTINUATION_DEFAULT_ROWS));
+    const priorDepth = Math.max(1, Math.floor(numberValue(toolInput.priorSearchDepth) ?? 1));
+    const targetLeadCount = mode === "broadening"
+        ? Math.min(PROVIDER_SEARCH_BROADEN_MAX_ROWS, baseTarget * (priorDepth + 1))
+        : Math.min(PROVIDER_SOURCE_CONTINUATION_MAX_ROWS, baseTarget);
+    markProviderPromptLoaded({ provider, campaignOfferId });
+    let importResult;
+    try {
+        importResult = await importLeads({
+            campaignOfferId,
+            provider,
+            sourceLeadListId,
+            searchId: reference.searchId,
+            mode: "add",
+            targetLeadCount,
+            confirmed: true,
+            workspaceId,
+        });
     }
-    const importCounts = recordValue(importRecord?.counts);
-    const rowsGained = numberValue(importCounts?.rows);
-    return {
-        status: "executed_and_reread",
-        result: {
+    catch (error) {
+        const status = apiErrorStatus(error);
+        if (status === 401 || status === 403) {
+            return providerOutcomeAttempt(authorizationOutcome(status, facts));
+        }
+        if (userAddedRowsLimitPayloadFromError(error)) {
+            return providerOutcomeAttempt({
+                class: "capacity",
+                code: "provider_table_capacity",
+                detail: "The selected source table cannot accept the bounded add.",
+                facts: {
+                    ...facts,
+                    capacity: userAddedRowsLimitPayloadFromError(error),
+                },
+            });
+        }
+        if (status === 404) {
+            return providerOutcomeAttempt({
+                class: "stale_packet_replan",
+                code: "provider_search_or_source_changed",
+                detail: "The saved search or source table changed after planning.",
+                facts,
+            });
+        }
+        if (status === 429) {
+            return providerOutcomeAttempt({
+                class: "transient",
+                code: "provider_rate_limited",
+                detail: "The provider rejected this bounded attempt due to rate limiting.",
+                retryable: true,
+                facts: { ...facts, status },
+            });
+        }
+        const candidateJobId = candidateJobIdFromError(error);
+        const reconciled = await reconcileExactProviderJob({
             provider,
-            campaignOfferId,
-            previousSourceLeadListId: sourceLeadListId,
-            sourceFingerprint,
-            searchId,
-            priorDepth,
-            newDepth,
-            broadenedTargetLeadCount,
-            // Rows gained by a widened async import surface on the next replan's row
-            // frontier; expose the synchronous count when the import path returns one.
-            rowsGained: rowsGained ?? null,
-            rowsGainedPending: rowsGained == null,
-            importResult,
+            workspaceId,
+            sourceLeadListId,
+            candidateJobId,
+            facts,
+        });
+        if (reconciled)
+            return providerOutcomeAttempt(reconciled);
+        if (status !== null && status >= 500) {
+            return providerOutcomeAttempt({
+                class: "transient",
+                code: "provider_outage",
+                detail: "The provider returned a server failure and no exact active job was found during reconciliation.",
+                retryable: true,
+                facts: { ...facts, status },
+            });
+        }
+        return providerOutcomeAttempt({
+            class: "uncertain_effect",
+            code: status === 409
+                ? "provider_conflict_unreconciled"
+                : "provider_timeout_or_crash_unreconciled",
+            detail: "The mutation may have started, but exact active-job reconciliation did not prove its effect.",
+            facts: { ...facts, status, candidateJobId },
+        });
+    }
+    const importRecord = recordValue(importResult) ?? {};
+    const jobId = stringValue(importRecord.jobId);
+    if (!jobId) {
+        const reconciled = await reconcileExactProviderJob({
+            provider,
+            workspaceId,
+            sourceLeadListId,
+            facts,
+        });
+        if (reconciled)
+            return providerOutcomeAttempt(reconciled, { importResult });
+        return providerOutcomeAttempt({
+            class: "uncertain_effect",
+            code: "provider_import_not_started",
+            detail: "The provider returned without a jobId and exact active-job reconciliation found no attributable job.",
+            facts,
+        }, { importResult });
+    }
+    const rowsGained = numberValue(recordValue(importRecord.counts)?.rows);
+    const outcome = {
+        class: "executed",
+        code: rowsGained !== null && rowsGained > 0
+            ? "provider_job_partial_or_positive_yield"
+            : "provider_job_started",
+        detail: "The provider returned a confirmed started jobId; replan from the refreshed source receipt.",
+        jobId,
+        facts: {
+            ...facts,
+            targetLeadCount,
+            priorSearchDepth: mode === "broadening" ? priorDepth : null,
+            newSearchDepth: mode === "broadening" ? priorDepth + 1 : null,
+            netNewRows: rowsGained,
         },
     };
+    return providerOutcomeAttempt(outcome, { importResult });
+}
+export async function continueProviderSource(action, workspaceId) {
+    return executeProviderSavedSearch(action, workspaceId, "continuation");
+}
+export async function broadenProviderSearch(action, workspaceId) {
+    return executeProviderSavedSearch(action, workspaceId, "broadening");
 }
 /**
  * feat(110-23b): rung 4 of the automatic escalation ladder — bounded, reversible