@sellable/mcp 0.1.793 → 0.1.794

package/dist/tools/refill-v3-campaign-work.js

@@ -0,0 +1,1015 @@
+/**
+ * Refill V3 selected-campaign traversal RUNTIME (Phase 146.5 Plan 09 T1,
+ * RV3PRM-001).
+ *
+ * This is AI seam #2's OWNED RUNTIME HOME (`A09-AI-SEAM-RUNTIME-HOME`). The
+ * markdown subskill supplies the model's judgment; this module is the
+ * deterministic authority that stands between that judgment and every product
+ * effect. It:
+ *
+ *  1. decodes the model's output into AT MOST ONE action drawn from the shared
+ *     `REFILL_V3_CAMPAIGN_ATTENTION_ACTIONS` constant — never a local list;
+ *  2. refuses connection-health evidence before any prompt work;
+ *  3. gates every action behind live-job absence with a BOUNDED wait;
+ *  4. enforces enrich-before-rubric structurally (incident 112k);
+ *  5. consumes the canonical diagnostic order VERBATIM so an enriched island
+ *     can never truncate traversal;
+ *  6. loads exactly ONE matching active provider prompt for a new provider
+ *     search and exactly ZERO on a drain;
+ *  7. falsifies an AI exhaustion claim through the shared exhaustion predicate;
+ *  8. dispatches EXACTLY ONE authority, validates its receipt, and forces the
+ *     exact sender/date two-lane re-observation before the iteration ends.
+ *
+ * The AI seam NEVER mutates. Every effect crosses `dispatchAuthority`, which the
+ * caller binds to an existing owner, and a second mutation from the same
+ * evidence packet is a closed typed failure.
+ *
+ * Package constraints (`A02-NO-ZOD`): no app `src/**` import, no validation
+ * library, hand-rolled guards only.
+ */
+import { REFILL_V3_CAMPAIGN_ATTENTION_ACTIONS, REFILL_V3_CAMPAIGN_ATTENTION_RESULTS, REFILL_V3_DIAGNOSTIC_SAMPLE_CAP, REFILL_V3_EXHAUSTION_PREDICATE, REFILL_V3_LEAD_SOURCE_FAMILIES, } from "./refill-v3-attention-packet-contract.js";
+// ───────────────────────────────────────────────────────────────────────────
+// ONE shared AI-output failure taxonomy for BOTH seams
+// ───────────────────────────────────────────────────────────────────────────
+/**
+ * The single closed taxonomy for "the model's output cannot be trusted".
+ * `refill-v3-waterfall.ts` IMPORTS this constant rather than forking a second
+ * AI-output framework (`A09-AI-SEAM-RUNTIME-HOME`, disposition D7).
+ *
+ * Every member is a VALUE, never a throw: a recoverable model error must not
+ * take the row down.
+ */
+export const REFILL_V3_AI_OUTPUT_FAILURES = [
+    "malformed_output",
+    "zero_actions",
+    "multiple_actions",
+    "duplicate_action",
+    "unsupported_action",
+    "stale_evidence",
+    "model_timeout",
+    "delegated_tool_timeout",
+    "receipt_incomplete",
+    "second_mutation_forbidden",
+];
+/** Deterministic REFUSALS that are about the world, not the model's syntax. */
+export const REFILL_V3_CAMPAIGN_WORK_REFUSALS = [
+    "foreign_scope",
+    "health_recheck_required",
+    "live_job_blocks_action",
+    "rubric_before_enrichment",
+    "rubric_before_viable_repair",
+    "provider_prompt_missing",
+    "provider_prompt_mismatch",
+    "provider_prompt_forbidden_on_drain",
+    "exhaustion_falsified",
+    "negative_set_replay",
+    "diagnostic_order_not_consumed",
+    "cohort_arithmetic_forbidden",
+    "template_meaning_requires_approval",
+];
+/**
+ * TRANSPORT MIRROR of the app-owned diagnostic scan-termination union
+ * (`src/lib/workflow-tables/campaign-cell-selectors.ts`). The published package
+ * may not import app source, so the mirror is declared here and DRIFT IS
+ * PINNED: `tests/mcp/refill-v3/campaign-work-validator.test.ts` asserts this
+ * tuple equals the app-owned union member-for-member.
+ *
+ * ONLY `frontier_exhausted` is exhaustion evidence (incident 112t).
+ */
+export const REFILL_V3_DIAGNOSTIC_TERMINATIONS = [
+    "frontier_exhausted",
+    "scan_budget_exhausted",
+    "limit_reached",
+];
+/** Connection-health reason codes Plan 10 must intercept BEFORE this seam. */
+export const REFILL_V3_HEALTH_REASON_CODES = [
+    "paid_inmail_connection_health_recheck_required",
+    "missing_balance",
+    "sender_connection_connecting",
+    "sender_connection_credentials",
+    "sender_disconnected",
+    "sales_nav_disconnected",
+];
+/** The bounded source modes. A drain loads NO provider prompt. */
+export const REFILL_V3_SOURCE_COMMAND_MODES = [
+    "new_provider_search",
+    "drain_imported",
+    "post_engager_continuation",
+];
+/**
+ * Cohort/batch keys the model may NEVER name. Sizing belongs to the existing
+ * `campaign-message-preparation` adaptive worker; a batch size in the model's
+ * command is a second selector by another name.
+ */
+export const REFILL_V3_FORBIDDEN_COMMAND_KEYS = [
+    "batchSize",
+    "cohortSize",
+    "limit",
+    "offset",
+    "rangeStart",
+    "rangeEnd",
+    "targetCount",
+    "retryCount",
+    "attempts",
+    "cursor",
+];
+/** The SEVEN reuse points a preparation delegation receipt must carry. */
+export const REFILL_V3_PREPARATION_REUSE_POINTS = [
+    "frontier",
+    "remainingGapPassEvidence",
+    "serialBatchCap",
+    "totalRowBudget",
+    "replayKey",
+    "lowPassGuard",
+    "reclaimBehavior",
+];
+function camelize(value) {
+    return value.replace(/_(.)/g, (_match, char) => char.toUpperCase());
+}
+function aliasMap(tokens) {
+    const entries = tokens.map((token) => [camelize(token), token]);
+    return Object.fromEntries(entries);
+}
+const ACTION = aliasMap(REFILL_V3_CAMPAIGN_ATTENTION_ACTIONS);
+const RESULT = aliasMap(REFILL_V3_CAMPAIGN_ATTENTION_RESULTS);
+/** Actions that may only be chosen once the bounded sample is ENRICHED. */
+export const REFILL_V3_ENRICHMENT_GATED_ACTIONS = [
+    ACTION.requestRubricTrial,
+    ACTION.broadenSourceFamily,
+    ACTION.recordSourceFrontierExhausted,
+];
+/** Actions that OUTRANK rubric relaxation and source broadening. */
+export const REFILL_V3_REPAIR_FIRST_ACTIONS = [
+    ACTION.rerunErroredCells,
+    ACTION.repairCampaignConfig,
+    ACTION.enrichBoundedSample,
+    ACTION.regenerateStaleMessages,
+    ACTION.patchFilterCriteria,
+    ACTION.patchSourceCriteria,
+];
+/** Row-scoped actions whose exact cohort is owned by the diagnostic authority. */
+export const REFILL_V3_ROW_SCOPED_ACTIONS = [
+    ACTION.rerunErroredCells,
+    ACTION.enrichBoundedSample,
+    ACTION.regenerateStaleMessages,
+];
+/** Actions that carry a bounded source command. */
+export const REFILL_V3_SOURCE_ACTIONS = [
+    ACTION.broadenSourceFamily,
+    ACTION.patchSourceCriteria,
+];
+/** One deterministic result per chosen action. */
+export const REFILL_V3_ACTION_RESULTS = Object.freeze({
+    [ACTION.rerunErroredCells]: RESULT.cellsRerun,
+    [ACTION.repairCampaignConfig]: RESULT.campaignConfigRepaired,
+    [ACTION.enrichBoundedSample]: RESULT.boundedSampleEnriched,
+    [ACTION.regenerateStaleMessages]: RESULT.staleMessagesRegenerated,
+    [ACTION.patchFilterCriteria]: RESULT.filterCriteriaPatched,
+    [ACTION.patchSourceCriteria]: RESULT.sourceCriteriaPatched,
+    [ACTION.broadenSourceFamily]: RESULT.sourceFamilyBroadened,
+    [ACTION.requestRubricTrial]: RESULT.rubricTrialRequested,
+    [ACTION.awaitActiveJob]: RESULT.activeJobAwaited,
+    [ACTION.recordSourceFrontierExhausted]: RESULT.sourceFrontierExhausted,
+});
+/**
+ * Posts-search sub-mechanics the MODEL must respect. They live here because the
+ * prompt and the decoder are the two surfaces the model touches; the source
+ * dispatcher IMPORTS them rather than restating them.
+ */
+export const REFILL_V3_POSTS_KEYWORD_BATCH_SIZE = 5;
+export const REFILL_V3_POSTS_MAX_SELECTED = 5;
+export const REFILL_V3_POSTS_ROUND_BUDGET = 3;
+/** Finite wait guidance so a stuck job can never hold a campaign forever. */
+export const REFILL_V3_ACTIVE_JOB_WAIT_MS = 30_000;
+export function createRefillV3CampaignWorkTaskScope() {
+    return { mutatedEvidenceFingerprints: new Set() };
+}
+// ───────────────────────────────────────────────────────────────────────────
+// Hand-rolled guards
+// ───────────────────────────────────────────────────────────────────────────
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+function isOneOf(value, options) {
+    return (typeof value === "string" && options.includes(value));
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every(isNonEmptyString);
+}
+function sameOrder(left, right) {
+    if (left.length !== right.length)
+        return false;
+    return left.every((value, index) => value === right[index]);
+}
+function malformed(detail) {
+    return { ok: false, failure: "malformed_output", detail };
+}
+function unsupported(detail) {
+    return { ok: false, failure: "unsupported_action", detail };
+}
+const OUTPUT_KEYS = new Set([
+    "scopeEcho",
+    "actions",
+    "consumedDiagnosticRowIds",
+]);
+const SCOPE_ECHO_KEYS = new Set([
+    "campaignId",
+    "tableId",
+    "campaignVersion",
+    "evidenceFingerprint",
+]);
+const ACTION_KEYS = new Set([
+    "action",
+    "rationale",
+    "rowIds",
+    "sourceCommand",
+    "candidateVerdicts",
+    "templateFingerprint",
+    "templateMeaningChanged",
+    "exhaustionEvidence",
+    "providerPromptRef",
+]);
+const SOURCE_COMMAND_KEYS = new Set([
+    "family",
+    "mode",
+    "provider",
+    "requestFingerprint",
+    "query",
+    "filterDelta",
+    "keywordBatch",
+    "selectedPostIds",
+    "postRationales",
+]);
+const EXHAUSTION_KEYS = new Set([
+    "supply",
+    "activeJob",
+    "repairableExistingRows",
+    "approvedUndispatchedWork",
+    "structurallyUnactionableRows",
+    "retryExhaustedRows",
+    "scanTermination",
+    "searchedNegativeSet",
+    "yieldEvidence",
+]);
+/**
+ * DEEP scan for cohort/retry bookkeeping anywhere in the model's raw output.
+ *
+ * It runs BEFORE decoding so a batch size buried inside a nested command can
+ * never reach a dependency. Sizing belongs to the existing adaptive worker and a
+ * model-supplied cap is a second selector by another name.
+ */
+export function findRefillV3ForbiddenCommandKey(value) {
+    const queue = [value];
+    for (let index = 0; index < queue.length; index += 1) {
+        const current = queue[index];
+        if (Array.isArray(current)) {
+            for (const entry of current)
+                queue.push(entry);
+            continue;
+        }
+        if (!isRecord(current))
+            continue;
+        for (const key of Object.keys(current)) {
+            if (REFILL_V3_FORBIDDEN_COMMAND_KEYS.includes(key)) {
+                return key;
+            }
+            queue.push(current[key]);
+        }
+    }
+    return null;
+}
+function decodeSourceCommand(value) {
+    if (!isRecord(value)) {
+        return { ok: false, result: malformed("sourceCommand must be an object.") };
+    }
+    const unknownKey = Object.keys(value).find((key) => !SOURCE_COMMAND_KEYS.has(key));
+    if (unknownKey) {
+        return {
+            ok: false,
+            result: malformed(`Unknown sourceCommand field: ${unknownKey}`),
+        };
+    }
+    if (!isOneOf(value.family, REFILL_V3_LEAD_SOURCE_FAMILIES)) {
+        return {
+            ok: false,
+            result: unsupported(`Source family ${String(value.family)} is outside the closed table.`),
+        };
+    }
+    if (!isOneOf(value.mode, REFILL_V3_SOURCE_COMMAND_MODES)) {
+        return {
+            ok: false,
+            result: unsupported(`Source mode ${String(value.mode)} is outside the closed set.`),
+        };
+    }
+    if (!isNonEmptyString(value.requestFingerprint)) {
+        return {
+            ok: false,
+            result: malformed("sourceCommand needs a requestFingerprint."),
+        };
+    }
+    if (!(value.provider === null || isNonEmptyString(value.provider))) {
+        return {
+            ok: false,
+            result: malformed("provider must be a string or null."),
+        };
+    }
+    if (!(value.query === null || typeof value.query === "string")) {
+        return { ok: false, result: malformed("query must be a string or null.") };
+    }
+    if (!(value.filterDelta === null || isRecord(value.filterDelta))) {
+        return {
+            ok: false,
+            result: malformed("filterDelta must be an object or null."),
+        };
+    }
+    let keywordBatch = null;
+    if (value.keywordBatch !== null && value.keywordBatch !== undefined) {
+        if (!isStringArray(value.keywordBatch)) {
+            return {
+                ok: false,
+                result: malformed("keywordBatch must be an array of keywords."),
+            };
+        }
+        if (value.keywordBatch.length !== REFILL_V3_POSTS_KEYWORD_BATCH_SIZE) {
+            return {
+                ok: false,
+                result: unsupported(`A posts-search round carries exactly ${REFILL_V3_POSTS_KEYWORD_BATCH_SIZE} keywords; ${value.keywordBatch.length} were supplied.`),
+            };
+        }
+        keywordBatch = [...value.keywordBatch];
+    }
+    let selectedPostIds = null;
+    if (value.selectedPostIds !== null && value.selectedPostIds !== undefined) {
+        if (!isStringArray(value.selectedPostIds)) {
+            return {
+                ok: false,
+                result: malformed("selectedPostIds must be an array of post ids."),
+            };
+        }
+        if (value.selectedPostIds.length > REFILL_V3_POSTS_MAX_SELECTED) {
+            return {
+                ok: false,
+                result: unsupported(`At most ${REFILL_V3_POSTS_MAX_SELECTED} candidate posts per round; ${value.selectedPostIds.length} were selected.`),
+            };
+        }
+        selectedPostIds = [...value.selectedPostIds];
+    }
+    let postRationales = null;
+    if (value.postRationales !== null && value.postRationales !== undefined) {
+        if (!Array.isArray(value.postRationales)) {
+            return {
+                ok: false,
+                result: malformed("postRationales must be an array."),
+            };
+        }
+        const decoded = [];
+        for (const entry of value.postRationales) {
+            if (!isRecord(entry) ||
+                !isNonEmptyString(entry.postId) ||
+                !isNonEmptyString(entry.expectedYieldBasis)) {
+                return {
+                    ok: false,
+                    result: malformed("Every selected post needs a postId and an expectedYieldBasis."),
+                };
+            }
+            decoded.push({
+                postId: entry.postId,
+                expectedYieldBasis: entry.expectedYieldBasis,
+            });
+        }
+        postRationales = decoded;
+    }
+    // A selected post with no recorded rationale is an unauditable pick.
+    if (selectedPostIds !== null) {
+        const explained = new Set((postRationales ?? []).map((entry) => entry.postId));
+        const unexplained = selectedPostIds.filter((postId) => !explained.has(postId));
+        if (unexplained.length > 0) {
+            return {
+                ok: false,
+                result: malformed(`Selected posts without a recorded selection rationale: ${unexplained.join(", ")}`),
+            };
+        }
+    }
+    return {
+        ok: true,
+        value: {
+            family: value.family,
+            mode: value.mode,
+            provider: value.provider,
+            requestFingerprint: value.requestFingerprint,
+            query: value.query,
+            filterDelta: value.filterDelta,
+            keywordBatch,
+            selectedPostIds,
+            postRationales,
+        },
+    };
+}
+function decodeExhaustionEvidence(value) {
+    if (!isRecord(value))
+        return null;
+    if (Object.keys(value).some((key) => !EXHAUSTION_KEYS.has(key)))
+        return null;
+    if (!isRecord(value.supply) ||
+        !isRecord(value.searchedNegativeSet) ||
+        typeof value.repairableExistingRows !== "number" ||
+        typeof value.approvedUndispatchedWork !== "number" ||
+        typeof value.structurallyUnactionableRows !== "number" ||
+        typeof value.retryExhaustedRows !== "number" ||
+        typeof value.scanTermination !== "string") {
+        return null;
+    }
+    return value;
+}
+function decodeCandidateVerdicts(value) {
+    if (value === null || value === undefined)
+        return { ok: true, value: null };
+    if (!Array.isArray(value))
+        return { ok: false };
+    const decoded = [];
+    for (const entry of value) {
+        if (!isRecord(entry) ||
+            !isNonEmptyString(entry.candidateId) ||
+            !isNonEmptyString(entry.rubricBasis) ||
+            !(entry.verdict === "pass" || entry.verdict === "fail")) {
+            return { ok: false };
+        }
+        decoded.push({
+            candidateId: entry.candidateId,
+            verdict: entry.verdict,
+            rubricBasis: entry.rubricBasis,
+        });
+    }
+    return { ok: true, value: decoded };
+}
+function decodeActionEntry(value) {
+    if (!isRecord(value)) {
+        return {
+            ok: false,
+            result: malformed("Every action entry must be an object, never prose."),
+        };
+    }
+    const unknownKey = Object.keys(value).find((key) => !ACTION_KEYS.has(key));
+    if (unknownKey) {
+        return {
+            ok: false,
+            result: malformed(`Unknown action field: ${unknownKey}`),
+        };
+    }
+    if (!isRefillV3CampaignAttentionAction(value.action)) {
+        return {
+            ok: false,
+            result: unsupported(`Action ${String(value.action)} is not in the closed vocabulary.`),
+        };
+    }
+    if (!isNonEmptyString(value.rationale)) {
+        return {
+            ok: false,
+            result: malformed("Every action needs a non-empty rationale."),
+        };
+    }
+    let rowIds = null;
+    if (value.rowIds !== null && value.rowIds !== undefined) {
+        if (!isStringArray(value.rowIds)) {
+            return {
+                ok: false,
+                result: malformed("rowIds must be an array of ids."),
+            };
+        }
+        rowIds = [...value.rowIds];
+    }
+    let sourceCommand = null;
+    if (value.sourceCommand !== null && value.sourceCommand !== undefined) {
+        const decoded = decodeSourceCommand(value.sourceCommand);
+        if (!decoded.ok)
+            return { ok: false, result: decoded.result };
+        sourceCommand = decoded.value;
+    }
+    const verdicts = decodeCandidateVerdicts(value.candidateVerdicts);
+    if (!verdicts.ok) {
+        return {
+            ok: false,
+            result: malformed("Every candidate verdict needs an identity, a pass/fail, and a rubric basis."),
+        };
+    }
+    if (!(value.templateFingerprint === null ||
+        value.templateFingerprint === undefined ||
+        isNonEmptyString(value.templateFingerprint))) {
+        return {
+            ok: false,
+            result: malformed("templateFingerprint must be a string or null."),
+        };
+    }
+    if (value.templateMeaningChanged !== undefined &&
+        typeof value.templateMeaningChanged !== "boolean") {
+        return {
+            ok: false,
+            result: malformed("templateMeaningChanged must be a boolean."),
+        };
+    }
+    let exhaustionEvidence = null;
+    if (value.exhaustionEvidence !== null &&
+        value.exhaustionEvidence !== undefined) {
+        exhaustionEvidence = decodeExhaustionEvidence(value.exhaustionEvidence);
+        if (exhaustionEvidence === null) {
+            return {
+                ok: false,
+                result: malformed("exhaustionEvidence does not match the shared shape."),
+            };
+        }
+    }
+    let providerPromptRef = null;
+    if (value.providerPromptRef !== null &&
+        value.providerPromptRef !== undefined) {
+        const ref = value.providerPromptRef;
+        if (!isRecord(ref) ||
+            !isNonEmptyString(ref.provider) ||
+            !isNonEmptyString(ref.campaignOfferId)) {
+            return {
+                ok: false,
+                result: malformed("providerPromptRef needs an exact provider and campaignOfferId."),
+            };
+        }
+        providerPromptRef = {
+            provider: ref.provider,
+            campaignOfferId: ref.campaignOfferId,
+        };
+    }
+    return {
+        ok: true,
+        value: {
+            action: value.action,
+            rationale: value.rationale,
+            rowIds,
+            sourceCommand,
+            candidateVerdicts: verdicts.value,
+            templateFingerprint: typeof value.templateFingerprint === "string"
+                ? value.templateFingerprint
+                : null,
+            templateMeaningChanged: value.templateMeaningChanged === true,
+            exhaustionEvidence,
+            providerPromptRef,
+        },
+    };
+}
+/**
+ * SOLE decoder for the traversal's model output.
+ *
+ * The model answers with an ARRAY so zero, multiple, and duplicate choices each
+ * get their OWN typed failure instead of being silently collapsed into "the
+ * first one" — which is how a model that hedged two actions gets read as having
+ * decided one.
+ */
+export function decodeRefillV3CampaignWorkOutput(value) {
+    if (!isRecord(value)) {
+        return malformed("The traversal output must be an object, never narration.");
+    }
+    const unknownKey = Object.keys(value).find((key) => !OUTPUT_KEYS.has(key));
+    if (unknownKey) {
+        return malformed(`Unknown output field: ${unknownKey}`);
+    }
+    const echo = value.scopeEcho;
+    if (!isRecord(echo)) {
+        return malformed("The output must echo the selected scope.");
+    }
+    if (Object.keys(echo).some((key) => !SCOPE_ECHO_KEYS.has(key))) {
+        return malformed("scopeEcho carries a field outside the closed set.");
+    }
+    if (!isNonEmptyString(echo.campaignId) ||
+        !isNonEmptyString(echo.tableId) ||
+        !Number.isInteger(echo.campaignVersion) ||
+        !isNonEmptyString(echo.evidenceFingerprint)) {
+        return malformed("scopeEcho is incomplete.");
+    }
+    if (!Array.isArray(value.actions)) {
+        return malformed("actions must be an array so arity is decidable.");
+    }
+    if (value.actions.length === 0) {
+        return {
+            ok: false,
+            failure: "zero_actions",
+            detail: "The model returned no action.",
+        };
+    }
+    if (value.actions.length > 1) {
+        const tokens = value.actions.map((entry) => isRecord(entry) ? String(entry.action) : "");
+        const distinct = new Set(tokens);
+        return distinct.size === 1
+            ? {
+                ok: false,
+                failure: "duplicate_action",
+                detail: `The model repeated ${tokens[0]} ${tokens.length} times.`,
+            }
+            : {
+                ok: false,
+                failure: "multiple_actions",
+                detail: `The model returned ${distinct.size} distinct actions: ${[...distinct].join(", ")}`,
+            };
+    }
+    const decodedAction = decodeActionEntry(value.actions[0]);
+    if (!decodedAction.ok)
+        return decodedAction.result;
+    let consumed = null;
+    if (value.consumedDiagnosticRowIds !== null &&
+        value.consumedDiagnosticRowIds !== undefined) {
+        if (!isStringArray(value.consumedDiagnosticRowIds)) {
+            return malformed("consumedDiagnosticRowIds must be an array of row ids.");
+        }
+        consumed = [...value.consumedDiagnosticRowIds];
+    }
+    return {
+        ok: true,
+        value: {
+            scopeEcho: {
+                campaignId: echo.campaignId,
+                tableId: echo.tableId,
+                campaignVersion: echo.campaignVersion,
+                evidenceFingerprint: echo.evidenceFingerprint,
+            },
+            actions: [decodedAction.value],
+            consumedDiagnosticRowIds: consumed,
+        },
+    };
+}
+// ───────────────────────────────────────────────────────────────────────────
+// The one traversal iteration
+// ───────────────────────────────────────────────────────────────────────────
+function refuse(callLog, failure, detail, result = null) {
+    return { ok: false, failure, detail, result, callLog };
+}
+/**
+ * Run ONE selected-campaign attention iteration.
+ *
+ * Ordering is load-bearing and every early refusal makes ZERO dependency calls:
+ *
+ *  health → cohort bookkeeping → decode → exact scope → task-local replay →
+ *  bounded diagnose → live-job gate → canonical order → repair-first →
+ *  enrich-before-rubric → template meaning → provider prompt → negative set →
+ *  exhaustion falsification → ONE authority → receipt → ONE re-observation.
+ */
+export async function runRefillV3CampaignWork(input) {
+    const { packet, dependencies } = input;
+    const callLog = [];
+    // 1. Connection health is Plan 10's, never this seam's. It outranks every
+    //    other branch, including a legitimate live-job wait: editing config to
+    //    mask a disconnected sender is the defect this refusal exists to stop.
+    if ((input.healthEvidence ?? []).length > 0) {
+        return refuse(callLog, "health_recheck_required", `Connection-health evidence must be handled before campaign work: ${(input.healthEvidence ?? []).join(", ")}`, RESULT.healthRecheckRequired);
+    }
+    // 2. Cohort/retry bookkeeping anywhere in the raw output.
+    const forbiddenKey = findRefillV3ForbiddenCommandKey(input.output);
+    if (forbiddenKey) {
+        return refuse(callLog, "cohort_arithmetic_forbidden", `The model supplied ${forbiddenKey}; sizing and replay bookkeeping belong to the deterministic owners.`);
+    }
+    // 3. One closed action.
+    const decoded = decodeRefillV3CampaignWorkOutput(input.output);
+    if (!decoded.ok) {
+        return refuse(callLog, decoded.failure, decoded.detail);
+    }
+    const chosen = decoded.value.actions[0];
+    const echo = decoded.value.scopeEcho;
+    // 4. Exact scope, then drift. Foreign identity and stale identity are
+    //    DIFFERENT facts and must never collapse into one reason.
+    if (echo.campaignId !== packet.scope.campaignId ||
+        echo.tableId !== packet.scope.tableId) {
+        return refuse(callLog, "foreign_scope", `The output names ${echo.campaignId}/${echo.tableId}, not the selected ${packet.scope.campaignId}/${packet.scope.tableId}.`);
+    }
+    if (echo.campaignVersion !== packet.scope.campaignVersion ||
+        echo.evidenceFingerprint !== packet.scope.evidenceFingerprint) {
+        return refuse(callLog, "stale_evidence", `The output was formed against version ${echo.campaignVersion}/${echo.evidenceFingerprint}, not ${packet.scope.campaignVersion}/${packet.scope.evidenceFingerprint}.`);
+    }
+    // 5. One evidence packet can authorize at most one mutation per task.
+    if (input.taskScope?.mutatedEvidenceFingerprints.has(packet.scope.evidenceFingerprint)) {
+        return refuse(callLog, "second_mutation_forbidden", `Evidence ${packet.scope.evidenceFingerprint} already authorized one mutation; re-observe before choosing again.`);
+    }
+    // 6. The bounded diagnostic read. Exactly one call, capped at the canonical
+    //    sample size, scoped to the selected campaign and table.
+    const sample = await dependencies.loadDiagnosticSample({
+        workspaceId: packet.scope.workspaceId,
+        campaignId: packet.scope.campaignId,
+        tableId: packet.scope.tableId,
+        limit: REFILL_V3_DIAGNOSTIC_SAMPLE_CAP,
+    });
+    callLog.push({
+        step: "diagnose",
+        detail: `${packet.scope.campaignId}:${packet.scope.tableId}:limit=${REFILL_V3_DIAGNOSTIC_SAMPLE_CAP}`,
+    });
+    // 7. Live-job gate, re-checked at the DISPATCH boundary against the shared
+    //    TABLE frontier so two senders enrolled on one table cannot both dispatch.
+    const packetLiveJob = packet.evidence.activeJob;
+    const dispatchBoundaryLiveJob = packetLiveJob === null
+        ? await dependencies.readLiveTableJob({ tableId: packet.scope.tableId })
+        : null;
+    const liveJob = packetLiveJob ?? dispatchBoundaryLiveJob;
+    if (liveJob !== null) {
+        // A model must obey a live job that was already in its packet. A job first
+        // observed (or revived) at the dispatch boundary is newer deterministic
+        // evidence the model could not have predicted, so the authority converts
+        // the stale mutation proposal into the only safe transition: a bounded
+        // wait with zero dispatch.
+        const becameLiveAtDispatchBoundary = packetLiveJob === null && dispatchBoundaryLiveJob !== null;
+        if (chosen.action !== ACTION.awaitActiveJob &&
+            !becameLiveAtDispatchBoundary) {
+            return refuse(callLog, "live_job_blocks_action", `A live ${liveJob.kind} job (${liveJob.status}) holds this frontier; the only legal action is a bounded wait.`);
+        }
+        callLog.push({ step: "await_active_job", detail: liveJob.id });
+        const reobservation = await dependencies.reobserveExactSenderDates({
+            workspaceId: packet.scope.workspaceId,
+            senderId: packet.scope.senderId,
+            date: packet.scope.date,
+        });
+        callLog.push({
+            step: "reobserve",
+            detail: `${packet.scope.senderId}:${packet.scope.date}`,
+        });
+        return {
+            ok: true,
+            action: ACTION.awaitActiveJob,
+            result: RESULT.activeJobAwaited,
+            receipt: {
+                outcome: "no_effect",
+                result: RESULT.activeJobAwaited,
+                scopeEcho: scopeEchoOf(packet),
+                idempotencyKey: idempotencyKeyOf(input, ACTION.awaitActiveJob),
+                beforeFingerprint: null,
+                afterFingerprint: null,
+                changedFields: [],
+                effectKey: null,
+                rollback: null,
+                reobserveRequired: true,
+                preparationDelegation: null,
+                systemicError: false,
+                lowPass: false,
+                refusalReason: null,
+            },
+            reobservation,
+            wait: {
+                activeJob: liveJob,
+                waitMs: REFILL_V3_ACTIVE_JOB_WAIT_MS,
+                reobserveRequired: true,
+                resumeGuidance: `Re-observe this sender/date after ${REFILL_V3_ACTIVE_JOB_WAIT_MS}ms and choose again from fresh evidence. The wait is finite: a job that is still live on the next observation is a stuck job, not a reason to block.`,
+            },
+            nextCohortCap: null,
+            callLog,
+        };
+    }
+    // 8. The backend owns the canonical bounded cohort. A model may echo an
+    //    already-issued order for backward compatibility, but it never needs a
+    //    discovery/retry call merely to learn row ids. Any supplied prefix,
+    //    offset, or reordering is still refused.
+    if (decoded.value.consumedDiagnosticRowIds !== null &&
+        !sameOrder(decoded.value.consumedDiagnosticRowIds, sample.orderedRowIds)) {
+        return refuse(callLog, "diagnostic_order_not_consumed", `The echoed order [${decoded.value.consumedDiagnosticRowIds.join(",")}] is not the canonical order [${sample.orderedRowIds.join(",")}].`);
+    }
+    // 9. A FAILED job is not active: it routes to bounded just-in-time inspection
+    //    and then to ONE repair, which OUTRANKS rubric relaxation and broadening.
+    if (packet.evidence.failedJobRef !== null) {
+        if (sample.failureEvidence.length === 0) {
+            return refuse(callLog, "stale_evidence", `The packet names failed job ${packet.evidence.failedJobRef} but the bounded inspection returned no failure evidence.`);
+        }
+        if (!REFILL_V3_REPAIR_FIRST_ACTIONS.includes(chosen.action)) {
+            return refuse(callLog, "rubric_before_viable_repair", `An exact repair for failed job ${packet.evidence.failedJobRef} outranks ${chosen.action}.`);
+        }
+    }
+    // 10. Enrich BEFORE any rubric judgement. A rubric verdict over an unenriched
+    //     sample is a false negative because the fields it reads do not exist yet
+    //     (incident 112k), so it can never justify relaxation, broadening, or
+    //     exhaustion.
+    if (sample.unenrichedRowIds.length > 0 &&
+        REFILL_V3_ENRICHMENT_GATED_ACTIONS.includes(chosen.action)) {
+        return refuse(callLog, "rubric_before_enrichment", `${sample.unenrichedRowIds.length} sampled rows are unenriched; ${chosen.action} is invalid until the bounded sample is enriched.`);
+    }
+    // 11. Template/sequence MEANING exits to the existing approval boundary. It
+    //     cannot be smuggled through repair, source work, or rubric relaxation.
+    if (chosen.templateMeaningChanged) {
+        return refuse(callLog, "template_meaning_requires_approval", "A template or sequence meaning change belongs to the separate approval boundary.", RESULT.noActionAvailable);
+    }
+    // 12. Row selection must stay inside the canonical bounded frontier.
+    const resolvedRowIds = resolveRowIds(chosen, sample);
+    if (resolvedRowIds !== null) {
+        const canonical = new Set(sample.orderedRowIds);
+        const outside = resolvedRowIds.filter((rowId) => !canonical.has(rowId));
+        if (outside.length > 0) {
+            return refuse(callLog, "diagnostic_order_not_consumed", `Rows outside the canonical bounded frontier: ${outside.join(", ")}`);
+        }
+    }
+    // 13. Searched-negative-set replay. Checked BEFORE any provider guidance load
+    //     so an identical search costs zero provider work.
+    if (chosen.sourceCommand !== null &&
+        packet.evidence.searchedNegativeSetFingerprints.includes(chosen.sourceCommand.requestFingerprint)) {
+        return refuse(callLog, "negative_set_replay", `Request fingerprint ${chosen.sourceCommand.requestFingerprint} is already in the searched negative set for this campaign.`);
+    }
+    // 14. Exactly ONE matching active provider prompt for a new provider search or
+    //     a prompt-package-bound exhaustion record; exactly ZERO on a drain.
+    const promptGate = resolveProviderPromptRequirement(chosen, packet);
+    if (promptGate.kind === "refuse") {
+        return refuse(callLog, promptGate.failure, promptGate.detail);
+    }
+    let providerPrompt = null;
+    if (promptGate.kind === "load") {
+        providerPrompt = await dependencies.loadProviderPrompt({
+            provider: promptGate.provider,
+            campaignOfferId: packet.scope.campaignId,
+        });
+        callLog.push({
+            step: "load_provider_prompt",
+            detail: `${promptGate.provider}:${packet.scope.campaignId}`,
+        });
+        if (providerPrompt === null) {
+            return refuse(callLog, "provider_prompt_missing", `${promptGate.provider} has no active campaign-scoped guidance for ${packet.scope.campaignId}; missing guidance can never license a search or prove exhaustion.`);
+        }
+    }
+    // 15. Every exhaustion claim is falsified against the SHARED predicate. The
+    //     AI never terminates a campaign on its own word.
+    let exhaustionVerdict = null;
+    if (chosen.action === ACTION.recordSourceFrontierExhausted) {
+        if (chosen.exhaustionEvidence === null) {
+            return refuse(callLog, "stale_evidence", "An exhaustion claim must carry the bounded evidence it was formed from.");
+        }
+        exhaustionVerdict = falsifyRefillV3ExhaustionClaim(chosen.exhaustionEvidence);
+        if (!exhaustionVerdict.exhausted) {
+            return refuse(callLog, "exhaustion_falsified", `Live evidence contradicts the exhaustion claim: ${exhaustionVerdict.falsifyingClause}. The flow continues.`);
+        }
+    }
+    // 16. EXACTLY ONE authority dispatch. Duplicate-work identity keys to the
+    //     TABLE frontier, never to the enrolled sender (incident 112ak).
+    const request = {
+        action: chosen.action,
+        scope: { ...packet.scope },
+        frontierKey: `${packet.scope.tableId}:${chosen.action}`,
+        idempotencyKey: idempotencyKeyOf(input, chosen.action),
+        rowIds: resolvedRowIds,
+        sourceCommand: chosen.sourceCommand,
+        candidateVerdicts: chosen.candidateVerdicts,
+        providerPrompt,
+        exhaustionVerdict,
+    };
+    const receipt = await dependencies.dispatchAuthority(request);
+    callLog.push({ step: "authority", detail: chosen.action });
+    const receiptCheck = validateReceipt(receipt, request, chosen);
+    if (receiptCheck !== null) {
+        return refuse(callLog, receiptCheck.failure, receiptCheck.detail);
+    }
+    // 17. Immediate exact sender/date two-lane re-observation, then STOP.
+    const reobservation = await dependencies.reobserveExactSenderDates({
+        workspaceId: packet.scope.workspaceId,
+        senderId: packet.scope.senderId,
+        date: packet.scope.date,
+    });
+    callLog.push({
+        step: "reobserve",
+        detail: `${packet.scope.senderId}:${packet.scope.date}`,
+    });
+    input.taskScope?.mutatedEvidenceFingerprints.add(packet.scope.evidenceFingerprint);
+    return {
+        ok: true,
+        action: chosen.action,
+        result: receipt.result,
+        receipt,
+        reobservation,
+        wait: null,
+        // The shrink-back rule is BOUND to the worker's own low-pass guard; this
+        // layer names the canonical bounded cap and computes no cohort of its own.
+        nextCohortCap: receipt.systemicError || receipt.lowPass
+            ? REFILL_V3_DIAGNOSTIC_SAMPLE_CAP
+            : null,
+        callLog,
+    };
+}
+function scopeEchoOf(packet) {
+    return `${packet.scope.workspaceId}:${packet.scope.campaignId}:${packet.scope.tableId}`;
+}
+function idempotencyKeyOf(input, action) {
+    if (isNonEmptyString(input.idempotencyKey))
+        return input.idempotencyKey;
+    const { scope } = input.packet;
+    return `${scope.workspaceId}:${scope.campaignId}:${scope.tableId}:${scope.evidenceFingerprint}:${action}`;
+}
+/**
+ * Every row-scoped action consumes the diagnostic authority's exact bounded
+ * cohort. The model chooses WHAT to do; it never chooses the batch.
+ */
+function resolveRowIds(chosen, sample) {
+    if (chosen.action === ACTION.enrichBoundedSample ||
+        chosen.action === ACTION.regenerateStaleMessages) {
+        return sample.orderedRowIds;
+    }
+    if (chosen.action === ACTION.rerunErroredCells)
+        return sample.failedRowIds;
+    return chosen.rowIds;
+}
+function resolveProviderPromptRequirement(chosen, packet) {
+    const needsGuidance = chosen.action === ACTION.recordSourceFrontierExhausted ||
+        (chosen.sourceCommand !== null &&
+            chosen.sourceCommand.mode === "new_provider_search");
+    if (!needsGuidance) {
+        // A drain of already-imported supply and a non-provider post-engager
+        // continuation require and mark NO provider guidance. Preloading one anyway
+        // contradicts the declared mode.
+        if (chosen.providerPromptRef !== null) {
+            return {
+                kind: "refuse",
+                failure: "provider_prompt_forbidden_on_drain",
+                detail: "This action performs no new provider search, so it must load zero provider prompts.",
+            };
+        }
+        return { kind: "skip" };
+    }
+    const ref = chosen.providerPromptRef;
+    if (ref === null) {
+        return {
+            kind: "refuse",
+            failure: "provider_prompt_mismatch",
+            detail: "A new provider search and an exhaustion record each require the matching active provider guidance to be named.",
+        };
+    }
+    if (ref.campaignOfferId !== packet.scope.campaignId) {
+        return {
+            kind: "refuse",
+            failure: "provider_prompt_mismatch",
+            detail: `Guidance was named for campaign ${ref.campaignOfferId}, not the selected ${packet.scope.campaignId}.`,
+        };
+    }
+    if (chosen.sourceCommand !== null &&
+        chosen.sourceCommand.provider !== null &&
+        chosen.sourceCommand.provider !== ref.provider) {
+        return {
+            kind: "refuse",
+            failure: "provider_prompt_mismatch",
+            detail: `Guidance was named for ${ref.provider} but the command targets ${chosen.sourceCommand.provider}.`,
+        };
+    }
+    return { kind: "load", provider: ref.provider };
+}
+/**
+ * A receipt is the ONLY evidence an effect happened. Missing or uncertain
+ * evidence is never success, and an uncertain receipt is reconciled by effect
+ * identity rather than assumed to be a no-op.
+ */
+function validateReceipt(receipt, request, chosen) {
+    if (receipt.outcome === "uncertain") {
+        return {
+            failure: "delegated_tool_timeout",
+            detail: `The ${request.action} authority returned an uncertain effect; reconcile by effect identity before any further mutation.`,
+        };
+    }
+    if (receipt.outcome === "refused") {
+        return {
+            failure: "receipt_incomplete",
+            detail: `The ${request.action} authority refused: ${receipt.refusalReason ?? "no reason supplied"}.`,
+        };
+    }
+    if (!receipt.reobserveRequired) {
+        return {
+            failure: "receipt_incomplete",
+            detail: "Every closed outcome obliges a fresh exact sender/date observation.",
+        };
+    }
+    if (receipt.outcome === "applied") {
+        const missing = [];
+        if (!isNonEmptyString(receipt.beforeFingerprint))
+            missing.push("beforeFingerprint");
+        if (!isNonEmptyString(receipt.afterFingerprint))
+            missing.push("afterFingerprint");
+        if (receipt.changedFields.length === 0)
+            missing.push("changedFields");
+        if (!isNonEmptyString(receipt.effectKey))
+            missing.push("effectKey");
+        if (receipt.rollback === null)
+            missing.push("rollback");
+        if (missing.length > 0) {
+            return {
+                failure: "receipt_incomplete",
+                detail: `An applied receipt is missing: ${missing.join(", ")}.`,
+            };
+        }
+    }
+    if (chosen.action === ACTION.regenerateStaleMessages) {
+        const delegation = receipt.preparationDelegation;
+        const absent = REFILL_V3_PREPARATION_REUSE_POINTS.filter((point) => delegation === null || delegation[point] === undefined);
+        if (absent.length > 0) {
+            return {
+                failure: "receipt_incomplete",
+                detail: `Message preparation must consume every reuse point; missing: ${absent.join(", ")}.`,
+            };
+        }
+    }
+    return null;
+}
+/**
+ * Exported so the falsification path can never be restated: the AI's exhaustion
+ * claim is answered by the SHARED predicate, not by a local truth table.
+ */
+export function falsifyRefillV3ExhaustionClaim(evidence) {
+    return REFILL_V3_EXHAUSTION_PREDICATE.evaluate(evidence);
+}
+/** The bounded sample cap, re-exported so no consumer computes a cohort. */
+export const REFILL_V3_CAMPAIGN_WORK_SAMPLE_CAP = REFILL_V3_DIAGNOSTIC_SAMPLE_CAP;
+/** Guard used by the decoder and by the source dispatcher's boundary pins. */
+export function isRefillV3CampaignAttentionAction(value) {
+    return (typeof value === "string" &&
+        REFILL_V3_CAMPAIGN_ATTENTION_ACTIONS.includes(value));
+}