@openlup/core 0.0.0 → 0.6.0

package/src/payment/paymentFailureTaxonomy.ts

@@ -0,0 +1,201 @@
+import {
+  PAYMENT_FAILURE_HINTS,
+  PAYMENT_RETRY_ADVICE_CODES,
+  type PaymentFailureClass,
+  type PaymentFailureEvidence,
+  type PaymentFailureHint,
+} from "./paymentFailureTaxonomyContracts.js";
+
+/**
+ * Pure classification of a refused payment into {@link PaymentFailureClass}.
+ *
+ * No clock, no input/output, no acquirer code tables: everything the verdict
+ * depends on arrives in {@link PaymentFailureEvidence}, so the same evidence
+ * always produces the same class and a test can enumerate the whole surface.
+ *
+ * Nothing consumes this yet. It is the contract the adapter mappings and the
+ * cadence branching are written against, landed first and on its own so the
+ * table can be reviewed as a table rather than as a diff inside a scheduler.
+ */
+
+/** Which rule produced the class. Published so a precedence conflict is assertable, not inferred from the class alone. */
+/** @beta */
+export const PAYMENT_FAILURE_CLASSIFICATION_SOURCES = [
+  "advice_code",
+  "neutral_hint",
+  "failure_reason_key",
+  "default",
+] as const;
+/** @beta */
+export type PaymentFailureClassificationSource =
+  (typeof PAYMENT_FAILURE_CLASSIFICATION_SOURCES)[number];
+
+/** @beta */
+export interface PaymentFailureClassification {
+  failureClass: PaymentFailureClass;
+  decidedBy: PaymentFailureClassificationSource;
+}
+
+/** @beta */
+export interface PaymentFailureClassificationOptions {
+  /**
+   * The adapter's own translation from its opaque decline codes to neutral
+   * hints. Supplied per call because the codes belong to the adapter, never to
+   * this kernel. Keys are matched exactly, so the adapter owns normalization.
+   */
+  declineCodeHints?: Readonly<Record<string, readonly PaymentFailureHint[]>>;
+}
+
+const ADVICE_CLASSES: Readonly<Record<string, PaymentFailureClass>> = Object.freeze({
+  do_not_try_again: "hard_do_not_retry",
+  confirm_card_data: "fix_and_retry_customer_action",
+  try_again_later: "soft_retryable",
+});
+
+const HINT_CLASSES: Readonly<Record<PaymentFailureHint, PaymentFailureClass>> = Object.freeze({
+  credentialDead: "hard_do_not_retry",
+  mandateUnsupported: "mandate_dead",
+  authenticationRequired: "sca_required",
+  dataInvalid: "fix_and_retry_customer_action",
+  limitExceeded: "soft_retry_delayed",
+  transient: "soft_retryable",
+});
+
+/**
+ * The internal reason strings already persisted by the control plane.
+ *
+ * The `provider_*` four resolve to `indeterminate` on purpose: they record THAT
+ * the charge failed and by which rail the news arrived, never WHY the issuer
+ * refused. Mapping them to anything softer would invent a verdict that was never
+ * returned. They are listed rather than left to the default so the absence of
+ * information is pinned by a test instead of re-derived by each reader.
+ *
+ * The rest are renewal PREFLIGHT reasons: refusals reached on local evidence,
+ * before any rail is asked. They belong here for the reason
+ * `off_session_sca_required` does — the key IS the whole evidence, there is no
+ * issuer verdict to defer to, and each states something about the stored method
+ * rather than about one scheme's vocabulary.
+ *
+ * A key naming a specific scheme belongs to the adapter that owns it, which
+ * asserts the matching neutral hint instead. Hence the vendor-prefixed preflight
+ * reasons are absent: they resolve to `indeterminate` until that adapter maps
+ * them, which is the honest answer rather than a kernel guess.
+ */
+const REASON_KEY_CLASSES: Readonly<Record<string, PaymentFailureClass>> = Object.freeze({
+  off_session_sca_required: "sca_required",
+  provider_declined: "indeterminate",
+  provider_failed: "indeterminate",
+  provider_webhook_failed: "indeterminate",
+  provider_execution_indeterminate: "indeterminate",
+  // Authorization withdrawn. The instrument may live on; this reference cannot
+  // be charged.
+  payment_method_revoked: "hard_do_not_retry",
+  // Stored evidence says the payer must be present — an issuer's authentication
+  // demand, reached one step earlier.
+  payment_method_requires_action: "sca_required",
+  // Nothing usable stored, or what is stored failed its integrity read. Both
+  // need the payer to supply a method; neither is retriable as-is.
+  missing_provider_method_ref: "fix_and_retry_customer_action",
+  payment_method_invalid: "fix_and_retry_customer_action",
+});
+
+function ownValue<T>(table: Readonly<Record<string, T>>, key: string | undefined): T | undefined {
+  return key !== undefined && Object.prototype.hasOwnProperty.call(table, key) ? table[key] : undefined;
+}
+
+function classified(
+  failureClass: PaymentFailureClass,
+  decidedBy: PaymentFailureClassificationSource,
+): PaymentFailureClassification {
+  return Object.freeze({ failureClass, decidedBy });
+}
+
+function assertedHints(
+  evidence: PaymentFailureEvidence,
+  options: PaymentFailureClassificationOptions,
+): ReadonlySet<PaymentFailureHint> {
+  const hints = new Set<PaymentFailureHint>(evidence.neutralReasonHints ?? []);
+  for (const hint of ownValue(options.declineCodeHints ?? {}, evidence.declineCode) ?? []) {
+    hints.add(hint);
+  }
+  return hints;
+}
+
+/**
+ * Precedence, strongest first:
+ *
+ * 1. `adviceCode` — the issuer's or network's own retry verdict. It outranks
+ *    every local reading because it is the only evidence produced by the party
+ *    that will refuse the next attempt. An unrecognized value decides nothing
+ *    and falls through rather than being coerced.
+ * 2. neutral hints — what the adapter is willing to assert, whether stated
+ *    directly or reached through its own decline-code table. Several hints at
+ *    once resolve in {@link PAYMENT_FAILURE_HINTS} order, strictest first, so a
+ *    refusal that is both dead and merely slow is never scheduled for a
+ *    background retry.
+ * 3. `failureReasonKey` — the reason already persisted with the attempt. Weakest
+ *    because it is our own summary of a refusal, written before anyone tried to
+ *    classify it.
+ * 4. `indeterminate` — nothing decided.
+ */
+/** @beta */
+export function classifyPaymentFailure(
+  evidence: PaymentFailureEvidence,
+  options: PaymentFailureClassificationOptions = {},
+): PaymentFailureClassification {
+  const advised = ownValue(ADVICE_CLASSES, evidence.adviceCode);
+  if (advised !== undefined) return classified(advised, "advice_code");
+
+  const hints = assertedHints(evidence, options);
+  for (const hint of PAYMENT_FAILURE_HINTS) {
+    if (hints.has(hint)) return classified(HINT_CLASSES[hint], "neutral_hint");
+  }
+
+  const byReason = ownValue(REASON_KEY_CLASSES, evidence.failureReasonKey);
+  if (byReason !== undefined) return classified(byReason, "failure_reason_key");
+
+  return classified("indeterminate", "default");
+}
+
+/** True when a value is one of the advice codes this kernel acts on. */
+/** @beta */
+export function isPaymentRetryAdviceCode(
+  value: string,
+): value is (typeof PAYMENT_RETRY_ADVICE_CODES)[number] {
+  return (PAYMENT_RETRY_ADVICE_CODES as readonly string[]).includes(value);
+}
+
+/**
+ * The hard ceiling any retry schedule must stay under: at most 15 attempts on one
+ * instrument in 30 days. It is the stricter of the published card-scheme limits,
+ * chosen deliberately so a schedule that satisfies this one satisfies all of them.
+ *
+ * The current ladder tops out at 4, far below this. The constant exists so a later
+ * wave that widens the ladder has to measure itself against the scheme rule rather
+ * than discover it through fines.
+ */
+/** @beta */
+export const SCHEME_RETRY_ATTEMPT_CEILING = 15;
+
+/** The rolling window the ceiling is counted over. */
+/** @beta */
+export const SCHEME_RETRY_WINDOW_DAYS = 30;
+
+/**
+ * Whether an attempt is provably inside the scheme ceiling.
+ *
+ * `attemptCount` is the ordinal of the attempt being considered — the 15th
+ * attempt is inside, the 16th is not. `windowDays` is the span those attempts
+ * were counted over; a span longer than {@link SCHEME_RETRY_WINDOW_DAYS} cannot
+ * prove compliance, because the attempts may still cluster inside one 30-day
+ * sub-window, so it answers false rather than pretending to know.
+ *
+ * Fail-closed for anything that is not a positive integer.
+ */
+/** @beta */
+export function withinSchemeRetryCeiling(attemptCount: number, windowDays: number): boolean {
+  if (!Number.isInteger(attemptCount) || !Number.isInteger(windowDays)) return false;
+  if (attemptCount < 1 || windowDays < 1) return false;
+  if (windowDays > SCHEME_RETRY_WINDOW_DAYS) return false;
+  return attemptCount <= SCHEME_RETRY_ATTEMPT_CEILING;
+}

package/src/payment/paymentFailureTaxonomyContracts.ts

@@ -0,0 +1,228 @@
+/**
+ * The vocabulary a refused payment is classified into, and the retry decision
+ * each class implies.
+ *
+ * The classes answer one question — *may this instrument be charged again, and
+ * by whom* — and nothing else. They are deliberately not a copy of any acquirer's
+ * code list: an adapter translates its own codes into the neutral evidence in
+ * {@link PaymentFailureEvidence}, and only that evidence reaches this kernel.
+ *
+ * `indeterminate` means the CLASS is unknown, never that the OUTCOME is unknown.
+ * A refusal whose money movement is itself ambiguous must be resolved by the
+ * idempotency and attempt-fingerprint layer before anything here is consulted;
+ * this kernel cannot make a repeat charge safe.
+ */
+
+/**
+ * Ordered strongest-refusal-first. The order is documentation only — the
+ * classifier resolves a class from evidence, never from this array's index.
+ */
+/** @beta */
+export const PAYMENT_FAILURE_CLASSES = [
+  /** The credential is dead or the refusal is final: lost, stolen, reported fraudulent, closed account, or an authorization the payer revoked. Another attempt cannot succeed and still costs scheme fees. */
+  "hard_do_not_retry",
+  /** The stored mandate, alias, or standing consent no longer works even though the instrument may. Re-registration or a replacement method is required; a scheduled retry against the same stored reference repeats the same refusal. */
+  "mandate_dead",
+  /** Strong authentication is required. A retry is only meaningful through an on-session or hosted confirmation the payer can answer; a blind background retry cannot clear it. */
+  "sca_required",
+  /** Submitted data is wrong: number, security code, expiry, or address. Never retry automatically — the same wrong data produces the same refusal and, repeated, looks like enumeration. */
+  "fix_and_retry_customer_action",
+  /** Retriable, but only after a longer wait: a velocity, frequency, or amount limit was exceeded and needs time to decay. */
+  "soft_retry_delayed",
+  /** Transient: insufficient funds, a processing error, an unreachable issuer, or an explicit try-again-later verdict. A scheduled retry is the correct response. */
+  "soft_retryable",
+  /** Unclassifiable from the evidence supplied. Treated as soft with the default schedule, which is the conservative choice only because the retry ladder is bounded elsewhere. */
+  "indeterminate",
+] as const;
+/** @beta */
+export type PaymentFailureClass = (typeof PAYMENT_FAILURE_CLASSES)[number];
+
+/**
+ * The retry verdict the network or issuer returned with the refusal. These three
+ * values are scheme-standard advice, not one acquirer's vocabulary, which is why
+ * a neutral kernel may name them.
+ */
+/** @beta */
+export const PAYMENT_RETRY_ADVICE_CODES = [
+  "do_not_try_again",
+  "try_again_later",
+  "confirm_card_data",
+] as const;
+/** @beta */
+export type PaymentRetryAdviceCode = (typeof PAYMENT_RETRY_ADVICE_CODES)[number];
+
+/**
+ * Neutral assertions an adapter makes about a refusal it already understands.
+ *
+ * The array order IS the resolution order used when several hints are asserted
+ * at once: the strictest reading wins, so a refusal that is both dead and merely
+ * slow is never scheduled for a background retry.
+ */
+/** @beta */
+export const PAYMENT_FAILURE_HINTS = [
+  /** The instrument itself is finished: reported lost or stolen, flagged as fraud, closed, or the payer withdrew authorization. */
+  "credentialDead",
+  /** The payer's bank cannot honour the stored reusable reference, whatever the instrument's own state. */
+  "mandateUnsupported",
+  /** The refusal is an authentication demand, not a decline of the money. */
+  "authenticationRequired",
+  /** A submitted value was rejected as wrong rather than refused as unaffordable. */
+  "dataInvalid",
+  /** A velocity, frequency, or amount limit was hit; the same charge may pass once the limit decays. */
+  "limitExceeded",
+  /** An ordinary temporary refusal with no further detail. */
+  "transient",
+] as const;
+/** @beta */
+export type PaymentFailureHint = (typeof PAYMENT_FAILURE_HINTS)[number];
+
+/**
+ * Everything the kernel is allowed to look at. Every field is optional: an
+ * adapter that knows nothing supplies nothing and gets `indeterminate`, which is
+ * an honest answer rather than a guess.
+ */
+/** @beta */
+export interface PaymentFailureEvidence {
+  /** The issuer or network retry verdict, when one was returned. Recognized values are {@link PaymentRetryAdviceCode}; anything else is ignored rather than guessed at. */
+  adviceCode?: string;
+  /** The acquirer's own refusal code, kept opaque here. It contributes a class only through a caller-supplied hint table — this kernel embeds no code lists. */
+  declineCode?: string;
+  /** Neutral assertions the adapter is willing to make about the refusal. */
+  neutralReasonHints?: readonly PaymentFailureHint[];
+  /** The internal reason string already persisted with the attempt, if the failure travelled through the control plane before being classified. */
+  failureReasonKey?: string;
+}
+
+/** What a retry is allowed to look like for a class. */
+/** @beta */
+export type PaymentRetryProfile = "standard" | "delayed" | "none" | "on_session_only";
+
+/**
+ * The consequence of a class, as data. This record does not schedule anything and
+ * does not know the current ladder; it states what a scheduler is permitted to do.
+ */
+/** @beta */
+export interface PaymentFailureDecision {
+  retryAllowed: boolean;
+  retryProfile: PaymentRetryProfile;
+  customerActionRequired: boolean;
+  methodReplacementRequired: boolean;
+}
+
+const DECISIONS: Readonly<Record<PaymentFailureClass, PaymentFailureDecision>> = Object.freeze({
+  hard_do_not_retry: Object.freeze({
+    retryAllowed: false,
+    retryProfile: "none",
+    customerActionRequired: true,
+    methodReplacementRequired: true,
+  }),
+  mandate_dead: Object.freeze({
+    retryAllowed: false,
+    retryProfile: "none",
+    customerActionRequired: true,
+    methodReplacementRequired: true,
+  }),
+  sca_required: Object.freeze({
+    retryAllowed: true,
+    retryProfile: "on_session_only",
+    customerActionRequired: true,
+    methodReplacementRequired: false,
+  }),
+  fix_and_retry_customer_action: Object.freeze({
+    retryAllowed: false,
+    retryProfile: "none",
+    customerActionRequired: true,
+    methodReplacementRequired: false,
+  }),
+  soft_retry_delayed: Object.freeze({
+    retryAllowed: true,
+    retryProfile: "delayed",
+    customerActionRequired: false,
+    methodReplacementRequired: false,
+  }),
+  soft_retryable: Object.freeze({
+    retryAllowed: true,
+    retryProfile: "standard",
+    customerActionRequired: false,
+    methodReplacementRequired: false,
+  }),
+  indeterminate: Object.freeze({
+    retryAllowed: true,
+    retryProfile: "standard",
+    customerActionRequired: false,
+    methodReplacementRequired: false,
+  }),
+});
+
+/**
+ * The frozen decision for a class. Frozen so a consumer cannot quietly widen
+ * `retryAllowed` for one call site and leave every other reader believing the
+ * table still holds.
+ */
+/** @beta */
+export function failureClassDecision(failureClass: PaymentFailureClass): PaymentFailureDecision {
+  return DECISIONS[failureClass];
+}
+
+/**
+ * What a payer can be TOLD about a refused or impossible charge.
+ *
+ * Coarser than {@link PAYMENT_FAILURE_CLASSES} on purpose: a payer acts on
+ * remedies and there are fewer remedies than classes. Every class whose real
+ * content is "we do not know why" collapses into `unknown`, which exists so a
+ * caller can say nothing rather than guess — a surface rendering `unknown` must
+ * render exactly what it rendered before consulting this vocabulary.
+ *
+ * `method_missing` is the one cause no class produces: it belongs to the
+ * pre-renewal rails, which read a stored method that does not exist rather than a
+ * refusal that happened. It lives here so both kinds of surface quote one
+ * vocabulary instead of two.
+ */
+/** @beta */
+export const PAYMENT_FAILURE_CUSTOMER_CAUSES = [
+  /** Authentication is owed; the instrument may be fine, nobody was present. */
+  "needs_confirmation",
+  /** Stored consent cannot back an unattended charge, whatever the instrument. */
+  "method_cannot_recur",
+  /** The instrument is finished; another attempt on it cannot succeed. */
+  "method_dead",
+  /** Stored details rejected as wrong, not refused as unaffordable. */
+  "method_data_invalid",
+  /** No usable stored method. Pre-renewal state only, never a refusal. */
+  "method_missing",
+  /** Nothing may be claimed. Surfaces must add no sentence at all. */
+  "unknown",
+] as const;
+/** @beta */
+export type PaymentFailureCustomerCause = (typeof PAYMENT_FAILURE_CUSTOMER_CAUSES)[number];
+
+const CUSTOMER_CAUSES: Readonly<Record<PaymentFailureClass, PaymentFailureCustomerCause>> =
+  Object.freeze({
+    hard_do_not_retry: "method_dead",
+    mandate_dead: "method_cannot_recur",
+    sca_required: "needs_confirmation",
+    fix_and_retry_customer_action: "method_data_invalid",
+    // The soft readings say only that a retry is allowed, which is not a cause
+    // anybody can act on; `indeterminate` says outright that nothing is known.
+    // Naming a cause here would invent an issuer verdict.
+    soft_retry_delayed: "unknown",
+    soft_retryable: "unknown",
+    indeterminate: "unknown",
+  });
+
+/**
+ * The cause a payer may be told, for a class that may not have been recorded.
+ *
+ * Takes `string | null` rather than {@link PaymentFailureClass} on purpose: the
+ * caller reads a nullable column written by an older deployment, and an
+ * unrecognized value must degrade to `unknown` exactly like a missing one.
+ */
+/** @beta */
+export function customerCauseForFailureClass(
+  failureClass: string | null | undefined,
+): PaymentFailureCustomerCause {
+  if (failureClass === null || failureClass === undefined) return "unknown";
+  return Object.prototype.hasOwnProperty.call(CUSTOMER_CAUSES, failureClass)
+    ? CUSTOMER_CAUSES[failureClass as PaymentFailureClass]
+    : "unknown";
+}

package/src/payment/paymentRecovery.ts

@@ -0,0 +1,95 @@
+import { isLiveAttemptStatus, type PaymentAttemptStatus } from "./paymentControlTypes.js";
+import type {
+  PaymentRecoveryAction, PaymentRecoveryCandidate, PaymentRecoveryEvidence,
+  PaymentRecoveryOperation,
+} from "./paymentRecoveryContracts.js";
+
+/** @beta */
+export interface PaymentRecoveryAttempt {
+  id: string;
+  status: PaymentAttemptStatus;
+  evidence: PaymentRecoveryEvidence | null;
+}
+/** @beta */
+export interface PaymentRecoveryGuidance extends PaymentRecoveryEvidence {
+  version: 1;
+  paymentAttemptId: string;
+  consecutiveRefusals: 0 | 1 | 2 | null;
+  emphasis: "normal" | "recommended";
+  actions: readonly PaymentRecoveryAction[];
+}
+
+/** Only an authoritative failed attempt can become refusal guidance. @beta */
+export function derivePaymentRecoveryGuidance(input: {
+  paymentState: "failed" | "paid" | "pending" | "expired";
+  activeAttemptId: string | null;
+  /** Newest first, ordered by durable creation identity; never browser clicks. */
+  attempts: readonly PaymentRecoveryAttempt[];
+  historyComplete: boolean;
+}): PaymentRecoveryGuidance | null {
+  if (input.paymentState !== "failed" || !input.activeAttemptId) return null;
+  if (input.attempts.some((attempt) => attempt.status === "succeeded")) return null;
+  const current = input.attempts.find((attempt) => attempt.id === input.activeAttemptId);
+  if (!current || current.status !== "failed" || !current.evidence?.refusalVerified) return null;
+  // A later local attempt makes this a stale observation even if a caller picked it.
+  if (input.attempts[0]?.id !== current.id) return null;
+  const evidence = safeEvidence(current.evidence);
+  const count = evidence.cause !== "generic_decline" ? 0
+    : refusalStreak(input.attempts, evidence.method?.recoveryMethodKey, input.historyComplete);
+  const actions: PaymentRecoveryAction[] = evidence.cause === "expired_card"
+    ? ["change_instrument", "change_method"]
+    : evidence.cause === "invalid_payment_data" ? ["correct_data", "change_method"]
+    : evidence.cause === "authentication_required" ? ["authenticate", "change_method"]
+    : ["change_instrument", "change_method"];
+  if (evidence.advice?.code === "do_not_try_again" && evidence.advice.scope === "method") {
+    actions.splice(0, actions.length, "change_method");
+  }
+  return { ...evidence, version: 1, paymentAttemptId: current.id,
+    consecutiveRefusals: count, emphasis: count === 2 ? "recommended" : "normal", actions };
+}
+
+function safeEvidence(evidence: PaymentRecoveryEvidence): PaymentRecoveryEvidence {
+  return evidence.disclosure === "restricted" || evidence.certainty !== "verified"
+    ? { ...evidence, cause: "generic_decline", certainty: "unknown" } : evidence;
+}
+
+function refusalStreak(
+  attempts: readonly PaymentRecoveryAttempt[], methodKey: string | undefined, complete: boolean,
+): 1 | 2 | null {
+  if (!methodKey) return null;
+  let count = 0;
+  const seen = new Set<string>();
+  for (const attempt of attempts) {
+    if (seen.has(attempt.id)) continue;
+    seen.add(attempt.id);
+    if (isLiveAttemptStatus(attempt.status) || ["blocked_preflight", "cancelled", "expired"].includes(attempt.status)) continue;
+    const evidence = attempt.evidence;
+    if (!evidence?.refusalVerified || !evidence.method) return null;
+    if (safeEvidence(evidence).cause !== "generic_decline" || evidence.method.recoveryMethodKey !== methodKey) {
+      return count > 0 ? 1 : null;
+    }
+    count += 1;
+    if (count >= 2) return 2;
+  }
+  return complete && count === 1 ? 1 : null;
+}
+
+/** Filter with currently implemented, eligible choices; this never enables a rail. @beta */
+export function availablePaymentRecoveryActions(
+  guidance: PaymentRecoveryGuidance,
+  candidates: readonly PaymentRecoveryCandidate[],
+  operation: PaymentRecoveryOperation,
+): PaymentRecoveryAction[] {
+  const available = new Set<PaymentRecoveryAction>();
+  for (const candidate of candidates) {
+    if (candidate.capability !== "supported" || !candidate.available || candidate.operation !== operation) continue;
+    for (const action of candidate.actions) {
+      if (!guidance.actions.includes(action)) continue;
+      const sameChoice = candidate.method.recoveryMethodKey === guidance.method?.recoveryMethodKey;
+      if (action === "change_method" && sameChoice) continue;
+      if (action === "change_instrument" && (!sameChoice || candidate.method.interaction !== "new_instrument")) continue;
+      available.add(action);
+    }
+  }
+  return available.size ? [...available] : ["contact_support"];
+}

package/src/payment/paymentRecoveryContracts.ts

@@ -0,0 +1,61 @@
+/** Checkout guidance describes evidence; it never authorizes another charge. */
+import type { PaymentRetryAdviceCode } from "./paymentFailureTaxonomyContracts.js";
+
+/** @beta */
+export const PAYMENT_RECOVERY_CAUSES = [
+  "generic_decline", "insufficient_funds", "expired_card", "invalid_payment_data",
+  "authentication_required", "operation_unsupported", "recurring_setup_failed",
+] as const;
+/** @beta */
+export type PaymentRecoveryCause = (typeof PAYMENT_RECOVERY_CAUSES)[number];
+/** @beta */
+export const PAYMENT_RECOVERY_ACTIONS = [
+  "change_method", "change_instrument", "correct_data", "authenticate",
+  "check_status", "review_order", "contact_support", "retry",
+] as const;
+/** @beta */
+export type PaymentRecoveryAction = (typeof PAYMENT_RECOVERY_ACTIONS)[number];
+/** @beta */
+export type PaymentRecoveryOperation =
+  "one_time_payment" | "recurring_setup" | "stored_method_payment";
+/** @beta */
+export interface PaymentRecoveryMethod {
+  /** A method identity, never an operator identity or an instrument fingerprint. */
+  kind: string;
+  /** Canonical visible choice; changing operator alone cannot change this key. */
+  recoveryMethodKey: string;
+  interaction: "new_instrument" | "stored_instrument";
+}
+/** @beta */
+export interface PaymentRecoveryAdvice {
+  code: PaymentRetryAdviceCode;
+  scope: "instrument" | "method" | "operation" | "unknown";
+}
+/** @beta */
+export interface PaymentRecoveryEvidence {
+  /** Established refusal, not merely an unconfirmed or locally failed request. */
+  refusalVerified: boolean;
+  cause: PaymentRecoveryCause;
+  certainty: "verified" | "unknown";
+  disclosure: "safe" | "restricted";
+  method: PaymentRecoveryMethod | null;
+  operation: PaymentRecoveryOperation | null;
+  advice: PaymentRecoveryAdvice | null;
+}
+/** @beta */
+export interface PaymentRecoveryCandidate {
+  method: PaymentRecoveryMethod;
+  operation: PaymentRecoveryOperation;
+  capability: "supported" | "unsupported" | "unknown";
+  /** Resolved deployment, merchant and client eligibility, not operator marketing. */
+  available: boolean;
+  actions: readonly PaymentRecoveryAction[];
+}
+/**
+ * Companion to execution capabilities. A caller injects provider normalizers;
+ * the kernel sees only their neutral outputs. An absent normalizer adds no facts.
+ * @beta
+ */
+export interface PaymentRecoveryNormalizer<TInput = unknown> {
+  normalize(input: TInput): PaymentRecoveryEvidence | null;
+}