@openlup/platform 0.19.0 → 0.21.0

package/dist/payments/paymentAttemptSilenceWindow.d.ts

@@ -0,0 +1,10 @@
+import type { ClaimedPaymentAttempt, SilenceWindowLookup } from "./contracts/reconciliation.js";
+/**
+ * Whether this rail has answered non-terminally for longer than it declares
+ * normal. The window comes from the rail's published capability - never a
+ * provider identity, never a global constant, because a pushed-event rail and a
+ * polled rail have genuinely different normal silences and a self-hoster
+ * declares their own. Absent or unusable means never overdue: stay quiet rather
+ * than accuse a healthy rail.
+ */
+export declare function silenceIsOverdue(capabilities: SilenceWindowLookup | undefined, attempt: ClaimedPaymentAttempt, now: string): boolean;

package/dist/payments/paymentAttemptSilenceWindow.js

@@ -0,0 +1,19 @@
+/**
+ * Whether this rail has answered non-terminally for longer than it declares
+ * normal. The window comes from the rail's published capability - never a
+ * provider identity, never a global constant, because a pushed-event rail and a
+ * polled rail have genuinely different normal silences and a self-hoster
+ * declares their own. Absent or unusable means never overdue: stay quiet rather
+ * than accuse a healthy rail.
+ */
+export function silenceIsOverdue(capabilities, attempt, now) {
+    const minutes = capabilities?.get(attempt.provider)?.terminalOutcomeReporting
+        ?.silenceBecomesSuspectAfterMinutes;
+    if (typeof minutes !== "number" || !Number.isFinite(minutes) || minutes <= 0)
+        return false;
+    const since = Date.parse(attempt.localUpdatedAt);
+    const at = Date.parse(now);
+    if (!Number.isFinite(since) || !Number.isFinite(at))
+        return false;
+    return at - since >= minutes * 60_000;
+}

package/dist/payments/paymentMethodLifecycle.d.ts

@@ -0,0 +1,11 @@
+import { type PaymentMethodLifecycleEvent, type PaymentMethodReplacementFacts } from "@openlup/core/payment";
+import type { NormalizedProviderPaymentWebhook } from "./verifiedIngress.js";
+export interface ProviderWebhookWithMethodLifecycle extends NormalizedProviderPaymentWebhook {
+    methodLifecycle?: PaymentMethodLifecycleEvent | null;
+}
+export declare const METHOD_SCHEME_SNAPSHOT_KEY = "methodScheme";
+export declare const METHOD_LAST_DIGITS_SNAPSHOT_KEY = "methodLastDigits";
+export declare const METHOD_EXPIRES_AT_SNAPSHOT_KEY = "methodExpiresAt";
+export declare function methodFactSnapshotKeys(facts: PaymentMethodReplacementFacts | null | undefined): Record<string, unknown>;
+export declare function expiryForMethodRefWrite(consentSnapshot: Record<string, unknown> | undefined, occurredAt: string, active: boolean): string | null;
+export declare function readMethodLifecycleEvent(event: NormalizedProviderPaymentWebhook): PaymentMethodLifecycleEvent | null;

package/dist/payments/paymentMethodLifecycle.js

@@ -0,0 +1,37 @@
+import { isPaymentMethodLifecycleEventKind, } from "@openlup/core/payment";
+export const METHOD_SCHEME_SNAPSHOT_KEY = "methodScheme";
+export const METHOD_LAST_DIGITS_SNAPSHOT_KEY = "methodLastDigits";
+export const METHOD_EXPIRES_AT_SNAPSHOT_KEY = "methodExpiresAt";
+export function methodFactSnapshotKeys(facts) {
+    if (!facts)
+        return {};
+    return {
+        ...(facts.schemeLabel ? { [METHOD_SCHEME_SNAPSHOT_KEY]: facts.schemeLabel } : {}),
+        ...(facts.lastDigits ? { [METHOD_LAST_DIGITS_SNAPSHOT_KEY]: facts.lastDigits } : {}),
+        ...(facts.expiresAt ? { [METHOD_EXPIRES_AT_SNAPSHOT_KEY]: facts.expiresAt } : {}),
+    };
+}
+export function expiryForMethodRefWrite(consentSnapshot, occurredAt, active) {
+    const raw = consentSnapshot?.[METHOD_EXPIRES_AT_SNAPSHOT_KEY];
+    if (typeof raw !== "string" || !raw.trim())
+        return null;
+    const expiry = Date.parse(raw);
+    if (!Number.isFinite(expiry))
+        return null;
+    if (!active)
+        return raw;
+    const reference = Date.parse(occurredAt);
+    return Number.isFinite(reference) && expiry <= reference ? null : raw;
+}
+export function readMethodLifecycleEvent(event) {
+    const candidate = event.methodLifecycle;
+    if (!candidate || typeof candidate !== "object")
+        return null;
+    if (!isPaymentMethodLifecycleEventKind(candidate.kind))
+        return null;
+    if (!candidate.providerKind?.trim() || !candidate.providerMethodRef?.trim())
+        return null;
+    if (!candidate.providerEventId?.trim() || !candidate.occurredAt?.trim())
+        return null;
+    return candidate;
+}

package/dist/payments/paymentProviderReconciliationAbsenceReopen.d.ts

@@ -0,0 +1,7 @@
+import type { ClaimedPaymentAttempt, PaymentProviderReconciliationWorkerInput } from "./contracts/reconciliation.js";
+/** Reopen only after genuine provider-side absence proof. A missing local
+ * acknowledgement cannot exclude a charge before reference persistence failed;
+ * minting a fresh idempotency key in that crash window could double-charge.
+ * Providers without an exact absence probe require operator review.
+ */
+export declare function tryReopenPreparedAbsence(input: PaymentProviderReconciliationWorkerInput, attempt: ClaimedPaymentAttempt, now: string): Promise<boolean>;

package/dist/payments/paymentProviderReconciliationAbsenceReopen.js

@@ -0,0 +1,100 @@
+import { absenceProbeEvidenceKey, absenceReopenKey, safeMessage, } from "./paymentProviderReconciliationEvidence.js";
+// Mirrors the RPC's v_min_stranded_age guard (migration 20260711153000). The
+// worker pre-checks so an under-age attempt is a silent skip for this pass
+// instead of a guaranteed `prepared_attempt_absence_reopen_too_fresh` reject.
+const MIN_PREPARED_ABSENCE_REOPEN_AGE_SECONDS = 30 * 60;
+/** Reopen only after genuine provider-side absence proof. A missing local
+ * acknowledgement cannot exclude a charge before reference persistence failed;
+ * minting a fresh idempotency key in that crash window could double-charge.
+ * Providers without an exact absence probe require operator review.
+ */
+export async function tryReopenPreparedAbsence(input, attempt, now) {
+    // Reopen schedules another subscription-cycle charge. One-time prepared
+    // attempts remain operator-manual so this path can never create a blind
+    // second provider call for them.
+    if (attempt.orderMode !== "subscription_cycle" || !attempt.subscriptionCycleId)
+        return false;
+    const subscriptionCycleId = attempt.subscriptionCycleId;
+    const provider = input.providers[attempt.provider];
+    // Without an exact absence probe, stranded attempts stay operator-manual.
+    // Guessing absence could schedule a second charge.
+    if (!provider?.findPaymentByLocalIntent)
+        return false;
+    const ageMs = Date.parse(now) - Date.parse(attempt.localUpdatedAt);
+    if (!Number.isFinite(ageMs) || ageMs < MIN_PREPARED_ABSENCE_REOPEN_AGE_SECONDS * 1000) {
+        // Under the RPC's stranded-age guard — the next configured reconciliation pass catches it.
+        return false;
+    }
+    let probe;
+    try {
+        probe = await provider.findPaymentByLocalIntent({ attempt });
+    }
+    catch (error) {
+        await recordProbeEvidence(input, attempt, now, "absence_probe_failed", {
+            probeError: safeMessage(error),
+            operatorReviewRequired: true,
+        });
+        return false;
+    }
+    if (probe === "found") {
+        // Crash-after-charge window: the provider HAS a payment for this intent
+        // but our attempt never recorded it. Reopening would double-charge —
+        // leave it for operator ref-repair; the stale-attempt readback path takes
+        // over once refs are restored.
+        await recordProbeEvidence(input, attempt, now, "provider_payment_found_after_prepare", {
+            providerAbsenceConfirmed: false,
+            operatorReviewRequired: true,
+            reopenBlocked: "provider_payment_exists",
+        });
+        return false;
+    }
+    try {
+        await input.port.reopenPreparedAttemptAfterAbsence({
+            idempotencyKey: absenceReopenKey(attempt),
+            paymentAttemptId: attempt.paymentAttemptId,
+            expectedPaymentIntentId: attempt.paymentIntentId,
+            expectedSubscriptionCycleId: subscriptionCycleId,
+            operatorRef: "payment-provider-reconciliation@auto",
+            absenceCheckedAt: now,
+            nextRetryAt: now,
+            absenceEvidence: {
+                providerAbsenceConfirmed: true,
+                source: "payment-provider-reconciliation.auto-reopen.v0",
+                basis: `${attempt.provider}_intent_correlated_search_absent`,
+                probedAt: now,
+            },
+        });
+        // The RPC records its own 'prepared_attempt_provider_absent' corrected
+        // evidence, cancels the attempt, and requeues the cycle — nothing more to
+        // write here.
+        return true;
+    }
+    catch (error) {
+        const message = safeMessage(error);
+        // The RPC's 22023 precondition rejects (too_fresh, provider_event_exists,
+        // terminal reconciliation, state drift since claim, ...) are expected
+        // races, not run failures — the attempt stays operator-visible either way.
+        await recordProbeEvidence(input, attempt, now, message.includes("prepared_attempt_absence_reopen_")
+            ? "absence_reopen_precondition_reject"
+            : "absence_reopen_failed", { reopenError: message, operatorReviewRequired: true });
+        return false;
+    }
+}
+function recordProbeEvidence(input, attempt, now, providerStatus, extra) {
+    return input.port.recordEvidence({
+        idempotencyKey: absenceProbeEvidenceKey(attempt, now),
+        provider: attempt.provider,
+        providerPaymentId: null,
+        paymentIntentId: attempt.paymentIntentId,
+        paymentAttemptId: attempt.paymentAttemptId,
+        localStatus: attempt.attemptStatus,
+        providerStatus,
+        correctionStatus: "observed",
+        checkedAt: now,
+        payload: {
+            source: "payment-provider-reconciliation.auto-reopen.v0",
+            provider: attempt.provider,
+            ...extra,
+        },
+    });
+}

package/dist/payments/paymentProviderReconciliationEvidence.d.ts

@@ -0,0 +1,36 @@
+import type { ClaimedPaymentAttempt, ProviderReconciliationStatus, ProviderReconciliationStatusKind } from "./contracts/reconciliation.js";
+export declare function evidencePayload(attempt: ClaimedPaymentAttempt, providerStatus: ProviderReconciliationStatus, extra: Record<string, unknown>): Record<string, unknown>;
+export declare function terminalAmountMismatch(attempt: ClaimedPaymentAttempt, status: ProviderReconciliationStatus): string | null;
+export declare function applyResultKey(attempt: ClaimedPaymentAttempt, status: "succeeded" | "failed"): string;
+export declare function observedEvidenceKey(attempt: ClaimedPaymentAttempt, status: ProviderReconciliationStatusKind, correction: "observed" | "failed", checkedAt: string): string;
+export declare function preparedAttemptEvidenceKey(attempt: ClaimedPaymentAttempt, checkedAt: string): string;
+export declare function absenceReopenKey(attempt: ClaimedPaymentAttempt): string;
+export declare function absenceProbeEvidenceKey(attempt: ClaimedPaymentAttempt, checkedAt: string): string;
+export declare function bucket(value: string): string;
+export declare function clamp(value: number, min: number, max: number): number;
+export declare function safeMessage(error: unknown): string;
+/**
+ * The class the reading adapter already decided, read back off the normalized
+ * status so the terminal write can carry it.
+ *
+ * READ, never re-derived. Both shipped adapters classify what they read through
+ * the shared `classifyDecline` seam and put the verdict in `rawPayload`; deriving
+ * a second one here would be a second classifier, free to disagree with the one
+ * whose reasoning the evidence payload records. It is also why this function is
+ * provider-agnostic: it never learns which rail refused, only what that rail
+ * concluded.
+ *
+ * Returns a spreadable fragment rather than a nullable value, so an unclassified
+ * refusal leaves the key genuinely ABSENT from the composed call instead of
+ * present-and-null. Absence is what the port's contract defines as "behave
+ * exactly as before the field existed", and it is what the two non-classifying
+ * consumers of that contract are pinned to.
+ *
+ * A success carries no class by construction: there is no refusal to classify.
+ */
+export declare function classificationOf(resultStatus: "succeeded" | "failed", providerStatus: ProviderReconciliationStatus): {
+    failureClassification?: {
+        failureClass: string;
+        decidedBy: string;
+    };
+};

package/dist/payments/paymentProviderReconciliationEvidence.js

@@ -0,0 +1,91 @@
+export function evidencePayload(attempt, providerStatus, extra) {
+    return {
+        source: "payment-provider-reconciliation.v0",
+        provider: attempt.provider,
+        providerPaymentId: attempt.providerPaymentId,
+        paymentIntentId: attempt.paymentIntentId,
+        paymentAttemptId: attempt.paymentAttemptId,
+        orderId: attempt.orderId,
+        subscriptionId: attempt.subscriptionId,
+        subscriptionCycleId: attempt.subscriptionCycleId,
+        localAttemptStatus: attempt.attemptStatus,
+        localIntentStatus: attempt.intentStatus,
+        providerStatus: providerStatus.providerStatus,
+        normalizedStatus: providerStatus.status,
+        failureReason: providerStatus.failureReason,
+        amountMinorPresent: providerStatus.amountMinor !== null,
+        currency: providerStatus.currency,
+        providerPayload: providerStatus.rawPayload,
+        ...extra,
+    };
+}
+export function terminalAmountMismatch(attempt, status) {
+    if (status.amountMinor !== null && status.amountMinor !== attempt.amountMinor) {
+        return "provider_amount_mismatch";
+    }
+    if (status.currency && status.currency.toUpperCase() !== attempt.currency.toUpperCase()) {
+        return "provider_currency_mismatch";
+    }
+    return null;
+}
+export function applyResultKey(attempt, status) {
+    return `payment-provider-reconciliation:${attempt.paymentAttemptId}:apply:${status}`;
+}
+export function observedEvidenceKey(attempt, status, correction, checkedAt) {
+    return `payment-provider-reconciliation:${attempt.paymentAttemptId}:${correction}:${status}:${bucket(checkedAt)}`;
+}
+export function preparedAttemptEvidenceKey(attempt, checkedAt) {
+    return `payment-provider-reconciliation:${attempt.paymentAttemptId}:failed:prepared_without_provider_ack:${bucket(checkedAt)}`;
+}
+// Stable (no time bucket): a successful reopen cancels the attempt (it leaves
+// `created`), so the RPC is called at most once per attempt; replays after a
+// crash return the recorded response via commerce_idempotency_keys.
+export function absenceReopenKey(attempt) {
+    return `payment-provider-reconciliation:${attempt.paymentAttemptId}:absence-reopen`;
+}
+export function absenceProbeEvidenceKey(attempt, checkedAt) {
+    return `payment-provider-reconciliation:${attempt.paymentAttemptId}:absence-probe:${bucket(checkedAt)}`;
+}
+export function bucket(value) {
+    const ms = Date.parse(value);
+    if (!Number.isFinite(ms))
+        return "unknown";
+    return String(Math.floor(ms / (30 * 60 * 1000)));
+}
+export function clamp(value, min, max) {
+    if (!Number.isFinite(value))
+        return min;
+    return Math.max(min, Math.min(max, Math.trunc(value)));
+}
+export function safeMessage(error) {
+    return (error instanceof Error ? error.message : String(error)).slice(0, 240);
+}
+/**
+ * The class the reading adapter already decided, read back off the normalized
+ * status so the terminal write can carry it.
+ *
+ * READ, never re-derived. Both shipped adapters classify what they read through
+ * the shared `classifyDecline` seam and put the verdict in `rawPayload`; deriving
+ * a second one here would be a second classifier, free to disagree with the one
+ * whose reasoning the evidence payload records. It is also why this function is
+ * provider-agnostic: it never learns which rail refused, only what that rail
+ * concluded.
+ *
+ * Returns a spreadable fragment rather than a nullable value, so an unclassified
+ * refusal leaves the key genuinely ABSENT from the composed call instead of
+ * present-and-null. Absence is what the port's contract defines as "behave
+ * exactly as before the field existed", and it is what the two non-classifying
+ * consumers of that contract are pinned to.
+ *
+ * A success carries no class by construction: there is no refusal to classify.
+ */
+export function classificationOf(resultStatus, providerStatus) {
+    if (resultStatus !== "failed")
+        return {};
+    const { failureClass, failureClassDecidedBy } = providerStatus.rawPayload;
+    if (typeof failureClass !== "string" || failureClass.length === 0)
+        return {};
+    if (typeof failureClassDecidedBy !== "string" || failureClassDecidedBy.length === 0)
+        return {};
+    return { failureClassification: { failureClass, decidedBy: failureClassDecidedBy } };
+}

package/dist/payments/paymentProviderReconciliationWorker.d.ts

@@ -0,0 +1,4 @@
+import type { PaymentProviderReconciliationWorkerInput, PaymentProviderReconciliationWorkerResult } from "./contracts/reconciliation.js";
+export type { ClaimedPaymentAttempt, PaymentProviderReconciliationPort, PaymentProviderReconciliationProvider, PaymentProviderReconciliationWorkerInput, PaymentProviderReconciliationWorkerResult, ProviderReconciliationStatus, ProviderReconciliationStatusKind, ReconciliationProviderKind, SilenceWindowLookup, } from "./contracts/reconciliation.js";
+export declare const DEFAULT_STALE_AFTER_SECONDS: number;
+export declare function runPaymentProviderReconciliationWorker(input: PaymentProviderReconciliationWorkerInput): Promise<PaymentProviderReconciliationWorkerResult>;

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;