@openlup/platform 0.19.0 → 0.21.0

package/dist/payments/sql.js

@@ -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) },
+];

package/dist/payments/stripe/classifyDecline.d.ts

@@ -0,0 +1,46 @@
+import { type PaymentExecutionProviderDecline, type PaymentFailureClassification } from "@openlup/core/payment";
+export declare const DECLINE_FAILURE_REASONS: {
+    /** The payer's bank cannot register a reusable mandate — offer a card instead. */
+    readonly mandateUnsupported: "blik_recurring_unsupported_bank";
+    /** Declined for a reason the provider did not distinguish. */
+    readonly generic: "provider_declined";
+};
+/** Maps a provider refusal to the stable code persisted as `failure_reason`. */
+export declare function declineFailureReason(decline: PaymentExecutionProviderDecline): string;
+/**
+ * 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 declare function classifyDecline(decline: PaymentExecutionProviderDecline, options?: {
+    failureReasonKey?: string;
+}): PaymentFailureClassification;

package/dist/payments/stripe/classifyDecline.js

@@ -0,0 +1,58 @@
+import { classifyPaymentFailure } 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",
+};
+/** Maps a provider refusal to the stable code persisted as `failure_reason`. */
+export function declineFailureReason(decline) {
+    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, options = {}) {
+    const asserted = [...(decline.neutralReasonHints ?? [])];
+    if (decline.mandateUnsupported)
+        asserted.push("mandateUnsupported");
+    return classifyPaymentFailure({
+        adviceCode: decline.adviceCode,
+        declineCode: decline.declineCode,
+        neutralReasonHints: asserted,
+        failureReasonKey: options.failureReasonKey ?? declineFailureReason(decline),
+    });
+}

package/dist/payments/stripe/declineFailureHints.d.ts

@@ -0,0 +1,46 @@
+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 declare const DECLINE_CODE_HINT_TABLE: Readonly<Record<string, readonly PaymentFailureHint[]>>;
+/**
+ * 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 declare function declineCodeHints(declineCode: string | undefined): readonly PaymentFailureHint[];

package/dist/payments/stripe/declineFailureHints.js

@@ -0,0 +1,87 @@
+/**
+ * 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 = Object.freeze({
+    approve_with_id: Object.freeze(["transient"]),
+    authentication_required: Object.freeze(["authenticationRequired"]),
+    card_not_supported: Object.freeze(["credentialDead"]),
+    card_velocity_exceeded: Object.freeze(["limitExceeded"]),
+    currency_not_supported: Object.freeze(["credentialDead"]),
+    expired_card: Object.freeze(["credentialDead"]),
+    fraudulent: Object.freeze(["credentialDead"]),
+    highest_risk_level: Object.freeze(["credentialDead"]),
+    incorrect_address: Object.freeze(["dataInvalid"]),
+    incorrect_cvc: Object.freeze(["dataInvalid"]),
+    incorrect_number: Object.freeze(["dataInvalid"]),
+    incorrect_zip: Object.freeze(["dataInvalid"]),
+    insufficient_funds: Object.freeze(["transient"]),
+    invalid_account: Object.freeze(["credentialDead"]),
+    invalid_amount: Object.freeze(["dataInvalid"]),
+    invalid_cvc: Object.freeze(["dataInvalid"]),
+    invalid_expiry_month: Object.freeze(["dataInvalid"]),
+    invalid_expiry_year: Object.freeze(["dataInvalid"]),
+    invalid_number: Object.freeze(["dataInvalid"]),
+    issuer_not_available: Object.freeze(["transient"]),
+    lost_card: Object.freeze(["credentialDead"]),
+    merchant_blacklist: Object.freeze(["credentialDead"]),
+    new_account_information_available: Object.freeze(["credentialDead"]),
+    pickup_card: Object.freeze(["credentialDead"]),
+    pin_try_exceeded: Object.freeze(["credentialDead"]),
+    processing_error: Object.freeze(["transient"]),
+    reenter_transaction: Object.freeze(["transient"]),
+    restricted_card: Object.freeze(["credentialDead"]),
+    revocation_of_all_authorizations: Object.freeze(["credentialDead"]),
+    revocation_of_authorization: Object.freeze(["credentialDead"]),
+    stolen_card: Object.freeze(["credentialDead"]),
+    stop_payment_order: Object.freeze(["credentialDead"]),
+    transaction_not_allowed: Object.freeze(["credentialDead"]),
+    try_again_later: Object.freeze(["transient"]),
+    withdrawal_count_limit_exceeded: Object.freeze(["limitExceeded"]),
+});
+/**
+ * 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) {
+    if (declineCode === undefined)
+        return [];
+    return Object.prototype.hasOwnProperty.call(DECLINE_CODE_HINT_TABLE, declineCode)
+        ? DECLINE_CODE_HINT_TABLE[declineCode]
+        : [];
+}

package/dist/payments/stripe/donorContracts.d.ts

@@ -0,0 +1,120 @@
+/** 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 declare const PAYMENT_NEXT_ACTION_KINDS: readonly ["redirect", "3ds_challenge", "sca_required"];
+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/dist/payments/stripe/donorContracts.js

@@ -0,0 +1 @@
+export const PAYMENT_NEXT_ACTION_KINDS = ["redirect", "3ds_challenge", "sca_required"];

package/dist/payments/stripe/executionDecline.d.ts

@@ -0,0 +1,53 @@
+import { type PaymentFailureEvidence } from "./paymentFailureEvidence.js";
+import type { PaymentExecutionResult } from "./donorContracts.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 declare const PROVIDER_DECLINE_ERROR_TYPE = "StripeCardError";
+/** 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 declare function declineFromError(error: unknown): ExecutionDecline | 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 declare function declinedExecutionFacts(declined: ExecutionDecline): DeclinedExecutionFacts;
+export {};

package/dist/payments/stripe/executionDecline.js

@@ -0,0 +1,107 @@
+import { stripeFailureEvidence } from "./stripeFailureEvidence.js";
+import { failureEvidencePayload } from "./paymentFailureEvidence.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";
+/**
+ * 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) {
+    if (!error || typeof error !== "object")
+        return null;
+    const raw = error;
+    if (raw.type !== PROVIDER_DECLINE_ERROR_TYPE)
+        return null;
+    const intent = raw.payment_intent && typeof raw.payment_intent === "object"
+        ? raw.payment_intent
+        : 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) {
+    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) => Boolean(code)),
+        },
+    };
+}
+function readOptionalString(value, key) {
+    const raw = value[key];
+    return typeof raw === "string" && raw.length > 0 ? raw : undefined;
+}

package/dist/payments/stripe/index.d.ts

@@ -0,0 +1,16 @@
+import type { PaymentAdapter, PaymentAdapterCapabilities } from "../contracts/index.js";
+import { type StripeSandboxClient } from "./stripeSandboxPaymentExecutionAdapter.js";
+import { type StripePaymentIntentReader } from "./stripePaymentReconciliationProvider.js";
+/** Host-owned client, credentials, SDK construction and mode policy. clock returns UTC seconds. */
+export interface StripePaymentAdapterConfig {
+    client: Omit<StripeSandboxClient, "createSetupIntent"> & Partial<Pick<StripeSandboxClient, "createSetupIntent">> & StripePaymentIntentReader;
+    webhookSigningSecrets: readonly string[];
+    mode: "live" | "test";
+    supportedCurrencies: readonly string[];
+    toleranceSeconds?: number;
+    clock?: () => number;
+}
+/** Observed protocol capabilities; account activation remains host-owned. */
+export declare const stripePaymentCapabilities: Readonly<PaymentAdapterCapabilities>;
+/** Explicit construction is the only activation point; importing performs no I/O. */
+export declare function createStripePaymentAdapter(config: StripePaymentAdapterConfig): PaymentAdapter;