@openlup/platform 0.20.0 → 0.22.0

package/dist/fulfillment/verifiedIngress.js

@@ -0,0 +1,66 @@
+import { applyFulfillmentObservationEffects } from "./fulfillmentObservationEffects.js";
+import { observationStatusPolicy, projectObservation } from "./observationProjection.js";
+import { uniqueTrackingReferences } from "./providerTrackingReferences.js";
+/** Adapter verification owns auth-before-parse; the host owns durable replay. */
+export async function verifyAndNormalizeFulfillmentObservation(input) {
+    if (!input.enabled)
+        return { kind: "refused", refusal: { reason: "disabled", phase: "verify", retryable: false } };
+    const verified = await input.provider.verifyAndNormalize(input.verification);
+    if (verified.kind === "refused")
+        return verified;
+    const observation = projectObservation(verified.observation);
+    const inbound = await input.localPersistence.recordObservation(observation);
+    const ref = await input.lifecycle.findDispatchRef(observation);
+    if (!ref) {
+        await input.localPersistence.markProcessed(observation.eventKey, { status: "ignored", refusal: { reason: "local_missing", phase: "apply", retryable: false } });
+        return { kind: "ignored", observation, replayed: inbound.replayed, trackingRefs: 0, trackingReadBacks: 0 };
+    }
+    const externalRef = observation.correlation.externalRef?.trim() || ref.externalRef?.trim();
+    if (!externalRef)
+        throw new TypeError("fulfillment_dispatch_acceptance_external_ref_missing");
+    await input.lifecycle.acknowledgeDispatchAcceptance(ref, observation);
+    const statusEvidence = await input.lifecycle.recordStatusEvidence(ref, observation);
+    let trackingRefs = 0;
+    let trackingReadBacks = 0;
+    const effectPort = {
+        ...input.lifecycle.effects,
+        async markProviderStockConsumed(request) {
+            try {
+                return await input.lifecycle.effects.markProviderStockConsumed(request);
+            }
+            catch (error) {
+                if (input.lifecycle.classifyFailure(error) === "stock_contention") {
+                    try {
+                        await input.lifecycle.annotateStockContention?.(observation.eventKey, ref.fulfillmentRef);
+                    }
+                    catch { /* Annotation is best-effort; preserve the original stock failure. */ }
+                }
+                throw error;
+            }
+        },
+    };
+    const localStatus = observation.fact.canonicalStatus;
+    const effects = {
+        port: effectPort, localStatus, ids: { orderId: ref.orderRef, fulfillmentOrderId: ref.fulfillmentRef }, observation,
+        trackingRefs: uniqueTrackingReferences(observation.trackingRefs).map(tracking => ({ trackingNumber: tracking.trackingNumber, trackingUrl: tracking.publicUrl, carrierKind: tracking.carrierRef, service: tracking.serviceRef })),
+        stockIdempotencyKey: input.lifecycle.keys.stock(ref.fulfillmentRef), handoffIdempotencyKey: input.lifecycle.keys.handoff(ref.fulfillmentRef),
+        trackingIdempotencyKey: number => input.lifecycle.keys.tracking(observation.eventKey, number),
+        issueAccountingInvoice: input.lifecycle.issueAccountingInvoice ? () => input.lifecycle.issueAccountingInvoice(ref.fulfillmentRef) : undefined,
+        onTrackingRecorded: result => { trackingRefs += result.replayed ? 0 : 1; trackingReadBacks += result.readBack ? 1 : 0; },
+    };
+    if (!observationStatusPolicy.handsOver(localStatus))
+        await applyFulfillmentObservationEffects({ ...effects, trackingRefs: [] }, observationStatusPolicy);
+    else {
+        try {
+            await applyFulfillmentObservationEffects(effects, observationStatusPolicy);
+        }
+        catch (error) {
+            if (input.lifecycle.classifyFailure(error) !== "state_conflict")
+                throw error;
+            await input.localPersistence.markProcessed(observation.eventKey, { status: "processed" });
+            return { kind: "superseded", observation, replayed: inbound.replayed || statusEvidence.replayed, trackingRefs, trackingReadBacks };
+        }
+    }
+    await input.localPersistence.markProcessed(observation.eventKey, { status: "processed" });
+    return { kind: "processed", observation, replayed: inbound.replayed || statusEvidence.replayed, trackingRefs, trackingReadBacks };
+}

package/dist/payments/adapterConformance.d.ts

@@ -0,0 +1,8 @@
+import type { PaymentAdapterConformanceEvidence, PaymentAdapterConformanceSubject, PaymentVerifyNormalizePort } from "./contracts/index.js";
+/** Runner-independent adapter proof. Verification fixtures are owned by each adapter. */
+export declare function runPaymentAdapterConformance(subjects: readonly (PaymentAdapterConformanceSubject & {
+    verification: readonly {
+        input: Parameters<PaymentVerifyNormalizePort["verifyAndNormalize"]>[0];
+        expected: Awaited<ReturnType<PaymentVerifyNormalizePort["verifyAndNormalize"]>>;
+    }[];
+})[]): Promise<PaymentAdapterConformanceEvidence>;

package/dist/payments/adapterConformance.js

@@ -0,0 +1,109 @@
+import { projectVerifiedEvidence } from "./verifiedEvidenceProjection.js";
+import { validatePaymentExecutionContractResult } from "@openlup/core/testing";
+/** Runner-independent adapter proof. Verification fixtures are owned by each adapter. */
+export async function runPaymentAdapterConformance(subjects) {
+    const observations = [];
+    const cases = [];
+    for (const subject of subjects) {
+        const { adapter, executionInput, readbackInput } = subject;
+        const provider = adapter.capabilities.providerKind;
+        requireFact(executionInput.money.currency.length > 0, "configured currency");
+        adapter.attemptPort.validateInput(executionInput);
+        const result = await adapter.attemptPort.execute(executionInput);
+        const { handoff, ...execution } = result;
+        const sensitiveValues = [executionInput.payer?.email, executionInput.payer?.name, executionInput.customerAuthorization,
+            handoff?.kind === "client-confirmed" ? handoff.payload : handoff?.url].filter((v) => v !== undefined && v.length > 0);
+        const sensitiveForms = sensitiveValues.flatMap(value => [value, JSON.stringify(value).slice(1, -1)]);
+        const payerForms = [executionInput.payer?.email, executionInput.payer?.name]
+            .filter((value) => Boolean(value?.length))
+            .flatMap(value => [value, JSON.stringify(value).slice(1, -1)]);
+        const input = {
+            idempotencyKey: executionInput.attemptRef, providerIdempotencyKey: executionInput.providerIdempotencyKey,
+            providerRequestFingerprint: executionInput.fingerprint, paymentIntentId: executionInput.intentRef,
+            amountMinor: executionInput.money.amountMinor, currency: executionInput.money.currency, mode: "one_time",
+        };
+        const validation = validatePaymentExecutionContractResult({ input, expectedProvider: provider, sensitiveValues: sensitiveForms,
+            result: { provider, providerAttemptId: result.dispatch.kind === "dispatched" ? result.dispatch.providerPaymentRef : null,
+                providerSessionId: null, attemptStatus: result.outcome.kind === "attempt" ? result.outcome.status : "processing",
+                nextActionKind: null, requestPayload: { providerIdempotencyKey: input.providerIdempotencyKey,
+                    providerRequestFingerprint: input.providerRequestFingerprint }, responsePayload: result.diagnostics },
+        });
+        requireFact(validation.ok, "execution diagnostics and taxonomy");
+        requireFact(!payerForms.some(value => JSON.stringify(result).includes(value)), "execution payer redaction");
+        if (adapter.capabilities.payerContext.requiresPayerBlock && !executionInput.payer) {
+            requireFact(result.dispatch.kind === "notDispatched" && result.dispatch.evidence.exact
+                && result.dispatch.evidence.phase === "before-dispatch", "missing required input exact notDispatched");
+        }
+        const returned = await adapter.readbackPort.readPayment(readbackInput);
+        const { handoff: readbackHandoff, ...readback } = "handoff" in returned ? returned : { ...returned, handoff: undefined };
+        requireFact(!sensitiveForms.some(value => JSON.stringify(readback).includes(value)), "readback secret redaction");
+        requireFact(sameIdentity(readback.identity, readbackInput.identity) && sameMoney(readback.expectedMoney, readbackInput.expectedMoney), "readback exact identity and money");
+        requireFact(adapter.capabilities.readback === "supported" ? returned.kind !== "unsupported" : returned.kind === "unsupported", "readback capability");
+        if ("observedMoney" in returned)
+            requireFact(sameMoney(returned.observedMoney, readbackInput.expectedMoney), "observed money");
+        if (adapter.capabilities.close === "supported") {
+            requireFact(typeof adapter.readbackPort.close === "function", "close method present");
+            const closed = await adapter.readbackPort.close(readbackInput);
+            requireFact(closed.kind !== "unsupported" && sameIdentity(closed.identity, readbackInput.identity)
+                && sameMoney(closed.expectedMoney, readbackInput.expectedMoney), "close exact identity and money");
+        }
+        else if (adapter.readbackPort.close) {
+            requireFact((await adapter.readbackPort.close(readbackInput)).kind === "unsupported", "close refuses");
+        }
+        let absence;
+        if (adapter.capabilities.exactAbsence === "supported")
+            requireFact(adapter.absencePort !== undefined, "absence port present");
+        if (adapter.absencePort) {
+            requireFact(subject.absenceInput !== undefined, "absence input present");
+            absence = await adapter.absencePort.proveAbsence(subject.absenceInput);
+            requireFact(sameIdentity(absence.identity, subject.absenceInput.identity)
+                && sameMoney(absence.expectedMoney, subject.absenceInput.expectedMoney), "absence exact identity and money");
+            requireFact(adapter.capabilities.exactAbsence === "supported" ? absence.kind !== "unsupported" : absence.kind === "unsupported", "absence capability");
+            if (absence.kind === "absent")
+                requireFact(absence.evidence.exact && absence.evidence.complete
+                    && absence.evidence.lookupReference.trim().length > 0, "complete absence evidence");
+        }
+        const fingerprints = new Map();
+        const moneyEvents = [];
+        for (const fixture of subject.verification) {
+            const verified = await adapter.verifyPort.verifyAndNormalize(fixture.input);
+            requireFact(JSON.stringify(verified) === JSON.stringify(fixture.expected), "verified fixture");
+            if (verified.kind !== "refusal") {
+                requireFact(verified.kind !== "money" || (verified.money !== null
+                    && Number.isSafeInteger(verified.money.amountMinor) && verified.money.amountMinor > 0
+                    && verified.money.currency.trim().length > 0)
+                    || (verified.outcome !== "succeeded" && verified.outcome !== "refunded" && verified.outcome !== "disputed"), "settling outcome requires positive money");
+                requireFact(!sensitiveForms.some(value => JSON.stringify({ payload: projectVerifiedEvidence(verified, fixture.input, "require-evidence").rawPayload, diagnostics: result.diagnostics }).includes(value)), "audit payload secret redaction");
+                const outcome = verified.kind + ":" + verified.outcome;
+                const previous = fingerprints.get(verified.providerEventId);
+                if (previous)
+                    requireFact(previous.outcome === outcome && previous.fingerprint === verified.fingerprint, "replay identity fingerprint");
+                if (verified.kind === "money") {
+                    for (const event of moneyEvents) {
+                        if (event.reference === verified.providerPaymentRef && event.outcome !== outcome) {
+                            requireFact(event.eventId !== verified.providerEventId && event.fingerprint !== verified.fingerprint, "changing outcome identity");
+                        }
+                    }
+                    moneyEvents.push({ reference: verified.providerPaymentRef, outcome, eventId: verified.providerEventId, fingerprint: verified.fingerprint });
+                }
+                fingerprints.set(verified.providerEventId, { fingerprint: verified.fingerprint, outcome });
+            }
+        }
+        // Transient handoffs are deliberately excluded from the returned evidence.
+        void readbackHandoff;
+        observations.push({ subjectId: subject.subjectId, execution, readback, ...(absence ? { absence } : {}) });
+        cases.push({ subjectIds: [subject.subjectId], name: "execution, verification, capability and exact readback", passed: true });
+    }
+    return { subjects: observations, cases };
+}
+function requireFact(value, label) {
+    if (!value)
+        throw new Error(`payment_adapter_conformance:${label}`);
+}
+function sameMoney(left, right) {
+    return left.amountMinor === right.amountMinor && left.currency === right.currency;
+}
+function sameIdentity(left, right) {
+    return left.provider === right.provider && left.providerPaymentRef === right.providerPaymentRef
+        && left.intentRef === right.intentRef && left.attemptRef === right.attemptRef;
+}

package/dist/payments/bindings.d.ts

@@ -0,0 +1,3 @@
+import type { PaymentServices, PaymentServicesOptions } from "./contracts/repair.js";
+/** One host-owned scope per runtime unit; no driver or environment discovery. */
+export declare function createPaymentServices(options: PaymentServicesOptions): PaymentServices | null;

package/dist/payments/bindings.js

@@ -0,0 +1,17 @@
+/** One host-owned scope per runtime unit; no driver or environment discovery. */
+export function createPaymentServices(options) {
+    if (options.schema?.truth !== "supported" || !options.openTruth)
+        return null;
+    const openTruth = options.openTruth;
+    return {
+        async run(work) {
+            const scope = await openTruth();
+            try {
+                return await work(scope.port);
+            }
+            finally {
+                await scope.close();
+            }
+        },
+    };
+}

package/dist/payments/checkoutActivePaymentActionResolver.d.ts

@@ -0,0 +1,7 @@
+import type { CheckoutActivePaymentActionResolver, CheckoutActionReadProvider } from "./contracts/repair.js";
+import type { PaymentVerifyReadPort } from "./contracts/reconciliation.js";
+export declare function createCheckoutActivePaymentActionResolver(deps: {
+    readPort: PaymentVerifyReadPort;
+    providers: Partial<Record<string, CheckoutActionReadProvider>>;
+    railHandoffKinds(rail: string): readonly ("redirect" | "client-confirmed")[];
+}): CheckoutActivePaymentActionResolver;

package/dist/payments/checkoutActivePaymentActionResolver.js

@@ -0,0 +1,77 @@
+import { toClaimedAttemptShape } from "./paymentVerifyNowService.js";
+const LIVE_INTENT_STATUSES = new Set(["requires_action", "processing"]);
+const LIVE_ATTEMPT_STATUSES = new Set(["sent_to_provider", "requires_action", "processing"]);
+export function createCheckoutActivePaymentActionResolver(deps) {
+    return {
+        async readActiveAction(authority) {
+            try {
+                const initial = await deps.readPort.readVerifiableAttempt({
+                    orderId: authority.orderId,
+                    paymentIntentId: authority.paymentIntentId,
+                });
+                if (!matchesAuthority(initial, authority) || !isLive(initial))
+                    return null;
+                const provider = deps.providers[authority.executionRail];
+                const providerPaymentId = provider?.resolvePaymentReference(initial) ?? null;
+                if (!provider || !providerPaymentId)
+                    return null;
+                const attempt = toClaimedAttemptShape(initial, providerPaymentId);
+                const reading = await provider.readRecoveryPayment({
+                    providerPaymentId,
+                    attempt,
+                    purpose: "active_checkout",
+                });
+                if (!reading.clientAction
+                    || !actionMatchesRail(reading.clientAction, authority.executionRail, deps.railHandoffKinds)
+                    || reading.manualReviewRequired
+                    || !reading.identityMatches
+                    || !reading.configuredMoneyMatches
+                    || reading.status.status !== "pending")
+                    return null;
+                const current = await deps.readPort.readVerifiableAttempt({
+                    orderId: authority.orderId,
+                    paymentIntentId: authority.paymentIntentId,
+                });
+                if (!sameCanonicalAttempt(initial, current) || !isLive(current))
+                    return null;
+                return reading.clientAction;
+            }
+            catch {
+                return null;
+            }
+        },
+    };
+}
+function matchesAuthority(snapshot, authority) {
+    return Boolean(snapshot)
+        && snapshot?.orderId === authority.orderId
+        && snapshot.orderClientId === authority.clientId
+        && snapshot.paymentIntentId === authority.paymentIntentId
+        && snapshot.paymentAttemptId === authority.paymentAttemptId
+        && snapshot.provider === authority.executionRail;
+}
+function isLive(snapshot) {
+    return Boolean(snapshot)
+        && LIVE_INTENT_STATUSES.has(snapshot?.intentStatus ?? "")
+        && LIVE_ATTEMPT_STATUSES.has(snapshot?.attemptStatus ?? "");
+}
+function actionMatchesRail(action, rail, railHandoffKinds) {
+    return action.provider === rail && railHandoffKinds(rail).includes(action.kind);
+}
+function sameCanonicalAttempt(before, after) {
+    return Boolean(after)
+        && after?.orderId === before.orderId
+        && after.orderClientId === before.orderClientId
+        && after.paymentIntentId === before.paymentIntentId
+        && after.paymentAttemptId === before.paymentAttemptId
+        && after.paymentId === before.paymentId
+        && after.provider === before.provider
+        && after.providerAttemptId === before.providerAttemptId
+        && after.providerSessionId === before.providerSessionId
+        && after.intentProviderPaymentId === before.intentProviderPaymentId
+        && after.intentStatus === before.intentStatus
+        && after.attemptStatus === before.attemptStatus
+        && after.amountMinor === before.amountMinor
+        && after.currency.toUpperCase() === before.currency.toUpperCase()
+        && after.localUpdatedAt === before.localUpdatedAt;
+}

package/dist/payments/checkoutRecoveryPaymentResolver.d.ts

@@ -0,0 +1,8 @@
+import type { CheckoutRecoveryPaymentResolver, PaymentProviderRecoveryProvider } from "./contracts/repair.js";
+import type { PaymentVerifyReadPort, PaymentProviderReconciliationPort } from "./contracts/reconciliation.js";
+export declare function createCheckoutRecoveryPaymentResolver(deps: {
+    readPort: PaymentVerifyReadPort;
+    applyPort: Pick<PaymentProviderReconciliationPort, "applyTerminalResult">;
+    providers: Partial<Record<string, PaymentProviderRecoveryProvider>>;
+    now?: () => Date;
+}): CheckoutRecoveryPaymentResolver;

package/dist/payments/checkoutRecoveryPaymentResolver.js

@@ -0,0 +1,87 @@
+import { terminalAmountMismatch } from "./paymentProviderReconciliationEvidence.js";
+import { toClaimedAttemptShape, verifyPaymentAttemptNow } from "./paymentVerifyNowService.js";
+const LIVE_ATTEMPT_STATUSES = new Set(["sent_to_provider", "requires_action", "processing", "created"]);
+export function createCheckoutRecoveryPaymentResolver(deps) {
+    const now = deps.now ?? (() => new Date());
+    return {
+        async resolve(input) {
+            if (!input.paymentIntentId)
+                return { kind: "retry_new" };
+            const snapshot = await deps.readPort.readVerifiableAttempt({
+                orderId: input.orderId,
+                paymentIntentId: input.paymentIntentId,
+            });
+            if (!snapshot) {
+                return input.intentStatus === "created" || input.intentStatus === "failed"
+                    ? { kind: "retry_new" }
+                    : { kind: "awaiting_provider" };
+            }
+            return resolveSnapshot(snapshot, deps, now);
+        },
+    };
+}
+async function resolveSnapshot(snapshot, deps, now) {
+    if (snapshot.attemptStatus === "succeeded" || snapshot.intentStatus === "succeeded") {
+        return { kind: "paid" };
+    }
+    if (snapshot.attemptStatus === "failed" || snapshot.intentStatus === "failed") {
+        return { kind: "retry_new" };
+    }
+    if (!LIVE_ATTEMPT_STATUSES.has(snapshot.attemptStatus)) {
+        return { kind: "awaiting_provider" };
+    }
+    const provider = deps.providers[snapshot.provider];
+    const providerPaymentId = provider?.resolvePaymentReference(snapshot) ?? null;
+    if (!provider || !providerPaymentId)
+        return { kind: "awaiting_provider" };
+    const attempt = toClaimedAttemptShape(snapshot, providerPaymentId);
+    try {
+        // Every caller of this resolver is a buyer holding a recovery link open, so
+        // an intent still waiting for its first payment method is one they can be
+        // handed back — not one to close under them and replace.
+        const recovery = await provider.readRecoveryPayment({
+            providerPaymentId,
+            attempt,
+            purpose: "active_checkout",
+        });
+        if (recovery.manualReviewRequired
+            || !recovery.identityMatches
+            || !recovery.configuredMoneyMatches) {
+            return { kind: "manual_review" };
+        }
+        if (recovery.clientAction) {
+            return { kind: "resume_existing", clientAction: recovery.clientAction };
+        }
+        if (recovery.status.status === "pending" || recovery.status.status === "unknown") {
+            return { kind: "awaiting_provider" };
+        }
+        if (terminalAmountMismatch(attempt, recovery.status)) {
+            return { kind: "manual_review" };
+        }
+        const verified = await verifyPaymentAttemptNow({
+            snapshot,
+            applyPort: deps.applyPort,
+            providers: deps.providers,
+            providerPaymentId,
+            providerStatus: recovery.status,
+            now,
+        });
+        if (verified.status !== "succeeded" && verified.status !== "failed") {
+            return { kind: "awaiting_provider" };
+        }
+        const current = await deps.readPort.readVerifiableAttempt({
+            orderId: snapshot.orderId,
+            paymentIntentId: snapshot.paymentIntentId,
+        });
+        if (current?.attemptStatus === "succeeded" || current?.intentStatus === "succeeded") {
+            return { kind: "paid" };
+        }
+        if (current?.attemptStatus === "failed" || current?.intentStatus === "failed") {
+            return { kind: "retry_new" };
+        }
+        return verified.status === "succeeded" ? { kind: "paid" } : { kind: "retry_new" };
+    }
+    catch {
+        return { kind: "awaiting_provider" };
+    }
+}

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

@@ -0,0 +1,113 @@
+import type { PaymentExecutionAttemptStatus, PaymentFailureClass, PaymentFailureHint, PaymentProviderCapabilityDescriptor, PaymentRetryAdviceCode, StoredMandateSnapshot } from "@openlup/core/payment";
+import type { PaymentAbsencePort, PaymentReadbackPort, PaymentVerifyNormalizePort } from "./evidence.js";
+declare const transientSecret: unique symbol;
+/**
+ * One-time customer authorization or opaque client handoff, held only in memory.
+ * Never persist, log, fingerprint, or include in request/response diagnostics.
+ * The host brands a value only at the transient client/server input boundary.
+ */
+export type TransientSecret = string & {
+    readonly [transientSecret]: true;
+};
+/** Hosted navigation or client confirmation; opaque payloads are transient only. */
+export type PaymentMethodHandoff = {
+    kind: "redirect";
+    url: string;
+} | {
+    kind: "client-confirmed";
+    payload: TransientSecret;
+};
+/** Only core neutral taxonomy crosses the adapter boundary; no provider prose. */
+export interface PaymentRefusalEnvelope {
+    code: PaymentFailureClass;
+    hints: readonly PaymentFailureHint[];
+    adviceCode?: PaymentRetryAdviceCode;
+}
+/**
+ * A non-terminal attempt or synchronous decline; terminal money is evidence-owned.
+ * Diagnostics must exclude transient secrets, handoff payloads, raw bodies and
+ * provider prose. Persist only explicitly redacted request/response diagnostics.
+ */
+export interface PaymentExecutionEnvelope {
+    outcome: {
+        kind: "attempt";
+        status: PaymentExecutionAttemptStatus;
+    } | {
+        kind: "decline";
+        refusal: PaymentRefusalEnvelope;
+    };
+    dispatch: {
+        kind: "dispatched";
+        providerPaymentRef: string;
+    } | {
+        kind: "notDispatched";
+        evidence: {
+            exact: true;
+            phase: "before-dispatch";
+            reason: PaymentRefusalEnvelope;
+        };
+    } | {
+        kind: "unknown";
+    };
+    handoff?: PaymentMethodHandoff;
+    diagnostics: Readonly<Record<string, string | number | boolean | null>>;
+}
+/** Host identity/key/fingerprint and configured integer-minor money pass verbatim.
+ * Missing adapter-required input must refuse before dispatch with exact
+ * notDispatched evidence (phase before-dispatch), never unknown or dispatched.
+ */
+export interface PaymentAttemptPort {
+    validateInput(input: {
+        attemptRef: string;
+        intentRef: string;
+        fingerprint: string;
+        providerIdempotencyKey: string;
+        money: {
+            amountMinor: number;
+            currency: string;
+        };
+        mode: "live" | "test";
+        purpose: "initial" | "renewal-unattended" | "recovery";
+        methodSelection?: {
+            family: "card" | "wallet" | "bank-redirect" | "one-time-code";
+            channelRef?: string;
+        };
+        /** Transient dispatch input only; never persist, audit, log or diagnose. */
+        payer?: {
+            email: string;
+            name?: string;
+        };
+        storedMethod?: {
+            reference: string;
+            mandate: StoredMandateSnapshot;
+        };
+        /** Client-entered, server-submitted authorization; never persisted or echoed. */
+        customerAuthorization?: TransientSecret;
+    }): void;
+    execute(input: Parameters<PaymentAttemptPort["validateInput"]>[0]): Promise<PaymentExecutionEnvelope>;
+}
+/** Platform overlay; the shared core descriptor remains unchanged. */
+export interface PaymentAdapterCapabilities extends Omit<PaymentProviderCapabilityDescriptor, "captureFlows"> {
+    captureFlows: readonly {
+        kind: string;
+        handoff: PaymentMethodHandoff["kind"] | "customer-authorization";
+        methodFamilies: readonly ("card" | "wallet" | "bank-redirect" | "one-time-code")[];
+    }[];
+    supportedCurrencies: readonly string[];
+    unattended: "supported" | "unsupported";
+    readback: "supported" | "unsupported";
+    close: "supported" | "unsupported";
+    exactAbsence: "supported" | "unsupported";
+    refundObservation: "supported" | "unsupported";
+    refundCreate: "unsupported";
+    authorizationCaptureSplit: "unsupported";
+}
+/** The neutral bundle an adapter factory returns; optional ports match declared capabilities. */
+export interface PaymentAdapter {
+    capabilities: PaymentAdapterCapabilities;
+    attemptPort: PaymentAttemptPort;
+    verifyPort: PaymentVerifyNormalizePort;
+    readbackPort: PaymentReadbackPort;
+    absencePort?: PaymentAbsencePort;
+}
+export {};

package/dist/payments/contracts/adapter.js

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

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

@@ -0,0 +1,155 @@
+import type { PaymentAdapter, PaymentAttemptPort, PaymentExecutionEnvelope } from "./adapter.js";
+import type { PaymentAbsenceEnvelope, PaymentAbsencePort, PaymentReadbackEnvelope, PaymentReadbackPort } from "./evidence.js";
+/** A fixture binds its own identity, adapter ports and inputs; scenarios accept multiple subjects. */
+export interface PaymentAdapterConformanceSubject {
+    subjectId: string;
+    adapter: PaymentAdapter;
+    executionInput: Parameters<PaymentAttemptPort["execute"]>[0];
+    readbackInput: Parameters<PaymentReadbackPort["readPayment"]>[0];
+    /** Required when the adapter supplies an absence port. */
+    absenceInput?: Parameters<PaymentAbsencePort["proveAbsence"]>[0];
+}
+/** Runner-independent observations; never include transient input or raw diagnostics. */
+export interface PaymentAdapterConformanceEvidence {
+    subjects: readonly {
+        subjectId: string;
+        execution: Omit<PaymentExecutionEnvelope, "handoff">;
+        readback: PaymentReadbackEnvelope & {
+            handoff?: never;
+        };
+        absence?: PaymentAbsenceEnvelope;
+    }[];
+    cases: readonly {
+        subjectIds: readonly string[];
+        name: string;
+        passed: boolean;
+    }[];
+}
+import type { PaymentExecutionBaseInput, PaymentExecutionContractResult } from "@openlup/core/testing";
+export type ExecutionCapability = {
+    readonly name: string;
+    readonly durabilityClaim: false;
+};
+export type SimulatorResult = PaymentExecutionContractResult & {
+    providerDecline?: {
+        code?: string;
+        mandateUnsupported?: boolean;
+    } | null;
+};
+export type ExecutionSubject<TInput extends PaymentExecutionBaseInput, TResult extends SimulatorResult> = {
+    readonly execute: (request: TInput) => Promise<TResult>;
+};
+/**
+ * The expected provider identity is a property of the adapter under proof, not of
+ * this contract. The collector that constructs the subject owns that literal, so a
+ * second runtime bundle proves the same behaviour under its own provider identity
+ * and this contract names no provider at all.
+ */
+export type ExecutionProviderIdentity = {
+    readonly expectedProvider: string;
+};
+export type ExecutionEvidence = {
+    readonly capability: ExecutionCapability;
+    readonly executions: number;
+    readonly providerCalls: number;
+    readonly capturedEffects: number;
+    readonly permanentRefusals: number;
+};
+export type AggregateKey = "outOfOrder" | "lateSuccess";
+export type ResultStatus = "succeeded" | "failed";
+export type DurableEventCounts = {
+    clients: number;
+    orders: number;
+    payments: number;
+    intents: number;
+    attempts: number;
+    events: number;
+    transitions: number;
+    idempotencyKeys: number;
+    outboxEvents: number;
+};
+export type DurableEventAggregate = {
+    orderId: string;
+    paymentId: string;
+    paymentIntentId: string;
+    paymentAttemptId: string;
+    orderStatus: string;
+    paymentStatus: string;
+    intentStatus: string;
+    attemptStatus: string;
+};
+/** Fixture cardinality that stays constant for the whole run. */
+export type DurableEventFixtureCardinality = Pick<DurableEventCounts, "clients" | "orders" | "payments" | "intents" | "attempts">;
+/** Durable writes the adapter emits per step. */
+export type DurableEventWriteCardinality = Pick<DurableEventCounts, "events" | "transitions" | "idempotencyKeys" | "outboxEvents">;
+/**
+ * Exact write cardinality is adapter-owned, not part of the portable contract:
+ * how many transitions, idempotency keys, and outbox rows one payment event
+ * produces is a property of the writer and outbox fan-out under proof, and a
+ * second runtime bundle emits its own. The behavioural assertions below (no
+ * second canonical event, no regression after a stale failure, convergence on
+ * late success) are the portable part; the collector that owns the adapter
+ * injects its own numbers so they are still asserted at the exact same step.
+ */
+export type DurableEventCardinalityExpectations = {
+    readonly fixture: DurableEventFixtureCardinality;
+    readonly baseline: DurableEventWriteCardinality;
+    readonly afterOutOfOrderSuccess: DurableEventWriteCardinality;
+    readonly afterOutOfOrderFailure: DurableEventWriteCardinality;
+    readonly afterDuplicate: DurableEventWriteCardinality;
+    readonly afterLateFailure: DurableEventWriteCardinality;
+    readonly final: DurableEventWriteCardinality;
+};
+export type DurableEventSnapshot = {
+    counts: DurableEventCounts;
+    aggregates: Record<AggregateKey, DurableEventAggregate>;
+    events: Array<{
+        id: string;
+        eventKey: string;
+        paymentIntentId: string;
+        paymentAttemptId: string;
+        processingStatus: string;
+    }>;
+};
+export type EventReceipt = {
+    paymentEventId: string;
+    replayed: boolean;
+};
+export type DurableEventCapability = {
+    readonly name: string;
+    readonly durabilityClaim: true;
+    assertSafe(): void;
+    reset(): Promise<{
+        residualRows: number;
+    }>;
+    seed(): Promise<void>;
+    snapshot(): Promise<DurableEventSnapshot>;
+    ingest(input: {
+        aggregate: AggregateKey;
+        eventKey: string;
+        resultStatus: ResultStatus;
+        occurredAt: string;
+    }): Promise<EventReceipt>;
+    apply(input: {
+        aggregate: AggregateKey;
+        paymentEventId: string;
+        eventKey: string;
+        resultStatus: ResultStatus;
+        occurredAt: string;
+    }): Promise<{
+        replayed: boolean;
+    }>;
+};
+export type DurableEventEvidence = {
+    capability: {
+        name: string;
+        durabilityClaim: true;
+    };
+    baseline: DurableEventSnapshot;
+    afterOutOfOrderSuccess: DurableEventSnapshot;
+    afterOutOfOrderFailure: DurableEventSnapshot;
+    afterDuplicate: DurableEventSnapshot;
+    afterLateFailure: DurableEventSnapshot;
+    final: DurableEventSnapshot;
+    cleanupResidualRows: 0;
+};