@openlup/platform 0.20.0 → 0.21.0

package/dist/payments/contracts/evidence.d.ts

@@ -0,0 +1,157 @@
+import type { PaymentMethodLifecycleEvent } from "@openlup/core/payment";
+import type { PaymentMethodHandoff, PaymentRefusalEnvelope } from "./adapter.js";
+/** Configured integer-minor money; currency bytes pass through unchanged. */
+export type PaymentMoney = {
+    amountMinor: number;
+    currency: string;
+};
+/** Exact attempt identity for readback, close and absence lookups. */
+export type PaymentAttemptIdentity = {
+    provider: string;
+    /** Null permits an exact intent lookup when dispatch acknowledgement was lost. */
+    providerPaymentRef: string | null;
+    intentRef: string;
+    attemptRef: string;
+};
+type VerifiedIdentity = {
+    provider: string;
+    /** Adapter-derived; includes outcome/status class, never transaction identity alone. */
+    providerEventId: string;
+    /** Provider-asserted time or null; never substitute receipt time. */
+    providerOccurredAt: string | null;
+    /** Stable normalized evidence fingerprint; excludes receipt time and secrets. */
+    fingerprint: string;
+    /** Adapter-filtered provider facts for host audit/repair readers. Never raw bodies,
+     * transient secrets, handoffs or customer authorization; excluded from identity/fingerprint.
+     * Typed evidence takes precedence over overlapping audit facts. */
+    providerAuditPayload?: Readonly<Record<string, unknown>>;
+};
+/** Original payment money and stable operation identity accompany every reversal. */
+export type PaymentRefundObservation = {
+    operationId: string;
+    originalPaymentMoney: PaymentMoney;
+} & ({
+    kind: "cumulative-snapshot";
+    refundedMoney: PaymentMoney;
+} | {
+    kind: "event-delta";
+    refundedMoney: PaymentMoney;
+} | {
+    kind: "full-reversal";
+    reason: "refund" | "chargeback";
+});
+/** Type-only policy: require-evidence is default; legacy behavior needs explicit opt-in. */
+export type RefundEvidencePolicy = "require-evidence" | "legacy-assume-full";
+/** Verified money facts; authorization alone is never settled money. */
+export type VerifiedPaymentEvidence = VerifiedIdentity & {
+    kind: "money";
+    providerPaymentRef: string;
+    intentRef: string | null;
+    attemptRef: string | null;
+    outcome: "succeeded" | "failed" | "pending" | "refunded" | "disputed";
+    money: PaymentMoney | null;
+    refusal?: PaymentRefusalEnvelope;
+    refund?: PaymentRefundObservation;
+};
+/**
+ * Method lifecycle facts, separate from the money-outcome union; setup is never money success.
+ * Outcomes follow the core method lifecycle kinds plus setup failure and required customer action.
+ */
+export type VerifiedMethodEvidence = VerifiedIdentity & {
+    kind: "method";
+    outcome: "registered" | "updated" | "revoked" | "expired" | "suspended" | "failed" | "requires-action";
+    methodLifecycle?: PaymentMethodLifecycleEvent;
+    /** Registration facts only. The host resolves client/subscription ownership. */
+    reusableMethod?: {
+        providerCustomerRef?: string | null;
+        providerMethodRef: string;
+        providerMandateRef?: string | null;
+        methodKind: string;
+        status: "pending_verification" | "active" | "inactive" | "expired" | "revoked";
+    };
+    methodRef: string;
+    setupRef: string | null;
+    intentRef: string | null;
+};
+/** Verification uses injected I/O and original bytes; never reserialize rawBody. */
+export interface PaymentVerifyNormalizePort {
+    verifyAndNormalize(input: {
+        rawBody: Uint8Array;
+        headers: Readonly<Record<string, string | readonly string[] | undefined>>;
+        /** Freshness only; never part of identity or fingerprint. */
+        receivedAt: string;
+    }): Promise<VerifiedPaymentEvidence | VerifiedMethodEvidence | {
+        kind: "refusal";
+        reason: "signature" | "stale" | "malformed" | "unsupported-event";
+    }>;
+}
+/** Existing purpose bytes are preserved for reference reconciliation callers. */
+export type ProviderReadPurpose = "active_checkout" | "recovery";
+/** Absence requires a complete bounded lookup of exact identity and configured money. */
+export type PaymentAbsenceEnvelope = {
+    identity: PaymentAttemptIdentity;
+    expectedMoney: PaymentMoney;
+} & ({
+    kind: "absent";
+    evidence: {
+        exact: true;
+        complete: true;
+        lookupReference: string;
+    };
+} | {
+    kind: "unknown";
+    reason: "timeout" | "truncated" | "indeterminate";
+} | {
+    kind: "unsupported";
+});
+/** Unknown is neither absence nor unsupported. Timeout/truncation stays unknown. */
+export type PaymentReadbackEnvelope = {
+    identity: PaymentAttemptIdentity;
+    expectedMoney: PaymentMoney;
+    purpose: ProviderReadPurpose;
+} & ({
+    kind: "succeeded" | "failed" | "pending";
+    observedMoney: PaymentMoney;
+    providerOccurredAt: string | null;
+    refusal?: PaymentRefusalEnvelope;
+    handoff?: PaymentMethodHandoff;
+} | {
+    kind: "unknown";
+    reason: "timeout" | "truncated" | "indeterminate";
+} | {
+    kind: "absent";
+    evidence: Extract<PaymentAbsenceEnvelope, {
+        kind: "absent";
+    }>["evidence"];
+} | {
+    kind: "unsupported";
+});
+/** Exact readback of one attempt; a browser return or provider silence is never money truth. */
+export interface PaymentReadbackPort {
+    readPayment(input: {
+        identity: PaymentAttemptIdentity;
+        expectedMoney: PaymentMoney;
+        purpose: ProviderReadPurpose;
+    }): Promise<PaymentReadbackEnvelope>;
+    /** Present only when capabilities declare close supported; returns the post-close readback. */
+    close?(input: {
+        identity: PaymentAttemptIdentity;
+        expectedMoney: PaymentMoney;
+        purpose: ProviderReadPurpose;
+    }): Promise<PaymentReadbackEnvelope>;
+}
+/** Present only when capabilities declare exact absence supported. */
+export interface PaymentAbsencePort {
+    proveAbsence(input: {
+        identity: PaymentAttemptIdentity;
+        expectedMoney: PaymentMoney;
+    }): Promise<PaymentAbsenceEnvelope>;
+}
+/** Transport-neutral acknowledgement; hosts write their own HTTP response. */
+export interface PaymentIngressPort {
+    receive(input: Parameters<PaymentVerifyNormalizePort["verifyAndNormalize"]>[0]): Promise<{
+        status: 200 | 400 | 409 | 503;
+        data: Record<string, unknown>;
+    }>;
+}
+export {};

package/dist/payments/contracts/evidence.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,10 @@
+export type { PreparedAttemptPrepareInput, PreparedAttemptPersistenceResult, PreparedAttemptFinalizeInput, PreparedAttemptPersistencePort, PreparedAttemptExecutionPort, PreparedAttemptExecutionInput, PreparedAttemptFailurePolicy, PreparedAttemptExecutionResult, } from "./preparedAttempt.js";
+export type { TransientSecret, PaymentMethodHandoff, PaymentRefusalEnvelope, PaymentExecutionEnvelope, PaymentAttemptPort, PaymentAdapterCapabilities, PaymentAdapter, } from "./adapter.js";
+export type { PaymentRefundObservation, RefundEvidencePolicy, VerifiedPaymentEvidence, VerifiedMethodEvidence, PaymentVerifyNormalizePort, ProviderReadPurpose, PaymentAbsenceEnvelope, PaymentReadbackEnvelope, PaymentMoney, PaymentAttemptIdentity, PaymentReadbackPort, PaymentAbsencePort, } from "./evidence.js";
+export type { PaymentAdapterConformanceSubject, PaymentAdapterConformanceEvidence } from "./conformance.js";
+export type { PaymentTruthOutcome, PaymentTruthRefusalClass, PaymentSourceEvidence, PaymentTruthEvent, PaymentReconciliationResult, PaymentTruthReadback, PaymentTruthPort, CanonicalPaymentSource, } from "./truth.js";
+export type { PaymentIngressPort } from "./evidence.js";
+export type { ProviderReconciliationStatusKind, ProviderReconciliationStatus, PaymentProviderReconciliationProvider, ClaimedPaymentAttempt, PaymentProviderReconciliationPort, InteractivePreparedAttemptManualReconciliationPort, ManualInteractivePreparedAttemptAbsenceEvidence, InteractivePreparedAttemptReopenResult, PaymentProviderReconciliationWorkerResult, PaymentProviderReconciliationWorkerInput, SilenceWindowLookup, PaymentVerifyReadPort, VerifiableAttemptSnapshot, PaymentVerifyNowResult, } from "./reconciliation.js";
+export type { PostgresPaymentTruthOptions } from "./truth.js";
+export type { ActivePaymentActionAuthority, CheckoutActivePaymentActionResolver, CheckoutRecoveryPaymentResolver, CheckoutRecoveryPaymentResolution, PaymentRecoveryAction, PaymentRepairMethodPort } from "./repair.js";
+export type { PaymentServicesOptions, PaymentServices } from "./repair.js";

package/dist/payments/contracts/index.js

@@ -0,0 +1 @@
+export {};

package/dist/payments/contracts/preparedAttempt.d.ts

@@ -0,0 +1,69 @@
+import type { PaymentAttemptStatus, PaymentExecutionBaseInput, PaymentExecutionBaseResult } from "@openlup/core/payment";
+/** Durable preparation facts; provider admission belongs to the caller. */
+export interface PreparedAttemptPrepareInput<P extends string = string> {
+    idempotencyKey: string;
+    paymentIntentId: string;
+    provider: P;
+    providerIdempotencyKey: string;
+    providerRequestFingerprint: string;
+    providerFlow: string;
+    paymentMethodRef?: string | null;
+    requestPayload: Record<string, unknown>;
+}
+export interface PreparedAttemptPersistenceResult<N extends string = string> {
+    paymentAttemptId: string;
+    status: PaymentAttemptStatus;
+    replayed: boolean;
+    providerAttemptId: string | null;
+    providerSessionId: string | null;
+    nextActionKind: N | null;
+}
+export interface PreparedAttemptFinalizeInput<N extends string = string> extends Pick<PaymentExecutionBaseResult, "providerAttemptId" | "providerSessionId" | "attemptStatus" | "requestPayload" | "responsePayload"> {
+    idempotencyKey: string;
+    paymentIntentId: string;
+    paymentAttemptId: string;
+    providerIdempotencyKey: string;
+    providerRequestFingerprint: string;
+    nextActionKind: N | null;
+}
+/** Only persistence capabilities needed by interactive attempt ordering. */
+export interface PreparedAttemptPersistencePort<P extends string = string, N extends string = string> {
+    prepareProviderAttempt(input: PreparedAttemptPrepareInput<P>): Promise<PreparedAttemptPersistenceResult<N>>;
+    finalizeProviderAttempt(input: PreparedAttemptFinalizeInput<N>): Promise<PreparedAttemptPersistenceResult<N>>;
+}
+export interface PreparedAttemptExecutionPort<I extends PaymentExecutionBaseInput, R extends PaymentExecutionBaseResult> {
+    validateInput?(input: I): void;
+    execute(input: I): Promise<R>;
+}
+/** Exact execution extensions and original input/port references cross this seam. */
+export interface PreparedAttemptExecutionInput<I extends PaymentExecutionBaseInput, R extends PaymentExecutionBaseResult, P extends string, N extends string> {
+    paymentPort: PreparedAttemptPersistencePort<P, N>;
+    executionPort: PreparedAttemptExecutionPort<I, R>;
+    provider: P;
+    paymentIntentId: string;
+    executionInput: I;
+    prepareIdempotencyKey: string;
+    finalizeIdempotencyKey: string;
+    providerIdempotencyKey: string;
+    providerRequestFingerprint: string;
+    providerFlow: string;
+    paymentMethodRef?: string | null;
+    prepareRequestPayload: Record<string, unknown>;
+    validateExecution?: (execution: R) => void;
+}
+/** Synchronous, call-scoped native trust, diagnostics and error construction. */
+export interface PreparedAttemptFailurePolicy<E extends Error, N extends string> {
+    replayError(prepared: PreparedAttemptPersistenceResult<N>): Error;
+    isTrustedNoCharge(error: unknown): error is E;
+    logRetry(error: E, prepared: PreparedAttemptPersistenceResult<N>): void;
+    exhaustedError(error: E, first: E, prepared: PreparedAttemptPersistenceResult<N>): E;
+    executionError(error: unknown, prepared: PreparedAttemptPersistenceResult<N>): Error;
+    finalizationError(error: unknown, prepared: PreparedAttemptPersistenceResult<N>): Error;
+}
+export interface PreparedAttemptExecutionResult<R extends PaymentExecutionBaseResult> {
+    execution: R;
+    attempt: {
+        paymentAttemptId: string;
+        status: PaymentAttemptStatus;
+    };
+}

package/dist/payments/contracts/preparedAttempt.js

@@ -0,0 +1 @@
+export {};

package/dist/payments/contracts/reconciliation.d.ts

@@ -0,0 +1,303 @@
+import type { ProviderReadPurpose } from "./evidence.js";
+export type ReconciliationProviderKind = string;
+export type ProviderReconciliationStatusKind = "succeeded" | "failed" | "pending" | "unknown";
+export interface ProviderReconciliationStatus {
+    status: ProviderReconciliationStatusKind;
+    providerStatus: string;
+    occurredAt: string | null;
+    failureReason: string | null;
+    amountMinor: number | null;
+    currency: string | null;
+    rawPayload: Record<string, unknown>;
+}
+/**
+ * Who is asking, and therefore what an unresolved provider state MEANS.
+ *
+ * The same read answers two different questions. Reconciliation — the caller
+ * that names no purpose — asks "is this attempt over", long after the buyer
+ * left, and an intent still waiting for its first payment method is over. A
+ * buyer standing in a live checkout asks "is this attempt settled yet", and the
+ * same state means the opposite: nobody has been asked anything.
+ *
+ * ⛔ Omitting the purpose keeps the reconciliation reading. Terminalizing real
+ * abandonment is the more expensive of the two errors to lose, so it is the
+ * behaviour a caller gets by default rather than one it must opt into.
+ */
+export interface PaymentProviderReconciliationProvider {
+    readPayment(input: {
+        providerPaymentId: string;
+        attempt?: ClaimedPaymentAttempt;
+        purpose?: ProviderReadPurpose;
+    }): Promise<ProviderReconciliationStatus>;
+    /** Atomically close an incomplete provider object before minting a replacement. */
+    closePayment?(input: {
+        providerPaymentId: string;
+    }): Promise<ProviderReconciliationStatus>;
+    /** Exact provider-side absence only; missing local acknowledgement is not
+     * absence proof and must never authorize another charge. */
+    findPaymentByLocalIntent?(input: {
+        attempt: ClaimedPaymentAttempt;
+    }): Promise<"found" | "absent">;
+}
+export interface ClaimedPaymentAttempt {
+    paymentAttemptId: string;
+    paymentIntentId: string;
+    paymentId: string;
+    orderId: string;
+    subscriptionId: string | null;
+    subscriptionCycleId: string | null;
+    provider: ReconciliationProviderKind;
+    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 ManualInteractivePreparedAttemptAbsenceEvidence = {
+    providerAbsenceConfirmed: true;
+    watchdogEvidence: true;
+    evidenceCode: "operator_verified_absence" | "operator_documented_absence";
+};
+export interface InteractivePreparedAttemptReopenResult {
+    paymentAttemptId: string;
+    paymentIntentId: string;
+    paymentAttemptStatus: "failed";
+    paymentIntentStatus: "failed";
+    replayed: boolean;
+}
+export interface PaymentProviderReconciliationPort {
+    claimPreparedAttempts(input: {
+        now: string;
+        staleAfterSeconds: number;
+        limit: number;
+        claimKey: string;
+    }): Promise<ClaimedPaymentAttempt[]>;
+    claimStaleAttempts(input: {
+        now: string;
+        staleAfterSeconds: number;
+        limit: number;
+        claimKey: string;
+    }): Promise<ClaimedPaymentAttempt[]>;
+    recordEvidence(input: {
+        idempotencyKey: string;
+        provider: ReconciliationProviderKind;
+        providerPaymentId: string | null;
+        paymentIntentId: string;
+        paymentAttemptId: string;
+        localStatus: string;
+        providerStatus: string;
+        correctionStatus: "observed" | "corrected" | "ignored" | "failed";
+        checkedAt: string;
+        payload: Record<string, unknown>;
+    }): Promise<{
+        replayed: boolean;
+    }>;
+    applyTerminalResult(input: {
+        idempotencyKey: string;
+        expectedOrderId: string;
+        expectedPaymentIntentId: string;
+        expectedPaymentAttemptId: string;
+        expectedPaymentId: string;
+        provider: ReconciliationProviderKind;
+        providerPaymentId: string;
+        localStatus: string;
+        providerStatus: string;
+        resultStatus: "succeeded" | "failed";
+        occurredAt: string;
+        failureReason: string | null;
+        /**
+         * The class the reading adapter already decided for this refusal, persisted
+         * beside the refusal itself on both the attempt and the dunning case the
+         * terminal write opens.
+         *
+         * OPTIONAL, and absence is a real state rather than a default: a caller that
+         * omits it writes exactly what it wrote before this field existed, because
+         * the RPC coalesces it to NULL and the SQL treats a NULL class as "stamp
+         * nothing" rather than "stamp NULL". Two of this port's three consumers
+         * (`paymentVerifyNowService`, `checkoutRecoveryPaymentResolver`) resolve a
+         * payment without classifying it and are pinned to stay classification-absent.
+         *
+         * Shape mirrors `applyPaymentResultRpc` deliberately, so the synchronous
+         * decline rail and this polling rail hand the control plane the same object.
+         */
+        failureClassification?: {
+            failureClass: string;
+            decidedBy: string;
+        } | null;
+        checkedAt: string;
+        payload: Record<string, unknown>;
+    }): Promise<{
+        replayed: boolean;
+        paymentResult: {
+            paymentIntentId: string;
+            paymentAttemptId: string;
+            paymentId: string;
+            orderId: string;
+            status: string;
+            kind: string;
+            replayed: boolean;
+        };
+        correctionStatus: "corrected" | "ignored";
+        subscriptionWebhookDunning: {
+            opened: boolean;
+            replayed: boolean;
+            caseId: string | null;
+        } | null;
+    }>;
+    reopenPreparedAttemptAfterAbsence(input: {
+        idempotencyKey: string;
+        paymentAttemptId: string;
+        expectedPaymentIntentId: string;
+        expectedSubscriptionCycleId: string;
+        operatorRef: string;
+        absenceCheckedAt: string;
+        nextRetryAt: string;
+        absenceEvidence: Record<string, unknown>;
+    }): Promise<{
+        replayed: boolean;
+    }>;
+    /**
+     * Optional because the automatic reconciliation worker and its provider
+     * neutral fixtures must not acquire an operator-only interactive capability.
+     * A caller that selects this rail must require the narrow interface below.
+     */
+    reopenInteractivePreparedAttemptAfterAbsence?(input: {
+        idempotencyKey: string;
+        paymentAttemptId: string;
+        expectedPaymentIntentId: string;
+        expectedOrderId: string;
+        expectedSubscriptionId: string | null;
+        expectedSubscriptionCycleId: string | null;
+        operatorRef: string;
+        absenceCheckedAt: string;
+        absenceEvidence: ManualInteractivePreparedAttemptAbsenceEvidence;
+    }): Promise<InteractivePreparedAttemptReopenResult>;
+}
+/**
+ * Service-role operator boundary for an interactive checkout, distinct from
+ * the renewal retry RPC. It terminalizes the local prepared attempt after a
+ * human/provider absence confirmation; it never schedules dunning or cron.
+ */
+export interface InteractivePreparedAttemptManualReconciliationPort extends PaymentProviderReconciliationPort {
+    reopenInteractivePreparedAttemptAfterAbsence(input: {
+        idempotencyKey: string;
+        paymentAttemptId: string;
+        expectedPaymentIntentId: string;
+        expectedOrderId: string;
+        expectedSubscriptionId: string | null;
+        expectedSubscriptionCycleId: string | null;
+        operatorRef: string;
+        absenceCheckedAt: string;
+        absenceEvidence: ManualInteractivePreparedAttemptAbsenceEvidence;
+    }): Promise<InteractivePreparedAttemptReopenResult>;
+}
+export interface PaymentProviderReconciliationWorkerResult {
+    ok: boolean;
+    checked: number;
+    corrected: number;
+    succeeded: number;
+    failed: number;
+    pending: number;
+    unknown: number;
+    ignored: number;
+    dunningOpened: number;
+    replayed: number;
+    providerCalls: number;
+    preparedWithoutProviderAck: number;
+    preparedAttemptsReopened: number;
+    manualReview: number;
+    /**
+     * Attempts whose rail has answered non-terminally for longer than that rail
+     * declares normal. Counted, never acted on: elapsed time is not evidence
+     * about money, so this surfaces a case for a human rather than resolving it.
+     */
+    silenceOverdue: number;
+    amountCurrencyMismatches: number;
+    failures: number;
+    skipped: boolean;
+    reason?: string;
+}
+export interface PaymentProviderReconciliationWorkerInput {
+    port: PaymentProviderReconciliationPort;
+    providers: Partial<Record<ReconciliationProviderKind, PaymentProviderReconciliationProvider>>;
+    now?: string;
+    staleAfterSeconds?: number;
+    batchSize?: number;
+    claimKey?: string;
+    /**
+     * When true, prepared attempts whose provider proves absence (see
+     * PaymentProviderReconciliationProvider.findPaymentByLocalIntent) and that
+     * are at least MIN_PREPARED_ABSENCE_REOPEN_AGE_SECONDS old are automatically
+     * reopened for cron retry via the operator RPC. Default false — the
+     * stranded-attempt loop stays operator-manual unless the flag is on.
+     */
+    autoReopenPreparedAbsence?: boolean;
+    /**
+     * Published rail capabilities, read to learn how long a non-terminal answer
+     * from each rail is still normal. Optional: without it no attempt is ever
+     * counted overdue, so omitting it preserves today's behaviour exactly.
+     */
+    capabilities?: SilenceWindowLookup;
+}
+/**
+ * The narrow slice of the capability registry this worker reads.
+ *
+ * Declared here rather than importing the whole registry type so the worker
+ * depends on the one question it asks - "when does this rail's silence stop
+ * being normal" - and not on the shape of every unattended-charge capability.
+ */
+export interface SilenceWindowLookup {
+    get(providerKind: string): {
+        terminalOutcomeReporting?: {
+            silenceBecomesSuspectAfterMinutes: number;
+        };
+    } | null;
+}
+export interface VerifiableAttemptSnapshot {
+    orderId: string;
+    orderClientId: string;
+    orderMode: string;
+    paymentIntentId: string;
+    intentStatus: string;
+    intentProviderPaymentId: string | null;
+    paymentAttemptId: string;
+    paymentId: string;
+    attemptStatus: string;
+    provider: string;
+    providerAttemptId: string | null;
+    providerSessionId: string | null;
+    amountMinor: number;
+    currency: string;
+    localUpdatedAt: string;
+}
+export interface PaymentVerifyReadPort {
+    readVerifiableAttempt(input: {
+        orderId: string;
+        paymentIntentId: string;
+    }): Promise<VerifiableAttemptSnapshot | null>;
+}
+export type PaymentVerifyNowResult = {
+    status: string;
+    verified: false;
+    applied: false;
+    providerPaymentId: string | null;
+    attempt: ClaimedPaymentAttempt | null;
+} | {
+    status: "unavailable" | "pending" | "manual_review";
+    verified: boolean;
+    applied: false;
+    providerPaymentId: string | null;
+    attempt: ClaimedPaymentAttempt | null;
+} | {
+    status: "succeeded" | "failed";
+    verified: true;
+    applied: boolean;
+    providerPaymentId: string;
+    attempt: ClaimedPaymentAttempt;
+};

package/dist/payments/contracts/reconciliation.js

@@ -0,0 +1 @@
+export {};

package/dist/payments/contracts/repair.d.ts

@@ -0,0 +1,92 @@
+import type { PaymentMethodHandoff } from "./adapter.js";
+import type { ClaimedPaymentAttempt, PaymentProviderReconciliationProvider, ProviderReconciliationStatus } from "./reconciliation.js";
+import type { ProviderReadPurpose } from "./evidence.js";
+export type CheckoutRecoveryPaymentResolution = {
+    kind: "paid";
+} | {
+    kind: "retry_new";
+} | {
+    kind: "resume_existing";
+    clientAction: PaymentRecoveryAction;
+} | {
+    kind: "awaiting_provider";
+} | {
+    kind: "manual_review";
+};
+export interface ProviderPaymentReferenceInput {
+    providerAttemptId: string | null;
+    providerSessionId: string | null;
+    intentProviderPaymentId: string | null;
+}
+export type PaymentRecoveryAction = {
+    provider: string;
+} & PaymentMethodHandoff;
+export interface ProviderRecoveryRead {
+    status: ProviderReconciliationStatus;
+    identityMatches: boolean;
+    configuredMoneyMatches: boolean;
+    manualReviewRequired: boolean;
+    clientAction: PaymentRecoveryAction | null;
+}
+/**
+ * Recovery is an explicit capability, not an optional method on generic
+ * reconciliation providers. One read returns both PSP truth and any transient
+ * buyer action, so a redeem never calls the provider twice.
+ */
+export interface PaymentProviderRecoveryProvider extends PaymentProviderReconciliationProvider {
+    resolvePaymentReference(input: ProviderPaymentReferenceInput): string | null;
+    readRecoveryPayment(input: {
+        providerPaymentId: string;
+        attempt: ClaimedPaymentAttempt;
+        purpose?: ProviderReadPurpose;
+    }): Promise<ProviderRecoveryRead>;
+}
+export interface CheckoutRecoveryPaymentResolver {
+    resolve(input: {
+        orderId: string;
+        paymentIntentId: string | null;
+        intentStatus?: string | null;
+    }): Promise<CheckoutRecoveryPaymentResolution>;
+}
+export interface ActivePaymentActionAuthority {
+    orderId: string;
+    clientId: string;
+    paymentIntentId: string;
+    paymentAttemptId: string;
+    executionRail: string;
+}
+export interface CheckoutActivePaymentActionResolver {
+    readActiveAction(authority: ActivePaymentActionAuthority): Promise<PaymentRecoveryAction | null>;
+}
+export type CheckoutActionReadProvider = Pick<PaymentProviderRecoveryProvider, "resolvePaymentReference" | "readRecoveryPayment">;
+/** Method collection only. Hosts authorize ownership before calling this port.
+ * The result never confirms payment, redeems a token or writes a subscription.
+ * Handoffs remain transient; unsupported must be shown as an explicit refusal.
+ */
+export interface PaymentRepairMethodPort {
+    setupMethod(input: {
+        customer: string;
+        metadata: Record<string, string>;
+        idempotencyKey: string;
+    }): Promise<{
+        kind: "ready";
+        setupRef: string;
+        handoff: PaymentMethodHandoff;
+        replayed: boolean;
+    } | {
+        kind: "unsupported";
+    }>;
+}
+/** Host-selected durable truth scope. Unsupported schema never opens a store. */
+export interface PaymentServicesOptions {
+    schema?: {
+        truth: "supported" | "unsupported";
+    };
+    openTruth?: () => Promise<{
+        port: import("./truth.js").PaymentTruthPort;
+        close(): Promise<void>;
+    }>;
+}
+export interface PaymentServices {
+    run<T>(work: (port: import("./truth.js").PaymentTruthPort) => Promise<T>): Promise<T>;
+}

package/dist/payments/contracts/repair.js

@@ -0,0 +1 @@
+export {};