@openlup/platform 0.19.0 → 0.21.0

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 {};

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

@@ -0,0 +1,92 @@
+export type PaymentTruthOutcome = "captured" | "refused" | "indeterminate";
+/**
+ * How a refusal looked to the settlement source that reported it.
+ *
+ * NOT the retry taxonomy. `PaymentFailureClass` in `@openlup/core/payment` is a
+ * different vocabulary with no value in common: that one answers "may this be
+ * retried, and how", and is what `commerce_payment_attempts.failure_class`
+ * persists. This one answers "what did the source say happened" and never leaves
+ * this module's reconciliation ledger. They shared a name until this wave, which
+ * meant an import could quietly resolve to the wrong five strings.
+ */
+export type PaymentTruthRefusalClass = "authorization_refused" | "insufficient_funds" | "method_unavailable" | "risk_refused" | "unknown_refusal";
+export type PaymentSourceEvidence = {
+    sourceKind: "accepted_event" | "reconciliation_read";
+    sourceReference: string;
+    observedStatus: string;
+    observedAt: string;
+    payloadFingerprint: string;
+};
+export type PaymentTruthEvent = {
+    sourceEventId: string;
+    idempotencyKey: string;
+    settlementIntentId: string;
+    outcome: PaymentTruthOutcome;
+    amountMinor: number;
+    currency: string;
+    occurredAt: string;
+    failure: {
+        classification: PaymentTruthRefusalClass;
+        reason: string | null;
+    } | null;
+    evidence: PaymentSourceEvidence;
+};
+export type PaymentReconciliationResult = {
+    eventId: string;
+    idempotencyKey: string;
+    evidenceStatus: "observed" | "failed";
+    outcome: PaymentTruthOutcome;
+    occurredAt: string;
+    failure: PaymentTruthEvent["failure"];
+    evidence: PaymentSourceEvidence;
+};
+export type PaymentTruthReadback = {
+    event: {
+        id: string;
+        sourceEventId: string;
+        fingerprint: string;
+        state: "open" | "settled";
+        outcome: PaymentTruthOutcome;
+        replayed: boolean;
+    };
+    effects: {
+        paymentResultRecorded: boolean;
+        dunningOpened: boolean;
+        accountingRequested: boolean;
+    };
+    financial: {
+        settlementStatus: string | null;
+        orderStatus: string | null;
+        subscriptionStatus: string | null;
+        accountingStatus: string | null;
+        amountMinor: number;
+        currency: string;
+    };
+};
+export interface PaymentTruthPort {
+    ingestEvent(input: PaymentTruthEvent): Promise<PaymentTruthReadback>;
+    recordReconciliation(input: PaymentReconciliationResult): Promise<PaymentTruthReadback>;
+    sweepOpenEvents(input: {
+        now: string;
+        limit: number;
+    }): Promise<{
+        claimed: number;
+        settledIgnored: number;
+        eventIds: string[];
+    }>;
+    readEvent(eventId: string): Promise<PaymentTruthReadback | null>;
+}
+export type CanonicalPaymentSource = {
+    sourceEventId: string;
+    eventKind: string;
+    settlementIntentId: string | null;
+    amountMinor: number | null;
+    currency: string | null;
+    occurredAt: string | null;
+    payloadFingerprint: string;
+};
+export type PostgresPaymentTruthOptions = {
+    dunningTemplateSlug: string;
+    recoveryUrlPath: string;
+    recoveryTemplateSlug: string;
+};

package/dist/payments/contracts/truth.js

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

package/dist/payments/eventConformanceRunner.d.ts

@@ -0,0 +1,12 @@
+import type { PaymentExecutionBaseInput } from "@openlup/core/testing";
+import type { SimulatorResult, ExecutionSubject, ExecutionProviderIdentity, ExecutionEvidence, DurableEventCardinalityExpectations, DurableEventCapability, DurableEventEvidence } from "./contracts/conformance.js";
+/** Framework-free execution proof; durable event evidence is a separate capability. */
+export declare function runExecutionConformance<TInput extends PaymentExecutionBaseInput, TResult extends SimulatorResult>(input: ExecutionProviderIdentity & {
+    readonly captured: ExecutionSubject<TInput, TResult>;
+    readonly capturedLedger: {
+        cardinality(): number;
+    };
+    readonly refused: ExecutionSubject<TInput, TResult>;
+    readonly request: TInput;
+}): Promise<ExecutionEvidence>;
+export declare function runDurableEventConformance(subject: DurableEventCapability, expected: DurableEventCardinalityExpectations): Promise<DurableEventEvidence>;

package/dist/payments/eventConformanceRunner.js

@@ -0,0 +1,125 @@
+import { validatePaymentExecutionContractResult, } from "@openlup/core/testing";
+/** Framework-free execution proof; durable event evidence is a separate capability. */
+export async function runExecutionConformance(input) {
+    assertEqual(input.capturedLedger.cardinality(), 0, "initial captured ledger cardinality");
+    const captured = await input.captured.execute(input.request);
+    const refused = await input.refused.execute(input.request);
+    for (const result of [captured, refused]) {
+        const validation = validatePaymentExecutionContractResult({
+            input: input.request,
+            result,
+            expectedProvider: input.expectedProvider,
+        });
+        if (!validation.ok || validation.issues.length) {
+            throw new Error(`Invalid simulator payment execution result: ${JSON.stringify(validation.issues)}`);
+        }
+    }
+    assertEqual(captured.responsePayload.outcome, "captured", "captured subject outcome");
+    assertEqual(refused.responsePayload.outcome, "refused", "refused subject outcome");
+    const results = [captured, refused];
+    const providerCalls = results.filter((result) => result.responsePayload.providerCall === true).length;
+    const capturedEffects = input.capturedLedger.cardinality();
+    const permanentRefusals = results.filter((result) => result.responsePayload.outcome === "refused"
+        && result.providerDecline?.code === "payment_failed" && result.providerDecline.mandateUnsupported === false).length;
+    if (capturedEffects !== 1 || permanentRefusals !== 1) {
+        throw new Error("Expected one captured effect and one permanent simulator refusal.");
+    }
+    return {
+        capability: { name: "simulator-execution", durabilityClaim: false },
+        executions: results.length,
+        providerCalls,
+        capturedEffects,
+        permanentRefusals,
+    };
+}
+export async function runDurableEventConformance(subject, expected) {
+    subject.assertSafe();
+    let evidence;
+    try {
+        assertEqual((await subject.reset()).residualRows, 0, "baseline residual rows");
+        await subject.seed();
+        const baseline = await subject.snapshot();
+        assertCoreCounts(baseline.counts, expected.fixture, expected.baseline);
+        const aSuccess = await deliver(subject, "outOfOrder", "a-success", "succeeded", "2026-07-29T10:00:00.000Z");
+        const afterOutOfOrderSuccess = await subject.snapshot();
+        assertEvent(afterOutOfOrderSuccess, aSuccess, "a-success", "outOfOrder", "processed");
+        assertCoreCounts(afterOutOfOrderSuccess.counts, expected.fixture, expected.afterOutOfOrderSuccess);
+        assertSucceeded(afterOutOfOrderSuccess.aggregates.outOfOrder);
+        const aFailure = await deliver(subject, "outOfOrder", "a-failure", "failed", "2026-07-29T09:00:00.000Z");
+        const afterOutOfOrderFailure = await subject.snapshot();
+        assertEvent(afterOutOfOrderFailure, aFailure, "a-failure", "outOfOrder", "ignored");
+        assertCoreCounts(afterOutOfOrderFailure.counts, expected.fixture, expected.afterOutOfOrderFailure);
+        assertSucceeded(afterOutOfOrderFailure.aggregates.outOfOrder);
+        assertStableAggregate(baseline.aggregates.outOfOrder, afterOutOfOrderFailure.aggregates.outOfOrder);
+        const duplicate = await deliver(subject, "outOfOrder", "a-success", "succeeded", "2026-07-29T10:00:00.000Z");
+        assertEqual(duplicate.ingest.replayed, true, "duplicate ingest replay");
+        assertEqual(duplicate.apply.replayed, true, "duplicate apply replay");
+        assertEqual(duplicate.ingest.paymentEventId, aSuccess.ingest.paymentEventId, "duplicate canonical event id");
+        const afterDuplicate = await subject.snapshot();
+        assertEvent(afterDuplicate, duplicate, "a-success", "outOfOrder", "processed");
+        assertCoreCounts(afterDuplicate.counts, expected.fixture, expected.afterDuplicate);
+        assertSucceeded(afterDuplicate.aggregates.outOfOrder);
+        assertStableAggregate(afterOutOfOrderFailure.aggregates.outOfOrder, afterDuplicate.aggregates.outOfOrder);
+        const bFailure = await deliver(subject, "lateSuccess", "b-failure", "failed", "2026-07-29T09:30:00.000Z");
+        const afterLateFailure = await subject.snapshot();
+        assertEvent(afterLateFailure, bFailure, "b-failure", "lateSuccess", "processed");
+        assertCoreCounts(afterLateFailure.counts, expected.fixture, expected.afterLateFailure);
+        assertEqual(JSON.stringify(Object.values(afterLateFailure.aggregates.lateSuccess).slice(4)), JSON.stringify(["pending_payment", "failed", "failed", "failed"]), "late failure statuses");
+        const bSuccess = await deliver(subject, "lateSuccess", "b-success", "succeeded", "2026-07-29T10:30:00.000Z");
+        const final = await subject.snapshot();
+        assertEvent(final, bSuccess, "b-success", "lateSuccess", "processed");
+        assertCoreCounts(final.counts, expected.fixture, expected.final);
+        assertSucceeded(final.aggregates.lateSuccess);
+        assertStableAggregate(baseline.aggregates.lateSuccess, final.aggregates.lateSuccess);
+        evidence = {
+            capability: { name: subject.name, durabilityClaim: true },
+            baseline,
+            afterOutOfOrderSuccess,
+            afterOutOfOrderFailure,
+            afterDuplicate,
+            afterLateFailure,
+            final,
+        };
+    }
+    finally {
+        const cleanup = await subject.reset();
+        assertEqual(cleanup.residualRows, 0, "cleanup residual rows");
+    }
+    if (!evidence)
+        throw new Error("Payment-event conformance produced no evidence");
+    return { ...evidence, cleanupResidualRows: 0 };
+}
+async function deliver(subject, aggregate, eventKey, resultStatus, occurredAt) {
+    const ingest = await subject.ingest({ aggregate, eventKey, resultStatus, occurredAt });
+    const apply = await subject.apply({ aggregate, eventKey, paymentEventId: ingest.paymentEventId, resultStatus, occurredAt });
+    return { ingest, apply };
+}
+function assertCoreCounts(counts, fixture, writes) {
+    for (const [key, value] of Object.entries({ ...fixture, ...writes })) {
+        assertEqual(counts[key], value, `${key} count`);
+    }
+}
+function assertEvent(snapshot, receipt, eventKey, aggregate, expectedState) {
+    const event = snapshot.events.find((candidate) => candidate.eventKey === eventKey);
+    if (!event)
+        throw new Error(`Missing durable event ${eventKey}`);
+    assertEqual(event.id, receipt.ingest.paymentEventId, `${eventKey} canonical event id`);
+    assertEqual(event.paymentIntentId, snapshot.aggregates[aggregate].paymentIntentId, `${eventKey} intent id`);
+    assertEqual(event.paymentAttemptId, snapshot.aggregates[aggregate].paymentAttemptId, `${eventKey} attempt id`);
+    assertEqual(event.processingStatus, expectedState, `${eventKey} processing status`);
+}
+function assertStableAggregate(before, after) {
+    for (const key of ["orderId", "paymentId", "paymentIntentId", "paymentAttemptId"]) {
+        assertEqual(after[key], before[key], `stable ${key}`);
+    }
+}
+function assertSucceeded(aggregate) {
+    assertEqual(aggregate.orderStatus, "paid", "order status");
+    assertEqual(aggregate.paymentStatus, "succeeded", "payment status");
+    assertEqual(aggregate.intentStatus, "succeeded", "intent status");
+    assertEqual(aggregate.attemptStatus, "succeeded", "attempt status");
+}
+function assertEqual(actual, expected, label) {
+    if (actual !== expected)
+        throw new Error(`${label}: expected ${String(expected)}, received ${String(actual)}`);
+}

package/dist/payments/index.d.ts

@@ -0,0 +1,16 @@
+export { executePreparedAttemptMechanism } from "./preparedAttempt.js";
+export { paymentSourceFingerprint, paymentPayloadFingerprint, paymentTruthFingerprint, paymentReconciliationFingerprint, assertPaymentTruthEvent } from "./paymentTruth.js";
+export { createVerifiedPaymentIngress } from "./verifiedIngress.js";
+export { readMethodLifecycleEvent } from "./paymentMethodLifecycle.js";
+export { handoffExplicitPaymentRefusal } from "./paymentWebhookPostProcessing.js";
+export { runPaymentProviderReconciliationWorker } from "./paymentProviderReconciliationWorker.js";
+export { verifyPaymentAttemptNow } from "./paymentVerifyNowService.js";
+export { runExecutionConformance, runDurableEventConformance } from "./eventConformanceRunner.js";
+export { runPaymentAdapterConformance } from "./adapterConformance.js";
+export { createPostgresPaymentTruthPort } from "./postgresPaymentTruth.js";
+export { PAYMENT_MIGRATIONS } from "./sql.js";
+export { paymentSchemaDescriptor } from "./schemaCapabilities.js";
+export { createCheckoutActivePaymentActionResolver } from "./checkoutActivePaymentActionResolver.js";
+export { createCheckoutRecoveryPaymentResolver } from "./checkoutRecoveryPaymentResolver.js";
+export { createCommercePaymentVerifyHandler } from "./paymentVerifyNowHandler.js";
+export { createPaymentServices } from "./bindings.js";

package/dist/payments/index.js

@@ -0,0 +1,16 @@
+export { executePreparedAttemptMechanism } from "./preparedAttempt.js";
+export { paymentSourceFingerprint, paymentPayloadFingerprint, paymentTruthFingerprint, paymentReconciliationFingerprint, assertPaymentTruthEvent } from "./paymentTruth.js";
+export { createVerifiedPaymentIngress } from "./verifiedIngress.js";
+export { readMethodLifecycleEvent } from "./paymentMethodLifecycle.js";
+export { handoffExplicitPaymentRefusal } from "./paymentWebhookPostProcessing.js";
+export { runPaymentProviderReconciliationWorker } from "./paymentProviderReconciliationWorker.js";
+export { verifyPaymentAttemptNow } from "./paymentVerifyNowService.js";
+export { runExecutionConformance, runDurableEventConformance } from "./eventConformanceRunner.js";
+export { runPaymentAdapterConformance } from "./adapterConformance.js";
+export { createPostgresPaymentTruthPort } from "./postgresPaymentTruth.js";
+export { PAYMENT_MIGRATIONS } from "./sql.js";
+export { paymentSchemaDescriptor } from "./schemaCapabilities.js";
+export { createCheckoutActivePaymentActionResolver } from "./checkoutActivePaymentActionResolver.js";
+export { createCheckoutRecoveryPaymentResolver } from "./checkoutRecoveryPaymentResolver.js";
+export { createCommercePaymentVerifyHandler } from "./paymentVerifyNowHandler.js";
+export { createPaymentServices } from "./bindings.js";