@openlup/core 0.0.0 → 0.7.0

package/dist/payment/methodLifecycle.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Neutral payment-method lifecycle vocabulary.
+ *
+ * A stored consent does not only come into existence. It is rotated, revoked
+ * and suspended, and it expires — and every rail announces those transitions in
+ * its own words. This module is the vocabulary those announcements are
+ * translated INTO, so the engine that reacts (deactivating a dead method,
+ * warning a payer before a renewal that can no longer be charged) never has to
+ * learn a rail's event names.
+ *
+ * Types and pure functions only: nothing here reads a clock, a network or a
+ * database, and no rail is named.
+ */
+/**
+ * Every transition a rail may report about a method it holds on file.
+ *
+ * `method_suspended` is declared but published by no rail in this deployment.
+ * It is here because the consuming branch is exhaustive over this list: a rail
+ * that starts emitting a suspension must be handled, never silently ignored.
+ */
+export declare const PAYMENT_METHOD_LIFECYCLE_EVENT_KINDS: readonly ["method_registered", "method_updated", "method_revoked", "method_expired", "method_suspended"];
+export type PaymentMethodLifecycleEventKind = (typeof PAYMENT_METHOD_LIFECYCLE_EVENT_KINDS)[number];
+/**
+ * What the rail reports about the method AFTER the transition.
+ *
+ * Deliberately three fields and no more: the label a payer recognises the
+ * method by, the trailing digits shown beside it, and the instant it stops
+ * being chargeable. ⛔ The full instrument number is never part of this
+ * contract, and an adapter that put one here would be widening a surface this
+ * type exists to keep narrow.
+ *
+ * Every field is independently nullable because rails report them
+ * independently: an alias rail may carry an expiry and no digits at all.
+ */
+export interface PaymentMethodReplacementFacts {
+    /** Scheme or rail label the payer recognises, e.g. a card network name. */
+    schemeLabel: string | null;
+    /** Trailing digits of the instrument, never more than the payer is shown. */
+    lastDigits: string | null;
+    /** ISO-8601 instant after which the method can no longer be charged. */
+    expiresAt: string | null;
+}
+/**
+ * One rail transition, expressed neutrally.
+ *
+ * `providerKind` and `providerMethodRef` are opaque identity, not a branch
+ * condition: together they address exactly one stored method. A consumer that
+ * compares `providerKind` against a known name re-creates the coupling this
+ * contract removes.
+ */
+export interface PaymentMethodLifecycleEvent {
+    kind: PaymentMethodLifecycleEventKind;
+    /** Registry key of the rail that reported this, used only for addressing. */
+    providerKind: string;
+    /** The rail's own reference for the stored method this transition is about. */
+    providerMethodRef: string;
+    /** The rail's identifier for this delivery, used for replay-safe writes. */
+    providerEventId: string;
+    /** ISO-8601 instant the rail reported the transition at. */
+    occurredAt: string;
+    /** Fresh facts the rail published with the transition, when it published any. */
+    replacement?: PaymentMethodReplacementFacts | null;
+}
+/**
+ * Whether this transition means the stored method can no longer back a charge.
+ *
+ * The single place that answers it. ⛔ A rotation (`method_updated`) is NOT a
+ * death: the same consent continues under fresh details, and treating it as one
+ * would strip a healthy subscription of the method it renews on.
+ */
+export declare function endsStoredMethodUsability(kind: PaymentMethodLifecycleEventKind): boolean;
+export declare function isPaymentMethodLifecycleEventKind(value: unknown): value is PaymentMethodLifecycleEventKind;
+/**
+ * The instant a month-and-year validity actually runs out.
+ *
+ * Convention, pinned here once so no adapter has to re-decide it: an
+ * instrument valid "through 06/2027" is chargeable for the whole of that month
+ * and stops at the LAST instant of it, in UTC — `2027-06-30T23:59:59.999Z`. The
+ * common alternative, the first instant of the month, would retire a method up
+ * to 31 days before the payer's own statement says it dies.
+ *
+ * UTC rather than a local zone on purpose: the value is compared against
+ * `now()` by storage and by health reads, both of which are UTC, and the
+ * one-day ambiguity a local zone would introduce is not worth a timezone
+ * dependency in a kernel.
+ *
+ * Returns null for anything that is not a plainly valid month and four-digit
+ * year, so a malformed rail payload yields "no expiry known" rather than a
+ * fabricated date.
+ */
+export declare function expiryInstantFromMonthYear(month: number | null | undefined, year: number | null | undefined): string | null;

package/dist/payment/methodLifecycle.js

@@ -0,0 +1,76 @@
+/**
+ * Neutral payment-method lifecycle vocabulary.
+ *
+ * A stored consent does not only come into existence. It is rotated, revoked
+ * and suspended, and it expires — and every rail announces those transitions in
+ * its own words. This module is the vocabulary those announcements are
+ * translated INTO, so the engine that reacts (deactivating a dead method,
+ * warning a payer before a renewal that can no longer be charged) never has to
+ * learn a rail's event names.
+ *
+ * Types and pure functions only: nothing here reads a clock, a network or a
+ * database, and no rail is named.
+ */
+/**
+ * Every transition a rail may report about a method it holds on file.
+ *
+ * `method_suspended` is declared but published by no rail in this deployment.
+ * It is here because the consuming branch is exhaustive over this list: a rail
+ * that starts emitting a suspension must be handled, never silently ignored.
+ */
+export const PAYMENT_METHOD_LIFECYCLE_EVENT_KINDS = [
+    "method_registered",
+    "method_updated",
+    "method_revoked",
+    "method_expired",
+    "method_suspended",
+];
+/**
+ * Whether this transition means the stored method can no longer back a charge.
+ *
+ * The single place that answers it. ⛔ A rotation (`method_updated`) is NOT a
+ * death: the same consent continues under fresh details, and treating it as one
+ * would strip a healthy subscription of the method it renews on.
+ */
+export function endsStoredMethodUsability(kind) {
+    return kind === "method_revoked" || kind === "method_expired" || kind === "method_suspended";
+}
+export function isPaymentMethodLifecycleEventKind(value) {
+    return typeof value === "string"
+        && PAYMENT_METHOD_LIFECYCLE_EVENT_KINDS.includes(value);
+}
+/**
+ * The instant a month-and-year validity actually runs out.
+ *
+ * Convention, pinned here once so no adapter has to re-decide it: an
+ * instrument valid "through 06/2027" is chargeable for the whole of that month
+ * and stops at the LAST instant of it, in UTC — `2027-06-30T23:59:59.999Z`. The
+ * common alternative, the first instant of the month, would retire a method up
+ * to 31 days before the payer's own statement says it dies.
+ *
+ * UTC rather than a local zone on purpose: the value is compared against
+ * `now()` by storage and by health reads, both of which are UTC, and the
+ * one-day ambiguity a local zone would introduce is not worth a timezone
+ * dependency in a kernel.
+ *
+ * Returns null for anything that is not a plainly valid month and four-digit
+ * year, so a malformed rail payload yields "no expiry known" rather than a
+ * fabricated date.
+ */
+export function expiryInstantFromMonthYear(month, year) {
+    if (!Number.isInteger(month) || !Number.isInteger(year))
+        return null;
+    const monthValue = month;
+    const yearValue = year;
+    if (monthValue < 1 || monthValue > 12)
+        return null;
+    // Below 1000 the platform's own two-digit-year remapping would silently turn
+    // 27 into 1927; a rail that abbreviates the year is refused, not guessed at.
+    if (yearValue < 1000 || yearValue > 9999)
+        return null;
+    // Month is 1-based here and 0-based in the platform date constructor, so
+    // passing it unchanged addresses the FIRST instant of the following month;
+    // one millisecond earlier is the last instant of the expiry month itself.
+    const firstInstantAfter = Date.UTC(yearValue, monthValue, 1);
+    return new Date(firstInstantAfter - 1).toISOString();
+}

package/dist/payment/paymentControlTypes.d.ts

@@ -0,0 +1,135 @@
+/** @beta */
+export declare const PAYMENT_TARGET_KINDS: readonly ["one_time_order", "subscription_cycle"];
+/** @beta */
+export type PaymentTargetKind = (typeof PAYMENT_TARGET_KINDS)[number];
+/** @beta */
+export declare const PAYMENT_INTENT_STATUSES: readonly ["created", "requires_action", "processing", "succeeded", "failed", "expired", "cancelled", "refunded", "partially_refunded", "disputed"];
+/** @beta */
+export type PaymentIntentStatus = (typeof PAYMENT_INTENT_STATUSES)[number];
+/** @beta */
+export declare const PAYMENT_ATTEMPT_STATUSES: readonly ["created", "blocked_preflight", "sent_to_provider", "requires_action", "processing", "succeeded", "failed", "cancelled", "expired"];
+/** @beta */
+export type PaymentAttemptStatus = (typeof PAYMENT_ATTEMPT_STATUSES)[number];
+/**
+ * The attempt statuses that prove no provider call can still be outstanding, and
+ * so allow a fresh attempt against the same intent.
+ *
+ * This is the admission gate's own set, not a convenience list: the durable
+ * gate is written in SQL as `status NOT IN (...)` over exactly these four values,
+ * at three call sites, and `src/domains/payment/payment.test.ts` pins all three
+ * against this constant. The gate is deliberately fail-closed — every status
+ * outside this set is treated as "a call may exist" even when it is terminal —
+ * because admitting a second call against a live attempt can take the payer's
+ * money twice, while refusing one only delays a retry.
+ *
+ * @beta
+ */
+export declare const RETRYABLE_ATTEMPT_STATUSES: readonly ["blocked_preflight", "failed", "cancelled", "expired"];
+/**
+ * The attempt statuses that describe an outcome still in the air: the request
+ * exists, and neither success nor refusal is known yet.
+ *
+ * NOT the complement of {@link RETRYABLE_ATTEMPT_STATUSES}. The complement also
+ * contains `succeeded`, which is settled rather than live, so the two predicates
+ * relate as `!isRetryableAttemptStatus(s) === isLiveAttemptStatus(s) || s ===
+ * "succeeded"` — an identity the canon test pins, because reasoning about it
+ * from the two lists alone has already gone wrong once in this repository.
+ *
+ * @beta
+ */
+export declare const LIVE_ATTEMPT_STATUSES: readonly ["created", "sent_to_provider", "requires_action", "processing"];
+/**
+ * Whether a fresh attempt may be admitted against the intent this attempt
+ * belongs to. See {@link RETRYABLE_ATTEMPT_STATUSES}.
+ *
+ * @beta
+ */
+export declare function isRetryableAttemptStatus(status: string): boolean;
+/**
+ * Whether this attempt's outcome is still unresolved — the row a status poller,
+ * a reconciliation sweep or a stuck-attempt watchdog is looking for. See
+ * {@link LIVE_ATTEMPT_STATUSES}.
+ *
+ * @beta
+ */
+export declare function isLiveAttemptStatus(status: string): boolean;
+/**
+ * Whether the request demonstrably reached the provider and nothing came back.
+ *
+ * The single status that says so is `sent_to_provider`, and it exists because the
+ * alternatives both lie. `created` claims the provider was never contacted, so a
+ * caller is free to contact it again. `processing` claims money is moving, which
+ * is what a payer is then told — and that exact claim was made about intents no
+ * issuer had ever been asked about (recorded in the deployment payment-status canon).
+ *
+ * Reaching for this predicate instead of comparing the string is the point: the
+ * mapping that produced the wrong verdict lived in an adapter that could not see
+ * the reasoning, which sat unexported in a file beside it.
+ *
+ * @beta
+ */
+export declare function providerAckedButNeverConfirmed(status: string): boolean;
+/** @beta */
+export declare const PAYMENT_CONTROL_EVENT_TYPES: readonly ["payment.requires_action", "payment.succeeded", "payment.failed", "payment.refunded", "payment.disputed"];
+/** @beta */
+export type PaymentControlEventType = (typeof PAYMENT_CONTROL_EVENT_TYPES)[number];
+/** @beta */
+export interface PaymentIntentAggregate {
+    id: string;
+    targetKind: PaymentTargetKind;
+    targetId: string;
+    status: PaymentIntentStatus;
+    amountMinor: number;
+    currency: string;
+    activeAttemptId: string | null;
+    updatedAt: string;
+    providerPaymentId?: string | null;
+    failureReason?: string | null;
+}
+/** @beta */
+export interface PaymentAttemptAggregate {
+    id: string;
+    intentId: string;
+    status: PaymentAttemptStatus;
+    provider: string;
+    providerAttemptId: string | null;
+    amountMinor: number;
+    currency: string;
+    idempotencyKey: string;
+    updatedAt: string;
+    nextActionKind?: string | null;
+    failureReason?: string | null;
+}
+/** @beta */
+export interface CanonicalPaymentControlEvent {
+    provider: string;
+    providerEventId: string;
+    eventType: PaymentControlEventType;
+    providerPaymentId: string;
+    amountMinor?: number;
+    currency?: string;
+    occurredAt: string;
+    failureReason?: string;
+    nextActionKind?: string;
+    rawPayload: Record<string, unknown>;
+}
+/** @beta */
+export type PaymentControlDecisionKind = "state_changed" | "noop" | "late_success_recovered";
+/** @beta */
+export interface PaymentControlDecision {
+    kind: PaymentControlDecisionKind;
+    reason: string;
+    intent: PaymentIntentAggregate;
+    attempt: PaymentAttemptAggregate;
+}
+/** @beta */
+export type PaymentControlFailureReason = "amount_mismatch" | "currency_mismatch" | "invalid_transition" | "refund_requires_success" | "terminal_intent" | "wrong_attempt";
+/** @beta */
+export type PaymentControlResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    reason: PaymentControlFailureReason;
+    message: string;
+};

package/dist/payment/paymentControlTypes.js

@@ -0,0 +1,110 @@
+/** @beta */
+export const PAYMENT_TARGET_KINDS = ["one_time_order", "subscription_cycle"];
+/** @beta */
+export const PAYMENT_INTENT_STATUSES = [
+    "created",
+    "requires_action",
+    "processing",
+    "succeeded",
+    "failed",
+    "expired",
+    "cancelled",
+    "refunded",
+    "partially_refunded",
+    "disputed",
+];
+/** @beta */
+export const PAYMENT_ATTEMPT_STATUSES = [
+    "created",
+    "blocked_preflight",
+    "sent_to_provider",
+    "requires_action",
+    "processing",
+    "succeeded",
+    "failed",
+    "cancelled",
+    "expired",
+];
+/**
+ * The attempt statuses that prove no provider call can still be outstanding, and
+ * so allow a fresh attempt against the same intent.
+ *
+ * This is the admission gate's own set, not a convenience list: the durable
+ * gate is written in SQL as `status NOT IN (...)` over exactly these four values,
+ * at three call sites, and `src/domains/payment/payment.test.ts` pins all three
+ * against this constant. The gate is deliberately fail-closed — every status
+ * outside this set is treated as "a call may exist" even when it is terminal —
+ * because admitting a second call against a live attempt can take the payer's
+ * money twice, while refusing one only delays a retry.
+ *
+ * @beta
+ */
+export const RETRYABLE_ATTEMPT_STATUSES = [
+    "blocked_preflight",
+    "failed",
+    "cancelled",
+    "expired",
+];
+/**
+ * The attempt statuses that describe an outcome still in the air: the request
+ * exists, and neither success nor refusal is known yet.
+ *
+ * NOT the complement of {@link RETRYABLE_ATTEMPT_STATUSES}. The complement also
+ * contains `succeeded`, which is settled rather than live, so the two predicates
+ * relate as `!isRetryableAttemptStatus(s) === isLiveAttemptStatus(s) || s ===
+ * "succeeded"` — an identity the canon test pins, because reasoning about it
+ * from the two lists alone has already gone wrong once in this repository.
+ *
+ * @beta
+ */
+export const LIVE_ATTEMPT_STATUSES = [
+    "created",
+    "sent_to_provider",
+    "requires_action",
+    "processing",
+];
+/**
+ * Whether a fresh attempt may be admitted against the intent this attempt
+ * belongs to. See {@link RETRYABLE_ATTEMPT_STATUSES}.
+ *
+ * @beta
+ */
+export function isRetryableAttemptStatus(status) {
+    return RETRYABLE_ATTEMPT_STATUSES.includes(status);
+}
+/**
+ * Whether this attempt's outcome is still unresolved — the row a status poller,
+ * a reconciliation sweep or a stuck-attempt watchdog is looking for. See
+ * {@link LIVE_ATTEMPT_STATUSES}.
+ *
+ * @beta
+ */
+export function isLiveAttemptStatus(status) {
+    return LIVE_ATTEMPT_STATUSES.includes(status);
+}
+/**
+ * Whether the request demonstrably reached the provider and nothing came back.
+ *
+ * The single status that says so is `sent_to_provider`, and it exists because the
+ * alternatives both lie. `created` claims the provider was never contacted, so a
+ * caller is free to contact it again. `processing` claims money is moving, which
+ * is what a payer is then told — and that exact claim was made about intents no
+ * issuer had ever been asked about (recorded in the deployment payment-status canon).
+ *
+ * Reaching for this predicate instead of comparing the string is the point: the
+ * mapping that produced the wrong verdict lived in an adapter that could not see
+ * the reasoning, which sat unexported in a file beside it.
+ *
+ * @beta
+ */
+export function providerAckedButNeverConfirmed(status) {
+    return status === "sent_to_provider";
+}
+/** @beta */
+export const PAYMENT_CONTROL_EVENT_TYPES = [
+    "payment.requires_action",
+    "payment.succeeded",
+    "payment.failed",
+    "payment.refunded",
+    "payment.disputed",
+];

package/dist/payment/paymentFailureTaxonomy.d.ts

@@ -0,0 +1,80 @@
+import { 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 declare const PAYMENT_FAILURE_CLASSIFICATION_SOURCES: readonly ["advice_code", "neutral_hint", "failure_reason_key", "default"];
+/** @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[]>>;
+}
+/**
+ * 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 declare function classifyPaymentFailure(evidence: PaymentFailureEvidence, options?: PaymentFailureClassificationOptions): PaymentFailureClassification;
+/** True when a value is one of the advice codes this kernel acts on. */
+/** @beta */
+export declare function isPaymentRetryAdviceCode(value: string): value is (typeof PAYMENT_RETRY_ADVICE_CODES)[number];
+/**
+ * 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 declare const SCHEME_RETRY_ATTEMPT_CEILING = 15;
+/** The rolling window the ceiling is counted over. */
+/** @beta */
+export declare 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 declare function withinSchemeRetryCeiling(attemptCount: number, windowDays: number): boolean;

package/dist/payment/paymentFailureTaxonomy.js

@@ -0,0 +1,155 @@
+import { PAYMENT_FAILURE_HINTS, PAYMENT_RETRY_ADVICE_CODES, } 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",
+];
+const ADVICE_CLASSES = 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 = 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 = 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(table, key) {
+    return key !== undefined && Object.prototype.hasOwnProperty.call(table, key) ? table[key] : undefined;
+}
+function classified(failureClass, decidedBy) {
+    return Object.freeze({ failureClass, decidedBy });
+}
+function assertedHints(evidence, options) {
+    const hints = new Set(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, options = {}) {
+    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) {
+    return PAYMENT_RETRY_ADVICE_CODES.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, windowDays) {
+    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;
+}