@sellable/mcp 0.1.793 → 0.1.794

package/dist/tools/refill-v3-campaign-work.d.ts

@@ -0,0 +1,324 @@
+/**
+ * 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 { type RefillV3ActiveJob, type RefillV3CampaignAttentionAction, type RefillV3CampaignAttentionPacket, type RefillV3CampaignAttentionResult, type RefillV3ExhaustionInput, type RefillV3ExhaustionVerdict, type RefillV3LeadSourceFamily } from "./refill-v3-attention-packet-contract.js";
+/**
+ * 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 declare const REFILL_V3_AI_OUTPUT_FAILURES: readonly ["malformed_output", "zero_actions", "multiple_actions", "duplicate_action", "unsupported_action", "stale_evidence", "model_timeout", "delegated_tool_timeout", "receipt_incomplete", "second_mutation_forbidden"];
+export type RefillV3AiOutputFailure = (typeof REFILL_V3_AI_OUTPUT_FAILURES)[number];
+/** Deterministic REFUSALS that are about the world, not the model's syntax. */
+export declare const REFILL_V3_CAMPAIGN_WORK_REFUSALS: readonly ["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"];
+export type RefillV3CampaignWorkRefusal = (typeof REFILL_V3_CAMPAIGN_WORK_REFUSALS)[number];
+/**
+ * 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 declare const REFILL_V3_DIAGNOSTIC_TERMINATIONS: readonly ["frontier_exhausted", "scan_budget_exhausted", "limit_reached"];
+export type RefillV3DiagnosticTermination = (typeof REFILL_V3_DIAGNOSTIC_TERMINATIONS)[number];
+/** Connection-health reason codes Plan 10 must intercept BEFORE this seam. */
+export declare const REFILL_V3_HEALTH_REASON_CODES: readonly ["paid_inmail_connection_health_recheck_required", "missing_balance", "sender_connection_connecting", "sender_connection_credentials", "sender_disconnected", "sales_nav_disconnected"];
+export type RefillV3HealthReasonCode = (typeof REFILL_V3_HEALTH_REASON_CODES)[number];
+/** The bounded source modes. A drain loads NO provider prompt. */
+export declare const REFILL_V3_SOURCE_COMMAND_MODES: readonly ["new_provider_search", "drain_imported", "post_engager_continuation"];
+export type RefillV3SourceCommandMode = (typeof REFILL_V3_SOURCE_COMMAND_MODES)[number];
+/**
+ * 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 declare const REFILL_V3_FORBIDDEN_COMMAND_KEYS: readonly ["batchSize", "cohortSize", "limit", "offset", "rangeStart", "rangeEnd", "targetCount", "retryCount", "attempts", "cursor"];
+/** The SEVEN reuse points a preparation delegation receipt must carry. */
+export declare const REFILL_V3_PREPARATION_REUSE_POINTS: readonly ["frontier", "remainingGapPassEvidence", "serialBatchCap", "totalRowBudget", "replayKey", "lowPassGuard", "reclaimBehavior"];
+export type RefillV3PreparationReusePoint = (typeof REFILL_V3_PREPARATION_REUSE_POINTS)[number];
+/** Actions that may only be chosen once the bounded sample is ENRICHED. */
+export declare const REFILL_V3_ENRICHMENT_GATED_ACTIONS: readonly ["request_rubric_trial", "broaden_source_family", "record_source_frontier_exhausted"];
+/** Actions that OUTRANK rubric relaxation and source broadening. */
+export declare const REFILL_V3_REPAIR_FIRST_ACTIONS: readonly ["rerun_errored_cells", "repair_campaign_config", "enrich_bounded_sample", "regenerate_stale_messages", "patch_filter_criteria", "patch_source_criteria"];
+/** Row-scoped actions whose exact cohort is owned by the diagnostic authority. */
+export declare const REFILL_V3_ROW_SCOPED_ACTIONS: readonly ["rerun_errored_cells", "enrich_bounded_sample", "regenerate_stale_messages"];
+/** Actions that carry a bounded source command. */
+export declare const REFILL_V3_SOURCE_ACTIONS: readonly ["broaden_source_family", "patch_source_criteria"];
+/** One deterministic result per chosen action. */
+export declare const REFILL_V3_ACTION_RESULTS: Readonly<Record<RefillV3CampaignAttentionAction, RefillV3CampaignAttentionResult>>;
+/**
+ * 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 declare const REFILL_V3_POSTS_KEYWORD_BATCH_SIZE = 5;
+export declare const REFILL_V3_POSTS_MAX_SELECTED = 5;
+export declare const REFILL_V3_POSTS_ROUND_BUDGET = 3;
+/** Finite wait guidance so a stuck job can never hold a campaign forever. */
+export declare const REFILL_V3_ACTIVE_JOB_WAIT_MS = 30000;
+export type RefillV3CandidateVerdict = {
+    candidateId: string;
+    verdict: "pass" | "fail";
+    rubricBasis: string;
+};
+export type RefillV3SourceCommand = {
+    family: RefillV3LeadSourceFamily;
+    mode: RefillV3SourceCommandMode;
+    provider: string | null;
+    requestFingerprint: string;
+    query: string | null;
+    filterDelta: Record<string, unknown> | null;
+    keywordBatch: readonly string[] | null;
+    selectedPostIds: readonly string[] | null;
+    postRationales: readonly {
+        postId: string;
+        expectedYieldBasis: string;
+    }[] | null;
+};
+export type RefillV3CampaignWorkAction = {
+    action: RefillV3CampaignAttentionAction;
+    rationale: string;
+    rowIds: readonly string[] | null;
+    sourceCommand: RefillV3SourceCommand | null;
+    candidateVerdicts: readonly RefillV3CandidateVerdict[] | null;
+    templateFingerprint: string | null;
+    templateMeaningChanged: boolean;
+    exhaustionEvidence: RefillV3ExhaustionInput | null;
+    providerPromptRef: {
+        provider: string;
+        campaignOfferId: string;
+    } | null;
+};
+/**
+ * The model answers with an ARRAY so zero, multiple, and duplicate choices are
+ * all DETECTABLE rather than silently collapsed into "the first one".
+ */
+export type RefillV3CampaignWorkOutput = {
+    scopeEcho: {
+        campaignId: string;
+        tableId: string;
+        campaignVersion: number;
+        evidenceFingerprint: string;
+    };
+    actions: readonly RefillV3CampaignWorkAction[];
+    consumedDiagnosticRowIds: readonly string[] | null;
+};
+export type RefillV3CampaignWorkDecodeResult = {
+    ok: true;
+    value: RefillV3CampaignWorkOutput;
+} | {
+    ok: false;
+    failure: RefillV3AiOutputFailure;
+    detail: string;
+};
+export type RefillV3DiagnosticSample = {
+    limit: number;
+    /** Canonical `(position, id)` order. CONSUMED VERBATIM, never re-windowed. */
+    orderedRowIds: readonly string[];
+    unenrichedRowIds: readonly string[];
+    failedRowIds: readonly string[];
+    failureEvidence: readonly {
+        rowId: string;
+        error: string | null;
+        statusReason: string | null;
+    }[];
+    termination: {
+        reason: RefillV3DiagnosticTermination;
+        rowsChecked: number;
+        rowsRemaining: number | null;
+        hasMore: boolean;
+    };
+};
+export type RefillV3ProviderPromptFact = {
+    provider: string;
+    campaignOfferId: string;
+    promptPackage: string;
+    promptVersion: string;
+};
+export type RefillV3AuthorityRequest = {
+    action: RefillV3CampaignAttentionAction;
+    scope: {
+        workspaceId: string;
+        campaignId: string;
+        tableId: string;
+        campaignVersion: number;
+        evidenceFingerprint: string;
+        senderId: string;
+        date: string;
+    };
+    /**
+     * Duplicate-work identity is keyed to the TABLE FRONTIER, never to the
+     * enrolled sender: two senders sharing one table share one frontier
+     * (incident 112ak).
+     */
+    frontierKey: string;
+    idempotencyKey: string;
+    rowIds: readonly string[] | null;
+    sourceCommand: RefillV3SourceCommand | null;
+    candidateVerdicts: readonly RefillV3CandidateVerdict[] | null;
+    providerPrompt: RefillV3ProviderPromptFact | null;
+    exhaustionVerdict: RefillV3ExhaustionVerdict | null;
+};
+export type RefillV3AuthorityReceipt = {
+    outcome: "applied" | "no_effect" | "refused" | "uncertain";
+    result: RefillV3CampaignAttentionResult;
+    scopeEcho: string;
+    idempotencyKey: string;
+    beforeFingerprint: string | null;
+    afterFingerprint: string | null;
+    changedFields: readonly string[];
+    effectKey: string | null;
+    rollback: {
+        available: boolean;
+        input: unknown;
+        result: unknown;
+    } | null;
+    reobserveRequired: boolean;
+    preparationDelegation: Readonly<Partial<Record<RefillV3PreparationReusePoint, unknown>>> | null;
+    systemicError: boolean;
+    lowPass: boolean;
+    refusalReason: string | null;
+};
+export type RefillV3ReobservationFact = {
+    observed: true;
+    senderId: string;
+    date: string;
+    lanes: readonly string[];
+    evidenceFingerprint: string;
+};
+export type RefillV3CampaignWorkDependencies = {
+    loadDiagnosticSample(input: {
+        workspaceId: string;
+        campaignId: string;
+        tableId: string;
+        limit: number;
+    }): Promise<RefillV3DiagnosticSample>;
+    loadProviderPrompt(input: {
+        provider: string;
+        campaignOfferId: string;
+    }): Promise<RefillV3ProviderPromptFact | null>;
+    readLiveTableJob(input: {
+        tableId: string;
+    }): Promise<RefillV3ActiveJob | null>;
+    dispatchAuthority(request: RefillV3AuthorityRequest): Promise<RefillV3AuthorityReceipt>;
+    reobserveExactSenderDates(input: {
+        workspaceId: string;
+        senderId: string;
+        date: string;
+    }): Promise<RefillV3ReobservationFact>;
+};
+export type RefillV3CampaignWorkCallStep = "diagnose" | "load_provider_prompt" | "authority" | "await_active_job" | "reobserve";
+export type RefillV3CampaignWorkCall = {
+    step: RefillV3CampaignWorkCallStep;
+    detail: string;
+};
+export type RefillV3CampaignWorkWait = {
+    activeJob: RefillV3ActiveJob;
+    waitMs: number;
+    reobserveRequired: true;
+    resumeGuidance: string;
+};
+export type RefillV3CampaignWorkOutcome = {
+    ok: true;
+    action: RefillV3CampaignAttentionAction;
+    result: RefillV3CampaignAttentionResult;
+    receipt: RefillV3AuthorityReceipt;
+    reobservation: RefillV3ReobservationFact;
+    wait: RefillV3CampaignWorkWait | null;
+    nextCohortCap: number | null;
+    callLog: readonly RefillV3CampaignWorkCall[];
+} | {
+    ok: false;
+    failure: RefillV3AiOutputFailure | RefillV3CampaignWorkRefusal;
+    detail: string;
+    result: RefillV3CampaignAttentionResult | null;
+    callLog: readonly RefillV3CampaignWorkCall[];
+};
+export type RefillV3CampaignWorkInput = {
+    packet: RefillV3CampaignAttentionPacket;
+    output: unknown;
+    dependencies: RefillV3CampaignWorkDependencies;
+    /** Canonical health evidence Plan 10 should already have intercepted. */
+    healthEvidence?: readonly string[];
+    /** Task-local guard so one evidence packet can never mutate twice. */
+    taskScope?: RefillV3CampaignWorkTaskScope;
+    /** Per-request replay identity. */
+    idempotencyKey?: string;
+};
+/**
+ * TASK-LOCAL mutation ledger. It is a plain in-memory value with no durable
+ * storage, no cursor, and no attempt counter: its only job is to make a second
+ * mutation from ONE evidence packet impossible inside one task.
+ */
+export type RefillV3CampaignWorkTaskScope = {
+    readonly mutatedEvidenceFingerprints: Set<string>;
+};
+export declare function createRefillV3CampaignWorkTaskScope(): RefillV3CampaignWorkTaskScope;
+/**
+ * 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 declare function findRefillV3ForbiddenCommandKey(value: unknown): string | null;
+/**
+ * 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 declare function decodeRefillV3CampaignWorkOutput(value: unknown): RefillV3CampaignWorkDecodeResult;
+/**
+ * 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 declare function runRefillV3CampaignWork(input: RefillV3CampaignWorkInput): Promise<RefillV3CampaignWorkOutcome>;
+/**
+ * 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 declare function falsifyRefillV3ExhaustionClaim(evidence: RefillV3ExhaustionInput): RefillV3ExhaustionVerdict;
+/** The bounded sample cap, re-exported so no consumer computes a cohort. */
+export declare const REFILL_V3_CAMPAIGN_WORK_SAMPLE_CAP = 10;
+/** Guard used by the decoder and by the source dispatcher's boundary pins. */
+export declare function isRefillV3CampaignAttentionAction(value: unknown): value is RefillV3CampaignAttentionAction;