@openlup/platform 0.19.0 → 0.21.0

package/dist/payments/paymentTruth.js

@@ -0,0 +1,125 @@
+import { createHash } from "node:crypto";
+const PAYMENT_TRUTH_REFUSAL_CLASSES = [
+    "authorization_refused",
+    "insufficient_funds",
+    "method_unavailable",
+    "risk_refused",
+    "unknown_refusal",
+];
+export function paymentReconciliationFingerprint(input) {
+    if (!input.eventId.trim() || input.idempotencyKey.trim().length < 8 || !isInstant(input.occurredAt)) {
+        throw new Error("payment_reconciliation_input_invalid");
+    }
+    if (input.evidenceStatus === "failed" && input.outcome !== "indeterminate") {
+        throw new Error("payment_reconciliation_failure_cannot_terminalize");
+    }
+    if (input.outcome === "refused" && !input.failure) {
+        throw new Error("payment_truth_refusal_classification_required");
+    }
+    if (input.outcome !== "refused" && input.failure) {
+        throw new Error("payment_truth_failure_only_for_refusal");
+    }
+    assertPaymentFailure(input.failure);
+    assertPaymentSourceEvidence(input.evidence);
+    return digest({
+        eventId: input.eventId,
+        evidenceStatus: input.evidenceStatus,
+        outcome: input.outcome,
+        occurredAt: input.occurredAt,
+        failure: input.failure,
+        evidence: input.evidence,
+    });
+}
+/** Fingerprint accepted at a provider boundary before local ownership is known. */
+export function paymentSourceFingerprint(input) {
+    if (!input.sourceEventId.trim() || !input.eventKind.trim()
+        || (input.occurredAt !== null && !isInstant(input.occurredAt))) {
+        throw new Error("payment_source_fingerprint_input_invalid");
+    }
+    if (!/^[0-9a-f]{64}$/.test(input.payloadFingerprint)) {
+        throw new Error("payment_truth_payload_fingerprint_invalid");
+    }
+    return digest(input);
+}
+export function paymentPayloadFingerprint(payload) {
+    return digest(payload);
+}
+/** Canonical identity for one normalized event; idempotency is deliberately not part of it. */
+export function paymentTruthFingerprint(input) {
+    assertPaymentTruthEvent(input);
+    return digest({
+        sourceEventId: input.sourceEventId,
+        settlementIntentId: input.settlementIntentId,
+        outcome: input.outcome,
+        amountMinor: input.amountMinor,
+        currency: input.currency,
+        occurredAt: input.occurredAt,
+        failure: input.failure,
+        evidence: input.evidence,
+    });
+}
+export function assertPaymentTruthEvent(input) {
+    if (!input.sourceEventId.trim())
+        throw new Error("payment_truth_source_event_id_required");
+    if (input.idempotencyKey.trim().length < 8)
+        throw new Error("payment_truth_idempotency_key_invalid");
+    if (!input.settlementIntentId.trim())
+        throw new Error("payment_truth_settlement_intent_required");
+    if (!Number.isSafeInteger(input.amountMinor) || input.amountMinor <= 0) {
+        throw new Error("payment_truth_amount_invalid");
+    }
+    if (!/^[A-Z]{3}$/.test(input.currency))
+        throw new Error("payment_truth_currency_invalid");
+    if (!isInstant(input.occurredAt) || !isInstant(input.evidence.observedAt)) {
+        throw new Error("payment_truth_time_invalid");
+    }
+    if (!input.evidence.sourceReference.trim() || !input.evidence.observedStatus.trim()) {
+        throw new Error("payment_truth_source_evidence_invalid");
+    }
+    if (!/^[0-9a-f]{64}$/.test(input.evidence.payloadFingerprint)) {
+        throw new Error("payment_truth_payload_fingerprint_invalid");
+    }
+    if (input.outcome === "refused" && !input.failure) {
+        throw new Error("payment_truth_refusal_classification_required");
+    }
+    if (input.outcome !== "refused" && input.failure) {
+        throw new Error("payment_truth_failure_only_for_refusal");
+    }
+    assertPaymentFailure(input.failure);
+    assertPaymentSourceEvidence(input.evidence);
+}
+function isInstant(value) {
+    return value.trim().length > 0 && Number.isFinite(Date.parse(value));
+}
+function stableJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stableJson).join(",")}]`;
+    if (value && typeof value === "object") {
+        return `{${Object.entries(value)
+            .sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0)
+            .map(([key, entry]) => `${JSON.stringify(key)}:${stableJson(entry)}`)
+            .join(",")}}`;
+    }
+    return JSON.stringify(value);
+}
+function assertPaymentFailure(failure) {
+    if (failure && !PAYMENT_TRUTH_REFUSAL_CLASSES.includes(failure.classification)) {
+        throw new Error("payment_truth_failure_class_invalid");
+    }
+}
+function assertPaymentSourceEvidence(evidence) {
+    if (evidence.sourceKind !== "accepted_event" && evidence.sourceKind !== "reconciliation_read") {
+        throw new Error("payment_truth_source_kind_invalid");
+    }
+    if (!evidence.sourceReference.trim() || !evidence.observedStatus.trim()) {
+        throw new Error("payment_truth_source_evidence_invalid");
+    }
+    if (!isInstant(evidence.observedAt))
+        throw new Error("payment_truth_time_invalid");
+    if (!/^[0-9a-f]{64}$/.test(evidence.payloadFingerprint)) {
+        throw new Error("payment_truth_payload_fingerprint_invalid");
+    }
+}
+function digest(value) {
+    return createHash("sha256").update(stableJson(value)).digest("hex");
+}

package/dist/payments/paymentVerifyNowHandler.d.ts

@@ -0,0 +1,27 @@
+import { z } from "zod";
+import type { HttpRequest, HttpResponse } from "../http/index.js";
+import type { BffResponder } from "../bff/index.js";
+import type { PaymentProviderReconciliationProvider, PaymentProviderReconciliationPort } from "./contracts/reconciliation.js";
+import type { PaymentVerifyReadPort } from "./contracts/reconciliation.js";
+/**
+ * Buyer-triggered "verify now": after a CLIENT-side confirm failure the FE has
+ * the only copy of the outcome (a pre-charge provider rejection emits no
+ * webhook), so it asks the server to read the provider immediately instead of
+ * waiting for the next adopter-configured reconciliation pass. The client can never assert a result — truth is the live
+ * provider readback, and the only write path is the reconciliation apply RPC
+ * with the cron's own idempotency key, so both paths converge replay-safely.
+ */
+export declare const paymentVerifyRequestSchema: z.ZodObject<{
+    orderId: z.ZodGUID;
+    paymentIntentId: z.ZodGUID;
+    clientId: z.ZodGUID;
+}, z.core.$strip>;
+export type PaymentVerifyRequest = z.infer<typeof paymentVerifyRequestSchema>;
+export declare function createCommercePaymentVerifyHandler(deps: {
+    readPort: PaymentVerifyReadPort;
+    applyPort: Pick<PaymentProviderReconciliationPort, "applyTerminalResult">;
+    providers: Partial<Record<string, PaymentProviderReconciliationProvider>>;
+    mutationsEnabled: () => boolean;
+    now?: () => Date;
+    responder: BffResponder;
+}): (req: HttpRequest, res: HttpResponse) => Promise<void>;

package/dist/payments/paymentVerifyNowHandler.js

@@ -0,0 +1,70 @@
+import { z } from "zod";
+import { verifyPaymentAttemptNow } from "./paymentVerifyNowService.js";
+/**
+ * Buyer-triggered "verify now": after a CLIENT-side confirm failure the FE has
+ * the only copy of the outcome (a pre-charge provider rejection emits no
+ * webhook), so it asks the server to read the provider immediately instead of
+ * waiting for the next adopter-configured reconciliation pass. The client can never assert a result — truth is the live
+ * provider readback, and the only write path is the reconciliation apply RPC
+ * with the cron's own idempotency key, so both paths converge replay-safely.
+ */
+export const paymentVerifyRequestSchema = z.object({
+    orderId: z.guid(),
+    paymentIntentId: z.guid(),
+    clientId: z.guid(),
+});
+export function createCommercePaymentVerifyHandler(deps) {
+    const now = deps.now ?? (() => new Date());
+    const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = deps.responder;
+    return async (req, res) => {
+        if (req.method !== "POST") {
+            sendMethodNotAllowed(res, ["POST"]);
+            return;
+        }
+        if (!deps.mutationsEnabled()) {
+            sendBffError(res, "UPSTREAM_UNAVAILABLE", "Provider payment verify is disabled", {
+                details: {
+                    feature: "payment-verify",
+                    featureFlag: "COMMERCE_PROVIDER_PAYMENTS_ENABLED",
+                    reason: "feature_flag_disabled",
+                },
+            });
+            return;
+        }
+        const parsed = paymentVerifyRequestSchema.safeParse(req.body);
+        if (!parsed.success) {
+            sendBffError(res, "BAD_REQUEST", "Invalid payment verify request", {
+                details: parsed.error.flatten(),
+            });
+            return;
+        }
+        const snapshot = await deps.readPort.readVerifiableAttempt(parsed.data);
+        if (!snapshot) {
+            sendBffError(res, "NOT_FOUND", "Payment not found");
+            return;
+        }
+        // Same non-leaking ownership shape as payment-status: a non-owning triple
+        // reads as absent rather than confirming the payment exists.
+        if (snapshot.orderClientId !== parsed.data.clientId) {
+            sendBffError(res, "NOT_FOUND", "Payment not found");
+            return;
+        }
+        const result = await verifyPaymentAttemptNow({
+            snapshot,
+            applyPort: deps.applyPort,
+            providers: deps.providers,
+            now,
+            // This route has exactly one kind of caller: a browser sitting in a live
+            // checkout, asking about the attempt it is currently waiting on. The
+            // reconciliation worker never comes through here — it holds the provider
+            // and calls `readPayment` itself — so the purpose is a property of the
+            // seam, not something a request may choose.
+            purpose: "active_checkout",
+        });
+        sendBffSuccess(res, {
+            status: result.status,
+            verified: result.verified,
+            applied: result.applied,
+        });
+    };
+}

package/dist/payments/paymentVerifyNowService.d.ts

@@ -0,0 +1,23 @@
+import type { ProviderReadPurpose } from "./contracts/evidence.js";
+import type { VerifiableAttemptSnapshot, PaymentVerifyNowResult } from "./contracts/reconciliation.js";
+import type { ClaimedPaymentAttempt, PaymentProviderReconciliationPort, PaymentProviderReconciliationProvider, ProviderReconciliationStatus } from "./contracts/reconciliation.js";
+/**
+ * Shared buyer/cron-compatible live PSP read. It never accepts a browser
+ * outcome and terminal writes still pass through the canonical reconciliation
+ * RPC, so recovery cannot create a second payment truth path.
+ */
+export declare function verifyPaymentAttemptNow(input: {
+    snapshot: VerifiableAttemptSnapshot;
+    applyPort: Pick<PaymentProviderReconciliationPort, "applyTerminalResult">;
+    providers: Partial<Record<string, PaymentProviderReconciliationProvider>>;
+    now: () => Date;
+    providerPaymentId?: string;
+    providerStatus?: ProviderReconciliationStatus;
+    /**
+     * Passed straight to the provider read. A caller that omits it gets the
+     * reconciliation reading, in which an intent still waiting for its first
+     * payment method is a finished, abandoned attempt.
+     */
+    purpose?: ProviderReadPurpose;
+}): Promise<PaymentVerifyNowResult>;
+export declare function toClaimedAttemptShape(snapshot: VerifiableAttemptSnapshot, providerPaymentId: string): ClaimedPaymentAttempt;

package/dist/payments/paymentVerifyNowService.js

@@ -0,0 +1,93 @@
+import { applyResultKey, evidencePayload, terminalAmountMismatch } from "./paymentProviderReconciliationEvidence.js";
+const LIVE_ATTEMPT_STATUSES = new Set(["sent_to_provider", "requires_action", "processing", "created"]);
+/**
+ * Shared buyer/cron-compatible live PSP read. It never accepts a browser
+ * outcome and terminal writes still pass through the canonical reconciliation
+ * RPC, so recovery cannot create a second payment truth path.
+ */
+export async function verifyPaymentAttemptNow(input) {
+    const { snapshot } = input;
+    if (!LIVE_ATTEMPT_STATUSES.has(snapshot.attemptStatus)) {
+        return { status: snapshot.attemptStatus, verified: false, applied: false, providerPaymentId: null, attempt: null };
+    }
+    const provider = input.providers[snapshot.provider];
+    const providerPaymentId = input.providerPaymentId
+        ?? snapshot.providerAttemptId
+        ?? snapshot.intentProviderPaymentId
+        ?? snapshot.providerSessionId;
+    if (!provider || !providerPaymentId) {
+        return { status: "unavailable", verified: false, applied: false, providerPaymentId, attempt: null };
+    }
+    const attempt = toClaimedAttemptShape(snapshot, providerPaymentId);
+    const providerStatus = input.providerStatus
+        ?? await provider.readPayment({
+            providerPaymentId,
+            attempt,
+            ...(input.purpose ? { purpose: input.purpose } : {}),
+        });
+    if (providerStatus.status !== "succeeded" && providerStatus.status !== "failed") {
+        return {
+            // Preserve the established payment-verify contract: an unknown provider
+            // vocabulary is still non-terminal and therefore reported as pending.
+            status: "pending",
+            verified: true,
+            applied: false,
+            providerPaymentId,
+            attempt,
+        };
+    }
+    if (terminalAmountMismatch(attempt, providerStatus)) {
+        return { status: "manual_review", verified: true, applied: false, providerPaymentId, attempt };
+    }
+    const checkedAt = input.now().toISOString();
+    const applied = await input.applyPort.applyTerminalResult({
+        idempotencyKey: applyResultKey(attempt, providerStatus.status),
+        expectedOrderId: snapshot.orderId,
+        expectedPaymentIntentId: snapshot.paymentIntentId,
+        expectedPaymentAttemptId: snapshot.paymentAttemptId,
+        expectedPaymentId: snapshot.paymentId,
+        provider: attempt.provider,
+        providerPaymentId,
+        localStatus: snapshot.attemptStatus,
+        providerStatus: providerStatus.providerStatus,
+        resultStatus: providerStatus.status,
+        occurredAt: providerStatus.occurredAt ?? checkedAt,
+        failureReason: providerStatus.status === "failed"
+            ? providerStatus.failureReason ?? `provider_verify_${providerStatus.providerStatus}`
+            : null,
+        checkedAt,
+        payload: evidencePayload(attempt, providerStatus, {
+            source: "commerce-payment-verify.v0",
+            trigger: "buyer_confirm_settled",
+        }),
+    });
+    return {
+        status: providerStatus.status,
+        verified: true,
+        applied: applied.correctionStatus === "corrected" && !applied.replayed,
+        providerPaymentId,
+        attempt,
+    };
+}
+export function toClaimedAttemptShape(snapshot, providerPaymentId) {
+    return {
+        paymentAttemptId: snapshot.paymentAttemptId,
+        paymentIntentId: snapshot.paymentIntentId,
+        paymentId: snapshot.paymentId,
+        orderId: snapshot.orderId,
+        subscriptionId: null,
+        subscriptionCycleId: null,
+        provider: snapshot.provider,
+        providerPaymentId,
+        providerAttemptId: snapshot.providerAttemptId,
+        providerSessionId: snapshot.providerSessionId,
+        attemptStatus: snapshot.attemptStatus,
+        intentStatus: snapshot.intentStatus,
+        amountMinor: snapshot.amountMinor,
+        currency: snapshot.currency,
+        orderMode: snapshot.orderMode,
+        cycleRetryAttempt: 0,
+        cycleNextRetryAt: null,
+        localUpdatedAt: snapshot.localUpdatedAt,
+    };
+}

package/dist/payments/paymentWebhookPostProcessing.d.ts

@@ -0,0 +1,22 @@
+export type PaymentRefusalHandoff = {
+    outcome: "refused" | "not_refused";
+    idempotencyKey: string;
+    paymentIntentId: string | null;
+    sourceEventId: string;
+    failureReason: string | null;
+    occurredAt: string;
+};
+export interface PaymentFailureDunningPort {
+    openFromExplicitRefusal(input: {
+        idempotencyKey: string;
+        paymentIntentId: string;
+        sourceEventId: string;
+        failureReason: string | null;
+        occurredAt: string;
+    }): Promise<void>;
+}
+/**
+ * Neutral terminal handoff. Only explicit refusal evidence may enter dunning;
+ * silence, timeout and every other non-terminal answer are deliberate no-ops.
+ */
+export declare function handoffExplicitPaymentRefusal(input: PaymentRefusalHandoff, port: PaymentFailureDunningPort): Promise<void>;

package/dist/payments/paymentWebhookPostProcessing.js

@@ -0,0 +1,15 @@
+/**
+ * Neutral terminal handoff. Only explicit refusal evidence may enter dunning;
+ * silence, timeout and every other non-terminal answer are deliberate no-ops.
+ */
+export async function handoffExplicitPaymentRefusal(input, port) {
+    if (input.outcome !== "refused" || !input.paymentIntentId)
+        return;
+    await port.openFromExplicitRefusal({
+        idempotencyKey: input.idempotencyKey,
+        paymentIntentId: input.paymentIntentId,
+        sourceEventId: input.sourceEventId,
+        failureReason: input.failureReason,
+        occurredAt: input.occurredAt,
+    });
+}

package/dist/payments/postgresPaymentTruth.d.ts

@@ -0,0 +1,10 @@
+import type { PaymentTruthPort } from "./contracts/truth.js";
+import type { PostgresPaymentTruthOptions } from "./contracts/truth.js";
+interface PgQueryExecutor {
+    query(text: string, values?: unknown[]): Promise<{
+        rows: Record<string, unknown>[];
+    }>;
+}
+/** Direct-PG caller for the provider-neutral payment truth public forward. */
+export declare function createPostgresPaymentTruthPort(executor: PgQueryExecutor, options: PostgresPaymentTruthOptions): PaymentTruthPort;
+export {};

package/dist/payments/postgresPaymentTruth.js

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

package/dist/payments/preparedAttempt.d.ts

@@ -0,0 +1,6 @@
+import type { PaymentExecutionBaseInput, PaymentExecutionBaseResult } from "@openlup/core/payment";
+import type { PreparedAttemptExecutionInput, PreparedAttemptExecutionResult, PreparedAttemptFailurePolicy } from "./contracts/preparedAttempt.js";
+/** Interactive ordering only; the caller binds nominal trust and native errors. */
+export declare function executePreparedAttemptMechanism<I extends PaymentExecutionBaseInput, R extends PaymentExecutionBaseResult & {
+    nextActionKind: N | null;
+}, P extends string, N extends string, E extends Error>(input: PreparedAttemptExecutionInput<I, R, P, N>, policy: PreparedAttemptFailurePolicy<E, N>): Promise<PreparedAttemptExecutionResult<R>>;

package/dist/payments/preparedAttempt.js

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

package/dist/payments/preparedAttemptFinalization.d.ts

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

package/dist/payments/preparedAttemptFinalization.js

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

package/dist/payments/schemaCapabilities.d.ts

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

package/dist/payments/schemaCapabilities.js

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

package/dist/payments/sql.d.ts

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