@sellable/mcp 0.1.756 → 0.1.757

package/dist/refill-run-loop.js

@@ -61,6 +61,14 @@ const DEFAULT_BUDGETS = {
 // refuses to promote unversioned legacy creditTrust packets into scheduling
 // authority, even when they contain a fresh provider response.
 const REFILL_CREDIT_TRUST_VERSION = 2;
+const PAID_INMAIL_CREDIT_RECEIPT_VERSION = "paid_inmail_credit_evaluation.v2";
+const PAID_INMAIL_CREDIT_POLICY_VERSION = 1;
+const PAID_INMAIL_CREDIT_POLICY_TTL_MS = 6 * 60 * 60 * 1000;
+const USABLE_CONTEXTUAL_CREDIT_RECEIPT_STATUSES = new Set([
+    "fresh",
+    "refreshed",
+    "below_threshold",
+]);
 // Mirrors RefillDoneReason in src/lib/workflow-tables/refill-target-plan.ts,
 // plus loop-authored terminals the planner never emits:
 // - abandoned_stale_checkpoint (fix 110-20d): a resumed wait the loop declares
@@ -2274,6 +2282,116 @@ async function startOrResume(input, deps) {
     }
     return ctx;
 }
+function sha256ReceiptParts(parts) {
+    return createHash("sha256").update(JSON.stringify(parts)).digest("hex");
+}
+function sameReceiptContext(value, expected) {
+    return (stringValue(value.workspaceId) === expected.workspaceId &&
+        stringValue(value.senderId) === expected.senderId &&
+        stringValue(value.runId) === expected.runId &&
+        stringValue(value.campaignId) === expected.campaignId &&
+        stringValue(value.tableId) === expected.tableId &&
+        stringValue(value.columnId) === expected.columnId &&
+        (stringValue(value.cellId) ?? null) === expected.cellId &&
+        stringValue(value.actionType) === expected.actionType &&
+        numberValue(value.threshold) === expected.threshold);
+}
+/**
+ * Decode the backend-owned Phase 123 receipt enough to prove that the client
+ * is handing the exact fact/context identity back to the planner. The backend
+ * performs the same validation again when parsing run state; this client-side
+ * check prevents advancing g0 with bytes that are already known to fail there.
+ */
+function decodeContextualPaidInmailReceipt(value, expected, now) {
+    const response = recordValue(value);
+    const receipt = recordValue(response?.receipt) ??
+        (stringValue(response?.receiptVersion) ===
+            PAID_INMAIL_CREDIT_RECEIPT_VERSION
+            ? response
+            : null);
+    if (!receipt ||
+        stringValue(receipt.receiptVersion) !==
+            PAID_INMAIL_CREDIT_RECEIPT_VERSION ||
+        numberValue(receipt.policyVersion) !== PAID_INMAIL_CREDIT_POLICY_VERSION ||
+        numberValue(receipt.policyTtlMs) !== PAID_INMAIL_CREDIT_POLICY_TTL_MS ||
+        numberValue(receipt.maxStalenessMs) !== PAID_INMAIL_CREDIT_POLICY_TTL_MS ||
+        !USABLE_CONTEXTUAL_CREDIT_RECEIPT_STATUSES.has(stringValue(receipt.status) ?? "")) {
+        return null;
+    }
+    const evaluationContext = recordValue(receipt.evaluationContext);
+    if (!evaluationContext ||
+        !sameReceiptContext(evaluationContext, expected) ||
+        !sameReceiptContext(receipt, expected)) {
+        return null;
+    }
+    const evaluatedAt = new Date(stringValue(receipt.evaluatedAt) ?? "");
+    const after = recordValue(receipt.after);
+    const checkedAt = new Date(stringValue(after?.checkedAt) ?? "");
+    const balance = numberValue(after?.balance);
+    const sentSince = numberValue(after?.sentSince);
+    const available = numberValue(after?.available);
+    const logicalRefreshId = stringValue(receipt.logicalRefreshId);
+    const transportAttempt = recordValue(receipt.transportAttempt);
+    if (!Number.isFinite(evaluatedAt.getTime()) ||
+        !Number.isFinite(checkedAt.getTime()) ||
+        evaluatedAt.getTime() > now.getTime() ||
+        checkedAt.getTime() > now.getTime() ||
+        balance === null ||
+        !Number.isInteger(balance) ||
+        balance < 0 ||
+        sentSince === null ||
+        !Number.isInteger(sentSince) ||
+        sentSince < 0 ||
+        available === null ||
+        !Number.isInteger(available) ||
+        available < 0 ||
+        !logicalRefreshId ||
+        stringValue(transportAttempt?.logicalRefreshId) !== logicalRefreshId) {
+        return null;
+    }
+    const factIdentity = sha256ReceiptParts([
+        "paid-inmail-credit-fact",
+        PAID_INMAIL_CREDIT_POLICY_VERSION,
+        expected.senderId,
+        checkedAt.toISOString(),
+        balance,
+    ]);
+    if (stringValue(receipt.factIdentity) !== factIdentity ||
+        stringValue(after?.factIdentity) !== factIdentity) {
+        return null;
+    }
+    const snapshotIdentity = sha256ReceiptParts([
+        "paid-inmail-credit-evaluation-snapshot",
+        factIdentity,
+        sentSince,
+        available,
+        evaluatedAt.toISOString(),
+    ]);
+    if (stringValue(receipt.evaluationSnapshotIdentity) !== snapshotIdentity) {
+        return null;
+    }
+    const contextIdentity = sha256ReceiptParts([
+        expected.workspaceId,
+        expected.senderId,
+        expected.runId,
+        expected.campaignId,
+        expected.tableId,
+        expected.columnId,
+        expected.cellId,
+        expected.actionType,
+        expected.threshold,
+    ]);
+    const receiptId = sha256ReceiptParts([
+        PAID_INMAIL_CREDIT_RECEIPT_VERSION,
+        PAID_INMAIL_CREDIT_POLICY_VERSION,
+        contextIdentity,
+        factIdentity,
+        snapshotIdentity,
+        logicalRefreshId,
+        stringValue(receipt.status),
+    ]);
+    return stringValue(receipt.receiptId) === receiptId ? receipt : null;
+}
 async function gateBootstrap(input, deps, ctx) {
     const plan = await deps.readPlan(refillPlanReadInput(input, { ctx, journal: false }));
     const issuedReportingContext = sanitizeRefillReportingContextProjection(plan.reportingContext);
@@ -2294,46 +2412,127 @@ async function gateBootstrap(input, deps, ctx) {
     if (issuedReportingContext) {
         input.reportingContext = issuedReportingContext;
     }
-    const paidCredit = arrayValue(recordValue(plan.bootstrap)?.paidCredit).filter(isRecord);
-    const refreshedSenderIds = new Set(arrayValue(recordValue(ctx.runState.creditTrust)?.senderIds)
-        .map((entry) => stringValue(entry))
-        .filter((entry) => Boolean(entry)));
-    const attemptedSenderIds = new Set(arrayValue(recordValue(ctx.runState.creditTrust)?.attemptedSenderIds)
-        .map((entry) => stringValue(entry))
-        .filter((entry) => Boolean(entry)));
-    const receipts = [];
-    for (const entry of paidCredit) {
-        const senderId = stringValue(entry.senderId);
-        if (!senderId ||
-            !entry.plannedJitRefresh ||
-            refreshedSenderIds.has(senderId) ||
-            attemptedSenderIds.has(senderId)) {
-            continue;
+    const pinnedRunState = pinInitialSenderLaneChains(plan, ctx.runState);
+    // Exact fenced plans are projected by projectedV2Packet(), whose legacy
+    // bootstrap.paidCredit array is intentionally empty. The canonical refresh
+    // authority is packet.target.globalActionQueue; reading the bootstrap array
+    // minted `{ version: 2, receipts: [] }` on every run, which made the next
+    // exact planner read receipt-aware without giving it a receipt to validate.
+    const packet = recordValue(plan.packet);
+    const packetTarget = recordValue(packet?.target);
+    const paidCreditActions = arrayValue(packetTarget?.globalActionQueue)
+        .filter(isRecord)
+        .filter((action) => stringValue(action.type) === "refresh_paid_inmail_credits");
+    const contextualReceipts = [];
+    const refreshedSenderIds = [];
+    const now = deps.now?.() ?? new Date();
+    for (const action of paidCreditActions) {
+        const toolInput = actionToolInput(action);
+        const ids = actionIds(action);
+        const senderId = actionSenderId(action);
+        const campaignId = actionCampaignId(action);
+        const tableId = actionTableId(action);
+        const columnId = stringValue(toolInput.columnId) ??
+            stringValue(ids.columnId) ??
+            stringValue(action.columnId);
+        const actionType = stringValue(action.actionType) ?? stringValue(toolInput.actionType);
+        const threshold = numberValue(toolInput.threshold) ??
+            numberValue(toolInput.oldThreshold) ??
+            numberValue(action.threshold) ??
+            numberValue(action.oldThreshold);
+        const completeContext = senderId &&
+            campaignId &&
+            tableId &&
+            columnId &&
+            actionType === "send_inmail_closed" &&
+            threshold !== null &&
+            Number.isInteger(threshold) &&
+            threshold >= 0
+            ? {
+                workspaceId: input.workspaceId,
+                senderId,
+                runId: ctx.runId,
+                campaignId,
+                tableId,
+                columnId,
+                cellId: null,
+                actionType: "INMAIL_CLOSED",
+                threshold,
+            }
+            : null;
+        if (!completeContext) {
+            return {
+                status: "blocked",
+                blocker: "paid_inmail_refresh_failed",
+                runId: ctx.runId,
+                fence: ctx.fence,
+                gate: ctx.gate,
+                guidance: "The exact paid InMail refresh action did not carry a complete sender/campaign/table/column/action/threshold context. The run stayed at bootstrap and no refill primitive executed.",
+                report: { action },
+                journalPath: ctx.journalPath,
+                targetConfig: ctx.targetConfig ?? undefined,
+                runHandle: ctx.runHandle,
+            };
         }
-        const receipt = await deps.executors.refreshPaidInmailCreditsWithRetry(senderId, input.workspaceId);
-        attemptedSenderIds.add(senderId);
-        const classification = classifyPaidInmailRefreshReceipt(receipt.receipt);
-        receipts.push({ senderId, receipt, classification });
-        if (classification.usableCurrentFacts) {
-            refreshedSenderIds.add(senderId);
+        const refresh = await deps.executors.refreshPaidInmailCreditsWithRetry(completeContext.senderId, completeContext.workspaceId, {
+            runId: completeContext.runId,
+            actionType: "send_inmail_closed",
+            campaignId: completeContext.campaignId,
+            tableId: completeContext.tableId,
+            columnId: completeContext.columnId,
+            threshold: completeContext.threshold,
+        });
+        const classification = classifyPaidInmailRefreshReceipt(refresh.receipt);
+        const decodedReceipt = decodeContextualPaidInmailReceipt(refresh.receipt, completeContext, now);
+        if (!classification.usableCurrentFacts || !decodedReceipt) {
+            return {
+                status: "blocked",
+                blocker: "paid_inmail_refresh_failed",
+                runId: ctx.runId,
+                fence: ctx.fence,
+                gate: ctx.gate,
+                guidance: "Paid InMail credit refresh did not return one usable receipt matching the exact fenced context. The run stayed at bootstrap and did not advance with invalid authority.",
+                report: {
+                    senderId: completeContext.senderId,
+                    receiptStatus: classification.status,
+                    error: classification.error,
+                    attempts: refresh.attempts,
+                    errors: refresh.errors,
+                },
+                journalPath: ctx.journalPath,
+                targetConfig: ctx.targetConfig ?? undefined,
+                runHandle: ctx.runHandle,
+            };
         }
-    }
-    const pinnedRunState = pinInitialSenderLaneChains(plan, ctx.runState);
-    const nextRunState = mergeRunState(pinnedRunState, {
-        creditTrust: {
-            version: REFILL_CREDIT_TRUST_VERSION,
-            refreshedAt: (deps.now?.() ?? new Date()).toISOString(),
-            senderIds: [...refreshedSenderIds],
-            attemptedSenderIds: [...attemptedSenderIds],
-            receipts,
-        },
-    });
+        contextualReceipts.push(decodedReceipt);
+        refreshedSenderIds.push(completeContext.senderId);
+    }
+    // Never promote an empty or legacy packet into receipt authority. With no
+    // refresh head, the exact planner remains cache-fact based and can execute
+    // the source/preparation action it already selected.
+    const { creditTrust: _discardedCreditTrust, ...runStateWithoutCreditTrust } = pinnedRunState;
+    const nextRunState = contextualReceipts.length > 0
+        ? mergeRunState(runStateWithoutCreditTrust, {
+            creditTrust: {
+                version: REFILL_CREDIT_TRUST_VERSION,
+                receiptId: stringValue(contextualReceipts[0]?.receiptId),
+                refreshedAt: now.toISOString(),
+                senderIds: [...new Set(refreshedSenderIds)],
+                attemptedSenderIds: [...new Set(refreshedSenderIds)],
+                receipts: contextualReceipts,
+            },
+        })
+        : runStateWithoutCreditTrust;
     await safeJournalAppend(ctx, deps, deps.journal.renderBootstrapSection({
         summary: "Refill v2 execution bootstrap",
         senderSummary: safeJson(recordValue(plan.bootstrap)?.senders ?? []),
         laneSummary: safeJson(recordValue(plan.bootstrap)?.laneOrder ?? []),
         targetSummary: safeJson(recordValue(plan.bootstrap)?.target ?? []),
-        creditSummary: safeJson(recordValue(plan.bootstrap)?.paidCredit ?? []),
+        creditSummary: safeJson({
+            refreshActionCount: paidCreditActions.length,
+            persistedReceiptCount: contextualReceipts.length,
+            refreshedSenderIds: [...new Set(refreshedSenderIds)],
+        }),
     }));
     const advanced = await deps.runClient.advanceRefillRunGateRemote({
         workspaceId: input.workspaceId,

package/dist/tools/evergreen-refill-plan.d.ts

@@ -17,6 +17,40 @@ type GetRefillPlanV2Input = {
     journalNote?: string;
 };
 export declare function sanitizeEvergreenRefillPlanResult(value: unknown): Record<string, unknown>;
+export declare function projectedV2Packet(packet: Record<string, unknown>): {
+    sideEffects: {
+        scheduled: boolean;
+        mutated: boolean;
+        sent: boolean;
+        refreshedPaidInmailCredits: boolean;
+    };
+    warnings: unknown;
+    reporting?: Record<string, unknown> | undefined;
+    refillReporting?: Record<string, unknown> | undefined;
+    reportingContext?: RefillReportingContextV2 | undefined;
+    readOnly: boolean;
+    generatedAt: unknown;
+    bootstrap: {
+        senders: never[];
+        laneOrder: never[];
+        target: never[];
+        paidCredit: never[];
+        laneMemoryHints: {
+            appliedFromRunState: boolean;
+            cooldownsApplied: never[];
+        };
+    };
+    plans: {};
+    globalActionQueue: {};
+    evergreen: unknown;
+    planRevision: unknown;
+    stateRevision: unknown;
+    packet: Record<string, unknown>;
+    targetConfig: unknown;
+    targetConfigBytes: unknown;
+    targetConfigDigest: unknown;
+    runHandle: {} | null;
+};
 export declare function buildRunStateFromLocalHints(workspaceId: string): {
     version: number;
     senderCursors: never[];

package/dist/tools/evergreen-refill-plan.js

@@ -76,7 +76,7 @@ export function sanitizeEvergreenRefillPlanResult(value) {
     }
     return sanitized;
 }
-function projectedV2Packet(packet) {
+export function projectedV2Packet(packet) {
     const target = isRecord(packet.target) ? packet.target : {};
     const reporting = sanitizeRefillReportingProjection(packet.reporting);
     const reportingContext = sanitizeRefillReportingContextProjection(packet.reportingContext);

package/dist/tools/refill-executors.d.ts

@@ -7,6 +7,7 @@ export type PaidInmailRefreshAction = {
     action?: Record<string, unknown>;
 };
 export type PaidInmailCreditRefreshOptions = {
+    runId?: string | null;
     actionType?: string | null;
     campaignId?: string | null;
     tableId?: string | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sellable/mcp",
-  "version": "0.1.756",
+  "version": "0.1.757",
   "type": "module",
   "description": "Sellable MCP server for Claude Code, Codex, and Hermes campaign workflows",
   "main": "dist/index.js",