@openlup/platform 0.19.0 → 0.21.0

package/src/payments/postgresPaymentTruth.ts

@@ -0,0 +1,149 @@
+import type {
+  PaymentTruthPort,
+  PaymentTruthReadback,
+} from "./contracts/truth.js";
+import {
+  paymentReconciliationFingerprint,
+  paymentTruthFingerprint,
+} from "./paymentTruth.js";
+import type { PostgresPaymentTruthOptions } from "./contracts/truth.js";
+
+// Same structural executor as the platform data port; no driver or builder.
+interface PgQueryExecutor {
+  query(text: string, values?: unknown[]): Promise<{ rows: Record<string, unknown>[] }>;
+}
+
+const INGEST = `SELECT public.payment_truth_ingest_event(
+  $1,$2,$3,$4::uuid,$5,$6,$7,$8,$9,$10,$11::jsonb,$12,$13,$14) AS response`;
+const RECONCILE = `SELECT public.payment_truth_record_reconciliation(
+  $1::uuid,$2,$3,$4,$5,$6,$7,$8,$9::jsonb,$10,$11,$12) AS response`;
+const SWEEP = "SELECT public.payment_truth_sweep_open_events($1,$2) AS response";
+const READ = "SELECT public.payment_truth_readback($1::uuid,false) AS response";
+
+/** Direct-PG caller for the provider-neutral payment truth public forward. */
+export function createPostgresPaymentTruthPort(
+  executor: PgQueryExecutor,
+  options: PostgresPaymentTruthOptions,
+): PaymentTruthPort {
+  const dunningTemplateSlug = required(options.dunningTemplateSlug, "payment_truth_dunning_template_required");
+  const recoveryUrlPath = required(options.recoveryUrlPath, "payment_truth_recovery_path_required");
+  const recoveryTemplateSlug = required(options.recoveryTemplateSlug, "payment_truth_recovery_template_required");
+  return {
+    async ingestEvent(input) {
+      const response = first(await executor.query(INGEST, [
+        input.sourceEventId,
+        paymentTruthFingerprint(input),
+        input.idempotencyKey,
+        input.settlementIntentId,
+        input.outcome,
+        input.amountMinor,
+        input.currency,
+        input.occurredAt,
+        input.failure?.classification ?? null,
+        input.failure?.reason ?? null,
+        JSON.stringify(input.evidence),
+        dunningTemplateSlug,
+        recoveryUrlPath,
+        recoveryTemplateSlug,
+      ]));
+      return readback(response?.response);
+    },
+
+    async recordReconciliation(input) {
+      const response = first(await executor.query(RECONCILE, [
+        input.eventId,
+        input.idempotencyKey,
+        paymentReconciliationFingerprint(input),
+        input.evidenceStatus,
+        input.outcome,
+        input.occurredAt,
+        input.failure?.classification ?? null,
+        input.failure?.reason ?? null,
+        JSON.stringify(input.evidence),
+        dunningTemplateSlug,
+        recoveryUrlPath,
+        recoveryTemplateSlug,
+      ]));
+      return readback(response?.response);
+    },
+
+    async sweepOpenEvents(input) {
+      const response = record(first(await executor.query(SWEEP, [input.now, input.limit]))?.response);
+      return {
+        claimed: integer(response.claimed),
+        settledIgnored: integer(response.settledIgnored),
+        eventIds: Array.isArray(response.eventIds)
+          ? response.eventIds.filter((value): value is string => typeof value === "string")
+          : [],
+      };
+    },
+
+    async readEvent(eventId) {
+      const value = first(await executor.query(READ, [eventId]))?.response;
+      return value === null || value === undefined ? null : readback(value);
+    },
+  };
+}
+
+function readback(value: unknown): PaymentTruthReadback {
+  const root = record(value);
+  const event = record(root.event);
+  const effects = record(root.effects);
+  const financial = record(root.financial);
+  const outcome = event.outcome;
+  const state = event.state;
+  if (
+    typeof event.id !== "string"
+    || typeof event.sourceEventId !== "string"
+    || typeof event.fingerprint !== "string"
+    || (state !== "open" && state !== "settled")
+    || (outcome !== "captured" && outcome !== "refused" && outcome !== "indeterminate")
+    || typeof event.replayed !== "boolean"
+    || typeof effects.paymentResultRecorded !== "boolean"
+    || typeof effects.dunningOpened !== "boolean"
+    || typeof effects.accountingRequested !== "boolean"
+    || !Number.isSafeInteger(financial.amountMinor)
+    || typeof financial.currency !== "string"
+  ) throw new Error("payment_truth_readback_invalid");
+  return {
+    event: {
+      id: event.id,
+      sourceEventId: event.sourceEventId,
+      fingerprint: event.fingerprint,
+      state,
+      outcome,
+      replayed: event.replayed,
+    },
+    effects: {
+      paymentResultRecorded: effects.paymentResultRecorded,
+      dunningOpened: effects.dunningOpened,
+      accountingRequested: effects.accountingRequested,
+    },
+    financial: {
+      settlementStatus: nullableString(financial.settlementStatus),
+      orderStatus: nullableString(financial.orderStatus),
+      subscriptionStatus: nullableString(financial.subscriptionStatus),
+      accountingStatus: nullableString(financial.accountingStatus),
+      amountMinor: financial.amountMinor as number,
+      currency: financial.currency,
+    },
+  };
+}
+
+function first(result: { rows: Record<string, unknown>[] }): Record<string, unknown> | null {
+  return result.rows[0] ?? null;
+}
+function record(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : {};
+}
+function integer(value: unknown): number {
+  return typeof value === "number" && Number.isFinite(value) ? Math.max(0, Math.trunc(value)) : 0;
+}
+function nullableString(value: unknown): string | null {
+  return typeof value === "string" ? value : null;
+}
+function required(value: string, error: string): string {
+  const trimmed = value.trim();
+  if (!trimmed) throw new Error(error);
+  return trimmed;
+}

package/src/payments/preparedAttempt.ts

@@ -0,0 +1,90 @@
+import type { PaymentExecutionBaseInput, PaymentExecutionBaseResult } from "@openlup/core/payment";
+import type {
+  PreparedAttemptExecutionInput,
+  PreparedAttemptExecutionResult,
+  PreparedAttemptFailurePolicy,
+  PreparedAttemptPersistenceResult,
+} from "./contracts/preparedAttempt.js";
+import { finalizePreparedProviderAttempt } from "./preparedAttemptFinalization.js";
+
+/** Interactive ordering only; the caller binds nominal trust and native errors. */
+export async function executePreparedAttemptMechanism<
+  I extends PaymentExecutionBaseInput,
+  R extends PaymentExecutionBaseResult & { nextActionKind: N | null },
+  P extends string,
+  N extends string,
+  E extends Error,
+>(
+  input: PreparedAttemptExecutionInput<I, R, P, N>,
+  policy: PreparedAttemptFailurePolicy<E, N>,
+): Promise<PreparedAttemptExecutionResult<R>> {
+  // Reject deterministic local input/config errors before persisting a durable
+  // attempt. Only an actual PSP dispatch may create an indeterminate attempt.
+  input.executionPort.validateInput?.(input.executionInput);
+
+  const preparedAttempt = await input.paymentPort.prepareProviderAttempt({
+    idempotencyKey: input.prepareIdempotencyKey,
+    paymentIntentId: input.paymentIntentId,
+    provider: input.provider,
+    providerIdempotencyKey: input.providerIdempotencyKey,
+    providerRequestFingerprint: input.providerRequestFingerprint,
+    providerFlow: input.providerFlow,
+    paymentMethodRef: input.paymentMethodRef ?? null,
+    requestPayload: input.prepareRequestPayload,
+  });
+
+  if (preparedAttempt.replayed) {
+    throw policy.replayError(preparedAttempt);
+  }
+
+  let execution: R;
+  try {
+    execution = await input.executionPort.execute(input.executionInput);
+    input.validateExecution?.(execution);
+  } catch (error) {
+    if (policy.isTrustedNoCharge(error)) {
+      policy.logRetry(error, preparedAttempt);
+      try {
+        execution = await input.executionPort.execute(input.executionInput);
+        input.validateExecution?.(execution);
+      } catch (retryError) {
+        if (policy.isTrustedNoCharge(retryError)) {
+          throw policy.exhaustedError(retryError, error, preparedAttempt);
+        }
+        throw policy.executionError(retryError, preparedAttempt);
+      }
+    } else {
+      throw policy.executionError(error, preparedAttempt);
+    }
+  }
+
+  let finalizedAttempt: PreparedAttemptPersistenceResult<N>;
+  try {
+    const finalizeInput = {
+      idempotencyKey: input.finalizeIdempotencyKey,
+      paymentIntentId: input.paymentIntentId,
+      paymentAttemptId: preparedAttempt.paymentAttemptId,
+      providerIdempotencyKey: input.providerIdempotencyKey,
+      providerRequestFingerprint: input.providerRequestFingerprint,
+      providerAttemptId: execution.providerAttemptId,
+      providerSessionId: execution.providerSessionId,
+      attemptStatus: execution.attemptStatus,
+      nextActionKind: execution.nextActionKind,
+      requestPayload: execution.requestPayload,
+      responsePayload: execution.responsePayload,
+    };
+    finalizedAttempt = await finalizePreparedProviderAttempt(
+      () => input.paymentPort.finalizeProviderAttempt(finalizeInput),
+    );
+  } catch (error) {
+    throw policy.finalizationError(error, preparedAttempt);
+  }
+
+  return {
+    execution,
+    attempt: {
+      paymentAttemptId: finalizedAttempt.paymentAttemptId,
+      status: finalizedAttempt.status,
+    },
+  };
+}

package/src/payments/preparedAttemptFinalization.ts

@@ -0,0 +1,13 @@
+/**
+ * Replays one local idempotent finalize after its response is lost. The caller
+ * closes over one immutable payload, so this cannot issue another PSP request.
+ */
+export async function finalizePreparedProviderAttempt<T>(
+  finalize: () => Promise<T>,
+): Promise<T> {
+  try {
+    return await finalize();
+  } catch {
+    return finalize();
+  }
+}

package/src/payments/schemaCapabilities.ts

@@ -0,0 +1,10 @@
+/** Direct truth graph only; unsupported operations require a separate store. */
+export const paymentSchemaDescriptor = {
+  truth: "supported",
+  settlement: "supported",
+  laterOnlyCycle: "supported",
+  preparedDurableStore: "unsupported",
+  methodSetup: "unsupported",
+  absenceReopen: "unsupported",
+  cumulativeRefund: "unsupported",
+} as const;

package/src/payments/sql.ts

@@ -0,0 +1,6 @@
+/** Sparse projections of canonical units, never an install chain. */
+export const PAYMENT_MIGRATIONS = [
+  { id: "20260810180000_payment_settlement_rail", catalogPath: "db/platform/migrations/20260810180000_payment_settlement_rail.sql", position: 10, sha256: "af153aadedc09c07b25f69300d335d8928526cad126646c1b9bf25341f1c2d0e", url: new URL("../../sql/20260810180000_payment_settlement_rail.sql", import.meta.url) },
+  { id: "20260815150000_payment_truth_reconciliation", catalogPath: "db/platform/migrations/20260815150000_payment_truth_reconciliation.sql", position: 35, sha256: "dd38a601edc2f43f259eefc2cdb9af14fd37fe792a7f82e58c351bd373a88905", url: new URL("../../sql/20260815150000_payment_truth_reconciliation.sql", import.meta.url) },
+  { id: "20260826100000_late_payment_shifts_the_subscription_cycle", catalogPath: "db/platform/migrations/20260826100000_late_payment_shifts_the_subscription_cycle.sql", position: 56, sha256: "992540b0f49713d604859926624b3bef09d5075b68b604f069dcbd688328e452", url: new URL("../../sql/20260826100000_late_payment_shifts_the_subscription_cycle.sql", import.meta.url) },
+] as const;

package/src/payments/stripe/classifyDecline.ts

@@ -0,0 +1,62 @@
+import { classifyPaymentFailure, type PaymentExecutionProviderDecline, type PaymentFailureClassification, type PaymentFailureHint } from "@openlup/core/payment";
+export const DECLINE_FAILURE_REASONS = {
+  /** The payer's bank cannot register a reusable mandate — offer a card instead. */
+  mandateUnsupported: "blik_recurring_unsupported_bank",
+  /** Declined for a reason the provider did not distinguish. */
+  generic: "provider_declined",
+} as const;
+
+/** Maps a provider refusal to the stable code persisted as `failure_reason`. */
+export function declineFailureReason(decline: PaymentExecutionProviderDecline): string {
+  return decline.mandateUnsupported
+    ? DECLINE_FAILURE_REASONS.mandateUnsupported
+    : DECLINE_FAILURE_REASONS.generic;
+}
+
+/**
+ * The one place a refused payment gets a class, for every rail that consumes a
+ * synchronous decline: interactive checkout, checkout recovery, and the
+ * off-session renewal cron.
+ *
+ * Provider-agnostic on purpose. Every code the adapter understood has already
+ * been translated into `adviceCode` and `neutralReasonHints` by the adapter that
+ * owns the vocabulary, so nothing here needs to know which provider refused.
+ *
+ * The one reading this seam adds is the mandate flag. `mandateUnsupported` is a
+ * neutral capability statement any adapter may set, and it is what produces the
+ * scheme-named failure reason below; asserting the matching hint is what turns
+ * that reason into `mandate_dead` instead of leaving it unclassified. Doing it
+ * here rather than per adapter means a second adapter setting the same flag gets
+ * the same class without repeating the mapping.
+ *
+ * DISPLAY-LOAD-BEARING, and NOT a cadence input. Three live readers turn the
+ * class this seam decides into what the payer is told: `dunningFailureClassPort`
+ * reads it off the case, `customerAccountActionRequiredReadModel` selects it into
+ * the account surface, and `paymentRecoverySetupHandler` renders it as the cause
+ * sentence on the recovery page. What still does NOT read it is the retry ladder:
+ * no cadence, retry decision or scheduling branch consults the class, and that
+ * wave stays gated on validating this taxonomy against the historical corpus.
+ *
+ * `failureReasonKey` overrides the reason this seam would derive itself, and is
+ * supplied by a rail that persists a DIFFERENT reason string with the attempt:
+ * the reconciliation rail writes its own adapter-prefixed key, not
+ * `provider_declined`. That key is the classifier's weakest evidence tier, so
+ * the override changes a class only where the rail's own key is mapped; what it
+ * always changes is `decidedBy`, and that is the point. The historical-corpus
+ * replay reproduces a verdict from the stored attempt row, so the key named in
+ * the telemetry has to be the key actually on that row rather than one this seam
+ * invented for itself.
+ */
+export function classifyDecline(
+  decline: PaymentExecutionProviderDecline,
+  options: { failureReasonKey?: string } = {},
+): PaymentFailureClassification {
+  const asserted: PaymentFailureHint[] = [...(decline.neutralReasonHints ?? [])];
+  if (decline.mandateUnsupported) asserted.push("mandateUnsupported");
+  return classifyPaymentFailure({
+    adviceCode: decline.adviceCode,
+    declineCode: decline.declineCode,
+    neutralReasonHints: asserted,
+    failureReasonKey: options.failureReasonKey ?? declineFailureReason(decline),
+  });
+}

package/src/payments/stripe/declineFailureHints.ts

@@ -0,0 +1,89 @@
+import type { PaymentFailureHint } from "@openlup/core/payment";
+
+/**
+ * This adapter's own translation from its opaque refusal codes to the neutral
+ * hints the failure taxonomy accepts.
+ *
+ * The table lives here, in the adapter that owns the codes, and never in the
+ * neutral kernel: the kernel classifies evidence, and this file is what turns
+ * one acquirer's vocabulary into that evidence.
+ *
+ * It follows the published scheme research collected for the dunning programme.
+ * The class these hints produce is DISPLAY-load-bearing: it reaches the payer as
+ * the sentence explaining why the charge could not happen. It is still not a
+ * cadence input (nothing in the retry ladder branches on it), so a wrong row
+ * here costs a wrong sentence, not a wrong charge.
+ *
+ * Precedence note: this table is consulted only when the refusal carries NO
+ * issuer advice code. Advice is the verdict of the party that would refuse the
+ * next attempt, so it outranks anything read locally.
+ *
+ * Two deliberate silences, both from the research:
+ *   - `do_not_honor` and `generic_decline` get NO entry. They are the issuer's
+ *     way of declining without saying why, and they arrive on refusals that are
+ *     dead and on refusals that clear on the next attempt alike. Guessing either
+ *     way would invent a verdict; falling through to `indeterminate` is honest.
+ *   - `restricted_card` IS mapped, to `credentialDead`, and the caveat is
+ *     recorded rather than hidden: the research reads it as "this instrument may
+ *     not be used for this transaction", which the payer's bank can lift, so the
+ *     instrument is not necessarily finished. It is mapped anyway because every
+ *     reading of it agrees that repeating the identical charge unattended cannot
+ *     clear it, and that is the whole content of the class.
+ *
+ * The same caveat applies to `card_not_supported`, `currency_not_supported` and
+ * `transaction_not_allowed`: the credential may be perfectly alive and the
+ * refusal still final for the charge as submitted. `credentialDead` is chosen
+ * for the CLASS it yields, not as a claim about the plastic.
+ */
+export const DECLINE_CODE_HINT_TABLE: Readonly<Record<string, readonly PaymentFailureHint[]>> = Object.freeze({
+  approve_with_id: Object.freeze(["transient"] as const),
+  authentication_required: Object.freeze(["authenticationRequired"] as const),
+  card_not_supported: Object.freeze(["credentialDead"] as const),
+  card_velocity_exceeded: Object.freeze(["limitExceeded"] as const),
+  currency_not_supported: Object.freeze(["credentialDead"] as const),
+  expired_card: Object.freeze(["credentialDead"] as const),
+  fraudulent: Object.freeze(["credentialDead"] as const),
+  highest_risk_level: Object.freeze(["credentialDead"] as const),
+  incorrect_address: Object.freeze(["dataInvalid"] as const),
+  incorrect_cvc: Object.freeze(["dataInvalid"] as const),
+  incorrect_number: Object.freeze(["dataInvalid"] as const),
+  incorrect_zip: Object.freeze(["dataInvalid"] as const),
+  insufficient_funds: Object.freeze(["transient"] as const),
+  invalid_account: Object.freeze(["credentialDead"] as const),
+  invalid_amount: Object.freeze(["dataInvalid"] as const),
+  invalid_cvc: Object.freeze(["dataInvalid"] as const),
+  invalid_expiry_month: Object.freeze(["dataInvalid"] as const),
+  invalid_expiry_year: Object.freeze(["dataInvalid"] as const),
+  invalid_number: Object.freeze(["dataInvalid"] as const),
+  issuer_not_available: Object.freeze(["transient"] as const),
+  lost_card: Object.freeze(["credentialDead"] as const),
+  merchant_blacklist: Object.freeze(["credentialDead"] as const),
+  new_account_information_available: Object.freeze(["credentialDead"] as const),
+  pickup_card: Object.freeze(["credentialDead"] as const),
+  pin_try_exceeded: Object.freeze(["credentialDead"] as const),
+  processing_error: Object.freeze(["transient"] as const),
+  reenter_transaction: Object.freeze(["transient"] as const),
+  restricted_card: Object.freeze(["credentialDead"] as const),
+  revocation_of_all_authorizations: Object.freeze(["credentialDead"] as const),
+  revocation_of_authorization: Object.freeze(["credentialDead"] as const),
+  stolen_card: Object.freeze(["credentialDead"] as const),
+  stop_payment_order: Object.freeze(["credentialDead"] as const),
+  transaction_not_allowed: Object.freeze(["credentialDead"] as const),
+  try_again_later: Object.freeze(["transient"] as const),
+  withdrawal_count_limit_exceeded: Object.freeze(["limitExceeded"] as const),
+});
+
+/**
+ * The hints this adapter asserts for one refusal code. Own-property lookup, so
+ * an inherited key (`constructor`, `toString`) is not a mapping.
+ *
+ * The table itself is exported too, for a reader that holds a stored code and
+ * has no adapter in the loop: the historical-corpus replay hands it straight to
+ * the kernel's `declineCodeHints` option.
+ */
+export function declineCodeHints(declineCode: string | undefined): readonly PaymentFailureHint[] {
+  if (declineCode === undefined) return [];
+  return Object.prototype.hasOwnProperty.call(DECLINE_CODE_HINT_TABLE, declineCode)
+    ? DECLINE_CODE_HINT_TABLE[declineCode]
+    : [];
+}

package/src/payments/stripe/donorContracts.ts

@@ -0,0 +1,87 @@
+/** Private structural contracts for the unchanged execution and observation slices. */
+import type { PaymentExecutionBaseInput, PaymentExecutionBaseResult } from "@openlup/core/payment";
+import type { ProviderReadPurpose } from "../contracts/index.js";
+export type PaymentProviderFlow = "one_time_payment" | "setup_reusable_method" | "off_session_payment";
+export const PAYMENT_NEXT_ACTION_KINDS = ["redirect", "3ds_challenge", "sca_required"] as const;
+export type PaymentNextActionKind = (typeof PAYMENT_NEXT_ACTION_KINDS)[number];
+export interface PaymentExecutionInput extends PaymentExecutionBaseInput {
+  orderRef: string;
+  providerFlow?: PaymentProviderFlow;
+  customerRef?: string;
+  paymentMethodRef?: string;
+  saveForFutureUse?: boolean;
+  clientId?: string;
+}
+export interface PaymentExecutionResult extends PaymentExecutionBaseResult {
+  nextActionKind: PaymentNextActionKind | null;
+  clientSecret?: string | null;
+  customerProviderRef?: string | null;
+  paymentMethodRef?: string | null;
+  webhookExpected?: boolean;
+  recoveryRequired?: boolean;
+}
+export interface PaymentExecutionPort {
+  execute(input: PaymentExecutionInput): Promise<PaymentExecutionResult>;
+}
+export type PaymentWebhookEventType = "payment.succeeded" | "payment.failed" | "payment.refunded" |
+  "payment.requires_action" | "payment.disputed" | "setup.succeeded" | "setup.failed" | "setup.requires_action";
+export interface CanonicalPaymentEvent {
+  provider_event_id: string;
+  event_type: PaymentWebhookEventType;
+  payment_provider_id: string;
+  amount_minor?: number;
+  next_action_kind?: PaymentNextActionKind;
+  raw_payload: Record<string, unknown>;
+}
+export interface NormalizedProviderPaymentWebhook {
+  provider: string;
+  providerEventId: string;
+  eventType: PaymentWebhookEventType;
+  providerPaymentId: string;
+  paymentIntentId?: string | null;
+  paymentAttemptId?: string | null;
+  amountMinor?: number | null;
+  currency?: string | null;
+  occurredAt: string;
+  refundKind?: "full" | "partial" | null;
+  rawPayload: Record<string, unknown>;
+  reusableMethod?: {
+    clientId: string;
+    subscriptionId?: string | null;
+    providerCustomerRef?: string | null;
+    providerMethodRef: string;
+    providerMandateRef?: string | null;
+    methodKind: "card";
+    status: "active";
+    consentSnapshot?: Record<string, unknown>;
+  } | null;
+}
+export interface ProviderReconciliationStatus {
+  status: "succeeded" | "failed" | "pending" | "unknown";
+  providerStatus: string;
+  occurredAt: string | null;
+  failureReason: string | null;
+  amountMinor: number | null;
+  currency: string | null;
+  rawPayload: Record<string, unknown>;
+}
+export interface ClaimedPaymentAttempt {
+  paymentAttemptId: string; paymentIntentId: string; paymentId: string; orderId: string;
+  subscriptionId: string | null; subscriptionCycleId: string | null; provider: string;
+  providerPaymentId: string | null; providerAttemptId: string | null; providerSessionId: string | null;
+  attemptStatus: string; intentStatus: string; amountMinor: number; currency: string;
+  orderMode: "one_time" | "subscription_cycle"; cycleRetryAttempt: number; cycleNextRetryAt: string | null;
+  localUpdatedAt: string;
+}
+export type ProviderRecoveryAction = { kind: "provider_embedded"; provider: string; clientSecret: string };
+export interface PaymentProviderRecoveryProvider {
+  resolvePaymentReference(input: { providerAttemptId: string | null; intentProviderPaymentId: string | null;
+    providerSessionId: string | null }): string | null;
+  readPayment(input: { providerPaymentId: string; attempt?: ClaimedPaymentAttempt;
+    purpose?: ProviderReadPurpose }): Promise<ProviderReconciliationStatus>;
+  readRecoveryPayment(input: { providerPaymentId: string; attempt: ClaimedPaymentAttempt;
+    purpose?: ProviderReadPurpose }): Promise<{ status: ProviderReconciliationStatus; identityMatches: boolean;
+      configuredMoneyMatches: boolean; manualReviewRequired: boolean; clientAction: ProviderRecoveryAction | null }>;
+  closePayment?(input: { providerPaymentId: string }): Promise<ProviderReconciliationStatus>;
+  findPaymentByLocalIntent?(input: { attempt: ClaimedPaymentAttempt }): Promise<"found" | "absent">;
+}

package/src/payments/stripe/executionDecline.ts

@@ -0,0 +1,126 @@
+import { stripeFailureEvidence } from "./stripeFailureEvidence.js";
+import { failureEvidencePayload, type PaymentFailureEvidence } from "./paymentFailureEvidence.js";
+import type { PaymentExecutionResult } from "./donorContracts.js";
+import { declineCodeHints } from "./declineFailureHints.js";
+
+/**
+ * Normalization of a refusal the provider throws instead of returning.
+ *
+ * Split from the execution adapter because it is a different job: the adapter
+ * creates intents and reports what came back, this reads an exception and
+ * decides whether it is evidence of a refusal at all — the decision that keeps a
+ * possibly-paid charge out of the terminal `failed` path.
+ */
+
+/**
+ * The provider's error type for an issuer refusal, spelled exactly as the SDK
+ * sets it. Exported so the decline branch and its proofs cannot drift apart.
+ */
+export const PROVIDER_DECLINE_ERROR_TYPE = "StripeCardError";
+
+/** Used when the provider refuses without naming a code of its own. */
+const UNSPECIFIED_DECLINE_CODE = "provider_declined";
+
+/** What the adapter learned from a refusal: the fact itself plus its correlation handle. */
+export interface ExecutionDecline {
+  diagnosticFailureEvidence?: PaymentFailureEvidence;
+  decline: NonNullable<PaymentExecutionResult["providerDecline"]>;
+  /** The intent the provider had already created, when the refusal names one. */
+  providerAttemptId: string | null;
+  providerStatus: string | null;
+}
+
+/** The half of an execution result a refusal determines; the adapter owns the rest. */
+type DeclinedExecutionFacts = Omit<PaymentExecutionResult, "provider" | "requestPayload">;
+
+/**
+ * Reads an issuer refusal out of a thrown provider error, or returns null.
+ *
+ * Deliberately narrow: only the provider's own refusal type qualifies. Codes
+ * alone would not — an infrastructure error can also carry a `code`, and
+ * treating one as a decline would apply a terminal `failed` result to a charge
+ * that may have gone through.
+ */
+export function declineFromError(error: unknown): ExecutionDecline | null {
+  if (!error || typeof error !== "object") return null;
+  const raw = error as Record<string, unknown>;
+  if (raw.type !== PROVIDER_DECLINE_ERROR_TYPE) return null;
+  const intent = raw.payment_intent && typeof raw.payment_intent === "object"
+    ? raw.payment_intent as Record<string, unknown>
+    : null;
+  const declineCode = readOptionalString(raw, "decline_code");
+  const adviceCode = readOptionalString(raw, "advice_code");
+  // Translated here, where the code vocabulary is owned, so the control plane
+  // classifies the refusal without ever seeing an acquirer code.
+  const neutralReasonHints = declineCodeHints(declineCode);
+  const evidence = stripeFailureEvidence(raw, { source: "execution" });
+  return {
+    ...(evidence ? { diagnosticFailureEvidence: evidence } : {}),
+    decline: {
+      code: readOptionalString(raw, "code") ?? UNSPECIFIED_DECLINE_CODE,
+      // Reserved for a payer bank that cannot hold a reusable mandate at all.
+      // A refused charge on an already-registered method proves the opposite,
+      // so this rail never claims it.
+      mandateUnsupported: false,
+      ...(declineCode ? { declineCode } : {}),
+      ...(adviceCode ? { adviceCode } : {}),
+      ...(neutralReasonHints.length > 0 ? { neutralReasonHints } : {}),
+    },
+    providerAttemptId: intent ? readOptionalString(intent, "id") ?? null : null,
+    providerStatus: intent ? readOptionalString(intent, "status") ?? null : null,
+  };
+}
+
+/**
+ * Turns a refusal into attempt facts, DELIBERATELY without a correlation handle.
+ *
+ * `attemptStatus` stays non-terminal by contract — only the control plane makes
+ * terminal transitions, and it does so from `providerDecline`.
+ *
+ * The refused intent's id is reported ONLY inside `responsePayload`, never as
+ * `providerAttemptId`. That is not an oversight: event ingest matches a callback
+ * to an attempt by `provider_attempt_id`, and the control plane's failed branch
+ * has no guard against applying `failed` to an already-failed intent. So a
+ * correlation handle would let the provider's later failure callback re-apply the
+ * same refusal under its own idempotency key — advancing the retry ladder a
+ * second rung, rewriting the failure reason, and sending the customer a second
+ * dunning email minutes after the first. Until that branch is idempotent
+ * (planned PR-0c), a refusal this rail already reported must stay uncorrelated,
+ * and the callback must stay inert.
+ */
+export function declinedExecutionFacts(declined: ExecutionDecline): DeclinedExecutionFacts {
+  const { decline, providerAttemptId, providerStatus } = declined;
+  return {
+    providerAttemptId: null,
+    providerSessionId: null,
+    attemptStatus: "processing",
+    nextActionKind: null,
+    providerDecline: decline,
+    clientSecret: null,
+    customerProviderRef: null,
+    paymentMethodRef: null,
+    // This rail already reported the refusal synchronously; the callback that
+    // repeats it must not be waited for, and must not be able to land twice.
+    webhookExpected: false,
+    recoveryRequired: false,
+    responsePayload: {
+      // Forensics only. This payload is stored on the attempt but nothing joins
+      // on it, so an operator can still trace the refused intent by hand without
+      // the ingest matcher ever finding it.
+      providerStatus,
+      providerAttemptId,
+      providerDeclined: true,
+      ...failureEvidencePayload(declined.diagnosticFailureEvidence),
+      // Codes only, never the provider's message: that text is free-form and can
+      // carry payer-identifying detail, and this payload is persisted and logged.
+      providerErrorCodes: [decline.code, decline.declineCode, decline.adviceCode].filter(
+        (code): code is string => Boolean(code),
+      ),
+    },
+  };
+}
+
+function readOptionalString(value: Record<string, unknown>, key: string): string | undefined {
+  const raw = value[key];
+  return typeof raw === "string" && raw.length > 0 ? raw : undefined;
+}