@openlup/platform 0.20.0 → 0.22.0

package/src/payments/checkoutActivePaymentActionResolver.ts

@@ -0,0 +1,97 @@
+import type { ActivePaymentActionAuthority, CheckoutActivePaymentActionResolver, CheckoutActionReadProvider, PaymentRecoveryAction } from "./contracts/repair.js";
+import type { PaymentVerifyReadPort, VerifiableAttemptSnapshot } from "./contracts/reconciliation.js";
+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: {
+  readPort: PaymentVerifyReadPort;
+  providers: Partial<Record<string, CheckoutActionReadProvider>>;
+  railHandoffKinds(rail: string): readonly ("redirect" | "client-confirmed")[];
+}): CheckoutActivePaymentActionResolver {
+  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: VerifiableAttemptSnapshot | null,
+  authority: ActivePaymentActionAuthority,
+): snapshot is VerifiableAttemptSnapshot {
+  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: VerifiableAttemptSnapshot | null): snapshot is VerifiableAttemptSnapshot {
+  return Boolean(snapshot)
+    && LIVE_INTENT_STATUSES.has(snapshot?.intentStatus ?? "")
+    && LIVE_ATTEMPT_STATUSES.has(snapshot?.attemptStatus ?? "");
+}
+
+function actionMatchesRail(
+  action: PaymentRecoveryAction,
+  rail: ActivePaymentActionAuthority["executionRail"],
+  railHandoffKinds: (rail: string) => readonly ("redirect" | "client-confirmed")[],
+): boolean {
+  return action.provider === rail && railHandoffKinds(rail).includes(action.kind);
+}
+
+function sameCanonicalAttempt(
+  before: VerifiableAttemptSnapshot,
+  after: VerifiableAttemptSnapshot | null,
+): after is VerifiableAttemptSnapshot {
+  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/src/payments/checkoutRecoveryPaymentResolver.ts

@@ -0,0 +1,108 @@
+import type { CheckoutRecoveryPaymentResolution, CheckoutRecoveryPaymentResolver, PaymentProviderRecoveryProvider } from "./contracts/repair.js";
+import type { PaymentVerifyReadPort, VerifiableAttemptSnapshot, PaymentProviderReconciliationPort } from "./contracts/reconciliation.js";
+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: {
+  readPort: PaymentVerifyReadPort;
+  applyPort: Pick<PaymentProviderReconciliationPort, "applyTerminalResult">;
+  providers: Partial<Record<string, PaymentProviderRecoveryProvider>>;
+  now?: () => Date;
+}): CheckoutRecoveryPaymentResolver {
+  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: VerifiableAttemptSnapshot,
+  deps: {
+    readPort: PaymentVerifyReadPort;
+    applyPort: Pick<PaymentProviderReconciliationPort, "applyTerminalResult">;
+    providers: Partial<Record<string, PaymentProviderRecoveryProvider>>;
+  },
+  now: () => Date,
+): Promise<CheckoutRecoveryPaymentResolution> {
+  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/src/payments/contracts/adapter.ts

@@ -0,0 +1,96 @@
+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;
+}

package/src/payments/contracts/conformance.ts

@@ -0,0 +1,171 @@
+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;
+};

package/src/payments/contracts/evidence.ts

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

package/src/payments/contracts/index.ts

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