@openlup/platform 0.20.0 → 0.22.0

package/dist/payments/paymentProviderReconciliationWorker.js

@@ -0,0 +1,245 @@
+import { tryReopenPreparedAbsence } from "./paymentProviderReconciliationAbsenceReopen.js";
+import { applyResultKey, bucket, clamp, classificationOf, evidencePayload, observedEvidenceKey, preparedAttemptEvidenceKey, safeMessage, terminalAmountMismatch, } from "./paymentProviderReconciliationEvidence.js";
+import { silenceIsOverdue } from "./paymentAttemptSilenceWindow.js";
+const MAX_ATTEMPTS_PER_RUN = 4;
+const DEFAULT_BATCH_SIZE = MAX_ATTEMPTS_PER_RUN;
+export const DEFAULT_STALE_AFTER_SECONDS = 15 * 60;
+export async function runPaymentProviderReconciliationWorker(input) {
+    const now = input.now ?? new Date().toISOString();
+    const staleAfterSeconds = clamp(input.staleAfterSeconds ?? DEFAULT_STALE_AFTER_SECONDS, 60, 86_400);
+    // Provider reads and optional prepared-absence probes are sequential and may
+    // be slow. Preserve the per-run ceiling even for an oversized requested batch.
+    const batchSize = clamp(input.batchSize ?? DEFAULT_BATCH_SIZE, 1, MAX_ATTEMPTS_PER_RUN);
+    const claimKey = input.claimKey ?? `payment-provider-reconciliation:${bucket(now)}`;
+    const result = {
+        ok: true,
+        checked: 0,
+        corrected: 0,
+        succeeded: 0,
+        failed: 0,
+        pending: 0,
+        unknown: 0,
+        ignored: 0,
+        dunningOpened: 0,
+        replayed: 0,
+        providerCalls: 0,
+        preparedWithoutProviderAck: 0,
+        preparedAttemptsReopened: 0,
+        manualReview: 0,
+        silenceOverdue: 0,
+        amountCurrencyMismatches: 0,
+        failures: 0,
+        skipped: false,
+    };
+    // Prepared attempts can remain operator-manual indefinitely. Bound their
+    // share so they can never consume a whole worker batch and starve provider
+    // readback for finalized attempts. A batch of one intentionally prioritizes
+    // provider readback; normal scheduled runs use the larger default batch.
+    const preparedLimit = Math.floor(batchSize / 2);
+    const preparedAttempts = preparedLimit > 0
+        ? await input.port.claimPreparedAttempts({
+            now,
+            staleAfterSeconds,
+            limit: preparedLimit,
+            claimKey: `${claimKey}:prepared`,
+        })
+        : [];
+    for (const attempt of preparedAttempts) {
+        const providerStatus = {
+            status: "unknown",
+            providerStatus: "prepared_without_provider_ack",
+            occurredAt: null,
+            failureReason: "prepared_without_provider_ack",
+            amountMinor: null,
+            currency: null,
+            rawPayload: {
+                source: "payment-provider-reconciliation.prepared-watchdog.v0",
+                provider: attempt.provider,
+                providerCallPlanned: true,
+                providerAcknowledged: false,
+            },
+        };
+        const evidence = await input.port.recordEvidence({
+            idempotencyKey: preparedAttemptEvidenceKey(attempt, now),
+            provider: attempt.provider,
+            providerPaymentId: null,
+            paymentIntentId: attempt.paymentIntentId,
+            paymentAttemptId: attempt.paymentAttemptId,
+            localStatus: attempt.attemptStatus,
+            providerStatus: providerStatus.providerStatus,
+            correctionStatus: "failed",
+            checkedAt: now,
+            payload: evidencePayload(attempt, providerStatus, {
+                applied: false,
+                operatorReviewRequired: true,
+            }),
+        });
+        if (evidence.replayed)
+            result.replayed += 1;
+        result.preparedWithoutProviderAck += 1;
+        result.failures += 1;
+        result.ok = false;
+        result.reason = result.reason ?? "prepared_without_provider_ack";
+        // Auto-reopen after a GENUINE provider-side absence proof. A purely local
+        // "no ack recorded" signal cannot rule out the crash window between
+        // executionPort.execute() (provider charged) and finalizeProviderAttempt
+        // (refs persisted) — reopening in that window would mint a fresh PSP
+        // idempotency key and double-charge. Providers without an absence probe
+        if (input.autoReopenPreparedAbsence) {
+            const reopened = await tryReopenPreparedAbsence(input, attempt, now);
+            if (reopened)
+                result.preparedAttemptsReopened += 1;
+        }
+    }
+    const remainingLimit = batchSize - preparedAttempts.length;
+    const attempts = remainingLimit > 0
+        ? await input.port.claimStaleAttempts({
+            now,
+            staleAfterSeconds,
+            limit: remainingLimit,
+            claimKey,
+        })
+        : [];
+    result.checked = preparedAttempts.length + attempts.length;
+    for (const attempt of attempts) {
+        const provider = input.providers[attempt.provider];
+        if (!provider) {
+            await recordNonTerminalEvidence(input.port, attempt, now, {
+                status: "unknown",
+                providerStatus: "provider_not_configured",
+                occurredAt: null,
+                failureReason: "provider_not_configured",
+                amountMinor: null,
+                currency: null,
+                rawPayload: { provider: attempt.provider, source: "payment-provider-reconciliation.v0" },
+            }, "failed");
+            result.unknown += 1;
+            result.failures += 1;
+            result.ok = false;
+            result.reason = result.reason ?? `${attempt.provider}_provider_not_configured`;
+            continue;
+        }
+        let providerStatus;
+        try {
+            if (!attempt.providerPaymentId) {
+                throw new Error("provider_payment_id_missing");
+            }
+            result.providerCalls += 1;
+            providerStatus = await provider.readPayment({
+                providerPaymentId: attempt.providerPaymentId,
+                attempt,
+            });
+        }
+        catch (error) {
+            providerStatus = {
+                status: "unknown",
+                providerStatus: "provider_read_failed",
+                occurredAt: null,
+                failureReason: safeMessage(error),
+                amountMinor: null,
+                currency: null,
+                rawPayload: {
+                    provider: attempt.provider,
+                    providerPaymentId: attempt.providerPaymentId,
+                    readError: safeMessage(error),
+                },
+            };
+            await recordNonTerminalEvidence(input.port, attempt, now, providerStatus, "failed");
+            result.unknown += 1;
+            result.failures += 1;
+            result.ok = false;
+            result.reason = result.reason ?? safeMessage(error);
+            continue;
+        }
+        if (providerStatus.status === "pending" || providerStatus.status === "unknown") {
+            // Polling cannot separate "still running" from "stuck" - both answer
+            // non-terminally forever - so ask the rail how long its own silence stays
+            // normal and surface the attempt past that. NOT a terminal decision:
+            // elapsed time says nothing about whether money moved.
+            const overdue = silenceIsOverdue(input.capabilities, attempt, now);
+            await recordNonTerminalEvidence(input.port, attempt, now, providerStatus, "observed", overdue);
+            if (providerStatus.status === "pending")
+                result.pending += 1;
+            else
+                result.unknown += 1;
+            if (overdue) {
+                result.silenceOverdue += 1;
+                result.manualReview += 1;
+            }
+            continue;
+        }
+        const mismatch = terminalAmountMismatch(attempt, providerStatus);
+        if (mismatch) {
+            await recordNonTerminalEvidence(input.port, attempt, now, {
+                ...providerStatus,
+                failureReason: mismatch,
+                rawPayload: { ...providerStatus.rawPayload, reconciliationMismatch: mismatch },
+            }, "failed");
+            result.manualReview += 1;
+            result.amountCurrencyMismatches += 1;
+            continue;
+        }
+        const occurredAt = providerStatus.occurredAt ?? now;
+        const resultStatus = providerStatus.status;
+        try {
+            const applied = await input.port.applyTerminalResult({
+                idempotencyKey: applyResultKey(attempt, resultStatus),
+                expectedOrderId: attempt.orderId,
+                expectedPaymentIntentId: attempt.paymentIntentId,
+                expectedPaymentAttemptId: attempt.paymentAttemptId,
+                expectedPaymentId: attempt.paymentId,
+                provider: attempt.provider,
+                providerPaymentId: attempt.providerPaymentId,
+                localStatus: attempt.attemptStatus,
+                providerStatus: providerStatus.providerStatus,
+                resultStatus,
+                occurredAt,
+                failureReason: resultStatus === "failed"
+                    ? providerStatus.failureReason ?? `provider_reconciliation_${providerStatus.providerStatus}`
+                    : null,
+                ...classificationOf(resultStatus, providerStatus),
+                checkedAt: now,
+                payload: evidencePayload(attempt, providerStatus, { applied: true, resultStatus }),
+            });
+            if (applied.replayed)
+                result.replayed += 1;
+            if (applied.correctionStatus === "ignored") {
+                result.ignored += 1;
+                continue;
+            }
+            result.corrected += applied.replayed ? 0 : 1;
+            if (resultStatus === "succeeded")
+                result.succeeded += 1;
+            else
+                result.failed += 1;
+            if (applied.subscriptionWebhookDunning?.opened && !applied.subscriptionWebhookDunning.replayed) {
+                result.dunningOpened += 1;
+            }
+        }
+        catch (error) {
+            await recordNonTerminalEvidence(input.port, attempt, now, {
+                ...providerStatus,
+                failureReason: safeMessage(error),
+                rawPayload: { ...providerStatus.rawPayload, applyResultError: safeMessage(error) },
+            }, "failed");
+            result.failures += 1;
+            result.ok = false;
+            result.reason = result.reason ?? safeMessage(error);
+        }
+    }
+    return result;
+}
+function recordNonTerminalEvidence(port, attempt, checkedAt, providerStatus, correctionStatus, silenceOverdue = false) {
+    return port.recordEvidence({
+        idempotencyKey: observedEvidenceKey(attempt, providerStatus.status, correctionStatus, checkedAt),
+        provider: attempt.provider,
+        providerPaymentId: attempt.providerPaymentId,
+        paymentIntentId: attempt.paymentIntentId,
+        paymentAttemptId: attempt.paymentAttemptId,
+        localStatus: attempt.attemptStatus,
+        providerStatus: providerStatus.providerStatus,
+        correctionStatus,
+        checkedAt,
+        payload: evidencePayload(attempt, providerStatus, { applied: false, silenceOverdue }),
+    });
+}

package/dist/payments/paymentTruth.d.ts

@@ -0,0 +1,8 @@
+import type { PaymentTruthEvent, PaymentReconciliationResult, CanonicalPaymentSource } from "./contracts/truth.js";
+export declare function paymentReconciliationFingerprint(input: PaymentReconciliationResult): string;
+/** Fingerprint accepted at a provider boundary before local ownership is known. */
+export declare function paymentSourceFingerprint(input: CanonicalPaymentSource): string;
+export declare function paymentPayloadFingerprint(payload: unknown): string;
+/** Canonical identity for one normalized event; idempotency is deliberately not part of it. */
+export declare function paymentTruthFingerprint(input: PaymentTruthEvent): string;
+export declare function assertPaymentTruthEvent(input: PaymentTruthEvent): void;

package/dist/payments/paymentTruth.js

@@ -0,0 +1,125 @@
+import { createHash } from "node:crypto";
+const PAYMENT_TRUTH_REFUSAL_CLASSES = [
+    "authorization_refused",
+    "insufficient_funds",
+    "method_unavailable",
+    "risk_refused",
+    "unknown_refusal",
+];
+export function paymentReconciliationFingerprint(input) {
+    if (!input.eventId.trim() || input.idempotencyKey.trim().length < 8 || !isInstant(input.occurredAt)) {
+        throw new Error("payment_reconciliation_input_invalid");
+    }
+    if (input.evidenceStatus === "failed" && input.outcome !== "indeterminate") {
+        throw new Error("payment_reconciliation_failure_cannot_terminalize");
+    }
+    if (input.outcome === "refused" && !input.failure) {
+        throw new Error("payment_truth_refusal_classification_required");
+    }
+    if (input.outcome !== "refused" && input.failure) {
+        throw new Error("payment_truth_failure_only_for_refusal");
+    }
+    assertPaymentFailure(input.failure);
+    assertPaymentSourceEvidence(input.evidence);
+    return digest({
+        eventId: input.eventId,
+        evidenceStatus: input.evidenceStatus,
+        outcome: input.outcome,
+        occurredAt: input.occurredAt,
+        failure: input.failure,
+        evidence: input.evidence,
+    });
+}
+/** Fingerprint accepted at a provider boundary before local ownership is known. */
+export function paymentSourceFingerprint(input) {
+    if (!input.sourceEventId.trim() || !input.eventKind.trim()
+        || (input.occurredAt !== null && !isInstant(input.occurredAt))) {
+        throw new Error("payment_source_fingerprint_input_invalid");
+    }
+    if (!/^[0-9a-f]{64}$/.test(input.payloadFingerprint)) {
+        throw new Error("payment_truth_payload_fingerprint_invalid");
+    }
+    return digest(input);
+}
+export function paymentPayloadFingerprint(payload) {
+    return digest(payload);
+}
+/** Canonical identity for one normalized event; idempotency is deliberately not part of it. */
+export function paymentTruthFingerprint(input) {
+    assertPaymentTruthEvent(input);
+    return digest({
+        sourceEventId: input.sourceEventId,
+        settlementIntentId: input.settlementIntentId,
+        outcome: input.outcome,
+        amountMinor: input.amountMinor,
+        currency: input.currency,
+        occurredAt: input.occurredAt,
+        failure: input.failure,
+        evidence: input.evidence,
+    });
+}
+export function assertPaymentTruthEvent(input) {
+    if (!input.sourceEventId.trim())
+        throw new Error("payment_truth_source_event_id_required");
+    if (input.idempotencyKey.trim().length < 8)
+        throw new Error("payment_truth_idempotency_key_invalid");
+    if (!input.settlementIntentId.trim())
+        throw new Error("payment_truth_settlement_intent_required");
+    if (!Number.isSafeInteger(input.amountMinor) || input.amountMinor <= 0) {
+        throw new Error("payment_truth_amount_invalid");
+    }
+    if (!/^[A-Z]{3}$/.test(input.currency))
+        throw new Error("payment_truth_currency_invalid");
+    if (!isInstant(input.occurredAt) || !isInstant(input.evidence.observedAt)) {
+        throw new Error("payment_truth_time_invalid");
+    }
+    if (!input.evidence.sourceReference.trim() || !input.evidence.observedStatus.trim()) {
+        throw new Error("payment_truth_source_evidence_invalid");
+    }
+    if (!/^[0-9a-f]{64}$/.test(input.evidence.payloadFingerprint)) {
+        throw new Error("payment_truth_payload_fingerprint_invalid");
+    }
+    if (input.outcome === "refused" && !input.failure) {
+        throw new Error("payment_truth_refusal_classification_required");
+    }
+    if (input.outcome !== "refused" && input.failure) {
+        throw new Error("payment_truth_failure_only_for_refusal");
+    }
+    assertPaymentFailure(input.failure);
+    assertPaymentSourceEvidence(input.evidence);
+}
+function isInstant(value) {
+    return value.trim().length > 0 && Number.isFinite(Date.parse(value));
+}
+function stableJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stableJson).join(",")}]`;
+    if (value && typeof value === "object") {
+        return `{${Object.entries(value)
+            .sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0)
+            .map(([key, entry]) => `${JSON.stringify(key)}:${stableJson(entry)}`)
+            .join(",")}}`;
+    }
+    return JSON.stringify(value);
+}
+function assertPaymentFailure(failure) {
+    if (failure && !PAYMENT_TRUTH_REFUSAL_CLASSES.includes(failure.classification)) {
+        throw new Error("payment_truth_failure_class_invalid");
+    }
+}
+function assertPaymentSourceEvidence(evidence) {
+    if (evidence.sourceKind !== "accepted_event" && evidence.sourceKind !== "reconciliation_read") {
+        throw new Error("payment_truth_source_kind_invalid");
+    }
+    if (!evidence.sourceReference.trim() || !evidence.observedStatus.trim()) {
+        throw new Error("payment_truth_source_evidence_invalid");
+    }
+    if (!isInstant(evidence.observedAt))
+        throw new Error("payment_truth_time_invalid");
+    if (!/^[0-9a-f]{64}$/.test(evidence.payloadFingerprint)) {
+        throw new Error("payment_truth_payload_fingerprint_invalid");
+    }
+}
+function digest(value) {
+    return createHash("sha256").update(stableJson(value)).digest("hex");
+}

package/dist/payments/paymentVerifyNowHandler.d.ts

@@ -0,0 +1,27 @@
+import { z } from "zod";
+import type { HttpRequest, HttpResponse } from "../http/index.js";
+import type { BffResponder } from "../bff/index.js";
+import type { PaymentProviderReconciliationProvider, PaymentProviderReconciliationPort } from "./contracts/reconciliation.js";
+import type { PaymentVerifyReadPort } from "./contracts/reconciliation.js";
+/**
+ * Buyer-triggered "verify now": after a CLIENT-side confirm failure the FE has
+ * the only copy of the outcome (a pre-charge provider rejection emits no
+ * webhook), so it asks the server to read the provider immediately instead of
+ * waiting for the next adopter-configured reconciliation pass. The client can never assert a result — truth is the live
+ * provider readback, and the only write path is the reconciliation apply RPC
+ * with the cron's own idempotency key, so both paths converge replay-safely.
+ */
+export declare const paymentVerifyRequestSchema: z.ZodObject<{
+    orderId: z.ZodGUID;
+    paymentIntentId: z.ZodGUID;
+    clientId: z.ZodGUID;
+}, z.core.$strip>;
+export type PaymentVerifyRequest = z.infer<typeof paymentVerifyRequestSchema>;
+export declare function createCommercePaymentVerifyHandler(deps: {
+    readPort: PaymentVerifyReadPort;
+    applyPort: Pick<PaymentProviderReconciliationPort, "applyTerminalResult">;
+    providers: Partial<Record<string, PaymentProviderReconciliationProvider>>;
+    mutationsEnabled: () => boolean;
+    now?: () => Date;
+    responder: BffResponder;
+}): (req: HttpRequest, res: HttpResponse) => Promise<void>;

package/dist/payments/paymentVerifyNowHandler.js

@@ -0,0 +1,70 @@
+import { z } from "zod";
+import { verifyPaymentAttemptNow } from "./paymentVerifyNowService.js";
+/**
+ * Buyer-triggered "verify now": after a CLIENT-side confirm failure the FE has
+ * the only copy of the outcome (a pre-charge provider rejection emits no
+ * webhook), so it asks the server to read the provider immediately instead of
+ * waiting for the next adopter-configured reconciliation pass. The client can never assert a result — truth is the live
+ * provider readback, and the only write path is the reconciliation apply RPC
+ * with the cron's own idempotency key, so both paths converge replay-safely.
+ */
+export const paymentVerifyRequestSchema = z.object({
+    orderId: z.guid(),
+    paymentIntentId: z.guid(),
+    clientId: z.guid(),
+});
+export function createCommercePaymentVerifyHandler(deps) {
+    const now = deps.now ?? (() => new Date());
+    const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = deps.responder;
+    return async (req, res) => {
+        if (req.method !== "POST") {
+            sendMethodNotAllowed(res, ["POST"]);
+            return;
+        }
+        if (!deps.mutationsEnabled()) {
+            sendBffError(res, "UPSTREAM_UNAVAILABLE", "Provider payment verify is disabled", {
+                details: {
+                    feature: "payment-verify",
+                    featureFlag: "COMMERCE_PROVIDER_PAYMENTS_ENABLED",
+                    reason: "feature_flag_disabled",
+                },
+            });
+            return;
+        }
+        const parsed = paymentVerifyRequestSchema.safeParse(req.body);
+        if (!parsed.success) {
+            sendBffError(res, "BAD_REQUEST", "Invalid payment verify request", {
+                details: parsed.error.flatten(),
+            });
+            return;
+        }
+        const snapshot = await deps.readPort.readVerifiableAttempt(parsed.data);
+        if (!snapshot) {
+            sendBffError(res, "NOT_FOUND", "Payment not found");
+            return;
+        }
+        // Same non-leaking ownership shape as payment-status: a non-owning triple
+        // reads as absent rather than confirming the payment exists.
+        if (snapshot.orderClientId !== parsed.data.clientId) {
+            sendBffError(res, "NOT_FOUND", "Payment not found");
+            return;
+        }
+        const result = await verifyPaymentAttemptNow({
+            snapshot,
+            applyPort: deps.applyPort,
+            providers: deps.providers,
+            now,
+            // This route has exactly one kind of caller: a browser sitting in a live
+            // checkout, asking about the attempt it is currently waiting on. The
+            // reconciliation worker never comes through here — it holds the provider
+            // and calls `readPayment` itself — so the purpose is a property of the
+            // seam, not something a request may choose.
+            purpose: "active_checkout",
+        });
+        sendBffSuccess(res, {
+            status: result.status,
+            verified: result.verified,
+            applied: result.applied,
+        });
+    };
+}

package/dist/payments/paymentVerifyNowService.d.ts

@@ -0,0 +1,23 @@
+import type { ProviderReadPurpose } from "./contracts/evidence.js";
+import type { VerifiableAttemptSnapshot, PaymentVerifyNowResult } from "./contracts/reconciliation.js";
+import type { ClaimedPaymentAttempt, PaymentProviderReconciliationPort, PaymentProviderReconciliationProvider, ProviderReconciliationStatus } from "./contracts/reconciliation.js";
+/**
+ * Shared buyer/cron-compatible live PSP read. It never accepts a browser
+ * outcome and terminal writes still pass through the canonical reconciliation
+ * RPC, so recovery cannot create a second payment truth path.
+ */
+export declare function verifyPaymentAttemptNow(input: {
+    snapshot: VerifiableAttemptSnapshot;
+    applyPort: Pick<PaymentProviderReconciliationPort, "applyTerminalResult">;
+    providers: Partial<Record<string, PaymentProviderReconciliationProvider>>;
+    now: () => Date;
+    providerPaymentId?: string;
+    providerStatus?: ProviderReconciliationStatus;
+    /**
+     * Passed straight to the provider read. A caller that omits it gets the
+     * reconciliation reading, in which an intent still waiting for its first
+     * payment method is a finished, abandoned attempt.
+     */
+    purpose?: ProviderReadPurpose;
+}): Promise<PaymentVerifyNowResult>;
+export declare function toClaimedAttemptShape(snapshot: VerifiableAttemptSnapshot, providerPaymentId: string): ClaimedPaymentAttempt;

package/dist/payments/paymentVerifyNowService.js

@@ -0,0 +1,93 @@
+import { applyResultKey, evidencePayload, terminalAmountMismatch } from "./paymentProviderReconciliationEvidence.js";
+const LIVE_ATTEMPT_STATUSES = new Set(["sent_to_provider", "requires_action", "processing", "created"]);
+/**
+ * Shared buyer/cron-compatible live PSP read. It never accepts a browser
+ * outcome and terminal writes still pass through the canonical reconciliation
+ * RPC, so recovery cannot create a second payment truth path.
+ */
+export async function verifyPaymentAttemptNow(input) {
+    const { snapshot } = input;
+    if (!LIVE_ATTEMPT_STATUSES.has(snapshot.attemptStatus)) {
+        return { status: snapshot.attemptStatus, verified: false, applied: false, providerPaymentId: null, attempt: null };
+    }
+    const provider = input.providers[snapshot.provider];
+    const providerPaymentId = input.providerPaymentId
+        ?? snapshot.providerAttemptId
+        ?? snapshot.intentProviderPaymentId
+        ?? snapshot.providerSessionId;
+    if (!provider || !providerPaymentId) {
+        return { status: "unavailable", verified: false, applied: false, providerPaymentId, attempt: null };
+    }
+    const attempt = toClaimedAttemptShape(snapshot, providerPaymentId);
+    const providerStatus = input.providerStatus
+        ?? await provider.readPayment({
+            providerPaymentId,
+            attempt,
+            ...(input.purpose ? { purpose: input.purpose } : {}),
+        });
+    if (providerStatus.status !== "succeeded" && providerStatus.status !== "failed") {
+        return {
+            // Preserve the established payment-verify contract: an unknown provider
+            // vocabulary is still non-terminal and therefore reported as pending.
+            status: "pending",
+            verified: true,
+            applied: false,
+            providerPaymentId,
+            attempt,
+        };
+    }
+    if (terminalAmountMismatch(attempt, providerStatus)) {
+        return { status: "manual_review", verified: true, applied: false, providerPaymentId, attempt };
+    }
+    const checkedAt = input.now().toISOString();
+    const applied = await input.applyPort.applyTerminalResult({
+        idempotencyKey: applyResultKey(attempt, providerStatus.status),
+        expectedOrderId: snapshot.orderId,
+        expectedPaymentIntentId: snapshot.paymentIntentId,
+        expectedPaymentAttemptId: snapshot.paymentAttemptId,
+        expectedPaymentId: snapshot.paymentId,
+        provider: attempt.provider,
+        providerPaymentId,
+        localStatus: snapshot.attemptStatus,
+        providerStatus: providerStatus.providerStatus,
+        resultStatus: providerStatus.status,
+        occurredAt: providerStatus.occurredAt ?? checkedAt,
+        failureReason: providerStatus.status === "failed"
+            ? providerStatus.failureReason ?? `provider_verify_${providerStatus.providerStatus}`
+            : null,
+        checkedAt,
+        payload: evidencePayload(attempt, providerStatus, {
+            source: "commerce-payment-verify.v0",
+            trigger: "buyer_confirm_settled",
+        }),
+    });
+    return {
+        status: providerStatus.status,
+        verified: true,
+        applied: applied.correctionStatus === "corrected" && !applied.replayed,
+        providerPaymentId,
+        attempt,
+    };
+}
+export function toClaimedAttemptShape(snapshot, providerPaymentId) {
+    return {
+        paymentAttemptId: snapshot.paymentAttemptId,
+        paymentIntentId: snapshot.paymentIntentId,
+        paymentId: snapshot.paymentId,
+        orderId: snapshot.orderId,
+        subscriptionId: null,
+        subscriptionCycleId: null,
+        provider: snapshot.provider,
+        providerPaymentId,
+        providerAttemptId: snapshot.providerAttemptId,
+        providerSessionId: snapshot.providerSessionId,
+        attemptStatus: snapshot.attemptStatus,
+        intentStatus: snapshot.intentStatus,
+        amountMinor: snapshot.amountMinor,
+        currency: snapshot.currency,
+        orderMode: snapshot.orderMode,
+        cycleRetryAttempt: 0,
+        cycleNextRetryAt: null,
+        localUpdatedAt: snapshot.localUpdatedAt,
+    };
+}

package/dist/payments/paymentWebhookPostProcessing.d.ts

@@ -0,0 +1,22 @@
+export type PaymentRefusalHandoff = {
+    outcome: "refused" | "not_refused";
+    idempotencyKey: string;
+    paymentIntentId: string | null;
+    sourceEventId: string;
+    failureReason: string | null;
+    occurredAt: string;
+};
+export interface PaymentFailureDunningPort {
+    openFromExplicitRefusal(input: {
+        idempotencyKey: string;
+        paymentIntentId: string;
+        sourceEventId: string;
+        failureReason: string | null;
+        occurredAt: string;
+    }): Promise<void>;
+}
+/**
+ * Neutral terminal handoff. Only explicit refusal evidence may enter dunning;
+ * silence, timeout and every other non-terminal answer are deliberate no-ops.
+ */
+export declare function handoffExplicitPaymentRefusal(input: PaymentRefusalHandoff, port: PaymentFailureDunningPort): Promise<void>;

package/dist/payments/paymentWebhookPostProcessing.js

@@ -0,0 +1,15 @@
+/**
+ * Neutral terminal handoff. Only explicit refusal evidence may enter dunning;
+ * silence, timeout and every other non-terminal answer are deliberate no-ops.
+ */
+export async function handoffExplicitPaymentRefusal(input, port) {
+    if (input.outcome !== "refused" || !input.paymentIntentId)
+        return;
+    await port.openFromExplicitRefusal({
+        idempotencyKey: input.idempotencyKey,
+        paymentIntentId: input.paymentIntentId,
+        sourceEventId: input.sourceEventId,
+        failureReason: input.failureReason,
+        occurredAt: input.occurredAt,
+    });
+}

package/dist/payments/postgresPaymentTruth.d.ts

@@ -0,0 +1,10 @@
+import type { PaymentTruthPort } from "./contracts/truth.js";
+import type { PostgresPaymentTruthOptions } from "./contracts/truth.js";
+interface PgQueryExecutor {
+    query(text: string, values?: unknown[]): Promise<{
+        rows: Record<string, unknown>[];
+    }>;
+}
+/** Direct-PG caller for the provider-neutral payment truth public forward. */
+export declare function createPostgresPaymentTruthPort(executor: PgQueryExecutor, options: PostgresPaymentTruthOptions): PaymentTruthPort;
+export {};