@openlup/platform 0.19.0 → 0.21.0

package/src/payments/contracts/truth.ts

@@ -0,0 +1,108 @@
+
+
+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/src/payments/eventConformanceRunner.ts

@@ -0,0 +1,149 @@
+import type { PaymentExecutionBaseInput } from "@openlup/core/testing";
+import type { ExecutionCapability, SimulatorResult, ExecutionSubject, ExecutionProviderIdentity, ExecutionEvidence, AggregateKey, ResultStatus, DurableEventCounts, DurableEventAggregate, DurableEventFixtureCardinality, DurableEventWriteCardinality, DurableEventCardinalityExpectations, DurableEventSnapshot, EventReceipt, DurableEventCapability, DurableEventEvidence } from "./contracts/conformance.js";
+import {
+  validatePaymentExecutionContractResult,
+} from "@openlup/core/testing";
+
+/** Framework-free execution proof; durable event evidence is a separate capability. */
+export async 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> {
+  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: DurableEventCapability,
+  expected: DurableEventCardinalityExpectations,
+): Promise<DurableEventEvidence> {
+  subject.assertSafe();
+  let evidence: Omit<DurableEventEvidence, "cleanupResidualRows"> | undefined;
+  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: DurableEventCapability, aggregate: AggregateKey, eventKey: string, resultStatus: ResultStatus, occurredAt: string) {
+  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: DurableEventCounts, fixture: DurableEventFixtureCardinality, writes: DurableEventWriteCardinality): void {
+  for (const [key, value] of Object.entries({ ...fixture, ...writes })) {
+    assertEqual(counts[key as keyof DurableEventCounts], value, `${key} count`);
+  }
+}
+
+function assertEvent(snapshot: DurableEventSnapshot, receipt: { ingest: EventReceipt }, eventKey: string, aggregate: AggregateKey, expectedState: string): void {
+  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: DurableEventAggregate, after: DurableEventAggregate): void {
+  for (const key of ["orderId", "paymentId", "paymentIntentId", "paymentAttemptId"] as const) {
+    assertEqual(after[key], before[key], `stable ${key}`);
+  }
+}
+
+function assertSucceeded(aggregate: DurableEventAggregate): void {
+  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: unknown, expected: unknown, label: string): void {
+  if (actual !== expected) throw new Error(`${label}: expected ${String(expected)}, received ${String(actual)}`);
+}

package/src/payments/index.ts

@@ -0,0 +1,21 @@
+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/src/payments/paymentAttemptSilenceWindow.ts

@@ -0,0 +1,26 @@
+import type {
+  ClaimedPaymentAttempt,
+  SilenceWindowLookup,
+} from "./contracts/reconciliation.js";
+
+/**
+ * Whether this rail has answered non-terminally for longer than it declares
+ * normal. The window comes from the rail's published capability - never a
+ * provider identity, never a global constant, because a pushed-event rail and a
+ * polled rail have genuinely different normal silences and a self-hoster
+ * declares their own. Absent or unusable means never overdue: stay quiet rather
+ * than accuse a healthy rail.
+ */
+export function silenceIsOverdue(
+  capabilities: SilenceWindowLookup | undefined,
+  attempt: ClaimedPaymentAttempt,
+  now: string,
+): boolean {
+  const minutes = capabilities?.get(attempt.provider)?.terminalOutcomeReporting
+    ?.silenceBecomesSuspectAfterMinutes;
+  if (typeof minutes !== "number" || !Number.isFinite(minutes) || minutes <= 0) return false;
+  const since = Date.parse(attempt.localUpdatedAt);
+  const at = Date.parse(now);
+  if (!Number.isFinite(since) || !Number.isFinite(at)) return false;
+  return at - since >= minutes * 60_000;
+}

package/src/payments/paymentMethodLifecycle.ts

@@ -0,0 +1,50 @@
+import {
+  isPaymentMethodLifecycleEventKind,
+  type PaymentMethodLifecycleEvent,
+  type PaymentMethodReplacementFacts,
+} from "@openlup/core/payment";
+import type { NormalizedProviderPaymentWebhook } from "./verifiedIngress.js";
+
+export interface ProviderWebhookWithMethodLifecycle extends NormalizedProviderPaymentWebhook {
+  methodLifecycle?: PaymentMethodLifecycleEvent | null;
+}
+
+export const METHOD_SCHEME_SNAPSHOT_KEY = "methodScheme";
+export const METHOD_LAST_DIGITS_SNAPSHOT_KEY = "methodLastDigits";
+export const METHOD_EXPIRES_AT_SNAPSHOT_KEY = "methodExpiresAt";
+
+export function methodFactSnapshotKeys(
+  facts: PaymentMethodReplacementFacts | null | undefined,
+): Record<string, unknown> {
+  if (!facts) return {};
+  return {
+    ...(facts.schemeLabel ? { [METHOD_SCHEME_SNAPSHOT_KEY]: facts.schemeLabel } : {}),
+    ...(facts.lastDigits ? { [METHOD_LAST_DIGITS_SNAPSHOT_KEY]: facts.lastDigits } : {}),
+    ...(facts.expiresAt ? { [METHOD_EXPIRES_AT_SNAPSHOT_KEY]: facts.expiresAt } : {}),
+  };
+}
+
+export function expiryForMethodRefWrite(
+  consentSnapshot: Record<string, unknown> | undefined,
+  occurredAt: string,
+  active: boolean,
+): string | null {
+  const raw = consentSnapshot?.[METHOD_EXPIRES_AT_SNAPSHOT_KEY];
+  if (typeof raw !== "string" || !raw.trim()) return null;
+  const expiry = Date.parse(raw);
+  if (!Number.isFinite(expiry)) return null;
+  if (!active) return raw;
+  const reference = Date.parse(occurredAt);
+  return Number.isFinite(reference) && expiry <= reference ? null : raw;
+}
+
+export function readMethodLifecycleEvent(
+  event: NormalizedProviderPaymentWebhook,
+): PaymentMethodLifecycleEvent | null {
+  const candidate = (event as ProviderWebhookWithMethodLifecycle).methodLifecycle;
+  if (!candidate || typeof candidate !== "object") return null;
+  if (!isPaymentMethodLifecycleEventKind(candidate.kind)) return null;
+  if (!candidate.providerKind?.trim() || !candidate.providerMethodRef?.trim()) return null;
+  if (!candidate.providerEventId?.trim() || !candidate.occurredAt?.trim()) return null;
+  return candidate;
+}

package/src/payments/paymentProviderReconciliationAbsenceReopen.ts

@@ -0,0 +1,130 @@
+import {
+  absenceProbeEvidenceKey,
+  absenceReopenKey,
+  safeMessage,
+} from "./paymentProviderReconciliationEvidence.js";
+import type {
+  ClaimedPaymentAttempt,
+  PaymentProviderReconciliationProvider,
+  PaymentProviderReconciliationWorkerInput,
+} from "./contracts/reconciliation.js";
+
+// Mirrors the RPC's v_min_stranded_age guard (migration 20260711153000). The
+// worker pre-checks so an under-age attempt is a silent skip for this pass
+// instead of a guaranteed `prepared_attempt_absence_reopen_too_fresh` reject.
+const MIN_PREPARED_ABSENCE_REOPEN_AGE_SECONDS = 30 * 60;
+
+/** Reopen only after genuine provider-side absence proof. A missing local
+ * acknowledgement cannot exclude a charge before reference persistence failed;
+ * minting a fresh idempotency key in that crash window could double-charge.
+ * Providers without an exact absence probe require operator review.
+ */
+export async function tryReopenPreparedAbsence(
+  input: PaymentProviderReconciliationWorkerInput,
+  attempt: ClaimedPaymentAttempt,
+  now: string,
+): Promise<boolean> {
+  // Reopen schedules another subscription-cycle charge. One-time prepared
+  // attempts remain operator-manual so this path can never create a blind
+  // second provider call for them.
+  if (attempt.orderMode !== "subscription_cycle" || !attempt.subscriptionCycleId) return false;
+  const subscriptionCycleId = attempt.subscriptionCycleId;
+
+  const provider: PaymentProviderReconciliationProvider | undefined = input.providers[attempt.provider];
+
+  // Without an exact absence probe, stranded attempts stay operator-manual.
+  // Guessing absence could schedule a second charge.
+  if (!provider?.findPaymentByLocalIntent) return false;
+
+  const ageMs = Date.parse(now) - Date.parse(attempt.localUpdatedAt);
+  if (!Number.isFinite(ageMs) || ageMs < MIN_PREPARED_ABSENCE_REOPEN_AGE_SECONDS * 1000) {
+    // Under the RPC's stranded-age guard — the next configured reconciliation pass catches it.
+    return false;
+  }
+
+  let probe: "found" | "absent";
+  try {
+    probe = await provider.findPaymentByLocalIntent({ attempt });
+  } catch (error) {
+    await recordProbeEvidence(input, attempt, now, "absence_probe_failed", {
+      probeError: safeMessage(error),
+      operatorReviewRequired: true,
+    });
+    return false;
+  }
+
+  if (probe === "found") {
+    // Crash-after-charge window: the provider HAS a payment for this intent
+    // but our attempt never recorded it. Reopening would double-charge —
+    // leave it for operator ref-repair; the stale-attempt readback path takes
+    // over once refs are restored.
+    await recordProbeEvidence(input, attempt, now, "provider_payment_found_after_prepare", {
+      providerAbsenceConfirmed: false,
+      operatorReviewRequired: true,
+      reopenBlocked: "provider_payment_exists",
+    });
+    return false;
+  }
+
+  try {
+    await input.port.reopenPreparedAttemptAfterAbsence({
+      idempotencyKey: absenceReopenKey(attempt),
+      paymentAttemptId: attempt.paymentAttemptId,
+      expectedPaymentIntentId: attempt.paymentIntentId,
+      expectedSubscriptionCycleId: subscriptionCycleId,
+      operatorRef: "payment-provider-reconciliation@auto",
+      absenceCheckedAt: now,
+      nextRetryAt: now,
+      absenceEvidence: {
+        providerAbsenceConfirmed: true,
+        source: "payment-provider-reconciliation.auto-reopen.v0",
+        basis: `${attempt.provider}_intent_correlated_search_absent`,
+        probedAt: now,
+      },
+    });
+    // The RPC records its own 'prepared_attempt_provider_absent' corrected
+    // evidence, cancels the attempt, and requeues the cycle — nothing more to
+    // write here.
+    return true;
+  } catch (error) {
+    const message = safeMessage(error);
+    // The RPC's 22023 precondition rejects (too_fresh, provider_event_exists,
+    // terminal reconciliation, state drift since claim, ...) are expected
+    // races, not run failures — the attempt stays operator-visible either way.
+    await recordProbeEvidence(
+      input,
+      attempt,
+      now,
+      message.includes("prepared_attempt_absence_reopen_")
+        ? "absence_reopen_precondition_reject"
+        : "absence_reopen_failed",
+      { reopenError: message, operatorReviewRequired: true },
+    );
+    return false;
+  }
+}
+
+function recordProbeEvidence(
+  input: PaymentProviderReconciliationWorkerInput,
+  attempt: ClaimedPaymentAttempt,
+  now: string,
+  providerStatus: string,
+  extra: Record<string, unknown>,
+): Promise<{ replayed: boolean }> {
+  return input.port.recordEvidence({
+    idempotencyKey: absenceProbeEvidenceKey(attempt, now),
+    provider: attempt.provider,
+    providerPaymentId: null,
+    paymentIntentId: attempt.paymentIntentId,
+    paymentAttemptId: attempt.paymentAttemptId,
+    localStatus: attempt.attemptStatus,
+    providerStatus,
+    correctionStatus: "observed",
+    checkedAt: now,
+    payload: {
+      source: "payment-provider-reconciliation.auto-reopen.v0",
+      provider: attempt.provider,
+      ...extra,
+    },
+  });
+}

package/src/payments/paymentProviderReconciliationEvidence.ts

@@ -0,0 +1,117 @@
+import type {
+  ClaimedPaymentAttempt,
+  ProviderReconciliationStatus,
+  ProviderReconciliationStatusKind,
+} from "./contracts/reconciliation.js";
+
+export function evidencePayload(
+  attempt: ClaimedPaymentAttempt,
+  providerStatus: ProviderReconciliationStatus,
+  extra: Record<string, unknown>,
+): Record<string, unknown> {
+  return {
+    source: "payment-provider-reconciliation.v0",
+    provider: attempt.provider,
+    providerPaymentId: attempt.providerPaymentId,
+    paymentIntentId: attempt.paymentIntentId,
+    paymentAttemptId: attempt.paymentAttemptId,
+    orderId: attempt.orderId,
+    subscriptionId: attempt.subscriptionId,
+    subscriptionCycleId: attempt.subscriptionCycleId,
+    localAttemptStatus: attempt.attemptStatus,
+    localIntentStatus: attempt.intentStatus,
+    providerStatus: providerStatus.providerStatus,
+    normalizedStatus: providerStatus.status,
+    failureReason: providerStatus.failureReason,
+    amountMinorPresent: providerStatus.amountMinor !== null,
+    currency: providerStatus.currency,
+    providerPayload: providerStatus.rawPayload,
+    ...extra,
+  };
+}
+
+export function terminalAmountMismatch(
+  attempt: ClaimedPaymentAttempt,
+  status: ProviderReconciliationStatus,
+): string | null {
+  if (status.amountMinor !== null && status.amountMinor !== attempt.amountMinor) {
+    return "provider_amount_mismatch";
+  }
+  if (status.currency && status.currency.toUpperCase() !== attempt.currency.toUpperCase()) {
+    return "provider_currency_mismatch";
+  }
+  return null;
+}
+
+export function applyResultKey(attempt: ClaimedPaymentAttempt, status: "succeeded" | "failed"): string {
+  return `payment-provider-reconciliation:${attempt.paymentAttemptId}:apply:${status}`;
+}
+
+export function observedEvidenceKey(
+  attempt: ClaimedPaymentAttempt,
+  status: ProviderReconciliationStatusKind,
+  correction: "observed" | "failed",
+  checkedAt: string,
+): string {
+  return `payment-provider-reconciliation:${attempt.paymentAttemptId}:${correction}:${status}:${bucket(checkedAt)}`;
+}
+
+export function preparedAttemptEvidenceKey(attempt: ClaimedPaymentAttempt, checkedAt: string): string {
+  return `payment-provider-reconciliation:${attempt.paymentAttemptId}:failed:prepared_without_provider_ack:${bucket(checkedAt)}`;
+}
+
+// Stable (no time bucket): a successful reopen cancels the attempt (it leaves
+// `created`), so the RPC is called at most once per attempt; replays after a
+// crash return the recorded response via commerce_idempotency_keys.
+export function absenceReopenKey(attempt: ClaimedPaymentAttempt): string {
+  return `payment-provider-reconciliation:${attempt.paymentAttemptId}:absence-reopen`;
+}
+
+export function absenceProbeEvidenceKey(attempt: ClaimedPaymentAttempt, checkedAt: string): string {
+  return `payment-provider-reconciliation:${attempt.paymentAttemptId}:absence-probe:${bucket(checkedAt)}`;
+}
+
+export function bucket(value: string): string {
+  const ms = Date.parse(value);
+  if (!Number.isFinite(ms)) return "unknown";
+  return String(Math.floor(ms / (30 * 60 * 1000)));
+}
+
+export function clamp(value: number, min: number, max: number): number {
+  if (!Number.isFinite(value)) return min;
+  return Math.max(min, Math.min(max, Math.trunc(value)));
+}
+
+export function safeMessage(error: unknown): string {
+  return (error instanceof Error ? error.message : String(error)).slice(0, 240);
+}
+
+/**
+ * The class the reading adapter already decided, read back off the normalized
+ * status so the terminal write can carry it.
+ *
+ * READ, never re-derived. Both shipped adapters classify what they read through
+ * the shared `classifyDecline` seam and put the verdict in `rawPayload`; deriving
+ * a second one here would be a second classifier, free to disagree with the one
+ * whose reasoning the evidence payload records. It is also why this function is
+ * provider-agnostic: it never learns which rail refused, only what that rail
+ * concluded.
+ *
+ * Returns a spreadable fragment rather than a nullable value, so an unclassified
+ * refusal leaves the key genuinely ABSENT from the composed call instead of
+ * present-and-null. Absence is what the port's contract defines as "behave
+ * exactly as before the field existed", and it is what the two non-classifying
+ * consumers of that contract are pinned to.
+ *
+ * A success carries no class by construction: there is no refusal to classify.
+ */
+export function classificationOf(
+  resultStatus: "succeeded" | "failed",
+  providerStatus: ProviderReconciliationStatus,
+): { failureClassification?: { failureClass: string; decidedBy: string } } {
+  if (resultStatus !== "failed") return {};
+  const { failureClass, failureClassDecidedBy } = providerStatus.rawPayload;
+  if (typeof failureClass !== "string" || failureClass.length === 0) return {};
+  if (typeof failureClassDecidedBy !== "string" || failureClassDecidedBy.length === 0) return {};
+  return { failureClassification: { failureClass, decidedBy: failureClassDecidedBy } };
+}